agentera 3.0.0-dev.4 → 3.0.0-dev.41

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

@@ -2,7 +2,7 @@ schema_version: agentera.bundle_skill_vocabulary.v1
 status: active_authority
 purpose: >-
   Classify surviving `bundle` and `SKILL.md` terminology so docs, package
-  metadata, runtime descriptors, tests, historical records, and compatibility
+  metadata, tests, historical records, and compatibility
   identifiers share one bounded vocabulary source without forcing mechanical
   renames of shipped surfaces.
 sources:
@@ -12,9 +12,9 @@ scope:
   includes:
     - Current user-facing and diagnostic prose that names Agentera app files.
     - Package and distribution metadata that names the suite package shape.
-    - Runtime hook packaging prose and metadata for plugin-shipped hooks.
+    - Historical classification of retired runtime hook packaging prose and metadata.
     - Historical references to the removed `bundle-status` command.
-    - Current and legacy references to `skills/agentera/SKILL.md` and v1 skill entry files.
+    - Current references to `skills/agentera/SKILL.md`.
   excludes:
     - Routing and execution vocabulary collapse work.
     - Capability instruction-file rename work.
@@ -32,8 +32,6 @@ canonical_concept_order:
   - removed_bundle_status_command
   - agentera_routing_entry
   - skill_entry_file
-  - v1_skill_entry_file
-  - legacy_hej_bridge
 canonical_concepts:
   agentera_app_files:
     definition: >-
@@ -54,8 +52,7 @@ canonical_concepts:
   suite_package:
     definition: >-
       The packaged distribution shape that ships the Agentera skill, CLI,
-      scripts, hooks, references, runtime descriptors, and package metadata as
-      one suite artifact.
+      references, and package metadata as one suite artifact.
     allowed_terms:
       - suite package
       - Agentera package
@@ -65,10 +62,10 @@ canonical_concepts:
       - bundle
       - single-bundle model
       - bundled suite
-  plugin_shipped_hooks:
+  retired_plugin_shipped_hooks:
     definition: >-
-      Hooks that are shipped by runtime plugin package surfaces such as Codex,
-      OpenCode, Claude, or GitHub plugin metadata.
+      Historical term for hooks shipped by retired v2 host-native packages.
+      Current Agentera packages ship no host-native hooks or plugin metadata.
     allowed_terms:
       - plugin-shipped hooks
       - plugin-bundled hooks
@@ -119,32 +116,6 @@ canonical_concepts:
       - SKILL.md
       - skill file
       - skill entry
-  v1_skill_entry_file:
-    definition: >-
-      A historical standalone v1 skill entry file or path retained in migration
-      notes, tests, stale-path checks, and compatibility fixtures.
-    allowed_terms:
-      - v1 skill entry file
-      - v1 standalone skill entry file
-      - "historical v1 `SKILL.md` file"
-      - v1 skill path
-    forbidden_ambiguous_shortcuts:
-      - SKILL.md
-      - v1 SKILL.md
-      - old skill file
-  legacy_hej_bridge:
-    definition: >-
-      The temporary v1 `/hej` bridge or exact bare `hej` compatibility path that
-      guides users toward `/agentera` and the v2 upgrade path.
-    allowed_terms:
-      - legacy hej bridge
-      - "legacy `/hej` bridge"
-      - v1 hej bridge
-      - "bare `hej` compatibility path"
-    forbidden_ambiguous_shortcuts:
-      - hej skill
-      - legacy skill
-      - old hej
 classification_order:
   - canonical_concept
   - compatibility_identifier
@@ -183,6 +154,7 @@ focused_scan:
   allowed_classifications:
     - canonical
     - compatibility-preserved
+    - migration-only
     - historical
     - fixture-only
     - generic
@@ -190,11 +162,10 @@ focused_scan:
     - AGENTS.md
     - README.md
     - references/cli/vocabulary.md
-    - references/adapters/opencode.md
     - (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
@@ -221,16 +192,8 @@ focused_scan:
       reason: Vocabulary docs use concrete skill entry file paths and source-index references.
     - path: ^references/cli/vocabulary\.md$
       text: --only bundle|\.agentera-bundle\.json|bundle\.status|activeBundleRoot|bundle-status
-      classification: compatibility-preserved
-      reason: Vocabulary docs preserve shipped compatibility identifiers and removed command references.
-    - path: ^references/adapters/opencode\.md$
-      text: bundled Agentera dashboard path|bundled `agentera` skill|bundled Agentera
-      classification: generic
-      reason: OpenCode adapter prose uses bundled in the ordinary package-shipping sense, not as Agentera app-file terminology.
-    - path: ^references/adapters/opencode\.md$
-      text: SKILL\.md files|<name>/SKILL\.md|skills/\*/SKILL\.md|skills/agentera/SKILL\.md
-      classification: compatibility-preserved
-      reason: OpenCode adapter prose documents concrete runtime skill entry file paths.
+      classification: migration-only
+      reason: Vocabulary docs classify retired v2 identifiers for migration evidence and released history only.
     - path: ^scripts/measure_token_payload\.py$
       text: 'v1 baseline: all 12 v1 SKILL\.md files|skill_root / "SKILL\.md"'
       classification: historical
@@ -251,7 +214,7 @@ focused_scan:
       text: .
       classification: fixture-only
       reason: Runtime adapter tests use fixture paths, expected diagnostics, package metadata, and compatibility test class names.
-compatibility_identifiers:
+migration_identifiers:
   bundle:
     - .agentera-bundle.json
     - bundle.status

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,85 @@ 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 instructions through the slim
+      `capability_context` capsule's `instructions` 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 instructions
+      in the `instructions` 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 instructions 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 `instructions` 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.instructions` 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
 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
@@ -114,8 +109,51 @@ surface_inventory:
   docs_vocabulary: delegates_to_this_authority
   readme: concise_user_facing_current_and_future_authoring_seam
   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/capability-instruction-structure.md

@@ -0,0 +1,144 @@
+# Capability instruction structure
+
+Origin: Decision 80 (2026-07-06) — Six-section spine for capability instructions.
+Builds on D79 (status rewrite, direct-contract philosophy), D71 (RFC 2119 modal
+vocabulary), D72 (bundle-to-app terminology), D57/D65 (instructions.ts as
+canonical module served via `agentera prime --context`).
+
+Agentera's 12 capability instruction files (`packages/cli/src/capabilities/<name>/instructions.ts`)
+MUST follow a shared six-section spine. Five sections are shape-constrained; one
+(Workflow phases) is mandatory-as-section but free-form in content. This document
+owns the spine spec, the five workflow shapes taxonomy, and the per-capability
+deviation table filled incrementally as each audit completes.
+
+---
+
+## The six-section spine
+
+Every capability instructions.ts MUST contain these six sections in order:
+
+### 1. Purpose
+
+One paragraph stating what the capability does, plus the capability glyph
+(SG1-SG12). Shape-constrained: glyph plus one-paragraph purpose. No sub-sections.
+
+### 2. State artifacts
+
+What the capability reads, writes, and consumes. Shape-constrained:
+reads/writes/consumes declarations plus artifact path resolution. Per-capability
+artifact-schema subsections allowed (e.g., vision's `vision.yaml shape`, document's
+`docs.yaml shape`, design's `DESIGN.md format`).
+
+### 3. Workflow phases (mandatory section, free-form content)
+
+The per-capability core. The section MUST exist and MUST be named "Workflow phases"
+or a per-capability equivalent that names the workflow shape (e.g., "The orchestration
+loop", "The cycle", "Briefing", "Running state"). Internal structure is per-capability:
+linear steps, conversational loop, cycle-based, mode-split, or multi-surface. See
+the five workflow shapes taxonomy below.
+
+### 4. Safety rails
+
+`<critical>` block with MUST NOT / NEVER rules. Protocol-bound. Shape-constrained:
+MUST start with `<critical>` tag, MUST use D71 RFC 2119 modal vocabulary for
+protocol-force rules.
+
+### 5. Exit signals
+
+EX1-EX4 conditions with the capability's canonical glyph marker. Protocol-bound.
+Shape-constrained: MUST list all four exit conditions, MUST use the
+`<glyph> <capability> · <status>` marker format.
+
+### 6. Cross-capability integration
+
+Feeds-into, triggers, and informed-by declarations, plus getting-started use-case
+examples (when to invoke this capability from other contexts). Shape-constrained:
+MUST be present; depth is per-capability (status = one paragraph; orchestrate =
+substantial surface descriptions). Invocation guidance ("Before a build session,
+run `/agentera discuss`") folds into this section as the inverse of
+feeds-into/triggers — same relationship, consumer perspective.
+
+---
+
+## Flex sections (per-capability optional)
+
+Domain content sections MAY appear between spine sections when the capability has
+capability-specific content that does not fit the spine (e.g., design: Colors and
+Typography; profile: PROFILE.md template; research: deliverable template). These
+are rare and documented in the deviation table below.
+
+---
+
+## Five workflow shapes taxonomy
+
+Capabilities declare their workflow shape at the top of the Workflow phases section
+so the deviation table can classify them:
+
+| Shape | Capabilities | Structure |
+|---|---|---|
+| **Linear** | status, research, audit | Step N then Step N+1; one-shot progression |
+| **Conversational loop** | discuss | Scratchpad plus per-turn question loop; no linear progression |
+| **Cycle-based** | build, optimize | Iterative cycle with hypothesis/task/constraints; repeat until done |
+| **Mode-split** | vision, document, profile, design, plan | Step 0 detect mode then mode-A / mode-B / mode-C |
+| **Multi-surface** | orchestrate | Multiple surface templates with different structures per surface |
+
+---
+
+## Reference implementation
+
+Status (D79) is the reference implementation. Its structure:
+
+1. **Purpose**: header plus glyph plus one-paragraph purpose plus direct-contract rule
+2. **State artifacts**: source_contract.capability_startup delegation rule (lean on
+   the contract; do not re-encode machine-readable rules in prose)
+3. **Workflow phases**: Dashboard rendering then Briefing then Routing suggestion
+   (linear shape, three phases)
+4. **Safety rails**: six MUST NOT rules in `<critical>` block
+5. **Exit signals**: EX1-EX4 with `⌂ status · <status>` marker
+6. **Cross-capability integration**: one paragraph (status has no
+   getting-started use-case examples to fold in)
+
+Prose length: 10,389 chars. Modal vocabulary: 5 MUST, 5 MUST NOT. No v2-era residue.
+
+---
+
+## Per-capability deviation table
+
+Filled incrementally as each audit completes. "Not audited" = not yet audited
+against D80 plus this reference doc.
+
+| Capability | Shape | Length | D71 modal | D72 terms | Direct contract | Deviations | Audit |
+|---|---|---|---|---|---|---|---|
+| ⌂ status | Linear | 10,389 | Yes | Yes | Yes | None | Complete (D79) |
+| ⛥ vision | Mode-split | 16,667 | Yes | Yes | Yes | Has vision.yaml shape subsection; shared pre-write self-audit hoist (DRY between Create and Refine modes) | Complete (D81) |
+| ❈ discuss | Loop | 12,045 | Yes | Yes | Yes | Has decisions.yaml shape subsection; Getting started folded into §6; loop shape named "The deliberation loop" (§3); readiness check names unclear or unverified items at Done; steering rules (breadth-first, ask-user-to-sketch); schema files use artifact-id labels not canonical filenames | Complete (D82) |
+| ⬚ research | Linear | 12,484 | Yes | Yes | Yes | Has deliverable template; has transferable concepts checkpoint between source reading and target exploration; runtime-agnostic tool references | Complete (D83) |
+| ≡ plan | Mode-split | 14,515 | Yes | Yes | Yes | Has skip/light/full modes; `unknowns:` and `rejected:` full-plan fields; `How build reads PLAN.md` removed (artifact read contract declared in §2 only); unknowns check at handoff; replan trigger qualitative (surprises on one task alter downstream acceptance); Getting started folded into §6; YAML formats reordered intent-first | Complete (D84) |
+| ⧉ build | Cycle | 15,081 | Yes | Yes | Yes | Has Handling blocked work; vision bootstrap folded into Workflow phases; brainstorm cut to minimal fallback; subagent spawning table cut to brief pointer; self-audit folded into Log (8 steps); plan unknowns consumption; cycle boundary stated once; `/loop` replaced with explicit user request | Complete (D85) |
+| ⎘ optimize | Cycle | 20,622 | Yes | Yes | Yes | Has Handling blocked experiments; self-audit folded into Log (7 steps); subagent spawning table compressed (D85 propagation); benchmark context lean seam; experiments.yaml has context block; brainstorm stripped to 4 questions | Complete (D86) |
+| ⛶ audit | Linear | 18,401 | Yes | Yes | Yes | Has finding taxonomy plus health.yaml shape; has 3 agentera-specific dimension mechanics (Version health, Artifact freshness, Prose health); Getting started folded into §6; self-audit folded into Report (7→6 steps); subagent spawning compressed to brief pointer; evidence_context startup delegation (bespoke); decision satisfaction authority rule in Safety rails | Complete (D87) |
+| ▤ document | Mode-split | 14,886 | Yes | Yes | Yes | Has docs.yaml shape; closeout context lean pointer; Getting started folded into §6; self-audit folded into write steps; doc-prose enforcement compressed to lint+report; Step 0 mode detection folded into opening; decision satisfaction in Safety rails | Complete (D88) |
+| ♾ profile | Mode-split | 19,567 | Yes | Yes | Yes | Has PROFILE.md template flex section; coverage+extraction merged (6→4 Full steps); prediction validation folded into Generate + EX2 for <3/5; Validate V3+V4 merged (4→3); Getting started folded into §6; startup contract delegation | Complete (D89) |
+| ◰ design | Mode-split | 16,383 | Yes | Yes | Yes | Has DESIGN.md format subsection in State artifacts; self-audit folded into Write/Update steps; Step 0 folded into opening; Getting started folded into §6 | Complete (D90) |
+| ⎈ orchestrate | Multi-surface | 18,497 | Yes | Yes | Yes | Has staleness check in Step 0 (3 steps, self-contained); has loop stop condition in Exit signals; WARN eliminated from evaluation (PASS/FAIL only); test-suppression directive removed from delegation prompt; Keeping the orchestrator lean folded into Safety rails; subagent table compressed to brief pointer; Getting started folded into §6; decision satisfaction in Safety rails | Complete (D91) |
+
+---
+
+## Cross-cutting rules (apply to all 12)
+
+These rules are inherited from prior decisions and are not re-stated per capability:
+
+- **D71**: RFC 2119 modal vocabulary (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY).
+  Capitalized keywords carry protocol force; lowercase modal verbs are ordinary English.
+- **D72**: `app.*` terminology (not `bundle.*`).
+- **D79 direct-contract philosophy**: lean on `source_contract.capability_startup`;
+  the prose MUST NOT re-encode rules the contract mechanizes (forbidden-command lists,
+  fallback ladders, do-not-read-raw-yaml warnings). If `complete_for_capability_startup`
+  is true, the prose trusts the contract.
+- **D57/D65**: instructions.ts is the canonical module, served via
+  `agentera prime --context <name> --format json`.
+- **Artifact path resolution**: SKILL.md owns the host-bootstrap artifact-path
+  resolution; capability prose delegates (status proved this in D79).
+- **Procedural recovery content**: lives in the owning capability, not the consuming
+  one (status renders `project_integration` fields; upgrade/doctor owns the repair
+  procedure).

package/bundle/references/cli/capability-tool-classification.yaml

@@ -1,53 +1,53 @@
 # Capability tool classification authority
 # Defines which tools each capability subagent needs to fulfill its purpose.
-# Consumed by: descriptor validation, regression tests, runtime adapter docs.
-# Source of truth for per-capability tool requirements across all runtimes.
+# Consumed by shared-skill worker metadata validation and regression tests.
+# Hosts provide and enforce their own tool surfaces; Agentera ships no native adapter.
 
 classification:
   mutation_capable:
     description: Needs file write, edit, and/or shell execution to fulfill purpose
     capabilities:
-      realisera:
+      build:
         permission: {write: allow, bash: allow}
         rationale: Autonomous dev execution — writes code, runs tests/builds, commits
-      optimera:
+      optimize:
         permission: {write: allow, bash: allow}
         rationale: Metric-driven optimization — runs experiments, writes harnesses
-      orkestrera:
+      orchestrate:
         permission: {write: allow, bash: allow}
         rationale: Multi-cycle orchestration — dispatches workers, updates plan/progress
-      dokumentera:
+      document:
         permission: {write: allow, bash: deny}
         rationale: Documentation generation — creates/updates doc files
-      planera:
+      plan:
         permission: {write: allow, bash: deny}
         rationale: Plan management — writes plan.yaml, archives completed plans
 
   contextual_write:
     description: Writes owned Agentera state artifacts
     capabilities:
-      visionera:
+      vision:
         permission: {write: allow, bash: deny}
         rationale: Writes vision.yaml, archives old visions
-      resonera:
+      discuss:
         permission: {write: allow, bash: deny}
         rationale: Writes decisions.yaml, may update TODO.md
-      visualisera:
+      design:
         permission: {write: allow, bash: deny}
         rationale: Writes DESIGN.md, archives old designs
-      profilera:
+      profile:
         permission: {write: allow, bash: allow}
         rationale: Runs extraction scripts, writes PROFILE.md
-      inspektera:
+      audit:
         permission: {write: allow, bash: deny}
         rationale: Writes health.yaml audit reports
 
   read_only:
     description: Only reads files, searches, analyzes
     capabilities:
-      hej:
+      status:
         permission: {write: deny, bash: deny}
         rationale: Strictly read-only orientation dashboard
-      inspirera:
+      research:
         permission: {write: deny, bash: deny}
         rationale: Analysis-only creative exploration

package/bundle/references/cli/coexistence-probe.yaml

@@ -0,0 +1,13 @@
+# v2/v3 coexistence doctor warning contract (both CLI lines).
+schema_version: agentera.coexistenceProbe.v1
+section_header: Coexistence
+warning:
+  headline: "v3 detected alongside v2; pick one line"
+  resolutions:
+    - complete v3 migration
+    - uninstall v3
+    - stay on v2 explicitly
+naming_divergence:
+  description: "v3 uses English capability IDs (status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate); v2 stable uses Swedish -era IDs (hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, orkestrera)"
+  v3_canonical: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+  v2_stable: [hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, orkestrera]