docs(kiln): add the Kiln product tab

docs.json

@@ -730,6 +730,48 @@
           }
         ]
       },
+      {
+        "tab": "Kiln",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "kiln/index",
+              "kiln/getting-started"
+            ]
+          },
+          {
+            "group": "GitHub Actions",
+            "pages": [
+              "kiln/actions/runs-on",
+              "kiln/actions/sizes",
+              "kiln/actions/templates-and-regions",
+              "kiln/actions/run-as"
+            ]
+          },
+          {
+            "group": "Caching",
+            "pages": [
+              "kiln/cache/index",
+              "kiln/cache/settings"
+            ]
+          },
+          {
+            "group": "Organization settings",
+            "pages": [
+              "kiln/settings/ci-defaults",
+              "kiln/settings/limits-and-priority"
+            ]
+          },
+          {
+            "group": "Reference",
+            "pages": [
+              "kiln/reference/runs-on-grammar",
+              "kiln/roadmap"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Changelog",
         "hidden": true,

kiln/.sync.json

@@ -0,0 +1,5 @@
+{
+  "generatedFrom": "trunk-io/trunk-cloud",
+  "sourceRef": "firewatch-kiln-docs",
+  "sourceSha": "948fdb07d44d9eb99f4ff791ddae442c11c65372"
+}

kiln/actions/run-as.mdx

@@ -0,0 +1,45 @@
+---
+title: "Run as a user"
+description: "Run a job as the person who started it, not a shared CI identity."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+<Warning>
+  This feature is in Beta. It may be off for your organization. Ask the Trunk
+  team to turn it on.
+</Warning>
+
+By default, a Kiln job runs as a shared CI identity. With `run-as`, a job runs as
+the real person who started it. This makes the job's actions and logs belong to
+that person.
+
+Trunk finds the person from the GitHub event that started the job. You do not name
+a user in the label. The label only says that the job should run as its actor.
+
+## Modes
+
+Add `run-as` with one of two modes:
+
+| Mode                | When it applies                                                      |
+| ------------------- | -------------------------------------------------------------------- |
+| `run-as=dispatcher` | A run you start by hand (`workflow_dispatch`) on the default branch. |
+| `run-as=actor`      | A `push` or a pull request on any branch.                            |
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..run-as=dispatcher
+```
+
+## Rules
+
+- **The job never fails because of `run-as`.** If Trunk cannot find the person,
+  the job runs as the shared CI identity instead.
+- **A pull request from a fork does not run as a user.** Trunk refuses it for
+  safety.
+- **The person must be a member of your organization.**
+
+<Info>
+  Use `run-as` when a job acts on a person's behalf, such as a coding agent that
+  works in the job. The job then uses that person's identity.
+</Info>

kiln/actions/runs-on.mdx

@@ -0,0 +1,65 @@
+---
+title: "The runs-on label"
+description: "One label selects the Kiln runner and sets its options."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+You point a job at Kiln with one `runs-on` label. The label starts with the Kiln
+anchor and adds options after it. Each option uses `key=value`, and `..` joins the
+options.
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium
+```
+
+<Note>
+  The anchor holds a unique value per run: `${{ github.run_id }}-${{
+  github.run_attempt }}`. This value keeps each job on its own runner, so one job
+  never takes another job's runner.
+</Note>
+
+## Options
+
+| Option     | Required | What it sets                                                                                                         |
+| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `size`     | Yes      | The machine size, which sets the CPU count. See [Machine sizes](/kiln/actions/sizes).                                |
+| `memory`   | No       | `high` for 4 GiB per CPU instead of 2. See [Machine sizes](/kiln/actions/sizes).                                     |
+| `template` | No       | The template (a prepared environment) for the job. See [Templates and regions](/kiln/actions/templates-and-regions). |
+| `region`   | No       | The region for the job. See [Templates and regions](/kiln/actions/templates-and-regions).                            |
+| `cache`    | No       | `kiln` or `github` to choose the cache. See [Caching](/kiln/cache/index).                                            |
+| `run-as`   | No       | Run the job as the person who started it. See [Run as a user](/kiln/actions/run-as).                                 |
+
+Only `size` is required. If you leave out `template` or `region`, the job uses
+your [organization defaults](/kiln/settings/ci-defaults).
+
+## Examples
+
+A medium runner with high memory:
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large..memory=high
+```
+
+A job on a chosen template and region:
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..template=<template-id>..region=us-west
+```
+
+## Rules
+
+- **A wrong key fails the job with a clear message.** A typo never runs the wrong
+  machine.
+- **The order of the options does not matter.**
+- **Keys are not case-sensitive.**
+- **A key must not repeat.**
+
+<Warning>
+  If a job does not start, read the job's error message first. Kiln reports the
+  exact reason, such as an unknown option or a missing `size`.
+</Warning>
+
+See the [full label format](/kiln/reference/runs-on-grammar) for every option in
+one table.

kiln/actions/sizes.mdx

@@ -0,0 +1,46 @@
+---
+title: "Machine sizes"
+description: "Pick a size to set the CPU count. Ask for high memory when a job needs it."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+The `size` option sets the CPU count of the runner. `size` is required in the
+`runs-on` label.
+
+## Sizes
+
+| Size     | CPUs |
+| -------- | ---- |
+| `xsmall` | 1    |
+| `small`  | 2    |
+| `medium` | 4    |
+| `large`  | 8    |
+| `xlarge` | 16   |
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large
+```
+
+<Note>
+  There is no default size. You must set `size` on every Kiln job. A missing or
+  unknown size fails the job with a clear message.
+</Note>
+
+## Memory
+
+By default, a runner has 2 GiB of memory per CPU. When a job needs more, add
+`memory=high` for 4 GiB per CPU. The size still sets the CPU count.
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large..memory=high
+```
+
+A `large` runner with `memory=high` has 8 CPUs and 32 GiB of memory.
+
+<Tip>
+  Start with a size that matches your job. Add `memory=high` only for a job that
+  runs out of memory, such as a large build or a test suite that holds a lot of
+  data.
+</Tip>

kiln/actions/templates-and-regions.mdx

@@ -0,0 +1,40 @@
+---
+title: "Templates and regions"
+description: "Run a job on a chosen template or region, or use your organization defaults."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+A job can run on a chosen template or in a chosen region. If you do not choose,
+the job uses your [organization defaults](/kiln/settings/ci-defaults).
+
+## Templates
+
+A template is a prepared environment for a job. It holds the tools and the setup
+your jobs need, so a job starts ready. Your organization admin creates templates
+and sets an organization default.
+
+Add `template` to run a job on a chosen template:
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..template=<template-id>
+```
+
+If you leave out `template`, the job uses the organization default template.
+
+## Regions
+
+A region is the location where the job runs. Your organization admin sets a
+default region. Add `region` to run a job in a chosen region:
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..region=us-west
+```
+
+If you leave out `region`, the job uses the organization default region.
+
+<Info>
+  Ask your organization admin for the template IDs and the regions your
+  organization can use.
+</Info>

kiln/cache/index.mdx

@@ -0,0 +1,46 @@
+---
+title: "Caching"
+description: "The shared cache lets jobs reuse build results, so they finish faster."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+Kiln has a shared build cache. Jobs reuse build results across runs, so they
+finish faster. The cache is on by default.
+
+## What the cache supports
+
+The shared cache works with the GitHub Actions cache and common build tools:
+
+- The GitHub Actions cache (`actions/cache`)
+- `sccache`
+- `bazel`
+- `gradle`
+- `ccache`
+
+Common build-tool lanes work with no setup. To choose the cache for the GitHub
+Actions cache on one job, use the `cache` option.
+
+## The cache option
+
+Add `cache` to the `runs-on` label to choose the cache for a job:
+
+| Value          | Effect                                                  |
+| -------------- | ------------------------------------------------------- |
+| `cache=kiln`   | Use the Kiln shared cache for the GitHub Actions cache. |
+| `cache=github` | Use the GitHub cache for that job.                      |
+
+```yaml
+runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..cache=kiln
+```
+
+<Info>
+  A fork pull request gets read-only cache access. A push to your own repository
+  can write to the cache.
+</Info>
+
+## Turn the cache on or off
+
+An admin can turn the shared cache off, per repository or for the whole
+organization. See [Cache settings](/kiln/cache/settings).

kiln/cache/settings.mdx

@@ -0,0 +1,36 @@
+---
+title: "Cache settings"
+description: "Turn the shared cache on or off, per repository or for the organization."
+groups: ["firewatch"]
+---
+
+{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */}
+
+The shared cache is on by default. An admin can turn it off. This page shows the
+settings and who can change them.
+
+## Where the setting applies
+
+| Level        | What it controls                  |
+| ------------ | --------------------------------- |
+| Repository   | The cache for one repository.     |
+| Organization | The default for every repository. |
+
+The repository setting wins over the organization default. If a repository has no
+setting, the job uses the organization default. If the organization has no
+default, the cache is on.
+
+## Who can change it
+
+An **organization admin** or a **repository admin** on GitHub can change the
+setting.
+
+## Turn the cache off for one job
+
+To keep the cache on but skip it for one job, add `cache=github` to the job's
+`runs-on` label. See [Caching](/kiln/cache/index).
+
+<Note>
+  When you turn the cache off, jobs stop reading and writing the shared cache. A
+  job that already started keeps its cache until it ends.
+</Note>