agentera 3.0.0-dev.23 → 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:
 
@@ -60,10 +56,10 @@ and is projected by `agentera schema --format json`.
 
 ```bash
 agentera state plan list --format json
-agentera state plan get --plan PLAN_ID --format json
+agentera state plan get --id PLAN_ID --format json
 agentera state plan tasks list --limit 20 --format json
 agentera state experiments list --objective OBJECTIVE_ID --format json
-agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+agentera state experiments get --objective OBJECTIVE_ID --id EXPERIMENT_ID --format json
 ```
 
 Pages use opaque snapshot cursors, explicit omission fields, whole-entry output
@@ -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,6 +4,8 @@
 
 ### Changed
 
+- 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`.
 - Changed `agentera check lint` verbosity checks to consume schema-owned full-file and per-entry word limits, skip no-limit and token-only dimensions, and report authority failures without fallback budgets.
@@ -12,6 +14,11 @@
 
 ### Added
 
+- 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.
 - Added an authoritative evidence-tier contract (`references/analysis/evidence-tier-authority.yaml`) and contract-model loader (`packages/cli/src/registries/evidenceTierContract.ts`) fixing the bounded full-evidence and signal tiers, supported Codex, Cursor, OpenCode, Copilot, and historical Claude source coverage, the consumer field-supply map including the latent startup-analysis reader, reserved signal semantics for the deferred glossary, and deterministic recovery outcomes for oversized, legacy, missing, corrupt, and incomplete state.
 - Added bounded tier publication and direct retrieval (`packages/cli/src/analytics/extractCorpus/evidenceTiers.ts`): complete local evidence is retained as independently bounded, source-family shards that split when exceeding the reader cap; a derived, content-addressable bounded signal tier carries only contract-required fields plus a resolvable `evidence_anchor`; generations are staged and revealed by an atomic current-pointer swap so no consumer observes a partial publication; and direct retrieval resolves a signal identity to its full record. The monolithic `corpus.json` write is eliminated; tiers are the only canonical publication output.
 - Added bounded tier-aware reads for usage analytics, report status, prime corpus coverage, startup analysis, and profile synthesis so every analytics consumer reads from bounded evidence shards one at a time instead of loading the monolithic `corpus.json`. A new `tierReader.ts` module projects contract compatibility states and recovery guidance, streams full-evidence records, and reads signal-tier metadata. A new `profileSignals.ts` module reads the bounded signal tier, assesses per-family retention sufficiency against the contract threshold, and resolves synthesized claims' evidence anchors to retained full-evidence shards. Legacy `corpus.json` remains a fallback when no tiers are published; oversized legacy state is never loaded whole.
@@ -27,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`.
@@ -44,18 +47,11 @@
 
 ### 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 `agentera upgrade --only artifacts` to preview and apply deterministic
-  plan lifecycle migration for docs-mapped current plans and archives. Legacy
-  `active` and `completed` plan statuses become `open` and `complete` without
-  rewriting retained task evidence; archive recency now uses persisted creation
-  dates instead of file modification times.
+- 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
+  evidence; archive recency uses persisted creation dates instead of file
+  modification times.
 - Changed plan reads to normalize legacy `active` and `completed` statuses within
   the current-plan and archive boundary, with structured diagnostics for
   malformed current plans and archives.
@@ -65,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.
@@ -82,6 +74,10 @@
 
 ### 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.
 - Fixed schema/runtime alias parity: introspection now advertises exactly the six Phase 3 transitional aliases, Build startup and compaction guidance use canonical `agentera check compact`, check/fix output reports `command: "check compact"`, top-level `compact` remains behavior-compatible, and removed names such as `gate` return structured runnable corrections.
@@ -105,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`.
@@ -118,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:
@@ -99,10 +78,10 @@ explicit omissions, and exact detail commands. The runtime contract is
 
 ```bash
 agentera state plan list --format json
-agentera state plan get --plan PLAN_ID --format json
+agentera state plan get --id PLAN_ID --format json
 agentera state plan tasks list --limit 20 --format json
 agentera state experiments list --objective OBJECTIVE_ID --format json
-agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+agentera state experiments get --objective OBJECTIVE_ID --id EXPERIMENT_ID --format json
 ```
 
 Plan list/get spans the active plan and immutable plan archives. Plan task
@@ -110,14 +89,15 @@ list/get is active-plan-only. Experiment retrieval merges its bounded projection
 with objective-owned immutable archives and reports detail as full, summary-only,
 or unavailable.
 
-The standard project state is:
+Ordinary mutable state uses one canonical file per entity. Every public record
+has only `id` and `artifact` identity, and is accessed through bounded `list`,
+exact `get --id`, and typed `agentera state <artifact> explain` write contracts.
+Do not edit files under `.agentera/entities/` directly.
+
+The intentional singleton project state is:
 
 - `.agentera/vision.yaml` — product direction
-- `.agentera/plan.yaml` — active and archived plans
-- `.agentera/progress.yaml` — shipped work and verification
-- `.agentera/decisions.yaml` — durable reasoning
-- `.agentera/health.yaml` — architecture and project health
-- `.agentera/docs.yaml` — documentation inventory and path/version mappings
+- `.agentera/docs.yaml` — documentation policy and path/version mappings
 - `TODO.md`, `CHANGELOG.md`, and `DESIGN.md` — human-facing project artifacts
 
 ## Capabilities