Document maintainer archive workflows

[joshka]

Summary

• add a maintainer archive workflow guide for local-first Discrawl use
• document wiretap/no-bot flows, freshness checks, read-only SQL, stable channel ids, publish preflight, and importer stop checks
• link the new guide from the docs landing page

Validation

• markdownlint-cli2 --config ~/.markdownlint-cli2.yaml docs/guides/maintainer-archive-workflows.md
• node scripts/build-docs-site.mjs

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 21, 2026, 3:30 PM ET / 19:30 UTC.

Summary
Adds docs/guides/maintainer-archive-workflows.md and updates the docs landing page guide summary to mention maintainer archive workflows.

Reproducibility: not applicable. this is a documentation PR, not a bug report. The review path is source and docs inspection of the added guide, linked command docs, and paired issue.

Review metrics: 1 noteworthy metric.

• Docs-only scope: 2 files changed; 199 added, 1 deleted. The patch is limited to documentation and does not touch runtime, workflow, dependency, or release surfaces.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #106
Summary: This PR is the implementation candidate for the paired maintainer archive workflow documentation issue; nearby workflow issues remain separate follow-ups.

Members:

• canonical: Document initial local maintainer-archive workflows #106 - The issue requests the same maintainer-archive workflow guide and section set that this PR adds.
• partial_overlap: Track initial local Discord maintainer-archive use friction #100 - The parent issue tracks broader local maintainer-archive friction; this PR addresses only the documentation portion.
• partial_overlap: Add archive coverage and wiretap progress reporting #101 - The new guide documents current coverage checks with SQL, while the issue asks for first-class coverage and wiretap progress reporting.
• partial_overlap: Add process and SQLite lock diagnostics #102 - The guide documents current process checks, while the issue asks for new process, lock, and integrity diagnostics.
• partial_overlap: Add source provenance and publish-scope preflight checks #103 - The guide documents publish preflight practice, while the issue asks for new source-provenance and publish-scope diagnostic commands.
• 1 more in the report.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Next step before merge

• No repair lane is needed because the PR has no concrete review finding; normal maintainer review and merge checks are sufficient.

Security
Cleared: The diff is docs-only and does not change code execution, dependencies, workflows, secrets handling, permissions, or supply-chain surfaces.

Review details

Best possible solution:

Land the guide if maintainers accept the wording, while keeping the separate diagnostic, provenance, and channel-resolution feature issues open.

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

Not applicable: this is a documentation PR, not a bug report. The review path is source and docs inspection of the added guide, linked command docs, and paired issue.

Is this the best way to solve the issue?

Yes. For the paired docs request, adding one guide that links existing command pages and gives concrete command sequences is the narrow maintainable solution.

AGENTS.md: not found in the target repository.

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

Label changes

Label changes:

• add P3: This is a low-risk documentation improvement for maintainer workflow ergonomics, not an urgent runtime regression.

Label justifications:

• P3: This is a low-risk documentation improvement for maintainer workflow ergonomics, not an urgent runtime regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• PR diff scope: The PR adds one new guide and changes one docs landing-page line, with 199 insertions and 1 deletion and no runtime, workflow, dependency, or generated files touched. (docs/guides/maintainer-archive-workflows.md:1, 893e4a55495a)
• Guide content matches request: The added guide covers local-first archive use, health/freshness checks, wiretap/no-bot flow, read-only SQL, stable channel ids, bot metadata vs cache data, publish preflight, and stopped-importer checks. (docs/guides/maintainer-archive-workflows.md:3, 893e4a55495a)
• Current main lacks equivalent guide: Searching current main for maintainer-archive/local-first guide terms found no existing equivalent documentation, so this PR is not redundant on main. (a82cacd73b26)
• Docs-site discoverability: The docs-site builder includes all Markdown files under docs/guides, so the new guide will be part of the generated Guides navigation. (scripts/build-docs-site.mjs:14, a82cacd73b26)
• Command-doc source backing: Existing command docs back the guide's claims about wiretap source selection, watch mode, read-only SQL, status metadata, and public-only publish filtering. (docs/commands/wiretap.md:7, a82cacd73b26)
• Canonical paired issue: The open paired issue requests a maintainer-archive workflow guide with the same core sections and acceptance criteria this PR adds.

Likely related people:

• steipete: Local blame attributes the current docs landing page and command docs to the release commit, and history shows the generated docs site was introduced in earlier docs work. (role: docs-site introducer and recent docs owner; confidence: high; commits: 4f15765afb72, cc1247bfc6b1; files: docs/README.md, scripts/build-docs-site.mjs, docs/commands/wiretap.md)
• joshka: GitHub commit metadata and git show link this contributor to prior merged docs navigation and docs-site work before this PR. (role: recent docs contributor; confidence: medium; commits: 2407489af770; files: docs/README.md, scripts/build-docs-site.mjs)
• vincentkoc: History links this contributor to desktop wiretap import, crawlkit archive docs, and Cloudflare remote archive mode, all of which the new guide references. (role: adjacent archive workflow contributor; confidence: medium; commits: 0a247939e841, f32dae98cc1f, dcf0c9c8dbb3; files: internal/discorddesktop/import.go, docs/guides/git-snapshots.md, docs/commands/remote.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.