From eae4b0bdc0304c10bbeb4dfbf787ff7cb4988445 Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 04:16:38 +0200
Subject: [PATCH 1/7] feat(cli): pair homes into private ~/.miakapp contexts

Adds persistent multi-home credentials and a pairing flow so an agent never
re-exports MIAKAPP_HOME_KEY and never signs in on the owner's behalf.

- miakapp pair redeems a one-time code (stdin pipe or hidden prompt; --code
  allowed, never echoed) at a pinned HTTPS issuer: discovery must name that
  exact issuer before the code is sent, redirects are refused, and the
  POST /v1/pairing/redeem response must be no-store, name the same issuer and
  carry its key_id inside home_key. The new key is stored as a new context,
  others are kept, and a publication token exchange proves it works.
- ~/.miakapp/config.json (no secrets) and credentials.json (keys only),
  0600 in a 0700 directory, atomic temp+fsync+rename under a lock file;
  loose permissions, symlinks, foreign owners and swapped keys are refused.
- context list/show/use/remove, never printing a key.
- Per-invocation selection: --context, MIAKAPP_CONTEXT, MIAKAPP_HOME_KEY (CI),
  then the context paired with the home in miakapp.yaml. A context or a known
  key for another home is refused before any request.
- status reads the live pointer (RFC 0004 component-pointer); publish and
  activate default --expected-generation to it, still compare-and-set.
- init defaults --home/--control-plane from the selected context.
- MCP exposes pair, status and the context actions; remove needs confirm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/cli/bin/miakapp.js                |   6 +-
 packages/cli/src/contexts.ts               | 438 ++++++++++++++
 packages/cli/src/main.ts                   | 658 +++++++++++++++++++--
 packages/cli/src/mcp.ts                    | 207 ++++++-
 packages/cli/src/pairing.ts                | 197 ++++++
 packages/cli/src/publication.ts            |  39 ++
 packages/cli/src/terminal.ts               |  85 +++
 packages/cli/test/contexts.test.ts         | 646 ++++++++++++++++++++
 packages/cli/test/mcp.test.ts              |  49 +-
 packages/cli/test/support/control-plane.ts |  71 ++-
 packages/cli/test/support/host.ts          |  11 +
 packages/cli/test/terminal.test.ts         | 108 ++++
 12 files changed, 2421 insertions(+), 94 deletions(-)
 create mode 100644 packages/cli/src/contexts.ts
 create mode 100644 packages/cli/src/pairing.ts
 create mode 100644 packages/cli/src/terminal.ts
 create mode 100644 packages/cli/test/contexts.test.ts
 create mode 100644 packages/cli/test/terminal.test.ts

diff --git a/packages/cli/bin/miakapp.js b/packages/cli/bin/miakapp.js
index f48ba44..baaf88a 100755
--- a/packages/cli/bin/miakapp.js
+++ b/packages/cli/bin/miakapp.js
@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { run } from '../dist/main.js';
+import { readSecret } from '../dist/terminal.js';
+
+const writeError = (text) => void process.stderr.write(text);
 
 process.exitCode = await run(process.argv.slice(2), {
   write: (text) => void process.stdout.write(text),
-  writeError: (text) => void process.stderr.write(text),
+  writeError,
   cwd: () => process.cwd(),
   env: (name) => process.env[name],
   input: process.stdin,
+  readSecret: (prompt) => readSecret(process.stdin, prompt, writeError),
 });
diff --git a/packages/cli/src/contexts.ts b/packages/cli/src/contexts.ts
new file mode 100644
index 0000000..e7b63c4
--- /dev/null
+++ b/packages/cli/src/contexts.ts
@@ -0,0 +1,438 @@
+/**
+ * Persistent, multi-home CLI contexts in `~/.miakapp`.
+ *
+ * A context names one Home Key for one home at one issuer, so an agent or a
+ * machine that works on several homes never re-exports a secret and never
+ * guesses which secret belongs to which house. Two files, split by sensitivity:
+ *
+ * - `config.json` holds what is safe to show: the context names, their issuer,
+ *   home ID, key ID, key label and the current context. Printing it leaks
+ *   nothing.
+ * - `credentials.json` holds the Home Keys and nothing else.
+ *
+ * Both are written mode 0600 inside a 0700 directory, through a temporary file,
+ * an fsync and a rename, so a crash leaves either the old file or the new one
+ * and never half of each. A lock file serializes writers: two `miakapp pair`
+ * runs finishing at the same moment must both keep their context, because the
+ * code each one redeemed cannot be redeemed again.
+ *
+ * Reads refuse a credentials file that another account could read or replace,
+ * the way `ssh` refuses a private key with loose permissions: silently using a
+ * leaked key is worse than stopping.
+ */
+import { randomBytes } from 'node:crypto';
+import { isAbsolute, join } from 'node:path';
+import { authorizationError, usageError } from './errors.js';
+import { canonicalHttpsUrl } from './internal/http.js';
+import { InvalidJsonError, boundedString, exactRecord, parseJson } from './internal/json.js';
+import { isHomeId, isRandomId } from './internal/names.js';
+
+export const CONFIG_DIRECTORY_VARIABLE = 'MIAKAPP_CONFIG_DIR';
+export const CONFIG_FILE = 'config.json';
+export const CREDENTIALS_FILE = 'credentials.json';
+export const CONFIG_SCHEMA = 'miakapp.cli-config/1';
+export const CREDENTIALS_SCHEMA = 'miakapp.cli-credentials/1';
+
+const LOCK_FILE = 'lock';
+const LOCK_WAIT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const MAXIMUM_FILE_BYTES = 262_144;
+const MAXIMUM_CONTEXTS = 256;
+const CONTEXT_NAME = /^[a-z0-9][a-z0-9._-]{0,62}$/;
+const HOME_KEY = /^mhk1_([A-Za-z0-9_-]{22})_([A-Za-z0-9_-]{43})$/;
+
+export interface StoredContext {
+  readonly name: string;
+  readonly issuer: string;
+  readonly homeId: string;
+  readonly keyId: string;
+  readonly label: string;
+  readonly createdAt: string;
+}
+
+export interface ContextState {
+  readonly current: string | null;
+  readonly contexts: ReadonlyMap<string, StoredContext>;
+}
+
+/** Whether a context's Home Key is present and is the key it was paired with. */
+export type CredentialStatus = 'stored' | 'missing' | 'mismatched';
+
+interface Snapshot extends ContextState {
+  readonly keys: ReadonlyMap<string, string>;
+}
+
+export function isContextName(value: unknown): value is string {
+  return typeof value === 'string' && CONTEXT_NAME.test(value);
+}
+
+export function contextNameError(name: string): never {
+  throw usageError(
+    `Invalid context name ${JSON.stringify(name)}`,
+    'A context name is 1..63 characters of a-z, 0-9, ".", "_" and "-", starting with a letter or digit.',
+  );
+}
+
+/**
+ * The directory holding both files. `MIAKAPP_CONFIG_DIR` relocates it for CI,
+ * containers and tests; it must be absolute so a relative value can never
+ * resolve to a different directory from one working directory to the next.
+ */
+export function configDirectory(env: (name: string) => string | undefined, home: string): string {
+  const override = env(CONFIG_DIRECTORY_VARIABLE);
+  if (override !== undefined && override !== '') {
+    if (!isAbsolute(override)) {
+      throw usageError(`${CONFIG_DIRECTORY_VARIABLE} must be an absolute path`);
+    }
+    return override;
+  }
+  return join(home, '.miakapp');
+}
+
+function enforcesModes(): boolean {
+  return process.platform !== 'win32';
+}
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === 'object' && error !== null && 'code' in error
+    ? String((error as { code: unknown }).code)
+    : undefined;
+}
+
+function storeError(path: string, problem: string): never {
+  throw authorizationError(
+    `${path} ${problem}`,
+    'Repair or remove the file, then pair again with miakapp pair. The CLI never guesses at a '
+    + 'credential store it cannot read exactly.',
+  );
+}
+
+async function readStoreFile(path: string, secret: boolean): Promise<Uint8Array | undefined> {
+  const fs = await import('node:fs/promises');
+  let status;
+  try {
+    status = await fs.lstat(path);
+  } catch (error) {
+    if (errorCode(error) === 'ENOENT') return undefined;
+    throw error;
+  }
+  if (!status.isFile()) storeError(path, 'is not a regular file (symbolic links are refused)');
+  if (status.size > MAXIMUM_FILE_BYTES) storeError(path, 'is larger than any context store');
+  if (enforcesModes()) {
+    const uid = process.getuid?.();
+    if (uid !== undefined && status.uid !== uid) storeError(path, 'is owned by another account');
+    // The credentials must be private. The configuration holds no secret, but
+    // anyone able to rewrite it could repoint a context at their own issuer.
+    const forbidden = secret ? 0o077 : 0o022;
+    if ((status.mode & forbidden) !== 0) {
+      throw authorizationError(
+        `${path} is accessible to other accounts (mode ${(status.mode & 0o777).toString(8)})`,
+        `Run chmod 600 ${path}. Rotate the Home Keys it holds if anyone else could have read it.`,
+      );
+    }
+  }
+  return new Uint8Array(await fs.readFile(path));
+}
+
+function decodeDocument(path: string, bytes: Uint8Array): Readonly<Record<string, unknown>> {
+  try {
+    const value = parseJson(bytes);
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      return storeError(path, 'is not a JSON object');
+    }
+    return value as Readonly<Record<string, unknown>>;
+  } catch (error) {
+    if (error instanceof InvalidJsonError) return storeError(path, 'is not valid JSON');
+    throw error;
+  }
+}
+
+function decodeContext(path: string, name: string, value: unknown): StoredContext {
+  try {
+    const entry = exactRecord(value, ['issuer', 'home_id', 'key_id', 'label', 'created_at']);
+    const issuer = canonicalHttpsUrl(entry.issuer, 'issuer');
+    if (issuer.endsWith('/') || !isHomeId(entry.home_id) || !isRandomId(entry.key_id)) {
+      throw new InvalidJsonError();
+    }
+    return Object.freeze({
+      name,
+      issuer,
+      homeId: entry.home_id,
+      keyId: entry.key_id,
+      label: boundedString(entry.label, 1, 64),
+      createdAt: boundedString(entry.created_at, 1, 64),
+    });
+  } catch {
+    return storeError(path, `holds an invalid context ${JSON.stringify(name)}`);
+  }
+}
+
+async function readSnapshot(directory: string): Promise<Snapshot> {
+  const configPath = join(directory, CONFIG_FILE);
+  const credentialsPath = join(directory, CREDENTIALS_FILE);
+  const contexts = new Map<string, StoredContext>();
+  const keys = new Map<string, string>();
+  let current: string | null = null;
+
+  const configBytes = await readStoreFile(configPath, false);
+  if (configBytes !== undefined) {
+    const document = decodeDocument(configPath, configBytes);
+    if (document.schema !== CONFIG_SCHEMA) storeError(configPath, `does not declare ${CONFIG_SCHEMA}`);
+    let entries: Readonly<Record<string, unknown>>;
+    try {
+      exactRecord(document, ['schema', 'current_context', 'contexts']);
+      entries = exactRecord(document.contexts, [], Object.keys(document.contexts ?? {}));
+    } catch {
+      return storeError(configPath, 'does not match the closed configuration schema');
+    }
+    const names = Object.keys(entries);
+    if (names.length > MAXIMUM_CONTEXTS) storeError(configPath, 'holds too many contexts');
+    for (const name of names) {
+      if (!isContextName(name)) storeError(configPath, `holds an invalid context name ${JSON.stringify(name)}`);
+      contexts.set(name, decodeContext(configPath, name, entries[name]));
+    }
+    const selected = document.current_context;
+    if (selected !== null && (typeof selected !== 'string' || !contexts.has(selected))) {
+      storeError(configPath, 'names a current context it does not define');
+    }
+    current = selected as string | null;
+  }
+
+  const credentialBytes = await readStoreFile(credentialsPath, true);
+  if (credentialBytes !== undefined) {
+    const document = decodeDocument(credentialsPath, credentialBytes);
+    if (document.schema !== CREDENTIALS_SCHEMA) {
+      storeError(credentialsPath, `does not declare ${CREDENTIALS_SCHEMA}`);
+    }
+    let entries: Readonly<Record<string, unknown>>;
+    try {
+      exactRecord(document, ['schema', 'credentials']);
+      entries = exactRecord(document.credentials, [], Object.keys(document.credentials ?? {}));
+    } catch {
+      return storeError(credentialsPath, 'does not match the closed credentials schema');
+    }
+    for (const [name, value] of Object.entries(entries)) {
+      let key: unknown;
+      try {
+        key = exactRecord(value, ['home_key']).home_key;
+      } catch {
+        key = undefined;
+      }
+      if (typeof key !== 'string' || !HOME_KEY.test(key)) {
+        storeError(credentialsPath, `holds an invalid credential for ${JSON.stringify(name)}`);
+      }
+      keys.set(name, key);
+    }
+  }
+  return { current, contexts, keys };
+}
+
+function credentialStatus(snapshot: Snapshot, context: StoredContext): CredentialStatus {
+  const key = snapshot.keys.get(context.name);
+  if (key === undefined) return 'missing';
+  return HOME_KEY.exec(key)?.[1] === context.keyId ? 'stored' : 'mismatched';
+}
+
+/**
+ * Reads the safe half of the store, plus whether each key is present. A
+ * missing directory is an empty store. No Home Key leaves this function.
+ */
+export async function readContexts(
+  directory: string,
+): Promise<ContextState & { readonly credentials: ReadonlyMap<string, CredentialStatus> }> {
+  const snapshot = await readSnapshot(directory);
+  const credentials = new Map<string, CredentialStatus>();
+  for (const context of snapshot.contexts.values()) {
+    credentials.set(context.name, credentialStatus(snapshot, context));
+  }
+  return { current: snapshot.current, contexts: snapshot.contexts, credentials };
+}
+
+/**
+ * Returns one context and its Home Key, or fails with a remedy.
+ *
+ * The key ID recorded at pairing time is compared with the stored key, so a
+ * credentials file edited by hand cannot silently attach another home's key to
+ * this context.
+ */
+export async function readCredential(
+  directory: string,
+  name: string,
+): Promise<{ readonly context: StoredContext; readonly homeKey: string }> {
+  const snapshot = await readSnapshot(directory);
+  const context = snapshot.contexts.get(name);
+  if (context === undefined) {
+    const known = [...snapshot.contexts.keys()];
+    throw usageError(
+      `No context named ${name}`,
+      known.length === 0
+        ? 'No context is configured yet. Run miakapp pair to add one.'
+        : `Known contexts: ${known.join(', ')}. Run miakapp context list for details.`,
+    );
+  }
+  const homeKey = snapshot.keys.get(name);
+  const status = credentialStatus(snapshot, context);
+  if (homeKey === undefined || status === 'missing') {
+    throw authorizationError(
+      `Context ${name} has no stored credential`,
+      `Remove it with miakapp context remove ${name} and pair the home again.`,
+    );
+  }
+  if (status === 'mismatched') {
+    throw authorizationError(
+      `The credential stored for ${name} is not the key ${context.keyId} it was paired with`,
+      `Remove the context with miakapp context remove ${name} and pair the home again.`,
+    );
+  }
+  return { context, homeKey };
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+  const fs = await import('node:fs/promises');
+  let handle;
+  try {
+    handle = await fs.open(directory, 'r');
+    await handle.sync();
+  } catch {
+    // Not every platform can fsync a directory; the rename is still atomic.
+  } finally {
+    await handle?.close();
+  }
+}
+
+/**
+ * Replaces one file atomically with a private one. The temporary name is
+ * random and opened exclusively, so a stale temporary from a crashed run can
+ * neither be reused nor followed.
+ */
+async function writeAtomic(directory: string, name: string, document: unknown): Promise<void> {
+  const fs = await import('node:fs/promises');
+  const target = join(directory, name);
+  const temporary = join(directory, `.${name}.${randomBytes(8).toString('hex')}.tmp`);
+  const handle = await fs.open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(document, null, 2)}\n`);
+    if (enforcesModes()) await handle.chmod(0o600);
+    await handle.sync();
+  } catch (error) {
+    await handle.close();
+    await fs.rm(temporary, { force: true });
+    throw error;
+  }
+  await handle.close();
+  try {
+    await fs.rename(temporary, target);
+  } catch (error) {
+    await fs.rm(temporary, { force: true });
+    throw error;
+  }
+  await syncDirectory(directory);
+}
+
+async function ensureDirectory(directory: string): Promise<void> {
+  const fs = await import('node:fs/promises');
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const status = await fs.lstat(directory);
+  if (!status.isDirectory()) {
+    throw authorizationError(`${directory} is not a directory`, 'Move it aside and run the command again.');
+  }
+  if (enforcesModes()) {
+    const uid = process.getuid?.();
+    if (uid !== undefined && status.uid !== uid) {
+      throw authorizationError(`${directory} is owned by another account`, 'Use a directory you own.');
+    }
+    if ((status.mode & 0o077) !== 0) await fs.chmod(directory, 0o700);
+  }
+}
+
+async function acquireLock(directory: string): Promise<() => Promise<void>> {
+  const fs = await import('node:fs/promises');
+  const path = join(directory, LOCK_FILE);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  while (true) {
+    try {
+      const handle = await fs.open(path, 'wx', 0o600);
+      await handle.writeFile(`${process.pid}\n`);
+      await handle.close();
+      return async () => {
+        await fs.rm(path, { force: true });
+      };
+    } catch (error) {
+      if (errorCode(error) !== 'EEXIST') throw error;
+    }
+    try {
+      const status = await fs.stat(path);
+      if (Date.now() - status.mtimeMs > LOCK_STALE_MS) {
+        await fs.rm(path, { force: true });
+        continue;
+      }
+    } catch (error) {
+      if (errorCode(error) === 'ENOENT') continue;
+      throw error;
+    }
+    if (Date.now() > deadline) {
+      throw authorizationError(
+        `Another miakapp process holds ${path}`,
+        'Wait for it to finish. If none is running, delete the lock file.',
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}
+
+export interface Mutation {
+  current: string | null;
+  readonly contexts: Map<string, StoredContext>;
+  readonly keys: Map<string, string>;
+}
+
+/**
+ * Applies one change under the lock and writes both files.
+ *
+ * The credentials are written before the configuration, so a crash between the
+ * two leaves an unreferenced key rather than a context with no key. The next
+ * write drops any credential no context references.
+ */
+export async function mutateContexts<T>(
+  directory: string,
+  change: (state: Mutation) => T,
+): Promise<T> {
+  await ensureDirectory(directory);
+  const release = await acquireLock(directory);
+  try {
+    const snapshot = await readSnapshot(directory);
+    const state: Mutation = {
+      current: snapshot.current,
+      contexts: new Map(snapshot.contexts),
+      keys: new Map(snapshot.keys),
+    };
+    const result = change(state);
+    if (state.contexts.size > MAXIMUM_CONTEXTS) {
+      throw usageError(`At most ${MAXIMUM_CONTEXTS} contexts can be stored`);
+    }
+    if (state.current !== null && !state.contexts.has(state.current)) state.current = null;
+
+    const credentials: Record<string, { home_key: string }> = {};
+    const contexts: Record<string, unknown> = {};
+    for (const [name, context] of [...state.contexts].sort(([a], [b]) => (a < b ? -1 : 1))) {
+      const key = state.keys.get(name);
+      if (key !== undefined) credentials[name] = { home_key: key };
+      contexts[name] = {
+        issuer: context.issuer,
+        home_id: context.homeId,
+        key_id: context.keyId,
+        label: context.label,
+        created_at: context.createdAt,
+      };
+    }
+    await writeAtomic(directory, CREDENTIALS_FILE, { schema: CREDENTIALS_SCHEMA, credentials });
+    await writeAtomic(directory, CONFIG_FILE, {
+      schema: CONFIG_SCHEMA,
+      current_context: state.current,
+      contexts,
+    });
+    return result;
+  } finally {
+    await release();
+  }
+}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index cd71178..d86beae 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -14,25 +14,45 @@
  *   {@link EXIT_CODE}), so a wrapper decides without parsing prose;
  * - `--json`, which prints exactly one closed object on stdout.
  */
+import { homedir, hostname } from 'node:os';
 import { installPack } from './agent-pack.js';
 import { CLI_VERSION } from './version.js';
 import { prepareArtifact, type Artifact } from './artifact.js';
-import { exchangePublisherToken, fetchDiscovery } from './control-plane.js';
+import { exchangePublisherToken, fetchDiscovery, homeKeyId } from './control-plane.js';
+import {
+  configDirectory,
+  contextNameError,
+  isContextName,
+  mutateContexts,
+  readContexts,
+  readCredential,
+  type StoredContext,
+} from './contexts.js';
 import { discoverFlows, inventoryJson, type Inventory } from './discovery.js';
 import {
   CliError,
   EXIT_CODE,
   artifactError,
   authorizationError,
+  contractError,
   projectError,
   usageError,
 } from './errors.js';
 import type { FetchLike } from './internal/http.js';
 import { isDigest, isRelease, REQUIREMENT_KINDS, type Requirements } from './internal/names.js';
+import {
+  DEFAULT_ISSUER,
+  PAIRING_PAGE,
+  normalizeCode,
+  pairingIssuer,
+  redeemPairingCode,
+  validateLabel,
+} from './pairing.js';
 import { PROJECT_FILE, PROJECT_SCHEMA, findProjectFile, parseProject, type Project } from './project.js';
 import {
   activateRelease,
   publish,
+  readPointer,
   readRelease,
   readUpload,
   type ComponentPointer,
@@ -42,12 +62,16 @@ import {
 export { CLI_VERSION };
 
 /**
- * The Home Key is read from the environment only. A secret passed as an
- * argument would land in shell history, in a process listing and in most CI
- * logs, so no command accepts one.
+ * A Home Key comes from a paired context in `~/.miakapp` or, for CI and
+ * compatibility, from this variable. A secret passed as an argument would land
+ * in shell history, in a process listing and in most CI logs, so no command
+ * accepts one.
  */
 export const HOME_KEY_VARIABLE = 'MIAKAPP_HOME_KEY';
 
+/** Selects a stored context for one invocation, like `--context`. */
+export const CONTEXT_VARIABLE = 'MIAKAPP_CONTEXT';
+
 export interface FileSystem {
   read(path: string): Promise<Uint8Array>;
   /** Creates. Fails if the path exists: no command may clobber by accident. */
@@ -76,6 +100,16 @@ export interface CliHost {
   fetch?: FetchLike;
   /** Read only by `mcp`, which serves a request stream instead of one command. */
   input?: AsyncIterable<Uint8Array>;
+  /** Parent of `.miakapp`. Injected by tests; defaults to the account's home. */
+  homeDirectory?(): string;
+  /** Names the machine in a default key label. Defaults to the OS host name. */
+  hostname?(): string;
+  /**
+   * Reads one secret line without echoing it: a hidden prompt on a terminal,
+   * the first line of a pipe otherwise. Absent under MCP, whose stdin is the
+   * protocol stream.
+   */
+  readSecret?(prompt: string): Promise<string>;
 }
 
 type Field = readonly [key: string, value: string | number | readonly string[]];
@@ -102,10 +136,16 @@ Usage
 
 Commands
   docs start              Print the complete agent guide bundled with this CLI
+  pair                    Redeem a one-time pairing code into a stored context
+  context list            List stored contexts (never prints a key)
+  context show [name]     Show one context, the current one by default
+  context use <name>      Make a context current
+  context remove <name>   Delete a context and its stored key
   init                    Write ${PROJECT_FILE} in the current directory
   agent-pack              Install the guide and the MCP wiring into a repository
   discover                Inventory an existing Node-RED installation offline
   check                   Validate the project and the artifact offline
+  status                  Read the live generation and release of the home
   publish                 Upload, finalize and activate the built artifact
   activate                Activate an already finalized digest at a new generation
   rollback                Alias of activate, for returning to a known-good digest
@@ -118,15 +158,25 @@ Commands
 Common options
   --json                  Print one machine-readable object on stdout
   --project <dir>         Start the ${PROJECT_FILE} search here (default: cwd)
+  --context <name>        Use this stored context (status, publish, activate,
+                          rollback, release, upload, init)
+
+pair options
+  (code)                      Read from stdin: hidden prompt on a terminal, first
+                              line of a pipe otherwise. Preferred: never echoed.
+  --code <code>               Pass the code explicitly (lands in shell history)
+  --issuer <https url>        Control plane to redeem at (default: ${DEFAULT_ISSUER})
+  --label <label>             Key label shown to the owner (default: miakapp-cli@host)
+  --name <context>            Context name (default: the paired home ID)
 
 publish options
-  --expected-generation <n>   Generation the pointer is expected to hold (required)
+  --expected-generation <n>   Generation the pointer holds (default: read live)
   --generation <n>            Generation to publish (default: expected + 1)
   --release <name>            Override component.release from ${PROJECT_FILE}
 
 activate / rollback options
   --sha256 <digest>           Finalized artifact digest (required)
-  --expected-generation <n>   Generation the pointer is expected to hold (required)
+  --expected-generation <n>   Generation the pointer holds (default: read live)
   --generation <n>            Generation to publish (default: expected + 1)
 
 discover options
@@ -141,15 +191,22 @@ agent-pack options
   --dir <path>                Repository to install into (default: cwd)
 
 init options
-  --home <homeId>             Home ID to write into ${PROJECT_FILE} (required)
-  --control-plane <https url> Control-plane issuer (required)
+  --home <homeId>             Home ID (default: from the selected context)
+  --control-plane <https url> Control-plane issuer (default: from the context)
   --artifact <path>           Built artifact path (default: dist/component.js)
   --release <name>            Initial release name (default: 0.1.0)
 
+Credentials, highest precedence first
+  1. --context <name>       a context stored by miakapp pair
+  2. ${CONTEXT_VARIABLE}=<name>  the same, from the environment
+  3. ${HOME_KEY_VARIABLE}      a raw Home Key, for CI and compatibility
+  4. the stored context whose home and issuer match ${PROJECT_FILE}
+     (the current context wins a tie)
+  A stored context whose home or issuer differs from ${PROJECT_FILE} is refused,
+  so a key can never publish into another home. Keys are never printed.
+
 Environment
-  ${HOME_KEY_VARIABLE}   Home Key with the components:publish scope. Required by
-                     publish, activate, rollback, release and upload. It is never
-                     accepted as an argument and never printed.
+  MIAKAPP_CONFIG_DIR   Absolute directory replacing ~/.miakapp
 
 Exit codes
   0 success        1 usage        2 project      3 artifact
@@ -162,15 +219,18 @@ const GLOBAL_OPTIONS = ['project'] as const;
 /** Exported so the MCP surface can be proved to expose every option, and no other. */
 export const COMMAND_OPTIONS: Record<string, readonly string[]> = {
   docs: [],
-  init: ['home', 'control-plane', 'artifact', 'release'],
+  pair: ['code', 'issuer', 'label', 'name'],
+  context: [],
+  init: ['home', 'control-plane', 'artifact', 'release', 'context'],
   'agent-pack': ['dir'],
   discover: ['flows'],
   check: [],
-  publish: ['expected-generation', 'generation', 'release'],
-  activate: ['sha256', 'expected-generation', 'generation'],
-  rollback: ['sha256', 'expected-generation', 'generation'],
-  release: [],
-  upload: [],
+  status: ['context'],
+  publish: ['expected-generation', 'generation', 'release', 'context'],
+  activate: ['sha256', 'expected-generation', 'generation', 'context'],
+  rollback: ['sha256', 'expected-generation', 'generation', 'context'],
+  release: ['context'],
+  upload: ['context'],
   mcp: [],
   help: [],
   version: [],
@@ -255,21 +315,46 @@ function generationOption(invocation: Invocation, name: string): number {
   return value;
 }
 
-/** `--generation` defaults to one above the expected generation, never higher. */
-function generationPair(invocation: Invocation): {
-  expectedGeneration: number;
-  generation: number;
-} {
-  const expectedGeneration = generationOption(invocation, 'expected-generation');
+interface GenerationPlan {
+  readonly expectedGeneration: number | undefined;
+  readonly generation: number | undefined;
+}
+
+/** Validated before any network use, so a typo never costs a request. */
+function generationPlan(invocation: Invocation): GenerationPlan {
+  const expectedGeneration = invocation.options.has('expected-generation')
+    ? generationOption(invocation, 'expected-generation')
+    : undefined;
   const generation = invocation.options.has('generation')
     ? generationOption(invocation, 'generation')
-    : expectedGeneration + 1;
-  if (generation <= expectedGeneration) {
+    : undefined;
+  if (expectedGeneration !== undefined && generation !== undefined
+    && generation <= expectedGeneration) {
     throw usageError('--generation must be strictly above --expected-generation');
   }
   return { expectedGeneration, generation };
 }
 
+/**
+ * Resolves the compare-and-set pair. Without `--expected-generation` the live
+ * generation is read first. That read takes no lock: the activation is still a
+ * compare-and-set, so a publication that lands in between fails with
+ * `conflict` rather than being overwritten.
+ */
+async function resolveGenerations(
+  target: PublicationTarget,
+  plan: GenerationPlan,
+): Promise<{ expectedGeneration: number; generation: number }> {
+  const expectedGeneration = plan.expectedGeneration ?? (await readPointer(target)).generation;
+  const generation = plan.generation ?? expectedGeneration + 1;
+  if (generation <= expectedGeneration) {
+    throw usageError(
+      `--generation must be strictly above the live generation ${expectedGeneration}`,
+    );
+  }
+  return { expectedGeneration, generation };
+}
+
 function digestOption(invocation: Invocation, name: string): string {
   const value = requiredOption(invocation, name);
   if (!isDigest(value)) {
@@ -278,16 +363,117 @@ function digestOption(invocation: Invocation, name: string): string {
   return value;
 }
 
-function homeKey(host: CliHost): string {
-  const value = host.env(HOME_KEY_VARIABLE);
-  if (value === undefined || value === '') {
+function nonEmpty(value: string | undefined): string | undefined {
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function storeDirectory(host: CliHost): string {
+  return configDirectory((name) => host.env(name), host.homeDirectory?.() ?? homedir());
+}
+
+/** Where the Home Key of one invocation came from. The key itself never leaves. */
+interface Credential {
+  readonly homeKey: string;
+  readonly source: 'context' | 'environment';
+  readonly context: StoredContext | undefined;
+}
+
+/** The context named for this invocation, by flag first and then environment. */
+function explicitContext(host: CliHost, invocation: Invocation): string | undefined {
+  const name = invocation.options.get('context') ?? nonEmpty(host.env(CONTEXT_VARIABLE));
+  if (name !== undefined && !isContextName(name)) contextNameError(name);
+  return name;
+}
+
+/**
+ * The wrong-home guard. The project file says where a publication goes; a
+ * context says which home its key opens. When the two disagree the command
+ * stops, because the control plane would accept a valid key for home A
+ * publishing into home A, while the person meant home B.
+ */
+function requireSameHome(context: StoredContext, project: Project, origin: string): void {
+  if (context.homeId === project.homeId && context.issuer === project.issuer) return;
+  throw authorizationError(
+    `${origin} is for home ${context.homeId} at ${context.issuer}, but ${PROJECT_FILE} targets `
+    + `home ${project.homeId} at ${project.issuer}`,
+    'Select the context paired with this home (miakapp context list), or pair it with '
+    + 'miakapp pair. Nothing was sent.',
+  );
+}
+
+/**
+ * Picks the Home Key for one invocation. Precedence, highest first:
+ *
+ * 1. `--context <name>`, then `MIAKAPP_CONTEXT`: an explicit stored context;
+ * 2. `MIAKAPP_HOME_KEY`: a raw key, for CI and compatibility;
+ * 3. the stored context paired with the project's home and issuer, the
+ *    current context breaking a tie between several keys for that one home.
+ *
+ * A stored context is used only for the home it was paired with, and a raw
+ * key known to belong to another stored home is refused the same way.
+ */
+async function resolveCredential(
+  host: CliHost,
+  invocation: Invocation,
+  project: Project,
+): Promise<Credential> {
+  const directory = storeDirectory(host);
+  const explicit = explicitContext(host, invocation);
+  if (explicit !== undefined) {
+    const { context, homeKey } = await readCredential(directory, explicit);
+    requireSameHome(context, project, `Context ${context.name}`);
+    return { homeKey, source: 'context', context };
+  }
+
+  const environmentKey = nonEmpty(host.env(HOME_KEY_VARIABLE));
+  if (environmentKey !== undefined) {
+    const keyId = homeKeyId(environmentKey);
+    let known: Iterable<StoredContext> = [];
+    try {
+      known = (await readContexts(directory)).contexts.values();
+    } catch {
+      // The guard is best effort here: a CI runner has no store, and a broken
+      // one must not block a key the caller supplied explicitly.
+    }
+    for (const context of known) {
+      if (context.keyId === keyId) {
+        requireSameHome(context, project, `${HOME_KEY_VARIABLE} (paired as context ${context.name})`);
+      }
+    }
+    return { homeKey: environmentKey, source: 'environment', context: undefined };
+  }
+
+  const state = await readContexts(directory);
+  const matching = [...state.contexts.values()]
+    .filter((context) => context.homeId === project.homeId && context.issuer === project.issuer)
+    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+  const chosen = matching.find((context) => context.name === state.current) ?? matching[0];
+  if (chosen === undefined) {
+    const others = [...state.contexts.keys()];
     throw authorizationError(
-      `${HOME_KEY_VARIABLE} is not set`,
-      `Export a Home Key holding components:publish as ${HOME_KEY_VARIABLE}. `
-      + 'It is never accepted as a command-line argument.',
+      `No credential for home ${project.homeId} at ${project.issuer}`,
+      'Pair this home: ask the owner to open '
+      + `${PAIRING_PAGE}, choose it, confirm access and send you the code, then run `
+      + `miakapp pair. ${HOME_KEY_VARIABLE} also works, for CI.`
+      + (others.length === 0 ? '' : ` Stored contexts are for other homes: ${others.join(', ')}.`),
     );
   }
-  return value;
+  const { homeKey } = await readCredential(directory, chosen.name);
+  return { homeKey, source: 'context', context: chosen };
+}
+
+function credentialJson(credential: Credential): Record<string, unknown> {
+  return {
+    credential_source: credential.source,
+    context: credential.context?.name ?? null,
+  };
+}
+
+function credentialFields(credential: Credential): readonly Field[] {
+  return [[
+    'credential',
+    credential.context === undefined ? HOME_KEY_VARIABLE : `context ${credential.context.name}`,
+  ]];
 }
 
 async function nodeFileSystem(): Promise<FileSystem> {
@@ -345,22 +531,38 @@ async function loadArtifact(host: CliHost, project: Project): Promise<Artifact>
   return prepareArtifact(await filesystem.read(project.artifactPath));
 }
 
-async function publicationTarget(host: CliHost, project: Project): Promise<PublicationTarget> {
-  const key = homeKey(host);
+async function publicationTarget(
+  host: CliHost,
+  invocation: Invocation,
+  project: Project,
+): Promise<{ target: PublicationTarget; credential: Credential }> {
+  const credential = await resolveCredential(host, invocation, project);
   const options = host.fetch === undefined ? {} : { fetch: host.fetch };
   const discovery = await fetchDiscovery({ issuer: project.issuer, ...options });
-  const token = await exchangePublisherToken(discovery, key, options);
-  return { issuer: discovery.issuer, homeId: project.homeId, token: token.accessToken, ...options };
+  const token = await exchangePublisherToken(discovery, credential.homeKey, options);
+  return {
+    target: { issuer: discovery.issuer, homeId: project.homeId, token: token.accessToken, ...options },
+    credential,
+  };
 }
 
 function requirementFields(requires: Requirements): readonly Field[] {
   return REQUIREMENT_KINDS.map((kind): Field => [`requires.${kind}`, requires[kind]]);
 }
 
-function pointerResult(summary: string, pointer: ComponentPointer): CommandResult {
+function pointerResult(
+  summary: string,
+  pointer: ComponentPointer,
+  credential: Credential,
+  expectedGeneration: number | undefined,
+): CommandResult {
   return {
     summary,
     fields: [
+      ...credentialFields(credential),
+      ...(expectedGeneration === undefined
+        ? []
+        : [['expected_generation', expectedGeneration] as Field]),
       ['home', pointer.homeId],
       ['generation', pointer.generation],
       ['release', pointer.release],
@@ -378,6 +580,8 @@ function pointerResult(summary: string, pointer: ComponentPointer): CommandResul
       sha256: pointer.sha256,
       size: pointer.size,
       requires: pointer.requires,
+      ...(expectedGeneration === undefined ? {} : { expected_generation: expectedGeneration }),
+      ...credentialJson(credential),
     },
   };
 }
@@ -418,9 +622,10 @@ async function runInit(host: CliHost, invocation: Invocation): Promise<CommandRe
   if (!isRelease(release)) {
     throw usageError('--release must be 1..64 UTF-8 bytes without control characters');
   }
+  const target = await initTarget(host, invocation);
   const source = projectTemplate({
-    home: requiredOption(invocation, 'home'),
-    controlPlane: requiredOption(invocation, 'control-plane'),
+    home: target.home,
+    controlPlane: target.controlPlane,
     artifact: invocation.options.get('artifact') ?? 'dist/component.js',
     release,
   });
@@ -429,8 +634,64 @@ async function runInit(host: CliHost, invocation: Invocation): Promise<CommandRe
   await filesystem.write(path, new TextEncoder().encode(source));
   return {
     summary: `Wrote ${path}`,
-    fields: [['project', path]],
-    json: { project: path, schema: PROJECT_SCHEMA },
+    fields: [
+      ['project', path],
+      ['home', target.home],
+      ['control_plane', target.controlPlane],
+      ...(target.context === undefined ? [] : [['context', target.context] as Field]),
+    ],
+    json: {
+      project: path,
+      schema: PROJECT_SCHEMA,
+      home_id: target.home,
+      control_plane: target.controlPlane,
+      context: target.context ?? null,
+    },
+  };
+}
+
+/**
+ * `--home` and `--control-plane` default to the selected context — the one
+ * named by `--context` or `MIAKAPP_CONTEXT`, else the current one — so the step
+ * after `miakapp pair` needs no identifier typed by hand. An explicit value
+ * that contradicts an explicitly selected context is refused rather than
+ * silently preferred.
+ */
+async function initTarget(host: CliHost, invocation: Invocation): Promise<{
+  home: string;
+  controlPlane: string;
+  context: string | undefined;
+}> {
+  const home = invocation.options.get('home');
+  const controlPlane = invocation.options.get('control-plane');
+  const explicit = explicitContext(host, invocation);
+  if (explicit === undefined && home !== undefined && controlPlane !== undefined) {
+    return { home, controlPlane, context: undefined };
+  }
+  const state = await readContexts(storeDirectory(host));
+  const name = explicit ?? state.current ?? undefined;
+  const context = name === undefined ? undefined : state.contexts.get(name);
+  if (explicit !== undefined && context === undefined) {
+    throw usageError(`No context named ${explicit}`, 'Run miakapp context list.');
+  }
+  if (context === undefined) {
+    throw usageError(
+      `--${home === undefined ? 'home' : 'control-plane'} is required when no context is selected`,
+      'Pair the home first with miakapp pair, or pass both --home and --control-plane.',
+    );
+  }
+  if (explicit !== undefined
+    && ((home !== undefined && home !== context.homeId)
+      || (controlPlane !== undefined && controlPlane !== context.issuer))) {
+    throw usageError(
+      `Context ${context.name} is for home ${context.homeId} at ${context.issuer}, which `
+      + 'contradicts --home or --control-plane',
+    );
+  }
+  return {
+    home: home ?? context.homeId,
+    controlPlane: controlPlane ?? context.issuer,
+    context: context.name,
   };
 }
 
@@ -626,14 +887,15 @@ async function runCheck(host: CliHost, invocation: Invocation): Promise<CommandR
 }
 
 async function runPublish(host: CliHost, invocation: Invocation): Promise<CommandResult> {
-  const { expectedGeneration, generation } = generationPair(invocation);
+  const plan = generationPlan(invocation);
   const project = await loadProject(host, invocation);
   const release = invocation.options.get('release') ?? project.release;
   if (!isRelease(release)) {
     throw usageError('--release must be 1..64 UTF-8 bytes without control characters');
   }
   const artifact = await loadArtifact(host, project);
-  const target = await publicationTarget(host, project);
+  const { target, credential } = await publicationTarget(host, invocation, project);
+  const { expectedGeneration, generation } = await resolveGenerations(target, plan);
   const { pointer } = await publish(target, artifact, {
     release,
     requires: project.requires,
@@ -643,14 +905,16 @@ async function runPublish(host: CliHost, invocation: Invocation): Promise<Comman
   return pointerResult(
     `Published ${release} as generation ${pointer.generation}`,
     pointer,
+    credential,
+    expectedGeneration,
   );
 }
 
 async function runActivate(host: CliHost, invocation: Invocation): Promise<CommandResult> {
   const sha256 = digestOption(invocation, 'sha256');
-  const { expectedGeneration, generation } = generationPair(invocation);
+  const plan = generationPlan(invocation);
   const project = await loadProject(host, invocation);
-  const target = await publicationTarget(host, project);
+  const { target, credential } = await publicationTarget(host, invocation, project);
   // Activation is checked against a readable finalized record first, so a typo
   // in a digest fails as an artifact error instead of spending a CAS attempt.
   const existing = await readRelease(target, sha256);
@@ -660,10 +924,13 @@ async function runActivate(host: CliHost, invocation: Invocation): Promise<Comma
       'Activate only a digest this home has already published.',
     );
   }
+  const { expectedGeneration, generation } = await resolveGenerations(target, plan);
   const pointer = await activateRelease(target, { sha256, expectedGeneration, generation });
   return pointerResult(
     `Activated ${existing.release} as generation ${pointer.generation}`,
     pointer,
+    credential,
+    expectedGeneration,
   );
 }
 
@@ -674,7 +941,7 @@ async function runRelease(host: CliHost, invocation: Invocation): Promise<Comman
     throw usageError('The release digest must be 43 base64url characters');
   }
   const project = await loadProject(host, invocation);
-  const target = await publicationTarget(host, project);
+  const { target } = await publicationTarget(host, invocation, project);
   const record = await readRelease(target, sha256);
   if (record === undefined) {
     throw artifactError(`No finalized release for ${sha256}`);
@@ -703,7 +970,7 @@ async function runUpload(host: CliHost, invocation: Invocation): Promise<Command
   const uploadId = invocation.positional[0];
   if (uploadId === undefined) throw usageError('upload requires one uploadId argument');
   const project = await loadProject(host, invocation);
-  const target = await publicationTarget(host, project);
+  const { target } = await publicationTarget(host, invocation, project);
   const state = await readUpload(target, uploadId);
   return {
     summary: `Upload ${state.uploadId} is ${state.status}`,
@@ -728,6 +995,297 @@ async function runUpload(host: CliHost, invocation: Invocation): Promise<Command
   };
 }
 
+async function runStatus(host: CliHost, invocation: Invocation): Promise<CommandResult> {
+  const project = await loadProject(host, invocation);
+  const { target, credential } = await publicationTarget(host, invocation, project);
+  const { generation, pointer } = await readPointer(target);
+  if (pointer === null) {
+    return {
+      summary: `${project.homeId} has never activated a component (generation 0)`,
+      fields: [['home', project.homeId], ['generation', 0], ...credentialFields(credential)],
+      json: { home_id: project.homeId, generation, active: false, ...credentialJson(credential) },
+    };
+  }
+  const result = pointerResult(
+    `${project.homeId} runs ${pointer.release} at generation ${generation}`,
+    pointer,
+    credential,
+    undefined,
+  );
+  return { ...result, json: { ...result.json, active: true } };
+}
+
+function defaultLabel(host: CliHost): string {
+  const machine = (host.hostname?.() ?? hostname()).replace(/[^A-Za-z0-9._-]/g, '-');
+  return `miakapp-cli@${machine === '' ? 'unknown' : machine}`.slice(0, 64);
+}
+
+/** A free context name: the base itself, else base-2, base-3, ... */
+function freeContextName(taken: ReadonlyMap<string, unknown>, base: string): string {
+  if (!taken.has(base)) return base;
+  for (let suffix = 2; ; suffix += 1) {
+    const candidate = `${base.slice(0, 62 - String(suffix).length)}-${suffix}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+
+async function pairingCode(host: CliHost, invocation: Invocation): Promise<string> {
+  const explicit = invocation.options.get('code');
+  if (explicit !== undefined) return explicit;
+  if (host.readSecret === undefined) {
+    throw usageError(
+      'pair needs the one-time code',
+      'Pipe it on stdin (printf %s "$CODE" | miakapp pair) or run miakapp pair in a terminal to '
+      + 'be prompted without echo.',
+    );
+  }
+  return await host.readSecret('Pairing code (hidden): ');
+}
+
+/**
+ * Trades a one-time pairing code for a fresh Home Key and stores it as a new
+ * context. Every existing context is kept. The new context becomes current.
+ *
+ * Everything that can fail without spending the code — the issuer, the label,
+ * the name, the readability of the store and the issuer's discovery document —
+ * is checked before the code is sent, because a code works exactly once.
+ */
+async function runPair(host: CliHost, invocation: Invocation): Promise<CommandResult> {
+  const issuer = pairingIssuer(invocation.options.get('issuer') ?? DEFAULT_ISSUER);
+  const label = validateLabel(invocation.options.get('label') ?? defaultLabel(host));
+  const requestedName = invocation.options.get('name');
+  if (requestedName !== undefined && !isContextName(requestedName)) contextNameError(requestedName);
+  const directory = storeDirectory(host);
+  const before = await readContexts(directory);
+  if (requestedName !== undefined && before.contexts.has(requestedName)) {
+    throw usageError(
+      `A context named ${requestedName} already exists`,
+      `Choose another --name, or remove it first with miakapp context remove ${requestedName}. `
+      + 'The code was not used.',
+    );
+  }
+
+  const code = normalizeCode(await pairingCode(host, invocation));
+  const options = host.fetch === undefined ? {} : { fetch: host.fetch };
+  let discovery: Awaited<ReturnType<typeof fetchDiscovery>>;
+  try {
+    discovery = await fetchDiscovery({ issuer, ...options });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'unknown failure';
+    throw contractError(
+      `${issuer} did not prove it is a Miakapp control plane: ${reason}`,
+      'The code was not sent and is still valid until it expires. Check --issuer and the '
+      + 'network, then run pair again with the same code.',
+    );
+  }
+  const paired = await redeemPairingCode({ issuer, code, label, ...options });
+
+  const createdAt = new Date().toISOString();
+  let stored: { name: string; previous: readonly StoredContext[] };
+  try {
+    stored = await mutateContexts(directory, (state) => {
+      const previous = [...state.contexts.values()]
+        .filter((context) => context.homeId === paired.homeId && context.issuer === paired.issuer);
+      const name = freeContextName(state.contexts, requestedName ?? paired.homeId);
+      state.contexts.set(name, {
+        name,
+        issuer: paired.issuer,
+        homeId: paired.homeId,
+        keyId: paired.keyId,
+        label,
+        createdAt,
+      });
+      state.keys.set(name, paired.homeKey);
+      state.current = name;
+      return { name, previous };
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'unknown failure';
+    throw authorizationError(
+      `Home Key ${paired.keyId} for ${paired.homeId} was issued but could not be stored in `
+      + `${directory}: ${reason}`,
+      `Ask the owner to revoke the key labelled ${JSON.stringify(label)}, fix the directory, then pair again.`,
+    );
+  }
+
+  // The key is stored; proving it can obtain a publication token tells the
+  // agent now, rather than at its first publish, whether the grant is usable.
+  let publishAccess: 'verified' | 'refused' = 'verified';
+  let publishAccessDetail: string | undefined;
+  try {
+    await exchangePublisherToken(discovery, paired.homeKey, options);
+  } catch (error) {
+    publishAccess = 'refused';
+    publishAccessDetail = error instanceof Error ? error.message : 'unknown failure';
+  }
+
+  const previous = stored.previous.map((context) => context.name);
+  return {
+    summary: `Paired ${paired.homeId} as context ${stored.name}`
+      + (publishAccess === 'verified' ? '' : ' (the key could not obtain a publication token)'),
+    fields: [
+      ['context', stored.name],
+      ['home', paired.homeId],
+      ['issuer', paired.issuer],
+      ['key_id', paired.keyId],
+      ['label', label],
+      ['current', 'yes'],
+      ['publish_access', publishAccessDetail === undefined ? publishAccess : `${publishAccess}: ${publishAccessDetail}`],
+      ['config', directory],
+      ...(previous.length === 0 ? [] : [['earlier_contexts_for_this_home', previous] as Field]),
+    ],
+    json: {
+      context: stored.name,
+      home_id: paired.homeId,
+      issuer: paired.issuer,
+      key_id: paired.keyId,
+      label,
+      current: true,
+      publish_access: publishAccess,
+      ...(publishAccessDetail === undefined ? {} : { publish_access_detail: publishAccessDetail }),
+      config_directory: directory,
+      earlier_contexts_for_this_home: previous,
+    },
+  };
+}
+
+function contextJson(
+  context: StoredContext,
+  current: string | null,
+  credential: string | undefined,
+): Record<string, unknown> {
+  return {
+    name: context.name,
+    home_id: context.homeId,
+    issuer: context.issuer,
+    key_id: context.keyId,
+    label: context.label,
+    created_at: context.createdAt,
+    current: context.name === current,
+    credential: credential ?? 'missing',
+  };
+}
+
+/**
+ * `context list | show [name] | use <name> | remove <name>`.
+ *
+ * Nothing here prints a Home Key: `credential` reports only whether the stored
+ * key is present and is the key the context was paired with.
+ */
+async function runContext(host: CliHost, invocation: Invocation): Promise<CommandResult> {
+  const [action, name, extra] = invocation.positional;
+  const directory = storeDirectory(host);
+  if (extra !== undefined) throw usageError('context takes at most one name');
+  const named = (verb: string): string => {
+    if (name === undefined) throw usageError(`context ${verb} requires a context name`);
+    if (!isContextName(name)) contextNameError(name);
+    return name;
+  };
+
+  switch (action) {
+    case 'list': {
+      if (name !== undefined) throw usageError('context list takes no name');
+      const state = await readContexts(directory);
+      const contexts = [...state.contexts.values()];
+      return {
+        summary: contexts.length === 0
+          ? `No context in ${directory}. Run miakapp pair to add one.`
+          : `${counted(contexts.length, 'context', 'contexts')} in ${directory}`,
+        fields: contexts.map((context): Field => [
+          `${context.name === state.current ? '* ' : ''}${context.name}`,
+          `home ${context.homeId} at ${context.issuer}, key ${context.keyId} `
+          + `(${state.credentials.get(context.name) ?? 'missing'})`,
+        ]),
+        json: {
+          config_directory: directory,
+          current_context: state.current,
+          contexts: contexts.map((context) => contextJson(
+            context,
+            state.current,
+            state.credentials.get(context.name),
+          )),
+        },
+      };
+    }
+    case 'show': {
+      const state = await readContexts(directory);
+      const selected = name ?? state.current ?? undefined;
+      if (selected === undefined) {
+        throw usageError('No current context', 'Name one: miakapp context show <name>, or pair with miakapp pair.');
+      }
+      if (!isContextName(selected)) contextNameError(selected);
+      const context = state.contexts.get(selected);
+      if (context === undefined) {
+        throw usageError(`No context named ${selected}`, 'Run miakapp context list.');
+      }
+      const json = contextJson(context, state.current, state.credentials.get(context.name));
+      return {
+        summary: `Context ${context.name}${json['current'] === true ? ' (current)' : ''}`,
+        fields: [
+          ['home', context.homeId],
+          ['issuer', context.issuer],
+          ['key_id', context.keyId],
+          ['label', context.label],
+          ['created_at', context.createdAt],
+          ['credential', `${String(json['credential'])} (never printed)`],
+          ['config', directory],
+        ],
+        json: { ...json, config_directory: directory },
+      };
+    }
+    case 'use': {
+      const selected = named('use');
+      const context = await mutateContexts(directory, (state) => {
+        const found = state.contexts.get(selected);
+        if (found === undefined) {
+          throw usageError(`No context named ${selected}`, 'Run miakapp context list.');
+        }
+        state.current = selected;
+        return found;
+      });
+      return {
+        summary: `Current context is now ${selected}`,
+        fields: [['home', context.homeId], ['issuer', context.issuer]],
+        json: { current_context: selected, home_id: context.homeId, issuer: context.issuer },
+      };
+    }
+    case 'remove': {
+      const selected = named('remove');
+      const result = await mutateContexts(directory, (state) => {
+        const found = state.contexts.get(selected);
+        if (found === undefined) {
+          throw usageError(`No context named ${selected}`, 'Run miakapp context list.');
+        }
+        state.contexts.delete(selected);
+        state.keys.delete(selected);
+        const wasCurrent = state.current === selected;
+        if (wasCurrent) state.current = null;
+        return { context: found, wasCurrent };
+      });
+      return {
+        summary: `Removed context ${selected} and its stored key`,
+        fields: [
+          ['home', result.context.homeId],
+          ['key_id', result.context.keyId],
+          ['still_valid_on_server', 'yes: ask the owner to revoke it if it is no longer needed'],
+        ],
+        json: {
+          removed: selected,
+          home_id: result.context.homeId,
+          key_id: result.context.keyId,
+          was_current: result.wasCurrent,
+          revoked: false,
+        },
+      };
+    }
+    default:
+      throw usageError(
+        action === undefined ? 'context requires an action' : `Unknown context action: ${action}`,
+        'Use context list, context show [name], context use <name> or context remove <name>.',
+      );
+  }
+}
+
 /**
  * Runs one parsed invocation.
  *
@@ -738,6 +1296,12 @@ export async function dispatch(host: CliHost, invocation: Invocation): Promise<C
   switch (invocation.command) {
     case 'docs':
       return await runDocs(host, invocation);
+    case 'pair':
+      return await runPair(host, invocation);
+    case 'context':
+      return await runContext(host, invocation);
+    case 'status':
+      return await runStatus(host, invocation);
     case 'init':
       return await runInit(host, invocation);
     case 'agent-pack':
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index ae9d8b3..9c4ee86 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -60,19 +60,25 @@ interface ToolArgument {
 interface ToolPositional {
   readonly name: string;
   readonly description: string;
+  /** Defaults to true. */
+  readonly required?: boolean;
 }
 
 interface ToolDefinition {
   readonly name: string;
   readonly title: string;
   readonly command: string;
+  /** Fixed first positional, for commands with actions such as `context list`. */
+  readonly action?: string;
   readonly description: string;
   readonly args: readonly ToolArgument[];
   readonly positional?: ToolPositional;
   /** Reads only; opens no socket and writes no file. */
   readonly readOnly: boolean;
-  /** Moves the home pointer, so it demands `confirm: true`. */
+  /** Moves the home pointer or deletes a credential, so it demands `confirm: true`. */
   readonly guarded: boolean;
+  /** Why `confirm: true` is demanded, repeated in the refusal. */
+  readonly guardReason?: string;
 }
 
 const PROJECT_ARGUMENT: ToolArgument = {
@@ -85,13 +91,27 @@ const PROJECT_ARGUMENT: ToolArgument = {
 const EXPECTED_GENERATION: ToolArgument = {
   name: 'expected_generation',
   type: 'integer',
-  required: true,
+  required: false,
   description:
-    'Generation the home pointer is expected to hold right now. The activation is a '
+    'Generation the home pointer is expected to hold right now. Omit it to use the live '
+    + 'generation read just before activating (miakapp_status shows it). The activation is a '
     + 'compare-and-set: if the real generation differs the call fails with kind "conflict" and '
     + 'changes nothing. Re-read the state, do not retry blindly.',
 };
 
+const CONTEXT_ARGUMENT: ToolArgument = {
+  name: 'context',
+  type: 'string',
+  required: false,
+  description:
+    'Stored context to use (see miakapp_context_list). By default the context paired with the '
+    + "project's home is used. A context for another home is refused.",
+};
+
+const POINTER_GUARD =
+  'This tool changes what every device in the home runs, and will not act without an explicit '
+  + 'confirmation from the caller.';
+
 const GENERATION: ToolArgument = {
   name: 'generation',
   type: 'integer',
@@ -108,6 +128,19 @@ const CONFIRM: ToolArgument = {
     + 'the home runs. Set it only when the owner asked for this exact publication.',
 };
 
+const CONFIRM_REMOVAL: ToolArgument = {
+  name: 'confirm',
+  type: 'boolean',
+  required: true,
+  description:
+    'Must be true. Deletes the stored Home Key; the home stays reachable only by pairing again.',
+};
+
+const CONTEXT_NAME: ToolPositional = {
+  name: 'name',
+  description: 'Context name, as listed by miakapp_context_list.',
+};
+
 /**
  * The exposed surface. Every CLI command is here except `help` and `version`,
  * which an MCP client gets from `initialize` and `tools/list` instead.
@@ -129,6 +162,110 @@ export const TOOLS: readonly ToolDefinition[] = [
     readOnly: true,
     guarded: false,
   },
+  {
+    name: 'miakapp_pair',
+    title: 'Pair a home with a one-time code',
+    command: 'pair',
+    description:
+      'Redeem the one-time pairing code the owner created at https://miakapp.com/pair for a new, '
+      + 'separately revocable Home Key, and store it as a new context in ~/.miakapp (private '
+      + 'files, other contexts kept, the new one made current). The owner chooses the home and '
+      + 'confirms access in their own browser; never ask them for a password, a Google login or '
+      + 'an existing key. A code works once for ten minutes: never retry it after a failure, ask '
+      + 'for a new one. The result never contains the key.',
+    args: [
+      {
+        name: 'code',
+        type: 'string',
+        required: true,
+        description: 'The one-time code exactly as the owner sent it. Never repeat it in a reply.',
+      },
+      {
+        name: 'issuer',
+        type: 'string',
+        required: false,
+        description: 'Control plane to redeem at. Defaults to https://control.miakapp.com.',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: 'Key label the owner sees in their key list. Defaults to miakapp-cli@<host>.',
+      },
+      {
+        name: 'name',
+        type: 'string',
+        required: false,
+        description: 'Context name. Defaults to the paired home ID.',
+      },
+    ],
+    readOnly: false,
+    guarded: false,
+  },
+  {
+    name: 'miakapp_context_list',
+    title: 'List stored contexts',
+    command: 'context',
+    action: 'list',
+    description:
+      'List the homes this machine holds a key for: context name, home ID, issuer, key ID and '
+      + 'whether the key is stored. Never returns a key. Offline.',
+    args: [],
+    readOnly: true,
+    guarded: false,
+  },
+  {
+    name: 'miakapp_context_show',
+    title: 'Show one stored context',
+    command: 'context',
+    action: 'show',
+    description: 'Show one context, the current one when no name is given. Never returns a key.',
+    args: [],
+    positional: { ...CONTEXT_NAME, required: false },
+    readOnly: true,
+    guarded: false,
+  },
+  {
+    name: 'miakapp_context_use',
+    title: 'Make a context current',
+    command: 'context',
+    action: 'use',
+    description:
+      'Make a stored context current. Publication still follows the home named in miakapp.yaml: '
+      + 'the current context only breaks a tie between several keys for that same home.',
+    args: [],
+    positional: CONTEXT_NAME,
+    readOnly: false,
+    guarded: false,
+  },
+  {
+    name: 'miakapp_context_remove',
+    title: 'Delete a stored context',
+    command: 'context',
+    action: 'remove',
+    description:
+      'Delete a context and its stored Home Key from this machine. The key stays valid on the '
+      + 'server until the owner revokes it.',
+    args: [CONFIRM_REMOVAL],
+    positional: CONTEXT_NAME,
+    readOnly: false,
+    guarded: true,
+    guardReason:
+      'This tool deletes a stored Home Key, and will not act without an explicit confirmation '
+      + 'from the caller.',
+  },
+  {
+    name: 'miakapp_status',
+    title: 'Read what the home runs now',
+    command: 'status',
+    description:
+      'Read the live component pointer of the home in miakapp.yaml: generation, release, digest '
+      + 'and requirements, or generation 0 for a home that never activated. Read-only. Run it '
+      + 'before publishing and after, to verify the publication is what is live.',
+    args: [PROJECT_ARGUMENT, CONTEXT_ARGUMENT],
+    readOnly: true,
+    guarded: false,
+  },
   {
     name: 'miakapp_discover',
     title: 'Inventory an existing Node-RED house',
@@ -175,20 +312,21 @@ export const TOOLS: readonly ToolDefinition[] = [
     command: 'init',
     description:
       'Write miakapp.yaml in the project directory. Refuses to overwrite an existing one, so it '
-      + 'is safe to call when unsure. Declares no requirements: grant them one at a time, as the '
-      + 'component earns them.',
+      + 'is safe to call when unsure. home and control_plane default to the selected or current '
+      + 'context, so after miakapp_pair no identifier needs typing. Declares no requirements: '
+      + 'grant them one at a time, as the component earns them.',
     args: [
       {
         name: 'home',
         type: 'string',
-        required: true,
-        description: 'Home ID the component is published to.',
+        required: false,
+        description: 'Home ID the component is published to. Defaults to the context home.',
       },
       {
         name: 'control_plane',
         type: 'string',
-        required: true,
-        description: 'Control-plane issuer, an https URL.',
+        required: false,
+        description: 'Control-plane issuer, an https URL. Defaults to the context issuer.',
       },
       {
         name: 'artifact',
@@ -203,6 +341,7 @@ export const TOOLS: readonly ToolDefinition[] = [
         description: 'Initial release name. Defaults to 0.1.0.',
       },
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
     ],
     readOnly: false,
     guarded: false,
@@ -227,7 +366,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       'Read the finalized release record for one digest: release name, ABI, size, requirements '
       + 'and finalization instant. This is the reconciliation read after a lost finalize '
       + 'response — call it before deciding that a publication did not happen.',
-    args: [PROJECT_ARGUMENT],
+    args: [PROJECT_ARGUMENT, CONTEXT_ARGUMENT],
     positional: {
       name: 'sha256',
       description: 'Artifact digest, 43 base64url characters.',
@@ -243,7 +382,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       'Read the status of one upload: awaiting_upload, delivered or finalized. This is the read '
       + 'that tells a lost PUT from an upload that never arrived. Call it after any '
       + 'unknown_outcome, before touching the control plane again.',
-    args: [PROJECT_ARGUMENT],
+    args: [PROJECT_ARGUMENT, CONTEXT_ARGUMENT],
     positional: {
       name: 'upload_id',
       description: 'Upload ID returned when the capability was issued, 22 characters.',
@@ -257,8 +396,9 @@ export const TOOLS: readonly ToolDefinition[] = [
     command: 'publish',
     description:
       'Upload the built artifact, finalize it and activate it as the new generation, in one run. '
-      + 'Changes what every device in the home runs. Requires MIAKAPP_HOME_KEY in the '
-      + 'environment. Run miakapp_check first; this tool does not build the component.',
+      + 'Changes what every device in the home runs. Uses the context paired with the home in '
+      + 'miakapp.yaml (or MIAKAPP_HOME_KEY in the environment, for CI). Run miakapp_check first; '
+      + 'this tool does not build the component. Afterwards, run miakapp_status to verify.',
     args: [
       EXPECTED_GENERATION,
       GENERATION,
@@ -269,6 +409,7 @@ export const TOOLS: readonly ToolDefinition[] = [
         description: 'Release name for this publication. Defaults to component.release.',
       },
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
       CONFIRM,
     ],
     readOnly: false,
@@ -291,6 +432,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       EXPECTED_GENERATION,
       GENERATION,
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
       CONFIRM,
     ],
     readOnly: false,
@@ -314,6 +456,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       EXPECTED_GENERATION,
       GENERATION,
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
       CONFIRM,
     ],
     readOnly: false,
@@ -345,7 +488,7 @@ export function inputSchema(tool: ToolDefinition): Record<string, unknown> {
       minLength: 1,
       description: tool.positional.description,
     };
-    required.push(tool.positional.name);
+    if (tool.positional.required !== false) required.push(tool.positional.name);
   }
   for (const argument of tool.args) {
     properties[argument.name] = schemaProperty(argument);
@@ -370,7 +513,8 @@ function descriptor(tool: ToolDefinition): Record<string, unknown> {
       readOnlyHint: tool.readOnly,
       destructiveHint: tool.guarded,
       idempotentHint: false,
-      openWorldHint: !tool.readOnly || tool.command === 'release' || tool.command === 'upload',
+      openWorldHint: tool.command !== 'context'
+        && (!tool.readOnly || ['release', 'upload', 'status'].includes(tool.command)),
     },
   };
 }
@@ -387,7 +531,7 @@ export function buildArgv(
   args: Record<string, unknown>,
 ): readonly string[] {
   const byName = new Map(tool.args.map((argument) => [argument.name, argument]));
-  const argv: string[] = [tool.command];
+  const argv: string[] = tool.action === undefined ? [tool.command] : [tool.command, tool.action];
   const positional = tool.positional;
 
   for (const key of Object.keys(args)) {
@@ -402,10 +546,12 @@ export function buildArgv(
 
   if (positional !== undefined) {
     const value = args[positional.name];
-    if (typeof value !== 'string' || value === '') {
-      throw usageError(`${positional.name} is required and must be a non-empty string`);
+    if (value !== undefined || positional.required !== false) {
+      if (typeof value !== 'string' || value === '') {
+        throw usageError(`${positional.name} is required and must be a non-empty string`);
+      }
+      argv.push(value);
     }
-    argv.push(value);
   }
 
   for (const argument of tool.args) {
@@ -414,11 +560,7 @@ export function buildArgv(
       // A guard is not an option: it is checked here and never reaches the argv,
       // so the command line keeps exactly the shape it had before MCP existed.
       if (value !== true) {
-        throw usageError(
-          `${argument.name} must be set to true`,
-          'This tool changes what every device in the home runs, and will not act without an '
-          + 'explicit confirmation from the caller.',
-        );
+        throw usageError(`${argument.name} must be set to true`, tool.guardReason ?? POINTER_GUARD);
       }
       continue;
     }
@@ -507,9 +649,13 @@ export async function callTool(
   );
 }
 
-/** The dispatch never prints; the protocol owns both streams of this process. */
+/**
+ * The dispatch never prints and never reads: the protocol owns stdin and stdout
+ * of this process, so a pairing code arrives as a tool argument instead.
+ */
 function silentHost(host: CliHost): CliHost {
-  return { ...host, write: () => {}, writeError: () => {} };
+  const { readSecret: _stdinBelongsToTheProtocol, ...rest } = host;
+  return { ...rest, write: () => {}, writeError: () => {} };
 }
 
 export interface Message {
@@ -533,14 +679,17 @@ function errorResponse(id: unknown, code: number, message: string): Record<strin
 }
 
 const INSTRUCTIONS =
-  'Publish and roll back one Miakapp home component. Start with miakapp_discover on a house '
+  'Publish and roll back one Miakapp home component. Read miakapp_docs first. To get access, '
+  + 'ask the owner to open https://miakapp.com/pair, choose the home, confirm, and send you the '
+  + 'one-time code; then call miakapp_pair. Start with miakapp_discover on a house '
   + 'that already exists, then miakapp_check before every publication. A publication is a '
   + 'compare-and-set on the home generation: when a call fails with kind "conflict" the state '
   + 'moved under you, so read it again rather than retrying. When a call fails with kind '
   + '"unknown_outcome" the effect is undetermined — call miakapp_upload or miakapp_release to '
   + 'find out what happened before acting. Every result is a closed JSON object with a stable '
-  + `"kind"; branch on that, never on the prose. Publishing needs ${HOME_KEY_VARIABLE} in this `
-  + 'server\'s environment; it is never an argument and never printed.';
+  + '"kind"; branch on that, never on the prose. Publishing uses the paired context for the home '
+  + `in miakapp.yaml, or ${HOME_KEY_VARIABLE} in this server's environment; a key is never an `
+  + 'argument and never printed.';
 
 /**
  * Handles one decoded message.
diff --git a/packages/cli/src/pairing.ts b/packages/cli/src/pairing.ts
new file mode 100644
index 0000000..8a104ad
--- /dev/null
+++ b/packages/cli/src/pairing.ts
@@ -0,0 +1,197 @@
+/**
+ * Redeems a one-time pairing code for a new Home Key.
+ *
+ * The person picks the home and confirms access in their own browser, on the
+ * pairing page of their own account; the agent never signs in anywhere. What
+ * reaches the agent is a short-lived, single-use code, and this module trades
+ * it for a fresh, separately revocable key — one key per agent or machine,
+ * never a copy of someone else's.
+ *
+ * Contract (shared with the control plane, fixed):
+ *
+ *     POST {issuer}/v1/pairing/redeem
+ *     {"code": "...", "label": "..."}
+ *     → 200 {"home_key", "home_id", "key_id", "issuer"}, Cache-Control: no-store
+ *
+ * The request goes only to the issuer chosen before the code was read, after
+ * that issuer's own discovery document confirmed it is a Miakapp control plane
+ * under exactly that name. Redirects are refused, so a code cannot be walked to
+ * another host, and the response must name the same issuer and a key whose ID
+ * is embedded in the key itself.
+ */
+import { CliError, authorizationError, contractError, unknownOutcomeError, usageError } from './errors.js';
+import {
+  cancelBody,
+  canonicalHttpsUrl,
+  readBoundedBody,
+  requestBody,
+  type FetchLike,
+} from './internal/http.js';
+import { boundedString, exactRecord, parseJson } from './internal/json.js';
+import { isHomeId } from './internal/names.js';
+
+export const PAIRING_PATH = '/v1/pairing/redeem';
+export const DEFAULT_ISSUER = 'https://control.miakapp.com';
+export const PAIRING_PAGE = 'https://miakapp.com/pair';
+
+const HOME_KEY = /^mhk1_([A-Za-z0-9_-]{22})_([A-Za-z0-9_-]{43})$/;
+const CODE = /^[\x21-\x7e]{4,128}$/;
+const CONTROL_CHARACTER = /\p{Cc}/u;
+const MAXIMUM_REDEEM_RESPONSE_BYTES = 16_384;
+
+export interface PairingResult {
+  readonly homeKey: string;
+  readonly homeId: string;
+  readonly keyId: string;
+  readonly issuer: string;
+}
+
+/** Validates the issuer a code may be sent to, before the code is read. */
+export function pairingIssuer(value: string): string {
+  let issuer: string;
+  try {
+    issuer = canonicalHttpsUrl(value, 'issuer');
+  } catch {
+    throw usageError(
+      `--issuer must be an exact https URL without a path suffix, query or fragment, received ${JSON.stringify(value)}`,
+      `Omit --issuer to use ${DEFAULT_ISSUER}.`,
+    );
+  }
+  if (issuer.endsWith('/')) throw usageError('--issuer must not have a trailing slash');
+  return issuer;
+}
+
+/** Trims the surrounding whitespace a paste or a pipe adds, and nothing else. */
+export function normalizeCode(value: string): string {
+  const code = value.trim();
+  if (code === '') {
+    throw usageError(
+      'No pairing code was provided',
+      `Ask the owner to open ${PAIRING_PAGE}, confirm access to the home and send you the code.`,
+    );
+  }
+  if (!CODE.test(code)) {
+    throw usageError(
+      'The pairing code must be 4..128 printable characters without spaces',
+      'Paste the code exactly as the pairing page shows it.',
+    );
+  }
+  return code;
+}
+
+export function validateLabel(value: string): string {
+  if (value.length === 0
+    || new TextEncoder().encode(value).byteLength > 64
+    || CONTROL_CHARACTER.test(value)) {
+    throw usageError('--label must be 1..64 UTF-8 bytes without control characters');
+  }
+  return value;
+}
+
+function orphanRemedy(label: string): string {
+  return `The code may have been consumed. Ask the owner for a new code at ${PAIRING_PAGE}, and to `
+    + `revoke any Home Key labelled ${JSON.stringify(label)} that they did not expect.`;
+}
+
+async function failureCode(response: Response): Promise<string | undefined> {
+  try {
+    const body = parseJson(await readBoundedBody(response, MAXIMUM_REDEEM_RESPONSE_BYTES));
+    const error = (body as { error?: { code?: unknown } } | null)?.error;
+    return typeof error?.code === 'string' && /^[a-z_]{1,64}$/.test(error.code) ? error.code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Sends the code once. Never retried: a lost response may hide a key that was
+ * already issued, and the second attempt would only burn the attempt budget on
+ * a code that is now spent.
+ */
+export async function redeemPairingCode(options: {
+  readonly issuer: string;
+  readonly code: string;
+  readonly label: string;
+  readonly fetch?: FetchLike;
+}): Promise<PairingResult> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  let response: Response;
+  try {
+    response = await fetcher(`${options.issuer}${PAIRING_PATH}`, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json; charset=utf-8',
+      },
+      body: requestBody({ code: options.code, label: options.label }),
+      credentials: 'omit',
+      redirect: 'error',
+      referrerPolicy: 'no-referrer',
+    });
+  } catch {
+    throw unknownOutcomeError('The pairing request did not return a response', orphanRemedy(options.label));
+  }
+
+  if (response.status !== 200 && response.status !== 201) {
+    const code = await failureCode(response);
+    const suffix = code === undefined ? '' : ` ${code}`;
+    if (response.status === 429) {
+      const retry = response.headers.get('retry-after');
+      throw authorizationError(
+        `The pairing service refused the attempt with HTTP 429${suffix}: too many attempts`,
+        `${retry === null ? 'Wait' : `Wait ${retry} seconds`} before trying again, and check the code `
+        + 'with the owner instead of guessing.',
+      );
+    }
+    if (response.status >= 500) {
+      throw unknownOutcomeError(
+        `The pairing service failed with HTTP ${response.status}${suffix}`,
+        orphanRemedy(options.label),
+      );
+    }
+    throw authorizationError(
+      `The pairing code was refused with HTTP ${response.status}${suffix}`,
+      'A code works once and for ten minutes. Ask the owner to create a new one at '
+      + `${PAIRING_PAGE} and send it to you.`,
+    );
+  }
+
+  const cacheControl = (response.headers.get('cache-control') ?? '')
+    .split(',')
+    .map((item) => item.trim().toLowerCase());
+  if (!cacheControl.includes('no-store')) {
+    cancelBody(response);
+    throw contractError(
+      'The pairing response is missing Cache-Control: no-store; the key it carries was discarded',
+      `Report the control plane. Ask the owner to revoke the Home Key labelled ${JSON.stringify(options.label)}.`,
+    );
+  }
+
+  let result: PairingResult;
+  try {
+    // The contract fixes these four fields. A `schema` tag is tolerated because
+    // every other control-plane document carries one; any other member is a
+    // contract change and is refused. Nothing but the four is ever stored.
+    const document = exactRecord(
+      parseJson(await readBoundedBody(response, MAXIMUM_REDEEM_RESPONSE_BYTES)),
+      ['home_key', 'home_id', 'key_id', 'issuer'],
+      ['schema'],
+    );
+    const homeKey = boundedString(document.home_key, 1, 256);
+    const keyId = boundedString(document.key_id, 22, 22);
+    const match = HOME_KEY.exec(homeKey);
+    if (match?.[1] !== keyId) throw contractError('home_key does not carry key_id');
+    if (!isHomeId(document.home_id)) throw contractError('home_id is not a Miakapp home ID');
+    if (document.issuer !== options.issuer) {
+      throw contractError(`The response names issuer ${String(document.issuer)}, not ${options.issuer}`);
+    }
+    result = Object.freeze({ homeKey, homeId: document.home_id, keyId, issuer: options.issuer });
+  } catch (error) {
+    const detail = error instanceof CliError ? `: ${error.message}` : '';
+    throw contractError(
+      `The pairing response does not match the redeem contract${detail}; nothing was stored`,
+      `Report the control plane. Ask the owner to revoke the Home Key labelled ${JSON.stringify(options.label)}.`,
+    );
+  }
+  return result;
+}
diff --git a/packages/cli/src/publication.ts b/packages/cli/src/publication.ts
index 7b50b45..c828471 100644
--- a/packages/cli/src/publication.ts
+++ b/packages/cli/src/publication.ts
@@ -473,6 +473,45 @@ export async function readRelease(
   return decodeRelease(await readJsonBody(response));
 }
 
+/**
+ * Reads what is live: the generation the pointer holds and the release it
+ * points at, or generation 0 and no pointer for a home that never activated.
+ *
+ * RFC 0004 §13.2 serves this under the same publisher authorization as the
+ * other reads. It takes no lock, so the activation that follows remains a
+ * compare-and-set and a concurrent publisher still fails with
+ * `generation_conflict` instead of being overwritten.
+ */
+export async function readPointer(
+  target: PublicationTarget,
+): Promise<{ readonly generation: number; readonly pointer: ComponentPointer | null }> {
+  const { fetcher, signal, base } = client(target);
+  const response = await fetcher(
+    `${base}/component-pointer`,
+    jsonRequestInit('GET', target.token, undefined, signal),
+  );
+  if (response.status !== 200) {
+    throw failure('Pointer read', response.status, await readFailure(response), false);
+  }
+  const document = exactRecord(await readJsonBody(response), ['schema', 'generation', 'pointer']);
+  if (document.schema !== 'miakapp.component-pointer-state/1') {
+    throw contractError('Pointer state has an unsupported schema');
+  }
+  const generation = document.generation;
+  if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation < 0) {
+    throw contractError('Pointer state generation is not a non-negative safe integer');
+  }
+  if (document.pointer === null) {
+    if (generation !== 0) throw contractError('Pointer state has a generation but no pointer');
+    return Object.freeze({ generation, pointer: null });
+  }
+  const pointer = decodePointer(document.pointer, target);
+  if (pointer.generation !== generation) {
+    throw contractError('Pointer state generation does not match its pointer');
+  }
+  return Object.freeze({ generation, pointer });
+}
+
 /**
  * Step 4: compare-and-set the home pointer to a strictly greater generation.
  *
diff --git a/packages/cli/src/terminal.ts b/packages/cli/src/terminal.ts
new file mode 100644
index 0000000..e8556c3
--- /dev/null
+++ b/packages/cli/src/terminal.ts
@@ -0,0 +1,85 @@
+/**
+ * Reads one secret line from stdin without ever echoing it.
+ *
+ * On a terminal the prompt goes to stderr and the terminal is put in raw mode,
+ * so the code is neither displayed nor kept in the scrollback. From a pipe —
+ * `printf %s "$CODE" | miakapp pair`, the form an agent uses — the first line
+ * is read and the rest ignored. Either way the value never reaches argv, so it
+ * is absent from shell history and from the process list.
+ */
+import { usageError } from './errors.js';
+
+const MAXIMUM_SECRET_BYTES = 4_096;
+
+export interface SecretInput extends AsyncIterable<Uint8Array | string> {
+  readonly isTTY?: boolean;
+  setRawMode?(mode: boolean): unknown;
+  on?(event: 'data', listener: (chunk: Uint8Array | string) => void): unknown;
+  off?(event: 'data', listener: (chunk: Uint8Array | string) => void): unknown;
+  resume?(): unknown;
+  pause?(): unknown;
+}
+
+function text(chunk: Uint8Array | string): string {
+  return typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+}
+
+async function readPipe(input: SecretInput): Promise<string> {
+  let buffer = '';
+  for await (const chunk of input) {
+    buffer += text(chunk);
+    const newline = buffer.search(/\r?\n/);
+    if (newline !== -1) return buffer.slice(0, newline);
+    if (buffer.length > MAXIMUM_SECRET_BYTES) throw usageError('The secret on stdin is too long');
+  }
+  return buffer;
+}
+
+function readTerminal(input: SecretInput, writeError: (text: string) => void): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const finish = (outcome: () => void): void => {
+      input.off?.('data', onData);
+      input.setRawMode?.(false);
+      input.pause?.();
+      writeError('\n');
+      outcome();
+    };
+    const onData = (chunk: Uint8Array | string): void => {
+      for (const character of text(chunk)) {
+        if (character === '\r' || character === '\n' || character === '\u0004') {
+          finish(() => resolve(value));
+          return;
+        }
+        if (character === '\u0003') {
+          finish(() => reject(usageError('Cancelled')));
+          return;
+        }
+        if (character === '\u007f' || character === '\b') {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += character;
+        if (value.length > MAXIMUM_SECRET_BYTES) {
+          finish(() => reject(usageError('The secret is too long')));
+          return;
+        }
+      }
+    };
+    input.setRawMode?.(true);
+    input.on?.('data', onData);
+    input.resume?.();
+  });
+}
+
+export async function readSecret(
+  input: SecretInput,
+  prompt: string,
+  writeError: (text: string) => void,
+): Promise<string> {
+  if (input.isTTY === true && input.setRawMode !== undefined && input.on !== undefined) {
+    writeError(prompt);
+    return await readTerminal(input, writeError);
+  }
+  return await readPipe(input);
+}
diff --git a/packages/cli/test/contexts.test.ts b/packages/cli/test/contexts.test.ts
new file mode 100644
index 0000000..529b93c
--- /dev/null
+++ b/packages/cli/test/contexts.test.ts
@@ -0,0 +1,646 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chmod, lstat, mkdtemp, readFile, readdir, rm, symlink, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CONFIG_FILE,
+  CREDENTIALS_FILE,
+  mutateContexts,
+  readContexts,
+  readCredential,
+} from '../src/contexts.js';
+import { EXIT_CODE } from '../src/errors.js';
+import { CONTEXT_VARIABLE, HOME_KEY_VARIABLE, run } from '../src/main.js';
+import { callTool } from '../src/mcp.js';
+import { ISSUER, fakeControlPlane, homeKey, type FakeControlPlane } from './support/control-plane.js';
+import { MemoryFiles, PROJECT_ROOT, standardProject, testHost } from './support/host.js';
+
+const HOME_ID = 'test-home';
+const OTHER_HOME = 'other-home';
+const CODE = 'K7QX-93FP-LM2D';
+
+let home: string;
+let store: string;
+
+beforeEach(async () => {
+  home = await mkdtemp(join(tmpdir(), 'miakapp-contexts-'));
+  store = join(home, '.miakapp');
+});
+
+afterEach(async () => {
+  await rm(home, { recursive: true, force: true });
+});
+
+function plane(homeId = HOME_ID, options: Partial<Parameters<typeof fakeControlPlane>[0]> = {}): FakeControlPlane {
+  const created = fakeControlPlane({ homeId, ...options });
+  created.pairingCodes.set(CODE, homeId);
+  return created;
+}
+
+function secret(value: string): { readSecret: (prompt: string) => Promise<string>; prompts: string[] } {
+  const prompts: string[] = [];
+  return {
+    prompts,
+    readSecret: async (prompt) => {
+      prompts.push(prompt);
+      return value;
+    },
+  };
+}
+
+async function pair(
+  control: FakeControlPlane,
+  extra: readonly string[] = [],
+  code = `${CODE}\n`,
+): Promise<{ code: number; host: ReturnType<typeof testHost> }> {
+  const host = testHost({ fetch: control.fetch, home, ...secret(code) });
+  const exit = await run(['pair', '--issuer', ISSUER, '--json', ...extra], host);
+  return { code: exit, host };
+}
+
+function everythingPrinted(host: ReturnType<typeof testHost>): string {
+  return host.stdout() + host.stderr();
+}
+
+async function storedKey(name: string): Promise<string> {
+  return (await readCredential(store, name)).homeKey;
+}
+
+describe('miakapp pair', () => {
+  test('redeems the code once and stores a private context without printing secrets', async () => {
+    const control = plane();
+    const { code, host } = await pair(control);
+
+    expect(code).toBe(EXIT_CODE.success);
+    expect(control.pairingRequests).toEqual([{ code: CODE, label: 'miakapp-cli@test-machine' }]);
+    expect(control.pairingCodes.size).toBe(0);
+
+    const report = host.json();
+    expect(report).toMatchObject({
+      ok: true,
+      command: 'pair',
+      context: HOME_ID,
+      home_id: HOME_ID,
+      issuer: ISSUER,
+      current: true,
+      publish_access: 'verified',
+      earlier_contexts_for_this_home: [],
+    });
+    const key = await storedKey(HOME_ID);
+    expect(report['key_id']).toBe(key.slice(5, 27));
+    expect(everythingPrinted(host)).not.toContain(key);
+    expect(everythingPrinted(host)).not.toContain(CODE);
+    // The fresh key was proven usable for publication before pair returned.
+    expect(control.exchangedKeys).toEqual([key]);
+
+    if (process.platform !== 'win32') {
+      expect((await lstat(store)).mode & 0o777).toBe(0o700);
+      expect((await lstat(join(store, CREDENTIALS_FILE))).mode & 0o777).toBe(0o600);
+      expect((await lstat(join(store, CONFIG_FILE))).mode & 0o777).toBe(0o600);
+    }
+    // The configuration is the half that is safe to show: it holds no key.
+    expect(await readFile(join(store, CONFIG_FILE), 'utf8')).not.toContain('mhk1_');
+    expect((await readdir(store)).sort()).toEqual([CONFIG_FILE, CREDENTIALS_FILE]);
+  });
+
+  test('a second home is added beside the first, which keeps its key', async () => {
+    const first = plane(HOME_ID);
+    expect((await pair(first)).code).toBe(EXIT_CODE.success);
+    const firstKey = await storedKey(HOME_ID);
+
+    const second = plane(OTHER_HOME);
+    expect((await pair(second)).code).toBe(EXIT_CODE.success);
+
+    const state = await readContexts(store);
+    expect([...state.contexts.keys()].sort()).toEqual([OTHER_HOME, HOME_ID]);
+    expect(state.current).toBe(OTHER_HOME);
+    expect(await storedKey(HOME_ID)).toBe(firstKey);
+    expect(await storedKey(OTHER_HOME)).not.toBe(firstKey);
+  });
+
+  test('pairing the same home again keeps the earlier context and reports it', async () => {
+    const control = plane();
+    expect((await pair(control)).code).toBe(EXIT_CODE.success);
+    control.pairingCodes.set('SECOND-CODE', HOME_ID);
+    const { code, host } = await pair(control, [], 'SECOND-CODE');
+
+    expect(code).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({
+      context: `${HOME_ID}-2`,
+      earlier_contexts_for_this_home: [HOME_ID],
+    });
+    expect((await readContexts(store)).contexts.size).toBe(2);
+  });
+
+  test('an existing --name is refused before the code is read or sent', async () => {
+    const control = plane();
+    expect((await pair(control, ['--name', 'cabin'])).code).toBe(EXIT_CODE.success);
+    control.pairingCodes.set('ANOTHER-CODE', HOME_ID);
+
+    const reader = secret('ANOTHER-CODE');
+    const host = testHost({ fetch: control.fetch, home, readSecret: reader.readSecret });
+    const before = control.requests.length;
+    expect(await run(['pair', '--issuer', ISSUER, '--name', 'cabin'], host)).toBe(EXIT_CODE.usage);
+    expect(reader.prompts).toEqual([]);
+    expect(control.requests.length).toBe(before);
+    expect(control.pairingCodes.has('ANOTHER-CODE')).toBe(true);
+  });
+
+  test('the code is read through the hidden prompt, never required as an argument', async () => {
+    const control = plane();
+    const reader = secret(`  ${CODE}  \n`);
+    const host = testHost({ fetch: control.fetch, home, readSecret: reader.readSecret });
+    expect(await run(['pair', '--issuer', ISSUER], host)).toBe(EXIT_CODE.success);
+    expect(reader.prompts).toEqual(['Pairing code (hidden): ']);
+    expect(host.stdout()).toContain(`Paired ${HOME_ID} as context ${HOME_ID}`);
+    expect(everythingPrinted(host)).not.toContain(CODE);
+  });
+
+  test('an explicit --code works and is not echoed', async () => {
+    const control = plane();
+    const host = testHost({ fetch: control.fetch, home });
+    expect(await run(['pair', '--issuer', ISSUER, '--code', CODE], host)).toBe(EXIT_CODE.success);
+    expect(everythingPrinted(host)).not.toContain(CODE);
+  });
+
+  test('without a code source the command explains how to pipe one', async () => {
+    const host = testHost({ fetch: plane().fetch, home });
+    expect(await run(['pair', '--issuer', ISSUER], host)).toBe(EXIT_CODE.usage);
+    expect(host.stderr()).toContain('printf %s "$CODE" | miakapp pair');
+  });
+
+  test('a non-https issuer is refused before any network use', async () => {
+    const control = plane();
+    const host = testHost({ fetch: control.fetch, home, ...secret(CODE) });
+    expect(await run(['pair', '--issuer', 'http://control.example.test'], host)).toBe(EXIT_CODE.usage);
+    expect(await run(['pair', '--issuer', `${ISSUER}/`], host)).toBe(EXIT_CODE.usage);
+    expect(control.requests).toEqual([]);
+  });
+
+  test('an issuer whose discovery names another issuer never receives the code', async () => {
+    const control = plane();
+    const host = testHost({
+      fetch: async (input, init) => {
+        if (input.endsWith('/.well-known/miakapp-control-plane')) {
+          return new Response(JSON.stringify({
+            schema: 'miakapp.control-plane-discovery/1',
+            issuer: 'https://attacker.example.test',
+            jwks_uri: 'https://attacker.example.test/jwks',
+            exchange_endpoint: 'https://attacker.example.test/x',
+            user_relay_exchange_endpoint: 'https://attacker.example.test/y',
+            push_audience: 'https://attacker.example.test/p',
+            components_audience: 'https://attacker.example.test/c',
+          }), { status: 200 });
+        }
+        return control.fetch(input, init);
+      },
+      home,
+      ...secret(CODE),
+    });
+    expect(await run(['pair', '--issuer', ISSUER], host)).toBe(EXIT_CODE.contract);
+    expect(control.pairingRequests).toEqual([]);
+    expect(control.pairingCodes.has(CODE)).toBe(true);
+  });
+
+  test('a used, expired or wrong code is an authorization failure pointing to the pairing page', async () => {
+    const control = plane();
+    control.pairingCodes.clear();
+    const { code, host } = await pair(control);
+    expect(code).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain('https://miakapp.com/pair');
+    expect(host.stderr()).toContain('invalid_pairing_code');
+    expect((await readContexts(store)).contexts.size).toBe(0);
+  });
+
+  test('throttling is reported with its delay and never retried', async () => {
+    const control = plane(HOME_ID, {
+      fail: new Map([['POST /v1/pairing/redeem', { status: 429, code: 'rate_limited' }]]),
+    });
+    const { code, host } = await pair(control);
+    expect(code).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain('too many attempts');
+    expect(control.requests.filter((entry) => entry === 'POST /v1/pairing/redeem')).toHaveLength(1);
+  });
+
+  test('a lost response is an unknown outcome, because a key may have been issued', async () => {
+    const control = plane();
+    const host = testHost({
+      fetch: async (input, init) => {
+        if (input.endsWith('/v1/pairing/redeem')) throw new TypeError('socket hang up');
+        return control.fetch(input, init);
+      },
+      home,
+      ...secret(CODE),
+    });
+    expect(await run(['pair', '--issuer', ISSUER, '--json'], host)).toBe(EXIT_CODE.unknown_outcome);
+    expect(host.stderr()).toContain('revoke any Home Key labelled');
+  });
+
+  test('a response without no-store is refused and nothing is stored', async () => {
+    const control = plane(HOME_ID, {
+      pairingResponse: (issued) => new Response(JSON.stringify({
+        home_key: issued.homeKey,
+        home_id: issued.homeId,
+        key_id: issued.keyId,
+        issuer: ISSUER,
+      }), { status: 200 }),
+    });
+    const { code, host } = await pair(control);
+    expect(code).toBe(EXIT_CODE.contract);
+    expect(host.stderr()).toContain('no-store');
+    expect((await readContexts(store)).contexts.size).toBe(0);
+  });
+
+  for (const [label, mutate] of [
+    ['another issuer', (body: Record<string, unknown>) => ({ ...body, issuer: 'https://evil.example.test' })],
+    ['a key ID the key does not carry', (body: Record<string, unknown>) => ({ ...body, key_id: 'A'.repeat(22) })],
+    ['an invalid home ID', (body: Record<string, unknown>) => ({ ...body, home_id: 'Not A Home' })],
+    ['an unknown member', (body: Record<string, unknown>) => ({ ...body, scopes: ['everything'] })],
+    ['a malformed key', (body: Record<string, unknown>) => ({ ...body, home_key: 'plaintext' })],
+  ] as const) {
+    test(`a response naming ${label} is refused and nothing is stored`, async () => {
+      const control = plane(HOME_ID, {
+        pairingResponse: (issued) => new Response(JSON.stringify(mutate({
+          home_key: issued.homeKey,
+          home_id: issued.homeId,
+          key_id: issued.keyId,
+          issuer: ISSUER,
+        })), { status: 200, headers: { 'cache-control': 'no-store' } }),
+      });
+      const { code, host } = await pair(control);
+      expect(code).toBe(EXIT_CODE.contract);
+      expect(host.stderr()).not.toContain('mhk1_');
+      expect((await readContexts(store)).contexts.size).toBe(0);
+    });
+  }
+
+  test('a key that cannot obtain a publication token is stored and reported as refused', async () => {
+    const control = plane(HOME_ID, {
+      fail: new Map([['POST /v1/access-tokens:exchange', { status: 403, code: 'insufficient_scope' }]]),
+    });
+    const { code, host } = await pair(control);
+    expect(code).toBe(EXIT_CODE.success);
+    expect(host.json()['publish_access']).toBe('refused');
+    expect((await readContexts(store)).contexts.has(HOME_ID)).toBe(true);
+  });
+
+  test('MCP pairs from a tool argument, never from the protocol stdin', async () => {
+    const control = plane();
+    let stdinRead = false;
+    const host = testHost({
+      fetch: control.fetch,
+      home,
+      readSecret: async () => {
+        stdinRead = true;
+        return 'WRONG';
+      },
+    });
+    const result = await callTool(host, 'miakapp_pair', { code: CODE, issuer: ISSUER });
+    expect(result['isError']).toBe(false);
+    expect(stdinRead).toBe(false);
+    expect(JSON.stringify(result)).not.toContain('mhk1_');
+    expect(JSON.stringify(result)).not.toContain(CODE);
+
+    const missing = await callTool(host, 'miakapp_pair', { issuer: ISSUER });
+    expect(missing['isError']).toBe(true);
+  });
+});
+
+describe('credential selection', () => {
+  async function pairedHome(homeId: string): Promise<FakeControlPlane> {
+    const control = plane(homeId);
+    expect((await pair(control)).code).toBe(EXIT_CODE.success);
+    return control;
+  }
+
+  test('publish uses the paired context without any environment export', async () => {
+    const control = await pairedHome(HOME_ID);
+    const key = await storedKey(HOME_ID);
+    const host = testHost({ files: standardProject(), fetch: control.fetch, home });
+
+    expect(await run(['publish', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({
+      generation: 1,
+      expected_generation: 0,
+      credential_source: 'context',
+      context: HOME_ID,
+    });
+    expect(control.exchangedKeys.at(-1)).toBe(key);
+    expect(control.requests).toContain(`GET /v1/homes/${HOME_ID}/component-pointer`);
+    expect(everythingPrinted(host)).not.toContain(key);
+  });
+
+  test('the context matching the project wins over a current context for another home', async () => {
+    const control = await pairedHome(HOME_ID);
+    await pairedHome(OTHER_HOME);
+    expect((await readContexts(store)).current).toBe(OTHER_HOME);
+
+    const host = testHost({ files: standardProject(), fetch: control.fetch, home });
+    expect(await run(['status', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({ context: HOME_ID, generation: 0, active: false });
+  });
+
+  test('an explicit context for another home is refused before anything is sent', async () => {
+    const control = await pairedHome(OTHER_HOME);
+    const before = control.requests.length;
+    const host = testHost({ files: standardProject(), fetch: control.fetch, home });
+
+    expect(await run(['publish', '--context', OTHER_HOME], host)).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain(`is for home ${OTHER_HOME}`);
+    expect(host.stderr()).toContain(`targets home ${HOME_ID}`);
+    expect(control.requests.length).toBe(before);
+  });
+
+  test('MIAKAPP_CONTEXT selects like --context, and the flag wins over it', async () => {
+    const control = await pairedHome(HOME_ID);
+    await pairedHome(OTHER_HOME);
+
+    const wrong = testHost({
+      files: standardProject(),
+      fetch: control.fetch,
+      home,
+      env: { [CONTEXT_VARIABLE]: OTHER_HOME },
+    });
+    expect(await run(['status'], wrong)).toBe(EXIT_CODE.authorization);
+
+    const flagged = testHost({
+      files: standardProject(),
+      fetch: control.fetch,
+      home,
+      env: { [CONTEXT_VARIABLE]: OTHER_HOME },
+    });
+    expect(await run(['status', '--context', HOME_ID], flagged)).toBe(EXIT_CODE.success);
+  });
+
+  test('an explicit context wins over MIAKAPP_HOME_KEY', async () => {
+    const control = await pairedHome(HOME_ID);
+    const key = await storedKey(HOME_ID);
+    const host = testHost({
+      files: standardProject(),
+      fetch: control.fetch,
+      home,
+      env: { [HOME_KEY_VARIABLE]: homeKey() },
+    });
+    expect(await run(['status', '--context', HOME_ID, '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()['credential_source']).toBe('context');
+    expect(control.exchangedKeys.at(-1)).toBe(key);
+  });
+
+  test('MIAKAPP_HOME_KEY still works alone, for CI, and wins over stored contexts', async () => {
+    const control = await pairedHome(HOME_ID);
+    const ciKey = homeKey();
+    const host = testHost({
+      files: standardProject(),
+      fetch: control.fetch,
+      home,
+      env: { [HOME_KEY_VARIABLE]: ciKey },
+    });
+    expect(await run(['status', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({ credential_source: 'environment', context: null });
+    expect(control.exchangedKeys.at(-1)).toBe(ciKey);
+  });
+
+  test('MIAKAPP_HOME_KEY known to belong to another stored home is refused', async () => {
+    const control = await pairedHome(OTHER_HOME);
+    const otherKey = await storedKey(OTHER_HOME);
+    const before = control.requests.length;
+    const host = testHost({
+      files: standardProject(),
+      fetch: control.fetch,
+      home,
+      env: { [HOME_KEY_VARIABLE]: otherKey },
+    });
+    expect(await run(['publish'], host)).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain(`paired as context ${OTHER_HOME}`);
+    expect(control.requests.length).toBe(before);
+  });
+
+  test('no credential at all names the pairing flow as the remedy', async () => {
+    const host = testHost({ files: standardProject(), fetch: plane().fetch, home });
+    expect(await run(['publish'], host)).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain(`No credential for home ${HOME_ID}`);
+    expect(host.stderr()).toContain('miakapp pair');
+  });
+
+  test('status after publish shows what is live and the digest to roll back to', async () => {
+    const control = await pairedHome(HOME_ID);
+    const publisher = testHost({ files: standardProject(), fetch: control.fetch, home });
+    expect(await run(['publish', '--json'], publisher)).toBe(EXIT_CODE.success);
+    const published = publisher.json();
+
+    const reader = testHost({ files: standardProject(), fetch: control.fetch, home });
+    expect(await run(['status', '--json'], reader)).toBe(EXIT_CODE.success);
+    expect(reader.json()).toMatchObject({
+      active: true,
+      generation: 1,
+      sha256: published['sha256'],
+      release: published['release'],
+    });
+    expect(reader.json()['expected_generation']).toBeUndefined();
+  });
+
+  test('a publication read live still fails as a conflict when the pointer moves', async () => {
+    const control = await pairedHome(HOME_ID);
+    const original = control.fetch;
+    const racing: typeof original = async (input, init) => {
+      const response = await original(input, init);
+      // Another publisher activates between the pointer read and this one's activation.
+      if (input.endsWith('/component-pointer')) control.generation += 1;
+      return response;
+    };
+    const host = testHost({ files: standardProject(), fetch: racing, home });
+    expect(await run(['publish'], host)).toBe(EXIT_CODE.conflict);
+  });
+
+  test('init after pair needs no identifier typed by hand', async () => {
+    await pairedHome(HOME_ID);
+    const files = new MemoryFiles();
+    const host = testHost({ files, home });
+    expect(await run(['init', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({ home_id: HOME_ID, control_plane: ISSUER, context: HOME_ID });
+    expect(files.text(`${PROJECT_ROOT}/miakapp.yaml`)).toContain(`home: ${HOME_ID}\ncontrol_plane: ${ISSUER}\n`);
+  });
+
+  test('init refuses a --home that contradicts the context it was told to use', async () => {
+    await pairedHome(HOME_ID);
+    const host = testHost({ files: new MemoryFiles(), home });
+    expect(await run(['init', '--context', HOME_ID, '--home', OTHER_HOME], host)).toBe(EXIT_CODE.usage);
+  });
+});
+
+describe('miakapp context', () => {
+  async function seed(): Promise<void> {
+    expect((await pair(plane(HOME_ID))).code).toBe(EXIT_CODE.success);
+    expect((await pair(plane(OTHER_HOME))).code).toBe(EXIT_CODE.success);
+  }
+
+  test('list shows every home and never a key', async () => {
+    await seed();
+    const host = testHost({ home });
+    expect(await run(['context', 'list', '--json'], host)).toBe(EXIT_CODE.success);
+    const report = host.json();
+    expect(report['current_context']).toBe(OTHER_HOME);
+    const contexts = report['contexts'] as Array<Record<string, unknown>>;
+    expect(contexts.map((entry) => [entry['name'], entry['current'], entry['credential']])).toEqual([
+      [OTHER_HOME, true, 'stored'],
+      [HOME_ID, false, 'stored'],
+    ]);
+    expect(host.stdout()).not.toContain('mhk1_');
+
+    const text = testHost({ home });
+    expect(await run(['context', 'list'], text)).toBe(EXIT_CODE.success);
+    expect(text.stdout()).toContain(`* ${OTHER_HOME}:`);
+    expect(text.stdout()).not.toContain('mhk1_');
+  });
+
+  test('show redacts the credential and defaults to the current context', async () => {
+    await seed();
+    const host = testHost({ home });
+    expect(await run(['context', 'show'], host)).toBe(EXIT_CODE.success);
+    expect(host.stdout()).toContain(`Context ${OTHER_HOME} (current)`);
+    expect(host.stdout()).toContain('credential: stored (never printed)');
+    expect(host.stdout()).not.toContain('mhk1_');
+  });
+
+  test('use switches the current context and survives a restart', async () => {
+    await seed();
+    expect(await run(['context', 'use', HOME_ID], testHost({ home }))).toBe(EXIT_CODE.success);
+    // A new process reads the same files: nothing lives in memory or in the environment.
+    expect((await readContexts(store)).current).toBe(HOME_ID);
+    expect(await run(['context', 'use', 'missing'], testHost({ home }))).toBe(EXIT_CODE.usage);
+  });
+
+  test('remove deletes the context and its key, keeps the others and says the key is not revoked', async () => {
+    await seed();
+    const removedKey = await storedKey(OTHER_HOME);
+    const host = testHost({ home });
+    expect(await run(['context', 'remove', OTHER_HOME, '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()).toMatchObject({ removed: OTHER_HOME, was_current: true, revoked: false });
+
+    const state = await readContexts(store);
+    expect([...state.contexts.keys()]).toEqual([HOME_ID]);
+    expect(state.current).toBeNull();
+    expect(await readFile(join(store, CREDENTIALS_FILE), 'utf8')).not.toContain(removedKey);
+  });
+
+  test('an unknown action or a bad name is a usage failure', async () => {
+    expect(await run(['context'], testHost({ home }))).toBe(EXIT_CODE.usage);
+    expect(await run(['context', 'rename', 'a'], testHost({ home }))).toBe(EXIT_CODE.usage);
+    expect(await run(['context', 'use', '../escape'], testHost({ home }))).toBe(EXIT_CODE.usage);
+  });
+
+  test('an empty store lists nothing and reads nothing outside it', async () => {
+    const host = testHost({ home });
+    expect(await run(['context', 'list', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()['contexts']).toEqual([]);
+  });
+
+  test('MIAKAPP_CONFIG_DIR relocates the store and must be absolute', async () => {
+    const elsewhere = join(home, 'ci-store');
+    const control = plane();
+    const host = testHost({
+      fetch: control.fetch,
+      home,
+      env: { MIAKAPP_CONFIG_DIR: elsewhere },
+      ...secret(CODE),
+    });
+    expect(await run(['pair', '--issuer', ISSUER], host)).toBe(EXIT_CODE.success);
+    expect((await readContexts(elsewhere)).contexts.has(HOME_ID)).toBe(true);
+    expect((await readContexts(store)).contexts.size).toBe(0);
+
+    const relative = testHost({ home, env: { MIAKAPP_CONFIG_DIR: 'relative/dir' } });
+    expect(await run(['context', 'list'], relative)).toBe(EXIT_CODE.usage);
+  });
+});
+
+describe('the store protects itself', () => {
+  async function seeded(): Promise<void> {
+    expect((await pair(plane(HOME_ID))).code).toBe(EXIT_CODE.success);
+  }
+
+  test.skipIf(process.platform === 'win32')('a credentials file readable by others is refused', async () => {
+    await seeded();
+    await chmod(join(store, CREDENTIALS_FILE), 0o644);
+    const host = testHost({ files: standardProject(), fetch: plane().fetch, home });
+    expect(await run(['status'], host)).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain('chmod 600');
+  });
+
+  test.skipIf(process.platform === 'win32')('a symbolic link in place of the credentials is refused', async () => {
+    await seeded();
+    const elsewhere = join(home, 'elsewhere.json');
+    await writeFile(elsewhere, await readFile(join(store, CREDENTIALS_FILE)), { mode: 0o600 });
+    await rm(join(store, CREDENTIALS_FILE));
+    await symlink(elsewhere, join(store, CREDENTIALS_FILE));
+    expect(await run(['context', 'list'], testHost({ home }))).toBe(EXIT_CODE.authorization);
+  });
+
+  test('a configuration that does not parse is refused, never rewritten', async () => {
+    await seeded();
+    await writeFile(join(store, CONFIG_FILE), '{"schema": ', { mode: 0o600 });
+    const host = testHost({ home });
+    expect(await run(['context', 'use', HOME_ID], host)).toBe(EXIT_CODE.authorization);
+    expect(await readFile(join(store, CONFIG_FILE), 'utf8')).toBe('{"schema": ');
+  });
+
+  test('a credential swapped for another key is refused', async () => {
+    await seeded();
+    const path = join(store, CREDENTIALS_FILE);
+    const document = JSON.parse(await readFile(path, 'utf8')) as {
+      credentials: Record<string, { home_key: string }>;
+    };
+    document.credentials[HOME_ID] = { home_key: homeKey() };
+    await writeFile(path, JSON.stringify(document), { mode: 0o600 });
+
+    const host = testHost({ files: standardProject(), fetch: plane().fetch, home });
+    expect(await run(['status'], host)).toBe(EXIT_CODE.authorization);
+    expect(host.stderr()).toContain('is not the key');
+  });
+
+  test('concurrent writers never lose a context', async () => {
+    await Promise.all(Array.from({ length: 12 }, (_, index) => mutateContexts(store, (state) => {
+      const name = `home-${index}`;
+      const key = homeKey();
+      state.contexts.set(name, {
+        name,
+        issuer: ISSUER,
+        homeId: `home-${index}x`,
+        keyId: key.slice(5, 27),
+        label: 'test',
+        createdAt: new Date().toISOString(),
+      });
+      state.keys.set(name, key);
+    })));
+    const state = await readContexts(store);
+    expect(state.contexts.size).toBe(12);
+    expect([...state.credentials.values()].every((status) => status === 'stored')).toBe(true);
+    // Atomic replacement leaves no temporary file and no lock behind.
+    expect((await readdir(store)).sort()).toEqual([CONFIG_FILE, CREDENTIALS_FILE]);
+  });
+
+  test('a failed change writes nothing', async () => {
+    await seeded();
+    const before = await readFile(join(store, CONFIG_FILE), 'utf8');
+    await expect(mutateContexts(store, () => {
+      throw new Error('refused');
+    })).rejects.toThrow('refused');
+    expect(await readFile(join(store, CONFIG_FILE), 'utf8')).toBe(before);
+    expect((await readdir(store)).sort()).toEqual([CONFIG_FILE, CREDENTIALS_FILE]);
+  });
+
+  test('a lock left by a crashed process is reclaimed once stale', async () => {
+    await seeded();
+    const lock = join(store, 'lock');
+    await writeFile(lock, '999999\n');
+    const old = new Date(Date.now() - 120_000);
+    await utimes(lock, old, old);
+    expect(await run(['context', 'use', HOME_ID], testHost({ home }))).toBe(EXIT_CODE.success);
+  });
+
+  test.skipIf(process.platform === 'win32')('a loose store directory is tightened on the next write', async () => {
+    await seeded();
+    await chmod(store, 0o755);
+    expect(await run(['context', 'use', HOME_ID], testHost({ home }))).toBe(EXIT_CODE.success);
+    expect((await lstat(store)).mode & 0o777).toBe(0o700);
+  });
+});
diff --git a/packages/cli/test/mcp.test.ts b/packages/cli/test/mcp.test.ts
index 2e4d68a..93f1478 100644
--- a/packages/cli/test/mcp.test.ts
+++ b/packages/cli/test/mcp.test.ts
@@ -59,7 +59,14 @@ describe('the tool surface mirrors the command surface', () => {
     const commands = Object.keys(COMMAND_OPTIONS)
       .filter((name) => !['help', 'version', 'mcp'].includes(name))
       .sort();
-    expect(TOOLS.map((entry) => entry.command).sort()).toEqual(commands);
+    expect([...new Set(TOOLS.map((entry) => entry.command))].sort()).toEqual(commands);
+  });
+
+  test('every context action is its own tool, so no tool takes a free-form verb', () => {
+    const actions = TOOLS.filter((entry) => entry.command === 'context')
+      .map((entry) => entry.action)
+      .sort();
+    expect(actions).toEqual(['list', 'remove', 'show', 'use']);
   });
 
   test('no tool hides an option the command accepts', () => {
@@ -82,9 +89,14 @@ describe('the tool surface mirrors the command surface', () => {
     }
   });
 
-  test('exactly the pointer-moving tools are guarded and declared destructive', () => {
-    const guarded = TOOLS.filter((entry) => entry.guarded).map((entry) => entry.command).sort();
-    expect(guarded).toEqual(['activate', 'publish', 'rollback']);
+  test('exactly the pointer-moving and key-deleting tools are guarded and declared destructive', () => {
+    const guarded = TOOLS.filter((entry) => entry.guarded).map((entry) => entry.name).sort();
+    expect(guarded).toEqual([
+      'miakapp_activate',
+      'miakapp_context_remove',
+      'miakapp_publish',
+      'miakapp_rollback',
+    ]);
     for (const entry of TOOLS) {
       const confirms = entry.args.some((argument) => argument.name === 'confirm');
       expect([entry.name, confirms]).toEqual([entry.name, entry.guarded]);
@@ -103,7 +115,9 @@ describe('the tool surface mirrors the command surface', () => {
       expect([entry.name, declared]).toEqual([entry.name, expected.sort()]);
 
       const required = entry.args.filter((argument) => argument.required).map((a) => a.name);
-      if (entry.positional !== undefined) required.unshift(entry.positional.name);
+      if (entry.positional !== undefined && entry.positional.required !== false) {
+        required.unshift(entry.positional.name);
+      }
       expect([entry.name, schema['required']]).toEqual([entry.name, required]);
     }
   });
@@ -142,7 +156,30 @@ describe('argument translation', () => {
   });
 
   test('a missing required argument is refused before anything runs', () => {
-    expect(() => buildArgv(tool('miakapp_publish'), { confirm: true })).toThrow(/required/);
+    expect(() => buildArgv(tool('miakapp_activate'), { confirm: true })).toThrow(/required/);
+    expect(() => buildArgv(tool('miakapp_pair'), {})).toThrow(/code is required/);
+  });
+
+  test('publish may omit the expected generation and let the CLI read it live', () => {
+    expect(buildArgv(tool('miakapp_publish'), { confirm: true })).toEqual(['publish']);
+  });
+
+  test('a context action is a fixed verb followed by the name', () => {
+    expect(buildArgv(tool('miakapp_context_use'), { name: 'home-a' }))
+      .toEqual(['context', 'use', 'home-a']);
+    expect(buildArgv(tool('miakapp_context_show'), {})).toEqual(['context', 'show']);
+    expect(() => buildArgv(tool('miakapp_context_remove'), { name: 'home-a' }))
+      .toThrow(/confirm must be set to true/);
+    expect(buildArgv(tool('miakapp_context_remove'), { name: 'home-a', confirm: true }))
+      .toEqual(['context', 'remove', 'home-a']);
+  });
+
+  test('a stored context can be selected for every networked command', () => {
+    for (const name of ['miakapp_status', 'miakapp_publish', 'miakapp_activate',
+      'miakapp_rollback', 'miakapp_release', 'miakapp_upload', 'miakapp_init']) {
+      expect([name, tool(name).args.some((argument) => argument.name === 'context')])
+        .toEqual([name, true]);
+    }
   });
 
   test('a negative generation is refused before the parser sees it', () => {
diff --git a/packages/cli/test/support/control-plane.ts b/packages/cli/test/support/control-plane.ts
index ffce18c..0e9aa32 100644
--- a/packages/cli/test/support/control-plane.ts
+++ b/packages/cli/test/support/control-plane.ts
@@ -36,6 +36,8 @@ export interface FakeControlPlaneOptions {
   readonly generation?: number;
   /** Forces one response, by exact `${method} ${path}` key, for failure tests. */
   readonly fail?: ReadonlyMap<string, { status: number; code: string }>;
+  /** Replaces the pairing redeem response, for contract-violation tests. */
+  readonly pairingResponse?: (issued: { homeKey: string; homeId: string; keyId: string }) => Response;
 }
 
 export interface FakeControlPlane {
@@ -44,6 +46,13 @@ export interface FakeControlPlane {
   generation: number;
   readonly uploads: Map<string, Upload>;
   readonly releases: Map<string, { release: string; sha256: string; size: number; requires: unknown }>;
+  /** One-time pairing codes still redeemable, mapped to the home they open. */
+  readonly pairingCodes: Map<string, string>;
+  /** Every pairing redeem body received, to prove what the CLI sent. */
+  readonly pairingRequests: Array<{ code: string; label: string }>;
+  /** Every Home Key presented to the token exchange. */
+  readonly exchangedKeys: string[];
+  active: { release: string; sha256: string; size: number; requires: unknown } | undefined;
 }
 
 function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
@@ -74,6 +83,10 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
     generation: options.generation ?? 0,
     uploads: new Map(),
     releases: new Map(),
+    pairingCodes: new Map(),
+    pairingRequests: [],
+    exchangedKeys: [],
+    active: undefined,
   };
 
   async function handle(input: string, init: RequestInit): Promise<Response> {
@@ -100,6 +113,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
       const authorization = (init.headers as Record<string, string>)['authorization'] ?? '';
       const keyId = /^Bearer mhk1_([A-Za-z0-9_-]{22})_/.exec(authorization)?.[1];
       if (keyId === undefined) return failure(401, 'invalid_home_key');
+      plane.exchangedKeys.push(authorization.slice('Bearer '.length));
       return json(200, {
         schema: 'miakapp.access-token/1',
         access_token: 'header.payload.signature',
@@ -113,6 +127,24 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
       });
     }
 
+    if (key === 'POST /v1/pairing/redeem') {
+      const body = JSON.parse(String(init.body)) as { code: string; label: string };
+      plane.pairingRequests.push(body);
+      const homeId = plane.pairingCodes.get(body.code);
+      if (homeId === undefined) return failure(410, 'invalid_pairing_code');
+      plane.pairingCodes.delete(body.code);
+      const issued = homeKey();
+      const keyId = issued.slice(5, 27);
+      if (options.pairingResponse !== undefined) {
+        return options.pairingResponse({ homeKey: issued, homeId, keyId });
+      }
+      return json(200, { home_key: issued, home_id: homeId, key_id: keyId, issuer: ISSUER }, {
+        'cache-control': 'no-store',
+        pragma: 'no-cache',
+        'referrer-policy': 'no-referrer',
+      });
+    }
+
     const local = input.startsWith(base) ? input.slice(base.length) : undefined;
     if (local === undefined) return failure(404, 'not_found');
 
@@ -182,6 +214,15 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
       });
     }
 
+    if (method === 'GET' && local === '/component-pointer') {
+      const active = plane.active;
+      return json(200, {
+        schema: 'miakapp.component-pointer-state/1',
+        generation: plane.generation,
+        pointer: active === undefined ? null : pointerBody(plane.generation, active),
+      });
+    }
+
     const releaseMatch = /^\/component-releases\/([A-Za-z0-9_-]{43})$/.exec(local);
     if (method === 'GET' && releaseMatch !== null) {
       const record = plane.releases.get(releaseMatch[1] as string);
@@ -201,22 +242,30 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
         return failure(409, 'generation_conflict');
       }
       plane.generation = body.generation;
-      return json(200, {
-        schema: 'miakapp.component-pointer/1',
-        home_id: options.homeId,
-        generation: body.generation,
-        release: record.release,
-        abi: COMPONENT_ABI,
-        url: `${ISSUER}/v1/components/${record.sha256}.js`,
-        sha256: record.sha256,
-        size: record.size,
-        requires: record.requires,
-      });
+      plane.active = record;
+      return json(200, pointerBody(body.generation, record));
     }
 
     return failure(404, 'not_found');
   }
 
+  function pointerBody(
+    generation: number,
+    record: { release: string; sha256: string; size: number; requires: unknown },
+  ): unknown {
+    return {
+      schema: 'miakapp.component-pointer/1',
+      home_id: options.homeId,
+      generation,
+      release: record.release,
+      abi: COMPONENT_ABI,
+      url: `${ISSUER}/v1/components/${record.sha256}.js`,
+      sha256: record.sha256,
+      size: record.size,
+      requires: record.requires,
+    };
+  }
+
   function releaseBody(record: {
     release: string;
     sha256: string;
diff --git a/packages/cli/test/support/host.ts b/packages/cli/test/support/host.ts
index 0b9a62d..6480ba4 100644
--- a/packages/cli/test/support/host.ts
+++ b/packages/cli/test/support/host.ts
@@ -72,12 +72,20 @@ export interface TestHost extends CliHost {
   json(): Record<string, unknown>;
 }
 
+/**
+ * Where `~/.miakapp` resolves for a test that names no store. It never exists,
+ * so no test can read or write the real account's credentials by accident.
+ */
+export const ABSENT_HOME = '/nonexistent/miakapp-test-home';
+
 export function testHost(options: {
   files?: FileSystem;
   fetch?: FetchLike;
   env?: Record<string, string>;
   cwd?: string;
   input?: AsyncIterable<Uint8Array>;
+  home?: string;
+  readSecret?: (prompt: string) => Promise<string>;
 } = {}): TestHost {
   const out: string[] = [];
   const err: string[] = [];
@@ -89,6 +97,9 @@ export function testHost(options: {
     writeError: (text) => void err.push(text),
     cwd: () => options.cwd ?? PROJECT_ROOT,
     env: (name) => environment[name],
+    homeDirectory: () => options.home ?? ABSENT_HOME,
+    hostname: () => 'test-machine',
+    ...(options.readSecret === undefined ? {} : { readSecret: options.readSecret }),
     ...(options.files === undefined ? {} : { files: options.files }),
     ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
     ...(options.input === undefined ? {} : { input: options.input }),
diff --git a/packages/cli/test/terminal.test.ts b/packages/cli/test/terminal.test.ts
new file mode 100644
index 0000000..9d4d973
--- /dev/null
+++ b/packages/cli/test/terminal.test.ts
@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { EventEmitter } from 'node:events';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { readSecret, type SecretInput } from '../src/terminal.js';
+
+const PACKAGE_DIRECTORY = resolve(import.meta.dir, '..');
+
+class FakeTerminal extends EventEmitter {
+  readonly isTTY = true;
+  readonly modes: boolean[] = [];
+  setRawMode(mode: boolean): this {
+    this.modes.push(mode);
+    return this;
+  }
+  resume(): this {
+    return this;
+  }
+  pause(): this {
+    return this;
+  }
+  async *[Symbol.asyncIterator](): AsyncIterator<string> {
+    // A terminal is read through `data` events in raw mode, never iterated.
+    throw new Error('iterated a terminal');
+  }
+}
+
+describe('reading a secret', () => {
+  test('a pipe yields its first line and nothing is echoed', async () => {
+    const echoed: string[] = [];
+    const value = await readSecret(
+      Readable.from(['ABCD-', 'EFGH\nsecond line\n']) as unknown as SecretInput,
+      'Pairing code: ',
+      (text) => void echoed.push(text),
+    );
+    expect(value).toBe('ABCD-EFGH');
+    expect(echoed).toEqual([]);
+  });
+
+  test('a terminal is prompted in raw mode, without echo, and restored', async () => {
+    const terminal = new FakeTerminal();
+    const echoed: string[] = [];
+    const pending = readSecret(terminal, 'Pairing code: ', (text) => void echoed.push(text));
+    terminal.emit('data', 'ABX');
+    terminal.emit('data', '\u007fC-12\r');
+    expect(await pending).toBe('ABC-12');
+    expect(terminal.modes).toEqual([true, false]);
+    expect(echoed.join('')).toBe('Pairing code: \n');
+  });
+
+  test('Ctrl-C on a terminal cancels and restores the terminal', async () => {
+    const terminal = new FakeTerminal();
+    const pending = readSecret(terminal, '> ', () => {});
+    terminal.emit('data', 'AB\u0003');
+    await expect(pending).rejects.toThrow('Cancelled');
+    expect(terminal.modes).toEqual([true, false]);
+  });
+});
+
+describe('the built executable', () => {
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(join(tmpdir(), 'miakapp-bin-'));
+    const build = Bun.spawnSync(['bun', 'run', 'build'], { cwd: PACKAGE_DIRECTORY, stdout: 'pipe', stderr: 'pipe' });
+    expect(build.exitCode).toBe(0);
+  });
+
+  afterEach(async () => {
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  test('pair reads the code from a pipe and never sends it to an unproven issuer', () => {
+    const code = 'PIPE-CODE-1234';
+    const result = Bun.spawnSync(
+      ['node', 'bin/miakapp.js', 'pair', '--issuer', 'https://127.0.0.1:9', '--json'],
+      {
+        cwd: PACKAGE_DIRECTORY,
+        stdin: new TextEncoder().encode(`${code}\n`),
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { ...process.env, MIAKAPP_CONFIG_DIR: directory, MIAKAPP_HOME_KEY: '' },
+      },
+    );
+    const stderr = result.stderr.toString();
+    expect(result.exitCode).toBe(5);
+    expect(JSON.parse(stderr)).toMatchObject({ ok: false, kind: 'contract' });
+    expect(stderr).toContain('The code was not sent');
+    expect(stderr + result.stdout.toString()).not.toContain(code);
+  });
+
+  test('context list works from a fresh process with no environment export', () => {
+    const result = Bun.spawnSync(['node', 'bin/miakapp.js', 'context', 'list', '--json'], {
+      cwd: PACKAGE_DIRECTORY,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: { ...process.env, MIAKAPP_CONFIG_DIR: directory },
+    });
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout.toString())).toMatchObject({
+      ok: true,
+      config_directory: directory,
+      contexts: [],
+    });
+  });
+});

From 5101ea467ad938e12aaa6951c13d58a98be9b86c Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 04:19:53 +0200
Subject: [PATCH 2/7] docs: make a verified publication the agent's deliverable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent guide (docs + packaged asset), agent-pack block, CLI and template READMEs:

- §0 defines done as a published, verified interface and a working link —
  never a screenshot, mockup or offline prototype — separates publishing a V4
  interface (in scope, reversible) from changing the physical installation
  (explicit request only), and states no platform source is needed.
- §3 requires a committed docs/inventory.md (source, meaning, freshness,
  readers, command) before design; the V1 covers the real data, never invents
  values, distinguishes current/stale/unavailable and shows no plumbing text.
- §8/§9 document pair, contexts, credential precedence, status and the
  optional --expected-generation; the pack block points at pairing.
- Template: publish:home no longer hardcodes generation 0 (it failed on every
  second publication); control plane uses the production issuer
  control.miakapp.com expected by the backend instead of control.miakapp.app.
- Tests: the guide must mention every command and the deliverable rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/agent-guide.md                  | 163 ++++++++++++++++++++++++---
 packages/cli/README.md               | 104 +++++++++++++----
 packages/cli/assets/agent-guide.md   | 163 ++++++++++++++++++++++++---
 packages/cli/src/agent-pack.ts       |  11 +-
 packages/cli/test/agent-pack.test.ts |  29 ++++-
 templates/home/README.md             |  23 +++-
 templates/home/miakapp.yaml          |   2 +-
 templates/home/package.json          |   2 +-
 8 files changed, 427 insertions(+), 70 deletions(-)

diff --git a/docs/agent-guide.md b/docs/agent-guide.md
index 6c0f1ce..a65a009 100644
--- a/docs/agent-guide.md
+++ b/docs/agent-guide.md
@@ -10,6 +10,42 @@ Everything below is true of the code in this repository. Where a rule exists for
 a reason that is not obvious, the reason is given, because a rule whose purpose
 you cannot see is one you will optimize away.
 
+## 0. What "done" means
+
+The owner asked for a home they can use, not for a picture of one. You are done
+when the household can open the published interface, read real values from it
+and use every control the owner authorized — and you checked that yourself.
+Concretely:
+
+- **Publish, then verify.** A build that only runs on your machine, a mockup, a
+  prototype kept offline or a screenshot is an intermediate result, never the
+  deliverable. Do not stop to show one and ask whether to continue: the owner
+  asked for the home, and publication is reversible in one command (§8).
+- **Hand over a link that works.** Give the owner the Miakapp app address where
+  the home appears for its members, and say what you verified there. The `url`
+  that `miakapp publish` prints is the raw component bytes, not an interface:
+  never send it as "the link". If you cannot open the app yourself, say exactly
+  that, and what `miakapp status` proved instead.
+- **Ask once, at the start, and only for what you cannot find.** Access comes
+  from pairing (§9), the existing installation from inventory (§3). Repeated
+  permission questions in the middle of the work are a failure of the work.
+- **You need nothing from the platform's source.** This guide, the CLI, the
+  public packages and `templates/home` are the whole toolchain. Never edit or
+  redeploy the Miakapp platform to make one house work; if a capability is
+  missing, report it to the owner as missing instead of patching around it.
+
+Two scopes must not be confused:
+
+| In scope by default | Needs the owner's explicit, separate request |
+| --- | --- |
+| reading the existing installation (§3) | changing flows, automations, brokers or devices that already run the house |
+| writing and testing a coordinator and a component | granting a physical action (heat, lock, unlock, open, close) that the owner has not named |
+| publishing, verifying and rolling back the V4 interface | anything on the owner's own machines beyond the coordinator you were asked to run |
+
+Caution about the second column is not a reason to withhold the first. A new V4
+interface that only reads is still a useful, publishable V1; say plainly which
+controls are not offered and why.
+
 ## 1. What you are building
 
 Three artifacts, and no more:
@@ -94,6 +130,37 @@ Write down what you found before you write the configuration. The state paths yo
 choose become a disclosure boundary and a public interface at the same time, and
 renaming one after the household has used it is not free.
 
+### The inventory comes before the design
+
+Commit the inventory as `docs/inventory.md` in the home repository, one line per
+datum or action, before you design a single screen:
+
+| Field | Example |
+| --- | --- |
+| source | `zigbee2mqtt/salon_thermo` over the house broker |
+| what it is | temperature, °C, one decimal |
+| how fresh | reports every ~60 s; last seen 2 min ago |
+| who may read it | every member / owner only |
+| command | none — a measurement, not a control |
+
+Then design **from** it: the V1 shows every datum the household would care
+about and every action that is both technically possible and authorized,
+grouped the way people live in the house — by room or by use, not by device
+or protocol. Anything you leave out, leave out on purpose, and say why in the
+inventory. A V1 that shows three values when the house reports twenty is not a
+first version; it is an unfinished one.
+
+What the interface must never do:
+
+- **invent data.** A value with no source is shown as absent, never filled in
+  with a plausible number or a demo fixture;
+- **blur freshness.** Distinguish *current*, *stale* (with its age) and
+  *unavailable* for every value, in words a resident understands;
+- **spend space on plumbing.** No protocol or platform vocabulary
+  (`ACCEPTED`, "relay connected", ABI, schema names, IDs), no banner restating
+  that a view is read-only, no title repeating the home's name on every card.
+  Every line of text is either information or an action.
+
 ### Reading a V3 house you inherited
 
 Most houses arriving at V4 already run Node-RED with the v3 MiakAPI nodes. Ask
@@ -305,25 +372,34 @@ writes no history, rewrites no source it did not generate, and invents no
 control-plane endpoint. The repository is the owner's.
 
 ```bash
-miakapp agent-pack                                             # once, per repository
-miakapp init --home <homeId> --control-plane <https url>
+miakapp docs start                             # this guide, from the installed CLI
+miakapp pair                                   # once per home and machine (§9)
+miakapp agent-pack                             # once, per repository
+miakapp init                                   # home and issuer come from the paired context
 miakapp check
-miakapp publish  --expected-generation <n>
-miakapp activate --sha256 <digest> --expected-generation <n>
-miakapp rollback --sha256 <digest> --expected-generation <n>   # alias of activate
+miakapp status                                 # what is live now: generation, release, digest
+miakapp publish                                # upload, finalize, activate
+miakapp status                                 # verify the new digest is what is live
+miakapp activate --sha256 <digest>             # promote an already finalized digest
+miakapp rollback --sha256 <digest>             # alias of activate
 miakapp release <sha256>      # read one finalized release
 miakapp upload  <uploadId>    # reconcile a lost request
 ```
 
-`--expected-generation` is a compare-and-swap on the home's component pointer: the
-generation you believe it currently holds. It is `0` for a home that has never
-published. It is required, and it is what stops two agents from silently
-overwriting each other.
+Activation is a compare-and-set on the home's component pointer. Without
+`--expected-generation` the CLI reads the live generation first and activates
+the next one; the read takes no lock, so another publication landing in between
+still fails with `conflict` instead of being overwritten. Pass
+`--expected-generation <n>` when you want to assert the state you reviewed.
 
 Rollback is `activate` pointed at a digest you already trust. Keep the digest of
 every release you shipped; a rollback you can perform in one command is worth
 more than an incident you can explain.
 
+`miakapp status` after `publish` is the minimum verification: the live `sha256`
+must be the one you just built. It proves what the home runs, not that the
+interface is right — open it as a member would before telling the owner it works.
+
 ### Driving the CLI as a program
 
 Every failure maps to exactly one stable exit code and one stable
@@ -366,22 +442,68 @@ Three differences are worth knowing before you call anything:
 `packages/cli/README.md` lists the tools. The exit codes above are the
 `exit_code` field in every result, so branch on the same table either way.
 
-## 9. Secrets
+## 9. Access: pairing and contexts
+
+You never sign in as the owner and never ask for a password, a Google login or
+an existing key. The owner grants access to one home, in their own browser:
 
-`MIAKAPP_HOME_KEY` comes from the environment. It is never a command-line
-argument, never printed, never written into a project file. No command accepts
-one, deliberately: an argument lands in shell history, in a process listing and
-in most CI logs.
+1. Ask the owner to open **https://miakapp.com/pair**, sign in to their own
+   account, choose the home (or create it), confirm the access it grants, and
+   send you the one-time code it shows. A code works once, for ten minutes.
+2. Redeem it. The code is read from stdin and never echoed:
+
+   ```bash
+   printf '%s\n' "<code>" | miakapp pair            # add --issuer <url> if the page shows one
+   ```
+
+   Over MCP, call `miakapp_pair` with `code`. Never repeat the code back in a
+   message, and never retry a refused code — ask for a new one.
+3. `pair` stores a **new, separately revocable** Home Key for this machine as a
+   context in `~/.miakapp`, keeps every other context, makes the new one
+   current, and proves the key can publish. It prints the key ID and label,
+   never the key.
 
 ```bash
-export MIAKAPP_HOME_KEY="$(your-secret-manager read miakapp/home-key)"
+miakapp context list          # every home this machine can publish to
+miakapp context show [name]   # one context; the key is never printed
+miakapp context use <name>    # make a context current
+miakapp context remove <name> # delete it locally (the owner revokes it server-side)
 ```
 
-If you are about to write a secret into `miakapp.yaml` so something works, stop:
-that is the failure this design exists to prevent.
+`~/.miakapp/config.json` holds names, homes, issuers and key IDs;
+`credentials.json` holds the keys. Both are mode 0600 in a 0700 directory and
+are replaced atomically; the CLI refuses a credentials file other accounts can
+read. `MIAKAPP_CONFIG_DIR` relocates the directory.
+
+Which key a command uses, highest precedence first:
+
+1. `--context <name>`, then `MIAKAPP_CONTEXT=<name>`;
+2. `MIAKAPP_HOME_KEY`, a raw key for CI and compatibility;
+3. the stored context paired with the home and issuer in `miakapp.yaml` — the
+   current context breaks a tie between two keys for that same home.
+
+A context, or a known key, for a different home than `miakapp.yaml` names is
+refused before any request: a key can never publish into the wrong house.
+
+Prefer one key per agent or machine, so the owner can revoke one without
+breaking the others. A coordinator running on the owner's machine still reads
+its own key from its environment (`templates/home/README.md`).
+
+If you are about to write a secret into `miakapp.yaml` or any file in the
+repository so something works, stop: that is the failure this design exists to
+prevent.
 
 ## 10. Before you tell the owner you are done
 
+- [ ] `docs/inventory.md` lists every source, datum and action you found, and
+      the interface covers it or says why not.
+- [ ] Every value shows whether it is current, stale or unavailable; nothing is
+      invented, and no technical vocabulary is on screen.
+- [ ] The interface is published, `miakapp status` shows your digest live, and
+      you opened it as a member would — or you say precisely what you could not
+      check.
+- [ ] The owner received a working link and the rollback digest, not a
+      screenshot or a mockup.
 - [ ] Every physically consequential function authorizes its caller on its first
       line, and a test proves an unauthorized caller is refused.
 - [ ] Every name in `miakapp.yaml` is covered by the coordinator, and a test
@@ -390,11 +512,16 @@ that is the failure this design exists to prevent.
 - [ ] No call path retries an unknown outcome.
 - [ ] State is written before its event is published.
 - [ ] `bun run check` is green, and CI ran it — not just you.
-- [ ] The Home Key exists only in the environment.
+- [ ] The Home Key exists only in `~/.miakapp` or the environment, never in the
+      repository.
 - [ ] You recorded the digest of what you published, so rollback is one command.
 
 ## Where to read further
 
+Everything a home needs is above, in the CLI and in the template. The RFCs and
+platform paths below explain *why* the platform behaves as it does; you never
+need them, or the platform repository, to build and publish a home.
+
 - `packages/cli/README.md` — every command and every tool, including what the
   pack writes and what it refuses to overwrite.
 - `templates/home/README.md` — the mechanics of the template itself.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 0a7c9ce..33fbbe4 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -12,9 +12,11 @@ stable exit code and one stable failure kind, and `--json` prints exactly one
 object on stdout.
 
 ```bash
-bunx @miakapp/cli init --home my-home --control-plane https://control.miakapp.app
+printf '%s\n' "$CODE" | bunx @miakapp/cli pair   # code from https://miakapp.com/pair
+bunx @miakapp/cli init                            # home and issuer from the paired context
 bunx @miakapp/cli check
-bunx @miakapp/cli publish --expected-generation 0
+bunx @miakapp/cli publish
+bunx @miakapp/cli status                          # verify what is live
 ```
 
 ## The project file
@@ -24,7 +26,7 @@ bunx @miakapp/cli publish --expected-generation 0
 ```yaml
 schema: miakapp.project/1
 home: my-home
-control_plane: https://control.miakapp.app
+control_plane: https://control.miakapp.com
 
 component:
   artifact: dist/component.js
@@ -55,10 +57,13 @@ duplicate keys — is rejected with the offending line rather than guessed at.
 
 | Command | What it does |
 | --- | --- |
+| `pair` | Redeems a one-time pairing code into a new stored context. |
+| `context list\|show\|use\|remove` | Manages stored contexts. Never prints a key. |
 | `init` | Writes `miakapp.yaml`. Never overwrites an existing one. |
 | `agent-pack` | Offline. Installs the guide and the MCP wiring into a repository. |
 | `discover` | Offline. Inventories a Node-RED installation from its flows export. |
 | `check` | Offline. Parses the project, verifies the artifact, prints the digest. |
+| `status` | Reads the live generation, release and digest of the home. |
 | `publish` | Capability → delivery → finalization → activation, in one run. |
 | `activate` | Activates an already finalized digest at a new generation. |
 | `rollback` | Alias of `activate`, for returning to a known-good digest. |
@@ -129,8 +134,7 @@ tools over newline-delimited JSON-RPC on stdio.
   "mcpServers": {
     "miakapp": {
       "command": "bunx",
-      "args": ["@miakapp/cli", "mcp"],
-      "env": { "MIAKAPP_HOME_KEY": "${MIAKAPP_HOME_KEY}" }
+      "args": ["@miakapp/cli", "mcp"]
     }
   }
 }
@@ -138,6 +142,12 @@ tools over newline-delimited JSON-RPC on stdio.
 
 | Tool | Command | |
 | --- | --- | --- |
+| `miakapp_pair` | `pair` | stores a new context; the code is a tool argument |
+| `miakapp_context_list` | `context list` | read-only, offline |
+| `miakapp_context_show` | `context show` | read-only, offline |
+| `miakapp_context_use` | `context use` | offline, changes the current context |
+| `miakapp_context_remove` | `context remove` | **deletes a stored key — needs `confirm: true`** |
+| `miakapp_status` | `status` | read-only |
 | `miakapp_discover` | `discover` | read-only, offline |
 | `miakapp_check` | `check` | read-only, offline |
 | `miakapp_release` | `release` | read-only |
@@ -154,7 +164,8 @@ drift apart. A tool argument is the option name with `_` for `-`
 (`expected_generation` → `--expected-generation`); an argument the tool does not
 declare is refused rather than ignored.
 
-The three pointer-moving tools additionally require `confirm: true`. It is
+The three pointer-moving tools and `miakapp_context_remove` additionally
+require `confirm: true`. It is
 checked before anything else and never reaches the command line, so a model that
 hallucinated a publication spends the mistake on an argument check instead of on
 a generation.
@@ -165,20 +176,69 @@ remedy — not as a JSON-RPC error. That distinction matters: a protocol error
 means the call never happened, while a publication that reached the control
 plane and failed did happen, and only `kind` says whether to reconcile.
 
-## Authorization
+## Access: pairing and contexts
 
-The Home Key is read from `MIAKAPP_HOME_KEY` and from nowhere else. No command
-accepts it as an argument, because an argument lands in shell history, in a
-process listing and in most CI logs.
+The owner grants access in their own browser; the agent never signs in. They
+open `https://miakapp.com/pair`, choose the home, confirm, and send the
+one-time code, which `pair` trades for a **new, separately revocable** Home Key:
 
 ```bash
-export MIAKAPP_HOME_KEY="$(op read op://home/miakapp/home-key)"   # or your own vault
-bunx @miakapp/cli publish --expected-generation 4
+printf '%s\n' "$CODE" | miakapp pair      # or run it in a terminal: hidden prompt
+miakapp pair --code "$CODE"               # allowed, but lands in shell history
 ```
 
-The key is exchanged for a five-minute `components:publish` token before every
-run. Publication endpoints never accept the Home Key itself, and the CLI never
-prints either credential.
+| Option | Default |
+| --- | --- |
+| `--issuer <https url>` | `https://control.miakapp.com` |
+| `--label <label>` | `miakapp-cli@<host name>`, shown in the owner's key list |
+| `--name <context>` | the paired home ID (`-2`, `-3`… if taken) |
+
+Before the code is sent, the issuer must serve a discovery document naming
+exactly itself; redirects are refused. The redeem response —
+`POST {issuer}/v1/pairing/redeem` with `{code, label}`, answered with
+`{home_key, home_id, key_id, issuer}` and `Cache-Control: no-store` — must name
+the same issuer and a key whose ID is embedded in the key. The code is sent
+once and never retried: a lost response is exit 7, because a key may exist.
+`pair` then exchanges the key for a publication token, reported as
+`publish_access`, so a key without the publish scope is caught now rather than
+at the first publication.
+
+Contexts live in `~/.miakapp` (or `$MIAKAPP_CONFIG_DIR`, absolute):
+
+| File | Holds | Mode |
+| --- | --- | --- |
+| `config.json` | context names, home IDs, issuers, key IDs, labels, current context | 0600 |
+| `credentials.json` | the Home Keys, nothing else | 0600 |
+
+The directory is 0700. Both files are replaced through a temporary file, an
+fsync and a rename, under a lock file, so concurrent runs never lose a context
+and a crash never leaves half a file. A credentials file readable by another
+account, a symbolic link, a foreign owner or a key that is not the one the
+context was paired with is refused rather than used.
+
+```bash
+miakapp context list
+miakapp context show [name]     # credential: stored (never printed)
+miakapp context use <name>
+miakapp context remove <name>   # local only: the owner revokes the key server-side
+```
+
+Which Home Key a command uses, highest precedence first:
+
+1. `--context <name>`, then `MIAKAPP_CONTEXT=<name>`;
+2. `MIAKAPP_HOME_KEY` — a raw key, kept for CI and compatibility;
+3. the stored context whose home and issuer match `miakapp.yaml`, the current
+   context breaking a tie between keys for that same home.
+
+A selected context for another home — or a `MIAKAPP_HOME_KEY` this machine
+knows was paired with another home — is refused before any request, so a key
+can never publish into the wrong house. Every networked result reports
+`credential_source` and `context`, never the key.
+
+No command accepts a Home Key as an argument: an argument lands in shell
+history, in a process listing and in most CI logs. The key is exchanged for a
+five-minute `components:publish` token before every run, and publication
+endpoints never see the Home Key itself.
 
 ## Generations
 
@@ -187,11 +247,11 @@ believe the pointer holds, and `--generation` (default: expected + 1) is the one
 you are publishing. A stale expectation fails with `generation_conflict` and
 exit code 6 rather than last-write-wins.
 
-`--expected-generation` is required rather than discovered, because RFC 0004
-§13.2 publishes no read for the current pointer: the pointer lives in
-`components/{homeID}` and reaches clients as authenticated platform data. Until
-that surface exists, the CLI asks you for the number instead of guessing one —
-inventing an endpoint would be worse than an explicit flag.
+Without `--expected-generation`, `publish` and `activate` read the live pointer
+first (`GET /v1/homes/{homeId}/component-pointer`, RFC 0004 §13.2) and use its
+generation. That read takes no lock, so the activation is still a
+compare-and-set: a publication that lands in between makes this one fail with
+exit 6, never overwrites it. `miakapp status` prints the same read.
 
 ## Exit codes
 
@@ -213,14 +273,14 @@ committed, so the next step is a read — `miakapp upload <id>` or
 ## Failure output
 
 ```console
-$ miakapp publish --expected-generation 0
+$ miakapp publish
 miakapp: conflict: Activation failed with HTTP 409 generation_conflict (request Zq1...)
   Another publication advanced the pointer. Read the active generation and retry
   the activation with the observed expected_generation.
 ```
 
 ```console
-$ miakapp publish --expected-generation 0 --json
+$ miakapp publish --json
 {"ok":false,"kind":"conflict","exit_code":6,"message":"...","remedy":"..."}
 ```
 
diff --git a/packages/cli/assets/agent-guide.md b/packages/cli/assets/agent-guide.md
index 6c0f1ce..a65a009 100644
--- a/packages/cli/assets/agent-guide.md
+++ b/packages/cli/assets/agent-guide.md
@@ -10,6 +10,42 @@ Everything below is true of the code in this repository. Where a rule exists for
 a reason that is not obvious, the reason is given, because a rule whose purpose
 you cannot see is one you will optimize away.
 
+## 0. What "done" means
+
+The owner asked for a home they can use, not for a picture of one. You are done
+when the household can open the published interface, read real values from it
+and use every control the owner authorized — and you checked that yourself.
+Concretely:
+
+- **Publish, then verify.** A build that only runs on your machine, a mockup, a
+  prototype kept offline or a screenshot is an intermediate result, never the
+  deliverable. Do not stop to show one and ask whether to continue: the owner
+  asked for the home, and publication is reversible in one command (§8).
+- **Hand over a link that works.** Give the owner the Miakapp app address where
+  the home appears for its members, and say what you verified there. The `url`
+  that `miakapp publish` prints is the raw component bytes, not an interface:
+  never send it as "the link". If you cannot open the app yourself, say exactly
+  that, and what `miakapp status` proved instead.
+- **Ask once, at the start, and only for what you cannot find.** Access comes
+  from pairing (§9), the existing installation from inventory (§3). Repeated
+  permission questions in the middle of the work are a failure of the work.
+- **You need nothing from the platform's source.** This guide, the CLI, the
+  public packages and `templates/home` are the whole toolchain. Never edit or
+  redeploy the Miakapp platform to make one house work; if a capability is
+  missing, report it to the owner as missing instead of patching around it.
+
+Two scopes must not be confused:
+
+| In scope by default | Needs the owner's explicit, separate request |
+| --- | --- |
+| reading the existing installation (§3) | changing flows, automations, brokers or devices that already run the house |
+| writing and testing a coordinator and a component | granting a physical action (heat, lock, unlock, open, close) that the owner has not named |
+| publishing, verifying and rolling back the V4 interface | anything on the owner's own machines beyond the coordinator you were asked to run |
+
+Caution about the second column is not a reason to withhold the first. A new V4
+interface that only reads is still a useful, publishable V1; say plainly which
+controls are not offered and why.
+
 ## 1. What you are building
 
 Three artifacts, and no more:
@@ -94,6 +130,37 @@ Write down what you found before you write the configuration. The state paths yo
 choose become a disclosure boundary and a public interface at the same time, and
 renaming one after the household has used it is not free.
 
+### The inventory comes before the design
+
+Commit the inventory as `docs/inventory.md` in the home repository, one line per
+datum or action, before you design a single screen:
+
+| Field | Example |
+| --- | --- |
+| source | `zigbee2mqtt/salon_thermo` over the house broker |
+| what it is | temperature, °C, one decimal |
+| how fresh | reports every ~60 s; last seen 2 min ago |
+| who may read it | every member / owner only |
+| command | none — a measurement, not a control |
+
+Then design **from** it: the V1 shows every datum the household would care
+about and every action that is both technically possible and authorized,
+grouped the way people live in the house — by room or by use, not by device
+or protocol. Anything you leave out, leave out on purpose, and say why in the
+inventory. A V1 that shows three values when the house reports twenty is not a
+first version; it is an unfinished one.
+
+What the interface must never do:
+
+- **invent data.** A value with no source is shown as absent, never filled in
+  with a plausible number or a demo fixture;
+- **blur freshness.** Distinguish *current*, *stale* (with its age) and
+  *unavailable* for every value, in words a resident understands;
+- **spend space on plumbing.** No protocol or platform vocabulary
+  (`ACCEPTED`, "relay connected", ABI, schema names, IDs), no banner restating
+  that a view is read-only, no title repeating the home's name on every card.
+  Every line of text is either information or an action.
+
 ### Reading a V3 house you inherited
 
 Most houses arriving at V4 already run Node-RED with the v3 MiakAPI nodes. Ask
@@ -305,25 +372,34 @@ writes no history, rewrites no source it did not generate, and invents no
 control-plane endpoint. The repository is the owner's.
 
 ```bash
-miakapp agent-pack                                             # once, per repository
-miakapp init --home <homeId> --control-plane <https url>
+miakapp docs start                             # this guide, from the installed CLI
+miakapp pair                                   # once per home and machine (§9)
+miakapp agent-pack                             # once, per repository
+miakapp init                                   # home and issuer come from the paired context
 miakapp check
-miakapp publish  --expected-generation <n>
-miakapp activate --sha256 <digest> --expected-generation <n>
-miakapp rollback --sha256 <digest> --expected-generation <n>   # alias of activate
+miakapp status                                 # what is live now: generation, release, digest
+miakapp publish                                # upload, finalize, activate
+miakapp status                                 # verify the new digest is what is live
+miakapp activate --sha256 <digest>             # promote an already finalized digest
+miakapp rollback --sha256 <digest>             # alias of activate
 miakapp release <sha256>      # read one finalized release
 miakapp upload  <uploadId>    # reconcile a lost request
 ```
 
-`--expected-generation` is a compare-and-swap on the home's component pointer: the
-generation you believe it currently holds. It is `0` for a home that has never
-published. It is required, and it is what stops two agents from silently
-overwriting each other.
+Activation is a compare-and-set on the home's component pointer. Without
+`--expected-generation` the CLI reads the live generation first and activates
+the next one; the read takes no lock, so another publication landing in between
+still fails with `conflict` instead of being overwritten. Pass
+`--expected-generation <n>` when you want to assert the state you reviewed.
 
 Rollback is `activate` pointed at a digest you already trust. Keep the digest of
 every release you shipped; a rollback you can perform in one command is worth
 more than an incident you can explain.
 
+`miakapp status` after `publish` is the minimum verification: the live `sha256`
+must be the one you just built. It proves what the home runs, not that the
+interface is right — open it as a member would before telling the owner it works.
+
 ### Driving the CLI as a program
 
 Every failure maps to exactly one stable exit code and one stable
@@ -366,22 +442,68 @@ Three differences are worth knowing before you call anything:
 `packages/cli/README.md` lists the tools. The exit codes above are the
 `exit_code` field in every result, so branch on the same table either way.
 
-## 9. Secrets
+## 9. Access: pairing and contexts
+
+You never sign in as the owner and never ask for a password, a Google login or
+an existing key. The owner grants access to one home, in their own browser:
 
-`MIAKAPP_HOME_KEY` comes from the environment. It is never a command-line
-argument, never printed, never written into a project file. No command accepts
-one, deliberately: an argument lands in shell history, in a process listing and
-in most CI logs.
+1. Ask the owner to open **https://miakapp.com/pair**, sign in to their own
+   account, choose the home (or create it), confirm the access it grants, and
+   send you the one-time code it shows. A code works once, for ten minutes.
+2. Redeem it. The code is read from stdin and never echoed:
+
+   ```bash
+   printf '%s\n' "<code>" | miakapp pair            # add --issuer <url> if the page shows one
+   ```
+
+   Over MCP, call `miakapp_pair` with `code`. Never repeat the code back in a
+   message, and never retry a refused code — ask for a new one.
+3. `pair` stores a **new, separately revocable** Home Key for this machine as a
+   context in `~/.miakapp`, keeps every other context, makes the new one
+   current, and proves the key can publish. It prints the key ID and label,
+   never the key.
 
 ```bash
-export MIAKAPP_HOME_KEY="$(your-secret-manager read miakapp/home-key)"
+miakapp context list          # every home this machine can publish to
+miakapp context show [name]   # one context; the key is never printed
+miakapp context use <name>    # make a context current
+miakapp context remove <name> # delete it locally (the owner revokes it server-side)
 ```
 
-If you are about to write a secret into `miakapp.yaml` so something works, stop:
-that is the failure this design exists to prevent.
+`~/.miakapp/config.json` holds names, homes, issuers and key IDs;
+`credentials.json` holds the keys. Both are mode 0600 in a 0700 directory and
+are replaced atomically; the CLI refuses a credentials file other accounts can
+read. `MIAKAPP_CONFIG_DIR` relocates the directory.
+
+Which key a command uses, highest precedence first:
+
+1. `--context <name>`, then `MIAKAPP_CONTEXT=<name>`;
+2. `MIAKAPP_HOME_KEY`, a raw key for CI and compatibility;
+3. the stored context paired with the home and issuer in `miakapp.yaml` — the
+   current context breaks a tie between two keys for that same home.
+
+A context, or a known key, for a different home than `miakapp.yaml` names is
+refused before any request: a key can never publish into the wrong house.
+
+Prefer one key per agent or machine, so the owner can revoke one without
+breaking the others. A coordinator running on the owner's machine still reads
+its own key from its environment (`templates/home/README.md`).
+
+If you are about to write a secret into `miakapp.yaml` or any file in the
+repository so something works, stop: that is the failure this design exists to
+prevent.
 
 ## 10. Before you tell the owner you are done
 
+- [ ] `docs/inventory.md` lists every source, datum and action you found, and
+      the interface covers it or says why not.
+- [ ] Every value shows whether it is current, stale or unavailable; nothing is
+      invented, and no technical vocabulary is on screen.
+- [ ] The interface is published, `miakapp status` shows your digest live, and
+      you opened it as a member would — or you say precisely what you could not
+      check.
+- [ ] The owner received a working link and the rollback digest, not a
+      screenshot or a mockup.
 - [ ] Every physically consequential function authorizes its caller on its first
       line, and a test proves an unauthorized caller is refused.
 - [ ] Every name in `miakapp.yaml` is covered by the coordinator, and a test
@@ -390,11 +512,16 @@ that is the failure this design exists to prevent.
 - [ ] No call path retries an unknown outcome.
 - [ ] State is written before its event is published.
 - [ ] `bun run check` is green, and CI ran it — not just you.
-- [ ] The Home Key exists only in the environment.
+- [ ] The Home Key exists only in `~/.miakapp` or the environment, never in the
+      repository.
 - [ ] You recorded the digest of what you published, so rollback is one command.
 
 ## Where to read further
 
+Everything a home needs is above, in the CLI and in the template. The RFCs and
+platform paths below explain *why* the platform behaves as it does; you never
+need them, or the platform repository, to build and publish a home.
+
 - `packages/cli/README.md` — every command and every tool, including what the
   pack writes and what it refuses to overwrite.
 - `templates/home/README.md` — the mechanics of the template itself.
diff --git a/packages/cli/src/agent-pack.ts b/packages/cli/src/agent-pack.ts
index 4663196..e502253 100644
--- a/packages/cli/src/agent-pack.ts
+++ b/packages/cli/src/agent-pack.ts
@@ -119,9 +119,12 @@ inventory an existing installation, validate the project, publish, and roll back
 The same commands exist as \`${SERVER_NAME}\` on the command line; they are one
 implementation, so neither surface can drift from the other.
 
-Three rules the guide explains and this file repeats because getting them wrong
+Four rules the guide explains and this file repeats because getting them wrong
 is expensive:
 
+- Done means published and verified: inventory the house first, publish a V1
+  that covers the real data, check \`${SERVER_NAME} status\`, open it as a member
+  would, and hand the owner a working link — never a screenshot or a mockup.
 - \`publish\`, \`activate\` and \`rollback\` change what every device in the home
   runs. Over MCP they refuse to act without \`confirm: true\`. Set it when the
   owner asked for that publication, never to get past an error.
@@ -129,8 +132,10 @@ is expensive:
   \`conflict\` means re-read the pointer; \`unknown_outcome\` means the effect is
   undetermined — reconcile with \`${SERVER_NAME} release\` or \`${SERVER_NAME} upload\`
   before acting again, and never retry it.
-- The Home Key lives in \`MIAKAPP_HOME_KEY\` in the environment. No command
-  accepts it as an argument, and it belongs in no file in this repository.
+- Access comes from \`${SERVER_NAME} pair\`: the owner confirms the home at
+  https://miakapp.com/pair and sends a one-time code; never ask for a login or
+  a key. Keys live in \`~/.miakapp\` (or \`MIAKAPP_HOME_KEY\` for CI), never in
+  this repository and never in a command argument.
 ${END_MARKER}`;
 }
 
diff --git a/packages/cli/test/agent-pack.test.ts b/packages/cli/test/agent-pack.test.ts
index 82ed261..16c61aa 100644
--- a/packages/cli/test/agent-pack.test.ts
+++ b/packages/cli/test/agent-pack.test.ts
@@ -14,7 +14,7 @@ import {
   serverEntry,
 } from '../src/agent-pack.js';
 import { EXIT_CODE } from '../src/errors.js';
-import { guideAssetPath, run } from '../src/main.js';
+import { COMMAND_OPTIONS, guideAssetPath, run } from '../src/main.js';
 import { TOOLS, buildArgv } from '../src/mcp.js';
 import { CLI_VERSION, PACKAGE_NAME } from '../src/version.js';
 import { MemoryFiles, PROJECT_ROOT, testHost } from './support/host.js';
@@ -230,6 +230,14 @@ describe('the block tells an agent what it must not get wrong', () => {
     expect(block).toContain('unknown_outcome');
   });
 
+  test('it sends the agent through pairing and to a verified publication', () => {
+    const block = instructionBlock('Codex');
+    expect(block).toContain('miakapp pair');
+    expect(block).toContain('https://miakapp.com/pair');
+    expect(block).toContain('miakapp status');
+    expect(block).toContain('never a screenshot');
+  });
+
   test('each instruction file names the client that reads it', () => {
     for (const { path, client } of INSTRUCTION_FILES) {
       expect([path, instructionBlock(client).includes(client)]).toEqual([path, true]);
@@ -249,6 +257,25 @@ describe('the packaged guide is the repository guide', () => {
     expect(shipped.equals(source)).toBe(true);
   });
 
+  test('the guide teaches every command an agent can run', async () => {
+    const guide = (await readFile(await guideAssetPath())).toString('utf8');
+    const commands = Object.keys(COMMAND_OPTIONS).filter((name) => !['help', 'version'].includes(name));
+    for (const command of commands) {
+      expect([command, guide.includes(`miakapp ${command}`)]).toEqual([command, true]);
+    }
+    for (const action of ['list', 'show', 'use', 'remove']) {
+      expect([action, guide.includes(`miakapp context ${action}`)]).toEqual([action, true]);
+    }
+  });
+
+  test('the guide makes a verified publication the deliverable', async () => {
+    const guide = (await readFile(await guideAssetPath())).toString('utf8');
+    expect(guide).toContain('docs/inventory.md');
+    expect(guide).toContain('https://miakapp.com/pair');
+    expect(guide).toMatch(/screenshot/);
+    expect(guide).toContain('You need nothing from the platform');
+  });
+
   test('the guide is served as a tool and reaches the command as plain argv', () => {
     const tool = TOOLS.find((entry) => entry.name === 'miakapp_agent_pack');
     expect(tool?.command).toBe('agent-pack');
diff --git a/templates/home/README.md b/templates/home/README.md
index 890739b..fe9db8d 100644
--- a/templates/home/README.md
+++ b/templates/home/README.md
@@ -39,21 +39,32 @@ To run the coordinator against a real home:
 
 ```bash
 export MIAKAPP_COORDINATOR_NAME=living-room
-export MIAKAPP_CONTROL_PLANE_EXCHANGE_ENDPOINT=https://control.miakapp.app/v1/access-tokens:exchange
+export MIAKAPP_CONTROL_PLANE_EXCHANGE_ENDPOINT=https://control.miakapp.com/v1/access-tokens:exchange
 export MIAKAPP_OWNER_USER_ID=<your Firebase UID>
 export MIAKAPP_HOME_KEY="$(your-secret-manager read miakapp/home-key)"
 bun run dev
 ```
 
-The Home Key is read from the environment and never written to a file in this
-project. Publishing reads the same variable:
+The coordinator's Home Key is read from its environment and never written to a
+file in this project. Give the coordinator its own key, separate from the one
+you publish with, so either can be revoked alone.
+
+Publishing uses the key `miakapp pair` stored for this home in `~/.miakapp` —
+the owner confirms the home at https://miakapp.com/pair and sends you a
+one-time code — or `MIAKAPP_HOME_KEY` in CI:
 
 ```bash
-bun run publish:home        # bundles, then publishes at generation 1
+printf '%s\n' "<code>" | miakapp pair   # once per home and machine
+bun run publish:home                    # bundles, then publishes the next generation
+miakapp status                          # verify the new digest is live
 ```
 
-`--expected-generation` is the generation you believe the home's component
-pointer currently holds. It is `0` for a home that has never published.
+`miakapp.yaml` names the home. Replace `my-home` with the home ID `pair`
+printed (or write the file with `miakapp init`, which takes both values from
+the paired context); a key paired with another home is refused. The CLI reads
+the live generation before activating, and the activation stays a
+compare-and-set, so a concurrent publication fails with `conflict` instead of
+being overwritten.
 
 ## The one rule that ties the three files together
 
diff --git a/templates/home/miakapp.yaml b/templates/home/miakapp.yaml
index 31f5e77..fc71c3b 100644
--- a/templates/home/miakapp.yaml
+++ b/templates/home/miakapp.yaml
@@ -1,6 +1,6 @@
 schema: miakapp.project/1
 home: my-home
-control_plane: https://control.miakapp.app
+control_plane: https://control.miakapp.com
 
 component:
   artifact: dist/component.js
diff --git a/templates/home/package.json b/templates/home/package.json
index 063b5a9..5222b19 100644
--- a/templates/home/package.json
+++ b/templates/home/package.json
@@ -13,7 +13,7 @@
     "check": "bun run typecheck && bun run build && bun run test && bun run check:artifact",
     "check:artifact": "miakapp check",
     "dev": "bun run coordinator/main.ts",
-    "publish:home": "bun run build && miakapp publish --expected-generation 0",
+    "publish:home": "bun run build && miakapp publish",
     "test": "bun test test/",
     "typecheck": "tsc --noEmit"
   },

From d56dc4d432976403e228c78eb17cd4d97b1b6eae Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 04:20:28 +0200
Subject: [PATCH 3/7] fix(cli): name the symbolic-link refusal for the context
 directory

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/cli/src/contexts.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/cli/src/contexts.ts b/packages/cli/src/contexts.ts
index e7b63c4..3fbb3d5 100644
--- a/packages/cli/src/contexts.ts
+++ b/packages/cli/src/contexts.ts
@@ -334,7 +334,10 @@ async function ensureDirectory(directory: string): Promise<void> {
   await fs.mkdir(directory, { recursive: true, mode: 0o700 });
   const status = await fs.lstat(directory);
   if (!status.isDirectory()) {
-    throw authorizationError(`${directory} is not a directory`, 'Move it aside and run the command again.');
+    throw authorizationError(
+      `${directory} is not a directory (symbolic links are refused)`,
+      `Move it aside, or point ${CONFIG_DIRECTORY_VARIABLE} at the real directory.`,
+    );
   }
   if (enforcesModes()) {
     const uid = process.getuid?.();

From 3367ab38528b93010ceac886f6501bef5fb02b34 Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 05:10:01 +0200
Subject: [PATCH 4/7] feat(cli): publish whole-house applications
 (miakapp.app/1)

- miakapp.yaml takes exactly one of app: (miakapp.app/1, the new
  default) or component: (miakapp.component/1, unchanged). app.requires
  may declare only state_read and call; events, media and protocol-
  reserved miakapp.* functions are refused before any upload.
- publish sends the project's ABI and refuses a control plane that
  echoes another one at upload, finalization or activation; upload,
  release and pointer reads accept both ABIs.
- Discovery accepts the optional runtime_diagnostics_endpoint (checked
  to be under the issuer) and home_url_template (exactly
  <origin>/app?home={home_id}). publish/status/activate print home_url,
  the resident link, and the bundle as artifact_url; with no template
  home_url is null rather than invented.
- init --kind app|component, app by default (dist/app.js); the MCP
  tool exposes kind.
- New @miakapp/app package: typed window.miakapp, connect(), paths(),
  subscribe(), call() and the closed call error codes.
- templates/home: a DOM house app (own layout, CSS, hash routing, stale
  and outcome-unknown handling) bundled as one IIFE, with a tested view
  model; the semantic component stays buildable (build:component).
- Agent guide and agent-pack block default to whole-house apps, require
  handing over home_url and forbid household data in the bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 bun.lock                                   |  13 +-
 docs/agent-guide.md                        |  66 +++++++--
 package.json                               |   7 +-
 packages/app/LICENSE                       |  15 ++
 packages/app/README.md                     |  48 +++++++
 packages/app/package.json                  |  50 +++++++
 packages/app/src/index.ts                  | 156 +++++++++++++++++++++
 packages/app/test/app.test.ts              | 104 ++++++++++++++
 packages/app/tsconfig.build.json           |  18 +++
 packages/app/tsconfig.json                 |  32 +++++
 packages/cli/assets/agent-guide.md         |  66 +++++++--
 packages/cli/src/agent-pack.ts             |   8 +-
 packages/cli/src/control-plane.ts          |  43 +++++-
 packages/cli/src/internal/names.ts         |   9 ++
 packages/cli/src/main.ts                   |  74 ++++++++--
 packages/cli/src/mcp.ts                    |  13 +-
 packages/cli/src/project.ts                |  54 ++++++-
 packages/cli/src/publication.ts            |  38 +++--
 packages/cli/test/agent-pack.test.ts       |   4 +-
 packages/cli/test/app-publication.test.ts  | 137 ++++++++++++++++++
 packages/cli/test/main.test.ts             |  23 ++-
 packages/cli/test/support/control-plane.ts |  15 +-
 templates/home/app/main.ts                 | 109 ++++++++++++++
 templates/home/app/view.ts                 |  58 ++++++++
 templates/home/bun.lock                    |   3 +
 templates/home/miakapp.yaml                |  18 +--
 templates/home/package.json                |   8 +-
 templates/home/test/app.test.ts            |  39 ++++++
 templates/home/tsconfig.json               |   4 +-
 29 files changed, 1147 insertions(+), 85 deletions(-)
 create mode 100644 packages/app/LICENSE
 create mode 100644 packages/app/README.md
 create mode 100644 packages/app/package.json
 create mode 100644 packages/app/src/index.ts
 create mode 100644 packages/app/test/app.test.ts
 create mode 100644 packages/app/tsconfig.build.json
 create mode 100644 packages/app/tsconfig.json
 create mode 100644 packages/cli/test/app-publication.test.ts
 create mode 100644 templates/home/app/main.ts
 create mode 100644 templates/home/app/view.ts
 create mode 100644 templates/home/test/app.test.ts

diff --git a/bun.lock b/bun.lock
index cbaa9c1..d3ac0dc 100644
--- a/bun.lock
+++ b/bun.lock
@@ -15,9 +15,18 @@
         "typescript": "7.0.2",
       },
     },
+    "packages/app": {
+      "name": "@miakapp/app",
+      "version": "4.0.0-alpha.0",
+      "devDependencies": {
+        "@types/bun": "1.2.23",
+        "@types/node": "22.20.1",
+        "typescript": "7.0.2",
+      },
+    },
     "packages/cli": {
       "name": "@miakapp/cli",
-      "version": "4.0.0-alpha.3",
+      "version": "4.0.0-alpha.5",
       "bin": {
         "miakapp": "./bin/miakapp.js",
       },
@@ -38,6 +47,8 @@
     },
   },
   "packages": {
+    "@miakapp/app": ["@miakapp/app@workspace:packages/app"],
+
     "@miakapp/cli": ["@miakapp/cli@workspace:packages/cli"],
 
     "@miakapp/component": ["@miakapp/component@workspace:packages/component"],
diff --git a/docs/agent-guide.md b/docs/agent-guide.md
index a65a009..1687ea1 100644
--- a/docs/agent-guide.md
+++ b/docs/agent-guide.md
@@ -21,11 +21,12 @@ Concretely:
   prototype kept offline or a screenshot is an intermediate result, never the
   deliverable. Do not stop to show one and ask whether to continue: the owner
   asked for the home, and publication is reversible in one command (§8).
-- **Hand over a link that works.** Give the owner the Miakapp app address where
-  the home appears for its members, and say what you verified there. The `url`
-  that `miakapp publish` prints is the raw component bytes, not an interface:
-  never send it as "the link". If you cannot open the app yourself, say exactly
-  that, and what `miakapp status` proved instead.
+- **Hand over a link that works.** Give the owner the `home_url` that
+  `miakapp publish` and `miakapp status` print — the Miakapp address where the
+  home opens for its members — and say what you verified there. The
+  `artifact_url` (JSON `url`) is the raw bundle, not an interface: never send it
+  as "the link". If the control plane advertises no `home_url`, say so instead of
+  inventing one, and say what `miakapp status` proved.
 - **Ask once, at the start, and only for what you cannot find.** Access comes
   from pairing (§9), the existing installation from inventory (§3). Repeated
   permission questions in the middle of the work are a failure of the work.
@@ -53,10 +54,16 @@ Three artifacts, and no more:
 | Artifact | Where it runs | What it owns |
 | --- | --- | --- |
 | Coordinator | the owner's machine, under Bun | state, events, functions, **authorization** |
-| Component | a sandboxed Worker in the household's browser | the interface |
-| `miakapp.yaml` | neither; it is the contract | what the component may ask for |
+| Interface | an isolated frame (app) or sandboxed Worker (component) in the household's browser | what residents see and touch |
+| `miakapp.yaml` | neither; it is the contract | what the interface may ask for |
 
-The coordinator is trusted. The component is not. The relay between them is
+The interface is, by default, a **whole-house application** (`app:` in
+`miakapp.yaml`, ABI `miakapp.app/1`): your own layout, styles, navigation and
+libraries, bundled into one file. A semantic **component** (`component:`,
+`miakapp.component/1`) is still supported for a minimal tree Miakapp draws for
+you. §5 covers both.
+
+The coordinator is trusted. The interface is not. The relay between them is
 platform-untrusted but not blind: it terminates TLS, stores plaintext state and
 enforces routing, so self-hosting it does not give end-to-end confidentiality.
 Do not tell the owner otherwise.
@@ -247,7 +254,43 @@ The relay keeps ownership tables for topics, state paths and functions, detects
 collisions and rejects with `4409`. If you claim `lighting.set` for the whole
 house, you have taken a name another integration may need; scope what you own.
 
-## 5. The component
+## 5. The interface
+
+### A whole-house application (default)
+
+`miakapp init` writes an `app:` section; `templates/home/app/` is a working
+example. You own the document: build any DOM, ship your own CSS, route with
+`location.hash`, use React, Svelte, Vue, charts or WebAssembly — anything a
+bundler can inline. The deliverable is **one classic-script IIFE** of at most
+2 MiB, with no `import()` and no source map:
+
+```bash
+bun build app/main.ts --format=iife --minify --outfile dist/app.js
+```
+
+Miakapp runs it in an isolated, opaque-origin frame below a permanent Miakapp
+bar, after the resident agreed to open the home. The frame has no network, no
+cookies or storage, no popups and no fullscreen; assets go in the bundle as
+`data:`/`blob:` URLs. Its only way to the home is `@miakapp/app`:
+
+```ts
+import { callErrorCode, connect } from '@miakapp/app';
+
+const home = connect();
+home.subscribe((state) => render(state));        // also called once immediately
+await home.call('lighting.set', { on: true });   // rejects with a closed code
+```
+
+Declare every state path (exact or `prefix.*`) under `app.requires.state_read`
+and every function under `app.requires.call`. Events, media and `miakapp.*`
+functions are refused by `miakapp check`. Show `state.stale`, disable controls
+while it is true, and handle `outcome_unknown` exactly as below.
+
+**The bundle is not private.** Any signed-in user who learns its digest can
+fetch it. Put no household data in it — no names, rooms, devices or accounts —
+and read everything from state, which the coordinator filters per resident.
+
+### A semantic component (compatible)
 
 Import from `@miakapp/component`. The whole public surface is one module, and the
 whole rendering vocabulary is `ui.*`:
@@ -375,7 +418,7 @@ control-plane endpoint. The repository is the owner's.
 miakapp docs start                             # this guide, from the installed CLI
 miakapp pair                                   # once per home and machine (§9)
 miakapp agent-pack                             # once, per repository
-miakapp init                                   # home and issuer come from the paired context
+miakapp init                                   # app: by default; --kind component for a semantic tree
 miakapp check
 miakapp status                                 # what is live now: generation, release, digest
 miakapp publish                                # upload, finalize, activate
@@ -398,7 +441,8 @@ more than an incident you can explain.
 
 `miakapp status` after `publish` is the minimum verification: the live `sha256`
 must be the one you just built. It proves what the home runs, not that the
-interface is right — open it as a member would before telling the owner it works.
+interface is right — open its `home_url` as a member would before telling the
+owner it works.
 
 ### Driving the CLI as a program
 
diff --git a/package.json b/package.json
index 1ed23cb..c013d5b 100644
--- a/package.json
+++ b/package.json
@@ -34,15 +34,16 @@
     "check": "bun run typecheck && bun run build && bun run test && bun run smoke:node && bun run smoke:browser && bun run test:contract && bun run pack:check",
     "check:cli": "bun --filter @miakapp/cli check",
     "check:component": "bun --filter @miakapp/component check",
-    "check:packages": "bun run check:cli && bun run check:component && bun run check:template",
-    "check:template": "bun run build && bun --filter @miakapp/component build && bun --filter @miakapp/cli build && cd templates/home && rm -rf node_modules && bun install --frozen-lockfile && bun run check",
+    "check:packages": "bun run check:cli && bun run check:component && bun run check:app && bun run check:template",
+    "check:template": "bun run build && bun --filter @miakapp/component build && bun --filter @miakapp/app build && bun --filter @miakapp/cli build && cd templates/home && rm -rf node_modules && bun install --frozen-lockfile && bun run check",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "bun run check",
     "smoke:browser": "node scripts/check-browser-bundle.mjs",
     "smoke:node": "node test/node-smoke.mjs",
     "test": "bun test test/*.test.ts examples/*.test.ts packages/*/test/*.test.ts",
     "test:contract": "bun run build:contract && node scripts/check-contract.mjs",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check:app": "bun --filter @miakapp/app check"
   },
   "repository": {
     "type": "git",
diff --git a/packages/app/LICENSE b/packages/app/LICENSE
new file mode 100644
index 0000000..c5247b7
--- /dev/null
+++ b/packages/app/LICENSE
@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Mathieu Colmon
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
diff --git a/packages/app/README.md b/packages/app/README.md
new file mode 100644
index 0000000..167917a
--- /dev/null
+++ b/packages/app/README.md
@@ -0,0 +1,48 @@
+# @miakapp/app
+
+Typed SDK for a Miakapp **whole-house application** (`miakapp.app/1`).
+
+A house application is your home's own interface: any DOM, CSS, router or UI
+library, bundled as **one classic-script IIFE** and published with
+`miakapp publish`. Residents open it at the `home_url` the CLI prints. Miakapp
+runs it in an isolated frame — no network, no storage, no access to the
+resident's account or other homes — behind a consent screen and a permanent
+Miakapp bar. Its only window on the home is `window.miakapp`; this package
+types it.
+
+```ts
+import { callErrorCode, connect } from '@miakapp/app';
+
+const home = connect();
+
+home.subscribe((state) => {
+  document.body.dataset.stale = String(state.stale);
+  for (const path of home.paths('room')) {
+    // render home.get(path) however you like
+  }
+});
+
+async function setLight(on: boolean): Promise<void> {
+  try {
+    await home.call('lighting.set', { on });
+  } catch (error) {
+    // 'outcome_unknown' means the home may have acted: never retry, wait for state.
+    console.warn(callErrorCode(error));
+  }
+}
+```
+
+## Rules the shell enforces
+
+- Declare every state path (exact or `prefix.*`) and every call in
+  `miakapp.yaml` under `app.requires.state_read` and `app.requires.call`.
+  Events, media and `miakapp.*` functions are refused.
+- The coordinator still decides per resident: a path a resident may not see
+  never reaches the frame, and a call they may not make is refused.
+- Bundle everything (≤ 2 MiB): images and fonts as `data:`/`blob:`. No
+  `import()`, no source maps, no external URLs.
+- The artifact is public to signed-in users who know its digest. Put no
+  household data in it; read it from state.
+- Show `state.stale`; never present old values as current.
+
+Build with Bun: `bun build app/main.ts --format=iife --minify --outfile dist/app.js`.
diff --git a/packages/app/package.json b/packages/app/package.json
new file mode 100644
index 0000000..4f8a05b
--- /dev/null
+++ b/packages/app/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "@miakapp/app",
+  "version": "4.0.0-alpha.0",
+  "description": "Typed SDK for Miakapp whole-house applications (miakapp.app/1): granted state, calls and preferences inside the isolated house frame",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.2.23",
+    "node": ">=22.9"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test test/",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run build && bun run typecheck && bun run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Miakapp/MiakAPI.git",
+    "directory": "packages/app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "Miakapp",
+    "MiakAPI",
+    "app",
+    "smart-home",
+    "iframe"
+  ],
+  "author": "Mathieu Colmon",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/bun": "1.2.23",
+    "@types/node": "22.20.1",
+    "typescript": "7.0.2"
+  }
+}
diff --git a/packages/app/src/index.ts b/packages/app/src/index.ts
new file mode 100644
index 0000000..02d7cfd
--- /dev/null
+++ b/packages/app/src/index.ts
@@ -0,0 +1,156 @@
+/**
+ * Typed access to a Miakapp whole-house application's one window on its home.
+ *
+ * A `miakapp.app/1` release is a single classic-script bundle that owns its
+ * whole document: any DOM, CSS, router or UI library. It runs in an isolated
+ * opaque-origin frame with no network and no storage, and the trusted shell
+ * installs exactly one object before the bundle runs: `window.miakapp`. This
+ * package types that object and adds the few helpers every house needs, so a
+ * house reads state and calls functions without reaching for `any`.
+ *
+ * Nothing here grants anything. What the house may read and call is its
+ * release's `requires`, narrowed by the coordinator per resident; a path the
+ * resident may not see never reaches the frame.
+ */
+
+export const APP_ABI = 'miakapp.app/1' as const;
+
+export const CALL_ERROR_CODES = [
+  'denied',
+  'unavailable',
+  'failed',
+  'outcome_unknown',
+  'timeout',
+  'busy',
+] as const;
+
+/**
+ * Why a call did not complete. `outcome_unknown` means the home may have acted:
+ * never retry it, wait for the next state instead.
+ */
+export type CallErrorCode = (typeof CALL_ERROR_CODES)[number];
+
+export type Theme = 'system' | 'light' | 'dark';
+
+export interface HomeState {
+  readonly values: Readonly<Record<string, unknown>>;
+  readonly revision: number;
+  /** True when Miakapp no longer has a current view: show it, never hide it. */
+  readonly stale: boolean;
+}
+
+/** The object the trusted shell installs as `window.miakapp`. */
+export interface MiakappHost {
+  readonly abi: typeof APP_ABI;
+  readonly release: string;
+  readonly home: { readonly id: string; readonly name: string };
+  readonly locale: string;
+  readonly theme: string;
+  onThemeChange(listener: (theme: string) => void): () => void;
+  readonly state: {
+    get(path: string): unknown;
+    values(): Readonly<Record<string, unknown>>;
+    readonly revision: number;
+    readonly stale: boolean;
+    subscribe(listener: (state: HomeState) => void): () => void;
+  };
+  readonly can: { read(path: string): boolean; call(name: string): boolean };
+  call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<unknown>;
+  ready(): void;
+}
+
+export class MiakappUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MiakappUnavailableError';
+  }
+}
+
+export interface Home {
+  readonly id: string;
+  readonly name: string;
+  readonly release: string;
+  /** BCP 47 language of the resident, e.g. `fr`. */
+  readonly locale: string;
+  theme(): Theme;
+  onThemeChange(listener: (theme: Theme) => void): () => void;
+  /** The current granted view, immutable. */
+  state(): HomeState;
+  get<T = unknown>(path: string): T | undefined;
+  /** Granted paths, optionally under one dotted prefix, sorted. */
+  paths(prefix?: string): string[];
+  /**
+   * Calls `listener` with every new view. With `immediate` (the default) it is
+   * also called once now, so a render function can be the only listener.
+   */
+  subscribe(listener: (state: HomeState) => void, options?: { immediate?: boolean }): () => void;
+  canRead(path: string): boolean;
+  canCall(name: string): boolean;
+  /** Rejects with an error whose `callErrorCode()` is one of `CALL_ERROR_CODES`. */
+  call<T = unknown>(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<T>;
+  /** Lifts the shell's loading screen before the script finishes, if you want. */
+  ready(): void;
+}
+
+function theme(value: string): Theme {
+  return value === 'light' || value === 'dark' ? value : 'system';
+}
+
+function isHost(value: unknown): value is MiakappHost {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<MiakappHost>;
+  return candidate.abi === APP_ABI
+    && typeof candidate.call === 'function'
+    && typeof candidate.state === 'object'
+    && typeof candidate.state?.subscribe === 'function';
+}
+
+/**
+ * Connects to the home this frame was opened for. Throws when not running
+ * inside a Miakapp house frame — for example in a unit test or a plain browser
+ * tab — so a mistake fails loudly instead of rendering an empty home.
+ */
+export function connect(scope: { readonly miakapp?: unknown } = globalThis as { miakapp?: unknown }): Home {
+  const host = scope.miakapp;
+  if (!isHost(host)) {
+    throw new MiakappUnavailableError(
+      'window.miakapp is missing: this bundle runs only inside a Miakapp house frame',
+    );
+  }
+  const snapshot = (): HomeState => ({
+    values: host.state.values(),
+    revision: host.state.revision,
+    stale: host.state.stale,
+  });
+  return Object.freeze({
+    id: host.home.id,
+    name: host.home.name,
+    release: host.release,
+    locale: host.locale,
+    theme: () => theme(host.theme),
+    onThemeChange: (listener: (value: Theme) => void) => host.onThemeChange((value) => listener(theme(value))),
+    state: snapshot,
+    get: <T>(path: string) => host.state.get(path) as T | undefined,
+    paths: (prefix?: string) => Object.keys(host.state.values())
+      .filter((path) => prefix === undefined || path === prefix || path.startsWith(`${prefix}.`))
+      .sort(),
+    subscribe: (listener: (state: HomeState) => void, options: { immediate?: boolean } = {}) => {
+      const unsubscribe = host.state.subscribe(listener);
+      if (options.immediate ?? true) listener(snapshot());
+      return unsubscribe;
+    },
+    canRead: (path: string) => host.can.read(path),
+    canCall: (name: string) => host.can.call(name),
+    call: async <T>(name: string, args?: unknown, options?: { timeoutMs?: number }) => (
+      await host.call(name, args ?? null, options ?? {}) as T
+    ),
+    ready: () => host.ready(),
+  });
+}
+
+/** The closed reason a call failed, or undefined for anything else. */
+export function callErrorCode(error: unknown): CallErrorCode | undefined {
+  if (error === null || typeof error !== 'object' || !('code' in error)) return undefined;
+  const code = (error as { code: unknown }).code;
+  return (CALL_ERROR_CODES as readonly unknown[]).includes(code) ? code as CallErrorCode : undefined;
+}
diff --git a/packages/app/test/app.test.ts b/packages/app/test/app.test.ts
new file mode 100644
index 0000000..f6aa404
--- /dev/null
+++ b/packages/app/test/app.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  APP_ABI,
+  MiakappUnavailableError,
+  callErrorCode,
+  connect,
+  type HomeState,
+  type MiakappHost,
+} from '../src/index.js';
+
+/** A stand-in for the object the trusted shell's bootstrap installs. */
+function fakeHost(values: Record<string, unknown>, stale = false) {
+  let state: HomeState = { values, revision: 1, stale };
+  const listeners = new Set<(state: HomeState) => void>();
+  const calls: Array<{ name: string; args: unknown }> = [];
+  let ready = 0;
+  const host: MiakappHost = {
+    abi: APP_ABI,
+    release: 'r1',
+    home: { id: 'maison-a', name: 'Maison A' },
+    locale: 'fr',
+    theme: 'dark',
+    onThemeChange: () => () => undefined,
+    state: {
+      get: (path) => state.values[path],
+      values: () => state.values,
+      get revision() {
+        return state.revision;
+      },
+      get stale() {
+        return state.stale;
+      },
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    },
+    can: {
+      read: (path) => path.startsWith('room.'),
+      call: (name) => name === 'lighting.set',
+    },
+    call: async (name, args) => {
+      calls.push({ name, args });
+      if (name !== 'lighting.set') throw Object.assign(new Error('x'), { code: 'denied' });
+      return { applied: true };
+    },
+    ready: () => {
+      ready += 1;
+    },
+  };
+  return {
+    host,
+    calls,
+    readyCount: () => ready,
+    emit(next: HomeState) {
+      state = next;
+      for (const listener of listeners) listener(next);
+    },
+  };
+}
+
+describe('@miakapp/app', () => {
+  test('connects only inside a house frame', () => {
+    expect(() => connect({})).toThrow(MiakappUnavailableError);
+    expect(() => connect({ miakapp: { abi: 'miakapp.component/1' } })).toThrow(MiakappUnavailableError);
+  });
+
+  test('exposes the granted view, its paths and staleness', () => {
+    const reading = { kind: 'temperature', value: 21.5, unit: '°C', fresh: true };
+    const fake = fakeHost({ 'room.kitchen.temperature': reading, 'room.kitchen.humidity': 48, 'security.doors.front': false });
+    const home = connect({ miakapp: fake.host });
+    expect(home.name).toBe('Maison A');
+    expect(home.theme()).toBe('dark');
+    expect(home.get<typeof reading>('room.kitchen.temperature')).toEqual(reading);
+    expect(home.paths('room')).toEqual(['room.kitchen.humidity', 'room.kitchen.temperature']);
+    expect(home.paths('room.sal')).toEqual([]);
+    expect(home.canRead('security.doors.front')).toBe(false);
+
+    const seen: HomeState[] = [];
+    const stop = home.subscribe((state) => seen.push(state));
+    expect(seen).toHaveLength(1);
+    fake.emit({ values: {}, revision: 2, stale: true });
+    expect(seen[1]).toEqual({ values: {}, revision: 2, stale: true });
+    stop();
+    fake.emit({ values: {}, revision: 3, stale: false });
+    expect(seen).toHaveLength(2);
+  });
+
+  test('calls through the shell and reports the closed failure reason', async () => {
+    const fake = fakeHost({});
+    const home = connect({ miakapp: fake.host });
+    await expect(home.call('lighting.set', { on: true })).resolves.toEqual({ applied: true });
+    const failure = await home.call('door.unlock').catch((error: unknown) => error);
+    expect(callErrorCode(failure)).toBe('denied');
+    expect(callErrorCode(new Error('plain'))).toBeUndefined();
+    expect(fake.calls).toEqual([
+      { name: 'lighting.set', args: { on: true } },
+      { name: 'door.unlock', args: null },
+    ]);
+    home.ready();
+    expect(fake.readyCount()).toBe(1);
+  });
+});
diff --git a/packages/app/tsconfig.build.json b/packages/app/tsconfig.build.json
new file mode 100644
index 0000000..6103c93
--- /dev/null
+++ b/packages/app/tsconfig.build.json
@@ -0,0 +1,18 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "sourceMap": true,
+    "stripInternal": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}
diff --git a/packages/app/tsconfig.json b/packages/app/tsconfig.json
new file mode 100644
index 0000000..5a4e4e7
--- /dev/null
+++ b/packages/app/tsconfig.json
@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "types": [
+      "bun",
+      "node"
+    ],
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}
diff --git a/packages/cli/assets/agent-guide.md b/packages/cli/assets/agent-guide.md
index a65a009..1687ea1 100644
--- a/packages/cli/assets/agent-guide.md
+++ b/packages/cli/assets/agent-guide.md
@@ -21,11 +21,12 @@ Concretely:
   prototype kept offline or a screenshot is an intermediate result, never the
   deliverable. Do not stop to show one and ask whether to continue: the owner
   asked for the home, and publication is reversible in one command (§8).
-- **Hand over a link that works.** Give the owner the Miakapp app address where
-  the home appears for its members, and say what you verified there. The `url`
-  that `miakapp publish` prints is the raw component bytes, not an interface:
-  never send it as "the link". If you cannot open the app yourself, say exactly
-  that, and what `miakapp status` proved instead.
+- **Hand over a link that works.** Give the owner the `home_url` that
+  `miakapp publish` and `miakapp status` print — the Miakapp address where the
+  home opens for its members — and say what you verified there. The
+  `artifact_url` (JSON `url`) is the raw bundle, not an interface: never send it
+  as "the link". If the control plane advertises no `home_url`, say so instead of
+  inventing one, and say what `miakapp status` proved.
 - **Ask once, at the start, and only for what you cannot find.** Access comes
   from pairing (§9), the existing installation from inventory (§3). Repeated
   permission questions in the middle of the work are a failure of the work.
@@ -53,10 +54,16 @@ Three artifacts, and no more:
 | Artifact | Where it runs | What it owns |
 | --- | --- | --- |
 | Coordinator | the owner's machine, under Bun | state, events, functions, **authorization** |
-| Component | a sandboxed Worker in the household's browser | the interface |
-| `miakapp.yaml` | neither; it is the contract | what the component may ask for |
+| Interface | an isolated frame (app) or sandboxed Worker (component) in the household's browser | what residents see and touch |
+| `miakapp.yaml` | neither; it is the contract | what the interface may ask for |
 
-The coordinator is trusted. The component is not. The relay between them is
+The interface is, by default, a **whole-house application** (`app:` in
+`miakapp.yaml`, ABI `miakapp.app/1`): your own layout, styles, navigation and
+libraries, bundled into one file. A semantic **component** (`component:`,
+`miakapp.component/1`) is still supported for a minimal tree Miakapp draws for
+you. §5 covers both.
+
+The coordinator is trusted. The interface is not. The relay between them is
 platform-untrusted but not blind: it terminates TLS, stores plaintext state and
 enforces routing, so self-hosting it does not give end-to-end confidentiality.
 Do not tell the owner otherwise.
@@ -247,7 +254,43 @@ The relay keeps ownership tables for topics, state paths and functions, detects
 collisions and rejects with `4409`. If you claim `lighting.set` for the whole
 house, you have taken a name another integration may need; scope what you own.
 
-## 5. The component
+## 5. The interface
+
+### A whole-house application (default)
+
+`miakapp init` writes an `app:` section; `templates/home/app/` is a working
+example. You own the document: build any DOM, ship your own CSS, route with
+`location.hash`, use React, Svelte, Vue, charts or WebAssembly — anything a
+bundler can inline. The deliverable is **one classic-script IIFE** of at most
+2 MiB, with no `import()` and no source map:
+
+```bash
+bun build app/main.ts --format=iife --minify --outfile dist/app.js
+```
+
+Miakapp runs it in an isolated, opaque-origin frame below a permanent Miakapp
+bar, after the resident agreed to open the home. The frame has no network, no
+cookies or storage, no popups and no fullscreen; assets go in the bundle as
+`data:`/`blob:` URLs. Its only way to the home is `@miakapp/app`:
+
+```ts
+import { callErrorCode, connect } from '@miakapp/app';
+
+const home = connect();
+home.subscribe((state) => render(state));        // also called once immediately
+await home.call('lighting.set', { on: true });   // rejects with a closed code
+```
+
+Declare every state path (exact or `prefix.*`) under `app.requires.state_read`
+and every function under `app.requires.call`. Events, media and `miakapp.*`
+functions are refused by `miakapp check`. Show `state.stale`, disable controls
+while it is true, and handle `outcome_unknown` exactly as below.
+
+**The bundle is not private.** Any signed-in user who learns its digest can
+fetch it. Put no household data in it — no names, rooms, devices or accounts —
+and read everything from state, which the coordinator filters per resident.
+
+### A semantic component (compatible)
 
 Import from `@miakapp/component`. The whole public surface is one module, and the
 whole rendering vocabulary is `ui.*`:
@@ -375,7 +418,7 @@ control-plane endpoint. The repository is the owner's.
 miakapp docs start                             # this guide, from the installed CLI
 miakapp pair                                   # once per home and machine (§9)
 miakapp agent-pack                             # once, per repository
-miakapp init                                   # home and issuer come from the paired context
+miakapp init                                   # app: by default; --kind component for a semantic tree
 miakapp check
 miakapp status                                 # what is live now: generation, release, digest
 miakapp publish                                # upload, finalize, activate
@@ -398,7 +441,8 @@ more than an incident you can explain.
 
 `miakapp status` after `publish` is the minimum verification: the live `sha256`
 must be the one you just built. It proves what the home runs, not that the
-interface is right — open it as a member would before telling the owner it works.
+interface is right — open its `home_url` as a member would before telling the
+owner it works.
 
 ### Driving the CLI as a program
 
diff --git a/packages/cli/src/agent-pack.ts b/packages/cli/src/agent-pack.ts
index e502253..1258e64 100644
--- a/packages/cli/src/agent-pack.ts
+++ b/packages/cli/src/agent-pack.ts
@@ -107,8 +107,9 @@ export function instructionBlock(client: string): string {
 ## Miakapp
 
 This repository is a Miakapp home: a coordinator that runs on the owner's
-machine and owns state, events and authorization, and a component that runs
-sandboxed in the household's browser and owns nothing but the interface.
+machine and owns state, events and authorization, and an interface — by default
+a whole-house application bundled as one IIFE — that runs isolated in the
+household's browser and owns nothing but what residents see.
 
 **Read \`${GUIDE_FILE}\` before writing or publishing anything here.** It is the
 full guide, copied into this repository so it is readable offline, and it is the
@@ -124,7 +125,8 @@ is expensive:
 
 - Done means published and verified: inventory the house first, publish a V1
   that covers the real data, check \`${SERVER_NAME} status\`, open it as a member
-  would, and hand the owner a working link — never a screenshot or a mockup.
+  would, and hand the owner the printed \`home_url\` — never the artifact URL, a
+  screenshot or a mockup.
 - \`publish\`, \`activate\` and \`rollback\` change what every device in the home
   runs. Over MCP they refuse to act without \`confirm: true\`. Set it when the
   owner asked for that publication, never to get past an error.
diff --git a/packages/cli/src/control-plane.ts b/packages/cli/src/control-plane.ts
index 578a447..d9d380b 100644
--- a/packages/cli/src/control-plane.ts
+++ b/packages/cli/src/control-plane.ts
@@ -24,6 +24,38 @@ export interface Discovery {
   readonly userRelayExchangeEndpoint: string;
   readonly pushAudience: string;
   readonly componentsAudience: string;
+  /**
+   * `https://<trusted web origin>/app?home={home_id}` when the deployment
+   * declares where residents open homes. The only source of a `home_url`; the
+   * artifact `url` is never a resident link.
+   */
+  readonly homeUrlTemplate?: string;
+}
+
+const HOME_URL_SUFFIX = '/app?home={home_id}';
+
+/**
+ * Accepts exactly `<canonical https origin>/app?home={home_id}`: no path, no
+ * credentials, no port games, nothing a server could use to point residents
+ * somewhere else under a plausible-looking link.
+ */
+export function parseHomeUrlTemplate(value: unknown): string {
+  if (typeof value !== 'string' || !value.endsWith(HOME_URL_SUFFIX)) {
+    throw contractError('home_url_template is not <origin>/app?home={home_id}');
+  }
+  const origin = value.slice(0, -HOME_URL_SUFFIX.length);
+  canonicalHttpsUrl(origin, 'home_url_template origin');
+  if (new URL(origin).origin !== origin) {
+    throw contractError('home_url_template must be rooted at a bare origin');
+  }
+  return value;
+}
+
+/** The trusted resident link for a home, or null when discovery names none. */
+export function homeUrl(discovery: Pick<Discovery, 'homeUrlTemplate'>, homeId: string): string | null {
+  return discovery.homeUrlTemplate === undefined
+    ? null
+    : discovery.homeUrlTemplate.replace('{home_id}', encodeURIComponent(homeId));
 }
 
 export interface PublisherToken {
@@ -77,13 +109,19 @@ export async function fetchDiscovery(options: ControlPlaneOptions): Promise<Disc
     'user_relay_exchange_endpoint',
     'push_audience',
     'components_audience',
-  ]);
+  ], ['runtime_diagnostics_endpoint', 'home_url_template']);
   if (document.schema !== 'miakapp.control-plane-discovery/1') {
     throw contractError('Discovery document has an unsupported schema');
   }
   if (document.issuer !== issuer) {
     throw contractError('Discovery document advertises a different issuer');
   }
+  // Optional, but never unchecked: it is still a location under this issuer.
+  if (document.runtime_diagnostics_endpoint !== undefined
+    && canonicalHttpsUrl(document.runtime_diagnostics_endpoint, 'runtime_diagnostics_endpoint')
+      !== `${issuer}/v1/runtime-diagnostics`) {
+    throw contractError('runtime_diagnostics_endpoint is not under this issuer');
+  }
   return Object.freeze({
     issuer,
     jwksUri: canonicalHttpsUrl(document.jwks_uri, 'jwks_uri'),
@@ -94,6 +132,9 @@ export async function fetchDiscovery(options: ControlPlaneOptions): Promise<Disc
     ),
     pushAudience: canonicalHttpsUrl(document.push_audience, 'push_audience'),
     componentsAudience: canonicalHttpsUrl(document.components_audience, 'components_audience'),
+    ...(document.home_url_template === undefined
+      ? {}
+      : { homeUrlTemplate: parseHomeUrlTemplate(document.home_url_template) }),
   });
 }
 
diff --git a/packages/cli/src/internal/names.ts b/packages/cli/src/internal/names.ts
index 0ddcae3..0a95f6f 100644
--- a/packages/cli/src/internal/names.ts
+++ b/packages/cli/src/internal/names.ts
@@ -13,6 +13,15 @@ const PRESENTATION_HANDLE = /^media\.[^.]/;
 /** RFC 0002 §7.1 caps the artifact at 2 MiB decoded. */
 export const MAXIMUM_ARTIFACT_BYTES = 2_097_152;
 
+/** RFC 0002 semantic component and whole-house application (house-app ABI spec). */
+export const COMPONENT_ABI = 'miakapp.component/1';
+export const APP_ABI = 'miakapp.app/1';
+export type ReleaseAbi = typeof COMPONENT_ABI | typeof APP_ABI;
+
+export function isReleaseAbi(value: unknown): value is ReleaseAbi {
+  return value === COMPONENT_ABI || value === APP_ABI;
+}
+
 /** RFC 0002 §10 aborts tokenization beyond this program ceiling. */
 export const MAXIMUM_PROGRAM_TOKENS = 100_000;
 
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index d86beae..9974656 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -18,7 +18,7 @@ import { homedir, hostname } from 'node:os';
 import { installPack } from './agent-pack.js';
 import { CLI_VERSION } from './version.js';
 import { prepareArtifact, type Artifact } from './artifact.js';
-import { exchangePublisherToken, fetchDiscovery, homeKeyId } from './control-plane.js';
+import { exchangePublisherToken, fetchDiscovery, homeKeyId, homeUrl } from './control-plane.js';
 import {
   configDirectory,
   contextNameError,
@@ -221,7 +221,7 @@ export const COMMAND_OPTIONS: Record<string, readonly string[]> = {
   docs: [],
   pair: ['code', 'issuer', 'label', 'name'],
   context: [],
-  init: ['home', 'control-plane', 'artifact', 'release', 'context'],
+  init: ['home', 'control-plane', 'artifact', 'release', 'context', 'kind'],
   'agent-pack': ['dir'],
   discover: ['flows'],
   check: [],
@@ -535,7 +535,7 @@ async function publicationTarget(
   host: CliHost,
   invocation: Invocation,
   project: Project,
-): Promise<{ target: PublicationTarget; credential: Credential }> {
+): Promise<{ target: PublicationTarget; credential: Credential; homeUrl: string | null }> {
   const credential = await resolveCredential(host, invocation, project);
   const options = host.fetch === undefined ? {} : { fetch: host.fetch };
   const discovery = await fetchDiscovery({ issuer: project.issuer, ...options });
@@ -543,6 +543,7 @@ async function publicationTarget(
   return {
     target: { issuer: discovery.issuer, homeId: project.homeId, token: token.accessToken, ...options },
     credential,
+    homeUrl: homeUrl(discovery, project.homeId),
   };
 }
 
@@ -550,11 +551,18 @@ function requirementFields(requires: Requirements): readonly Field[] {
   return REQUIREMENT_KINDS.map((kind): Field => [`requires.${kind}`, requires[kind]]);
 }
 
+/**
+ * `home_url` is the link residents open — the trusted Miakapp shell for this
+ * home, from discovery — and the only link to hand a person. `url` stays the
+ * raw artifact the shell verifies and runs; it is printed as `artifact_url` so
+ * it is never mistaken for a page.
+ */
 function pointerResult(
   summary: string,
   pointer: ComponentPointer,
   credential: Credential,
   expectedGeneration: number | undefined,
+  residentUrl: string | null,
 ): CommandResult {
   return {
     summary,
@@ -564,15 +572,18 @@ function pointerResult(
         ? []
         : [['expected_generation', expectedGeneration] as Field]),
       ['home', pointer.homeId],
+      ['home_url', residentUrl ?? 'not advertised by this control plane'],
+      ['abi', pointer.abi],
       ['generation', pointer.generation],
       ['release', pointer.release],
       ['sha256', pointer.sha256],
       ['size', pointer.size],
-      ['url', pointer.url],
+      ['artifact_url', pointer.url],
       ...requirementFields(pointer.requires),
     ],
     json: {
       home_id: pointer.homeId,
+      home_url: residentUrl,
       generation: pointer.generation,
       release: pointer.release,
       abi: pointer.abi,
@@ -591,7 +602,25 @@ function projectTemplate(fields: {
   controlPlane: string;
   artifact: string;
   release: string;
+  kind: 'app' | 'component';
 }): string {
+  if (fields.kind === 'app') {
+    return `schema: ${PROJECT_SCHEMA}
+home: ${fields.home}
+control_plane: ${fields.controlPlane}
+
+# A whole-house application: one self-contained classic-script (IIFE) bundle
+# that draws its own interface in Miakapp's isolated frame. Every path read and
+# every function called must be declared; the coordinator still decides, per
+# resident, what each one may see and do.
+app:
+  artifact: ${fields.artifact}
+  release: ${fields.release}
+  requires:
+    state_read: []
+    call: []
+`;
+  }
   return `schema: ${PROJECT_SCHEMA}
 home: ${fields.home}
 control_plane: ${fields.controlPlane}
@@ -622,12 +651,17 @@ async function runInit(host: CliHost, invocation: Invocation): Promise<CommandRe
   if (!isRelease(release)) {
     throw usageError('--release must be 1..64 UTF-8 bytes without control characters');
   }
+  const kind = invocation.options.get('kind') ?? 'app';
+  if (kind !== 'app' && kind !== 'component') {
+    throw usageError('--kind must be app (whole-house application, default) or component');
+  }
   const target = await initTarget(host, invocation);
   const source = projectTemplate({
     home: target.home,
     controlPlane: target.controlPlane,
-    artifact: invocation.options.get('artifact') ?? 'dist/component.js',
+    artifact: invocation.options.get('artifact') ?? (kind === 'app' ? 'dist/app.js' : 'dist/component.js'),
     release,
+    kind,
   });
   // Parsed before it is written, so init can never emit a file check rejects.
   parseProject(root, source);
@@ -643,6 +677,7 @@ async function runInit(host: CliHost, invocation: Invocation): Promise<CommandRe
     json: {
       project: path,
       schema: PROJECT_SCHEMA,
+      kind,
       home_id: target.home,
       control_plane: target.controlPlane,
       context: target.context ?? null,
@@ -866,6 +901,7 @@ async function runCheck(host: CliHost, invocation: Invocation): Promise<CommandR
     fields: [
       ['home', project.homeId],
       ['control_plane', project.issuer],
+      ['abi', project.abi],
       ['release', project.release],
       ['artifact', project.artifactPath],
       ['sha256', artifact.sha256],
@@ -876,6 +912,7 @@ async function runCheck(host: CliHost, invocation: Invocation): Promise<CommandR
     json: {
       home_id: project.homeId,
       control_plane: project.issuer,
+      abi: project.abi,
       release: project.release,
       artifact: project.artifactPath,
       sha256: artifact.sha256,
@@ -894,10 +931,11 @@ async function runPublish(host: CliHost, invocation: Invocation): Promise<Comman
     throw usageError('--release must be 1..64 UTF-8 bytes without control characters');
   }
   const artifact = await loadArtifact(host, project);
-  const { target, credential } = await publicationTarget(host, invocation, project);
+  const { target, credential, homeUrl: residentUrl } = await publicationTarget(host, invocation, project);
   const { expectedGeneration, generation } = await resolveGenerations(target, plan);
   const { pointer } = await publish(target, artifact, {
     release,
+    abi: project.abi,
     requires: project.requires,
     expectedGeneration,
     generation,
@@ -907,6 +945,7 @@ async function runPublish(host: CliHost, invocation: Invocation): Promise<Comman
     pointer,
     credential,
     expectedGeneration,
+    residentUrl,
   );
 }
 
@@ -914,7 +953,7 @@ async function runActivate(host: CliHost, invocation: Invocation): Promise<Comma
   const sha256 = digestOption(invocation, 'sha256');
   const plan = generationPlan(invocation);
   const project = await loadProject(host, invocation);
-  const { target, credential } = await publicationTarget(host, invocation, project);
+  const { target, credential, homeUrl: residentUrl } = await publicationTarget(host, invocation, project);
   // Activation is checked against a readable finalized record first, so a typo
   // in a digest fails as an artifact error instead of spending a CAS attempt.
   const existing = await readRelease(target, sha256);
@@ -931,6 +970,7 @@ async function runActivate(host: CliHost, invocation: Invocation): Promise<Comma
     pointer,
     credential,
     expectedGeneration,
+    residentUrl,
   );
 }
 
@@ -997,13 +1037,24 @@ async function runUpload(host: CliHost, invocation: Invocation): Promise<Command
 
 async function runStatus(host: CliHost, invocation: Invocation): Promise<CommandResult> {
   const project = await loadProject(host, invocation);
-  const { target, credential } = await publicationTarget(host, invocation, project);
+  const { target, credential, homeUrl: residentUrl } = await publicationTarget(host, invocation, project);
   const { generation, pointer } = await readPointer(target);
   if (pointer === null) {
     return {
-      summary: `${project.homeId} has never activated a component (generation 0)`,
-      fields: [['home', project.homeId], ['generation', 0], ...credentialFields(credential)],
-      json: { home_id: project.homeId, generation, active: false, ...credentialJson(credential) },
+      summary: `${project.homeId} has never activated an interface (generation 0)`,
+      fields: [
+        ['home', project.homeId],
+        ['home_url', residentUrl ?? 'not advertised by this control plane'],
+        ['generation', 0],
+        ...credentialFields(credential),
+      ],
+      json: {
+        home_id: project.homeId,
+        home_url: residentUrl,
+        generation,
+        active: false,
+        ...credentialJson(credential),
+      },
     };
   }
   const result = pointerResult(
@@ -1011,6 +1062,7 @@ async function runStatus(host: CliHost, invocation: Invocation): Promise<Command
     pointer,
     credential,
     undefined,
+    residentUrl,
   );
   return { ...result, json: { ...result.json, active: true } };
 }
diff --git a/packages/cli/src/mcp.ts b/packages/cli/src/mcp.ts
index 9c4ee86..b143815 100644
--- a/packages/cli/src/mcp.ts
+++ b/packages/cli/src/mcp.ts
@@ -313,9 +313,16 @@ export const TOOLS: readonly ToolDefinition[] = [
     description:
       'Write miakapp.yaml in the project directory. Refuses to overwrite an existing one, so it '
       + 'is safe to call when unsure. home and control_plane default to the selected or current '
-      + 'context, so after miakapp_pair no identifier needs typing. Declares no requirements: '
-      + 'grant them one at a time, as the component earns them.',
+      + 'context, so after miakapp_pair no identifier needs typing. kind defaults to app: a '
+      + 'whole-house application you draw yourself (any DOM, CSS, framework) bundled as one IIFE. '
+      + 'Declares no requirements: grant them one at a time, as the interface earns them.',
     args: [
+      {
+        name: 'kind',
+        type: 'string',
+        required: false,
+        description: 'app (whole-house application, default) or component (semantic tree).',
+      },
       {
         name: 'home',
         type: 'string',
@@ -332,7 +339,7 @@ export const TOOLS: readonly ToolDefinition[] = [
         name: 'artifact',
         type: 'string',
         required: false,
-        description: 'Built artifact path. Defaults to dist/component.js.',
+        description: 'Built artifact path. Defaults to dist/app.js (app) or dist/component.js.',
       },
       {
         name: 'release',
diff --git a/packages/cli/src/project.ts b/packages/cli/src/project.ts
index a43be6d..0a04fc8 100644
--- a/packages/cli/src/project.ts
+++ b/packages/cli/src/project.ts
@@ -1,7 +1,14 @@
 import { isAbsolute, join, normalize, resolve, sep } from 'node:path';
 import { projectError } from './errors.js';
 import { canonicalHttpsUrl } from './internal/http.js';
-import { isHomeId, isRelease, type Requirements } from './internal/names.js';
+import {
+  APP_ABI,
+  COMPONENT_ABI,
+  isHomeId,
+  isRelease,
+  type ReleaseAbi,
+  type Requirements,
+} from './internal/names.js';
 import { canonicalRequirements } from './internal/requirements.js';
 import { parseYaml, type YamlMapping, type YamlValue } from './internal/yaml.js';
 
@@ -10,6 +17,8 @@ export const PROJECT_SCHEMA = 'miakapp.project/1';
 
 export interface Project {
   readonly root: string;
+  /** `miakapp.app/1` for an `app:` section, `miakapp.component/1` for `component:`. */
+  readonly abi: ReleaseAbi;
   readonly homeId: string;
   readonly issuer: string;
   readonly artifactPath: string;
@@ -51,9 +60,30 @@ export function resolveProjectPath(root: string, declared: unknown, label: strin
   return join(root, normalized);
 }
 
+/**
+ * The trusted shell brokers only state reads and calls to a whole-house
+ * application, and never a protocol-reserved `miakapp.*` function. Declaring
+ * anything else would publish a manifest the shell silently narrows, so it is
+ * refused here instead.
+ */
+function assertAppCeiling(requires: Requirements): void {
+  for (const kind of ['event_subscribe', 'event_publish', 'presentation'] as const) {
+    if (requires[kind].length > 0) {
+      throw projectError(
+        `app.requires.${kind} must be empty: the house shell brokers only state_read and call`,
+        'Read state and call functions; render media and react to changes from state.',
+      );
+    }
+  }
+  const reserved = requires.call.find((name) => name === 'miakapp.*' || name.startsWith('miakapp.'));
+  if (reserved !== undefined) {
+    throw projectError(`app.requires.call names the protocol-reserved function ${reserved}`);
+  }
+}
+
 export function parseProject(root: string, source: string): Project {
   const document = parseYaml(source);
-  exactKeys(document, ['schema', 'home', 'control_plane', 'component', 'coordinator'], PROJECT_FILE);
+  exactKeys(document, ['schema', 'home', 'control_plane', 'app', 'component', 'coordinator'], PROJECT_FILE);
   if (document.schema !== PROJECT_SCHEMA) {
     throw projectError(
       `${PROJECT_FILE} must declare schema: ${PROJECT_SCHEMA}`,
@@ -68,14 +98,25 @@ export function parseProject(root: string, source: string): Project {
   const issuer = canonicalHttpsUrl(document.control_plane, 'control_plane');
   if (issuer.endsWith('/')) throw projectError('control_plane must not have a trailing slash');
 
-  const component = mapping(document.component, 'component');
-  exactKeys(component, ['artifact', 'release', 'requires'], 'component');
+  const hasApp = document.app !== undefined && document.app !== null;
+  const hasComponent = document.component !== undefined && document.component !== null;
+  if (hasApp === hasComponent) {
+    throw projectError(
+      `${PROJECT_FILE} must declare exactly one of app (a whole-house application) or component`,
+      'Use app: for a resident interface you draw yourself; component: for a semantic tree.',
+    );
+  }
+  const section = hasApp ? 'app' : 'component';
+  const abi: ReleaseAbi = hasApp ? APP_ABI : COMPONENT_ABI;
+  const component = mapping(document[section], section);
+  exactKeys(component, ['artifact', 'release', 'requires'], section);
   if (!isRelease(component.release)) {
-    throw projectError('component.release must be 1..64 UTF-8 bytes without control characters');
+    throw projectError(`${section}.release must be 1..64 UTF-8 bytes without control characters`);
   }
   const requires = canonicalRequirements(
     component.requires === undefined || component.requires === null ? {} : component.requires,
   );
+  if (hasApp) assertAppCeiling(requires);
 
   let coordinatorEntry: string | undefined;
   if (document.coordinator !== undefined && document.coordinator !== null) {
@@ -86,9 +127,10 @@ export function parseProject(root: string, source: string): Project {
 
   return Object.freeze({
     root,
+    abi,
     homeId: document.home,
     issuer,
-    artifactPath: resolveProjectPath(root, component.artifact, 'component.artifact'),
+    artifactPath: resolveProjectPath(root, component.artifact, `${section}.artifact`),
     release: component.release,
     requires,
     coordinatorEntry,
diff --git a/packages/cli/src/publication.ts b/packages/cli/src/publication.ts
index c828471..555c04c 100644
--- a/packages/cli/src/publication.ts
+++ b/packages/cli/src/publication.ts
@@ -29,14 +29,18 @@ import {
   isHomeId,
   isRandomId,
   isRelease,
+  isReleaseAbi,
   isUploadToken,
+  type ReleaseAbi,
   REQUIREMENT_KINDS,
   type Requirements,
 } from './internal/names.js';
 import { canonicalRequirements, sameRequirements } from './internal/requirements.js';
 import type { Artifact } from './artifact.js';
 
-export const COMPONENT_ABI = 'miakapp.component/1';
+import { COMPONENT_ABI } from './internal/names.js';
+
+export { APP_ABI, COMPONENT_ABI } from './internal/names.js';
 
 /** RFC 0004 §13.2 expires an upload capability within fifteen minutes. */
 const MAXIMUM_CAPABILITY_LIFETIME_MS = 900_000;
@@ -54,7 +58,7 @@ export interface UploadState {
   readonly uploadId: string;
   readonly status: UploadStatus;
   readonly release: string;
-  readonly abi: string;
+  readonly abi: ReleaseAbi;
   readonly sha256: string;
   readonly size: number;
   readonly requires: Requirements;
@@ -63,7 +67,7 @@ export interface UploadState {
 
 export interface ComponentRelease {
   readonly release: string;
-  readonly abi: string;
+  readonly abi: ReleaseAbi;
   readonly sha256: string;
   readonly size: number;
   readonly requires: Requirements;
@@ -74,7 +78,7 @@ export interface ComponentPointer {
   readonly homeId: string;
   readonly generation: number;
   readonly release: string;
-  readonly abi: string;
+  readonly abi: ReleaseAbi;
   readonly url: string;
   readonly sha256: string;
   readonly size: number;
@@ -93,6 +97,8 @@ export interface PublicationTarget {
 
 export interface UploadRequest {
   readonly release: string;
+  /** Defaults to the semantic component ABI for compatibility. */
+  readonly abi?: ReleaseAbi;
   readonly requires: Requirements;
 }
 
@@ -271,12 +277,12 @@ function decodeUploadState(value: unknown): UploadState {
   if (!isRandomId(document.upload_id)) throw contractError('upload_id is invalid');
   if (!isRelease(document.release)) throw contractError('release is invalid');
   if (!isDigest(document.sha256)) throw contractError('sha256 is not a base64url SHA-256 digest');
-  if (document.abi !== COMPONENT_ABI) throw contractError('abi is not the supported ABI');
+  if (!isReleaseAbi(document.abi)) throw contractError('abi is not a supported ABI');
   return Object.freeze({
     uploadId: document.upload_id,
     status,
     release: document.release,
-    abi: COMPONENT_ABI,
+    abi: document.abi,
     sha256: document.sha256,
     size: positiveInteger(document.size, MAXIMUM_ARTIFACT_BYTES),
     requires: decodeRequirements(document.requires),
@@ -299,10 +305,10 @@ function decodeRelease(value: unknown): ComponentRelease {
   }
   if (!isRelease(document.release)) throw contractError('release is invalid');
   if (!isDigest(document.sha256)) throw contractError('sha256 is not a base64url SHA-256 digest');
-  if (document.abi !== COMPONENT_ABI) throw contractError('abi is not the supported ABI');
+  if (!isReleaseAbi(document.abi)) throw contractError('abi is not a supported ABI');
   return Object.freeze({
     release: document.release,
-    abi: COMPONENT_ABI,
+    abi: document.abi,
     sha256: document.sha256,
     size: positiveInteger(document.size, MAXIMUM_ARTIFACT_BYTES),
     requires: decodeRequirements(document.requires),
@@ -333,7 +339,7 @@ function decodePointer(value: unknown, target: PublicationTarget): ComponentPoin
   }
   if (!isRelease(document.release)) throw contractError('Pointer release is invalid');
   if (!isDigest(document.sha256)) throw contractError('Pointer sha256 is invalid');
-  if (document.abi !== COMPONENT_ABI) throw contractError('Pointer abi is not the supported ABI');
+  if (!isReleaseAbi(document.abi)) throw contractError('Pointer abi is not a supported ABI');
   const url = boundedString(document.url, 1, 2_048);
   if (url !== `${target.issuer}/v1/components/${document.sha256}.js`) {
     throw contractError('Pointer url is not the token-free control-plane artifact resource');
@@ -342,7 +348,7 @@ function decodePointer(value: unknown, target: PublicationTarget): ComponentPoin
     homeId: target.homeId,
     generation: document.generation,
     release: document.release,
-    abi: COMPONENT_ABI,
+    abi: document.abi,
     url,
     sha256: document.sha256,
     size: positiveInteger(document.size, MAXIMUM_ARTIFACT_BYTES),
@@ -362,7 +368,7 @@ export async function requestUpload(
   }
   const body = requestBody({
     release: request.release,
-    abi: COMPONENT_ABI,
+    abi: request.abi ?? COMPONENT_ABI,
     sha256: artifact.sha256,
     size: artifact.size,
     requires: request.requires,
@@ -569,12 +575,14 @@ export async function publish(
   },
 ): Promise<{ readonly release: ComponentRelease; readonly pointer: ComponentPointer }> {
   const requires = canonicalRequirements(request.requires);
-  const capability = await requestUpload(target, artifact, { release: request.release, requires });
+  const abi = request.abi ?? COMPONENT_ABI;
+  const capability = await requestUpload(target, artifact, { release: request.release, abi, requires });
   await deliverArtifact(target, capability, artifact);
   const state = await readUpload(target, capability.uploadId);
   if (state.sha256 !== artifact.sha256
     || state.size !== artifact.size
     || state.release !== request.release
+    || state.abi !== abi
     || !sameRequirements(state.requires, requires)) {
     throw contractError('Upload state does not match the tuple the capability was bound to');
   }
@@ -587,7 +595,7 @@ export async function publish(
   const release = state.status === 'finalized'
     ? await requireRelease(target, artifact.sha256)
     : await finalizeUpload(target, capability.uploadId);
-  if (release.sha256 !== artifact.sha256 || release.size !== artifact.size) {
+  if (release.sha256 !== artifact.sha256 || release.size !== artifact.size || release.abi !== abi) {
     throw contractError('Finalized release does not match the delivered artifact');
   }
   const pointer = await activateRelease(target, {
@@ -595,7 +603,9 @@ export async function publish(
     expectedGeneration: request.expectedGeneration,
     generation: request.generation,
   });
-  if (pointer.sha256 !== artifact.sha256 || !sameRequirements(pointer.requires, requires)) {
+  if (pointer.sha256 !== artifact.sha256
+    || pointer.abi !== abi
+    || !sameRequirements(pointer.requires, requires)) {
     throw contractError('Activated pointer does not match the published release');
   }
   return { release, pointer };
diff --git a/packages/cli/test/agent-pack.test.ts b/packages/cli/test/agent-pack.test.ts
index 16c61aa..dbd9b3a 100644
--- a/packages/cli/test/agent-pack.test.ts
+++ b/packages/cli/test/agent-pack.test.ts
@@ -235,7 +235,9 @@ describe('the block tells an agent what it must not get wrong', () => {
     expect(block).toContain('miakapp pair');
     expect(block).toContain('https://miakapp.com/pair');
     expect(block).toContain('miakapp status');
-    expect(block).toContain('never a screenshot');
+    expect(block).toContain('home_url');
+    expect(block).toContain('never the artifact URL');
+    expect(block).toContain('screenshot');
   });
 
   test('each instruction file names the client that reads it', () => {
diff --git a/packages/cli/test/app-publication.test.ts b/packages/cli/test/app-publication.test.ts
new file mode 100644
index 0000000..c292f90
--- /dev/null
+++ b/packages/cli/test/app-publication.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+
+import { fetchDiscovery, homeUrl, parseHomeUrlTemplate } from '../src/control-plane.js';
+import { EXIT_CODE } from '../src/errors.js';
+import { HOME_KEY_VARIABLE, run } from '../src/main.js';
+import { parseProject } from '../src/project.js';
+import { ISSUER, digestOf, fakeControlPlane, homeKey } from './support/control-plane.js';
+import { MemoryFiles, PROJECT_ROOT, testHost } from './support/host.js';
+
+const HOME_ID = 'test-home';
+const APP_SOURCE = '(function () { document.body.textContent = "maison"; })();\n';
+const APP_YAML = `schema: miakapp.project/1
+home: ${HOME_ID}
+control_plane: ${ISSUER}
+
+app:
+  artifact: dist/app.js
+  release: 2026-10-03.1
+  requires:
+    state_read:
+      - room.*
+      - security.*
+    call:
+      - lighting.set
+`;
+const TEMPLATE = 'https://app.example.test/app?home={home_id}';
+
+function appProject(yaml = APP_YAML): MemoryFiles {
+  return new MemoryFiles({
+    [`${PROJECT_ROOT}/miakapp.yaml`]: yaml,
+    [`${PROJECT_ROOT}/dist/app.js`]: APP_SOURCE,
+  });
+}
+
+describe('app manifest', () => {
+  test('selects the whole-house ABI and keeps prefix requirements', () => {
+    const project = parseProject(PROJECT_ROOT, APP_YAML);
+    expect(project.abi).toBe('miakapp.app/1');
+    expect(project.artifactPath).toBe(`${PROJECT_ROOT}/dist/app.js`);
+    expect(project.requires.state_read).toEqual(['room.*', 'security.*']);
+    expect(project.requires.call).toEqual(['lighting.set']);
+  });
+
+  test('refuses both or neither section, and anything the shell would not broker', () => {
+    const refused = [
+      APP_YAML.replace('app:', 'component:\n  artifact: a.js\n  release: x\napp:'),
+      APP_YAML.replace(/app:[\s\S]*/u, ''),
+      APP_YAML.replace('    call:', '    event_subscribe:\n      - door.opened\n    call:'),
+      APP_YAML.replace('    call:', '    presentation:\n      - media.camera\n    call:'),
+      APP_YAML.replace('      - lighting.set', '      - miakapp.join'),
+      APP_YAML.replace('      - lighting.set', '      - miakapp.*'),
+      APP_YAML.replace('  release: 2026-10-03.1', '  release: 2026-10-03.1\n  url: https://x'),
+    ];
+    for (const yaml of refused) expect(() => parseProject(PROJECT_ROOT, yaml)).toThrow();
+  });
+});
+
+describe('discovery home link', () => {
+  test('accepts exactly <origin>/app?home={home_id}', () => {
+    expect(parseHomeUrlTemplate(TEMPLATE)).toBe(TEMPLATE);
+    expect(homeUrl({ homeUrlTemplate: TEMPLATE }, 'maison-a')).toBe('https://app.example.test/app?home=maison-a');
+    expect(homeUrl({}, 'maison-a')).toBeNull();
+    for (const bad of [
+      'http://app.example.test/app?home={home_id}',
+      'https://app.example.test/x/app?home={home_id}',
+      'https://user@app.example.test/app?home={home_id}',
+      'https://app.example.test/app?home={home_id}&next=https://evil.example',
+      'https://app.example.test/v1/components/{home_id}.js',
+      'https://app.example.test/app?home=fixed',
+    ]) {
+      expect(() => parseHomeUrlTemplate(bad)).toThrow();
+    }
+  });
+
+  test('accepts the optional members a current control plane sends, and checks them', async () => {
+    const accepted = fakeControlPlane({
+      homeId: HOME_ID,
+      discoveryExtras: {
+        runtime_diagnostics_endpoint: `${ISSUER}/v1/runtime-diagnostics`,
+        home_url_template: TEMPLATE,
+      },
+    });
+    const discovery = await fetchDiscovery({ issuer: ISSUER, fetch: accepted.fetch });
+    expect(discovery.homeUrlTemplate).toBe(TEMPLATE);
+
+    const foreign = fakeControlPlane({
+      homeId: HOME_ID,
+      discoveryExtras: { runtime_diagnostics_endpoint: 'https://elsewhere.example/v1/runtime-diagnostics' },
+    });
+    await expect(fetchDiscovery({ issuer: ISSUER, fetch: foreign.fetch })).rejects.toThrow();
+    const unknown = fakeControlPlane({ homeId: HOME_ID, discoveryExtras: { surprise: 'x' } });
+    await expect(fetchDiscovery({ issuer: ISSUER, fetch: unknown.fetch })).rejects.toThrow();
+  });
+});
+
+describe('app publication', () => {
+  test('publishes miakapp.app/1 and prints the resident link apart from the artifact', async () => {
+    const plane = fakeControlPlane({ homeId: HOME_ID, generation: 0, discoveryExtras: { home_url_template: TEMPLATE } });
+    const host = testHost({ files: appProject(), fetch: plane.fetch, env: { [HOME_KEY_VARIABLE]: homeKey() } });
+    expect(await run(['publish', '--json'], host)).toBe(EXIT_CODE.success);
+    const result = host.json();
+    expect(result['abi']).toBe('miakapp.app/1');
+    expect(result['home_url']).toBe(`https://app.example.test/app?home=${HOME_ID}`);
+    const digest = digestOf(new TextEncoder().encode(APP_SOURCE));
+    expect(result['url']).toBe(`${ISSUER}/v1/components/${digest}.js`);
+    expect(result['home_url']).not.toBe(result['url']);
+    expect([...plane.uploads.values()][0]?.abi).toBe('miakapp.app/1');
+
+    const human = testHost({ files: appProject(), fetch: plane.fetch, env: { [HOME_KEY_VARIABLE]: homeKey() } });
+    expect(await run(['status'], human)).toBe(EXIT_CODE.success);
+    expect(human.stdout()).toContain(`home_url: https://app.example.test/app?home=${HOME_ID}`);
+    expect(human.stdout()).toContain('artifact_url: ');
+    expect(human.stdout()).not.toMatch(/^url:/mu);
+  });
+
+  test('says no resident link is advertised rather than inventing one', async () => {
+    const plane = fakeControlPlane({ homeId: HOME_ID, generation: 0 });
+    const host = testHost({ files: appProject(), fetch: plane.fetch, env: { [HOME_KEY_VARIABLE]: homeKey() } });
+    expect(await run(['publish', '--json'], host)).toBe(EXIT_CODE.success);
+    expect(host.json()['home_url']).toBeNull();
+  });
+
+  test('refuses a control plane that echoes another ABI', async () => {
+    const plane = fakeControlPlane({ homeId: HOME_ID, generation: 0 });
+    const original = plane.fetch;
+    const tampering = async (input: string, init: RequestInit) => {
+      if (init.method === 'POST' && input.endsWith('/component-uploads')) {
+        const body = JSON.parse(String(init.body)) as Record<string, unknown>;
+        return await original(input, { ...init, body: JSON.stringify({ ...body, abi: 'miakapp.component/1' }) });
+      }
+      return await original(input, init);
+    };
+    const host = testHost({ files: appProject(), fetch: tampering, env: { [HOME_KEY_VARIABLE]: homeKey() } });
+    expect(await run(['publish'], host)).toBe(EXIT_CODE.contract);
+    expect(plane.generation).toBe(0);
+  });
+});
diff --git a/packages/cli/test/main.test.ts b/packages/cli/test/main.test.ts
index e444c10..50daf4f 100644
--- a/packages/cli/test/main.test.ts
+++ b/packages/cli/test/main.test.ts
@@ -128,7 +128,7 @@ describe('offline commands', () => {
     expect(host.stderr()).toContain('dynamic_import');
   });
 
-  test('init writes a project file that check accepts', async () => {
+  test('init writes a project file that check accepts, a whole-house app by default', async () => {
     const files = new MemoryFiles();
     const host = testHost({ files });
     const code = await run([
@@ -137,13 +137,30 @@ describe('offline commands', () => {
       '--control-plane', 'https://control.example.test/api',
     ], host);
     expect(code).toBe(EXIT_CODE.success);
+    expect(new TextDecoder().decode(files.entries.get(`${PROJECT_ROOT}/miakapp.yaml`))).toContain('\napp:\n');
 
     files.entries.set(
-      `${PROJECT_ROOT}/dist/component.js`,
+      `${PROJECT_ROOT}/dist/app.js`,
       new TextEncoder().encode(ARTIFACT_SOURCE),
     );
     const second = testHost({ files });
-    expect(await run(['check'], second)).toBe(EXIT_CODE.success);
+    expect(await run(['check', '--json'], second)).toBe(EXIT_CODE.success);
+    expect(JSON.parse(second.stdout()).abi).toBe('miakapp.app/1');
+  });
+
+  test('init --kind component keeps the semantic component shape', async () => {
+    const files = new MemoryFiles();
+    const host = testHost({ files });
+    expect(await run([
+      'init',
+      '--kind', 'component',
+      '--home', HOME_ID,
+      '--control-plane', 'https://control.example.test/api',
+    ], host)).toBe(EXIT_CODE.success);
+    files.entries.set(`${PROJECT_ROOT}/dist/component.js`, new TextEncoder().encode(ARTIFACT_SOURCE));
+    const second = testHost({ files });
+    expect(await run(['check', '--json'], second)).toBe(EXIT_CODE.success);
+    expect(JSON.parse(second.stdout()).abi).toBe('miakapp.component/1');
   });
 
   test('init never overwrites an existing project file', async () => {
diff --git a/packages/cli/test/support/control-plane.ts b/packages/cli/test/support/control-plane.ts
index 0e9aa32..2c6f8cc 100644
--- a/packages/cli/test/support/control-plane.ts
+++ b/packages/cli/test/support/control-plane.ts
@@ -24,6 +24,7 @@ interface Upload {
   readonly uploadId: string;
   readonly token: string;
   readonly release: string;
+  readonly abi: string;
   readonly sha256: string;
   readonly size: number;
   readonly requires: unknown;
@@ -38,6 +39,8 @@ export interface FakeControlPlaneOptions {
   readonly fail?: ReadonlyMap<string, { status: number; code: string }>;
   /** Replaces the pairing redeem response, for contract-violation tests. */
   readonly pairingResponse?: (issued: { homeKey: string; homeId: string; keyId: string }) => Response;
+  /** Optional discovery members a newer control plane advertises. */
+  readonly discoveryExtras?: Readonly<Record<string, string>>;
 }
 
 export interface FakeControlPlane {
@@ -106,6 +109,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
         user_relay_exchange_endpoint: `${ISSUER}/v1/user-relay-tokens:exchange`,
         push_audience: `${ISSUER}/v1/push`,
         components_audience: `${ISSUER}/v1/components`,
+        ...options.discoveryExtras,
       });
     }
 
@@ -151,6 +155,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
     if (method === 'POST' && local === '/component-uploads') {
       const body = JSON.parse(String(init.body)) as {
         release: string;
+        abi: string;
         sha256: string;
         size: number;
         requires: unknown;
@@ -160,6 +165,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
         uploadId,
         token: randomSecret(),
         release: body.release,
+        abi: body.abi,
         sha256: body.sha256,
         size: body.size,
         requires: body.requires,
@@ -206,7 +212,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
         upload_id: upload.uploadId,
         status: upload.status,
         release: upload.release,
-        abi: COMPONENT_ABI,
+        abi: upload.abi,
         sha256: upload.sha256,
         size: upload.size,
         requires: upload.requires,
@@ -251,14 +257,14 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
 
   function pointerBody(
     generation: number,
-    record: { release: string; sha256: string; size: number; requires: unknown },
+    record: { release: string; sha256: string; size: number; requires: unknown; abi?: string },
   ): unknown {
     return {
       schema: 'miakapp.component-pointer/1',
       home_id: options.homeId,
       generation,
       release: record.release,
-      abi: COMPONENT_ABI,
+      abi: record.abi ?? COMPONENT_ABI,
       url: `${ISSUER}/v1/components/${record.sha256}.js`,
       sha256: record.sha256,
       size: record.size,
@@ -271,11 +277,12 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
     sha256: string;
     size: number;
     requires: unknown;
+    abi?: string;
   }): unknown {
     return {
       schema: 'miakapp.component-release/1',
       release: record.release,
-      abi: COMPONENT_ABI,
+      abi: record.abi ?? COMPONENT_ABI,
       sha256: record.sha256,
       size: record.size,
       requires: record.requires,
diff --git a/templates/home/app/main.ts b/templates/home/app/main.ts
new file mode 100644
index 0000000..52b6a08
--- /dev/null
+++ b/templates/home/app/main.ts
@@ -0,0 +1,109 @@
+/**
+ * The household's interface: a whole-house application.
+ *
+ * It owns its document — this file builds the DOM, styles it and routes between
+ * two views with plain `location.hash`. Swap any of it for React, Svelte, Vue or
+ * anything a bundler can inline: the build emits one classic-script IIFE
+ * (`dist/app.js`), which is what Miakapp publishes and runs in its isolated
+ * frame. The only way to the home is `@miakapp/app`.
+ *
+ * Every path read and function called is declared in `miakapp.yaml`; the
+ * coordinator still decides per resident.
+ */
+import { callErrorCode, connect, type HomeState } from '@miakapp/app';
+
+import { STATE } from '../coordinator/home.js';
+import { buildView, phaseAfterFailure, type LightPhase } from './view.js';
+
+const home = connect();
+let phase: LightPhase = 'idle';
+let state: HomeState = home.state();
+
+const style = document.createElement('style');
+style.textContent = `
+  :root { color-scheme: light dark; font-family: ui-rounded, system-ui, sans-serif; }
+  body { margin: 0; min-height: 100vh; background: Canvas; color: CanvasText; }
+  header { display: flex; align-items: baseline; justify-content: space-between; padding: 20px 20px 8px; }
+  h1 { margin: 0; font-size: 1.6rem; }
+  nav { display: flex; gap: 6px; padding: 0 16px; }
+  nav a { padding: 8px 14px; border-radius: 999px; color: inherit; text-decoration: none; }
+  nav a[aria-current="page"] { background: color-mix(in srgb, CanvasText 12%, transparent); font-weight: 600; }
+  main { display: grid; gap: 14px; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); padding: 16px; }
+  .card { padding: 20px; border-radius: 22px; background: color-mix(in srgb, CanvasText 6%, Canvas); }
+  .value { margin: 8px 0 0; font-size: 2.4rem; font-weight: 700; }
+  .muted { opacity: .65; }
+  .stale { margin: 0 16px; padding: 10px 14px; border-radius: 12px; background: #ffe2a8; color: #4a3000; }
+  button { font: inherit; padding: 12px 20px; border: 0; border-radius: 999px; background: CanvasText; color: Canvas; }
+  button:disabled { opacity: .45; }
+`;
+document.head.append(style);
+
+const header = document.createElement('header');
+const nav = document.createElement('nav');
+const notice = document.createElement('p');
+const main = document.createElement('main');
+document.body.append(header, nav, notice, main);
+
+const ROUTES = [['overview', 'Overview'], ['lights', 'Lights']] as const;
+
+function element<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  if (text !== undefined) node.textContent = text;
+  if (className !== undefined) node.className = className;
+  return node;
+}
+
+async function toggleLight(next: boolean): Promise<void> {
+  phase = 'sending';
+  render();
+  try {
+    await home.call('lighting.set', { on: next }, { timeoutMs: 10_000 });
+    phase = 'idle';
+  } catch (error) {
+    // Never retried: the next state snapshot says what really happened.
+    phase = phaseAfterFailure(callErrorCode(error));
+  }
+  render();
+}
+
+function render(): void {
+  const view = buildView(home.name, state, phase, home.canCall('lighting.set'));
+  const route = location.hash.slice(1) === 'lights' ? 'lights' : 'overview';
+
+  header.replaceChildren(element('h1', view.title), element('span', view.healthy ? 'Home online' : 'Home offline', 'muted'));
+  nav.replaceChildren(...ROUTES.map(([id, label]) => {
+    const link = element('a', label);
+    link.href = `#${id}`;
+    if (id === route) link.setAttribute('aria-current', 'page');
+    return link;
+  }));
+  notice.className = view.stale ? 'stale' : '';
+  notice.textContent = view.stale ? 'Showing the last known state; waiting for the home.' : '';
+
+  const light = element('section', undefined, 'card');
+  const button = element('button', view.light.label);
+  button.disabled = !view.light.usable;
+  button.addEventListener('click', () => void toggleLight(view.light.on !== true));
+  light.append(
+    element('h2', 'Living-room lamp'),
+    element('p', view.light.on === undefined ? '—' : view.light.on ? 'On' : 'Off', 'value'),
+    button,
+    ...(view.light.note === undefined ? [] : [element('p', view.light.note, 'muted')]),
+  );
+
+  const climate = element('section', undefined, 'card');
+  climate.append(
+    element('h2', 'Temperature'),
+    element('p', view.temperature ?? '—', 'value'),
+    element('p', home.canRead(STATE.temperature) ? 'Living room' : 'Not shared with you', 'muted'),
+  );
+
+  main.replaceChildren(...(route === 'lights' ? [light] : [climate, light]));
+}
+
+window.addEventListener('hashchange', render);
+home.subscribe((next) => {
+  state = next;
+  if (phase === 'unknown') phase = 'idle';
+  render();
+});
diff --git a/templates/home/app/view.ts b/templates/home/app/view.ts
new file mode 100644
index 0000000..87052e7
--- /dev/null
+++ b/templates/home/app/view.ts
@@ -0,0 +1,58 @@
+/**
+ * What the house shows, derived from the granted state alone. Pure, so the
+ * interface's decisions — which values are current, which control is usable,
+ * what a failed call means — are tested without a browser.
+ */
+import type { CallErrorCode, HomeState } from '@miakapp/app';
+
+import { STATE } from '../coordinator/home.js';
+
+export type LightPhase = 'idle' | 'sending' | 'failed' | 'unknown';
+
+export interface HomeView {
+  readonly title: string;
+  readonly stale: boolean;
+  readonly temperature: string | undefined;
+  readonly light: {
+    readonly on: boolean | undefined;
+    readonly usable: boolean;
+    readonly label: string;
+    readonly note: string | undefined;
+  };
+  readonly healthy: boolean;
+}
+
+export function buildView(
+  homeName: string,
+  state: HomeState,
+  phase: LightPhase,
+  canCall: boolean,
+): HomeView {
+  const temperature = state.values[STATE.temperature];
+  const on = state.values[STATE.lightOn];
+  const healthy = state.values[STATE.health] === 'healthy';
+  const lightOn = typeof on === 'boolean' ? on : undefined;
+  return {
+    title: homeName,
+    stale: state.stale,
+    healthy,
+    temperature: typeof temperature === 'number' && !state.stale
+      ? `${temperature.toFixed(1)} °C`
+      : undefined,
+    light: {
+      on: lightOn,
+      usable: canCall && healthy && !state.stale && lightOn !== undefined && phase !== 'sending',
+      label: phase === 'sending' ? 'Sending…' : lightOn === true ? 'Turn off' : 'Turn on',
+      note: phase === 'failed'
+        ? 'The home did not apply it.'
+        : phase === 'unknown'
+          ? 'The home may have acted; waiting for its state.'
+          : undefined,
+    },
+  };
+}
+
+/** A failed call's code, mapped to what the interface does next. */
+export function phaseAfterFailure(code: CallErrorCode | undefined): LightPhase {
+  return code === 'outcome_unknown' || code === 'timeout' ? 'unknown' : 'failed';
+}
diff --git a/templates/home/bun.lock b/templates/home/bun.lock
index 768924f..96cc71e 100644
--- a/templates/home/bun.lock
+++ b/templates/home/bun.lock
@@ -4,6 +4,7 @@
     "": {
       "name": "miakapp-home-template",
       "dependencies": {
+        "@miakapp/app": "file:../../packages/app",
         "@miakapp/component": "file:../../packages/component",
         "miakapi": "file:../..",
       },
@@ -16,6 +17,8 @@
     },
   },
   "packages": {
+    "@miakapp/app": ["@miakapp/app@file:../../packages/app", { "devDependencies": { "@types/bun": "1.2.23", "@types/node": "22.20.1", "typescript": "7.0.2" } }],
+
     "@miakapp/cli": ["@miakapp/cli@file:../../packages/cli", { "devDependencies": { "@types/bun": "1.2.23", "@types/node": "22.20.1", "typescript": "7.0.2" }, "bin": { "miakapp": "./bin/miakapp.js" } }],
 
     "@miakapp/component": ["@miakapp/component@file:../../packages/component", { "devDependencies": { "@types/bun": "1.2.23", "@types/node": "22.20.1", "typescript": "7.0.2" } }],
diff --git a/templates/home/miakapp.yaml b/templates/home/miakapp.yaml
index fc71c3b..7713174 100644
--- a/templates/home/miakapp.yaml
+++ b/templates/home/miakapp.yaml
@@ -2,23 +2,23 @@ schema: miakapp.project/1
 home: my-home
 control_plane: https://control.miakapp.com
 
-component:
-  artifact: dist/component.js
+# The household's interface: a whole-house application (miakapp.app/1) built
+# from app/main.ts into one IIFE. Residents open it at the home_url that
+# `miakapp publish` prints. To publish the semantic component in component/
+# instead, replace this section with `component:` (artifact dist/component.js,
+# built by `bun run build:component`), which may also declare its event.
+app:
+  artifact: dist/app.js
   release: 0.1.0
-  # These lists are the component's request, not a grant. The effective grant is
-  # the intersection with what the coordinator declared in coordinator/home.ts,
-  # so every name here must also be covered there.
+  # A request, not a grant: the coordinator in coordinator/home.ts decides per
+  # resident, so every name here must also be covered there.
   requires:
     state_read:
       - climate.living_room.temperature
       - service.coordinator.health
       - zone.living_room.light.on
-    event_subscribe:
-      - zone.living_room.light.changed
-    event_publish: []
     call:
       - lighting.set
-    presentation: []
 
 coordinator:
   entry: coordinator/main.ts
diff --git a/templates/home/package.json b/templates/home/package.json
index 5222b19..ea96ab8 100644
--- a/templates/home/package.json
+++ b/templates/home/package.json
@@ -1,7 +1,7 @@
 {
   "name": "miakapp-home-template",
   "version": "0.1.0",
-  "description": "Starting point for a Miakapp home: a coordinator, a component and a project file",
+  "description": "Starting point for a Miakapp home: a coordinator, a whole-house application and a project file",
   "type": "module",
   "private": true,
   "engines": {
@@ -9,15 +9,17 @@
     "node": ">=22.9"
   },
   "scripts": {
-    "build": "bun build component/main.ts --format=iife --minify --outfile dist/component.js",
+    "build": "bun build app/main.ts --format=iife --minify --outfile dist/app.js",
     "check": "bun run typecheck && bun run build && bun run test && bun run check:artifact",
     "check:artifact": "miakapp check",
     "dev": "bun run coordinator/main.ts",
     "publish:home": "bun run build && miakapp publish",
     "test": "bun test test/",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:component": "bun build component/main.ts --format=iife --minify --outfile dist/component.js"
   },
   "dependencies": {
+    "@miakapp/app": "file:../../packages/app",
     "@miakapp/component": "file:../../packages/component",
     "miakapi": "file:../.."
   },
diff --git a/templates/home/test/app.test.ts b/templates/home/test/app.test.ts
new file mode 100644
index 0000000..1e3625a
--- /dev/null
+++ b/templates/home/test/app.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+
+import { STATE } from '../coordinator/home.js';
+import { buildView, phaseAfterFailure } from '../app/view.js';
+
+const current = {
+  values: { [STATE.lightOn]: false, [STATE.temperature]: 21.46, [STATE.health]: 'healthy' },
+  revision: 4,
+  stale: false,
+};
+
+describe('house app view', () => {
+  test('shows current values and offers the lamp when the home can act', () => {
+    const view = buildView('Maison', current, 'idle', true);
+    expect(view.temperature).toBe('21.5 °C');
+    expect(view.light).toMatchObject({ on: false, usable: true, label: 'Turn on' });
+  });
+
+  test('never presents stale values as current and freezes the control', () => {
+    const view = buildView('Maison', { ...current, stale: true }, 'idle', true);
+    expect(view.stale).toBe(true);
+    expect(view.temperature).toBeUndefined();
+    expect(view.light.usable).toBe(false);
+  });
+
+  test('keeps the control off when the resident may not call or the home is down', () => {
+    expect(buildView('Maison', current, 'idle', false).light.usable).toBe(false);
+    const down = { ...current, values: { ...current.values, [STATE.health]: 'degraded' } };
+    expect(buildView('Maison', down, 'idle', true).light.usable).toBe(false);
+  });
+
+  test('treats an unknown outcome as "wait for state", never as a failure to retry', () => {
+    expect(phaseAfterFailure('outcome_unknown')).toBe('unknown');
+    expect(phaseAfterFailure('timeout')).toBe('unknown');
+    expect(phaseAfterFailure('denied')).toBe('failed');
+    expect(buildView('Maison', current, 'unknown', true).light.note).toContain('may have acted');
+    expect(buildView('Maison', current, 'sending', true).light.usable).toBe(false);
+  });
+});
diff --git a/templates/home/tsconfig.json b/templates/home/tsconfig.json
index 301cc36..cebc01e 100644
--- a/templates/home/tsconfig.json
+++ b/templates/home/tsconfig.json
@@ -5,7 +5,8 @@
     "exactOptionalPropertyTypes": true,
     "forceConsistentCasingInFileNames": true,
     "lib": [
-      "ES2022"
+      "ES2022",
+      "DOM"
     ],
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
@@ -27,6 +28,7 @@
   },
   "include": [
     "coordinator/**/*.ts",
+    "app/**/*.ts",
     "component/**/*.ts",
     "test/**/*.ts"
   ]

From e070ef20633d7e1c4f0f94f8587b433fab05d9dd Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 05:12:58 +0200
Subject: [PATCH 5/7] fix(cli): deliver uploads to the issuer-level upload URL

The control plane issues upload_url as {issuer}/v1/component-uploads/
{uploadId} (RFC 0004 13.2) and serves delivery only there. The CLI
required the URL under /v1/homes/{home}/component-uploads/ and refused
every real capability as a contract error; its fake control plane
shared the mistake, so the suite never noticed. Found by running the
CLI against the real control plane in the emulators. The fake now
issues and serves the issuer-level URL and refuses delivery under the
home path, like the real one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/cli/src/publication.ts            |  5 +++-
 packages/cli/test/support/control-plane.ts | 31 +++++++++++++---------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/packages/cli/src/publication.ts b/packages/cli/src/publication.ts
index 555c04c..0d05904 100644
--- a/packages/cli/src/publication.ts
+++ b/packages/cli/src/publication.ts
@@ -380,7 +380,10 @@ export async function requestUpload(
   if (response.status !== 201) {
     throw failure('Upload capability request', response.status, await readFailure(response), false);
   }
-  return decodeUploadCapability(await readJsonBody(response), `${base}/component-uploads/`);
+  // RFC 0004 §13.2: the capability is delivered to the issuer-level
+  // `PUT /v1/component-uploads/{uploadId}`, not under the home path that
+  // issued it.
+  return decodeUploadCapability(await readJsonBody(response), `${target.issuer}/v1/component-uploads/`);
 }
 
 /**
diff --git a/packages/cli/test/support/control-plane.ts b/packages/cli/test/support/control-plane.ts
index 2c6f8cc..df7b125 100644
--- a/packages/cli/test/support/control-plane.ts
+++ b/packages/cli/test/support/control-plane.ts
@@ -149,6 +149,21 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
       });
     }
 
+    const deliveryMatch = /^\/v1\/component-uploads\/([A-Za-z0-9_-]{22})$/.exec(path);
+    if (method === 'PUT' && deliveryMatch !== null) {
+      const upload = plane.uploads.get(deliveryMatch[1] as string);
+      if (upload === undefined) return failure(404, 'invalid_upload_capability');
+      if ((init.headers as Record<string, string>)['authorization'] !== `Bearer ${upload.token}`) {
+        return failure(403, 'invalid_upload_capability');
+      }
+      const bytes = init.body as Uint8Array;
+      if (digestOf(bytes) !== upload.sha256 || bytes.byteLength !== upload.size) {
+        return failure(422, 'invalid_artifact');
+      }
+      upload.status = 'delivered';
+      return new Response(null, { status: 204 });
+    }
+
     const local = input.startsWith(base) ? input.slice(base.length) : undefined;
     if (local === undefined) return failure(404, 'not_found');
 
@@ -175,7 +190,7 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
       return json(201, {
         schema: 'miakapp.component-upload/1',
         upload_id: uploadId,
-        upload_url: `${base}/component-uploads/${uploadId}`,
+        upload_url: `${ISSUER}/v1/component-uploads/${uploadId}`,
         upload_token: upload.token,
         expires_at: new Date(Date.now() + 600_000).toISOString(),
       });
@@ -195,18 +210,8 @@ export function fakeControlPlane(options: FakeControlPlaneOptions): FakeControlP
     if (uploadMatch !== null) {
       const upload = plane.uploads.get(uploadMatch[1] as string);
       if (upload === undefined) return failure(404, 'invalid_upload_capability');
-      if (method === 'PUT') {
-        if ((init.headers as Record<string, string>)['authorization']
-          !== `Bearer ${upload.token}`) {
-          return failure(403, 'invalid_upload_capability');
-        }
-        const bytes = init.body as Uint8Array;
-        if (digestOf(bytes) !== upload.sha256 || bytes.byteLength !== upload.size) {
-          return failure(422, 'invalid_artifact');
-        }
-        upload.status = 'delivered';
-        return new Response(null, { status: 204 });
-      }
+      // Like the real control plane, delivery is not served under the home.
+      if (method === 'PUT') return failure(404, 'not_found');
       return json(200, {
         schema: 'miakapp.component-upload-status/1',
         upload_id: upload.uploadId,

From a0bd667357ec707a23f351f97a34ad6e654977f4 Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 03:16:51 +0000
Subject: [PATCH 6/7] chore: prepare CLI alpha.6 and use the template-local
 executable

---
 packages/cli/package.json   | 2 +-
 packages/cli/src/version.ts | 2 +-
 templates/home/package.json | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index a4cad00..9a5fc0a 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@miakapp/cli",
-  "version": "4.0.0-alpha.5",
+  "version": "4.0.0-alpha.6",
   "description": "Agent-first Miakapp command line: check, build, publish, activate and roll back home components",
   "type": "module",
   "engines": {
diff --git a/packages/cli/src/version.ts b/packages/cli/src/version.ts
index 4405d5c..50aea9f 100644
--- a/packages/cli/src/version.ts
+++ b/packages/cli/src/version.ts
@@ -12,4 +12,4 @@
  */
 export const PACKAGE_NAME = '@miakapp/cli';
 
-export const CLI_VERSION = '4.0.0-alpha.5';
+export const CLI_VERSION = '4.0.0-alpha.6';
diff --git a/templates/home/package.json b/templates/home/package.json
index ea96ab8..f9a53c2 100644
--- a/templates/home/package.json
+++ b/templates/home/package.json
@@ -11,9 +11,9 @@
   "scripts": {
     "build": "bun build app/main.ts --format=iife --minify --outfile dist/app.js",
     "check": "bun run typecheck && bun run build && bun run test && bun run check:artifact",
-    "check:artifact": "miakapp check",
+    "check:artifact": "node ./node_modules/@miakapp/cli/bin/miakapp.js check",
     "dev": "bun run coordinator/main.ts",
-    "publish:home": "bun run build && miakapp publish",
+    "publish:home": "bun run build && node ./node_modules/@miakapp/cli/bin/miakapp.js publish",
     "test": "bun test test/",
     "typecheck": "tsc --noEmit",
     "build:component": "bun build component/main.ts --format=iife --minify --outfile dist/component.js"

From 2d1a4f7d425c844952e378699508f8fbb782a205 Mon Sep 17 00:00:00 2001
From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com>
Date: Sat, 3 Oct 2026 03:17:54 +0000
Subject: [PATCH 7/7] docs: align CLI quickstart with app-first publishing

---
 packages/cli/README.md | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/packages/cli/README.md b/packages/cli/README.md
index 33fbbe4..7b8fb81 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,6 +1,6 @@
 # @miakapp/cli
 
-Build, validate, publish and roll back one Miakapp home component.
+Pair, build, validate, publish and roll back independent Miakapp house applications.
 
 The CLI is the deployment mechanism, not the source of truth. **Git belongs to
 you**: this tool never commits, never rewrites sources it did not generate and
@@ -12,13 +12,19 @@ stable exit code and one stable failure kind, and `--json` prints exactly one
 object on stdout.
 
 ```bash
-printf '%s\n' "$CODE" | bunx @miakapp/cli pair   # code from https://miakapp.com/pair
+printf '%s\n' "$CODE" | bunx @miakapp/cli pair --issuer "$MIAKAPP_ISSUER"
 bunx @miakapp/cli init                            # home and issuer from the paired context
 bunx @miakapp/cli check
 bunx @miakapp/cli publish
 bunx @miakapp/cli status                          # verify what is live
 ```
 
+Use the exact issuer command shown by your deployment's `/pair` page; do not
+guess a staging issuer. `init` writes the project manifest, not an application:
+build your house UI as one classic-script IIFE (the `@miakapp/app` SDK is
+optional), then run `check` and `publish`. Open and verify the returned
+`home_url` as a resident before handing it over.
+
 ## The project file
 
 `miakapp.yaml` sits at the root of your repository:
@@ -26,24 +32,25 @@ bunx @miakapp/cli status                          # verify what is live
 ```yaml
 schema: miakapp.project/1
 home: my-home
-control_plane: https://control.miakapp.com
+control_plane: https://control.example.test
 
-component:
-  artifact: dist/component.js
-  release: 2026-09-13.1
+app:
+  artifact: dist/app.js
+  release: 2026-10-03.1
   requires:
     state_read:
       - climate.living_room.temperature
-    event_subscribe: []
-    event_publish: []
     call:
       - lighting.set
-    presentation: []
 
 coordinator:
   entry: coordinator/main.ts
 ```
 
+`app` declares only `state_read` and `call`; events, media and reserved
+`miakapp.*` calls are unavailable. Use `miakapp init --kind component` for the
+semantic component ABI instead. Choose exactly one of `app` and `component`.
+
 `requires` is the closed RFC 0002 capability object. Lists are de-duplicated and
 sorted before they are bound into an upload capability, so the value the CLI
 sends is byte-identical on every later reconciliation read.
@@ -116,9 +123,9 @@ place instead of appending another copy. `.mcp.json` is merged as a structure 
 one key, by name — so every other server in it survives, and a file that does
 not parse is refused rather than replaced with a valid one.
 
-The server is registered as the bare `miakapp` command rather than an absolute
-path, because the file is committed and the next machine to check it out will
-not have this one's directory layout.
+The generated server entry uses `npx -y @miakapp/cli@<installed-version> mcp`,
+so a new machine gets the same executable as the bundled guide without relying
+on a global binary or this machine's directory layout.
 
 Run it again whenever the CLI is upgraded: an unchanged file is reported
 `unchanged`, and a guide that moved on is reported `updated`.