---
name: "clawpilot-state-backup"
description: "Backs up selected Microsoft Scout (Clawpilot) local state from ~\\.scout to OneDrive. Keeps a mirrored 'latest' copy plus timestamped snapshots with 14-snapshot retention. Excludes auth tokens, encryption keys, binaries, logs, audit logs, and diagnostics."
---

This skill manages the Microsoft Scout (Clawpilot) state backup system.

## Backup script location
`%USERPROFILE%\OneDrive - Microsoft\Documents\Clawpilot\Backups\Backup-ClawpilotSelectedState.ps1`

## Source of truth
`%USERPROFILE%\.scout`

**Important history:** Scout migrated its state root from `%USERPROFILE%\.copilot` to `%USERPROFILE%\.scout` on **2026-07-14** (marker file: `.scout-migration-complete`). Until 2026-07-28 the script still pointed at the legacy `.copilot` folder, so it was re-copying frozen data every night while none of the live state was protected. This was corrected on 2026-07-28. If you ever see the script reading from `.copilot`, that is the old bug.

## What is backed up (allow-list, relative to `~\.scout`)
**Folders**
- `m-sessions` — Scout chat session history
- `m-skills` — user-authored skills
- `skills` — bundled / installed skills
- `m-automations` — scheduled automations
- `heartbeat` — heartbeat settings
- `copilot\session-state` — Copilot CLI session state

**Files**
- `m-settings.json`, `m-preferences.json`, `m-mcp-servers.json`, `m-memory.json`, `memora-state.json`, `m-region.json`
- `copilot\config.json`, `copilot\session-store.db`, `copilot\session-store.db-wal`, `copilot\session-store.db-shm`

## What is excluded (never copied)
`bin`, `ide`, `logs`, `browser-output`, `copilot\cache`, `copilot\logs`, `m-audit-logs`, `m-auth`, `m-encryption-key.enc`, `m-github-update-token.enc`, `m-avatar-cache.json`, `m-diagnostics.jsonl*`, `m-loki-*.json`, `m-onedrive-*.json`, `m-sync-state.json`, `m-window-state.json`

## Backup destination
`%USERPROFILE%\OneDrive - Microsoft\Documents\Clawpilot\Backups\.copilot-selected-state\`
- `latest\` — rebuilt (mirrored) every run, so deleted source files do not linger
- `snapshots\<yyyyMMdd-HHmmss>\` — point-in-time copies; the 14 most recent are kept
- `latest-legacy-dotcopilot\` — permanent frozen archive of the old `.copilot` state (3,567 files / 489 MB). Never modified. Snapshots dated `20260728-175440` and earlier are also legacy `.copilot` copies.

Each folder the script writes contains a `.scout-state-backup` marker file. **Retention only prunes marked folders**, so legacy snapshots are never deleted automatically.

## Running a manual backup
```
& "$env:USERPROFILE\OneDrive - Microsoft\Documents\Clawpilot\Backups\Backup-ClawpilotSelectedState.ps1"
```
Options:
- `-RetentionCount <n>` — number of marked snapshots to keep (default 14; `0` disables pruning)
- `-SkipSnapshot` — refresh `latest\` only

Exit codes: `0` = success, `1` = completed with warnings (warning text is printed).

## Automation
"Daily Clawpilot selected-state backup" (id `32bdqhszmpzjt4v2`) runs the script every day at 5:00 PM.

## Restore instructions (new machine / reinstall)
1. Close Scout/Clawpilot completely.
2. Optionally make a safety copy of the current `%USERPROFILE%\.scout` folder.
3. Copy the allow-listed folders/files from `latest\` (or a chosen `snapshots\<timestamp>\`) back into `%USERPROFILE%\.scout`, preserving the `copilot\` subfolder structure.
4. Do not copy the `.scout-state-backup` marker file into the restored folder.
5. Reopen Scout and confirm old sessions, skills, automations, and settings are visible.
6. Re-authenticate (M365, Azure CLI) — auth tokens are deliberately not backed up.
7. Re-create the daily automation if it was not restored.

## Safety rules
- Backup output is stored only in the user's own protected OneDrive — never push to GitHub or any shared/public location.
- Never back up encryption keys, auth tokens, audit logs, or diagnostics.
- The script only copies local files into the OneDrive-synced folder — no network calls.