Settings guide

Settings is the company control plane. Use it to manage members, invites, providers, channels, local-agent access, and operating defaults.

Setup order

Start with members and invites, then provider and channel connections, then MCP or CLI access. Do not connect tools for an agent seat until the Charter and Steward are clear.

Navigating Settings

Settings is reached from the footer gear in the left sidebar (the nav collapse moved it out of the primary item list). It is a left-rail master–detail layout: a grouped rail (General, Team & Access, Billing, AI & Agents, Connections, Advanced) selects one section at a time, shown in the detail pane. The active section is a URL search param, so /settings?section=<id> is linkable and survives a refresh. The Connections section is the workspace-level provider surface: Google, Slack, QuickBooks, local runners, seat-scoped agent tokens, and stored secrets appear as provider cards with status, used-for chips, actions, and the shared Access language (Off / Read / Draft / Act with approval). Any other integrations row — e.g. a Baserow REST/custom connection created through integration.connect_rest — renders as a generic connection card alongside the stock providers, so a non-stock connector is never invisible on this page. Detailed management forms for tokens, channels, runners, provider links, and stored vault entries remain reachable from those cards.

Section state is fully server-side: every in-app link, redirect, and save uses ?section=<id>, never a #anchor — there is no client-side hash shim to desync from. Documented shortcut pages redirect straight to the right section instead of a dead end: /settings/integrations and /readiness redirect to ?section=connections (connector readiness lives inside the Connections overview, not on a standalone page), /settings/members redirects to ?section=members, /settings/policy redirects to ?section=guardrails, and MCP/CLI access tokens live in the Agent access tokens section (not a separate /mcp page — /mcp is the MCP protocol endpoint itself, not a browsable settings screen). The Advanced group links out to /migration/ninety, the one settings-adjacent page with no home in the grouped rail. Every settings form carries the section it lives in, so saving a change redirects back to that same section with no flash, instead of returning to the top.

What belongs in Settings

• Company profile and workspace defaults. Rename the company from Settings or with tenant.rename (CLI: rost settings rename --company "<name>"); the command is owner-only, human-gated, and records a rename event with old and new names.
• Members, invites, and tenant roles.
• Agent access tokens for local agents.
• Billing plan, hosted Stripe actions, invoices, subscription usage coverage, and latest true-up status.
• Provider and integration configuration.
• Slack channels (the channel bindings that route escalations, Sync Briefs, and reports to a seat or cluster).
• Connected machines (the paired Runners that run scheduled local work orders).
• Stored credentials (vault references only) and tool access approvals.
• Operating defaults, including Sync Brief scope.
• Product-learning participation for bounded product analytics.
• Model gateway policy: whether managed runs may use a non-zero-retention model.

Settings lifecycle timestamps are display metadata for tokens, connected machines, integrations, and stored credentials. They may be emitted by the database as either timestamp values or strings, but Settings renders them as safe labels rather than treating timestamp formatting failures as page-level failures.

When a settings source is temporarily unavailable, the app keeps the route open and marks affected sections as unavailable instead of showing raw errors or stale-looking editable values. Budget and Sync Brief controls stay read-only until their server-backed data can be loaded. Notification timestamps and integration test timestamps follow the same safe-label rule, so a malformed or missing timestamp becomes Unknown or unavailable copy rather than a page crash.

Integration health

integration.list lists connector metadata for CLI and MCP operators, integration.readiness returns the setup checklist, integration.status reads one provider or integration id, and integration.test runs the installed provider-specific health check. These commands return account labels, scopes, capabilities, timestamps, checklist status, and health only; they never return vault references, access tokens, refresh tokens, client secrets, or raw provider responses. Google's test refreshes the vaulted OAuth credential and reads the Gmail profile as the minimal live check. Settings keeps the client-facing Google card narrower: connected account, last successful test, granted capabilities, and connect, reconnect, or test actions.

Google production verification is a roadmap item planned after the first 100 users. Until then, live external Gmail send remains approval-gated and partner demos should use connected-account tests, sandbox previews, drafts, and approval-held examples rather than claiming unrestricted Google production send.

Reconnects keep historical rows for audit, but provider status in Settings, CLI, and MCP prefers the current connected row first, then the latest error or disconnected row.

When a connection's credential authenticates as an account that does not match the one on record, the Settings card's description text warns that the connection authenticated as the wrong account; the connected/needs attention badge above it does not change, because the badge reflects connection status alone and never reads identity state. The remedy the description offers is to reconnect as the account the connection is recorded against: testing a stable mismatch again only records the same mismatch, and accepting the newly reported account is not yet offered from the card. Once the identity is verified again — because a later check resolves the recorded account, or because the newly reported account is accepted — the description drops that warning and, matching the connection's test history, either reports that identity was verified and asks for a fresh test or simply asks you to test the connection to confirm access; it never treats the verification alone as proof the connection works, because establishing who a credential belongs to is not evidence that it does. For the same reason, a passing test older than the most recent identity verification stops counting as current, and the description asks you to test again rather than reporting the stale pass. An identity the provider contradicts, or one it declined to report, keeps the description's warning even when an earlier test passed. The agent-setup card's Google connection readiness badge works differently from the Settings badge: it folds connection, test, and identity state together, so the same identity risk that leaves the Settings badge untouched can turn that badge to Needs attention, and once the risk clears without a current passing test it can read Connected, not tested. Note that integration.readiness does not read identity state yet: its connection-test check reports the stored test result on its own, so a connection with an identity warning on Settings, or a Needs attention agent-setup readiness badge, can still report as tested to CLI and MCP until it is tested again.

Sync Brief scope

The weekly Sync Brief compiles either company-wide or per cluster. Company-wide is one brief covering the whole company and is the default for a new company. Per cluster compiles one brief per cluster, scoped to each cluster's seats; pick it when clusters run their own weekly sync. Per cluster falls back to a single company-wide brief when the company has no clusters, so the rhythm never produces zero briefs. The owner sets this at onboarding and can change it later in Settings.

Product learning

Product-learning participation controls whether ROST may record product/page/recommendation analytics for this tenant. It does not disable security logs, audit logs, error logs, events, tool-call guard records, or other operational records required to run and secure the service.

• enabled allows bounded product analytics for feature quality, defaults, templates, recommendations, safety checks, and reliability.
• disabled blocks generic product/page/recommendation analytics for the tenant.
• enterprise_contract blocks generic product-learning writes until contract-specific handling exists.

Read the policy with settings.product_learning.get (CLI: rost settings product-learning get). Change it with settings.product_learning.update (CLI: rost settings product-learning update --mode disabled). Analytics ingestion code should call the shared product-learning policy helper instead of reading tenants.settings directly.

The product analytics foundation stores only bounded product telemetry: product events, page views by route template, command invocation metadata, onboarding milestones, and recommendation outcomes. Recommendation outcomes use bounded statuses such as shown, accepted, edited, rejected, dismissed, and reversed; current instrumented paths include model-tier recommendations from agent.create_custom and Charter seat-type recommendations from the Charter lifecycle. These rows store safe enums/categories and fingerprints, not raw responsibility answers, Charter prose, prompt text, tool arguments, or customer content. Authenticated users can read analytics rows for their tenant, but writes are server-owned through the trusted DB helpers. The helpers and database constraints reject or redact obvious raw URLs, filesystem paths, secrets, prompt/content fields, command argument/output fields, direct contact/payment identifiers, and long prose-shaped values. These analytics rows are not audit records; operational logs and security evidence stay in their dedicated append-only or product-visible tables.

The authenticated web app records first-party page views and product events through route templates, not raw full URLs or query strings. The ingestion route resolves tenant and user server-side, caps client batches, validates enriched payloads with the shared protocol schemas, and treats product-learning opt-out as a skipped analytics write rather than a product error.

Onboarding milestones are recorded from durable server-side transitions such as company setup, graph review, first Charter draft, first agent setup/dry run/pass/live, first Signal, first goal, Sync rhythm start, and onboarding finish. They are idempotent per tenant and milestone: repeated UI, CLI, MCP, or system calls keep the earliest product-learning timestamp instead of creating duplicate funnel steps. The append-only event log remains the audit timeline; onboarding milestone rows are a bounded analytics projection and are skipped when product learning is disabled.

Command invocation analytics are emitted from the central command executor for UI, CLI, and MCP calls. They store command id, source, actor/scope kind, outcome class, duration, confirmation flag, guard result, request id when UUID-shaped, safe error code, and bounded changed ids. They do not store raw command arguments or outputs. The command outcome classes are ok, denied, pending_confirmation, validation_error, precondition_error, authorization_error, and internal_error. Product analytics write failures are ignored so they cannot mask the command result or replace audit/security records.

Inference budget

Agents that run on ROST-managed inference draw against a tenant inference budget with a hard cap. A new company starts with a hard cap of $0, so a managed-inference run is blocked until the cap is raised. When a run hits the cap it stops with a typed budget error that names the fix; raise the cap before agents can run again.

• Set the hard cap with settings.update (CLI: rost settings update --hard-cap-usd <amount>). The optional soft cap warns before the hard cap and must be less than or equal to it.
• The sandbox dry run is free and is never blocked by the cap, so a fresh company can charter, dry-run, and take an agent live before setting a budget. The cap applies only to real managed-inference runs.
• A company that brings its own provider key (BYOK) is metered on that key and is not subject to the ROST-managed hard cap. BYOK changes the provider account used for eligible cloud calls, not the Charter, tool guard, human gate, or data-retention posture; see the ai-model-data-handling-guide before making provider-handling claims.
• AICOS cloud brain selection is managed with aicos.brain_settings.get and owner-gated aicos.brain_settings.update. Managed cloud answers draw from the included allowance; BYOK cloud answers meter against the tenant key. Runner Claude and MCP client answers are labeled separately and do not draw from the managed cloud allowance. The AICOS Codex runner choice remains gated off until the governed interactive runner path is verified.

Company autonomy ceiling (Company Guardrails)

The company autonomy ceiling is a single tenant-wide dial that caps how much ANY agent may do without a human in the loop. It is the fourth governance gate, after the signed manifest, the budget, and before escalation — it never replaces them. It only ever constrains AUTONOMOUS (always_allow) actions; a tool already routed to a human (always_ask), an explicit escalation, a connector that already escalated, or secret-shaped input is never blocked by the ceiling.

• Read it with settings.agent_policy.get (CLI: rost settings agent-policy get).
• Set it with settings.agent_policy.update (CLI: rost settings agent-policy set --profile locked_down). Owner-only and human-gated.
• In the signed-in app, tenant owners manage the same policy from Settings → Company guardrails. Non-owners can see the current posture but cannot change it.
• Profiles are named ceilings: locked_down (agents autonomously read/draft only; every write/send escalates), balanced (the default; read/draft autonomous, writes escalate), high_autonomy (approval-marked write tools may run autonomously; only full-access escalates), and custom + max_autonomous_risk (low, medium, high, critical).
• An explicitly set ceiling is ENFORCED by default. Enforcement has two modes: enforce blocks an over-ceiling autonomous call and routes it to the steward (it is never a dead-end deny — a human can still approve), and observe allows the call but logs it. The platform default for a company that never set a policy is balanced + observe, so existing live agents are never retro-bricked.
• When enforcement is on, signing a manifest or taking an agent live is REFUSED if the manifest grants always_allow to a tool whose risk exceeds the ceiling; the error names the exact ceiling, tool, and risk in its details. Lower that tool to always_ask, or raise the ceiling, then retry.

CLI confirmation mode

The CLI confirmation mode is a separate tenant-wide dial. It does not change what an agent may do (that is the company autonomy ceiling above); it changes whether the rost CLI tool itself may stand in for a human at an already-gated confirmation.

• careful is the strict default for every company, including internal ones. The server refuses the CLI's silent auto-replay of a pending confirmation — a human must review it before it is approved.
• trusted_operator is a deliberate tenant_admin opt-in (an ADR-0018 §6 standing authorization) that lets the CLI silently auto-approve only confirmations whose command is explicitly classified Trusted-eligible. Always-human, not-applicable, missing, unknown, and dangerous-risk confirmations still require interactive human review in either mode.
• Read it with settings.confirmation_policy.get (CLI: rost settings confirmation-mode get). Set it with settings.confirmation_policy.update (CLI: rost settings confirmation-mode set --mode trusted_operator). Owner-only and human-gated.
• Stored at tenants.settings.confirmation_policy; enforced server-side in confirmation.approve, so a stale or modified local CLI cannot bypass it.

Model gateway policy

The model gateway policy is a separate tenant-wide dial (ADR-0019) that controls whether the AI Gateway may route a managed run to a provider model that lacks a zero-retention (ZDR) tier.

• allow_non_zdr_models: false is the conservative default for every company. The gateway restricts managed runs to zero-retention-eligible models.
• Unlocking is a deliberate tenant_admin opt-in (an ADR-0018 §6 standing authorization): it lets managed brains without a zero-retention tier run, disclosed up front — the provider retains data up to 30 days for abuse monitoring.
• Set it with tenant.model_gateway_policy.update (call with {"allow_non_zdr_models":true} or {"allow_non_zdr_models":false}). Owner-only and human-gated.
• Stored at tenants.settings.model_gateway_policy; enforced server-side in the AI Gateway inference-policy resolver, so a stale or modified local client cannot bypass it. The model-picker UI that surfaces this choice inline ships separately.

Agent guidance

Agents may explain which setting is needed and why. They should not ask users to paste secrets into chat or tool arguments. When credentials are required, route the user to the vault-backed setup flow.