@mutmutco/hermes-plugin 3.139.1

package/skills/secrets/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: secrets
+description: Manage the full own-project vault and granted org-infra secret names.
+---
+
+**Host-native invocation:** Claude `/mmi:secrets` · Codex `$mmi:secrets` · jervcode/Kimi `/skill:secrets` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /secrets — two-tier project secrets
+
+**Authority:** a project-admin self-serves their own product repo's full vault tree (`mmi-cli oracle org access
+role` → `project-admin` + `train`): stageless, `dev`, `rc`, and `main`. Do not redirect them to master for
+an own-project coordinate. Only org-infra grants and cross-project administration stay master-only.
+
+Secrets in the org split by **blast radius + who manages them** (not by storage — both tiers are SSM
+SecureString + KMS, and **a value is never echoed to chat or logs**):
+
+- **YOUR REPO** — `/mmi-future/<slug>/<KEY>` (the stageless canonical) plus
+  `/mmi-future/<slug>/{dev,rc,main}/*` (staged per-stage overrides) for a repo you are project-admin of.
+  You **self-serve your own repo's full tree** — the canonical root, dev, rc, AND main prod secrets — via
+  `/secrets`, on your **GitHub role alone**, no AWS, no waiting on the master (#2032).
+- **ORG-INFRA** — the shared/infra namespaces (`/mmi-future/{shared,cloudflare,docs,mmi-hub}/*`), at
+  **every** tier (their `dev/` holds Hetzner/AWS/CF tokens + Hub tooling). **Crown jewels, master-only.**
+  A project-admin reaches one of these only via a master **grant**; the master is unrestricted (master ⊇
+  project-admin).
+
+**Grant scope (#3652).** A grant is `rw` by default — it opens both keyless `use` and `set`/`rm` on that
+key. `mmi-cli vault secrets grant <repo> <login> <key> --read` grants **consume-only** reach: keyless `use`
+works, rotate and remove still refuse. Only a `--read` grant may name a **wildcard** key — `*` for the
+whole namespace, `<provider>/*` for one provider group — so "may read every crown jewel" is one grant
+instead of forty. A wildcard never confers write; asking for one as `rw` is refused, not narrowed.
+`mmi-cli oracle org access capabilities` prints `grant (read)` or `grant (rw)` next to each name.
+
+A bare `<KEY>` is the **stageless canonical** at the slug root — one value every stage shares (#2244)
+and the path deploys resolve (#2523). A staged `dev/<KEY>` is a **per-stage override** and WINS for that
+stage at deploy (#2522); `set`/`use` warn (names only) when an override shadows the canonical. The
+`dev`/non-`dev` `tier` field in older JSON is compatibility metadata, not an authority boundary: an
+own-project `main/SECRET_KEY_BASE` or `rc/DB_URL` remains project-admin self-service.
+
+**Declare-first (#2528):** the registry catalog is the SSOT; SSM is a projection of it. A `set` to a
+coordinate not declared in the catalog is **rejected** — the error names the attempted path and the fix.
+Declare the key first via `mmi-cli oracle org project set <owner/repo> --secrets-file <catalog.json>` (`stages: []`
+= the shared stageless canonical, `stages: ["dev"]` = a per-stage override), then retry. See what is
+declared with `mmi-cli vault secrets catalog` or `secrets list`; ask for a key you lack via `mmi-cli vault secrets
+request <KEY>`. There is no master bypass. `rm` of an undeclared path stays allowed, so cleanup keeps
+working. Google OAuth is one stageless pair per repo: bare `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`
+at the slug root (the staged `{dev,rc,main}/GOOGLE_*` shape is retired; `org oauth set-creds` writes the
+bare keys).
+
+All ops run through `mmi-cli vault secrets …`, which calls the org backend with the caller's `gh` token; the
+backend re-verifies **project-admin-of-this-repo** and the **vault namespace** server-side and does the scoped
+SSM op. This skill never touches AWS.
+
+## Step 0 — orient
+
+Read the current repo + slug; the tier of a key follows from its name (above). `secrets list` shows what
+exists and which ones **you** can manage (a `*`), never values.
+
+```bash
+mmi-cli vault secrets list                 # names + tier + a * on the ones you can write. NEVER values.
+```
+
+`secrets: no registry META` or `Hub API unreachable` → the repo is not registered with the Hub, GitHub auth
+is missing, or the Hub API is unavailable. Run `mmi-cli oracle org project get <owner/repo>` to distinguish those cases;
+a master-admin backfills the registry before secrets can be resolved.
+
+## Step 1 — the verb
+
+Default to the **current repo**; pass `--repo owner/Name` to target another (you must be its project-admin).
+
+```bash
+# CONSUME a secret keyless — injected into the command's env, NEVER printed (raw `secrets get` was
+# removed, the floor wins, #2844):
+mmi-cli vault secrets use SCRAPER_API_KEY -- <cmd>
+
+# Write / rotate — the VALUE is read from stdin, NEVER an argument (so it can't leak into shell history
+# or process args). Pipe it in:
+printf %s "$THE_VALUE" | mmi-cli vault secrets set SCRAPER_API_KEY
+
+# Validate a known provider key without printing its value:
+mmi-cli vault secrets verify RECALL_API_KEY
+
+# Remove:
+mmi-cli vault secrets rm SCRAPER_API_KEY
+```
+
+**Never** pass a value as an argument (`secrets set KEY thevalue` is wrong — there is no value arg). The
+confirmation prints the **name and tier only**, never the value.
+
+## Rotation checklist
+
+Before rotating, enumerate every copy of the key so no tier stays stale:
+
+```bash
+mmi-cli vault secrets list --repo owner/Repo
+```
+
+Check the bare canonical plus any `dev/`, `rc/`, `main/` overrides the list shows. Rotate the provider-side
+key first, then write every declared coordinate that still needs that key. For keys with a provider probe
+(`RECALL_API_KEY` today), `secrets set` validates the new value before printing success; `secrets verify
+<KEY>` repeats the same probe later without printing the value. If the verifier fails, treat the rotation as
+incomplete even if the vault write itself succeeded.
+
+## Step 2 — org-infra elevation (master-only)
+
+Your own repo's full tree (dev/rc/main) is already self-serve (#2032). The **org-infra** namespaces
+(`shared`/`cloudflare`/`docs`/`mmi-hub`, every tier) stay master-only. A project-admin who needs one of
+those keys asks the master, who grants a **scoped, auditable** standing access to that one key (or revokes
+it). These verbs are **master-only** — the backend 403s anyone else.
+
+```bash
+# MASTER: let @oguz-mut consume one _org provider key from their MM-Chat project
+mmi-cli vault secrets grant mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+# MASTER: withdraw it
+mmi-cli vault secrets revoke mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+```
+
+The master can also operate the org-infra key directly while guiding (master ⊇ project-admin). Org-infra
+access by a project-admin **always originates from the master** — own-project access does not.
+
+## Coordinate — where does a new project secret belong?
+
+- Shared across stages → bare `<KEY>` at the project slug root (the usual canonical value).
+- Genuinely stage-distinct → `<stage>/<KEY>` override for `dev`, `rc`, or `main`.
+- The project-admin owns both shapes across their own project. A path under `_org`/shared infrastructure is
+  not a project coordinate and stays master-managed.
+
+## Tier-to-tier copy (provider keys, #1433)
+
+**Encryption / stage-distinct keys** (`*_ENC_KEY`, `SECRET_KEY_BASE`, etc.) must be **generated per stage** —
+never copied. **Provider sandbox keys** (e.g. Recall/Gemini for Katip dev/rc) **may** be shared across dev/rc
+when they point at the same sandbox project; prod should stay distinct when the provider contract requires it.
+
+Sanctioned copy within the own-project vault (org-infra/cross-project sources remain master-gated):
+```bash
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY,GEMINI_API_KEY
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY --dry-run   # plan only
+```
+Prefer this over manual copy piping — audit-logged, blocklist enforced.
+
+## Notes
+
+- **Never echo a value** — not in chat, a commit, a log, or an issue. No command emits a value to stdout;
+  consume one keyless with `secrets use <KEY> -- <cmd>` (#2844). Treat every secret as write-once.
+- Authority is **GitHub**: project-admin = repo `write` plus the registry `projectAdmins` entry, master =
+  org owner. The backend checks both with the org App token, so the decision is server-side (your token
+  scope can't widen it).
+- Runtime consumes declared keys through its scoped broker token (and central deploy injects the declared
+  stage set without a repo `.env`); CI reads keylessly through its OIDC role. Neither uses raw `/secrets`
+  output. `secrets use <KEY>` is the safe local command-consumption path.
+- Every self-service write is **attributable** — the backend logs actor + repo + KEY name (never the value).
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. a canonical-name or tier mix-up, or a step
+that risked echoing a value.) If yes, file **one** lesson and move on; a clean run is silent (hard cap:
+one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR — never edit the
+skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli learning skill-lesson --skill secrets --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/stage/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: stage
+description: Run a local test stage, or a personal cloud dev stage with --live.
+---
+
+**Host-native invocation:** Claude `/mmi:stage` · Codex `$mmi:stage` · jervcode/Kimi `/skill:stage` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /stage — local test environment
+
+A throwaway **local** environment to exercise the current branch — a dev server / local stack, plus
+Playwright or other tools where the project uses them. It is **off the promotion train**: any developer,
+no version effect, no deploy. It lives in a **gitignored** workspace, **force-kills the previous stage**
+before starting, and **auto-decommissions** when done.
+
+Use `/stage` as the normal path for local previews, smoke tests, and Playwright targets. If the user
+already asked to run or preview the app, that is enough authorization to start it; when intent is unclear,
+ask before creating or destroying a stage. Manual dev-server commands are allowed when the user explicitly
+wants a bypass or when a bounded diagnostic needs one, but say why. If the stage path itself fails, diagnose
+from `mmi-cli stage --json`, `tmp/stage/state.json`, process/port/container evidence, and file Hub/org-default
+friction instead of silently working around it.
+
+The stage recipe is the **registry-derived default** for plumbing-free product repos: a `tenant-container`
+repo that ships `docker-compose.yml` and has a Hub registry `portRange` needs **no committed config**.
+`mmi-cli stage` derives a default compose stage — run `docker compose build --no-cache`, run `docker compose
+up -d`, choose a free port from the registry range, and report the local URL (e.g. `http://127.0.0.1:3700/`).
+The commands are shell-aware and `--apply` runs them cross-shell. Board, deploy, secret, and project registry
+facts all live in the Hub registry — no repo-local control-plane file.
+
+**Secrets are vault-native — no `.env` on disk (#2655).** The org forbids *using* `.env` files, not just
+committing them. A repo **without** `.env.example` stages vault-native: `mmi-cli stage --apply` resolves the
+declared dev runtime secrets (registry `requiredRuntimeSecrets[dev]`) from the vault and injects them straight
+into the compose **process environment** — the compose file reads them via `environment:` passthrough, and no
+secret ever touches disk. A repo that still ships `.env.example` keeps the legacy `.env` bootstrap for
+back-compat until its compose migrates to passthrough; new repos should ship **no** `.env.example`.
+
+## Step 0 — inspect the plan
+
+```bash
+mmi-cli stage --json
+```
+
+The JSON reports `source` (`derived` / `local` / `none`) and, when derived, the local `url`. `source: none`
+means neither a usable local recipe nor a derivable default exists — the message names the missing fact
+(deployModel, `docker-compose.yml`, or registry `portRange`; `.env.example` is **not** required — #2655).
+That gap does not mean the repo's Hub registry/org project setup is missing.
+
+## Step 1 — run the stage
+
+A stage is **per worktree**. The CLI force-stops only the previous stage **in this worktree**, runs
+`stage.build`, starts `stage.up`, records `tmp/stage/state.json`, picks a free port from the registry
+range (skipping ports reserved by sibling worktrees), and polls `stage.healthUrl` when configured.
+Use `--port` to pin a port when needed:
+
+```bash
+mmi-cli stage run --apply
+mmi-cli stage run --apply --port 5180
+```
+
+Use a larger bound when the repo's local stack is known to be slow:
+```bash
+mmi-cli stage run --apply --timeout-ms 120000
+```
+
+All stage artifacts (build output, screenshots, Playwright traces, local DB files) stay under `tmp/stage/`
+— never tracked.
+
+A local stage is bound to the worktree that started it. Concurrent worktrees on one machine each keep
+their own stage on separate ports — you do not need to stop one before starting another. For `jervaise`, continuity
+keys on branch; use a distinct North Star slug per parallel grind or feature. Stage JSON/state records
+the starting `cwd` plus git branch/commit when available.
+
+### Step 1a — post-smoke panel (when criteria exist)
+
+When grinding or the user supplied **acceptance criteria** (from the issue body at Gate 1 — not
+ad-hoc chat text), run a **Budget-routing panel** on observable stage signals before teardown:
+
+1. **Panel** (parallel):
+   - **requirements-match** (budget tier) — does the staged URL/behavior meet the criteria?
+   - **runtime-health** (budget tier) — console errors, failed `healthUrl`, broken UI signals
+     *(smoke observability — not the grind `correctness` hard lens)*
+   - **tests-actually-test** (budget tier) — if Playwright ran, did it exercise the changed path?
+2. **Confirm** — get an independent second model to verify the staged URL or behavior meets the acceptance criteria.
+3. Feed the result back to the active loop or report to the human. A blocker
+   means the stage failed smoke — do not claim the grind criterion met.
+   This panel is **not** a security clearance — grind Phase 2 still runs the `security` hard lens.
+
+Skip when `/stage` is ad-hoc preview with no criteria.
+
+## Step 2 — stop when done
+
+```bash
+mmi-cli stage stop --apply
+```
+
+Stop the stage when the work is done, before switching context, or before replacing it with another stage.
+If the user clearly wants the preview to stay up, leave it running and report that. The next `/stage` also
+stops the previous recorded stage before starting, so a stale server does not linger between runs. For the
+registry-derived Docker Compose default, stop also runs the recorded compose teardown (`docker compose down`)
+from the original stage working directory.
+
+## /stage --live — personal cloud dev stage
+
+dev.x stages are **not standing environments**: without `--live` the dev stage is dark. `--live`
+deploys the **current branch** to the project's dev runtime and serves it **only to your public IP** —
+gated at the **Cloudflare edge** (#1761). The CLI detects your IP, dispatches the central
+`tenant-deploy.yml` (stage=dev), then `tenant-control.yml` `cf-gate-allow` (an ephemeral Cloudflare WAF
+rule scoped to your dev host + IP). The box no longer IP-gates dev. No SSH from your machine; everything
+moves through the central workflows.
+
+```bash
+mmi-cli stage --live           # dry-run plan
+mmi-cli stage --live --apply   # deploy + gate your IP at the Cloudflare edge
+```
+
+Tear it down when done — the runtime stops and the Cloudflare edge gate is removed:
+
+```bash
+mmi-cli stage --live --down --apply
+```
+
+Personal dev stages only — rc/live environments still move exclusively through the promotion train.
+
+## Step 3 — report
+
+The stage URL, what's running (server + tools), the workspace path (`tmp/stage/`), and the teardown command.
+
+## Notes
+
+- `/stage` is local — no AWS, no deploy, no board or version effect. The one cloud exception is
+  `--live`: an on-demand **dev** stage of your branch, gated to your IP at the Cloudflare edge (above).
+- Remote rc/live environments move only through `/rcand`, `/release`, and `/hotfix`.
+- Everything is gitignored; `/stage` never produces a tracked change.
+- **Playwright MCP output goes to `tmp/`**, never the repo root: if you drive the Playwright MCP server,
+  pass `--output-dir tmp/playwright-mcp` (or point its output there). `.playwright-mcp/` is kept gitignored
+  by the org `.gitignore` managed block (`mmi-cli doctor`) as a safety net, so a stray default capture is
+  never tracked.
+- `tools[]` is declarative for now; stage hardening starts/stops the main configured process. Repos with
+  extra local services should encode them behind `stage.up` until a tool runner is added.
+- **Stale Docker bundle:** the registry-derived Docker Compose default builds with `docker compose build
+  --no-cache` before `up`. If the browser still serves an old bundle, run `mmi-cli stage stop --apply`, rerun
+  `/stage`, then inspect `tmp/stage/state.json` identity, container image labels, and compose build inputs.
+- **Stale `.env`:** when `.env` already exists from a prior `/stage` run, `stage run` does **not** refresh it
+  from an updated `.env.example` — it warns on stderr and keeps the stale file. Delete `.env` (or merge in the
+  new keys by hand) when `.env.example` changes, then re-run `/stage`.
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. a teardown that left a port bound, or a
+Playwright output path aimed at the repo root.) If yes, file **one** lesson and move on; a clean run is
+silent (hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR —
+never edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli learning skill-lesson --skill stage --title "<what misfired>" --body "<what; evidence; proposed amendment>"`