clawmini 0.0.8 → 0.0.9

package/docs/backups/SPEC.md

@@ -0,0 +1,296 @@
+# `.clawmini` Backup — what's safe, what's not, and how to do it
+
+## Goal
+
+Decide what under a workspace's `.clawmini/` directory can safely be pushed
+to a private git remote (or any external backup target) for disaster
+recovery, and what must stay on the local machine.
+
+"Private repo" is not the same as "secret store". Even a private GitHub
+repo:
+
+- Stores everything in plaintext on Anthropic's, GitHub's, and any
+  collaborator's disks.
+- Keeps a permanent history — once a token is committed, rotation is the
+  only real remediation.
+- Gets cloned to CI, other workstations, and any future tooling you wire
+  up. Each clone is a copy of every secret it contains.
+- Is reachable by anyone with read access to the repo (org admins, future
+  teammates, leaked SSH keys, stolen laptops).
+
+So the bar for "safe to back up" is: would I be comfortable if this file
+were posted in a private channel that 5 people will eventually read? Not
+"is the repo private right now?".
+
+---
+
+## Inventory of `.clawmini/`
+
+Sensitivity ratings: **LOW** = config/metadata, **MED** = may contain
+secrets depending on user, **HIGH** = routinely contains secrets or
+private content, **CRIT** = always contains live credentials.
+
+### Stable, user-authored config
+
+| Path | Sensitivity | Notes |
+| --- | --- | --- |
+| `settings.json` | LOW | Default chat id, environment-to-path map. |
+| `policies.json` | LOW | Policy command/args definitions. |
+| `policy-scripts/*.js` | LOW–MED | User code; treat like any source file. |
+| `commands/*.{md,txt}` | LOW–MED | Slash-command text. May contain prompts/snippets. |
+| `templates/*` | LOW–MED | Mirrors built-in templates; rarely sensitive. |
+| `chats/<id>/settings.json` | LOW | Per-chat metadata. |
+| `agents/<id>/installed-files.json` | LOW | SHA manifest only. |
+
+### Per-agent / per-environment config (mostly safe, leaks via `env`)
+
+| Path | Sensitivity | Notes |
+| --- | --- | --- |
+| `agents/<id>/settings.json` | MED | `env` and `subagentEnv` may hold API keys. |
+| `agents/<id>/sessions/<sid>/settings.json` | MED | Same shape, per session. |
+| `environments/<name>/env.json` | MED | `env` block may hold secrets; `init` script may reference them. |
+| `environments/<name>/*` | MED | Whatever the user dropped in. |
+
+### Conversation + execution history (private content, sometimes secrets)
+
+| Path | Sensitivity | Notes |
+| --- | --- | --- |
+| `chats/<id>/chat.jsonl` | HIGH | Full transcript: user prompts, model output, tool I/O, command stdout/stderr, file contents pasted in. Routinely contains code, internal docs, occasionally credentials echoed by a misbehaving script. Append-only, can be very large. |
+
+### Adapter config + state (credential central)
+
+| Path | Sensitivity | Notes |
+| --- | --- | --- |
+| `adapters/discord/config.json` | **CRIT** | `botToken` is a live Discord bot token (required field). |
+| `adapters/discord/state.json` | LOW | Sync cursors + channel→chat map. No secrets. |
+| `adapters/google-chat/config.json` | **CRIT** | `oauthClientId` / `oauthClientSecret` for Drive. |
+| `adapters/google-chat/state.json` | **CRIT** | `oauthTokens` — live refresh + access tokens. |
+
+### Runtime / ephemeral / IPC
+
+| Path | Sensitivity | Notes |
+| --- | --- | --- |
+| `daemon.sock` (a.k.a. `server.sock` in older builds) | n/a | Unix socket — not a real file, can't be copied. Exclude. |
+| `daemon.log` | MED | Stderr from the daemon. Paths, errors, sometimes argv. |
+| `logs/*.log` (`web.log`, `adapter-*.log`) | MED | Same shape, per service. |
+| `supervisor.pid` | LOW | `<pid>:<startTime>`. Worthless on another machine. |
+| `tmp/requests/<rid>.json` | HIGH | Pending policy requests, including `executionResult.{stdout,stderr}`. |
+| `tmp/snapshots/*` | HIGH | Up-to-5MB copies of files a policy is about to touch. |
+| `tmp/discord/*`, `tmp/google-chat/*` | HIGH | Downloaded chat attachments. |
+| `tmp/<agentId>/stdout-<rid>.txt`, `stderr-<rid>.txt` | HIGH | Truncated command output (>500 chars). |
+| `*.<pid>.<hex>.tmp` | n/a | Atomic-write scratch files. Exclude. |
+
+### "There may be more"
+
+The user explicitly flagged this. Things that are likely or known to
+appear over time and aren't enumerated above:
+
+- New adapter directories as new adapters land (each tends to follow the
+  `config.json` + `state.json` pattern — assume CRIT until proven LOW).
+- Hooks / skills installed under `agents/<id>/` by templates.
+- Future cache directories.
+
+The backup policy below is therefore **allow-list**, not deny-list — new
+unknown files default to *not backed up* until a human looks at them.
+
+---
+
+## Options considered
+
+### A. Back up `.clawmini/` wholesale to a private git repo
+
+Easiest. One `git init` inside `.clawmini`, push to a private remote,
+done.
+
+- **Pro:** zero ongoing thought; everything recovers.
+- **Con:** ships every Discord bot token, every OAuth refresh token, and
+  every chat transcript to the remote in plaintext, forever. Any future
+  collaborator, CI runner, or leaked deploy key gets all of it. Token
+  rotation requires git-history rewriting.
+- **Verdict:** rejected. The credential exposure is not acceptable even
+  for a single-user "private" repo.
+
+### B. Wholesale backup with `git-crypt` / `git-secret` / `age` for sensitive files
+
+Same as A, but adapter configs, state, and chat history are encrypted at
+rest in the repo with a key kept locally.
+
+- **Pro:** one repo covers everything; secrets are encrypted; you can
+  share the repo without sharing the key.
+- **Con:** adds a key-management problem (you now must back up the key
+  separately, or losing the laptop also loses the backup). `git-crypt`
+  in particular smudge/cleans on every checkout — easy to misconfigure
+  and accidentally commit plaintext. Encrypting an append-only JSONL
+  blows up diffs.
+- **Verdict:** viable, but heavier than the user's needs and trades one
+  problem (secret leakage) for another (key custody). Worth it only if
+  full chat history backup is a hard requirement.
+
+### C. Allow-list backup of low-risk config only
+
+A `.gitignore` inside `.clawmini/` that excludes by default and includes
+a known-safe set: `settings.json`, `policies.json`, `policy-scripts/`,
+`commands/`, `templates/`, `chats/*/settings.json`,
+`agents/*/settings.json`, `agents/*/installed-files.json`,
+`environments/*/env.json`, `adapters/*/state.json` *except* google-chat.
+
+Per-agent/env settings sometimes contain `env` API keys — still risky.
+This option drops them or asks the user to inline-strip them.
+
+- **Pro:** simple, no encryption, no key. Restoring on a new machine
+  gives back the *shape* of the workspace (chats, agents, environments,
+  policies) immediately.
+- **Con:** chat transcripts are not backed up. Adapter credentials are
+  not backed up — you have to re-do `clawmini init` for each adapter on
+  restore. `agents/*/settings.json` may still leak if the user put keys
+  in `env`.
+- **Verdict:** strong default. Matches "back up the things that are a
+  pain to recreate, accept that secrets get rotated."
+
+### D. Allow-list config (option C) **plus** encrypted bundle for chats and adapters
+
+Option C handles the durable config in cleartext. Sensitive content goes
+into an encrypted tarball committed alongside.
+
+- **Pro:** chats and adapter creds *are* recoverable; the encrypted
+  blob keeps them out of plain git history.
+- **Con:** key management again; the tar grows; restore is a two-step.
+- **Verdict:** the right answer if the user wants real DR, not just
+  config preservation.
+
+### E. Don't use git at all — use a backup tool (restic, borg, time machine)
+
+`restic` to a private S3 bucket / B2 / SSH host with a passphrase, or
+just include `.clawmini` in Time Machine.
+
+- **Pro:** purpose-built for this; encryption, dedup, point-in-time
+  snapshots, prune. Handles binary growth (chat.jsonl) far better than
+  git. No accidental plaintext credentials in a permanent history.
+- **Con:** not a git repo, so no easy diffing or merging across
+  machines. You don't get the "view my settings on github.com" niceness.
+- **Verdict:** technically the cleanest answer for the "avoid data loss"
+  framing the user mentioned at the end. Worth recommending alongside.
+
+---
+
+## Recommendation
+
+Two-track approach. Pick based on what the user actually wants out of
+the backup.
+
+### Track 1 — config-only git backup (recommended default)
+
+Use **Option C** for the version-controlled, shareable, "I want to see
+my workspace settings on a new laptop" backup.
+
+Concretely: put a `.gitignore` at the root of `.clawmini/` that opts
+out of everything and re-opts-in only the safe set. Suggested contents:
+
+```gitignore
+# default: ignore everything
+*
+
+# re-include known-safe config
+!.gitignore
+!settings.json
+!policies.json
+!policy-scripts/
+!policy-scripts/**
+!commands/
+!commands/**
+!templates/
+!templates/**
+
+# chat *metadata* only — not transcripts
+!chats/
+chats/*
+!chats/*/
+!chats/*/settings.json
+
+# agents: settings + manifest, no sessions, no tmp
+!agents/
+agents/*
+!agents/*/
+!agents/*/settings.json
+!agents/*/installed-files.json
+
+# environments: env.json only
+!environments/
+environments/*
+!environments/*/
+!environments/*/env.json
+
+# adapters: state only, and only for adapters known not to hold creds
+# (discord state is safe; google-chat state holds OAuth tokens — exclude)
+!adapters/
+adapters/*
+!adapters/discord/
+adapters/discord/*
+!adapters/discord/state.json
+
+# everything else stays ignored: chat.jsonl, tmp/, logs/, daemon.log,
+# daemon.sock, supervisor.pid, *.tmp, adapters/*/config.json,
+# adapters/google-chat/state.json, agents/*/sessions/, agents/*/tmp/
+```
+
+Caveats the user should accept up front:
+
+1. **Re-check `agents/*/settings.json` and `environments/*/env.json`
+   before the first push** — if the user has put API keys into `env`,
+   they'll go to the remote. Either move them out (e.g. into shell env
+   or a separate uncommitted file) or downgrade this track to manual
+   review.
+2. **Adapter credentials are not backed up.** On a new machine, re-run
+   `clawmini init` for each adapter. This is a feature, not a bug:
+   token rotation is the standard fix for "laptop lost".
+3. **Chat history is not backed up.** If that's a problem, add Track 2.
+
+### Track 2 — full disaster-recovery backup (optional, for chats + creds)
+
+Use **Option E** (`restic` or similar) for the "I don't want to lose my
+chat history if my disk dies" backup. Point it at the entire
+`.clawmini/` directory excluding only `daemon.sock` and `*.tmp`
+scratch files. The tool handles encryption, incremental snapshots, and
+the inevitable size growth of `chat.jsonl`.
+
+Rough sketch:
+
+```sh
+restic -r <repo> backup \
+  ~/path/to/workspace/.clawmini \
+  --exclude '*.sock' --exclude '*.tmp' \
+  --exclude '.clawmini/tmp/snapshots/*'   # optional: skip large file snapshots
+```
+
+This is the right tool for opaque, mutable, occasionally-sensitive
+runtime state. Don't try to make git do it.
+
+### What about Option D (encrypted bundle in the same git repo)?
+
+Only worth the complexity if the user specifically wants *one* repo
+that contains both the config and the sensitive bits. Otherwise Track 1
++ Track 2 separates concerns cleanly: git for the human-readable
+config, restic for the runtime data.
+
+---
+
+## Summary table — what goes where
+
+| Path | Track 1 (git) | Track 2 (restic) |
+| --- | --- | --- |
+| `settings.json`, `policies.json` | ✅ | ✅ |
+| `policy-scripts/`, `commands/`, `templates/` | ✅ | ✅ |
+| `chats/*/settings.json` | ✅ | ✅ |
+| `chats/*/chat.jsonl` | ❌ | ✅ |
+| `agents/*/settings.json` (review for `env` secrets!) | ⚠️ | ✅ |
+| `agents/*/installed-files.json` | ✅ | ✅ |
+| `agents/*/sessions/*`, `agents/*/tmp/*` | ❌ | ✅ |
+| `environments/*/env.json` (review for `env` secrets!) | ⚠️ | ✅ |
+| `adapters/discord/config.json` | ❌ | ✅ |
+| `adapters/discord/state.json` | ✅ | ✅ |
+| `adapters/google-chat/config.json` | ❌ | ✅ |
+| `adapters/google-chat/state.json` | ❌ | ✅ |
+| `daemon.log`, `logs/*.log` | ❌ | optional |
+| `tmp/**`, `*.tmp`, `*.sock`, `supervisor.pid` | ❌ | ❌ |
+
+⚠️ = include only after auditing the file for inline secrets.

package/docs/backups/clawmini.gitignore

@@ -0,0 +1,69 @@
+# Allow-list `.gitignore` for a Clawmini workspace's `.clawmini/` directory.
+#
+# Installed automatically by `clawmini init`, and also available as a
+# template at <clawmini>/docs/backups/clawmini.gitignore for retrofitting
+# an existing workspace.
+#
+# Everything is ignored by default; the entries below opt specific paths
+# back in. New unknown files therefore stay out of the backup until a
+# human reviews them. See the Clawmini `docs/guides/backups.md` for the
+# rationale and `docs/backups/SPEC.md` for the full tradeoff analysis.
+
+# default: ignore everything
+*
+
+# re-include known-safe config
+!.gitignore
+!settings.json
+!policies.json
+!policy-scripts/
+!policy-scripts/**
+!commands/
+!commands/**
+!templates/
+!templates/**
+
+# chat *metadata* only — NOT transcripts (chat.jsonl is excluded)
+!chats/
+chats/*
+!chats/*/
+!chats/*/settings.json
+
+# agents: settings + manifest only — no sessions, no tmp
+# WARNING: review settings.json for inline `env` secrets before committing.
+!agents/
+agents/*
+!agents/*/
+!agents/*/settings.json
+!agents/*/installed-files.json
+
+# environments: env.json only
+# WARNING: review env.json for inline `env` secrets before committing.
+!environments/
+environments/*
+!environments/*/
+!environments/*/env.json
+
+# adapters: state only, and only for adapters known not to hold creds.
+# - discord/state.json is sync metadata (safe).
+# - discord/config.json holds the bot token (excluded).
+# - google-chat/config.json holds the OAuth client secret (excluded).
+# - google-chat/state.json holds live OAuth tokens (excluded).
+!adapters/
+adapters/*
+!adapters/discord/
+adapters/discord/*
+!adapters/discord/state.json
+
+# Everything below stays ignored by default. Listed here for clarity:
+#   chats/*/chat.jsonl       - full transcripts (private content)
+#   adapters/*/config.json   - credentials
+#   adapters/google-chat/state.json - OAuth tokens
+#   agents/*/sessions/       - per-session state (may contain env secrets)
+#   agents/*/tmp/            - command stdout/stderr captures
+#   tmp/                     - policy requests, file snapshots, attachments
+#   logs/                    - service logs
+#   daemon.log               - daemon stderr
+#   daemon.sock, server.sock - Unix sockets (not real files)
+#   supervisor.pid           - process metadata
+#   *.tmp                    - atomic-write scratch files

package/docs/guides/backups.md

@@ -0,0 +1,332 @@
+# Backing up your Clawmini workspace
+
+Clawmini stores everything that matters about a workspace under
+`.clawmini/`: chats, agents, environments, policies, and adapter
+credentials. Losing that directory loses your chat history and forces
+you to re-authenticate every adapter. This guide explains how to back
+it up without leaking secrets.
+
+## How to think about it
+
+`.clawmini/` is a mix of three things, and they want different
+treatment:
+
+1. **Durable config** — `settings.json`, `policies.json`,
+   `policy-scripts/`, `commands/`, `templates/`, per-chat metadata,
+   per-agent settings, per-environment settings. Hand-written, slowly
+   evolving, useful to review on github.com.
+2. **Runtime state and history** — `chats/<id>/chat.jsonl`, logs,
+   policy requests, file snapshots, command stdout/stderr captures.
+   Mutable, sometimes large, sometimes contains private content (code
+   you pasted, command output, files the agent looked at).
+3. **Credentials** — `adapters/discord/config.json` (bot token),
+   `adapters/google-chat/config.json` (OAuth client secret),
+   `adapters/google-chat/state.json` (live OAuth refresh tokens).
+   Sometimes also embedded in `agents/*/settings.json` or
+   `environments/*/env.json` if you put API keys in their `env` block.
+
+The first one wants version control. The second wants opaque
+incremental snapshots. The third doesn't want to be in any backup that
+will ever be cloned, shared, or pushed to a remote in plaintext.
+
+A "private" git repo is **not** a credential vault: history is forever,
+clones are unencrypted, and read access tends to widen over time
+(collaborators, CI, leaked deploy keys). Treat it like a private Slack
+channel — fine for config, wrong for tokens.
+
+## The two tracks
+
+Most users want both of these, for different reasons.
+
+### Track 1 — Git for config (recommended)
+
+Put `.clawmini/` itself under git, with a strict allow-list
+`.gitignore` that ships only the safe-to-share config. Push to a
+private remote. You get diffs, history, and a way to restore your
+workspace shape on a new machine in one clone.
+
+What's included: `settings.json`, `policies.json`, `policy-scripts/`,
+`commands/`, `templates/`, chat metadata (not transcripts), agent
+settings, environment settings, Discord adapter sync state.
+
+What's excluded: chat transcripts, adapter credentials, OAuth tokens,
+logs, tmp files, sockets. On restore you re-run `clawmini init` for
+each adapter to rotate creds.
+
+**Setup:**
+
+`clawmini init` installs `.clawmini/.gitignore` automatically using the
+allow-list template at
+[`docs/backups/clawmini.gitignore`](../backups/clawmini.gitignore).
+Workspaces created before this behaviour landed can retrofit it by
+copying that template manually:
+
+```sh
+cp /path/to/clawmini/docs/backups/clawmini.gitignore .clawmini/.gitignore
+```
+
+Then push it to a private remote:
+
+```sh
+cd .clawmini
+git init
+git add .
+git status   # *** review carefully before the first commit ***
+git commit -m "Initial clawmini workspace backup"
+git remote add origin <your-private-remote>
+git push -u origin main
+```
+
+**Audit before your first push.** Two files are included by the
+allow-list but can leak secrets if you've put API keys into them:
+
+- `agents/*/settings.json` — check the `env` and `subagentEnv`
+  blocks.
+- `environments/*/env.json` — check the `env` block.
+
+If you have inline secrets there, move them out (shell environment, a
+separate uncommitted file, your OS keychain) before committing.
+
+### Track 2 — Restic for everything else (optional but recommended)
+
+If you want chat history and adapter credentials to survive a disk
+failure, use a real backup tool. Restic, Borg, and Time Machine all
+work; the walkthrough below uses restic because it's cross-platform,
+encrypts at rest, dedupes between snapshots, and handles the unbounded
+growth of `chat.jsonl` far better than git would.
+
+The setup below backs up to **another local folder on the same
+machine** every day. That protects you from `rm -rf`, agents going
+sideways, and accidental git operations — but **not** from disk
+failure or theft. Point the repo at an external drive or a remote
+target (`b2:`, `sftp:`, `s3:`, …) when you want real off-device
+durability; everything else in this section stays the same.
+
+#### 1. Install restic
+
+macOS:
+
+```sh
+brew install restic
+```
+
+Linux (pick whichever your distro uses):
+
+```sh
+sudo apt install restic            # Debian / Ubuntu
+sudo dnf install restic            # Fedora / RHEL
+sudo pacman -S restic              # Arch
+```
+
+#### 2. Pick a destination and a passphrase
+
+Choose a folder *outside* your workspace — ideally on a different disk
+or partition, but any local path works for a baseline.
+
+```sh
+export RESTIC_REPOSITORY="$HOME/Backups/clawmini-restic"
+mkdir -p "$RESTIC_REPOSITORY"
+```
+
+Restic encrypts every snapshot with a passphrase. If you lose it, the
+backup is unrecoverable — store it somewhere you'll still have after
+your laptop dies (password manager, paper in a drawer, etc.). Save it
+to a 0600-mode file so the scheduled job can read it without a prompt:
+
+```sh
+umask 077
+printf '%s\n' 'your-long-passphrase-here' > "$HOME/.config/restic/clawmini.pw"
+```
+
+Initialize the repo (one time only):
+
+```sh
+restic init --password-file "$HOME/.config/restic/clawmini.pw"
+```
+
+#### 3. Write the backup script
+
+Save this as `~/bin/clawmini-backup.sh` and `chmod +x` it. Edit
+`WORKSPACE` to point at your workspace.
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+
+WORKSPACE="$HOME/path/to/workspace"
+export RESTIC_REPOSITORY="$HOME/Backups/clawmini-restic"
+export RESTIC_PASSWORD_FILE="$HOME/.config/restic/clawmini.pw"
+
+RESTIC_BIN="$(command -v restic)"
+
+"$RESTIC_BIN" backup "$WORKSPACE/.clawmini" \
+  --tag clawmini \
+  --exclude '*.sock' \
+  --exclude '*.tmp' \
+  --exclude '.clawmini/tmp/snapshots/*'
+
+"$RESTIC_BIN" forget \
+  --tag clawmini \
+  --keep-daily 30 --keep-weekly 8 --keep-monthly 12 \
+  --prune
+```
+
+The retention policy keeps the last 30 daily snapshots, 8 weekly, and
+12 monthly — roughly a year of history with a long tail of dailies for
+recent recovery. `--prune` reclaims the space from forgotten snapshots
+in the same run.
+
+Verify the script works manually before scheduling it:
+
+```sh
+~/bin/clawmini-backup.sh
+restic snapshots                   # should list a snapshot
+```
+
+#### 4. Schedule it daily
+
+##### macOS — launchd
+
+Save this as `~/Library/LaunchAgents/com.clawmini.backup.plist`,
+replacing `YOURUSER` with your home-directory username:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>com.clawmini.backup</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/Users/YOURUSER/bin/clawmini-backup.sh</string>
+    </array>
+    <key>StartCalendarInterval</key>
+    <dict>
+      <key>Hour</key><integer>3</integer>
+      <key>Minute</key><integer>15</integer>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/Users/YOURUSER/Library/Logs/clawmini-backup.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOURUSER/Library/Logs/clawmini-backup.log</string>
+  </dict>
+</plist>
+```
+
+Load it and verify:
+
+```sh
+launchctl load ~/Library/LaunchAgents/com.clawmini.backup.plist
+launchctl list | grep clawmini       # confirms it's registered
+launchctl start com.clawmini.backup   # run once now
+tail ~/Library/Logs/clawmini-backup.log
+```
+
+To remove it later: `launchctl unload ~/Library/LaunchAgents/com.clawmini.backup.plist`.
+
+If your laptop is asleep at the scheduled time, launchd runs the job
+on the next wake. Good enough for a daily backup.
+
+##### Linux — systemd timer
+
+Create the service unit at `~/.config/systemd/user/clawmini-backup.service`:
+
+```ini
+[Unit]
+Description=Clawmini workspace restic backup
+
+[Service]
+Type=oneshot
+ExecStart=%h/bin/clawmini-backup.sh
+Nice=10
+IOSchedulingClass=idle
+```
+
+Create the timer at `~/.config/systemd/user/clawmini-backup.timer`:
+
+```ini
+[Unit]
+Description=Daily Clawmini restic backup
+
+[Timer]
+OnCalendar=*-*-* 03:15:00
+Persistent=true
+RandomizedDelaySec=15m
+
+[Install]
+WantedBy=timers.target
+```
+
+`Persistent=true` makes systemd run a missed backup on next boot
+(important for laptops). Enable and start:
+
+```sh
+systemctl --user daemon-reload
+systemctl --user enable --now clawmini-backup.timer
+systemctl --user list-timers clawmini-backup.timer
+```
+
+To run a backup immediately:
+`systemctl --user start clawmini-backup.service`. Logs:
+`journalctl --user -u clawmini-backup.service`.
+
+If you want the timer to fire while you're logged out, run
+`loginctl enable-linger $USER` once.
+
+If you don't have systemd (or prefer cron), the equivalent crontab
+entry is:
+
+```cron
+15 3 * * * /home/YOURUSER/bin/clawmini-backup.sh >> /home/YOURUSER/.local/share/clawmini-backup.log 2>&1
+```
+
+#### 5. Restore
+
+```sh
+restic snapshots                                # list backups
+restic restore latest --target /tmp/restore     # pull latest into /tmp/restore
+```
+
+The restored tree contains a `.clawmini/` directory you can copy back
+into a fresh workspace.
+
+If you don't want a separate tool, Time Machine on macOS or your
+distro's equivalent covers the same use case at coarser granularity;
+just make sure `.clawmini/` is included.
+
+## Common questions
+
+**"Can I just push the whole `.clawmini/` to a private repo?"** Don't.
+Your Discord bot token, Google OAuth client secret, and live OAuth
+refresh tokens would go to the remote in plaintext, in permanent
+history. Rotation (not deletion) is the only fix once that happens.
+
+**"What about `git-crypt` so I can keep one repo?"** It works but adds
+a key-management problem (lose the key, lose the backup) and easy
+misconfigurations (smudge/clean filters silently fail). Worth it only
+if you specifically want one combined repo. Otherwise Track 1 + Track 2
+separates concerns more cleanly.
+
+**"Will Track 1 let me move my workspace to a new laptop?"** Yes for
+config; no for credentials and chat history. After cloning, you re-run
+`clawmini init` for each adapter (which rotates the bot token / OAuth
+grant — generally what you want when moving machines anyway). Track 2
+restores the rest.
+
+**"What if I add a new adapter or some new file appears under
+`.clawmini/`?"** The `.gitignore` is allow-list, so new files default
+to *not* tracked. Inspect `git status --ignored`, decide whether the
+new file is safe, and add an explicit `!path/to/file` if it is.
+
+**"Can I trust `agents/*/settings.json` to be safe?"** Mostly yes —
+it's template-derived config — but the `env` block is a free-form map
+where users sometimes drop API keys. Audit before each commit, or
+adopt a habit of keeping secrets out of that file entirely.
+
+## Reference
+
+- Allow-list `.gitignore` template:
+  [`docs/backups/clawmini.gitignore`](../backups/clawmini.gitignore)
+- Full sensitivity inventory and option analysis:
+  [`docs/backups/SPEC.md`](../backups/SPEC.md)