# Control Plane Setup Apply Guide

This guide explains how to run `cmd/setup apply` correctly for local development.

## Why This Exists

`backend/cmd/server` is read-only for metadata and performs readiness checks on startup.
If required schema/metadata state is missing, startup fails and asks you to run:

```bash
go run ./cmd/setup apply
```

## Recommended Local Flow

From repo root:

```bash
bash -lc 'source ./scripts/runtime-env.sh && nexus_export_runtime_env "$PWD" && make setup'
```

Then verify:

```bash
bash -lc 'source ./scripts/runtime-env.sh && nexus_export_runtime_env "$PWD" && make setup-verify'
```

Then start app:

```bash
npm run dev
```

## Why Use `bash -lc`

`scripts/runtime-env.sh` uses bash-specific expansion and should not be sourced directly in zsh.
The `bash -lc` wrapper ensures `.env` loading and exported runtime vars work consistently.

## Common Errors

### `Readiness verification failed — run 'go run ./cmd/setup apply' first`

Database is reachable, but required managed schema/metadata state is missing.
Run `make setup` against the same DB used by server startup.

### `/sobjects/_System_File/describe` returns `404`

That usually means the managed `_System_File` metadata row was soft-deleted in
`_System_Object`. Run `make setup` to restore managed system-object visibility
before retrying the server. The file runtime still uses `_System_File`; the
legacy `Content*` tables remain compatibility-only.

### `nexus_load_env_file:... bad substitution`

You sourced `runtime-env.sh` in zsh. Re-run with `bash -lc '...'`.

## CI/Deploy Relationship

- Local dev: run setup manually (`make setup`) before server startup.
- Deploy environments: container entrypoint runs setup automatically before server.