agentera 3.0.0-dev.22 → 3.0.0-dev.25

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-index.yaml

@@ -41,9 +41,9 @@ normalization_rules:
   - rule: The CLI source and rendered dashboard are different.
     use: agentera prime source data, status dashboard rendered briefing
     avoid: Treating raw CLI labels as the user-facing dashboard.
-  - rule: Routine state uses flat commands.
-    use: agentera plan, agentera docs, agentera health
-    avoid: agentera query plan for routine state.
+  - rule: Routine state uses the state namespace.
+    use: agentera state plan, agentera state docs, agentera state health
+    avoid: agentera plan, agentera docs, or agentera health as routine state commands.
   - rule: query is advanced access.
     use: agentera query --list-artifacts, agentera query <artifact>
     avoid: Calling it the normal state interface.

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.                                                                                                                                                                                                                    |
@@ -99,11 +99,11 @@ enforcement boundary promoted to `true` in D65.
 
 Use this prose as guidance only: the default is that the first capability
 invocation shells out to `agentera prime --context <name> --format json` and
-reads the returned `prose` field. Today, capability directories carry the
-`schemas/` files only, the prose module lives at
+reads the returned `instructions` field. Today, capability directories carry
+the `schemas/` files only, the instructions module lives at
 `packages/cli/src/capabilities/<name>/instructions.ts`, runtime descriptors
 invoke the prime command, and the `agentera prime --context <name> --format
-json` response emits `capability_context.prose` plus
+json` response emits `capability_context.instructions` plus
 `first_invocation_read` metadata.
 
 Do not replace this with a parallel Markdown table of read modes or migration
@@ -112,6 +112,13 @@ human-facing boundary. The `prime_context` runtime enforcement is owned by the
 CLI process; agent runtimes shell out to the prime command instead of reading
 the prose module directly.
 
+Status startup is the one-call exception to the general compact-data wording
+above: `agentera prime --context status --format json` returns
+`capability_context.instructions` and bounded
+`capability_context.context.status_context` together. Consumers do not make a
+second bare-prime call or read raw artifacts; omitted detail names its
+authoritative recovery command.
+
 ## Invocation and routing grammar
 
 | Term                         | Definition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -208,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
@@ -65,10 +79,10 @@ The CLI routes. The host agent follows.
 
 | Request shape | Route |
 |---|---|
-| Bare `/agentera` | 1. Run `agentera prime --format json` for state data. 2. Run the `fetch_command` from `source_contract.capability_context` to get rendering instructions. 3. Follow `capability_context.instructions` for dashboard template, field rules, and exit marker. 4. Render the dashboard from the state data per the instructions. 5. Follow `next_action` to suggest the next capability. |
+| Bare `/agentera` | 1. Run `agentera prime --context status --format json` once. 2. Read `capability_context.instructions` and `capability_context.context.status_context`. 3. Render the dashboard from that bounded state and follow `next_action` to suggest the next capability. |
 | `/agentera <capability-name>` | Run `agentera prime --context <capability> --format json`. Follow the capability's instructions and contract. |
 | `/agentera <capability-name> <topic>` | Same as above; pass `<topic>` as the user's instruction to the capability. |
-| Natural language | Run `agentera prime --format json`. Run the `fetch_command` from `source_contract.capability_context` for rendering instructions. Use `next_action.capability` to suggest the matching capability. If no high-confidence match, present a disambiguation prompt. |
+| Natural language | Run `agentera prime --context status --format json` once. Read `capability_context.instructions` and `capability_context.context.status_context`; use `next_action.capability` to suggest the matching capability. If no high-confidence match, present a disambiguation prompt. |
 
 Capability names are the routing identity: `status`, `vision`, `discuss`,
 `research`, `plan`, `build`, `optimize`, `audit`, `document`, `profile`,
@@ -98,10 +112,11 @@ Capability handoffs use glyph plus canonical name (e.g. `⧉ build`, `≡ plan`)
 
 The prime dashboard rendering contract — template, field-by-field rules, output
 budget, attention-item ordering, exit marker — is owned by the status capability
-instructions. Bare `agentera prime --format json` returns a pointer at
-`source_contract.capability_context` with a `fetch_command` to retrieve them;
-run it, then follow `capability_context.instructions` for layout,
-inclusion/exclusion rules, and the mandatory `⌂ status · <status>` exit marker.
+instructions. `agentera prime --context status --format json` returns the full
+`capability_context.instructions` body and the bounded
+`capability_context.context.status_context` state in one response. Render from
+that capsule without a separate bare-prime call or raw artifact read; use the
+named recovery command when the capsule marks detail as omitted.
 Ask for confirmation before invoking a state-changing downstream capability.
 
 The first response in a fresh interaction delivers the brief and a free-form
@@ -144,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:
 
@@ -167,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`
 
@@ -183,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/agents/audit.toml

@@ -2,5 +2,5 @@
 name = "audit"
 description = "Codebase health audit."
 developer_instructions = """
-You are the Agentera audit capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context audit --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera audit capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context audit --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/build.toml

@@ -2,5 +2,5 @@
 name = "build"
 description = "Autonomous development execution."
 developer_instructions = """
-You are the Agentera build capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context build --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera build capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context build --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/design.toml

@@ -2,5 +2,5 @@
 name = "design"
 description = "Visual identity and design systems."
 developer_instructions = """
-You are the Agentera design capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context design --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera design capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context design --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/discuss.toml

@@ -2,5 +2,5 @@
 name = "discuss"
 description = "Structured deliberation and decision support."
 developer_instructions = """
-You are the Agentera discuss capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context discuss --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera discuss capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context discuss --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/document.toml

@@ -2,5 +2,5 @@
 name = "document"
 description = "Documentation updates and synchronization."
 developer_instructions = """
-You are the Agentera document capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context document --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera document capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context document --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/optimize.toml

@@ -2,5 +2,5 @@
 name = "optimize"
 description = "Metric-driven optimization cycles."
 developer_instructions = """
-You are the Agentera optimize capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context optimize --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera optimize capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context optimize --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/orchestrate.toml

@@ -2,5 +2,5 @@
 name = "orchestrate"
 description = "Multi-cycle orchestration over active plans."
 developer_instructions = """
-You are the Agentera orchestrate capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context orchestrate --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera orchestrate capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context orchestrate --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/plan.toml

@@ -2,5 +2,5 @@
 name = "plan"
 description = "Planning with acceptance criteria."
 developer_instructions = """
-You are the Agentera plan capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context plan --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera plan capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context plan --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/profile.toml

@@ -2,5 +2,5 @@
 name = "profile"
 description = "Decision profiling and preference memory."
 developer_instructions = """
-You are the Agentera profile capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context profile --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera profile capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context profile --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/research.toml

@@ -2,5 +2,5 @@
 name = "research"
 description = "External pattern research and synthesis."
 developer_instructions = """
-You are the Agentera research capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context research --format json` to fetch the authoritative instructions as a JSON capsule (the `instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera research capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context research --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/status.toml

@@ -2,5 +2,5 @@
 name = "status"
 description = "Agentera orientation and routing dashboard."
 developer_instructions = """
-You are the Agentera status capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context status --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera status capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context status --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/vision.toml

@@ -2,5 +2,5 @@
 name = "vision"
 description = "Define and refine project direction."
 developer_instructions = """
-You are the Agentera vision capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context vision --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera vision capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context vision --format json` to fetch the authoritative instructions as a JSON capsule (the `capability_context.instructions` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

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