Skip to content

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

Merged
tusharmath merged 4 commits intoantinomyhq:mainfrom
ahundt:docs/readme-newcomer-orientation
Apr 7, 2026
Merged

docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs#2862
tusharmath merged 4 commits intoantinomyhq:mainfrom
ahundt:docs/readme-newcomer-orientation

Conversation

@ahundt
Copy link
Copy Markdown
Contributor

@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
@tusharmath tusharmath merged commit 29411b3 into antinomyhq:main Apr 7, 2026
9 of 10 checks passed
@tusharmath tusharmath removed the type: feature Brand new functionality, features, pages, workflows, endpoints, etc. label Apr 7, 2026
@github-actions github-actions bot added the type: feature Brand new functionality, features, pages, workflows, endpoints, etc. label Apr 7, 2026
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