agentera 3.0.0-dev.5 → 3.0.0-dev.6

package/README.md

@@ -17,10 +17,11 @@ 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).
+Full preview instructions, channels, and migration paths: [`UPGRADE.md`](../../UPGRADE.md).
 
-Upgrade channels and v2→v3 opt-in: [`UPGRADE.md`](../../UPGRADE.md).
+## Editor runtime installs
+
+Agentera ships a skill bundle for supported editor runtimes (Claude Code, OpenCode, Cursor, Copilot CLI, Codex CLI). Install steps and parity details live in the [repository README — Internals](../../README.md#internals) and [`references/adapters/runtime-feature-parity.md`](../../references/adapters/runtime-feature-parity.md).
 
 ## Package layout
 

package/bundle/references/adapters/opencode.md

@@ -56,7 +56,7 @@ OpenCode skill search paths:
 - Global install: `npx skills add jgabor/agentera -g -a opencode --skill agentera -y`
 - Project install: symlink or copy `skills/agentera/` into `.opencode/skills/agentera/` or `.agents/skills/agentera/`
 
-The temporary `skills/hej/` entry point is a v1 upgrade bridge, not a new-install target. Each Agentera skill entry file already contains YAML frontmatter with `name` and `description`, which matches OpenCode's frontmatter requirements exactly. The OpenCode plugin adds one prompt transformation: when the complete user message is exactly bare text `hej`, `chat.message` rewrites it to load the bundled `agentera` skill and route through the `agentera hej` dashboard path. The match is exact except for OpenCode's CLI-added single trailing newline transport artifact, and does not apply to `/hej`, `Hej`, `hej there`, attachments, or other message parts.
+Each Agentera skill entry file contains YAML frontmatter with `name` and `description`, which matches OpenCode's frontmatter requirements exactly. The OpenCode plugin adds one prompt transformation: when the complete user message is exactly bare text `hej`, `chat.message` rewrites it to load the bundled `agentera` skill and route through the `agentera prime` dashboard path. The match is exact except for OpenCode's CLI-added single trailing newline transport artifact, and does not apply to `Hej`, `hej there`, attachments, or other message parts.
 
 **OpenCode frontmatter validation** requires: `name` (1-64 chars, lowercase alphanumeric with single hyphens), `description` (1-1024 chars). Agentera entry point names are lowercase, matching the validation regex `^[a-z0-9]+(-[a-z0-9]+)*$`.
 

package/bundle/references/adapters/package-registry.yaml

@@ -233,7 +233,6 @@ records:
         - .claude-plugin/marketplace.json
         - .opencode/plugins/agentera.js
         - skills/agentera/SKILL.md
-        - skills/hej/SKILL.md
         - registry.json
       index_targets:
         - references/adapters/package-surface-characterization.md

package/bundle/references/adapters/package-surface-characterization.md

@@ -17,7 +17,7 @@ The current version-bearing surfaces are:
 | `plugin.json` | version-bearing surface and runtime package manifest | root Copilot manifest `version` matches the suite version. |
 | `.github/plugin/plugin.json` | version-bearing surface and runtime package manifest | repository Copilot manifest `version` matches the suite version. |
 | `.codex-plugin/plugin.json` | version-bearing surface and runtime package manifest | Codex manifest `version` matches the suite version. |
-| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and every plugin entry version, including the legacy `hej` bridge, match the suite version. |
+| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and the bundled `agentera` plugin entry version match the suite version. |
 | `.opencode/plugins/agentera.js` | version-bearing surface | `AGENTERA_VERSION` matches the registry suite version and drives the OpenCode command marker file `.agentera-version`. |
 
 `.opencode/package.json` is intentionally not version-bearing. Its current behavior is runtime package manifest behavior only: it keeps `type: "module"`, `main`/`exports` pointing at `./plugins/agentera.js`, `dependencies["@opencode-ai/plugin"] == "1.14.33"`, and an `agentera` npm-loadable plugin metadata block, but it has no top-level `name` or `version` field.
@@ -44,5 +44,4 @@ Write gating is preserved: `--update-packages` changes package items from `skipp
 | `.agentera/docs.yaml` `version_files` includes version-bearing surfaces and excludes `.opencode/package.json`. | version-bearing surface | `preserve` | Keep `.opencode/package.json` out of version checks because it is a runtime package manifest, not a suite version surface. |
 | `.opencode/package.json` is force-included and bundled, but it is not in docs `version_files`. | runtime package manifest | `preserve` | Keep packaging it without treating it as version-bearing. |
 | Upgrade package commands are represented as argv lists for Claude Code and OpenCode only; Codex and Copilot have runtime manifests but no package-manager command entries. | package-manager command surface | `preserve` | Keep command planning limited to currently managed package runtimes. |
-| `.claude-plugin/marketplace.json` carries a `hej` legacy bridge version alongside `agentera`. | version-bearing surface | `defer` | Keep the legacy bridge version aligned until a separate legacy-bridge removal or marketplace simplification task exists. |
 | Live package-manager behavior is not characterized by this task. | package-manager command surface | `defer` | Keep tests mocked; do not introduce live `npx skills` execution. |

package/bundle/references/analysis/startup-measurement-contract.yaml

@@ -362,17 +362,17 @@ privacy_boundary:
     - canonical_event_class
     - salted_non_reconstructable_hash
   canonical_artifact_labels:
-    TODO.md: TODO.md
-    CHANGELOG.md: CHANGELOG.md
-    DESIGN.md: DESIGN.md
-    PLAN.md: PLAN.md
-    PROGRESS.md: PROGRESS.md
-    DOCS.md: DOCS.md
-    DECISIONS.md: DECISIONS.md
-    HEALTH.md: HEALTH.md
-    VISION.md: VISION.md
-    OBJECTIVE.md: OBJECTIVE.md
-    EXPERIMENTS.md: EXPERIMENTS.md
+    todo: todo
+    changelog: changelog
+    design: design
+    plan: plan
+    progress: progress
+    docs: docs
+    decisions: decisions
+    health: health
+    vision: vision
+    objective: objective
+    experiments: experiments
     AGENTS.md: AGENTS.md
     SKILL.md: SKILL.md
     AGENTERA_ARTIFACTS: AGENTERA_ARTIFACTS

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -204,9 +204,10 @@ prime_hej_schema_migration_boundary:
   prime_absorbs_hej:
     status: target
     hej_cli: >-
-      Top-level `hej` is removed from the public parser after the alias period.
-      `agentera hej` prints one stderr deprecation naming `prime` and delegates
-      during Phase 1–2.
+      Top-level `hej` is removed from the npm 3.x public parser and dispatch.
+      During Phase 1–2, `agentera hej` printed one stderr deprecation naming
+      `prime` and delegated; Phase 3 on the development channel rejects the
+      command with an unsupported-target envelope.
     hej_skill_route: >-
       Bare `hej` in the Agentera skill still routes to orientation, but the installed
       CLI gate calls `agentera prime` and renders from that composite result.
@@ -225,8 +226,9 @@ prime_hej_schema_migration_boundary:
     status: target
     canonical: agentera schema [--format json|yaml]
     alias: >-
-      `agentera describe` prints one stderr deprecation naming `schema` and delegates
-      during Phase 1–2.
+      Top-level `describe` is removed from the npm 3.x public parser and dispatch.
+      During Phase 1–2, `agentera describe` printed one stderr deprecation naming
+      `schema` and delegated.
     discovery_ownership: >-
       `schema` owns runtime CLI/schema introspection formerly on `describe`, including
       command tree, audience tags, artifact locations, and linked contract sections.
@@ -260,7 +262,9 @@ plan_routing_distinction:
       is not a CLI command and does not read `.agentera/plan.yaml` by itself.
   state_read:
     invocation: agentera state plan
-    legacy_alias: agentera plan
+    legacy_alias: >-
+      Top-level `agentera plan` was removed on the npm 3.x CLI in Phase 3; use
+      `agentera state plan`.
     surface: CLI routine state read
     meaning: >-
       Read-only access to the active plan artifact summary, tasks, acceptance
@@ -275,8 +279,8 @@ plan_routing_distinction:
       for Planera remains `agentera prime --context planera --format json`.
   agent_guidance: >-
     Use `/agentera plan` when the user wants planning work routed to Planera; use
-    `agentera state plan` (or legacy `agentera plan`) when the agent needs plan
-    artifact state; use `agentera planera` for capability routing guidance; use
+    `agentera state plan` when the agent needs plan artifact state; use
+    `agentera planera` for capability routing guidance; use
     `agentera prime --context planera` for bounded Planera startup context.
 migration_phases:
   phase_1:
@@ -295,15 +299,18 @@ migration_phases:
       - Record measurement evidence for JSON surface moves.
   phase_3:
     name: remove_deprecated_top_level_parsers
+    status: shipped_on_development_channel
     actions:
       - >-
-        Remove `hej`, public `describe`, and `gate` from top-level parser help.
+        Remove `hej`, public `describe`, and `gate` from top-level parser help
+        and dispatch on the npm 3.x CLI.
       - >-
-        Remove other deprecated top-level parsers except documented capability and
-        lifecycle names and the Phase 1–2 alias set until post-major cleanup.
+        Remove routine-state top-level parsers (`plan`, `progress`, `health`,
+        `todo`, `decisions`, `docs`, `objective`, `experiments`) from help and
+        dispatch on the npm 3.x CLI.
       - >-
-        Deferred final removal of all routine-state top-level aliases after one
-        minor alias release.
+        Keep a transitional stderr-alias set (`validate`, `compact`, `verify`,
+        `stats`, `lint`, `query`) until post-cutover cleanup.
 alias_policy:
   stderr_format: one-line deprecation naming the canonical command
   delegation: forward to canonical handler with unchanged JSON/text envelopes
@@ -334,22 +341,29 @@ command_tree_target:
     - report [user]
     - check [maintainer]
 
-deprecated_top_level_aliases:
-  # Command aliases that emit stderr deprecation warnings
-  - { legacy: hej, canonical: prime }
-  - { legacy: describe, canonical: schema }
-  - { legacy: plan, canonical: "state plan" }
-  - { legacy: progress, canonical: "state progress" }
-  - { legacy: health, canonical: "state health" }
-  - { legacy: todo, canonical: "state todo" }
-  - { legacy: decisions, canonical: "state decisions" }
-  - { legacy: docs, canonical: "state docs" }
-  - { legacy: objective, canonical: "state objective" }
-  - { legacy: experiments, canonical: "state experiments" }
+removed_top_level_commands:
+  # Phase 3 on npm 3.x: removed from help and dispatch (unsupported_target)
+  - hej
+  - describe
+  - gate
+  - plan
+  - progress
+  - health
+  - todo
+  - decisions
+  - docs
+  - objective
+  - experiments
+
+transitional_stderr_aliases:
+  # Still delegate with one-line stderr deprecation on npm 3.x
   - { legacy: query, canonical: "state query" }
   - { legacy: compact, canonical: "check compact" }
-  - { legacy: gate, canonical: "check compact" }
   - { legacy: verify, canonical: "check verify" }
   - { legacy: stats, canonical: report }
   - { legacy: lint, canonical: "check lint" }
   - { legacy: validate, canonical: "check validate" }
+
+# Superseded by `removed_top_level_commands` and `transitional_stderr_aliases`
+# for npm 3.x Phase 3 (empty list retained for contract migration readers).
+deprecated_top_level_aliases: []

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

@@ -14,7 +14,7 @@ scope:
     - Package and distribution metadata that names the suite package shape.
     - Runtime hook packaging prose and metadata for plugin-shipped hooks.
     - 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: >-
@@ -119,32 +117,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

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

@@ -0,0 +1,9 @@
+# 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

package/bundle/references/cli/single-name-protocol.yaml

@@ -0,0 +1,42 @@
+schema_version: agentera.single_name_protocol.v1
+status: active_authority
+decision: 58
+purpose: >-
+  Machine-readable Decision 58 boundary: forbidden legacy protocol identifiers
+  and scan surfaces for the single-name protocol regression test.
+human_index:
+  document: references/cli/vocabulary.md
+forbidden_protocol_substrings:
+  - pattern: instruction_file
+    rationale: D65 renamed DIRECTORY_REQUIREMENTS and contract fields to instruction_module.
+  - pattern: canonical_instruction_file
+    rationale: Use canonical_instruction_module in capability-instruction-contract.yaml.
+  - pattern: legacy_instruction_file
+    rationale: Historical paths belong in archive or migration modules only.
+  - pattern: instructionPath
+    rationale: capabilityContract loader exposes instructionModulePath only.
+forbidden_storage_protocol_markdown_artifacts:
+  - PROGRESS.md
+  - PLAN.md
+  - DECISIONS.md
+  - VISION.md
+  - HEALTH.md
+  - DOCS.md
+  - OBJECTIVE.md
+  - EXPERIMENTS.md
+scan_roots:
+  - packages/cli/src
+  - skills/agentera/capability_schema_contract.yaml
+  - skills/agentera/protocol.yaml
+  - references/cli/capability-instruction-contract.yaml
+  - references/cli/vocabulary.md
+  - references/cli/vocabulary-index.yaml
+  - registry.json
+scan_exclude_globs:
+  - "**/capabilities/**/instructions.ts"
+  - "**/migrateArtifactsV1ToV2.ts"
+  - "**/migrateArtifactsV2ToV3.ts"
+  - "**/migrateArtifacts*.ts"
+  - "**/*.test.ts"
+  - "**/test/**"
+comment_line_exempt: true

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

@@ -37,6 +37,7 @@ channels:
       concept: forward_successor_line
       channel: development
       version: "3.0.0"
+      announced: false
       npm:
         dist_tag: next
       npm_only_advisory: >-

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.md

@@ -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` |
+| 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/*` |
-| Shared protocol | The primitive vocabulary in `protocol.yaml`: confidence, severity, decision labels, exits, visual tokens, glyphs, and phases. | `skills/agentera/protocol.yaml` |
+| 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` |
@@ -201,12 +203,12 @@ ambiguous-term sweep remain separate follow-up work.
 | 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. |
@@ -440,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.
@@ -490,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. |

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/skills/agentera/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: agentera
 description: >
-  The open protocol for turning AI agents into engineering teams. One Agentera
-  skill with twelve capabilities; per-capability prose lives in
+  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
@@ -196,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
@@ -361,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