agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/bundle/references/cli/capability-instruction-contract.yaml

@@ -55,7 +55,7 @@ current_state:
     field: first_invocation_read
     status: emitted_in_prime_capability_context
     current_behavior: >-
-      `agentera prime --context <name> --format json` emits
+      `npx -y agentera@next prime --context <name> --format json` emits
       `capability_context` metadata including `first_invocation_read`
       (value: `prime_context`, runtime_enforcement: true) and the full instructions
       in the `instructions` field for supported capabilities. Historical
@@ -72,14 +72,14 @@ first_invocation_read:
     prime_context:
       meaning: >-
         The first capability invocation must shell out to
-        `agentera prime --context <name> --format json` and read the
+        `npx -y agentera@next prime --context <name> --format json` and read the
         returned `instructions` field (the full Markdown body) before executing
         capability-specific work.
-      obligation: shell out to agentera prime --context <name> --format json
+      obligation: shell out to npx -y agentera@next prime --context <name> --format json
   default_rule: prime_context
   full_read_obligation: >-
     On initial capability invocation, shell out to
-    `agentera prime --context <name> --format json` and read the
+    `npx -y agentera@next prime --context <name> --format json` and read the
     `capability_context.instructions` field in full.
 implementation_state:
   instructions_ts_modules: implemented

package/bundle/references/cli/hybrid-route-contract.yaml

@@ -24,7 +24,7 @@ protocol:
       The transient, unmodified user message. It is accepted for routing and is
        never persisted by this protocol.
     cli_seam:
-      command: agentera route request --input PATH --format json
+      command: npx -y agentera@next route request --input PATH --format json
       input: >-
         A YAML or JSON mapping supplied by --input PATH or --input -. The request
         field is never accepted in argv; --input - reads it from stdin.
@@ -39,7 +39,7 @@ protocol:
       required_fields: [capability, tier, recognized_span, topic_span, provenance]
       tiers: [bare, direct, phrase]
     semantic_required:
-      required_fields: [request_sha256, semantic_capsule, semantic_capsule_sha256, provenance]
+      required_fields: [request_sha256, semantic_capsule, semantic_capsule_sha256, receipt_contract, provenance]
       semantic_capsule: >-
         The active trigger intent documentation and contract version needed for
         a host judgment. It contains no state-derived next_action and no raw
@@ -59,11 +59,33 @@ protocol:
           The digest binds the bounded classification inputs presented to the
           host, not route diagnostics, state, private raw request duplication,
           or any authority the host did not see.
+      receipt_contract:
+        schema_version: agentera.route_receipt_contract.v1
+        purpose: >-
+          A self-describing semantic-receipt guide returned only with deterministic
+          abstention. It contains the exact nullable receipt schema, legal outcomes,
+          nullability, compound and span rules, and one current stdin round trip.
+        stdin_command: npx -y agentera@next route receipt --input - --format json
+        input_schema:
+          type: object
+          additionalProperties: false
+          required: [request, receipt]
+          properties:
+            request: { type: string }
+            receipt: { $ref: '#/nullable_schema' }
+        stdin_example:
+          request: make implementation plan
+          receipt:
+            outcome: select
+            capability: plan
+            compound: none
+            question: null
+            remainder_span: null
   receipt:
     version: agentera.route_receipt.v1
     required_fields: [version, request_sha256, semantic_capsule_sha256, outcome]
     cli_seam:
-      command: agentera route receipt --input PATH --format json
+      command: npx -y agentera@next route receipt --input PATH --format json
       input: >-
         A YAML or JSON mapping supplied by --input PATH or --input -. It has the
          transient original request in request and the complete nullable host output
@@ -233,7 +255,7 @@ protocol:
       version: agentera.route_receipt_result.v1
       selected: >-
         Emits the selected canonical capability, bounded semantic-receipt
-        provenance, and agentera prime --context <capability> --format json as
+        provenance, and npx -y agentera@next prime --context <capability> --format json as
         the existing startup path. It authorizes that capability only.
       clarification: >-
         Emits exactly one validated question and semantic-receipt provenance; it
@@ -371,7 +393,7 @@ privacy:
 
 evaluation:
   conformance_owner: packages/cli/test/registries/hybridRouteContract.test.ts
-  visible_corpus_entrypoint: agentera route evaluate --format json
+  visible_corpus_entrypoint: npx -y agentera@next route evaluate --format json
   visible_corpus_exit_codes: { pass: 0, failed_evaluation: 1, authority_conflict: 2 }
   visible_corpus_output: >-
     agentera.hybrid_route_evaluation.v1 reports only case IDs, partitions,

package/bundle/references/cli/routing-model.md

@@ -48,8 +48,9 @@ host did not see.
 ## Phase two: semantic receipt
 
 For `semantic_required`, the host sends the same transient original request and
-the complete nullable host receipt to `agentera route receipt --input - --format
-json`. The receipt binds to the SHA-256 of the request's UTF-8 bytes and the
+the complete nullable host receipt to
+`npx -y agentera@next route receipt --input - --format json`. The receipt binds
+to the SHA-256 of the request's UTF-8 bytes and the
 `semantic_capsule_sha256` returned in phase one. The CLI first validates the
 unmodified host shape, removes only contract-listed nulls, then reruns
 deterministic routing and accepts the receipt only when the same request still
@@ -57,6 +58,13 @@ produces `semantic_required` with both bound digests. It then validates the
 projected CLI receipt with canonical-capability binding and request-bound span
 rules:
 
+Every `semantic_required` response includes a `receipt_contract` with the exact
+`agentera.route_receipt.v1` nullable schema, legal outcomes, outcome nullability,
+compound and `remainder_span` rules, and a current runnable stdin example. The
+same guide appears in `npx -y agentera@next route receipt --help`; a host does not need to
+inspect implementation or contract files to construct its receipt. The example
+uses a fixed public request, never the transient request being classified.
+
 | Receipt | Required result | Startup |
 | --- | --- | --- |
 | `select` | one canonical capability and `none` or `preserve` compound disposition | selected capability only |
@@ -65,8 +73,9 @@ rules:
 | invalid | bounded field-level correction, exit 64 | none |
 
 The resulting `selected` or `status_fallback` authorization contains bounded
-route provenance and the existing `agentera prime --context <capability>
---format json` startup path. A `clarification` contains exactly one bounded
+route provenance and the existing
+`npx -y agentera@next prime --context <capability> --format json` startup path.
+A `clarification` contains exactly one bounded
 question and no startup. This is intentionally a shared CLI contract, not a
 runtime-specific adapter. The portable shared skill is the sole host integration
 surface.
@@ -137,3 +146,10 @@ model calls.
 - `packages/cli/src/eval/hybridRouteEvaluation.ts` evaluates the frozen offline
   conformance corpus; its tests verify the evaluator and protocol structure.
 - `skills/agentera/SKILL.md` remains the thin portable host integration surface.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `node packages/cli/dist/bin/agentera.js route evaluate --format json`

package/bundle/references/cli/trigger-schema-enrichment.md

@@ -138,3 +138,10 @@ validator validates their compatibility shapes; specifically, it validates the
 numeric fields' integer 0..100 range, while the loader accepts and discards
 their values. Do not add them to new active trigger entries. Their presence
 cannot change a natural-language classification.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `node packages/cli/dist/bin/agentera.js check validate capability-contract --format json`

package/bundle/references/cli/vocabulary-index.yaml

@@ -14,9 +14,7 @@ authority_order:
   - references/artifacts/artifact-registry-interface-model.yaml
   - references/cli/app-lifecycle-vocabulary.yaml
   - references/cli/update-channels.yaml
-  - references/cli/bundle-skill-vocabulary.yaml
   - references/cli/capability-instruction-contract.yaml
-  - references/cli/routing-execution-vocabulary.yaml
   - skills/agentera/SKILL.md
   - packages/cli/src/capabilities/*/instructions.ts
   - the agentera CLI
@@ -158,7 +156,7 @@ decision_44:
         Preserve the Decision 43 English alias set as the binding canonical names for v3 and onward under the single-agent identity (Decision 74): status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate. Future capability additions follow the same transfer-friendly English-verb pattern (Decision 70). Per Decisions 70 and 74, the D43 alias set is the binding name set under one agent, one CLI, many capabilities; future renames require a new decision.
     - surface: Legacy Swedish capability names (v2 stable only)
       boundary: >-
-        Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera for the v2 stable distribution (`npx -y agentera@latest`, ships from `main`) and 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.
+        Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera for the v2 stable distribution from main and 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.
     - surface: Historical artifacts
       boundary: Do not rewrite old progress, changelog, archived plans, or decisions solely for vocabulary cleanup.
     - surface: Release version

package/bundle/references/cli/vocabulary.md

@@ -19,11 +19,9 @@ included when they shape cross-suite usage.
 | `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.                                                                                                                                                                                                                                                 |
 
@@ -52,12 +50,12 @@ 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. 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` |
+| 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. 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 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) |
+| 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`                                               |
@@ -97,11 +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
+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 `agentera prime --context <name> --format
-json` response emits `capability_context.instructions` plus
+`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
@@ -111,9 +110,10 @@ CLI process; agent runtimes shell out to the prime command instead of reading
 the prose module directly.
 
 Status startup is the one-call exception to the general compact-data wording
-above: `agentera prime --context status --format json` returns
+above: `npx -y agentera@next prime --context status --format json` returns
 `capability_context.instructions` and bounded
-`capability_context.context.status_context` together. Consumers do not make a
+`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.
 
@@ -122,7 +122,7 @@ authoritative recovery command.
 | 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](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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -173,7 +173,7 @@ 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
-record reads use `agentera state plan list`, `state progress list`,
+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
@@ -183,27 +183,6 @@ 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                                                                                                                                                                                                                                                                                                                           |
@@ -306,7 +285,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.                                    |
-| Draft lint preview                         | Optional early feedback for verbosity mismatch, abstraction creep, and filler accumulation. | `agentera check lint --artifact <ARTIFACT>` previews a draft; the typed writer validates final bytes when publishing. |
+| 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.                        |
@@ -390,7 +369,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.
 
@@ -418,8 +397,8 @@ 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
+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 alphas and release candidates 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
@@ -437,25 +416,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, 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
-human-facing boundary.
-
 ## Evaluation and evidence grammar
 
 | Term                        | Definition                                                                                                                                                                                                                                                                                                                                                                  |
@@ -463,7 +423,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.                                                                                                                                                                                                                                                                                                               |
@@ -556,15 +516,13 @@ High-signal source surfaces for this vocabulary:
 | `skills/agentera/SKILL.md`                                    | Routing entry, routing layers, CLI-first access, installed-app status check, and v1 migration check.                                                                                      |
 | `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.                                                                                                                                                    |

package/bundle/references/meta/retained-reference-authority.yaml

@@ -0,0 +1,151 @@
+schema_version: agentera.retainedReferenceAuthority.v1
+live_roots:
+  - references
+  - skills/agentera/references
+inventory:
+  - path: references/adapters/package-publication.json
+    classification: current
+    production_owner: { module: packages/cli/scripts/publication-transaction.mjs, symbol: PUBLICATION_CONTRACT }
+    consumers:
+      - { kind: runtime, module: packages/cli/scripts/publication-transaction.mjs, symbol: PUBLICATION_CONTRACT, consumption: loads }
+      - { kind: runtime, module: packages/cli/src/registries/packagePublication.ts, symbol: loadPackagePublicationModel, consumption: loads }
+  - path: references/adapters/package-registry.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/packageRegistry.ts, symbol: loadRegistry }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/packageRegistry.ts, symbol: loadRegistry, consumption: loads }
+  - path: references/analysis/evidence-tier-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/evidenceTierContract.ts, symbol: loadEvidenceTierContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/evidenceTierContract.ts, symbol: loadEvidenceTierContract, consumption: loads }
+  - path: references/analysis/verification-policy.yaml
+    classification: current
+    production_owner: { module: packages/cli/scripts/verify-lane.mjs, symbol: loadContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/scripts/verify-lane.mjs, symbol: loadContract, consumption: loads }
+  - path: references/artifacts/artifact-registry-interface-model.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/artifactRegistry.ts, symbol: loadArtifactRegistry }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/artifactRegistry.ts, symbol: loadArtifactRegistry, consumption: loads }
+  - path: references/artifacts/glossary-entry-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/glossaryEntryContract.ts, symbol: glossaryEntryAuthorityPath }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/glossaryEntryContract.ts, symbol: personalGlossaryOutputContract, consumption: loads }
+  - path: references/artifacts/state-storage-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/state/stateStorageAuthority.ts, symbol: loadStateStorageAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/state/stateStorageAuthority.ts, symbol: loadStateStorageAuthority, consumption: loads }
+  - path: references/artifacts/verbosity-budget-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/verbosityBudgetContract.ts, symbol: inspectArtifactVerbosityBudget }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/verbosityBudgetContract.ts, symbol: inspectArtifactVerbosityBudget, consumption: loads }
+  - path: references/cli/app-lifecycle-vocabulary.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/cli/bundle-skill-vocabulary.yaml
+    classification: delete
+  - path: references/cli/capability-instruction-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/cli/capabilityContext/progress.ts, symbol: evaluatorHandoffOutputRequirementsFromContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/cli/capabilityContext/progress.ts, symbol: evaluatorHandoffOutputRequirementsFromContract, consumption: loads }
+  - path: references/cli/hybrid-route-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/hybridRoute.ts, symbol: resolveRouteRequest }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/hybridRoute.ts, symbol: resolveRouteRequest, consumption: loads }
+  - path: references/cli/update-channels.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/release/releaseMetadata.ts, symbol: readReleaseMetadata }
+    consumers:
+      - { kind: validator, module: packages/cli/src/release/releaseMetadata.ts, symbol: readReleaseMetadata, consumption: loads }
+  - path: references/cli/vocabulary-index.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/cli/vocabulary.md
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-adapters.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleAdapterContract.ts, symbol: loadRuntimeLifecycleAdapterContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleAdapterContract.ts, symbol: loadRuntimeLifecycleAdapterContract, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-authority.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleAuthority.ts, symbol: loadLifecycleAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleAuthority.ts, symbol: loadLifecycleAuthority, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-operation-contract.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleOperationContract.ts, symbol: loadLifecycleOperationContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleOperationContract.ts, symbol: loadLifecycleOperationContract, consumption: loads }
+  - path: references/adapters/runtime-retired-resources.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/nativeResourceCleanup.ts, symbol: loadNativeResourceCleanupContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/nativeResourceCleanup.ts, symbol: loadNativeResourceCleanupContract, consumption: loads }
+  - path: references/cli/v3-handoff-manifest.schema.yaml
+    classification: delete
+  - path: references/adapters/package-surface-characterization.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: pnpm -C packages/cli run pack:dry-run
+  - path: references/cli/routing-model.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: node packages/cli/dist/bin/agentera.js route evaluate --format json
+  - path: references/cli/trigger-schema-enrichment.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: node packages/cli/dist/bin/agentera.js check validate capability-contract --format json
+  - path: references/meta/retained-reference-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/retainedReferenceAuthority.ts, symbol: validateRetainedReferenceAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/retainedReferenceAuthority.ts, symbol: validateRetainedReferenceAuthority, consumption: loads }
+  - path: references/cli/upgrade-repair-wording.md
+    classification: historical
+  - path: references/adapters/package-manifest-interface-model.yaml
+    classification: delete
+  - path: references/analysis/benchmark.md
+    classification: delete
+  - path: references/analysis/startup-measurement-contract.yaml
+    classification: delete
+  - path: references/cli/agent-ready-state-contract.yaml
+    classification: delete
+  - path: references/cli/audience-namespace-cli-migration.yaml
+    classification: delete
+  - path: references/cli/capability-instruction-structure.md
+    classification: delete
+  - path: references/cli/capability-tool-classification.yaml
+    classification: delete
+  - path: references/cli/parity-expected-actual-template.md
+    classification: delete
+  - path: references/cli/prime-consumer-compatibility.yaml
+    classification: delete
+  - path: references/cli/routing-execution-vocabulary.yaml
+    classification: delete
+  - path: references/cli/single-name-protocol.yaml
+    classification: delete
+  - path: references/meta/documentation-inventory.md
+    classification: delete
+  - path: skills/agentera/references/contract.md
+    classification: delete