@augurworks/augur 0.15.1

package/agents/currency.md

@@ -0,0 +1,74 @@
+# What is current here — and what has been left behind
+
+Making a second version of a screen costs one folder, so a workspace fills up
+with abandoned paths faster than anyone tidies them. Nothing breaks when it does:
+the dead prototype still opens, still looks finished, and still sits in the
+gallery next to the live one. That is the failure to watch for — a shelf where
+current and abandoned look identical has stopped being a repository, and it never
+announces itself.
+
+Two facts answer it, and the workspace already records both: the **status**
+somebody set on a unit, and the **date its bytes last changed**. One call returns
+them together for every unit.
+
+## The call
+
+```
+GET https://<your-site>/__publish/<workspace>/currency
+Authorization: Bearer $AUGUR_TOKEN
+```
+
+Same token `augur connect` (or `augur login`) already saved for publishing; scoped to your workspace,
+so it answers about that one and no other. (A signed-in browser reads the same
+answer from `/__currency` — one function, two doors, because a person has a
+session and you have a token.)
+
+```json
+{
+  "staleAfterDays": 90,
+  "now": "2026-08-27T09:12:04.000Z",
+  "since": null,
+  "count": 2,
+  "units": [
+    { "key": "checkout/flow", "path": "/checkout/flow/", "space": "acme",
+      "status": "dev-ready", "statusLabel": "Dev ready",
+      "editedAt": "2026-08-25T14:02:11.000Z", "by": "a1b2c3d4",
+      "ageDays": 2, "stale": false, "when": "Edited 2 days ago" },
+    { "key": "checkout/old-flow", "path": "/checkout/old-flow/", "space": "acme",
+      "status": null, "statusLabel": null,
+      "editedAt": "2025-11-02T08:44:00.000Z", "by": "a1b2c3d4",
+      "ageDays": 298, "stale": true, "when": "Untouched for 9 months" }
+  ]
+}
+```
+
+`key` is the same key the status chip writes under, so a row joins straight onto
+`/__status`. `by` is a one-way id, never an address — resolve it to a person
+through the roster, not by guessing.
+
+## What changed here lately
+
+```
+GET …/currency?since=14d          # 2w, 36h and a bare number of days also work
+```
+
+Narrows `units` to what actually moved in that window — the whole of "what
+happened here recently", in one request, without walking a manifest. A window
+the server cannot read is refused with a `400`, never widened: an answer to a
+different question would read as a busy workspace.
+
+## Three things to know before you use it
+
+**`stale` has three values, and `null` is one of them.** A unit published before
+per-file dates existed carries no date, so the answer is "no record" rather than
+either extreme. Do not treat `null` as fresh, and do not treat it as abandoned —
+say you do not know. It resolves itself the next time that unit is published.
+
+**`staleAfterDays` is in the response because it is the instance's number, not
+yours.** Read it; never hardcode 90. A workspace that moves the threshold would
+otherwise keep hearing its old one from you.
+
+**Never add a field to record staleness.** It is computed from the date a publish
+already stamps, which is why it needs no upkeep. The tempting fix — a flag on a
+prototype saying it is archived — is accurate only for units somebody came back
+to mark, and the ones that matter are exactly the ones nobody came back to.

package/agents/drafts.md

@@ -0,0 +1,92 @@
+# 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.
+
+## The whole day, in four lines
+
+```
+augur open <opportunity>/<prototype>     # a folder of its own, live at once at its draft address
+…edit the folder…                        # every save is live at that address before your next step
+augur land [-m "what changed"]           # the real URL moves; the LAST LINE of stdout is the live URL
+augur sync                               # only when land was refused: fold main into your draft, land again
+```
+
+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
+a short id, for example `/checkout/flow/@k7f3q1/`. Everyone signed in to the workspace
+can look at it while you work; the prototype's real URL keeps serving what it served until
+you land. Two agents opening the same prototype get two drafts, are both told about each
+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).
+
+## Editing
+
+Edit the files in the folder `open` created. That folder holds that prototype and
+nothing else. Your editor's hooks — installed the first time `augur open` ran on this
+machine — save every edit to the draft before your next tool call, so the draft address
+is always what your files are. A refused save comes back in your next tool result with
+the reason; read it, it says what to do.
+
+The hooks also refuse two kinds of write, with the reason:
+
+- a file under a prototype in a **shared checkout** (a clone of the workspace) — open the
+  prototype instead; that is what the refusal tells you to run;
+- a file in a **read-only copy** (`augur read <unit>` puts one under `_read/`, for
+  context) — open the prototype if you mean to change it.
+
+Everything else — the workspace's design system, its docs, other projects — is untouched.
+If you are editing by hand in an editor with no hooks, `augur watch` inside the folder
+saves on every burst of changes; `augur save` saves once.
+
+## Landing
+
+`augur land` replaces the prototype's real URL with your draft, records who landed it and
+when, and closes the draft. It is refused in exactly one case: somebody landed on this
+prototype since you opened yours. Then:
+
+```
+augur sync     # takes main's changes into your folder; a real overlap is left for you to fold
+augur land     # again
+```
+
+`sync` writes one-sided changes outright and merges a file you both touched when the
+edits do not overlap. When they do overlap, your version stays in place, theirs is put at
+`.augur/theirs/<path>`, and the overlapping hunks are printed — fold them, then land.
+Nothing is guessed, on the server or here.
+
+`augur close` removes the folder once landed. `augur close --discard` abandons a draft
+you do not want (its saves stay on the instance for a while; nothing else is touched).
+`augur status` lists the drafts open on this machine and who else is on those prototypes.
+
+## When something is refused
+
+| It says | What happened | Do |
+|---|---|---|
+| `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` |
+| `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 |
+| 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.
+- 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/identity.md

@@ -0,0 +1,148 @@
+# Users, login, avatars
+
+## Getting in, if you are an agent
+
+You do not need a login. Publishing needs a **publish token**, and the way to get one
+is device pairing: `npx augur connect --origin <the workspace>` prints a link and a
+code, the owner enters the code in a browser they are already signed in to, and the
+token lands on this machine. Nobody's password is asked for, typed or stored. The
+instance says the same at `GET /llms.txt`. The full shape is in [README.md](./README.md)
+under *Getting in*.
+
+The `pass` field on a user record below is a first-sign-in seed for a **self-hosted**
+instance, consulted only when that person has no credential in the store yet. It is not
+a key: on a hosted workspace it is dead, on a self-hosted one it stops working the moment
+the person sets a password, and the gate throttles failed attempts. Never try it.
+
+## The account model
+
+The engine has per-user accounts. Sign-in is email + password on a self-hosted
+instance, or an emailed code from the central account store on a hosted one (no
+password exists there; see `ACCOUNT_ORIGIN` / `SESSION_KEYS`). The engine repo
+itself carries **no users** — `src/identity.json` is an empty placeholder; the
+live list lives in the instance's deploy shell repo as `identity.json` (NOT in
+this engine repo). Editing it is a config change: it only reaches the live site
+once the instance config is redeployed/published (build re-emits
+`dist/__config/instance.json` from it), never on a bare file save.
+
+## The user record
+
+`identity.json` is an ARRAY of user objects:
+
+```jsonc
+{
+  "email": "person@example.org",   // login id
+  "emails": ["alias@example.org"], // optional extra addresses that also log in
+  "name": "Person Name",
+  "role": "admin",                 // "admin" | "editor" | "viewer". Omit for editor.
+                                   // (`user` is the legacy spelling of "editor" and
+                                   // still reads as one — never a flag day — but
+                                   // nothing new should be written wearing it.)
+  "passHash": "pbkdf2$…",          // FIRST ADMIN ONLY — everyone else is invited
+  "initials": "PN",                // presence chip fallback
+  "color": "#7A5AF8",              // presence chip color
+  "avatar": "data:image/webp;base64,…"  // optional SEED photo; served at /__avatar/<key>
+}
+```
+
+### The three roles
+
+| | Sign in, comment, drive boards | Publish | Admin panel, tokens, delete |
+|---|---|---|---|
+| `viewer` | ✅ | ❌ | ❌ |
+| `editor` | ✅ | ✅ | ❌ |
+| `admin`  | ✅ | ✅ | ✅ |
+
+`viewer` is the role for an account whose password is public knowledge — a demo
+instance's `loginHint` credentials. It is refused a publish token at mint time, and
+any token it already holds stops resolving, so a demotion cannot leave the old
+privilege alive in a credential.
+
+**Changing a role** is a per-person control in the Admin panel (click a row →
+Role). It takes effect on the next request via a KV overlay, and the panel asks the
+deploy shell to commit the change to `identity.json` so the file stays the durable
+record — at which point the overlay entry drains itself. The one refusal: the **last
+admin cannot be demoted**, because an instance with no admin cannot be repaired from
+inside it (every admin route, the panel and the star-scoped publish token all
+require one).
+Promote someone else first.
+
+- **The panel can add and remove people without a commit, and the two records
+  converge.** The Admin page lists everyone as a table (name + email, role, last
+  active) with an **Invite** action and, on clicking a row, **Reset password** /
+  **Remove user**. Invite and remove write a runtime overlay on top of the file, so
+  the change is live instantly; the same action asks the deploy shell to commit it
+  to `identity.json`, and when the deploy that follows pushes the new config back,
+  the worker DRAINS every overlay entry the file now supersedes.
+
+  ⚠️ **The overlay is transitional by design, not a second record.** Left
+  un-drained the two disagree visibly: builds bake people-derived state into every
+  generated page, so an identity-file build and a live-roster build disagree about
+  who exists, and each publish flips hundreds of gallery pages between the two
+  renderings. `identity.json` stays the durable record — edit it when a change
+  should outlive the instance — while day-to-day onboarding is a click.
+- **Credentials are invite-set, never issued.** `identity.json` is the ROSTER —
+  who exists, not what they know. A new user is added with NO password; the admin
+  panel's **Reset / invite** action mints a single-use link (`/__invite?t=…`,
+  7-day expiry) that the maintainer copies and sends manually. Opening it lets the
+  user choose their own password. Passwords live only as PBKDF2 hashes in KV
+  (`users:secrets`) — the operator never sets, reads, or can recover one; "reset"
+  just revokes the old hash and mints a fresh invite. The one account that cannot
+  be invited is the **first admin** of a new instance; seed that one with a
+  `passHash` (`hashPassword` in the worker generates it). Password verification
+  accepts `pbkdf2$…` strings and nothing else, so a **plaintext** value in the
+  file is worse than useless: it resolves as that user's secret, which makes the
+  account read as active rather than pending, while no password on earth verifies
+  against it.
+  Account states: **pending** (on the roster, no hash → can't log in yet),
+  **accepted** (has set a password), **active** (accepted + recently seen).
+  Resetting or changing a password signs that user out (the session changes, so
+  their cookie stops matching) and revokes every publish token they minted.
+
+  ⚠️ **A reset writes a TOMBSTONE, not a deletion**, and the difference is the
+  whole of the guarantee: a key that is present holding `null` reads as "no
+  secret", where an ABSENT key falls back to whatever `passHash` the roster seeded.
+  Tidying a tombstone away would put a reset password straight back in service.
+- **Photos are self-serve, and the file does NOT win.** Anyone signed in sets
+  their own from the profile menu (Add / Change / Remove photo): the browser
+  square-crops and downscales the file to ~192px, then `POST /__me/avatar` stores
+  it in KV — the image under `avatar:<hash>`, a one-line pointer per person in
+  `users:avatars` — and it serves ungated at `/__avatar/u/<hash>` so presence
+  chips and contributor faces work on public pages. An `avatar` data-URI in
+  `identity.json` is a **seed**: it shows until that person sets their own, and
+  it comes back if they remove it. This is the one field where the runtime
+  overlay beats the config file, deliberately — a person's face is theirs.
+  A photo kept in `identity.json` keeps working as a seed, and can be dropped
+  once that person has set their own.
+  Admins cannot set someone else's photo (there is no email parameter on the
+  route) — removing a user clears theirs.
+- Publishing does not need the identity file: `publish.mjs` fetches sanitized
+  contributor profiles from the live worker (`/__publish/_instance/profiles`)
+  when no identity file is around, so bare-clone publishes keep the faces.
+
+## ⏳ Where this is going, and what is already true
+
+A workspace is becoming the only tier, and identity is splitting in two — a
+**credential is account-level** (one address, one password, several workspaces)
+and **membership is workspace-level**. That is not cosmetic: an admin who could
+reset a shared credential would silently become an admin of their colleague's
+unrelated workspace, so a workspace's own store holds no password and no hash of
+one, by construction rather than by care.
+
+What is already true, and what a doc reader should not be surprised by:
+
+- **A publish token expires.** Thirty days by default, set per instance. It used
+  to last forever. Where the instance offers device pairing, a missing or expired
+  token pairs itself inside the publish (`augur connect`: a link and a code for a
+  signed-in browser); see [publishing.md](./publishing.md) for the refusals and
+  what each one does.
+- **A viewer cannot hold one at all**, and a demotion invalidates the tokens the
+  account already minted rather than leaving old privilege alive in a credential.
+- **Removal is not erasure.** Removing somebody revokes their access and leaves
+  their name on the comments they wrote, deliberately: the thread is a record
+  other people are part of. Erasure is a separate, explicit act that redacts
+  authorship and keeps every message body and every reply intact.
+- **The self-hosted single-instance shape above is not going away.** `identity.json`
+  plus an admin-issued invite is how an instance with no account service works, and
+  it stays the recovery path for one — that is the case a hosted platform's
+  account-level credential does not cover.

package/agents/prototype-contract.md

@@ -0,0 +1,69 @@
+# What the engine expects of a prototype
+
+A prototype is a folder of **self-contained static HTML/JS** under
+`<opportunity>/prototypes/<name>/` with `index.html` as the entry. No build
+step: it must work opened directly (`file://`). The contents of `prototypes/`
+folders are published — `research.md`, `context.md`, anything else outside a
+published folder stays internal by the build's whitelist. **`playground/` also
+ships** (verbatim, to the public `/playground/`), so nothing private belongs
+there either.
+
+That `file://`-ability is a property of the *files* — it keeps them portable and
+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
+only, not shipped, nobody else can see it.
+
+Neither is ever offered as a choice. An agent doesn't ask "should I publish
+this?" or present "local or deployed?" as two valid outcomes — the moment a
+prototype works, it ships, and the reply is the live URL that follows from
+that, not a question that precedes it.
+
+Beyond that, the engine reads a few things *from* your prototype. None are
+required, but each one improves how the site presents and reviews it:
+
+## `<meta name="description">` — the prototype's one-line description
+
+The engine treats it as the prototype's agent-facing and human-facing blurb:
+gallery cards, link previews (OG description), and the canvas insert-picker
+catalog all carry it. Write one sentence stating what the prototype shows.
+It lives in the artifact, so it updates in the same commit that changes the
+prototype — keep it true.
+
+## `<body data-gv-screen="…">` — the screen contract for SPAs
+
+The comment overlay scopes each pin to the screen it was dropped on.
+Multi-page prototypes need nothing (the URL distinguishes screens). A
+prototype that **swaps screens without changing the URL** must publish its
+visible state to `<body data-gv-screen>` (update it whenever the screen
+changes) — otherwise every screen shows every comment, and pins appear to
+float on the wrong UI.
+
+## Titles and display names
+
+The folder name is the URL segment (kebab-case, name it like a URL). The
+site's display name for a prototype or opportunity can be renamed live from
+the site chrome (stored server-side, in KV — not in your repo), so don't fight
+a bad folder name after the fact; rename the display instead.
+
+## Status chips
+
+An optional dev-status chip per prototype comes from `prototype-status.json`
+at the workspace root (see its `_comment` for the format; values are `in-progress`,
+`dev-ready`, `ignore`); statuses are also cycled by clicking the
+chip on the live site (stored in KV, overlaying the committed baseline).
+
+## Posters and link cards
+
+A `preview.webp` (gallery card) and `og.jpg` (link share) in the prototype
+folder are welcome but not required — without them the card falls back to a live
+iframe and links get no image; maintainers shoot them with `scripts/shoot.mjs` /
+`scripts/og.mjs`.
+
+## Comments overlay assets
+
+Any file the overlay must load from a public page has to be public too — if an
+image inside your prototype 404s or renders as a login page when logged out,
+check it lives inside the prototype folder (published) rather than outside
+(internal).