# Agent OS Bootstrap

This directory owns the source for the generic Agent OS bootstrap bundle.

The Linux Server design docs are the source specification:

- `/home/nxm/Documents/NxM Linux Server/Services/Agents.md` defines the Agent OS foundation, the `/opt/agent-os` runtime root, and the agent output contract.
- `/home/nxm/Documents/NxM Linux Server/Operations/Git Workflow.md` defines the Gitea source-of-truth flow and says generated runtime state must stay out of commits.
- `/home/nxm/Documents/NxM Linux Server/Current Work.md` records the clone synchronization baseline for Agent OS.

## Files

- `bundle-manifest.json` lists the canonical files and directories in the generic bundle.
- `export-rules.json` defines which metadata is exported and which paths must verify.
- `templates/generic/` holds the canonical bootstrap templates.
- `cli.py` is the unified bootstrap CLI.
- `generate-export.py`, `init-project.py`, and `smoke-test.py` are compatibility wrappers.

## CLI

The long-term interface is the unified bootstrap CLI:

```bash
python3 bootstrap/cli.py export
python3 bootstrap/cli.py verify
python3 bootstrap/cli.py apply /path/to/project
python3 bootstrap/cli.py smoke-test
```

## Generate

From a checked-out Agent OS clone:

```bash
python3 bootstrap/cli.py export
```

To generate the live runtime export requested by the server workflow:

```bash
sudo -n python3 bootstrap/cli.py export --output /opt/agent-os/bootstrap/exports/generic
```

Generated exports are intentionally ignored by Git.

To verify an existing bundle:

```bash
python3 bootstrap/cli.py verify --output /path/to/bootstrap/exports/generic
```

## Init / Apply

Initialize or update a project root from the bootstrap bundle:

```bash
python3 bootstrap/cli.py apply /path/to/project
```

The default behavior is:

- non-destructive
- merge-aware
- prompt-driven on conflicts

Apply shows a summary first, then handles conflicts one file at a time.

If a target file already exists and differs from the bootstrap content, the CLI offers:

- `keep`
- `replace`
- `write-new`

It also supports:

- optional `diff` when the file is cheap to diff
- `apply to all remaining conflicts` after choosing an action

Bootstrap-managed files are tracked in `.agent-os-bootstrap-state.json` in the
target project root.

For unattended runs, you must choose an explicit policy:

```bash
python3 bootstrap/cli.py apply /path/to/project --on-conflict keep
python3 bootstrap/cli.py apply /path/to/project --on-conflict replace
python3 bootstrap/cli.py apply /path/to/project --on-conflict write-new
```

## Smoke Test

Run the bootstrap against a brand new temp directory:

```bash
python3 bootstrap/cli.py smoke-test
```

To keep the generated temp folder for inspection:

```bash
python3 bootstrap/cli.py smoke-test --keep
```