pi-pocket 0.27.0-beta.6 → 0.27.0-beta.8

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 (214) hide show
  1. package/docs/examples/design-system/README.md +1 -1
  2. package/docs/examples/design-system/pocket/.pi/design/guidelines.md +1 -1
  3. package/docs/extensions/people-values.md +1 -0
  4. package/docs/extensions/reference/api-versions.md +1 -0
  5. package/docs/extensions/reference/host.md +18 -4
  6. package/docs/extensions/reference/theme-surface.md +4 -0
  7. package/docs/features.md +5 -4
  8. package/docs/map.md +76 -71
  9. package/package.json +1 -2
  10. package/src/server/alerts.ts +6 -1
  11. package/src/server/app.ts +8 -20
  12. package/src/server/commands.ts +3 -18
  13. package/src/server/design/color.ts +26 -583
  14. package/src/server/design/components.ts +3 -22
  15. package/src/server/design/docsite-color-section.ts +102 -216
  16. package/src/server/design/docsite-components.ts +39 -55
  17. package/src/server/design/docsite-core.ts +174 -341
  18. package/src/server/design/docsite-css.ts +267 -0
  19. package/src/server/design/docsite-js.ts +215 -0
  20. package/src/server/design/docsite-markdown.ts +3 -27
  21. package/src/server/design/docsite-reference.ts +74 -232
  22. package/src/server/design/docsite-sanitize.ts +7 -22
  23. package/src/server/design/docsite-space.ts +75 -237
  24. package/src/server/design/docsite-type.ts +146 -119
  25. package/src/server/design/docsite.ts +208 -364
  26. package/src/server/design/export.ts +3 -7
  27. package/src/server/design/fix.ts +68 -57
  28. package/src/server/design/guide.ts +4 -30
  29. package/src/server/design/index.ts +9 -12
  30. package/src/server/design/lint-analyze-contrast.ts +153 -0
  31. package/src/server/design/lint-analyze-page.ts +326 -0
  32. package/src/server/design/lint-analyze-system.ts +332 -0
  33. package/src/server/design/lint-analyze-util.ts +60 -0
  34. package/src/server/design/lint-color.ts +52 -61
  35. package/src/server/design/lint-page-checks.ts +2 -13
  36. package/src/server/design/lint-page-elements.ts +1 -12
  37. package/src/server/design/lint-page-focus.ts +1 -5
  38. package/src/server/design/lint-page-literals.ts +2 -11
  39. package/src/server/design/lint-page-setup.ts +2 -8
  40. package/src/server/design/lint-page-states.ts +2 -9
  41. package/src/server/design/lint-page-values.ts +2 -17
  42. package/src/server/design/lint-page.ts +3 -21
  43. package/src/server/design/lint-suggest.ts +9 -53
  44. package/src/server/design/lint.ts +86 -739
  45. package/src/server/design/render.ts +1 -31
  46. package/src/server/design/scan-categorize.ts +43 -64
  47. package/src/server/design/scan-colors.ts +608 -22
  48. package/src/server/design/scan-facts-files.ts +71 -211
  49. package/src/server/design/scan-facts-use.ts +132 -344
  50. package/src/server/design/scan-facts.ts +90 -120
  51. package/src/server/design/scan-files.ts +97 -216
  52. package/src/server/design/scan-import-convert.ts +31 -75
  53. package/src/server/design/scan-import-eval.ts +106 -386
  54. package/src/server/design/scan-import.ts +416 -176
  55. package/src/server/design/scan-infer.ts +74 -77
  56. package/src/server/design/scan-palette.ts +52 -149
  57. package/src/server/design/scan-parse.ts +147 -644
  58. package/src/server/design/scan-prepare.ts +143 -175
  59. package/src/server/design/scan-render-pages.ts +78 -114
  60. package/src/server/design/scan-render-probe.ts +8 -36
  61. package/src/server/design/scan-render.ts +107 -182
  62. package/src/server/design/scan-roles.ts +492 -171
  63. package/src/server/design/scan-scales.ts +225 -526
  64. package/src/server/design/scan-tailwind.ts +94 -9
  65. package/src/server/design/scan-tree.ts +38 -115
  66. package/src/server/design/scan-variables.ts +221 -196
  67. package/src/server/design/scan-worker.ts +7 -0
  68. package/src/server/design/scan.ts +210 -369
  69. package/src/server/design/system-types.ts +6 -102
  70. package/src/server/design/system.ts +38 -127
  71. package/src/server/design/tokens-base.ts +49 -27
  72. package/src/server/design/tokens-compile.ts +5 -30
  73. package/src/server/design/tokens-dtcg.ts +5 -46
  74. package/src/server/design/tokens-io.ts +36 -38
  75. package/src/server/design/tokens-model-checks.ts +260 -0
  76. package/src/server/design/tokens-model-defs.ts +305 -0
  77. package/src/server/design/tokens-model-report.ts +144 -0
  78. package/src/server/design/tokens-model-resolve.ts +198 -0
  79. package/src/server/design/tokens-model.ts +188 -904
  80. package/src/server/design/tokens-names.ts +0 -8
  81. package/src/server/design/tokens-ramps.ts +2 -11
  82. package/src/server/design/tokens-summary.ts +2 -24
  83. package/src/server/design/tokens-tailwind.ts +4 -37
  84. package/src/server/design/tokens-values.ts +9 -17
  85. package/src/server/design/tokens.ts +16 -31
  86. package/src/server/docs.ts +0 -4
  87. package/src/server/extension-points.ts +56 -10
  88. package/src/server/extensions/artifacts.ts +2 -5
  89. package/src/server/extensions/ask.ts +146 -0
  90. package/src/server/extensions/design/app.js +2 -19
  91. package/src/server/extensions/design/canvas.js +3 -11
  92. package/src/server/extensions/design/check.js +37 -70
  93. package/src/server/extensions/design/color.d.ts +29 -0
  94. package/src/server/extensions/design/color.js +398 -259
  95. package/src/server/extensions/design/data.js +2 -10
  96. package/src/server/extensions/design/devices.js +2 -7
  97. package/src/server/extensions/design/docks.js +1 -10
  98. package/src/server/extensions/design/index.js +2 -12
  99. package/src/server/extensions/design/messages.js +0 -3
  100. package/src/server/extensions/design/parts.js +3 -4
  101. package/src/server/extensions/design/paths.js +1 -2
  102. package/src/server/extensions/design/picker.js +1 -3
  103. package/src/server/extensions/design/specimen.js +5 -7
  104. package/src/server/extensions/design/state.js +1 -7
  105. package/src/server/extensions/design/style.css +17 -102
  106. package/src/server/extensions/design/system-actions.js +4 -24
  107. package/src/server/extensions/design/system-api.ts +11 -26
  108. package/src/server/extensions/design/system-data.js +2 -21
  109. package/src/server/extensions/design/system-preview.js +0 -5
  110. package/src/server/extensions/design/system-routes.ts +366 -486
  111. package/src/server/extensions/design/system-sections.js +359 -539
  112. package/src/server/extensions/design/system-ui.js +2 -8
  113. package/src/server/extensions/design/system-view.js +158 -298
  114. package/src/server/extensions/design/system-widgets.js +245 -342
  115. package/src/server/extensions/design/system.css +123 -379
  116. package/src/server/extensions/design/system.js +32 -222
  117. package/src/server/extensions/design/unsaved.js +1 -7
  118. package/src/server/extensions/design/workspace.js +3 -8
  119. package/src/server/extensions/design.ts +2 -8
  120. package/src/server/extensions/gallery.ts +0 -1
  121. package/src/server/extensions/plan.ts +1 -0
  122. package/src/server/extensions/subagents.ts +3 -1
  123. package/src/server/extensions/updates/index.js +0 -2
  124. package/src/server/extensions/updates.ts +1 -3
  125. package/src/server/gallery/reach.ts +62 -54
  126. package/src/server/gallery.ts +0 -13
  127. package/src/server/host.ts +20 -1
  128. package/src/server/http/artifact-inspect.ts +12 -24
  129. package/src/server/pip.ts +1 -11
  130. package/src/server/reload.ts +3 -0
  131. package/src/server/updates.ts +7 -46
  132. package/src/server/versions.ts +2 -13
  133. package/types/pocket.d.ts +46 -1
  134. package/web/artifact-bridge.js +1 -3
  135. package/web/calls.js +20 -0
  136. package/web/composer.js +10 -4
  137. package/web/peeks.js +6 -1
  138. package/web/quote-reply.js +0 -4
  139. package/web/quote-text.js +1 -7
  140. package/web/seen.js +1 -6
  141. package/web/sessions.js +22 -65
  142. package/web/sheets/appearance.js +1 -1
  143. package/web/sheets/extensions.js +1 -3
  144. package/web/sheets/file.js +1 -2
  145. package/web/sheets/gallery.js +7 -57
  146. package/web/sheets/people.js +0 -1
  147. package/web/sheets/session.js +3 -24
  148. package/web/sheets.js +0 -1
  149. package/web/store.js +1 -9
  150. package/web/style.css +160 -36
  151. package/web/theme-surface.js +4 -0
  152. package/web/theme.js +0 -1
  153. package/web/transcript.js +125 -28
  154. package/docs/design/design-system.md +0 -165
  155. package/docs/design/ds-notes-b.md +0 -61
  156. package/docs/design/ds-notes-g.md +0 -170
  157. package/docs/design/ds-notes-t.md +0 -303
  158. package/docs/design/ds-notes-u.md +0 -220
  159. package/docs/design/ds-notes-v.md +0 -186
  160. package/docs/design/ds-rounds.md +0 -160
  161. package/docs/design/ds-u-bridge.patch +0 -732
  162. package/docs/examples/design-system/pocket/.pi/design/dist/components.css +0 -730
  163. package/docs/examples/design-system/pocket/.pi/design/dist/names.md +0 -495
  164. package/docs/examples/design-system/pocket/.pi/design/dist/tailwind.css +0 -1132
  165. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.css +0 -1126
  166. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.dark.resolved.json +0 -2022
  167. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.high-contrast.resolved.json +0 -2022
  168. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.light.resolved.json +0 -2022
  169. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.resolved.json +0 -371
  170. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.studio.json +0 -5915
  171. package/src/server/design/check-cli.ts +0 -283
  172. package/src/server/design/docsite-assets.ts +0 -29
  173. package/src/server/design/docsite-color.ts +0 -303
  174. package/src/server/design/docsite-css-base.ts +0 -397
  175. package/src/server/design/docsite-css-content.ts +0 -477
  176. package/src/server/design/docsite-css-phone.ts +0 -251
  177. package/src/server/design/docsite-css-reference.ts +0 -374
  178. package/src/server/design/docsite-css-specimens.ts +0 -465
  179. package/src/server/design/docsite-js-code.ts +0 -96
  180. package/src/server/design/docsite-js-core.ts +0 -72
  181. package/src/server/design/docsite-js-demos.ts +0 -24
  182. package/src/server/design/docsite-js-links.ts +0 -25
  183. package/src/server/design/docsite-js-nav.ts +0 -73
  184. package/src/server/design/docsite-js-stages.ts +0 -81
  185. package/src/server/design/docsite-js-table.ts +0 -81
  186. package/src/server/design/docsite-motion.ts +0 -110
  187. package/src/server/design/docsite-shadows.ts +0 -45
  188. package/src/server/design/scan-braces.ts +0 -115
  189. package/src/server/design/scan-channels.ts +0 -113
  190. package/src/server/design/scan-color-base.ts +0 -209
  191. package/src/server/design/scan-color-names.ts +0 -403
  192. package/src/server/design/scan-color-palette.ts +0 -91
  193. package/src/server/design/scan-color-roles.ts +0 -565
  194. package/src/server/design/scan-facts-antd.ts +0 -171
  195. package/src/server/design/scan-facts-lists.ts +0 -538
  196. package/src/server/design/scan-facts-sass.ts +0 -113
  197. package/src/server/design/scan-facts-theme.ts +0 -400
  198. package/src/server/design/scan-facts-wordpress.ts +0 -374
  199. package/src/server/design/scan-import-material.ts +0 -745
  200. package/src/server/design/scan-import-sd-config.ts +0 -370
  201. package/src/server/design/scan-import-sd.ts +0 -381
  202. package/src/server/design/scan-import-studio.ts +0 -242
  203. package/src/server/design/scan-js-eval.ts +0 -1267
  204. package/src/server/design/scan-review.ts +0 -54
  205. package/src/server/design/scan-sass-colors.ts +0 -275
  206. package/src/server/design/scan-sass-eval.ts +0 -269
  207. package/src/server/design/scan-sass-expr.ts +0 -911
  208. package/src/server/design/scan-sass-modules.ts +0 -353
  209. package/src/server/design/scan-sass-run.ts +0 -1003
  210. package/src/server/design/scan-sass-stmt.ts +0 -256
  211. package/src/server/design/scan-sass-values.ts +0 -886
  212. package/src/server/design/scan-theme-shapes.ts +0 -579
  213. package/src/server/design/scan-util.ts +0 -44
  214. package/src/server/design/system-schema.ts +0 -68
@@ -1,6 +1,6 @@
1
1
  # Example design system: Pi Pocket
2
2
 
3
- `pocket/.pi/design/` is Pi Pocket's own design system, written the way Design mode expects it (see [Design systems](../../design/design-system.md)). It is the reference for the file format and a ready system to try.
3
+ `pocket/.pi/design/` is Pi Pocket's own design system, written the way Design mode expects it (see the design system in [features.md](../../features.md)). It is the reference for the file format and a ready system to try.
4
4
 
5
5
  | File | What it holds |
6
6
  | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -64,7 +64,7 @@ Pi Pocket looks like a tiling window manager that learned to be gentle: soft til
64
64
  ## Using the system
65
65
 
66
66
  - Link `ds/tokens.css` and use `var(--…)` for every color, size, space, radius, shadow, and duration.
67
- - Reuse a component from `components/` before you write a new one. Copy its markup and its classes. The CSS of every component is in `dist/components.css`.
67
+ - Reuse a component from `components/` before you write a new one. Copy its markup and its classes. Link `ds/components.css` for the CSS of every component.
68
68
  - For dark mode, set `data-theme="dark"` on the root. The system also follows `prefers-color-scheme`.
69
69
  - A design that needs a value the system does not have asks for a new token. It does not invent one in place.
70
70
 
@@ -45,6 +45,7 @@ if (!answer.answered) {
45
45
 
46
46
  - The values are in `answer.values`, by field name. They are not in the transcript, nor sent to the other people in the session. A plain Allow, as from a notification, is refused: each field must be filled in.
47
47
  - With no fields, the card is a question that the button answers: "Solve the CAPTCHA in the browser, then tap Done".
48
+ - Since 0.27.0, a field can have `choices`: 2 to 4 answers that show as buttons, with `multiple` for one or more and `other` for an answer the person types. Its value is the label chosen (labels one per line with `multiple`). Pi's own `ask` tool uses them ([the reference](reference/host.md#askfield)).
48
49
  - **Do not keep the values** in `api.memo` or a document: a restart would find them there. A tool that asks is not safe to replay (the default), so a call that a restart cut off comes back as interrupted, and Pi asks again.
49
50
  - Tell Pi what happened, never the values: "Signed in as the person".
50
51
 
@@ -87,3 +87,4 @@ Each member in the reference has its own Since line. These parts came together:
87
87
  | Give PiP a message: `pocket.pip.ask` (experimental) | 0.26.0 |
88
88
  | A person's role: `host.roleOf` (experimental) | 0.27.0 |
89
89
  | The page's scroll position: `scroll` in the `host.browser` snapshot (experimental) | 0.27.0 |
90
+ | Answers to pick on an ask's card: `header`, `choices`, `multiple`, and `other` in `AskField` (experimental) | 0.27.0 |
@@ -537,18 +537,32 @@ Since 0.22.0 · Experimental
537
537
  interface AskField {
538
538
  name: string;
539
539
  label: string;
540
+ header?: string;
541
+ choices?: AskChoice[];
542
+ multiple?: boolean;
543
+ other?: boolean;
540
544
  secret?: boolean;
541
545
  placeholder?: string;
542
546
  autocomplete?: string;
543
547
  }
548
+
549
+ interface AskChoice {
550
+ label: string;
551
+ description?: string;
552
+ }
544
553
  ```
545
554
 
546
- Since 0.22.0 · Experimental
555
+ Since 0.22.0 · Experimental. `header`, `choices`, `multiple`, `other`, and `AskChoice` since 0.27.0.
547
556
 
548
557
  - `name`: the value's key in the answer: letters, digits, and `_`, up to 40, starting with a letter. Each field's is its own.
549
- - `label`: what the card says above the field.
550
- - `secret`: a hidden input, as for a password.
551
- - `autocomplete`: a hint for the browser and the phone's keyboard, such as `username`, `current-password`, or `one-time-code`.
558
+ - `label`: what the card says above the field, one line of up to 80 characters. A field with `choices` has its question here, up to 300.
559
+ - `header`: a short tag over the field, such as "Database", up to 12 characters.
560
+ - `choices`: 2 to 4 answers to pick, shown as buttons, with different labels. A choice's `label` is one line of up to 60 characters, and its `description`, under it, of up to 160. The field's value is the label chosen.
561
+ - `multiple`: with `choices`, the person can choose one or more. The value is their labels, one per line, in the order of `choices`.
562
+ - `other`: with `choices`, the person can type an answer of their own instead, and the value is what they typed. Its `placeholder` is the words of that field while it is empty.
563
+ - A value that is not one of the choices (and with no `other`) is refused, with an error that names the field, never the value.
564
+ - `secret`: a hidden input, as for a password. Not for a field with `choices`.
565
+ - `autocomplete`: a hint for the browser and the phone's keyboard, such as `username`, `current-password`, or `one-time-code`. Not for a field with `choices`.
552
566
 
553
567
  ### `AskAnswer`
554
568
 
@@ -143,6 +143,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
143
143
  | `prompt-head`, `author-mark`, `prompt-author` | Its head: who sent it and when; their initials; their name |
144
144
  | `prompt-text` | What it says (its skill chip, words, and files) |
145
145
  | `reply` | Pi's answer |
146
+ | `reply-quote` | The passage a reply quotes, at the top of a message (since 0.27.0) |
146
147
  | `reply-actions` | The row under an answer: react, discuss, pin, copy |
147
148
  | `activity`, `activity-head`, `activity-chevron` | A group of what Pi did, its head (what it did, how long), and the chevron that opens it |
148
149
  | `timeline` | The open group's steps, on a rule |
@@ -164,6 +165,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
164
165
  | `dock` | What sits above the message box: the queue and the bars |
165
166
  | `subagents-bar` | The subagents' bar |
166
167
  | `message-box` | The box you type in, with its buttons |
168
+ | `quote-strip` | Above the box: the passage a reply quotes, with a button to remove it (since 0.27.0) |
167
169
  | `composer-tools` | The row of buttons in it |
168
170
  | `composer-button` | Each of its own buttons: Places, Attach, Plan, the mic, Steer and Queue, Stop, and an extension's button (since 0.19.0) |
169
171
  | `plan-chip`, `mode-switch`, `stop-button` | Plan, Steer and Queue, and Stop, each also a `composer-button` |
@@ -180,6 +182,8 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
180
182
  | `sheet` | A sheet: a bottom sheet on phones, a window on wide screens. `data-sheet` says which (`appearance`, `menu`, `model`, …; `ext` for an extension's) |
181
183
  | `sheet-head`, `sheet-body` | Its title bar, and what it holds |
182
184
  | `menu` | The menu, on wide screens (it is the sheet `menu` on phones) |
185
+ | `session-menu` | The right-click menu on a session row (since 0.27.0) |
186
+ | `quote-reply-button` | The Reply button that shows over selected text (since 0.27.0) |
183
187
  | `launcher` | The launcher (Ctrl/⌘+K) |
184
188
  | `launcher-input`, `launcher-filters` | Its search field, and the search types under it |
185
189
  | `launcher-group`, `launcher-row` | A group's heading, and each result |
package/docs/features.md CHANGED
@@ -70,10 +70,10 @@ The full tour. For setup, see the [README](../README.md).
70
70
  - **Variations.** Artifacts of one group show as a grid of live thumbnails. **Use this one** puts a message about it in the message box.
71
71
  - **Export and share.** PNG, PDF, PPTX (decks), and an HTML zip, from the menu. The file is written in the session's `exports/` folder and the browser downloads it. **Share a link** is the artifact viewer's Share. There is no Canva export.
72
72
  - **What Pi does.** Its guide (a prompt section, only while the module is on) gives Pi an order of work, after Claude Design's (since 0.27.0): one round of questions when the work is new or unclear, then a start from what exists (the design system, the code, the screens) rather than a mock from scratch, a first version early, iterations, a check, and a short reply. A screen that exists is redesigned from itself: Pi reads its code and data first, makes version 1 the screen as it is today (in its place in the app, compared with a screenshot of the real one when it can get one), and then changes it in new versions, within what the code supports; a change that needs new data or server work is marked in the design and named in the reply, and a different direction becomes a new artifact in the same group. The product's own type sizes, spacing, and density win over the guide's craft defaults. It also gives Pi a page skeleton and craft rules: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs bound to the system's tokens, assets for images and fonts, variations as a group of 2 to 4 artifacts, a link to `ds/tokens.css` when the project has a design system, and a check with `design_preview` before it replies. When the project has a system, the guide carries a summary of it (roles and components first) as untrusted project data. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes, or the sizes asked for, and returns screenshots and a short report (see **Checks**); its options are `checks` (on by default), `tweaks`, `colorScheme`, `page` (another page of the bundle), and `actions` (hover, click, or focus on a selector before the screenshot). `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; it also takes `tweaks`, a custom `viewport`, and, for a deck's PNG, `slide` (a number, or `"all"` for a zip of every slide). A page's PDF is as wide as its viewport, and PPTX slide images have twice the pixels. `design_system` reads, scans, and changes the project's design system (see **The design system**). The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. Renders run 2 at once, and more wait their turn; each has 90 seconds.
73
- - **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, motion, and dark mode, from CSS variables, Tailwind, SCSS, theme objects, token files such as Tokens Studio, and WordPress `theme.json`), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
73
+ - **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, breakpoints, and dark mode, from CSS custom properties and rules in CSS, SCSS, Less, and page style blocks, Sass and Less variables with literal values, Tailwind's `@theme` and a `tailwind.config` theme read as a literal, and DTCG, Style Dictionary, and Tokens Studio JSON files; a browser renders the project's pages to fill in what the files leave out), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
74
74
  - **The System view.** The first row of the design picker (or `/design-open system`, or the launcher's "Open the design system") shows the system: **Colors** (role cards with contrast badges first, a live sample card, and the palette as ramp strips in a folded group), **Type**, **Spacing**, **Radii**, **Shadows** (each with its value), **Motion** (durations and easings that play), **Components** (every state, in a frame that runs nothing and loads nothing), and **Guidelines**. A section's count is its role tokens; the palette and component tokens show their own counts inside it. Modes show one at a time or side by side, and a mode's value says whether it is its own or inherited from the default. People who steer change a color, a size, a time, a weight, a font, an easing, or a shadow's layers in place, or link a token to another; the open design shows each change live when it uses the system's variables. The editor lists every contrast pair of a color (an exempt pair shows as exempt, not as a failure). **Undo** and **Redo** step through the changes, **Discard** gives them up, and **Save** writes the files and the generated CSS with no run of Pi (it refuses a change that the checks refuse, or one made on a system that changed meanwhile). The menu publishes the documentation page as a design, exports the generated files as a zip, and adds or removes a mode. People who only view see everything and change nothing. **Focus mode** hides the conversation for wide work. On a phone, the canvas fits the screen's width, and until a size is chosen it takes the size of its panel. The Design module loads only a small shell at app start; the workspace and the System view load when first opened.
75
- - **Checks.** A design's **Check** tab, `design_preview`, and `npm run design:check` (for CI: `src/server/design/check-cli.ts` on an HTML file and a `.pi/design` folder; exit 1 on an error, 2 without Chromium) render the page on the server and judge only what the author's CSS sets, never the browser's defaults. They report values that are not the system's (colors, fonts, and sizes, each with the exact CSS edit and the nearest token of the matching role), contrast (WCAG 2.2 AA, judged only where the background is certain), non-text contrast of focus rings and icon buttons (3:1), tap targets (an error under 24 px, a warning under 44 px), sideways overflow, image alt text, heading order, a missing `lang`, form controls with no label (a placeholder is not a label), links, buttons, and widgets with no accessible name, no `main` landmark, fonts that did not load, a missing viewport tag, missing `data-pid`s, elements with no visible focus style, long motion with no `prefers-reduced-motion` rule, and author-set input text under 16 px on a phone. A check runs in any mode of the system. The tab follows the mode and size on the canvas, puts a pin on each element, and **Send to Pi** puts one message with every finding in the message box. **Fix N exact matches** rewrites literals that equal a token exactly to `var(--token)` and saves a new version with no run of Pi. On a phone, the tab starts as a bar with the counts, so the page keeps most of the screen.
76
- - **The documentation page.** The System view's menu (and `design_system`) makes a documentation page of the system as a design: navigation, a filter of names and values, and links to every section; color roles with their values, contrast, and copy buttons for the CSS variable, the Tailwind class, and the JSON path; a text-on-ground matrix and the contrast pairs in every mode (exempt pairs labelled); palettes, type specimens, spacing, radii, shadows, and motion demos; component state grids with their code; guidelines; every token with a column for each mode; and "Use it" blocks for CSS, Tailwind v4, DTCG JSON (Style Dictionary), and Tokens Studio. Component states are drawn in shadow roots after an allowlist sanitizer, under a nonce-only script policy, so they paint in screenshots and PDFs and run nothing. It runs in the artifact sandbox with no network, so it can be shared with a link or exported like any design.
75
+ - **Checks.** A design's **Check** tab and `design_preview` render the page on the server and judge only what the author's CSS sets, never the browser's defaults. They report values that are not the system's (colors, fonts, and sizes, each with the exact CSS edit and the nearest token of the matching role), contrast (WCAG 2.2 AA, judged only where the background is certain), non-text contrast of focus rings and icon buttons (3:1), tap targets (an error under 24 px, a warning under 44 px), sideways overflow, image alt text, heading order, a missing `lang`, form controls with no label (a placeholder is not a label), links, buttons, and widgets with no accessible name, no `main` landmark, fonts that did not load, a missing viewport tag, missing `data-pid`s, elements with no visible focus style, long motion with no `prefers-reduced-motion` rule, and author-set input text under 16 px on a phone. A check runs in any mode of the system. The tab follows the mode and size on the canvas, puts a pin on each element, and **Send to Pi** puts one message with every finding in the message box. **Fix N exact matches** rewrites literals that equal a token exactly to `var(--token)` and saves a new version with no run of Pi. On a phone, the tab starts as a bar with the counts, so the page keeps most of the screen.
76
+ - **The documentation page.** The System view's menu (and `design_system`) makes a documentation page of the system as a design: navigation, a filter of names and values, and links to every section; color roles with their values, contrast, and copy buttons for the CSS variable and the Tailwind class; the contrast pairs in every mode (exempt pairs labelled); palettes, type specimens, spacing, radii, shadows, and motion demos; component state grids with their code; guidelines; every token with a column for each mode; and a list of the generated files with how to use them. Component states are drawn in shadow roots after an allowlist sanitizer, under a nonce-only script policy, so they paint in screenshots and PDFs and run nothing. It runs in the artifact sandbox with no network, so it can be shared with a link or exported like any design.
77
77
  - **Decks.** A deck is a page with `<meta name="pocket-kind" content="deck">` and its slides as `<section class="slide">`, written at 1920×1080 (`<meta name="pocket-slide-size" content="1280x720">` changes that). The canvas shows one slide at a time, scaled to fit, with a slide strip, a full-screen present mode, arrow keys, and swipes, and the page needs no navigation script of its own. PNG, PDF, and PPTX exports use the same slide size. PPTX slides are images with the slide's text as speaker notes, not editable shapes. A deck opened in its own tab or published shows one slide at a time too, and printing it gives one page for each slide.
78
78
  - **For page authors.** `data-pid` names an element for comments and pins. The tweaks manifest is `<script type="application/json" id="pocket-tweaks">[…]</script>`, an array of up to 40 knobs `{ name, label?, type: "range" | "color" | "select" | "toggle" | "text", value, min?, max?, step?, unit?, options? }`. A name that starts with `--` sets that CSS custom property on `:root`; any other name reaches the page as a `pocket:tweak` event on `window`. The app speaks to the page through the bridge's `pocket-inspect`, `pocket-edit-text`, `pocket-tweak-set`, `pocket-highlight`, and `pocket-goto` messages, and the page answers with `pocket-picked`, `pocket-text-edited`, `pocket-tweaks`, and `pocket-deck`. Only the app's inspector can send those answers, and the app checks their shape and length before it uses them.
79
79
  - **Who.** People who see every session load the module; people who steer comment, edit, tweak, go back, and export; viewers read the canvas, versions, and comments. Someone invited to one session never loads it. While **Take turns** is on, only the driver writes.
@@ -107,6 +107,7 @@ The full tour. For setup, see the [README](../README.md).
107
107
  - **Lancet Guard.** Off by default: the owner turns it on in Menu → **Extensions**. If `specpi-lancet-guard` is installed in Pi and turned on there too, its rules and classifier check every bash, write, and edit call, and each command Pi starts in the background. A "risky" or "unsure" verdict shows Allow/Deny buttons to everyone in the session; the answer survives restarts. The classifier needs the LANCET Nano model, a one-time download of about 109 MB. While it is missing, the guard row in Extensions says so and the owner gets a **Download** button there: it fetches the pinned release from GitHub, checks it against fixed checksums, and installs it where Pi's own `/lancet-guard setup` puts it, so Pi uses it too. Progress shows in every tab, and nothing downloads it without that button. A guard that is on without its model blocks the bash calls its local rules leave open, and the status line shows "guard failed".
108
108
  - **Codemode.** On by default, like `"+codemode"` in Pi's `defaultTools`. The `codemode` tool runs JavaScript the agent writes in a QuickJS sandbox with no Node, files, network, or timers; its only capability is calling the agent's other tools as `tools.<name>(args)`. Use it to batch independent calls, chain them, or filter large output before it reaches the model. Each call a script makes goes through the same checks and hooks as a direct call, so Lancet Guard judges it and can ask for approval. `store()` and `load()` keep values per conversation. Its card shows the script, each call it made, and the output.
109
109
  - **Share to Pi.** With Pi Pocket on the home screen (Android), share a link, some text, or a screenshot from any app to Pi Pocket: pick a session or a new one, and it goes into the message box with the files attached, ready to send.
110
+ - **Pi's questions.** Since 0.27.0, Pi's `ask` tool asks the person it works for 1 to 4 questions on a card at its call, when a decision changes the work and only they can make it. Each question has a short tag, the question, and 2 to 4 answers as buttons, each with a line under it; a tap chooses one (or several, where the question allows it), and **Or type your own answer** takes a typed one instead. **Send** is on once each question has an answer; **Decline** answers nothing, and Pi goes on with its best judgment. Pi waits for the answer, for hours if it must, and after a restart the same card asks again. Pi gets one line per question (`Storage: Local storage`), and the call shows each question and its answer to everyone in the session. The card shows, and notifies, as an extension's question does (below). It runs in plan mode, the guard never asks about it, and subagents do not have it. The **Ask** module, on by default (Menu → Extensions).
110
111
  - **Questions from extensions.** An extension can ask the person Pi works for on a card, as an approval asks: a sign-in, a one-time code, a key, or "solve the CAPTCHA, then tap Done". Only that person can fill it in (the owner, when nobody is known); anyone who can steer can **Decline**. What is typed goes to the extension, never to Pi, into the transcript, or to the other people here, and the call's line says **Answered** or **Declined** by whom. A notification goes to that person alone, and opens the session: the fields are filled in in the app. Extensions can also hide values (they show as `[label]` in command output, tool results, and in a message to Pi that someone pasted one into), give commands environment variables, and use the session's browser page. Since 0.22.0 ([docs/extensions/people-values.md](extensions/people-values.md)).
111
112
  - **Approvals need someone else.** An owner setting under Lancet Guard in Menu → **Extensions**: a guest cannot allow a risky call that their own message led to. Someone else has to; the owner always can.
112
113
  - **Docs for agents.** Pi's system prompt says where Pi Pocket's documentation is ([index.md](index.md)), to read when someone asks about Pi Pocket itself: changing how Pi works without code, writing extensions (with tested examples), and changing Pi Pocket's code while it runs, checked first on a throwaway copy (`node test/serve.ts`).
@@ -115,7 +116,7 @@ The full tour. For setup, see the [README](../README.md).
115
116
  - **Extension workspace APIs (0.16.0).** A page can save its own durable catalog with request-lifetime document commits, or use a source-bound route to start linked sessions as the person who clicked Run. Current source access, turn, plan, spend, team, and model checks apply; explicit thinking choices are not silently lowered. Human history can open authorized sessions through `pocket.openConversation`. Extensions can read the running server's package version through `host.pocketVersion` or browser `pocket.pocketVersion`, without an updater or restart control; the extension API level remains 1.
116
117
  - **Extensions hub.** Menu → **Extensions** opens **Discover**, **Installed**, and **Updates**, as tabs in the sheet's head, for the owner while the gallery is on. Wide screens show the list and the selected entry side by side; phones show one at a time, with Back returning to the filtered list. The list is in sections: **Extensions** as dense rows divided by hairlines (a small mark, the name and its maker, one line about it, and up to three facts of what it reaches or adds, such as `openrouter.ai`, `a key`, `sees turns`, or `2 tools`), and **Themes** as cards, each a tiny desktop drawn in the theme's own colors with its color dots (since 0.27.0). Filters narrow Discover to **Extensions** or **Themes**, and to those with **Tools for Pi**, a part **In the app**, or ones that **Change Pi** (hooks, prompt sections, wraps). **Installed** (also tap "guard" in the status line, which opens it with **Built in** unfolded) lists your **Extensions** (from the gallery and your own drop-ins) first, each with how it stands now: **On**, **Off**, **Did not load** (with the error under it), **Off in this tab** (its browser part failed here), **Edited since install**, or **Revoked**; then your **Themes** (from the gallery, and your own, marked **Yours**, which open Appearance); then the **Built in** modules, folded under one line that says how many are on, and unfolded by a search or a module that did not load. A module's row shows its tools, the routes, commands, and browser module it adds to the app, and any load error, in this browser too. The owner can turn Artifacts, Design, Browser, Subagents, Scheduled messages, Done when, Plan mode, Codemode, Memory, PiP, Triggers, Extension gallery, Pi Pocket updates, Agent Teams, Session tags, Lancet Guard, or a drop-in off and on, or reload one; the change applies to every session at once, stays after restarts (`disabledExtensions` and `enabledExtensions` in `~/.pi-pocket/config.json`), and everyone in a session sees who changed what. Turning Lancet Guard off first shows a warning card with **Keep it on** and **Turn off**; only **Turn off** applies the change. This leaves Pi's own setting (`~/.pi/lancet-guard.json`) alone. Under PiP, the owner picks when PiP compacts its context. The system prompt cannot be turned off.
117
118
  - **Extension settings.** A module can declare settings (on or off, text, a number, a choice, or a secret such as an API key); the owner changes them in Menu → Extensions under the module, with **Save settings**, and **Default** or **Clear** to put one back. A secret's value never leaves the server: the sheet shows only that it is set. Modules can also listen to what happens in the app (sessions made, renamed, and archived, messages, runs) and offer services to each other; Extensions says which ones offer a service. Since 0.22.0 ([docs/extensions/services-settings.md](extensions/services-settings.md)).
118
- - **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files in its data folder"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none), and the files it writes (`its data folder`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
119
+ - **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files it writes"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, and that the scan reads text so the code can reach more, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code, or gives one of them, or a `net`, `tls`, or `dgram` connection, an address it builds, also beside hosts it names), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none, or loads code the scan cannot read: `eval`, `new Function`, `getBuiltinModule`, `process.binding` or `dlopen`, `import()` or `require()` of a name it builds, or a `.node` file), and the files it writes (`files it writes`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
119
120
  - **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
120
121
  - **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (above Models for subagents), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
121
122
  - **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them.