refactor: prune verbose comments, and write down the rule

[jvsena42]

Comments had grown to 19.6% of every Kotlin line. Most of that was not
documentation: it was the signature restated in prose, or a bug's entire
history — how it was found, what was measured, which alternative was rejected —
retold in a KDoc where git log already holds it.

This prunes the heaviest files and writes the rule down so a fresh session does
not re-grow it.

What changed

37 files, 5,736 → 4,678 comment lines (18%). Across the tree, 16,879 →
15,821 (19.6% → 18.6% of all Kotlin). The files processed are the ones carrying
the long blocks — Repositories.kt alone was 69% comment by line.

The rule applied, now recorded in CLAUDE.md under Coding conventions →
Comments:

• The name is the documentation; a KDoc restating it is deleted.
• No KDoc on private declarations unless it carries something non-obvious — a
  lock precondition, an ordering constraint, a measured number, a bug the shape
  prevents. Those are kept in full.
• Comment the "why", never the "what".
• One tight paragraph, not an essay.

Roughly 830 KDocs sit on private declarations. I checked whether they could be
removed mechanically and they could not — most carry real content
(Guarded by [cacheLock], The caller must hold [Deck.id]'s write lock), so
every file was reviewed by hand and only the restatements went.

Bugs found on the way

Seven KDoc blocks documented the wrong declaration. A /** … */ separated
from its declaration by another KDoc silently attaches to whatever follows, and
nothing in the build reports it. LoopkyNavigation had three stranded above
goHomeSignedIn belonging to functions ~200 lines further down;
OnboardingViewModel, FakePubkyClient, Routes and ZipReader had one each.

Stale facts in the docs, all verified against the tree rather than carried
forward:

Claim	Was	Is
shared tests	~680	1,312 (:shared:jvmTest, all passing)
commonTest files	73	105
numbered journeys	19 (README) / 23 (CLAUDE.md)	25
repositories	9	11 — KeyBackupRepository and SignupRepository were missing from Architecture.md's table entirely
IdentityRepository	signInWithRing()	exists nowhere in the tree
Pubky FFI impl	AndroidPubkyClient (androidMain), an actual	UniffiPubkyClient (jvmSharedMain); PubkyClient is a plain Koin-bound interface, not expect/actual

Also condenses Architecture.md §7.8's account of the Ring-redeems-token path
that #147 removed — the decision and its reason stay, the deleted mechanism's
internals go.

Verification

No code changed. Every file was diffed comment-stripped against the
pre-refactor baseline and is byte-identical; the one thing that did change
shape, comment indentation, was caught by detekt and re-anchored.

• ./gradlew detektAll — clean
• ./gradlew :shared:jvmTest — 1312/1312
• :cli, :shared, :composeApp all compile

No journeys/ re-run: this touches no UI behaviour, and the code is provably
unchanged.

Not done

The prune covered the 37 files holding the long blocks. The long tail — ~100
files at 40–90 comment lines each — is untouched; CLAUDE.md says so, and frames
the rules as what to apply when you next touch a file rather than a claim the
tree is finished.

🤖 Generated with Claude Code

https://claude.ai/code/session_0116NZ92Pe7aGQpqtiRkP4Ye