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 |
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 |
| Project knowledge learned from chats | knowledge, session integration | Project/profile vault with source records and human-edited articles; see 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.
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.