@augurworks/augur 0.15.1

package/README.md

@@ -0,0 +1,150 @@
+# Augur
+
+A prototype and research repository for product teams. Real, clickable
+prototypes and the design system they are built from, on one site with login,
+comments and live boards on top. Underneath it is all git and static HTML.
+
+**Building the prototypes is the easy part.** An agent can produce a convincing
+screen in a minute, and most teams already have more of them than they can find.
+What is missing is everything around them: where the last version went, who
+changed it, which of the four things called "the dashboard" is the one being
+reviewed, and where the feedback landed. That is what this is. Prototypes live
+in one place with the design system they are made from, comments stick to the
+pixels they are about, boards let you run the real screens side by side, and
+every version is a commit you can walk back to.
+
+It runs on your own box, or on somebody else's. There is no editor to be locked
+out of and no export to negotiate: a prototype is a folder of static HTML in a
+git repository you already own.
+
+**See it running: [demo.augur.works](https://demo.augur.works)**, sign in with
+`visita@fulla.demo` / `regadora`. It resets every night, so scribble away.
+
+![The projects gallery](docs/shots/gallery.png)
+
+The demo runs [Fulla](https://github.com/andratwiro/augur-space-fulla), an
+invented community garden product. That repo doubles as the starter space, so
+everything below works against it.
+
+## How a prototype gets made
+
+There is no editor. A prototype is briefed, not drawn. You describe the screen
+the way you would brief a designer, and an agent builds it as a page in the
+space, using the design system like anyone else on the team.
+
+The brief that made [Seed swap](https://demo.augur.works/garden/seed-swap/):
+
+```text
+Seed swap — a noticeboard where members offer saved seeds and claim each
+other's. One screen. A board of offer cards: who, what, roughly how many,
+which plot they came from — "Fava beans, saved from plot 12, ~40 seeds".
+Claiming an offer keeps the card on the board but settles it down visually;
+the swap happens at the shed, not in the app. The empty state suggests the
+first action instead of apologizing. Warm and hand-made like the rest of
+Fulla — use the fulla design system, don't invent new vocabulary. Add the
+one-line meta description. No routing, no backend; seed the board with a
+handful of believable offers.
+```
+
+![The agent building the seed swap screen from the brief, the browser hot-reloading into it, and a comment pinned on the result](docs/shots/authoring.gif)
+
+That is Claude Code in the capture; any coding agent that can read the
+contracts in [agents/](./agents/) does the same job. Screens in the demo space
+carry the session that made them: [open the repo and read one](https://github.com/andratwiro/augur-space-fulla/tree/main/garden/prompts).
+The follow-ups read like design direction, because that is what they are.
+
+## Boards where the prototypes run
+
+Drop a live prototype next to the stickies and drive it. Everyone on the board
+sees the same screen state. Agents join as pixel mascots and work next to you.
+Up close: the specimen spins inside its tile, a teammate's cursor works the
+area, and Menta the agent strolls over to watch.
+
+![A live prototype spinning on the board while people and agents move](docs/shots/canvas-live.gif)
+
+## Comments on the real pixels
+
+Shift+C on any prototype opens review mode. A pin sticks to the element it
+talks about, the thread keeps everyone's face on it, and the design system
+shows through as a layer.
+
+![Review mode on a prototype](docs/shots/review.png)
+
+## Build your design library
+
+The same space that holds your prototypes holds your design system. Tokens,
+base, components, patterns and pages each get a tier, every entry is a plain
+HTML page you write, and the site renders it with a live preview and the class
+names it documents. A small registry gives the review overlay the same
+vocabulary, so a pin on a prototype knows which component it landed on.
+
+![The components tier of the library](docs/shots/library.png)
+
+Up close, at the tokens depth: paddings shade in place like devtools, and the
+panel lists the tokens a component drinks with their live values. Token usage
+is tracked to the pixel across every prototype that links the system.
+
+![A component's padding shaded, its tokens listed with live values](docs/shots/tokens.png)
+
+## Try it locally
+
+**Under ten seconds from an empty folder to a page in your browser**, and that is
+a measured number rather than a hopeful one: three runs on a laptop with a fast
+connection came in at 7.3s, 9.0s and 9.2s, stopwatch from `git clone` to a `200`
+on `http://localhost:8788/` serving the real gallery. Most of that is the two
+clones, so a slower connection moves the number and nothing else does — the
+engine itself is about two seconds from cold to serving.
+
+```bash
+git clone https://github.com/andratwiro/augur.git
+git clone https://github.com/andratwiro/augur-space-fulla.git
+cd augur-space-fulla
+node ../augur/scripts/dev.mjs
+```
+
+There is no install step and no build step in that list, and that is not an
+omission: **the engine has no runtime dependencies**, so plain `node` is enough.
+What you get is the full shell — the gallery, the library, review mode, boards —
+with about a second of hot reload on every save. No login prompt, because a bare
+clone has no user list to gate against; add one and the gate turns on.
+
+Prototypes are self-contained static HTML, so `index.html` also opens straight
+from disk. That is fine for your own glance and never a way to show anyone
+anything: no chrome, no comments, no boards, and the link works on exactly one
+machine.
+
+## How it is put together
+
+- **A space is a git repo.** Your design system and your prototypes, nothing
+  else. Only the contents of `prototypes/` folders and the gallery tiers ever
+  publish. The research notes sitting next to them stay private by
+  construction.
+- **The engine is this repo.** It composes spaces into one static site and
+  runs the overlay worker on Cloudflare. It carries no secrets and no content.
+- **A private deploy shell holds your instance.** The engine pin, the user
+  list, every secret. Engine fixes reach your instance by pin bump, never by
+  forking.
+- **Publishing is `augur land`** on a workspace that serves drafts — open one
+  prototype, edit, land; seconds, atomic, with history. Self-hosted instances
+  without a unit store publish with `augur publish`. A git push saves and shares
+  work without deploying anything.
+
+## Run your own
+
+[INSTALL.md](./INSTALL.md) is the recipe, written to be executed top to bottom
+by a person or an agent. About an hour, most of it waiting on DNS and CI.
+
+## Docs
+
+- [CLAUDE.md](./CLAUDE.md), the engine conventions
+- [agents/](./agents/), the contracts for agents working in a space
+- [CANVAS.md](./CANVAS.md), the board engine and how agents co-work on it
+- [CONTRIBUTING.md](./CONTRIBUTING.md), fork to PR, never fork to deploy
+
+## License
+
+MIT for the code. See [LICENSE](./LICENSE).
+
+The name, the marks in `brand/` and the typefaces bundled with them are not part of
+that grant — [TRADEMARKS.md](./TRADEMARKS.md) says what you can do without asking
+(fork it, rename it, say what it is) and what needs a word first.

package/TRADEMARKS.md

@@ -0,0 +1,72 @@
+# Trademarks, brand assets and bundled fonts
+
+[LICENSE](./LICENSE) is MIT and covers the **code**. It does not, and was never meant to,
+hand over the project's name or the files in [`brand/`](./brand). This page says where that
+line is, because a bare MIT file placed next to a logo reads as though it grants the logo
+too.
+
+## What the MIT licence does not grant
+
+These are **unregistered** marks. That is what is true today and it is what this page
+claims — no more, because claiming a registration you do not hold is a misrepresentation,
+and no less, because an unregistered mark is still a mark.
+
+**The name.** "Augur", used as the name of a product, a service, a company or a domain.
+
+**The marks.** `brand/augur-mark.svg`, `brand/augur-icon.svg`, `brand/augur-eye.svg`, and
+the copies of them that a build emits (`augur-mark.png`, `augur-icon-192.png`,
+`augur-icon-512.png`, `augur-eye.svg`). Copying a file is not a licence to wear it.
+
+**The fonts.** `brand/lentianova.woff2`, `brand/lentianova-bulky.otf` and
+`brand/lentianova-median.otf` are **third-party typefaces, licensed to this project and not
+sublicensable by it**. They sit in the repository because the build needs them; they are
+not covered by the MIT grant, and no MIT grant could cover them, because they are not this
+project's to give. If you are shipping something built from this repository, obtain your
+own licence or substitute your own typeface — every font reference resolves through the
+design-system tokens, so replacing it is a value change, not a code change.
+
+> The project's own licence position on these typefaces is not yet settled for commercial
+> use. Until it is, treat them as the most restricted files in the repository.
+
+`src/canvas/DSEG7Classic-Bold.woff2` is different: it ships under the SIL Open Font
+License, and its terms are in [`src/canvas/DSEG-LICENSE.txt`](./src/canvas/DSEG-LICENSE.txt)
+alongside it.
+
+## What you can do without asking
+
+**Run it, fork it, change it, ship it.** That is what MIT is for, and none of the above
+narrows it. A fork that keeps the code and replaces the name and the marks needs no
+permission from anyone.
+
+**Say what it is.** "Built on Augur", "compatible with Augur", "an Augur instance" —
+describing a thing accurately by its name is nominative use, and it is fine. So is naming
+the project in a talk, a blog post, an academic paper or a comparison table.
+
+**Keep the marks in an unmodified copy.** Redistributing the repository as it is, marks
+included, is fine. What is not fine is lifting the marks out of it.
+
+## What needs asking
+
+Using the name or the marks in a way that suggests a project is **the** Augur, or is
+endorsed by, affiliated with or maintained by it. Concretely: naming your product or your
+company Augur or something confusable with it; registering a domain of the form
+`augur-<something>` for a service you run; putting the mark on a paid hosted service; or
+using it as the icon of an application that is not this one.
+
+Modified copies must not carry the marks. That is the whole point of the carve-out: the
+mark is how someone tells which copy they are looking at, and a mark on a fork makes that
+question unanswerable.
+
+## Asking
+
+Open an issue on the repository. There is no form and no fee.
+
+## In short
+
+Take the code. Leave the name.
+
+---
+
+*This page describes the position; it is not legal advice, and it has not yet been through
+a lawyer. The trademark itself is not yet cleared — see the project's own launch notes. If
+you are relying on any of this commercially, ask your own counsel.*

package/agents/README.md

@@ -0,0 +1,65 @@
+# agents/ — engine docs for agents working in a workspace
+
+These files are the engine's contract for the everyday things a **workspace
+collaborator's agent** does with Augur: shipping work, reading review feedback,
+what the engine expects of a prototype folder, the `space.json` schema, users
+and avatars.
+
+The word for the thing is **workspace** — one per instance, served at its root.
+The FILE is still `space.json` and every identifier keeps its old spelling; see
+[space-json.md](./space-json.md) for why that is a decision and not a leftover.
+
+They ship WITH the engine so every instance gets the same, current contract —
+when an engine change alters behavior, the same commit updates the doc here.
+Workspace repos should link to these files (the engine clone sits next to every
+workspace clone that publishes), never copy them: a copied contract drifts.
+
+## Getting in
+
+A workspace is a sign-in gate. Pages need a person's session; creating and publishing
+prototypes needs a **publish token**, and an agent gets one by device pairing, never by
+asking anyone for a password:
+
+```
+npx augur connect --origin https://<the workspace>
+```
+
+It prints one line to relay — *ask the owner of this workspace to open `<link>` and
+enter `<code>`* — and waits. The owner opens the link in a browser they are already
+signed in to and types the code; the token lands in `~/.config/augur/tokens.json`, and
+`augur ship` / `augur publish` use it from then on. `publish` runs the pairing itself when
+it finds no token, so inside a workspace tree nothing has to be done first. On a workspace
+that serves drafts (`/.well-known/augur.json` says `drafts.enabled`), the everyday verbs
+are `augur open` and `augur land` instead — see [drafts.md](./drafts.md). To get the
+tree from a hostname, pair first, then `npx augur clone --space <id>` — it reads the
+origin from the pairing.
+
+Not on npm yet? The engine clone sits next to every workspace that publishes:
+`node <engine>/scripts/cli.mjs connect --origin <origin>`. The instance says all of this
+itself at `GET /llms.txt` (and as data at `/.well-known/augur.json`); a signed-out
+request for an engine path answers `401` with the same facts.
+
+Two things an agent never does: type a password into a terminal (`augur login` exists
+for CI, and says so), and try the `pass` field from a deploy shell's `identity.json` —
+that is a first-sign-in seed for a self-hosted instance, dead on a hosted workspace, and
+the gate throttles failed attempts per address and per email.
+
+Read them by trigger, not up front:
+
+| When you are… | Read |
+|---|---|
+| asking what is current here, or what changed lately | [currency.md](./currency.md) |
+| starting work on a prototype somebody else might also be in | [working-marks.md](./working-marks.md) — read it BEFORE the first edit |
+| changing a prototype on a workspace that serves drafts | [drafts.md](./drafts.md) — open, edit, land |
+| shipping / going live on a workspace without drafts | [publishing.md](./publishing.md) |
+| acting on review comments | [review-feedback.md](./review-feedback.md) |
+| building a prototype folder | [prototype-contract.md](./prototype-contract.md) |
+| naming a canonical screen, or asked to "pull screens X, Y, Z" | [canon.md](./canon.md) |
+| editing `space.json` | [space-json.md](./space-json.md) |
+| building or forking a design system (`skills/<x>-ui/`) | [ui-skill.md](./ui-skill.md) |
+| asked to copy a design system out of a live product | [canon-extract.md](./canon-extract.md) |
+| adding users / avatars / login questions | [identity.md](./identity.md) |
+| a board-shaped ask (brainstorm, compare, map a flow) or canvas work | [canvas.md](./canvas.md) — includes WHEN to suggest a canvas |
+
+Engine *development* (build.js, worker, overlays) is a different audience:
+see [../CLAUDE.md](../CLAUDE.md) and [../CONTRIBUTING.md](../CONTRIBUTING.md).

package/agents/canon-extract.md

@@ -0,0 +1,117 @@
+# Extracting a design system from a live product
+
+`augur canon` turns "copy the design system from this URL" into a flow: a working folder,
+a fixed list of token roles, an evidence collector that runs where the login already is, a
+grader that is arithmetic rather than taste, and an emitter that writes the result into the
+workspace's design system.
+
+**Augur does none of the deciding.** Which of a product's eleven greys is its hairline, and
+which single colour means "act on this", is judgement. This engine ships the harness; the
+user's own agent, on the user's own account with whatever provider they like, does the
+judging. There is no model call in this repository, no API key, no endpoint, no inference
+dependency, and `augur canon` added none — `../test/canon-no-inference.test.mjs` fails the
+build on the commit that changes that.
+
+## Why a URL and not a repository
+
+Extracting a design system from a codebase is a solved problem and it is the wrong door for
+the person who needs this one. The people who feel the cost of not having a canon are
+product managers and designers: they hold a **login** to the product, not commit rights to
+it. So the collector runs inside the browser they are already signed in to, sees the real
+screens behind the login, and makes no request of its own.
+
+## The flow
+
+```
+augur canon start <url>     the working folder, the brief, the skeleton answer
+augur canon snippet         the collector to paste into your own browser
+augur canon collect <url>   or: read a PUBLIC page over HTTP
+augur canon collect --merge fold several screens into one observation
+augur canon grade           grade the answer
+augur canon apply           write it into the workspace's design system
+```
+
+`start` writes a `BRIEF.md` into the folder that names the actual URL, prefix and
+workspace, with the role table inline. **That file is written for an agent to follow start
+to finish**; hand it over rather than paraphrasing it.
+
+## The three files
+
+| File | What it is | Who writes it |
+| --- | --- | --- |
+| `observation.json` | evidence: ranked colours, type sizes, gaps, radii, shadows, the product's own custom properties, candidate class families | the collector |
+| `canon.json` | the answer: a value for each token role, plus named components | **the user's agent** |
+| the skill folder | `<prefix>-tokens.css`, `<prefix>-canon.css`, `skill.json`, `registry.json`, `CANON.md` | `apply` |
+
+The observation is ranked by how much of the screen a value actually covers, not by how
+many times it appears in a stylesheet — which is why the browser door is the better
+evidence as well as the only one that gets past a login. Text colour is weighted by the ink
+it puts on the page rather than by the box, so a full-height container inheriting a colour
+it never paints does not outrank the body.
+
+## One format, not two
+
+The roles in `../src/canon/schema.mjs` are exactly the tokens a workspace is born with (see
+`../seed/README.md`). That is enforced: `../test/canon-schema.test.mjs` fails if the seed
+grows a token the schema does not name, or reads one the extractor would not emit.
+
+It buys three things, and they are the reason the list is fixed rather than discovered per
+product:
+
+- **The screens a workspace already has re-skin instead of breaking.** Every prototype
+  links `<prefix>-tokens.css`; replacing the values moves all of them at once.
+- **The page that teaches the design system keeps teaching it.** `set-up-your-design-system`
+  reads the token file live, so after an extraction it shows the team their own product.
+- **A prototype written against one design system works against another.** Pulling a screen
+  from an example workspace into a real one is a copy, not a port.
+
+Roles marked *computed* may be left out; they are derived from the ones that were observed,
+and derived to be legible — a `mark-ink` computed from `mark` is guaranteed to clear 4.5:1
+as text on the sheet, which a colour picked by eye frequently does not. A value the roles
+have no slot for goes under an `x-` name and emits as a real token.
+
+## What `apply` will and will not do
+
+- **Regenerates** `<prefix>-tokens.css`. Safe because the roles are fixed.
+- **Creates** `<prefix>-canon.css` with the extracted components. Its own file.
+- **Never touches** the workspace's own component stylesheet (`<prefix>-ui.css`). That is
+  the workspace's writing, not the extractor's.
+- **Refuses** a class name the workspace already defines. Two rules for one selector in two
+  files is a bug that shows up on one screen and nowhere else.
+- **Merges** `registry.json` by name, keeping the workspace's own labels and descriptions.
+- Emits under the **workspace's** prefix even when the canon calls itself something else —
+  renaming a workspace's tokens orphans every prototype that reads them.
+
+## What the grader enforces
+
+Arithmetic only, and each rule exists because the failure it catches is invisible in a diff:
+
+- every observed role answered, every value the right kind;
+- the type scale and the space ramp climb;
+- body text clears 4.5:1 on the sheet, and so does the mark used as text;
+- **no component hard-codes a colour** — a component that does stops moving when a token
+  changes, and then the design system is decoration;
+- every `var()` a component reads is a token the canon defines;
+- every class carries the skill's class prefix, and the CSS defines every class it lists.
+
+`augur canon grade --space <workspace>` grades the design system a workspace is actually
+carrying, read back off disk. A workspace that has never been near the extractor should
+pass it.
+
+## Where it stops
+
+- The collector sees **rendered** values, so a colour that only exists in a state nobody
+  triggered — an error toast, a disabled row — is not in the evidence. Collect the screens
+  that matter, including the ugly ones.
+- It reads no images. A logo, an illustration style and a photographic treatment are design
+  system and none of them are in here.
+- **`font-display` and `font-body` are stacks, not files.** Nothing downloads a face, so a
+  stack naming a face the workspace does not already have falls back silently — and a near
+  fallback looks intentional, which makes it harder to notice, not easier. Self-host the
+  face and add the `@font-face` yourself, or name one that is already there.
+- A role typed `length` holds one length, so a `border-radius` SHORTHAND (four values, or a
+  slash) has no role. Put a representative length in the role so the scale still works and
+  carry the real shorthand as an `x-` token.
+- Dark mode is a second canon, not a second column: collect it separately.
+- A cross-origin stylesheet cannot be read for custom properties. Computed styles still
+  count, and the observation says how many sheets were unreadable.

package/agents/canon.md

@@ -0,0 +1,151 @@
+# The canon — how canonical screens and parts are named
+
+The canon is the part of a workspace that is meant to be **pulled by name**: "build it
+the way `invoice-detail` is built", "pull `invoice-list`, `invoice-detail` and
+`invoice-empty` and wire them together". That instruction is the whole return on having a
+design system, and it presumes `invoice-detail` names something an agent can find COLD —
+no human pointing, in a session that has never seen this workspace before.
+
+Names decide whether that works, and names drift the moment they are only a habit. One
+screen lands as `checkout-v2`, the next as `new_Checkout`, a third as a scratch folder
+wearing the same name as a canonical page, and the instruction stops resolving. Renaming
+everything afterwards works and costs a day. This file is the scheme that makes the day
+unnecessary, and `augur canon` is that scheme as a command.
+
+**Resolving a name is one line, and it needs nothing else read first:**
+
+```bash
+augur canon find invoice-detail    # → the tier, the folder, the entry page, what it links
+augur canon list                   # → every canonical name with its one-line description
+```
+
+Both read the tree at the moment they are asked. There is no index file, so there is
+nothing to regenerate and nothing that can be stale — the directory names ARE the index.
+That holds only while they obey the scheme below, which is what `augur canon check` is
+for.
+
+**If the workspace has no canon yet, this file is the second thing to read.** A team that
+would benefit from a canon usually already has one — their live product — and
+`augur canon <start|collect|snippet|grade|apply>` copies it out of there into this
+workspace's design system: see [canon-extract.md](canon-extract.md). Same command, same
+`canon` word, because it is the same job at a different stage; the scheme below is what
+the extracted result then gets named by. Note that the extractor's grading verb is
+`grade` rather than `check` — `check` is this file's verb, and it answers a different
+question (do the NAMES resolve, not do the TOKENS pass).
+
+## Where the canon lives
+
+Four directories at the workspace root. Each is published and gets its own tab on the
+site, and the build reads them directly — this is the engine's existing contract, not a
+new layout.
+
+| Where | What it holds | Pull it when |
+| --- | --- | --- |
+| `base/<name>/` | one atom, every state on one page | you need the button, the input, the badge |
+| `components/<name>/` | one composed component | you need the thing itself |
+| `patterns/<name>/` | an arrangement several screens repeat | you need the layout, not the parts |
+| `pages/<name>/` | a whole screen | somebody said "pull screens X, Y, Z" |
+
+Everything else in a workspace is **not** the canon, and a bare name never means one of
+them. A folder under `<project>/prototypes/` is a working prototype — an exploration,
+kept as the record of one. `playground/` is scratch. Both can be promoted; see
+[Growing the canon](#growing-the-canon).
+
+## The name
+
+**A canonical name is a directory name, and there is no second name.** The live site can
+rename what a card DISPLAYS (that override lives in KV, not in the repo) and it never
+changes what a name resolves to. If the two disagree, the folder is right.
+
+**Form.** Lowercase ASCII letters, digits and single hyphens — `^[a-z0-9]+(-[a-z0-9]+)*$`.
+No underscores, no spaces, no capitals, forty characters and four words at the outside.
+
+**Subject first, qualifier last.** `invoice-list`, `invoice-detail`, `invoice-empty` —
+never `list-of-invoices`, never `empty-invoice`. This is the rule that does the work:
+A→Z sorts a subject's screens together, so a directory listing reads as a table of
+contents and "pull the invoice screens" is one glance instead of a search. It is also
+what lets somebody who knows one name in a family guess the rest.
+
+**The qualifier comes from a closed set**, so the same idea is spelled the same way in
+every workspace and an agent told "the empty state of the invoice list" can write down
+`invoice-empty` without asking:
+
+`-list` · `-detail` · `-new` · `-edit` · `-empty` · `-error` · `-loading` · `-confirm` · `-success`
+
+Anything else at the end of a name is a second subject word, not a state. `-index`,
+`-view`, `-show`, `-create`, `-add`, `-blank`, `-none`, `-fail`, `-done` and `-ok` are
+the near misses — every one means a word already on the list, and `augur canon check`
+names them rather than renaming anything, because which of two words a team says is
+theirs to settle.
+
+**A name says WHAT, never WHEN.** `-v2`, `-final`, `-copy`, `-old`, `-wip`, `-draft`,
+`-tmp`, `-test`, a date, a ticket id — all refused. Every one encodes a moment in
+somebody's afternoon, and a name carrying one cannot be guessed by the person who has to
+pull it tomorrow. The version of a canon entry is its git history. (`-new` is on the
+allowed list because it is a state — the create screen; `-new2` is not.)
+
+**One name, one thing.** A name resolves in exactly one tier. Two tiers holding the same
+name fails `check`; a prototype or playground folder holding a canonical name is reported
+as a shadow, because the canon wins and that copy is one nobody will ever be sent to.
+
+**Every entry says what it shows**, in one sentence in `<meta name="description">` — the
+same tag the gallery card, the link preview and the canvas insert-picker already read
+(see [prototype-contract.md](./prototype-contract.md)). `augur canon list` prints it, and
+it is the only way a name is found by somebody who does not know it yet. An entry without
+one fails `check`, and `augur canon save` refuses to create one.
+
+## Growing the canon
+
+A canon that only grows when somebody schedules an afternoon for it does not grow. The
+promotion is therefore one command, run at the moment the screen is finished and still
+in front of you:
+
+```bash
+augur canon save orders/prototypes/order-detail        # → pages/order-detail/
+augur canon save playground/filter-bar --tier components
+augur canon save . --as invoice-detail --dry-run
+```
+
+What it does, and what each part of it exists to prevent:
+
+- **Copies, never moves.** The prototype stays where it is: comment pins are keyed to the
+  URL a screen was reviewed at, and the prototype is the record of the exploration. The
+  canon entry is the thing to copy from. When the two later disagree, `check` reports the
+  shadow rather than guessing which is current.
+- **Applies the naming rules, and says so.** A source folder called `order-detail-v2`
+  promotes as `order-detail`, with the change printed. `--as <name>` overrides.
+- **Repoints the design-system references for the new depth.** A prototype three levels
+  down references `../../../skills/<prefix>-ui/…`; a canon entry two levels down
+  references `../../skills/<prefix>-ui/…`. Getting that wrong produces a page that looks
+  correct on the site (the build rewrites the reference anyway) and opens unstyled from
+  disk — which is the failure that made promotion feel like a chore, because it is
+  invisible until somebody opens the file. This is the hand-edit the command exists to
+  remove.
+- **Refuses rather than half-doing it.** No description and no `--desc` → refused. A name
+  already used in another tier → refused. An entry already there → refused unless
+  `--replace`. `--dry-run` prints the identical plan and writes nothing.
+- **Writes `CANON.md` at the workspace root** if the workspace has none, so an agent
+  arriving cold finds the scheme by looking at the workspace rather than by being told.
+  Most workspaces already have it at birth — `augur init` scaffolds one and the seed ships
+  one — because the workspace whose names have already drifted is exactly the one that has
+  been worked in for a month without anybody promoting anything.
+
+Promotion is also how a planned page becomes a real one: a slug listed in `space.json`
+`pendingPages` shows on the site as a roadmap entry and drops off by itself the moment
+`pages/<slug>/` exists.
+
+## Checking it
+
+```bash
+augur canon check
+```
+
+Fails on the things that make a name un-findable: a name that is not lowercase-hyphen, a
+name carrying a version or a date, two tiers holding one name, an entry with no
+`index.html`, an entry with no description, and a skill reference that does not resolve
+from where the entry sits. Reports as advice: a near-miss qualifier, a name over four
+words, a prototype shadowing a canonical name, a missing `CANON.md`.
+
+A green run says the names are findable. It cannot say they are the right names for the
+things — whether `invoice-detail` is the screen a person would ask for by that name is a
+review question, and no lint has ever been able to answer it.

package/agents/canvas.md

@@ -0,0 +1,88 @@
+# Canvas — live multiplayer whiteboards, and when to suggest one
+
+Augur has an infinite-canvas layer: sticky notes, shapes, text, images, tables,
+drawings, arrows, sections, stamps, and **live prototype tiles** — all
+multiplayer (shared cursors, presence, co-typing) with an agent able to join the
+room as a visible participant. A canvas IS a prototype (a small loader page in
+the workspace repo), so boards publish, share, and comment like any other prototype.
+
+The deep reference — node schemas, the co-work protocol, engine internals — is
+**`../CANVAS.md`**. This file is the agent-facing contract only.
+
+## Suggest it — the ask-shape rule
+
+Canvas is a tool in your belt. When a request is **board-shaped, offer it** (one
+line: "this feels like a board — want me to set up a canvas?"); don't silently
+build one, don't wait to be asked:
+
+- "brainstorm / explore options / how might we…" → stickies + sections
+- comparing variants side by side → tiles of the alternatives + annotation
+- mapping a flow / journey / timeline / system → shapes + arrows + sections
+- workshop-style input from several people → a shared board beats a doc
+- reviewing many screens at once → prototype tiles arranged spatially
+
+## Making a board
+
+Copy any existing board folder — a short loader (`window.GV_CANVAS = {name}` +
+the two engine tags) — into `<opportunity>/prototypes/<board>/`, or use the
+in-app "＋ New canvas" button (signed-in users). Publish like any prototype.
+Boards are public by the same obscure-share-link model as prototypes.
+
+## Reading and writing a board
+
+- **Read:** `GET /__board?path=/<opportunity>/<board>/` → `{doc}`, where `doc` is
+  `{name, nameV, nodes, tombs, clock}` (or `{doc: null}` if the board was never
+  saved). `nodes` and `tombs` live INSIDE `doc`. Node types and their exact
+  fields: **`../CANVAS.md` § "Node schemas"** — the single write contract
+  (positions in world px, `rich` HTML whitelist, image `desc` rules).
+- **Write (full-state):** `POST /__board?path=…` with the body wrapped in a doc
+  envelope — `{"doc": {…, "nodes": [...]}}`. A bare node array (or any body
+  without `doc.nodes` as an array) 400s.
+- **Versions:** every node carries `v` + `vn` under last-writer-wins. Writing
+  through the proper doors (the ClawdCanvas client, `GVCanvas.addNode`, the
+  in-page editor) bumps automatically. Hand-rolling a full-state write over an
+  existing board: bump each modified node's `v` above what you read, or the room
+  keeps its copy.
+- **Images** upload via `POST /__asset` (content-hashed, immutable) — content
+  type must be `image/jpeg|png|webp|gif` (else **415**), 4MB cap (else **413**);
+  they read back at `GET /__asset/<40-hex-hash>`. Or point `src` at an image
+  committed in the workspace repo. Never write new data-URLs.
+
+## Co-working live (the default when changing a board)
+
+Join the board's room as a visible agent and stream per-node ops — never a
+full-state `POST /__board` while people are on it. The client:
+`../scripts/clawd-canvas.mjs` (`ClawdCanvas`; needs **Node 22+** for the global
+WebSocket) — connect, then `moveCursorTo`, `pose('thinking'|'sparkles'|…)`,
+`say()/unsay()`, `focus(id)`, `upsert/del/rename`, `dragNode`, `typeNode`,
+`status()`. Long sessions run the daemon (`node clawd-canvas.mjs daemon
+<boardPath> <cmdFile>` — launch detached; identity is derived, don't pass
+`--name` unless it's a `--sibling` agent — the daemon rejects a bare `--name`).
+
+**Show activity first:** the human watches the canvas, not your terminal. On any
+ask, your first move is visual — walk to the spot, pose, say what you're doing,
+stub the placeholder — *then* do the real work, and delete the stub when the
+artifact lands. Full protocol + daemon command set: **`../CANVAS.md` § "Working
+on the canvas"**.
+
+⏳ **A room is named by the PATH THE CLIENT SENDS, and that is not where this is
+going.** Today the path you pass is the room's identity, so two boards at the same
+path are the same room and the server takes the client's word for which one it is.
+Deriving the name server-side from the workspace plus the path is planned and not
+built. Nothing in this doc depends on which it is — you pass the board's path
+either way — but do not build anything that relies on choosing a room name, and do
+not read today's behaviour as a guarantee.
+
+**Origins:** with a deploy shell next door the client resolves them itself. From
+a bare workspace clone it works too: `space.json`'s `siteOrigin` supplies the site
+and the client connects through the site's `/__rt` proxy. Env overrides:
+`CANVAS_SITE_ORIGIN`, `CANVAS_RT_ORIGIN`.
+
+## Testing near canvases
+
+A test that opens a canvas page (or connects a client) **joins the real room and
+writes real data**. Isolate the room path onto a throwaway path — and it **must
+be under `/__test/`**: only `/__test/` rooms are RAM-only, every other path gets
+real DO SQLite + KV writes (there is no self-healing for a non-`/__test/` path).
+Use the `Object.defineProperty` clobber in **`../CANVAS.md` § "Multiplayer"** and
+block `POST **/__board` in Playwright routes.