dotfiles

Prepare for a /clear: bring all documentation up to date with this session's changes, persist recovery context (memory + handoff), and emit a copy-paste resume prompt so the next session begins the next task with zero context loss. Invoke explicitly as /clear-prep [next-task].

Use when adding or modifying a devcontainer feature in devcontainer.json - fetch its devcontainer-feature.json schema first and verify every option key exists, because features silently drop unknown options.

Use when creating branches, commits, pushes, or PRs with plain git. Branch BEFORE committing — never commit directly onto the default branch. Avoids virtual-branch composition bugs where commits silently depend on other applied branches.

Write a CROSS-SURFACE session handoff to a tracked path and push it, so a session on another surface (web, desktop, or CLI) can continue with zero context loss. Use when ending a session whose work must be picked up on a DIFFERENT machine/surface. For same-machine /clear continuity use /clear-prep instead. Invoke as /handoff [next-task].

Use when running parallel-scientist research - ALWAYS follow with an opus verification stage that re-probes load-bearing claims and surfaces gaps. Skipping the verifier almost shipped a wrong recommendation in session 2026-04-07e.

Use when sharing a single `~/.ssh/config` across macOS + Linux - apply OpenSSH `IgnoreUnknown` to tolerate macOS-only directives (`UseKeychain`, `AddKeysToAgent`) on Linux where they would otherwise be fatal.

Use when auditing whether the repo's pinned tools are current AND whether any hand-rolled custom code is now superseded by a native tool feature. Produces a retire/bump report from mise outdated + pkl/pin-vs-latest diff + a cache-first release-note scan.

Use when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent. Fetches library documentation, manages AI coding skills, and configures Context7 MCP.

Bring the devcontainer up/down/build, run tier 1-3 smoke checks, and respect the thin host-user overlay invariant. Use when working with .devcontainer/, mise tasks, or the @devcontainers/cli.

Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists, where the question should be treated as a graphify query first. Turns any input (code, docs, papers, images, videos) into a persistent knowledge graph with god nodes, community detection, and query/path/explain tools.

Invoke MCP servers as one-shot CLI commands (no native registration, no schema injection into Claude's context). Use whenever a research or tool-use task wants an MCP server's capabilities without paying the per-conversation context tax of `claude mcp add`.

Use when fetching mintlify-hosted documentation: curl `llms.txt` plus per-page `.md` surface, NOT `mcp2cli` against per-repo URLs (descriptor-only previews, no live MCP).

Research-first workflow for investigating and resolving CI build warnings. Use when CI logs or Docker build output contain warnings that need triage — fix if possible, document and create GH issue if not.

Use when curating the auto-memory index (MEMORY.md) — trimming a bloated hook, deleting a stale memory, or reacting to a size warning. Shortening a hook silently destroys any fact that lives only there, so the order is verify → migrate/correct → THEN shorten. Run `mise run memory-index` first.

Ship and land PRs via `mise run ship` / `mise run land` — the full gated loop from committed work to merged-and-locally-validated main. Use whenever committing work that should become a PR, when asked to merge a green PR, or when validating that the ship/land wiring is intact. Never hand-roll commit→push→PR→merge sequences.

Converge the local devcontainer onto the latest CI-built image and verify it, via `mise run sync`. Use after a merge to main (promote retags :dev), when unsure whether the local container/base is current, or to pre-validate a PR image with --tag pr-NNN. Also carries the wiring audit checklist for the sync workflow itself.

Resume work on a DIFFERENT surface (web, desktop, or CLI) from a tracked cross-surface handoff written by /handoff. Pulls the branch, reads the latest docs/handoffs/session-*.md, restates the plan, and continues. Invoke as /resume [handoff-file].

Watch this repo's CI failure-report workflow outputs, triage failed runs, launch the research team, drive branch-based remediation, and repeat until the workflow is green or blocked. Use when you want the full repo-local monitor and fix loop for GitHub Actions failures in this dotfiles repo.

Use when a Pkl file imports hyphenated filenames - an `as` alias is required. (Historical: pklr once lacked import/spread; parity-verified fixed at hk 1.49, the HK_PKL_BACKEND=pkl override is retired.)

Use when enabling Shift+Enter and other modified-key combinations inside TUIs running under tmux - forward CSI-u sequences.

Run the smallest useful local validation set for this repo before pushing or after a failed CI run. Use when you need fast local checks for Docker, devcontainer, mise, hk, or Python workflow regressions. Supports standard, tool-specific, and image-specific modes.

Use when configuring docker/bake-action: the `set` parameter has higher precedence than `push`; an unconditional `*.output=type=cacheonly` silently prevents image pushes on main.

Use when the OMC HUD statusline shows discovery-wrapper errors like "Plugin dist exists but HUD not found" - bypass the wrapper and invoke the target directly to surface the real import error.

Use when running Python tools from the repo root with uv - prefer `uv run --project python` over `uv run --directory python`. The former keeps cwd unchanged; the latter breaks relative test paths.

Validate chezmoi templates render correctly and check for common template issues. Use when editing home/ templates or after changing .chezmoi.toml.tmpl.

Use when the user asks about a specific library, framework, SDK, CLI tool, or cloud service -- even for well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Retrieves up-to-date documentation, API references, and code examples. Training data may not reflect recent API changes or version updates. Always use for: API syntax questions, configuration options, version migration issues, "how do I" questions mentioning a library name, debugging that involves library-specific behavior, setup instructions, and CLI tool usage. Use even when you think you know the answer -- do not rely on training data for API details, signatures, or configuration options as they are frequently outdated. Always verify against current docs. Prefer this over web search for library documentation and API details.

Normalize a failed GitHub Actions run for this dotfiles repo into one machine-readable triage report. Use when given a run URL, run id, job URL, or "latest failed run" and you need failing jobs, failing steps, warning signatures, blocker signatures, and likely owner areas. Use the GitHub plugin for repo/PR context, but use `gh` for Actions run and log retrieval.

Vet a new tool or backend before adding it to the devcontainer image or mise manifest in this repo. Use when proposing a new tool, backend, registry, or package source and require docs-backed rationale, local feasibility proof, and a recorded acceptance or rejection decision.

Create or reuse a branch for fixing a failed CI run in this repo, run local preflight, push the branch, and optionally create or update a PR using the GitHub plugin. Use when a remediation plan is ready and fixes must never go directly to main.

Record recurring CI failure signatures, successful fixes, rejected fixes, and tool/backend incompatibilities for this repo only. Use after triage, after remediation, or after rejecting an approach so the next iteration does not repeat the same blind fix.

Launch a bounded multi-agent research team for a failed CI run in this dotfiles repo. Use when a normalized GitHub Actions failure report exists and you need parallel analysis across docker-bake, Dockerfile, chezmoi, mise, devcontainer, hk, Python automation, synthesis, and verification. Prefer OMX/team orchestration first and Codex native subagents as fallback.