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

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -73,32 +73,32 @@ entity_target:
     status: final
     commands:
       progress:
-        list: agentera state progress list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state progress get --id ID --format json
+        list: npx -y agentera@next state progress list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state progress get --id ID --format json
       decisions:
-        list: agentera state decisions list [--topic TEXT] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state decisions get --id ID --format json
+        list: npx -y agentera@next state decisions list [--topic TEXT] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state decisions get --id ID --format json
       health:
-        list: agentera state health list [--dimension DIMENSION] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state health get --id ID --format json
+        list: npx -y agentera@next state health list [--dimension DIMENSION] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state health get --id ID --format json
       plans:
-        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state plan get --id ID --format json
+        list: npx -y agentera@next state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state plan get --id ID --format json
       plan_tasks:
-        list: agentera state plan tasks list [PLAN_ID] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state plan tasks get --id ID --format json
+        list: npx -y agentera@next state plan tasks list [PLAN_ID] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state plan tasks get --id ID --format json
       objective:
-        list: agentera state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state objective get --id ID --format json
+        list: npx -y agentera@next state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state objective get --id ID --format json
       experiments:
-        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state experiments get --id ID --format json
+        list: npx -y agentera@next state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state experiments get --id ID --format json
       todo:
-        list: agentera state todo list [--severity SEVERITY] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state todo get --id ID --format json
+        list: npx -y agentera@next state todo list [--severity SEVERITY] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state todo get --id ID --format json
       docs:
-        list: agentera state docs list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
-        get: agentera state docs get --id ID --format json
+        list: npx -y agentera@next state docs list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state docs get --id ID --format json
     list_help:
       schema_version: agentera.entityListHelp.v1
       defaults:
@@ -120,53 +120,53 @@ entity_target:
           filters:
             - { flag: --topic TEXT, name: topic, values: free_text }
             - { flag: --status STATUS, name: status, values: free_text }
-          example: agentera state progress list --limit 20 --format json
+          example: npx -y agentera@next state progress list --limit 20 --format json
         decisions:
           command_tokens: [decisions]
           bare_read: alias
           filters:
             - { flag: --topic TEXT, name: topic, values: free_text }
-          example: agentera state decisions list --limit 20 --format json
+          example: npx -y agentera@next state decisions list --limit 20 --format json
         health:
           command_tokens: [health]
           bare_read: correction
-          bare_recovery: agentera state health list --limit 20 --format json
+          bare_recovery: npx -y agentera@next state health list --limit 20 --format json
           filters:
             - { flag: --dimension DIMENSION, name: dimension, values: free_text }
-          example: agentera state health list --limit 20 --format json
+          example: npx -y agentera@next state health list --limit 20 --format json
         plans:
           command_tokens: [plan]
           bare_read: correction
-          bare_recovery: agentera state plan list --status open --limit 20 --format json
+          bare_recovery: npx -y agentera@next state plan list --status open --limit 20 --format json
           filters:
             - { flag: '--status open|complete|archived', name: status, values: [open, complete, archived] }
-          example: agentera state plan list --status open --limit 20 --format json
+          example: npx -y agentera@next state plan list --status open --limit 20 --format json
         plan_tasks:
           command_tokens: [plan, tasks]
           bare_read: correction
-          bare_recovery: agentera state plan tasks list --limit 20 --format json
+          bare_recovery: npx -y agentera@next state plan tasks list --limit 20 --format json
           family_identifier:
             syntax: PLAN_ID
             required: false
             description: Optional bare plan ID; omit it to list tasks from the active plan.
           filters: []
-          example: agentera state plan tasks list --limit 20 --format json
+          example: npx -y agentera@next state plan tasks list --limit 20 --format json
         objective:
           command_tokens: [objective]
           bare_read: correction
-          bare_recovery: agentera state objective list --limit 20 --format json
+          bare_recovery: npx -y agentera@next state objective list --limit 20 --format json
           filters: []
-          example: agentera state objective list --limit 20 --format json
+          example: npx -y agentera@next state objective list --limit 20 --format json
         experiments:
           command_tokens: [experiments]
           bare_read: correction
-          bare_recovery: agentera state objective list --limit 20 --format json
+          bare_recovery: npx -y agentera@next state objective list --limit 20 --format json
           family_identifier:
             syntax: --objective ID
             required: true
             description: Required bare objective entity ID.
           filters: []
-          example: agentera state experiments list --objective qjtrmnpvka --limit 20 --format json
+          example: npx -y agentera@next state experiments list --objective qjtrmnpvka --limit 20 --format json
         todo:
           command_tokens: [todo]
           bare_read: alias
@@ -200,15 +200,15 @@ entity_target:
               ownership: computed_read_snapshot
               persisted: false
               filter: false
-          example: agentera state todo list --severity critical --ids-only --limit 20 --format json
+          example: npx -y agentera@next state todo list --severity critical --ids-only --limit 20 --format json
         docs:
           command_tokens: [docs]
           bare_read: correction
-          bare_recovery: agentera state docs list --limit 20 --format json
+          bare_recovery: npx -y agentera@next state docs list --limit 20 --format json
           filters:
             - { flag: --topic TEXT, name: topic, values: free_text }
             - { flag: --status STATUS, name: status, values: free_text }
-          example: agentera state docs list --limit 20 --format json
+          example: npx -y agentera@next state docs list --limit 20 --format json
     collections:
       - { artifact: progress, identity: id, classification: artifact }
       - { artifact: decisions, identity: id, classification: artifact }
@@ -384,7 +384,7 @@ entity_target:
       replay_equality: recursive_key_sorted_logical_content_with_array_order_preserved
       divergent_same_id: reject_without_overwrite
       state_validation:
-        canonical_command: agentera check validate state
+        canonical_command: npx -y agentera@next check validate state
         mutates: false
         failure_exit: nonzero
         diagnostics: bounded_structured_with_exact_recovery
@@ -420,8 +420,8 @@ entity_target:
           durability: persisted_in_each_new_progress_cycle_entity
           privacy: bounded_ordinal_without_time_identity_or_content
       retrieval:
-        exact: agentera state progress get --id ID --format json
-        list: agentera state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state progress get --id ID --format json
+        list: npx -y agentera@next state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: timestamp_desc_then_publication_order_desc_then_id_asc
         semantic_recency: >-
           The first full progress cycle is latest. Timestamp remains the public
@@ -491,8 +491,8 @@ entity_target:
             binds the complete parsed source record before canonical alias removal.
             Current confidence values and ordinary decision writes omit this metadata.
       retrieval:
-        exact: agentera state decisions get --id ID --format json
-        list: agentera state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state decisions get --id ID --format json
+        list: npx -y agentera@next state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -582,8 +582,8 @@ entity_target:
               Legacy canonical health audits omit appended_at and remain valid without
               reconstructed chronology.
       retrieval:
-        exact: agentera state health get --id ID --format json
-        list: agentera state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state health get --id ID --format json
+        list: npx -y agentera@next state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -595,7 +595,7 @@ entity_target:
       repair: >-
         Canonical health audit entities are immutable and cannot be row-deduplicated.
          Malformed envelopes, duplicate IDs, or conflicting ownership fail before effects
-          and recover through agentera check validate state; no repair event is fabricated.
+          and recover through `npx -y agentera@next check validate state`; no repair event is fabricated.
     - boundary: health_summary
       artifact: health
       independently_mutable: false
@@ -650,8 +650,8 @@ entity_target:
               syntactically indistinguishable from the legacy encoding and falls
               under this source-form rule; no semantic intent is inferred.
       retrieval:
-        exact: agentera state plan get --id ID --format json
-        list: agentera state plan list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state plan get --id ID --format json
+        list: npx -y agentera@next state plan list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: created_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -684,8 +684,8 @@ entity_target:
         required_paths: [header.title, header.status, objective.description, objective.measurement]
         forbidden_fields: [id, artifact, stable_id, objective_id]
       retrieval:
-        exact: agentera state objective get --id ID --format json
-        list: agentera state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state objective get --id ID --format json
+        list: npx -y agentera@next state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: created_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -709,8 +709,8 @@ entity_target:
         required_paths: [objective, date, label, status]
         forbidden_fields: [id, artifact, number, experiment_number, stable_id, objective_id]
       retrieval:
-        exact: agentera state experiments get --id ID --format json
-        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state experiments get --id ID --format json
+        list: npx -y agentera@next state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -756,6 +756,14 @@ entity_target:
           cardinality: zero_before_activation_then_exactly_one
           initial_match: exact_unique_public_fields_only
           retained_legacy_rows: bounded_section_and_exact_line_sha256_identities
+          effect_sha256: optional_for_legacy_cutover_required_for_explicit_activation
+          journal_authorization: >-
+            Explicit activation journals bind the preview effect SHA-256 into
+            transaction identity. Recovery validates that digest before target
+            effects. A completed explicit activation retains the same digest in
+            activation metadata so exact apply replay converges and unrelated
+            digests reject without effects; legacy activation accepts only its
+            current no-op preview digest.
           rule: >-
             The first reconciliation may assign a canonical ID only when one
             ID-less pre-activation row exactly matches one otherwise-unclaimed
@@ -835,8 +843,8 @@ entity_target:
           journal_utf8_bytes: 4194304
           todo_markdown_utf8_bytes: 1048576
       retrieval:
-        exact: agentera state todo get --id ID --format json
-        list: agentera state todo list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state todo get --id ID --format json
+        list: npx -y agentera@next state todo list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: severity_then_status_then_markdown_order_then_id
         default_limit: 20
         maximum_limit: 100
@@ -856,8 +864,8 @@ entity_target:
         required_paths: []
         forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
       retrieval:
-        exact: agentera state docs get --id ID --format json
-        list: agentera state docs list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        exact: npx -y agentera@next state docs get --id ID --format json
+        list: npx -y agentera@next state docs list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: path_then_id
         default_limit: 20
         maximum_limit: 100
@@ -1028,8 +1036,8 @@ entity_target:
             source_path: project-relative v2 aggregate source path
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
-          exact: agentera state progress get --id ID --format json
-          list: agentera state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+          exact: npx -y agentera@next state progress get --id ID --format json
+          list: npx -y agentera@next state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -1066,8 +1074,8 @@ entity_target:
             source_path: project-relative v2 aggregate source path
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
-          exact: agentera state decisions get --id ID --format json
-          list: agentera state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+          exact: npx -y agentera@next state decisions get --id ID --format json
+          list: npx -y agentera@next state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -1100,8 +1108,8 @@ entity_target:
             source_path: project-relative v2 aggregate source path
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
-          exact: agentera state health get --id ID --format json
-          list: agentera state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+          exact: npx -y agentera@next state health get --id ID --format json
+          list: npx -y agentera@next state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -1140,7 +1148,9 @@ entity_target:
         max_utf8_bytes: 32768
       startup_small:
         max_latency_ms: 5000
-        max_heap_delta_bytes: 67108864
+        # Retain margin for supported Node 22 peak-GC variance while keeping
+        # the small-startup ceiling at half the large-startup limit.
+        max_heap_delta_bytes: 134217728
         serialized_limits: budgets.startup.surfaces
       startup_large:
         max_latency_ms: 15000
@@ -1592,7 +1602,7 @@ historical_retrieval_evidence:
       bounds: count_1_to_100_and_serialized_utf8_budget
       cursor: opaque_snapshot_cursor
       omission: explicit_with_advancing_cursor_or_exact_get
-      get: agentera state progress get --id ID --format json
+      get: npx -y agentera@next state progress get --id ID --format json
     - collection_id: decisions.records
       artifact_id: decisions
       growth: immutable_base_and_revision_entities_with_replaceable_satisfaction_entity
@@ -1602,7 +1612,7 @@ historical_retrieval_evidence:
       bounds: count_1_to_100_and_serialized_utf8_budget
       cursor: opaque_snapshot_cursor
       omission: explicit_with_advancing_cursor_or_exact_get
-      get: agentera state decisions get --id ID --format json
+      get: npx -y agentera@next state decisions get --id ID --format json
     - collection_id: health.records
       artifact_id: health
       growth: append_only_unbounded
@@ -1612,7 +1622,7 @@ historical_retrieval_evidence:
       bounds: count_1_to_100_and_serialized_utf8_budget
       cursor: opaque_snapshot_cursor
       omission: explicit_with_advancing_cursor_or_exact_get
-      get: agentera state health get --id ID --format json
+      get: npx -y agentera@next state health get --id ID --format json
     - collection_id: plan.plans
       artifact_id: plan
       growth: one_active_plus_append_only_immutable_file_archives
@@ -1740,9 +1750,9 @@ consumer_matrix:
     - design
     - orchestrate
   access_contract:
-    startup: agentera prime --context <capability> --format json
-    list: agentera state <artifact-id> list --limit 20 --format json
-    get: agentera state <artifact> get --id ID --format json
+    startup: npx -y agentera@next prime --context <capability> --format json
+    list: npx -y agentera@next state <artifact-id> list --limit 20 --format json
+    get: npx -y agentera@next state <artifact> get --id ID --format json
     policy: >-
       Use the bounded prime context first, then the bounded state list for
       discovery and exact state get for requested detail. Raw artifact or Git
@@ -2109,7 +2119,7 @@ revisions:
     migration preview and cutover and is never a current publication target.
     Amend execution refuses before side effects for an unsafe target, duplicate
     same-base claim, or stale base hash. Discover the current contract with
-    `agentera state decisions explain --verb amend --format json`.
+    `npx -y agentera@next state decisions explain --verb amend --format json`.
 
 projections:
   archive:
@@ -2189,11 +2199,11 @@ api:
   artifact_syntax: agentera state <artifact-id>
   formats: [text, json, yaml]
   direct_get:
-    command: agentera state <artifact-id> get --id ID --format json
+    command: npx -y agentera@next state <artifact-id> get --id ID --format json
     examples:
-      progress: agentera state progress get --id qjtrmnpvka --format json
-      decisions: agentera state decisions get --id imumkmffwh --format json
-      health: agentera state health get --id abcdefghij --format json
+      progress: npx -y agentera@next state progress get --id qjtrmnpvka --format json
+      decisions: npx -y agentera@next state decisions get --id imumkmffwh --format json
+      health: npx -y agentera@next state health get --id abcdefghij --format json
     required_selector: --id ID
     result: >-
       One complete canonical entity record with id, artifact, detail availability,
@@ -2201,10 +2211,10 @@ api:
       compose immutable base, ordered revisions, and current satisfaction entities.
     exact_only: direct retrieval resolves one canonical entity ID without scanning unrelated records
   list:
-    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+    command: npx -y agentera@next state <artifact-id> list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
     examples:
-      progress: agentera state progress list --limit 20 --format json
-      decisions_next_page: agentera state decisions list --limit 20 --cursor TOKEN --format json
+      progress: npx -y agentera@next state progress list --limit 20 --format json
+      decisions_next_page: npx -y agentera@next state decisions list --limit 20 --cursor TOKEN --format json
     default_limit: 20
     minimum_limit: 1
     maximum_limit: 100
@@ -2218,7 +2228,7 @@ api:
       optional_entry: [summary, caveats]
     empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
   durability:
-    command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--id ID] [--limit N] --format json
+    command: npx -y agentera@next check durability [--project PATH] [--artifact ARTIFACT] [--id ID] [--limit N] --format json
     formats: [text, json, yaml]
     selectors:
       artifact: optional supported entity artifact ID
@@ -2242,9 +2252,9 @@ api:
       deterministic: >-
         With unchanged local files and reachable refs, repeated checks emit the
         same ordered result and do not create state or contact a remote.
-  entity_migration_discovery:
-    command: agentera state migrate entities --project PATH --dry-run --format json
-    implementation: implemented
+  entity_migration_upgrade:
+    command: npx -y agentera@next upgrade --channel development --project PATH --dry-run
+    implementation: upgrade_only
     read_only: true
     writes: forbidden
     authority: entity_migration.read_only_preview
@@ -2456,29 +2466,41 @@ budgets:
         max_heap_delta_bytes: 268435456
       serialized_output:
         # Generic prime capability capsules retain the full instructions body.
-        # The status capability is a separate one-call surface with a stricter
-        # bound declared below and in the JSON surface manifest.
+        # The status capability is the one bounded aggregation surface.
         prime_capability_context_max_utf8_bytes: 55000
-        prime_status_context_max_utf8_bytes: 25000
+        prime_status_context_max_utf8_bytes: 22500
+      aggregation:
+        schema_version: agentera.primeStartup.v1
+        outcome_values: [ok, degraded, blocked]
+        availability_row_fields: [family, availability, detail_command]
+        availability_values: [included, deferred]
+        detail_discovery: npx -y agentera@next schema --format json
+        single_projection_rule: >-
+          Prime emits one per-family availability projection at startup. Status
+          renders the same aggregate outcome without copying that projection.
+          A deferred row names its exact read command; it is not a second-call
+          requirement for an ok status startup.
+        writer_payloads: forbidden
     surfaces:
       prime_briefing:
         manifest_id: prime-briefing
         # Bounded default decision brief (Plan Task 3): the bare default
-        # `agentera prime --format json` projects the full orientation payload
+        # `npx -y agentera@next prime --format json` projects the full orientation payload
         # to routing-essential leaves plus named recovery pointers for omitted
         # rich state. Pretty UTF-8 JSON + trailing newline is measured and an
         # over-budget brief is rejected in favor of a bounded degraded envelope;
         # diagnostics stay on stderr. prime_dashboard keeps full current state
-        # while omitting duplicated ordinary history entries with recovery.
+        # while omitting duplicated ordinary history entries with recovery. The
+        # deprecated prime_dashboard alias emits the same status capsule.
         max_utf8_bytes: 12000
       prime_dashboard:
         manifest_id: prime-dashboard
-        max_utf8_bytes: 35000
+        max_utf8_bytes: 22500
       prime_status_context:
         manifest_id: prime-status-context
-        # Status startup includes the full instructions capsule as well as the
-        # bounded Task 3 decision brief. Diagnostics remain on stderr.
-        max_utf8_bytes: 25000
+        # Status startup includes its instructions and one bounded availability
+        # aggregation. Diagnostics remain on stderr.
+        max_utf8_bytes: 22500
       prime_sparse:
         manifest_id: prime-fields-sparse
         max_utf8_bytes: 28000
@@ -2527,8 +2549,8 @@ mutation_grammar:
         sources: [file, stdin]
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, publication_order]
-      recovery: Run agentera state progress explain --verb append --format json and correct the rejected field; no state was changed.
-      examples: ['agentera state progress append --input progress.yaml --format json']
+      recovery: Run `npx -y agentera@next state progress explain --verb append --format json` and correct the rejected field; no state was changed.
+      examples: ['npx -y agentera@next state progress append --input progress.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       compacts: true
       fields: []
@@ -2545,8 +2567,8 @@ mutation_grammar:
         sources: [file, stdin]
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact]
-      recovery: Run agentera state decisions explain --verb append --format json and supply every required field; no state was changed.
-      examples: ['agentera state decisions append --input decision.yaml --format json']
+      recovery: Run `npx -y agentera@next state decisions explain --verb append --format json` and supply every required field; no state was changed.
+      examples: ['npx -y agentera@next state decisions append --input decision.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       compacts: true
       fields: []
@@ -2558,8 +2580,8 @@ mutation_grammar:
       preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, satisfaction_state_is_valid]
       owned_fields: [id, artifact, satisfaction]
       input: { mode: none, sources: [], cli_owned_fields: [] }
-      recovery: Run agentera state decisions explain --verb update --format json, use the returned bare decision ID, and provide a valid satisfaction transition.
-      examples: ['agentera state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence "..." --format json']
+      recovery: Run npx -y agentera@next state decisions explain --verb update --format json, use the returned bare decision ID, and provide a valid satisfaction transition.
+      examples: ['npx -y agentera@next state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence "..." --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2581,7 +2603,7 @@ mutation_grammar:
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, base_sha256]
       recovery: Reread the exact decision, copy its current effective SHA-256, and retry with at least one amendable field; no state was changed.
-      examples: ['agentera state decisions amend --id qjtrmnpvka --base-sha256 HASH --input amendment.yaml --format json']
+      examples: ['npx -y agentera@next state decisions amend --id qjtrmnpvka --base-sha256 HASH --input amendment.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2599,8 +2621,8 @@ mutation_grammar:
         sources: [file, stdin]
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
-      recovery: Use agentera state plan explain --verb append --format json, select an open plan, and supply one complete task record with bare same-plan dependencies.
-      examples: ['agentera state plan append --plan qjtrmnpvka --input task.yaml --format json']
+      recovery: Use npx -y agentera@next state plan explain --verb append --format json, select an open plan, and supply one complete task record with bare same-plan dependencies.
+      examples: ['npx -y agentera@next state plan append --plan qjtrmnpvka --input task.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields:
          - { flag: --plan, field: plan, kind: string }
@@ -2618,7 +2640,7 @@ mutation_grammar:
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
       recovery: Reread the plan task by its bare ID, supply an omission-preserving patch through --input, and retry; no state was changed.
-      examples: ['agentera state plan update --id qjtrmnpvka --plan abcdefghij --input task-patch.yaml --format json']
+      examples: ['npx -y agentera@next state plan update --id qjtrmnpvka --plan abcdefghij --input task-patch.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields:
          - { flag: --id, field: id, kind: string, required: true }
@@ -2632,7 +2654,7 @@ mutation_grammar:
       owned_fields: [id, artifact, plan, status]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Reread the task list, copy its bare task ID, and use one of complete, in_progress, pending, or blocked.
-      examples: ['agentera state plan set-status --id qjtrmnpvka --status complete --format json']
+      examples: ['npx -y agentera@next state plan set-status --id qjtrmnpvka --status complete --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2647,7 +2669,7 @@ mutation_grammar:
       owned_fields: [id, artifact, plan, superseded_by, superseded_reason]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Complete and evaluate each replacement task with latest PASS evidence, then retry with the returned bare IDs.
-      examples: ['agentera state plan supersede --id qjtrmnpvka --by zqtrmnpvka --reason "Replacement task" --format json']
+      examples: ['npx -y agentera@next state plan supersede --id qjtrmnpvka --by zqtrmnpvka --reason "Replacement task" --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 100, max_reason_code_points: 500 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2663,7 +2685,7 @@ mutation_grammar:
       owned_fields: [id, artifact, plan, header.status]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Keep the plan open or resolve every incomplete task and replacement evaluation before retrying completion.
-      examples: ['agentera state plan set-plan-status --status complete --format json']
+      examples: ['npx -y agentera@next state plan set-plan-status --status complete --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
       fields:
         - { flag: --plan, field: plan, kind: string }
@@ -2677,7 +2699,7 @@ mutation_grammar:
       owned_fields: [id, artifact, plan, evaluation]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Use the task's bare ID, a stable attempt ID, and evaluator provenance, then retry without changing published evidence.
-      examples: ['agentera state plan record-evaluation --id qjtrmnpvka --attempt-id audit-1 --verdict pass --provenance "audit report" --format json']
+      examples: ['npx -y agentera@next state plan record-evaluation --id qjtrmnpvka --attempt-id audit-1 --verdict pass --provenance "audit report" --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2695,7 +2717,7 @@ mutation_grammar:
       owned_fields: [id, artifact, plan, header.status]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Complete or preserve the selected plan, then retry archive with no content flags; no state was changed.
-      examples: ['agentera state plan archive --dry-run --format json']
+      examples: ['npx -y agentera@next state plan archive --dry-run --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
       allow_force: true
       fields: [{ flag: --plan, field: plan, kind: string }]
@@ -2711,8 +2733,8 @@ mutation_grammar:
         root: complete plan document
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
-      recovery: Run agentera state plan explain --verb create --format json, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and correct the first schema or dependency violation.
-      examples: ['agentera state plan create --input plan.yaml --format json']
+      recovery: Run npx -y agentera@next state plan explain --verb create --format json, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and correct the first schema or dependency violation.
+      examples: ['npx -y agentera@next state plan create --input plan.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       allow_force: true
       fields: []
@@ -2728,8 +2750,8 @@ mutation_grammar:
         root: one audit entry
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, appended_at]
-      recovery: Run agentera check validate state --format json, preserve audit evidence, and retry with one schema-valid audit entry.
-      examples: ['agentera state health append --input audit.yaml --format json']
+      recovery: Run npx -y agentera@next check validate state --format json, preserve audit evidence, and retry with one schema-valid audit entry.
+      examples: ['npx -y agentera@next state health append --input audit.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       compacts: true
       fields: []
@@ -2746,7 +2768,7 @@ mutation_grammar:
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, header.id]
       recovery: Remove identity fields assigned by the CLI and retry with one schema-valid objective document.
-      examples: ['agentera state objective create --input objective.yaml --format json']
+      examples: ['npx -y agentera@next state objective create --input objective.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields: []
 
@@ -2762,7 +2784,7 @@ mutation_grammar:
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, header.id]
       recovery: Reread the objective, copy its bare ID to --id, remove CLI-owned fields, and retry.
-      examples: ['agentera state objective update --id qjtrmnpvka --input objective.yaml --format json']
+      examples: ['npx -y agentera@next state objective update --id qjtrmnpvka --input objective.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields: [{ flag: --id, field: id, kind: string, required: true }]
 
@@ -2778,13 +2800,43 @@ mutation_grammar:
         sources: [file, stdin]
         cli_owned_fields: [id, artifact, objective]
       recovery: Use a bare objective ID, omit numeric legacy selectors, and retry the exact input; divergent immutable identities remain untouched.
-      examples: ['agentera state experiments publish --objective qjtrmnpvka --input experiment.yaml --format json']
+      examples: ['npx -y agentera@next state experiments publish --objective qjtrmnpvka --input experiment.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       compacts: true
       fields:
         - { flag: --objective, field: objective, kind: string, required: true }
         - { flag: --id, field: id, kind: string }
 
+    - artifact: todo
+      verb: activate
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, activation_is_absent_or_replay, todo_reconciliation_is_valid, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Preview and review every reported activation effect before explicit confirmed apply; use the returned examples without modification.
+      examples: ['npx -y agentera@next state todo activate --dry-run --format json', 'npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: repair
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, activation_is_present, complete_one_to_one_repair_evidence_is_valid, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Preview and review every diagnosed repair decision before explicit confirmed apply; ambiguous evidence is rejected without effects.
+      examples: ['npx -y agentera@next state todo repair --dry-run --format json', 'npx -y agentera@next state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
     - artifact: todo
       verb: create
       class: record_payload
@@ -2797,8 +2849,8 @@ mutation_grammar:
         sources: [file, stdin]
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, status, public_order, lifecycle]
-      recovery: Run agentera state todo explain --verb create --format json, remove CLI-owned fields, provide the full typed TODO record, and retry.
-      examples: ['agentera state todo create --input todo.yaml --format json']
+      recovery: Run npx -y agentera@next state todo explain --verb create --format json, remove CLI-owned fields, provide the full typed TODO record, and retry.
+      examples: ['npx -y agentera@next state todo create --input todo.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       fields: []
 
@@ -2815,7 +2867,7 @@ mutation_grammar:
         structured_sources: [file, stdin]
         cli_owned_fields: [id, artifact, status, public_order, lifecycle]
       recovery: Reread the TODO item, use its bare ID, supply only typed patch fields, and use null or an empty list only for declared clearable fields.
-      examples: ['agentera state todo update --id qjtrmnpvka --input todo-patch.yaml --format json']
+      examples: ['npx -y agentera@next state todo update --id qjtrmnpvka --input todo-patch.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields: [{ flag: --id, field: id, kind: string, required: true }]
 
@@ -2827,7 +2879,7 @@ mutation_grammar:
       owned_fields: [id, artifact, severity, lifecycle]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Use the bare TODO ID, one immediate-impact severity, a reason, and a YYYY-MM-DD date; no record input is accepted.
-      examples: ['agentera state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json']
+      examples: ['npx -y agentera@next state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2843,7 +2895,7 @@ mutation_grammar:
       owned_fields: [id, artifact, status, lifecycle]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Use the selected bare TODO ID, an existing distinct replacement ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
-      examples: ['agentera state todo supersede --id qjtrmnpvka --replacement zqtrmnpvka --reason "Replaced by narrower work" --date 2026-07-31 --format json']
+      examples: ['npx -y agentera@next state todo supersede --id qjtrmnpvka --replacement zqtrmnpvka --reason "Replaced by narrower work" --date 2026-07-31 --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2859,7 +2911,7 @@ mutation_grammar:
       owned_fields: [id, artifact, status, lifecycle]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Use the bare TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
-      examples: ['agentera state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json']
+      examples: ['npx -y agentera@next state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2874,7 +2926,7 @@ mutation_grammar:
       owned_fields: [id, artifact, status, lifecycle]
       input: { mode: none, sources: [], cli_owned_fields: [] }
       recovery: Use the bare resolved TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
-      examples: ['agentera state todo reopen --id qjtrmnpvka --reason "Scope returned" --date 2026-07-31 --format json']
+      examples: ['npx -y agentera@next state todo reopen --id qjtrmnpvka --reason "Scope returned" --date 2026-07-31 --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
       fields:
         - { flag: --id, field: id, kind: string, required: true }
@@ -2893,7 +2945,7 @@ mutation_grammar:
         sources: [file, stdin]
         cli_owned_fields: [id, artifact]
       recovery: Remove id and artifact from the input and retry with one schema-valid documentation inventory entry.
-      examples: ['agentera state docs create --input documentation.yaml --format json']
+      examples: ['npx -y agentera@next state docs create --input documentation.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
       fields: []
 
@@ -2909,7 +2961,7 @@ mutation_grammar:
         sources: [file, stdin]
         cli_owned_fields: [id, artifact]
       recovery: Reread the documentation entry, copy its bare ID to --id, remove CLI-owned fields, and retry.
-      examples: ['agentera state docs update --id qjtrmnpvka --input documentation.yaml --format json']
+      examples: ['npx -y agentera@next state docs update --id qjtrmnpvka --input documentation.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields: [{ flag: --id, field: id, kind: string, required: true }]
 
@@ -2924,7 +2976,7 @@ mutation_grammar:
         root: one glossary publication request
         sources: [file, stdin]
         cli_owned_fields: []
-      recovery: Run agentera state glossary explain --verb publish --format json and correct the bounded request or confirmation.
-      examples: ['agentera state glossary publish --input glossary-publication.yaml --format json']
+      recovery: Run npx -y agentera@next state glossary explain --verb publish --format json and correct the bounded request or confirmation.
+      examples: ['npx -y agentera@next state glossary publish --input glossary-publication.yaml --format json']
       bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
       fields: []