Settings foundation: typed registry and CLI management

[SarthakWade]

Problem

Headless has one local preference, startup-presentation, implemented directly in the CLI with macOS UserDefaults. There is no central schema, Linux persistence, discovery command, reset behavior, or classification of settings that agents may change.

Proposed contract

Define a typed settings registry with key, type, default, platform scope, validation, restart behavior, and access class. Expose:

headless config list
headless config describe KEY
headless config get KEY
headless config set KEY VALUE
headless config reset KEY

Use UserDefaults on macOS and an XDG config file with mode 0600 in a 0700 directory on Linux. Migrate startup-presentation without losing its current value.

Boundaries

Security invariants are policies, not settings. The registry must never allow arbitrary JavaScript, TCP control, unsafe schemes, downloads, sandbox weakening, or bypassing sensitive-diagnostics gates. Unknown keys and invalid values fail closed. Settings must be classified as agent-readable, agent-writable, or user-only.

This changes the agent-facing contract and requires an architecture-decision entry before implementation.

Acceptance criteria

• One schema drives parsing, help, defaults, validation, and storage.
• CLI coverage includes list, describe, get, set, reset, unknown keys, invalid values, and platform-specific keys.
• Writes are atomic and permissions are verified on Linux.
• Existing startup-presentation behavior and tests remain compatible.
• COMMANDS, phase documentation, and capabilities are updated from authoritative sources.
• Protocol, runtime, build, and relevant E2E suites pass.

[yashranaway]

Still worth doing, but don't block the vault on a Settings window.

Credential authorization is not an agent-writable setting. If #157 needs "aliases only" vs "allow direct fill", put that in this registry as user-only or session-scoped. #155 and the unsigned vault should not wait on Cmd+,.

[yashranaway]

Still worth doing, not on the vault critical path. #155 should not wait on this.

When it ships: security invariants stay policies, not toggles. Classify keys as agent-readable, agent-writable, or user-only. Credential authorization is never agent-writable.