Skip to content

docs: make README user-facing and organize references - #405

Merged
pwltr merged 1 commit into
mainfrom
docs/user-facing-readme
Nov 9, 2026
Merged

pwltr merged 1 commit into
mainfrom
docs/user-facing-readme

Conversation

@pwltr

@pwltr pwltr commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Closes #403.

The README now leads with product information, iOS/Android downloads, the official landing-page headline and supplied product preview, a short getting-started flow, and support links. Development setup, input formats, and device-authentication/release-verification details live in three linked guides under docs. The existing Maestro guide stays in place.

The moved material was checked against current code and CI: Node guidance matches the package/CI setup, input docs include grant and direct-signup behavior and distinguish secret strings from encrypted recovery files, and APK verification no longer assumes signing files or a bundled public key exist. Checksum verification uses the clearsigned SHA256SUMS.asc format published by signed releases, rather than treating it as a detached signature over the unsigned manifest. Homeserver discovery and the known recovery limits are documented in the developer guide. The headline matches https://pubkyring.app/, which is also linked for product demos. The product preview uses the supplied image without modification.

Validation: Prettier and diff checks pass; checked all relative links, anchors, image paths, package script names, and shell-example syntax. External links were checked. All 21 relative links, anchors, and image paths resolve. The GitHub Markdown API accepted the README with the landing-page headline and one product preview with alt text. No app code changes or runtime tests in this documentation-only PR.

Release-verification regression check: downloaded the actual v1.16 public key and manifests into a temporary directory, imported the public key into an isolated GPG home, reproduced the failing two-file command, and confirmed the documented single-file verification succeeds. This validates the command against those assets; signer trust still requires an independently checked fingerprint.

@pwltr
pwltr force-pushed the docs/user-facing-readme branch 2 times, most recently from f15326e to 020a22a Compare November 9, 2026 15:52
@pwltr
pwltr requested a review from coreyphillips November 9, 2026 15:54

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two independent reviews.

needs changing before merge

  • Checksum verification command fails on the project's clearsigned manifests (docs/security.md:42-46). gpg --verify SHA256SUMS.asc SHA256SUMS treats the .asc as a detached signature, but every signed release (v1.14 to v1.17) ships SHA256SUMS.asc as a clearsigned message, so the documented command errors out. Confirmed by downloading the v1.16 assets into a temp dir and running gpg 2.2.41 with an isolated GNUPGHOME after importing the release's public-key.asc: $ gpg --verify SHA256SUMS.asc SHA256SUMS gpg: not a detached signature (exit 2) $ gpg --verify SHA256SUMS.asc gpg: Good signature from ... gpg: WARNING: not a detached signature; file 'SHA256SUMS' was NOT verified! v1.17's SHA256SUMS.asc also starts with -----BEGIN PGP SIGNED MESSAGE-----. The old README's single-argument form worked, so this is a regression. The prose ("its detached signature") describes a format the project does not produce. Suggested fix: use gpg --verify SHA256SUMS.asc, then compare the APK hash with the line inside SHA256SUMS.asc (the signed text). The loose SHA256SUMS file is not covered by the signature.

nits

  • README links pubkyring.app twice within a few lines (README.md:11-24). The Download section says "Visit pubkyring.app for more about the app", and right below the preview image "See Pubky Ring in action" links to the same URL. One link is enough for the short user-facing README the issue asks for.

the reviewers disagree, your call

  • A late grant refresh can reverse a homeserver switch (src/utils/pubky.ts:963-965). Objection: Real, but non-blocking rather than blocking: Confirmed by reading the code. When no stored session is usable, listAuthorizedGrants calls signInToHomeserver and then sets homeserver from the sign-in response (lines 963-965). This write is new in this PR. submitEditPubky → signUpToHomeserver never goes through withHomeserverOperation, so a sign-in that resolved the old mapping (A) can land after the switch to B and write A back. performAuth then republishes pubkyData.homeserver (A). Not blocking because it needs a refresh that is already in its sign-in fallback (signedUp but no usable stored session) and still pending while the user submits the switch, which is a narrow window. The fix is cheap: run the switch inside withHomeserverOperation, or skip the dispatch if the stored homeserver changed while the refresh was running.

@pwltr

pwltr commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

Addressed the documentation findings in 773e389:

  • Corrected the checksum regression: gpg --verify SHA256SUMS.asc verifies the clearsigned message. The guide explicitly says to compare against the checksum inside that signed text, and that the separate SHA256SUMS file is not authenticated by this command. I reproduced the bad command and verified the corrected one against the actual v1.16 assets using an isolated GPG home. The public-key filename now also matches the release asset.
  • Removed the duplicate landing-page link from the Download section; the product-demo link remains below the preview.

The refresh/switch race is also valid, but that code was already merged through #357 and is unchanged by this docs PR. I fixed it separately in #406: fallback refresh captures the saved homeserver and rejects its stale result if a manual switch changed that value during native sign-in or Keychain storage. The issued grant remains tracked for cleanup, and subsequent refresh uses the new server's existing session. Both regression cases fail before the fix; all 471 tests pass with it, plus typecheck, targeted lint, formatting, and diff checks. Live native timing has not been reproduced.

@pwltr
pwltr requested a review from coreyphillips November 9, 2026 16:22

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after the branch was rewritten, so every earlier point was verified again from scratch. 1 blocking finding the reviewers disagree about.

addressed

  • Checksum verification command fails on the project's clearsigned manifests (docs/security.md:42-46). Fixed: docs/security.md:42-54 now says gpg --verify SHA256SUMS.asc and has you compare against the signed text inside it. I downloaded the v1.17 assets and imported public-key.asc into an isolated GNUPGHOME. The documented command exits 0 with a good signature, and the old two-file form still fails with not a detached signature. The warning the guide mentions matches what gpg prints.
  • README links pubkyring.app twice within a few lines (README.md:11-24). Fixed: README.md now links pubkyring.app only once, at line 25. The Download section (line 11) keeps just the release verification link. Confirmed by grep.

still open

  • A late grant refresh can reverse a homeserver switch (src/utils/pubky.ts:963-965). When refresh needs a new management session, its sign-in response can arrive after setup has switched servers. I confirmed this with mocked native responses: delay refresh's sign-in on A, complete signup on B, then release the refresh. This dispatch persists A again, and the next performAuth republishes A. The switch path does not participate in the ordering protection used by refresh and sign-out. Codex still sees it: src/utils/pubky.ts:963-965 still restores A after a completed switch to B, reproduced with refresh delayed at native sign-in and Keychain storage. The separate #406 fix is absent from HEAD, and this implementation remains in the requested diff against origin/main.

@pwltr

pwltr commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for rechecking the documentation fixes. The remaining race is real and is fixed separately in #406, but it is not introduced or changed by #405.

I verified the current GitHub base and diff:

So the statement that this implementation remains in #405's diff against current origin/main is incorrect. It is existing code from the merged homeserver work. Please assess the race fix in #406 and the documentation here against the current main base. #406 has the native-sign-in and Keychain-delay regression cases described in this review; all 471 local tests passed, and its CI lint/unit checks are green while native E2E checks are pending. The docs PR intentionally does not include that code change.

@pwltr
pwltr requested a review from coreyphillips November 9, 2026 16:35

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after replies, with no new commit since 773e389. Nothing blocking remains.

addressed

  • A late grant refresh can reverse a homeserver switch (src/utils/pubky.ts:963-965). Rebutted: Your 16:33 comment holds against the code. git diff origin/main...HEAD --name-only lists only README.md and the docs/ files. src/utils/pubky.ts is the same blob (ad071f7d) at origin/main, at HEAD and at 97bd2dd (#357), so lines 963-965 came in with the merged homeserver work. The race is real, but it belongs to #406, not this docs PR.

@pwltr
pwltr merged commit e6ad5da into main Nov 9, 2026
4 checks passed
@pwltr
pwltr deleted the docs/user-facing-readme branch November 9, 2026 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make the README user-facing and relocate developer documentation

2 participants