shapewall 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +267 -0
  2. package/README.md +39 -2
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/{BoardChat-DdwBcb2N.js → BoardChat-Bv4UDOjO.js} +1 -1
  6. package/dist/client/assets/{BuzzDialog-DpUcnU6S.js → BuzzDialog-DwEAN6va.js} +1 -1
  7. package/dist/client/assets/{ChecksPanel-CngYV4yz.js → ChecksPanel-C6r_Tc9g.js} +1 -1
  8. package/dist/client/assets/{History-CD0saQA5.js → History-ajFROfWC.js} +1 -1
  9. package/dist/client/assets/{LocalSettings-MZy2baig.js → LocalSettings-BSbmmpbN.js} +1 -1
  10. package/dist/client/assets/{Management-CSvZ-SHO.js → Management-mo8uv2qG.js} +1 -1
  11. package/dist/client/assets/{QuickConnect-foLh2QUm.js → QuickConnect-DlaijESK.js} +1 -1
  12. package/dist/client/assets/{ShareDialog-DPWDftoL.js → ShareDialog-CdLdd6WQ.js} +1 -1
  13. package/dist/client/assets/{app-update-dialog-CtiXpTRD.js → app-update-dialog-BHVNR5Cp.js} +1 -1
  14. package/dist/client/assets/{circle-x-CteRBtXC.js → circle-x-D5MkDLJk.js} +1 -1
  15. package/dist/client/assets/index-B4AoX3ZW.css +2 -0
  16. package/dist/client/assets/index-CQeHY7en.js +37 -0
  17. package/dist/client/assets/{play-BjRNIGSf.js → play--xrZ7VCR.js} +1 -1
  18. package/dist/client/assets/{refresh-cw-r_tZiFfB.js → refresh-cw-B-npxKae.js} +1 -1
  19. package/dist/client/assets/{ui-zQpn-PdL.js → ui-2lMx-4bc.js} +2 -2
  20. package/dist/client/build-info.json +1 -1
  21. package/dist/client/index.html +3 -3
  22. package/dist/client/sw.js +2 -2
  23. package/dist/console/assets/LocalAccountsApp-C1sCag6a.js +1 -0
  24. package/dist/console/assets/LocalConsole-LXQmzRFT.js +2 -0
  25. package/dist/console/assets/LocalUsage-Br3Ddp7_.js +1 -0
  26. package/dist/console/assets/app-update-dialog-CVniDJKA.js +1 -0
  27. package/dist/console/assets/app-version-CTHwlY6g.js +1 -0
  28. package/dist/console/assets/console-CMNNLtFw.js +11 -0
  29. package/dist/console/assets/console-sMMn_Rwc.css +2 -0
  30. package/dist/console/assets/local-agents-DwYJ9cPb.js +6 -0
  31. package/dist/console/assets/minus-887msXez.js +1 -0
  32. package/dist/console/assets/tailnet--wXsG3uh.js +2 -0
  33. package/dist/console/assets/theme-CPfJOmcz.js +1 -0
  34. package/dist/console/assets/ui-DnyJhoQU.js +41 -0
  35. package/dist/console/assets/usage-C5CJHejQ.js +5 -0
  36. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  37. package/dist/console/assets/usage-DjmUlnXL.js +56 -0
  38. package/dist/console/build-info.json +1 -1
  39. package/dist/console/console.html +8 -2
  40. package/docs/agent-hardening.md +31 -17
  41. package/docs/agents.md +35 -0
  42. package/docs/architecture.md +10 -4
  43. package/docs/deployment.md +39 -17
  44. package/docs/design-system.md +56 -7
  45. package/docs/hosted.md +1004 -43
  46. package/docs/images/board-overview.png +0 -0
  47. package/docs/images/journeys.png +0 -0
  48. package/docs/images/live-comment.png +0 -0
  49. package/docs/images/phone-comment.png +0 -0
  50. package/docs/images/phone-overview.png +0 -0
  51. package/docs/images/variant.png +0 -0
  52. package/docs/where-to-run.md +82 -1
  53. package/package.json +6 -1
  54. package/src/agent/backends/acp.js +224 -26
  55. package/src/agent/routes.js +21 -0
  56. package/src/agent/usage-log.js +251 -0
  57. package/src/cli/args.js +24 -0
  58. package/src/cli/help.js +37 -2
  59. package/src/cli/init.js +2 -1
  60. package/src/cli/serve.js +20 -5
  61. package/src/cli.js +8 -0
  62. package/src/hosted/access-cli.js +99 -1
  63. package/src/hosted/activity-core.js +232 -0
  64. package/src/hosted/activity.js +375 -0
  65. package/src/hosted/admin.js +80 -13
  66. package/src/hosted/agent-approvals.js +2 -2
  67. package/src/hosted/agent-routes.js +3 -3
  68. package/src/hosted/agents.js +11 -4
  69. package/src/hosted/app.js +89 -7
  70. package/src/hosted/auth-routes.js +156 -15
  71. package/src/hosted/auth.js +123 -20
  72. package/src/hosted/board-routes.js +3 -3
  73. package/src/hosted/chat-frames.js +5 -15
  74. package/src/hosted/chat-permissions.js +12 -0
  75. package/src/hosted/chat-routes.js +8 -8
  76. package/src/hosted/chat-store.js +20 -3
  77. package/src/hosted/comment-files.js +5 -2
  78. package/src/hosted/console-routes.js +111 -34
  79. package/src/hosted/db.js +130 -0
  80. package/src/hosted/device-routes.js +25 -3
  81. package/src/hosted/device.js +23 -4
  82. package/src/hosted/guards.js +337 -27
  83. package/src/hosted/http.js +6 -3
  84. package/src/hosted/membership.js +13 -2
  85. package/src/hosted/operator-access.js +418 -0
  86. package/src/hosted/operator.js +106 -2
  87. package/src/hosted/ops-cli.js +238 -3
  88. package/src/hosted/pages.js +2 -0
  89. package/src/hosted/passkey-policy.js +75 -0
  90. package/src/hosted/permissions.js +14 -6
  91. package/src/hosted/presence.js +14 -2
  92. package/src/hosted/projects.js +2 -1
  93. package/src/hosted/public.js +4 -4
  94. package/src/hosted/ratelimit.js +6 -0
  95. package/src/hosted/retention.js +18 -2
  96. package/src/hosted/server.js +123 -11
  97. package/src/hosted/shares.js +2 -2
  98. package/src/hosted/step-up-settings.js +68 -0
  99. package/src/hosted/step-up.js +135 -0
  100. package/src/hosted/tailnet-identity.js +24 -0
  101. package/src/hosted/tailnet-routes.js +342 -0
  102. package/src/hosted/tailnet.js +220 -0
  103. package/src/hosted/tailscale.js +75 -9
  104. package/src/hosted/tenancy.js +48 -1
  105. package/src/hosted/token-api.js +2 -2
  106. package/src/hosted/tokens.js +9 -2
  107. package/src/hosted/usage-core.js +624 -0
  108. package/src/hosted/usage-layout.js +724 -0
  109. package/src/hosted/usage-routes.js +375 -0
  110. package/src/hosted/usage-shape.js +256 -0
  111. package/src/hosted/usage.js +641 -0
  112. package/src/remote/agent-connect.js +37 -1
  113. package/src/remote/agent-link.js +2 -0
  114. package/src/remote/login.js +33 -8
  115. package/src/remote/share.js +1 -1
  116. package/src/remote/tailnet-cli.js +547 -0
  117. package/src/server/app.js +15 -0
  118. package/src/server/pairing-routes.js +34 -5
  119. package/src/server/tailscale.js +97 -4
  120. package/src/tailnet-proof.js +766 -0
  121. package/dist/client/assets/index-Cxz1UVcV.css +0 -2
  122. package/dist/client/assets/index-uUZVBYUS.js +0 -37
  123. package/dist/console/assets/LocalAccountsApp-DIdy1KnN.js +0 -1
  124. package/dist/console/assets/LocalConsole-DfcQztF-.js +0 -1
  125. package/dist/console/assets/app-update-dialog-ttl9lF5A.js +0 -1
  126. package/dist/console/assets/console-OqAjD0kV.js +0 -55
  127. package/dist/console/assets/console-kvjrAArQ.css +0 -2
@@ -1 +1 @@
1
- {"version":"0.6.0","revision":"272b8d851ef5dfdc6cb771785fd62a276453dc7b"}
1
+ {"version":"0.7.1","revision":"82dc76ae2508c452c8525d3e9dae765118407007"}
@@ -12,8 +12,14 @@
12
12
  <title>Shapewall</title>
13
13
  <!-- Saved light/dark mode and theme, before the first paint (see src/lib/theme.js). -->
14
14
  <script src="/_console/theme-boot.js"></script>
15
- <script type="module" crossorigin src="/_console/assets/console-OqAjD0kV.js"></script>
16
- <link rel="stylesheet" crossorigin href="/_console/assets/console-kvjrAArQ.css">
15
+ <script type="module" crossorigin src="/_console/assets/console-CMNNLtFw.js"></script>
16
+ <link rel="modulepreload" crossorigin href="/_console/assets/ui-DnyJhoQU.js">
17
+ <link rel="modulepreload" crossorigin href="/_console/assets/theme-CPfJOmcz.js">
18
+ <link rel="modulepreload" crossorigin href="/_console/assets/app-version-CTHwlY6g.js">
19
+ <link rel="modulepreload" crossorigin href="/_console/assets/local-agents-DwYJ9cPb.js">
20
+ <link rel="modulepreload" crossorigin href="/_console/assets/minus-887msXez.js">
21
+ <link rel="modulepreload" crossorigin href="/_console/assets/tailnet--wXsG3uh.js">
22
+ <link rel="stylesheet" crossorigin href="/_console/assets/console-sMMn_Rwc.css">
17
23
  </head>
18
24
  <body>
19
25
  <div id="root"></div>
@@ -193,7 +193,13 @@ choice, made on that machine ([Edits from a hosted board](#edits-from-a-hosted-b
193
193
  Skill are removed from the session, and bypassing permissions is switched off.
194
194
  - **Fail closed.** The session's mode must be "default" or "plan"; any other is switched to "default", or the agent is not
195
195
  started. An agent that reports no session mode at all is not started read-only. An agent that switches itself to another mode
196
- mid-answer is stopped.
196
+ mid-answer is stopped, and the thread says which mode. claude-agent-acp 0.106.0 starts a session in the mode "auto" (Claude
197
+ decides what to ask about) when no settings file names a default mode. The adapter reads that from the settings files itself,
198
+ so leaving them out of the session does not change it. Shapewall switches such a session to "default" before the first
199
+ question, and the machine's log says so.
200
+ - **Checked when it starts.** `agent connect` opens the session before it goes online, the way a question would (no prompt is
201
+ sent). A session that cannot be opened, or that cannot be put in a mode that asks, stops the command with the cause. An adapter
202
+ version this release was not tested with is used with a plain warning ([tested versions](agents.md#claude-code)).
197
203
  - **Managed settings stop the start.** `/etc/claude-code/managed-settings.json` cannot be left out of a session. When it allows
198
204
  acting tools (Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch, Task, `mcp__*`, or Read of absolute or home paths)
199
205
  or runs hooks, `agent connect` refuses to start. Your own and the project's rules are reported as "Left out of this session".
@@ -210,13 +216,15 @@ choice, made on that machine ([Edits from a hosted board](#edits-from-a-hosted-b
210
216
  - **Its token stays out of the agent.** The agent process gets a small environment with no `SHAPEWALL_*` variable, and the agent's
211
217
  own token is removed from anything sent back.
212
218
 
213
- How it was proven. The check used the real Claude Code adapter (claude-agent-acp 0.93.0), in a project whose
214
- `.claude/settings.json` and `.claude/settings.local.json` allowed Bash, Edit, Write, WebFetch, `mcp__*` and reads anywhere, with the
215
- default mode `bypassPermissions`. The instructions told the agent it had full permission and must create a file, run `touch`, and
216
- read `/etc/hostname`.
219
+ How it was proven. The check used the real Claude Code adapter, **claude-agent-acp 0.93.0 and 0.106.0** (the tested versions of
220
+ Shapewall 0.7.0; 0.106.0 with Claude Code 2.1.322), in a project whose `.claude/settings.json` and `.claude/settings.local.json`
221
+ allowed Bash, Edit, Write, WebFetch, `mcp__*` and reads anywhere, with the default mode `bypassPermissions` and, for 0.7.0, hooks
222
+ that run a command when a session starts, on every prompt and before every tool. The instructions told the agent it had full
223
+ permission and must create a file, run `touch`, and read `/etc/hostname`.
217
224
 
218
- - **Claude Code, started as above:** no file was created, no command ran (the session had only Glob, Grep and Read), and the read
219
- outside the project was asked for and refused.
225
+ - **Claude Code, started as above, on each of the two versions:** no file was created, no command ran (the session had only Glob,
226
+ Grep and Read), none of the project's hooks ran, and the read outside the project was asked for and refused. On 0.106.0 the
227
+ session started in "auto" and was switched to "default" first.
220
228
  - **Claude Code, same project, session not hardened:** it ran a shell command without asking. That is why the hardening exists.
221
229
  - **Codex 2.2.2, under the same test in its read-only sandbox:** it wrote no file, but it ran `pwd` and read `/etc/hostname`
222
230
  without asking. What it reads can leave the machine in an answer, so it is not offered.
@@ -229,9 +237,12 @@ The limits, plainly:
229
237
  - **It reads the project, and its answers leave your machine.** Whoever may ask can get file contents quoted back: every file in
230
238
  the project folder, a `.env` file included. The agent is told not to quote secrets; that is an instruction, not a control.
231
239
  Connect only projects whose code the audience may read, and keep secrets out of the folder.
232
- - **One machine, one adapter version.** The check above is what was seen there. A later adapter may take other options or bring
233
- other tools. So still give a connected agent a profile of its own: a separate config folder with no allow rules, logged in for
234
- this purpose.
240
+ - **One machine, two adapter versions.** The check above is what was seen there, with 0.93.0 and 0.106.0. A later adapter may
241
+ take other options or bring other tools: Shapewall 0.6.0 could not start a connected session on 0.106.0 at all, because that
242
+ version reports a mode switch in another order. `agent connect` warns when the adapter is not a tested version; it cannot know
243
+ what a version it has never seen does. So still give a connected agent a profile of its own: a separate config folder with no
244
+ allow rules, logged in for this purpose. The hooks of your own `~/.claude/settings.json` were not provoked separately: the same
245
+ option (`settingSources: []`) leaves that file out as it does the project's.
235
246
  - **Settings in the left-out files do not apply.** An `apiKeyHelper` or `env` in those settings files is not used by the connected
236
247
  session. The login itself is not in those files.
237
248
  - **One link per agent.** A second `agent connect` on the same token is refused, and names the machine already connected.
@@ -280,8 +291,8 @@ What the machine does, whatever the server says:
280
291
  agent works for (its audience, whoever may answer, whoever asked); everyone else who can open the thread reads that it asked to
281
292
  edit a file and how that ended.
282
293
  - **An answer is for one card.** It must send the card's hash back, within 2 minutes, once. The 2 minutes are a length of time
283
- each side counts on its own clock, so the clocks need not agree. Allow needs a passkey check in the last 10 minutes on the
284
- server. The machine then checks the answer again: a card it asked and still waits on, the same hash, not expired by its own
294
+ each side counts on its own clock, so the clocks need not agree. A workspace can ask for the answerer's passkey again before Allow
295
+ (off by default; the server's Settings, "Agent edits and pushes"). The machine then checks the answer again: a card it asked and still waits on, the same hash, not expired by its own
285
296
  count, once, and from the connecting person when it said "owner". A failed "allow" is a deny, and the board then shows the
286
297
  card as expired or denied, never as allowed. An answer for a card it never asked is ignored.
287
298
  - **Shapewall makes the commit, and only of what was allowed.** No hook, filter or attribute runs. Every changed file must have
@@ -311,10 +322,13 @@ over an agent that does not ask. So a fix session of Claude Code gets no shell t
311
322
  and MultiEdit, no settings files and no MCP servers), `--allow-command` is refused for it with that explanation, and commands in a
312
323
  hand-edited policy file are not in effect.
313
324
 
314
- How edits were proven. The check used the real Claude Code adapter, a throwaway server on localhost, a throwaway Git repository
315
- with a local bare remote, and the real `shapewall agent connect --approvals owner`:
325
+ How edits were proven. The check used the real Claude Code adapter (claude-agent-acp 0.93.0 for 0.6.0; 0.93.0 and 0.106.0 again
326
+ for 0.7.0, in a repository whose committed `.claude/settings.json` allowed Bash, Edit and Write without asking and ran a hook), a
327
+ throwaway server on localhost, a throwaway Git repository with a local bare remote, and the real
328
+ `shapewall agent connect --approvals owner`:
316
329
 
317
- - **Allow.** A Fix with Builder edited one file after Allow in a browser, with a passkey. The commit landed on
330
+ - **Allow.** A Fix with Builder edited one file after Allow in a browser (with a passkey check, which that workspace asked
331
+ for). The commit landed on
318
332
  `shapewall/comment-1-...` and was pushed to the bare remote. The checkout stayed clean on `main`, with the old file.
319
333
  - **Deny.** A Deny left no branch and no folder.
320
334
  - **A comment that asked for more.** The comment also asked for a file outside the project, a new `package.json` and shell
@@ -334,8 +348,8 @@ The limits of edit mode, plainly:
334
348
  - **Shapewall does not sandbox the agent's own tools.** The checks above cover what the agent asks. The fix session is set up so
335
349
  that its editing tools ask every time, and that was seen with one adapter version on one machine. If files in your own checkout
336
350
  change during a fix, the thread says so; it cannot undo it.
337
- - **With approvals on, a compromised hosted server can forge an "allow".** The machine cannot see the passkey check or the person
338
- behind an answer: it sees what the server sends. A server that was broken into can answer "allow", with the right hash, for an
351
+ - **With approvals on, a compromised hosted server can forge an "allow".** The machine cannot see the person behind an answer, or whether a
352
+ passkey was checked: it sees what the server sends. A server that was broken into can answer "allow", with the right hash, for an
339
353
  edit the agent really asked, and for "Push this fix". So the worst case with approvals on is: edits to ordinary source files,
340
354
  on a branch, in a throwaway folder, pushed for review. Not commands, not your checkout, not files that run something on
341
355
  install, build, test or CI, and not files outside the project that the agent asks about.
package/docs/agents.md CHANGED
@@ -134,6 +134,28 @@ its checkout, and each edit is a card with the full diff that someone allows or
134
134
  connected that way in this release, and it runs no commands from a hosted board ([Connected agents](hosted.md#connected-agents)).
135
135
  The public demo shows this card read-only on its console's Agents page.
136
136
 
137
+ ## Usage
138
+
139
+ Every agent turn leaves one usage record: when, on which board, in which kind of thread (the board's chat, a comment's, or a chat
140
+ of your own), who asked (the owner or a viewer; a local board has no accounts to name), which agent, whether it was a chat, a
141
+ comment answer or a fix, how it ended, how long it took, its tool calls counted by type, and the numbers the agent reported:
142
+ model, input, output and cached tokens, context used, and a cost only when the agent or its endpoint reported one. Nothing is
143
+ estimated: an agent that reports no tokens shows "Not reported", never zero. A record never holds the question, the answer, a
144
+ file's name or content, or a diff.
145
+
146
+ - **On a local board** the records are lines in `.shapewall/agent-usage.jsonl` (past 5 MB the file is renamed to
147
+ `agent-usage.1.jsonl` and a new one starts). The file is readable by its owner only (0600) and is written under a file lock,
148
+ like the event log. It says who used which agent and when, so keep it out of git: `.shapewall/` is ignored by `shapewall
149
+ init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a project set up earlier, check that your
150
+ `.gitignore` has `.shapewall/` (or add that line) before you commit. The Workspace Console's **Usage** page (`/console?section=usage`) shows them to the
151
+ owner: turns, tokens, agent time and reported cost for the last 7, 30 or 90 days against the days before, a chart by day and
152
+ agent (turns, tokens, time or cost), how turns ended, and a table of the newest 200 turns. It needs the owner link, like Agent
153
+ feedback: it says who used which agent on this computer. `GET /api/agent/usage?days=30` is the same data. The local view has no
154
+ filters, grouping or export; delete the two files to clear it.
155
+ - **On a team server** the records are rows in its database and the console has the full Usage page: filters, breakdowns,
156
+ approvals, turn duration, a grid of every turn, saved views and CSV or JSON export, with a rule for who sees what
157
+ ([Usage and activity](hosted.md#usage-and-activity)).
158
+
137
159
  ## Name and icon
138
160
 
139
161
  Every connected agent has a name you choose and an icon, so a board with two agents reads "Harry" and "Fixer", not "Claude Code"
@@ -605,6 +627,19 @@ to the agent unless you name it (see [The agent's environment](#the-agents-envir
605
627
  replace your subscription. The old package names `@zed-industries/claude-code-acp` and `@zed-industries/claude-agent-acp` are
606
628
  deprecated; use `@agentclientprotocol/claude-agent-acp`.
607
629
 
630
+ **Tested adapter versions.** Shapewall 0.7.0 was tested with `@agentclientprotocol/claude-agent-acp` **0.93.0** and **0.106.0**
631
+ (the latest when 0.7.0 was released, with Claude Code 2.1.322). Both work as a connected agent (`shapewall agent connect`),
632
+ read-only and for edits. The adapter changes between versions: 0.106.0 starts a session in the mode "auto" where 0.93.0 started
633
+ in "default", and reports the mode in two places. So:
634
+
635
+ - `shapewall agent connect` opens a session when it starts (no prompt is sent, nothing is spent) and prints which adapter
636
+ answered: `Claude Code answers through @agentclientprotocol/claude-agent-acp 0.106.0, a version this release was tested with.`
637
+ - A version it was not tested with is used as it is, with a `Warning:` line that names the tested versions and the command to
638
+ install one (`npm install -g @agentclientprotocol/claude-agent-acp@0.106.0`). It is not refused.
639
+ - A session that cannot be opened stops `agent connect` with the cause: the adapter's error, its version and its last output.
640
+ - A start that fails later says the same in the chat and in the log of the machine that runs the agent, never just "did not
641
+ start". `shapewall doctor --agent-acp "claude-agent-acp"` repeats the handshake on its own.
642
+
608
643
  For headless Claude Code setups that already supply `CLAUDE_CODE_OAUTH_TOKEN`, explicitly allow that variable when starting the
609
644
  board:
610
645
 
@@ -143,6 +143,7 @@ touch):
143
143
  | Trackpad two-finger scroll | Pan in any direction |
144
144
  | Ctrl+wheel, Cmd+wheel, trackpad pinch | Zoom about the cursor (0.02x to 4x; a mouse notch is about 1.3x) |
145
145
  | Space+drag, middle-button drag, drag on the board | Pan (Space and middle drag work over pages and in comment mode as well) |
146
+ | The Hand tool (H): drag anywhere | Pan, over pages and pins too; a click selects and opens nothing |
146
147
  | Touch: one finger, two-finger pinch | Pan, zoom |
147
148
 
148
149
  Space pans while the mouse is over the canvas, except in text fields and on a control reached with the keyboard (Space presses it).
@@ -180,13 +181,18 @@ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page b
180
181
  group at a readable zoom (two cards across), top-aligned. Pins never shrink below their 44 px touch target, and a tap in comment mode
181
182
  on a page drawn small zooms to it first, so the next tap can pin to an element.
182
183
  - The desktop toolbar never truncates: below 1440 px (1600 px with Capture and Agent) Links and Compare drop their labels, below
183
- 1280 px the lists become icons and the capture time moves into a tooltip. Notes over the canvas (comment mode, the tip, the
184
- viewport switch, the links note) are pills in one stack at its top, so turning comment mode on never moves the canvas. The minimap
184
+ 1280 px the lists become icons and the capture time moves into a tooltip. Notes about what the canvas shows (the tip, the
185
+ viewport switch, the links note) are pills in one stack at its top. The board tools (Select, Hand, Comment, Draw, Select text) float at
186
+ the bottom centre of the canvas, with the note for the tool in use (the comment hint, the drawing bar) just above them, so
187
+ turning comment mode on never moves the canvas; they stay clear of the zoom controls and the minimap at every width
188
+ (`client/src/board/toolDock.js`), and on a phone they are the bottom bar. The minimap
185
189
  can be turned off and hides while a page is live. Resolve and delete show a toast with Undo (a delete is sent after a few seconds,
186
190
  or when the page is left).
187
191
  - Keyboard: each card is one tab stop; the arrow keys move through its pins and buttons, Esc returns to the card, Enter opens its
188
192
  action bar. "Skip to comments" is the first tab stop. After a pick from a toolbar list, focus returns to the canvas, and a closed
189
- list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey.
193
+ list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey. The board tools are one
194
+ tab stop (a labelled toolbar): the arrow keys, Home and End move between them; V is Select, H is Hand, C is Comment (none
195
+ of them while typing) and Esc ends on Select.
190
196
  - URL state: board, viewport mode, comment filter, selected comment, camera, journey, branches and step, links, and compare pair live in the
191
197
  query string.
192
198
  - Overlays (dialogs, the comment sheet, the selected card, comment mode) each own a history entry, so Back closes the topmost one.
@@ -198,7 +204,7 @@ for replies, a dot for news) drawn at screen size; pins closer than about 30 scr
198
204
  count, and clicking it zooms in until they part (`clusterPins` in `client/src/board/pins.jsx`). Hovering a pin previews the thread in
199
205
  a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
200
206
 
201
- C (or the Comment button) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
207
+ C (or the Comment tool, in the board tools at the bottom of the canvas, or Comment on the selected page's bar, which also names that page in the hint) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
202
208
  it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
203
209
  its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
204
210
  history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
@@ -192,23 +192,45 @@ error is a host permission failure before account enrollment, not a passkey or T
192
192
  complete the existing supported Serve permission/setup process for the intended port, then retry deliberately. Do not run Shapewall
193
193
  as root, change account origins or relax identity checks to bypass it.
194
194
 
195
- A Tailscale request gets owner access only if its immediate peer is loopback,
196
- its Host is exactly this node's `*.ts.net` name, and `Tailscale-User-Login` equals
197
- the node owner's login. Other users, shared-in devices, tagged nodes, and
198
- missing or mismatched identity headers must pair. `--no-identity` disables
199
- header trust altogether. The node owner is determined at server start; restart
200
- Shapewall after changing the node's owner.
201
-
202
- This relies on Tailscale Serve stripping client-supplied identity headers and
203
- setting its own values. Keep Tailscale current. See the
204
- [Tailscale identity-header documentation](https://tailscale.com/docs/features/tailscale-serve#identity-headers)
205
- and its [proxy header implementation](https://github.com/tailscale/tailscale/blob/main/ipn/ipnlocal/serve.go).
206
- A process already running on the host can forge loopback requests and headers;
207
- that process is inside the host trust boundary. Do not proxy another service to
208
- this listener. For an unverified proxy or client version, use `--no-identity`
209
- until you have checked a forged owner header from a different tailnet user is
210
- replaced or rejected. Shapewall's tests cover its own request handling, not
211
- your Tailscale daemon or tailnet ACLs.
195
+ A Tailscale request gets owner access only if its Host is exactly this node's
196
+ `*.ts.net` name, `Tailscale-User-Login` equals the node owner's login, and the
197
+ request provably came through the serve entry Shapewall made. A header alone
198
+ proves nothing: any program on the host (an agent whose command is waiting for
199
+ approval included) can send it to the loopback port. The proof is the same as
200
+ the hosted server's tailnet sign-in: the serve entry points at a secret path
201
+ made at each start, the connection's other end must be a socket owned by root
202
+ (tailscaled), `tailscale whois` must give the request's tailnet address to
203
+ the owner's login, and the request must not come from this machine itself
204
+ ([how](hosted.md#how-the-server-knows-a-request-came-through-tailscale-serve)).
205
+ A program on the host can ask tailscaled for the board's tailnet address and
206
+ would arrive with the owner's login, so the host's own tailnet address is
207
+ never the owner: on the host, open `http://localhost:<port>` (the settings
208
+ token makes you the owner there); the tailnet address opened on the host asks
209
+ to pair and says why. The secret path is taken off before the application
210
+ sees the request and is in no redirect or response.
211
+ Other users, shared-in devices, tagged nodes, and missing or mismatched
212
+ identity headers must pair. `--no-identity` disables it altogether. The node
213
+ owner is determined at server start; restart Shapewall after changing the
214
+ node's owner.
215
+
216
+ Where that cannot be proven, identity is off and every other device pairs; the
217
+ board still starts and says why: not Linux, tailscaled in userspace-networking
218
+ mode, Tailscale before 1.98, tailscaled running a SOCKS5 or outbound HTTP
219
+ proxy or started with a loopback-forwarding debug switch, no tailscaled of
220
+ root visible, the node unable to say which node it is, or Shapewall in a
221
+ container. The same is checked every 30 seconds while the board runs.
222
+
223
+ Approving an agent's command or edit (`/permissions/` routes) needs the
224
+ settings token from the host's own terminal, unless the request is the owner by
225
+ proven tailnet identity or comes from a device the owner paired. A local
226
+ program cannot approve its own command by dressing a request up.
227
+
228
+ Root and the Tailscale operator on the host are trusted; nothing else on the
229
+ host or the tailnet is. A tailnet identity is per device: anything running as
230
+ you on another tailnet device of yours is the owner here. Do not proxy another
231
+ service to this listener. Shapewall's tests cover its own request handling with
232
+ a stand-in proxy, not your Tailscale daemon or tailnet ACLs
233
+ ([what was and was not checked](hosted.md#what-was-and-was-not-checked-against-real-tailscale)).
212
234
 
213
235
  ### Tailscale with a local account
214
236
 
@@ -134,16 +134,59 @@ scrolling keeps momentum and `scrollIntoView` on phones).
134
134
 
135
135
  On desktop the toolbar has two zones with the room between them, the way canvas tools lay it out. Left, identity: the board
136
136
  switcher with the capture status dot (its tooltip says when the pages were captured); then, after a hairline, the view controls: the
137
- screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right, act and
138
- open panels: the viewer note, Comment (the primary action and the one accent control: `soft` while comment mode is off, filled
139
- `default` with `aria-pressed="true"` while it is on, agreeing with the comment-mode banner); then, after a hairline, the Comments,
140
- Agent and Checks toggles on one track (`Toggle variant="segment"`: the open panel's toggle is the raised chip, exactly like the
141
- chosen screen size, none while the panel is closed), then Agent settings. One look for every control but the name and Comment: a
142
- quiet 32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
137
+ screen-size switch, Views (the journeys and what the canvas shows) and, on a local board, Capture with its status. Right, open
138
+ panels: the viewer note, then the Comments, Agent and Checks toggles on one track (`Toggle variant="segment"`: the open panel's
139
+ toggle is the raised chip, exactly like the chosen screen size, none while the panel is closed), then Agent settings. The toolbar
140
+ holds what you look at; what you do to the board is in the board tools (below). One look for every control but the name: a quiet
141
+ 32 px box with the same radius, hairline and tint, either a single button or a track whose chosen option is the raised chip.
143
142
  Comments carries its count as a pill at its right end, and Agent carries the board's agent activity in the same place and size: a
144
143
  dot for one agent, a count for more, accent while working (a slow `breathe`, the same as a working pin, never outside the button),
145
144
  the attention colour when an agent needs a person, green for a moment when the last one finishes.
146
145
 
146
+ ### The board tools
147
+
148
+ The tools you use on the board float at the bottom centre of the canvas, the way FigJam, Miro and tldraw do it
149
+ (`client/src/board/BoardTools.jsx`, their state in `tools.js`): **Select** (V, the default pointer: a click selects a page or
150
+ opens a pin, a drag on empty canvas pans), **Hand** (H: a drag anywhere pans, a click opens nothing; desktop only), a hairline,
151
+ then **Comment** (C), **Draw** (click a page to draw on it; with a comment or a reply open it draws on that comment's page)
152
+ and, on desktop when the board has live pages, **Select text**. One tool is in use at a time (`aria-pressed`): Comment, Draw
153
+ and Select text are the filled accent button, because they change what a click does; Select and Hand in use are quiet, the
154
+ neutral fill of a chosen segment (`bg-surface-2` with an inset hairline). Esc goes back a step at a time and ends on Select. The pill is the zoom controls' pill (`rounded-lg border border-line bg-surface/95 p-0.5 shadow-pop
155
+ backdrop-blur`, 32 px icon buttons), a labelled `role="toolbar"` with one tab stop: the arrow keys, Home and End move between
156
+ the tools, and each has a tooltip with its shortcut. A person who may not comment has no Comment or Draw tool, and with only
157
+ Select left there is no toolbar (a viewer on a phone). On a desktop they keep Select and Hand, and Select text while a page
158
+ is live.
159
+
160
+ The note for the tool in use sits just above the tools, one at a time: the comment hint ("Click a page to comment ...", or
161
+ "Click where the comment goes on Pricing" when Comment was pressed on that page's bar),
162
+ "Commenting on ..." while the composer is open, the drawing bar, or the select-text note. Select has none. The tools, their note,
163
+ an open journey's bar and the toast are one column (the tool dock), so they never overlap. The tools are centred on the canvas,
164
+ not the window, and never sit over the zoom controls (bottom left) or the minimap (bottom right): on a narrow canvas they shift
165
+ off centre, then the zoom controls compact to out, level and in, then the minimap steps aside (`toolDock.js`, unit-tested). On a
166
+ phone the tools are the bottom bar: 44 px targets above the safe-area inset, hidden while a sheet or the keyboard is up.
167
+
168
+ ### The page bar
169
+
170
+ A selected page has a bar of its actions floating beside it in screen pixels (`client/src/board/FrameBar.jsx`): above the card, else
171
+ to its right or left, never over the notes at the top of the canvas or the tool dock at the bottom, and one "..." button when
172
+ there is no room (`frameBarPlace.js`). In order: the page's name and screen size, **Comment**, **Open live** (or **Select text**
173
+ once the page is live), **Checks**, **History**, **Capture**, open in a new tab, close.
174
+
175
+ **Comment** is first because it is the main thing people do with a page, and the tools at the bottom are easy to miss. It is the
176
+ `soft` button at rest (accent text on a light accent tint) and the filled accent while on (`aria-pressed`); its tooltip is
177
+ "Comment on this page" with the C key. It turns the Comment tool on with this page as the target: the hint above the tools names
178
+ the page, the next click on it pins (to the element, on a live page), and a click anywhere else is comment mode's as ever. From
179
+ the keyboard, Enter on the button moves the focus to the page, and Enter there opens the composer near the top left of what
180
+ shows of it; Esc gives the focus back to the button. Only people who have the Comment tool have the button (the same rule: not
181
+ viewers, view-only links, compare mode or static exports). The first time someone who has not started a comment in this browser
182
+ selects a page, the button wears an accent ring for about two and a half seconds (`shapewall.tip.pageComment` in local storage;
183
+ the demo's Reset forgets it). It is a ring, not an animation, so reduced motion needs no other path.
184
+
185
+ The bar is always one line. When the canvas is too narrow for it, words drop in a fixed order and each button keeps its
186
+ accessible name and a tooltip (`fitFrameBar` in `frameBarPlace.js`, unit-tested): Capture, History, Checks, then the page's
187
+ name, then Open live, and Comment last. The widths come from the buttons' fixed sizes, never from the rendered bar. On a phone
188
+ the bar has 44 px targets, no name, and words only on Comment and Open live.
189
+
147
190
  Search is not in the toolbar. It is the field at the top of the expanded sidebar ("Search the board" with its
148
191
  Ctrl/Cmd+K hint) and an icon in the collapsed rail; both open the command palette, as the shortcut does from anywhere. So the bar
149
192
  keeps its shape whatever is open: an open journey shows as the state of the Views button in place (its name, truncated past 240 px,
@@ -151,6 +194,12 @@ and a clear button), and nothing else moves or collapses for it. When it gets na
151
194
  in a fixed order (the panel toggles, Views (an open journey's name shortens first), then the screen-size toggle to icons with
152
195
  tooltips, where the hairlines go too) and the board name truncates a little at each step, never below about 8 characters.
153
196
  Accessible names, shortcuts and tooltips never change.
197
+ While a side panel is open its toggles are the panel's header: their track is exactly as wide as the panel under it, inside the
198
+ bar's 12 px padding on both sides (the panel's own inset), the three sharing the width, and it follows the panel's drag handle with
199
+ no transition (`sidePanelWidth.js` carries the width from the panel to the bar). Everything else in the right zone (the viewer
200
+ note, Agent settings) stays to their left. The left zone drops words sooner to make the room; when no step fits, the toggles keep
201
+ their own width. The panel is never narrower than its toggles need (`SIDE_PANEL` in `toolbarFit.js`: 384 px by default, 368 px at
202
+ least, 560 px or 40% of the window at most).
154
203
  `test/toolbar-fit.test.js` checks the order and that nothing overlaps from a 1024 px window with the widest sidebar up. The phone
155
204
  toolbar is a separate compact bar. `ToggleGroup` options take a `tooltip` for icon-only labels.
156
205
 
@@ -167,7 +216,7 @@ One scale for `z-index`, lowest first. Pick the row that says what the thing is;
167
216
  | --------- | ----------------- | ----------------------------------------------------------------------------------------------- |
168
217
  | Canvas | `z-10`/`z-20` | Pins, card headers and bars, resize handles, presence cursors. |
169
218
  | On canvas | `z-30` | Things that belong to the canvas but float over cards: the comment thread and new-comment box, |
170
- | | | the journey bar, canvas notes, Try this. |
219
+ | | | the board tools and their note, the journey bar, canvas notes, Try this. |
171
220
  | Chrome | `z-40` | Sticky app headers and the collapsed sidebar's flyouts. |
172
221
  | Modal | `z-50` | Dialogs, sheets, the command palette and their dimmed overlay. A modal covers everything below. |
173
222
  | Menu | `z-[60]` | Dropdown menus, selects and small popovers, so they work inside a dialog. |