Working with documents and canvases¶

A project contains a document corpus and one or more canvases. Ingest a PDF once, then reuse it on several canvases. A document card points into that corpus; a spec table keeps a separate source reference for each row.

For automatic evidence states and human citation judgments, see Evidence status and source review. For agent plans, previews, and applied changes, see Agent plans and canvas nodes.

Select the project before you start¶

For the project created in the Quickstart:

anchor use study pump-study
anchor serve --env study --project pump-study

Open the printed URL and leave the server running. CLI commands in another terminal can use the selection saved by anchor use. Commands inside a folder initialized with anchor init resolve that folder's project unless explicitly overridden. An MCP server is pinned to its environment; the agent selects a project separately with a tool argument or open_project.

Add a PDF¶

Drag a PDF onto the canvas, or choose + > PDF datasheet. A document card shows its progress. The provider determines what happens next:

Provider	Browser upload behavior
`local`	The server stores the PDF and runs local extraction. No model-assisted gold regions are created.
`harness`	The server stores the PDF, creates an awaiting agent card, and queues a `drop_to_ingest` intent. Your agent must complete the harness ingestion session.
`ollama`, `openai`, `azure`, `custom`	The server runs local extraction and configured model-assisted processing when the endpoint is available.

CLI ingestion is also available:

anchor ingest "/path/to/datasheet.pdf"
anchor list

This writes the document corpus, without adding a canvas card. A card is optional: drag an existing document from Files onto a canvas when you want it there. The CLI and MCP ingest_pdf run built-in ingestion; in a harness environment they do not replace the page-by-page session performed by the agent.

What the ingestion layers contain¶

Bronze: the original PDF and source metadata.
Silver: local extraction, page text, rendered pages, layout items, and geometry available from Docling.
Gold: interpreted regions and reconstructed region content, when produced by a configured extractor or harness session.

Gold-region semantic search needs both gold regions and embeddings. A local-only document can still be opened, read by page, and cited with available geometry. Gold is not required for every precise reference: an item, cell, or explicit box can locate evidence without a gold region.

For built-in ingestion, silver/<slug>/ingest-report.json records timing. anchor ingests and anchor ingest-status SLUG report ingestion activity. If a PDF has missing text, try --full-page-ocr. To replace an extraction, use --force deliberately; endpoint-backed processing may repeat paid calls.

Harness-driven ingestion¶

Ask your agent to check pending intents in the correct project. For an uploaded PDF it runs ingest_begin, retrieves page work items with ingest_get_page, submits interpretations with ingest_submit_page, and finishes with ingest_finalize. It then updates the card and resolves the intent.

ANCHOR validates the session output. Region IDs must be unique within a page; the same ID on different pages is valid. Use qualified locators such as p2/r4 when a bare ID is ambiguous. An invalid replacement does not replace the previous complete document generation. See Document generations.

Navigate a PDF¶

The explorer opens on Sources, the documents used by this canvas. It derives that list from node and spec-row source_ref values, explicit edge references, and existing document cards. Each document appears once, with a page-1 thumbnail, title, page count, and gold status. Missing project documents remain visible so you can identify broken citations. Files lists the whole project corpus.

Click a fact's source anchor or a spec row's citation to open the shared viewer at its source page and region. The active document appears larger in Sources, with the current page shown. Clicking that active item keeps the page and highlight. Browsing a project document does not add it to the canvas's sources.

Keep provenance on the node or row itself. Neither a document card nor an edge to a document hub is needed to open or review that citation. Explicit anchored evidence edges remain available when the line is useful, such as a connection from a spec row to a crop image. A source citation still needs validated claim evidence to earn a Verified row state.

Open a document in the source dock and choose Contents beside Pages. Headings are nested by level; extracted tables and figures have separate lists. Choose an entry to jump to its page. When the index supplies a bounding box, the dock briefly highlights that part of the page.

The viewer prefers the extracted silver outline, then tries the PDF's embedded bookmarks. If neither is available, a short hint points you back to Pages. In Full screen quick-look, use the Contents button to open the same navigation panel. Choosing an entry opens its page. Full-screen box overlays also require page geometry available to quick-look; use the dock for source review when quick-look reports that page dimensions are unknown.

Create and organize canvases¶

anchor canvas create comparison --title "Pump comparison"
anchor canvas list
anchor canvas state comparison

Open the canvas from the browser's canvas list. Add cards and shapes from the left rail, drag them into place, and use a spec table for related parameters. The files explorer and PDF source dock can be toggled with [ while you are not typing. Canvas state is saved to the project as you work.

Select an element, or Shift-select several, and hold Alt (Option on Mac) while dragging to place a duplicate. Ctrl+C/X/V (Cmd on Mac) copies, cuts, and pastes the selection. Each paste moves the copy 24 canvas units farther down and right. Containers include their contents; connectors between copied elements keep their handles and connect the new IDs. Copy both endpoints when moving a connector to another canvas.

With a selected node focused, Enter edits its label. Arrow keys move the selection 5 canvas units; Shift+Arrow moves it 20. Container contents move with the container, and the positions are saved. Ctrl+D (Cmd on Mac) duplicates the selection 24 units down and right using the same citation and review rules as paste. These keys leave text fields and PDF navigation alone.

Single keys choose tools: T text, R rectangle, O ellipse, D diamond, F container, N note, M Markdown, A/C connector, and I mark up. Escape clears the tool and selection. Delete/Backspace removes the selection. Tool keys stay inactive while you type.

The canvas clipboard is shared between canvases in the same open project and lasts until the page reloads. Source citations are preserved, while copied human reviews and evidence verdicts are cleared. The server can independently validate the new citations and supply fresh evidence. Cutting removes the originals as soon as the server accepts the delete operations.

In mark up mode, the same shortcuts copy drawn shapes and labels with their leaders. Pasted ink determines its targets again at its new location. Alt-drag clones a shape or label; Alt+Shift-drag deforms a drawn line. The markup clipboard is separate from the canvas clipboard. Clipboard shortcuts keep their usual text-editing behavior inside input fields and editable labels.

Deleting a canvas does not delete its source documents. Removing a document is a separate corpus operation; existing source links may then fail to resolve.

Ask an agent to extract information¶

Name the project, canvas, source document, and desired result:

In project pump-study, add one spec table to canvas comparison from the ingested datasheet. Include pressure and temperature limits with units and product variant. Put a source reference on each row and flag missing values.

For a request tied to visible objects, choose mark up (i), mark the target, add your words, and click send to agent. The request and subsequent answers remain in an intent thread. If nothing happens, ask the external agent to pull pending intents; registering MCP alone does not launch background agent work.

You can also select existing nodes, including by dragging a selection box, and choose Ask agent in the selection controls. Type your request and choose Send to agent. The thread targets exactly the nodes selected when you opened the request, and the selection stays in place. You do not need to redraw it with the pen. Find the queued request in Intents. A failed submission keeps your text so you can retry.

An agent can ask for clarification or stage a suggested change. Inspect the preview and approve, decline, or send feedback in the thread. Empty placeholders do not submit work on their own. See the tutorial for the full review flow.

Agent plans and canvas nodes¶

An agent's plan or progress update belongs to the intent thread when the agent posts it there. A positioned message can appear on the board as a ghost card; it remains stored with the thread rather than becoming an ordinary canvas node.

Item	Representation
Plan or progress	An intent-thread message, optionally displayed as a positioned ghost card.
Pending proposed changes	An intent suggestion with a preview of the nodes and edges it would change.
Applied changes	Real nodes and edges saved with the canvas.

A pending preview does not change the saved canvas. Applying the suggestion creates, updates, or removes real nodes and edges, while the intent thread keeps the conversation and change record. Applied changes may offer keep and revert controls in that thread.

The plan itself becomes canvas content only if the agent explicitly creates nodes to represent it, for example a text node listing the steps. A plan written only in an external agent's chat is not automatically sent to ANCHOR; the agent must post it to the intent thread or create the intended canvas content.

Save and reuse references¶

In the PDF dock, select text or a source region and choose Make reference. The References tab keeps the selected quote, page and bounding box in this canvas's bibliography. Search by caption, quote or document name. Click an entry to return to its source; rename or delete it from the same list.

To reuse an entry, select an editable canvas node, open References, and choose Attach on the entry. Choose Whole node or a table row. For a fact, note, text or Markdown node with body text, choose Selected words in text, select the words in the dialog, and choose Attach. The citation keeps the bibliography ID rather than duplicating its locator in the text. Cancel and reopen the dialog if an agent changes that text while you are selecting it.

Agents can create/list/attach references with canvas_create_reference, canvas_list_references and canvas_attach_reference. The HTTP /api/workspaces/{canvas}/references endpoints and CLI anchor canvas reference commands expose the same store and operations. To cite an existing bibliography entry in data.text, use the normal node update operation with this link syntax:

The maximum pressure is [10 bar](anchor:ref/REFERENCE_ID).

Both plain text cards and Markdown cards resolve this link in their owning canvas. Direct document links such as [10 bar](anchor:datasheet?page=1) still work. A missing or deleted bibliography ID appears as a broken citation; references from another canvas are not searched. Deleting an entry leaves the copied source locator on already attached nodes and table rows intact.

Attaching a reference replaces that target's current source link. It does not record Accept or Reject or mark the claim Verified; inspect and check the source as described below.

Inspect and maintain row evidence¶

Click a spec row's source anchor to open its PDF page. The dock highlights a resolvable region, item, cell, or explicit bounding box; a page-only reference opens the page. Select source text to add a more precise citation when needed.

A highlighted box also opens a small 2.5x magnifier beside it, so a value stays readable when the page is zoomed out. For a reference with several boxes, move the pointer over a box to magnify that place. Escape dismisses the highlight and magnifier together.

Evidence status and source review¶

The row's evidence state reports the automatic check:

Row state	Meaning
Verified	ANCHOR's automatic checker matched the row's claim to its cited source.
Stale	The claim or evidence changed and needs a fresh check.
Unverified	A source link exists, but automatic verification has not succeeded. The value may still be correct.
No evidence	The row has no source reference.

Right-click the row's anchor icon to record your judgment of its source link. Choose Checked, right (Accept) or Checked, wrong (Reject), with an optional note. Accept does not make a row Verified. Re-check against the source runs the automatic checker again and reports its progress and result. If the checker abstains, its explanation tells you what to inspect or correct. A request failure is reported separately.

Verify units, conditions, and pump model yourself. A row can be Verified yet deserve Checked, wrong because its cited value belongs to the wrong pump model. Automatic matching and your engineering judgment answer different questions. The anchor menu records a row's source-reference verdict; accepting or rejecting a whole node or a change in Proposals is a separate action.

Editing a value can keep its citation while changing its evidence state. See Claim and evidence and Source resolution.

Continue later¶

Stop anchor serve with Ctrl+C. Your project persists on disk. Start it again with the same --env and --project. Back up the whole project folder, including hidden .anchor_data/, rather than only the canvas JSON.

For FMU simulation, install the optional runtime and inspect the model before wiring table values into its parameters. FMU demo output is synthetic when ANCHOR_FMU_DEMO=1. CAD and SysML support is experimental. See the CLI reference for extension commands.