fix: keep documentation identity stable across checkouts

[steipete]

What Problem This Solves

Building the docs in a renamed checkout wrote that directory's name into llms.txt as the product identity.

User Impact

The generated documentation index consistently identifies Discrawl and retains its canonical URLs.

Why This Change Was Made

Use the product's explicit name and test a complete build in a renamed fixture directory. Run the regression and a real docs build in CI, and require the regression before Pages builds. Also correct an outdated Windows-lock test explanation that incorrectly claimed locking was a no-op; existing test selection and assertions are retained.

Evidence

• Before: the new regression failed with # renamed-discrawl-... and the same incorrect description.
• After: node --test scripts/build-docs-site.test.mjs passed; a real node scripts/build-docs-site.mjs invocation from the docs worktree generated:

  built docs site: dist/docs-site
  # discrawl
  
  discrawl documentation index.
  

• Built the Go CLI from the committed head; version and metadata --json schema checks passed.
• Actionlint passed; isolated Codex autoreview is scoped-clean at P0–P2.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 12, 2026, 9:15 PM ET / September 13, 2026, 01:15 UTC.

ClawSweeper review

What this changes

The branch fixes Discrawl’s generated documentation identity, adds a renamed-directory regression and CI checks, records the fix, and corrects a Windows test-skip explanation.

Merge readiness

✅ Ready for maintainer review

This PR remains useful: current main and v0.15.0 still derive the documentation identity from the checkout directory. The focused correction has adequate real build evidence and no blocking findings.

Priority: P3
Reviewed head: 47e809bce4af2e7c253ac419a857c1c374e34302

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused fix with relevant real build output, regression coverage, and no blocking defects.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.
Evidence reviewed	7 items	Current main still contains the defect: The builder uses process.cwd() for its root and path.basename(root) for the llms.txt product name; its canonical site and repository URLs are already fixed Discrawl values. Latest release does not contain the fix: v0.15.0 falls back to path.basename(root); a full-file search found no productName declaration that would override that fallback. Introduced correction and regression coverage: The verified base-to-head diff replaces the directory-derived identity with discrawl. The regression invokes the actual builder in a temporary renamed directory and checks the generated identity, canonical URLs, and absence of the directory name.
Findings	None	None.
Security	None	None.

How this fits together

Discrawl’s documentation builder reads Markdown from a checkout and generates the static website and an index for AI readers. GitHub Pages publishes those generated files.

flowchart LR
  A[Checkout documentation] --> B[Documentation builder]
  C[Fixed product identity and URLs] --> B
  B --> D[Website and AI documentation index]
  D --> E[GitHub Pages]
  F[Renamed-directory regression] --> B

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep the documentation identity explicit alongside the canonical URLs and retain the renamed-directory regression.

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

Yes, source establishes that building current main from a differently named checkout writes that directory name into llms.txt. This read-only review did not execute the builder.

Is this the best way to solve the issue?

Yes, an explicit product name matches the existing fixed branding and URLs without introducing configuration or another identity source.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 6169f2125e3d.

Labels

Label changes:

• add P3: This corrects generated documentation metadata without changing Discrawl’s archive or runtime behavior.
• add proof: sufficient: Contributor real behavior proof is sufficient. The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.

Label justifications:

• P3: This corrects generated documentation metadata without changing Discrawl’s archive or runtime behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.
• proof: sufficient: Contributor real behavior proof is sufficient. The supplied body shows the actual documentation builder run from a worktree named docs producing the corrected discrawl identity; the renamed-directory regression additionally verifies canonical URLs.

Evidence

What I checked:

• Current main still contains the defect: The builder uses process.cwd() for its root and path.basename(root) for the llms.txt product name; its canonical site and repository URLs are already fixed Discrawl values. (scripts/build-docs-site.mjs:62, 6169f2125e3d)
• Latest release does not contain the fix: v0.15.0 falls back to path.basename(root); a full-file search found no productName declaration that would override that fallback. (scripts/build-docs-site.mjs:62, 2eb4aae89549)
• Introduced correction and regression coverage: The verified base-to-head diff replaces the directory-derived identity with discrawl. The regression invokes the actual builder in a temporary renamed directory and checks the generated identity, canonical URLs, and absence of the directory name. (scripts/build-docs-site.test.mjs:11, 47e809bce4af)
• After-fix real build evidence: The complete supplied PR body reports a real invocation of node scripts/build-docs-site.mjs from the docs worktree and includes copied output showing the generated discrawl heading and description. This directly exercises the changed output; the reported failing-before/passing-after regression and successful docs check supplement it. Captured context sourceRevision: 5bdac1771191439044ad2429148ec3390a30079a70951e9b3c362b3ead60f6d0. (47e809bce4af)
• Feature-history routing: Main-branch history connects Peter Steinberger to the documentation index and subsequent builder maintenance; GitHub commit metadata maps the index commit to steipete. This establishes relevance beyond authorship of the proposed branch. (scripts/build-docs-site.mjs:56, 80fda26a976f)
• Workflow and security scope: The new CI job reuses the existing Pages checkout/setup-node pins and Node version under contents:read permissions. Pages adds the regression before its existing build; no permissions, dependency sources, publishing destinations, or secrets access change. (.github/workflows/ci.yml:17, 47e809bce4af)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.