chore: merge main into release/0.6.0

.claude/skills/release-docs/SKILL.md

@@ -261,11 +261,35 @@ cat > docs/releases/<YYYY-MM-DD>-release-<X-Y-Z>.md << 'EOF'
 EOF
 ```
 
-Commit:
+---
+
+## Step 6 — Snapshot and prune Docusaurus versions (coding agent)
+
+After writing the blog post, snapshot the current `docs/` tree as the new version
+and prune old snapshots to stay within the retention policy.
+
+**Retention policy**:
+- Latest **5** releases from the current minor series (e.g. `0.4.7`–`0.4.11`)
+- Highest release from **each previous minor series** (e.g. `0.3.11`, `0.2.x`)
+
+Run from repo root:
+
+```bash
+NEW_VERSION=<to> node docs/scripts/snapshot-and-prune-versions.js
+```
+
+This script:
+1. Runs `docusaurus docs:version <to>` — snapshots `docs/` into `versioned_docs/version-<to>/`
+2. Prunes `versioned_docs/`, `versioned_sidebars/`, and `versions.json` to the retention policy
+3. Updates `docs/versions-config.json` — sets `lastVersion`, marks `<to>` as `(Latest)`, removes pruned entries
+
+Commit all release artifacts together:
 
 ```bash
 git add docs/releases/<YYYY-MM-DD>-release-<X-Y-Z>.md
-git commit -s -m "docs: release notes + upgrade guide for <from> → <to>"
+git add docs/versioned_docs/ docs/versioned_sidebars/
+git add docs/versions.json docs/versions-config.json
+git commit -s -m "docs: release <to> — blog post, docs snapshot, version prune"
 ```
 
 ---

.claude/skills/speckit.specify/SKILL.md

@@ -44,22 +44,31 @@ Given that feature description, do this:
      - "Create a dashboard for analytics" → "analytics-dashboard"
      - "Fix payment processing timeout bug" → "fix-payment-timeout"
 
-2. **Create the feature branch** by running the script with `--short-name` (and `--json`). The script uses today's date (`YYYY-MM-DD`) as the branch prefix — no numbering needed:
+2. **Confirm branch creation with the user BEFORE running the script.** The script's default behaviour is to `git checkout -b <new-branch>`, which is destructive (it changes the user's checked-out branch and leaves any uncommitted spec edits on a fresh branch the user did not consent to). Some maintainers want a new branch every time; others prefer to keep spec work on the current branch and bundle it with other in-flight changes.
 
-   - Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"`
+   - Show the user the proposed branch name (e.g. `2026-05-07-user-auth`) and ask whether to create it.
+   - **Phrasing**: `"I'll create a new branch named '<proposed-branch-name>' for this spec. Reply 'no branch' (or 'stay on current branch') if you'd rather keep spec edits on '<current-branch>'."`
+   - Default if the user does not respond / responds ambiguously: create the branch (matches today's behaviour). But if the user has *already* said something like "don't create a new branch" earlier in the session — **honour that without re-asking**.
+   - If the user declines, pass `--no-branch` to the script in the next step. The script will still create the spec folder under `docs/docs/specs/<branch-name>/` and write `spec.md`; only the `git checkout -b` is skipped.
+
+3. **Create the spec folder (and optionally the feature branch)** by running the script with `--short-name` (and `--json`). The script uses today's date (`YYYY-MM-DD`) as the spec folder / branch prefix — no numbering needed:
+
+   - Bash example (branch): `{SCRIPT} --json --short-name "user-auth" "Add user authentication"`
+   - Bash example (no branch): `{SCRIPT} --json --no-branch --short-name "user-auth" "Add user authentication"`
    - PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"`
 
    **IMPORTANT**:
    - Do NOT pass `--number` — that flag no longer exists; the prefix is always today's date
    - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
+   - Pass `--no-branch` (Bash) if step 2's user confirmation came back negative. (Bash only — PowerShell support is not yet implemented.)
    - You must only ever run this script once per feature
    - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
-   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths (e.g. `2026-05-07-user-auth`)
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths (e.g. `2026-05-07-user-auth`). When `--no-branch` was passed, `BRANCH_NAME` is the *would-be* name — the spec folder under `docs/docs/specs/` is named after it, but the user's checked-out branch is unchanged.
    - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
 
-3. Load `templates/spec-template.md` to understand required sections.
+4. Load `templates/spec-template.md` to understand required sections.
 
-4. Follow this execution flow:
+5. Follow this execution flow:
 
     1. Parse user description from Input
        If empty: ERROR "No feature description provided"
@@ -85,9 +94,9 @@ Given that feature description, do this:
     7. Identify Key Entities (if data involved)
     8. Return: SUCCESS (spec ready for planning)
 
-5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+6. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
 
-6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+7. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
 
    a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
 
@@ -179,9 +188,9 @@ Given that feature description, do this:
 
    d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
 
-7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+8. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`). If the user declined a new branch in step 2, explicitly note which branch the spec lives on (e.g. `"Spec written to docs/docs/specs/2026-05-25-foo/spec.md on branch 'main' (no new branch created, per your instruction)."`).
 
-**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+**NOTE:** Unless `--no-branch` was passed in step 3, the script creates and checks out the new branch and initializes the spec file before writing. With `--no-branch`, only the spec folder is created and the caller's current branch is preserved.
 
 ## Quick Guidelines
 

.cursor/commands/speckit.specify.md

@@ -36,22 +36,31 @@ Given that feature description, do this:
      - "Create a dashboard for analytics" → "analytics-dashboard"
      - "Fix payment processing timeout bug" → "fix-payment-timeout"
 
-2. **Create the feature branch** by running the script with `--short-name` (and `--json`). The script uses today's date (`YYYY-MM-DD`) as the branch prefix — no numbering needed:
+2. **Confirm branch creation with the user BEFORE running the script.** The script's default behaviour is to `git checkout -b <new-branch>`, which is destructive (it changes the user's checked-out branch and leaves any uncommitted spec edits on a fresh branch the user did not consent to). Some maintainers want a new branch every time; others prefer to keep spec work on the current branch and bundle it with other in-flight changes.
 
-   - Bash example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"`
+   - Show the user the proposed branch name (e.g. `2026-05-07-user-auth`) and ask whether to create it.
+   - **Phrasing**: `"I'll create a new branch named '<proposed-branch-name>' for this spec. Reply 'no branch' (or 'stay on current branch') if you'd rather keep spec edits on '<current-branch>'."`
+   - Default if the user does not respond / responds ambiguously: create the branch (matches today's behaviour). But if the user has *already* said something like "don't create a new branch" earlier in the session — **honour that without re-asking**.
+   - If the user declines, pass `--no-branch` to the script in the next step. The script will still create the spec folder under `docs/docs/specs/<branch-name>/` and write `spec.md`; only the `git checkout -b` is skipped.
+
+3. **Create the spec folder (and optionally the feature branch)** by running the script with `--short-name` (and `--json`). The script uses today's date (`YYYY-MM-DD`) as the spec folder / branch prefix — no numbering needed:
+
+   - Bash example (branch): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"`
+   - Bash example (no branch): `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --no-branch --short-name "user-auth" "Add user authentication"`
    - PowerShell example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -ShortName "user-auth" "Add user authentication"`
 
    **IMPORTANT**:
    - Do NOT pass `--number` — that flag no longer exists; the prefix is always today's date
    - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
+   - Pass `--no-branch` (Bash) if step 2's user confirmation came back negative. (Bash only — PowerShell support is not yet implemented.)
    - You must only ever run this script once per feature
    - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
-   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths (e.g. `2026-04-28-user-auth`)
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths (e.g. `2026-04-28-user-auth`). When `--no-branch` was passed, `BRANCH_NAME` is the *would-be* name — the spec folder under `docs/docs/specs/` is named after it, but the user's checked-out branch is unchanged.
    - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
 
-3. Load `.specify/templates/spec-template.md` to understand required sections.
+4. Load `.specify/templates/spec-template.md` to understand required sections.
 
-4. Follow this execution flow:
+5. Follow this execution flow:
 
     1. Parse user description from Input
        If empty: ERROR "No feature description provided"
@@ -77,9 +86,9 @@ Given that feature description, do this:
     7. Identify Key Entities (if data involved)
     8. Return: SUCCESS (spec ready for planning)
 
-5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+6. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
 
-6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+7. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
 
    a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
 
@@ -171,9 +180,9 @@ Given that feature description, do this:
 
    d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
 
-7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+8. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`). If the user declined a new branch in step 2, explicitly note which branch the spec lives on (e.g. `"Spec written to docs/docs/specs/2026-05-25-foo/spec.md on branch 'main' (no new branch created, per your instruction)."`).
 
-**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+**NOTE:** Unless `--no-branch` was passed in step 3, the script creates and checks out the new branch and initializes the spec file before writing. With `--no-branch`, only the spec folder is created and the caller's current branch is preserved.
 
 ## Quick Guidelines
 

.cursor/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/guard-git-branch-ops.sh"
+      }
+    ]
+  }
+}

.cursor/hooks/guard-git-branch-ops.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# beforeShellExecution hook: pause for confirmation on git commands that can
+# move the checked-out branch pointer, clobber uncommitted work, or rewrite
+# shared history. Read-only git and `git worktree` (the safe isolation path)
+# are allowed automatically. See .cursor/rules/safe-git-worktree.mdc.
+#
+# Fails OPEN (allows) on parse/tooling errors so it never blocks the whole
+# session; this is a safety nudge, not a hard security boundary.
+
+input=$(cat)
+
+# Extract the command; fall back to allow if jq or the field is missing.
+if ! command -v jq >/dev/null 2>&1; then
+  echo '{ "permission": "allow" }'
+  exit 0
+fi
+command=$(printf '%s' "$input" | jq -r '.command // empty' 2>/dev/null)
+
+if [ -z "$command" ]; then
+  echo '{ "permission": "allow" }'
+  exit 0
+fi
+
+# Quick out: nothing to guard if there's no git invocation.
+if ! printf '%s' "$command" | grep -Eq '(^|[^[:alnum:]])git([[:space:]]|$)'; then
+  echo '{ "permission": "allow" }'
+  exit 0
+fi
+
+ask() {
+  msg="$1"
+  agent_msg="Per .cursor/rules/safe-git-worktree.mdc, this git command can disturb the user's working tree or shared history. Confirm with the user, or do the work in an isolated worktree (git worktree add /tmp/caipe-<task> origin/main -b <branch>). Command: ${command}"
+  jq -n --arg m "$msg" --arg a "$agent_msg" \
+    '{ permission: "ask", user_message: $m, agent_message: $a }'
+  exit 0
+}
+
+# --- Branch-pointer / working-tree mutations -------------------------------
+# checkout, switch, reset, restore, stash, clean, rebase, merge
+if printf '%s' "$command" | grep -Eq '(^|[^[:alnum:]])git[[:space:]]+(checkout|switch|reset|restore|stash|clean|rebase|merge)([[:space:]]|$)'; then
+  ask "This git command can move your branch or overwrite uncommitted edits. Review before running, or isolate the work in a git worktree."
+fi
+
+# --- Destructive branch ops (delete / rename / force) ----------------------
+if printf '%s' "$command" | grep -Eq '(^|[^[:alnum:]])git[[:space:]]+branch[[:space:]]+(-[dDmM]|--delete|--move|--force|-f)([[:space:]]|$)'; then
+  ask "This deletes, renames, or force-updates a branch. Review before running."
+fi
+
+# --- Force push / push to a protected branch -------------------------------
+if printf '%s' "$command" | grep -Eq '(^|[^[:alnum:]])git[[:space:]]+push'; then
+  if printf '%s' "$command" | grep -Eq '(--force([-=]|[[:space:]]|$)|--force-with-lease|(^|[[:space:]])-f([[:space:]]|$))'; then
+    ask "This is a force-push and can rewrite remote history. Review carefully."
+  fi
+  if printf '%s' "$command" | grep -Eq '(^|[[:space:]])(origin[[:space:]]+)?(main|master)([[:space:]]|:|$)'; then
+    ask "This pushes to a protected branch (main/master). Push to a feature branch instead."
+  fi
+fi
+
+# Everything else (status, log, diff, show, fetch, worktree, add, commit,
+# normal push to a feature branch, ...) is allowed.
+echo '{ "permission": "allow" }'
+exit 0

.cursor/rules/safe-git-worktree.mdc

@@ -0,0 +1,79 @@
+---
+description: Protect the user's live working tree during branch/PR work; verify a current base, preserve uncommitted edits, and isolate risky work in a worktree
+alwaysApply: true
+---
+
+# Safe Git: Protect the User's Working Tree
+
+The user's checked-out branch and working tree are theirs. Before doing any
+branch/PR work, make sure you will not lose their edits or churn thousands of
+files. The failure that motivated this rule was switching branches across a
+**stale local `main` (37 commits behind `origin/main`)**, which rewrote ~3,800
+`docs/` files in the user's tree.
+
+## Always (universal — applies to every repo and agent)
+
+- **Never assume local `main` is current.** Run `git fetch origin <base>` and
+  branch from the *remote* ref (`origin/main`), not the local one.
+- **Preserve uncommitted work.** Run `git status` before any git command. If the
+  tree is dirty, do not switch/reset/checkout over those edits — commit, stash
+  *with the user's awareness*, or isolate in a worktree instead.
+- **Never push to a shared branch.** Push only to feature branches; never
+  `push`/`--force` to `origin/main` (or any protected branch).
+- **Never rewrite shared history** (`reset --hard`, force-push) on a branch
+  others may have pulled.
+- **Branch naming:** use the `prebuild/` prefix when the branch should trigger CI
+  Docker image builds (see `AGENTS.md`).
+
+## Prefer an isolated worktree when the work is risky or parallel
+
+Reach for a throwaway worktree when you need to *experiment*, run work *in
+parallel* with the user's current branch, or when the tree is dirty and you must
+not disturb it:
+
+```bash
+git fetch origin main
+git worktree add /tmp/caipe-<task> origin/main -b prebuild/<feat-branch>
+cd /tmp/caipe-<task>          # do edits, commits, pushes here
+# when done:
+cd -                          # user's repo, untouched
+git worktree remove /tmp/caipe-<task>
+```
+
+Worktree caveats to handle (don't assume the worktree "just works"):
+
+- **Untracked-but-essential files don't come along.** Gitignored config such as
+  `.env` is absent in a fresh worktree — copy or symlink what the task needs.
+- **Virtualenvs are not shared.** Per `CLAUDE.md`, each worktree (and each
+  subpackage: RAG ingestors/server, MCP agents) needs its own
+  `uv venv --python python3.13 --clear .venv && uv sync`.
+- `/tmp` is cleared on reboot and duplicates large caches — fine for short tasks,
+  not for long-lived state.
+
+## A plain feature branch is acceptable when the base is current and the tree is clean
+
+If `git status` is clean and your base is up to date with `origin`, branching in
+the user's repo is normal git flow and is fine:
+
+```bash
+git fetch origin main
+git switch -c prebuild/<feat-branch> origin/main
+```
+
+The point of this rule is **not** "never branch" — it is "never destroy the
+user's uncommitted work or branch from a stale base."
+
+## If you only need to *read* another branch/commit
+
+Use `git show <ref>:<path>`, `git diff <ref>`, or `git log <ref>` — these never
+touch the working tree. Switch to an edit workflow (branch or worktree) only when
+you need to build, edit, or commit.
+
+## Enforcement
+
+Prose rules are advisory. For a hard gate, this repo ships a
+`beforeShellExecution` hook (`.cursor/hooks/guard-git-branch-ops.sh`) that pauses
+for confirmation on branch/history-mutating git commands while letting read-only
+git through. See `.cursor/hooks.json`.
+
+See the `using-git-worktrees` skill for the full isolation procedure.