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.

Naming rules

• Lowercase kebab-case, predictable and greppable: topics/auth/session-tokens.md.
• No spaces, no uppercase, no dates in filenames (dates live in frontmatter).
• The filename slug should match the note's id slug portion.

Required frontmatter (every note)

---
id: 20260618-session-tokens     # ID scheme: YYYYMMDD-slug. Stable. Never reuse or change.
title: Session tokens           # human title, also the note's H1
tags: [auth, security]          # only tags from the controlled list in INDEX.md
created: 2026-06-18
updated: 2026-06-18
related: [20260618-auth-flow]    # IDs of linked notes
summary: One scannable sentence describing what this note covers.
---

• id: YYYYMMDD-slug. Sortable, readable, stable. Different-titled same-day notes differ by slug; if two same-day notes would collide on the same slug, append -2, -3, … (check the INDEX.md registry before assigning). Once assigned, the id is permanent.
• summary: this exact sentence is what goes in the index registry — write it to help an agent decide whether to open the note.
• updated: bump it whenever the body changes.

Note body shape

# Session tokens

> Summary: One sentence (mirrors frontmatter summary).

## Context
Why this note exists / when it applies.

## Details
The actual content, in short H2/H3 sections.

## Related
- [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow.
- [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key.

• Use relative links between notes and annotate the relationship in a phrase.
• Every link target should also appear in the note's related frontmatter.

INDEX.md (the single source of truth)

INDEX.md has two parts: operating instructions for agents, and the registry.

# Knowledge Base — Index

## How to use this KB (for agents)
1. Read this index first. Pick notes by their descriptions; open only those.
2. To answer a question, prefer opening 1–3 specific notes over scanning everything.
3. Cite the note `id` when you use information from it.

## How to update this KB (for agents)
- New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`.
- Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change.
- Use only tags from the controlled vocabulary below; add a new tag here before using it.

## Controlled tags
`auth`, `security`, `billing`, `api`, `ops`   <!-- extend deliberately -->

## Registry
### auth
- `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end.
- `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation.

### billing
- `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent.

Registry line format: `id` — **Title** — `path` — one-line description.

_topic.md (topic map)

# Auth

Notes covering authentication, sessions, and access control.

- [Authentication flow](auth-flow.md) — how a session is established.
- [Session tokens](session-tokens.md) — token format, lifetime, rotation.

Workflows

Create a new KB

1. create_directory for the folder structure above.
2. write_file INDEX.md with the instructions block, an empty controlled-tag list, and an empty registry.
3. Add the first topic folder + _topic.md, then the first note (each via write_file).
4. Register the note in INDEX.md and link it from _topic.md — edit_block both so you touch only the changed lines.

Add a note

1. Pick or create the topic folder (list_directory to see what's there).
2. write_file the note (kebab-case slug) with full frontmatter and the body shape.
3. Add cross-links (and mirror them in related).
4. Register it in INDEX.md and link it in _topic.md with edit_block — same change.

Update a note

• Same idea, new information → edit_block the note in place, bump updated, and edit_block the registry line if the scope changed.
• Genuinely new idea → write_file a new atomic note instead of expanding this one.

Maintenance pass (run on demand)

Use start_search (ripgrep) for text scans and get_file_info / list_directory for existence checks — together they make this tractable at scale:

• Orphans (no inbound links — outbound doesn't matter): start_search the KB for the note's id and filename slug, then discount the self-matches that always exist — the note's own file, INDEX.md, and its _topic.md. Anything left is a genuine inbound reference; nothing left = orphan, so link it from a relevant note/MOC or archive it.
• Broken links / drift: don't infer resolution from a text hit — a string existing doesn't mean the file does. Confirm each registry path and related: target exists with get_file_info (or list_directory per topic), and that every file on disk is registered. Use a text compare only for the titles/summaries-out-of-sync half.
• Non-atomic notes: notes that grew to cover multiple topics → split them.
• Duplicates: near-identical notes → merge, keep one id, redirect links.
• Tag sprawl: read the controlled list from INDEX.md, then start_search the frontmatter tags: lines and flag any tag not on the list → reconcile. Pull candidates in bulk with read_multiple_files, apply fixes with edit_block, and report what changed.

Checklist before finishing any KB edit

• Every new/changed note has complete, valid frontmatter.
• id is unique and unchanged; filename slug matches the id slug.
• All links resolve and are mirrored in related.
• INDEX.md registry and the topic _topic.md reflect the change.
• Tags are from the controlled vocabulary.
• updated bumped on every changed note.