@gobing-ai/knowledge-kit 0.0.36 → 0.1.0

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.

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

@@ -0,0 +1,202 @@
+# Smart SEO — operations
+
+Setup, run, progress, and failure handling for the `kk-smart-seo` audit. The workflow is the
+orchestrator; `kk` owns every step (ADR-007). Nothing here mutates a site.
+
+## 1. Resolve the KK package root
+
+Both the stages and the decision catalogs live in the **installed** package, not in a checkout:
+
+```bash
+# The real path of the executable that is actually running (follows symlinks):
+readlink -f "$(command -v kk)"          # -> <pkg>/dist/index.js
+PKG_ROOT="$(dirname "$(dirname "$(readlink -f "$(command -v kk)")")")"
+```
+
+`kk stage run` resolves `plugins/kk/scripts/kk-workflow-stages.ts` next to its own entry: a real
+checkout uses the checked-in runner, an installed entry always uses its own package copy. An
+unrelated ancestor `plugins/` directory is never selected, so a run from an unrelated cwd is safe.
+
+## 2. Register the SEO decision catalogs (required for the integrated workflow)
+
+`decisions.paths` in the consumer project config (`.spur/config.yaml`) is the whole search path.
+**Append** one entry — never replace the list:
+
+```yaml
+decisions:
+  paths:
+    - <existing entry>                     # keep every existing entry
+    - <PKG_ROOT>/plugins/kk/decisions       # appended: the 4 SEO catalogs, 22 decisions
+  maker: <existing maker>                   # keep the maker and makers: mapping untouched
+```
+
+`seo-preflight` with `require_decisions=true` (the workflow's own call) fails with this pointer
+when the catalogs are not served:
+
+```text
+seo-preflight: SEO decision catalogs are not served — missing catalog file(s): kk-seo-site.yaml, ...
+Registration fix: append `<kk-package-root>/plugins/kk/decisions` to the project config `decisions.paths`
+(.spur/config.yaml), preserving every existing entry and maker setting, then re-run preflight.
+```
+
+Verify without dispatching a maker (configuration evidence, never model health):
+
+```bash
+spur decision list --json     # must serve the 22 kk-seo-* ids
+spur decision show kk-seo-page-type --json   # -> catalog, layer, effective maker + source
+spur decision status --json   # -> load errors, duplicate ids, per-decision effective maker
+```
+
+Collection-only stage use (`require_decisions=false`) and the explicit offline fixture mode need
+no catalogs. Do not run an audit that silently writes user-global configuration; the append above
+is a one-time operator setup, and it is repeated only when an upgrade changes the resolved
+package root.
+
+**The catalogs' declared schema must resolve from where they live.** Each shipped SEO catalog
+declares `$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"`, and Spur resolves that
+schema through the module tree above the catalog's own directory. A global install satisfies this
+by construction (both packages are siblings in the global tree); with a project-local KK install,
+keep `spur` resolvable from the installed package's location or `decision status --json` reports
+the catalogs as `loadErrors` (`Cannot resolve package schema …`) and preflight fails. A load error
+is a setup defect to fix, never a reason to fall back to a maker default silently.
+
+## 3. Options file
+
+Write a UTF-8 JSON object (≤ 64 KiB, strict schema — unknown keys are refused) and pass its path
+as data, never as shell source:
+
+```json
+{
+  "url": "https://example.com",
+  "locale": "en-US",
+  "business_context": "",
+  "max_pages": 60,
+  "max_depth": 5,
+  "max_requests": 200,
+  "deadline_seconds": 600,
+  "semantic_pages": 20,
+  "max_pairs": 10,
+  "max_keywords": 10,
+  "max_decision_calls": 320,
+  "performance": false,
+  "visibility_file": "",
+  "fixture": ""
+}
+```
+
+| Field | Meaning and bounds |
+| --- | --- |
+| `url` | Required HTTP(S) URL or bare domain (bare becomes HTTPS). Userinfo, nonstandard ports, local/reserved addresses and malformed hostnames are refused. |
+| `locale` | BCP-47; describes the report audience and the imported query market. It never assumes the site's language. |
+| `business_context` | Optional operator context ≤ 2,000 UTF-16 units. It is context, not website evidence. |
+| `max_pages` / `max_depth` | 60 / 5 by default; maxima 200 / 10. The page quota counts every attempt, including blocked, redirect and error records. |
+| `max_requests` / `deadline_seconds` | 200 / 600 by default; maxima 500 / 1800. One shared quota and deadline covers robots, sitemaps, pages, probes and link targets. |
+| `semantic_pages` / `max_pairs` / `max_keywords` | 20 / 10 / 10 by default; maxima 60 / 40 / 30. Selection is deterministic (homepage, observed depth/inlinks, URL tie break). |
+| `max_decision_calls` | 320 by default, maximum 1000. Every attempt consumes one; there is no retry on an unknown-charge call. Exhaustion is an explicitly partial assessment. |
+| `performance` | `false` by default. `true` requests PSI mobile/desktop and CrUX for at most 3 selected pages; the stage shares a 300 s deadline and a 12-call cap. |
+| `visibility_file` | Optional normalized local JSON snapshot (§4). Never an arbitrary provider dump. |
+| `fixture` | Explicit offline fixture **directory**. With a fixture, network access and real maker dispatch are forbidden. Production never falls back to fixture data. |
+
+## 4. Audit scope — the submitted host plus its exact `www` toggle
+
+Scope is the normalized submitted hostname with **one** leading `www.` removed when present, or
+added when absent — nothing else. `shop.example.com` admits `shop.example.com` and
+`www.shop.example.com` only: no registrable apex, no sibling subdomains, and default ports stay
+origin-specific. Off-scope redirects and links are recorded, never followed; `www`/non-`www` and
+HTTP/HTTPS transitions are observations, not defects. There is no browser rendering and no outbound
+external-link fetching in this version: state that assessment as **not collected** rather than
+assuming a result.
+
+## 5. Imported visibility snapshot
+```json
+{
+  "schemaVersion": 1,
+  "siteOrigin": "https://example.com",
+  "locale": "en-US",
+  "source": "search-console-export|analytics-export|manual",
+  "collectedAt": "2026-10-01T00:00:00Z",
+  "measurementKind": "measured",
+  "rows": [{ "query": "example query", "url": "https://example.com/a", "clicks": 4, "impressions": 120, "position": 8.5, "citations": 2, "sampleCount": 500, "platform": "chatgpt" }]
+}
+```
+
+Maximum 1 MiB / 500 rows; strings bounded; counts are finite nonnegative numbers; `position` ≥ 1;
+`citations` ≤ `sampleCount` with `platform` required; any `url` must belong to the audit scope.
+Unknown properties, a conflicting locale or site identity, a future timestamp, or evidence older
+than 90 days fails validation before use. Keywords come from this data — never invented volumes.
+
+## 6. Run the workflow
+
+```bash
+spur workflow run <PKG_ROOT>/plugins/kk/workflows/kk-smart-seo.yaml \
+  --vars '{"options_file":"/abs/path/options.json"}' --quiet
+```
+
+Leave `work_dir` empty: `seo-preflight` allocates `.works/kk-smart-seo/<UTC-stamp>-<runId>` with
+create-new semantics (an existing non-empty directory is refused) and writes the resolved absolute
+path to `.spur/run/<runId>-seo-work-dir.txt`, which the workflow reads back into `work_dir` before
+collection. A fixed `work_dir` must name an absent or empty directory.
+
+Stages: `preflight → collect → check → enrich → judge → score → narrative → report`, terminal
+`done | partial | failed`. `done` means every requested stage assessed its eligible evidence — not
+that the site has no SEO issues. `partial` is successful artifact delivery with missing requested
+evidence (an unavailable optional PSI/CrUX/typed-decision input is never a failure). `failed` is the
+sole failure state.
+
+Individual stages stay independently callable for review and re-scoring:
+
+```bash
+kk stage run seo-preflight <work_dir> <options_file> [run_id] [require_decisions]
+kk stage run seo-collect <work_dir>
+kk stage run seo-check <work_dir>
+kk stage run seo-enrich <work_dir>
+kk stage run seo-judge <work_dir>
+kk stage run seo-score <work_dir> [new_revision_dir]
+kk stage run seo-report <work_dir>
+```
+
+## 7. Progress
+
+- `spur workflow trace <run-id>` — the action trace; the state id tells you which stage is running.
+- `.spur/run/<runId>-seo-work-dir.txt` — the run-bound workspace path (never guess it).
+- `.spur/memory/runs/<run-id>.md` — the two-file run record.
+- Stage progress goes to stderr and is captured in the run record; long collection stages are
+  bounded by `max_requests`/`deadline_seconds`, so a run always terminates.
+
+Artifacts under the work dir, one run id shared by all of them: `options.json`, `manifest.json`,
+`crawl.json`, `checks.json`, `judgments.json`, `performance.json`, `visibility.json`, `audit.json`,
+`digest.md`, `narrative.json` (optional), `report.json`, `report.md`. Every JSON object carries
+`schemaVersion`, `methodVersion`, `runId`, `createdAt`, `inputDigest` and predecessor digests;
+wrong run, version or digest is a hard error. Writes are sibling temp file + rename, so a reader
+never sees a partially written value. The saved audit is durable under `.works/`, not volatile
+`.spur/run/`.
+
+## 8. Failure handling
+
+| Symptom | Handling |
+| --- | --- |
+| Missing/unserved SEO catalogs | Apply §2, re-run. Preflight failure text names the missing files/ids. |
+| Invalid options | Fix the named field; the file is validated before any collection. |
+| `work_dir` already populated | Use the run's own bound directory, or a new empty one. Never clear a directory from a previous run — preflight never deletes it. |
+| Network policy refusal (local/reserved address, peer mismatch, redirect off-scope) | The collected observation is recorded as unavailable/blocked. Do not work around it: an off-scope or non-public target is out of the audit's trust boundary. |
+| Budget exhaustion (`limits.hitLimit`) | Report it as a limit. Never present an exhausted crawl as a complete one. |
+| Optional evidence unavailable (no PSI/CrUX key, insufficient sample, 429, timeout) | Recorded as an availability outcome; the report is `partial`, never failed and never a zero score. |
+| Maker fallback / low confidence | The judgment stays `unknown`/`review`. It is not a site defect and not a measurement. |
+| Malformed predecessor artifact | Hard error, nonzero exit — malformed input is never reinterpreted as an empty result. |
+| Narrative absent or rejected | The report is still delivered with `narrativeStatus: omitted|rejected` and a deterministic summary; an optional agent failure is not an audit failure. |
+| Cancellation | Active sockets and decision children are aborted, completed artifacts are preserved with a cancellation marker, and no new requests or decisions start. |
+
+## 9. Offline rescoring
+
+Score a saved audit again without touching the network or the source run:
+
+```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 bounded inputs (`options.json`, `manifest.json`, `crawl.json`,
+`checks.json`) beside a fresh `audit.json`, keeps the original `runId` and adds a new `revisionId`.
+Source artifacts stay immutable, so a comparison between revisions reads two durable directories.
+Do not compare scores across runs with different coverage: `coverage` records the denominators,
+and the score is undefined (`null`) when no row of that category is applicable.