Repository maintenance: fix cross-link 404s, add LICENSE, CI checks, and contribution governance

.github/ISSUE_TEMPLATE/chapter-correction.yml

@@ -0,0 +1,67 @@
+name: Chapter correction / 章节纠错
+description: A passage contradicts the actual source behavior, a number is wrong, or a module's responsibility is misdescribed
+title: "[correction] "
+labels: ["correction", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Factual corrections are the highest-priority issue type here. A teardown that states something wrong gets quoted downstream as a conclusion, so thank you for catching it.
+
+        修正事实性错误是本仓库优先级最高的 issue。源码解读一旦写错，会被读者当结论引用。
+
+  - type: dropdown
+    id: chapter
+    attributes:
+      label: Chapter / 章节
+      options:
+        - "01 — Architecture Overview / 架构总览"
+        - "02 — Value Debate / 源码泄露的价值之争"
+        - "03 — Agent Loop / Agent 循环"
+        - "04 — Context Engineering / 上下文工程"
+        - "05 — Compaction System / 消息压缩系统"
+        - "06 — Permission System / 权限系统"
+        - "07 — Memory System / 记忆管理"
+        - "08 — Tools and Skills / 工具与 Skill 系统"
+        - "09 — MCP Integration / MCP 集成"
+        - "10 — Future Features / 未来功能蓝图"
+        - "11 — AI Code Review / AI Coding 时代的 Code Review"
+        - "12 — Agent Security Design / 从权限系统学 Agent 安全设计"
+        - "13 — Source Code Findings / 啃完源码之后的一些发现"
+    validations:
+      required: true
+
+  - type: input
+    id: language
+    attributes:
+      label: Which language version / 哪个语言版本
+      description: Chinese, English, or both
+      placeholder: both
+    validations:
+      required: true
+
+  - type: textarea
+    id: quote
+    attributes:
+      label: Quote the passage / 引用原文
+      description: Copy the sentence or table row as it currently reads, and say which section it is in.
+    validations:
+      required: true
+
+  - type: textarea
+    id: correction
+    attributes:
+      label: What it should say / 正确的描述是什么
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence / 证据
+      description: |
+        Required. Any one of: a source file path plus symbol name, reproducible steps that demonstrate the behavior, or a link to official documentation. An issue without evidence will be sent back before it can be acted on.
+
+        必填。三者任一即可：源码文件路径 + 符号名 / 可复现的操作步骤 / 官方文档链接。没有证据的 issue 会被要求补充后才处理。
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Read the docs online / 在线阅读
+    url: https://anneheartrecord.github.io/claude-code-docs/
+    about: The published site, with search across all 13 chapters.
+  - name: Contributing guide / 贡献指南
+    url: https://github.com/anneheartrecord/claude-code-docs/blob/main/CONTRIBUTING.md
+    about: What corrections are wanted, and the evidence bar for a factual correction.

.github/ISSUE_TEMPLATE/new-chapter.yml

@@ -0,0 +1,42 @@
+name: New chapter proposal / 新章节提议
+description: Propose a module or theme that deserves its own teardown
+title: "[chapter] "
+labels: ["new-chapter", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Proposals are welcome; whole AI-generated chapters submitted as pull requests are not. Open this first so the scope and the angle can be agreed on.
+
+        欢迎提议新章节；但不接受直接提交 AI 生成的整章 PR。先开这个 issue，把范围和切入角度谈好。
+
+  - type: input
+    id: topic
+    attributes:
+      label: Topic / 主题
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why it deserves a chapter / 为什么值得单开一章
+      description: What would a reader building an agent product be able to do afterward that they cannot do now?
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: What the chapter would cover / 章节大致覆盖什么
+      description: Rough section list is enough.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: overlap
+    attributes:
+      label: Overlap check / 重叠检查
+      options:
+        - label: I have read the existing 13 chapters and this is not already covered
+          required: true

.github/ISSUE_TEMPLATE/version-drift.yml

@@ -0,0 +1,50 @@
+name: Version drift / 版本漂移
+description: Upstream changed, and a chapter now describes a mechanism that no longer exists
+title: "[drift] "
+labels: ["version-drift", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The analysis was performed against a specific source snapshot — see the version coverage table in the README. Upstream moves; chapters go stale. Reporting drift is how this stays honest.
+
+        本仓库的分析基于某个特定的源码快照（见 README 的版本覆盖表）。上游会变，章节会过时。报告漂移是这份文档保持诚实的方式。
+
+  - type: input
+    id: chapter
+    attributes:
+      label: Chapter / 章节
+      placeholder: "06 — Permission System"
+    validations:
+      required: true
+
+  - type: textarea
+    id: described
+    attributes:
+      label: What the chapter describes / 章节里怎么写的
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What upstream does now / 上游现在的行为
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version you observed this in / 你观察到的版本
+      description: Output of `claude --version`, or the npm version.
+      placeholder: "2.1.227"
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence / 证据
+      description: Source path plus symbol, reproducible steps, changelog entry, or official documentation.
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!--
+中文贡献者可以用中文填写。
+Contributors may fill this in in Chinese or English.
+-->
+
+## What this changes / 改了什么
+
+<!-- One or two sentences. If it fixes an issue, write "Fixes #123". -->
+
+## Type / 类型
+
+- [ ] Factual correction / 事实纠错
+- [ ] Version drift update / 版本漂移更新
+- [ ] Translation or wording / 翻译与表述
+- [ ] Links, formatting, tooling / 链接、排版、工具链
+- [ ] New content / 新增内容 (discussed in an issue first / 已在 issue 中讨论过)
+
+## Evidence / 证据
+
+<!--
+Required for factual corrections and drift updates.
+Source path plus symbol, reproducible steps, or official documentation.
+事实纠错与版本漂移必填：源码路径 + 符号名 / 可复现步骤 / 官方文档。
+-->
+
+## Checklist / 自检
+
+- [ ] `python3 scripts/check_links.py` passes / 通过
+- [ ] `python3 scripts/check_bilingual.py` passes / 通过
+- [ ] Chinese and English sides both updated, if the change is factual / 事实性改动已中英双语同步
+- [ ] Commit messages follow Conventional Commits / commit message 符合 Conventional Commit
+- [ ] This PR does one thing / 这个 PR 只解决一件事

.github/workflows/docs-check.yml

@@ -0,0 +1,26 @@
+name: docs-check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Catch rot that arrives without anyone touching the repo.
+  schedule:
+    - cron: "0 2 * * 1"
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate links and link conventions
+        run: python3 scripts/check_links.py
+
+      - name: Validate bilingual chapter parity
+        run: python3 scripts/check_bilingual.py

.gitignore

@@ -0,0 +1,12 @@
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor scratch
+*.swp
+*~

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this documentation set are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/) adapted for documentation:
+
+- **MAJOR** — a chapter's conclusion changed, or chapters were added/removed
+- **MINOR** — substantive content added to an existing chapter
+- **PATCH** — corrections, link fixes, translation and wording repairs
+
+## [Unreleased]
+
+## [1.1.0] — 2026-08-11
+
+### Fixed
+
+- All 56 chapter cross-links resolved to `docs/<file>.md` from inside `docs/`, which 404'd in GitHub's file view and only worked on the docsify site. They are now same-directory relative and correct in both contexts. ([#1](https://github.com/anneheartrecord/claude-code-docs/pull/1))
+- `docs/12-Agent-Security-Design.md` linked to `13-啃完51万行源码的发现与Claude的封号机制.md`, a filename that no longer exists after chapter 13 was renamed. Dead in every context.
+- The Chinese chapter 12 pointed at chapter 13 under its old title.
+- `_sidebar.md` and `_home.md` now use root-absolute paths, required once `relativePath` is enabled.
+
+### Added
+
+- `LICENSE` — MIT, matching the declaration the READMEs have carried since the first release, plus a scope note clarifying that no Claude Code source is redistributed here.
+- `CONTRIBUTING.md` / `CONTRIBUTING_EN.md` — what corrections are wanted, the evidence bar for a factual correction, and the link conventions.
+- `CODE_OF_CONDUCT.md` — Contributor Covenant 2.1.
+- `scripts/check_links.py` — validates every local Markdown and image link and enforces the per-context link convention.
+- `scripts/check_bilingual.py` — flags chapters that exist in only one language or whose two sides have drifted apart in size.
+- GitHub Actions workflow running both checks on every push and pull request.
+- Issue templates for chapter corrections, version drift, and new chapter proposals; a pull request template.
+- Version coverage table in both READMEs, recording which source snapshot the analysis was verified against.
+- English chapter 01 expanded from a summary to full parity with the Chinese: source-leak background, what Claude Code is, how it differs from an agent framework, the six-step request journey, the industry comparison table, and the key-numbers table. It was previously 5.2 KB against 15 KB of Chinese.
+
+### Changed
+
+- docsify `relativePath` switched to `true` so a single link form works on the published site and on GitHub.
+- `.idea/` removed from version control and added to `.gitignore`.
+
+## [1.0.0] — 2026-04-24
+
+### Added
+
+- 13 chapters of teardown analysis in Chinese and English, covering architecture, the agent loop, context engineering, the compaction system, permissions, memory, tools and skills, MCP integration, the feature-flag roadmap, code review in the AI coding era, agent security design, and closing findings.
+- 59 hand-drawn illustrations across all 13 chapters.
+- docsify site published to GitHub Pages.
+
+[Unreleased]: https://github.com/anneheartrecord/claude-code-docs/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/anneheartrecord/claude-code-docs/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/anneheartrecord/claude-code-docs/releases/tag/v1.0.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Behavior that contributes to a positive environment:
+
+- Correcting a factual error is welcome and encouraged; correcting it with evidence is what makes it useful.
+- Disagreeing about a technical claim on the technical merits.
+- Accepting a correction gracefully when your own claim turns out to be wrong.
+- Being patient with contributors writing in their second language — this project is bilingual by design.
+
+Unacceptable behavior:
+
+- Harassment, insults, or derogatory comments, public or private.
+- Personal or political attacks.
+- Publishing others' private information without explicit permission.
+- Any conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This Code of Conduct applies in all project spaces — issues, pull requests, discussions — and when an individual is representing the project in public spaces.
+
+## Enforcement
+
+Report unacceptable behavior by opening a private security advisory on this repository, or by contacting the maintainer through the address on their GitHub profile. All complaints will be reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and security of the reporter.
+
+Maintainers who do not follow or enforce this Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.