add

What this skill does

# QMD Add: Clone or Index a Reference Collection

ultrathink

<role>
You are a reference library curator. Your job is to add new collections to qmd: cloning external GitHub repos OR registering existing local directories, detecting their structure, setting ignore globs, indexing them for search, embedding, and verifying they're ready for retrieval. You care about file type detection, mask correctness, ignore patterns, and index health. You execute every step and verify its output before proceeding.
</role>

## Current Collections
!`qmd collection list 2>/dev/null || echo "No collections yet"`

## Arguments

- `$ARGUMENTS` first token is required and is one of:
  - **GitHub URL**: `https://github.com/owner/repo` (or `[email protected]:owner/repo.git`)
  - **Owner/repo shorthand**: `owner/repo` (e.g. `vercel/next.js`)
  - **Local directory**: any absolute path (`/path/...`), home-relative (`~/path/...`), or `.`/`./path` for cwd-relative. Detected when `test -d` succeeds OR when the token starts with `/`, `~/`, `./`, or `../`.
- `$ARGUMENTS` containing `--name`: Override collection name (must match `[a-zA-Z0-9_-]+`)
- `$ARGUMENTS` containing `--mask`: Skip auto-detection, use provided glob pattern
- `$ARGUMENTS` containing `--dest`: Override clone destination (default: `~/Developer/refs/`). **GitHub paths only**, ignored for local paths.
- `$ARGUMENTS` containing `--full`: Clone with full history (not shallow). **GitHub paths only**.
- `$ARGUMENTS` containing `--defer-embed`: Skip embedding step, run `/qmd:update` later
- `$ARGUMENTS` containing `--dry-run`: Preview only. Run Steps 1-3, print plan, exit

## Constraints

- Execute commands, not suggestions. No dry-run prose
- Stop immediately on any step failure. Do not continue with broken state
- Never delete anything. Use `trash` (if available), never `rm`
- For GitHub paths: refs directory is `--dest` if provided, otherwise `~/Developer/refs/`. Steps reference this as `REFS`. Final collection path is `$REFS/<name>`.
- For local paths: the user's directory is the collection path verbatim (after resolving `~`/`.`). `REFS` and `--dest` are not used.
- QMD config: `${XDG_CONFIG_HOME:-~/.config}/qmd/index.yml`
- If `--dry-run`: exit after Step 3. No cloning, no indexing, no embedding
- If embed fails: report error, print retry command (`qmd embed`), exit

---

## Step 1: Parse input and detect mode

Look at the first token of `$ARGUMENTS`:

1. **GitHub URL** (`https://github.com/...` or `[email protected]:...`):
   - Mode = `github`
   - Parse `<owner>/<repo>`
   - Default name = `<repo>` (override with `--name`)
   - Collection path = `$REFS/<name>`

2. **Owner/repo shorthand** (matches `^[\w.-]+/[\w.-]+$` AND is not an existing directory):
   - Mode = `github`
   - URL = `https://github.com/<owner>/<repo>`
   - Default name = `<repo>` (override with `--name`)
   - Collection path = `$REFS/<name>`

3. **Local directory** (token starts with `/`, `~/`, `./`, `../`, OR `test -d <token>` succeeds):
   - Mode = `local`
   - Resolve the path: `realpath <token>` (or shell expansion for `~`)
   - Verify the directory exists. If not, STOP: "Local path does not exist: <path>".
   - Default name = the basename of the resolved path, lowercased and `handelize`'d (`[a-zA-Z0-9_-]+`)
   - Collection path = the resolved local path verbatim
   - **Ignore** `--dest` and `--full` if provided (warn the user they don't apply to local mode)

`--name`, `--mask`, `--defer-embed`, `--dry-run` apply in both modes.

Print the parsed mode + name + final collection path before proceeding so the user can confirm.

## Step 2: Clone, pull, or skip

**If mode = `github`:**

```bash
mkdir -p $REFS
```

If `$REFS/<name>` already exists, refresh it to the remote tip. A shallow fetch + reset keeps the read-only mirror shallow and never hits a fast-forward failure:
```bash
git -C $REFS/<name> fetch --depth 1 origin HEAD && git -C $REFS/<name> reset --hard FETCH_HEAD
```

Otherwise, shallow clone (default):
```bash
git clone --depth 1 https://github.com/<owner>/<repo> $REFS/<name>
```

If `--full`: omit `--depth 1`.

**If mode = `local`:**

Skip cloning entirely. The directory already exists (verified in Step 1). Move directly to Step 3.

If the local directory is a git repo, that's fine — Step 5 still sets a `git pull --ff-only` update command so `/qmd:update` will refresh it. If it's not a git repo (e.g., `~/Documents/notes`), Step 5 should leave the update command empty so `/qmd:update` just re-indexes without trying to pull.

## Step 3: Detect mask

If `--mask` provided, use it and skip to Step 4.

Detect from the repo root:

```
detected = []

if package.json exists OR any .ts/.tsx files:
    detected += "typescript"
if Cargo.toml exists OR any .rs files:
    detected += "rust"
if go.mod exists OR any .go files:
    detected += "go"
if pyproject.toml exists OR any .py files:
    detected += "python"
if Package.swift exists OR any .swift files:
    detected += "swift"

if len(detected) == 0:
    STOP → "Could not detect project type. Re-run with --mask '<glob>'."
if len(detected) > 1:
    WARN → "Multiple types detected: {detected}. Merging masks."
    mask = union of all matched type extensions
if len(detected) == 1:
    mask = extensions for the single matched type
```

Extension table (for building `**/*.{...}` mask):

| Type | Extensions |
|------|------------|
| typescript | `md,mdx,txt,ts,tsx,js,jsx,json,yaml,yml,css` |
| rust | `md,txt,rs,toml,yaml,yml` |
| go | `md,txt,go,mod,yaml,yml` |
| python | `md,txt,py,toml,yaml,yml,cfg` |
| swift | `md,txt,swift,yaml,yml` |

Print detected type(s) and final mask before proceeding.

### Dry-run gate

If `--dry-run`: print the execution plan (the commands Steps 4-8 would run) and exit. Do not clone, add collections, edit config, or embed.

## Step 4: Add collection

Use the resolved collection path from Step 1 (called `<path>` here — `$REFS/<name>` for github mode, the user's directory for local mode):

```bash
qmd collection add <path> --name <name> --mask "<mask>"
```

If collection already exists (command errors), remove first then re-add:
```bash
qmd collection remove <name>
qmd collection add <path> --name <name> --mask "<mask>"
```

## Step 5: Set auto-pull (github mode) and ignore patterns

**If mode = `github`:** configure the pre-update command. Use a shallow fetch + reset so the read-only mirror stays shallow and never hits a fast-forward failure:

```bash
qmd collection update-cmd <name> "git -C $REFS/<name> fetch --depth 1 origin HEAD && git -C $REFS/<name> reset --hard FETCH_HEAD"
```

**If mode = `local`:** check whether the directory is a git repo:

```bash
test -d <path>/.git && echo "git" || echo "not-git"
```

- If it's a git repo, set a non-destructive pull (never `reset --hard` a directory the user might be editing): `qmd collection update-cmd <name> "git -C <path> pull --ff-only"`. If it can't fast-forward, `/qmd:update` surfaces the error and the user resolves it, which is safer than discarding their work.
- If it's not a git repo (e.g. notes folder), leave the update command unset. `/qmd:update` will still re-index it on each run (file mtime detection picks up changes).

Then write `ignore:` globs into the YAML for the collection. The CLI has no subcommand to set ignore patterns — edit `${XDG_CONFIG_HOME:-~/.config}/qmd/index.yml` directly:

```yaml
collections:
  <name>:
    # ... existing fields ...
    ignore:
      - "out/**"
      - "target/**"
      - "Pods/**"
      - "**/*.test.*"
      - "**/*.spec.*"
      - "**/__tests__/**"
      - "**/__snapshots__/**"
      - "**/fixtures/**"
```

**What qmd already excludes by default (do NOT add these):**

qmd hardcodes a builtin exclude list of `node_modules`, `.git`, `.cache`, `vendor`, `dist`, `build` (verified in `src/cli/qmd.ts:1504` and `src/store.ts:1183`) AND filters out every path that contains a component starting with `.` (the dotfile filter at `src/cli/qmd.ts:1529`). So all of these are already excluded automati