agentera 3.0.0-dev.25 → 3.0.0-dev.27

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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,20 +68,30 @@ 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
 
 Requires Node.js 22+ and pnpm 10.30.3.
 
+### Generated-output ownership and recovery
+
+The canonical producer, reader, packing, retention, and recovery contract is
+[v3 npm packaging and verification](../../docs/packaging/v3-packaging.md).
+Generated generations are disposable; source files and the package registry
+remain authoritative. Use its recovery matrix rather than deleting uncertain
+state.
+
 ```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 verify:generated-overlap
+pnpm -C packages/cli run generated:cleanup -- --dry-run --json
 pnpm -C packages/cli run lint
 ```
 
-Use `npm pack --dry-run --json --ignore-scripts` after `build` and
-`bundle:data` to inspect the exact publication surface. Do not publish from a
-normal development or capability cycle.
+Use `pnpm -C packages/cli run pack:dry-run` to inspect the exact isolated
+publication surface. Do not publish from a normal development or capability
+cycle.

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`) as a self-contained package whose governed isolated construction stages compiled commands, registry-owned app data, and the `.agentera-npx-bundle.json` sentinel before packing with lifecycle scripts disabled.
 - 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,12 @@
 
 ### Fixed
 
+- Fixed overlapping source, build, and package verification to use isolated construction and one atomically selected `dist` + `bundle` generation; clean source no longer requires checkout output, package proof still runs from an extracted tarball, and `pnpm -C packages/cli run pack:dry-run` replaces direct checkout `npm pack`.
+- Fixed `agentera prime --context status` to report severity totals across every open TODO while keeping attention and routing detail bounded with explicit omission recovery.
+- Fixed `agentera prime --context status` to exclude resolved entity TODOs before bounded pagination, so severity counts, attention, and next-action routing reflect only open work.
+- 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 +104,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 +117,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: