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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/12528-each-spine-page-is-two-phone-screens-or → main 2 commits fork 3 threads · 3 unresolved

  • Merged. scout/12528-each-spine-page-is-two-phone-screens-or was merged into main as 89e2969.

Review

Sign in to review this change.
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
1212
1313 ## Moving
1414
15 - **To your machine**: `forge sync` clones every app you follow, and work continues offline. See [on your machine](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](ON-YOUR-MACHINE.md).
1616 - **Between forges**: connect another forge as an origin at `/settings/origins`, bring an app in, and send changes back. See [origins](ORIGINS.md).
1717 - **To a new owner**: transfer an app from its Danger zone. Old links keep working ([transfer](features/repo-transfer.md)).
1818
19 To keep your repositories mirrored on your machine, so you can work offline, run this after `forge login`:
outdated

A bare forge sync with no sentence introducing it. Say what it does here (keeps your repositories mirrored on your machine) before the block.

20
21 ```sh
22 forge sync
23 ```
24
1925 Next: [Every setting, by topic](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
88
99 ## Plans
1010
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 ([Bring your own AI](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 ([Bring your own AI](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`.
1220
1321 ## Getting paid
1422
docs/guide-own-ai.md +9
@@ -14,6 +14,15 @@ Open `/settings/model` and add your credential. The crew's other knobs (who work
1414
1515 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.
1616
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
1726 ## Use your own tools too
1827
1928 Your own assistant can drive the forge through the MCP: [Agents](guide-agents.md).
docs/guide-settings.md +6
@@ -18,6 +18,12 @@ General (name, default branch, visibility), App (how it runs, variables, domains
1818
1919 ## Admin
2020
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
2127 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.
2228
2329 Reference: [operating](OPERATING.md), [roles](ROLES.md). Next: [When something is wrong](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
1717 - `/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.
1818 - `/talk` is where you tell the crew something.
1919
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
2026 Everything is private until you make it public, and each page says in one line who can see it.
2127
2228 ## 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 `
2727 - A failed backup or a red restore drill is on `/settings/backups`.
2828 - If the forge cannot start, follow [recovery](RECOVERY.md); the ways it can stop are in [failure domains](DOMAINS.md).
2929
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
3036 ## Still stuck
3137
3238 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,
44
55 ## How an app runs
66
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.
198
209 ## Domains
2110
@@ -29,7 +18,7 @@ Your own account's keys, tokens and passkeys are at `/settings/secrets`, `/setti
2918
3019 ## Schedules
3120
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`:
3322
3423 ```json
3524 {
test/guide.test.ts +20 −2
@@ -18,8 +18,11 @@ import { searchDocs } from "../src/view/docs.ts";
1818 const root = new URL("..", import.meta.url).pathname;
1919 const read = (rel: string) => readFileSync(join(root, rel), "utf8");
2020 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");
2326
2427 const fences = (text: string, lang: string): string[] =>
2528 [...text.matchAll(new RegExp("```" + lang + "\\n([\\s\\S]*?)```", "g"))].map((m) => m[1] ?? "");
@@ -46,6 +49,21 @@ describe("the pages", () => {
4649 expect(p.text).toMatch(/^# \S/);
4750 const words = p.text.split(/\s+/).filter((w) => w !== "").length;
4851 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 }
4967 }
5068 });
5169

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs