@narumitw/pi-starship 0.52.3 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +53 -622
  2. package/dist/chunks/{chunk-6D6VEVE5.js → chunk-UX6PBXVK.js} +125 -26
  3. package/dist/chunks/chunk-UX6PBXVK.js.map +7 -0
  4. package/dist/chunks/{cloud-GEBXIN43.js → cloud-BKHYWCTA.js} +3 -3
  5. package/dist/chunks/cloud-BKHYWCTA.js.map +7 -0
  6. package/dist/chunks/{commands-T73QN435.js → commands-53ZO2JUK.js} +3 -2
  7. package/dist/chunks/{commands-T73QN435.js.map → commands-53ZO2JUK.js.map} +2 -2
  8. package/dist/chunks/{development-TOXV7LWE.js → development-BERD42HW.js} +2 -2
  9. package/dist/chunks/{development-TOXV7LWE.js.map → development-BERD42HW.js.map} +2 -2
  10. package/dist/chunks/{execution-QDYHQKST.js → execution-42JTEY3N.js} +2 -2
  11. package/dist/chunks/{execution-QDYHQKST.js.map → execution-42JTEY3N.js.map} +2 -2
  12. package/dist/chunks/{languages-QR3XPRVQ.js → languages-RMP6DW7H.js} +2 -2
  13. package/dist/chunks/languages-RMP6DW7H.js.map +7 -0
  14. package/dist/index.ts +31 -10
  15. package/dist/index.ts.map +3 -3
  16. package/package.json +14 -12
  17. package/skills/configuring-pi-starship/SKILL.md +113 -0
  18. package/skills/configuring-pi-starship/references/configuration.md +365 -0
  19. package/skills/configuring-pi-starship/references/module-catalog.md +978 -0
  20. package/skills/configuring-pi-starship/references/modules.md +230 -0
  21. package/skills/configuring-pi-starship/references/runtime-and-security.md +213 -0
  22. package/skills/configuring-pi-starship/scripts/apply.mjs +64 -0
  23. package/skills/configuring-pi-starship/scripts/config-path.mjs +11 -0
  24. package/skills/configuring-pi-starship/scripts/script-support.mjs +20 -0
  25. package/skills/configuring-pi-starship/scripts/validate.mjs +30 -0
  26. package/src/config.ts +9 -0
  27. package/src/effective-config.ts +1 -0
  28. package/src/format/style.ts +14 -6
  29. package/src/modules/activity.ts +57 -4
  30. package/src/modules/catalog.ts +2 -2
  31. package/src/modules/provider.ts +19 -1
  32. package/src/modules/render.ts +2 -1
  33. package/src/modules/thinking.ts +24 -0
  34. package/src/modules/types.ts +3 -0
  35. package/src/pi-starship.ts +24 -3
  36. package/src/runtime/cloud.ts +3 -2
  37. package/src/runtime/development.ts +1 -1
  38. package/src/runtime/execution.ts +1 -1
  39. package/src/runtime/github-pr.ts +2 -1
  40. package/src/runtime/languages.ts +1 -1
  41. package/dist/chunks/chunk-6D6VEVE5.js.map +0 -7
  42. package/dist/chunks/cloud-GEBXIN43.js.map +0 -7
  43. package/dist/chunks/languages-QR3XPRVQ.js.map +0 -7
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: configuring-pi-starship
3
+ description: Configure @narumitw/pi-starship and answer questions about its pi-starship.toml settings. Use when the user asks to create, edit, repair, migrate, or understand pi-starship.toml, or asks which pi-starship module, variable, option, style, palette, preset, or runtime behavior to use. Do not use for generic TOML, shell Starship configuration, pi-starship source-code development, or unrelated footer work.
4
+ license: MIT
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ # Configuring pi-starship
9
+
10
+ Answer pi-starship configuration questions or make the requested `pi-starship.toml` change.
11
+
12
+ ## Choose the task path
13
+
14
+ For a configuration question, load only the smallest relevant reference and answer with the exact supported names, values, defaults, and behavior.
15
+
16
+ Do not read or modify the user's settings file for a question that the references can answer directly.
17
+
18
+ For a configuration edit, inspect the existing document and follow the editing and validation workflow below.
19
+
20
+ Treat the bundled references and implementation as authoritative instead of assuming compatibility with shell Starship.
21
+
22
+ If the references do not answer a question, inspect the bundled source relative to this skill.
23
+
24
+ Use `../../src/config.ts` for parsing, defaults, validation, and persistence behavior.
25
+
26
+ Use `../../src/modules/catalog.ts`, `../../src/modules/types.ts`, and the relevant `../../src/modules/*.ts` file for module variables, options, defaults, and runtime values.
27
+
28
+ Use `../../src/presets/` for the exact bundled preset documents.
29
+
30
+ State clearly when an answer comes from implementation detail rather than a documented public configuration surface.
31
+
32
+ ## Load configuration references
33
+
34
+ Read [configuration and format](references/configuration.md) for settings location and persistence, presets, complete examples, root and module formats, styles, palettes, and display thresholds.
35
+
36
+ Read [the complete module catalog](references/module-catalog.md) for exact module names, format variables, default formats, symbols, enabled state, style fields, display defaults, option types, ranges, and enum values.
37
+
38
+ For one module, search that catalog for its exact `### \`module_name\`` heading and read only through the next module heading.
39
+
40
+ Read [module behavior](references/modules.md) for output semantics, detection defaults, aliases, truncation, and module-specific behavior.
41
+
42
+ Read [runtime and security](references/runtime-and-security.md) before enabling or explaining network, command-backed, development, cloud, deployment, host, user, or width-sensitive modules, and when checking limitations.
43
+
44
+ ## Locate and inspect an editable document
45
+
46
+ Use an explicit user-provided path when present.
47
+
48
+ Otherwise resolve the active path through Pi's `getAgentDir()` API by running `node scripts/config-path.mjs` relative to this `SKILL.md`.
49
+
50
+ The resolver prints a JSON string containing the exact absolute path, including correct expansion of a configured `~`.
51
+
52
+ Read the existing document before editing it.
53
+
54
+ Treat a missing document as built-in defaults, and create it only when the requested change requires a persisted configuration.
55
+
56
+ Do not redirect this workflow to `starship.toml`, `pi-statusline.json`, project-local overrides, or extension source files.
57
+
58
+ ## Make the smallest valid change
59
+
60
+ Preserve comments, ordering, unknown fields, and unrelated custom settings unless the user explicitly requests a complete replacement.
61
+
62
+ Keep the root `format` limited to module names and `$all`.
63
+
64
+ Keep each module's `format` limited to that module's documented variables and style variables.
65
+
66
+ When adding a module, make it reachable from the root `format` or `$all`, and set `disabled = false` when the module is disabled by default.
67
+
68
+ Use pi-starship's documented format grammar and supported module options.
69
+
70
+ Do not add shell commands, unrestricted environment-variable modules, or unsupported Starship fields.
71
+
72
+ Do not enable network, command-backed, cloud, deployment, host, or user metadata beyond the user's request.
73
+
74
+ Preserve an existing malformed document while diagnosing it, and change only the bytes needed to repair the requested problem.
75
+
76
+ ## Validate and hand off an edit
77
+
78
+ Create a separate draft without changing the active document, then make the smallest requested edit in that draft.
79
+
80
+ When the active document exists, also keep an untouched baseline file containing the exact bytes initially inspected.
81
+
82
+ When it is missing, use the explicit `--expect-missing` state instead of creating a baseline.
83
+
84
+ Resolve the bundled scripts relative to this `SKILL.md`, validate the draft, and publish it through the guarded atomic apply script:
85
+
86
+ ```bash
87
+ skill_dir="<directory containing this SKILL.md>"
88
+ draft_path="<path to the proposed pi-starship.toml draft>"
89
+ config_path="<absolute path to the active pi-starship.toml>"
90
+ expected_state="<path to the untouched baseline, or --expect-missing>"
91
+ node "$skill_dir/scripts/validate.mjs" "$draft_path"
92
+ node "$skill_dir/scripts/apply.mjs" "$draft_path" "$config_path" "$expected_state"
93
+ ```
94
+
95
+ The apply script stages the proposed bytes in the destination directory, validates that staged file, and immediately re-reads the active path.
96
+
97
+ It rejects publication when the active bytes differ from the baseline or when a supposedly missing document has appeared, then renames the staged file over the unchanged path.
98
+
99
+ This comparison does not lock out other processes after the re-read, so do not claim cross-process synchronization.
100
+
101
+ Fix every TOML syntax error and rerun the validator unless the user explicitly requested an invalid test fixture, which must not replace the active document.
102
+
103
+ Remove the separate draft and baseline after a successful publication, then re-read the saved document and review the exact change for accidental replacement or unrelated edits.
104
+
105
+ Report the edited path, the effective layout or module change, and the validator and atomic-publication results.
106
+
107
+ External edits do not update an active footer immediately.
108
+
109
+ When the pi-starship extension and `/starship status` command are available, tell the user to run `/reload` and inspect `/starship status` for semantic warnings.
110
+
111
+ When the extension or command is unavailable, report that only standalone TOML syntax and atomic publication were verified.
112
+
113
+ Do not claim semantic validation or an active-footer update unless that runtime verification actually occurred.
@@ -0,0 +1,365 @@
1
+ # Configuration and Format Reference
2
+
3
+ Use this authoritative public reference for configuration location and persistence, presets, complete-document examples, format grammar, styles, palettes, and state-selected styles.
4
+
5
+ ## ⚙️ Settings
6
+
7
+ The only configuration source is:
8
+
9
+ ```text
10
+ <getAgentDir()>/pi-starship.toml
11
+ ```
12
+
13
+ When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
14
+ The built-in root is the explicit sequence `$brand$model$thinking$directory` `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query.
15
+ The first successful settings save creates the file atomically.
16
+ Existing malformed documents are never overwritten.
17
+
18
+ The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
19
+
20
+ Open the interactive menu in TUI mode:
21
+
22
+ ```text
23
+ /starship
24
+ ```
25
+
26
+ Choose **Customize footer** to edit the TOML.
27
+ Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
28
+ Saving requires separate confirmation, then atomically updates the file and active footer.
29
+ Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
30
+ Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
31
+
32
+ The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
33
+ 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.
34
+ Modules opens a bounded searchable inspector for every registered module.
35
+ Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
36
+ 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.
37
+ Both views are read-only and do not create or update the settings document.
38
+
39
+ Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
40
+ Overview combines state, source, path, health, and bounded diagnostics.
41
+ 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.
42
+ Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
43
+ A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
44
+ 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.
45
+ A deleted document is a valid previewable transition to built-in defaults and creates no file.
46
+ 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.
47
+ 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.
48
+ Restore is disabled when no settings document exists or the exact built-in document is already saved.
49
+ 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.
50
+
51
+ ### 🎛️ Presets
52
+
53
+ Choose **Presets** from `/starship` to browse complete Pi-native starting points.
54
+ The catalog adapts all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
55
+ 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.
56
+
57
+ | Preset | Adapted visual treatment | Font requirement |
58
+ | --- | --- | --- |
59
+ | **Minimal** | Compact Pi essentials | Standard Unicode |
60
+ | **Bracketed Segments** | Balanced Pi and Git information in brackets | Standard Unicode |
61
+ | **Catppuccin Powerline** | Connected Catppuccin Mocha blocks; other Catppuccin palettes remain in the document for customization | Nerd Font |
62
+ | **Gruvbox Rainbow** | Warm Gruvbox connected segments | Nerd Font |
63
+ | **Jetpack** | Airy geometric activity/context and workspace columns joined by fill | Standard Unicode |
64
+ | **Nerd Font Symbols** | Balanced default layout with icon-rich symbols | Nerd Font |
65
+ | **No Empty Icons** | Conditional text labels that cannot appear without their values | Standard Unicode |
66
+ | **No Nerd Font** | Portable Unicode symbols without private-use glyphs | Standard Unicode |
67
+ | **No Runtime Versions** | Presence indicators without model or thinking details | Standard Unicode |
68
+ | **Pastel Powerline** | Connected magenta, coral, orange, blue, teal, and navy blocks | Nerd Font |
69
+ | **Plain Text Symbols** | Plain words replace pictograms | Standard Unicode |
70
+ | **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
71
+ | **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
72
+
73
+ Moving through the preset picker temporarily renders the selected preset in the footer without writing settings or starting collectors.
74
+ Press Enter to confirm replacement, or press `e` to edit the selected complete TOML document before preview and confirmation.
75
+ Escape returns to the main menu, while Ctrl+C closes the workflow; both restore the active footer.
76
+
77
+ Presets are complete documents, not overlays.
78
+ After confirmation, applying one replaces all of `pi-starship.toml`, including custom settings, unknown fields, and comments; no backup is kept.
79
+ Cancellation, disposal, validation failure, write failure, and runtime-apply failure preserve the previous document and footer.
80
+ An exact match is **Currently applied** and cannot be selected again; editing any byte makes it custom.
81
+ Use **Restore built-in…** for deterministic recovery.
82
+
83
+ The bundled presets use only pi-starship's local Pi and Git snapshot modules.
84
+ They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
85
+ 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.
86
+ There is no `/starship preset` textual route and no remote preset download.
87
+
88
+ ### 📝 Example
89
+
90
+ ```toml
91
+ format = """
92
+ $brand\
93
+ $model\
94
+ $thinking\
95
+ $directory\
96
+ $git_branch\
97
+ $git_status\
98
+ $activity\
99
+ $context\
100
+ $time"""
101
+
102
+ [model]
103
+ format = "[ $symbol$model ]($style)"
104
+ symbol = "◆ "
105
+ style = "bold blue"
106
+ truncation_length = 36
107
+ truncation_symbol = "…"
108
+ truncation_direction = "middle"
109
+
110
+ [directory]
111
+ style = "cyan bold"
112
+
113
+ [git_branch]
114
+ style = "bold purple"
115
+
116
+ [context]
117
+ format = "[$symbol $percentage/$window ]($style)"
118
+
119
+ [[context.display]]
120
+ threshold = 0
121
+ style = "bold green"
122
+ hidden = true
123
+
124
+ [[context.display]]
125
+ threshold = 30
126
+ style = "bold green"
127
+ hidden = false
128
+
129
+ [[context.display]]
130
+ threshold = 60
131
+ style = "bold yellow"
132
+ hidden = false
133
+
134
+ [[context.display]]
135
+ threshold = 80
136
+ style = "bold red"
137
+ hidden = false
138
+
139
+ [git_metrics]
140
+ added_style = "bold green"
141
+ deleted_style = "bold red"
142
+ disabled = false
143
+
144
+ [username]
145
+ style_user = "yellow bold"
146
+ style_root = "red bold"
147
+
148
+ [extension_status]
149
+ format = "([$statuses ]($style))"
150
+ icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
151
+ ```
152
+
153
+ Every module table supports `format`, `symbol`, and `disabled`.
154
+ Most modules also support one `style`.
155
+ 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.
156
+ `thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
157
+ Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
158
+ Version formats replace `$raw`.
159
+ Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
160
+ A leading `!` is supported by language detection arrays and rejects a matching project.
161
+ `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
162
+ Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
163
+ An empty configured icon suppresses only the icon.
164
+ `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
165
+
166
+ Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
167
+ pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
168
+ Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
169
+
170
+ **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`.
171
+
172
+ ## Configuration schema and validation
173
+
174
+ ### Root fields
175
+
176
+ A settings document is one TOML table with these accepted root keys:
177
+
178
+ | Key | Type | Behavior |
179
+ | --- | --- | --- |
180
+ | `format` | string | Root layout whose variables are module names or `$all`. |
181
+ | `palette` | string | Selects one exact table name from `[palettes.<name>]`. |
182
+ | `palettes` | table of tables | Defines direct color names used by style expressions. |
183
+ | `<module>` | table | Configures one module listed in [the complete module catalog](module-catalog.md). |
184
+
185
+ Unknown root keys produce warnings and remain inactive.
186
+ The loader normalizes `palettes` before resolving `palette`, so their textual order in TOML does not matter.
187
+ An unknown selected palette warns and supplies no custom colors.
188
+
189
+ ### Shared module fields
190
+
191
+ Every module table accepts `format`, `symbol`, and `disabled`.
192
+ The exact accepted style fields, display arrays, module-specific options, defaults, enum values, and numeric ranges are listed in [the complete module catalog](module-catalog.md).
193
+
194
+ `format` and `symbol` must be strings.
195
+ `disabled` must be boolean.
196
+ A standard `style` field must be a valid style string.
197
+ `thinking` accepts `style` plus `style_off`, `style_minimal`, `style_low`, `style_medium`, `style_high`, `style_xhigh`, and `style_max`.
198
+ `git_metrics` accepts `added_style` and `deleted_style` instead of `style`.
199
+ `username` accepts `style_user` and `style_root` instead of `style`.
200
+ `context` and `cost` accept `display` arrays instead of a direct `style` field.
201
+
202
+ `[[context.display]]` and `[[cost.display]]` entries require these typed fields:
203
+
204
+ ```toml
205
+ threshold = 60 # finite number
206
+ style = "bold yellow" # valid style string
207
+ hidden = false # boolean
208
+ ```
209
+
210
+ Unknown display fields warn.
211
+ Invalid display entries are discarded independently.
212
+ When no valid entries remain, the complete module display default is restored.
213
+
214
+ `extension_status` additionally accepts `separator`, `max_statuses`, and `icons`.
215
+ `separator` is a string, `max_statuses` is an integer from 0 through 100, and `icons` is a string-to-string table.
216
+
217
+ ### Module option types
218
+
219
+ Module-specific options use these validation rules:
220
+
221
+ | Type | Accepted value |
222
+ | --- | --- |
223
+ | string | A TOML string; options marked non-empty reject `""`. |
224
+ | string enum | An exact case-sensitive listed string. |
225
+ | boolean | A TOML boolean, not a quoted string. |
226
+ | integer | An integer inside the inclusive range listed in the module catalog. |
227
+ | string array | An array containing only non-empty strings. |
228
+ | string-to-string table | A TOML table whose values are all strings. |
229
+
230
+ Language `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
231
+ Other string-array options reject entries beginning with `!`.
232
+ Detection fallback and replacement behavior differs by module and is specified in [module behavior](modules.md).
233
+
234
+ ### Diagnostic and fallback behavior
235
+
236
+ | Failure | Result |
237
+ | --- | --- |
238
+ | Missing file | Use built-in defaults without creating a file or directory. |
239
+ | Read failure | Use built-in defaults and report an error diagnostic. |
240
+ | TOML syntax failure | Preserve the raw document, use built-in defaults, and report an error diagnostic. |
241
+ | Unknown root, module, option, or display field | Warn, ignore that field, and keep processing the document. |
242
+ | Wrong field type | Warn and retain the default for that field. |
243
+ | Invalid root `format` | Warn and restore only the built-in root format. |
244
+ | Invalid module `format` | Warn and restore only that module's default format. |
245
+ | Unknown format or style variable | Warn and render that variable empty. |
246
+ | Invalid literal group style | Warn and render that group unstyled. |
247
+ | Invalid module style field | Warn and restore only that style field's module default. |
248
+ | Invalid palette color | Warn and omit only that palette entry. |
249
+ | Invalid module option | Warn and restore only that option's default. |
250
+ | Invalid display entry | Warn and discard only that entry; restore defaults if none remain. |
251
+
252
+ TOML syntax and read failures are errors that block interactive saving or reload application.
253
+ Semantic warnings do not prevent a document from loading or being saved, but `/starship status` reports them.
254
+ Unknown fields and comments remain in the settings document even though they are excluded from the normalized effective configuration.
255
+
256
+ ## 🧩 Format grammar
257
+
258
+ - Variables: `$name` and `${name}`.
259
+ Unknown variables render empty and produce a warning when loaded from TOML.
260
+ - Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
261
+ - Styled groups: `[format string](style string)`.
262
+ - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
263
+ - Nested groups are supported.
264
+ - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
265
+
266
+ Module formats can use `$style` in a style expression.
267
+ Module output keeps its own style when embedded in an outer styled group.
268
+
269
+ ## 🎨 Styles and palettes
270
+
271
+ Style expressions support:
272
+
273
+ - Named colors and ANSI numbers `0`–`255`.
274
+ - Hex RGB (`#7aa2f7`), rendered as ANSI-256 when Pi's effective terminal capabilities disable true color.
275
+ - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
276
+ - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
277
+ - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
278
+ - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same Starship-compatible reset behavior.
279
+ - `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.
280
+ - Direct color names from one explicitly selected `[palettes.<name>]` table.
281
+
282
+ There is no built-in or fallback palette.
283
+ 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.
284
+ Palette names override terminal color names such as `blue`:
285
+
286
+ ```toml
287
+ palette = "company"
288
+
289
+ [palettes.company]
290
+ blue = "#86BBD8"
291
+ accent = "208"
292
+
293
+ [model]
294
+ style = "bold blue"
295
+ ```
296
+
297
+ Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
298
+ `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
299
+ Empty styled groups still advance previous-color state.
300
+ Invalid literal style expressions warn and render unstyled.
301
+ 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.
302
+ `/starship status` reports warnings.
303
+
304
+ 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"`.
305
+ Context, cost, Git metrics, and username use the state/multi-style defaults below.
306
+
307
+ ### Thinking level styles
308
+
309
+ `thinking` can override its appearance for `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` independently:
310
+
311
+ ```toml
312
+ [thinking]
313
+ style = "bold purple"
314
+ style_low = "bold blue"
315
+ style_high = "bold yellow"
316
+ style_max = "bold red"
317
+ ```
318
+
319
+ The matching `style_<level>` wins when it is non-empty.
320
+ Every unset or empty level override uses the existing `style`, including levels added by a future Pi release.
321
+ Invalid fallback and level styles warn and fall back independently without changing other levels.
322
+
323
+ ### State-selected styles
324
+
325
+ `context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
326
+ A later entry wins when thresholds are equal.
327
+ Each display entry requires a finite `threshold`, a valid `style`, and boolean `hidden`.
328
+ Invalid entries warn and are ignored; module defaults are used if none remain.
329
+
330
+ The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and `bold red` at `80`.
331
+ The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red` at `5`:
332
+
333
+ ```toml
334
+ [[cost.display]]
335
+ threshold = 0
336
+ style = "bold green"
337
+ hidden = true
338
+
339
+ [[cost.display]]
340
+ threshold = 1
341
+ style = "bold yellow"
342
+ hidden = false
343
+
344
+ [[cost.display]]
345
+ threshold = 5
346
+ style = "bold red"
347
+ hidden = false
348
+ ```
349
+
350
+ `git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
351
+ `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.
352
+
353
+ ### Breaking palette migration
354
+
355
+ 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.
356
+ Existing files are not rewritten.
357
+ 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.
358
+
359
+ Choose one migration:
360
+
361
+ 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
362
+ 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
363
+ 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
364
+
365
+ There is no hidden compatibility overlay or automatic migration.