mirror-mind 0.0.1 → 0.33.0

package/docs/releases/v0.31.7.md

@@ -0,0 +1,132 @@
+---
+digest: >
+  v0.31.7 makes the document-first Refinement Workbench transferable between
+  contributors and their Mirrors. A natural inspection request now renders one
+  standard read-only view from the canonical Markdown index; active Change
+  Requests can name a human Driver and branch or pull-request Delivery
+  reference; and a project-owned collaboration protocol carries work from
+  capture through return handoff. Git remains responsible for history,
+  concurrency, conflicts, and recovery. The release adds no Markdown parser,
+  shared database, projection, synchronization, watcher, lock, ID service, or
+  custom Git protocol, and it never consults legacy SQLite state when the
+  canonical index exists.
+---
+
+# v0.31.7 — Collaborative Refinement Work
+
+**Date:** 2026-08-03
+
+## Highlights
+
+- Adds a standard agent-composed `Refinement Workbench` view for natural
+  file-first inspection, including source, focus, RS status, ordered open CRs,
+  terminal history, next safe action, and an explicit read-only/SQLite boundary.
+- Adds canonical `Driver` and `Delivery` fields so active execution names one
+  accountable human and its branch or pull request without encoding people or
+  local runtime state in RS/CR identity.
+- Adds a project-owned Collaborative Refinement Protocol covering inspection,
+  capture, selection, planning, assignment, implementation evidence, Navigator
+  validation, debt review, terminal closure, return handoff, and Git conflict
+  handling.
+- Preserves captured/planned work as unassigned, requires explicit assignment
+  before active execution, keeps provenance in terminal history, and never
+  infers ownership from a checkout, committer, journey, conversation, or SQLite.
+- Validated through natural Pi prompts, an isolated second-Mirror capture smoke,
+  2,404 local unit/integration tests, clean Ruff checks, and green Python
+  3.10/3.12, TypeScript, and documentation PR CI.
+
+## Where We Started
+
+v0.31.6 established the document-first authority boundary: one canonical
+Markdown index owns shared Refinement focus, ordering, and status, linked files
+own narrative and evidence, and Git owns collaboration and recovery. That made
+the Workbench portable, but the first post-release use exposed three experience
+gaps before another contributor could use it independently.
+
+Builder entry surfaces pointed to the canonical file without presenting its
+contents. An `in_progress` status could not say who had assumed the work or where
+it was being delivered. And another person's Mirror had no durable project
+protocol for allocating IDs, capturing without changing focus, assigning work,
+validating it, or returning a handoff. Maintainers still had to reconstruct and
+transmit those rules through private conversation.
+
+## What Changed
+
+RS002 closed those gaps in three bounded Change Requests.
+
+CR005 added a presentation contract to the Builder skill. When asked naturally
+to show the Workbench, Mirror reads the canonical index and relevant linked
+documents, preserves canonical ordering, visibly distinguishes focus, separates
+open work from terminal history, recommends one grounded next action, and states
+that inspection changed nothing and did not consult SQLite. This is agent file
+reading, not a Python Markdown runtime or deterministic Ariad wrapper.
+
+CR006 added two explicit columns to the canonical CR table. `Driver` names one
+accountable human contributor. `Delivery` names a pull request when available or
+a Git branch before one exists. Captured and planned work can remain empty;
+active, blocked, and validated work retain both fields. Reassignment and stale
+work disposition remain Navigator decisions, and completed history preserves
+its delivery provenance.
+
+CR007 made collaboration durable through an ordinary linked Markdown protocol.
+It defines the complete contributor route: inspect, capture, select, plan,
+assign, implement, validate, review, close, and return a handoff. Capture chooses
+the next unused project-wide ID and requires an explicit RS under the current
+layout while preserving focus. Git surfaces concurrent ID, index, status,
+assignment, and narrative edits; Mirrors never silently renumber, overwrite,
+merge narratives, or use SQLite to resolve semantic conflicts.
+
+## Validation
+
+The presentation was validated in newly loaded Pi sessions using the natural
+prompt `Mostre o Refinement Workbench`. The output showed canonical focus,
+ordering, statuses, Driver/Delivery only where assigned, terminal history, and
+the read-only boundary.
+
+The collaboration route was validated with the shorter prompt `como trabalhar
+com refinements?`. The first response omitted return handoff and Git concurrency,
+which correctly failed the acceptance boundary. Skill guidance was tightened in
+cycle, and the repeated response covered all nine movements, handoff fields, and
+semantic-conflict behavior.
+
+An isolated second-Mirror smoke received a natural request to capture a fully
+specified refinement under RS002. It allocated the next ID, created the CR
+narrative, appended a captured/unassigned row, preserved current focus, linked
+the CR from its RS, and avoided SQLite. The generated CR existed only in the
+disposable `/tmp` project and never entered the real Workbench.
+
+## Conscious Exclusions
+
+- **No Markdown parser or second state model.** The agent reads project files;
+  Python does not parse or persist their meaning.
+- **No assignment service.** Driver and Delivery are explicit Markdown facts,
+  not locks, leases, heartbeats, or inferred presence.
+- **No automatic IDs or conflict resolution.** Contributors inspect the complete
+  index, and Git exposes concurrent choices for human resolution.
+- **No automatic Git operations.** The protocol does not create branches,
+  commits, pushes, pull requests, merges, tags, or releases.
+- **No legacy-state reconciliation.** File-first projects do not inspect,
+  migrate, compare, delete, or dual-write SQLite Workbench rows.
+- **Claude Builder parity remains separate.** This release improves the Pi and
+  shared Gemini/Codex skill surface without changing Claude's independently
+  tuned Builder skill.
+
+## What We Learned
+
+Making project state portable was not the same as making collaboration
+transferable. A second person also needs a visible field, explicit ownership,
+and a shared operating route. Those needs were satisfied with documents and
+agent guidance rather than a coordination subsystem.
+
+Natural-language validation mattered. The first protocol response looked useful
+while omitting the final handoff and conflict boundary. Treating that omission as
+a failed acceptance test produced a better contract without introducing parser
+or workflow machinery.
+
+## Next Horizon
+
+The next evidence should come from a real contributor using their own journey,
+Mirror, branch, and pull request to add Builder/Ariad refinements. Any future
+automation should answer a repeated observed failure in that collaboration,
+not anticipate one. RS001's runtime-trust CRs remain independent canonical work
+and are not promised by this release.

package/docs/releases/v0.31.8.md

@@ -0,0 +1,120 @@
+---
+digest: >
+  v0.31.8 introduces the Windows Desktop Frame as Mirror Mind's primary Windows
+  experience. One installer now carries a native Electron window for guided
+  onboarding, tabbed conversations through real Pi/ConPTY sessions, setup health,
+  controlled Pi updates, and a preserved terminal recovery route. The Frame
+  orchestrates the existing Mirror CLI and pins the homologated Pi version rather
+  than reimplementing either runtime. Packaging is fail-closed and validated on
+  Windows through unit tests, a session simulator, a packaged Electron/ConPTY
+  smoke, and a real non-ASCII user-profile smoke. The first release intentionally
+  remains unsigned and does not update the Mirror core from inside the Frame.
+---
+
+# v0.31.8 — Windows Desktop Frame
+
+**Date:** 2026-08-07
+
+## Highlights
+
+- Adds the native Windows Desktop Frame: guided first-run onboarding, tabbed Pi
+  conversations over real ConPTY sessions, setup health, persona inspection,
+  subscription login, and controlled Pi maintenance in one window.
+- Makes the Frame the primary Windows shortcut while preserving `Mirror Mind
+  (Terminal)` as an independent recovery and maintenance path.
+- Pins Pi exactly to the homologated `0.83.0` release; install and update paths
+  converge absent, older, and newer versions to that pin and never use `@latest`.
+- Gates every Frame PTY through one session authority so Pi cannot update while
+  Mirror, login, shell, or bootstrap sessions are open.
+- Packages the Frame and its native ConPTY dependency through one fail-closed
+  build path before compiling installer `0.31.0`.
+- Validates the integrated release on Python 3.10/3.12, TypeScript, documentation,
+  Pester, PSScriptAnalyzer, 63 Frame tests, session simulation, packaged
+  Electron/ConPTY, and a real non-ASCII `USERPROFILE` smoke.
+
+## Where We Started
+
+The existing Windows installer could bootstrap Mirror Mind and open Pi in a
+terminal, but the experience still exposed installation and runtime mechanics as
+the product. First-run identity setup, subscription login, health diagnosis, and
+conversation management were separate terminal interactions. That path remained
+valuable for recovery, but it was not yet the coherent desktop experience tested
+through the ES-004 functional mockup.
+
+The first Frame proposal proved the product direction and a viable
+Electron/ConPTY stack. Release review then exposed a stricter boundary: a native
+window also becomes an installer, updater, credential-transit, native-binary,
+and session-lifecycle responsibility. Shipping it required more than rendering a
+terminal inside Electron.
+
+## What Changed
+
+The Frame now installs as a private component of Mirror Mind and follows the
+Mirror release version. Its renderer runs sandboxed with context isolation and no
+Node integration. A narrow preload API reaches main-process handlers that verify
+their sender, reject unexpected navigation and windows, validate environment
+values against CR/LF injection, and execute only fixed command-registry entries.
+Pi owns OAuth tokens; the Frame observes only readiness and completion signals.
+
+Onboarding performs the real `.env` → `memory init` → `seed` flow and remains
+recoverable when initialization fails. Reinstalling preserves the identity home
+without silently rebinding it. The user explicitly enters the same identity name,
+and OpenRouter credentials remain guarded transient state until persistence.
+
+All PTYs participate in one `SessionGate`. Mirror conversations, hidden login,
+system terminals, and bootstrap sessions prevent a concurrent Pi update. The
+homologated Pi version lives in `installer/pi-version.txt`; both installer and
+packaged Frame read that installed authority and converge precisely to `0.83.0`.
+A missing or malformed pin disables automatic Pi maintenance rather than falling
+back to an uncontrolled version.
+
+Packaging is now reproducible outside CI. `frame/scripts/package.ps1`
+materializes the pinned Electron binary, assembles runtime dependencies, and
+feeds one verified payload into Inno Setup. Missing `MirrorFrame.exe`, ConPTY,
+preload, renderer, or required assets aborts the build. CI follows the same
+`npm ci → tests → simulator → package → verify → installer → smoke → upload`
+route and exercises the installed path under a genuinely non-ASCII Windows user
+profile.
+
+## Distribution Boundary
+
+The downloadable artifact is `MirrorMind-Setup-0.31.0.exe`. Installer versioning
+is independent because `0.31.0` describes the materially changed bootstrapper;
+the Frame inside it is version `0.31.8`, matching Mirror itself.
+
+The installer is not code-signed in this release. Windows SmartScreen may warn
+before execution. The release publishes a SHA-256 checksum so users can verify
+the exact artifact produced by the integrated GitHub Actions run.
+
+## Conscious Exclusions
+
+- **No automatic Mirror-core update inside the Frame.** The installed Frame and
+  core move together through a new installer; conscious manual maintenance
+  remains available through the Terminal shortcut.
+- **No unpinned Pi channel.** Moving beyond Pi `0.83.0` requires rerunning the
+  login, OAuth, fallback, and update compatibility matrix.
+- **No code-signing certificate.** The first installer remains unsigned, with
+  the SmartScreen consequence documented rather than hidden.
+- **No Microsoft Store distribution or TD-003 transport work.** Those require a
+  separate delivery and trust boundary.
+- **No Python-core redesign.** The Frame orchestrates the existing CLI and does
+  not alter the core under `src/memory/`.
+- **No in-executable Mirror icon stamping.** Installer shortcuts and the window
+  carry Mirror branding, while the executable resource may still show Electron's
+  default icon in some Windows surfaces.
+
+## What We Learned
+
+A desktop shell is not merely a new presentation layer. Once it owns onboarding,
+PTYs, updates, and installation, correctness depends on authority boundaries that
+remain valid when the renderer is wrong, the path contains spaces or accents,
+the native ABI differs from ordinary Node, or a setup attempt fails halfway.
+Making those boundaries executable in the canonical packaging and CI route was
+what turned the Frame from a promising prototype into a releasable Windows path.
+
+## Next Horizon
+
+The next evidence should come from installing the exact release asset on a clean
+Windows environment and observing real onboarding and daily conversation use.
+Code signing, executable-resource branding, broader distribution, and any future
+Frame-aware core updater remain separate decisions informed by that use.

package/docs/releases/v0.31.9.md

@@ -0,0 +1,120 @@
+---
+digest: >
+  v0.31.9 removes Mirror Mind's artificial two-level journey limit and makes
+  organizational journey trees recursively visible across textual and web
+  surfaces. Parent assignment now supports arbitrary depth while rejecting
+  direct, indirect, and malformed cycles; moves preserve journey identity,
+  project paths, and filesystem content. Journey removal is conservative and
+  transactional, allowing only empty leaves and never cascading into associated
+  records. The release also replaces the TypeScript migration's strict Python
+  feature freeze with an explicit moving-target parity contract, so the current
+  product can evolve while command authority transfers incrementally to TS.
+---
+
+# v0.31.9 — Recursive Journey Hierarchy
+
+**Date:** 2026-08-14
+
+## Highlights
+
+- Allows journeys to form organizational trees of arbitrary depth using the
+  existing `parent_journey` metadata contract, with no schema migration.
+- Rejects direct and indirect cycles before mutation and keeps malformed legacy
+  cycles bounded on read surfaces instead of hanging.
+- Renders the complete hierarchy recursively in `mm-journeys`, Workspace
+  navigation, Current Scene, All Journeys, and journey selectors.
+- Shows complete root-to-selected lineage while keeping conversations, memories,
+  tasks, attachments, routing, Builder state, and Scene movement exact to each
+  journey.
+- Preserves stable journey ids and independent `project_path` values when a
+  journey or subtree moves; no filesystem content is inferred or moved.
+- Makes removal fail closed: parents with children and leaves with associated
+  records are refused in one transaction; only empty leaves can be removed.
+- Establishes a moving-target TypeScript strangler contract: Python may evolve
+  while it remains authority for an unported command, and each change becomes
+  explicit TS parity scope before authority transfers.
+
+## Where We Started
+
+CV15 originally shipped a deliberately small one-level hierarchy. That was enough
+to prove that parent-child relationships could organize the journey field without
+merging context, and Current Scene then used that map to return cognitive
+location. Real use exposed the remaining artificial boundary: life areas,
+businesses, products, and projects naturally form deeper structures, while Mirror
+refused a child beneath an existing child.
+
+The TypeScript strangler introduced a second tension. Its original policy froze
+new Python features so the migration target would stay stable. The principle was
+coherent, but the migration is a long-running background effort; in practice the
+freeze required product evolution to wait months for TS sequencing.
+
+## What Changed
+
+`JourneyService` now validates a proposed parent by walking the complete ancestor
+chain. A journey may sit at any depth, including beneath a node that already has
+children. Reaching the journey itself rejects the move as a cycle; encountering a
+pre-existing cycle rejects extending malformed ancestry. Reads track visited ids,
+so corrupt rootless cycles remain visible and bounded.
+
+Journey options carry depth and complete lineage. The textual journey list,
+Workspace tree, Scene map, All Journeys view, and selection controls render
+recursively. Selecting a deep node opens its full ancestor chain. Current Scene
+returns the complete lineage and only immediate siblings, while all movement and
+content queries remain scoped to the exact selected journey.
+
+Movement changes only the moved node's `parent_journey`. Regression coverage and
+an isolated smoke prove that identity ids and `project_path` values remain stable.
+No directory is created, renamed, moved, or removed.
+
+Removal gained a conservative domain operation without a public UI. Storage uses
+an immediate transaction to check child journeys and every known associated
+record before deleting the identity. This closes the check-then-delete race and
+prevents implicit reparenting, orphaning, and cascades.
+
+Navigator homologation created a third-level journey through ordinary Mirror
+conversation. It also exposed a presentation defect: deep leading-space
+indentation crossed Markdown's code-block boundary. Text trees now use
+column-zero `│` connectors at every depth, with regression coverage preventing a
+return to fenced output.
+
+Finally, the migration policy now transfers authority command by command. Python
+continues to evolve where it still serves the product; CV22 must absorb the
+current observable contract before claiming parity. Recursive journey reads are
+assigned to CV22.E2.S5, and writes plus removal semantics to CV22.E4.
+
+## Conscious Exclusions
+
+- **No inherited context.** Parentage does not merge documents, memories,
+  conversations, tasks, attachments, instructions, status, routing, search, or
+  Builder state.
+- **No filesystem synchronization.** Paths do not infer parentage, and parentage
+  does not create or move directories.
+- **No automatic reparenting or cascade.** Removing a parent with children is a
+  simple refusal.
+- **No public journey-removal UI.** The domain operation exists, but irreversible
+  user-facing removal requires separate product work.
+- **No simultaneous TypeScript implementation.** Parity obligations are explicit
+  in CV22, but this patch does not duplicate the feature before the relevant TS
+  read/write foundations exist.
+- **No hierarchy watchers, aggregate status, or structural auto-repair.** The
+  capability remains a simple organizational tree.
+
+## What We Learned
+
+A stable migration target is valuable only while it does not make the product
+stand still. The safer long-running strangler is not one with no drift; it is one
+that makes drift explicit, captures observable contracts, and transfers authority
+at clear command boundaries.
+
+The homologation also reinforced that recursive behavior must be validated at the
+rendering boundary, not only in the data model. The hierarchy was semantically
+correct while Markdown made its deepest node look like code. Normal conversational
+use found what green service tests could not.
+
+## Next Horizon
+
+CV22 must absorb recursive journey behavior before its read and write commands
+claim authority. Public journey removal may later build on the conservative
+domain operation, but only with an explicit interaction and recovery design. The
+product can now gather real evidence from deeper journey organization without
+waiting for either horizon.

package/docs/releases/v0.32.0.md

@@ -0,0 +1,261 @@
+---
+digest: >
+  v0.32.0 closes CV22, the TypeScript Core Port. Mirror Mind is now one
+  TypeScript package run by Node.js 24, installed with `npm install -g
+  mirror-mind` and wired to Pi, Claude Code, Gemini CLI, or Codex by one
+  documented step each; no Python remains in the repository or the shipped
+  artifact. Every command, its arguments, and its output are what they were.
+  The migration was a database-seam strangler, one command at a time, each
+  proven against the Python engine before it answered users, decided on
+  2026-06-23 and finished on 2026-10-10. Eleven surfaces were retired with
+  cutoffs rather than ported, the Windows Frame and the web console among
+  them; the Python core's last tree is kept at `cv22-last-python-bearing`.
+  A clone updated by the previous release's updater completes and reports
+  success; then run `npm ci && npm link && mirror runtime migrate` once at the
+  clone root (see Upgrading from a clone in this note).
+---
+
+# v0.32.0 — One Language, One Install
+
+**Date:** 2026-10-11
+
+## Highlights
+
+- **Install is one command and no checkout:** `npm install -g mirror-mind`, then
+  `mirror init <you>`. Two bins on the `PATH`, `mirror` and `mirror-hook`; configuration in
+  `~/.config/mirror/env`; your home at `~/.mirror-minds/<you>`. Node.js 24 or newer is the
+  only prerequisite. See [Getting Started](../getting-started.md).
+- **No Python anywhere.** `src/memory/`, `uv`, `pyproject.toml`, and every way to reach
+  them are gone from the repository, and a guard proves the shipped package holds none by
+  path and by content. The TypeScript engine owns the database: bootstrap, migrations, and
+  every read and write.
+- **Each runtime wires by a counted step:** Pi 1, Claude Code 1, Gemini CLI 2, Codex 2,
+  printed by `init` for the runtimes it finds, and the Operating Instructions reach each
+  runtime its own way.
+- **The same commands, the same answers.** 31 front-door commands, 25 skills in three
+  copies that all say `mirror`. The last command family was proven byte-identical to the
+  Python oracle before the oracle was deleted.
+- **Upgrading from a clone is five lines**, described below. The previous release's
+  updater completes the hop and reports success; it does not know about the five lines,
+  so this note has to.
+- **Eleven surfaces are retired with cutoffs rather than ported**, each with what to do
+  instead and what still works if you do nothing: the web console, the Windows Frame and
+  installer, the Python extension API, journey projections, and seven smaller ones.
+  Summarized below; the full record is [Pending Cutoffs](pending-cutoffs.md).
+- **One behavior change a Pi user can notice:** a new home imports only the Pi sessions
+  that are newer than itself. Your earlier Pi history stays where it is.
+- **Not in this release:** Windows, Mirror Desktop, a programmatic API. Each is named
+  under Conscious Exclusions.
+
+## Where We Started
+
+Mirror Mind was a Python core with four runtime harnesses written in TypeScript around it.
+Installing it meant cloning the repository, running `uv sync`, keeping a `.env` in the
+clone, and opening your harness inside that directory, because the directory *was* the
+install. Every skill called the core by its path inside the clone. The Windows path was a
+separate Electron Frame with a PowerShell installer that cloned the repository for you.
+
+That shape worked for its first users and could not reach the next ones. Two languages
+meant two toolchains on every machine and two sets of idioms for every contributor. A
+clone is not a thing you can tell a stranger to install. And the harnesses, the MCP
+ecosystem, and the plugin formats Mirror lives in are all TypeScript; the core was the
+one piece that was not.
+
+On 2026-06-23 the decision was taken to
+[port the core to TypeScript through a database-seam strangler, not a rewrite](../project/decisions.md#mirror-mind-ports-to-typescript-via-a-database-seam-strangler-not-a-rewrite):
+the shared SQLite database would be the seam, a TypeScript front door would take one
+observable command at a time, each proven against the Python engine on copies of real
+databases before it answered anyone, and Python would dissolve as the front door grew.
+No big bang, no freeze, no feature pause: the Python product kept moving through
+v0.31.14, and every change to it created named parity scope on the TypeScript side.
+
+From 2026-09-07 the migration was a
+[single-owner effort](../project/decisions.md#cv22-becomes-a-single-owner-migration), with
+a multi-persona technical review standing in as the second opinion at each plan and each
+handoff. And from 2026-09-13 it was decided that
+[CV22 releases once, when the migration is complete](../project/decisions.md#cv22-releases-once-when-the-migration-is-complete):
+a half-migrated core is not a product story, so nothing shipped until all of it had.
+
+## What Changed
+
+### The strangler, in ten Delivery Stories
+
+The arc ran from a parity spike on hybrid search (DS1), through a read-only TypeScript
+foundation (DS2) and a Pi front door that wrapped the unported remainder (DS3), to
+deterministic writes (DS4) and the external-API commands, extraction and embeddings among
+them (DS5). DS6 moved schema custody: the TypeScript engine took over database creation
+and migrations, and proved a fresh database it creates is structurally identical to one
+Python created. DS7 burned down the remaining command surface, fourteen stories, until
+the deterministic Python command surface was empty. DS8 cut the live providers over.
+DS9 ported the MCP server, with a threat model first and wallet guards against denial of
+spend. DS10 retired what was left and made the package.
+
+Every ported family answered from TypeScript behind a one-variable revert to Python while
+it was young, and every revert was removed only when Python itself was. The oracle
+harness that graded TypeScript against Python on copies of real databases went with the
+oracle; its goldens are frozen fixtures the tests still grade against.
+
+### Deletion as a product decision
+
+Not everything was ported. Where a surface had no user the migration could name, it was
+[retired with a cutoff rather than carried across](../project/decisions.md#the-web-console-is-retired-not-ported-and-ds7-closes-at-1414):
+the web console, whose successor is `mirror-gui`; the
+[Windows Frame and installer](../project/decisions.md#the-windows-frame-and-installer-are-retired-not-re-homed-and-no-windows-story-is-promised),
+with three downloads ever and no known user; the Python extension API and the
+compatibility host that served it;
+[journey projections](../project/decisions.md#journey-projections-retire-with-the-python-core-mirror-desktop-is-outside-the-migration),
+whose one consumer is outside the migration; the SQLite Refinement Workbench, replaced by
+the file-first Refinement route; the legacy database conversion, the migration rehearsal
+tool, the journey admin verbs, the metadata backfill, and the Python-era release tooling.
+Each cutoff answers what no longer exists, what to do instead, and what still works if
+you do nothing. The full record, one section per surface, is
+[Pending Cutoffs](pending-cutoffs.md); the short version:
+
+| Removed | Instead |
+|---|---|
+| The Python core: `python -m memory …`, `uv`, the `MIRROR_TS_*` reverts, the Python API | `mirror <command>`; clean `MIRROR_TS_*` and the three path variables out of `.env` |
+| The web console (`python -m memory web`) and its scene synthesis | Everything it showed is in the terminal: `journeys`, `journey <slug>`, `memories`, `conversations`, `tasks`, and the four modes; `mirror-gui` is the graphical successor; the scene synthesis has no replacement |
+| The Windows Frame and PowerShell installer | Nothing on Windows in this release; a Frame install keeps working on `v0.31.14` and must not update from inside the Frame |
+| `register(api)`, `extension.py`, the compatibility host | An extension declares a runtime per capability in `skill.yaml`; install validates what the manifest declares |
+| Journey projections and `.mirror/projections` | Nothing; existing trees are inert; Mirror Desktop stays on the last Python-bearing release |
+| The SQLite Refinement Workbench's twenty verbs | `docs/project/refinement/index.md` and the file-first route |
+| `migrate-legacy` (the Portuguese-era conversion) | Convert once with the last Python-bearing release; any home Mirror has ever opened is already current |
+| `memory-rehearse-migration` | The TypeScript engine's own migration tests; backups before every write |
+| `journey export-registry` and `journey mutate` | `journeys` and `journey <slug>` to read; the Mirror, Builder, and Explorer surfaces to change; no machine-readable dump |
+| The conversation metadata backfill flags | Nothing: a one-shot pass whose moment has passed; the lifecycle faces stay |
+| `runtime release-doctor` and `release-promote` | Maintainer scripts, `npm run release:doctor` and `release:promote`, from a checkout |
+
+The last tree that contains the Python core is kept at the
+[`cv22-last-python-bearing`](https://github.com/mirror-mind-ai/mirror/tree/cv22-last-python-bearing)
+tag, so nothing is gone from the world, only from this version.
+
+### The package
+
+The repository is the package: `npm pack` produces 468 files with the same paths as a
+checkout, two bins on a loader shim that strips types for its own package only, no build
+step, no install script. The core reads its configuration in one order — environment,
+`<clone>/.env`, `~/.config/mirror/env` — and `init` writes `MIRROR_USER` there, readable by
+you only, never taking a key from the command line. All 25 skills, in the Pi, Claude
+Code, and plugin copies, say `mirror` under a guard that forbids any other form. A smoke
+in CI packs, installs into a scratch prefix, initializes, seeds, opens a migrating
+database, exercises the four runtimes' wrappers and the MCP server, and proves no
+interpreter was spawned.
+
+The package is published by npm's trusted publisher for this repository:
+[staged from CI with provenance, and a maintainer makes it public with 2FA](../project/decisions.md#the-npm-package-is-published-by-staging-from-ci-with-provenance-and-a-maintainer-approves-with-2fa).
+No long-lived token exists. The route was rehearsed end to end before this release.
+
+### One behavior change
+
+[A new home imports only the Pi sessions that are newer than itself](../project/decisions.md#a-new-mirror-home-imports-only-the-pi-sessions-that-are-newer-than-itself).
+Session maintenance used to backfill every untracked Pi session on the machine; for a
+home that had tracked Pi from the start that filled gaps, but for a new home it copied
+the person's whole Pi history, from every project, and then spent on retitling and
+extracting it before the first prompt was answered. Now a session is Mirror's only if it
+ended after the home existed; the home's age is its database's first open. For an
+existing home, nothing changes: your home is older than your sessions. The one case where
+a person loses an import they used to get: a database rebuilt from scratch is a new home,
+born now, and the sessions the old one held are not imported again. The home is the
+database.
+
+## Upgrading from a clone
+
+Until this release Mirror ran from a git clone and the skills called the core by its path
+inside it. The skills now say `mirror`, and nothing provides that name until you do, once.
+Node.js 24 or newer is required, and was not before: check `node --version` first.
+
+```bash
+cd <your clone>
+git pull                 # or: the previous release's runtime update, which completes
+npm ci
+npm link                 # puts `mirror` and `mirror-hook` on your PATH from this tree
+mirror runtime migrate   # applies this release's pending migration, snapshot first
+mirror runtime status    # should say: Install: clone (<your clone>) ... Status: ready
+```
+
+Keep opening your harness in the clone, as before; everything it finds there now answers
+through `mirror`. Your `.env` stays where it is. Your home and database are untouched.
+`runtime status` is read-only: it reports a pending migration and does not apply it;
+`runtime migrate` does, with a snapshot first, and so does the first ordinary command
+that opens the database, which is why the line is there.
+
+**If you updated with the previous release's `runtime update`**, it completes and
+reports success, lists this release, and shows its summary. It ran entirely inside a
+process that had loaded the Python engine before the tree changed under it, so nothing
+it checked could fail; and it knows nothing of the lines above. Run them. From then on
+`mirror runtime update` is the Node one. The old form, `uv run python -m memory …`, now
+fails with `No module named memory.__main__`: the package is gone, and only ignored
+`__pycache__` residue remains under `src/`.
+
+Then the housekeeping the cutoffs ask for: `rm -rf src .venv` at the clone root removes
+the Python residue, since nothing tracked lives under `src/` any more, and `uv` itself can
+go; remove any `MIRROR_TS_<FAMILY>=0` line and `EXPORT_DIR`, `TRANSCRIPT_EXPORT_DIR`,
+`DB_BACKUP_PATH` from `.env` (`mirror runtime diagnose` names the stragglers); if your
+`identity/user/identity.yaml` still says `uv run python -m memory identity edit`, the
+command is `mirror identity edit user identity`; and if you have extensions with their
+own skills, re-run `mirror extensions sync` after their repositories are updated.
+
+**You can move to the package instead** of keeping the clone: `npm install -g
+mirror-mind`, `mirror init <your-name>` (it finds your existing home by name and copies
+nothing), add your `OPENROUTER_API_KEY` to `~/.config/mirror/env`, run the wiring step
+`init` prints for your runtime, and delete the clone. A checkout opened in Pi and an
+installed package both provide the extension; there is no reason to keep both.
+
+## Conscious Exclusions
+
+- **Windows.** The Frame and installer are retired and no Windows story is promised. The
+  supported platform is POSIX (macOS, Linux). A Frame install keeps working on
+  `v0.31.14` as it is, and must not update from inside the Frame.
+- **Mirror Desktop.** Outside the migration. It couples to the Python era well beyond
+  projections and stays on the last Python-bearing release; its integration with the
+  TypeScript core is a separate effort after this one.
+- **A programmatic API.** `from memory import MemoryClient` has no TypeScript
+  counterpart in this release. The command line and the MCP server are the interfaces.
+- **A Gemini extension and Codex hooks.** Both runtimes wire by two documented steps and
+  Codex runs through a shipped wrapper; a packaged Gemini extension and Codex hooks were
+  considered and not built.
+- **Importing earlier Pi history on request.** The new rule does not ask and offers no
+  import of what it skips; if one is wanted, it is a feature with its own story.
+- **`v1.0.0`.** This release completes a Capability Value, which the versioning rule
+  would call a MAJOR, but
+  [that number is CV9's](../project/decisions.md#cv22-releases-as-v0320-not-v100): a
+  migration built not to be noticed does not get to be the 1.0.
+
+## What We Learned
+
+**The seam was the method.** Choosing the database as the boundary, rather than an API or
+a module, meant the two engines could run side by side over the same real data for three and
+a half months, and parity could be graded as resulting database state rather than argued. Every
+family flipped with a revert and lost it only when the oracle it would revert to was
+gone.
+
+**Deletion needs the same rigor as construction.** The surfaces retired here each got an
+inventory, a decision with the alternative written down, a cutoff that answers three
+questions for a user, and a guard in CI that keeps them retired. A retirement that was
+only a deletion would have come back.
+
+**A single owner needs a written second opinion.** With one person on the migration from
+September, the multi-persona plan and handoff reviews were not a supplement to review;
+they were the review. They found the loader shim Node's type-stripping needed, the
+operating instructions that had not shipped, the fail-open default in the backfill rule,
+and the full-scan that rule would have introduced.
+
+**Rehearse the one-shot step on a copy.** The release note said the previous updater
+would fail its post-update check on the Python-less tree. A rehearsal on a copy of the
+production clone showed it succeeding instead, in-process, with the engine already in
+memory, and showing the new release's summary as its only word to the user. The note was
+rewritten before anyone read it through that updater. There was exactly one Python-era
+production clone to learn this from; the copy was the second chance.
+
+**The documentation is read by the next session, not the next person.** Resumable
+plateaus with handoff statements, decisions recorded near the roadmap, and routes written
+so a stranger could run them made a part-time migration survivable across gaps of days.
+Where a pointer went stale, work was redone.
+
+## Next Horizon
+
+Mirror Mind is one package in one language, and the roadmap it serves is the product's
+again. Mirror Desktop's integration with the TypeScript core is the first thing waiting
+on the far side of this release. The Refinement index carries what the migration found
+and chose not to fix on its way out, CR124 the last of them, found on this release's own
+validation. And CV9, Mirror Mind 1.0, keeps its number.