@groeponline/pi-wishcraft 1.4.11 → 1.4.13

package/AGENTS.md

@@ -1,102 +1,314 @@
-# AGENTS.md
-
-Guidance for AI agents (and humans) working on this repository.
-
-## What this project is
-
-pi-wishcraft is a powerline-style status bar and wishcraft interaction layer for the `pi`
-coding agent: status segments, welcome overlay/header, working "vibes" loading
-messages, a queue + idea inbox, bash mode, prompt/stash history, and full
-user customization.
-
-## Repository layout
-
-- `index.ts` — package entry: the public barrel. It re-exports the default
-  activation function and the documented public API (`resolveShortcutConfig`,
-  `parseBashModeSettings`, `PowerlineShortcuts`). Keep it a barrel; no
-  implementation lives here.
-- `src/` — the proxy-free extension runtime, organized by domain:
-  - `src/extension/` — the extension runtime, organized into domain subfolders:
-    `core/` (constants, types, `state.ts` hub, segment-context), `commands/`
-    (slash commands, queue commands, bash-mode actions, vibe command),
-    `session/` (activation, session lifecycle, git invalidation, stale-context),
-    `ui/` (custom editor, layout, menu views, powerline widgets, status-line
-    renderers), `history/` (prompt + stash history), `queue/` (queue context +
-    integration), `settings/` (settings IO), `shortcuts/` (shortcut config +
-    router), `welcome/` (welcome control + integration), `skills/` (inline
-    invocation). Leaf modules keep the dependency graph acyclic: shared types
-    and constants live in `core/`, queue/welcome callbacks are wired through
-    leaves or `RuntimeState`, and `core/state.ts` is the hub that only has
-    inbound edges. Verify with `npx madge --circular src index.ts bash-mode
-    queue`.
-  - `src/config/` — powerline config parsing, presets, types, segment ids/options.
-  - `src/segments/` — segment registry and the segment renderers.
-  - `src/theme/` — colors, icons, separators, theme loading.
-  - `src/usage/` — token stats, context usage, currency rates.
-  - `src/welcome/` — welcome header/overlay rendering and discovery.
-  - `src/working-vibes/` — vibe theme storage, generation, manager.
-  - `src/git/`, `src/shell/`, `src/editor/`, `src/render/`, `src/paths/`,
-    `src/shortcuts/`, `src/lifecycle/` — small single-purpose domains.
-- `bash-mode/` — managed shell session, transcript store, completion engine.
-- `queue/` — file-backed queue/inbox store and types.
-- `tests/` — flat `node:test` suite (`tests/*.test.ts`); structural tests read
-  the module under test from `src/`, never from `index.ts` source text.
-- `scripts/release.mjs` — zero-dep release helper (bump, CHANGELOG, tag).
-
-## Rules
-
-- **No root-level monofiles.** Implementation lives under `src/` organized by
-  domain; `index.ts` is only a barrel. Import implementation via
-  `src/**` paths (or `bash-mode/`, `queue/`).
-- **Module size:** when a file exceeds ~450 lines, split it along domain
-  boundaries (e.g. command handlers out of `commands.ts`, git invalidation
-  out of `session-lifecycle.ts`). Prefer many cohesive small modules.
-- **No circular imports.** Domain modules must not import back into
-  `src/extension/core/state.ts` for callbacks; move the callback into a leaf module
-  (e.g. `welcome-control.ts`) or wire it through `RuntimeState`.
-- **Bun/Node-native TS:** `import` paths carry `.ts` extensions
-  (`allowImportingTsExtensions`), `node:`-prefixed builtins, `node --test`
-  with type stripping. No build step.
-- **English UI:** operator overlays, notify strings, and `/wishcraft` copy are
-  English. Do not add Dutch UI strings.
-- **Tests:** behavior changes in `src/` need a focused regression test near
-  the existing tests for that subsystem; structural tests assert on module
-  files in `src/` (never `index.ts`).
-
-## Commands
+# Repository Guidelines
+
+## Project Overview
+
+`pi-wishcraft` is an operator cockpit extension for the **Pi** coding agent (`@earendil-works/pi-coding-agent`). It provides a powerline-style status bar, welcome overlay/header, working "vibes" loading messages, a file-backed idea queue, sticky Bash mode with PTY sessions, inline skill invocation, command-level hooks/policy controls, and a fullscreen Skill Studio. The package ships as a Pi extension rooted at `./index.ts` and is published to npm as `@groeponline/pi-wishcraft`.
+
+## Architecture & Data Flow
+
+### Bootstrap & Runtime Hub
+
+The extension bootstraps from `index.ts`, which re-exports `powerlineFooter` from `src/extension/session/activate.ts`. Activation reads Pi settings, parses powerline config, creates a mutable `RuntimeState` (via `createRuntimeState` in `src/extension/core/state.ts`), and registers Pi lifecycle hooks, commands, segments, presets, shortcuts, skills, and bash-mode sessions.
+
+`src/extension/core/state.ts` is the **central mutable hub** — it holds `config`, schedulers, and derived caches. All runtime mutations flow through `RuntimeState` and callback hooks (`requestStatusRender`, `requestImmediateStatusRender`, `resetLayoutCache`, `dispatchSignalEvent`). Leaf modules consume and extend this hub but never import sibling leaves directly.
+
+### Rendering Pipeline
+
+The render pipeline is a pure, acyclic chain:
+
+1. **SegmentContext** is built read-only by `src/extension/core/segment-context.ts` from `RuntimeState`, config, theme, git state, and usage data.
+2. **Segment renderers** are dispatched through `src/segments/registry.ts` — a fault-isolated `renderSegment` that maps segment IDs to pure render functions.
+3. **Status line composition** happens in `src/render/v2-entry.ts`, which orders segments, inserts the motion rail from `src/render/motion-rail.ts`, then delegates painting to `src/render/paint.ts` and `src/render/v2-adapter.ts`.
+
+### Motion & Signal
+
+The motion engine (`src/motion/*`) defines a catalog of animations (`src/motion/catalog.ts`), a centralized scheduler (`src/motion/scheduler.ts`), and an accessibility policy (`src/motion/policy.ts`). The Signal controller (`src/signal/controller.ts`) leases one motion consumer per runtime event and manages the lifecycle of rendered signals on the status-line rail.
+
+### Leaf Domains
+
+Each domain operates through `RuntimeState` callbacks:
+
+- **bash-mode/** — PTY-managed shell sessions, transcripts, ghost suggestions, completion engine
+- **queue/** — file-backed JSONL queue/inbox store with aliases and retention
+- **working-vibes/** — themed loading message generation and persistence
+- **welcome/** — fullscreen TUI overlay with branded layout and countdown
+- **usage/** — token/cost/context ledger, TPS ring, daily budget
+- **theme/** — color resolution, icons, separators, token mapping
+- **studio/** — Skill Studio UI component, Deck renderer, advice engine
+- **skills/** — skill registry, manager, inline invocation, doctor, status
+- **hooks/** — session/context/tool hooks, policy engine, repairs
+- **settings/** — settings IO, config commands, appearance write-back
+
+### Acyclic Dependency Rule
+
+Domain modules must not import back into the hub for callbacks. Shared types and constants live in `src/extension/core/`. Verify no circular imports:
+
+```bash
+npm run circular
+# → madge --circular src index.ts bash-mode queue
+```
+
+## Key Directories
+
+| Directory | Purpose |
+|---|---|
+| `src/` | Extension runtime, organized by domain (core, config, segments, render, signal, motion, theme, welcome, working-vibes, usage, studio, skills, hooks, settings, shortcuts, history, queue, contrib) |
+| `src/extension/` | Pi extension runtime: `core/` (hub, types, constants), `session/` (activation, lifecycle), `ui/` (deck, layout), `commands/`, `shortcuts/`, `queue/`, `welcome/`, `skills/`, `hooks/`, `settings/`, `history/`, `contrib/` |
+| `src/config/` | Powerline config parsing, presets, settings registry, tokens |
+| `src/segments/` | Segment registry and builtin renderers (core, system, usage, custom) |
+| `src/theme/` | Colors, icons, separators, token mapping |
+| `src/render/` | Paint primitives, v2 adapter, layout, motion-rail |
+| `src/motion/` | Motion catalog, scheduler, policy, types, gallery, composer |
+| `src/signal/` | Signal controller and event dispatching |
+| `src/welcome/` | Welcome overlay, renderer, art, layout |
+| `src/studio/` | Studio UI component, deck, advice engine |
+| `bash-mode/` | Standalone PTY shell session management (editor, transcript, completion, forward mode) |
+| `queue/` | Standalone file-backed queue store and types |
+| `tests/` | Flat `node:test` suite (`tests/*.test.ts`), helpers in `tests/helpers/`, fixtures in `tests/fixtures/` |
+| `docs/` | Operator guides (configuration, commands, bash-mode, segments, skills, etc.) |
+| `docs/design/` | vNext design specs (not operator how-to docs) |
+| `.compound-engineering/` | CE overlay: tracked `config.yaml`, artifacts, plans |
+
+## Development Commands
 
 ```bash
+# Install dependencies
 npm ci
-npm run typecheck      # tsc --noEmit (strict)
-npm test               # node --experimental-strip-types --test tests/**/*.test.ts
+
+# Type check (strict, no emit)
+npm run typecheck
+
+# Run all tests
+npm test
+
+# Check for circular imports
+npm run circular
+
+# Full package contract verification (for publish preparation)
+npm run verify:package
+
+# Local preview server (Deck/Signal/motion surfaces)
+npm run preview
+
+# Dockerized parallel testing (typecheck + test + circular)
+scripts/docker-test.sh [-n N]
+
+# Cloud agent bootstrap (Node 24, pi CLI install)
+scripts/cloud-agent-install.sh
+scripts/cloud-agent-start.sh
+```
+
+### Release Flow
+
+Releases are CI-driven via GitHub Actions:
+
+```bash
+# Locally: bump version, rewrite CHANGELOG, tag, optional push
+node scripts/release.mjs          # or: npm run release
+
+# Publish to npm (CI handles auth)
+scripts/npm-publish.sh
+
+# Create GitHub Release
+scripts/github-release.sh
+```
+
+CI workflows (`.github/workflows/`):
+- `test.yml` — Node 24, typecheck, test, circular, verify:package, npm audit
+- `release.yml` — reuses test.yml, prepares release-candidate branch
+- `promote-release-candidate.yml` — promotes verified SHA to main, tags, dispatches publish
+
+## Code Conventions & Common Patterns
+
+### Module Structure
+
+- **No root-level monofiles**: implementation lives under `src/` by domain; `index.ts` is a barrel only
+- **Module size**: split files exceeding ~450 lines along domain boundaries
+- **TypeScript**: `.ts` extensions on all imports (`allowImportingTsExtensions`), `node:`-prefixed builtins, strict mode, no build step
+- **Entry point**: `index.ts` re-exports `powerlineFooter` and shortcut helpers — keep it a barrel, no implementation
+
+### Import Paths & Dependency Direction
+
+```typescript
+// Correct: import via domain paths
+import { SEGMENTS } from "src/segments/registry.ts";
+import { createRuntimeState } from "src/extension/core/state.ts";
+
+// Incorrect: avoid importing implementation from index.ts barrel
+import { powerlineFooter } from "./index.ts"; // tests must not do this
+```
+
+- Tests import from `src/<domain>/*` module files directly, **never** from `index.ts`
+- Domain modules must not import back into the hub for callbacks — use `RuntimeState` + callback hooks
+
+### State Management
+
+`RuntimeState` (from `src/extension/core/state.ts`) is the singleton mutable hub. It owns:
+- `config` — parsed powerline configuration
+- Motion/signal/render schedulers
+- Derived caches (segment context, layout)
+
+Leaf consumers receive `RuntimeState` plus callback hooks rather than importing sibling leaves directly.
+
+### Callback Wiring Pattern
+
+```typescript
+// Leaf modules receive hooks, do not import siblings
+function createRuntimeState(hooks: {
+  requestStatusRender: () => void;
+  requestImmediateStatusRender: () => void;
+  resetLayoutCache: () => void;
+}): RuntimeState
+```
+
+### Error Handling
+
+- Segment rendering is fault-isolated — a failing segment does not crash the status line
+- Policy engine evaluates pre/post tool hooks with deny/inject results
+- Hooks runner uses stdin JSON + timeout + process-group kill
+
+### Naming Conventions
+
+- Domain barrels: `src/<domain>/index.ts`
+- Segment files: `src/segments/{core,system,usage,custom}.ts`
+- Motion modules: `src/motion/{catalog,scheduler,policy,types}.ts`
+- Test files: `tests/<subsystem>.test.ts` (flat suite, descriptive names)
+
+## Important Files
+
+### Entry Points
+- `index.ts` — package barrel (re-exports `powerlineFooter`, `resolveShortcutConfig`, `parseBashModeSettings`, `PowerlineShortcuts`)
+- `src/extension/session/activate.ts` — activation bootstrap
+- `src/extension/core/state.ts` — `RuntimeState` hub, `createRuntimeState`
+- `src/extension/core/types.ts` — `RuntimeState` type definitions
+
+### Configuration
+- `src/config/parse.ts` — `parsePowerlineConfig`, `PowerlineConfig` interface
+- `src/config/settings-registry.ts` — operator settings definitions, defaults, validation
+- `src/config/structural-presets.ts` — structural preset definitions
+- `src/config/tokens.ts` — semantic token mapping
+
+### Rendering
+- `src/render/v2-entry.ts` — `renderStatusLineV2` (composed render entry)
+- `src/render/v2-adapter.ts` — layout adaptation for painting
+- `src/render/paint.ts` — painting primitives
+- `src/render/motion-rail.ts` — motion rail surface rendering
+
+### Segments
+- `src/segments/registry.ts` — `SEGMENTS` registry, `renderSegment` dispatcher
+- `src/segments/core.ts` — model, shell_mode, path, git, time, session, hostname
+- `src/segments/system.ts` — thinking, subagents, queue, extension_statuses, open ports/TPS
+- `src/segments/usage.ts` — token_in/out/total, cost, context_pct, cache_read/write
+- `src/segments/custom.ts` — custom registered/static segments
+
+### Signal & Motion
+- `src/signal/controller.ts` — `SignalRuntime` lifecycle
+- `src/signal/integration.ts` — event dispatcher
+- `src/motion/catalog.ts` — motion definitions, channel matrix
+- `src/motion/scheduler.ts` — shared `MotionScheduler`
+- `src/motion/policy.ts` — accessibility/policy filter
+
+### Bash Mode
+- `bash-mode/pty-session.ts` — PTY session abstraction
+- `bash-mode/session-factory.ts` — shell session creation
+- `bash-mode/transcript.ts` — `BashTranscriptStore`
+- `bash-mode/completion.ts` — completion engine
+
+### Queue
+- `queue/store.ts` — `PowerlineQueueStore` (filesystem-backed JSONL)
+- `queue/types.ts` — queue item/target/status types
+
+### Studio & Skills
+- `src/studio/component.ts` — fullscreen Skill Studio component
+- `src/studio/deck/render.ts` — Deck renderer
+- `src/studio/advise/engine.ts` — advice pane engine
+- `src/extension/skills/skill-registry.ts` — skill catalog
+- `src/extension/skills/skill-manager.ts` — skill management commands
+
+### Release & Verification
+- `scripts/release.mjs` — version bump, CHANGELOG rewrite, tag
+- `scripts/verify-package.mjs` — package contract checks (name, description, keywords, pi manifest, resources, peers)
+- `scripts/verify-pi-package-contract.mjs` — Pi package contract validation
+- `scripts/npm-publish.sh` — idempotent npm publish with marker-tag promotion
+- `scripts/github-release.sh` — GitHub Release creation
+- `scripts/gen-lantern.mjs` — generates lantern art pixel-grid module
+
+## Runtime/Tooling Preferences
+
+| Requirement | Detail |
+|---|---|
+| **Node** | v22.14 system default; Node 24 via nvm for CI and pi CLI (pi requires ≥22.19) |
+| **Package manager** | npm (lockfile v3) |
+| **TypeScript** | 5.9.3, strict mode, `NodeNext` module/resolution, `allowImportingTsExtensions`, no build step |
+| **Test runner** | Node built-in `node:test` with `--experimental-strip-types` type stripping |
+| **Circular import check** | `madge --circular src index.ts bash-mode queue` (via `npm run circular`) |
+| **Import style** | `.ts` extensions on all imports, `node:`-prefixed builtins |
+| **Pi CLI** | Installed at `^0.84.0`; wrapped to run under Node 24 via nvm |
+| **Docker** | `fuse-overlayfs` storage driver for nested VM testing |
+| **Compound Engineering** | `.compound-engineering/` overlay; portable skills via `~/.agents/skills/ce-*`; native Cursor plugin disabled |
+
+## Testing & QA
+
+### Test Framework
+
+- **Runner**: Node's built-in `node:test` (flat per-file suites)
+- **Assertions**: `node:assert/strict`
+- **Type stripping**: `--experimental-strip-types` (no `tsc` compilation in tests)
+- **Invocation**: `npm test` runs `node --experimental-strip-types --test tests/**/*.test.ts`
+
+### Test Organization
+
+Tests are flat in `tests/` with supporting helpers and fixtures:
+
+- `tests/helpers/strip-ansi.ts` — shared ANSI stripping utility
+- `tests/fixtures/skill-template-golden.ts` — golden fixture for skill templates
+
+### Test Types
+
+| Type | Convention | Examples |
+|---|---|---|
+| **Structural tests** | Assert on module contracts: layout rules, config precedence, catalog/scheduler invariants, registry behavior | `effective-config.test.ts`, `render-v2.test.ts`, `tokens.test.ts`, `hooks.test.ts` |
+| **Behavior tests** | Assert runtime output: rendered strings, command execution, state changes, temp FS flows | `signal.test.ts`, `system-segments.test.ts`, `queue-store.test.ts`, `deck.test.ts` |
+| **Golden tests** | Pin exact rendered output or template text | `signal-golden.test.ts`, `skill-templates.test.ts` |
+
+### Import Conventions
+
+Tests import from `src/<domain>/*` module files directly — **never** from `index.ts`. For example:
+
+```typescript
+// Correct
+import { SEGMENTS } from "src/segments/registry.ts";
+
+// Incorrect — do not import from index.ts
+import { powerlineFooter } from "./index.ts";
+```
+
+### CI Verification Gates
+
+The `.github/workflows/test.yml` workflow enforces the full verification chain:
+
+```bash
+npm run typecheck     # tsc --noEmit
+npm test              # node --test
+npm run circular      # madge --circular
+npm run verify:package # verify-package.mjs + verify-pi-package-contract.mjs
+npm audit             # security audit
+```
+
+### Release Verification
+
+Before any publish, `prepublishOnly` runs the full chain:
+
+```bash
+tsc --noEmit && verify-package.mjs && verify-pi-package-contract.mjs
+```
+
+### Dockerized Parallel Testing
+
+For isolated, parallel CI runs:
+
+```bash
+scripts/docker-test.sh -n 4   # 4 parallel containers
 ```
 
-Run both before proposing any non-trivial change.
-
-Compound Engineering overlay: `.compound-engineering/` (tracked `config.yaml`, gitignored `config.local.yaml`). Artifact root `.compound-engineering/artifacts/`. Portable skills `~/.agents/skills/ce-*`; native Cursor plugin is fallback only when this overlay is absent.
-
-## Cursor Cloud specific instructions
-
-The Cloud Agent environment is provisioned so the extension can be tested both as
-a library and inside real `pi`, with Docker for containerized/parallel runs.
-
-- **Node:** the platform `node` on `PATH` is v22.14 (fine for `npm ci`,
-  `typecheck`, and the test suite, which use `--experimental-strip-types`).
-  Node 24 is available via `nvm` and is what CI uses.
-- **pi CLI:** installed and pinned to the wishcraft peer range
-  (`@earendil-works/pi-coding-agent` `>=0.81.0 <0.85.0`). pi requires Node
-  `>=22.19`, so the `pi` launcher is wrapped to run under the `nvm` Node 24.
-  `~/.pi/agent/settings.json` loads this checkout (`packages: ["/workspace"]`,
-  `preset: chef`) so `pi` renders the wishcraft welcome/powerline on startup.
-  Running a model needs a provider key (`/login`); the extension loads without
-  one.
-- **Docker:** `dockerd` runs with the `fuse-overlayfs` storage driver (required
-  in the nested VM). `scripts/cloud-agent-start.sh` starts it per boot;
-  `scripts/cloud-agent-install.sh` is the idempotent bootstrap (`npm ci` plus
-  self-healing pi setup).
-- **Containerized / parallel testing:** `scripts/docker-test.sh [-n N]` runs the
-  full check suite (`typecheck` + `test` + `circular`) in `node:24` containers,
-  each with an isolated copy of the tree, so `N` runs are safe in parallel.
-- **Publishing / pi.dev:** merges to `main` auto-publish to npm via the org
-  `NPM_TOKEN` (`.github/workflows/release.yml`), and pi.dev mirrors npm. Gate
-  the catalog contract with `npm run verify:package`.
+Each container runs `typecheck + test + circular` with a shared read-only `node_modules` bind mount.

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [1.4.13] - 2026-09-05
+
+## [1.4.12] - 2026-09-05
+
 ## [1.4.11] - 2026-08-30
 
 ## [1.4.10] - 2026-08-30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.4.11",
+  "version": "1.4.13",
   "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [
@@ -63,7 +63,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",
-    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.3",
     "@earendil-works/pi-tui": "^0.84.0",
     "@types/node": "24.13.3",
     "madge": "^8.0.0",

package/src/extension/skills/global-registry.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface GlobalRegistrySkill {
+  name: string;
+  description: string;
+  category: string;
+  family: string;
+  metaSkill: string | null;
+  role: string | null;
+  routerParent: string | null;
+  mounts: string[];
+  drift: boolean;
+  filePath: string;
+}
+
+interface RegistryPayload {
+  schema?: string;
+  skills?: unknown[];
+}
+
+export function globalRegistryPath(): string {
+  return process.env.CHEFGROEP_SKILL_REGISTRY?.trim() || join(homedir(), ".config", "chefgroep", "skill-registry", "skills.json");
+}
+
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+export function loadGlobalSkillRegistry(path = globalRegistryPath()): GlobalRegistrySkill[] {
+  if (!existsSync(path)) return [];
+  let payload: RegistryPayload;
+  try {
+    payload = JSON.parse(readFileSync(path, "utf8")) as RegistryPayload;
+  } catch {
+    return [];
+  }
+  if (payload.schema !== "chefgroep-global-skill-registry/v1" || !Array.isArray(payload.skills)) return [];
+  const out: GlobalRegistrySkill[] = [];
+  for (const raw of payload.skills) {
+    if (!raw || typeof raw !== "object") continue;
+    const skill = raw as Record<string, any>;
+    if (typeof skill.name !== "string" || typeof skill.description !== "string") continue;
+    const canonical = skill.canonical && typeof skill.canonical === "object" ? skill.canonical : {};
+    const canonicalPath = typeof canonical.path === "string" ? canonical.path : "";
+    out.push({
+      name: skill.name,
+      description: skill.description,
+      category: typeof skill.category === "string" ? skill.category : "general",
+      family: typeof skill.family === "string" ? skill.family : "general",
+      metaSkill: typeof skill.meta_skill === "string" ? skill.meta_skill : null,
+      role: typeof skill.role === "string" ? skill.role : null,
+      routerParent: typeof skill.router_parent === "string" ? skill.router_parent : null,
+      mounts: Array.isArray(skill.mounts) ? skill.mounts.filter((x: unknown): x is string => typeof x === "string") : [],
+      drift: skill.drift === true,
+      filePath: expandHome(canonicalPath),
+    });
+  }
+  return out;
+}

package/src/extension/skills/skill-registry.ts

@@ -14,6 +14,7 @@ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSy
 import { basename, dirname, join, relative } from "node:path";
 import { getAgentDir, getAgentPath } from "../../paths/agent-dirs.ts";
 import { parseSkillFrontmatter, stripFrontmatter } from "../../core/frontmatter.ts";
+import { loadGlobalSkillRegistry } from "./global-registry.ts";
 
 /** Category: where the skill came from. */
 export type SkillCategory = "global" | "project" | "prompts" | "extra";
@@ -39,6 +40,14 @@ export interface SkillEntry {
   frontmatterKeys: string[];
   /** Frontmatter trigger value (e.g. /test, /showcase). */
   trigger: string | null;
+  /** Machine-side ChefGroep routing metadata when the global registry is installed. */
+  routingCategory?: string;
+  routingFamily?: string;
+  metaSkill?: string | null;
+  role?: string | null;
+  routerParent?: string | null;
+  mounts?: string[];
+  registryDrift?: boolean;
   /** Diagnostic message (core diagnostics, or empty description). */
   warning?: string;
 }
@@ -108,6 +117,7 @@ export function setSkillCacheInvalidationHandler(handler: (() => void) | null):
 
 const usageCache = new Map<string, SkillUsage>();
 let usageLoaded = false;
+let usageLoadedFrom: string | null = null;
 
 /** Drop the discovery cache (the next read scans again). */
 export function invalidateSkillCache(): void {
@@ -340,11 +350,24 @@ export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
   );
   cachedAt = now;
   cachedCwd = cwd;
-  cachedEntries = [
+  const localEntries = [
     ...deduped.filter((e) => !looseNames.has(e.name)),
     ...loose,
     ...rejected,
-  ].sort((a, b) => a.name.localeCompare(b.name));
+  ];
+
+  // Enrich local Pi entries with routing metadata, but do not append
+  // registry-only skills here: generic Pi catalog/count semantics stay local.
+  const registry = loadGlobalSkillRegistry();
+  const registryByName = new Map(registry.map((r) => [r.name, r] as const));
+  for (const entry of localEntries) {
+    const r = registryByName.get(entry.name);
+    if (!r) continue;
+    entry.routingCategory = r.category; entry.routingFamily = r.family;
+    entry.metaSkill = r.metaSkill; entry.role = r.role; entry.routerParent = r.routerParent;
+    entry.mounts = r.mounts; entry.registryDrift = r.drift;
+  }
+  cachedEntries = localEntries.sort((a, b) => a.name.localeCompare(b.name));
   cachedPathMap = new Map(cachedEntries.map((e) => [e.name, e.filePath] as const));
   cachedTriggerMap = new Map(
     cachedEntries
@@ -354,6 +377,32 @@ export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
   return cachedEntries;
 }
 
+/** Full machine-side catalog for Skill Studio only. */
+export function loadSkillStudioCatalog(cwd: string = process.cwd()): SkillEntry[] {
+  const local = loadSkillCatalog(cwd).map((e) => ({ ...e }));
+  const localNames = new Set(local.map((e) => e.name));
+  const registryOnly: SkillEntry[] = loadGlobalSkillRegistry()
+    .filter((r) => !localNames.has(r.name))
+    .map((r) => {
+      let sizeBytes = 0, lineCount = 0, mtimeMs = 0;
+      let warning: string | undefined;
+      try {
+        const content = readFileSync(r.filePath, "utf8");
+        sizeBytes = Buffer.byteLength(content, "utf8");
+        lineCount = content.split("\n").length;
+        mtimeMs = statSync(r.filePath).mtimeMs;
+      } catch { warning = "registry source not readable on this host"; }
+      return {
+        name: r.name, description: r.description, filePath: r.filePath, baseDir: dirname(r.filePath),
+        isDirectorySkill: basename(r.filePath) === "SKILL.md", category: "extra" as SkillCategory,
+        disableModelInvocation: false, sizeBytes, lineCount, mtimeMs, frontmatterKeys: [], trigger: null, warning,
+        routingCategory: r.category, routingFamily: r.family, metaSkill: r.metaSkill, role: r.role,
+        routerParent: r.routerParent, mounts: r.mounts, registryDrift: r.drift,
+      };
+    });
+  return [...local, ...registryOnly].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 /** Compat: name → file path (for inline-invocation $skill). */
 export function getAvailableSkills(): Map<string, string> {
   loadSkillCatalog();
@@ -376,10 +425,13 @@ function usageFile(): string {
 }
 
 function loadUsage(): void {
-  if (usageLoaded) return;
+  const file = usageFile();
+  if (usageLoaded && usageLoadedFrom === file) return;
   usageLoaded = true;
+  usageLoadedFrom = file;
+  usageCache.clear();
   try {
-    const raw = readFileSync(usageFile(), "utf8");
+    const raw = readFileSync(file, "utf8");
     const parsed = JSON.parse(raw) as Record<string, SkillUsage>;
     for (const [name, u] of Object.entries(parsed)) {
       usageCache.set(name, { count: u.count ?? 0, lastUsed: u.lastUsed ?? 0 });

package/src/motion/index.ts

@@ -36,6 +36,7 @@ export {
   allowedChannels,
   allowsColorTransition,
   cadenceFor,
+  channelsForMotion,
   describeMotionEvent,
   effectiveLevel,
   prefersAsciiGlyphs,