docs: correct pnpm version and caller-auth count in getting-started docs

[KrasimirKralev]

MUST: Allow edits from maintainers is enabled on this PR.

What Problem This Solves

Two getting-started docs state facts the code contradicts, so a new contributor following them hits a mismatch on the very first steps:

• docs/install.md tells you to use pnpm 11, but the repo pins pnpm 12.6.0 via corepack, so a from-source setup actually runs pnpm 12.
• docs/quickstart.md calls out "the four ways to identify a caller", but ClickClack resolves callers five ways — the linked auth page and the resolver both say five.

User Impact

Onboarding docs match the code: from-source instructions name the pnpm major that corepack will install, and the quickstart's auth pointer agrees with the auth page it links to. No behavior change — documentation only.

Why This Change Was Made

• pnpm version. corepack derives the pnpm version from packageManager in the root package.json, which is pnpm@12.6.0. docs/development.md already says "pnpm 12.6.0, matching packageManager in package.json." docs/install.md was left at "pnpm 11". Updated to "pnpm 12".
• Caller-auth count. currentActor resolves a caller through five mechanisms (Bearer session/bot token, session cookie, Cloudflare Access assertion, X-ClickClack-User header, dev fallback to the first user). docs/features/auth.md opens with "ClickClack accepts five ways to identify a caller" and enumerates all five. The quickstart link that points at that page said "four" — a stale count from before Cloudflare Access was added. Updated to "five".

Evidence

Grep of the current tree (upstream/main) showing docs vs. code:

$ grep -n 'packageManager' package.json
38:  "packageManager": "pnpm@12.6.0",

$ grep -rn 'pnpm 12' docs/development.md
16:- pnpm 12.6.0, matching `packageManager` in `package.json`.

# before this PR, docs/install.md:14 read "pnpm 11" — now "pnpm 12"

$ grep -n 'ways to identify a caller' docs/features/auth.md docs/quickstart.md
docs/features/auth.md:10:ClickClack accepts five ways to identify a caller, in order of precedence.
# before this PR, docs/quickstart.md:110 read "the four ways" — now "the five ways"

$ grep -nE 'Authorization|Session cookie|accessAssertionHeader|X-ClickClack-User|FirstUser' apps/api/internal/httpapi/actor.go
# currentActor resolves: Bearer token, session cookie, Cloudflare Access assertion,
# X-ClickClack-User header, and dev fallback (FirstUser) — five mechanisms.

Docs-only change; no code paths touched. CI's docs-site build validates the pages render.

[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 real behavior proof before merge. Reviewed September 29, 2026, 9:13 PM ET / September 30, 2026, 01:13 UTC (Revision 2).

ClawSweeper review

What this changes

The branch changes the source-install guide from pnpm 11 to 12, changes the quickstart auth pointer from four caller methods to five, and records both corrections in the changelog.

Merge readiness

⛔ Blocked before merge - 2 items remain

Current main still contains both outdated statements. The corrections match the package pin and authentication guide, and the PR remains useful.

Priority: P3
Reviewed head: 3bc3ef378f2e02eee55c38fe70881d34bd3c6d8c

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The focused corrections match current source, while direct after-change proof of the edited pages remains thin.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The PR body shows a source cross-check for the package pin and auth guide, but no after-change output or rendering of the edited install and quickstart pages. Because the branch also changes root-level CHANGELOG.md, the path-based docs-only exemption does not apply; a redacted terminal read of the edited lines or rendered-page evidence would establish the result. No stored-data contract changes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The PR body shows a source cross-check for the package pin and auth guide, but no after-change output or rendering of the edited install and quickstart pages. Because the branch also changes root-level CHANGELOG.md, the path-based docs-only exemption does not apply; a redacted terminal read of the edited lines or rendered-page evidence would establish the result. No stored-data contract changes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Introduced documentation changes: The pinned PR delta changes the two doc statements and adds an unreleased changelog entry. Current-main package pin: The root packageManager field pins pnpm 12.6.0; the current-main install guide still says pnpm 11. Current-main authentication contract: The auth guide enumerates five caller-identification methods, consistent with the server resolver; the current-main quickstart still says four.
Findings	None	None.
Security	None	None.

How this fits together

ClickClack’s getting-started docs guide contributors through building the server and finding its authentication guide. The build uses the workspace’s pinned package manager, while the server resolves incoming callers through the methods described in the auth guide.

flowchart LR
A[Source checkout] --> B[Install guide]
C[Package manager pin] --> B
B --> D[Built server]
E[Incoming request] --> F[Caller identification]
F --> G[Auth guide]
G --> H[Quickstart pointer]

Loading

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The PR body shows a source cross-check for the package pin and auth guide, but no after-change output or rendering of the edited install and quickstart pages. Because the branch also changes root-level CHANGELOG.md, the path-based docs-only exemption does not apply; a redacted terminal read of the edited lines or rendered-page evidence would establish the result. No stored-data contract changes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Show the changed install and quickstart text after the fix in a real checkout or rendered docs view, with private details redacted.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep the two onboarding statements aligned with the pinned toolchain and auth guide, with an observed check of the edited pages before merge.

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

Not applicable as a documentation correction; the current-main docs, package pin, and auth guide establish both mismatches directly.

Is this the best way to solve the issue?

Yes. Changing the two stale statements is the narrowest way to align onboarding with the existing toolchain and authentication behavior.

AGENTS.md: found, but no applicable review policy affected this item.

Codex review notes: model internal, reasoning medium; reviewed against 31d299eee271.

Labels

Label changes:

No label changes.

Label justifications:

• P3: This is a small documentation accuracy correction with no runtime change.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body shows a source cross-check for the package pin and auth guide, but no after-change output or rendering of the edited install and quickstart pages. Because the branch also changes root-level CHANGELOG.md, the path-based docs-only exemption does not apply; a redacted terminal read of the edited lines or rendered-page evidence would establish the result. No stored-data contract changes. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Introduced documentation changes: The pinned PR delta changes the two doc statements and adds an unreleased changelog entry. (docs/install.md:14, 3bc3ef378f2e)
• Current-main package pin: The root packageManager field pins pnpm 12.6.0; the current-main install guide still says pnpm 11. (package.json:38, 31d299eee271)
• Current-main authentication contract: The auth guide enumerates five caller-identification methods, consistent with the server resolver; the current-main quickstart still says four. (docs/features/auth.md:10, 31d299eee271)
• Caller resolver: The resolver handles bearer credentials, session cookies, a configured Access assertion, a local user header, and a local development fallback. (apps/api/internal/httpapi/actor.go:49, 31d299eee271)
• Unreleased documentation note: The branch adds a note under Unreleased in a root-level changelog. The supplied PR-body terminal excerpt checks the underlying mismatch but does not show an after-change read or rendering of either edited page. (CHANGELOG.md:5, 3bc3ef378f2e)
• Release boundary: The latest v0.6.0 tag points at current main, where both old doc statements remain; the PR head is in no local tag. (31d299eee271)

Likely related people:

• Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Shakker: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Isaiah Knight: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add redacted terminal output showing both edited lines after the change, or screenshots of the rendered pages; updating the PR body should trigger re-review, and a maintainer can request @clawsweeper re-review if it does not.

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 (1 earlier review cycle)

• reviewed 2026-09-27T10:09:54.768Z sha a5633a2 :: needs maintainer review before merge. :: none