@narumitw/pi-starship 0.51.5 → 0.52.1

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.
package/README.md CHANGED
@@ -1,26 +1,23 @@
1
- # 🚀 pi-starship — Native Starship-style Statusline for Pi
1
+ # 🚀 pi-starship — Build Pi's Footer with Starship-style TOML
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@narumitw/pi-starship)](https://www.npmjs.com/package/@narumitw/pi-starship) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
4
 
5
- A native Pi footer configured with Starship-style TOML. It parses and renders formats itself—no `starship` executable or shell prompt required.
5
+ Build a deeply customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout.
6
6
 
7
- > **Different package:** the unscoped npm package `pi-starship` delegates to the Starship binary. This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
7
+ No `starship` executable or shell prompt is required because this extension parses and renders the footer itself.
8
+
9
+ > **Different package:** The unscoped npm package `pi-starship` delegates to the Starship binary.
10
+ > This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
8
11
 
9
12
  ## ✨ Features
10
13
 
11
- - Loads a generated split TypeScript runtime through Pi's Jiti loader to reduce package startup work.
12
- - Uses a readable, palette-free Starship-style built-in configuration until settings are saved.
13
- - Starship-style root/module formats, conditional groups, `$all`, styles, and opt-in palettes.
14
- - Pi modules for model, thinking, activity, context, tokens, prompt cache, cost, turn, and extension statuses.
15
- - Cached Git branch, commit, operation state, line metrics, detailed status, and linked-worktree identity.
16
- - Native current-branch GitHub pull request links, checks, review state, and terminal-state retention.
17
- - Opt-in package, language, development-shell, deployment, cloud, and execution-context modules.
18
- - Width-aware `$fill` alignment for native multiline left/right layouts.
19
- - Footer rendering is pure: no subprocess, network, filesystem, timer, or environment work runs from `render()`.
20
- - Multiline output wraps to the terminal width instead of truncating.
21
- - Goal-oriented `/starship` menu with every Starship 1.26 preset style plus a Pi-native Minimal
22
- preset, footer explanation, searchable module inspection, configuration health, transactional
23
- preview, and recovery.
14
+ - Starts with a readable built-in footer and offers Starship presets plus a Pi-native Minimal preset.
15
+ - Supports root and module formats, conditional groups, `$all`, styles, palettes, and width-aware `$fill` alignment.
16
+ - Provides Pi, model, usage, Git, pull request, package, language, environment, deployment, cloud, and execution modules.
17
+ - Wraps native multiline layouts to terminal width instead of truncating them.
18
+ - Keeps rendering pure while refreshing filesystem, process, and network-derived data through bounded caches.
19
+ - Uses `/starship` for presets, preview, configuration health, searchable module details, customization, and recovery.
20
+ - Loads a generated split runtime to reduce Pi package startup work.
24
21
 
25
22
  ## 📦 Install
26
23
 
@@ -37,16 +34,20 @@ pi -e npm:@narumitw/pi-starship
37
34
  Build the generated runtime and try the local package from this repository:
38
35
 
39
36
  ```bash
40
- just try starship
37
+ npm --workspace @narumitw/pi-starship run build
38
+ pi -e ./packages/pi-starship
41
39
  ```
42
40
 
43
- The package declares `dist/index.ts`, so an unbuilt local checkout must run `npm --workspace @narumitw/pi-starship run build` before Pi loads the package directory.
44
-
45
- `just try starship` runs that build automatically.
41
+ The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
46
42
 
47
43
  Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
48
44
 
49
- ## ⚙️ Configuration
45
+ ## 🚀 Quick start
46
+
47
+ Start Pi with the extension to use the built-in footer without creating a settings file.
48
+ Run `/starship` to inspect the footer, choose a preset, or customize the configuration.
49
+
50
+ ## ⚙️ Settings
50
51
 
51
52
  The only configuration source is:
52
53
 
@@ -54,11 +55,10 @@ The only configuration source is:
54
55
  <getAgentDir()>/pi-starship.toml
55
56
  ```
56
57
 
57
- When this file is absent, the extension uses its readable palette-free default without creating the
58
- file or parent directory. The built-in root is the explicit sequence `$brand$model$thinking$directory`
59
- `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query. The first
60
- successful settings save creates the file atomically. Existing malformed documents are never
61
- overwritten.
58
+ When this file is absent, the extension uses its readable palette-free default without creating the file or parent directory.
59
+ 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.
60
+ The first successful settings save creates the file atomically.
61
+ Existing malformed documents are never overwritten.
62
62
 
63
63
  The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
64
64
 
@@ -68,38 +68,37 @@ Open the interactive menu in TUI mode:
68
68
  /starship
69
69
  ```
70
70
 
71
- Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens an
72
- adaptive, scrollable preview whose **Apply changes…**, **Continue editing**, and **Discard draft**
73
- actions remain reachable in short or narrow terminals. Saving happens only after a separate
74
- confirmation. Confirmed changes are atomically saved and applied immediately. Manual TOML edits load
75
- on the next `session_start`, including `/reload` and session replacement. Editor cancellation, preview
76
- cancellation, component disposal, invalid drafts, write failures, and runtime application failures
77
- preserve the previous file and effective footer.
78
-
79
- The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**,
80
- **Help**, and **Restore built-in…**. Explain footer uses the current immutable runtime snapshot to list
81
- each currently showing non-empty module once with its rendered value and description; it starts no new
82
- collection work. Modules opens a bounded searchable inspector for every registered module. Its
83
- textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and
84
- **Unavailable** only when the current footer cannot provide an inspection snapshot. Module detail
85
- shows the current preview when available, description, root reference and reachability, format
86
- variables, style fields, display rules, and the known reason for absent output. Both views are
87
- read-only and never create or update the settings document.
88
-
89
- Configuration combines state, source, path, health, and diagnostics. A healthy missing file is shown
90
- as **Built-in defaults**, an exact bundled document is shown as its named preset, and **Built-in
91
- fallback** is reserved for read or parse errors. Restore is disabled when no settings document exists
92
- or the exact built-in document is already saved. For a custom or invalid document, Restore previews
93
- the result and warns that the complete document,
94
- including custom settings, unknown fields, and comments, will be replaced without a post-success
95
- backup before asking for confirmation.
71
+ Choose **Customize footer** to edit the TOML.
72
+ Closing the editor validates the draft and opens an adaptive, scrollable preview whose **Apply changes…**, **Continue editing**, and **Discard draft** actions remain reachable in short or narrow terminals.
73
+ Saving happens only after a separate confirmation.
74
+ Confirmed changes are atomically saved and applied immediately.
75
+ Manual TOML edits load on the next `session_start`, including `/reload` and session replacement.
76
+ Editor cancellation, preview cancellation, component disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and effective footer.
77
+
78
+ The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
79
+ 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.
80
+ Modules opens a bounded searchable inspector for every registered module.
81
+ Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
82
+ Module detail shows the current preview when available, description, root reference and reachability, format variables, style fields, display rules, and the known reason for absent output.
83
+ Both views are read-only and never create or update the settings document.
84
+
85
+ Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
86
+ Overview combines state, source, path, health, and bounded diagnostics.
87
+ 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.
88
+ Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
89
+ A healthy missing file is shown as **Built-in defaults**, an exact bundled document is shown as its named preset, and **Built-in fallback** is reserved for read or parse errors.
90
+ 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.
91
+ A deleted document is a valid previewable transition to built-in defaults and creates no file.
92
+ 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.
93
+ 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.
94
+ Restore is disabled when no settings document exists or the exact built-in document is already saved.
95
+ 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 without a post-success backup before asking for confirmation.
96
96
 
97
97
  ### 🎛️ Presets
98
98
 
99
- Choose **Presets** from `/starship` to browse complete Pi-native starting points. The catalog adapts
100
- all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
101
- Colors, separators, typography, and layout follow the named Starship preset; modules are deliberately
102
- selected for Pi's model, thinking, workspace, Git, activity, context, and time snapshots.
99
+ Choose **Presets** from `/starship` to browse complete Pi-native starting points.
100
+ The catalog adapts all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
101
+ Colors, separators, typography, and layout follow the named Starship preset; modules are deliberately selected for Pi's model, thinking, workspace, Git, activity, context, and time snapshots.
103
102
 
104
103
  | Preset | Adapted visual treatment | Font requirement |
105
104
  | --- | --- | --- |
@@ -117,25 +116,21 @@ selected for Pi's model, thinking, workspace, Git, activity, context, and time s
117
116
  | **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
118
117
  | **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
119
118
 
120
- The preset cursor is a live footer preview. Opening the picker and moving with Up/Down, Page Up/Down,
121
- Home, or End temporarily renders the selected preset in the actual footer without writing settings or
122
- starting new collectors. Press Enter to start the named preset's replacement confirmation, or press
123
- `e` to customize the selected complete TOML document before its normal editor preview and
124
- confirmation. Escape returns to the main menu, while Ctrl+C closes the complete workflow; both restore
125
- the previously effective footer.
126
-
127
- Presets are complete documents, not overlays. Applying one replaces `pi-starship.toml`, including
128
- custom settings, unknown fields, and comments, only after a separate confirmation; no post-success
129
- backup is kept. Cursor movement, confirmation cancellation, disposal, validation failure, write
130
- failure, and runtime-apply failure retain the previous valid document and effective footer. Exact
131
- unedited matches are shown as **Currently applied** and cannot be redundantly selected; editing any
132
- byte makes the document custom again. **Restore built-in…** remains the deterministic recovery path.
133
-
134
- The bundled presets use only pi-starship's local Pi and Git snapshot modules. They do not enable the
135
- GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors. They are
136
- Pi-native adaptations of the color and format treatments emitted by Starship 1.26.0; they do not copy
137
- Starship's module selections because Pi exposes different runtime information. There is no
138
- `/starship preset` textual route and no remote preset download.
119
+ The preset cursor is a live footer preview.
120
+ Opening the picker and moving with Up/Down, Page Up/Down, Home, or End temporarily renders the selected preset in the actual footer without writing settings or starting new collectors.
121
+ Press Enter to start the named preset's replacement confirmation, or press `e` to customize the selected complete TOML document before its normal editor preview and confirmation.
122
+ Escape returns to the main menu, while Ctrl+C closes the complete workflow; both restore the previously effective footer.
123
+
124
+ Presets are complete documents, not overlays.
125
+ Applying one replaces `pi-starship.toml`, including custom settings, unknown fields, and comments, only after a separate confirmation; no post-success backup is kept.
126
+ Cursor movement, confirmation cancellation, disposal, validation failure, write failure, and runtime-apply failure retain the previous valid document and effective footer.
127
+ Exact unedited matches are shown as **Currently applied** and cannot be redundantly selected; editing any byte makes the document custom again.
128
+ **Restore built-in…** remains the deterministic recovery path.
129
+
130
+ The bundled presets use only pi-starship's local Pi and Git snapshot modules.
131
+ They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
132
+ They are Pi-native adaptations of the color and format treatments emitted by Starship 1.26.0; they do not copy Starship's module selections because Pi exposes different runtime information.
133
+ There is no `/starship preset` textual route and no remote preset download.
139
134
 
140
135
  ### 📝 Example
141
136
 
@@ -202,37 +197,35 @@ format = "([$statuses ]($style))"
202
197
  icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
203
198
  ```
204
199
 
205
- Every module table supports `format`, `symbol`, and `disabled`. Most modules also support one `style`.
206
- The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and
207
- `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
200
+ Every module table supports `format`, `symbol`, and `disabled`.
201
+ Most modules also support one `style`.
202
+ 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.
208
203
  Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
209
- Version formats replace `$raw`. Detection arrays replace defaults when non-empty and inspect only one
210
- listing of the current directory. A leading `!` is supported by language detection arrays and rejects
211
- a matching project.
212
- `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace
213
- wildcards such as `foo:*`; `fallback` controls unmatched statuses. Icon matching uses the exact key,
214
- the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`. An empty configured icon
215
- suppresses only the icon. `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
216
-
217
- Pi does not expose which package owns a status, so exact raw keys are the reliable third-party
218
- contract. pi-starship does not inspect installed packages, infer package aliases, assign icons to
219
- known extensions, or bridge compatibility keys. Extension authors may adopt `<extension-id>` or
220
- `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require that convention.
221
-
222
- **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons,
223
- or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a
224
- leading emoji in the status value, or `fallback`.
204
+ Version formats replace `$raw`.
205
+ Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
206
+ A leading `!` is supported by language detection arrays and rejects a matching project.
207
+ `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
208
+ Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
209
+ An empty configured icon suppresses only the icon.
210
+ `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
211
+
212
+ Pi does not expose which package owns a status, so exact raw keys are the reliable third-party contract. pi-starship does not inspect installed packages, infer package aliases, assign icons to known extensions, or bridge compatibility keys.
213
+ Extension authors may adopt `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require that convention.
214
+
215
+ **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons, or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a leading emoji in the status value, or `fallback`.
225
216
 
226
217
  ## 🧩 Format grammar
227
218
 
228
- - Variables: `$name` and `${name}`. Unknown variables render empty and produce a warning when loaded from TOML.
219
+ - Variables: `$name` and `${name}`.
220
+ Unknown variables render empty and produce a warning when loaded from TOML.
229
221
  - Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
230
222
  - Styled groups: `[format string](style string)`.
231
223
  - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
232
224
  - Nested groups are supported.
233
225
  - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
234
226
 
235
- Module formats can use `$style` in a style expression. Module output keeps its own style when embedded in an outer styled group.
227
+ Module formats can use `$style` in a style expression.
228
+ Module output keeps its own style when embedded in an outer styled group.
236
229
 
237
230
  ## 🎨 Styles and palettes
238
231
 
@@ -243,15 +236,13 @@ Style expressions support:
243
236
  - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
244
237
  - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
245
238
  - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
246
- - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same
247
- Starship-compatible reset behavior.
248
- - `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any
249
- absolute foreground/background in the expression as the no-previous fallback.
239
+ - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same Starship-compatible reset behavior.
240
+ - `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any absolute foreground/background in the expression as the no-previous fallback.
250
241
  - Direct color names from one explicitly selected `[palettes.<name>]` table.
251
242
 
252
- There is no built-in or fallback palette. A custom palette is active only when its table is explicitly
253
- selected, and its values must be direct named, ANSI, or RGB colors—palette entries cannot reference
254
- other entries. Palette names override terminal color names such as `blue`:
243
+ There is no built-in or fallback palette.
244
+ A custom palette is active only when its table is explicitly selected, and its values must be direct named, ANSI, or RGB colors—palette entries cannot reference other entries.
245
+ Palette names override terminal color names such as `blue`:
255
246
 
256
247
  ```toml
257
248
  palette = "company"
@@ -265,29 +256,24 @@ style = "bold blue"
265
256
  ```
266
257
 
267
258
  Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
268
- `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists. Empty styled
269
- groups still advance previous-color state. Invalid literal style expressions warn and render
270
- unstyled. An invalid root format falls back to the built-in root format; an invalid module format or
271
- catalog-owned style field falls back only at that field's module scope. `/starship status` reports
272
- warnings.
273
-
274
- The background-free direct defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`,
275
- `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`,
276
- `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` =
277
- `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`,
278
- `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
259
+ `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
260
+ Empty styled groups still advance previous-color state.
261
+ Invalid literal style expressions warn and render unstyled.
262
+ An invalid root format falls back to the built-in root format; an invalid module format or catalog-owned style field falls back only at that field's module scope.
263
+ `/starship status` reports warnings.
264
+
265
+ The background-free direct 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"`.
279
266
  Context, cost, Git metrics, and username use the state/multi-style defaults below.
280
267
 
281
268
  ### State-selected styles
282
269
 
283
- `context` and `cost` select the last entry at the highest threshold less than or equal to the current
284
- value. A later entry wins when thresholds are equal. Each display entry requires a finite `threshold`,
285
- a valid `style`, and boolean `hidden`. Invalid entries warn and are ignored; module defaults are used
286
- if none remain.
270
+ `context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
271
+ A later entry wins when thresholds are equal.
272
+ Each display entry requires a finite `threshold`, a valid `style`, and boolean `hidden`.
273
+ Invalid entries warn and are ignored; module defaults are used if none remain.
287
274
 
288
- The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and
289
- `bold red` at `80`. The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red`
290
- at `5`:
275
+ The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and `bold red` at `80`.
276
+ The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red` at `5`:
291
277
 
292
278
  ```toml
293
279
  [[cost.display]]
@@ -306,25 +292,20 @@ style = "bold red"
306
292
  hidden = false
307
293
  ```
308
294
 
309
- `git_metrics` exposes `$added_style` and `$deleted_style` in its module format. `username` still uses
310
- `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the
311
- selector is not a format variable.
295
+ `git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
296
+ `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.
312
297
 
313
298
  ### Breaking palette migration
314
299
 
315
- The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`,
316
- `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases
317
- were removed. Existing files are not rewritten. Old alias-based module styles warn and fall back to
318
- the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
300
+ The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`, `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases were removed.
301
+ Existing files are not rewritten.
302
+ Old alias-based module styles warn and fall back to the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
319
303
 
320
304
  Choose one migration:
321
305
 
322
- 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or
323
- `fg:#e3e5e5 bg:#769ff0`.
324
- 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with
325
- `palette = "<name>"`.
326
- 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new
327
- plain nine-module configuration.
306
+ 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
307
+ 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
308
+ 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
328
309
 
329
310
  There is no hidden compatibility overlay or automatic migration.
330
311
 
@@ -379,21 +360,20 @@ There is no hidden compatibility overlay or automatic migration.
379
360
 
380
361
  ### Usage semantics
381
362
 
382
- - `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer:
383
- assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned
384
- branches retained in the session.
385
- - Cache `$read` and `$write` are cumulative. `$rate` uses only the latest assistant prompt:
386
- `cacheRead / (input + cacheRead + cacheWrite) * 100`. The module is empty when Pi has reported no
387
- cache reads or writes.
388
- - `cache` is disabled and absent from the built-in root. Enable it and add `$cache` to a custom root
389
- format (or use `$all`) to display it.
390
- - Context `$percentage` uses native one-decimal precision. Its default display hides values below 30%;
391
- customize `[[context.display]]` when lower values should remain visible. The module name remains
392
- `context`, not `context_usage`.
393
- - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`. The dollar
394
- value is usage cost, not proof of an amount billed under a subscription.
395
- - Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot
396
- reliably provide the native `(auto)` marker.
363
+ - `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
364
+ This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
365
+ - Cache `$read` and `$write` are cumulative.
366
+ `$rate` uses only the latest assistant prompt with `cacheRead / (input + cacheRead + cacheWrite) * 100`.
367
+ The module is empty when Pi has reported no cache reads or writes.
368
+ - `cache` is disabled and absent from the built-in root.
369
+ Enable it and add `$cache` to a custom root format (or use `$all`) to display it.
370
+ - Context `$percentage` uses native one-decimal precision.
371
+ Its default display hides values below 30%.
372
+ Customize `[[context.display]]` when lower values should remain visible.
373
+ The module name remains `context`, not `context_usage`.
374
+ - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
375
+ The dollar value is usage cost, not proof of an amount billed under a subscription.
376
+ - Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot reliably provide the native `(auto)` marker.
397
377
 
398
378
  ### Directory, Git, and environment contraction
399
379
 
@@ -424,29 +404,26 @@ truncation_length = 1
424
404
  trim_at = "." # set to "" to keep the complete hostname
425
405
  ```
426
406
 
427
- Directory `$path` contracts the home directory and, by default, the current Git repository root
428
- before retaining the last three path components. `$full_path` remains the unmodified absolute cwd.
429
- A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no
430
- substitution is configured. `substitutions` is an ordered TOML string table of literal replacements.
431
- Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement
432
- Starship's regex substitution array or repo-root-specific split style/format fields. Directory
433
- rendering reads only immutable home and repository-root snapshot data and performs no filesystem or
434
- Git work.
435
-
436
- Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of
437
- `truncation_symbol` only when truncation occurs. The same rule applies independently to `$branch`,
438
- `$remote_name`, and `$remote_branch`. Upstream Starship represents its unlimited default as
439
- `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately
440
- bounded. `commit_hash_length` accepts 0 through 64.
441
-
442
- Conda retains the last path component by default; `0` keeps the complete environment path. Hostname
443
- trimming runs before exact alias lookup, matching Starship. These are display transformations only:
444
- collectors retain bounded, control-sanitized source metadata.
407
+ Directory `$path` contracts the home directory and, by default, the current Git repository root before retaining the last three path components.
408
+ `$full_path` remains the unmodified absolute cwd.
409
+ A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no substitution is configured.
410
+ `substitutions` is an ordered TOML string table of literal replacements.
411
+ Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement Starship's regex substitution array or repo-root-specific split style/format fields.
412
+ Directory rendering reads only immutable home and repository-root snapshot data and performs no filesystem or Git work.
413
+
414
+ Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of `truncation_symbol` only when truncation occurs.
415
+ The same rule applies independently to `$branch`, `$remote_name`, and `$remote_branch`.
416
+ Upstream Starship represents its unlimited default as `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately bounded.
417
+ `commit_hash_length` accepts 0 through 64.
418
+
419
+ Conda retains the last path component by default; `0` keeps the complete environment path.
420
+ Hostname trimming runs before exact alias lookup, matching Starship.
421
+ These transformations affect display only.
422
+ Collectors retain bounded, control-sanitized source metadata.
445
423
 
446
424
  ### Model aliases and truncation
447
425
 
448
- The model module accepts exact `model_aliases`, Starship-style `truncation_length` and
449
- `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
426
+ The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
450
427
 
451
428
  ```toml
452
429
  [model]
@@ -456,30 +433,29 @@ truncation_symbol = "…"
456
433
  truncation_direction = "middle"
457
434
  ```
458
435
 
459
- An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label
460
- is subject to the configured truncation. `truncation_length` counts model grapheme clusters retained
461
- before the symbol; `0` disables
462
- truncation and is the default. The direction names the removed portion: `start` retains the suffix,
463
- `end` retains the prefix and is the default, and `middle` retains both ends. When no alias matches,
464
- truncation runs after the built-in Claude/GPT shortening rules. It always changes display only—the
465
- provider model ID is untouched.
466
- Terminal control sequences in model IDs and truncation symbols are removed at render time. An empty
467
- symbol truncates without a marker. For example, `middle` can retain both a Hugging Face model
468
- family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
469
- pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes,
470
- or quantization names.
436
+ An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label is subject to the configured truncation.
437
+ `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
438
+ The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
439
+ When no alias matches, truncation runs after the built-in Claude/GPT shortening rules.
440
+ It always changes display only—the provider model ID is untouched.
441
+ Terminal control sequences in model IDs and truncation symbols are removed at render time.
442
+ An empty symbol truncates without a marker.
443
+ For example, `middle` can retain both a Hugging Face model family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
444
+ pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
471
445
 
472
- `truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic
473
- truncation-direction setting.
446
+ `truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic truncation-direction setting.
474
447
 
475
- `git_worktree` is empty in the primary worktree. In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
448
+ `git_worktree` is empty in the primary worktree.
449
+ In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
476
450
 
477
- `git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format. Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default. `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
451
+ `git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
452
+ Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
453
+ `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
478
454
 
479
455
  ### 🔎 Native GitHub pull requests
480
456
 
481
- `$github_pr` is independent of `pi-github-pr`; installing that extension is not required. It runs one
482
- bounded GitHub CLI query for the current branch:
457
+ `$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
458
+ It runs one bounded GitHub CLI query for the current branch:
483
459
 
484
460
  ```text
485
461
  gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
@@ -491,11 +467,8 @@ Install and authenticate `gh` first:
491
467
  gh auth login
492
468
  ```
493
469
 
494
- For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository
495
- remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly
496
- with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves
497
- the correct repository and host from the current checkout. It never mutates Pi's environment, calls
498
- the GitHub API directly, or manages tokens.
470
+ For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves the correct repository and host from the current checkout.
471
+ It never mutates Pi's environment, calls the GitHub API directly, or manages tokens.
499
472
 
500
473
  Variables have these values:
501
474
 
@@ -503,10 +476,8 @@ Variables have these values:
503
476
  - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
504
477
  - `$state`: `open`, `draft`, `merged`, or `closed`.
505
478
  - `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
506
- - `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty
507
- when unknown.
508
- - `$status`: one result selected in this order: merged, closed, draft, failing checks, changes
509
- requested, pending checks, approved, review required, passing checks, then no checks.
479
+ - `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty when unknown.
480
+ - `$status`: one result selected in this order: merged, closed, draft, failing checks, changes requested, pending checks, approved, review required, passing checks, then no checks.
510
481
 
511
482
  The compact symbols are font-safe and distinct from Git's default `$`, `!`, and `?` worktree markers:
512
483
 
@@ -529,8 +500,7 @@ PR #123 · R✓
529
500
  PR #123 · M
530
501
  ```
531
502
 
532
- Use the existing `$checks` and `$review` variables together when every check category and the review
533
- result should remain visible:
503
+ Use the existing `$checks` and `$review` variables together when every check category and the review result should remain visible:
534
504
 
535
505
  ```toml
536
506
  [github_pr]
@@ -555,30 +525,26 @@ This is a breaking display migration for custom formats that use these variables
555
525
  The old English values have no verbose aliases.
556
526
  The variable names and default module format remain unchanged, so no TOML field migration is needed.
557
527
 
558
- The query runs only in TUI sessions when the enabled module is reachable from the root format. It
559
- refreshes at session start, immediately after a branch change, after each agent run, after accepted
560
- settings changes, and every 60 seconds. Each query has a 10-second timeout. Branch changes clear the
561
- old PR before querying the new branch. Closed and merged PRs remain visible for 24 hours, then expire
562
- without waiting for the next refresh. Missing `gh`, missing authentication, no current PR, timeout,
563
- malformed or oversized output, and network failures all render an empty module without exposing raw
564
- errors or credentials.
528
+ The query runs only in TUI sessions when the enabled module is reachable from the root format.
529
+ It refreshes at session start, immediately after a branch change, after each agent run, after accepted settings changes, and every 60 seconds.
530
+ Each query has a 10-second timeout.
531
+ Branch changes clear the old PR before querying the new branch.
532
+ Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
533
+ Missing `gh`, missing authentication, no current PR, timeout, malformed or oversized output, and network failures all render an empty module without exposing raw errors or credentials.
565
534
 
566
- The query sends the repository/current-branch context through authenticated `gh` to the GitHub host
567
- configured by the repository. It requests only the fields above—never comments, review bodies,
568
- inline comments, or review threads. Footer rendering and previews read only the immutable cached
569
- snapshot and perform no network or subprocess work.
535
+ The query sends the repository/current-branch context through authenticated `gh` to the GitHub host configured by the repository.
536
+ It requests only the fields above—never comments, review bodies, inline comments, or review threads.
537
+ Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
570
538
 
571
- **Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic
572
- migration. Replace it with root `$github_pr` and an optional `[github_pr]` table. If `pi-github-pr`
573
- remains installed, its independent `github-pr` status can also appear under `$extension_status`;
574
- disable or remove that extension when adopting the native module to avoid duplicate information.
539
+ **Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic migration.
540
+ Replace it with root `$github_pr` and an optional `[github_pr]` table.
541
+ If `pi-github-pr` remains installed, its independent `github-pr` status can also appear under `$extension_status`.
542
+ Disable or remove that extension when adopting the native module to avoid duplicate information.
575
543
 
576
544
  ### 📦 Package and language modules
577
545
 
578
- Module behavior is inspired by Starship pinned at
579
- `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved
580
- multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`. This is not
581
- complete Starship module or configuration compatibility.
546
+ Module behavior is inspired by Starship pinned at `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`.
547
+ This is not complete Starship module or configuration compatibility.
582
548
 
583
549
  | Area | Adopted | Adapted | Intentionally omitted |
584
550
  | --- | --- | --- | --- |
@@ -590,10 +556,9 @@ complete Starship module or configuration compatibility.
590
556
  | Bun / Deno | Direct markers and `bun --version` / `deno -V` | Negative detection avoids overlapping Node defaults | Runtime installation and recursive source detection |
591
557
 
592
558
  All runtime commands use argv execution in `ctx.cwd`, a 2-second timeout, and 64 KiB accepted output.
593
- Commands run only when the reachable module format references the command-backed variable. Missing,
594
- killed, oversized, or malformed commands clear that value independently. `version_format`,
595
- `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package
596
- supports `version_format`.
559
+ Commands run only when the reachable module format references the command-backed variable.
560
+ Missing, killed, oversized, or malformed commands clear that value independently.
561
+ `version_format`, `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package supports `version_format`.
597
562
 
598
563
  ### 🧰 Development environments
599
564
 
@@ -606,48 +571,47 @@ supports `version_format`.
606
571
  | `nix_shell` | `IN_NIX_SHELL`, `NIX_SHELL_NAME`, `NIX_SHELL_LEVEL` | None | None |
607
572
  | `guix_shell` | Presence of `GUIX_ENVIRONMENT` | None | None |
608
573
 
609
- The extension never enumerates the process environment, activates a shell, evaluates Nix, lists
610
- installed tools, or publishes arbitrary environment values. Names and paths are control-sanitized and
611
- bounded before publication.
574
+ The extension never enumerates the process environment, activates a shell, evaluates Nix, lists installed tools, or publishes arbitrary environment values.
575
+ Names and paths are control-sanitized and bounded before publication.
612
576
 
613
577
  ### 🚢 Deployment and cloud context
614
578
 
615
- These modules read inert local metadata only. They do **not** contact Docker, a Kubernetes cluster,
616
- a Terraform/OpenTofu backend, a cloud API, an OAuth flow, a credential helper, or a metadata service.
617
- The deployment/cloud safety review retained opt-in root behavior: context labels may be sensitive and
618
- there is no usage evidence justifying more default footer density.
579
+ These modules read inert local metadata only.
580
+ They do **not** contact Docker, a Kubernetes cluster, a Terraform/OpenTofu backend, a cloud API, an OAuth flow, a credential helper, or a metadata service.
581
+ The deployment/cloud safety review retained opt-in root behavior: context labels may be sensitive and there is no usage evidence justifying more default footer density.
619
582
 
620
- - `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`;
621
- `default` is suppressed. `only_with_files` and detection arrays are supported.
622
- - `kubernetes`: at most `max_config_files` (default 8) from `KUBECONFIG` or `~/.kube/config`, with
623
- first-wins merge semantics. Only context, namespace, cluster name, and user name are selected.
583
+ - `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
584
+ The `default` context is suppressed.
585
+ `only_with_files` and detection arrays are supported.
586
+ - `kubernetes`: at most `max_config_files` (default 8) from `KUBECONFIG` or `~/.kube/config`, with first-wins merge semantics.
587
+ Only context, namespace, cluster name, and user name are selected.
624
588
  Exact `context_aliases`, `namespace_aliases`, `cluster_aliases`, and `user_aliases` apply.
625
- - `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is
626
- `TF_WORKSPACE` → `TF_DATA_DIR/environment` → `.terraform/environment`. `terraform version`, then
627
- `tofu version`, runs only for `$version`. Workspace, init, provider, and state commands never run.
628
- - `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS
629
- config section. The credentials file is never read. Exact profile/region aliases are supported.
630
- - `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI
631
- keys. Exact project/region aliases are supported.
632
- - `azure`: the default local `azureProfile.json` subscription name. `show_username` defaults to
633
- `false`; exact subscription aliases are supported.
634
- - `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only;
635
- exact cloud/project aliases are supported.
636
-
637
- Cloud files often colocate credentials with labels. Parsers allowlist fields while reading and
638
- discard source documents; token, key, password, auth URL, tenant, and credential-derived duration
639
- fields never enter snapshots, diagnostics, notifications, or rendered output. Presence indicates only
640
- selected local metadata—not valid credentials or connectivity.
589
+ - `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is `TF_WORKSPACE` → `TF_DATA_DIR/environment` → `.terraform/environment`.
590
+ `terraform version`, then `tofu version`, runs only for `$version`.
591
+ Workspace, init, provider, and state commands never run.
592
+ - `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS config section.
593
+ The credentials file is never read.
594
+ Exact profile/region aliases are supported.
595
+ - `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI keys.
596
+ Exact project/region aliases are supported.
597
+ - `azure`: the default local `azureProfile.json` subscription name.
598
+ `show_username` defaults to `false`; exact subscription aliases are supported.
599
+ - `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only.
600
+ Exact cloud/project aliases are supported.
601
+
602
+ Cloud files often colocate credentials with labels.
603
+ Parsers allowlist fields while reading and discard source documents; token, key, password, auth URL, tenant, and credential-derived duration fields never enter snapshots, diagnostics, notifications, or rendered output.
604
+ Presence indicates only selected local metadata—not valid credentials or connectivity.
641
605
 
642
606
  ### 🖥️ Execution context
643
607
 
644
- `hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`. `username`
645
- appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured
646
- `detect_env_vars`; it supports exact aliases. Negated username detection names are rejected. `os` is
647
- disabled by default and supports an exact `symbols` map. `container` uses only Dev Container/Codespaces
648
- markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not
649
- scan process tables or cgroups. Ordinary local hostname/username sessions stay empty. All identity
650
- labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
608
+ `hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`.
609
+ `username` appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured `detect_env_vars`; it supports exact aliases.
610
+ Negated username detection names are rejected.
611
+ `os` is disabled by default and supports an exact `symbols` map.
612
+ `container` uses only Dev Container/Codespaces markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not scan process tables or cgroups.
613
+ Ordinary local hostname/username sessions stay empty.
614
+ All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
651
615
 
652
616
  ### ↔️ Fill layout
653
617
 
@@ -661,31 +625,30 @@ symbol = " " # native invisible default; use "·" for a visible pattern
661
625
  style = "dimmed"
662
626
  ```
663
627
 
664
- Fill resolves independently on each logical line before ANSI serialization and wrapping. Multiple
665
- fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder
666
- uses styled spaces. Empty/zero-width patterns become spaces. Fixed content is never truncated: when it
667
- already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
668
- Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI
669
- visible-width semantics. `$all` deliberately includes enabled fill, so use `$all` only when that
670
- whole-catalog layout is intended. There is no `line_break` module; use literal newlines in `format`.
628
+ Fill resolves independently on each logical line before ANSI serialization and wrapping.
629
+ Multiple fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder uses styled spaces.
630
+ Empty/zero-width patterns become spaces.
631
+ Fixed content is never truncated: when it already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
632
+ Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI visible-width semantics.
633
+ `$all` deliberately includes enabled fill, so use `$all` only when that whole-catalog layout is intended.
634
+ There is no `line_break` module; use literal newlines in `format`.
671
635
 
672
636
  ### 🔄 Cached refresh lifecycle
673
637
 
674
- Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled
675
- modules. Root format reachability, `$all`, module `disabled`, and module-format variables determine
676
- file and command requirements. Workspace/Git refreshes run at session start, after accepted settings,
677
- branch changes, tool/turn completion, and a 30-second fallback. GitHub PR uses the narrower lifecycle
678
- and 60-second network refresh described above. One read runs with at most one latest pending refresh;
679
- immutable snapshot equality suppresses redraws, and session/request generations reject stale results.
680
- Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command
681
- work before starting replacements; disabling `github_pr` also stops its query and timers. Bounded local
682
- filesystem operations may finish, but stale generations cannot publish them. Execution identity is
683
- retained rather than re-read by the periodic fallback. Render and live preview consume snapshots
684
- synchronously and perform zero reads or commands.
638
+ Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
639
+ Root format reachability, `$all`, module `disabled`, and module-format variables determine file and command requirements.
640
+ Workspace/Git refreshes run at session start, after accepted settings, branch changes, tool/turn completion, and a 30-second fallback.
641
+ GitHub PR uses the narrower lifecycle and 60-second network refresh described above.
642
+ One read runs with at most one latest pending refresh.
643
+ Immutable snapshot equality suppresses redraws, and session or request generations reject stale results.
644
+ Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command work before starting replacements; disabling `github_pr` also stops its query and timers.
645
+ Bounded local filesystem operations may finish, but stale generations cannot publish them.
646
+ Execution identity is retained rather than re-read by the periodic fallback.
647
+ Render and live preview consume snapshots synchronously and perform zero reads or commands.
685
648
 
686
649
  Missing, unreadable, malformed, oversized, timed-out, or unavailable sources fail to empty values.
687
- Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never
688
- recurse, and make no network calls. The native GitHub PR query is the documented network exception.
650
+ Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
651
+ The native GitHub PR query is the documented network exception.
689
652
  Package's explicitly documented Cargo lookup is the only ancestor walk and is capped at eight parents.
690
653
 
691
654
  ## 💬 Commands
@@ -697,39 +660,34 @@ Package's explicitly documented Cargo lookup is the only ancestor walk and is ca
697
660
  | `/starship status` | Show config source/path and diagnostics |
698
661
  | `/starship help` | Show command and configuration help |
699
662
 
700
- The standard main menu keeps seven goals on one level: **Customize footer**, **Presets**,
701
- **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**. It shows whether
702
- the footer uses built-in defaults, a saved built-in document, a named preset, a custom document, or an
703
- error-driven fallback,
704
- together with the current health. Presets, Explain, and Modules are menu-only paths; they do not add
705
- textual subcommands or change RPC, print, or JSON protocols. Restore remains last and unavailable
706
- when there is no document to replace.
663
+ The standard main menu keeps seven goals on one level: **Customize footer**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
664
+ It shows whether the footer uses built-in defaults, a saved built-in document, a named preset, a custom document, or an error-driven fallback, together with the current health.
665
+ Presets, Explain, Modules, and the nested Configuration capabilities are menu-only paths; they do not add textual subcommands or change RPC, print, or JSON protocols.
666
+ Restore remains last and unavailable when there is no document to replace.
707
667
 
708
- The TOML editor, adaptive live footer previews, Explain view, and searchable module inspector remain
709
- specialized extension UI. Their hints follow Pi's injected keybindings; list and detail content stay
710
- bounded across terminal resize. Escape returns from detail or to the main menu, while Ctrl+C closes
711
- the whole workflow.
668
+ The TOML editor, adaptive live footer previews, Explain view, searchable module inspector, and Configuration document reviews remain specialized extension UI.
669
+ Their hints follow Pi's injected keybindings; list, detail, and exact-document content stay bounded across terminal resize.
670
+ Escape returns from detail or to the main menu, while Ctrl+C closes the whole workflow.
712
671
 
713
- The direct routes accept no trailing arguments. Status and help remain safe in TUI, RPC, JSON, and
714
- print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes
715
- produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
672
+ The direct routes accept no trailing arguments.
673
+ Status and help remain safe in TUI, RPC, JSON, and print modes.
674
+ RPC receives notifications but never opens custom terminal UI; print and JSON modes produce no ad hoc output.
675
+ Footer/timer/Git lifecycle work starts only in TUI mode.
716
676
 
717
677
  ## 📐 Scope
718
678
 
719
- The formatter, style concepts, and selected contextual modules are Starship-inspired, while Pi owns
720
- the lifecycle, snapshots, privacy boundary, and footer layout. This extension does not load
721
- `starship.toml`, claim complete module/config compatibility, invoke the Starship binary, run custom
722
- shell modules, or expose unrestricted `env_var` behavior. JVM/.NET, other long-tail languages,
723
- alternative VCS, system-monitor, and additional DevOps modules remain demand-gated; the first-wave
724
- review found no issue/discussion evidence for a coherent follow-up batch, so no second wave is added.
679
+ The formatter, style concepts, and selected contextual modules are Starship-inspired, while Pi owns the lifecycle, snapshots, privacy boundary, and footer layout.
680
+ This extension does not load `starship.toml`, claim complete module/config compatibility, invoke the Starship binary, run custom shell modules, or expose unrestricted `env_var` behavior.
681
+ JVM/.NET, other long-tail languages, alternative VCS, system-monitor, and additional DevOps modules remain demand-gated; the first-wave review found no issue/discussion evidence for a coherent follow-up batch, so no second wave is added.
725
682
 
726
- Pi-native model, context, cache, cost, Git metrics, and activity remain owned by the existing modules. The
727
- lifecycle design rejects provider-specific duplicates and ambiguous `turn_duration`/`last_result`
728
- modules until separately approved semantics exist.
683
+ Pi-native model, context, cache, cost, Git metrics, and activity remain owned by the existing modules.
684
+ The lifecycle design rejects provider-specific duplicates and ambiguous `turn_duration`/`last_result` modules until separately approved semantics exist.
729
685
 
730
686
  ## ➕ Adding a module
731
687
 
732
- Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`. Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog. Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
688
+ Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`.
689
+ Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog.
690
+ Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
733
691
 
734
692
  Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
735
693
 
@@ -741,7 +699,9 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
741
699
  - `src/pi-starship.ts` — authoritative extension lifecycle, cached refresh binding, live preview, and footer.
742
700
  - `src/usage.ts` — native-aligned session usage and cache aggregation.
743
701
  - `src/command-contract.ts` — lightweight command routes and completions loaded at startup.
744
- - `src/commands.ts` — lazily loaded menu, preview/confirmation flow, diagnostics, and compatibility routes.
702
+ - `src/commands.ts` — lazily loaded top-level menu, preview/confirmation workflows, and compatibility routes.
703
+ - `src/command-configuration.ts` — nested configuration presentation, exact document views, and safe runtime-only disk reload.
704
+ - `src/effective-config.ts` — explicit catalog-ordered public TOML projection and deterministic serialization.
745
705
  - `src/command-preset-picker.ts` — lifecycle-owned preset cursor and temporary footer-preview UI.
746
706
  - `src/presets/` — bundled complete TOML documents and stable preset metadata.
747
707
  - `src/command-inspector.ts` — adaptive Explain and searchable read-only module inspection surfaces.
@@ -756,9 +716,10 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
756
716
 
757
717
  ## 🔎 Keywords
758
718
 
759
- Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull
760
- request, prompt cache, cache hit rate, Pi extension
719
+ Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull request, prompt cache, cache hit rate, Pi extension
761
720
 
762
721
  ## 📄 License
763
722
 
764
- MIT. See [`LICENSE`](./LICENSE). Starship attribution and its ISC license are included in [`NOTICES.md`](./NOTICES.md).
723
+ MIT.
724
+ See [`LICENSE`](./LICENSE).
725
+ Starship attribution and its ISC license are included in [`NOTICES.md`](./NOTICES.md).