@narumitw/pi-starship 0.60.1 → 0.63.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +67 -9
  2. package/dist/chunks/chunk-63R6R5DH.ts +679 -0
  3. package/dist/chunks/chunk-63R6R5DH.ts.map +7 -0
  4. package/dist/chunks/{chunk-KZZKGGFW.ts → chunk-A65IOGL6.ts} +858 -1007
  5. package/dist/chunks/chunk-A65IOGL6.ts.map +7 -0
  6. package/dist/chunks/chunk-IYDZ3R2T.ts +69 -0
  7. package/dist/chunks/chunk-IYDZ3R2T.ts.map +7 -0
  8. package/dist/chunks/chunk-KP33I6BR.ts +579 -0
  9. package/dist/chunks/chunk-KP33I6BR.ts.map +7 -0
  10. package/dist/chunks/{chunk-PD457PX5.ts → chunk-S2KBLHE2.ts} +75 -10
  11. package/dist/chunks/chunk-S2KBLHE2.ts.map +7 -0
  12. package/dist/chunks/chunk-XQUIQO2G.ts +20 -0
  13. package/dist/chunks/chunk-XQUIQO2G.ts.map +7 -0
  14. package/dist/chunks/{chunk-ADX4CY27.ts → chunk-XTLQ4WUL.ts} +1 -1
  15. package/dist/chunks/chunk-XTLQ4WUL.ts.map +7 -0
  16. package/dist/chunks/chunk-Y24TJYG6.ts +1586 -0
  17. package/dist/chunks/chunk-Y24TJYG6.ts.map +7 -0
  18. package/dist/chunks/{cloud-EPAEV4ZB.ts → cloud-J2ZOE3HE.ts} +6 -2
  19. package/dist/chunks/cloud-J2ZOE3HE.ts.map +7 -0
  20. package/dist/chunks/command-configuration-menu-YOLN2SPR.ts +147 -0
  21. package/dist/chunks/command-configuration-menu-YOLN2SPR.ts.map +7 -0
  22. package/dist/chunks/command-settings-chat-5AHP3JGV.ts +1124 -0
  23. package/dist/chunks/command-settings-chat-5AHP3JGV.ts.map +7 -0
  24. package/dist/chunks/commands-IOG2PL67.ts +1026 -0
  25. package/dist/chunks/commands-IOG2PL67.ts.map +7 -0
  26. package/dist/chunks/{deployment-7J54EHNR.ts → deployment-NOJ2KCLI.ts} +85 -5
  27. package/dist/chunks/deployment-NOJ2KCLI.ts.map +7 -0
  28. package/dist/chunks/{development-IWJAAAEV.ts → development-T3XXVVDP.ts} +67 -15
  29. package/dist/chunks/development-T3XXVVDP.ts.map +7 -0
  30. package/dist/chunks/directory-OX6BWJZA.ts +31 -0
  31. package/dist/chunks/directory-OX6BWJZA.ts.map +7 -0
  32. package/dist/chunks/{execution-P4WZALW2.ts → execution-R2OHIP2L.ts} +8 -4
  33. package/dist/chunks/execution-R2OHIP2L.ts.map +7 -0
  34. package/dist/chunks/jujutsu-XLDYKSX2.ts +174 -0
  35. package/dist/chunks/jujutsu-XLDYKSX2.ts.map +7 -0
  36. package/dist/chunks/languages-CBQNNYXM.ts +262 -0
  37. package/dist/chunks/languages-CBQNNYXM.ts.map +7 -0
  38. package/dist/chunks/{package-H24VJEX3.ts → package-7KVAK3TC.ts} +6 -2
  39. package/dist/chunks/package-7KVAK3TC.ts.map +7 -0
  40. package/dist/chunks/system-574MHB4R.ts +165 -0
  41. package/dist/chunks/system-574MHB4R.ts.map +7 -0
  42. package/dist/index.ts +670 -206
  43. package/dist/index.ts.map +4 -4
  44. package/package.json +5 -1
  45. package/skills/configure-pi-starship/SKILL.md +17 -1
  46. package/skills/configure-pi-starship/references/configuration.md +119 -32
  47. package/skills/configure-pi-starship/references/module-catalog.md +278 -25
  48. package/skills/configure-pi-starship/references/modules.md +213 -36
  49. package/skills/configure-pi-starship/references/runtime-and-security.md +88 -28
  50. package/src/command-commit.ts +41 -7
  51. package/src/command-configuration-menu.ts +155 -0
  52. package/src/command-configuration.ts +15 -94
  53. package/src/command-preview.ts +3 -3
  54. package/src/command-settings-chat.ts +168 -0
  55. package/src/commands.ts +76 -124
  56. package/src/config/module-options.ts +112 -0
  57. package/src/config.ts +23 -59
  58. package/src/effective-config.ts +5 -4
  59. package/src/format/bounded-regex.ts +66 -0
  60. package/src/format/version.ts +24 -0
  61. package/src/modules/catalog.ts +10 -0
  62. package/src/modules/cloud.ts +1 -0
  63. package/src/modules/deployment.ts +8 -0
  64. package/src/modules/development.ts +20 -2
  65. package/src/modules/directory.ts +171 -51
  66. package/src/modules/execution.ts +2 -0
  67. package/src/modules/git/branch.ts +19 -4
  68. package/src/modules/git/commit.ts +9 -2
  69. package/src/modules/git/metrics.ts +9 -4
  70. package/src/modules/git/runtime.ts +122 -33
  71. package/src/modules/git/state.ts +23 -2
  72. package/src/modules/git/status-templates.ts +58 -0
  73. package/src/modules/git/status.ts +96 -30
  74. package/src/modules/jujutsu.ts +225 -0
  75. package/src/modules/languages.ts +26 -2
  76. package/src/modules/package.ts +1 -0
  77. package/src/modules/render.ts +42 -16
  78. package/src/modules/system.ts +54 -0
  79. package/src/modules/time-format.ts +188 -0
  80. package/src/modules/time.ts +11 -5
  81. package/src/modules/types.ts +42 -4
  82. package/src/pi-starship.ts +198 -88
  83. package/src/profile-store.ts +5 -0
  84. package/src/runtime/cloud.ts +3 -0
  85. package/src/runtime/command.ts +1 -1
  86. package/src/runtime/deployment.ts +120 -4
  87. package/src/runtime/development.ts +86 -13
  88. package/src/runtime/directory.ts +33 -0
  89. package/src/runtime/execution.ts +12 -2
  90. package/src/runtime/helpers.ts +57 -8
  91. package/src/runtime/jujutsu.ts +225 -0
  92. package/src/runtime/languages.ts +106 -19
  93. package/src/runtime/package.ts +3 -0
  94. package/src/runtime/system.ts +202 -0
  95. package/src/runtime/types.ts +3 -0
  96. package/src/runtime/version-requirements.ts +30 -0
  97. package/src/runtime/workspace.ts +12 -1
  98. package/src/settings-agent.ts +80 -0
  99. package/src/settings-chat-transcript.ts +192 -0
  100. package/src/settings-chat-ui.ts +526 -0
  101. package/src/settings-draft.ts +260 -0
  102. package/src/settings-snapshots.ts +41 -0
  103. package/dist/chunks/chunk-ADX4CY27.ts.map +0 -7
  104. package/dist/chunks/chunk-KZZKGGFW.ts.map +0 -7
  105. package/dist/chunks/chunk-PD457PX5.ts.map +0 -7
  106. package/dist/chunks/cloud-EPAEV4ZB.ts.map +0 -7
  107. package/dist/chunks/commands-C2VJ6ZBN.ts +0 -3374
  108. package/dist/chunks/commands-C2VJ6ZBN.ts.map +0 -7
  109. package/dist/chunks/deployment-7J54EHNR.ts.map +0 -7
  110. package/dist/chunks/development-IWJAAAEV.ts.map +0 -7
  111. package/dist/chunks/execution-P4WZALW2.ts.map +0 -7
  112. package/dist/chunks/languages-JO6R2PHL.ts +0 -168
  113. package/dist/chunks/languages-JO6R2PHL.ts.map +0 -7
  114. package/dist/chunks/package-H24VJEX3.ts.map +0 -7
  115. package/src/command-inspector.ts +0 -41
@@ -9,6 +9,20 @@ disable-model-invocation: true
9
9
 
10
10
  Answer pi-starship configuration questions or make the requested `pi-starship.toml` change.
11
11
 
12
+ ## Hosted preview-only chat
13
+
14
+ When the host explicitly supplies an owned draft path and identifies this as the hosted preview-only workflow, use this section instead of the standalone path-resolution and publication steps below.
15
+ Read and edit only that draft for configuration changes; never write or edit the active settings file.
16
+ The host provides `read`, `write`, and `edit`, validates each completed mutation, and updates the footer preview without `/reload`.
17
+ Read the relevant bundled references using their paths relative to this skill directory.
18
+ Use `read` before `edit`, preserve comments and unknown fields, and repair errors reported by the host.
19
+ A rejected preview can leave invalid text in the draft; fix that text rather than assuming the write was rolled back.
20
+ Do not run or request the resolver, validator, backup, or apply scripts in this workflow.
21
+ Do not request shell access, publish settings, or tell the user that settings were saved.
22
+ Only the user can choose the host's reviewed Save draft as profile action and enter its name.
23
+ The host then asks separately whether to apply the saved profile; declining keeps the profile without changing active settings.
24
+ Closing or discarding before that user save does not save the preview.
25
+
12
26
  ## Choose the task path
13
27
 
14
28
  For a configuration question, load only the smallest relevant reference and answer with the exact supported names, values, defaults, and behavior.
@@ -67,7 +81,9 @@ Do not install another Pi copy, modify `node_modules`, hard-code a Bun global di
67
81
 
68
82
  Read the existing document before editing it.
69
83
 
70
- Treat a missing document as built-in defaults, and create it only when the requested change requires a persisted configuration.
84
+ Treat a missing document as Pi's native footer, and create it only when the requested change requires a persisted Starship configuration.
85
+ Use the built-in Starship example as an editing seed, not as a document equivalent to Pi's native footer.
86
+ The menu action **Restore built-in…** archives the exact active bytes in History and removes the settings document; a saved built-in Starship example remains eligible for Restore.
71
87
 
72
88
  Do not redirect this workflow to `starship.toml`, `pi-statusline.json`, project-local overrides, or extension source files.
73
89
 
@@ -10,8 +10,9 @@ The only configuration source is:
10
10
  <getAgentDir()>/pi-starship.toml
11
11
  ```
12
12
 
13
- When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
14
- The built-in root is the explicit sequence `$brand$model$thinking$directory` `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query.
13
+ When this file is absent, the extension uses Pi's native footer without creating the file or its parent directory.
14
+ The built-in Starship example remains an editing seed; saving it enables a Starship footer, not Pi's native footer.
15
+ Its root is the explicit sequence `$brand$model$thinking$directory` `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query.
15
16
  The first successful settings save creates the file atomically.
16
17
  Existing malformed documents are never overwritten.
17
18
 
@@ -23,40 +24,60 @@ Open the interactive menu in TUI mode:
23
24
  /starship
24
25
  ```
25
26
 
26
- Choose **Customize footer** to edit the TOML.
27
+ Choose **Configure with agent** for edits and explanations.
28
+ The compatibility command `/starship settings` retains the raw TOML editor.
27
29
  Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
28
30
  Saving requires separate confirmation, then atomically updates the file and active footer.
29
31
  Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
30
32
  Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
31
33
 
32
- The bundled `configure-pi-starship` skill uses a separate external-edit workflow.
34
+ Choose **Configure with agent** for a separate, temporary configuration conversation with the bundled skill and `read`, `write`, and `edit` tools.
35
+ The agent can write only its private draft, not the active settings file; validated mutations update the preview without `/reload`, and invalid mutations retain the last valid preview.
36
+ Reads cover immutable disk and loaded-document snapshots, normalized active public TOML, source/path/health/diagnostics, module inspection, the private draft, and bundled skill/source documents; the draft is limited to 64 KiB.
37
+ These read-only documents are fixed at chat opening and do not change with draft previews or later runtime updates.
38
+ The disk baseline can differ from the loaded document after external edits; normalized TOML excludes comments, unknown fields, parser ASTs, and private selectors while preserving effective replacement order.
39
+ Module inspection includes states, current previews, reachability, variables, style-rule metadata, display rules, and reasons from existing runtime data without starting collectors.
40
+ When runtime inspection or loaded text is unavailable, report that limit instead of guessing.
41
+ The ordinary main-session skill has no live runtime access; direct active-state questions to this hosted chat.
42
+ The preview uses cached data without starting module commands or network requests.
43
+ During a response, normal submission queues steering for the next assistant turn; the configured app.message.followUp action queues work after natural completion and submits normally when idle.
44
+ The app.message.dequeue action restores pending messages to the editor; these message actions use Pi's native precedence, including explicit history bindings.
45
+ The configured cancel action stops a response and restores undelivered messages; when idle, it leaves the conversation open without opening a menu. Editor actions win cancel-key collisions, with Escape as a stop fallback unless assigned to an editor action.
46
+ Failed or aborted responses restore undelivered input without automatic restart.
47
+ Ctrl+C discards the flow, clears both queues, and restores the active footer unless its session was replaced.
48
+ When idle with a valid draft, Ctrl+S opens the Save draft as profile flow directly; its gray editor-border hint switches to F2 if Ctrl+S is reserved, or is omitted when both keys conflict.
49
+ Saving requires exact-draft review and a profile name; invalid or existing names are rejected without overwriting a profile.
50
+ After saving, the host asks whether to apply that profile through managed History and atomic replacement; declining keeps the profile without changing active settings.
51
+ Cancelling naming returns to the chat without saving; closing or session replacement removes the temporary draft, not any saved profile.
52
+ Application checks the initial disk snapshot, loaded revision, and saved profile identity, blocks detected concurrent changes, and warns before explicitly repairing an invalid original.
53
+ Chat content and settings read by the agent go to the selected model provider; the child uses the opening model/thinking selection with Pi authentication, has no shell tool, and does not persist its transcript or change the main conversation.
54
+ The fullscreen view uses Pi's native user/assistant/tool message components. Short gray status and control labels sit on the editor borders; the live preview ends at the terminal bottom, in the saved footer's position.
55
+ It shows recent output with expanded, read-only tool results; saving opens an exact-draft review.
56
+ Choose **Continue** to leave the save review; cancelling the review discards the flow without publishing.
57
+
58
+ Outside this hosted chat, the bundled `configure-pi-starship` skill uses a separate external-edit workflow.
33
59
  Before its apply script replaces an existing document, it preserves the inspected document under `<getAgentDir()>/pi-starship/pi-starship-YYYYMMDDHHmm.toml`; these backups use local time and remain after a successful apply.
34
60
  Backups are written and flushed under a private temporary name, atomically renamed to their final private file, and followed by flushes of the backup directory and its parent directory before publication continues; a recoverable failure removes the owned temporary file and preserves the active document.
35
61
  If configuration publication fails after that backup is durable, the failure reports its retained path; cleanup failures report both their operation and cause without hiding the primary failure.
36
62
  A missing document creates no backup, and a backup with the same minute name blocks publication when observed before rename; this check does not provide cross-process locking.
37
63
  The interactive `/starship` flows do not invoke this script. They preserve replaced documents in the separate recovery history described below; existing skill backups remain available read-only in History.
38
64
 
39
- The main menu also exposes **Profiles**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
40
- Explain footer uses the current immutable runtime snapshot to list each currently showing non-empty module once with its rendered value and description; it starts no new collection work.
41
- Modules opens a bounded searchable inspector for every registered module.
42
- Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
43
- Module detail shows the current preview when available, description, root reference and reachability, format variables, style fields, supported style-rule selectors, configured rule count, display rules, and the known reason for absent output.
44
- Both views are read-only and do not create or update the settings document.
45
-
46
- Configuration contains **Overview**, **Effective configuration**, **Settings document**, **Reload from disk**, **History**, **Share settings as Gist…**, and **Import settings from Gist…** on one nested level.
65
+ The main menu orders **Configure with agent**, **Presets**, **Profiles**, **Configuration**, **Restore built-in…**, and **Help**.
66
+ Configuration shows state, source, settings path, health, and all current warnings above **Reload from disk…**, **Share settings as Gist…**, **Import settings from Gist…**, and **History**.
67
+ Configured selection page-up/page-down actions scroll the summary without moving the selected action; selection and cancellation bindings take priority when bindings conflict.
68
+ The focused action remains visible at small terminal heights; enlarge an extremely short terminal to read the summary.
47
69
  Gist actions use `gh` authentication for github.com and transfer only `pi-starship.toml`, limited to 64 KiB; sharing includes comments and unknown fields and requires review and confirmation before creating an unlisted Gist.
48
70
  Unlisted Gists are readable by anyone with the link; remove sensitive data before sharing, and check GitHub before retrying a cancelled or failed upload because a remote Gist may already exist.
49
71
  Import accepts a Gist ID or URL, validates the complete document, requires raw TOML review, footer preview, and full-replacement confirmation, and preserves the previous document before applying; review untrusted settings for command execution and network access before accepting.
50
- Overview combines state, source, path, health, and bounded diagnostics.
51
- Effective configuration shows deterministic catalog-ordered public TOML from the normalized state currently in use; comments, unknown fields, parser ASTs, and private runtime selectors are excluded.
52
- Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
53
- A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
72
+ A missing file uses Pi's native footer, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
54
73
  Reload from disk reads only after the explicit action, validates and previews the current external state from the existing runtime snapshot, and asks for separate confirmation before changing the active session.
55
- A deleted document is a valid previewable transition to built-in defaults and creates no file.
74
+ A deleted document is a valid previewable transition to Pi's native footer and creates no file.
56
75
  An unchanged document is a no-op, while read or parse failure, cancellation, disposal, external changes after preview, session replacement, shutdown, or runtime apply failure preserves the prior effective footer and every file byte.
57
76
  Reload re-reads immediately after confirmation and rejects a different external snapshot; it does not claim cross-process locking or continuing synchronization with later edits.
58
- Restore is disabled when no settings document exists or the exact built-in document is already saved.
59
- For a custom or invalid document, Restore previews the result and warns that the complete document, including custom settings, unknown fields, and comments, will be replaced before asking for confirmation. The previous bytes are preserved first, including invalid content on an explicit recovery path.
77
+ **Restore built-in…** remains in the main menu and is disabled only when no settings document exists.
78
+ A saved built-in Starship example is not Pi's native footer and can be restored.
79
+ Restore previews Pi's native footer and asks for confirmation before archiving the exact document bytes in History and removing the active settings document, including custom settings, unknown fields, and comments.
80
+ Invalid content is preserved through the explicit recovery path.
60
81
 
61
82
  ### Named profiles
62
83
 
@@ -93,7 +114,7 @@ The native Pi editor has no public abort method; session cancellation removes th
93
114
  ### Recovery history
94
115
 
95
116
  Managed active-file replacements preserve the previous document in `<getAgentDir()>/pi-starship/history/<timestamp>-<random-id>.toml` before writing the replacement.
96
- Editor, preset, profile, restore, and Gist application use this policy.
117
+ Editor, configuration-chat save, preset, profile, restore, and Gist application use this policy.
97
118
  A missing file or a byte-identical no-op creates no recovery copy.
98
119
  Backup failure blocks replacement; runtime-application failure attempts guarded disk/runtime restoration and retains the backup.
99
120
  A recovery copy can therefore come from an unsuccessful application attempt; it is not proof that a candidate was applied.
@@ -237,12 +258,13 @@ styles = { "foo:*" = "bold green", "foo:error" = "bold red", fallback = "dimmed
237
258
 
238
259
  Every module table supports `format`, `symbol`, and `disabled`.
239
260
  Most modules also support one `style`.
240
- The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
261
+ The exceptions include Git/Jujutsu metrics (`added_style` and `deleted_style`), `jj_change` (prefix/suffix/offset styles), `username` (`style_user` and `style_root`), and threshold-selected `context`, `cost`, and `battery` `display` arrays.
262
+ Directory root/read-only styles and Node.js/Go requirement styles supplement their ordinary `style`; see [module behavior](modules.md).
241
263
  `thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
242
264
  Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
243
- Version formats replace `$raw`.
244
- Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
245
- A leading `!` is supported by language detection arrays and rejects a matching project.
265
+ [Version formats](#version-formats) support raw and numeric component variables.
266
+ Detection arrays inspect one bounded listing of the current directory; replacement and fallback rules are [module-specific](modules.md#reachability-and-collection-rules).
267
+ Language and Kubernetes file detectors support leading `!` rejection rules; [environment detectors](modules.md#environment-detection-and-messages) have separate presence rules.
246
268
  `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
247
269
  Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
248
270
  An empty configured icon suppresses only the icon.
@@ -283,11 +305,14 @@ The exact accepted style fields, display arrays, module-specific options, defaul
283
305
  A standard `style` field must be a valid style string.
284
306
  `thinking` accepts `style` plus `style_off`, `style_minimal`, `style_low`, `style_medium`, `style_high`, `style_xhigh`, and `style_max`.
285
307
  `provider`, `model`, and `thinking` additionally accept the ordered `style_rules` arrays described under [Content-selected styles](#content-selected-styles).
286
- `git_metrics` accepts `added_style` and `deleted_style` instead of `style`.
308
+ `git_metrics` and `jj_metrics` accept `added_style` and `deleted_style` instead of `style`.
309
+ `jj_change` accepts `prefix_style`, `suffix_style`, and `change_offset_style` instead of `style`.
310
+ `directory` additionally accepts `repo_root_style`, `before_repo_root_style`, and `read_only_style`.
311
+ `nodejs` and `golang` additionally accept `not_capable_style`; its exact default `"none"` disables requirement checks.
287
312
  `username` accepts `style_user` and `style_root` instead of `style`.
288
- `context` and `cost` accept `display` arrays instead of a direct `style` field.
313
+ `context`, `cost`, and `battery` accept `display` arrays instead of a direct `style` field.
289
314
 
290
- `[[context.display]]` and `[[cost.display]]` entries require these typed fields:
315
+ `[[context.display]]`, `[[cost.display]]`, and `[[battery.display]]` entries require these typed fields:
291
316
 
292
317
  ```toml
293
318
  threshold = 60 # finite number
@@ -313,18 +338,76 @@ Module-specific options use these validation rules:
313
338
  | string enum | An exact case-sensitive listed string. |
314
339
  | boolean | A TOML boolean, not a quoted string. |
315
340
  | integer | An integer inside the inclusive range listed in the module catalog. |
341
+ | number | A finite number inside the inclusive range listed in the module catalog; fractions are accepted. |
316
342
  | string array | An array containing only non-empty strings. |
317
343
  | string-to-string table | A TOML table whose values are all strings. |
344
+ | command alternatives | One command string, or at most 16 command strings/argv arrays; see below. |
345
+ | context rules | At most 64 ordered Kubernetes rule tables; see below. |
346
+ | substitutions | A legacy string-to-string table or at most 64 ordered structured rows; see below. |
318
347
 
319
- Language `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
348
+ Language and Kubernetes `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
349
+ `detect_env_vars` allows negation for `python`, `conda`, `direnv`, `gcloud`, `hostname`, and `kubernetes`; `username` retains positive-only detection.
320
350
  Other string-array options reject entries beginning with `!`.
321
351
  Detection fallback and replacement behavior differs by module and is specified in [module behavior](modules.md).
322
352
 
353
+ ### Version formats
354
+
355
+ `version_format` applies to package, language, Pixi, and Terraform/OpenTofu versions and defaults to `v$raw`.
356
+ It uses the [format grammar](#-format-grammar): `$raw`, `$major`, `$minor`, `$patch`, their `${name}` forms, escapes, and conditional groups, but returns plain text without ANSI styles.
357
+ One leading lowercase `v` is removed from `$raw`; suffixes and leading zeroes remain in that raw value.
358
+ Numeric components are available only for a dotted numeric release with an optional suffix matching `[-+][0-9A-Za-z.+_-]+` or `[A-Za-z][0-9A-Za-z.+_-]*`.
359
+ A single numeric component is valid; missing minor/patch values are empty, extra components after patch are ignored, and component leading zeroes are removed.
360
+ For example, `01.002.0003-rc1` exposes `1`, `2`, `3`, and raw `01.002.0003-rc1`; malformed `1..2` exposes only raw text.
361
+ Unknown variables render empty, and an empty template hides the version.
362
+ Custom formats now use formatter variable boundaries and escapes, not raw substring replacement: use `${raw}_suffix` for appended identifier text and `\$` for a literal dollar sign.
363
+ Malformed format syntax or a template over 4,096 characters falls back to `v` plus the raw value.
364
+ Python's explicit pyenv-label mode bypasses this formatter.
365
+
366
+ ### Bounded regex and structured options
367
+
368
+ Directory regex substitutions and Kubernetes context patterns use RE2JS, not JavaScript's backtracking regex engine.
369
+ Patterns are limited to 512 source characters; input and replacement strings to 4,096 characters; replacement output to 8,192 characters; the cache retains at most 64 compiled patterns, including invalid-pattern entries.
370
+ Backreferences and lookaround are unsupported and rejected.
371
+ Replacement fields are `$1`/`${1}`, `$name`/`${name}`, or `$$` for a literal dollar; unknown captures become empty.
372
+ These are regex capture fields, not footer module variables.
373
+
374
+ `directory.substitutions` accepts either an ordered legacy literal map or ordered `{ from, to, regex }` rows.
375
+ Each structured row requires string `from` (at most 512 characters) and `to` (at most 4,096 characters); optional boolean `regex` defaults to `false`.
376
+ No other row keys are accepted; empty `from`/`to` strings are allowed.
377
+ Literal rules replace all occurrences with literal text and skip empty search strings; regex rules replace only the first match, including an empty regex match.
378
+ The legacy map has no schema row/string bound, but rendering skips the complete sequence when it has more than 64 rules; all sequences have a 16,384-character intermediate path bound.
379
+ See [directory behavior](modules.md#directory-git-and-environment-contraction) for order and runtime-failure fallback.
380
+
381
+ `kubernetes.contexts` requires `context_pattern` and allows only `user_pattern`, `context_alias`, `user_alias`, `symbol`, and `style` as optional strings.
382
+ Both patterns use the 512-character bound; other strings use the 4,096-character bound, and `style` must be a valid style under the selected palette.
383
+ Rules match bounded source context/user labels before aliases with AND and first-match semantics; [Kubernetes behavior](modules.md#kubernetes-detection-and-context-rules) defines exact-match precedence and alias order.
384
+ An invalid row, unsupported regex, unknown row key, or oversized array rejects the entire corresponding substitutions/rules option with a warning and restores its default, not just the failing row.
385
+ Unknown document fields still remain on disk.
386
+
387
+ ### Python command alternatives
388
+
389
+ `python_binary = []` preserves the existing active-virtualenv interpreter or `python` fallback.
390
+ A scalar such as `python_binary = "python3"` becomes one alternative; a non-empty array replaces that choice, for example `python_binary = ["python3", ["py", "-3"]]`.
391
+ Each string is one executable name/path, not a shell command line; each nested argv array contains 1–16 elements including its executable.
392
+ A flat string array lists alternative executables, not arguments to one executable.
393
+ There can be at most 16 alternatives, and each element must contain 1–1,024 characters without C0/C1 controls (`U+0000`–`U+001F`, `U+007F`–`U+009F`).
394
+ The runner appends `--version`, never starts an implicit shell, and stops at the first successful command even if its version output is malformed.
395
+ Invalid settings warn and restore the empty-array default.
396
+ Only use trusted executables and arguments: direct argv execution does not make a configured program safe.
397
+
398
+ ### Status templates
399
+
400
+ Git's 20 status options and Jujutsu status options use the normal format grammar with at most 4,096 characters and 16 nested groups.
401
+ Static group styles and the selected palette are supported; style variables such as `$style` are not.
402
+ Counted states accept only `$count`/`${count}`; Git `diverged` accepts only `ahead_count` and `behind_count`; clean/boolean/description templates accept no variables.
403
+ Invalid templates warn and restore that field's default; empty templates suppress that state.
404
+ See [Git status behavior](modules.md#git-display-controls-and-status-templates) and [Jujutsu behavior](modules.md#jujutsu-modules) for count formatting, activation, and ordering.
405
+
323
406
  ### Diagnostic and fallback behavior
324
407
 
325
408
  | Failure | Result |
326
409
  | --- | --- |
327
- | Missing file | Use built-in defaults without creating a file or directory. |
410
+ | Missing file | Use Pi's native footer without creating a file or directory. |
328
411
  | Read failure | Use built-in defaults and report an error diagnostic. |
329
412
  | TOML syntax failure | Preserve the raw document, use built-in defaults, and report an error diagnostic. |
330
413
  | Unknown root, module, option, or display field | Warn, ignore that field, and keep processing the document. |
@@ -396,7 +479,7 @@ An invalid root format falls back to the built-in root format; an invalid module
396
479
  `/starship status` reports warnings.
397
480
 
398
481
  The background-free defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`, `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`, `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` = `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`, `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
399
- Context, cost, Git metrics, and username use the state/multi-style defaults below.
482
+ Context, cost, battery, metrics, Jujutsu IDs, and username use state/multi-style fields; see below and the [complete module catalog](module-catalog.md).
400
483
 
401
484
  ### Pi theme colors
402
485
 
@@ -533,7 +616,11 @@ style = "bold red"
533
616
  hidden = false
534
617
  ```
535
618
 
536
- `git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
619
+ `git_metrics` and `jj_metrics` expose `$added_style` and `$deleted_style` in their module formats.
620
+ `jj_change` styles its composite IDs with `prefix_style`, `suffix_style`, and `change_offset_style`.
621
+ `battery` uses upper bounds: it selects the lowest threshold greater than or equal to the raw charge percentage, with the first entry winning a tie; no match or `hidden = true` hides the module.
622
+ Its default display is visible through 10% with `red bold`, not a context-style lower-bound rule.
623
+ `memory_usage.threshold` is a finite number from -100 through 10,000 (default 75); it gates the rounded native RAM percentage and is not a display array.
537
624
  `username` still uses `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the selector is not a format variable.
538
625
 
539
626
  ### Breaking palette migration
@@ -546,6 +633,6 @@ Choose one migration:
546
633
 
547
634
  1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
548
635
  2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
549
- 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
636
+ 3. Use **Restore built-in…** from `/starship` to archive the complete document in History, remove the active settings file, and return to Pi's native footer.
550
637
 
551
638
  There is no hidden compatibility overlay or automatic migration.