create-yss-spec 2.1.10 → 2.1.13

package/template/.pi/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/.pi/skills/yss-web-controller/SKILL.md

@@ -63,6 +63,7 @@ node scripts/generate_controller.mjs \
 
 ## 按需读取
 
+- 分层开发规范：`references/web-adapter-layer-guide.md`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`

package/template/.pi/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -0,0 +1,168 @@
+本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
+Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **Request Handling**: Map HTTP requests (GET, POST, PUT, DELETE) to Java methods.
+- **Input Validation**: Validate request bodies and parameters using JSR-303/380 annotations (`@Valid`, `@NotNull`, etc.).
+- **Response Formatting**: Wrap business results into standard `Result` objects (`SingleResult`, `PageResult`, `MultiResult`).
+- **Orchestration Delegation**: Delegate business logic to the **Application Service**. Simple queries can be delegated directly to the **Domain Gateway** (CQRS pattern).
+
+## 2. 代码结构 (Code Structure)
+
+Web Adapters are typically located in the `bootstrap` module or a dedicated `web` module.
+
+```
+com.yss.{module}.rest
+├── {Domain}Controller.java      # Main REST Controller
+└── {Domain}ReportController.java # Optional: For reporting/stats APIs
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 Controller 定义
+
+- **注解**: 使用 `@RestController`。
+- **路径**: `@RequestMapping("/api/{module}/{domain}")` (e.g., `/api/quality/rule`).
+- **依赖注入**: 使用 Lombok `@RequiredArgsConstructor` 进行构造器注入。
+- **命名**: `{Domain}Controller` (e.g., `QualityRuleController`).
+
+### 3.2 依赖注入原则
+
+- **写操作/复杂逻辑**: 必须注入 **Application Service** (`XxxService`)。
+- **读操作 (Query)**: 允许直接注入 **Domain Gateway** (`XxxGateway`) 以减少样板代码 (CQRS)。
+
+### 3.3 参数与响应
+
+- **Command (写)**: 使用 `@PostMapping`/`@PutMapping` + `@RequestBody` + `{Domain}Cmd` 对象。
+- **Query (读)**: 使用 `@PostMapping` (for complex search) + `@RequestBody` + `{Domain}Page/Query` 对象。
+- **Wrapper**:
+  - `SingleResult<T>`: 单个对象或基本类型。
+  - `MultiResult<T>`: 列表。
+  - `PageResult<T>`: 分页数据。
+- **Validation**: 必须在参数前添加 `@Valid` 注解。
+
+### 3.4 异常处理
+
+- **不要**在 Controller 中捕获通用异常 (`Exception`)。
+- 让全局异常处理器 (`GlobalExceptionHandler`) 统一处理运行时异常。
+- 仅在需要特定 HTTP 状态码转换时捕获特定异常。
+
+## 4. 代码示例 (Code Examples)
+
+### 4.1 标准 CRUD Controller
+
+```java
+package com.yss.{module}.rest;
+
+import com.yss.cloud.dto.result.MultiResult;
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import com.yss.{module}.client.dto.cmd.{Domain}AddCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}UpdateCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}StatusCmd;
+import com.yss.{module}.client.dto.query.{Domain}Page;
+import com.yss.{module}.client.vo.{Domain}VO;
+import com.yss.{module}.core.service.{Domain}Service;
+// Optional: Import Gateway for direct queries
+// import com.yss.{module}.domain.gateway.{Domain}Gateway;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import javax.validation.Valid;
+
+/**
+ * {Domain} 管理控制器
+ *
+ * @author {User}
+ */
+@RestController
+@RequestMapping("/api/{module}/{domain-path}")
+@RequiredArgsConstructor
+public class {Domain}Controller {
+
+    private final {Domain}Service {domainVar}Service;
+    // private final {Domain}Gateway {domainVar}Gateway; // For CQRS if needed
+
+    /**
+     * 分页查询 {Domain}
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @PostMapping("/page")
+    public PageResult<{Domain}VO> page(@Valid @RequestBody {Domain}Page query) {
+        return {domainVar}Service.page(query);
+    }
+
+    /**
+     * 根据ID查询详情
+     *
+     * @param id 主键ID
+     * @return 详情对象
+     */
+    @GetMapping("/detail/{id}")
+    public SingleResult<{Domain}VO> detail(@PathVariable String id) {
+        return SingleResult.of({domainVar}Service.detail(id));
+    }
+
+    /**
+     * 新增 {Domain}
+     *
+     * @param cmd 新增命令
+     * @return 新增结果 (通常是ID或完整对象)
+     */
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody {Domain}AddCmd cmd) {
+        return SingleResult.of({domainVar}Service.add(cmd));
+    }
+
+    /**
+     * 更新 {Domain}
+     *
+     * @param cmd 更新命令
+     * @return 更新结果
+     */
+    @PutMapping
+    public SingleResult<Boolean> update(@Valid @RequestBody {Domain}UpdateCmd cmd) {
+        {domainVar}Service.update(cmd);
+        return SingleResult.of(true);
+    }
+
+    /**
+     * 状态变更 (启用/禁用)
+     *
+     * @param cmd 状态命令
+     * @return 变更后的状态
+     */
+    @PostMapping("/enabled")
+    public SingleResult<Integer> switchStatus(@Valid @RequestBody {Domain}StatusCmd cmd) {
+        {domainVar}Service.switchStatus(cmd);
+        return SingleResult.of(cmd.getStatus());
+    }
+}
+```
+
+### 4.2 复杂业务操作示例
+
+```java
+    /**
+     * 执行业务操作 (e.g. 立即运行检查)
+     *
+     * @param cmd 执行命令
+     * @return 执行结果ID
+     */
+    @PostMapping("/execute")
+    public SingleResult<String> execute(@Valid @RequestBody {Domain}ExecuteCmd cmd) {
+        // 调用 Service 处理复杂业务逻辑
+        return SingleResult.of(
+                {domainVar}Service.execute(cmd)
+        );
+    }
+```
+
+## 5. 阶段 7 合同
+
+- 只消费冻结 OpenAPI/no-impact record 和批准合同；Controller 不得穿透 Application/Domain 边界。
+- Controller/DTO/Convertor 骨架可受控生成；权限、校验、错误映射和接口行为使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，包含代码、契约/API 测试、实际验证和新增 API/权限影响。

package/template/.qoder/skills/ask-matt/SKILL.md

@@ -8,9 +8,15 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
 A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
-## The main flow: idea → ship
+## Matt compatibility flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
@@ -23,7 +29,7 @@ The route most work travels. You have an idea and want it built.
    - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 

package/template/.qoder/skills/code-review/SKILL.md

@@ -3,12 +3,13 @@ name: code-review
 description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of a pinned candidate against a fixed point:
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -99,17 +100,18 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 ### 5. Aggregate
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
 
 For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
-## Why two axes
+## Why separate axes
 
 A change can pass one axis and fail the other:
 
 - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
 - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
 
 Reporting them separately stops one axis from masking the other.

package/template/.qoder/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
 
@@ -102,5 +85,5 @@ High-fidelity HTML prototype
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to yss-prototype-stage>
 ```

package/template/.qoder/skills/implement/SKILL.md

@@ -12,4 +12,4 @@ Run typechecking regularly, single test files regularly, and the full test suite
 
 Once done, use /code-review to review the work.
 
-Commit your work to the current branch.
+Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.

package/template/.qoder/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/.qoder/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/.qoder/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/CLAUDE.md

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

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

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

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

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

package/template/.qoder/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/.qoder/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/.qoder/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/.qoder/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>, ...
+```