Maintaining the repo map

Goal: keep `README.md` (L0), `index.md` (L1), domain L2 files, and `conflicts.md` (L3) accurate without large rewrites.

After you change behavior in code

1. Default: Update only the domain L2 file that owns that behavior (e.g. server capture pipeline → ingestion.md; browser queue / /capture submit UX → capture-queue.md).
2. If you add or rename a domain (rare): Update index.md and add/remove an L2 file.
3. If project scope or top-level flows change: Update the short “Repo map” paragraph in README.md.
4. If you introduce or fix overlap between systems: Add or resolve a row in conflicts.md and adjust the CompetingSystems section in the affected domain file(s).
5. If this protocol or answer rules change: Edit maintenance.md or answer-protocol.md accordingly.

Same session when possible

Apply map updates in the same chat or editing session as the code change so the repo never sits in a long-lived “doc drift” state.

What not to do

• Do not duplicate long explanations across L2 files; link to the canonical file in code instead.
• Do not resolve conflicts.md rows without a one-line note of what was decided.

OKF (Open Knowledge Format)

Decision (June 2026): eigenWebsite does not adopt OKF v0.1 as a project initiative. The site already has build-time markdown, curated nav (`developer-nav.ts`), link validation, and `llms.txt`. OKF adds a type frontmatter label and a spec name — not a capability we lack on this repo.

Scope if revisited: Only `docs/repo-map/` would be the OKF-shaped folder (agent wiki with cross-links and a conflict ledger). Public operator docs under docs/getting-started/, docs/concepts/, etc. stay on the existing description / audience frontmatter and TypeScript nav. Internal docs/planning/ and docs/marketing/ are out of scope.

When to revisit: Check the knowledge-catalog OKF spec for breaking changes before changing repo-map conventions or if an external OKF consumer (e.g. Google's HTML visualizer) becomes useful. Memory export/import OKF belongs in the eigen product repo, not eigenWebsite.

Optional experiment (no site code changes): Add type frontmatter to index.md and one L2 file, then open docs/repo-map/ in the OKF visualizer to compare against reading markdown directly.