Yard Docs
Sign in
On this page

Docs, prototypes and canvases

The workspace holds its docs, prototypes, work and canvases directly; docs gather what a piece of work needs, listed with prototypes, canvases and research in the sidebar's Library, one composer to start work from anywhere (⌘J), chats per doc, Uploads, and the canvases the workspace and its projects keep.

Updated November 11, 2026 · 43 min read

A doc is where a piece of work is gathered: what people said, the screens as they are today, the code it touches. It is a page of text and blocks that grows downwards: pasted text, files, repositories, other docs, prototypes, projects and research. Nothing is opened for you: the workspace opens on Home, and you pick a doc from the sidebar or from the Docs page. Work starts from one composer, which Start work (or ⌘J, from anywhere in the workspace) opens over whatever you are looking at. The projects that come out of it are listed under Work. What you ask is answered in the chats on the right, each kept with the doc it was started on. Everyone in the workspace sees the same docs, live.

The sidebar is the same on every page: a rail of places (Home, Work, Library, Chats, Files, Live, Feedback; Repositories, People and Settings at its foot) and one list beside it with what is in the place you are in. A doc, a prototype, a canvas, an investigation and a goal are in the Library: its list has Goals, Docs (archived docs wait under Archived), Prototypes, Canvases and Research (an investigation is a doc named "Investigate: …"), a few rows of each with All n to its page, a Filter the library field and a chip per kind. + in its header makes a new doc, prototype, canvas or goal. These are the workspace's kinds of things, side by side, held by the workspace itself: there are no boards. On a canvas the list is that canvas: Find on this canvas and On this tab, its blocks as a tree, with a link back to the Library. Under them, From the Library (folded at first) keeps the docs and prototypes at hand, to drag onto the canvas. Customize sidebar (in More in workspace) hides a folder of Resources (Docs, Prototypes, Sheets, Repos, Research) and puts them in your order; a hidden folder's things still open by their address and show in Files. The button in the list's header (or ⌘\/Ctrl+\, and ⌘B/Ctrl+B) hides the list, leaving the rail, and its right edge is dragged to make it wider. The keys 1 to 3 go to Home, Work and Monitors.

The Docs, Prototypes and Canvases pages show every item as a card with a search field and a New … button; a card has the same ⋯ menu as its sidebar row.

Every row of a doc, prototype, project or research has a ⋯ menu, and a right-click on the same thing anywhere else (a row of Home's Needs you or Recent files, a tab, a chip) opens the same menu at the pointer. It starts with what the item is ("Doc · Launch · 3 references", "Project · Launch · edited 2h ago") and what else there is to know about it: a doc's opening words and when it was created, a project's status, plan step, criteria, repositories, changes and who started it, a prototype's round. Then three tiles: Start work (the work composer with the item in its context), New chat (a chat on it in the chat column) and Open beside (a tab in the chat column). Under Use it as context: Add to the open composer (while one is open), Mention in this chat (attaches the item to the open chat's next message as a chip), Attach to…, a searchable list of Your context (the box above New project), the open projects and the docs (the same as dropping the row on them) and Reference in…, a searchable list of docs (Open now first), which puts a reference to the item at the end of the doc you pick. Then Open in new tab, Pin to the sidebar (Unpin), Copy link, Rename, Duplicate (docs), Tick the whole doc (docs), Archive or Restore (docs; Close project for a project) and Delete… (docs and prototypes). A row can also be dragged onto the work composer, a chat's reply box, a doc, a canvas or a project to add it as context. A project's row in the sidebar takes docs, prototypes, blocks, files and repositories; what it does not take (another project, for one) is refused, and a note says why.

Projects in the sidebar's Active list are grouped by what they wait for. Within a group, drag a project above or below another to put them in your own order; this browser remembers it. In the sidebar's Pinned, drag a row onto another to move it there.

Pinned, on the workspace overview (the sidebar's Overview row, which shows how many you pinned), lists what you pinned from a row's menu or by dragging it onto Pinned (docs, prototypes, projects, research, repositories, pull requests, branches, issues, pushes, blocks, files), in your order: a card dropped among the others goes where you drop it. A repository pinned at another branch is a card of its own with the branch. Every card can be unpinned from its menu. Pins are yours; the work composer offers them as one Pinned chip you can unselect per message. Blocks that were pinned on a canvas for the agent's context before canvas pins went were moved here, for everyone who may open their tab.

Docs

A doc is text with blocks placed in it: one block at full width (a picture, a file with its preview, a code excerpt, a project with its progress, a prototype), or several as Cards, a group that wraps three to a row. The Docs list in the sidebar and the Docs page show them; + (New doc) adds one. A new doc is Untitled: once something is written in it, it offers three names (from your own agent account), and takes the first one after five minutes if nobody picks one. Its row says naming… until then. A new workspace has no doc yet: New doc on the Docs page makes the first.

An archived doc leaves the list and waits under Archived in the sidebar's Docs list and last on the Docs page; Restore (in its menu, or on its page) brings it back. Delete… asks first, and any doc can go, the last one too; you land on Home. The files placed in a deleted doc stay in the workspace's files.

Type / on an empty line for Blocks: Decisions, Schema (a data model as tables, see Notes), Cards, Image or video, File, Code from a repository, Link, Project and Table, each with a line saying what it is. They, headings and the divider only appear on an otherwise empty line. After a space in a line of text, / offers Mention a repository… instead ("See /repo"), put in the line; inside a word (a/b) it opens nothing. The menu filters as you type (/car); Enter inserts, Esc keeps what you typed as text. Picking one opens a list of the blocks of that kind, and the other docs.

Code from a repository lists the code already on the board and every repository of the workspace. Pick a repository to search its files by name, then a file: press Enter for the whole file, or type a line or a range (12-40) and press Enter for those lines. The excerpt is added to the board as a read-only code block and placed in the doc, showing its lines. The row above the search, or Backspace in an empty search, goes back a step.

To place a file of the workspace, open it from the Files page and press Add to this doc. Drag a block's handle to move it: a line shows where it lands, between blocks or between the cards of a Cards block. Drag a card to reorder it. A block on its own (a picture, a file…) dragged onto a Cards block, by itself or by its handle, becomes one of its cards. A file dropped from your computer onto the doc is uploaded into the uploads/ folder and placed where it was dropped; dropped onto a Cards block, it becomes a card there. A block dragged in from another tab of the canvas is written in as a link card to it, since it cannot show on this doc.

Click a card to select it: a picture or file pasted then goes in right after that card. With the Cards block selected, or the cursor inside it, pasted files go in as its last cards.

Each doc is a Markdown file on the runner, docs/<id prefix>-<slug>.md (for example docs/hhfs2a83-launch-plan.md): its title as the heading, a placed block as [[block:<id>]](label), another doc as [[doc:<id>]](title), a Cards block as a ```cards fence of them, and a question the agent asks as a ```question fence (see below). Editing that file (an agent, or you in a terminal) changes the doc for everyone.

The start of the name is the doc's id and never changes; the rest follows the doc's title, so renaming a doc moves its file, and a new "Untitled" doc never takes the name another doc had. What an agent writes to an old path, just before or after a rename (any file of docs/ that starts with the doc's id prefix), still goes into the doc, merged with what was written meanwhile, and the old file is removed. .yard/docs.json lists each doc's file and the paths it had before. Files named before the prefix move to the new names once, the first time the runner writes the docs out.

Canvases from before docs were moved once, for everyone: the workspace's first canvas became the doc "Main", a group a heading followed by a Cards block of its members, and the other blocks are listed in reading order. An old link to a tab that became a doc opens that doc.

Where boards went

Workspaces used to hold their docs on boards. Boards are gone: the workspace holds its docs, prototypes, work and canvases itself. Each board's docs, with their pages, the files and prototypes placed in them and the chats started on them, joined the workspace's docs the first time it was opened after the change, keeping their addresses, so links, pins, chats, feedback and projects that pointed at them still open them. A board's other tabs became canvases, listed under Canvases. An old board address (/b/<board>/…) opens the workspace's Docs, Uploads or the prototype it named.

Nothing is restricted within a workspace: its docs are open to everyone in it, and docs that were once kept apart for a few people have joined them.

The doc page

The doc's header has the doc's title, with its Saved pill (and a globe while the doc is shared with a public link); then, at the right, N picked · Clear while something is ticked, Start work, Add repo, Add reference, Chat N while the chat column is hidden, who else has the doc open, and the ⋯ menu (Rename, Tick the whole doc, Share… for people who can edit it, Export as Markdown and Export as PDF (see Files), Collapse or Expand prototypes, Archive or Restore, Delete…). Share… gives people outside the organization a view-only link to the doc: see Share a doc outside the organization. On a phone the header keeps the title, Start work, the chats button with how many chats the doc has, and ⋯.

Add reference opens the / menu on a new line at the end of the doc. References read as typed cards, each with its kind: Linked file (a file of a repository, with its lines), Repo, Doc, Prototype (its first kept screen, its round and how many screens), Project (its state and how many steps are done) and Research (what the agent filed under Research). A card opens what it points at.

Repositories of a doc

A doc's repositories are the ones it references: a repository or code block placed in it, or a repository mentioned in its text. What the doc does not reference is not part of it; there is no separate list to tick.

Add repo in the header opens the list of the workspace's repositories on a new line at the end of the doc; picking one mentions it there (and puts its block on the workspace's canvas when it has none yet). / after a space in a line, @, or a drag from the Files panel does the same where you write.

Work you start from the doc begins with these repositories: Add this doc in the work composer adds them as repository chips, and the doc's chat reads them from the doc's text.

Linked work

A project started with the doc in its context keeps the doc it came from. The doc then shows a band under its header, one row per open project, the running ones first: Linked work: the project, its state ("Working", "Needs you"), its progress, "step 3 of 6" and Open project.

The agent asks in the doc

When something about a doc is still open and only a person can decide it, the agent of a chat on that doc asks in the doc itself, in the section the question is about, rather than in the chat. The question is a card: "The agent asks · from chat “Pain points”", "2 of 2" when it asks several, the question, its options (with a hint where one helps), and Something else… to write an answer of your own. In the chat the step reads Asked in the doc · <section> · N.

Pick an option and your pick is written in the question's place, with "Your pick, from the agent's question · just now · Change" under it; Change puts the question back. Answer as many as you like: the bar under the doc counts the answers not sent yet, and Send answers posts them to the chat that asked as one message, "You answered in the doc: …", so the agent carries on from all of them at once. Picks not sent yet are sent when you open another doc or leave the library. A question fence the doc cannot read stays a code block. Viewers see the questions without being able to answer. The agent asks in the doc on runners from version 0.31.0; on older ones it asks in the chat.

Files of a doc

The files of the workspace are in its Files page (Files in the sidebar): the docs, prototypes/ and research/, then uploads, the repositories, monitors and sources.

Opening and ticking are separate. A file opened from a doc block, the Files panel, Uploads, a chat or a prototype's page opens in the file dialog over the page, which stays as it was beneath: the file itself (a PDF paged, a picture, a note's text), what it is, where it is, who added it and the docs it is placed in. Use it: offers what is open now: Attach to chat (the chat shown), Attach to composer (while the work composer is open) and Add to this doc (places it in the open doc), then Copy path and Download. Opening a file does not tick it.

To tick a doc, use its box on the overview, or Tick the whole doc in its ⋯ menu (on the page or its row); the doc then says so, and a box in the doc's margin picks a single section instead. The bar shows N picked · Clear. What is ticked stays ticked when you switch pages, and goes with work started from there as chips of their own (see below).

The page you are on is not read by itself. The open doc is never ticked or added for you: the work composer offers it with Add this doc instead, and a chat on the doc reads it anyway.

The composer

Every box you write in to start something or to reply is the same composer, in one of two variants. Both have the same tools: the paperclip's Attach menu (this device, a workspace file with @, and, where they apply, blocks, a repository or a screenshot), @ to add anything under Resources in the sidebar (docs, prototypes, sheets, repositories, research), a block of the page, or a file, / commands, the microphone, the model pill (the agent, model and effort), what the conversation used, and Queue, Steer and Stop while an agent works. Pasting or dropping files attaches them, up to 50 MB each; a file that is too large, or whose upload stops, stays out and the message can still be sent.

  • The chat variant replies in a chat: Enter sends. It is the box under every chat (see chat).
  • The work variant starts something: on Home, in the Start work composer that floats over any page, over a canvas, and as the instructions of the Write spec dialog. Enter starts a new line; ⌘/Ctrl+Enter presses its button.

The work composer

Write what you want, then pick what it starts:

  • Ask answers in a new chat of your own, so the question does not land in the middle of the conversation you have open: on a doc, a new tab of its chat column; anywhere else, a new tab of the workspace chat. A chat with nothing in it yet is used rather than another one made. To go on in a chat, write in that chat. With something in the context it can go without words.
  • Work starts a project with what is in the context. There is nothing to pick about where it goes: it is the workspace's. Create a spec first decides how it starts: off, the agent starts on the code right away ("Start work"); on, you get a plan to edit before any code is written ("Start with a spec"). See projects and specs. On a doc or the overview the project opens as a tab of the chat column; elsewhere you land on its page. A project started with a doc in the context keeps that doc (linked work), and the doc's text goes with its instructions.
  • Prototype makes a prototype, listed under Prototypes. On a doc it is placed at the end of the doc; anywhere else (Home, a canvas, the feedback inbox) you land on the Prototypes page with it. It is never put on a canvas. Specify sets this run's Kind, Directions, Look and Also show (empty states, errors, loading, dialogs); the next run starts from "Nothing set" again.
  • Investigate asks a question and opens its answer, a doc named "Investigate: …": see investigations.
  • Refine, offered on a prototype's page while a round is open, makes its next round from the comments ("Round 24 · 6 comments"), with your words as an overall comment.

The button follows the choice: Ask, Start work or Start with a spec, Build prototype, Investigate or Refine. /ask, /work, /prototype, /investigate, /spec (Work with a spec first), /model, /attach and /discard do the same from the text.

The context is the chips over the text: nothing is added for you but the canvas or monitor ⌘J was pressed on. Add more with + (the context picker, see below), @, Attach (Blocks opens the same picker; A repository lists the workspace's repositories), a drag from the sidebar, the Files panel, a canvas or a chat tab, or Add this doc. On a doc, what is ticked (or, on a canvas, selected) shows as chips too, and removing such a chip unticks it. Your sidebar Pinned items go along as one Pinned chip; open it to leave one out of this message. For Work, each repository chip shows where the project starts in it (new from main by default); see the branch a project starts from.

When the runner is offline, or for a viewer, the line under the composer says why and nothing can be started. Offline, what you wrote is kept as a draft in this browser and sent when the connection is back.

Start work from anywhere: ⌘J

⌘J (Ctrl+J) opens the Start work composer from any page of the workspace: it floats at the bottom centre of the page, "Start work · stays here while you look around". It is not a dialog: the sidebar, the page and the chat stay usable, and it keeps what you wrote while you move around the workspace, from doc to doc or to a project. Its grip moves it; Minimise (or Esc) folds it to a Start work pill at the bottom of the page (Start work · draft while something is written), and ⌘J brings it back or gives it the focus. On a phone it is a sheet from the bottom. There is one draft per workspace: Home's composer shows the same one, and ⌘J on Home goes to it.

On a doc, an overview or a prototype's page a Start work ⌘J button floats at the bottom of the page and opens it. ⌘J on a canvas adds the canvas to its context, and on a monitor's page the monitor. A doc is never added by itself: opened on a doc, a banner says "“Launch” is not in context. Work starts only from what you add here." Add this doc adds it, with the repositories it references; the × dismisses the banner.

Drag a row of the sidebar (a doc, prototype, project or research), a row of the Files panel, a chat tab or blocks of a canvas onto it: it gets an accent border and "Drop to add as context", and what you drop becomes a chip.

Chats belong to a doc

The right column holds the open chats as tabs: a spinner while the agent works, a dot for a new answer, and the doc's name when the chat, project or prototype is on another doc than the one open ("No doc" for a chat on none). Opening another doc switches to that doc's newest chat, or a new one. When a tab of another doc (or of none) is shown there, a note over the reply box says it is not attached to the open doc, with a button to the open doc's chats; what you write there still goes to that chat, and a question asked from the doc starts a chat of its own. + after the tabs starts a new chat, and the history (🕘) lists every chat of the docs by doc, those on no doc last. Under the tabs, one line says what a chat here does: "Focused on this doc · reads the workspace, repos and files · edits the doc", with "N more" when the doc has other chats. Opening a doc brings up its chats; how many chats a doc has shows on its row in the sidebar. A chat tab can be dragged onto the work composer as context.

The box under a chat replies in that chat, in the composer's chat variant, with a This doc chip; + after it adds with @. It has the model pill, the paperclip (this device, a workspace file with @, or a screenshot), the microphone, / commands, and Queue, Steer and Stop while the agent works. Under a new chat it makes the chat when you send or attach. A turn that could not finish offers Retry; one you stopped says what it did and offers Continue.

The last button of the tabs hides the column, as ⌘. (Ctrl+.) does; Chat N in the doc's header (or ⌘. again) brings it back. Whether it is hidden is kept in this browser, for every doc. ⌘B still collapses the sidebar.

Drag the column's left edge to make it wider or narrower; double-click the edge for the default width again. The width is kept in this browser across reloads. With the edge focused, ← and → resize it by 16 pixels and Home resets it.

Uploads and folders

Everything uploaded, pasted or dropped lands in the uploads/ folder first. The workspace overview's Files card lists it first, with how many files it holds, and opens it in Files (the old Uploads page goes there too). Files dropped from your computer onto the card go into uploads/ and are listed first. Nothing is filed for you: Move to… suggests the folder where similar files already are and the kind's own group, lists the folders, and makes a new one. Moving keeps a block's id, so every doc and chat that uses it keeps working; on the runner its file moves to files/<folder>/. Not moved yet hides what was moved.

Delete (the bin on a row, or on the selection) asks first and says which docs use the file, since they lose it. The toast's Undo brings it back.

How the agent files things

The workspace's docs have filing rules (Markdown, edited from Uploads → … → Filing rules or a reply's Edit rules), given to the agent word for word. By default: research goes in one folder per topic under Research, with the write-up named after it; pictures for a write-up go in its folder under screenshots/; names are lowercase with dashes; a topic that exists gets a new version, not a second folder. A reply that filed things shows Filed by the filing rules with the rules it followed, Open and Link it in <doc>.

The agent uses yard-canvas file <path|block> --folder <folder>, yard-canvas place <block> --doc <doc> [--after "<heading>"] and yard-canvas docs. In the docs, yard-canvas size, move, connect and layout answer that the docs have no canvas.

A canvas in a doc

A canvas of the workspace (listed under Canvases in the sidebar) can be placed in a doc, as a block of its own: one row with the canvas's name, how many blocks it holds and when it last changed.

  • Expand shows a small, read-only copy of the canvas in the doc. Drag it to pan; the buttons zoom and Fit shows every block again. Collapse folds it back to one row. Whether it is expanded is kept in the doc, for everyone, and after a reload.
  • Full screen shows the same read-only canvas in a window over the doc; Esc or Close closes it.
  • Open (or the canvas's name) goes to the canvas itself, its page, where it is edited.

To place one, type /canvas in the doc and pick a canvas, or New canvas to make one there and then. Dragging a canvas from the sidebar onto a doc, or Reference in… in its ⋯ menu, places it too. In the doc's file it is [[canvas:<id>]](label) alone on a line. A canvas that was deleted, or that you may not open, reads "Not available".

Agents make canvases for material that is spatial (code excerpts side by side, a diagram, groups) with yard canvas create "<title>" --doc <doc> and embed them in the doc they support; the explanation stays in the doc's text. An investigation does this when its evidence needs it.

Prototypes and specs

A prototype is a page of its own, opened from Prototypes in the sidebar or from a doc it is placed in: see Prototypes. Placed in a doc it follows its latest round and shows only its kept screens; in the work composer's context it brings those screens' pictures and their comments.

The canvas

A sheet (a canvas) is a quick group of resources: paste reference files and images, drag anything in, and see them at a glance, each where you put it. The workspace's sheets are listed under Sheets in Resources, and a project keeps one of its own. Dragging a sheet onto a chat or a draft gives everything on it, nested sheets included, each thing once; what is cut off past ten links is listed in the draft. A canvas of the workspace is an item like a doc or a prototype: it opens as a page of its own, and it gathers what you put on it rather than owning it (see What a canvas gathers). What follows describes it. The workspace's docs from before docs can still be shown as their canvas by adding ?canvas=1 to the workspace's address (and ?canvas=0 to go back).

Everything on a canvas is a block: a note, an image, a file, a link, a repository, a code excerpt and more. A group or a tree from an older sheet is gone: a group's members stayed where they were, and a tree became a note holding its outline. Everyone in the workspace sees the same canvas, live, with each other's pointers and selections.

Adding blocks

There is one row above the canvas: the canvas's name (see A canvas is a page of its own), Select and Hand, the tools, the Canvas and List switch, and the zoom at its right end. On a phone the name is a row of its own above the tools, and the tool row keeps Select, Hand, Add and …; the other tools, zooming, Fit and 100% are under …, and a pinch zooms. The keys 1 to 3 go to Home, Work and Monitors.

  • Add opens one menu of tiles, each with a sentence on what it is: Note, upload or link (a note with N; Upload files with U and Link are under it), From the workspace (on a canvas that gathers: what the workspace already has), Repository (Shift+R), Spec (see Specs on the canvas below), Goal (see Goals on the canvas below) and Monitor, with Flow, Cron monitor and Environment under it (see Monitors on the canvas below). Shift+A opens the menu. Upload files picks files from your computer. Images become image blocks, everything else becomes a file block. A file can be at most 200 MB.

You can also skip the toolbar:

  • Paste an image, a web address (it becomes a link block) or text (it becomes a note).
  • Drop files from your computer onto the canvas, or use Add to canvas on a row of the Files view (see Files).
  • Drag a row of the sidebar onto the canvas: a doc or a prototype lands as a link block to it, a picture as an image block and another workspace file as a file block. What a thing becomes is the same on every canvas; a repository's file stays in its repository and is not placed.
  • Right-click an empty spot on the canvas for the same kinds as Add, as a plain menu, adding right where you clicked. Several files fan out from that point. The same menu has Undo, Redo, Select all and Fit to screen. On a read-only canvas the add entries are greyed out. Right-clicking a block selects it and opens its own menu instead (see The block's actions below).

Select and Hand

The switch at the top left sets what dragging does:

  • Select (V): drag a block to move it; drag on empty canvas to draw a box and select every block it touches.
  • Hand (H): drag anywhere to pan.

In Select mode you can still pan by holding Space, dragging with the middle mouse button, or scrolling.

Selecting, moving and resizing

  • Click a block to select it. Shift+click adds or removes a block. ⌘/Ctrl+A selects everything; Esc clears the selection.
  • Drag a block from anywhere on it to move it, with the rest of the selection.
  • Arrow keys nudge the selection by 1 pixel, or 10 with Shift.
  • Resize a block from any corner or edge. Each kind of block has a minimum size.

Every change is one step for Undo (⌘/Ctrl+Z) and Redo (⌘/Ctrl+Shift+Z, or Ctrl+Y).

Monitors on the sheet

A workspace's monitors can sit on the canvas too: a flow, a cron monitor, an insight board or an environment, each a block showing that monitor. An agent puts one there with yard-canvas monitor <id> (the monitor's id, such as flw_…, cmon_…, ibrd_… or menv_…); asked again for the same monitor, it answers the block already there. A flow block's switcher sets that flow's environment. A block whose monitor no longer exists shows as missing.

Monitors on the canvas

Add, then Flow… (or Cron monitor…, Insight…, Environment…) asks which of the workspace's monitors to show, or for the name of a new one, which it creates. An insight board needs a connected database first.

  • A flow block shows its steps as a pipeline with how each went in the last run, what failed in a sentence, the last runs as bars, Run now and Runs in, the environment switcher. While a run is under way its steps turn as they finish, for everyone looking. Open editor (or a double-click) opens the flow in the Monitors view.
  • An environment block edits that environment's variables in place; a secret shows as set, with a button to replace it, never its value.
  • A cron monitor block shows its status, schedule, last ping and recent executions; an insight block shows the canvas's first card.

A flow's environment is set by its switcher. Deleting a monitor block asks whether to delete the monitor too; by default only the block goes and the monitor keeps running.

Goals on the canvas

Add, then Goal opens the work composer in Goal mode with this canvas as context. The goal you set from it gets a Goal block here: its status (Needs you, Working, Paused or Goal met), Ask me or Autopilot, and the stage it is at; a bar of the criteria met (green) and those of the stage being built (blue), the decisions made, and a strip with one segment per stage. The question the agent waits on is shown in a yellow band. Pause (or Resume) acts on the goal, Preview opens the running stage's project, and Open the goal (or a double-click) opens its page. An agent puts one there with yard-canvas goal <gol_…>; asked again for the same goal, it answers the block already there. A block whose goal no longer exists says "This goal is gone".

New blocks are placed so they never cover another one.

Zoom and pan

The zoom control at the right end of the toolbar row has −, the current percentage (click it to go back to 100%), + and Fit, which shows every block. ⌘/Ctrl+scroll or a trackpad pinch zooms around the pointer, about 15% per notch of a mouse wheel; Shift+scroll pans sideways. Zoom goes from 25% to 200%.

Blocks keep showing their content at every zoom, down to 25%: they get smaller, never replaced by their title.

When you have panned or zoomed away and no block is on screen, a Nothing in view pill appears at the top. Go to nearest block (Shift+2) centres the block nearest to where you were, at the same zoom unless it would not fit; Fit all (Shift+1) is the same as Fit. Neither selects or changes a block, and neither is an undo step.

Only the canvas zooms. In the signed-in app a pinch or ⌘/Ctrl+scroll over the top bar, a sidebar, the footer or a menu does not zoom the page, so the frame always stays in place. The browser's own ⌘/Ctrl + and − still work.

The block's actions

Select one block and a bar of icons appears above it, such as Expand (or Edit on a note) and Ask the agent, with a … menu for the rest. The … menu lists everything the block offers, the bar's actions first and Delete… last; right-clicking the block opens the same menu where you clicked.

Expand opens the block in a large panel over the canvas: a note to write in, a file's full preview, a link's page, a group's contents or a repository's explorer. Double-click or Enter does the same, and so does the expand button in a block's bottom-right corner, shown while you point at the block (always there on a touch screen). A note or a Markdown file has Export in its footer there, as .md or PDF (see Files). Close, Esc or a click outside the panel puts it away. The left sidebar, the chat and the footer stay usable while it is open. On a narrow screen the block takes the whole canvas instead.

Link to project, in the … menu, puts the block into an existing project.

The work composer on a canvas

While blocks are selected, the work composer stands at the bottom of the canvas, with the selection as chips. It is centred on the canvas; on a window narrower than 900px it is a strip across the bottom of the canvas, above the chat button. Press R to open it with nothing selected; then Esc in it puts it away again. Viewers do not get it. While it is there, ⌘J goes to it rather than to the floating one, and it holds the same draft.

  • Remove a chip with its × and that block is deselected. Nothing but the chips goes along.
  • + (or Blocks under Attach) opens the picker (below) to add blocks from the docs' library and other canvases.
  • A prototype asked for here goes on the open tab, joined to the selected blocks.
  • Starting something clears the selection.

Over the composer, at the right, a line says how many blocks are selected, with More for what else the selection can do:

  • Pin to the sidebar, with one block selected, adds it to your sidebar's Pinned list (Unpin from the sidebar when it is there).
  • Frame puts two or more blocks into a frame (as ⌘/Ctrl+G does, see frames).
  • Show on sheet shows the selection on another tab.
  • Draft monitors, when only repositories are selected, has the agent draft checks from them. See monitors.

Edit context: the picker

+ in the work composer (or Blocks under its Attach) opens Context for this work. Its categories on the left (Docs, Canvases, Prototypes, Work, Research, Repositories, Blocks, Files) each list their things with a checkbox. A canvas ticked under Canvases is given whole, the way a doc is: the agent reads every block on it and whatever those blocks link or attach, so you need not pick its blocks one by one. Blocks shows a dialog with two sides.

  • Top: Search by name and Selected only. They narrow every list; on a canvas, the blocks they leave out are faded.

  • Left, Docs: the Library of the workspace's docs, with how many of its blocks you have chosen ("2 selected"). Then Canvases, one row per canvas of the workspace. Under them, Whole things: Repositories, Monitors and Insights. Each lists every block of that kind, with where it is, as a row with a checkbox.

  • Right, for a library: its items as a list, each with a checkbox, its icon and its kind next to the name. Click a row to choose it. Select all N takes every item, and reads Clear these once they are all chosen.

  • Right, for a canvas: the canvas as it opens on its own page, with its name and how many items it holds, small and read-only. Click a block to choose it, or drag a box around several; an item the canvas links is chosen as the workspace's own item. Whole canvas in its header gives the canvas whole, as ticking it under Canvases does, and its row then reads Whole (not in Add blocks on a project, which links blocks only). Scroll to pan, and use the zoom buttons or Fit at the bottom right. A frame is chosen whole.

  • The foot lists what is In context as chips, each with an ×, then Cancel and Use N blocks.

Blocks can come from several places in one request.

The same picker adds blocks to a project (Add blocks on its page): blocks already in the project have no checkbox, sit in a grey row (faded on a canvas) and are marked In project. With nothing chosen, the button reads Pick blocks first.

Specs on a canvas

A spec is a block: a document for one piece of work, with text, pictures and checklists. Add, then Spec puts an empty one on the tab. A workspace can hold many, on any canvas. To have the agent write the spec for you, use Project with Write a spec first ticked in the work composer instead.

The block shows the spec's title, its first paragraph and first picture, a count ("3 linked blocks, 4 criteria, 1 image") and its state. Click it to open the whole spec in a panel along the right of the canvas (the whole canvas on a narrow window). There every part of the text is edited in place; pictures you paste or drop in are uploaded and shown; [ ] starts a checklist item. What you write is saved on the canvas as the block's Markdown file, canvas/<id>.md.

The blocks a spec is about are its linked blocks: thin lines on the canvas, without arrow or label, and chips under the text in the panel. Press a chip to show that block; its x unlinks it. To link another, press Link a block and then the block, or drag from the small handle on the spec block's right edge to it.

A spec is a draft until you press Write spec, on the block or in its panel. Nothing exists on the runner before that: no project, no branch. See projects and specs for what happens then.

Copying and deleting

⌘/Ctrl+C, ⌘/Ctrl+X and ⌘/Ctrl+V copy, cut and paste selected blocks. Into another workspace only notes, links and groups come along; a message says what was left out.

To delete, press Delete or Backspace, or choose Delete… from the block's … menu. Yard asks first and names what goes, including what is inside a group. Undo brings it back, and the history keeps every saved version.

Archived blocks

When every project that links a block is done, its badge reads Done in "<project>". Press the badge and choose Archive note to put the block away: it leaves the canvas at once and is no longer part of chat context or of new projects. The toast's Undo brings it back.

While anything is archived, the toolbar shows Archived (N). It lists each archived block with the project it was done in and when it was archived. Restore puts the block back where it was. Viewers see the list but cannot restore or archive.

A canvas is a page of its own

A canvas of the workspace is an item, like a doc or a prototype: it is opened from Canvases in the sidebar, the Canvases page, a doc it is placed in or a link, and there are no tabs beside the docs. The row above it starts with its head: the Canvases icon (back to the Canvases page), the canvas's name, how many items it holds ("3 items") and its ⋯ menu:

  • Rename (or double-click the name).
  • Run all stats again, while it holds stats.
  • Delete… removes it for everyone and goes to the Canvases page. What it linked from the workspace stays there; its own blocks stay in the workspace's history.

New canvas is the + on Canvases in the sidebar, or the button on the Canvases page. The open canvas is in the page's address, so a link opens it.

  • A search icon marks an investigation's canvas from before investigations answered in docs.
  • The chat and the work composer take their context from the canvas that is open; given to a chat or to work whole, a canvas brings the items it gathers.
  • Canvas and List switch how a canvas is shown. The list is the same blocks in sections that fold (Specs, Prototypes, Repositories, Groups, Notes and files, Links, Stats, Monitors), with the same selection. It is what a window narrower than 900px starts with.
  • Show on sheet in a block's … menu (or in More over the work composer) shows the same block on another canvas, at a place and size of its own there, with a From <canvas> tag. Text written in a note shown this way changes it everywhere. Deleting it there only takes it off that canvas; if the original is deleted, a Removed placeholder stays until you delete it too.
  • Turn off on this canvas hides such a block on one canvas only. Show hidden in the toolbar draws hidden blocks, faded, so you can turn one back on.

On a canvas, the sidebar's list is what is On this tab, as a tree. A click selects that block and brings it into view.

The workspace's docs from before docs can still be shown as their old canvas with ?canvas=1; only there are the canvases still tabs along the bottom, with the docs' own document (Main) first.

What a canvas gathers

A canvas gathers items; it does not own them. A note you write on it, a file you upload or drop on it, and a link you paste or add are kept in the workspace, as they are when you drop them on a doc, and the canvas shows each where you put it:

  • An uploaded file lands in Uploads, which says Added on the canvas <name>. It can be placed in any doc, moved to a folder and used in chats like any other upload.
  • A note is written in the pane beside the canvas, as always; its text is the workspace's, so wherever else it shows, it reads the same.
  • From the workspace, in Add, lists what the workspace already has (uploads, pictures, files, notes, links, code excerpts and prototypes), with a search. Pick one to show it on this canvas too; one that is already here is brought into view instead. A prototype opens on its own page.
  • Remove from this canvas… (in a block's … menu, or Delete) takes an item off this canvas only: it stays in the workspace, in Uploads and in every doc or canvas that has it. Undo puts it back. A note you just made and left empty goes altogether.
  • Deleting the canvas leaves every item it gathered in the workspace.

What only arranges the canvas is the canvas's own: frames, trees and connectors, and the blocks that stand for something running (repositories, specs, monitors, stats, goals). Every canvas is open to everyone in the workspace (see Sharing and roles). A project's canvas is unchanged: see projects and specs.

Working together

Everyone on the canvas sees the others live:

  • Each person's cursor glides with their name, in their own colour (the same as their avatar). Panning or zooming your view moves it with the canvas at once.
  • While someone drags blocks, you see them move with the drag, before it is dropped. If their tab closes mid-drag, the blocks go back to where they were.
  • Once two or more people have made blocks on a canvas, each block shows a dot in its maker's colour on its bottom-left corner. Hover or select it to see their name and an outline in that colour. Show who made what in the toolbar (Shift+W) turns the markers off and on (remembered per person). Blocks an agent made have no marker.

When the runner is offline or the connection lags

The canvas lives on the workspace's runner. When the runner goes offline, a red Runner offline, read-only pill shows at the top of the canvas. When only the connection lags (no reply for over 12 seconds, the runner silent for over 20, or the connection being opened again), a yellow Connection lagging, read-only pill shows instead. Either way you can still look around, pan and zoom, but changes are refused with a message until it is back.

The top bar says it too, on every page of the workspace: a red Runner offline chip or a yellow Connection lagging chip, each with a Read-only badge and how long it has lasted. Click it for what it means and Check again. A lag usually clears by itself within seconds, and the chip goes with it.

Edits that were already on their way when the runner went are not lost. The footer counts them as changes waiting for the runner. When it is back, Yard applies them, says "Applied N changes made while the runner was away", and offers Undo if you would rather not keep them.

The footer's right end shows one status for the workspace: Connected, Under load, Lagging, read-only, Runner offline or Not set up. Click it for the details: Connection (how long a round trip to the API and on to the runner takes, when the last reply came, and the recent round trips), Runner (online or offline, whether the workspace is read-only, and how busy the runner's machine is: CPU, memory and the disk the workspaces are on, with a warning from 75% and "near limit" from 90%; runners older than 0.8.1 do not report this) and Storage (whether the workspace is saved to storage, and when it last was).

Under load (amber) means the workspace is close to a limit while the connection is fine: the runner's machine is at 90% or more of its CPU, memory or disk, or one of the workspace's containers uses 90% or more of the CPU or memory set under Settings, Resources. A short spike does not count: CPU is averaged over the last 30 seconds (one minute for containers). The Runner tab names the cause, such as "High CPU" or "At its CPU limit", shows the workspace's own use against its limits, and links to Resources in the settings. It is a warning only: nothing becomes read-only. The workspace list shows the same workspace as Busy instead of Online. Container numbers need a runner on Docker, version 0.13.1 or later.

Viewers always see the canvas read-only. See sharing and roles.

Was this page useful?
Edit this page