docs: add bilingual docs structure

2026-03-15 23:45:17 +08:00 · 2026-03-15 23:45:17 +08:00 · 9e39cbc5a5
commit 9e39cbc5a5
parent ce10082df4
16 changed files with 471 additions and 119 deletions
--- a/docs/DOC_COVERAGE.md
+++ b/docs/DOC_COVERAGE.md
@ -0,0 +1,14 @@
+# Documentation Coverage Matrix
+
+This matrix tracks the bilingual canonical documentation set for `console.svc.plus` and maps it back to the current codebase and older docs.
+
+该矩阵用于跟踪 `console.svc.plus` 的双语规范文档，并将其与当前代码状态和历史文档对应起来。
+
+| Category | EN | ZH | Current status | Existing references | Next check |
+| --- | --- | --- | --- | --- | --- |
+| Architecture | Yes | Yes | Seeded from current codebase and existing docs. | `api/overview.md`<br>`architecture/components.md`<br>`architecture/design-decisions.md`<br>`architecture/overview.md`<br>`architecture/roadmap.md`<br>`development/code-structure.md`<br>`zh/api/overview.md`<br>`zh/architecture/components.md` | Keep diagrams and ownership notes synchronized with actual directories, services, and integration dependencies. |
+| Design | Yes | Yes | Seeded from current codebase and existing docs. | `SEO-WORK-SUMMARY.md`<br>`architecture/design-decisions.md`<br>`zh/SEO-WORK-SUMMARY.md`<br>`zh/architecture/design-decisions.md` | Promote one-off implementation notes into reusable design records when behavior, APIs, or deployment contracts change. |
+| Deployment | Yes | Yes | Seeded from current codebase and existing docs. | `development/dev-setup.md`<br>`getting-started/installation.md`<br>`getting-started/quickstart.md`<br>`governance/release-process.md`<br>`operations/runbooks/README.md`<br>`operations/runbooks/rag-server.md`<br>`usage/deployment.md`<br>`zh/development/dev-setup.md` | Verify deployment steps against current scripts, manifests, CI/CD flow, and environment contracts before each release. |
+| User Guide | Yes | Yes | Seeded from current codebase and existing docs. | `api/overview.md`<br>`architecture/overview.md`<br>`getting-started/concepts.md`<br>`getting-started/installation.md`<br>`getting-started/introduction.md`<br>`getting-started/quickstart.md`<br>`usage/cli.md`<br>`usage/config.md` | Prefer workflow-oriented examples and keep screenshots or terminal snippets aligned with the latest UI or CLI behavior. |
+| Developer Guide | Yes | Yes | Seeded from current codebase and existing docs. | `api/auth.md`<br>`api/endpoints.md`<br>`api/errors.md`<br>`api/overview.md`<br>`development/code-structure.md`<br>`development/contributing.md`<br>`development/dev-setup.md`<br>`development/testing.md` | Keep setup and test commands tied to actual package scripts, Make targets, or language toolchains in this repository. |
+| Vibe Coding Reference | Yes | Yes | Seeded from current codebase and existing docs. | `api/auth.md`<br>`api/endpoints.md`<br>`api/errors.md`<br>`api/overview.md`<br>`zh/api/auth.md`<br>`zh/api/endpoints.md`<br>`zh/api/errors.md`<br>`zh/api/overview.md` | Review prompt templates and repo rules whenever the project adds new subsystems, protected areas, or mandatory verification steps. |
--- a/docs/README.md
+++ b/docs/README.md
@ -1,94 +1,42 @@
-# Documentation
+# Console Service Plus / 控制台服务

-This directory follows a standard open-source documentation layout and mirrors the code organization of `console.svc.plus`.
+This `docs/` directory now has a bilingual canonical layer for the current repository state.

-## Languages
+本 `docs/` 目录现已补齐双语规范层，用于承接当前仓库状态下的核心文档。

- English (EN): this directory (`docs/`)
- Chinese (ZH): `docs/zh/` (stubs / translations)
+## Quick Entry / 快速入口

-## Structure
+- Coverage checklist / 覆盖检查矩阵: `docs/DOC_COVERAGE.md`
+- English index / 英文入口: `docs/en/README.md`
+- 中文入口 / Chinese index: `docs/zh/README.md`

- `getting-started/` — new user path to get running quickly.
- `architecture/` — system design, boundaries, and decisions.
- `usage/` — configuration and how-to guides.
- `api/` — service API references.
- `integrations/` — external systems and providers.
- `advanced/` — performance, security, scalability, customization.
- `development/` — contributor guides and local setup.
- `operations/` — logging, monitoring, troubleshooting, runbooks.
- `governance/` — license, security policy, release process.
- `appendix/` — FAQ, glossary, references.
+## Canonical Bilingual Pages / 双语规范页

-## Codebase Mapping
+- `docs/en/architecture.md` / `docs/zh/architecture.md`
+- `docs/en/design.md` / `docs/zh/design.md`
+- `docs/en/deployment.md` / `docs/zh/deployment.md`
+- `docs/en/user-guide.md` / `docs/zh/user-guide.md`
+- `docs/en/developer-guide.md` / `docs/zh/developer-guide.md`
+- `docs/en/vibe-coding-reference.md` / `docs/zh/vibe-coding-reference.md`

- App layer (Next.js): `src/app`, `src/components`, `src/lib`, `src/state`, `src/modules`
- Library layer (vendored): `packages/neurapress`
- Build/runtime glue: `scripts`, `config`, `public`
+## Current Repo Context / 当前仓库背景

-## Assistant Integrations
+- Root README: `console.svc.plus`
+- Previous docs index: `Documentation`
+- Manifest evidence / 构建清单: package.json (`dashboard`)
+- Active code and ops directories / 当前主要目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`

-The homepage AI assistant and `/panel/api` integrations page read their defaults from environment variables on the server side. Use `.env.example` plus `getting-started/installation.md` for the canonical setup.
+## Existing Docs To Reconcile / 需要继续归并的现有文档

-Canonical variables:
-
- `OPENCLAW_GATEWAY_REMOTE_URL`
- `OPENCLAW_GATEWAY_TOKEN`
- `VAULT_SERVER_URL`
- `VAULT_NAMESPACE`
- `VAULT_TOKEN`
- `APISIX_AI_GATEWAY_URL`
- `AI_GATEWAY_ACCESS_TOKEN`
-
-## Index
-
- Getting Started
-  - `getting-started/introduction.md`
-  - `getting-started/quickstart.md`
-  - `getting-started/installation.md`
-  - `getting-started/concepts.md`
- Architecture
-  - `architecture/overview.md`
-  - `architecture/components.md`
-  - `architecture/design-decisions.md`
-  - `architecture/roadmap.md`
- Usage
-  - `usage/cli.md`
-  - `usage/config.md`
-  - `usage/deployment.md`
-  - `usage/examples.md`
- API
-  - `api/overview.md`
-  - `api/auth.md`
-  - `api/endpoints.md`
-  - `api/errors.md`
- Integrations
-  - `integrations/databases.md`
-  - `integrations/cloud.md`
-  - `integrations/cloudflare-web-analytics.md`
-  - `integrations/ai-providers.md`
- Advanced
-  - `advanced/performance.md`
-  - `advanced/security.md`
-  - `advanced/scalability.md`
-  - `advanced/customization.md`
- Development
-  - `development/contributing.md`
-  - `development/dev-setup.md`
-  - `development/testing.md`
-  - `development/code-structure.md`
- Operations
-  - `operations/logging.md`
-  - `operations/monitoring.md`
-  - `operations/backup.md`
-  - `operations/troubleshooting.md`
-  - `operations/runbooks/README.md`
-  - `operations/runbooks/rag-server.md`
- Governance
-  - `governance/license.md`
-  - `governance/security-policy.md`
-  - `governance/release-process.md`
- Appendix
-  - `appendix/faq.md`
-  - `appendix/glossary.md`
-  - `appendix/references.md`
+- `SEO-AUDIT-REPORT.md`
+- `SEO-WORK-SUMMARY.md`
+- `advanced/customization.md`
+- `advanced/performance.md`
+- `advanced/scalability.md`
+- `advanced/security.md`
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `appendix/faq.md`
+- `appendix/glossary.md`
--- a/docs/en/README.md
+++ b/docs/en/README.md
@ -0,0 +1,34 @@
+# Console Service Plus Documentation
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+## Current state snapshot
+
+- Root README title: `console.svc.plus`
+- Build/runtime evidence: package.json (`dashboard`)
+- Primary directories detected: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Existing docs count: 86
+
+## Canonical pages
+
+- [Architecture](architecture.md)
+- [Design](design.md)
+- [Deployment](deployment.md)
+- [User Guide](user-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Vibe Coding Reference](vibe-coding-reference.md)
+
+## Legacy docs to fold in
+
+- `SEO-AUDIT-REPORT.md`
+- `SEO-WORK-SUMMARY.md`
+- `advanced/customization.md`
+- `advanced/performance.md`
+- `advanced/scalability.md`
+- `advanced/security.md`
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `appendix/faq.md`
+- `appendix/glossary.md`
--- a/docs/en/architecture.md
+++ b/docs/en/architecture.md
@ -0,0 +1,31 @@
+# Architecture
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page as the canonical bilingual overview of system boundaries, major components, and repo ownership.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `api/overview.md`
+- `architecture/components.md`
+- `architecture/design-decisions.md`
+- `architecture/overview.md`
+- `architecture/roadmap.md`
+- `development/code-structure.md`
+- `zh/api/overview.md`
+- `zh/architecture/components.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Keep diagrams and ownership notes synchronized with actual directories, services, and integration dependencies.
--- a/docs/en/deployment.md
+++ b/docs/en/deployment.md
@ -0,0 +1,31 @@
+# Deployment
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page to standardize deployment prerequisites, supported topologies, operational checks, and rollback notes.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `development/dev-setup.md`
+- `getting-started/installation.md`
+- `getting-started/quickstart.md`
+- `governance/release-process.md`
+- `operations/runbooks/README.md`
+- `operations/runbooks/rag-server.md`
+- `usage/deployment.md`
+- `zh/development/dev-setup.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Verify deployment steps against current scripts, manifests, CI/CD flow, and environment contracts before each release.
--- a/docs/en/design.md
+++ b/docs/en/design.md
@ -0,0 +1,27 @@
+# Design
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page to consolidate design decisions, ADR-style tradeoffs, and roadmap-sensitive implementation notes.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `SEO-WORK-SUMMARY.md`
+- `architecture/design-decisions.md`
+- `zh/SEO-WORK-SUMMARY.md`
+- `zh/architecture/design-decisions.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Promote one-off implementation notes into reusable design records when behavior, APIs, or deployment contracts change.
--- a/docs/en/developer-guide.md
+++ b/docs/en/developer-guide.md
@ -0,0 +1,31 @@
+# Developer Guide
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page to document local setup, project structure, test surfaces, and contribution conventions tied to the current codebase.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `development/code-structure.md`
+- `development/contributing.md`
+- `development/dev-setup.md`
+- `development/testing.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Keep setup and test commands tied to actual package scripts, Make targets, or language toolchains in this repository.
--- a/docs/en/user-guide.md
+++ b/docs/en/user-guide.md
@ -0,0 +1,31 @@
+# User Guide
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page to document primary user/operator tasks, everyday workflows, and navigation to existing how-to material.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `api/overview.md`
+- `architecture/overview.md`
+- `getting-started/concepts.md`
+- `getting-started/installation.md`
+- `getting-started/introduction.md`
+- `getting-started/quickstart.md`
+- `usage/cli.md`
+- `usage/config.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Prefer workflow-oriented examples and keep screenshots or terminal snippets aligned with the latest UI or CLI behavior.
--- a/docs/en/vibe-coding-reference.md
+++ b/docs/en/vibe-coding-reference.md
@ -0,0 +1,31 @@
+# Vibe Coding Reference
+
+This repository primarily delivers a web frontend experience and should document product flows, UI boundaries, and integration touchpoints.
+
+Use this page to align AI-assisted coding prompts, repo boundaries, safe edit rules, and documentation update expectations.
+
+## Current code-aligned notes
+
+- Documentation target: `console.svc.plus`
+- Repo kind: `frontend`
+- Manifest and build evidence: package.json (`dashboard`)
+- Primary implementation and ops directories: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- Package scripts snapshot: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## Existing docs to reconcile
+
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `zh/api/auth.md`
+- `zh/api/endpoints.md`
+- `zh/api/errors.md`
+- `zh/api/overview.md`
+
+## What this page should cover next
+
+- Describe the current implementation rather than an aspirational future-only design.
+- Keep terminology aligned with the repository root README, manifests, and actual directories.
+- Link deeper runbooks, specs, or subsystem notes from the legacy docs listed above.
+- Review prompt templates and repo rules whenever the project adds new subsystems, protected areas, or mandatory verification steps.
--- a/docs/zh/README.md
+++ b/docs/zh/README.md
@ -1,42 +1,34 @@
-# 文档 (ZH)
+# 控制台服务 文档

-本目录为 `console.svc.plus` 文档的中文版本（当前以占位/逐步翻译为主）。
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。

-> English docs: `../README.md`
+## 当前状态快照

-## 目录结构
+- 根 README 标题: `console.svc.plus`
+- 构建与运行时证据: package.json (`dashboard`)
+- 自动识别的主要目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- 现有文档数量: 86

- `getting-started/`  入门与快速开始
- `architecture/`  架构与设计
- `usage/`  使用与配置
- `api/`  API 参考
- `integrations/`  第三方集成
- `advanced/`  高级主题（性能/安全/扩展/定制）
- `development/`  开发与贡献
- `operations/`  运维（日志/监控/备份/排障/Runbooks）
- `governance/`  治理（许可证/安全策略/发布流程）
- `appendix/`  附录（FAQ/术语表/参考资料）
+## 核心双语文档

-## 翻译约定
+- [架构](architecture.md)
+- [设计](design.md)
+- [部署](deployment.md)
+- [使用手册](user-guide.md)
+- [开发手册](developer-guide.md)
+- [Vibe Coding 参考](vibe-coding-reference.md)

- 每个中文文件顶部会链接到对应的英文原文路径。
- 如果中文内容尚未完善，会保留 `TODO` 占位，逐步补齐。
+## 待归并的历史文档

-## AI 助手集成环境变量
-
-首页 AI 助手和 `/panel/api` 集成页会在服务端读取环境变量做默认值预填，不会把网关地址或令牌硬编码进前端 UI。
-
-建议优先查看：
-
- `../../.env.example`
- `getting-started/installation.md`
-
-当前约定的主变量：
-
- `OPENCLAW_GATEWAY_REMOTE_URL`
- `OPENCLAW_GATEWAY_TOKEN`
- `VAULT_SERVER_URL`
- `VAULT_NAMESPACE`
- `VAULT_TOKEN`
- `APISIX_AI_GATEWAY_URL`
- `AI_GATEWAY_ACCESS_TOKEN`
+- `SEO-AUDIT-REPORT.md`
+- `SEO-WORK-SUMMARY.md`
+- `advanced/customization.md`
+- `advanced/performance.md`
+- `advanced/scalability.md`
+- `advanced/security.md`
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `appendix/faq.md`
+- `appendix/glossary.md`
--- a/docs/zh/architecture.md
+++ b/docs/zh/architecture.md
@ -0,0 +1,31 @@
+# 架构
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页作为系统边界、核心组件与仓库职责的双语总览入口。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `api/overview.md`
+- `architecture/components.md`
+- `architecture/design-decisions.md`
+- `architecture/overview.md`
+- `architecture/roadmap.md`
+- `development/code-structure.md`
+- `zh/api/overview.md`
+- `zh/architecture/components.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 随着目录结构、服务关系和集成依赖变化，持续同步图示与职责说明。
--- a/docs/zh/deployment.md
+++ b/docs/zh/deployment.md
@ -0,0 +1,31 @@
+# 部署
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页用于统一部署前提、支持的拓扑、运维检查项与回滚注意事项。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `development/dev-setup.md`
+- `getting-started/installation.md`
+- `getting-started/quickstart.md`
+- `governance/release-process.md`
+- `operations/runbooks/README.md`
+- `operations/runbooks/rag-server.md`
+- `usage/deployment.md`
+- `zh/development/dev-setup.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 每次发布前，依据当前脚本、清单、CI/CD 流程和环境契约重新核对部署步骤。
--- a/docs/zh/design.md
+++ b/docs/zh/design.md
@ -0,0 +1,27 @@
+# 设计
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页用于汇总设计决策、类似 ADR 的权衡记录，以及与路线图相关的实现说明。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `SEO-WORK-SUMMARY.md`
+- `architecture/design-decisions.md`
+- `zh/SEO-WORK-SUMMARY.md`
+- `zh/architecture/design-decisions.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 当行为、API 或部署契约发生变化时，把一次性实现笔记提升为可复用设计记录。
--- a/docs/zh/developer-guide.md
+++ b/docs/zh/developer-guide.md
@ -0,0 +1,31 @@
+# 开发手册
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页用于记录本地开发环境、项目结构、测试面与贴合当前代码库的贡献约定。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `development/code-structure.md`
+- `development/contributing.md`
+- `development/dev-setup.md`
+- `development/testing.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 持续让环境搭建与测试命令对应真实存在的脚本、Make 目标或语言工具链。
--- a/docs/zh/user-guide.md
+++ b/docs/zh/user-guide.md
@ -0,0 +1,31 @@
+# 使用手册
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页用于记录主要用户或运维角色的日常任务、常见流程，以及现有操作文档入口。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `api/overview.md`
+- `architecture/overview.md`
+- `getting-started/concepts.md`
+- `getting-started/installation.md`
+- `getting-started/introduction.md`
+- `getting-started/quickstart.md`
+- `usage/cli.md`
+- `usage/config.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 优先提供面向流程的示例，并确保截图或终端片段与最新 UI/CLI 行为一致。
--- a/docs/zh/vibe-coding-reference.md
+++ b/docs/zh/vibe-coding-reference.md
@ -0,0 +1,31 @@
+# Vibe Coding 参考
+
+该仓库以 Web 前端体验为主，文档需要覆盖产品流程、界面边界与集成触点。
+
+本页用于统一 AI 辅助开发提示词、仓库边界、安全编辑规则与文档同步要求。
+
+## 与当前代码对齐的说明
+
+- 文档目标仓库: `console.svc.plus`
+- 仓库类型: `frontend`
+- 构建与运行依据: package.json (`dashboard`)
+- 主要实现与运维目录: `src/`, `scripts/`, `tests/`, `config/`, `public/`
+- `package.json` 脚本快照: `dev`, `prebuild`, `build`, `build:static`, `start`, `lint`
+
+## 需要继续归并的现有文档
+
+- `api/auth.md`
+- `api/endpoints.md`
+- `api/errors.md`
+- `api/overview.md`
+- `zh/api/auth.md`
+- `zh/api/endpoints.md`
+- `zh/api/errors.md`
+- `zh/api/overview.md`
+
+## 本页下一步应补充的内容
+
+- 先描述当前已落地实现，再补充未来规划，避免只写愿景不写现状。
+- 术语需要与仓库根 README、构建清单和实际目录保持一致。
+- 将上方列出的历史 runbook、spec、子系统说明逐步链接并归并到本页。
+- 当项目新增子系统、受保护目录或强制验证步骤时，同步更新提示模板与仓库规则。