AICOS chat guide

AICOS is the AI Chief of Staff for an authenticated ROST tenant. It is a governed agent seat in the Responsibility Graph, not an anonymous public chatbot and not a hidden superuser.

Where AICOS appears

In the authenticated app shell, AICOS opens from the floating assistant control. The panel is available across normal app pages and keeps the same thread while you move through the product. Full-bleed public, login, onboarding, docs, invite, and demo routes do not receive the authenticated shell.

Each thread has a purpose:

• Onboarding — setup help and page-aware setup context.
• Seat — a seat-scoped assistant pinned to one seat (see "Seat-scoped AICOS" below).
• General — company operating help.

You can reopen prior threads, search thread titles and summaries, or start a new one. Session history is stored in tenant-scoped conversation tables so chat history is not reconstructed from analytics, events, or run logs.

Set up AICOS for an existing company

New companies receive the governed AICOS foundation during provisioning. Existing companies can also set it up later from Settings -> AICOS. Owners and admins can see whether the foundation exists and repair it if needed; choosing the run location (the lane) after setup is owner-only.

The repair action ensures the same structure new companies receive: a Founder/CEO root seat, an owner occupancy for stewardship, an AI Chief of Staff seat, the live stock AICOS agent, and one active agent occupancy. It is idempotent; running it again repairs missing pieces instead of creating a second AICOS. If older setup attempts left more than one active AICOS occupancy, the repair path keeps the best current stock AICOS agent — live before dry-run, draft, or paused — promotes that canonical stock agent to live for Runner readiness, and ends the extra AICOS occupancies so Settings, lane readiness, and chat resolve the same governed agent.

Settings is the infrastructure surface for AICOS. Use it to confirm foundation status, inspect the current lane, see whether a seat-scoped MCP token exists, and choose Cloud, Runner, or MCP when the server-side readiness checks allow it. The AICOS seat has its own operations panel instead of the normal Staff this seat setup tabs, because AICOS is the company's governed AI Chief of Staff foundation rather than a generic agent to restaff from stock, custom design, or runner pairing controls. Use that panel to reach AICOS Settings, its Charter, runner readiness, MCP token management, and Trust Card run evidence. Direct lane changes reject non-owners with a lightweight server-side membership check before opening the command transaction, then repeat the owner check inside that transaction so a membership change between reads cannot reach capability or seat details or a lane write; the browser never decides authority.

The same Settings area shows AICOS authority and launch recovery in customer language. AICOS starts with connected company capabilities at maximum available access and Trusted posture, but tenant dial-backs and always-human boundaries remain authoritative. Launch-credit status shows 50%, 80%, and exhaustion posture plus Billing and BYOK recovery links; BYOK reduces managed inference cost only and does not replace the required subscription after launch access ends.

What context AICOS receives

Each turn carries server-normalized page context: route template, current path, safe search state, selected seat or object ids when authorized, onboarding state when relevant, and the current tenant clock. AICOS treats the supplied clock as authoritative for today's date and time instead of guessing from model priors. The server derives tenant and user authority from the authenticated session. Client-supplied tenant context is never accepted as authority.

The current chat harness shows the effective lane and model. Cloud is the default and remains the enforced lane during onboarding, even if a post-onboarding lane has been selected. After onboarding, an owner can select cloud, runner, or MCP only when the server says that lane is ready. On a live, recognized stock AICOS Charter, a lane change does more than update the agent seat: in the same transaction it mints a new Charter successor version carrying manifest evidence for the new lane, supersedes the version it replaces, and repins the agent to that successor — evidence is never re-minted onto the existing version. Before that receipt is written, the server re-runs every signing gate for the target lane; a matching manifest digest only establishes that the document is eligible to reuse, never that the target lane is authorized, so a target whose gates fail is refused and nothing is written. Those gates cover connector wiring for the target lane, the company autonomy ceiling, connection identity, and required Skill tool access — a lane change never clears a block the ordinary sign-off would refuse. Each refusal names the remediation that actually clears it: a Charter that is a recognized stock revision but has never been signed off names charter.sign_manifest and the exact version id to sign; an in-flight draft asks you to approve or discard it first. A manifest that has been edited, or is otherwise unrecognized, cannot re-mint automatically at all — automatic re-minting only recognizes unmodified stock revisions — so it is refused as such, and the way forward is to restore the Charter to a stock revision with charter.set and sign it with charter.sign_manifest. Any failure rolls the whole change back — no successor, receipt, decision, or audit event is left behind, and the lane itself stays where it was. The browser never decides tenant authority or runner/MCP readiness.

AICOS also has an explicit brain selection. Cloud can use the included managed allowance or a tenant Anthropic key (BYOK). When cloud is on the managed allowance, an owner can also pick a specific managed model from the AI Gateway's priced, ZDR-rated catalog (today: Anthropic's own "Automatic" default, plus managed OpenAI and xAI entries) instead of leaving the choice on Anthropic's default routing. A managed model without a zero-data-retention tier shows as locked with the reason until a tenant owner explicitly unlocks non-ZDR managed models (tenant.model_gateway_policy.update, owner-only and dangerous-gated); once unlocked, its per-model data-retention disclosure is shown before it becomes selectable. Selecting one of these managed models updates AICOS settings immediately, but it does not yet change which model actually answers a cloud AICOS turn — every non-Anthropic option says so plainly, and cloud turns keep running on the existing Anthropic routing until a later runtime cutover wires the persisted selection through. Runner brain preference still records Claude or Codex, but interactive AICOS runner turns are currently gated to Claude while the Codex path remains unverified. MCP is labeled as the MCP client. Read this selection with aicos.brain_settings.get; owners can update it with aicos.brain_settings.update (CLI flags: --lane, --cloud-brain managed|byok, --runner-brain claude-cli|codex-cli). BYOK requires an active tenant Anthropic key and does not support a specific managed-model selection. Choosing codex-cli for AICOS runner mode is currently rejected with a precondition error until the governed interactive runner path is verified. Runner and MCP answers are labeled in the transcript and do not consume the managed cloud allowance. If the selected runner reports that its active local model account has exhausted its allowance, Settings surfaces Allowance exhausted before the user sends another AICOS turn so they can switch lanes, switch runner accounts, or keep working manually instead of waiting on a doomed runner round-trip.

Runner mode uses the same AICOS sessions and transcript. Interactive chat turns are tracked separately from work orders: each user message has one user-owned turn execution with a short deadline, so two users' chat messages cannot collapse into the same work-order slot. Scheduled coordinator work, explicit/manual operator runs, and Forge runner work still use work orders. Runner claim packets carry ids and execution metadata, not the user's free-text request. After claim, the local runner calls the governed AICOS context-load tool, which re-checks seat scope and returns the bounded transcript, session summary, route context, tenant clock, grounding text, and source counts authorized for that turn. For execute-ready runners, the claim also carries a server-built Seat work contract that names the governed runtime profile, the AICOS context-loader tool, and the Seat's permission manifest; action attempts still route through command guards, tool-call audit, and pending confirmations. The runner treats loaded tenant clock, context, and contract as authoritative instead of substituting its own runtime clock, local files, or self-invented authority. A runner must be paired, execute-ready, and backed by the live AICOS agent before it can be selected; Claude-backed readiness additionally requires the dedicated cell's truthful auth_state: "ready" plus auth_state_contract_version: 1 marker. Missing or unknown Claude auth stays visible but is not advertised as ready, and an explicitly Codex-only runner is the only generic-work exception.

Agent seat pages can also expose a direct persistent chat with that seat's active agent. This is different from Seat-scoped AICOS: the target is the agent occupying the seat, the transcript is keyed by tenant, user, purpose, and target agent, and the same user can keep separate active threads for different agents. Owners and admins can read direct-agent transcripts for the tenant, and a human occupying the agent seat's Steward seat can read the transcript; unrelated members cannot. New prompts for a target agent enter an agent-scoped queue with a short turn deadline. A second prompt in the same thread coalesces into the pending turn until that turn is claimed, while prompts for another user or another agent keep their own queue position. Direct agent chat never dispatches through work_orders; scheduled coordinator work, explicit/manual operator runs, and Forge runner work still use work_orders.

Cloud and runner submissions carry a stable request ID. Distinct requests that compete while a turn is active receive HTTP 409 with code AICOS_TURN_CONFLICT; the losing request writes no partial user message and consumes none of its attachments. Runner acquisition commits its user message, execution, attachment links, queued transcript projection, and session snapshot together, so a failed projection leaves none of them half-written. Retrying the same request ID returns the original turn and does not rerun the model, builder, onboarding, or runner-queue side effects, even if the currently selected lane or runner readiness changed after the original submission.

When a runner claims an interactive AICOS turn, the runner reports start and final result back to ROST. The turn row records claim/start/finish timing, terminal reason, model label, and token counts when the runner or cloud path provides them. The server appends exactly one assistant transcript message for the result, links that message to run evidence, and treats duplicate or late result reports as idempotent. If the runner answer includes a validated in-app link, the web panel can surface the same consent-required navigation suggestion once polling sees that the pending turn is terminal. If a queued, claimed, or running interactive turn passes its short deadline before a runner writes back, the turn is marked offline and the transcript receives a terminal assistant message instead of leaving a permanent "queued" placeholder.

While a runner turn is queued, claimed, or running, the chat panel keeps showing the pending state and polls the session until the answer or terminal status arrives. The composer, model picker, and lane picker are disabled during that active turn so a second browser tab or direct API call cannot overlap another runner turn in the same thread. Terminal runner statuses such as failed, offline, or canceled stay visible only while they are still the latest user turn; if the user continues the conversation in another lane, the stale terminal marker is no longer projected at the bottom of the thread.

MCP mode uses the existing tenant-authorized MCP surfaces. It requires an active seat-scoped MCP token for the AICOS seat and does not grant hidden tenant-admin access or run browser-side MCP tool calls. Users operate MCP AICOS from their authorized agent interface; the web chat remains the same readable thread surface.

Model behavior is now explicit in the AICOS session contract. A thread can run in Auto or use a pinned compatible model from the guided catalog. Auto chooses a fast tier for short low-risk turns, the balanced default for normal operating help, and a higher-reasoning tier for onboarding synthesis or large context. The panel shows the effective model, disables lower-context choices once the active thread outgrows them, and tells the user to start a new session for those models. Session context is estimated and maintained as a bounded rolling summary for memory search; when the thread crosses the configured threshold, that summary becomes the compacted context for future model calls rather than resending the whole thread. Raw messages remain in history. Summaries preserve durable decision cues, open questions, linked artifacts or objects, and unresolved setup facts where the transcript contains them.

Assistant answers render safe Markdown for headings, short lists, emphasis, code, tables, and in-app links. User messages remain plain escaped text. Links only become clickable when they target same-origin app routes such as /inbox or /settings; external, protocol, script, API-style, or traversal targets are stripped to plain text before transcript storage. When an answer includes a validated app route, the chat can surface one consent-required navigation suggestion and, if the user has enabled the local preference, open that route automatically. Navigation is never authorization; destination pages still enforce their own tenant, role, and seat checks.

You can attach images to a message from the composer. ROST accepts PNG, JPEG, WebP, and GIF up to 10 MB each, and up to four per message. Images are held in a tenant-scoped private store, stripped of embedded metadata such as EXIF on upload, and shown as thumbnails in your message; the panel loads each thumbnail through a short-lived signed link rather than a public URL. In the cloud lane the agent can view the image directly. Runner and MCP viewing of attached images is a scoped follow-up; today the agent still reads the accompanying text on those lanes.

AICOS can also retrieve bounded summaries from prior sessions owned by the same tenant user and surface them as session-memory read models. Setup-limited users do not retrieve sensitive historical run or company-memory summaries through this path. This is a practical memory seam for AICOS continuity; it is not yet the future Company Brain, and it does not make unaccepted knowledge authoritative.

Platform allowance and BYOK state are checked before routing; an exhausted included allowance keeps AICOS in guided mode and points the user toward BYOK, billing, or manual continuation. The chat transcript and Settings surface the exhaustion reason and provide direct paths to add a tenant Anthropic key or review the plan. Cloud AICOS provider attempts write canonical run evidence and one linked llm_calls row with source metadata aicos_chat, prompt version, latency, token usage, cost, key source, and typed outcome. Managed-key turns consult the tenant hard cap before provider execution; BYOK turns never fall back to the managed platform key. Provider timeouts, provider server errors, empty output, and BYOK credential or allowance failures stay visible as terminal failed turns with retry or Settings recovery instead of being converted into a successful generic answer.

During onboarding, the deterministic harness may execute only explicit low-risk draft actions. In the Responsibility Graph step, a user with setup/action authority can ask AICOS to create one named draft seat per turn; the seat stays vacant, is traceable to the AICOS message through artifact sources, and still needs human review before staffing, Charters, manifests, or go-live. Compass and Charter help remains draft guidance and clarifying questions until the live drafting planner lands. AICOS never silently finishes onboarding, approves Compass or Charter content, signs manifests, goes live, stores credentials, changes autonomy policy, or invites external people; those actions remain human-confirmed.

AICOS posture is resolved on the server from the current user's AICOS access scope plus the tenant's Company guardrails. Report-only can read, explain, and draft guidance, but it cannot mutate setup or operating state. Balanced can perform narrow low-risk internal draft/setup actions and stops at human gates. High autonomy can perform allowed internal low-risk actions without changing the hard prohibitions: AICOS still cannot approve its own Charter or manifest, handle credentials, send externally, spend money, perform destructive/admin changes, go live, expand policy/access, or receive hidden sensitive data.

Draft an agent plan from chat

When a user describes an agent in chat, AICOS can draft a starter plan for that seat: the seat it should occupy, the Charter shape, tool and model choices, access boundaries, and the approval path. The draft is written into the transcript as guidance and does not become a durable lifecycle change on its own.

If the draft is missing or ambiguous, the plan card can ask structured clarification questions in the same thread. The current prompts cover the seat name, Charter purpose, steward/parent seat, tool hints, model tier, lane, and launch mode. Answers are submitted as a normal AICOS turn, stored with the transcript, and cited back to the revised draft as artifact evidence. A skipped or "not sure yet" answer keeps the conservative default. A revised draft is regenerated server-side from the previous governed compilation plus those answers; it does not let the browser supply tenant authority, execute lifecycle commands directly, or bypass the draft-and-confirm path.

Durable agent lifecycle changes still use the existing command surface:

• agent.create_custom creates the draft agent shell and Charter seed.
• agent.configure_tools stages tool access and credential requests.
• charter.sign_manifest signs the manifest before rehearsal.
• agent.run_dry_run rehearses the draft.
• agent.go_live only happens after the required approval gate.
• confirmation.approve is the human approval command for pending confirmations.

When a user asks AICOS to change an agent's configuration — set or clear an agent's schedule, or assign a skill — AICOS acts on the request instead of only explaining it. It stages the change as a draft-and-confirm proposal through the governed command and links the pending confirmation on the Approvals queue for a human to approve. Each of these proposals (agent.update_schedule, skill.assign_to_seat) is human-required and always-human, so nothing durable changes until a person confirms it and AICOS never applies a capability change on its own. A live agent's tool (capability) grants are not an AICOS-executable proposal: changing them goes through the seat's Tools & connections tab, which stages a Charter-manifest amendment (charter.set) for a human to approve — so when a user asks AICOS to grant or change a tool, AICOS names that gap and points to the seat's Tools tab instead of returning a generic how-to answer. When AICOS does not hold the command for a request more broadly, it names the exact gap and points to the seat page where a human can make the change.

If the user asks for report-only or no-action help, AICOS stays in plan-only mode and does not create or advance a lifecycle change. Seat-scoped staging only uses the server-authorized pinned seat from the session; client-supplied tenant or seat context is ignored as authority. Runner and MCP lanes do not bypass the same server command guards, and they do not grant hidden browser tool execution. Raw secrets, vault material, and secret-shaped metadata stay out of transcript storage.

Seat-scoped AICOS

From a seat page you can open AICOS scoped to that seat ("Ask AICOS about this seat"). A seat session is pinned to one seat and reads only that seat plus the seats it directly stewards — what needs attention there, what is blocked, and which tasks, Friction, Signals, goals, or approvals need action. The chat header shows Seat: <name> so it is always clear whether you are talking to Company AICOS or a Seat AICOS.

Seat mode is the intersection of your access scope and one seat, never an escalation: it can only ever show a narrower slice than your company or own-scope session, and it can never reach data your base scope would already deny. The seat is resolved from the session (pinned when it was opened), re-authorized on the server every turn against your current occupancies and stewardship — a manually supplied seat id in a turn is ignored, a seat from another tenant or one you are not authorized over is indistinguishable from not-found, and if your occupancy or stewardship ends the stored seat transcript locks instead of widening into a company/base-scope thread. Setup-limited access does not get seat operating data. Drafted seat actions stay scoped to the session's seat and remain human-gated where required.

AICOS grounds answers from three source classes before producing user-visible setup or operating guidance:

• Reference documents — public ROST guides such as this chat guide, onboarding guidance, the Responsibility Graph playbook, tool-access guidance, and confirmation guidance. AICOS retrieves the narrowest relevant guide before setup, Charter, Signal, Friction, Cascade, Sync, tool-access, or onboarding advice.
• Tenant read models — bounded summaries of tenant operating state, including onboarding status, graph/setup readiness, Compass/Charter readiness, operating health, agent/system health, approvals/inbox, and selected Seat context. These read models expose counts and short observations rather than raw database dumps.
• Session memory — bounded summaries from prior AICOS sessions for the same authorized user, filtered by scope and sensitivity.

Assistant messages can carry source counts and persisted source metadata so a thread can later show which reference docs or read models informed the answer.

Proactive pulse panels

The panel opens on the Chat thread, and one tab to its right the Pulse view is where AICOS surfaces what needs attention without being asked — deterministic, structured panels built directly from tenant read models — never generated prose — so nothing is invented: setup gaps, top recommended actions, pending confirmations, agent and run health, Friction and task bottlenecks, Signal and goal exceptions, and recent meaningful changes. Every item cites and links its source object (a Friction item, a pending confirmation, a Seat, a Signal, a goal) so the user can go straight to the record instead of trusting a summary. Starting or continuing a thread switches to the Chat view.

Pulse panels follow the same scope boundary as everything else AICOS reads. A setup-limited implementer sees setup gaps and its own seat-authorized pending confirmations only — never agent/run health, tenant-wide Friction or task bottlenecks, Signal or goal exceptions, or the recent-change feed. An own-scope user sees a slice limited to the Seats it occupies or directly stewards. Company-scope users see the tenant-wide picture. Pending confirmations reuse the exact same per-user Seat authority the Approvals queue already enforces, so this panel can never show more than that user could already see there.

Clicking "Ask AICOS" on a panel item prefills the chat composer with a suggested message and switches to the Chat tab; it does not send anything on its own and does not call a command directly. The resulting turn still goes through the same draft/confirm/guard pipeline as any other AICOS message, so a high-risk fix still needs a human confirmation before anything durable happens.

Governance boundary

AICOS can preserve context and explain what it is ready to do, but durable operating changes still use the same ROST controls:

• Tenant isolation is enforced by RLS and server-side tenant context.
• Raw secrets, vault refs, hidden tool arguments, storage refs, provider payloads, agent custom prompts, and secret-shaped text are not stored in chat history or read-model context.
• Durable decisions remain human decisions.
• Action execution must route through command guards and confirmation when required.
• Expanding authority, approving Charters or Compass versions, going live, credentials, external sends, money, destructive operations, and policy changes stay human-gated.
• AICOS never approves its own pending confirmation.

Treat AICOS as a coordinator over the operating system. It can become more useful as model grounding, read tools, draft actions, and runner execution are enabled, but it does not bypass the Responsibility Graph, Seat Steward accountability, command guards, or confirmations.