pi-pocket 0.27.0-beta.5 → 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 (201) 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 +42 -28
  6. package/docs/features.md +3 -2
  7. package/docs/map.md +101 -90
  8. package/docs/releases.md +6 -7
  9. package/package.json +3 -3
  10. package/src/server/alerts.ts +6 -1
  11. package/src/server/app.ts +84 -10
  12. package/src/server/commands.ts +3 -18
  13. package/src/server/design/check-cli.ts +0 -17
  14. package/src/server/design/color.ts +35 -74
  15. package/src/server/design/components.ts +3 -22
  16. package/src/server/design/docsite-assets.ts +2 -10
  17. package/src/server/design/docsite-color-section.ts +7 -23
  18. package/src/server/design/docsite-color.ts +59 -95
  19. package/src/server/design/docsite-components.ts +2 -13
  20. package/src/server/design/docsite-core.ts +18 -54
  21. package/src/server/design/docsite-css-base.ts +0 -2
  22. package/src/server/design/docsite-css-content.ts +1 -4
  23. package/src/server/design/docsite-css-phone.ts +1 -6
  24. package/src/server/design/docsite-css-reference.ts +1 -12
  25. package/src/server/design/docsite-css-specimens.ts +1 -3
  26. package/src/server/design/docsite-js-code.ts +1 -7
  27. package/src/server/design/docsite-js-core.ts +0 -3
  28. package/src/server/design/docsite-js-demos.ts +1 -3
  29. package/src/server/design/docsite-js-links.ts +1 -4
  30. package/src/server/design/docsite-js-nav.ts +1 -6
  31. package/src/server/design/docsite-js-stages.ts +1 -4
  32. package/src/server/design/docsite-js-table.ts +1 -4
  33. package/src/server/design/docsite-markdown.ts +3 -13
  34. package/src/server/design/docsite-motion.ts +1 -1
  35. package/src/server/design/docsite-reference.ts +2 -22
  36. package/src/server/design/docsite-sanitize.ts +7 -22
  37. package/src/server/design/docsite-shadows.ts +0 -7
  38. package/src/server/design/docsite-space.ts +0 -6
  39. package/src/server/design/docsite-type.ts +1 -6
  40. package/src/server/design/docsite.ts +3 -28
  41. package/src/server/design/export.ts +3 -7
  42. package/src/server/design/fix.ts +5 -42
  43. package/src/server/design/guide.ts +4 -30
  44. package/src/server/design/index.ts +9 -12
  45. package/src/server/design/lint-analyze-contrast.ts +153 -0
  46. package/src/server/design/lint-analyze-page.ts +326 -0
  47. package/src/server/design/lint-analyze-system.ts +318 -0
  48. package/src/server/design/lint-analyze-util.ts +60 -0
  49. package/src/server/design/lint-color.ts +26 -58
  50. package/src/server/design/lint-page-checks.ts +2 -13
  51. package/src/server/design/lint-page-elements.ts +1 -12
  52. package/src/server/design/lint-page-focus.ts +1 -5
  53. package/src/server/design/lint-page-literals.ts +2 -11
  54. package/src/server/design/lint-page-setup.ts +2 -8
  55. package/src/server/design/lint-page-states.ts +2 -9
  56. package/src/server/design/lint-page-values.ts +2 -17
  57. package/src/server/design/lint-page.ts +3 -21
  58. package/src/server/design/lint-suggest.ts +9 -53
  59. package/src/server/design/lint.ts +86 -739
  60. package/src/server/design/render.ts +1 -31
  61. package/src/server/design/scan-braces.ts +2 -8
  62. package/src/server/design/scan-categorize.ts +2 -8
  63. package/src/server/design/scan-channels.ts +7 -18
  64. package/src/server/design/scan-color-base.ts +3 -21
  65. package/src/server/design/scan-color-names.ts +1 -7
  66. package/src/server/design/scan-color-palette.ts +1 -7
  67. package/src/server/design/scan-color-roles.ts +3 -16
  68. package/src/server/design/scan-colors.ts +1 -8
  69. package/src/server/design/scan-facts-antd.ts +0 -14
  70. package/src/server/design/scan-facts-files.ts +0 -13
  71. package/src/server/design/scan-facts-lists.ts +6 -42
  72. package/src/server/design/scan-facts-sass.ts +0 -8
  73. package/src/server/design/scan-facts-theme.ts +3 -26
  74. package/src/server/design/scan-facts-use.ts +1 -21
  75. package/src/server/design/scan-facts-wordpress.ts +1 -16
  76. package/src/server/design/scan-facts.ts +1 -27
  77. package/src/server/design/scan-files.ts +41 -26
  78. package/src/server/design/scan-import-convert.ts +1 -14
  79. package/src/server/design/scan-import-eval.ts +24 -37
  80. package/src/server/design/scan-import-material.ts +4 -58
  81. package/src/server/design/scan-import-sd-config.ts +2 -34
  82. package/src/server/design/scan-import-sd.ts +95 -68
  83. package/src/server/design/scan-import-studio.ts +0 -22
  84. package/src/server/design/scan-import.ts +1 -36
  85. package/src/server/design/scan-infer.ts +2 -21
  86. package/src/server/design/scan-js-eval.ts +17 -49
  87. package/src/server/design/scan-palette.ts +0 -14
  88. package/src/server/design/scan-parse.ts +25 -101
  89. package/src/server/design/scan-prepare.ts +1 -24
  90. package/src/server/design/scan-render-pages.ts +3 -26
  91. package/src/server/design/scan-render-probe.ts +2 -20
  92. package/src/server/design/scan-render.ts +8 -38
  93. package/src/server/design/scan-review.ts +0 -7
  94. package/src/server/design/scan-roles.ts +0 -9
  95. package/src/server/design/scan-sass-colors.ts +0 -11
  96. package/src/server/design/scan-sass-eval.ts +4 -45
  97. package/src/server/design/scan-sass-expr.ts +0 -33
  98. package/src/server/design/scan-sass-modules.ts +3 -43
  99. package/src/server/design/scan-sass-run.ts +1 -35
  100. package/src/server/design/scan-sass-stmt.ts +1 -15
  101. package/src/server/design/scan-sass-values.ts +5 -38
  102. package/src/server/design/scan-scales.ts +6 -51
  103. package/src/server/design/scan-tailwind.ts +1 -9
  104. package/src/server/design/scan-theme-shapes.ts +13 -33
  105. package/src/server/design/scan-tree.ts +9 -16
  106. package/src/server/design/scan-util.ts +0 -7
  107. package/src/server/design/scan-variables.ts +39 -30
  108. package/src/server/design/scan-worker.ts +7 -0
  109. package/src/server/design/scan.ts +67 -85
  110. package/src/server/design/system-schema.ts +3 -20
  111. package/src/server/design/system-types.ts +6 -102
  112. package/src/server/design/system.ts +4 -23
  113. package/src/server/design/tokens-base.ts +49 -27
  114. package/src/server/design/tokens-compile.ts +5 -30
  115. package/src/server/design/tokens-dtcg.ts +5 -46
  116. package/src/server/design/tokens-io.ts +36 -38
  117. package/src/server/design/tokens-model-checks.ts +260 -0
  118. package/src/server/design/tokens-model-defs.ts +299 -0
  119. package/src/server/design/tokens-model-report.ts +144 -0
  120. package/src/server/design/tokens-model-resolve.ts +198 -0
  121. package/src/server/design/tokens-model.ts +188 -904
  122. package/src/server/design/tokens-names.ts +0 -8
  123. package/src/server/design/tokens-ramps.ts +2 -11
  124. package/src/server/design/tokens-summary.ts +2 -24
  125. package/src/server/design/tokens-tailwind.ts +4 -37
  126. package/src/server/design/tokens-values.ts +9 -17
  127. package/src/server/design/tokens.ts +16 -31
  128. package/src/server/docs.ts +0 -4
  129. package/src/server/extension-points.ts +56 -10
  130. package/src/server/extensions/artifacts.ts +2 -5
  131. package/src/server/extensions/ask.ts +146 -0
  132. package/src/server/extensions/design/app.js +2 -19
  133. package/src/server/extensions/design/canvas.js +2 -10
  134. package/src/server/extensions/design/check.js +11 -38
  135. package/src/server/extensions/design/color.js +0 -7
  136. package/src/server/extensions/design/data.js +2 -10
  137. package/src/server/extensions/design/devices.js +2 -7
  138. package/src/server/extensions/design/docks.js +1 -10
  139. package/src/server/extensions/design/index.js +2 -12
  140. package/src/server/extensions/design/messages.js +0 -3
  141. package/src/server/extensions/design/parts.js +0 -1
  142. package/src/server/extensions/design/paths.js +1 -2
  143. package/src/server/extensions/design/picker.js +1 -3
  144. package/src/server/extensions/design/specimen.js +5 -7
  145. package/src/server/extensions/design/state.js +1 -7
  146. package/src/server/extensions/design/style.css +1 -23
  147. package/src/server/extensions/design/system-actions.js +4 -24
  148. package/src/server/extensions/design/system-api.ts +1 -9
  149. package/src/server/extensions/design/system-data.js +2 -21
  150. package/src/server/extensions/design/system-preview.js +0 -5
  151. package/src/server/extensions/design/system-routes.ts +56 -80
  152. package/src/server/extensions/design/system-sections.js +4 -63
  153. package/src/server/extensions/design/system-ui.js +2 -8
  154. package/src/server/extensions/design/system-view.js +6 -51
  155. package/src/server/extensions/design/system-widgets.js +2 -37
  156. package/src/server/extensions/design/system.css +13 -86
  157. package/src/server/extensions/design/system.js +16 -191
  158. package/src/server/extensions/design/unsaved.js +1 -7
  159. package/src/server/extensions/design/workspace.js +2 -7
  160. package/src/server/extensions/design.ts +2 -8
  161. package/src/server/extensions/gallery.ts +0 -1
  162. package/src/server/extensions/plan.ts +1 -0
  163. package/src/server/extensions/subagents.ts +3 -1
  164. package/src/server/extensions/updates/index.js +0 -2
  165. package/src/server/extensions/updates.ts +1 -3
  166. package/src/server/gallery/reach.ts +62 -54
  167. package/src/server/gallery.ts +0 -13
  168. package/src/server/host.ts +20 -1
  169. package/src/server/http/artifact-inspect.ts +12 -24
  170. package/src/server/pip.ts +1 -11
  171. package/src/server/reload.ts +3 -0
  172. package/src/server/updates.ts +7 -46
  173. package/src/server/versions.ts +2 -13
  174. package/types/pocket.d.ts +46 -1
  175. package/web/artifact-bridge.js +1 -3
  176. package/web/calls.js +20 -0
  177. package/web/composer.js +10 -4
  178. package/web/peeks.js +7 -2
  179. package/web/quote-reply.js +0 -4
  180. package/web/quote-text.js +1 -7
  181. package/web/seen.js +32 -0
  182. package/web/sessions.js +779 -72
  183. package/web/sheets/appearance.js +1 -1
  184. package/web/sheets/extensions.js +1 -3
  185. package/web/sheets/file.js +1 -2
  186. package/web/sheets/gallery.js +7 -57
  187. package/web/sheets/people.js +0 -1
  188. package/web/sheets/session.js +3 -24
  189. package/web/sheets.js +0 -1
  190. package/web/store.js +26 -9
  191. package/web/style.css +502 -24
  192. package/web/theme-surface.js +23 -0
  193. package/web/theme.js +1 -2
  194. package/web/transcript.js +125 -28
  195. package/docs/design/ds-notes-b.md +0 -61
  196. package/docs/design/ds-notes-g.md +0 -170
  197. package/docs/design/ds-notes-t.md +0 -303
  198. package/docs/design/ds-notes-u.md +0 -220
  199. package/docs/design/ds-notes-v.md +0 -186
  200. package/docs/design/ds-rounds.md +0 -160
  201. 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
 
@@ -97,33 +97,41 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
97
97
 
98
98
  ### The frame
99
99
 
100
- | Part | What |
101
- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
- | `boot` | The screen while the app starts |
104
- | `brand-mark` | The π: on the rail, and on the boot screen |
105
- | `sidebar` | The rail and the session list, on wide screens |
106
- | `drawer` | The rail and the session list sliding in, on narrow screens |
107
- | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
- | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
109
- | `session-search` | The search field |
110
- | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
111
- | `session-tabs` | Recent, Folders, Archived |
112
- | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
113
- | `session-group`, `session-group-head` | A group of rows (a day, a folder), and its head, which folds it |
114
- | `session-group-name`, `session-group-count` | The head's name, and its count |
115
- | `session-row` | One session's line |
116
- | `session-button` | The row's button: its square, title, and what is on its right |
117
- | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
118
- | `session-branches` | The lines to a session that another one started |
119
- | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
120
- | `home` | The home screen on wide screens |
121
- | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
122
- | `home-actions` | Its buttons |
123
- | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
124
- | `home-list` | The session list as a phone's home screen |
125
- | `pane` | The conversation's window (or the subagents board, or an extension's page) |
126
- | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
100
+ | Part | What |
101
+ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
+ | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
+ | `boot` | The screen while the app starts |
104
+ | `brand-mark` | The π: on the rail, and on the boot screen |
105
+ | `sidebar` | The rail and the session list, on wide screens |
106
+ | `drawer` | The rail and the session list sliding in, on narrow screens |
107
+ | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
+ | `rail-needs` | The warning-colored count on the Sessions button: how many sessions need you (since 0.27.0) |
109
+ | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
110
+ | `session-search` | The search field |
111
+ | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
112
+ | `session-tabs` | Priority, Recent, Folders, and Archived (an icon) |
113
+ | `session-tab`, `session-tab-count` | One tab; and Priority's count of the sessions that need you (since 0.27.0) |
114
+ | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
115
+ | `session-group`, `session-group-head` | A group of rows (a day, a folder, a Priority group), and its head, which folds it; Priority's Needs you does not fold, and its head is not a button |
116
+ | `session-group-bar`, `session-group-action` | In Priority, a group's head with its button beside it (Dismiss N failed, Mark all read), and that button (since 0.27.0) |
117
+ | `session-clear`, `session-more` | In Priority, the line "Nothing needs you", and Show N more under Needs you (since 0.27.0) |
118
+ | `session-group-name`, `session-group-count` | The head's name, and its count |
119
+ | `session-row` | One session's line |
120
+ | `session-button` | The row's button: its square, title, and what is on its right |
121
+ | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
122
+ | `session-limit` | In Priority's Working group, the clock pill with the time a usage limit clears (since 0.27.0) |
123
+ | `session-quick`, `session-review`, `session-dismiss`, `session-read` | In Priority, the button at the right of a row: Review (a call waits), Dismiss (a failure), and Mark read on hover (since 0.27.0) |
124
+ | `session-ask`, `session-ask-command`, `session-ask-reason` | The call open in a row of Needs you, its command, and why the guard asks (since 0.27.0) |
125
+ | `session-deny`, `session-decline`, `session-allow`, `session-ask-open` | That call's buttons (since 0.27.0) |
126
+ | `session-branches` | The lines to a session that another one started |
127
+ | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
128
+ | `home` | The home screen on wide screens |
129
+ | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
130
+ | `home-actions` | Its buttons |
131
+ | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
132
+ | `home-list` | The session list as a phone's home screen |
133
+ | `pane` | The conversation's window (or the subagents board, or an extension's page) |
134
+ | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
127
135
 
128
136
  ### The conversation
129
137
 
@@ -135,6 +143,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
135
143
  | `prompt-head`, `author-mark`, `prompt-author` | Its head: who sent it and when; their initials; their name |
136
144
  | `prompt-text` | What it says (its skill chip, words, and files) |
137
145
  | `reply` | Pi's answer |
146
+ | `reply-quote` | The passage a reply quotes, at the top of a message (since 0.27.0) |
138
147
  | `reply-actions` | The row under an answer: react, discuss, pin, copy |
139
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 |
140
149
  | `timeline` | The open group's steps, on a rule |
@@ -156,6 +165,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
156
165
  | `dock` | What sits above the message box: the queue and the bars |
157
166
  | `subagents-bar` | The subagents' bar |
158
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) |
159
169
  | `composer-tools` | The row of buttons in it |
160
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) |
161
171
  | `plan-chip`, `mode-switch`, `stop-button` | Plan, Steer and Queue, and Stop, each also a `composer-button` |
@@ -172,6 +182,8 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
172
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) |
173
183
  | `sheet-head`, `sheet-body` | Its title bar, and what it holds |
174
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) |
175
187
  | `launcher` | The launcher (Ctrl/⌘+K) |
176
188
  | `launcher-input`, `launcher-filters` | Its search field, and the search types under it |
177
189
  | `launcher-group`, `launcher-row` | A group's heading, and each result |
@@ -200,7 +212,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
200
212
  | `session-row` | `data-state` | `working`, `waiting` (for you), `limited` (waiting for a provider's limit to clear, since 0.21.0), `failed`, `done` (since you looked), `idle` |
201
213
  | `peek-tile` | `data-state` | The same as `session-row`'s, but without `failed` |
202
214
  | `session-button` | `aria-current` | `page` on the open session's |
203
- | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open |
215
+ | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open; none on Priority's Needs you head, which does not fold |
204
216
  | `activity` | `data-state` | `open` while open |
205
217
  | `tool-call` | `data-state` | `running`, `ok`, `failed`, `waiting` (for approval), `denied`, `stopped` |
206
218
  | `prompt` | `data-from` | `me`, `person` (someone else), `linked` (a linked session), `other` (Pi's schedule, the main agent, a watch or a webhook) |
@@ -237,6 +249,8 @@ A part's `::before` and `::after` are a theme's to use, except these, which the
237
249
  | ---------------------------------------------- | --------------------------------------------------------------------------- |
238
250
  | `session-group-head` | `::after`: its tap area on touch screens |
239
251
  | `session-mark` | `::before`: the square that steps while the session works |
252
+ | `session-review`, `session-dismiss` | `::before`: their tap areas (since 0.27.0) |
253
+ | `session-group-action` | `::before`: its tap area on touch screens (since 0.27.0) |
240
254
  | `timeline` | `::before`: the rule |
241
255
  | `composer-button`, `model-chip`, `send-button` | `::before`: their tap areas on phones; the mic's `::after` while it listens |
242
256
  | `notice` | `::after`: the bar that counts down |
package/docs/features.md CHANGED
@@ -7,7 +7,7 @@ The full tour. For setup, see the [README](../README.md).
7
7
  - **Omarchy colors.** All of Omarchy's themes, from Tokyo Night and Gruvbox to Rosé Pine and the light ones, drawn from each theme's own `colors.toml`, in soft tiles: rounded windows and controls on 1px hairlines, soft shadows only on what floats, Geist for words and JetBrains Mono for code, paths, and numbers, with JetBrains Mono's own italic and the Nerd Fonts icons that prompts and tools print (bundled in `web/fonts/`, with Inter, Fira Code, IBM Plex Mono, and Iosevka for themes to name; `web/fonts/SOURCES.md` says where each came from); light themes too. Menu → **Appearance** (or the **Theme** tile, the launcher, or `/theme gruvbox`) picks one under **Colors**, as well as a theme folder's `colors.toml` (any Omarchy theme folder dropped into `themes/` shows there); the mini-desktop cards in Appearance preview a theme on hover or keyboard focus, and leaving without choosing restores the saved theme. The new look grows as a circle from where you tapped. **Desktop** follows the Omarchy theme of the machine Pi Pocket runs on: change your desktop's theme and the app follows within seconds, optionally with your wallpaper in the gaps.
8
8
  - **Sheets and controls.** Sheets have a 56px title bar on wide screens, a back chevron when opened from another sheet, grouped inset lists, round toggles, and segmented settings. On phones they keep their bottom-sheet grip and drag-to-close gesture. Text sheets have Cancel and the main action together at the bottom; all existing keyboard and back flows stay available. Buttons, fields, and search share the same rounded controls across the app.
9
9
  - **Tiled windows and motion.** On wide screens the sidebar and the session are Hyprland windows, softened: 8px gaps, rounded corners on a hairline, and a soft accent ring on the one under the mouse. Motion uses Omarchy's Hyprland curves: windows pop in at 87%, sheets and popovers rise a little as they fade in, and leave quickly, new messages slide in, and notices count down until they go. While Pi works, the conversation shows what it does; elsewhere a working session's square steps around and a small dot pulses (both hold still with reduced motion). Appearance can turn tiling off (no gaps, square corners, no ring), reduce motion (or follow the system's setting), choose Fluid motion (sheets, menus, the launcher, and notices arrive on a spring and leave quickly, over a frosted scrim; what they hold, and a tool group's first steps, follow a step apart; a message sent lifts off from the message box; each new paragraph of Pi's answer fades in, and its caret breathes; a pressed button springs back; and folding the sidebar morphs the windows into place; Width and tiling change at once, as they are set from a sheet or the launcher, which morphs skip; Auto never picks it), change the conversation's text size (13, 15, 17, or 20, or any size from 10 to 32 px typed in, in half pixels), set the width (Comfortable, which grows with a wide window, Wide, or Full: how much of the window the conversation and the message box take, per browser; phones stay as they are; a reply's code block with long lines grows past the column, centered on it, where plain text and Markdown wrap in the column, and a wide table grows toward the window's edge), set the density (Comfortable, Compact, or Tight: less room between turns, inside message cards and activity groups, between the conversation's lines, in the session list's rows, around the message box and the status line, in sheets and their lists, and in the top bar, while font sizes stay and rows on a touch screen stay a thumb tall), show Pi's thinking while it works, and show the reply speed under the message box.
10
- - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Recent, Folders, and Archived in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
10
+ - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
11
11
  - **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
12
12
  - **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
13
13
  - **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
@@ -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.