git:20260404.825e38f to git:20260404.df58347

# setup-generate

Generate a `setup.manifest.yaml` file for a project using the `setup.aiwg.io/v1` SetupManifest language.

## Trigger Phrases

- "generate a setup manifest for [project]"

- "create installer for [project]"

- "scaffold setup manifest"

- "write a setup.manifest.yaml for [directory]"

- "generate install workflow for [project]"

## Parameters

### project-dir (positional, optional)

Path to the project root. Defaults to `.`.

### --from-readme (optional)

Extract requirements from `README.md` or `INSTALL.md` in the project dir.

### --from-existing (optional)

Update an existing `setup.manifest.yaml` rather than creating from scratch.

### --platforms (optional)

Comma-separated list of target platforms: `linux,macos,windows,wsl2`.

Default: `linux,macos`.

### --interactive (optional)

Ask clarifying questions before generating.

## Execution Flow

### Phase 1: Discovery

1. Read the project root to understand structure:

- Check for `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Makefile`, etc.

- Check for `README.md`, `INSTALL.md`, `docs/install.md`

- Check for existing `setup.manifest.yaml`

2. If `--from-readme`, parse installation instructions from readme

3. If `--interactive`, ask:

- What OSes must be supported?

- What are the hard prerequisites (git, node, python version)?

- Is there a config directory that needs to be created?

- Does the project chain sub-projects?

### Phase 2: Assemble Manifest

Build the manifest YAML following this priority order:

- Always start with a `clone` or `verify-existing` detect step

- Add `install-deps-*` steps for each target platform

- Add `configure` step if config files are needed

- End with a `verify` step

### Docker-based Project Detection

When `docker-compose.yml` or `compose.yaml` is found during Phase 1 discovery, apply these additional behaviors:

**Platform** (#676):

- Include `macos` in the platform block alongside `linux` — Docker Desktop covers both.

- Any GPU or nvidia steps must add `when: "$(uname -s) = Linux"` so they are skipped on macOS.

- Update `install_hint` for docker prereqs to include macOS install links.

**Prerequisites** (#672, #674):

- Replace `command -v docker` with `docker version --format '{{.Server.Version}}' 2>/dev/null` to catch both "not installed" and "installed but no permission" cases.

- Expand the docker `install_hint` to mention `sudo usermod -aG docker $USER`.

- When Docker images or ML models are present, add disk space prereq (≥20GB free):

```yaml

- name: disk-space

detect: "df --output=avail -BG / | tail -1 | tr -d ' G'"

version_min: "20"

install_hint: "At least 20GB free disk space required for Docker images."

```

- When ML models are detected (Ollama, HuggingFace, etc.), add RAM prereq (≥8GB):

```yaml

- name: ram

detect: "awk '/MemTotal/ {printf \"%.0f\", $2/1024/1024}' /proc/meminfo"

version_min: "8"

install_hint: "At least 8GB RAM recommended. 16GB+ for GPU profiles."

```

**Params** (#671, #675):

- When a `DOMAIN` or `ISSUER_URL` param is emitted, also emit a `PROTOCOL` param with a smart default:

```yaml

- name: PROTOCOL

type: choice

choices: [http, https]

default: "$(echo ${DOMAIN} | grep -qE '^(localhost|127\\.0\\.0\\.1)' && echo http || echo https)"

description: "Protocol for OAuth/API URLs. Defaults to http for localhost."

```

Then reference `${PROTOCOL}://${DOMAIN}` in configure.sh instead of hardcoding `https://`.

- Default `DATA_DIR` to `${INSTALL_DIR}/data` (project-local, user-writable) rather than any system path like `/var/lib/<project>`. If the project explicitly requires a system path, emit a `check-data-dir` step (see steps below).

**Steps** (#673, #675, #677):

- Emit a `check-ports` step before `deploy` that validates all ports declared in the compose file are free:

```yaml

- id: check-ports

type: script

script: installer/scripts/check-ports.sh

depends_on: [configure]

```

- When the default `DATA_DIR` is a system path, emit a `check-data-dir` step before `configure`:

```yaml

- id: check-data-dir

type: script

script: installer/scripts/check-data-dir.sh

depends_on: [clone]

```

- When Ollama is detected in the compose file or `.env` template, emit a `pull-models` step after `deploy`:

```yaml

- id: pull-models

type: script

description: Pull Ollama models (may take several minutes)

script: installer/scripts/pull-models.sh

depends_on: [deploy]

verify: "docker exec $(docker compose ps -q ollama) ollama list | grep -q ${OLLAMA_GEN_MODEL%%:*}"

```

**Script templates used for Docker projects**:

- `installer/scripts/check-ports.sh` — port availability check before deploy

- `installer/scripts/pull-models.sh` — Ollama model pull after deploy (when applicable)

### Phase 3: Script Assembly

For each script step:

1. Copy the relevant template from `agentic/code/addons/agentic-installer/scripts/templates/`

### Phase 4: Output

Report:

```

Platform: linux, macos

Recovery: full-reset

```

## Script-First Rule

Every step that can be scripted MUST be a `script` step. Only use `type: agentic` for:

- Steps that require real-time environment inspection that cannot be expressed in bash

- Recovery from unexpected failures where the script approach has been exhausted

```yaml

apiVersion: setup.aiwg.io/v1

kind: SetupManifest

metadata:

version: 1.0.0

```

## References

- Schema: `agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`

- Run skill: `agentic/code/addons/agentic-installer/skills/setup-run/SKILL.md`

- Validate skill: `agentic/code/addons/agentic-installer/skills/setup-validate/SKILL.md`