Getting started with ARDS

Early access. This doc is v1. It covers the basics, honestly. If something looks wrong, please tell us — see Getting help.

This is the ARDS documentation for testers. It's split into:

• Quickstart — what you'll do in your first 15–30 minutes.
• Core concepts — vocabulary, lifecycle, how coders work, what costs what.
• Guides — task-oriented walkthroughs you'll come back to.
• Workflows — building and running workflows: the editor, the lifecycle, runs and governance. Missions increasingly run this way, so this chapter earns its size.
• Advanced — power-user surfaces. Optional reading; you can ignore them and still get full value from the product.
• How it works / Architecture — how the platform fits together under the hood. Background reading, not required for daily use.
• Reference — tables for states, models, notifications, and a list of pages you can safely skip.
• Troubleshooting — rough edges we already know about.
• Getting help — how to reach us.

If you've just landed via the welcome email, start with What ARDS is and walk straight down the Quickstart sidebar. Everything else can wait.

A note on this doc: it grows alongside the product. We mark known gaps as we go. If a page promises something the UI doesn't deliver, that's a bug in this doc — tell us and we'll fix it.

What ARDS is

ARDS is a system for getting software built by AI agents, with humans in the loop.

The shape is simple:

1. You describe what you want, in plain language, in a conversation.
2. ARDS turns the conversation into a mission, then breaks the mission into tasks. A mission can also run a workflow — a saved, pre-approved graph of steps — instead of ad-hoc decomposition.
3. AI coders pick up the tasks and do the work, each in its own sandboxed environment.
4. Everything they produce lands in a review mirror first — a separate copy of your repository that you can inspect.
5. Nothing reaches your real repository until you approve it. The same holds when a mission runs a workflow — a run's changes land only when you accept the run.

The last point is the important one. You're not handing over a credit card and letting bots merge code at will. The review step is non-optional, by design.

What you bring: a repository you'd like changes made to (or an empty one to start with), and credentials for at least one AI provider (Anthropic, OpenAI, or a compatible one).

What ARDS brings: orchestration, the coders, the review mirror, and a place to talk to it all.

Why two layers (mirror + origin)

If you've used GitHub bot integrations that commit directly to main, the mirror layer will feel unfamiliar at first. The reason it exists:

• Coders make mistakes. Bots that push straight to your repo make you the recovery plan.
• The mirror is yours. If a coder writes something wrong, it dies on the mirror without ever touching origin.
• Approval is one click. Rejecting and asking for changes is also one click.

Once you've approved a change on the mirror, ARDS pushes it through to your origin on your behalf.

What ARDS isn't

A few things ARDS isn't trying to be:

• A code editor. You read code in the review screen; you don't write code in ARDS.
• A CI/CD platform. ARDS produces commits and PRs. Whether your tests run on push is up to your own CI.
• A model marketplace. ARDS uses the models you connect via API keys. You bring the provider; ARDS uses it sensibly.

If you skim past this page, the one sentence to remember is: a coder's work lands on a mirror you approve, never directly on your repo.

Before you start

A few honest expectations:

• This is early access. The product works, but rough edges are still being filed down. You'll find some. That's expected and welcomed.
• This doc is v1. It covers the path you'll actually take in your first session. Deeper reference docs are coming as the product stabilises.
• Useful feedback is specific. "It broke" is hard to act on. "Screen X hung for 60 seconds after I clicked Y" is gold. Screenshots and rough timestamps help.
• Plan 15–30 minutes for a first session — long enough to set up, sign in, connect a provider, register a project, and start a first conversation.

What you need before the welcome email link

Not much:

• A modern desktop browser. Chrome, Firefox, Edge or Safari, recent versions. Mobile browsers work but the dashboard isn't laid out for small screens yet.
• One API key from a supported provider (see Models, providers & costs for the current list). Anthropic Claude is the recommended default. OpenAI keys (and OpenAI-compatible providers) also work.
• A repository if you want to start with real code — or none at all. When you register a project, the Repository URL field is optional: leave it empty and Genesis hosts the repository for you (a greenfield project). You can bring your own repo later.

What you don't need

• No installation. ARDS lives at https://<your-slug>.ards.etiakorp.com/. Nothing to install locally.
• No CLI. Everything is in the web app. (There's a CLI used by operators to provision tenants — testers don't see it.)
• No payment method during early access. Costs are billed to the API key you connect (your provider, your credit).

What this doc assumes you know

We assume you're comfortable with:

• Git basics (clone, branch, commit, PR) — you won't run git commands here, but the vocabulary helps.
• The idea of API keys / personal access tokens.
• Reading diffs.

If any of those words are unfamiliar, the rest of the doc will still mostly make sense — we explain the new vocabulary as it comes up in Vocabulary. If something doesn't, that's a bug — tell us at Getting help.

Ready? Go to Your first session.

Your first session

This is the happy path — what your first 15–30 minutes look like.

1. The welcome email

You'll receive an email from update@etiakorp.com with a link inside. A few honest notes:

• It may land in spam, especially on Outlook, Live, and Gmail. Check your spam folder first. Mark the sender as legitimate so future system emails reach your inbox.
• If you receive several invite emails (this can happen when provisioning retries during setup), use the most recent one. Older links may still work, but the latest is the canonical one.
• The link points to our identity provider, not to a Genesis page directly.

2. Activate your account

The link walks through two steps, both handled by the identity provider:

1. Set your password. Pick anything reasonable — you'll only need it once.
2. Verify your email. One click confirms it's really you.

After both, you're redirected to your tenant's URL: https://<your-slug>.ards.etiakorp.com/. The exact slug is in your email — bookmark the page.

3. Sign in

You land on the sign-in screen (still the identity provider — Genesis itself is one step further). Your email is pre-filled. Enter the password you just set. You'll only do this sign-in once for the session.

If the URL doesn't load on the first try, wait 1–2 minutes and refresh. New tenant subdomains need a moment for DNS and the TLS certificate to propagate. If it still doesn't work after 5 minutes, see Troubleshooting.

4. Connect a model provider

There's no separate setup wizard — first-run setup happens on the regular pages, in two short steps: connect a provider, then register a project.

The provider comes first, because everything downstream runs on it:

1. Open LLM Config. It's listed on the All features index at the bottom of the sidebar — and until a provider is connected, the Conversations page shows an Open LLM Config shortcut too.
2. On the Providers tab, click Add Provider: give it a name, pick the provider kind — Anthropic (the recommended default), OpenAI / Synthetic, Ollama or JetBrains — and leave the endpoint blank to use the provider's default.
3. On the provider you just created, click Add Credential and paste your API Key.

5. Register your first project

Now the project. Click Projects in the sidebar and fill in the Register New Project form:

• Project Name — anything readable.
• Repository URL — optional, HTTPS or SSH.
  • Paste a URL to have ARDS work on an existing repo. For a private HTTPS repo, there's a Personal Access Token field (read scope; stored encrypted, used only to clone into the mirror). For an SSH URL, the form generates a deploy key for you to add at your Git host.
  • Or leave it empty. The form spells out what that means: "Repository URL is optional. Leave it empty to create a greenfield project: Genesis hosts the repository and creates the customer origin at delivery." That's the easiest first run — no repo to prep, no URL to hunt down.

Click Register Project. That's the whole job: the project is cloned, indexed, and onboarded automatically — ARDS builds its picture of the project from what's actually in the repository. There is no separate onboarding flow to babysit.

While that runs, make it the active project: open the project selector in the top bar — the dropdown that reads All Projects until you pick one — and choose your project. That scopes the app to this project and adds two per-project links under Projects in the sidebar: Project Intel and Onboarding.

6. The dashboard

Head to Home — the dashboard is your home page.

One thing worth knowing early: the sidebar starts small on purpose. A few entries — Tasks, Reviews, Suggestions, Support cases, Research — only appear once your tenant produces its first artifact of that kind (your first task, your first review…), and once revealed they stay. Until then, every page is still reachable from the All features index at the bottom of the sidebar.

From here, two places matter next:

• Decisions — the approvals queue. Once onboarding completes, the project's steward proposes a first mission here, and every approval after that arrives in the same queue.
• Conversations — where you brief ARDS yourself. That's the next page: First conversation, mission & review.

A note about the mobile app

A mobile app exists in development. It's not deployed for testers yet. Stick to the web app in a desktop browser for v1.

First conversation, mission & review

You're on the dashboard. The full loop has three pages: Conversations, Missions, and Reviews. Conversations and Missions are always in the left nav; Reviews joins them later (it appears once your first mission produces work). Walking through them once cements the model.

1. Start a conversation

Click Conversations in the sidebar, then + New Chat.

A blank chat opens. Describe what you want, in plain language, the way you'd brief a developer friend. Worked examples:

• "Scaffold a Python FastAPI service with one /healthz endpoint and a Dockerfile."
• "In my-app/, the LoginForm doesn't show validation errors. Add a red helper text under each field that fails validation."
• "Write a brief design doc for migrating our settings module from JSON to YAML. Don't implement anything yet."

Tips that consistently land good results:

• Mention the file or area when you can. "the cart total widget" beats "the totals thing".
• Say what you don't want. "Don't touch the database schema" closes off a tempting wrong turn.
• One outcome per conversation, ideally. If you want two things, two conversations is cleaner.

ARDS responds in the chat. You're talking to a planning model, not a coder — it asks questions, clarifies scope, and proposes how it'd break the work down. Answer the questions; when it has enough, it proposes a mission.

2. Promote to a mission

When ARDS has a concrete-enough picture, it files a mission proposal itself — there's no create-mission button in the chat, and saying "yes" doesn't start anything on its own. Nothing runs yet: the proposal waits for your approval.

The proposal arrives as a pending item in the Decisions queue in the sidebar. Open Decisions, read it, and approve it — the mission then shows up on the Missions page (you're not navigated there automatically). Prefer to skip the conversation entirely? The Missions page also has a manual Create Mission form.

3. Approve the plan

If your mission was created with a workflow attached, there is no plan-approval step: the graph is the plan, and you decide at the workflow's gates instead — see Runs, acceptance & changements.

Otherwise the mission moves through its planning states (Planning, then Decomposing while the planning model breaks the work into individual tasks — usually 10–30 seconds) and stops at Decomposed. On the mission page you'll see:

• The plan: a list of tasks the mission proposes to run, in order. Each has a one-line summary.
• A banner — "Decomposition plan ready" — with one button: Approve Decomposition Plan (the Missions list offers the same action).

The plan is approved as a whole — there is no per-task selection. If you don't want it, don't approve it: nothing dispatches while the mission sits at Decomposed, and Cancel Mission on the mission page abandons it.

Until you approve, no coder runs on this plan. (Missions that run a workflow pause at the workflow's own gates instead — and either way, nothing lands on your repo without your say-so.) This is the first human gate.

4. Watch the coders work

Approved tasks transition to Pending, then InProgress as a coder picks them up. Each task shows live progress: which step it's on, which files it's touching, what model it's using. You don't need to babysit — you can leave the page and come back. ARDS sends an email when a task needs your attention or when the mission finishes.

One extra task will appear that you never planned: the platform's verification step. On a mission that produces code, once every planned task is finished ARDS appends a system task named "Verify the built application: …". It needs no approval — it dispatches on its own. Its coder checks out the integrated branch read-only, builds and starts the application, exercises the mission's main flow, and reports a verdict as the first line of its result — VERDICT: VERIFIED or VERDICT: FAILED with a reason — changing and committing nothing. The mission only completes once this task finishes, and the verdict is shown with the mission's completion review. Treat anything other than VERDICT: VERIFIED as not verified, and read the task's result for the evidence.

If a task needs you (an answer, a clarification, an approval), that need surfaces as a pending item on the Decisions page in the sidebar — that's not a failure, it's your turn. See Lifecycle states for how the states fit together.

5. Review the result

When a coder finishes, its work lands on the review mirror — a separate copy of your repo. The Reviews page lists pending changes (the sidebar entry appears once your first mission produces work).

Click into a pending review. You see:

• The diff, file by file.
• A one-paragraph summary of what the coder did and why.
• A comment box and two buttons: Approve / Reject.

Approve pushes the change through to your origin repo. Reject (it asks you to confirm, and takes an optional comment) declines the work — nothing reaches your origin. There is no request-changes verb on a review: if you want another iteration, brief it in a conversation — that's the same loop you just walked.

If your mission ran a workflow: the work arrives as a run you accept — or leave unaccepted — not as a review here; see Runs, acceptance & changements.

That's the loop. Most of what's behind the dashboard (settings, fleet management, observability, LLM config) you can ignore for your first session — come back to it when you want.

Vocabulary

A short glossary of the words you'll see in the app. Each one is just what it says on the tin — there's no hidden complexity.

• Conversation — Where you describe what you want, in plain language. Like chatting with a developer who happens to be very, very good at reading specs. A conversation can stay informal forever, or you can promote it to a mission when it's concrete enough.

• Mission — The complete unit of work for one concrete change — usually a conversation that got concrete enough to promote. A mission lives on its own durable branch and holds the runs that build the change. It stays conversable, too: every mission has its own chat, so you can ask it where things stand or steer it mid-flight.

• Workflow — A reusable, versioned plan, drawn as a graph of nodes in the visual editor. A workflow executes nothing by itself: you attach it to a mission, and it runs there.

• Run — One execution of a workflow inside a mission, on its own branch. You review each run's result — the diff — and accept or discard it; accepting folds it into the mission. See Lifecycle states.

• Task — One node of the running plan, materialized as a unit of coder work. A task is an execution snapshot you can inspect: the result, the diff, what it cost, how many attempts it took.

• Changement — The reversible delta an accepted run adds to the mission. The mission's merge request is the composition of its accepted changements, and each one can be reverted on its own (anything built on top follows, with a confirmation first).

• Coder — The AI agent that does the work. Each coder runs in its own container, with the model and tools it needs, and pushes its results to the review mirror. Coders come in three variants (standard, browser, android) — the lanes ARDS queues and scales containers in — and a task can additionally draw on shared capability pools (a real browser, an Android emulator, a Windows environment). See How coders work.

• Review / approval gate — The human-in-the-loop step. Coders push to a review mirror — a separate copy of your repository — and nothing reaches your real repository until you approve it. You approve or reject each batch.

• Attention request — A signal from the system that a person is needed. Most attention requests come from missions ("approve this plan", "answer this clarification") but they can also fire when a coder gets blocked, or a provider key fails. Attention requests are surfaced in the dashboard and via email.

• Modification — A change that has been approved and merged through to your origin repo. The Modifications page is the audit trail of "what actually landed". With the run model, each accepted run lands as a reversible changement, and the merge request is their composition.

• Product — A planned grouping layer above projects. Not in v1: today the top of the tree you'll actually touch is the project/workspace. If you meet the word 'product' in these docs or in chat output, read it as 'a future grouping of projects' — nothing in the current UI points at one.

• Workspace / project — A repository ARDS knows about. You register one from the Projects page, and can add or switch there later. Each workspace has its own review mirror.

• GitMirror — The internal service that holds the review-side clones. You'll see "the mirror" in chat messages and review screens; that's GitMirror.

• Provider — An AI provider you've connected: Anthropic, OpenAI-compatible, Synthetic.new, etc. Providers carry API keys; multiple providers can be connected simultaneously.

• Model — A specific LLM you can route work to: claude-opus-4-7, claude-haiku-4-5, hf:Qwen/Qwen3-Coder-480B-A35B-Instruct, etc. Different models for different jobs — see Models, providers & costs.

• Node instructions — Every workflow node can carry extra instructions layered onto its prompt. You set them by hand — per run, per project, per tenant, or globally; the most specific one wins. ARDS proposing a better prompt on its own is not in v1; if that lands, the proposal will arrive as a decision you approve or reject — nothing will ever apply itself.

That's the core vocabulary. A handful more terms exist on advanced pages (the orchestrator, Ghost, Cycle) — see Advanced. They're optional reading.

Lifecycle states

Missions, tasks, and reviews each have their own state machine. Understanding them takes ~2 minutes and saves a lot of "wait, is this stuck or just thinking?" later.

Every mission follows the same lifecycle; what varies is where its plan comes from. Today most missions are decomposed into tasks by the planner, and you approve the plan before anything runs — that's the path this page describes. Increasingly, a mission carries a workflow as its plan: each execution is a run on its own branch; you accept a run's result — or leave it unaccepted — and accepted runs stack up as reversible changements that compose the mission's change. The workflow-run path is becoming the primary execution model; planner decomposition stays available while that transition completes. Run outcomes are in the states cheatsheet.

Mission states

The happy path reads left to right: a mission is created (Pending), gets planned (Planning — decomposition into tasks, with a stop at Decomposed while ARDS waits for you to approve the proposed plan), runs (InProgress), lands in PendingReview while its results wait on you, and ends Completed — or Failed if it can't continue. Cancelled is the early exit, and it cascades to in-progress tasks. A mission proposed from a conversation starts one step earlier still, in AwaitingApproval: the proposal itself waits for your go-ahead before the mission even enters Pending.

Two states sit beside that line rather than on it:

• Paused is a resumable hold. The Pause button on the mission page stops new work; Resume puts the mission back to InProgress. Nothing is lost while paused.
• Completed, Failed, and Cancelled are terminal — with exactly one sanctioned exception: starting a new run on a Completed mission reopens it to InProgress. That's the only way out of Completed.

A state change the mission doesn't allow is refused, not silently ignored: the error tells you the mission's current state and which transitions it will accept. If an action bounces as an invalid transition, read that list before retrying — the same click will bounce again.

The full state table (every state, terminal vs. resumable) lives in the states cheatsheet.

You can act on a mission at any time:

• Cancel Mission is shown unless the mission is already Completed or Cancelled.
• Pause / Resume hold and release the work.
• Re-planning goes through the plan decision itself: instead of approving, pick Request Changes and the mission returns to Planning for a fresh decomposition. Reject cancels the mission entirely.

Task states

A task is Pending while it queues for a coder, InProgress while the coder works, then Completed (the result lands on the review mirror), Failed (the task page shows logs and the model's last message), or Cancelled. A few tasks pause in special states instead — the coder can exhaust its turn budget, or wait out a provider quota window. Those are covered in Troubleshooting, and the full table is in the states cheatsheet.

Needing you is not a task state. When a task wants a human — an approval, an answer, a choice of direction — that need surfaces as a pending item on the Decisions page. A pending decision is not failure; it's a polite "your turn", and the work waits until you respond.

Review states

Reviews live per-task. Each review represents one batch of changes pushed to the mirror.

A review that's still Pending or In review offers exactly two buttons — Approve and Reject. Rejecting asks you to confirm and takes an optional comment.

If a finding came from the Review Engine (the automated reviewer — see Review Engine), individual findings carry their own status: Open, Investigating, Resolved, Dismissed, Deferred.

The run path

When a mission runs a workflow, each execution is a run with its own small state machine:

While a run waits at a gate, the gate pauses the run's tasks, and the mission shows PendingOperatorDecision until you decide. Run outcomes are in the states cheatsheet; the full acceptance loop is in Runs, acceptance & changements.

What to do when a state surprises you

• Stuck in Decomposing for more than ~2 minutes → refresh the page; the planner sometimes needs the page to be open for SignalR updates. If still stuck, see Troubleshooting.
• A task seems to be waiting on you → open the Decisions page; the pending item's card says what's needed.
• Mission marked Failed but no obvious reason → the failure summary at the top of the mission page surfaces the first failing task's error. Click into that task for the full log.

How coders work

A coder is one Docker container running an AI agent that's been wired up with a model, a set of tools (file edit, shell, git, MCP), and — for each task it picks up — a clone of your workspace. Coders aren't spawned one per task: they're pooled queue consumers, and ARDS grows and shrinks the pool with demand.

The container lifecycle

Tasks queue up per coding tool and variant (standard, browser, android). ARDS regularly compares each queue's depth with the number of coder containers consuming it, and acts:

1. Cold start — tasks are waiting and no container is running for that queue → ARDS starts one. This is why the first task after a quiet stretch takes a little longer to leave Pending.
2. Scale up — the backlog grows past a threshold → another container joins, up to a cap.
3. Work — a container picks up a task (the task shows InProgress), clones your workspace from the review mirror, and gets going: reads files, runs commands, edits, tests, iterates. Everything happens inside the container — your host filesystem and origin repo never see any of it. Credentials the coder needs (API keys, git tokens) are injected as environment variables when the container starts.
4. Task end — success, failure, or cancel: the coder commits to a branch on the mirror and pushes. Anything that wasn't committed is lost — by design.
5. Reuse — the container doesn't die with the task; it goes back to its queue and consumes the next one.
6. Scale to zero — once a queue has sat empty for a stretch of idle minutes, its containers are removed. A container that exits or turns unhealthy is replaced automatically while work is still queued.

So a container may live through one task or many — but a task's work products live exactly as long as they're committed to the mirror. That point matters for what coders can and can't do, see below.

Inside a workflow, a coder's success, failure, or refusal routes down the workflow's outcome arms — see Anatomy of a workflow.

Coder capabilities

Every task runs on the standard coder image (backend, frontend, MCP tool development — .NET 10 SDK, Node.js, npm, common test frameworks). What varies per task is which extra capabilities are attached to it, drawn from shared capability pools:

• Browser — a real Chrome for visual testing, browser automation, or E2E flows that need a real DOM.
• Emulator — an Android emulator for mobile work.
• Windows tooling — a Windows environment for tasks that need one.

You don't pick these yourself — they're attached when the task calls for them, and most tasks need none of them. If you're curious how a task ran, the task page's details include the provider that served it, the branch it worked on, how many turns it took, and what it cost.

What coders can do

• Read, edit, and create files in the cloned workspace.
• Run any command available in the image — dotnet, npm, pytest, etc.
• Hit the internet for documentation and package downloads.
• Use MCP tools (the ARDS bridge) to look up project state, validate work, etc.
• Commit + push to the mirror.

What coders can't do (or won't)

• Push to your origin repo. Only the approval flow pushes through to origin.
• Persist work anywhere but the mirror. Only what's committed and pushed survives a task; the container's scratch state is disposable, and idle containers are routinely scaled away.
• See other tenants' data. The coder pool is per-tenant; one tenant's containers never serve another tenant's tasks.
• Hold a conversation directly with you. If a coder needs input, it raises an attention request that surfaces in the dashboard — it doesn't pop up a chat window.
• Edit code outside the workspace. Coders are scoped to one workspace at a time.

Where to read coder logs

On any task page, the Coder session link at the top opens the live session view for that task — everything the coder said and did: the tool calls, the model output, the commands it ran. If a task failed, this is where the cause usually lives. The same data feeds the Costs page (token-level accounting per task — see Tracking costs).

For workflow runs, the run viewer goes further: the node sheet and the Coder session panel show the effective prompt exactly as dispatched, the files touched, a diff on demand, and per-file or zip downloads. See Watching a run.

How long a task takes

Highly variable. Small refactors finish in a couple of minutes; a "write a new module with tests" task might take 10–20 minutes; an "implement feature X end to end" task can run an hour or more. Token usage scales roughly with wall-clock time when the same model is in use.

Models, providers & costs

ARDS doesn't run its own models. You bring API keys and ARDS routes work to those providers. This page covers the model lineup, what each is good for, and how billing works.

Provider families

• Anthropic Claude — the recommended default. Per-token billing through your Anthropic account. Four model tiers (Fable / Opus / Sonnet / Haiku) trading intelligence for cost.
• OpenAI & OpenAI-compatible — supported via the same sk-… API key shape. Use this for OpenAI directly or for any provider that exposes an OpenAI-style API (e.g. Azure OpenAI, OpenRouter).
• Synthetic.new — flat-rate subscription, not per-token. Hosts a curated catalogue of strong open-weight models (Qwen, Kimi, GLM, MiniMax and others). Good for high-volume work where token costs would otherwise pile up. Models carry the hf: prefix in their IDs.
• JetBrains — also selectable in the add-provider dialog on the LLM Config page.
• Ollama (local) — supported but only when you're running ARDS-adjacent infrastructure yourself; not relevant for hosted testers.

You may also meet a GitHub Copilot provider entry: a bring-your-own-key kind, backed by a fine-grained GitHub PAT with the Copilot Requests scope.

You can connect more than one provider. ARDS uses fallback chains so that, e.g., a primary Claude call that fails on credits silently retries on Synthetic. Configure chains on the LLM Config page.

Picking a model

For your first session, leave the defaults alone. The default conversation model is Opus; coder tasks follow the platform's presets, which pick a model per kind of work.

When you're comfortable, the rough rules of thumb:

• Planning / decomposition → Sonnet. It's fast and good at structure.
• Implementation tasks → Opus for harder tasks, Sonnet for routine.
• Test scaffolding / boilerplate → Haiku. A fifth of Opus's price per token and entirely capable for repetitive work.
• Cost-controlled high volume → Synthetic.new (e.g. Qwen3 Coder 480B). Flat-rate so you can leave it running.

Costs you'll see

The Costs dashboard tracks every dollar spent. Its two main panels are Costs by Source (which part of the platform spent it) and Costs by Model (where your spend concentrates). Filters above them slice by provider and date range, and switch the cost basis between Billed, API-equivalent (what subscription-covered usage would have cost at per-token rates), and Both. The page also shows subscription-usage windows, rate-limit events, and a table of recent cost records.

Anthropic prices are set per model family (per million tokens, current as of v1):

Newly discovered versions inherit their family's figures — Opus 4.8 and Opus 4.7 both bill at the Opus rates. Fable is the top tier, with a 1-million-token context window for work that needs a very large view. The full current lineup is in the models reference.

Synthetic.new is flat-rate by subscription — no per-token math; pick a plan and pour as much work through as you like.

Honest expectation: a "fix this bug" task costs cents on Sonnet. A "build a new microservice end to end" mission spanning several Opus tasks can run several dollars. The Costs page tells you in real time.

What happens when a key runs out

• Out of credits → you get an error in the mission, and (if a fallback chain is configured) ARDS retries on the next provider in the chain.
• Rate-limited → ARDS backs off and retries. Long-running rate limits surface as an attention request.
• Key revoked or invalid → mission fails. Re-add the key on the LLM Config page.

See Troubleshooting for the specific error shapes.

Security & data boundaries

A plain-English version of "where does my code go" and "what does ARDS keep". If you're using ARDS for real-repo work, this is the page to read carefully.

Your code

• Origin repo (yours): ARDS never pushes to it without your explicit approval click. There is no "auto-merge" mode in v1.
• Review mirror (ours): when you connect a repo, ARDS clones it onto an internal Git server. Coders work against this mirror. Approved changes are pushed back to your origin on your behalf.
• Coder containers: each coder works on its own clone of the mirror, inside a container from your tenant's pool. Containers are reused across tasks and scaled away after idle minutes — and nothing a coder doesn't commit and push to the mirror survives the task.

If you delete your tenant, all mirrors and conversation history go with it. (Backups are kept on rotation for short-window restore. Ask support if you need exact retention numbers.)

Your API keys

• Stored in our secret store (HashiCorp Vault on the platform side).
• Injected into coder containers only as environment variables at container start.
• Never written to disk inside the container.
• Never logged in plaintext.
• Never sent to providers other than the one the key is for.

You can revoke them at any time. Either remove from the LLM Config page (we stop using it immediately) or revoke at the provider — ARDS will surface the rejection as an error.

Your conversations and missions

• Stored in our database (Postgres).
• Visible only to your tenant.
• Used internally for:
  • Mission orchestration (the planning model reads the conversation it's planning).
  • Searchable history in the Intelligence dashboard (your own search; tenant-scoped).
  • Cost accounting (token counts per task).

We do not train models on your data. We don't have a model to train.

The in-app Ask Genesis help assistant answers product questions only — it can't see or change your project data.

Tenant isolation

• Each tester gets their own subdomain: <slug>.ards.etiakorp.com.
• Each tenant has its own Postgres database (separate database per tenant inside a shared Postgres cluster).
• Each tenant has its own Vault namespace for secrets.
• Coder containers are pooled per tenant; one tenant's coder can't see another's data.

The shared edge components (Postgres cluster, Vault server, K8s control plane) are tenant-aware: every query is filtered by tenant ID at the row level and the database boundary.

What about secrets in code?

If your repository contains hard-coded secrets and you push them through the review mirror, the coders will see them. They won't do anything with them deliberately, but they're still visible. Recommendation: don't trust the mirror for unredacted secrets; rotate any key that's lived in the mirror's history if you decide to move off ARDS.

The Review Engine's secret-scan domain catches obvious leaks (AWS keys, JWT tokens, etc.) and surfaces them as findings — see Review Engine.

What we log

• Mission state transitions.
• Task starts, ends, failures, with anonymised durations and token counts.
• HTTP errors hitting the dashboard.
• Operator-side platform metrics (CPU, memory, etc.).

Logs do not contain prompts or model outputs. They contain enough to debug "why did this mission fail" without snapshotting the content of your conversation.

Notifications

ARDS sends emails when something needs your attention or when something finished. Everything you see in email is also visible in the dashboard.

Email events you might see

• Welcome / activation — once, when your tenant is provisioned. Sender: update@etiakorp.com. Subject mentions account activation.
• Mission decomposed — when a mission's plan is ready and waiting for your approval. Subject names the mission and the task count. The link goes straight to the approval screen.
• Mission completed — when every task in a mission succeeded.
• Mission failed — when a mission can't continue. The email summarises which task failed and why; the link goes to the failing task.
• Attention request — when a coder needs human input mid-task (a clarification, an approval, a decision). The email contains the question text. Use the dashboard link to respond; replying to the email itself doesn't work in v1.
• Task failure — when an individual task errors out (separate from full mission failure, e.g. one task in a five-task mission).

What you won't get emailed about

• Routine task progress (those land in the dashboard only).
• Cost milestones (visible in the Costs dashboard).
• Successful Review Engine findings (they queue up in the Reviews page).
• System maintenance windows — those go via operator-side comms, not in-app email.

Sender domain and spam

All system mail comes from update@etiakorp.com. If you're using Outlook, Live, or Gmail, the first email frequently lands in spam — mark the sender as legitimate the first time and subsequent mail reaches your inbox normally.

We don't send marketing email. If we ever need to send platform-level news, it'll come through the same channel with a clear subject prefix.

Threading

Emails about the same mission are threaded together by mission ID. If you have email-thread view in your client, every notification for a mission lives in one conversation.

Replying to notifications

Replying to a system email lands in our inbound queue but doesn't drive action in the product. For a support reply, use support@etiakorp.com directly. To answer an attention request, click through to the dashboard.

Muting

There's no self-serve mute panel yet — the Settings dashboard holds the platform's configuration values and an audit log, not notification preferences. Recipients and per-event templates are managed on the platform side. If a class of email bothers you, write to support@etiakorp.com and we'll adjust it for you.

Workspaces & repositories

In the dashboard, the home of a codebase is a project: registering one tells ARDS where your code lives and makes it the place missions run against. Behind the scenes ARDS keeps its own clone of your repository — the working copy coders write to (you'll see it called the workspace in status messages) — and pushes approved work back to your real repository. You never manage the clone yourself; you manage projects.

There is no separate setup wizard any more. Registering a project does the whole job: it is cloned, indexed, and onboarded automatically, and the first mission — like every approval after it — arrives in the decisions queue.

The Projects page

Projects in the sidebar opens the registry — the page titles itself Project Management. All Projects lists every project as a card: its name (click through to the project's page), a status badge, its type, a link to its repository, and an Aspects progress figure from onboarding.

While the first clone is running, the card says Cloning workspace…. If it fails, the card says Workspace clone failed. with a hint about the likely cause and a Try Again button — a bad token or an unreachable host are the usual suspects.

Register a project

The Register New Project form sits on the same page:

• Project Name — required.
• Repository URL — where your code lives. The form adapts to what you paste:
  • HTTPS — for a private repo, add a Personal Access Token. The form states the scope it needs: "Required scope: read_repository (GitLab) / repo read (GitHub). Stored encrypted; used only to clone into the mirror." It also offers a direct link to your provider's token-creation page.
  • SSH — click Generate deploy key; ARDS generates an ed25519 keypair and shows you the public key to paste into your provider's deploy-keys list. Grant write access: a read-only key clones fine, but blocks the push back to your repository when work is approved later.
  • Empty — allowed. The form explains: "Repository URL is optional. Leave it empty to create a greenfield project: Genesis hosts the repository and creates the customer origin at delivery."
• Description — optional.
• Type — Managed, Consulted, or Observed.

Click Register Project and watch the new card appear in the list; the clone, indexing, and onboarding run on their own from there.

Pick the active project

The project selector lives in the top bar of the dashboard, showing All Projects by default. Picking a project scopes what you see — conversations, missions, and decisions filter to it — and per-project entries (Intelligence, Onboarding) appear in the sidebar for it.

A project's page

Click a project's name to open its page: the description, its id, current phase, repository link, and creation date, plus the project's vision when one is set. From here you reach the project's Intelligence and Onboarding views, see the branch state across its missions, review its design canvases, and set up app browsing targets.

Boundaries: what agents may touch

The Projects page also states the standing rules — Constitutional Boundaries — that apply to every project:

• Boundary (Protected) — .git/, main branch, *.env files: agents don't touch these.
• Requires Approval — merge to main, delete protected files: only with your explicit approval.
• Autonomous — feature branches, regular files: agents work freely here.

This is why day-to-day agent work happens on branches, and why anything that lands on your main branch passed through a human gate first.

How approved changes reach your repository

Approved work is pushed to your repository automatically, using the credential you provided at registration — the Personal Access Token for HTTPS, the deploy key for SSH. There is no separate "publish" step, which is also why a read-only deploy key eventually hurts: cloning worked, but the approval push fails.

When a mission runs workflows, the path has one more named layer: each run you accept lands as one changement on the mission's branch, and the mission's merge request is the composed stack of those changements. Each changement can be reverted individually — dependent changements cascade, and you see a preview of the cascade before anything is undone. See the changement stack.

Design canvases

A design canvas is a set of visual mockups — several artboards laid out on one surface — produced for your project by a design task. The project page has a Design canvases panel listing every canvas produced so far, with its artboard count (N artboards); before any exist it says: "No design canvases yet. Dispatch a design task to create one."

Click a canvas to open the full-screen viewer at /projects/{id}/design/{taskId}/{slug}. There you can pan and zoom across the artboards, export what you see as PNG or PDF, and download the canvas sources as a zip (Sources (zip)). The viewer is view-and-export only.

How one comes to exist: a design-type task produces it. When the visual direction is genuinely open, the coder drafts a few low-fi direction artboards first and asks you to choose between them — that question arrives in the Decisions queue. Look at the directions in the viewer, answer the decision, and the task continues by building out the direction you picked.

One honest limitation: canvases are produced by tasks, not hand-edited — there is no editing them in the dashboard. If you want a canvas changed, say so in the mission or task that owns it.

Tuning LLM configuration

The LLM Config page in the sidebar is where you go beyond the "paste one API key and roll" defaults. You probably don't need it in your first session. Come back when you want to:

• Connect a second provider, or a second key on the same provider.
• Change which model a call site uses (dialogue, mission decomposition, research…).
• Set up a fallback chain (primary configuration fails → retry on the next one).
• Restyle the whole setup in one click with a configuration mode.

A Project selector sits at the top of the page: System (default) edits the shared configuration; picking a project scopes your changes to that project only.

The six tabs

The page is organised as six tabs: Providers, Tools, Presets, Call Sites, Prompts, Modes.

1. Providers — the providers you've connected and the credentials (API keys) attached to each. This is where keys live.
2. Tools — coding-agent tooling for the coder fleet: the default tool, variant and model coders run with, and how many can run at once. Most testers never touch it.
3. Presets — saved model configurations built from steps. Step 0 is the primary configuration; additional steps form the fallback chain.
4. Call Sites — every place the product calls a model, grouped Research / Planning / Build. Attach a preset or manage a site's existing overrides here. This is the main lever you'll use.
5. Prompts — per-site system prompt adjustments: add a preamble in front of the default prompt, or replace it entirely, with an Effective prompt preview.
6. Modes — one-click switches that apply a named configuration across all call sites at once.

Common things you'll want to do

Add a provider and a key

Open the Providers tab. Click Add Provider and fill in a Name, the Provider Kind (Anthropic, OpenAI / Synthetic, Ollama or JetBrains) and optionally an Endpoint (leave blank for the provider's default). Then expand the provider row and click Add Credential: give the key a Label, optionally a Rate Limit Group and a Priority, and paste the API Key.

Click Test on the credential row to check that the key authenticates. The provider row has its own Test button too — it tests the highest-priority active credential.

A provider can hold several credentials. They are tried in priority order, and the ▲/▼ buttons move a key earlier or later in that order. A key that starts failing can be Quarantined (and reactivated later) without deleting it.

Pick which model a call site uses

Open the Call Sites tab. Sites are grouped by layer — Research (dialogue and research sites), Planning (mission decomposition), Build (execution). Find the card you want — for example Dialogue, or Mission Decomposition — and expand it. Pick a preset from the — Select preset — dropdown to apply it to that site — attaching a preset is how you choose the model. The Site Overrides section below lists any overrides already in effect on the site; the ✕ button resets one back to its default.

Dialogue is the most conversation-heavy site; decomposition is where mission plans are written. Moving either up or down a model tier is the cheapest way to trade quality against cost.

Set up a fallback chain

Fallback chains live inside presets. Open the Presets tab and create or edit a preset: it is a list of Steps, where step 0 is the primary configuration and each additional step is tried in turn if the previous one fails. Attach the preset to the call sites you care about from the Call Sites tab.

A common chain: an Anthropic step first, a Synthetic step second. Day-to-day runs on your Anthropic quota; if it's exhausted, the Synthetic flat-rate step picks up and keeps things moving.

Separately, within one provider, multiple credentials fail over by priority order (see above) — no preset needed for that.

Apply a mode

The Modes tab holds named whole-configuration switches — cards like Economy Mode, Max Intelligence, Synthetic Only, Local (Ollama) or Reset All. Click Apply on a card to preview and apply it across all call sites at once. You can also capture your current setup as a new mode (Capture Current State as Mode), and an application history at the bottom records who applied what, when.

Switch to a Synthetic.new model

ARDS recognises Synthetic models by the hf: prefix (e.g. hf:deepseek-ai/DeepSeek-V3.2). Connect a Synthetic credential on an OpenAI / Synthetic provider, then pick an hf: model in a preset step.

Things to know

• Changes apply immediately. The next call (dialogue turn, next task) uses the new config. In-flight calls finish on whatever config they started with.
• Every call is snapshotted. The LLM Snapshots page is a per-call viewer — it records the resolved configuration and provenance of each LLM call. Query it by time range and call site to retrace "what setup produced this output". Captured request/response text is purged after 7 days; snapshot rows after 30.
• Cost surprises are real. Moving everything up a model tier can multiply spend several times over. Watch the Costs page after big config changes.

When to leave it alone

For your first three or four missions, leave the defaults in place: dialogue sites default to Opus, and research and mission decomposition default to Sonnet 4.5. The LLM Config page is powerful but exposes a lot — don't tune it until you've felt the baseline behaviour.

Tracking costs

The Costs dashboard is the source of truth for "what does ARDS cost me?". It pulls from the live token accounting every LLM call generates.

Billed vs. API-equivalent

The dashboard's headline idea: not all usage is billed. A call that ran on a flat-rate subscription credential (an Anthropic subscription, Synthetic.new) costs you nothing extra — but the dashboard still computes what it would have cost at API list prices, so you can see the real weight of your usage.

The Cost basis switch at the top of the page has three positions:

• Billed — only dollars actually metered (API-key usage).
• API-equivalent — the ≈$ value of everything, as if it had all been API-metered.
• Both — the default: billed spend plus subscription-covered usage side by side.

The Cost Overview panel reflects the basis you picked, alongside total records and input/output token counts. A dedicated card, API-Equivalent (Covered by Subscription), carries the note "Not billed — this usage ran on the flat-rate subscription".

When subscription credentials are active, a Subscription Usage card also shows the provider's quota windows — session (5h) and week (7d) — with the percentage used and when each window resets.

What you see by default

The landing view shows the trailing 30 days. The filter bar offers:

• Date range — 24h / 7d / 30d / All tabs, or a custom From / To range.
• Provider — filter everything to one provider.

Below the overview, two panels split the spend:

• Costs by Source — by what generated the call: coding_task, research, dialogue, mission_agent, workflow, email_content, search_synthesis, and so on. This is where you spot patterns like "research is 30 % of my total".
• Costs by Model — by model, across providers.

Drilling down

Click a row in Costs by Source or Costs by Model to open a repartition drawer: a source's spend split by model (Repartition by model), or a model's spend split by source (Repartition by source).

There is no per-mission cost report. Instead, the Recent Cost Records table at the bottom lists individual records — timestamp, source, model, tokens, estimated cost — and each row links to the page that owns it: the coding task, the mission, the conversation. For per-call detail (the exact configuration and provenance of one LLM call), use the LLM Snapshots page.

What's free vs. metered

• Subscription credentials (Anthropic subscription, Synthetic.new flat-rate) — not billed per call. Their usage shows up as API-equivalent ≈$ values and counts against the subscription's quota windows.
• API-key credentials — metered per token. Every input and output token counts, at the provider's list price.

The dashboard shows public list prices. If your billing relationship gives you a discount, your actual invoice will be smaller than what the page reports.

Quotas and limits

Two surfaces keep you ahead of quota trouble:

• The Rate Limit Events table on the Costs page lists recent rate-limit hits — timestamp, the task that hit the wall, provider, model, and when the limit resets.
• The Quotas page shows each account's subscription quota windows with an Open / Shut until verdict per account. When an account's quota is exhausted, ARDS stops spawning new agent work on it until the window resets.

There is no hard spend limit: ARDS won't pause work because metered spend crossed a dollar threshold. If you want a guardrail, run on subscription credentials (flat-rate, can't surprise you) or set a monthly cap at your provider (Anthropic's console has one) — and watch the Costs page after big configuration changes.

The Decisions Dashboard

Decisions is always in the sidebar, and it is the one queue that matters most: everything in ARDS that is waiting on a human lands here. Wherever an attention request is raised — a mission asking you to approve its tasks, a workflow run parked on an approval gate, a coder blocked on a clarification, a provider key that failed — it surfaces on this page, across all your missions and projects, so you never have to hunt through individual mission pages to find what needs you.

Its subtitle says it plainly: Decision Queue and Attention Requests.

What lands here

Every card in Pending Decisions is something ARDS cannot (and will not) do on its own:

• Task approvals — a mission decomposed into tasks and waits for you to approve them before coders start.
• Workflow gates — a running workflow reached an approval gate. These cards carry a Workflow gate badge, and when a live run is sitting behind the gate, a second badge: A run is parked on this gate. A gate may declare its own named choices and even typed fields for you to fill in.
• Design-direction choices — a design task drafted a few visual directions and asks you to pick one. View them on the project page first (see Design canvases), then answer here.
• Clarifications — a coder is blocked and needs a question answered.
• Errors that need a human — for example a provider credential that failed.

Each card names its type (Decision, Approval, Input, Clarification, Error), its priority (Critical, High, Normal, Low), the mission and project it came from, what it is deciding on, who raised it, and how long it has waited.

One deliberate exception: mission code reviews are handled on the Reviews page, not here. The Pending tile points at them — N in Reviews — so the count stays honest without duplicating the review workflow.

Reading the queue

The strip at the top — Queue Statistics — shows Pending, Acknowledged, Avg Wait, Oldest, and Stale (items waiting more than 7 days), plus per-priority chips you can click to filter. Every figure is computed over exactly the rows rendered below it.

The toolbar cuts the queue down: a search box (Search title, mission, project, target, id), filters by type, age (Last 24h, 1-7 days, Stale (7d+)) and project, a Workflow gates only toggle, and a sort selector — Triage order (priority, oldest first) by default. Showing X of Y tells you what the filters are hiding; Reset brings everything back.

Acting on one decision

Click a card to open the Decision Details panel. It shows the full description, the context the decision was raised with (a gate over research branches shows each branch's output separately), and any choices the decision declares.

• Acknowledge marks the decision as seen — it moves from Pending to Acknowledged — but resolves nothing. Use it to signal "I know, I'll get to it."
• Resolve is the real action: pick a resolution, optionally add notes, and confirm. When a decision doesn't declare its own choices, the dropdown offers Proceed, Skip, Fail/Reject, and Defer: Proceed lets the gated work continue, Skip cancels the gated step, Fail/Reject fails it, Defer leaves it waiting. A workflow gate may instead declare its own named options and typed fields — required fields must be filled before Resolve enables.

Resolving is what unblocks the mission, task, or run that was waiting. See Lifecycle states, gates, and workflow governance.

Resolving several at once

When retries pile up you often face several byte-identical decisions. Tick their checkboxes and a bulk bar appears (N selected):

• Resolve selected applies one resolution to the whole selection — but only when the selected decisions are genuinely alike. Mixed selections are refused with an explanation: "These decisions are not alike. One verb cannot mean the same thing for all of them - select decisions of a single kind, or resolve them one at a time."
• Select all N alike widens the selection to every visible decision of the same kind — it selects, it never resolves.
• Some decisions can never be bulk-resolved: governance changes, separation-of-duties gates, and gates with required typed fields must each be opened and resolved on their own. The bar tells you which rail held and why.
• The receipt stays visible after the batch: "N resolved, M refused. The refused decisions are still selected and still pending."

There is no bulk acknowledge — acknowledging is a per-decision action in the details panel.

The habit

When a mission seems idle, check Decisions — it is usually waiting on you. Autonomy in ARDS is bounded by this queue: work stops at every human gate until you answer, so the queue's throughput is your throughput.

• Work Critical priority and the Oldest items first — those hold the most back.
• Refresh re-pulls the queue; Updated: HH:mm:ss shows when the view last did.
• A decision can also be resolved from the mission page it came from; this dashboard is just the aggregated, cross-mission view of the same queue.
• Decisions also arrive by email as attention-request notifications, but replying to the email doesn't drive action in v1 — click through to the dashboard to respond.

Searching your history

Two pages give you two different ways in: Search federates a query across your project and your history, and the Conversations page carries its own filter language for digging through past dialogue.

Search

Type a phrase, hit Enter. The query fans out to seven sources, each with its own toggle above the results:

• Code — your project's codebase, as ARDS has it cloned.
• Chat — your conversations, both your inputs and ARDS replies.
• Expert — expert knowledge attached to your projects.
• Docs — documentation sources.
• Git — your repository's commit history.
• CI — CI pipeline results.
• Web — the public web.

Each result links back to the original record, and per-source pills above the list show how many results each source returned. Results come Ranked (one merged list) or Grouped (by source).

Show advanced filters adds a File filter (e.g. *.cs *.razor), a Branch, From / To date pickers, and Max per source.

AI Synthesis

Tick AI Synthesis before searching and ARDS writes an answer over the top of the results — a short synthesis with citations back to the individual sources it drew from. It costs one model call (it shows up on the Costs page as search_synthesis), so leave it off for quick lookups.

Filtering conversations

The search bar on the Conversations page is a different tool: a filter language over your conversation list. Switch it from Simple to Advanced and the bar accepts queries like:

• title:"architecture review", body:refactor, id:a1b2 — text fields.
• model:opus, status:active, tag:CI — attribute filters.
• messages:>5, tokens:>10000 — numeric thresholds.
• after:monday, after:yesterday, age:>24h — time.
• is:pinned, is:archived — flags.
• has:missions, has:tasks, missions.status:failed — relations.

Terms combine with spaces (AND), OR between alternatives, and a leading - negates: -status:completed. The ? button opens the full syntax reference with clickable examples; the query-builder button composes a query visually; and the bookmark button holds preset queries plus any you save with Save current query....

Intelligence dashboard

Intelligence is not a search-history view — it's a per-project knowledge page. Open a project and its Intelligence entry appears in the sidebar, with tabs:

• Profile — what ARDS knows about the codebase: primary language, framework, build system, completeness.
• Knowledge — the knowledge sources registered for the project, and discovery to find more.
• Prisms — analysis passes over the project.
• Governance — governance rules in force.
• Alerts — things that need attention.

Use it when you want to see what ARDS understands about a project — not to look up something you said last week.

What's not in search

• Coder logs — they're per-task, on the task page. Search doesn't index them.
• External provider logs (Anthropic's, Synthetic's). Search doesn't reach those.

Privacy reminder

Search results are scoped to your tenant. There is no cross-tenant search, and there is no operator search of your tenant. (Operators can see system logs for debugging, but not the contents of your prompts or model outputs.)

If you want a record deleted — say you pasted a secret into a conversation by accident — open a support case and we'll wipe the specific record (we can do this on demand for v1; longer-term we'll add a self-service path).

Filing a support case

You can report a problem without leaving ARDS. Use it for anything where email feels heavy — bug reports, "is this expected?" questions, feature requests.

Filing a case

Click the floating ? button in the bottom-right corner (Help & support). It offers two options: Ask the assistant, for product questions, and Report an issue, which opens the report form:

• Summary — one short line. "Mission stuck Decomposing for 3 minutes" is good. "It's broken" isn't.
• Description — what happened, what you expected, what you tried. Include rough timestamps (so we can find logs).
• Severity (optional) — Low / Medium / High. Leave it empty if you're not sure; we triage everything anyway.
• Include a screenshot of the current page — tick it and ARDS captures the page for you when you submit.
• Attachments (optional) — add files from disk: up to 20 per report, 10 MB total. For anything bigger, use email.

Click Submit. The case appears on your Support cases page in state Received.

Why use this over email

Cases filed in-app are tied to your tenant, can carry a screenshot of the exact page where things went wrong, and surface in your dashboard — you see every status change directly, without checking your inbox.

Email still works (see Getting help — support@etiakorp.com). Use email when:

• You can't sign in (so you can't open a case).
• Your files exceed the in-app limit (20 attachments / 10 MB per report).
• The issue involves billing or security and you'd rather not file it in-band.

What happens next

We read it. Response times during early access are best-effort — somewhere between minutes and a couple of business days depending on time zone and severity.

The case moves through states you'll see as badges:

• Received — filed, not yet picked up.
• Investigating — someone (or an investigation mission) is looking at it.
• AwaitingReporter — we asked a question; the case thread says "The team is waiting on your reply." — answer there.
• Confirmed / Fixing — the bug is reproduced, then being fixed.
• AwaitingVerification — a fix shipped, and it's your call: "The team has shipped a fix. Please verify whether it resolves your issue." with two buttons, Confirm fixed and Still broken. Only you, the reporter, can close this loop.
• Resolved — you confirmed the fix.

A case can also close with a verdict instead of a fix: WontFix, CannotReproduce, Misconfiguration, Misuse, or Duplicate — each states why, so the outcome is never a silent close.

While a case is open you can add context to the thread at any time; it doesn't change the state.

Anti-patterns

• Don't paste secrets. Mask anything sensitive in screenshots. We don't need API keys or tokens to diagnose — they make our retention story harder.
• Don't file the same issue twice. If you see the same bug a second time, add a message to the existing case. Multiple cases for one bug make us slower to triage.
• Don't inflate severity on feature requests. It dilutes the signal. Leave severity empty or Low; we read everything.

Status check

Your Support cases page lists all your tenant's cases, filterable by project and status. Each row shows the case's state, its severity hint, and an SLA badge — On track, Stale, or Overdue — so you can see at a glance whether it's moving. Opening a case shows its full thread, attachments, and any investigation missions ARDS spawned for it.

What a workflow is

A workflow is a saved, versioned graph of steps — reads, model calls, coder work, approval gates — that a mission can execute instead of ad-hoc planning. Four rules define how workflows behave in ARDS. Learn them on this page; every other page in this section builds on them.

A workflow executes nothing by itself

A workflow executes nothing by itself. It is a plan, not a process. The only thing that executes in ARDS is a mission: the workflow describes what should happen, and it stays inert until a mission runs it.

A workflow meets a mission in exactly two ways:

• Attach it to a mission. You pick a published workflow (and its version) for a mission — typically in the attach dialog when you create the mission — and the mission runs it.
• Invoke it directly. You start from the workflow itself, and ARDS creates a new mission around it, because a run always needs a mission to live in.

Both roads lead to the same place: one mission, running one workflow, on the mission's own branch. There is no third road where a workflow "just runs" in the background on its own.

Runs propose; you accept

Each execution of a workflow inside a mission is a run. A run does its work on its own branch and is born Proposed. From there you choose what happens: Accept run lands its changes as Accepted; a run you decline ends Rejected — discarded by an agent, or auto-rejected when a competing sibling wins. The run states are summarized in the states cheatsheet.

Accepting a run lands exactly one changement — a single reversible delta — on the mission's branch. Discarding lands nothing, so there is nothing to undo. The full loop, revert included, is walked through in Runs, acceptance & changements.

Nothing is automatic by default

Workflows carry gates: points where the run pauses and waits for a decision in your Decisions queue. No gate auto-approves unless that specific gate was explicitly opted in — auto-resolution is per-gate, tracked, and off by default. It is never a platform-wide switch.

And approval always changes hands: you can't approve your own proposal. Whoever proposed a piece of work — human or agent — cannot be the one who approves it. Gates are covered in Control flow; the wider rules live in Governance.

Acceptance is physical

When you click Accept run, the merge is validated mechanically before anything lands: the system validates the run branch by exercising the merged result — never by an LLM verdict — and it refuses rather than waving anything through when it can't verify. Treat this as a requirement the platform enforces on every accept, not a feat any single run demonstrates: if the mechanical check cannot complete, the accept refuses, and the right move is to start a fresh run. A model saying "looks good" is never acceptance.

What's in the box

• The visual editor — where you draw, wire, validate and publish a graph.
• The node palette — the catalog of step types you can place, organized by category.
• System templates — built-in workflows you clone and make your own.
• The run viewer — where you watch a run, node by node, while it executes.

How to read this section

Pick the path that matches where you are:

• "I want to build my first workflow." Finish the first two headings above, then go: Build your first workflow → The visual editor → Control flow → The workflow lifecycle.
• "A workflow already ran and I want to understand what happened." Go: Runs, acceptance & changements → Watching a run → run outcomes → Gates → Governance.

Build your first workflow

In this tutorial you build a five-node workflow from nothing, publish it, and run it on a mission. It takes about twenty minutes and assumes nothing beyond What a workflow is — the short version: a workflow is a saved graph of steps that executes nothing by itself; a mission runs it, and you accept the result.

What you'll build

A tiny create-read-review-write pipeline, five nodes in a line:

1. A workspace create node opens a run-scoped workspace and hands out its handle — every read and write below needs that handle wired in.
2. A workspace read node loads a file from that workspace.
3. An llm node drafts an improvement to it, in one bounded model turn.
4. A gate pauses the run so you can check the draft.
5. A workspace write node saves the approved text.

The gate is the heart of the exercise. Every path to a write must pass a gate. The validator enforces this rule — a graph where generated content can reach a write without a human checkpoint will not publish.

Create a draft

1. Open the Workflows page and click New Workflow.
2. Name it — my-first-workflow is fine.
3. The editor opens: empty canvas, palette on the side.

A draft is the only editable state, and a draft can't run. Nothing you do here executes anything yet.

Place and wire nodes

1. From the palette's Workspace category, add a workspace-create node. It produces the workspace handle that the read and write nodes require.
2. From the same category, add a file-read node.
3. Add an llm node. In its panel, tell it what to do — for example: "Suggest one concrete improvement to this file, as plain text."
4. From the palette's Structural section, add an Approval Gate — drag the tile onto the canvas, or click it to add. Give it a label ("Review the suggestion") and instructions for the person deciding — that's you, later.
5. Add a file-write node and give it a target path.

Now wire the graph:

6. Connect the execution spine first: each node's out pin to the next node's in pin — create → read → llm → gate → write. The spine is what fixes execution order.
7. Wire the workspace handle: the create node's workspace output to the workspace pin of both the read node and the write node. These pins are required — leave one unwired and the graph will not publish.
8. Connect the data: the read node's result to the llm node's input, and the llm node's result to the write node's content.

Note where the gate sits: between the model and the write, so nothing the model produces is saved without you.

Publish — and read the problem list

Click Publish. In the editor, publishing is the validation step — the Problems panel's own empty state says it: "No problems. Publish to validate." The validator checks the whole graph, and if anything is wrong the publish refuses and the Problems panel reports every problem at once — one exhaustive list, not a fix-one-and-retry loop. Typical first-workflow entries: a required pin left unwired, a write that no gate guards. Work through the list top to bottom, then publish again; it goes through once the list is empty. (Agents can run the same check on demand, without attempting a publish, via the workflow_validate_draft tool.)

When the publish succeeds, the graph freezes: version 1 is now immutable, and every run of version 1 — today or next year — executes exactly what you just drew. To change anything, you edit a new draft and publish version 2. Details in the workflow lifecycle.

Run it on a mission

A workflow executes nothing by itself, so give it a mission:

1. Open the Missions dashboard and create a mission.
2. The creation dialog offers a workflow selector, set to (New empty workflow) by default. Pick my-first-workflow instead.
3. From the mission page, start a run.

The other direction works too: Invoke on the workflow's own page creates a fresh mission around it.

One prerequisite: the run needs a model and provider. If neither the node, a preset, nor your tenant's configured defaults name one, the run refuses to start.

The gate pauses for you

When the run reaches your gate, it stops. No timer pushes it past you, and no gate ever approves itself — auto-resolution exists only as an explicit per-gate opt-in, and you didn't opt this one in.

The pause arrives as a card in your Decisions queue, carrying the label and instructions you wrote, plus the llm's draft, frozen exactly as the run sees it. Read the draft, then click Approve. The run resumes and the write executes — into the run's isolated workspace, not your repository. (Gates can also capture typed answers, offer named decisions, and time out — see gates.)

Accept the run

When the run finishes, it appears on the mission page as Proposed: work done, nothing landed. You have two outcomes:

• Accept run — the merge is validated mechanically before anything lands; if the system can't verify it, acceptance refuses rather than taking anyone's word for it. On success the run becomes one changement on the mission's branch.
• Not accepting it — nothing landed, so there is nothing to undo. There is no decline button: you can simply leave the proposal where it is, and agents can drop it explicitly with the mission_run_discard tool. (The board's other button, Close-out…, belongs to acceptance — it opens the leftover checklist that unlocks Accept run.)

That's the whole loop: the gate guarded the write inside the run, and acceptance guarded your mission. Runs, acceptance & changements covers what acceptance does in depth.

Where next

• The visual editor — everything the canvas, palette and presets can do.
• Control flow: gates, branches & loops — typed gate fields, branching, fan-out over up to 1000 items, waits from 1 minute to 28 days.
• The workflow lifecycle — versions, triggers, cloning and archiving.
• Runs, acceptance & changements — the changement stack, revert, competing runs.

Anatomy of a workflow

A workflow is a graph you can read at a glance: boxes that each do one thing, wires that connect them. This page names the parts — at exactly the depth that changes what you do on the canvas. If you haven't built one yet, start with Build your first workflow and come back.

Execution order comes from the Exec spine. Everything else on this page hangs off that fact.

The graph

Every node is one step: read a file, call a model, pause for your approval, write a result. Each node carries two execution pins, in and out. Chain out to in and you get the Exec spine — the thread a run follows from first node to last. When you wonder "what runs next?", follow the spine, not the layout.

The palette offers 138 node types across 17 categories — see The node palette for the full index. Control constructs — gates, branches, loops, fan-out — are structural tiles with a page of their own: Control flow.

Pins carry typed data

Around the execution pins, nodes carry data pins. Every pin has a kind, and wires only connect compatible kinds — the editor won't let you plug a String into a Bool.

Six kinds are in use:

One convention worth knowing: 125 of the 138 node types expose a result output pin of kind Json carrying the node's outcome. Wire it into the next step when you need it; leaving it unwired is fine.

The three generative primitives

Exactly three generative primitives call a model to produce something new:

• llm — one bounded turn: input in, answer out. It has no tools, so it can only answer — it can't touch your workspace or anything else.
• agent — a multi-turn loop with an explicit toolset and a mandatory budget. Several built-in sys- flows now run on it — the aspect-onboarding flow alone dispatches ten agent nodes. For your own graphs, llm or coder is still the simpler first reach.
• coder — a full coding session in its own container, working in a workspace that exists only for the run.

On the palette these three map to more than three tiles: the coder ships as a synchronous and an asynchronous tile, and domain-flavored model call-sites — mission decomposition, review — are configurations of a site, never new primitives.

The rule that ties them together: primitives propose, verbs commit. A generative node never writes anywhere durable on its own. Writes happen in separate action nodes, and every path to a write passes a gate — nothing a model produces lands without a decision point in front of it.

Outcome arms

Most nodes have a single out pin: they succeed and continue, or they fail. One node is different. The asynchronous coder finishes in one of three ways — Success, Failure, or Refusal — and each way is its own execution pin, an outcome arm: onSuccess, onFailure, onRefusal. You wire each arm to whatever should happen in that case.

One rule changes how you draw: arms never reconverge. The paths downstream of two arms stay separate; the validator rejects wiring that merges them back together.

In practice, wire each arm to an explicit next step — every built-in template that uses the asynchronous coder routes all three.

Two nodes carry outcome arms today — the asynchronous coder and service:mission:integrate; you won't meet arms on other tiles.

Sub-workflows

A workflow can embed another published workflow as a single node — a FlowRef tile. On the canvas it looks like one box. The child workflow decides which inputs and outputs to expose; that small pin surface is its tunnel signature, and you wire it like any other node's pins.

A sub-workflow shares its parent's run and its parent's acceptance. It's composition, not a call: no second run to accept, no second branch to watch.

The sys- tiles in the palette — sys-research-codebase, sys-decompose-propose and friends — are published building blocks designed for exactly this. See System templates.

Params and slots

Two mechanisms keep a graph reusable. Run parameters are declared on the workflow and bound to values when a run starts — same graph, different inputs each run.

A slot is a typed hole you declare where generation is allowed to fill in structure. Generation fills the hole and nothing else: it never rewrites the topology around it, and the structure you already committed stays untouchable.

What publishing freezes

When you Publish a draft, the graph is frozen: a published version is immutable and checksummed, and nobody — ARDS included — can silently change it. At run time, each node also gets a frozen execution snapshot of its own: retrying a step re-runs exactly that snapshot rather than renegotiating it.

The day-to-day consequences are on the lifecycle page; the full mechanics are in the architecture chapter.

The visual editor

The editor is where you draw and change a workflow's graph. Everything here is design-time: you shape the plan, and a mission executes it later — nothing runs from the editor itself.

Only a draft is editable — a published version never changes.

Opening the editor

Open a workflow from the workflow list. What you get depends on what you opened:

• A draft opens fully editable: the palette is on the left, every node and wire can change, and Save Draft and Publish are available in the toolbar.
• A published version opens read-only. You can inspect every node, wire and setting, but no palette is rendered — there is nothing to add or remove. To change a published workflow, you create a new draft, usually by cloning (see the workflow lifecycle).

If you are looking at a graph and cannot find the palette, you are in a read-only view — check which version you opened.

The canvas

The canvas is the graph itself: nodes, wires, and the execution spine running through them.

Two things worth knowing before you start dragging:

• Layout direction. A toggle switches the canvas between LR (left-to-right) and TB (top-to-bottom) layout. It only changes how the graph is drawn — the graph is identical either way. Wide, shallow graphs usually read better in TB; long pipelines in LR.
• Live wiring. Drag from any pin and the canvas answers as you move: pins that can accept the wire light up, pins that can't stay dark. Release on a lit pin to connect; release anywhere else and nothing happens.

Click a node to open its settings panel; drag it to reposition it.

The palette

The palette lists everything you can place — 138 node types across 17 categories, plus a structural section.

• Categories group nodes by domain (Missions, Workspace, Git, Review…). Each category collapses and expands, so you keep open only the ones you use.
• Favorites / Recent lets you pin the nodes you reach for constantly to the top of the palette.
• Structural is the control-flow section. Its tiles are not catalog nodes but the shapes that organize them: Trigger, Approval Gate, Workflow Reference, Branch / Switch, For Each, Map / Fan-out, Wait (timer) and Wait (event) — plus Comment, a titled annotation frame you place behind nodes to describe a region of the graph; it is purely descriptive and never runs.
• Workflows lists published workflows as tiles — drop one onto the canvas to embed it as a sub-workflow reference.
• Shortcuts holds composite emitters, like the Research shortcut that drops a preconfigured research step (an LLM service step, or a coder configured to analyze).

To place anything, drag its tile onto the canvas — or just click the tile and it is added, ready for you to position.

The full catalog, category by category, is in the node palette. What each structural tile does is in control flow.

Wiring and pin compatibility

Every node exposes pins. The in/out pair is the execution spine — it decides order. The other pins carry typed data between nodes: Exec, Context, String, Bool, Json, Artifact. Most nodes deliver their output on a Json pin named result.

The editor enforces types while you wire: a String output only connects to inputs that accept a String, and the highlight during a drag shows you exactly which pins those are. You cannot create an ill-typed wire, so a graph that wires up is a graph whose data at least fits together.

What each pin kind means, and how the spine relates to data flow, is covered in anatomy of a workflow.

Presets on a draft

Generative nodes carry a preset selector: pick a preset and the node is bound to that model/provider bundle.

What you choose on the canvas is the authored default, not the last word. At dispatch, preset bindings set at any scope (global, project or customer) are resolved and the most specific one wins — it beats what you authored here. If nothing is bound anywhere, the run falls back to the baked-in default rather than failing. Details in presets.

Setting node instructions

A node's task text lives in its Instructions field: select the node and write it in the settings panel. It is part of the graph — publishing freezes it with everything else.

Coder and agent nodes can additionally carry an instruction binding — override text that replaces the authored instructions at dispatch, without touching the published graph. Bindings, their scopes and precedence (run > project > tenant > global) are covered in node instructions.

Publish is the validation step

There is no separate Validate button. In the editor, clicking Publish runs the whole validation — the Problems panel's own empty state says it: "No problems. Publish to validate." If anything is wrong, the publish refuses and the panel reports everything it finds at once — one exhaustive problem list, not a stop at the first error. Work down the list, fix, and publish again; it goes through once the list is empty. (Agents can run the same checks as a dry run, without attempting a publish, via the workflow_validate_draft MCP tool.)

A successful Publish freezes the draft into an immutable published version — from that point the graph never changes (see the workflow lifecycle).

If your draft is governed — it writes somewhere that requires controls — publishing from the editor injects the required control nodes as part of the publish itself: they land in the published graph marked as injected (runs badge their origin), rather than appearing on your canvas first. To review injected controls before publishing, use the agent path: the workflow_materialize MCP tool writes them into the draft, where you read them like any node you placed yourself. What makes a draft governed, and which controls arrive, is in governance.

Control flow: gates, branches & loops

Nodes do the work; control flow decides which nodes run, when, and under whose approval. The tiles you insert live in the palette's Structural section — drag a tile onto the canvas, or click it to add (the editor). The tiles: Trigger, Approval Gate, Workflow Reference, Branch / Switch, For Each, Map / Fan-out, the two wait tiles — Wait (timer) and Wait (event) — and Comment, a titled annotation frame that describes a region of the graph and never runs. This page covers the decision and repetition constructs; Workflow Reference — embedding another workflow — is covered in Anatomy, and Trigger belongs with triggers in the lifecycle.

One rule shapes everything else here: every path to a write passes a gate. The validator enforces it — you cannot publish a graph where a node that writes is reachable without a human decision standing in front of it.

Gates

A gate pauses the run and asks you to decide. You give each gate a label and instructions — the text the decider reads when the gate fires. While it waits, the gate sits in your Decisions queue (Decisions).

A gate can capture data, not just approval. Add typed fields — String, Number, Bool, Json, or Enum — and the values the decider fills in leave the gate on its response pin, available to every node downstream.

For routing decisions, give the gate named decisions: each becomes a human-labelled outgoing arm ("Ship it" / "Needs rework"), and the run continues down whichever arm the decider picks.

A gate can carry a timeout. If nobody decides in time, the gate does what you chose when authoring: fail the step, or skip it and move on. No gate ever approves itself — auto-resolution is a per-gate opt-in you configure deliberately, never a default (governance).

Branch

Branch — the Branch / Switch tile — routes on data instead of on a human. You write an ordered list of cases; at run time the first case that matches wins, and the run continues down that case's arm. A case matches in one of two ways: give it a match value to compare against the wired selector, or give it an Expression — a boolean rule — and that case becomes a Switch arm, routing by rule instead of by value. Every Branch has exactly one else arm for when nothing matches. Once arms diverge they stay apart — see the validator rules below.

Loop

Loop repeats a step until its result is accepted, up to a maximum of 10 attempts. It is a legacy construct: retired for new authoring, so you won't find a Loop tile in the Structural section. Published workflows that contain one still run, unchanged. For anything you author today, reach for ForEach below.

Fan-out in parallel (MapFanOut)

MapFanOut — the Map / Fan-out tile — runs the same body once per item of a list, in parallel. You point it at a source pin — the upstream output holding the list — name the item variable the body reads, and it fans out up to 1000 items.

The body is deliberately small: a single catalog step, or a sub-workflow when one step isn't enough (Anatomy covers sub-workflows). The natural shape is three nodes: a prepare step that loads the list, the per-item body, and a reduce step that aggregates the results. Items normally run independently; if some items must wait for others, declare sibling dependencies and the fan-out runs as a small dependency graph instead of a free-for-all.

Fan-out one at a time (ForEach)

ForEach — the For Each tile — walks the same list one item at a time, in order, and supports breaking out early when a condition is met.

Its body comes in two shapes, mutually exclusive:

• Inline body — one catalog step (or a sub-workflow) run once per element, with an optional break condition checked between items.
• Loop Body region — wire the tile's Loop Body to a small multi-step sub-graph of plain catalog steps, with one Branch driving the live Break pin when you need to stop early. That buys you a real multi-step body without splitting off a sub-workflow; nesting further structural tiles inside the region is still rejected.

Which one do you want? MapFanOut when items are independent and you want throughput. ForEach when order matters, when each item should see the effects of the previous one, or when you want to stop as soon as one item succeeds.

Wait

Two tiles, two behaviors:

• Wait (timer) pauses the run for a fixed duration — from 1 minute up to 28 days.
• Wait (event) pauses the run until something happens elsewhere in the platform. Six event types are live: mission.created, conversation.completed, support-case.created, incident.created, batch.completed, mr.merged.

Finally

Finally is for cleanup — releasing a lease, closing out a workspace, posting a summary. Whatever it wraps, the cleanup runs exactly once, whether the surrounding flow succeeds, fails, or is cancelled. Use it when a step acquires something that must not leak.

One caveat: Finally has no palette tile. Today it is authored in the graph payload itself — the agent/MCP authoring path — not placed from the editor.

Rules the validator enforces

When you Publish a draft — or dry-run the same checks with the workflow_validate_draft tool — everything is checked at once and every problem is reported together (lifecycle). For control flow, three rules matter most:

• Arms stay isolated. Branch cases, a gate's named decisions, and outcome arms (Anatomy) never reconverge downstream. An arm that leads nowhere is a valid dead end, not an error.
• Fan-out bodies stay flat. A MapFanOut body is one catalog step or one sub-workflow; a ForEach body is that — or a wired Loop Body region of plain steps. Either way, you cannot nest further structural control inside the body itself. Need more? Put it in a sub-workflow.
• Gate dominance. Every dependency path to a node that writes must pass through a gate. If any route around a gate reaches a write, the publish is refused and the problem list names it.

The node palette

The palette is the panel in the visual editor you drag from — or click — to add steps to a draft. It carries 138 node types in 17 categories. This page is the index: one honest line per node, so you can find the right one without placing it first. Exact inputs and outputs are deliberately not here — pin-level signatures belong to the agent reference.

Primitives propose, verbs commit: brain nodes never write by themselves, state-changing service nodes are gate-guarded on every path, and the run's repository delta merges only when you accept the run.

Four conventions cover almost everything, so we state them once:

• Every node sits on the Exec spine. Execution wires order the steps; data wires carry the values. See Anatomy of a workflow.
• Almost every node emits one JSON result. 125 of the 138 end in a single result output that downstream nodes consume.
• A few hand you a typed handle as well — a run id, an incident id, a lease id, or a workspace — which you wire straight into the nodes that need it.
• Families come in threes for fan-out. Many service families ship a prepare (or load) node, a per-item node built to sit inside a fan-out body, and a reduce node that folds the items back together (analyze, aggregate, finalize, score or submit-report). Rows marked (per-item) below are the middle piece.

One thing you will not find in this catalog: the flow-control constructs. The palette's Structural section carries the tiles — Trigger, Approval Gate, Branch / Switch, For Each, Map / Fan-out, Wait (timer), Wait (event), Workflow Reference and the Comment frame — and Finally, which has no tile and is authored through the graph payload. They all have their own page.

The brain nodes

Six of the 138 are generative — they call a model. Four are wired call-sites with a fixed job:

• Missions:Decomposition turns a mission objective into a proposed task breakdown.
• Coder:Default dispatches one coder task and waits for the resulting artifact.
• Coder:AsyncDefault dispatches coder work and routes what happens next down outcome arms — onSuccess, onFailure or onRefusal. It is one of the palette's two multi-arm nodes — the other is service:mission:integrate, under Git; see Outcome arms.
• ReviewEngine:Default reviews an artifact and produces findings.

Two are generic:

• llm runs one bounded model turn over its input. It has no tools, by construction.
• agent runs a multi-turn agent loop with an explicit toolset and a mandatory budget. Several built-in sys- flows now use it — one dispatches ten agent nodes. For your own graphs, llm or a coder is still the simpler first reach unless you know why you need it.

The discipline is the same for all six: primitives propose, verbs commit. A brain node never writes anywhere by itself. Its output reaches the world only through explicit service nodes downstream — and on every such path, a gate stands before the write.

Reads, actions and service nodes

The other 132 nodes are adapters, in three kinds:

• Reads — 20 nodes. They fetch state and change nothing: a mission's details, a file from a branch, a project's onboarding progress. Safe to place anywhere.
• Workspace actions — 2 nodes. workspace:write_file and workspace:create do write — but only inside a sandboxed workspace. They never touch your repository.
• Service operations — 110 nodes. One platform operation each: create an incident, classify a support case, run a compliance check, push a branch. The ones that change platform state are exactly what the gate-dominance rule guards.

You can usually read the kind off the id: read: fetches, service: operates, and the workspace file verbs live under workspace:.

Category index

Sixteen categories here, ordered by how often a tester reaches for them — the seventeenth, Legacy, closes the page. Expand a block to see its nodes.

Legacy

System templates

ARDS ships with two catalogs of built-in workflows, and they play different roles. A gallery template is an example you clone and own; a sys- building block is a published workflow you embed. Everything else on this page hangs off that distinction.

Two kinds of built-ins

The template gallery holds 22 read-only templates. Each one shows, in workflow form, how a real platform flow is shaped — decomposition, review sweeps, incident handling. You can't run a template directly and you can't edit it in place: you Clone it, which gives you an editable Draft you own. From there it's an ordinary workflow — yours to rename, rewire and publish.

One thing templates are not: live wiring into the platform. Cloning Mission lifecycle and running your clone runs your graph — it does not execute or replace the platform's internal mission pipeline. Templates teach shape; they don't carry the machinery.

The sys- building blocks are different: 19 published workflows seeded into every tenant. You don't clone these to use them — you embed one by dropping its tile into your own graph as a sub-workflow reference. The embedded block runs inside your run, pauses at its own gates, and lands through your acceptance; it is composition, not a separate execution (see Anatomy of a workflow).

A few names appear in both catalogs — sys-run-acceptance is both a gallery template and a seeded block. Where you meet it tells you which one you're holding: the gallery clones, the palette embeds.

The template gallery

The 22 templates group under 9 categories. Clone any of them and read the graph node by node in the editor — that's what they're for.

Mission (6)

Onboarding (4)

Ops (3)

Compliance (2)

Review (2)

Validation (2)

Evaluation (1)

Improvement (1)

Support (1)

Cloning a template

1. Open the template gallery from the workflow list.
2. Pick a template and click Clone. You get a Draft you own — the template itself is untouched.
3. Rename the draft so it reads as yours, not as a system flow.
4. Open it in the visual editor and make it yours: swap nodes, change gate instructions, rewire arms.
5. Validate, then Publish. Publishing freezes the graph exactly as it does for a workflow you built from scratch — see the workflow lifecycle.

A clone is a copy, not a subscription: if the gallery template changes in a later release, your clone doesn't move. You can also clone in the other direction — from a mission that already ran — which is covered in The workflow lifecycle.

The sys- building blocks

The 19 seeded sys- workflows are published and versioned like any workflow of your own; they show up as ready-made tiles you can drop into a draft. Embedding one means your workflow calls it as a sub-workflow: it contributes its steps to your run, and its output lands through your acceptance like everything else in the graph.

Two you're likely to reach for:

• sys-research-codebase — a read-only codebase investigation; a good grounding step before anything generative.
• sys-decompose-propose — the agentic task-plan proposal; embed it when your workflow should propose an ordered task plan the way the platform does.

Most of the 19 exist to serve the platform's own seeded flows. You're free to embed any of them, but you never need one — a workflow built entirely from palette nodes is just as legitimate.

The workflow lifecycle

A workflow is a versioned thing: one stable identity that owns a series of numbered versions, each moving through the same three states. A published version never changes — evolution always means a new version. Everything else on this page follows from that rule.

Three states, two transitions

The only legal transitions are Draft → Published and Published → Archived. There is no way back: you can't unpublish, and you can't unarchive.

Delete exists only for drafts, and it is permanent. A published version can never be deleted — if you want it out of the way, you archive it.

Versions

Version numbers count up — 1, 2, 3 — and are never reused or rewound. To change a published workflow, you start a new draft; publishing it creates the next version.

Several published versions of the same workflow can coexist, and each one stays runnable. Running one is always an explicit version choice: nothing silently substitutes "the latest" for the version you asked for. (Triggers are the one place a latest-version policy exists, and even there it is a choice you state explicitly — see below.)

Validation happens at publish

There is no separate Validate step in the editor: clicking Publish runs the checks, and if anything is wrong it refuses and reports every problem at once — wiring mistakes, missing required pins, writes with no gate in front of them — in a single list, so you fix in one pass instead of resubmitting to discover the next complaint. The list is exhaustive: once it is empty, the publish goes through. The problems list lives in the editor. Agents can run the same checks as a true dry run — without attempting a publish, freezing nothing — via the workflow_validate_draft tool.

Publish freezes the graph

Publish validates one last time, then freezes the draft. From that moment the graph is immutable and sealed with a checksum; every run records exactly which frozen graph it executed, so what you reviewed is provably what ran.

One thing lives outside the freeze: the display name. Renaming with Rename touches all versions of the workflow and never alters a graph — a rename is always safe, even on published versions.

For the full mechanics of the freeze, see the architecture chapter on workflows.

Ways a workflow starts

A workflow executes nothing by itself; every start becomes a mission. Three doors:

• Attach at mission creation. You create a mission and pick a workflow as its plan. Runs then happen on that mission — see Runs, acceptance & changements.
• Invoke. You run the workflow directly with Invoke; ARDS creates a new mission for it. Same loop from there.
• Triggers. A schedule, a webhook, or a platform event starts the workflow automatically. You configure them from the workflow list: Manage triggers opens the dialog where you pick Schedule, Webhook or Event and name the mandatory provider and model. Each trigger binds either a pinned version or the latest published one — you state which when you create the trigger — and names its model and provider up front (there is no silent fallback). A trigger never bypasses a gate: an automatic start pauses at every approval a manual start would.

Clone

Cloning always lands a new draft you own — never a published version.

• From a template. System templates clone into an editable draft; edit and publish it like any other.
• From a mission. "Save this run as a workflow." If the mission was itself born from a workflow, the source graph is re-drafted verbatim. If it was an organic, planner-decomposed mission, ARDS reconstructs a graph from what actually ran — and attaches a notes list of every repair it made along the way, so you can judge the reconstruction before trusting it.

Changing a sub-workflow reference

A workflow can embed another workflow by reference (see Anatomy of a workflow). You can rebind that reference — point it at a different workflow, or a different version — but rebinding invalidates any gate ratification given against the old target. Nothing carries over silently: the rebound draft passes through your approval again before it can publish.

Archive

Archive retires a published version for good. It stops being runnable, but it is kept forever: past runs still point at it, and provenance never evaporates.

One guard: you cannot archive a version while a published parent workflow still references it as a sub-workflow. Rebind or archive the parent first. And since archiving is terminal, the way "back" is always forward — publish a new version.

Runs, acceptance & changements

A workflow never lands anything on its own. Work happens inside a run, and a run only ever produces a proposal. A run proposes; only your acceptance lands anything.

The loop at a glance

You attach a workflow to a mission — or invoke one, which creates its mission for you. You start a run; the run executes the graph on its own branch, away from the mission's work so far. When it finishes, it sits in Proposed with its changes ready for you. You inspect the result and decide: Accept run lands the work on the mission as one changement; a proposal you don't accept lands nothing, and the mission stays exactly as it was (declining is not a button).

Start a run

Runs start from the mission page. The Runs & acceptance board lists every run this mission has had, past and present — the live tag in its header means it refreshes as the mission moves — and each new run starts from the mission's current state.

Each run row shows its outcome and, when they apply, two small badges: dormant — the run has no provisioned target yet, nothing has run against it — and stale — the run's base is behind the mission tip, so an accept would refuse until you start a fresh run.

A run can refuse to start. The reasons you will actually meet:

• A run is already open. One run at a time per mission — wait for it, or accept or discard it first.
• The mission isn't planned yet. Its plan isn't in place; let it get there first.
• The mission is finished. A completed or cancelled mission takes no new runs.

Anything more exotic is an agent-level refusal; the full list lives on the agent pages.

While it runs

While a run executes, its gates pause into your Decisions queue: the run holds at the gate until you respond (or, if the gate was authored with a timeout, until it expires), then resumes. Everything else about a live run — the graph view, per-node status, the coder session panel — is in the run viewer; see Watching a run.

A run proposes changes

A run is born Proposed and stays there until you decide.

The full cheatsheet is under run outcomes.

Accept

Accept run does three things, in order — and refuses rather than half-doing any of them:

1. Stale check. The run started from a specific mission state. If the mission has moved since, the accept refuses.
2. Physical validation. The merged result must be verified mechanically before it lands. This is fail-closed: if the system cannot mechanically verify the merge, it refuses — it never lands work on anyone's word, including its own.
3. Merge. The changes land on the mission branch, and a changement is created to record them as one reversible unit.

On the board, a proposed run carries two buttons: Accept run — it reads Accepting… while it works — and Close-out…, which opens the run's close-out checklist. Anything the run left open — a leftover task, an open gate, a failed node — needs a dated dispose note there before the accept unlocks; a clean run answers "No leftovers — every node landed terminal and clean."

Why an accept may refuse:

• Things moved underneath. The mission advanced since the run started. Start a fresh run.
• Merge conflict. The run's changes no longer apply cleanly. Start a fresh run from the current state.
• Another run already won. If runs were competing (below), only one gets accepted.

A refused accept lands nothing and breaks nothing — the mission is untouched.

Declining a proposal

There is no discard button on the run board: a proposed run is either accepted or left where it is. Leaving it is safe — nothing happened to the mission, so there is nothing to undo — but the mission won't take a new run while a proposal is still open.

An unwanted proposal clears in one of two ways. Accepting one proposal auto-rejects the other proposed runs in its competing group, and their branches are deleted — that answers "what happens to the others?" for competing runs. And agents can drop a run explicitly with the MCP verb mission_run_discard (agent reference): the run is marked rejected and its branch deleted. Either way it is the cheap way to say "not this one" — nothing ever landed.

The changement stack

On the board this is the Accepted changements stack — empty, it reads "Nothing accepted onto the tip yet." Each accepted run becomes exactly one changement, and changements stack in order on the mission's branch. The mission's merge request is that composed stack — not a pile of raw commits, but a sequence of accepted, validated deltas. Because every accept is validated before it merges, the tip of the mission is always a state that passed validation.

Revert

Any changement can be reverted — its Revert… button shows a preview before anything is undone. The preview shows the cascade: later changements that touch the same files depend on the one you're reverting, and they revert with it, in reverse order. If a revert would conflict, ARDS refuses rather than guessing at a resolution. And nothing evaporates: the reverted changement and the revert itself both stay in the mission's history, dated and attributed.

Competing runs

Advanced, but worth knowing exists: you can start several runs from the same starting point — different workflows, different parameters, different instructions — as one competing group. Inspect them side by side and accept the one you prefer; the losers are rejected and their branches deleted. It is A/B testing where the judge is you, on real, validated results.

Governance: presets, instructions & the publish floor

Workflows describe work; governance decides who signs off on it, which model performs it, and what a graph must contain before it may be published. This page covers the four levers you'll actually touch: gates as decisions, presets, node instructions, and the publish floor.

Nothing approves itself: no gate auto-resolves unless you explicitly opted that specific gate in — and the separation-of-duties floor never can be.

Gates are decisions

Every gate a running workflow reaches becomes a card in your Decisions queue. The run pauses; the card carries the gate's label, its instructions, and any typed fields the author asked you to fill. You resolve it with one of three verbs:

• Approve — the gated step resumes once every step before it has completed.
• Skip — cancels the gated step; the run continues without it.
• Fail — fails the step, and the workflow's failure routing takes over.

Or do nothing: an unresolved gate just waits. Nothing moves until someone decides.

One rule sits above all three: you never approve your own proposal. The identity that resolves a gate must be different from the one that proposed the work, and a gate raised by an agent always requires a human. If ARDS cannot attribute the resolver, it refuses the resolution rather than guessing.

Never automatic by default

No gate auto-approves out of the box. Auto-resolution is a per-gate opt-in: you grant it explicitly, for that one gate, and every automatic resolution is logged. The grant is also tied to the exact content it was given for — if what the gate guards changes, the gate comes back and asks a human again.

Even with opt-ins, one floor never moves: the separation-of-duties gate that stands between a mission's accepted work and your project can never be made automatic — not by configuration, not by waiver. Runs are accepted by you; the promotion past that point is decided by you too.

Presets

A preset is a named bundle of model and provider choices (plus the tool transport that goes with them) used by a workflow's generative nodes. Rather than hard-coding a model on every node, you bind a preset and manage the choice in one place.

Presets carry a scope — global, project, or customer — and the most specific one wins: a project-level binding beats a customer-wide one, which beats a global one.

Two facts matter in practice:

• Presets resolve at dispatch, not at publish — when a run starts, the preset bound at that moment wins, even over what was authored on the canvas. Publishing froze the graph, not the model choice.
• Resolution walks a chain — a preset bound at dispatch wins; otherwise the node's authored (pinned) preset applies; otherwise the site-wide default preset fills in. If nothing names a model anywhere, the run refuses to start rather than guessing.

You bind a preset on a draft with the selector in the editor. Fleet profiles are a different lever entirely — container sizing and concurrency, not model choice; see Fleet tuning.

Node instructions

A workflow's coder and agent nodes can carry node instructions — an instruction binding that replaces the node's authored instructions at the next dispatch (for a coder, inputs and the outcome contract are recomposed unchanged; for an agent, the binding replaces its task text), without touching the published graph or its checksum. Exactly one binding applies — the most specific: run beats project, which beats tenant, which beats global.

Today you set node instructions by hand, from the editor or per run when you start one. ARDS proposing a better prompt on its own is not in v1; if that lands, the proposal will arrive as a decision you approve or reject — nothing will ever apply itself.

The publish floor

A workflow counts as governed when your organisation's control catalogue applies to it — in practice, as soon as its graph writes anywhere that matters. For a governed graph, two things happen before publish:

• Every write needs a stage — one of Design, Implementation, Integration, Verification, PreDeployment. The stage tells the floor which controls that write requires.
• The required controls are injected as part of publish — the gates and reviews the catalogue demands land in the published graph as real nodes, visually marked as injected. Publishing from the editor injects them during the publish itself; to review them on the draft before publishing, agents run the workflow_materialize tool, which writes them into the draft exactly like nodes you placed yourself. Publish is refused until the graph is complete.

The check is deterministic: the same graph plus the same control catalogue always yields the same controls — the LLM never synthesizes compliance. And the floor only ever adds: governance can raise the bar above what you authored, never quietly lower it. Publishing itself is covered in the workflow lifecycle.

Waivers

When a required control genuinely doesn't apply, you don't delete it — injected controls are non-negotiable on the canvas. The escape hatch is a waiver: explicit, tied to one control, carrying a written reason, and permanently logged. A waived control stays visible as waived, not absent.

Some controls cannot be waived at all. The 25-year retention rule is one: no reason, however good, removes it.

Watching a run

A run is a proposal, and you should never have to accept a proposal you can't inspect. The run viewer shows you what a run actually did — every node, every prompt, every file it touched — while it executes and after it finishes. When the run viewer doesn't know a value, it shows nothing rather than guessing. An empty field means "not recorded", never "invented".

The run viewer

Every run belongs to a mission. Open the mission, find the run on its runs board, and click it — the run viewer opens on the same graph you published, now painted with execution state. At a glance you see which nodes completed, which failed, and which one is holding the run at a gate.

The run's URL is shareable — anyone you send it to lands on the same run. And wherever a node is referenced elsewhere in the UI, that reference deep-links into the viewer with the node's sheet already open. That deep link is the fastest way to say "look at this step" in a bug report.

The viewer covers a run in any state — still executing, parked at a gate, or finished and waiting as Proposed. What happens next — accepting the proposal, or leaving it — is covered in Runs, acceptance & changements.

The node sheet

Click a node and its sheet opens: status, failure reason if it failed, start time and duration, how many attempts it took, and the tokens it consumed. If one of those values wasn't recorded, the row is simply absent — the sheet never fills a gap with a plausible number.

The sheet also links outward. A node that dispatched a coder links to the coder task. A node that raised a gate links to that decision. A multi-arm node — the async coder or service:mission:integrate — shows which arm the run actually took (outcome arms).

Finally, the sheet flags nodes that didn't come from the author's hand — generated, injected or amended; a node you authored carries no origin badge at all. Provenance matters when you're deciding how much to trust a step — a control you placed yourself reads differently from one governance added.

Gate sheets

When a run pauses at a gate, the gate lands in your Decisions queue, and its sheet shows the exact variable snapshot the run held when it raised the gate. That snapshot is frozen: what you approve is what you saw, not whatever the values become later.

A gate can carry typed capture fields (String, Number, Bool, Json, Enum) and named decisions — the same shapes described in Gates. Fill them on the sheet; your answers flow back into the run.

Injected controls are visually distinguished from authored gates. If the pause you're looking at was required by the publish floor rather than placed by the workflow's author, the sheet says so — see Governance for why those controls exist and why they can't be negotiated away at run time.

The coder session panel

When a node dispatched a coder, its sheet includes a Coder Session panel — the full record of what that coder was told and what it did:

• The effective prompt, exactly as dispatched. Expandable to the full text. This is what the coder actually received — not a summary, not a reconstruction.
• Files touched. Every file the session changed, listed.
• Diff on demand. Click Load changes to render the full diff — file count, additions and deletions, real hunks.
• Downloads. Any file individually, or everything as one zip.

This panel is how you audit a coder without leaving the run. For what coders are and how they work, see Coders.

From run to mission and back

The run viewer is one hop from everything it touches. The breadcrumb takes you back to the mission, where the runs board shows this run next to its siblings. The node sheet takes you to the coder task or to the raised decision. And references to the run elsewhere in the UI — on a decision card, on the mission page — link straight back here.

When you've seen enough, the decision happens on the mission page, not in the viewer: Accept the run — or decline it. The viewer's job ends where yours begins — it shows; you decide.

Agent reference: workflow & run tools

This page is the lookup surface for the 33 MCP tools that author, run, and accept workflows: 23 workflow_* tools, 3 workflow_node_instructions_* tools, and 7 mission-run/changement tools, in eight groups. For step-by-step procedures, use the cookbook; when a call refuses, the refusals page maps every token to a recovery.

Who this is for

You are an MCP-connected agent — or the operator driving one. Every tool on this page returns the same envelope: { success, data } on success, { success: false, error, code } on refusal. All of these tools require tenant-admin rights; if a call fails authorization, that is a permissions problem, not a workflow problem.

This page tells you what each tool does and what it returns. For how the machinery works underneath — compilation, branches, seals — read the workflow architecture chapter.

The two legal entry surfaces

A published workflow executes through exactly two surfaces: workflow_invoke and mission_run_start — everything else on this page authors, inspects, or accepts.

• workflow_invoke — workflow-first. Compiles a published version into a fresh mission it creates for you. Use it when the work has no mission yet.
• mission_run_start — a run on an existing mission. The run gets its own branch off the mission tip and enters the acceptance loop: born Proposed, then you accept or discard it. Use it when the work belongs to a mission you already have.

The human-side walkthrough of that loop is Runs, acceptance & changements.

Authoring & lifecycle (9 tools)

These take a graph from empty draft to frozen published version. Drafts are the only editable state; publishing freezes the graph — see The workflow lifecycle.

Composition (3 tools)

Workflows compose by reference: a FlowRef node embeds another published workflow as a sub-workflow.

Discovery & observation (6 tools)

Execution (1 tool)

workflow_invoke — run a published version, workflow-first.

• Inputs: workflowId, version (must be ≥ 1 — running "whatever is latest" is never implicit), optional objective, model, provider, paramsJson, projectId, presetId (+ forceOnAllCallSites), agentBudgetJson (+ forceBudgetOnAllAgentSites).
• Parameters bind at compile time. The values in paramsJson are bound when the graph is compiled into the new mission's plan; nothing rebinds mid-run.
• Model resolution is explicit. model and provider are required unless tenant defaults resolve them — there is no silent model fallback.
• Presets are the preferred lever. presetId runs this invocation with a named preset instead of a raw model; an unknown preset refuses with NOT_FOUND rather than falling back. By default it replaces only the workflow-level default preset — a step that pinned its own preset at edit time keeps it — unless you also pass forceOnAllCallSites.
• Per-run agent budgets. agentBudgetJson adjusts agent budgets for this run only, applied axis by axis. By default a stated axis stands in for the engine default only — it fills the axes a step's authored budget leaves unstated, and a step that authored that axis keeps its own value — unless you also pass forceBudgetOnAllAgentSites, which pushes the stated axes onto every agent site, outranking what the step authored. A malformed override refuses with VALIDATION_ERROR before any mission is created.
• Project targeting is explicit and fail-loud. projectId (id or slug) aims the run's writes at a project: an unknown target refuses with NOT_FOUND and a non-Active project with CONFLICT, both before any mission is created. Omit it and the run lands in the tenant's default project — recorded as such in the mission's provenance.
• Returns the new missionId with step, gate, and control counts. Every gate is born paused behind a pending decision.
• Follow-ups: mission_get to watch the mission, decision_list to find pending gates, workflow_run_nodes for per-node status.

Cloning (2 tools)

System templates (2 tools)

Templates are representational: cloning gives you a graph to own and edit, not a wire into the platform's internal flows. The full enumeration of the 22 lives on System templates.

Node instructions (3 tools)

Coder and agent nodes can carry an instruction binding — override text that replaces the node's authored instructions at the next dispatch, without touching the published graph or its checksum. Exactly one binding applies — the most specific wins: run > project > tenant > global.

Only manually-set slots are writable through these tools; a slot owned by the platform's prompt-engineering machinery refuses with CONFLICT. ARDS proposing prompt improvements on its own is not in v1; if that lands, proposals will arrive as decisions you approve — nothing will ever apply itself. See Governance for the human-side view.

Mission runs & changements (7 tools)

The acceptance loop on an existing mission. Strict-sequential by default: one undecided run at a time, each accepted run landing as one changement on the mission branch. Pass the same groupId to several starts to open a competition instead — one winner, siblings rejected.

The human-side walkthrough — accept, discard, revert, competition — is Runs, acceptance & changements.

Mission context

Four neighbouring tools you will meet in every workflow session; the full mission surface is documented in Missions & tasks.

mission_propose drafts a mission and routes it for approval instead of creating it outright — the proposal arrives as a decision a human accepts or rejects. You never approve your own proposal.

mission_create creates a mission directly. Attach a workflow at creation, or start runs on it later with mission_run_start.

mission_decompose asks the planner to break a conversation-born mission into tasks. Missions that carry a workflow skip this: the graph already is the plan.

decision_respond is the single gate-resolution verb. Its resolutions map onto a paused gate as: approve releases the gate once prior steps complete; skip cancels the gated step; fail fails it. Leaving the decision unresolved keeps the run paused. Pending gates are listed by decision_list and appear in the Decisions queue.

Status vocabularies

Normative token tables. Tokens are returned verbatim; match on them exactly. Per-token recovery detail lives in Refusals & failure modes.

Run-start statuses

Returned by mission_run_start. One success token, ten refusals.

Run-accept statuses

Returned by mission_run_accept. One success token, six refusals.

Run outcomes

The lifecycle of a run itself — the same tokens as the states cheatsheet.

Version statuses

The only legal transitions are Draft → Published → Archived.

Node run states

Per-node statuses as reported by workflow_run_nodes and the mission_run_get roll-up.

Agent cookbook: canonical sequences

This page is for an MCP-connected agent (or the operator driving one) that already knows the individual tools and wants the proven order to call them in. Every call returns the { success, data } envelope described in the agent reference; sequences 1 and 2 below are the two legal entry surfaces. Each sequence states its preconditions, the numbered calls with their key parameters, what you should see, and where to look when a call refuses.

No sequence in this cookbook lands anything by itself: every path ends at a gate or an accept, and a proposer never approves its own proposal.

Author, publish, invoke

The full authoring loop: from an empty draft to a fresh mission running your graph.

Preconditions — tenant-admin MCP access; a model and provider you are allowed to bind (there is no silent fallback at invoke).

Steps

1. workflow_catalog — read the palette first: 138 node types in 17 categories, each with its pins. Wire only pin-compatible connections; node types with lifecycle Legacy are publish-blocked in new drafts.
2. workflow_create_draft — pass your graph payload as graphJson (a minimal skeleton is fine); you get back an id and a workflowId in state Draft, the only editable state. There is no name parameter here — set the display name separately with workflow_rename.
3. workflow_update_draft — send nodes and wires; repeat as often as needed while the version is still a draft.
4. Governed graphs only: workflow_materialize injects the required control nodes into your draft — deterministically, before publish — so review them like any node you authored. Use workflow_waive_control with a written reason for a control that can be waived; some controls are non-waivable. See Governance.
5. workflow_validate_draft — a dry run of the same validator publish uses. It aggregates every problem in one response: fix them all, then validate again — do not fix one and retry.
6. workflow_publish — freezes the graph into an immutable, checksummed (SHA-256) version. A later rename stays outside the checksum. See what publishing freezes.
7. workflow_invoke — pass an explicit version (≥ 1: a published version, never a draft), your run parameters (bound at compile time), and model + provider (required unless tenant defaults resolve them) — or bind a named preset with presetId instead, the lever this estate prefers over a raw model (agent reference). Invoke creates a fresh mission around the run.
8. Watch it: mission_get for mission state, workflow_run_nodes for per-node progress, decision_list for gates waiting on a decision.

Expected outputs — a workflowId; a published version number; a new mission id from the invoke; gates arriving as decisions while it runs.

If it refuses — validation problems (gate dominance, arm reconvergence, a Legacy node, …) all arrive at once under VALIDATION_ERROR; edits to a non-draft return CONFLICT; invoke refuses when the workflow is not invocable. Causes and recoveries: Refusals & failure modes.

Run on an existing mission

The acceptance loop: start a run on a mission that already exists, resolve its gates, then accept or discard what it proposes.

Preconditions — an existing mission that is planned and not terminal; a published workflowId and version; no run already open on the mission — unless you are deliberately competing with a shared groupId.

Steps

1. mission_run_start — missionId, workflowId, version, parameters; groupId optional. Omit groupId for strict-sequential behavior. Only Started means a run exists — handle all 11 start statuses.
2. Poll mission_run_get until the run reaches Proposed. While it runs, gates park as decisions: list them with decision_list, resolve them with decision_respond — approve resumes the step, skip cancels it, fail fails it. You never approve a proposal you raised yourself.
3. Decide. mission_run_accept: on Accepted, exactly one changement lands on the mission branch, and mission_run_get now carries the seal anchors and isAnchored. Acceptance is physical and fail-closed: if no validation backend is reachable in your environment, the accept returns ValidationRefused and nothing merges — the run stays Proposed. On StaleRefused the tip moved underneath you: start a fresh run off the new tip; never retry in a loop. Or mission_run_discard: nothing landed, nothing to undo. All 7 tokens: accept statuses.
4. mission_changement_stack — the ordered stack of everything accepted so far; the mission's MR is this composed stack. See changements.
5. To undo an accepted run: mission_revert_preview first — it shows the transitive dependent cascade — then mission_revert, which reverts in reverse ordinal order and fails closed on conflict: the cascade aborts cleanly and names the failing member; nothing partial lands.

Competition variant — start several runs with the same groupId from the same tip (different workflows, parameters, or node instructions). Accept the one you keep; the others are rejected and their branches deleted; a later accept in the group returns GroupAlreadyWon.

Expected outputs — a run id; outcome Proposed → Accepted or Rejected (run outcomes); one changement ordinal per accepted run.

If it refuses — 10 non-Started start tokens and 6 non-Accepted accept tokens, each with a recovery: Refusals & failure modes.

Clone a system template

Preconditions — none beyond MCP access; you clone into your own tenant.

Steps

1. workflow_system_list — the 22 built-in templates.
2. workflow_system_get — inspect the graph before you clone; cheaper than cloning just to look.
3. workflow_clone_from_system — you get a fresh draft you own. Cloning never publishes.
4. Continue as in sequence 1, steps 3–6: edit, validate, publish.

Templates are representational: cloning gives you the graph to make your own, not a wire into the flow the platform runs internally. See System templates.

Expected outputs — a new workflowId in state Draft, fully editable.

If it refuses — the clone itself rarely refuses; any problems you inherit surface at workflow_validate_draft, all at once — Refusals & failure modes.

Compose by reference

Preconditions — a draft open for editing; the sub-workflow you want to embed has a Published version — only published versions resolve.

Steps

1. workflow_tile_catalog — the published tiles you can embed, including the sys- building blocks.
2. Place a FlowRef node via workflow_update_draft. The child's tunnel pins project onto the tile; the child shares your run and your acceptance — composition, never a separate invocation surface.
3. Before archiving a workflow that others may embed: workflow_referenced_by. Archive is refused while the list is non-empty.
4. workflow_rebind_flowref — move a consumer to a different target. Rebinding invalidates gate ratification: the affected gates must be re-approved.

Expected outputs — a draft whose FlowRef resolves at validation; workflow_referenced_by returning the live consumers of any published flow.

If it refuses — archiving with live consumers returns CONFLICT; a FlowRef pointing at an unpublished target surfaces at validation. Refusals & failure modes.

Start from a trigger

Preconditions — a published version, and a way off the MCP surface: there is no workflow-trigger MCP tool, so registering the trigger happens in the dashboard or over the platform's REST API. Triggers never fire drafts.

Steps

1. Publish, as in sequence 1.
2. Register the trigger outside MCP — either a human uses Manage triggers on the workflow in the dashboard's workflow list, or you call the REST triggers endpoint. Pick one of three kinds: Schedule (a cron expression), Webhook (the endpoint carries a write-only secret — store it at creation, you cannot read it back), or Event (one of the six live seams: mission.created, conversation.completed, support-case.created, incident.created, batch.completed, mr.merged).
3. Choose the version policy: LatestPublished follows the latest published version; Pinned stays on the one you name. selectedModel and selectedProvider are mandatory on the trigger.
4. Verify a firing: workflow_runs for the workflow's runs, then mission_get and decision_list on the mission each firing creates.

Every firing behaves like a workflow_invoke: a fresh mission, the same graph, the same gates. Triggers never bypass gates — a triggered run pauses at the same decisions a manual run does.

Expected outputs — one new mission per firing; the runs visible under workflow_runs.

If it refuses — a trigger pointed at an archived or never-published workflow cannot fire; omitting the model or provider refuses at registration. Refusals & failure modes.

Refusals & failure modes

This page is the diagnosis surface for the workflow and run tools: when a call is refused, look the token or code up here. Each entry gives the token verbatim, the tool that raises it, the cause, and the recovery. The normative token tables live in the agent reference; the canonical call sequences live in the cookbook.

Every refusal on this page is fail-closed: Genesis refuses and leaves state intact rather than guessing — nothing partial ever lands.

How to read this page

Refusals arrive in two shapes:

• a status token in the reply — mission_run_start and mission_run_accept answer with a token, and any token other than Started / Accepted means the operation did not happen;
• an error envelope carrying a code — the authoring and lifecycle tools refuse with VALIDATION_ERROR or CONFLICT.

A refused call never needs cleanup: fix the cause and retry. For the architecture behind these rules, see the workflows chapter.

Publish & validate failures

Raised by workflow_validate_draft and workflow_publish, code VALIDATION_ERROR. The validator aggregates: it reports every problem in the graph at once, so work through the whole list before you revalidate — there is no hidden queue of problems behind the first one.

Lifecycle conflicts

Code CONFLICT. These protect the three-state lifecycle — Draft → Published → Archived, in that order only.

Run-start refusals

Raised by mission_run_start. Any token other than Started means no run was created. The full 11-token vocabulary is in the agent reference; the sequence that handles them is attach and run.

Accept refusals

Raised by mission_run_accept. Any token other than Accepted means nothing merged: no changement was created and the mission tip did not move. The full vocabulary is in the agent reference.

The last token deserves its own entry, because it comes from the acceptance doctrine rather than from run state:

ValidationRefused — Acceptance is physical: before a run merges, Genesis validates the run branch by exercising it — never by an LLM verdict. The check is fail-closed: if no validation backend is reachable in your environment, the accept is refused rather than waved through. The run stays intact as Proposed; nothing merges. Recovery: confirm a validation backend is available (ask your operator), then retry the accept.

Revert refuses on conflict

Raised by mission_revert. A revert unwinds changements in reverse order, cascading over dependents. It is fail-closed on conflict: if any changement in the cascade cannot be reverted cleanly, the whole cascade aborts and the refusal names the failing member. Nothing partial lands — the mission branch is exactly as it was before the call.

Recovery:

1. Run mission_revert_preview first — it shows the full dependent cascade before you commit to anything.
2. Inspect the named changement in the stack (mission_changement_stack) and resolve what makes it conflict.
3. Retry. A refused revert changed nothing, so retrying is always safe.

See the changement stack for how changements compose on the mission branch.

The Orchestrator

This page exists so you're not surprised when you see the orchestrator surface in the UI. It's internal plumbing; you don't need to know about it for any normal use.

The orchestrator in one paragraph

The orchestrator is ARDS's internal reasoning and routing layer. When it needs to make a decision that isn't a single tool call — picking which coder variant to assign, deciding whether to split a task in two, comparing two possible implementation paths — it dispatches a small research mission to its reasoning layer. That layer runs a parallel investigation (codebase, docs, web), synthesises an answer, and hands it back to the orchestrator to act on.

The orchestrator dashboard

The Orchestrator page is not in the sidebar — open the All features index (the "…" entry at the bottom of the sidebar) and look for Orchestrator. The dashboard shows an overview — expert status, queries handled, recent maintenance waves — and an Explore row of sibling surfaces:

• Team Compositions — team composition history and recommendations.
• Intent Expansions — intent expansion history and implication rules.
• Living Diagrams — auto-generated system diagrams with diff tracking.
• System Health — system harmony analysis and balance metrics.
• Scenario Runner — system validation scenarios and test execution.
• Validation Harness — test prompts across multiple LLMs and compare responses.
• Email Channel — outbound notifications and inbound email processing.
• Migration Dashboard — system migration planning and context mapping.
• Expert Traces — debug expert routing, consultations, and response quality.

These are research surfaces, and browsing them is safe — but not everything is read-only. Trigger Maintenance on the dashboard sits behind a confirmation dialog; Scenario Runner has live Run and Run All buttons that actually execute validation scenarios; and Validation Harness has a New Run panel that sends test prompts to several LLMs (real calls, real spend), plus a Cancel on runs in flight. Leave those controls alone unless an operator asks; everything else you can explore freely without breaking anything.

When you'll see the orchestrator in the UI

• In mission decomposition: a long-running mission may show "Investigating…" during planning. That's the orchestrator's reasoning layer at work, and it's normal. Missions that run a workflow largely skip this decomposition-time reasoning — the graph already is the plan — so the "Investigating…" behavior applies to conversation-born missions.
• In Costs: there's an Orchestrator call-site row alongside Planning, Coder, Review Engine. Usually a small fraction of total spend.
• In Search results: research mission outputs are searchable like conversations.

What testers can actually do with the orchestrator

Nothing you need to, in v1. There's no "start an orchestrator research" button exposed to testers; the orchestrator triggers its reasoning layer as needed. (The one active control on its dashboard, Trigger Maintenance, is for operators.)

If you want a research-style answer from ARDS — "survey the codebase and tell me what's there" — the right path is to start a Conversation and ask for that. The planner will route it through the orchestrator under the hood.

Review Engine

The Review Engine is the automated reviewer — but not of diffs. It sweeps a project's own surfaces (pages, code, config, data, pipelines) and produces findings across quality domains, both on demand and on a schedule. Reviews of coder-produced diffs happen on the Reviews page; that's a separate mechanism.

What it covers

Findings come from domains — each is a tab on the dashboard. The built-in set:

• Security, Architecture, Code Quality, Functional, Data Integrity
• Design Coherence, Discovery, Pipeline Health
• Regulatory Compliance, Third-Party Risk, UI/UX

Each domain produces findings with a severity — Info / Low / Medium / High / Critical — and a one-line summary.

What it reviews

Review sessions run against targets inventoried per project: application pages, code projects, config files, database tables, MCP tools, repositories. Each domain tab has a Target Inventory listing what it knows about. Everything on the page is scoped to the project selected in the top bar.

How it runs

• Scheduled — a daily pulse (lightweight automated checks) and a weekly deep sweep run per project, so sessions and findings appear without any action from you. The Maintenance Schedule panel on the dashboard shows the last daily pulse, the last weekly deep, the last reviewed commit, and the conversation thresholds: when a sweep produces enough findings at or above the configured severity, the engine opens a conversation about them, and High/Critical findings raise attention requests.
• Manual — tick the domains you want in the domain-selection panel and click Review Selected Domains (a dialog asks which LLM preset to run with). On a single domain's tab you get Review domain and, for domains that support it, Trigger Maintenance.

The domain checkboxes only scope the run you're starting — there is no per-domain on/off switch on this page, and nothing here blocks merges: the engine has no merge-gating mode at all.

Reading findings

A finding has a domain, severity, status, a category, a title and description, the target it was spotted on, and usually a recommendation. Click a finding to open the detail panel; from there you can add a note and act: Acknowledge, Open Matter, Won't Fix, Resolve.

Finding states:

• Open — fresh, hasn't been triaged.
• Investigating — marked as being looked at.
• Resolved — fixed.
• Dismissed — you decided it's not a real issue. Stays in history.
• Deferred — punt to later.

When findings are wrong

The Review Engine uses rules and LLM judgments. It will sometimes flag things that aren't issues. Marking a finding Won't Fix (with a note saying why) is a perfectly good outcome — dismissed and won't-fix findings stay in history and searchable.

What Review Engine isn't

• It's not a security scanner you'd bet your life on. Don't substitute it for SAST/DAST.
• It's not a compiler. Some "obvious" errors might slip past if they only fail in a specific build configuration.
• It's not a substitute for reviewing coder work. Diffs from your missions are reviewed on the Reviews page — the engine's findings live here, on its own dashboard.

When to use the Review Engine page

• Checking what the scheduled sweeps found — the domain tabs carry open-finding badges, and the dashboard's domain cards show open/critical counts and when each domain last ran.
• Starting a targeted review after a big change landed in a project.
• Browsing the target inventory and each domain's rules.
• Triaging findings — acknowledging, resolving, or opening a matter from the good ones.

The page is on the All features index (the "…" entry at the bottom of the sidebar), under Review Engine.

Ghost Evaluation

Ghost Evaluation is ARDS's "would a different model have done as well?" machinery. Useful when you're deciding which model to pin to a call site and want evidence, not vibes.

What it does

Ghost re-runs LLM calls against one or more ghost models and compares each ghost's answer with the response the product actually used (the authoritative response). Two things feed it:

• Shadow evaluations, automatically. Live calls from the platform's own call sites — dialogue, research, critic, decomposition, classification, coder — are re-run in the background against the configured ghost models. You don't start these; they accumulate on their own.
• On-demand evaluations. You can queue one yourself from the dashboard (see below).

Ghost runs are ghost: they never change product state. The original conversation is untouched; results live on the Ghost Evaluations dashboard, scored and comparable. Each evaluation compares one ghost model side by side against the authoritative response — there is no N-model matrix.

When it's useful

• "Could a cheaper model hold the planning call site? The leaderboard has weeks of evidence."
• "Does an open-weight model answer dialogue as well as the default, at a fraction of the cost?"
• "We changed the default model — did the character of the answers actually move?"

The dashboard

Two main tabs:

• Stats — filter by source type, read the counters (Total / Completed / Failed / Timeout) and the Model Leaderboard: per ghost model, its completed evaluations, average concordance, judge score, latency, tokens and failures. Rows highlighted green are promotion candidates — models with ≥ 90% concordance over ≥ 50 evaluations.
• Evaluations — the individual runs, filterable by source, status and model. Click a row to open the detail: the concordance breakdown, judge scores when enabled, a latency and token comparison, and a Side-by-Side Comparison of the ghost response against the authoritative response. A Re-run button queues the same prompt again.

Running one yourself

Click New Evaluation on the dashboard:

1. On the Manual tab, type a prompt (plus an optional system prompt) — or switch to From History and pick a single past conversation message (with options to include its context and system prompt).
2. Optionally tick Enable LLM judge scoring.
3. Click Run Evaluation. The prompt is queued against every configured ghost model.

You don't pick models in the dialog. Which ghost models run — and which model judges — is tenant-wide configuration resolved server-side from LLM Config (the ghost-models call site takes a comma-separated model list).

Scoring

Every completed evaluation gets a concordance score computed without an LLM: length ratio, keyword overlap and structural similarity against the authoritative response.

If judging is enabled, one judge model also compares the two answers on fixed dimensions — semantic similarity, factual accuracy, completeness — plus an overall score and a short written reasoning. The dimensions are fixed; there is no per-run rubric and no multi-judge mode. (The judge's instructions can be overridden tenant-wide on the LLM Config Prompts tab, like other system prompts.) The judge is itself an LLM call with biases of its own — read the reasoning, not just the number.

Cost considerations

Each evaluated prompt runs once per configured ghost model, and the judge adds one more LLM call per evaluation. Ghost spend scales with the size of the ghost-model list — keep it short. There is no projected-cost display; watch the Costs dashboard if you're unsure what Ghost is spending.

What Ghost doesn't do

• Doesn't replay tool calls. When the original work involved file edits and commands, Ghost can't re-execute the side effects. It re-runs the LLM-level exchange only.
• Doesn't change anything live. Even when a ghost model outscores the authoritative one, nothing swaps in automatically. Use the evidence to update LLM Config, then run new work.

Fleet tuning

The coder fleet is the pool of containers ARDS spawns to run tasks. In v1, you almost never need to tune it — the defaults are sized for the typical tester workload. This page exists so you can if you want to.

Where to look

• LLM Config → Tools tab — the fleet's home since the surfaces were consolidated. It holds the Fleet Defaults (default tool, variant, model, concurrency, turn budget), per-tool configuration with a live count of active instances, per-variant Resource Limits, and the container registries. The old Fleet Resources page now lands here automatically. LLM Config is on the All features index (the "…" entry at the bottom of the sidebar).
• Fleet Profiles page — named configuration sets layered on top of the system defaults. It has no sidebar entry; open /fleet/profiles directly.
• Coder Fleet page — live operations, not configuration: a Coder Monitor tab (running coders) and a Queue Dashboard tab (what's waiting). Diagnostic reading only.

What you can tune

On the Tools tab of LLM Config:

• Fleet Defaults — Default Tool, Default Variant, Default Model, Max Concurrent (default 3) and Max Turns (default 30). Increase concurrency if you have a big mission with parallelisable tasks; decrease to throttle spend (each coder uses tokens independently).
• Tool Configurations — one card per coder tool, with an enable toggle and API key. Each card shows how many instances are active right now.
• Resource Limits, per variant (standard / browser / android) — Memory, CPU, shared memory (SHM) and Max Instances. Increase memory only if a task page shows out-of-memory kills in the logs; browser and Android variants need the SHM allowance.

Model fallback chains are not a fleet setting — they live in LLM configuration. For workflow runs, dispatch-time preset bindings take precedence — see Presets.

Profiles

The Fleet Profiles page manages named configuration sets with sparse overlays: a profile only stores the fields that differ from its parent; everything else is inherited. One profile ships seeded — System defaults (marked with an S badge; it can't be deleted). There are no other built-in presets.

• Buttons: New Profile, Clone, Delete, Save Profile, Preview Resolved.
• Profile fields: a description, an optional Parent Profile, the defaults (Default Tool — claude, copilot, codex, gemini, aider, octofriend, junie or custom; Default Variant — standard, browser, android; Default Model; Max Concurrent; Max Turns), profile-level environment variables, and a read-only view of per-tool overrides.
• Resolution runs system defaults → parent profile → profile → per-project overrides; provenance badges next to each field show where the resolved value came from, and Preview Resolved shows the final merged configuration.

Profiles apply per project, and binding a profile to a project is currently API-only — there is no button in the UI for it. Until a binding is made, every project runs on the system defaults.

Fleet profiles vs workflow presets

The names rhyme; the jobs don't. A fleet profile configures how coders run for a project: which coder tool and variant, the default model, how many run at once, the turn budget. A workflow preset is a bundle of model and provider choices bound to a workflow, resolved at dispatch time — the most specific scope wins, and it beats whatever model was authored on the canvas. Tune coders here; tune what a workflow's nodes talk to in Presets.

When to worry about the fleet

• Tasks queue forever before running → Max Concurrent (Fleet Defaults) or the variant's Max Instances is too low for your workload. Bump it on the Tools tab.
• Tasks die with "out of memory" → raise the variant's memory limit on the Tools tab.
• Spend doubled overnight → check the Default Model in Fleet Defaults and remember that more concurrency means more parallel token spend.

When to leave it alone

If you're doing 1–3 missions a week of moderate scope, the shipped defaults are correctly sized. Tuning further usually doesn't pay back.

The Tools tab also exposes some operator-grade controls (Docker registries, image discovery). Don't touch those unless an operator told you to — they're there for platform-team use, not testers.

How Genesis Works

Genesis is a multi-agent software-delivery orchestrator. You describe an outcome in plain language; Genesis plans the work, breaks it into tasks, dispatches AI coding agents to do it, runs governance and review gates, tracks every dollar of model spend, and surfaces the whole pipeline to humans through a dashboard, a REST API, and a large catalog of MCP tools. It is multi-tenant: one deployment hosts many isolated customer tenants, each with its own projects, missions, agents, conversations, costs, and compliance posture.

This page is the map. It explains the big pieces and how they fit together, then points to a dedicated page for each subsystem. Every subsystem page is written from two angles: the operator / product surface (what it does and how you drive it — MCP tools, REST controllers, dashboard pages) and the internal architecture (the services, data model, and execution internals).

The shape of the system

Genesis is organized as a hierarchy of intent that narrows from strategy to execution:

• Tenant — the top-level isolation boundary (a customer). The control-plane database holds the tenant registry, environments, and all shared catalogs (LLM providers / presets / routing, system workflows, the compliance requirement/control catalog, constitutional rules, fleet profiles). Each tenant then has its own operational data (missions, tasks, agents, conversations, costs, reviews, knowledge) in a tenant database. Tenancy is implicit via the per-tenant database — there is no TenantId column (ADR-008).
• Project — a unit of work inside a tenant, typically bound to one or more Git repositories. Projects group missions, hold a registered file/module tree, carry a boundary policy, and are the scope for costs, knowledge, and fleet configuration.
• Charter → Matter → Mission → Task — the work hierarchy. A Charter is a strategic initiative (it carries a Vision and acceptance criteria). A Matter is a strategic epic under a Charter. A Mission is a concrete piece of deliverable work that gets decomposed into Tasks, the atomic units agents actually execute.
• Track — every mission and conversation runs in one of four tracks that frame the kind of work: Governance (policy), Research (strategy / investigation), Planning (command / decomposition), and Build (execution). (Older code persists this under a legacy field name; it always denotes the Track.)

The two cornerstones

Two subsystems are the heart of Genesis and have their own deep-dive guides.

• Agents — the autonomous workers. A native Strategic Orchestration Agent (and a standing Compliance agent) run on an event-sourced core (agent_instances + agent_event_queue) and are self-pacing: a background AgentDispatcher ticks every Active instance, the agent reads its event log, plans through one provenance-recorded LLM call, then takes typed, governed actions. Mission-type agents (Feature, Research, Review, onboarding, etc.) wrap that core to drive a specific mission to completion. Coding work is delegated to coders — containerized CLI tools (Claude, Copilot, Codex, Gemini, Aider, Octofriend) spawned per task. See the Agents guide for the full lifecycle, event model, budgets, and dispatch internals.
• Workflows — a reusable, versioned graph of typed steps (stored as GraphJson, with a Draft → Published lifecycle and a content checksum). Invoking a published workflow compiles the graph into a mission whose tasks carry the step wiring; gate steps become pending approval decisions that humans resolve, and the mission records workflowId@version + checksum as compliance provenance. Workflows can embed compliance controls from a versioned catalog (with per-run waivers). See the Workflows guide for the node/pin model, the compiler, gates, controls, triggers, and run internals.

The cross-cutting layers

Three layers run underneath everything above:

• Dialogue — strategic conversations with the model that can propose missions for human approval (the main on-ramp from idea to work).
• The LLM routing layer — every model call is attributed to a named call site (e.g. Missions:Decomposition, ReviewEngine:Architecture). A preset attached to that site resolves the provider, model, routing chain (with fallbacks), tool policy, sampling / limits, and prompt overlay at dispatch time. Modes apply a whole bundle of site attachments atomically. See LLM Configuration & Prompt Overlays.
• Costs & governance — every call writes a cost record (tokens, cache, batch pricing, estimated USD) attributed to its mission / task / project; budgets, quotas, constitutional rules, and compliance gates constrain what agents may do. See Costs & Budgets.

Subsystem guide

Workflows

A Workflow is a reusable, versioned automation that an operator authors once and runs many times. It is a directed graph of typed steps — LLM call sites, system reads, inline write actions, service operations, human approval gates, and control-flow constructs (branch / loop / dynamic fan-out) — wired together by pins. When you run a workflow, Genesis compiles the graph into a mission whose tasks execute on the existing mission engine, with every gate paused behind a human decision and the originating workflowId@version + checksum pinned onto the run as compliance provenance.

Workflows are per-tenant authoring artifacts: every tool and endpoint is gated by the tenant-admin policy, and tenancy is implicit via the per-tenant database (no TenantId column — ADR-008), exactly like missions and tasks.

This page covers both surfaces:

• Operator / product — what a workflow is, its lifecycle, the MCP tool surface, the REST API, and the dashboard pages.
• Architecture — the data model, the graph IR and pin model, the step catalog, materialize → publish → invoke → run internals, system vs tenant workflows, triggers, compliance governance, the mission-run acceptance layer (runs → changements), and how workflows relate to missions and agents.

1. Operator guide

1.1 What a workflow is

1.2 The lifecycle

                 update_draft / materialize / waive_control / validate_draft
                 ┌───────────────────────────┐
                 ▼                            │
  create_draft ───►  DRAFT  ──── publish ───►  PUBLISHED  ──── archive ───►  ARCHIVED
       │              │  (validate + freeze)        │
       │              │                             │
       │          delete_draft                   invoke ───► RUN (a mission)
       │         (permanent)                         │
       └─ clone_from_mission / clone_from_system ────┘ (always lands a new DRAFT)

The only legal status transitions are Draft → Published and Published → Archived:

1. Draft — the mutable working version; the only state that accepts graph edits. A new workflow's first draft is version 1; versioning an existing workflow adds max(version)+1.
2. Update — replace the draft's graph/tunnels payload as many times as needed.
3. Materialize (optional, governed workflows) — inject the required compliance gate/review steps from the active control catalog before publish, so the operator reviews them on the canvas.
4. Publish — validate, then freeze. Validation reports every problem at once (catalog/site checks, pin compatibility, required pins, cycles, gate dominance, compliance floor). On success the version becomes immutable, gets a SHA-256 checksum, stamps PublishedAt, and becomes invocable. At any point before that, workflow_validate_draft runs the identical validation as a dry run — the same aggregated problem list, no freeze, no status change.
5. Invoke — run a published version as a new mission. Multiple published versions of the same workflow can coexist; you choose which one to run.
6. Runs — observe the launched missions per-workflow, per-version, and per-node.
7. Archive — retire a published version (terminal; no longer invocable, kept for provenance). Delete is allowed only on drafts; published versions are immutable and must be archived instead.

1.3 The MCP tool surface

All tools live in WorkflowMcpTools (deferred names workflow_*), are gated by TenantAdminPolicy, and call the same services the REST controllers use through an in-process scope (Core is the service — no HTTP hop). Every tool returns a { success, data } (or { success:false, error, code }) envelope.

Authoring

Discovery / reads

Composition

Execution

workflow_invoke — run a published version.

• Inputs: workflowId, version (must be ≥ 1 — there is no version=0 shorthand here; running "whatever is latest" must be an explicit choice), optional objective, model, provider, paramsJson (a JSON object of run-parameter values), and projectId (optional target project the run's coder writes into — GUID or slug; unknown → 404, non-Active → 409, omitted → tenant default project, recorded in provenance as projectScope).
• Behavior: compiles the graph into a mission whose tasks carry the step wiring; every gate step is paused behind a pending approval decision (resolve with decision_respond: approve releases the gate once prior steps complete, skip cancels it, fail fails it). model + provider are required unless tenant defaults resolve them — there is no silent model fallback.
• Returns: { missionId, workflowId, version, checksum, stepCount, gateCount, controlCount }.
• Follow-ups: mission_get to watch the run; decision_list to find pending gate approvals; workflow_run_nodes for per-step status.

Cloning (save a run, or fork a template)

System-workflow templates

Node instructions

Every workflow node can carry node instructions — extra text layered onto the node's prompt at dispatch. Instructions live in scoped slots with precedence run > project > tenant > global (the most specific slot wins). Three tools manage them, gated by the same tenant-admin policy as the rest of the surface:

Today every live slot is set by hand; the PromptEngineer proposal path (ARDS proposing prompt improvements itself) is not live in v1 — the CONFLICT guard reserves its slots.

1.4 REST API

Base route api/v1/workflows (tenant-admin). Mirrors the MCP surface for the dashboard composer:

• GET /workflows — one row per workflow identity (latest version).
• GET /workflows/catalog — the step-type palette.
• GET /workflows/{workflowId}/versions — all versions, newest first.
• GET /workflows/{workflowId}/{version} — one version with the full payload.
• POST /workflows — create a draft (body: graphJson, optional workflowId/tunnelsJson/name).
• PUT /workflows/{id} — replace a draft's payload.
• POST /workflows/{workflowId}/rename — set the display name on all versions.
• POST /workflows/{id}/materialize · POST /workflows/{id}/waive — compliance overlay + waiver.
• POST /workflows/{id}/publish — validate + freeze. Note: completed validation is always HTTP 200 with a { success, workflow, problems[] } envelope (success:false + a list of structured { nodeId, pin, message, raw } problems on failure) — the dashboard maps any non-2xx to "request failed", so a validation failure must stay a 200 envelope. 404/409 remain for missing/non-draft rows.
• POST /workflows/{id}/archive · DELETE /workflows/{id} — archive (published) / delete (draft).
• POST /workflows/{workflowId}/{version}/invoke — run.
• POST /workflows/clone-from-mission — clone a mission to a draft.
• GET/POST /workflows/system[...] — list/get/clone system templates.
• GET /workflows/{workflowId}/runs and /runs/{missionId}/nodes and GET /workflows/runs (fleet) — run observability (§2.10).

Trigger CRUD lives under api/v1/workflows/{workflowId}/triggers (§2.9); the run-centric read surface also has api/v1/workflow-runs/{missionId}/graph-status and GET /workflow-runs (in-progress runs).

1.5 Dashboard pages

The Blazor composer (Genesis.UI) provides:

2. Architecture

2.1 Data model

Workflows persist in three places. Critically, runs are not a workflow table — a run is a Mission + its TaskDefinition rows, stamped with workflow provenance in Mission.Metadata["workflow"].

workflow_records (tenant DB — WorkflowRecord): one row per (workflowId, version).

workflow_triggers (tenant DB — WorkflowTrigger): automatic trigger bindings, not graph-embedded (so they survive re-versioning). Columns: id, workflow_id, version_policy (LatestPublished/Pinned), pinned_version, trigger_type (Schedule/Webhook/Event), config_json (jsonb), webhook_secret (write-only), selected_model, selected_provider (both required — invoke has no fallback), objective, params_json, target_project_id, is_active, last_run_at, next_run_at, audit columns. Indexed (workflow_id, is_active) and (trigger_type, is_active, next_run_at).

system_workflows (control-plane DB — SystemWorkflowRecord): platform templates surfaced read-only to every tenant. Columns: id, workflow_key (unique), name, description, category, scope (Tenant/Platform), is_system_seed, status, graph_json, tunnels_json, checksum, timestamps. Reconciled from the code catalog on startup; tenants may clone but not edit them.

The compliance control catalog (workflow_control_catalog rows, control-plane + tenant) backs materialize/floor checks; it is documented under Compliance.

2.2 The graph IR and node/pin model

WorkflowRecord.GraphJson parses (via WorkflowIrSerializer) into a WorkflowIr record:

WorkflowIr { int IrVersion, IrNode[] Nodes, WorkflowEdge[] Edges, WorkflowParam[]? Params }
WorkflowEdge { PinRef From, PinRef To }   PinRef { string NodeId, string Pin }

Node kinds (IrNodeKind) — 16 kinds:

A latent LLM site that fires exactly one terminal outcome (onSuccess/onFailure/onRefusal) is an async call site; its descriptor exposes outcome pins instead of a single out, and the runtime fires exactly one arm (OutcomeRole).

Pins (PinKind): Exec (sequencing only, never carries data, never widens), Context, Document, Artifact, Json (may carry a JSON-Schema refinement), String, Number, Bool. Wiring is legal when kinds match (plus scalar→Json widenings); when both sides of a Json edge declare a schema, structural subset compatibility is enforced at publish. A PinDescriptor carries Name, Schema (kind + optional schema), Required, an optional editor-only DefaultValue, and Variadic (a data pin that accepts >1 incoming edge — an N-way fan-in collected into an array at runtime).

Params (WorkflowParam { Name, JsonSchema?, Required, default? }): graph-level invocation parameters. Values passed to workflow_invoke(paramsJson) are resolved at compile time into the bound pins' literals — there is no runtime parameter plumbing. A param bound to a required pin must itself be required or carry a default (checked at publish), so a published workflow can never compile into a task missing a required input.

Vocabulary / wire-format note: the IR persists a node's track under a legacy field name, kept stable so published checksums stay byte-identical. In all prose, UI, and tooling this field is the step's Track (Governance / Research / Planning / Build); the compiler defaults it to Build.

2.3 The step catalog (palette)

WorkflowNodeCatalog.All is the curated, code-defined palette of 128 step types (pinned live census). Each entry is a WorkflowNodeDescriptor { NodeTypeId, Kind (LlmSite/ReadAdapter/ActionAdapter/ServiceAdapter), SiteId, Inputs[], Outputs[], Outcomes?, ConfigFields? }. The descriptor attaches typed pins alongside the existing call-site registry — it never modifies LlmCallSite in Genesis.Contracts; an unannotated site is simply not palette-eligible. Representative entries:

• LLM call sites: Missions:Decomposition, Coder:Default (sync) and Coder:AsyncDefault (outcome arms), ReviewEngine:Default. Every LLM site also carries two optional ghost-evaluation pins (ghostEval, ghostEvalModel). The Coder sites expose ConfigFields (Task Type, Track, Coder Variant, pinned Preset id) that the Properties panel renders and the compiler/validator read.
• Read adapters (pure, never gated): read:mission_get, read:gitlab_get_file, read:intelligence_knowledge_query, read:loki_query_range, read:task-deps:resolve, read:boundary:validate, read:task-routing:route, workspace:read_file, workspace:list_files.
• Action adapters (inline workspace writes, gate-dominated): workspace:write_file, workspace:create.
• Service adapters (inline C# operations, gate-dominated): workspace:merge, service:decomposition:propose, the service:research:* family (investigate-codebase/docs/web, synthesize, critique, llm), the service:review-engine:*, service:ux-review:*, service:canary:*, service:improvement:*, service:support:*, service:onboarding:*, service:aspect-onboarding:*, service:validation-runs:*, service:batch-processing:*, service:satisfaction:score, service:git-push:default, and the service:compliance:* evaluators (SCA, clause-map, ROI completeness, incident timeliness, and the CRA / PLD families).

Read adapters' result schemas come from the adapter DTO files (single source of truth). The Genesis.Missions library stays free of the Contracts dependency — the Genesis.Core publish validator cross-checks each SiteId against the live LlmSiteRegistry.

The census by taxonomy family (17 families): ComplianceChecks 24 · Validation 20 · Missions 11 · Scaffolding 9 · Onboarding 9 · Support 8 · Review 7 · Improvement 7 · Workspace 6 · Research 6 · Incidents 5 · Agents 4 · Git 3 · Knowledge 3 · ComplianceAssess 3 · Communication 2 · Legacy 1. By descriptor kind: ServiceAdapter 102, ReadAdapter 18, LlmSite 4, ActionAdapter 2 (workspace:write_file, workspace:create), plus the generic Llm and Agent entries (one each). Exactly one node is Legacy — service:research:llm, superseded by the generic llm node and publish-blocked in new drafts.

Catalog-wide conventions: every node rides the Exec spine (in/out) — the sole exception is Coder:AsyncDefault, the one multi-arm node, whose exec exits are its outcome arms; 122 of 128 emit a required result:Json output; the six brain nodes (Missions:Decomposition, Coder:Default, Coder:AsyncDefault, ReviewEngine:Default, llm, agent) are the only ones carrying the context:Context pin, and the four wired LLM sites among them (Missions:Decomposition, Coder:Default, Coder:AsyncDefault, ReviewEngine:Default) are the ones where the ghost-evaluation (ghostEval/ghostEvalModel) pin pair is live; the fan-out families follow a prepare → per-item → reduce triad (the per-item body node's first input is item:Json, required); and a few nodes emit typed handles alongside — or instead of — result: runId (service:compliance-assess:prepare), incidentId (service:incident:create), leaseId (service:run-target:lease), workspace (workspace:create/workspace:merge).

2.4 Authoring and the compliance overlay (materialize)

materialize (ComplianceOverlayService.MaterializeDraftAsync) runs before publish so the operator reviews the injected controls on the canvas. It:

1. Parses the draft IR.
2. Reads the floor — the active control catalog (IWorkflowControlCatalog.GetActiveAsync) — plus additive-only governance augmentations (IOverlayGovernanceAugmenter; the default reads nothing, the seam allows a project to add controls, never remove a floor control — the ratchet design).
3. Runs the deterministic ComplianceOverlayMaterializer, which injects the required human-gate and regulatory-review/service:compliance:* nodes keyed off the development stages the graph's nodes are tagged with (Design / Implementation / Integration / Verification / PreDeployment), plus the base always-required controls. Injected nodes carry overlay provenance ({ controlId, catalogVersion }).
4. Idempotent: if the canonical JSON is unchanged it returns the draft untouched (no checksum churn). Otherwise it persists the parse-compatible wire form draft→draft.

waive_control appends an audited waiver { controlId, reason, grantedBy, grantedAt } to the draft so the publish floor treats that control as satisfied — unless the control is non-waivable, in which case the presence of a waiver is itself a publish violation.

2.5 Publish and validation

IWorkflowRepository.PublishAsync runs a single injected IWorkflowPublishValidator — a CompositeWorkflowPublishValidator that runs every registered validator and aggregates all problems (no short-circuit), so structural, registry, and compliance-floor issues surface together. The three validators:

1. Structural — WorkflowIrValidator (pure; no DB/registry). It runs the same way the compiler will: FlowRef-expand → Validate(Authored) → control-flow-expand → Validate(Final). It checks: well-formed ids (unique, no reserved __/# segments), at most one Event, per-kind pin models, edge kind/schema compatibility, single-edge-per-data-pin (relaxed for variadic), required-pin connectivity, literal/param binding rules, branch/loop/fan-out configuration, branch-arm and outcome-arm reconvergence isolation, acyclicity (with an explicit cycle path), and — the cornerstone — gate dominance.
2. Registry — LlmSiteRegistryWorkflowPublishValidator (Genesis.Core): re-runs the structural pipeline on the FlowRef-expanded graph, cross-checks every call site's SiteId against LlmSiteRegistry.GetAll(), validates the draft's tunnel signature (names/kinds/binds), and validates any node-pinned LLM preset id is known and eligible.
3. Compliance floor — ComplianceFloorPublishValidator (Genesis.Core, fail-closed). A graph is governed iff any node carries a stage tag or an overlay-injected node. Ungoverned graphs publish unchanged. For a governed graph: every write-classified node must carry a stage; a required control is satisfied only by a node matching its control id and node kind; a missing control passes only with an explicit waiver (and only if the control is waivable). On success it pins the active catalog version onto the record.

Gate dominance. The wave executor runs a task only when all its dependencies have completed. So a write-classified step (CallSite / Action / ServiceAdapter) is execution-blocked by a gate iff a Gate node is an ancestor in the union (exec + data) dependency graph. The validator enforces exactly that: every dependency path to a write must traverse a Gate. Read steps are never write-classified and never gated. The one exemption is an overlay-injected service:compliance:* check — it is the protection mechanism (deliberately placed before the stage gate so a failed check cascade-cancels the gate→push), not an author write.

Publish failure is reported as VALIDATION_ERROR over MCP and as a 200 { success:false, problems:[…] } envelope over REST; the controller parses each validator message into a structured { nodeId, pin, message, raw } for canvas highlighting.

2.6 Invocation: compiling a graph into a mission

WorkflowInvocationService.InvokeAsync is compile-first so a graph that no longer compiles (e.g. a referenced sub-flow was unpublished) never leaves an orphaned mission:

1. Load + integrity. Fetch (workflowId, version); require Published; recompute the SHA-256 of graph_json and refuse if it does not match the stored checksum.
2. Compile (pure). Parse the IR, build a FlowResolver (resolves FlowRef sub-flows; only Published versions resolve), generate a fresh per-invocation seed, parse paramsJson, and run WorkflowCompiler.Compile. The compiler is pure and deterministic — no DB, no clock, no fresh GUIDs; same graph + same seed → byte-identical task set. It:
   • FlowRef-expands, validates (Authored), control-flow-expands (Branch/Loop/MapFanOut → Control nodes), validates (Final), then applies params into literals.
   • Assigns deterministic TaskDefIds (DeterministicIdGenerator.TaskDefId(seed, nodeId)), computes Kahn topological waves (the ExecutionOrder), and lowers each node to a CompiledTask carrying TaskType, Track, CoderVariant, DependsOn, status, allowed tools, acceptance criteria, a workflow carrier (the JSON describing node id/kind/site/inputBindings/outputSchema/control config, used at dispatch), and — for gates — a CompiledGate.
   • Lowering by kind: Gate → gate/Paused; Control → workflow-control/Paused; Read → analyze/Pending; Action → workflow-action/Pending; ServiceAdapter → workflow-service/Pending; CallSite → code (or configured)/Pending. Defense-in-depth guard throws against a non-gate row carrying the reserved gate/workflow-control/workflow-service task types (which would self-approve or mis-route).
3. Resolve the optional target project (fail-loud before the mission is created; an omitted target is logged and recorded as projectScope=tenant-default).
4. Derive model/provider for a one-click UI invoke from a coder node's pinned preset (resolved through the same Coder:Default site dispatch uses) — additive and blank-gated, so a caller-supplied model/provider is a no-op here.
5. Create the mission with Metadata.skipDecomposition=true and a workflow provenance blob (workflowId, version, irChecksum, invocationSeed, paramsJson, targetProjectId, projectScope). Model/provider are forwarded to CreateMissionAsync, which fails loud when both are blank.
6. Materialize the tasks in one save (the ProposalMaterializer pattern) with pre-set TaskDefIds and per-task status. Gate and control rows get MaxRetries=0 (a rejected gate must stay rejected; a fail-resolved loop-exit must stay failed — auto-retry would otherwise resurrect them as "approved").
7. Queue one approval request per gate through the decision queue (IDecisionQueueService), carrying the gate's decision arms / typed fields in the AttentionRequest metadata, and an optional deadline + timeout action. If anything fails mid-materialization the mission is compensated to Failed (a half-materialized run with an unblockable gate must never park silently).

The result is { missionId, workflowId, version, checksum, stepCount, gateCount, controlCount } (compiler-synthesized control rows are excluded from stepCount and surfaced separately).

2.7 Runtime execution of a run

A run executes on the existing mission engine (ArdsMissionOrchestrator) — workflows add no new runtime. Because the mission is created skipDecomposition=true, the orchestrator never auto-decomposes it; it dispatches the pre-materialized tasks by wave. For workflow-provenance missions, each orchestrator tick runs a deterministic control pass (IWorkflowControlService.EvaluateAsync) before the Ready-dispatch and Pending→Ready promotion loops:

• It reads each workflow-control task's resolved carrier and the in-memory task list and runs to a fixpoint (guard-capped), only ever transitioning statuses of already-materialized tasks — it never creates tasks (except the MapFanOut materializer, which adds body work tasks idempotently). The routers: RouteBranches, RouteLoopContinues, RouteLoopExits, RouteGateSkipArms, RouteGateDecisionArms, RouteOutcomeArms, RouteMapFanOut, RouteMapJoins, and CascadeSkip (dead-region cancellation, marked workflow-cascade to distinguish from an operator skip).
• Conditions prefer an authored boolean RulesEngine expression when present, else fall back to a dotted-path-plus-expected scalar equality — so every pre-expression graph behaves byte-identically.

Step execution by kind:

• Gate — born Paused with an open AttentionRequest. The operator resolves it via decision_respond/decision_create: approve releases dependents once prior steps complete (pre-approval is allowed); skip cancels the gated region; fail fails it. N-arm gates route on the decision pin (never the display label); typed gate fields are captured onto the gate's ResultSummary and exposed via a response data pin.
• Read / Action / ServiceAdapter — run inline in the dispatch poller (never dispatch a coder): the orchestrator resolves the matching IWorkflowReadAdapterExecutor / IWorkflowActionExecutor / IWorkflowServiceAdapterExecutor, passes the carrier's resolved inputBindings (literals, upstream output references, and dispatch-time name-pattern bindings via WorkflowReadInputResolver), and writes the result back. Action/ServiceAdapter rows are guarded: a row reaching dispatch without compiler carrier provenance is failed rather than run.
• CallSite — materialized into a coding task and dispatched to a coder as usual; the carrier's node-pinned preset drives provider routing, and an async call site must emit a parseable {"outcome":…} final line (the result consumer fails+retries a result that declares none).

2.8 System vs tenant workflows

The platform ships 22 system-workflow templates that represent the hardcoded orchestration flows as composable graphs, defined in code (SystemWorkflowCatalog) and reconciled into the control-plane system_workflows table on startup. The category breakdown: Mission ×6 (sys-mission-lifecycle, sys-research-mission, sys-decompose-direct, sys-mission-decompose-grounded, sys-decompose-research, sys-task-dispatch), Onboarding ×4 (sys-first-run-onboarding, sys-aspect-onboarding, sys-intelligence-scaffolding, sys-project-onboarding), Ops ×3 (sys-batch-processing, sys-canary, sys-run-acceptance), Compliance ×2 (sys-compliance-assess, sys-incident-pipeline), Review ×2 (sys-review-engine, sys-ux-review), Validation ×2 (sys-llm-preset-validation, sys-validation-runs), Evaluation ×1 (sys-satisfaction-scoring), Improvement ×1 (sys-improvement-cycle), Support ×1 (sys-support-case-triage). These exercise the real constructs — e.g. sys-mission-lifecycle is an engine-driven MapFanOut (one coder per proposed task, count unknown until decomposition runs); sys-research-mission runs 3 parallel investigators (a diamond) into a bounded synthesize→critique revise loop (max 3 passes, breaking the moment the critic approves).

System rows are read-only to tenants (ISystemWorkflowStore): tenants can list/get and clone into a tenant-owned draft (workflow_clone_from_system → fresh identity, graph verbatim), then edit/publish/invoke freely. Scope="Platform" templates are hidden from tenant surfaces.

Two catalogs, two purposes. SystemWorkflowCatalog holds the 22 representational templates above — read-only clonables: cloning one gives you the graph as an editable tenant draft, not a wire into the platform's hardcoded flow. Separately, SysWorkflowInventory seeds 19 executable sys- compositions, published per-tenant as real workflow versions and surfaced as FlowRef tiles for embedding (e.g. sys-research-codebase, sys-decompose-propose); most are seed-only today — the legacy call sites they mirror have not yet been re-pointed onto them. The full template enumeration lives in the user docs: the templates page.

A related capability, decomposition-as-workflow (MaterializeDecompositionWorkflowAsync), materializes a system decompose template (sys-decompose-direct / sys-decompose-research) directly onto an existing mission and auto-resolves the plain leading gate through the live decision path — the flag-gated seam that replaces the inline phase invoker for opted-in missions.

2.9 Triggers (automatic invocation)

A WorkflowTrigger binds a published workflow (by stable workflowId + a version policy: LatestPublished or Pinned) to an automatic source. Every source ends at the same call — resolve the published version and InvokeAsync — differing only in how "fire now" is detected:

• Schedule — WorkflowTriggerScheduler (a BackgroundService, ~1-minute loop with a startup delay) fans out over the tenant registry and fires rows whose NextRunAt is due, then advances NextRunAt via the shared cron parser. Missed-window policy: fire once and recompute forward (never catch up N occurrences); NextRunAt is the idempotency guard.
• Webhook — an inbound GitLab event verified against the per-trigger webhook_secret (constant-time, never logged), filtered by eventType + a filterJson.
• Event — WorkflowTriggerDispatcher looks up active Event triggers for an in-process domain event (the six live seams: mission.created, conversation.completed, support-case.created, incident.created, batch.completed, mr.merged), evaluates each trigger's matchJson (projectId / keyword filters) against the event context, and invokes matches. A bounded (trigger, eventId) set gives at-most-once delivery per process; a loop guard skips dispatch entirely when the context carries triggerSpawned:true, so a trigger-spawned mission cannot re-fire mission.created.

Triggers are validated fail-loud at create time (the workflow must have a published version; selectedModel + selectedProvider are mandatory because invoke has no fallback; a Schedule cron must parse; a Webhook needs a secret + eventType). Triggering never bypasses or auto-approves a gate — fail-closed discipline is preserved. Triggers are not graph-embedded, so they survive re-versioning.

2.10 Run observability

Because a run is a mission, observability is a projection over its tasks rather than a dedicated store. WorkflowRunsReader reads Mission.Metadata["workflow"] provenance and maps each TaskDefinition back to its authoring node id via the carrier (shared by MCP and REST so they can't drift). Beyond the raw workflow_run_nodes shape, the read services project each node to a NodeRunState — the eight TaskDefinitionStatus values plus a derived AwaitingGate (a Paused task that has an open, unresolved AttentionRequest). The surfaces:

• GET /workflows/{workflowId}/runs/{missionId}/nodes — per-node projected states, filterable by state / nodeType / gateLabel.
• GET /workflows/runs — fleet view: cross-workflow runs with a per-run NodeRunState rollup, sourced from the F003-safe GetMissionsAsync, filterable by the shared RunFilter grammar (template/missionId/time-window/providerModel at run level; state/nodeType/gateLabel at node level).
• GET /workflow-runs/{missionId}/graph-status and GET /workflow-runs — the run-centric FE surface (per-node status + in-progress runs). The graph shape itself is fetched through the existing version API using the returned workflowId + version — it is deliberately not duplicated here.

(Fan-out body tasks are node-grain-incomplete in the per-run read until the body carrier carries provenance fields; the fleet rollup counts all real task rows.)

2.11 Clone-from-mission

WorkflowCloneService.CloneFromMissionAsync turns a run back into a draft via two paths chosen by what the mission carries:

• Workflow-born — the mission pins workflowId@version provenance and the source WorkflowRecord still exists: its GraphJson is re-drafted verbatim under TargetWorkflowId ?? sourceWorkflowId (a checksum drift only adds a note).
• Organic — no usable provenance (a hand-built/decomposed mission, or one whose source record was deleted): MissionGraphReconstructor rebuilds a graph from the mission's task rows, adding a trigger and — only when needed — a single approval gate so the result is publishable, reporting every repair in the notes.

It never publishes (always lands a Draft the author reviews) and surfaces the mission's objective + model/provider as run hints only — no pin-level parameters are extracted.

2.12 Relationship to missions and agents

• Missions are the substrate. A published workflow compiles deterministically into a mission's TaskDefinition set; the run executes on the existing wave executor, decision queue, and orchestrator sweeps. Workflows add the authoring/versioning/compliance layer; missions add nothing back into the graph.
• Gates reuse the decision system. A gate is not a new entity — it is an AttentionRequest row + task Paused + mission PendingOperatorDecision, resolved by the same decision_* tools agents and operators already use.
• Agents are the executors. CallSite steps dispatch coders/agents exactly as decomposed mission tasks do, honoring per-node LLM presets through the same provider routing; read/action/service steps run inline against the same services. A workflow is therefore a governed, reusable, gate-enforced way to orchestrate the same agent fleet that ad-hoc missions use — with provenance (workflowId@version + checksum) pinned onto every run as a compliance artifact.

2.13 Mission runs and changements (the acceptance layer)

workflow_invoke creates a fresh mission (§2.6). A published version can also be run inside an existing mission as a discrete, acceptable unit — a MissionRun — via mission_run_start (flag-gated Workflows:MissionRuns:StartEnabled; enabled on current deployments). It reuses the same compile-first pipeline, but the run is born on its own git branch off the mission tip (strict-sequential: the run's base SHA must still equal the tip), and every materialized task is stamped with the run id/branch.

mission_run_accept closes the loop and is the unit of acceptance:

1. Re-check the run's base is still the mission tip (else a StaleRefused — re-run off the current tip).
2. Run the non-waivable physical-validation floor against the run branch. This is fail-closed: with no live execution backend to validate against, the accept is refused (ValidationRefused), never passed unvalidated.
3. Merge the run branch onto the mission tip and record the result as a Changement — a reversible unit carrying an ordinal, its touched files, and its dependencies on prior changements (derived by file overlap). The accepted tip is sealed, so the mission tip stays always-green.

mission_changement_stack lists the stack in ordinal order. mission_revert_preview + mission_revert undo a changement together with the transitive closure of everything that depends on it, in reverse order, each as a merge-revert — fail-closed on conflict (a conflict aborts the cascade cleanly and names the failing member). mission_run_discard drops an un-accepted run (marks it rejected, deletes its branch) without touching the stack; a competition run resolves to exactly one winner (siblings rejected, branches deleted). This is how a workflow's output becomes reviewable, acceptable, and reversible on the mission it runs in.

mission_run_start takes an optional groupId. Omit it and runs are strict-sequential: a second start while a run is still open is refused (RunAlreadyOpen) — accept or discard the open run first. Pass the same groupId to N starts and the runs compete from the same base SHA: exactly one can be accepted; the siblings are rejected and their branches deleted (GroupAlreadyWon on a late accept). mission_run_get returns the per-node roll-up plus the acceptance anchors — the changement, the physical-validation seal (tip SHA + verdict), and isAnchored, true iff the run is Accepted and its changement applied and its seal passed.

The two status vocabularies, verbatim. mission_run_start returns one of 11 statuses: Started · FeatureDisabled · AgenticMissionUnsupported · MissionTerminal · MissionNotPlanned · ChildSpawnerDisallowed · RunAlreadyOpen · TipUnavailable · WorkflowNotFound · NotInvocable · MaterializationFailed. mission_run_accept returns one of 7: Accepted · StaleRefused · MergeConflict · GroupAlreadyWon · ValidationRefused · NotProposed · TipUnavailable.

Agents

Audience: Genesis operators and Genesis agents alike. This page documents the agents subsystem end to end — what agents are and how you drive them (operator surface), then how the dispatch, scheduling, budgeting, and LLM-call internals actually work (architecture). It is a deep page; skim the operator half, read the architecture half when you need to reason about behaviour.

1. What an agent is

In Genesis, an agent is a long-lived autonomous worker that runs a plan-then-act loop on its own cadence. Unlike a one-shot LLM call, an agent:

• persists as a row (agent_instances) in its tenant's database, with a lifecycle status, an active operating mode, and self-pacing scheduling state;
• wakes on a schedule (a heartbeat "tick") and on external events (an operator message, an answered question, a mission state change);
• reasons once per tick through a single provenance-recorded LLM call, then takes typed actions (propose a mission, escalate a decision, message the operator) strictly through governed tool calls;
• remembers its own past turns (an append-only state ledger) and re-injects them as continuity context;
• never self-applies anything risky — every consequential action is either governance-gated or routed to a human via the decision queue.

There are two broad families that share most of this machinery:

1. Standing agents — always-on, tenant-scoped brains that run a continuous plan-then-act loop: the Strategic Orchestration Agent (SOA) and the Compliance agent. These are the focus of this page.
2. Bursty / bound agents — agents that exist to do a finite job and then go quiet: the Prompt Engineer (one burst per call-site rework) and mission agents (one mission lifecycle each).

Separate from both is the lightweight in-memory agent registry — a coordination directory of external/worker agents (coders, reviewers, monitors) used for capability-based task routing. The same word "agent" covers both the heavyweight standing brains and the registry entries; the sections below keep them distinct.

2. Operator surface

2.1 Agent types

There are two complementary type systems.

(a) The persisted AgentType discriminator — the authoritative type of an agent_instances row. It selects the agent's policy, its planning preset/site, its operating-mode catalogue, and (for missions) the lifecycle pump.

The Mission* members mirror the mission "kind" one-for-one. A mission "runs as an agent-type" only at the policy + LLM-invocation seam — its lifecycle is still driven by the separate mission pump off the missions / mission_event_queue tables. Native standing agents (Soa, Compliance, PromptRedactor) run directly on agent_instances / agent_event_queue.

(b) The in-memory registry role — a lighter directory for coordination and routing. When you call agent_register, you supply a free-form role (Developer, Reviewer, Coordinator, Monitor, or Generic) plus capabilities. These registry agents are how coders and other workers advertise themselves so tasks can be routed to them by capability. Registry entries are ephemeral (in-process, tenant-partitioned, heartbeat-expired after 5 minutes); the agent_instances rows are durable.

2.2 Registration & discovery (the coordination registry)

These MCP tools manage the in-memory registry (they proxy Core's /api/v1/agents controller):

The standing SOA registers itself here automatically (role/type orchestration) so it appears on the /agents dashboard and can receive live turn pushes; that registration is a UI surfacing convenience, not the SOA's control plane.

2.3 Spawning and driving coders

Coders are containerised coding workers. Two layers:

On-demand coders (OnDemandCoderMcpTools, tenant-admin, proxy /api/v1/coders/on-demand):

Coding tasks (CodingTaskMcpTools, tenant-admin) — the actual unit of work a coder executes:

The model/provider/backend for a coding task resolves through the same preset machinery as everything else (see §3.7); presetId overrides the explicit model/provider/backend triple.

Windows lane (WindowsMcpTools, behind the windows-pool feature, attached with enableWindowsMcp) — a coder leases a Windows worker on first use (no lease verb; the session is held across calls until windows_release hands it back, the task settles, or the lease expires) and drives it through two shapes. The build shape: windows_run_spec (submit a script, get a task handle) + windows_task_status (poll). The desktop shape (ARDS-857), which drives real UI Automation on the leased machine the way the browser tools drive a page: windows_launch (start a program, get {pid, hwnd, title}), windows_windows (visible top-level windows with their hwnd and bounds), windows_focus / windows_close, windows_snapshot (the UI Automation tree as indented text, one node per line with a ref=e<N> that stays valid until the next snapshot), windows_click and windows_type (target by ref, else automationId / name / controlType, else a screen point; the returned method says whether the element's own pattern or a real mouse click / keystrokes did it), windows_key (chords such as Ctrl+S, Alt+F4), windows_wait_for (an element or a window title reaching exists / enabled / gone), windows_computer (raw mouse / keyboard in primary-screen pixels) and windows_screenshot (the primary screen, or cropped to an hwnd; its pixels are the coordinates windows_computer takes). windows_release hands the leased machine back to the pool at once: it ends the session (a windows_run_spec build still running on it is cancelled and the programs launched on it are closed), the next windows_* call leases a new one, and it is idempotent — with nothing held it answers released: false (outcome: not_held) and changes nothing. windows_type takes exactly one of text / secretRef: a secretRef names a secret the operator provisioned on the Windows pool (a credential, a licence key) — the pool types its value on the machine and the value never reaches the coder. A secretRef may only be typed into a password-masked control: aimed at anything else the guest refuses without typing (SECRET_TARGET_NOT_MASKED), and on a call that carried typed input the pool's error body reaches the coder projected to {error, reason, state, secretRef, host} — never the guest's free text. windows_screenshot with an hwnd is a pure read — the window is not brought to the front and a covered region shows what is on top; windows_focus first when it matters. When a coder's Windows session is released (by windows_release, expired, evicted, or the task settled), the pool has the guest close every process that session started with windows_launch before the slot is reused, so nothing a coder launched outlives its lease. windows_wait_for.timeoutMs is clamped to 10 minutes and windows_launch.waitForWindowMs to 55 s — the guest's own ceiling, ordered guest < pool < core (the pool's launch budget is the wait + 10 s), so a program that shows no window by then comes back as the guest's honest hwnd: null, never as UI_TIMEOUT (both clamped, not refused). Every error a Windows verb returns carries one of these codes. FEATURE_DISABLED: the windows-pool feature is off for this tenant — every verb, before any lease; an operator turns it on. VALIDATION_ERROR: windows_type was given neither or both of text / secretRef, or a secretRef that is not a bare name — fix the call, no machine was leased. A host with no interactive desktop answers every desktop verb DESKTOP_UNAVAILABLE with the pool's reason: session_0 is a compile-only install (no retry changes it); capture_probe_failed means the host's interactive session stopped rendering (its RDP client disconnected or was minimised) — an operator has to restore that window, after which the pool re-probes the desktop within 30 s, so retry only after the operator acts; ELEMENT_NOT_FOUND means re-snapshot, WINDOW_NOT_FOUND means that hwnd is gone (list again with windows_windows), WAIT_TIMEOUT carries the elapsed time, UI_TIMEOUT means the guest did not answer within the pool's per-call budget (a modal dialog may be blocking the desktop — windows_screenshot shows it; retryable), SECRET_NOT_FOUND names the missing secret for the operator, WINDOW_NOT_FOREGROUND means focus the target (or dismiss what covers it) and retry, INPUT_BLOCKED means a higher-integrity window or a locked desktop refuses input. Anything else is the pool's generic vocabulary, shared with the browser and emulator lanes: POOL_UNAVAILABLE (no HTTP answer — the pool is unreachable or the call outlived core's HTTP timeout; retry), POOL_ERROR (the pool answered 5xx; at capacity it names the current holder(s), so a busy pool reads differently from a leaked hold; retry), UNAUTHENTICATED / FORBIDDEN (the pool refused core's credential — an operator fixes the resource-pool-auth secret; no retry helps), NOT_FOUND with sessionEvicted: true (the pool no longer knows the session: the hold was dropped, the machine's state is gone, the next call leases a fresh one), CONFLICT (a 409 outside the desktop vocabulary, such as a windows_run_spec while a task is already running — its taskHandle is in poolDetail), RATE_LIMITED (429; retry later) and BAD_REQUEST (any other refusal — an unknown key name in windows_key, for instance). Each error's data carries httpStatus, retryable and the pool's own body as poolDetail.

2.4 Human-in-the-loop (HITL)

Agents never silently make irreversible calls. There are two HITL channels:

The decision queue (agent escalation). When a standing agent needs a human call it raises an AttentionRequest via soa_propose_decision (or, internally, soa_propose_mode_change for a mode switch). This:

1. is constitution-gated before it is created (a violation is fed back to the agent, not thrown);
2. appears on the operator's decision queue (the decision_* tools / dashboard) as a SOA-origin request carrying { source: "soa", soaInstanceId };
3. pauses the relevant work until the operator answers (decision_respond).

When the operator resolves it, AgentControlService.EnqueueOperatorAnsweredEscalationAsync enqueues an OperatorAnsweredEscalation event back to the exact originating instance, carrying the operator's resolution + resolutionNotes. The agent resumes from that event on its next tick. The round-trip is idempotent (a unique partial index dedupes concurrent REST-then-MCP resolves). Critically, the agent never enqueues its own events — the control side owns every enqueue.

Operator chat. soa_send_message (agent→operator) and the operator's reply (which lands as an OperatorMessage event) form a non-blocking chat channel, persisted as the durable transcript and broadcast live to the agent's detail page.

Mission HITL (mission_ask_user). The mission family has its analog: a mission sub-agent can call mission_ask_user to pose a question that surfaces to the operator and feeds the answer back as refinement guidance the mission resumes from. It is the mission-side equivalent of the SOA's soa_propose_decision → OperatorAnsweredEscalation loop.

2.5 Operating modes, presets & call-sites

Operating modes shape what an agent focuses on and which tools it may use this episode. Each agent type has its own seeded mode catalogue (table-backed, in-code-seed fallback):

• SOA (six modes): Strategic (default), Incident, Dialogue, Housekeeping, Idle, Discovery.
• Compliance (three): Cadence (default), GateReview, Research.
• Prompt Engineer (one): Redact.

The agent cannot switch its own mode (rail R3/R7). The mode is written only by a human:

• the UI mode control (AgentControlService.SetActiveModeAsync / the per-type Compliance + redactor variants, source=ui), or
• the approval of a soa_propose_mode_change AttentionRequest (source=approval).

Both paths funnel through one chokepoint and append an audit row to agent_mode_change_events. The agent only ever proposes a switch.

Presets & call-sites. Every LLM call in Genesis is attributed to a named call-site in the static LlmSiteRegistry. The agent-relevant sites:

An operator binds a preset (a model+provider+backend+overlay bundle) to a call-site (llm_site_attach_preset / _detach_preset). A leaf site inherits its parent's family-default binding until pinned (e.g. Agent:Planning → Agent:Default). This is how you pin Compliance to a different model than the SOA without touching code. See §3.7 for resolution mechanics.

2.6 Dashboard pages

3. Architecture

3.1 The data model

Standing agents live entirely on per-tenant tables.

agent_instances — one row per agent instance (the SOA analog of a mission row):

agent_event_queue — the per-instance event log. Each row is one event with an event_kind, an optional JSON payload, a sequence_number, a visible_at (the authoritative due-gate), and a consumed marker (events are consumed, not deleted, so resume-dedup can see history). The AgentEventKind discriminator:

• AgentInitialized — first event for a fresh instance (drives the plan-then-greet opener).
• AgentTick — the self-scheduled heartbeat.
• OperatorMessage — an operator chat message to read next tick.
• OperatorAnsweredEscalation — an operator answered a decision the agent raised.
• MissionStateChanged / DecisionResolved / DependencyCompleted — orchestration signals (a steered mission changed status, a decision resolved, a dependency unblocked).
• ExternalSignalReceived — a generic agent-type-agnostic signal whose JSON payload carries an AgentSignalKind (NewCouple / GuidanceUpdated / RegressionDetected / HumanRequest). Used by the Prompt Engineer (Step 6 wires only HumanRequest); the SOA never receives it.

agent_state_ledger (+ agent_state_ledger_actions) — the append-only turn record. Each turn row carries the triggering event kind/payload, the AgentDecisionKind, the structured decision payload ({actions, waitCondition, reasoningSummary, activeMode}), the wait-condition, the reasoning summary, and a back-link to the LLM call snapshot (served model + cost). Inserts are lease-enforced. Per-action child rows normalise the actions the turn produced.

agent_modes — the per-type mode catalogue (name, description, prompt fragment, toolset-subset JSON, optional preset, optional budget override JSON, system-seed flag). agent_mode_change_events — the mode-change audit trail. agent_messages — the operator↔agent chat transcript (with direction).

AgentDecisionKind classifies each turn: Initialized, Heartbeat, MessageAcknowledged, EscalationResumed, NoOp (legacy), plus the planning-loop kinds Planned, ActedWithTool, WaitingForEvent, Escalated. It is additive-only (persisted as string; historical rows must keep classifying).

3.2 The dispatch model

The AgentDispatcher is a hosted BackgroundService that pumps standing agents. Its shape:

1. Gated by the standing-agents feature, at two levels. The dispatcher is hosted whenever the deploy level is on (services.core.features.standingAgents.enabled, historically the AgentDispatcher:Enabled env; deploy default on), but it only ticks a tenant whose tenant level is on — and the tenant default is off: each tenant opts in from Settings → Features (see Feature flags). On start it enumerates active tenants and fans out one polling loop per tenant. Newly added tenants need a pod restart to be picked up.
2. Per-tenant bootstrap. When AutoBootstrap=true, each tenant gets one singleton SOA instance ensured at startup (the schema does not enforce the singleton; the "one SOA per tenant" invariant lives in AgentControlService / the bootstrap caller). With StandingAgentsIdleByDefault=true it is created Active and seeded an AgentInitialized event (so it runs its plan-then-greet opener immediately, then idles); otherwise it is created Paused, awaiting an operator start. On first creation the instance also enters the foundational phase (§3.6).
3. Polling cycle. Every PollingInterval (default 5 s) the dispatcher opens a per-cycle DI scope under an ambient tenant scope, lists instances "needing attention", and processes up to MaxConcurrentInstancesPerTenant (default 4) of them.
4. Per-instance processing is lease-bounded and runs through the shared tick supervisor (next section).
5. Error isolation at cycle and instance level — one bad instance or cycle never stops the loop.

The body to run is resolved per instance by AgentType via keyed DI (AgentType.Soa → AgentAgent; AgentType.Compliance → also AgentAgent but with the Compliance policy; PromptRedactor → PromptRedactorAgent). This is how one dispatcher serves every standing type.

Two execution regimes, one code path. A single config flag, AgentDispatcher:EphemeralPod, picks the regime:

• Warm (default, EphemeralPod=false) — the in-process poll loop ticks instances directly. KeepWarm == !EphemeralPod.
• Ephemeral pod (EphemeralPod=true) — the in-core pump stops ticking instances in-proc; KEDA-spawned agent pods pull ticks over the /mcp/agent endpoint via agent_tick_claim / agent_tick_complete. Bootstrap and event-seeding still run in-core; only per-instance ticking moves to the pods.

Both regimes drive ticks through the same AgentTickSupervisor primitives, so persistence, heartbeat, and STUCK logic are byte-identical whichever runs.

3.3 Tick scheduling: claim → run → complete

AgentTickSupervisor factors the lease + queue + passivation primitives so the warm dispatcher and the pod runner share them exactly.

ClaimTickAsync:

1. Acquire the per-instance CAS lease for a fresh sessionId (skip if held by another session → null).
2. Dequeue the next due event (visible_at <= now). If none is due, seed a heartbeat AgentTick if none is pending (first beat / chain recovery), release the lease, and return null.
3. Read the pre-tick instance snapshot (the idle/STUCK counters key on it) and return a TickClaim.

CompleteTickAsync is the single passivation writer — exactly one place writes phase/next-tick/counters per tick:

1. Session-guard the write — re-read the instance and confirm the lease is still held by this session (a pod whose lease expired mid-run must not clobber). If lost, skip the write and return.
2. Derive the decision kind/phase (warm path passes the agent's already-decided kind/phase straight through, so the persisted value is byte-identical; the pod path lets the supervisor re-derive from the raw outcome via the shared AgentDecisionMapper).
3. Idle detection — a tick is idle when it was an AgentTick whose PlanInputHash matches the prior tick's. consecutive_idle_ticks increments on idle, resets otherwise.
4. STUCK guard — a genuine PhaseBlocked (the planner returned blocked, mapped to WaitingForEvent with phase idle:blocked) increments consecutive_blocked_turns. The counter is always persisted; the halt only fires when enforceStuckGuard=true (the pod path). On halt at MaxConsecutiveBlockedTurns (default 3) the instance is set Closed, the heartbeat is suppressed (so the queue drains and KEDA scales to zero), and an operator AttentionRequest is surfaced. The warm path never halts (preserving legacy behaviour).
5. Maintain exactly one heartbeat — unless halting, enqueue a single future AgentTick at next_tick_at if none is pending.
6. Surface the instance on /agents (warm only), write the single passivation update, push the turn live over SignalR (warm only), and release the lease in finally.

ComputeNextHeartbeatDelay sets the cadence:

• When StandingAgentIdleHeartbeatEnabled=true (default), the next heartbeat is a flat StandingAgentHeartbeatInterval (default 24 h) — a slow daily check-in that is immune to telemetry jitter. So an agent goes quiet right after its opening greeting and stays quiet until a real event.
• Otherwise it falls back to geometric idle backoff (ComputeTickDelay): base · BackoffFactor^priorIdle, capped at MaxBackoffInterval (default 30 min). This only ever engages on unchanged inputs.

Either way, real events bypass the cadence entirely — operator messages and answered escalations enqueue with visible_at = now and wake the agent on the next cycle.

This is the "standing vs bursty" distinction in practice: standing agents (SOA, Compliance) settle to the slow flat heartbeat and react to events; bursty agents (Prompt Engineer) are never dispatcher-bootstrapped — they are created Paused on a binding/signal and ticked only once activated.

3.4 The per-tick planning loop (AgentAgent)

AgentAgent is the shared plan-then-act body for every standing planning agent. Per tick it does not touch leases or the event queue (the dispatcher owns those); it only re-injects, plans, and records. The sequence:

1. Re-inject — load the recent turn tail (last 12 turns) for continuity across ticks / pod restarts.
2. Ops digest — probe "ARDS-self" operational health (DB deadlocks/rollbacks, error-rate spikes, firing alerts) via IOpsDigestProbe, bucketed into the plan-input hash so a real incident flips the bucket and forces a re-plan.
3. Load the instance — needed for both the short-circuit and the mode resolution. If the read fails, the tick aborts cleanly (it cannot safely resolve mode/type) and retries next tick.
4. B1 no-op short-circuit — compute a SHA-256 PlanInputHash over the external drivers only (event kind + payload + bucketed ops digest; the agent's own ever-changing reasoning tail is deliberately excluded). If the hash matches the last tick's and a forced re-plan isn't due, skip the LLM call entirely and idle. A safety valve (ForcedReplanEveryNIdleTicks, default 20) forces a real re-plan periodically to catch drift. This is the lever that stops idle agents re-planning every 30 s and burning spend.
5. Per-event preamble — steer by what triggered the tick: AgentInitialized → survey + post a short grounded greeting then idle; OperatorMessage → read and reply; OperatorAnsweredEscalation → resume incorporating the answer; AgentTick → baseline.
6. Open-items roster — the missions this agent already created + the escalations it raised (linked via a JSONB soaInstanceId metadata helper, index-served). Injected at the top of the objective so the model grounds against in-flight work before proposing — the direct lever on duplicate proposals.
7. Resolve the active mode — read active_mode (default per type), look it up in the seeded catalogue, and assert its toolset ⊆ the §3 superset fail-closed (the resolver throws if a mode would grant an out-of-membership tool — there is no [Authorize] backstop on the warm path). The resolved mode's toolset becomes both the invoker's authorized tools and the objective's advertised action menu; its prompt fragment is appended to the invariant base.
8. (Compliance only) cold-sweep corpus discovery — resolve the tenant's compliance project id(s) so the objective can name the corpus to query.
9. Credit gate (B-iii) — resolve the tenant's weekly agent-planning credit window (default $60/wk). When CreditEnforcementEnabled and the pool is exhausted, skip the LLM call and idle until regen; otherwise meter the drawdown.
10. Plan — one provenance-recorded LLM call through ISubAgentInvoker (§3.5), with the mode's toolset as the authorized tool surface and the resolved per-tick budget (§3.6).
11. Map the outcome — histogram-driven precedence (raised an escalation → Escalated; took any side-effecting action → ActedWithTool; else clean completion → Planned/MessageAcknowledged/EscalationResumed by event; else blocked → WaitingForEvent). The ladder lives in the shared AgentDecisionMapper so warm and pod map identically.
12. Record the append-only ledger turn (with the back-linked provenance snapshot) and return the AgentDecision — the dispatcher persists the phase, schedules the next tick, and releases the lease.

A "burst" is therefore a sequence of these ticks: the first (AgentInitialized) greets and idles; subsequent ticks fire on the flat heartbeat or on injected events; within a single tick the invoker runs a bounded multi-turn agentic loop (the "episode") that may query memory/telemetry then emit one or two proposals before terminating.

3.5 How agents do LLM calls (the in-process pipeline)

Agents reason through SubAgentInvoker — the codebase's manual agentic loop, deliberately not the SDK auto-invoke path, because it must observe the loop boundary every turn (budget enforcement, named-tool termination, per-turn provenance, dispatch-failure policy).

Each invocation takes a SubAgentRequest carrying the parent entity id (the agent instance), the AgentType, a phase kind (the agent uses a findings-only Research phase so no mission proposal batch is opened), the preset site key (Agent:Planning / Agent:Compliance, resolved from the agent's IPlanningAgentPolicy), the objective payload, the budget envelope, the authorized MCP tools (the active mode's toolset), an invocation id, and the mode's system-prompt suffix. It also carries cost-attribution hooks (OwnerAgentInstanceId, QuotaWindowId) and the foundational per-turn output-token override.

The loop body: seed messages → while not terminated: check budget → resolve the (model, provider, backend) couple from the preset/site (see §3.7) → call the LLM via a Microsoft.Extensions.AI IChatClient → write an LlmCallSnapshot (tagged AgentPlanning, keyed by invocation id) → update consumption → dispatch each FunctionCallContent through its typed MCP handler → react. The load-bearing rule (§1.1): the tool call is the commit; response text is reasoning trace and is never parsed for state. Termination is by named control-plane tool (phase_complete / phase_blocked), not by interpreting prose; if a turn emits zero tool calls the loop appends a synthetic nudge to terminate.

Fallback & provenance. The invoker drives the preset's fallback chain — within-provider credential failover first (e.g. an OAuth-Max 429 → the lower-priority API key), then provider advance — emitting OpenTelemetry spans and counters (subagent.llm_call.fallback_advance, …all_providers_exhausted, etc.). Each attempt records a CallAttempt against the snapshot, with served-vs-requested model and cost computed Core-side through the canonical pricing path (the agent never self-reports cost). AgentAgent then back-links the latest snapshot id onto the ledger turn so the dashboard shows served model + cost per turn.

Overlays are part of the resolved preset — a prompt overlay (and routing-chain / tool-policy / sampling / limits profiles) bound to the site. The mode's prompt fragment is appended to the invariant base system prompt inside the invoker (base + "\n\n" + fragment), keeping the base mode-invariant.

Out-of-process parity (pod path). When EphemeralPod=true the programmatic agent runner has no in-proc invoker, so AgentPodMcpTools ports the exact two-step provenance onto the agent surface: agent_record_call_attempt mints the AgentPlanning snapshot + terminal attempt so the dashboards light up identically. The pod tick itself runs agent_tick_claim → (substrate turn) → agent_tick_complete, with the supervisor doing the single passivation write server-side.

3.6 Per-tick budgets

AgentTickBudgetResolver is the single source of truth for a standing agent's per-tick budget envelope. Each axis reads the DB config layer first (the AgentDispatcher:Tick* keys in system_configs), falling back to the AgentDispatcherOptions value (appsettings/env, itself defaulting to the code default). The DB-first read is what makes the caps operator-tunable live — a write via the Settings UI / config_set takes effect on the very next tick, no restart.

The envelope (SOA defaults, all config-overridable):

AgentAgent.ResolveTickBudget layers three sources, in precedence:

1. Foundational phase first. While is_building_starting_workset is set and within workset_deadline_utc, every axis is lifted to Unlimited and the per-turn output cap rises to FoundationalMaxOutputTokensPerTurn (default 16,384) — so a brand-new agent can build its one-time starting workset (its baseline knowledge / dossier corpus) unthrottled. The agent ends the phase by calling the agent_workset_complete control terminator; the deadline (default now + 24 h) self-heals it if the terminator is never called. The weekly dollar ceiling stays in force throughout as the runaway-cost backstop. The exemption is universal — it lives on the shared AgentAgent seam, so it applies to every standing type.
2. Mode override. A mode may carry a BudgetJson override (e.g. Compliance Research widens to 48k tokens / 24 tool-calls / 600 s / $4.00 / 24 turns for whole-chapter dossier authoring) — applied only to that mode, never widening the shared default.
3. Policy default — the IPlanningAgentPolicy.TickBudget (read live from options each access).

3.7 Resolving the (model, provider) couple

Every agent LLM call is attributed to a call-site in the static LlmSiteRegistry (each LlmCallSite carries a SiteId, display name, a default model, supported backends, default allowed/denied tools, and the catalog axes — category, the track boundary it belongs to, dispatch mode, default routing-chain/tool-policy/overlay ids). The agent sites are Agent:Default, Agent:Planning, Agent:Compliance, PromptRedactor:Default, PromptRedactor:Redact, and Agent:Pod.

Resolution at the invoker:

1. The agent's policy supplies the preset site key (SOA → Agent:Planning; Compliance → Agent:Compliance).
2. The provider resolver looks up the site-attached preset (llm_site_attach_preset binding). If the leaf site has none, it walks the parent chain (GetParentSiteId: Agent:Planning → Agent:Default; Agent:Compliance → Agent:Default; PromptRedactor:Redact → PromptRedactor:Default) and uses the family-default binding (LLM.Agent:Default.Preset). A default seeder seeds an initial binding so resolution lands a real preset rather than the legacy [synthetic, anthropic] tail.
3. The resolved preset yields the concrete (model, provider, backend) couple plus its fallback chain and any attached overlays/profiles. The invoker tries each couple in order (credential failover within a provider before advancing).

So "which model does the SOA think with" is answered by: the preset bound to Agent:Planning (or inherited from Agent:Default), pinned live by an operator via llm_site_attach_preset — no code change, effective on the next tick. The current code default for the agent family is claude-opus-4-8.

The Agent:Pod deny-list on that site is advisory only (a tools/list trim). The authoritative boundary for the remote agent-pod surface is the class gate: AgentPodMcpTools is the only class an agent token can reach (it satisfies AgentPodPolicy and nothing else), and every dangerous tool (decision_respond, *_approve, config_set, llm_* mutations, constitution_*, project_delete, gitlab_* writes, coder_spawn, modification_apply, browser_*) lives in a class gated by a policy the agent token fails. The deny-list enumerates each member explicitly because tool filtering matches exact names (no glob).

3.8 The tool/governance rail

The set of tools a standing agent can ever reach on the warm path is the §3 tool superset (AgentModeCatalog.ToolSuperset), and a mode's toolset is always a strict subset (asserted fail-closed). Every superset member is either read-only (soa_query_telemetry, agent_query_memory, intelligence_knowledge_query, intelligence_code_search, compliance_query_posture, compliance_knowledge_query, orchestrator_research_get, compliance_dossier_list) or artifact-record (compliance_dossier_record / _translate, compliance_knowledge_ingest, orchestrator_research_create) or a human-gated escalation/control verb (soa_propose_decision, soa_send_message, soa_propose_mode_change, agent_workset_complete).

The one self-applying tenant mutation — soa_propose_task (governance-gated mission-create) — is in the superset for the SOA only. The machine-guarded SelfApplyingTools deny-list asserts that no Compliance (or Prompt Engineer) mode toolset ever contains it: those agents can escalate to a human but can never self-apply a change. This "never self-applies" rail is enforced in code (a test asserts the superset contains no self-applying tool beyond the SOA's, and that Compliance modes exclude it), not just documented.

The action handlers themselves keep their governance gates intact regardless of surface (warm in-process or pod): soa_propose_task runs constitution + boundary checks before persisting; soa_propose_decision / soa_send_message / soa_propose_mode_change run constitution on their content. A violation is block-but-feed-back (returned to the model as a structured { blockedReason, violations }, never thrown), so the agent can reconsider within the same episode.

3.9 Lifecycle & control

AgentControlService owns every operator action and every enqueue (the agent never enqueues):

• Start / Stop / Reset (SOA) and StartCompliance / StopCompliance — flip status Active↔Paused, seeding an AgentInitialized event on start. Reset additionally clears the ledger memory, drains stale events, and re-seeds a fresh opener (refusing if a tick is mid-flight, to protect the single-passivation-writer invariant).
• Operator chat — persist the message (durable transcript), enqueue an OperatorMessage event, broadcast live.
• Mode control — the UI set (source=ui) and the approval chokepoint (source=approval), each validating the target against the agent's own catalogue and auditing the change.
• Escalation round-trip — on an operator resolving a SOA-origin AttentionRequest, apply any approved mode change, then enqueue the OperatorAnsweredEscalation resume (idempotent via the resume-dedup index).
• Prompt Engineer signals — RaiseRedactorSignalAsync ensure-creates the Paused call-site-bound redactor instance and enqueues an ExternalSignalReceived event (ships dark — durably queued but not ticked until the redactor body is activated).

The agent registry (AgentRegistryService) is the separate in-memory coordination directory: tenant-partitioned, thread-safe, heartbeat-expired (5 min), surfacing registry agents (including the SOA's self-registration) on /agents. It is ephemeral — re-populated after a pod restart — and strictly tenant-isolated.

4. Putting it together: a standing agent's life

1. Bootstrap. The dispatcher ensures one SOA per tenant. With idle-by-default on, it is created Active, enters the foundational phase (unthrottled per-tick, weekly $ ceiling still enforced), and is seeded AgentInitialized.
2. Opener. The first tick surveys context and posts a short grounded greeting (soa_send_message), then schedules the next heartbeat ~24 h out and goes quiet.
3. Foundation. Over the next ticks (unthrottled) it builds its starting workset, then calls agent_workset_complete to revert to the normal per-tick budget (or the deadline self-heals it).
4. Steady state. It idles on the flat daily heartbeat. Each heartbeat: probe ops health, hash the external inputs, and short-circuit without an LLM call if nothing changed.
5. React. A real event — an operator message, an answered escalation, a mission state change, an incident flipping the ops bucket — enqueues with visible_at = now, wakes the agent immediately, and forces a re-plan. Within that tick the invoker runs a bounded episode: query memory/telemetry to ground, then take at most one or two governed actions (propose a mission, escalate a decision, send a message), never duplicating something already on the open-items roster, then phase_complete.
6. Human gate. Any genuine fork becomes an AttentionRequest on the decision queue; the operator's answer comes back as OperatorAnsweredEscalation and the agent resumes.
7. Modes. A human (UI or approval) can switch the agent's focus — Strategic/Incident/Discovery/… for the SOA, Cadence/GateReview/Research for Compliance — narrowing or widening its tool surface and budget per episode. The agent can only propose a switch.
8. Safety. If a pod-path agent gets wedged (MaxConsecutiveBlockedTurns consecutive blocks) it halts to Closed, drains its queue (KEDA scales to zero), and surfaces an operator AttentionRequest.

Missions & Tasks

What it is

The execution backbone. A mission is a single deliverable that Genesis plans, decomposes into tasks, and runs to completion; a task is the atomic unit an agent or coder executes. Human approval gates inside the pipeline surface as decisions.

Operator surface

MCP tools cover the full lifecycle:

• Mission lifecycle — mission_create, mission_get, mission_list, mission_decompose, mission_status, mission_pipeline_status.
• Task review & approval — mission_tasks_list, mission_tasks_approve / mission_approve_tasks, mission_task_add.
• Task-level control — task_create, task_get, task_list, task_update, task_retry, task_reset_retry, task_cancel, task_delete.
• Decisions (human approval gates) — decision_list, decision_get, decision_respond, decision_acknowledge, decision_bulk_acknowledge, decision_stats.
• Runs & changements (acceptance layer) — mission_run_start, mission_run_get, mission_run_accept, mission_run_discard, mission_revert_preview, mission_revert, mission_changement_stack. See Workflows §2.13 for the full run/accept/revert model.

The REST surface is MissionsController / TasksController / DecisionsController, and missions render on the dashboard mission pages.

How it works

A mission moves through Pending → Planning (decomposition) → InProgress → PendingReview → Completed / Failed, with Paused as a resumable side state and Cancelled as an early exit; Completed, Failed, and Cancelled are terminal. The Mission entity records its track, kind, project / matter linkage, token / cost rollups, selected model / provider, and integration-branch metadata. A mission's plan can come from LLM decomposition or from a published Workflow compiled into it — the lifecycle above is the same either way; only the plan's source varies.

Decomposition is LLM-driven and resolves the Missions:Decomposition site preset — which may route to a containerized coder that adds tasks via mission_task_add. Tasks (TaskDefinition + TaskEvent) are dispatched to agents / coders, and gate steps pause behind pending Decision rows resolved with decision_respond (approve / skip / fail). Mission and task state changes flow through an event queue (MissionEventQueue) consumed by the agent dispatcher.

Illegal status transitions are refused, not silently ignored. The Mission aggregate owns which transitions are legal, so asking for one it does not allow (e.g. Failed → InProgress, or any change out of a terminal status) is rejected rather than dropped into a no-op success. Over REST the status endpoint returns 409 with code mission.status.invalid-transition and a body carrying currentStatus, requestedStatus, and legalTransitions; the mission_status MCP tool returns a structured INVALID_STATE_TRANSITION error with the same three fields — so an agent or operator learns what it may do instead of receiving a success for a change that never applied. The legal-transition list is derived from the aggregate's own guards, so it cannot drift from the real rules.

Completed is terminal, with exactly one sanctioned exit: starting a fresh run on a completed mission reopens it to InProgress via an explicit reopen intent (ReopenForRun). The generic status-update path still refuses Completed → InProgress; reopening for a run is the only way a mission leaves Completed.

Missions are the substrate that Workflows compile into and that Agents drive; see those guides for the orchestration internals.

Run artifacts

A run artifact is something a workflow run produced that a person can look at — a built web application or an Android APK — rendered inside the conversation that owns the mission, with a durable identity that outlives any single viewing session. The run builds the thing; Genesis serves it on our own infrastructure and streams pixels to the operator's browser, so the operator's clicks are real clicks on the running app while its code never reaches their machine.

Run artifacts are per-tenant: every tool and endpoint is gated by the tenant-admin policy, and tenancy is implicit via the per-tenant database (no TenantId column — ADR-008), exactly like missions, tasks and workflows. The record lives in the owning tenant's database, so an id minted for one tenant is structurally invisible to another.

This page covers both surfaces:

• Operator / product — what an artifact is, the two kinds, live-vs-durable, the visibility model, and the isolation boundary as it actually is today.
• Architecture — the record, how a run's build becomes a servable target, the capture pipeline, the read-only/single-writer render session, and the tool surface.

Status (2026-08): staging-only, default-off. The whole surface is behind Artifacts:Enabled (default off) and the interactive render session behind Features:OperatorBrowseInputLock (default off). The isolation caveat below is load-bearing — read it before enabling anything.

1. Operator guide

1.1 What an artifact is

1.2 Live vs durable

A live render session cannot be kept forever, so the stable identity must survive it. Reopening an artifact after its session has died shows its captures, not an error, and offers to respawn if the build is still available. A link viewer only ever sees captures — never an input-capable session.

1.3 The interactive session

The authorised operator attaches interactive by default — real keyboard and mouse into the running app. Additional viewers of the same session attach read-only, and a read-only attach looks read-only: their input is dropped at the broker while pixels keep flowing. Input is single-writer — exactly one attached viewer holds the input lock at a time; handing it over is explicit, and two people never drive the same session simultaneously. The in-pod browser is pinned to the served app's origin: a navigation off that origin is blocked and shown to the operator as a refusal, never silently followed.

1.4 Making an artifact reachable by a link is a write

Producing an artifact is a run side-effect and needs no new approval. Enabling Link visibility is a boundary crossing: it is write-classified, gated, and recorded (who enabled it and when). An automated identity is refused — exactly as decision_respond refuses one on a governance change; only an authenticated human may open a link.

1.5 The isolation boundary — read this

Within a tenant, a preview artifact (model-written code) and that tenant's client test environments share the render boundary. That is deliberate: a tenant is one customer's data domain.

The per-tenant boundary is NOT enforced at the network layer on the current substrate. The render pool is one cluster-shared instance, and both clusters run a CNI (Flannel) that ships no NetworkPolicy engine — so the network policies that exist are inert. Measured from inside the render pod, untrusted build output can reach the Genesis core API, Postgres, Keycloak, the git mirror, the MCP endpoint and another tenant's services; the app-layer auth (MCP/API tokens, DB credentials) still holds, but the network does not. The origin-pin stops an operator click from becoming an off-origin request; it does not stop the served app's own on-load fetches from reaching internal services.

This is why the feature is staging-only and default-off. It is bounded there by five properties — no content (a structural clone, no client repos / real tenant data / real identities), a single operator, flag-off, no credential path to prod, and no private network path to prod. The precondition for any prod or multi-tenant use is a policy-capable CNI (Cilium/Calico) plus pool hardening (authenticated noVNC ports, browser_run_spec/eval gated, no mounted service-account token, per-tenant render namespaces). That gap is recorded as a compliance gap, not carried silently by the feature flag.

If the app under test can reach anything stateful, an operator's clicks cause real writes — visible before they click, not discovered after.

2. Architecture

2.1 The record

RunArtifact (tenant DB, run_artifacts) carries: the artifact StringId; MissionId / RunId / TaskDefId / NodeId provenance; Kind / Visibility / SessionState (string-persisted so a third kind needs no migration); the link fields (LinkToken, expiry, enabled-by/at); the build reference (BuildRef, branch, sha, tenant slug, environment id — enough to respawn); the capture set (CaptureSetHash + an ordered CaptureManifestJson); and the current session handle when one is live. Uniqueness is (RunId, NodeId) NULLS NOT DISTINCT — one artifact per produced node. EnvironmentId is a plain string, not a foreign key: the environment record lives in the control-plane database.

The record is the missing producer for a consumer that was already shipped fail-closed: RunTargetProvisioner.ResolveRunArtifactRef now does a true lookup of the build a run produced instead of deriving one from an operator template.

2.2 From build to served target

There is no image build in Genesis core — the path is git-clone plus an ArgoCD-rendered environment. A WebApp is served by a serve mode of the run-built-target chart: the run branch is cloned into an ephemeral pod that builds and serves the app on a port; BuildRef is that in-cluster service URL. The browser pool leases a session, navigates to it, and streams headed Chrome over noVNC — the same brokering path the emulator/APK kind uses. The serve pod keeps a hardened posture (no mounted service-account token, non-root, seccomp, all capabilities dropped).

2.3 Captures

Captures are pixels, not code. A still is persisted through the attachment service (base64 in Postgres — there is no object store yet, so a "screencast" is a bounded sequence of stills, not video), appended to the ordered manifest, and fingerprinted by a stable SHA-256 over the ordered attachment ids. They are served through a dedicated endpoint that forces image/png — captured HTML/JS is never served as an active document from a trusted origin.

2.4 The render session

The pixel broker is the operator-browse VNC proxy. For a read-only viewer, a stateful RFB message-framing filter drops whole input messages (key/pointer/clipboard) while forwarding display messages, and fails closed on anything it cannot frame. Who may write is a core-authoritative input lock streamed to the broker; the broker caches the holder locally and treats itself as read-only if the lock stream drops or goes stale (> 2 s). The enforcement is gated by Features:OperatorBrowseInputLock (default off — the legacy verbatim proxy when off).

2.5 Tool surface

Read-only MCP: artifact_list (by mission or run), artifact_get (metadata + capture URLs), and artifact_show (emit the render block into the conversation so the card renders inline). All are tenant-admin, gated by Artifacts:Enabled, and born attributed. Link publication is deliberately not an MCP tool — it is a human action behind the decision chokepoint.

2.6 What is not implemented

Serving artifact HTML to a human's own browser (a different, origin-isolation security model); editing, versioning or diffing artifacts; and video screencasts (deferred until an object store exists). The per-tenant network boundary (see §1.5) is the load-bearing prerequisite for prod.

Charters & Matters

What it is

The strategic layer above missions. A Charter is a long-running initiative — a Vision with acceptance criteria and excluded scope. A Matter is a strategic epic under a Charter that groups related missions.

Operator surface

Read-mostly from MCP:

• charter_get — Vision + acceptance criteria.
• matter_get — epic detail with its parent Charter and linked missions.
• matter_progress — total / completed / failed missions + a health ratio.
• matter_register / matter_list — register and list epics.

The dashboard exposes a strategy / roadmap view, and StrategyController serves the read APIs.

How it works

CharterRecord owns a collection of MatterRecords (ordered via ExecutionOrder / SortOrder), and missions reference their MatterId. Charters also carry integration-branch and affected-repository metadata so a whole initiative can land on a target branch. The MatterPipelineService and MatterVerificationService drive epics forward and verify their acceptance criteria, while StrategyRepository is the read/write data accessor. Charters and matters live in the tenant database and are managed by tenant admins.

Dialogue (Conversations)

What it is

Strategic, multi-turn conversations with the model that double as the main on-ramp for turning an idea into approved work. A conversation can read the system's live state and, when you ask it to act, either propose work for your approval or — with the write tier enabled — take a bounded action.

Operator surface

• conversation_create, conversation_send, conversation_list, conversation_get, conversation_complete — the conversation lifecycle. Each conversation is tagged with a Track (Governance / Research / Planning / Build) for context.
• conversation_branch — fork a conversation to explore an alternative.
• mission_propose — the current bridge into execution. On a turn where you ask for a feature or a change, the model calls this (instead of describing the work in prose) to raise one approval request. It creates an unpublished workflow draft plus a single Approval attention request that lands in the Decisions queue — no live mission and no published workflow. You review and approve — and approval then creates the mission automatically (see below).
• dialogue_propose_mission — the older, simpler bridge, still present: it creates a pending mission directly, linked to the conversation, for you to approve. No workflow draft is attached.
• dialogue_check_mission, dialogue_get_mission_results — track a proposal, and pull a completed mission's task outcomes back into the conversation to synthesise a reply.

DialogueController and ConversationExportController back the REST / dashboard chat surface.

How it works

Conversations are stored as Conversation + ConversationMessage rows, tagged with their Track. Model calls made during a conversation route through the LLM layer under their own dialogue call site (e.g. Dialogue:GeneralDialogue, Dialogue:MissionAssistant) and are cost-attributed to the conversation. Anything the model creates carries the originating conversation id (OriginConversationId), so a proposal or a mission is always traceable back to the dialogue that spawned it. Dialogue can run against an in-process direct model provider or a sidecar, depending on the resolved preset and backend.

What the model is allowed to do (tool tiers)

The tools a conversation can call are tiered by how much they can change. By default Core serves them in-process (no separate Bridge process required):

• Read tier — always available. Status, list, and get tools (missions, tasks, decisions, costs, pipelines, …) run directly. A few read-named tools that actually fan out to expert or model calls — and so cost money — are held back until an operator opts in.
• Act / write tier — off by default, twice gated. A curated allowlist of create/update tools (mission_create, task_create, decision_create, mission_add_task, …) is served only when a deployment-level switch (Dialogue:InProcessTools:WriteEnabled) admits it. Even then a tool runs only when the tenant has turned write tools on (a toggle on the Features settings screen — the refusal message points there) and you explicitly asked for the action (an execution-command intent) or a live session grant authorises it. On an ordinary feature-request turn it does not execute — the model surfaces the proposed action and a suggestion is recorded instead. The dispose verbs (*_approve / *_reject / *_respond / *_promote) are excluded outright, so a conversation can never approve or resolve a human-gated item — including its own proposals.
• Propose tier — mission_propose. Served under the same deployment switch as the write tier, so on a deployment with write tools off you will not see it at all. What proposing skips is the execution gating: it mutates nothing directly (it only raises an approval request), so neither the per-tenant toggle nor the explicit-intent check applies — even a plain feature-request turn is allowed to propose. The system proposes; the human disposes.

What approving a proposal does — and doesn't

The proposal lands in the Decisions queue carrying the proposed mission spec and a handle to the unpublished workflow draft, with three options: Approve and create, Request changes, Reject. Choose Approve and create and the mission is created for you: a resolution handler watches for the approval and materialises the mission through the same path mission_create uses — no manual re-entry, and exactly one mission per proposal even if the approval fires twice.

What approval deliberately does not do is publish (or attach) the workflow draft. If the model could not sketch an execution plan, the draft is a placeholder graph that would fail publish validation — so the draft always stays a draft for you to review, complete, and publish yourself. In short: approving creates the mission automatically; publishing the workflow remains your deliberate act.

If a feature request never reaches a formal proposal, the conversation still records a suggestion (a MissionSuggestionRecord row) tied to the conversation, so the idea is captured for later review rather than lost.

Compliance

What it is

Continuous regulatory posture management. Assess a project against frameworks (DORA, CRA, PLD, NIST CSF, ISO 27001, SOC 2, GDPR, HIPAA, NIS2, EU AI Act, and more), track gaps, manage incidents and SBOM / vulnerabilities, and generate evidence dossiers. A standing Compliance agent sweeps this posture autonomously.

Operator surface

• Assessment & reporting — compliance_status, compliance_assess (re-evaluate frameworks and persist scores + gaps), compliance_assessment_history, compliance_requirements, compliance_gaps / compliance_gap_create, compliance_frameworks, compliance_mappings, compliance_market_readiness.
• Catalogue customization — compliance_catalogue_list plus control / requirement create, override, disable, and clear-override tools.
• Incidents — incident_create, incident_classify, incident_timeline_submit, incident_close, incident_overdue.
• Supply chain — sbom_latest, sbom_import, vulnerability_list / vulnerability_record, compliance_documents / compliance_document_upload.

REST lives in ComplianceController, ComplianceCatalogueController, IncidentController, RegulatoryDossierController, and DossierController.

How it works

The requirement / control catalog and cross-framework control mappings live in the control plane (ComplianceRequirements, ComplianceControls, ComplianceControlMappings) and are resolved per tenant with overrides. Assessments persist as ComplianceAssessmentRunRecord → ComplianceAssessmentItemRecord rows with ComplianceGapRecord and ComplianceEvidenceRecord. Assessment can invoke LLM-driven rule checks under the Compliance:Assessment site preset.

Catalogue changes proposed by the Compliance agent (compliance_catalogue_propose_delta) never write the catalog directly: each delta lands in the Decisions queue as a ratification request that a different human must approve — the proposer can never be the approver. On approval the delta is applied to the governing catalog and every dossier that depends on it is flagged stale; re-rendering a stale dossier stays an explicit human action.

Incidents, SBOM snapshots / components, third-party providers, dossier entries, and report snapshots are all tenant-scoped and feed exportable, optionally bilingual (EN / FR) compliance reports and dossiers. The same control catalog backs the Workflows compliance overlay (materialize / waivers / publish floor).