docs: adopt four-bucket docs layout and progressive AGENTS index

CONTRIBUTING.md

@@ -4,6 +4,10 @@
 
 Thanks for your interest in BitFun! BitFun is a multi-platform AI programming environment powered by Rust and TypeScript, with shared core logic across Desktop/CLI/Server. This guide explains how to contribute effectively.
 
+This file is the **human contribution entry**: how to set up, open PRs, and what we welcome.
+
+**Code-change norms, architecture, and verification** live in [`AGENTS.md`](AGENTS.md) — do not treat this file as a third command or verification encyclopedia.
+
 ## Code of Conduct
 
 Be respectful, kind, and constructive. We welcome contributors of all backgrounds and experience levels.
@@ -72,7 +76,7 @@ pnpm run e2e:test
 
 > **`desktop:dev` vs `desktop:preview:debug`**: `desktop:dev` runs `tauri dev`, which provides **full hot-reload** — frontend changes apply instantly via Vite HMR, and Rust/backend changes trigger an incremental rebuild followed by an automatic app restart. This is the recommended workflow for active development. `desktop:preview:debug` launches a pre-built debug binary alongside a Vite dev server; frontend edits still get HMR, but **Rust-side changes are not auto-rebuilt** — you must stop and re-run the command (or use `--force-rebuild`). Use `desktop:preview:debug` when you only need to iterate on frontend code or want a faster cold-start without waiting for `tauri dev` initialization.
 
-> For the full script list, see [`package.json`](package.json). For agent-specific commands, verification, and architecture rules, see [`AGENTS.md`](AGENTS.md).
+> For the full script list, see [`package.json`](package.json) and [`docs/guideline/common-commands.md`](docs/guideline/common-commands.md). After changes, pick the smallest check from [`docs/guideline/verification.md`](docs/guideline/verification.md). For agent-specific commands, verification, and architecture rules, see [`AGENTS.md`](AGENTS.md). Docs placement: [`docs/guideline/docs-governance.md`](docs/guideline/docs-governance.md).
 
 ### Desktop debugging tools
 
@@ -166,7 +170,7 @@ Common local checks:
 | Repository metadata or GitHub config | `pnpm run check:repo-hygiene && pnpm run check:github-config && git diff --check` |
 | Frontend runtime or UI | `pnpm run type-check:web`, plus the nearest focused test when behavior changed |
 | Mobile web | `pnpm --dir src/mobile-web run type-check` |
-| Rust shared runtime or services | `cargo check --workspace`, plus a focused `cargo test` when behavior changed |
+| Rust shared runtime or services | Nearest module `AGENTS.md`; otherwise `cargo check -p <owning-package>` with the minimum feature set, plus a focused `cargo test` when behavior changed |
 | Desktop/Tauri integration | `cargo check -p bitfun-desktop` |
 | i18n resources or contract | use the matching i18n row in `AGENTS.md` |
 

CONTRIBUTING_CN.md

@@ -4,6 +4,10 @@
 
 感谢你对 BitFun 的兴趣！BitFun 是一个由 Rust 与 TypeScript 驱动的多端 AI 编程环境，桌面端/CLI/Server 共享核心逻辑。本指南说明如何高效参与贡献。
 
+本文是**人类贡献入口**：如何搭建、如何开 PR、我们欢迎什么。
+
+**改代码规范、架构与验证**见 [`AGENTS.md`](AGENTS.md)——不要把本文当成第三套命令或验证百科。
+
 ## 行为准则
 
 请保持尊重、友善与建设性沟通。我们欢迎不同背景与经验的贡献者。
@@ -69,7 +73,7 @@ pnpm run e2e:test
 
 > **`desktop:dev` 与 `desktop:preview:debug` 的区别**：`desktop:dev` 运行 `tauri dev`，提供**完整热更新** — 前端改动通过 Vite HMR 即时生效，Rust/后端改动会触发增量重编译并自动重启应用，是日常开发的首选方式。`desktop:preview:debug` 启动预构建的 debug 二进制和 Vite dev server；前端编辑仍可 HMR，但 **Rust 侧改动不会自动重编译** — 需要手动停止并重新运行命令（或使用 `--force-rebuild`）。适合仅需迭代前端代码、或希望跳过 `tauri dev` 初始化以更快冷启动的场景。
 
-> 完整脚本列表见 [`package.json`](package.json)。agent 专用命令、验证与架构规则见 [`AGENTS.md`](AGENTS.md)。
+> 完整脚本列表见 [`package.json`](package.json) 与 [`docs/guideline/common-commands.md`](docs/guideline/common-commands.md)。改完后从 [`docs/guideline/verification.md`](docs/guideline/verification.md) 选最小检查。agent 专用命令、验证与架构规则见 [`AGENTS.md`](AGENTS.md)。文档放置：[`docs/guideline/docs-governance.md`](docs/guideline/docs-governance.md)。
 
 ### 桌面端调试工具
 
@@ -154,7 +158,7 @@ UI 改动请附前后对比截图或短录屏，方便快速评审。
 | 仓库元信息或 GitHub 配置 | `pnpm run check:repo-hygiene && pnpm run check:github-config && git diff --check` |
 | 前端运行时或 UI | `pnpm run type-check:web`；行为变化时再加最近的 focused test |
 | Mobile web | `pnpm --dir src/mobile-web run type-check` |
-| Rust 共享 runtime 或 services | `cargo check --workspace`；行为变化时再加 focused `cargo test` |
+| Rust 共享 runtime 或 services | 先用最近模块 `AGENTS.md` 的命令；若未提供，则以最小 feature 运行 `cargo check -p <owning-package>`，行为变化时再加 focused `cargo test` |
 | Desktop/Tauri 集成 | `cargo check -p bitfun-desktop` |
 | i18n 资源或契约 | 使用 `AGENTS.md` 中匹配的 i18n 验证行 |
 

README.md

@@ -8,7 +8,7 @@
 
 Writes code, produces documents, and drives the desktop — with Mini Apps, a Rust runtime, and a self-hostable device-sync server.
 
-[**⬇ Download for macOS · Windows · Linux**](https://github.com/GCWing/BitFun/releases/latest) · [Verify downloads](./docs/verify-downloads.md)
+[**⬇ Download for macOS · Windows · Linux**](https://github.com/GCWing/BitFun/releases/latest) · [Verify downloads](./docs/guideline/verify-downloads.md)
 
 [Website](https://openbitfun.com/) · [Quick start](#first-run) · [Security](./SECURITY.md) · [Discussions](https://github.com/GCWing/BitFun/discussions) · [Contributing](./CONTRIBUTING.md)
 
@@ -131,7 +131,7 @@ BitFun's extension paths progress continuously from light to deep customization:
 | Tier | Path | Best for |
 | --- | --- | --- |
 | **L1** | Custom Agent | Defining roles, flows, constraints, and tool bundles. |
-| **L2** | MCP / Skills / [Hooks](docs/features/agent-hooks.md) | Connecting external tools and professional capabilities, and running your own commands at Agent lifecycle points — fully Codex-hook compatible, so existing hook scripts work as-is. |
+| **L2** | MCP / Skills / [Hooks](docs/specs/agent-hooks.md) | Connecting external tools and professional capabilities, and running your own commands at Agent lifecycle points — fully Codex-hook compatible, so existing hook scripts work as-is. |
 | **L3** | Mini App | Generating dedicated interfaces, forms, panels, or visualizations for tasks. |
 | **L4** | Source-level customization | Changing tools, adapters, UI, Runtime, or product shape. |
 

README.zh-CN.md

@@ -8,7 +8,7 @@
 
 能写代码、能做文档、能操控桌面，并提供小应用、Rust Runtime 和可自部署的多设备互控服务器。
 
-[**⬇ 下载 macOS · Windows · Linux 版**](https://github.com/GCWing/BitFun/releases/latest) · [校验下载](./docs/verify-downloads.zh-CN.md)
+[**⬇ 下载 macOS · Windows · Linux 版**](https://github.com/GCWing/BitFun/releases/latest) · [校验下载](./docs/guideline/verify-downloads.zh-CN.md)
 
 [官网](https://openbitfun.com/) · [快速开始](#第一次运行) · [安全策略](./SECURITY_CN.md) · [讨论区](https://github.com/GCWing/BitFun/discussions) · [参与贡献](./CONTRIBUTING_CN.md)
 
@@ -131,7 +131,7 @@ BitFun 的扩展路径从轻到重连续展开：
 | 层级 | 方式 | 适合场景 |
 | --- | --- | --- |
 | **L1** | Agent 自定义 | 定义角色、流程、约束和工具组合。 |
-| **L2** | MCP / Skills / [Hooks](docs/features/agent-hooks.zh-CN.md) | 接入外部工具和专业能力，并在 Agent 生命周期节点运行你自己的命令 —— 完全兼容 Codex Hooks，已有脚本无需适配。 |
+| **L2** | MCP / Skills / [Hooks](docs/specs/agent-hooks.zh-CN.md) | 接入外部工具和专业能力，并在 Agent 生命周期节点运行你自己的命令 —— 完全兼容 Codex Hooks，已有脚本无需适配。 |
 | **L3** | Mini App | 为任务生成专属界面、表单、面板或可视化。 |
 | **L4** | 源码级改造 | 修改工具、适配器、UI、Runtime 或产品形态。 |
 

docs/README.md

@@ -0,0 +1,32 @@
+# 文档地图
+
+> 用途：为 BitFun 代码仓内的文档提供放置路由与一级索引。
+> 范围：已跟踪的 `docs/` 内容；不包含源码旁的模块文档。
+> 状态：stable。
+> 权威语言：中文。治理规则见 [`guideline/docs-governance.zh-CN.md`](guideline/docs-governance.zh-CN.md)。
+
+| 目录 | 进入条件 | 索引 |
+|---|---|---|
+| `architecture/` | 查稳定架构、owner、依赖或已接受设计 | [`architecture/README.md`](architecture/README.md) |
+| `guideline/` | 查全仓常驻开发规范：命令、验证、宿主/远程、日志、i18n、文档治理 | [`guideline/README.md`](guideline/README.md) |
+| `specs/` | 写或查需求规格与设计（what & why） | [`specs/README.md`](specs/README.md) |
+| `plans/` | 写或查实施计划与收尾记录（how & when） | [`plans/README.md`](plans/README.md) |
+
+以下与代码耦合的产品操作指南作为明确例外保留在本仓 `guideline/`：
+飞书远程连接 [`feishu-bot-setup.zh-CN.md`](guideline/feishu-bot-setup.zh-CN.md)
+（[English](guideline/feishu-bot-setup.md)）、
+发布签名校验 [`verify-downloads.zh-CN.md`](guideline/verify-downloads.zh-CN.md)
+（[English](guideline/verify-downloads.md)）。
+
+## 兼容路径
+
+以下旧路径只保留短跳转页，供已发布版本和长期公共链接继续使用；正文只在上表四个权威目录维护：
+
+- [`remote-connect/feishu-bot-setup.md`](remote-connect/feishu-bot-setup.md) / [`remote-connect/feishu-bot-setup.zh-CN.md`](remote-connect/feishu-bot-setup.zh-CN.md) → `guideline/feishu-bot-setup*.md`
+- [`verify-downloads.md`](verify-downloads.md) / [`verify-downloads.zh-CN.md`](verify-downloads.zh-CN.md) → `guideline/verify-downloads*.md`
+- [`features/agent-hooks.md`](features/agent-hooks.md) / [`features/agent-hooks.zh-CN.md`](features/agent-hooks.zh-CN.md) → `specs/agent-hooks*.md`
+- [`features/remote-workspaces.md`](features/remote-workspaces.md) → `specs/remote-workspaces.md`
+- [`features/session-runtime-usage-report-design.md`](features/session-runtime-usage-report-design.md) → `specs/session-runtime-usage-report-design.md`
+
+不要在 `docs/` 根新增权威专题文章。临时调研、评审提示和个人草稿使用未跟踪的
+`*.local.md`；稳定内容按上表归入唯一 owner，不在多个目录复制。

docs/architecture/README.md

@@ -0,0 +1,60 @@
+# Architecture index
+
+Purpose: complete topic map for stable architecture docs under `docs/architecture/`.
+Scope: product runtime boundaries and cross-cutting design authorities.
+Status: stable
+Authority language: Chinese for most design bodies; this index is English for AI / ops navigation.
+
+Governance: [`docs/guideline/docs-governance.md`](../guideline/docs-governance.md).
+Product norms entry: root [`AGENTS.md`](../../AGENTS.md). Specs / plans: [`docs/specs/README.md`](../specs/README.md).
+
+This directory owns stable cross-module boundaries and accepted designs. It
+must not contain implementation task lists, user setup guides, benchmark dumps,
+temporary review notes, or module-local coding rules. Proposed targets must be
+marked as proposed and must not be presented as shipped behavior.
+
+## Start here
+
+| Topic | Authority |
+|---|---|
+| Product runtime boundaries / decomposition | [`product-architecture.md`](product-architecture.md) |
+| Rust build dependency boundaries | [`rust-build-dependency-boundaries.md`](rust-build-dependency-boundaries.md) |
+| Agent Runtime deployment / multi-instance | [`agent-runtime-deployment-design.md`](agent-runtime-deployment-design.md) |
+| Agent Runtime lifecycle sequence | [`agent-runtime-lifecycle-sequence.md`](agent-runtime-lifecycle-sequence.md) |
+| Agent runtime & services | [`agent-runtime-services-design.md`](agent-runtime-services-design.md) |
+| Agent SDK product shape | [`agent-sdk-product-architecture.md`](agent-sdk-product-architecture.md) |
+| App Server architecture (proposed target) | [`app-server-architecture.md`](app-server-architecture.md) |
+| CLI / TUI product line | [`cli-product-line-design.md`](cli-product-line-design.md) |
+| HarmonyOS PC / portability | [`platform-portability-design.md`](platform-portability-design.md) |
+| Product customization | [`product-customization-blueprint.md`](product-customization-blueprint.md) |
+| Appearance package system | [`appearance-package-system.md`](appearance-package-system.md) |
+| i18n | [`i18n.md`](i18n.md) |
+| Theme / color tokens | [`theme-token-optimization.md`](theme-token-optimization.md) |
+| Peer device mode | [`peer-device-mode.md`](peer-device-mode.md) |
+| Remote workspace transport | [`remote-workspace-transport.md`](remote-workspace-transport.md) |
+| Session projection | [`session-projection.md`](session-projection.md) |
+| Review lifecycle | [`review-lifecycle.md`](review-lifecycle.md) |
+| Deep Review | [`deep-review.md`](deep-review.md) |
+| Detached task dispatch | [`detached-task-dispatch.md`](detached-task-dispatch.md) |
+| Cache-friendly messages | [`cache-friendly-message-structure.md`](cache-friendly-message-structure.md) |
+| Model request cache reuse | [`model-request-cache-reuse.md`](model-request-cache-reuse.md) |
+| SDLC governance architecture | [`sdlc-governance-architecture.md`](sdlc-governance-architecture.md) |
+| Security boundary | [`security-boundary.md`](security-boundary.md) |
+| Quality data plane | [`quality-data-plane.md`](quality-data-plane.md) |
+| Evidence pack | [`evidence-pack.md`](evidence-pack.md) |
+| Artifact graph | [`artifact-graph.md`](artifact-graph.md) |
+| Project profile integration | [`project-profile-integration.md`](project-profile-integration.md) |
+| Agent workflow design | [`agent-workflow-design.md`](agent-workflow-design.md) |
+
+## Extensions
+
+| Topic | Authority |
+|---|---|
+| OpenCode compatibility | [`extensions/opencode-extension-compatibility.md`](extensions/opencode-extension-compatibility.md) |
+| External AI work sources | [`extensions/external-ai-work-sources-design.md`](extensions/external-ai-work-sources-design.md) |
+| Capability runtime integration | [`extensions/capability-runtime-integration-design.md`](extensions/capability-runtime-integration-design.md) |
+| Plugin runtime and host | [`extensions/plugin-runtime-design.md`](extensions/plugin-runtime-design.md) |
+| OpenCode config assets | [`extensions/opencode-config-assets-adapter-design.md`](extensions/opencode-config-assets-adapter-design.md) |
+| OpenCode plugin runtime adapter | [`extensions/opencode-plugin-runtime-adapter-design.md`](extensions/opencode-plugin-runtime-adapter-design.md) |
+| OpenCode TUI plugin adapter | [`extensions/opencode-tui-plugin-adapter-design.md`](extensions/opencode-tui-plugin-adapter-design.md) |
+| OpenCode external integrations | [`extensions/opencode-external-integration-adapter-design.md`](extensions/opencode-external-integration-adapter-design.md) |

docs/architecture/agent-runtime-deployment-design.md

@@ -554,6 +554,7 @@ Session/Turn、事件恢复、Permission/UserInput、Controller、配置管理
 
 - 只有一套 Agent Runtime 业务实现；部署差异不能产生第二套 Session、Tool、Permission 或 MCP owner。
 - 当前入口使用第 1.1 节列出的 adapter；Embedded TUI 使用 direct Runtime adapter，Web/需要连接边界的 Rich Client 继续使用 App Server。
+- Rust Runtime 与 Node/Bun Plugin Host 进程不要默认按 Client、workspace、session 或 plugin 拆进程；进程边界应由负责状态 owner、execution/security domain、可计量的安全条件与容量需求共同决定。
 - Client、窗口、Session 或 workspace 数量不会自动等量增加 Runtime 或 Plugin Host 进程。
 - 当前 Shared Runtime IPC 是第一方 TUI 的 private compatibility transport，不成为公开 SDK、Remote、Peer、HTTP 或浏览器协议；是否由 App Server Shared transport 替换仍待评审。
 - Shared TUI 的 Model、Skill、Subagent、MCP、External Source V1、Hook 和 Worktree 管理由 controller 直接调用现有 owner/service。这些 capability 不进入 `CliAgentRuntimeClient` 或 v17 wire。Account/Settings Sync 和后续 External Application V2 未由当前 Shared Host 提供并返回 typed unsupported；Remote workspace scope 明确 fail closed，不回落控制端本机。MCP service 的进程状态和 tool registry 只属于当前 CLI 进程，不即时重配已经运行的 Shared Runtime Host；跨进程 MCP 管理需要单独的同步/restart contract。

docs/sdlc-harness/architecture/agent-workflow-design.md → docs/architecture/agent-workflow-design.md

@@ -1,6 +1,6 @@
 # BitFun 智能体工作流交互与边界补充设计
 
-> 范围：为 [../agent-workflow-staged-plan.md](../agent-workflow-staged-plan.md) 中的场景提供交互和边界补充。
+> 范围：为 [../agent-workflow-staged-plan.md](../plans/sdlc-governance-agent-workflow-staged-plan.md) 中的场景提供交互和边界补充。
 > 本文不定义新的 Agent Kernel、Harness、QDP 或 DeepReview 核心对象模型；实现时优先复用既有 session、task、Agent Kernel/Harness long-running queue、DeepReview manifest、runtime events 和质量数据面契约。新受管 work packets 仅服务大目标 L1 Review，历史 packet 继续兼容读取。
 
 ## 1. 设计定位

docs/sdlc-harness/architecture/artifact-graph.md → docs/architecture/artifact-graph.md

@@ -1,6 +1,6 @@
 # BitFun 子模块设计：交付物图谱
 
-> 上游文档：[design.md](../design.md)
+> 上游文档：[design.md](sdlc-governance-architecture.md)
 > 模块角色：把目标项目中的任务、需求、设计、代码、测试、评审、CI、发布、运行期和复盘资产建模为可追踪、可失效、可确认的关系层。
 
 ## 1. 模块定位

docs/sdlc-harness/architecture/evidence-pack.md → docs/architecture/evidence-pack.md

@@ -1,6 +1,6 @@
 # BitFun 子模块设计：证据包
 
-> 上游文档：[design.md](../design.md)
+> 上游文档：[design.md](sdlc-governance-architecture.md)
 > 模块角色：把一次任务或变更的上下文、验证、风险、跳过项、人工决策和安全授权整理成可呈现、可失效、可回放的证据快照。
 
 ## 1. 模块定位
@@ -30,7 +30,7 @@
 | `evidence_refs` | 摘要加命令、CI、文件、审查和安全决策引用 | PR 就绪度、审查、团队建议投影 |
 | `full_pack` | 完整证据包、策略版本、风险接受、新鲜度和审计引用 | 守护/合规策略、发布、事故、评测 |
 
-展示层由 [配置化策略画像](../features/configurable-policy-profile.md) 决定。证据存在性和证据展示层级相互独立：后台可以生成最小证据摘要，快速路径只展示任务闭环需要的信息。
+展示层由 [配置化策略画像](../specs/configurable-policy-profile.md) 决定。证据存在性和证据展示层级相互独立：后台可以生成最小证据摘要，快速路径只展示任务闭环需要的信息。
 
 ## 4. 输入、输出与数据模型