> ## Documentation Index > Fetch the complete documentation index at: https://forst-lang.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # For agents > Compressed Forst usage for LLMs. Start here before reading full docs. Pair with /llms.txt or /llms-full.txt on this site. Use this page when generating or editing Forst (`.ft`) backend code. It is a **usage cheat sheet**, not a language spec. Fetch deeper pages only when you need one topic. ## Mintlify AI endpoints This site is Mintlify-hosted. Fetch these directly (no HTML): | Path | Use when | | -------------------- | --------------------------------------------------------------------------------------- | | `/llms.txt` | Page index with descriptions. Regenerated on every deploy. | | `/llms-full.txt` | Entire docs corpus in one Markdown file. Large. Prefer `/llms.txt` plus one topic page. | | `/resources/llms.md` | Forst usage rules. **Start here** for coding tasks. | | Any doc path + `.md` | One page as Markdown. Example: `/quickstart.md`. | Also available at `/.well-known/llms.txt` and `/.well-known/llms-full.txt`. Mintlify sends `Link` and `X-Llms-Txt` headers on every page so agents can discover the index. See [Mintlify llms.txt docs](https://www.mintlify.com/docs/ai/llmstxt). ## What Forst is Go-interoperable backend language. Source: `.ft` files. Output: Go you build with `go build`. Structural types carry validation constraints. TypeScript types come from the same tree via `forst generate`. ## Install and run Minimal install and compile commands: ```bash theme={"languages":{"custom":["/languages/forst.json"]}} npm install -D @forst/cli npx forst version npx forst run path/to/file.ft npx forst build path/to/file.ft -root ./my-service npx forst generate ./my-service npx forst test ./... ``` CI: set `FORST_BINARY` to a preinstalled compiler path. ## Typical layout Common project tree for a Forst backend: ```text theme={"languages":{"custom":["/languages/forst.json"]}} my-service/ ├── go.mod ├── handlers/orders.ft ├── internal/legacy.go ├── ftconfig.json # optional: generate / dev discovery └── generated/types.d.ts # often gitignored ``` Same-package `.ft` files merge when you pass `-root`. Go files and Forst files can live in one module. ## Syntax you must use | Topic | Rule | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Packages** | Go style: `package handlers`, `import "fmt"`, module paths from `go.mod`. | | **Types** | `type Name = { field: String, count: Int }`. Use `String`, `Int`, `Float`, `Bool`, `Array(T)`, `*T`, not `string`/`int` in Forst type positions. | | **Parameters** | Always annotated: `func f(x: OrderInput): Result(String, Error)`. | | **Records at call sites** | `placeOrder({ stockKeepingUnit: "A", quantity: 2 })`. | | **Constraints on fields** | `String.Min(1).Max(64)`, `Int.Min(1).Max(99)`, `Array(String).NotEmpty()`. Compiler emits boundary checks. | | **Runtime checks** | `ensure speed is LessThan(100) or TooFast({ ... })`. | | **Optional / errors** | `ensure err is Nil() or err`. No `try`/`catch`, no `panic`/`recover`. | | **Map lookup** | Returns `Result(V, Error)`. **No comma-ok.** `ensure avail is Ok()` then use `avail`. | | **Nominal errors** | `error InsufficientStock { stockKeepingUnit: String, ... }`. Use with `ensure ... or InsufficientStock({...})`. | | **Result returns** | `func f(): Result(String, Error) { return Ok("done") }`. Narrow with `ensure x is Ok()`. | | **Providers** | `use logger: Logger` inside body. Wire at entry with `with { Logger: prodLogger {} } { handler(input) }`. Params = request data. Providers = host services. | ## Constraints reference (common) | Type | Examples | | --------------- | ------------------------------------------------------------------------ | | `String` | `.Min(n)`, `.Max(n)`, `.NotEmpty()`, `.HasPrefix("x")`, `.Contains("x")` | | `Int` / `Float` | `.Min(n)`, `.Max(n)`, `.LessThan(n)`, `.GreaterThan(n)` | | `Array(T)` | `.Min(n)`, `.Max(n)`, `.NotEmpty()` | | `*T` | `.Nil()`, `.Present()` | | `Result` | `.Ok()`, `.Err()` in `ensure` | Chain with dots. Same names work on type fields and in `ensure`. ## CLI quick reference | Command | Purpose | | ----------------------------------------------- | -------------------------------- | | `forst run FILE.ft` | Transpile, build, run | | `forst build FILE.ft [-root DIR]` | Transpile and build only | | `forst generate [DIR\|FILE]` | Emit TypeScript from Forst types | | `forst dev -root DIR -port N` | HTTP dev server + discovery | | `forst test ./...` | Run Forst tests | | `forst fmt FILE.ft` | Format source | | `forst dump --file FILE.ft --phase typechecker` | Debug compiler | Flags: `-root` merges same-package `.ft` files; `-export-struct-fields` emits exported struct fields with `json` tags for wire serialization; `-log-level trace|debug|info|warn|error`. ## When writing code 1. Put validation on **types** at the HTTP boundary. Avoid manual `if len(s) < 1` when a constraint fits. 2. Keep **business failures** as nominal `error` types or `Result`, not string errors. 3. Thread **request payloads** through parameters. Use **`use` / `with`** for loggers, clocks, repos (not `context.Context` values). 4. Import real **Go packages** when needed (`fmt`, your module). Generated Go must compile with `go build`. 5. After edits, run `npx forst run` or `npx forst test` on the touched package. ## Do not invent | Avoid | Use instead | | ---------------------------------------- | ----------------------------------------------------------------------- | | Zod / class-validator patterns | Constraints on Forst shapes | | `try` / `catch`, thrown exceptions | `ensure`, `Result`, nominal `error` | | `v, ok := m[k]` | `Result` + `ensure v is Ok()` | | User-defined generics `` | Built-ins only: `Array(T)`, `*T`, `Result(S,F)` (generics roadmap item) | | DI frameworks, globals, service locators | `use` / `with` at entry points | | Providers in sidecar / TS emit | Wire providers in Go host; export data types only | ## Read more (single topic) | Task | Page | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | | First project | [Quickstart](/docs/quickstart) | | Shapes and constraints | [Shapes and constraints](/docs/language/shapes-and-constraints) | | `ensure` and narrowing | [Ensure and narrowing](/docs/language/ensure-and-narrowing) | | Errors and Result | [Errors and Result](/docs/language/errors-and-result) | | Providers | [Providers (DI)](/docs/language/providers) | | Go interop | [Go interop](/docs/interop/go) — subslices, variadic spread into Go calls, fields/methods on Go values, sibling Forst packages | | TypeScript emit | [Generate client types](/docs/interop/node/generate-types) | | Examples in repo | [github.com/forst-lang/forst/tree/main/examples/in](https://github.com/forst-lang/forst/tree/main/examples/in) |