Flisk Generated Files

---
name: flisk-generated-files
description: Understand which files Flisk owns (everything under `.autogenerated/` and `.flisk/.flisk-out/`), check them for drift with `flisk config verify` and `flisk config explain`, and regenerate them with `flisk up` or `flisk config regenerate`. Use when `flisk up` refuses to start because generated files differ from service.json, when a generated Dockerfile, nginx, Vite, tsconfig or env file looks wrong, or when reviewing what the CLI writes. To change what gets generated, edit service.json (see flisk-service-json).
license: MIT
compatibility: Requires the flisk CLI. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Generated files and drift

Flisk writes the local runtime files from each `service.json`. You own the contract; the CLI owns the generated wiring.

## Who owns what

| File | Owner |
| --- | --- |
| `service.json`, `.flisk/project.json`, the project `.env`, your app code and `package.json` | You |
| `services/<stack>/<name>/.autogenerated/*` (Dockerfile, nginx, Vite, tsconfig, env files, `service.yaml`, `api-client.ts`) | Flisk |
| `.autogenerated/.flisk-contract/` (snapshots for drift detection) | Flisk |
| `.flisk/.flisk-out/` (the Tiltfile and the vendored engine) | Flisk, git-ignored |

## Workflow

1. Change only the source: `service.json`, `.flisk/project.json`, or your code.
2. Run `flisk up` (or `flisk up --dry-run` to only check). It regenerates the service files and refuses to start when a generated file was edited by hand, naming the file.
3. To check without starting anything: `flisk config verify --json` compares the project contract, every `service.json` and the file snapshots. It reports and never blocks.
4. To ask about one file: `flisk config explain <path>` says whether Flisk generates it, from which input, and whether editing it blocks `flisk up`.
5. To rewrite the project-level files from `.flisk/project.json`: `flisk config regenerate`. After a schema change, `flisk config migrate` updates old `service.json` files.

## If a hand edit blocks `flisk up`

1. Move the intended change into `service.json`, the project config or the generator.
2. Regenerate with `flisk up` (service files) or `flisk config regenerate` (project files).
3. Only when the user asks to start anyway: `flisk up --ignore-drift`. The edit is lost on the next regeneration.

## Guardrails

- Never commit hand edits to `.autogenerated/` files.
- If a generated file is wrong for a valid `service.json`, the fix belongs in the generator in flisk-sh/flisk, not in the output.
- Full list of outputs per service type: [docs/generated-files.md](https://github.com/flisk-sh/flisk/blob/main/docs/generated-files.md).