shapewall 0.8.0 → 0.9.0

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 (76) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +5 -2
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +2 -2
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  7. package/dist/client/assets/{History-C_NAxaRl.js → History-FzpzGmXZ.js} +1 -1
  8. package/dist/client/assets/{LocalSettings-W5Ze9ks7.js → LocalSettings-BGFl4VKr.js} +1 -1
  9. package/dist/client/assets/{Management-CXGSi6gI.js → Management-BGdmGtby.js} +1 -1
  10. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  11. package/dist/client/assets/{app-update-dialog-DNL0kP9U.js → app-update-dialog-BQxVHa5e.js} +1 -1
  12. package/dist/client/assets/index-B_m65HWT.css +2 -0
  13. package/dist/client/assets/{index-DTXjDgcg.js → index-C1ZwriJU.js} +19 -19
  14. package/dist/client/build-info.json +1 -1
  15. package/dist/client/index.html +2 -2
  16. package/dist/client/sw.js +2 -2
  17. package/dist/console/assets/{LocalAccountsApp-Z0gEJ74C.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  18. package/dist/console/assets/{LocalConsole-DzHNISE9.js → LocalConsole-Rg-MTvSJ.js} +1 -1
  19. package/dist/console/assets/{app-update-dialog-CQsUPrMX.js → app-update-dialog-CEhV7th4.js} +1 -1
  20. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  21. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  22. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  23. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  24. package/dist/console/assets/{tailnet-C2QPbIIC.js → tailnet-Cqtbptzq.js} +2 -2
  25. package/dist/console/assets/{usage-BDt6IQh1.js → usage-BCIwgDP9.js} +2 -2
  26. package/dist/console/build-info.json +1 -1
  27. package/dist/console/console.html +5 -5
  28. package/docs/README.md +64 -0
  29. package/docs/agent-hardening.md +3 -3
  30. package/docs/agent-recipes.md +3 -3
  31. package/docs/agent-workflow.md +6 -4
  32. package/docs/agents.md +25 -16
  33. package/docs/architecture.md +6 -1
  34. package/docs/config.md +53 -25
  35. package/docs/deployment.md +2 -2
  36. package/docs/github.md +1 -1
  37. package/docs/hosted.md +265 -70
  38. package/docs/local-accounts.md +1 -1
  39. package/docs/performance.md +3 -2
  40. package/docs/pull-requests.md +1 -1
  41. package/docs/starter-agent.md +4 -4
  42. package/docs/where-to-run.md +1 -1
  43. package/package.json +3 -2
  44. package/src/agent/backends/acp.js +39 -9
  45. package/src/capture/capture.js +35 -5
  46. package/src/capture/destination.js +67 -0
  47. package/src/capture/load-errors.js +82 -0
  48. package/src/checks/cli.js +41 -5
  49. package/src/cli/args.js +1 -0
  50. package/src/cli/capture.js +5 -0
  51. package/src/cli/comments.js +41 -3
  52. package/src/cli/help.js +4 -1
  53. package/src/cli/init.js +8 -4
  54. package/src/cli/misc.js +3 -3
  55. package/src/cli/serve.js +34 -6
  56. package/src/comment-fields.js +5 -0
  57. package/src/comments-cli.js +26 -5
  58. package/src/config-keys.js +191 -0
  59. package/src/config-reload.js +4 -1
  60. package/src/config.js +33 -2
  61. package/src/doctor.js +188 -39
  62. package/src/hosted/auth.js +14 -8
  63. package/src/hosted/db.js +50 -0
  64. package/src/hosted/pages.js +5 -1
  65. package/src/missing-package.js +11 -0
  66. package/src/ports.js +35 -0
  67. package/src/serve-state.js +16 -0
  68. package/src/watch.js +6 -0
  69. package/dist/client/assets/BoardChat-DG08cvD0.js +0 -27
  70. package/dist/client/assets/ChecksPanel-BD7GniTp.js +0 -1
  71. package/dist/client/assets/QuickConnect-Cta4dT3n.js +0 -1
  72. package/dist/client/assets/index-CBrmVq4n.css +0 -2
  73. package/dist/console/assets/app-version-CP0o1L1_.js +0 -1
  74. package/dist/console/assets/console-DIWY1goy.css +0 -2
  75. package/dist/console/assets/console-DYqhjwPS.js +0 -11
  76. package/dist/console/assets/local-agents-D7Jd9P7A.js +0 -6
@@ -1 +1 @@
1
- {"version":"0.8.0","revision":"d89ef355b30aa13ff386887ce4c06f35761ba469"}
1
+ {"version":"0.9.0","revision":"0b45aa284bdc8ef617e543c686d1df03cddd980c"}
@@ -12,14 +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-DYqhjwPS.js"></script>
15
+ <script type="module" crossorigin src="/_console/assets/console-BD5_Gha1.js"></script>
16
16
  <link rel="modulepreload" crossorigin href="/_console/assets/ui-HgfwUo3E.js">
17
17
  <link rel="modulepreload" crossorigin href="/_console/assets/theme-CB-cwoG6.js">
18
- <link rel="modulepreload" crossorigin href="/_console/assets/app-version-CP0o1L1_.js">
19
- <link rel="modulepreload" crossorigin href="/_console/assets/local-agents-D7Jd9P7A.js">
18
+ <link rel="modulepreload" crossorigin href="/_console/assets/app-version-BiMzvHaD.js">
19
+ <link rel="modulepreload" crossorigin href="/_console/assets/local-agents-UprGVyLj.js">
20
20
  <link rel="modulepreload" crossorigin href="/_console/assets/minus-Cnq0kKnu.js">
21
- <link rel="modulepreload" crossorigin href="/_console/assets/tailnet-C2QPbIIC.js">
22
- <link rel="stylesheet" crossorigin href="/_console/assets/console-DIWY1goy.css">
21
+ <link rel="modulepreload" crossorigin href="/_console/assets/tailnet-Cqtbptzq.js">
22
+ <link rel="stylesheet" crossorigin href="/_console/assets/console-PWt8SxrJ.css">
23
23
  </head>
24
24
  <body>
25
25
  <div id="root"></div>
package/docs/README.md ADDED
@@ -0,0 +1,64 @@
1
+ # Shapewall guides
2
+
3
+ Every file in this folder is listed below. Most of them are the text the website shows: [shapewall.com/docs](https://shapewall.com/docs)
4
+ reads them from here, so there is one source and no second copy to keep in step. The groups below are that sidebar's groups. The last
5
+ two are for people changing the code and are not on the website.
6
+
7
+ Five guides exist only on the website, because they are written for the site rather than for the repository:
8
+
9
+ - [Getting started](https://shapewall.com/docs/getting-started): install, write a config, capture, open the board.
10
+ - [CLI reference](https://shapewall.com/docs/cli): every command and flag. The same help text is in this repository's
11
+ [README](../README.md#cli), so a reader who never leaves the repository is not stuck.
12
+ - [FAQ](https://shapewall.com/docs/faq): single-page apps, signed-in pages, where the data lives, teams, licenses.
13
+ - [Security model](https://shapewall.com/docs/security): why captured HTML can never run code.
14
+ - [Before, after and staging](https://shapewall.com/docs/compare): resolved comments before and after, variants, staging against
15
+ production.
16
+
17
+ ## Start here
18
+
19
+ [config.md](config.md) is the only guide of this group that lives here: every key in `shapewall.config.json`, from pages and viewports
20
+ to actions, setup, signed-in pages, boards, CI and the environment variables. Getting started and the CLI reference are on the website,
21
+ above.
22
+
23
+ ## Workflows
24
+
25
+ | Guide | What it covers |
26
+ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
27
+ | [agent-workflow.md](agent-workflow.md) | The three ways to hand comments to a coding agent: JSON, `shapewall watch`, the MCP server. |
28
+ | [agent-recipes.md](agent-recipes.md) | Copy-paste commands for Claude Code, Codex, goose, Ollama and chat bots. |
29
+ | [agents.md](agents.md) | The board's chat panel: connect a model or an agent CLI, work on a branch, images and voice. |
30
+ | [starter-agent.md](starter-agent.md) | `shapewall agent`: one comment at a time in a container, with a trigger gate, budgets and a branch. |
31
+ | [journeys.md](journeys.md) | Link arrows drawn from the real links between pages, and named paths you step through. |
32
+ | [pull-requests.md](pull-requests.md) | Capture every page on each pull request and keep one comment up to date with what changed. |
33
+ | [page-checks.md](page-checks.md) | `shapewall checks`: reliability, SEO and social images against the original site, and the panel. |
34
+ | [performance.md](performance.md) | `shapewall audit`: local Lighthouse runs, measurement profiles, budgets and report history. |
35
+ | [interaction-audits.md](interaction-audits.md) | `shapewall checks flow` and `checks accessibility`: the flow file, supported actions, axe snapshots. |
36
+
37
+ ## Run it
38
+
39
+ | Guide | What it covers |
40
+ | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
41
+ | [where-to-run.md](where-to-run.md) | Local board or hosted server: who can reach each, and where the work happens. |
42
+ | [deployment.md](deployment.md) | Run the board, share it behind an authenticating proxy, export a static copy, capture on CI. |
43
+ | [capture-warnings.md](capture-warnings.md) | Reading the network summary beside a screenshot, and the pacing settings that slow a capture down. |
44
+ | [local-accounts.md](local-accounts.md) | The optional local owner account: passkeys, recovery codes, sessions, profile images. |
45
+ | [updates.md](updates.md) | Which version is running, updating a clone or a project install, the optional update helper. |
46
+ | [hosted.md](hosted.md) | Operating a team server: accounts, workspaces, roles, quotas, retention, backups, restore. |
47
+ | [agent-hardening.md](agent-hardening.md) | Prompt injection through comments, the built-in defenses, least privilege, a sandbox checklist. |
48
+
49
+ ## Integrations
50
+
51
+ | Guide | What it covers |
52
+ | ------------------------------------ | ---------------------------------------------------------------------------------- |
53
+ | [github.md](github.md) | A comment as a GitHub issue, the pull requests that fix it, resolving on merge. |
54
+ | [notifications.md](notifications.md) | Comment events to a signed webhook, Slack, Discord or email, with mentions routed. |
55
+ | [buzz.md](buzz.md) | Optional bridge to coding agents that already sit in a self-hosted Buzz channel. |
56
+
57
+ ## Contributor docs (this repository only)
58
+
59
+ These two are not user guides and are not on the website. They describe how the code is put together, for anyone changing it.
60
+
61
+ | Guide | What it covers |
62
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
63
+ | [architecture.md](architecture.md) | The three parts and the files they share: capture, live HTML and its limits, anchors, the board. |
64
+ | [design-system.md](design-system.md) | The board's UI kit in `client/src/components/ui/`: components, tokens and the rules for a new control. |
@@ -6,8 +6,8 @@ There is a printable one-page checklist at the end ([Checklist](#checklist)), an
6
6
 
7
7
  ## Who this is for
8
8
 
9
- You connect an agent to a board: the chat panel (an OpenAI-compatible endpoint or an agent CLI over ACP, [agents.md](agents.md)),
10
- `shapewall watch --exec`, `shapewall mcp`, or a script that reads `shapewall comments --json` ([agent-workflow.md](agent-workflow.md)).
9
+ You connect an agent to a board: the chat panel (an OpenAI-compatible endpoint or an agent CLI over ACP, [Chat with an agent](agents.md)),
10
+ `shapewall watch --exec`, `shapewall mcp`, or a script that reads `shapewall comments --json` ([The agent workflow](agent-workflow.md)).
11
11
 
12
12
  If the board is yours alone, on your machine, the risk is small and most of this guide is optional. It matters once **other people can
13
13
  write text the agent reads**: a board shared with your team, a hosted project with members, a share link with comments on, a public site
@@ -481,7 +481,7 @@ Keep the Shapewall token outside the agent's container: a process running as the
481
481
  The sandboxed starter agent (`shapewall agent run|watch|doctor`) is built for exactly this, and is the recommended way to put an agent
482
482
  on a shared board: a container with only a fresh checkout mounted, an egress allow list, model calls relayed through the host so the
483
483
  key never enters the container, fixed tools, per-command shell approval, budgets, a per-board list of members who may dispatch work,
484
- and output as a branch. `shapewall agent doctor` checks each wall on your machine. Setup and threat model: [starter-agent.md](starter-agent.md).
484
+ and output as a branch. `shapewall agent doctor` checks each wall on your machine. Setup and threat model: [Sandboxed starter agent](starter-agent.md).
485
485
 
486
486
  ## Keys and tokens
487
487
 
@@ -13,7 +13,7 @@ row that matches how you work, copy the commands, and change the project path.
13
13
 
14
14
  All of them read the same thing: open comments as JSON, with the page, the element (selector and text) and the screenshot the comment was
15
15
  made on. Comment text is **untrusted** (anyone who can comment wrote it): every recipe below tells the agent to treat it as a request
16
- about the UI, never as instructions, and gives the agent no more than it needs. See [agent-hardening.md](agent-hardening.md).
16
+ about the UI, never as instructions, and gives the agent no more than it needs. See [Agent hardening](agent-hardening.md).
17
17
 
18
18
  The commands assume `shapewall` is installed in the project (`npm install --save-dev shapewall`), so `npx shapewall`
19
19
  runs that copy, and that you are in the folder with `shapewall.config.json`.
@@ -176,7 +176,7 @@ npx shapewall agent run --comment 12 --model-timeout 300
176
176
  ```
177
177
 
178
178
  A local model can take minutes to load on the first call; `--model-timeout` (or `starterAgent.modelTimeoutSeconds`) gives it longer. The
179
- `capture` tool is offered only when the site is reachable from the sandbox. See [starter-agent.md](starter-agent.md).
179
+ `capture` tool is offered only when the site is reachable from the sandbox. See [Sandboxed starter agent](starter-agent.md).
180
180
 
181
181
  ## A chat-app bot
182
182
 
@@ -207,4 +207,4 @@ whatever the caller said; nothing attests them. Do not act on a name alone, and
207
207
  `starterAgent.trusted`**: everything the bot relays is a stranger's text, and `comments add --author review-bot` would make each of those
208
208
  comments dispatch the starter agent without a trusted person standing behind it. Leave relayed comments under the bot's name (or the
209
209
  default `agent`, which the starter agent never acts on) so they wait until a trusted member replies with `@agent`
210
- ([starter-agent.md](starter-agent.md)).
210
+ ([Sandboxed starter agent](starter-agent.md)).
@@ -1,6 +1,6 @@
1
1
  # Working with a coding agent
2
2
 
3
- Shapewall does not include a model (the board chat only talks to one you connect, see [agents.md](agents.md)). It produces feedback in a shape that any coding agent (or a person) can act on, keeps
3
+ Shapewall does not include a model (the board chat only talks to one you connect, see [Chat with an agent](agents.md)). It produces feedback in a shape that any coding agent (or a person) can act on, keeps
4
4
  track of which comments an agent has taken, and makes checking the result cheap. There are three ways to connect an agent, from simplest
5
5
  to most automatic:
6
6
 
@@ -133,7 +133,7 @@ is resolved: the board, `comments resolve`, the API or the MCP `resolve_comment`
133
133
 
134
134
  ### API
135
135
 
136
- The board server has the same operations (JSON bodies, see [deployment.md](deployment.md) for the write protections):
136
+ The board server has the same operations (JSON bodies, see [Deployment and self-hosting](deployment.md) for the write protections):
137
137
 
138
138
  | Route | Body | Returns |
139
139
  | ------------------------------------------------- | ---------------------------------------------------------- | ----------------------------- |
@@ -196,7 +196,9 @@ were `queued` or `working` when a previous watcher stopped are listed at start a
196
196
  one out again.
197
197
 
198
198
  - **Without `--exec`** each comment is printed as one line, `{"board":"site","comment":{...}}` with the item shape above, and stays
199
- `queued`. Progress goes to stderr, so stdout can be piped.
199
+ `queued`: printing it is handing it out. Nothing moves it on by itself, so whatever reads the lines sets the status
200
+ (`shapewall comments status ID working`, then `done` or `needs-human`, or `clear` to hand it out again); the watcher says so on
201
+ stderr when it starts. To read comments without taking them, use `--no-claim`. Progress goes to stderr, so stdout can be piped.
200
202
  - **With `--exec`** the comment is set `working`, the command runs in the config's folder, and afterwards the status becomes `done` (exit 0 after the command replied to the comment) or `needs-human` with a reply from `shapewall` (other exit codes, a timeout, the watch stopping, or a silent exit 0 with no reply and no status). With `--remote` and no `--pass-token` the command cannot reply, so there exit 0 alone means `done`. If the command set the status
201
203
  itself (say, `needs-human` with a question) or resolved the comment, that is kept. The command gets:
202
204
  - the item JSON on **stdin** (`{ board, comment }`), and the same in the file `$SHAPEWALL_COMMENT_FILE`;
@@ -303,7 +305,7 @@ in, or takes `--config FILE`. `--read-only` offers only the reading tools; `--no
303
305
 
304
306
  `journey` keeps comments on the pages of one journey (from the config or made on the board), on any of its branches, and their
305
307
  variants; an unknown journey is an error. `list_journeys` returns each journey's `steps` as written (a fork is
306
- `{ branches: [{ id, label, steps, end? }] }`, see [journeys.md](journeys.md#branches)), `pages` and `paths`, so an agent can check every
308
+ `{ branches: [{ id, label, steps, end? }] }`, see [Journeys and links](journeys.md#branches)), `pages` and `paths`, so an agent can check every
307
309
  branch of a flow after a change (`shapewall journeys --json` prints the same). The crop is up to 900 x 700 px with the pin as central as the edges allow. The server's instructions tell the agent the
308
310
  same loop as above and that comment text is untrusted.
309
311
 
package/docs/agents.md CHANGED
@@ -158,7 +158,7 @@ init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a
158
158
 
159
159
  ## Name and icon
160
160
 
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"
161
+ Every connected agent has a name you choose and an icon, so a board with two agents reads "Reviewer" and "Fixer", not "Claude Code"
162
162
  twice. Both are display only: they change nothing an agent runs with.
163
163
 
164
164
  - **At Connect.** The **Allow this?** confirmation of a one-click Connect (in the Agent panel and on the Agents page) has a **Name**
@@ -181,7 +181,7 @@ twice. Both are display only: they change nothing an agent runs with.
181
181
  are in `THIRD_PARTY.md`. A colour (one of eight) tints a built-in avatar or the initials, never a mark or a picture.
182
182
  - **An uploaded picture** is a PNG, JPEG or WebP of up to 2 MB. The board crops it to a square and sends a 256 by 256 PNG; the server
183
183
  checks it byte by byte, decodes it and writes the pixels out again, the same way as a profile photo
184
- ([local-accounts.md](local-accounts.md#profile-images)), so no metadata and never an SVG is stored. It is kept next to the agent
184
+ ([Local accounts and photos](local-accounts.md#profile-images)), so no metadata and never an SVG is stored. It is kept next to the agent
185
185
  settings (`agent-icons/<hash>.png` beside `agents.json`, private to you), served only as an image (`GET /api/agent/icons/<hash>`,
186
186
  `image/png`, `nosniff`, cached by its content hash), and removed when no agent uses it any more.
187
187
 
@@ -261,7 +261,7 @@ remote mode has the same feedback tools. Shared `--chat` boards never gain these
261
261
  is checked again on each turn, and trusted and untrusted ACP sessions are separate. Approving a permission, stopping an owner turn, or clearing its thread requires the same owner capability, including while its ACP session is idle. `--no-capture` hides Fix and removes recapture tools.
262
262
 
263
263
  For an external coding session, open **Chat settings** in the chat panel: **Use with Claude Code / Codex** shows copyable MCP setup
264
- commands (before an agent is connected, the same commands are folded under the connect options). See [agent-workflow.md](agent-workflow.md#mcp-server-shapewall-mcp).
264
+ commands (before an agent is connected, the same commands are folded under the connect options). See [The agent workflow](agent-workflow.md#mcp-server-shapewall-mcp).
265
265
 
266
266
  ## Undo an agent's change
267
267
 
@@ -707,7 +707,15 @@ Older Gemini CLI versions call the flag `--experimental-acp` (still accepted, de
707
707
  the panel shows a card with the agent's options (**Allow**, **Reject**, and any "always" choices it offers). An edit or a write
708
708
  shows its diff on the card, computed by Shapewall from the file as it is and the new text (the first 80 lines or 8 KB, with **Show
709
709
  the whole diff** for up to 1500 lines or 64 KB). No answer within 2 minutes counts as a deny, and so does Stop. Whether the agent asks at all is the agent's own setting (Claude Code's permission mode,
710
- Codex's approval policy, goose's mode): Shapewall does not change it.
710
+ Codex's approval policy, goose's mode): Shapewall does not change it. One-click **Connect** saves the bare command
711
+ (`claude-agent-acp`), so the agent starts in whatever mode its own settings give it, and some adapters start in one that acts without
712
+ asking (`claude-agent-acp` 0.106.0 starts a new session in `auto` when no `permissions.defaultMode` is set).
713
+ - **The mode in effect.** The panel's line about a local agent says it runs under its own permission settings. Once its session has
714
+ started and it reports a mode, the line names it: **Auto, which acts without asking** (any mode whose name says so: auto, accept
715
+ edits, bypass, full access, yolo and the like), **Default: it asks here before an edit or a command its own settings do not already
716
+ allow** (Claude Code's `default`, goose's `approve`), **Plan: it reads and answers** (Claude Code's `plan`, Codex's `read-only`,
717
+ goose's `chat`), or just the mode's name for any other. To be asked first, pick an asking mode in the composer's options, or set
718
+ one in the agent's own settings ([Restrict the agent's own tools](#restrict-the-agents-own-tools)).
711
719
 
712
720
  ### What the agent may do through Shapewall
713
721
 
@@ -746,12 +754,13 @@ quote each comment in the same `<shapewall-data trust="untrusted">` element.
746
754
  The agent works with its own tools under its own settings, and Shapewall cannot sandbox them. Run it the way you would run it on a repo
747
755
  full of other people's text:
748
756
 
749
- - **Claude Code** (`claude-agent-acp`) follows your Claude Code settings. Keep `permissions.defaultMode` at `default` (asks before
750
- edits and commands) or `plan` (read-only), never `bypassPermissions`. A separate config folder for Shapewall works too:
757
+ - **Claude Code** (`claude-agent-acp`) follows your Claude Code settings. Set `permissions.defaultMode` to `default` (asks before
758
+ edits and commands your allow rules do not cover) or `plan` (read-only), never `auto`, `acceptEdits` or `bypassPermissions`. Set
759
+ it explicitly: with none set, `claude-agent-acp` 0.106.0 starts in `auto`, which acts without asking. A separate config folder for Shapewall works too:
751
760
  `CLAUDE_CONFIG_DIR` is passed to the agent.
752
761
  - **Codex** (`codex-acp`) follows `~/.codex/config.toml` (or `CODEX_HOME`). Use `sandbox_mode = "workspace-write"` (or
753
762
  `"read-only"`) with `approval_policy = "on-request"`, never `danger-full-access`.
754
- - **goose** loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
763
+ - **goose** asks only in `GOOSE_MODE=approve` (or `smart_approve`); its default, `auto`, acts without asking. It also loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
755
764
  extension, and start it with that extension named:
756
765
 
757
766
  ```sh
@@ -791,8 +800,8 @@ What the bridge protects against, and what it does not:
791
800
  - **Who can chat:** anyone who can reach a board with chat can drive the agent, with your login, on your machine. `shapewall serve`
792
801
  keeps chat off for boards shared beyond this machine unless you pass `--chat`, and with an ACP agent it refuses to start a shared
793
802
  board with `--chat` unless you also pass `--allow-remote-agent`: that combination is remote command execution as you, for anyone
794
- who reaches the board. For shared boards, use the sandboxed starter agent ([starter-agent.md](starter-agent.md)), and see
795
- [agent-hardening.md](agent-hardening.md).
803
+ who reaches the board. For shared boards, use the [sandboxed starter agent](starter-agent.md), and see
804
+ [Agent hardening](agent-hardening.md).
796
805
  - **Not covered:** the agent's own tools and its own sandbox (or lack of one), what its model provider sees, and anything you allow.
797
806
  A command you approve runs as you in the project, so the project's own config still applies to it (a repo's `.git/config` can make
798
807
  `git status` run a program): approve commands only in repos you trust.
@@ -903,8 +912,8 @@ What the bridge protects against, and what it does not:
903
912
  own name (**Effort**, **Thinking**), and anything else it offers (a mode such as Ask or Plan) under **More options**. When the panel
904
913
  is too narrow for them, one control holds every option in sections. They come from an ACP agent's own session (`session/new`
905
914
  config options and its older modes), or the model list an OpenAI-compatible endpoint reports at `/models`. Never a permission or
906
- sandbox setting, and never a mode that acts without asking (bypass, auto, yolo and the like), so the agent still asks before it
907
- changes files or runs commands. Values show the agent's real names: a value that is just the agent's default says **Default
915
+ sandbox setting, and never a switch to a mode that acts without asking (bypass, auto, yolo and the like). A session that is
916
+ already in such a mode (its own settings started it there) keeps it until you pick another, and the panel's line says so. Values show the agent's real names: a value that is just the agent's default says **Default
908
917
  model**, or the model it says it currently is. The keyboard works as in any menu: the current choice has the focus when it opens,
909
918
  the arrows and Home and End move, Escape closes it back to its button.
910
919
  - **Options before the first message.** As soon as the panel is open and on screen for the owner, a new chat (New chat included)
@@ -1009,14 +1018,14 @@ Markdown to share it.
1009
1018
 
1010
1019
  ## Board tools
1011
1020
 
1012
- Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([agent-workflow.md](agent-workflow.md)).
1021
+ Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([The agent workflow](agent-workflow.md)).
1013
1022
 
1014
1023
  Agents with only a shell, and chat bots that relay a board to people, use the CLI: `shapewall comments get|add|reply|resolve|status`
1015
1024
  (all with `--json`; `comments` and `comments get` also take `--for-agent`, each comment quoted as untrusted `<shapewall-data>` for a
1016
1025
  model to read), `shapewall comments --since ID|TIME` for what is new, and `shapewall events --follow --json` for a live stream of
1017
1026
  every comment event from every process that never claims anything (`shapewall watch --no-claim` likewise). While `shapewall serve` runs,
1018
- it sends the notifications for all of those changes ([agent-workflow.md](agent-workflow.md#a-chat-bot-telegram-slack-discord),
1019
- [notifications.md](notifications.md#events)).
1027
+ it sends the notifications for all of those changes ([The agent workflow](agent-workflow.md#a-chat-bot-telegram-slack-discord),
1028
+ [Notifications](notifications.md#events)).
1020
1029
 
1021
1030
  An ACP agent reads the project with its own tools; board data comes with each message. On trusted owner turns, its ACP session also receives a Shapewall stdio MCP server scoped to this board. It provides board reads plus replies, agent status, resolution and optional recapture, with no GitHub actions. Ask it to call `recapture_pages` with any other configured pages it changed; Shapewall automatically recaptures the comment page after the turn.
1022
1031
 
@@ -1034,7 +1043,7 @@ Anyone who can comment can write text that a model will read. Shapewall keeps th
1034
1043
  That lowers the risk; it does not remove it. Models can still be talked into a wrong answer, so treat answers about untrusted comments
1035
1044
  with care, and do not point a chat at a board you share with strangers using a key that has other powers.
1036
1045
 
1037
- Connecting an agent to a board other people can write on? Read [agent-hardening.md](agent-hardening.md) first (also as a printable
1046
+ Connecting an agent to a board other people can write on? Read [Agent hardening](agent-hardening.md) first (also as a printable
1038
1047
  [PDF](https://shapewall.com/downloads/shapewall-agent-hardening.pdf)): how injected text reaches an agent, least privilege, a sandbox checklist and what to do if something goes wrong.
1039
1048
 
1040
1049
  ## Sharing a board
@@ -1131,5 +1140,5 @@ chosen, expiresAt }`, state `pending`, then `approved`, `denied`, `expired` or `
1131
1140
  ## Shared boards
1132
1141
 
1133
1142
  The chat runs the agent as you. For boards where not everyone who comments should drive an agent on your machine, use the
1134
- [starter-agent.md](starter-agent.md): work on a comment runs in a container with only a fresh worktree, an egress allow list, fixed tools, a trigger gate, budgets, and a branch as
1143
+ [Sandboxed starter agent](starter-agent.md): work on a comment runs in a container with only a fresh worktree, an egress allow list, fixed tools, a trigger gate, budgets, and a branch as
1135
1144
  the output.
@@ -207,7 +207,12 @@ count, and clicking it zooms in until they part (`clusterPins` in `client/src/bo
207
207
  a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
208
208
 
209
209
  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
210
- it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
210
+ it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The composer, the reply box and
211
+ the edit box have a microphone where the browser has speech recognition (`client/src/board/DictationButton.jsx`): the browser's
212
+ `SpeechRecognition` writes at the caret, the rules for joining words to the text around them and the session states are pure
213
+ (`client/src/board/dictation.js`, tested in `test/comment-dictation.test.js`), and `hooks/useCommentDictation.js` drives one
214
+ recognizer at a time and releases it on posting, Esc, unmount and a hidden tab. Shapewall never receives the audio; the browser's
215
+ speech service does the transcription. The open thread is a popover at
211
216
  its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
212
217
  history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
213
218
  that reads the pin's position every frame, bounded by the canvas, so they follow pan and zoom, flip to stay on screen and hide when
package/docs/config.md CHANGED
@@ -10,11 +10,21 @@ each board (including a board's own `viewports`, `block`, `setup` and `auth`), `
10
10
  in the serve log and the board keeps the last good config. `outputDir`, `boardUrl`, `auth`, `browser`, `liveHtml`, `agent`,
11
11
  `starterAgent`, `notifications` and `github` still need a restart (the log says so).
12
12
 
13
+ `checks` and `ci` are in neither list, so an edit to either is silently not picked up and the log says nothing about it. Restart
14
+ `serve` for a `checks` change to reach the board's **Run checks**; `ci` is read by `shapewall ci` in its own run, so a running board
15
+ never uses it anyway.
16
+
17
+ A key Shapewall does not use (a typo like `"viewport"` for `"viewports"`, or a page key such as `waitFor` set at the top level) is
18
+ ignored, and `shapewall doctor`, `capture` and `serve` warn about it with the key it most likely meant; the config still loads.
19
+ Unknown keys are refused outright only inside `capturePacing`, `checks`, `setup`, `ci`, an action's options and a page's `seo`,
20
+ plus the secret and command key lists in `agent` and `github`. A required key under the wrong case (`"baseURL"`) is an error that
21
+ says to rename it. `$schema` is allowed anywhere.
22
+
13
23
  ## Top level
14
24
 
15
25
  | Key | Type | Default | Notes |
16
26
  | --------------- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
- | `title` | string | `"Shapewall"` | Board title (single-board configs). |
27
+ | `title` | string | `"Shapewall"` | The config's title, on the board and in exports and hosted pushes. In a single-board config the board takes it too; a board with none is titled by its id. |
18
28
  | `id` | string | `"site"` | Board id for single-board configs. Lowercase letters, digits, dashes. |
19
29
  | `baseUrl` | http(s) URL | required | Where pages are loaded from. May include a base path: `http://localhost:3000/app`. |
20
30
  | `publicUrl` | http(s) URL | none | Used for "Open page" links and to rewrite links in live HTML. |
@@ -29,18 +39,19 @@ in the serve log and the board keeps the last good config. `outputDir`, `boardUr
29
39
  | `liveHtml` | boolean | `true` | `false` captures screenshots only. |
30
40
  | `versions` | 0-50 | `5` | Previous captures kept per page and viewport, for before/after. `0` keeps none. |
31
41
  | `boardUrl` | http(s) URL | the running `serve` address | Where people open the board, for links in notifications and GitHub issues. Without it, links use a running `shapewall serve` for this config, else port 4600. |
32
- | `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. See below. |
33
- | `journeys` | Journey[] | none | Named page sequences, which may fork. See [journeys.md](journeys.md). |
42
+ | `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. 1 to 8 of them. See below. |
43
+ | `journeys` | Journey[] | none | Named page sequences, which may fork. See [Journeys and links](journeys.md). |
34
44
  | `auth` | object | none | See below. |
35
45
  | `browser` | object | Playwright's Chromium | `{ "channel": "chrome" }` or `{ "executablePath": "/path/to/chrome" }` (absolute, outside the project). |
36
46
  | `groups` | string[] | order of first use | Group order on the board. |
37
47
  | `pages` | Page[] | required (or `boards`) | See below. |
38
48
  | `boards` | Board[] | none | Several boards in one file, instead of top-level `pages`. |
39
- | `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [notifications.md](notifications.md). |
49
+ | `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [Notifications](notifications.md). |
40
50
  | `github` | object | none | GitHub connect: `repo`, `boardUrl`, `labels`. See [GitHub](#github) below. |
41
51
  | `agent` | object | none | The board chat's model endpoint. See [Agent](#agent) below. |
42
- | `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [starter-agent.md](starter-agent.md). |
52
+ | `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [Sandboxed starter agent](starter-agent.md). |
43
53
  | `sitemap` | URL, file or object | none | Default source for `shapewall sitemap`. See [Sitemap import](#sitemap-import). |
54
+ | `checks` | object | none | Defaults for page checks. Only `seo` and `budgets` are accepted. See [Checks SEO](#checks-seo) and [Checks budgets](#checks-budgets) below. |
44
55
  | `ci` | object | none | Capture on pull requests: threshold, pages, ignore selectors, build and serve commands. See [CI](#ci) below. |
45
56
 
46
57
  Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
@@ -58,11 +69,11 @@ Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
58
69
  | `group` | string | Card group on the board. Defaults to `Pages`. |
59
70
  | `note` | string | Up to 200 characters, shown on the card and with its comments: "Sample data", "Signed-out state". |
60
71
  | `waitFor` | selector | Must be visible before the shot. |
61
- | `actions` | Action[] | Run in order after loading, before the shot. |
72
+ | `actions` | Action[] | Run in order after loading, before the shot. At most 30. |
62
73
  | `viewports` | string[] | A subset of the configured viewports for this page. |
63
74
  | `expectStatus` | number or number[] | An error page captured on purpose, e.g. `404` or `[404, 410]`. It is captured like any page; another status is the failure. |
64
75
  | `errorSelectors` | string[] | Optional known error-state CSS selectors for checks. At most 10 selectors of 500 characters each. Visible matches produce a reliability finding; no page-text guessing. |
65
- | `seo` | object | Optional `{ "indexable": false }` skips public SEO diagnostics even with `--seo`. Omit or use `true` for selected public pages. SEO remains off without `--seo`. |
76
+ | `seo` | object | An object whose only key is a boolean `indexable`. `{ "indexable": false }` skips public SEO diagnostics even with `--seo`; omit it for public pages. SEO is off without `--seo`. |
66
77
  | `timeout` | ms | This page's budget for loading, `waitFor` and its actions, 1000-300000. Replaces `timeouts.page` for it, and lets its `wait` and `hold` actions run that long. |
67
78
  | `localStorage` | object | Seeds for this page, on top of the board's. See [localStorage seeds](#localstorage-seeds). |
68
79
  | `frameHeight` | number or object | This page's own frame height, 240-8000: one number for all its viewports, or `{ "desktop": 900, "phone": 844 }`. The browser window stays the viewport's. See [Viewports](#viewports). |
@@ -203,8 +214,9 @@ A board for a guest-first app and a canvas game might read:
203
214
 
204
215
  ## Viewports
205
216
 
206
- `viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; any other lowercase name works
207
- too (`phone-landscape`, `kiosk`). Up to 8.
217
+ `viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; a name of your own works too
218
+ (`phone-landscape`, `kiosk`), as long as it is lowercase letters, digits and dashes, starts with a letter and is at most 32
219
+ characters: `Kiosk` and `4k` are rejected. Up to 8.
208
220
 
209
221
  | Key | Notes |
210
222
  | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -242,6 +254,7 @@ heights.
242
254
  - `"analytics"` is a built-in list: Google Analytics and Tag Manager, Plausible, Umami Cloud, Cloudflare Web Analytics and RUM, Segment,
243
255
  Hotjar, Clarity, Mixpanel, Amplitude, PostHog, Heap, FullStory, Fathom, Simple Analytics, GoatCounter, and the Meta, Bing, LinkedIn,
244
256
  X, TikTok and HubSpot pixels. A self-hosted analytics endpoint needs its own pattern (`"*/umami/*"`).
257
+ - A list holds at most 50 entries, each at most 300 characters and without whitespace.
245
258
 
246
259
  The top-level list applies to every board; a board's `block` adds to it. Blocked requests are not network failures in the capture
247
260
  warnings or in page checks. Page checks apply the same list.
@@ -254,9 +267,10 @@ warnings or in page checks. Page checks apply the same list.
254
267
  { "localStorage": { "game.trailerSeen": "1", "settings": { "music": false } } }
255
268
  ```
256
269
 
257
- Strings are stored as they are; numbers, booleans, objects and arrays as JSON. A page's keys win over its board's, a board's over the
258
- top level's. They are set on every load of that origin in the shot. Use them for flags an app checks at start (a tutorial seen, a saved
259
- setting) instead of clicking through to set them.
270
+ Strings are stored as they are; numbers, booleans, objects and arrays as JSON. Each object takes at most 50 keys, a key at most 200
271
+ characters and a stored value at most 20000. A page's keys win over its board's, a board's over the top level's. They are set on
272
+ every load of that origin in the shot. Use them for flags an app checks at start (a tutorial seen, a saved setting) instead of
273
+ clicking through to set them.
260
274
 
261
275
  ## Setup (shared state)
262
276
 
@@ -275,7 +289,7 @@ and the pages in its scope start from the browser state it left: cookies, localS
275
289
  }
276
290
  ```
277
291
 
278
- - `actions` (required): any page actions, including `viewports` guards and `optional`.
292
+ - `actions` (required): any page actions, including `viewports` guards and `optional`. At most 30, as on a page.
279
293
  - `path`: where it starts, default `/`.
280
294
  - `groups` and `pages`: its scope. Without either, every page of the board uses it; with them, only pages in those groups or with
281
295
  those ids (marketing pages keep a clean first visit).
@@ -311,8 +325,8 @@ page only.
311
325
  - With more than `--limit` pages (default 100, at most 1000), the shallowest are kept, so the top of the site wins over deep archives.
312
326
  - `--board ID` adds them to one board of a multi-board config. Nothing is captured; run `shapewall capture` next.
313
327
 
314
- To set the source once, add `sitemap` to the config (or to a board in `boards[]`). `shapewall sitemap` with no argument reads it, and
315
- `init --sitemap` records it:
328
+ To set the source once, add `sitemap` to the config, or, in a multi-board config, to each board inside `boards[]` (a top-level
329
+ `sitemap` beside `boards` is an error). `shapewall sitemap` with no argument reads it, and `init --sitemap` records it:
316
330
 
317
331
  ```json
318
332
  { "sitemap": { "source": "https://www.example.com/sitemap.xml", "limit": 50, "exclude": ["/tag/"], "group": "Site" } }
@@ -393,13 +407,13 @@ Versions are kept for the default environment only.
393
407
  `repo` (`owner/name`), `boardUrl` (where the board is served, for links from issues; default `http://127.0.0.1:4600/`), `labels` (up to
394
408
  10, put on new issues), `board` (the board that bare `shapewall:<id>` markers mean) and `apiUrl` (GitHub Enterprise Server). Top level
395
409
  only. The token comes from `SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN` and the webhook secret from `SHAPEWALL_GITHUB_WEBHOOK_SECRET`; a
396
- `token` or `webhookSecret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
397
- `SHAPEWALL_GITHUB_API_URL`. See [github.md](github.md).
410
+ `token`, `webhookSecret` or `secret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
411
+ `SHAPEWALL_GITHUB_API_URL`. See [GitHub connect](github.md).
398
412
 
399
413
  ## CI
400
414
 
401
415
  Capture on every pull request: what `shapewall ci` and the workflow from `shapewall init --ci` read. See
402
- [pull-requests.md](pull-requests.md).
416
+ [Capture on pull requests](pull-requests.md).
403
417
 
404
418
  ```json
405
419
  {
@@ -419,10 +433,10 @@ Capture on every pull request: what `shapewall ci` and the workflow from `shapew
419
433
  | `threshold` | 0-1 | `0.00001` | Share of pixels below which a shot counts as unchanged (0.00001 is 0.001%). A size change always counts. `--threshold` overrides it. |
420
434
  | `pages` | string[] | every page | Page ids to compare (an allow-list), in the config's order. |
421
435
  | `viewports` | string[] | each page's own | Viewport names to compare. |
422
- | `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50. |
436
+ | `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50, each at most 300 characters. |
423
437
  | `images` | string | `"links"` | `"links"`: the comment links to the workflow artifact. `"branch"`: thumbnails committed to a `shapewall-ci` branch and shown inline (public repositories only; needs `contents: write`). |
424
438
  | `maxPages` | 1-500 | `50` | Compare at most this many pages. `--max-pages` overrides it. |
425
- | `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (default 180000). |
439
+ | `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (1000 to 1800000, default 180000). With `start`, `serve` is required. |
426
440
 
427
441
  `start` commands are argv arrays (`["npm", "run", "build"]`): a program name found on `PATH`, then its arguments, run without a shell.
428
442
  A string is an error, and so are paths (`./build.sh`, so a config cannot name a program the repository ships), shells and launchers
@@ -438,10 +452,15 @@ from `shapewall ci capture --allow-start` inside a CI job (`GITHUB_ACTIONS` or `
438
452
  ```
439
453
 
440
454
  The board chat's endpoint: any OpenAI-compatible chat completions API. `baseUrl` and `model` are required to connect; `apiKeyEnv` (the
441
- variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [agents.md](agents.md#name-and-icon)), `vision` (default `true`), `tools` (default `true`), `maxTokens`,
442
- `temperature` and `backend` (`"openai-compatible"`) are optional. Top level only. An `apiKey`, `key` or `token` key here is an error, and `apiKeyEnv` may only name `SHAPEWALL_AGENT_*` or a `*_API_KEY`
455
+ variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [Chat with an agent](agents.md#name-and-icon)), `vision` (default `true`), `tools` (default `true`), `maxTokens`,
456
+ `temperature` (0 to 2) and `backend` are optional. `maxTokens` is a whole number from 1 to 200000. `backend` is
457
+ `"openai-compatible"` (the default) or `"acp"`, which chats with an agent CLI over ACP instead; that command comes from
458
+ `serve --agent-acp`, `SHAPEWALL_AGENT_ACP` or the host's saved agent settings, never from the config. Top level only. An `apiKey`,
459
+ `key`, `token`, `secret` or `password` key here is an error, and so is any key that could name a command to run (`command`, `cmd`,
460
+ `exec`, `acp`, `acpCommand`, `program`, `args`, `argv`, `env`), because a committed config would run it on the machine of whoever
461
+ chats from that repo. `apiKeyEnv` may only name `SHAPEWALL_AGENT_*` or a `*_API_KEY`
443
462
  variable. A key goes only to this machine, a known hosted API, or a host confirmed in `SHAPEWALL_AGENT_KEY_HOSTS`.
444
- Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [agents.md](agents.md).
463
+ Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [Chat with an agent](agents.md).
445
464
 
446
465
  How fixes run, both off by default and also on the Agents page of the Workspace Console (saved settings win over these):
447
466
  `branchMode` (`true` runs an agent CLI's fixes on a branch of their own) with `branchPrefix` (default `"shapewall/"`), see
@@ -450,6 +469,11 @@ How fixes run, both off by default and also on the Agents page of the Workspace
450
469
 
451
470
  ## Auth
452
471
 
472
+ A page that needs a sign-in usually redirects to the sign-in page, and without a login a capture is a picture of that page. Each
473
+ shot keeps the URL it landed on (`finalUrl` in `capture --json`, with `redirected: true` when it is not the page asked for), the
474
+ capture line says "landed on /login/, not /app/", the capture ends with a warning that points here, and the board marks the card
475
+ "Redirected". `shapewall checks` prints the same as a warning.
476
+
453
477
  Never put credentials in the config. Two options:
454
478
 
455
479
  **Guided manual sign-in.** Run this on the desktop that will capture the site:
@@ -482,8 +506,12 @@ record and capture locally, then use the normal capture-push workflow instead of
482
506
 
483
507
  **Login script.** An ES module whose default export signs in. It runs once per capture; its cookies and storage are reused for every page.
484
508
 
485
- Capture also refuses a `baseUrl` whose public-looking hostname resolves to a private or loopback address, so a config from someone
486
- else cannot point captures at your internal network through DNS. Use `localhost` or the address itself for your own dev server.
509
+ When the page being captured is loaded from a public host, the capture browser refuses that page's own requests to loopback, private
510
+ and internal hosts, including a public name that resolves to one, so a public page cannot make the browser fetch from this machine or
511
+ its network (a router page, a local dev server, cloud metadata). The `baseUrl` itself is never refused, and a `baseUrl` that is
512
+ already local or private -- the usual dev site -- keeps all of its requests, including those to other hosts on your network. So the
513
+ guard bounds what a public page may reach through the capture browser; it is not a check on where a config may point. Read a config
514
+ you did not write before you capture with it.
487
515
 
488
516
  A login script is code: `shapewall capture`, the board's Capture button and page checks run it on your machine, as you, with your
489
517
  environment. Capture prints a line the first time it runs one. Only use a config with `auth.loginScript` from a repo you trust, and read
@@ -78,13 +78,13 @@ Any proxy works (nginx with `auth_basic`, an SSO proxy such as oauth2-proxy, a T
78
78
  - Anyone who can reach the board can read every capture and comment and, unless you pass `--read-only` or `--no-capture`, add comments
79
79
  and start captures.
80
80
  - The board chat spends your model key, so it is off on a shared board unless you pass `--chat` (with a rate limit, a cap on answers at
81
- once and a storage quota per board). See [agents.md](agents.md#sharing-a-board).
81
+ once and a storage quota per board). See [Chat with an agent](agents.md#sharing-a-board).
82
82
  - The comment author is a free-text name, not an identity. If you need accountability, put identity in the proxy and its logs.
83
83
  - Binding to a non-loopback address (`--host 0.0.0.0`) without a proxy exposes the board unauthenticated; Shapewall prints a warning. With
84
84
  a non-loopback `--host` and no allowed host names, the Host check is off.
85
85
  - With GitHub connect, anyone who can use the board can open issues with the server's token. A GitHub webhook
86
86
  (`POST /api/github/webhook`, only when `SHAPEWALL_GITHUB_WEBHOOK_SECRET` is set) must reach the board without the proxy's login; it is
87
- protected by its signature instead. See [github.md](github.md#webhook).
87
+ protected by its signature instead. See [GitHub connect](github.md#webhook).
88
88
  - `SHAPEWALL_ALLOWED_HOSTS` (comma-separated) adds names the same way as `--allowed-host`, and keeps the Host check on for a non-loopback
89
89
  `--host`. The value `*` turns the check off on purpose, for when the proxy in front already restricts the Host.
90
90
 
package/docs/github.md CHANGED
@@ -94,7 +94,7 @@ Every delivery must carry a valid `X-Hub-Signature-256` for the secret (checked
94
94
  nothing. `ping` answers 200; `pull_request` events of the configured repo link and resolve as above; other events and other repos are
95
95
  acknowledged and ignored. The webhook needs no token: the event carries the pull request. A `--read-only` server refuses deliveries.
96
96
 
97
- The board's Host check still applies, so add the public name with `--allowed-host` (see [deployment.md](deployment.md)). If an
97
+ The board's Host check still applies, so add the public name with `--allowed-host` (see [Deployment and self-hosting](deployment.md)). If an
98
98
  authenticating proxy sits in front of the board, let `POST /api/github/webhook` through without the login; the signature is what protects
99
99
  it.
100
100