docs: split context into layered, agent-oriented files

Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.

Layers:
- architecture/  stable structural reference (overview, source-map,
                 test-map, data-flow)
- patterns/      memory, commands, autocomplete, events, xmpp,
                 encryption, ui, plugins
- testing/       unit-tests, stubs, functional-tests, bench
- build/         local, docker, ci
- playbooks/     add-command, add-test, add-autocomplete,
                 add-event-handler, add-encryption
- gotchas.md     append-only dated entries (seven seed entries)
- wip/           branch-specific notes; deleted on merge to master

Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.

INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.

README.md

@@ -1,2 +1,68 @@
 # cproof-context
 
+Agent-oriented context documentation for the [cproof](https://git.jabber.space/devs/cproof)
+project (a fork of Profanity, a terminal-based XMPP client written in C).
+
+This repository is **not** human-onboarding documentation. It is structured for
+consumption by AI/agent skills — tables over prose, concrete identifiers over
+descriptions, layered files loaded on demand.
+
+## Layout
+
+| Path | Churn | Purpose |
+|---|---|---|
+| `SKILL.md` | low | Always-loaded entry hint. Points to `INDEX.md`. |
+| `INDEX.md` | low | One-page map of every doc with churn label. |
+| `architecture/` | low | Stable structural reference: source map, test map, data flow. |
+| `patterns/` | medium | Codified conventions: memory, commands, autocomplete, events, etc. |
+| `testing/` | medium | How tests are organised, written, and stubbed. |
+| `build/` | medium | Local, Docker, and CI build flows. |
+| `playbooks/` | medium | Step-by-step recipes for common tasks. |
+| `gotchas.md` | append-only | Dated entries: one per known pitfall. |
+| `wip/` | high | Branch-specific notes for in-flight features. Deleted on merge. |
+
+See `INDEX.md` for the full file list.
+
+## Consumer
+
+Consumed by an agent skill that operates on the cproof codebase. The skill
+should pin this repo to a specific SHA (not a branch) and treat the loaded
+files as authoritative for their stated scope.
+
+## Update flow
+
+1. Edits land via PRs against `master`.
+2. Drift checks (path / identifier existence in cproof HEAD) run in CI before
+   merge — see `architecture/test-map.md` and `build/ci.md` for details once
+   wired up.
+3. After major cproof refactors, the skill consumer bumps the pinned SHA to a
+   commit known to pass drift checks.
+
+## Out of scope
+
+- User-specific agent preferences (language, commit-trailer policy, etc.) —
+  belong in agent memory, not here.
+- Git history snapshots, changelogs, PR summaries — derivable from `git log` /
+  `gh pr`.
+- Aspirational guidance — this repo describes cproof as it is, not as it
+  should be.
+
+## Baseline and WIP
+
+The stable layers (`architecture/`, `patterns/`, `testing/`, `build/`,
+`playbooks/`, `gotchas.md`) describe **cproof on `master`**. They do not
+mention symbols, files, or commits that exist only on a feature branch.
+
+In-flight feature branches that materially change the surface (new module,
+new commands, new stubs) get a single file under `wip/<branch-slug>.md`. On
+merge to `master`, that file is deleted and any surviving content is folded
+into the stable layers.
+
+Current WIP: `wip/feat-ai.md` (cproof branch `feat/ai`).
+
+## Status
+
+Layout is being authored on `draft/split-context`. The single
+`file-structure.md` (still present on `feat/add-context`) is being decomposed
+into the structure above; once the split is complete, `file-structure.md` is
+deleted.