Skip to content

docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs#2862

Open
ahundt wants to merge 3 commits intoantinomyhq:mainfrom
ahundt:docs/readme-newcomer-orientation
Open

docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs#2862
ahundt wants to merge 3 commits intoantinomyhq:mainfrom
ahundt:docs/readme-newcomer-orientation

Conversation

@ahundt
Copy link
Copy Markdown

@ahundt ahundt commented Apr 6, 2026

Adds onboarding context and documents the ZSH plugin system, which was not
covered in the README. Also updates the CLI reference to match the current
binary and clarifies a few configuration details.

What's added

  • "How Forge Works: Three Modes" section orienting newcomers to the three
    distinct usage patterns: Interactive TUI, One-Shot CLI (-p), and ZSH Plugin.
    Includes a note that forge conversation resume <id> opens the interactive
    TUI (not a one-shot command), which is a common point of confusion.
  • "ZSH Plugin: The : Prefix System" section with full coverage of agents
    (forge/sage/muse, aliases :ask/:plan), prompt sending, file attachment via
    @ + Tab, conversation management (:new, :conversation, :clone,
    :rename, :retry, :copy, :dump, :compact), git integration
    (:commit, :commit-preview), shell tools (:suggest, :edit),
    session-only vs persistent config options, skills (built-in and custom),
    AGENTS.md, custom agents/commands, semantic search/workspace, and a
    quick-reference table of all : commands.
  • "Subcommands" section listing all forge subcommands by category.

What's updated

  • Command-Line Options table: reflects current flags (--conversation-id,
    --agent, -C/--directory, --sandbox); removes flags not present in the
    current CLI (-c, -w, -r).
  • MCP section: replaces commands from an earlier version (add, add-json,
    get) with the current subcommands (import, show, remove, reload);
    makes config paths explicit (./.mcp.json for project-local,
    ~/forge/.mcp.json for global).
  • ZSH plugin env var comment: corrected from # prefix to : prefix.
  • Global config path: corrected from ~/.forge/.forge.toml to
    ~/forge/.forge.toml (source: crates/forge_infra/src/env.rs line 27-29,
    h.join("forge")).
  • Three minor grammar fixes (missing comma, pronoun clarity, sentence structure).

…c CLI docs

Adds onboarding context and documents the ZSH plugin system, which was not
covered in the README. Also updates the CLI reference to match the current
binary and clarifies a few configuration details.

What's added:
- "How Forge Works: Three Modes" section orienting newcomers to the three
  distinct usage patterns: Interactive TUI, One-Shot CLI (-p), and ZSH Plugin.
  Includes a note that `forge conversation resume <id>` opens the interactive
  TUI (not a one-shot command), which is a common point of confusion.
- "ZSH Plugin: The `:` Prefix System" section with full coverage of agents
  (forge/sage/muse, aliases :ask/:plan), prompt sending, file attachment via
  @ + Tab, conversation management (:new, :conversation, :clone, :rename,
  :retry, :copy, :dump, :compact), git integration (:commit, :commit-preview),
  shell tools (:suggest, :edit), session-only vs persistent config options,
  skills (built-in and custom), AGENTS.md, custom agents/commands, semantic
  search/workspace, and a quick-reference table of all : commands.
- "Subcommands" section listing all forge subcommands by category.

What's updated:
- Command-Line Options table: reflects current flags (--conversation-id,
  --agent, -C/--directory, --sandbox); removes flags not present in the
  current CLI (-c, -w, -r).
- MCP section: replaces commands from an earlier version (add, add-json, get)
  with the current subcommands (import, show, remove, reload); makes config
  paths explicit (./.mcp.json for project-local, ~/forge/.mcp.json for global).
- ZSH plugin env var comment: corrected from # prefix to : prefix.
- Global config path: corrected from ~/.forge/.forge.toml to ~/forge/.forge.toml
  (source: crates/forge_infra/src/env.rs line 27-29, h.join("forge")).
- Three minor grammar fixes (missing comma, pronoun clarity, sentence structure).
@github-actions github-actions bot added type: docs Related to documentation and information. type: feature Brand new functionality, features, pages, workflows, endpoints, etc. labels Apr 6, 2026
@CLAassistant
Copy link
Copy Markdown

CLAassistant commented Apr 6, 2026

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ tusharmath
❌ ahundt
You have signed the CLA already but the status is still pending? Let us recheck it.

tusharmath and others added 2 commits April 6, 2026 20:19
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
@tusharmath
Copy link
Copy Markdown
Collaborator

Many many thanks!

@tusharmath tusharmath enabled auto-merge (squash) April 6, 2026 14:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: docs Related to documentation and information. type: feature Brand new functionality, features, pages, workflows, endpoints, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants