[good first issue] Document common CLI failures in docs/forge-cli.md #73

New issue

Open

opened 2026-07-09 03:17:03 +00:00 by gmackie · 0 comments

gmackie commented

2026-07-09 03:17:03 +00:00

Owner

Why this is a good first issue

Documentation-only. No product code required. Improves contributor and operator UX before public launch.

Goal

Add a Common failures section to docs/forge-cli.md covering the failures newcomers hit first:

forge doctor failures (missing Nix, flake, server URL, token)
forge login / auth token problems
Deploy blocked / stage missing (fg status / fg stage list discovery)
Agent offline / hub connectivity hints

Acceptance criteria

Section exists with at least the four topics above
Each failure lists: symptom, likely cause, concrete command to diagnose, link to deeper docs if any
Linked from the top of docs/forge-cli.md (TOC or "See also")
No invented flags — only commands verified against forge --help / real docs

References

CONTRIBUTING.md
docs/community/strategy.md (good first issue policy)
STAGES.md for stage naming / discovery

Labels

good first issue · docs · help wanted

## Why this is a good first issue Documentation-only. No product code required. Improves contributor and operator UX before public launch. ## Goal Add a **Common failures** section to [`docs/forge-cli.md`](docs/forge-cli.md) covering the failures newcomers hit first: 1. `forge doctor` failures (missing Nix, flake, server URL, token) 2. `forge login` / auth token problems 3. Deploy blocked / stage missing (`fg status` / `fg stage list` discovery) 4. Agent offline / hub connectivity hints ## Acceptance criteria - [ ] Section exists with at least the four topics above - [ ] Each failure lists: symptom, likely cause, concrete command to diagnose, link to deeper docs if any - [ ] Linked from the top of `docs/forge-cli.md` (TOC or "See also") - [ ] No invented flags — only commands verified against `forge --help` / real docs ## References - [`CONTRIBUTING.md`](CONTRIBUTING.md) - [`docs/community/strategy.md`](docs/community/strategy.md) (`good first issue` policy) - [`STAGES.md`](STAGES.md) for stage naming / discovery ## Labels `good first issue` · `docs` · `help wanted`

gmackie added the

good first issue

help wanted

docs

labels

2026-07-09 03:17:03 +00:00