Current entry point for contributors and coding agents. This map separates the chat surface from the resident surface and points to implementation owners. Read contributing and recent change entries before relying on an older design. This page describes code organization, not user-facing promises; those belong in the shipped manual.
| Surface | Entry and implementation | Product knowledge |
|---|---|---|
| Interactive chat | chat launcher, terminal UI, session engine | Chat manual |
| Scripted work | commands, headless contract | Running from the terminal |
| Resident | head, resident | Resident manual |
Chat and resident share parts of the repository, but their lifecycles and manual corpora differ. Do not use the historical resident architecture as a description of the chat's storage or execution model.
The launcher wires configuration, the workspace and the session to the terminal surface. The surface presents state and user actions; the session owns the turn loop, tools and task coordination. Start with these files, then follow the specific action rather than reading either large package from beginning to end.
| Responsibility | Start here | Related reference |
|---|---|---|
| Launch, resume and configuration | chatv3.go, config | Starting codeaf |
| Screen, navigation and interaction | tui3/app.go, shared tui2 components | Design language |
| Turns, tools and task execution | session/session.go, session/task_run.go, exec | Subharness contract |
| Provider calls and model configuration | provider, config | Usage accounting, limits |
| Remote sessions and movable chats | remote, enginehost, cell | Remote architecture, remote testing |
| Relay coordination across computers and workers | relay server, committed directory, consensus core, hosted relay, cluster command | Run a relay, coordination and workers |
Before delegating across folders, cooperating on private copies, receiving a chat, applying results or cleaning task storage, read the task workspace and relay agent contract.
There is no single Markdown file that acts as every kind of memory. Keep these concepts separate when implementing a feature or writing an agent's brief.
| Kind of knowledge | Owner | How it is maintained |
|---|---|---|
| What codeaf knows about its product | manual | Maintained Markdown embedded in the binary, with separate chat and resident corpora |
| Profile knowledge learned from saved chats | knowledge, session integration | Native SQLite vault, background compiler, and human edits; see knowledge architecture and Memory behavior |
| Graph and memory storage mechanisms | store | Read the relevant caller and tests before changing schema or replay behavior |
| What contributors know about this codebase | This page and engineering references | Reviewed documentation committed beside the code |
Repository documentation is not automatically part of the shipped manual, and a user's project knowledge vault is not the repository's developer documentation. A project-knowledge feature needs both developer guidance here when structure changes and product guidance in the manual when behavior changes.
The knowledge vault owns source admission, background compilation, publication, search, and human overrides. The session history reader decides which saved records can enter the vault. Memory renders published pages and does not run compilation on the UI loop. Agent recall reads the same effective publication.
Start with the knowledge architecture for entry points and module contracts. Preserve immutable sources, stable page identities, cancellation, revision-checked edits, and deletion intent when changing this path. Keep provider requests outside database write transactions and publish pages and search entries as one revision.
Current interface references include headless behavior, remote protocol, subharness execution, pairing, spend limits, and usage accounting. Check their stated scope before applying them to another surface.
Design rationale explains why a mechanism was chosen. Start with the relevant page in the documentation map; a design proposal is not evidence that the behavior shipped. Superseded material belongs in history, linked from its replacement.
Use tests at the observable interface affected by the change. Update the matching manual and reference in the same PR when commands, defaults, tools, limits or refusals change. Follow CI guidance for focused validation and PERF.md for measured performance changes. Keep general repository instructions in AGENTS.md, not in the product manual.