cue-ai 0.3.0

package/resources/skills/skills/meta/skill-suggestion/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: skill-suggestion
+description: >-
+  Use when user says "find a skill", "which skill", or "suggest skill". Catalog lookup, matching existing skills, avoiding duplicates.
+---
+
+# skill-suggestion
+
+You are PROACTIVE. The user doesn't ask for this skill — you load it when you spot a pattern they should automate. Then you make ONE concise suggestion and stop.
+
+## When to load this skill
+
+Load when ANY of these is true:
+
+- **Repetition observed.** The user has just performed the same multi-step workflow ≥2 times in this session, or you're about to do it for the 2nd time.
+- **Skill mismatch.** You manually executed something an existing skill (visible in your skills list) could have handled in one call.
+- **Reusable pattern emerged.** A non-trivial workflow just succeeded and the user is likely to want it again (e.g. a deploy sequence, a debug recipe, a setup procedure).
+- **The user explicitly says** "should this be a skill", "automate this", "next time", "I keep doing X", or "/skill-suggestion".
+
+## When NOT to load
+
+- The user is asking a one-off question (just answer it).
+- The task is a single tool call (no automation value).
+- You already suggested a skill this session for the same pattern (don't nag).
+- The user explicitly waved off a prior suggestion.
+- The pattern is highly user-specific and lives better as a Justfile recipe than a skill — suggest the recipe instead.
+
+## What to do once loaded
+
+### Step 1 — Identify the pattern in one sentence
+
+Write down the workflow you observed, like:
+- "User ran `pnpm install && pnpm build && rsync ...` to deploy storefront — 2nd time this session."
+- "User manually walked through 4 SQL inserts to seed Medusa products."
+- "User asked DNS-related questions; spent 3 turns navigating Hostinger UI."
+
+If you can't compress it to one sentence, you don't have a clear pattern — abort.
+
+### Step 2 — Search for an existing skill
+
+**Use the local catalog first — it's pre-indexed and zero-latency.**
+
+```bash
+# Catalog file: ~/Documents/soul/skills/catalog/catalog.json
+# Refreshed via: just refresh-catalog
+# Quick search across installed + upstream + mcps:
+just catalog-search <keyword>
+```
+
+If the catalog is stale (`generated_at` more than ~24h old per `just catalog-stats`), refresh it first: `just refresh-catalog`. The refresh hits GitHub for `anthropics/skills`, `obra/superpowers`, `wshobson/agents`, and any other repos in `soul/skills/catalog/known_repos.json`.
+
+Search order within the catalog:
+
+1. **`installed`** — already loaded into Claude Code / Codex. If matched, the user just needs to invoke (or YOU should have invoked it). Surface the existing skill name + trigger phrase.
+2. **`upstream`** — exists in a trusted repo but not adopted yet. Surface the name + repo URL; offer to adopt via `soul`.
+3. **`mcps`** — sometimes the right answer is an MCP server, not a skill (stateful APIs, persistent connections).
+4. **Wider GitHub** — only if catalog has no match: `gh search code 'filename:SKILL.md <keyword>'`. If the result is from a publisher you trust, suggest adding the repo to `known_repos.json` so future searches see it.
+
+### Step 3 — Decide which path
+
+| Finding | Action |
+|---------|--------|
+| Existing skill, already loaded | "FYI — `<name>` skill handles this; next time say <trigger phrase>." |
+| Existing skill in `soul/`, not synced | "Found `<name>` in soul/, run `~/Documents/soul/skills/scripts/install-local.sh` to activate." |
+| Upstream skill exists | Show the URL + one-line summary. Ask if they want to adopt via `soul` skill (which knows the upstream-first rule). |
+| Nothing exists | Offer to scaffold via `soul`. Sketch the proposed `name`, `category`, `description` triggers. Ask before writing. |
+| Better as Justfile recipe | Suggest adding to `~/Documents/Justfile` instead. Skills are for *behavior*; Justfile is for *commands*. |
+
+### Step 4 — Format the suggestion
+
+Keep it ≤4 lines. Pattern:
+
+```
+💡 Suggestion: This looks repeatable. <Found-X | Should-create-Y>.
+   • <one-line action> (e.g. "say `/<name>` next time" or "I can scaffold `meta/<name>` — confirm?")
+   • <opt-out phrase> (e.g. "or 'skip' to ignore")
+```
+
+Then **stop**. Don't argue, don't elaborate. The user will either accept, ignore, or wave you off.
+
+## Anti-nag rules
+
+- **One suggestion per pattern per session.** If the user ignored it, don't bring it up again until next session.
+- **Don't suggest during interrupts.** If the user is mid-task and the suggestion isn't blocking, defer to end-of-task.
+- **Don't suggest the trivial.** A 1-line bash command isn't a skill candidate. A 1-line Justfile recipe might be.
+- **Skill > Justfile recipe** when the operation needs LLM reasoning (parse output, decide branch). **Justfile > skill** when it's pure deterministic command sequence.
+- **Skill > MCP** for prompts/workflows. **MCP > skill** for stateful tool surfaces (databases, APIs, persistent connections).
+
+## When the user says "yes, scaffold it"
+
+Hand off to the `soul` skill. Don't write SKILL.md files yourself — `soul` knows the canonical paths, frontmatter rules, and the upstream-first procedure.
+
+## When the user says "yes, install upstream"
+
+For Anthropic's `anthropics/skills` repo or community catalogs:
+
+1. `git clone <repo> /tmp/<name>-source`
+2. `cp -r /tmp/<name>-source/<skill-path> ~/Documents/soul/skills/skills/<category>/<name>/`
+3. Add `Source: <upstream URL>@<commit-sha>` line at the top of the body
+4. Trigger sync: `~/Documents/soul/skills/scripts/install-local.sh`
+
+Use the `soul` skill's procedure — it documents the canonical layout.
+
+## Calibration — when in doubt, don't suggest
+
+False positives erode the user's trust in the suggestion. Skip the suggestion if:
+
+- You're <70% sure the pattern is repeatable
+- The user's intent is unclear
+- The "automation" would replace a step the user wants to retain manual control over (e.g. destructive operations)
+
+Better to miss a suggestion than fire a bad one.
+
+## Sister tooling
+
+- **`find-skills`** — REACTIVE counterpart. User-initiated lookups. Don't compete; defer to it when the user explicitly asks.
+- **`soul`** — scaffolds the new skill once the user agrees.
+- **`workspace-recipes`** — alternative target when the answer is a Justfile recipe, not a full skill.
+- **`note --priority`** — if the user wants to remember a workflow but isn't ready to skill-ify it yet.

package/resources/skills/skills/meta/smithery-usage/SKILL.md

@@ -0,0 +1,68 @@
+---
+description: "When user asks about finding, installing, or managing MCP servers via Smithery marketplace, guide them through smithery CLI and cue marketplace commands"
+tags: [meta, smithery, mcps, marketplace]
+category: meta
+version: 1.0.0
+requires_mcps: []
+---
+
+# Smithery — MCP Marketplace
+
+Smithery is the largest MCP registry (100K+ tools). Use it to discover and connect MCP servers.
+
+## Via cue (recommended)
+
+```bash
+cue marketplace search "web search"       # search everything
+cue marketplace search-mcps "database"    # MCPs only
+cue marketplace install-mcp exa           # install + add to profile
+cue marketplace list-mcps                 # show connections
+cue marketplace find-tools "search web"   # find tools by intent
+```
+
+## Direct Smithery CLI
+
+```bash
+smithery mcp search "github"              # search registry
+smithery mcp add exa --id exa             # connect (remote)
+smithery mcp add <id> --client claude     # add to Claude Desktop
+smithery mcp list                         # list connections
+smithery mcp remove <id>                  # disconnect
+smithery tool list <connection>           # list tools
+smithery tool find <connection> "query"   # search tools
+smithery tool call <conn> <tool> '{}'     # invoke a tool
+smithery auth whoami                      # check auth
+```
+
+## Popular MCPs
+
+| ID | Uses | Description |
+|---|---|---|
+| `exa` | 28K | Web search + page fetching |
+| `brave` | 13K | Brave web search |
+| `context7` | 11K | Up-to-date library docs |
+| `github` | 4K | GitHub repos, issues, PRs |
+| `googledrive` | 6K | Google Drive files |
+| `jina` | 5K | AI search + read pages |
+| `parallel/search` | 6K | High-accuracy web search |
+| `Tavily` | 3.8K | AI-optimized web search |
+| `docfork/docfork` | 2.5K | Docs from GitHub repos |
+| `LinkupPlatform/linkup-mcp-server` | 2.9K | Real-time web search |
+
+## Workflow: Add an MCP to your profile
+
+1. Search: `cue marketplace search-mcps "what you need"`
+2. Install: `cue marketplace install-mcp <qualifiedName>`
+3. Reload: `/cue-reload` (restarts Claude with new MCP)
+
+## Remote vs Local MCPs
+
+- **Smithery MCPs** run remotely on `server.smithery.ai` — no local process
+- **Local MCPs** (in `resources/mcps/`) run on your machine
+- Both work in cue profiles; Smithery MCPs need internet
+
+## Tips
+
+- Use `--json` flag for machine-readable output
+- `smithery tool call` lets you test MCPs without Claude
+- Connect multiple MCPs and search across all with `smithery tool find`

package/resources/skills/skills/meta/smithery-usage/test/case-1.md

@@ -0,0 +1,5 @@
+---
+input: "smithery usage"
+expect_contains: ["smithery"]
+expect_not_contains: []
+---

package/resources/skills/skills/meta/soul/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: soul
+description: >-
+  Use when user says "/soul", "new soul skill", "create soul skill", or "scaffold a skill". Creates soul skills/MCPs under ~/Documents/soul with correct taxonomy.
+---
+
+# soul
+
+The soul/ tree is the user's personal toolbox of skills and MCP catalog
+entries that get loaded into every Claude Code / Codex session via
+`install-local.sh` symlinks into `~/.claude/skills/` and `~/.codex/skills/`.
+
+This skill keeps soul/ tidy. When the user wants a new skill or a new MCP
+entry, this skill writes the file in the **correct category folder** with
+the **correct frontmatter shape**, so the sync timer picks it up cleanly
+on the next fire.
+
+## Canonical paths
+
+```
+~/Documents/soul/skills/skills/<category>/<name>/SKILL.md   ← skill
+~/Documents/soul/mcps/mcps/<name>/README.md                 ← MCP catalog
+~/Documents/soul/mcps/mcps/<name>/skills.md                 ← related skills
+```
+
+After writing, the next sync fire (every 15 min via systemd timer, or
+end of a Claude Code turn via Stop hook) runs `install-local.sh` which
+symlinks the new skill into `~/.claude/skills/<name>` and
+`~/.codex/skills/<name>`. The user does not need to do anything else.
+
+## Skill categories
+
+Pick the closest fit. If nothing matches, ask the user before creating
+a new category — `meta/` is the safe fallback for cross-cutting tooling.
+
+| Category | When to use |
+|---|---|
+| `caveman` | Token-compression style/communication tweaks |
+| `colony` | Multi-agent coordination, file claims, handoffs |
+| `content` | Content generation (writers, copy, marketing) |
+| `deployment` | Coolify, Hostinger deploy, infra automation |
+| `design` | UI/UX, visual systems, brandkit, image-gen, design tokens |
+| `github` | `gh` CLI, PRs, CI/Actions, repo automation |
+| `higgsfield` | Higgsfield image/video gen specifics |
+| `hostinger` | Hostinger-specific APIs (DNS, VPS, billing, hosting, reach) |
+| `medusa` | Medusa ecommerce backend/storefront/admin |
+| `meta` | Meta-tooling: this skill, doctor, plan, hud, skill manager |
+| `obsidian` | Obsidian vault tooling, markdown, bases, canvas |
+| `orchestration` | Multi-mode runners: autopilot, ralph, ralplan, team, ulw |
+| `private` | User-private skills (don't publish) |
+| `research` | Research/scrape: autoresearch, defuddle, keyword research |
+| `review` | Code review, security review, slop cleanup |
+| `stripe` | Stripe-specific (webhooks, billing, Connect, subscriptions) |
+
+## SKILL.md frontmatter template
+
+```markdown
+---
+name: <kebab-case-name>
+description: >-
+  Use when user says "<trigger 1>", "<trigger 2>", "/<name>", or wants <verb>
+  <object>. <One sentence describing what it does>. NOT for <when not to use>
+  — use <other-skill> instead.
+---
+
+# <Title Case Name>
+
+<One paragraph: the why and the what.>
+
+## When to use
+
+- "<exact trigger phrase>"
+- <another phrasing>
+
+## When NOT to use
+
+- <out-of-scope case>
+
+## How
+
+<the actual instructions Claude follows>
+```
+
+Description-field rules (these matter — the skill listing is matched
+against this string by every model on every turn):
+- Lead with `Use when user says ...` and list the exact trigger phrases
+- Phrase from the user's mouth, not the skill's mouth
+- Include `/<name>` as a slash-trigger if the skill is also user-invocable
+- End with `NOT for ...` so the model has a negative anchor to disambiguate
+- Keep under 400 chars for context efficiency
+
+## MCP catalog entry template
+
+`soul/mcps/mcps/<name>/README.md`:
+
+```markdown
+# <name> MCP
+
+Source URL: <github / npm URL>
+
+Install command:
+
+\`\`\`sh
+<one-liner that installs the binary>
+\`\`\`
+
+Expected command/type:
+
+\`\`\`text
+command: <bin or runtime>
+args: <args>
+type: stdio | http | sse
+\`\`\`
+
+Required env vars:
+
+\`\`\`text
+<VAR_NAME>
+\`\`\`
+
+Related skills:
+
+\`\`\`text
+<skill-name>
+\`\`\`
+
+Quick health check:
+
+\`\`\`sh
+<one-liner that probes the server>
+\`\`\`
+```
+
+Optional sibling: `soul/mcps/mcps/<name>/skills.md` — long-form notes on
+skill bundling, prompt patterns, integration tips.
+
+## Workflow
+
+When invoked, follow this order:
+
+1. **Identify intent.** Skill, MCP catalog entry, or both? If ambiguous, ask.
+2. **Collect inputs.** Either ask explicitly or extract from the user's
+   message:
+   - Skill: `name` (kebab-case), `category` (from list above), description
+     fragments (triggers, what-it-does, not-for), short body.
+   - MCP: `name`, source URL, install command, expected command/args/type,
+     env vars, related skills.
+3. **Pick the category.** Match against the table above. If multiple apply,
+   prefer the most specific one. If none match, ask the user before
+   inventing a new category — categories are durable.
+4. **Search upstream FIRST — don't reinvent.** If the skill is for a tool,
+   library, framework, or open-source repo (`just`, `pnpm`, `playwright`,
+   `stripe`, `medusa`, `obsidian-cli`, etc.), check whether someone has
+   already written a canonical SKILL.md before authoring one yourself.
+   See **Upstream-first rule** below for the exact procedure. Only proceed
+   to step 5 with an upstream skill (adopted) or after confirming none
+   exists.
+5. **Check for collisions.** Does `soul/skills/skills/<category>/<name>/`
+   already exist? Does `soul/mcps/mcps/<name>/` already exist? If yes, ask
+   whether to update vs. rename.
+6. **Write the file.** Use the template above; do not invent extra fields.
+   Description goes in frontmatter; everything else in body.
+7. **(Skill only) Verify the frontmatter.** `description` must start with
+   `Use when user says` and include at least 3 trigger phrases.
+8. **Don't run install-local.sh manually.** The systemd timer fires every
+   15 min and the Claude Code Stop hook fires at end of turn. Either path
+   picks the new skill up. Tell the user the new skill will be live within
+   15 min, or they can force it with:
+
+   ```sh
+   ~/Documents/soul/skills/scripts/install-local.sh
+   ```
+
+9. **Tell the user the path.** Always echo the absolute path of the file
+   you wrote so they can review.
+
+## Upstream-first rule
+
+**Don't reinvent a SKILL.md when the community already wrote one.** A
+hand-rolled local skill drifts from upstream wisdom and accumulates
+quirks; an adopted upstream skill stays current and benefits from other
+people's bug reports.
+
+### When to apply
+
+Any skill whose subject is a **tool / library / framework / open-source
+repo** that has its own community. Examples: `just`, `pnpm`, `git`,
+`playwright`, `stripe`, `obsidian-cli`, `medusa`, `coolify`, `supabase`,
+`docker`. NOT for skills that are inherently personal-workflow
+(`workspace-recipes`, `colony-prompts`, `soul`, `note`, `hud`) — those
+have no upstream.
+
+### Procedure
+
+1. **Search GitHub (in this order):**
+   - The tool's own repo for `SKILL.md`, `AGENTS.md`, `CLAUDE.md`, or a
+     `skills/` directory at root or under `docs/`.
+     ```
+     gh search code 'filename:SKILL.md' --repo <owner/tool>
+     ```
+   - GitHub-wide search for community SKILL.md files matching the tool name:
+     ```
+     gh search code 'filename:SKILL.md <tool-name>' --limit 20
+     ```
+   - Anthropic-published skills (highest authority for the agentic-skill
+     format): `gh search repos --owner anthropics skills`
+   - Awesome-skills lists / model-context-protocol repos.
+
+2. **Decide what to adopt:**
+   - **Full match** (skill exists, fits the user's intent): copy the body
+     verbatim, add a `Source:` line near the top pointing at the upstream
+     URL + commit SHA. Keep the upstream's wording — don't paraphrase.
+   - **Partial match** (skill exists but covers a different scope): adopt
+     the body, then add an explicit "Local additions" section at the
+     bottom for anything the user actually needed. Don't merge inline.
+   - **No match**: write from scratch using the template above. Note in a
+     code comment near the top that no upstream was found, so the next
+     person doesn't redo the search.
+
+3. **Keep upstream and local concerns separate.** When the upstream skill
+   describes the tool generally and the user has personal recipes/configs,
+   create TWO skills:
+   - `meta/<tool>/SKILL.md` — adopted upstream, generic
+   - `meta/workspace-<tool>/SKILL.md` (or `<category>/workspace-...`) —
+     user's specific recipes, with the upstream skill as a "see also"
+     reference
+
+   Precedent: `meta/just/SKILL.md` (upstream `just` reference) +
+   `meta/workspace-recipes/SKILL.md` (user's `~/Documents/Justfile`).
+
+4. **Re-pull periodically.** Note the upstream commit SHA in the `Source:`
+   line. When the user says "refresh skills" or "update <tool> skill",
+   diff against latest upstream and merge changes.
+
+### Anti-pattern
+
+Don't copy the upstream skill and silently rewrite half of it to match a
+local opinion. Either adopt cleanly with attribution, or write a separate
+`workspace-<tool>` skill that *complements* the upstream — never both
+sneakily merged.
+
+## Naming rules
+
+- **Skill names:** `kebab-case`, ASCII only, ≤30 chars. Match the directory
+  name to the `name` field in frontmatter (the harness expects this).
+- **MCP catalog names:** match the registered MCP name (`mcpServers.<key>`
+  in `~/.claude.json` or `~/.codex/config.toml`).
+- **Avoid plurals.** `colony` not `colonies`. `review` not `reviews`.
+- **Avoid the word "skill"** inside skill names. Just describe what it does.
+
+## What NOT to do
+
+- Don't write outside the canonical paths. Skills live under
+  `soul/skills/skills/<category>/<name>/`, not at the soul root or in
+  `~/.claude/skills/` directly (those are managed by `install-local.sh`).
+- Don't create a new category without asking the user first.
+- Don't auto-publish or auto-push. The Stop hook + 15-min timer handle
+  that — staying out of the way avoids races and double-commits.
+- Don't add fields beyond `name`/`description` to skill frontmatter unless
+  the user explicitly asks (e.g. `argument-hint` for slash-command skills).
+
+## Sister tooling
+
+- `meta/skill` — the OMX skill manager (CRUD for `~/.codex/skills/`). Use
+  it when the user wants to *manage existing skills*; this skill is for
+  *creating new ones in soul/*.
+- `meta/plugin-creator` — codex plugin scaffolder. Different scope: that
+  builds plugin packages with `marketplace.json`, this builds simple
+  SKILL.md files in soul/.

package/resources/skills/skills/meta/upgrade-stack/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: upgrade-stack
+description: "Use when user says 'upgrade my stack', 'update plugins', 'upgrade claude-mem', 'reapply patches', 'check for updates', or after a claude-mem plugin upgrade. Runs claude-stack-doctor.sh to upgrade bun/npm/cargo globals and re-apply --smol patches. NOT for Claude Code itself — that's manual."
+---
+
+# upgrade-stack — keep the Claude Code stack current
+
+User's box runs a stack with **local patches** that get wiped by plugin upgrades. The tool `~/.local/bin/claude-stack-doctor.sh` automates upgrade + re-patch in one go.
+
+## When to use
+
+- After `/plugin update` inside Claude Code (rebuilds plugin cache → wipes my --smol patches)
+- Weekly maintenance (`claude-stack-doctor --check` to see what's outdated)
+- When user says "upgrade stack" / "update everything" / "check for updates"
+- When a fresh claude-mem version directory appears (e.g. 13.3.0 alongside 13.2.0)
+
+## How to use
+
+```bash
+# Diagnose only, no changes:
+claude-stack-doctor.sh --check
+
+# Upgrade everything + re-apply patches:
+claude-stack-doctor.sh
+
+# Just re-apply patches (fast, idempotent — use after a manual /plugin update):
+claude-stack-doctor.sh --patches-only
+
+# Quiet (only failures + actual changes printed):
+claude-stack-doctor.sh -q
+```
+
+## What it does
+
+1. **bun globals** (`bun upgrade` + `bun update -g`) — picks up new gbrain, rtk if bun-installed, etc.
+2. **npm globals** — reports outdated but does NOT auto-upgrade `@anthropic-ai/claude-code` (restart-sensitive).
+3. **cargo globals** — if `cargo-install-update` is present, runs `cargo install-update -a`. Otherwise notes how to install it.
+4. **RTK** — reports current version; upgrade path varies (brew on mac, cargo/bun on Linux).
+5. **claude-mem --smol patches** — finds latest version directory, re-applies the 3-file patch suite if missing. Idempotent — running twice is a no-op.
+
+## What it does NOT do
+
+- **Won't upgrade Claude Code itself.** That kills active sessions. User runs `npm i -g @anthropic-ai/claude-code` manually when ready.
+- **Won't run `/plugin update`.** That's an interactive Claude Code command; only the user inside a session can run it.
+- **Won't kill running daemons.** New `--smol` settings only apply to *new* claude-mem worker spawns. To force-recycle the daemon: `pkill -f worker-service.cjs` — it respawns on next SessionStart hook.
+
+## After running
+
+If patches were freshly applied, tell user:
+> Patches applied. Inside any Claude Code session, the running claude-mem daemon is still on the *old* (non-patched) code. To pick up `--smol`:
+> `pkill -f worker-service.cjs` — the next SessionStart hook will respawn it.
+
+If `claude-mem` version directory changed (e.g. 13.3.0 just appeared), confirm patches landed in the new dir:
+```bash
+grep -l 'BUN_NO_SMOL\|LOCAL PATCH' ~/.claude/plugins/cache/thedotmack/claude-mem/<NEW_VERSION>/scripts/*.{js,cjs}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "CANNOT PATCH (anchor not found)" | Upstream `claude-mem` rewrote the file beyond recognition | Manual review of `~/.claude/plugins/cache/thedotmack/claude-mem/<ver>/scripts/`; consult §7 of `~/Documents/claude-code-setup-prompt.md` for the original patch sites |
+| `cargo-install-update missing` | Optional cargo-update tool not installed | `cargo install cargo-update` if user wants cargo globals auto-upgraded |
+| `bun update -g` errors | Network or registry issue | Check `bun pm ls -g` for the problem package, upgrade individually |
+
+## Related
+
+- See memory `project-memory-tuning` for the full reasoning behind `--smol`.
+- See memory `project-skill-layout` for the broader skill / plugin convention on this machine.
+- `/plugin update` inside Claude Code is the interactive companion to this tool — they're complementary.

package/resources/skills/skills/meta/workspace-recipes/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: workspace-recipes
+description: >-
+  Use when user says "spawn a new shop", "new medusa shop", "clean disk", "agent tree", or "rebuild colony cli". Workspace-specific recipes from ~/Documents/Justfile. For generic `just` syntax use the `just` skill.
+---
+
+# workspace-recipes — `~/Documents/Justfile`
+
+Workspace-level recipes the user maintains in `~/Documents/Justfile`. Run any of these from anywhere via `cd ~/Documents && just <recipe>`. The Justfile uses absolute paths internally so `cwd` doesn't matter.
+
+For the underlying `just` tool itself (discovery flags, syntax), see the `just` skill.
+
+## Recipes
+
+### Medusa shops
+
+| Command | What it does |
+|---------|--------------|
+| `just new-shop NAME` | Spawn a new Medusa shop from `medusa-shops/base-template/` — copies dir, `git init`, copies `.env.example` → `.env` for backend + storefront, runs `pnpm install`. After: edit the two `.env` files, then `just shop-backend NAME`. |
+| `just shop-backend SHOP` | `pnpm --filter backend dev` in the shop |
+| `just shop-storefront SHOP` | `pnpm --filter storefront dev` in the shop |
+| `just shop-build-storefront SHOP` | `pnpm hostinger:build && pnpm hostinger:finalize:static` — produces `dist/client/` ready to upload to `<shop>.hu` Hostinger document root |
+
+### Disk / cleanup
+
+| Command | What it does |
+|---------|--------------|
+| `just clean` | Wipes ALL `node_modules`, `.next`, `dist`, `build`, `target`, `.turbo`, `.venv` across the workspace. Reports before/after `df`. Run `pnpm install` (or equivalent) per project to restore. **Recovered 35 GB the first time.** |
+| `just clean-dry` | Same find, no delete — shows what would go |
+| `just disk` | Top 20 largest dirs (depth 3) |
+| `just df` | Free / used space on `/home` |
+
+### Docs / soul
+
+| Command | What it does |
+|---------|--------------|
+| `just agent-tree` | All `AGENTS.md` / `CLAUDE.md` across the workspace |
+| `just skills` | List skill categories under `soul/skills/skills/` |
+| `just mcps` | List MCP servers under `soul/mcps/mcps/` |
+
+### Recovery
+
+| Command | What it does |
+|---------|--------------|
+| `just colony-rebuild` | `pnpm install && pnpm --filter colonyq build` in `recodee/colony/`. Run this if the colony Stop/SessionStart hooks start failing with `Cannot find module '/home/deadpool/Documents/recodee/colony/apps/cli/dist/index.js'` — usually after `just clean` wipes `dist/`. |
+
+## When to invoke
+
+- User asks to "spawn / create / start a new (medusa) shop" → `just new-shop NAME`
+- User asks to "clean / free disk space / wipe node_modules" → `just clean-dry` first to confirm scale, then `just clean`
+- User asks to "show disk usage" → `just disk` then `just df`
+- User asks to "list / find AGENTS.md" → `just agent-tree`
+- User asks to "fix colony hook" or sees the colony Cannot-find-module error → `just colony-rebuild`
+
+## Reading the Justfile
+
+Always check `~/Documents/Justfile` for the canonical, current recipe list — recipes get added over time. `just --list --unsorted` from any directory inside `~/Documents/` shows the menu.
+
+## Caveats
+
+- Recipes assume cwd is somewhere under `~/Documents/`; they `cd` to absolute paths internally so safe to invoke from anywhere.
+- `just clean` is destructive but reversible — the categories it wipes are listed in `~/Documents/.gitignore` and are all rebuildable from source.
+- `just new-shop` requires `pnpm` installed and assumes the `base-template/` is up to date.