docs: finalize documentation classification and reference guides - #1415
Open
chenncy wants to merge 1 commit into
Open
docs: finalize documentation classification and reference guides#1415chenncy wants to merge 1 commit into
chenncy wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the documentation into a clearer classification (tutorials, how-to, explanation, integrations, reference) in both English and Chinese, while updating reference pages to reflect current Server contracts and behaviors.
Changes:
- Reorganize docs navigation and landing pages into the new documentation taxonomy (EN/ZH).
- Add new bilingual how-to guides for Server env files, vector search, and Agent Skill targets.
- Update reference content for MCP scope, Scalar
/docs,/openapi.jsonauth behavior, and other contract clarifications.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| zensical.toml | Updates EN/ZH navigation to the new docs classification and adds new how-to entries. |
| docs/en/docs/index.md | Updates the docs overview intro and adds new “Configure …” entries. |
| docs/zh/docs/index.md | Updates the docs overview intro and adds new “配置 …” entries. |
| docs/en/docs/reference/interfaces.md | Refreshes interface descriptions and simplifies work-continuity explanation to match current behavior. |
| docs/zh/docs/reference/interfaces.md | Same as EN; updates MCP scope description and work-continuity summary. |
| docs/en/docs/reference/http-api.md | Updates contract discovery guidance for Scalar /docs and /openapi.json auth behavior. |
| docs/zh/docs/reference/http-api.md | Same as EN; updates discovery and auth notes for /docs and /openapi.json. |
| docs/en/docs/reference/configuration.md | Moves procedures out of reference and points to new how-to pages for workflows. |
| docs/zh/docs/reference/configuration.md | Same as EN; consolidates reference content and points to new how-to guides. |
| docs/en/docs/how-to/deploy-server.md | Clarifies which routes require auth and that /docs shell stays public. |
| docs/zh/docs/how-to/deploy-server.md | Same as EN; clarifies auth boundaries for /docs and /openapi.json. |
| docs/en/docs/how-to/configure-server-environment.md | New how-to: generate, validate, and run from an explicit env file. |
| docs/zh/docs/how-to/configure-server-environment.md | New how-to: explicit env file workflow (ZH). |
| docs/en/docs/how-to/configure-vector-search.md | New how-to: embedding profile + capability verification for vector search. |
| docs/zh/docs/how-to/configure-vector-search.md | New how-to: vector search setup and capability verification (ZH). |
| docs/en/docs/how-to/configure-agent-skill-targets.md | New how-to: configure external Skill targets for discovery/publication. |
| docs/zh/docs/how-to/configure-agent-skill-targets.md | New how-to: configure Agent Skill targets (ZH). |
| docs/en/docs/how-to/configure-hermes.md | Updates internal link target for deployment guidance. |
| docs/en/docs/how-to/configure-codex.md | Updates internal links for Memory/Handoff boundary and handoff procedure. |
| docs/en/docs/how-to/configure-claude-code.md | Updates configuration reference link for plugin controls. |
| docs/en/docs/explanation/memory-and-handoff.md | Updates internal link to the handoff procedure. |
| docs/zh/docs/explanation/memory-and-handoff.md | Same as EN; updates internal link to the handoff procedure. |
| docs/en/docs/explanation/experience-and-skill-lifecycle.md | Updates internal links to review/how-to procedures. |
| docs/zh/docs/explanation/experience-and-skill-lifecycle.md | Same as EN; updates internal links to related how-to pages. |
| docs/en/docs/explanation/core-concepts.md | Updates internal links to review/how-to and reference pages. |
| docs/zh/docs/explanation/core-concepts.md | Same as EN; updates internal links to how-to and reference pages. |
Suppressed comments (4)
docs/en/docs/explanation/core-concepts.md:92
- This link is written as a root-relative URL (
/en/...), which can break if the docs are served under a subpath. Prefer a relative link to the how-to page.
The [Handoff Report](/en/docs/how-to/use-handoff-report/) projects current Handoff Revisions for inspection and export. The
docs/en/docs/explanation/core-concepts.md:107
- These root-relative links (
/en/...) may bypass the docs base path in some deployments. Prefer relative links to the reference pages.
Use [Interfaces](/en/docs/reference/interfaces/) for current surface availability and
[Configuration](/en/docs/reference/configuration/) for exact settings and defaults. RFCs record design decisions and may
docs/zh/docs/explanation/core-concepts.md:84
- 该链接使用了以
/zh/...开头的根路径，若站点部署在子路径可能会绕过 base path。建议改为相对链接。
[Handoff Report](/zh/docs/how-to/use-handoff-report/) 将当前 Handoff Revision 投影为可检查、可导出的视图。当前 scope
report 尚不包含 Activity event 或 period comparison，也不会改写 Memory 或底层 Handoff history。
docs/zh/docs/explanation/core-concepts.md:94
- 该行包含多个以
/zh/...开头的根路径链接，子路径部署时可能失效。建议改为相对链接以保证链接在不同部署前缀下都可用。
当前接口可用范围见[接口](/zh/docs/reference/interfaces/)，精确设置和默认值见[配置](/zh/docs/reference/configuration/)。RFC 记录
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
85
to
87
| Let the Hermes wizard store authorization in its protected `.env` secret store; do not put the token in | ||
| `config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](deploy-server.md) before connecting | ||
| `config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](/en/docs/how-to/deploy-server/) before connecting | ||
| to a remote deployment. Evaluation traces contain prompts and recalled context; keep them local and protect them as |
Comment on lines
68
to
+71
| Memory stores durable, reusable decisions, constraints, and state. A Handoff temporarily transfers the current task to | ||
| another task, session, or model. It must be explicitly prepared, inspected, and delivered, rather than substituted with | ||
| a few Memory entries. Read [Memory and Handoff](../explanation/memory-and-handoff.md) for the boundary and | ||
| [Hand off work in Codex](handoff-with-codex.md) for the procedure. | ||
| a few Memory entries. Read [Memory and Handoff](/en/docs/explanation/memory-and-handoff/) for the boundary and | ||
| [Hand off work in Codex](/en/docs/how-to/handoff-with-codex/) for the procedure. |
Comment on lines
131
to
133
| The timeout and flush controls are listed in the | ||
| [configuration reference](../reference/configuration.md#claude-code-plugin). They apply to the Hook process; the MCP | ||
| [configuration reference](/en/docs/reference/configuration/#claude-code-plugin). They apply to the Hook process; the MCP | ||
| client remains managed by Claude Code. |
| publish an approved managed Skill. Publication cannot select an arbitrary path or overwrite a foreign or modified | ||
| package. | ||
|
|
||
| For the configuration schema and compatibility form, see [Configuration](/en/docs/reference/configuration/). |
| `allow_managed_publish` 默认是 `false`。只在允许 authenticated Server 发布 approved managed Skill 的 target 上将其设为 | ||
| `true`。发布不能选择任意路径，也不会覆盖外部或已被修改的 package。 | ||
|
|
||
| 配置 schema 和兼容格式见[配置](/zh/docs/reference/configuration/)。 |
|
|
||
| 批准会写入不可变 Artifact Revision，并返回精确的 `result_artifact`。拒绝只记录 decision reason，不创建 Artifact。 | ||
| 两种决定都是终态。操作步骤见[审核 Candidate](../how-to/review-candidates.md)。 | ||
| 两种决定都是终态。操作步骤见[审核 Candidate](/zh/docs/how-to/review-candidates/)。 |
Comment on lines
39
to
+40
| Never store secrets, access tokens, or other sensitive information in either. For the Handoff procedure, see | ||
| [Hand off work in Codex](../how-to/handoff-with-codex.md). | ||
| [Hand off work in Codex](/en/docs/how-to/handoff-with-codex/). |
Comment on lines
34
to
+35
| 无论使用哪一种，都不要存储密钥、访问令牌或其他敏感信息。使用 Handoff 的具体步骤见 | ||
| [在 Codex 中交接工作](../how-to/handoff-with-codex.md)。 | ||
| [在 Codex 中交接工作](/zh/docs/how-to/handoff-with-codex/)。 |
Comment on lines
+69
to
+71
| Use [Review Candidates](/en/docs/how-to/review-candidates/) for the review procedure, | ||
| [Create and review an Experience](/en/docs/how-to/create-and-review-experience/) for Experience operations, and | ||
| [Create and export a managed Skill](/en/docs/how-to/create-and-export-skill/) for Skill operations. |
Comment on lines
+64
to
+66
| 审核步骤见[审核 Candidate](/zh/docs/how-to/review-candidates/)，Experience 操作见 | ||
| [创建并审核 Experience](/zh/docs/how-to/create-and-review-experience/)，Skill 操作见 | ||
| [创建并导出 managed Skill](/zh/docs/how-to/create-and-export-skill/)。 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #1226
Rationale for this change
Classify current documentation by purpose, move task procedures out of reference pages, and align the published docs with current Server contracts.
What changes are included in this PR?
Are there any user-facing changes?
Yes. Documentation navigation and setup guidance are clearer. No runtime API behavior changes.
How was this change tested?
.\.venv\Scripts\zensical.exe build -sgit diff --checkAI usage statement
Used Codex with the documentation-writer and humanizer skills. Maintainer review is required.