# Settings UI **Status:** Approved target-state behavior — Advisor configuration integrated **First minimal realization:** I0/I1 **Deepens across increments.** ## Page Job Make AWP's typed configuration, policy, advisors, accounts/connections and defaults inspectable and editable at the correct scope without configuration-file archaeology. ```text System Settings Project Settings Plan Settings Task settings/context Run resolved configuration (read-only snapshot where appropriate) ``` ## Scope and Provenance Every setting shows: ```text label / purpose current effective value source scope (System/Project/Plan/Task) inherited chain override indicator validation / allowed values change consequence locked/read-only reason if not editable [Reset to inherited] when applicable ``` Do not hide locked configuration; show it disabled with explanation. ## Information Architecture Categories follow product concepts rather than config file names: - General / project identity; - Planning defaults / participation; - Delivery / Quality / CI / Deployment defaults; - Factory / execution profiles; - **Advisors / Personas**; - Accounts / Models / Providers; - Connections / credentials (identity/scope only, not secret value); - Autonomy / Human-in-the-loop policy; - Cluster/execution policy where applicable; - Notifications/communications; - Advanced / diagnostics. Search finds settings by label/key/purpose/provider/persona. ## Advisors / Personas Activates with I3. Manage built-in and custom `AdvisorPersona` definitions without turning instructions into an authority bypass. Collection/detail shows where relevant: ```text name / role / purpose built-in vs custom active/inactive scope policy model/account selection policy allowed query capabilities allowed proposal/command capabilities page-context default thread retention policy current version / updated by / updated at usage/default relationships ``` Initial built-ins: ```text Project Manager AWP Advisor ``` Future custom/built-in examples can include DBA, CI Expert, Release Expert, Security Advisor and Architecture Advisor. ### Persona editing Material behavior changes create a new persona version rather than rewriting historical turn attribution: ```text instructions scope policy capability set model selection policy retention behavior ``` UI previews consequence, such as: ```text future threads/turns use version 4 existing historical turns retain version 3 Project default advisor changes for new threads capability removed from future proposals ``` Custom instructions cannot broaden system capability/data-access ceilings. Locked system/built-in safety fields remain visible with explanation. ### Create / clone Prefer `Clone persona` for custom experts so users can start from a known role contract. One primary action per create/edit view. No raw provider key/token is entered into persona instructions. Model/account choices reference canonical Account/Connection policies. ## Connections / Accounts Manage reusable Connections, accounts/models/provider health and project bindings. Secret entry/update uses trusted flow; after save, show metadata/status only. Project scope shows only allowed binding subset and capability/resources. ## Autonomy / Policy Preset 0–100 editor plus concrete category rules. User can see what the preset actually means and customize categories. Security ceilings are visibly non-broadenable. Advisor proposal/action capabilities are constrained by the same Policy/capability model; persona settings do not create a second autonomy system. ## Mutations Before applying consequential changes, show effect: future runs/threads only, replan/readiness invalidation, restart, Approval required, capability reduction, etc. Save feedback is immediate and revision-safe. ## States Loading, validation error, conflict/stale revision, inherited/no override, provider degraded, reauth required, unsaved changes, save pending/succeeded/failed. Advisor category additionally covers no personas, built-ins only, custom persona validation error, inactive persona, historical version view and model/provider unavailable. ## Responsive / Accessibility Desktop: category sidebar + settings form/detail. Small: category drill-in. Every input has label/help/error; disabled control explanation is keyboard/screen-reader accessible. Avoid tooltip-only essential instructions. Advisor capability matrices use accessible labelled controls and textual explanations rather than color-only permission grids. ## URL Truth Scope/category/search/selected setting encoded so links can point directly to configuration item. Unsaved state warns on navigation. Advisor persona detail/version can use stable Settings subroute/query so a Decision/Thread can link directly to the configuration responsible for behavior. ## Increment Realization I0/I1 minimum system/project execution/provider settings can exist via UI/CLI. I2 adds Planning/delivery/connections. I3 adds autonomy + Advisors/Personas + Search-related user preferences if needed. I5/I6 CI/deployment; I7 cluster; I8 notifications/incidents; I9 org/tenant/reliability/persona-sharing governance. ## High-Fidelity Requirements Before first Settings UI implementation: inherited vs overridden, locked explanation, validation/error, connection/account state and responsive category navigation. Before I3 Advisor Settings: persona collection, built-in detail, custom clone/edit, version consequence, capability/locked state, validation failure and small-screen navigation. ## Target State Settings is the human control surface for AWP's typed configuration, effective-value provenance, policy/defaults, advisor personas and external account/connection bindings. It replaces hidden JSON/config archaeology without creating a second configuration authority. ## Primary Users / Jobs - owner/admin: understand and safely configure system/project defaults, policy and available advisor personas; - project/product lead: override allowed Project/Plan settings, choose Project advisor defaults and understand consequences/inheritance; - engineer/operator: diagnose effective configuration, provider/account/connection health and immutable Run/advisor-version provenance. ## Entry / Exit Points Entry: global `SETTINGS`, Project Settings, Plan/Task contextual settings, ConnectionRequirement flow, health/reauth attention, advisor persona/version link, direct setting deep link/search. Exit: originating Project/Plan/Task/AdvisorThread, connection auth/binding flow, Decision/Approval when a material protected change requires it, or provider/account detail. ## User Journeys ### J1 — Understand an effective value ```text open Settings at scope -> search/select setting -> inspect effective value + inherited chain + local override -> read why locked/editable + consequence -> leave without mutation or choose override/reset ``` ### J2 — Override safely ```text editable setting -> change value -> validate type/range/policy -> preview consequence/replan/restart/approval impact -> Save once -> revision-safe mutation -> effective value/provenance refreshes ``` ### J3 — Reset inheritance ```text local override exists -> inspect parent/system values -> Reset to inherited -> confirm consequential effect if required -> local override removed -> effective value resolves from parent -> downstream stale/replan effects shown ``` ### J4 — Connect or reauthenticate provider ```text account/connection needs auth -> start trusted Connection flow -> preserve Settings/Planning return target -> authenticate/select resource/narrow binding -> health verify -> return to exact setting/context -> no raw secret displayed ``` ### J5 — Configure autonomy ```text select autonomy preset -> preview generated category rules -> adjust specific human-in-loop criteria -> security ceilings stay non-broadenable -> save policy revision -> affected future/current work consequences shown ``` ### J6 — Create a custom advisor ```text Settings -> Advisors -> select Project Manager / CI Expert template -> Clone persona -> name/purpose/scope/model/capabilities/instructions -> validation + authority ceiling preview -> Save -> new versioned AdvisorPersona -> optionally set as Project/system default ``` ### J7 — Change an advisor safely ```text open AdvisorPersona -> inspect current version + usage -> edit instruction/model/capability policy -> preview future-thread consequence -> Save new version -> historical threads keep old attribution -> new threads/turns use new version ``` ## Data / Source of Truth ConfigurationDefinition, scoped values/effective resolution, Policy, AdvisorPersona/version, Connection/Binding/Requirement, Account/Model/Provider and immutable Run configuration snapshots are canonical. Environment/provider observed config is compared as desired/applied/observed evidence; raw files are not a parallel editable truth. AdvisorThread content is not configuration truth; it references the persona version used for each turn. ## Actions / Authorization Editing rights are scope/capability/policy dependent. Child scopes can override only allowed definitions and cannot broaden security ceilings. Secret changes use trusted Connection/SecretStore flows. Read-only values remain visible with authoritative explanation. Protected policy/security changes can require Approval. Custom advisor capabilities are validated against Principal/system ceilings; instruction text can never grant hidden read/write/tool permissions. ## Async / Duplicate-Mutation Safety Save/reset/connect/persona-version actions use expected revision + idempotency protection, immediate pending/success/failure feedback and conflict handling. Duplicate Save cannot create conflicting revisions. External auth has a durable return target. High-risk/security/credential mutation requires live authoritative connectivity and is never queued offline. ## Invariants From Day 1 - every effective value can explain where it came from; - desired/applied/observed configuration remain distinguishable; - locked settings are visible and explain why; - raw secret material is never rendered after trusted entry; - Project/Plan/Task scopes can narrow/override only within system ceilings; - Run snapshot is immutable historical evidence; - AdvisorPersona behavior is versioned and historical turns retain attribution; - persona instructions cannot broaden authorization/capability; - UI/CLI/API use the same typed configuration/application commands and definitions. ## Current Implementation State Target page only. Minimal bootstrap may use CLI/manual configuration before all categories have polished UI, but typed canonical configuration exists from I0. Advisor category is target-specified but inactive until I3. ## Deferred Realization Planning/delivery categories deepen I2, autonomy/Advisors I3, CI/deployment I5/I6, Cluster I7, communications/incidents I8, organization/tenant/reliability/persona-sharing I9. Future categories extend the same scope/provenance model. ## Temporary Dogfood Behavior I0/I1 may expose only the settings required to bootstrap execution/providers and may use `aw*` CLI for some canonical mutations. Do not add JSON-only shadow config that later needs migration into the Settings model. Do not hard-code a hidden Project Manager prompt as a permanent frontend setting before I3; the first product advisor must use final versioned `AdvisorPersona` semantics. ## Related Contracts / Decisions - [`../domains/configuration.md`](../domains/configuration.md) - [`../domains/policy-autonomy.md`](../domains/policy-autonomy.md) - [`../domains/advisory-personas.md`](../domains/advisory-personas.md) - [`../domains/integrations-connections.md`](../domains/integrations-connections.md) - [`../architecture/configuration-and-policy.md`](../architecture/configuration-and-policy.md) - [`../architecture/advisory-agents.md`](../architecture/advisory-agents.md) - [`../architecture/control-surfaces.md`](../architecture/control-surfaces.md) - [`planning.md`](planning.md), [`project.md`](project.md), [`advisory-chat.md`](advisory-chat.md), [`approval.md`](approval.md) ## Decisions / ADRs Typed System -> Project -> Plan -> Task -> Run configuration hierarchy, narrowing security capabilities and SecretStore separation are architecture authority. AdvisorPersona versioning extends the same principle for advisory behavior. Introducing a new generic config source, external policy engine or advisor-specific secret/authority store requires a Decision rather than UI-only integration. ## Visual Mockup Authority No Settings high-fi is approved yet. The first implemented Settings slice must have approved inherited/override, locked, validation/conflict, Connection/account and responsive states. Advisor settings get their own I3 high-fi before implementation. Unapproved exploratory settings screens are not canonical. ## Acceptance A user can understand where an effective value came from, safely override/reset it, configure versioned Advisor personas and their bounded capabilities, and configure the product without editing hidden JSON or creating drift between duplicate configuration sources.