From f32dae98cc1f459ecc90150fe77c6bb25b7b8ad1 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Tue, 5 May 2026 19:16:52 -0700
Subject: [PATCH] docs: document crawlkit archive surfaces

---
 CHANGELOG.md                 | 15 +++++++++++++++
 README.md                    |  8 ++++++++
 docs/README.md               |  5 +++++
 docs/guides/git-snapshots.md |  5 +++++
 4 files changed, 33 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9340a48..1b8b9d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 ## 0.7.0 - Unreleased
 
+### Changes
+
+- Document the crawlkit-backed config/status/control, snapshot, mirror,
+  sync-state, output, and shared TUI surfaces now used on `main`.
+- Clarify that Discord bot sync, desktop wiretap parsing, DM privacy filters,
+  schema ownership, FTS/ranking, embeddings, and analytics remain app-owned.
+- Align terminal browser docs with the gitcrawl-style shared TUI model:
+  channel/person/thread groups, message rows, detail/thread panes, sorting,
+  mouse selection, right-click actions, and local/remote status chrome.
+
+### Maintenance
+
+- Document the read-only `metadata --json`, `status --json`, and
+  `doctor --json` control surface for launchers, automation, and CI checks.
+
 ### Fixes
 
 - `wiretap` now uses a fast default path for Discord Chromium cache imports: it scans cheap context files plus route-bearing HTTP cache entries, checkpoints file progress in batches, and leaves exhaustive historical cache archaeology behind `--full-cache` / `desktop.full_cache`.
diff --git a/README.md b/README.md
index 85fae20..4a6c31e 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,8 @@ Wiretap DMs stay local and are never exported to the Git-backed snapshot mirror.
 - imports classifiable Discord Desktop cache messages with `wiretap`, including proven DMs under `@me`
 - publishes and imports private Git-backed archive snapshots for org-wide read access
 - browses stored messages and local DMs in a terminal archive UI
+- exposes `metadata --json`, `status --json`, and `doctor --json` for local
+  launchers, automation, and CI
 - supports Git-only read mode with no Discord credentials on reader machines
 - generates backup README activity reports, with optional AI-written field notes
 - exposes read-only SQL for ad hoc analysis
@@ -171,6 +173,12 @@ discrawl tui --dm
 discrawl --json tui --limit 50
 ```
 
+The terminal browser uses the shared crawlkit explorer. The left pane groups
+channels, people, or threads; the middle pane lists messages; the right pane
+shows the selected message, surrounding conversation, and thread detail. Mouse
+selection, right-click actions, sortable headers, and the local/remote footer
+follow the same interaction model as `gitcrawl tui`.
+
 ### `init`
 
 Creates the local config and discovers accessible guilds.
diff --git a/docs/README.md b/docs/README.md
index fb2ec9f..d860c7c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,7 @@ Mirror Discord guilds into local SQLite. Search server history without depending
 - **Just want to read a shared archive?** Use [`subscribe`](commands/subscribe.html) - no token needed.
 - **Need DM search?** [`wiretap`](commands/wiretap.html) imports local Discord Desktop cache.
 - **Want semantic search?** Configure [Embeddings](guides/embeddings.html), then run [`embed`](commands/embed.html).
+- **Wiring an agent or launcher?** `discrawl metadata --json`, `discrawl status --json`, and `discrawl doctor --json` expose the read-only crawlkit control surface.
 
 ## At a glance
 
@@ -30,6 +31,10 @@ discrawl search "panic: nil pointer"
 discrawl tail
 ```
 
+`discrawl tui` uses the shared crawlkit terminal explorer: channel/person/thread
+groups on the left, message rows in the middle, and readable message/thread
+detail on the right.
+
 ## Sections
 
 - **[Start](install.html)** - install, configure, set up the Discord bot, security notes, contact
diff --git a/docs/guides/git-snapshots.md b/docs/guides/git-snapshots.md
index 86a24df..255be20 100644
--- a/docs/guides/git-snapshots.md
+++ b/docs/guides/git-snapshots.md
@@ -2,6 +2,11 @@
 
 Discrawl can publish the SQLite archive as sharded, compressed NDJSON snapshots in a private Git repo, then auto-import that repo before local read commands. This gives readers org memory without Discord credentials.
 
+Snapshot packing/import and git mirror mechanics are shared through
+`crawlkit`. Discrawl still owns Discord-specific privacy policy: `@me` direct
+messages, wiretap sync state, and local-only desktop rows are excluded from
+published snapshots and are preserved locally on import.
+
 ## Publisher
 
 ```bash