v0.2 — Polish Pass, Guidance, and Symlink Install

src/
├── index.ts      # CLI entry point
├── processor.ts  # unified pipeline
...

#### Step 4: Polish pass — Upgrade box-based ASCII to Mermaid

After synthesis, scan the trace for ASCII diagrams that would benefit from Mermaid rendering.

**What to upgrade:**
- Box-based ASCII diagrams (Claude often misaligns right edges of boxes)
- Flowcharts drawn with `+---+` or `|   |` characters
- Architecture diagrams with multiple connected components
- Entity relationships and data models

**What to leave alone:**
- **Lifecycle/state diagrams** — ASCII is more readable in terminal for these
- Directory trees (`├── src/`, `└── lib/`) — standard and well-aligned
- Simple inline arrows (`A → B → C`)
- Markdown tables
- Simple linear flows that don't need visual polish

**Guidance (optional):**
After a `-` separator, capture freeform guidance that influences exploration and synthesis:
- `/trace auth - focus on the new OAuth flow`
- `/trace --update - add mermaid diagrams for the data flow`
- `/trace api - I just pulled changes, note breaking changes in v2`

The guidance gets passed to explore agents and the polish pass.

argument-hint: [name] [--update] [--list] [- guidance]

**Format guidance**:
- **Lead with understanding, follow with reference** — Mental Model and Lifecycle sections go FIRST to contextualize, then architecture/schemas/files as reference material
...
- **Mental Model** (REQUIRED for subsystem traces — how should someone think about this?)
  - Analogies to familiar concepts (e.g., "Templates are like Docker images")
  - Why it exists / the problem it solves
  - Key abstractions and their relationships
- **Lifecycle** (REQUIRED for stateful systems)
  - State diagram or flowchart showing creation → use → destruction
  - What triggers state transitions
  - Timing/billing/persistence characteristics

**What to leave alone:**
- **Lifecycle/state diagrams** — ASCII is more readable in terminal for these

link_command() {
    local src="$SCRIPT_DIR/$1"
    local dest="$COMMANDS_DIR/$1"

    if [ -L "$dest" ]; then
        # Already a symlink - check if it points to us
        current_target=$(readlink "$dest")
        if [ "$current_target" = "$src" ]; then
            echo "  - /$1 (already linked)"
            return
        else
            echo "  - /$1: symlink points elsewhere ($current_target)"
            echo "    Run: ln -sf \"$src\" \"$dest\" to update"
            return
        fi
    elif [ -f "$dest" ]; then
        # Regular file exists - check for differences
        if diff -q "$src" "$dest" > /dev/null 2>&1; then
            # Same content, safe to replace with symlink
            rm "$dest"
            ln -s "$src" "$dest"
            echo "  - /$1 (converted to symlink)"
        else
            echo "  - /$1: DIFFERS from source!"
            echo "    Installed version has changes. Diff:"
            diff "$src" "$dest" | head -20
            echo "    ..."
            echo "    To overwrite: ln -sf \"$src\" \"$dest\""
            return
        fi
    else
        # No file exists, create symlink
        ln -s "$src" "$dest"
        echo "  - /$1 (linked)"
    fi
}

## Trace-First Context Loading [RECOMMENDED]

When diving into a feature or module, check for existing traces first:
1. Look for `.traces/` directory
2. If trace exists for the area (`auth.md`, `api.md`, etc.) → load it
3. If no relevant trace → suggest creating one: "Want to `/trace auth` first? Captures the module for future sessions too."

**Why trace first:**
- Instant context vs. exploratory searching
- Shared understanding (traces are git-committed)
- Creates reusable snapshot for future sessions

ls -la ~/.claude/commands/trace.md
lrwxr-xr-x@ 1 joel  staff  42 Jan  6 15:37 /Users/joel/.claude/commands/trace.md -> /Users/joel/Code/cc-trace-command/trace.md