docs: organize repository knowledge for agents

AGENTS.md

@@ -4,7 +4,7 @@ This is the repository entry document for coding agents. It is intentionally sho
 
 - keep durable project facts and hard constraints here
 - move multi-step procedures into skills
-- move deep reference material into `docs/guide/agent-reference.md`
+- move deep reference material into the indexed `docs/` knowledge base
 
 ## What ScholarAIO Is
 
@@ -28,10 +28,11 @@ The Python package is `scholaraio`. Real work should usually happen through the
 Read these in roughly this order:
 
 1. [`README.md`](README.md) for the product overview and top-level structure.
-2. [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md) for repo-open vs plugin or cross-project setup.
-3. [`docs/guide/cli-reference.md`](docs/guide/cli-reference.md) for the current user-facing CLI surface.
-4. [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md) for deeper agent, runtime, and skill organization details.
-5. [`docs/development/scholaraio-upgrade-plan.md`](docs/development/scholaraio-upgrade-plan.md) before changing runtime layout, migration, or compatibility behavior.
+2. [`docs/DESIGN.md`](docs/DESIGN.md) for the repository knowledge map.
+3. [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md) for repo-open vs plugin or cross-project setup.
+4. [`docs/guide/cli-reference.md`](docs/guide/cli-reference.md) for the current user-facing CLI surface.
+5. [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md) for deeper agent, runtime, and skill organization details.
+6. [`docs/internal/PLANS.md`](docs/internal/PLANS.md) and [`docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md`](docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md) before changing runtime layout, migration, or compatibility behavior.
 
 ## Skill-First Workflow
 
@@ -126,10 +127,13 @@ project MCP JSON. Codex uses its own MCP registry; see
 
 Use the smallest doc that answers the question:
 
+- Repository knowledge map: [`docs/DESIGN.md`](docs/DESIGN.md)
+- Plan map and execution history: [`docs/internal/PLANS.md`](docs/internal/PLANS.md), [`docs/internal/exec-plans/`](docs/internal/exec-plans/index.md)
+- Knowledge quality and cleanup: [`docs/internal/QUALITY_SCORE.md`](docs/internal/QUALITY_SCORE.md)
 - Agent and skill organization: [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
 - Setup and installation: [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md), [`docs/getting-started/installation.md`](docs/getting-started/installation.md), [`docs/getting-started/configuration.md`](docs/getting-started/configuration.md)
 - CLI behavior: [`docs/guide/cli-reference.md`](docs/guide/cli-reference.md)
 - Writing workflows: [`docs/guide/writing.md`](docs/guide/writing.md)
-- Runtime layout and migration: [`docs/development/scholaraio-upgrade-plan.md`](docs/development/scholaraio-upgrade-plan.md), [`docs/development/directory-structure-spec.md`](docs/development/directory-structure-spec.md), [`docs/development/directory-migration-sequence.md`](docs/development/directory-migration-sequence.md), [`docs/development/migration-mechanism-spec.md`](docs/development/migration-mechanism-spec.md)
+- Runtime layout and migration: [`docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md`](docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md), [`docs/design-docs/directory-structure-spec.md`](docs/design-docs/directory-structure-spec.md), [`docs/design-docs/directory-migration-sequence.md`](docs/design-docs/directory-migration-sequence.md), [`docs/design-docs/migration-mechanism-spec.md`](docs/design-docs/migration-mechanism-spec.md)
 
 When in doubt, keep this file short, keep skills procedural, and keep deep detail in dedicated reference docs.

AGENTS_CN.md

@@ -4,7 +4,7 @@
 
 - 这里只放持久有效的项目事实和硬约束
 - 多步骤流程放进 skills
-- 深度参考材料放进 `docs/guide/agent-reference.md`
+- 深度参考材料放进带索引的 `docs/` 知识库
 
 ## ScholarAIO 是什么
 
@@ -28,10 +28,11 @@ ScholarAIO 是一个 AI-native research terminal。用户通过 coding agent 用
 建议按这个顺序看：
 
 1. [`README.md`](README.md)：产品定位和顶层结构
-2. [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md)：直接开仓库 vs 插件 / 跨项目接入
-3. [`docs/guide/cli-reference.md`](docs/guide/cli-reference.md)：当前 CLI 面
-4. [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)：更深的 agent、runtime、skill 组织说明
-5. [`docs/development/scholaraio-upgrade-plan.md`](docs/development/scholaraio-upgrade-plan.md)：涉及运行时布局、迁移、兼容层时先看
+2. [`docs/DESIGN.md`](docs/DESIGN.md)：仓库知识地图
+3. [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md)：直接开仓库 vs 插件 / 跨项目接入
+4. [`docs/guide/cli-reference.md`](docs/guide/cli-reference.md)：当前 CLI 面
+5. [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)：更深的 agent、runtime、skill 组织说明
+6. [`docs/internal/PLANS.md`](docs/internal/PLANS.md) 和 [`docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md`](docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md)：涉及运行时布局、迁移、兼容层时先看
 
 ## Skill 优先工作流
 
@@ -120,10 +121,13 @@ breaking cleanup generation 已移除 `scholaraio.index`、`scholaraio.workspace
 
 按最小必要原则阅读：
 
+- 仓库知识地图：[`docs/DESIGN.md`](docs/DESIGN.md)
+- 计划地图与执行历史：[`docs/internal/PLANS.md`](docs/internal/PLANS.md)、[`docs/internal/exec-plans/`](docs/internal/exec-plans/index.md)
+- 知识质量与清理：[`docs/internal/QUALITY_SCORE.md`](docs/internal/QUALITY_SCORE.md)
 - Agent 与 skill 组织：[`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
 - 安装与配置：[`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md)、[`docs/getting-started/installation.md`](docs/getting-started/installation.md)、[`docs/getting-started/configuration.md`](docs/getting-started/configuration.md)
 - CLI 行为：[`docs/guide/cli-reference.md`](docs/guide/cli-reference.md)
 - 写作工作流：[`docs/guide/writing.md`](docs/guide/writing.md)
-- 运行时布局与迁移：[`docs/development/scholaraio-upgrade-plan.md`](docs/development/scholaraio-upgrade-plan.md)、[`docs/development/directory-structure-spec.md`](docs/development/directory-structure-spec.md)、[`docs/development/directory-migration-sequence.md`](docs/development/directory-migration-sequence.md)、[`docs/development/migration-mechanism-spec.md`](docs/development/migration-mechanism-spec.md)
+- 运行时布局与迁移：[`docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md`](docs/internal/exec-plans/completed/scholaraio-upgrade-plan.md)、[`docs/design-docs/directory-structure-spec.md`](docs/design-docs/directory-structure-spec.md)、[`docs/design-docs/directory-migration-sequence.md`](docs/design-docs/directory-migration-sequence.md)、[`docs/design-docs/migration-mechanism-spec.md`](docs/design-docs/migration-mechanism-spec.md)
 
 拿不准时，遵循三条：入口文档保持精简，流程性内容进 skills，深细节进专项参考文档。

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **Repository knowledge map** ([#112](https://github.com/ZimoLiao/scholaraio/pull/112)): Added a published `docs/DESIGN.md` knowledge map and focused documentation indexes for agent navigation, while keeping maintenance plans, validation records, and audit notes out of the published MkDocs surface.
 - **Automated cross-project agent setup** ([#111](https://github.com/ZimoLiao/scholaraio/pull/111)): Added `scholaraio setup agent` preview, apply, and check workflows for shell runtime wiring, Codex/OpenClaw skill discovery, Claude Code plugin instructions, and project-local wrappers for Qwen, Cursor, Cline, Windsurf, and GitHub Copilot.
 - **Nature workflow bridge skill** ([#107](https://github.com/ZimoLiao/scholaraio/issues/107)): Added a ScholarAIO `nature-workflow` bridge skill that routes Nature Portfolio writing and figure workflows to the upstream `nature-skills` repository when installed, keeps ScholarAIO-native fallbacks explicit, documents the install and quick-start path, and includes deterministic plus product-demo fixtures that generate reviewable manuscript, figure, slide, and QA artifacts.
 

CLAUDE.md

@@ -4,7 +4,7 @@ This file is the Claude Code project-memory entrypoint. It intentionally stays l
 
 - durable project facts and navigation live here
 - reusable procedures belong in `.claude/skills/`
-- deep reference lives in `docs/guide/agent-reference.md`
+- deep reference lives in the indexed `docs/` knowledge base, starting at `docs/DESIGN.md` and `docs/guide/agent-reference.md`
 
 Claude-specific notes:
 

README.md

@@ -45,7 +45,7 @@ pip install -e ".[full]"
 scholaraio setup
 ```
 
-Then open the repository in Codex, Claude Code, or another supported agent. In this setup, the agent gets the fullest experience: bundled instructions, local skills, the CLI, and the complete codebase context are all available directly. For Claude Code plugins, Codex/OpenClaw skill registration, and other setup paths, see [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md).
+Then open the repository in Codex, Claude Code, or another supported agent. In this setup, the agent gets the fullest experience: bundled instructions, local skills, the CLI, the repository knowledge map in [`docs/DESIGN.md`](docs/DESIGN.md), and the complete codebase context are all available directly. For Claude Code plugins, Codex/OpenClaw skill registration, and other setup paths, see [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md).
 
 ## Upgrading To 1.4
 
@@ -174,8 +174,9 @@ data/spool/inbox-proceedings/ # Dedicated proceedings ingest inbox
 
 Upgrading an older runtime layout? See [Upgrading To 1.4](#upgrading-to-14).
 
-Agent entry docs → [`CLAUDE.md`](CLAUDE.md) or [`AGENTS.md`](AGENTS.md)
-Deep agent reference → [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
+- Agent entry docs: [`CLAUDE.md`](CLAUDE.md) or [`AGENTS.md`](AGENTS.md)
+- Repository knowledge map: [`docs/DESIGN.md`](docs/DESIGN.md)
+- Deep agent reference: [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
 
 ## Citation
 

README_CN.md

@@ -45,7 +45,7 @@ pip install -e ".[full]"
 scholaraio setup
 ```
 
-这样一来，agent 能得到最完整的使用体验：仓库内置指令、本地 skills、CLI 和完整代码上下文都会直接可用。Claude Code 插件、Codex/OpenClaw skills 注册，以及其他使用路径的详细说明，详见 [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md)。
+这样一来，agent 能得到最完整的使用体验：仓库内置指令、本地 skills、CLI、[`docs/DESIGN.md`](docs/DESIGN.md) 中的仓库知识地图，以及完整代码上下文都会直接可用。Claude Code 插件、Codex/OpenClaw skills 注册，以及其他使用路径的详细说明，详见 [`docs/getting-started/agent-setup.md`](docs/getting-started/agent-setup.md)。
 
 ## 升级到 1.4
 
@@ -173,8 +173,9 @@ data/spool/inbox-proceedings/ # proceedings 专用 inbox
 
 从旧版 runtime layout 升级时，请看上面的[升级到 1.4](#升级到-14)。
 
-Agent 入口文档 → [`CLAUDE.md`](CLAUDE.md) 或 [`AGENTS.md`](AGENTS.md)
-深入 agent 参考 → [`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
+- Agent 入口文档：[`CLAUDE.md`](CLAUDE.md) 或 [`AGENTS.md`](AGENTS.md)
+- 仓库知识地图：[`docs/DESIGN.md`](docs/DESIGN.md)
+- 深入 agent 参考：[`docs/guide/agent-reference.md`](docs/guide/agent-reference.md)
 
 ## 引用
 

docs/DESIGN.md

@@ -0,0 +1,61 @@
+# Repository Knowledge Design
+
+Status: Current map
+
+Last Updated: 2026-06-12
+
+ScholarAIO is an agent-first research infrastructure. Its published repository
+knowledge is organized for progressive disclosure: entry docs give agents a map,
+and the public `docs/` tree carries user-facing and durable design material.
+
+This layout is inspired by OpenAI's harness-engineering guidance that
+`AGENTS.md` should behave like a table of contents rather than a monolithic
+manual: https://openai.com/index/harness-engineering/
+
+## Principles
+
+- `AGENTS.md`, `CLAUDE.md`, and other wrappers stay short and point inward.
+- Durable facts live in versioned Markdown near the code they govern.
+- Multi-step procedures live in skills, not in entry docs.
+- Plans, validation records, and audits are local maintenance artifacts, not
+  published documentation.
+- Generated references must say how they were generated and when to refresh them.
+- Agent-facing docs should be easy to index, grep, validate, and garbage collect.
+
+## Directory Roles
+
+| Path | Role |
+|------|------|
+| `docs/index.md` | Public documentation home |
+| `docs/getting-started/` | User setup and upgrade paths |
+| `docs/guide/` | User-facing workflow references |
+| `docs/writing-guide/` | Writing and diagram authoring guides |
+| `docs/api/` | Python API documentation |
+| `docs/design-docs/` | Long-lived architecture and runtime design decisions |
+| `docs/product-specs/` | Product behavior and workflow specifications |
+| `docs/generated/` | Generated facts such as schema or CLI snapshots |
+| `docs/superpowers/` | Local planning artifacts created by superpowers workflows |
+| `docs/archive/` and `docs/internal/` | Historical or local-only notes excluded from published docs |
+
+## Reading Order
+
+1. Start with `AGENTS.md` for hard constraints and navigation.
+2. Use this file for the repository knowledge map.
+3. Use `docs/guide/agent-reference.md` for agent runtime and skill details.
+4. Use the relevant design doc, product spec, generated reference, or guide
+   before changing a governed area.
+5. Use source code and tests as the final authority for current behavior.
+
+## Maintenance Rules
+
+- When adding a durable design decision, put it under `docs/design-docs/` and
+  link it from `docs/design-docs/index.md`.
+- Keep plans, validation evidence, and audits under `docs/internal/`, which is
+  excluded from the published MkDocs site.
+- When internal work discovers reusable policy or product behavior, promote only
+  the stable public fact into `docs/design-docs/`, `docs/product-specs/`, or a
+  project skill.
+- When a reference is generated, put it under `docs/generated/` and document the
+  generating command in the file header.
+- Do not use a single root wrapper as the long-term home for checklists,
+  examples, or operational runbooks.

docs/development/directory-migration-sequence.md → docs/design-docs/directory-migration-sequence.md

@@ -12,12 +12,12 @@ the active breaking-cleanup runtime.
 
 - this document remains the historical execution record for the compatibility-window generation
 - current runtime behavior is no longer compatibility-window behavior: legacy public import facades are removed and legacy runtime roots are no longer auto-opened
-- the active breaking-generation execution authority is `docs/development/breaking-compat-cleanup-plan.md`
+- the active breaking-generation execution authority is kept in internal release-gate records
 - the hardened post-migration user cleanup flow is now `scholaraio migrate finalize --confirm`
 
 ## 1. Purpose
 
-This document defines the recommended execution order for migrating ScholarAIO toward the target directory structure described in `docs/development/directory-structure-spec.md`.
+This document defines the recommended execution order for migrating ScholarAIO toward the target directory structure described in `docs/design-docs/directory-structure-spec.md`.
 
 This is an implementation-order document, not a vision document. Its job is to answer:
 
@@ -30,7 +30,7 @@ This is an implementation-order document, not a vision document. Its job is to a
 
 This document should be read together with:
 
-- `docs/development/migration-mechanism-spec.md`
+- `docs/design-docs/migration-mechanism-spec.md`
 
 That companion document defines the control-plane contract (`instance.json`, `migration.lock`, journal, verification, cleanup gating). This document defines when that machinery must appear in the execution order.
 
@@ -83,8 +83,8 @@ Historical audited facts from the compatibility-window generation:
 
 The following bullets intentionally preserve the pre-cleanup compatibility
 language used during migration planning. In the active release generation, legacy
-public import facades have been removed; see `docs/development/breaking-compat-cleanup-plan.md`
-and `docs/guide/agent-reference.md` for the current contract.
+public import facades have been removed; see the internal breaking-cleanup
+release gate and `docs/guide/agent-reference.md` for the current contract.
 
 - `scholaraio/core/config.py` now exposes a much broader runtime-path accessor surface and routes `ensure_dirs()` through those accessors, which lowers path-migration risk but does not yet remove direct path construction in downstream modules
 - `scholaraio/core/config.py` now resolves `index_db`, `metrics_db_path`, and `topics_model_dir` through logical `state_root` subdirectories for fresh installs, while still auto-detecting existing legacy `data/index.db`, `data/metrics.db`, and `data/topic_model/` stores
@@ -362,9 +362,7 @@ Objective:
 
 - eliminate hardcoded runtime paths from leaf modules and orchestration code by first exposing them through `Config`
 
-Primary audit reference:
-
-- `docs/development/config-surface-audit.md`
+Primary audit reference: internal config-surface audit records.
 
 Required additions in or around `scholaraio/core/config.py`:
 
@@ -605,7 +603,7 @@ Required changes:
 
 Required reference:
 
-- align this phase with `docs/development/migration-mechanism-spec.md`
+- align this phase with `docs/design-docs/migration-mechanism-spec.md`
 
 Why this phase exists here:
 

docs/development/directory-structure-spec.md → docs/design-docs/directory-structure-spec.md

@@ -231,7 +231,7 @@ Rationale:
 
 The detailed contract for this directory is defined in:
 
-- `docs/development/migration-mechanism-spec.md`
+- `docs/design-docs/migration-mechanism-spec.md`
 
 ## 6. `data/` Subtree Specification
 

docs/design-docs/index.md

@@ -0,0 +1,24 @@
+# Design Docs
+
+Status: Current index
+
+Last Updated: 2026-06-12
+
+Design docs are long-lived architecture and runtime decisions. They answer what
+must stay true, not just what one implementation plan happened to do.
+
+## Current Authorities
+
+| Document | Scope |
+|----------|-------|
+| `directory-structure-spec.md` | Current runtime directory layout and path ownership |
+| `migration-mechanism-spec.md` | Migration control-plane contract, journal, locking, and cleanup gates |
+| `directory-migration-sequence.md` | Historical compatibility-window execution order |
+| `user-data-migration-strategy.md` | Historical user-data migration strategy and posture |
+
+## Rules
+
+- Put durable architecture decisions here.
+- Keep execution checklists and validation evidence in internal maintenance docs,
+  not in the published design-doc surface.
+- Link new design docs from this index before treating them as authority.