agentera 3.0.0-dev.4 → 3.0.0-dev.6

package/bundle/references/cli/upgrade-repair-wording.md

@@ -0,0 +1,31 @@
+# Upgrade repair wording — v3 cursor agent skip
+
+When `agentera upgrade --runtime cursor` (or a full runtime phase) runs against a
+**project** directory, managed `.cursor/agents/*.md` descriptors are normally
+copied from the active app-home bundle. On a **v3 capability-surface** project
+that signal is suppressed so D65 `prime --context` bodies are not regressed to
+the retired `instructions.md` read path.
+
+## v3 surface probe
+
+Treat the project as v3 when **all twelve** instruction modules exist:
+
+`packages/cli/src/capabilities/<name>/instructions.ts`
+
+for every routed capability (`hej`, `visionera`, `resonera`, `inspirera`,
+`planera`, `realisera`, `optimera`, `inspektera`, `dokumentera`, `profilera`,
+`visualisera`, `orkestrera`).
+
+If any module is missing, preserve v2 upgrade behavior (copy/refresh managed
+agents from the bundle).
+
+## Orchestrator behavior
+
+| Orchestrator | Branch | Behavior |
+| --- | --- | --- |
+| TypeScript (`packages/cli/src/upgrade/runtimeMigration.ts`) | `feat/v3` | On v3 probe match, emit `skipped` `copy-agent` items for in-tree `.cursor/agents/` instead of copying from the bundle. |
+| Python (`scripts/agentera_upgrade.py`) | `main` (stable) | Same probe before the cursor agent copy loop; do not schedule `copy-agent` targets under the project when the probe matches. Backport per the both-branch pattern. |
+
+## User-visible skip message
+
+`v3 capability instruction modules present; in-tree .cursor/agents/ uses prime --context and is not overwritten`

package/bundle/references/cli/v3-handoff-manifest.schema.yaml

@@ -0,0 +1,98 @@
+schema_version: agentera.v3_handoff_manifest.v1
+status: active_authority
+purpose: >-
+  Contract for the v2→v3 handoff manifest written by the stable Python CLI at the
+  app-home root and read by the v3 TypeScript migration preflight. The manifest
+  lets v3 migration classify preserved user state in O(1) time instead of
+  scanning the entire app home.
+manifest_file: v3-handoff.json
+manifest_path: >-
+  {app_home}/v3-handoff.json where app_home is the platform data-home install
+  root (for example ~/.local/share/agentera on Linux).
+writers:
+  - v2 stable Python CLI on install, upgrade apply, and doctor (refresh when stale)
+readers:
+  - v3 TypeScript migration preflight in packages/cli/src/migrate/v2HandoffManifest.ts
+performance:
+  reader_preflight_budget_ms: 100
+  note: >-
+    When the manifest is present and valid, the v3 reader must complete parsing
+    and validation within 100ms. When absent or invalid, the reader may fall
+    back to a full app-home scan with no time budget.
+required_top_level_fields:
+  schema_version:
+    type: string
+    const: agentera.v3_handoff_manifest.v1
+  written_at:
+    type: string
+    format: iso8601_utc
+    description: UTC timestamp when the manifest was last written.
+  installed_v2_version:
+    type: string
+    min_length: 1
+    description: Installed Agentera suite version from the active v2 bundle marker.
+  app_home_path:
+    type: string
+    min_length: 1
+    description: Absolute resolved app-home path the writer used.
+  user_data_inventory:
+    type: array
+    min_items: 6
+    description: >-
+      One entry per catalog id below. Entries for paths that do not exist on disk
+      set exists=false; writers still emit the full catalog so v3 preflight can
+      trust absence without rescanning.
+  runtime_adapters:
+    type: array
+    items:
+      type: string
+    description: >-
+      Runtime adapter ids (references/adapters/runtime-adapter-registry.yaml)
+      that the v2 install actively uses — runtimes whose setup doctor status is
+      pass at write time.
+user_data_inventory_catalog:
+  - id: benchmarks
+    relative_path: benchmarks
+    kind: directory
+  - id: intermediate
+    relative_path: intermediate
+    kind: directory
+  - id: sessions
+    relative_path: sessions
+    kind: directory
+  - id: history
+    relative_path: history
+    kind: directory
+  - id: corpus
+    relative_path: corpus
+    kind: directory
+  - id: profile_files
+    kind: profile_files
+    members:
+      - relative_path: PROFILE.md
+        kind: file
+      - relative_path: USAGE.md
+        kind: file
+user_data_inventory_entry_shapes:
+  directory:
+    required: [id, relative_path, kind, exists]
+    kind_const: directory
+  file:
+    required: [id, relative_path, kind, exists]
+    kind_const: file
+  profile_files:
+    required: [id, kind, members]
+    kind_const: profile_files
+    members:
+      required: [relative_path, kind, exists]
+      kind_const: file
+freshness:
+  writer_obligations:
+    - Refresh the manifest on every v2 upgrade apply.
+    - Refresh the manifest on v2 doctor when stale or missing (after warning).
+  stale_when_any:
+    - Manifest file missing.
+    - schema_version mismatch.
+    - app_home_path differs from the resolved install root.
+    - installed_v2_version differs from the active bundle marker version.
+    - written_at is older than the bundle marker mtime.

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. |
 
@@ -51,11 +51,13 @@ examples. Diagnostics should state object, state, cause, and fix.
 
 | Term | Definition | Common sources |
 | --- | --- | --- |
-| 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/*` |
-| Shared protocol | The primitive vocabulary in `protocol.yaml`: confidence, severity, decision labels, exits, visual tokens, glyphs, and phases. | `skills/agentera/protocol.yaml` |
+| Agentera | An opinionated mobile-first coding agent. One product brand across the monorepo (`@agentera/mobile`, `@agentera/web`, `@agentera/cli`). Structured `.agentera/` project state makes sessions compound. | `README.md`, `.agentera/vision.yaml` |
+| Product surface | A shipped user-facing package in the monorepo: `@agentera/mobile` (primary app), `@agentera/web` (site and docs), `@agentera/cli` (agent runtime and state CLI). | `README.md`, `AGENTS.md`, `packages/*/README.md` |
+| @agentera/mobile | The flagship mobile/web app package at `packages/mobile`. SvelteKit, Cursor SDK, Cloudflare Worker. | `packages/mobile/README.md`, `packages/mobile/DESIGN.md` |
+| Agentera skill | Internal runtime-loaded skill at `skills/agentera/`. Contains the routing entry and twelve capabilities. Contributor and editor-integration surface, not the primary product headline. | `skills/agentera/SKILL.md` |
+| 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/*` |
+| Capability alias | User-facing English name in the mobile app (e.g. `brief`, `discuss`) mapped to internal `-era` IDs (e.g. `hej`, `resonera`). Documented in `packages/mobile/README.md`; schemas retain internal IDs. | `packages/mobile/README.md`, `.agentera/decisions.yaml` |
+| Shared protocol | Internal primitive vocabulary in `protocol.yaml`: confidence, severity, decision labels, exits, visual tokens, glyphs, and phases. | `skills/agentera/protocol.yaml` |
 | Capability schema contract | The executable contract for capability schema groups, stable IDs, priorities, deprecations, and primitive references. | `skills/agentera/capability_schema_contract.yaml` |
 | Project state | Structured files that preserve intent, decisions, plans, progress, health, docs, design, and session continuity. | `README.md`, `.agentera/docs.yaml` |
 | Project history | Durable history kept in files so future agents do not reconstruct history from chat residue. | `README.md`, `.agentera/progress.yaml` |
@@ -87,21 +89,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,14 +200,15 @@ 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. |
+| Canonical artifact name | Protocol `artifact_id` such as `plan`, `progress`, or `docs`; human-facing Markdown filenames such as `TODO.md` are `display_name` values, not protocol identity. |
 | Resolved artifact path | The actual path after consulting `.agentera/docs.yaml` mapping or the default layout. |
-| Artifact mapping | `.agentera/docs.yaml` rows that map canonical names to project-local paths and producers. |
+| Artifact mapping | `.agentera/docs.yaml` rows that map `artifact_id` values to project-local paths and producers. |
 | ArtifactRegistry | The registry interface model for artifact IDs, display names, default paths, producers, consumers, type, scope, and special cases. |
 | `artifact_id` | Machine identifier such as `progress`, `health`, `docs`, or `objective`. |
-| `display_name` | Human-readable canonical name, usually the v1-style Markdown name. |
+| `display_name` | Human-readable filename label such as `VISION.md` or `TODO.md`; registry-owned, not protocol identity. |
 | `default_path` | Registry-owned path used when no docs mapping overrides it. |
 | `local_role` | Capability relationship to an artifact: `produces`, `consumes`, or `produces_and_consumes`. |
 | Docs override boundary | `docs.yaml` may override paths for known display names; it must not redefine canonical identity facts. |
@@ -434,7 +442,7 @@ references, generic plain language, and ambiguous current prose.
 Use this prose as guidance only: current conceptual docs should say the object
 they mean, such as Agentera app files, suite package, plugin-shipped hooks,
 removed `bundle-status` command, Agentera routing entry point, skill entry file,
-v1 skill entry file, or legacy hej bridge. Preserve shipped identifiers and
+historical v1 skill entry paths (post-3.0 removed from the repo tree). Preserve shipped identifiers and
 literal paths such as `.agentera-bundle.json`, `bundle.status`,
 `activeBundleRoot`, `--only bundle`, and `skills/agentera/SKILL.md` unless an
 explicit compatibility migration is in scope.
@@ -484,8 +492,8 @@ Visualisera owns visual identity in `DESIGN.md`. Protocol owns token meanings in
 
 | Phrase | Use |
 | --- | --- |
-| “The open protocol for turning AI agents into engineering teams.” | Product identity. |
-| “One install, one entry point, one query interface to all project state.” | v2 app-home promise. |
+| “Opinionated mobile-first coding agent.” | Product identity. |
+| “One install, one entry point, one query interface to all project state.” | CLI state-access promise (internals/contributor docs). |
 | “Continuity lives in files, not memory.” | Realisera/project-state principle. |
 | “The conversation preserves reasoning; the artifact preserves the plan.” | Planera boundary. |
 | “Planera owns WHAT and WHY; realisera owns HOW.” | Planning/building boundary. |
@@ -543,7 +551,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/references/meta/documentation-inventory.md

@@ -4,7 +4,14 @@ Maintainer inventory of repository documentation, workpapers, and legacy surface
 Authoritative Agentera docs live under `references/`, `skills/agentera/`, and root
 guides — not under `docs/`.
 
-**Last reviewed:** 2026-05-23
+**Last reviewed:** 2026-06-05
+
+## Design docs under `docs/`
+
+| Path | Topic |
+| ---- | ----- |
+| `docs/packaging/v3-packaging.md` | v3 CLI npm/Bun distribution contract |
+| `docs/consolidation/monorepo-plan.md` | Product pivot, `@agentera/*` package layout, migration checklist (D67) |
 
 ## Authority stack
 
@@ -17,7 +24,7 @@ guides — not under `docs/`.
 | Benchmark contract | `references/analysis/startup-measurement-contract.yaml` |
 | Benchmark runbook | `references/analysis/benchmark.md` |
 | JSON surface budgets | `scripts/json_output_surface_manifest.yaml` |
-| Project drafts | `docs/` (gitignored except `docs/README.md`) |
+| Project drafts | `docs/` (gitignored except `docs/README.md`, `docs/packaging/`, `docs/consolidation/`) |
 
 ## `docs/` policy
 
@@ -40,4 +47,3 @@ Live JSON enforcement uses `scripts/json_output_surface_manifest.yaml` only.
 
 - Replace live `SPEC.md` references in `UPGRADE.md`, hooks, adapter docs, `contract.md`
 - Refresh or drop assertions against pre-migration characterization snapshots
-- Agentera 3.0: remove `skills/hej/` bridge and `references/v1-section-mapping.md`

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": [

package/bundle/skills/agentera/SKILL.md

@@ -1,14 +1,28 @@
 ---
 name: agentera
 description: >
-  The open protocol for turning AI agents into engineering teams.
-  One Agentera skill with twelve capabilities, each defined by human-readable
-  prose and machine-readable schemas. The agent reads this file to route
-  incoming requests to the right capability. Use this skill for /agentera,
-  Agentera capability requests, and a complete user message exactly `hej`;
-  bare `hej` runs the agentera prime orientation dashboard path instead of a generic greeting.
-version: "2.7.6"
+  Agentera agent engine for editor runtimes. One Agentera skill with twelve
+  capabilities; per-capability prose lives in
+  `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
+  it through `agentera prime --context <name> --format json`. Use this skill
+  for /agentera, Agentera capability requests, and a complete user message
+  exactly `hej`; bare `hej` runs the agentera prime orientation dashboard path
+  instead of a generic greeting.
+version: "3.0.0"
 spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
+capabilities:
+  - hej
+  - visionera
+  - resonera
+  - inspirera
+  - planera
+  - realisera
+  - optimera
+  - inspektera
+  - dokumentera
+  - profilera
+  - visualisera
+  - orkestrera
 ---
 
 # agentera
@@ -182,9 +196,10 @@ above must have already confirmed the installed CLI is usable.
 
 Routine commands are: `prime`, `state plan`, `state progress`, `state health`,
 `state todo`, `state decisions`, `state docs`, `state objective`, and
-`state experiments`. Top-level aliases for legacy commands remain during migration with stderr deprecation; see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml) for the full list. Discovery and custom
-inspection remain available through `agentera schema --format json`
-(with legacy `describe` alias),
+`state experiments`. On the npm 3.x CLI, top-level `hej`, `describe`, `gate`, and
+routine-state names are removed; a smaller transitional alias set still forwards
+with stderr deprecation — see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml). Discovery and custom
+inspection remain available through `agentera schema --format json`,
 `state query --list-artifacts`, and `state query <artifact-name> --format json|yaml`.
 Structured discovery includes an artifact-location contract with mapped paths,
 normal read commands, and raw-access boundaries; use that contract before
@@ -239,7 +254,7 @@ Bare `/agentera` returning-project output must include these visible markers:
 
 Use the README-style layout from hej Step 1b: metrics first, narrative read
 inside `status`, then attention and next. The issues summary line uses
-`critical · degraded · annoying` only. Omit `attention` only when the source has no attention items. Always include the
+`critical · degraded · normal · annoying` in the order prime emits them. Omit `attention` only when the source has no attention items. Always include the
 mandatory `⌂ hej · <status>` marker below the dashboard code fence, and ask for
 confirmation before invoking the suggested downstream capability. For
 `/agentera <capability-name>` or `/agentera <alias>`, do not assume the route
@@ -261,21 +276,25 @@ v2 paths `hej --capability-context` and `--context-profile` are removed in 3.0.
 For normal ≡ planera execution, use
 `capability_context.context.planning_context.startup_contract` from
 `agentera prime --context planera --format json`
-before reading `skills/agentera/capabilities/planera/instructions.md`. Read Planera prose only when
-editing Planera, resolving contradiction or ambiguity, validating detailed
-behavior not covered by the compact contract, or investigating benchmark/read-trigger
-evidence. This preserves Planera prose as detailed authority and does not add
-`agentera planera`; `/agentera plan` remains routing while `agentera state plan`
-remains plan state (top-level `agentera plan` is a migration alias).
+before reading the Planera prose from
+`packages/cli/src/capabilities/planera/instructions.ts` (served via
+`capability_context.prose` from the same prime call). Read the full Planera
+prose only when editing Planera, resolving contradiction or ambiguity,
+validating detailed behavior not covered by the compact contract, or
+investigating benchmark/read-trigger evidence. This preserves Planera prose
+as detailed authority and does not add `agentera planera`; `/agentera plan`
+remains routing while `agentera state plan` remains plan state (top-level
+`agentera plan` is a migration alias).
 For normal DECISIONS.md context, use `agentera state decisions --format json` and its
 source_contract. When `complete_for_normal_deliberation_context=true`, preserve
 returned `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed`
 instead of raw-reading `.agentera/decisions.yaml` to reconstruct missing history.
 Raw decision artifact access is reserved for Resonera-owned writes/repairs,
 artifact corruption diagnostics, or CLI defect investigation.
-Reading a capability's `instructions.md` file is not itself a capability invocation;
-invocation means routing to the capability, following its prose, and using the
-CLI state layer first for artifact-backed state.
+Reading a capability's instructions module is not itself a capability invocation;
+invocation means routing to the capability, fetching the prose via
+`agentera prime --context <name> --format json`, following that prose, and using
+the CLI state layer first for artifact-backed state.
 
 Capability handoffs use glyph plus canonical capability name, for example
 `⧉ realisera` or `≡ planera`. Reserve `/agentera <alias>` wording for explicit
@@ -343,15 +362,14 @@ when supplied by the CLI.
 Do not replace the CLI-owned preview with manual artifact inspection,
 hand-written migration steps, or raw YAML reads. Only the apply step requires confirmation.
 
-The upgrade command is idempotent. It installs or updates Agentera app files
-when invoked through `uvx`, migrates v1 artifacts, wires runtime config to that
-app home, and removes fixable outdated v1 runtime artifacts.
-The artifacts phase migrates supported v1 Markdown files to YAML with backups
-after preview and confirmation. Package refreshes that run `npx skills remove`
-for v1 skill entries and `npx skills add` for `/agentera` remain explicit opt-in
-via `--update-packages`. `npx skills update` by itself updates only the visible
-skill; if `/agentera` then finds missing or out-of-date app files, run the
-plain-language repair preview above so upgrade updates the app and cleans up
+The upgrade command is idempotent. It installs or updates Agentera app files,
+migrates legacy Markdown artifacts to YAML when detected, wires runtime config
+to the app home, and removes fixable outdated runtime artifacts after preview
+and confirmation. Package refreshes that run `npx skills remove` for legacy
+standalone skill entries and `npx skills add` for `/agentera` remain explicit
+opt-in via `--update-packages`. `npx skills update` by itself updates only the
+visible skill; if `/agentera` then finds missing or out-of-date app files, run
+the plain-language repair preview above so upgrade updates the app and cleans up
 the old default directory when it is recoverable.
 
 ### Layer 1: Bare `/agentera` or bare `hej` — delegate to prime
@@ -436,25 +454,24 @@ Before reading or writing any artifact, check if `.agentera/docs.yaml` exists. I
 
 ```
 skills/agentera/
-  SKILL.md                          # This file
+  SKILL.md                          # This file (routing stub + capability table)
   protocol.yaml                     # Shared primitives
   capability_schema_contract.yaml   # Self-referential schema contract
   capabilities/
     hej/
-      instructions.md
       schemas/
         triggers.yaml
         artifacts.yaml
         validation.yaml
         exit.yaml
     resonera/
-      instructions.md
       schemas/
         triggers.yaml
         artifacts.yaml
         validation.yaml
         exit.yaml
-    ... (12 capabilities total)
+    ... (12 capabilities total, each with schemas/ only)
+packages/cli/src/capabilities/<name>/instructions.ts   # Per-capability prose (D65)
 ```
 
 Validate any capability against the contract through the canonical CLI:

package/bundle/skills/agentera/agents/dokumentera.toml

@@ -2,5 +2,5 @@
 name = "dokumentera"
 description = "Documentation updates and synchronization."
 developer_instructions = """
-You are the Agentera dokumentera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/dokumentera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/dokumentera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera dokumentera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context dokumentera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/hej.toml

@@ -2,5 +2,5 @@
 name = "hej"
 description = "Agentera orientation and routing dashboard."
 developer_instructions = """
-You are the Agentera hej capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/hej/instructions.md when available. For local checkout development, use skills/agentera/capabilities/hej/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera hej capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context hej --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/inspektera.toml

@@ -2,5 +2,5 @@
 name = "inspektera"
 description = "Codebase health audit."
 developer_instructions = """
-You are the Agentera inspektera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspektera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspektera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera inspektera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context inspektera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/inspirera.toml

@@ -2,5 +2,5 @@
 name = "inspirera"
 description = "External pattern research and synthesis."
 developer_instructions = """
-You are the Agentera inspirera capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspirera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspirera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera inspirera capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context inspirera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/optimera.toml

@@ -2,5 +2,5 @@
 name = "optimera"
 description = "Metric-driven optimization cycles."
 developer_instructions = """
-You are the Agentera optimera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/optimera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/optimera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera optimera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context optimera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/orkestrera.toml

@@ -2,5 +2,5 @@
 name = "orkestrera"
 description = "Multi-cycle orchestration over active plans."
 developer_instructions = """
-You are the Agentera orkestrera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/orkestrera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/orkestrera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera orkestrera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context orkestrera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/planera.toml

@@ -2,5 +2,5 @@
 name = "planera"
 description = "Planning with acceptance criteria."
 developer_instructions = """
-You are the Agentera planera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/planera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/planera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera planera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context planera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/profilera.toml

@@ -2,5 +2,5 @@
 name = "profilera"
 description = "Decision profiling and preference memory."
 developer_instructions = """
-You are the Agentera profilera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/profilera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/profilera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera profilera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context profilera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/realisera.toml

@@ -2,5 +2,5 @@
 name = "realisera"
 description = "Autonomous development execution."
 developer_instructions = """
-You are the Agentera realisera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/realisera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/realisera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera realisera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context realisera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/resonera.toml

@@ -2,5 +2,5 @@
 name = "resonera"
 description = "Structured deliberation and decision support."
 developer_instructions = """
-You are the Agentera resonera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/resonera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/resonera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera resonera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context resonera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/visionera.toml

@@ -2,5 +2,5 @@
 name = "visionera"
 description = "Define and refine project direction."
 developer_instructions = """
-You are the Agentera visionera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/visionera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/visionera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera visionera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context visionera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/visualisera.toml

@@ -2,5 +2,5 @@
 name = "visualisera"
 description = "Visual identity and design systems."
 developer_instructions = """
-You are the Agentera visualisera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/visualisera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/visualisera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera visualisera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context visualisera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """