Reference

`.terrace.yml`

An optional file at the root of your repository. Terrace reads it on every survey and merges it into the hill. Use it for what the code can’t show: where things really run, why a folder exists, which other repos belong to the same system.

The quickest way to write one: open your terrace, add notes and declare hosts in the viewer, then chooseExport .terrace.yml. It opens GitHub’s new-file page with the content filled in.

Example

hosting:
  - name: Neon Postgres
    kind: database
    description: Primary database for the API
    url: https://neon.tech
    from: [app:worker]
  - name: Cloudflare R2
    kind: object storage
    from: [app:worker]

notes:
  repo: The public site and API for Lantern.
  folder:infra: Only the platform team edits this.
  fw:hono: Chosen for its tiny cold start on Workers.

related:
  - lantern-org/lantern-mobile
  - lantern-org/lantern-infra

Fields

Key	What it does
`hosting`	A list of hosts added to the summit. Each needs a `name`; `kind`, `description`, `url` (http/https only) and `from` are optional. Up to 20.
`hosting[].from`	Stone ids (or app names) that this host is built from. Draws the threads up to it.
`notes`	A map of stone id → text, shown as the owner’s note on that stone. Up to 1,000 characters each.
`related`	Up to 8 `owner/repo` names drawn as neighbouring hills.

Stone ids

Every stone has a stable id. You can see it in the viewer’s export, or build it from these patterns:

Terrace	Pattern	Example
Repository	`repo`, `doc:readme`, `doc:license`, `doc:docs`	`repo`
Folders	`folder:<top-level folder>`, `folder:.` for root files	`folder:src`
Languages	`format:<id>`	`format:typescript`
Frameworks	`fw:<id>`	`fw:astro`
Apps	`app:<folder path>`, `app:root`	`app:packages/api`
Hosting	`host:<id>`, `declared:<slug of name>`	`host:cloudflare-workers`

Rules

The file is parsed defensively: anything malformed is ignored rather than breaking the survey.
Terraces are cached for 30 minutes, so a new .terrace.yml can take that long to appear.
.terrace.yaml works too.