Forelead handbook

This is the internal handbook for Forelead. It explains how the platform works, how to run it, and what its API looks like. It is for Forelead people only.

Every page starts with plain words and puts the technical detail after. Each page ends with the files in the platform repository that it is based on. If a page and the code disagree, the code wins: fix the page.

Start here

• How does a task get from Ready to merged? A task's life
• What runs where? Architecture
• Why can't an agent do that? Security model
• I need to upgrade, restart or roll back. Upgrade and rollback and Restarts and leases
• Something is red. Failure signatures
• What can I call? Browser API, runner protocol, broker and gateway
• The full existing documents (deploy guide, design notes) are under Full documents.

How this site is built

The site is built from the platform repository on every change. The API reference comes from the same bundled OpenAPI file the web app uses, and a test in web/ fails when the Go routes and that file disagree. There are no secrets in this site: the secrets page lists names, paths and owners only, and a build check fails on anything shaped like a key or token. See the handbook README in handbook/README.md.