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 28, 2026, 1:08 PM ET / 17:08 UTC.

Summary
The PR adds docs/guides/maintainer-archive-workflows.md and updates the docs landing page guide summary.

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 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 diagnostics, 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 670994a45f61.

Label changes

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 diff adds one guide and changes one docs landing-page line, with 199 insertions and 1 deletion across two docs files. (docs/guides/maintainer-archive-workflows.md:1, 893e4a55495a)
• Guide content matches the paired docs 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 desktop cache data, publish preflight, and stopped-importer checks. (docs/guides/maintainer-archive-workflows.md:3, 893e4a55495a)
• Docs landing page link: The PR updates the Guides summary on the docs landing page to mention maintainer archive workflows. (docs/README.md:42, 893e4a55495a)
• Docs site will include the new guide: The docs-site builder includes all Markdown files under docs/guides, so the new guide will be picked up by the generated Guides navigation. (scripts/build-docs-site.mjs:14, 670994a45f61)
• Not already implemented on current main: Current main has no docs/guides/maintainer-archive-workflows.md path, and its Guides summary still lists only the existing guide set. (docs/README.md:42, 670994a45f61)
• Not shipped in latest release: The latest release tag v0.11.3 also has no maintainer archive workflow guide path. (docs/guides/maintainer-archive-workflows.md, 6a91d9cc67bb)

Likely related people:

• steipete: History shows the generated docs site and much of the docs surface were introduced or maintained in commits attributed to Peter Steinberger. (role: docs-site introducer and docs-area owner signal; confidence: high; commits: 4f15765afb72, 758334ea487a; files: scripts/build-docs-site.mjs, docs/README.md, docs/guides/git-snapshots.md)
• joshka: This contributor has prior merged docs navigation/docs-site work before this PR, including exposing the changelog in the docs site. (role: recent docs contributor; confidence: medium; commits: 2407489af770, 4ee8d3dd2226; files: docs/README.md, scripts/build-docs-site.mjs, docs/guides/data-storage.md)
• vincentkoc: History links this contributor to desktop wiretap import, crawlkit archive docs, Cloudflare remote archive mode, and the current docs refresh that main blames for the landing-page guide list. (role: adjacent archive workflow contributor; confidence: medium; commits: 0a247939e841, f32dae98cc1f, dcf0c9c8dbb3; files: docs/guides/wiretap.md, 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.