@gobing-ai/knowledge-kit 0.0.37 → 0.1.1

package/plugins/kk/skills/article-adapt/SKILL.md

@@ -9,8 +9,8 @@ description: This skill should be used when a kk-itc publish plan contains varia
 
 
 This skill adapts one published article into one Content file per `publish-plan.json` variant with
-`adapt: true`. It is deliberately **thin**: the plan (built from `TARGET_PROFILES` in
-`plugins/kk/scripts/itc-stages.ts`) carries the per-variant locale, format and limits — this skill
+`adapt: true`. It is deliberately **thin**: the plan (built by `buildItcPublishPlan` in
+`apps/cli/src/itc-plan.ts` from each publish manifest's declared profiles) carries the per-variant locale, format and limits — this skill
 holds **no platform table** and never decides which variants exist.
 
 ## Inputs

package/plugins/kk/skills/smart-seo/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: smart-seo
+description: >-
+  Run, review and interpret a read-only Smart SEO/GEO audit and turn its evidence into a prioritized
+  action plan. Use when the user says "audit this site for SEO", "run a smart SEO audit", "review
+  this saved audit", "explain these SEO findings", or "check GEO readiness". Read-only results: no
+  site mutation, no ranking and no citation promises.
+version: 0.1.0
+---
+
+# smart-seo — evidence-grounded SEO/GEO audits
+
+One entry point for the whole audit lifecycle: intake → run → review evidence → interpret →
+narrative → offline rescoring. There is no second command, subagent or plugin kind; this skill plus
+`plugins/kk/workflows/kk-smart-seo.yaml` and the `kk stage run seo-*` stages are the entire surface.
+
+## 0. The contract — state it before you report
+
+- **Read-only.** The audit fetches public pages and writes artifacts under `.works/`; it never edits
+  the site, submits URLs, changes accounts, publishes or schedules anything. Remediation is an
+  operator action you may recommend, never perform.
+- **No ranking, citation, traffic or revenue promise.** The audit cannot observe indexing, ranking,
+  visits, revenue, bot behavior or answer-engine citations. Say "not measured" where that is true.
+- **Label the evidence class** in every statement: observed **measurement**, **heuristic**,
+  **unknown**, **model judgment / advisory**, or **consultation**. `references/method.md` §1.
+- **Crawler purposes stay separate:** search-indexing, model-training and user-triggered fetchers
+  have different policies and different consequences. `references/seo-geo-sources.md` §2.
+- **`vendors/` is reference-only:** excluded from runtime and install resolution; never read or copy
+  it into a shipped file, and never wrap the vendor Python.
+- **Specialist advice is consultation.** Legal, hosting, server, analytics or i18n work outside the
+  collected evidence is flagged as consultation with the missing evidence named — never presented
+  as an audit finding.
+- **No phantom metrics.** Every number in your answer comes from an artifact field, and you name it.
+
+## 1. Route the request
+
+| Input | Path |
+| --- | --- |
+| A public URL / domain | Full workflow run (§3→§4) with a written options file. |
+| A saved audit directory (`audit.json` present) | Skip to review/interpret (§5→§6); rescore with §8 when the rubric or inputs changed. |
+| A question about an existing report | Read `report.json` + `audit.json` + `checks.json`, answer from the fields (§5). |
+| "Make the site rank / get cited" | Explain what the evidence does and does not support (§0, §6) and produce the action plan. |
+
+Never invent a run id, work directory or artifact path. Resolve them from the run-bound file
+`.spur/run/<runId>-seo-work-dir.txt`, and read the package root from the running executable
+(`references/operations.md` §1) — never from a hard-coded checkout path.
+
+## 2. Intake and the options file
+
+Confirm with the operator: the exact URL, the intended audience locale, any business context worth
+recording (≤ 2,000 characters — operator context, not website evidence), whether measured
+performance evidence is desired (PSI/CrUX keys present), and whether an imported visibility
+snapshot exists. Then write a strict JSON options file — fields, defaults, bounds and the imported
+snapshot contract are in `references/operations.md` §3, §5. Pass the file **path** as data; never
+template a user value into shell source, and refuse NUL input.
+
+## 3. Register the decision catalogs (integrated runs)
+
+The workflow's preflight passes `require_decisions=true`: the four SEO catalogs (22 decisions) must
+be served, or preflight fails with the registration pointer. The supported setup is an **append** of
+`<package-root>/plugins/kk/decisions` to the consumer project's `decisions.paths`, preserving every
+existing entry and every maker setting. Verify with `spur decision list|show|status --json` — that
+is configuration evidence, never model health. Exact steps and failure text:
+`references/operations.md` §2. Collection-only stage use and the offline fixture mode need no
+catalogs.
+
+## 4. Run it, bounded
+
+```bash
+spur workflow run <package-root>/plugins/kk/workflows/kk-smart-seo.yaml \
+  --vars '{"options_file":"/abs/path/options.json"}' --quiet
+```
+
+`preflight → collect → check → enrich → judge → score → narrative → report`, terminal
+`done | partial | failed`. Leave `work_dir` empty so preflight allocates it and records the
+run-bound path. Show progress from the workflow trace and the run record, not by guessing a
+directory; report `partial` as successful delivery with named missing evidence, and `failed` as the
+only failure state. Full command/artifact/progress detail: `references/operations.md` §6–§8.
+For a run with no network access (fixture mode), the same workflow executes offline — say so
+explicitly and never present fixture-derived numbers as a live site audit.
+
+## 5. Review the evidence before reading any judgment
+
+1. `report.json` — `status`, `narrativeStatus`, `scores`, `coverage`, `actions` (already ordered).
+2. Start with `P1`, then `P2` actions. For each: severity, category, affected pages, `effort` band,
+   and `heuristic` (true = rule-of-thumb over observed facts, false = directly observed).
+3. Confirm each action against `checks.json`: `status`, `reason`, `evidenceRefs`, `sourceUrl`,
+   `sourceCheckedAt`. A failing row with a `heuristic: true` flag is a hypothesis to verify, not a
+   defect.
+4. Read `audit.json` `/limits/*` and `coverage` (`assessed`, `unknown`, `ratio`, `hitLimit`). A
+   limit or a large `unknown` count bounds every conclusion; orphan/depth/duplicate observations are
+   "among sampled pages".
+5. Treat policy-looking rows carefully: robots directives, intentional `noindex`, canonical-to-other
+   and missing optional files (`robots_missing`, `sitemap_missing`, `not_in_sitemap`,
+   `llms_txt_missing`) are **signals requiring operator intent**, not automatic defects.
+6. When a row's `sourceCheckedAt` is old relative to the question, refresh the primary source first
+   (`references/seo-geo-sources.md` §3) instead of asserting behavior from memory.
+
+## 6. Interpret for the operator — per area
+
+Explain each area from the recorded evidence and stop where the evidence stops. Rubric, scoring and
+the full "cannot conclude" list live in `references/method.md` §3 and §6.
+
+| Area | What the evidence supports | What it must not become |
+| --- | --- | --- |
+| **Technical** | Observed HTTP status/redirect chains, canonical and hreflang tags, indexability directives, headers, HTTPS/host variants, response size and timings. | Proof of indexing, rendering or crawl-budget impact. `js_dependent` is raw-HTML shell suspicion only — no browser rendering. |
+| **On-page** | Title/meta/H1–H3/outline/link/anchor/image facts, structured-data syntax and type inventory, Open Graph presence. | A ranking explanation. Length thresholds are heuristics; structured data is data, and its presence is not an AI or rich-result eligibility requirement. |
+| **Content / editorial** | Visible word counts (an editorial measure, language-limited), duplicate/thin-content observations, sampled text. | A quality verdict or an audience judgment. Model judgments (`source: model`) are advisory with a maker and a confidence. |
+| **Local** | Declared locale/origin facts, contact and business-entity signals, `kk-seo-local-intent`. | Local-pack or maps presence claims — not measured. |
+| **Ecommerce** | Product/category page-type and action classifications, duplicated titles/meta, canonical and redirect observations on product URLs. | Price, feed or merchant-center diagnostics — out of scope; name that as consultation. |
+| **International** | hreflang observations, locale declarations, duplicate-content observations across host/path variants. | A statement that a market does or does not receive traffic. Machine-translation quality is consultation. |
+| **GEO (generative engines)** | Editorial diagnostics — intent satisfaction, first-hand specificity, verifiable provenance, entity consistency, answer-first structure — plus imported citation/visibility snapshots when supplied. | Any citation, mention or inclusion promise. Blocking a training crawler is a policy choice, not a search defect. |
+
+### Crawler policies, kept separate
+
+Explain a robots observation by the crawler's **purpose**, never as one verdict, and report the
+observed directive plus the path it applies to:
+
+- **Search indexing** (`Googlebot`, `Bingbot`, `OAI-SearchBot`) — affects eligibility for search and
+  search-grounded answer surfaces. A deliberate restriction is an operator decision, not a defect.
+- **Model training** (`GPTBot`, `Google-Extended`, `ClaudeBot`, `CCBot`) — a data-policy choice.
+  Blocking it is not a search defect; allowing it promises nothing.
+- **User-triggered fetch** (`ChatGPT-User` and similar) — serves a user's explicit request; a block
+  limits that session, not search eligibility.
+
+A router robots group (the audit's own user agent) is likewise an operator policy. Never claim what
+any crawler actually did: the audit observes the site's declared policy and its own requests only.
+
+### When evidence is missing
+
+Say which of the three it is — **not collected** (outside the bounded crawl), **collected but
+unknown** (`status: unknown`), or **not applicable** (`not-applicable`) — and name the input that
+would settle it (a larger budget, a supplied visibility snapshot, an operator answer about intent).
+Consultation is the right label for work this method cannot evidence at all.
+
+## 7. Write the narrative
+
+Two different artifacts — keep them apart:
+
+- **Validated narrative** (`narrative.json`): the §9 schema — allow-listed headings, fixed
+  `fact | action | limit` templates and `evidenceRef` pointers into the materialized `audit.json`,
+  bound to its sha256 and run id. Selecting and ordering recorded references is allowed; adding a
+  measurement, diagnosis or prediction is not, and any invalid claim rejects the whole narrative
+  (which then degrades to the labeled deterministic summary). Schema, worked example and rejection
+  cases: `references/narrative.md`.
+- **Advisory prose** (your answer): the explanation, prioritization and operator-facing advice.
+  Label evidence classes, cite artifact fields, mark consultation, and describe what the report
+  deliberately cannot say. The report accepts no free prose — `references/narrative.md` §4.
+
+## 8. Offline rescoring
+
+To re-score a saved audit without touching the network, the source run or its artifacts:
+
+```bash
+kk stage run seo-score <saved-work_dir> <new-revision_dir>   # revision dir must be absent/empty
+kk stage run seo-report <new-revision_dir>
+```
+
+The revision copies the validated inputs beside a fresh `audit.json`, keeps the original `runId`
+and adds a `revisionId`, so source artifacts stay immutable and two revisions are comparable as
+durable directories. Never compare scores across runs with different coverage or `methodVersion`,
+and never patch a saved artifact in place. Details: `references/operations.md` §9.
+
+## 9. Failures and limits — report, never paper over
+
+Unserved catalogs, invalid options, a populated `work_dir`, a refused network target
+(local/reserved address), budget exhaustion, unavailable optional PSI/CrUX evidence, maker
+fallback/low confidence, malformed predecessors, a rejected narrative and cancellation each have a
+defined handling in `references/operations.md` §8. Three habits matter most: never present an
+exhausted crawl as complete, never turn an unknown or a low-confidence judgment into a defect, and
+never convert "not measured" into "passed".
+
+## 10. References
+
+| Reference | Owns |
+| --- | --- |
+| `references/operations.md` | Package-root resolution, catalog registration and failure text, options fields, imported snapshot, run/progress commands, per-artifact map, failure handling, offline rescoring. |
+| `references/method.md` | Evidence classes, the 52-rule checklist structure, score/coverage formulas, action ordering and priorities, how to read a check back to its evidence, and the method's explicit limits. |
+| `references/seo-geo-sources.md` | Primary source registry with checked-at dates and per-source limits, crawler-purpose separation, the source refresh procedure, GEO limits, and the `vendors/` reference-only rule. |
+| `references/narrative.md` | The validated narrative schema, worked example, rejection matrix, and the boundary with advisory prose. |
+
+Attribution for the adapted rubric, rule identities and upstream notice:
+`plugins/kk/references/smart-seo-attribution.md`.

package/plugins/kk/skills/smart-seo/references/method.md

@@ -0,0 +1,126 @@
+# Smart SEO — method, rubric and score interpretation
+
+The rubric is a **versioned internal checklist**, not a vendor grade and not a search-engine
+verdict. Every claim below is what the artifacts record; nothing here measures indexing, ranking,
+traffic, revenue, bot behavior or citation visibility.
+
+## 1. Evidence classes — label them every time you report
+
+| Class | Meaning | Recorded where |
+| --- | --- | --- |
+| **Measurement / observed fact** | A value the audit actually observed within its stated budget (HTTP status, title text, robots directive, response bytes, timings). | `crawl.json` page facts, `checks.json` row `evidenceRefs`, `audit.json` `/facts/*` |
+| **Heuristic** | A bounded rule-of-thumb over observed facts. `heuristic: true` on the check row and on the derived action. Examples: page depth, thin content (visible word count), title length, heading skips, orphan/depth observations "among sampled pages". | `checks.json` / `audit.json` `heuristic` |
+| **Unknown** | Not assessed or not assessable: malformed, unavailable, budget-exhausted, blocked, or outside the collected scope. Never rendered as a pass. | `checks.json` status `unknown`, `coverage.unknown`, `audit.json` `/limits/*` |
+| **Model judgment** | An editorial output from a typed decision (`source: model`, with maker and confidence). Advisory, never a measurement. | `judgments.json`, `audit.json` `/judgments` |
+| **Imported evidence** | A supplied visibility snapshot or PSI/CrUX measurement, with source, collection window and `measurementKind`. | `performance.json`, `visibility.json` |
+| **Consultation** | Advice outside the collected evidence (specialist legal/hosting/i18n/analytics work). Say so explicitly and name the missing evidence. | nowhere — it must not enter the report as a finding |
+
+Rule of thumb: a value is a **measurement** only if some artifact records it with a source; a
+judgment, an inference or a threshold over content is a **heuristic** or **advisory** statement.
+
+## 2. Checklist structure
+
+52 deterministic rules across five categories — `technical` (22), `content` (16), `crawl` (8),
+`security` (4), `geo` (2). Each rule keeps a stable identity, a severity, an effort band, a
+`heuristic` flag, a primary `sourceUrl` and a `sourceCheckedAt` date, and one disposition from the
+vendor review (`native`, `adapted`, `informational`, `deferred`).
+
+Every eligible rule/subject pair yields exactly **one** row:
+
+```json
+{
+  "ruleId": "title_missing",
+  "subjectId": "<hashed subject identity>",
+  "subjectUrl": "https://example.com/a",
+  "status": "fail",
+  "category": "content",
+  "severity": "high",
+  "evidenceRefs": ["https://example.com/a"],
+  "sourceUrl": "https://developers.google.com/search/docs/appearing-in-search/...",
+  "sourceCheckedAt": "2026-10-14",
+  "heuristic": false,
+  "reason": "Human-readable reason for this status"
+}
+```
+
+`status` is `pass | fail | unknown | not-applicable`. **The absence of a row is an error, never a
+pass.** `not-applicable` means the rule cannot apply to that subject (for example a site-level rule
+against a page-level subject); it is excluded from both the score and the coverage denominator.
+A `deferred`-disposition rule applies but is not assessed in this method version, so it emits
+`unknown` and counts in `coverage.unknown`.
+
+Intent-sensitive observations are not defects by themselves: a robots directive, an intentional
+`noindex`, a canonical pointing elsewhere, a missing optional file or missing optional metadata all
+require operator intent before they become a recommendation. Missing SEO files never turn into
+indexing requirements in the narrative.
+
+## 3. Scores
+
+Category score = `round(100 * pass / (pass + fail))` over the **applicable assessed** rows of that
+category, and `null` when that category has no assessed row:
+
+| Field | Meaning |
+| --- | --- |
+| `scores.technical` / `content` / `crawl` / `security` | The checklist pass ratio in that category. `null` = undefined denominator, never 0. |
+| `coverage.totalRules` | 52 (the checklist size). |
+| `coverage.applicableRules` | Rows whose status is not `not-applicable`. |
+| `coverage.assessed` | Rows with `pass` or `fail`. |
+| `coverage.unknown` | Applicable rows left `unknown`. |
+| `coverage.ratio` | `assessed / (assessed + unknown)` — how much of the applicable checklist was actually assessed. |
+
+Interpretation rules:
+
+- There is **no blended overall SEO/GEO grade** in this method version. Report the four category
+  ratios with their coverage side by side; a ratio published without its coverage is misleading.
+- `geo` rules are assessed and prioritized like any other row but produce no category score.
+- `informational` rules (vendor-review disposition) are reported but never enter a category score:
+  they neither deduct on `fail` nor pad the ratio on `pass`.
+- Unknown and review values never count as successes, and a disabled or unavailable optional area
+  is reported as such rather than folded into a pass.
+- Never compare scores across two runs with different coverage, different `methodVersion`, or
+  different options — record the denominators with the number.
+- A high score means "few sampled rules failed", not "the site is healthy". A low score does not
+  prove a traffic or ranking problem.
+
+## 4. Action ordering and priorities
+
+One action per failing rule, carrying the full affected-subject list (aggregation must not hide
+unknown subjects). Stable ID `SEO-<ruleId>-<first12(sha256(subject identity))>` — sorting never
+renumbers an ID, so IDs stay comparable across revisions.
+
+Order: severity (`critical`, `high`, `medium`, `low`, `info`) → affected-page count descending →
+effort band ascending → stable ID.
+
+| Priority | Meaning |
+| --- | --- |
+| `P1` | Confirmed `critical` or `high` severity failures. |
+| `P2` | Confirmed `medium` severity failures. |
+| `P3` | Confirmed low-severity failures. |
+| `review` | Uncertain items — kept out of fix-first lists until the operator confirms intent or supplies missing evidence. |
+
+`effort` is a declared planning band (1–4), not a quote or an estimate in hours. Severity expresses
+the rule's consequence, not its certainty; read it together with `heuristic` and with `coverage`.
+Editorial (content/GEO) scores can justify a review suggestion, never confirm a technical fact.
+
+## 5. Reading a check back to its evidence
+
+1. Take the action's `ruleId`, `affectedSubjects` and stable ID.
+2. Open `checks.json` and select the rows with that `ruleId`; read `status`, `reason`,
+   `evidenceRefs`, `sourceUrl` and `sourceCheckedAt`.
+3. Read the underlying page facts in `crawl.json` (or the referenced `evidence/pages/*.json`).
+4. Read `audit.json` `/limits/*` and `coverage` before drawing any conclusion: a limit or a high
+   `unknown` count bounds what the finding can mean.
+5. If the primary source page has changed since `sourceCheckedAt`, refresh the source before
+   relying on the rule's stated rationale (see `seo-geo-sources.md`).
+
+## 6. What this method cannot conclude
+
+- Whether a URL is indexed, ranking, receiving traffic or being cited by any AI answer engine.
+- What a crawler actually did: the audit observes the site's **declared** policy
+  (robots.txt, meta robots, sitemap) and its own requests — never another crawler's behavior.
+- How a browser renders a JavaScript-dependent page: rendering is deferred, so a raw-HTML shell is
+  suspicion only.
+- Whether an editorial judgment is correct: adequacy of a value proposition, content depth or
+  citability is an opinion with a maker and a confidence, not a fact.
+- Performance causes or fixes: PSI lab metrics and CrUX field data, when supplied, describe
+  observed timing, not the work needed to change it.

package/plugins/kk/skills/smart-seo/references/narrative.md

@@ -0,0 +1,125 @@
+# Smart SEO — the validated narrative contract
+
+The narrative is **optional** and **fully validated**. It selects and orders references into the
+materialized `audit.json`; it cannot introduce a measurement, unit, diagnosis or prediction. When
+it is absent or rejected the report is still delivered with `narrativeStatus: omitted|rejected`
+plus a deterministic summary — an optional agent failure is never an audit failure.
+
+## 1. Schema (schema version 1)
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "<audit.runId>",
+  "auditDigest": "<sha256 of the exact audit.json bytes>",
+  "sections": [
+    {
+      "heading": "summary | priorities | limits",
+      "claims": [
+        { "template": "fact | action | limit", "evidenceRef": { "artifact": "audit.json", "jsonPointer": "/facts/<key> | /actions/<id> | /limits/<key>" } }
+      ]
+    }
+  ]
+}
+```
+
+Hard limits and exact shapes — every key below is the *only* accepted key at its level:
+
+| Rule | Value |
+| --- | --- |
+| Root keys | exactly `schemaVersion`, `runId`, `auditDigest`, `sections` |
+| `schemaVersion` | `1` |
+| `runId` | must equal the audit's `runId` |
+| `auditDigest` | must equal the sha256 of the materialized `audit.json` (stale or unknown digest rejects) |
+| `sections[]` keys | exactly `heading`, `claims`; at least one section; `claims` non-empty |
+| `heading` | one of `summary`, `priorities`, `limits` |
+| `claims[]` keys | exactly `template`, `evidenceRef`; unknown keys anywhere (including a free-prose `text`) reject the whole narrative |
+| `template` | one of `fact`, `action`, `limit` |
+| `evidenceRef` keys | exactly `artifact`, `jsonPointer`; `artifact` must be `audit.json` |
+| `jsonPointer` | exactly two segments: the template's own collection plus one key — `/facts/<key>` for `fact`, `/actions/<actionId>` for `action`, `/limits/<key>` for `limit` |
+| Pointer targets | `fact` must address a recorded scalar observed fact (`/facts/pages_visited`, `/facts/requests_made`, `/facts/total_bytes`, …); `action` must address an existing action **by stable id** (never an array index); `limit` must address a recorded limit (`pagesVisited`, `requestsMade`, `totalBytes`, `elapsedSeconds`, `hitLimit`) |
+| Bounds | ≤ 32 KiB raw and ≤ 30 claims |
+
+Prototype keys (`__proto__`, `constructor`, `prototype`) and out-of-collection pointers are refused.
+Rendering is method-owned: each claim becomes an `**Observed fact**`, `**Planned action**` or
+`**Recorded limit**` line with the audit's own value, unit and source, and Markdown-escaped.
+
+## 2. Worked example
+
+Given an audit whose `runId` is `8f2c…`, whose `auditDigest` is the real sha256 of `audit.json`,
+and whose actions include `SEO-title_missing-0f115db062b7`:
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "8f2c1d0e-…",
+  "auditDigest": "<sha256 of audit.json>",
+  "sections": [
+    {
+      "heading": "summary",
+      "claims": [
+        { "template": "fact", "evidenceRef": { "artifact": "audit.json", "jsonPointer": "/facts/pages_visited" } },
+        { "template": "fact", "evidenceRef": { "artifact": "audit.json", "jsonPointer": "/facts/requests_made" } }
+      ]
+    },
+    { "heading": "priorities", "claims": [{ "template": "action", "evidenceRef": { "artifact": "audit.json", "jsonPointer": "/actions/SEO-title_missing-0f115db062b7" } }] },
+    { "heading": "limits", "claims": [{ "template": "limit", "evidenceRef": { "artifact": "audit.json", "jsonPointer": "/limits/hitLimit" } }] }
+  ]
+}
+```
+
+Renders as (in `report.md`, section 3):
+
+```markdown
+### Summary
+
+- **Observed fact** `pages_visited` = `12` count — source: `crawl.json`
+- **Observed fact** `requests_made` = `34` count — source: `crawl.json`
+
+### Priorities
+
+- **Planned action** `SEO-title_missing-0f115db062b7` (high, P1) — Fix title missing — 3 affected page(s), effort band 1
+
+### Limits
+
+- **Recorded limit** `hitLimit` = `none`
+```
+
+To produce this in a run: read `<work_dir>/audit.json`, compute its sha256 over the exact file
+bytes, keep the same `runId`, then write the object to `<work_dir>/narrative.json` **before**
+`seo-report` runs (the workflow's `agent.run` step does exactly that, with
+`answerFile: <work_dir>/narrative.json`). Replying `{}` is the documented way to decline: the
+report then falls back to its deterministic summary.
+
+## 3. Rejection cases (each rejects the entire narrative)
+
+| Case | Diagnostic shape |
+| --- | --- |
+| Free prose added to a claim (`text: "…"`) or any unknown key | `sections[0].claims[1]: unknown key "text"` |
+| Heading outside the allow list (`"Overview"`) | `sections[0]: heading "Overview" is not an allow-listed heading` |
+| Template mismatch with the pointer (`fact` + `/limits/…`) | `template "fact" requires a pointer into /facts, got "/limits"` |
+| Invented fact or limit key | `unknown fact id "domain_authority"` / `unknown limit id "ranking_position"` |
+| Invented or misspelled action id, or an array index (`/actions/0`) | `unknown action id "0"` |
+| Pointer deeper or shallower than two segments (`/facts/a/b`) | `jsonPointer "…" must address exactly one record (collection/key)` |
+| Stale digest (audit re-scored after the narrative was written) | `narrative auditDigest does not match the materialized audit.json digest (stale or unknown digest)` |
+| Wrong run id | `narrative runId "…" does not match the audit runId` |
+| Non-object root, non-JSON bytes, empty sections, > 32 KiB, > 30 claims | `narrative root must be a JSON object` / `narrative is not valid JSON: …` / `narrative sections must not be empty` |
+
+On rejection the stage writes `narrative-diagnostics.json` beside the audit, sets
+`report.json.narrativeStatus: 'rejected'`, and renders the deterministic summary labeled
+`**Narrative rejected**`. Never edit the saved `narrative.json` to force acceptance, and never move
+a rejected claim into the deterministic summary by hand: the summary is method-owned.
+
+## 4. Advisory prose lives outside the report
+
+The validated narrative deliberately cannot carry commentary. If the operator asks for
+explanation, interpretation or an action plan in prose, that is the **skill's** output: keep it in
+conversation (or a separate operator-authored document) and:
+
+- label every statement as measurement, heuristic, model judgment or unknown (see `method.md`);
+- cite the artifact plus the field (`report.json` action id, `checks.json` row, `audit.json`
+  `/facts/*`) for every number;
+- mark specialist advice outside the collected evidence as **consultation**, naming the missing
+  evidence and the source that would be needed;
+- make no promise about rankings, citations, traffic, revenue or crawler behavior, and propose no
+  change that mutates the site — the audit is read-only, and any remediation is an operator action.