# Quick start

This quick start installs a runnable Portable Agent OS from a verified source checkout. It uses no
runtime dependencies and never downloads or executes a remote script.

## 1. Verify the source

Use Python 3.11 or newer and inspect the checkout before granting it access to your home:

```powershell
python --version
git status --short
git log -1 --oneline
```

Prefer a published tag and verify release checksums when they are available. The project is not a
PyPI package in this pre-release phase.

## 2. Preview the installation

From the repository root:

```powershell
python install.py --dry-run
```

Preview is mutation-free. It selects the current home, the platform default install root, the
private `.agent-os` overlay, and the Codex plus generic adapters. The JSON result contains logical
locators and hashes, not absolute home paths or existing instruction content.

## 3. Install with one command

```powershell
python install.py --yes
```

`--yes` is explicit authority to modify the selected real home. The bootstrap:

1. Chooses `AGENTS.override.md` when it is the active non-empty Codex global file; otherwise it uses
   `AGENTS.md`.
2. Preserves any existing file in local managed state and appends a delimited Agent OS block.
3. Installs the runnable Python core and `bin/agent-os.py` under the managed install root.
4. Creates the private overlay outside the source repository.
5. Runs `status` and `doctor` and returns one JSON receipt.

If a target changes between preview and apply, contains conflicting managed markers, traverses a
link/reparse point, or cannot be safely preserved, installation stops with exit code 2.

## 4. Verify and update

On Windows with default paths:

```powershell
python "$HOME\AppData\Local\AgentOS\bin\agent-os.py" status --home $HOME
python "$HOME\AppData\Local\AgentOS\bin\agent-os.py" doctor --home $HOME
python install.py --yes
```

The last command automatically selects update. An unchanged installation returns a no-op. Update
is backup-first and refuses drifted managed files.

## 5. Uninstall safely

Preview and then apply uninstall:

```powershell
python "$HOME\AppData\Local\AgentOS\bin\agent-os.py" uninstall --home $HOME --dry-run
python "$HOME\AppData\Local\AgentOS\bin\agent-os.py" uninstall --home $HOME
```

Uninstall backs up managed state, restores pre-existing Codex global guidance byte-for-byte,
removes only verified managed files, and preserves the private overlay.

## Disposable demo and tests

The synthetic demo still proves the complete lifecycle without touching a real profile:

```powershell
$env:PYTHONPATH = (Resolve-Path src)
python examples/synthetic/demo/run_demo.py
python -m unittest discover -s tests -p "test_*.py"
```

Read [Configuration](CONFIGURATION.md), [Lifecycle](LIFECYCLE.md), and the
[Security model](SECURITY_MODEL.md) before customizing paths or importing packages.