diff --git a/README.md b/README.md
index 8c852f7..dbaf03a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,19 @@
-# Devloop
-
-Spec in. Reviewed code out.
+
+
+░█▀▄░█▀▀░█░█░█░░░█▀█░█▀█░█▀█
+░█░█░█▀▀░▀▄▀░█░░░█░█░█░█░█▀▀
+░▀▀░░▀▀▀░░▀░░▀▀▀░▀▀▀░▀▀▀░▀░░
+
+ Spec in. Reviewed code out.
+
+ 
+ 
+
+
+
+
+ 
+
`devloop` runs a local agent loop: Codex implements, Claude Code reviews, and Codex retries until the work is accepted, stalled, unclear, or out of passes.
@@ -10,84 +23,58 @@ Spec in. Reviewed code out.
curl -fsSL https://devloop.sh/install | bash
```
-Installs to `~/.local/share/devloop`, links `~/.local/bin/devloop`, and installs the bundled Codex and Claude Code skills.
-
-Required: Bash, git, Homebrew, `codex`, `claude`, `gum`, and `fzf`. The installer can install missing `gum` and `fzf`; install the agent CLIs yourself. PR-backed loops (`--create-pr`) additionally require an authenticated `gh`.
-
-From source:
+Or from source:
```sh
git clone https://github.com/satyaborg/devloop.git
cd devloop
./scripts/install.sh
-devloop doctor
-```
-
-## Uninstall
-
-```sh
-./scripts/uninstall.sh
```
-Removes the `~/.local/bin/devloop` symlink, the `~/.local/share/devloop` runtime, and the devloop-managed skills. Pass `--dry-run` to preview, or set `DEVLOOP_FORCE=1` to also remove hand-modified skills. Leaves the source checkout, `gum`, `fzf`, and `gh` untouched.
+> Requires Bash, git, `codex`, `claude`, `gum`, and `fzf`. Run `devloop doctor` to check.
-## Use
+Uninstall with `./scripts/uninstall.sh` (`--dry-run` to preview).
-```sh
-devloop
-devloop spec "add retry behavior to the chat sender"
-devloop .devloop/specs/change.md
-devloop --create-pr .devloop/specs/change.md
-devloop continue
-devloop status
-devloop clean
-```
+## Usage
-Start with a spec you already have, or from scratch. Pass a path to run an existing spec; run `devloop spec` with no context to let the agent interview you and write one. `devloop continue` resumes a tracked run where it left off.
+| Command | Description |
+|---|---|
+| `devloop` | Interactive menu: create, run, or continue a spec |
+| `devloop spec "..."` | Have an agent interview you and write a spec |
+| `devloop ` | Run a spec |
+| `devloop --create-pr ` | Run a spec and maintain a draft PR (requires `gh`) |
+| `devloop continue` | Resume a tracked run |
+| `devloop status` | Show run status |
+| `devloop clean` | Remove run artifacts |
-Each run writes an HTML report and the markdown spec and reviews under `.devloop/`, so the work is easy to read and review at a glance. HTML is the default; pass `--report-format markdown` for plain text.
+Each run writes an HTML report, spec, and reviews under `.devloop/`.
## Specs
-A good spec is short, concrete, and verifiable. Start from [`skills/devloop-spec/references/spec-template.md`](skills/devloop-spec/references/spec-template.md), or launch a spec agent:
-
-```sh
-devloop spec
-devloop spec --agent claude notes.md
-```
-
-Strict mode is on by default. Specs need `## Acceptance criteria`, and reviews must pass both the spec gate and engineering quality gate.
-
-Devloop stores shared settings in `~/.devloop/config`. The default spec directory is the current repo's `.devloop/specs/`. Set a custom `spec_dir` (global or per-repo) to point elsewhere, for example `~/Projects/specs`; the picker searches both the custom directory and the repo's `.devloop/specs/`.
-
-## PR mode
+A good spec is short, concrete, and verifiable. Start from [`skills/devloop-spec/references/spec-template.md`](skills/devloop-spec/references/spec-template.md).
-A plain non-interactive `devloop ` remains local-only.
-
-With `--create-pr`, `devloop` opens and maintains a draft PR during the loop. The PR is canonical for review history; local `.devloop/reviews/*.md` files are execution cache.
-
-Install `gh` and run `gh auth login` before using PR-backed loops.
+Strict mode is on by default: specs need `## Acceptance criteria`, and reviews must pass both the spec gate and engineering quality gate.
## Runtime
- Uses an isolated sibling git worktree by default; pass `--in-place` to stay in the current worktree.
-- Runs up to 5 passes, commits eligible coder changes, and executes `.devloop/verify` after each coder pass when present.
+- Runs up to 5 passes, commits eligible coder changes, and executes `.devloop/verify` after each coder pass when present. Keep `.devloop/verify` local and auditable.
- Writes tracks, reviews, reports, logs, session ids, and spec snapshots under `.devloop/`; generated worktrees and branches remain for inspection.
-## Security
-
-`devloop` runs local agent CLIs against your checkout, so those agents inherit your local credentials, PATH, and machine access. `devloop` adds no telemetry; network behavior depends on the agents and commands you configure.
-
-Keep `.devloop/verify` local and auditable. It runs from the run worktree with the pass number and slug as arguments.
-
-## Development
+## Contributing
```sh
+git clone https://github.com/satyaborg/devloop.git
+cd devloop
bash scripts/devloop_test.sh
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, full gates, and release notes.
+## Privacy
+
+`devloop` adds no telemetry. It runs local agent CLIs against your checkout, so network behavior depends on the agents and commands you configure.
+
## License
-MIT
+[MIT](LICENSE)
diff --git a/demo.gif b/demo.gif
new file mode 100644
index 0000000..6180be3
Binary files /dev/null and b/demo.gif differ
diff --git a/scripts/devloop_test.sh b/scripts/devloop_test.sh
index def3df5..d7fe9c9 100755
--- a/scripts/devloop_test.sh
+++ b/scripts/devloop_test.sh
@@ -86,13 +86,8 @@ skill_path="$("$REPO_ROOT/devloop" spec --skill-path)"
contains "$("$REPO_ROOT/devloop" spec --print-skill)" "name: devloop-spec" "spec skill"
ok "spec skill path"
-contains "$(cat "$REPO_ROOT/README.md")" "opens and maintains a draft PR during the loop" "README PR mode"
-contains "$(cat "$REPO_ROOT/README.md")" "plain non-interactive" "README local-only"
-contains "$(cat "$REPO_ROOT/README.md")" "remains local-only" "README local-only"
-contains "$(cat "$REPO_ROOT/README.md")" "With \`--create-pr\`, \`devloop\` opens and maintains a draft PR during the loop" "README PR mode"
-not_contains "$(tr '\n' ' ' < "$REPO_ROOT/README.md")" "A plain non-interactive \`devloop \` remains local-only. This mode opens and maintains a draft PR during the loop." "README local-only coherence"
-contains "$(cat "$REPO_ROOT/README.md")" "PR is canonical" "README PR canonical"
-contains "$(cat "$REPO_ROOT/README.md")" "gh auth login" "README optional gh auth"
+contains "$(cat "$REPO_ROOT/README.md")" "\`devloop --create-pr \`" "README PR mode"
+contains "$(cat "$REPO_ROOT/README.md")" "maintain a draft PR (requires \`gh\`)" "README PR mode"
ok "README PR guidance"
for skill in "$REPO_ROOT"/skills/*/SKILL.md; do
diff --git a/site/public/demo.mp4 b/site/public/demo.mp4
new file mode 100644
index 0000000..8337578
Binary files /dev/null and b/site/public/demo.mp4 differ