@lidtop/loadout 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # Loadout
 
-Share a collection of agent skills and instructions with your team. Everyone in the repository picks the kits they want, keeping the full collection available without adding it all to their agent's context.
+Choose agent skills and instructions for yourself or your team. Loadout configures Codex and Claude Code.
 
-Kit definitions live in the repository. Each developer's selections and generated files stay local and ignored by Git. Loadout configures both Codex and Claude Code.
+Private kits and selections live in `.loadout-personal/`, ignored by Git. Add reusable kits to `~/.loadout/kits/` and enable them per repository.
 
 ## Use it
 
-Requires Node.js **22.13+**. In a repository using Loadout:
+Requires Node.js **22.13+**. Run in any repository:
 
 ```sh
 npm install -g @lidtop/loadout
@@ -15,7 +15,9 @@ loadout
 
 Pick your kits, select **Continue**, and confirm. Run `loadout` again to change your selection.
 
-## Add it to your repository
+Conflicting project instructions are skipped with a warning; the kit’s skills still install.
+
+## Share kits with your team
 
 ```sh
 loadout init

package/dist/adoption.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 import { exists, json, readOptional, safePath, walk, portableMode, } from './fs.js';
 import { isOutput } from './output-path.js';
 import { parse } from './schema.js';
-const manifestPath = '.loadout/adopted.json';
+const manifestPath = '.loadout-personal/adopted.json';
 const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const manifestSchema = z
     .object({
@@ -61,10 +61,10 @@ export function prepareAdoption(root, rendered, owned, global, allow) {
     for (const [file, entry] of Object.entries(manifest.files)) {
         if (!isOutput(file, global) || !Object.hasOwn(owned, file))
             throw new Error(`Unexpected adopted output: ${file}`);
-        const blobPath = `.loadout/adopted/${entry.hash}`;
+        const blobPath = `.loadout-personal/adopted/${entry.hash}`;
         const blob = read(root, blobPath);
         if (!blob || digest(blob.content) !== entry.hash)
-            throw new Error(`Original content is missing or changed for ${file}. Restore its .loadout/adopted backup before applying.`);
+            throw new Error(`Original content is missing or changed for ${file}. Restore its .loadout-personal/adopted backup before applying.`);
         blobs.set(blobPath, blob);
         originals.set(file, { content: blob.content, mode: entry.mode });
     }
@@ -125,7 +125,7 @@ export function prepareAdoption(root, rendered, owned, global, allow) {
             });
         const hash = digest(original.content);
         nextManifest.files[file] = { hash, mode: original.mode };
-        const blobPath = `.loadout/adopted/${hash}`;
+        const blobPath = `.loadout-personal/adopted/${hash}`;
         const existing = blobs.get(blobPath) ?? read(root, blobPath);
         if (existing && !existing.content.equals(original.content))
             throw new Error(`Original backup changed: ${blobPath}`);

package/dist/catalog.js

@@ -15,13 +15,16 @@ export function discover(cwd) {
         // A home catalog is global, never an implicit catalog for child projects.
         if (root === home && root !== initial)
             break;
-        if (exists(path.join(root, '.loadout/config.yaml')))
+        if (exists(path.join(root, '.loadout/config.yaml')) ||
+            exists(path.join(root, '.loadout-personal')))
             return root;
-        if (exists(path.join(root, '.git')) || path.dirname(root) === root)
+        if (exists(path.join(root, '.git')))
+            return root;
+        if (path.dirname(root) === root)
             break;
         root = path.dirname(root);
     }
-    throw new Error('No .loadout/config.yaml found in this repository. Run loadout init at the repository root.');
+    return initial;
 }
 function readYaml(root, relative) {
     try {
@@ -31,7 +34,7 @@ function readYaml(root, relative) {
         throw new Error(`${relative}: ${error.message}`);
     }
 }
-function validateKit(kit, root, global) {
+function validateKit(kit) {
     if (kit.ready === false)
         return;
     const dir = kit.directory;
@@ -51,15 +54,8 @@ function validateKit(kit, root, global) {
                 throw new Error(`${kit.id}: invalid condition on ${output.when.answer}`);
         }
         if (output.type === 'instructions') {
-            if (global && output.scope !== '.')
-                throw new Error(`${kit.id}: global instructions must use scope: .`);
             if (!fs.statSync(source).isFile())
                 throw new Error(`${kit.id}: instructions source must be a file`);
-            if (output.scope !== '.') {
-                const scope = safePath(root, output.scope);
-                if (!exists(scope) || !fs.statSync(scope).isDirectory())
-                    throw new Error(`${kit.id}: scope directory does not exist: ${output.scope}`);
-            }
         }
         else {
             if (!fs.statSync(source).isDirectory())
@@ -83,24 +79,51 @@ function validateKit(kit, root, global) {
     }
 }
 export function loadCatalog(root, global = path.resolve(root) === fs.realpathSync(os.homedir())) {
-    const config = parse(configSchema, readYaml(root, '.loadout/config.yaml'), '.loadout/config.yaml');
-    const directory = safePath(root, '.loadout/kits');
-    const kits = new Map();
-    for (const folder of exists(directory)
-        ? fs.readdirSync(directory).sort()
-        : []) {
-        const dir = safePath(directory, folder);
-        if (!fs.statSync(dir).isDirectory())
-            continue;
-        const manifest = `.loadout/kits/${folder}/kit.yaml`;
-        const kit = {
-            ...parse(kitSchema, readYaml(root, manifest), manifest),
-            directory: dir,
+    const home = fs.realpathSync(os.homedir());
+    const sources = [
+        ...(!global && root !== home
+            ? [
+                { root: home, directory: '.loadout', personal: true },
+                { root: home, directory: '.loadout-personal', personal: true },
+            ]
+            : []),
+        { root, directory: '.loadout', personal: global },
+        { root, directory: '.loadout-personal', personal: true },
+    ];
+    const configs = sources.map((source) => {
+        const file = `${source.directory}/config.yaml`;
+        const present = exists(safePath(source.root, file));
+        return {
+            ...source,
+            present,
+            config: parse(configSchema, present ? readYaml(source.root, file) : { schemaVersion: 1 }, `${source.root}/${file}`),
         };
-        if (kits.has(kit.id))
-            throw new Error(`Duplicate kit ID: ${kit.id}`);
-        validateKit(kit, root, global);
-        kits.set(kit.id, kit);
+    });
+    const config = {
+        curated: [...configs].reverse().find((source) => source.present)?.config.curated ??
+            true,
+        externalKits: configs.flatMap(({ config }) => config.externalKits),
+    };
+    const kits = new Map();
+    for (const source of configs) {
+        const directory = safePath(source.root, `${source.directory}/kits`);
+        for (const folder of exists(directory)
+            ? fs.readdirSync(directory).sort()
+            : []) {
+            const dir = safePath(directory, folder);
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+            const manifest = `${source.directory}/kits/${folder}/kit.yaml`;
+            const kit = {
+                ...parse(kitSchema, readYaml(source.root, manifest), manifest),
+                directory: dir,
+                ...(source.personal ? { origin: 'personal' } : {}),
+            };
+            if (kits.has(kit.id))
+                throw new Error(`Duplicate kit ID: ${kit.id}. Personal and repository kits must have distinct IDs.`);
+            validateKit(kit);
+            kits.set(kit.id, kit);
+        }
     }
     for (const [definitions, origin] of [
         [config.curated ? curatedKits : [], 'curated'],
@@ -137,7 +160,7 @@ export function loadCatalog(root, global = path.resolve(root) === fs.realpathSyn
             };
             if (kits.has(kit.id))
                 throw new Error(`Duplicate kit ID: ${kit.id}`);
-            validateKit(kit, root, global);
+            validateKit(kit);
             kits.set(kit.id, kit);
         }
     }

package/dist/cli.js

@@ -6,7 +6,7 @@ import os from 'node:os';
 import { discover } from './catalog.js';
 import { initialize } from './init.js';
 import { interactive, confirmApply, selectUpdates, confirmRetry, confirmAdoption, } from './interactive.js';
-import { apply, applyAll, plan } from './storage.js';
+import { apply, applyAll, hasChanges, plan } from './storage.js';
 import { renderWithExternal } from './external.js';
 import { DownloadCancelledError } from './retry.js';
 import { loadTarget } from './targets.js';
@@ -18,7 +18,7 @@ const program = new Command()
     .name('loadout')
     .description('Configure your repository’s agent tools.')
     .version(version)
-    .option('-g, --global', 'use the Loadout catalog in your home directory')
+    .option('-g, --global', 'enable kits for all repositories')
     .option('--offline', 'use saved external kits without network requests')
     .option('-C, --cwd <directory>', 'run in a different directory', process.cwd())
     .showHelpAfterError();
@@ -32,8 +32,7 @@ function context() {
     const { root, global } = targetRoot();
     const target = loadTarget(root, global);
     if (!target.catalog || !target.state)
-        throw new Error(target.error ??
-            `Loadout is not initialized here. Run loadout ${global ? '--global ' : ''}init.`);
+        throw new Error(target.error ?? 'Cannot load kits for this location.');
     return { catalog: target.catalog, state: target.state };
 }
 function interactiveTargets() {
@@ -54,15 +53,21 @@ function interactiveTargets() {
     const initial = global ? targets.length - 1 : 0;
     const current = targets[initial];
     if (!current.catalog)
-        throw new Error(current.error ??
-            `Loadout is not initialized here. Run loadout ${global ? '--global ' : ''}init.`);
+        throw new Error(current.error ?? 'Cannot load kits for this location.');
     return { targets, initial };
 }
+function showSkipped(result, preview = false) {
+    for (const skipped of result.skippedInstructions ?? [])
+        console.log(`Skipped instructions from ${skipped.kits.join(', ')} (${skipped.paths.join(', ')}): ${skipped.reason}.`);
+    for (const id of result.kitsWithoutOutputs ?? [])
+        console.log(`${id}: no agent outputs ${preview ? 'will be applied' : 'applied'}; all instructions skipped.`);
+}
 function preview(result, diff = false) {
-    const changed = result.changes.filter((c) => c.kind !== 'unchanged' && c.path !== '.gitignore');
+    showSkipped(result, true);
+    const changed = result.changes.filter((c) => c.kind !== 'unchanged' && !c.path.startsWith('.loadout-personal/'));
     if (!changed.length) {
-        console.log(result.changes.some((c) => c.kind !== 'unchanged')
-            ? 'Ignore rules will be refreshed.'
+        console.log(hasChanges(result)
+            ? 'Local settings will be refreshed.'
             : 'Generated files are unchanged.');
         return;
     }
@@ -71,8 +76,6 @@ function preview(result, diff = false) {
         console.log(`  ${change.kind === 'create' ? '+' : change.kind === 'delete' ? '-' : '~'} ${change.path}`);
     if (diff) {
         for (const change of changed) {
-            if (change.path.startsWith('.loadout/') || change.path === '.gitignore')
-                continue;
             const before = change.before?.content ?? Buffer.alloc(0), after = change.after?.content ?? Buffer.alloc(0);
             if (before.equals(after))
                 continue;
@@ -126,6 +129,7 @@ async function generate(catalog, state, opts) {
         const count = apply(result);
         if (count)
             console.log(`\nLoadout applied (${count} files changed).`);
+        showSkipped(result);
     }
 }
 async function setup() {
@@ -159,11 +163,17 @@ async function setup() {
             throw new DownloadCancelledError();
         plans.push(result);
     }
-    if (!plans.some((result) => result.changes.some((c) => c.kind !== 'unchanged')))
+    if (!plans.some(hasChanges))
         return;
     if (await confirmApply()) {
         applyAll(plans);
         console.log('\nYour loadout is ready.');
+        for (const result of plans) {
+            if (!result.skippedInstructions?.length)
+                continue;
+            console.log(result.root);
+            showSkipped(result);
+        }
     }
     else
         console.log('Cancelled. No kit selections or agent outputs saved.');
@@ -171,7 +181,7 @@ async function setup() {
 program.action(setup);
 program
     .command('init')
-    .description('create a starter catalog and open setup in a terminal')
+    .description('create an optional shared catalog and open setup')
     .action(async () => {
     const opts = program.opts();
     const root = opts.global ? os.homedir() : opts.cwd;
@@ -200,7 +210,7 @@ program
         console.log(`${kit.id} [${status}]\n  ${kitSource(kit)} · ${kit.description}`);
     }
     if (!catalog.kits.size)
-        console.log('No kits found. Add .loadout/kits/<name>/kit.yaml.');
+        console.log('No kits found. Add ~/.loadout/kits/<name>/kit.yaml.');
 });
 program
     .command('explain <kit>')

package/dist/external.js

@@ -31,11 +31,11 @@ const storeSchema = z
 })
     .strict();
 export function readExternal(root) {
-    const raw = readOptional(root, '.loadout/external.json');
+    const raw = readOptional(root, '.loadout-personal/external.json');
     return {
         raw,
         store: raw
-            ? parse(storeSchema, JSON.parse(raw.toString()), '.loadout/external.json')
+            ? parse(storeSchema, JSON.parse(raw.toString()), '.loadout-personal/external.json')
             : { schemaVersion: 1, kits: {} },
     };
 }

package/dist/ignore.d.ts

@@ -0,0 +1,7 @@
+export type IgnoreTarget = {
+    root: string;
+    key: string;
+    prefix: string;
+};
+export declare function ignoreTarget(root: string): IgnoreTarget | undefined;
+export declare function ignoredText(original: string, target: IgnoreTarget, paths: string[]): string;

package/dist/ignore.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+// Git resolves the common metadata directory for linked worktrees and repos
+// whose .git is a file. Exclude patterns are relative to the working-tree root.
+export function ignoreTarget(root) {
+    try {
+        const git = (...args) => execFileSync('git', ['-C', root, 'rev-parse', ...args], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).replace(/\r?\n$/, '');
+        const topPath = git('--show-toplevel');
+        const exclude = git('--path-format=absolute', '--git-path', 'info/exclude');
+        if (!path.isAbsolute(topPath) || !path.isAbsolute(exclude))
+            throw new Error('Git returned a non-absolute repository path.');
+        const top = fs.realpathSync(topPath);
+        const prefix = path.relative(top, root).split(path.sep).join('/');
+        if (/[\r\n]/.test(prefix))
+            throw new Error('Catalog paths containing newlines cannot be ignored.');
+        return {
+            root: fs.realpathSync(path.resolve(exclude, '../..')),
+            key: createHash('sha256').update(root).digest('hex').slice(0, 16),
+            prefix: prefix ? `${prefix}/` : '',
+        };
+    }
+    catch (error) {
+        const e = error;
+        if ((e.code === 'ENOENT' && e.syscall?.startsWith('spawn')) ||
+            e.stderr?.toString().includes('not a git repository'))
+            return undefined;
+        throw new Error(`Cannot resolve local Git excludes: ${e.message}`);
+    }
+}
+export function ignoredText(original, target, paths) {
+    const start = `# >>> loadout ${target.key}`;
+    const end = `# <<< loadout ${target.key}`;
+    const lines = original.split(/(?<=\n)/);
+    const markers = lines.map((line) => line.replace(/\r?\n$/, ''));
+    const first = markers.indexOf(start), last = markers.indexOf(end);
+    if (first < 0 !== last < 0 ||
+        last < first ||
+        markers.filter((line) => line === start).length > 1 ||
+        markers.filter((line) => line === end).length > 1)
+        throw new Error('Malformed Loadout block in Git info/exclude; repair its markers before applying.');
+    const escape = (p) => p.replace(/[\\*?\[\]#! ]/g, '\\$&');
+    const patterns = [...new Set(['.loadout-personal/', ...paths])]
+        .sort()
+        .map((p) => `/${escape(target.prefix + p)}`);
+    const block = `${start}\n${patterns.join('\n')}\n${end}\n`;
+    if (first >= 0) {
+        lines.splice(first, last - first + 1, block);
+        return lines.join('');
+    }
+    return `${original}${original && !original.endsWith('\n') ? '\n' : ''}${block}`;
+}

package/dist/init.js

@@ -2,15 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { exists, safePath } from './fs.js';
-import { ignoredText } from './storage.js';
+import { apply, planExcludes } from './storage.js';
 export function initialize(cwd, global = fs.realpathSync(cwd) === fs.realpathSync(os.homedir())) {
     const root = fs.realpathSync(cwd);
     const target = safePath(root, '.loadout');
     if (exists(target))
         throw new Error('.loadout already exists. Refusing to replace an existing catalog.');
-    const ignore = safePath(root, '.gitignore');
-    const original = exists(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
-    const updated = ignoredText(original, []); // Validate before creating anything.
+    const exclude = planExcludes(root, []); // Validate before creating anything.
     try {
         const starterFiles = {
             'config.yaml': 'schemaVersion: 1\n',
@@ -42,7 +40,11 @@ and set ready: true in the kit's kit.yaml when it is ready to use.
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.writeFileSync(file, content, { flag: 'wx' });
         }
-        fs.writeFileSync(ignore, updated);
+        apply({
+            root,
+            changes: [],
+            exclude,
+        });
     }
     catch (error) {
         fs.rmSync(target, { recursive: true, force: true });

package/dist/interactive.js

@@ -2,7 +2,6 @@ import { checkbox, confirm, select } from '@inquirer/prompts';
 import { configure } from './resolve.js';
 import { validAnswer } from './schema.js';
 import { targetPicker } from './picker.js';
-import { initializeTarget } from './targets.js';
 import { availableUpdates, updateDescription } from './updates.js';
 export async function interactive(targets, initial = 0) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
@@ -10,7 +9,6 @@ export async function interactive(targets, initial = 0) {
     const chosen = await targetPicker({
         targets,
         initial,
-        initialize: initializeTarget,
     });
     const configured = [];
     for (const { target, state } of chosen) {

package/dist/locations.d.ts

@@ -0,0 +1 @@
+export declare function stateDirectory(root: string): string;

package/dist/locations.js

@@ -0,0 +1,4 @@
+import { safePath } from './fs.js';
+export function stateDirectory(root) {
+    return safePath(root, '.loadout-personal');
+}

package/dist/picker.d.ts

@@ -11,7 +11,6 @@ export type TargetPickerConfig = {
     initial?: number;
     columns?: number;
     rows?: number;
-    initialize?: (target: Target) => Target;
 };
 export type TargetSelection = {
     target: Target;
@@ -22,7 +21,6 @@ declare const renderPicker: import("@inquirer/type").Prompt<TargetSelection[], {
     initial?: number;
     columns?: number;
     rows?: number;
-    initialize?: (target: Target) => Target;
 } & TargetPickerConfig>;
 export declare function targetPicker(config: TargetPickerConfig, context?: Parameters<typeof renderPicker>[1]): Promise<TargetSelection[]>;
 export declare function kitPicker(config: PickerConfig, context?: Parameters<typeof targetPicker>[1]): Promise<string[]>;

package/dist/picker.js

@@ -1,6 +1,5 @@
 import { createPrompt, useEffect, useKeypress, useState, isEnterKey, isSpaceKey, } from '@inquirer/core';
 import { stripVTControlCharacters, styleText } from 'node:util';
-import path from 'node:path';
 import stringWidth from 'string-width';
 import { resolveKits, reasons } from './resolve.js';
 import { kitSource } from './schema.js';
@@ -35,7 +34,10 @@ function wordmark(width, rows) {
     ];
 }
 const repositorySections = ['Kits', 'Browse', 'Installed'];
-const providerFor = (kit) => kit.origin === 'bundled' ? 'loadout' : kit.external?.repo;
+const providerFor = (kit) => kit.origin === 'bundled'
+    ? 'loadout'
+    : (kit.external?.repo ??
+        (kit.origin === 'personal' ? 'Personal' : undefined));
 const providerPrefixes = {
     loadout: 'loadout-',
     'mattpocock/skills': 'matt-pocock-',
@@ -52,7 +54,6 @@ const renderPicker = createPrompt((config, done) => {
     const [visited, setVisited] = useState([config.initial ?? 0]);
     const [selections, setSelections] = useState(config.targets.map((target) => (target.state?.selected ?? []).filter((id) => target.catalog?.kits.has(id) &&
         target.catalog.kits.get(id)?.ready !== false)));
-    const [pending, setPending] = useState(undefined);
     const [pendingSwitch, setPendingSwitch] = useState(undefined);
     const [notice, setNotice] = useState('');
     const target = targets[targetIndex];
@@ -67,7 +68,10 @@ const renderPicker = createPrompt((config, done) => {
     const hasSelectionChanges = JSON.stringify([...selected].sort()) !==
         JSON.stringify([...(target.state?.selected ?? [])].sort());
     const setSelected = (value) => setSelections(selections.map((ids, index) => (index === targetIndex ? value : ids)));
-    const [section, setSection] = useState(target.global ? 'Browse' : 'Kits');
+    const [section, setSection] = useState(target.global ||
+        ![...catalog.kits.values()].some((kit) => !providerFor(kit))
+        ? 'Browse'
+        : 'Kits');
     const [scopeFocused, setScopeFocused] = useState(false);
     const [provider, setProvider] = useState(undefined);
     const [query, setQuery] = useState('');
@@ -132,13 +136,15 @@ const renderPicker = createPrompt((config, done) => {
             const origins = new Set(kits.map((kit) => kit.origin));
             const description = id === 'loadout'
                 ? 'Included with Loadout'
-                : origins.has('curated') && providerDescriptions[id]
-                    ? providerDescriptions[id]
-                    : origins.size > 1
-                        ? 'Curated and repository sources'
-                        : origins.has('curated')
-                            ? 'Curated kits'
-                            : 'Repository sources';
+                : id === 'Personal'
+                    ? 'Your personal kits'
+                    : origins.has('curated') && providerDescriptions[id]
+                        ? providerDescriptions[id]
+                        : origins.size > 1
+                            ? 'Curated and repository sources'
+                            : origins.has('curated')
+                                ? 'Curated kits'
+                                : 'Repository sources';
             return [
                 {
                     id,
@@ -187,7 +193,10 @@ const renderPicker = createPrompt((config, done) => {
         const switchTarget = (index) => {
             setScopeFocused(false);
             setTargetIndex(index);
-            setSection(targets[index].global ? 'Browse' : 'Kits');
+            setSection(targets[index].global ||
+                ![...targets[index].catalog.kits.values()].some((kit) => !providerFor(kit))
+                ? 'Browse'
+                : 'Kits');
             setVisited([...new Set([...visited, index])]);
             setProvider(undefined);
             setNotice('');
@@ -206,40 +215,14 @@ const renderPicker = createPrompt((config, done) => {
             }
             return;
         }
-        if (pending !== undefined) {
-            if (key.name === 'y' && config.initialize) {
-                try {
-                    const initialized = config.initialize(targets[pending]);
-                    if (!initialized.catalog)
-                        throw new Error(initialized.error ??
-                            'Initialization did not produce a catalog.');
-                    setTargets(targets.map((item, index) => index === pending ? initialized : item));
-                    setSelections(selections.map((ids, index) => index === pending ? (initialized.state?.selected ?? []) : ids));
-                    switchTarget(pending);
-                }
-                catch (error) {
-                    setNotice(error.message);
-                }
-                setPending(undefined);
-            }
-            else if (key.name === 'n' ||
-                key.name === 'escape' ||
-                isEnterKey(key)) {
-                setPending(undefined);
-            }
-            restoreInput();
-            return;
-        }
         if (scopeFocused && (isEnterKey(key) || isSpaceKey(key))) {
             setScopeFocused(false);
             const next = (targetIndex + 1) % targets.length;
             const other = targets[next];
             if (other.error)
                 setNotice(other.error);
-            else if (!other.catalog) {
-                setPending(next);
-                reset();
-            }
+            else if (!other.catalog)
+                setNotice('Cannot load this location.');
             else if (hasSelectionChanges) {
                 setPendingSwitch(next);
             }
@@ -348,27 +331,6 @@ const renderPicker = createPrompt((config, done) => {
             `  ${accent('[Enter/Esc]')} Stay   ${accent('[y]')} Switch`,
             '\u001b[?25l',
         ].join('\n');
-    if (pending !== undefined) {
-        const destination = targets[pending];
-        const pathWidth = width - 9;
-        const catalogPath = path.join(destination.root, '.loadout');
-        const displayPath = stringWidth(clean(catalogPath)) <= pathWidth
-            ? clean(catalogPath)
-            : destination.global
-                ? '~/.loadout'
-                : `${fit(destination.root, pathWidth - 9)}/.loadout`;
-        return [
-            ...header,
-            ...scopeLines,
-            '',
-            `  ${bold(fit(`Set up ${destination.label} and switch?`, width - 2))}`,
-            `  ${fit(`Create ${displayPath}`, width - 2)}`,
-            ...selectionWarning,
-            '',
-            `  ${accent('[Enter/Esc]')} Cancel   ${accent('[y]')} Set up`,
-            '\u001b[?25l',
-        ].join('\n');
-    }
     if (finished)
         return [
             ...header,
@@ -384,7 +346,7 @@ const renderPicker = createPrompt((config, done) => {
     const detailed = height >= 20;
     const hints = scopeFocused
         ? [
-            `space/enter ${other?.error ? 'details' : other?.catalog ? 'switch' : 'setup'}`,
+            `space/enter ${other?.error || !other?.catalog ? 'details' : 'switch'}`,
             '←→/tab move',
             'esc back',
         ]
@@ -406,9 +368,9 @@ const renderPicker = createPrompt((config, done) => {
     }
     const help = helpLines.map((line) => `  ${muted(line)}`);
     if (scopeFocused && other) {
-        const action = other.error
+        const action = other.error || !other.catalog
             ? `${other.label} is unavailable`
-            : `${other.catalog ? 'Switch to' : 'Set up'} ${other.label}`;
+            : `Switch to ${other.label}`;
         return [
             ...header,
             ...scopeLines,

package/dist/render.d.ts

@@ -6,6 +6,11 @@ export type FileContent = {
 export type Rendered = {
     files: Map<string, FileContent>;
     skillRoots: Set<string>;
+    instructionGroups: {
+        paths: string[];
+        kits: string[];
+    }[];
+    skillKits: Set<string>;
     external?: {
         before?: Buffer;
         content: Buffer;

package/dist/render.js

@@ -1,27 +1,43 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { agents } from './schema.js';
-import { safePath, walk, portableMode } from './fs.js';
+import { safePath, walk, portableMode, exists } from './fs.js';
 import { resolveKits } from './resolve.js';
 export function render(catalog, state) {
     const files = new Map();
     const skillRoots = new Set();
+    const skillKits = new Set();
+    const instructionGroups = [];
+    const instructionKits = new Map();
     const sections = new Map();
     for (const id of resolveKits(catalog, state.selected)) {
         const kit = catalog.kits.get(id);
+        if (kit.external)
+            skillKits.add(id);
         for (const output of kit.outputs) {
             if (output.when &&
                 state.answers[id]?.[output.when.answer] !== output.when.equals)
                 continue;
             const source = safePath(kit.directory, output.source);
             if (output.type === 'instructions') {
+                if (catalog.global && output.scope !== '.')
+                    throw new Error(`${kit.id}: global instructions must use scope: .`);
+                if (output.scope !== '.') {
+                    const scope = safePath(catalog.root, output.scope);
+                    if (!exists(scope) || !fs.statSync(scope).isDirectory())
+                        throw new Error(`${kit.id}: scope directory does not exist: ${output.scope}`);
+                }
                 const section = fs.readFileSync(source, 'utf8').trim();
+                const kits = instructionKits.get(output.scope) ?? new Set();
+                kits.add(id);
+                instructionKits.set(output.scope, kits);
                 sections.set(output.scope, [
                     ...(sections.get(output.scope) ?? []),
                     section,
                 ]);
             }
             else {
+                skillKits.add(id);
                 for (const agent of agents) {
                     const destination = `${agent === 'codex' ? '.agents' : '.claude'}/skills/${path.basename(source)}`;
                     if (skillRoots.has(destination))
@@ -47,6 +63,10 @@ export function render(catalog, state) {
             : path.posix.join(scope, 'CLAUDE.md');
         if (files.has(instructions) || files.has(claude))
             throw new Error(`Output collision: ${scope}`);
+        instructionGroups.push({
+            paths: [instructions, claude],
+            kits: [...instructionKits.get(scope)],
+        });
         files.set(instructions, {
             content: Buffer.from(`${content.join('\n\n')}\n`),
             mode: 0o644,
@@ -60,5 +80,7 @@ export function render(catalog, state) {
     return {
         files: new Map([...files].sort(([a], [b]) => a.localeCompare(b))),
         skillRoots,
+        instructionGroups,
+        skillKits,
     };
 }

package/dist/schema.d.ts

@@ -97,7 +97,7 @@ export type Kit = z.infer<typeof kitSchema> & {
     directory: string;
     external?: ExternalSource;
     pinned?: ExternalSource;
-    origin?: 'curated' | 'external' | 'bundled';
+    origin?: 'curated' | 'external' | 'bundled' | 'personal';
 };
 export type Catalog = {
     root: string;

package/dist/schema.js

@@ -14,7 +14,14 @@ export const relativePath = z
             .every((s) => s !== '..' && s !== '.' && s !== '' && !s.endsWith(' '))), 'Use a relative path without traversal, glob characters, or backslashes');
 export const scopeSchema = relativePath.refine((p) => !p
     .split('/')
-    .some((s) => ['.git', '.loadout', '.agents', '.claude', '.codex'].includes(s)), 'Scope must be a repository directory outside configuration directories');
+    .some((s) => [
+    '.git',
+    '.loadout',
+    '.loadout-personal',
+    '.agents',
+    '.claude',
+    '.codex',
+].includes(s)), 'Scope must be a repository directory outside configuration directories');
 const condition = z
     .object({ answer: idSchema, equals: z.union([z.boolean(), z.string()]) })
     .strict();
@@ -128,7 +135,8 @@ export function parse(schema, value, label) {
 export function kitSource(kit) {
     return kit.origin === 'bundled'
         ? 'loadout'
-        : ((kit.pinned ?? kit.external)?.repo ?? 'Repository');
+        : ((kit.pinned ?? kit.external)?.repo ??
+            (kit.origin === 'personal' ? 'Personal' : 'Repository'));
 }
 export function sameSource(a, b) {
     return (a.repo === b.repo &&

package/dist/storage.d.ts

@@ -1,3 +1,4 @@
+import { type IgnoreTarget } from './ignore.js';
 import { type Catalog, type State } from './schema.js';
 import { type FileContent, type Rendered } from './render.js';
 export type Change = {
@@ -10,6 +11,13 @@ export type Plan = {
     root: string;
     changes: Change[];
     adopted?: string[];
+    skippedInstructions?: {
+        paths: string[];
+        kits: string[];
+        reason: string;
+    }[];
+    kitsWithoutOutputs?: string[];
+    exclude?: ExcludePlan;
     guard?: {
         untracked: string[];
         directories: {
@@ -19,9 +27,16 @@ export type Plan = {
     };
 };
 export declare function loadState(catalog: Catalog): State;
-export declare function ignoredText(original: string, paths: string[]): string;
+type ExcludePlan = {
+    target: IgnoreTarget;
+    paths: string[];
+    change: Change;
+};
+export declare function planExcludes(root: string, paths: string[]): ExcludePlan | undefined;
+export declare function hasChanges(plan: Plan): boolean;
 export declare function plan(catalog: Catalog, state: State, rendered: Rendered, options?: {
     adopt?: boolean;
 }): Plan;
 export declare function apply(plan: Plan): number;
 export declare function applyAll(plans: Plan[]): number;
+export {};

package/dist/storage.js

@@ -1,18 +1,17 @@
 import fs from 'node:fs';
 import { isOutput } from './output-path.js';
+import { ignoredText, ignoreTarget } from './ignore.js';
 import { prepareAdoption } from './adoption.js';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { exists, json, readOptional, safePath, walk, portableMode, } from './fs.js';
 import { parse, ownedSchema, stateSchema, } from './schema.js';
-const start = '# >>> loadout';
-const end = '# <<< loadout';
 const hash = (content) => createHash('sha256').update(content).digest('hex');
 export function loadState(catalog) {
-    const raw = readOptional(catalog.root, '.loadout/local.json');
+    const raw = readOptional(catalog.root, '.loadout-personal/local.json');
     return raw
-        ? parse(stateSchema, JSON.parse(raw.toString()), '.loadout/local.json')
+        ? parse(stateSchema, JSON.parse(raw.toString()), '.loadout-personal/local.json')
         : { schemaVersion: 1, selected: [], answers: {} };
 }
 function snapshot(root, relative) {
@@ -29,33 +28,29 @@ function equal(a, b) {
         ? a === b
         : a.mode === b.mode && a.content.equals(b.content);
 }
-export function ignoredText(original, paths) {
-    const lines = original.split(/\r?\n/);
-    const first = lines.indexOf(start), last = lines.indexOf(end);
-    if (first < 0 !== last < 0 ||
-        last < first ||
-        lines.filter((l) => l === start).length > 1 ||
-        lines.filter((l) => l === end).length > 1)
-        throw new Error('Malformed Loadout block in .gitignore; repair its markers before applying.');
-    if (first >= 0)
-        lines.splice(first, last - first + 1);
-    const base = lines.join('\n').replace(/\n*$/, '');
-    // Escape gitignore metacharacters so these patterns own only exact paths.
-    const escape = (p) => p.replace(/[\\*?\[\]#! ]/g, '\\$&');
-    return `${base ? `${base}\n\n` : ''}${start}\n${[
-        ...new Set([
-            '.loadout/local.json',
-            '.loadout/generated.json',
-            '.loadout/external.json',
-            '.loadout/adopted.json',
-            '.loadout/adopted/',
-            '.loadout/apply.lock/',
-            ...paths,
-        ]),
-    ]
-        .sort()
-        .map((p) => `/${escape(p)}`)
-        .join('\n')}\n${end}\n`;
+export function planExcludes(root, paths) {
+    const target = ignoreTarget(root);
+    if (!target)
+        return undefined;
+    const before = snapshot(target.root, 'info/exclude');
+    const after = {
+        content: Buffer.from(ignoredText(before?.content.toString() ?? '', target, paths)),
+        mode: before?.mode ?? 0o644,
+    };
+    return {
+        target,
+        paths,
+        change: {
+            path: 'info/exclude',
+            before,
+            after,
+            kind: equal(before, after) ? 'unchanged' : before ? 'update' : 'create',
+        },
+    };
+}
+export function hasChanges(plan) {
+    return (plan.changes.some((change) => change.kind !== 'unchanged') ||
+        !!(plan.exclude && plan.exclude.change.kind !== 'unchanged'));
 }
 function trackedFiles(root) {
     try {
@@ -76,27 +71,43 @@ function trackedFiles(root) {
 }
 export function plan(catalog, state, rendered, options = {}) {
     const root = catalog.root;
-    const raw = readOptional(root, '.loadout/generated.json');
+    const raw = readOptional(root, '.loadout-personal/generated.json');
     const owned = raw
-        ? parse(ownedSchema, JSON.parse(raw.toString()), '.loadout/generated.json')
-            .files
+        ? parse(ownedSchema, JSON.parse(raw.toString()), '.loadout-personal/generated.json').files
         : {};
+    const tracked = trackedFiles(root);
+    const skippedInstructions = [];
+    const retainedKits = new Set(rendered.skillKits);
+    rendered = { ...rendered, files: new Map(rendered.files) };
+    for (const group of rendered.instructionGroups) {
+        // Existing ownership still requires the usual edit/deletion safeguards.
+        const conflict = group.paths.some((file) => Object.hasOwn(owned, file))
+            ? undefined
+            : group.paths.find((file) => tracked.has(file) ||
+                (!options.adopt && exists(safePath(root, file))));
+        if (!conflict) {
+            for (const id of group.kits)
+                retainedKits.add(id);
+            continue;
+        }
+        skippedInstructions.push({
+            ...group,
+            reason: tracked.has(conflict)
+                ? `${conflict} is tracked by Git`
+                : `${conflict} already exists and is not managed by Loadout`,
+        });
+        // CLAUDE.md imports AGENTS.md, so skip the whole scope together.
+        for (const file of group.paths)
+            rendered.files.delete(file);
+    }
+    const kitsWithoutOutputs = [
+        ...new Set(skippedInstructions.flatMap((group) => group.kits)),
+    ].filter((id) => !retainedKits.has(id));
     const adoption = prepareAdoption(root, rendered, owned, !!catalog.global, !!options.adopt);
     rendered = { ...rendered, files: adoption.files };
     const paths = [
         ...new Set([...Object.keys(owned), ...rendered.files.keys()]),
     ].sort();
-    const tracked = trackedFiles(root);
-    for (const local of [
-        '.loadout/local.json',
-        '.loadout/generated.json',
-        '.loadout/external.json',
-        '.loadout/adopted.json',
-        ...adoption.beforeOutputs.map((change) => change.path),
-        ...adoption.afterOutputs.map((change) => change.path),
-    ])
-        if (tracked.has(local))
-            throw new Error(`${local} is tracked by Git. Untrack personal state before applying.`);
     const changes = [...adoption.beforeOutputs];
     for (const relative of paths) {
         if (!isOutput(relative, catalog.global))
@@ -137,22 +148,16 @@ export function plan(catalog, state, rendered, options = {}) {
         .filter(([p]) => !adoption.released.has(p))
         .map(([p, f]) => [p, { hash: hash(f.content), mode: f.mode }]));
     const metadata = new Map([
-        ['.loadout/local.json', json(state)],
-        ['.loadout/generated.json', json({ schemaVersion: 1, files })],
-        [
-            '.gitignore',
-            Buffer.from(ignoredText(readOptional(root, '.gitignore')?.toString() ?? '', [
-                ...Object.keys(files),
-            ])),
-        ],
+        ['.loadout-personal/local.json', json(state)],
+        ['.loadout-personal/generated.json', json({ schemaVersion: 1, files })],
     ]);
     if (rendered.external) {
-        const current = readOptional(root, '.loadout/external.json');
+        const current = readOptional(root, '.loadout-personal/external.json');
         if (current === undefined
             ? rendered.external.before !== undefined
             : !rendered.external.before?.equals(current))
             throw new Error('External snapshots changed while preparing the preview. Run the command again.');
-        metadata.set('.loadout/external.json', rendered.external.content);
+        metadata.set('.loadout-personal/external.json', rendered.external.content);
     }
     changes.push(...adoption.afterOutputs);
     for (const [relative, content] of metadata) {
@@ -164,14 +169,18 @@ export function plan(catalog, state, rendered, options = {}) {
             kind: equal(before, after) ? 'unchanged' : before ? 'update' : 'create',
         });
     }
+    for (const change of changes)
+        if (tracked.has(change.path))
+            throw new Error(`Refusing to manage Git-tracked file: ${change.path}`);
     return {
         root,
         changes,
         adopted: adoption.adopted,
+        skippedInstructions,
+        kitsWithoutOutputs,
+        exclude: planExcludes(root, Object.keys(files)),
         guard: {
-            untracked: changes
-                .filter((change) => change.path !== '.gitignore')
-                .map((change) => change.path),
+            untracked: changes.map((change) => change.path),
             directories: [...rendered.skillRoots]
                 .filter((skill) => adoption.adopted.some((file) => file.startsWith(`${skill}/`)))
                 .map((skill) => ({
@@ -202,7 +211,9 @@ function prune(root, relative) {
     // Repository scopes and agent configuration roots may predate Loadout.
     // Only prune empty skill directories and internal adoption backups.
     const boundary = /^(\.(?:agents|claude)\/skills)\//.exec(relative)?.[1] ??
-        (relative.startsWith('.loadout/adopted/') ? '.loadout' : undefined);
+        (relative.startsWith('.loadout-personal/adopted/')
+            ? '.loadout-personal'
+            : undefined);
     if (!boundary)
         return;
     const stop = safePath(root, boundary);
@@ -223,22 +234,77 @@ export function apply(plan) {
 export function applyAll(plans) {
     if (new Set(plans.map((plan) => plan.root)).size !== plans.length)
         throw new Error('Cannot apply multiple plans for the same location.');
+    // Several catalogs/worktrees can share one excludes file. Merge their blocks
+    // into one transactional write, retaining all other catalogs' rules.
+    const excludes = new Map();
+    for (const plan of plans) {
+        if (!plan.exclude)
+            continue;
+        const { target, paths, change } = plan.exclude;
+        const previous = excludes.get(target.root);
+        if (!previous) {
+            excludes.set(target.root, change);
+            continue;
+        }
+        if (!equal(previous.before, change.before))
+            throw new Error('Git excludes changed between previews. Run the command again.');
+        const after = {
+            ...change.after,
+            content: Buffer.from(ignoredText(previous.after.content.toString(), target, paths)),
+        };
+        excludes.set(target.root, {
+            ...previous,
+            after,
+            kind: equal(previous.before, after)
+                ? 'unchanged'
+                : previous.before
+                    ? 'update'
+                    : 'create',
+        });
+    }
+    const writes = [
+        ...[...excludes].map(([root, change]) => ({ root, change })),
+        ...plans.flatMap((plan) => plan.changes.map((change) => ({
+            root: plan.root,
+            change,
+        }))),
+    ];
     const locks = [];
     const written = [];
     try {
         for (const plan of [...plans].sort((a, b) => a.root.localeCompare(b.root))) {
-            const lock = safePath(plan.root, '.loadout/apply.lock');
+            const lock = safePath(plan.root, '.loadout-personal/apply.lock');
+            fs.mkdirSync(path.dirname(lock), { recursive: true });
+            try {
+                fs.mkdirSync(lock);
+            }
+            catch (error) {
+                if (error.code === 'EEXIST')
+                    throw new Error(`Another apply is running (or a previous process stopped). Remove ${lock} only after confirming no Loadout process is running.`);
+                throw error;
+            }
+            locks.push(lock);
+        }
+        // These locks also serialize applies from different linked worktrees.
+        for (const root of [...excludes.keys()].sort()) {
+            const lock = safePath(root, 'info/exclude.loadout.lock');
+            fs.mkdirSync(path.dirname(lock), { recursive: true });
             try {
                 fs.mkdirSync(lock);
             }
             catch (error) {
                 if (error.code === 'EEXIST')
-                    throw new Error('Another apply is running (or a previous process stopped). Remove .loadout/apply.lock only after confirming no Loadout process is running.');
+                    throw new Error(`Another apply is using Git excludes (or a previous process stopped). Remove ${lock} only after confirming no Loadout process is running.`);
                 throw error;
             }
             locks.push(lock);
         }
         // Recheck every location before writing to any of them.
+        for (const plan of plans) {
+            const current = ignoreTarget(plan.root);
+            if (JSON.stringify(current) !== JSON.stringify(plan.exclude?.target))
+                throw new Error('Git exclude location changed since preview. Run the command again.');
+        }
         for (const plan of plans) {
             if (!plan.guard)
                 continue;
@@ -252,20 +318,17 @@ export function applyAll(plans) {
                     throw new Error(`Skill directory changed since preview: ${directory.path}`);
             }
         }
-        for (const plan of plans)
-            for (const change of plan.changes)
-                if (!equal(snapshot(plan.root, change.path), change.before))
-                    throw new Error(`File changed since preview: ${change.path}. Run the command again.`);
-        for (const plan of plans) {
-            for (const change of plan.changes) {
-                if (change.kind === 'unchanged')
-                    continue;
-                if (change.after)
-                    writeAtomic(plan.root, change.path, change.after);
-                else
-                    fs.unlinkSync(safePath(plan.root, change.path));
-                written.push({ root: plan.root, change });
-            }
+        for (const { root, change } of writes)
+            if (!equal(snapshot(root, change.path), change.before))
+                throw new Error(`File changed since preview: ${change.path}. Run the command again.`);
+        for (const { root, change } of writes) {
+            if (change.kind === 'unchanged')
+                continue;
+            if (change.after)
+                writeAtomic(root, change.path, change.after);
+            else
+                fs.unlinkSync(safePath(root, change.path));
+            written.push({ root, change });
         }
     }
     catch (error) {

package/dist/targets.d.ts

@@ -8,4 +8,3 @@ export type Target = {
     error?: string;
 };
 export declare function loadTarget(root: string, global: boolean): Target;
-export declare function initializeTarget(target: Target): Target;

package/dist/targets.js

@@ -1,7 +1,5 @@
 import { loadCatalog } from './catalog.js';
 import { readExternal } from './external.js';
-import { exists, safePath } from './fs.js';
-import { initialize } from './init.js';
 import { loadState } from './storage.js';
 export function loadTarget(root, global) {
     const target = {
@@ -10,10 +8,8 @@ export function loadTarget(root, global) {
         label: global ? 'Global' : 'Repository',
     };
     try {
-        if (!exists(safePath(root, '.loadout/config.yaml')))
-            return target;
         const catalog = loadCatalog(root, global);
-        const { store } = readExternal(root);
+        const { store } = readExternal(catalog.root);
         for (const [id, snapshot] of Object.entries(store.kits)) {
             const kit = catalog.kits.get(id);
             if (kit?.external)
@@ -25,7 +21,3 @@ export function loadTarget(root, global) {
         return { ...target, error: error.message };
     }
 }
-export function initializeTarget(target) {
-    initialize(target.root, target.global);
-    return loadTarget(target.root, target.global);
-}

package/kits/write-kit/skills/loadout-write-kit/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: loadout-write-kit
-description: Create or edit Loadout kits in .loadout/kits/.
+description: Create or edit private or shared Loadout kits.
 ---
 
-Adapt this example; drop unused questions, outputs, and files.
+Use `.loadout-personal/kits/` for private kits, `.loadout/kits/` for shared kits, or `~/.loadout/kits/` for kits you can enable in any repository. Adapt this example; drop unused questions, outputs, and files.
 
-`.loadout/kits/review/kit.yaml`:
+`.loadout-personal/kits/review/kit.yaml`:
 
 ```yaml
 schemaVersion: 1
@@ -28,7 +28,7 @@ outputs:
     when: { answer: detail, equals: detailed }
 ```
 
-`.loadout/kits/review/skills/review/SKILL.md`:
+`.loadout-personal/kits/review/skills/review/SKILL.md`:
 
 ```markdown
 ---
@@ -52,4 +52,4 @@ loadout enable review --answer review.diagrams=true --answer review.detail=detai
 loadout disable review
 ```
 
-Drop `--dry-run --diff` to apply, or select via `loadout` → Kits → Continue.
+Drop `--dry-run --diff` to apply, or select via `loadout` → Browse → Personal → Continue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lidtop/loadout",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Choose and manage agent instruction and skill kits for repositories and your home directory.",
   "type": "module",
   "bin": {