Owner settings inventory

This page lists every setting an owner can change, which API stores it, and which surfaces can set it today. The approved October 2026 direction amends VUH-1813's “every UI” rule in AGENTS.md:

• CLI: covers every setting; it is the agents' interface.
• App and desktop pet: cover the Common tier through the same API.
• Advanced: stays in the CLI. Existing controls elsewhere are not a mandate to expand those surfaces.
• Dashboard: billing and account only.
• TUI: a maintained surface; existing controls remain supported.

This is the coverage target, not a claim that every CLI setting is implemented. The dated inventory below records observed capability, including old controls outside today's scope. Missing Advanced app controls and body-settings dashboard controls are no longer parity gaps. No controls are removed by this doc change.

Audited 2026-10-07 against clankie 6f165578, clankie-app 3068dd9 and clankie-ops 244e4de. Core follow-up on 2026-10-07 adds host writes and moves fleet, persona, voice, Discord fields, holds and Linear follow/wake onto owner APIs; app/dashboard controls remain separate work. When a surface or route changes, update this page.

How to read it

• Tier. Common: the owner changes it; keep it up front. Advanced: sensible default, configured through the CLI. Single: single-surface by nature.
• API. The HTTP route that owns the value. "None" means no API writes it. Then the value lives only in ~/.config/clankie/settings.json, and only local tools can change it.
• Surfaces. CLI/TUI are the local clankie commands and console. App is clankie-app (phone, web and desktop). The desktop pet shares the Common coverage target; it has not been separately audited here. Dash is the account page (clankie-ops/apps/fleet/web).
  • ✓ sets it through the API.
  • file: the local CLI or TUI writes settings.json directly instead of calling the API.
  • view: read-only.
  • adv: only reachable as a raw field in a generic Advanced list.
  • off: built but shipped disabled.
  • —: absent.

How each surface reaches the API

• App and hosted console. They reach a body through the public gateway. Owner settings ride one of two paths:

  • the relay's settings projection (apps/relay/src/operator-conversations.ts, OPERATOR_RELAY_DEVICE_ROUTES, which needs the terminalControl grant);
  • the hosted operator bridge (hostedOperatorAllows in packages/protocol/src/hosted-operator.ts).

  A route missing from both lists is unreachable from a phone, even though it exists on the body.

• Local CLI and TUI. Fleet, persona, voice, Discord fields, worker-account holds and Linear follow/wake use the same owner API as devices, including revision fences. Host availability settings also use the owner API. A stale write is refused without retry. Machine bootstrap exceptions are listed in ADR 0248.

• Discord settings. These are the only settings with a host-supplied definition (DISCORD_SETUP_DEFINITION, ADR 0222): labels, help and choice labels come from @clankie/protocol. Every other domain uses typed snapshots.

Inventory

Clankie's own seat (2026-10-25)

captain.seat is a Common setting: app (the default), claude or codex. GET/POST /v1/captain/seat stores it behind owner or Take Control authority with a revision fence. clankie seat show|set covers the CLI; the desktop onboarding work in VUH-2784 consumes the same route. No new TUI or dashboard control is added. Saving never launches a harness; seat start is a separate, idempotent action on this Mac. Worker harness/model preferences remain under fleet.hire. See the CLI contract.

1. How he talks: Discord attention

2. Where he lives: Discord server

3. His mind: model and voice

Pet skins use the separate appearance.petSkin pack ID on that same fenced API. Unset/null selects original 2D Clankie; the Mac pet offers previews of original Clankie and Hoodie (3D). Unsupported pet surfaces keep the saved ID and render original Clankie. This does not change World/chat lead art.

4. How the fleet works

5. Projects

6. Worker accounts

7. Connections

8. Machines and availability

9. Devices, privacy and support

10. Play

11. Account and billing (hosted only)

These live only on the hosted account page, and should stay there. Plan changes, payment cards, invoices, credit top-ups, overage caps, account deletion and sign-out all pass through Stripe or Cognito. The app shows credits read-only.

Historical follow-ups: Discord ownership and room-skill controls in clankie-app (including its web/desktop surfaces, VUH-1835) and clankie-ops hosted dashboard (VUH-1836) are named follow-ups to VUH-1831. Core API, CLI and TUI ship together; older clients preserve these settings on unrelated saves.

Historical parity gaps (October 7 audit)

Scope amended 2026-10-23. The entries below retain the audit history; dashboard body settings and Advanced app settings are not launch requirements. CLI coverage and Common app/pet controls are the current target.

Status 2026-10-07. Gaps 1–4 are closed in core (669b2946, ADR 0248) and the app (clankie-app 72bb526…88800dc, iPhone captures in that repo's docs/testing/2026-10-07-vuh-1813-settings-parity/). Still open: the hosted dashboard for these settings (gap 5), the app hire page's pi default harness, and iPad layout under VUH-1810. The history below records the gaps as found.

1. Discord attention in the app.
   • The app has no chattiness or reply policy, and the wake trigger appears only as a raw Advanced chip that cannot go back to the body default.
   • The relay does not carry /v1/operator/persona.
   • The dashboard's wake selector exists only on the free-bot card, and the edge it needs is not deployed in production (VUH-1765, VUH-1689).
   • The labels live only in the TUI (WAKE_TRIGGER_LABELS, CHATTINESS_LABELS), not in @clankie/protocol.
2. Fleet hire defaults (harness, model, effort, "no preference").
   • No API writes fleet.hire; only the local CLI and TUI can.
   • The app's hire page also defaults the harness to pi instead of "no preference".
3. Worker account holds.
   • No API holds or releases an account, and GET /v1/worker-accounts is not relayed, so the app cannot even read it.
4. Host availability core gap resolved.
   • Revision-fenced host write APIs and device forwarding now exist for host.keepAwake and host.autoUpdate, with shared protocol wording.
   • The app binds both switches under Keeping Clankie available.
5. Hosted dashboard Discord settings are built but off (VUH-1689), and its Model section is view-only.
6. Core owner paths unified. Fleet, persona, voice, Discord set, holds and Linear follow/wake now read and write the owner API. Every update uses the returned revision; conflicts require a fresh read and review.
   • First-run machine wiring, local account profile registration, provider credentials and the signed webhook URL remain separate setup operations.
   • See ADR 0248.
7. Voice brain, Linear follow and wake, email: app controls remain follow-up work. Voice and follow/wake routes are now relayed; email still has no API.
8. Project details:
   • The fleet size/models override can't be changed after a project is created.
   • The app can't edit a role's harness and omits the ultra effort.
9. Guidance text outside protocol.
   • FLEET_SIZE_GUIDANCE and FLEET_MODEL_GUIDANCE live in @clankie/settings, so the app writes its own copy.
10. Historical cross-surface follow-ups:
    • VUH-1782 gates ("Just do it / Clankie decides / Ask me" plus presets), with the VUH-1809 mailbox following those gates.
    • Web (VUH-1793) and desktop (VUH-1791) inherit the app's settings.

Grouping the app should converge on

These groups mirror the inventory sections above, so each one covers a single concern:

1. How he talks
2. Where he lives (Discord)
3. His mind
4. How the fleet works (worker accounts appear here too)
5. Projects
6. Connections
7. Machines
8. Devices and privacy

Within each group, app and pet expose the Common rows. Advanced settings, including play and raw Discord fields, stay in the CLI. Dashboard settings are limited to billing and account. Existing TUI controls remain supported.