mirror-mind 0.38.0 → 0.38.1

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.38.1 — The Refusal Names the Way Out](v0.38.1.md) — patch release of three Change Requests, CR185, CR186, and CR187: a package with no home configured names the homes it finds and the `mirror init <name>` that selects one, and `init` adopts a home that already exists; a missing or refused OpenRouter key is one line that names the file, before anything is touched; a `stable` clone ahead only by `main`'s commits is told that `stable` is behind it, not to push or reset. No migration.
 - [v0.38.0 — The Model Behind the Memories, Chosen by Measurement](v0.38.0.md) — minor release closing CV9.DS9: the model behind memories, tasks, titles, summaries, tags, reception, journal, shadow, and consolidation is Claude Haiku 5.5 at reasoning off, chosen on the eval suite with reasoning on and off and on 24 of the owner's own conversations ranked blind, where it came first on 16 of 26 surfaces. Every extraction-pin call can carry a reasoning effort, and a pin carries its own default. With CR180, summaries open with their subject, every lifecycle prompt sees the owner's name, and a framed opening is written once more. Release gate 70 of 70 probes. Rollback is one env line. No migration.
 - [v0.37.0 — The Mirror Stays in the Conversation](v0.37.0.md) — minor release closing CV9.DS8 and, with CV21.DS11, CV21: on Pi, Claude Code, Codex, and Antigravity one doorman in the core puts Mirror's context before the model on every turn of Mirror Mode, all of it on the turn Mirror Mode starts and then the persona and memories each question calls for; an explicit turn loads once; one signature, `◇ persona-name`; Pi reaches L4, measured live. One parity matrix in the runtime interface contract, sourced and held by a test. Codex, Antigravity, and Grok Build need their plugin copy brought level. Migration 018, applied on its own.
 - [v0.36.3 — A Skill You Invoke Is Not Something You Said](v0.36.3.md) — patch release of one Change Request, CR160, with CR159's docs: on Pi, a skill picked from the menu or typed is no longer stored as the person's words, and neither is its reply; a question asked with `/mm-mirror` is stored as the question. Pi's turns go through the rule the other runtimes have. `mirror conversations skill-turns` repairs what earlier versions stored, only on `--apply` and after a verified backup. No migration.

package/docs/releases/v0.33.3.md

@@ -111,7 +111,8 @@ hand:
 
 ```bash
 # a clone: in the checkout
-git pull --ff-only
+git fetch origin
+git merge --ff-only origin/stable   # origin/main if the clone follows main
 # a package
 npm install -g mirror-mind@latest
 ```
@@ -124,6 +125,13 @@ mirror runtime update          # or: npm install -g mirror-mind
 
 There is no database migration and no runtime wiring change.
 
+*Corrected on 2026-10-29:* the clone line first read `git pull --ff-only`. A clone follows
+`stable` unless you chose `main`. On `main`, that command pulls past the release, so the
+next `runtime update` refused with `plan: local commits present` (CR186). If that happened
+to you, your checkout is fine. Every later release contains the commits it pulled, so
+`runtime update` works again from the next release on. `mirror runtime channel main`
+follows `main` instead.
+
 ## Conscious Exclusions
 
 - **A Windows product.** REFERENCE.md's platform envelope stands: POSIX. The Windows

package/docs/releases/v0.38.1.md

@@ -0,0 +1,152 @@
+---
+digest: >
+  v0.38.1 is a patch release of three Change Requests, CR185, CR186, and CR187, two of
+  them from Leandro Garcia's report on PR #42. Where Mirror refused to go on, it now
+  says what to do next. A package with no home configured names the homes it finds and
+  the `mirror init <name>` that selects one, and `init` adopts a home that already
+  exists. A missing or refused OpenRouter key is one line that names the file the key
+  goes in, said before anything is touched. A `stable` clone that took `main`'s commits
+  early is told that `stable` is behind it, not to push or reset. No migration.
+---
+
+# v0.38.1 — The Refusal Names the Way Out
+
+**Date:** 2026-10-30
+
+## Highlights
+
+- **A package with no home configured says where it looks and what to run**
+  ([CR185](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr185-a-package-with-no-home-configured-does-not-say-where-it-looks.md)).
+  The error names the homes it finds under `~/.mirror-minds`, the `mirror init <name>`
+  that selects one, and the file that command writes. `mirror init <name>` now adopts a
+  home that already exists, changing nothing in it, so moving from a clone to the
+  package is one command. The bare `mirror` names the home too.
+- **A missing OpenRouter key stops the command before it touches anything**
+  ([CR187](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr187-a-missing-openrouter-key-crashes-three-commands-with-a-stack-trace-that-names-no-file.md)).
+  The six commands that cannot work without it (`consult`, `journal`, `week plan`,
+  `descriptor generate`, `consolidate scan`, and `shadow scan`) refuse in one line that
+  says what was not done and where the key goes, and exit 2. `journal` says the entry
+  was not saved, instead of crashing after it had copied the database into a snapshot.
+  A key that OpenRouter refuses is one line too. `runtime status`, `runtime diagnose`,
+  and a degraded search say when the key is missing.
+- **A `stable` clone ahead only by `main`'s commits is told that `stable` is behind it**
+  ([CR186](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr186-runtime-update-reads-main-s-commits-as-local-work.md)).
+  The ways out are `runtime channel main` or the next release, in the words a package
+  install already used. It is no longer told to push commits the remote already has, or
+  to reset its code below a database that may be newer than `stable`'s. Real local work
+  keeps the push-or-reset refusal.
+- No migration, and no model or prompt change.
+
+## Where We Started
+
+v0.33.3 fixed installs under a non-ASCII path, which Leandro Garcia reproduced on PR #42.
+On 2026-10-17 he came back with two bumps he met while following the update
+instructions:
+
+- Moving to the package, `runtime update` stopped with "Mirror home is not configured"
+  and did not say where the package looks.
+- On a clone, the release notes' manual step, `git pull --ff-only`, pulled `main` past
+  the release. The next `runtime update` refused with `local commits present` and
+  "push or reset", for commits that were not his.
+
+The answer came on 2026-10-29, twelve days late. The v0.33.3 notes were corrected to
+`git fetch origin` and `git merge --ff-only origin/stable`. CR185's review turned up a
+third refusal of the same kind: with no `OPENROUTER_API_KEY`, `consult`, `journal`, and
+`week plan` crashed with a stack trace that named no file, and `journal` lost the entry.
+
+## What Changed
+
+**A home the error can name (CR185).** One module now owns the homes root,
+`~/.mirror-minds`, and decides what counts as a home there: a directory with a non-empty
+`identity/` or a `memory*.db` file. The not-configured error is one line everywhere it
+appears. It ends with the command that finishes the job:
+
+```text
+Mirror home is not configured. To use the home at <root>/<name>, run: mirror init <name> (it writes MIRROR_USER=<name> to <config>).
+```
+
+There are forms for several homes, for a home whose name `init` would refuse, and for
+none. `init <name>` on an existing home copies nothing and changes nothing in it. It
+writes `MIRROR_USER` to an owner-only config file when no home is selected, and prints
+only what is left to do: the key, `mirror seed` when there is no database, and the
+runtime wiring. Selecting the only home automatically was considered and refused. A
+silent fallback once caused the wrong-session export incident, so one explicit command,
+whose effect is kept in a file, is the honest minimum.
+
+**A key checked before anything is touched (CR187).** The key used to be read at the
+first model call, so a failing command could already have done work. A keyless
+`journal` copied the whole database into its pre-write snapshot, then crashed. Now the
+six commands that cannot work without the key check it before the database opens. Any
+other command that meets a missing key is answered by the front door's handler: one
+line, no stack trace. All the sentences come from one place and name the file the
+install reads its configuration from. When that file does not exist yet, the line says
+to create it readable only by its owner. A key that OpenRouter refuses (HTTP 401 or 403)
+gets its own line, whether a chat call or an embedding call met it. `consolidate apply`
+is not checked up front, because only a merge proposal embeds.
+
+**The channel behind the clone (CR186).** The plan stage of `runtime update` counted
+every commit in `origin/stable..HEAD` as the person's own. Releases only fast-forward
+`stable` to `main`, so one more local count tells the two cases apart. When every commit
+past `stable` is already on `origin/main`, the clone's channel is behind it. The update
+then refuses the way the package lane refuses a channel behind the installed version,
+and in its words: "A downgrade is refused: migrations do not run backwards.", then
+`runtime channel main`, or staying until the next release. The captured Change Request
+also offered a reset to `origin/stable`; it was dropped. `main`'s code can migrate the
+database when it opens it, and `stable`'s core refuses a database newer than itself. One
+function now reads where a clone stands, for both the update plan and the welcome card,
+which had counted two different ways. A count that cannot run reads as local work, so
+real work is never mistaken for published work.
+
+**Reviewed before code, validated by hand.** Each plan was reviewed through persona
+lenses before any code was written: five for CR185, four each for CR186 and CR187. The
+Navigator validated each change on a natural route: CR185 and CR187 as a package user,
+the lane Leandro was on, and CR186 in a scratch clone ahead of `stable`. CR186's reviews
+turned its plan around. It had proposed reporting the clone as up to date, until the
+engineer found the package lane already refusing the same state.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind@latest
+```
+
+No migration, and nothing to configure. Moving from a clone to the package with a home
+that already exists: `mirror init <your-name>` now selects it without changing anything
+in it, and says what is left, such as the key. No skill, plugin, or extension changed in
+this release, so a reinstall line the updater prints for Codex, Antigravity, or Grok
+Build only moves the version number.
+
+## Conscious Exclusions
+
+- Transport failures other than a refused key (a timeout, an outage, a rate limit, a
+  server error) still crash the commands that call a model with a stack trace, and
+  `journal` still loses the entry
+  ([CR188](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr188-a-provider-outage-crashes-the-commands-that-call-a-model-with-a-stack-trace.md)).
+- Extraction at session end with no key is unchanged, and a configuration error still
+  counts as an attempt, which can quarantine a conversation
+  ([CR178](../project/refinement/rs010-cv22-oracle-and-port-hygiene/cr178-a-configuration-error-counts-as-an-extraction-attempt-and-nothing-releases-a-quarantine.md)).
+- With a wrong key, `descriptor generate` still prints "skipped (empty response)" for each
+  persona. That line is golden-graded.
+- `runtime update --check` still reports `local_ahead` for a clone ahead of `stable` by
+  `main`'s commits, where a package reports `channel_behind`.
+- A `main`-channel clone ahead by commits on another pushed branch keeps the
+  push-or-reset refusal.
+
+## What We Learned
+
+A validation route is code too, and it has to be run before it is handed over. CR186's
+route, run first by the agent, never reached the plan: a `node_modules` symlink made the
+scratch tree dirty, because `.gitignore`'s `node_modules/` matches only a directory.
+CR187's first route could not prove that no snapshot was taken, because `ls -l` shows
+minutes. Both were caught before the Navigator ran them.
+
+CI runs the suite under `MEMORY_ENV=test`. CR185's first push failed a test that had
+assumed `memory.db`. The suite is now run that way before every push.
+
+The same state deserves the same words. CR186's answer was already written, in the
+package lane's refusal of a channel behind the installed version.
+
+## Next Horizon
+
+CR188, the transport failures, is the next refusal of this kind. CV9, Mirror Mind 1.0,
+continues, and when its done condition is met the release is `v1.0.0`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Codex, Antigravity)",
   "license": "MIT",
   "repository": {

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/plugins/mirror-mind/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mirror-mind",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "mcpServers": {
     "mirror-mind": {
       "command": "/bin/sh",

package/ts/src/frontDoor/cli.ts

@@ -44,12 +44,11 @@ import { type Database, openDatabaseReadOnly, type WritableDatabase } from "#db/
 import { ensureDatabaseReady } from "#db/readyOnOpen.ts";
 import { assertSchemaState, SchemaStateError } from "#db/schemaState.ts";
 import { allDescriptors, descriptorsByLayer } from "#descriptor/descriptorRead.ts";
-import { newIdentityKeyProblem, newUserNameProblem } from "#identity/identityKey.ts";
+import { newIdentityKeyProblem } from "#identity/identityKey.ts";
 import { identityRowExists, listIdentityByLayer } from "#identity/identityRead.ts";
 import { listJourneysForListCommand } from "#identity/journeyListing.ts";
 import { listPersonas } from "#identity/personaListing.ts";
 import { setIdentity } from "#identity/setIdentity.ts";
-import { IdentityRootExistsError, initUserHome, TemplatesNotFoundError } from "#init/init.ts";
 import { JOURNEY_PATH_LAYER } from "#journey/journeyStatus.ts";
 import { JourneyNotFoundError } from "#journey/journeyWrite.ts";
 import { environmentSessionId } from "#mirror/runtimeSession.ts";
@@ -61,9 +60,14 @@ import {
 import { chatLedgerHook } from "#observability/ledgerHooks.ts";
 import { runWeekSave } from "#planning/weekSave.ts";
 import type { EmbeddingProvider } from "#providers/embedding.ts";
-import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import {
+  requireFamilyProviders,
+  requireKeyForFamily,
+  resolveFamilyProviders,
+} from "#providers/familyProviders.ts";
 import type { LlmProvider } from "#providers/llm.ts";
 import {
+  CONSULT_ASK_TRANSPORT,
   CULTIVATION_APPLY_TRANSPORT,
   CULTIVATION_SCAN_TRANSPORT,
   DESCRIPTOR_TRANSPORT,
@@ -72,18 +76,10 @@ import {
 } from "#providers/transport.ts";
 import { verifyBackupArchive } from "#runtime/backup.ts";
 import { exitQuietlyOnBrokenPipe } from "#runtime/brokenPipe.ts";
-import {
-  configFilePath,
-  loadConfiguration,
-  silenceExperimentalWarnings,
-  writeConfigValue,
-} from "#runtime/config.ts";
-import { runningTreeRoot } from "#runtime/treeRoot.ts";
-import { detectRuntimes, runtimeWiringLines } from "#runtime/wiring.ts";
+import { configFilePath, loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
 import { runSeed } from "#seed/seed.ts";
 import { getTasksForWeek, listTasks } from "#tasks/taskStore.ts";
 import { computeWeekRange } from "#tasks/weekView.ts";
-import { isExecutable } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
@@ -105,7 +101,7 @@ import {
   runReject,
   runShadowApply as runShadowApplyRoute,
 } from "./cultivationRoute.ts";
-import { MirrorHomeNotConfiguredError, resolveDbPath } from "./dbPath.ts";
+import { initCommandFor, MirrorHomeNotConfiguredError, resolveDbPath } from "./dbPath.ts";
 import { runBackupRoute, runRepairEncodingRoute } from "./dbSafetyToolsRoute.ts";
 import { defaultExploreRouteDeps, runExploreRoute } from "./exploreRoute.ts";
 import { frontDoorLogPath, logFrontDoor } from "./frontDoorLog.ts";
@@ -114,8 +110,10 @@ import {
   isImportedConversationsCommand,
   runImportedConversationsRoute,
 } from "./importedConversationsRoute.ts";
+import { runInit } from "./initRoute.ts";
 import { applyJourneySetPath } from "./journeyWriteRoute.ts";
 import { openLiveWriteDatabase } from "./liveBackup.ts";
+import { findMirrorHomes, homesRoot } from "./mirrorHomes.ts";
 import {
   isMirrorDoorman,
   isMirrorWrite,
@@ -454,7 +452,10 @@ function runWeekSaveWrite(argv: readonly string[]): number {
  * in depth.
  */
 async function runJournalContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, JOURNAL_TRANSPORT);
+  // CR187: refused before the database opens, saying what was not kept.
+  const family = await requireFamilyProviders(process.env, JOURNAL_TRANSPORT, {
+    consequence: "the journal entry was not saved",
+  });
   if (!family?.llm || !family.embedding) {
     throw new Error("journal requires an LLM and an embedding provider");
   }
@@ -467,14 +468,15 @@ async function runJournalContentRoute(argv: readonly string[]): Promise<number>
 }
 
 async function runWeekPlanContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, WEEK_PLAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, WEEK_PLAN_TRANSPORT);
   if (!family?.llm) throw new Error("week plan requires an LLM provider");
   const llm = family.llm;
   return withLiveWriteDbAsync(argv, (db) => runWeekPlanRoute(db, argv.slice(2), llm));
 }
 
 async function runDescriptorContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, DESCRIPTOR_TRANSPORT);
+  // CR187: without the key every persona would read "skipped (empty response)".
+  const family = await requireFamilyProviders(process.env, DESCRIPTOR_TRANSPORT);
   if (!family?.llm) throw new Error("descriptor generate requires an LLM provider");
   const llm = family.llm;
   const reporter = outcomeReporter(argv, "descriptor");
@@ -884,90 +886,6 @@ function isInit(argv: readonly string[]): boolean {
   return argv[0] === "init";
 }
 
-/**
- * Serve `init <user>` (DS7.US1 Slice B). Filesystem-only — no database is
- * opened. Python's argparse defines only the `user` positional (no
- * --mirror-home/--db-path), so none are stripped here.
- *
- * Deliberate divergence: an already-populated identity root or a missing
- * templates root are uncaught exceptions in Python (a raw traceback, exit 1) --
- * not a designed message. This preserves the contract (exit 1, a stderr
- * message naming the failure) without fabricating a fake traceback.
- *
- * CV22.DS10.US3 (D3): when no source configured a user, `init` writes
- * `MIRROR_USER=<user>` into `~/.config/mirror/env` (0600 in 0700) and says
- * where to add `OPENROUTER_API_KEY` by hand. The key is never read from argv.
- * When a user IS configured -- the checkout's `.env`, or a shell running a
- * second mirror -- the file is left alone and the person is told how to
- * select the new home.
- *
- * Plateau 3: it ends with the wiring step for each runtime found on the PATH
- * (`#runtime/wiring.ts`), with this tree's path in it, so the person is handed
- * the next line rather than a page. Printing is not automating.
- */
-function runInit(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): number {
-  const user = argv[1];
-  // A word that starts with `-` is a flag this command does not have, not a
-  // user: `init --help` once created a home named `--help`.
-  if (!user || user.startsWith("-")) {
-    console.error("Usage: init <user>");
-    return 2;
-  }
-  // And any other word is a key: the home's directory name and the value of
-  // MIRROR_USER in the wiring commands printed below. CR104's rule for slugs
-  // and persona ids, asked before anything is created (CR141).
-  const problem = newUserNameProblem(user);
-  if (problem !== null) {
-    console.error(`Error: ${problem}`);
-    return 2;
-  }
-  try {
-    const identityRoot = initUserHome(user);
-    const mirrorHome = dirname(identityRoot);
-    const configured = Boolean(env.MIRROR_USER || env.MIRROR_HOME);
-    const configuration = configured
-      ? [
-          `  1. This machine already selects a user; to use this one, run with MIRROR_USER=${user}`,
-          `     or set it in ${configFilePath(env)}`,
-        ]
-      : [
-          `Configuration: ${writeConfigValue("MIRROR_USER", user, { env })} (MIRROR_USER=${user})`,
-          "",
-          "Next steps:",
-          "  1. Add OPENROUTER_API_KEY=<your key> to that file (it is created readable by you only)",
-        ];
-    const prints = [
-      `Created user home: ${mirrorHome}`,
-      `Identity ready at: ${identityRoot}`,
-      ...(configured ? ["", "Next steps:"] : []),
-      ...configuration,
-      `  2. Run: ${PROGRAM} seed`,
-      "\nYour identity is ready to use. Deepen it over time with:",
-      `  ${PROGRAM} identity edit user identity`,
-      ...runtimeWiringSection(env),
-    ];
-    process.stdout.write(prints.map((line) => `${line}\n`).join(""));
-    return 0;
-  } catch (error) {
-    if (error instanceof IdentityRootExistsError || error instanceof TemplatesNotFoundError) {
-      console.error(error.message);
-      return 1;
-    }
-    throw error;
-  }
-}
-
-/** The "Wire your runtime" tail of `init`, empty when no runtime is on the PATH. */
-function runtimeWiringSection(env: NodeJS.ProcessEnv): string[] {
-  const detected = detectRuntimes(env, isExecutable);
-  if (detected.length === 0) return [];
-  const root = runningTreeRoot();
-  return [
-    "\nWire your runtime to this install (each step is one you run and can read first):",
-    ...detected.flatMap((runtime) => ["", ...runtimeWiringLines(runtime, root)]),
-  ];
-}
-
 function isSeed(argv: readonly string[]): boolean {
   return argv[0] === "seed";
 }
@@ -1408,7 +1326,7 @@ async function runConsolidateScanWrite(argv: readonly string[]): Promise<number>
   const limit = limitRaw !== null ? Number(limitRaw) : DEFAULT_CONSOLIDATE_SCAN_LIMIT;
   const thresholdRaw = optionValue(args, "--threshold");
   const threshold = thresholdRaw !== null ? Number(thresholdRaw) : DEFAULT_CLUSTER_THRESHOLD;
-  const family = await resolveFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
   if (!family?.llm) throw new Error("consolidate scan requires an LLM provider");
   const provider = family.llm;
   const reporter = outcomeReporter(argv, "consolidation");
@@ -1435,7 +1353,7 @@ async function runShadowScanWrite(argv: readonly string[]): Promise<number> {
   const args = argv.slice(2);
   const limitRaw = optionValue(args, "--limit");
   const limit = limitRaw !== null ? Number(limitRaw) : DEFAULT_SHADOW_SCAN_LIMIT;
-  const family = await resolveFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
   if (!family?.llm) throw new Error("shadow scan requires an LLM provider");
   const provider = family.llm;
   const reporter = outcomeReporter(argv, "shadow_scan");
@@ -1663,6 +1581,9 @@ function resolveLogPath(argv: readonly string[]): string | null {
  * itself, extended to db resolution.
  */
 async function runConsultAskWithDb(argv: readonly string[]): Promise<number> {
+  // CR187: before the ledger database opens, because that open takes the
+  // pre-write snapshot; the route checks again, for `consult credits`.
+  requireKeyForFamily(process.env, CONSULT_ASK_TRANSPORT);
   const db = tryOpenDbForConsultLogging(argv);
   try {
     process.stdout.write(await runConsultRoute(db, argv.slice(1)));
@@ -1904,9 +1825,17 @@ export async function main(rawArgv = process.argv.slice(2)): Promise<number> {
   // name is whatever the caller typed, and it stays out of the log.
   if (decision.engine === "usage") {
     const env = process.env;
+    const userConfigured = Boolean(
+      env.MIRROR_USER || env.MIRROR_HOME || env.MEMORY_DIR || env.DB_PATH,
+    );
     const answer = answerUsage(decision.request, {
-      userConfigured: Boolean(env.MIRROR_USER || env.MIRROR_HOME || env.MEMORY_DIR || env.DB_PATH),
+      userConfigured,
       configFile: configFilePath(env),
+      // CR185: a home on disk that nothing selects is named, read only when no
+      // user is configured -- the one case the orientation is rendered.
+      useHome: userConfigured
+        ? null
+        : (initCommandFor(findMirrorHomes(), homesRoot())?.sentence ?? null),
     });
     (answer.stream === "stdout" ? process.stdout : process.stderr).write(answer.text);
     logFrontDoor(logPath, {

package/ts/src/frontDoor/consultRoute.ts

@@ -1,7 +1,7 @@
 import { parseConsultArgs } from "#consult/args.ts";
 import { runConsult } from "#consult/core.ts";
 import type { WritableDatabase } from "#db/database.ts";
-import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { requireFamilyProviders } from "#providers/familyProviders.ts";
 import { CONSULT_ASK_TRANSPORT, CONSULT_CREDITS_TRANSPORT } from "#providers/transport.ts";
 
 /**
@@ -17,7 +17,9 @@ export async function runConsultRoute(
   // Per leaf, from the same specs `routing.ts` decided with: `credits` needs
   // only a credit provider, `ask` needs a chat provider too (CV22.DS8.US3).
   const spec = command.command === "credits" ? CONSULT_CREDITS_TRANSPORT : CONSULT_ASK_TRANSPORT;
-  const family = await resolveFamilyProviders(process.env, spec);
+  // CR187: no provider call without the key; `ask` checked before its ledger
+  // database opened, `credits` has none to open.
+  const family = await requireFamilyProviders(process.env, spec);
   if (!family?.credits) {
     // `routing.ts` sends a reverted or half-configured family to Python before
     // the route is reached, so this is defense in depth.

package/ts/src/frontDoor/dbPath.ts

@@ -14,7 +14,10 @@
 //   modern `~/.mirror-minds/<user>` does not exist (one-line stderr warning,
 //   permanent support — see docs/project/decisions.md).
 // - Nothing configured fails loudly (CV9.E2.S6: unconfigured resolution must
-//   not write to the homes root), unlike the pre-CR024 silent fallback.
+//   not write to the homes root), unlike the pre-CR024 silent fallback. The
+//   sentence says what to run and which file that writes, naming the homes it
+//   finds (CR185): a move from a clone to the package leaves a home that no
+//   configuration points at, and the person needs the command, not the cause.
 //
 // Front-door-only extension: the CLI flags `--db-path` and `--mirror-home`
 // are explicit per-invocation intent and take precedence over all env vars.
@@ -22,8 +25,13 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { configFilePath } from "#runtime/config.ts";
 import { expandHome } from "#util/paths.ts";
+import { PROGRAM } from "#util/program.ts";
+import { pyRepr } from "#util/pythonText.ts";
+import { shellWord } from "#util/shellWord.ts";
 import { optionValue } from "./args.ts";
+import { type FoundHome, findMirrorHomes, homesRoot, userHomePath } from "./mirrorHomes.ts";
 
 /** Raised when no database location can be resolved — maps to CLI exit 2. */
 export class MirrorHomeNotConfiguredError extends Error {}
@@ -34,7 +42,6 @@ const DB_NAMES: Record<string, string> = {
   test: "memory_test.db",
 };
 
-const DEFAULT_USER_HOMES_DIR = ".mirror-minds";
 const LEGACY_USER_HOMES_DIR = ".mirror";
 
 /** Port of Python `db_name_for_env`: one (environment) → one database name. */
@@ -50,6 +57,8 @@ export interface DbPathEnv {
   MEMORY_DIR?: string;
   MIRROR_HOME?: string;
   MIRROR_USER?: string;
+  /** Read only to name the config file in the not-configured sentence. */
+  XDG_CONFIG_HOME?: string;
 }
 
 /** Injection points so tests can run without touching the real filesystem. */
@@ -57,6 +66,8 @@ export interface DbPathIo {
   home?: string;
   exists?: (path: string) => boolean;
   warn?: (message: string) => void;
+  /** The homes under `<home>/.mirror-minds`, for the not-configured sentence. */
+  homes?: (home: string) => readonly FoundHome[];
 }
 
 /**
@@ -72,7 +83,7 @@ export function resolveMirrorHome(env: DbPathEnv, io: DbPathIo = {}): string {
   const explicitHome = env.MIRROR_HOME ?? "";
   const explicitUser = env.MIRROR_USER ?? "";
   const resolvedHome = explicitHome ? expandHome(explicitHome) : null;
-  const derivedHome = explicitUser ? join(home, DEFAULT_USER_HOMES_DIR, explicitUser) : null;
+  const derivedHome = explicitUser ? userHomePath(explicitUser, home) : null;
 
   if (resolvedHome && explicitUser && basename(resolvedHome) !== explicitUser) {
     throw new MirrorHomeNotConfiguredError(
@@ -94,10 +105,72 @@ export function resolveMirrorHome(env: DbPathEnv, io: DbPathIo = {}): string {
     }
     return derivedHome;
   }
-  throw new MirrorHomeNotConfiguredError(
-    "Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER " +
-      "(or pass an explicit MEMORY_DIR/DB_PATH override).",
-  );
+  throw new MirrorHomeNotConfiguredError(homeNotConfiguredMessage(env, io));
+}
+
+/**
+ * The not-configured sentence (CR185), one line: what to run, and which file
+ * that command writes.
+ *
+ * Every surface prints it: `runtime update`, `migrate`, and `backup` bare, the
+ * other commands after `Mirror TS front door:`, and `runtime status` as its
+ * `Mirror home note:`. Built only when nothing resolves, so a hook on an
+ * unconfigured machine pays one directory read for a message it discards.
+ *
+ * A home name reaches the line bare only when `init` accepts it, so the line
+ * cannot be broken, or carry an escape sequence, by a directory name. Any other
+ * home is offered `MIRROR_HOME`, its path printed as a repr.
+ */
+export function homeNotConfiguredMessage(env: DbPathEnv, io: DbPathIo = {}): string {
+  const home = io.home ?? homedir();
+  const config = configFilePath({ XDG_CONFIG_HOME: env.XDG_CONFIG_HOME }, home);
+  const homes = (io.homes ?? findMirrorHomes)(home);
+  const sentences: string[] = [];
+  const command = initCommandFor(homes, homesRoot(home));
+  if (command !== null) {
+    sentences.push(`${command.sentence} (it writes MIRROR_USER=${command.name} to ${config}).`);
+  }
+  for (const other of homes.filter((found) => !found.nameable)) {
+    const path = pyRepr(other.path);
+    sentences.push(`To use the home at ${path}, add MIRROR_HOME=${path} to ${config}.`);
+  }
+  if (sentences.length === 0) {
+    const create = `${PROGRAM} init <your-name>`;
+    sentences.push(
+      `To create one, run: ${create} (it writes MIRROR_USER=<your-name> to ${config}).`,
+      `If yours lives elsewhere, add MIRROR_HOME=<path> to ${config}.`,
+    );
+  }
+  return ["Mirror home is not configured.", ...sentences].join(" ");
+}
+
+/**
+ * "To use the home at <path>, run: mirror init <name>", or the form for
+ * several, for the homes `init` can name; null when there are none. `name` is
+ * what the command takes: the one home's own name, or `<name>`. Bare `mirror`
+ * prints the same sentence.
+ *
+ * The command is built on a line of its own, its value through `shellWord`
+ * (CR104): an agent runs it as printed. A name `init` accepts is a plain token,
+ * so it prints unchanged. The path and the names around the command are prose.
+ */
+export function initCommandFor(
+  homes: readonly FoundHome[],
+  root: string,
+): { sentence: string; name: string } | null {
+  const nameable = homes.filter((found) => found.nameable);
+  const [only] = nameable;
+  if (only === undefined) return null;
+  if (nameable.length === 1) {
+    const command = `${PROGRAM} init ${shellWord(only.name)}`;
+    return { sentence: `To use the home at ${only.path}, run: ${command}`, name: only.name };
+  }
+  const names = nameable.map((found) => found.name).join(", ");
+  const command = `${PROGRAM} init <name>`;
+  return {
+    sentence: `To use one of the homes in ${root} (${names}), run: ${command}`,
+    name: "<name>",
+  };
 }
 
 /**