docs(slash-commands): add comprehensive slash command reference; link from core README; add code comments reminding to update docs when adding commands

codex-rs/core/README.md

@@ -2,6 +2,9 @@
 
 This crate implements the business logic for Codex. It is designed to be used by the various Codex UIs written in Rust.
 
+See also: [Slash Commands](../../docs/slash-commands.md) for a complete list of
+interactive commands available in the TUI.
+
 ## Dependencies
 
 Note that `codex-core` makes some assumptions about certain helper utilities being available in the environment. Currently, this

codex-rs/core/src/slash_commands.rs

@@ -1,5 +1,10 @@
 use crate::config_types::AgentConfig;
 
+// NOTE: These are the prompt formatters for the prompt‑expanding slash commands
+// (/plan, /solve, /code). If you add or change a slash command, please update
+// the user documentation in `docs/slash-commands.md` so the list stays in sync
+// with the UI and behavior.
+
 /// Get the list of enabled agent names from the configuration
 pub fn get_enabled_agents(agents: &[AgentConfig]) -> Vec<String> {
     agents

codex-rs/tui/src/slash_command.rs

@@ -5,6 +5,10 @@ use strum_macros::EnumString;
 use strum_macros::IntoStaticStr;
 
 /// Commands that can be invoked by starting a message with a leading slash.
+///
+/// IMPORTANT: When adding or changing slash commands, also update
+/// `docs/slash-commands.md` at the repo root so users can discover them easily.
+/// This enum is the source of truth for the list and ordering shown in the UI.
 #[derive(
     Debug, Clone, Copy, PartialEq, Eq, Hash, EnumString, EnumIter, AsRefStr, IntoStaticStr,
 )]

docs/slash-commands.md

@@ -0,0 +1,67 @@
+# Slash Commands
+
+Codex CLI supports a set of slash commands you can type at the start of the
+composer input. These commands provide quick actions, toggles, or expand into
+full prompts. This document lists all built‑in commands and what they do.
+
+Notes
+
+- Commands are shown in the TUI’s slash popup; the order below matches the UI.
+- Commands marked “prompt‑expanding” transform your input into a full prompt and
+  typically kick off multi‑agent flows.
+- Some commands accept arguments; if required, usage is shown in parentheses.
+
+## Navigation & Session
+
+- `/browser`: open internal browser.
+- `/chrome`: connect to Chrome.
+- `/new`: start a new chat during a conversation.
+- `/resume`: resume a past session for this folder.
+- `/quit`: exit Codex.
+- `/logout`: log out of Codex.
+
+## Workspace & Git
+
+- `/init`: create an `AGENTS.md` file with instructions for Codex.
+- `/diff`: show `git diff` (including untracked files).
+- `/branch [task]`: create a worktree branch and switch to it. If a
+  task/description is provided, it is used when naming the branch.
+
+## UX & Display
+
+- `/theme`: switch between color themes.
+- `/verbosity (high|medium|low)`: change text verbosity.
+- `/reasoning (minimal|low|medium|high)`: change reasoning effort.
+- `/prompts`: show example prompts.
+- `/status`: show current session configuration and token usage.
+
+## Search & Mentions
+
+- `/mention`: mention a file (opens the file search for quick insertion).
+
+## Performance & Agents
+
+- `/perf (on|off|show|reset)`: performance tracing controls.
+- `/agents`: list agents (running and availability).
+
+## Prompt‑Expanding (Multi‑Agent)
+
+These commands expand into full prompts (generated by `codex-core`) and
+typically start multiple agents. They require a task/problem description.
+
+- `/plan <task>`: create a comprehensive plan (multiple agents). Prompt‑expanding.
+- `/solve <problem>`: solve a challenging problem (multiple agents). Prompt‑expanding.
+- `/code <task>`: perform a coding task (multiple agents). Prompt‑expanding.
+
+## Development‑Only
+
+- `/test-approval`: test approval request (available in debug builds only).
+
+Implementation Notes
+
+- The authoritative list of commands is defined in
+  `codex-rs/tui/src/slash_command.rs` (the `SlashCommand` enum). When adding a
+  new command, please update this document to keep the UI and docs in sync.
+- Prompt formatting for `/plan`, `/solve`, and `/code` lives in
+  `codex-rs/core/src/slash_commands.rs`.
+