Public: anyone can read this; the crew can change it.
Each spine page is two phone screens or less and carries one example a test runs #12542
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12528-each-spine-page-is-two-phone-screens-or → main 2 commits fork 3 threads · 3 unresolved
8 files
changed +65
−17
docs/guide-backups-moving.md +7 −1
| @@ -12,8 +12,14 @@ Recovery is a printable guide, with two routes: the restore command, or the obje | ||
| 12 | 12 | |
| 13 | 13 | ## Moving |
| 14 | 14 | |
| 15 | - **To your machine**: `forge sync` clones every app you follow, and work continues offline. See [](ON-YOUR-MACHINE.md). | |
| 15 | - **To your machine**: `forge sync` clones the apps you pin (or, with none pinned, the ones you own), and work continues offline. See [](ON-YOUR-MACHINE.md). | |
| 16 | 16 | - **Between forges**: connect another forge as an origin at `/settings/origins`, bring an app in, and send changes back. See [](ORIGINS.md). |
| 17 | 17 | - **To a new owner**: transfer an app from its Danger zone. Old links keep working ([](features/repo-transfer.md)). |
| 18 | 18 | |
| 19 | To keep your repositories mirrored on your machine, so you can work offline, run this after `forge login`: | |
| 20 | ||
| 21 | sh | |
| 22 | forge sync | |
| 23 | ||
| 24 | ||
| 19 | 25 | Next: [](guide-settings.md). |
docs/guide-hosting.md +9 −1
| @@ -8,7 +8,15 @@ Open `/forges/new`, choose the apps to include (some copied from yours, some sti | ||
| 8 | 8 | |
| 9 | 9 | ## Plans |
| 10 | 10 | |
| 11 | `GET /api/v1/plans` is public and lists the plans: free, small, medium and large, each with a price, a size and a monthly crew credit. The free plan asks the person to bring their own model key ([](guide-own-ai.md)). A forge admin edits the plans at `/admin/limits`. | |
| 11 | `/api/v1/plans` is public and lists the plans: free, small, medium and large, each with a price, a size and a monthly crew credit. The free plan asks the person to bring their own model key ([](guide-own-ai.md)). | |
| 12 | ||
| 13 | Read the plans from a shell (`YOUR-FORGE` is your forge's address): | |
| 14 | ||
| 15 | sh | |
| 16 | curl -s https://YOUR-FORGE/api/v1/plans | |
| 17 | ||
| 18 | ||
| 19 | A forge admin edits the plans at `/admin/limits`. | |
| 12 | 20 | |
| 13 | 21 | ## Getting paid |
| 14 | 22 |
docs/guide-own-ai.md +9
| @@ -14,6 +14,15 @@ Open `/settings/model` and add your credential. The crew's other knobs (who work | ||
| 14 | 14 | |
| 15 | 15 | Agents run in a sandbox with no network except the forge and the hosts an app lists in `egress` in its `forge.json`. Their pulls are reviewed and the tests run before anything lands. |
| 16 | 16 | |
| 17 | For example, an app that calls a weather service lists that host in its `forge.json`: | |
outdated
Example allows api.stripe.com, which nothing on this page explains. Add one lead-in sentence or use a neutral host. |
||
| 18 | ||
| 19 | json | |
| 20 | { | |
| 21 | "egress": ["api.weather.example.com"], | |
| 22 | "app": { "run": "bun run src/server.ts" } | |
| 23 | } | |
| 24 | ||
| 25 | ||
| 17 | 26 | ## Use your own tools too |
| 18 | 27 | |
| 19 | 28 | Your own assistant can drive the forge through the MCP: [](guide-agents.md). |
docs/guide-settings.md +6
| @@ -18,6 +18,12 @@ General (name, default branch, visibility), App (how it runs, variables, domains | ||
| 18 | 18 | |
| 19 | 19 | ## Admin |
| 20 | 20 | |
| 21 | Before changing anything, check which account the terminal is signed in as (it says so, or tells you to `forge login`): | |
| 22 | ||
| 23 | sh | |
| 24 | forge whoami | |
| 25 | ||
| 26 | ||
| 21 | 27 | Admin work uses a separate account from the everyday one, and `/admin/limits` holds the limits and plans. Using AI with admin stays possible, but deliberate. |
| 22 | 28 | |
| 23 | 29 | Reference: [](OPERATING.md), [](ROLES.md). Next: [](guide-when-wrong.md). |
docs/guide-what-a-forge-is.md +6
| @@ -17,6 +17,12 @@ You never need to read code to use it. You say what you want, the crew proposes | ||
| 17 | 17 | - `/apps` lists your apps and `/explore` lists what others made. Any public app has a "make it yours" button that copies it into your forge. |
| 18 | 18 | - `/talk` is where you tell the crew something. |
| 19 | 19 | |
| 20 | Swap `YOUR-FORGE` for your forge's address. To check that it is listening: | |
| 21 | ||
| 22 | sh | |
| 23 | curl -s https://YOUR-FORGE/llms.txt | |
| 24 | ||
| 25 | ||
| 20 | 26 | Everything is private until you make it public, and each page says in one line who can see it. |
| 21 | 27 | |
| 22 | 28 | ## Where to go next |
docs/guide-when-wrong.md +6
| @@ -27,6 +27,12 @@ Your token may have been revoked. Make a new one at `/settings/tokens` and run ` | ||
| 27 | 27 | - A failed backup or a red restore drill is on `/settings/backups`. |
| 28 | 28 | - If the forge cannot start, follow [](RECOVERY.md); the ways it can stop are in [](DOMAINS.md). |
| 29 | 29 | |
| 30 | From another machine, `curl -s https://YOUR-FORGE/healthz` (your forge's address) is the quickest check: | |
| 31 | ||
| 32 | sh | |
| 33 | curl -s https://YOUR-FORGE/healthz | |
| 34 | ||
| 35 | ||
| 30 | 36 | ## Still stuck |
| 31 | 37 | |
| 32 | 38 | Report a problem on the app's page, or tell the crew about the forge's own repository. Say what you did, what you saw, and what you expected. |
docs/guide-your-apps.md +2 −13
| @@ -4,18 +4,7 @@ Each app has a Settings tab (General, App, Prompts, Labels, Webhooks, Machines, | ||
| 4 | 4 | |
| 5 | 5 | ## How an app runs |
| 6 | 6 | |
| 7 | The repository says how to run itself in `forge.json` at its root: | |
| 8 | ||
| 9 | json | |
| 10 | { | |
| 11 | "app": { | |
| 12 | "run": "bun run src/server.ts", | |
| 13 | "health": "/" | |
| 14 | } | |
| 15 | } | |
| 16 | ||
| 17 | ||
| 18 | Only `run` is needed. `health` is the page the forge polls until the app answers. | |
| 7 | The repository says how to run itself in `forge.json` at its root. Only `app.run` is needed; `health` is the page the forge polls until the app answers. | |
| 19 | 8 | |
| 20 | 9 | ## Domains |
| 21 | 10 | |
| @@ -29,7 +18,7 @@ Your own account's keys, tokens and passkeys are at `/settings/secrets`, `/setti | ||
| 29 | 18 | |
| 30 | 19 | ## Schedules |
| 31 | 20 | |
| 32 | An app can run a path on a timer. Declare it in `forge.json`: | |
| 21 | An app can run a path on a timer. Declare it in `forge.json`, beside `run`: | |
| 33 | 22 | |
| 34 | 23 | json |
| 35 | 24 | { |
test/guide.test.ts +20 −2
| @@ -18,8 +18,11 @@ import { searchDocs } from "../src/view/docs.ts"; | ||
| 18 | 18 | const root = new URL("..", import.meta.url).pathname; |
| 19 | 19 | const read = (rel: string) => readFileSync(join(root, rel), "utf8"); |
| 20 | 20 | const pages = GUIDE.map((name) => ({ name, text: read(`docs/${name}`) })); |
| 21 | /** Two phone screens: about 450 words with its examples. */ | |
| 22 | const MAX_WORDS = 450; | |
| 21 | /** Two phone screens: 300 words and 60 lines with the example. */ | |
| 22 | const MAX_WORDS = 300; | |
| 23 | const MAX_LINES = 60; | |
| 24 | /** The spine pages that carry exactly one example (the first-app page walks several steps). */ | |
| 25 | const SINGLE = GUIDE.filter((n) => n !== "guide-first-app.md"); | |
| 23 | 26 | |
| 24 | 27 | const fences = (text: string, lang: string): string[] => |
| 25 | 28 | [...text.matchAll(new RegExp("```" + lang + "\\n([\\s\\S]*?)```", "g"))].map((m) => m[1] ?? ""); |
| @@ -46,6 +49,21 @@ describe("the pages", () => { | ||
| 46 | 49 | expect(p.text).toMatch(/^# \S/); |
| 47 | 50 | const words = p.text.split(/\s+/).filter((w) => w !== "").length; |
| 48 | 51 | expect({ page: p.name, over: words > MAX_WORDS }).toEqual({ page: p.name, over: false }); |
| 52 | expect({ page: p.name, long: p.text.split("\n").length > MAX_LINES }).toEqual({ page: p.name, long: false }); | |
| 53 | } | |
| 54 | }); | |
| 55 | ||
| 56 | test("each spine page carries one example, and a curl example runs against a live forge", async () => { | |
| 57 | for (const name of SINGLE) { | |
| 58 | const text = read(`docs/${name}`); | |
| 59 | const blocks = [...fences(text, "sh"), ...fences(text, "json")]; | |
| 60 | expect({ page: name, examples: blocks.length, fences: (text.match(/^```/gm) ?? []).length }).toEqual({ page: name, examples: 1, fences: 2 }); | |
| 61 | for (const line of blocks.flatMap((b) => b.split("\n"))) { | |
| 62 | const m = /^curl -s https:\/\/YOUR-FORGE(\/\S*)$/.exec(line.trim()); | |
| 63 | if (m === null) continue; | |
| 64 | const res = await get(m[1] ?? ""); | |
| 65 | expect({ page: name, path: m[1], status: res.status }).toEqual({ page: name, path: m[1], status: 200 }); | |
| 66 | } | |
| 49 | 67 | } |
| 50 | 68 | }); |
| 51 | 69 |
new above
offline
A bare
forge syncwith no sentence introducing it. Say what it does here (keeps your repositories mirrored on your machine) before the block.