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.

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.
• 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.

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, DER-coded next actions, 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 exposes the same Google readiness facts and test action beside Connect/Reconnect, showing whether OAuth env, callback registration, tenant connection, scopes, tests, Google verification/CASA, and Gmail/Sheets handler slices are ready or still waiting on DER-880, DER-881, DER-866, DER-867, or DER-869.

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.

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.

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.