@lovehlmmm/primekit 1.0.0

package/skills/ai-multimodal/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: pk:ai-multimodal
+description: Analyze and generate image, audio, video, and document content through the npm-latest Multix CLI and live provider catalogs. Use for vision analysis, transcription, OCR, design extraction, and multimodal generation.
+user-invocable: true
+when_to_use: "Invoke for Gemini vision, OCR, media generation, or transcription."
+category: ai-ml
+keywords: [vision, image, video, audio, Gemini]
+license: MIT
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+argument-hint: "[file-path] [prompt]"
+---
+
+# AI Multimodal
+
+Process audio, images, videos, and documents with the latest npm release of
+`@mrgoonie/multix`. Use the `npx` invocation shown here; do not install or
+call a global `multix`.
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix --version
+```
+
+## Setup
+
+Requires Node.js 20+ and provider keys in process env, project `.env`, or
+`~/.multix/.env`.
+
+```bash
+export GEMINI_API_KEY="your-key"          # https://aistudio.google.com/apikey
+export OPENROUTER_API_KEY="your-key"      # optional image/video routing
+export MINIMAX_API_KEY="your-key"         # optional MiniMax generation
+```
+
+Verify setup:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix check --verbose
+```
+
+When npm networking is enabled, every command resolves npm's `latest` dist-tag
+and forces a registry staleness check. Network-restricted sessions must
+pre-warm the current release first.
+
+### Backend ownership
+
+- Treat the npm-latest Multix CLI as the runtime contract for covered media
+  operations; keep this skill focused on orchestration, provider setup, and
+  examples.
+- Report missing keys, FFmpeg, provider access, or `multix check` failures as
+  environment blockers, not kit-loader failures.
+- Track missing capability upstream and refresh the package's latest release
+  before retrying. Do not recreate a parallel PrimeKit Python backend unless an
+  accepted ADR or explicit maintainer decision changes backend ownership.
+- The skill intentionally has no managed runtime package: PrimeKit requires
+  immutable package pins there, while this command contract requires npm latest.
+
+## Quick Start
+
+Analyze media:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix gemini analyze \
+  --files input.png \
+  --prompt "Analyze this content" \
+  --format markdown \
+  --output analysis.md
+```
+
+Transcribe audio or video:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix gemini transcribe \
+  --files interview.mp4 \
+  --prompt "Generate a transcript with timestamps" \
+  --format markdown \
+  --output transcript.md
+```
+
+Extract structured data:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix gemini extract \
+  --files receipt.png \
+  --prompt "Extract merchant, date, total, and line items as JSON" \
+  --format json \
+  --output receipt.json
+```
+
+Convert documents to Markdown:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix doc convert \
+  --input report.pdf \
+  --output report.md
+```
+
+Generate images after resolving an available model from the live provider catalog:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix gemini generate \
+  --prompt "Studio product photo on white background" \
+  --model <verified-model-id> \
+  --aspect-ratio 1:1 \
+  --size 2K \
+  --output product.png
+```
+
+Generate images through OpenRouter:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix openrouter generate \
+  --prompt "Editorial campaign key visual" \
+  --model <provider-qualified-model-id> \
+  --aspect-ratio 4:5 \
+  --image-size 2K \
+  --output campaign.png
+```
+
+Configure OpenRouter fallback models with:
+
+```bash
+export OPENROUTER_FALLBACK_MODELS="black-forest-labs/flux.2-flex,recraft-ai/recraft-v3"
+```
+
+Generate videos with a currently available provider model:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix gemini generate-video \
+  --prompt "15-second product demo video" \
+  --model <verified-model-id> \
+  --resolution 1080p \
+  --aspect-ratio 16:9 \
+  --output demo.mp4
+```
+
+Generate with MiniMax:
+
+```bash
+# Image
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix minimax generate \
+  --prompt "A cyberpunk city" --model <verified-image-model> --aspect-ratio 16:9 --output city.png
+
+# Video
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix minimax generate-video \
+  --prompt "A dancer" --model <verified-video-model> --duration <supported-seconds> --resolution <supported-resolution> --output dancer.mp4
+
+# Speech
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix minimax generate-speech \
+  --text "Hello world" --model <verified-speech-model> --voice <verified-voice> --output hello.mp3
+
+# Music
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix minimax generate-music \
+  --lyrics "La la la\nOh yeah" --prompt "upbeat pop" --model <verified-music-model> --output song.mp3
+```
+
+Optimize media before provider uploads:
+
+```bash
+npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix media optimize \
+  --input raw-video.mp4 \
+  --output optimized-video.mp4 \
+  --target-size 20
+```
+
+## Provider and Model Resolution
+
+The npm-latest Multix CLI owns command syntax. Provider catalogs own model IDs,
+availability, features, limits, pricing, and deprecations. Before generation:
+
+1. Run the relevant npm-latest `multix ... --help` command.
+2. Check the provider's current model and pricing documentation.
+3. Select an explicit model that supports the requested modality and controls.
+4. Record that model in project configuration when reproducibility matters.
+
+Never infer a provider model as "latest," "default," or "recommended" from this skill.
+
+## Failure UX
+
+- **First run / offline**: when npm networking is enabled, `npx --prefer-online` checks the npm registry before each run. For sandboxed or offline sessions, pre-warm with `npx --yes --prefer-online --package=@mrgoonie/multix@latest -- multix --version` while network access is available.
+- **Node <20**: install Node.js 20+ and rerun the command.
+- **Provider key missing**: `multix` reports the missing env var. Export keys in the shell, project `.env`, or `~/.multix/.env`.
+- **Environment discovery**: use the locations reported by the resolved CLI; do not infer provider-key search paths from an older backend.
+- **Provider API error**: keep the full provider error, redact keys, and retry only after fixing auth, billing, quota, model access, or request parameters.
+- **Codex installs**: this skill has no managed runtime package. Codex uses the npm-latest `npx` commands in this file, so pre-warm the npm cache before network-restricted runs.
+
+If the resolved CLI does not expose a required operation, report the observed gap
+and check the upstream issue tracker. Do not revive a parallel local backend.
+
+## References
+
+Load for detailed guidance:
+
+| Topic | File | Description |
+|-------|------|-------------|
+| Music | `references/music-generation.md` | Stable music brief and review workflow; resolve live provider controls. |
+| Audio | `references/audio-processing.md` | Stable transcription and generation workflow; resolve live formats, models, limits, and pricing. |
+| Images | `references/vision-understanding.md` | Stable OCR and visual-analysis workflow; resolve live input limits. |
+| Image Gen | `references/image-generation.md` | Stable generation/editing workflow; resolve live model capabilities and pricing. |
+| Video | `references/video-analysis.md` | Stable video-analysis workflow; resolve live inputs and limits. |
+| Video Gen | `references/video-generation.md` | Stable video-generation workflow; resolve live controls and models. |
+| MiniMax | `references/minimax-generation.md` | Stable multimodal workflow; resolve the live MiniMax catalog. |
+
+## Limits
+
+Provider limits still apply. Resolve current inline/file-upload size,
+retention, duration, context, and output limits before execution. When input or
+output exceeds the verified limit, split media with `ffmpeg` or the resolved
+Multix media command, process segments, then combine the results.
+
+Transcript output should be Markdown with metadata, chunk status, and timestamped
+lines:
+
+```text
+[HH:MM:SS -> HH:MM:SS] transcript content
+```
+
+## Outputs
+
+Invoke `pk:project-organization` when generated assets need to be grouped into a
+project, campaign, report, or deliverable folder.
+
+## Resources
+
+- [multix CLI](https://github.com/mrgoonie/multix-cli)
+- [Gemini API Docs](https://ai.google.dev/gemini-api/docs/)
+- [Gemini Pricing](https://ai.google.dev/pricing)
+- [OpenRouter Image Generation Docs](https://openrouter.ai/docs/guides/overview/multimodal/image-generation)
+- [OpenRouter Provider Routing](https://openrouter.ai/docs/features/provider-routing)
+- [MiniMax API Docs](https://platform.minimax.io/docs/api-reference/api-overview)
+- [MiniMax Pricing](https://platform.minimax.io/pricing)

package/skills/ai-multimodal/references/audio-processing.md

@@ -0,0 +1,32 @@
+# Audio Processing
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Provider catalogs
+own available transcription, speech, voice, language, streaming, format,
+duration, context, retention, and pricing facts.
+
+## Transcription Workflow
+
+1. Inspect the resolved transcription command with `--help`.
+2. Verify current input and output limits in provider documentation.
+3. Normalize or split audio only when the verified limits require it.
+4. Request timestamps, speaker labels, uncertainty markers, and domain terms
+   appropriate to the task.
+5. Validate names, numbers, quoted language, and action items against the source.
+6. Merge segments without inventing text across boundaries.
+
+```bash
+<latest-multix> gemini transcribe \
+  --files interview.mp3 \
+  --prompt "Timestamped transcript with speakers and uncertainty markers" \
+  --format markdown \
+  --output transcript.md
+```
+
+## Generation Workflow
+
+Resolve a current model and voice from the live provider, pass both explicitly,
+generate a short review sample, then validate pronunciation, pacing, consent,
+and output rights before producing the full asset.
+
+Do not copy token rates, cost calculations, model rankings, hard duration
+limits, or deprecation schedules into this file.

package/skills/ai-multimodal/references/image-generation.md

@@ -0,0 +1,38 @@
+# Image Generation
+
+Use the npm-latest Multix invocation from `../SKILL.md`. This reference owns
+workflow, not a provider snapshot.
+
+## Resolve Before Running
+
+1. Run the resolved image-generation command with `--help`.
+2. Check the provider's current image-model and pricing documentation.
+3. Verify that the selected model supports the requested generation, editing,
+   reference-image, size, aspect-ratio, text, and safety controls.
+4. Pass the verified model ID explicitly. Never infer a default from this file.
+
+Model IDs, rankings, release status, limits, latency, and prices are live
+provider facts. Do not copy them into project documentation or tests.
+
+## Workflow
+
+1. Define subject, composition, style, lighting, palette, and output use.
+2. Choose an aspect ratio and resolution supported by the verified model.
+3. Generate a small review batch.
+4. Check prompt adherence, anatomy, text accuracy, brand consistency, and
+   prohibited content.
+5. Refine one variable at a time and preserve the accepted prompt/config.
+6. Save the final asset plus the explicit provider/model metadata needed to
+   reproduce it.
+
+```bash
+<latest-multix> gemini generate \
+  --prompt "<specific visual brief>" \
+  --model <verified-model-id> \
+  --aspect-ratio <supported-ratio> \
+  --size <supported-size> \
+  --output image.png
+```
+
+For current capabilities and pricing, use the provider links in
+`../SKILL.md`.

package/skills/ai-multimodal/references/minimax-generation.md

@@ -0,0 +1,22 @@
+# MiniMax Generation
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Resolve available
+image, video, speech, music, voice, duration, resolution, language, safety, and
+pricing controls from the live MiniMax catalog before each workflow.
+
+## Workflow
+
+1. Inspect the relevant resolved `multix minimax ... --help` command.
+2. Verify one model supports the requested modality and controls.
+3. Pass the model and other catalog IDs explicitly.
+4. Generate a short review asset first.
+5. Validate prompt adherence, continuity, pronunciation, rights, and safety.
+6. Preserve the accepted prompt and explicit provider configuration.
+
+```bash
+<latest-multix> minimax <operation> \
+  --model <verified-model-id> \
+  <verified-operation-flags>
+```
+
+Do not cache a model roster, release status, ranking, hard limit, or price here.

package/skills/ai-multimodal/references/music-generation.md

@@ -0,0 +1,25 @@
+# Music Generation
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Provider catalogs
+own current music models, duration, lyrics, vocals, streaming, format, rights,
+safety, quota, and pricing facts.
+
+## Workflow
+
+1. Define purpose, duration, structure, mood, instrumentation, tempo, vocals,
+   and licensing constraints.
+2. Inspect the resolved music command with `--help`.
+3. Verify a current model supports the required controls.
+4. Pass the model explicitly and generate a short review sample.
+5. Review structure, artifacts, lyric accuracy, loudness, rights, and safety.
+6. Preserve the accepted prompt/configuration with the final asset.
+
+```bash
+<latest-multix> minimax generate-music \
+  --prompt "<music brief>" \
+  --model <verified-model-id> \
+  --output music.mp3
+```
+
+Never store a recommended model, catalog matrix, release date, duration limit,
+or price in this reference.

package/skills/ai-multimodal/references/video-analysis.md

@@ -0,0 +1,27 @@
+# Video Analysis
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Resolve current
+provider models, input methods, formats, duration/context limits, retention,
+YouTube support, and pricing from live provider documentation.
+
+## Workflow
+
+1. State the required output: summary, transcript, scene map, comparison,
+   timestamps, or structured extraction.
+2. Inspect the pinned analysis/transcription command with `--help`.
+3. Verify the chosen model and upload method against the live provider limits.
+4. Split or compress media when the verified boundary requires it.
+5. Ask for timestamped evidence and distinguish observed content from inference.
+6. Validate important timestamps against the source before publishing.
+7. Delete provider-hosted files when the live API and task require cleanup.
+
+```bash
+<latest-multix> gemini analyze \
+  --files video.mp4 \
+  --prompt "Return a timestamped scene summary and unresolved ambiguities" \
+  --format markdown \
+  --output analysis.md
+```
+
+Never encode provider token math, maximum duration, file expiry, model status,
+or a recommended model in this reference.

package/skills/ai-multimodal/references/video-generation.md

@@ -0,0 +1,28 @@
+# Video Generation
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Resolve current
+provider model IDs, generation modes, duration, resolution, aspect ratio,
+reference-frame, audio, extension, safety, latency, and pricing facts live.
+
+## Workflow
+
+1. Write a shot brief: subject, action, setting, camera, lighting, timing, and
+   audio intent.
+2. Inspect the resolved video-generation command with `--help`.
+3. Verify the requested controls against one currently available model.
+4. Pass the verified model and supported values explicitly.
+5. Generate a short review asset and inspect continuity, motion, artifacts,
+   prompt adherence, audio, and policy compliance.
+6. Preserve the accepted prompt/config and disclose generated media as required.
+
+```bash
+<latest-multix> gemini generate-video \
+  --prompt "<shot brief>" \
+  --model <verified-model-id> \
+  --resolution <supported-resolution> \
+  --aspect-ratio <supported-ratio> \
+  --output video.mp4
+```
+
+Never cache a "latest" or "production" model, capability matrix, release date,
+price estimate, or hard provider limit here.

package/skills/ai-multimodal/references/vision-understanding.md

@@ -0,0 +1,27 @@
+# Vision Understanding
+
+Use the npm-latest Multix invocation from `../SKILL.md`. Resolve current
+model availability, image formats, inline/upload boundaries, context use,
+retention, and pricing from live provider documentation.
+
+## Workflow
+
+1. Define the evidence needed: OCR, layout, object/scene description, visual
+   comparison, accessibility review, or structured extraction.
+2. Inspect the resolved analysis command with `--help`.
+3. Preserve source resolution needed for small text or fine details.
+4. Ask the model to separate visible evidence, uncertainty, and inference.
+5. For multiple images, label inputs and request explicit cross-image mapping.
+6. Verify critical text, measurements, identities, and safety conclusions
+   against the original image.
+
+```bash
+<latest-multix> gemini analyze \
+  --files input.png \
+  --prompt "Extract visible text and describe uncertain regions separately" \
+  --format markdown \
+  --output analysis.md
+```
+
+Do not store token counts, cost examples, file-expiry windows, or model defaults
+in this reference.

package/skills/ai-multimodal/skill.yaml

@@ -0,0 +1,3 @@
+name: ai-multimodal
+version: "1.0.0"
+description: Multimodal analysis and generation through the npm-latest @mrgoonie/multix CLI.

package/skills/ak/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: pk:primekit
+description: "Operate the primekit control-plane CLI itself — the PrimeKit binary that installs, inspects, updates, recovers, and removes kits and their skills. Use when the next action is invoking an primekit subcommand (init, kit, skills, plan, journal, doctor, recover, self-update, login), deciding between read-only inspection and lifecycle mutation, disambiguating project vs global scope, or interpreting primekit --json output. Not for authoring skills (use pk:skill-creator) or routing generic work (use pk:primekit)."
+user-invocable: true
+when_to_use: "Invoke when the next action is running an primekit subcommand or interpreting its output. Do not invoke for skill authoring (pk:skill-creator), plan writing (pk:plan), journal writing (pk:journal), generic task routing (pk:primekit), or kit-specific workflows already covered by their own skills."
+category: cli
+keywords: [primekit, cli, lifecycle, install, kit, skills, scope, adapter, doctor, recover, self-update]
+argument-hint: "[goal or subcommand]"
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+# primekit — safe CLI operation
+
+Purpose: teach agents how to use the `primekit` control-plane CLI without breaking
+user-owned state. This skill owns the safe **operating model**, not the flag
+reference. The generated appendix at
+[`references/command-reference.md`](./references/command-reference.md) is a
+starting index; `primekit <cmd> --help` and `--json` output are always
+authoritative.
+
+## When to use vs when not to use
+
+Use `pk:primekit` when the next concrete action is:
+
+- running an `primekit` subcommand (`init`, `kit`, `skills`, `plan`, `journal`,
+  `doctor`, `recover`, `self-update`, …);
+- deciding between a read-only inspection command and a mutating lifecycle
+  command;
+- disambiguating project vs user/global scope, adapter, or delivery mode
+  before a change lands somewhere the user did not expect;
+- interpreting an `primekit <cmd> --json` envelope.
+
+Do **not** invoke for:
+
+| Intent | Route to |
+|--------|----------|
+| Authoring or refining a Claude skill | `pk:skill-creator` |
+| Writing or executing an implementation plan | `pk:plan`, `pk:cook` |
+| Writing a technical journal entry | `pk:journal` |
+| Choosing which installed skill fits a task | `pk:primekit` (task router) |
+| Any kit-specific workflow already covered by its own skill | that skill |
+
+`pk:primekit` decides *which skill runs*. `pk:primekit` runs *the primekit binary itself*.
+
+## Safe operating protocol
+
+Follow every step in order. Do not skip the inspect step even when the
+command name is familiar — the installed binary may be older or newer than
+the appendix.
+
+1. **Triage the goal.** Which category of the safety legend does the intent
+   fall into?
+   - `read-only` — never mutates disk, config, or remote state
+   - `mutating` — installs, updates, removes, or writes durable state
+   - `diagnostic` — long-running or interactive (TUI, GUI, watch, daemon
+     serve); user judgement is the main side effect
+2. **Inspect before acting.** Run `primekit <cmd> --help` for the intended
+   subcommand. For **read-only** scripted work also pass
+   `--json --no-interactive` so the response is a versioned envelope
+   (`schema_version`, `kind`, `data`) that can be parsed instead of scraped.
+   **Never** pass `--no-interactive` or `--yes` to a mutating command
+   without explicit user approval — those flags suppress the confirmation
+   prompt that is the only human gate before disk mutation.
+   For human diagnostics, use `--verbose` on a safe read-only reproduction or
+   the next authorized invocation. Never repeat a mutating command solely for
+   diagnostic detail; inspect partial state and confirm the retry first.
+   `--quiet` overrides `--verbose`; `--verbose` does not change the typed JSON
+   envelope.
+3. **Confirm scope.** Where does this command act?
+   - Project scope: current working tree; changes live under the project.
+   - User/global scope: `~/.claude`, `~/.agents`, `~/.codex`, or the
+     equivalent adapter home; changes affect every project.
+   - Kit installation source (embedded vs remote registry vs local path).
+   - Adapter/delivery mode (native emission vs plugin package). See the
+     runtime support matrix before claiming a capability is active on any
+     harness.
+4. **Prefer status / inspect before lifecycle mutation.** Before `primekit update`,
+   `primekit kit refresh`, `primekit self-update`, `primekit uninstall`, or `primekit recover`, run
+   the corresponding read-only path: `primekit doctor`, `primekit kit list-kits`,
+   `primekit kit validate`, `primekit skill verify`, `primekit plan status`, `primekit sessions
+   list`, `primekit backups list`, `primekit diagnostics export`, etc. Preview conflicts
+   instead of guessing. **Snapshot before mutate:** before `primekit recover`,
+   `primekit backups restore`, `primekit uninstall`, or any command combined with
+   `--fresh`, first run `primekit backups create` (or confirm a current backup
+   with `primekit backups list`) so the mutation is reversible.
+5. **Preserve unknown files.** PrimeKit mutates only paths it owns. Never
+   suggest `--force` combined with `--fresh`; never propose a destructive
+   reset unless the user has explicitly asked. Surface a conflict; do not
+   silently overwrite.
+6. **Never run destructive commands against real maintainer state.** For
+   installer/refresh/recovery smoke tests, use a fresh temporary home and
+   set every applicable env var: `AGENTKIT_HOME`, `AGENTKIT_CLAUDE_HOME`,
+   `CODEX_HOME`, cache/config/transcript/project paths. See
+   [`docs/operations/implementation-smoke.md`](../../../../docs/operations/implementation-smoke.md).
+7. **Report the exact command, scope, and result.** Include the resolved
+   `--json` envelope where relevant. Name what changed on disk and any
+   unresolved constraint (e.g. "matrix says cursor is production but the
+   local install claims it as spike").
+
+## Command families by task
+
+Names below are the *task category*; the full command list with
+classifications is in
+[`references/command-reference.md`](./references/command-reference.md).
+Use the appendix to find the exact command, then `primekit <cmd> --help` for
+flags.
+
+- **Bootstrap and setup** — start here for a new project or a new machine.
+  `primekit init`, `primekit new`, `primekit setup`. All `mutating`. Confirm intended kit and
+  scope first.
+- **Kits** — install, refresh, validate, and remove kits.
+  `primekit kit init|install|refresh|validate|uninstall|list-kits|repair-install-mode`.
+  `primekit kit list-kits` and `primekit kit validate` are read-only; the rest mutate.
+- **Skills** — inventory and per-skill environment.
+  `primekit skills list|show|search|install|remove|graph` for the inventory;
+  `primekit skill install|remove|repair|upgrade|verify` for one skill.
+- **Agents, content, commands** — mirror the skills shape.
+  Reads (`list`, `show`, `search`), writes (`install`, `remove`), and one
+  domain-specific mutating action per group.
+- **Plans and journals** — file-first plan and journal management. `primekit plan
+  list|show|status|search|validate|resolve|parse` are read-only. `primekit plan
+  create|check|uncheck|add-phase|update|use|archive|close|reindex|migrate`
+  mutate the plan store or plan files. `primekit plan kanban` is a diagnostic
+  TUI. `primekit journal list|show|validate` read; `primekit journal create` writes.
+- **Diagnostics** — `primekit doctor`, `primekit activity`, `primekit audit`, `primekit sessions`,
+  `primekit analytics`, `primekit backups`, `primekit versions`, `primekit changelog`,
+  `primekit diagnostics export`. Nearly all read-only; enable/disable/delete
+  under `analytics` and `content-search` are mutating.
+- **Recovery** — `primekit recover`, `primekit backups restore`. Always confirm scope
+  and preview before invoking; both are mutating and irreversible without
+  a prior `primekit backups create`.
+- **Watch / daemons** — `primekit watch start|stop|status|dry-run`,
+  `primekit content schedule daemon`, `primekit codex-agent-runtime serve`,
+  `primekit api start|stop|status`, `primekit config start|stop|status`. Long-running
+  processes; `start` classifies as diagnostic, `stop` as mutating (it kills
+  the process), `status` and `dry-run` as read-only.
+- **Config, auth, and MCP** — `primekit config prefs
+  resolve|set|unset|validate`, top-level auth commands (`primekit login`,
+  `primekit logout`, `primekit whoami`, `primekit licenses`), and `primekit mcp
+  add|link|list|remove|show|verify`. Writes here reach user-scope
+  state; verify scope before invoking. Note: auth commands are
+  top-level, not under an `primekit auth` parent.
+- **Selfupdate and migrations** — `primekit self-update`, `primekit migrate
+  prefs|rollback`. Always run `primekit versions` and check `primekit changelog`
+  before invoking; keep the installed skill copies in mind (see
+  source-of-truth clause below — the binary can advance without the
+  skill copies moving).
+
+## Maintaining this skill
+
+When an `primekit` CLI command is added, removed, renamed, reparented, or changes
+flags, scope, mutation behavior, or output, consider activating
+`pk:skill-creator`. Update this skill when the change affects its operating
+guidance, command classifications, examples, or safety rules. Regenerate
+`references/command-reference.md` with `make skill-ref`; never hand-edit it.
+Run `make skill-ref-check` to fail closed on stale output or unclassified
+commands.
+
+## Source-of-truth clause (do not remove)
+
+The generated appendix carries a version stamp. If it lags behind
+`primekit --version`, treat the appendix as a **starting hint** and re-check
+flags with `primekit <cmd> --help` before any mutating call. `primekit self-update`
+advances the binary independently of installed skill content, so version
+skew is normal after self-update and before the next `primekit update` refresh.
+
+Never rely on the appendix's flag list for a mutating command. The
+authoritative surfaces, in order:
+
+1. `primekit <cmd> --help` (always current for the running binary)
+2. `primekit <cmd> --json` output (versioned envelope, parseable)
+3. `references/command-reference.md` (starting index, may lag)
+
+## Anti-patterns
+
+- Do **not** combine `--force` with `--fresh` on any lifecycle command.
+- Do **not** run installer, refresh, migration, uninstall, or destructive
+  smoke tests against real maintainer state. Set a temp home per
+  [`docs/operations/implementation-smoke.md`](../../../../docs/operations/implementation-smoke.md).
+- Do **not** invent flags not present in `primekit <cmd> --help`. The Cobra
+  metadata is authoritative; if the flag is not there, it is not shipped.
+- Do **not** treat a source-only capability as active in the installed
+  binary. Confirm via `primekit versions` or `primekit doctor`.
+- Do **not** infer adapter capability from another adapter. Check
+  `docs/conformance/runtime-support-matrix.yaml` and adapter output.
+- Do **not** hand-edit the appendix at `references/command-reference.md`;
+  regenerate via `make skill-ref`.
+- Do **not** report a mutating command's outcome without the resolved
+  scope. "Installed the engineer kit" is not enough — say project vs
+  global, adapter, and any conflict skipped.
+
+## Reference
+
+- [`references/command-reference.md`](./references/command-reference.md) —
+  auto-generated command index with classifications, regenerated by
+  `make skill-ref`. Fail-closed drift gate: `make skill-ref-check`.
+- Runtime support matrix: `docs/conformance/runtime-support-matrix.yaml`
+  (owner of adapter capability truth).
+- Temp-home discipline: `docs/operations/implementation-smoke.md`.
+- Owner-locked packaging model: repo root `CLAUDE.md` §"Owner-locked kit
+  packaging and installation safety".