# AGENTS.md — `@celilo/cli`

Celilo is a **home-lab orchestration system**: you describe infrastructure as
**modules**, and celilo deploys them onto a fleet (Proxmox LXC/VM) and wires them
together through versioned **capabilities**. This file orients an AI agent to
build and ship apps on celilo. **Read the local docs below before searching the
web** — they are the source of truth; the hosted copies at
`https://celilo.computer/docs` lag them.

## Mental model (learn these five things)

- **Module** — a directory with a `manifest.yml` and `celilo/scripts/` hooks,
  packaged into a `.netapp` artifact and published to **celilo-registry**.
  Everything celilo deploys is a module.
- **Capability** — a module `provides:` capabilities (e.g. `public_web`, `idp`,
  `source_forge`) at a **versioned contract**, and consumers `requires:` them.
  Consumers bind to the **capability** version (`provides.capabilities[].version`)
  — *not* the module's own `version`. Bump the capability version on a contract
  change; that's the load-bearing semver.
- **Hook** — a lifecycle script (`on_install`, `health_check`, `on_backup`, …) in
  `celilo/scripts/`, written with `defineHook(...)` from `@celilo/capabilities`.
  Hooks receive typed clients for the capabilities they `requires`/`optional`.
- **Build bus** — app repo CI publishes a `.netapp` to celilo-registry →
  celilo-mgr **polls** → `module upgrade` → deploy → verify. No manual hop.
- **Versioning** — `manifest.yml#version` is the **payload** version; `+N` is the
  recipe revision; `version_source` declares how the version is set. See below.

## Building an app (the happy path)

An **app** is a module that provides no capability (it serves content), so set
`version_source: { kind: changeset }`.

1. **`manifest.yml`** — `id` (kebab-case), `celilo_contract: "1.0"`, `version`,
   the capabilities you `requires:` (e.g. `public_web`, `idp`), `variables`,
   `hooks`, and `version_source`. Keep the schema directive on line 1 so your
   editor validates:
   `# yaml-language-server: $schema=../../schemas/module-manifest.schema.json`
2. **Hooks** in `celilo/scripts/` — at least `on_install` (provision) and
   `health_check`. Use `defineHook`; required capabilities are typed non-null.
3. **CI/CD** — copy the reference workflows + add the `register-forge` deploy
   hook so your repo gets a scoped publish token (see `APP_CI_REFERENCE.md`).
4. **Version with changesets** — `celilo module changeset --bump <major|minor|
   patch>` in each behaviour-changing PR; `celilo module version` stamps
   `manifest.yml#version` + CHANGELOG at release. Pick the bump by deploy **blast
   radius** (major ⇒ safe deploy w/ backup; patch ⇒ fast).
5. **Ship** — `celilo module check .` then `celilo module publish .`. On the
   fleet: `module update` (registry sweep) → `module deploy <id>` → `module
   health`.

## CLI you'll use

```
celilo module import <name|path>        # pull a module
celilo module check [dir]               # validate: schema, capabilities, git-hygiene
celilo module changeset --bump <b> -m … # author a version changeset (module-id keyed)
celilo module version [dir]             # stamp version+CHANGELOG from changesets
celilo module publish [dir]             # build .netapp + publish to celilo-registry
celilo module deploy <id> / update / health   # deploy + verify on the fleet
```

## Conventions / rules

- Module `id` is **kebab-case**; pin `celilo_contract: "1.0"`.
- **`version_source`** picks how `version` is sourced: `changeset` (apps/content —
  authored via changesets, ordered by `+N`), `pin` (wraps upstream software —
  `version` = the installed upstream version, resolver-checked), `recipe`
  (config-only modules — no payload version; `+N` orders). Default `recipe`.
- The capability **contract** semver lives in `provides.capabilities[].version`,
  independent of the module `version`. Don't conflate them.
- **Never hand-edit `schemas/module-manifest.schema.json`** — it's generated from
  `src/manifest/schema.ts` via `bun run export:schema`.
- Validate before publishing; `celilo module check` mirrors the publish gates.

## Doc map (read in this order)

- `./CELILO_SUBSYSTEMS.md` — map of the infrastructure primitives celilo already
  implements (IPAM, capabilities, firewall/DNS, generator, …), with entry-point files.
- `./CELILO_CORE_MODULES.md` — the production modules celilo ships in `modules/`
  (what each provides/requires, its role in the fleet).
- `../../reference/MODULE_DEVELOPMENT_GUIDE.md` — author a module (start here).
- `./MODULE_PRIMITIVES.md` — the remote-ops primitives a hook uses to touch a box
  (probe / serviceCtl / applyRenderedConfig / waitFor / …). **Modules never
  hand-build SSH** — read this before writing any hook that reaches a remote host.
- `./CLI_USAGE.md` — full CLI reference + workflows.
- `../../openspec/changes/build-bus-poll-cd/proposal.md` — how a change reaches the fleet.
- `../../reference/APP_CI_REFERENCE.md` — wire an app's CI/CD (the copy-me recipe).
- `../../openspec/changes/module-version-semantics/proposal.md` — what `version` means; `version_source`.
- `../../schemas/module-manifest.schema.json` — the manifest contract.
- `https://celilo.computer/docs` — hosted docs (LAN; the repo docs lead).