agenr 3.3.0 → 2026.6.2

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 ## [Unreleased]
 
+## [2026.6.2] - 2026-06-06
+
+Calendar versioning, host session-memory parity, durable staleness, and package-boundary hardening release.
+
+### Added
+
+- **OpenClaw host session-memory parity.** OpenClaw now uses scoped session identity, compaction transcript handling, pre-compaction episode capture, host-neutral session-memory routing, and before-turn session artifacts that align with the Skeln memory-runtime model.
+- **Memory doctrine and tool guidance.** Shared prompt doctrine, claim-key guidance, project metadata update support, and fetch/update/store tool formatting now give agents clearer instructions and warnings at the tool boundary.
+- **Release-version validation and package syncing.** Calendar release-version parsing plus the package-version sync script keep root package metadata, plugin package metadata, and OpenClaw plugin manifests aligned.
+
+### Changed
+
+- **Release versioning** now follows OpenClaw's `YYYY.M.PATCH` calendar scheme instead of semver. The third component is a monthly patch counter, not a calendar day.
+- **OpenClaw plugin packaging** now ships as a thinner adapter package and defers optional runtime modules while copying shared root build artifacts needed by dynamic imports into plugin packages.
+- **`agenr_update` patch handling** is more focused and docs now distinguish project metadata corrections from durable content corrections.
+- **Database ports** expose `closeDurableValidity` and `closeProcedureValidity` instead of `retireDurable` and `retireProcedure`.
+- **Docs and tests** updated for the staleness model across durables, episodes, procedures, dreaming, and the OpenClaw plugin.
+
+### Breaking
+
+- **Greenfield database only.** Schema versioning and in-place migrations are removed. Startup rejects legacy tables and columns such as `entries`, `retired`, `minhash_sig`, `cluster_id`, `durables_retired`, and `recall_delta`, and rejects partially initialized databases that are missing required tables. Run `agenr db reset` before upgrading.
+- **Removed unused columns.** `durables.minhash_sig`, `durables.cluster_id`, and `dream_run_actions.recall_delta` are dropped from the schema.
+- **Keyed durables require lifecycle status.** Rows with a `claim_key` must also store a valid `claim_key_status`; NULL lifecycle status is no longer treated as legacy at read time.
+- **Retirement flags removed; staleness uses `valid_to`.** `durables`, `episodes`, and `procedures` no longer store `retired`, `retired_at`, or `retired_reason`. Close validity with `valid_to` plus optional `supersession_kind: "stale"` and `supersession_reason` instead.
+- **`agenr_retire` removed.** Use `agenr_update` with `validTo` to close durable validity from OpenClaw hosts.
+- **`agenr_trace` removed from OpenClaw.** Use `agenr trace` for provenance, lineage, and recall-history inspection.
+- **Dreaming prune actions renamed.** Run summaries and `dream_runs.durables_staled` replace `durables_retired`; audit actions use `stale` instead of `retire`.
+- **Neighborhood expansion flag renamed.** Recall adapters accept `includeHistorical` instead of `includeRetired`.
+
+### Fixed
+
+- **Plugin dynamic imports** now resolve shared root dist artifacts from packaged OpenClaw and Skeln plugin builds.
+- **Validation cleanup** clears ESLint warnings so `pnpm check` runs green.
+
+### Validation
+
+Changes since last push to `origin/master`:
+
+- Replace OpenClaw continuity with host session-memory parity, scoped session identity, compaction handling, and shared session-start artifacts
+- Add centralized memory doctrine, stronger claim-key guidance, and project metadata update support
+- Switch releases to OpenClaw-style calendar versions and add package-version sync checks
+- Thin OpenClaw plugin packaging while preserving runtime dynamic-import resolution for plugin packages
+- Replace retirement semantics with valid-time staleness across durable, episode, procedure, dreaming, and recall paths
+- Add dreaming milestone work, compute-efficiency eval seams, directive topic triggers, and concurrency hardening already summarized in the `4.0.0` section below
+- Clear validation issues so `pnpm check` passes before release
+
+## [4.0.0] - 2026-06-05
+
+### Breaking
+
+- **Greenfield schema with `durables` and dreaming tables.** The `entries` table and all `surgeon_*` tables are gone. This build only supports schema version `4` on a fresh database. Delete existing knowledge databases and re-run `agenr init` or `agenr db reset` before upgrading.
+- **`entries` renamed to `durables` across types, SQL, ingest, recall, and scenarios.** There are no compatibility aliases. Extraction JSON now uses a top-level `durables` array.
+- **Surgeon removed; dreaming replaces it.** `agenr surgeon ...` commands, `surgeon` config, and surgeon docs are deleted. Use `agenr dream run|status|history` and the `dreaming` config section instead.
+
+### Added
+
+- **Dreaming Milestone 1 skeleton.** Scan, deterministic reconcile, and apply stages with `dream_runs`, `dream_run_actions`, `dream_proposals`, `dream_state`, and `profile_snapshots` persistence.
+- **Dreaming Milestone 2 injection hardening.** Bi-temporal as-of valid-time filtering shared by session-start, before-turn, and default recall, plus injection-filtering and directive-abstention scenario fixtures and regression tests that prove expired or not-yet-valid durables never auto-inject.
+- **Dreaming Milestone 3 extract and temporalize stages.** The `extract` stage mines durable candidates from episode evidence with content-hash and context-lookup deduplication; the `temporalize` stage revises stale beliefs through supersession (insert successor, close the predecessor valid-time window, link `superseded_by`) without rewriting content in place.
+- **Dreaming proposal review surface.** New `agenr dream actions`, `agenr dream proposals`, `agenr dream backlog`, and `agenr dream review` commands, with backed-up transactional proposal apply.
+- **Session-end episode boundaries.** OpenClaw now writes the current session's episode from its `session_end` hook so dreaming has fresh evidence before the next session starts; the write is best-effort and idempotent by session id. Skeln's shutdown chain writes through the same bounded episode contract.
+- **Dreaming pipeline scenario fixtures.** New fixtures under `tests/scenarios/dreaming/pipeline/` cover implicit-preference capture, trip-lifecycle revision, point-in-time recall, and the no-overconsolidation guard.
+- **Dreaming Milestone 5 release path.** The `prune` stage now closes validity on protected low-signal durables on `standard` and `deep` runs, background `light` runs fire after host session-end episode writes, successful `agenr_store` calls can trigger `light` runs when accumulated durable importance crosses the configured threshold, and completion summaries include compute-efficiency counters for the eval scoreboard.
+- **Dreaming ops hardening (WS6).** A process-wide dreaming lease prevents overlapping CLI, background, store-triggered runs, and host episode writes; the lock heartbeat reclaims rows orphaned by a crashed process after a stale timeout without stealing active long-running runs; episode writes serialize through the same lock before post-session light dreaming; background apply runs record `backupSkipped` in completion summaries; `agenr dream status` warns when recent applied `light` runs skipped backup; and `procedures/agenr-dream-deep-maintenance.yaml` documents weekly deep maintenance.
+- **Dreaming compute-efficiency suite (WS3).** `recomputeRatio` is now `synthesizedDurableMutations / evidenceItemsRead`; a new `POST /internal/evals/dreaming-efficiency/run` seam provisions pre-baked completion summaries and derives efficiency from persisted scan/project/stage counters (Option A); `agenr-evals` ships `manifests/dreaming/compute-efficiency.json` with three regression cases via the `agenr-dreaming-efficiency-http` adapter.
+- **Directive topic triggers (WS4).** Proactive `topic:<term>` directives now surface during before-turn when the current user turn mentions the topic; abstain directives still run last and suppress conflicting topic directives. Session-start behavior for `topic:` triggers is unchanged in v1.
+- **Docs:** `docs/DURABLES.md`, `docs/DREAMING.md`. `docs/STORE.md` and `docs/SURGEON.md` removed.
+
+### Changed
+
+- **Claim-key scenario harness** now supports `dreaming` scenarios instead of `surgeon` scenarios.
+- **Dreaming `deep` tier** now reads the full evidence backlog instead of only the incremental cursor.
+- **Dreaming config parsing** now accepts and persists non-default `tiers`, `stages.extract`, `stages.project`, and `triggers` settings.
+- **Dreaming `light` tier semantics.** Background `light` runs now skip reconcile and prune while keeping temporalize and project, and run summaries record those skips in `stages_skipped`. Light extract defaults to at most two episode sessions per run (`stages.extract.lightMaxSessionsPerRun`).
+- **AGENTS.md, ARCHITECTURE.md, README.md, DEBUGGING.md, and VS Code launch configs** updated for the durable/dreaming nomenclature.
+
 ## [3.3.0] - 2026-06-02
 
 Feature flag defaults, Skeln install policy, and OpenClaw package cleanup release.
@@ -316,7 +392,7 @@ Ingest concurrency and progress reporting patch release.
 
 - **Dedup now honors bounded concurrency.** Multi-entry similarity clusters are now arbitrated in parallel with deterministic result ordering, and ingest paths explicitly thread configured/default concurrency into dedup instead of leaving arbitration serial.
 - **Claim extraction now uses real batch concurrency without violating ordered semantics.** Batch claim-key extraction now honors configured concurrency, preserves past-only hint visibility via per-entry frozen hint snapshots, and propagates sensible defaults through the relevant ingest/store paths instead of falling back to historical hardcoded single-worker behavior.
-- **Ingest spinner now reports real post-extraction stages.** Non-verbose `agenr ingest entries` runs now surface dedup, claim-key extraction, store pipeline, and bulk-write index preparation/finalization stages instead of looking stuck after `(N/N extracted)`.
+- **Ingest spinner now reports real post-extraction stages.** Non-verbose `agenr ingest durables` runs now surface dedup, claim-key extraction, store pipeline, and bulk-write index preparation/finalization stages instead of looking stuck after `(N/N extracted)`.
 
 ### Validation
 
@@ -523,7 +599,7 @@ The surgeon retirement pass — an autonomous agent that evaluates and retires s
 ### Added
 
 - **Surgeon retirement pass.** A standalone agent loop powered by `@mariozechner/pi-agent-core` that evaluates knowledge entries and retires semantically stale ones. Runs as `agenr surgeon run` with full dry-run and apply modes, budget governance, and completion guards.
-- **7 surgeon tools.** `get_health_stats`, `query_candidates`, `inspect_entry`, `simulate_recall`, `retire_entry`, `update_entry`, and `complete_pass` — each adapted from the v0 surgeon for v1's simpler schema.
+- **7 surgeon tools.** `get_health_stats`, `query_candidates`, `inspect_durable`, `simulate_recall`, `retire_durable`, `update_durable`, and `complete_pass` — each adapted from the v0 surgeon for v1's simpler schema.
 - **Recall simulation without telemetry.** The `simulate_recall` tool wraps the v1 recall pipeline with a no-op telemetry adapter and optional target-entry exclusion, so the surgeon can test retrieval impact without polluting recall metrics.
 - **Surgeon CLI commands.** `agenr surgeon run`, `agenr surgeon status`, `agenr surgeon history`, and `agenr surgeon actions <run-id>` for running, inspecting, and auditing surgeon passes.
 - **Surgeon status shows evaluation coverage.** `agenr surgeon status` now displays recently evaluated vs new candidates, so you can see how much work remains before running.
@@ -535,7 +611,7 @@ The surgeon retirement pass — an autonomous agent that evaluates and retires s
 
 ### Changed
 
-- **Schema version bumped to 2.** The `surgeon_runs` table is expanded with pass type, status, token/cost tracking, model, dry-run flag, and structured summary fields. A new `surgeon_run_actions` table logs individual surgeon actions with indexed `entry_id` for efficient recently-evaluated queries. Existing databases are migrated automatically via `ALTER TABLE ADD COLUMN`.
+- **Schema version bumped to 2.** The `surgeon_runs` table is expanded with pass type, status, token/cost tracking, model, dry-run flag, and structured summary fields. A new `surgeon_run_actions` table logs individual surgeon actions with indexed `durable_id` for efficient recently-evaluated queries. Existing databases are migrated automatically via `ALTER TABLE ADD COLUMN`.
 - **Protection threshold raised to importance ≥ 9.** Entries with importance 8 are now eligible for surgeon evaluation since many entries default to importance 8 during ingestion.
 - **Setup prompt updated.** The advanced model override prompt now reads "Customize task-specific models?" to reflect the addition of surgeon alongside extraction and dedup overrides.
 

package/README.md

@@ -27,9 +27,9 @@ What makes agenr different is the combination of local-first storage, semantic e
 - Procedural memory: repo-authored YAML procedures synced into durable structured runbooks for repeatable how-to workflows.
 - LLM-powered knowledge extraction from conversation transcripts.
 - Semantic deduplication using exact hashes, normalized hashes, embeddings, and within-run clustering.
-- Session continuity with predecessor resolution, recent transcript tails, and LLM-generated continuity summaries.
-- Surgeon maintenance passes for corpus health: claim-key quality, proposal resolution, supersession review, and retirement cleanup, all with audit history.
-- Agent tools for durable memory through the OpenClaw plugin (`store`, `recall`, `retire`, `update`, and `trace`) and the Skeln plugin (`store`, `recall`, `update`, `work`, and goal aliases).
+- Session-end episode ingest for the just-finished OpenClaw session.
+- Dreaming maintenance pipeline for corpus health: tiered scan, deterministic reconcile, and apply with audit history.
+- Agent tools for durable memory through the OpenClaw plugin (`store`, `recall`, `fetch`, `update`, and `trace`) and the Skeln plugin (`store`, `recall`, `update`, `work`, and goal aliases).
 - Native OpenClaw memory plugin that replaces OpenClaw's built-in memory slot.
 - Skeln extension with working-memory tools, goal aliases, and shared recall/store semantics.
 - Local-first storage with SQLite/libSQL. Memory stays on your machine; only model and embedding calls leave it.
@@ -70,7 +70,7 @@ The OpenClaw plugin id remains `agenr`, so `plugins.entries.agenr`, `plugins.slo
 After the plugin is installed, `openclaw plugins update agenr` continues to target that same plugin id.
 If `plugins.entries.agenr.config` is omitted, the plugin falls back to agenr's normal config resolution: `AGENR_CONFIG_PATH`, then `~/.agenr/config.json`, and the `dbPath` from that config or `~/.agenr/knowledge.db`.
 
-If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/openclaw-plugin@3.0.0`.
+If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/openclaw-plugin@2026.6.1`.
 
 For local development or a custom build path, run `pnpm build` first and point OpenClaw at the plugin package root:
 
@@ -140,7 +140,7 @@ Important: when agenr is running as an OpenClaw plugin, session summaries and st
 Compatibility policy:
 
 - Agenr only supports the current `config.json` shape. Move any legacy `apiKey` value into `credentials.openaiApiKey` or `credentials.anthropicApiKey`, move any `embeddingApiKey` value into `credentials.openaiApiKey`, then remove the legacy fields.
-- Agenr only supports fresh databases and databases already at the current schema version. Older schema versions are no longer auto-migrated at startup.
+- Agenr only supports fresh databases created by the current schema. Run `agenr db reset` before upgrading when the knowledge database predates the current shape.
 
 ## What You Need
 
@@ -152,30 +152,26 @@ Compatibility policy:
 
 The CLI surface is still intentionally compact, but it now covers setup, recall, ingest, and corpus maintenance.
 
-| Command                             | What it does                                                                                                                                                           |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agenr init`                        | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion.                                               |
-| `agenr setup`                       | Configure auth, model defaults, embeddings, and the agenr database path.                                                                                               |
-| `agenr recall <query>`              | Run the hybrid recall pipeline with optional temporal and type/tag filters.                                                                                            |
-| `agenr trace`                       | Inspect one entry's provenance and claim-family lineage by id, subject, or `--last`.                                                                                   |
-| `agenr ingest <path>`               | Default durable-entry ingest shorthand. Equivalent to `agenr ingest entries <path>`.                                                                                   |
-| `agenr ingest entries <path>`       | Bulk-ingest one file or directory of OpenClaw transcript files into durable knowledge entries.                                                                         |
-| `agenr ingest episodes [path]`      | Backfill episodic summaries from OpenClaw session transcripts, including rotated `.reset.*` and `.deleted.*` files.                                                    |
-| `agenr ingest procedures [path]`    | Sync repo-authored YAML procedures into procedural-memory revisions stored in the knowledge database.                                                                  |
-| `agenr surgeon run`                 | Execute surgeon maintenance. Defaults to the autonomous multi-pass sequence; use `--pass <type>` for one pass. Dry-run by default; add `--apply` to mutate the corpus. |
-| `agenr surgeon status`              | Show corpus health, claim-key lifecycle counts, proposal backlog, and the latest surgeon run summary.                                                                  |
-| `agenr surgeon history`             | Show recent surgeon runs.                                                                                                                                              |
-| `agenr surgeon actions <runId>`     | Show the audit trail for one surgeon run.                                                                                                                              |
-| `agenr surgeon backlog`             | List open surgeon proposals across runs.                                                                                                                               |
-| `agenr surgeon proposals <runId>`   | Show proposals recorded for one surgeon run.                                                                                                                           |
-| `agenr surgeon review <proposalId>` | Apply or reject one open proposal.                                                                                                                                     |
-| `agenr scenarios list`              | List repo-local claim-key sandbox scenarios.                                                                                                                           |
-| `agenr scenarios run`               | Run one or more claim-key sandbox scenarios.                                                                                                                           |
-| `agenr db reset`                    | Delete and recreate the knowledge database.                                                                                                                            |
-
-The OpenClaw plugin also gives the agent five tools directly inside the runtime: `agenr_store`, `agenr_recall`, `agenr_retire`, `agenr_update`, and `agenr_trace`.
-
-The Skeln plugin exposes seven tools: `agenr_store`, `agenr_recall`, `agenr_update`, `agenr_work`, `get_goal`, `create_goal`, and `update_goal`. It does not expose `agenr_retire` or `agenr_trace`.
+| Command                          | What it does                                                                                                                           |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `agenr init`                     | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion.               |
+| `agenr setup`                    | Configure auth, model defaults, embeddings, and the agenr database path.                                                               |
+| `agenr recall <query>`           | Run the hybrid recall pipeline with optional temporal and type/tag filters.                                                            |
+| `agenr trace`                    | Inspect one entry's provenance and claim-family lineage by id, subject, or `--last`.                                                   |
+| `agenr ingest <path>`            | Default durable-entry ingest shorthand. Equivalent to `agenr ingest durables <path>`.                                                  |
+| `agenr ingest durables <path>`   | Bulk-ingest one file or directory of OpenClaw transcript files into durable knowledge entries.                                         |
+| `agenr ingest episodes [path]`   | Backfill episodic summaries from OpenClaw session transcripts, including rotated `.reset.*` and `.deleted.*` files.                    |
+| `agenr ingest procedures [path]` | Sync repo-authored YAML procedures into procedural-memory revisions stored in the knowledge database.                                  |
+| `agenr dream run`                | Execute a dreaming maintenance run. Dry-run by default; add `--apply` to mutate the corpus. Use `--tier light`, `standard`, or `deep`. |
+| `agenr dream status`             | Show corpus health, claim-key lifecycle counts, and the latest dreaming run summary.                                                   |
+| `agenr dream history`            | Show recent dreaming runs.                                                                                                             |
+| `agenr scenarios list`           | List repo-local claim-key sandbox scenarios.                                                                                           |
+| `agenr scenarios run`            | Run one or more claim-key sandbox scenarios.                                                                                           |
+| `agenr db reset`                 | Delete and recreate the knowledge database.                                                                                            |
+
+The OpenClaw plugin gives the agent four tools directly inside the runtime: `agenr_store`, `agenr_recall`, `agenr_fetch`, and `agenr_update`.
+
+The Skeln plugin exposes eight tools: `agenr_store`, `agenr_recall`, `agenr_fetch`, `agenr_update`, `agenr_work`, `get_goal`, `create_goal`, and `update_goal`. Neither host exposes a runtime trace tool; use `agenr trace` for provenance inspection.
 
 Examples:
 
@@ -192,11 +188,11 @@ agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
 # Preview procedure sync changes
 agenr ingest procedures --dry-run
 
-# Run the default autonomous surgeon sequence (dry-run by default)
-agenr surgeon run --budget 2.00
+# Run a standard-tier dreaming pass (dry-run by default)
+agenr dream run --tier standard
 
-# Run one explicit surgeon pass
-agenr surgeon run --pass supersession --budget 2.00
+# Apply dreaming mutations explicitly
+agenr dream run --tier standard --apply
 
 # Inspect the latest stored entry
 agenr trace --last
@@ -221,23 +217,23 @@ Recall is a hybrid pipeline. Agenr embeds the query, retrieves candidates throug
 
 Agenr has two transcript-ingest pipelines plus one repo-authored procedure sync path:
 
-- `agenr ingest entries <path>` extracts durable typed knowledge such as facts, decisions, preferences, lessons, milestones, and relationships.
+- `agenr ingest durables <path>` extracts durable typed knowledge such as facts, decisions, preferences, lessons, milestones, and relationships.
 - `agenr ingest episodes [path]` generates one narrative summary per session so the brain can answer temporal questions like "what happened last week?"
 - `agenr ingest procedures [path]` validates and syncs repo-authored procedural workflows from `procedures/` into the database.
 
-The two transcript paths parse OpenClaw transcripts first, but they optimize for different outputs: entry ingest distills durable knowledge and runs semantic dedup across the whole ingest batch, while episode ingest does a session-by-session preflight pass, uses `sessions.json` metadata when available, reconstructs missing surface metadata for rotated files, and writes episodic summaries. Procedure sync is different: it reads strict YAML authoring files, normalizes them into canonical stored revisions, and writes only when a procedure is new or semantically changed. Details: [docs/INGEST.md](./docs/INGEST.md), [docs/STORE.md](./docs/STORE.md), and [docs/PROCEDURES.md](./docs/PROCEDURES.md).
+The two transcript paths parse OpenClaw transcripts first, but they optimize for different outputs: durable ingest distills long-term knowledge and runs semantic dedup across the whole ingest batch, while episode ingest does a session-by-session preflight pass, uses `sessions.json` metadata when available, reconstructs missing surface metadata for rotated files, and writes episodic summaries. Procedure sync is different: it reads strict YAML authoring files, normalizes them into canonical stored revisions, and writes only when a procedure is new or semantically changed. Details: [docs/INGEST.md](./docs/INGEST.md), [docs/DURABLES.md](./docs/DURABLES.md), and [docs/PROCEDURES.md](./docs/PROCEDURES.md).
 
 ## How Procedures Work
 
-Procedures are the durable how-to layer. They are authored in `procedures/` as reviewed YAML, normalized into canonical stored procedure revisions, and synced with `agenr ingest procedures [path]`. Procedure recall is live through unified host-plugin `agenr_recall` and before-turn suggestion, but the standalone CLI `agenr recall` command still targets entry recall only. For the current model, storage shape, sync semantics, and read surfaces, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
+Procedures are the durable how-to layer. They are authored in `procedures/` as reviewed YAML, normalized into canonical stored procedure revisions, and synced with `agenr ingest procedures [path]`. Procedure recall is live through unified host-plugin `agenr_recall` and before-turn suggestion, but the standalone CLI `agenr recall` command still targets durable recall only. For the current model, storage shape, sync semantics, and read surfaces, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
 
 ## How Episodes Work
 
 Episodes are session-level memory artifacts stored separately from durable entries. They preserve temporal narrative: what happened in a session, when it happened, which agent/session it belonged to, and optionally an embedding for semantic episode search. Recall can route narrative or time-bounded questions toward episodes automatically, or combine episode and entry results in mixed mode. For implementation details and the episode recall model, see [docs/EPISODES.md](./docs/EPISODES.md).
 
-## How the Surgeon Works
+## How Dreaming Works
 
-The surgeon is a maintenance system for the durable-memory corpus. Four passes are implemented today: `claim_key_quality`, `proposal_resolution`, `supersession`, and `retirement`. `agenr surgeon run` defaults to an autonomous sequence across those passes and is safe by default because it starts in dry-run mode; `--pass <type>` runs one pass, and `--apply` is the explicit mutation switch. For runtime details, governance, and audit behavior, see [docs/SURGEON.md](./docs/SURGEON.md).
+Dreaming is the maintenance system for the durable-memory corpus. Milestone 1 ships a pipeline skeleton with `scan`, deterministic `reconcile`, and `apply`. `agenr dream run` is dry-run by default; `--apply` is the explicit mutation switch, and `--tier` selects `light`, `standard`, or `deep` coverage. For runtime details, governance, and the stage roadmap, see [docs/DREAMING.md](./docs/DREAMING.md).
 
 ## Development