Context and docs architecture

ops parked

repo: n/a — this workspace (docs/, CLAUDE.md), with the actual design-corpus split happening in land-of-lor/docs/ · updated 2026-08-05

What this is

A proposal — not yet implemented — for stopping agent cold-start context cost from growing as this project’s documentation grows. The full analysis, measured against the repo’s actual current content, lives in docs/context-architecture.md. This file stays short on purpose, per the proposal’s own point 4 (“one fact, one home”) — read the doc, don’t expect this overview to duplicate it.

Why it exists

Kris has said plainly he doesn’t want startup context to grow as the project grows. Nothing today enforces that; it’s a preference, not a property of the repo. Left unaddressed, every new epic, every new design doc, every new deliverable makes every future agent’s cold start slightly more expensive, forever.

Scope

Per docs/context-architecture.md: a tiered reading model (with line caps grounded in today’s actual file sizes), CLAUDE.md as a router rather than a library, doc frontmatter + a generated docs/index.json, a one-fact-one-home rule, durable-vs-ephemeral status files, numbered decision records, build-time enforcement (not GitHub-Actions-dependent, given the known token-scope limitation — see public-site-and-comms), a cold-start cost measurement for workspace-dashboard to display, and a concrete split plan for land-of-lor/docs/’s design corpus.

Non-goals

Not implementing any of this in this pass. No files get restructured, no CI check gets written, no decisions/ folder gets created yet — this epic is the spec only.
Not a land-of-lor design epic — the proposed docs split happens there, but authoring the actual primer/topic-file content is out of this epic’s scope; this epic only proposes the shape.

Relationship to `workspace-dashboard`

Related, not the same epic — kept separate deliberately. workspace-dashboard is about routing a human’s attention across many agents; this epic is about controlling agent context cost. They touch at exactly two points, both noted in the proposal doc: this epic’s cold-start cost measurement (point 8) is a number workspace-dashboard would want to display, and its blocker/question log design should reuse this epic’s durable-vs-ephemeral log/ pattern rather than inventing a second one. Neither needs the other to exist first.

Key open questions

See docs/context-architecture.md’s closing section — the structured decision-record template, and whether enforcement blocks commits, builds, or both, are both explicitly left open.

Relevant docs

docs/context-architecture.md — the full proposal; read this, not a summary of it.
land-of-lor/CLAUDE.md — the single file most affected if point 2 (router, not library) is adopted.
epics/public-site-and-comms/ — source of the GitHub Actions token-scope limitation this proposal’s CI recommendation works around.

Status

no tasks yet

Next: Parked — this is a proposal awaiting Kris's review, not active work.

Tasks (0)

No tasks yet — this epic hasn't been decomposed, or is question-only by nature.

Ask an agent about this epic

Also available as raw markdown.