loadouts 0.1.11

package/docs/troubleshooting.md

@@ -0,0 +1,147 @@
+# Troubleshooting
+
+## Common Issues
+
+### "No .loadouts/ directory found"
+
+Run `loadouts init` to create one, or check you're in the right directory.
+
+### "Loadout not found: <name>"
+
+The loadout doesn't exist in the current scope. Check available loadouts:
+```bash
+loadouts list        # Project scope
+loadouts list -g     # Global scope
+loadouts list -a     # Both scopes
+```
+
+### "Cannot infer artifact kind for path"
+
+The file path doesn't match any known kind. Built-in kinds expect:
+- **Rules:** `rules/*.md`
+- **Skills:** `skills/<name>/SKILL.md`
+- **Instructions:** `instructions/AGENTS.*.md`
+- **Prompts:** `prompts/*.md`
+
+For custom artifact types, create a `.loadouts/kinds/*.yaml` definition. Run `loadouts kinds -v` to see all registered kinds and their detection rules.
+
+### "Include not found"
+
+A file in your loadout's `include` list doesn't exist. Paths are relative to `.loadouts/`.
+
+### Outputs not updating after edits
+
+Run `loadouts sync` to regenerate outputs from sources. Then verify with `loadouts status`.
+
+If outputs still don't appear, check:
+1. Is the artifact included in an active loadout? (`loadouts info`)
+2. Is the loadout activated? (`loadouts status`)
+
+### Symlinks broken after moving project
+
+Symlinks use absolute paths. Run `loadouts sync` to recreate them.
+
+### Tool not picking up rules/skills
+
+First, verify outputs were rendered:
+```bash
+loadouts status    # Check for drift or missing outputs
+loadouts sync      # Re-render if needed
+```
+
+**Cursor:** Rules need `.mdc` extension — loadouts handles this automatically. Restart Cursor if rules don't appear immediately.
+
+**OpenCode:** Rules require the `opencode-rules` plugin. Add to `opencode.json`:
+```json
+{ "plugins": ["opencode-rules"] }
+```
+
+**Claude Code:** Verify rules exist in `.claude/rules/`. May require restarting the session.
+
+**Codex:** Rules not yet supported; skills and instructions only.
+
+---
+
+## Validation
+
+Run validation to catch issues:
+```bash
+loadouts check -v
+```
+
+Validates:
+- YAML syntax
+- All referenced files exist
+- No circular `extends`
+- Tool prerequisites satisfied
+- No unmanaged file collisions (shadowed files)
+
+### Shadowed file collision
+
+A **shadowed file** occurs when loadouts wants to write to a path that already has an unmanaged file. Loadouts never overwrites unmanaged files — it skips them and reports the collision.
+
+**To resolve:**
+```bash
+loadouts rule import .cursor/rules/existing.mdc  # Import into loadout
+# OR
+rm .cursor/rules/existing.mdc && loadouts sync  # Remove and re-render
+# OR keep the unmanaged file (it takes precedence)
+```
+
+---
+
+## Debugging
+
+### Preview changes without applying
+```bash
+loadouts activate backend --dry-run
+loadouts sync --dry-run
+```
+
+### See what's active
+```bash
+loadouts status
+loadouts info
+```
+
+### Check token cost
+```bash
+loadouts info backend    # Shows upfront and lazy tokens
+```
+
+---
+
+## Removing Loadouts
+
+### From a project
+
+**Warning:** These commands delete your loadout configuration. Back up `.loadouts/` first if you want to preserve your rules and skills.
+
+```bash
+loadouts clear           # Remove all managed outputs (safe, reversible)
+```
+
+To fully remove loadouts from a project:
+```bash
+loadouts clear           # Remove managed outputs first
+rm -rf .loadouts        # Delete source config (irreversible)
+rm CLAUDE.md            # Remove generated wrapper if present
+```
+
+### Global config
+
+```bash
+loadouts clear -g        # Remove global managed outputs
+rm -rf ~/.config/loadouts  # Delete global config (irreversible)
+```
+
+---
+
+## Getting Help
+
+```bash
+loadouts --help          # Command overview
+loadouts <cmd> --help    # Command-specific help
+loadouts docs            # Full documentation
+loadouts docs <topic>    # Topic-specific docs
+```

package/docs/visual-language.md

@@ -0,0 +1,251 @@
+# Loadouts CLI Visual Language
+
+This document defines the unified visual language for all loadouts CLI output. Follow these patterns when adding or modifying commands to maintain consistency.
+
+## Core Principle
+
+**Artifact-first, tool-secondary.**
+
+- **Vertical axis (rows)** → Artifacts (what the user cares about)
+- **Horizontal axis (columns)** → Tools (where artifacts go)
+- **Cell content** → Status indicators
+
+Users should always be able to:
+1. Scan rows to see what artifacts are involved
+2. Scan columns to see which tools are affected
+3. Read cells to understand what's happening
+
+## Standard Table Format
+
+All commands that display artifact information should use this columnar format:
+
+```
+  kind         artifact         claude-code  cursor  opencode  codex  pi
+  ───────────  ───────────────  ───────────  ──────  ────────  ─────  ──
+  instruction  AGENTS           ✓            ✓       ✓         ✓      ✓
+  skill        managing-memory  ✓            ✓       ✓         ✓      ✓
+  extension    tmux-fork.ts     —            —       —         —      ✓
+```
+
+### Column Order
+1. `kind` — artifact kind (instruction, rule, skill, extension, etc.)
+2. `artifact` — display name (not full path)
+3. Additional context columns (tokens, mode, action) — optional, command-specific
+4. Tool columns — one per tool, in canonical order: `claude-code`, `cursor`, `opencode`, `codex`, `pi`
+5. Status column — optional, for overall row status
+
+### Column Widths
+- `kind`: dynamic, min 4 chars
+- `artifact`: dynamic, max 35 chars (truncate with leading `…`)
+- Tool columns: width of tool name, min 2 chars
+- Token columns: 7 chars, right-aligned
+
+## Status Indicators
+
+Use these symbols consistently across all commands:
+
+| Symbol | Color  | Meaning                    | Used In              |
+|--------|--------|----------------------------|----------------------|
+| `✓`    | green  | in-sync, ok, applicable    | status, info         |
+| `+`    | green  | added, created             | activate, sync, diff |
+| `~`    | yellow | modified, updated          | activate, sync, diff |
+| `-`    | red    | removed, deleted           | activate, sync, diff |
+| `!`    | red    | missing, error             | status               |
+| `?`    | yellow | shadowed (blocked)         | status, activate     |
+| `⚡`    | yellow | unlinked (symlink broken)  | status               |
+| `💀`    | red    | broken (unrecoverable)     | status               |
+| `—`    | dim    | not applicable             | info, status         |
+| `▸`    | green  | active loadout             | list, info           |
+| `•`    | dim    | global scope               | info                 |
+| `◦`    | cyan   | local/project scope        | info                 |
+| `→`    | yellow | external source            | info                 |
+
+**Cell semantics:** Use `—` for not-applicable tool cells (never leave cells blank).
+
+### In Table Cells
+- Symbols are left-aligned in their column
+- Pad with spaces to maintain column width
+- Use chalk colors for terminal output
+
+## Command-Specific Formats
+
+### `info` — Show loadout information
+
+Displays a unified table of all active loadouts with artifacts grouped by loadout.
+Scope is indicated with subtle symbols after the loadout name.
+
+```
+Active loadouts
+───────────────
+  loadout    kind         artifact         upfront     lazy  claude-code  cursor  ...
+  ─────────  ───────────  ───────────────  ───────  ───────  ───────────  ──────  ...
+  ▸ base •   instruction  AGENTS.base.md       968        —  ✓            ✓       ...
+             skill        managing-memory       94     1.4k  ✓            ✓       ...
+             extension    tmux-fork.ts           —        —                       ...
+  ▸ base ◦   instruction  AGENTS.base.md       641        —  ✓            ✓       ...
+
+  Upfront: 1.7k • Lazy: 1.4k • Total: 3.1k tokens
+  • global  ◦ local  →name source
+```
+
+Scope indicators:
+- `•` (dim) — global scope
+- `◦` (cyan) — local/project scope  
+- `→name` (yellow) — external source (shows source name)
+
+The `▸` marker (green) indicates active loadouts.
+Loadout name only appears on the first row of each group.
+Token columns appear when any artifact has context tokens.
+
+### `status` — Show drift status
+
+Unified table matching `info`, with an additional status column showing drift.
+
+```
+Loadout status
+──────────────
+  loadout    kind         artifact         claude-code  cursor  ...  status
+  ─────────  ───────────  ───────────────  ───────────  ──────  ...  ────────
+  ▸ base ◦   instruction  AGENTS.base.md   ✓            ✓       ...  ok
+  ▸ base •   instruction  AGENTS.base.md   ✓            ✓       ...  ok
+             skill        managing-memory  ✓            ✓       ...  ok
+             extension    tmux-fork.ts                          ...  ok
+
+  • global  ◦ local
+
+✓ All in sync
+```
+
+Status column shows the worst drift status across all tools for that artifact.
+Drift indicators (worst to best): `💀` broken > `!` missing > `⚡` unlinked > `~` modified > `✓` ok.
+
+### `activate` / `sync` / `deactivate` — Apply changes
+```
+Activated loadouts: base (global)
+─────────────────────────────────
+  kind         artifact         claude-code  cursor  opencode  codex  pi
+  ───────────  ───────────────  ───────────  ──────  ────────  ─────  ──
+  instruction  AGENTS           +            +       +         +      +
+  skill        managing-memory  +            +       +         +      +
+
+✓ 8 changes: 5 added, 2 updated, 1 removed
+```
+
+### `activate --dry-run` — Preview changes
+```
+Would apply loadouts: base (global)
+───────────────────────────────────
+  kind         artifact         claude-code  cursor  opencode  codex  pi
+  ───────────  ───────────────  ───────────  ──────  ────────  ─────  ──
+  instruction  AGENTS           generate     sym     sym       sym    sym
+  skill        managing-memory  sym          sym     sym       sym    sym
+
+  8 outputs to 5 tools
+```
+
+Mode abbreviations: `sym` = symlink, `generate` = generate, `copy` = copy
+
+### `diff` — Show pending changes
+```
+Diff: base (global)
+───────────────────
+  kind         artifact         claude-code  cursor  opencode  codex  pi  action
+  ───────────  ───────────────  ───────────  ──────  ────────  ─────  ──  ──────
+  instruction  AGENTS           +            +       +         +      +   create
+  skill        managing-memory  ~            ~       ~         ~      ~   update
+  rule         old-rule         -            -       -         -      -   delete
+```
+
+### `list` — List available loadouts
+
+Shows all available loadouts with scope indicators matching `info`.
+
+```
+Available loadouts
+──────────────────
+  loadout           items  description
+  ────────────────  ─────  ──────────────────────────────
+  ▸ base       * ◦      1  Base loadout configuration
+  ▸ base         •      3  Global base configuration
+    meta         •     11  Meta loadout configuration
+
+  ▸ active  * default
+  • global  ◦ local  →name source
+```
+
+Loadout column format: `▸ name * scope` where:
+- `▸` (green) — active loadout
+- `*` (cyan) — default loadout (project scope only)
+- Scope indicators match `info` (• global, ◦ local, →name source)
+
+## Headings and Separators
+
+### Section Headings
+```typescript
+heading("Global loadout: base");
+// Output:
+// 
+// Global loadout: base
+// ────────────────────
+```
+
+- Blank line before heading
+- Title in bold
+- Separator line matches title length (dim)
+
+### Key-Value Metadata
+```typescript
+keyValue({
+  Description: "My loadout",
+  Root: "/path/to/root",
+});
+// Output:
+//   Description: My loadout
+//   Root: /path/to/root
+```
+
+- 2-space indent
+- Key in dim, followed by colon and space
+- Value in normal color
+
+## Log Messages
+
+Use the standard log helpers:
+
+```typescript
+log.success("8 changes applied");     // ✓ 8 changes applied (green)
+log.info("Checking prerequisites");   // ℹ Checking prerequisites (blue)
+log.warn("3 files shadowed");         // ⚠ 3 files shadowed (yellow)
+log.error("Failed to resolve");       // ✗ Failed to resolve (red)
+log.dim("Run 'loadouts sync' to fix"); // (dimmed text)
+```
+
+## Implementation
+
+### Shared Utilities (`src/lib/artifact-table.ts`)
+
+- `getArtifactName()` — extract display name from path
+- `sortArtifacts()` — sort by kind priority, then name
+- `truncatePath()` — truncate with leading ellipsis
+- `getToolColumns()` — calculate tool column specs
+- `calculateColumnWidths()` — dynamic column sizing
+- `renderArtifactTable()` — base table renderer
+
+### Output Helpers (`src/lib/output.ts`)
+
+- `heading()` — section heading with separator
+- `keyValue()` — key-value pair list
+- `list()` — bulleted list
+- `log.*` — status messages
+
+## Adding New Commands
+
+When adding a new command that displays artifact information:
+
+1. Use the artifact table format with tools as columns
+2. Use standard status indicators
+3. Follow the heading/separator patterns
+4. Use `log.*` for status messages
+5. Add any new columns between artifact and tool columns
+
+When in doubt, look at `info` and `status` as reference implementations.

package/docs/workflows.md

@@ -0,0 +1,184 @@
+# Workflows
+
+## Git Integration
+
+### What Gets Committed
+
+Loadout auto-manages `.gitignore` to exclude only rendered outputs:
+
+```gitignore
+# <loadouts>
+# Auto-generated by loadouts. Do not edit this section.
+.loadouts/.state.json
+.cursor/rules/coding-style.mdc
+.claude/rules/coding-style.md
+# </loadouts>
+```
+
+**Committed:** `.loadouts/` (source), `AGENTS.md` (canonical), `.gitignore`
+**Local only:** Rendered outputs, state file
+
+### Custom Tool Configs
+
+Because loadouts ignores specific paths (not whole directories), you can have custom configs alongside managed ones:
+
+```
+.cursor/
+├── rules/
+│   ├── coding-style.mdc    # Managed by loadouts (ignored)
+│   └── my-custom.mdc       # Your custom rule (committed)
+└── mcp.json                # Tool settings (committed)
+```
+
+---
+
+## Team Onboarding
+
+After cloning a repo with loadouts, team members need to render outputs once. Choose one approach:
+
+### Option 1: Git Hooks (Recommended)
+
+Run once after cloning:
+```bash
+git config core.hooksPath .loadouts/hooks
+```
+
+This auto-syncs on `git checkout` and `git pull`.
+
+**Caveats:**
+- Must run from git root (not subprojects)
+- Replaces any existing `core.hooksPath` setting
+- To undo: `git config --unset core.hooksPath`
+
+**For JS projects**, automate in `package.json`:
+```json
+{
+  "scripts": {
+    "prepare": "git config core.hooksPath .loadouts/hooks 2>/dev/null || true"
+  }
+}
+```
+
+### Option 2: Direnv
+
+If using [direnv](https://direnv.net/):
+```bash
+direnv allow
+```
+
+Auto-syncs when entering the directory. Good for teams already using direnv.
+
+### Option 3: Manual Sync
+
+For users without loadouts installed or preferring manual control:
+```bash
+loadouts sync
+```
+
+Hooks skip gracefully if loadouts isn't installed, so CI and teammates without loadouts won't error.
+
+---
+
+## Monorepo Setup
+
+Put shared config at repo root, package-specific in each package:
+
+```
+~/code/monorepo/
+├── .loadouts/                       # Repo-level
+│   ├── loadouts/base.yaml          # Shared base
+│   ├── rules/shared-style.md
+│   └── skills/debugging/
+├── packages/
+│   └── api/
+│       ├── .loadouts/
+│       │   ├── loadouts.yaml       # sources: [../..]
+│       │   └── loadouts/api.yaml   # extends: base
+│       └── src/
+```
+
+In `packages/api/.loadouts/loadouts.yaml`:
+```yaml
+version: "1"
+sources:
+  - ../..                           # Points to monorepo root
+```
+
+Now `api` loadout can `extends: base` from the parent.
+
+---
+
+## CI/CD
+
+Most CI pipelines don't need loadouts — AI tools typically aren't used in CI.
+
+**When to use loadouts in CI:**
+- Automated AI code review workflows
+- Validating loadouts configuration on PRs
+
+**Example CI step:**
+```bash
+npm install -g loadouts
+loadouts check -v          # Validate config (catches broken references)
+loadouts sync --dry-run    # Preview what would be rendered
+```
+
+If your CI step actually needs the rendered outputs:
+```bash
+loadouts sync              # Render outputs
+```
+
+---
+
+## Common Workflows
+
+### Daily Context Switching
+```bash
+loadouts activate base backend     # Morning: backend work
+loadouts activate base frontend    # Afternoon: switch to frontend
+loadouts deactivate frontend       # Remove frontend, keep base
+```
+
+### After Editing Rules/Skills
+```bash
+# Edit the source file
+$EDITOR .loadouts/rules/my-rule.md
+
+# Re-render to all tools
+loadouts sync
+
+# Verify the change
+loadouts status
+```
+
+### Check for Drift
+```bash
+loadouts status      # See what changed
+loadouts sync        # Reconcile
+```
+
+### Adding Global Personal Config
+```bash
+loadouts init -g
+loadouts rule add -g my-style
+loadouts activate base -g
+```
+
+---
+
+## Shadowed Files
+
+A **shadowed file** is when loadouts wants to write to a path that already has an unmanaged file.
+
+Loadout **never overwrites** unmanaged files. It skips and reports in `loadouts status`.
+
+**To resolve:**
+```bash
+# Import the existing file
+loadouts rule import .cursor/rules/existing.mdc
+
+# Or remove it manually
+rm .cursor/rules/existing.mdc && loadouts sync
+
+# Or keep it (it takes precedence)
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "loadouts",
+  "version": "0.1.11",
+  "description": "Composable configuration bundles for AI coding agents",
+  "type": "module",
+  "bin": {
+    "loadouts": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "bundled"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "loadouts": "node dist/index.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "cli",
+    "configuration",
+    "claude",
+    "cursor",
+    "opencode",
+    "codex"
+  ],
+  "author": "Evatt",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evatths/loadouts.git"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@types/update-notifier": "^6.0.8",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "update-notifier": "^7.3.1",
+    "yaml": "^2.4.0",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}