Feature how-tos
A feature's how-to goes in its own file here, docs/features/<name>.md, named
for the one feature it describes. Do not add a section to the top-level
README.md: it is capped (test/readme-cap.test.ts) because every pull that
appended to it collided with the next. Existing README sections stay where they
are.
Reference notes
Every note is listed once below, under the topic a reader would look in; the
topics follow the guide.
A new note gets a row here (test/feature-orphans.test.ts).
What a forge is
Read with the guide page What a forge is.
- A forge made from a template says so on its home
- First week: three steps on a new forge's home
- The crew on a forge link's page
- A hosted forge proposes to its parent once the parent has handed it a credential
- How long the last forge from a template took, at /templates/<name>
- What a template holds: its files, run and check lines, on /templates
- A look in the feed
- One step deeper from a post
- A fork's page finds its place in the tree
- Open pulls red for over a day are named in one issue
- Empty lists
- An app with no description says its README
- Arcade carts
- How far behind a followed fork is
- Changelog
- Tell the crew from any shell with ssh and tell
- /docs
- Engine shape
- Feed fold
- Filter the feed by one app
- Questions on an issue
- A feed post has a permalink
- A run post opens its log
- Feed likes: the ledger
- Reply to an issue post in the feed
- Forge packs: a premade forge to deploy (
/packs) - Home paints its frame first
- Behaviors: shared interactions, attached by attribute
- Is v1.0.0 proven?
- Looks of
/signed out - Milestones at the front door
- Migration mode: a crew whose standing job is parity
- Data move: a platform app's Postgres through the drop into the app's store, with a receipt and an undo
- Cut over: check a domain against the platform, move it to the forge app with a receipt, undo in one step
- Now pages and Repositories
- Pixel art: the crew's faces
- Plans on the home
- Returning visitors
- Template mark
- What a template gives: apps, starter budget, model
- Who changed a setting, and when
- A new forge can start from a template repository
- Spawn a forge from a config, and keep it as a recipe
- Made from: the template a forge came from
- The explorer's sorts
- The feed pages by cursor
- The fork tree
- A busy branch of the forge family folds
- The home
- The quiet feed names its one next thing
- The feed says how many posts are new since your last visit
- The roadmap
Getting around: keys, the palette and search
- A mistyped repository address offers close ones
- Cmd-K: a pull's actions
- Cmd-K: repositories and their apps
gthen a letter: jump between pages- Hotkey hints
- The 404 offers the pages nearest the path asked
- Lists that ask for a decision answer the same keys
- Page help (
? Help) - Palette rows: numbers, people, settings, actions
- Phone search is the palette
- Pick list
- The empty palette lists what you opened last
Your first app in five minutes
Read with the guide page Your first app in five minutes.
- Bring an app from another forge (
/bring) - Display
- Displays list
- Make it yours
- New app, from the terminal
- Plain git contributes
- Send a change without a forge of your own
- Start: an agent builds with only the forge's URL
- The account screen of a forge you just started
- The line about a sent forge's first screen
- Home after the first ask
- Where a new app stands
Tell the crew
Read with the guide page Tell the crew.
- Dictate into the tell box
- Send a tell with Ctrl or Cmd+Enter
- A bug closes with a reason
- A business, as a map
- A maintainer keeps the code easy to change, and nothing else
- Switch a repository's crew off
- A new app starts the crew on it
- A new forge builds at once
- A new issue from any page
- A run's state is worked out from what it did
- A team is told once that a pull waits on its review
- A tell from a preview's toolbar carries its pull
- A tell's page says what became of it
- Tell the crew from the terminal's screen: key M
- A write the restart cut short, in a conversation
- Actions that answer at once
- Starter prompts in an empty conversation
- A thread folds its settled history
- An agent says what it does; a repo's team is three lists
- An assigned ask can be settled where it stands
- Ask filters
- Ask to reach a host
- Attention budgets
- Bets
- Bugs on a clock
- Chapters: a version with an end
- Each app with its crew member
- The app's page: detail on demand
- Estimates
- Flow keeper
- Flow line actions
- /flow: pulls closed unmerged after a CPU stop
- Flow: the week's budget as pipes
- Flow: waiting
- Flow: where the crew gives up
- Flows
- Flows across the forge
- Give a team member a role
- Everyone with an account, last seen first
- Hold new work on a file
- Maintenance duties
- See what waits for you: /?waits=me, and the terminal's Waiting for me
- Preview data of pulls closed over seven days
- Muting from the inbox keeps you in place
- Next up
- Next up says why a ready issue is not started
- Notes
- Refused first asks
- Share to the forge from a phone
- Since you were here
- /talk answers "what needs me?"
- Talk as a builder
- Answering a proposed action: Do it and Not now
- /talk attachments
- Talk runs the captain
- Talk to the forge's agent
- Stopping a Talk answer
- Talk answers link the issue and pull numbers they cite
- Tell the crew from a share, with a look before it files
- The crew line on Home
- The crew list
- The crew's runs on the desk
- The crew's week
- The crew's week shows which pulls came back
- The first ask by ssh makes an app
- The governor's line
- The map, lightly
- The pulls a crew team's review holds
- The pulls waiting on a crew team
- The open-issue ceiling
- A crew beside a backlog says why it stands still
- The queue
- The space
- The thank-you note
- The week is one budget for the whole crew
- The week's pace
- Walking a wave
- The wave-standing line
- How many of a wave's changes are live and waiting to ship
- How close a wave is to done
- What a repository with no waves says and offers
- Reading a wave's pulls, newest landed first, with who merged each
- What became of the first ask
- When a setting or a permission stands in the way
- The map's growth line
- Your team
Ship and undo
Read with the guide page Ship and undo.
- One notice per release
- A forge killed in the middle of a merge
- A person's reopen stands
- A preview of the forge, looked at as its owner
- The daily count of look pages in the check log
- A pull opens on its verdict
- A pull's looks
- An approval says what it was given for
- An approved pull that has waited a week
- Build cache
- Build pins
- Build preview
- Code scanning
- Detach a fork from its parent
- Iterations
- Land it as it is
- Landing a fork's pull in slices
- Naming the approved pull that waits
- Nightly jobs
- One path: check, review, land, live
- Pin screenshots
- Pulls untouched for 14 days
- Ranked checks
- Runners: a check on another machine, with a URL and a token
- A repository stuck behind its pulls
- A beat the forge owns, and a gate on the push
- Release heartbeat and the main-ahead alarm
- Release keeper
- Release what the Later gate holds
- Reviews are something an owner turns on
- The forge ships itself
- The landing line: when an approved pull will land
- The Later gate in plain sight
- The merge queue's gates, by failing test
- The polish share
- The throughput keeper
- Variants
- What a deploy carries, and when each change first went live
Your apps
Read with the guide page Your apps.
- An app refused an outside host says so in the forge's words
- What the crew is doing, as one sentence per app
- A child forge's own source
- A forge that runs its own code
- Absorb, reviewed from several angles
- Absorb: an app becomes one of the forge's features
- Adapter facts on the app page and in the terminal
- An app cannot stall the forge
- An app's own domain: cut-over and the way back
- App templates
- Template page
- Archive listing
- A binary file shows its size and type
- An OPML or RSS/Atom file opens as its entries
- A big .log or .txt opens its last lines
- Crawl budget
- Data browser (core)
- Database size
- Durable jobs
- The drop: a private place per app for what the crew cannot find in the repository
- First look at a note from an app
- Maintenance: shut down for a move and come back by itself
- Measuring a page: height and words
- New app from a template
- One place for a secret (
Settings → App → Secrets this app uses) - Pause and resume a maintenance duty
- Pinned toolchains (rust)
- A run's page folds its steps and its log
- Scheduled tools: the forge calls an absorbed app's tool on time
- Scrape evidence
- The box pass
- A table downloads as CSV
- The data explorer starts from a question
- The data explorer's sentence box
- The forge toolbar
- Timers and schedules
- Traffic
- Where people come from and where they go
- Whose wait it was: the forge's or the app's
Files in the browser
- Every kind of file the viewer opens, and how large
- An .obj or .ply file opens in the 3D viewer
- An .stl file as a 3D model
- A .dxf file as a picture
- Mermaid, draw.io and Excalidraw files
- A .psd file: facts, preview and layers
- A .har file as a request waterfall
- A .sarif file opens as its findings
- A
.env.exampleopens as the variables an app needs - A
.sqlfile opens as its schema - A
Dockerfileopens as its stages - A
Makefileopens as its targets - A
package.jsonopens as its manifest - A compose file opens as its services
- A GitHub Actions workflow opens as its jobs
- A GraphQL schema opens as its types
- A JUnit XML report opens as its results
- An .eml file opens as a message
- An lcov coverage file opens as its coverage
- An OpenAPI document opens as its operations
- Calendar files (.ics) as a list of events
- Config files as a form
- A refused form keeps what was typed
- Contacts files (.vcf) as a list of people
- CSV and TSV as a table
- Video-edit timelines (.otio, .edl, .fcpxml) as a cut list
- Files in the browser: the media route and the kind registry
- Font specimens
- G-code layers
- STEP (.step, .stp) as a part card
- GeoJSON (.geojson) as an outline and a properties table
- GPS tracks (.gpx) as a route outline
- HTML preview
- KML maps (.kml) as a placemark table
- A half-written tell is kept
- Jupyter notebooks
- Markdown relative images and links
- Markdown front matter as a list of facts
- Notebooks, JSON Lines and logs in the terminal
- Shift a subtitle file
- SQLite files as tables
- Parquet files as their columns and row groups
- Excel workbooks (.xlsx) as a table
- Office documents and layered images (.docx, .pptx, .ora)
- Subtitles as a transcript
- Terminal logs in colour
Hosting forges for others, and getting paid
Read with the guide page Hosting forges for others, and getting paid.
- A child forge's cores, held by pausing where the kernel cannot
- A child forge's disk bandwidth is capped by its size
- A child forge's own filesystem
- A claimed child receives the credential to propose back to its parent
- A client's monthly bill
- A forge for a client, from one link
- The client list's three times: sent, opened, first tell
- A forge whose billing is none
- A forge's claim link as a QR in the terminal
- A forge's own key and budgets
- A forge's size and use on /system
- A machine shell's first screen
- A new forge's first ten minutes
- A pinned forge
- Billing
- Buy a forge at /pricing
- What a paid forge is, at /terms
- Buy links
- Capacity flags a count set below its ceiling
- CPUs kept for the forge's own process
- Cloud accounts
- Disks on the machines page
- Does a forge I sent answer yet?
- End a forge link, and undo it
- What a forge link says when it no longer works
- Fleet rows
- Forge it
- /forges side by side
- Growth and the planner switch
- Hosted forges that scale to zero
- How fast a team ships, and what it costs
- How is my forge?
- How much each seat may do at once
- Is a forge name free?
- Machines
- Maintenance duty budgets
- Plans
- Real-cell proof: the build half, in process
- "Running" is proven from outside
- Start my forge
- Stripe checkout binding
- Telemetry readers
- The forge view (
GET /api/v1/forge/view) - The forge's spend in the terminal
- The last Stripe event and refused signatures
- The money line — cost, revenue and the gap
- The repository wallet — the last 20 spends
- A wallet running low — one line for admins under 20% left
- The page that answers "make me a forge"
- The Plan row in a forge's settings
- The selling funnel
- A taken forge name: refused with two free ones
- The spawner's claim link
- The statement — what the forge would charge an app
- Ways to the fleet graph
- What a forge costs
- What a sized forge's cores mean for builds
- What the forge stands on
- Where a sent forge link stands
- Your shells
Bring your own AI
Read with the guide page Bring your own AI.
- A child forge's cell may reach its model provider
- A forge with no model key
- A parent funds a child's crew
- Hosted forges' cores and the xlarge size
- A child's proposal says what the child proved
- An org's model account
- Cost ledger
- Cost by day
- Economics: the profit slider, its prices and what the month costs
- Escalate to Opus by need
- Issue cost: what an issue and its pulls spent
- Dependency standing: what an issue waits for, read at a glance
- Mirror credit
- The OpenAI-compatible runner
- The weekly model review
Agents: MCP, git, or the terminal
Read with the guide page Agents: MCP, git, or the terminal.
- AGENTS.md on every repository
- Atom feeds
- Guest pulls
- How a person with no account gets in to contribute
- OAuth consent words
- Connected agents
- OAuth refresh
- OAuth revoke
- OpenAPI and OAuth
- Opening /mcp in a browser
- Health, spoken in two sentences
- The desk over the API and the event stream
- Outside agents: a contribute token with no account
- Request access
- Security contact
- Security controls
- Stranger pulls
- The API reference
- The API root
- The fence: what the forge's agent reads is data
- The Muse test: how an outsider reports a problem
- Offering a patch with no account
- Sending one commit of a fork to its parent as a pull
- The report form for outsiders
- The receipt an outsider is handed for a report
- A team's effective share of builder slots
- Which harness holds a token
Backups and moving
Read with the guide page Backups and moving.
- A nightly backup that doubles
- A backup that stopped landing
- A data volume that is filling up
- A branch that cannot be backed up
- A forge is an origin
- A pull proposed to an origin, and its state coming back
- An app's encrypted backup, with a restore proof
- An overdue off-box backup
- Backups that cannot lie
- Connecting a friend's forge, whatever release it runs
- Connecting an origin read-only
- Forge-to-forge compatibility, measured
- How a fork follows its upstream
- Choosing how a fork follows, in three named choices
- Read an update before you take it
- An upstream update that conflicts is one issue
- Moving a forge out of this forge's process into its own sandbox
- Moving a platform app to the forge (gretchy-stretchy, #11687)
- Moving a repository to another owner
- New commits upstream, on a mirror
- Sending your forge's idea upstream, and pulling back
- Taking updates from an origin you follow
- The backups line on Resilience
- A backup that finishes on a slow line
- Hosted forges in the nightly backup
- The off-site backup lane
- The operator guard and proposing through your fork
- Which hosted forges are in use, and archiving one
Every setting, by topic
Read with the guide page Every setting, by topic.
- Account settings help
- Security, for a visitor
- Devices
- Edge-only accounts
- Knobs
- Manage account: reset a person's access
- Rotating the secret key
- Sent to sign in by an app, and back again
- Taking the forge's own name
- Ask for a new forge link
- Trusted sources
- Who can see it, in one line
- Your dotfiles in every shell
When something is wrong
Read with the guide page When something is wrong.
- /status says when it was read, and since when a row is not ok
- The machine's real size on /system and in health
- Where the bottleneck is: the line, CPU, checks, crew, memory and disk, each beside its lever
- A child forge the host stopped
- Cells that outlive the host, and are taken back on start
- A failed adapter pull speaks once in the writers' feed
- A failing webhook is said once
- A full disk
- A rebuild that stopped
- A repeated review comment becomes a check
- Batch doctor
- Blocked hosts
- Clog watch
- Content-Security-Policy reports
- Disk marks and the largest directories
- Disk readings per machine
- Events in the browser
- Flaky tests on main
- Flow: declined runs
- /flow: what is clogging the lane
- How long the event log keeps what it holds
- Interrupted out
- Load test
- Main-thread stalls by route
- Maintenance, last 7 days
- Memory held, not hit
- Memory by owner and growth across a stall
- Offline page
- Pages over budget (real visitors)
- Pausing a webhook
- Performance watcher
- Pulls drifting from main
- Re-checking checks a release cut
- Red batches, named
- Redeliver a failed webhook delivery
- Refused first asks
- Screens and sideways scroll in the check's vitals
- Send a webhook a test ping
- The crew does not build the same thing twice
- The from_app alarm
- The gate cannot lock itself out
- The lane has stopped
- The rule watcher
- Try again on an issue the crew parked twice
- What holds a ready issue
- Who liked a post
- The price of a forge, first on /pricing
- A claimed forge tells a stranger whose it is