diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 73d7e9266..82180fb53 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,11 +1,11 @@
 blank_issues_enabled: true
 contact_links:
   - name: Model Configuration
-    url: https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/docs/models.md
+    url: https://github.com/can1357/oh-my-pi/blob/main/docs/models.md
     about: How to add custom providers and models via models.yml
   - name: Extensions Guide
-    url: https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/docs/extensions.md
+    url: https://github.com/can1357/oh-my-pi/blob/main/docs/extensions.md
     about: Build custom tools, commands, and integrations
   - name: Skills Documentation
-    url: https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/docs/skills.md
+    url: https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md
     about: How to create and use skills
diff --git a/README.md b/README.md
index 788356821..5460a1f7d 100644
--- a/README.md
+++ b/README.md
@@ -469,7 +469,7 @@ return config
 | OpenRouter | `OPENROUTER_API_KEY` |
 | Z.AI       | `ZAI_API_KEY`        |
 
-See [Environment Variables](packages/coding-agent/docs/environment-variables.md) for the full list.
+See [Environment Variables](docs/environment-variables.md) for the full list.
 
 **Option 2: OAuth / interactive auth (`/login`)**
 
@@ -670,7 +670,7 @@ Toggle inline images via `/settings` or set `terminal.showImages: false`.
 
 Sessions are stored as JSONL with a tree structure for branching and replay.
 
-See [packages/coding-agent/docs/session.md](packages/coding-agent/docs/session.md) for the file format and API.
+See [docs/session.md](docs/session.md) for the file format and API.
 
 ### Session Management
 
@@ -712,7 +712,7 @@ compaction:
   autoContinue: true
 ```
 
-See [packages/coding-agent/docs/compaction.md](packages/coding-agent/docs/compaction.md) for internals and hook integration.
+See [docs/compaction.md](docs/compaction.md) for internals and hook integration.
 
 ### Branching
 
@@ -758,7 +758,7 @@ Add custom providers/models via `~/.omp/agent/models.yml`.
 
 `models.json` is still supported for legacy configs, but `models.yml` is the modern format.
 
-> See [models.yml provider integration guide](packages/coding-agent/docs/models.md) for schema and merge behavior.
+> See [models.yml provider integration guide](docs/models.md) for schema and merge behavior.
 
 ```yaml
 providers:
@@ -858,7 +858,7 @@ theme:
 
 **Custom themes:** create `~/.omp/agent/themes/*.json`.
 
-> See [Theme Documentation](packages/coding-agent/docs/theme.md).
+> See [Theme Documentation](docs/theme.md).
 
 ### Custom Slash Commands
 
@@ -917,7 +917,7 @@ description: Web search via Brave Search API.
 
 Disable skills with `omp --no-skills` or `skills.enabled: false`.
 
-> See [Skills Documentation](packages/coding-agent/docs/skills.md).
+> See [Skills Documentation](docs/skills.md).
 
 ### Hooks
 
@@ -949,7 +949,7 @@ Inject messages from hooks with:
 omp.sendMessage(message, { triggerTurn: true });
 ```
 
-> See [Hooks Documentation](packages/coding-agent/docs/hooks.md) and [examples/hooks/](packages/coding-agent/examples/hooks/).
+> See [Hooks Documentation](docs/hooks.md) and [examples/hooks/](packages/coding-agent/examples/hooks/).
 
 ### Custom Tools
 
@@ -978,7 +978,7 @@ const factory: CustomToolFactory = () => ({
 export default factory;
 ```
 
-> See [Custom Tools Documentation](packages/coding-agent/docs/custom-tools.md) and [examples/custom-tools/](packages/coding-agent/examples/custom-tools/).
+> See [Custom Tools Documentation](docs/custom-tools.md) and [examples/custom-tools/](packages/coding-agent/examples/custom-tools/).
 
 ---
 
@@ -1084,7 +1084,7 @@ omp --export session.jsonl output.html
 | `PI_NO_PTY`                                       | Disable PTY-based bash execution                        |
 | `VISUAL`, `EDITOR`                                | External editor for Ctrl+G                              |
 
-See [Environment Variables](packages/coding-agent/docs/environment-variables.md) for the complete reference.
+See [Environment Variables](docs/environment-variables.md) for the complete reference.
 
 ---
 
@@ -1162,7 +1162,7 @@ The SDK provides control over:
 - Settings (`Settings`)
 - API key and OAuth resolution
 
-> See [SDK Documentation](packages/coding-agent/docs/sdk.md) and [examples/sdk/](packages/coding-agent/examples/sdk/).
+> See [SDK Documentation](docs/sdk.md) and [examples/sdk/](packages/coding-agent/examples/sdk/).
 
 ### RPC Mode
 
@@ -1181,7 +1181,7 @@ Send JSON commands on stdin:
 
 Responses are emitted as `type: "response"`; session events stream on stdout as they occur.
 
-> See [RPC Documentation](packages/coding-agent/docs/rpc.md) for the full protocol.
+> See [RPC Documentation](docs/rpc.md) for the full protocol.
 
 ### HTML Export
 
diff --git a/packages/coding-agent/docs/bash-tool-runtime.md b/docs/bash-tool-runtime.md
similarity index 84%
rename from packages/coding-agent/docs/bash-tool-runtime.md
rename to docs/bash-tool-runtime.md
index ec4a087dc..ba494f137 100644
--- a/packages/coding-agent/docs/bash-tool-runtime.md
+++ b/docs/bash-tool-runtime.md
@@ -258,16 +258,16 @@ This component is wired by `CommandController.handleBashCommand()` and fed from
 
 ## Implementation files
 
-- [`src/tools/bash.ts`](../src/tools/bash.ts) — tool entrypoint, normalization/interception, PTY/non-PTY selection, result/error mapping, bash tool renderer.
-- [`src/tools/bash-normalize.ts`](../src/tools/bash-normalize.ts) — command normalization and post-run head/tail filtering.
-- [`src/tools/bash-interceptor.ts`](../src/tools/bash-interceptor.ts) — interceptor rule matching and blocked-command messages.
-- [`src/exec/bash-executor.ts`](../src/exec/bash-executor.ts) — non-PTY executor, shell session reuse, cancellation wiring, output sink integration.
-- [`src/tools/bash-interactive.ts`](../src/tools/bash-interactive.ts) — PTY runtime, overlay UI, input normalization, non-interactive env defaults.
-- [`src/session/streaming-output.ts`](../src/session/streaming-output.ts) — `OutputSink` truncation/artifact spill and summary metadata.
-- [`src/tools/output-utils.ts`](../src/tools/output-utils.ts) — artifact allocation helpers and streaming tail buffer.
-- [`src/tools/output-meta.ts`](../src/tools/output-meta.ts) — truncation metadata shape + notice injection wrapper.
-- [`src/session/agent-session.ts`](../src/session/agent-session.ts) — session-level `executeBash`, message recording, abort lifecycle.
-- [`src/modes/components/bash-execution.ts`](../src/modes/components/bash-execution.ts) — interactive `!` command execution component.
-- [`src/modes/controllers/command-controller.ts`](../src/modes/controllers/command-controller.ts) — wiring for interactive `!` command UI stream/update completion.
-- [`src/modes/rpc/rpc-mode.ts`](../src/modes/rpc/rpc-mode.ts) — RPC `bash` and `abort_bash` command surface.
-- [`src/internal-urls/artifact-protocol.ts`](../src/internal-urls/artifact-protocol.ts) — `artifact://<id>` resolution.
\ No newline at end of file
+- [`src/tools/bash.ts`](../packages/coding-agent/src/tools/bash.ts) — tool entrypoint, normalization/interception, PTY/non-PTY selection, result/error mapping, bash tool renderer.
+- [`src/tools/bash-normalize.ts`](../packages/coding-agent/src/tools/bash-normalize.ts) — command normalization and post-run head/tail filtering.
+- [`src/tools/bash-interceptor.ts`](../packages/coding-agent/src/tools/bash-interceptor.ts) — interceptor rule matching and blocked-command messages.
+- [`src/exec/bash-executor.ts`](../packages/coding-agent/src/exec/bash-executor.ts) — non-PTY executor, shell session reuse, cancellation wiring, output sink integration.
+- [`src/tools/bash-interactive.ts`](../packages/coding-agent/src/tools/bash-interactive.ts) — PTY runtime, overlay UI, input normalization, non-interactive env defaults.
+- [`src/session/streaming-output.ts`](../packages/coding-agent/src/session/streaming-output.ts) — `OutputSink` truncation/artifact spill and summary metadata.
+- [`src/tools/output-utils.ts`](../packages/coding-agent/src/tools/output-utils.ts) — artifact allocation helpers and streaming tail buffer.
+- [`src/tools/output-meta.ts`](../packages/coding-agent/src/tools/output-meta.ts) — truncation metadata shape + notice injection wrapper.
+- [`src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — session-level `executeBash`, message recording, abort lifecycle.
+- [`src/modes/components/bash-execution.ts`](../packages/coding-agent/src/modes/components/bash-execution.ts) — interactive `!` command execution component.
+- [`src/modes/controllers/command-controller.ts`](../packages/coding-agent/src/modes/controllers/command-controller.ts) — wiring for interactive `!` command UI stream/update completion.
+- [`src/modes/rpc/rpc-mode.ts`](../packages/coding-agent/src/modes/rpc/rpc-mode.ts) — RPC `bash` and `abort_bash` command surface.
+- [`src/internal-urls/artifact-protocol.ts`](../packages/coding-agent/src/internal-urls/artifact-protocol.ts) — `artifact://<id>` resolution.
\ No newline at end of file
diff --git a/packages/coding-agent/docs/blob-artifact-architecture.md b/docs/blob-artifact-architecture.md
similarity index 84%
rename from packages/coding-agent/docs/blob-artifact-architecture.md
rename to docs/blob-artifact-architecture.md
index 79fbe8a0d..0a809793c 100644
--- a/packages/coding-agent/docs/blob-artifact-architecture.md
+++ b/docs/blob-artifact-architecture.md
@@ -219,14 +219,14 @@ The two systems intersect only indirectly (both reduce session JSONL bloat) but
 
 ## Implementation files
 
-- [`src/session/blob-store.ts`](../src/session/blob-store.ts) — blob reference format, hashing, put/get, externalize/resolve helpers.
-- [`src/session/artifacts.ts`](../src/session/artifacts.ts) — session artifact directory model and numeric artifact ID allocation.
-- [`src/session/streaming-output.ts`](../src/session/streaming-output.ts) — `OutputSink` truncation/spill-to-file behavior and summary metadata.
-- [`src/session/session-manager.ts`](../src/session/session-manager.ts) — persistence transforms, blob rehydration on load, session fork/move interactions.
-- [`src/session/agent-session.ts`](../src/session/agent-session.ts) — artifact directory copy during interactive fork.
-- [`src/tools/output-utils.ts`](../src/tools/output-utils.ts) — tool artifact manager bootstrap and per-tool artifact path allocation.
-- [`src/internal-urls/artifact-protocol.ts`](../src/internal-urls/artifact-protocol.ts) — `artifact://` resolver.
-- [`src/internal-urls/agent-protocol.ts`](../src/internal-urls/agent-protocol.ts) — `agent://` resolver + JSON extraction.
-- [`src/sdk.ts`](../src/sdk.ts) — internal URL router wiring and artifacts-dir resolver.
-- [`src/task/output-manager.ts`](../src/task/output-manager.ts) — session-scoped agent output ID allocation for `agent://`.
-- [`src/task/executor.ts`](../src/task/executor.ts) — subagent output artifact writes (`<id>.md`) and temp artifact directory fallback.
\ No newline at end of file
+- [`src/session/blob-store.ts`](../packages/coding-agent/src/session/blob-store.ts) — blob reference format, hashing, put/get, externalize/resolve helpers.
+- [`src/session/artifacts.ts`](../packages/coding-agent/src/session/artifacts.ts) — session artifact directory model and numeric artifact ID allocation.
+- [`src/session/streaming-output.ts`](../packages/coding-agent/src/session/streaming-output.ts) — `OutputSink` truncation/spill-to-file behavior and summary metadata.
+- [`src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts) — persistence transforms, blob rehydration on load, session fork/move interactions.
+- [`src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — artifact directory copy during interactive fork.
+- [`src/tools/output-utils.ts`](../packages/coding-agent/src/tools/output-utils.ts) — tool artifact manager bootstrap and per-tool artifact path allocation.
+- [`src/internal-urls/artifact-protocol.ts`](../packages/coding-agent/src/internal-urls/artifact-protocol.ts) — `artifact://` resolver.
+- [`src/internal-urls/agent-protocol.ts`](../packages/coding-agent/src/internal-urls/agent-protocol.ts) — `agent://` resolver + JSON extraction.
+- [`src/sdk.ts`](../packages/coding-agent/src/sdk.ts) — internal URL router wiring and artifacts-dir resolver.
+- [`src/task/output-manager.ts`](../packages/coding-agent/src/task/output-manager.ts) — session-scoped agent output ID allocation for `agent://`.
+- [`src/task/executor.ts`](../packages/coding-agent/src/task/executor.ts) — subagent output artifact writes (`<id>.md`) and temp artifact directory fallback.
\ No newline at end of file
diff --git a/packages/coding-agent/docs/compaction.md b/docs/compaction.md
similarity index 100%
rename from packages/coding-agent/docs/compaction.md
rename to docs/compaction.md
diff --git a/packages/coding-agent/docs/config-usage.md b/docs/config-usage.md
similarity index 100%
rename from packages/coding-agent/docs/config-usage.md
rename to docs/config-usage.md
diff --git a/packages/coding-agent/docs/custom-tools.md b/docs/custom-tools.md
similarity index 100%
rename from packages/coding-agent/docs/custom-tools.md
rename to docs/custom-tools.md
diff --git a/packages/coding-agent/docs/environment-variables.md b/docs/environment-variables.md
similarity index 100%
rename from packages/coding-agent/docs/environment-variables.md
rename to docs/environment-variables.md
diff --git a/packages/coding-agent/docs/extension-loading.md b/docs/extension-loading.md
similarity index 100%
rename from packages/coding-agent/docs/extension-loading.md
rename to docs/extension-loading.md
diff --git a/packages/coding-agent/docs/extensions.md b/docs/extensions.md
similarity index 100%
rename from packages/coding-agent/docs/extensions.md
rename to docs/extensions.md
diff --git a/packages/coding-agent/docs/fs-scan-cache-architecture.md b/docs/fs-scan-cache-architecture.md
similarity index 100%
rename from packages/coding-agent/docs/fs-scan-cache-architecture.md
rename to docs/fs-scan-cache-architecture.md
diff --git a/packages/coding-agent/docs/gemini-manifest-extensions.md b/docs/gemini-manifest-extensions.md
similarity index 91%
rename from packages/coding-agent/docs/gemini-manifest-extensions.md
rename to docs/gemini-manifest-extensions.md
index 79e6475c4..b6aeefdbb 100644
--- a/packages/coding-agent/docs/gemini-manifest-extensions.md
+++ b/docs/gemini-manifest-extensions.md
@@ -6,12 +6,12 @@ It does **not** cover TypeScript/JavaScript extension module loading (`extension
 
 ## Implementation files
 
-- [`../src/discovery/gemini.ts`](../src/discovery/gemini.ts)
-- [`../src/discovery/builtin.ts`](../src/discovery/builtin.ts)
-- [`../src/discovery/helpers.ts`](../src/discovery/helpers.ts)
-- [`../src/capability/extension.ts`](../src/capability/extension.ts)
-- [`../src/capability/index.ts`](../src/capability/index.ts)
-- [`../src/extensibility/extensions/loader.ts`](../src/extensibility/extensions/loader.ts)
+- [`../src/discovery/gemini.ts`](../packages/coding-agent/src/discovery/gemini.ts)
+- [`../src/discovery/builtin.ts`](../packages/coding-agent/src/discovery/builtin.ts)
+- [`../src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)
+- [`../src/capability/extension.ts`](../packages/coding-agent/src/capability/extension.ts)
+- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)
+- [`../src/extensibility/extensions/loader.ts`](../packages/coding-agent/src/extensibility/extensions/loader.ts)
 
 ---
 
diff --git a/packages/coding-agent/docs/handoff-generation-pipeline.md b/docs/handoff-generation-pipeline.md
similarity index 94%
rename from packages/coding-agent/docs/handoff-generation-pipeline.md
rename to docs/handoff-generation-pipeline.md
index 50fdb032d..de3fd082e 100644
--- a/packages/coding-agent/docs/handoff-generation-pipeline.md
+++ b/docs/handoff-generation-pipeline.md
@@ -19,11 +19,11 @@ Does not cover:
 
 ## Implementation files
 
-- [`../src/modes/controllers/input-controller.ts`](../src/modes/controllers/input-controller.ts)
-- [`../src/modes/controllers/command-controller.ts`](../src/modes/controllers/command-controller.ts)
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`../src/session/session-manager.ts`](../src/session/session-manager.ts)
-- [`../src/extensibility/slash-commands.ts`](../src/extensibility/slash-commands.ts)
+- [`../src/modes/controllers/input-controller.ts`](../packages/coding-agent/src/modes/controllers/input-controller.ts)
+- [`../src/modes/controllers/command-controller.ts`](../packages/coding-agent/src/modes/controllers/command-controller.ts)
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)
+- [`../src/extensibility/slash-commands.ts`](../packages/coding-agent/src/extensibility/slash-commands.ts)
 
 ## Trigger path
 
diff --git a/packages/coding-agent/docs/hooks.md b/docs/hooks.md
similarity index 100%
rename from packages/coding-agent/docs/hooks.md
rename to docs/hooks.md
diff --git a/packages/coding-agent/docs/mcp-protocol-transports.md b/docs/mcp-protocol-transports.md
similarity index 94%
rename from packages/coding-agent/docs/mcp-protocol-transports.md
rename to docs/mcp-protocol-transports.md
index 4ade289bf..928db12b1 100644
--- a/packages/coding-agent/docs/mcp-protocol-transports.md
+++ b/docs/mcp-protocol-transports.md
@@ -17,13 +17,13 @@ Does not cover extension authoring UX or command UI.
 
 ## Implementation files
 
-- [`src/mcp/types.ts`](../src/mcp/types.ts)
-- [`src/mcp/transports/stdio.ts`](../src/mcp/transports/stdio.ts)
-- [`src/mcp/transports/http.ts`](../src/mcp/transports/http.ts)
-- [`src/mcp/transports/index.ts`](../src/mcp/transports/index.ts)
-- [`src/mcp/json-rpc.ts`](../src/mcp/json-rpc.ts)
-- [`src/mcp/client.ts`](../src/mcp/client.ts)
-- [`src/mcp/manager.ts`](../src/mcp/manager.ts)
+- [`src/mcp/types.ts`](../packages/coding-agent/src/mcp/types.ts)
+- [`src/mcp/transports/stdio.ts`](../packages/coding-agent/src/mcp/transports/stdio.ts)
+- [`src/mcp/transports/http.ts`](../packages/coding-agent/src/mcp/transports/http.ts)
+- [`src/mcp/transports/index.ts`](../packages/coding-agent/src/mcp/transports/index.ts)
+- [`src/mcp/json-rpc.ts`](../packages/coding-agent/src/mcp/json-rpc.ts)
+- [`src/mcp/client.ts`](../packages/coding-agent/src/mcp/client.ts)
+- [`src/mcp/manager.ts`](../packages/coding-agent/src/mcp/manager.ts)
 
 ## Layer boundaries
 
diff --git a/packages/coding-agent/docs/mcp-runtime-lifecycle.md b/docs/mcp-runtime-lifecycle.md
similarity index 87%
rename from packages/coding-agent/docs/mcp-runtime-lifecycle.md
rename to docs/mcp-runtime-lifecycle.md
index f49a94a70..85ab1016a 100644
--- a/packages/coding-agent/docs/mcp-runtime-lifecycle.md
+++ b/docs/mcp-runtime-lifecycle.md
@@ -198,13 +198,13 @@ In current wiring, explicit teardown is used in MCP command flows (for reload/re
 
 ## Implementation files
 
-- [`src/mcp/loader.ts`](../src/mcp/loader.ts) — loader facade, discovery error normalization, `LoadedCustomTool` conversion.
-- [`src/mcp/manager.ts`](../src/mcp/manager.ts) — lifecycle state registries, parallel connect/list flow, refresh/disconnect.
-- [`src/mcp/client.ts`](../src/mcp/client.ts) — transport setup, initialize handshake, list/call/disconnect.
-- [`src/mcp/index.ts`](../src/mcp/index.ts) — MCP module API exports.
-- [`src/sdk.ts`](../src/sdk.ts) — startup wiring into session/tool registry.
-- [`src/mcp/config.ts`](../src/mcp/config.ts) — config discovery/filtering/validation used by manager.
-- [`src/mcp/tool-bridge.ts`](../src/mcp/tool-bridge.ts) — `MCPTool` and `DeferredMCPTool` runtime behavior.
-- [`src/session/agent-session.ts`](../src/session/agent-session.ts) — `refreshMCPTools` live rebinding.
-- [`src/modes/controllers/mcp-command-controller.ts`](../src/modes/controllers/mcp-command-controller.ts) — interactive reload/reconnect flows.
-- [`src/task/executor.ts`](../src/task/executor.ts) — subagent MCP proxying via parent manager connections.
+- [`src/mcp/loader.ts`](../packages/coding-agent/src/mcp/loader.ts) — loader facade, discovery error normalization, `LoadedCustomTool` conversion.
+- [`src/mcp/manager.ts`](../packages/coding-agent/src/mcp/manager.ts) — lifecycle state registries, parallel connect/list flow, refresh/disconnect.
+- [`src/mcp/client.ts`](../packages/coding-agent/src/mcp/client.ts) — transport setup, initialize handshake, list/call/disconnect.
+- [`src/mcp/index.ts`](../packages/coding-agent/src/mcp/index.ts) — MCP module API exports.
+- [`src/sdk.ts`](../packages/coding-agent/src/sdk.ts) — startup wiring into session/tool registry.
+- [`src/mcp/config.ts`](../packages/coding-agent/src/mcp/config.ts) — config discovery/filtering/validation used by manager.
+- [`src/mcp/tool-bridge.ts`](../packages/coding-agent/src/mcp/tool-bridge.ts) — `MCPTool` and `DeferredMCPTool` runtime behavior.
+- [`src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — `refreshMCPTools` live rebinding.
+- [`src/modes/controllers/mcp-command-controller.ts`](../packages/coding-agent/src/modes/controllers/mcp-command-controller.ts) — interactive reload/reconnect flows.
+- [`src/task/executor.ts`](../packages/coding-agent/src/task/executor.ts) — subagent MCP proxying via parent manager connections.
diff --git a/packages/coding-agent/docs/mcp-server-tool-authoring.md b/docs/mcp-server-tool-authoring.md
similarity index 91%
rename from packages/coding-agent/docs/mcp-server-tool-authoring.md
rename to docs/mcp-server-tool-authoring.md
index a20a59441..3f8333a52 100644
--- a/packages/coding-agent/docs/mcp-server-tool-authoring.md
+++ b/docs/mcp-server-tool-authoring.md
@@ -214,13 +214,13 @@ For robust MCP authoring in this codebase:
 
 ## Implementation files
 
-- [`src/mcp/types.ts`](../src/mcp/types.ts)
-- [`src/mcp/config.ts`](../src/mcp/config.ts)
-- [`src/mcp/config-writer.ts`](../src/mcp/config-writer.ts)
-- [`src/mcp/tool-bridge.ts`](../src/mcp/tool-bridge.ts)
-- [`src/discovery/mcp-json.ts`](../src/discovery/mcp-json.ts)
-- [`src/modes/controllers/mcp-command-controller.ts`](../src/modes/controllers/mcp-command-controller.ts)
-- [`src/mcp/manager.ts`](../src/mcp/manager.ts)
-- [`src/capability/index.ts`](../src/capability/index.ts)
-- [`src/config/resolve-config-value.ts`](../src/config/resolve-config-value.ts)
-- [`src/mcp/loader.ts`](../src/mcp/loader.ts)
+- [`src/mcp/types.ts`](../packages/coding-agent/src/mcp/types.ts)
+- [`src/mcp/config.ts`](../packages/coding-agent/src/mcp/config.ts)
+- [`src/mcp/config-writer.ts`](../packages/coding-agent/src/mcp/config-writer.ts)
+- [`src/mcp/tool-bridge.ts`](../packages/coding-agent/src/mcp/tool-bridge.ts)
+- [`src/discovery/mcp-json.ts`](../packages/coding-agent/src/discovery/mcp-json.ts)
+- [`src/modes/controllers/mcp-command-controller.ts`](../packages/coding-agent/src/modes/controllers/mcp-command-controller.ts)
+- [`src/mcp/manager.ts`](../packages/coding-agent/src/mcp/manager.ts)
+- [`src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)
+- [`src/config/resolve-config-value.ts`](../packages/coding-agent/src/config/resolve-config-value.ts)
+- [`src/mcp/loader.ts`](../packages/coding-agent/src/mcp/loader.ts)
diff --git a/packages/coding-agent/docs/models.md b/docs/models.md
similarity index 100%
rename from packages/coding-agent/docs/models.md
rename to docs/models.md
diff --git a/packages/coding-agent/docs/non-compaction-retry-policy.md b/docs/non-compaction-retry-policy.md
similarity index 92%
rename from packages/coding-agent/docs/non-compaction-retry-policy.md
rename to docs/non-compaction-retry-policy.md
index 2fe3780a9..29bad0ca7 100644
--- a/packages/coding-agent/docs/non-compaction-retry-policy.md
+++ b/docs/non-compaction-retry-policy.md
@@ -2,16 +2,16 @@
 
 This document describes the standard API-error retry path in `AgentSession`.
 
-It explicitly excludes context-overflow recovery via auto-compaction. Overflow is handled by compaction logic and is documented separately in [`compaction.md`](./compaction.md).
+It explicitly excludes context-overflow recovery via auto-compaction. Overflow is handled by compaction logic and is documented separately in [`compaction.md`](../docs/compaction.md).
 
 ## Implementation files
 
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`../src/config/settings-schema.ts`](../src/config/settings-schema.ts)
-- [`../src/modes/controllers/event-controller.ts`](../src/modes/controllers/event-controller.ts)
-- [`../src/modes/rpc/rpc-mode.ts`](../src/modes/rpc/rpc-mode.ts)
-- [`../src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts)
-- [`../src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts)
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`../src/config/settings-schema.ts`](../packages/coding-agent/src/config/settings-schema.ts)
+- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)
+- [`../src/modes/rpc/rpc-mode.ts`](../packages/coding-agent/src/modes/rpc/rpc-mode.ts)
+- [`../src/modes/rpc/rpc-client.ts`](../packages/coding-agent/src/modes/rpc/rpc-client.ts)
+- [`../src/modes/rpc/rpc-types.ts`](../packages/coding-agent/src/modes/rpc/rpc-types.ts)
 
 ## Scope boundary vs compaction
 
diff --git a/packages/coding-agent/docs/notebook-tool-runtime.md b/docs/notebook-tool-runtime.md
similarity index 95%
rename from packages/coding-agent/docs/notebook-tool-runtime.md
rename to docs/notebook-tool-runtime.md
index d478ed6ac..7181a0646 100644
--- a/packages/coding-agent/docs/notebook-tool-runtime.md
+++ b/docs/notebook-tool-runtime.md
@@ -6,11 +6,11 @@ The critical distinction: **`notebook` is a JSON notebook editor, not a notebook
 
 ## Implementation files
 
-- [`src/tools/notebook.ts`](../src/tools/notebook.ts)
-- [`src/ipy/executor.ts`](../src/ipy/executor.ts)
-- [`src/ipy/kernel.ts`](../src/ipy/kernel.ts)
-- [`src/session/streaming-output.ts`](../src/session/streaming-output.ts)
-- [`src/tools/python.ts`](../src/tools/python.ts)
+- [`src/tools/notebook.ts`](../packages/coding-agent/src/tools/notebook.ts)
+- [`src/ipy/executor.ts`](../packages/coding-agent/src/ipy/executor.ts)
+- [`src/ipy/kernel.ts`](../packages/coding-agent/src/ipy/kernel.ts)
+- [`src/session/streaming-output.ts`](../packages/coding-agent/src/session/streaming-output.ts)
+- [`src/tools/python.ts`](../packages/coding-agent/src/tools/python.ts)
 
 ## 1) Runtime boundary: editing vs executing
 
diff --git a/packages/coding-agent/docs/plugin-manager-installer-plumbing.md b/docs/plugin-manager-installer-plumbing.md
similarity index 89%
rename from packages/coding-agent/docs/plugin-manager-installer-plumbing.md
rename to docs/plugin-manager-installer-plumbing.md
index 54771d4b7..5542d90b8 100644
--- a/packages/coding-agent/docs/plugin-manager-installer-plumbing.md
+++ b/docs/plugin-manager-installer-plumbing.md
@@ -254,11 +254,11 @@ Operationally, `doctor --fix` can repair some drift (`bun install`, orphaned con
 
 ## Implementation files
 
-- [`src/commands/plugin.ts`](../src/commands/plugin.ts) — CLI command declaration and flag mapping
-- [`src/cli/plugin-cli.ts`](../src/cli/plugin-cli.ts) — action dispatch, user-facing command handlers
-- [`src/extensibility/plugins/manager.ts`](../src/extensibility/plugins/manager.ts) — active install/remove/list/link/state/doctor implementation
-- [`src/extensibility/plugins/installer.ts`](../src/extensibility/plugins/installer.ts) — legacy installer helpers and additional link safety checks
-- [`src/extensibility/plugins/loader.ts`](../src/extensibility/plugins/loader.ts) — enabled-plugin discovery and tool/hook/command path resolution
-- [`src/extensibility/plugins/parser.ts`](../src/extensibility/plugins/parser.ts) — install spec and package-name parsing helpers
-- [`src/extensibility/plugins/types.ts`](../src/extensibility/plugins/types.ts) — manifest/runtime/override type contracts
-- [`src/extensibility/custom-tools/loader.ts`](../src/extensibility/custom-tools/loader.ts) — runtime wiring for plugin-provided tool modules
+- [`src/commands/plugin.ts`](../packages/coding-agent/src/commands/plugin.ts) — CLI command declaration and flag mapping
+- [`src/cli/plugin-cli.ts`](../packages/coding-agent/src/cli/plugin-cli.ts) — action dispatch, user-facing command handlers
+- [`src/extensibility/plugins/manager.ts`](../packages/coding-agent/src/extensibility/plugins/manager.ts) — active install/remove/list/link/state/doctor implementation
+- [`src/extensibility/plugins/installer.ts`](../packages/coding-agent/src/extensibility/plugins/installer.ts) — legacy installer helpers and additional link safety checks
+- [`src/extensibility/plugins/loader.ts`](../packages/coding-agent/src/extensibility/plugins/loader.ts) — enabled-plugin discovery and tool/hook/command path resolution
+- [`src/extensibility/plugins/parser.ts`](../packages/coding-agent/src/extensibility/plugins/parser.ts) — install spec and package-name parsing helpers
+- [`src/extensibility/plugins/types.ts`](../packages/coding-agent/src/extensibility/plugins/types.ts) — manifest/runtime/override type contracts
+- [`src/extensibility/custom-tools/loader.ts`](../packages/coding-agent/src/extensibility/custom-tools/loader.ts) — runtime wiring for plugin-provided tool modules
diff --git a/packages/coding-agent/docs/provider-streaming-internals.md b/docs/provider-streaming-internals.md
similarity index 87%
rename from packages/coding-agent/docs/provider-streaming-internals.md
rename to docs/provider-streaming-internals.md
index 17c7a726d..9974ac1d2 100644
--- a/packages/coding-agent/docs/provider-streaming-internals.md
+++ b/docs/provider-streaming-internals.md
@@ -207,12 +207,12 @@ Provider-specific (not fully abstracted):
 
 ## Implementation files
 
-- [`../../ai/src/stream.ts`](../../ai/src/stream.ts) — provider dispatch, option mapping, API key/session plumbing.
-- [`../../ai/src/utils/event-stream.ts`](../../ai/src/utils/event-stream.ts) — generic stream queue + assistant delta throttling.
-- [`../../ai/src/utils/json-parse.ts`](../../ai/src/utils/json-parse.ts) — partial JSON parsing for streamed tool arguments.
-- [`../../ai/src/providers/anthropic.ts`](../../ai/src/providers/anthropic.ts) — Anthropic event translation and tool JSON delta accumulation.
-- [`../../ai/src/providers/openai-responses.ts`](../../ai/src/providers/openai-responses.ts) — OpenAI Responses event translation and status mapping.
-- [`../../ai/src/providers/google.ts`](../../ai/src/providers/google.ts) — Gemini stream chunk-to-block translation.
-- [`../../ai/src/providers/google-shared.ts`](../../ai/src/providers/google-shared.ts) — Gemini finish-reason mapping and shared conversion rules.
-- [`../../agent/src/agent-loop.ts`](../../agent/src/agent-loop.ts) — provider stream consumption and `message_update` bridging.
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts) — session-level handling of streaming updates, abort, retry, and persistence.
+- [`../../ai/src/stream.ts`](../packages/ai/src/stream.ts) — provider dispatch, option mapping, API key/session plumbing.
+- [`../../ai/src/utils/event-stream.ts`](../packages/ai/src/utils/event-stream.ts) — generic stream queue + assistant delta throttling.
+- [`../../ai/src/utils/json-parse.ts`](../packages/ai/src/utils/json-parse.ts) — partial JSON parsing for streamed tool arguments.
+- [`../../ai/src/providers/anthropic.ts`](../packages/ai/src/providers/anthropic.ts) — Anthropic event translation and tool JSON delta accumulation.
+- [`../../ai/src/providers/openai-responses.ts`](../packages/ai/src/providers/openai-responses.ts) — OpenAI Responses event translation and status mapping.
+- [`../../ai/src/providers/google.ts`](../packages/ai/src/providers/google.ts) — Gemini stream chunk-to-block translation.
+- [`../../ai/src/providers/google-shared.ts`](../packages/ai/src/providers/google-shared.ts) — Gemini finish-reason mapping and shared conversion rules.
+- [`../../agent/src/agent-loop.ts`](../packages/agent/src/agent-loop.ts) — provider stream consumption and `message_update` bridging.
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — session-level handling of streaming updates, abort, retry, and persistence.
diff --git a/packages/coding-agent/docs/python-repl.md b/docs/python-repl.md
similarity index 100%
rename from packages/coding-agent/docs/python-repl.md
rename to docs/python-repl.md
diff --git a/packages/coding-agent/docs/rpc.md b/docs/rpc.md
similarity index 100%
rename from packages/coding-agent/docs/rpc.md
rename to docs/rpc.md
diff --git a/packages/coding-agent/docs/rulebook-matching-pipeline.md b/docs/rulebook-matching-pipeline.md
similarity index 89%
rename from packages/coding-agent/docs/rulebook-matching-pipeline.md
rename to docs/rulebook-matching-pipeline.md
index 49c346682..23ed6b78d 100644
--- a/packages/coding-agent/docs/rulebook-matching-pipeline.md
+++ b/docs/rulebook-matching-pipeline.md
@@ -9,18 +9,18 @@ It reflects the current implementation, including partial semantics and metadata
 
 ## Implementation files
 
-- [`../src/capability/rule.ts`](../src/capability/rule.ts)
-- [`../src/capability/index.ts`](../src/capability/index.ts)
-- [`../src/discovery/index.ts`](../src/discovery/index.ts)
-- [`../src/discovery/helpers.ts`](../src/discovery/helpers.ts)
-- [`../src/discovery/builtin.ts`](../src/discovery/builtin.ts)
-- [`../src/discovery/cursor.ts`](../src/discovery/cursor.ts)
-- [`../src/discovery/windsurf.ts`](../src/discovery/windsurf.ts)
-- [`../src/discovery/cline.ts`](../src/discovery/cline.ts)
-- [`../src/sdk.ts`](../src/sdk.ts)
-- [`../src/system-prompt.ts`](../src/system-prompt.ts)
-- [`../src/internal-urls/rule-protocol.ts`](../src/internal-urls/rule-protocol.ts)
-- [`../src/utils/frontmatter.ts`](../src/utils/frontmatter.ts)
+- [`../src/capability/rule.ts`](../packages/coding-agent/src/capability/rule.ts)
+- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)
+- [`../src/discovery/index.ts`](../packages/coding-agent/src/discovery/index.ts)
+- [`../src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)
+- [`../src/discovery/builtin.ts`](../packages/coding-agent/src/discovery/builtin.ts)
+- [`../src/discovery/cursor.ts`](../packages/coding-agent/src/discovery/cursor.ts)
+- [`../src/discovery/windsurf.ts`](../packages/coding-agent/src/discovery/windsurf.ts)
+- [`../src/discovery/cline.ts`](../packages/coding-agent/src/discovery/cline.ts)
+- [`../src/sdk.ts`](../packages/coding-agent/src/sdk.ts)
+- [`../src/system-prompt.ts`](../packages/coding-agent/src/system-prompt.ts)
+- [`../src/internal-urls/rule-protocol.ts`](../packages/coding-agent/src/internal-urls/rule-protocol.ts)
+- [`../src/utils/frontmatter.ts`](../packages/coding-agent/src/utils/frontmatter.ts)
 
 ## 1. Canonical rule shape
 
diff --git a/packages/coding-agent/docs/sdk.md b/docs/sdk.md
similarity index 100%
rename from packages/coding-agent/docs/sdk.md
rename to docs/sdk.md
diff --git a/packages/coding-agent/docs/session-operations-export-share-fork-resume.md b/docs/session-operations-export-share-fork-resume.md
similarity index 95%
rename from packages/coding-agent/docs/session-operations-export-share-fork-resume.md
rename to docs/session-operations-export-share-fork-resume.md
index 6ce199351..e7de14181 100644
--- a/packages/coding-agent/docs/session-operations-export-share-fork-resume.md
+++ b/docs/session-operations-export-share-fork-resume.md
@@ -4,12 +4,12 @@ This document describes operator-visible behavior for session export/share/fork/
 
 ## Implementation files
 
-- [`../src/modes/controllers/command-controller.ts`](../src/modes/controllers/command-controller.ts)
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`../src/session/session-manager.ts`](../src/session/session-manager.ts)
-- [`../src/export/html/index.ts`](../src/export/html/index.ts)
-- [`../src/export/custom-share.ts`](../src/export/custom-share.ts)
-- [`../src/main.ts`](../src/main.ts)
+- [`../src/modes/controllers/command-controller.ts`](../packages/coding-agent/src/modes/controllers/command-controller.ts)
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)
+- [`../src/export/html/index.ts`](../packages/coding-agent/src/export/html/index.ts)
+- [`../src/export/custom-share.ts`](../packages/coding-agent/src/export/custom-share.ts)
+- [`../src/main.ts`](../packages/coding-agent/src/main.ts)
 
 ## Operation matrix
 
diff --git a/packages/coding-agent/docs/session-switching-and-recent-listing.md b/docs/session-switching-and-recent-listing.md
similarity index 91%
rename from packages/coding-agent/docs/session-switching-and-recent-listing.md
rename to docs/session-switching-and-recent-listing.md
index 779433c6b..23bf92d68 100644
--- a/packages/coding-agent/docs/session-switching-and-recent-listing.md
+++ b/docs/session-switching-and-recent-listing.md
@@ -6,15 +6,15 @@ It focuses on current implementation behavior, including fallback paths and cave
 
 ## Implementation files
 
-- [`../src/session/session-manager.ts`](../src/session/session-manager.ts)
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`../src/cli/session-picker.ts`](../src/cli/session-picker.ts)
-- [`../src/modes/components/session-selector.ts`](../src/modes/components/session-selector.ts)
-- [`../src/modes/controllers/selector-controller.ts`](../src/modes/controllers/selector-controller.ts)
-- [`../src/main.ts`](../src/main.ts)
-- [`../src/sdk.ts`](../src/sdk.ts)
-- [`../src/modes/interactive-mode.ts`](../src/modes/interactive-mode.ts)
-- [`../src/modes/utils/ui-helpers.ts`](../src/modes/utils/ui-helpers.ts)
+- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`../src/cli/session-picker.ts`](../packages/coding-agent/src/cli/session-picker.ts)
+- [`../src/modes/components/session-selector.ts`](../packages/coding-agent/src/modes/components/session-selector.ts)
+- [`../src/modes/controllers/selector-controller.ts`](../packages/coding-agent/src/modes/controllers/selector-controller.ts)
+- [`../src/main.ts`](../packages/coding-agent/src/main.ts)
+- [`../src/sdk.ts`](../packages/coding-agent/src/sdk.ts)
+- [`../src/modes/interactive-mode.ts`](../packages/coding-agent/src/modes/interactive-mode.ts)
+- [`../src/modes/utils/ui-helpers.ts`](../packages/coding-agent/src/modes/utils/ui-helpers.ts)
 
 ## Recent-session discovery
 
diff --git a/packages/coding-agent/docs/session-tree-plan.md b/docs/session-tree-plan.md
similarity index 99%
rename from packages/coding-agent/docs/session-tree-plan.md
rename to docs/session-tree-plan.md
index 680f72ff1..df5f29f46 100644
--- a/packages/coding-agent/docs/session-tree-plan.md
+++ b/docs/session-tree-plan.md
@@ -1,6 +1,6 @@
 # Session tree architecture (current)
 
-Reference: [session.md](./session.md)
+Reference: [session.md](../docs/session.md)
 
 This document describes how session tree navigation works today: in-memory tree model, leaf movement rules, branching behavior, and extension/event integration.
 
diff --git a/packages/coding-agent/docs/session.md b/docs/session.md
similarity index 96%
rename from packages/coding-agent/docs/session.md
rename to docs/session.md
index 9c6375c42..96f3622fe 100644
--- a/packages/coding-agent/docs/session.md
+++ b/docs/session.md
@@ -17,11 +17,11 @@ Does not cover `/tree` UI rendering behavior beyond semantics that affect sessio
 
 ## Implementation Files
 
-- [`src/session/session-manager.ts`](../src/session/session-manager.ts)
-- [`src/session/messages.ts`](../src/session/messages.ts)
-- [`src/session/session-storage.ts`](../src/session/session-storage.ts)
-- [`src/session/history-storage.ts`](../src/session/history-storage.ts)
-- [`src/session/blob-store.ts`](../src/session/blob-store.ts)
+- [`src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)
+- [`src/session/messages.ts`](../packages/coding-agent/src/session/messages.ts)
+- [`src/session/session-storage.ts`](../packages/coding-agent/src/session/session-storage.ts)
+- [`src/session/history-storage.ts`](../packages/coding-agent/src/session/history-storage.ts)
+- [`src/session/blob-store.ts`](../packages/coding-agent/src/session/blob-store.ts)
 
 ## On-Disk Layout
 
diff --git a/packages/coding-agent/docs/skills.md b/docs/skills.md
similarity index 100%
rename from packages/coding-agent/docs/skills.md
rename to docs/skills.md
diff --git a/packages/coding-agent/docs/slash-command-internals.md b/docs/slash-command-internals.md
similarity index 88%
rename from packages/coding-agent/docs/slash-command-internals.md
rename to docs/slash-command-internals.md
index fea458fc0..585439c68 100644
--- a/packages/coding-agent/docs/slash-command-internals.md
+++ b/docs/slash-command-internals.md
@@ -4,19 +4,19 @@ This document describes how slash commands are discovered, deduplicated, surface
 
 ## Implementation files
 
-- [`src/extensibility/slash-commands.ts`](../src/extensibility/slash-commands.ts)
-- [`src/capability/slash-command.ts`](../src/capability/slash-command.ts)
-- [`src/discovery/builtin.ts`](../src/discovery/builtin.ts)
-- [`src/discovery/claude.ts`](../src/discovery/claude.ts)
-- [`src/discovery/codex.ts`](../src/discovery/codex.ts)
-- [`src/discovery/claude-plugins.ts`](../src/discovery/claude-plugins.ts)
-- [`src/capability/index.ts`](../src/capability/index.ts)
-- [`src/discovery/helpers.ts`](../src/discovery/helpers.ts)
-- [`src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`src/modes/interactive-mode.ts`](../src/modes/interactive-mode.ts)
-- [`src/modes/controllers/input-controller.ts`](../src/modes/controllers/input-controller.ts)
-- [`src/modes/utils/ui-helpers.ts`](../src/modes/utils/ui-helpers.ts)
-- [`src/modes/controllers/command-controller.ts`](../src/modes/controllers/command-controller.ts)
+- [`src/extensibility/slash-commands.ts`](../packages/coding-agent/src/extensibility/slash-commands.ts)
+- [`src/capability/slash-command.ts`](../packages/coding-agent/src/capability/slash-command.ts)
+- [`src/discovery/builtin.ts`](../packages/coding-agent/src/discovery/builtin.ts)
+- [`src/discovery/claude.ts`](../packages/coding-agent/src/discovery/claude.ts)
+- [`src/discovery/codex.ts`](../packages/coding-agent/src/discovery/codex.ts)
+- [`src/discovery/claude-plugins.ts`](../packages/coding-agent/src/discovery/claude-plugins.ts)
+- [`src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)
+- [`src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)
+- [`src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`src/modes/interactive-mode.ts`](../packages/coding-agent/src/modes/interactive-mode.ts)
+- [`src/modes/controllers/input-controller.ts`](../packages/coding-agent/src/modes/controllers/input-controller.ts)
+- [`src/modes/utils/ui-helpers.ts`](../packages/coding-agent/src/modes/utils/ui-helpers.ts)
+- [`src/modes/controllers/command-controller.ts`](../packages/coding-agent/src/modes/controllers/command-controller.ts)
 
 ## 1) Discovery model
 
diff --git a/packages/coding-agent/docs/task-agent-discovery.md b/docs/task-agent-discovery.md
similarity index 91%
rename from packages/coding-agent/docs/task-agent-discovery.md
rename to docs/task-agent-discovery.md
index 41088fccd..16c52e0f4 100644
--- a/packages/coding-agent/docs/task-agent-discovery.md
+++ b/docs/task-agent-discovery.md
@@ -6,16 +6,16 @@ It covers runtime behavior as implemented today, including precedence, invalid-d
 
 ## Implementation files
 
-- [`src/task/discovery.ts`](../src/task/discovery.ts)
-- [`src/task/agents.ts`](../src/task/agents.ts)
-- [`src/task/types.ts`](../src/task/types.ts)
-- [`src/task/index.ts`](../src/task/index.ts)
-- [`src/task/commands.ts`](../src/task/commands.ts)
-- [`src/prompts/agents/task.md`](../src/prompts/agents/task.md)
-- [`src/prompts/tools/task.md`](../src/prompts/tools/task.md)
-- [`src/discovery/helpers.ts`](../src/discovery/helpers.ts)
-- [`src/config.ts`](../src/config.ts)
-- [`src/task/executor.ts`](../src/task/executor.ts)
+- [`src/task/discovery.ts`](../packages/coding-agent/src/task/discovery.ts)
+- [`src/task/agents.ts`](../packages/coding-agent/src/task/agents.ts)
+- [`src/task/types.ts`](../packages/coding-agent/src/task/types.ts)
+- [`src/task/index.ts`](../packages/coding-agent/src/task/index.ts)
+- [`src/task/commands.ts`](../packages/coding-agent/src/task/commands.ts)
+- [`src/prompts/agents/task.md`](../packages/coding-agent/src/prompts/agents/task.md)
+- [`src/prompts/tools/task.md`](../packages/coding-agent/src/prompts/tools/task.md)
+- [`src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)
+- [`src/config.ts`](../packages/coding-agent/src/config.ts)
+- [`src/task/executor.ts`](../packages/coding-agent/src/task/executor.ts)
 
 ---
 
diff --git a/packages/coding-agent/docs/theme.md b/docs/theme.md
similarity index 100%
rename from packages/coding-agent/docs/theme.md
rename to docs/theme.md
diff --git a/packages/coding-agent/docs/tree.md b/docs/tree.md
similarity index 100%
rename from packages/coding-agent/docs/tree.md
rename to docs/tree.md
diff --git a/packages/coding-agent/docs/ttsr-injection-lifecycle.md b/docs/ttsr-injection-lifecycle.md
similarity index 86%
rename from packages/coding-agent/docs/ttsr-injection-lifecycle.md
rename to docs/ttsr-injection-lifecycle.md
index c175e4ffd..61fcc9461 100644
--- a/packages/coding-agent/docs/ttsr-injection-lifecycle.md
+++ b/docs/ttsr-injection-lifecycle.md
@@ -4,16 +4,16 @@ This document covers the current Time Traveling Stream Rules (TTSR) runtime path
 
 ## Implementation files
 
-- [`../src/sdk.ts`](../src/sdk.ts)
-- [`../src/export/ttsr.ts`](../src/export/ttsr.ts)
-- [`../src/session/agent-session.ts`](../src/session/agent-session.ts)
-- [`../src/session/session-manager.ts`](../src/session/session-manager.ts)
-- [`../src/prompts/system/ttsr-interrupt.md`](../src/prompts/system/ttsr-interrupt.md)
-- [`../src/capability/index.ts`](../src/capability/index.ts)
-- [`../src/extensibility/extensions/types.ts`](../src/extensibility/extensions/types.ts)
-- [`../src/extensibility/hooks/types.ts`](../src/extensibility/hooks/types.ts)
-- [`../src/extensibility/custom-tools/types.ts`](../src/extensibility/custom-tools/types.ts)
-- [`../src/modes/controllers/event-controller.ts`](../src/modes/controllers/event-controller.ts)
+- [`../src/sdk.ts`](../packages/coding-agent/src/sdk.ts)
+- [`../src/export/ttsr.ts`](../packages/coding-agent/src/export/ttsr.ts)
+- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)
+- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)
+- [`../src/prompts/system/ttsr-interrupt.md`](../packages/coding-agent/src/prompts/system/ttsr-interrupt.md)
+- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)
+- [`../src/extensibility/extensions/types.ts`](../packages/coding-agent/src/extensibility/extensions/types.ts)
+- [`../src/extensibility/hooks/types.ts`](../packages/coding-agent/src/extensibility/hooks/types.ts)
+- [`../src/extensibility/custom-tools/types.ts`](../packages/coding-agent/src/extensibility/custom-tools/types.ts)
+- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)
 
 ## 1. Discovery feed and rule registration
 
diff --git a/packages/coding-agent/docs/tui-runtime-internals.md b/docs/tui-runtime-internals.md
similarity index 91%
rename from packages/coding-agent/docs/tui-runtime-internals.md
rename to docs/tui-runtime-internals.md
index df391932b..284cc3fe4 100644
--- a/packages/coding-agent/docs/tui-runtime-internals.md
+++ b/docs/tui-runtime-internals.md
@@ -11,15 +11,15 @@ Boundary rule: the TUI engine is message-agnostic. It only knows `Component.rend
 
 ## Implementation files
 
-- [`../src/modes/interactive-mode.ts`](../src/modes/interactive-mode.ts)
-- [`../src/modes/controllers/event-controller.ts`](../src/modes/controllers/event-controller.ts)
-- [`../src/modes/controllers/input-controller.ts`](../src/modes/controllers/input-controller.ts)
-- [`../src/modes/components/custom-editor.ts`](../src/modes/components/custom-editor.ts)
-- [`../../tui/src/tui.ts`](../../tui/src/tui.ts)
-- [`../../tui/src/terminal.ts`](../../tui/src/terminal.ts)
-- [`../../tui/src/editor-component.ts`](../../tui/src/editor-component.ts)
-- [`../../tui/src/stdin-buffer.ts`](../../tui/src/stdin-buffer.ts)
-- [`../../tui/src/components/loader.ts`](../../tui/src/components/loader.ts)
+- [`../src/modes/interactive-mode.ts`](../packages/coding-agent/src/modes/interactive-mode.ts)
+- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)
+- [`../src/modes/controllers/input-controller.ts`](../packages/coding-agent/src/modes/controllers/input-controller.ts)
+- [`../src/modes/components/custom-editor.ts`](../packages/coding-agent/src/modes/components/custom-editor.ts)
+- [`../../tui/src/tui.ts`](../packages/tui/src/tui.ts)
+- [`../../tui/src/terminal.ts`](../packages/tui/src/terminal.ts)
+- [`../../tui/src/editor-component.ts`](../packages/tui/src/editor-component.ts)
+- [`../../tui/src/stdin-buffer.ts`](../packages/tui/src/stdin-buffer.ts)
+- [`../../tui/src/components/loader.ts`](../packages/tui/src/components/loader.ts)
 
 ## Boot and component tree assembly
 
diff --git a/packages/coding-agent/docs/tui.md b/docs/tui.md
similarity index 100%
rename from packages/coding-agent/docs/tui.md
rename to docs/tui.md