How to use Zahara

Roles

Operator

The person responsible for monitoring agents day to day and choosing the next safe action.

Reviewer

The person who approves, rejects, or requests changes when a run, tool, eval regression, or policy needs human judgment.

Builder

The person who creates, imports, configures, or edits an agent before it is trusted for real work.

Admin

The workspace owner or manager who controls credentials, team access, tokens, and high-impact settings.

Platform terms

Agent

A configured AI worker with instructions, model policy, tools, run history, and governance settings.

Fleet

The roster of agents in a workspace. Use it to find, review, pause, configure, or inspect one agent.

Run

One execution attempt by an agent. A run should have status, cost, latency, events, and audit proof.

Runner

The background worker that executes Workboard cards or agent tasks. If no runner is online, queued work waits.

Runner lease

A claim on one Workboard card by one runner so two workers do not perform the same task at once.

AI Agent Control Plane

The Zahara system that governs every agent in a workspace, regardless of how the agent was built or where it runs. The control plane enforces review gates, routes model access through Gateway, traces every run, and keeps a tamper-evident audit record.

Control plane

The Zahara system that governs agent activity across build, import, activation, runtime, and audit. When an agent enters Zahara, however it was created, the control plane owns what it is allowed to do, what gets reviewed, and what gets proved.

Studio

The agent builder inside the control plane. Vibe lets Thomas interview you and turn plain-language answers into a governed agent spec. Flow lets you wire the agent visually as a graph of nodes and edges. Pro gives you direct access to the full agent YAML spec. Import brings an external agent config into the builder for review before activation.

Thomas

Zahara's AI. Thomas runs the Vibe interview in Studio, answers questions in the platform guide, and helps operators understand what the current page shows and what to do next.

Approval

A human decision point that pauses risky, blocked, or policy-sensitive work before it continues.

Trace

The step-by-step path of a run across model calls, tools, approvals, errors, and output.

Inspect

The detailed run view for status, latency, cost, tokens, events, output, and error context.

Audit

The timestamped evidence log for imports, runs, reviews, evals, credentials, and other important state changes.

Gateway

The routing layer for model providers, keys, budgets, and fallback behavior.

Workboard

The board where proof work and business work become cards with owners, status, review, and evidence.

Adapter

The importer that reads a source format and maps it into Zahara fields for review.

Slug

A short URL-safe identifier, like support-triage, used to reference agents or config items.

Source record

The evidence of how an agent entered the control plane: the original file, config, or connection, plus the adapter used, hash, field mappings, and any warnings raised during review. Built agents have a spec history instead of a source record.

Basic workflow

1. 1Read the control plane headline, check the live workspace signal, and note how many agents are governed, approvals are waiting, and runs succeeded.
2. 2Use the guided tour or a starter chip to ask the first question.
3. 3Use the platform path cards to choose Import, Studio, Approvals, Observe, or Integrations.
4. 4Review platform updates if you want to see what recently changed.
5. 5Use the control plane path to understand the full journey from learning to observing live work.
6. 6Open Command Center once you are ready for the daily operating room.

Proof that it worked

• The hero shows Zahara as the AI Agent Control Plane for Agent Ops.
• Thomas Intel is embedded and open by default.
• Thomas Intel answers Home questions through `/api/thomas/main-chat`.
• Import and Build are separate cards that link to `/import` and `/studio`.
• Platform updates show user-facing shipped capabilities without source details, PR numbers, branch names, or internal implementation labels.
• The control plane path stays readable as one left-to-right journey.

Before you start

• Confirm you are on /home and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the first path is unclear, choose the guided tour before Import or Studio.
• If a card sends you somewhere unexpected, use Command Center as the operating room and return here only for orientation.
• If Thomas gives a vague answer, ask it to choose between Import, Studio, Observe, Approvals, and Command Center using visible page context.

Useful Thomas questions

• I am new. Should I start with Import, Studio, Observe, or Command Center?
• Explain Zahara in one minute using this Home page.
• What should I click first if I already have agents running?

Basic workflow

1. 1Open Command Center at the start of a session.
2. 2Use the page-title pop-out to open the walls this operator station needs on second, third, or fourth screens.
3. 3Use the Page View menu when you need a saved team or personal Command Center layout.
4. 4Use Customize this page to add, remove, move, or tune data blocks, then Save for me when the layout should persist after refresh.
5. 5Use Customize layout in the live monitor only if this station needs a different second-screen card order.
6. 6Read Daily operator report first so the shift starts from the right human action.
7. 7Check Live action readiness before running a live Workboard card.
8. 8Read the top strip for critical agents, waiting approvals, tool health, cost, and active agents.
9. 9Handle the highest-risk row in What needs you.
10. 10Use Approval queue age to clear the oldest pending reviews before they miss the review target.
11. 11Expand any DOWN or WARN tool card to see affected agents and blocked cost.
12. 12Use Critical issues timeline and Fleet dependency graph when risk might cascade.
13. 13Check Guardrails and Activity trend to see whether the workspace is improving.
14. 14Open Safe to leave alone only when you need the healthy-system proof.
15. 15Use Proof of what ran before calling the issue resolved.

Proof that it worked

• No 404 or app error.
• The top strip, What needs you, Guardrails, Activity trend, Tool health, Quality, and Recent runs are visible.
• The app header exposes a small pop-out icon beside the current page title.
• The page pop-out opens the current surface in a chrome-free window instead of a fixed monitor picker.
• The Command Center monitor opens the same operating story in a read-only second-screen view.
• Page Views can switch between team default and personal layouts.
• Customize this page can add, remove, move, and tune data blocks before saving.
• Save for me persists the selected personal Page View after hard refresh.
• Demo workspaces clearly show synthetic/read-only context and should not expose confusing write flows.
• The live monitor Customize layout reorders cards locally and Reset layout restores the default order.
• Daily operator report shows triage, live path, spend, and proof checklist items.
• Live action readiness names provider key, runner, Workboard, and operator access status.
• Critical and warning rows link to the page where the user can act.
• Approval queue age shows pending buckets and an overdue-review callout when old reviews are waiting.
• Tool cards show affected agents and suggested action for DOWN or WARN tools.
• Metric sparklines show trend direction across the operating strip.
• Critical issues timeline renders incident windows or a clear empty state.
• Agent status treemap opens Fleet filtered by status.
• Fleet dependency graph supports node detail, What-if cascade mode, search, and PNG export.
• Safe to leave alone expands and collapses without hiding active-risk sections.
• Recent runs show status, cost, latency, and a clear note.

Before you start

• Confirm you are on /command-center and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If live data cannot load, do not treat the page as empty. Retry refresh, then check Fleet or Evals to see whether the API or one panel is down.
• If a metric spikes, open the linked detail page before changing an agent.
• If approval age is high, clear the oldest pending review before starting more live work.

Useful Thomas questions

• What needs attention right now on Command Center?
• Which item is safe to leave alone?
• What linked page should I open first and why?

Basic workflow

1. 1Open Onboarding after first sign-in or signup.
2. 2Show the welcome modal over the blurred platform preview.
3. 3Ask one question: how does the user want to start?
4. 4Lead with the recommended control plane tour.
5. 5If they pick the tour, schedule Zahara to open on Command Center and introduce the sandbox agent.
6. 6If they pick Build or Import, record the choice and send them to Command Center without auto-launching the guide.
7. 7If they skip, send them to Home where Zahara can guide their first path.

Proof that it worked

• The page shows a centered control plane welcome modal over the blurred app.
• The three choices are Let Agent Zahara show the control plane, I have agents running - bring them in, and Build a new agent inside the control plane.
• The control plane tour is marked Recommended and schedules the Zahara guided tour.
• The preview names the Demo Support Triage Agent and explains that nothing sends, spends, or touches real data.
• Build and Import choices still land on Command Center so the user first sees the operating room.
• The page guide opens from the app header and links to `/docs#onboarding`.

Before you start

• Confirm you are on /onboarding and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If you are new, choose the recommended tour; it opens Command Center first so you can see the operating room before building anything.
• If Build or Import lands on Command Center, that is intentional: Zahara shows the control plane before you connect or create real agents.
• If you skipped onboarding too early, use Home or this manual to restart from the Day 1 quick start.

Useful Thomas questions

• Which onboarding path should I choose if this is my first time?
• Why does Build or Import land on Command Center first?
• Show me the safest demo path before I connect anything real.

Basic workflow

1. 1Pick one external agent or workflow to observe.
2. 2Confirm the workspace and admin/operator role are correct.
3. 3Create a Trace Connect token and store the one-time secret in the external runtime.
4. 4Click Send test heartbeat and verify Zahara accepts a terminal `run.completed` event before adding the token to production code.
5. 5Choose the matching starter recipe for OpenAI Agents, LangGraph, CrewAI, AutoGen, n8n, or Dify.
6. 6Send a `run.started` or `message` event with a stable `trace_id`.
7. 7Send tool, model, handoff, guardrail, or error events with `span_id` when available.
8. 8Send `run.completed` or `run.error` when the external run finishes.
9. 9Open Observe / Health or Observe / Trace and confirm the run evidence is visible.
10. 10Open Audit and filter for `trace_connect.event_received` if the operator needs tamper-evident proof.
11. 11Revoke any token that was created only for testing.

Proof that it worked

• Trace Connect token tooling can list, create, and revoke scoped tokens.
• Token create responses include a one-time secret plus curl and Python snippets.
• Send test heartbeat accepts one safe event, increments the active bridge count, and links to the Trace run.
• The starter recipe picker includes OpenAI Agents, LangGraph, CrewAI, AutoGen, n8n, and Dify.
• Selecting a recipe updates the setup guidance, emitted event types, and copyable snippet.
• `POST /trace-connect/events` returns `ok: true`, `run_id`, and the normalized event item.
• A Zahara `Run` row is created with source `trace_connect` and request id equal to `trace_id`.
• Tool and model events create run-step evidence for Observe and Inspect.
• Audit records `trace_connect.event_received` for every accepted event.
• Audit records token create/revoke events for credential changes.
• Events are scoped to the active workspace and are not visible to other accounts.
• Secret-looking metadata fields are redacted before they are stored.

Before you start

• Confirm you are on /trace-connect/events and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If events do not appear, send a test heartbeat before wiring production traffic.
• If the token fails, create a fresh token and copy the one-time secret into the external runtime.
• If the event is unmapped, include agent_id or agent_slug only after the target agent exists in Fleet.

Useful Thomas questions

• How do I prove Trace Connect is working with a test heartbeat?
• Which starter recipe matches my external agent runtime?
• Why did this external event not map to an agent?

Basic workflow

1. 1Choose Upload, Connect, or Template from Quick Start. Choose the tab that matches the source you have right now.
2. 2Load the file, paste the config, describe the agent, scan GitHub, or use API/CI/CD.
3. 3Confirm the detected adapter or open Supported formats if you need an override.
4. 4For cloud and enterprise sources, note credentials that must be set during review.
5. 5Review mapped fields, not-mapped fields, warnings, model route, tools, and secrets.
6. 6Send to Fleet for review.
7. 7Open the new Fleet review row.

Proof that it worked

• One tabbed action area is visible immediately on page load.
• Quick Start scrolls to the matching Upload, Connect, or Template section.
• Upload, paste, and GitHub inputs stay separated.
• Upload explains supported files, source preservation, Fleet review, and version history.
• Supported formats shows 39 formats across the five current tabs.
• Bedrock, Azure, and Vertex show credentials-set-during-review warnings.
• Detected adapter is visible after a source is loaded.
• Readiness panel is present.
• Warnings are preserved.
• Onboarding ID is created after sending to Fleet.

Before you start

• Confirm you are on /import and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the source does not map cleanly, do not activate it. Read warnings and unsupported fields first.
• If an adapter is unknown, use Supported formats or paste a smaller source before sending to Fleet.
• If secrets appear in the source, remove or rotate them before review.

Useful Thomas questions

• What did Zahara detect in this import?
• Which warnings must I review before sending this to Fleet?
• Is this source safe to activate or only safe to review?

Basic workflow

1. 1Open Integration Hub when a user asks what Zahara connects to.
2. 2Search or filter to the system they already use.
3. 3Read the status guide so Connected, Guide available, and Coming soon are clear.
4. 4Open the matching card and read the detail drawer.
5. 5Connect, request preview, or ask to be notified.
6. 6Review access before any agent can use the connection.

Proof that it worked

• Search returns the expected card.
• Connected, Guide available, and Coming soon labels are visible.
• The catalog count shows 417 listings.
• Each card opens the drawer.
• Confirming a drawer action shows a toast.
• The copy says agents cannot use a connection until review.

Before you start

• Confirm you are on /integrations and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Integration Hub does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Integration Hub state?

Basic workflow

1. 1Scan the status pills to see whether the roster is calm or needs attention.
2. 2Stay in Rows view for normal roster triage.
3. 3Use search or a status filter to narrow the roster.
4. 4Use Agent GPS from the card or row when the next question is what one agent is doing or what it just did.
5. 5Use Configure directly when you already know the agent's settings need work.
6. 6Use the chevron to expand the row when you want roster-level context first.
7. 7Check status, spend cap, team assignment, recent activity, and quick links.
8. 8For a demo or new workspace, add the sample fleet or load a manager operating pack before judging whether the product is empty.
9. 9For a manager row, open the manager inbox, choose an operating pack, save reusable packs, configure scheduled refresh, and set routing defaults when the team needs repeatable queues.
10. 10Save small control changes inline.
11. 11Open Agent Cockpit, Configure, Inspect, Audit, Studio, or Dependencies when the next action needs a deeper surface.

Proof that it worked

• Counts match expected scope.
• The page pop-out opens the Fleet wall with active fleet, attention, runtime queue, runner state, and a read-only watch list.
• Customize layout reorders cards locally and Reset layout restores the default order.
• No-run agents show dashes instead of fake zero metrics.
• Rows view is the default Fleet experience and remains the main roster surface.
• Agent GPS buttons open `/agents/[agentId]/live` and do not fall through to the cockpit route.
• Only one row expands at a time.
• Rows have a visible Configure button for the full settings page.
• Expanded rows show operational controls, team setup, recent activity, settings/configuration links, and separated destructive actions.
• Manager rows can expand to show child agents when hierarchy is configured.
• The sample fleet banner shows Demo data and Safe to delete when the pack is active.
• Sample fleet controls include Add sample fleet, View sample agents, and Delete sample fleet.
• Manager rows show manager inbox, blocked work, operating pack, reusable pack library, scheduled desk refresh, and routing default controls when manager context is available.
• Dependencies explains shared-resource impact before the graph appears.

Before you start

• Confirm you are on /agents and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If agents are missing, check search, status pills, time window, and whether sample agents are hidden.
• If an agent shows no runs, open the agent Status page and confirm whether there are truly no runs or telemetry is unavailable.
• If Dependencies shows shared risk, inspect what else could break before changing a provider, model, or tool.

Useful Thomas questions

• Which agent should I inspect first from this Fleet view?
• Why does this agent show Needs attention?
• What else could break if I change this shared provider or tool?

Basic workflow

1. 1Confirm status is Active, Draft, Paused, or Retired.
2. 2Open Configure before running when the agent's purpose, model, tools, safety, or review policy is unclear.
3. 3If runnable, send one safe proof prompt.
4. 4Open Inspect and Trace from the run console.
5. 5Use Audit to confirm run start and terminal events.
6. 6Only promote operational use after proof is clean.

Proof that it worked

• Status and run lock state are clear.
• Proof run creates a stable run ID.
• Configure opens with a left rail and section-specific settings.
• Inspect shows latency, cost, tokens, and events.
• Audit shows matching run evidence.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If Run test is locked, read the lock reason and fix configuration, credentials, or status first.
• If a run fails, open Inspect before editing prompts.
• If source evidence is missing, open Audit or Configure before trusting the agent.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Cockpit state?

Basic workflow

1. 1Confirm the status pill and run lock state.
2. 2Read Agent handoff and Manage controls.
3. 3If the page says Runnable, run one proof test before trusting real work.
4. 4If source evidence is missing, open Configure or Audit before running.
5. 5If a recent run exists, open Inspect or Trace for the exact evidence.
6. 6Use the page-title pop-out when this agent should stay visible on another screen.
7. 7Use Customize layout in the Agent Live Monitor when this station needs a different order.

Proof that it worked

• Status pill, version chip, and primary next move are visible.
• Manage controls explain whether Runtime is runnable or locked.
• Recent run preview distinguishes no runs, loaded runs, and unavailable history.
• Performance cards show budget, success, run count, and latency posture.
• The page pop-out opens `/agents/[agentId]/live` as a read-only wall view with auto-refresh.
• Customize layout reorders Agent Live Monitor cards locally and Reset layout restores the default order.
• Source evidence links to Audit or Configure when available.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Status does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Status state?

Basic workflow

1. 1Open an agent's Live page.
2. 2Select Rows for the decision feed or the Agent GPS graph for the radial touch map.
3. 3Watch capability touches appear with allowed, approval-required, or denied verdicts.
4. 4When an action pauses, read the reason, add an optional note, then approve or reject.
5. 5Open Full trace for replay or Outcome Intelligence for trust metrics after the run.

Proof that it worked

• The page header says Live Run Console.
• Rows and Graph toggles are visible; Graph is the Agent GPS visual map.
• Status, cost so far, and touch count cards render.
• Capability touches appear with gate verdicts when a run is active.
• A pending steer decision can be approved or rejected with `decision_source=live`.
• Full trace and Outcome Intelligence links are visible.

Before you start

• Confirm you are on /agents/[agentId]/live and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Live Console does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Live Console state?

Basic workflow

1. 1Open Configure from Fleet, Status, Flow, Pro, or a deep link.
2. 2Start with Identity Brief for mission, audience, authority, tone, escalation, memory intent, and definition of done.
3. 3Use Instructions / Behavior when the agent's actual answers need to change.
4. 4Use Model Policy, Runtime, Guardrails, Tools, and Human Review for execution safety.
5. 5Use Alerts, Quality / Evals, Knowledge / Memory, and GitHub Source Sync to keep the agent maintainable after launch.
6. 6Choose the exact section in the left rail.
7. 7Read the helper copy and current saved values before editing.
8. 8Save the section and wait for confirmation.
9. 9Switch to Status, Flow, or Pro to verify the same policy is reflected there.

Proof that it worked

• The Configure rail highlights the selected section from the URL.
• Each section explains what is saved and why it matters.
• Saving writes a new draft spec instead of silently changing a signed live snapshot.
• Flow policy banners and Pro agent.yaml reflect the saved Configure-owned fields.
• Deep links use `/agents/[id]?tab=configure&section=...`.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Configure does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Configure state?

Basic workflow

1. 1Open Activity from the agent tab bar or a Status card.
2. 2Use Runs for the timeline.
3. 3Select Inspect when a run needs evidence.
4. 4Open Audit when you need to prove who or what changed state.
5. 5Use Versions when you need to compare or restore a saved spec.

Proof that it worked

• Runs show loaded, unavailable, or empty states honestly.
• Inspect links preserve the agent or run ID.
• Audit rows include event type, actor, timestamp, and summary.
• Versions show signed snapshots when available.
• Activity does not pretend missing telemetry is the same as no runs.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Activity does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Activity state?

Basic workflow

1. 1Open Observe from the agent tab bar.
2. 2Check scoped health and recent risk signals.
3. 3For manager agents, compare child cards and blocked work.
4. 4Open Trace for execution timing or tool-step evidence.
5. 5Open Workboard when the next action is a card decision.

Proof that it worked

• Observe remains scoped to the selected agent ID.
• Manager agents show child cards and manager Workboard links.
• Trace links preserve agent or run filters.
• Risk signals explain whether the next page should be Trace, Workboard, or Configure.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Observe does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Observe state?

Basic workflow

1. 1Open Changelog from the agent tab bar.
2. 2Read the newest entry first.
3. 3If an entry mentions a run or operational change, open Activity for the evidence.
4. 4Use Audit when you need actor, timestamp, or state-change proof.
5. 5Use the changelog as demo narration only after the evidence pages still match.

Proof that it worked

• Changelog tab opens without a blank state or 404.
• Entries are plain English and newest first.
• The page makes it clear this is a summary, not a replacement for Activity or Audit.
• Activity and Audit remain the proof path for important entries.

Before you start

• Confirm you are on /agents/ and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Agent Changelog does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Agent Changelog state?

Basic workflow

1. 1Import work or add a card.
2. 2Use the page-title pop-out when Workboard should stay visible on another screen.
3. 3Use Customize layout in the Workboard monitor when this station needs a different queue, runner, or event order.
4. 4Use Proof view if you need to narrow the board to a proof slice before opening cards.
5. 5Use Manager inbox when you need one manager-owned queue without losing the rest of Workboard.
6. 6Start next or open a card drawer.
7. 7Let the runner lease move the card into progress.
8. 8Read the Agent report and decision brief for the selected card.
9. 9Collapse the sections you do not need right now so the selected-card detail stays focused while you work.
10. 10If the card belongs to a manager-owned team, confirm the manager route before sending it forward again.
11. 11For Fleet proof cards, scan Run proof and cost, read Proof state, use Start here for the best next page, then use Open the right page when you need another proof surface.
12. 12If the card shows Retry watch, Retry risk, Blocked, or Stopped, inspect before choosing another attempt.
13. 13Review evidence when the card reaches review.
14. 14Close only when evidence is attached or the stop reason is clear.

Proof that it worked

• Cards move across To do, In progress, In review, and Done.
• The page pop-out opens the Workboard wall with queue health, runner status, and recent events without the full app chrome.
• Customize layout reorders Workboard monitor cards locally and Reset layout restores the default order.
• Active tasks show who claimed work.
• Re-importing the Fleet proof queue refreshes existing proof cards instead of leaving stale run cost fields.
• Selected cards show a report, decision, next safe action, proof count, and retry status.
• Selected cards keep secondary detail in collapsible sections so proof, review, and workspace context stay easy to reopen without crowding the main action path.
• Manager-owned cards show the supervising manager, assigned child agent, and recent routing trail on the card itself.
• Selected cards explain what happened last, whether to keep Run once, and whether Loop is worth the extra pass.
• Fleet proof cards show run status, cost, latency, tokens, model, and audit match.
• Selected proof cards summarize whether proof is still missing, waiting on audit, blocked, review-ready, or healthy.
• Proof cards show a compact proof-state badge in the board view for faster scanning.
• Proof cards show a compact next-step badge in the board view so users can see the likely next move before selecting a card.
• Proof view filters the board to the proof slice you want without changing the underlying card evidence.
• When a proof view is active, Workboard explains the current proof slice and gives users a quick return to all cards.
• Manager inbox filters the board to one manager team or one team-routing state without hiding the card-level routing controls.
• Selected proof cards point to the best next page before showing the full list of deeper proof surfaces.
• Selected proof cards explain which deeper page to open for agent controls, run detail, trace, or audit evidence.
• Retry signals count stuck/watch cards and badges show the reason on affected cards.
• Repeated work stays operator-controlled instead of silently looping.
• Proof packets include agent, prompt, pass criteria, blockers, and evidence links.
• Stale cards can be removed from the board once no active lease is still running.

Before you start

• Confirm you are on /workboard and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If cards are not moving, check that a runner is online and has a recent heartbeat.
• If Start next is unavailable, read Live action readiness and clear provider key, runner, or queue setup first.
• If a card is stuck, inspect What happened last, blockers, and cost before turning on Loop.

Useful Thomas questions

• Why is this Workboard card blocked?
• Is Loop worth using on this card?
• Which proof page should I open from this card?

Basic workflow

1. 1Open the pending item.
2. 2Use the page-title pop-out when approvals should stay visible on another screen.
3. 3Use Customize layout in the Approvals monitor when this station needs a different review order.
4. 4Read the agent request and context.
5. 5Check linked run or audit evidence.
6. 6Approve, reject, or request changes.

Proof that it worked

• Decision item has a clear status.
• The page pop-out opens the approvals wall with pending approval state without exposing approve/reject controls.
• Customize layout reorders Approvals monitor cards locally and Reset layout restores the default order.
• Linked evidence is visible.
• Operator decision is recorded.

Before you start

• Confirm you are on /approvals and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• In demo, approval cards are synthetic and read-only so you can inspect the evidence without mutating the shared workspace.
• If a review lacks context, open the linked run, eval, or audit evidence before deciding.
• If reviews are aging, handle the oldest high-risk item first.

Useful Thomas questions

• Which pending approval should I handle first?
• What evidence should I inspect before approving this?
• Why are demo approval decisions read-only?

Basic workflow

1. 1Open Studio and choose Vibe, Flow, Pro, or Import based on the kind of edit you need.
2. 2Generate or edit the agent in the chosen builder.
3. 3Save the draft so the same agent is available across Studio lenses and Agent Cockpit Configure.
4. 4Use Test Agent for a safe proof run.
5. 5Open Cockpit or Inspect to review status and evidence.
6. 6Switch builders only when a specific edit calls for it; switch to Configure when the change is governance-owned.

Proof that it worked

• The saved agent can be opened from Studio's Vibe, Flow, Pro, and Import lenses where supported.
• Agent Cockpit Configure shows the governance fields for the same saved agent.
• Draft can be saved without forcing a builder-to-builder handoff.
• Test run reaches terminal or review state.
• Inspect can explain the result.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Studio does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Studio state?

Basic workflow

1. 1Open Studio with the agentId for the agent you are editing.
2. 2Pick Vibe for a brief-first draft, Flow for graph wiring, Pro for raw YAML, Import for external sources, or Agent Cockpit Configure for governance.
3. 3Save changes as a draft tied to that agent.
4. 4Switch to another surface to verify the same spec data appears there.
5. 5Use Test Agent, Inspect, or Audit before publishing or demoing the change.

Proof that it worked

• The URL keeps the same agentId while switching Flow and Pro.
• Configure-owned fields appear in Flow as read-only policy banners or panels.
• agent.yaml includes the same policy and graph fields that Agent Cockpit Configure and Flow render.
• Guide links explain each builder behavior without requiring tribal knowledge.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Builders overview does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Builders overview state?

Basic workflow

1. 1Open this changelog before a Studio Coherence review.
2. 2Follow the related links to the feature-specific Guide page.
3. 3Compare the Guide proof checklist with the visible product behavior.
4. 4Block follow-up PRs that change behavior without updating the matching Guide page.

Proof that it worked

• This page links to Builders overview, Loading existing agents, Flow block policy, and agent.yaml schema.
• Each linked page names routes, user value, workflow, and proof.
• GUIDE_STYLE.md exists at the repo root and describes the Guide writing rules.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If What changed this version does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this What changed this version state?

Basic workflow

1. 1Open Studio and switch to Pro.
2. 2Open agent.yaml for the selected agent draft.
3. 3Find the top-level section that matches the Configure section you would otherwise edit.
4. 4Make the YAML change and save.
5. 5Switch to Configure or Flow and confirm the same field rendered there.
6. 6Publish only after the draft has been reviewed and tested.

Proof that it worked

• agent.yaml includes identity, instructions, io_contract, model, skills, knowledge, triggers, approvals, safety, runtime, alerts, quality_evals, self_improve, source_sync, and flow.
• Editing a Pro field updates the matching Configure-facing spec key on save.
• Unrelated saved spec fields survive a Pro round trip.
• The JSON Schema reference is available at /schemas/agent.schema.json and as read-only agent.schema.json in Pro.
• Invalid agent.yaml saves show an actionable schema error and do not create a new version.
• Specs with not-yet-representable fields show a warning and preserve those fields on save.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If this section feels too raw, use Agent Configure first; YAML is for users editing specs directly in code.
• If a field is rejected, run a dry-run apply or compare the matching Configure section before changing production config.
• If a slug fails validation, use a short URL-safe identifier such as support-triage.

Useful Thomas questions

• Should I edit YAML directly or use Configure?
• Which YAML fields map to approvals and tool access?
• Why did this agent spec fail validation?

Basic workflow

1. 1Open /studio?v=flow or /studio?v=pro.
2. 2Click Load agent.
3. 3Search if the workspace list is long.
4. 4Click the agent row to edit the latest draft in place.
5. 5Use the row menu and Duplicate as new agent when you want a fork instead.
6. 6Switch between Flow and Pro and confirm agentId stays in the URL.

Proof that it worked

• Load agent is visible in both Flow and Pro headers.
• Rows show name, slug, status, v-number, and last-edited time.
• Selecting a row updates the URL with agentId.
• Switching Flow -> Pro -> Flow keeps the same agentId.
• Duplicate as new agent creates a separate agent and leaves the original unchanged.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Loading existing agents into the builder does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Loading existing agents into the builder state?

Basic workflow

1. 1Open Studio with an agent selected.
2. 2Select a Flow block that has a policy panel.
3. 3Read the policy values before changing wiring.
4. 4Click the Configure deep link when the saved policy needs editing.
5. 5Return to Flow and reload or reselect the agent to confirm the policy summary changed.

Proof that it worked

• Start node Advanced shows Triggers & Intake instead of Soon placeholders.
• Scheduled agents show cron, timezone, scheduled input, and next-run preview; protocol agents show A2A, AG-UI, ACP, or ANP endpoint details.
• The Start node policy panel links to /agents/[id]?tab=configure&section=schedule.
• Agent node Prompt shows a compiled Instructions / Behavior preview with a Configure deep link.
• Agent node Settings shows runtime caps and reflection state with a Runtime deep link.
• Tool node Settings shows enabled skills, allowed MCPs, and an Open Tools & Skills link to /agents/[id]?tab=configure&section=skills.
• Tool node skill options that are not enabled for the agent are disabled with Enable in Tools & Skills guidance.
• Knowledge node Settings shows citation, freshness, relationship map, memory, retention, and missing-source behavior.
• Knowledge node policy links to /agents/[id]?tab=configure&section=knowledge-graph.
• Guardrails node Settings shows the agent-level Safety banner and links to /agents/[id]?tab=configure&section=guardrails.
• The Safety banner remains visible when node-level Moderation or PII checks are disabled.
• Output node Settings shows accepted inputs, output contract, validation rules, destination, and failure behavior.
• Output node contract policy links to /agents/[id]?tab=configure&section=io-contract.
• The canvas-level lifecycle strip appears below Fit to View and summarizes Alerts, Quality / Evals, and Self-improvement.
• The lifecycle strip links Alerts to /agents/[id]?tab=configure&section=alerts and Quality / Self-improvement to /agents/[id]?tab=configure&section=quality-evals.
• The lifecycle strip can be dismissed without changing the saved agent spec.
• Policy Guide buttons open the Flow policy Guide in a side panel without navigating away from Studio.
• Flow does not add write controls for Configure-owned trigger policy.

Before you start

• Confirm you are on /studio and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If How Flow blocks reflect agent-level policy does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this How Flow blocks reflect agent-level policy state?

Basic workflow

1. 1Open the run by run ID or agent.
2. 2Confirm the governance badge and run risk.
3. 3Review the Policy Compliance Matrix and expand failing rows.
4. 4Read the Approval Chain Timeline.
5. 5Inspect Tool Usage & Data Access, especially PII or write access.
6. 6Review metrics and event timeline.
7. 7Export for Audit if the run needs portable compliance evidence.
8. 8Open Trace for visual path if needed.
9. 9Open Audit for tamper-evident proof.

Proof that it worked

• Run ID is stable.
• Status, latency, cost, tokens, and events are visible.
• Governance badge, policy matrix, approval chain, tool/data panel, risk badge, and filters are visible.
• Export for Audit downloads a JSON file for the selected run.
• Linked audit events exist for run start and run finish.

Before you start

• Confirm you are on /inspect and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Inspect does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Inspect state?

Basic workflow

1. 1Open Evals from Command Center or the Analyze nav group.
2. 2Read overall coverage, configured policy count, stale cadence count, and active regression count.
3. 3Open any regression card before lower-risk scorecards.
4. 4Use Quality over time to choose the agent to inspect.
5. 5Open Scorecard Detail, confirm threshold/cadence/release gate, run the saved eval pack if needed, compare model versions, then use Audit for config-change proof.
6. 6Create eval.regressed and eval.stale alert rules so the scheduled evaluator can page operators and create review-required Audit events.
7. 7Use the matrix and burndown to jump into Quality / Evals and add missing cases.

Proof that it worked

• Coverage bars show category progress and target markers.
• Quality trajectory and backend-marked regression cards are visible when data supports them.
• Scorecard Detail shows policy target, cadence, release gate, stored history trends, scenario bars, test cases, Run evals now, Compare models, Inspect runs, and agent-level Audit proof.
• Backend release gates block live, scheduled, and retry runs when the configured scorecard is missing, stale, regressed, or below threshold.
• The scheduled evaluator writes eval.scheduled_run_created, eval.review_required, and eval.scheduler_completed Audit events.
• Completed test cases include case-level Audit proof links filtered to the exact eval_result entity.
• Test coverage matrix uses saved case metadata, and sparse or scored cells route into real eval work when possible.
• Alert rules can fire for eval.regressed and eval.stale, with alert_outbox and delivered_via evidence for email, SMS, webhook, or Slack attempts.

Before you start

• Confirm you are on /evals and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Evals does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Evals state?

Basic workflow

1. 1Open Observe when you need the best first route into runtime health.
2. 2Use the page-title pop-out when Observe should stay visible on another screen.
3. 3Use Customize layout on the monitor when this workstation needs a different card order.
4. 4Read the sparkline summary cards, cost burn rate, approval queue, activity graph, and top-agent panel.
5. 5Choose Signals, Health, or Trace based on the question you need answered.
6. 6Move to the deeper page only after the Observe home points to the right lane.

Proof that it worked

• Summary cards load for the selected window, including Cost burn rate and Approval queue.
• The page pop-out opens the same runtime health story in a read-only auto-refreshing view.
• Customize layout reorders the Observe monitor for this browser and Reset layout restores the default.
• The live activity graph renders for the selected window.
• Top agents needing attention links into agent Observe pages.
• The page links clearly to Signals, Health, and Trace.
• Current attention explains whether the workspace is calm or needs review.

Before you start

• Confirm you are on /observe and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Observe does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Observe state?

Basic workflow

1. 1Open Trace from a run, agent, or Workboard proof packet.
2. 2Choose one agent if you want the run list to stay in that agent's lane.
3. 3Confirm the metadata panel matches the run and agent you meant to inspect.
4. 4Read the execution timeline and open the flagged step.
5. 5Use the token waterfall and latency chart to decide what caused cost or delay.
6. 6Open Inspect or Audit if the path needs deeper proof.

Proof that it worked

• Execution timeline has phase swimlanes and event bars.
• Slowest and most expensive steps are visually flagged when present.
• Token waterfall, latency chart, metadata, and event detail agree on the selected run.
• Error context appears when a failed run is selected.

Before you start

• Confirm you are on /observe/trace and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Observe / Trace does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Observe / Trace state?

Basic workflow

1. 1Start with All agents and pick the smallest useful window.
2. 2Read the efficiency and cost burn cards before chasing one chart.
3. 3Check API providers to rule out upstream status before changing agents.
4. 4Use the latency view toggle to decide whether the delay starts at first token or across the full run.
5. 5Use the latency breakdown to identify the largest time sink.
6. 6Click a cost bar or choose one agent when you need a tighter read.
7. 7Use Tool performance when failures look tied to a connector or MCP server.
8. 8Use Data lineage checkpoints when the question is where a metric came from or how sensitive data was handled.

Proof that it worked

• The agent filter changes the page scope without leaving Observe.
• The chart updates when the window changes or the agent filter changes.
• Cost burn shows hourly rate, daily total, budget percent, and projection.
• API provider cards show status, uptime, p50 latency, and external status links.
• Latency breakdown names the biggest bottleneck in the current window.
• Tool performance is sorted worst-first and each row links to Inspect.
• Data lineage checkpoints show sources, processing, privacy handling, outputs, and status.
• Cost, model, latency, and tool panels agree on which agent or tool path is carrying the pressure.

Before you start

• Confirm you are on /observe/health and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Observe / Health does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Observe / Health state?

Basic workflow

1. 1Pick the time window and stay on All agents first.
2. 2Read cost to succeed, escalate, and fail before opening a single run.
3. 3Clear anomaly cards before reading lower-priority charts.
4. 4Use status, retry, and rate trends to decide whether the problem is growing or contained.
5. 5Use the incident impact table to see what else a tool or incident could break.
6. 6Open failure categories, spike days, or top errors when you are ready to inspect proof.

Proof that it worked

• Signal cards load for the selected window and selected agent scope.
• Run status uses the styled stacked bar and retry trend shows the 5% threshold.
• Error breakdown, spend calendar, escalation-vs-cost, and anomaly cards render when their data is present.
• Incident impact table lists incidents, tools, affected runs, and next actions.
• Failure categories, spend days, retry callouts, and top errors link into Inspect or Trace.

Before you start

• Confirm you are on /observe/signals and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Observe / Signals does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Observe / Signals state?

Basic workflow

1. 1Open Observe, then Outcomes.
2. 2Read the headline trust metrics before looking at individual runs.
3. 3Find the workflow with the largest completion-vs-acceptance gap.
4. 4Check correction rate to see whether humans are cleaning up the agent's work.
5. 5Compare cost per accepted outcome against Gateway spend.
6. 6Open Trace, Audit, Approvals, or Live Console when a metric needs evidence.

Proof that it worked

• The Observe tab set includes Outcomes.
• Outcome Intelligence shows the message that completion is not the same as trust.
• Accepted outcomes, completion-vs-acceptance gap, correction rate, and cost per accepted outcome are visible.
• Workflow outcomes are listed with enough context to choose the next investigation.
• Human review decisions and run outcomes can be traced back to proof pages.

Before you start

• Confirm you are on /observe/outcomes and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Observe / Outcomes does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Observe / Outcomes state?

Basic workflow

1. 1Confirm the tamper-evident log indicator says hash verified.
2. 2Use change frequency and actor activity to find the change window.
3. 3Filter Audit to config changes, policy exceptions, or the entity ID.
4. 4Expand diffs or version rows before deciding on rollback.
5. 5Export SOC 2 or a custom range when the evidence needs to leave Zahara.

Proof that it worked

• Tamper-evident retention and hash status are visible.
• Change heatmap, actor matrix, policy exceptions, version history, and policy coverage matrix render.
• Config-change rows can expand into before/after diffs.
• Export buttons download visible filtered audit evidence.

Before you start

• Confirm you are on /audit and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Audit does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Audit state?

Basic workflow

1. 1Read Alert history and open-alert count.
2. 2Check Rule effectiveness for noisy rules.
3. 3Open the rule docs panel when a threshold needs context.
4. 4Use the template builder and preview before saving a new rule.
5. 5Confirm the fire log and delivery receipts after a rule triggers.

Proof that it worked

• Template picker, summary preview, and last-100-runs test are visible.
• Alert history, rule effectiveness, and resolution time charts render with empty states.
• Rule rows expand into documentation panels.
• Alert fire log still shows status, trigger, delivery receipts, and related entity.

Before you start

• Confirm you are on /alerts and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Alert settings does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Alert settings state?

Basic workflow

1. 1Open Gateway and choose the correct project.
2. 2Use Overview to read spend, request volume, latency, provider health, and recent request previews.
3. 3Open Models to confirm the alias and provider/model mapping.
4. 4Open Routes to tune fallback, provider order, budget, rate limit, timeout, or default-route status.
5. 5Open API Keys when an app or demo loop needs a scoped Gateway key.
6. 6Open Requests to filter and inspect the exact model-call evidence.
7. 7Use Fleet, Configure, or Flow for tool permission and agent assignment; do not treat Gateway as approval to touch external systems.

Proof that it worked

• The correct Gateway project is selected.
• Overview totals and charts show requests, spend, tokens, latency, provider health, and recent request previews.
• The route alias maps to the intended provider/model and fallback chain.
• The Gateway key is active, tested, and scoped to the selected project.
• The Requests tab shows the request with status, endpoint, provider, model, latency, and detail.
• Tool or MCP access remains governed by Fleet/Configure approval, not by the route alone.

Before you start

• Confirm you are on /gateway and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Gateway does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Gateway state?

Basic workflow

1. 1Open the Integrations tool registry for tools detected during import.
2. 2Review purpose and risk.
3. 3Map to approved capability or leave blocked.
4. 4Run proof and verify tool usage in Inspect or Trace.

Proof that it worked

• Tool references are visible.
• Approval or blocked state is clear.
• Proof run uses only approved tools.

Before you start

• Confirm you are on /integrations and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Integrations tool registry does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Integrations tool registry state?

Basic workflow

1. 1Open the operational page you want to shape, such as Command Center.
2. 2Choose the Page View you want to start from.
3. 3Click Customize this page.
4. 4Add one data block from the block catalog if the page needs more evidence.
5. 5Remove any block that distracts from the job.
6. 6Move important blocks higher in the layout.
7. 7Open block settings for any block that needs a title, chart, or filter adjustment.
8. 8Click Save for me for a personal layout.
9. 9Hard refresh and confirm the selected view, block order, and visible blocks persisted.
10. 10In demo, repeat the visual check only and confirm the workspace remains synthetic and read-only.

Proof that it worked

• The Page View menu shows the current view and available page views.
• Customize this page enters a clear edit state.
• Add data block shows searchable blocks and On page state after adding.
• Remove block and move controls change the draft layout without page jank.
• Block settings open in a drawer instead of a blocking modal.
• Save for me persists the selected personal view and changed layout.
• A hard refresh keeps the selected personal view, block order, and visible blocks.
• Fleet remains row/list-first; Page Views do not replace Fleet's roster default.
• Demo clearly marks synthetic/read-only context and does not offer confusing write actions.

Before you start

• Confirm you are on /settings/page-views and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Page Views does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Page Views state?

Basic workflow

1. 1Open Settings, then Credentials.
2. 2Add or confirm the provider key or workspace secret.
3. 3Test the credential when a test action is available.
4. 4Open Gateway to confirm route readiness.
5. 5Run one proof prompt from Agent Cockpit or Studio.
6. 6For tools and MCP, confirm the credential exists here and the agent-specific permission exists in Fleet or Configure.

Proof that it worked

• The Credentials page uses the vault framing.
• Provider or secret readiness is visible.
• Gateway route can use the provider.
• Proof run does not fail on missing credentials.
• Tool credentials are not treated as agent approval by themselves.

Before you start

• Confirm you are on /settings/credentials and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Credentials does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Credentials state?

Basic workflow

1. 1Open Settings -> Team.
2. 2Confirm the active workspace is correct.
3. 3Choose the least-powerful role that fits the job: viewer, operator, or admin.
4. 4Invite the teammate with that role.
5. 5Have them accept the invitation and sign in.
6. 6Verify they can reach the needed pages and cannot see controls outside their role.
7. 7Use Audit or visible team state to confirm sensitive role/access changes.

Proof that it worked

• Member appears in Team.
• Role is one of viewer, operator, or admin and matches intended access.
• Pending invitations show email, role, and expiry until accepted or revoked.
• User can access beta pages without guest mode.
• Viewer users do not get admin-only credential, role, service-token, or delete controls.
• Operator users can perform approved day-to-day operations without owning secrets or team access.
• Admin-only changes are limited to admin users.

Before you start

• Confirm you are on /settings/team and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Team does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Team state?

Basic workflow

1. 1Open Feedback from the page where friction happened.
2. 2Describe what happened and what was expected.
3. 3Include route, agent, run, or onboarding ID if visible.
4. 4Submit and continue with a workaround if possible.

Proof that it worked

• Feedback is submitted.
• Report includes enough context to reproduce or understand the issue.

Before you start

• Confirm you are on /feedback and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Feedback does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Feedback state?

Basic workflow

1. 1Confirm Thomas Intel is enabled.
2. 2Ask a page-specific question.
3. 3Check that Thomas Intel uses visible page data first.
4. 4Update the operations manual if users keep asking the same question.

Proof that it worked

• Thomas Intel answers from visible page context.
• Thomas Intel does not invent counts, IDs, or private implementation details.

Before you start

• Confirm you are on /settings and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Settings does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Settings state?

Basic workflow

1. 1Open the login page.
2. 2Read or collapse the new-user happy path.
3. 3Enter workspace credentials.
4. 4Confirm the redirect returns to the target page, Onboarding, or Command Center.
5. 5From Onboarding, pick Build, Upload, or Connect before entering Command Center.
6. 6From Command Center, check Team, Credentials, Agent, and Operate readiness before the first live run.

Proof that it worked

• User is authenticated.
• Private routes load without guest mode.
• The happy path explains Onboarding as the first-run starting point.

Before you start

• Confirm you are on /login and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Login does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Login state?

Basic workflow

1. 1Open Register.
2. 2Read or collapse the new-user happy path.
3. 3Enter real identity and company fields.
4. 4Submit and land in Onboarding by default.
5. 5Choose Build, Upload, or Connect from the onboarding page.
6. 6Follow Team, Credentials, Agent, and Operate readiness before the first live run.

Proof that it worked

• Signup rejects free email domains.
• Signup records name, company email, company name, and website.
• Intake is routed for admin follow-up.
• The happy path explains the default Onboarding landing.

Before you start

• Confirm you are on /register and looking at the right workspace.
• Read visible status, warning, or empty-state text before clicking an action.
• If the page shows IDs, copy the relevant agent, run, onboarding, or request ID before switching pages.

If you get blocked

• If the page is empty, check whether filters, scope, or time window are hiding the data.
• If an action is locked, follow the visible lock reason before trying another route.
• If Register / Beta Signup does not answer the question, open the linked evidence page instead of guessing.

Useful Thomas questions

• Based on the visible state, what is the next safe action?
• Which status, warning, or ID should I verify first?
• Which linked evidence page proves this Register / Beta Signup state?