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 6c0f1ce..1687ea1 100644
--- a/docs/agent-guide.md
+++ b/docs/agent-guide.md
@@ -10,6 +10,43 @@ 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 `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.
+- **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:
@@ -17,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 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 component is not. The relay between them is
+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.
@@ -94,6 +137,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
@@ -180,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.*`:
@@ -305,25 +415,35 @@ 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                                   # app: by default; --kind component for a semantic tree
 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 its `home_url` 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 +486,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:
+
+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:
 
-`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.
+   ```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 +556,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/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/README.md b/packages/cli/README.md
index 0a7c9ce..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,11 +12,19 @@ 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 --issuer "$MIAKAPP_ISSUER"
+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
 ```
 
+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:
@@ -24,24 +32,25 @@ 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.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.
@@ -55,10 +64,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. |
@@ -111,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`.
@@ -129,8 +141,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 +149,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 +171,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 +183,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 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
+printf '%s\n' "$CODE" | miakapp pair      # or run it in a terminal: hidden prompt
+miakapp pair --code "$CODE"               # allowed, but lands in shell history
+```
+
+| 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 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 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
-export MIAKAPP_HOME_KEY="$(op read op://home/miakapp/home-key)"   # or your own vault
-bunx @miakapp/cli publish --expected-generation 4
+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
 ```
 
-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.
+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 +254,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 +280,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..1687ea1 100644
--- a/packages/cli/assets/agent-guide.md
+++ b/packages/cli/assets/agent-guide.md
@@ -10,6 +10,43 @@ 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 `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.
+- **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:
@@ -17,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 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 component is not. The relay between them is
+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.
@@ -94,6 +137,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
@@ -180,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.*`:
@@ -305,25 +415,35 @@ 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                                   # app: by default; --kind component for a semantic tree
 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 its `home_url` 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 +486,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:
+
+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:
 
-`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.
+   ```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 +556,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/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/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/agent-pack.ts b/packages/cli/src/agent-pack.ts
index 4663196..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
@@ -119,9 +120,13 @@ 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 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.
@@ -129,8 +134,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/src/contexts.ts b/packages/cli/src/contexts.ts
new file mode 100644
index 0000000..3fbb3d5
--- /dev/null
+++ b/packages/cli/src/contexts.ts
@@ -0,0 +1,441 @@
+/**
+ * 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 (symbolic links are refused)`,
+      `Move it aside, or point ${CONFIG_DIRECTORY_VARIABLE} at the real directory.`,
+    );
+  }
+  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/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 cd71178..9974656 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, homeUrl } 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', 'kind'],
   '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,32 +531,59 @@ 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; 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 });
-  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,
+    homeUrl: homeUrl(discovery, project.homeId),
+  };
 }
 
 function requirementFields(requires: Requirements): readonly Field[] {
   return REQUIREMENT_KINDS.map((kind): Field => [`requires.${kind}`, requires[kind]]);
 }
 
-function pointerResult(summary: string, pointer: ComponentPointer): CommandResult {
+/**
+ * `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,
     fields: [
+      ...credentialFields(credential),
+      ...(expectedGeneration === undefined
+        ? []
+        : [['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,
@@ -378,6 +591,8 @@ function pointerResult(summary: string, pointer: ComponentPointer): CommandResul
       sha256: pointer.sha256,
       size: pointer.size,
       requires: pointer.requires,
+      ...(expectedGeneration === undefined ? {} : { expected_generation: expectedGeneration }),
+      ...credentialJson(credential),
     },
   };
 }
@@ -387,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}
@@ -418,19 +651,82 @@ 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: requiredOption(invocation, 'home'),
-    controlPlane: requiredOption(invocation, 'control-plane'),
-    artifact: invocation.options.get('artifact') ?? 'dist/component.js',
+    home: target.home,
+    controlPlane: target.controlPlane,
+    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);
   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,
+      kind,
+      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,
   };
 }
 
@@ -605,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],
@@ -615,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,
@@ -626,16 +924,18 @@ 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, 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,
@@ -643,14 +943,17 @@ async function runPublish(host: CliHost, invocation: Invocation): Promise<Comman
   return pointerResult(
     `Published ${release} as generation ${pointer.generation}`,
     pointer,
+    credential,
+    expectedGeneration,
+    residentUrl,
   );
 }
 
 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, 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);
@@ -660,10 +963,14 @@ 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,
+    residentUrl,
   );
 }
 
@@ -674,7 +981,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 +1010,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 +1035,309 @@ 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, homeUrl: residentUrl } = await publicationTarget(host, invocation, project);
+  const { generation, pointer } = await readPointer(target);
+  if (pointer === null) {
+    return {
+      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(
+    `${project.homeId} runs ${pointer.release} at generation ${generation}`,
+    pointer,
+    credential,
+    undefined,
+    residentUrl,
+  );
+  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 +1348,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..b143815 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,26 +312,34 @@ 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. 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',
-        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',
         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',
@@ -203,6 +348,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 +373,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 +389,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 +403,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 +416,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 +439,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       EXPECTED_GENERATION,
       GENERATION,
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
       CONFIRM,
     ],
     readOnly: false,
@@ -314,6 +463,7 @@ export const TOOLS: readonly ToolDefinition[] = [
       EXPECTED_GENERATION,
       GENERATION,
       PROJECT_ARGUMENT,
+      CONTEXT_ARGUMENT,
       CONFIRM,
     ],
     readOnly: false,
@@ -345,7 +495,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 +520,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 +538,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 +553,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 +567,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 +656,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 +686,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/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 7b50b45..0d05904 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,
@@ -374,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/`);
 }
 
 /**
@@ -473,6 +482,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.
  *
@@ -530,12 +578,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');
   }
@@ -548,7 +598,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, {
@@ -556,7 +606,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/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/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/packages/cli/test/agent-pack.test.ts b/packages/cli/test/agent-pack.test.ts
index 82ed261..dbd9b3a 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,16 @@ 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('home_url');
+    expect(block).toContain('never the artifact URL');
+    expect(block).toContain('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 +259,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/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/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/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/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..df7b125 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;
@@ -36,6 +37,10 @@ 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;
+  /** Optional discovery members a newer control plane advertises. */
+  readonly discoveryExtras?: Readonly<Record<string, string>>;
 }
 
 export interface FakeControlPlane {
@@ -44,6 +49,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 +86,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> {
@@ -93,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,
       });
     }
 
@@ -100,6 +117,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,12 +131,46 @@ 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 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');
 
     if (method === 'POST' && local === '/component-uploads') {
       const body = JSON.parse(String(init.body)) as {
         release: string;
+        abi: string;
         sha256: string;
         size: number;
         requires: unknown;
@@ -128,6 +180,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,
@@ -137,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(),
       });
@@ -157,24 +210,14 @@ 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,
         status: upload.status,
         release: upload.release,
-        abi: COMPONENT_ABI,
+        abi: upload.abi,
         sha256: upload.sha256,
         size: upload.size,
         requires: upload.requires,
@@ -182,6 +225,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,32 +253,41 @@ 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; abi?: string },
+  ): unknown {
+    return {
+      schema: 'miakapp.component-pointer/1',
+      home_id: options.homeId,
+      generation,
+      release: record.release,
+      abi: record.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;
     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/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: [],
+    });
+  });
+});
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/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 31f5e77..7713174 100644
--- a/templates/home/miakapp.yaml
+++ b/templates/home/miakapp.yaml
@@ -1,24 +1,24 @@
 schema: miakapp.project/1
 home: my-home
-control_plane: https://control.miakapp.app
+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 063b5a9..f9a53c2 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",
+    "check:artifact": "node ./node_modules/@miakapp/cli/bin/miakapp.js check",
     "dev": "bun run coordinator/main.ts",
-    "publish:home": "bun run build && miakapp publish --expected-generation 0",
+    "publish:home": "bun run build && node ./node_modules/@miakapp/cli/bin/miakapp.js 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"
   ]