pi-fold 4.1.5 → 4.1.6

package/README.md

@@ -37,14 +37,14 @@ In an interactive session one compact, full-height bar sits directly above Pi's
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-dark.svg">
-  <img alt="A single full-height usage bar. Batlow colours group consolidated folds, span folds, tool folds, pinned content, marked content, and raw context in that order. The suffix shows percentage, commit point, and fold, pin, and mark counts." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
+  <img alt="A single full-height usage bar. Batlow colours group consolidated folds, span folds, tool folds, marked content, raw context and pinned content in that order. The suffix shows percentage, commit point, and fold, mark, and pin counts." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
 </picture>
 
-The forty-column bar uses full-height half-blocks for eighty steps of fill, following the provider's measured count against the serving budget. Within that fill, colours show the estimated visible composition, grouped in this order: **Consolidated Folds, Span Folds, Tool Folds, Pinned, Marked, Raw**. Compressed content uses the first half of [Crameri's Batlow palette](https://www.fabiocrameri.ch/colourmaps/); still-raw content uses the second half. Foreground lightness is adjusted for dark and light backgrounds, and label colours match the bar. Each nonempty category keeps at least one half-cell when the measured fill has room; remaining width follows relative mass. This visibility floor makes small compressed categories visible, so individual category widths are not token-exact. At very low occupancy, the largest shares take the available space. There are no individual fold edges, scores, or height differences.
+The forty-column bar uses full-height half-blocks for eighty steps of fill, following the provider's measured count against the serving budget. Within that fill, colours show the estimated visible composition, grouped by distance from compression: **Consolidated Folds, Span Folds, Tool Folds, Marked, Raw, Pinned**. The first three are compressed now, deepest first; marked content folds at the next commit; raw content is eligible later; pinned content is held against every commit until released. The six shades, from consolidated to pinned, are read off a colour map, [Crameri's Batlow](https://www.fabiocrameri.ch/colourmaps/) end to end by default, so the bar reads as a gradient from most compressed to most settled. `/fold-settings` offers Batlow, viridis, plasma, magma and cividis, and where on the chosen map the two ends sit, so a slice of a map or a reversed one is a keypress away; the bar repaints on each step. Whatever the choice, each shade's lightness is moved away from the background, hue held, until it clears 4.5:1 on dark and light terminals, and label colours match the bar. Each nonempty category keeps at least one half-cell when the measured fill has room; remaining width follows relative mass. This visibility floor makes small compressed categories visible, so individual category widths are not token-exact. At very low occupancy, the largest shares take the available space. There are no individual fold edges, scores, or height differences.
 
-The suffix reads `34% · commit at 55% · N Folds (X Cons., Y Span, Z Tool, X Pin, Y Mark)`. `N Folds` counts visible compressed folds; `Pin` counts protected entries and `Mark` counts pending marks, not additional compressed folds. A tool fold is lossless compression of tool-result context, not a count of tool calls. `/fold-status` retains the detailed token and nesting figures.
+The suffix reads `34% · commit at 55% · N Folds (X Cons., Y Span, Z Tool, X Mark, Y Pin)`, naming only the kinds with something to count, in the bar's order; a fresh session reads `0 Folds`. `N Folds` counts visible compressed folds; `Mark` counts pending marks and `Pin` counts protected entries, not additional compressed folds. A tool fold is lossless compression of tool-result context, not a count of tool calls. `/fold-status` retains the detailed token and nesting figures.
 
-Matching dashed guides show `minTarget`, where a commit aims to land, and `maxTarget`, where automatic folding is triggered. Before a measurement the row says `not measured yet`; after a commit it identifies the old reading until the provider measures again. Crossing the target is routine runtime work, not a user action item. On reload, saved session context supplies the fold counts and composition without a new model message; the next real context event replaces that read-only view. Unavailable composition is stated as `mapping`; if folding stops, `FOLDING STOPPED` replaces the bar. Non-truecolor terminals use the theme's own colours.
+Two dotted marks stand in the band's edge cells: one at `minTarget`, where a commit aims to land, and one at `maxTarget`, where automatic folding is triggered. Each is drawn over the fill's own colour in a deeper tone of that same hue, so the fill continues behind the mark; on the empty track they stand in muted ink. Neither takes a colour of its own or a warning colour. Before a measurement the row says `not measured yet`; after a commit it identifies the old reading until the provider measures again. Crossing the target is routine runtime work, not a user action item. On reload, saved session context supplies the fold counts and composition without a new model message; the next real context event replaces that read-only view. Unavailable composition is stated as `mapping`; if folding stops, `FOLDING STOPPED` replaces the bar. Non-truecolor terminals use the theme's own colours.
 
 ## Results
 
@@ -80,7 +80,7 @@ Four papers with figure sources, redacted per-request ledgers and campaign logs
 
 The one thing worth adding is a long-term memory store. Rotation and retention are different jobs: folding gets stale material out of the window, a store keeps what the session learned. A handoff summary tries to do both in one record, written once under time pressure, bounded by the window it has to fit in. Folding is the rotation half and only that half.
 
-Six options, and every other name is refused.
+Seven options, and every other name is refused.
 
 | Option | Default | Effect |
 | --- | --- | --- |
@@ -90,6 +90,7 @@ Six options, and every other name is refused.
 | `toolFoldThreshold` | `0.50` | The tool-call diet: a share in `[0, 1)` naming the oldest fraction of the window whose tool results are clipped in view. `0` turns it off. |
 | `preCommitNotice` | `false` | The notice switch. False is the shape that won the campaign above: no carrier reaches the projection and every fold ships the runtime's own words. `true` states the window's status to the agent once per approach to a commit: where the commit fires, how far away it is, what is staged, what that frees, what is pinned and what the pin costs, with the verbs listed and no argument made for using any of them. |
 | `noticeLeadShare` | `0.10` | How far below the commit trigger that notice speaks, as a share of the serving budget. A distance rather than a point, so it follows a band that moves. Read only when `preCommitNotice` is on. |
+| `palette` | `{ map: "batlow", start: 0, end: 1 }` | The fold bar's colours, and nothing about folding. `map` is one of `batlow`, `viridis`, `plasma`, `magma`, `cividis`; `start` and `end` are positions on it in `[0, 1]` for the most compressed and the pinned shade, which may not coincide and may run backwards. Set whole or not at all. |
 
 Four commands ship for the human: `/fold-status`, `/fold` (commit every staged mark now), `/fold-editor` (the interactive map of the window) and `/fold-settings` (edit the options above; each change is saved to `~/.config/pi-fold/settings.json` and takes effect in the running session).
 

package/extensions/active-context.ts

@@ -64,7 +64,10 @@ import {
   stringIds,
   toolPayload,
 } from "./lib/measurement.ts";
-import { emptyFoldBarMass, renderFoldBar, type FoldBarKind, type FoldBarModel } from "./lib/status-widget.ts";
+import {
+  emptyFoldBarMass, renderFoldBar, resolveFoldBarPalette,
+  type FoldBarKind, type FoldBarModel, type FoldBarPalette,
+} from "./lib/status-widget.ts";
 import type {
   NativeCompactionCompletionReceipt,
   NativeCompactionDecisionReceipt,
@@ -303,6 +306,12 @@ export function registerActiveContext(pi: any, options: {
    *  rather than a point, so it tracks a band that moves. Read only when preCommitNotice
    *  is true. */
   noticeLeadShare?: number;
+  /** THE FOLD BAR'S COLOURS (2026-09-06, Shane): which colour map the status bar shades
+   *  its five folded-to-raw categories from and where on that map the two ends of the
+   *  ramp sit. A display preference: it moves nothing about folding, and it is here only
+   *  because the settings file is handed to registration whole. Absent means Batlow end
+   *  to end. */
+  palette?: FoldBarPalette;
 }): {
   projectionCandidates: (ctx: any) => Array<Record<string, unknown>>;
 } {
@@ -320,6 +329,7 @@ export function registerActiveContext(pi: any, options: {
   let preCommitNotice = resolvedPreCommitNotice(options.preCommitNotice);
   let noticeLeadShare = resolveNoticeLeadShare(options.noticeLeadShare);
   let toolFoldThreshold = resolvedToolFoldThreshold(options.toolFoldThreshold);
+  let palette = resolveFoldBarPalette(options.palette);
   // THE RENAMED OPTION IS REFUSED BY NAME, not ignored (2026-08-30). postFoldNotice was
   // public for three days and named a carrier that no longer exists in that shape: it
   // fired on a fold count, after the cut, and asked for briefs. Silently accepting the
@@ -777,6 +787,7 @@ export function registerActiveContext(pi: any, options: {
       staleAfterCommit: input.share !== null && foldBar.staleSince !== null &&
         foldBar.staleSince === measurements.lastProviderMeasurement,
       stopped: ladder.automaticFailure?.message ?? null,
+      palette,
     };
     if (!state || !snapshot) return model;
     model.mapped = true;
@@ -928,6 +939,7 @@ export function registerActiveContext(pi: any, options: {
     const nextToolFoldThreshold = resolvedToolFoldThreshold(settings?.toolFoldThreshold);
     const nextPreCommitNotice = resolvedPreCommitNotice(settings?.preCommitNotice);
     const nextNoticeLeadShare = resolveNoticeLeadShare(settings?.noticeLeadShare);
+    const nextPalette = resolveFoldBarPalette(settings?.palette);
     const changed: string[] = [];
     for (const field of ["maxTarget", "minTarget", "consolidateAfter", "minFoldChars"] as const) {
       if (nextThresholds[field] !== thresholds[field]) changed.push(field);
@@ -935,6 +947,7 @@ export function registerActiveContext(pi: any, options: {
     if (nextToolFoldThreshold !== toolFoldThreshold) changed.push("toolFoldThreshold");
     if (nextPreCommitNotice !== preCommitNotice) changed.push("preCommitNotice");
     if (nextNoticeLeadShare !== noticeLeadShare) changed.push("noticeLeadShare");
+    if (nextPalette.map !== palette.map || nextPalette.start !== palette.start || nextPalette.end !== palette.end) changed.push("palette");
     // A SAVE THAT MOVED NOTHING IS NOT AN EVENT. The screen saves every keystroke that
     // lands, including a row stepped back to where it started.
     if (!changed.length) return;
@@ -942,6 +955,7 @@ export function registerActiveContext(pi: any, options: {
     toolFoldThreshold = nextToolFoldThreshold;
     preCommitNotice = nextPreCommitNotice;
     noticeLeadShare = nextNoticeLeadShare;
+    palette = nextPalette;
     dropDerivationMemo();
     // THE STREAM CARRIES IT, because from here on the session's commits fire at a point
     // no earlier record explains, and an archive reading this run later has no other way
@@ -955,6 +969,7 @@ export function registerActiveContext(pi: any, options: {
       tool_fold_threshold: toolFoldThreshold,
       pre_commit_notice: preCommitNotice,
       notice_lead_share: noticeLeadShare,
+      palette: { ...palette },
     });
     // The person is standing in the settings screen, so the line they will look at next
     // is the status line. Without this it keeps the old number until a context event.

package/extensions/index.js

@@ -11,7 +11,7 @@ export {
 
 const PUBLIC_OPTIONS = Object.freeze([
   "thresholds", "providerInputBudget", "blacklistAutoFoldTools", "toolFoldThreshold",
-  "preCommitNotice", "noticeLeadShare",
+  "preCommitNotice", "noticeLeadShare", "palette",
 ]);
 
 const GENERATOR_DELETED = "the model brief generator is deleted (2026-08-14): across 15 sealed " +

package/extensions/lib/live-settings.ts

@@ -25,6 +25,7 @@
 // deployment) still agrees on the property.
 
 import type { ActiveContextThresholds } from "./policy.ts";
+import type { FoldBarPalette } from "./status-widget.ts";
 
 /**
  * What the settings screen hands the runtime: exactly the settings FILE's shape, where an
@@ -37,6 +38,7 @@ export interface LiveFoldSettings {
 	toolFoldThreshold?: number;
 	preCommitNotice?: boolean;
 	noticeLeadShare?: number;
+	palette?: FoldBarPalette;
 }
 
 /** Refuses by throwing, exactly as registration does, and leaves the runtime untouched. */

package/extensions/lib/status-widget.ts

@@ -2,11 +2,254 @@
 import { truncateToWidth } from "@earendil-works/pi-tui";
 
 export const FOLD_BAR_WIDTH = 40;
-// The first half of Batlow is compressed; the second half is still raw.
-export const FOLD_BAR_KINDS = ["consolidated", "span", "tool", "pinned", "marked", "raw"] as const;
+// GROUPED BY DISTANCE FROM COMPRESSION, left to right (Shane 2026-09-06). Consolidated,
+// span and tool folds are compressed now, deepest first. Marked content is raw now and
+// folds at the next commit. Raw content is raw now and eligible later. Pinned content is
+// raw and HELD against every commit until released, so it is the farthest from
+// compression of all, and it sits at the fresh edge of the bar.
+export const FOLD_BAR_KINDS = ["consolidated", "span", "tool", "marked", "raw", "pinned"] as const;
 export type FoldBarKind = typeof FOLD_BAR_KINDS[number];
 export type FoldBarMass = Record<FoldBarKind, number>;
-export const emptyFoldBarMass = (): FoldBarMass => ({ consolidated: 0, span: 0, tool: 0, pinned: 0, marked: 0, raw: 0 });
+export const emptyFoldBarMass = (): FoldBarMass => ({ consolidated: 0, span: 0, tool: 0, marked: 0, raw: 0, pinned: 0 });
+
+// ALL SIX KINDS TAKE THEIR SHADE FROM THE MAP, in that order (Shane 2026-09-06, second
+// pass). A pin sat off the ramp in the theme accent for one build; Shane put it back at
+// the far end, because a pin is the MOST settled state of all, decided and held, and the
+// map's last shade reads as separate from the rest of the fill on its own.
+
+// THE COLOUR MAPS, sampled at 64 positions by lab/generate_colour_maps.py: Batlow from
+// Crameri's own 256-step table, the other four from matplotlib. Five shades are read off
+// the chosen map by linear interpolation between a start and an end position, so a
+// person can use the whole map, a slice of it, or run it backwards. No palette library
+// ships: these tables are the whole dependency.
+export const COLOUR_MAP_NAMES = ["batlow", "viridis", "plasma", "magma", "cividis"] as const;
+export type ColourMapName = typeof COLOUR_MAP_NAMES[number];
+const COLOUR_MAPS: Record<ColourMapName, readonly string[]> = {
+  batlow: [
+    "#011959", "#051F5A", "#08265B", "#0B2B5C", "#0D315D", "#0E365E", "#0F3B5F", "#103F60",
+    "#114360", "#124761", "#134B61", "#154F62", "#175362", "#195662", "#1C5A62", "#1F5D61",
+    "#236061", "#27635F", "#2C665D", "#31695B", "#376B59", "#3C6D56", "#426F52", "#49714F",
+    "#4F734C", "#557548", "#5C7744", "#627941", "#697B3D", "#707D3A", "#777F36", "#7E8133",
+    "#858330", "#8D852E", "#94872C", "#9C892B", "#A48B2C", "#AC8C2D", "#B48E30", "#BC8F34",
+    "#C49138", "#CB923E", "#D29343", "#D9954A", "#E09651", "#E69858", "#EC9A61", "#F19C69",
+    "#F59F73", "#F8A17C", "#FAA486", "#FCA78F", "#FDAB98", "#FDAEA1", "#FDB1AA", "#FDB3B3",
+    "#FDB6BB", "#FDB9C4", "#FDBCCC", "#FCBFD5", "#FCC2DE", "#FBC6E7", "#FBC9F1", "#FACCFA",
+  ],
+  viridis: [
+    "#440154", "#46075A", "#470D60", "#471365", "#48186B", "#481E6F", "#482374", "#482878",
+    "#472D7C", "#46327F", "#453782", "#433C84", "#424186", "#404688", "#3E4A89", "#3C4F8A",
+    "#3A538B", "#38578C", "#365C8D", "#34608D", "#32648E", "#31688E", "#2F6C8E", "#2D708E",
+    "#2C748E", "#2A778E", "#297B8E", "#277F8E", "#26838E", "#24878E", "#238A8D", "#218E8D",
+    "#20928C", "#1F968B", "#1F9A8A", "#1F9D89", "#1FA187", "#21A586", "#23A984", "#26AC81",
+    "#2AB07F", "#2FB47C", "#35B779", "#3BBB75", "#42BE71", "#4AC26D", "#52C569", "#5AC864",
+    "#63CB5F", "#6CCE59", "#76D054", "#80D34D", "#8AD547", "#94D841", "#9FDA3A", "#A9DC33",
+    "#B4DD2C", "#BFDF25", "#CAE01F", "#D4E21A", "#DFE318", "#E9E41A", "#F3E61E", "#FDE725",
+  ],
+  plasma: [
+    "#0D0887", "#19068C", "#220690", "#2A0593", "#320597", "#39049A", "#40049C", "#46039F",
+    "#4D02A1", "#5402A3", "#5A01A5", "#6001A6", "#6700A7", "#6D00A8", "#7301A8", "#7902A8",
+    "#7F03A8", "#8506A7", "#8B0AA5", "#910EA3", "#9613A1", "#9C179E", "#A11C9B", "#A62098",
+    "#AB2594", "#B02991", "#B42E8D", "#B93289", "#BD3785", "#C13B82", "#C5407E", "#C9457A",
+    "#CD4976", "#D14E73", "#D4526F", "#D8576C", "#DB5C68", "#DE6065", "#E16561", "#E46A5E",
+    "#E76F5A", "#EA7457", "#ED7953", "#EF7E50", "#F2834C", "#F48849", "#F68D45", "#F89342",
+    "#F9993E", "#FA9E3B", "#FCA437", "#FDAA34", "#FDB031", "#FEB62E", "#FEBC2B", "#FDC328",
+    "#FDC926", "#FCD025", "#FBD624", "#F9DD25", "#F7E425", "#F5EB27", "#F2F227", "#F0F921",
+  ],
+  magma: [
+    "#000004", "#02010A", "#040312", "#06051A", "#0A0822", "#0F0B2B", "#130D34", "#180F3E",
+    "#1D1148", "#231151", "#29115B", "#301164", "#37106C", "#3E0F72", "#450F76", "#4B117A",
+    "#52137C", "#58157E", "#5F187F", "#651A80", "#6B1D81", "#721F81", "#782281", "#7E2482",
+    "#852681", "#8B2981", "#922B81", "#982D80", "#9F2F7F", "#A5317E", "#AC337C", "#B3357A",
+    "#B93878", "#C03A76", "#C63D74", "#CD3F71", "#D3436E", "#D9466B", "#DF4A68", "#E44F65",
+    "#E95462", "#ED5A5F", "#F1605D", "#F4675C", "#F66E5C", "#F8765C", "#FA7E5E", "#FB8560",
+    "#FC8D63", "#FD9567", "#FD9C6B", "#FEA470", "#FEAB75", "#FEB37A", "#FEBA80", "#FEC286",
+    "#FEC98D", "#FED193", "#FED89A", "#FDDFA1", "#FDE7A8", "#FCEEB0", "#FCF5B7", "#FCFDBF",
+  ],
+  cividis: [
+    "#00224E", "#002554", "#00285B", "#002B63", "#002E6A", "#003070", "#063370", "#123670",
+    "#1B386F", "#223B6E", "#283E6E", "#2D416D", "#32446D", "#37476C", "#3C496C", "#404C6C",
+    "#444F6C", "#48526C", "#4C556C", "#50576C", "#545A6D", "#575D6D", "#5B606E", "#5F636F",
+    "#62666F", "#666870", "#696B71", "#6D6E72", "#707173", "#747475", "#777776", "#7A7A78",
+    "#7E7D78", "#828078", "#868379", "#898678", "#8D8978", "#918C78", "#958F77", "#999277",
+    "#9D9576", "#A19875", "#A59C74", "#A99F73", "#ADA272", "#B2A570", "#B6A96F", "#BAAC6D",
+    "#BEAF6B", "#C2B369", "#C7B667", "#CBBA64", "#CFBD62", "#D4C15F", "#D8C45C", "#DDC859",
+    "#E1CC55", "#E5CF51", "#EAD34D", "#EFD748", "#F3DB42", "#F8DF3C", "#FDE234", "#FEE838",
+  ],
+};
+
+/** Which map the bar reads and where on it the two ends of the ramp sit. `start` is the
+ *  position of the most compressed shade and `end` the position of raw; a start above
+ *  its end runs the map backwards. Both are positions in [0, 1] and may not coincide,
+ *  because six shades read at one position are one shade. */
+export interface FoldBarPalette { map: ColourMapName; start: number; end: number; }
+export const DEFAULT_FOLD_BAR_PALETTE: Readonly<FoldBarPalette> = Object.freeze({ map: "batlow", start: 0, end: 1 });
+
+export class FoldBarPaletteError extends Error {}
+
+/** One resolver for every path a palette arrives by: registration, the settings file and
+ *  a live edit. Absent means the package default; anything present is validated whole. */
+export function resolveFoldBarPalette(value: unknown): FoldBarPalette {
+  if (value === undefined) return { ...DEFAULT_FOLD_BAR_PALETTE };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new FoldBarPaletteError("palette must be an object { map, start, end }");
+  }
+  const candidate = value as Record<string, unknown>;
+  for (const key of Object.keys(candidate)) {
+    if (key !== "map" && key !== "start" && key !== "end") {
+      throw new FoldBarPaletteError(`palette has no ${key} field: the fields are map, start, end`);
+    }
+  }
+  const { map, start, end } = candidate;
+  if (typeof map !== "string" || !(COLOUR_MAP_NAMES as readonly string[]).includes(map)) {
+    throw new FoldBarPaletteError(`palette.map must be one of ${COLOUR_MAP_NAMES.join(", ")}`);
+  }
+  for (const [name, position] of [["start", start], ["end", end]] as const) {
+    if (typeof position !== "number" || !Number.isFinite(position) || position < 0 || position > 1) {
+      throw new FoldBarPaletteError(`palette.${name} must be a position on the map from 0 to 1`);
+    }
+  }
+  if (start === end) {
+    throw new FoldBarPaletteError("palette.start and palette.end must differ: six shades read at one position are one shade");
+  }
+  return { map: map as ColourMapName, start: start as number, end: end as number };
+}
+
+// sRGB <-> linear <-> OKLab, enough to hold a hue while moving its lightness.
+const hexToRgb = (hex: string): number[] => [1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16) / 255);
+const rgbToHex = (rgb: number[]): string =>
+  "#" + rgb.map((v) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, "0").toUpperCase()).join("");
+const toLinear = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const fromLinear = (c: number): number => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+const luminanceOf = (hex: string): number => {
+  const [r, g, b] = hexToRgb(hex).map(toLinear);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+/** WCAG contrast ratio between two colours, the measure gate 165 has always applied. */
+export function contrastRatio(a: string, b: string): number {
+  const [la, lb] = [luminanceOf(a), luminanceOf(b)];
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+const linearToOklab = ([r, g, b]: number[]): number[] => {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [
+    0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s,
+  ];
+};
+const oklabToLinear = ([L, a, b]: number[]): number[] => {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.2914855480 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+};
+/** An OKLab colour brought into the sRGB gamut by shrinking its chroma, hue held. */
+const inGamut = (L: number, a: number, b: number): number[] => {
+  const inside = (rgb: number[]): boolean => rgb.every((v) => v >= -1e-6 && v <= 1 + 1e-6);
+  let rgb = oklabToLinear([L, a, b]);
+  if (inside(rgb)) return rgb.map(fromLinear);
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 16; i += 1) {
+    const mid = (lo + hi) / 2;
+    if (inside(oklabToLinear([L, a * mid, b * mid]))) lo = mid; else hi = mid;
+  }
+  rgb = oklabToLinear([L, a * lo, b * lo]);
+  return rgb.map((v) => fromLinear(Math.max(0, Math.min(1, v))));
+};
+
+/** The two reference backgrounds the readability floor is measured against. */
+export const READABILITY = Object.freeze({ dark: "#202122", light: "#FFFFFF", contrast: 4.5 });
+
+/** THE READABILITY CLAMP. A map's dark end vanishes on a dark terminal and its pale end
+ *  on a light one, and the old build carried two hand-adjusted hex tables to cover that
+ *  for one map at one range. With the map and the range a choice, the adjustment runs
+ *  here: lightness moves away from the background, hue held and chroma shrunk only as far
+ *  as the gamut needs, until the shade clears 4.5:1 against the reference background. A
+ *  shade that already clears it is returned untouched. */
+export function readableOn(hex: string, dark: boolean): string {
+  const background = dark ? READABILITY.dark : READABILITY.light;
+  if (contrastRatio(hex, background) >= READABILITY.contrast) return hex.toUpperCase();
+  const [L, a, b] = linearToOklab(hexToRgb(hex).map(toLinear));
+  // Lightness is monotone in luminance at held hue, so the boundary is found by bisection
+  // between the shade's own lightness and the far end, which always clears the floor.
+  let fails = L;
+  let passes = dark ? 1 : 0;
+  for (let i = 0; i < 24; i += 1) {
+    const mid = (fails + passes) / 2;
+    if (contrastRatio(rgbToHex(inGamut(mid, a, b)), background) >= READABILITY.contrast) passes = mid;
+    else fails = mid;
+  }
+  return rgbToHex(inGamut(passes, a, b));
+}
+
+/** The glyph a guide draws. Marks, not breaks: the fill's own colour stays behind them.
+ *  DOTTED, NOT A LINE (Shane 2026-09-06, sixth pass): a full-height one-pixel stroke
+ *  inside a solid colour is exactly what the boundary between two folds of that colour
+ *  looks like, so the edge strokes "read as fold segments"; a mark that does not span
+ *  the cell's height cannot be a boundary. The dotted vertical is centred in its cell,
+ *  so each guide stands just inside the band's edge: the aim in the cell whose left edge
+ *  is the aim share, the commit in the cell whose right edge is the commit share, a
+ *  quarter cell in from each line. Earlier passes: a text-ink hairline "too pronounced",
+ *  a notch "confusing", brackets off their lines because a font insets them. The ink is
+ *  the fill's own hue toned toward the background, muted on the track. */
+export const GUIDE_GLYPHS = Object.freeze({ aim: "┊", commit: "┊" });
+/** How far a bracket's ink is pulled from the shade under it toward the reference
+ *  background. Shane 2026-09-06, fourth pass: black brackets were too heavy, and no one
+ *  fixed accent is legible over a map that runs from navy to pale pink (the theme's teal
+ *  vanished over the teal span shade, violet over the blue, white over the pink). The
+ *  fill's own hue, darkened on a dark theme and lightened on a light one, is legible over
+ *  every shade because the readability clamp holds each shade at 4.5:1 against that
+ *  background: at this depth the floor is 3:1 over the darkest shade a map can carry. */
+export const GUIDE_TONE = 0.75;
+/** A guide's ink over a shade: the same hue, most of the way to the reference
+ *  background, so a bracket over salmon is a dark salmon and one over navy a deeper navy.
+ *  Never a hue of its own, so no guide competes with a category. */
+export function guideInk(under: string, dark: boolean): string {
+  const background = hexToRgb(dark ? READABILITY.dark : READABILITY.light);
+  return rgbToHex(hexToRgb(under).map((v, i) => v * (1 - GUIDE_TONE) + background[i] * GUIDE_TONE));
+}
+/** How far the dim ink is pulled toward the reference background to stand in for the
+ *  ░ texture it replaces: a quarter-coverage glyph reads as about a quarter of its ink. */
+export const TRACK_DEPTH = 0.7;
+/** The empty track's one shade, or null when the theme's dim ink is not an RGB escape. */
+export function trackShade(theme: FoldBarTheme, dark: boolean): string | null {
+  const match = /^\x1b\[38;2;(\d+);(\d+);(\d+)m$/.exec(theme.getFgAnsi?.("dim") ?? "");
+  if (!match) return null;
+  const dim = match.slice(1, 4).map((v) => Number(v) / 255);
+  const background = hexToRgb(dark ? READABILITY.dark : READABILITY.light);
+  return rgbToHex(dim.map((v, i) => v * (1 - TRACK_DEPTH) + background[i] * TRACK_DEPTH));
+}
+
+/** The shade a map holds at a position in [0, 1], interpolated between its samples. */
+export function sampleColourMap(map: ColourMapName, position: number): string {
+  const table = COLOUR_MAPS[map];
+  const at = Math.max(0, Math.min(1, position)) * (table.length - 1);
+  const lo = Math.floor(at), hi = Math.min(table.length - 1, lo + 1), t = at - lo;
+  const a = hexToRgb(table[lo]), b = hexToRgb(table[hi]);
+  return rgbToHex(a.map((v, i) => v * (1 - t) + b[i] * t));
+}
+
+const shadeMemo = new Map<string, Record<FoldBarKind, string>>();
+/** The six shades for a palette on a background: read off the map at evenly spaced
+ *  positions from start to end, then brought up to the readability floor. Memoized on
+ *  the palette and background, since the bar renders many times per choice. */
+export function foldBarShades(palette: FoldBarPalette, dark: boolean): Record<FoldBarKind, string> {
+  const key = `${palette.map}:${palette.start}:${palette.end}:${dark ? "dark" : "light"}`;
+  const held = shadeMemo.get(key);
+  if (held) return held;
+  const shades = Object.fromEntries(FOLD_BAR_KINDS.map((kind, i) => {
+    const position = palette.start + (palette.end - palette.start) * (i / (FOLD_BAR_KINDS.length - 1));
+    return [kind, readableOn(sampleColourMap(palette.map, position), dark)];
+  })) as Record<FoldBarKind, string>;
+  shadeMemo.set(key, shades);
+  return shades;
+}
 
 export interface FoldBarModel {
   brand: string;
@@ -26,27 +269,17 @@ export interface FoldBarModel {
   weighed: boolean;
   staleAfterCommit: boolean;
   stopped: string | null;
+  /** Absent means the package default, exactly as it does in the settings file. */
+  palette?: FoldBarPalette;
 }
 export interface FoldBarTheme {
   fg(color: "dim" | "muted" | "text" | "warning" | "error" | "accent", text: string): string;
   bold(text: string): string;
   getColorMode?(): "truecolor" | "256color";
-  getFgAnsi?(color: "text" | "muted" | "accent"): string;
+  getFgAnsi?(color: "text" | "muted" | "accent" | "dim"): string;
   name?: string;
 }
 
-// Batlow samples at 0, .2, .4 | .6, .8, 1, in the requested category order.
-// Static foreground lightness adjustments retain readable labels on dark/white
-// reference backgrounds. No palette generator or new dependency ships.
-const ON_DARK: Record<FoldBarKind, string> = {
-  consolidated: "#6C89C7", span: "#5B919F", tool: "#729261",
-  pinned: "#B38E2F", marked: "#FBA689", raw: "#FACCFA",
-};
-const ON_LIGHT: Record<FoldBarKind, string> = {
-  consolidated: "#011959", span: "#185562", tool: "#577647",
-  pinned: "#927012", marked: "#AA624A", raw: "#8F6891",
-};
-
 export function lightBackground(theme: FoldBarTheme): boolean {
   try {
     const match = /38;2;(\d+);(\d+);(\d+)/.exec(theme.getFgAnsi?.("text") ?? "");
@@ -65,7 +298,9 @@ const truecolor = (hex: string, text: string): string => {
 /** Two half-cell samples per terminal column. The measured fill never grows to fit
  * inventory. Each nonempty CATEGORY gets one half-cell when there is room, then quotas
  * follow relative mass. This is a visibility floor, not a per-fold width or token-exact
- * proportion. Both halves of a guide column are reserved so it cannot erase a category.
+ * proportion. A guide reserves the RIGHT half of its column only: the hairline is drawn
+ * at that column's right edge, which is the exact share the guide names, over whatever
+ * colour the left half holds, so a guide costs one half-cell and erases no category.
  */
 export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array<FoldBarKind | "empty" | "unknown" | "tick"> {
   const samples = 2 * width;
@@ -73,7 +308,7 @@ export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array
   const ticks = foldBarTicks(model, width);
   const total = FOLD_BAR_KINDS.reduce((sum, kind) => sum + model.mass[kind], 0);
   const cells: Array<FoldBarKind | "empty" | "unknown" | "tick"> = Array.from({ length: samples }, (_, i) =>
-    ticks.has(Math.floor(i / 2)) ? "tick" : i < filled ? "unknown" : "empty");
+    i % 2 === 1 && ticks.has(Math.floor(i / 2)) ? "tick" : i < filled ? "unknown" : "empty");
   const slots = cells.flatMap((kind, i) => kind === "unknown" ? [i] : []);
   if (!model.mapped || total <= 0 || !slots.length) return cells;
   const allocation = FOLD_BAR_KINDS.filter((kind) => model.mass[kind] > 0)
@@ -99,9 +334,16 @@ export function foldBarCells(model: FoldBarModel, width = FOLD_BAR_WIDTH): Array
   }
   return cells;
 }
+/** Each guide stands in the band's own edge cell: the aim in the column whose LEFT edge
+ *  is the aim share, the commit in the column whose RIGHT edge is the commit share, so
+ *  the band is the run of cells from one mark to the other inclusive. When both land on
+ *  one column the commit wins, since it is the one the label also names. */
 export function foldBarTicks(model: FoldBarModel, width = FOLD_BAR_WIDTH): Map<number, "aim" | "commit"> {
-  const at = (share: number): number => Math.max(0, Math.min(width - 1, Math.round(share * width) - 1));
-  return new Map([[at(model.aimShare), "aim"], [at(model.commitShare), "commit"]]);
+  const column = (value: number): number => Math.max(0, Math.min(width - 1, value));
+  return new Map([
+    [column(Math.round(model.aimShare * width)), "aim"],
+    [column(Math.round(model.commitShare * width) - 1), "commit"],
+  ]);
 }
 export function foldBarPlainText(model: FoldBarModel): string {
   return renderFoldBar(model, Number.POSITIVE_INFINITY, { fg: (_c, t) => t, bold: (t) => t });
@@ -115,37 +357,73 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
   if (model.stopped) return cut(`${brand} ${theme.fg("error", theme.bold("FOLDING STOPPED"))}` +
     (model.share === null ? "" : neutral(` · ${Math.round(model.share * 100)}% full`)));
   if (model.share === null) return cut(`${brand} ${muted(`not measured yet · folds automatically at ${Math.round(model.commitShare * 100)}%`)}`);
-  const palette = lightBackground(theme) ? ON_LIGHT : ON_DARK;
+  const truecolorMode = theme.getColorMode?.() === "truecolor";
+  const dark = !lightBackground(theme);
+  const shades = foldBarShades(model.palette ?? DEFAULT_FOLD_BAR_PALETTE, dark);
+  // Without truecolor the theme's own inks stand in: pinned takes the accent, raw the
+  // muted ink, everything compressed or marked the text ink.
   const ink = (kind: FoldBarKind, text: string): string => {
-    if (theme.getColorMode?.() === "truecolor") return truecolor(palette[kind], text);
-    if (kind === "pinned") return theme.fg("accent", text);
-    return theme.fg(kind === "raw" ? "muted" : "text", text);
+    if (truecolorMode) return truecolor(shades[kind], text);
+    return theme.fg(kind === "pinned" ? "accent" : kind === "raw" ? "muted" : "text", text);
   };
   const cells = foldBarCells(model);
+  const ticks = foldBarTicks(model);
+  // THE TRACK IS SOLID (Shane 2026-09-06, fourth pass): a guide cell on a ░ track was a
+  // blank cell with a bracket in it, which read as a hole. With an RGB dim ink the empty
+  // track is one shade, the dim ink pulled most of the way to the reference background
+  // so it sits where ░ used to, and a bracket on it stands on that same shade. Without
+  // an RGB dim ink the ░ texture stays, and the guide cell there is bare.
+  const track = trackShade(theme, dark);
+  const trackBg = track ? truecolor(track, "").replace("[38;", "[48;") : null;
   const solid = (kind: typeof cells[number]): string => {
-    if (kind === "tick") return neutral(theme.bold("┆"));
-    if (kind === "empty") return theme.fg("dim", "░");
+    if (kind === "empty") return trackBg ? `${trackBg} \x1b[49m` : theme.fg("dim", "░");
     if (kind === "unknown") return muted("█");
-    return ink(kind, "█");
+    return ink(kind as FoldBarKind, "█");
   };
-  const background = (kind: FoldBarKind): string | null => {
-    if (theme.getColorMode?.() === "truecolor") return truecolor(palette[kind], "").replace("[38;", "[48;");
-    // Pi exposes the same theme ink in 256-colour mode. Convert its foreground escape
-    // to background, without assuming an RGB theme or leaking styles into the label.
-    const fg = theme.getFgAnsi?.(kind === "pinned" ? "accent" : kind === "raw" ? "muted" : "text") ?? "";
+  const background = (kind: FoldBarKind | "unknown"): string | null => {
+    if (truecolorMode && kind !== "unknown") return truecolor(shades[kind], "").replace("[38;", "[48;");
+    // Pi exposes the same theme ink in 256-colour mode, and the accent for a pin there.
+    // Convert its foreground escape to background, without assuming an RGB theme or
+    // leaking styles into the label.
+    const fg = theme.getFgAnsi?.(kind === "pinned" ? "accent" : kind === "raw" || kind === "unknown" ? "muted" : "text") ?? "";
     const extended = /^\x1b\[38;(?:2;\d+;\d+;\d+|5;\d+)m$/.test(fg);
     if (extended) return fg.replace("[38;", "[48;");
     const basic = /^\x1b\[(3[0-7]|9[0-7])m$/.exec(fg);
     return basic ? `\x1b[${Number(basic[1]) + 10}m` : null;
   };
+  // THE GUIDES ARE MARKS ON THE AXIS, NOT BREAKS IN THE FILL (Shane 2026-09-06, third
+  // pass). A hairline in text ink read as a white bar; a notch cut into the fill read as
+  // a boundary between two kinds of content, which a threshold is not. The band is an
+  // interval, so a dotted mark stands in each of its edge cells, drawn over the fill's
+  // own colour in that colour's own hue pulled toward the background. No hue of its
+  // own, since a coloured guide competes with a category; never the warning ink, since
+  // folding is automatic and the person has nothing to do about it. On the track the
+  // muted ink stands on the track's shade; without truecolor the mark stands on the
+  // default background, because the theme's inks are the fill.
+  const shadeUnder = (left: typeof cells[number]): string | null =>
+    truecolorMode && (FOLD_BAR_KINDS as readonly string[]).includes(left) ? shades[left as FoldBarKind] : null;
+  const guide = (column: number, left: typeof cells[number]): string => {
+    const glyph = GUIDE_GLYPHS[ticks.get(column) ?? "aim"];
+    const under = shadeUnder(left);
+    if (under) return `${background(left as FoldBarKind)}${truecolor(guideInk(under, dark), glyph)}\x1b[49m`;
+    if (left === "empty" && trackBg) return `${trackBg}${theme.fg("muted", glyph)}\x1b[49m`;
+    return theme.fg("muted", glyph);
+  };
   let bar = "";
   for (let i = 0; i < cells.length; i += 2) {
     const left = cells[i], right = cells[i + 1];
+    if (right === "tick") {
+      // The mark over the left half's own colour: the guide stands in the band's edge
+      // cell and hides no fill. Off the fill it stands on the track.
+      bar += guide(i / 2, left);
+      continue;
+    }
     if (left === right) { bar += solid(left); continue; }
     // One full-height left-half glyph, right colour supplied by the cell background:
     // two colours in one column, never a notch, gap, score, or extra terminal column.
     if (right === "empty") {
-      bar += left === "unknown" ? muted("▌") : ink(left as FoldBarKind, "▌");
+      const half = left === "unknown" ? muted("▌") : ink(left as FoldBarKind, "▌");
+      bar += trackBg ? `${trackBg}${half}\x1b[49m` : half;
     } else {
       const bg = background(right as FoldBarKind);
       bar += bg ? `${bg}${ink(left as FoldBarKind, "▌")}\x1b[49m` : solid(left);
@@ -160,13 +438,18 @@ export function renderFoldBar(model: FoldBarModel, width: number, theme: FoldBar
     parts.push(neutral(`${pct}%`), muted(when));
   }
   if (model.mapped) {
-    // N counts compressed folds. Pin/Mark are accompanying states, not added to N.
-    const counts = [
-      ink("consolidated", `${model.foldConsolidations} Cons.`), ink("span", `${model.foldSpans} Span`),
-      ink("tool", `${model.foldTruncations} Tool`), ink("pinned", `${model.pinnedRefs} Pin`),
-      ink("marked", `${model.stagedMarks} Mark`),
-    ];
-    parts.push(neutral(`${model.folds} Folds (`) + counts.join(muted(", ")) + neutral(")"));
+    // N counts compressed folds. Mark/Pin are accompanying states, not added to N, and
+    // they are named in the bar's own order. A kind with nothing to count is not named
+    // (Shane 2026-09-06): the row's width is the scarce thing, and "0 Tool" tells a
+    // person nothing the bar does not already show by its absence.
+    const counts = ([
+      ["consolidated", model.foldConsolidations, "Cons."], ["span", model.foldSpans, "Span"],
+      ["tool", model.foldTruncations, "Tool"], ["marked", model.stagedMarks, "Mark"],
+      ["pinned", model.pinnedRefs, "Pin"],
+    ] as const).filter(([, count]) => count > 0).map(([kind, count, word]) => ink(kind, `${count} ${word}`));
+    parts.push(counts.length
+      ? neutral(`${model.folds} Folds (`) + counts.join(muted(", ")) + neutral(")")
+      : neutral(`${model.folds} Folds`));
     if (model.unplacedItems > 0) parts.push(muted(`${model.unplacedItems} not mapped`));
   } else parts.push(muted("mapping"));
   return cut(`${bar} ${parts.join(theme.fg("dim", " · "))}`);

package/extensions/settings.ts

@@ -29,6 +29,13 @@ import {
 	type ActiveContextThresholds,
 } from "./lib/policy.ts";
 import { applyLiveSettings, liveSettingsReachable } from "./lib/live-settings.ts";
+import {
+	COLOUR_MAP_NAMES,
+	DEFAULT_FOLD_BAR_PALETTE,
+	FoldBarPaletteError,
+	resolveFoldBarPalette,
+	type FoldBarPalette,
+} from "./lib/status-widget.ts";
 
 export const DEFAULT_FOLD_SETTINGS_PATH = join(
 	homedir(),
@@ -47,6 +54,11 @@ export interface FoldSettingsFile {
 	toolFoldThreshold?: number;
 	preCommitNotice?: boolean;
 	noticeLeadShare?: number;
+	// THE BAR'S COLOURS, stored whole for the same reason the thresholds are (2026-09-06):
+	// start and end may not coincide, which is a cross-field invariant, so a partial object
+	// would mean whatever the defaults are at read time. Absent means the package default.
+	// It is a display preference and moves nothing about folding.
+	palette?: FoldBarPalette;
 }
 
 // The four settings, named once. This was a hand-written union until the migration
@@ -63,11 +75,17 @@ const THRESHOLD_FIELDS = [
 // validation and no relationship to any other value on the screen.
 const SCALAR_FIELDS = ["toolFoldThreshold", "preCommitNotice", "noticeLeadShare"] as const;
 
-export type FoldSettingId = typeof THRESHOLD_FIELDS[number] | typeof SCALAR_FIELDS[number];
+// The three rows that edit the palette object, each naming the field it moves.
+const PALETTE_FIELDS = { paletteMap: "map", paletteStart: "start", paletteEnd: "end" } as const;
+
+export type FoldSettingId = typeof THRESHOLD_FIELDS[number] | typeof SCALAR_FIELDS[number] | keyof typeof PALETTE_FIELDS;
 
 function isThresholdField(id: FoldSettingId): id is typeof THRESHOLD_FIELDS[number] {
 	return (THRESHOLD_FIELDS as readonly string[]).includes(id);
 }
+function isPaletteField(id: FoldSettingId): id is keyof typeof PALETTE_FIELDS {
+	return Object.hasOwn(PALETTE_FIELDS, id);
+}
 
 // One edit, applied against the WHOLE draft: the merged thresholds object is
 // re-validated through resolveThresholds so cross-field invariants
@@ -105,6 +123,20 @@ export function applyFoldSettingsEdit(
 		}
 		return { ok: true, draft: { ...draft, toolFoldThreshold: value } };
 	}
+	if (isPaletteField(id)) {
+		// The palette is re-validated WHOLE through the runtime's own resolver, so the
+		// cross-field rule (start and end differ) holds at every saved state.
+		const field = PALETTE_FIELDS[id];
+		const raw = rawValue.trim();
+		const value = field === "map" ? raw : Number(raw);
+		try {
+			const palette = resolveFoldBarPalette({ ...(draft.palette ?? DEFAULT_FOLD_BAR_PALETTE), [field]: value });
+			return { ok: true, draft: { ...draft, palette } };
+		} catch (error) {
+			if (error instanceof FoldBarPaletteError) return { ok: false, error: error.message };
+			throw error;
+		}
+	}
 	try {
 		const value = Number(rawValue.trim());
 		if ((id === "consolidateAfter" || id === "minFoldChars") && !Number.isSafeInteger(value)) {
@@ -209,10 +241,10 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 		dropped = true;
 	}
 	for (const key of Object.keys(parsed)) {
-		if (key === "thresholds" || (SCALAR_FIELDS as readonly string[]).includes(key)) continue;
+		if (key === "thresholds" || key === "palette" || (SCALAR_FIELDS as readonly string[]).includes(key)) continue;
 		if (RETIRED_FILE_KEYS.includes(key)) { delete parsed[key]; dropped = true; continue; }
 		return refused(`fold settings file has no ${key} field: the surface is ` +
-			`thresholds, ${SCALAR_FIELDS.join(", ")}`);
+			`thresholds, ${SCALAR_FIELDS.join(", ")}, palette`);
 	}
 	// The two scalars are validated the same way the editor validates them, through the
 	// one path, so a hand-edited file cannot hold a value the screen would refuse.
@@ -232,6 +264,12 @@ export function readFoldSettingsFile(path: string = DEFAULT_FOLD_SETTINGS_PATH):
 		}
 		Object.assign(scalars, applied.draft);
 	}
+	// The palette goes through the one resolver the runtime and the editor use, so a
+	// hand-edited file cannot hold a map name or a range the screen would refuse.
+	if (parsed.palette !== undefined) {
+		try { scalars.palette = resolveFoldBarPalette(parsed.palette); }
+		catch (error: any) { return refused(`fold settings palette is invalid: ${error?.message ?? error}`); }
+	}
 	if (parsed.thresholds === undefined) {
 		if (dropped) { try { saveFoldSettingsFile(path, scalars); } catch { } }
 		return { settings: scalars, refusal: null, migrated: dropped };
@@ -271,6 +309,7 @@ export function saveFoldSettingsFile(path: string, settings: FoldSettingsFile):
 	if (settings.toolFoldThreshold !== undefined) clean.toolFoldThreshold = settings.toolFoldThreshold;
 	if (settings.preCommitNotice !== undefined) clean.preCommitNotice = settings.preCommitNotice;
 	if (settings.noticeLeadShare !== undefined) clean.noticeLeadShare = settings.noticeLeadShare;
+	if (settings.palette !== undefined) clean.palette = settings.palette;
 	mkdirSync(dirname(path), { recursive: true });
 	const temporary = `${path}.tmp`;
 	writeFileSync(temporary, `${JSON.stringify(clean, null, 2)}\n`);
@@ -297,6 +336,12 @@ const EDITOR_ROWS: readonly EditorRow[] = [
 	{ id: "toolFoldThreshold", label: "Clip old tool results", description: "The oldest share of the window shows tool results shortened, still recoverable in full. Off keeps them whole (toolFoldThreshold)" },
 	{ id: "preCommitNotice", label: "Tell the model before folding", description: "Show the model the window's status once as a fold approaches: what is staged, what is pinned, what it can change. Off is what the measured runs used (preCommitNotice)" },
 	{ id: "noticeLeadShare", label: "How early to tell it", description: "How far below the folding point that status appears. Only used when the notice is on (noticeLeadShare)" },
+	// THE BAR'S COLOURS ARE A CHOICE (Shane 2026-09-06). Three rows over one stored object:
+	// which map, and where on it the two ends of the ramp sit. The status line repaints on
+	// every step, so the bar itself is the preview.
+	{ id: "paletteMap", label: "Bar colours", description: "The colour map the status bar reads its six shades from, most compressed first and pinned last (palette.map)" },
+	{ id: "paletteStart", label: "Folded shade at", description: "Where on that map the most compressed content sits. Put it past the pinned end to run the map backwards (palette.start)" },
+	{ id: "paletteEnd", label: "Pinned shade at", description: "Where on that map pinned content sits, with raw just before it. The shades between are spaced evenly (palette.end)" },
 ];
 
 // The cycle lattice for both shares. Shares step in cents so no float drift reaches a
@@ -326,6 +371,9 @@ const MIN_FOLD_CHOICES = [2_000, 4_000, 6_000, 8_000, 12_000, 16_000, 24_000, 32
 // off: without a 0 here the only way to decline in-view clipping would be the file.
 const TOOL_FOLD_CHOICES = [0, 0.25, 0.35, 0.50, 0.65, 0.75, 0.90];
 
+// Positions on a colour map, the whole of it in twentieths, ends included.
+const MAP_POSITION_CHOICES = Array.from({ length: 21 }, (_, i) => i / 20);
+
 function shareCandidates(): number[] {
 	const { min, max, step } = SHARE_LATTICE;
 	const values: number[] = [];
@@ -337,8 +385,13 @@ function shareCandidates(): number[] {
 
 // The lattice a row steps along, as numbers. Display belongs to rowDisplayValue and
 // only to it: this list is stepped, never shown.
-function allowedValues(id: FoldSettingId, thresholds: ActiveContextThresholds): number[] {
+function allowedValues(id: FoldSettingId, thresholds: ActiveContextThresholds, palette: FoldBarPalette): number[] {
 	if (id === "toolFoldThreshold") return TOOL_FOLD_CHOICES;
+	// Each end of the ramp may step anywhere on the map except onto the other end: the
+	// cross-field rule is the filter, so stepping across the other end is one keypress.
+	if (id === "paletteStart") return MAP_POSITION_CHOICES.filter((v) => Math.abs(v - palette.end) > 1e-9);
+	if (id === "paletteEnd") return MAP_POSITION_CHOICES.filter((v) => Math.abs(v - palette.start) > 1e-9);
+	if (id === "paletteMap") return [];
 	// THE LEAD STEPS THE ONE SHARE LATTICE, unfiltered. It answers to nothing but its own
 	// range: a lead wider than the trigger is legal and means "speak from the first
 	// measurement", which the runtime floors rather than refuses, so there is no
@@ -359,6 +412,7 @@ function rowRawValue(settings: FoldSettingsFile, id: FoldSettingId): string {
 	// A SCALAR THAT IS ABSENT READS AS THE PACKAGE DEFAULT, never as zero or false. The
 	// file omits what was never set on purpose, so the screen has to supply the same
 	// value the runtime would, or the row would show a setting nobody chose.
+	if (isPaletteField(id)) return String((settings.palette ?? DEFAULT_FOLD_BAR_PALETTE)[PALETTE_FIELDS[id]]);
 	if (!isThresholdField(id)) {
 		if (id === "toolFoldThreshold") return String(settings.toolFoldThreshold ?? DEFAULT_TOOL_FOLD_THRESHOLD);
 		if (id === "noticeLeadShare") return String(settings.noticeLeadShare ?? DEFAULT_NOTICE_LEAD_SHARE);
@@ -384,6 +438,13 @@ function rowDisplayValue(settings: FoldSettingsFile, id: FoldSettingId, budgetTo
 	}
 	if (id === "consolidateAfter") return raw;
 	if (id === "minFoldChars") return `${Number(raw).toLocaleString("en-US")} characters`;
+	if (id === "paletteMap") return raw;
+	if (id === "paletteStart" || id === "paletteEnd") {
+		// A POSITION ON THE MAP, not a share of the window: the percentages elsewhere on this
+		// screen are occupancy, and this one is not, so it says what it is along.
+		const position = Number(raw);
+		return position === 0 ? "start of the map" : position === 1 ? "end of the map" : `${Math.round(position * 100)}% along the map`;
+	}
 	// A PERCENTAGE, like every other human surface. The screen used to read "0.80" while
 	// the status line, /fold-status and the editor header all said "80%", so the one place
 	// a person CHANGES the number spoke a different dialect from the three that report it.
@@ -539,8 +600,14 @@ export class FoldSettingsEditor extends Container {
 			this.applyAndSave(id, rowRawValue(this.draft, id) === "true" ? "false" : "true");
 			return;
 		}
+		// A NAMED LIST steps by index, clamped at its ends like every other row.
+		if (id === "paletteMap") {
+			const at = (COLOUR_MAP_NAMES as readonly string[]).indexOf(rowRawValue(this.draft, id)) + direction;
+			if (at >= 0 && at < COLOUR_MAP_NAMES.length) this.applyAndSave(id, COLOUR_MAP_NAMES[at]);
+			return;
+		}
 		const thresholds = this.draft.thresholds ?? DEFAULT_THRESHOLDS;
-		const candidates = allowedValues(id, thresholds);
+		const candidates = allowedValues(id, thresholds, this.draft.palette ?? DEFAULT_FOLD_BAR_PALETTE);
 		const current = Number(rowRawValue(this.draft, id));
 		const target = direction > 0
 			? candidates.find((candidate) => candidate > current + 1e-9)
@@ -595,7 +662,7 @@ export function registerFoldSettings(
 ): void {
 	const settingsPath = options.settingsPath ?? DEFAULT_FOLD_SETTINGS_PATH;
 	pi.registerCommand("fold-settings", {
-		description: "Configure pi-fold: commit band, consolidation, fold size, tool-result clipping, brief invitation",
+		description: "Configure pi-fold: commit band, consolidation, fold size, tool-result clipping, the pre-commit notice, bar colours",
 		handler: async (_args: string, ctx: any) => {
 			if (typeof ctx.ui?.custom !== "function") {
 				throw new Error("/fold-settings needs an interactive UI; set thresholds in the settings file instead");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fold",
-  "version": "4.1.5",
+  "version": "4.1.6",
   "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",