# SetupManifest Reference (`setup.aiwg.io/v1`)

## Overview

`setup.aiwg.io/v1` is a Kubernetes-style YAML language for declaring cross-platform,
software installation. A SetupManifest declares a platform matrix,
user-facing parameters, prerequisite checks, OS-level configuration entries, ordered
installation steps, and named recovery procedures. Manifests are validated, executed,
and authored by the **agentic-installer** addon.

The default `deterministic` execution mode is script-first: `agentic` steps are
reserved for exception handling and adaptive recovery. The
`provider-orchestrated` mode is for a manifest deliberately interpreted by a
capable AI provider, such as AIWG's public install/repair flow. It may use
reasoning steps as its primary workflow because inspection, authorization, and
non-destructive repair vary by machine and project. `aiwg setup-run` executes
only deterministic manifests.

The authoritative JSON Schema lives at
`agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`. This
document mirrors that schema; on conflict the schema wins.

## File Location and Discovery

By convention manifests live at `setup.manifest.yaml` in the project root. The
agentic-installer runtime commands (`setup-generate`, `setup-validate`,
`setup-run`) are agent-facing CLI surfaces. `setup-validate` and `setup-run`
accept a manifest path or `--manifest`; otherwise they look for
`setup.manifest.yaml` relative to the working directory. `setup-generate` writes
a starter manifest to `--output` or `setup.manifest.yaml`.

## Top-Level Structure

```yaml
apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata: { ... }
spec:
  platforms: [ ... ]
  params: [ ... ]
  prerequisites: [ ... ]
  os_config: [ ... ]
  steps: [ ... ]
  recovery: [ ... ]
  briefing: { ... }
```

| Field        | Type                       | Required | Description                         |
| ------------ | -------------------------- | -------- | ----------------------------------- |
| `apiVersion` | const `"setup.aiwg.io/v1"` | yes      | API version literal.                |
| `kind`       | const `"SetupManifest"`    | yes      | Resource kind literal.              |
| `metadata`   | object                     | yes      | Identity and audience info.         |
| `spec`       | object                     | yes      | Platform matrix and execution plan. |

`additionalProperties: false` at every object — unknown fields are rejected.

### `metadata`

| Field          | Type         | Required         | Description                   |
| -------------- | ------------ | ---------------- | ----------------------------- |
| `name`         | string       | yes              | Identifier for this manifest. |
| `description`  | string       | optional         | Free-form description.        |
| `version`      | string       | optional         | Manifest version.             |
| `install_type` | enum (below) | optional, `user` | Audience tag.                 |
| `execution_mode` | enum (below) | optional, `deterministic` | Runtime contract. |

`install_type` values: `user` (production deploy), `developer` (local dev environment),
`ci` (headless pipeline setup). Only `developer` manifests may use `os_config`.

`execution_mode` values:

- `deterministic` — executable through `aiwg setup-run`; use scripts for known work.
- `provider-orchestrated` — give the manifest URL or contents to a supported AI
  provider. The CLI validates it but returns a handoff message instead of executing it.

### `spec`

| Field           | Type                        | Required | Description                                                                 |
| --------------- | --------------------------- | -------- | --------------------------------------------------------------------------- |
| `platforms`     | `Platform[]`                | yes (≥1) | Supported platform targets. Installer refuses to run on unlisted platforms. |
| `params`        | `Param[]`                   | optional | User-facing parameters resolved before any step executes.                   |
| `prerequisites` | `Prerequisite[]`            | optional | Prerequisite checks run before any step. Required ones abort if missing.    |
| `os_config`     | `OsConfigEntry[]`           | optional | OS-level configuration entries (developer manifests only).                  |
| `steps`         | `Step[]`                    | yes (≥1) | Ordered installation steps.                                                 |
| `recovery`      | `RecoveryProcedure[]`       | optional | Named recovery procedures referenced by steps via `on_fail`.                |
| `briefing`      | `{ success?, next_steps? }` | optional | Messages delivered on completion.                                           |

## Platform Matrix

```yaml
platforms:
  - os: linux
    distros: [ubuntu, debian, fedora]
    arch: [x86_64, arm64]
    shell: bash
```

| Field     | Type / values | Description                     |
| --------- | ------------- | ------------------------------- |
| `os`      | enum (below)  | OS family. Required.            |
| `distros` | string[]      | Optional distro filter (Linux). |
| `arch`    | string[]      | Optional architecture filter.   |
| `shell`   | enum (below)  | Shell context.                  |

- `os` values: `linux`, `macos`, `windows`, `docker`
- `distros` values: `ubuntu`, `debian`, `fedora`, `rhel`, `rocky`, `centos`, `arch`, `alpine`
- `arch` values: `x86_64`, `arm64`, `aarch64`
- `shell` values: `bash`, `zsh`, `sh`, `wsl2` (WSL2 bash on Windows), `native` (PowerShell/cmd)

## Params

User-facing parameters resolved before any step runs. Names use UPPER_SNAKE_CASE;
values are passed to scripts as env vars.

| Field                  | Type                  | Description                                                                                                                                                          |
| ---------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | string                | Env-var-style name (UPPER_SNAKE_CASE). Required.                                                                                                                     |
| `type`                 | enum (below)          | Value type. Required.                                                                                                                                                |
| `default`              | any                   | Default if not provided by user.                                                                                                                                     |
| `required`             | bool, default `false` | Whether the param must be supplied.                                                                                                                                  |
| `description`          | string                | Human-readable explanation.                                                                                                                                          |
| `choices`              | string[]              | Valid values when `type: choice`.                                                                                                                                    |
| `interactive_required` | bool, default `false` | Force interactive prompt; cannot be pre-filled by default. Use when a wrong default would cause OS configuration changes (SSH key email, GPG key ID, preferred IDE). |

`type` values: `string`, `path` (expanded — `~` → home), `bool`, `int`, `choice`.

## Prerequisites

```yaml
prerequisites:
  - name: git
    detect: "command -v git"
    version_min: "2.30"
    install_hint: "Install git: https://git-scm.com"
```

| Field          | Type                 | Description                                                    |
| -------------- | -------------------- | -------------------------------------------------------------- |
| `name`         | string               | Required.                                                      |
| `detect`       | string               | Shell command. Exit 0 = present, non-zero = missing. Required. |
| `version_min`  | string               | Minimum version parsed from `detect` stdout.                   |
| `required`     | bool, default `true` | Required prerequisites abort install if missing.               |
| `install_hint` | string               | Shown when missing.                                            |

## OS Config Entries (Developer Manifests Only)

`os_config` declares OS mutations (kernel params, group membership, file permissions,
shell profile changes) as check/apply pairs. Reachable only via `type: os-config`
steps that reference an entry by `config_id`.

| Field              | Type                  | Description                                                                                        |
| ------------------ | --------------------- | -------------------------------------------------------------------------------------------------- |
| `id`               | string                | Unique identifier referenced by `config_id`. Required.                                             |
| `description`      | string                | What this entry does. Required.                                                                    |
| `check`            | string                | Shell command. Exit 0 = already configured (skip apply), non-zero = needs configuration. Required. |
| `apply`            | string                | Shell command or multi-line script to apply the configuration. Required.                           |
| `requires_relogin` | bool, default `false` | Installer warns the user that logout/login or new shell is required.                               |
| `interactive`      | bool, default `false` | Apply triggers a GUI dialog or interactive prompt; installer must pause and inform the user.       |
| `platforms`        | string[]              | Optional platform filter. Values: `linux`, `macos`, `windows`.                                     |

## Steps

Ordered installation steps. Each step has a `type` that selects one of seven execution
modes.

### Step types

| Type             | When to use                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `script`         | Known operation — use this first. Run a script file with declared params. |
| `detect`         | Check environment state.                                                  |
| `ask`            | Collect user input mid-install.                                           |
| `verify`         | Post-operation validation (run `commands`).                               |
| `agentic`        | Exception handling only — adaptive recovery via free-form `instruction`.  |
| `platform-route` | Branch by OS/distro using `routes`.                                       |
| `chain`          | Invoke a sub-project SetupManifest.                                       |
| `os-config`      | Apply a single `os_config` entry by ID (developer manifests only).        |

### Common step fields

| Field        | Type               | Description                                                                            |
| ------------ | ------------------ | -------------------------------------------------------------------------------------- |
| `id`          | string             | Unique step identifier. Referenced by `depends_on` and `on_fail`. Required.            |
| `type`        | enum (above)       | Execution mode. Required.                                                              |
| `platform`    | string or string[] | Platform filter. Omit to run on all declared platforms.                                |
| `depends_on`  | string[]           | Step IDs that must complete successfully before this step runs.                        |
| `when`        | string             | Condition expression; step skipped if false. References params by name.                |
| `on_fail`     | string             | Recovery procedure ID to invoke on failure. The literal `recover` invokes the default. |
| `interactive` | bool, default `false` | This step itself prompts directly. With every name in this step's own `params` resolved, it runs headless instead (no terminal needed); otherwise it requires a terminal, and `aiwg setup-run` refuses a marked step up front (naming it) instead of running it when none is attached (#3062; second review finding 5b). |

### Running headless (#3062)

Without an interactive terminal attached, `script`/`verify`/`detect`/`os-config` steps
run bounded (10 minutes by default, `AIWG_SYNC_LONG_TIMEOUT_MS` to override) with stdin
ignored: a step whose command tries to prompt fails fast instead of hanging `aiwg
setup-run` forever. With a terminal attached, behavior is unchanged — a step's
command/script gets inherited stdio so a person can actually answer a prompt it issues.

Mark a step `interactive: true` when it is known to prompt directly. It can
*optionally* declare which inputs would let it skip that prompt via the same
`params` field a `script` step uses to pass param names as env vars (#3062 second
review, finding 5b): with every declared param already resolved
(`--param`/`--params-file`/env/`default`), the step is trusted not to need to prompt
and runs headless (bounded) exactly like any other step in that same environment —
no terminal required. With no `params` declared at all ("undeclared interaction" —
its questions cannot be enumerated or supplied via `--param`, since it runs an
arbitrary script), or with a declared param still missing, a terminal is required;
`aiwg setup-run` refuses up front, before running anything, instead of waiting out
the bounded timeout. With a terminal attached and nothing resolved, behavior is
unchanged from before `params` existed on this field: the step's underlying
command/script runs with inherited stdio and may prompt on its own.

`type: ask` steps declare which inputs they need via `params` the same way. An `ask`
step with every declared param already resolved runs headless, logging which params
answered it. One with a declared param still unresolved is refused *only* when no
terminal is attached, naming the missing name(s) so `--param`/`--params-file` can
supply them instead; **with a terminal attached, it is prompted for the missing
ones** (#3062 second review, finding 5b — this is the one behavioral difference from
`interactive: true`: this CLI itself owns the prompting for `ask` steps, since there
is no separate script to hand a terminal to, so it can actually ask instead of just
letting a script do its own thing). A declared answer threads into every later step's
env exactly like a `--param`-supplied one. An `ask` step with **no** `params`
declared at all is always refused, with or without a terminal — this is one of only
two permanent exceptions to "an input with a terminal gets prompted for" (the other
is `tools/contrib/sync-upstream.mjs`'s contributor sync-strategy choice): with
nothing declared, there is no destination to store an answer in at all.

`type: agentic` and `type: chain` steps are always refused — deterministic CLI
execution does not support either, regardless of terminal or supplied params.

Every selected step (including nested `platform-route` steps, and the entire
recovery sequence any selected step's `on_fail` names) is checked for all of the
above conditions **before any step runs** — not inside the per-step loop, and not
only for the step about to execute — so an earlier step can never run ahead of a
*later* step's refusal, nor can a normal step run ahead of a refusal inside the
recovery sequence it would trigger on failure (#3062 second review, finding 7). A
step only reachable through `on_fail` recovery and not already covered that way
(i.e. a manifest with no selected step actually naming it) is checked individually,
right before it would run.

### Type-specific fields

| Type             | Required fields                              | Optional fields                          |
| ---------------- | -------------------------------------------- | ---------------------------------------- |
| `script`         | `script` (path relative to manifest)         | `params`, `verify`                       |
| `verify`         | `commands` (string[])                        | —                                        |
| `ask`            | `message`                                    | `params` (required to run headless; see "Running headless" above), `on_deny` (`abort` or `skip`) |
| `agentic`        | `instruction`                                | —                                        |
| `os-config`      | `config_id`                                  | —                                        |
| `platform-route` | `routes[]` (each `{platform, steps[]}`)      | —                                        |
| `chain`          | `manifest` (path or URL to chained manifest) | —                                        |
| `detect`         | —                                            | typically uses `verify`/`commands` shape |

For `script` steps: `params` lists param names passed to the script as env vars;
`verify` is one or more post-step commands (exit 0 = success).

## Recovery Procedures

Named groups of steps invoked when a step's `on_fail` matches.

```yaml
recovery:
  - id: full-reset
    steps:
      - id: reset
        type: script
        script: scripts/reset.sh
```

| Field   | Type     | Description                                            |
| ------- | -------- | ------------------------------------------------------ |
| `id`    | string   | Required. Procedure ID referenced by `step.on_fail`.   |
| `steps` | `Step[]` | Required. Recovery steps (same shape as `spec.steps`). |

## Briefing

```yaml
briefing:
  success: "Install complete. Run aiwg help to get started."
  next_steps:
    - "Run aiwg use sdlc to deploy the SDLC framework"
    - "Open ./README.md for project orientation"
```

## Worked Example

```yaml
apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata:
  name: myapp
  version: 1.0.0
  install_type: user
spec:
  platforms:
    - os: linux
      distros: [ubuntu, debian, fedora]
      arch: [x86_64, arm64]
      shell: bash
    - os: macos
      arch: [arm64]
      shell: zsh
  params:
    - name: INSTALL_DIR
      type: path
      required: true
      description: "Where to clone the project"
  prerequisites:
    - name: git
      detect: "command -v git"
      version_min: "2.30"
      install_hint: "Install git: https://git-scm.com"
  steps:
    - id: clone
      type: script
      script: scripts/clone.sh
      params: [INSTALL_DIR]
      verify: "test -d ${INSTALL_DIR}/.git"
      on_fail: full-reset
    - id: configure
      type: script
      script: scripts/configure.sh
      depends_on: [clone]
  recovery:
    - id: full-reset
      steps:
        - id: reset
          type: script
          script: scripts/reset.sh
  briefing:
    success: "Install complete."
    next_steps:
      - "cd ${INSTALL_DIR} && ./bin/myapp --help"
```

## Tooling

The agentic-installer addon ships three agent-facing CLI entrypoints, three
backing skills, one agent, two rules, and the canonical schema. These are
agentic runtime assets: discovery and index automation should locate them by
type (`skill`, `agent`, `rule`, `schema`) and by command name where applicable.

- **`setup-generate`** — generate starter manifest and script assets.
- **`setup-validate`** — schema + reference checks + agentic-step audit.
  `--fix` is reserved for future safe autofixes and currently validates only.
- **`setup-run`** — six-phase execution with platform detection, dry-run, and recovery
  confirmation gate.
- **`installer-agent`** — specialized persona for manifest generation, validation, and
  execution.

```bash
# Generate starter runtime assets
aiwg setup-generate --output setup.manifest.yaml

# Validate
aiwg setup-validate setup.manifest.yaml

# Dry run
aiwg setup-run --manifest setup.manifest.yaml --dry-run

# Execute after reviewing the dry-run plan and obtaining authorization
aiwg setup-run --manifest setup.manifest.yaml --confirm
```

Two HIGH-severity rules govern manifest authoring and execution:

- **`installer-safety`** — show before run, confirm destructive ops, validate before
  execute, agentic-steps-as-exceptions, params-before-steps, no inline secrets,
  platform mismatch = skip.
- **`installer-authoring`** — script-first, always source libs, manifests describe
  while scripts act, one manifest per unit, every manifest needs recovery.

## Cross-References

- **Schema (authoritative)**:
  `agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`
- **Addon source**: `agentic/code/addons/agentic-installer/`
- **Script templates**: `agentic/code/addons/agentic-installer/scripts/templates/`
  (clone, install-deps for ubuntu/fedora/macos/windows, configure, verify, reset,
  hub-chain)
- **Library helpers** (sourced by templates):
  `agentic/code/addons/agentic-installer/scripts/lib/{detect,params,verify}.sh`,
  `detect.ps1`
- **Authoring rules**:
  `agentic/code/addons/agentic-installer/rules/installer-authoring.md`,
  `installer-safety.md`
- **Release announcement** (introduces the language):
  `docs/releases/v2026.4.0-announcement.md` (#663–#667)
- **Project-level config** (separate concern): see [`aiwg-config.md`](./aiwg-config.md)
