Document initial local maintainer-archive workflows

[joshka]

Parent: #100

Related Gitcrawl context: openclaw/gitcrawl#81

Observed Workflow

Initial Discrawl use showed that many needed pieces already exist, but the useful workflow is spread across command knowledge, repo docs, and local helper scripts.

The practical maintainer-archive workflow included:

• checking discrawl status --json
• running discrawl doctor
• using discrawl sync --source wiretap when bot access was unavailable
• using discrawl wiretap --watch-every while browsing Discord Desktop
• using read-only discrawl sql for exact counts
• using numeric channel ids for repeatable queries
• using discrawl sync --source discord before privacy-sensitive publish checks
• understanding that wiretap DMs and @me rows stay local-only
• confirming stopped state with process checks when a background importer had been running

Current Workaround

The working knowledge exists, but it had to be assembled from separate pages, previous sessions, local skills, and ad hoc notes.

Request

Add a maintainer-archive workflow guide focused on real local use.

Suggested sections:

• "Use the local archive first, then live Discord only when needed"
• "No-bot path with sync --source wiretap"
• "Manual browsing plus wiretap --watch-every"
• "Checking freshness and coverage"
• "Using read-only SQL safely"
• "Stable channel ids for repeatable agent queries"
• "Bot metadata vs wiretap cache data"
• "Public/private publish preflight"
• "Stopping background importers and checking DB health"

Why This Matters

This is the same broad workflow as the Gitcrawl maintainer-archive work: local archive first, Codex queries the archive as needed, and live services are used only when current state or permissions require it. Discrawl already has many of the primitives; a workflow guide would reduce repeated setup friction.

Acceptance Criteria

• The guide links to existing command docs rather than duplicating all reference material.
• It includes concrete command sequences.
• It clearly distinguishes bot sync, wiretap cache import, Git snapshot reader mode, and cloud remote mode.
• It explains the privacy boundary for local-only DMs.
• It recommends numeric channel ids for repeatable workflows.
• It points to diagnostics for freshness, coverage, process/lock state, and publish-scope readiness as those features exist.

---

Prepared with Codex, confirmed as accurate by human.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 23, 2026, 10:39 AM ET / 14:39 UTC.

Summary
Keep open: current main and the latest release do not contain the requested maintainer-archive workflow guide, and #107 is the active open implementation path.

Reproducibility: not applicable. this is a documentation request rather than a bug report. Current-main inspection confirms the requested guide is absent while the underlying command docs exist separately.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Do not queue a new automated fix PR because #107 already implements the requested guide.

Review details

Best possible solution:

Merge the open docs PR if it remains acceptable, or intentionally replace it with another guide PR; close this issue only after the guide lands on main.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a documentation request rather than a bug report. Current-main inspection confirms the requested guide is absent while the underlying command docs exist separately.

Is this the best way to solve the issue?

Yes; adding a guide that links to existing command references is the narrowest maintainable solution, and the open PR follows that shape.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• Closing this issue before Document maintainer archive workflows #107 merges would drop an active, directly matching documentation path.

Codex review notes: model internal, reasoning high; reviewed against 670994a45f61.

Label changes

Label changes:

• add P3: This is a low-risk documentation workflow request rather than a runtime defect.
• add impact:other: The maintainer-visible impact is repeated setup friction from scattered local archive workflow documentation.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk documentation workflow request rather than a runtime defect.
• impact:other: The maintainer-visible impact is repeated setup friction from scattered local archive workflow documentation.

Evidence reviewed

What I checked:

• Requested guide absent on current main: Current main lists the existing guides as sync sources, wiretap internals, search modes, embeddings, Git snapshots, and data layout; there is no maintainer archive workflow guide under docs/guides. (docs/README.md:42, 670994a45f61)
• Guide absent from latest release: The latest release tag v0.11.3 points at 6a91d9c, and no maintainer/archive-workflows guide path exists there. (6a91d9cc67bb)
• Open implementation candidate: Document maintainer archive workflows #107 is open, mergeable, and adds docs/guides/maintainer-archive-workflows.md plus a docs/README.md guide-list update. (docs/guides/maintainer-archive-workflows.md:1, 893e4a55495a)
• Existing primitives are currently scattered: Current docs already document sync sources and wiretap/local-only DM behavior separately, which matches the issue's premise that the commands exist but the workflow guide is missing. (docs/guides/sync-sources.md:3, 670994a45f61)
• Docs-area history: Blame on the relevant docs guide/index pages in the visible current-main history points to Vincent Koc's docs refresh at 6a91d9c. (docs/guides/sync-sources.md:1, 6a91d9cc67bb)

Likely related people:

• vincentkoc: Visible current-main blame and history for the relevant docs landing and guide files point to the latest docs refresh. (role: recent docs-area contributor; confidence: medium; commits: 6a91d9cc67bb; files: docs/README.md, docs/guides/sync-sources.md, docs/commands/wiretap.md)
• joshka: The open linked PR adds the requested maintainer archive workflow guide and docs landing-page link. (role: current implementation candidate author; confidence: medium; commits: 893e4a55495a; files: docs/guides/maintainer-archive-workflows.md, docs/README.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

🦞🔧
ClawSweeper is automatically building this issue.

The issue review finished and no active implementation pull request was found.

Automatic implementation progress:

• State: Queued
• Detail: Review complete; no active implementation PR was found. The Codex implementation worker is queued.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27887913069
• Updated: 2026-06-21T00:04:15.989Z
• Opt out: add clawsweeper:manual-only or clawsweeper:human-review.

[steipete]

Resolved by #107 and merged as 53f417b, with contributor credit preserved for @joshka.

The guide now covers the current local-first workflow: bot, wiretap, Git snapshot, and cloud remote modes; status, diagnostics, coverage, and failures; stable channel ids and read-only SQL; watched wiretap imports; exact writer-lock state; and fail-closed privacy-sensitive publish --check preflight.

Proof: docs site build passed, markdown lint reported 0 guide errors, the full Go suite passed, an exact-built disposable synthetic archive exercised the documented local sequence and fail-closed preflight, final autoreview found no actionable defects, and all 9 exact-head PR checks passed.