docs: architecture section, FAQ, cross-references, vault-memory update

README.md:
  - Added §1.5 'Architecture: Framework vs Project' with directory tree
    and lifecycle flow diagram
  - Added §2.5 FAQ covering coexistence, hooks, loops, multi-project
  - Updated install section already done in prior commit

AGENTS.md:
  - Added 'Script Cross-References' table mapping install.sh →
    onboard-project.sh → status.py --create-task

scripts/install-hooks.sh:
  - Updated header to reference onboard-project.sh as caller
  - Added 'Next step' line pointing to --create-task

vault-memory CONTEXT.md:
  - Updated test count (518→611)
  - Added new scripts (detect_models.py, onboard-project.sh)
  - Documented install/onboard flow and split architecture

AGENTS.md

@@ -136,6 +136,21 @@ Modes:
 2. Run `python3 -m pytest tests/test_prompt_paths.py` to ensure task paths are canonical.
 3. Update `CHANGELOG.md` under `[unreleased]`.
 
+## Script Cross-References
+
+The framework provides three lifecycle scripts that should be referenced from each other:
+
+| Script | Purpose | Called when | Next step |
+|---|---|---|---|
+| `scripts/install.sh` | Install framework on a fresh machine | `curl \| bash` or `git clone + bash` | → `scripts/onboard-project.sh` |
+| `scripts/onboard-project.sh` | Bootstrap automaton in a project | After framework install, per project | → `status.py --create-task` |
+| `scripts/install-hooks.sh` | Install git hooks per project | After onboarding, or manually | see `onboard-project.sh` |
+
+- `install.sh` outputs "Next: onboard-project.sh" at the end.
+- `onboard-project.sh` outputs "Next: status.py --create-task" at the end.
+- `install-hooks.sh` is called by `onboard-project.sh` automatically.
+- `update.sh` does NOT call `onboard-project.sh` — it only updates the framework.
+
 ## Adding a New Script
 
 1. Place the script in `scripts/`.

README.md

@@ -51,6 +51,73 @@ If a project was set up under the old model (with copies of framework files), it
 
 ---
 
+## 1.5 Architecture: Framework vs Project
+
+Automaton uses a **split architecture** — one shared framework, many project `./.automaton/` directories:
+
+```
+~/.automaton/                          ← Framework (installed once per machine)
+  ├── scripts/                         ← shared tooling: status.py, loop-runner.py
+  ├── prompts/                         ← shared LLM prompts
+  ├── plugins/                         ← shared harness plugins
+  ├── templates/                       ← shared task & loop templates
+  ├── .automaton/tasks/                ← framework housekeeping tasks (self-improvement)
+  └── .automaton/loops/                ← framework loops (self-improvement loop)
+
+~/projects/my-app/
+  └── .automaton/                      ← Project (onboarded once per project)
+       ├── tasks/                      ← YOUR project's tasks
+       ├── models.json                 ← YOUR project's model config
+       ├── config.md                   ← YOUR project's VRAM config
+       ├── project-name.md             ← YOUR project's display name
+       └── loops/                      ← YOUR project's loops
+```
+
+**Key rules:**
+
+- The agent is **scope-aware**: if you're inside `~/.automaton/`, it operates in **framework mode** (reads framework tasks). If you're inside a project dir, it operates in **project mode** (reads project tasks). They never interfere.
+- All framework scripts (`status.py`, etc.) live in `~/.automaton/scripts/` and are shared — never copied into projects.
+- Framework prompts live in `~/.automaton/prompts/` — projects reference them by path at runtime.
+- Git hooks are **per-project**. Each project installs its own via `bash ~/.automaton/scripts/install-hooks.sh <project-path>`.
+- The self-improvement loop targets **only** the framework itself. Your project won't get framework-level tasks in its board.
+- You can work on both at the same time in different terminals — independent `.automaton/` directories, shared tooling.
+
+### Lifecycle overview
+
+```
+   ┌─────────────────────────────────────────────────────┐
+   │          1. Install Framework (once per machine)     │
+   │  curl .../install.sh | bash -s -- <git-url>          │
+   │  → clones to ~/.automaton/                          │
+   │  → VRAM detection, guards, venv, self-improvement   │
+   └────────────────────────┬────────────────────────────┘
+                            │
+   ┌────────────────────────▼────────────────────────────┐
+   │          2. Onboard Project (once per project)       │
+   │  bash ~/.automaton/scripts/onboard-project.sh <dir>  │
+   │  → creates .automaton/ skeleton                     │
+   │  → probes models, writes config.md                  │
+   │  → git init + hooks                                 │
+   └────────────────────────┬────────────────────────────┘
+                            │
+   ┌────────────────────────▼────────────────────────────┐
+   │          3. Create Task (per feature)                │
+   │  python3 ~/.automaton/scripts/status.py              │
+   │    --create-task my-feature --project .              │
+   └────────────────────────┬────────────────────────────┘
+                            │
+   ┌────────────────────────▼────────────────────────────┐
+   │          4. Work Through Phases (per task)            │
+   │  status.py --transition research --task my-feature   │
+   │  → agent writes SPEC.md                              │
+   │  status.py --transition implement --task my-feature  │
+   │  → agent writes code + IMPLEMENTATION.md             │
+   │  ... → complete                                      │
+   └─────────────────────────────────────────────────────┘
+```
+
+---
+
 ## 2. Project Setup (Per project)
 
 Once the framework is installed globally, you must "onboard" every individual project you work on.
@@ -113,6 +180,43 @@ The self-improvement loop installed by default targets the **framework itself**
 
 ---
 
+## 2.5 FAQ
+
+### Can I work on the framework and a project at the same time?
+Yes. They have separate `.automaton/` directories. Open two terminals:
+```
+Terminal 1: cd ~/.automaton                    → framework mode
+Terminal 2: cd ~/projects/my-app               → project mode
+```
+The agent detects scope from your current directory. Each can have its own tasks, loops, and config. They share the same `~/.automaton/scripts/` binaries.
+
+### Why doesn't `install.sh` need a Git URL when run from the repo?
+Because the framework is already cloned. `install.sh` skips cloning when `~/.automaton/` exists and runs all the setup steps (VRAM detection, pip deps, self-improvement loop, guards). The Git URL is only required for a fresh install via `curl | bash`.
+
+### Do I need to run `install.sh` again after pulling updates?
+No. `git pull` inside `~/.automaton/` updates the code. The self-improvement loop and guards persist across updates. If you want to re-register guards (e.g. after switching harnesses), run `bash ~/.automaton/scripts/register-guards.sh`.
+
+### How do git hooks work per project?
+Each project installs its own hooks via:
+```bash
+bash ~/.automaton/scripts/install-hooks.sh /path/to/project
+```
+The pre-commit hook blocks commits when no task is in `implement` or `doc_review` phase. The pre-push hook catches `--no-verify` bypasses. They're independent per repo.
+
+### Can I have multiple projects onboarded at once?
+Yes. Each project gets its own `.automaton/` directory. Run `onboard-project.sh` once per project. The shared scripts in `~/.automaton/scripts/` enforce the state machine on whichever project you point `--project` at.
+
+### What about loops on my project?
+The self-improvement loop runs only on the framework. To add a loop to your project:
+```bash
+python3 ~/.automaton/scripts/status.py --create-loop my-loop \
+  --from-template self-improvement --project /path/to/project
+python3 ~/.automaton/scripts/status.py --install-schedule my-loop \
+  --interval 3600 --project /path/to/project
+```
+
+---
+
 ## The Autopilot Workflow
 The framework features an **Autopilot** mode that allows the agent to drive a project to completion with minimal intervention.
 

scripts/automaton-cleanup.sh

@@ -1,2 +1,2 @@
 #!/usr/bin/env bash
-python3 "/Users/laptran/.automaton/scripts/status.py" --cleanup-done --days 7 --project "/private/var/folders/f5/yv0dzbnx47x3yp8sc_2519gh0000gn/T/pytest-of-laptran/pytest-128/test_uninstall_via_disabled_re0"
+python3 "/Users/laptran/.automaton/scripts/status.py" --cleanup-done --days 7 --project "/private/var/folders/f5/yv0dzbnx47x3yp8sc_2519gh0000gn/T/pytest-of-laptran/pytest-129/test_uninstall_via_disabled_re0"

scripts/install-hooks.sh

@@ -3,9 +3,14 @@
 #
 # Usage: bash ~/.automaton/scripts/install-hooks.sh [project-path]
 #
+# Called automatically by onboard-project.sh. Can also be run manually
+# after framework updates to refresh hooks.
+#
 # Installs pre-commit and pre-push hooks. The pre-commit hook blocks
 # commits when no task is in implement/doc_review. The pre-push hook
 # blocks pushes in the same condition, catching --no-verify bypasses.
+#
+# Next step: python3 ~/.automaton/scripts/status.py --create-task --project .
 
 set -euo pipefail