App Creator

Use when the user wants to build a new Adom "app", a mini web server that renders its UI in a Hydrogen webview tab.

Every Adom app CLI takes an ai-thread name on every call: a global --ai-thread flag, exactly like adom-bridge-cli. The CLI forwards it to the app's server, anonymous state-changing calls get a teaching refusal (caller_identity_required, same code ab uses), and the name keys logs, registry entries, and snapshots. Read when building any app server or CLI, or when a call is refused with caller_identity_required. Trigger words: ai-thread, ai thread name, --ai-thread, aiThread, name your thread, who is calling, caller identity, caller_identity_required, thread attribution, anonymous caller, identify your thread.

The SSE live channel every Adom app builds between its server and its frontend, and the CLI verb relay that rides it: the AI calls the app's binary, the CLI posts to the server, the server pushes a directive over SSE, and the live page reacts (auto-click a button, expand a menu, glide a fake cursor, swap rendered data in place, reload). Read when wiring any app's frontend to its server. Trigger words: sse, server-sent events, live channel, event stream, drive the frontend from the cli, auto-click, fake cursor, ai cursor, push to the ui, update without refresh, swap data live, websocket vs sse, broadcast state, EventSource.

The teaching-refusal pattern that makes AI callers behave: hints, reprimands, and reason-gated verbs. Any action beyond the norm (foreground a window, delete, overwrite, publish, kill) is refused until the caller re-calls it with a written reason, which forces the AI to actually deliberate. Modeled on pup's foreground_reason_required gate and ab's gated verbs and confirm flows. Read when designing any app server's endpoints. Trigger words: reason required, reason_required, foregroundReason, teaching refusal, reprimand the ai, gate a verb, disruptive action, make the ai think, confirm flow, error hint, beyond the norm, escalation verb.

How an Adom app server cleans up after itself: the 24h idle reaper with lossless per-thread snapshots, the instance registry with <app> ls and reuse-instead-of-respawn, --port auto, and version-drift detection after package updates. Read when building any app server, or when a container has accumulated zombie servers. Trigger words: server lifecycle, clean up my servers, zombie server, leaked server, orphaned server, idle shutdown, self shutdown, ttl, reaper, instance registry, list instances, reuse instance, already running on port, duplicate instance, stale instance, version drift, port auto, too many node servers.

Almost every Adom app ships a Settings window, even for a single toggle. Covers why, the gear-icon entry point, server-side persistence (GET/POST /settings, never localStorage), AI parity via curl, and the standard entries (TTL, default surface, dev mode). Read when scaffolding any app UI. Trigger words: settings window, settings panel, app settings, gear icon, toggle mode, preferences, configure the app, settings endpoint, persist settings.

Which browser surface an Adom app should open its UI in, and how to respect the user's preference: wv (Hydrogen webview tab, the default), extwv (sites that refuse framing), hbw (Hydrogen's standalone browser window), pup (the AI's own logged-out Chrome on the desktop), nb (the user's real signed-in browser). Covers the decision table, the show verb with --surface, the proxy-URL platform trap, background-first etiquette, and window reuse. Read when wiring any app's show/open path. Trigger words: which surface, webview vs pup, open in wv, open in hbw, open in nb, show the app, surface preference, browser picker, where to open, display surface, simple browser.