A visual field guide

Same files.
Different systems.

Markdown is the substrate. The use case decides the structure, retrieval, tools, and workflow.

20 transformations7 design forces1 fitted generator

README.md PDFs src/
notes-final-2.md tickets
logs plans tools chat

↓

inspect · fit · own · prove

↓

The design mixer

The folders are an output, not a starting point.

Payloadcode · claims · people · cases · experiments

Volatilitystable · decaying · event-sourced · contested

Authoritycode · spec · evidence · human ruling

Scale30 · 300 · 30,000 pages

Riskcasual · operational · regulated

Readersself · team · unknown public

Toolsfiles · code · PDF · mail · logs · agents

7 forces×real questions→fitted wiki

The universal separation

Different lifetimes need different homes.

Evidenceraw, immutable, attributable

Durable knowledgeconcepts, decisions, architecture

Active workplans, tasks, proposals, retry state

Agent interfacepurpose, schema, small router

Operationsingest, query, lint, refresh, close

→

One state → one ownerNo rival current specs, plans, or memories.

Tool output ≠ durable truthPromote accepted conclusions at close.

Files prove recoveryA fresh agent resumes without old chat.

Code & delivery / I

When executable systems are the authority.

Undocumented monolith

src/
README
tribal lore
stale diagrams

→

architecture/
components/
decisions/
procedures/

FLOW
imports → tests → anchored claim → affected-page refresh

rggitAST/LSPtests

WHY Code owns behavior; wiki owns intent + boundaries. GAIN safer onboarding.

Large monorepo

80 packages
nested READMEs
CODEOWNERS
one giant doc

→

domains/
services/
contracts/
owners/ + maps/

FLOW
changed paths → dependency slice → owner review → local refresh

build graphgit diffCI

WHY Scale selects hierarchy. GAIN bounded context + visible blast radius.

Brownfield product

docs/
tickets
3 planning tools
lost decisions

→

wiki/ durable
changes/ active
specs/ current
agent-stack.md

FLOW
propose → review → build → verify → archive → promote

OpenSpec*gittests

WHY Plans expire; accepted intent survives. GAIN one current truth.

* Or one alternative state owner—never one planner per category.

Code & delivery / II

When the system must keep proving itself.

Public API / SDK

OpenAPI
comments
copied snippets
drifting guides

→

contracts/
journeys/
errors/
executable examples/

FLOW
spec diff → regenerate facts → run examples → publish

OpenAPISDK matrixlink check

WHY Contracts own facts; Markdown explains. GAIN examples can fail CI.

Data / ML platform

SQL
notebooks
model cards
dashboards

→

datasets/
pipelines/
features/
models/ + evals/

FLOW
probe → snapshot → compare contract → attest / block

SQL ROschema catalogeval CLI

WHY Observed state decays. GAIN lineage + reproducible impact.

SRE estate

runbooks
alerts
dashboards
chat postmortems

→

systems/
runbooks/
incidents/
signals/ + probes/

FLOW
alert → response → incident → patch runbook → expiry sweep

logs/metrics ROstatus APIscheduler

WHY Freshness outranks elegance. GAIN fewer unsafe stale commands.

Evidence & inquiry

When disagreement and provenance are the payload.

Research library

PDFs · BibTeX
highlights
paper folders

→

sources/ · authors/
claims/ · debates/
syntheses/

FLOW freeze → extract → claim graph → preserve contradiction → synthesize

PDF/OCRcitation resolversearch

WHY Competing authors stay visible. GAIN synthesis without false consensus.

Laboratory notebook

instrument files
protocols
photos
spreadsheets

→

raw/runs/
experiments/
observations/
findings/

FLOW hash raw → record conditions → analyze → review → replicate

checksumnotebookmetadata

WHY Observation precedes interpretation. GAIN clean re-analysis.

Legal / compliance

regulations
contracts
policies
audit sheets

→

obligations/
controls/
evidence/
exceptions/

FLOW authority → candidate duty → counsel review → control → evidence expiry

OCRclause searchcalendar

WHY Authority is external; interpretation is reviewed. GAIN audit-ready clocks.

Due diligence room

data room
decks
financials
interviews

→

claims/
evidence/
risks/
questions/

FLOW inventory → claim/evidence map → contradiction → open request → ruling

doc parsersheetsredaction

WHY Missing evidence is first-class state. GAIN visible uncertainty.

People & operations / I

When events become confirmed state.

Personal second brain

daily notes
bookmarks
mail · calendar
tasks

→

inbox/
people/ · projects/
areas/ · decisions/
history/

FLOW
capture → nightly triage → rewrite current → append history → weekly review

filesmail/calendar*clipper

WHY One life, not competing authors. GAIN clean present + retained history.

Customer intelligence

CRM
calls
emails
tickets

→

accounts/
people/ · needs/
commitments/
decisions/

FLOW
import event → extract candidate → owner confirms → age stale claim

CRM/exporttranscriptsidentity

WHY Events are evidence; commitments need confirmation. GAIN fewer invented promises.

Support + feedback

tickets
reviews
issues
analytics

→

symptoms/
themes/
causes/
fixes/

FLOW
dedupe → candidate cluster → reproduce → verified cause → retire / reopen

ticket APIclusteringrepro tests

WHY A cluster is not a cause. GAIN measurable closure.

* Connector when available; Markdown export when it is not.

People & operations / II

When access and learning shape the graph.

Field program

mobile forms
site reports
photos
partner sheets

→

sites/ · partners/
interventions/
outcomes/ · methods/

FLOW local capture → redact → sync ledger → conflict queue → aggregate

offline exportEXIF scrubsync ledger

WHY Access constraints select files + queues. GAIN consent-aware recovery.

Course / curriculum

slides
readings
assignments
rubrics

→

outcomes/
concepts/
prerequisites/
misconceptions/

FLOW map → detect gap → teach → sample errors → revise activity

doc ingestrubric checkLMS export

WHY Organize by mastery, not source chapters. GAIN missing prerequisites become visible.

Creative, cultural & public

When identity, canon, or portability dominates.

Fiction / game lore

scripts
quest files
art notes
contradictory drafts

→

characters/
places/ · events/
timelines/
canon/

FLOW
draft → continuity conflict → canon level → creative ruling → propagate

script parsertimeline lintapproval

WHY Contradiction may be intentional. GAIN safe branches + retcons.

Museum / archive

catalogs
scans
donor records
name variants

→

objects/
people/ · places/
provenance/
treatments/

FLOW
import → identity candidate → curator confirms → aliases → provenance

OCRauthority lookupentity match

WHY Names are claims, not IDs. GAIN non-destructive reconciliation.

Open community knowledge

many repos
many schemas
unknown consumers

→

index.md
documents/*
sources/*
attributed signals/*

FLOW
validate envelope → augment → attach signals → publish portable bundle

validatorlink checkgit

WHY Unknown readers need open types. GAIN lower interchange cost.

Agent-native systems

When tools and agents are part of the knowledge design.

Multi-agent delivery factory

chat plans
ad hoc agents
duplicate work
no resume

→

intent.md
contracts/
board + leases
handoffs/ + gates

FLOW decompose → lease → parallel work → deterministic gate → merge → promote

orchestratorworktreesCIledger

WHY Concurrency needs typed boundaries. GAIN fresh-session recovery.

Tool / workflow catalog

READMEs
feature lists
“best tools”
unknown lock-in

→

tools/ · mechanisms/
comparisons/
recipes/
adoption decisions/

FLOW pin → inspect docs/templates/callers → profile ownership → compare → recovery test

repo readCLI helpcode searchversion pin

WHY Choose capability before product. GAIN compatible stacks, no rival planners.

Retrieval changes with scale

Climb one rung only when needed.

≈30 pagesIndex

One curated map. Exact navigation. Zero infrastructure.

≈300Index + grep

Human clusters first; exact search catches the long tail.

≈3,000Search shortlist

Lexical or semantic candidates; pages remain canonical.

≈30,000Graph slices

Typed edges, bounded neighborhoods, incremental indexes.

Search is a route to files—never the only copy of knowledge.

Tool-aware ownership

Five state classes. Five clear contracts.

◆Wiki

Purpose, architecture, accepted decisions, durable constraints.

CANONICAL AFTER CLOSE

△Workflow

Active proposal, plan, task graph, checks, handoff.

CANONICAL WHILE ACTIVE

〈/〉Code + tests

Executable behavior and machine-enforced contracts.

EXECUTABLE TRUTH

∿Memory

Embeddings, recall cache, cross-session convenience.

DERIVED + REBUILDABLE

↗Agent router

Non-derivable policy and triggers pointing to the owners.

SMALL; NEVER A COPY

The generator

Inspect first. Generate last.

01Inventory

tree · files · Git · tools · routines

02Fit

payload · exclusions · readers · scale

03Own

one state owner + close-out map

04Retrieve

design from recurring questions

05Operate

ingest · query · lint · domain loops

06Guard

gates · budgets · queue · ledger

07Prove

fresh-session recovery + findings

Acceptance test

A fresh agent finds the purpose · canonical truth · active work · last verified result · blockers · next action using only the root directory.

What the fitted structure buys

Less context. More continuity. Visible truth.

↓ contextLoad a routed slice, not the whole corpus.

↑ trustTrace claims to code, evidence, or rulings.

→ recoveryResume from disk instead of reconstructing chat.

⊘ driftExpiry and probes surface decayed knowledge.

≠ conflictOne state owner prevents rival “current” files.

↻ learningSchema findings let the first draft improve.

Send feedback ↗Back to start ↑

Same files.Different systems.