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

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 (200) hide show
  1. package/docs/design/design-system.md +2 -2
  2. package/docs/extensions/people-values.md +1 -0
  3. package/docs/extensions/reference/api-versions.md +1 -0
  4. package/docs/extensions/reference/host.md +18 -4
  5. package/docs/extensions/reference/theme-surface.md +4 -0
  6. package/docs/features.md +2 -1
  7. package/docs/map.md +82 -71
  8. package/package.json +2 -2
  9. package/src/server/alerts.ts +6 -1
  10. package/src/server/app.ts +8 -20
  11. package/src/server/commands.ts +3 -18
  12. package/src/server/design/check-cli.ts +0 -17
  13. package/src/server/design/color.ts +35 -74
  14. package/src/server/design/components.ts +3 -22
  15. package/src/server/design/docsite-assets.ts +2 -10
  16. package/src/server/design/docsite-color-section.ts +7 -23
  17. package/src/server/design/docsite-color.ts +59 -95
  18. package/src/server/design/docsite-components.ts +2 -13
  19. package/src/server/design/docsite-core.ts +18 -54
  20. package/src/server/design/docsite-css-base.ts +0 -2
  21. package/src/server/design/docsite-css-content.ts +1 -4
  22. package/src/server/design/docsite-css-phone.ts +1 -6
  23. package/src/server/design/docsite-css-reference.ts +1 -12
  24. package/src/server/design/docsite-css-specimens.ts +1 -3
  25. package/src/server/design/docsite-js-code.ts +1 -7
  26. package/src/server/design/docsite-js-core.ts +0 -3
  27. package/src/server/design/docsite-js-demos.ts +1 -3
  28. package/src/server/design/docsite-js-links.ts +1 -4
  29. package/src/server/design/docsite-js-nav.ts +1 -6
  30. package/src/server/design/docsite-js-stages.ts +1 -4
  31. package/src/server/design/docsite-js-table.ts +1 -4
  32. package/src/server/design/docsite-markdown.ts +3 -13
  33. package/src/server/design/docsite-motion.ts +1 -1
  34. package/src/server/design/docsite-reference.ts +2 -22
  35. package/src/server/design/docsite-sanitize.ts +7 -22
  36. package/src/server/design/docsite-shadows.ts +0 -7
  37. package/src/server/design/docsite-space.ts +0 -6
  38. package/src/server/design/docsite-type.ts +1 -6
  39. package/src/server/design/docsite.ts +3 -28
  40. package/src/server/design/export.ts +3 -7
  41. package/src/server/design/fix.ts +5 -42
  42. package/src/server/design/guide.ts +4 -30
  43. package/src/server/design/index.ts +9 -12
  44. package/src/server/design/lint-analyze-contrast.ts +153 -0
  45. package/src/server/design/lint-analyze-page.ts +326 -0
  46. package/src/server/design/lint-analyze-system.ts +318 -0
  47. package/src/server/design/lint-analyze-util.ts +60 -0
  48. package/src/server/design/lint-color.ts +26 -58
  49. package/src/server/design/lint-page-checks.ts +2 -13
  50. package/src/server/design/lint-page-elements.ts +1 -12
  51. package/src/server/design/lint-page-focus.ts +1 -5
  52. package/src/server/design/lint-page-literals.ts +2 -11
  53. package/src/server/design/lint-page-setup.ts +2 -8
  54. package/src/server/design/lint-page-states.ts +2 -9
  55. package/src/server/design/lint-page-values.ts +2 -17
  56. package/src/server/design/lint-page.ts +3 -21
  57. package/src/server/design/lint-suggest.ts +9 -53
  58. package/src/server/design/lint.ts +86 -739
  59. package/src/server/design/render.ts +1 -31
  60. package/src/server/design/scan-braces.ts +2 -8
  61. package/src/server/design/scan-categorize.ts +2 -8
  62. package/src/server/design/scan-channels.ts +7 -18
  63. package/src/server/design/scan-color-base.ts +3 -21
  64. package/src/server/design/scan-color-names.ts +1 -7
  65. package/src/server/design/scan-color-palette.ts +1 -7
  66. package/src/server/design/scan-color-roles.ts +3 -16
  67. package/src/server/design/scan-colors.ts +1 -8
  68. package/src/server/design/scan-facts-antd.ts +0 -14
  69. package/src/server/design/scan-facts-files.ts +0 -13
  70. package/src/server/design/scan-facts-lists.ts +6 -42
  71. package/src/server/design/scan-facts-sass.ts +0 -8
  72. package/src/server/design/scan-facts-theme.ts +3 -26
  73. package/src/server/design/scan-facts-use.ts +1 -21
  74. package/src/server/design/scan-facts-wordpress.ts +1 -16
  75. package/src/server/design/scan-facts.ts +1 -27
  76. package/src/server/design/scan-files.ts +41 -26
  77. package/src/server/design/scan-import-convert.ts +1 -14
  78. package/src/server/design/scan-import-eval.ts +24 -37
  79. package/src/server/design/scan-import-material.ts +4 -58
  80. package/src/server/design/scan-import-sd-config.ts +2 -34
  81. package/src/server/design/scan-import-sd.ts +95 -68
  82. package/src/server/design/scan-import-studio.ts +0 -22
  83. package/src/server/design/scan-import.ts +1 -36
  84. package/src/server/design/scan-infer.ts +2 -21
  85. package/src/server/design/scan-js-eval.ts +17 -49
  86. package/src/server/design/scan-palette.ts +0 -14
  87. package/src/server/design/scan-parse.ts +25 -101
  88. package/src/server/design/scan-prepare.ts +1 -24
  89. package/src/server/design/scan-render-pages.ts +3 -26
  90. package/src/server/design/scan-render-probe.ts +2 -20
  91. package/src/server/design/scan-render.ts +8 -38
  92. package/src/server/design/scan-review.ts +0 -7
  93. package/src/server/design/scan-roles.ts +0 -9
  94. package/src/server/design/scan-sass-colors.ts +0 -11
  95. package/src/server/design/scan-sass-eval.ts +4 -45
  96. package/src/server/design/scan-sass-expr.ts +0 -33
  97. package/src/server/design/scan-sass-modules.ts +3 -43
  98. package/src/server/design/scan-sass-run.ts +1 -35
  99. package/src/server/design/scan-sass-stmt.ts +1 -15
  100. package/src/server/design/scan-sass-values.ts +5 -38
  101. package/src/server/design/scan-scales.ts +6 -51
  102. package/src/server/design/scan-tailwind.ts +1 -9
  103. package/src/server/design/scan-theme-shapes.ts +13 -33
  104. package/src/server/design/scan-tree.ts +9 -16
  105. package/src/server/design/scan-util.ts +0 -7
  106. package/src/server/design/scan-variables.ts +39 -30
  107. package/src/server/design/scan-worker.ts +7 -0
  108. package/src/server/design/scan.ts +67 -85
  109. package/src/server/design/system-schema.ts +3 -20
  110. package/src/server/design/system-types.ts +6 -102
  111. package/src/server/design/system.ts +4 -23
  112. package/src/server/design/tokens-base.ts +49 -27
  113. package/src/server/design/tokens-compile.ts +5 -30
  114. package/src/server/design/tokens-dtcg.ts +5 -46
  115. package/src/server/design/tokens-io.ts +36 -38
  116. package/src/server/design/tokens-model-checks.ts +260 -0
  117. package/src/server/design/tokens-model-defs.ts +299 -0
  118. package/src/server/design/tokens-model-report.ts +144 -0
  119. package/src/server/design/tokens-model-resolve.ts +198 -0
  120. package/src/server/design/tokens-model.ts +188 -904
  121. package/src/server/design/tokens-names.ts +0 -8
  122. package/src/server/design/tokens-ramps.ts +2 -11
  123. package/src/server/design/tokens-summary.ts +2 -24
  124. package/src/server/design/tokens-tailwind.ts +4 -37
  125. package/src/server/design/tokens-values.ts +9 -17
  126. package/src/server/design/tokens.ts +16 -31
  127. package/src/server/docs.ts +0 -4
  128. package/src/server/extension-points.ts +56 -10
  129. package/src/server/extensions/artifacts.ts +2 -5
  130. package/src/server/extensions/ask.ts +146 -0
  131. package/src/server/extensions/design/app.js +2 -19
  132. package/src/server/extensions/design/canvas.js +2 -10
  133. package/src/server/extensions/design/check.js +11 -38
  134. package/src/server/extensions/design/color.js +0 -7
  135. package/src/server/extensions/design/data.js +2 -10
  136. package/src/server/extensions/design/devices.js +2 -7
  137. package/src/server/extensions/design/docks.js +1 -10
  138. package/src/server/extensions/design/index.js +2 -12
  139. package/src/server/extensions/design/messages.js +0 -3
  140. package/src/server/extensions/design/parts.js +0 -1
  141. package/src/server/extensions/design/paths.js +1 -2
  142. package/src/server/extensions/design/picker.js +1 -3
  143. package/src/server/extensions/design/specimen.js +5 -7
  144. package/src/server/extensions/design/state.js +1 -7
  145. package/src/server/extensions/design/style.css +1 -23
  146. package/src/server/extensions/design/system-actions.js +4 -24
  147. package/src/server/extensions/design/system-api.ts +1 -9
  148. package/src/server/extensions/design/system-data.js +2 -21
  149. package/src/server/extensions/design/system-preview.js +0 -5
  150. package/src/server/extensions/design/system-routes.ts +56 -80
  151. package/src/server/extensions/design/system-sections.js +4 -63
  152. package/src/server/extensions/design/system-ui.js +2 -8
  153. package/src/server/extensions/design/system-view.js +6 -51
  154. package/src/server/extensions/design/system-widgets.js +2 -37
  155. package/src/server/extensions/design/system.css +13 -86
  156. package/src/server/extensions/design/system.js +16 -191
  157. package/src/server/extensions/design/unsaved.js +1 -7
  158. package/src/server/extensions/design/workspace.js +2 -7
  159. package/src/server/extensions/design.ts +2 -8
  160. package/src/server/extensions/gallery.ts +0 -1
  161. package/src/server/extensions/plan.ts +1 -0
  162. package/src/server/extensions/subagents.ts +3 -1
  163. package/src/server/extensions/updates/index.js +0 -2
  164. package/src/server/extensions/updates.ts +1 -3
  165. package/src/server/gallery/reach.ts +62 -54
  166. package/src/server/gallery.ts +0 -13
  167. package/src/server/host.ts +20 -1
  168. package/src/server/http/artifact-inspect.ts +12 -24
  169. package/src/server/pip.ts +1 -11
  170. package/src/server/reload.ts +3 -0
  171. package/src/server/updates.ts +7 -46
  172. package/src/server/versions.ts +2 -13
  173. package/types/pocket.d.ts +46 -1
  174. package/web/artifact-bridge.js +1 -3
  175. package/web/calls.js +20 -0
  176. package/web/composer.js +10 -4
  177. package/web/peeks.js +6 -1
  178. package/web/quote-reply.js +0 -4
  179. package/web/quote-text.js +1 -7
  180. package/web/seen.js +1 -6
  181. package/web/sessions.js +22 -65
  182. package/web/sheets/appearance.js +1 -1
  183. package/web/sheets/extensions.js +1 -3
  184. package/web/sheets/file.js +1 -2
  185. package/web/sheets/gallery.js +7 -57
  186. package/web/sheets/people.js +0 -1
  187. package/web/sheets/session.js +3 -24
  188. package/web/sheets.js +0 -1
  189. package/web/store.js +1 -9
  190. package/web/style.css +160 -36
  191. package/web/theme-surface.js +4 -0
  192. package/web/theme.js +0 -1
  193. package/web/transcript.js +125 -28
  194. package/docs/design/ds-notes-b.md +0 -61
  195. package/docs/design/ds-notes-g.md +0 -170
  196. package/docs/design/ds-notes-t.md +0 -303
  197. package/docs/design/ds-notes-u.md +0 -220
  198. package/docs/design/ds-notes-v.md +0 -186
  199. package/docs/design/ds-rounds.md +0 -160
  200. package/docs/design/ds-u-bridge.patch +0 -732
@@ -1,6 +1,6 @@
1
1
  # Design systems in Design mode (hill climb)
2
2
 
3
- Status: in progress, on `feat/design-system` (off 0.27.0-beta.1). This page is the plan, the contracts between the streams, and the rubric that scores each round. Streams write what they built, and what differs from this page, in `docs/design/ds-notes-<stream>.md`.
3
+ Status: shipped in 0.27.0. This page was the plan, the contracts between the streams, and the rubric that scored each round. What each feature does now is in [features.md](../features.md) and where its code is in [map.md](../map.md).
4
4
 
5
5
  ## Goal
6
6
 
@@ -162,4 +162,4 @@ A panel of two independent judges (different models) scores 0–10 per line with
162
162
 
163
163
  ## Process
164
164
 
165
- Round 0: this page, `system-types.ts`, worktrees. Round 1: the five streams build in parallel. Then the integrator merges into `feat/design-system`, runs the bench, and asks the judges. Each next round takes the lowest-scoring lines and fixes them, smallest change first, and keeps a change only when the score goes up (or a line rises and none falls). Stop when every line is at 9 or more, or two rounds bring no rise. The integrator records each round's scores in `docs/design/ds-rounds.md`.
165
+ Round 0: this page, `system-types.ts`, worktrees. Round 1: the five streams build in parallel. Then the integrator merges into `feat/design-system`, runs the bench, and asks the judges. Each next round takes the lowest-scoring lines and fixes them, smallest change first, and keeps a change only when the score goes up (or a line rises and none falls). Stop when every line is at 9 or more, or two rounds bring no rise.
@@ -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
@@ -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.