@mutmutco/codex-plugin 4.3.41 → 4.3.43

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mmi",
-  "version": "4.3.41",
+  "version": "4.3.43",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/codex-plugin",
-  "version": "4.3.41",
+  "version": "4.3.43",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/mmi-help/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: mmi-help
+description: Show a short, human-readable introduction to MMI and its commands.
+---
+
+# MMI help
+
+This is the MMI help command: Claude `/mmi:mmi-help`, Codex `$mmi:mmi-help`, Cursor and JervCode
+`/mmi-help`, or Hermes `skill_view(name='mmi-help')`. These are host skill invocations, not shell
+commands. The distinct name avoids colliding with a host's built-in help command.
+
+Read the [org guide entry](../org-guide/SKILL.md) and
+[getting started](../org-guide/references/getting-started.md). Do not load other topics for general help.
+
+Print a friendly, human-readable **MMI help** card of at most 180 words:
+
+1. Explain that MMI provides the organization's shared tools and working rules.
+2. Show the npm install command, `mmi-hub install`, and the read-only `mmi-hub status` check.
+3. Summarize the essentials: automatic updates, vault/keyless secrets, no repository environment
+   files or personal agent instructions, and approved MMI release workflows.
+4. Name the org-guide skill for details and board, secrets, stage, and release for common tasks.
+   Render invocation syntax for the current host only, using the forms above with the skill name
+   substituted. If the host is unknown, use plain skill names rather than guessing.
+
+For a specific help question, read only its linked guide topic and answer that question instead.
+Explain commands without running them. Help does not install, claim, rotate, provision, or release.
+Do not claim the user's setup is healthy without an actual status result.

package/skills/org-guide/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: org-guide
+description: Read MMI org rules before project work; load only the topic needed.
+---
+
+# MMI organization guide
+
+Read this short entry before MMI project work. Then read **only the topic relevant to the task**;
+do not load the whole guidebook or repeat it in the conversation. For a human introduction, use
+the [MMI help skill](../mmi-help/SKILL.md).
+
+## Essential rules
+
+- Install `@mutmutco/hub` through npm, run `mmi-hub install`, and keep automatic updates enabled.
+  Check actual health with `mmi-hub status`; installation alone is not proof of a working updater.
+- Use the scoped two-tier vault and keyless workflows. Never put secret values in chat, logs,
+  command arguments, or repository environment files.
+- Personal agent instructions and host settings stay local and gitignored in product repositories.
+  Do not commit AGENTS.md, CLAUDE.md, or copied plugin instructions.
+- Claim approved work through the board, use the repository's checks, and land through MMI.
+  A request for help or a plan does not authorize a change or a production release.
+- Read the registry for release tracks, domains, and OAuth configuration. Use MMI provisioning
+  and release workflows rather than inventing parallel deployment or credential paths.
+
+## Read one topic
+
+| Task | Local reference |
+| --- | --- |
+| Install, update, reload, or diagnose tooling | [Getting started](references/getting-started.md) |
+| Work an issue, test, merge, or release | [Work and releases](references/work-and-releases.md) |
+| Consume, declare, rotate, or request a secret | [Vault and keyless access](references/vault.md) |
+| Register domains or configure Google OAuth | [Domains and OAuth](references/domains-and-oauth.md) |
+| Decide what belongs in a product repository | [Repository rules](references/repository-rules.md) |
+
+This is MMI organization guidance, not Jerv or JervCode operating instructions.
+The plugin carries these files locally at its installed release version. Resolve current values
+and exact command flags through the live CLI; a bundled guide is not a live status report.

package/skills/org-guide/references/domains-and-oauth.md

@@ -0,0 +1,31 @@
+# Domains and OAuth
+
+MMI owns the central project registry and provisioning workflows. Read
+`mmi-cli oracle org project get <owner/repo> --json` before changing hostnames or login settings.
+Use the declared edge domains for each stage; do not guess hostnames from a slug or create a
+second DNS/deployment control plane in a product repository. New project setup goes through
+[bootstrap](../../bootstrap/SKILL.md).
+
+Cloudflare owns public DNS and edge TLS. Preserve unrelated records during an authorized change.
+A dev stage is private only after its independent edge-block check succeeds. A configured record
+or successful deployment alone does not prove access control. Use [stage](../../stage/SKILL.md)
+for the supported private live workflow.
+
+## Google OAuth
+
+An eligible project uses one Google web client across local, dev, rc, and main, not one per stage.
+The registry declares OAuth metadata and extra callback paths for additional login/connect flows.
+Generate the current origins and redirects with
+`mmi-cli vault org oauth plan --repo <owner/repo> --json`; do not assemble a copied URI list.
+The plan includes the declared edge hosts, callback paths, and supported loopback redirects.
+
+Client creation and editing are human Google Console actions. Add the planned origins and redirects
+to that client. Store its downloaded credentials through
+`mmi-cli vault org oauth set-creds --repo <owner/repo>` using the file on stdin, never its contents
+in chat or command arguments. Keep credential files outside the repository and remove the temporary
+download after the authorized import. The stored pair is shared across stages through the vault.
+
+Run `mmi-cli vault org oauth verify --repo <owner/repo>` before removing a working redirect.
+Verification probes redirect acceptance; it does **not** inspect registered JavaScript origins.
+Reconcile those against the plan in Console. Check actual authority and use the
+[vault guide](vault.md) for the credential boundary.

package/skills/org-guide/references/getting-started.md

@@ -0,0 +1,28 @@
+# Getting started
+
+Install the maintenance package from npm, then let it install the CLI and supported host plugins:
+
+```bash
+npm install -g @mutmutco/hub
+mmi-hub install
+mmi-hub status
+```
+
+Keep automatic updates enabled. Install converges the tools immediately and enables an hourly
+schedule on supported systems. Status is read-only: it reports installed versions, scheduling,
+the last run, and failures. A missing, unsupported, or failing schedule is not a healthy installation.
+Use `mmi-hub autoupdate on` to enable scheduling and `mmi-hub update` for an immediate update.
+Do not edit plugin caches or installation records by hand.
+
+Complete the host's trust and reload step: reload plugins or restart Claude Code, restart Codex,
+reload the Cursor window, restart JervCode, or start a fresh Hermes process. An existing session
+may still hold the old skill catalog until then. The updater manages the MMI plugin on each
+supported host present on the machine; it does not grant repository or vault access.
+
+Authenticate GitHub for your assigned repository. In its checkout, run `mmi-cli onboard` for
+readiness and `mmi-cli oracle board read` for work. Use `mmi-cli commands --json` to discover routes
+and `mmi-cli explain <command> --json` for exact syntax. Check `mmi-hub status` separately for
+machine-wide updater health.
+
+Ask for **MMI help** for the short introduction or open the [org guide](../SKILL.md) for one topic.
+The guide travels with the plugin on every release; it requires neither a Hub checkout nor wiki access.

package/skills/org-guide/references/repository-rules.md

@@ -0,0 +1,23 @@
+# Repository rules
+
+Product repositories contain product code, tests, and useful product documentation.
+Organization tooling and shared agent workflows come from the MMI plugin.
+Keep project-specific guidance in the README and architecture documents rather than copying
+organization instructions into each repository.
+
+Personal agent instructions and host settings are developer-owned, local, and gitignored.
+The organization ruleset restricts AGENTS.md, CLAUDE.md, GEMINI.md, the .claude, .codex, and .agents
+directories, and .cursor/rules at any depth in covered repositories. Designated distribution-source
+repositories have centrally managed exceptions; a product developer must not invent a bypass.
+Do not force-add ignored files or commit plugin caches to work around delivery problems.
+
+Do not create repository environment files to hold runtime configuration or secrets.
+Use the declared vault and supported [keyless workflows](vault.md), including for local stages.
+Renaming a secrets file or leaving it untracked is not a workaround. A runtime environment injected
+by the deployment system is different from a developer-maintained file in the repository.
+
+Use [bootstrap](../../bootstrap/SKILL.md) to provision organization-owned repository assets and
+rules. Preserve product-owned content when updating managed sections.
+Use `mmi-cli tests policy --base <comparison-base>` and the repository's own checks before landing.
+For tooling repair, `mmi-hub status` reads state and `mmi-hub update` updates installed tooling;
+repository cleanup is a separate, explicit action, not an automatic consequence of asking for help.

package/skills/org-guide/references/vault.md

@@ -0,0 +1,28 @@
+# Vault and keyless access
+
+The two tiers describe authority and blast radius, not separate storage products:
+
+- **Your project:** a project-admin can manage their own product's full vault tree, including
+  shared values and dev, rc, and main overrides. Production-stage names do not by themselves
+  require an organization master-admin.
+- **Organization infrastructure:** shared infrastructure secrets are master-admin managed.
+  Project access requires an explicit grant for the relevant names. A read grant permits
+  consumption, not rotation or deletion; do not assume a grant authorizes every operation.
+
+Read `mmi-cli oracle org access role <owner/repo> --json` and
+`mmi-cli oracle org access capabilities` for your actual authority.
+Installing MMI does not confer that authority. The server checks the caller and target scope.
+
+The registry catalog declares secret names before values are set. A shared, stageless value is
+the canonical default; a declared stage override wins for that stage. Avoid accidental duplicate
+copies that hide a rotation. Use `mmi-cli vault secrets catalog` and `mmi-cli vault secrets list`
+to inspect names and reach, never values.
+
+Consume through `mmi-cli vault secrets use <KEY> -- <command>`: the authorized child receives the
+value at runtime. Do not print it, save it to a repository environment file, paste it into chat,
+or pass it as a command argument. Keyless means using the authorized runtime injection or workload
+identity; developers do not need standing cloud keys to perform supported MMI vault operations.
+
+For declarations, writes, grants, rotation, and verification, read the
+[secrets skill](../../secrets/SKILL.md). Writes take values through stdin, never argv.
+An access denial or failed provider probe is a fact to resolve, not permission to bypass the vault.

package/skills/org-guide/references/work-and-releases.md

@@ -0,0 +1,48 @@
+# Work and releases
+
+Start with `mmi-cli onboard` and the [board skill](../../board/SKILL.md).
+Reading or discussing the board is read-only until the developer authorizes work.
+Claim approved work with `mmi-cli oracle board claim <issue>`, then prepare an isolated task
+workspace through the host. Preserve other developers' work.
+
+Read the issue, implementation, callers, and repository policy before editing.
+Run `mmi-cli tests policy --base <comparison-base>` to determine required checks against your target
+branch (normally origin/development for train repositories). The repository's policy decides, not
+a universal test count. Use its build and check commands.
+Open a PR through `mmi-cli devops pr create` with a closing issue link, and land through
+`mmi-cli devops pr land`. Verify required checks, merge, issue closure, and cleanup before calling
+the implementation complete. A merged implementation is not a production release.
+
+## Choose the declared train
+
+Read `mmi-cli oracle org project get <owner/repo> --json` and `mmi-cli status` for the resolved track.
+The registry and MMI's resolver own the release track and deployment model; do not invent your own
+inference from the repository name or branches that happen to exist. Normal train work targets
+development. A trunk repository follows its single branch and declared workflow instead.
+
+- Full track: development → rc → main. Use [rcand](../../rcand/SKILL.md) to prepare a candidate,
+  then [release](../../release/SKILL.md) for promotion. The release workflow also describes its
+  supported development-source route.
+- Direct track: development → main. Use [release](../../release/SKILL.md); do not invent an rc lane.
+- Trunk track: one main branch, without an rc/development promotion train. Follow the repository's
+  declared publishing workflow rather than manufacturing train branches.
+- Urgent already-merged fixes: use [hotfix](../../hotfix/SKILL.md), which carries selected development
+  fixes directly to main on either track.
+
+Production changes require explicit authorization from the authorized human.
+Read the selected release skill before operating the train. Let it choose versions, run gates,
+publish, deploy, and verify the resulting release. A refusal requires fixing its cause; do not
+finish by hand, bypass checks, or start a duplicate release.
+A release announces itself in Slack: the Hub to the org alerts channel, a product to its own
+project channel when the project vault declares `SLACK_RELEASE_CHANNEL`; never post release notes
+by hand.
+
+For local or private live testing, read [stage](../../stage/SKILL.md).
+For a new product repository, use [bootstrap](../../bootstrap/SKILL.md).
+
+## Keep guidance with the change
+
+When changing organization behavior, update the affected guide topic in the same PR.
+Hub release packaging rebuilds every host's skill tree from the shared source and verifies parity.
+The guide's source-review check requires reviewing a topic when its declared policy inputs change;
+unchanged advice needs no cosmetic rewrite on each version bump.

package/skills/release/SKILL.md

@@ -33,7 +33,7 @@ Read `ready`, then `findings[]`: each carries `code`, `severity` (`blocker` · `
 
 Run from the primary checkout on the lane's start branch (`rc`; `development` for direct-track and `--dev`). Export the bump intent once from the bare argument — `MMI_BUMP_INTENT=minor|major|patch`, unset → `patch`; `MMI_RELEASE_VERSION=X.Y.Z` only for an exact target the tag math cannot derive.
 
-MMI-Hub only: write a fresh 3–6 line neutral summary to `f=$(mktemp tmp/release-summary.XXXXXX)` — sourced from Hub PR titles only (`origin/main..origin/development`), rewritten in Hub-subsystem terms, never a product or brand name. Hub scope is only `mutmutco/MMI-Hub`: never a product's board, `ds-propagate.yml`, or a product's deploy state.
+MMI-Hub only: write a fresh 3–6 line neutral summary to `f=$(mktemp tmp/release-summary.XXXXXX)` — sourced from Hub PR titles only (`origin/main..origin/development`), rewritten in Hub-subsystem terms, never a product or brand name. Hub scope is only `mutmutco/MMI-Hub`: never a product's board, `ds-propagate.yml`, or a product's deploy state. A product repo may pass `--announce-summary-file` too (optional): its notes post to the project's own release channel from the declared `SLACK_RELEASE_CHANNEL` vault key, in that product's own names — with no key declared the announcement is `skipped` and nothing else changes.
 
 ```bash
 r=$(mktemp tmp/release-receipt.XXXXXX)
@@ -41,7 +41,7 @@ mmi-cli devops release --apply --json --out "$r"
 mmi-cli devops release --apply --announce-summary-file "$f" --json --out "$r"     # MMI-Hub
 ```
 
-Add `--dev` for a full-track dev → main release and `--watch` to block on the deploy/publish runs. `mmi-cli devops release --apply --ack <sha>[,<sha>…]` only when the authorized human has verified that a main-only commit the hotfix-coverage guard refused is already in the candidate — never ack to save time. The one command merges, runs the version fold (automatic, inside `mmi-cli devops release --apply`) that bumps the manifests unconditionally before the tag, pushes the tag first (`gate.yml` runs on `v*` tags, so the fold commit earns its required checks), waits for the required contexts, pushes `main`, publishes the Release, dispatches or correlates the deploy (`tenant-deploy.yml` only for tenant-container), announces (Hub), re-syncs project info, and rolls `development` and `rc` forward. Nothing here is done by hand.
+Add `--dev` for a full-track dev → main release and `--watch` to block on the deploy/publish runs. `mmi-cli devops release --apply --ack <sha>[,<sha>…]` only when the authorized human has verified that a main-only commit the hotfix-coverage guard refused is already in the candidate — never ack to save time. The one command merges, runs the version fold (automatic, inside `mmi-cli devops release --apply`) that bumps the manifests unconditionally before the tag, pushes the tag first (`gate.yml` runs on `v*` tags, so the fold commit earns its required checks), waits for the required contexts, pushes `main`, publishes the Release, dispatches or correlates the deploy (`tenant-deploy.yml` only for tenant-container), announces (the org alerts channel for the Hub; the project's own release channel for a product repo), re-syncs project info, and rolls `development` and `rc` forward. Nothing here is done by hand.
 
 ## Verify
 
@@ -51,7 +51,7 @@ Read the receipt at `$r`, never the exit code (exit `2` = shipped with a follow-
 - `deployStatus` — `pending` is never terminal; `promoted: true` holds even when a deploy failed.
 - `workflowRuns` — every run on the release SHA (deploy-model runs, any `push: main` deploy, the repo's own `gate`). Watch each non-success entry to conclusion: `gh run watch <run-id> --repo {owner}/{repo} --exit-status`. Name which run is red: `deploy.yml` / `publish.yml` / `tenant-deploy.yml` / `jerv-gateway` is a deploy or publish verdict; a `gate` push run is ordinary CI sharing the SHA.
 - With `--watch` the train waits for its own alignment PR to land (true merge) and folds the ledger in the same run, so the receipt ends `succeeded` / `complete`. An external `gh run watch` never folds anything: if the receipt still shows a `pending` leg (no `--watch`, or the alignment PR outlived the bounded wait), fold it live before declaring the cut done or starting any new train: `mmi-cli devops release --resume --watch --json --out <fresh-receipt>`; the NEXT train's doctor otherwise refuses with `ledger-pending`.
-- `announceNote` (Hub) — `announced`, `skipped`, or the failure note.
+- `announceNote` — `announced` (to the alerts channel for the Hub, to the project release channel for a product repo), `skipped`, or the failure note. The channel id itself is never printed.
 - `devRollForward` / `rcAlignment` — `pushed`, or `pr-pending` with the alignment PR to land by true merge (Merge floor). An enqueued auto-merge is not evidence of the method; before reporting, read the enqueued method back — `gh pr view <n> --json autoMergeRequest --jq .autoMergeRequest.mergeMethod` — and prove it is `MERGE`. An enqueued `SQUASH` is a stop under the Merge floor, not something to wait out.
 - `versionFold`, `rcRetirement`, `checkout` — `returned`, or the named reason you are still on `main`.
 - A `private` npm surface (`surfaces.json`): the doctor's `npm-token-rejected` finding comes first. A 401 from `npm whoami` through the `_org` `npm/NPM_TOKEN` vault hop means the token is rejected, and every authenticated `npm view` then 404s exactly like an absent package — rotate the token; only after a login is a restricted 404 "unverifiable from here", never "not published" (`publish-private-package`). On a repo whose workflows publish through Trusted Publishing and name no registry token, that row is `info`, not a warning: no lane consumes the org token, so it constrains your manual read only.