@happyvertical/smrt-app-shell 0.60.17 → 0.61.0

package/AGENTS.md

@@ -6,22 +6,30 @@ for one person: the owner. Epic #4867; this package is #4872. The engine is
 documented in [agents/engine.md](agents/engine.md) (it must not import
 SvelteKit or `src/lib`). README has the route and JSON contracts.
 
+Shared assistant adapters and legacy approval storage: [agents/shared-pieces.md](agents/shared-pieces.md).
+
 ## Where things live
 
 | Path | What |
 |---|---|
-| `src/engine/` | `AppHost`, worker thread, migrations, QuickJS sandbox. Finished and tested on its own. |
+| `src/engine/` | `AppHost`, worker thread, migrations, QuickJS sandbox, drafts (`forkDraft`/`previewPublish`/`publishDraft`/`undoTo`, frozen host, draft-only `autoApprove`; see engine.md "Drafts"). Finished and tested on its own. |
 | `src/lib/objects/` | Shell models (`objectsDir` in `vite.config.ts`): `App`, `AppVersion`, `Approval`, `AssistantThread`, `AssistantMessage`. |
 | `src/lib/server/smrt.ts` | `createSmrtSvelteKitRuntime`, `prepareDatabase`, `configureShell`. |
+| `src/lib/server/registry.ts` | The ONE startup registration path (permissions, preference kinds); `smrt.ts` imports it before the runtime. app-runtime grants newly registered permissions to an existing owner on every start. `registry.test.ts` guards it. |
 | `src/lib/server/schema.ts` | `prepareShellSchema(db)`: additive first-run schema. |
-| `src/lib/server/host.ts` | Holders: shell db, data root, the one lazily opened `AppHost`. |
-| `src/lib/server/version-store.ts` | `ShellVersionStore` (engine `VersionStore` on `AppVersion` + the `App` row). |
+| `src/lib/server/host.ts` | Holders: shell db, data root, the LIVE `AppHost` (`getHost`, never the draft) and the open-draft slot; `hostFor(target)` is how a request reaches either; restart adoption of an open draft (re-freeze live, reopen the draft with `autoApprove`). |
+| `src/lib/server/target.ts`, `drafts.ts`, `view.ts` | The copy a request names (`live`/`draft`, `CallScope`), the draft lifecycle (start, describe, preview, publish and discard apply, History grouping) and the owner's saved view. README "Draft then publish (the shell)" lists routes, payloads, events. |
+| `src/lib/server/version-store.ts` | `ShellVersionStore` (engine `VersionStore` on `AppVersion` + the `App` row; `commit` is one transaction, a publish's draft mark rides in it) and `DraftVersionStore` (`AppDraftVersion` rows of one `AppDraft`). |
 | `src/lib/server/owner.ts` | Owner check, `Principal`, `assertOwner`, `runAs`. |
-| `src/lib/server/approvals.ts` | Approval service; the only place `approved: true` is set. |
+| `src/lib/server/approvals.ts`, `approval-store.ts` | Shared-authority storage adapter and shell action executor; the only place `approved: true` is set. |
 | `src/lib/server/builder.ts` | `runCommand`/`runAppTool`/`runRest`/`requestRecordDelete`: execute or turn into an Approval. |
 | `src/lib/server/catalog.ts`, `policy.ts`, `mcp-server.ts` | Merged tool catalog, the one policy, the `/mcp` server. |
 | `src/lib/server/http.ts`, `events.ts` | Route plumbing; in-process event bus for SSE. |
-| `src/lib/server/assistant/`, `src/lib/assistant/` | Assistant: turn loop, hold, config, routes (`mountAssistantRoutes`), thread store; dock UI, pure reducer/stream parser, `guidance/system.md`. |
+| `src/lib/server/inference.ts`, `inference-registry.ts` | smrt-inference host + controller over shell.db and the runtime's master key; `asOwner` runs a settings request as the verified owner; `installShellInference` registers the user resolver (the assistant's key source). |
+| `src/lib/server/assistant/`, `src/lib/assistant/` | Assistant: turn loop, hold, config, routes (`mountAssistantRoutes`), thread store; chat column UI (`AssistantPanel`), pure reducer/stream parser, `guidance/system.md`. |
+| `src/routes/+layout.svelte`, `src/lib/ui/layout.ts`, `src/lib/ui/menu.ts` | Shell layout over smrt-svelte `AppShell`: left sidebar (the person's app only), the chat column (`panel`), footer voice/assistant toggles, user menu (Approvals with count, History, Theme, Settings, Sign out). Plugin mode (iframe or `?embed=plugin`) has no chat or toggles. Chat open state and the sidebar collapse (`edgeToggles.left`, icon rail) are per owner in localStorage; `sidebarFooterDivider={false}` removes the footer line so it does not clash with the chat composer's border. |
+| `src/lib/server/agent-cli/`, `assistant/agent-turn.ts`, `onboarding.ts` | Thin host adapters over smrt-inference/server (CLI, token scope, shell guidance/approvals), the `assistant` preference (engine, onboarding), onboarding routes; UI `routes/welcome`, `components/ConnectAi.svelte`, `routes/settings/assistant`. |
+| `src/routes/settings/` | Settings menu (`ShellSettingsPage`), built-in sections, owner-only `inference/` (panel + actions over the shared controller). |
 | `src/routes/` | `/api/shell/*`, `/api/app/[...path]`, `/api/events`, `/mcp`, `/setup`, health. UI pages are placeholders. |
 
 ## Invariants
@@ -49,6 +57,18 @@ SvelteKit or `src/lib`). README has the route and JSON contracts.
   reserved core endpoints are refused (only the app's own collections are
   served). Snapshots are retained (20 `method-*`; clean up prunes old
   `migrate-*`/`schema-*`).
+- **Drafts and targets.** Every request names its copy; there is no ambient
+  "current host". REST: `?target=` (`x-shell-target` on `/api/app/*`); MCP:
+  the URL (`/mcp`, `?target=draft`, `?scope=assistant`); tools and the
+  assistant pass a `CallScope`. Default live. `getHost()` is live only; the
+  draft host is reached only via `hostFor('draft')`; `invariants.test.ts` keeps
+  request paths on `hostFor` and `autoApprove: true` in `openDraftHost`. While a
+  draft is open live is frozen (also after a restart): builder calls naming live
+  are refused naming the draft; live records keep working. `publishDraft` is
+  always an Approval (`publish-draft`, pinned to the preview digest; the engine
+  refuses at apply if the chain changed); a discard is direct from the UI route,
+  an Approval from a tool. Approvals only ever run against live. Table changes
+  here are new tables only (`prepareShellSchema` cannot ALTER).
 - **Decorator configs are literals** (`@smrt({...})` on `App`, `Approval`). The
   scanner reads them statically; a shared constant silently falls back to full
   CRUD routes. Collections are undecorated. The shell models expose only their
@@ -62,7 +82,9 @@ SvelteKit or `src/lib`). README has the route and JSON contracts.
   `<data root>/user-app/` (`app.db`, `snapshots/`, archives inside app.db):
   plain files and directories inside the app-runtime data root, no symlinks, so
   the encrypted backup seals them. `PORT` and `SMRT_DATA_DIR` are honored (the
-  desktop sidecar contract); health is `/api/_runtime/health`.
+  desktop sidecar contract); health is `/api/_runtime/health` and the desktop
+  wrapper's owner link is `/api/_runtime/owner-link` (both app-runtime handlers;
+  the Tricia desktop product is `smrt-desktop/examples/tricia`).
 - **App-subclass rule** lives in the engine (`enableRecipe` creates app
   subclasses of shipped models). The shell never registers user models in its
   own registry.
@@ -84,14 +106,34 @@ SvelteKit or `src/lib`). README has the route and JSON contracts.
   decides approvals (`approval_decide` is not in the catalog, and
   `ASSISTANT_DENIED_TOOLS` repeats it): only the signed-in owner does, in the UI. A risky call is held (`holdForUser`) on its Approval; only the
   owner's `Approval.decide` applies it. The loop is bounded (`DEFAULT_LIMITS`),
-  serial, aborts on disconnect. API key only: `config.ts` refuses
-  `claude-cli`/`chatgpt-plan`; never spawn a CLI. Model errors are never
+  serial, aborts on disconnect. Three engines (`assistant` preference): `api`
+  (`config.ts` refuses `claude-cli` and any configured `chatgpt-plan`; no
+  in-app Claude subscription login), `chatgpt` (the owner's Sign in with
+  ChatGPT, a PREVIEW for open source apps: `chatgpt.ts`, `assistant/model.ts`,
+  README "Sign in with ChatGPT"; runs only on the target smrt-inference's
+  sign-in resolver made for the `AppShellAssistantChatGPT` request, never an
+  API key; `chat()` + `onProgress`, none of `maxTokens`/sampling/`user`/
+  response format/reasoning/forced tool choice; the SDK keeps the credentials
+  in `<data root>/chatgpt/chatgpt.json`, never read, logged or returned here)
+  and a local agent CLI (`claude-code`/`codex`, the person's own signed-in
+  tool; `agent-cli/`, README "The local agent CLI engine"). The CLI engine gets
+  tools only through `/mcp` under a short-lived owner-bound `assistant.use`
+  token in the child env (never argv, file or log), with built-ins absent (Claude) or OS-confined (Codex; inference
+  `agents/engines.md`), provider keys stripped and the stream guarded; never read a
+  CLI's credential files or keychain, never offer or proxy its login (it opens
+  the vendor's page itself), plain-text product names only. Approvals stay the
+  shell's: `invariants.test.ts` keeps `agent-cli/` and `agent-turn.ts` free of
+  `decideApproval` / `approved: true`. The API key is resolved by
+  `resolveInferenceTarget` through the resolver `installShellInference`
+  registered: the owner's key saved in Settings, then stored bindings, then
+  config/env as `base`. Keys are written only by the owner-only `saveKey`
+  action; none is logged or returned (`inference-settings.test.ts`). Model errors are never
   forwarded or logged beyond class/code (SDK messages can echo keys). Tests use
   a stub through `modelFactory`.
 
 ## Tests and build
 
-`vitest run` (in-process, SQLite, temp dirs; `test-support.ts` seeds an owner
+`vitest run` then `vitest run -c vitest.dom.config.ts` (the layout's jsdom component tests, `*.dom.test.ts`, over smrt-svelte's built `dist`; rebuild smrt-svelte first). Node suite: in-process, SQLite, temp dirs; `test-support.ts` seeds an owner
 and a member; it opens the real driver because the vitest setup would
 pre-create tables). `pnpm build` (tsc engine, `svelte-kit sync`, `vite build`;
 the smrt() plugin generates `src/routes/api/{apps,approvals,_changes,_events,

package/README.md

@@ -12,6 +12,32 @@ smrt-app-shell (SvelteKit + adapter-node, app-runtime local profile)
 └── <data root>/user-app/                app.db, snapshots (plain files; the newest 20 `method-*` are kept, clean up prunes old migration ones)
 ```
 
+## Shared assistant pieces (Tricia)
+
+The saved data-shell product keeps its own assistant panel, routes, thread
+history, builder and draft policy. Engines use smrt-inference; human tool
+labels use smrt-chat; approval decisions/consumption use app-runtime's
+`OwnerApprovalAuthority` and chat's observation-only hold bridge; connection
+onboarding/settings use smrt-svelte's `ConnectAi` and `mountConnectAiRoutes`.
+
+Existing approvals **stay in `approvals`**: no data copy, migration or new
+approval ids. `Approval` is a compatibility model/endpoint facade and
+`approval-store.ts` adapts those rows to the shared authority. Pending requests
+retain their original indefinite lifetime, preview and requester. Decided
+history retains its timestamps/results. Atomic conditional updates decide and
+consume once across authorities; execution is recorded before live effects.
+Interrupted approvals never replay automatically. An old approved row without a
+result remains an unknown execution outcome and needs manual reconciliation.
+The adapter refuses storage with more than one installation tenant because the
+old rows do not encode tenancy; it cannot safely infer another ownership model.
+
+Opt-in shared compatibility options preserve generic record chips, compact
+connection wording/grouping, the settings-only ChatGPT model preference, API
+selection without a configured key, and remote sign-out confirmation. The
+shell keeps its existing sign-out fallback to the API preference, Fresh/Skip
+steps, detailed builder/code previews and draft-review link. Other applications
+keep the shared defaults. See [adapter contracts and validation](agents/shared-pieces.md).
+
 ## Run it
 
 Build once, then set up the data folder and the owner link, then start the
@@ -34,6 +60,17 @@ the app's state folder, not the data folder). If the link is lost, stop the
 server and run `smrt app recover` for a new one. Setup is loopback only and
 single use. Health: `GET /api/_runtime/health`.
 
+Desktop: the shell also mounts `GET /api/_runtime/owner-link`
+(`createOwnerLinkHandler`), the route the desktop wrapper opens its window on.
+It is loopback-only and answers 403 without the wrapper's per-launch secret, so
+it does nothing outside the wrapper. With that secret it uses `autoClaim`: the
+first launch creates the local owner (named after the OS account, no email) and
+signs them in, a later launch with a lost session cookie signs the sole owner
+back in, and the window lands on `/`. No owner form is shown. Under the wrapper
+the signed-out and `/setup` pages say to quit and reopen the app instead of
+naming terminal commands. Tricia, the packaged desktop product, is
+[`smrt-desktop/examples/tricia`](../smrt-desktop/examples/tricia/README.md).
+
 ## Builder operations (MCP tools and `POST /api/apps/<operation>`)
 
 The same names and parameters on both surfaces. A wrong-shaped argument is a
@@ -52,6 +89,8 @@ The same names and parameters on both surfaces. A wrong-shaped argument is a
 | `enableRecipe` | `recipe` |
 | `cleanUp` | `keep?` |
 | `importTemplate`, `exportTemplate` | `data`, `includeRecords?` |
+| `undoTo` (`app_undoto`) | `version` |
+| `startDraft`, `previewPublish`, `publishDraft`, `discardDraft` | `name?`; none; `expect?`; none. See [Draft then publish](#draft-then-publish-the-shell). `?target=live\|draft` (REST) names the copy a builder operation acts on |
 
 A FieldDef is `{ type, label?, required?, choices?, ref? }`; `type` is one of
 text, number, integer, boolean, date, money, choice, reference, json. Field names
@@ -65,16 +104,16 @@ owner). Writes must be same-origin `application/json`. Errors are
 
 | Route | Body | Response |
 |---|---|---|
-| `GET /api/shell/describe` | | `{ name, version, recipes, models: { [Model]: { kind: 'app'\|'shipped-subclass', label, table, className, extends, fields: { [name]: FieldDef }, ownFields: string[], methods: { [name]: { description, params } } } }, pendingApprovals }` |
-| `GET /api/shell/history` | | `{ versions: { version, parent, author, summary, createdAt, purged, current }[] }` oldest first |
-| `POST /api/shell/undo` | none | change result `{ version, summary, statements, snapshot, appRestartMs, ... }`; 409 if purged; **202** `PendingApproval` (with `preview.replaced`, the rows that would be overwritten) when the change being undone converted a field's type |
+| `GET /api/shell/describe?target=` | | `{ mode: 'live'\|'draft', draft: DraftInfo \| null, frozen, name, version, recipes, models: { [Model]: { kind: 'app'\|'shipped-subclass', label, table, className, extends, fields: { [name]: FieldDef }, ownFields: string[], methods: { [name]: { description, params } } } }, pendingApprovals }` (see [Draft then publish](#draft-then-publish-the-shell)) |
+| `GET /api/shell/history?target=` | | `{ mode, versions: { version, parent, author, summary, createdAt, purged, current, publish: { draftId, name } \| null }[] }` oldest first |
+| `POST /api/shell/undo?target=` | none | change result `{ version, summary, statements, appRestartMs, ... }`; 409 if purged; **202** `PendingApproval` (with `preview.replaced`, the rows that would be overwritten) when the change being undone converted a field's type |
 | `GET /api/shell/approvals?status=` | | `{ approvals: ApprovalView[], pending }`; `status` is `pending`, `approved`, `denied` or `failed` |
 | `POST /api/shell/approvals/<id>` | `{ approve: boolean }` | `{ id, status: 'approved'\|'denied'\|'failed', result?, error? }`; 404 unknown, 409 already decided |
-| `GET /api/shell/records/<Model>?limit=` | | `{ records: object[] }` |
-| `POST /api/shell/records/<Model>` | the record's fields | 201 the record |
-| `GET /PUT /api/shell/records/<Model>/<id>` | PUT: changed fields | the record |
-| `DELETE /api/shell/records/<Model>/<id>` | | **202** `PendingApproval`; nothing is deleted until approved |
-| `/api/app/<route>` (any method) | as the app's REST | the app's generated REST (`/api/app/chores` is the app's `/api/chores`); `DELETE` answers **202** `PendingApproval`; only the app's own collection routes are served (`sync/apply`, `_changes`, `_events` and unknown collections are 404) |
+| `GET /api/shell/records/<Model>?limit=&target=` | | `{ records: object[] }` |
+| `POST /api/shell/records/<Model>?target=` | the record's fields | 201 the record |
+| `GET /PUT /api/shell/records/<Model>/<id>?target=` | PUT: changed fields | the record |
+| `DELETE /api/shell/records/<Model>/<id>?target=` | | live: **202** `PendingApproval`, nothing is deleted until approved; draft: **200** `{ deleted: id }` |
+| `/api/app/<route>` (any method; copy in the `x-shell-target` header) | as the app's REST | the app's generated REST (`/api/app/chores` is the app's `/api/chores`); `DELETE` answers **202** `PendingApproval`; only the app's own collection routes are served (`sync/apply`, `_changes`, `_events` and unknown collections are 404) |
 | `GET /api/events` | | server-sent events |
 | `POST /mcp` | MCP Streamable HTTP | shell tools plus app tools, one policy |
 
@@ -83,8 +122,8 @@ owner). Writes must be same-origin `application/json`. Errors are
 where `action` is `{ kind: 'command', command } | { kind: 'tool', name, args } | { kind: 'rest', method, url } | { kind: 'record-delete', model, id }`.
 
 `GET /api/events` sends `event: ready`, then `event: shell` with JSON
-`{ type: 'changed', version, summary }` (definition changed: reload
-`describe`, the menu and the tool catalog), `{ type: 'records', model }`
+`{ type: 'changed', target, version, summary }` (definition changed: reload
+`describe`, the menu and the tool catalog), `{ type: 'records', target, model }`
 (`model` may be null: reload lists) and `{ type: 'approval', id, status, summary }`
 (`pending`, `approved`, `denied`, `failed`). A `: ping` comment every 25 s.
 
@@ -93,7 +132,8 @@ REST (`POST /api/apps/<op>`) and MCP tools (`app_definemodel`, `app_addfield`,
 `app_hidefield`, `app_renamefield`, `app_removefield`, `app_changefieldtype`,
 `app_removemodel`, `app_addmethod`, `app_enablerecipe`, `app_undo`,
 `app_cleanup`, `app_exporttemplate`, `app_importtemplate`, `app_describe`,
-`app_history`), plus `approval_pending`. There is no tool to decide an approval: only the
+`app_history`, `app_undoto`, `app_startdraft`, `app_previewpublish`,
+`app_publishdraft`, `app_discarddraft`), plus `approval_pending`. There is no tool to decide an approval: only the
 owner, signed in, decides in the UI, so no model-driven client (the assistant
 or an outside MCP client) can approve its own call. The risky ones
 (`addMethod`, `removeField`, `removeModel`, `changeFieldType`, `cleanUp`, an
@@ -105,18 +145,45 @@ or an outside MCP client) can approve its own call. The risky ones
 
 - `toolsFor(principal): Promise<CatalogTool[]>`: the merged catalog (`{ name, description, inputSchema, annotations?, side: 'shell'|'app', risky }`); empty unless `principal` is the owner.
 - `authorizeCall(principal, name): Promise<CatalogTool>`: throws `PolicyError` (`status` 401 no principal, 403 not the owner or unknown tool).
-- `callTool(principal, name, args)`: authorize and run. A risky call returns a `PendingApproval`.
+- `callTool(principal, name, args, scope?)`: authorize and run on the copies `scope` names (default: live). A risky call returns a `PendingApproval`.
 - `Principal = { id, tenantId, scopes? }`; get one from the request with `principalFromLocals(locals)` (`owner.ts`).
 
+## Settings
+
+`/settings` is the section menu (`ShellSettingsPage`): Appearance, Account,
+Layout and Shortcuts, plus **Assistant** (`/settings/assistant`: the engine,
+see Onboarding) and **Inference** (`/settings/inference`), the
+`InferenceSettingsPanel` from smrt-inference. Owner only: every load and action
+runs as the verified owner (a member or a stranger gets 403 before any body is
+read). Saving a provider key (`saveKey`) binds it to its endpoint, stores it in
+smrt-secrets (sealed under the app-runtime master key, created once into the
+vault key store; `SMRT_SECRET_MASTER_KEY` wins), and `keySet` is read back from
+the resolver's redacted view; the key itself never returns to the browser. The
+shell registers smrt-inference's user resolver at startup, which is what the
+assistant resolves through. The inference, preferences and secrets tables are
+created by `prepareShellSchema` on first start (`consumer.packages` in
+`smrt.config.ts` lists their packages). The load and writes are smrt-inference's
+`createInferenceSettingsController`, shared with the template.
+
 ## The assistant
 
-The dock (`src/lib/assistant/AssistantDock.svelte`, mounted for the owner in
-the layout) talks to `mountAssistantRoutes` (`src/lib/server/assistant/`).
+The chat column (`src/lib/assistant/AssistantPanel.svelte`, the `panel` of
+smrt-svelte's `AppShell` in `src/routes/+layout.svelte`, mounted for the owner)
+talks to `mountAssistantRoutes` (`src/lib/server/assistant/`). The layout is
+left sidebar, chat, content; the voice and assistant toggles and the user menu
+sit in the sidebar footer. The sidebar collapses to an icon rail (nav icons with
+tooltips, the footer controls as icons) from the chevron above the footer; the
+choice is remembered per owner, and the footer has no divider line (it would sit
+beside the chat composer's top border). The boundary between chat and content is a draggable
+separator (arrow keys, double-click resets); its width and the open state are
+remembered per owner. As a plugin view (iframe, or `?embed=plugin`) there is no
+chat and no toggles: the host app is the chat. Voice mode shows as not
+available yet; nothing connects speech to the assistant.
 Owner session required on all of them (401/403); the POST is same-origin.
 
 | Route | Body | Response |
 |---|---|---|
-| `GET /api/assistant/status` | | `{ configured: boolean, code?, message? }`; never a key, provider or endpoint. `code` is `assistant_not_configured` (no API key), `assistant_provider_refused` (subscription provider configured) or `ai_unavailable` (inference off) |
+| `GET /api/assistant/status` | | `{ configured: boolean, engine?, engineLabel?, code?, message?, action? }`; never a key, provider, endpoint or path. `engine` is `api`, `claude-code`, `codex` or `chatgpt`. `code` is `assistant_not_configured` (no API key), `assistant_provider_refused` (subscription provider configured), `ai_unavailable` (inference off), `agent_cli_missing` or `agent_cli_signed_out` (a local CLI engine that is not ready), `chatgpt_signed_out` (Sign in with ChatGPT not done); `action` is the link that fixes it |
 | `GET /api/assistant/threads` | | `{ threads: { id, title, updatedAt }[] }` newest first |
 | `GET /api/assistant/threads/<id>` | | `{ thread, messages: ThreadMessage[] }`; 404 for a missing or foreign thread |
 | `POST /api/assistant/turn` | `{ message, threadId? }` | `text/event-stream`, `event: turn`, JSON `TurnEvent` (below). **503** `{ type: 'unavailable', configured: false, code, error }` when the assistant cannot run; 409 while another turn is running |
@@ -124,7 +191,7 @@ Owner session required on all of them (401/403); the POST is same-origin.
 `TurnEvent` (`src/lib/assistant/events.ts`): `thread {threadId}`, `text {delta}`,
 `tool_call {id,name,args}`, `tool_result {id,name,ok,summary}`,
 `approval_required {id,name,approvalId,summary,preview}`,
-`approval_decided {id,approvalId,status}`, `error {code,message}`,
+`approval_decided {id,approvalId,status}`, `error {code,message,action?}`,
 `done {stop}` (`complete | max_steps | max_tokens | timeout | aborted | waiting | error`).
 Closing the request (the dock's Stop button, a closed tab) aborts the model
 call, the running tool and any wait.
@@ -140,13 +207,28 @@ call, the running tool and any wait.
   wait times out or the client leaves, the model is told it is waiting, the
   turn ends as `waiting`/`aborted`, and the Approval stays pending, unapplied.
   The assistant has no way to set the engine's `approved` flag.
-- **Engine.** `@happyvertical/ai` through core's inference tiers
-  (`resolveInferenceTarget`, tier `good`, override `SMRT_APP_SHELL_ASSISTANT_TIER`).
-  The key comes from the `ai` block of `smrt.config.ts`, `SMRT_AI_*` or the
-  provider's own variable (`ANTHROPIC_API_KEY`), read only server side, never
-  logged or sent to the browser, until bring-your-own (#4666) lands. Subscription
-  providers (`claude-cli`, `chatgpt-plan`) are refused. With no key,
-  status/turn answer the typed not-configured state and the dock shows it.
+- **Engines.** Three, chosen by the owner (the non-secret `assistant`
+  preference, `engine` = `api` | `claude-code` | `codex` | `chatgpt`; default
+  `api`):
+  - **API key** (`api`): `@happyvertical/ai` through core's inference tiers
+    (`resolveInferenceTarget`, tier `good`, override
+    `SMRT_APP_SHELL_ASSISTANT_TIER`). The key is the owner's, pasted once in
+    **Settings > Inference** (`/settings/inference`, see below), or the
+    deployment's: the `ai` block of `smrt.config.ts`, `SMRT_AI_*` or the
+    provider's own variable (`ANTHROPIC_API_KEY`). The saved key wins, then the
+    stored tier bindings, then config/env, so a desktop app launched from
+    Finder works with no environment. The key is read only server side, never
+    logged or sent to the browser. Subscription providers (`claude-cli`,
+    `chatgpt-plan` from configuration) are refused here, as is any in-app
+    Claude subscription login.
+  - **Local agent CLI** (`claude-code`, `codex`): the turn runs through the
+    person's own, already installed and signed-in Claude Code or Codex
+    (`src/lib/server/agent-cli/`, `assistant/agent-turn.ts`). See below.
+  - **ChatGPT** (`chatgpt`): the owner's own ChatGPT plan through OpenAI's
+    official Sign in with ChatGPT flow (see below).
+  With no usable engine, status/turn answer the typed not-configured state, the
+  dock shows it with a link to fix it, and it checks again each time it is
+  opened, so a saved key or a finished sign-in needs no restart.
 - **Bounds** (`DEFAULT_LIMITS` in `turn.ts`): 8 model rounds, 2048 output
   tokens per call, 60 000 tokens per turn, 4 calls per round, 60 s per model
   call, 180 s of model/tool time per turn, 15 min per approval wait.
@@ -154,6 +236,261 @@ call, the running tool and any wait.
 - **Threads** persist in shell.db (`assistant_threads`, `assistant_messages`).
 - **Tests** inject a stub model (`modelFactory` option, `test-helpers.ts`).
 
+The reusable CLI engine, ChatGPT model adapter and connection diagnostics live in
+[smrt-inference/server](../inference/agents/engines.md). The shell supplies its
+owner token scope, MCP route, thread persistence, draft guidance and approval
+presentation through thin host adapters; its policy remains the authority.
+
+### Sign in with ChatGPT (a preview for open source apps)
+
+OpenAI's official flow for local open source apps, a **preview**: the
+authorization basis and its limits are in OpenAI's
+[preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations).
+Claude has no equivalent here: its subscription stays on the Claude Code
+engine below, and `claude-cli` and any in-app Claude subscription login stay
+refused.
+
+- **Sign-in** (`lib/server/chatgpt.ts`, smrt-inference's
+  `createChatGPTPlanConnection`): "Sign in with ChatGPT" on `/welcome` and in
+  Settings > Assistant. Under the desktop wrapper this process opens the system
+  browser (`open` / `xdg-open` / `cmd /c start`) after checking the address is
+  https on `auth.openai.com`; in a plain browser session the page shows a normal
+  link. The SDK's loopback listener (127.0.0.1, PKCE, dynamic client
+  registration, OIDC validation) receives the callback, the page polls until it
+  is signed in and then selects the engine.
+- **Credentials** live only in the SDK's own owner-only file,
+  `<data root>/chatgpt/chatgpt.json` (directory `0700`, file `0600`, outside any
+  source tree; the encrypted backup that seals the data root seals it too).
+  This app never reads it and never logs, returns or copies a token: the
+  provider gets a `{ accessToken(clientId) }` handle, the browser sees
+  signed in / signing in / an account label. Sign out clears it and asks OpenAI
+  to revoke. `SMRT_APP_SHELL_NAME` sets the app name OpenAI's page shows.
+- **The turn** (`assistant/model.ts`): the `chatgpt` engine asks the resolver
+  smrt-inference composed (`installShellInference`) with its own request name,
+  and runs ONLY on the `chatgpt-plan` target that sign-in produced; with nobody
+  signed in it is unavailable ("Sign in with ChatGPT"), never an API key, never
+  another provider. The loop uses `chat()` with `onProgress` (the provider's
+  `stream()` rejects tools) and a tool namespace (`shell_tools`); it sends no
+  `maxTokens`, sampling, `user`, response format, reasoning option or forced
+  tool choice, which the preview refuses. The model is the owner's pick in
+  Settings > Assistant, else the first model in the account's catalog.
+  Approvals, the offer gate and the deny list are unchanged.
+- **Failures** become dock messages: usage limit, revoked session and workspace
+  refusals (the last two with "Sign in again", linking to
+  Settings > Assistant), "unavailable, still signed in", and the preview's
+  unsupported-capability refusal. Only the error class and code are logged.
+- **Tests** stub the provider (`assistant/chatgpt-engine.test.ts`), the
+  connection (`routes/onboarding-chatgpt.test.ts`) and the opener
+  (`lib/server/chatgpt.test.ts`); nothing signs in.
+
+### The local agent CLI engine
+
+**Rule (two lines).** No in-app Claude subscription login: this app never
+offers Claude.ai sign-in and never collects, stores or passes on those
+credentials. The local-CLI engine only runs the person's own, unmodified Claude
+Code or Codex, signed in through the vendor's own flow and billed to them
+([Claude Code legal and compliance](https://code.claude.com/docs/en/legal-and-compliance)).
+Product names appear as plain text, no logos.
+
+- **Detection** (`agent-cli/locate.ts`, `detect.ts`): the executable on PATH,
+  then the usual install places (`~/.local/bin`, `~/.claude/local`, Homebrew,
+  `/usr/local/bin`, npm/pnpm/volta/bun/nvm bins, Windows equivalents), then the
+  person's login shell (`command -v`), so an app started from Finder finds it.
+  Version and sign-in come only from the tool's own commands (`--version`,
+  `claude auth status`, `codex login status`); no credential file or keychain
+  item is read, and the browser sees only installed / version / signed in. Not
+  installed: a link to the vendor's install page, nothing is installed for them.
+  Windows runs a real `.exe` (a `.cmd` shim is not started, there is no shell).
+- **Connect** (`agent-cli/login.ts`): signed out, it starts the tool's own
+  sign-in (`claude auth login`, `codex login`), which opens the vendor's page
+  in the system browser; the app only watches the process end, then asks the
+  status command again.
+- **A turn** (`agent-cli/session.ts`, `assistant/agent-turn.ts`):
+  `claude -p --output-format stream-json --verbose --include-partial-messages`
+  or `codex exec --json`, the prompt on stdin, streamed JSON mapped onto the
+  same `TurnEvent`s (the dock has no engine-specific code). Locked down:
+  - Tools: only the shell's, from `/mcp`, with the same owner policy and
+    Approval gate. Every built-in tool that touches the machine is off (Claude:
+    `--tools ""` plus a strict MCP config; Codex: shell, exec, apps, plugins,
+    hooks, sub-agents, code mode and more disabled, read-only sandbox, approvals
+    never, no web search). The stream is also checked: any other tool, or an
+    unknown Codex item kind, stops the turn.
+  - Token: a short-lived (15 min), owner-bound, `assistant.use`-scoped
+    app-runtime local MCP token, issued under one holder (each turn rotates the
+    last) and revoked when the turn ends. It is in the child's environment only:
+    never argv, a file or a log, and only ever sent to a loopback URL. Claude
+    reads it through `${VAR}` in its MCP header config; Codex through
+    `bearer_token_env_var`.
+  - Environment: an allow-list (`agent-cli/env.ts`); `ANTHROPIC_*`, `OPENAI_*`,
+    `CODEX_*`, `CLAUDE_CODE_*` and `SMRT_*` never reach the child, so the tool
+    uses the person's own login. Working directory: an empty private folder
+    `<data root>/agent-cli/work`. Claude loads none of the person's settings,
+    hooks, skills or plugins; Codex ignores their `config.toml` and rules.
+  - Approvals: a risky call returns `pending_approval` from `/mcp`; the turn
+    shows the card (`approval_required`) and ends `waiting`. Only the owner's
+    decision applies it (`Approval.decide`). The tool is told not to retry.
+  - Bounds: 10 minutes per turn; cancel (the Stop button) and timeout kill the
+    whole process tree. A later turn resumes the tool's own session (stored on
+    the thread's last assistant message), else starts a new one.
+  - Known gaps: Codex still offers its own code-mode `exec` and `apply_patch`
+    tools to the model (no flag removes them; the read-only sandbox and the
+    stream guard are what stop them), and it still reads the person's own global
+    Codex instructions file (its home folder AGENTS.md). Codex 0.162.1 needs `--enable mcp_2026_07_28` to
+    reach `/mcp`. The tool keeps its own session transcript in its own folder.
+- **Tests:** stub CLIs (shared `smrt-inference/test-support`) over the real
+  `/mcp` route (`assistant/agent-turn.test.ts`); fake binaries on a temp PATH
+  (`agent-cli/detect.test.ts`). An opt-in run against a real installed CLI:
+  `REAL_AGENT_CLI=claude-code|codex npx vitest run
+  src/lib/server/assistant/agent-cli.manual.test.ts` (spends the person's own
+  subscription, one short turn).
+
+## Onboarding
+
+`/welcome` (owner only; an owner with an empty app who has not finished or
+skipped it is sent there once): **1. Connect your AI** (Use Claude Code,
+Sign in with ChatGPT, plus Advanced: the full inference setup at
+`/settings/inference`, which links back; Codex is an advanced option under
+Settings > Assistant, not on this page) and **2. How do you want to start?** (Fresh: an empty app with the
+assistant dock open; Wizard: shown, disabled, coming soon). Skippable. Finished
+or skipped is stored as `onboarding` in the `assistant` preference
+(`agent-cli/settings.ts`, the smrt-preferences store smrt-inference also uses;
+not a member of the `inference` payload, which the settings panel replaces whole,
+and not a tier target of core's inference model). **Settings > Assistant**
+(`/settings/assistant`) switches engine and re-opens the steps. JSON routes
+(owner only, same-origin writes): `GET /api/shell/onboarding[?fresh=1]`,
+`POST /api/shell/onboarding/{connect,engine,complete,skip}`, and
+`GET`/`POST /api/shell/onboarding/chatgpt` (start, sign-out, model;
+`lib/server/onboarding.ts`).
+
+## Draft then publish (the shell)
+
+A draft is a test copy of the person's app (its definition and its records at
+that moment) that they build in while the live app keeps working. Rules the UI
+can rely on:
+
+- One draft at a time. While it is open **live structure is frozen** (frozen
+  again after every restart); live **records** keep working (create, edit,
+  delete, reports, the app's own REST and tools).
+- A draft's own records are throw-away test data and are **not carried** at
+  publish; records added to live meanwhile are kept.
+- A publish lands as N ordinary live versions (summaries tagged
+  `[draft: <name>] ...`) and can be undone in one step with `undoTo`.
+- **Every request names its copy**, there is no "current host": REST uses
+  `?target=live|draft` (absent = `live`; anything else is 400), `/api/app/*`
+  uses the `x-shell-target` header (its query string belongs to the app), MCP
+  uses the URL. `target=draft` with no draft open is 404 `no draft open`.
+- A structural request that names `live` while a draft is open is **409**
+  `The draft "<name>" is open, so the live app's structure is frozen. Make this
+  change in the draft (target=draft), or publish or discard the draft first.`
+- A risky change in the draft (remove a field or model, change a type, add a
+  method, delete a record, a DELETE through the app's REST) applies at once: the
+  draft host approves its own. On live it is an Approval, as before.
+
+### Routes (owner only: 401 signed out, 403 anyone else; writes same-origin JSON)
+
+| Route | Body | Response |
+|---|---|---|
+| `GET /api/shell/draft` | | `{ draft: DraftInfo \| null, view: 'live'\|'draft' }` |
+| `POST /api/shell/draft` | `{ name? }` | **201** `DraftInfo`; 409 if one is already open |
+| `POST /api/shell/draft/preview` | none | `{ draft: DraftInfo, preview: PublishPreview }`; 404 no draft; 409 unpublishable |
+| `POST /api/shell/draft/publish` | `{ expect? }` (the preview's `digest`) | **always 202** `PendingApproval`; 409 when `expect` no longer matches (review again) |
+| `POST /api/shell/draft/discard` | `{ draftId? }` | `{ discarded: name }`; the owner's direct action (the UI confirms first); 404 none, 409 wrong id |
+| `GET /api/shell/draft/view` | | `{ view }` (`live` whenever no draft is open) |
+| `PUT /api/shell/draft/view` | `{ view: 'live'\|'draft' }` | `{ view }`; `draft` with no usable draft is 409 |
+| `POST /api/shell/undo-to?target=` | `{ version }` | the change result; 202 `PendingApproval` when an undone change converted a field's type; 409 purged |
+| `POST /api/apps/{startDraft,previewPublish,publishDraft,discardDraft,undoTo}` | as the tools | the same operations as generated REST; `publishDraft` and `discardDraft` answer **202** (an Approval) |
+
+`DraftInfo = { id, name, status: 'open', baseVersion, version, changes,
+createdAt, createdBy, liveVersion, liveFrozen, publishable, problem, recovery }`.
+`changes` counts the changes made in the draft; `version` is null when its copy
+cannot be opened. `publishable: false` comes with a `problem` sentence (the data
+folder was restored or moved so the draft names another live app; its files are
+missing; it cannot be opened): show it and offer Discard (the only way out).
+`recovery: 'rolled-back'` means a restart interrupted a publish and it was
+undone; the draft is still open, publish again.
+
+`PublishPreview = { digest, risky: true, fromVersion, toVersion, versions:
+{ version, draftVersion, author, summary, steps, statements }[], definition:
+DefinitionDiff, archives: { values, tables }, methods: { model, name, change:
+'added'\|'changed'\|'unchanged', description, code, ... }[] }`. EVERY method of
+the final definition is listed in full (draft code reaches live at publish, show
+it). Archive counts are of that moment and can drift. The publish Approval's
+`preview` is this object plus `draft` (the name); its `action` is
+`{ kind: 'publish-draft', draftId, draftName, digest }`. Approving applies
+exactly that chain and **fails** (status `failed`, the draft stays open) if the
+draft changed since. Approve through `POST /api/shell/approvals/<id>` as for any
+Approval. A discard asked by a tool is `{ kind: 'discard-draft', draftId,
+draftName }`. A successful publish result is `{ version, versions, summary,
+archives, appRestartMs, draft }`.
+
+`describe` for each copy: `GET /api/shell/describe?target=live` is
+`{ mode: 'live', frozen: true, draft: DraftInfo, ... }` while a draft is open;
+`?target=draft` is `{ mode: 'draft', frozen: false, draft: DraftInfo, ... }`;
+with no draft `draft` is null and `frozen` false. A view of live therefore has
+what it needs for the draft strip from the same call.
+
+History: `GET /api/shell/history` (live) tags every version a publish made with
+`publish: { draftId, name }` (group rows by `draftId`; "Undo this publish" is
+`POST /api/shell/undo-to { version: <parent of the group's first row> }`).
+`?target=draft` lists only changes made in the draft (the live base version is
+left out).
+
+Events (`GET /api/events`) now say which copy changed:
+`{ type: 'changed', target: 'live'|'draft', version, summary }`,
+`{ type: 'records', target, model }` (reload only the view of that copy) and
+`{ type: 'draft', status: 'started'|'published'|'discarded'|'unpublishable', id, name }`
+(everything is stale: reload describe, history, lists).
+
+### Tools and MCP
+
+Tools: `app_startdraft` (`name?`), `app_previewpublish`, `app_publishdraft`
+(`expect?`; always a `pending_approval`), `app_discarddraft` (a
+`pending_approval`), `app_undoto` (`version`). `/mcp` names its copy in the URL,
+fixed per endpoint: `/mcp` is live (builder tools are refused while a draft is
+open; record tools work), `/mcp?target=draft` is the draft, and
+`/mcp?scope=assistant` is the assistant's split, resolved per call. In code,
+`callTool(principal, name, args, scope)` takes a
+`CallScope = { records, structure }` (`scopeFor('draft')` puts both on the
+draft); the default is live.
+
+### The assistant
+
+All engines (API key, ChatGPT plan, Claude Code, Codex) use the same scope
+(`assistant/scope.ts`), resolved at every call. No draft: everything is live,
+approvals as before. A draft open: builder tools go to the draft with no
+per-change approval and record tools to the copy the person is viewing (the
+saved view). The system prompt and every turn input carry the current mode (including resumed CLI sessions); stored user messages stay unchanged. `tool_result` events
+carry `copy: 'live'|'draft'` while a draft is open, and a turn that changed
+structure in the draft closes with "I made that change in the draft ... so the
+live app is unchanged". Publishing through the assistant raises the publish
+Approval and holds the turn; it never applies.
+
+## Draft then publish (engine API)
+
+The engine can run a second host, a draft, over a copy of the live data and
+later replay the draft's changes onto live. Rules and failure behaviour are in
+[agents/engine.md](agents/engine.md); the API on `AppHost` (exported from
+`src/engine`):
+
+```ts
+const live = await AppHost.open(dir, { store });
+const draft = await live.forkDraft(draftDir, { store: emptyDraftStore }); // autoApprove on
+live.setFrozen(true); // live keeps serving records; structural commands are refused
+// ...build in `draft` (draft.execute / draft.create ...)...
+const preview = await live.previewPublish(draft); // diff, archives, all method code, digest
+await live.publishDraft(draft, {
+  author, approved: true, expect: preview.digest, draftName: 'Spring cleanup',
+}); // N ordinary live versions; any failure leaves live's app.db untouched
+live.setFrozen(false);
+await draft.discard(); // closes it and deletes only the directory fork made
+await live.execute({ type: 'undoTo', version: base, from: live.version }, { author });
+```
+
+`AppHost.open(dir, { store, autoApprove: true })` only works on a directory the
+engine marked as a draft. A host start reconciles an interrupted publish
+(`host.recovery`). A `VersionStore` may implement the optional atomic
+`commit(records, current)`.
+
 ## First-run schema
 
 `prepareShellSchema(db)` (`src/lib/server/schema.ts`) creates the tables of every
@@ -172,3 +509,21 @@ pnpm --filter @happyvertical/smrt-app-shell typecheck
 ```
 
 See [AGENTS.md](AGENTS.md) for the invariants and [agents/engine.md](agents/engine.md) for the engine.
+
+### Draft UI
+
+The content header offers **Start draft**, then **Live / Draft**, the unpublished
+change count, **Discard** (confirmed), and **Review and publish**. Starting a draft
+opens its view; switching copies saves the owner's choice and returns home. In
+Draft, a warning explains that test records are thrown away and draft-only models
+have a **new** marker. Chat shows **Building in draft**; tool chips name the copy,
+including after reopening a thread.
+
+`/draft/review` rehearses the publish and shows definition changes, conversions,
+archive counts, and all final method code. **Publish** requests a digest-pinned
+Approval; the existing approval card resolves it. A changed-chain failure offers
+**Review again**. Counts can drift as live records change. History groups each
+publish under its draft name; **Undo this publish** returns to its first parent
+(and takes back subsequent changes), with an Approval if needed. Lifecycle events
+refresh the bar and pages without reloading. An unusable draft explains the problem
+and keeps Discard available. See [UI validation](agents/draft-ui.md).