Expose the changelog in the docs site

[joshka]

Summary

• add docs/CHANGELOG.md as a symlink to the root changelog
• include the changelog in the docs site Start navigation
• mention release history from the docs home page section list
• add root CHANGELOG.md to the Pages workflow path filter so changelog-only edits rebuild the published docs site

Rationale

Finding the changelog from the documentation site currently takes multiple steps for a user. The release history is useful when someone wants to understand what changed, whether their installed version has a feature, or how recent behavior differs from older releases.

This makes the changelog a first-class docs page without duplicating the source file, so the site stays easy to navigate while the root CHANGELOG.md remains the canonical source. Since the generated site now depends on the root changelog, the Pages workflow also needs to watch CHANGELOG.md; otherwise release-note-only updates could leave the published docs stale.

Validation

• node scripts/build-docs-site.mjs
• git diff --check -- .github/workflows/pages.yml docs/CHANGELOG.md docs/README.md scripts/build-docs-site.mjs
• opened http://127.0.0.1:4173/CHANGELOG.html in the in-app browser

Terminal proof from the generated site:

built docs site: dist/docs-site

--- rendered file proof ---
6:  <title>Changelog - Discrawl</title>
219:      <nav><section><h2>start</h2><a class="nav-link" href="index.html">Discrawl</a><a class="nav-link" href="install.html">Install</a><a class="nav-link" href="configuration.html">Configuration</a><a class="nav-link" href="bot-setup.html">Discord bot setup</a><a class="nav-link" href="security.html">Security</a><a class="nav-link active" href="CHANGELOG.html">Changelog</a><a class="nav-link" href="contact.html">Contact</a></section>
237:        <article class="doc"><h1 id="changelog">Changelog</h1>

--- home proof ---
219:      <nav><section><h2>start</h2><a class="nav-link active" href="index.html">Discrawl</a><a class="nav-link" href="install.html">Install</a><a class="nav-link" href="configuration.html">Configuration</a><a class="nav-link" href="bot-setup.html">Discord bot setup</a><a class="nav-link" href="security.html">Security</a><a class="nav-link" href="CHANGELOG.html">Changelog</a><a class="nav-link" href="contact.html">Contact</a></section>
280:<li><strong><a href="install.html">Start</a></strong> - install, configure, set up the Discord bot, security notes, release history, contact</li>

Rendered-page proof from the in-app browser:

{
  "activeHref": "CHANGELOG.html",
  "activeNav": "Changelog",
  "firstChangelogItem": "Keep incremental share imports compatible with crawlkit's safe changed-tail replacement plan instead of falling back to a full archive rebuild.",
  "heading": "Changelog",
  "startNav": [
    "Discrawl",
    "Install",
    "Configuration",
    "Discord bot setup",
    "Security",
    "Changelog",
    "Contact"
  ],
  "title": "Changelog - Discrawl",
  "url": "http://127.0.0.1:4173/CHANGELOG.html"
}

[clawsweeper]

Codex review: found issues before merge. Reviewed June 18, 2026, 6:10 PM ET / 22:10 UTC.

Summary
The PR exposes the root changelog as a docs-site page, links it in the Start navigation/home copy, and updates the Pages workflow path filter for changelog-only rebuilds.

Reproducibility: yes. for the remaining review concern: source inspection shows layout() builds edit URLs from repoEditBase and page.rel, while the PR adds CHANGELOG.md as a docs-relative symlink page. The primary changelog page rendering is directly shown by the PR body output and inspected screenshot.

Review metrics: 2 noteworthy metrics.

• Changed surface: 4 files changed, 4 insertions, 2 deletions. The diff is narrow but includes a workflow trigger and generated docs navigation source.
• Pages trigger coverage: 1 path added. The generated docs site would depend on the root changelog after this PR, so the Pages workflow must watch that file.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
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:

• Point the generated changelog page's edit link at the root CHANGELOG.md or hide that edit affordance.

Risk before merge

• [P1] The generated changelog page still inherits the standard docs edit URL, so the visible edit affordance points at the docs symlink path instead of the canonical root changelog unless maintainers accept or adjust that behavior.

Maintainer options:

1. Decide the mitigation before merge
   Land the changelog page and Pages trigger while keeping generated-page affordances aligned with the canonical root changelog.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] The remaining action is a maintainer choice on whether the minor edit-link affordance should be fixed before merge.

Security
Cleared: The diff changes docs navigation, a symlink, and a Pages path filter only; it does not broaden permissions, change action refs, add dependencies, or touch secrets handling.

Review findings

• [P3] Point the changelog edit link at the root file — scripts/build-docs-site.mjs:13

Review details

Best possible solution:

Land the changelog page and Pages trigger while keeping generated-page affordances aligned with the canonical root changelog.

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

Yes for the remaining review concern: source inspection shows layout() builds edit URLs from repoEditBase and page.rel, while the PR adds CHANGELOG.md as a docs-relative symlink page. The primary changelog page rendering is directly shown by the PR body output and inspected screenshot.

Is this the best way to solve the issue?

Mostly yes: the symlink, navigation entry, and Pages path filter are a narrow maintainable way to expose the changelog. The remaining question is whether the generated edit link should special-case the root changelog or be left as an edit to the symlink path.

Full review comments:

• [P3] Point the changelog edit link at the root file — scripts/build-docs-site.mjs:13
  Adding CHANGELOG.md to the docs section makes the generated page use the standard docs edit URL, so the visible edit button targets docs/CHANGELOG.md rather than the canonical root CHANGELOG.md. Please special-case the changelog edit URL or hide that edit affordance for this page.
  Confidence: 0.78

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: not found in the target repository.

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

Label changes

Label changes:

• remove merge-risk: 🚨 automation: Current PR review selected no merge-risk labels.

Label justifications:

• P3: This is a low-risk docs discoverability PR with no runtime product behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes copied build/rendered-page output, and the inspected screenshot shows the generated changelog page with active navigation and rendered entries.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied build/rendered-page output, and the inspected screenshot shows the generated changelog page with active navigation and rendered entries.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes copied build/rendered-page output, and the inspected screenshot shows the generated changelog page with active navigation and rendered entries.

Evidence reviewed

What I checked:

• Current main omits changelog docs navigation: Current main's Start section lists README, install, configuration, bot setup, security, and contact, with no changelog page in generated docs navigation. (scripts/build-docs-site.mjs:13, 7ba9fa595787)
• Current main Pages trigger omits root changelog: Current main's Pages workflow watches docs, the docs builder script, and the workflow file, but not root CHANGELOG.md. (.github/workflows/pages.yml:8, 7ba9fa595787)
• PR adds the intended docs surface: The PR adds CHANGELOG.md to the Start section, creates docs/CHANGELOG.md as a symlink to ../CHANGELOG.md, updates docs README copy, and adds root CHANGELOG.md to the Pages path filter. (scripts/build-docs-site.mjs:13, 416ea796b427)
• Edit-link side effect: At PR head, layout() still builds edit URLs as repoEditBase plus page.rel, while standardHero() renders the visible edit link; the changelog page therefore links to docs/CHANGELOG.md instead of the canonical root CHANGELOG.md. (scripts/build-docs-site.mjs:299, 416ea796b427)
• Rendered proof inspected: Downloaded and inspected the contributor screenshot; it shows the Changelog heading, active Changelog sidebar item, rendered changelog entries, and visible github/edit affordances. (416ea796b427)
• History owner: The docs-site builder, Pages workflow, docs README, and root changelog were introduced together in v0.11.0 by commit 37a9338. (scripts/build-docs-site.mjs:13, 37a9338fdcdb)

Likely related people:

• steipete: Git blame, path history, and GitHub commit metadata tie the generated docs site, Pages workflow, docs README, and root changelog to the v0.11.0 release commit. (role: docs site and Pages workflow history; confidence: high; commits: 37a9338fdcdb; files: scripts/build-docs-site.mjs, .github/workflows/pages.yml, docs/README.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.

[joshka]

Rendered changelog docs page proof:

Rendered changelog docs page

tmp-pr93-changelog-screenshot.png

[steipete]

Validated the generated docs site: the changelog page builds, appears in Start navigation, and is linked from the home page. git diff --check and autoreview pass; required CI and security checks are green.

[steipete]

Landed as 2407489af7708cd7cb2aab801e691dc211206124; contributor credit added in 2711628.

Proof: generated docs site contains CHANGELOG.html, active Start navigation, home-page link, and the follow-up Unreleased entry; git diff --check and autoreview passed; all PR CI and security checks were green. Thanks @joshka.