The upstream repo ships an unusually complete documentation tree under docs/. This appendix maps every top-level Markdown file and subdirectory — what it covers and who should read it — so you can navigate from this site back to the authoritative source.

The i18n convention

Every in-scope document is maintained in English and Simplified Chinese as a pair plus a translation index (the one exception is docs/cordis-api/inherited.md, which is English-only):

• <name>.md — English source.
• <name>.zh.md — Chinese translation, a faithful non-literal rendering.
• <name>.i18n.yaml — the i18n pairing/paths declaration.

The contract, checks, scope, and exclusions live in docs/i18n/README.md; how to translate is in docs/i18n/translation-rules.md; the terminology source of truth is docs/i18n/terminology.md. docs/AGENTS.md is the documentation writing standard that governs this whole tree.

Top-level overview and architecture

Repo path	What it covers	Worth reading for
docs/architecture.md	Read-before-hacking overview: Cordis, profiles/bundles/patches, core packages, events, turn flow, session log, seams	Architecture overview, capability seams
docs/glossary.md	Canonical one-term-per-concept domain vocabulary	Glossary appendix
docs/cordis-primer.md	The Cordis ideas a plugin author needs before the generated references	Cordis primer
docs/rescope.md	Name mapping for the vendored @deepseek-ai/cordis* scope	Package index

Development

Repo path	What it covers	Worth reading for
docs/development.md	Contributor setup tutorial plus repo layout, daily workflow, CI organization	Development
docs/AGENTS.md	The documentation writing standard: structure, Markdown tiers, budgets	Page conventions (see docs/AGENTS.md)
docs/testing.md	Testing policy tier by tier and the rules that keep the suite meaningful	Testing
docs/defensive-patterns.md	Bug-class rules (events, concurrency, lifecycle, subprocess, teardown) that actually shipped	Development
docs/event-producer-consumer.md	Generated matrix of every event's producers and consumers	Events
docs/module-graph.md	Generated package-level module dependency graph	Package index
docs/graph-atlas.md	Generated index of all documentation graphs	Architecture overview
docs/web-styling.md	Styling ownership and component rules for browser client packages	Web UI

Catalogs (generated reference)

Repo path	What it covers	Worth reading for
docs/tool-catalog.md	Generated schema catalog of every model-facing tool	Tool registry
docs/config-catalog.md	Generated plugin config catalog	Configuration
docs/persistence-catalog.md	Generated session persistence event catalog	Session
docs/api-gateway.md	Current-state reference for the Typert API Gateway (Remote methods, Host/Client contracts)	Host API
docs/capability-seams.md	Generated page of every capability seam and core service	Capability seams
docs/tool-execution-pipeline.md	Generated page of the tool execution pipeline	Tools
docs/agent-lifecycle.md	Generated agent turn-and-step lifecycle diagram	Agent loop

Subsystem references (docs/subsystems/)

45 subsystem pages — core, session, tools, shell, fs, subprocess, sandbox, llm-streaming, session-projection, session-query, session-telemetry, session-title, settings, credentials, persistence, approval, permission-presets, user-questions, commands, plan, goal, schedule, jobs, workflow, subagent, skills, system-prompt, compaction, spill, storage, lsp, web, web-server, terminal, feedback, extensions, client-modules, typert, invariants, scope and more. Each is a plugin-territory reference (service, events, config, providers) for one package group.

Repo path	What it covers	Worth reading for
docs/subsystems/README.md	Index of all subsystem references	Subsystem index (see docs/subsystems/README.md)
docs/subsystems/core.md	Agent, agent-loop, system-prompt register	Agent loop
docs/subsystems/session.md	The event-sourced session store	Session
docs/subsystems/scope.md	The scoped-registration primitive	Scope
docs/subsystems/goal.md	Same-session goals and goal rounds	Goals
docs/subsystems/...	One reference page per package group (see README index)	Per subsystem

Cordis API and tutorial (docs/cordis-api/, docs/cordis-tutorial/)

Generated catalog of the vendored Cordis framework surface (context, events, fiber, registry, service, plus inherited.md), and a hands-on 7-lesson tutorial (first plugin → lifecycle/effects → services → events → config → composition/HMR → into the harness).

Repo path	What it covers	Worth reading for
docs/cordis-primer.md	Concept primer before the generated references	Cordis primer
docs/cordis-api/context.md	Cordis Context API	Cordis
docs/cordis-api/events.md	Cordis typed event API	Events
docs/cordis-api/service.md	Cordis Service API	Cordis
docs/cordis-api/fiber.md	Cordis fiber model	Cordis
docs/cordis-api/registry.md	Cordis registry API	Cordis
docs/cordis-api/inherited.md	Inherited generated API surface	Cordis
docs/cordis-tutorial/index.md	Hands-on introduction in seven lessons	Cordis tutorial

Cookbook (docs/cookbook/)

Repo path	What it covers	Worth reading for
docs/cookbook/adding-a-package.md	How to add a workspace package	Extension cookbook (see docs/cookbook/extension-cookbook.md)
docs/cookbook/adding-a-tool.md	Tool authoring reference	Tools
docs/cookbook/adding-an-llm-adapter.md	How to add an LLM adapter	LLM
docs/cookbook/adding-a-vendored-package.md	How to add a vendored package	Vendored packages
docs/cookbook/adding-a-conversation-node.md	Add a Web Client conversation node	Web UI
docs/cookbook/extension-cookbook.md	Extension plugin shapes (features → capabilities index)	Extension cookbook (see docs/cookbook/extension-cookbook.md)
docs/cookbook/maintaining-dsh-code-review.md	Maintaining the dsh-code-review skill	Development
docs/cookbook/responding-to-pr-review-on-a-stack.md	Responding across a stacked PR chain	Development

User guides (docs/user/)

Three sub-trees: guide/ (Web UI usage, providers/models, Python SDK), develop/ (basic plugin → service framework → three-role practice), and the top-level index.md (redirect).

Repo path	What it covers	Worth reading for
docs/user/index.md	Redirect to the Web UI quickstart	Quickstart
docs/user/guide/index.md	Using the Web UI after server start	Web UI
docs/user/guide/providers.md	Configuring models and providers	Models
docs/user/guide/python-sdk.md	Getting started with the Python SDK	SDK
docs/user/develop/basic/index.md	Your first plugin, loaded into the Web UI	First plugin (see docs/user/develop/basic/)
docs/user/develop/framework/index.md	Cordis plugin model and lifecycle state machine	Develop framework (see docs/user/develop/framework/)
docs/user/develop/practice/index.md	Three-role capability design, concept + advanced tutorial	Capability seams

docs/user/develop/basic/ covers tool.md, config.md, publish.md; docs/user/develop/framework/ covers service.md and events.md; practice has an llm-adapter.md.

Post-mortems (docs/postmortem/)

Repo path	What it covers	Worth reading for
docs/postmortem/README.md	Index of incident post-mortems	Post-mortems (see docs/postmortem/README.md)
docs/postmortem/0001-*.md	ACP default-export drops inject	Extensibility
docs/postmortem/0002-*.md	JS expression disabled filesystem tools	Filesystem
docs/postmortem/0003-*.md	Web agent GUI feedback loop	Web UI
docs/postmortem/0004-*.md	Landlock partial notice misclassified child failures	Sandbox

There are four numbered post-mortems at this revision (0001…0004).

Further reading

• Package index — maps each doc to the packages it describes.
• Glossary — the vocabulary the upstream docs assume.
• docs/README.md-level scaffolding lives in docs/*.md (repo-relative).
• docs/i18n/README.md — the bilingual pairing contract (repo-relative).