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.

architecture/data-flow.md

@@ -0,0 +1,76 @@
+# Data flow
+
+High-level paths through the codebase. Use this when reasoning about where a
+change should land or where a bug originates.
+
+## User input → action
+
+```
+keypress
+  → src/ui/inputwin.c           (line editor, key dispatch)
+  → src/command/cmd_ac.c        (autocomplete on Tab)
+  → src/command/cmd_defs.c      (parse / lookup)
+  → src/command/cmd_funcs.c     (handler: cmd_<name>)
+  → side effects: src/xmpp/, src/config/, src/ui/, src/event/
+```
+
+- Tab triggers autocomplete via `cmd_ac.c` lookup in `ac_funcs` hash table
+  (key: `/cmd`, value: per-command `_<cmd>_autocomplete` function).
+- Enter parses input via `parse_args()` (`src/tools/parser.c`), looks up the
+  `Command*` via `cmd_get()` (`src/command/cmd_defs.c`), invokes the handler
+  declared with `CMD_MAINFUNC` or one of the `CMD_SUBFUNCS`.
+
+## Outgoing chat message
+
+```
+cmd_msg / typing-into-chatwin
+  → src/xmpp/message.c          (build message stanza)
+  → src/xmpp/stanza.c           (assemble XML)
+  → libstrophe                   (send)
+  → src/chatlog.c               (persist locally)
+  → src/ui/chatwin.c            (echo into window)
+```
+
+Encryption injects between message build and send:
+
+- OMEMO via `src/xmpp/omemo.c` → `src/omemo/omemo.c` (libsignal-protocol).
+- OTR via `src/otr/otr.c` (libotr).
+- PGP / OX via `src/pgp/gpg.c` / `src/pgp/ox.c` → `src/xmpp/ox.c`.
+
+## Incoming stanza
+
+```
+libstrophe callback
+  → src/xmpp/{message,presence,iq,muc,roster}.c   (parse, validate)
+  → src/event/server_events.c                      (sv_ev_*)
+  → src/ui/{chatwin,mucwin,console,...}.c          (render)
+  → src/chatlog.c                                  (persist)
+```
+
+`server_events.c` is the chokepoint — every inbound XMPP event flows through a
+`sv_ev_*` function. UI updates and persistence fan out from there.
+
+## Client-initiated events
+
+`src/event/client_events.c` mirrors `server_events.c` for events that
+originate locally (UI actions, command-driven state changes) but need the
+same downstream fan-out.
+
+## Connection state
+
+- `src/xmpp/connection.c` owns the `jabber_conn_status_t` (declared in
+  `connection.h`).
+- `connection_get_status()` returns the current state. Many code paths gate
+  on `JABBER_CONNECTED` — see `patterns/xmpp.md`.
+- Tests must `will_return(connection_get_status, JABBER_CONNECTED)` (or the
+  desired state) before exercising any code path that consults it. See
+  `gotchas.md`.
+
+## Plugin hook points
+
+Plugin callbacks (`src/plugins/callbacks.c`) sit on:
+- Pre/post message send and receive (around `src/xmpp/message.c` flow).
+- Connection lifecycle (around `src/xmpp/session.c`).
+- Window-switch events (around `src/ui/window_list.c`).
+
+See `patterns/plugins.md`.