@augurworks/augur 0.15.2 → 0.15.3

package/INSTALL.md

@@ -108,8 +108,9 @@ git clone https://github.com/andratwiro/augur.git augur
 The engine has no runtime dependencies — `login`, `publish`, `build` and `status` run on
 a bare clone with plain `node`. `npm install` is only needed for the Playwright-backed
 screenshot scripts. The commands below call the scripts by path
-(`node <parent>/augur/scripts/<name>.mjs`); `npm link` inside `augur/` gives you the
-shorter `augur <cmd>` form if you want it.
+(`node <parent>/augur/scripts/<name>.mjs`), which works on a bare clone;
+`npm i -g @augurworks/augur` gives you the shorter `augur <cmd>` form from the
+published package instead.
 
 Never nest one instance's parent inside another's — offline mode would serve both
 instances' spaces at once.

package/README.md

@@ -96,12 +96,14 @@ 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
+npx @augurworks/augur dev
 ```
 
+Or, with an engine clone beside the workspace instead of the package:
+`git clone https://github.com/andratwiro/augur.git` and `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 —

package/agents/README.md

@@ -34,10 +34,10 @@ are `augur open` and `augur land` instead — see [drafts.md](./drafts.md). To g
 tree from a hostname, pair first, then `npx @augurworks/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.
+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. `npm i -g @augurworks/augur` puts `augur` on the PATH for good; an engine
+clone beside the workspace still works too (`node <engine>/scripts/cli.mjs <verb>`).
 
 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` —
@@ -49,7 +49,6 @@ 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) |

package/agents/drafts.md

@@ -1,8 +1,8 @@
 # Drafts — how a prototype is changed on a workspace that serves them
 
 **Does this apply here?** Ask the instance: `GET /.well-known/augur.json` carries
-`drafts.enabled`. `true` → this document. `false` → [publishing.md](./publishing.md), and
-`augur ship` as before. `augur ship` on a drafts workspace refuses and points here.
+`drafts.enabled`. `true` → this document; `augur publish` refuses there and points here.
+`false` → [publishing.md](./publishing.md), which publishes a whole tree.
 
 ## The whole day, in four lines
 
@@ -16,6 +16,12 @@ augur sync                               # only when land was refused: fold main
 That is it. There is no commit, no push, no build. The URL `land` prints is what you hand
 the person you are working for — never a localhost, never a `file://` path.
 
+A prototype that does not exist yet: `augur open --new <opportunity>/<name>` gives you an
+empty folder and an empty draft; write its `index.html` and land. The same works for a
+library demo (`components/<name>`, `base/…`, `patterns/…`, `pages/…`) and for the
+workspace's design system (`skills/<prefix>-ui`), which is one unit like any other.
+Without `--new`, a name that does not exist is refused rather than guessed at.
+
 ## What a draft is
 
 Your own live copy of one prototype, at its own address: the prototype's URL with `@` and
@@ -25,7 +31,7 @@ you land. Two agents opening the same prototype get two drafts, are both told ab
 other, and both work — nothing locks, nobody waits.
 
 `augur open` prints who else has it open. That is the whole coordination step; there is
-nothing to leave and nothing to clear (working marks are for workspaces without drafts).
+nothing to leave and nothing to clear.
 
 ## Editing
 
@@ -74,13 +80,12 @@ you do not want (its saves stay on the instance for a while; nothing else is tou
 | `stale-draft` | another process saved to this same draft | `augur sync`, then `augur save` |
 | `would-unpublish` | the draft has no files (the folder is empty) | check the folder; a deletion is its own verb |
 | `not-a-prototype-folder` / `reserved-folder` | the path is not `<opportunity>/<prototype>` | name the prototype folder |
-| `units-not-configured` | this instance does not serve drafts | use `augur ship` — see publishing.md |
+| `units-not-configured` | this instance does not serve drafts | `augur publish` — see publishing.md |
 | no publish token | this machine is not paired | `augur connect` (never a password) |
 | unreachable | the instance could not be reached | nothing is lost; the next save carries every change since |
 
 ## What you never do
 
-- Ship a whole tree to a drafts workspace. `ship` refuses; `--legacy` exists for one
-  release and is not for you.
+- Publish a whole tree to a drafts workspace. `publish` refuses there, and `ship` is gone.
 - Wait for, or refuse over, somebody else's draft. Both work; the second landing syncs.
 - Hand over a path on disk as "done". Done is the URL `land` printed.

package/agents/prototype-contract.md

@@ -12,7 +12,7 @@ That `file://`-ability is a property of the *files* — it keeps them portable a
 buildless, nothing more. It is not a hand-off channel: publish the change and
 share the live URL (see `agents/publishing.md`). The only acceptable local
 stand-in, and only when publishing is genuinely impossible, is the real shell
-(`node ../augur/scripts/dev.mjs`), said out loud to be exactly that — local
+(`augur dev`), said out loud to be exactly that — local
 only, not shipped, nobody else can see it.
 
 Neither is ever offered as a choice. An agent doesn't ask "should I publish

package/agents/publishing.md

@@ -1,20 +1,22 @@
 # Publishing — how work in a workspace goes live
 
-**Where the workspace serves drafts, this is the legacy path** — `augur ship` refuses
-there and points at `augur open` / `augur land`; read [drafts.md](./drafts.md). The
+**Where the workspace serves drafts, this document does not apply** — `augur publish`
+refuses there and points at `augur open` / `augur land`; read [drafts.md](./drafts.md). The
 instance says which it is at `/.well-known/augur.json` (`drafts.enabled`). Everything
-below is for a workspace that does not serve drafts yet.
+below is for a self-hosted instance without a unit store, which still publishes a tree.
 
-**One command, every time:**
+**The command, every time your work is ready:**
 
 ```
-node ../augur/scripts/ship.mjs            # commit + publish + push, then print the live URL
-node ../augur/scripts/ship.mjs -m "…"     # with your own commit message
+augur publish                               # the working tree goes live; the last line is the URL
+git add -A && git commit -m "…" && git push   # then keep the repository true, yourself
 ```
 
-`augur ship` is the same thing, and only works if someone ran `npm link` in the
-engine clone on this machine. The `node …` form always works — prefer it in
-instructions, or an agent following them hits "command not found" and improvises.
+`augur` is the npm package `@augurworks/augur` (`npm i -g @augurworks/augur`, or
+`npx @augurworks/augur publish` for a one-off). On a machine that only has an engine
+clone beside the workspace, `node ../augur/scripts/publish.mjs` is the same command.
+(`augur ship`, which did the commit and the push for you, is retired: where drafts are
+served there is nothing to commit, and elsewhere the three steps are the two lines above.)
 
 Agents: this is the default, and it runs every time you finish a piece of work —
 not once at the end of a session. Hand the human the URL it prints: the live
@@ -29,7 +31,9 @@ checkout, and telling them to run `git pull` is a support ticket you created.
 Assume **none of them know what git is** — that is the design target, not a
 worst case.
 
-So: keep the engine clone current yourself. `publish` fast-forwards it
+So: keep the engine current yourself. A package install updates with
+`npm i -g @augurworks/augur@latest`, and `publish` prints exactly that line when the
+instance speaks a newer protocol than the package. A clone `publish` fast-forwards
 automatically when the instance speaks a newer publish protocol (clean tree,
 `--ff-only`, once per run), and re-runs itself — you will see
 `engine updated <a> → <b>`. When it cannot (uncommitted changes in the engine
@@ -173,10 +177,10 @@ site doesn't show your change, the answer is always the same: it wasn't publishe
 
 ## The command
 
-From the workspace repo's root (the engine clone must sit next to it):
+From the workspace repo's root:
 
 ```
-node ../augur/scripts/publish.mjs        # or: augur publish
+augur publish                            # or, clone-only: node ../augur/scripts/publish.mjs
 ```
 
 - Infers the workspace from the working directory; `--dry-run` and `--engine`
@@ -225,7 +229,11 @@ them.
 purpose), say so:
 
 ```
-node ../augur/scripts/ship.mjs --allow-unpublish
+<<<<<<< HEAD
+node ../augur/scripts/publish.mjs --allow-unpublish
+=======
+augur publish --allow-unpublish
+>>>>>>> 01da41b5 (npm: the engine speaks as a package — hooks, self-update and every contract)
 ```
 
 Adding pages is never blocked; only losing them is.
@@ -244,8 +252,7 @@ The first publish on a machine pairs it with your browser, on its own:
 
 Open the link in a browser where you are already signed in to the site, type the
 code, and the publish carries on. No password goes near the terminal, the shell
-history, or an agent transcript. `node ../augur/scripts/connect.mjs` (`augur connect`)
-runs that step by itself when you want it ahead of time. Agents: relay the link and
+history, or an agent transcript. `augur connect` runs that step by itself when you want it ahead of time. Agents: relay the link and
 the code to your human; that is the whole hand-off.
 
 `augur login` (web email + password) still exists for two cases: CI and scripts,
@@ -299,7 +306,7 @@ responses agree before declaring a chrome bug.
 
 ## Local preview (no publish involved)
 
-`node ../augur/scripts/dev.mjs` from the workspace root runs the full site shell
+`augur dev` from the workspace root runs the full site shell
 locally — login, rail, overlays, canvas, the same experience the live site
 gives (login `dev@local` / `dev` when no identity file is around). This is the
 **only** acceptable stand-in when you genuinely cannot publish, and always say

package/build.js

@@ -1875,28 +1875,6 @@ const PAGE_CSS = `
       .card-opp.is-stale .preview :is(iframe, .preview-img, .preview-ph) { transition: none; }
     }
 
-    /* ---- Working mark ("somebody is in here right now"; MARKS_JS stamps it) ----
-       The card-side face of an AGENT protocol: a tool leaves a mark before it starts
-       editing so the next tool reads it. This badge is the byproduct, and it is drawn
-       to be exactly that — it refuses nothing, covers nothing clickable, and takes
-       itself off the card the second the mark's TTL passes.
-       Top-RIGHT, because the status glyph owns bottom-left and the two must never
-       cover each other on a small card. */
-    .mark-badge {
-      position: absolute; right: 8px; top: 8px; z-index: 3;
-      display: inline-flex; align-items: center; gap: 6px; max-width: calc(100% - 16px);
-      padding: 3px 9px 3px 4px; border-radius: 999px;
-      background: #fff; box-shadow: 0 2px 8px -1px rgba(16,24,40,0.32);
-      font-size: 11.5px; font-weight: 600; letter-spacing: -0.005em; color: #101828;
-      pointer-events: none; /* a note is not a control */
-    }
-    .mark-badge__who {
-      flex: none; width: 16px; height: 16px; border-radius: 50%;
-      display: inline-grid; place-items: center;
-      font-size: 8px; font-weight: 700; letter-spacing: 0; color: #fff;
-      background: var(--faint);
-    }
-    .mark-badge__text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
     /* Draft chips — one per open draft on a prototype card, a count on a folder card.
        Bottom-left so they never fight the mark badge (top-right) or the status chip. */
     .draft-chips {
@@ -3095,80 +3073,6 @@ const FACE_JS = `
   wire();
 })();`;
 
-// Working marks, the card-side face of an AGENT protocol (`F-presence-marks`).
-//
-// A tool leaves a mark on a path before it starts editing so the next tool reads it; this
-// badge is the BYPRODUCT of that, not the point, and it is written to stay one. It reads
-// (`GET /__marks`) and never writes: a person with a tab open is not running a work-start
-// step, and inventing a mark for them would put a claim in the store nobody made.
-//
-// ⚠️ IT REFUSES NOTHING. It adds a note to a card. It does not disable the link, dim the
-// card, gate the menu or set anything another script could branch on to block — a mark
-// that stopped a click would be a lock, which is the one thing this feature is not.
-//
-// EXACT PATHS ONLY, deliberately. The CLI matches a mark against a path by containment,
-// because before you start work a mark on the folder above is the thing worth knowing. A
-// CARD is a published unit, so stamping a folder's mark onto each prototype inside it
-// would put "someone is working on this" on five cards nobody has touched. A folder has
-// its own card on the landing grid and gets the badge there.
-//
-// One fetch per page load, only on pages that have cards, and each badge takes itself off
-// at its own expiry — so a lapsed mark cannot outlive its meaning on an open tab, which
-// is the same guarantee the instance makes to every other reader.
-const MARKS_JS = `
-(function(){
-  function norm(p){
-    var s = String(p == null ? '' : p).trim();
-    if(!s) return '';
-    try { s = decodeURIComponent(s); } catch(e){}
-    s = s.replace(/^\\.\\//, '').replace(/\\/{2,}/g, '/');
-    if(!s || s === '/') return '/';
-    return '/' + s.replace(/^\\/+/, '').replace(/\\/+$/, '') + '/';
-  }
-  function pathOf(card){
-    var a = card.querySelector('a.preview-link[href], a[href]');
-    if(!a) return '';
-    try { return norm(new URL(a.getAttribute('href'), location.href).pathname); } catch(e){ return ''; }
-  }
-  function badge(card, m){
-    if(card.dataset.markDone) return;
-    card.dataset.markDone = '1';
-    var host = card.querySelector('.preview') || card;
-    var b = document.createElement('span');
-    b.className = 'mark-badge';
-    var who = document.createElement('span');
-    who.className = 'mark-badge__who';
-    who.textContent = m.initials || '?';
-    if(m.color) who.style.background = m.color;
-    var t = document.createElement('span');
-    t.className = 'mark-badge__text';
-    // "Someone" when the id behind the mark answers to nobody on the roster — a token
-    // labelled by hand, or a person who has since left. Never a guess at a name.
-    t.textContent = (m.by || 'Someone') + ' is working on this';
-    b.appendChild(who); b.appendChild(t);
-    host.appendChild(b);
-    var left = Math.max(0, +m.expiresIn || 0);
-    setTimeout(function(){ b.remove(); delete card.dataset.markDone; }, left);
-  }
-  function wire(){
-    var cards = [].slice.call(document.querySelectorAll('.card-proto, .card-opp'));
-    if(!cards.length) return;
-    fetch('/__marks', { credentials: 'same-origin', headers: { Accept: 'application/json' } })
-      .then(function(r){ return r.ok ? r.json() : null; })
-      .then(function(d){
-        if(!d || !d.marks || !d.marks.length) return;
-        var by = {};
-        d.marks.forEach(function(m){ if(m && m.path) by[norm(m.path)] = m; });
-        cards.forEach(function(card){
-          var m = by[pathOf(card)];
-          if(m) badge(card, m);
-        });
-      })
-      .catch(function(){ /* a note may never be the reason a gallery looks broken */ });
-  }
-  window.__gvMarksWire = wire;
-  wire();
-})();`;
 
 // Draft chips — the gallery's face of drafts that land (docs/drafts-that-land.md §5).
 //
@@ -6178,7 +6082,7 @@ const CHROME_CSS_BODY = `${FONT_CSS}${PAGE_CSS}${NAV_CSS}${TABBAR_CSS}`;
 const CHROME_JS_BODY = [
   CAROUSEL_JS, chromeScript(), STATUS_JS, CURRENCY_JS, COMP_STATUS_JS, CARD_MENU_JS,
   PINS_JS, PROFILE_JS, SETTINGS_JS, NEWCANVAS_JS, SPACE_JS, WORKSPACES_JS, TABBAR_JS(),
-  RESEARCH_JS, FACE_JS, MARKS_JS, DRAFTS_JS,
+  RESEARCH_JS, FACE_JS, DRAFTS_JS,
 ].join("\n;\n") + "\n;\n" +
   // Register the service worker (P0), shipped inside the already-cached bundle so
   // it costs pages zero inline bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augurworks/augur",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "files": [
     "scripts/",
     "build.js",

package/scripts/cli.mjs

@@ -4,13 +4,11 @@
 //   augur dev       full local shell in the current space folder (or workspace root)
 //   augur build     compose dist/ once
 //   augur deploy    build + direct-upload the whole site (see deploy.mjs)
-//   augur ship      commit + publish + push — the default way a change goes out
 //   augur publish   publish only, without committing or pushing (see publish.mjs)
 //   augur fork      copy a published artifact to a new URL, moving no bytes (see fork.mjs)
 //   augur status    what is live vs what your clones hold (see status.mjs)
 //   augur refine    render every component, photograph it, measure it against the
 //                   original, and report a pass-rate nobody can assert (see refine.mjs)
-//   augur mark      say what you are about to work on; read what everyone else is
 //   augur open      open one prototype into a folder of its own, live at once
 //   augur save      push every changed file in this draft folder
 //   augur land      replace the prototype's main with this draft
@@ -40,13 +38,11 @@ const map = {
   dev: "dev.mjs",
   offline: "offline.mjs",
   deploy: "deploy.mjs",
-  ship: "ship.mjs",
   publish: "publish.mjs",
   // The one publishing verb that needs no tree: two paths and a token (see fork.mjs).
   fork: "fork.mjs",
   status: "status.mjs",
   refine: "refine.mjs",
-  mark: "mark.mjs",
   // Drafts that land (docs/drafts-that-land.md): one prototype, one folder, live at once.
   open: "open.mjs",
   save: "save.mjs",
@@ -83,8 +79,18 @@ const map = {
   canon: "canon.mjs",
   build: path.join("..", "build.js"),
 };
+// Two verbs that are gone, answered rather than dropped: a person or an agent following an
+// older note lands on one sentence saying where the work went, not on "unknown command".
+if (sub === "ship") {
+  console.error("augur ship is retired. A prototype is changed by opening it: `augur open <opportunity>/<prototype>`, edit, `augur land` (engine agents/drafts.md). A workspace without a unit store still publishes a tree with `augur publish`.");
+  process.exit(1);
+}
+if (sub === "mark") {
+  console.error("augur mark is retired: a draft IS the mark. `augur open <prototype>` tells you who else has it open, and `augur status` lists what is open on this machine.");
+  process.exit(1);
+}
 if (!map[sub]) {
-  console.error("usage: augur <init|ship|dev|offline|build|deploy|publish|fork|status|canon|refine|mark|open|save|land|sync|close|read|watch|hook|clone|pull|export|restore|migrate|bundle-rekey|identity-rekey|adopt|freeze|thaw|connect|login> [options]");
+  console.error("usage: augur <init|dev|offline|build|deploy|publish|fork|status|canon|refine|open|save|land|sync|close|read|watch|hook|clone|pull|export|restore|migrate|bundle-rekey|identity-rekey|adopt|freeze|thaw|connect|login> [options]");
   process.exit(sub ? 1 : 0);
 }
 const child = spawn(process.execPath, [path.join(SCRIPTS, map[sub]), ...rest], {

package/scripts/clone.mjs

@@ -68,7 +68,6 @@ import {
   resolveUnit, unitFilesFromManifest, skillDirsReferenced, skillFilesFromManifest,
   rerootHtml, residualFindings, isText, isSkillInternal,
 } from "./lib/graduate.mjs";
-import { fetchMarks, marksOverlap, markLine } from "./lib/marks.mjs";
 
 const C = { dim: "\x1b[2m", warn: "\x1b[33m", bad: "\x1b[31m", ok: "\x1b[32m", off: "\x1b[0m" };
 const log = (m) => console.log(`\x1b[35m[clone]\x1b[0m ${m}`);
@@ -332,25 +331,6 @@ async function main() {
     console.log(`  ${C.warn}conflict${C.off}  ${c.path}  ${C.dim}${c.why}${C.off}`);
   }
 
-  // ── WHO IS ALREADY IN HERE (`F-presence-marks`) ───────────────────────────
-  //
-  // A pull is a work-start: files are about to be written into a tree somebody is about to
-  // edit. So the marks on the paths ABOUT TO BE TOUCHED are printed before the first byte
-  // lands, which is the only moment the information can still change what happens next.
-  //
-  // ⚠️ IT NEVER REFUSES AND NEVER CHANGES THE EXIT CODE. A mark is a note, not a lock, and
-  // a pull that stopped for one would be a lock with extra steps. Read on a URL rather than
-  // a source path: a mark names the published unit, which is what both sides can agree on.
-  const touching = [...plan.write, ...plan.conflict];
-  if (touching.length) {
-    const marks = (await fetchMarks(req))
-      .filter((m) => touching.some((f) => marksOverlap(f.url, m.path)));
-    if (marks.length) {
-      console.log(`\n  ${C.warn}somebody is working on paths this pull touches${C.off}`);
-      for (const m of marks) console.log(`    ${markLine(m)}`);
-      console.log(`  ${C.dim}Nothing here is blocked. It is worth knowing before you edit the same folder.${C.off}\n`);
-    }
-  }
   if (DRY) {
     log(`${C.dim}dry run — would write ${plan.write.length}, leave ${plan.skip.length} identical, ${plan.conflict.length} conflict(s)${C.off}`);
     process.exit(plan.conflict.length ? 2 : 0);

package/scripts/init.mjs

@@ -96,7 +96,7 @@ const html = `<!doctype html>
      and ships exactly as written.</p>
   <p>When it works, ship it: on a workspace that serves drafts,
      <code>augur open ${project}/${proto}</code> then <code>augur land</code>; otherwise
-     <code>augur ship</code>. Either way you get the live URL.</p>
+     <code>augur publish</code>. Either way you get the live URL.</p>
 </main>
 </body>
 </html>
@@ -119,4 +119,4 @@ log(`  space.json`);
 log(`  ${rel}`);
 if (wroteCanon) log(`  CANON.md`);
 if (!origin) log(`no siteOrigin set — add one to space.json (or pass --origin) so connect/login/publish work from this clone.`);
-log(`next: edit the prototype, then \`augur land\` (a workspace that serves drafts) or \`augur ship\`.`);
+log(`next: edit the prototype, then \`augur land\` (a workspace that serves drafts) or \`augur publish\`.`);

package/scripts/lib/adapters.mjs

@@ -16,12 +16,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
 
 // What identifies OUR entries in a settings file: the quoted script name and the event,
 // exactly as `hookCommand` spells them — so an entry survives the engine moving on disk
 // (the path changes, the tail does not) and nobody else's hook is ever mistaken for ours.
 export const HOOK_TAG = 'hook.mjs"';
-const OURS_RE = /hook\.mjs" (?:pre|post)$/;
+// Two spellings are ours: the clone-era `node "<path>/hook.mjs" pre` and the package-era
+// `augur hook pre`. Both are matched so an entry written by an older engine is replaced
+// on the next `augur open`, never duplicated.
+const OURS_RE = /(?:hook\.mjs" |(?:^|\s)augur hook )(?:pre|post)$/;
 export const HOOK_SCRIPT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "hook.mjs");
 export const UNIT_HOME_RE = /^(?:([^/]+)\/prototypes\/([^/]+)|(playground)\/([^/]+))(?:\/|$)/;
 
@@ -90,7 +94,22 @@ export const ADAPTERS = Object.freeze([
   }),
 ]);
 
-export const hookCommand = (event) => `node "${HOOK_SCRIPT}" ${event}`;
+/**
+ * The command a tool runs for one of our hooks. With the package installed globally
+ * (`npm i -g @augurworks/augur`) `augur` resolves on PATH and the hook says so, because
+ * the absolute path of a global install moves on every upgrade. Otherwise — a clone, or
+ * a one-off `npx` run — the absolute path to this engine's hook.mjs is the one thing
+ * guaranteed to exist.
+ */
+export const hookCommand = (event, { onPath = false } = {}) =>
+  onPath ? `augur hook ${event}` : `node "${HOOK_SCRIPT}" ${event}`;
+/** Whether `augur` resolves on this machine's PATH. Asked once, at install time. */
+export function augurOnPath() {
+  try {
+    const out = execFileSync(process.platform === "win32" ? "where" : "which", ["augur"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.trim().length > 0;
+  } catch (e) { return false; }
+}
 const ours = (h) => !!(h && Array.isArray(h.hooks) && h.hooks.some((x) => x && typeof x.command === "string" && OURS_RE.test(x.command.trim())));
 
 export function mergeHooks(settings, matcher, commands) {
@@ -146,7 +165,8 @@ function applyToAdapters({ home = os.homedir(), dryRun = false } = {}, decide) {
 /** Install the two hooks for every tool present on this machine. Idempotent; keeps every other hook. */
 export function installAdapters(opts = {}) {
   return applyToAdapters(opts, (a, cur) => {
-    const r = mergeHooks(cur, a.matcher, { pre: hookCommand("pre"), post: hookCommand("post") });
+    const onPath = typeof opts.onPath === "boolean" ? opts.onPath : augurOnPath();
+    const r = mergeHooks(cur, a.matcher, { pre: hookCommand("pre", { onPath }), post: hookCommand("post", { onPath }) });
     const had = !!(cur && cur.hooks && Object.values(cur.hooks).some((l) => Array.isArray(l) && l.some(ours)));
     return { ...r, did: had ? "updated" : "installed" };
   });

package/scripts/lib/draft.mjs

@@ -28,6 +28,18 @@ const MIME = {
 export const mimeOf = (name) => MIME[path.extname(name).slice(1).toLowerCase()] || "application/octet-stream";
 export const hashBytes = (buf) => createHash("sha256").update(buf).digest("hex");
 export const relOf = (unit, urlPath) => urlPath.slice(unit.length);
+/**
+ * A REPO folder or a URL, as the unit path it publishes to: `<project>/prototypes/<name>`
+ * is the nesting a space clone keeps, served at `/<project>/<name>/`. An agent has just been
+ * looking at the folder, so it is the spelling it will type.
+ */
+export function unitPathFor(input) {
+  const s = String(input == null ? "" : input).trim().slice(0, 300).replace(/\/prototypes\//g, "/");
+  if (!s) return "";
+  const t = s.replace(/^\.\//, "").replace(/\/{2,}/g, "/");
+  if (!t || t === "/") return "/";
+  return `/${t.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+}
 export const urlOf = (unit, rel) => unit + rel;
 
 export function scanFolder(dir) {
@@ -150,11 +162,19 @@ async function materialise(client, unit, table, dir) {
   }
 }
 
-async function doOpenImpl({ client, unit, dir, origin, space, session, now }) {
+async function doOpenImpl({ client, unit, dir, origin, space, session, now, isNew = false }) {
   if (fs.existsSync(dir) && fs.readdirSync(dir).length) return { ok: false, error: "folder-not-empty", dir };
   const createdFolder = !fs.existsSync(dir);
   const o = await client.open({ unit });
   if (o.status) return { ok: false, ...o };
+  // A unit with no files is one that does not exist yet. Creating one is a decision the
+  // caller states with `isNew`; without it, a typo would quietly open an empty draft on a
+  // prototype that was never there. Either mismatch hands the draft straight back.
+  const exists = Object.keys(o.table || {}).length > 0;
+  if (exists !== !isNew) {
+    try { await client.discard({ unit, draftId: o.draftId }); } catch (e) { /* best-effort */ }
+    return { ok: false, error: exists ? "unit-exists" : "unknown-unit", unit };
+  }
   // From here the server-side draft exists, so any failure below must both undo what we
   // wrote to disk and tell the server to drop the orphan — otherwise a retry finds a
   // half-materialised folder (`folder-not-empty`) and the draft it opened is never freed.
@@ -177,7 +197,7 @@ async function doOpenImpl({ client, unit, dir, origin, space, session, now }) {
     throw err;
   }
   const others = (o.presence || []).filter((d) => d.id !== o.draftId);
-  return { ok: true, draftId: o.draftId, address: `${origin}${o.address}`, files: Object.keys(o.table).length, others };
+  return { ok: true, draftId: o.draftId, address: `${origin}${o.address}`, files: Object.keys(o.table).length, others, isNew: !exists };
 }
 
 async function doSaveImpl({ client, dir, baseRevision, baseTable }) {

package/scripts/no-tenant-globals.mjs

@@ -224,6 +224,7 @@ const ALLOWLIST = {
       "mcpHostAllowlist",
       "CANVAS_REGISTRY",
       "PITI_REMARKS",
+      "DERIVED",              // the two store reads a derived gallery needs, per manifest version — the status baseline and the design-system catalog
       "ROSTER_OVERLAY",
       "FREEZE_STATE",
       "SUSPENSION_STATE",
@@ -281,6 +282,21 @@ const ALLOWLIST = {
     },
   },
 
+  // The derived pages: pure renderers over the live store. Every table here is a fact
+  // about the engine's vocabulary — tier names, status words and glyphs, the emoji pool a
+  // card's leading glyph is picked from — the same for every workspace.
+  "src/galleries.mjs": {
+    frozen: [
+      "TIERS",        // the four library tiers whose demos are units
+      "TIER_TITLE",   // their titles
+      "TIER_COPY",    // their hints and empty states
+      "STATUS_META",  // status word → label + class
+      "STATUS_ICONS", // status word → glyph
+      "STATUS_RANK",  // the card order a status implies
+      "EMOJI_POOL",   // the leading-emoji pool, picked by slug hash
+    ],
+  },
+
   "src/bundle-keys.mjs": {
     frozen: [
       "BUNDLE_TENANCY",       // which bundle-store families carry a workspace segment; one word per family is the revert, and a deploy-wide fact — moved here from the worker so the workspace object shares the key shape

package/scripts/open.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// augur open <prototype> [--dir <folder>] [--session <label>]
+// augur open <prototype> [--new] [--dir <folder>] [--session <label>]
 //
 // Open one prototype into a folder of its own, as a draft that is live at once at its own
 // address. Prints who else is drafting it. The folder holds only that prototype's files and
@@ -8,8 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { target, buildStamp } from "./lib/store.mjs";
-import { markPathFor } from "./lib/marks.mjs";
-import { unitClient, doOpen } from "./lib/draft.mjs";
+import { unitClient, doOpen, unitPathFor } from "./lib/draft.mjs";
 import { installAdapters } from "./lib/adapters.mjs";
 import { normUnit } from "../src/unit-core.mjs";
 
@@ -21,7 +20,7 @@ const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[
 
 const raw = positional[0];
 if (!raw) die("name a prototype: `augur open <opportunity>/<prototype>` (a folder path works too).");
-const unit = normUnit(markPathFor(raw) || raw);
+const unit = normUnit(unitPathFor(raw) || raw);
 if (!unit) die(`"${raw}" is not a prototype path.`);
 let origin, token;
 try { ({ origin, token } = target({ needToken: true })); } catch (e) { die(e.message); }
@@ -35,15 +34,18 @@ const session = process.env.AUGUR_SESSION || opt("--session") || `session-${proc
 const dir = path.resolve(opt("--dir") || unit.split("/").filter(Boolean).pop());
 
 const client = unitClient({ origin, token, space, session });
-const r = await doOpen({ client, unit, dir, origin, space, session, now: new Date().toISOString() });
+const isNew = argv.includes("--new");
+const r = await doOpen({ client, unit, dir, origin, space, session, now: new Date().toISOString(), isNew });
 if (!r.ok) {
   if (r.error === "folder-not-empty") die(`${r.dir} is not empty — pick another folder with --dir.`);
+  if (r.error === "unknown-unit") die(`${unit} does not exist here. To create it: \`augur open --new ${unit.replace(/^\/|\/$/g, "")}\`.`);
+  if (r.error === "unit-exists") die(`${unit} exists already — open it without --new.`);
   if (r.error === "units-not-configured") die("this instance does not serve drafts yet (no unit store bound).");
   if (r.error === "bad-unit" && r.reason === "reserved-folder") die(`${unit} sits under a folder the engine reserves — a prototype lives at <opportunity>/<prototype>.`);
   if (r.error === "bad-unit" && r.reason === "not-a-prototype-folder") die(`${unit} is not a prototype folder — name one as <opportunity>/<prototype>.`);
   die(`could not open: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}`);
 }
-log(`draft ${r.draftId} on ${unit} — ${r.files} file(s) in ${dir}`);
+log(r.isNew ? `draft ${r.draftId} on ${unit} — a NEW prototype; ${dir} is empty, write its index.html there` : `draft ${r.draftId} on ${unit} — ${r.files} file(s) in ${dir}`);
 // The agent tool's hooks, installed for this machine the first time a draft is opened
 // here (idempotent; `AUGUR_NO_ADAPTERS=1` skips it — the suite and CI set it).
 if (!process.env.AUGUR_NO_ADAPTERS) {