New forge from a template

A new forge can start from a template repository: one an admin marked at Settings → Templates and the maker can read. The New forge page has one Template select (default "The forge's own code", then Blank, Starter app and each readable template repository); the terminal's New forge screen cycles the same list with left and right, or takes owner/name typed. POST /api/v1/forges and the MCP spawn tool take template: "owner/name". An unmarked or unreadable owner/name answers 422 saying which. A string that is no template at all (not blank, starter or owner/name) answers 404 unknown_template with one sentence, "There is no such template.", and the known built-in ids in templates; the id sent is never echoed, and any other wrong type stays the 422. The page door answers the same 404: the form again with the name kept and the sentence, and below it the /templates rows as buttons that open the form with that template chosen. The terminal has no free-text id to get wrong: its New forge screen cycles the list, and a typed owner/name that is not a template gets the sentence only; its Templates screen is where the list is.

The template's code becomes the child's own forge repository. It keeps the template's visibility: a private template never becomes a public repository in the child.

Code: src/spawn/templates.ts (ids and words), src/spawn/forge_code.ts (the fork), src/actions/spawn.ts (the checks).

From the command line: forge new --template

forge new <name> --template NAME makes a forge from a template through the same door as the page (POST /api/v1/forges), signed in as the CLI is (forge login). On success it prints made forge <name> from <template> and, on the next line, the claim link to send to whoever will own the forge.

Code: src/cli/new_template.ts, the two calls in src/cli/api.ts (templates, newForge). Test: test/cli-new-template.test.ts.

The list: /templates

/templates lists what a new forge can start from: the built-in templates, then the template repositories you can read. Each row has one sentence and one secondary button, "Start a forge", which opens /forges/new?template=<id> with that template chosen. Signed out works too: a stranger lands on the same form with the template kept. ?template= is accepted only when spawn accepts it (parseTemplate); anything else leaves Blank chosen, and it is never echoed. The plan (do=plan) shows "It starts from the <b>…</b> template".

The terminal has the same list: the "Templates" command (src/tui/screens/templates.ts) shows the same rows; Enter on a row opens New forge with that template chosen, for people signed in, and a guest is told to sign in. Both read templateList (src/spawn/template_list.ts), so a private template repository is listed only to people who can read it, on the page and in the terminal alike.

Filtering the list

/templates?q=star keeps the rows whose title or id contains the word, case-insensitively; the field keeps its value, q is trimmed and capped at 80 characters, and a word that matches nothing says "No template matches that name." with a link to /templates that clears it. In the terminal, / on the Templates screen types the same filter (Enter or Esc stops typing). Both use filterTemplates in src/spawn/template_list.ts.

One template's page: /templates/<name>

/templates/<id> (/templates/starter, /templates/owner/name) is a page to share: Open Graph and Twitter meta (title, the one-line sentence, and the card /og/template/<id>.png, owner~name for a repository), and one plain link, "Start a forge from <name>", to /forges/new?template=<id>. The card is the existing renderer and its cached PNG path, drawn only from what a signed-out reader is offered. A template not listed to the reader, or unknown, answers 404 alike. The terminal's Templates screen prints the same path under the row as "Share:". Code: templatePage in src/web/pages/template.ts; the id and card-ref pair in src/spawn/template_list.ts. Test: test/template-share.test.ts.

Choosing on the page: radios

The New forge page lists the built-in templates as radio buttons, Blank checked, and needs no script; /forges/new?template=starter opens the form with Starter app checked. Pick one and press Make. In the terminal the New forge screen cycles the same choices with left and right, so both doors offer the same list. Code: src/web/pages/new-forge.ts. Test: test/new-forge-template.test.ts.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs