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, 10:34 AM ET / 14:34 UTC.

ClawSweeper review

What this changes

Adds SwiftLint and SwiftFormat, with the Homebrew installation command, to the source-build prerequisites in the build guide.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open for ordinary maintainer review: this is a narrow docs-only candidate fix for the still-open linked report, and its one-line prerequisite clarification matches the repository’s documented validation workflow. Likely related people: steipete is a low-confidence adjacent repository-policy contact; the direct source-history ownership trail was not available in the supplied review evidence.

Priority: P3
Reviewed head: 14ed4c1efd69076dcbe15bd6c2339cc7d4c1ab06

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, internally consistent documentation fix with a clear linked user report and no correctness or security concerns.
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	3 items	Targeted documentation change: The PR changes only docs/building.md, adding SwiftLint and SwiftFormat plus brew install swiftlint swiftformat to the existing source-build prerequisite list. Repository validation contract: The repository policy identifies pnpm run lint and pnpm run format as required validation before handoff, supporting documentation of the tools those helpers require. Open canonical report: The PR body uses closing syntax for the still-open report at #294, so this active implementation PR should remain open until it is reviewed and merged or otherwise resolved.
Findings	None	None.
Security	None	None.

How this fits together

The source-build guide tells developers which local tools they need before using Peekaboo’s pnpm validation helpers. Those prerequisites affect whether lint and formatting commands can run successfully after checkout.

flowchart LR
  A[Developer checks out source] --> B[Source-build guide]
  B --> C[Install prerequisites]
  C --> D[pnpm validation helpers]
  D --> E[Lint and format checks]

Loading

Before merge

• Complete next step (P2) - This active docs-only PR has no actionable repair finding; it needs ordinary maintainer approval as the candidate fix for the linked open report.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	1 file affected; 1 line added, 1 trailing blank line removed	The patch is limited to the source-build prerequisite list and does not change scripts, tooling configuration, or release behavior.

Technical review

Best possible solution:

Merge the focused build-guide correction if maintainer review agrees, so source builders see the validation-tool prerequisites before running the documented pnpm checks.

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

Not applicable: this PR documents an existing development prerequisite rather than repairing a runtime failure path; the linked report supplies the setup gap it addresses.

Is this the best way to solve the issue?

Yes: placing 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 documentation clarification that reduces source-build setup friction without changing runtime behavior.
• 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:

• Targeted documentation change: The PR changes only docs/building.md, adding SwiftLint and SwiftFormat plus brew install swiftlint swiftformat to the existing source-build prerequisite list. (docs/building.md:16, 14ed4c1efd69)
• Repository validation contract: The repository policy identifies pnpm run lint and pnpm run format as required validation before handoff, supporting documentation of the tools those helpers require. (AGENTS.md:20, 8448599ab899)
• Open canonical report: The PR body uses closing syntax for the still-open report at swiftformat and swiftlint are needed for building Peekaboo #294, so this active implementation PR should remain open until it is reviewed and merged or otherwise resolved. (14ed4c1efd69)

Likely related people:

• steipete: The checked-in repository policy names this handle in its PR attribution guidance, but the supplied evidence does not establish direct ownership of the build guide; route with caution. (role: adjacent repository-policy contact; confidence: low; files: AGENTS.md, 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 (4 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