docs(cli): rewrite /cli for the new TUI cockpit

[charlesrhoward]

Summary

The standalone mogplex CLI (with exec, login, slash, etc. subcommands) is being replaced by the new interactive cockpit shipping out of mogplex-tui. This PR rewrites the entire /cli/* URL space to document the new product. URL space is preserved (no redirects needed).

What changed

New sections:

• cli/concepts/{architecture, transports, permissions, approvals, attach} — mental model + load-bearing concepts.
• cli/reference/{panels, drawers, keybindings, cost-and-usage, export} — one page per surface in the cockpit.

Rewritten:

• cli/index.mdx — overview reframed for the cockpit (panels, drawers, attach, slash commands).
• cli/installation.mdx — kept curl-bash installer pattern; dropped per-config-file complexity.
• cli/quickstart.mdx — /run, approvals, attach. No more mogplex exec.
• cli/commands/index.mdx — now the slash command reference (/run, /pause, /permissions, etc.).
• cli/guides/{index, authentication, configuration-and-flags, slash-commands, project-commands} — auth is in-app; env vars are escape hatches; no config.toml.
• cli/skills/{index, using-mogplex-cli, mogplex-slash, mogplex-auth} — reframed as guidance skills (CLI is interactive-only; agents advise the user, they don't drive the TUI).
• skills/<name>/SKILL.md (canonical files) — same rewrites.
• extend/{index, skills}.mdx — updated to reference the new guidance-skills framing and remove mogplex exec mentions.
• Homepage index.mdx — CLI card and positioning copy updated.

Deleted:

• cli/commands/{exec, login, slash, reserved-names}.mdx — subcommands gone.
• cli/guides/exec-mode.mdx — no exec mode.
• cli/skills/mogplex-exec.mdx + skills/mogplex-exec/SKILL.md — capability removed.
• scripts/gen-cli-reference.ts + prebuild npm script — auto-gen targeted the old commander metadata.
• tsx devDep — only used by the removed prebuild script.

Source of truth used

• mogplex-tui/spec.MD, mogplex-tui/CLAUDE.md, and mogplex-tui/README.md
• mogplex-tui/packages/tui/src/transport/router.ts (transport selection rules)
• mogplex-tui/packages/tui/src/permissions/{types,storage,runtime}.ts (permission modes + on-disk schema)
• mogplex-tui/packages/tui/src/drawers/{all,palette-registry}.ts (drawer + slash command lists)
• mogplex-tui/packages/tui/src/index.tsx (Ctrl+C double-tap behavior)

Test plan

• pnpm types:check passes
• pnpm build builds 58+ pages without errors
• rg -i "mogplex exec|exec mode" content/docs/cli/ returns 0 matches
• No links remain to deleted pages (/cli/commands/exec, /cli/commands/login, /cli/commands/slash, /cli/commands/reserved-names, /cli/guides/exec-mode, /cli/skills/mogplex-exec)
• pnpm dev — manual click-through under /cli/* (rendered locally; sampled /cli, /cli/quickstart, /cli/skills, /cli/concepts/permissions, /cli/commands, /cli/guides/authentication, /cli/guides/project-commands — all 200, Callout components render correctly)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mogplex-docs	Ready	Preview, Comment	Apr 27, 2026 8:16pm

[mogplex]

Mogplex PR Review

Status: Attention needed

This is a large, well-structured documentation rewrite that correctly pivots the entire /cli/* URL space from the old mogplex exec/subcommand model to the new TUI cockpit. The content is internally consistent, cross-links are accurate, and the PR description matches the diff faithfully. There are no security issues, no broken build scripts left behind, and the tsx devDep is cleanly removed alongside the script that used it. A few real issues are worth fixing before merge: one stale cross-reference in the Skills card text, one missing Callout import in the Skills index page, and a correctness concern in the permissions documentation about the "projects can only be more permissive" claim.

3 findings were added inline.

Suggestions

• Truncated patch in cli/commands/index.mdx diff — verify the See also section rendered correctly (content/docs/cli/commands/index.mdx)
  The unified diff for this file is truncated at the end of the See also section (- [Exec Mode…). The fetched full file content shows the section is complete, but given the diff was cut off it's worth a manual visual check in pnpm dev that the page renders fully without orphaned MDX.
• --logout flag is undocumented in the CLI flags table (content/docs/cli/guides/configuration-and-flags.mdx)
  The Configuration and Flags page lists these CLI flags:

| --attach <runId> | … |
| --logout | Clear the stored Mogplex token before launching. … |
| --events=jsonl | … |

--logout correctly appears here and in cli/concepts/attach.mdx. However, the cli/index.mdx overview's "Slash commands at a glance" line and the Quickstart's step-by-step table do not mention it. This is fine — it's an edge-case flag. Just confirm there is no user path where they'd expect to find it and hit a dead end.

View check run

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ba1f7a7c5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mogplex]

Mogplex PR Review

Status: Attention needed

This is a large, well-executed documentation rewrite that cleanly replaces the old exec-mode CLI surface with the new TUI cockpit model. The internal consistency across concepts, reference pages, guides, and skill files is strong. There are a handful of concrete issues to address before merging: one missing import statement that will cause a build-time MDX error, one stale link remnant in a truncated diff, one subtle but meaningful permissions-model inconsistency in the callout text, and a couple of minor hygiene items.

3 findings were added inline.

Suggestions

• skills/mogplex-slash/SKILL.md — mogplex-slash description still mentions /attach which doesn't exist as a slash command (skills/mogplex-slash/SKILL.md)
  The YAML frontmatter description says "Use when the user asks how to start, pause, kill, attach, model-switch, approve, or export a Mogplex run." But --attach is a CLI flag (mogplex --attach <runId>), not a slash command. The skill's own body table correctly maps "Pull up that run from CI" to mogplex --attach <runId> rather than a /attach slash command. The description's mention of "attach" as a skill trigger is fine contextually, but the phrasing alongside slash-command verbs may cause a skill-aware host to try looking for /attach. Slight rewording would reduce ambiguity: "Use when the user asks how to start, pause, kill, or control a Mogplex run, attach to one from CI, switch models, manage approvals, or export."
• CODEX_HOME deprecation note is not cross-linked from authentication guide (content/docs/cli/guides/configuration-and-flags.mdx)
  The configuration guide correctly notes that CODEX_HOME is deprecated in favor of MOGPLEX_HOME. This is the only place this fact appears. Users who have CODEX_HOME set from an older install may not realize their auth.json path is resolving from the wrong location and think the auth guide's file path is wrong. A one-sentence cross-reference in the auth guide's "See also" or in the inline note about ~/.mogplex/auth.json ("if you previously used CODEX_HOME, see Configuration and Flags") would close this gap.
• PR test plan has an open manual checkbox — should be completed before merge
  The test plan item [ ] pnpm dev — manual click-through every nav entry under /cli/* and confirm new pages render is explicitly unchecked. This is a large structural change (new concepts/ and reference/ sections added to nav, multiple deletions). The automated checks (pnpm build, rg for old references) are solid, but they don't catch runtime rendering issues (e.g. the missing Callout import above, or any Card/Callout components that fumadocs needs for the new pages). The manual verification step should be completed and the checkbox checked before this merges.

View check run

[mogplex]

Mogplex PR Review

Status: Attention needed

This is a large, well-scoped documentation rewrite that cleanly removes the old mogplex exec/login/slash CLI surface and replaces it with accurate coverage of the new TUI cockpit. The internal link graph is consistent, the permissions model is documented correctly, and the skill files have been properly updated to the guidance-only framing. Two issues deserve attention before merge.

Warnings

• Permissions resolution prose contradicts the stated loosen-only invariant (content/docs/cli/concepts/permissions.mdx)
  The closing sentence of the How rules resolve prose reads: "In other words, a layer can only loosen what an outer layer already restricts — it cannot tighten it." This sentence is applied to all layers equally, but it is only true of the project layer. The global layer can and does tighten mode defaults by adding deny rules (and those cannot be overridden by project files). The Callout immediately below says this correctly — but a reader who only reads the prose will conclude incorrectly that the global layer also cannot tighten anything.

Suggestion: Change the sentence to "In other words, a more specific layer (project) can only loosen what a less specific layer (global, mode default) already restricts — it cannot tighten it." This scopes the claim to the project layer and matches the Callout exactly.

Suggestions

• Stale card description in extend/index.mdx still says 'drive a Mogplex workspace' (content/docs/extend/index.mdx)
  The Skills (available today) Card still reads: "Anthropic Agent Skills that teach any skill-aware host how to drive a Mogplex workspace through the mogplex CLI." The word 'drive' contradicts the guidance-only framing applied everywhere else in this PR. An integrator reading only this card could believe skills can execute commands headlessly.

Suggestion: Update to "Anthropic Agent Skills that teach skill-aware hosts how to guide users through the Mogplex cockpit — slash commands, login flow, and repo-local config."

• mogplex-auth.mdx uses Callout without a visible import statement (content/docs/cli/skills/mogplex-auth.mdx)
  The page opens with a block but the diff shows no import { Callout } from 'fumadocs-ui/components/callout' line. Every other page in this PR that uses Callout (permissions.mdx, keybindings.mdx, quickstart.mdx, configuration-and-flags.mdx) includes the explicit import. The build passed so this is probably covered by a global MDX component config, but it is worth a consistency check — if the import is ever required explicitly, this page would silently render a raw unknown element.
• Manual click-through test step is unchecked (content/docs/cli/quickstart.mdx)
  The PR test plan lists 'pnpm dev — manual click-through every nav entry under /cli/' as unchecked. Given the number of new pages (concepts/, reference/*) and the new meta.json nav entries, an unverified render is a meaningful gap. Not a blocker, but completing this before merge is advisable especially for the new Concepts and Reference sections whose nav ordering is defined for the first time here.

View check run