skill-family-doc-render 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 变更日志
 
+## 0.4.0 - 2026-09-07
+
+### 新增
+
+- 增加显式成对的 `site.format: markdown-v1` 与 `site.template: editorial`。受限 Markdown
+  由精确依赖 `marked@18.0.11` 分词，再经过本包的结构、链接和锚点校验；包内模板生成
+  完整 HTML、分组目录、静态搜索、交互与首尾不循环的教程翻页。
+- 增加包内 `editorial` 模板的 CSS、JavaScript 和 SVG 图标。新模式不读取项目自有主题
+  CSS 或 JavaScript，同一冻结输入会产生确定的页面及资源字节。
+- 增加站内 SVG 主动内容检查。脚本、事件属性、`foreignObject`、DTD/实体声明，以及
+  外部或 data 资源会在输出替换前被拒绝；SVG 不内联。
+- 增加只读的 `--check-project --repo <name>`，依次检查输入与公开安全、Markdown 机械
+  合同、覆盖状态、渲染与基线、内部链接和资源，并在失败时输出可复制的恢复提示。
+
+### 安全与兼容
+
+- `site.format` 与 `site.template` 同时缺省时继续使用完整 HTML 注入。该路径只供既有
+  消费者兼容，不获得新主题；新建站点使用 `markdown-v1` 与 `editorial`。
+- `--check-project` 必须与单个 `--repo` 一起使用，不与其他模式组合。全程只读；状态
+  问题返回 1，输入或工具问题返回 2。
+
+## 0.3.0 - 2026-09-07
+
+### 新增
+
+- 增加 `site.coverage` 和最小 `site-coverage-lock.json`，记录已审阅产品输入的文件摘要、
+  聚合摘要，以及启用 artifact-graph 时的版本锁摘要。
+- 增加只读的 `--status --repo <name>` 和只更新覆盖快照的
+  `--refresh-coverage --repo <name>`。状态命令会报告覆盖提交、当前摘要、变化文件、
+  权威版本值和建议执行的 Git diff 命令。
+- 状态命令从 `repo.source` 发现所属 Git 仓库。目标位于外层工作区中的独立内层仓库时，
+  覆盖提交、变化路径和 diff 建议只使用内层仓库历史。
+- 增加 `site.versionSources`。渲染器从收容于 `repo.source` 的 JSON 文件和 JSON Pointer
+  读取版本值，版本源文件自动加入覆盖输入。
+
+### 安全与兼容
+
+- 覆盖输入拒绝绝对路径、越界路径、空匹配和符号链接逃逸；覆盖锁始终排除自身，
+  避免形成摘要循环。
+- 保留现有静态 token 和按仓库名派生版本 token 的兼容行为；同名
+  `site.versionSources` 取值优先。
+
 ## 0.2.1 - 2026-09-06
 
 ### 变更

package/README.md

@@ -2,10 +2,13 @@
 
 Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).
 
-Reads `public-release.json` from the current working directory, renders every repo carrying a
-`site` field from its site source directory to its target directory (typically `docs/`), injects
-nav / pager / footer, replaces version placeholders, copies assets, writes `.nojekyll` and a
-tree baseline (`site-baseline.json`), and runs a content-level leak scan over every output file
+Reads `public-release.json` from the current working directory and renders every repo carrying a
+`site` field from its site source directory to its target directory (typically `docs/`). New
+sites explicitly select `format: "markdown-v1"` and `template: "editorial"`; the renderer parses
+restricted Markdown and supplies the complete page structure, navigation, theme, interactions,
+and search data. Sites without `format` keep the legacy complete-HTML injection path for
+compatibility. Both paths replace version placeholders, write `.nojekyll` and a
+tree baseline (`site-baseline.json`), and run a content-level leak scan over every output file
 (pages **and** assets) before any target change. Render, scan, baseline computation and the
 `--assert-git` preflight all finish before the target is changed, so failures in those steps
 leave the existing target untouched. The final directory commit uses Foundation's fixed-set
@@ -13,41 +16,69 @@ publication APIs. A failure before commit removes staging and leaves the existin
 untouched. After commit, or when publication is indeterminate, staging or displaced data may
 remain for diagnosis; the renderer does not guess or roll back.
 
+> **Version boundary:** this source tree is version `0.4.0`. Verify that exact version in the
+> official npm registry before treating it as installable. Version 0.4.0 adds `markdown-v1`, the
+> `editorial` template, and `--check-project` on top of the 0.3.0 coverage workflow.
+
 ## Install
 
+After confirming availability, install this release with an exact version:
+
 ```sh
-npm install skill-family-doc-render@0.2.0
+npm install --save-exact skill-family-doc-render@0.4.0
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
-0.2.0 consumes the three Foundation packages at the exact `0.18.0` pin:
-`skill-family-contracts@0.18.0`, `skill-family-harness-node@0.18.0` and
-`skill-family-engineering-kit@0.18.0` (the last one is used by the workspace profile check).
+Version 0.4.0 has exact runtime dependencies on `marked@18.0.11`,
+`skill-family-contracts@0.18.0`, and `skill-family-harness-node@0.18.0`. `marked` supplies the
+Markdown lexer; the renderer applies its own restricted-format validation before passing semantic
+content to the template. The workspace profile check separately uses
+`skill-family-engineering-kit@0.18.0`.
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
 must re-render their baseline before using `--check`. See the changelog for the full migration
 notes.
 
 ## CLI
 
+Use the exact 0.4.0 CLI for rendering, checks, coverage maintenance, and the Git index assertion:
+
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.2.0
+npx skill-family-doc-render@0.4.0
 
 # drift check only: compare in-memory render against committed site-baseline.json, write nothing
-npx skill-family-doc-render@0.2.0 --check
+npx skill-family-doc-render@0.4.0 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.2.0 --repo <name>
+npx skill-family-doc-render@0.4.0 --repo <name>
 
 # additionally assert every rendered file is tracked in the git index
-npx skill-family-doc-render@0.2.0 --assert-git
+npx skill-family-doc-render@0.4.0 --assert-git
+
+# inspect or refresh the reviewed product-input snapshot
+npx skill-family-doc-render@0.4.0 --status --repo <name>
+npx skill-family-doc-render@0.4.0 --refresh-coverage --repo <name>
+npx skill-family-doc-render@0.4.0 --check-project --repo <name>
 ```
 
-Exit codes: `0` success; `1` drift class — `--check` drift, leak-scan hit, `--assert-git`
-missing files, missing/corrupt baseline; `2` configuration class — missing/invalid
-`public-release.json` or `pages.json`, JSON parse failures, unreplaced `@TOKEN@` placeholders,
-invalid `--repo` usage (the message includes the JSON field path). When several repos are
+The current directory must be the workspace that owns `public-release.json`. From this package's
+source checkout, `node bin/skill-family-doc-render.mjs` is the equivalent local CLI entry.
+
+`--check-project` requires exactly one `--repo <name>`. It cannot be combined with `--check`,
+`--status`, `--refresh-coverage`, `--assert-git`, or `--help`. It checks input and public-content
+safety, the mechanical Markdown contract, coverage freshness, the in-memory render and baseline,
+then internal links and resources. It writes nothing. A failure identifies the repo,
+`public-release.json`, the reason, and a copyable `skill-family-docs-render-site` recovery prompt.
+
+Exit codes: `0` success; `1` drift/status class — `--check` drift, leak-scan hit, `--assert-git`
+missing files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
+configuration/tool class — missing/invalid `public-release.json` or `pages.json`, JSON parse
+failures, unreplaced `@TOKEN@` placeholders, invalid `--repo` usage, invalid coverage inputs, or
+Git failure (the message includes the JSON field path). `--check-project` uses the same classes:
+public-safety, coverage, render, link, or resource findings return `1`; invalid input,
+configuration, or tool errors return `2`.
+When several repos are
 rendered in one run, each repo is isolated: a failure in one does not stop the others, and the
 run ends with a summary of successes/failures plus a non-zero exit (2 if any failure was
 configuration-class, otherwise 1).
@@ -56,7 +87,8 @@ configuration-class, otherwise 1).
 
 The config file lives at the workspace root (resolved from `process.cwd()`). It is validated
 against `schemas/public-release.schema.json` (JSON Schema 2020-12, strict policy) before
-anything runs.
+anything runs. The paired `format` and `template` fields in the example below require version
+0.4.0 or later.
 
 ```json
 {
@@ -72,6 +104,23 @@ anything runs.
         "dir": "site-src",
         "target": "docs",
         "pages": "pages.json",
+        "format": "markdown-v1",
+        "template": "editorial",
+        "coverage": {
+          "lock": "site-coverage-lock.json",
+          "inputs": ["package.json", "src/**", "schemas/**"]
+        },
+        "versionSources": {
+          "@COMPONENT_VERSION@": {
+            "source": "package.json",
+            "pointer": "/version"
+          },
+          "@COMPONENT_TAG@": {
+            "source": "package.json",
+            "pointer": "/version",
+            "prefix": "component-v"
+          }
+        },
         "tokens": { "@CUSTOM_NOTE@": "any static placeholder" }
       }
     }
@@ -83,27 +132,60 @@ anything runs.
 
 - Only repos with a `site` field are rendered; `--repo <name>` selects one by `name`
   (`--repo` without a valid value is an error, never a silent "render all").
-- `site.pages` points to a pages manifest: `{ "pages": [{ "id", "title", "order", "inPager" }] }`,
-  validated against `schemas/pages.schema.json`. Pages are sorted by `order`;
-  `inPager: false` excludes a page from the prev/next pager. Page `id` is restricted to
-  `[A-Za-z0-9][A-Za-z0-9_-]*`.
+- `site.format` and `site.template` are paired. New sites use only `markdown-v1` and `editorial`.
+  Omitting both selects the legacy HTML compatibility path.
+- `site.pages` points to a manifest validated against `schemas/pages.schema.json`. A
+  `markdown-v1` manifest declares site metadata, navigation groups, and each page's `id`, title,
+  reader role, layout kind, group, unique order, and `inPager` state. The page `id` is restricted
+  to `[A-Za-z0-9][A-Za-z0-9_-]*`.
 - `forbiddenPublicPaths` / `privateLiterals` append project-specific literals to the leak scan.
+- `site.coverage` declares reviewed product inputs relative to `repo.source`. Each input accepts
+  `*` and `**` glob syntax and must match at least one file after the coverage lock itself is
+  excluded.
+- `site.versionSources` maps a token to an existing JSON file and an
+  [RFC 6901 JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901). `prefix` and `suffix` format
+  the scalar value without copying the version into configuration. Every referenced JSON file
+  automatically joins the coverage inputs.
+
+## Input formats
+
+### Restricted Markdown and the editorial template
+
+Each `markdown-v1` page is `site.dir/<id>.md`, with an exact one-to-one match to the manifest.
+The format supports paragraphs, level 2–4 headings, ordered and unordered lists, tables, inline
+links and emphasis, fenced code with a language, `NOTE` / `TIP` / `WARNING` callouts, and local
+SVG images. The manifest supplies the only H1. A heading may end with `{#stable-id}`; otherwise a
+deterministic slug is generated. Raw HTML, MDX, task or nested lists, indented or unlabelled code,
+ordinary blockquotes, and arbitrary attributes are rejected before output replacement.
+
+The editorial template owns HTML, CSS, JavaScript, icons, navigation, search, and the non-circular
+tutorial pager. Projects using `markdown-v1` do not supply theme CSS or JavaScript. Project images
+are limited to contained SVG files. Before rendering, SVG safety checks reject scripts, event
+attributes, `foreignObject`, DTD/entity declarations, and external or data resources; SVG remains
+an external image and is never inlined.
 
-## Placeholders
+### Legacy HTML compatibility
 
-Source pages use three HTML-comment injection points, replaced at render time:
+When `format` and `template` are omitted, source pages remain complete HTML and use three comment
+injection points:
 
 - `<!--NAV-->` — table-of-contents nav (active page gets `class="active"`)
-- `<!--PAGER-->` — circular prev/next pager
+- `<!--PAGER-->` — legacy circular prev/next pager
 - `<!--FOOTER-->` — site footer (owner + license)
 
+Legacy HTML remains available for existing consumers, but it does not receive the editorial
+theme. New sites should not start on this compatibility path.
+
+## Version placeholders
+
 Version tokens are derived automatically from the repo's `package.json` version and `name`
 (uppercased, non-alphanumeric runs collapsed to `_`):
 
 - `@{NAME}_TAG@` — e.g. `my-project` → `@MY_PROJECT_TAG@` = `tagPrefix` + version
 - `@{NAME}_VERSION@` — the bare version
 
-`site.tokens` adds arbitrary static placeholder replacements on top. If a rendered page still
+`site.tokens` adds non-version static placeholder replacements. A token also declared in
+`site.versionSources` always takes its value from the JSON source. If a rendered page still
 contains an unreplaced `@TOKEN@` (`@[A-Z0-9_]+@`), the run fails fast (exit 2) naming the
 tokens and the file — placeholder typos never slip into the published site silently.
 
@@ -111,9 +193,32 @@ If a repo has no `package.json` (or no valid `version`), the version falls back
 with a loud `WARNING` on stderr, because that fallback is baked into the output and the
 baseline; a malformed `package.json` fails fast (exit 2).
 
+## Coverage status
+
+`--refresh-coverage --repo <name>` expands `site.coverage.inputs`, adds every configured version
+source, computes the file digests and closure digest, then atomically writes the declared coverage
+lock. It does not render the site or modify Git. The lock contains only:
+
+- `sha256`: the Foundation resource-closure digest;
+- `inputs`: sorted relative file paths and their byte digests;
+- `artifactGraphVersionLockSha256`: the current `artifacts/traceability-version-lock.json`
+  digest when the repository contains `artifact-graph.config.yaml`.
+
+`--status --repo <name>` recomputes the same facts without writing. It prints the last commit that
+changed the coverage lock, the current and recorded closure digests, changed covered files,
+current values from `site.versionSources`, and suggested `git diff` commands. A matching snapshot
+returns `0`; a missing or stale snapshot returns `1`. A site without `coverage`, a path escape, an
+empty glob, an invalid JSON pointer, a symlink escape, or a Git failure returns `2`.
+
+Coverage paths are relative to `repo.source`. Absolute paths, lexical traversal, realpath escape,
+and symlink escape are rejected through Foundation path containment. The coverage lock is always
+excluded from its own inputs, avoiding a digest cycle. `--status` requires a Git repository with a
+resolvable `HEAD`, because its report includes committed, staged, unstaged, and covered untracked
+changes.
+
 ## Leak scan
 
-Every output file — rendered pages **and** copied assets (`.html`/`.css`/`.js`/`.svg`) — is
+Every output file — rendered pages **and** copied or template assets (`.html`/`.css`/`.js`/`.svg`) — is
 scanned **before** any write (`scripts/lib/leak-scan.mjs`). The scanner decodes HTML entities
 (two passes, defeating double encoding), JS escape sequences and URL percent-encoding first,
 then matches case-insensitively against built-in private literals (absolute home paths) and
@@ -145,36 +250,41 @@ The digest is a deterministic set-level sha256 over the contained resources.
 
 ## Foundation dependencies
 
-This package is a thin domain layer over the skill-family foundation and adds no other runtime
-dependencies:
+This package is a thin domain layer over the skill-family foundation. In addition to the two
+Foundation packages below, it uses exact `marked@18.0.11` for Markdown tokenization:
 
 - [`skill-family-harness-node`](https://github.com/ifoohoo/skill-family-harness-node) — all file
   reads go through `resolveContained` / `readFileContained` (path traversal, symlink and realpath
   escapes rejected), per-file digests use `digestBytes`, the tree baseline is computed with
-  `computeResourceClosure`. Output is staged in a sibling directory under the target's canonical
-  parent, with contained writes through `writeFileAtomic`. A new target uses
+  `computeResourceClosure`, and coverage locks use `writeFileAtomic`. Output is staged in a
+  sibling directory under the target's canonical parent, with contained writes through
+  `writeFileAtomic`. A new target uses
   `createFixedSetPublicationManifest` followed by `publishFixedSet`; an existing target uses
   `replaceFixedSetAtomic`. Staging is removed after success or a clearly pre-commit failure;
   post-commit or indeterminate failures may retain it for diagnosis. These APIs do not add a
   broader atomicity guarantee than Foundation provides.
 - [`skill-family-contracts`](https://github.com/ifoohoo/skill-family-contracts) —
   `validateDocument` (JSON Schema 2020-12, strict policy) validates `public-release.json`,
-  `pages.json` and `site-baseline.json`; validation failure aborts with exit code 2.
+  `pages.json`, `site-baseline.json`, and `site-coverage-lock.json`; validation failure aborts
+  with exit code 2.
 
 ## License
 
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** after installing the exact `skill-family-doc-render@0.2.0`, run
-> `./node_modules/.bin/skill-family-doc-render --check` — the drift check is read-only:
+> **Start here:** run `npx skill-family-doc-render@0.4.0 --check-project --repo <name>` after
+> confirming that exact release in the official registry. From a local checkout, use
+> `node bin/skill-family-doc-render.mjs --check-project --repo <name>`. The check is read-only:
 > it renders in memory, compares against the committed `site-baseline.json`, writes
 > nothing and touches no network or credentials. The CLI performs no Git writes; only an
 > explicit `--assert-git` performs a read-only query of the Git index.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **External write boundary:** this CLI writes the declared target and a controlled sibling
-> staging directory, both within the target's canonical parent, with contained path checks.
+> **External write boundary:** rendering writes the declared target and a controlled sibling
+> staging directory, both within the target's canonical parent, with contained path checks. An
+> explicit `--refresh-coverage` writes only the declared coverage lock through an atomic file
+> replacement. `--status`, `--check`, and `--check-project` write nothing.
 > Render, scan, baseline and `--assert-git` preflight failures happen before target changes.
 > Staging is removed after success or a clearly pre-commit failure; post-commit or
 > indeterminate failures may retain it to preserve diagnosable state.
@@ -184,7 +294,9 @@ Apache-2.0
 
 ## Minimal example
 
+Display help and run a read-only project check:
+
 ```sh
-npx skill-family-doc-render@0.2.0 --help     # show usage
-npx skill-family-doc-render@0.2.0 --check    # read-only drift check — the safe first command
+npx skill-family-doc-render@0.4.0 --help
+npx skill-family-doc-render@0.4.0 --check-project --repo <name>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",
@@ -15,6 +15,7 @@
     "bin",
     "scripts",
     "schemas",
+    "templates",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -25,6 +26,7 @@
     "render:site:check": "node bin/skill-family-doc-render.mjs --check"
   },
   "dependencies": {
+    "marked": "18.0.11",
     "skill-family-contracts": "0.18.0",
     "skill-family-harness-node": "0.18.0"
   }

package/schemas/pages.schema.json

@@ -2,24 +2,82 @@
   "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/pages.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "pages.json",
-  "description": "站点页面清单：页面顺序、导航与翻页的真源。site 块为站点元数据（渲染器不消费）。id 限文件名片段字符，顺带消除拼路径时的 shell 元字符面。",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["pages"],
-  "properties": {
-    "site": { "type": "object" },
-    "pages": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["id", "title", "order"],
-        "properties": {
-          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" },
-          "title": { "type": "string", "minLength": 1 },
-          "order": { "type": "integer" },
-          "inPager": { "type": "boolean" }
+  "description": "旧 HTML 与 markdown-v1 共用的页面清单合同。渲染器按 public-release.json 中的 format 选择对应语义。",
+  "oneOf": [
+    { "$ref": "#/$defs/legacy" },
+    { "$ref": "#/$defs/markdownV1" }
+  ],
+  "$defs": {
+    "safeId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" },
+    "legacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pages"],
+      "properties": {
+        "site": { "type": "object" },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "order"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 },
+              "order": { "type": "integer" },
+              "inPager": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "markdownV1": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["site", "groups", "pages"],
+      "properties": {
+        "site": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["title", "description", "productKind"],
+          "properties": {
+            "title": { "type": "string", "minLength": 1 },
+            "description": { "type": "string", "minLength": 1 },
+            "productKind": { "enum": ["plugin", "library"] }
+          }
+        },
+        "groups": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "pages": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "role", "kind", "group", "order", "inPager"],
+            "properties": {
+              "id": { "$ref": "#/$defs/safeId" },
+              "title": { "type": "string", "minLength": 1 },
+              "navTitle": { "type": "string", "minLength": 1 },
+              "role": { "enum": ["overview", "setup", "first-success", "maintenance", "release", "troubleshooting", "upgrade", "reference"] },
+              "kind": { "enum": ["home", "task", "reference", "troubleshooting"] },
+              "group": { "$ref": "#/$defs/safeId" },
+              "order": { "type": "integer" },
+              "inPager": { "type": "boolean" }
+            }
+          }
         }
       }
     }

package/schemas/public-release.schema.json

@@ -29,12 +29,48 @@
               "dir": { "type": "string", "minLength": 1 },
               "target": { "type": "string", "minLength": 1 },
               "pages": { "type": "string", "minLength": 1 },
+              "format": { "const": "markdown-v1" },
+              "template": { "const": "editorial" },
+              "coverage": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["lock", "inputs"],
+                "properties": {
+                  "lock": { "type": "string", "minLength": 1, "pattern": "^[^*?\\[\\]{}()!]+$" },
+                  "inputs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1, "pattern": "^[^?\\[\\]{}()!]+$" }
+                  }
+                }
+              },
+              "versionSources": {
+                "type": "object",
+                "minProperties": 1,
+                "propertyNames": { "pattern": "^@[A-Z0-9_]+@$" },
+                "additionalProperties": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["source", "pointer"],
+                  "properties": {
+                    "source": { "type": "string", "minLength": 1, "pattern": "^[^*?\\[\\]{}()!]+$" },
+                    "pointer": { "type": "string", "pattern": "^/" },
+                    "prefix": { "type": "string" },
+                    "suffix": { "type": "string" }
+                  }
+                }
+              },
               "tokens": {
                 "type": "object",
                 "additionalProperties": {
                   "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }]
                 }
               }
+            },
+            "dependentRequired": {
+              "format": ["template"],
+              "template": ["format"]
             }
           }
         }

package/schemas/site-coverage-lock.schema.json

@@ -0,0 +1,28 @@
+{
+  "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/site-coverage-lock.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "site-coverage-lock.json",
+  "description": "知识站已审阅产品输入的最小字节快照；不保存版本、发布状态或人工结论。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sha256", "inputs"],
+  "properties": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        }
+      }
+    },
+    "artifactGraphVersionLockSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}