docs: document SwiftLint and SwiftFormat prerequisites

[goutamadwant]

Closes #294

What Problem This Solves

Fixes an issue where users building Peekaboo from source could miss that the repository validation helpers require SwiftLint and SwiftFormat.

Why This Change Was Made

The build guide already lists the source-build prerequisites, so this adds the missing formatter and linter tools there with the Homebrew install command. This is intentionally documentation-only and does not change build scripts, lint configuration, or release behavior.

User Impact

Developers following the source-build guide can install the expected validation tools before running the pnpm helper scripts, avoiding avoidable setup failures.

Evidence

• node scripts/docs-lint.mjs
  • Result: docs-lint: ok
• git diff --check
  • Result: passed.
• GitHub reports the pushed commit signature as verified.

Disclosure: AI was used to understand the codebase and review the fix.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 30, 2026, 9:18 PM ET / July 31, 2026, 01:18 UTC.

ClawSweeper review

What this changes

The PR adds SwiftLint and SwiftFormat, with a Homebrew install command, to the source-build prerequisites in docs/building.md.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

This active docs-only PR is the linked implementation candidate for the still-open report about missing source-build validation prerequisites. The proposed clarification is narrow, consistent with repository guidance that validation uses SwiftLint and SwiftFormat, and should remain open for ordinary maintainer approval and merge handling.

Priority: P3
Reviewed head: 14ed4c1efd69076dcbe15bd6c2339cc7d4c1ab06

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused docs-only patch with no identified correctness or security defects; it needs ordinary maintainer review rather than contributor repair.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed	4 items	PR scope: The supplied PR diff changes only docs/building.md, adding the formatter and linter prerequisite while removing only the file-ending blank line. Repository policy: The repository guidance identifies pnpm run lint and pnpm run format as handoff validation commands and instructs source contributors to install required tooling; this supports documenting the two Swift tools in the build guide. Linked report remains open: The PR body uses closing syntax for the open report at #294, and the related-item context marks it clawsweeper:linked-pr-open; it should not be closed before this PR merges.
Findings	None	None.
Security	None	None.

How this fits together

docs/building.md is the contributor-facing source-build guide. It prepares developers to run the repository’s pnpm validation helpers, which depend on locally installed SwiftLint and SwiftFormat tools.

flowchart LR
  A[Source contributor] --> B[Build guide]
  B --> C[Prerequisite setup]
  C --> D[pnpm validation helpers]
  D --> E[SwiftLint and SwiftFormat]
  E --> F[Build and validation results]

Loading

Before merge

• Complete next step (P2) - No mechanical repair is needed; the remaining action is ordinary maintainer review and merge handling for the linked implementation PR.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	1 file affected; 1 line added, 1 line removed	The patch is narrowly limited to contributor prerequisite guidance and does not alter build, lint, format, or release behavior.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #294
Summary: This PR explicitly proposes the documentation fix for the still-open prerequisite report.

Members:

• canonical: swiftformat and swiftlint are needed for building Peekaboo #294 - The report identifies the same missing SwiftLint and SwiftFormat prerequisite information that this PR adds to the build guide.

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

Technical review

Best possible solution:

Merge this focused prerequisite clarification after ordinary maintainer review so the linked issue can close automatically with the documentation fix.

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

Not applicable: this PR documents prerequisite tooling rather than repairing an executable runtime failure. The linked report supplies the relevant developer setup context.

Is this the best way to solve the issue?

Yes. Adding the missing tools beside the existing source-build prerequisites is the narrowest maintainable solution and avoids changing validation scripts or configuration.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P3: This is a low-risk developer-documentation clarification with limited blast radius.
• 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

What I checked:

• PR scope: The supplied PR diff changes only docs/building.md, adding the formatter and linter prerequisite while removing only the file-ending blank line. (docs/building.md:16, 14ed4c1efd69)
• Repository policy: The repository guidance identifies pnpm run lint and pnpm run format as handoff validation commands and instructs source contributors to install required tooling; this supports documenting the two Swift tools in the build guide. (AGENTS.md:18, 8448599ab899)
• Linked report remains open: The PR body uses closing syntax for the open report at swiftformat and swiftlint are needed for building Peekaboo #294, and the related-item context marks it clawsweeper:linked-pr-open; it should not be closed before this PR merges. (14ed4c1efd69)
• Review continuity: Seven completed ClawSweeper cycles at the same head SHA reported no actionable patch findings; the current review context contains no maintainer review comments or changed-head evidence requiring a new finding. (14ed4c1efd69)

Likely related people:

• goutamadwant: The available review context identifies this person as the sole author of the focused documentation commit; no current-main history could be inspected because the read-only command sandbox failed before repository commands could run. (role: documentation change proposer; confidence: low; commits: 14ed4c1efd69; files: docs/building.md)

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.

History

Review history (7 earlier review cycles)

• reviewed 2026-07-29T17:08:22.469Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-29T20:22:22.946Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-29T22:19:15.896Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T07:38:32.593Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T14:34:51.736Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T21:14:47.429Z sha 14ed4c1 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T23:35:13.806Z sha 14ed4c1 :: needs maintainer review before merge. :: none