# Create Overlay Command

`bin/railiance create-overlay` scaffolds a local Railiance overlay repo for a
third-party upstream application.

The command is intentionally local and conservative:

- records the upstream source in `railiance/upstream.toml`;
- generates a stage-aware `railiance/app.toml`;
- creates a starter Helm chart, stage values, tests, and runbooks;
- initializes only local files and directories;
- does not clone upstream code, create remotes, fetch secrets, or push
  anything.

## Usage

```bash
bin/railiance create-overlay \
  --app-id forgejo \
  --upstream-url https://codeberg.org/forgejo/forgejo \
  --name Forgejo \
  --owner platform \
  --criticality high \
  --init-git
```

The generated Service is explicitly `ClusterIP`, a default-deny ingress
NetworkPolicy is included, and Stage 2 does not emit an Ingress. Enabling an
Ingress later requires matching rapp and reef declaration files at the
Stage 2 deploy gate; an Ingress object is not itself an ADR-0008 grant.

Required arguments:

- `--app-id`
- `--upstream-url`

Useful optional arguments:

- `--name`
- `--owner`
- `--criticality`
- `--upstream-revision`
- `--upstream-tracking`
- `--out-dir`
- `--init-git`

## Generated Structure

The scaffold creates:

- `README.md`
- `railiance/upstream.toml`
- `railiance/app.toml`
- `charts/<app-id>/templates/`
- `values/`
- `patches/upstream/`
- `tests/`
- `runbooks/`
- `docs/`

The output is a compatibility-era overlay starting point on the path toward
future `rapp-*` packaging. It keeps the current migration window usable without
moving workload ownership into `rail-kubernetes`.