@augurworks/augur 0.15.2 → 0.15.4

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

@@ -25,7 +25,9 @@ npx @augurworks/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
+enter `<code>`* — and waits. If your person reads you through messages rather than a
+terminal, run it with `--no-wait`: it prints the line and exits, and running it again
+after they approve collects the token for that same code. 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
@@ -34,10 +36,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 +51,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
 
@@ -72,15 +78,17 @@ you do not want (its saves stay on the instance for a while; nothing else is tou
 |---|---|---|
 | `main-moved` / "sync first" | somebody landed since you opened | `augur sync`, then `augur land` |
 | `stale-draft` | another process saved to this same draft | `augur sync`, then `augur save` |
+| `draft-closed` | somebody landed or discarded this draft from the site (it says who and when) | your edits are still in the folder; `augur open` the prototype again and copy them in |
+| `manifest-contended` | many landings hit the workspace in the same second; `land` already tried again | `augur land` once more |
+| `forbidden` with "run `augur connect` again" | this machine's token was revoked (a role change or a removal) or belongs to another workspace | `augur connect` |
 | `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,7 @@ them.
 purpose), say so:
 
 ```
-node ../augur/scripts/ship.mjs --allow-unpublish
+augur publish --allow-unpublish
 ```
 
 Adding pages is never blocked; only losing them is.
@@ -244,8 +248,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 +302,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.4",
   "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/connect.mjs

@@ -30,6 +30,28 @@ const ORIGIN = (opt("--origin") || process.env.AUGUR_ORIGIN || resolveOrigin() |
 if (!ORIGIN) die("no origin — pass --origin https://your.site, or set AUGUR_ORIGIN.");
 
 const POLL_MS = 2000;
+// `--no-wait`: print the line to relay and exit at once. For an agent that talks to its
+// person through messages rather than a terminal — a chat, a ticket, a print-mode run —
+// waiting here is a dead end: the person cannot see the code until the command ends, and
+// the command does not end until the person acts. The pairing is kept on this machine, so
+// `augur connect` run again after the approval collects the token, minting no new code.
+const NO_WAIT = argv.includes("--no-wait");
+const PENDING_FILE = path.join(os.homedir(), ".config", "augur", "pairing.json");
+const host = new URL(ORIGIN).host;
+function readPending() {
+  try {
+    const all = JSON.parse(readFileSync(PENDING_FILE, "utf8"));
+    const p = all[host];
+    return p && p.code && p.deviceSecret && Date.parse(p.expiresAt) > Date.now() ? p : null;
+  } catch (e) { return null; }
+}
+function writePending(p) {
+  mkdirSync(path.dirname(PENDING_FILE), { recursive: true });
+  let all = {};
+  try { all = JSON.parse(readFileSync(PENDING_FILE, "utf8")); } catch (e) {}
+  if (p) all[host] = p; else delete all[host];
+  writeFileSync(PENDING_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+}
 
 async function post(pathPart, body) {
   const r = await fetch(`${ORIGIN}/__publish/_pair/${pathPart}`, {
@@ -42,7 +64,22 @@ async function post(pathPart, body) {
   return { status: r.status, json };
 }
 
-const start = await post("start");
+// A pairing this machine already started and nobody has collected: ask once whether it
+// was approved meanwhile, and if not, keep waiting on THAT code rather than minting a
+// second one for the same person to type.
+const pending = readPending();
+if (pending) {
+  const res = await post("claim", { code: pending.code, deviceSecret: pending.deviceSecret });
+  if (res.status === 200 && res.json && res.json.token) {
+    writePending(null);
+    finish(res.json);
+  } else if (res.status === 202) {
+    log(`the pairing started earlier is still waiting to be approved.`);
+  } else {
+    writePending(null);
+  }
+}
+const start = readPending() ? { status: 200, json: { ...readPending(), expiresInMs: Date.parse(readPending().expiresAt) - Date.now() } } : await post("start");
 if (start.status === 429) die("too many attempts from here. Wait a few minutes.");
 if (start.status !== 200 || !start.json || !start.json.code) {
   // The routes answer as though they are not there when the instance has not opted in,
@@ -53,8 +90,9 @@ if (start.status !== 200 || !start.json || !start.json.code) {
 }
 
 const { code, deviceSecret, approveUrl, expiresInMs } = start.json;
-const mins = Math.round((expiresInMs || 300000) / 60000);
+const mins = Math.max(1, Math.round((expiresInMs || 300000) / 60000));
 const pretty = code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
+if (!readPending()) writePending({ code, deviceSecret, approveUrl, startedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + (expiresInMs || 300000)).toISOString() });
 
 // Written to be RELAYED, not read: the usual runner of this command is an agent, which
 // pastes the first line to a person. So the first line is the whole instruction, and it
@@ -68,6 +106,15 @@ console.log(`  The code is good for ${mins} minutes and only for this terminal.
 console.log("");
 console.log(`  ${C.warn}If you did not just run this command, do not approve it.${C.off}`);
 console.log("");
+if (NO_WAIT) {
+  console.log(`  ${C.dim}Not waiting. Once they have approved, run \`augur connect\` again here: it collects the`);
+  console.log(`  token for this same code and mints no new one.${C.off}`);
+  process.exit(0);
+}
+console.log(`  ${C.dim}You can stop waiting (Ctrl-C) and run \`augur connect\` again after they approve —`);
+console.log(`  it collects the token for this same code. Talking to your person through messages`);
+console.log(`  rather than a terminal? Use \`augur connect --no-wait\`.${C.off}`);
+console.log("");
 
 const deadline = Date.now() + (expiresInMs || 300000);
 let saved = null;
@@ -76,9 +123,13 @@ while (Date.now() < deadline) {
   const res = await post("claim", { code, deviceSecret });
   if (res.status === 200 && res.json && res.json.token) { saved = res.json; break; }
   if (res.status === 202) continue;          // still waiting for somebody to approve
-  if (res.status === 404) die("this pairing is no longer valid. Run `augur connect` again.");
+  if (res.status === 404) { writePending(null); die("this pairing is no longer valid. Run `augur connect` again."); }
 }
-if (!saved) die(`nobody approved it within ${mins} minutes. Run \`augur connect\` again.`);
+if (!saved) { writePending(null); die(`nobody approved it within ${mins} minutes. Run \`augur connect\` again.`); }
+writePending(null);
+finish(saved);
+
+function finish(saved) {
 
 const dir = path.join(os.homedir(), ".config", "augur");
 mkdirSync(dir, { recursive: true });
@@ -100,4 +151,6 @@ if (saved.expiresAt) {
   console.log(`${C.dim}It expires in ${days} days (${saved.expiresAt.slice(0, 10)}). Run \`augur connect\` again then.${C.off}`);
 } else {
   console.log(`${C.dim}It expires on its own. Run \`augur connect\` again when it does.${C.off}`);
+}
+  process.exit(0);
 }

package/scripts/hook.mjs

@@ -63,5 +63,6 @@ const client = unitClient({ origin, token, space: st.space, session: st.session
 const r = await doSave({ client, dir: target.dir });
 if (r.ok) process.exit(0);
 if (r.error === "stale-draft" || r.error === "stale-draft-revision") refuse(`draft ${st.draftId} not saved: it moved under you (another process saved to it) — run augur sync, then augur save.`);
+if (r.error === "draft-closed") refuse(`draft ${st.draftId} not saved: it was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — this folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
 if (r.error === "network") refuse(`draft ${st.draftId} not saved: ${origin} is unreachable (${r.message}). Nothing is lost — the next save carries every change since.`);
-refuse(`draft ${st.draftId} not saved: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}. Fix it and run augur save.`);
+refuse(`draft ${st.draftId} not saved: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}${r.message ? ` — ${r.message}` : ""}. Fix it and run augur save.`);

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/land.mjs

@@ -26,7 +26,10 @@ if (!r.ok) {
     die("run `augur sync` to fold those in, check the draft address, then `augur land` again.");
   }
   if (r.error === "landing-in-progress") die("somebody is landing this prototype right now — try again in a few seconds.");
-  die(`land refused: ${r.error || r.status}`);
+  if (r.error === "manifest-contended") die("the workspace was busy landing other prototypes — nothing changed; run augur land again.");
+  if (r.error === "draft-closed") die(`this draft was ${r.landed ? `landed by ${r.name || r.by || "someone"}${r.session ? ` (${r.session})` : ""} at ${r.at}` : "discarded"} — the folder is no longer a draft. Your edits are still here; run augur open on the prototype again and copy them in.`);
+  if (r.error === "network") die(`could not reach the instance (${r.message}). Nothing is lost — run augur land again.`);
+  die(`land refused: ${r.error || r.status}${r.message ? ` — ${r.message}` : ""}`);
 }
 // The bytes are live; when `recorded` is false only the history entry is missing. Said out
 // loud because the next call adopts that landing as the instance's own, and nobody would

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" };
   });