@marver-design/marver 0.10.1 → 0.11.0

package/dist/utm-CxC3QN5X.mjs

@@ -0,0 +1,20 @@
+//#region src/shared/utm.ts
+/** Automatic attribution for the powered-by links: every canvas tags its marver.design
+*  link so site analytics can see WHICH canvas sent a visitor - zero user setup.
+*  Conventional UTM semantics (stable groupings first, the variable last):
+*    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
+*    utm_medium   = the link unit ('powered-by')
+*    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
+*    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
+*/
+function poweredByUrl(canvasName, source, content) {
+	const slug = (canvasName ?? "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return `https://marver.design/?${new URLSearchParams({
+		utm_source: source,
+		utm_medium: "powered-by",
+		...slug ? { utm_campaign: slug } : {},
+		utm_content: content
+	}).toString()}`;
+}
+//#endregion
+export { poweredByUrl as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/content/img-lod.ts

@@ -35,6 +35,12 @@ const schedule = (job: () => Promise<void>): void => {
   pump()
 }
 
+// Decode-idle signal for the headless shot: 0 means no decode is running or queued. The shot
+// (src/server/shot.ts) polls this to know each image's first decode has settled - which pins
+// its aspect-ratio and so stabilizes the frame's measured height - before it measures and
+// captures. Harmless and 0 when there are no LOD images (nothing ever decodes).
+if (typeof window !== 'undefined') (window as { __mvLodBusy?: () => number }).__mvLodBusy = () => active + q.length
+
 interface Item { canvas: HTMLCanvasElement; src: string; bucket: number; token: number }
 const items = new Set<Item>()
 let scale = 0.2      // overview default until the shell primes the settled scale on frame-ready

package/src/client/frame-host/bridge.js

@@ -73,7 +73,9 @@ window.addEventListener('message', (e) => {
 })
 
 if (isHtmlFrame) {
-  const ready = () => post({ type: 'sh:ready', id })
+  // stamp the URL revision (see main.tsx) so the shell can drop a ready from a superseded document
+  const gen = new URLSearchParams(location.search).get('r') ?? ''
+  const ready = () => post({ type: 'sh:ready', id, gen })
   document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
 }
 

package/src/client/frame-host/main.tsx

@@ -77,7 +77,10 @@ async function boot() {
     for (const W of wrappers.reverse()) if (W != null) tree = createElement(W, null, tree)
 
     createRoot(document.getElementById('root')!).render(createElement(Boundary, null, tree))
-    post({ type: 'sh:ready', id, meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
+    // stamp the URL revision so the shell can drop a ready queued by a superseded document (one it
+    // auto-renavigated past) - a WindowProxy survives navigation, so a stale ready could otherwise
+    // mark a reloading frame ready. Mirrors the sh:measure generation guard.
+    post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
   } catch (err) {
     fail((err as Error).message)
   }

package/src/client/shell/App.tsx

@@ -710,6 +710,11 @@ export function App() {
       const s = useStore.getState()
 
       if (data.type === 'sh:ready') {
+        // a WindowProxy survives navigation, so a ready queued by a SUPERSEDED document (one the
+        // ready-watchdog auto-renavigated past) can arrive here; drop it by generation like
+        // sh:measure does, so a stale ready never marks a reloading frame ready.
+        const gen = el.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
+        if (String(data.gen ?? '') !== gen) return
         s.setStatus(nodeKey, 'ready')
       } else if (data.type === 'sh:error') {
         s.setStatus(nodeKey, 'error', String(data.message ?? 'unknown error'))

package/src/client/shell/canvas/FrameNode.tsx

@@ -7,6 +7,7 @@ import { threadHostKey } from '../keys.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
 import { primeCameraFor } from './camera-broadcast.ts'
 import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
+import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -47,7 +48,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   // B0.1: no reactive scale subscription - it re-rendered every FrameNode on every
   // pan/zoom tick. gestureScale below measures the world rect (the canonical source,
   // Law G-5); the stored scale is only a never-hit fallback, read lazily at drag time.
-  const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, setGesture, toast } = useStore.getState()
+  const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, reloadFrame, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
   // src is frozen at mount: theme changes ride sh:set-theme (never navigation), so
@@ -204,12 +205,40 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
   }, [node.nav])
 
-  // ready timeout: 10s without sh:ready -> error card with reload
+  // Reload the frame, assigning the fresh URL SYNCHRONOUSLY so the live iframe's src is current the
+  // instant a stale sh:ready (queued by the document we just superseded) could be processed - the
+  // App generation guard then drops it against the new src. reloadFrame bumps nav+manifestRev; we
+  // pre-apply the src here and advance navRef so the passive nav effect does not navigate a 2nd time.
+  const reload = (automatic: boolean) => {
+    const before = useStore.getState().nodes.find((x) => x.key === node.key)
+    if (!before || (automatic && !canAutoReload(before))) return
+    reloadFrame(node.key, automatic)
+    const after = useStore.getState().nodes.find((x) => x.key === node.key)
+    const f = useStore.getState().frameFor(node)
+    if (after && f && iframeRef.current) {
+      iframeRef.current.src = frameUrl(f, node.theme)
+      navRef.current = after.nav ?? 0
+    }
+  }
+  // latest-callback ref so the watchdog effect can call the current reload() without taking it as a
+  // dep (an unstable function there would reset the timer every render and starve the retry)
+  const reloadRef = useRef(reload)
+  reloadRef.current = reload
+
+  // ready watchdog: a slow dev server (Vite re-optimizing deps, or the box saturated by parallel
+  // Live Jam agents) can leave boot()'s module fetches unresolved past the deadline - that is a slow
+  // frame, NOT a failed one (a real failure posts sh:error immediately). So the first silent deadline
+  // auto-renavigates ONCE on a fresh rev; a second silence stays 'loading' (never a red error card).
+  // node.nav is a dep so a fresh navigation restarts the full budget; readyRetried flips true on the
+  // retry and bounds it to exactly one.
   useEffect(() => {
-    if (node.status !== 'loading') return
-    const t = setTimeout(() => setStatus(node.key, 'error', 'frame never reported ready (10s)'), 10_000)
+    if (!shouldArmReadyWatch(node, !!frame)) return
+    const t = setTimeout(() => reloadRef.current(true), 10_000)
     return () => clearTimeout(t)
-  }, [node.status, node.key, setStatus])
+    // depend on the frame's stable SIGNATURE, not the manifest object - that object is replaced on
+    // every manifest reconcile, so depending on it would reset the budget on unrelated frames during
+    // heavy Live Jam churn and starve the retry. kind/file still re-arm on a real file swap.
+  }, [node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
 
   const drag = (e: React.PointerEvent, mode: 'move' | 'e' | 's' | 'se') => {
     e.stopPropagation()
@@ -345,7 +374,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
             <span className="msg">{node.error}</span>
             <span className="dim">{frame.file}</span>
             <span className="row">
-              <button className="sh-no-pan" onClick={() => { setStatus(node.key, 'loading'); iframeRef.current && (iframeRef.current.src = frameUrl(frame, node.theme)) }}>
+              <button className="sh-no-pan" onClick={() => reload(false)}>
                 <ReloadIcon size={12} /> reload
               </button>
               <button className="sh-no-pan" onClick={() => { navigator.clipboard.writeText(`${frame.file}: ${node.error}`); toast('error copied for agent') }}>
@@ -354,6 +383,16 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
             </span>
           </div>
         ) : null}
+        {/* a frame still silent after its one auto-retry: a slow dev server, never a failure. A quiet
+            non-covering pill (not the red card) keeps it honest and offers a manual reload. */}
+        {node.status === 'loading' && node.readyRetried ? (
+          <div className="sh-loading sh-no-pan">
+            <span>still loading</span>
+            <button className="sh-no-pan" onClick={() => reload(false)}>
+              <ReloadIcon size={11} /> reload
+            </button>
+          </div>
+        ) : null}
         <iframe
           ref={bindIframe}
           className="sh-live"

package/src/client/shell/canvas/ready-watch.ts

@@ -0,0 +1,28 @@
+// Readiness-watchdog policy, kept pure so it can be unit-tested apart from the browser-coupled
+// store (which imports Vite virtual modules and can't load under vitest).
+//
+// The frame host posts sh:ready SYNCHRONOUSLY after it renders, so a frame that misses the
+// deadline has not failed - its dev-server module fetches just haven't settled (Vite re-optimizing
+// dependencies, or the box saturated by parallel Live Jam agents). A genuine failure takes the
+// separate immediate sh:error path. So a silent deadline earns exactly ONE automatic re-navigation
+// on a fresh revision; a second silence stays 'loading' forever (never a red failure card).
+
+export interface ReadyNode {
+  status: 'loading' | 'ready' | 'error'
+  readyRetried?: boolean
+  missing?: boolean
+}
+
+/** Arm the 10s watchdog only for a present, still-loading, not-yet-retried frame. A missing or
+ *  absent frame must NOT spend the one-shot allowance - it has no live iframe booting, and would
+ *  otherwise burn its retry before its file even arrives. */
+export function shouldArmReadyWatch(node: ReadyNode, hasFrame: boolean): boolean {
+  return node.status === 'loading' && !node.readyRetried && hasFrame && !node.missing
+}
+
+/** Whether an automatic (watchdog-driven) reload still applies: one shot, and only while the frame
+ *  is still silently loading. A frame that already went ready/error, or already spent its retry,
+ *  is left alone. */
+export function canAutoReload(node: ReadyNode): boolean {
+  return node.status === 'loading' && !node.readyRetried
+}

package/src/client/shell/store.ts

@@ -38,6 +38,10 @@ export interface Node {
    *  frame arrives - an authored size on a temporarily-missing frame is never touched. */
   sizeFallback?: boolean
   status: 'loading' | 'ready' | 'error'; error?: string; missing?: boolean
+  /** the frame's one automatic ready-retry has been spent (a slow dev server must not be reported
+   *  as a failed frame; see canvas/ready-watch.ts). Transient - cleared on any real ready/error and
+   *  on every fresh navigation. */
+  readyRetried?: boolean
 }
 /** A Live Jam notification: a persistent bottom-right glass pill for a Marver
  *  reply. Frame-first: the FRAME is the news (icon + title, blue), Marver + preview below. */
@@ -48,6 +52,7 @@ export const CONFIG: { viewports: Record<string, { width: number; height: number
 
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
+import { canAutoReload } from './canvas/ready-watch.ts'
 
 /** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
  *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
@@ -94,7 +99,7 @@ export const bumpManifestRev = () => { manifestRev++ }
 
 export function frameUrl(frame: FrameEntry, theme: string): string {
   return frame.kind === 'html'
-    ? `/${frame.file}?theme=${theme}`
+    ? `/${frame.file}?theme=${theme}&r=${manifestRev}`   // r= carries the generation for the sh:ready guard (static serving ignores it)
     : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}&r=${manifestRev}`
 }
 
@@ -175,6 +180,7 @@ interface State {
   resizeNode(key: string, w: number, h: number): void
   measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
   setStatus(key: string, status: Node['status'], error?: string): void
+  reloadFrame(key: string, automatic?: boolean): void
   removeNode(key: string): void
   select(key: string | null, additive?: boolean): void
   selectMany(keys: string[]): void
@@ -620,7 +626,7 @@ export const useStore = create<State>((set, get) => {
             n.w = vp?.width ?? d.w
             n.h = vp?.height ?? d.h
           }
-          if (arrived) delete n.sizeFallback
+          if (arrived) { delete n.sizeFallback; n.readyRetried = false }   // a fresh mount earns a fresh allowance
           n.missing = missing
           changed = true
         }
@@ -637,7 +643,7 @@ export const useStore = create<State>((set, get) => {
         if (!f?.contentWidth && n.sizeMode) { delete n.sizeMode; retinted = true }
         // an errored frame whose file IS in the fresh manifest gets one automatic retry
         // on a rev-stamped URL - the "unknown frame id" dead end must self-heal (#20)
-        if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; retinted = true }
+        if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; n.readyRetried = false; retinted = true }
       }
       // auto boards prune deleted frames outright - "auto-managed" must manage both
       // directions (friction log #15). Curated boards keep the explicit card.
@@ -793,7 +799,22 @@ export const useStore = create<State>((set, get) => {
       else scheduleSave()
     },
     setStatus(key, status, error) {
-      set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, status, error } : n)) }))
+      // any real ready/error resets the one-shot retry allowance, so a later manual reload or a
+      // fresh manifest earns its own auto-retry again
+      set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, status, error, readyRetried: false } : n)) }))
+    },
+    // Reload a frame on a fresh rev-stamped URL (dodges a poisoned-cache document, #20). The
+    // watchdog calls this with automatic=true after a silent deadline: it fires at most once per
+    // load (canAutoReload gates it) and marks readyRetried so a second silence never retries and
+    // never becomes an error. A manual reload passes automatic=false, granting a fresh allowance.
+    reloadFrame(key, automatic = false) {
+      const n = get().nodes.find((x) => x.key === key)
+      if (!n) return
+      if (automatic && !canAutoReload(n)) return
+      bumpManifestRev()
+      set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
+        ? { ...x, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: automatic }
+        : x)) }))
     },
     // plain select replaces; additive toggles membership. Interact survives only while its
     // frame stays selected.
@@ -884,7 +905,7 @@ export const useStore = create<State>((set, get) => {
       const nodes = s.nodes.map((n) => {
         if (!ids.has(n.frame)) return n
         if (frameIsLeased(n.frame, s)) { pending[n.frame] = revision; return n }
-        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 }
+        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false }
       })
       set({ nodes, pendingFrameRevisions: pending, ...(s.play ? { playUpdateRevision: revision } : {}) })
     },
@@ -897,7 +918,7 @@ export const useStore = create<State>((set, get) => {
       const pending = { ...s.pendingFrameRevisions }
       for (const id of ids) delete pending[id]
       const nodes = s.nodes.map((n) => apply.has(n.frame)
-        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 } : n)
+        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false } : n)
       set({ nodes, pendingFrameRevisions: pending })
     },
     setExternalLease(nodeKey, reason, on) {

package/src/client/shell/styles.css

@@ -426,6 +426,14 @@ body.sh-commenting .sh-lean { opacity: 0 }
   border: 1px solid currentColor; background: transparent; color: inherit; border-radius: 999px;
   padding: 4px 10px; cursor: pointer }
 
+/* still-loading pill: a slow (not failed) frame after its one auto-retry. Non-covering, sits above
+   the drag overlay (z2) so its reload button is clickable, and stays out of the frame's content. */
+.sh-loading { position: absolute; left: 8px; bottom: 8px; z-index: 6; display: inline-flex; align-items: center;
+  gap: 8px; padding: 4px 4px 4px 10px; border-radius: 999px; font: 500 11px -apple-system, system-ui, sans-serif;
+  color: var(--card-warn-ink); background: var(--card-warn-bg); box-shadow: 0 1px 4px rgba(0, 0, 0, .16) }
+.sh-loading button { display: inline-flex; align-items: center; gap: 4px; font: 600 11px -apple-system, system-ui, sans-serif;
+  border: 1px solid currentColor; background: transparent; color: inherit; border-radius: 999px; padding: 3px 9px; cursor: pointer }
+
 /* shared icon button (glass surfaces) */
 .sh-ibtn { display: grid; place-items: center; width: 28px; height: 28px; border-radius: 999px;
   border: 0; background: none; color: var(--glass-ink-3); cursor: pointer }

package/src/shared/utm.ts

@@ -4,12 +4,12 @@
  *    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
  *    utm_medium   = the link unit ('powered-by')
  *    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
- *    utm_content  = the placement ('gate' badge | 'shell' wordmark)
+ *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
  */
 export function poweredByUrl(
   canvasName: string | undefined,
   source: 'published-canvas' | 'dev-canvas',
-  content: 'gate' | 'shell',
+  content: 'gate' | 'shell' | 'sign-in',
 ): string {
   const slug = (canvasName ?? '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   const q = new URLSearchParams({

package/templates/instructions/configure.md

@@ -72,6 +72,10 @@ If collaboration is deployed, each engineer runs `marver comments connect
 cloud sync on top of git. Git carries the committed comments; `connect` adds
 the real-time stream from published viewers.
 
+On a canvas gated by Marver Sign In there are no per-engineer CLI accounts:
+identity accounts have no password to connect with. The repo connects once with
+the canvas's `MARVER_CLI_TOKEN`, acting as the owner - see instructions/publish.md.
+
 ## Dev identity (who comments render as)
 
 `marver dev` resolves the local author from `design/.local/` - never invent or

package/templates/instructions/jam.md

@@ -92,6 +92,10 @@ The `result.json` is the universal signal - it works even when you cannot see im
 throw shows the frame's own exception, "the frame rendered an error - ..."; an unreachable
 dev server or missing Chrome says so). So a crashed or blank frame is caught by the JSON
 alone. `"ok":true` means it painted - and THEN the PNG tells you whether it painted *well*.
+The result also reports the exact `width`/`height` captured: a content frame (a `Doc`) is
+shot at its natural width and its FULL height, so a wide layout or a long spec renders in
+full, not cropped. A frame tall enough to hit the capture cap comes back with
+`"truncated":true` and a `note` - split it or shorten it and re-shoot.
 
 (If you DO have a shell - `npx marver shot <scene/frame> [--theme dark]` is the same thing
 in one line, printing the PNG path.)

package/templates/instructions/publish.md

@@ -18,11 +18,32 @@ vars if the host has no CLI.
    `--boards a,b` overrides ad hoc (grants comment), `--all-boards` ships
    everything loudly.
 
-2. **The canvas password** - `MARVER_PASSWORD` at serve time. This is the READ
-   boundary: one shared password for GUESTS. Members never need it - their own
-   account signs them in at the gate, and invite links skip it entirely (the
-   token is the authorization). Rotating it therefore only affects guests.
-   No env var = an open canvas.
+2. **Who gets in** - pick ONE of two gates at serve time. They are alternatives,
+   not layers; setting both weakens the invite list to "an account OR whoever
+   has the password". No env var at all = an open canvas.
+
+   **Marver Sign In - `MARVER_ID_ISSUER`. Use this by default.** People sign in
+   as themselves (Google, or an emailed code) instead of sharing a secret. One
+   sign-in opens every canvas gated this way, there is no password to leak or
+   rotate, and removing one person removes exactly them. Needs
+   `MARVER_PUBLIC_ORIGIN` set to the canvas's exact public origin, and
+   `MARVER_DATA_DIR`.
+
+   ```
+   MARVER_ID_ISSUER=https://id.marver.design
+   MARVER_PUBLIC_ORIGIN=https://<the deployed url>
+   ```
+
+   **The canvas password - `MARVER_PASSWORD`.** The sovereign option, and the
+   right one when the canvas must depend on nothing outside itself: no outbound
+   request of any kind. One shared password for GUESTS; members never need it,
+   since their own account signs them in and invite links skip it entirely.
+   Choose it deliberately - offline or air-gapped hosting, or an explicit
+   preference for no third party in the sign-in path - not by default.
+
+   **Who may enter is decided by the canvas either way**, from the invite list
+   the owner keeps. Marver Sign In proves who somebody is; it has no say in
+   where they may go, and is never told the answer.
 
 3. **Collaboration on or off** - `MARVER_DATA_DIR` at serve time. Set it to a
    path on a PERSISTENT disk and the serve grows accounts + live comments.
@@ -35,9 +56,12 @@ vars if the host has no CLI.
 | Var | Meaning |
 |---|---|
 | `PORT` | listen port (hosts inject this) |
-| `MARVER_PASSWORD` | canvas password (guests' read credential); unset = open |
+| `MARVER_ID_ISSUER` | `https://id.marver.design` - people sign in as themselves (**preferred**) |
+| `MARVER_PUBLIC_ORIGIN` | REQUIRED with `MARVER_ID_ISSUER`: this canvas's exact public origin |
+| `MARVER_PASSWORD` | the sovereign alternative: one shared password; unset = open |
 | `MARVER_DATA_DIR` | persistent dir for `comments/` + `auth.json`; unset = no collaboration |
-| `MARVER_OWNER_EMAIL` | prints a single-use OWNER claim link in the deploy logs on first boot |
+| `MARVER_OWNER_EMAIL` | who owns an empty canvas. With Marver Sign In they just sign in; with a password, a single-use claim link prints in the deploy logs on first boot |
+| `MARVER_CLI_TOKEN` | generated 32+ char secret (`openssl rand -hex 24`) that lets this repo run `comments invite`/`revoke`/`sync` as the owner. Required with `MARVER_ID_ISSUER` - identity accounts have no password for the CLI to use |
 | `MARVER_TRUSTED_PROXY` | set to `1` behind a reverse proxy (Railway, Fly) so rate limits see real IPs |
 
 ## The host contract (works on any volume-capable host)
@@ -71,10 +95,17 @@ Then, once per service:
 ```bash
 railway init                      # or `railway link` an existing service
 railway volume add --mount-path /data
-railway variables --set MARVER_PASSWORD=<pw> --set MARVER_DATA_DIR=/data \
-  --set MARVER_OWNER_EMAIL=<owner@email> --set MARVER_TRUSTED_PROXY=1
+# The default gate: people sign in as themselves.
+railway variables --set MARVER_ID_ISSUER=https://id.marver.design \
+  --set MARVER_PUBLIC_ORIGIN=https://<the deployed url> --set MARVER_DATA_DIR=/data \
+  --set MARVER_OWNER_EMAIL=<owner@email> --set MARVER_TRUSTED_PROXY=1 \
+  --set MARVER_CLI_TOKEN="$(openssl rand -hex 24)"
+# ...or the sovereign alternative, if this canvas must depend on nothing external:
+#   --set MARVER_PASSWORD=<pw>   (instead of MARVER_ID_ISSUER/MARVER_PUBLIC_ORIGIN)
 railway up                        # uploads the repo; Railway runs build then start
-railway logs                      # ← the owner claim LINK prints here, once (see below)
+railway logs                      # with a PASSWORD gate, the owner claim link prints
+                                  # here once. With Marver Sign In there is no link -
+                                  # the owner simply signs in. See below.
 ```
 
 Republishing is just `railway up` again: the server unions the seeded logs on
@@ -83,7 +114,12 @@ the event log is single-writer by design.
 
 ## What the deployed gate offers (so you know what you're wiring)
 
-On a collaboration canvas the gate has three doors, one credential each:
+**With `MARVER_ID_ISSUER`** there is one door: people sign in at
+id.marver.design with Google or an emailed code, come back, and are let in if
+the owner's list has their address. Nobody types a canvas password because there
+isn't one. An address that is not on the list is refused by name, on screen.
+
+**With `MARVER_PASSWORD`** the gate has three doors, one credential each:
 - **Guest** - the canvas password → read-only across published boards.
 - **Member** - "Sign in instead" → their own email + password → read + comment.
   A member session IS gate passage; they never touch the shared password again.
@@ -92,9 +128,41 @@ On a collaboration canvas the gate has three doors, one credential each:
 
 ## Wiring people up (after first deploy)
 
-`MARVER_OWNER_EMAIL` makes the first boot print an owner bootstrap in the logs:
-a browser link (`<url>/#/i/<token>`) AND the exact repo command. The token is
-single-use. Claim it from the repo so this machine can mint invites:
+**With Marver Sign In**, the owner just signs in - `MARVER_OWNER_EMAIL` claims an
+empty canvas for that address, with no token to pass around.
+
+**To manage people from this machine, the canvas needs `MARVER_CLI_TOKEN`.**
+`comments invite`, `revoke` and `sync` sign the CLI in with a password, and
+identity mode has none. Generate a secret - do not choose one, nothing
+rate-limits this and nothing slows a guess down - set it on the canvas, and hand
+the same value back:
+
+```bash
+# on the canvas (deployment environment):  MARVER_CLI_TOKEN=$(openssl rand -hex 24)
+MARVER_CLI_TOKEN='<that same value>' marver comments connect https://canvas.example.com
+```
+
+Hex, not base64: an `Authorization` header carries letters, digits, `_` and `-`,
+and the canvas refuses to start on a value it could never accept. `--token` works
+too, but a value on the command line is visible to anything that can list
+processes, so prefer the variable.
+
+It acts as whoever owns the canvas, so let the owner sign in once first - until
+somebody owns it there is nobody for the token to be. `connect` trades it for an
+ordinary session and stores THAT, so the secret never lands in your repo.
+Rotating `MARVER_CLI_TOKEN` ends every session it minted.
+
+It is a deployment variable and not something a page hands out, because authored
+frames run same-origin in a canvas: frame code can read `mv_c` and ride the
+viewer's session, so anything a browser can mint, a frame can mint silently. A
+browser-approved device flow was built for this job and removed before release for
+that reason. Do not reintroduce one, and do not invent a workaround that posts to
+internal endpoints.
+
+**With a canvas password**, `MARVER_OWNER_EMAIL` makes the first boot print an
+owner bootstrap in the logs: a browser link (`<url>/#/i/<token>`) AND the exact
+repo command. The token is single-use. Claim it from the repo so this machine can
+mint invites:
 
 ```bash
 # 1. claim the owner account - copy the command the deploy logs printed:
@@ -125,5 +193,6 @@ through sign-in.
 - `<MARVER_DATA_DIR>/auth.json` - accounts (scrypt), sessions, invites, on the volume.
 - `design/comments/<board>.jsonl` - the dev-side mirror, git-tracked: feedback
   has history, and the volume has an off-site replica for free.
-- `design/.local/collab.json` - THIS machine's device credential. Gitignored;
+- `~/.marver/canvases/<project-hash>.json` - THIS machine's device credential, kept
+  OUTSIDE the repo because `marver dev` serves the repo;
   never commit it.