agentera 3.0.0-dev.23 → 3.0.0-dev.25

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -332,7 +332,7 @@ structured_output:
             derives from the same `_decision_context_entry` and
              `_decision_satisfaction_context` semantics as bounded `agentera state
              decisions list --limit 20 --format json` plus exact `state decisions
-             get --number N`, never infers satisfaction, never mutates `.agentera/decisions.yaml`,
+             get --id ID`, never infers satisfaction, never mutates decision entities,
             keeps top-level attention bounded, and must not change `next_action`
             routing priority.
           evidence_context_target_contract: evidence_context_target_contract
@@ -491,13 +491,13 @@ evidence_context_target_contract:
         fallback: none when complete_for_plan_artifact is true
       - family: progress_verification
         source: agentera state progress list --limit 20 --format json latest verification
-        fallback: agentera state progress get --number N --format json
+        fallback: agentera state progress get --id ID --format json
       - family: docs_state
         source: agentera state docs --format json summary and entries
         fallback: agentera state docs --format json
       - family: health_state
         source: agentera state health list --limit 20 --format json latest audit
-        fallback: agentera state health get --number N --format json
+        fallback: agentera state health get --id ID --format json
       - family: todo_state
         source: agentera state todo --format json known issues and source-contract TODOs
         fallback: agentera state todo --format json

package/bundle/references/cli/prime-consumer-compatibility.yaml

@@ -40,7 +40,7 @@ consumers:
       - plan.first_pending.name
       - progress
       - progress.latest
-      - progress.latest.number
+      - progress.latest.id
       - progress.latest.what
       - progress.latest.next
       - next_action
@@ -581,7 +581,7 @@ fixtures:
           present_when: health.exists
         - path: plan.first_pending.name
           present_when: plan.first_pending
-        - path: progress.latest.number
+        - path: progress.latest.id
           present_when: progress.latest
         - path: progress.latest.what
           present_when: progress.latest

package/bundle/references/cli/update-channels.yaml

@@ -45,7 +45,8 @@ channels:
         supported 2.x line until you explicitly opt in through npm.
       guide_url: >-
         https://github.com/jgabor/agentera/blob/main/UPGRADE.md#upgrading-v2-to-v3-development-channel-irreversible
-      preview_command: npx -y agentera@next upgrade --dry-run --channel development
+      preview_command: npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
       irreversible_advisory: >-
         Forward migration to the successor line is one-way; return to the prior
         Python support line is permanently unsupported.
@@ -75,7 +76,8 @@ channels:
         The v3 successor line is npm-only; opt in to v2→v3 migration through npx @next.
       guide_url: >-
         https://github.com/jgabor/agentera/blob/main/UPGRADE.md#upgrading-v2-to-v3-development-channel-irreversible
-      preview_command: npx -y agentera@next upgrade --dry-run --channel development
+      preview_command: npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
       irreversible_advisory: >-
         Forward migration to the v3 line is one-way; return to the prior
         Python support line is permanently unsupported.

package/bundle/references/cli/vocabulary.md

@@ -16,7 +16,7 @@ included when they shape cross-suite usage.
 | `skills/agentera/protocol.yaml`                                    | Confidence, severity, decision labels, exit signals, visual tokens, glyphs, and phases.                                                                                                                                                                                                                                      |
 | `skills/agentera/capability_schema_contract.yaml`                  | Capability schema structure, required groups, priorities, and primitive-reference fields.                                                                                                                                                                                                                                    |
 | `skills/agentera/schemas/artifacts/*.yaml`                         | Artifact field grammar, status values, path contracts, and validation rules.                                                                                                                                                                                                                                                 |
-| `references/artifacts/artifact-registry-interface-model.yaml`      | Artifact identity facts: `artifact_id`, display name, default path, producers, consumers, type, scope.                                                                                                                                                                                                                       |
+| `references/artifacts/artifact-registry-interface-model.yaml`      | Internal artifact registry facts. Public state envelopes use `artifact` for the family and `id` for the stable public identifier.                                                                                                                                                                                             |
 | `references/cli/app-lifecycle-vocabulary.yaml`                     | App lifecycle canonical statuses, deprecated aliases, operation verbs, status concepts, and consumer ownership boundaries.                                                                                                                                                                                                   |
 | `references/cli/update-channels.yaml`                              | Stable and development update channels, dist-tag/git resolution, default channel, and override keys.                                                                                                                                                                                                                         |
 | `references/cli/bundle-skill-vocabulary.yaml`                      | Canonical concepts, compatibility boundaries, and classification rules for `bundle` and `SKILL.md` usage.                                                                                                                                                                                                                    |
@@ -215,11 +215,11 @@ ambiguous-term sweep remain separate follow-up work.
 | Severity band policy    | TODO.md severity bands (⇶ Critical, ⇉ Degraded, → Normal, ⇢ Annoying) may be header-only when they have no open work; open items use `- [ ] [type:train]` only. Authority: `skills/agentera/schemas/artifacts/todo.yaml` CONVENTION TC5; executable rule in `packages/cli/src/hooks/validateArtifact/markdown.ts` `validateMdItems`. |
 | Agent-facing artifact   | A structured YAML artifact under `.agentera/`, such as `.agentera/progress.yaml`.                                                                                                                                                                                                                                                    |
 | Global artifact         | A user-level artifact outside a project, such as `PROFILE.md` or `USAGE.md`.                                                                                                                                                                                                                                                         |
-| Canonical artifact name | Protocol `artifact_id` such as `plan`, `progress`, or `docs`; human-facing Markdown filenames such as `TODO.md` are `display_name` values, not protocol identity.                                                                                                                                                                    |
+| Canonical artifact name | Public `artifact` value such as `plan`, `progress`, or `docs`; human-facing Markdown filenames such as `TODO.md` are display labels, not protocol identity.                                                                                                                                                                         |
 | Resolved artifact path  | The actual path after consulting `.agentera/docs.yaml` mapping or the default layout.                                                                                                                                                                                                                                                |
-| Artifact mapping        | `.agentera/docs.yaml` rows that map `artifact_id` values to project-local paths and producers.                                                                                                                                                                                                                                       |
+| Artifact mapping        | `.agentera/docs.yaml` rows that map `artifact` values to project-local paths and producers.                                                                                                                                                                                                                                          |
 | ArtifactRegistry        | The registry interface model for artifact IDs, display names, default paths, producers, consumers, type, scope, and special cases.                                                                                                                                                                                                   |
-| `artifact_id`           | Machine identifier such as `progress`, `health`, `docs`, or `objective`.                                                                                                                                                                                                                                                             |
+| `artifact`              | Public artifact-family value such as `progress`, `health`, `docs`, or `objective`. Entity envelopes pair it with `id`, the stable public identifier whose grammar is owned by `references/artifacts/state-storage-authority.yaml`.                                                                                                     |
 | `display_name`          | Human-readable filename label such as `VISION.md` or `TODO.md`; registry-owned, not protocol identity.                                                                                                                                                                                                                               |
 | `default_path`          | Registry-owned path used when no docs mapping overrides it.                                                                                                                                                                                                                                                                          |
 | `local_role`            | Capability relationship to an artifact: `produces`, `consumes`, or `produces_and_consumes`.                                                                                                                                                                                                                                          |

package/bundle/skills/agentera/SKILL.md

@@ -57,6 +57,20 @@ For static routing guidance (agentera vs native tools):
 npx -y agentera prime --guidance
 ```
 
+### Upgrade from v2 to v3 development
+
+The preview is optional. Apply is one full command:
+
+```bash
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+```
+
+Apply requires the complete v2 migration source to be tracked by Git and
+unchanged at `HEAD`. The boundary is one-way: there is no rollback, restore,
+non-Git, or partial cross-major workflow. Rerun the same apply command after an
+interruption; recovery continues forward internally.
+
 ---
 
 ## Routing
@@ -145,11 +159,11 @@ Proceed/Cancel handoff.
 
 ## Artifact writes
 
-The CLI state writer is the canonical mutation path for `progress`, `decisions`,
-`plan`, and `health`. Do not hand-edit those artifacts during normal capability
-execution. The writer assigns numbers, validates schema fields, honors docs-mapped
-paths, serializes concurrent writes, compacts where required, and supports
-filesystem-safe previews.
+The CLI state writer is the canonical mutation path for entity-backed state.
+Every public record has `id` and `artifact`, lives in one writer-owned entity
+file, and is retrieved through bounded `list` or exact `get --id` commands. Do
+not edit `.agentera/entities/` directly. The writer assigns bare IDs, validates
+records, publishes atomically, and supports filesystem-safe previews.
 
 Discover the live contract before constructing a write:
 
@@ -168,9 +182,10 @@ Common mutations:
 
 - `agentera state progress append ... --format json`
 - `agentera state decisions append ... --format json`
-- `agentera state decisions update --number N ... --format json`
+- `agentera state decisions update --id ID ... --format json`
 - `agentera state plan create --input plan.yaml --format json`
-- `agentera state plan append|update|set-status|set-plan-status ... --format json`
+- `agentera state plan update|set-status --id ID ... --format json`
+- `agentera state plan set-plan-status --id ID ... --format json`
 - `agentera state plan archive --format json`
 - `agentera state health append --input audit.yaml --format json`
 
@@ -184,16 +199,15 @@ json` exposes the machine-readable writer operation matrix under
 
 ## Artifact path resolution
 
-The state writer resolves path mappings itself. Before directly reading or
-writing an artifact outside the writer contract, check if `.agentera/docs.yaml` exists.
-If it has an Artifact Mapping section, use the path specified for each canonical
-filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given
-artifact, use the default layout:
+The state writer resolves entity storage itself. Before directly reading or
+writing an intentional singleton outside the writer contract, check whether
+`.agentera/docs.yaml` maps it to another path. If no mapping exists, use the
+default singleton layout:
 
 - Human-facing artifacts at the project root: `TODO.md`, `CHANGELOG.md`, `DESIGN.md`
-- Agent-facing artifacts in `.agentera/` as YAML: `progress.yaml`, `decisions.yaml`, `health.yaml`, `plan.yaml`, `docs.yaml`, `vision.yaml`, `objective.yaml`, `experiments.yaml`
+- Agent-facing singletons: `.agentera/docs.yaml` and `.agentera/vision.yaml`
 
-Do not silently bypass the CLI and read raw `.agentera/*.yaml` files first. If
+Do not silently bypass the CLI and read raw entity files first. If
 CLI state declares complete coverage, do not perform defensive raw artifact
 reads. Use raw artifact reads only as a last-resort fallback after CLI
 fallback commands fail or declare incomplete state.

package/bundle/skills/agentera/capabilities/audit/schemas/artifacts.yaml

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: health
+    artifact: health
     local_role: produces_and_consumes
     description: >-
       Codebase health assessment with findings, dimension grades, and trajectory.
@@ -9,11 +9,11 @@ ARTIFACTS:
       severity and confidence scores, trend comparisons, and de facto
       architecture patterns. During evaluation startup, Audit consumes health
       state through CLI `evidence_context`, then bounded `agentera state health
-      list --limit 20 --format json` and exact `state health get --number N`.
+       list --limit 20 --format json` and exact `state health get --id ID`.
       Raw health reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Audit treats vision state as protected during evidence-context startup;
@@ -21,17 +21,17 @@ ARTIFACTS:
       instead of forcing a raw vision read.
   3:
     id: A3
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Audit consumes decision caveats through CLI `evidence_context`, then
       bounded `agentera state decisions list --limit 20 --format json` discovery
-      and exact `state decisions get --number N` retrieval. Raw decision reads
+       and exact `state decisions get --id ID` retrieval. Raw decision reads
       are diagnostic-only for corruption or CLI-defect investigation. Compacted
       decision caveats must be preserved rather than reconstructed.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Audit reads this to avoid re-reporting known issues and writes to it
@@ -41,17 +41,17 @@ ARTIFACTS:
       for corruption or CLI-defect investigation.
   5:
     id: A5
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Audit consumes latest progress verification and progress caveats through
       CLI `evidence_context`, then bounded `agentera state progress list --limit
-      20 --format json` discovery and exact `state progress get --number N`
+       20 --format json` discovery and exact `state progress get --id ID`
       retrieval. Raw progress reads are diagnostic-only for corruption or
       CLI-defect investigation.
   6:
     id: A6
-    artifact_id: plan
+    artifact: plan
     local_role: consumes
     description: >-
       Audit consumes evaluation target and plan criteria through CLI
@@ -59,7 +59,7 @@ ARTIFACTS:
       still provides the artifact-current-state baseline when that state is needed.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Audit treats design state as optional during evidence-context startup;
@@ -67,7 +67,7 @@ ARTIFACTS:
       diagnostic-only raw design read.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Audit reads this first to resolve project-local artifact mappings
@@ -76,7 +76,7 @@ ARTIFACTS:
       CLI `evidence_context` before any diagnostic-only raw docs read.
   9:
     id: A9
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Audit consumes profile status and stale-profile caveats through CLI

package/bundle/skills/agentera/capabilities/audit/schemas/validation.yaml

@@ -24,8 +24,8 @@ VALIDATION:
     id: V3
     rule: decisions_respected
     description: >-
-      Findings that contradict deliberate decisions documented in
-      .agentera/decisions.yaml MUST be discarded or downgraded to info
+      Findings that contradict deliberate decisions returned by the bounded
+      decisions entity view MUST be discarded or downgraded to info
       (SF3). A deliberate decision is not a finding; it is an
       implementation of that decision.
     severity: critical

package/bundle/skills/agentera/capabilities/build/schemas/artifacts.yaml

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Build consumes this through CLI execution_context caveats or explicit
@@ -9,7 +9,7 @@ ARTIFACTS:
       during vision bootstrap.
   2:
     id: A2
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Build consumes TODO state from execution_context and included status state
@@ -17,7 +17,7 @@ ARTIFACTS:
       entries. Severity classified per protocol SI1-SI4.
   3:
     id: A3
-    artifact_id: changelog
+    artifact: changelog
     local_role: produces_and_consumes
     description: >-
       Build consumes changelog boundary from execution_context or the listed
@@ -25,27 +25,27 @@ ARTIFACTS:
       [Unreleased] based on commit type and promotes on version bumps.
   4:
     id: A4
-    artifact_id: progress
+    artifact: progress
     local_role: produces_and_consumes
     description: >-
       Operational cycle log. Build consumes latest progress evidence from
       execution_context first, then bounded `agentera state progress list --limit
-      20 --format json` discovery or exact `state progress get --number N`
+       20 --format json` discovery or exact `state progress get --id ID`
       retrieval, and appends one entry per cycle with mandatory Verified field.
       Compacted by applying schema COMPACTION rules.
   5:
     id: A5
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Build consumes health state from execution_context and included status
       state before bounded `agentera state health list --limit 20 --format json`
-      discovery or exact `state health get --number N` retrieval, focusing on
+       discovery or exact `state health get --id ID` retrieval, focusing on
       critical and degraded findings for work selection. Raw reads are
       diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Build consumes decision caveats and bounded list/get fallback commands from
@@ -54,7 +54,7 @@ ARTIFACTS:
       diagnostic-only for corruption or CLI-defect investigation.
   7:
     id: A7
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
       Build consumes selected task, acceptance criteria, dependencies,
@@ -62,7 +62,7 @@ ARTIFACTS:
       direct plan reads, then updates task status and surprises during execution.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Build consumes status profile summary first. Missing or stale profile state
@@ -70,14 +70,14 @@ ARTIFACTS:
       during normal startup.
   9:
     id: A9
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Build consumes artifact mappings and docs caveats from execution_context
       and included status docs state before direct docs reads.
   10:
     id: A10
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Build treats design state missing from execution_context as a caveat or

package/bundle/skills/agentera/capabilities/build/schemas/validation.yaml

@@ -3,7 +3,7 @@ VALIDATION:
     id: V1
     rule: verified_field_mandatory
     description: >-
-      Every progress.yaml cycle entry MUST have a verified field. The field
+      Every progress entity record MUST have a verified field. The field
       carries either observed output from the primary entrypoint, an allowlisted
       N/A tag, or a free-form rationale of at least 8 words.
     severity: critical
@@ -19,7 +19,7 @@ VALIDATION:
       an explicit user request.
     severity: critical
     checks:
-      - "Only one cycle entry appended to PROGRESS.md per invocation"
+      - "Only one progress entity is appended per invocation"
   3:
     id: V3
     rule: no_remote_push
@@ -43,7 +43,7 @@ VALIDATION:
     id: V5
     rule: consecutive_failure_guard
     description: >-
-      If the last 3 progress.yaml entries all record failed cycles, build
+      If the last 3 bounded progress records all report failed cycles, build
       MUST stop and surface the pattern to the user. Do not attempt a 4th
       consecutive cycle on the same failing problem.
     severity: critical
@@ -53,13 +53,13 @@ VALIDATION:
     id: V6
     rule: artifact_path_resolution
     description: >-
-      Before reading or writing any artifact, check .agentera/docs.yaml for path
-      overrides. If absent, use the default layout (TODO.md, CHANGELOG.md,
-      and DESIGN.md at root; canonical VISION.md at .agentera/vision.yaml;
-      other agent-facing artifacts as YAML in .agentera/).
+      Entity state MUST use exact/list CLI reads and typed writers discovered by
+      `agentera state <artifact> explain`. Check .agentera/docs.yaml only for
+      intentional singleton path overrides.
     severity: warning
     checks:
-      - "docs.yaml checked before artifact access"
+      - "Entity files are not read or edited directly"
+      - "docs.yaml checked before singleton artifact access"
   7:
     id: V7
     rule: execution_context_first

package/bundle/skills/agentera/capabilities/design/schemas/artifacts.yaml

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: design
+    artifact: design
     local_role: produces_and_consumes
     description: >-
       Visual identity system with design tokens, typography, colors,
@@ -9,35 +9,35 @@ ARTIFACTS:
       reads agent-readable YAML token blocks with HTML comment markers.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Design reads the Identity section to propose visual tokens
       coherent with the declared verbal personality.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Design reads this during refine mode to identify UI work and
       inline design decisions since the design system was written.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Design reads this to check for design-related issues and files
       code drift findings here during audit mode.
   5:
     id: A5
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Design reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   6:
     id: A6
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Design reads aesthetic preferences from the profile as defaults

package/bundle/skills/agentera/capabilities/discuss/schemas/artifacts.yaml

@@ -1,12 +1,12 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: decisions
+    artifact: decisions
     local_role: produces_and_consumes
     description: >-
       Reasoning trail with confidence labels. Discuss reads existing decisions
       through bounded `agentera state decisions list --limit 20 --format json`
-      discovery plus exact `agentera state decisions get --number N --format json`
+       discovery plus exact `agentera state decisions get --id ID --format json`
       retrieval and its source_contract to avoid re-deliberation, and writes new decision entries with confidence
       (DL1 firm, DL2 provisional, DL3 exploratory). Compact older entries by
       applying schema COMPACTION rules; incomplete compacted entries are
@@ -14,7 +14,7 @@ ARTIFACTS:
       normal deliberation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Discuss may update project direction only with explicit user
@@ -22,28 +22,28 @@ ARTIFACTS:
       context during deliberation.
   3:
     id: A3
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Discuss may add tech debt items surfaced during deliberation only with
       explicit user confirmation. Severity per protocol SI1-SI4.
   4:
     id: A4
-    artifact_id: objective
+    artifact: objective
     local_role: produces_and_consumes
     description: >-
       Discuss may write optimization decisions only with explicit user
       confirmation when a decision feeds into what to optimize.
   5:
     id: A5
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Discuss reads this at session start to acknowledge high-confidence
       entries and avoid re-deliberating settled ground.
   6:
     id: A6
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Discuss reads this first to resolve project-local artifact mappings.

package/bundle/skills/agentera/capabilities/document/schemas/artifacts.yaml

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: docs
+    artifact: docs
     local_role: produces_and_consumes
     description: >-
       Documentation contract with conventions, artifact mapping, and
@@ -12,44 +12,44 @@ ARTIFACTS:
       raw reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Document reads this to understand who the documentation is for
       and what tone to use.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode to understand
       recent project context. During closeout, latest progress evidence and
       verification pointers are consumed through CLI `closeout_context`, then
       bounded `agentera state progress list --limit 20 --format json` discovery
-      or exact `state progress get --number N` retrieval. Raw reads are
+       or exact `state progress get --id ID` retrieval. Raw reads are
       diagnostic-only for corruption or CLI-defect investigation.
   4:
     id: A4
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
       Document reads this during explore-and-generate mode for project
       context and decision awareness through bounded `agentera state decisions
       list --limit 20 --format json` discovery or exact `state decisions get
-      --number N` retrieval. Raw reads are diagnostic-only for corruption or
+       --id ID` retrieval. Raw reads are diagnostic-only for corruption or
       CLI-defect investigation.
   5:
     id: A5
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Document reads this to discover documentation gaps surfaced during health
       audits through bounded `agentera state health list --limit 20 --format
-      json` discovery or exact `state health get --number N` retrieval. Raw reads
+       json` discovery or exact `state health get --id ID` retrieval. Raw reads
       are diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Document writes to this when code diverges from docs (per DTC,
@@ -58,21 +58,21 @@ ARTIFACTS:
       any diagnostic-only raw TODO read.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Document reads this to respect the declared aesthetic and voice
       when generating user-facing documentation.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Document reads this to calibrate documentation style preferences:
       detail level, tone, format.
   9:
     id: A9
-    artifact_id: changelog
+    artifact: changelog
     local_role: consumes
     description: >-
       Document reads this during closeout synchronization through CLI