agent-os/bootstrap/README.md

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:

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:

python3 bootstrap/cli.py export

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

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:

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

Init / Apply

Initialize or update a project root from the bootstrap bundle:

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:

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:

python3 bootstrap/cli.py smoke-test

To keep the generated temp folder for inspection:

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