Ground a session

This tutorial builds the habit that pays across everything else on the platform: packaging the context for an effort once, so every agent session that touches it starts briefed instead of spending its first stretch re-discovering the project. You author a context artifact, attach a small knowledge graph to it, ground a live session with it, verify the grounding actually took, and iterate the artifact as the effort evolves.

The scenario: an effort that will outlive one session — say, a website revamp. It has a goal, a few decisions already made, a handful of files that matter, and it will be worked by you and by agents over days. Exactly the case where re-explaining yourself every session is the hidden cost.

Prerequisites

• The quickstart tour — you have opened Terminals and launched an agent pane before.
• The mental model: Context artifacts & grounding.
• A real effort with a few real files in your workspace — the tutorial works with placeholders, but the verification step is only convincing with content that means something to you.
• Context Artifacts and Terminals are Pro surfaces — see Tiers: Pro & Ultra.
• Costs: authoring and attaching cost nothing. The grounded session is an agent session on your own subscription. Graph depths have their own cost profile — stated at that step.

Step 1 — Author the artifact

Open Context Artifacts (sidebar ▸ Data) and create an artifact. Give it a clear name — sessions will be grounded with it by that name.

Work in Visual mode, the structured builder:

1. Write a one-line description and the freeform notes: the goal, the decisions already made, the constraints, the vocabulary. Write it as the briefing you would otherwise repeat.
2. Add file references — individual files or whole folders. You can also drag a file straight from your file manager onto the artifact.

You should see: edits save automatically as you type — there is no save button. Switch to Raw mode once to see what you actually built: the artifact is plain Markdown, nothing hidden behind the UI. It lives as a file under documents/context-artifacts/ in your workspace, which means your agents can read and even maintain it, and any outside edit shows up in the view automatically.

Step 2 — Attach a knowledge graph (optional, choose the depth)

Switch to KG mode to bundle a purpose-built graph with the artifact, built from its file references. Pick the build depth — the same three choices as everywhere in the platform:

Choose Structure only for this walk — it is a complete, useful state, not a stub, and it costs nothing. The choice is recorded on the artifact and tracks reality: enriching the graph later moves the badge on its own.

You should see: the attached graph appear in Cortex like any other workspace. The same documents stay single nodes in the one knowledge graph — attaching them here duplicates nothing.

Step 3 — Preview what the agent will receive

Before trusting the artifact with real work, open its preview: the exact materialized fragment a grounded session would be handed — notes, resolved file references, and graph pointer included.

You should see: something that reads like a good briefing. If it does, the grounding will too. This is also the fastest way to catch a stale reference or a note that no longer applies — fix it now, in the artifact, not later in a session.

Step 4 — Attach where sessions launch

Switch to the Terminals view. Context attaches at two levels:

• Workspace-level — the artifact becomes the default context for every agent pane in that terminal workspace. The right move for a fleet or a standing effort: attach the briefing once, every session there inherits it.
• Pane-level — context for one specialist session, layered on top of the workspace default. A session's effective context is the union of both, deduplicated.

Attach your artifact at the workspace level for this walk.

You should see: back in the Context Artifacts view, the artifact now shows an "attached in" marker for that terminal workspace, with a jump straight to it.

The shortcut, for when you do not want a standing attachment. The launch dialog has a Global context field of its own — optional, injected at launch, inherited by every terminal in the new workspace. Picking your artifact there grounds one launch without making it that workspace's default, and the picker takes plain file paths as well as artifacts. It is the same channel and the same resolved fragment; the only difference is whether the attachment outlives the launch. Use the workspace-level attach for a standing effort, the launch field for a one-shot.

Step 5 — Spawn a grounded session

In the workspace you attached to, add an agent pane — or launch a workspace fresh with agent panes, which is where the rest of the spawn controls live: how many terminals, what each one runs, the model and reasoning effort, whether the session asks before tool calls, and the working folder.

You should see: a full, interactive agent session start in a visible pane. It is a grounded session because the artifact was injected at launch — and only the context was injected: the session keeps all of its own tools, model settings, and permissions. Grounding changes what it knows at start, not what it can do.

Step 5b — Or have it start working by itself

The launch dialog's last field is a First message, delivered once the session is ready. It is what turns a grounded workspace into a working one: with nothing to send, the terminals come up briefed and then wait at an idle prompt.

Put the verification question from step 6 in it, targeted at All terminals, and the session answers before you have touched the keyboard. (Don't send is the other choice, and it is the right one when you want to read the pane first.)

Step 6 — Verify the grounding

Type into the pane and ask the session to play its briefing back — or read the answer the first message already produced:

Before we start: summarize what you understand this effort to be,
what has already been decided, and which files you plan to consult.

You should see: an answer that mirrors your artifact — the goal, the decisions, and your file references, named without any searching or directory exploration first. If the session instead starts exploring to orient itself, the grounding is thin: go back to step 1 and sharpen the notes or the references. The preview from step 3 is exactly what the session received, so the two should agree.

Step 7 — Iterate the artifact

The artifact is the living home of the effort's framing. As decisions land, update it — in the view, in any editor, or let an agent maintain it. Two properties to internalize while iterating:

• Grounding is captured at launch. Editing an artifact does not reach into sessions already running — a live agent's briefing never shifts mid-task. Respawn the pane (or start a fresh session) to carry the updated context.
• One mechanism, every door. Sessions you launch, sessions Voice stands up, and sessions agents spawn for other agents all resolve artifacts through the same backend — an agent-dispatched worker inherits the workspace's context exactly as your own sessions do. The artifact you just wrote is now the effort's briefing for everyone.

This is also the recommended preparation for a mission fleet. A fleet's launch dialog carries the same two fields: a Global context every pane inherits on top of its mission grounding, and a first message appended to the commander's kickoff and to every worker's opening turn. Attach the effort's artifact there and the whole fleet starts briefed — see Run a mission.

Where everything landed

Where to go deeper

• Context artifacts & grounding — why grounding is the operator's highest-leverage move
• Context Artifacts — the view in reference form
• Terminals — workspaces, agent panes, spawn controls, and what to check before you point one at code you did not write
• Run a mission — the same grounding, applied to a whole fleet
• The knowledge graph — the three depths and when each is worth it