agentera 3.0.0-dev.3 → 3.0.0-dev.5

package/README.md

@@ -1,9 +1,42 @@
-# Agentera CLI (v3)
+# Agentera CLI (npm)
 
-Placeholder for the planned TypeScript CLI rewrite.
+Native TypeScript CLI for Agentera 3.x, published as [`agentera`](https://www.npmjs.com/package/agentera).
 
-The current Python CLI lives at `scripts/agentera` in the repository root.
-This package will eventually host the v3 TypeScript implementation.
+| Dist tag | Channel | Use for |
+| --- | --- | --- |
+| `@latest` | stable (2.x) | Supported production line |
+| `@next` | development (3.x pre-releases) | Early testing of the self-contained npm CLI |
 
-See the [Agentera repository](https://github.com/jgabor/agentera) for the
-current CLI documentation and usage.
+## Quick start
+
+```bash
+npx -y agentera@next prime --format json
+npx -y agentera@next upgrade --dry-run --channel development
+```
+
+Run those from a project root. `prime` reports `project_integration.recommendation`
+(`stay` or `upgrade`) and suggested commands for the current repo.
+
+Full preview instructions, highlights, and migration paths:
+[repository README — Agentera 3.0 preview](../../README.md#agentera-30-preview).
+
+Upgrade channels and v2→v3 opt-in: [`UPGRADE.md`](../../UPGRADE.md).
+
+## Package layout
+
+- `dist/` — compiled CLI (`agentera` bin)
+- `bundle/` — shipped app data (`skills/`, `references/`, `registry.json`)
+
+Requires Node.js 22+.
+
+## Contributors
+
+Build and test from the monorepo:
+
+```bash
+pnpm -C packages/cli build
+pnpm -C packages/cli test
+pnpm -C packages/cli run publish:dev   # publishes with @next tag
+```
+
+See [`AGENTS.md`](../../AGENTS.md) for capability validation and commit conventions.

package/bundle/.agentera-npx-bundle.json

@@ -1,4 +1,4 @@
 {
   "kind": "agentera-npx-bundle",
-  "suiteVersion": "2.7.6"
+  "suiteVersion": "3.0.0"
 }

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -282,10 +282,10 @@ structured_output:
             contract can summarize planning levels, step markers, CLI-first
             orientation, raw plan artifact boundaries, full-plan review/self-audit
             requirements, handoff expectations, and the Planera prose authority
-            boundary without reading `planera/instructions.md` at runtime. It must
-            not introduce `agentera planera`, new top-level commands, or hidden
-            capability-name aliases; `agentera schema` owns runtime/schema
-            introspection rather than a capability workflow payload.
+            boundary without reading `packages/cli/src/capabilities/planera/instructions.ts`
+            at runtime. It must not introduce `agentera planera`, new top-level
+            commands, or hidden capability-name aliases; `agentera schema` owns
+            runtime/schema introspection rather than a capability workflow payload.
           orchestration_context_semantics: >-
             `agentera prime --context orkestrera --format json` may include
             orchestration_context with dependency-ready tasks, blocked task reasons,
@@ -465,7 +465,7 @@ evidence_context_target_contract:
         verified_field: header.status=complete
       - reason: Inspektera prose and schemas are validated directly; complete evidence_context covers normal evaluation startup without raw plan/progress/docs/health/TODO/decisions reads.
         paths:
-          - skills/agentera/capabilities/inspektera/instructions.md
+          - packages/cli/src/capabilities/inspektera/instructions.ts
           - skills/agentera/capabilities/inspektera/schemas/artifacts.yaml
           - skills/agentera/capabilities/inspektera/schemas/validation.yaml
         raw_artifact_reads_required_for_startup: false
@@ -755,11 +755,13 @@ verify_namespace:
   rejected_umbrella_command: smoke
   purpose: >-
     Define the supported `agentera verify` namespace so agents can run or inspect
-    smoke and eval gates through one discoverable verification surface without
-    guessing direct script names or unsupported capability-name CLI commands.
+    eval gates through one discoverable verification surface without guessing direct
+    script names or unsupported capability-name CLI commands.
   namespace_rationale: >-
     `agentera verify` is the public command for the evaluation gates (skills and
-    semantic). The smoke-check family was retired in the self-contained package.
+    semantic) on the npm self-contained CLI. The smoke-check family is retired on
+    @next; run smoke maintainer harnesses on the stable Python line with
+    `uvx --from git+https://github.com/jgabor/agentera@main agentera check verify smoke installed-skills`.
   command_shape: agentera verify <family> <target> [--format text|json] [target options]
   supported_gate_families:
     eval:
@@ -810,9 +812,11 @@ verify_namespace:
       - skipped
   invalid_input_behavior:
     family_error: >-
-      Unknown verify families must exit nonzero, list valid families `smoke` and
-      `eval`, show `agentera verify <family> <target> [--format text|json]`, and
-      include concrete examples for one smoke target and one eval target.
+      Unknown verify families must exit nonzero, list valid family `eval`, show
+      `agentera verify <family> <target> [--format text|json]`, and include a
+      concrete eval example. Requests for the retired `smoke` family must exit
+      nonzero with explicit npm-retired guidance pointing to eval verify or the
+      stable Python maintainer path.
     target_error: >-
       Unknown targets must exit nonzero, list valid targets for the selected family,
       show the correct family syntax, and include one concrete example for that family.
@@ -831,18 +835,17 @@ verify_namespace:
     - >-
       `agentera verify eval semantic` remains callable directly with fixture path arguments
       and existing offline semantic fixture behavior.
-      offline default behavior plus the explicit `--real-npx` opt-in path.
-      default behavior and explicit `--live`/`--yes` live-host opt-in behavior.
-      observable smoke-check behavior, including current non-argparse `--help` behavior.
-      observable local bootstrap diagnostics and failure behavior.
+    - >-
+      Retired `smoke` verify requests on the npm self-contained CLI must fail with
+      bounded guidance instead of invoking Python smoke harnesses.
   non_goals:
     - Do not add unsupported capability-name CLI commands such as `agentera realisera` or `agentera orkestrera`.
     - Do not reintroduce the retired smoke gate-family.
     - Do not implement D48 `validate`, `corpus`, or `usage` work.
     - Do not run live network, installed-app mutation, profile refresh, publication, push, tag, or package-update flows as part of this contract definition.
   evidence_sources:
-    - agentera --help exposes the `verify` namespace and safe smoke/eval examples.
-    - the verify vitest tests (packages/cli/test/cli/verify.test.ts) covers smoke success, eval success, text output, JSON output, invalid input feedback, safety boundaries, and preserved direct-script compatibility.
+    - agentera --help exposes the `verify` namespace and eval examples only on npm @next.
+    - the verify vitest tests (packages/cli/test/cli/verify.test.ts) cover eval success, smoke retirement, text output, JSON output, invalid input feedback, safety boundaries, and preserved direct-script compatibility.
     - agentera verify eval skills --help defines `--skill`, `--dry-run`, `--parallel`, `--timeout`, and `--runtime`.
     - agentera verify eval semantic --help defines fixture path inputs for offline semantic evaluation.
 usage_namespace:

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

@@ -194,7 +194,7 @@ focused_scan:
     - (retired maintainer measurement tool)
     - skills/agentera/SKILL.md
     - skills/agentera/capabilities/hej/schemas/triggers.yaml
-    - skills/agentera/capabilities/resonera/instructions.md
+    - packages/cli/src/capabilities/resonera/instructions.ts
     - tests/test_cross_capability.py
     - tests/test_resonera_capability.py
     - tests/test_runtime_adapters.py

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

@@ -3,9 +3,10 @@ status: active_authority
 decision: 57
 purpose: >-
   Define the Decision 57 capability instruction-file contract: the canonical
-  `instructions.md` file name, implemented CLI/schema first-invocation read
-  discoverability, compact-startup exception boundaries, and runtime behavior
-  that remains intentionally unsupported.
+  `instructions.ts` module path, implemented CLI/schema first-invocation read
+  discoverability, the `prime_context` runtime-enforcement boundary, and
+  retirement of the historical `full`/`compact_startup`/`skip` values
+  superseded by Decision 65.
 sources:
   decision: .agentera/decisions.yaml#decision-57
   prose:
@@ -13,91 +14,87 @@ sources:
     - README.md#development
 scope:
   includes:
-    - Documentation authority for the implemented capability instruction-file name.
+    - Documentation authority for the implemented capability instruction module path.
     - CLI/schema discoverability for first capability invocation startup-read metadata.
-    - Compact-startup exception semantics and boundaries.
-    - Current canonical references to existing `instructions.md` files.
+    - The single `prime_context` first-invocation shape enforced by the runtime.
+    - Current canonical references to existing `instructions.ts` modules.
     - Explicit separation from runtime behavior work.
   excludes:
     - Implementing first-invocation read behavior.
     - Marking Decision 57 satisfied or editing protected vision/objective/profile/installed-app state.
 current_state:
   canonical_instruction_file:
-    path: skills/agentera/capabilities/<name>/instructions.md
+    path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_canonical_implemented
     definition: >-
-      The human-readable instruction file for each capability.
+      The TypeScript module that exports the capability's behavioral
+      instructions as a default-exported string constant. The runtime loads
+      the compiled .js path and serves the prose through the slim
+      `capability_context` capsule's `prose` field.
   legacy_instruction_file:
+    path: skills/agentera/capabilities/<name>/instructions.md
+    status: historical_or_compatibility_evidence_only
+    definition: >-
+      The pre-D65 Markdown instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
+  legacy_prose_file:
     path: skills/agentera/capabilities/<name>/prose.md
     status: historical_or_compatibility_evidence_only
     definition: >-
-      The former capability instruction filename. It may survive only in archived
-      history, compatibility fixtures, benchmark evidence, or explicit migration
-      documentation; real capability directories do not use it as canonical.
+      The pre-D57 capability instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
   validator_requirement:
-    current_required_path: instructions.md
-    future_required_path: instructions.md
+    current_required_path: packages/cli/src/capabilities/<name>/instructions.ts
+    future_required_path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_requirement_enforced
   cli_metadata:
     field: first_invocation_read
     status: emitted_in_prime_capability_context
     current_behavior: >-
       `agentera prime --context <name> --format json` emits
-      `capability_context` metadata including `first_invocation_read` for
-      supported capabilities. Historical `hej --capability-context` is removed in 3.0.
+      `capability_context` metadata including `first_invocation_read`
+      (value: `prime_context`, runtime_enforcement: true) and the full prose
+      in the `prose` field for supported capabilities. Historical
+      `hej --capability-context` is removed in 3.0.
 first_invocation_read:
-  field_status: cli_schema_discoverability_implemented
+  field_status: runtime_enforced
   definition: >-
-    Capability metadata declaring what instruction content an agent must read on
-    the first invocation of that capability in a session.
+    Capability metadata declaring what instruction content an agent must
+    read on the first invocation of that capability in a session. Decision
+    65 collapses the legacy `full`/`compact_startup` distinction into a
+    single `prime_context` value because the CLI now owns the prose and
+    the runtime can mechanically shell out to the prime command.
   allowed_values:
-    full:
-      meaning: >-
-        The first capability invocation must read `instructions.md` in full before
-        executing capability-specific work.
-      obligation: full_instruction_file_read_required
-    compact_startup:
-      meaning: >-
-        A declared compact startup contract may satisfy initial orientation without
-        reading the full instruction file first.
-      obligation: compact_contract_must_name_covered_guidance_and_escalation_rules
-    skip:
+    prime_context:
       meaning: >-
-        No first-invocation instruction read is required for the declared scope.
-      obligation: requires_explicit_contract_justification
-      caution: >-
-        Reserved for narrow future surfaces; not a default and not implemented by
-        this authority.
-  default_rule: full
+        The first capability invocation must shell out to
+        `agentera prime --context <name> --format json` and read the
+        returned `prose` field (the full Markdown body) before executing
+        capability-specific work.
+      obligation: shell out to agentera prime --context <name> --format json
+  default_rule: prime_context
   full_read_obligation: >-
-    On initial capability invocation, read `instructions.md` in full unless that
-    capability declares a compact-startup exception with explicit coverage and
-    escalation boundaries.
-compact_startup_exception:
-  status: implemented_for_planera_compact_startup_discoverability
-  allowed_when:
-    - A machine-readable startup contract is available through supported state access.
-    - The compact contract states which instruction topics it covers.
-    - The compact contract states when the agent must escalate to a full instruction-file read.
-    - The compact contract preserves unsupported-command and raw-artifact-read boundaries.
-  not_allowed_when:
-    - The agent is editing the capability's own instructions or schemas.
-    - The compact contract is missing, incomplete, stale, or contradictory.
-    - The requested work touches behavior not covered by the compact contract.
-    - Safety rails, validation, exit semantics, or cross-capability boundaries are ambiguous.
+    On initial capability invocation, shell out to
+    `agentera prime --context <name> --format json` and read the
+    `capability_context.prose` field in full.
 implementation_state:
-  instructions_md_files: renamed
-  validators_require_instructions_md: true
+  instructions_ts_modules: implemented
+  validators_require_instructions_ts: true
   first_invocation_read_cli_metadata: true
   first_invocation_read_schema_metadata: true
-  runtime_first_invocation_behavior: false
-  descriptors_rewritten_to_instructions_md: true
-  package_metadata_rewritten_to_instructions_md: true
+  runtime_first_invocation_behavior: true
+  descriptors_rewritten_to_prime_command: true
+  package_metadata_rewritten_to_prime_command: true
 compatibility_preservation:
   preserve_legacy_references_only_when_classified:
-    - skills/agentera/capabilities/*/instructions.md paths
+    - skills/agentera/capabilities/*/instructions.md paths (historical)
+    - packages/cli/src/capabilities/*/instructions.ts paths (current canonical)
     - skills/agentera/capability_schema_contract.yaml directory requirements
-    - runtime descriptors and generated agent guidance that point to `instructions.md`
+    - runtime descriptors and generated agent guidance that point to `instructions.md` (retired)
     - archived v1/v2 migration records and progress evidence
     - compatibility fixtures and tests that intentionally preserve old behavior evidence
     - README, AGENTS, and vocabulary references that explicitly describe the current canonical state
@@ -116,6 +113,50 @@ surface_inventory:
   capability_schema_contract: current_canonical_validator_reference
   runtime_descriptors: current_canonical_instructions_md_pointers
   capability_instruction_files: current_canonical_instruction_files
+evaluator_handoff:
+  status: implemented
+  purpose: >-
+    Define the inspektera evaluation report schema and citation requirements
+    for orkestrera Step 3 Surface 2 delegations and post-plan health checks.
+  report_schema_version: agentera.inspekteraEvaluationReport.v1
+  row_schema:
+    required_fields:
+      - criterion
+      - status
+      - evidence
+    status_values:
+      - PASS
+      - WARN
+      - FAIL
+    citation_required_for:
+      - WARN
+      - FAIL
+    citation_formats:
+      file_line:
+        pattern: "^[^:\\s]+:\\d+$"
+        description: Relative repo path with 1-based line number, e.g. TODO.md:15
+      not_applicable:
+        prefix: "not-applicable:"
+        min_reason_length: 8
+        description: >-
+          Use when no file anchor exists; prefix with not-applicable: and give a
+          concrete reason (at least 8 characters after the prefix).
+    warn_verify_command:
+      required_when: file_line_citation
+      allowed_prefixes:
+        - grep
+        - git show
+      description: >-
+        WARN rows with a file:line citation MUST include verify_command with the
+        exact grep or git show invocation that reproduces the evidence at the
+        cited line.
+  orchestration_context_fields:
+    output_requirements:
+      citation_required_for:
+        - WARN
+        - FAIL
+      warn_verify_command_required: true
+      schema_authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff
 docs_delegation:
   document: references/cli/vocabulary.md
   required_anchor: Capability instruction contract

package/bundle/references/cli/routing-execution-vocabulary.yaml

@@ -171,9 +171,9 @@ focused_scan:
     - (retired maintainer measurement tool)
     - skills/agentera/SKILL.md
     - skills/agentera/references/contract.md
-    - skills/agentera/capabilities/realisera/instructions.md
-    - skills/agentera/capabilities/optimera/instructions.md
-    - skills/agentera/capabilities/orkestrera/instructions.md
+    - packages/cli/src/capabilities/realisera/instructions.ts
+    - packages/cli/src/capabilities/optimera/instructions.ts
+    - packages/cli/src/capabilities/orkestrera/instructions.ts
     - tests/test_skill_dispatch_contract.py
     - tests/test_runtime_adapters.py
     - tests/test_runtime_adapter_registry.py
@@ -222,15 +222,15 @@ focused_scan:
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: The contract preserves the parseable historical checkpoint commit message string.
-    - path: ^skills/agentera/capabilities/realisera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/realisera/instructions\.ts$
       text: 'Step 5: Dispatch|checkpoint before worktree dispatch'
       classification: compatibility-preserved
       reason: Realisera preserves the current step heading and checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/optimera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/optimera/instructions\.ts$
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: Optimera preserves the current checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/orkestrera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/orkestrera/instructions\.ts$
       text: review pressure in dispatch|dispatch/evaluation context|`dispatch` and `chain` are autonomous orchestration verbs
       classification: canonical
       reason: Orkestrera capability prose uses dispatch for its explicitly owned orchestration loop.

package/bundle/references/cli/update-channels.yaml

@@ -10,12 +10,13 @@ sources:
 scope:
   includes:
     - Channel names, default selection, and resolution precedence.
-    - npm dist-tag and git ref resolution per channel.
+    - npm dist-tag resolution per channel and git ref resolution for the stable line only.
     - Environment, config, and CLI override keys.
   excludes:
     - App lifecycle canonical statuses and operation verb definitions.
     - Migration orchestration phases, apply semantics, and compatibility detection.
     - Package publication, dist-tag retirement, and release approval decisions.
+    - uv/git install paths for the development (3.x) channel; feat/v3 is TS-only on npm.
 compatibility_boundary: >-
   Stable channel must continue resolving to 2.x until an explicit release decision
   retires it. Cross-major v2→v3 migration is never implied by default channel
@@ -32,6 +33,21 @@ channels:
       Tracks the supported 2.x release line for users who must not cross the v2→v3
       major boundary without explicit opt-in.
     distribution_major: 2
+    next_major:
+      concept: forward_successor_line
+      channel: development
+      version: "3.0.0"
+      npm:
+        dist_tag: next
+      npm_only_advisory: >-
+        The successor line is npm-only; stable git/uvx installs remain on the
+        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
+      irreversible_advisory: >-
+        Forward migration to the successor line is one-way; return to the prior
+        Python support line is permanently unsupported.
     resolution:
       npm:
         dist_tag: latest
@@ -43,16 +59,20 @@ channels:
     concept: v3_pre_release_line
     definition: >-
       Tracks 3.x alphas, betas, and release candidates for early adopters and
-      maintainers testing the npm self-contained distribution.
+      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.
     distribution_major: 3
     resolution:
       npm:
         dist_tag: next
         update_command: npx -y agentera@next
       git:
-        ref: feat/v3
-        update_command: >-
-          uvx --from git+https://github.com/jgabor/agentera@feat/v3 agentera
+        supported: false
+        reason: >-
+          feat/v3 has no Python packaging; development-channel CLI delivery is
+          npm-only. Stable-channel git/uvx remains the Python 2.x maintainer path
+          on @main.
 override_precedence:
   - cli_flag
   - env_var
@@ -122,8 +142,8 @@ version_resolution:
   latest_on_channel:
     resolver: npm_dist_tag_with_offline_defaults
     offline_defaults:
-      stable: "2.7.6"
-      development: "3.0.0-dev.3"
+      stable: "2.7.7"
+      development: "3.0.0"
   irreversibility:
     downgrade_to_v2: permanently_blocked
     supported_downgrade_lines: []

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

@@ -18,7 +18,7 @@ authority_order:
   - references/cli/capability-instruction-contract.yaml
   - references/cli/routing-execution-vocabulary.yaml
   - skills/agentera/SKILL.md
-  - skills/agentera/capabilities/*/instructions.md
+  - packages/cli/src/capabilities/*/instructions.ts
   - the agentera CLI
   - packages/cli/src/upgrade (doctor/upgrade)
   - README.md
@@ -62,8 +62,8 @@ normalization_rules:
   - rule: Worker safety commits are Git-only.
     use: pre-spawn Git commit
     avoid: Non-Git checkpoint or pre-dispatch commit gate in new docs.
-  - rule: Capability instruction files have current metadata and a runtime boundary.
-    use: instructions.md plus emitted first_invocation_read; runtime enforcement remains false
+  - rule: Capability instruction modules have current metadata and a runtime boundary.
+    use: instructions.ts plus emitted prime_context first_invocation_read; runtime enforcement is true via the CLI prime command
     avoid: Claiming agents are policed for actual reads, or adding unsupported agentera planera commands.
 plain_language:
   lead_with_plain_phrase:

package/bundle/references/cli/vocabulary.md

@@ -20,10 +20,10 @@ included when they shape cross-suite usage.
 | `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 `instructions.md` authority, and implemented `first_invocation_read` CLI/schema discoverability. |
+| `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. |
-| `skills/agentera/capabilities/*/instructions.md` | Capability behavior, workflow grammar, step markers, and cross-capability boundaries. |
+| `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`. |
 | `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. |
 
@@ -54,7 +54,7 @@ examples. Diagnostics should state object, state, cause, and fix.
 | Agentera | The open protocol for turning AI agents into engineering teams through shared project state, roles, decisions, and verification. | `README.md`, `.agentera/vision.yaml`, `skills/agentera/SKILL.md` |
 | Agentera v2 | The current architecture: one Agentera skill, one `/agentera` entry point, twelve capabilities, YAML project state, and CLI-first access. | `README.md`, `UPGRADE.md`, `.agentera/decisions.yaml` |
 | Agentera skill | The runtime-loaded Agentera skill at `skills/agentera/`. It contains the routing entry and twelve capabilities. | `skills/agentera/SKILL.md` |
-| Capability | A routed behavioral unit inside the Agentera skill, with `instructions.md` plus `triggers.yaml`, `artifacts.yaml`, `validation.yaml`, and `exit.yaml`. | `AGENTS.md`, `skills/agentera/capabilities/*` |
+| Capability | A routed behavioral unit inside the Agentera skill, with the prose module `packages/cli/src/capabilities/<name>/instructions.ts` plus `triggers.yaml`, `artifacts.yaml`, `validation.yaml`, and `exit.yaml`. | `AGENTS.md`, `skills/agentera/capabilities/*`, `packages/cli/src/capabilities/*` |
 | Shared protocol | The 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` |
@@ -87,21 +87,26 @@ Capability names use Swedish-style `-era` verb forms. The name is the action:
 
 The machine-readable authority is
 `references/cli/capability-instruction-contract.yaml`; it owns Decision 57's
-instruction-file boundary, including the canonical `instructions.md` file,
-legacy `prose.md` compatibility boundaries, implemented `first_invocation_read` values,
-full-read obligations, compact-startup exceptions, and unsupported runtime
-enforcement states.
-
-Use this prose as guidance only: the default is that initial capability invocation
-reads `instructions.md` in full unless an explicit compact-startup exception is
-declared. Today, capability files and runtime descriptors use `instructions.md`,
-validators require `instructions.md`, and `agentera hej --format json
---capability-context <name>` emits `source_contract.capability_context.first_invocation_read`.
+instruction-file boundary, including the canonical `instructions.ts` module,
+legacy `prose.md` and `instructions.md` compatibility boundaries, the
+implemented `first_invocation_read: prime_context` value, the
+`prime --context <name> --format json` ownership statement, and the runtime
+enforcement boundary promoted to `true` in D65.
+
+Use this prose as guidance only: the default is that the first capability
+invocation shells out to `agentera prime --context <name> --format json` and
+reads the returned `prose` field. Today, capability directories carry the
+`schemas/` files only, the prose module lives at
+`packages/cli/src/capabilities/<name>/instructions.ts`, runtime descriptors
+invoke the prime command, and the `agentera prime --context <name> --format
+json` response emits `capability_context.prose` plus
+`first_invocation_read` metadata.
 
 Do not replace this with a parallel Markdown table of read modes or migration
 surfaces. Update the YAML authority first, then keep this section as the short
-human-facing boundary. Runtime first-invocation read behavior and broad
-required-read validation regression remain separate follow-up work.
+human-facing boundary. The `prime_context` runtime enforcement is owned by the
+CLI process; agent runtimes shell out to the prime command instead of reading
+the prose module directly.
 
 ## Invocation and routing grammar
 
@@ -193,6 +198,7 @@ ambiguous-term sweep remain separate follow-up work.
 | --- | --- |
 | Artifact | A project or agent state file owned by one or more capabilities. |
 | Human-facing artifact | A root-level Markdown artifact intended for people, such as `TODO.md`, `CHANGELOG.md`, or `DESIGN.md`. |
+| Severity band policy | TODO.md severity bands are header-only allowed for Degraded (⇉), Normal (→), and Annoying (⇢); Critical (⇶) is enforced and must contain at least one `- [type]` item. Authority: `skills/agentera/schemas/artifacts/todo.yaml` CONVENTION TC6; executable rule in `packages/cli/src/hooks/validateArtifact.ts` `validateMdItems`. |
 | Agent-facing artifact | A structured YAML artifact under `.agentera/`, such as `.agentera/progress.yaml`. |
 | Global artifact | A user-level artifact outside a project, such as `PROFILE.md` or `USAGE.md`. |
 | Canonical artifact name | Display identifier such as `VISION.md`, `PROGRESS.md`, or `DOCS.md`; not always a literal path. |
@@ -404,9 +410,12 @@ 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;
-**development** tracks 3.x alphas and release candidates. Default channel is
-stable. Override with `--channel`, `AGENTERA_UPDATE_CHANNEL`, or
+Use this prose as guidance only: **stable** tracks the supported 2.x line on
+`npx -y agentera@latest` and, for maintainers, `uvx --from git+...@main` (Python
+CLI). **development** tracks 3.x alphas and release candidates on **npm only**
+(`npx -y agentera@next`); feat/v3 is TypeScript-only and has no uv/git install
+path. v2→v3 is a one-way upgrade through the development npm channel. Default
+channel is stable. Override with `--channel`, `AGENTERA_UPDATE_CHANNEL`, or
 `update.channel` in user config. Cross-major v2→v3 migration is never implied by
 stable-channel `@latest` while stable tracks 2.x; it is migrate work tagged
 `major_boundary_crossing` in the app lifecycle authority and requires semver
@@ -540,7 +549,7 @@ 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. |
-| `skills/agentera/capabilities/*/instructions.md` | Workflow grammar, capability roles, safety rails, exit marker forms. |
+| `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`. |
 | `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. |

package/bundle/registry.json

@@ -4,7 +4,7 @@
   "skills": [
     {
       "name": "agentera",
-      "version": "2.7.6",
+      "version": "3.0.0",
       "description": "Compound agent orchestration suite — 12 capabilities in one bundled skill; exact bare hej uses the Agentera dashboard path",
       "path": "skills/agentera",
       "capabilities": [