agentera 3.0.0-dev.25 → 3.0.0-dev.26

package/README.md

@@ -2,8 +2,10 @@
 
 Native TypeScript CLI for Agentera 3.0, published as
 [`agentera`](https://www.npmjs.com/package/agentera). The npm package is
-self-contained: compiled commands live in `dist/` and runtime data, manifests,
-hooks, agents, skills, contracts, and documentation live in `bundle/`.
+self-contained: compiled commands live in `dist/`; the canonical shared skill,
+its schemas, required references, and `registry.json` live in `bundle/`. It
+ships no host-native plugin, hook, command, agent, descriptor, or marketplace
+surface.
 
 Until the stable dist-tag is promoted, run 3.0 through `@next`:
 
@@ -20,27 +22,21 @@ Status startup is one call: `prime --context status --format json` returns
 bytes). Omitted detail names its authoritative recovery command. `doctor`
 returns detailed read-only evidence and exact user actions.
 
-## Runtime lifecycle
+## Shared-skill integration
 
-The four active runtimes are OpenCode, Codex, Cursor, and GitHub Copilot; their
-IDs are exactly `opencode`, `codex`, `cursor`, and `copilot`.
-Cursor Agent CLI and Cursor IDE are surfaces of one `cursor` identity; CLI is
-required and IDE is conditional. The canonical shared skill path is
-`~/.agents/skills/agentera`.
+Agentera uses one portable integration: the Agentera CLI plus the shared skill
+at `~/.agents/skills/agentera`. Normal upgrade previews and applies app/project
+migration only. It has no current-runtime selector and does not create native
+runtime resources.
 
 ```bash
-npx -y agentera@next upgrade --dry-run --channel development
-npx -y agentera@next upgrade --runtime all --dry-run
-npx -y agentera@next upgrade --runtime all --yes
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
 ```
 
-On v3 development, the selector-free dry-run previews all active runtimes.
-Use one active ID instead of `all` to scope runtime work. A selector-free apply
-remains app-only; runtime apply requires the selector and `--yes`. `--dry-run`
-has zero filesystem or state side effects. `--yes` approves only declared
-Agentera-owned operations; native install/update, authentication, enablement,
-and trust remain user-owned. Secure automatic apply is Linux-only and reports
-`action_required` elsewhere.
+Preview has no side effects. The apply path is the explicit, one-way v2-to-v3
+migration described in [UPGRADE.md](../../UPGRADE.md); it does not run a native
+package installer.
 
 Retired Claude cleanup is intentionally separate:
 
@@ -72,8 +68,7 @@ plan task retrieval is active-only. Experiment history is objective-scoped and
 reports full, summary-only, or unavailable detail without fabricating archives.
 
 See [UPGRADE.md](../../UPGRADE.md) for ownership, recovery, and migration
-details and [runtime feature parity](../../references/adapters/runtime-feature-parity.md)
-for host-specific behavior.
+details.
 
 ## Contributors
 
@@ -81,6 +76,7 @@ Requires Node.js 22+ and pnpm 10.30.3.
 
 ```bash
 pnpm -C packages/cli test
+pnpm -C packages/cli run verify:package
 pnpm -C packages/cli run typecheck
 pnpm -C packages/cli build
 pnpm -C packages/cli run lint

package/bundle/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Changed
 
-- Changed the v2-to-v3 development upgrade to one full Git-backed command that requires every migration input to match tracked `HEAD`, activates entity authority last, and validates state and `prime` startup automatically. The optional dry-run is read-only; cross-major apply is one-way and has no rollback, restore, non-Git, or partial workflow.
+- Changed the v2-to-v3 development upgrade to one full Git-backed command that converts unchanged tracked input directly into canonical entities, accepts exact partial targets on retry, validates the complete graph, and activates entity authority last. Runtime blockers are reported as post-activation action-required work without modifying the blocked resource. The optional dry-run is read-only; cross-major apply is one-way and has no staging graph, recovery journal, rollback, restore, non-Git, or partial workflow.
 - Cut ordinary project state over to one canonical writer-owned file per entity. Public records now use only bare `id` and `artifact` identity, bounded `list` and exact `get --id` reads, and typed writers discovered through `agentera state <artifact> explain`; aggregate state files and ordinal selectors remain migration or historical evidence only.
 - Split lifecycle validation orchestration from the public validation facade while preserving its import surface and validation behavior.
 - Eliminated the monolithic `corpus.json` publication output from the extract CLI; report dry-run diagnostics now reference tier files and the `privacy.corpus_write` field is renamed to `privacy.tier_write`.
@@ -14,8 +14,8 @@
 
 ### Added
 
-- Added post-cutover entity-backed default state views, bare-ID durability diagnostics, and read-only migration-manifest target validation while preserving legacy numbered behavior before cutover.
-- Added a Git-backed entity cutover owned by the full development-channel `upgrade --yes` command, with deterministic projection, marker-last authority activation, and bounded forward-only interruption recovery.
+- Added post-cutover entity-backed default state views, bare-ID durability diagnostics, and read-only historical migration-manifest target validation while preserving legacy numbered behavior before cutover.
+- Added a Git-backed entity cutover owned by the full development-channel `upgrade --yes` command, with deterministic direct publication, exact-target retries, marker-last authority activation, and first-unresolved-path handoff.
 - Added post-cutover decision entities for immutable bases and content revisions, replaceable satisfaction ownership, bare-ID exact and bounded reads, deterministic effective provenance, stale-base and transition validation, and explicit same-decision conflict detection; marker-absent projects retain the legacy numbered authority without dual writes.
 - Added the post-cutover progress entity writer and `state progress get|list` reads with bare IDs, one canonical file per cycle, atomic replay-safe publication, full provenance, bounded snapshot pagination, and no legacy projection or archive writes; legacy projects remain unchanged until the durable cutover marker exists.
 - Added authority-driven, one-file-per-entity storage primitives with secure project-wide IDs, symlink-safe discovery, conflict-safe publication, relationship validation, and `agentera check validate state` diagnostics.
@@ -34,15 +34,11 @@
 - Added `agentera state decisions amend --number N [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes a record-local revision under `.agentera/revisions/decisions.yaml` that composes over the immutable numbered archive at read time. Apply never rewrites the decisions projection, preserves unrelated decisions' bytes (including comments, block scalars, quoting, and inherited legacy confidence labels), refuses a broken revision document or unsafe record-local boundary without side effects, retries converge on a stable revision identity, and an identical re-submission is an idempotent replay. Append, satisfaction update, and amend tolerate untouched inherited confidence labels as explicit legacy caveats while requiring current vocabulary for new or amended content.
 
 - Added an executable bounded-retrieval authority and reserved CLI grammar for plan tasks, plans, and objective-scoped experiments, including stable and legacy identity rules, experiment `0`, opaque cursors, explicit omissions, and structured compatibility errors; retrieval execution remains staged for subsequent tasks.
-- Added a canonical runtime lifecycle projection with deterministic snapshot identity, applicability, ownership, action classes, counts, and command eligibility for OpenCode, Codex, Cursor, and Copilot.
-- Added bounded prime/status lifecycle attention rows with runtime-scoped repair previews, exact manual procedures, and doctor diagnostics for non-executable blockers.
-- Added runtime lifecycle schemas and adapters for skills, plugins, hooks, agents, configuration, enablement, trust, and native actions across all four active runtimes.
-- Added append-only ownership-journal recovery, exact operation dependencies, Linux secure directory-relative publication, and outcomes `applied`, `noop`, `failed`, `blocked_unowned`, `skipped_dependency`, and `action_required`.
-- Added explicit retired cleanup through `agentera upgrade --legacy-cleanup claude --dry-run|--yes`; it can remove only the ledger-owned legacy Agentera skill link and excludes user data.
+- Added one shared skill at `~/.agents/skills/agentera` plus the CLI and entity-backed project state as the active integration contract; host-native plugin, hook, agent, and package surfaces are not shipped.
+- Retained runtime lifecycle contracts only as migration evidence and for explicit `agentera upgrade --legacy-cleanup claude --dry-run|--yes`, which can remove only the ownership-proven legacy Agentera skill link and excludes user data.
 - Added typed artifact writes under `agentera state`: progress/decision/audit appends, decision satisfaction updates, plan create/task/status/archive lifecycle operations, schema-derived `explain`, server-assigned identifiers, exact retry replay, dry-run diffs, project locking, strict mapped-path safety, staged 10/40/50 compaction, final-byte validation, and atomic publication.
 - Added `install_track` to `prime --format json` (`app_home.install_track`) and `doctor --format json`. Values are `v2`, `v3`, `source`, and `unknown`.
-- Added the native TypeScript CLI on the npm development channel (`npx -y agentera@next`), bundling app data at pack time via `prepack` (`tsc` + `scripts/copy-bundle.mjs`) and the `.agentera-npx-bundle.json` sentinel checked by `packages/cli/test/packaging/prepack.test.ts`.
-- Added `bash scripts/single-binary.sh` and the packaging contract in `docs/packaging/v3-packaging.md` for Bun `--compile` single-binary delivery alongside the npm tarball.
+- Added the TypeScript CLI on the npm development channel (`npx -y agentera@next`), bundling app data at pack time via `prepack` (`tsc` + `scripts/copy-bundle.mjs`) and the `.agentera-npx-bundle.json` sentinel checked by `packages/cli/test/packaging/prepack.test.ts`.
 - Added `packages/cli/src/migrate/v2HandoffManifest.ts` to read `v3-handoff.json` during v2→v3 cleanup preflight per `references/cli/v3-handoff-manifest.schema.yaml`.
 - Added v3 `agentera doctor` coexistence detection in `packages/cli/src/upgrade/coexistenceProbe.ts` with regression coverage in `packages/cli/test/cli/coexistenceProbe.test.ts`.
 - Added maintainer gates under `agentera check` (`validate`, `verify`, `lint`, `compact`) with JSON parity oracles for validate families, verify eval targets, invalid-input envelopes, and `source_contract` emissions on `prime`, `prime --context`, `state plan`, and `state query --list-artifacts`.
@@ -51,13 +47,6 @@
 
 ### Changed
 
-- Changed `agentera state migrate` to inventory legacy project state locally within
-  bounded file and byte limits, retain custom names with explicit provenance, and
-  require exact selectors plus `--apply --force` before immutable archive, backup,
-  and projection publication.
-- Changed `agentera state backfill` to remain optional local-Git enrichment: direct
-  `--apply --force` revalidates the project, `HEAD`, candidate, reachability, and
-  immutable target, while bounded history and no-remote behavior remain explicit.
 - Changed deterministic plan lifecycle migration to run inside the full
   development-channel v2-to-v3 upgrade. Legacy `active` and `completed` plan
   statuses become `open` and `complete` without rewriting retained task
@@ -72,12 +61,8 @@
 - Defined plan lifecycle status as `open` or `complete`, with activity derived from the current-plan path and forced unfinished archives remaining open and non-executable.
 - Enforced plan lifecycle surface classification with a bounded repository scan covering readers, writers, migrators, schemas, adapters, fixtures, and documented commitments.
 - Expanded lifecycle classification to every repository surface outside documented vendor, cache, generated-output, snapshot, symlink, and secret exclusions.
-- Changed v3 development-channel dry-runs without `--runtime` to show all active runtime lifecycle findings; generated lifecycle apply commands include `--runtime all --yes`, while apply without a selector remains app-only.
-- Changed lifecycle repair to fail closed on incomplete ownership provenance, isolate narrowed runtime selectors, and count explicit Claude cleanup separately from active-runtime work.
-- Changed corrupt or disconnected ownership-journal blockers to report stable causes without volatile event filenames across preview and apply.
-- Synchronized lifecycle projections across prime, status, project integration, and doctor while keeping Cursor CLI required, IDE conditional, and Claude cleanup explicit.
-- Changed lifecycle apply so native installation, update, authentication, enablement, and trust are always user-owned `action_required` steps. Automatic filesystem apply is Linux-only; other platforms retain complete preview and diagnosis.
-- Changed the npm package to include every declared OpenCode, Codex, Cursor, and GitHub Copilot manifest/hook/agent source and to reject package, documentation, runtime-ID, or version parity drift during validation.
+- Separated source verification from package-boundary verification: source tests validate repository behavior, while extracted-package tests validate the self-contained CLI, shared skill, bundled contracts, and absence of host-native package surfaces.
+- Changed packed v2-to-v3 upgrade reruns to converge after exact partial targets or completed migration, preserving canonical entity identities and producing no additional project or home-directory changes.
 - Renamed the top-level `bundle` field to `app` in `prime --format json`. Nested names are now `activeAppRoot`, `cliApp`, and `legacyAppRoot`; this is a breaking JSON output change.
 - Added v2/v3 coexistence warning to the orientation attention list when a v2 managed app is detected at the app home alongside a v3 CLI runtime. Uses the existing "pick one line" contract message from `references/cli/coexistence-probe.yaml`.
 - Promoted English names to canonical v3 capability IDs (`status`, `vision`, `discuss`, `research`, `plan`, `build`, `optimize`, `audit`, `document`, `profile`, `design`, `orchestrate`) and retired Swedish `-era` IDs from the active command surface.
@@ -89,6 +74,9 @@
 
 ### Fixed
 
+- Fixed overlapping `upgrade --yes` runs to hold separate exclusive project and shared-runtime locks, reject stale or malformed lock state with bounded manual recovery, and release only a matching ownership token.
+- Fixed migration-required recovery commands to shell-quote project paths so shell substitutions remain literal and the intended project receives the v2-to-v3 cutover.
+- Fixed marker-absent v2 projects to select the entity cutover from project state under npm or source v3 execution, so the recovery command emitted by `prime` can complete the forward migration instead of reporting an unrelated no-op.
 - Fixed post-cutover routine query aliases, canonical-boundary Git recovery, migration-marker evidence binding, entity page byte caps, plan recovery guidance, and nested entity identity metadata.
 - Fixed the npm shim to diagnose a configured `AGENTERA_HOME` whose managed script is missing or not runnable before continuing through repository and `uvx` fallback resolution.
 - Fixed `agentera check lint` to report findings without failing by default, fail the same findings with `--strict`, and keep invalid input, authority failures, and validated plan publication nonzero.
@@ -113,7 +101,7 @@
 - Fixed `cliDistributionMajor` silently defaulting to v2 when `registry.json` version-authority was missing or corrupted. The function now reads `package.json#version` as a secondary signal before falling back to 2, and emits a one-time stderr diagnostic when both primary and secondary signals miss — preventing v3 installs with corrupted registry assets from being misclassified as v2 in runtime inference, cross-major boundary detection, channel resolution, and next-major doctor rendering.
 - Fixed `pnpm install` failing on hosts with a system-wide `vips` (Arch, Fedora, Nix with vips overlay, Homebrew on macOS): sharp's `useGlobalLibvips()` check returned true and the install hook fell through to a `node-gyp` source build that needed `node-addon-api`. Migrated the deprecated `pnpm.onlyBuiltDependencies` and `pnpm.overrides` from `package.json#pnpm` to `pnpm-workspace.yaml` (pnpm 10+ ignores the legacy key) and added a `preinstall` hook that re-execs `pnpm install` with `SHARP_IGNORE_GLOBAL_LIBVIPS=true` so sharp's prebuilt binary is always used.
 - Fixed `pnpm install` emitting `Failed to replace env in config: ${NPM_TOKEN}` on every invocation: scoped the npm auth config from repo root to `packages/cli/.npmrc`. Both publishing packages (the `agentera` 3.0 CLI on `@next` and the `agentera` 0.0.x shim on `@latest`) find the auth via npm's parent-directory walk; `pnpm install` from the repo root no longer reads any auth-bearing `.npmrc`.
-- Fixed v3 `agentera upgrade` skipping in-tree `.cursor/agents/*.md` copy-agent steps when the project already uses v3 capability instruction modules, so managed Cursor agents keep `Run agentera prime --context <name> --format json` instead of regressing to `Read …/capabilities/<name>/instructions.md`.
+- Fixed v2-to-v3 migration skipping tracked legacy `.cursor/agents/*.md` inputs when the project already contains v3 capability instruction modules, so cleanup processes those migration inputs consistently.
 - Fixed `agentera prime --context orkestrera --format json` returning empty `dependency_ready_tasks` when plan `depends_on` references were complete but normalized differently from task numbers.
 - Fixed v2→v3 migration tests leaking OpenCode skill symlinks into the developer's real home by requiring `MigrationContext.env` in `planRuntimeMigrationItems` and adding `noHomeLeak.test.ts`.
 - Fixed `link-skill` apply failing on pre-existing dangling symlinks by unlinking symlink targets via `lstat` before `symlinkSync`.
@@ -126,11 +114,13 @@
 - Removed v1 legacy migration paths, standalone skill bundle wording, and obsolete v1 fixture assumptions from the 3.x tree after the 3.0 boundary (`packages/cli/test/cli/v1LegacyCruft.test.ts` guards against reintroduction).
 - Removed `hej`, `describe`, and `gate` from top-level `agentera --help` and dispatch; unsupported structured requests return runnable corrections to `agentera prime`, `agentera schema`, and `agentera check compact`.
 - Removed the requirement for `uv` or a git checkout on the development channel; `uvx --from git+https://github.com/jgabor/agentera@main agentera` remains the stable 2.x Python line only.
+- Removed `agentera state migrate`, `agentera state backfill`, projection repair, and automatic v1 conversion. Recognized v2 aggregate projects now have one forward mutation path: full `agentera upgrade --yes`; `state migrate entities --dry-run` remains read-only.
+- Removed host-native runtime selectors, repair actions, package manifests, plugins, hooks, agents, and Bun single-binary delivery from the v3 distribution. Migration fixtures, ownership evidence, and explicit Claude cleanup remain internal migration surfaces.
 
 ### Migration notes
 
 - **npm shim 0.0.2 v3 deprecation hint**: the `agentera@0.0.2` npm shim on `@latest` now emits a three-line stderr banner on every invocation pointing users to `npx -y agentera@next prime` for the v3 TypeScript CLI. `--help` lists the `@next` command; the install-help failure path leads with the `@next` pointer; `--version` stays banner-free so `--json` and pipe consumers stay clean. Set `AGENTERA_NO_V3_HINT=1` to suppress for CI and scripted invocations.
-- **npm shim 0.0.0 cwd preservation**: the `agentera@0.0.0` npm shim on `@latest` now forwards the user's working directory to the installed Python CLI for the `app-home` backend, so `npx -y agentera` state and prime reads resolve the project's `.agentera/` artifacts instead of the app home. The shim remains the 2.x transitional entry point; the native TypeScript CLI is `npx -y agentera@next` until the 3.0 cutover graduates `@latest`.
+- **npm shim 0.0.0 cwd preservation**: the `agentera@0.0.0` npm shim on `@latest` now forwards the user's working directory to the installed Python CLI for the `app-home` backend, so `npx -y agentera` state and prime reads resolve the project's `.agentera/` artifacts instead of the app home. The shim remains the 2.x transitional entry point; the TypeScript CLI is `npx -y agentera@next` until the 3.0 cutover graduates `@latest`.
 
 ## [2.7.7] · 2026-06-03
 

package/bundle/README.md

@@ -26,48 +26,27 @@ Run that from a git project. In an editor runtime, invoke `/agentera`
 (`$agentera` in Codex) for the rendered status dashboard.
 
 `prime` is deliberately bounded: it summarizes current project state and the
-next useful action. Use `doctor` when you need detailed install and runtime
-evidence.
+next useful action. Use `doctor` when you need app, project-state, shared-skill,
+and CLI evidence.
 
 ```bash
 npx -y agentera@next prime --format json
 npx -y agentera@next doctor --format json
 ```
 
-## Supported runtimes
+## Runtime integration
 
-Agentera 3.0 has exactly four active runtime identities:
+Agentera 3.0 uses one portable integration for compatible runtimes: the shared
+skill at `~/.agents/skills/agentera` plus the Agentera CLI. Normal `upgrade`
+previews and applies only app/project migration; it has no current-runtime
+selector and creates no native plugin, hook, agent, command, descriptor, or
+marketplace file. See [UPGRADE.md](./UPGRADE.md) for the distinct one-way v2
+migration and explicit retired Claude cleanup route:
+`agentera upgrade --legacy-cleanup claude --dry-run|--yes`.
 
-- OpenCode
-- Codex
-- Cursor
-- GitHub Copilot
-
-Cursor Agent CLI is the required Cursor surface and Cursor IDE is conditional;
-both belong to the single `cursor` runtime identity. The canonical portable
-skill is `~/.agents/skills/agentera`.
-
-On the v3 development channel, a dry-run without a selector previews lifecycle
-findings for all active runtimes without making changes. Approve Agentera-owned
-runtime operations separately:
-
-```bash
-npx -y agentera@next upgrade --runtime all --dry-run
-npx -y agentera@next upgrade --runtime all --yes
-```
-
-You can replace `all` with `opencode`, `codex`, `cursor`, or `copilot`.
-Preview creates no files, directories, locks, caches, telemetry, or state
-changes. Apply writes only declared Agentera-owned resources. Native package
-installation, authentication, enablement, and trust remain user-owned and are
-reported as `action_required`.
-
-Secure automatic lifecycle apply currently requires Linux `/proc/self/fd`.
-Other platforms still receive the complete preview and explicit manual actions,
-but filesystem operations remain `action_required`.
-
-`prime`, status, and project-integration output summarize the same lifecycle
-snapshot, including runtime counts, blockers, and the recommended next action.
+`doctor` reports read-only app, project-state, shared-skill, and CLI evidence.
+`prime`, status, and project-integration output use the app/project recommendation
+and shared-skill diagnosis to select the next action.
 
 Claude Code is retired from active support. Its only lifecycle command is a
 separate, explicit cleanup of the exact Agentera-owned legacy skill link:

package/bundle/UPGRADE.md

@@ -1,141 +1,74 @@
-# Upgrade and runtime lifecycle
+# Upgrade and migration
 
-Agentera 3.0 uses one upgrade command for project/app migration and explicitly
-selected runtime lifecycle work. Preview and apply are separate operations.
+Agentera 3.0 uses one upgrade command for app/project migration and explicit
+retired Claude cleanup. Preview and apply are separate operations. Current
+runtime installation and repair are not upgrade operations.
 
 Before the npm stable dist-tag promotion, use `agentera@next`. The stable 2.x
-channel remains `agentera@latest` until that promotion; this repository does
-not publish or retag as part of an upgrade run.
+channel remains `agentera@latest` until that promotion; upgrade does not publish
+or retag packages.
 
-## Start with a preview
+## Active integration
 
-```bash
-npx -y agentera@next upgrade --dry-run --channel development
-```
+Agentera has one active integration contract:
 
-On the v3 development channel, a dry-run without `--runtime` also observes all
-active runtimes so blocked app or channel phases do not hide lifecycle findings.
-The preview remains read-only. Runtime apply is explicit:
-
-```bash
-npx -y agentera@next upgrade --runtime all --dry-run
-npx -y agentera@next upgrade --runtime cursor --dry-run
+```text
+~/.agents/skills/agentera + agentera CLI
 ```
 
-The active runtimes are OpenCode, Codex, Cursor, and GitHub Copilot. Selectors
-are `all`, `opencode`, `codex`, `cursor`, and `copilot`.
-`cursor-agent` is not a selector: Cursor Agent CLI and Cursor IDE are surfaces
-of the one `cursor` identity. CLI is required; IDE is conditional.
+Normal `prime`, `doctor`, `schema`, help, and project-integration output reports
+that shared skill and CLI/app/project state. Normal `upgrade` has no
+current-runtime selector or native-resource operation set. It creates no current
+plugin, hook, agent, command, descriptor, or marketplace file and does not run
+runtime package managers, authentication, enablement, or trust operations.
 
-The preview is strictly read-only. It creates no files, directories, locks,
-caches, ownership journals, telemetry, or other state changes. Its output
-includes:
+Passing `--runtime` fails before mutation. Remove `--runtime`, ensure the runtime
+can read `~/.agents/skills/agentera`, and invoke the CLI directly. The supported
+v2 migration and Claude cleanup routes below are separate from normal active
+integration.
 
-- observed runtime and surface evidence;
-- skill, plugin, hook, agent, configuration, enablement, trust, and native-action state;
-- planned operations and dependencies;
-- current ownership evidence and blocked reasons;
-- exact manual or host-native actions;
-- required support-floor gaps.
+## Preview and apply
 
-`prime` exposes a bounded projection of the same snapshot. `doctor` exposes the
-detailed read-only diagnosis:
+Preview normal app/project work:
 
 ```bash
-npx -y agentera@next prime --format json
-npx -y agentera@next doctor --format json
+npx -y agentera@next upgrade --dry-run --channel development
 ```
 
-Status and project-integration recommendations use the same lifecycle identity,
-counts, blockers, and retry guidance as `prime` and `doctor`.
-
-## Apply approved Agentera-owned work
-
-After reviewing an all-runtime preview, use its generated command or rerun the
-selection explicitly with `--runtime all --yes`:
+The preview is strictly read-only: it creates no files, directories, locks,
+caches, ownership records, telemetry, or other state. Apply only after reviewing
+the generated command:
 
 ```bash
-npx -y agentera@next upgrade --runtime all --yes
+npx -y agentera@next upgrade --yes --channel development
 ```
 
-An apply invoked without `--runtime` retains the existing app-only behavior.
-Named selectors such as `--runtime cursor` limit runtime-specific writes to that
-identity. Stable-channel v2 behavior remains app-only.
-
-Apply can write only resources declared by the lifecycle contract and proven
-Agentera-owned by the append-only ownership journal. Matching names or bytes do
-not establish ownership. User-owned, ambiguous, shadowed, or malformed targets
-remain blocked.
-
-For every blocked collision, the exact remediation is: “The destination is not
-ledger-owned; review the collision manually. Agentera will not adopt it by name
-or equality.” The destination remains unchanged until authoritative ownership is
-available.
-
-The operation outcomes are:
-
-- `applied` — the declared change was published;
-- `noop` — desired state was already exact;
-- `failed` — this operation failed; independent operations may continue;
-- `blocked_unowned` — ownership was not proven;
-- `skipped_dependency` — a prerequisite did not complete;
-- `action_required` — the user or host must perform the step.
+`prime` and `doctor` expose the same app/project classification and shared-skill
+state:
 
-Retries are designed to converge. Completed work becomes `noop`; failed or
-pending work is re-observed and retried. Corrupt, forked, disconnected, or
-non-contiguous ownership journals fail closed.
-
-Secure automatic filesystem publication currently requires Linux
-`/proc/self/fd`. On macOS, Windows, or a Linux environment without that secure
-primitive, preview and diagnosis still work but mutation is returned as
-`action_required`.
-
-## Ownership and trust boundary
-
-The canonical skill is:
-
-```text
-~/.agents/skills/agentera
+```bash
+npx -y agentera@next prime --format json
+npx -y agentera@next doctor --format json
 ```
 
-Agentera can maintain declared Agentera-owned skill, plugin, hook, and agent
-resources. It does not run native runtime package managers or approve:
-
-- runtime installation or self-update;
-- authentication;
-- plugin or hook enablement;
-- trust prompts or organizational policy;
-- user-owned configuration collisions.
-
-Those steps are reported with exact remediation and remain user-owned.
-
-## Cursor lifecycle
-
-Cursor is one runtime identity with two surfaces:
-
-| Surface | Support-floor role | Typical source |
-| --- | --- | --- |
-| Agent CLI | required | Cursor CLI binary and canonical shared skill |
-| IDE | conditional | `.cursor-plugin/plugin.json`, `.cursor/hooks.json`, `.cursor/agents/` |
-
-An absent IDE does not block a CLI-only installation. Once IDE evidence is
-present, its incomplete or denied mandatory evidence is reported beneath the
-same Cursor identity.
+Retries re-observe the current app/project state. Completed migration work
+converges to no change; interrupted v2 migration continues through the same full
+apply command.
 
 ## Retired Claude cleanup
 
-Claude Code is not an active Agentera runtime and cannot be passed to
-`--runtime`. Its legacy cleanup is a separate explicit selection:
+Claude cleanup is a distinct historical route, not a current-runtime selection:
 
 ```bash
 npx -y agentera@next upgrade --legacy-cleanup claude --dry-run
 npx -y agentera@next upgrade --legacy-cleanup claude --yes
 ```
 
-Cleanup is limited to the exact Agentera-owned legacy skill link recorded by
-the ownership ledger. It never removes Claude projects, transcripts, settings,
+Cleanup is limited to the exact Agentera-owned legacy skill link recorded by the
+ownership journal. It never removes Claude projects, transcripts, settings,
 credentials, caches, or other user data. Ambiguous or unowned resources remain
-blocked.
+blocked. Preview is read-only; apply is idempotent and can be retried with the
+same explicit selection.
 
 Historical transcript import is independent of cleanup. Default extraction and
 analytics do not read Claude history. Import requires explicit local consent:
@@ -145,9 +78,9 @@ npx -y agentera@next report refresh --import-source claude
 ```
 
 Imported records carry `historical_import` provenance, have no active runtime
-ID, and remain excluded from default active-runtime analytics.
+ID, and remain excluded from default active-source analytics.
 
-## Recommended upgrade v1 & v2 stable channel
+## Stable v2 line
 
 The stable `@latest` channel remains on the supported 2.x line. Preview before
 applying an in-line upgrade:
@@ -157,65 +90,35 @@ npx -y agentera@latest upgrade --dry-run
 npx -y agentera@latest upgrade --yes
 ```
 
-Use the v3 development migration below only when you explicitly intend to
-leave the stable line.
+Use the v3 development migration below only when you explicitly intend to leave
+the stable line.
 
-## Upgrading v2 to v3 development channel (irreversible)
+## Upgrading v2 to v3 development channel
 
-Use the development channel explicitly while 3.0 is on `@next`:
+Recognized marker-absent v2 aggregate state has one supported forward route:
 
 ```bash
 npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
 npx -y agentera@next upgrade --channel development --project "$PWD" --yes
 ```
 
-The dry-run is optional and read-only. Before applying, commit or restore the
-complete v2 migration source: every input must be a regular file tracked by Git
-and unchanged at `HEAD`. The apply command performs the full runtime and entity
-state upgrade, then validates state and representative `prime` startup.
-
-Forward migration to v3 is one-way. Returning to the Python 2.x line is not
-supported, and cross-major apply has no rollback, restore, non-Git, or partial
-workflow. If an apply is interrupted, rerun the same full apply command to
-continue forward.
-
-## Legacy state and optional Git enrichment
-
-Project-state migration and historical Git enrichment are separate local
-operations. Migration does not read Git, contact a remote, or remove its source
-files. Its default inventory and `--dry-run` are read-only; apply requires the
-exact artifact and entry selectors with `--apply --force`:
-
-```bash
-npx -y agentera@next state migrate --project "$PWD" --artifact progress --number N --dry-run --format json
-npx -y agentera@next state migrate --project "$PWD" --artifact progress --number N --apply --force --format json
-```
-
-Git enrichment is optional. A preview is useful but not required before direct
-apply. Inventory and preview may use the current working directory when
-`--project` is omitted; direct apply must name `--project PATH` explicitly.
-Apply revalidates the selected project, current `HEAD`, allowed-ref
-reachability, candidate provenance and content, and the immutable archive target
-immediately before publication:
+The optional preview is read-only. Before apply, commit or restore the complete
+v2 migration source: every input must be a regular file tracked by Git and
+unchanged at `HEAD`. Apply performs the full project rewiring and entity-state
+cutover, then validates state and representative `prime` startup. Rewiring may
+update recognized v2 project files; it does not install current native resources.
 
-```bash
-npx -y agentera@next state backfill --project "$PWD" --artifact progress --number N --dry-run --format json
-npx -y agentera@next state backfill --project "$PWD" --artifact progress --number N --apply --force --format json
-```
+Forward migration is one-way. Returning to the Python 2.x line is unsupported,
+and cross-major apply has no rollback, restore, non-Git, or partial workflow.
+If apply is interrupted, rerun the same full apply command.
 
-The backfill contract is bounded to 100 result rows, 500 history units, and
-16 MiB of Git output. It inspects only `HEAD`, local heads, and tags; remote and
-custom refs and operations are excluded. Returned provenance keeps the commit,
-path, blob ID, stable entry ID, content hash, and reachability so a result can
-be traced without adding commit fields to the archive record.
+## Unsupported legacy state
 
-`complete`, `degraded`, `blocked`, and `unavailable` are explicit outcomes.
-Changed, shallow, rewritten, ambiguous, corrupt, missing, bounded, unavailable,
-and immutable-conflict results are reported rather than guessed. Resolve the
-reported local condition and retry the same selectors; refused operations leave
-active projections and existing archives unchanged, and identical publication
-converges as a replay. The full command, limits, failure, recovery, and
-traceability contract is `references/artifacts/state-storage-authority.yaml`.
+Pending v1 Markdown state and unknown marker-absent state are not automatic
+mutation inputs. `state migrate`, `state backfill`, projection repair, v1
+conversion, restore, and downgrade are unsupported. The read-only
+`state migrate entities --dry-run` diagnostic may inventory cutover input but
+cannot publish it.
 
 ## Verification and recovery
 
@@ -227,14 +130,11 @@ npx -y agentera@next prime --format json
 ```
 
 `upgrade --verify` without `--yes` is a read-only doctor and capability-context
-verification. With `--yes`, it runs those checks after the approved upgrade
-apply. Lifecycle selections with `--verify` require `--yes`.
-For lifecycle partial failure, rerun the same preview and apply selection. Do
-not delete or hand-edit the ownership journal to force adoption.
+verification. With `--yes`, it runs those checks after approved migration.
+Explicit Claude cleanup with `--verify` requires `--yes`.
 
 `--force` applies only where the owning migration contract explicitly permits
-replacement. It does not convert user-owned resources into Agentera-owned
-resources and does not approve native or trust actions.
+replacement. It never adopts user-owned resources.
 
 ## Maintainer verification
 
@@ -244,8 +144,14 @@ Release preparation does not publish, tag, or push:
 pnpm -C packages/cli test
 pnpm -C packages/cli run typecheck
 pnpm -C packages/cli build
-node packages/cli/dist/bin/agentera.js check validate lifecycle-adapters
+node packages/cli/dist/bin/agentera.js check validate capability-contract --format json
 node packages/cli/dist/bin/agentera.js check validate release-metadata
-pnpm -C packages/cli run bundle:data
-npm pack --dry-run --json --ignore-scripts
 ```
+
+## Mutation ownership
+
+Upgrade apply holds the required project lock before migration begins. Explicit
+Claude cleanup additionally uses its ownership journal and shared lock. Lock
+creation is atomic, and release succeeds only for the matching ownership token.
+A stale or malformed lock stops the operation; inspect the named lock file,
+remove only that file after confirming no operation owns it, then rerun.