agentera 3.0.0-dev.8 → 3.0.0-dev.80

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

@@ -1,96 +1,155 @@
-# Five-layer routing model
-
-Origin: Decision 76 (2026-06-30) — LLM-primary routing model. Retires the
-deterministic NL routing engine and repositions the trigger schema as
-LLM-readable intent documentation. Builds on the original five-layer concept
-from Decision 42 (2026-05-04), redefining Layers 3-4 as LLM-native.
-
-The Agentera routing model resolves incoming requests to a capability across
-five layers. Layers 1, 2, and 5 are deterministic dispatch (bare invocation,
-exact alias, no match); they are implemented and unchanged. Layers 3 and 4
-cover natural-language requests. Per Decision 76, the LLM host — the AI model
-that receives the user's message — owns natural-language routing natively. The
-trigger schema (`description`, `disambiguates_against`, `priority`, phase
-context) provides LLM-readable intent documentation the host consults; there is
-no scoring engine, no confidence threshold, and no borderline band. Layer 4
-(formerly borderline-band disambiguation) is dissolved into Layer 3: the LLM
-resolves ambiguity natively, using `disambiguates_against` hints as advisory
-context. Decision 75's request-vs-state mutual exclusivity is dissolved: request
-intent and state-readiness are both advisory context the LLM consults.
-
-## Layer 1: Bare `/agentera` or bare `hej` — delegate to prime
-
-- **Input pattern**: the request is `/agentera` with no additional text, or the
-  complete user message is exactly `hej`.
-- **Action**: delegate immediately to the status capability. Status performs
-  state-aware routing through the `agentera prime` composite result, which
-  condenses project artifacts and suggests the most useful next capability.
-  This is deterministic and never wrong. Bare `hej` must not be handled as a
-  generic greeting.
-- **Implementation status**: implemented and unchanged.
-
-## Layer 2: capability name or `/agentera <primary-alias>` — direct route
-
-- **Input pattern**: the request text exactly matches a capability name
-  (case-insensitive), or exactly matches one primary alias from
-  `capability_schema_contract.yaml` `ROUTE_ALIASES.primary_aliases`, or begins
-  with a canonical capability name followed by more text (`/agentera <capability>
-  <topic>`).
-- **Action**: route directly to that capability without evaluating natural-language
-  trigger descriptions. Pass any remaining text as the user's topic or instruction.
-  Each capability has exactly one primary alias; secondary wording stays in
-  capability trigger schemas below this layer.
-- **Implementation status**: implemented and unchanged.
-
-## Layer 3: Natural language — LLM-native routing
-
-- **Input pattern**: the request is natural language (e.g. "help me think
-  through this") that does not match Layer 1 or Layer 2.
-- **Action**: the LLM host routes natively. It consults the trigger schema's
-  `description` fields (what each capability does), `disambiguates_against`
-  hints (how to tell near-equal capabilities apart), and `priority`
-  (relevance precedence) as LLM-readable intent documentation, then selects a
-  capability. There are no confidence scores, no thresholds, and no
-  weighted-average computation; the LLM reads the intent descriptions and
-  routes.
-- **Resolving ambiguity**: when two capabilities could match a request, the
-  LLM host resolves the ambiguity natively, surfacing the
-  `disambiguates_against.hint` strings as advisory context when it asks the
-  user to confirm or clarify. The hints supply the words; the LLM supplies the
-  judgment.
-- **Implementation status**: implemented — the LLM host owns this layer.
-  `references/cli/trigger-schema-enrichment.md` is the intent documentation
-  contract the host reads.
-
-## Layer 4: Dissolved into Layer 3
-
-Layer 4 formerly described a borderline-band disambiguation engine that fired
-when two capabilities scored within a configurable band. Decision 76 retired
-that engine: ambiguity resolution is now part of Layer 3, performed natively by
-the LLM host using the `disambiguates_against` hints as advisory context. There
-is no separate disambiguation layer, no borderline band, and no
-disambiguation-engine output schema.
-
-## Layer 5: No match — fallback to status
-
-- **Input pattern**: the LLM host cannot map the request to any capability from
-  the trigger schema's intent descriptions.
-- **Action**: route to status for orientation. Status handles greetings, status
-  requests, and ambiguous inputs.
-- **Implementation status**: implemented and unchanged.
+# Hybrid routing model
+
+The portable shared skill and CLI use one hybrid cascade. Explicit routes and
+curated, globally unique literal phrases provide deterministic tiers; open-ended
+language remains host-owned. The normative protocol is
+[`hybrid-route-contract.yaml`](./hybrid-route-contract.yaml); this page is a
+reader-oriented model, not a second contract.
+
+Decision 76 remains in force for natural-language judgment. Decision mpulyomlyl supersedes it only for the curated literal fast path: there is still no scoring engine, no confidence threshold, and no borderline band. Legacy trigger patterns, regexes, thresholds, and bands do not route requests.
+
+## Cascade and precedence
+
+1. **Bare `/agentera`.** With no added text, select status deterministically.
+2. **Explicit direct route.** A canonical capability name or primary alias uses
+   the established direct-route grammar and passes its remaining text as topic.
+3. **Curated leading phrase.** Match one active phrase from
+   [`skills/agentera/route-phrases.yaml`](../../skills/agentera/route-phrases.yaml)
+   only when it is the exact normalized leading phrase. It selects that phrase's
+   sole owner and preserves the original remainder as topic.
+4. **Deterministic abstention.** Every other request returns
+   `semantic_required`. This tier never guesses from trigger prose, substrings,
+   regexes, scores, thresholds, bands, state, or `next_action`.
+5. **Validated semantic receipt.** The host makes an LLM-native semantic
+   judgment and submits `select`, `clarify`, or `no_match`; the CLI validates it
+   before capability startup. `select` starts one selected capability, `clarify` starts none, and `no_match` must route to status for orientation only after no capability matches.
+
+The direct grammar has precedence over phrase matching. A phrase collision is a
+registry validation error, not a tie to resolve at runtime.
+
+## Phase one: route request
+
+`agentera.route_request.v1` takes the transient original request. Its response
+is exactly one of:
+
+- `deterministic_selection`: a `bare`, `direct`, or `phrase` selection with
+  capability, provenance, recognized span, and topic span.
+- `semantic_required`: a request digest, semantic intent capsule, and canonical
+  capsule digest. It does not start a capability.
+
+The request itself is not persisted. The semantic capsule contains active
+trigger `description`, `priority`, and `disambiguates_against` documentation,
+not executable matcher inputs. Its digest is SHA-256 over contract-owned
+canonical JSON (recursively sorted object keys, no insignificant whitespace,
+and the presented array order) for exactly that capsule. It excludes private
+request text, request digests, diagnostics, state, and matcher authorities the
+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
+`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
+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 |
+| `clarify` | one non-empty question | none |
+| `no_match` | no capability or question | status only |
+| invalid | bounded field-level correction, exit 64 | none |
+
+The resulting `selected` or `status_fallback` authorization contains 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.
+
+## Phrase, span, and topic behavior
+
+The phrase registry owns stable IDs, capability ownership, literal phrases,
+global collision detection, and deprecation. Per-capability trigger schemas
+never create phrase ownership. Matching uses the contract's normalized token
+view (Unicode NFKC, case folding, whitespace normalization) while returning
+source UTF-8 byte offsets and exact slices from the original request. A `:`,
+`-`, or `—` that terminates the final phrase token is recognized in the
+comparison view but starts the preserved topic slice; other attached
+punctuation abstains.
+
+For example, `HELP\tME decide: migrate the store` recognizes only
+`HELP\tME decide`; its topic is the exact original `: migrate the store`.
+The separator is deliberately preserved. Quoted, negated, later-in-sentence,
+partial, and unregistered wording abstains; it belongs to the semantic phase.
+
+## Selection, ambiguity, and compounds
+
+The LLM host owns semantic selection and genuine consequential ambiguity. It
+consults trigger intent documentation, then chooses one of `select`, `clarify`,
+or `no_match`. A compound request never authorizes implicit chaining:
+
+- A direct or phrase selection preserves its entire original remainder as one
+  topic without interpreting it as follow-on work.
+- A semantic `select` may mark one original, UTF-8 code-point-aligned trailing
+  remainder span `preserve`; it is deferred intent, not a second startup.
+  `clarify` is an outcome, never a compound disposition.
+- Independent or consequential compound intent uses the `clarify` outcome when
+  one primary capability cannot be named safely.
+
+`next_action` informs readiness only after classification and cannot override the message intent. It never classifies a request.
+
+## Evaluation and privacy
+
+The visible frozen development and adversarial regression data live in
+[`fixtures/routing/hybrid-corpus.yaml`](../../fixtures/routing/hybrid-corpus.yaml).
+They use synthetic or explicitly consented text only and are the sole frozen
+implementation conformance corpus; no sealed holdout, credential, privacy
+approval, or provider-host benchmark is required.
+Retained evaluation evidence contains IDs, partition, outcome, tier,
+capability, timing, and aggregate metrics; private raw request
+text, topic text, receipt questions, and semantic rationale are absent by
+default.
+
+The portable host receipt shape has all fields required, using nullable fields
+for outcome-inapplicable values; the bounded host-to-CLI normalization seam first
+validates that unmodified shape, removes only contract-listed nulls, and preserves
+every non-null value unchanged. The CLI schema then separately validates outcome
+relationships, request binding, spans, canonical capabilities, and startup authorization.
+Normalization never authorizes startup or weakens a cross-field rule.
+The evaluator reports separate, run-specific local deterministic and
+receipt-validation p95 values. They prove protocol conformance for this visible
+corpus, not semantic generalization or an end-to-end latency commitment. Semantic
+model quality and latency remain host-dependent and unmeasured; it makes no live
+model calls.
 
 ## Ownership boundaries
 
-- **This document** defines what Layers 1-5 mean: their input patterns, actions,
-  and implementation status.
-- **`skills/agentera/capability_schema_contract.yaml`** (`ENTRY_SCHEMA.fields.priority`
-  and `FIELD_RULES.TRIGGERS.priority`) defines trigger `priority` values
-  (`high`, `medium`, `low`) as an advisory relevance-precedence hint the LLM host
-  reads — not a scoring weight.
-- **Per-capability `schemas/triggers.yaml`** owns the trigger `description`,
-  `priority`, and `disambiguates_against` intent documentation that the LLM host
-  consults for Layer 3 routing. `references/cli/trigger-schema-enrichment.md` is
-  the intent documentation contract; pattern matching and scoring belong to
-  neither, having been retired by Decision 76.
-- **`skills/agentera/SKILL.md`** is the thin bootstrap routing surface per Decision
-  74; it cross-references this document rather than restating the full model.
+- `references/cli/hybrid-route-contract.yaml` owns protocol, outcome vocabulary,
+  precedence, span rules, privacy, evaluation gates, and deprecations.
+- `skills/agentera/route-phrases.yaml` owns the deterministic phrase inventory.
+- `references/cli/trigger-schema-enrichment.md` owns semantic trigger intent
+  documentation only.
+- `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

@@ -1,38 +1,31 @@
 # Trigger intent documentation contract
 
-Authority for Layer 3 LLM-native capability routing. This document defines the
-trigger-schema fields the LLM host consults to understand what each capability
-does and how to disambiguate near-equal requests. The fields are documentation
-the host reads, not inputs to a scoring engine.
+Authority for semantic-phase trigger intent documentation. This document
+defines the trigger-schema fields a host consults only after the CLI
+deterministically abstains, so it can make a semantic judgment and submit a
+receipt. The fields are documentation, not inputs to a routing engine.
 
 - **Authority path:** `references/cli/trigger-schema-enrichment.md`
 - **Schema contract:** `skills/agentera/capability_schema_contract.yaml` (the
   contract loader at `packages/cli/src/registries/capabilityContract.ts` consumes it)
 - **Trigger files:** `skills/agentera/capabilities/<name>/schemas/triggers.yaml`
-- **Scope:** Layer 3 (LLM-native natural-language routing) of the five-layer
-  routing model. Layer 4 (formerly borderline-band disambiguation) is dissolved
-  into Layer 3. Layers 1, 2, and 5 are unchanged.
-
-## Decision 76 — repositioning
-
-Decision 76 (2026-06-30) retires the deterministic NL routing engine. The LLM
-host — the AI model that receives the user's message — owns natural-language
-routing natively. This document is repositioned from a scoring-enrichment
-contract to the **trigger intent documentation contract**: it defines the
-`triggers.yaml` fields that help the LLM host understand what each capability
-does and how to disambiguate near-equal requests.
-
-The fields stay as documentation, not as scoring inputs. The LLM host reads the
-descriptions and disambiguates natively; `priority` and `disambiguates_against`
-are advisory hints, not scoring weights. There is no scoring algorithm, no
-confidence threshold, no borderline band, and no `prime --route` output schema.
-Decision 75's request-vs-state mutual exclusivity is dissolved: request intent
-and state-readiness are both advisory context the LLM consults. Decision 76
-supersedes Decision 75 design choices 2 (request-derived scoring as router), 4
-(mutual exclusivity), and 5 (pure request-derived).
-
-Decision 76 records the design choices and rejected alternatives (including the
-tuning-the-engine and reposition-`--route` alternatives that were rejected).
+- **Scope:** The semantic phase of the two-phase route contract. See
+  `references/cli/hybrid-route-contract.yaml` for the authoritative precedence,
+  abstention, receipt validation, and startup authorization rules.
+
+## Current boundary and obsolete layer numbering
+
+Earlier Decision 76 material described open-ended routing as Layer 3 and folded
+the former Layer 4 into it. That layer numbering is obsolete; it is not another
+routing model. The hybrid route contract now has one deterministic request phase
+(bare, direct, and curated phrase selection) and one semantic receipt phase.
+
+Only a `semantic_required` response may expose these fields to a host. The host
+uses them to choose `select`, `clarify`, or `no_match`, then submits the complete
+receipt. The CLI validates that receipt before authorizing capability startup.
+`priority` and `disambiguates_against` are advisory semantic-judgment context,
+not scoring weights. There is no scoring algorithm, confidence threshold,
+borderline band, or `prime --route` output schema.
 
 ## 1. Field shape
 
@@ -45,11 +38,11 @@ one capability.
 ### 1.1 `description`
 
 - **Type:** non-empty string (required on every `TRIGGERS` entry).
-- **Meaning:** the LLM-readable explanation of what this trigger entry routes to.
-  The LLM host reads this to decide whether a natural-language request matches
-  the capability's intent. Prose that names the capability's purpose and the
-  request shapes it owns reads better than keyword lists; write it for a reader
-  who has never seen the capability before.
+- **Meaning:** the semantic-judgment explanation of this capability's intent.
+  After `semantic_required`, the host reads it to decide whether a request fits
+  the capability. Prose that names the capability's purpose and request shapes
+  reads better than keyword lists; write it for a reader who has never seen the
+  capability before.
 - **Validation failure:** a missing, empty, or non-string `description` fails
   validation with an error message naming the offending entry ID.
 
@@ -58,11 +51,11 @@ TRIGGERS:
   1:
     id: T2
     description: >-
-      Audit and codebase health requests.
-    priority: medium
-    patterns:
-      - "check code health"
-      - "architecture review"
+      Audit local codebase health, architecture, quality, or technical debt.
+    priority: high
+    disambiguates_against:
+      - capability: document
+        hint: "audit owns code and architecture health; document owns documentation maintenance"
 ```
 
 ### 1.2 `disambiguates_against`
@@ -76,11 +69,10 @@ TRIGGERS:
   - `hint` — non-empty string distinguishing this trigger's intent from the
     named capability on near-equal requests.
 - **Meaning:** declares which other capabilities this trigger's intent could be
-  confused with, with a hint the LLM host consults when it sees a request that
-  could match more than one capability. The list is advisory: the LLM host
-  resolves ambiguity natively and MAY surface the hint when asking the user to
-  confirm or clarify. The hint supplies the words; the LLM supplies the
-  judgment.
+  confused with, with a hint the host consults after `semantic_required`. The
+  list is advisory: the host resolves ambiguity and MAY surface the hint when
+  asking the user to clarify. The hint supplies the words; the host supplies the
+  judgment in a receipt the CLI validates.
 - **Validation failure:** a `capability` value that is not one of the twelve
   canonical IDs, a missing `hint`, an empty `hint`, or an entry that is not a
   mapping fails validation with the offending entry ID and the constraint.
@@ -98,7 +90,8 @@ disambiguates_against:
 - **Type:** string enum `high` | `medium` | `low` (required on every `TRIGGERS`
   entry).
 - **Meaning:** advisory relevance-precedence hint the LLM host reads alongside
-  `description` when deciding which capability best fits a request. `high`
+  `description` when deciding which capability best fits a semantically
+  abstained request. `high`
   marks a capability that owns the request strongly; `low` marks a capability
   that is a plausible but weaker fit. It is not a scoring weight and feeds no
   weighted-average calculation; the LLM host uses it as one signal among the
@@ -132,5 +125,23 @@ contract-owned values).
 | `description` is a non-empty string on every `TRIGGERS` entry | §1.1 |
 | `disambiguates_against` entries reference a valid capability ID and include a non-empty hint | §1.2 |
 | `priority` is one of `high` / `medium` / `low` on every `TRIGGERS` entry | §1.3 |
-| Document reframed as LLM-readable intent documentation; no scoring algorithm, thresholds, borderline band, or `--route` output schema | Decision 76, §1 |
-| Decision artifact lists each choice, ≥1 alternative, and rationale | Decision 76 in `.agentera/decisions.yaml` |
+| Trigger fields are semantic-phase documentation; no scoring algorithm, thresholds, borderline band, or `--route` output schema | Current boundary, §1 |
+| Deterministic precedence and validated receipt authorization remain singular | `hybrid-route-contract.yaml` |
+
+## 4. Legacy enriched fields
+
+`patterns`, `patterns_regex`, `confidence_threshold`, and `borderline_band`
+remain accepted only so inherited enriched trigger files validate and load. They
+are discarded by the loader: the active trigger model does not expose strings,
+`RegExp` objects, scores, thresholds, or bands from them. The capability
+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/update-channels.yaml

@@ -3,7 +3,7 @@ status: active_authority
 purpose: >-
   Define dual update channels that select which published Agentera line upgrade,
   doctor, and prime resolve: stable tracks the supported 2.x line; development
-  tracks 3.x alphas and release candidates.
+  tracks 3.x prereleases.
 sources:
   prose:
     - references/cli/vocabulary.md#update-channels
@@ -45,7 +45,8 @@ channels:
         supported 2.x line until you explicitly opt in through npm.
       guide_url: >-
         https://github.com/jgabor/agentera/blob/main/UPGRADE.md#upgrading-v2-to-v3-development-channel-irreversible
-      preview_command: npx -y agentera@next upgrade --dry-run --channel development
+      preview_command: npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
       irreversible_advisory: >-
         Forward migration to the successor line is one-way; return to the prior
         Python support line is permanently unsupported.
@@ -59,7 +60,7 @@ channels:
   development:
     concept: v3_pre_release_line
     definition: >-
-      Tracks 3.x alphas, betas, and release candidates for early adopters and
+      Tracks 3.x prereleases for early adopters and
       maintainers testing the npm self-contained TypeScript distribution. The
       feat/v3 branch and v3 CLI are npm-only; v2→v3 is a one-way upgrade through
       npx @next, not through uvx or git checkout installs.
@@ -75,7 +76,8 @@ channels:
         The v3 successor line is npm-only; opt in to v2→v3 migration through npx @next.
       guide_url: >-
         https://github.com/jgabor/agentera/blob/main/UPGRADE.md#upgrading-v2-to-v3-development-channel-irreversible
-      preview_command: npx -y agentera@next upgrade --dry-run --channel development
+      preview_command: npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
       irreversible_advisory: >-
         Forward migration to the v3 line is one-way; return to the prior
         Python support line is permanently unsupported.
@@ -133,7 +135,7 @@ consumers:
       - development
   prime:
     owns:
-      - channel-aware v1 migration and app-home gate command strings.
+      - channel-aware app-home gate command strings.
     may_resolve_channels:
       - stable
       - development

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
@@ -33,17 +31,17 @@ normalization_rules:
     use: single Agentera agent, capabilities (the product word); "skill" and "plugin" survive only as internal transport (the skills/ directory and plugin.json manifests host editors require)
     avoid: '"Agentera skill" or "plugin" as product words; "twelve-skill suite" or "plugin suite" for the capability set.'
   - rule: Agentera is the agent; the host is the harness (Decision 74).
-    use: host runtime, harness, host coding agent (Claude, Cursor, Codex, Copilot, OpenCode); the CLI owns routing, memory, capability prose, and the worker-spec contract
+    use: host runtime, harness, host coding agent (OpenCode, Codex, Cursor, Copilot); the CLI owns routing, memory, capability prose, and the worker-spec contract
     avoid: Calling host coding agents peers or extension hosts of Agentera; implying Agentera is a module loaded into the host.
   - rule: /agentera is the main invocation.
     use: /agentera, $agentera for Codex-specific docs
-    avoid: /hej except as a legacy bridge.
+    avoid: /hej.
   - rule: The CLI source and rendered dashboard are different.
     use: agentera prime source data, status dashboard rendered briefing
     avoid: Treating raw CLI labels as the user-facing dashboard.
-  - rule: Routine state uses flat commands.
-    use: agentera plan, agentera docs, agentera health
-    avoid: agentera query plan for routine state.
+  - rule: Routine state uses the state namespace.
+    use: agentera state plan list, agentera state docs list, agentera state health list
+    avoid: agentera plan, agentera docs, or agentera health as routine state commands.
   - rule: query is advanced access.
     use: agentera query --list-artifacts, agentera query <artifact>
     avoid: Calling it the normal state interface.
@@ -74,7 +72,7 @@ plain_language:
       avoid: Bare freshness checkpoint
     - use: Agentera app files need repair
       avoid: bundle freshness gap in user-facing diagnostics
-    - use: v1 migration check
+    - use: product-v1 state requires an explicit reset
       avoid: Bare upgrade guard in onboarding or recovery text
     - use: checkpoint commit
       avoid: Bare checkpoint
@@ -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