Merge pull request #1 from anneheartrecord/chore/maintenance-2026-08

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

Author: anneheartrecord

.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
+*~