@profile-as-code/cli 0.3.7 → 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,22 +93,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 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]]` | 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 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) + `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 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; `docs/post-mvp.md`) |
+| `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:
@@ -83,11 +119,12 @@ 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), the `max-chars` / `min-chars` rows
-  declared in `content/checks.yaml` over the headline/bio rows that exist
+  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
@@ -97,13 +134,12 @@ The partial commands are explicit, and each one says what still owns the rest:
   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`).
+  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).
+  (#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
@@ -112,7 +148,7 @@ The partial commands are explicit, and each one says what still owns the rest:
   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 post experiment notes](https://github.com/ChristianLuciani/profile-as-code/blob/main/docs/post-mvp.md)).
 
 ### The audit (`pasco audit --json`, #283)
 
@@ -170,7 +206,7 @@ a usage error, and a schema/load failure is the standard error envelope at exit
 `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
+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`.
@@ -187,7 +223,7 @@ warns about) and `geoCheck`'s coverage codes.
 
 `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
+the renderers embed — the engine's single assembler, so there
 is no CLI-local builder and no second truth (SPEC §7.2).
 
 ```sh
@@ -400,13 +436,13 @@ 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) —
+[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).
@@ -477,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
@@ -488,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
@@ -504,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).
@@ -518,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
@@ -557,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,
@@ -568,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)
 
@@ -595,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:`) |
@@ -616,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 |
 |---|---|
@@ -666,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
 
@@ -687,7 +783,7 @@ 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
@@ -783,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.