knowledge-base

Knowledge Base (Markdown, agent-readable)

A knowledge base (KB) here is a folder of Markdown files designed so any AI agent can navigate it without a vector database: the agent reads one index file, picks the relevant notes by their descriptions, and opens only those. Keep the whole KB readable and the index lean — the index is what gets loaded into context, so it must be high-signal.

Apply the rules below when creating a new KB, adding/editing notes, or doing a maintenance pass. When the user's request is ambiguous (new KB vs. add note vs. cleanup), ask which one before acting.

Core principles (the "why")

1. Index-first navigation. The index is a map, not a container. An agent reads INDEX.md, selects notes by their one-line descriptions, then opens only those files. No note is "in" the KB unless it's registered in the index.
2. Atomicity. One topic per note. If a title needs an "and", it's probably two notes. Atomic notes are easier to find, link, and reuse.
3. Stable IDs. Every note has a permanent ID that never changes and is never reused, so links survive renames and moves.
4. Linked with reason. When two notes connect, state why (prerequisite, supports, contrasts, see-also). Connections carry as much value as the notes.
5. Lean instructions. Keep INDEX.md instructions short and high-signal — it competes for the agent's context budget. Bodies load on demand.
6. Structured for retrieval. Clear H1 title and H2/H3 sections so an agent can grab the relevant slice of a note, not the whole thing.

Folder structure (nested by topic)

knowledge-base/
  INDEX.md                 # entry point: instructions + full note registry
  topics/
    <topic>/
      _topic.md            # topic map: what this topic covers + its notes
      <slug>.md            # one atomic note
  assets/                  # images / attachments referenced by notes

• Topic folders are short, lowercase nouns (auth, billing, deploys).
• _topic.md is the topic-level map of content (MOC): a short intro plus links to every note in that topic. It is a convenience view; INDEX.md remains the source of truth.