agentera 3.0.0-dev.23 → 3.0.0-dev.26

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.                                                                                                                                                                                                                    |
@@ -51,11 +51,11 @@ examples. Diagnostics should state object, state, cause, and fix.
 
 | Term                       | Definition                                                                                                                                                                                                                                                                          | Common sources                                                                   |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| Agentera                   | The agent. One persistent identity that thinks through every step and keeps working when you walk away — the colleague, not the team. The CLI is the brain and spine: it owns routing, memory, capability prose, and the worker-spec contract. Active host coding agents (OpenCode, Codex, Cursor, Copilot) are harnesses that provide the model and tool runtime; Agentera provides the identity, memory, discipline, and routing. Identity is per-project: same personality, same capabilities, different memory, no bleed. Headline: one agent, one CLI, many capabilities. | `README.md`, `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
-| Host runtime (harness)      | An active host coding agent — OpenCode, Codex, Cursor, or Copilot — that provides the model, the tool runtime, and the spawn capacity. Agentera is the agent; the host is the harness. The host learns one contract: the JSON the CLI returns from `agentera prime`. Editor runtime installs are transport (the `skills/` directory, `plugin.json`), not an extension surface. | `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
-| Product surface            | Where the same fixed Agentera workflow ships: `@agentera/cli` (the agent runtime and narrow waist — owns routing, memory, capability prose, and the worker-spec contract), `@agentera/mobile` (primary app, a client of the CLI), `@agentera/web` (site and docs), and active host runtimes (OpenCode, Codex, Cursor, Copilot). Host runtimes are harnesses — clients of the CLI, not extension hosts or peers. | `README.md`, `AGENTS.md`, `packages/*/README.md`, `.agentera/decisions.yaml` (D74) |
+| Agentera                   | The agent. One persistent identity that thinks through every step and keeps working when you walk away — the colleague, not the team. The CLI is the brain and spine: it owns routing, memory, capability prose, and the worker-spec contract. Coding hosts consume the same shared skill and CLI contract; Agentera does not ship host-native package surfaces. Identity is per-project: same personality, same capabilities, different memory, no bleed. Headline: one agent, one CLI, many capabilities. | `README.md`, `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
+| Host runtime (harness)      | A coding agent host that provides the model, tools, and worker execution. Agentera is the agent; the host is the harness. Hosts consume the shared skill at `~/.agents/skills/agentera` and the JSON returned by `agentera prime`; Agentera does not install or repair host-native plugins, hooks, agents, or packages. | `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
+| Product surface            | Where the fixed Agentera workflow ships: `@agentera/cli` (the agent runtime and narrow waist), `@agentera/mobile` (a client of the CLI), and `@agentera/web` (site and docs). Coding hosts consume the shared skill and CLI rather than receiving native Agentera package surfaces. | `README.md`, `AGENTS.md`, `packages/*/README.md`, `.agentera/decisions.yaml` (D74) |
 | @agentera/mobile           | The flagship mobile/web app package at `packages/mobile`. SvelteKit, Cursor SDK, Cloudflare Worker.                                                                                                                                                                                 | `packages/mobile/README.md`, `packages/mobile/DESIGN.md`                         |
-| Agentera skill             | Internal transport, not a product word. The bundle at `skills/agentera/` packages Agentera's routing entry and capability prose for host editor runtimes — the `skills/` directory and `plugin.json` manifests host editors require. It is the same fixed workflow, not user extensibility. Per Decision 74, "skill" is retired from product vocabulary and survives only as internal transport; the product word is capabilities. | `skills/agentera/SKILL.md`, `README.md` Internals, `.agentera/decisions.yaml` (D74) |
+| Agentera skill             | Shared transport, not a product extension point. The source at `skills/agentera/` is installed once at `~/.agents/skills/agentera` and packages Agentera's routing entry and capability prose without host-native manifests. It is the same fixed workflow, not user extensibility. Per Decision 74, the product word is capabilities. | `skills/agentera/SKILL.md`, `README.md` Internals, `.agentera/decisions.yaml` (D74) |
 | Capability                 | A routed behavioral unit of the single Agentera agent, driven through the CLI. Eleven top-level capabilities (status, vision, discuss, research, plan, build, optimize, audit, document, design, orchestrate) plus profile, which surfaces through existing capabilities but appears as a peer row in user-facing docs. Each capability has a prose module at `packages/cli/src/capabilities/<name>/instructions.ts` plus `triggers.yaml`, `artifacts.yaml`, `validation.yaml`, and `exit.yaml`. English names are canonical per Decision 70; the Swedish `-era` names are legacy v2 stable only (see Legacy Swedish capability names). | `AGENTS.md`, `skills/agentera/capabilities/*`, `packages/cli/src/capabilities/*`, `.agentera/decisions.yaml` (D70, D74) |
 | Capability canonical name (v3) | The English name binding for v3+ capability invocation, per Decision 70, under the single-agent identity crystallized in Decision 74. Promoted from the Decision 43 alias set. Mobile UX, web docs, host runtimes, and the CLI all use the same English name; the v2 stable distribution uses the legacy Swedish `-era` IDs (see `Legacy Swedish capability names`). | `.agentera/decisions.yaml` (D43, D70, D74), `references/cli/vocabulary-index.yaml` (protected_surfaces) |
 | Legacy Swedish capability names (v2 stable) | The historical Swedish `-era` IDs (e.g. `hej`, `resonera`) used by the v2 stable distribution (`npx -y agentera@latest`) and preserved as historical references in archived plans, decisions, and changelogs. Out of scope for v3 surface per Decisions 70 and 74; the single-agent identity uses English capability names exclusively. Coexistence probe surfaces per-distribution naming divergence. | `.agentera/decisions.yaml` (D70, D74), `references/cli/vocabulary-index.yaml` (protected_surfaces) |
@@ -142,14 +142,14 @@ authoritative recovery command.
 | Suggest, don't force         | Status recommends the next capability but waits for user confirmation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Capability handoff label     | A recommendation from one capability to another. Use glyph plus canonical name, such as `⧉ build` or `≡ plan`, not standalone slash-capability names. SG priority codes are internal protocol references and are not user-facing handoff labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Explicit route documentation | User-facing examples that teach the actual entry route. Use `/agentera <alias>` such as `/agentera build`; do not present aliases as CLI commands.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Runtime question tool        | Host-native bounded-choice prompt. Concrete tool availability belongs to the active host runtime, not this vocabulary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| Question-tool gating         | Use a native question tool only for at least two meaningful non-terminal next actions or consequential Proceed/Cancel; `Done` and custom/free-form answers do not count as alternatives. Initial Agentera/status briefs stay free-form unless bounded choices were requested or the suggested next step is a state-changing Proceed/Cancel handoff. A single non-mutating suggested handoff may use a free-form prompt, but a single state-changing handoff uses native Proceed/Cancel confirmation. State-changing means the proposed next step may write artifacts, edit code, run optimization or orchestration cycles, apply migrations, refresh app/runtime state, or otherwise mutate project/runtime state. Apply the behavior rule first, with examples such as ⧉ build, ≡ plan when creating or updating plans, ▤ document when writing docs, ⎘ optimize when running or applying optimization cycles, and ⎈ orchestrate when dispatching cycles. This dispatcher rule governs status and capability handoff prompts; invoked capability prose can impose stricter question-tool requirements. |
+| Bounded-choice prompt        | A question surface supplied by the coding host. Agentera may use one when available but does not install, configure, or advertise a host-specific prompt integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Question gating              | Use bounded choices only for at least two meaningful non-terminal next actions or consequential Proceed/Cancel; `Done` and custom/free-form answers do not count as alternatives. Initial Agentera/status briefs stay free-form unless bounded choices were requested or the suggested next step is a state-changing Proceed/Cancel handoff. A single non-mutating suggested handoff may use a free-form prompt, but a single state-changing handoff uses Proceed/Cancel confirmation. State-changing means the proposed next step may write artifacts, edit code, run optimization or orchestration cycles, apply migrations, or otherwise mutate project state. Apply the behavior rule first; invoked capability prose can impose stricter requirements. |
 | Handoff confirmation         | Clear free-form acceptance of the named single suggestion confirms invocation. Selecting a downstream capability option in a bounded prompt also confirms invocation; selecting `Done` stops without routing. Ambiguous replies get one clarifying question.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Route                        | Direct user invocation by canonical capability name, primary alias, or slash route. A route is already consent to invoke the capability and does not need an extra handoff confirmation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Suggest                      | Recommend a downstream capability and wait for confirmation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Delegate                     | Orchestrate assigns approved plan work to a worker capability during an explicitly orchestrated flow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Spawn                        | Build or Optimize launches an isolated runtime worker through the host subagent mechanism.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Subagent mechanism           | Runtime support for worker execution through OpenCode, Codex CLI, Cursor IDE, Copilot CLI, or another active host-native worker surface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Spawn                        | Build or Optimize asks the coding host to launch an isolated worker when the host provides that facility.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Worker mechanism             | A host-provided worker facility. Agentera ships no host-specific worker descriptor, adapter, plugin, hook, or package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Legacy bridge                | Temporary v1 entry points, especially `/hej`, that guide users to `/agentera` and the v2 upgrade path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 CLI-visible `agentera prime` labels are source labels. Preserve them in CLI tests
@@ -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`.                                                                                                                                                                                                                                          |
@@ -368,18 +368,14 @@ not add precision:
 | Missing normal directory     | Previewable. Agentera can show a no-write repair preview.                                                                                                                                                                                                      |
 | Missing chosen directory     | Needs a user decision when provided through `AGENTERA_HOME` or explicit `--install-root`.                                                                                                                                                                      |
 | Package refresh              | Package-manager or marketplace update. It does not prove Agentera's app files are current.                                                                                                                                                                     |
-| App repair                   | Normal repair flow that previews or applies Agentera app files plus managed runtime config, plugins, hooks, commands, and safe cleanup together. It must not edit shell startup files, and package-manager commands remain opt-in through `--update-packages`. |
-| `--only bundle`              | Compatibility selector for narrow app-file work. Do not present it as the normal repair recommendation when managed runtime surfaces may also need repair.                                                                                                     |
+| App repair                   | Normal flow that previews or applies Agentera app/project work. It does not install, update, authenticate, enable, trust, or repair host-native resources.                                                                                                     |
 | Preview                      | No-write mode. Required before upgrade or app repair writes; the underlying command flag is `--dry-run`.                                                                                                                                                       |
 | `--yes`                      | Explicit apply flag after preview and approval.                                                                                                                                                                                                                |
-| Final check                  | Setup validation after upgrade apply. Uses the same app-home probe as `agentera doctor` (`build_doctor_status`), not `setup_doctor.build_report`.                                                                                                              |
-| Package-update opt-in        | External package manager changes require `--update-packages`.                                                                                                                                                                                                  |
-| Runtime adapter              | Runtime-specific Agentera adapter support for skill loading, hooks, artifact validation, lifecycle metadata, and diagnostics.                                                                                                                                  |
+| Final check                  | Validation after upgrade apply using the same app/project evidence reported by `agentera doctor`.                                                                                                                                                              |
 | Host support                 | What a runtime can theoretically do. Distinguish it from shipped Agentera behavior.                                                                                                                                                                            |
-| Hook lifecycle               | Runtime callbacks such as `SessionStart`, `Stop`, `PreToolUse`, and `PostToolUse`.                                                                                                                                                                             |
-| Setup doctor                 | Diagnostic command surface for install/runtime health.                                                                                                                                                                                                         |
+| Retired native integration vocabulary | Runtime selectors, adapter repair, plugin-shipped hooks, setup-doctor runtime health, and package-update flags describe released history or migration evidence only. They are not current Agentera features.                                                                                                            |
 
-Canonical active runtime names are OpenCode, Codex, Cursor, and GitHub Copilot. Cursor Agent CLI and Cursor IDE are surfaces of the single Cursor identity; `cursor-agent` is an inactive Cursor alias and source-product name. Claude Code is a retired migration and consent-gated historical-import source, not an active runtime.
+Claude Code is a retired migration and consent-gated historical-import source, not an active runtime. Current coding hosts consume the shared skill and CLI without entering an Agentera runtime inventory.
 
 ### App lifecycle status vocabulary
 
@@ -452,12 +448,11 @@ identifiers, package metadata, historical records, fixtures, path-like
 references, generic plain language, and ambiguous current prose.
 
 Use this prose as guidance only: current conceptual docs should say the object
-they mean, such as Agentera app files, suite package, plugin-shipped hooks,
-removed `bundle-status` command, Agentera routing entry point, skill entry file,
-historical v1 skill entry paths (post-3.0 removed from the repo tree). Preserve shipped identifiers and
-literal paths such as `.agentera-bundle.json`, `bundle.status`,
-`activeBundleRoot`, `--only bundle`, and `skills/agentera/SKILL.md` unless an
-explicit compatibility migration is in scope.
+they mean, such as Agentera app files, suite package, Agentera routing entry
+point, or skill entry file. Plugin-shipped hooks and `--only bundle` are retired
+v2 vocabulary and may appear only in released history, fixtures, or explicit
+migration evidence. Literal current paths such as `skills/agentera/SKILL.md`
+remain valid.
 
 Do not replace this with a parallel Markdown table of allowed and forbidden
 terms. Update the YAML authority first, then keep this section as the short
@@ -530,7 +525,7 @@ schema concept, runtime capability, install state, or user action.
 | Ambiguous term  | Why bare usage is risky                                                                                | Required wording                                                                                                                                                                     |
 | --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Skill           | Confuses v1 standalone skills, the host editor skill bundle, and internal workflows.                  | Per Decision 74, `skill` is internal transport, not product vocabulary. Use `capability` for Agentera workflows; reserve `skill` for the `skills/` directory and host editor manifests; `v1 skill` for history.       |
-| Contract        | Could mean schema structure, artifact shape, protocol primitive, adapter behavior, or product promise. | Use `schema contract`, `artifact schema`, `protocol primitives`, `runtime adapter contract`, or `product promise`.                                                                   |
+| Contract        | Could mean schema structure, artifact shape, protocol primitive, package behavior, or product promise. | Use `schema contract`, `artifact schema`, `protocol primitives`, `package contract`, or `product promise`.                                                                           |
 | Status          | Different surfaces use different state machines and output labels.                                     | Use `exit status`, `task status`, `installed-app status`, `install status`, `docs status`, or `health status`.                                                                       |
 | Freshness       | Sounds like a branded synonym for several normal states: current, stale, synced, or out of date.       | Use object-specific state wording such as `artifact is current`, `Agentera app files need repair`, `docs are current`, or `plan-level current-state check`.                          |
 | Checkpoint      | In software, can mean commit, savepoint, restore point, model checkpoint, or milestone.                | Use `final state sync`, `plan-level current-state check`, `checkpoint commit`, or `pre-dispatch checkpoint commit`.                                                                  |

package/bundle/references/meta/documentation-inventory.md

@@ -10,7 +10,7 @@ guides — not under `docs/`.
 
 | Path | Topic |
 | ---- | ----- |
-| `docs/packaging/v3-packaging.md` | v3 CLI npm/Bun distribution contract |
+| `docs/packaging/v3-packaging.md` | v3 CLI npm distribution and verification-lane contract |
 | `docs/consolidation/monorepo-plan.md` | Product pivot, `@agentera/*` package layout, migration checklist (D67) |
 
 ## Authority stack

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.