diff --git a/.dockerignore b/.dockerignore
index 24924a4bf..9f2cc3750 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -12,3 +12,12 @@ __pycache__
 web/.next
 web/node_modules
 web/.env
+
+# Documentation site dependencies and generated output
+docs/node_modules/
+docs/.next/
+docs/dist/
+docs/.fumapress/
+docs/.waku/
+docs/content/
+docs/public/
diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml
new file mode 100644
index 000000000..2aa5f0366
--- /dev/null
+++ b/.github/workflows/docs-tests.yml
@@ -0,0 +1,29 @@
+name: Docs tests
+
+on:
+  pull_request:
+    paths: ['docs/**', '.github/workflows/*docs*.yml', '.github/workflows/sync-*.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Fumapress docs build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
diff --git a/.github/workflows/sync-blog-articles.yml b/.github/workflows/sync-blog-articles.yml
new file mode 100644
index 000000000..c7ccf0668
--- /dev/null
+++ b/.github/workflows/sync-blog-articles.yml
@@ -0,0 +1,62 @@
+name: Sync LangBot Blog articles
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 2 * * *'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-langbot-blog-articles
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    if: github.repository == 'langbot-app/LangBot' && github.ref == 'refs/heads/main' && vars.DOCS_MIRROR_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Check out main
+        uses: actions/checkout@v5
+        with:
+          ref: main
+          fetch-depth: 0
+          # A PAT push triggers the mirror and Wiki workflows; GITHUB_TOKEN does not.
+          token: ${{ secrets.LANGBOT_WIKI_PUSH_TOKEN }}
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - run: npm ci
+      - name: Check out LangBot landing page
+        uses: actions/checkout@v5
+        with:
+          repository: langbot-app/langbot-landing-page
+          token: ${{ secrets.LANGBOT_WIKI_PUSH_TOKEN }}
+          path: .article-source
+          persist-credentials: false
+      - name: Synchronize articles and images
+        run: node scripts/sync-blog-articles.mjs --source ../.article-source
+      - name: Validate generated articles
+        run: |
+          node scripts/sync-blog-articles.mjs --check --source ../.article-source
+          node scripts/sync-blog-articles.mjs --check
+          npm test
+          npm run build
+      - name: Commit synchronized content
+        run: |
+          git add docs.json en/articles zh/articles ja/articles images/articles scripts/blog-articles-manifest.json
+          if git diff --cached --quiet; then
+            echo 'LangBot Blog articles are already synchronized.'
+            exit 0
+          fi
+          git config user.name 'langbot-docs-bot'
+          git config user.email 'actions@users.noreply.github.com'
+          git commit -m 'docs(articles): sync LangBot Blog'
+          git push origin HEAD:main
diff --git a/.github/workflows/sync-github-wiki.yml b/.github/workflows/sync-github-wiki.yml
new file mode 100644
index 000000000..03140de9e
--- /dev/null
+++ b/.github/workflows/sync-github-wiki.yml
@@ -0,0 +1,90 @@
+name: Sync GitHub Wiki
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/en/**"
+      - "docs/zh/**"
+      - "docs/ja/**"
+      - "docs/scripts/build-github-wiki.py"
+      - ".github/workflows/sync-github-wiki.yml"
+  pull_request:
+    paths:
+      - "docs/en/**"
+      - "docs/zh/**"
+      - "docs/ja/**"
+      - "docs/scripts/build-github-wiki.py"
+      - "docs/tests/test_build_github_wiki.py"
+      - ".github/workflows/sync-github-wiki.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-langbot-github-wiki
+  cancel-in-progress: false
+
+jobs:
+  build:
+    defaults:
+      run:
+        working-directory: docs
+    name: Build Wiki mirror
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Run converter tests
+        run: python -m unittest tests/test_build_github_wiki.py
+      - name: Build Wiki pages
+        run: python scripts/build-github-wiki.py --output dist/github-wiki
+      - name: Validate generated pages
+        run: |
+          test -f dist/github-wiki/Home.md
+          test -f dist/github-wiki/_Sidebar.md
+          test "$(find dist/github-wiki -maxdepth 1 -name '*.md' | wc -l)" -gt 250
+      - name: Upload generated Wiki
+        uses: actions/upload-artifact@v7
+        with:
+          name: github-wiki
+          path: docs/dist/github-wiki
+          if-no-files-found: error
+
+  sync:
+    name: Publish to LangBot Wiki
+    if: github.event_name != 'pull_request' && github.repository == 'langbot-app/LangBot' && github.ref == 'refs/heads/main' && vars.DOCS_MIRROR_ENABLED == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: github-wiki
+          path: generated
+      - name: Clone target Wiki
+        env:
+          WIKI_PUSH_TOKEN: ${{ secrets.LANGBOT_WIKI_PUSH_TOKEN }}
+        run: |
+          test -n "$WIKI_PUSH_TOKEN"
+          git clone "https://x-access-token:${WIKI_PUSH_TOKEN}@github.com/langbot-app/LangBot.wiki.git" target
+      - name: Replace and publish Wiki contents
+        env:
+          SOURCE_SHA: ${{ github.sha }}
+        run: |
+          find target -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+          cp -a generated/. target/
+          cd target
+          git add -A
+          if git diff --cached --quiet; then
+            echo "GitHub Wiki is already up to date."
+            exit 0
+          fi
+          git config user.name "langbot-docs-sync[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs: sync from LangBot/docs@${SOURCE_SHA::7}"
+          git push origin HEAD:master
diff --git a/.github/workflows/sync-landing-submodule.yml b/.github/workflows/sync-landing-submodule.yml
new file mode 100644
index 000000000..e4d736a93
--- /dev/null
+++ b/.github/workflows/sync-landing-submodule.yml
@@ -0,0 +1,44 @@
+name: Sync docs mirror and landing submodule
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', '.github/workflows/sync-landing-submodule.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-landing-docs-main
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    if: github.repository == 'langbot-app/LangBot' && github.ref == 'refs/heads/main' && vars.DOCS_MIRROR_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Test synchronization contracts
+        working-directory: docs
+        run: python3 -m unittest discover -s tests -p test_sync_landing_submodule.py -v
+      - name: Publish docs subtree (fast-forward only)
+        env:
+          GH_TOKEN: ${{ secrets.LANGBOT_WIKI_PUSH_TOKEN }}
+        run: |
+          gh auth setup-git
+          git remote add docs-mirror https://github.com/langbot-app/langbot-docs.git
+          git fetch docs-mirror main
+          docs_sha=$(git subtree split --prefix=docs)
+          git merge-base --is-ancestor docs-mirror/main "$docs_sha"
+          git push docs-mirror "$docs_sha:refs/heads/main"
+      - name: Update landing submodule and production fork
+        working-directory: docs
+        env:
+          GH_TOKEN: ${{ secrets.LANGBOT_WIKI_PUSH_TOKEN }}
+        run: python3 scripts/sync-landing-submodule.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 32f4cde68..9088647f6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -5,19 +5,23 @@ repos:
     hooks:
       # Run the linter of backend.
       - id: ruff
+        exclude: ^docs/
         args: [--fix]
       # Run the formatter of backend.
       - id: ruff-format
+        exclude: ^docs/
 
   - repo: local
     hooks:
       - id: prettier
+        exclude: ^docs/
         name: prettier
         entry: npx --prefix web prettier --write --ignore-unknown
         language: system
         types_or: [javascript, jsx, ts, tsx, css, scss]
 
       - id: lint-staged
+        exclude: ^docs/
         name: lint-staged
         entry: cd web && pnpm lint-staged
         language: system
diff --git a/AGENTS.md b/AGENTS.md
index 938eef4d9..3abf8259d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,12 +44,13 @@ Run tests in Linux to match CI; on Windows, use Linux containers through `wslc`
 
 ## Where to Look
 
+- Public documentation source: `docs/`; published at https://langbot.app/docs/. `langbot-app/langbot-docs` is a generated subtree mirror; edit here.
 - Architecture map: `ARCHITECTURE.md`.
 - Dev environment guide: https://langbot.app/docs/zh/develop/dev-config.
 - Plugin runtime / CLI / SDK debugging: https://langbot.app/docs/zh/develop/plugin-runtime.
-- API-key auth: `docs/API_KEY_AUTH.md`.
+- API-key auth: `dev-docs/API_KEY_AUTH.md`.
 - Service API CLI: [`langbot-cli`](https://github.com/langbot-app/langbot-cli) (`lbctl`) manages running Workspaces; it is separate from the SDK's `lbp` CLI.
-- Box deep-dive notes: `docs/review/box-architecture.md` and related files.
+- Box deep-dive notes: `dev-docs/review/box-architecture.md` and related files.
 - In-repo skills: `skills/` is the single source of truth for LangBot agent skills.
 - SDK repo: `../langbot-plugin-sdk/` when changing shared entities, plugin APIs, action protocol, `lbp rt`, or `lbp box`.
 
@@ -105,7 +106,7 @@ Config keys to verify in `data/config.yaml` / `src/langbot/templates/config.yaml
 - China-only adapters and configuration/field validation diagnostics do not require localization. An adapter also serving international users is not exempt merely because it supports a Chinese platform.
 - Preserve raw provider/plugin diagnostics, tracebacks, protocol values, and machine-readable error/status codes. Translate LangBot's own category or explanation around them; do not translate arbitrary errors with substring replacement. Plugin-authored messages remain the plugin's localization responsibility.
 - Keep changes small and maintainable. Reuse existing persistence and response boundaries; delete obsolete fields only after verifying they have no remaining readers, including compatibility paths.
-- When changing language behavior, verify catalog/placeholder parity, Workspace isolation and permissions, and Pipeline inheritance/custom overrides. Update affected configuration snapshots and API/MCP documentation. Implementation details and focused test locations: [Backend message language](docs/architecture/backend-i18n.md).
+- When changing language behavior, verify catalog/placeholder parity, Workspace isolation and permissions, and Pipeline inheritance/custom overrides. Update affected configuration snapshots and API/MCP documentation. Implementation details and focused test locations: [Backend message language](dev-docs/architecture/backend-i18n.md).
 
 ## Runtime Pitfalls
 
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 913fc982b..350968ea8 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -162,7 +162,7 @@ In this repo:
 - `pkg/plugin/handler.py` exposes LangBot actions to the runtime and calls runtime actions for plugin operations.
 - `pkg/provider/tools/loaders/plugin.py` exposes plugin Tool components to LLM runners.
 - Pipeline handlers emit SDK events such as normal-message events and prompt-processing events.
-- [Certified plugin policy](docs/architecture/certified-plugins.md) defines Core's archive-fact, admission, and tenant-log-visibility boundary; the SDK remains responsible for certificate verification.
+- [Certified plugin policy](dev-docs/architecture/certified-plugins.md) defines Core's archive-fact, admission, and tenant-log-visibility boundary; the SDK remains responsible for certificate verification.
 
 In `langbot-plugin-sdk`:
 
@@ -201,7 +201,7 @@ Box is the optional sandbox subsystem used by native execution tools, stdio MCP
 In this repo:
 
 - `pkg/box/service.py` is the application-facing facade for exec, sessions, managed processes, status, reconnects, quotas, generic mounts, and sandbox profiles.
-- [Outbox export failures](docs/BOX_OUTBOX_EXPORT.md) documents bounded reads, permission fallback, and cleanup after Runner acceptance.
+- [Outbox export failures](dev-docs/BOX_OUTBOX_EXPORT.md) documents bounded reads, permission fallback, and cleanup after Runner acceptance.
 - `pkg/box/connector.py` connects to the Box Runtime over stdio, Windows subprocess+WebSocket, or remote WebSocket.
 - `pkg/provider/tools/loaders/native.py` is the Core orchestration seam: the
   Skill loader supplies generic read-only mounts to Box execution. `mcp_stdio.py`
@@ -345,3 +345,7 @@ When one of these changes, update the others if the behavior or contract changed
 - Prefer small, explicit agent surfaces over exposing every internal API.
 - Treat cross-repo contracts with the SDK as public interfaces.
 - Test behavior at the narrowest useful layer first, then add integration/e2e coverage for runtime or platform changes.
+
+## Documentation repositories
+
+The public documentation site lives in `docs/` and is built with Node.js 24 and Fumapress. Internal design and review notes live in `dev-docs/`. The `langbot-app/langbot-docs` repository is a fast-forward subtree mirror for the landing site submodule and Context7. See `dev-docs/DOCS_MIGRATION.md` for publication and cutover details.
diff --git a/README.md b/README.md
index caf8a4a86..199ddbb8a 100644
--- a/README.md
+++ b/README.md
@@ -188,3 +188,5 @@ Thanks to all [contributors](https://github.com/langbot-app/LangBot/graphs/contr
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[Documentation source](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_CN.md b/README_CN.md
index 33b92645e..18a7d3426 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -212,3 +212,5 @@ LangBot **从设计上就对 Agent 友好** —— 你的编码 Agent（Claude C
 
 If you're a code agent based on LLM, you should read [AGENTS.md](AGENTS.md) to understand the project structure and development process before you start any development.
 -->
+
+[文档源码](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_ES.md b/README_ES.md
index d6749d5bb..f0fc684e9 100644
--- a/README_ES.md
+++ b/README_ES.md
@@ -186,3 +186,5 @@ Gracias a todos los [colaboradores](https://github.com/langbot-app/LangBot/graph
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[Código fuente de la documentación](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_FR.md b/README_FR.md
index 71cda2887..33c6bcc82 100644
--- a/README_FR.md
+++ b/README_FR.md
@@ -186,3 +186,5 @@ Merci à tous les [contributeurs](https://github.com/langbot-app/LangBot/graphs/
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[Sources de la documentation](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_JP.md b/README_JP.md
index d410e6efa..a76774e67 100644
--- a/README_JP.md
+++ b/README_JP.md
@@ -186,3 +186,5 @@ LangBot をより良くするために貢献してくださったすべての[
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[ドキュメントのソース](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_KO.md b/README_KO.md
index df06da4ab..bcc9c32f7 100644
--- a/README_KO.md
+++ b/README_KO.md
@@ -186,3 +186,5 @@ LangBot을 더 나은 프로젝트로 만들어 주신 모든 [기여자](https:
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[문서 소스](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_RU.md b/README_RU.md
index ca65b6556..a8fd8e65c 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -186,3 +186,5 @@ LangBot **дружелюбен к агентам по своей архитек
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[Исходники документации](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_TW.md b/README_TW.md
index 36d3c765a..0b9fc1ae6 100644
--- a/README_TW.md
+++ b/README_TW.md
@@ -204,3 +204,5 @@ LangBot **從設計上就對 Agent 友善** —— 你的編碼 Agent（Claude C
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[文件原始碼](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/README_VI.md b/README_VI.md
index 2a412d992..60f5354cc 100644
--- a/README_VI.md
+++ b/README_VI.md
@@ -186,3 +186,5 @@ Cảm ơn tất cả [người đóng góp](https://github.com/langbot-app/LangB
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
+
+[Mã nguồn tài liệu](https://github.com/langbot-app/LangBot/tree/main/docs) · [langbot-docs mirror](https://github.com/langbot-app/langbot-docs)
diff --git a/docs/API_KEY_AUTH.md b/dev-docs/API_KEY_AUTH.md
similarity index 100%
rename from docs/API_KEY_AUTH.md
rename to dev-docs/API_KEY_AUTH.md
diff --git a/docs/BOX_OUTBOX_EXPORT.md b/dev-docs/BOX_OUTBOX_EXPORT.md
similarity index 100%
rename from docs/BOX_OUTBOX_EXPORT.md
rename to dev-docs/BOX_OUTBOX_EXPORT.md
diff --git a/docs/CODEX_SUBSCRIPTION.md b/dev-docs/CODEX_SUBSCRIPTION.md
similarity index 100%
rename from docs/CODEX_SUBSCRIPTION.md
rename to dev-docs/CODEX_SUBSCRIPTION.md
diff --git a/docs/DEPENDENCY_CONTRACT_TESTS.md b/dev-docs/DEPENDENCY_CONTRACT_TESTS.md
similarity index 100%
rename from docs/DEPENDENCY_CONTRACT_TESTS.md
rename to dev-docs/DEPENDENCY_CONTRACT_TESTS.md
diff --git a/dev-docs/DOCS_MIGRATION.md b/dev-docs/DOCS_MIGRATION.md
new file mode 100644
index 000000000..1f361328e
--- /dev/null
+++ b/dev-docs/DOCS_MIGRATION.md
@@ -0,0 +1,61 @@
+# Documentation subtree and publication
+
+Public docs live in `LangBot/docs/`. The former internal `docs/` directory is
+`dev-docs/` (27 top-level entries, 87 tracked files at migration). Do not merge
+this migration using GitHub squash or rebase: use a merge commit to retain the
+subtree parent and original signed commits. Imported history is reachable through
+the subtree merge's second parent; `git log --follow docs/<file>` or
+`git log <imported-docs-sha>` exposes original authors. A plain path-limited log
+need not show pre-import paths.
+
+## Local checks
+
+With Node.js 24, run `npm ci`, `npm run typecheck`, `npm test`, and `npm run build`
+inside `docs/`. Output is `docs/dist/`. The site remains mounted at `/docs/` with
+canonical URL `https://langbot.app/docs`.
+
+## Cutover after the PR is reviewed and merged
+
+1. Pause the legacy `sync-blog-articles.yml` workflow in `langbot-app/langbot-docs`
+   and let any running writer finish. Freeze direct commits to that repository.
+   Pause its legacy Wiki and landing sync workflows too, avoiding duplicate
+   publishers while switching ownership. Do not push disabling commits directly
+   to the mirror.
+2. Fetch mirror `main` and confirm it is an ancestor of the new subtree split.
+   If it advanced since import, integrate it with an **unsquashed**
+   `git subtree pull --prefix=docs <mirror-url> main` through another reviewed PR
+   before cutover; reapply the inert mirror workflow files if necessary. Never
+   force-push or rewrite the mirror history.
+3. Verify `LANGBOT_WIKI_PUSH_TOKEN` is configured in LangBot with existing access
+   to the docs mirror, LangBot Wiki, landing upstream and production fork. The
+   blog job additionally needs to push to LangBot main and trigger workflows.
+   Repository workflow-file updates must be permitted by that token. Do not
+   weaken branch protection to accommodate this migration; use a separately
+   reviewed publication approach if the current token cannot perform the push.
+4. Set LangBot repository variable `DOCS_MIRROR_ENABLED=true`. Dispatch
+   `sync-landing-submodule.yml` on main. It fetches full main history, runs
+   `git subtree split --prefix=docs`, verifies the current mirror head is an
+   ancestor, pushes without force, then advances only landing's `docs` gitlink.
+   The first split replaces legacy mirror workflows with inert manual stubs.
+5. Dispatch `sync-github-wiki.yml` and `sync-blog-articles.yml` in LangBot.
+   The blog job now commits only docs article paths to LangBot main using the
+   dedicated token, so its push triggers the mirror and Wiki workflows.
+6. Confirm the `docs` gitlink in `langbot-app/langbot-landing-page`, then confirm
+   production fork `RockChinQ/LangBot-LandingPage-Vue` matches upstream. This is
+   the actual fork in the existing sync script (not the similarly named fork
+   mentioned in the original migration proposal). Observe Cloudflare Pages
+   deployment and check `https://langbot.app/docs/`, localized pages, assets,
+   sitemap and canonical URLs. Verify Wiki pages after publication.
+
+The four root workflows own publication and validation. Nested workflow stubs
+are intentionally inert when split into the mirror. No direct writes should be
+made to the mirror after cutover; all edits belong in LangBot `docs/`.
+
+`docs/context7.json` continues to identify `langbot-app/langbot-docs` because that
+repository remains available with the same tree layout and original history.
+Verify Context7 ingestion after the first mirror update; no library re-registration
+is needed merely to relocate the authoring source.
+
+Disable `DOCS_MIRROR_ENABLED` to pause publishers if cutover fails. A failed
+mirror ancestry check must be investigated and reconciled, never bypassed by a
+force push. Do not restore direct mirror writers while LangBot is authoritative.
diff --git a/docs/HTTP_BOT_ADAPTER_DESIGN.md b/dev-docs/HTTP_BOT_ADAPTER_DESIGN.md
similarity index 98%
rename from docs/HTTP_BOT_ADAPTER_DESIGN.md
rename to dev-docs/HTTP_BOT_ADAPTER_DESIGN.md
index d0826f2b5..9ef2cde25 100644
--- a/docs/HTTP_BOT_ADAPTER_DESIGN.md
+++ b/dev-docs/HTTP_BOT_ADAPTER_DESIGN.md
@@ -15,8 +15,8 @@
 > - `src/langbot/pkg/platform/sources/http_bot.py` — `HttpBotAdapter`
 > - `src/langbot/pkg/platform/sources/http_bot_signing.py` — HMAC helpers
 > - `src/langbot/pkg/platform/sources/http_bot.svg` — icon
-> - `docs/platforms/http-bot.md` — integration guide
-> - `docs/http-bot-openapi.json` — machine-readable contract
+> - `dev-docs/platforms/http-bot.md` — integration guide
+> - `dev-docs/http-bot-openapi.json` — machine-readable contract
 > - `examples/http-bot/` — Python + TypeScript reference clients
 >
 > **Final decisions (resolving the original open questions):**
@@ -489,13 +489,13 @@ time so replies always have a destination even if config later changes).
 The whole point of a standalone adapter is that **integrating is pleasant**. v1
 ships:
 
-1. **`docs/platforms/http-bot.md`** — task-oriented integration guide:
+1. **`dev-docs/platforms/http-bot.md`** — task-oriented integration guide:
    create the bot → copy inbound URL → set secret → stand up a callback
    endpoint → send first message → handle 1→M.
 2. **Copy-paste curl** for the first message (with a working signing one-liner).
 3. **Reference clients** (≤50 LOC each) in `examples/http-bot/`:
    `client.py` (push + a Flask/Quart callback receiver) and `client.ts`.
-4. **OpenAPI fragment** `docs/http-bot-openapi.json` describing inbound +
+4. **OpenAPI fragment** `dev-docs/http-bot-openapi.json` describing inbound +
    callback shapes, so integrators can codegen.
 5. **Local echo recipe**: a one-command callback server that prints every
    reply, so a developer sees N→1 and 1→M working in under five minutes.
@@ -542,7 +542,7 @@ curl -sS -X POST "$BOT" \
 | 2 | `HttpBotAdapter` (inbound verify, event build, outbound queue) | `platform/sources/http_bot.py` |
 | 3 | Signing helper module (shared) | `platform/sources/` or `utils/` |
 | 4 | i18n strings (en/zh/ja) | adapter yaml + web locale |
-| 5 | Integration docs `docs/platforms/http-bot.md` | `docs/` |
+| 5 | Integration docs `dev-docs/platforms/http-bot.md` | `docs/` |
 | 6 | OpenAPI fragment + reference clients | `docs/`, `examples/http-bot/` |
 | 7 | Tests: signature verify, N→1 aggregation, 1→M ordering, retry | `tests/` |
 | 8 | (opt) SSRF guard for callback_url | adapter |
diff --git a/docs/LLM_LATENCY_BENCHMARK.md b/dev-docs/LLM_LATENCY_BENCHMARK.md
similarity index 100%
rename from docs/LLM_LATENCY_BENCHMARK.md
rename to dev-docs/LLM_LATENCY_BENCHMARK.md
diff --git a/docs/LLM_REQUEST_E2E.md b/dev-docs/LLM_REQUEST_E2E.md
similarity index 100%
rename from docs/LLM_REQUEST_E2E.md
rename to dev-docs/LLM_REQUEST_E2E.md
diff --git a/docs/LLM_REQUEST_POLICY.md b/dev-docs/LLM_REQUEST_POLICY.md
similarity index 100%
rename from docs/LLM_REQUEST_POLICY.md
rename to dev-docs/LLM_REQUEST_POLICY.md
diff --git a/docs/MIGRATION_SUMMARY.md b/dev-docs/MIGRATION_SUMMARY.md
similarity index 100%
rename from docs/MIGRATION_SUMMARY.md
rename to dev-docs/MIGRATION_SUMMARY.md
diff --git a/docs/POSTGRES_CONTRACT_TESTS.md b/dev-docs/POSTGRES_CONTRACT_TESTS.md
similarity index 100%
rename from docs/POSTGRES_CONTRACT_TESTS.md
rename to dev-docs/POSTGRES_CONTRACT_TESTS.md
diff --git a/docs/PYPI_INSTALLATION.md b/dev-docs/PYPI_INSTALLATION.md
similarity index 100%
rename from docs/PYPI_INSTALLATION.md
rename to dev-docs/PYPI_INSTALLATION.md
diff --git a/docs/SEEKDB_INTEGRATION.md b/dev-docs/SEEKDB_INTEGRATION.md
similarity index 100%
rename from docs/SEEKDB_INTEGRATION.md
rename to dev-docs/SEEKDB_INTEGRATION.md
diff --git a/docs/TESTING_SUMMARY.md b/dev-docs/TESTING_SUMMARY.md
similarity index 100%
rename from docs/TESTING_SUMMARY.md
rename to dev-docs/TESTING_SUMMARY.md
diff --git a/docs/VALKEY_SEARCH_INTEGRATION.md b/dev-docs/VALKEY_SEARCH_INTEGRATION.md
similarity index 100%
rename from docs/VALKEY_SEARCH_INTEGRATION.md
rename to dev-docs/VALKEY_SEARCH_INTEGRATION.md
diff --git a/docs/WEBSOCKET_README.md b/dev-docs/WEBSOCKET_README.md
similarity index 100%
rename from docs/WEBSOCKET_README.md
rename to dev-docs/WEBSOCKET_README.md
diff --git a/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md b/dev-docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
similarity index 100%
rename from docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
rename to dev-docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
diff --git a/docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md b/dev-docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md
similarity index 100%
rename from docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md
rename to dev-docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md
diff --git a/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md b/dev-docs/agent-runner-pluginization/EVENT_BASED_AGENT.md
similarity index 100%
rename from docs/agent-runner-pluginization/EVENT_BASED_AGENT.md
rename to dev-docs/agent-runner-pluginization/EVENT_BASED_AGENT.md
diff --git a/docs/agent-runner-pluginization/EVENT_DEBUG_E2E_2026-09-05.md b/dev-docs/agent-runner-pluginization/EVENT_DEBUG_E2E_2026-09-05.md
similarity index 100%
rename from docs/agent-runner-pluginization/EVENT_DEBUG_E2E_2026-09-05.md
rename to dev-docs/agent-runner-pluginization/EVENT_DEBUG_E2E_2026-09-05.md
diff --git a/docs/agent-runner-pluginization/EVENT_DEBUG_FULL_QA_2026-09-05.md b/dev-docs/agent-runner-pluginization/EVENT_DEBUG_FULL_QA_2026-09-05.md
similarity index 100%
rename from docs/agent-runner-pluginization/EVENT_DEBUG_FULL_QA_2026-09-05.md
rename to dev-docs/agent-runner-pluginization/EVENT_DEBUG_FULL_QA_2026-09-05.md
diff --git a/docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md b/dev-docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md
similarity index 100%
rename from docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md
rename to dev-docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md
diff --git a/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md b/dev-docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
similarity index 100%
rename from docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
rename to dev-docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
diff --git a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md b/dev-docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
similarity index 100%
rename from docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
rename to dev-docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
diff --git a/docs/agent-runner-pluginization/PLATFORM_ACTION_TOOLS.md b/dev-docs/agent-runner-pluginization/PLATFORM_ACTION_TOOLS.md
similarity index 100%
rename from docs/agent-runner-pluginization/PLATFORM_ACTION_TOOLS.md
rename to dev-docs/agent-runner-pluginization/PLATFORM_ACTION_TOOLS.md
diff --git a/docs/agent-runner-pluginization/PROTOCOL_V1.md b/dev-docs/agent-runner-pluginization/PROTOCOL_V1.md
similarity index 100%
rename from docs/agent-runner-pluginization/PROTOCOL_V1.md
rename to dev-docs/agent-runner-pluginization/PROTOCOL_V1.md
diff --git a/docs/agent-runner-pluginization/README.md b/dev-docs/agent-runner-pluginization/README.md
similarity index 100%
rename from docs/agent-runner-pluginization/README.md
rename to dev-docs/agent-runner-pluginization/README.md
diff --git a/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md b/dev-docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md
similarity index 100%
rename from docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md
rename to dev-docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md
diff --git a/docs/agent-runner-pluginization/RUN_STEERING_AND_CHECKPOINT.md b/dev-docs/agent-runner-pluginization/RUN_STEERING_AND_CHECKPOINT.md
similarity index 100%
rename from docs/agent-runner-pluginization/RUN_STEERING_AND_CHECKPOINT.md
rename to dev-docs/agent-runner-pluginization/RUN_STEERING_AND_CHECKPOINT.md
diff --git a/docs/agent-runner-pluginization/SECURITY_HARDENING.md b/dev-docs/agent-runner-pluginization/SECURITY_HARDENING.md
similarity index 100%
rename from docs/agent-runner-pluginization/SECURITY_HARDENING.md
rename to dev-docs/agent-runner-pluginization/SECURITY_HARDENING.md
diff --git a/docs/agent-runner-pluginization/STATUS.md b/dev-docs/agent-runner-pluginization/STATUS.md
similarity index 97%
rename from docs/agent-runner-pluginization/STATUS.md
rename to dev-docs/agent-runner-pluginization/STATUS.md
index 4d6686e2b..70acf22ae 100644
--- a/docs/agent-runner-pluginization/STATUS.md
+++ b/dev-docs/agent-runner-pluginization/STATUS.md
@@ -1,6 +1,6 @@
 # Runner Pluginization Status
 
-本文档是 `docs/agent-runner-pluginization/` 的状态事实源。协议 schema 仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试步骤以 [RUNNER_QA_GUIDE.md](./RUNNER_QA_GUIDE.md) 为准；安全发布门槛以 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 为准。
+本文档是 `dev-docs/agent-runner-pluginization/` 的状态事实源。协议 schema 仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试步骤以 [RUNNER_QA_GUIDE.md](./RUNNER_QA_GUIDE.md) 为准；安全发布门槛以 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 为准。
 
 状态快照日期：2026-09-05。代码基线为 LangBot `dev/4.11.x` / `a4d36aa2d` 和 SDK `dev/4.11.x` / `f1da058`；本文是本地检视快照，不代表远端最新状态或正式发布批准。
 
diff --git a/docs/agent-runner-pluginization/eba-productization-release.md b/dev-docs/agent-runner-pluginization/eba-productization-release.md
similarity index 100%
rename from docs/agent-runner-pluginization/eba-productization-release.md
rename to dev-docs/agent-runner-pluginization/eba-productization-release.md
diff --git a/docs/architecture/backend-i18n.md b/dev-docs/architecture/backend-i18n.md
similarity index 100%
rename from docs/architecture/backend-i18n.md
rename to dev-docs/architecture/backend-i18n.md
diff --git a/docs/architecture/certified-plugins.md b/dev-docs/architecture/certified-plugins.md
similarity index 100%
rename from docs/architecture/certified-plugins.md
rename to dev-docs/architecture/certified-plugins.md
diff --git a/docs/architecture/cloud-plan-revisions.md b/dev-docs/architecture/cloud-plan-revisions.md
similarity index 100%
rename from docs/architecture/cloud-plan-revisions.md
rename to dev-docs/architecture/cloud-plan-revisions.md
diff --git a/docs/assets/pr-2336/after.png b/dev-docs/assets/pr-2336/after.png
similarity index 100%
rename from docs/assets/pr-2336/after.png
rename to dev-docs/assets/pr-2336/after.png
diff --git a/docs/assets/pr-2336/before.png b/dev-docs/assets/pr-2336/before.png
similarity index 100%
rename from docs/assets/pr-2336/before.png
rename to dev-docs/assets/pr-2336/before.png
diff --git a/docs/assets/pr-2363/oauth-required-state.png b/dev-docs/assets/pr-2363/oauth-required-state.png
similarity index 100%
rename from docs/assets/pr-2363/oauth-required-state.png
rename to dev-docs/assets/pr-2363/oauth-required-state.png
diff --git a/docs/event-based-agents/00-overview.md b/dev-docs/event-based-agents/00-overview.md
similarity index 100%
rename from docs/event-based-agents/00-overview.md
rename to dev-docs/event-based-agents/00-overview.md
diff --git a/docs/event-based-agents/01-event-system.md b/dev-docs/event-based-agents/01-event-system.md
similarity index 100%
rename from docs/event-based-agents/01-event-system.md
rename to dev-docs/event-based-agents/01-event-system.md
diff --git a/docs/event-based-agents/02-platform-api.md b/dev-docs/event-based-agents/02-platform-api.md
similarity index 100%
rename from docs/event-based-agents/02-platform-api.md
rename to dev-docs/event-based-agents/02-platform-api.md
diff --git a/docs/event-based-agents/03-adapter-structure.md b/dev-docs/event-based-agents/03-adapter-structure.md
similarity index 100%
rename from docs/event-based-agents/03-adapter-structure.md
rename to dev-docs/event-based-agents/03-adapter-structure.md
diff --git a/docs/event-based-agents/04-event-routing.md b/dev-docs/event-based-agents/04-event-routing.md
similarity index 100%
rename from docs/event-based-agents/04-event-routing.md
rename to dev-docs/event-based-agents/04-event-routing.md
diff --git a/docs/event-based-agents/05-plugin-sdk.md b/dev-docs/event-based-agents/05-plugin-sdk.md
similarity index 100%
rename from docs/event-based-agents/05-plugin-sdk.md
rename to dev-docs/event-based-agents/05-plugin-sdk.md
diff --git a/docs/event-based-agents/06-migration-plan.md b/dev-docs/event-based-agents/06-migration-plan.md
similarity index 100%
rename from docs/event-based-agents/06-migration-plan.md
rename to dev-docs/event-based-agents/06-migration-plan.md
diff --git a/docs/event-based-agents/07-agent-orchestration.md b/dev-docs/event-based-agents/07-agent-orchestration.md
similarity index 100%
rename from docs/event-based-agents/07-agent-orchestration.md
rename to dev-docs/event-based-agents/07-agent-orchestration.md
diff --git a/docs/event-based-agents/08-agent-page-and-event-orchestration.md b/dev-docs/event-based-agents/08-agent-page-and-event-orchestration.md
similarity index 100%
rename from docs/event-based-agents/08-agent-page-and-event-orchestration.md
rename to dev-docs/event-based-agents/08-agent-page-and-event-orchestration.md
diff --git a/docs/event-based-agents/09-event-processors.md b/dev-docs/event-based-agents/09-event-processors.md
similarity index 100%
rename from docs/event-based-agents/09-event-processors.md
rename to dev-docs/event-based-agents/09-event-processors.md
diff --git a/docs/event-based-agents/adapters/00-index.md b/dev-docs/event-based-agents/adapters/00-index.md
similarity index 100%
rename from docs/event-based-agents/adapters/00-index.md
rename to dev-docs/event-based-agents/adapters/00-index.md
diff --git a/docs/event-based-agents/adapters/acceptance-checklist.md b/dev-docs/event-based-agents/adapters/acceptance-checklist.md
similarity index 100%
rename from docs/event-based-agents/adapters/acceptance-checklist.md
rename to dev-docs/event-based-agents/adapters/acceptance-checklist.md
diff --git a/docs/event-based-agents/adapters/acceptance-report.md b/dev-docs/event-based-agents/adapters/acceptance-report.md
similarity index 100%
rename from docs/event-based-agents/adapters/acceptance-report.md
rename to dev-docs/event-based-agents/adapters/acceptance-report.md
diff --git a/docs/event-based-agents/adapters/aiocqhttp.md b/dev-docs/event-based-agents/adapters/aiocqhttp.md
similarity index 100%
rename from docs/event-based-agents/adapters/aiocqhttp.md
rename to dev-docs/event-based-agents/adapters/aiocqhttp.md
diff --git a/docs/event-based-agents/adapters/dingtalk.md b/dev-docs/event-based-agents/adapters/dingtalk.md
similarity index 100%
rename from docs/event-based-agents/adapters/dingtalk.md
rename to dev-docs/event-based-agents/adapters/dingtalk.md
diff --git a/docs/event-based-agents/adapters/discord.md b/dev-docs/event-based-agents/adapters/discord.md
similarity index 100%
rename from docs/event-based-agents/adapters/discord.md
rename to dev-docs/event-based-agents/adapters/discord.md
diff --git a/docs/event-based-agents/adapters/kook.md b/dev-docs/event-based-agents/adapters/kook.md
similarity index 100%
rename from docs/event-based-agents/adapters/kook.md
rename to dev-docs/event-based-agents/adapters/kook.md
diff --git a/docs/event-based-agents/adapters/lark.md b/dev-docs/event-based-agents/adapters/lark.md
similarity index 100%
rename from docs/event-based-agents/adapters/lark.md
rename to dev-docs/event-based-agents/adapters/lark.md
diff --git a/docs/event-based-agents/adapters/officialaccount.md b/dev-docs/event-based-agents/adapters/officialaccount.md
similarity index 100%
rename from docs/event-based-agents/adapters/officialaccount.md
rename to dev-docs/event-based-agents/adapters/officialaccount.md
diff --git a/docs/event-based-agents/adapters/qqofficial.md b/dev-docs/event-based-agents/adapters/qqofficial.md
similarity index 100%
rename from docs/event-based-agents/adapters/qqofficial.md
rename to dev-docs/event-based-agents/adapters/qqofficial.md
diff --git a/docs/event-based-agents/adapters/slack.md b/dev-docs/event-based-agents/adapters/slack.md
similarity index 100%
rename from docs/event-based-agents/adapters/slack.md
rename to dev-docs/event-based-agents/adapters/slack.md
diff --git a/docs/event-based-agents/adapters/telegram.md b/dev-docs/event-based-agents/adapters/telegram.md
similarity index 100%
rename from docs/event-based-agents/adapters/telegram.md
rename to dev-docs/event-based-agents/adapters/telegram.md
diff --git a/docs/event-based-agents/adapters/wecom.md b/dev-docs/event-based-agents/adapters/wecom.md
similarity index 100%
rename from docs/event-based-agents/adapters/wecom.md
rename to dev-docs/event-based-agents/adapters/wecom.md
diff --git a/docs/event-based-agents/adapters/wecombot.md b/dev-docs/event-based-agents/adapters/wecombot.md
similarity index 100%
rename from docs/event-based-agents/adapters/wecombot.md
rename to dev-docs/event-based-agents/adapters/wecombot.md
diff --git a/docs/event-based-agents/adapters/wecomcs.md b/dev-docs/event-based-agents/adapters/wecomcs.md
similarity index 100%
rename from docs/event-based-agents/adapters/wecomcs.md
rename to dev-docs/event-based-agents/adapters/wecomcs.md
diff --git a/docs/http-bot-openapi.json b/dev-docs/http-bot-openapi.json
similarity index 100%
rename from docs/http-bot-openapi.json
rename to dev-docs/http-bot-openapi.json
diff --git a/docs/llm-latency-2026-10-15.json b/dev-docs/llm-latency-2026-10-15.json
similarity index 100%
rename from docs/llm-latency-2026-10-15.json
rename to dev-docs/llm-latency-2026-10-15.json
diff --git a/docs/multi-tenant/DATABASE_MIGRATION_GUIDE.md b/dev-docs/multi-tenant/DATABASE_MIGRATION_GUIDE.md
similarity index 100%
rename from docs/multi-tenant/DATABASE_MIGRATION_GUIDE.md
rename to dev-docs/multi-tenant/DATABASE_MIGRATION_GUIDE.md
diff --git a/docs/multi-tenant/cloud-runtime-soak-gate.md b/dev-docs/multi-tenant/cloud-runtime-soak-gate.md
similarity index 100%
rename from docs/multi-tenant/cloud-runtime-soak-gate.md
rename to dev-docs/multi-tenant/cloud-runtime-soak-gate.md
diff --git a/docs/multi-tenant/cloud-v2-pending-verification.md b/dev-docs/multi-tenant/cloud-v2-pending-verification.md
similarity index 100%
rename from docs/multi-tenant/cloud-v2-pending-verification.md
rename to dev-docs/multi-tenant/cloud-v2-pending-verification.md
diff --git a/docs/multi-tenant/implementation-checklist.md b/dev-docs/multi-tenant/implementation-checklist.md
similarity index 100%
rename from docs/multi-tenant/implementation-checklist.md
rename to dev-docs/multi-tenant/implementation-checklist.md
diff --git a/docs/multi-tenant/implementation-decisions.md b/dev-docs/multi-tenant/implementation-decisions.md
similarity index 100%
rename from docs/multi-tenant/implementation-decisions.md
rename to dev-docs/multi-tenant/implementation-decisions.md
diff --git a/docs/multi-tenant/pending-architecture-decisions.md b/dev-docs/multi-tenant/pending-architecture-decisions.md
similarity index 100%
rename from docs/multi-tenant/pending-architecture-decisions.md
rename to dev-docs/multi-tenant/pending-architecture-decisions.md
diff --git a/docs/multi-tenant/runtime-resource-audit-2026-07-28.md b/dev-docs/multi-tenant/runtime-resource-audit-2026-07-28.md
similarity index 100%
rename from docs/multi-tenant/runtime-resource-audit-2026-07-28.md
rename to dev-docs/multi-tenant/runtime-resource-audit-2026-07-28.md
diff --git a/docs/multi-tenant/verification-report.md b/dev-docs/multi-tenant/verification-report.md
similarity index 100%
rename from docs/multi-tenant/verification-report.md
rename to dev-docs/multi-tenant/verification-report.md
diff --git a/docs/multi-tenant/workspace-multi-user-architecture.md b/dev-docs/multi-tenant/workspace-multi-user-architecture.md
similarity index 100%
rename from docs/multi-tenant/workspace-multi-user-architecture.md
rename to dev-docs/multi-tenant/workspace-multi-user-architecture.md
diff --git a/docs/pipeline-migration-config-map.zh-CN.md b/dev-docs/pipeline-migration-config-map.zh-CN.md
similarity index 100%
rename from docs/pipeline-migration-config-map.zh-CN.md
rename to dev-docs/pipeline-migration-config-map.zh-CN.md
diff --git a/docs/platforms/http-bot.md b/dev-docs/platforms/http-bot.md
similarity index 99%
rename from docs/platforms/http-bot.md
rename to dev-docs/platforms/http-bot.md
index 94117bca2..aa07e162f 100644
--- a/docs/platforms/http-bot.md
+++ b/dev-docs/platforms/http-bot.md
@@ -248,7 +248,7 @@ Watch Terminal 1 print each reply part (`[part ]` / `[FINAL]`) with its
 sequence number — that's 1→M working, signatures verified.
 
 A machine-readable contract is in
-[`docs/http-bot-openapi.json`](../http-bot-openapi.json).
+[`dev-docs/http-bot-openapi.json`](../http-bot-openapi.json).
 
 ---
 
diff --git a/docs/qa-message-routing-acceptance.md b/dev-docs/qa-message-routing-acceptance.md
similarity index 100%
rename from docs/qa-message-routing-acceptance.md
rename to dev-docs/qa-message-routing-acceptance.md
diff --git a/docs/review/box-architecture.md b/dev-docs/review/box-architecture.md
similarity index 100%
rename from docs/review/box-architecture.md
rename to dev-docs/review/box-architecture.md
diff --git a/docs/review/box-issues.md b/dev-docs/review/box-issues.md
similarity index 100%
rename from docs/review/box-issues.md
rename to dev-docs/review/box-issues.md
diff --git a/docs/review/box-session-scope.md b/dev-docs/review/box-session-scope.md
similarity index 100%
rename from docs/review/box-session-scope.md
rename to dev-docs/review/box-session-scope.md
diff --git a/docs/review/box-test-coverage.md b/dev-docs/review/box-test-coverage.md
similarity index 100%
rename from docs/review/box-test-coverage.md
rename to dev-docs/review/box-test-coverage.md
diff --git a/docs/review/box-tob-analysis.md b/dev-docs/review/box-tob-analysis.md
similarity index 100%
rename from docs/review/box-tob-analysis.md
rename to dev-docs/review/box-tob-analysis.md
diff --git a/docs/review/box-vs-plugin-runtime.md b/dev-docs/review/box-vs-plugin-runtime.md
similarity index 100%
rename from docs/review/box-vs-plugin-runtime.md
rename to dev-docs/review/box-vs-plugin-runtime.md
diff --git a/docs/review/mcp-resources-pr-2215-review.md b/dev-docs/review/mcp-resources-pr-2215-review.md
similarity index 100%
rename from docs/review/mcp-resources-pr-2215-review.md
rename to dev-docs/review/mcp-resources-pr-2215-review.md
diff --git a/docs/review/model-reasoning-control-design.md b/dev-docs/review/model-reasoning-control-design.md
similarity index 100%
rename from docs/review/model-reasoning-control-design.md
rename to dev-docs/review/model-reasoning-control-design.md
diff --git a/docs/review/omni-mainline-sync-2026-09-10.md b/dev-docs/review/omni-mainline-sync-2026-09-10.md
similarity index 100%
rename from docs/review/omni-mainline-sync-2026-09-10.md
rename to dev-docs/review/omni-mainline-sync-2026-09-10.md
diff --git a/docs/review/telegram-4.11-acceptance.md b/dev-docs/review/telegram-4.11-acceptance.md
similarity index 100%
rename from docs/review/telegram-4.11-acceptance.md
rename to dev-docs/review/telegram-4.11-acceptance.md
diff --git a/docs/service-api-openapi.json b/dev-docs/service-api-openapi.json
similarity index 100%
rename from docs/service-api-openapi.json
rename to dev-docs/service-api-openapi.json
diff --git a/src/langbot/pkg/platform/sources/http_bot.py b/src/langbot/pkg/platform/sources/http_bot.py
index c7c7652a6..72c99d1c8 100644
--- a/src/langbot/pkg/platform/sources/http_bot.py
+++ b/src/langbot/pkg/platform/sources/http_bot.py
@@ -22,7 +22,7 @@ Design notes:
   (``pkg/api/http/controller/groups/webhooks.py``) calls
   ``handle_unified_webhook`` on this adapter.
 
-See docs/platforms/http-bot.md for the full integration guide.
+See dev-docs/platforms/http-bot.md for the full integration guide.
 """
 
 from __future__ import annotations
diff --git a/src/langbot/pkg/platform/sources/http_bot_signing.py b/src/langbot/pkg/platform/sources/http_bot_signing.py
index 0578721c4..035d34ee1 100644
--- a/src/langbot/pkg/platform/sources/http_bot_signing.py
+++ b/src/langbot/pkg/platform/sources/http_bot_signing.py
@@ -7,7 +7,7 @@ A dependency-free, symmetric HMAC-SHA256 scheme used in *both* directions:
 
 Inbound requests are signed by the caller and verified here; outbound
 callbacks are signed here and verified by the caller. The scheme is trivial to
-reproduce in any language (see docs/platforms/http-bot.md for JS/curl).
+reproduce in any language (see dev-docs/platforms/http-bot.md for JS/curl).
 """
 
 from __future__ import annotations
diff --git a/src/langbot/pkg/vector/vdbs/valkey_search.py b/src/langbot/pkg/vector/vdbs/valkey_search.py
index dd50e4189..b1f9699f8 100644
--- a/src/langbot/pkg/vector/vdbs/valkey_search.py
+++ b/src/langbot/pkg/vector/vdbs/valkey_search.py
@@ -493,7 +493,7 @@ class ValkeySearchVectorDatabase(VectorDatabase):
             self.ap.logger.warning(
                 'Valkey Search backend does not honor vector_weight: hybrid search uses '
                 'filter-then-KNN without weighted score fusion. The vector_weight value '
-                'is ignored. See docs/VALKEY_SEARCH_INTEGRATION.md.'
+                'is ignored. See dev-docs/VALKEY_SEARCH_INTEGRATION.md.'
             )
             self._vector_weight_warned = True
 
diff --git a/tests/README.md b/tests/README.md
index f3fd35f44..4f5205313 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -178,7 +178,7 @@ The test suite uses a centralized fixture system that provides:
 3. **Coverage**: Tests cover happy paths, edge cases, and error conditions
 4. **Extensibility**: Easy to add new tests by reusing existing fixtures
 
-See [provisioned dependency contracts](../docs/DEPENDENCY_CONTRACT_TESTS.md) for
+See [provisioned dependency contracts](../dev-docs/DEPENDENCY_CONTRACT_TESTS.md) for
 the real compiled CLI, pinned official plugin identity helpers, and embedded
 SeekDB CI jobs, including local prerequisites and verification boundaries.
 
@@ -315,7 +315,7 @@ Note: PostgreSQL tests are **not** included in fast integration gate because the
 
 A separate **PostgreSQL Contract Tests** job provisions a disposable database for
 pipeline admission, RAG recovery, migration convergence, and timestamp/lease contracts.
-See [the PostgreSQL contract guide](../docs/POSTGRES_CONTRACT_TESTS.md) for scope,
+See [the PostgreSQL contract guide](../dev-docs/POSTGRES_CONTRACT_TESTS.md) for scope,
 local commands, and remaining optional prerequisites.
 
 CI workflow `.github/workflows/test-migrations.yml` runs: