@mohammadhprp/system-prompt 0.13.0 → 0.13.1

package/framework/skills/README.md

@@ -21,6 +21,7 @@ This catalog is framework-agnostic: each skill defines when to activate, a step-
 | [effective-html](./effective-html/SKILL.md) | Create self-contained HTML artifacts with routed guidance for design, wireframes, prototypes, plans, and diagrams. | Standalone HTML reports, explainers, interfaces, wireframes, prototypes, plans, and diagrams. |
 | [find-skills](./find-skills/SKILL.md) | Discover, evaluate, and install skills from the open agent skills ecosystem. | Finding an installable skill for a specialized task or extending an agent's capabilities. |
 | [frontend-design](./frontend-design/SKILL.md) | Distinctive, intentional visual design for new UI or reshaping existing UI — aesthetic direction, typography, and choices that don't read as templated defaults. | Building new interfaces, reshaping existing UI, or escaping generic AI-generated design looks. |
+| [grilling](./grilling/SKILL.md) | Grill plans and decisions relentlessly through design-tree rounds until shared understanding is reached. | Stress-testing ideas, surfacing hidden assumptions, and scoping plans before implementation. |
 | [glab](./glab/SKILL.md) | Use the GitLab CLI (glab) to manage merge requests, issues, pipelines, and repositories from the command line. | Any project hosted on GitLab (SaaS or self-hosted). |
 | [humanizer](./humanizer/SKILL.md) | Remove signs of AI-generated writing from text — inflated importance, promotional language, em dash overuse, rule of three, AI vocabulary, and filler phrases. | Editing or reviewing prose to make it sound more natural and human-written. |
 | [improve](./improve/SKILL.md) | Audit repositories as a read-only senior advisor and produce prioritized implementation plans for another agent. | Repository-wide audits, improvement roadmaps, and implementation handoffs. |

package/framework/skills/grilling/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+# grilling
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+
+## Source
+
+Adapted from [skills](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md) by Matt Pocock, MIT License.

package/framework/skills/grilling/examples.md

@@ -0,0 +1,47 @@
+# Grilling Skill — Example Outputs
+
+Realistic examples of how the `grilling` skill stress-tests thinking through design-tree rounds.
+
+## Example 1: New feature plan (frontier round, recommendations, wait)
+
+**User:** "Grill me on my plan to add Redis caching to the API."
+
+**What the agent does:**
+
+Maps the design tree (invalidation strategy branches off what is cached; TTL branches off invalidation; cache key shape branches off endpoints covered), computes the frontier, and asks round 1:
+
+```
+❓ **Q1** - **What gets cached**: Which endpoints or queries go through Redis — everything, read-heavy endpoints only, or specific hot queries?
+
+➡️ Read-heavy endpoints only. Caching everything multiplies invalidation bugs for little gain.
+
+---
+
+❓ **Q2** - **Where Redis lives**: Managed service (Upstash/ElastiCache), self-hosted container, or reuse existing infrastructure?
+
+➡️ Managed service. One less stateful thing to operate for a first caching pass.
+```
+
+Then waits. Q3 (TTL values) stays out of this round — it depends on Q1's answer.
+
+**Result:** Whole frontier asked at once, each with a recommendation, no guessing at unsettled answers.
+
+## Example 2: Facts via sub-agent, decisions via user (don't block)
+
+**User:** Answers Q1 with "specific hot queries" and Q2 with "self-hosted container."
+
+**What the agent does:**
+
+Settled decisions push the frontier outward. Q3 (TTL per query) is now askable. But "which queries are actually hot" is a fact, not a decision — dispatches a sub-agent to check access logs and slow-query stats instead of asking the user. Asks the rest of the frontier now (eviction policy, invalidation trigger); only the TTL question waits for the sub-agent's report.
+
+**Result:** Facts looked up, decisions put to the user, no blocking on exploration.
+
+## Example 3: Session close (frontier empty, confirm before acting)
+
+**User:** Answers the final round on invalidation triggers.
+
+**What the agent does:**
+
+Frontier is empty — every branch visited (scope, hosting, TTLs, eviction, invalidation). States the shared understanding back in one summary and asks for confirmation. Does not write any code or config until the user confirms.
+
+**Result:** Nothing silently assumed, no action before confirmed understanding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohammadhprp/system-prompt",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "AI Coding Agent Framework — interactive bootstrap CLI",
   "keywords": [
     "ai",

package/src/agent-configs.js

@@ -74,21 +74,89 @@ export function generateOpenCodeConfig({ selections, mcpEntries, includeAgentsMd
   return JSON.stringify(config, null, 4);
 }
 
-export function generateTuiConfig({ selections }) {
+export const TUI_THEMES = [
+  'system',
+  'tokyonight',
+  'everforest',
+  'ayu',
+  'catppuccin',
+  'catppuccin-macchiato',
+  'gruvbox',
+  'kanagawa',
+  'nord',
+  'matrix',
+  'one-dark',
+];
+
+export const TUI_DEFAULTS = {
+  theme: 'system',
+  scroll_speed: 3,
+  scroll_acceleration: true,
+  diff_style: 'auto',
+  mouse: true,
+  cursor: { style: 'block', blinking: true },
+  attention: { enabled: true, notifications: true, sound: true, volume: 0.4 },
+};
+
+export function normalizeTuiPreferences(preferences = {}) {
+  const source = preferences || {};
+  const cursor = source.cursor || {};
+  const attention = source.attention || {};
+  const scrollSpeed = Number(source.scroll_speed);
+  const volume = Number(attention.volume);
+
+  return {
+    theme: typeof source.theme === 'string' && source.theme ? source.theme : TUI_DEFAULTS.theme,
+    scroll_speed: Number.isFinite(scrollSpeed) && scrollSpeed >= 0.001 ? scrollSpeed : TUI_DEFAULTS.scroll_speed,
+    scroll_acceleration: typeof source.scroll_acceleration === 'boolean' ? source.scroll_acceleration : TUI_DEFAULTS.scroll_acceleration,
+    diff_style: source.diff_style === 'stacked' ? 'stacked' : 'auto',
+    mouse: typeof source.mouse === 'boolean' ? source.mouse : TUI_DEFAULTS.mouse,
+    cursor: {
+      style: ['block', 'underline', 'line', 'default'].includes(cursor.style) ? cursor.style : TUI_DEFAULTS.cursor.style,
+      blinking: typeof cursor.blinking === 'boolean' ? cursor.blinking : TUI_DEFAULTS.cursor.blinking,
+    },
+    attention: {
+      enabled: typeof attention.enabled === 'boolean' ? attention.enabled : TUI_DEFAULTS.attention.enabled,
+      notifications: typeof attention.notifications === 'boolean' ? attention.notifications : TUI_DEFAULTS.attention.notifications,
+      sound: typeof attention.sound === 'boolean' ? attention.sound : TUI_DEFAULTS.attention.sound,
+      volume: Number.isFinite(volume) && volume >= 0 && volume <= 1 ? volume : TUI_DEFAULTS.attention.volume,
+    },
+  };
+}
+
+export function tuiPreferencesFromConfig(config) {
+  if (!config || typeof config !== 'object') return {};
+  const preferences = {};
+  if (typeof config.theme === 'string') preferences.theme = config.theme;
+  if (typeof config.scroll_speed === 'number') preferences.scroll_speed = config.scroll_speed;
+  if (typeof config.scroll_acceleration?.enabled === 'boolean') preferences.scroll_acceleration = config.scroll_acceleration.enabled;
+  if (typeof config.diff_style === 'string') preferences.diff_style = config.diff_style;
+  if (typeof config.mouse === 'boolean') preferences.mouse = config.mouse;
+  if (config.cursor && typeof config.cursor === 'object') preferences.cursor = config.cursor;
+  if (config.attention && typeof config.attention === 'object') preferences.attention = config.attention;
+  return preferences;
+}
+
+export function generateTuiConfig({ selections, preferences }) {
+  const prefs = normalizeTuiPreferences(preferences);
   const config = {
     $schema: 'https://opencode.ai/tui.json',
-    theme: 'system',
-    scroll_speed: 3,
+    theme: prefs.theme,
+    scroll_speed: prefs.scroll_speed,
     scroll_acceleration: {
-      enabled: true,
+      enabled: prefs.scroll_acceleration,
+    },
+    diff_style: prefs.diff_style,
+    cursor: {
+      style: prefs.cursor.style,
+      blinking: prefs.cursor.blinking,
     },
-    diff_style: 'auto',
-    mouse: true,
+    mouse: prefs.mouse,
     attention: {
-      enabled: true,
-      notifications: true,
-      sound: true,
-      volume: 0.4,
+      enabled: prefs.attention.enabled,
+      notifications: prefs.attention.notifications,
+      sound: prefs.attention.sound,
+      volume: prefs.attention.volume,
     },
   };
 

package/src/catalog.js

@@ -3,6 +3,7 @@ export const categories = {
     title: 'Skills',
     description: 'Task-specific procedures for AI coding agents',
     sourceDir: 'framework/skills',
+    itemLayout: 'directory',
     items: [
       { id: 'adhd', name: 'ADHD', description: 'Shape output for ADHD readers: action first, numbered steps, restated state, no tangents' },
       { id: 'agent-browser', name: 'Agent Browser', description: 'Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction' },
@@ -17,6 +18,7 @@ export const categories = {
       { id: 'effective-html', name: 'Effective HTML', description: 'Create self-contained HTML artifacts with routed guidance for design, wireframes, prototypes, plans, and diagrams' },
       { id: 'find-skills', name: 'Find Skills', description: 'Discover, evaluate, and install agent skills for specialized tasks' },
       { id: 'frontend-design', name: 'Frontend Design', description: 'Distinctive, intentional visual design for new UI or reshaping existing UI' },
+      { id: 'grilling', name: 'Grilling', description: 'Grill plans and decisions relentlessly through design-tree rounds until shared understanding is reached' },
       { id: 'gh', name: 'GitHub CLI', description: 'Work with GitHub via the gh CLI for repositories, issues, pull requests, Actions, releases, and APIs' },
       { id: 'glab', name: 'Glab', description: 'Work with GitLab via the glab CLI for MRs, issues, and pipelines' },
       { id: 'humanizer', name: 'Humanizer', description: 'Remove signs of AI-generated writing to make text sound more natural and human' },
@@ -46,6 +48,7 @@ export const categories = {
     title: 'Subagents',
     description: 'Specialized subagents for security, architecture, review, and research',
     sourceDir: 'framework/agents',
+    itemLayout: 'file',
     items: [
       { id: 'researcher', name: 'Researcher', description: 'Fetch and analyze web content from URLs' },
       { id: 'reviewer', name: 'Reviewer', description: 'Review code for correctness and best practices' },
@@ -57,6 +60,7 @@ export const categories = {
     title: 'Slash Commands',
     description: 'Slash command workflows for repeatable tasks',
     sourceDir: 'framework/commands',
+    itemLayout: 'file',
     items: [
       { id: 'audit-your-codebase', name: 'Audit Your Codebase', description: 'Audit for materially useful simplifications in structure, state, algorithms, and ownership' },
       { id: 'explain-codebase', name: 'Explain Codebase', description: 'Map a codebase and teach it interactively, from overview to focused deep-dives' },
@@ -69,6 +73,8 @@ export const categories = {
     title: 'MCPs',
     description: 'Model Context Protocol servers for AI coding agents',
     sourceDir: 'framework/mcps',
+    itemLayout: 'directory',
+    copyItems: false,
     items: [
       { id: 'excalidraw', name: 'Excalidraw MCP', description: 'Stream hand-drawn diagrams with interactive editing' },
       { id: 'figma-mcp-go', name: 'Figma MCP Go', description: 'Read/write access to Figma designs via plugin bridge' },
@@ -82,6 +88,8 @@ export const categories = {
     title: 'Plugins',
     description: 'OpenCode plugins that extend the core agent',
     sourceDir: 'framework/plugins',
+    itemLayout: 'directory',
+    copyItems: false,
     items: [
       { id: 'opencode-goal-plugin', name: 'OpenCode Goal Plugin', description: 'Goal-driven long-running tasks with persistence' },
       { id: 'ponytail', name: 'Ponytail', description: 'Lazy senior dev mode — YAGNI-first, reuse-first ladder that reduces code bloat and cost' },
@@ -92,6 +100,7 @@ export const categories = {
     title: 'Styles',
     description: 'Design system references from Refero Styles',
     sourceDir: 'framework/styles',
+    itemLayout: 'directory',
     items: [
       { id: 'factory', name: 'Factory', description: 'Terminal war room design system' },
       { id: 'huly', name: 'Huly', description: 'Midnight observatory design system' },
@@ -105,6 +114,7 @@ export const categories = {
     title: 'Modes',
     description: 'Behavior, tool, and prompt presets for different use cases',
     sourceDir: 'framework/modes',
+    itemLayout: 'file',
     items: [
       { id: 'audit', name: 'Audit', description: 'Read-only high-scrutiny review mode for evaluating artifacts' },
     ],
@@ -114,6 +124,7 @@ export const categories = {
     title: 'Memory',
     description: 'Persistent agent memory files for cross-session context',
     sourceDir: 'framework/memory',
+    itemLayout: 'file',
     items: [
       { id: 'codebase-insights', name: 'Codebase Insights', description: 'Non-obvious facts, gotchas, past decisions, and architecture quirks' },
       { id: 'user-preferences', name: 'User Preferences', description: 'Coding style, naming conventions, and architectural preferences' },
@@ -124,6 +135,7 @@ export const categories = {
     title: 'Standards',
     description: 'Canonical engineering standards',
     sourceDir: 'framework/references/standards',
+    itemLayout: 'file',
     items: [
       { id: 'api', name: 'API Design', description: 'REST API design standards' },
       { id: 'architecture', name: 'Architecture', description: 'System architecture standards' },
@@ -144,6 +156,7 @@ export const categories = {
     title: 'Templates',
     description: 'Fillable workflow documents',
     sourceDir: 'framework/references/templates',
+    itemLayout: 'file',
     items: [
       { id: 'adr', name: 'ADR', description: 'Architecture Decision Record' },
       { id: 'api-spec', name: 'API Spec', description: 'API specification document' },

package/src/cli.js

@@ -1,12 +1,25 @@
-import { intro, outro, confirm, multiselect, spinner, isCancel } from '@clack/prompts';
+import { intro, outro, confirm, multiselect, spinner, select, isCancel } from '@clack/prompts';
+import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
 import { categories } from './catalog.js';
 import { getPackageVersion, install, loadLockFile, lockToSelections } from './installer.js';
 import { doctor } from './doctor.js';
+import { normalizeTuiPreferences, tuiPreferencesFromConfig, TUI_THEMES } from './agent-configs.js';
 
 const CATEGORY_FLAGS = new Set(Object.keys(categories));
 
+const defaultUi = {
+  intro,
+  outro,
+  confirm,
+  multiselect,
+  spinner,
+  select,
+  isCancel,
+  log: (...args) => console.log(...args),
+};
+
 export function parseArgs(argv) {
   const options = {
     targetDir: '.opencode',
@@ -48,29 +61,28 @@ export function parseArgs(argv) {
   return options;
 }
 
-function allSelections() {
+export function allSelections() {
   return Object.fromEntries(Object.entries(categories).map(([category, config]) => [
     category,
     config.items.filter(item => !item.removed).map(item => item.id),
   ]));
 }
 
+function itemNames(config, ids) {
+  return ids.map(id => config?.items?.find(item => item.id === id)?.name || id);
+}
+
 function buildSummary(selections) {
   const lines = [];
   for (const [cat, ids] of Object.entries(selections)) {
     if (!ids?.length) continue;
     const catConfig = categories[cat];
-    const label = catConfig?.title || cat;
-    const names = ids.map(id => {
-      const item = catConfig?.items.find(i => i.id === id);
-      return item ? item.name : id;
-    });
-    lines.push(`  ${label}: ${names.join(', ')}`);
+    lines.push(`  ${catConfig?.title || cat}: ${itemNames(catConfig, ids).join(', ')}`);
   }
   return lines.join('\n');
 }
 
-function computeDiff(oldLock, selections) {
+export function computeDiff(oldLock, selections) {
   const oldSels = lockToSelections(oldLock);
   const added = {};
   const removed = {};
@@ -95,240 +107,402 @@ function computeDiff(oldLock, selections) {
   return { added, removed, kept };
 }
 
-function formatDiff(diff) {
-  const { added, removed, kept } = diff;
+export function formatDiff(diff) {
+  const sections = [
+    ['+ Added', diff.added],
+    ['- Removed', diff.removed],
+    ['~ Unchanged', diff.kept],
+  ];
   const lines = [];
 
-  if (Object.keys(added).length) {
-    lines.push('  + Added:');
-    for (const [cat, data] of Object.entries(added)) {
-      const names = data.ids.map(id => {
-        const item = data.config?.items?.find(i => i.id === id);
-        return item?.name || id;
-      });
-      lines.push(`    ${data.config?.title || cat}: ${names.join(', ')}`);
-    }
-  }
-
-  if (Object.keys(removed).length) {
+  for (const [label, group] of sections) {
+    const entries = Object.entries(group);
+    if (!entries.length) continue;
     if (lines.length) lines.push('');
-    lines.push('  - Removed:');
-    for (const [cat, data] of Object.entries(removed)) {
-      const names = data.ids.map(id => {
-        const item = data.config?.items?.find(i => i.id === id);
-        return item?.name || id;
-      });
-      lines.push(`    ${data.config?.title || cat}: ${names.join(', ')}`);
-    }
-  }
-
-  if (Object.keys(kept).length) {
-    if (lines.length) lines.push('');
-    lines.push('  ~ Unchanged:');
-    for (const [cat, data] of Object.entries(kept)) {
-      const names = data.ids.map(id => {
-        const item = data.config?.items?.find(i => i.id === id);
-        return item?.name || id;
-      });
-      lines.push(`    ${data.config?.title || cat}: ${names.join(', ')}`);
+    lines.push(`  ${label}:`);
+    for (const [cat, data] of entries) {
+      lines.push(`    ${data.config?.title || cat}: ${itemNames(data.config, data.ids).join(', ')}`);
     }
   }
 
   return lines.join('\n');
 }
 
-export async function main(argv = process.argv.slice(2)) {
-  const args = parseArgs(argv);
-  if (args.doctor) {
-    const healthy = await doctor(args.targetDir);
-    if (!healthy) process.exitCode = 1;
-    return healthy;
+export function initialItemValues(visibleItems, existingIds = []) {
+  const visible = new Set(visibleItems.map(item => item.id));
+  return existingIds.filter(id => visible.has(id));
+}
+
+export function shouldPreselectAll(visibleItems, existingIds = []) {
+  if (existingIds.length) return existingIds.length === visibleItems.length;
+  return visibleItems.length <= 12;
+}
+
+async function readTuiPreferences(absTarget) {
+  try {
+    return tuiPreferencesFromConfig(JSON.parse(await readFile(resolve(absTarget, 'tui.json'), 'utf-8')));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return {};
+    throw error;
   }
+}
 
-  const version = await getPackageVersion();
-  intro(`System prompt (v${version})`);
+async function collectTuiPreferences(existing, ui) {
+  const base = normalizeTuiPreferences(existing);
+
+  const theme = await ui.select({
+    message: 'TUI theme',
+    options: TUI_THEMES.map(value => ({
+      value,
+      label: value,
+      hint: value === 'system' ? 'Adapts to your terminal' : undefined,
+    })),
+    initialValue: base.theme,
+  });
+  if (ui.isCancel(theme)) return null;
+
+  const diffStyle = await ui.select({
+    message: 'Diff style',
+    options: [
+      { value: 'auto', label: 'auto', hint: 'Adapts to terminal width' },
+      { value: 'stacked', label: 'stacked', hint: 'Always single column' },
+    ],
+    initialValue: base.diff_style,
+  });
+  if (ui.isCancel(diffStyle)) return null;
 
-  const agentType = 'opencode';
-  const targetDir = args.targetDir;
+  const cursorStyle = await ui.select({
+    message: 'Cursor style',
+    options: ['block', 'underline', 'line', 'default'].map(value => ({ value, label: value })),
+    initialValue: base.cursor.style,
+  });
+  if (ui.isCancel(cursorStyle)) return null;
+
+  const scrollSpeed = await ui.select({
+    message: 'Scroll speed',
+    options: [
+      { value: 1, label: '1', hint: 'Slow' },
+      { value: 2, label: '2' },
+      { value: 3, label: '3', hint: 'Default' },
+      { value: 4, label: '4' },
+      { value: 5, label: '5', hint: 'Fast' },
+    ],
+    initialValue: base.scroll_speed,
+  });
+  if (ui.isCancel(scrollSpeed)) return null;
 
-  if (args.nonInteractive) {
-    const selections = args.all ? allSelections() : args.selections;
-    const absTarget = resolve(process.cwd(), targetDir);
-    const oldLock = await loadLockFile(absTarget);
-    if (!args.dryRun) console.log(`Installing selected components into ${absTarget}`);
-    await install({
-      targetDir,
-      agentType,
-      selections,
-      includeAgentsMd: args.includeAgentsMd,
-      oldSelections: oldLock ? lockToSelections(oldLock) : undefined,
-      oldLock,
-      force: args.force,
-      dryRun: args.dryRun,
+  const scrollAcceleration = await ui.confirm({
+    message: 'Enable scroll acceleration?',
+    initialValue: base.scroll_acceleration,
+  });
+  if (ui.isCancel(scrollAcceleration)) return null;
+
+  const mouse = await ui.confirm({
+    message: 'Enable mouse support?',
+    initialValue: base.mouse,
+  });
+  if (ui.isCancel(mouse)) return null;
+
+  const attentionEnabled = await ui.confirm({
+    message: 'Enable attention notifications and sounds?',
+    initialValue: base.attention.enabled,
+  });
+  if (ui.isCancel(attentionEnabled)) return null;
+
+  const attention = { ...base.attention, enabled: attentionEnabled };
+  if (attentionEnabled) {
+    const notifications = await ui.confirm({
+      message: 'Desktop notifications?',
+      initialValue: base.attention.notifications,
     });
-    console.log(args.dryRun ? 'Dry run complete.' : 'Installation complete.');
-    return;
+    if (ui.isCancel(notifications)) return null;
+
+    const sound = await ui.confirm({
+      message: 'Sound alerts?',
+      initialValue: base.attention.sound,
+    });
+    if (ui.isCancel(sound)) return null;
+
+    const volume = await ui.select({
+      message: 'Alert volume',
+      options: [
+        { value: 0.2, label: '20%' },
+        { value: 0.4, label: '40%', hint: 'Default' },
+        { value: 0.6, label: '60%' },
+        { value: 0.8, label: '80%' },
+        { value: 1, label: '100%' },
+      ],
+      initialValue: base.attention.volume,
+    });
+    if (ui.isCancel(volume)) return null;
+
+    attention.notifications = notifications;
+    attention.sound = sound;
+    attention.volume = volume;
   }
 
-  const categoryOptions = Object.entries(categories).map(([key, cat]) => {
-    const visible = cat.items.filter(i => !i.removed);
+  return normalizeTuiPreferences({
+    theme,
+    diff_style: diffStyle,
+    cursor: { style: cursorStyle, blinking: base.cursor.blinking },
+    scroll_speed: scrollSpeed,
+    scroll_acceleration: scrollAcceleration,
+    mouse,
+    attention,
+  });
+}
+
+function cancelled(ui) {
+  ui.outro('Cancelled.');
+  return { status: 'cancelled' };
+}
+
+export function buildCategoryOptions() {
+  return Object.entries(categories).map(([key, cat]) => {
+    const visible = cat.items.filter(item => !item.removed);
     return {
       value: key,
       label: cat.title,
       hint: `${visible.length} ${key === 'mcps' ? 'MCPs' : cat.title.toLowerCase()}`,
     };
   });
+}
 
-  const selectedCategories = await multiselect({
-    message: 'What would you like to install?',
-    options: categoryOptions,
-    required: false,
+async function installGeneratedFiles({ ui, targetDir, agentType, force, dryRun, oldLock, existingSelections, existingTuiPreferences }) {
+  const includeAgentsMd = await ui.confirm({
+    message: 'Generate AGENTS.md?',
+    initialValue: oldLock ? oldLock.includeAgentsMd : true,
   });
-  if (isCancel(selectedCategories)) {
-    outro('Cancelled.');
-    process.exit(0);
+  if (ui.isCancel(includeAgentsMd)) return cancelled(ui);
+
+  const hasExisting = Object.keys(existingSelections).length > 0;
+  let keepExisting = false;
+  if (hasExisting) {
+    const removeAll = await ui.confirm({
+      message: 'Remove all previously installed components?',
+      initialValue: false,
+    });
+    if (ui.isCancel(removeAll)) return cancelled(ui);
+    keepExisting = !removeAll;
   }
 
-  if (!selectedCategories?.length) {
-    const includeAgentsMd = await confirm({
-      message: 'Generate AGENTS.md?',
-      initialValue: true,
-    });
-    if (isCancel(includeAgentsMd)) {
-      outro('Cancelled.');
-      process.exit(0);
-    }
+  const progress = ui.spinner();
+  progress.start('Writing files...');
+  await install({
+    targetDir,
+    agentType,
+    selections: keepExisting ? existingSelections : {},
+    includeAgentsMd,
+    oldSelections: hasExisting ? existingSelections : undefined,
+    oldLock,
+    tuiPreferences: existingTuiPreferences,
+    force,
+    dryRun,
+  });
+  progress.stop('Done.');
 
-    const s = spinner();
-    s.start('Writing files...');
-    await install({
-       targetDir,
-      agentType,
-      selections: {},
-      includeAgentsMd,
-    });
-    s.stop('Done.');
-    const installed = [];
-    if (includeAgentsMd) installed.push('AGENTS.md');
-    outro(`${installed.join(' and ')} written. Open them in your project to get started.`);
-    process.exit(0);
-  }
+  const installed = includeAgentsMd ? ['AGENTS.md'] : [];
+  ui.outro(`${installed.join(' and ')} written. Open them in your project to get started.`);
+  return { status: 'installed' };
+}
 
-  const selections = {};
+function reportPlan({ ui, oldLock, selections, includeAgentsMd }) {
+  if (oldLock) {
+    const diffText = formatDiff(computeDiff(oldLock, selections));
+    ui.log('\n📦 Changes from previous installation:\n');
+    if (diffText) {
+      ui.log(diffText);
+      ui.log();
+    } else {
+      ui.log('  No changes — same selections as before.\n');
+    }
 
-  const includeAgentsMd = await confirm({
-    message: 'Generate AGENTS.md?',
-    initialValue: true,
-  });
-  if (isCancel(includeAgentsMd)) {
-    outro('Cancelled.');
-    process.exit(0);
+    const generatedFiles = [];
+    if (includeAgentsMd) generatedFiles.push('AGENTS.md');
+    generatedFiles.push('opencode.json', 'tui.json', '.gitignore');
+    if (selections.mcps?.length) generatedFiles.push('.env');
+    if (selections.memory?.length) generatedFiles.push('memory/');
+
+    if (generatedFiles.length) {
+      ui.log('  Generated files:');
+      for (const file of generatedFiles) ui.log(`    📄 ${file}`);
+      ui.log();
+    }
+    return;
   }
 
+  ui.log('\n📦 Summary of what will be installed:\n');
+  if (includeAgentsMd) ui.log('  📄 AGENTS.md');
+  ui.log('  📄 opencode.json');
+  ui.log('  📄 tui.json');
+  ui.log('  📄 .gitignore');
+  ui.log(buildSummary(selections));
+  ui.log();
+}
+
+async function collectSelections({ ui, selectedCategories, existingSelections }) {
+  const selections = {};
   for (const cat of selectedCategories) {
     const catConfig = categories[cat];
-    const allIds = catConfig.items.map(i => i.id);
+    const visibleItems = catConfig.items.filter(item => !item.removed);
+    const existingIds = initialItemValues(visibleItems, existingSelections[cat] || []);
 
-      const visibleItems = catConfig.items.filter(i => !i.removed);
-
-      const all = await confirm({
-        message: `Install all ${catConfig.title.toLowerCase()}?`,
-        initialValue: visibleItems.length <= 12,
-      });
-      if (isCancel(all)) {
-        outro('Cancelled.');
-        process.exit(0);
-      }
+    const all = await ui.confirm({
+      message: `Install all ${catConfig.title.toLowerCase()}?`,
+      initialValue: shouldPreselectAll(visibleItems, existingIds),
+    });
+    if (ui.isCancel(all)) return null;
 
-      if (all) {
-        selections[cat] = visibleItems.map(i => i.id);
-      } else {
-        const picked = await multiselect({
-          message: `Which ${catConfig.title.toLowerCase()} do you want?`,
-          options: visibleItems.map(item => ({
-            value: item.id,
-            label: item.deprecated ? `${item.name} (deprecated)` : item.name,
-            hint: item.deprecated ? '⚠  Deprecated — consider alternatives' : item.description,
-          })),
-          required: true,
-        });
-      if (isCancel(picked)) {
-        outro('Cancelled.');
-        process.exit(0);
-      }
-      selections[cat] = picked;
+    if (all) {
+      selections[cat] = visibleItems.map(item => item.id);
+      continue;
     }
-  }
 
-  const absTarget = resolve(process.cwd(), targetDir);
-  const oldLock = await loadLockFile(absTarget);
+    const picked = await ui.multiselect({
+      message: `Which ${catConfig.title.toLowerCase()} do you want?`,
+      options: visibleItems.map(item => ({
+        value: item.id,
+        label: item.deprecated ? `${item.name} (deprecated)` : item.name,
+        hint: item.deprecated ? '⚠  Deprecated — consider alternatives' : item.description,
+      })),
+      initialValues: existingIds,
+      required: true,
+    });
+    if (ui.isCancel(picked)) return null;
+    selections[cat] = picked;
+  }
+  return selections;
+}
 
-  if (oldLock) {
-    const diff = computeDiff(oldLock, selections);
-    const diffText = formatDiff(diff);
+async function installSelectedItems({ ui, targetDir, agentType, force, dryRun, oldLock, existingSelections, existingTuiPreferences }, selectedCategories) {
+  const includeAgentsMd = await ui.confirm({
+    message: 'Generate AGENTS.md?',
+    initialValue: oldLock ? oldLock.includeAgentsMd : true,
+  });
+  if (ui.isCancel(includeAgentsMd)) return cancelled(ui);
 
-    console.log('\n📦 Changes from previous installation:\n');
-    if (diffText) {
-      console.log(diffText);
-      console.log();
-    } else {
-      console.log('  No changes — same selections as before.\n');
-    }
+  const selections = await collectSelections({ ui, selectedCategories, existingSelections });
+  if (!selections) return cancelled(ui);
 
-    const genFiles = [];
-    if (includeAgentsMd) genFiles.push('AGENTS.md');
-    genFiles.push('opencode.json', 'tui.json', '.gitignore');
-    if (selections.mcps?.length) genFiles.push('.env');
-    if (selections.memory?.length) genFiles.push('memory/');
+  let tuiPreferences = existingTuiPreferences;
+  const customizeTui = await ui.confirm({
+    message: 'Customize OpenCode TUI settings?',
+    initialValue: false,
+  });
+  if (ui.isCancel(customizeTui)) return cancelled(ui);
+  if (customizeTui) {
+    const custom = await collectTuiPreferences(existingTuiPreferences, ui);
+    if (!custom) return cancelled(ui);
+    tuiPreferences = custom;
+  }
 
-    if (genFiles.length) {
-      console.log('  Generated files:');
-      for (const f of genFiles) {
-        console.log(`    📄 ${f}`);
+  if (oldLock) {
+    const initialDiff = computeDiff(oldLock, selections);
+    if (Object.keys(initialDiff.removed).length) {
+      const removeDeselected = await ui.confirm({
+        message: 'Remove deselected items from the previous installation?',
+        initialValue: false,
+      });
+      if (ui.isCancel(removeDeselected)) return cancelled(ui);
+      if (!removeDeselected) {
+        for (const [cat, data] of Object.entries(initialDiff.removed)) {
+          selections[cat] = [...new Set([...(selections[cat] || []), ...data.ids])];
+        }
       }
-      console.log();
     }
-  } else {
-    console.log('\n📦 Summary of what will be installed:\n');
-    if (includeAgentsMd) console.log('  📄 AGENTS.md');
-    console.log('  📄 opencode.json');
-    console.log('  📄 tui.json');
-    console.log('  📄 .gitignore');
-    console.log(buildSummary(selections));
-    console.log();
   }
 
-  const confirmed = await confirm({
+  reportPlan({ ui, oldLock, selections, includeAgentsMd });
+
+  const confirmed = await ui.confirm({
     message: 'Proceed with installation?',
     initialValue: true,
   });
-  if (isCancel(confirmed) || !confirmed) {
-    outro('Installation cancelled.');
-    process.exit(0);
+  if (ui.isCancel(confirmed) || !confirmed) {
+    ui.outro('Installation cancelled.');
+    return { status: 'cancelled' };
   }
 
-  const s = spinner();
-  s.start(oldLock ? 'Updating files...' : 'Installing files...');
+  const progress = ui.spinner();
+  progress.start(oldLock ? 'Updating files...' : 'Installing files...');
 
   const finalTarget = await install({
     targetDir,
     agentType,
     selections,
     includeAgentsMd,
-    oldSelections: oldLock ? lockToSelections(oldLock) : undefined,
+    oldSelections: oldLock ? existingSelections : undefined,
     oldLock,
-    force: args.force,
-    dryRun: args.dryRun,
+    tuiPreferences,
+    force,
+    dryRun,
   });
 
-  s.stop('Installation complete!');
+  progress.stop('Installation complete!');
 
-  const fileCount = Object.values(selections).reduce((sum, arr) => sum + (arr?.length || 0), 0);
+  const fileCount = Object.values(selections).reduce((sum, ids) => sum + (ids?.length || 0), 0);
   const verb = oldLock ? 'Updated' : 'Installed';
-  outro(`${verb} ${fileCount} components to ${finalTarget}
+  ui.outro(`${verb} ${fileCount} components to ${finalTarget}
 
 Next steps:
   ${agentType === 'opencode' ? '- Open your project in OpenCode — it will read opencode.json and AGENTS.md automatically' : '- Point your AI coding agent to AGENTS.md as the entry point'}
   - Run /help in your agent to see available commands
 `);
+  return { status: 'installed', target: finalTarget };
+}
+
+export async function runInteractive({ targetDir, force = false, dryRun = false, agentType = 'opencode', ui = defaultUi }) {
+  const absTarget = resolve(process.cwd(), targetDir);
+  const oldLock = await loadLockFile(absTarget);
+  const existingSelections = lockToSelections(oldLock);
+  const existingTuiPreferences = await readTuiPreferences(absTarget);
+  const context = { ui, targetDir, agentType, force, dryRun, oldLock, existingSelections, existingTuiPreferences };
+
+  const selectedCategories = await ui.multiselect({
+    message: 'What would you like to install?',
+    options: buildCategoryOptions(),
+    initialValues: Object.keys(existingSelections),
+    required: false,
+  });
+  if (ui.isCancel(selectedCategories)) return cancelled(ui);
+
+  if (!selectedCategories?.length) return installGeneratedFiles(context);
+  return installSelectedItems(context, selectedCategories);
+}
+
+export async function runNonInteractive({ targetDir, selections, all, includeAgentsMd, force = false, dryRun = false, agentType = 'opencode', ui = defaultUi }) {
+  const resolvedSelections = all ? allSelections() : selections;
+  const absTarget = resolve(process.cwd(), targetDir);
+  const oldLock = await loadLockFile(absTarget);
+  if (!dryRun) ui.log(`Installing selected components into ${absTarget}`);
+  await install({
+    targetDir,
+    agentType,
+    selections: resolvedSelections,
+    includeAgentsMd,
+    oldSelections: oldLock ? lockToSelections(oldLock) : undefined,
+    oldLock,
+    force,
+    dryRun,
+  });
+  ui.log(dryRun ? 'Dry run complete.' : 'Installation complete.');
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.doctor) {
+    const healthy = await doctor(args.targetDir);
+    if (!healthy) process.exitCode = 1;
+    return healthy;
+  }
+
+  const version = await getPackageVersion();
+  defaultUi.intro(`System prompt (v${version})`);
+
+  const agentType = 'opencode';
+
+  if (args.nonInteractive) {
+    return runNonInteractive({ ...args, agentType });
+  }
+  return runInteractive({ ...args, agentType });
 }

package/src/doctor.js

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto';
 
 import { categories } from './catalog.js';
 import { loadLockFile, lockToSelections } from './installer.js';
+import { itemRelativePath } from './item-layout.js';
 
 async function exists(path) {
   try {
@@ -14,6 +15,16 @@ async function exists(path) {
   }
 }
 
+async function checkManagedFile(absTarget, relativePath, expectedHash, issues) {
+  try {
+    const actual = createHash('sha256').update(await readFile(resolve(absTarget, relativePath))).digest('hex');
+    if (actual !== expectedHash) issues.push(`Modified managed file: ${relativePath}`);
+  } catch (error) {
+    if (error.code === 'ENOENT') issues.push(`Missing managed file: ${relativePath}`);
+    else throw error;
+  }
+}
+
 export async function inspectInstallation(targetDir) {
   const absTarget = resolve(process.cwd(), targetDir);
   const issues = [];
@@ -32,26 +43,14 @@ export async function inspectInstallation(targetDir) {
   }
 
   for (const [path, entry] of Object.entries(lock.generated || {})) {
-    try {
-      const actual = createHash('sha256').update(await readFile(resolve(absTarget, path))).digest('hex');
-      if (actual !== entry.computedHash) issues.push(`Modified managed file: ${path}`);
-    } catch (error) {
-      if (error.code === 'ENOENT') issues.push(`Missing managed file: ${path}`);
-      else throw error;
-    }
+    await checkManagedFile(absTarget, path, entry.computedHash, issues);
   }
 
   for (const [category, entries] of Object.entries(lock)) {
     if (!categories[category]) continue;
-    for (const [id, entry] of Object.entries(entries)) {
+    for (const entry of Object.values(entries)) {
       for (const [path, expected] of Object.entries(entry.files || {})) {
-        try {
-          const actual = createHash('sha256').update(await readFile(resolve(absTarget, path))).digest('hex');
-          if (actual !== expected) issues.push(`Modified managed file: ${path}`);
-        } catch (error) {
-          if (error.code === 'ENOENT') issues.push(`Missing managed file: ${path}`);
-          else throw error;
-        }
+        await checkManagedFile(absTarget, path, expected, issues);
       }
     }
   }
@@ -60,10 +59,7 @@ export async function inspectInstallation(targetDir) {
     const config = categories[category];
     for (const id of ids) {
       const item = config.items.find(entry => entry.id === id);
-      const relativePath = ['agents', 'commands', 'memory', 'modes', 'standards', 'templates'].includes(category)
-        ? `${config.sourceDir.replace(/^framework\//, '')}/${id}.md`
-        : `${config.sourceDir.replace(/^framework\//, '')}/${id}`;
-      if (!item || !(await exists(resolve(absTarget, relativePath)))) {
+      if (!item || !(await exists(resolve(absTarget, itemRelativePath(category, id))))) {
         issues.push(`Missing installed ${category} item: ${id}`);
       }
     }

package/src/installer.js

@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto';
 
 import { categories } from './catalog.js';
 import { loadMcpConfigs, generateOpenCodeConfig, generateTuiConfig } from './agent-configs.js';
+import { LOCK_CATEGORIES, isFileBased, isCopyable, itemSourcePath, itemRelativePath, targetSubdir } from './item-layout.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, '..');
@@ -87,9 +88,6 @@ bun.lock
 `;
 
 export const LOCK_VERSION = 1;
-export const LOCK_CATEGORIES = ['skills', 'agents', 'commands', 'mcps', 'plugins', 'styles', 'modes', 'memory', 'standards', 'templates'];
-
-const FILE_BASED = new Set(['agents', 'commands', 'memory', 'modes', 'standards', 'templates']);
 
 export function lockToSelections(lock) {
   const selections = {};
@@ -101,12 +99,6 @@ export function lockToSelections(lock) {
   return selections;
 }
 
-function itemSourcePath(category, id) {
-  const config = categories[category];
-  if (FILE_BASED.has(category)) return `${config.sourceDir}/${id}.md`;
-  return `${config.sourceDir}/${id}`;
-}
-
 function buildComputedHash(files, fallbackId) {
   const keys = Object.keys(files).sort();
   if (keys.length === 0) return hash(fallbackId);
@@ -308,22 +300,22 @@ async function copySelectedDirs(targetDir, category, selectedIds, options) {
   const catConfig = categories[category];
   if (!catConfig || !selectedIds?.length) return;
 
-  const relativeDir = targetSubdir(catConfig.sourceDir);
-  const destParent = resolve(targetDir, relativeDir);
+  const destParent = resolve(targetDir, targetSubdir(catConfig.sourceDir));
 
   for (const id of selectedIds) {
     if (await isRemoved(category, id)) continue;
 
-    const srcPath = resolveSource(`${catConfig.sourceDir}/${id}`);
+    const source = itemSourcePath(category, id);
+    const srcPath = resolveSource(source);
     const destPath = resolve(destParent, id);
     await assertSafeDestination(targetDir, destPath);
 
     try {
       await stat(srcPath);
-      await copyDir(srcPath, destPath, `${relativeDir}/${id}`, options, { category, id });
+      await copyDir(srcPath, destPath, itemRelativePath(category, id), options, { category, id });
     } catch (error) {
       if (sourceMissing(error)) {
-        console.warn(`  ⚠  Source not found: ${catConfig.sourceDir}/${id}`);
+        console.warn(`  ⚠  Source not found: ${source}`);
         continue;
       }
       throw error;
@@ -335,22 +327,22 @@ async function copySelectedFiles(targetDir, category, selectedIds, options) {
   const catConfig = categories[category];
   if (!catConfig || !selectedIds?.length) return;
 
-  const relativeDir = targetSubdir(catConfig.sourceDir);
-  const destParent = resolve(targetDir, relativeDir);
+  const destParent = resolve(targetDir, targetSubdir(catConfig.sourceDir));
   if (!options.dryRun) await mkdir(destParent, { recursive: true });
 
   for (const id of selectedIds) {
     if (await isRemoved(category, id)) continue;
 
-    const srcFile = resolveSource(`${catConfig.sourceDir}/${id}.md`);
-    const destFile = resolve(destParent, `${id}.md`);
+    const source = itemSourcePath(category, id);
+    const relativePath = itemRelativePath(category, id);
+    const destFile = resolve(targetDir, relativePath);
     await assertSafeDestination(targetDir, destFile);
     try {
-      const content = await readFile(srcFile);
-      await writeManagedFile(destFile, content, `${relativeDir}/${id}.md`, options, { category, id });
+      const content = await readFile(resolveSource(source));
+      await writeManagedFile(destFile, content, relativePath, options, { category, id });
     } catch (error) {
       if (sourceMissing(error)) {
-        console.warn(`  ⚠  Source not found: ${catConfig.sourceDir}/${id}.md`);
+        console.warn(`  ⚠  Source not found: ${source}`);
         continue;
       }
       throw error;
@@ -359,21 +351,14 @@ async function copySelectedFiles(targetDir, category, selectedIds, options) {
 }
 
 async function deleteSelectedItems(absTarget, category, ids, oldLock, force, dryRun) {
-  const catConfig = categories[category];
-  if (!catConfig || !ids?.length) return;
-
-  if (!FILE_BASED.has(category) && category !== 'skills' && category !== 'styles') return;
+  if (!categories[category] || !ids?.length || !isCopyable(category)) return;
 
-  const relativeDir = targetSubdir(catConfig.sourceDir);
   for (const id of ids) {
-    const relativePath = FILE_BASED.has(category)
-      ? `${relativeDir}/${id}.md`
-      : `${relativeDir}/${id}`;
+    const relativePath = itemRelativePath(category, id);
     const destPath = resolve(absTarget, relativePath);
     await assertSafeDestination(absTarget, destPath);
     if (!force && oldLock) {
-      const oldFiles = oldLock?.[category]?.[id]?.files || {};
-      const managedEntries = Object.entries(oldFiles);
+      const managedEntries = Object.entries(oldLock?.[category]?.[id]?.files || {});
       if (managedEntries.length === 0) {
         console.warn(`  ⚠  Preserving unmanaged item: ${relativePath}`);
         continue;
@@ -391,7 +376,7 @@ async function deleteSelectedItems(absTarget, category, ids, oldLock, force, dry
         console.warn(`  ⚠  Preserving modified item: ${relativePath}`);
         continue;
       }
-      if (!FILE_BASED.has(category)) {
+      if (!isFileBased(category)) {
         if (!dryRun) {
           for (const [path] of managedEntries) await rm(resolve(absTarget, path), { force: true });
         }
@@ -472,7 +457,7 @@ export function validateSelections(selections) {
   return selections;
 }
 
-export async function install({ targetDir, agentType, selections, includeAgentsMd = true, writeAgentsMd, oldSelections, oldLock, force = false, dryRun = false }) {
+export async function install({ targetDir, agentType, selections, includeAgentsMd = true, writeAgentsMd, oldSelections, oldLock, force = false, dryRun = false, tuiPreferences }) {
   validateSelections(selections);
   if (oldLock) validateLock(oldLock);
   writeAgentsMd = writeAgentsMd ?? includeAgentsMd;
@@ -516,11 +501,11 @@ export async function install({ targetDir, agentType, selections, includeAgentsM
   }
 
   const tasks = [];
-  for (const category of ['skills', 'styles']) {
-    if (selections[category]?.length) tasks.push(copySelectedDirs(absTarget, category, selections[category], options));
-  }
-  for (const category of ['agents', 'commands', 'modes', 'memory', 'standards', 'templates']) {
-    if (selections[category]?.length) tasks.push(copySelectedFiles(absTarget, category, selections[category], options));
+  for (const category of LOCK_CATEGORIES) {
+    if (!isCopyable(category) || !selections[category]?.length) continue;
+    tasks.push(isFileBased(category)
+      ? copySelectedFiles(absTarget, category, selections[category], options)
+      : copySelectedDirs(absTarget, category, selections[category], options));
   }
   await Promise.all(tasks);
 
@@ -542,11 +527,11 @@ export async function install({ targetDir, agentType, selections, includeAgentsM
         mcpEntries: previousMcpEntries,
         includeAgentsMd: oldLock.includeAgentsMd ?? true,
       }));
-      previousTuiConfig = JSON.parse(generateTuiConfig({ selections: oldSelections }));
+      previousTuiConfig = JSON.parse(generateTuiConfig({ selections: oldSelections, preferences: tuiPreferences }));
     }
     const configJson = generateOpenCodeConfig({ selections, mcpEntries, includeAgentsMd });
     await mergeJsonFile(resolve(absTarget, 'opencode.json'), JSON.parse(configJson), 'opencode.json', options, previousOpenCodeConfig);
-    await mergeJsonFile(resolve(absTarget, 'tui.json'), JSON.parse(generateTuiConfig({ selections })), 'tui.json', options, previousTuiConfig);
+    await mergeJsonFile(resolve(absTarget, 'tui.json'), JSON.parse(generateTuiConfig({ selections, preferences: tuiPreferences })), 'tui.json', options, previousTuiConfig);
     await mergeGitignore(resolve(absTarget, '.gitignore'), options);
   }
 
@@ -596,10 +581,6 @@ function resolveSource(subpath) {
   return resolve(packageRoot, subpath);
 }
 
-function targetSubdir(sourceDir) {
-  return sourceDir.replace(/^framework\//, '');
-}
-
 async function isRemoved(category, id) {
   const catConfig = categories[category];
   if (!catConfig) return false;

package/src/item-layout.js

@@ -0,0 +1,26 @@
+import { categories } from './catalog.js';
+
+export const LOCK_CATEGORIES = Object.keys(categories);
+
+export function isFileBased(category) {
+  return categories[category]?.itemLayout === 'file';
+}
+
+export function isCopyable(category) {
+  const config = categories[category];
+  return Boolean(config?.itemLayout) && config.copyItems !== false;
+}
+
+export function targetSubdir(sourceDir) {
+  return sourceDir.replace(/^framework\//, '');
+}
+
+export function itemSourcePath(category, id) {
+  const config = categories[category];
+  return isFileBased(category) ? `${config.sourceDir}/${id}.md` : `${config.sourceDir}/${id}`;
+}
+
+export function itemRelativePath(category, id) {
+  const dir = targetSubdir(categories[category].sourceDir);
+  return isFileBased(category) ? `${dir}/${id}.md` : `${dir}/${id}`;
+}