# @kody/fly — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
**name** only — never paste token values. Do not disable live webhooks or jobs
(the bundled `machine-status` job stays `enabled: false` unless the operator
turns it on after a fork).

## Secrets

| Name | Purpose |
| --- | --- |
| `flyApiToken` | Machines REST, GraphQL, logs, Prometheus |
| `flyApiToken-<label>` | Extra account via `account: "<label>"` or `secretName` |

Hosts: `api.machines.dev` (Machines REST, Bearer), `api.fly.io` (GraphQL /
logs / Prometheus, Bearer / FlyV1).

## Import paths

| Export | Import |
| --- | --- |
| root dispatcher (default `smoke-test`) + re-exports | `kody:@kody/fly` |
| organizations | `kody:@kody/fly/organizations` |
| apps | `kody:@kody/fly/apps` |
| machines (list/get/start/stop/destroy) | `kody:@kody/fly/machines` |
| machine-count | `kody:@kody/fly/machine-count` |
| app-machines | `kody:@kody/fly/app-machines` |
| logs | `kody:@kody/fly/logs` |
| metrics | `kody:@kody/fly/metrics` |
| graphql | `kody:@kody/fly/graphql` |
| docs / discovery metadata | `kody:@kody/fly/docs` |
| smoke-test | `kody:@kody/fly/smoke-test` |
| scheduled-status | `kody:@kody/fly/scheduled-status` |

Prefer static `kody:@kody/fly/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

Without `flyApiToken` returns `{ ok: true, live: false }` plus the setup URL.
With the secret saved it lists organizations and a sample of apps — no writes.

```js
import smokeTest from 'kody:@kody/fly/smoke-test'

export default async function main() {
	return await smokeTest()
}
```

Equivalent via root dispatcher:

```js
import fly from 'kody:@kody/fly'

export default async function main() {
	return await fly()
}
```

List apps:

```js
import fly from 'kody:@kody/fly'

export default async function main() {
	return await fly({
		action: 'list-apps',
		organizationSlug: 'my-org',
	})
}
```

## dryRun / confirm

Pass `dryRun: true` on `startMachine`, `stopMachine`, or `destroyMachine` to
return `{ dryRun: true, method, path }` without contacting Fly.
`destroyMachine` also throws unless `confirm: true`.
Do not destroy anyone's machines from a smoke test or scheduled job.

```js
import { startMachine, destroyMachine } from 'kody:@kody/fly/machines'

export default async function main() {
	const preview = await startMachine({
		appName: 'my-app',
		machineId: '148e26d9b3e089',
		dryRun: true,
	})
	return preview
}
```

## Edge cases

- No Fly app names or organization slugs are baked in — callers supply them.
- When `organizationSlug` is omitted and the token sees multiple orgs, pass an
  explicit slug.
- Do not enable the `machine-status` job on the official listing; after a fork,
  enable only if the operator wants the periodic read.