docs/book/src/contributing/architecture-map.md
Use this page when a change is larger than a typo and you are not sure which architecture, foundation, contributor, or maintainer documents apply.
This page is only a map. The linked files remain the source of truth.
AGENTS.md first. It contains the current risk tiers, protected files, anti-patterns, localization rules, and agent-specific workflow contracts.| Change | Read first | Why |
|---|---|---|
| New provider | Architecture overview, Crates, Custom providers, Provider configuration | Providers are edge adapters behind the provider trait, with config, factory, attribution, and routing contracts. |
| New channel | Architecture overview, Crates, Channel runtime lifecycle, Channels overview, existing implementations in crates/zeroclaw-channels/ | Channels are user-visible trust boundaries; validate inbound, outbound, pairing, authorization, dispatch, and reply lifecycle behavior. |
| Channel dispatch, webhook ingress, reply intent, streaming drafts, listener lifecycle, or channel reload behavior | Channel runtime lifecycle, Request lifecycle, Gateway HTTP API, Plugin protocol, Testing | Channel lifecycle changes need a single dispatch and turn path instead of one-off adapter or gateway mini-orchestrators. |
| New built-in tool or tool policy | Tools overview, Built-In Tool Inventory, Tool execution lifecycle, ADR-004: Tool shared state ownership, Plugin protocol, Security overview, Tool receipts | Tools execute actions for the agent. First check whether the capability belongs in core, then validate registration, approval, dispatch, audit, receipts, localization, attribution, and shared-state ownership. |
| Runtime, agent loop, cron, SOP, state, provider token streaming, or tool-loop behavior | Request lifecycle, Runtime state and persistence, Tool execution lifecycle, Crates, FND-001, Testing | Runtime changes often affect multiple user paths and need boundary-level tests. Provider token streaming stays runtime-owned; channel draft or typing-indicator streaming follows the channel lifecycle row. Tool-loop changes should name whether they affect approval, dispatch, receipts, observer events, history, or cancellation. |
| Memory, session history, prompt context, tool results, files/media payloads, or context trimming | Memory and payload lifecycle, Runtime state and persistence, History management, Runtime internals, Testing | Payload changes need clear owner, scope, durability, privacy, and truncation boundaries. |
| Gateway, web API, or dashboard behavior | Gateway HTTP API, Building the web dashboard, Request lifecycle, Security overview, Reviewer playbook | Gateway changes can affect auth, public exposure, generated API contracts, dashboard consumers, and review risk. Use the channel lifecycle row for webhook dispatch or reply behavior. |
| Config schema, environment variables, defaults, or reload behavior | Config lifecycle, Environment variables, Runtime state and persistence, Provider configuration, FND-001, RFC process | Config changes affect upgrade paths, reload behavior, source-of-truth boundaries, and may require migration or RFC discussion. |
| CI, release, GitHub Actions, or allowed actions | CI & Actions, FND-004, PR workflow | Infrastructure changes are high-risk when they alter what code can run or ship. |
| Docs structure, contributor guidance, or knowledge organization | FND-002, Docs & Translations, this page | Documentation changes should reduce search cost and preserve the decision trail. |
| Governance, labels, board workflow, or contribution process | FND-003, RFC process, Labels, Reviewer playbook | Process changes affect maintainers and contributors; keep them durable and explicit. |
| AI-assisted contribution, superseding, or review culture | FND-005, Superseding PRs, PR review protocol | AI-assisted work is welcome, but the human sponsor owns accuracy, attribution, and review response. |
| Production code health, error handling, or dead-code cleanup | FND-006, Testing, repo-root AGENTS.md | Error discipline, unused code, and production readiness are review gates, not style preferences. |
| Foundation | Read when the change asks... |
|---|---|
| FND-001: Intentional architecture | Does this fit the microkernel/runtime direction? Which layer should own it? |
| FND-002: Documentation standards | Where should knowledge live? How should docs stay navigable and durable? |
| FND-003: Governance | Who decides? Which labels, project board, or RFC process should carry the state? |
| FND-004: Engineering infrastructure | How should CI, release automation, or GitHub Actions behave? |
| FND-005: Contribution culture | How should contributors, maintainers, and AI-assisted work communicate and review? |
| FND-006: Zero compromise in practice | What quality bar applies to production code, errors, dead code, and release readiness? |
Coding agents should use the same public docs as humans, plus the repository-local agent contracts.
AGENTS.md and the matching in-repo skill listed there when one applies.AGENTS.md, or a ratified foundation document, stop and reconcile before posting or implementing.This map does not replace the RFC process or the PR template; it only helps you find the right doc. The RFC process carries the canonical "is this RFC-shaped?" table, so check it rather than guessing from a restated list here. After RFC #6808 policy slices are promoted, follow FND-003, Labels, PR workflow, and Reviewer playbook.
.github/pull_request_template.md). If those answers are not clear, write the design note or RFC first.