---
name: atlas-canvas
description: Maintain an Atlas visual knowledge canvas through its authenticated workspace API. Use when an agent is asked to log research, sources, insights, decisions, questions, or relationships in Atlas; inspect or organize an Atlas workspace; continue research from an Atlas connection bundle; or leave durable knowledge behind after a chat or coding task.
---

# Atlas Canvas

Use Atlas as durable shared memory. Keep chat for interaction; place reusable knowledge, evidence, conclusions, and open questions on the canvas.

## Connect

Require an Atlas connection bundle containing:

- `endpoint`: `https://<site>/api/atlas/<workspace-id>`
- `researchEndpoint`: `https://<site>/api/atlas-research/<workspace-id>`
- `mcp`: `https://<site>/mcp/<workspace-id>` for Streamable HTTP MCP clients
- `token`: scoped bearer credential
- `permissions`: allowed scopes and canvas IDs
- `workspace`: workspace ID

Treat the token as a secret. Never place it in card content, logs, commits, URLs, or responses. If no bundle is available, ask the user to open **Ask an agent → Connect an agent** in Atlas and copy one.

Check `permissions.scopes` before choosing a workflow. `read` permits inspection, `propose` permits Ask Atlas, `research` permits pending mission capture, and `write` permits direct attributed transactions. Never attempt to bypass a missing scope. Agent bundles never grant deletion or access management.

If the host supports MCP with custom authorization headers, prefer the bundle's `mcp` URL and pass the token as `Authorization: Bearer <token>`. The server exposes only the operations that the credential can authorize. Otherwise use the deterministic HTTP client below.

Use `scripts/atlas_client.py` for deterministic reads and writes. Set credentials only in environment variables:

```bash
export ATLAS_ENDPOINT='https://…/api/atlas/…'
export ATLAS_TOKEN='…'
python3 scripts/atlas_client.py inspect
```

Read [references/protocol.md](references/protocol.md) before constructing transactions directly.
The Atlas web app normally bootstraps the workspace. Use the documented bootstrap command only for an isolated workspace that the user explicitly authorized the agent to initialize.

## Workflow

1. Run `inspect` and identify the target canvas by title and ID.
2. Read the existing nodes and edges before adding anything.
3. Decide whether the new material is durable. Prefer:
   - sourced claims;
   - concise explanations;
   - decisions and their rationale;
   - contradictions and uncertainty;
   - useful questions and next steps.
4. Avoid transcript dumps, greetings, repeated information, private credentials, and unsupported certainty.
5. Reuse or update an existing node when it already represents the idea.
6. If the bundle grants `write`, create a small atomic transaction. Include the agent name, optimistic base revision, and a unique client mutation ID. Otherwise use research capture so the human reviews the change.
7. Connect new material to the ideas or evidence it depends on.
8. Read the returned workspace and verify the intended nodes and edges exist.
9. Report what was added or changed with canvas and node titles.

## Live research capture

When a user wants Atlas to learn alongside a conversation, use a research session instead of writing directly to the canvas.

1. Inspect first and identify the target canvas.
2. Start a mission with a concrete goal and intent (`understand`, `compare`, `decide`, or `build`) using `atlas_research_start` or `research-start`.
3. During the conversation, submit small batches with `atlas_research_capture`. Each candidate must be one durable item: a `source`, `claim`, `insight`, `decision`, `question`, `contradiction`, or `next_step`.
4. Use `atlas_research_ingest_source` for public URLs so Atlas can validate redirects and capture source metadata safely.
5. Create checkpoints after a topic boundary or roughly 3–7 strong candidates.
6. End the session when the research task ends. Tell the user how many candidates are waiting in the Research Inbox.

Never send raw messages, full conversation history, chain-of-thought, credentials, greetings, or filler. Research tools only create pending candidates. The human must edit, accept, or reject them in Atlas; agents cannot approve their own capture.

Prefer candidates that state why they matter and how they relate to existing node IDs. Durable cards should normally contain 120–220 useful words: the mechanism or finding, why it matters, and at least one boundary, failure mode, falsification test, or concrete example. A short label with one generic sentence is not a finished knowledge card.

Separate what a source says from what the agent infers, attach a source URL where available, and use honest `low`, `medium`, or `high` confidence. For `source` candidates, include supported bibliographic and appraisal fields when available: `sourceTitle`, `sourceAuthor`, `sourcePublishedAt`, `sourcePublisher`, `sourceType`, and `evidenceQuality`. Never invent missing metadata.

## Canvas grammar

Use these node types consistently:

- `overview`: central question or orientation
- `source`: paper, article, video, dataset, or primary evidence
- `concept`: explanation or definition
- `insight`: synthesis derived from multiple items
- `question`: unresolved or falsifiable question
- `timeline`: chronological development
- `note`: informal durable thought

Use relationship labels such as `supports`, `contradicts`, `explains`, `depends on`, `example of`, `caused by`, and `raises`.

## Research quality

- Separate source claims from agent synthesis.
- Preserve uncertainty explicitly.
- Put citations or source URLs in source-node content.
- Attribute agent-created material using the request-level `agent` field.
- Prefer five strong cards over twenty shallow cards.
- A strong explanatory card includes mechanism, implication, and boundary; a strong source card includes the exact finding, scope or limitation, and evidence grade.
- Do not reorganize human-authored regions without being asked.
- Never delete human-authored nodes unless the user explicitly requests deletion.

## Common operations

Inspect:

```bash
python3 scripts/atlas_client.py inspect
```

Apply a transaction file:

```bash
python3 scripts/atlas_client.py transact operations.json --agent "Codex"
```

Research capture:

```bash
python3 scripts/atlas_client.py research-start --goal "Understand when RAG improves an LLM product" --canvas product-research --agent "Codex"
python3 scripts/atlas_client.py research-capture SESSION_ID candidates.json --agent "Codex"
python3 scripts/atlas_client.py research-checkpoint SESSION_ID --label "Evidence reviewed"
python3 scripts/atlas_client.py research-end SESSION_ID
```

The transaction file must be a JSON array of operations. The bundled client automatically sends the inspected cloud revision and a unique mutation ID so retries are safe. Use server-returned IDs when later operations depend on newly created nodes; otherwise split into two transactions and inspect between them.
