# Files in your repository

> The files Stableship reads from your repository, and the ones your coding agent commits for it.

Stableship never writes to your repository. Your coding agent writes these files when you ask it to, from `get_repo_files`.

## .gate/rules.md

Your rules as plain sentences grouped by area, then a fenced `json` block with the full rules. The `json` block is what Stableship reads: editing only a sentence changes nothing. Change the block and push to your default branch, and the change comes back to Stableship as a rule suggestion. It is never applied directly when it lets more people see or change something. A file that matches the rules in use, or whose block does not parse, is ignored.

## .gate/context.md

Your product notes, one per line below a marker. Push a change to your default branch and the notes in Stableship are replaced with the file's.

## The Stableship section of AGENTS.md

A section between these markers tells every session of your agent how to use the rules and the tools:

```text
<!-- stableship:start -->
…
<!-- stableship:end -->
```

`get_repo_files` returns your `AGENTS.md` as it is on your default branch, with that section added or replaced. Nothing outside the markers changes. If your repository has a `CLAUDE.md` or a `replit.md`, put the same section there.

## .gate/build.yaml

You write this one, and only when Stableship cannot work out how to build and start your app on its own. Flat `key: value` lines:

```yaml
install: pnpm install
build: pnpm build
start: pnpm start
port: 3000
root: apps/web
health: /api/health
```

| Key | Means | Default |
|---|---|---|
| `start` | The command that starts the app. Required. | |
| `install` | The command that installs dependencies. | Detected |
| `build` | The command that builds the app. | Detected |
| `port` | The port the app listens on. | 3000 |
| `root` | The folder the app lives in. | The repository root |
| `health` | A path that answers once the app is ready. | `/` |

A committed `.gate/build.yaml` wins over what Stableship detects.

## STABLESHIP_FIXES.md

The fix plan, if you choose to keep it in the repository: every open problem as an ordered task. See [Fix what Stableship found](/docs/guides/fix-loop).