# Tovuk agent guide

Tovuk deploys Rust backends, static frontends, and fullstack apps. Fullstack
apps use one root tovuk.toml, serve the frontend at `/`, and route `/api/*` to
the Rust backend.

Use the npm CLI unless the user already installed a persistent CLI:

```sh
npx tovuk doctor --json
npx tovuk deploy --wait --json
```

Reference: [Tovuk docs](https://docs.tovuk.com).

Agent repair loop:

1. Run `npx tovuk doctor --json`.
2. If it fails, read the first failed check.
3. Apply its `agent_instruction` exactly.
4. Rerun doctor until it passes.
5. Run `npx tovuk deploy --wait --json`.
6. If deploy fails, read `build_job.id` or the failed build id.
7. Run `npx tovuk logs --build <build_id> --json`.
8. Fix the first actionable log error.
9. Rerun doctor before redeploying.

Rust backend contract:

- `Cargo.toml`, `Cargo.lock`, and `tovuk.toml` are committed.
- `[build].check` includes `cargo fmt --all --check`.
- `[build].check` includes `cargo check --locked`.
- `[build].check` includes
  `cargo clippy --locked --all-targets --all-features -- -D warnings`.
- The server listens on `0.0.0.0:$PORT`.
- The configured health path returns HTTP 200.
- Direct `unsafe` is not allowed in workspace source.

Static frontend contract:

- `kind = "static_frontend"` is set in `tovuk.toml`.
- `package.json` is committed.
- A package lockfile is committed.
- Browser source is `.ts` or `.tsx` under `src`, `app`, `pages`, `routes`, or
  `components`.
- `package.json` has `typecheck`, `lint`, and `build` scripts.
- `typecheck` runs stable native type-aware TypeScript checks such as
  `oxlint --type-aware --type-check`.
- `lint` runs native tooling such as `oxlint`, `biome check`, or `deno lint`.
- `lint` also runs Fallow `dead-code`, semantic `dupes`, and `health` gates.
- `[build].check` installs dependencies and runs package scripts for typecheck
  and lint.
- Weak typecheck, fake lint, missing Fallow quality gates, and
  JavaScript-based lint/format scripts are rejected for deploys.
- JavaScript and TypeScript are frontend-only. API routes, SSR handlers,
  middleware, and server logic must move to the Rust backend.

Plain static frontend contract:

- `index.html` is committed.
- `kind = "static_frontend"` is set in `tovuk.toml`.
- `[build].check = ":"`, `[build].command = ":"`, and `[build].output = "."`.

Fullstack contract:

- One root `tovuk.toml` sets `kind = "fullstack"`.
- `[backend].root` points to the Rust backend.
- `[frontend].root` points to the static frontend.
- The frontend calls same-origin `/api`.
- The backend health path is `/api/healthz`.
- Backend build and runtime commands must use `cargo build --release` and a
  `./target/release/*` Rust binary, never Node, Bun, Deno, or TS runtimes.

Useful commands:

```sh
npx tovuk capabilities --json
curl https://api.tovuk.com/v1/status
npx tovuk activity --json
npx tovuk apps --json
npx tovuk overview --app <app> --json
npx tovuk builds --app <app> --json
npx tovuk logs --build <build_id> --json
npx tovuk logs --app <app> --json
npx tovuk env list --app <app> --json
npx tovuk domains list --app <app> --json
npx tovuk billing checkout --json
npx tovuk support list --json
npx tovuk support create "Deploy failed" "Agent retried deploy after doctor." --app <app> --build <build_id> --deploy <deploy_id> --failing-command "npx tovuk deploy --wait --json" --first-log-line "first actionable log line" --json
npx tovuk support resolve <ticket_id> --json
```

Use `GET /v1/status` only when Tovuk itself appears unavailable. If the API is
available and a deploy fails, inspect build logs instead of changing status
checks.

Never print or commit secrets. Put secrets in Tovuk env vars with
`npx tovuk env set --app <app> KEY=value`.

When a free-tier limit blocks work, run
`npx tovuk billing checkout --json` and show the returned URL to the
human. When Tovuk support is needed, create a ticket only after collecting the
failing command, app id, build id, deploy id, first actionable log line, and
what the agent already tried. Resolve the ticket when the issue is fixed so
future agents do not duplicate the same support work.