@narumitw/pi-starship 0.52.2 → 0.54.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.
package/README.md CHANGED
@@ -2,9 +2,8 @@
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
- Build a deeply customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout.
6
-
7
- No `starship` executable or shell prompt is required because this extension parses and renders the footer itself.
5
+ Build a customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout.
6
+ The extension parses and renders the footer itself, so it does not need the `starship` executable or a shell prompt.
8
7
 
9
8
  > **Different package:** The unscoped npm package `pi-starship` delegates to the Starship binary.
10
9
  > This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
@@ -38,15 +37,35 @@ npm --workspace @narumitw/pi-starship run build
38
37
  pi -e ./packages/pi-starship
39
38
  ```
40
39
 
41
- The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
42
-
43
- Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
40
+ The package declares `dist/index.ts`, so build an unbuilt local checkout before Pi loads the package directory.
41
+ Install only from sources you trust because Pi extensions run with Pi's permissions.
42
+ Do not enable this with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
44
43
 
45
44
  ## 🚀 Quick start
46
45
 
47
46
  Start Pi with the extension to use the built-in footer without creating a settings file.
48
47
  Run `/starship` to inspect the footer, choose a preset, or customize the configuration.
49
48
 
49
+ ## 💬 Commands
50
+
51
+ | Command | Purpose |
52
+ | --- | --- |
53
+ | `/starship` | Open the current-state menu in TUI mode; show help in RPC |
54
+ | `/starship settings` | Edit, preview, and confirm TOML in TUI; show the file path in RPC |
55
+ | `/starship status` | Show the configuration source, path, and diagnostics in TUI or RPC |
56
+ | `/starship help` | Show command and configuration help in TUI or RPC |
57
+
58
+ The main menu keeps seven actions on one level: **Customize footer**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
59
+ It shows the current source and configuration health.
60
+ Presets, Explain, Modules, and Configuration are menu-only; they do not add textual subcommands.
61
+ Restore is unavailable when there is no document to replace.
62
+
63
+ The TOML editor, live footer previews, Explain view, module inspector, and configuration reviews use specialized TUI screens.
64
+ Their content and key hints adapt to terminal width and Pi's configured keybindings.
65
+ Escape returns to the previous screen, while Ctrl+C closes the workflow.
66
+ Direct routes reject trailing arguments.
67
+ Print and JSON modes produce no ad hoc output, and footer lifecycle work runs only in TUI mode.
68
+
50
69
  ## ⚙️ Settings
51
70
 
52
71
  The only configuration source is:
@@ -55,7 +74,7 @@ The only configuration source is:
55
74
  <getAgentDir()>/pi-starship.toml
56
75
  ```
57
76
 
58
- When this file is absent, the extension uses its readable palette-free default without creating the file or parent directory.
77
+ When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
59
78
  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
79
  The first successful settings save creates the file atomically.
61
80
  Existing malformed documents are never overwritten.
@@ -69,24 +88,23 @@ Open the interactive menu in TUI mode:
69
88
  ```
70
89
 
71
90
  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.
91
+ Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
92
+ Saving requires separate confirmation, then atomically updates the file and active footer.
93
+ Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
94
+ Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
77
95
 
78
96
  The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
79
97
  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
98
  Modules opens a bounded searchable inspector for every registered module.
81
99
  Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
82
100
  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.
101
+ Both views are read-only and do not create or update the settings document.
84
102
 
85
103
  Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
86
104
  Overview combines state, source, path, health, and bounded diagnostics.
87
105
  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
106
  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.
107
+ A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
90
108
  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
109
  A deleted document is a valid previewable transition to built-in defaults and creates no file.
92
110
  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.
@@ -116,16 +134,15 @@ Colors, separators, typography, and layout follow the named Starship preset; mod
116
134
  | **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
117
135
  | **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
118
136
 
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.
137
+ Moving through the preset picker temporarily renders the selected preset in the footer without writing settings or starting collectors.
138
+ Press Enter to confirm replacement, or press `e` to edit the selected complete TOML document before preview and confirmation.
139
+ Escape returns to the main menu, while Ctrl+C closes the workflow; both restore the active footer.
123
140
 
124
141
  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.
142
+ After confirmation, applying one replaces all of `pi-starship.toml`, including custom settings, unknown fields, and comments; no backup is kept.
143
+ Cancellation, disposal, validation failure, write failure, and runtime-apply failure preserve the previous document and footer.
144
+ An exact match is **Currently applied** and cannot be selected again; editing any byte makes it custom.
145
+ Use **Restore built-in…** for deterministic recovery.
129
146
 
130
147
  The bundled presets use only pi-starship's local Pi and Git snapshot modules.
131
148
  They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
@@ -200,6 +217,7 @@ icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
200
217
  Every module table supports `format`, `symbol`, and `disabled`.
201
218
  Most modules also support one `style`.
202
219
  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.
220
+ `thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
203
221
  Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
204
222
  Version formats replace `$raw`.
205
223
  Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
@@ -209,8 +227,9 @@ Icon matching uses the exact key, the longest `:*` wildcard, a leading status em
209
227
  An empty configured icon suppresses only the icon.
210
228
  `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
211
229
 
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.
230
+ Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
231
+ pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
232
+ Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
214
233
 
215
234
  **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`.
216
235
 
@@ -232,7 +251,7 @@ Module output keeps its own style when embedded in an outer styled group.
232
251
  Style expressions support:
233
252
 
234
253
  - Named colors and ANSI numbers `0`–`255`.
235
- - Hex RGB (`#7aa2f7`).
254
+ - Hex RGB (`#7aa2f7`), rendered as ANSI-256 when Pi's effective terminal capabilities disable true color.
236
255
  - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
237
256
  - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
238
257
  - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
@@ -262,9 +281,25 @@ Invalid literal style expressions warn and render unstyled.
262
281
  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
282
  `/starship status` reports warnings.
264
283
 
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"`.
284
+ 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"`.
266
285
  Context, cost, Git metrics, and username use the state/multi-style defaults below.
267
286
 
287
+ ### Thinking level styles
288
+
289
+ `thinking` can override its appearance for `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` independently:
290
+
291
+ ```toml
292
+ [thinking]
293
+ style = "bold purple"
294
+ style_low = "bold blue"
295
+ style_high = "bold yellow"
296
+ style_max = "bold red"
297
+ ```
298
+
299
+ The matching `style_<level>` wins when it is non-empty.
300
+ Every unset or empty level override uses the existing `style`, including levels added by a future Pi release.
301
+ Invalid fallback and level styles warn and fall back independently without changing other levels.
302
+
268
303
  ### State-selected styles
269
304
 
270
305
  `context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
@@ -325,7 +360,7 @@ There is no hidden compatibility overlay or automatic migration.
325
360
  | `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
326
361
  | `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
327
362
  | `git_status` | `$symbol`, `$all_status`, `$ahead_behind`, `$ahead`, `$behind`, `$diverged`, `$up_to_date`, `$conflicted`, `$stashed`, `$deleted`, `$renamed`, `$modified`, `$typechanged`, `$staged`, `$untracked`, and detailed index/worktree counters | Cached porcelain-v2 counters |
328
- | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$text` | Active tools, streaming, completion, or idle |
363
+ | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
329
364
  | `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
330
365
  | `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
331
366
  | `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
@@ -360,6 +395,8 @@ There is no hidden compatibility overlay or automatic migration.
360
395
 
361
396
  ### Usage semantics
362
397
 
398
+ - During a blocking extension UI prompt, `activity` sets `$state` to `waiting`, `$kind` to the prompt kind, and `$title` to the sanitized bounded title or an empty string.
399
+ - Prompt waiting takes precedence without losing the underlying tool, streaming, completed, or idle state, which returns when the prompt closes.
363
400
  - `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
364
401
  This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
365
402
  - Cache `$read` and `$write` are cumulative.
@@ -373,7 +410,6 @@ There is no hidden compatibility overlay or automatic migration.
373
410
  The module name remains `context`, not `context_usage`.
374
411
  - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
375
412
  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.
377
413
 
378
414
  ### Directory, Git, and environment contraction
379
415
 
@@ -421,7 +457,7 @@ Hostname trimming runs before exact alias lookup, matching Starship.
421
457
  These transformations affect display only.
422
458
  Collectors retain bounded, control-sanitized source metadata.
423
459
 
424
- ### Model aliases and truncation
460
+ ### Model and provider aliases and model truncation
425
461
 
426
462
  The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
427
463
 
@@ -437,9 +473,19 @@ An exact alias is selected before the built-in Claude/GPT shortening rules, then
437
473
  `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
438
474
  The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
439
475
  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.
476
+ Truncation changes display only; the provider model ID is untouched.
441
477
  Terminal control sequences in model IDs and truncation symbols are removed at render time.
442
478
  An empty symbol truncates without a marker.
479
+
480
+ The provider module accepts exact display aliases without changing the selected provider or model:
481
+
482
+ ```toml
483
+ [provider]
484
+ provider_aliases = { "openai-codex" = "codex", "amazon-bedrock" = "bedrock" }
485
+ ```
486
+
487
+ An empty alias hides only the provider text.
488
+ Provider names and aliases are stripped of terminal controls at render time.
443
489
  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
490
  pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
445
491
 
@@ -452,6 +498,8 @@ In a linked worktree it defaults to the top-level directory name; use `$path` wh
452
498
  Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
453
499
  `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
454
500
 
501
+ ## 🔒 Security and privacy
502
+
455
503
  ### 🔎 Native GitHub pull requests
456
504
 
457
505
  `$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
@@ -473,7 +521,7 @@ It never mutates Pi's environment, calls the GitHub API directly, or manages tok
473
521
  Variables have these values:
474
522
 
475
523
  - `$number`: digits such as `123`.
476
- - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
524
+ - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL when Pi's effective terminal capabilities enable hyperlinks, otherwise plain `#123`.
477
525
  - `$state`: `open`, `draft`, `merged`, or `closed`.
478
526
  - `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
479
527
  - `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty when unknown.
@@ -532,7 +580,7 @@ Branch changes clear the old PR before querying the new branch.
532
580
  Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
533
581
  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.
534
582
 
535
- The query sends the repository/current-branch context through authenticated `gh` to the GitHub host configured by the repository.
583
+ The query sends the repository and current branch through authenticated `gh` to the repository's configured GitHub host.
536
584
  It requests only the fields above—never comments, review bodies, inline comments, or review threads.
537
585
  Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
538
586
 
@@ -577,8 +625,8 @@ Names and paths are control-sanitized and bounded before publication.
577
625
  ### 🚢 Deployment and cloud context
578
626
 
579
627
  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.
628
+ They do **not** contact Docker, Kubernetes, Terraform/OpenTofu backends, cloud APIs, OAuth flows, credential helpers, or metadata services.
629
+ They remain opt-in because context labels may be sensitive.
582
630
 
583
631
  - `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
584
632
  The `default` context is suppressed.
@@ -613,6 +661,8 @@ Negated username detection names are rejected.
613
661
  Ordinary local hostname/username sessions stay empty.
614
662
  All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
615
663
 
664
+ ## 📐 Layout and lifecycle
665
+
616
666
  ### ↔️ Fill layout
617
667
 
618
668
  Add `${fill}` between left and right root content (braces disambiguate adjacent text):
@@ -646,48 +696,23 @@ Bounded local filesystem operations may finish, but stale generations cannot pub
646
696
  Execution identity is retained rather than re-read by the periodic fallback.
647
697
  Render and live preview consume snapshots synchronously and perform zero reads or commands.
648
698
 
649
- Missing, unreadable, malformed, oversized, timed-out, or unavailable sources fail to empty values.
650
- Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
699
+ Missing, unreadable, malformed, oversized, timed-out, or unavailable sources produce empty values.
700
+ Workspace and Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
651
701
  The native GitHub PR query is the documented network exception.
652
- Package's explicitly documented Cargo lookup is the only ancestor walk and is capped at eight parents.
653
-
654
- ## 💬 Commands
655
-
656
- | Command | Purpose |
657
- | --- | --- |
658
- | `/starship` | Open the current-state menu in TUI mode; retain help behavior outside TUI |
659
- | `/starship settings` | Open the compatible direct edit → preview → confirm flow (TUI only) |
660
- | `/starship status` | Show config source/path and diagnostics |
661
- | `/starship help` | Show command and configuration help |
662
-
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.
667
-
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.
671
-
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.
676
-
677
- ## 📐 Scope
702
+ The Cargo package lookup is the only ancestor walk and stops after eight parents.
678
703
 
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.
704
+ ## 🚧 Limitations
682
705
 
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.
706
+ - The formatter and modules are Starship-inspired, not fully compatible with Starship.
707
+ - The extension does not load `starship.toml`, invoke the Starship binary, run custom shell modules, or provide unrestricted `env_var` behavior.
708
+ - JVM/.NET, other long-tail languages, alternative version-control systems, system monitoring, and additional DevOps modules are not implemented.
709
+ - Pi does not expose the auto-compaction toggle, so the footer cannot reliably show Pi's native `(auto)` marker.
685
710
 
686
711
  ## ➕ Adding a module
687
712
 
688
713
  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
714
  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.
715
+ Add the module to the built-in root format only when it should be visible by default, then document and test its user-facing values.
691
716
 
692
717
  Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
693
718