@profile-as-code/cli 0.3.6 → 0.3.7

package/README.md

@@ -58,14 +58,23 @@ commands above are the standalone path.
 |---|---|---|
 | `pasco init [dir]` | Scaffold a profile-data workspace (`content/identity.yaml`, `README.md`, `.pascorc`) — `pasco validate`-clean | ✅ |
 | `pasco validate [--json]` | Schema **fail** (exit 1) + drift/geo **warn** (exit 0) — D12 | ✅ |
+| `pasco doctor [--json]` | **Engine · schema · workspace** on one line (#348): the installed CLI version, the profile-contract version this build validates (from the schema `$id`), the resolved workspace and whether it loads, plus the **effective** `.pascorc` engine requirement (the strictest declaration in every config the resolution consulted, with its file). `--json` emits `{ engine, schema, workspace, requirement: { declared, met, problem?, source? } }`. Exit 0 healthy · 1 unhealthy · 2 usage; offline, no clock, no writes | ✅ v1 |
 | `pasco build [platform] [--lang]` | Deterministic base texts per platform+lang; platforms with a renderer (the eight registered in the generated renderer map) write `profiles/<platform>/README.md` + bundled media; renderer-less manual surfaces with a bio row write `profiles/<platform>.md` (#239). Empty render = no-trace unbuild of the generated output, preserving `profiles/<platform>/variants/` (chosen-variant input, #238; pure profiles/, §15.1 — v1.7). Media in `profiles/<platform>/assets/` + `assets/manifest.json` (M8/§18.6 — see `docs/media-pipeline.md`) | ✅ |
+| `pasco preview [--out <dir>] [--no-open] [--lang <l>] [--now <iso>] [--json]` | The **local view** (#282): **one** self-contained HTML file of the surfaces `pasco build` writes — inline CSS, no `<script>`, no external asset, no HTTP server. Sections are the published surfaces (`#github-readme`, `#linkedin`, …) plus the ones this language does not publish, named with their reason; the check state is the same report `pasco check` prints, and the text is `build`'s own render decision tree. Default `<workspace>/.pasco/preview/index.html`, then opened in the browser; `--out <dir>` writes and opens **nothing** (the CI-artifact transport). A privacy gate refuses the write (exit 1) on an absolute machine path, a credential shape, an external asset, active content, or a source outside the workspace | ✅ v1 |
 | `pasco edit <contract-path> [--set <text> [--check]]` | Resolve **one** contract field by contract path; `--set` **writes it** (comment-preserving range splice, validated, atomic) and `--set --check` previews the **published lines the edit changes** (or says it changes nothing). Epic #247, S1–S5 landed | ✅ S1–S5 (read · preview · write · surface impact · cap pre-flight · machine contract) |
 | `pasco diff [--json]` | Changes since the last `release-*` tag (git-based → CHANGELOG hint) | ✅ |
 | `pasco status [platform] [--mark <ledgerKey> <surface>] [--verify] [--write-checklist] [--completeness]` | Per-entry deploy report — origin · surfaces · in-sync/stale/never · **certification** (verified/attested/unverifiable/out-of-band-drift, §19.5) + the derived **publication truth** per surface (§20.1, #242) + ledger write paths (D18, §19) | ✅ |
+| `pasco presence [--json]` / `pasco release plan [<id>] [--json]` | **Presence board** (D23/§22, #262): every surface a release has addressed, at its newest release, with the ledger-derived state (`in-sync`/`stale`/`never`), and the **release plan** — the ordered fan-out (`repo-meta` → `profile` → `distribution`, then slug), each surface's state and the per-kind **factual spine**. Copy per channel lives in the shipped skills, not the engine | ✅ v1 |
 | `pasco refine <platform> [--lang] [--variants N] [--choose <id>]` | Agent-driven variant flow (D10/D11/D13); the chosen body is `profiles/<platform>/variants/<id>.md` (a complete platform artifact), rendered by `pasco build` (#238) | 🚧 template + `--choose` (full flow M3) |
-| `pasco check [platform]` | User checks from `content/checks.yaml` (schema-validated catalog) + registry rules (M7/§18.8) + media-transport rules (M8/§18.6) + offline `max-chars`/`min-chars` over headlines/bios (#240) | 🚧 offline rules today (limits + registry + media; remaining catalog M3/M4) |
-| `pasco post <seed\|task\|choose\|check\|export\|import\|list>` | Week-1 post MVP (#264): a seed at `posts/<seed>/seed.md` → task bundle → chosen variant → check → optional Postiz draft payload; the CLI never calls an LLM | 🚧 experiment (not in the v1 contract; `docs/post-mvp.md`) |
-| `pasco skills:export <dir> [--force] [--list]` | Copy the platform skills this package ships into a directory you name (`--list` shows them; no per-agent paths are invented — #254) | ✅ |
+| `pasco check [platform]` | User checks from `content/checks.yaml` (schema-validated catalog) + registry rules (M7/§18.8) + media-transport rules (M8/§18.6) + offline `max-chars`/`min-chars` over headlines/bios (#240) + `fact-present` (the built surface's fact tokens vs the SSOT render, #283) | 🚧 offline rules today (limits + registry + media + fact-present; remaining catalog M3/M4) |
+| `pasco discover <url>... [--json] [--allow-host <hosts>]` | **Provisional profile** from public surfaces (#329, SPEC §7.10), for a prospect with no workspace: reads schema.org JSON-LD + links only (no prose mining), attaches per-fact provenance (`attested: false`) and lists `absent` fields; reports the audit's class names with discovery's own predicates (SPEC §7.10); closed host allowlist checked before any request (sequential, no retries, no credentials); **writes nothing** | ✅ v1 |
+| `pasco audit [--json]` | Offline **diagnostic projection**, findings only (no score/prioritisation/branding, #283): three fixed classes — `dangling-ref` FAIL · `contradiction` FAIL · `unsourced-claim` WARN — exit 1 iff any FAIL; `--json` carries `{ schemaVersion: "1", scope: { declared, checked, notRun }, findings }` | ✅ v1 |
+| `pasco entity [--json \| --jsonld [--out <file>] [--bare]]` | The **entity projection** for surfaces the engine does not render (#287): `--json` is the frozen view — `entity { id, type, name, sameAs, email }`, the structured-data `gaps` (geoCheck codes verbatim), `jsonld: null` and `faqJsonLd` (the `FAQPage` node, `null` when the workspace declares no `faq[]`); `--jsonld` is the **same assembler output** the renderers embed, as paste-ready `<script type="application/ld+json">` blocks — the entity first, then the `FAQPage` when it exists (#360). Exit 1 when `@id` is absent (never invented) | ✅ v1 |
+| `pasco cite-check [<answers.ndjson>] [--json]` | The **citation matcher** over saved answer-engine answers (#291): reads the runner's NDJSON (stdin when no path), matches the workspace's declared entity and emits, **per answer and never aggregated**, `{ cited, confidence, spans, reasons }`. Ladder: `citation-url` (a citation on the entity's own page or its `sameAs` set — host, and the declared path or a descendant) and `exact-name` → **high**; `alias` (`identity.orgName`) and `handle` → **medium**; `partial` (any contiguous multi-token prefix, ≥ 2 tokens) → **low**, and low is never citable downstream. Refuses to guess: a one-word name with no declared disambiguator (`cited: false`, the longer capitalised reading named as `competing`), or a contrast mention, is not a citation; a declared qualifier or an adjacent capital never disqualifies a hit by itself | ✅ v1 |
+| `pasco export ai-policy [--out <dir> \| --check] [--lang <l>]` | The M9 stance as an artifact (#290): `--out` writes `robots.txt` (**two named groups, no wildcard** — the listed retrieval crawlers allowed, the listed training crawlers disallowed, each UA commented with its registry entry/operator/source/date; the file declares that a crawler it does not name is **not restricted**), `llms.txt` (the workspace index: name, definition, canonical identity, `faq[]`, `publications[]`, with a coverage assertion) and `AI-POLICY.md` (allowed · blocked · that same explicit-list limit · who can change it · the date, quoting the stance verbatim). `--check` exits 1 on an incomplete or unsourced entry, a duplicate token (case-insensitive), a malformed/future/`>180`-day `as_of`, or a `policy.as_of` that is stale or older than its newest row; `--out` refuses to write one. The UA list is projected from the platform registry — never hardcoded in the CLI | ✅ v1 |
+| `pasco export profile [--json] [--now <iso8601>]` | The **normalized profile** for programmatic consumers (#348): `{ schemaVersion, engine, source: { commit, generatedAt }, profile }` — `profile` is exactly what `core.load()` returns (**every root the workspace declares, plus every list root defaulted to `[]`**; an optional object root appears only when declared), never a platform slice (`compile()` makes that other object). `artifactRefs` ids resolve in `profile.artifacts[]`, `publications[].url` as declared, `deployments` included. No clock is read: `generatedAt` is `null` unless `--now` pins it, so two runs are byte-identical; `source.commit` is the workspace git HEAD (`null` outside a repo) | ✅ v1 |
+| `pasco post <seed\|task\|choose\|check\|export\|import\|list>` | Post experiment (#264/#265, long-form #266): a seed at `posts/<seed>/` → task bundle → chosen variant → check → Postiz draft payload (API channels) or paste checklist (Substack/Ghost). Two seed formats (`short`/`longform`); a short child derived from an essay records `derivedFrom`. The CLI never calls an LLM | 🚧 experiment (not in the v1 contract; `docs/post-mvp.md`) |
+| `pasco skills:export <dir> [--force] \| --list` | Copy the platform skills this package ships into a directory you name (`--list` shows them; no per-agent paths are invented — #254). A destination and `--list` are **separate invocations**: both together is usage (exit 2), never an ignored argument | ✅ |
 
 The partial commands are explicit, and each one says what still owns the rest:
 
@@ -77,21 +86,384 @@ The partial commands are explicit, and each one says what still owns the rest:
   #253). The full variant flow is M3 (`src/commands/refine.ts`).
 - **`check`** — executes the offline rules that exist today: the brand handle
   matrix (brand flavor only, D15/§17), the evidence-registry checks (M7/§18.8),
-  the media-transport rules (M8/§18.6), and the `max-chars` / `min-chars` rows
+  the media-transport rules (M8/§18.6), the `max-chars` / `min-chars` rows
   declared in `content/checks.yaml` over the headline/bio rows that exist
-  (offline, warn-class, #240). The remaining per-platform rules in the catalog
-  ship with the skills `checks.yaml` union (M3) and the full `pasco check` (M4).
-  It prints its `owner` line (`src/commands/check.ts`).
+  (offline, warn-class, #240), and **`fact-present`** — for the surfaces whose
+  catalog declares it (`content/checks.yaml` ∪ the shipped
+  `skills/<platform>/checks.yaml`): the artifact `pasco build` last wrote is
+  compared **symmetrically** against the SSOT render — a URL, ISO
+  date or number one side carries and the other does not, or a text difference no
+  fact token explains, is a finding — WARN in `check` (D12), because a published
+  surface that disagrees with the SSOT is a fact problem, not a schema one. A
+  targeted surface with no artifact reports the rule as **not run**, never as OK. The remaining
+  per-platform rules in the catalog ship with the skills `checks.yaml` union (M3)
+  and the full `pasco check` (M4). It prints its `owner` line
+  (`src/commands/check.ts`).
 - **`skills:export`** — copies the platform skills this package ships into the
   directory the user names (`--list` first; an existing non-empty directory needs
   `--force`). It replaces the earlier projection stub: the CLI never invents a
   per-agent destination and never points at tooling the reader cannot open
   (`src/commands/skills-export.ts`, #254).
-- **`post`** — the week-1 experiment (#264/#265): a CLI subcommand family over
-  the `posts/` store; it never calls an LLM, emits the agent task, records the
-  choice, checks limits/URLs/refs and exports a Postiz draft. It reads the
-  `skills/` bundled with the package (set `PASCO_SKILLS_DIR` only to point at a
-  custom tree), and it is **not part of the v1 contract yet** (`docs/post-mvp.md`).
+- **`post`** — the post experiment (#264/#265, long-form #266): a CLI
+  subcommand family over the `posts/` store; it never calls an LLM, emits the
+  agent task, records the choice, checks limits/URLs/refs (plus title/dek and
+  the word band for long-form) and exports a Postiz draft for API channels or a
+  paste checklist for Substack/Ghost. A seed is `format: short | longform`; a
+  short child derived from an essay records `derivedFrom: <essay-id>`. It reads
+  the `skills/` bundled with the package (set `PASCO_SKILLS_DIR` only to point
+  at a custom tree), and it is **not part of the v1 contract yet**
+  (`docs/post-mvp.md`).
+
+### The audit (`pasco audit --json`, #283)
+
+`audit` is an **offline JSON projection over existing checks** — not a second
+analysis engine and not a scoring surface. It aggregates per identity (where
+`check` is per document) and reports **findings only**: no score, no
+prioritisation, no branding. Those belong to the consumer (`PROP-017 §Module
+boundary`), and putting them in the engine would recreate the monolith the
+module split exists to prevent.
+
+```sh
+pasco audit                 # human list, one block per finding
+pasco audit --json          # machine contract
+```
+
+```json
+{
+  "schemaVersion": "1",
+  "scope": { "catalog": "shipped", "declared": ["github-readme"], "checked": ["github-readme"], "notRun": [] },
+  "findings": [
+    {
+      "class": "dangling-ref",
+      "severity": "FAIL",
+      "path": "projects[hub].links[0]",
+      "detail": "drift/url-not-in-identity — URL https://github.com/someoneelse lives on a platform host but is not in identity.links"
+    }
+  ]
+}
+```
+
+`scope` is the artifact side (the SSOT-side rules always run): `catalog` is
+`shipped` | `not-shipped` (a package without its skills tree cannot declare the
+premise — a bundle state, not "nothing declared"); `declared` are the targeted
+surfaces whose catalog declares the `fact-present` premise, `checked` the
+declared ones whose built artifact was compared, `notRun` the declared ones with no
+artifact on disk or no renderer for the flavor. **`declared: []` means the premise
+is not declared anywhere; `checked: []` means it measured nothing** — either way the
+audit says so instead of looking clean.
+
+| Class | Fires when | Severity |
+|---|---|---|
+| `dangling-ref` | a pointer does not resolve in the current view | **FAIL** |
+| `contradiction` | two surfaces assert incompatible values for one datum | **FAIL** |
+| `unsourced-claim` | a quantitative claim carries no evidence | **WARN** |
+
+`schemaVersion` is the contract version: a consumer refuses a version it does not
+know rather than guessing at the shape. `path` is a `factRef` (the row `id`
+replaces the array index when the row declares one); a finding about a built
+surface addresses the artifact path (`profiles/<surface>/README.md`), because a
+fact the SSOT does not carry has no `factRef` by definition.
+
+Exit `1` iff a `FAIL` finding exists, `0` otherwise (WARN-only included); `2` is
+a usage error, and a schema/load failure is the standard error envelope at exit
+`1`. The audit never touches the network, and no finding is derived from
+`content/deployments.yaml` (the ledger is not a fact source) — it works on a
+workspace that has neither a ledger nor a built artifact.
+
+What it composes (`docs/SPEC.md` §7.1): `load`/schema, `reconciledDrift` (drift
+plus the #238 variant-store reconciliation `validate` applies), `geoCheck` (its
+`faq-coverage` premise gates the claim rows; the codes themselves map to no class),
+the completeness `evidence` premise, and `fact-present`.
+
+It is **deliberately stricter than `validate`/`check`** on the two FAIL classes:
+D12 governs validity (drift facts warn, `validate` exits 0), while the audit's
+contract is publishability and the issue freezes the class severities. A drift fact
+in a FAIL class therefore exits 1 here and 0 there — declared in SPEC §7.1 and
+pinned by a test. Two inputs are deliberately NOT findings, declared in §7.1:
+`drift/url-not-in-identity` (the URL resolves — a canonicalization rule `validate`
+warns about) and `geoCheck`'s coverage codes.
+
+### The entity projection (`pasco entity`, #287)
+
+`audit` diagnoses; `entity` is the artifact for a surface this engine does not
+render (WordPress, Webflow, Next, a landing page). It exposes the **same** entity
+the renderers embed — `core/src/structured-data.ts` is the one assembler, so there
+is no CLI-local builder and no second truth (SPEC §7.2).
+
+```sh
+pasco entity --json                      # the frozen view: facts, @id, sameAs, gaps
+pasco entity --jsonld                    # paste-ready <script type="application/ld+json"> (+ FAQPage)
+pasco entity --jsonld --bare             # the bare JSON object (node array when faq[] exists)
+pasco entity --jsonld --out entity.html  # write the block (refuses an existing file)
+pasco entity --jsonld --out entity.html --force  # replace it (atomic write)
+```
+
+```json
+{
+  "schemaVersion": "1",
+  "entity": { "id": null, "type": "Person", "name": "Elena Vasquez", "sameAs": ["https://github.com/elenavasquez"], "email": null },
+  "gaps": [
+    { "code": "geo/entity-id", "detail": "no role: identity link — all 5 link(s) are role: realization (they indicate the entity, not are it). Mark the one that represents you role: identity to make the entity citable." }
+  ],
+  "jsonld": null
+}
+```
+
+`entity.id` is the URL of the `role: identity` link (the first one wins) or
+`null`: the engine **never invents an `@id`**. `gaps` are the `geoCheck` checks of
+its structured-data section that scored below 1, with the code and detail
+**verbatim** — no new vocabulary. `jsonld` is always `null` in `--json`; the
+artifact has its own mode, and `faqJsonLd` carries the `FAQPage` node the same
+mode emits when the workspace declares `faq[]` (`null` otherwise — never an empty
+`FAQPage`, never an invented `@id`, `faq[].source` travels as
+`acceptedAnswer.citation`). Parsing the `--jsonld` output yields exactly
+`structuredData()`'s object (plus the `FAQPage` node when there is one) —
+asserted by a test. `--bare` without `faq[]` stays byte-identical to the
+pre-#360 artifact.
+
+Both modes resolve **one** language (`--lang`, else `.pascorc` `defaults.lang`,
+else `en`): the readiness gaps are measured in the same language the JSON-LD is
+assembled, so a brand whose only populated `mission`/`tagline` is `es` cannot show
+`description` as missing while the block emits it.
+
+`--out` writes a temp file and renames it into place (atomic), and **refuses an
+existing file** unless `--force` is passed — a mistyped path must not truncate the
+SSOT. A write failure (existing file without `--force`, ENOENT, EACCES) is an error
+envelope at exit `1`, never a stack.
+
+Exit `0` when `@id` is present, `1` when it is absent (the entity has no declared
+home; the JSON-LD is still emitted, without `@id`) or the `--out` write failed, `2`
+for usage. It is offline and deterministic: no network, no clock, no AI.
+
+### The citation matcher (`pasco cite-check`, #291)
+
+Every GEO number is priced in "prompts monitored per month", and the half that
+decides whether the number is true is one question: **did this answer actually
+cite this entity?** The network half belongs to the runner; this command answers
+the matching question over the answers it already saved. It is a pure function of
+the SSOT and the input bytes — no network, no model, no clock (D19).
+
+```sh
+pasco cite-check answers.ndjson          # one line per answer
+cat answers.ndjson | pasco cite-check    # stdin when no path is given
+pasco cite-check answers.ndjson --json   # the frozen per-answer contract
+```
+
+Input — the runner's NDJSON, which this engine never produces:
+
+```json
+{ "engine": "chatgpt", "askedAt": "2026-10-23T15:00:00Z",
+  "question": "¿qué agencia GEO hay en Ecuador?",
+  "answer": "…", "citations": [ { "url": "https://…", "title": "…" } ] }
+```
+
+`answer` and `citations[]` are required; `engine`/`askedAt`/`question` are carried
+through. A blank line is ignored; any other malformed line is exit `2` naming the
+line and field — **never a silent skip**, because a skipped line changes a rate.
+
+The ladder is fixed, and each rung carries its own confidence:
+
+| Rung | What matched | Confidence |
+|---|---|---|
+| `citation-url` | a saved citation on the entity's own page or its `sameAs` set — host, and the declared path or a descendant (`github.com/<you>` does not match `github.com/someone-else`) | **high** |
+| `exact-name` | the full `identity.name`, word-bounded, case- and accent-insensitive (`Domínguez` = `Dominguez`) | **high** |
+| `alias` | `identity.orgName` | **medium** |
+| `handle` | `identity.handle` or a `socialHandles[]` row with `status: claimed` | **medium** |
+| `partial` | **any** contiguous multi-token prefix of the name (`DA SEO` and `DA SEO Digital` of `DA SEO Digital Studio`) — a term a higher rung already claims is not repeated | **low** |
+
+`confidence: "low"` is **never** a citation in a downstream report — the field
+exists so that refusal is explicit. The matcher also refuses to guess: a one-word
+name whose sentence has no declared disambiguator (`ambiguous-term:pasco` +
+`no-qualifier`, with the longer capitalised reading the text carries named as
+`competing:Pasco County School District`), a mention after a contrast marker
+(`contrast-context`), a shorter declared term inside a longer one
+(`longer-name:…`) and a citation URL the parser rejects (`url-invalid:<url>`, a
+missing scheme being the common case — named, never dropped) are all reported in
+`reasons[]` as **not** citations.
+
+```json
+{
+  "schemaVersion": "1",
+  "entity": { "name": "Pasco", "aliases": [], "handles": ["pasco_cli"],
+              "partials": [], "hosts": ["github.com", "linkedin.com", "x.com"] },
+  "answers": [
+    { "line": 1, "engine": "chatgpt", "askedAt": "…", "question": "…",
+      "cited": true, "confidence": "high",
+      "spans": [ { "start": 0, "end": 5, "kind": "name" } ],
+      "reasons": ["exact-name"] }
+  ]
+}
+```
+
+One row per input line, in input order, **never aggregated**: no rate, no score,
+no total — that belongs to the report layer. A citation span is
+`{ start: 0, end: 0, kind: "citation-url", url }` because the URL is in the
+answer's citation list, not in its text; text spans are offsets into the original
+answer. `entity` is the declared vocabulary the matcher resolved, so a report can
+say what it matched without re-reading the workspace.
+
+Exit `0` on a successful read whatever the matches (a non-citation is data) · `1`
+when the workspace or the input path cannot be read · `2` usage, or malformed
+NDJSON. Contract: SPEC §7.4.
+
+### The AI policy artifacts (`pasco export ai-policy`, #290)
+
+A profile publishes into a web where two kinds of machine reader arrive: the ones
+whose output is a **citation** (search and answer indexing, a fetch a user asked
+for) and the ones collecting material for **foundation-model training**. The
+project's stance (SPEC §12 M9) is that the second kind does not get the content
+unless the owner opts in — and until this command there was no file that said so.
+One command now emits all three, from the workspace and the platform registry:
+
+```sh
+pasco export ai-policy --out ./public   # robots.txt + llms.txt + AI-POLICY.md
+pasco export ai-policy --check          # exit 1 when the UA list is stale or unsourced
+```
+
+- **`robots.txt`** carries two *named* groups and never a wildcard: `ai-retrieval`
+  is `Allow: /`, `ai-training` is `Disallow: /`. Every `User-agent` line is
+  preceded by a comment naming its registry entry, operator, source URL and the
+  date that source was read, so a reader can tell **why** a crawler is in a group.
+  Because there is no `User-agent: *` group, the file restricts exactly the tokens
+  it lists: a crawler it does not name is **not restricted by it** (RFC 9309
+  §2.2.1). The artifacts **say that out loud** instead of claiming a default — the
+  list covers the crawlers whose classification has been checked against the
+  operator's own documentation, not the web.
+- **`llms.txt`** is the workspace index in the shape the project site already
+  uses: name, one-line definition, the canonical identity URL, the `faq[]`
+  answers, the citable `publications[]`, and a dated stamp. The builder asserts
+  that **every document it claims to index appears in the text** — a document
+  missing from the index is a silent hole, not a cosmetic bug.
+- **`AI-POLICY.md`** is the statement you send when a client asks "what is your AI
+  policy": what is allowed, what is blocked, who can change it, the date, and the
+  per-crawler table with each operator's own documentation URL.
+
+The crawler list is **derived data**: it lives in the `ai:` block of the platform
+registry, `pnpm gen:platforms` projects it into the engine, and the generator
+refuses an entry with no `source` or no `as_of`. `--check` fails an unsourced
+entry or a source older than **180 days**, and it gates the policy's own
+`as_of` (real date, inside the window, not older than the newest row it seals) —
+and `--out` runs the same check first, so a stale list becomes a failing command
+instead of a file that rots. Tokens compare **case-insensitively** (RFC 9309
+§2.2.1), so `GPTBot` and `gptbot` cannot slip in as two groups. No clock is
+read when writing: the stamp is the registry's review date, so two runs on
+different days produce byte-identical files.
+
+`--out` never truncates a file it did not generate: an existing `robots.txt` that
+is not ours needs `--force`. A refused write or a failed `--check` is exit `1`, a
+usage error is exit `2`. The `--json` contract is frozen in SPEC §7.3.
+
+### The normalized profile (`pasco export profile`, #348)
+
+`build` renders platform texts and `validate` checks the workspace, but neither
+hands a program to the **profile itself**. A site build, a service or a script
+that needs the facts used to re-implement `load()` + `normalize()` — and each copy
+drifted (roots hardcoded to `[]`, `publications[].url` dropped, `experience[].org`
+mistaken for a langMap). `export profile` is that object, assembled by the same
+`load()` every other command uses:
+
+```sh
+pasco export profile --json                                   # the payload
+pasco export profile --json --now 2026-10-28T00:00:00Z | jq .  # pin the stamp
+```
+
+```json
+{
+  "schemaVersion": "1",
+  "engine": { "name": "@profile-as-code/cli", "version": "<cli version>" },
+  "source": { "commit": "<workspace HEAD or null>", "generatedAt": null },
+  "profile": { "identity": {}, "…": "the normalized profile (see below)" }
+}
+```
+
+- `schemaVersion` is the payload's frozen version — the same key §7.1/§7.2 use: a
+  consumer **refuses a version it does not know** instead of guessing.
+- `source.commit` is the workspace's git `HEAD` — the value a consumer pins for
+  freshness — or `null` when the workspace is not inside a git repository.
+- `source.generatedAt` is **`null` unless you pass `--now <iso8601>`**, which is
+  emitted verbatim after a real-calendar check. The command reads no clock, so two
+  runs over one workspace are byte-identical (a malformed or impossible `--now` —
+  `2026-02-31` — is exit `1`, never a silent "now").
+- `profile` is the normalized `load()` object: **every root the workspace declares,
+  plus every list root defaulted to `[]`**. An optional object root (`newsletter`,
+  `podcast`, `audiences`, `active`) appears only when declared, because the
+  contract has no valid empty value for it. `artifactRefs` stay ids and resolve
+  against `profile.artifacts[]` (`load()` already refuses a dangling ref),
+  `publications[].url` is emitted as declared (never replaced by a DOI link), and
+  `deployments` is included. It is the SSOT — **not** a rendered surface, so
+  `visibility` is not filtered (renderers own §18.5) and there is no platform
+  slice (that is `pasco build`, via `compile()`).
+
+Exit `0` ok · `1` the workspace fails to load or `--now` is malformed · `2` usage
+(`--out`/`--check`/`--force`/`--lang` belong to `export ai-policy`). The contract
+is frozen in SPEC §7.5.
+
+**A consumer that only needs to validate** does not need this package at all: the
+released schema is published as a tag-pinned URL + sha256 in
+[`schema/consumer-contract.json`](https://github.com/ChristianLuciani/profile-as-code/blob/main/schema/consumer-contract.json).
+The manifest's `current` block is **not** a published artifact: schema v1.15 has
+no release tag yet (`published: false`, `artifact: null`), and the only released
+artifact is schema **v1.13 at tag v0.3.6**, which **rejects `publication.kind`**
+(`additionalProperties: false`) and has no `releases[]`. A consumer that needs
+either must use a v1.15 checkout (verify its sha256) until the next release. The reading guide is
+[docs/SCHEMA-CONTRACT.md](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SCHEMA-CONTRACT.md) —
+including what structural validation does **not** cover (the cross-file
+invariants core re-checks, engine behavior, `.pascorc` and this payload's
+envelope).
+
+### The local view (`pasco preview`, #282)
+
+`profile-data` is private because its data is personal, so there is no way to
+*see* the result without publishing something — and a private fork with Pages on
+publishes the data by default (personal plans have no access control). What was
+missing is a **view**, not hosting:
+
+```sh
+pasco preview                 # <workspace>/.pasco/preview/index.html, then opened
+pasco preview --no-open       # write it, open nothing
+pasco preview --out ./dist    # write ./dist/index.html, open nothing (CI)
+```
+
+**One file, two transports.** The artifact is the contract: one HTML document,
+inline CSS, no `<script>`, no external asset (no font, no CDN, no badge fetch),
+no HTTP server — it opens from `file://`, so nothing is published. A single file
+has no base URL to resolve, which is why there are no per-platform or
+per-language pages: one page with sections and anchors (`#github-readme`,
+`#linkedin`, …). A remote image in an artifact (a shields.io badge) is rendered
+as a text note instead of being fetched; workspace media is inlined as `data:`
+URIs. The header reads `generated <date> from <N> facts` — freshness, not a
+version — and `--now <iso8601>` pins that stamp so two runs are byte-identical.
+
+**What it composes.** The text per platform comes from the same decision tree
+`build` uses (active variant → renderer → shared paste source, with `build`'s
+selection gate), and the checks come from the same report `pasco check` prints.
+`preview` never touches `profiles/`; its default destination is
+`<workspace>/.pasco/preview/`, untracked as long as the workspace ignores
+`.pasco/` — a destination inside a git work tree that does not gets a warning
+that also travels in the page's own notes.
+
+**The privacy gate.** The public site publishes public entries only; the preview
+carries your working data, so it **refuses** and writes **no file**:
+
+| Rule | Refuses |
+|---|---|
+| `absolute-path` | a machine path (`/Users/…`, `C:\…`, `file:///…`) in the document |
+| `credential` | a pasted token or private key (token shapes, `secret: <16+ non-space>` assignments) |
+| `external-asset` | a `<link>`, a remote `src`, `url(https:…)`, `@import` |
+| `active-content` | a `<script>`, an `on*=` handler, an `<iframe>`, a `javascript:` URL |
+| `source-outside-declared-roots` | a source that resolves outside the workspace (a symlink escape) |
+| `source-missing` · `credential-file` | a declared source that is gone; a dotfile-shaped asset (`.env`, `.netrc`, `id_rsa`, `*.pem`) |
+
+Evidence-root media is never inlined (a per-machine path never reaches a render);
+an oversized image is left out and listed, never silently dropped. The gate's
+own refusal classes are exercised by the package test suite.
+
+**Limits, stated.** `--out` into a git work tree without an ignore entry warns —
+a preview committed by accident is the leak the command exists to avoid. The
+preview does not edit, does not encrypt (that breaks the no-JS invariant), and
+does not enforce: it reports the check state, `pasco check` remains the gate. The
+CI-artifact transport is a workflow in your workspace template, `workflow_dispatch`
+only, with no Pages; the artifact is readable by anyone with repository access.
 
 ### Contract paths (`pasco edit`, epic #247 — read · preview · write)
 
@@ -317,11 +689,22 @@ pasco status                          # …also prints the derived publication-t
 pasco refine linkedin --variants 3            # emits the agent task template (full flow M3)
 pasco refine linkedin --choose li-en-2        # records the chosen variant in content/active.yaml
 pasco check github-readme
+pasco audit                                  # findings only: dangling-ref · contradiction · unsourced-claim
+pasco audit --json                           # { schemaVersion, findings } — exit 1 iff any FAIL
+pasco entity --json                          # entity facts + @id + sameAs + gaps (exit 1 without @id)
+pasco entity --jsonld                        # paste-ready <script type="application/ld+json"> (+ FAQPage)
+pasco cite-check answers.ndjson              # per answer: cited? high/medium/low + why
+pasco cite-check answers.ndjson --json       # { schemaVersion, entity, answers[] }
 pasco post seed demo --text seed.md           # week-1 experiment: posts/<seed>/seed.md
+pasco post seed essay --text essay.md --format longform   # essay/newsletter seed
 pasco post task demo --channel linkedin,x   # task bundles (no LLM call)
+pasco post task essay --format longform --channel medium,substack
+pasco post task demo-x --format short --from essay --channel x  # derived family
 pasco post choose demo --channel linkedin --variant linkedin-1
 pasco post check demo                        # limits + URLs + {{fact:...}} refs
-pasco post export demo --target postiz       # POST /posts draft payload
+pasco post export demo --target postiz       # Postiz payload, or a paste checklist
+pasco export ai-policy --out ./public        # robots.txt + llms.txt + AI-POLICY.md (M9)
+pasco export ai-policy --check               # exit 1 on an unsourced or >180-day UA list
 pasco skills:export --list                   # skill channels shipped with this package
 pasco skills:export ./pasco-skills           # copy them to a directory you choose
 ```
@@ -336,6 +719,7 @@ file) > current directory.
 ```json
 {
   "workspace": ".",
+  "engine": "0.4.0",
   "defaults": { "lang": "en", "variants": 3 },
   "diff": { "tagPattern": "release-*" },
   "completeness": {
@@ -349,6 +733,18 @@ file) > current directory.
 }
 ```
 
+The `engine` field is the **minimum** CLI version this workspace requires
+(#348, SPEC §7.6), written as exactly `MAJOR.MINOR.PATCH` (a lower bound, not a
+semver range). `validate`, `build`, `export profile` and `preview` check it before doing
+any work: an older install exits `1` with the required version, the installed
+version and the upgrade command; a malformed value exits `1` with the accepted
+syntax. Absent means no requirement. Every `.pascorc` the resolution consulted is
+read — with no `--workspace` flag, the cwd `.pascorc` that resolved the workspace
+AND the workspace's own file — and the **stricter** declaration wins; a malformed
+one in either file is refused. `pasco doctor` reports the same effective
+requirement in one line (with the file it came from); it does not replace the
+gate, and it exits `1` when the workspace is unhealthy.
+
 The `completeness` block is the policy for `pasco status --completeness` (issue
 #102): `target` names the milestone; `langs` sets which languages text coverage is
 measured in; `items` overrides the shipped weights per catalog id (a weight of `0`
@@ -361,7 +757,7 @@ written to the workspace; only this policy is stored.
 | Code | Meaning |
 |---|---|
 | `0` | OK — schema valid. Drift warnings still exit 0 (D12: facts warn, schema fails). |
-| `1` | Schema or operational failure (workspace not found, bad YAML, not a git repo for `diff`), **or a data finding that blocks the command** (`edit`: the address is not exactly one row, or the edit does not change the published artifact). |
+| `1` | Schema or operational failure (workspace not found, bad YAML, not a git repo for `diff`), **an unmet or malformed `.pascorc` `engine` requirement** (`validate` · `build` · `export profile` · `preview`, before any work), **or a data finding that blocks the command** (`edit`: the address is not exactly one row, or the edit does not change the published artifact; `audit`: at least one `FAIL` finding; `export ai-policy`: an unsourced or stale UA list, or a refused write; `preview`: the privacy gate refused a document, or the write failed). |
 | `2` | Usage error (unknown command/platform/lang, bad flags). |
 
 Human output is EN by default (D8/§11); `--json` prints a machine-readable