docs: Answer first-time questions in the user guide - #97
BenWestgate wants to merge 3 commits into
Conversation
BenWestgate
left a comment
BenWestgate
left a comment
There was a problem hiding this comment.
AI-generated release-gate review, posted at the maintainer's request.
Concept ACK, but I would keep this draft for two documentation fixes before human review:
- “
ms32 create 2and the other thresholds write shares at random indices” is only true when indices are not explicitly supplied. The guide already documents--indices, so this answer should say the presets/default share-count path chooses random ordinary indices while--indicesuses the operator's explicit indices. - #90 explicitly says the length-specific cards from #88 show where the string ends. Once #88/#96 is settled, this answer should link the 48- and 74-character card templates (or state that the rarer lengths have no dedicated template yet) rather than leaving the length answer disconnected from that requested guidance.
The fingerprint/no-record and case answers match #57's reviewed contract. No security blocker beyond preserving that wording. The commit is Claude-authored and still requires responsible-human rewrite/squash before integration.
|
Reviewed the FAQ against the CLI. Follow-up 7fa8137 qualifies the two defaults: operators can choose share indices with --indices and specify an identifier. The original answers about the wallet-record fingerprint, length, and case remain unchanged. The updated documentation diff is ready for human review; the follow-up is agent-authored and should be handled under the repository authorship policy. |
BenWestgate
added
the
gate: adversarial review
ChatGPT Codex Connector
054e8d9 to
115f2c2
Compare
BenWestgate
left a comment
BenWestgate
left a comment
There was a problem hiding this comment.
Codex current-head follow-up review of 7fa8137: the first review finding is fixed. The share-index answer now correctly says the default ms32 create 2 path chooses random indices and points operators to --indices for explicit choices; the identifier wording likewise distinguishes the random default from an explicitly supplied identifier. Exact-head Python-package run 552 succeeded and there are no inline review threads.
One documentation blocker remains before ACK/human handoff: the length answer must link the 48-character standard recovery card and the 74-character/256-bit recovery card from #96, and explicitly say that 54/61/67/127-character backups do not yet have dedicated printable templates. Keep this draft until that follow-up is applied on the post-#96 base, then rerun the review. Claude/agent-authored commits still require responsible-human rewrite/squash before integration.
A tester asked why the fingerprint stays off the cards, why restore asks for it, how long a string is, which share indices create uses, and whether letter case matters. Answer each in a short section. The restore answer describes the typed-fingerprint step from #57, so this sits on that branch. Closes #90 Claude-Session: https://claude.ai/code/session_015CuLXqAvAovfoVcUmmogwa
The FAQ treated random indices and identifiers as unconditional even though the CLI accepts chosen share indices and an explicit set identifier. State the default behavior and the available choices accurately. Refs #90.
The 48-character answer points to the standard card and the 74-character answer to the 256-bit card from #96. The other lengths have no card yet. Claude-Session: https://claude.ai/code/session_015CuLXqAvAovfoVcUmmogwa
7fa8137 to
aafb716
Compare
BenWestgate
left a comment
BenWestgate
left a comment
There was a problem hiding this comment.
AI-generated review (Codex), posted at the maintainer's request.
ACK aafb716. The added first-use guidance matches the implemented recovery model.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aafb7167db
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Neither `ms1` nor the header says. A Bitcoin master seed is 48, 54, 61, 67, 74 | ||
| or 127 characters. Most are 48, which is 12 groups of four and fits the | ||
| [standard card](recovery-card.html). 256-bit seeds are 74, which is 19 groups | ||
| with two characters in the last and fits the [256-bit card](recovery-card-256.html). |
There was a problem hiding this comment.
A repository-wide path and history search confirms that docs/user/recovery-card-256.html is absent from this commit, so anyone following this new 256-bit-card link receives a broken page. Add the card in the same change or defer the link until that dependency is present.
AGENTS.md reference: AGENTS.md:L45-L47
Useful? React with 👍 / 👎.
| choose specific ones. Shared creation never shows `S`, the secret itself. | ||
| `ms32 create` with no threshold writes one unshared secret card, and | ||
| `ms32 secret` rebuilds the secret from shares. Each run without `--existing` | ||
| makes a new seed; its identifier is random unless you specify one. |
There was a problem hiding this comment.
When the preceding bare ms32 create example is used, generate_master_seed derives the identifier from the first 20 bits of the new seed's BIP32 fingerprint; only fresh shared sets use a random identifier by default. Saying every run without --existing has a random identifier therefore gives users incorrect information about the public metadata on the unshared card.
Useful? React with 👍 / 👎.
This branch has not been deployed
2 participants
Closes #90.
Add a short Common questions section to the user guide covering the first-time tester questions: why the wallet fingerprint stays off recovery cards, why restore asks the operator to type it, supported codex32 lengths, share indices and
S, and letter case.This documentation is based on #57 because the restore answer describes its typed-fingerprint gate and explicit no-record path.
Current review state:
115f2c2; the two earlier commits are unchanged (git range-diffshows them identical);bdd4a2b):ms32 create 2now says random share indices are the default and points to--indices; explicit identifiers are likewise distinguished from the random default;aafb716: it links docs: Size recovery cards to the backup length #96's 48-character standard card and 74-character 256-bit card, and states that 54/61/67/127-character backups have no printable card yet. The 256-bit card file comes from docs: Size recovery cards to the backup length #96, so that link resolves once docs: Size recovery cards to the backup length #96 is integrated (checked locally with docs: Size recovery cards to the backup length #96 applied on top: it applies cleanly and both files exist);aafb716; every test and compatibility job is green on it (github-advanced-security fails only on the Copilot monthly quota);Merge after #96 so the 256-bit card link resolves. The Claude/agent-authored commits require responsible-human rewrite/squash before integration.