@profile-as-code/cli 0.3.6 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 The `pasco` CLI — `@profile-as-code/cli`. Consumes `@profile-as-code/core`
 (`load`/`driftCheck`/`geoCheck`/`compile`) — it never re-implements them. The
-contract source is `schema/profile.schema.json` (D3); Zod is generated in core.
+contract source is [the profile schema](https://github.com/ChristianLuciani/profile-as-code/blob/main/schema/profile.schema.json) (D3); Zod is generated in core.
 
 ## Install
 
@@ -22,14 +22,14 @@ server, no account.
 > npm-publish attestations + SLSA provenance v1; `0.3.6` is prepared in this release
 > (CHANGELOG `[0.3.6]`). The `0.3.0` tarball carries none because it was published while
 > the source repository was private.
-> Source install: [User Guide §2](../../docs/USER-GUIDE.md#2-install-the-pasco-cli).
+> Source install: [User Guide §2](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/USER-GUIDE.md#2-install-the-pasco-cli).
 
 ## Get a workspace
 
 `pasco` reads a **workspace folder** (`content/*.yaml` + `.pascorc`) by configured
 path. That folder does not have to be a git repository, and it does not have to live
 on GitHub — a repo is the **recommended** place to keep it, not a requirement
-([SPEC §9](../../docs/SPEC.md)). Three on-ramps, each with its capability difference
+([SPEC §9](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md)). Three on-ramps, each with its capability difference
 stated up front:
 
 | On-ramp | What you get | Automation + history | Account + repo |
@@ -48,9 +48,44 @@ The two no-account on-ramps keep the whole engine command set except `pasco diff
 history — `pasco init` is minimal on purpose, and the complete package lives in
 the template. **Where each on-ramp is discovered:** the template repo's own README,
 this package page, and — in the repository — the
-[User Guide §3](../../docs/USER-GUIDE.md#3-create-your-workspace-profile-data-username)
-(EN). Links into `docs/` resolve in the repository, not on this npm page: the two
-commands above are the standalone path.
+[User Guide §3](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/USER-GUIDE.md#3-create-your-workspace-profile-data-username)
+(EN). The links point at the public repository; the two commands above are the
+standalone path.
+
+## How the cycle resolves (three questions)
+
+**What does `fact-present` compare?**
+
+> **Symmetric**: a URL the surface adds → `dangling-ref`; a URL it omits, a date or
+> number either side carries and the other does not, or a projected text difference
+> with no token to attribute → `contradiction`.
+
+> All are WARN (D12: facts warn), and a targeted surface with no artifact on disk
+> reports the rule as **not run**, never as OK
+
+Canonical home: [SPEC §7](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md#7-core-interfaces-deep-module).
+
+**In what order does `build` choose an artifact?**
+
+> **The artifact source is resolved in ONE fixed order** (`renderArtifact`): an
+> active variant body (#238, written verbatim as the platform artifact) → the
+> platform renderer from the generated renderer map → the shared paste source
+> (#239, a manual-paste surface writes `profiles/<platform>.md`). First match wins;
+> `preview` and `edit --check` read the same tree.
+
+Canonical home: [SPEC §7](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md#7-core-interfaces-deep-module).
+
+**Where do the per-platform character caps come from?**
+
+> The **limit executor** measures the workspace's `content/checks.yaml` when it
+> declares checks, else the caps shipped with the package (#240); the `max-chars`
+> rows the shipped `skills/<platform>/checks.yaml` declare are **declared and not
+> executed** — no skill row reaches that executor.
+
+> a platform with no sourced cap reads `cap unknown` in text mode (`limit: null` in
+> `--json`)
+
+Canonical home: [SPEC §7](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md#7-core-interfaces-deep-module). The gap these clauses state is tracked in #455.
 
 ## Commands
 
@@ -58,14 +93,24 @@ 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 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 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 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, state, problem?, source? } }`, where `state` is `absent` · `met` · `NOT MET` · `INVALID` — an absent declaration is a state, never a silent pass. 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 [the media pipeline guide](https://github.com/ChristianLuciani/profile-as-code/blob/main/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]]` · `--list [<block>]` · `--create <root> [--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). Covers the answer-engine surface too: `identity.definition.<lang>`, `faq[id=<slug>,lang=<l>].q|.a` and `faq[id=<slug>].source` (#435). `--list` is the read-only discovery surface: every addressable row, one per line, `--json` as `{ addresses: [{ address, kind, readOnly }], warnings }` (#411). `--create <root>` seeds a root the workspace does not declare yet (`content/faq.yaml`): schema-valid template, refused when the root exists, same validation + cap pre-flight, `--check` previews it (#435). Epic #247, S1–S5 landed | ✅ S1–S5 (read · preview · write · surface impact · cap pre-flight · machine contract) + `--list` + `--create` |
 | `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 status [platform] [--mark <ledgerKey> <platform>] [--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]` | The workspace's checks declared in `content/` (schema-validated catalog) — or the conservative caps shipped with pasco when it declares none (#240) — + 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>] [--observations <file>]` | **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). `--observations` takes the rows a human read by hand (`surface`, `field` = `name`/`link`/`experience`, `value`, `url`, `retrieved_at`) for surfaces the machine cannot read (LinkedIn 999, no `Person` node): no request is made, the rows enter the same provisional profile/findings, and `--json` (payload **v2**: `via`, nullable `status`) marks each surface `via: fetch|manual`; a disagreement between two surfaces is a `contradiction` (two different names included). **Writes nothing** | ✅ v1 |
+| `pasco achievements [--targets] [--json]` | The **career impact log** (D24/§23, #446): one row per result — `metric` (`value`/`target`/`baseline`/`unit`/`direction`) or `milestone` — with the units it belongs to (`refs`), how the result is known (`basis`) and its required `visibility`. The status is **DERIVED** at read time (`planned` · `measured` · `achieved` · `partial`), never stored; `--targets` prints only the planned goals; `--json` emits `{ schemaVersion: "1", scope, achievements }`. Read-only | ✅ 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; [the post experiment notes](https://github.com/ChristianLuciani/profile-as-code/blob/main/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:
 
@@ -74,24 +119,387 @@ The partial commands are explicit, and each one says what still owns the rest:
   `--choose` records the pick in `content/active.yaml`. The platform skill ships
   **inside this package**, so the template prints its real path on an npm install
   (and says `no skill for <platform>` vs `skills not shipped` distinctly —
-  #253). The full variant flow is M3 (`src/commands/refine.ts`).
+  #253). The full variant flow is M3.
 - **`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
-  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`).
+  the media-transport rules (M8/§18.6), the `max-chars` / `min-chars` rows
+  declared in the workspace's `content/` (or the package's conservative caps when
+  it declares none) over the headline/bio rows that exist
+  (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).
 - **`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`).
+  (#254).
+- **`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**
+  ([the post experiment notes](https://github.com/ChristianLuciani/profile-as-code/blob/main/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 ([SPEC §7.1](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md)): `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 — the engine's single 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
+[the consumer contract](https://github.com/ChristianLuciani/profile-as-code/blob/main/schema/consumer-contract.json).
+This CLI releases schema **v1.16** at tag `v0.4.0`, so the tag-pinned artifact is
+`https://raw.githubusercontent.com/ChristianLuciani/profile-as-code/v0.4.0/schema/profile.schema.json`
+(the tag is the release trigger, so it exists before this tarball is published). A
+consumer that needs `achievements[]` reads that tag; one that does not can keep pinning
+`v0.3.7` unchanged. The reading guide is
+[the schema contract reading guide](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)
 
@@ -105,7 +513,10 @@ pasco edit positioning.statement.en                       # the current value
 pasco edit positioning.statement.en --set "…" --check       # the published lines this edit changes
 pasco edit positioning.statement.en --set "…"               # write it (one line, comments intact)
 pasco edit headlines[platform=github-readme,lang=en].text --set "…" --check
+pasco edit identity.definition.en --set "…"                 # the canonical definition
+pasco edit 'faq[id=what-is-elena,lang=en].a' --set "…"      # one answer
 pasco edit identity.links[platform=github].url              # read-only (the URL SSOT)
+pasco edit --create faq                                     # seed a missing root (content/faq.yaml)
 ```
 
 Addressable fields (by **contract path**, never by line/offset — the schema is the
@@ -116,8 +527,51 @@ authority on what a field is):
 | `positioning.statement.<lang>` | `positioning.statement[lang]` (`lang`: `en`/`es`/`fr`) |
 | `headlines[platform=<p>,lang=<l>].text` | the matching `headlines[]` row |
 | `bios[platform=<p>,lang=<l>,length=<len>].text` | the matching `bios[]` row |
+| `identity.definition.<lang>` | the canonical per-language definition (#288, v1.10) |
+| `faq[id=<slug>,lang=<l>].q` / `.a` | one `faq[]` row's question/answer for that language — `q`/`a` are langMaps, so `lang` is **required** |
+| `faq[id=<slug>].source` | the row's optional http(s) pointer (`lang` does not apply) |
 | `identity.links[platform=<p>,label=<l>].url` | the row's URL — **read-only**; `label` disambiguates two links on one platform |
 
+`faq[]` is selected by its stable `id`, never by array index: a repeated id matches
+more than one row and the command refuses to choose, exactly like a duplicate
+bio. An optional field the row does not carry (`source`, or `q.es`) is **0 rows** —
+`edit` never creates it; the row itself must already exist.
+
+**Finding the path (`--list`, #411).** `pasco edit --list` prints every
+addressable row of the loaded workspace — read-only and deterministic, built by
+the same constructors resolution uses, never a second grammar:
+
+```sh
+pasco edit --list                       # every block, one address per line
+pasco edit --list headlines             # scope: positioning | headlines | bios | identity.definition | identity.links | faq
+pasco edit --list --json                # { addresses: [{ address, kind, readOnly }], warnings }
+```
+
+Link rows are marked `(read-only)`. A link row whose platform cannot be
+expressed as a selector (empty, padded, or carrying `,`, `]`, `=`, `"` or a
+control character) is a **warning**; a **label** the grammar cannot express is
+dropped and the row is listed by its platform when that resolves to one row (the
+warning says so). Any address that resolves to **more than one row** (a duplicate
+headline/bio, a label-less link sharing its platform) is a warning too: the list
+advertises only paths that resolve to exactly one row, the bar `edit` enforces. `--list` never locates a CST
+node, never takes `content/.pasco-edit.lock` and writes nothing; an empty
+workspace prints the header alone (exit 0). Combining `--list` with `--set`,
+`--check`, `--create` or an address is usage (exit 2), never a silently ignored
+argument.
+
+**Creating a missing root (`--create`, #435).** The splice never invents bytes, so
+it cannot create `content/faq.yaml` — the answer-engine surface the product
+exists to be quoted through. `--create <root>` is a **different operation**, not
+a rewrite of the writer: it writes a schema-valid **template** for a root the
+workspace does not declare yet, refuses when the root already exists (idempotent:
+nothing is written, exit 1), and validates the result through the same `load()`
+gate over a temp copy before the file reaches disk. It runs the same cap
+pre-flight as `--set`, and `--check` previews the seed (validates it, writes
+nothing). Both the root name and the file form are accepted:
+`pasco edit --create faq` / `pasco edit --create content/faq.yaml`. Seedable
+roots today: `faq` (3 placeholder pairs — the schema minimum). Every value is a
+`<placeholder>` the owner replaces: the engine never invents facts (D11/D14).
+
 **The write (S2, #249).** A byte-range splice over the **original text**: the CST
 locates the scalar and only those bytes are replaced, so comments, alignment and
 layout survive *by construction* and the diff is **one line** (a document
@@ -132,7 +586,8 @@ command resolved — a row inserted or reordered since the address was resolved
 a **staleness** refusal (exit 1), not a silent write to the wrong row.
 Concurrent `pasco edit` writers on one workspace serialize on
 `content/.pasco-edit.lock` (a second waits 2 s, then refuses; a lock left by a
-crash is broken after 30 s); an external editor is caught by the re-read
+crash is broken after 30 s — `--create` takes the same lock and re-checks the
+root immediately before its exclusive create); an external editor is caught by the re-read
 immediately before the atomic rename. A symlinked
 content file keeps its link (the target is replaced) and the file mode is
 preserved. Re-setting an identical value is a **noop** (exit 0, nothing written).
@@ -146,7 +601,11 @@ it is honest where echoing the addressed row would not be: a paste surface
 publishes exactly **one** bio (length priority `long > medium > short`), several
 renderers never emit the statement, and a renderer-less surface carries no
 headline. In those cases the artifact does not change and the preview says so —
-with the reason, and exit `1`. It runs the writer's **eligibility and staleness
+with the reason, and exit `1`. Two #435 fields have a different published
+surface: `identity.definition` reaches the entity JSON-LD that `github-readme`
+and `github-org` embed (the preview shows that block), and `faq[]` has **no**
+`pasco build` artifact — its published surface is the `FAQPage` node
+`pasco entity --jsonld` emits (#360), so `--check` previews that node's bytes. It runs the writer's **eligibility and staleness
 checks first**, so `--check` refuses the same ADDRESSED shapes `--set` refuses
 (block/multi-line/anchored scalars, a stale row, a read-only **file**). A
 read-only **directory**, a validation refusal or a concurrent change can still
@@ -185,7 +644,12 @@ when the workspace declares checks, the **sourced caps shipped with pasco**
 otherwise — and prints the cap, its **cited source** and its provenance tier. Over-cap is a
 **warning**, never a block (D12: facts warn, schema fails): `edit` says so, `check`
 reports the same finding (same executor), and a platform with **no sourced cap**
-says `cap: unknown` instead of guessing a number.
+says `cap unknown` instead of guessing a number. The answer-engine fields are
+pre-flighted the same way against the **contract's** own caps (#435): 160 chars
+per `identity.definition` value, 90 per `faq[].q`, 320 per `faq[].a` (v1.10,
+#288, `[OFICIAL]`). Those are schema `maxLength`s, so over one the pre-flight
+warns and the **write is refused by validation** — the one place the cap is a
+failure, not a warning (D12).
 
 `--json` payload (inside the CLI's usual envelope, which also carries `command`,
 `ok` and `exitCode`): `{ address, current, proposed, rendered, ok, noop, written,
@@ -196,14 +660,17 @@ record; `null` for a read-only link or an address that is not one row), and
 `noop` says the value was already there, `written` says the file changed, and
 `warnings` carries the non-blocking findings a write proceeded through (a D22/§21
 selection error that makes `pasco build` refuse the workspace — the SSOT write is
-still valid, so it is reported, not blocked). Exit codes: **0** the write succeeded
-(or the noop was a noop), or the preview changes the artifact · **1** the address
-did not resolve to exactly one row, the target is read-only or changed under the
-command (stale), the validation refused the result, or (preview only) the artifact
-does not change or a D22/§21 selection error makes `build` refuse the workspace
-(`kind: "selection"`) · **2** usage (malformed address, read-only field, block/multi-line
-scalar, anchored/aliased scalar, a value with a line break, `--check` without
-`--set`).
+still valid, so it is reported, not blocked). `--create` carries its own payload
+(`{ mode: "create", root, file, created, preview, seed, limits, warnings }`). Exit
+codes: **0** the write succeeded (or the noop was a noop), the preview changes the
+artifact, or the seed was written/previewed · **1** the address did not resolve to
+exactly one row, the target is read-only or changed under the command (stale), the
+validation refused the result, `--create` found the root already present (nothing
+written), or (preview only) the artifact does not change or a D22/§21 selection
+error makes `build` refuse the workspace (`kind: "selection"`) · **2** usage
+(malformed address, read-only field, block/multi-line scalar, anchored/aliased
+scalar, a value with a line break, `--check` without `--set`, `--create` with an
+unknown root or next to `--set`/`--list`/an address).
 
 ### The machine contract (`--json`, S5 / #252)
 
@@ -223,7 +690,7 @@ are the envelope; the edit's own fields are
 | `stale` | `Record<surface, "in-sync" \| "stale">` | each **recorded** surface of the edited unit |
 | `state` | `"never" \| "in-sync" \| "stale" \| null` | the §19 unit rollup (`null` when the address is not one writable unit) |
 | `drift` | number | the measured drift-check count |
-| `limit` | `{cap, source, tier} \| null` | the applicable published cap; `null` when the catalog has none **or** the address type has no cap (a statement or a link) |
+| `limit` | `{cap, source, tier} \| null` | the applicable published cap (the catalog's for headline/bio, the contract's for definition/faq); `null` when there is none **or** the address type has no text cap (a statement, a link, `faq[].source`) |
 | `over` | boolean | the value exceeds that cap |
 | `variant` | string \| null | the active #238 variant shadowing the **addressed platform** (a statement names its variants in `warnings` instead) |
 | `reason` | string \| null | why the preview does not reach the artifact (the same sentence the human output prints as `why:`) |
@@ -244,9 +711,9 @@ finding in `warnings` (the SSOT write is valid even when `build` refuses).
 nobody edits a field the renderer ignores.
 
 Exit codes (one row per user-visible state; the CLI rows are pinned in
-`packages/cli/tests/edit.test.ts`, the write-path rows — stale, read-only,
+[the edit command tests](https://github.com/ChristianLuciani/profile-as-code/blob/main/packages/cli/tests/edit.test.ts), the write-path rows — stale, read-only,
 validation, lock contention — at the writer seam in
-`packages/cli/tests/edit-write.test.ts`):
+[the edit write tests](https://github.com/ChristianLuciani/profile-as-code/blob/main/packages/cli/tests/edit-write.test.ts)):
 
 | Code | When |
 |---|---|
@@ -294,8 +761,9 @@ It is **derived and never stored**: `--json` carries it as the additive
 `publication` array, `--completeness` folds it in as *coverage of publication*
 (the weighted percentage never moves because a surface drifted), and
 `--write-checklist` writes the coverage phrase into the generated `CHECKLIST.md`.
-The path is `src/publication.ts` (one home for artifact resolution and the three
-axes) and `src/limits.ts` (the cap executor `check` and `status` share).
+The resolution lives in [the publication module](https://github.com/ChristianLuciani/profile-as-code/blob/main/packages/cli/src/publication.ts)
+(one home for artifact resolution and the three axes), and the cap executor `check`
+and `status` share lives in [the limits module](https://github.com/ChristianLuciani/profile-as-code/blob/main/packages/cli/src/limits.ts).
 
 ## Usage
 
@@ -315,13 +783,24 @@ pasco status --write-checklist        # regenerate CHECKLIST.md from the ledger
 pasco status                          # …also prints the derived publication-truth line:
                                       #   github-readme: in-sync · artifact: matches-SSOT · limits: ok
 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 refine linkedin --choose linkedin-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 +815,7 @@ file) > current directory.
 ```json
 {
   "workspace": ".",
+  "engine": "0.4.0",
   "defaults": { "lang": "en", "variants": 3 },
   "diff": { "tagPattern": "release-*" },
   "completeness": {
@@ -349,6 +829,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 +853,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
@@ -387,7 +879,6 @@ script, no nag on every command:
 - [Patreon](https://www.patreon.com/cluciani)
 - [GitHub Sponsors](https://github.com/sponsors/ChristianLuciani)
 
-A tip funds the engine (`packages/core`) and this CLI — the schema contract
-(`docs/SPEC.md`), the renderers and the platform skills. It buys **no** SLA, no
+A tip funds the engine and this CLI — the [schema contract](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/SPEC.md), the renderers and the platform skills. It buys **no** SLA, no
 priority handling, and no influence over the roadmap: a proposal is weighed on
 its merits, in public. The code stays MIT — it is yours whether you tip or not.