agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/bundle/references/cli/vocabulary.md

@@ -16,14 +16,12 @@ 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.                                                                                                                                                                                                                    |
 | `references/cli/capability-instruction-contract.yaml`              | Decision 57 capability instruction-file contract, current `packages/cli/src/capabilities/<name>/instructions.ts` authority, and implemented `first_invocation_read` CLI/schema discoverability (D65 collapsed the legacy `full`/`compact_startup` distinction into a single `prime_context` value with runtime enforcement). |
-| `references/cli/routing-execution-vocabulary.yaml`                 | Canonical concepts, compatibility boundaries, and classification rules for routing, suggestions, delegation, worker spawning, runtime subagent mechanisms, and pre-spawn Git commits.                                                                                                                                        |
 | `skills/agentera/SKILL.md`                                         | Agentera routing entry point, routing model, CLI-first state access, installed-app status checks, and safety rails.                                                                                                                                                                                                          |
-| `packages/cli/src/capabilities/*/instructions.ts`                  | Capability behavior, workflow grammar, step markers, and cross-capability boundaries. Loaded as a default-exported string constant and served via `agentera prime --context <name> --format json`.                                                                                                                           |
+| `packages/cli/src/capabilities/*/instructions.ts`                  | Capability behavior, workflow grammar, step markers, and cross-capability boundaries. Loaded as a default-exported string constant and served pre-cutover via `npx -y agentera@next prime --context <name> --format json`.                                                                                                                           |
 | `the agentera CLI` and `packages/cli/src/upgrade (doctor/upgrade)` | CLI-visible command labels, upgrade output, and doctor diagnostics.                                                                                                                                                                                                                                                          |
 | `README.md`, `UPGRADE.md`, `DESIGN.md`, `.agentera/*.yaml`         | User-facing phrasing, design vocabulary, and current project-state examples.                                                                                                                                                                                                                                                 |
 
@@ -51,14 +49,13 @@ 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. Host coding agents (Claude, Cursor, Codex, Copilot, OpenCode) 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)      | A host coding agent — Claude, Cursor, Codex, Copilot, or OpenCode — 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 host runtimes (Claude, Cursor, Codex, Copilot, OpenCode). 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/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                   | 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 pre-cutover by `npx -y agentera@next 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            | The fixed Agentera workflow ships through the `agentera` package and CLI. Coding hosts consume the shared skill and CLI rather than receiving native Agentera package surfaces. | `README.md`, `AGENTS.md`, `packages/cli/README.md`, `.agentera/decisions.yaml` |
+| 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) |
+| 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. Host runtimes and the CLI 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 npm distribution 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) |
 | Shared protocol            | Internal primitive vocabulary in `protocol.yaml`: confidence, severity, decision labels, exits, visual tokens, glyphs, and phases.                                                                                                                                                  | `skills/agentera/protocol.yaml`                                                  |
 | Capability schema contract | The executable contract for capability schema groups, stable IDs, priorities, deprecations, and primitive references.                                                                                                                                                               | `skills/agentera/capability_schema_contract.yaml`                                |
 | Project state              | Structured files that preserve intent, decisions, plans, progress, health, docs, design, and session continuity.                                                                                                                                                                    | `README.md`, `.agentera/docs.yaml`                                               |
@@ -98,12 +95,12 @@ implemented `first_invocation_read: prime_context` value, the
 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
-`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
+invocation shells out to `npx -y agentera@next prime --context <name> --format json` and
+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`, and the
+`npx -y agentera@next prime --context <name> --format 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,12 +109,20 @@ 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: `npx -y agentera@next prime --context status --format json` returns
+`capability_context.instructions` and bounded
+`capability_context.context.status_context` together with the one
+`capability_context.startup` availability projection. 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | CLI-first state access       | Read project state through `agentera` top-level commands before raw artifact reads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Top-level state commands     | The canonical namespace command is `state` followed by a subcommand (`plan`, `progress`, `health`, `todo`, `decisions`, `docs`, `objective`, `experiments`, `query`). Legacy top-level aliases remain during migration; see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Top-level state commands     | The canonical namespace command is `state` followed by a subcommand (`plan`, `progress`, `health`, `todo`, `decisions`, `docs`, `objective`, `experiments`, `query`). Legacy top-level aliases remain during migration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Artifact-backed briefing     | Any briefing or routing decision backed by Agentera project artifacts. It must use CLI-first state access.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Bare `/agentera`             | Invocation without a specific request. It delegates to `status` and renders the status dashboard from one composite source command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Status dashboard                | User-facing project briefing with logo, status metrics, a narrative read inside `status`, attention, next action, and `⌂ status · <status>`. Issues summary uses `critical · degraded · annoying` only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -125,25 +130,23 @@ the prose module directly.
 | Direct route                 | A canonical capability name with optional following topic text, `/agentera <capability-name>` with optional topic text, or `/agentera <primary-alias>` routes directly to that capability and bypasses natural-language matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | Canonical capability route   | An English capability name such as `discuss`, `plan`, or `orchestrate`, optionally followed by topic text, plus the slash form `/agentera <capability-name>` with optional topic text. Canonical names remain protocol identity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | Primary route alias          | The one plain `/agentera <alias>` direct route for a capability, owned by `ROUTE_ALIASES.primary_aliases`. Each canonical capability has exactly one primary alias.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Secondary request wording    | Natural-language phrases in capability trigger schemas, such as `deliberate`, `brainstorm`, `rubber duck`, `brief`, and `what's next`. They route through trigger matching and are not primary aliases.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Natural-language trigger     | A phrase in `schemas/triggers.yaml` that maps a request to a capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Trigger priority             | `high`, `medium`, or `low`; owned by the schema contract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| High-confidence match        | A natural-language request with enough trigger evidence to route without asking.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Borderline match             | A request with competing plausible routes. Agentera asks for disambiguation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Fallback to status             | No sufficient match routes to status for orientation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Secondary request wording    | LLM-readable intent descriptions in capability trigger entries. They describe secondary wording and are not primary aliases.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Natural-language trigger     | A trigger entry in `schemas/triggers.yaml` whose description and collision hints a host reads only after deterministic routing returns `semantic_required`. The host's semantic judgment must be submitted as a receipt the CLI validates before startup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Trigger priority             | `high`, `medium`, or `low`; an advisory relevance-precedence hint owned by the schema contract, not a score.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Genuine consequential ambiguity | Two materially plausible capabilities without enough intent to choose responsibly. Ask one clarification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Fallback to status           | Route to status for orientation only when no capability fits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Concrete next action         | A route suggestion tied to an object such as `PLAN Task N`, `TODO`, `OBJECTIVE`, or `VISION refresh`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | 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. Current examples: Claude Code `AskUserQuestion`, Copilot `ask_user`, Codex `request_user_input`, and OpenCode `question`. These are guidance examples, not schema authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| 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 Claude Code, OpenCode, Codex CLI, Copilot CLI, Cursor IDE, or another host-native worker surface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Legacy bridge                | Temporary v1 entry points, especially `/hej`, that guide users to `/agentera` and the v2 upgrade path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 CLI-visible `agentera prime` labels are source labels. Preserve them in CLI tests
 and parsing code, but transform them before presenting a user dashboard:
@@ -169,36 +172,16 @@ Primary route aliases are slash-route vocabulary, not CLI command vocabulary:
 
 Do not teach primary aliases as CLI state commands. v3 orientation is
 `agentera prime` (capability ID `status` via `prime --context status`); routine
-state reads use `agentera state plan`, `state progress`, `state health`,
-`state todo`, `state decisions`, `state docs`, `state objective`,
-`state experiments`, and advanced `state query`. The v2 stable distribution
+record reads use `npx -y agentera@next state plan list`, `state progress list`,
+`state health list`, `state todo list`, `state decisions list`, `state docs list`,
+`state objective list`, objective-scoped `state experiments list`, exact
+`get --id ID`, and advanced `state query`. The v2 stable distribution
 retains `hej` and the rest of the Swedish capability surface per Decision 70.
 
 When capability prose recommends another capability, use the handoff label
 grammar (`<glyph> <capability>`). Keep slash forms only when documenting the
 entry route (`/agentera <alias>`) or preserving clearly historical evidence.
 
-### Routing and execution vocabulary
-
-The machine-readable authority is
-`references/cli/routing-execution-vocabulary.yaml`; it owns classification of
-routing and execution terms into canonical concepts, compatibility identifiers,
-code identifiers, historical records, fixtures, path-like references, generic
-plain language, and ambiguous current prose.
-
-Use this prose as guidance only: request-to-capability routing uses `Agentera router`
-or routing language, next-action recommendations `suggest`, Orkestrera
-task assignment `delegate`, Realisera/Optimera worker launch `spawn`, runtime
-support `subagent mechanism`, and worker safety `pre-spawn Git commit`.
-Preserve shipped identifiers and concrete code/path evidence such as
-`subagent_dispatch`, historical `pre-dispatch commit` records, fixture names,
-and archived plans unless an explicit compatibility migration is in scope.
-
-Do not replace this with a parallel Markdown table of preferred and forbidden
-terms. Update the YAML authority first, then keep this section as the short
-human-facing boundary. The broader current-prose replacement and repository-wide
-ambiguous-term sweep remain separate follow-up work.
-
 ## Artifact grammar
 
 | Term                    | Definition                                                                                                                                                                                                                                                                                                                           |
@@ -208,11 +191,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`.                                                                                                                                                                                                                                          |
@@ -221,7 +204,7 @@ ambiguous-term sweep remain separate follow-up work.
 
 Canonical artifact IDs include `vision`, `decisions`, `plan`, `progress`,
 `todo`, `health`, `docs`, `design`, `profile`, `objective`, `experiments`,
-`changelog`, `session`, `plan_archive`, `optimera_harness`, and
+`changelog`, `session`, `plan_archive`, `optimize_harness`, and
 `semantic_fixture`.
 
 ## Status, severity, confidence, and exits
@@ -301,7 +284,7 @@ tests, labels, or active state.
 | Decision gate                              | Explicit condition-based branch before proceeding.                                      | Optimize keep/discard decision.                                           |
 | Exit-early stop condition                  | Stop condition when work is already complete or unnecessary.                            | Docs current, no stale work found.                                        |
 | Behavioral verification gate               | Build check that behavior was verified against real project state.                  | Tests, builds, or manual verification.                                    |
-| Pre-write self-audit                       | Prose check for verbosity mismatch, abstraction creep, and filler accumulation.         | `agentera lint --artifact <ARTIFACT>` exposes the checks through the CLI. |
+| Draft lint preview                         | Optional early feedback for verbosity mismatch, abstraction creep, and filler accumulation. | Pre-cutover, `npx -y agentera@next check lint --artifact <ARTIFACT>` previews a draft; the typed writer validates final bytes when publishing. |
 | Plan-completion sweep                      | Build cleanup when plan tasks finish.                                               | Progress rollup, changelog, TODO, health cross-reference, archive.        |
 | Worker spawn                               | Isolated implementation or measurement by a worker through the host subagent mechanism. | Build and optimize can use it.                                        |
 | Stale-base awareness                       | Prevent workers from branching from old `origin/main` or stale HEAD.                    | Use pre-spawn Git commits before spawning workers.                        |
@@ -361,18 +344,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 runtime names are Claude Code, OpenCode, Copilot CLI, Codex CLI, Cursor IDE, and Cursor Agent CLI.
+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
 
@@ -389,7 +368,7 @@ words. `agentera upgrade` is the only repair command. When app files are
 version-behind, the operation inside that command is an **update**; when files
 are missing or broken, it is a **repair**; when v1 artifacts exist, it is a
 **migrate**. Hej attention text should name both the operation and the command
-(for example, app files outdated; run `agentera upgrade`).
+(for example, app files outdated; run `npx -y agentera@next upgrade`).
 Compatibility aliases are transitional classifications in the YAML authority,
 not second source-of-truth status values.
 
@@ -417,9 +396,9 @@ prime resolve. The machine-readable authority is
 npm dist-tag and git ref resolution, override precedence, and consumer ownership
 for upgrade, doctor, prime, docs, and tests.
 
-Use this prose as guidance only: **stable** tracks the supported 2.x line on
-`npx -y agentera@latest` and, for maintainers, `uvx --from git+...@main` (Python
-CLI). **development** tracks 3.x alphas and release candidates on **npm only**
+Use this prose as guidance only: **stable** tracks the supported 2.x npm line
+and, for maintainers, `uvx --from git+...@main` (Python
+CLI). **development** tracks 3.x prereleases on **npm only**
 (`npx -y agentera@next`); feat/v3 is TypeScript-only and has no uv/git install
 path. v2→v3 is a one-way upgrade through the development npm channel. Default
 channel is stable. Override with `--channel`, `AGENTERA_UPDATE_CHANNEL`, or
@@ -436,26 +415,6 @@ Do not replace this with a parallel Markdown table of dist-tags, git refs, or
 override keys. Update the YAML authority first, then keep this section as the
 short human-facing boundary.
 
-### Bundle and SKILL.md vocabulary
-
-The machine-readable authority is
-`references/cli/bundle-skill-vocabulary.yaml`; it owns classification of
-`bundle` and `SKILL.md` usage into canonical concepts, compatibility
-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.
-
-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
-human-facing boundary.
-
 ## Evaluation and evidence grammar
 
 | Term                        | Definition                                                                                                                                                                                                                                                                                                                                                                  |
@@ -463,7 +422,7 @@ human-facing boundary.
 | Validation passed           | Evidence that required checks completed successfully. Name the checks.                                                                                                                                                                                                                                                                                                      |
 | Focused tests               | Targeted tests for the changed surface.                                                                                                                                                                                                                                                                                                                                     |
 | Full pytest                 | Repository-wide pytest run. Use exact counts when recorded.                                                                                                                                                                                                                                                                                                                 |
-| Capability validator        | `uv run agentera check validate capability skills/agentera/capabilities/<name>`.                                                                                                                                                                                                                                                                                            |
+| Capability validator        | `npx -y agentera@next check validate capability skills/agentera/capabilities/<name>`.                                                                                                                                                                                                                                                                                       |
 | Cross-capability validation | Checks that capability schemas agree with registry, protocol, routing, and exit contracts.                                                                                                                                                                                                                                                                                  |
 | Smoke eval                  | Runtime/setup check for crashes, non-zero exits, or obvious host failures.                                                                                                                                                                                                                                                                                                  |
 | Live-host smoke             | Explicit opt-in model-host check against real runtime access.                                                                                                                                                                                                                                                                                                               |
@@ -523,7 +482,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`.                                                                  |
@@ -543,7 +502,7 @@ High-risk diagnostic rewrites:
 | `bundle freshness guard failed` | `install status check failed`                                         |
 | `bundle refresh required`       | `repair Agentera app files`                                           |
 | `app refresh required`          | `Agentera app files need repair` or `Agentera app files are outdated` |
-| `upgrade guard triggered`       | `v1 migration check found legacy files`                               |
+| `upgrade guard triggered`       | `product-v1 state requires an explicit reset`                         |
 | `stale marker`                  | `missing or outdated version marker`                                  |
 | `artifact freshness failed`     | `artifact is stale` or `artifact needs sync`                          |
 
@@ -553,18 +512,16 @@ High-signal source surfaces for this vocabulary:
 
 | Source                                                        | Vocabulary surface                                                                                                                                                                        |
 | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `skills/agentera/SKILL.md`                                    | Routing entry, routing layers, CLI-first access, installed-app status check, and v1 migration check.                                                                                      |
+| `skills/agentera/SKILL.md`                                    | Routing entry, routing layers, CLI-first access, installed-app status check, and product-v1 reset boundary.                                                                               |
 | `skills/agentera/protocol.yaml`                               | Protocol primitives, glyphs, phases, visual tokens, exit signals.                                                                                                                         |
 | `skills/agentera/capability_schema_contract.yaml`             | Schema groups, priorities, stable IDs, primitive-reference fields.                                                                                                                        |
-| `packages/cli/src/capabilities/*/instructions.ts`             | Workflow grammar, capability roles, safety rails, exit marker forms. Loaded as a default-exported string constant; runtime serves it via `agentera prime --context <name> --format json`. |
+| `packages/cli/src/capabilities/*/instructions.ts`             | Workflow grammar, capability roles, safety rails, exit marker forms. Loaded as a default-exported string constant; pre-cutover runtime serves it via `npx -y agentera@next prime --context <name> --format json`. |
 | `skills/agentera/capabilities/*/schemas/*.yaml`               | Trigger patterns, artifact roles, validation rules, exit conditions.                                                                                                                      |
 | `skills/agentera/schemas/artifacts/*.yaml`                    | Artifact fields, status enums, validation vocabulary, and protected current-state fields.                                                                                                 |
 | `references/artifacts/artifact-registry-interface-model.yaml` | Canonical artifact registry language.                                                                                                                                                     |
 | `references/cli/app-lifecycle-vocabulary.yaml`                | App lifecycle canonical status and operation vocabulary authority.                                                                                                                        |
 | `references/cli/update-channels.yaml`                         | Update channel resolution and override-key authority.                                                                                                                                     |
-| `references/cli/bundle-skill-vocabulary.yaml`                 | Bundle and `SKILL.md` concept classification authority.                                                                                                                                   |
 | `references/cli/capability-instruction-contract.yaml`         | Decision 57 capability instruction-file and first-invocation read contract authority.                                                                                                     |
-| `references/cli/routing-execution-vocabulary.yaml`            | Routing and execution vocabulary authority.                                                                                                                                               |
 | `the agentera CLI`                                            | Flat State CLI labels and `agentera hej` source contract.                                                                                                                                 |
 | `packages/cli/src/upgrade (doctor/upgrade)`                   | Upgrade and doctor output grammar.                                                                                                                                                        |
 | `packages/cli/src/state/installRoot.ts`                       | Install-root classification semantics.                                                                                                                                                    |