create-yss-spec 2.1.11 → 2.1.13

package/template/.agents/skills/yss-design-system/references/design-qa-theme.md

@@ -0,0 +1,64 @@
+# Design QA 项目主题对照
+
+本文件给 Codex `$design-qa` 使用。官方 `design-qa` skill 仍负责截图对比流程和 `final result: passed|blocked`；本文件只提供项目视觉真相，不改上游插件正文。
+
+## Source visual truth
+
+- 规范：`docs/design/design.md`
+- Token：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/variables.css`
+- 实现截图：当前原型或页面在同一 viewport / 主题 / 状态下的渲染
+
+官方 `https://ant.design/design.md` 只是上游默认。项目覆盖与官方不同时，以项目覆盖为准。
+
+## 必查 fidelity surface（项目覆盖）
+
+### Colors and visual tokens
+
+| 角色 | 必须对照 | 记为 P1 token drift |
+| --- | --- | --- |
+| 主色 | `#3371ff` | `#1677ff` 或 `#3177ff` 当默认主色 |
+| 主色 hover / active | `#4096ff` / `#0958d9` | 用算法重算替代 `:root` 显式值且未记录 |
+| 错误色 | `#f5222d` | 官方 `#ff4d4f` 当默认错误色 |
+| 成功 / 警告 | `#52c41a` / `#faad14` | 改成非功能色装饰 |
+| 页面背景 | `#f0f2f5` | `#f5f5f5` 或其它灰底当默认 layout |
+| 容器 / 浮层 | `#ffffff` | 用卡片阴影堆叠替代表面层级 |
+| 主文本 / 次文本 | `rgba(0, 0, 0, 0.88)` / `rgba(0, 0, 0, 0.65)` | `#2e2e2e` / `#646464` 当默认文本 |
+| 边框 / 分割线 | `#d9d9d9` / `#f0f0f0` | `#dbdbdb` / `#f1f1f1` 当默认边框 |
+| 运行时变量 | `--primary-color` 指向 `--brand-color-primary` | 页面另写一套 Less 色值 |
+
+`blue` 预设色板里的 `#1677ff` 不是品牌主色，不要据此判定主色漂移。
+
+### Fonts and typography
+
+| 角色 | 必须对照 | 记为 P1 token drift |
+| --- | --- | --- |
+| 默认正文字号 | 14px | 16px 营销字号当正文 |
+| 默认控件高度 | 32px | 明显偏离 32px 且未走 compact algorithm |
+| 字体栈 | 系统栈（`-apple-system, BlinkMacSystemFont, "Segoe UI", ...`） | 强制 `Inter` 或其它未登记品牌字体 |
+| 字重 | 400 / 600 | 用 700+ 表达选中或激活 |
+
+### Spacing and layout rhythm
+
+| 角色 | 必须对照 | 记为 P1 token drift |
+| --- | --- | --- |
+| 圆角 | 小控件 4px、默认 6px、容器 8px | 历史品牌 8px / 10px，或 Less 前半 4px 当全局默认 |
+| 间距网格 | 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48 | 任意 magic number 撑开中后台密度 |
+| 顶栏 / 侧栏 | 顶栏 64px，深色侧栏 `#001529` | 未说明就改成营销式顶栏 |
+
+### Image quality and copy
+
+沿用官方 `design-qa` 规则。本主题不引入插画、logo 或营销文案；出现这类素材时按官方 rubric 记 finding，并同时记为偏离中后台定位。
+
+## 判定
+
+- 仍用官方 `#1677ff`、强制 `Inter` 或 8px 品牌圆角作为默认主题：P1。
+- 只改局部组件、且 `prototype-evidence.yaml` 的 `theme_override` 已记录：按官方 severity 评估，不自动升 P1。
+- 暗色模式：本轮未重派生完整暗色色板；暗色对照前若缺少新的 algorithm 派生证据，`final result: blocked`，写明 blocker。
+
+## 报告要求
+
+`design-qa.md` 必须写明：
+
+- source visual truth path：`docs/design/design.md` 与对应 token 文件
+- 已按本清单核对 Colors/tokens 与 Fonts/typography
+- 与官方默认的差异是否被接受为项目覆盖

package/template/.agents/skills/yss-design-system/references/design-system.md

@@ -39,22 +39,22 @@
 
 | Token | 值 | 用途 |
 | --- | --- | --- |
-| `colorPrimary` | `#1677ff` | 主操作、链接、焦点、选中态 |
+| `colorPrimary` | `#3371ff` | 主操作、链接、焦点、选中态 |
 | `colorPrimaryHover` | `#4096ff` | 主色 hover |
 | `colorPrimaryActive` | `#0958d9` | 主色 active |
 | `colorSuccess` | `#52c41a` | 成功状态 |
 | `colorWarning` | `#faad14` | 警告状态 |
-| `colorError` | `#ff4d4f` | 错误状态 |
-| `colorInfo` | `#1677ff` | 信息提示 |
-| `colorBgLayout` | `#f5f5f5` | 页面背景 |
+| `colorError` | `#f5222d` | 错误状态 |
+| `colorInfo` | `#3371ff` | 信息提示 |
+| `colorBgLayout` | `#f0f2f5` | 页面背景 |
 | `colorBgContainer` | `#ffffff` | 内容容器 |
 | `colorBgElevated` | `#ffffff` | 浮层容器 |
-| `colorText` | `#2e2e2e` | 主文本 |
-| `colorTextSecondary` | `#646464` | 次级文本 |
-| `colorTextTertiary` | `#949494` | 弱说明 |
-| `colorTextQuaternary` | `#c4c4c4` | placeholder / disabled |
-| `colorBorder` | `#dbdbdb` | 主边框 |
-| `colorBorderSecondary` | `#f1f1f1` | 次级分割线 |
+| `colorText` | `rgba(0, 0, 0, 0.88)` | 主文本 |
+| `colorTextSecondary` | `rgba(0, 0, 0, 0.65)` | 次级文本 |
+| `colorTextTertiary` | `#8c8c8c` | 弱说明 |
+| `colorTextQuaternary` | `#bfbfbf` | placeholder / disabled |
+| `colorBorder` | `#d9d9d9` | 主边框 |
+| `colorBorderSecondary` | `#f0f0f0` | 次级分割线 |
 
 颜色规则：
 
@@ -63,7 +63,10 @@
 - 预设色板只用于 Tag、图表、分类可视化，不用于重新定义主操作。
 - 不硬编码白色、灰色、状态色；优先引用 token、CSS variables 或 Ant Design theme。
 - semantic token 优先于色值：页面先声明背景、容器、浮层、文本、边框、状态等角色，再映射到具体 token。
+- 运行时短名 `--primary-color`、`--text-color`、`--bg-color` 必须指向 `--brand-*`，不要再维护第二套色值。
+- `blue` 等预设色板可以仍含官方 `#1677ff`；色板预设 ≠ 品牌主色。
 - accessibility contrast 不足时，通过 `ConfigProvider` 的 seed token 或组件 token 调整；不要为单个页面制造不可复用的深浅色例外。
+- Codex `$design-qa` 的 token / 字体对照读 `references/design-qa-theme.md`。
 
 ### 排版
 
@@ -81,6 +84,7 @@
 
 - UI 默认正文 14px。
 - UI 字重优先 400 / 600。
+- 字体栈使用系统字体，不强制 `Inter`。
 - 不用 700+ 粗体表达选中或激活状态。
 - 选中状态优先使用颜色、边框、下划线、背景表达。
 
@@ -93,8 +97,12 @@
 | 小控件高度 | 24px |
 | 大控件高度 | 40px |
 | 默认字号 | 14px |
-| 当前品牌默认圆角 | 8px |
-| 大容器 / 浮层圆角 | 10px |
+| 字体栈 | 系统栈，不强制 `Inter` |
+| 小控件圆角 | 4px |
+| 默认控件圆角 | 6px |
+| 大容器 / 浮层圆角 | 8px |
+| 顶栏高度 | 64px |
+| 深色侧栏 | `#001529` |
 
 执行规则：
 

package/template/.agents/skills/yss-product-lifecycle/SKILL.md

@@ -29,7 +29,7 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 入口分诊 | 身份、影响面、最近可信阶段 | `yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
 | 机会调研/需求分析 | Discovery、用户/MVP/非目标/成功标准、测试 seam | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，用户确认，无 runnable blocker |
 | Spec/功能架构 | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 人工批准后资产才为 `approved` 并进入下游 |
-| 原型设计 | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `yss-design-system` → `yss-prototype-stage` → Codex `product-design:index`（非 Codex 交付等价合同） | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有证据 |
+| 原型设计 | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `yss-design-system` → `yss-prototype-stage` → `yss-antd-design`（仅原型事实）→ Codex `product-design:index`（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有证据 |
 | 技术分析 | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查 | `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-router` | API/架构契约冻结；无 API 影响有明确记录；脚手架策略满足 |
 | Ticket 正式化 | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本 |
 | 技术实现 | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`implement` 为兼容入口；前端按 `yss-ui` + `yss-page-module-development`，后端按 `yss-router` 最小闭包，业务行为统一 `tdd` | 只写允许路径；业务行为用 `behavior-tdd`；UI 影响必须有还原计划 |

package/template/.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -138,7 +138,7 @@ work_unit_routes:
     human_gate: spec-baseline
   work-unit.prototype-design:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
-    skills: [yss-design-system, yss-prototype-stage, product-design:index]
+    skills: [yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
     human_gate: prototype-confirmation
   work-unit.technical-analysis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}

package/template/.agents/skills/yss-prototype-stage/SKILL.md

@@ -25,7 +25,9 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 优先级固定为：官方 `design.md` 的上游默认 → `docs/design/design.md` 与项目 token 的 `project_design` 项目覆盖 → 当前功能的语义组件映射。不得用上游默认覆盖项目 token。
 
-使用官方 `antd` skill / CLI 查询事实，始终用 `--format json`，并记录实际 `antd`、CLI 和目标组件版本。至少保存 `antd design.md`、已选组件的 `info`/`demo`/`token`/`semantic` 查询和 `antd lint` 结果；目标版本存在时，将同一 `<target_antd_version>` 传给版本敏感查询，禁止在模板中固化某个 CLI 或组件版本。
+Codex `$design-qa` 仍走官方对比流程；Colors/tokens 与 Fonts/typography 必须以项目覆盖为 source visual truth。对照清单见 `yss-design-system/references/design-qa-theme.md`。仍用官方 `#1677ff`、强制 `Inter` 或历史 8px 品牌圆角当默认主题，视为项目覆盖漂移。
+
+Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列调用官方 `antd` skill，也不要在前端代码落地时继续使用它。进入实现后改走 `yss-ui`。
 
 ## 验证与回流
 

package/template/.agents/skills/yss-ui/SKILL.md

@@ -30,7 +30,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
 
-产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。
+产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于原型设计构建，进入本技能后不得再调用。
 
 ## 3. 组件选型门禁
 

package/template/.claude/skills/high-fidelity-html-prototype/SKILL.md

@@ -24,24 +24,7 @@ If low-fidelity `prototype-review` is blocked or missing, stop and return to `ys
 
 ## Ant Design Official Agent Baseline
 
-Use the official Ant Design agent guidance as the fact baseline through `yss-prototype-stage`:
-
-- Read or reference `https://ant.design/docs/react/for-agents` when the task starts.
-- Use `@ant-design/cli` before choosing unfamiliar components, props, tokens, or migration-sensitive APIs.
-- Prefer direct CLI subcommands because `--help` may fail in some Node environments while subcommands still work.
-
-Record the installed CLI version and the target AntD version in `prototype-evidence.yaml`. Use `--format json`; pass the recorded target version to version-sensitive queries:
-
-```bash
-antd design.md --format json
-antd info Button --version <target_antd_version> --format json
-antd token Button --version <target_antd_version> --format json
-antd demo Select basic --version <target_antd_version> --format json
-antd semantic Button --version <target_antd_version> --format json
-antd lint <prototype-path> --format json
-```
-
-Use the project-selected version when one exists; otherwise record the CLI's actual default version before making version-sensitive decisions. Record every queried component in the evidence manifest.
+Ant Design v6 事实由 `yss-antd-design` 执行并回写 `prototype-evidence.yaml`。本兼容入口不并列调用官方 `antd` skill，也不在前端代码落地时使用；实现改走 `yss-ui`。
 
 ## Core Rules
 

package/template/.claude/skills/llm-wiki/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: llm-wiki
+description: >
+  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
+  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
+  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
+  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
+  an existing wiki.
+---
+
+# llm-wiki
+
+Compile a persistent wiki from live documents and code. The wiki is the IR; live sources are the truth. Read [schema](references/schema.md), then the matching mode file.
+
+One-off notes are out of scope. Use this skill to compile or lint a persistent wiki (`raw/` + `wiki/` + `.wiki-manifest.json`), or to answer from an existing wiki per [query.md](references/query.md).
+
+## Mode
+
+| User intent | Mode | Completion |
+|---|---|---|
+| 从零构建知识库 | `init` | 三层目录 + schema + index + log + 文章 + `.wiki-manifest.json`，lint 退出 0 |
+| 源变了，更新受影响页 | `refresh` | 只改漂移命中的文章；human-owned 不改；lint 0；log 有 REFRESH |
+| 全局按新源重编译 | `rebuild` | raw 对齐 live；稳定 ID 与 human-owned 保留；LLM 页全量重写；lint 0；log 有 REBUILD |
+| 健康检查 | `lint` | 结构脚本 exit 0 + 已跑 advise 并报告条数；对变更页做 live 源抽查 |
+| 把点名外源或已落盘 research 笔记编进 wiki | `ingest` | raw 登记 + manifest 源 + 四态候选经确认后写页；lint 0；log 有 `INGEST` |
+
+Ambiguous → ask. Existing wiki + "构建" → ask refresh vs rebuild, do not init over it.
+
+Query is not a mode. Follow [query.md](references/query.md). Query never writes and never ingests.
+
+## Layout
+
+```
+<wiki-root>/
+  raw/                  # immutable copies + labelled extracts
+  wiki/                 # articles + index.md + log.md + CLAUDE.md
+  .wiki-manifest.json   # compile graph (sources ↔ articles)
+```
+
+Scripts live in this skill's `scripts/` directory (the folder that contains this `SKILL.md`). Run them from the repo root so `--wiki` / `--repo` resolve correctly:
+
+```bash
+node <skill-root>/scripts/inventory.mjs hash --wiki <wiki-root>
+node <skill-root>/scripts/inventory.mjs status --wiki <wiki-root>
+node <skill-root>/scripts/lint-wikilinks.mjs <wiki-root>
+node <skill-root>/scripts/advise.mjs <wiki-root>
+node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <wiki-root>/<rawPath>
+```
+
+`status` is a stable alias of `drift`. `<skill-root>` is the canonical skill directory or a projection that points at it. Do not hard-code `.agents/skills/llm-wiki`.
+
+## Steps
+
+1. Detect: `wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists.
+2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
+3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
+4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).
+5. Run structural lint and advise. Append `log.md`. Stop.
+
+`refresh` without a manifest: stop. Rebuild, or reconstruct the manifest from existing「来源」sections — do not guess `sourceIds`.

package/template/.claude/skills/llm-wiki/assets/CLAUDE.md.template

@@ -0,0 +1,26 @@
+# CLAUDE.md — Wiki schema
+
+本文档是本 wiki 的 schema（结构契约）。正文语言遵循宿主项目的文档语言规则；英文专有名词、类名、枚举值、表名与 API 路径保持原样。
+
+## 三层结构
+
+- **`raw/`** — 不可变原始源。从 live 文档拷贝，或从 live 源提取且标明出处的派生摘要。只读，不靠改 raw 来「修正」事实。
+- **文章（`wiki/*.md`）** — LLM 生成的知识文章。文件名（不含 `.md`）即文章 ID，必须全局唯一。使用 `[[wikilink]]` 互引。
+- **`index.md`** — 内容目录。`##` 节标题定义分类；节下列出该分类下的 `[[wikilink]]`。
+
+## 文章写作约定
+
+- 首行为 `# H1`，随后紧跟首段摘要。
+- 正文使用 `[[目标文章名]]`；目标必须是本 wiki 内存在的文章文件名（不含 `.md`）。
+- 论断必须能追溯到 `raw/` 或 live 代码路径。文末使用 `## 来源`。
+- 分类归属由 `index.md` 决定。
+- 可选 frontmatter：`human-owned: true` 时 refresh / rebuild 不得重写正文。
+- 仅当多个来源冲突，或 live 与旧 raw 不一致时写可选 `## Status`（`Disputed` / `Outdated`）。单一 live 正确则不写。
+
+## 基础设施文件
+
+`index.md`、`log.md`、`CLAUDE.md`、`AGENTS.md`、`soul.md`、`concept-table.md` 为基础设施文件，不视为文章。
+
+## 操作日志
+
+`log.md` 只追加。格式：`## [YYYY-MM-DD] OPERATION | 描述`（CREATE / UPDATE / LINK / FIX / REFRESH / REBUILD / RETIRE / LINT / INGEST）。

package/template/.claude/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+fixture schema

package/template/.claude/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/index.md

@@ -0,0 +1,5 @@
+# broken fixture
+
+## 分类
+
+- [[存在的页]]

package/template/.claude/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/log.md

@@ -0,0 +1 @@
+# 操作日志

package/template/.claude/skills/llm-wiki/assets/fixtures/broken-wiki/wiki//345/255/230/345/234/250/347/232/204/351/241/265.md

@@ -0,0 +1,7 @@
+# 存在的页
+
+摘要。引用了 [[不存在的页]]。
+
+## 来源
+
+- fixture

package/template/.claude/skills/llm-wiki/references/compile.md

@@ -0,0 +1,126 @@
+# Compile modes
+
+Manifest schema is the incremental-compile graph. The agent fills `id`, `kind`, `livePath`, `rawPath`, `role`, `extract` (derived only), `articles`. Scripts fill `sha256`, `compiledAt`, `gitCommit`.
+
+## Manifest
+
+Path: `<wiki-root>/.wiki-manifest.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "wikiRoot": "wiki/example",
+  "compiledAt": "ISO-8601",
+  "gitCommit": "hex or empty",
+  "profile": "mixed",
+  "sources": [
+    {
+      "id": "schema.sql",
+      "kind": "document",
+      "livePath": "apps/.../schema.sql",
+      "rawPath": "raw/schema.sql",
+      "sha256": "...",
+      "role": "copy"
+    },
+    {
+      "id": "skills-lock.json",
+      "kind": "derived",
+      "livePath": "skills-lock.json",
+      "rawPath": "raw/skills-lock-names.md",
+      "role": "extract",
+      "extract": { "kind": "skill-names" }
+    }
+  ],
+  "articles": [
+    {
+      "id": "连接器管理",
+      "file": "wiki/连接器管理.md",
+      "sourceIds": ["schema.sql"],
+      "humanOwned": false
+    }
+  ]
+}
+```
+
+`profile`: `mixed` (docs + code), `documents`, `code`.
+
+Source kinds:
+
+| kind | raw | when it drifts |
+|---|---|---|
+| `document` | copy of `livePath` | sync raw, rewrite articles that list this `id` |
+| `derived` | extract from `livePath` | re-run extract, rewrite dependents |
+| `code-surface` | none (`rawPath` null) | rewrite dependents; do not copy source into raw |
+
+`livePath` is repo-relative. `rawPath` is wiki-root-relative. `file` is wiki-root-relative.
+
+Article id = basename of `file` without `.md`. Renames are explicit `LINK` / `RETIRE`, never a silent refresh side effect.
+
+## Derived extracts
+
+Every `kind: derived` source must set `extract.kind` to one of `skill-names`, `heading-list`, or `prose-note`. Refresh and rebuild re-run that recipe into `rawPath`. Do not copy the live file in full.
+
+Shared rules:
+
+1. Input is `livePath` (or the live files the recipe names).
+2. Output is `rawPath` only.
+3. Sort or section order must be stable and documented for that kind.
+4. The extract must be smaller than the live input and must not include secrets, hashes, or lock metadata unless the recipe says those names are the payload.
+5. Replay the same recipe on drift; do not hand-edit raw to "fix" names.
+
+| `extract.kind` | Replay |
+|---|---|
+| `skill-names` | `extract.mjs skill-names --in <livePath> --out <wiki-root>/<rawPath>`. Lists `skills.shared` and `skills.platform` keys, `localeCompare` sorted. No hashes or paths. |
+| `heading-list` | Agent: list headings from the live file in document order, verbatim. No body copy. No script in this skill. |
+| `prose-note` | Agent: short labelled note that cites the live inputs. Stable section order. No full-file copy. No script in this skill. |
+
+## init
+
+Done when the target is a detectable Karpathy wiki and lint exits 0.
+
+1. If `wiki/index.md` already exists: ask refresh vs rebuild. Do not init over it.
+2. Ask: wiki path, corpus roots, coverage, and body language (follow the host project's document-language rule). See [discover.md](discover.md).
+3. Discover corpus with the [discover.md](discover.md) checklist. Do not ingest `docs/` wholesale.
+4. Write raw copies/extracts. Write manifest source list. Run `inventory.mjs hash`.
+5. Write `wiki/CLAUDE.md` from the template, adapted to this corpus — do not hard-code a previous product name.
+6. Write `index.md` categories first, then articles. Categories are index `##` headings.
+7. Orchestrator writes hub pages. Other pages go to subagents with disjoint file lists ([writing.md](writing.md)).
+8. Lint. Sample live-source facts. Append `log.md` `CREATE`.
+
+## refresh
+
+Done when only drift-hit articles change, human-owned pages are untouched, lint exits 0, and log has a structured `REFRESH`.
+
+1. No manifest → stop. Rebuild, or rebuild the manifest from existing「来源」sections. Do not invent `sourceIds`.
+2. `inventory.mjs status` (alias of `drift`) against every `livePath`. Pass each Agent-listed new file as `--candidate <livePath>`. Do not scan the tree. Read the JSON keys `changed`, `missing`, `unchanged`, `articles`, `unmapped`, `humanOwned`. Non-empty `changed` or `missing` is stale. Exit `0` with that JSON is normal, not a failure. Exit `2` is a script error.
+3. Impact set = `articles`. Rewrite those pages except `humanOwned` (wikilinks only).
+4. For `document` / `derived`: update raw first (derived: re-run `extract`), then rewrite hit articles.
+5. Each `unmapped` live path must get one triage: `New` / `Update` / `Disputed` / `No material`. Do not create pages silently. `No material` appends log only.
+6. Deleted sources → mark missing in citing articles; do not delete pages silently.
+7. Unhit articles: zero bytes changed.
+8. Rewrite is not "rewrite the whole wiki and call it refresh".
+9. Lint. Sample facts on hit pages. Append `REFRESH` with machine-readable fields:
+
+```
+## [YYYY-MM-DD] REFRESH | <summary>
+- changed: <sourceId>, ...
+- missing: <sourceId>, ...
+- articles: <articleId>, ...
+- unmapped: <livePath> (New|Update|Disputed|No material)
+```
+
+Omit an empty `changed` / `missing` / `articles` line. Repeat `unmapped` once per candidate. `status` / `drift` never fail just because those arrays are non-empty.
+
+## rebuild
+
+Done when raw matches live, LLM-owned pages are rewritten, stable ids and human-owned pages remain, lint exits 0, and log has `REBUILD`.
+
+1. Rediscover corpus with [discover.md](discover.md). Do not trust the old source list as complete.
+2. Recopy / re-extract raw.
+3. Keep article ids that still earn a page. Retired ids: `RETIRE` in log, drop from index.
+4. `humanOwned: true` (frontmatter or manifest): fix wikilinks only.
+5. Rewrite remaining articles. Rebuild index (categories may evolve).
+6. Replace manifest via `inventory.mjs hash`.
+7. Full lint + sample + `REBUILD`.
+
+rebuild is not `rm -rf wiki`. Stable ids keep old `[[wikilink]]` and external links valid.

package/template/.claude/skills/llm-wiki/references/discover.md

@@ -0,0 +1,41 @@
+# Discover corpus
+
+Discovery is an Agent checklist, not a scanner. Use it for `init` and `rebuild`. Confirm the answers, then write sources. Do not silently ingest every markdown file.
+
+## Ask first
+
+1. Wiki path (`<wiki-root>`).
+2. Corpus roots the user wants covered.
+3. Coverage: `core` (authoritative process / contract files) or `full` (core plus extra docs the user names).
+4. Body language: follow the host project's document-language rule.
+
+If any answer is missing, ask. Do not guess from directory names or Git remotes.
+
+## Default include (core)
+
+Unless the user replaces this list with the host's single source-of-truth table:
+
+- Root authoritative files (for example `README`, `AGENTS`, `CONTEXT`, repository-identity manifest)
+- `docs/adr/`
+- `docs/process/`
+- `docs/agents/`
+- `docs/templates/`
+- Frozen contracts the user names
+
+`full` adds only roots the user listed. It is not "everything under `docs/`".
+
+## Default exclude
+
+- `docs/reviews/`
+- `docs/.scratch/`
+- Agent projection directories (copies or symlinks of shared skills)
+- `node_modules`
+- Whole lock files (`package-lock.json`, `pnpm-lock.yaml`, `skills-lock.json` as a document). A lock may appear only as `kind: derived` with an `extract` recipe.
+
+## Threshold
+
+If the candidate `document` count would exceed 40, list the candidates and stop. Do not write `raw/`, articles, or the manifest until the user confirms the list.
+
+## After the list is confirmed
+
+Write raw copies or extracts, then fill manifest `sources` per [compile.md](compile.md). Derived sources need `extract`. Code surfaces are not copies.

package/template/.claude/skills/llm-wiki/references/ingest.md

@@ -0,0 +1,36 @@
+# Ingest
+
+Ingest is a compile mode. It adds a user-named external source or an already-written research note to the wiki. It does not replace `refresh`.
+
+Query must not ingest. Mapped live sources that changed go to `refresh`.
+
+## Allowed inputs
+
+- A URL, paste, or file outside the repo that the user named in this turn.
+- An already-written research note on disk (for example under the host's research archive). One-off fact gathering still belongs to the host's research skill; ingest only compiles a note that already exists.
+
+Forbidden inputs: `docs/reviews/`, `docs/.scratch/`, agent projection directories, lock files as documents, and any live authoritative file that is already a manifest `livePath`.
+
+Do not treat a web search as this skill's `refresh`. Confirm new web material as a named input first.
+
+## Done when
+
+`raw/` has the copy or labelled extract, the manifest lists the source, triage is recorded, confirmed pages are written (or none if the user declined), structural lint exits 0, advise has been run, and `log.md` has `INGEST`.
+
+## Steps
+
+1. Detect the wiki. No `wiki/index.md` → suggest `init`. Stop.
+2. If the path is already a manifest `livePath` → stop and use `refresh`.
+3. Write `raw/` as a copy or a labelled extract. Do not invent `extract.kind` values. Do not edit live authoritative files.
+4. Add a manifest source (`kind: document` or `derived`) with `livePath` (repo-relative when the file is in-repo; otherwise leave a labelled extract and record the origin in the extract header). Do not create a second config file (`inbox.md`, YAML sidecars). The pending queue is the new source plus the log.
+5. Run `inventory.mjs status --wiki <wiki-root> --candidate <livePath>` if the input is in-repo. Assign each unmapped path or new source one triage: `New` / `Update` / `Disputed` / `No material`.
+6. Show the candidate article list. **Stop until the user confirms.** Unconfirmed ingest changes zero article bytes. `No material` writes log only.
+7. After confirmation: write or update only the confirmed pages. Use `## Status` when triage is `Disputed`. Follow [writing.md](writing.md).
+8. `inventory.mjs hash`. Structural lint. Advise (report counts). Sample live/raw facts on changed pages. Append:
+
+```
+## [YYYY-MM-DD] INGEST | <summary>
+- source: <sourceId>
+- disposition: New|Update|Disputed|No material
+- articles: <articleId>, ...
+```

package/template/.claude/skills/llm-wiki/references/lint.md

@@ -0,0 +1,54 @@
+# Lint
+
+From the repo root, run this skill's scripts (resolve `<skill-root>` from the directory that contains `SKILL.md`):
+
+```bash
+node <skill-root>/scripts/lint-wikilinks.mjs <wiki-root>
+node <skill-root>/scripts/advise.mjs <wiki-root>
+```
+
+`lint-wikilinks.mjs` exit 0 only when every structural check below passes. `advise.mjs` always prints JSON and exits `0` when the report is valid (exit `2` is a script error). Advise never fails lint and never auto-fixes.
+
+## Script checks
+
+- Every `[[target]]` in articles and `index.md` resolves to `wiki/target.md` (infrastructure filenames are not valid article targets). Cross-path targets such as `[[../other]]` fail; they are not ignored.
+- Every article H1 equals the article id (filename without `.md`).
+- Every `[[wikilink]]` in `index.md` exists on disk.
+- Every article file appears in `index.md`. Orphans fail.
+- Every article has a `## 来源` heading.
+- Infrastructure files are not articles: `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`, `soul.md`, `concept-table.md`.
+- Missing `## Status` is not a failure.
+- If `.wiki-manifest.json` exists:
+  - each `articles[].file` exists; each `sources[].livePath` exists when set; `sha256` mismatch is stale (fail)
+  - every non-infrastructure `wiki/*.md` appears in `articles[]`
+  - each `articles[].id` equals the basename of `file` without `.md`
+  - each `sourceIds[]` exists in `sources[].id`
+  - `profile === "documents"` forbids `kind: code-surface`
+  - `kind: document|derived` requires a `rawPath` whose file exists; `code-surface` requires `rawPath == null`
+  - `kind: derived` requires `extract.kind` in `skill-names` | `heading-list` | `prose-note`
+
+`STALE HASH` during lint means the wiki is being claimed healthy while live files drifted. That is separate from `inventory.mjs status`, which reports the same drift with exit `0`.
+
+## Advise (do not repair)
+
+After the structural script, run `advise.mjs` and report the counts. JSON keys:
+
+- `oneWayLinks`: article A → B and B has no link back to A. `index.md` links do not count as backlinks.
+- `missingTermPages`: backtick identifiers, `**bold**` phrases, or `##` headings that appear at least twice and are not an article id.
+- `unreferencedRaws`: manifest `rawPath` values not cited in any article `## 来源`.
+- `suspects`: high-signal literals (number+suffix such as `42K`, ISO dates, quoted strings of length ≥ 12) in the article body that do not appear in the cited live/raw files.
+
+Do not create pages. Do not rewrite numbers. Do not promote `suspects` to lint exit 1.
+
+## Agent checks (after scripts)
+
+From changed pages, sample `N = min(5, changed page count)` claims against **live** files, not against the wiki text just written.
+
+Look for: enum members, HTTP statuses, "persisted vs in-memory", hardcoded vs configured values, freeze coverage vs extra controllers. Advise cannot replace this pass.
+
+## Repair
+
+- Broken wikilink: add the page, retarget, or remove the link. Do not leave dangling `[[...]]`.
+- Stale hash: run refresh on that source, or `inventory.mjs hash` after a deliberate raw sync.
+- Missing manifest on an otherwise valid wiki: reconstruct from「来源」or rebuild. Do not invent mappings.
+- Advise findings: report only, unless the user asked to act on a specific item.

package/template/.claude/skills/llm-wiki/references/query.md

@@ -0,0 +1,21 @@
+# Query
+
+Query is not a compile mode. It reads the wiki; it does not write `raw/`, articles, `index.md`, `log.md`, or `.wiki-manifest.json`.
+
+Use this algorithm when the user asks a repository question and a wiki exists, or asks to answer from the wiki. Do not open the whole corpus, and do not treat wiki prose as live fact.
+
+## Steps
+
+1. **Detect.** If `wiki/index.md` is absent, say the question is outside query: no wiki exists. Suggest `init`. Stop.
+
+2. **Freshness.** If `.wiki-manifest.json` exists, run `inventory.mjs status --wiki <wiki-root>` (same JSON as `drift`). Read `changed`, `missing`, `unchanged`, `articles`, `unmapped`, `humanOwned`. Exit `0` is a valid report, not a failure. Exit `2` is a script error. Show that source-status table. Non-empty `changed` or `missing` means stale: name those sources, ask whether to `refresh`, and do not present drifted pages as current fact. If the user still wants an answer, mark every claim that depends on a drifted source as stale.
+
+3. **Select pages.** First match proper nouns and distinctive terms against `index.md` category headings (`##`) and `[[wikilink]]` targets. If that set is empty or clearly too narrow for the question, search H1 and the first paragraph of each non-infrastructure `wiki/*.md` with the question's distinctive terms and obvious synonyms (`rg` is enough; do not build an index). Open at most `N = min(8, hit count)` articles. Do not open the whole wiki. Do not answer from one summary paragraph when more hit pages exist.
+
+4. **Verify claims.** For each assertion, re-read the live paths in that page's `## 来源` (repo-relative live files, not the wiki sentence). If wiki text conflicts with live, cite live and record wiki drift. Do not rewrite the wiki during query. Do not ingest.
+
+5. **Zero hits.** Only after **both** the index/`[[wikilink]]` pass and the H1/summary search are empty may you say the wiki does not cover the question. List the index categories considered and the search terms used. Do not invent article ids, pages, or facts.
+
+## Done when
+
+The answer cites the pages actually opened and the live sources actually re-read, or it states non-coverage. Query never completes via lint, `CREATE`, `REFRESH`, `REBUILD`, or `INGEST`.