docs(backup): correct backup/.backup/.backupignore docs across the system

Streamlined prompts had drifted from reality. Full-context investigation
(3 agents + @memory storyline) corrected:

- .backup/ documented as a SHARED runtime namespace (3 writers: @backup
  snapshot stores, @memory rollover safety copies, @flow processed_plans),
  not @backup-exclusive.
- @backup README: full 11-command coverage, .backup/ store layout, and a
  .backupignore (gitignore-for-backups: pathspec/gitwildmatch, BUILTIN_IGNORES,
  self-exclusion, ships as config) section.
- @backup branch prompt: stale .backup_system/ -> .backup/ (3x), drive_test.py
  -> drive_check.py (was misleading the agent every turn).
- Root README: @backup added to roster + uninstall covers .backup/.backupignore.
  navmap @backup line corrected (Drive planned + shared namespace).
- Shipped root /.backupignore realigned to BUILTIN_IGNORES (dropped stale
  .backup_system/, removed over-broad *logs).
- Removed dead backup/run/ test dir.

@backup verified: 220 tests green, seedgo 100%. Closes td-218.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QEQZXCtgnF3NQtcttTErpq

.aipass/tier1_navmap.md

@@ -55,7 +55,7 @@ src/aipass/<name>/
  - @skills — capability framework. Discoverable, self-contained skill units any agent can run; consume AIPass services as opt-in imports (e.g. the Telegram skill).
  - @daemon — task scheduler. Cron-triggered firing; each branch owns its `.daemon/schedule.json`, the daemon discovers and fires.
  - @commons — the social space. Where branches post, comment, vote, and gather as a community.
- - @backup — local-first backups. Project-owned snapshots and restore for any directory; no external service.
+ - @backup — local-first backups. Snapshots + versioning + restore for any directory; optional Google Drive sync (planned). `.backup/` is a shared runtime namespace — @memory rollover and @flow (plan archive) also write there.
 
 # Daily commands
 

.backupignore

@@ -2,7 +2,6 @@
 # Lines starting with # are comments. Blank lines are ignored.
 # Edit this file to customize. Source defaults: handlers/ignore/patterns.py
 
-.backup_system/
 .backup/
 .git/
 .svn/
@@ -27,4 +26,3 @@ dist/
 *.log
 .ruff_cache/
 .coverage
-*logs

CHANGELOG.md

@@ -32,6 +32,19 @@ PyPI version — not the changelog header.
   the event, its `BULLETINS.central.json` store no longer exists, and prax
   already prunes `bulletin_board` as a deprecated section. Archived + unwired
   from the event registry; prax's pruning stays (td-102).
+- **Dead `backup/run/` test dir** — leftover from an ad-hoc backup test run
+  (only its generated `.backupignore` had been tracked); removed (td-218).
+
+### Documentation
+
+- **Backup docs corrected** — `.backup/` is now documented as a **shared runtime
+  namespace** (@backup stores + @memory rollover safety copies + @flow plan
+  archive), not @backup-exclusive. @backup's README gained full command coverage,
+  the `.backup/` store layout, and a `.backupignore` ("gitignore for backups")
+  section; its branch prompt's stale `.backup_system/` / `drive_test.py` names
+  were fixed. Root README lists @backup and documents `.backupignore`; the navmap
+  was corrected. The shipped root `/.backupignore` was realigned to
+  `BUILTIN_IGNORES` (dropped stale `.backup_system/` + over-broad `*logs`).
 
 ## [2026-06-23]
 

README.md

@@ -155,7 +155,7 @@ drone @ai_mail dispatch @agent "Archive old sessions" "Find sessions older than
 
 ## The Reference Implementation
 
-AIPass ships with 13 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.
+AIPass ships with 14 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.
 
 ```
 devpulse (orchestrator)
@@ -170,7 +170,8 @@ devpulse (orchestrator)
    ├── memory   — automatic archival, ChromaDB, semantic search
    ├── api      — LLM access layer (OpenRouter, multi-provider)
    ├── trigger  — event-driven automation + self-healing
-   └── cli      — terminal formatting and rich output
+   ├── cli      — terminal formatting and rich output
+   └── backup   — local-first snapshots + restore (optional Drive sync)
 ```
 
 These agents work on the **same filesystem, same project, same time** — no sandboxes, no worktrees. This is the pattern your projects inherit.
@@ -201,6 +202,7 @@ These agents work on the **same filesystem, same project, same time** — no san
 | [**hooks**](src/aipass/hooks/README.md) | Hook engine — per-project config, sound control, event dispatch |
 | [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
 | [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output |
+| [**backup**](src/aipass/backup/README.md) | Local-first backups — snapshots, versioning, restore (optional Google Drive sync) |
 
 </details>
 
@@ -266,6 +268,9 @@ AIPass stores everything locally in your project directory. To remove it:
 rm -rf .aipass/ .claude/ .ai_mail.local/ hooks/ src/
 rm -f CLAUDE.md AGENTS.md *_REGISTRY.json .gitignore
 
+# If you ran the backup system, also remove its local state + shipped config
+rm -rf .backup/ && rm -f .backupignore
+
 # If you installed via pip
 pip uninstall aipass
 ```

src/aipass/backup/.aipass/aipass_local_prompt.md

@@ -39,7 +39,7 @@ apps/
 │   ├── settings.py        # Settings UI (stub — low priority)
 │   ├── drive_sync.py      # Drive sync (stub — DPLAN-003)
 │   ├── drive_stats.py     # Drive stats (stub)
-│   ├── drive_test.py      # Drive test (stub)
+│   ├── drive_check.py     # Drive check (stub — DPLAN-003)
 │   └── drive_clear.py     # Drive clear (stub)
 └── handlers/
     ├── copy/              # File copying (snapshot + versioned)
@@ -47,7 +47,7 @@ apps/
     ├── ignore/            # .backupignore patterns + whitelist
     ├── json/              # JSON persistence, atomic writes, ops log
     ├── path/              # Backup path building
-    ├── project/           # Config, registry, setup (.backup_system/)
+    ├── project/           # Config, registry, setup (.backup/)
     ├── report/            # Result formatting
     ├── scan/              # Directory walking + filtering
     ├── state/             # Changelog, metadata, timestamps
@@ -58,11 +58,11 @@ apps/
 ## Integration
 
 - **Depends on:** @prax for logging, @cli for Rich console output
-- **Serves:** Any project on the PC — backups are project-owned (.backup_system/ in target root)
+- **Serves:** Any project on the PC — backups are project-owned (.backup/ in target root)
 
 ## Working Habits
 
-- Project-owned design: .backup_system/ and .backupignore live in the TARGET project, not centrally
+- Project-owned design: .backup/ and .backupignore live in the TARGET project, not centrally
 - Normal citizen namespace: uses `from aipass.backup.apps.modules.*` / `from aipass.backup.apps.handlers.*`
 - Entry point sets AIPASS_BRANCH_NAME env var for Prax
 - BUILTIN_IGNORES in patterns.py is the single source for default ignore patterns

src/aipass/backup/README.md

@@ -64,11 +64,59 @@ apps/
 backup register <path> [--name <name>]   # Register a project for backup
 backup snapshot <path|@name>             # Full mirror backup
 backup versioned <path|@name>            # Incremental timestamped backup
-backup all <path|@name>                  # Snapshot + versioned
+backup all <path|@name>                  # Snapshot + versioned + drive
 backup status <path|@name>              # Show backup info and history
-backup --version                        # Show version
+backup restore <path|@name> list <file>  # List available versions of a file
+backup restore <path|@name> file <f> <o> # Restore a file version to output path
+backup settings <path|@name>             # Settings UI (stub)
+backup drive_sync <path|@name>           # Google Drive sync (stub — DPLAN-003)
+backup drive_check <path|@name>          # Drive connectivity check (stub — DPLAN-003)
+backup drive_stats <path|@name>          # Drive storage stats (stub — DPLAN-003)
+backup drive_clear <path|@name>          # Clear Drive sync state (stub — DPLAN-003)
 ```
 
+All 11 commands are auto-discovered by the entry point router.
+
+---
+
+## `.backup/` Store Structure
+
+Each registered project gets a `.backup/` directory at its root:
+
+```
+.backup/
+├── config.json          # Project backup configuration
+├── snapshots/           # Full mirror copies (eager — created on register)
+├── versioned/           # Incremental timestamped backups (lazy)
+├── logs/                # Operation logs (eager — created on register)
+├── timestamps.json      # Backup timing metadata (lazy)
+├── changelog.json       # Change history (lazy)
+└── drive_tracker.json   # Drive sync dedup tracker (lazy)
+```
+
+On `register`, only `snapshots/` and `logs/` are created eagerly (plus `config.json`). The rest are created lazily on first use.
+
+**Shared namespace:** `.backup/` is NOT exclusive to @backup. Three writers use it:
+- **@backup** — snapshot/versioned stores at a registered project root
+- **@memory** — rollover safety copies (`rollover_backup_*.json`) written to `<branch>/.backup/` during memory overflow
+- **@flow** — closed plans archived to `<repo-root>/.backup/processed_plans/` for vectorization by @memory
+
+The root `.gitignore` covers all three with a single `.backup/` entry.
+
+---
+
+## `.backupignore`
+
+A true `.gitignore` for backups, using real pathspec/gitwildmatch semantics:
+- `#` comments, blank lines ignored
+- `!` negation (un-ignore a path)
+- Trailing `/` for directory-only matching
+- Last-match-wins ordering
+
+Lives at the **project root** and is the single source of truth governing snapshot, versioned, Drive sync, and mirror-cleanup operations. Generated from `BUILTIN_IGNORES` in `handlers/ignore/patterns.py` during `register`. The `.backup/` directory is included in `BUILTIN_IGNORES`, so the store self-excludes from its own backups.
+
+The repo-root `/.backupignore` ships intentionally as the curated default so users don't snapshot junk.
+
 ---
 
 ## Integration Points
@@ -78,4 +126,4 @@ backup --version                        # Show version
 - @cli — Rich console output
 
 ### Provides To
-- Any project on the PC — backups are project-owned (.backup/ in target root)
+- Any project on the PC — backups are project-owned (`.backup/` in target root)

src/aipass/backup/run/.backupignore

@@ -1,28 +0,0 @@
-# Backup System ignore patterns (gitignore-style)
-# Lines starting with # are comments. Blank lines are ignored.
-# Edit this file to customize. Source defaults: handlers/ignore/patterns.py
-
-.backup/
-.git/
-.svn/
-.hg/
-__pycache__/
-.pytest_cache/
-*.pyc
-*.pyo
-*.egg-info/
-.venv/
-venv/
-.tox/
-node_modules/
-.vscode/
-.idea/
-*.swp
-*.swo
-.DS_Store
-Thumbs.db
-build/
-dist/
-*.log
-.ruff_cache/
-.coverage