birdclaw 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.0 - 2026-04-27
+
+### Added
+
+- Add live likes and bookmarks sync through `xurl`/`bird`, local search filters, archive import support, and dedicated Likes/Bookmarks web views.
+- Add Git-friendly JSONL backup sync, export, import, validation, and stale-aware auto-sync for rebuilding or merging the local SQLite store from text shards across machines.
+- Add a scheduled bookmark sync job with launchd installation, JSONL audit logging, overlap locking, and automatic Git backup sync after each refresh.
+- Add launchd env-file support so scheduled bookmark sync can source `bird` credentials without storing secrets in the plist.
+
+### Changed
+
+- Update the README tagline and package description for local X memory across archives, DMs, likes, bookmarks, and moderation.
+- Refresh dependencies, including `jsdom` 29.1.0.
+- Hide reply state and reply actions in saved likes/bookmarks web lanes.
+- Shard backup DMs by year and route unknown tweet dates to `data/tweets/unknown.jsonl` so Git backups stay compact and avoid bogus 1970 files.
+- Speed up archive imports plus JSONL backup export, import, and validation for large local datasets.
+
+### Fixed
+
+- Fix live bookmark sync to use stored X user ids, force OAuth2 for `xurl` collection reads, and tolerate large/current `bird` bookmark payloads.
+- Fix fresh-machine backup sync so demo data is never exported into Git backups, and keep no-op syncs from creating metadata-only commits.
+
+## 0.1.1 - 2026-04-27
+
+### Added
+
+- Add opt-in low-quality timeline filtering for year-scale tweet review, including date windows, originals-only mode, and CLI/API flags for hiding retweets, tiny replies, and link-only noise.
+
+### Fixed
+
+- Fix fresh npm installs so the packaged `birdclaw` binary includes its TypeScript runtime dependency.
+
 ## 0.1.0 - 2026-04-27
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
-# birdclaw
+# birdclaw 🪶 — Local X memory in SQLite: archives, DMs, likes, bookmarks
 
-`birdclaw` is a local-first X workspace: archive import, cached live reads, focused triage, and reply flows in one local web app + CLI.
+`birdclaw` is a local-first X workspace: archive import, cached live reads, focused triage, and reply flows in one local web app + CLI. Built by [@steipete](https://github.com/steipete/).
 
 Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and rough edges while the core settles.
 
@@ -21,6 +21,9 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 - FTS5 search over tweets and DMs
 - archive autodiscovery on macOS
 - archive import for tweets, likes, profiles, and full DMs
+- archive import for bookmark exports when present
+- live likes and bookmarks sync through `xurl` or `bird`
+- Git-friendly text backups with yearly tweet shards and per-conversation DM shards
 - profile hydration from live X metadata
 - local avatar cache
 - local media cache root under `~/.birdclaw`
@@ -29,6 +32,7 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 
 - `Home` timeline
 - `Mentions` queue
+- `Likes` and `Bookmarks` review lanes
 - `DMs` workspace with two-column layout
 - `Inbox` for mixed mention + DM triage
 - `Blocks` for local blocklist maintenance
@@ -44,6 +48,7 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 - AI-ranked inbox for mentions + DMs
 - OpenAI scoring hook for low-signal filtering
 - cached live mentions export in `xurl`-compatible JSON
+- liked/bookmarked tweet filters for archive and live-synced collections
 - live profile-reply inspection for borderline AI/slop triage
 - one-shot blocklist import from a file for batch moderation passes
 
@@ -79,6 +84,7 @@ If you need polished product-grade sync parity today, this is not there yet.
 
 - `Home`: read and reply without fighting the main X timeline
 - `Mentions`: work the reply queue with clean filters
+- `Likes` / `Bookmarks`: revisit saved posts from archive or live sync
 - `DMs`: triage by sender context, follower count, and influence
 - `Inbox`: let heuristics / OpenAI float likely-important items
 - `Blocks`: maintain a local-first account-scoped blocklist
@@ -110,6 +116,7 @@ export BIRDCLAW_HOME=/path/to/custom/root
 - `pnpm`
 - macOS recommended for Spotlight archive discovery
 - `xurl` optional for live reads / writes
+- `bird` optional for cookie-backed likes, bookmarks, mentions, DMs, and write fallback
 - OpenAI API key optional for inbox scoring
 
 ## Install
@@ -158,6 +165,18 @@ birdclaw import archive ~/Downloads/twitter-archive-2025.zip --json
 birdclaw import hydrate-profiles --json
 ```
 
+Back up the local SQLite store as canonical JSONL text:
+
+```bash
+birdclaw backup sync --repo ~/Projects/backup-birdclaw --remote https://github.com/steipete/backup-birdclaw.git --json
+```
+
+Merge the backup into the current `BIRDCLAW_HOME`:
+
+```bash
+birdclaw backup import ~/Projects/backup-birdclaw --json
+```
+
 Start the app:
 
 ```bash
@@ -179,6 +198,19 @@ pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
 ```bash
 pnpm cli search tweets "local-first" --json
 pnpm cli search tweets "sync engine" --limit 20 --json
+pnpm cli search tweets --since 2020-01-01 --until 2021-01-01 --originals-only --hide-low-quality --limit 500 --json
+pnpm cli search tweets --liked --limit 20 --json
+pnpm cli search tweets --bookmarked --limit 20 --json
+```
+
+### Sync likes and bookmarks
+
+`auto` tries `xurl` first, then falls back to `bird`. Use `bird` directly when the API path is unavailable for the account/token you have locally.
+
+```bash
+pnpm cli sync likes --mode auto --limit 100 --refresh --json
+pnpm cli sync bookmarks --mode auto --limit 100 --refresh --json
+pnpm cli sync bookmarks --mode bird --all --max-pages 5 --limit 100 --refresh --json
 ```
 
 ### Export mentions for agents
@@ -204,13 +236,13 @@ Home config lives in `~/.birdclaw/config.json`. Example:
 
 ```json
 {
-  "actions": {
-    "transport": "auto"
-  },
-  "mentions": {
-    "dataSource": "bird",
-    "birdCommand": "/Users/steipete/Projects/bird/bird"
-  }
+	"actions": {
+		"transport": "auto"
+	},
+	"mentions": {
+		"dataSource": "bird",
+		"birdCommand": "/Users/steipete/Projects/bird/bird"
+	}
 }
 ```
 
@@ -225,6 +257,7 @@ Notes:
 - `actions.transport` accepts `auto`, `bird`, or `xurl`
 - `bird` mode uses your local `bird` CLI and caches its mentions output into birdclaw's canonical store
 - filters still work in `xurl` mode; filtered payloads are rebuilt from the local canonical store after sync
+- `sync likes` and `sync bookmarks` store live results in the same local timeline table, so `search tweets --liked` and `search tweets --bookmarked` work across archive and live data
 
 ### Search and triage DMs
 
@@ -323,6 +356,79 @@ pnpm cli compose reply tweet_004 "On it."
 pnpm cli compose dm dm_003 "Send it over."
 ```
 
+### Text Backup
+
+`birdclaw backup export` writes deterministic JSONL shards that can rebuild the local SQLite index without committing SQLite WAL/SHM files, FTS shadow tables, or transient live caches.
+
+Layout:
+
+```text
+manifest.json
+data/accounts.jsonl
+data/profiles.jsonl
+data/tweets/YYYY.jsonl
+data/tweets/unknown.jsonl
+data/collections/likes.jsonl
+data/collections/bookmarks.jsonl
+data/dms/conversations.jsonl
+data/dms/YYYY.jsonl
+data/moderation/blocks.jsonl
+data/moderation/mutes.jsonl
+```
+
+Tweets are sharded by year for human browsing and yearly analysis. Collection-only tweets whose real creation date is unknown go into `data/tweets/unknown.jsonl` instead of pretending they belong to 1970. DMs are sharded by year with `conversation_id` in each row; this keeps Git fast while preserving conversation membership. Likes and bookmarks are stored as collection edges in `data/collections` and mirrored into the timeline rows for current query compatibility.
+
+Use `backup sync` when the target is a private Git repo. It pulls first, merge-imports the remote backup into local SQLite, exports the local union back into text shards, commits, and pushes.
+
+```bash
+pnpm cli backup sync --repo ~/Projects/backup-birdclaw --remote https://github.com/steipete/backup-birdclaw.git --json
+pnpm cli backup validate ~/Projects/backup-birdclaw --json
+```
+
+Configure stale-aware backup reads in `~/.birdclaw/config.json`:
+
+```json
+{
+	"backup": {
+		"repoPath": "/Users/steipete/Projects/backup-birdclaw",
+		"remote": "https://github.com/steipete/backup-birdclaw.git",
+		"autoSync": true,
+		"staleAfterSeconds": 900
+	}
+}
+```
+
+Read paths such as CLI search, inbox, API status/query, and web startup pull + merge from Git only when the last backup check is stale. Data-changing commands run a full backup sync afterward when this config is enabled. Set `BIRDCLAW_BACKUP_AUTO_SYNC=0` to disable that behavior for one process.
+
+### Scheduled Bookmark Sync
+
+`birdclaw jobs sync-bookmarks` refreshes live bookmarks and appends one JSONL audit entry per run. Each entry includes host, timestamps, duration, before/after bookmark counts, source transport, fetched count, backup sync result, and any error.
+
+```bash
+birdclaw --json jobs sync-bookmarks --mode auto --limit 100 --max-pages 5 --refresh
+tail -n 5 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
+```
+
+After a successful bookmark refresh, the job runs the normal backup auto-sync path. If `~/.birdclaw/config.json` has `backup.autoSync` enabled, the changed local data is merged into the configured Git backup repo, committed, and pushed. The audit entry records that backup result so scheduled runs are inspectable later.
+
+On macOS, install the 3-hour LaunchAgent after choosing the Birdclaw executable path for that machine:
+
+```bash
+birdclaw --json jobs install-bookmarks-launchd --program /opt/homebrew/bin/birdclaw
+```
+
+If the machine uses `bird` with browser cookies that are not available to launchd, write an export-only env file with mode `0600` and install with `--env-file ~/.config/bird/env.sh`. Birdclaw sources that file inside the scheduled process without storing the secrets in the plist.
+
+The LaunchAgent writes `~/Library/LaunchAgents/com.steipete.birdclaw.bookmarks-sync.plist`, runs at load, then every 10,800 seconds. It writes the audit log to `~/.birdclaw/audit/bookmarks-sync.jsonl` and stdout/stderr to `~/.birdclaw/logs/bookmarks-sync.*.log`. A lock file prevents overlapping runs and records an `already-running` skip when needed. The default job fetches up to 5 pages every 3 hours; pass `--all` if you want every retrievable page each run.
+
+Useful checks:
+
+```bash
+launchctl print gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
+launchctl kickstart -k gui/$(id -u)/com.steipete.birdclaw.bookmarks-sync
+tail -n 1 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
+```
+
 ## Typical Workflow
 
 1. import your archive if you have one
@@ -340,8 +446,9 @@ pnpm cli compose dm dm_003 "Send it over."
 Current preference:
 
 - `xurl` first
+- `bird` fallback for surfaces where cookie-backed reads work better
 
-Without `xurl`, `birdclaw` still works in local/archive mode.
+Without `xurl` or `bird`, `birdclaw` still works in local/archive mode.
 
 Check transport:
 

package/bin/birdclaw.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const tsxCli = join(packageRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const require = createRequire(import.meta.url);
+const tsxCli = require.resolve("tsx/cli");
 const birdclawCli = join(packageRoot, "src", "cli.ts");
 
 const result = spawnSync(

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "birdclaw",
-	"version": "0.1.0",
-	"description": "Local-first X workspace for archives, DMs, mentions, and moderation",
+	"version": "0.2.0",
+	"description": "Local X memory in SQLite for archives, DMs, likes, bookmarks, and moderation",
 	"homepage": "https://github.com/steipete/birdclaw#readme",
 	"license": "MIT",
 	"repository": {
@@ -41,6 +41,7 @@
 		"test": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run",
 		"coverage": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run --coverage",
 		"e2e": "playwright test",
+		"typecheck": "tsgo --noEmit",
 		"format": "oxfmt --write src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
 		"format:check": "oxfmt --check src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
 		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
@@ -80,7 +81,7 @@
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
 		"@vitest/coverage-v8": "^4.1.5",
-		"jsdom": "^29.0.2",
+		"jsdom": "^29.1.0",
 		"oxfmt": "^0.46.0",
 		"oxlint": "^1.61.0",
 		"typescript": "^6.0.3",

package/src/cli.ts

@@ -8,6 +8,18 @@ import { Command } from "commander";
 import { registerModerationCommands } from "#/cli-moderation";
 import { findArchives } from "#/lib/archive-finder";
 import { importArchive } from "#/lib/archive-import";
+import {
+	exportBackup,
+	importBackup,
+	maybeAutoSyncBackup,
+	maybeAutoUpdateBackup,
+	syncBackup,
+	validateBackup,
+} from "#/lib/backup";
+import {
+	installBookmarkSyncLaunchAgent,
+	runBookmarkSyncJob,
+} from "#/lib/bookmark-sync-job";
 import { importBlocklist } from "#/lib/blocklist";
 import {
 	type ActionsTransport,
@@ -32,6 +44,10 @@ import {
 	listDmConversations,
 	listTimelineItems,
 } from "#/lib/queries";
+import {
+	syncTimelineCollection,
+	type TimelineCollectionMode,
+} from "#/lib/timeline-collections-live";
 
 const program = new Command();
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -53,6 +69,20 @@ function resolveActionOptions(options: { transport?: string }) {
 	};
 }
 
+async function autoUpdateBeforeRead() {
+	const result = await maybeAutoUpdateBackup();
+	if (!result.ok) {
+		console.error(`birdclaw backup auto-sync failed: ${result.error}`);
+	}
+}
+
+async function autoSyncAfterWrite() {
+	const result = await maybeAutoSyncBackup();
+	if (!result.ok) {
+		console.error(`birdclaw backup sync failed: ${result.error}`);
+	}
+}
+
 program
 	.name("birdclaw")
 	.description("Local-first X workspace")
@@ -115,6 +145,7 @@ importCommand
 		}
 
 		const result = await importArchive(resolvedArchivePath);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -123,6 +154,7 @@ importCommand
 	.description("Backfill archive-imported profiles from live X metadata")
 	.action(async () => {
 		const result = await hydrateProfilesFromX();
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -131,12 +163,19 @@ const searchCommand = program
 	.description("Search local data");
 
 searchCommand
-	.command("tweets <query>")
+	.command("tweets [query]")
 	.option("--resource <resource>", "home or mentions", "home")
 	.option("--replied", "Only replied items")
 	.option("--unreplied", "Only unreplied items")
+	.option("--since <date>", "Include tweets created at or after this date")
+	.option("--until <date>", "Include tweets created before this date")
+	.option("--originals-only", "Exclude authored replies that start with @")
+	.option("--hide-low-quality", "Hide RTs, tiny replies, and link-only noise")
+	.option("--liked", "Only liked tweets")
+	.option("--bookmarked", "Only bookmarked tweets")
 	.option("--limit <n>", "Limit results", "20")
-	.action((query, options) => {
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -146,6 +185,12 @@ searchCommand
 			resource: options.resource === "mentions" ? "mentions" : "home",
 			search: query,
 			replyFilter,
+			since: options.since,
+			until: options.until,
+			includeReplies: !options.originalsOnly,
+			qualityFilter: options.hideLowQuality ? "summary" : "all",
+			likedOnly: Boolean(options.liked),
+			bookmarkedOnly: Boolean(options.bookmarked),
 			limit: Number(options.limit),
 		});
 		print(items, program.opts().json ?? false);
@@ -162,7 +207,8 @@ searchCommand
 	.option("--replied", "Only replied threads")
 	.option("--unreplied", "Only unreplied threads")
 	.option("--limit <n>", "Limit results", "20")
-	.action((query, options) => {
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -210,6 +256,7 @@ mentionsCommand
 	)
 	.option("--limit <n>", "Limit results", "20")
 	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -228,6 +275,7 @@ mentionsCommand
 				refresh: Boolean(options.refresh),
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
 			print(payload, true);
 			return;
 		}
@@ -242,6 +290,7 @@ mentionsCommand
 				refresh: Boolean(options.refresh),
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
 			print(payload, true);
 			return;
 		}
@@ -272,6 +321,108 @@ profilesCommand
 
 const dmsCommand = program.command("dms").description("Direct messages");
 
+const syncCommand = program
+	.command("sync")
+	.description("Refresh live X collections into the local store");
+
+for (const kind of ["likes", "bookmarks"] as const) {
+	syncCommand
+		.command(kind)
+		.description(`Refresh live ${kind} through xurl or bird`)
+		.option("--account <accountId>", "Account id")
+		.option("--mode <mode>", "auto, xurl, or bird", "auto")
+		.option("--limit <n>", "Per-page/result limit", "20")
+		.option("--all", "Fetch every retrievable page")
+		.option("--max-pages <n>", "Stop after N pages when using --all")
+		.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+		.option("--refresh", "Bypass live-cache freshness window")
+		.action(async (options) => {
+			const result = await syncTimelineCollection({
+				kind,
+				account: options.account,
+				mode: options.mode as TimelineCollectionMode,
+				limit: Number(options.limit),
+				all: Boolean(options.all) || options.maxPages !== undefined,
+				maxPages: options.maxPages ? Number(options.maxPages) : undefined,
+				refresh: Boolean(options.refresh),
+				cacheTtlMs: Number(options.cacheTtl) * 1000,
+			});
+			await autoSyncAfterWrite();
+			print(result, true);
+		});
+}
+
+const jobsCommand = program
+	.command("jobs")
+	.description("Run and install background Birdclaw jobs");
+
+jobsCommand
+	.command("sync-bookmarks")
+	.description("Refresh live bookmarks and append a JSONL audit entry")
+	.option("--account <accountId>", "Account id")
+	.option("--mode <mode>", "auto, xurl, or bird", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--all", "Fetch every retrievable page")
+	.option("--max-pages <n>", "Stop after N pages", "5")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--refresh", "Bypass live-cache freshness window")
+	.option("--log <path>", "Audit JSONL path")
+	.action(async (options) => {
+		const result = await runBookmarkSyncJob({
+			account: options.account,
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			all: Boolean(options.all) || options.maxPages !== undefined,
+			maxPages: options.all ? undefined : Number(options.maxPages),
+			refresh: Boolean(options.refresh),
+			cacheTtlMs: Number(options.cacheTtl) * 1000,
+			logPath: options.log,
+		});
+		print(result, true);
+		if (!result.ok) {
+			process.exitCode = 1;
+		}
+	});
+
+jobsCommand
+	.command("install-bookmarks-launchd")
+	.description("Install a LaunchAgent that runs bookmark sync every 3 hours")
+	.option("--label <label>", "LaunchAgent label")
+	.option("--interval-seconds <seconds>", "Launch interval", "10800")
+	.option("--program <path>", "birdclaw executable or command", "birdclaw")
+	.option("--mode <mode>", "auto, xurl, or bird", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--all", "Fetch every retrievable page")
+	.option("--max-pages <n>", "Stop after N pages", "5")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--no-refresh", "Allow live-cache reuse")
+	.option("--log <path>", "Audit JSONL path")
+	.option("--env-file <path>", "Shell env file to source before running")
+	.option("--stdout <path>", "launchd stdout path")
+	.option("--stderr <path>", "launchd stderr path")
+	.option("--launch-agents-dir <path>", "LaunchAgents directory")
+	.option("--no-load", "Write plist without loading it")
+	.action(async (options) => {
+		const result = await installBookmarkSyncLaunchAgent({
+			label: options.label,
+			intervalSeconds: Number(options.intervalSeconds),
+			program: options.program,
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			all: Boolean(options.all) || options.maxPages !== undefined,
+			maxPages: options.all ? undefined : Number(options.maxPages),
+			refresh: options.refresh,
+			cacheTtlSeconds: Number(options.cacheTtl),
+			logPath: options.log,
+			envFile: options.envFile,
+			stdoutPath: options.stdout,
+			stderrPath: options.stderr,
+			launchAgentsDir: options.launchAgentsDir,
+			load: options.load,
+		});
+		print(result, true);
+	});
+
 dmsCommand
 	.command("list")
 	.option("--account <accountId>", "Account id")
@@ -299,6 +450,9 @@ dmsCommand
 				refresh: true,
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
+		} else {
+			await autoUpdateBeforeRead();
 		}
 		const items = listDmConversations({
 			account: options.account,
@@ -336,6 +490,7 @@ dmsCommand
 			refresh: Boolean(options.refresh),
 			cacheTtlMs: Number(options.cacheTtl) * 1000,
 		});
+		await autoSyncAfterWrite();
 		print(result, true);
 	});
 
@@ -356,6 +511,7 @@ composeCommand
 	.option("--account <accountId>", "Account id", "acct_primary")
 	.action(async (text, options) => {
 		const result = await createPost(options.account, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -364,6 +520,7 @@ composeCommand
 	.option("--account <accountId>", "Account id", "acct_primary")
 	.action(async (tweetId, text, options) => {
 		const result = await createTweetReply(options.account, tweetId, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -372,6 +529,7 @@ composeCommand
 	.description("Reply inside an existing DM conversation")
 	.action(async (conversationId, text) => {
 		const result = await createDmReply(conversationId, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -383,6 +541,7 @@ program
 	.option("--score", "Score top items with OpenAI before listing")
 	.option("--limit <n>", "Limit results", "20")
 	.action(async (options) => {
+		await autoUpdateBeforeRead();
 		const kind =
 			options.kind === "mentions" || options.kind === "dms"
 				? options.kind
@@ -392,6 +551,7 @@ program
 				kind,
 				limit: Number(options.limit),
 			});
+			await autoSyncAfterWrite();
 		}
 		print(
 			listInboxItems({
@@ -408,6 +568,7 @@ program
 	.command("db stats")
 	.description("Show local storage and dataset stats")
 	.action(async () => {
+		await autoUpdateBeforeRead();
 		const meta = await getQueryEnvelope();
 		const paths = getBirdclawPaths();
 		print(
@@ -420,10 +581,82 @@ program
 		);
 	});
 
+const backupCommand = program
+	.command("backup")
+	.description("Export, import, and validate Git-friendly text backups");
+
+backupCommand
+	.command("export")
+	.description("Export canonical JSONL backup shards")
+	.requiredOption("--repo <path>", "Backup repository/path")
+	.option("--commit", "Create a git commit in the backup repo")
+	.option("--push", "Push the backup repo after committing")
+	.option(
+		"--message <message>",
+		"Git commit message",
+		"archive: update birdclaw backup",
+	)
+	.option("--no-validate", "Skip post-export validation")
+	.action(async (options) => {
+		const result = await exportBackup({
+			repoPath: options.repo,
+			commit: Boolean(options.commit) || Boolean(options.push),
+			push: Boolean(options.push),
+			message: options.message,
+			validate: options.validate,
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("import <repo>")
+	.description("Merge a canonical JSONL backup into the local SQLite store")
+	.option("--no-validate", "Skip backup validation before import")
+	.option("--replace", "Replace local portable tables instead of merging")
+	.action(async (repo, options) => {
+		const result = await importBackup({
+			repoPath: repo,
+			validate: options.validate,
+			mode: options.replace ? "replace" : "merge",
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("sync")
+	.description("Pull, merge-import, export, commit, and push a backup repo")
+	.requiredOption("--repo <path>", "Backup repository/path")
+	.option("--remote <url>", "Git remote to clone/configure")
+	.option(
+		"--message <message>",
+		"Git commit message",
+		"archive: sync birdclaw backup",
+	)
+	.action(async (options) => {
+		const result = await syncBackup({
+			repoPath: options.repo,
+			remote: options.remote,
+			message: options.message,
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("validate <repo>")
+	.description("Validate backup manifest, shard hashes, and JSONL rows")
+	.action(async (repo) => {
+		const result = await validateBackup(repo);
+		print(result, true);
+		if (!result.ok) {
+			process.exitCode = 1;
+		}
+	});
+
 program
 	.command("serve")
 	.description("Run the local web app")
-	.action(() => {
+	.action(async () => {
+		await autoUpdateBeforeRead();
 		const child = spawn(
 			process.execPath,
 			["node_modules/vite/bin/vite.js", "dev", "--port", "3000"],

package/src/components/AppNav.tsx

@@ -14,6 +14,8 @@ const links = [
 	{ to: "/inbox", label: "Inbox" },
 	{ to: "/", label: "Home" },
 	{ to: "/mentions", label: "Mentions" },
+	{ to: "/likes", label: "Likes" },
+	{ to: "/bookmarks", label: "Bookmarks" },
 	{ to: "/dms", label: "DMs" },
 	{ to: "/blocks", label: "Blocks" },
 ] as const;