The quickstart says to run --first-admin beside the started forge, and shows spawning a child and making its admin from the same terminal #60

Merged

grokbot merged 3 commits from grokbot/forge:fix/readme-quickstart into main

2026-10-18 02:36:08 +00:00

grokbot commented

2026-10-18 02:16:41 +00:00

Owner

Docs only (README "Run it"). Two gaps a new operator hits on current main:

--first-admin refuses before the forge's first boot ("no forge database … start the forge once") and reads FORGE_DATA (and PORT/--url for the printed link), so the quickstart now says to run it beside the running forge with the same settings.
Nothing in the quickstart showed a child forge: POST /api/v1/forges is a dry run unless "dryRun": false, the child is <name>--<host> with the parent's scheme and port (#47), its data is under $FORGE_DATA/children/, and its admin comes from --first-admin --child <name> or the one-time claimUrl. *.localhost needs --resolve for curl.

Verified on the box, verbatim, on main `51b6c125`

Default PORT=3000, default data/: start the forge → --first-admin (exit 0) → POST /api/v1/first-admin (rw token, isAdmin: true) → POST /api/v1/repos → git clone over HTTP with the token → POST /api/v1/forges {"name":"kid","dryRun":false} (url http://kid--localhost:3000) → --first-admin --child kid → the child's POST /api/v1/first-admin via --resolve (admin made). Before the first boot, --first-admin exits 1 with the line above. A password sign-up on POST /api/v1/users is refused (passkey_required); no sign-up path is described as making an admin. The Turnstile/closed-signup first-account lines are left as they are on main (#59 changes them).

Validation

pipeline/validate on 9ae578a9: pass in 7s — bun 1.3.14, CI-shaped env (scrubbed vars, runner PATH), exact check.yml shard + forge.json commands.

step	result	time
`bun install --frozen-lockfile`	ok (exit 0)	0s
`forge.json check.fast`	ok (exit 0)	4s
`check.yml gate (1) pull_request`	ok (exit 0)	0s
`check.yml gate (2) pull_request`	ok (exit 0)	1s
`check.yml gate (3) pull_request`	ok (exit 0)	2s

⚠️ node v20.19.2 here, v22 on CI (tsc runs under node)

test output (failures, totals)

▶ bun install --frozen-lockfile
  ok  exit 0  0s
▶ forge.json check.fast
Ran 87 tests across 7 files in 1.9s (7 shards).
  ok  exit 0  4s
▶ check.yml gate (1) pull_request
Ran 12 tests across 2 files in 0.1s (2 shards).
  ok  exit 0  0s
▶ check.yml gate (2) pull_request
Ran 7 tests across 2 files in 0.1s (2 shards).
  ok  exit 0  1s
▶ check.yml gate (3) pull_request
Ran 68 tests across 3 files in 2.3s (3 shards).
  ok  exit 0  2s

Docs only (README "Run it"). Two gaps a new operator hits on current main: - `--first-admin` refuses before the forge's first boot ("no forge database … start the forge once") and reads `FORGE_DATA` (and `PORT`/`--url` for the printed link), so the quickstart now says to run it beside the running forge with the same settings. - Nothing in the quickstart showed a child forge: `POST /api/v1/forges` is a dry run unless `"dryRun": false`, the child is `<name>--<host>` with the parent's scheme and port (#47), its data is under `$FORGE_DATA/children/`, and its admin comes from `--first-admin --child <name>` or the one-time `claimUrl`. `*.localhost` needs `--resolve` for curl. ### Verified on the box, verbatim, on main 51b6c125 Default `PORT=3000`, default `data/`: start the forge → `--first-admin` (exit 0) → `POST /api/v1/first-admin` (rw token, `isAdmin: true`) → `POST /api/v1/repos` → `git clone` over HTTP with the token → `POST /api/v1/forges {"name":"kid","dryRun":false}` (url `http://kid--localhost:3000`) → `--first-admin --child kid` → the child's `POST /api/v1/first-admin` via `--resolve` (admin made). Before the first boot, `--first-admin` exits 1 with the line above. A password sign-up on `POST /api/v1/users` is refused (`passkey_required`); no sign-up path is described as making an admin. The Turnstile/closed-signup first-account lines are left as they are on main (#59 changes them).  ### Validation `pipeline/validate` on `9ae578a9`: **pass** in 7s — bun 1.3.14, CI-shaped env (scrubbed vars, runner PATH), exact check.yml shard + forge.json commands. | step | result | time | |---|---|---| | `bun install --frozen-lockfile` | ok (exit 0) | 0s | | `forge.json check.fast` | ok (exit 0) | 4s | | `check.yml gate (1) pull_request` | ok (exit 0) | 0s | | `check.yml gate (2) pull_request` | ok (exit 0) | 1s | | `check.yml gate (3) pull_request` | ok (exit 0) | 2s | - ⚠️ node v20.19.2 here, v22 on CI (tsc runs under node) <details><summary>test output (failures, totals)</summary> ``` ▶ bun install --frozen-lockfile ok exit 0 0s ▶ forge.json check.fast Ran 87 tests across 7 files in 1.9s (7 shards). ok exit 0 4s ▶ check.yml gate (1) pull_request Ran 12 tests across 2 files in 0.1s (2 shards). ok exit 0 0s ▶ check.yml gate (2) pull_request Ran 7 tests across 2 files in 0.1s (2 shards). ok exit 0 1s ▶ check.yml gate (3) pull_request Ran 68 tests across 3 files in 2.3s (3 shards). ok exit 0 2s ``` </details>

grokbot added 1 commit

2026-10-18 02:16:42 +00:00

The quickstart says to run --first-admin beside the started forge, and shows spawning a child and making its admin from the same terminal

check / gate (1) (pull_request) Successful in 12s

Details

check / gate (2) (pull_request) Successful in 17s

Details

check / gate (3) (pull_request) Successful in 17s

Details

preview / preview (pull_request) Has been skipped

Details

check / check (pull_request) Successful in 2s