@jeiemgi/cckit 0.1.6

package/bin/cckit

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# cckit — the CLI dispatcher. A thin bash front-end over the git-mechanics bundle (scripts/lib).
+# Agent-agnostic: every verb runs from a shell; append --llm for machine-readable output.
+# Driven entirely from cckit.config.json — no org/repo is hardcoded. See AGENTS.md.
+#
+# Usage:
+#   cckit                           resume: print the last session's resume-here handoff
+#   cckit handoff "<note>"          save a resume-here note for the next session
+#   cckit install [bin-dir]         symlink cckit onto your PATH (global install)
+#   cckit init --profile <p>        scaffold cckit.config.json + .claude/ (--profile required)
+#   cckit start <issue> [slug]      isolated worktree + branch for an issue
+#   cckit pr <issue> <summary>      commit + push + open the PR
+#   cckit close <issue> <summary>   close issue + mark done
+#   cckit contribute "<summary>"    open a contribution PR to cckit, gated on scripts/check.sh
+#   cckit sync [--llm]              board state / what's unblocked
+#   cckit effort <new|start|pr|close|plan>   the effort lifecycle
+#   cckit orchestrate <a> <b> …     run N flows in parallel worktrees (--dry-run/--cap/--agent)
+#   cckit autopilot [<a> …]         unattended multi-flow: drive (or auto-pick) issues under a cap
+#   cckit gc [--prune [--yes]]      report (default) or prune merged branches + worktrees
+#   cckit status                    thin dashboard: board + worktrees + resume handoff
+#   cckit scan [--llm]              detect this repo's stack + kit state (JSON)
+#   cckit debug [--check] <args>    optional browser-debug via chrome-devtools-axi (auto-detected)
+#   cckit encode-context            stdin JSON -> compact TOON (uniform arrays; JSON fallback)
+#   cckit doctor                    onboarding preflight (deps, gh auth)
+#   cckit update                    check whether this project is behind the installed cckit
+#   cckit migrate                   reshuffle an old kit layout to the current one
+#   cckit adopt                     record kit-shaped files a repo already has into the manifest
+#   cckit digest <path|url>         summarize a file or URL (local model)
+#   cckit release <ver> [--publish] cut a release (dry-run by default)
+#   cckit version [--llm]           the installed cckit version
+#   cckit commands [--llm]          list every verb (the command catalog)
+#   cckit completions [bash|zsh]    print a shell-completion script to source
+#   cckit help
+set -eu
+
+# Resolve this script through symlinks — Homebrew and scripts/install.sh link bin/cckit onto
+# PATH, so $0 may be a symlink; follow it to find the real repo root (where scripts/lib lives).
+SOURCE="${BASH_SOURCE[0]:-$0}"
+while [ -h "$SOURCE" ]; do
+  _dir="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  case "$SOURCE" in /*) ;; *) SOURCE="$_dir/$SOURCE" ;; esac
+done
+BIN="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ROOT="$(cd "$BIN/.." && pwd)"
+LIB="$ROOT/scripts/lib"
+
+# Resolve the PROJECT config from the directory cckit was invoked in (walk upward for
+# cckit.config.json, or .claude/kit.config.json), so board/lifecycle verbs act on the project you
+# ran cckit in — NOT cckit's own install dir. Running inside the cckit repo resolves to its own
+# cckit.config.json naturally (self-hosting); outside any project we fall back to cckit's config.
+# An explicit KIT_CONFIG in the environment always wins.
+_cckit_find_config() {
+  local d="$1"
+  while [ -n "$d" ] && [ "$d" != "/" ]; do
+    [ -f "$d/cckit.config.json" ]       && { printf '%s\n' "$d/cckit.config.json";       return 0; }
+    [ -f "$d/.claude/kit.config.json" ] && { printf '%s\n' "$d/.claude/kit.config.json"; return 0; }
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+if [ -z "${KIT_CONFIG:-}" ]; then
+  KIT_CONFIG="$(_cckit_find_config "$PWD" || true)"
+  [ -n "$KIT_CONFIG" ] || KIT_CONFIG="$ROOT/cckit.config.json"
+fi
+export KIT_CONFIG
+# No `cd "$ROOT"`: cckit's own files are referenced via absolute $ROOT/$LIB/$BIN paths, while
+# project verbs (sync/start/pr/close/gc/scan/status/effort/…) must run in the invoking directory.
+# Verbs that act on cckit itself (release, contribute) cd into $ROOT locally below.
+
+# Structured-output helpers (cckit_is_json / cckit_json) — wired into every verb below.
+# shellcheck source=/dev/null
+source "$LIB/cckit-output.sh"
+# Terminal ergonomics (color/tty gating, optional glow/fzf) — detect-or-fallback, never required.
+# shellcheck source=/dev/null
+source "$LIB/ui.sh"
+
+usage() { sed -n '/^# Usage:/,/^[^#]/p' "$BIN/cckit" | sed '1d;$d;s/^# \{0,1\}//'; }
+
+# --llm flag → structured output (parsed by agents). Strip it from positional args, export a flag.
+CCKIT_OUTPUT="human"
+args=()
+for a in "$@"; do
+  case "$a" in
+    --llm|--output=json) CCKIT_OUTPUT="json" ;;
+    *) args+=("$a") ;;
+  esac
+done
+set -- "${args[@]+"${args[@]}"}"
+export CCKIT_OUTPUT
+
+# Bare `cckit` (no verb) resumes the last session's handoff (locked behavior).
+cmd="${1:-resume}"; shift || true
+
+case "$cmd" in
+  version)
+    # The installed cckit version is cckit's OWN config, independent of the project we're invoked in.
+    v="$(jq -r '.kitVersion // "0.0.0"' "$ROOT/cckit.config.json" 2>/dev/null || echo 0.0.0)"
+    if cckit_is_json; then cckit_json version "$v"; else echo "cckit $(ui_paint '1;36' "$v")"; fi
+    ;;
+  effort)
+    # shellcheck source=/dev/null
+    source "$LIB/effort.sh"
+    # shellcheck source=/dev/null
+    source "$LIB/effort-ops.sh"   # the new|start|pr|close lifecycle ops (compose effort.sh helpers)
+    sub="${1:-}"; shift || true
+    case "$sub" in
+      new)   effort_new   "$@" ;;
+      start) effort_start "$@" ;;
+      pr)    effort_pr    "$@" ;;
+      close) effort_close "$@" ;;
+      plan)  source "$LIB/effort-plan.sh"; effort_plan "$@" ;;
+      *) echo "cckit effort <new|start|pr|close|plan>" >&2; exit 2 ;;
+    esac
+    ;;
+  start)
+    # Isolated worktree + branch for an issue (wt_start drives off cckit.config.json: repo + base
+    # branch). Config must be loaded so KIT_REPO / KIT_BASE_BRANCH are set before wt_start runs.
+    # shellcheck source=/dev/null
+    source "$LIB/kit-config.sh" && load_kit_config
+    # shellcheck source=/dev/null
+    source "$LIB/role-identity.sh"; source "$LIB/worktree-start.sh"
+    if cckit_is_json; then
+      out="$(wt_start "$@" 2>&1)"; rc=$?
+      cckit_json verb start issue "${1:-}" ok "$([ "$rc" -eq 0 ] && echo true || echo false)" \
+        detail "$(printf '%s' "$out" | tail -1)"
+      exit "$rc"
+    fi
+    wt_start "$@"
+    ;;
+  pr|close)
+    # shellcheck source=/dev/null
+    source "$LIB/kit-config.sh" && load_kit_config
+    # shellcheck source=/dev/null
+    source "$LIB/role-identity.sh"; source "$LIB/gh-project.sh"; source "$LIB/kit-task-ops.sh"
+    if cckit_is_json; then
+      case "$cmd" in
+        pr)    out="$(kto_task_pr    "$@" 2>&1)"; rc=$? ;;
+        close) out="$(kto_task_close "$@" 2>&1)"; rc=$? ;;
+      esac
+      url="$(printf '%s' "$out" | grep -oE 'https://[^ ]+/pull/[0-9]+' | tail -1)"
+      cckit_json verb "$cmd" issue "${1:-}" ok "$([ "$rc" -eq 0 ] && echo true || echo false)" \
+        url "$url" detail "$(printf '%s' "$out" | tail -1)"
+      exit "$rc"
+    fi
+    case "$cmd" in
+      pr)    kto_task_pr    "$@" ;;
+      close) kto_task_close "$@" ;;
+    esac
+    ;;
+  sync)        exec "$ROOT/scripts/task-sync.sh" "$@" ;;
+  gc)
+    # shellcheck source=/dev/null
+    source "$LIB/kit-config.sh" && load_kit_config
+    # shellcheck source=/dev/null
+    source "$LIB/kit-gc.sh"
+    case " $* " in
+      *" --prune "*|*" prune "*)
+        # Remove worktrees + local branches whose PR merged. Dry-run unless --yes.
+        kit_gc_prune "$@"
+        ;;
+      *)
+        if cckit_is_json; then
+          out="$(kit_gc_analyze 2>/dev/null || true)"
+          safe="$(printf '%s\n' "$out" | grep -c '> SAFE ' || true)"
+          protected="$(printf '%s\n' "$out" | grep -c 'PROTECTED:' || true)"
+          orphan="$(printf '%s\n' "$out" | grep -c 'ORPHAN' || true)"
+          cckit_json verb gc safe "$safe" protected "$protected" orphan "$orphan"
+        else
+          kit_gc_analyze "$@"
+        fi
+        ;;
+    esac
+    ;;
+  orchestrate) exec "$ROOT/scripts/orchestrate.sh" "$@" ;;
+  autopilot)   exec "$ROOT/scripts/autopilot.sh" "$@" ;;
+  # Ops exposed so an agent/autopilot can run the whole lifecycle through the one CLI (#16).
+  release)
+    # Acts on cckit's own repo, so run from the install root regardless of where it was invoked.
+    cd "$ROOT"
+    # `--next` reports the version the conventional commits imply; otherwise cut a release.
+    case "${1:-}" in
+      --next) exec "$ROOT/scripts/lib/version-bump.sh" --next ;;
+      *)      exec "$ROOT/scripts/publish.sh" "$@" ;;
+    esac
+    ;;
+  update)      exec "$ROOT/scripts/kit-version-check.sh" "$@" ;;
+  migrate)     exec "$ROOT/scripts/kit-migrate.sh" "$@" ;;
+  adopt)       exec "$ROOT/scripts/kit-adopt.sh" "$@" ;;
+  doctor)      exec "$ROOT/scripts/kit-doctor.sh" "$@" ;;
+  digest)      exec "$ROOT/scripts/kit-digest.sh" "$@" ;;
+  scan)        source "$LIB/project-scan.sh"; project_scan "$@" ;;
+  encode-context) source "$LIB/toon.sh"; toon_encode ;;
+  debug)       exec "$ROOT/scripts/debug.sh" "$@" ;;
+  contribute)  cd "$ROOT"; exec "$ROOT/scripts/contribute.sh" "$@" ;;
+  status|ui)   exec "$ROOT/scripts/status.sh" "$@" ;;
+  resume)      source "$LIB/handoff.sh"; handoff_read ;;
+  handoff)     source "$LIB/handoff.sh"; handoff_write "$@" ;;
+  install)     exec "$ROOT/scripts/install.sh" "$@" ;;
+  init)        exec "$ROOT/scripts/init.sh" "$@" ;;
+  commands)
+    # The command catalog - verbs parsed from this dispatcher's own case labels (single source).
+    verbs="$(grep -oE '^  [a-z][a-z|-]*\)' "$BIN/cckit" | sed 's/[) ]//g' | tr '|' '\n' | grep -vE '^(-|$)' | sort -u)"
+    if cckit_is_json; then printf '%s\n' "$verbs" | jq -R . | jq -cs .; else printf '%s\n' "$verbs" | tr '\n' ' '; echo; fi
+    ;;
+  completions)
+    case "${1:-bash}" in
+      bash) cat "$ROOT/completions/cckit.bash" ;;
+      zsh)  echo "autoload -Uz bashcompinit && bashcompinit"; cat "$ROOT/completions/cckit.bash" ;;
+      *)    echo "cckit completions [bash|zsh]" >&2; exit 2 ;;
+    esac
+    ;;
+  help|--help|-h) usage ;;
+  *) echo "cckit: unknown command '$cmd' — run 'cckit help'" >&2; exit 2 ;;
+esac

package/cckit.config.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "./kit.config.schema.json",
+  "kitVersion": "0.1.6",
+  "project": {
+    "name": "cckit",
+    "slug": "cckit",
+    "owner": "jeiemgi",
+    "language": "en"
+  },
+  "profile": "software",
+  "skillPrefix": "",
+  "github": {
+    "repo": "jeiemgi/cckit",
+    "owner": "jeiemgi",
+    "baseBranch": "main",
+    "projectsV2": false,
+    "projectNumber": null,
+    "projectTitle": null
+  },
+  "plans": {
+    "format": "github",
+    "dir": ""
+  },
+  "knowledge": {
+    "dir": "docs-site/src/content/docs"
+  },
+  "memory": {
+    "enabled": false,
+    "wing": "cckit"
+  },
+  "engine": {
+    "mode": "off"
+  }
+}

package/commands/kit-add.md

@@ -0,0 +1,42 @@
+---
+description: Stack a kit MODULE onto this project (e.g. `kit add software`) — turns a free workspace into a GitHub-managed island via a short wizard, without restructuring anything above it.
+argument-hint: "<module>   (e.g. software)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# /kit-add — stack a module onto this project
+
+Modules are **apilables** (D1): a base project stays a free workspace until a module is added on
+demand. Adding `software` is the "build me an app" moment — it writes THIS island's
+`.claude/kit.config.json` (modules + wizard answers) and nothing above it (D4/D17). A module is
+**identity, not files** (D14): the agents/skills come from the installed plugin singleton; kit-add
+only writes config, manifest-tracked so it can be updated or removed cleanly.
+
+Engine (under `${CLAUDE_PLUGIN_ROOT}`):
+- `scripts/lib/kit-interview.sh --catalog <module>` — the module's wizard questions.
+- `scripts/kit-add.sh <module> --answers FILE [--dir DIR]` — derive + persist (the four-beat machine).
+- `scripts/kit-add.sh <module> --set k=v ... ` — same, answers as flags.
+
+## Steps
+
+1. **Resolve the module** from `$ARGUMENTS` (default `software` if none given). Confirm a catalog
+   exists: `scripts/lib/kit-interview.sh --catalog <module>` (non-zero rc = unknown module → tell
+   the user which modules exist: look in `${CLAUDE_PLUGIN_ROOT}/modules/`).
+2. **Render the wizard** (the catalog already carries each question's recommended `default`).
+3. **Ask with AskUserQuestion** — one batched round. For each question use its `header`,
+   `question`, and `options`; put the `recommended` option first and label it "(Recommended)".
+   The kit recommends; the user decides.
+4. **Persist** — build `{ "<key>": "<value>", ... }` to a temp file and run
+   `scripts/kit-add.sh <module> --answers /tmp/kit-<module>.json` (add `--dir` if not in the
+   island root). For software the wizard covers **versioning** (GitHub vs local git),
+   **deploy** (none / Vercel / other), and **CI** (GitHub Actions / none).
+5. **Report** what changed: the island config path, `modules`, and the resolved github/deploy/ci.
+   Note the workspace above was untouched, and that `/kit-task-start` etc. now apply here.
+
+## Rules
+
+- **Idempotent** — running it again with the same answers is a no-op; `modules` never duplicates.
+- **Never hand-edit `kit.config.json`** — always go through `kit-add.sh` so the manifest stays true.
+- **Writes only into this island** — never above the project level without an explicit confirm
+  (that's `kit-promote`'s job, not kit-add).
+- Honors `KIT_DRY_RUN` (preview) and `KIT_ASSUME_YES` (accept recommended defaults, for batch/CI).

package/commands/kit-docs.md

@@ -0,0 +1,45 @@
+---
+description: Browse claude-kit's own documentation from inside Claude Code. Use to open the kit docs, read the usage / agents / reference / contributing guides, or get a navigable index — bilingual (EN/ES), with prev/next navigation. Triggers — "kit docs", "claude-kit documentation", "open the kit guide", "how do I use the kit".
+argument-hint: "[readme|usage|agents|reference|contributing] [es]"
+allowed-tools: Read, Glob
+---
+
+# /kit-docs — browse the claude-kit docs
+
+The kit's documentation ships inside the plugin at `${CLAUDE_PLUGIN_ROOT}`. Use this to read and
+navigate it without leaving Claude Code. These docs are a **sequence** — readme → usage → agents →
+reference → contributing — so always offer prev/next.
+
+## Steps
+
+1. **Resolve language.** Default to the user's working language. If `$ARGUMENTS` contains `es` (or the
+   user is writing Spanish), use the `.es.md` variants; otherwise the English `.md`.
+
+2. **Doc map** (paths relative to `${CLAUDE_PLUGIN_ROOT}`):
+
+   | Key | EN | ES | What |
+   | --- | -- | -- | ---- |
+   | `readme` | `README.md` | `README.es.md` | overview · install · update · best practices · stack |
+   | `usage` | `docs/usage.md` | `docs/usage.es.md` | what you get, profiles, per-project model, `/kit-init`, `--dry-run`, `/kit-customize`, demos |
+   | `agents` | `docs/agents.md` | `docs/agents.es.md` | orchestrator → sub-agent model, 13-agent table, mermaid diagrams |
+   | `reference` | `docs/reference.md` | `docs/reference.es.md` | how it works, config, stack skills, Spec Kit, pre-push gate, requirements |
+   | `contributing` | `CONTRIBUTING.md` | `CONTRIBUTING.md` | submit agents/skills/profiles/requests upstream |
+
+3. **No key in `$ARGUMENTS`** → print the **index**: each doc as a row (key + one-line description) in
+   the order above, and tell the user to run `/kit-docs <key>` to open one.
+
+4. **A key given** → `Read` the resolved file from `${CLAUDE_PLUGIN_ROOT}` and present it:
+   - If the user asked a specific question, surface the **relevant section** + its path — don't dump the
+     whole file.
+   - Otherwise render the doc (keep mermaid/code blocks fenced as-is; for long docs, lead with the
+     section headers so they can jump).
+   - End with a **nav footer**: `← Prev: /kit-docs <prev>` · `Index: /kit-docs` · `Next: /kit-docs <next> →`
+     using the sequence order (readme → usage → agents → reference → contributing).
+
+5. Mention the same page is on GitHub if they prefer the browser (link the repo path).
+
+## Rules
+
+- Read only from `${CLAUDE_PLUGIN_ROOT}` (the installed kit) — never the user's project files.
+- Unknown key → show the index instead of erroring.
+- Keep it navigable: every response ends with how to reach the previous and next doc.

package/commands/kit-doctor.md

@@ -0,0 +1,52 @@
+---
+description: Onboarding preflight — check deps (Homebrew, git, gh, jq, perl, node, pnpm), authenticate gh + add scope:project, optionally set up SSH. Auto-installs everything it can; pauses only for sudo password (Homebrew) and browser OAuth (gh auth login).
+argument-hint: "[--dry-run] [--no-install] [--dismiss-local]"
+allowed-tools: Bash
+---
+
+# /kit-doctor — onboarding preflight
+
+Run the kit-doctor script to check all dependencies and authentication required by claude-kit.
+
+## What it checks
+
+| Tier | Checks |
+| ---- | ------ |
+| Tier 0 | Homebrew (macOS bootstrap — installs if missing, requires sudo password) |
+| Tier 1 | `git`, `gh` (≥2.29 for Projects v2), `jq`, `perl` — auto-installs via brew |
+| Tier 2 | `node`, `pnpm`, `vercel` (if .vercel/ exists), `turbo`/`playwright` (dev deps only) |
+| Local | Only when `.local.enabled` — installs `mlx-lm` via `uv tool install` (fallback `pipx`, never plain `pip`) + starts `mlx_lm.server` in background with a port health check (first run downloads ~4.5 GB) |
+| Auth | `gh auth status`, scope `project`, `git config user.name/email` |
+| SSH | Optional: detect existing key; `KIT_DOCTOR_SSH=1` triggers guided ed25519 setup |
+
+## Flags
+
+- `--dry-run` — report only, touch nothing (no installs, no server start)
+- `--no-install` — check + auth only, skip package installs
+- `--dismiss-local` — silence the "local layer down" SessionStart notice until the next x.y kit update (writes `.local.dismissed` to `kit.config.json`); session-only alternative: `KIT_LOCAL_DISMISS=1`
+
+## Steps
+
+1. Resolve the doctor script path: `${CLAUDE_PLUGIN_ROOT}/scripts/kit-doctor.sh`
+
+2. Pass through any `$ARGUMENTS` (e.g. `--dry-run` or `--no-install`):
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/scripts/kit-doctor.sh" $ARGUMENTS
+   ```
+
+3. If the script exits non-zero (Tier 1 failures remain):
+   - Surface the "Action required" items from the output
+   - Tell the user to fix them and re-run `/kit-doctor`
+   - Do not proceed with `/kit-init` until all Tier 1 checks pass
+
+4. If all Tier 1 checks pass:
+   - Report success
+   - Remind the user the onboarding guide is at `http://localhost:3001/onboarding` (or `$CCKIT_ADMIN_URL/onboarding`)
+
+## Rules
+
+- Never skip the preflight. `/kit-init` calls this automatically, but it can be run standalone.
+- Bare URLs only in terminal output (Terminal.app does not support OSC 8 hyperlinks).
+- The `--dry-run` flag makes the doctor read-only — safe to run in CI or before any changes.
+- For SSH setup, the user must set `KIT_DOCTOR_SSH=1` explicitly — the doctor never generates SSH keys by default.

package/commands/kit-export-project.md

@@ -0,0 +1,58 @@
+---
+description: Export this kit project to the non-terminal Claude surfaces (#376). Flattens CLAUDE.md (+ inlined @.claude/rules) into claude.ai custom-instructions, copies knowledge/ into an upload-ready folder, verifies Cowork compat, and emits a support matrix. Acceptance: the same project runs in terminal / Cowork / claude.ai with no hand edits.
+argument-hint: "[--verify] [--matrix] [--out DIR] [--dry-run]"
+allowed-tools: Bash
+---
+
+# /kit-export-project — run the project on claude.ai + Cowork, no hand edits
+
+A kit project runs on three Claude surfaces. **Terminal** and **Cowork** read `CLAUDE.md` + `.claude/`
+natively — they need nothing from this command. **claude.ai Projects** have no filesystem: only a
+"custom instructions" text box + uploaded "project knowledge". This command produces exactly those
+two artifacts, and checks the project is portable.
+
+## Tier model (#373)
+
+- **Tier A = portable** — skills / rules / agents / commands; meaningful in Cowork AND claude.ai.
+- **Tier B = CLI-only** — `statusline.sh` / `settings.json` / `hooks/` / `lib/`; need a terminal +
+  filesystem. The export carries only tier-A semantics off-terminal; a tier-B file the project
+  _requires_ is a portability defect `--verify` flags.
+
+## What it writes (default `.kit-export/`)
+
+| File                     | Use                                                                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `claude-instructions.md` | Flattened `CLAUDE.md` with `@.claude/rules/*` inlined (tier-A only) — paste into the claude.ai Project custom-instructions box. |
+| `project-knowledge/`     | `knowledge/**` + tier-A `rules/` + `agents/` — upload as Project knowledge.                                                     |
+| `SUPPORT-MATRIX.md`      | terminal / Cowork / claude.ai capability table, generated from the manifest.                                                    |
+
+## Modes
+
+- (no args) — full export to `.kit-export/` (or `--out DIR`).
+- `--verify` — Cowork + claude.ai compat check only, writes nothing; rc 1 on a portability defect.
+- `--matrix` — print the support matrix, write nothing.
+- `--dry-run` — report what it would write, write nothing.
+
+## Steps
+
+1. Run the export (pass through `$ARGUMENTS`):
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/scripts/kit-export-project.sh" $ARGUMENTS
+   ```
+
+   (or `kit export $ARGUMENTS` — the CLI dispatches to the same canonical script.)
+
+2. For a full export, tell the user the two manual steps claude.ai needs:
+   - paste `.kit-export/claude-instructions.md` into the Project's custom-instructions box
+   - upload `.kit-export/project-knowledge/` as the Project's knowledge
+
+3. If `--verify` exits non-zero, surface the flagged tier-B-required / missing imports — those
+   files silently no-op off-terminal; fix before relying on the non-terminal surfaces.
+
+## Rules
+
+- Bare URLs only in terminal output (no OSC 8).
+- The export carries **only tier-A** semantics to claude.ai — a tier-B shim has no meaning without a
+  filesystem. Run `--verify` to confirm the portable surface is self-sufficient.
+- `/kit-doctor` runs the same `--verify` as a connection test — green there means this export is clean.

package/commands/kit-export-training.md

@@ -0,0 +1,49 @@
+---
+description: OPT-IN export of your Claude Code sessions to redacted training JSONL — pick sessions, run the dataset builder with redaction ON, and get JSONL ready for the fine-tuning pipeline.
+argument-hint: "[--match KEY ...] | [--sessions FILE ...]   (default: current project)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# /kit-export-training — export sessions as redacted training data
+
+Fine-tuning a local model on your own work only helps if the data leaves the machine clean. This is
+the **consent gate** in front of a dataset builder (`chat-datasets/build_dataset.py`): it lets a
+builder choose which sessions to export, **always** runs the builder with redaction ON (secret /
+key / token / email masking is the builder's default; this command never passes `--no-redact`), and
+prints where it wrote plus a reminder that redaction must be verified before sharing.
+
+Nothing here is automatic — it runs **only when explicitly invoked**, and it never uploads anything.
+The output is plain JSONL on disk; what you do with it is your call.
+
+Handler (under `${CLAUDE_PLUGIN_ROOT}`):
+- `scripts/kit-export-training.sh [--builder PATH] [--match KEY ...] [--dirs DIR ...] [--sessions FILE ...] [--out PATH] [--split FRAC] [--final-only] [--drop-narration]`
+
+## Steps
+
+1. **Locate the builder (config-driven)** — the handler resolves `build_dataset.py` with NO
+   hardcoded user path, in this order: `--builder PATH` → `KIT_DATASET_BUILDER` env → a sibling
+   `chat-datasets/build_dataset.py` next to the git repo root. If none resolve it stops and asks for
+   `--builder` / `KIT_DATASET_BUILDER`.
+2. **Select what to export** — default is the **current git project** (matched by its slug under
+   `~/.claude/projects`). Let the builder choose instead:
+   - `--match KEY ...` — project-dir name substrings (e.g. `cckit tuempresa`)
+   - `--sessions FILE ...` — individual `*.jsonl` transcripts (staged into a temp dir)
+   - `--dirs DIR ...` — explicit `~/.claude/projects/<dir>` directories
+3. **Confirm (opt-in)** — on a TTY the handler asks before writing anything; aborting writes
+   nothing. Use AskUserQuestion to surface the selection + output path for an explicit yes.
+4. **Build with redaction ON** — runs `build_dataset.py` with masking (the builder's default; there
+   is deliberately **no `--no-redact` passthrough**). Optional `--split`, `--final-only`,
+   `--drop-narration` pass straight through.
+5. **Report** — prints the JSONL path, the sidecar `*.stats.json` (includes a `redactions_applied`
+   tally), and the train/valid split dir if `--split` was used.
+6. **Remind** — redaction is applied automatically but is **not a guarantee**; the user must verify
+   the output for leftover secrets, tokens, private names, or customer data **before sharing**.
+
+## Rules
+
+- **Opt-in only** — never runs unprompted; never uploads. Output is local files.
+- **Redaction is always on** — this command exists to enforce that; do not add a way to disable it.
+- **Builder path is config-driven** — `--builder` / `KIT_DATASET_BUILDER` / sibling discovery; never
+  hardcode an absolute path.
+- **Default output** — `~/.claude/exports/<slug>-training.jsonl` unless `--out` is given.
+- Honors `KIT_ASSUME_YES` (skip the final confirm, for batch/CI).

package/commands/kit-init.md

@@ -0,0 +1,126 @@
+---
+description: Scaffold a tailored .claude/ (agents + skills + rules + workflow) into the current project from a claude-kit role profile.
+argument-hint: "[profile] [--name ...] [--repo owner/repo] [--project-number N] [--memory on]"
+allowed-tools: Bash, Read, AskUserQuestion, Edit
+---
+
+# /kit-init — scaffold this project's .claude/ from claude-kit
+
+You are initializing the current project with the **claude-kit** setup. The kit lives at
+`${CLAUDE_PLUGIN_ROOT}` (the installed plugin root). The engine is
+`${CLAUDE_PLUGIN_ROOT}/scripts/init.sh`.
+
+## Steps
+
+1. **Identify the project, then gather inputs.**
+
+   **First, identify what you're initializing and recommend the per-project model:**
+   - Inspect the target. If it looks like a **parent/workspace** holding several projects (multiple
+     subdirectories with their own `.git` / `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`),
+     **recommend running `/kit-init` inside each project separately** — one `.claude/` per project —
+     instead of once at the workspace root. Explain the payoff: each project maps to its own MemPalace
+     **wing**, so the kit keeps **traceability and history per project** (decisions, plans, and agent
+     diaries never bleed across projects). List the projects you detected and let the user pick.
+   - If it's a single project (a `.git` here, or one app), continue here.
+   - Suggest a layout that favors the kit — `CLAUDE.md` + `.claude/` at the project root, plans under
+     `docs/plans/`, the kit's `scripts/` alongside; **one repo = one kit setup**. See
+     [docs/usage.md → Project structure](${CLAUDE_PLUGIN_ROOT}/docs/usage.md).
+
+   **Then gather inputs.** If `$ARGUMENTS` already names a profile and the key values, use them.
+   Otherwise ask the user with `AskUserQuestion`:
+   - **Profile** — `software`, `content`, `research`, or `minimal`
+     (read `${CLAUDE_PLUGIN_ROOT}/profiles/*.json` to describe each)
+   - **GitHub repo** — `owner/repo` (offer `gh api user --jq .login` as the default owner)
+   - **Projects v2 board** — board number if they use one, else "off"
+   - **MemPalace memory** — on/off (off unless they actively use MemPalace)
+   - **Spec Kit (SDD)** — on/off; pass `--speckit on` to enable the spec-driven workflow section
+   - **Pre-push gate** — optional. If they want a check to run before every `git push` (e.g.
+     `pnpm build`, `pnpm typecheck`, `pnpm -w lint`), pass `--prepush "<command>"`. Omit for none —
+     projects without it are never blocked.
+   - **Language** — working language (e.g. English, Spanish, mixed)
+
+   Note: stack-gated build skills (`feature-build-refine`, `supabase-patterns`, …) ship with the
+   `software` profile and **self-activate** only when their technology is in the project's
+   `package.json` — nothing to choose at init.
+
+   Skip questions already answered in `$ARGUMENTS`. Derive sensible defaults (project name =
+   repo name, slug = lowercased name) and only confirm the non-obvious ones.
+
+2. **Run the engine** from the project root:
+
+   ```bash
+   "${CLAUDE_PLUGIN_ROOT}/scripts/init.sh" \
+     --profile <profile> \
+     --target "$PWD" \
+     --name "<Project Name>" \
+     --repo "<owner/repo>" \
+     [--project-number <N>] \
+     [--memory on] \
+     [--lang "<language>"]
+   ```
+
+   It substitutes `{{VARS}}`, resolves `<!-- IF:FLAG -->` blocks, and writes `CLAUDE.md`,
+   `.claude/{kit.config.json,agents,skills,rules,settings.local.json}`, and `scripts/`.
+
+   Tip: add `--dry-run` to print the exact scaffold plan (files, hooks, onboarding tools) **without
+   writing anything** — useful to confirm the profile first. Offer the user a dry-run preview if the
+   profile/target is at all uncertain.
+
+3. **Set up external tools — opt-in.** Configure the CLIs the scaffold relies on. This is
+   **opt-in and consent-based**: for each tool, **explain what it is and why it's needed, then
+   install/authenticate only with the user's go-ahead**. Nothing is forced; a declined tool just
+   leaves the matching features dormant (they don't error) and can be re-run anytime.
+
+   **GitHub CLI (`gh`)** — backs the whole task/PR workflow (issues, PRs, labels, milestones).
+   - Detect: `gh auth status`. If not authenticated, explain every `task-*` skill needs it and,
+     with consent, run `gh auth login`. Re-check with `gh auth status`.
+
+   **MemPalace** (only when memory was enabled) — the persistent-memory backend: an MCP server
+   exposing the `mempalace_*` tools plus the `mempalace-mcp` binary, which the `Stop`/`PreCompact`
+   hooks and every agent's diary protocol depend on. Absent = dormant, never errors.
+   - Detect: `command -v mempalace-mcp` and `claude mcp list | grep -i mempalace`.
+   - Binary present but unregistered → with consent run `claude mcp add mempalace mempalace-mcp`;
+     verify with `claude mcp list`. Then confirm with a `mempalace_status` call.
+   - Binary missing → explain it and ask the user for their install method; `mempalace-mcp` is a
+     user-provided tool, so **do not guess a package name or fabricate an installer**. Re-check
+     `command -v mempalace-mcp`.
+
+   **Google Workspace CLI (`gws`)** — opt-in; offer only if the user works with Google Docs / Sheets /
+   Slides / Drive / Gmail / Calendar (e.g. the `gws-slides` skill drives it).
+   - Detect: `command -v gws`, then `gws auth status`.
+   - Installed but not authenticated → with consent run `gws auth login` (OAuth, opens a browser).
+     `gws auth setup` configures the GCP project + OAuth client and needs `gcloud`. Re-check
+     `gws auth status`.
+   - `gws` missing → explain it and ask the user for their install method; **do not guess a package
+     name or installer**. Re-check `command -v gws`.
+
+4. **Report** what was written (echo the engine's summary) and surface the printed "Next steps"
+   (seed labels/milestones, capture Projects v2 IDs).
+
+5. **Offer** to run `./scripts/setup-labels.sh` and `./scripts/setup-milestones.sh` now if a
+   GitHub repo was configured. Ask before running — they mutate the repo.
+
+6. **Audit stack conformance** (when the `software` profile activated a stack-gated build skill).
+   The build skills (`feature-build-refine`, `supabase-patterns`, …) self-activate from
+   `package.json` and immediately become the project's "how we build" standard — but the existing
+   code may not follow them. Briefly audit the repo against each activated skill (directory layout,
+   the canonical form/handler/data-access patterns) and report **conforms / partial / divergent**.
+   On non-trivial drift, surface the reconciliation choice to the user — **migrate repo → standard**,
+   **amend standard → repo**, or **hybrid** — and, if they choose migrate/hybrid, offer a phased
+   migration plan (`docs/plans`, per the `plan-output-format` rule) + tracked issues. Don't present
+   the standard as already-followed when it isn't. (Spec Kit's `/speckit` runs the deeper version of
+   this audit in its §6 before authoring the constitution.)
+
+7. **Point to `/kit-customize`.** Tell the user they can tailor the setup anytime with `/kit-customize`
+   — add/edit/delete agents, wire skills + tools onto them, search/suggest skills for the profile, lint
+   agents, or build (and save) a custom profile. It also activates automatically when they ask to
+   create/edit/delete an agent. Use it whenever the presets don't fit exactly. And point them to
+   **`/kit-docs`** to browse the kit's guides (usage · agents · reference · contributing) from inside
+   Claude Code. For a React project, point them to **`/kit-annotate`** to add click-to-annotate UI
+   feedback wired to Claude (via Agentation).
+
+## Rules
+
+- Never overwrite an existing `.claude/kit.config.json` without passing `--force` and confirming.
+- Do not invent a repo or owner — confirm with the user.
+- After scaffolding, the project owns its `.claude/` files. Edits there are the user's, not the kit's.