cue-ai 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recodee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# cue — Agent Profile Manager for Claude Code & Codex
+
+> Pick a profile. Launch with the right skills, MCPs, and plugins. Nothing else.
+
+`cue` is a CLI that sits between your shell and the agent binary. Type `claude` or `codex` and `cue` intercepts: it resolves which profile applies in the current directory, materializes an isolated `CLAUDE_CONFIG_DIR` (or `CODEX_HOME`) with just that profile's skills, MCP servers, and Claude Code plugins, then exec's the real agent. Per-directory pins mean the right loadout follows the project, not the terminal session.
+
+## Why cue?
+
+- **Per-profile isolation.** Skills, MCP servers, and Claude Code plugins are scoped to the active profile. Marketing work doesn't see frontend's MCPs; backend doesn't see design's skills. No more "every session has every tool" overload.
+- **Directory-aware.** Pin a profile to a directory (`.cue-profile`), and every `claude` / `codex` you launch from inside boots with that loadout automatically. No flag wrangling.
+- **Composable.** Profiles inherit from a `core` baseline so cross-session memory (claude-mem) and meta skills are shared by default. Add team-wide tools in one place.
+- **Pre-launch picker.** First time you type `claude` in a fresh directory, a TUI picker opens. Pin or one-shot — your choice.
+- **Materialized, hash-short-circuited.** Each launch rebuilds the runtime only when the resolved profile actually changed. Cold-start cost is a stat + sha256 compare.
+- **No service to run.** No daemon, no background process, no auto-update. Just a Bun CLI and a shim script in `~/.local/bin`.
+
+## Repo layout
+
+- `profiles/` — one directory per profile; a YAML decides what loads. Inheritance chains depth-3, agents=[claude-code|codex] scoping per resource.
+- `resources/skills/` — local skill library composed into profiles. Source for the `skills/local:` field.
+- `resources/mcps/` — MCP server configs (`claude.sanitized.json`, `codex.sanitized.json`) composed into profiles.
+- `plugins/cue/` — the Claude Code plugin shipping `/cue`, `/cue switch`, `/cue reload`, `/cue current` slash commands.
+- `src/` — the Bun CLI itself: `commands/`, `lib/{cwd-resolver,picker,runtime-materializer,...}`.
+- `setup/` — per-OS install prompts you can paste into an agent session.
+- `docs/` — `launch.md` (hot-path flow), `shell-install.md` (shim install + PATH), `superpowers/specs/` (design + plans).
+
+License: [MIT](./LICENSE).
+
+---
+
+## Install (one line)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash
+```
+
+This installs bun (if needed), clones the repo to `~/Documents/cue`, and runs the interactive installer.
+
+**Options:**
+
+```bash
+# Non-interactive (auto-yes)
+curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash -s -- --yes
+
+# Custom install location
+CUE_DIR=~/dev/cue curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash
+```
+
+**Or clone manually:**
+
+```bash
+git clone https://github.com/recodeee/cue.git ~/Documents/cue && ~/Documents/cue/install.sh
+```
+
+`install.sh` is interactive: it installs the `claude` shim by default and asks before touching `codex` (in case you already have a wrapper there). Non-interactive variants:
+
+```bash
+~/Documents/cue/install.sh --yes           # install claude shim, skip codex prompt
+~/Documents/cue/install.sh --yes --codex   # install both shims (clobbers existing codex on PATH)
+~/Documents/cue/install.sh --uninstall     # remove the symlinks, leave the repo
+```
+
+### What the installer does
+
+1. Verifies `git` and `bun` (Bun ≥ 1.0; install from https://bun.sh)
+2. Runs `bun install` inside the repo
+3. Self-checks `bin/cue --version`
+4. Symlinks `~/.local/bin/cue` → `<repo>/bin/cue`
+5. Checks that `~/.local/bin` is on your `$PATH` (warns if not)
+6. Writes the `~/.local/bin/claude` shim (and optionally `codex`)
+
+Idempotent. Safe to re-run on any machine that already has cue installed.
+
+### After install
+
+```bash
+cd ~/projects/q4-launch-campaign
+echo marketing > .cue-profile
+claude          # boots with the marketing profile's skills, MCPs, and plugins
+```
+
+See [docs/launch.md](./docs/launch.md) for the resolve → materialize → exec flow.
+
+---
+
+## Quick install — pick your OS (legacy soul flow)
+
+Two paths per OS:
+
+- **Direct** — copy a shell block, paste in a terminal, runs the install end-to-end.
+- **Agent-driven** — paste the corresponding `setup/<os>.md` into Claude Code as your first message; it walks you through the phases interactively (recommended if you've never set this up).
+
+The shell blocks below trigger GitHub's "copy" button when you hover over them on github.com — one click to clipboard.
+
+### macOS
+
+Open **Terminal** (⌘+Space → "Terminal"), paste, run once:
+
+```bash
+# 1. Homebrew
+[ -x "$(command -v brew)" ] || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+# 2. Core tools
+brew install bun node@22 python@3.12 uv jq rtk
+# 3. Claude Code
+curl -fsSL https://claude.ai/install.sh | sh
+# 4. RTK token-savings hook
+rtk init -g
+echo "Setup complete. Run:  claude  — then paste setup/macos.md as your first message."
+```
+
+→ Full agent-driven prompt: **[setup/macos.md](./setup/macos.md)** (paste into Claude Code)
+
+### Linux (Ubuntu / Debian / Fedora / Arch)
+
+```bash
+# 1. System packages
+if   command -v apt    >/dev/null; then sudo apt update && sudo apt install -y curl git jq build-essential python3 python3-pip
+elif command -v dnf    >/dev/null; then sudo dnf install -y curl git jq @development-tools python3 python3-pip
+elif command -v pacman >/dev/null; then sudo pacman -S --noconfirm curl git jq base-devel python python-pip
+fi
+# 2. Bun
+[ -x "$(command -v bun)" ] || curl -fsSL https://bun.sh/install | bash
+export PATH="$HOME/.bun/bin:$HOME/.local/bin:$PATH"
+# 3. uv (Python venv manager)
+[ -x "$(command -v uv)" ] || curl -LsSf https://astral.sh/uv/install.sh | sh
+# 4. RTK
+[ -x "$(command -v rtk)" ] || (curl -fsSL https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /tmp && sudo install /tmp/rtk /usr/local/bin/rtk)
+# 5. Claude Code
+curl -fsSL https://claude.ai/install.sh | sh
+rtk init -g
+echo "Setup complete. Run:  claude  — then paste setup/linux.md as your first message."
+```
+
+→ Full agent-driven prompt: **[setup/linux.md](./setup/linux.md)**
+
+### Windows 10 / 11 (PowerShell)
+
+Open **PowerShell**. First-time only:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+Then:
+
+```powershell
+# 1. Core tools via winget
+winget install --id OpenJS.NodeJS.LTS  --silent --accept-source-agreements --accept-package-agreements
+winget install --id Python.Python.3.12 --silent --accept-source-agreements --accept-package-agreements
+winget install --id stedolan.jq        --silent --accept-source-agreements --accept-package-agreements
+winget install --id Git.Git            --silent --accept-source-agreements --accept-package-agreements
+$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+# 2. Bun + uv
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) { irm bun.sh/install.ps1 | iex }
+if (-not (Get-Command uv  -ErrorAction SilentlyContinue)) { irm https://astral.sh/uv/install.ps1 | iex }
+# 3. Claude Code via npm
+npm install -g @anthropic-ai/claude-code
+# 4. RTK
+if (-not (Get-Command rtk -ErrorAction SilentlyContinue)) {
+    Invoke-WebRequest -Uri "https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-pc-windows-msvc.zip" -OutFile "$env:TEMP\rtk.zip"
+    Expand-Archive -Path "$env:TEMP\rtk.zip" -DestinationPath "$env:USERPROFILE\.local\bin" -Force
+}
+rtk init -g
+Write-Host "Setup complete. Run:  claude  — then paste setup/windows.md as your first message."
+```
+
+→ Full agent-driven prompt: **[setup/windows.md](./setup/windows.md)**
+
+(WSL2 user? Use the Linux block inside your WSL distro instead — cleaner.)
+
+---
+
+## Optional — Parallel agents tier (Colony + gitguardex)
+
+If you want to run **2+ Codex/Claude agents in parallel on the same repo** without them stomping on each other, layer this tier on top of the lean stack:
+
+- **[recodeee/gitguardex](https://github.com/recodeee/gitguardex)** — `gx` CLI. Per-agent branch + worktree isolation, file locks, PR-only merges.
+- **[recodeee/colony](https://github.com/recodeee/colony)** — Local-first MCP for fleet coordination. Replaces 30k-token repo handoffs with ~400-token compact state in SQLite at `~/.colony`. Auto-detects file claims, task graphs, and prior decisions so agents see ownership before editing.
+
+→ Full setup prompt: **[setup/parallel-agents.md](./setup/parallel-agents.md)** (Linux + macOS; Windows via WSL2)
+
+Skip this tier if you only ever run one Claude Code window at a time — claude-mem + gbrain are enough for solo work.
+
+---
+
+## How it works
+
+Typing `claude` or `codex` in a repo where cue's shims are installed triggers the launch flow:
+
+1. **Resolve** — cue checks for a `.cue-profile` file in the current directory (or any parent up to `$HOME`). If none is found, it falls back to a repo-level default, a global default, or opens the TUI picker.
+2. **Materialize** — cue builds `~/.config/cue/runtime/<profile>/{claude,codex}/` with a content-addressed hash check. If the profile hasn't changed, this is a no-op.
+3. **Exec** — the real `claude` or `codex` binary is launched with `CLAUDE_CONFIG_DIR` (or `CODEX_HOME`) pointing at the materialized runtime tree.
+
+The shims are a one-time install: `cue shell install`. See **[docs/launch.md](./docs/launch.md)** for the full resolve-precedence rules and bypass paths.
+
+---
+
+## Profiles
+
+Profiles keep each Claude Code or Codex session lean by materializing only the skills and MCPs needed for the current job.
+
+```bash
+cue list
+cue use medusa-dev
+cd profiles/medusa-dev/workspace && claude
+```
+
+Each profile carries an emoji icon shown in the picker:
+
+```
+🐻 backend         APIs, webhooks, security review, CI, package, …
+🦋 frontend        Frontend UI implementation, redesign, screenshots, …
+🦜 marketing       Marketing — copywriting, SEO, CRO, growth, …
+🦉 research        Source-backed lookup, extraction, market research
+🐺 fleet-control   Multi-agent orchestration, Colony, OMX, gx
+🦚 creative-media  Image, video, brand, visual generation
+🐝 docs-writer     Markdown, PDF, Obsidian, structured writing
+🐆 caveman-quick   Fast low-context edits, summaries, reviews
+🦄 full            Diagnostic profile — every local skill + MCP
+🐢 core            Shared baseline (claude-mem, meta skills, …)
+```
+
+Pick or change an icon: `cue icon <profile>` (interactive emoji picker).
+
+The active profile is also stamped at the top of the materialized `CLAUDE.md`,
+so `/goal` inside Claude Code shows which profile is loaded.
+
+### Saving the current session as a profile
+
+From any Claude Code session, ask: *"save this as a profile"*. The
+`meta/save-profile` skill walks you through the steps and calls
+`cue create-profile` to write the YAML:
+
+```bash
+cue create-profile my-project \
+  --icon "🦊" \
+  --description "My project work" \
+  --skills design/ui-ux-pro-max,research/find-skills \
+  --pin
+```
+
+### Multi-account flow (with authmux)
+
+If you keep separate Claude/Codex accounts (e.g. via `authmux`), point each
+alias at its own `CLAUDE_CONFIG_DIR`:
+
+```bash
+alias claude-account2="CLAUDE_CONFIG_DIR=$HOME/.claude-accounts/account2 cue launch claude"
+```
+
+cue detects the pre-set config dir, copies `.credentials.json` and merges the
+account's `settings.json` into the materialized runtime, and **always shows
+the picker** with the previously-pinned profile on top — so you can pick a
+different profile per session without losing the auth.
+
+Start with the docs hub at **[docs/profiles/](./docs/profiles/)** for the schema, inheritance model, scan-to-profile flow, and troubleshooting.
+
+---
+
+## For AI agents
+
+If you are an AI coding agent helping a human set this up, read **[AGENTS.md](./AGENTS.md)** first — it explains the bootstrap contract (phase-by-phase, ask-before-network, verify-each-step) and points to the per-OS prompt your user should paste.
+
+---
+
+## What you get
+
+After bootstrap (~550 MB cold RAM per session):
+
+| Layer | What it does |
+|---|---|
+| **claude-mem** plugin | Captures session observations passively; `mem-search "topic"` to recall across sessions |
+| **caveman** plugin | `/caveman` for terse replies, `/caveman-commit` for Conventional Commit messages |
+| **RTK** (CLI hook) | Filters shell-command outputs — 60-90% token savings on `ls` / `git` / `cat` |
+| **gbrain** MCP | Personal knowledge wiki with embeddings, backlinks, timeline |
+| **excel-mcp-server** | Native `.xlsx` read/write/format |
+| **office-word-mcp-server** | Native `.docx` read/write |
+
+claude-mem (passive) and gbrain (manual wiki) are complementary — both recommended.
+
+---
+
+## What's inside the repo
+
+```
+cue/
+├── skills/         110+ Claude Code / Codex skills
+│   ├── medusa/     building-with-medusa, storefront-best-practices, …
+│   ├── codex-fleet/  bringup, dispatch, supervisors, panes, troubleshoot
+│   ├── higgsfield/   generate, marketplace-cards, soul-id
+│   ├── caveman/      caveman, caveman-commit, caveman-compress
+│   └── ...
+├── mcps/           MCP server snapshots + configs
+│   ├── configs/    claude.sanitized.json, codex.sanitized.json, …
+│   ├── mcps/       individual MCP server entries
+│   └── plugins/    Claude Code plugin snapshots
+└── setup/          paste-into-Claude-Code prompts (macos.md, linux.md, windows.md)
+```
+
+---
+
+## Contributing
+
+Each skill is a folder with `SKILL.md` (frontmatter + body) plus reference files. The frontmatter `description` is what the LLM matches against — write it as `"when user says X, do Y"`.
+
+To add a new skill: copy an existing one as a template, edit `SKILL.md`, drop it under `skills/skills/<category>/<slug>/`. The catalog regenerates on the next sync.

package/bin/README.md

@@ -0,0 +1,32 @@
+# bin/
+
+The `soul` CLI lives here. Bun-based (consistent with the macOS/Linux setup
+flow). Subcommand dispatch only — actual logic is in `bin/cli/lib/`.
+
+## Layout
+
+```
+bin/
+├── soul                 # bash launcher → `bun bin/cli/index.ts "$@"`
+└── cli/
+    ├── index.ts         # entrypoint, dispatches to commands/
+    ├── commands/        # one file per `soul <subcommand>`
+    └── lib/             # profile loader, resolvers, materializers
+```
+
+## Subcommands (planned)
+
+| Command             | Purpose                                                          |
+|---------------------|------------------------------------------------------------------|
+| `soul use <name>`   | Materialize a profile into CWD (or `--global` into ~/.claude/)   |
+| `soul list`         | List profiles with skill/MCP counts and active marker            |
+| `soul new <name>`   | Create a profile; `--from-scan` buckets discovered skills        |
+| `soul scan`         | Print a tree of installed skills/plugins grouped by domain       |
+| `soul doctor`       | Diff declared profile vs actual disk state; `--fix` repairs      |
+| `soul validate`     | Schema + lint checks for one profile (or `--all`)                |
+| `soul init-shell`   | Generate `claude-<profile>` aliases for zsh/bash/pwsh            |
+
+Exit codes:
+- `0` — success
+- `1` — user error (bad args, missing profile)
+- `2` — internal error

package/bin/cue

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# cue — launcher for the Bun-based CLI.
+# Resolves its own location so the script works from any cwd and through symlinks.
+
+set -euo pipefail
+
+# Resolve symlinks until we get the real path of this script.
+src="${BASH_SOURCE[0]}"
+while [ -h "$src" ]; do
+  dir="$(cd -P "$(dirname "$src")" && pwd)"
+  src="$(readlink "$src")"
+  [[ "$src" != /* ]] && src="$dir/$src"
+done
+CUE_BIN_DIR="$(cd -P "$(dirname "$src")" && pwd)"
+CUE_REPO_ROOT="$(cd -P "$CUE_BIN_DIR/.." && pwd)"
+
+export CUE_REPO_ROOT
+# Backward compat
+export SOUL_REPO_ROOT="$CUE_REPO_ROOT"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "cue: bun is required but was not found in PATH" >&2
+  echo "     install from https://bun.sh and re-run" >&2
+  exit 2
+fi
+
+exec bun "$CUE_REPO_ROOT/src/index.ts" "$@"

package/bin/medusa-dev

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# medusa-dev — run multiple Medusa shops side-by-side without port collisions.
+#
+# Reads ~/Documents/medusa-shops/.dev-ports.yaml as the source of truth.
+# Each shop gets a deterministic backend port + storefront port from that file.
+#
+# Usage:
+#   medusa-dev list                     # show registry + which ports are live now
+#   medusa-dev start <shop> [back|front|both]   # default: both
+#   medusa-dev stop  <shop> [back|front|both]
+#   medusa-dev tail  <shop> [back|front]        # tail the log
+#   medusa-dev status                   # what's running across all shops
+#   medusa-dev cors-fix <shop>          # set STORE_CORS/AUTH_CORS to a regex
+#                                       # that allows any http://localhost:PORT
+#
+# Logs go to ~/.cache/medusa-dev/<shop>.<back|front>.log
+# Pidfiles to ~/.cache/medusa-dev/<shop>.<back|front>.pid
+
+set -euo pipefail
+
+REGISTRY="${MEDUSA_DEV_REGISTRY:-$HOME/Documents/medusa-shops/.dev-ports.yaml}"
+WORKSPACE="${MEDUSA_DEV_WORKSPACE:-$HOME/Documents}"
+CACHE="$HOME/.cache/medusa-dev"
+mkdir -p "$CACHE"
+
+err()  { printf '\033[31m%s\033[0m\n' "$*" >&2; }
+info() { printf '\033[36m%s\033[0m\n' "$*" >&2; }
+ok()   { printf '\033[32m%s\033[0m\n' "$*" >&2; }
+
+# Parse the YAML using inline python3 (always available on the user's machine).
+# Returns a TSV: shop<TAB>path<TAB>backend_port<TAB>storefront_port<TAB>framework<TAB>notes
+registry_tsv() {
+  python3 - "$REGISTRY" <<'PY'
+import sys, re
+path = sys.argv[1]
+with open(path) as f: txt = f.read()
+
+# Tiny YAML walker — no PyYAML dependency. Handles the flat 2-level shape
+# only: `shops:` then `<name>:` with indented `key: value` children.
+out, cur = [], None
+def flush():
+    if cur is not None:
+        out.append((cur["name"], cur.get("path",""), cur.get("backend",""),
+                    cur.get("storefront",""), cur.get("framework",""),
+                    cur.get("notes","").strip('"')))
+for raw in txt.splitlines():
+    line = raw.rstrip()
+    if not line.strip() or line.lstrip().startswith("#"): continue
+    if line == "shops:": continue
+    if re.match(r"^  [A-Za-z0-9_.-]+:\s*$", line):
+        flush()
+        cur = {"name": line.strip().rstrip(":")}
+    elif cur is not None and re.match(r"^    [a-z_]+:", line):
+        k,_,v = line.strip().partition(":")
+        cur[k.strip()] = v.strip()
+flush()
+for row in out:
+    print("\t".join(str(c) for c in row))
+PY
+}
+
+# Look up a single shop. Echoes a TSV line, or returns nonzero if not found.
+shop_row() {
+  local name="$1"
+  registry_tsv | awk -F'\t' -v n="$name" '$1==n {print; found=1} END{exit !found}'
+}
+
+# Process status — is the pidfile alive?
+is_alive() {
+  local pidfile="$1"
+  [[ -f "$pidfile" ]] || return 1
+  local pid; pid="$(cat "$pidfile" 2>/dev/null || true)"
+  [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null
+}
+
+# Is a port currently held by *any* process?
+port_held() {
+  ss -lntH "sport = :$1" 2>/dev/null | grep -q LISTEN
+}
+
+cmd_list() {
+  printf "%-16s %-7s %-7s %-7s %-7s %s\n" SHOP BACKEND STATE FRONT STATE PATH
+  while IFS=$'\t' read -r name path back front fw notes; do
+    [[ -z "${name:-}" ]] && continue
+    local bstate fstate
+    if is_alive "$CACHE/$name.back.pid"; then bstate="up"
+    elif port_held "$back"; then bstate="busy"
+    else bstate="-"; fi
+    if is_alive "$CACHE/$name.front.pid"; then fstate="up"
+    elif port_held "$front"; then fstate="busy"
+    else fstate="-"; fi
+    printf "%-16s %-7s %-7s %-7s %-7s %s\n" "$name" "$back" "$bstate" "$front" "$fstate" "$path"
+  done < <(registry_tsv)
+}
+
+cmd_status() { cmd_list; }
+
+# Start one role of one shop.
+start_one() {
+  local shop="$1" role="$2" path="$3" port="$4"
+  local cwd="$WORKSPACE/$path"
+  local pidfile="$CACHE/$shop.$role.pid"
+  local logfile="$CACHE/$shop.$role.log"
+
+  if is_alive "$pidfile"; then
+    info "$shop.$role already running (pid $(cat "$pidfile"))."
+    return 0
+  fi
+  if port_held "$port"; then
+    local owner
+    owner=$(ss -lntpH "sport = :$port" 2>/dev/null | awk -F'"' '{print $2}' | head -1)
+    err "Port $port already in use by '$owner' — won't collide. Stop it or change the registry."
+    return 1
+  fi
+  if [[ ! -d "$cwd" ]]; then
+    err "Path missing: $cwd"
+    return 1
+  fi
+
+  local script
+  case "$role" in
+    back)  script="--filter backend dev" ;;
+    front) script="--filter storefront dev" ;;
+    *) err "unknown role: $role"; return 1 ;;
+  esac
+
+  info "Starting $shop.$role on port $port → $cwd"
+  ( cd "$cwd" && PORT="$port" nohup pnpm $script > "$logfile" 2>&1 & echo $! > "$pidfile" )
+  ok "$shop.$role started (pid $(cat "$pidfile"), log: $logfile)"
+}
+
+cmd_start() {
+  local shop="${1:?shop name required}" which="${2:-both}"
+  local row; row="$(shop_row "$shop")" || { err "unknown shop: $shop"; exit 1; }
+  IFS=$'\t' read -r name path back front _fw _notes <<<"$row"
+  case "$which" in
+    back)  start_one "$shop" back  "$path" "$back"  ;;
+    front) start_one "$shop" front "$path" "$front" ;;
+    both)  start_one "$shop" back  "$path" "$back" || true
+           start_one "$shop" front "$path" "$front" || true ;;
+    *) err "expected back|front|both, got: $which"; exit 1 ;;
+  esac
+}
+
+stop_one() {
+  local shop="$1" role="$2"
+  local pidfile="$CACHE/$shop.$role.pid"
+  if is_alive "$pidfile"; then
+    local pid; pid="$(cat "$pidfile")"
+    info "Stopping $shop.$role (pid $pid)"
+    kill "$pid" 2>/dev/null || true
+    # Give it 5s for graceful, then SIGKILL the whole process group.
+    for _ in 1 2 3 4 5; do kill -0 "$pid" 2>/dev/null || break; sleep 1; done
+    if kill -0 "$pid" 2>/dev/null; then
+      kill -9 -- "-$pid" 2>/dev/null || kill -9 "$pid" 2>/dev/null || true
+    fi
+    rm -f "$pidfile"
+    ok "$shop.$role stopped"
+  else
+    info "$shop.$role not running"
+    rm -f "$pidfile" 2>/dev/null || true
+  fi
+}
+
+cmd_stop() {
+  local shop="${1:?shop name required}" which="${2:-both}"
+  shop_row "$shop" >/dev/null || { err "unknown shop: $shop"; exit 1; }
+  case "$which" in
+    back)  stop_one "$shop" back  ;;
+    front) stop_one "$shop" front ;;
+    both)  stop_one "$shop" back; stop_one "$shop" front ;;
+    *) err "expected back|front|both, got: $which"; exit 1 ;;
+  esac
+}
+
+cmd_tail() {
+  local shop="${1:?shop name required}" role="${2:-back}"
+  local logfile="$CACHE/$shop.$role.log"
+  [[ -f "$logfile" ]] || { err "no log at $logfile"; exit 1; }
+  exec tail -f "$logfile"
+}
+
+# Loosen CORS in a shop's backend .env so any localhost port is accepted.
+cmd_cors_fix() {
+  local shop="${1:?shop name required}"
+  local row; row="$(shop_row "$shop")" || { err "unknown shop: $shop"; exit 1; }
+  IFS=$'\t' read -r name path _back _front _fw _notes <<<"$row"
+  local envfile="$WORKSPACE/$path/apps/backend/.env"
+  [[ -f "$envfile" ]] || { err "no backend .env at $envfile"; exit 1; }
+  cp "$envfile" "$envfile.bak.$(date +%s)"
+  python3 - "$envfile" <<'PY'
+import sys, re
+p = sys.argv[1]
+regex = "^http://localhost:\\d+$"
+with open(p) as f: lines = f.readlines()
+keys = ("STORE_CORS","AUTH_CORS","ADMIN_CORS")
+seen = {k: False for k in keys}
+out = []
+for ln in lines:
+    m = re.match(r"^(STORE_CORS|AUTH_CORS|ADMIN_CORS)=", ln)
+    if m:
+        out.append(f"{m.group(1)}={regex}\n")
+        seen[m.group(1)] = True
+    else:
+        out.append(ln)
+for k, ok in seen.items():
+    if not ok:
+        out.append(f"{k}={regex}\n")
+with open(p, "w") as f: f.writelines(out)
+print("Updated:", ", ".join(seen.keys()))
+PY
+  ok "Backup saved alongside $envfile.bak.<ts>"
+}
+
+usage() {
+  cat <<EOF
+medusa-dev — run multiple Medusa shops side-by-side on stable per-shop ports.
+
+  medusa-dev list                            # show registry + live state
+  medusa-dev status                          # alias for list
+  medusa-dev start <shop> [back|front|both]
+  medusa-dev stop  <shop> [back|front|both]
+  medusa-dev tail  <shop> [back|front]
+  medusa-dev cors-fix <shop>                 # set CORS keys to localhost regex
+
+Registry: $REGISTRY
+Cache:    $CACHE
+EOF
+}
+
+case "${1:-list}" in
+  list|ls)        shift; cmd_list "$@" ;;
+  status)         shift; cmd_status "$@" ;;
+  start|up)       shift; cmd_start "$@" ;;
+  stop|down|kill) shift; cmd_stop "$@" ;;
+  tail|log|logs)  shift; cmd_tail "$@" ;;
+  cors-fix)       shift; cmd_cors_fix "$@" ;;
+  -h|--help|help) usage ;;
+  *) err "unknown command: $1"; usage; exit 1 ;;
+esac

package/bin/soul

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# DEPRECATED — renamed to "cue". This shim forwards all invocations.
+echo "soul: renamed to 'cue'. Update your PATH/alias." >&2
+exec "$(dirname "$0")/cue" "$@"