add developer docs

docs-site/docs/developer/bun-bundle-and-feature-flags.md

@@ -0,0 +1,26 @@
+# Bun bundle and feature flags
+
+The shipping Claude Code CLI is built with **Bun** and internal **`bun:bundle`** integration. In the recovered source, `src/main.tsx` uses compile-time feature gates such as:
+
+- `feature('KAIROS')` — lazy `require` of `assistant/` (assistant / Agent SDK–oriented paths).
+- `feature('COORDINATOR_MODE')` — lazy `require` of `coordinator/coordinatorMode`.
+- `feature('VOICE_MODE')` — conditional `useVoiceIntegration` in `REPL.tsx`.
+
+## What `feature()` means here
+
+In Anthropic’s pipeline, `feature('…')` is almost certainly a **constant** resolved at bundle time: dead branches are stripped from the published `cli.js`. The reconstruction **contains all branches** as TypeScript, so you can read “internal” code paths that might not ship in every npm artifact.
+
+## Implications for “building from source”
+
+A normal `tsc` or `bun build` **without** Anthropic’s bundler will not reproduce:
+
+- The same dead-code elimination.
+- The same `bun:bundle` API semantics.
+- The same proprietary dependency closure.
+
+That is one reason [Reproducibility and limits](../reproducibility.md) states you cannot rebuild the shipping binary from this mirror.
+
+## See also
+
+- [System design: layers](../system-design/layers.md)
+- [CLI entry reference](../reference/cli-entry.md)

docs-site/docs/developer/editing-documentation.md

@@ -0,0 +1,29 @@
+# Editing this documentation
+
+## Local setup
+
+```bash
+cd docs-site
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+mkdocs serve
+```
+
+Open `http://127.0.0.1:8000` and edit files under `docs-site/docs/`. The site reloads on save.
+
+## Conventions
+
+- Use **admonitions** for legal and safety notes (`!!! warning` for proprietary / leak context).
+- Prefer **relative links** between pages (`../reference/cli-entry.md` in source becomes sibling URLs when built).
+- Add **mermaid** only where diagrams clarify flow; keep [mermaid syntax](https://mermaid.js.org/) compatible with [Material diagrams](https://squidfunk.github.io/mkdocs-material/reference/diagrams/).
+
+## After structural changes
+
+If you add a **new top-level topic** that appears in [Anthropic’s docs index](https://code.claude.com/docs/llms.txt), add a row to [Official docs map](../official-docs-map.md).
+
+## Publishing
+
+Pushing to `main` runs the GitHub Action that deploys to `gh-pages`. Ensure `site_url` in `mkdocs.yml` matches your GitHub Pages base URL.
+
+See also: [Documentation and CI for your own projects](../guides/documentation-and-ci-for-docs.md).

docs-site/docs/developer/index.md

@@ -0,0 +1,25 @@
+# Developer hub (this repository)
+
+!!! warning "Not an open-source product repo"
+This tree is **reconstructed proprietary source**. You can maintain **documentation**, trace **read-only** flow in `src/`, and run small **helper scripts**. You **cannot** legally ship Claude Code from this mirror, and there is no supported way to compile the full CLI here.
+
+## What you can do
+
+| Activity                     | How                                                                                                                    |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Preview or extend docs**   | [Editing documentation](editing-documentation.md)                                                                      |
+| **Understand control flow**  | [Navigating the source](navigating-the-source.md)                                                                      |
+| **Learn build-time gates**   | [Bun bundle and feature flags](bun-bundle-and-feature-flags.md)                                                        |
+| **Regenerate appendix data** | `scripts/gen-appendices.sh` at repo root (see [Appendix: environment variables](../appendix/environment-variables.md)) |
+
+## What you cannot do (from this mirror alone)
+
+- Run `npm install` / `bun build` for the full product (no root `package.json`, private graph, `bun:bundle` feature flags).
+- Execute a project-wide automated test suite for the CLI (no harness shipped in the reconstruction).
+
+Details: [Reproducibility and limits](../reproducibility.md).
+
+## Related
+
+- [System design: layers](../system-design/layers.md)
+- [Official docs map](../official-docs-map.md)

docs-site/docs/developer/navigating-the-source.md

@@ -0,0 +1,37 @@
+# Navigating the `src/` tree
+
+!!! warning "Read-only study"
+Use this guide to **read** the reconstruction. Do not treat the tree as a template for redistributing Anthropic’s product.
+
+## Suggested reading order
+
+1. **`main argv` and lifecycle** — `src/main.tsx` (Commander, `preAction`, mode routing).
+2. **Interactive path** — `src/replLauncher.tsx`, `src/screens/REPL.tsx` (queue, `onQuery`, UI).
+3. **Headless path** — `src/cli/print.ts`, `src/cli/structuredIO.ts`, `src/QueryEngine.ts`.
+4. **Core loop** — `src/query.ts` (`queryLoop`), then `src/services/api/client.ts` / `claude.ts`.
+5. **Tools** — `src/tools.ts`, `src/Tool.ts`, then a single tool package e.g. `src/tools/BashTool/` and `src/services/tools/`.
+6. **MCP** — `src/services/mcp/` and `src/tools/MCPTool/`.
+
+## Maps and indexes
+
+- Top-level layout: [Appendix: directory structure](../appendix/directory-structure.md) (and repo `docs/directory-structure.md`).
+- Tool packages: [Appendix: tool packages](../appendix/tool-packages.md).
+- Official doc crosswalk: [Official docs map](../official-docs-map.md).
+
+## Search tips
+
+From the repository root:
+
+```bash
+# Example: find where a symbol is used
+rg "queryLoop" src/query.ts src/ -n
+
+# Example: MCP channel permissions
+rg "channelAllowlist" src/services/mcp -n
+```
+
+IDE “go to definition” may be incomplete: there is **no** root `tsconfig.json` or `package.json` mirroring Anthropic’s build, so path aliases like `src/...` might not resolve everywhere.
+
+## Deeper subsystems
+
+Use the [Reference](../reference/cli-entry.md) section for per-topic entry points (permissions, compaction, telemetry, bridge, etc.).