@hienlh/ppm 0.23.9 → 0.23.11

package/docs/deployment-guide.md

@@ -533,6 +533,13 @@ models and serials, link speeds, driver and API versions. On Linux all of it com
 daemon; a field the host cannot measure is omitted rather than sent as `0`, and the UI renders an
 omitted field as an em dash.
 
+On macOS the same rows come from the kernel over `bun:ffi` (`host_statistics64`,
+`proc_pid_rusage`, the SMC, IOReport, CoreWLAN) plus one `ioreg`/`netstat`/`ifconfig` read a tick
+that every collector shares — again no root and no helper binary. The sensor reads are synchronous
+and hold the event loop while they run, so they are budgeted to about 10 ms a tick (SMC ≤ 4.7 ms,
+IOReport ~4 ms, the SSD's NAND sensor once every 10 s); `/api/health` measured p99 18 ms beside a
+full tier every 2 s.
+
 `/api/system/services*` is the Services page: `systemctl list-units` + one bulk `systemctl show`
 per scope (two spawns, not one per unit), with `journalctl -o json` behind the per-unit log. Unit
 actions (start/stop/restart/enable/disable) are separate authenticated routes and are confirmed in
@@ -540,6 +547,16 @@ the UI before they run. `/api/system/app-icon/:id` serves an application's own d
 it accepts `?token=` because an `<img>` cannot send an `Authorization` header, and it is safe to
 widen to because it takes an app id, never a path.
 
+On macOS the same routes talk to launchd instead: `launchctl print system`, `gui/<uid>` and
+`user/<uid>` (one spawn per domain — the user's jobs live in two, the GUI session's and the
+background one's), with the job's own stdout/stderr files — or, for a job that has none, the
+unified log since its process started (since boot when it is not running) — behind the per-job
+log. PPM's own job, every `com.apple.*` job and the whole system domain (which needs root) refuse
+the actions that would hurt, through the same function that greys out the buttons, and an app's
+own per-launch `application.*` job refuses every action. An app there is an application
+bundle, and its icon is the bundle's `.icns` converted by `sips` into a 64 px PNG under
+`<ppm dir>/app-icons/` — once per icon file, since the PNG is named after the icon's mtime.
+
 Each Linux process row also carries its swapped memory (`VmSwap` from `/proc/<pid>/status`) and a
 `unitKey` of `"<scope>:<unit>"` read from `/proc/<pid>/cgroup` — about 4.5 ms per full tick for 560
 processes, beside the 1.7 ms `/proc/<pid>/io` already costs. The Services page's per-unit CPU,

package/docs/design-guidelines.md

@@ -99,7 +99,7 @@ These rules MUST be followed when creating or modifying any UI component. PPM is
 ## Floating Windows
 
 Desktop-only window manager (`src/web/components/floating-window/`), hosting the OS File Explorer,
-team-member sessions, the System Monitor, and detached tabs (`tab-host`). Every kind shares one
+agent sessions, the System Monitor, and detached tabs (`tab-host`). Every kind shares one
 titlebar chrome — `WindowSkinChrome` resolves the active OS skin (Settings override, else host
 platform) and renders it, whatever the window's `kind` — and one PiP capability owned by the frame,
 not by any one kind. Any future floating-window feature must follow the same contract:
@@ -131,6 +131,11 @@ not by any one kind. Any future floating-window feature must follow the same con
   every skin renders the same PiP button, absent (not disabled, never a dead control that only
   explains itself) on browsers without `documentPictureInPicture`. The "Bring back" control shown
   while a window plays in PiP is a full ≥44×44px touch target like any other primary action.
+- **Portrait default for reading windows**: a window whose body is a live, scrolling read-only
+  feed (an agent/teammate's transcript) spawns portrait (9:16), pinned top-right, instead of the
+  landscape cascade every other kind uses — a step list reads top-to-bottom and wastes width in
+  landscape. Any future "reading" kind should follow suit; a workspace kind (explorer, terminal,
+  editor) keeps the landscape default.
 - **Tab-host windows** (a tab detached from its panel, plus its optional PiP step) follow the same
   desktop-only rule as every other kind: below `md`, both detach items are hidden from the tab
   context menu and any already-detached tabs reconcile back into the grid — a windowed tab is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.23.9",
+  "version": "0.23.11",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",

package/src/providers/codex-app-server/codex-history.ts

@@ -48,7 +48,7 @@ function safeParseArgs(raw: unknown): Record<string, unknown> {
 }
 
 /** rollout `function_call` (OpenAI Responses format) → PPM tool_use. */
-function fnCallToToolUse(p: Record<string, unknown>): ChatEvent {
+export function fnCallToToolUse(p: Record<string, unknown>): ChatEvent {
   const args = safeParseArgs(p.arguments);
   const command = typeof args.command === "string" ? args.command : "";
   const callId = typeof p.call_id === "string" ? p.call_id : undefined;
@@ -60,7 +60,7 @@ function fnCallToToolUse(p: Record<string, unknown>): ChatEvent {
 }
 
 /** rollout `custom_tool_call` (apply_patch / custom tools) → PPM tool_use. */
-function customToolCallToToolUse(p: Record<string, unknown>): ChatEvent {
+export function customToolCallToToolUse(p: Record<string, unknown>): ChatEvent {
   const callId = typeof p.call_id === "string" ? p.call_id : undefined;
   if (p.name === "apply_patch" && typeof p.input === "string") {
     const changes = parseApplyPatch(p.input);
@@ -70,7 +70,7 @@ function customToolCallToToolUse(p: Record<string, unknown>): ChatEvent {
 }
 
 /** Unknown `*_call` record → generic visible tool_use (never dropped). */
-function genericCallToToolUse(p: Record<string, unknown>): ChatEvent {
+export function genericCallToToolUse(p: Record<string, unknown>): ChatEvent {
   const callId = typeof p.call_id === "string" ? p.call_id : undefined;
   const tool = String(p.name ?? p.type ?? "tool");
   const input = p.input ?? safeParseArgs(p.arguments);
@@ -78,7 +78,7 @@ function genericCallToToolUse(p: Record<string, unknown>): ChatEvent {
 }
 
 /** rollout `function_call_output` / `custom_tool_call_output` → PPM tool_result. */
-function fnOutputToToolResult(p: Record<string, unknown>): ChatEvent {
+export function fnOutputToToolResult(p: Record<string, unknown>): ChatEvent {
   const output = typeof p.output === "string" ? p.output : JSON.stringify(p.output ?? "");
   const m = /exit code:\s*(\d+)/i.exec(output);
   return {

package/src/providers/codex-app-server/codex-provider.ts

@@ -86,7 +86,7 @@ const CODEX_SESSIONS_DIR = join(homedir(), ".codex", "sessions");
  * made a switched session come back empty and silently start over as a new
  * thread, since resume is only attempted when a rollout is found.
  */
-function codexSessionsDirs(sessionId?: string): string[] {
+export function codexSessionsDirs(sessionId?: string): string[] {
   const dirs: string[] = [];
   const boundId = sessionId ? getSessionCodexAccount(sessionId) : null;
   const accounts = listCodexAccounts();
@@ -1353,12 +1353,15 @@ export class CodexAppServerProvider implements AIProvider {
     this.skillsCache.clear();
   }
 
-  async listSkills(sessionId?: string): Promise<CodexSkill[]> {
-    const cwd = (sessionId ? getSessionProjectPath(sessionId) : null) || process.cwd();
+  async listSkills(sessionId?: string, cwdHint?: string): Promise<CodexSkill[]> {
+    const cwd = (sessionId ? getSessionProjectPath(sessionId) : null) || cwdHint || process.cwd();
     // Reuse the account already bound to the session; resolving afresh here
-    // would advance a round-robin strategy for a mere UI listing.
+    // would advance a round-robin strategy for a mere UI listing. A session with
+    // no binding yet (its first turn is being prepared) lists with the account
+    // that will certainly serve it, when that is knowable without choosing one:
+    // the ambient home can hold a different set of skills.
     const accountId = sessionId ? getSessionCodexAccount(sessionId) : null;
-    const home = (accountId ? getCodexAccount(accountId)?.home : null) ?? undefined;
+    const home = (accountId ? getCodexAccount(accountId)?.home : peekCodexAccount()?.home) ?? undefined;
 
     const key = `${cwd}\0${home ?? ""}`;
     const hit = this.skillsCache.get(key);

package/src/providers/codex-app-server/codex-rollout-tail-parser.ts

@@ -0,0 +1,203 @@
+import type { ChatEvent } from "../provider.interface.ts";
+import { stripSharedContext } from "../../shared/provider-context.ts";
+import { redactTruncate } from "./codex-redact.ts";
+import { completeLines, parseLine } from "./codex-rollout-header.ts";
+import { mapRolloutItem } from "./codex-rollout-items.ts";
+import { subagentToolResult, subagentToolUse } from "./codex-subagent-thread.ts";
+import {
+  customToolCallToToolUse, fnCallToToolUse, fnOutputToToolResult, genericCallToToolUse,
+} from "./codex-history.ts";
+
+/**
+ * Line-fed parser for ONE codex rollout, for the live Agent-session window.
+ *
+ * Unlike `rolloutMessageSteps` (`codex-history.ts`) this never groups events
+ * into user/assistant turns and never answers a "load more" request — it just
+ * turns each newly-written record into flat step events, in the order they
+ * were written, as the file grows. It must never change how history renders,
+ * so it is a separate reader over the same schema rather than a refactor of
+ * the existing one.
+ *
+ * A child rollout writes its OWN `session_meta` first and its parent's second
+ * (a forked context) — only the first describes the file, so every session_meta
+ * after the first is ignored entirely here, the same as `readRolloutHeader` does.
+ */
+
+/**
+ * First cli_version observed (2026-10-01 survey of ~3400 local rollouts)
+ * writing the newer `item_completed` record instead of the legacy
+ * `response_item` pairs. Below this, a file is read the legacy way; at or
+ * above it, or when the version cannot be read at all, the newer/default path
+ * is used — an older writer's rollout has nothing later versions removed, so
+ * reading it as the newer shape would just find no item_completed records and
+ * emit nothing.
+ */
+const FIRST_ITEM_EVENTS_CLI_VERSION = "0.154.0";
+
+function isOlderThan(version: string, floor: string): boolean {
+  const parts = (v: string) => v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const a = parts(version);
+  const b = parts(floor);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0);
+    if (diff !== 0) return diff < 0;
+  }
+  return false;
+}
+
+/** One step, wire-ready for `/ws/global` push. */
+export interface TailEventEnvelope {
+  ev: ChatEvent;
+  /** Epoch ms, from the record's own timestamp (carried forward when absent). */
+  ts: number;
+  /** A later event reusing a `toolUseId` already emitted — the client updates
+   *  that step in place (a tool_result answering an earlier tool_use is the
+   *  common case) instead of appending a new one. */
+  replace?: boolean;
+}
+
+export interface TailFeedResult {
+  events: TailEventEnvelope[];
+  /** The file rewrote its own history (compaction / rollback): the caller must
+   *  drop everything it has for this parser and re-read the file from byte 0. */
+  reset?: boolean;
+  /** Thread ids of subagents spawned since the previous `feed()` call, so the
+   *  caller can start tailing their rollouts alongside this one. */
+  links: string[];
+}
+
+/** Redact the input of a tool_use whose tool name is an unmapped item/call
+ *  type verbatim — the generic fallback that would otherwise carry through
+ *  whatever fields an unrecognized record happened to have, unredacted. */
+function redactIfGeneric(ev: ChatEvent, rawType: string): ChatEvent {
+  if (ev.type === "tool_use" && ev.tool === rawType) {
+    return { ...ev, input: redactTruncate(ev.input) };
+  }
+  return ev;
+}
+
+/** Always-generic legacy-path call (its tool name already comes from `p.name`,
+ *  there is nothing more specific to compare it against). */
+function redactGenericCall(ev: ChatEvent): ChatEvent {
+  return ev.type === "tool_use" ? { ...ev, input: redactTruncate(ev.input) } : ev;
+}
+
+export function createRolloutTailParser(): { feed(chunk: string): TailFeedResult } {
+  // Raw text not yet terminated by a newline — carried to the next feed() call
+  // rather than parsed early, so a chunk boundary landing mid-line (or mid
+  // multi-byte character) never produces a corrupt partial record.
+  let pending = "";
+  let headerSeen = false;
+  let format: "item-events" | "legacy" = "item-events";
+  const seenIds = new Set<string>();
+  let lastTs = 0;
+
+  function resolveTs(raw: unknown): number {
+    if (typeof raw === "string") {
+      const parsed = Date.parse(raw);
+      if (!Number.isNaN(parsed)) { lastTs = parsed; return parsed; }
+    }
+    return lastTs;
+  }
+
+  function push(out: TailEventEnvelope[], ev: ChatEvent, ts: number): void {
+    const id = "toolUseId" in ev ? ev.toolUseId : undefined;
+    if (id) {
+      if (seenIds.has(id)) { out.push({ ev, ts, replace: true }); return; }
+      seenIds.add(id);
+    }
+    out.push({ ev, ts });
+  }
+
+  function reset(out: TailEventEnvelope[]): void {
+    // The window is about to be rebuilt from byte 0, so every id emitted so
+    // far is no longer "already sent" from the caller's point of view either.
+    seenIds.clear();
+    out.length = 0;
+  }
+
+  function feed(chunk: string): TailFeedResult {
+    pending += chunk;
+    const lastNl = pending.lastIndexOf("\n");
+    const ready = lastNl >= 0 ? pending.slice(0, lastNl + 1) : "";
+    pending = lastNl >= 0 ? pending.slice(lastNl + 1) : pending;
+
+    const out: TailEventEnvelope[] = [];
+    const links: string[] = [];
+    const linkSeen = new Set<string>();
+    let didReset = false;
+
+    for (const line of completeLines(ready)) {
+      const rec = parseLine(line);
+      if (!rec) continue;
+      const p = rec.payload ?? {};
+      const ts = resolveTs(rec.timestamp);
+
+      if (rec.type === "session_meta") {
+        if (!headerSeen) {
+          headerSeen = true;
+          const cliVersion = typeof p.cli_version === "string" ? p.cli_version : undefined;
+          format = cliVersion && isOlderThan(cliVersion, FIRST_ITEM_EVENTS_CLI_VERSION) ? "legacy" : "item-events";
+        }
+        continue;
+      }
+
+      if (rec.type === "compacted") {
+        reset(out);
+        didReset = true;
+        continue;
+      }
+
+      if (rec.type === "event_msg") {
+        if (p.type === "thread_rolled_back") {
+          reset(out);
+          didReset = true;
+          continue;
+        }
+        if (p.type === "user_message" && typeof p.message === "string") {
+          push(out, { type: "text", content: stripSharedContext(p.message) }, ts);
+          continue;
+        }
+        if (p.type === "agent_message" && typeof p.message === "string") {
+          push(out, { type: "text", content: p.message }, ts);
+          continue;
+        }
+        if (p.type === "item_completed" && format === "item-events") {
+          const item = p.item;
+          const rawType = item && typeof item === "object" && typeof (item as Record<string, unknown>).type === "string"
+            ? (item as Record<string, unknown>).type as string
+            : "";
+          const mapped = mapRolloutItem(item);
+          if (mapped.kind === "user") {
+            push(out, { type: "text", content: stripSharedContext(mapped.text) }, ts);
+          } else if (mapped.kind === "assistant") {
+            push(out, { type: "text", content: mapped.text }, ts);
+          } else if (mapped.kind === "events") {
+            for (const ev of mapped.events) push(out, redactIfGeneric(ev, rawType), ts);
+          } else if (mapped.kind === "subagent") {
+            const { activity } = mapped;
+            if (!linkSeen.has(activity.threadId)) { linkSeen.add(activity.threadId); links.push(activity.threadId); }
+            // No `children`: the window renders nested agents flat, following
+            // in timestamp order as their own steps rather than nested inline.
+            push(out, activity.done ? subagentToolResult(activity) : subagentToolUse(activity), ts);
+          }
+          continue;
+        }
+        continue;
+      }
+
+      if (rec.type === "response_item" && format === "legacy") {
+        if (p.type === "function_call") push(out, fnCallToToolUse(p), ts);
+        else if (p.type === "function_call_output") push(out, fnOutputToToolResult(p), ts);
+        else if (p.type === "custom_tool_call") push(out, customToolCallToToolUse(p), ts);
+        else if (p.type === "custom_tool_call_output") push(out, fnOutputToToolResult(p), ts);
+        else if (typeof p.type === "string" && p.type.endsWith("_call_output")) push(out, fnOutputToToolResult(p), ts);
+        else if (typeof p.type === "string" && p.type.endsWith("_call")) push(out, redactGenericCall(genericCallToToolUse(p)), ts);
+      }
+    }
+
+    return { events: out, links, ...(didReset ? { reset: true as const } : {}) };
+  }
+
+  return { feed };
+}

package/src/providers/codex-app-server/codex-subagent-thread.ts

@@ -62,7 +62,12 @@ export function subagentCardId(threadId: string): string {
   return `subagent-${threadId}`;
 }
 
-/** The spawn, as the Agent card the chat already knows how to expand. */
+/** The spawn, as the Agent card the chat already knows how to expand.
+ *
+ * `transcript` is only ever passed by a history reader that already found and parsed the
+ * child's rollout — live streaming (`codex-event-mapper.ts`) and the tail parser call this
+ * with none, so `transcriptAvailable` stays unset there and the chat keeps this card's full
+ * live children instead of slimming away a source it cannot later stream from disk. */
 export function subagentToolUse(activity: SubagentActivity, transcript?: SubagentTranscript | null): ChatEvent {
   return {
     type: "tool_use",
@@ -70,6 +75,7 @@ export function subagentToolUse(activity: SubagentActivity, transcript?: Subagen
     input: { description: activity.path },
     toolUseId: subagentCardId(activity.threadId),
     ...(transcript?.events.length ? { children: transcript.events } : {}),
+    ...(transcript ? { transcriptAvailable: true } : {}),
   };
 }
 

package/src/server/index.ts

@@ -248,6 +248,8 @@ app.route("/api/settings", settingsRoutes);
 app.route("/api/settings/mcp", mcpRoutes);
 app.route("/api/mcp-auth", mcpAuthRoutes);
 app.route("/api/settings/themes", settingsThemesRoutes);
+import { designSettingsRoutes } from "./routes/design-settings.ts";
+app.route("/api/settings/design", designSettingsRoutes);
 app.route("/api/tunnel", tunnelRoutes);
 import { namedTunnelRoutes } from "./routes/named-tunnel.ts";
 app.route("/api/tunnel/named", namedTunnelRoutes);
@@ -926,8 +928,13 @@ if (process.argv.includes("__serve__")) {
 
       if (url.pathname === "/ws/global") {
         // App-wide event bus: owns file watching + cross-cutting broadcasts, so
-        // they no longer depend on a chat tab being mounted.
-        const upgraded = server.upgrade(req, { data: { type: "global" } });
+        // they no longer depend on a chat tab being mounted. The token is
+        // snapshotted here — not re-read from config on every push — so the
+        // agent-transcript hub can tell a long-lived socket apart from one
+        // whose password/token has since been rotated.
+        const authConfig = configService.get("auth");
+        const token = authConfig.enabled ? (url.searchParams.get("token") ?? null) : null;
+        const upgraded = server.upgrade(req, { data: { type: "global", token } });
         if (upgraded) return undefined;
         return new Response("WebSocket upgrade failed", { status: 400 });
       }

package/src/server/routes/design-preview.ts

@@ -9,6 +9,7 @@ import { resolveProjectPath } from "../helpers/resolve-project.ts";
 import { BRIDGE_NONCE_RE } from "../../shared/design-bridge-protocol.ts";
 import { isValidDesignSlug } from "../../services/design/design-slug.ts";
 import { getDesign } from "../../services/design/design-store.service.ts";
+import { designVariantsOf } from "../../shared/design-variants.ts";
 import { readDesignFileSafe } from "../../services/design/design-safe-walk.ts";
 import { decodeDesignText, MAX_DESIGN_SOURCE_BYTES } from "../../services/design/source/design-source-file.ts";
 import { buildDesignCsp } from "../../services/design/preview/design-csp.ts";
@@ -64,7 +65,8 @@ export function createDesignPreviewRoutes(now: () => number = Date.now) {
     const body: unknown = await c.req.json().catch(() => null);
     const b = body && typeof body === "object" && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
     if (!b || typeof b.projectName !== "string" || !b.projectName || !isValidDesignSlug(b.slug)
-      || !isDesignPreviewPurpose(b.purpose) || (b.token !== undefined && typeof b.token !== "string")) {
+      || !isDesignPreviewPurpose(b.purpose) || (b.token !== undefined && typeof b.token !== "string")
+      || (b.entry !== undefined && typeof b.entry !== "string")) {
       return c.json(err("projectName, a design slug and purpose (canvas, print or standalone) are required"), 400);
     }
     const slug = b.slug;
@@ -77,6 +79,10 @@ export function createDesignPreviewRoutes(now: () => number = Date.now) {
     }
     try {
       const design = await getDesign(projectPath, slug);
+      // The token reads any file of the design anyway; naming only a listed variant keeps
+      // the address the canvas loads to pages the design actually offers.
+      const entry = b.entry === undefined ? design.entry : designVariantsOf(design).find((v) => v.file === b.entry)?.file;
+      if (!entry) return c.json(err("That page is not a variant of this design"), 404);
       let cap: DesignPreviewCapability;
       let rotated = false;
       if (typeof b.token === "string") {
@@ -92,7 +98,7 @@ export function createDesignPreviewRoutes(now: () => number = Date.now) {
       } else {
         cap = store.mint({ projectPath, slug }, purpose);
       }
-      return c.json(ok({ url: urlFor(cap, design.entry), token: cap.token, expiresAt: cap.idleExpires, rotated }));
+      return c.json(ok({ url: urlFor(cap, entry), token: cap.token, expiresAt: cap.idleExpires, rotated }));
     } catch (e) {
       const info = mapFsError(e);
       if (info.status >= 500) console.error(`[design-preview] mint ${slug}: ${info.message}`);

package/src/server/routes/design-settings.ts

@@ -0,0 +1,88 @@
+import { Hono } from "hono";
+import { resolve } from "node:path";
+import { configService } from "../../services/config.service.ts";
+import { providerRegistry } from "../../providers/registry.ts";
+import { getDesignInstructions, setDesignInstructions } from "../../services/design/design-settings.service.ts";
+import { listProviderSkills } from "../../services/design/design-skill-sources.ts";
+import { DESIGN_INSTRUCTIONS_MAX_BYTES, normalizeDesignInstructions } from "../../shared/design-skill-mentions.ts";
+import type { SlashItem } from "../../services/slash-discovery/types.ts";
+import { ok, err } from "../../types/api.ts";
+
+/**
+ * Settings → Design (`/api/settings/design`): the owner's global design instructions and,
+ * for the editor's `/` picker, the skills each design-capable provider can load.
+ */
+export const designSettingsRoutes = new Hono();
+
+interface ProviderSkillList {
+  id: string;
+  name: string;
+  runtime: "claude" | "codex";
+  items: SlashItem[];
+  /**
+   * Whether `items` is a real answer. An empty codex list is a runtime that did not answer
+   * (codex always reports its own system skills when it is up), which the pane must not
+   * present as "nothing installed"; an empty Claude list is just that.
+   */
+  available: boolean;
+}
+
+/** A registered project's folder by name; anything else lists user-level skills only. */
+function projectPathByName(name: string | undefined): string | null {
+  if (!name) return null;
+  const project = configService.get("projects").find((p) => p.name === name);
+  return project ? resolve(project.path) : null;
+}
+
+/**
+ * Only providers that deliver design instructions get a list: nothing else ever reads the
+ * setting. A provider whose list cannot be read answers with an empty one rather than
+ * failing the pane, which must still load the saved text.
+ */
+async function listDesignProviderSkills(projectPath: string | null, fresh: boolean): Promise<ProviderSkillList[]> {
+  const providers = providerRegistry.listAll()
+    .map(({ id }) => providerRegistry.get(id))
+    .filter((p): p is NonNullable<typeof p> => !!p?.supportsDesignInstructions);
+  return Promise.all(providers.map(async (provider): Promise<ProviderSkillList> => {
+    try {
+      const { runtime, items } = await listProviderSkills(provider.id, { projectPath, fresh });
+      return { id: provider.id, name: provider.name, runtime, items, available: runtime === "claude" || items.length > 0 };
+    } catch (e) {
+      console.warn(`[design] could not list skills for ${provider.id}: ${(e as Error).message}`);
+      return { id: provider.id, name: provider.name, runtime: provider.listSkills ? "codex" : "claude", items: [], available: false };
+    }
+  }));
+}
+
+/**
+ * GET /settings/design?project=<name>&fresh=1 — `fresh` re-reads the skill lists (the
+ * settings pane, opened right after installing a skill); without it the cached lists do.
+ */
+designSettingsRoutes.get("/", async (c) => {
+  try {
+    const fresh = c.req.query("fresh") === "1";
+    const providers = await listDesignProviderSkills(projectPathByName(c.req.query("project")), fresh);
+    return c.json(ok({ instructions: getDesignInstructions(), maxBytes: DESIGN_INSTRUCTIONS_MAX_BYTES, providers }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** PUT /settings/design — body: { instructions: string } */
+designSettingsRoutes.put("/", async (c) => {
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json(err("Body must be JSON"), 400);
+  }
+  const instructions = body && typeof body === "object" ? (body as { instructions?: unknown }).instructions : undefined;
+  const result = normalizeDesignInstructions(instructions);
+  if (!result.ok) return c.json(err(result.error), 400);
+  try {
+    setDesignInstructions(result.text);
+    return c.json(ok({ instructions: result.text }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/server/routes/design-systems.ts

@@ -0,0 +1,81 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
+import {
+  createDesignSystem, deleteDesignSystem, getDesignSystem, listDesignSystems, updateDesignSystem,
+} from "../../services/design/design-systems.service.ts";
+import { designSystemStaleness } from "../../services/design/design-systems-stale.ts";
+import { ensureShowcaseDesign } from "../../services/design/design-systems-showcase.ts";
+
+/**
+ * `/api/project/:projectName/designs/systems` — the apps declared for one project, mounted
+ * under the design routes so it shares their auth and project-path resolution.
+ */
+export const designSystemRoutes = new Hono<DesignRouteEnv>();
+
+designSystemRoutes.get("/", async (c) => {
+  try {
+    return c.json(ok(await listDesignSystems(c.get("projectPath"))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designSystemRoutes.post("/", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await createDesignSystem(c.get("projectPath"), body)), 201);
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designSystemRoutes.get("/:id", async (c) => {
+  try {
+    return c.json(ok(await getDesignSystem(c.get("projectPath"), c.req.param("id"))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designSystemRoutes.patch("/:id", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return c.json(ok(await updateDesignSystem(c.get("projectPath"), c.req.param("id"), body)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+/** Un-declaring needs `?confirm=<id>`; `&deleteFiles=1` also removes its design-system files. */
+designSystemRoutes.delete("/:id", async (c) => {
+  const id = c.req.param("id");
+  if (c.req.query("confirm") !== id) return c.json(err("Confirm the removal with ?confirm=<id>"), 400);
+  try {
+    await deleteDesignSystem(c.get("projectPath"), id, { deleteFiles: c.req.query("deleteFiles") === "1" });
+    return c.json(ok({ deleted: id }));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designSystemRoutes.get("/:id/stale", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const system = await getDesignSystem(projectPath, c.req.param("id"));
+    return c.json(ok(await designSystemStaleness(projectPath, system)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+/** Get-or-create the app's showcase design, so "Set up design system" always has a tab to open. */
+designSystemRoutes.post("/:id/showcase", async (c) => {
+  try {
+    return c.json(ok(await ensureShowcaseDesign(c.get("projectPath"), c.req.param("id"))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});

package/src/server/routes/designs.ts

@@ -8,9 +8,9 @@ import { designStyleRoutes } from "./design-style.ts";
 import { designUndoRoutes } from "./design-undo.ts";
 import { designExportRoutes } from "./design-export.ts";
 import { designCheckRoutes } from "./design-check.ts";
-import {
-  createDesign, deleteDesign, designSystemStatus, getDesign, listDesigns, renameDesign,
-} from "../../services/design/design-store.service.ts";
+import { designSystemRoutes } from "./design-systems.ts";
+import { createDesign, deleteDesign, getDesign, listDesigns, renameDesign } from "../../services/design/design-store.service.ts";
+import { listDesignSystems } from "../../services/design/design-systems.service.ts";
 import { listSnapshots } from "../../services/design/design-snapshots.service.ts";
 import { restoreSnapshot } from "../../services/design/design-restore.service.ts";
 
@@ -27,8 +27,8 @@ export const designRoutes = new Hono<DesignRouteEnv>();
 designRoutes.get("/", async (c) => {
   try {
     const projectPath = c.get("projectPath");
-    const [designs, system] = await Promise.all([listDesigns(projectPath), designSystemStatus(projectPath)]);
-    return c.json(ok({ designs, system }));
+    const [designs, systems] = await Promise.all([listDesigns(projectPath), listDesignSystems(projectPath)]);
+    return c.json(ok({ designs, systems }));
   } catch (e) {
     return fail(c, e);
   }
@@ -38,12 +38,17 @@ designRoutes.post("/", async (c) => {
   const body = await jsonBody(c);
   if (!body) return c.json(err("Expected a JSON object"), 400);
   try {
-    return c.json(ok(await createDesign(c.get("projectPath"), { title: body.title, kind: body.kind })), 201);
+    return c.json(ok(await createDesign(c.get("projectPath"), { title: body.title, kind: body.kind, system: body.system })), 201);
   } catch (e) {
     return fail(c, e);
   }
 });
 
+// Mounted before `/:slug`: Hono matches routes in registration order, and an app id ("systems"
+// itself is a reserved, invalid design slug — see design-slug.ts) must never fall through to
+// the design-by-slug handlers below.
+designRoutes.route("/systems", designSystemRoutes);
+
 designRoutes.get("/:slug", async (c) => {
   try {
     return c.json(ok(await getDesign(c.get("projectPath"), c.req.param("slug"))));

package/src/server/routes/resources.ts

@@ -43,9 +43,9 @@ export function createResourceRoutes(
   routes.get("/hardware", async (c) => c.json(ok(await hardware())));
 
   // The request names an APP, never a path: the only file this can serve is one
-  // this host's own desktop entry pointed at, resolved server-side.
+  // that app's own metadata pointed at, resolved server-side.
   routes.get("/app-icon/:id", async (c) => {
-    const iconPath = appIcons.path(c.req.param("id") ?? "");
+    const iconPath = await appIcons.path(c.req.param("id") ?? "");
     if (!iconPath) return c.json(err("No icon for that app"), 404);
     const file = Bun.file(iconPath);
     if (!(await file.exists())) return c.json(err("No icon for that app"), 404);