@groeponline/pi-wishcraft 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-08-27
+
 ## [1.3.1] - 2026-08-25
 
 ### Fixed

package/ROADMAP.md

@@ -1,146 +1,41 @@
 # Roadmap — pi-wishcraft
 
-Baseline: **v1.2.0**, published 2026-08-24.
-
-Pi is the engine. Wishcraft is the operator experience layer: Signal, Deck, skills, ideas, shell UX, hooks, repairs and policy without forking Pi core.
-
-Historical 0.x/1.0/vNext campaign detail belongs in `CHANGELOG.md` and `docs/design/`. This file describes only the current product contract and work that is still open.
-
-## Product boundary
-
-Wishcraft may extend the Pi experience, but it does not become:
-
-- a Pi fork or second agent engine;
-- a fleet/orchestration control plane;
-- a SaaS integrations bundle;
-- a second plugin runtime competing with Pi extensions;
-- a telemetry collector by default.
-
-External systems should connect through small contribution/integration contracts. Vendor-specific control planes belong outside Wishcraft.
+Baseline: **v1.3.1** (`e79737f`, tag `v1.3.1` 2026-08-25, npm `1.3.1`) — `origin/main` @ `0044a87` (vivid). Historical vNext PR0-8 detail is archived in `CHANGELOG.md` and `docs/design/vnext-overview.md`; this file is the current contract.
 
 ## Release line
 
-| Release | Theme | State | Done means |
-| --- | --- | --- | --- |
-| **1.2** | Operator Layer | shipped | Deck, universal Signal, structural appearance, motion gallery/composer, skill workbench and first-class motion accessibility |
-| **1.3** | Hardening | current | release invariant, render-path performance, one token source of truth, explicit renderer/lifecycle contracts, regression coverage |
-| **1.4** | Extension Contract | next | typed settings registry plus small contribution APIs; no new plugin runtime |
-| **1.5** | Craft Ecosystem | later | curated skill/package workflows built on Pi-native distribution and the contribution contract |
-| **2.0** | Stable Experience Platform | target | documented compatibility policy, migrations, performance budgets and stable public extension points |
-
-## 1.3 — Hardening
-
-No feature dump. This release exists to make the v1.2 surface trustworthy.
-
-### P0 — release integrity
-
-- One reusable `Verify` contract for PR verification and release gating.
-- Verify includes whitespace, typecheck, unit tests, circular dependency check and Pi package contract.
-- Release jobs depend on Verify and re-check the synchronized `origin/main` tree before tagging.
-- `main` should require the Verify check in repository rules before merge.
-
-### P0 — render/runtime performance
-
-- Deck paint must not run filesystem-backed skill discovery, skill doctor or settings parsing.
-- Expensive Deck data is cached as static snapshot state and refreshed only on open, relevant navigation or mutation.
-- Live model/Git/context/queue/Signal state remains cheap to repaint.
-- Idle motion stays 0 FPS.
-
-### P0 — appearance consistency
-
-- `src/config/types.ts` + `src/config/tokens.ts` are the canonical token contract.
-- `src/theme/tokens/*` is compatibility-only; it may re-export but may not define a second palette or semantic mapping.
-- One structural base must paint the same semantic roles regardless of the configuration path used to select it.
-
-### P0 — Signal contract
-
-- Signal is the universal status renderer for legacy and structural presets.
-- Legacy presets keep their existing segment/layout/color contract unless a structural appearance layer is explicitly selected.
-- Terminal one-shots (`success`, `warning`, `error`) settle to `idle/ready` after their finite burst.
-- Reduced/off/screen-reader modes communicate state without requiring animation.
-
-### P1 — verification matrix
-
-Add/keep regression coverage for:
-
-- widths around 40 / 80 / 120+ columns;
-- ASCII, Nerd Font and `NO_COLOR` rendering;
-- full / reduced / functional / off motion;
-- Deck render hot-path invariants;
-- legacy preset color compatibility;
-- release-gate dependency order;
-- Linux and macOS system-segment parsing.
-
-## 1.4 — Extension Contract
-
-The next architecture step is **composability**, not more built-in routes.
-
-### Typed settings registry
-
-One registry should drive:
-
-```text
-settings definition
-      │
-      ├─ parsing + validation
-      ├─ defaults + migrations
-      ├─ /wishcraft settings
-      ├─ Pi settings contribution (where supported)
-      └─ generated documentation/examples
-```
-
-This removes duplicate knowledge about settings and enables a real zero-config first run.
+| Release | Theme | State | Done means | Pin |
+| --- | --- | --- | --- | --- |
+| **1.2** | Operator Layer | shipped | Deck, Signal 3-lane, 10 bases, gallery/composer, workbench, a11y | tag `v1.2.0` `65e62fd` (784faaa merge) |
+| **1.3** | Hardening | shipped | Verify contract, 0 FPS idle, token SSOT, renderer/lifecycle, regression | `f352b38`→`ecb2d5e` v1.3.0, `e79737f` v1.3.1, RC `v1.3.2-cea7e3e` pending |
+| **1.4** | Extension Contract | **current** | 1.4a-d below; no new runtime | `0bfa5a2` registry on main, `62d6156` contrib on `feat/contribution-api`, `0044a87` vivid on main |
+| **1.5** | Craft Ecosystem | next | skill install via Pi-native dist + recipes, built on 1.4 contract | starts after 1.4c Signal wiring green |
+| **2.0** | Stable Platform | target | compat policy, migrations, perf budgets, stable contracts, provenance | after 1.4a-d + 1.3-P1 |
 
-### Small contribution API
+## 1.4 — Extension Contract (current, split)
 
-Target capabilities, subject to Pi host APIs:
+**1.4a — Settings registry** — *shipped* `0bfa5a2` `feat(config): typed settings registry` on `origin/main`. `src/config/settings-registry.ts` (28 defs, `SETTING_DEFAULTS`, `get/validate` O(1) maps, `SETTING_GROUPS`). `src/extension/settings/wishcraft-config-items.ts` now renders from registry (124 lines removed). Tests `tests/settings-registry.test.ts` + `wishcraft-config.test.ts` green (557). Still TODO: `contributeSettings()` Pi-contribution + `defaults/migrations` + docgen from registry.
 
-```text
-registerDeckRoute()
-registerSignalSource()
-registerMotion()
-registerAppearanceContribution()
-registerRecipeOrAction()
-contributeSettings()
-```
+**1.4b — Contribution API** — *pending* `62d6156` `feat(contract): typed contribution API` on `origin/feat/contribution-api` (not yet on `origin/main`). `src/extension/contrib/{types,registry}.ts` ships `registerDeckRoute`/`registerSignalSource` (validate `id /^[a-z0-9][a-z0-9-_]*$/`, dedup, `false` never throw). Deck wired via `src/extension/ui/deck/routes.ts` `getAllDeckRouteDefs()`/`isDeckRoute()`. Still TODO: `registerMotion()`, `registerAppearanceContribution()`, `registerRecipeOrAction()` as separate slices (one PR per contract).
 
-Rules:
+**1.4c — Signal wiring** — *next* after 1.4b merge. `src/signal/render.ts` must call `getContributedSignalSources()` with per-source fault isolation (`try/catch` → `null`), versioned capability scope. Done when both Deck and Signal contributions render without taking down the bar (`tests/contrib-registry.test.ts` + `signal.test.ts` + fault test).
 
-- Pi remains the package/extension runtime.
-- Contributions are data/callback contracts, not arbitrary nested plugin loaders.
-- Public contracts are versioned and capability-scoped.
-- A failing contribution cannot take down Signal or the Deck.
+**1.4d — Preset composer** — Decouple `PresetDef` `tokens/chrome/signal/motion/deck/welcome/glyphs` from `src/config/structural-presets.ts` to allow `contributedAppearance` overrides per preset with validation. Done when `tests/structural-presets.test.ts` + `tokens.test.ts` cover contributed palette/motion.
 
-## 1.5 — Craft Ecosystem
+**Gate for 1.4 done:** `npm run typecheck && npm test && npx madge --circular src` green, `isDeckRoute` + Signal sources both isolated, registry `contributeSettings` tested, no new runtime.
 
-After the contribution/settings contracts are stable:
+## 1.3 — Hardening (shipped, pending tags)
 
-- skill import/install workflows from explicit trusted sources;
-- curated recipes/actions that compose existing Wishcraft/Pi capabilities;
-- package discovery surfaced through Pi-native package distribution rather than a parallel Wishcraft marketplace;
-- export/import of appearance and motion recipes with validation.
+P0 Verify: `whitespace + tsc --noEmit + npm test + madge --circular + scripts/verify-pi-package-contract.mjs`. Release depends on Verify and re-checks `origin/main` before tag. `main` requires `Verify` (repo rules). Promote flow is **official**: `release-candidate/v*` + `promote-release-candidate.yml` (`65143ae`) → tag → npm. P1 matrix still open: widths 40/80/120+, ASCII/Nerd/`NO_COLOR`, `full/reduced/functional/off`, Deck hot-path (no fs in paint), legacy colors, gate order, Linux/macOS segments. Pending RCs: `v1.3.2-cea7e3e` (`ff68fff`), `v1.4.0-0bfa5a2` (`529bc10`), `v1.5.0-0044a87` — collapse into single `1.4.0` promote after 1.4c.
 
-## 2.0 — Stable Experience Platform
+## 1.5 — Craft Ecosystem (next)
 
-2.0 is justified when the public contracts, not the feature count, are stable.
+Starts after 1.4c wiring green: skill install from Pi-native dist (no parallel marketplace), curated recipes. One paragraph; detail deferred.
 
-Required before 2.0:
+## 2.0 — Stable Platform (target)
 
-- compatibility and deprecation policy;
-- settings migrations with round-trip tests;
-- measured render/performance budgets;
-- stable contribution API with fault isolation;
-- release provenance and required repository checks;
-- docs generated from canonical contracts where practical;
-- no known duplicate sources of truth for tokens, settings or release verification.
+Needs: compat/deprecation policy, migrations with round-trip tests, perf budgets, stable contribution API with fault isolation, provenance via required `Verify`, docs from canonical contracts, no duplicate SSOTs.
 
-## Always-on engineering rules
+## Always-on
 
-- English operator UI.
-- No synchronous discovery work in paint/render loops.
-- No background animation when nothing consumes it.
-- Core Pi tools are not silently rewritten by Wishcraft repairs.
-- Policies and hooks remain explicitly disableable.
-- Security-sensitive paths fail closed.
-- Package/release verification runs before npm publication.
-- New features must fit the operator-layer boundary above.
+English UI, no sync discovery in paint, no background animation when idle (0 FPS, ambient 8 FPS max vivid), no silent Pi core rewrites, policies/hooks disableable, fail closed, Verify before npm, operator-layer boundary.

package/docs/design/vnext-release-plan.md

@@ -1,4 +1,6 @@
-# Wishcraft vNext — Stacked PR Release Plan
+# Wishcraft vNext — Stacked PR Release Plan — ARCHIVED (all 8 landed)
+
+> **Archived 2026-08-26:** All 8 PRs landed via `784faaa feat: merge Wishcraft vNext operator layer` → `65e62fd v1.2.0` (plus hardening `f352b38`/`ecb2d5e`/`e79737f` and vivid `0044a87`). Historical detail only; active plan is `ROADMAP.md` 1.4a-d. Do not use this as future todo.
 
 ## Goal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [

package/src/config/parse.ts

@@ -29,6 +29,7 @@ import type {
 } from "./types.ts";
 import { isStructuralPresetName } from "./structural-presets.ts";
 import { isMotionLevel, type MotionLevel } from "../motion/accessibility.ts";
+import { SETTING_DEFAULTS } from "./settings-registry.ts";
 
 export interface PowerlineConfig {
   preset: StatusLinePreset;
@@ -65,7 +66,7 @@ export function parsePowerlineConfig(
   presets: readonly StatusLinePreset[],
 ): PowerlineConfig {
   const defaultConfig: PowerlineConfig = {
-    preset: "default",
+    preset: SETTING_DEFAULTS["powerline.preset"],
     customItems: [],
     disabledSegments: [],
     invalidDisabledSegments: [],
@@ -73,9 +74,9 @@ export function parsePowerlineConfig(
     invalidLayoutSegments: [],
     separator: null,
     segmentOptions: {},
-    placement: "above",
+    placement: SETTING_DEFAULTS["powerline.placement"],
     invalidPlacement: null,
-    welcome: true,
+    welcome: SETTING_DEFAULTS["powerline.welcome"],
     stashSharpSShortcut: false,
     costAlert: null,
     customItemsAuto: false,
@@ -84,7 +85,7 @@ export function parsePowerlineConfig(
     presets: {},
     segmentLabels: {},
     appearance: {},
-    motionLevel: "full",
+    motionLevel: SETTING_DEFAULTS["powerline.motionLevel"],
   };
 
   const directPreset = normalizePreset(value, presets);
@@ -138,7 +139,10 @@ export function parsePowerlineConfig(
     segmentOptions: normalizeSegmentOptions(value),
     placement,
     invalidPlacement,
-    welcome: value.welcome !== false,
+    welcome:
+      typeof value.welcome === "boolean"
+        ? value.welcome
+        : SETTING_DEFAULTS["powerline.welcome"],
     stashSharpSShortcut: value.stashSharpSShortcut === true,
     costAlert: normalizeCostAlert(value.costAlert),
     customItemsAuto:
@@ -149,7 +153,9 @@ export function parsePowerlineConfig(
     presets: customPresetDefs,
     segmentLabels: normalizeSegmentLabels(value.segmentLabels),
     appearance: normalizeAppearance(value.appearance),
-    motionLevel: isMotionLevel(value.motionLevel) ? value.motionLevel : "full",
+    motionLevel: isMotionLevel(value.motionLevel)
+      ? value.motionLevel
+      : SETTING_DEFAULTS["powerline.motionLevel"],
   };
 }
 

package/src/config/settings-registry.ts

@@ -0,0 +1,118 @@
+/**
+ * Canonical metadata for settings exposed by Wishcraft.
+ *
+ * Keep defaults, edit kinds, choices, grouping and operator copy here. Runtime
+ * parsers may consume the same defaults without depending on the TUI layer.
+ */
+import { MOTION_LEVELS } from "../motion/accessibility.ts";
+import { STRUCTURAL_PRESET_NAMES } from "./types.ts";
+
+export type SettingValue = boolean | string | number;
+export type SettingKind = "toggle" | "select" | "text" | "number";
+export type SettingGroupId = "status" | "vibes" | "skills" | "harness" | "shortcuts";
+
+interface SettingDefinitionBase {
+  id: string;
+  path: string;
+  group: SettingGroupId;
+  label: string;
+  hint?: string;
+  description?: string;
+  restartRequired?: boolean;
+}
+
+export type SettingDefinition =
+  | (SettingDefinitionBase & { kind: "toggle"; defaultValue?: boolean })
+  | (SettingDefinitionBase & { kind: "select"; choices: readonly string[]; defaultValue?: string })
+  | (SettingDefinitionBase & { kind: "text"; defaultValue?: string })
+  | (SettingDefinitionBase & { kind: "number"; defaultValue?: number });
+
+export interface SettingGroupDefinition {
+  id: SettingGroupId;
+  title: string;
+}
+
+export const SETTING_DEFAULTS = {
+  "powerline.preset": "default",
+  "powerline.placement": "above",
+  "powerline.welcome": true,
+  "powerline.motionLevel": "full",
+  "powerline.segmentOptions.tps.windowMs": 1000,
+  "wishcraft.readHints": true,
+  "wishcraft.hooksEnabled": true,
+  "wishcraft.repairsEnabled": true,
+} as const satisfies Record<string, SettingValue>;
+
+export const SETTING_GROUPS = [
+  { id: "status", title: "Status bar" },
+  { id: "vibes", title: "Welcome & vibes" },
+  { id: "skills", title: "Skills" },
+  { id: "harness", title: "Hooks & repairs (harness)" },
+  { id: "shortcuts", title: "Shortcuts" },
+] as const satisfies readonly SettingGroupDefinition[];
+
+const SEPARATORS = [
+  "powerline", "powerline-thin", "slash", "pipe", "block", "none",
+  "ascii", "dot", "chevron", "star",
+] as const;
+const STATUS_PRESETS = ["default", "minimal", "compact", "full", "nerd", "ascii", "chef"] as const;
+
+export const SETTINGS_REGISTRY = [
+  { id: "status.preset", path: "powerline.preset", group: "status", label: "Preset", kind: "select", choices: STATUS_PRESETS, defaultValue: SETTING_DEFAULTS["powerline.preset"] },
+  { id: "appearance.base", path: "powerline.appearance.base", group: "status", label: "Structural base", kind: "select", choices: STRUCTURAL_PRESET_NAMES, hint: "colors and motion for Signal; layout preset stays separate" },
+  { id: "motion.level", path: "powerline.motionLevel", group: "status", label: "Motion level", kind: "select", choices: MOTION_LEVELS, defaultValue: SETTING_DEFAULTS["powerline.motionLevel"], hint: "full · reduced · functional · off" },
+  { id: "status.separator", path: "powerline.separator", group: "status", label: "Separator", kind: "select", choices: SEPARATORS },
+  { id: "status.placement", path: "powerline.placement", group: "status", label: "Placement", kind: "select", choices: ["above", "below"], defaultValue: SETTING_DEFAULTS["powerline.placement"] },
+  { id: "status.path.mode", path: "powerline.segmentOptions.path.mode", group: "status", label: "Path mode", kind: "select", choices: ["basename", "abbreviated", "full"] },
+  { id: "status.path.maxLength", path: "powerline.segmentOptions.path.maxLength", group: "status", label: "Path max length", kind: "number", hint: "0 = unlimited" },
+  { id: "status.time.format", path: "powerline.segmentOptions.time.format", group: "status", label: "Time format", kind: "select", choices: ["12h", "24h"] },
+  { id: "status.time.seconds", path: "powerline.segmentOptions.time.showSeconds", group: "status", label: "Time seconds", kind: "toggle" },
+  { id: "status.git.hostIcons", path: "powerline.segmentOptions.git.hostIcon", group: "status", label: "Git host icons", kind: "toggle" },
+  { id: "status.git.aheadBehind", path: "powerline.segmentOptions.git.showAheadBehind", group: "status", label: "Git ahead/behind", kind: "toggle" },
+  { id: "status.git.latestCommit", path: "powerline.segmentOptions.git.showCommit", group: "status", label: "Git latest commit", kind: "toggle" },
+  { id: "status.context.format", path: "powerline.segmentOptions.context.format", group: "status", label: "Context format", kind: "select", choices: ["full", "percent"] },
+  { id: "status.cacheRead.format", path: "powerline.segmentOptions.cache_read.format", group: "status", label: "Cache-read format", kind: "select", choices: ["tokens", "percent", "both"] },
+  { id: "status.cost.display", path: "powerline.segmentOptions.cost.subscriptionDisplay", group: "status", label: "Cost display", kind: "select", choices: ["subscription", "reported-cost", "both"] },
+  { id: "status.cost.currency", path: "powerline.segmentOptions.cost.currency", group: "status", label: "Currency", kind: "text" },
+  { id: "status.ports.udp", path: "powerline.segmentOptions.openPorts.includeUdp", group: "status", label: "Ports include UDP", kind: "toggle" },
+  { id: "status.tps.windowMs", path: "powerline.segmentOptions.tps.windowMs", group: "status", label: "TPS window (ms)", kind: "number", defaultValue: SETTING_DEFAULTS["powerline.segmentOptions.tps.windowMs"], hint: "default 1000" },
+  { id: "status.tps.mode", path: "powerline.segmentOptions.tps.mode", group: "status", label: "TPS mode", kind: "select", choices: ["both", "out", "in"] },
+  { id: "status.tps.label", path: "powerline.segmentLabels.tps", group: "status", label: "TPS label", kind: "text", hint: "empty = no label" },
+  { id: "welcome.enabled", path: "powerline.welcome", group: "vibes", label: "Welcome overlay", kind: "toggle", defaultValue: SETTING_DEFAULTS["powerline.welcome"], hint: "on = overlay at startup, off = no welcome" },
+  { id: "welcome.lanternMotion", path: "wishcraft.welcome.animateLantern", group: "vibes", label: "Animate wishcraft lantern", kind: "toggle", hint: "flicker on the lantern" },
+  { id: "skills.inline", path: "wishcraft.inlineSkills", group: "skills", label: "Inline expand /command and $skill", kind: "toggle", hint: "needs a restart to take effect", restartRequired: true },
+  { id: "skills.readHints", path: "wishcraft.readHints", group: "skills", label: "Read hints", kind: "toggle", defaultValue: SETTING_DEFAULTS["wishcraft.readHints"], hint: "off = no continuation hint after partial reads" },
+  { id: "harness.hooks", path: "wishcraft.hooksEnabled", group: "harness", label: "Hooks enabled", kind: "toggle", defaultValue: SETTING_DEFAULTS["wishcraft.hooksEnabled"], hint: "gate for configured preToolUse / postToolUse / sessionStart hooks" },
+  { id: "harness.repairs", path: "wishcraft.repairsEnabled", group: "harness", label: "Tool-input repairs", kind: "toggle", defaultValue: SETTING_DEFAULTS["wishcraft.repairsEnabled"], hint: "null-for-optional, auto-link, json-array, path aliases" },
+  { id: "budget.dailyTokens", path: "wishcraft.tokenBudget.daily", group: "harness", label: "Daily token budget", kind: "number", hint: "colours the cost segment; never blocks. 0 = off" },
+  { id: "shortcut.menu", path: "powerlineShortcuts.menu", group: "shortcuts", label: "Menu", kind: "text", hint: "e.g. alt+p" },
+  { id: "shortcut.info", path: "powerlineShortcuts.info", group: "shortcuts", label: "Info", kind: "text" },
+  { id: "shortcut.stash", path: "powerlineShortcuts.stashHistory", group: "shortcuts", label: "Stash", kind: "text" },
+  { id: "shortcut.idea", path: "powerlineShortcuts.ideaCapture", group: "shortcuts", label: "Idea", kind: "text" },
+  { id: "shortcut.queue", path: "powerlineShortcuts.queueOpen", group: "shortcuts", label: "Queue", kind: "text" },
+] as const satisfies readonly SettingDefinition[];
+
+const SETTINGS_BY_PATH = new Map<string, SettingDefinition>(SETTINGS_REGISTRY.map((item) => [item.path, item]));
+const SETTINGS_BY_ID = new Map<string, SettingDefinition>(SETTINGS_REGISTRY.map((item) => [item.id, item]));
+
+export function getSettingDefinition(pathOrId: string): SettingDefinition | undefined {
+  return SETTINGS_BY_PATH.get(pathOrId) ?? SETTINGS_BY_ID.get(pathOrId);
+}
+
+export function effectiveSettingValue(
+  definition: SettingDefinition,
+  storedValue: unknown,
+): SettingValue | null {
+  if (validateSettingValue(definition, storedValue)) return storedValue;
+  return definition.defaultValue ?? null;
+}
+
+export function validateSettingValue(
+  definition: SettingDefinition,
+  value: unknown,
+): value is SettingValue {
+  if (definition.kind === "toggle") return typeof value === "boolean";
+  if (definition.kind === "number") return typeof value === "number" && Number.isFinite(value);
+  if (definition.kind === "text") return typeof value === "string";
+  return typeof value === "string" && definition.choices.includes(value);
+}

package/src/config/structural-presets.ts

@@ -23,6 +23,7 @@ import { STRUCTURAL_PRESET_NAMES } from "./types.ts";
 export { STRUCTURAL_PRESET_NAMES };
 import type { MotionEvent } from "../motion/types.ts";
 import { defaultMotionFor } from "../motion/catalog.ts";
+import { resolveAppearance } from "../extension/contrib/appearance.ts";
 
 function tokens(partial: Partial<WishcraftTokens>): Partial<WishcraftTokens> {
   return partial;
@@ -513,7 +514,11 @@ export function isStructuralPresetName(name: string): name is StructuralPresetNa
 }
 
 export function getStructuralPreset(name: StructuralPresetName): StructuralPresetDef {
-  return STRUCTURAL_PRESETS[name];
+  return resolveAppearance(STRUCTURAL_PRESETS[name]);
+}
+
+export function getEffectivePreset(name: StructuralPresetName): StructuralPresetDef {
+  return getStructuralPreset(name);
 }
 
 /** Display name for a stored base, or the raw value when it is not structural. */

package/src/core/frontmatter.ts

@@ -42,14 +42,15 @@ export function stripFrontmatter(content: string): string {
 export interface SkillFrontmatter {
 	name: string | null;
 	description: string | null;
+	trigger: string | null;
 }
 
 /**
- * Parse minimal YAML frontmatter (name/description) from a skill file.
+ * Parse minimal YAML frontmatter (name/description/trigger) from a skill file.
  * Returns nulls when the keys are absent or there is no frontmatter block.
  */
 export function parseSkillFrontmatter(content: string): SkillFrontmatter {
-	const fm: SkillFrontmatter = { name: null, description: null };
+	const fm: SkillFrontmatter = { name: null, description: null, trigger: null };
 	const lines = content.split("\n");
 
 	if (lines[0]?.trim() !== "---") {
@@ -76,6 +77,8 @@ export function parseSkillFrontmatter(content: string): SkillFrontmatter {
 			fm.name = value || null;
 		} else if (key === "description" && fm.description === null) {
 			fm.description = value || null;
+		} else if (key === "trigger" && fm.trigger === null) {
+			fm.trigger = value ? value.replace(/^\//, "") : null;
 		}
 	}
 

package/src/extension/contrib/appearance.ts

@@ -0,0 +1,91 @@
+import type { StructuralPresetDef, StructuralPresetName } from "../../config/types.ts";
+
+// ponytail: appearance contributions are data patches, not loaders. One preset may have many patches; last wins per field.
+
+type SignalPatch = Omit<Partial<StructuralPresetDef["signal"]>, "separators" | "caps"> & {
+  separators?: Partial<StructuralPresetDef["signal"]["separators"]>;
+  caps?: Partial<StructuralPresetDef["signal"]["caps"]>;
+};
+
+type ChromePatch = Omit<Partial<StructuralPresetDef["chrome"]>, "corners" | "dividers"> & {
+  corners?: Partial<StructuralPresetDef["chrome"]["corners"]>;
+  dividers?: Partial<StructuralPresetDef["chrome"]["dividers"]>;
+};
+
+export type AppearancePresetPatch = Omit<
+  Partial<StructuralPresetDef>,
+  "name" | "tokens" | "signal" | "chrome" | "glyphs"
+> & {
+  tokens?: StructuralPresetDef["tokens"];
+  signal?: SignalPatch;
+  chrome?: ChromePatch;
+  glyphs?: Partial<StructuralPresetDef["glyphs"]>;
+};
+
+const patches = new Map<StructuralPresetName, AppearancePresetPatch[]>();
+
+/** Register an appearance-only patch for a structural preset. Invalid input is rejected without throwing. */
+export function registerAppearanceContribution(
+  preset: StructuralPresetName,
+  patch: AppearancePresetPatch,
+): boolean {
+  if (!preset || typeof patch !== "object" || patch === null) return false;
+  if (Array.isArray(patch) || "name" in patch) return false;
+  const list = patches.get(preset) ?? [];
+  list.push({ ...patch });
+  patches.set(preset, list);
+  return true;
+}
+
+/** Return registered patches for a preset in application order. */
+export function getAppearancePatches(
+  preset: StructuralPresetName,
+): readonly AppearancePresetPatch[] {
+  return patches.get(preset) ?? [];
+}
+
+/** Clear all registered appearance contributions. Primarily used for isolation in tests and reloads. */
+export function clearAppearanceContributions(): void {
+  patches.clear();
+}
+
+/** Resolve a structural preset with all contributed patches while preserving nested defaults and preset identity. */
+export function resolveAppearance(base: StructuralPresetDef): StructuralPresetDef {
+  const list = patches.get(base.name as StructuralPresetName);
+  if (!list || list.length === 0) return base;
+  let out: StructuralPresetDef = { ...base };
+  for (const patch of list) {
+    out = {
+      ...out,
+      ...patch,
+      name: base.name,
+      tokens: patch.tokens ? { ...out.tokens, ...patch.tokens } : out.tokens,
+      signal: patch.signal
+        ? {
+            ...out.signal,
+            ...patch.signal,
+            separators: patch.signal.separators
+              ? { ...out.signal.separators, ...patch.signal.separators }
+              : out.signal.separators,
+            caps: patch.signal.caps
+              ? { ...out.signal.caps, ...patch.signal.caps }
+              : out.signal.caps,
+          }
+        : out.signal,
+      chrome: patch.chrome
+        ? {
+            ...out.chrome,
+            ...patch.chrome,
+            corners: patch.chrome.corners
+              ? { ...out.chrome.corners, ...patch.chrome.corners }
+              : out.chrome.corners,
+            dividers: patch.chrome.dividers
+              ? { ...out.chrome.dividers, ...patch.chrome.dividers }
+              : out.chrome.dividers,
+          }
+        : out.chrome,
+      glyphs: patch.glyphs ? { ...out.glyphs, ...patch.glyphs } : out.glyphs,
+    };
+  }
+  return out;
+}

package/src/extension/contrib/registry.ts

@@ -0,0 +1,42 @@
+import type { ContributedDeckRoute, ContributedSignalSource } from "./types.ts";
+
+// ponytail: single in-memory registry, no new runtime — data/callback contracts only.
+// A failing contribution never takes down Signal or Deck — callers must isolate.
+
+const deckRoutes = new Map<string, ContributedDeckRoute>();
+const signalSources = new Map<string, ContributedSignalSource>();
+
+function isValidId(id: string): boolean {
+  return /^[a-z0-9][a-z0-9-_]*$/.test(id);
+}
+
+export function registerDeckRoute(route: ContributedDeckRoute): boolean {
+  if (!route || typeof route.id !== "string" || !isValidId(route.id)) return false;
+  if (typeof route.label !== "string" || !route.label.trim()) return false;
+  if (deckRoutes.has(route.id)) return false;
+  if (route.jumpKey != null && !/^[a-z0-9]$/.test(route.jumpKey)) return false;
+  deckRoutes.set(route.id, { ...route, label: route.label.trim() });
+  return true;
+}
+
+export function registerSignalSource(source: ContributedSignalSource): boolean {
+  if (!source || typeof source.id !== "string" || !isValidId(source.id)) return false;
+  if (typeof source.label !== "string" || !source.label.trim()) return false;
+  if (signalSources.has(source.id)) return false;
+  signalSources.set(source.id, { ...source });
+  return true;
+}
+
+export function getContributedDeckRoutes(): readonly ContributedDeckRoute[] {
+  return [...deckRoutes.values()];
+}
+
+export function getContributedSignalSources(): readonly ContributedSignalSource[] {
+  return [...signalSources.values()];
+}
+
+/** Test helper — clears the registry. */
+export function clearContributions(): void {
+  deckRoutes.clear();
+  signalSources.clear();
+}

package/src/extension/contrib/types.ts

@@ -0,0 +1,20 @@
+export type DeckRouteId = string;
+
+export interface ContributedDeckRoute {
+  id: DeckRouteId;
+  label: string;
+  description?: string;
+  jumpKey?: string;
+}
+
+export interface ContributedSignalSource {
+  id: string;
+  label: string;
+  /** Called on each Signal repaint; must not throw. */
+  render?: (ctx: unknown) => string | null;
+}
+
+export interface ContributedMotion {
+  id: string;
+  name: string;
+}

package/src/extension/core/state.ts

@@ -1,5 +1,6 @@
 import type { PowerlineConfig } from "../../config/powerline-config.ts";
 import type { StatusLinePreset } from "../../config/types.ts";
+import { SETTING_DEFAULTS } from "../../config/settings-registry.ts";
 import { PRESETS } from "../../config/presets.ts";
 import { BashTranscriptStore } from "../../../bash-mode/transcript.ts";
 import { BashCompletionEngine } from "../../../bash-mode/completion.ts";
@@ -31,7 +32,7 @@ import type { RuntimeState } from "./types.ts";
 // ═══════════════════════════════════════════════════════════════════════════
 
 export let config: PowerlineConfig = {
-  preset: "default",
+  preset: SETTING_DEFAULTS["powerline.preset"],
   customItems: [],
   disabledSegments: [],
   invalidDisabledSegments: [],
@@ -39,9 +40,9 @@ export let config: PowerlineConfig = {
   invalidLayoutSegments: [],
   separator: null,
   segmentOptions: {},
-  placement: "above",
+  placement: SETTING_DEFAULTS["powerline.placement"],
   invalidPlacement: null,
-  welcome: true,
+  welcome: SETTING_DEFAULTS["powerline.welcome"],
   stashSharpSShortcut: false,
   costAlert: null,
   customItemsAuto: false,
@@ -50,7 +51,7 @@ export let config: PowerlineConfig = {
   presets: {},
   segmentLabels: {},
   appearance: {},
-  motionLevel: "full",
+  motionLevel: SETTING_DEFAULTS["powerline.motionLevel"],
 };
 
 export function setConfig(next: PowerlineConfig): void {

package/src/extension/hooks/hooks-config.ts

@@ -19,6 +19,8 @@
  * ---------------------------------------------------------------------------
  */
 
+import { SETTING_DEFAULTS } from "../../config/settings-registry.ts";
+
 export type HookEventName = "preToolUse" | "postToolUse" | "sessionStart" | "turnEnd";
 
 export interface HookCommand {
@@ -81,7 +83,10 @@ export function parseHooksSettings(
   wishcraftSettings: unknown,
 ): { enabled: boolean; hooks: WishcraftHooksSettings } {
   if (!isRecord(wishcraftSettings)) return { enabled: false, hooks: {} };
-  const enabled = wishcraftSettings.hooksEnabled !== false;
+  const enabled =
+    typeof wishcraftSettings.hooksEnabled === "boolean"
+      ? wishcraftSettings.hooksEnabled
+      : SETTING_DEFAULTS["wishcraft.hooksEnabled"];
   const raw = wishcraftSettings.hooks;
   if (!isRecord(raw)) return { enabled, hooks: {} };
   return {