Skip to content

Say that custody is a journey, without arguing anyone into buying - #117

Merged
HodlDee merged 4 commits into
mainfrom
guide-custody-journey
Sep 8, 2026
Merged

HodlDee merged 4 commits into
mainfrom
guide-custody-journey

Conversation

@HodlDee

@HodlDee HodlDee commented Sep 7, 2026 •

Copy link
Copy Markdown
Owner

What this changes, and why

Closes #65. New guide: Self-custody is a journey, not a test you pass (custody-journey, fundamentals, beginner).

The brief asked for the journey framing — day one on an ETF or an exchange is fine and should not be frowned upon, the goal might be multisig, and you do not drive on the motorway during your first lesson.

The thesis changed during review, and this description is the corrected one

The original draft argued that having exposure beats waiting. It called reading about custody for eight months and buying nothing "the genuinely common failure", ranked someone with coins on an exchange above someone with a good mental model and none, and pull-quoted "having exposure is not the mistake."

External review flagged that as persuasion about whether to own bitcoin — in the same batch where #116 was reframed precisely because the homepage says "Built to Inform, Not Persuade." Applying that standard to one guide and breaking it in another is worse than not applying it at all, so the thesis is gone.

What the guide argues now: whether to own bitcoin at all is not a question this site answers. Deciding it is not for you, or not yet, is a complete answer. What the page is about is custody — how to move between arrangements without hurting yourself, for people who have coins or have decided to get some.

Reducing shame about an existing exchange balance never required shaming someone who chose not to buy.

The first step needs no money, and now actually works that way

Replacing the pressure with an exercise that costs nothing was the right move, and my first attempt at it was wrong: it told the reader to "send a few thousand satoshis to yourself" while promising every mistake was free. An empty wallet cannot send anything, and a real transfer risks the amount and the fee. The reviewer caught it.

The unfunded exercise now ends where it can — set up a wallet, write the backup down properly, record the first receiving address, wipe, restore from the backup alone, compare the address. Every step is genuinely free because there is nothing in the wallet to lose, and the comparison is what makes it a test rather than a rehearsal of typing.

Sending is called out as the one thing it cannot cover, pointed at test-transaction, and marked explicitly optional and later.

It resolves a tension already in the library

choosing-your-first-setup says bitcoin left on an exchange "is exposed to the risk you were trying to avoid". True. The brief says day-one exposure is fine. Also true. The resolution is that the right response to that risk is a route out, not shame about being on it — and the two guides link to each other.

Notes for the reviewer

  • The overlap was the risk. choosing-your-first-setup §5 already gives a three-stage arc. That guide answers which shape fits the amount you hold; this one answers how to move between shapes without hurting yourself. Cross-linked rather than repeated — worth checking you agree they are different questions.
  • An ETF is price exposure rather than bitcoin — no withdrawal, because there is nothing to withdraw. Saying so is not shaming anyone for being in one.
  • Readiness is presented as checkable rather than felt: restored once, sent and received deliberately, able to say where the keys are, and bored of the current setup. Boredom is the signal.
  • It declines to assume everyone is heading for multisig. A hardware wallet with a tested backup is a complete answer for most people holding most amounts, not a waypoint. That is a position, and you may want it stated more or less strongly.

Tests

npm run build

Every guard passing. All glossary anchors resolve.

  • I ran the tests relevant to this change
  • npm run build completes with every guard passing
  • If I added a test, I wired it into .github/workflows/build.yml

Generated output

  • I changed build sources, and the regenerated docs/ is committed here

The offline artifact

  • The digest is unchanged

Assets and third-party code

  • This adds no images and no third-party code

Before requesting review

  • This contains no real seed phrase, private key, passphrase or entropy
  • This is not a security fix that should have gone through the private advisory form

🤖 Generated with Claude Code

Closes #65. The brief asked for the journey framing -- day one on an ETF or an
exchange is fine and should not be frowned upon, the goal might be multisig,
and you do not drive on the motorway during your first lesson.

Writing it surfaced a tension in the existing library worth resolving rather
than tiptoeing around. choosing-your-first-setup says bitcoin left on an
exchange "is exposed to the risk you were trying to avoid", which is true.
The brief says day-one exposure is fine, which is also true. The synthesis is
that having exposure is not the mistake -- staying where you started, by
default, for years, because nobody said the next step could be small, is.
Both guides now say that, and link to each other.

The overlap with that guide's "Plan to outgrow it" section was the risk here.
It answers which shape fits the amount you hold. This one answers how to move
between shapes without hurting yourself, which is a different question, and
the two are cross-linked rather than repeating each other.

Two things the brief did not ask for and the page needed. An ETF is price
exposure rather than bitcoin -- there is no withdrawal because there is nothing
to withdraw -- so it is a waiting room rather than a first rung, and saying so
is not the same as shaming anyone for being in it. And readiness is presented
as something you check rather than feel: restored once, sent and received
deliberately, able to say where the keys are, and bored of the current setup.
Boredom is the signal; novelty means you are still learning the rung you are on.

It also declines to assume everyone is heading for multisig. A hardware wallet
with a tested backup is a complete answer for most people holding most amounts,
not a waypoint to something better.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
From the external review, and it is the finding I least enjoyed reading.

The opening called reading about custody for eight months and buying nothing
"the genuinely common failure", ranked "a person with coins on an exchange"
above "a person with a perfect mental model and no bitcoin", and pull-quoted
"having exposure is not the mistake."

That is persuasion about whether to own bitcoin, in the same batch where I
reframed #116 specifically because the homepage says "Built to Inform, Not
Persuade" and the draft reached a conclusion for the reader. Applying the
standard to one guide and breaking it in another is worse than not having
applied it at all.

Reducing shame about an existing exchange balance does not require shaming
someone who has chosen not to buy. The section now says plainly that whether to
own bitcoin at all is not a question this site answers, and that deciding it is
not for you, or not yet, is a complete answer.

What replaces the pressure is more useful than what it removes: **a first step
that involves buying nothing.** Set up a wallet with no money in it, generate a
backup, restore from it, send yourself a few thousand satoshis. It costs almost
nothing, every mistake is free, and it answers the question people are actually
stuck on -- whether they can do this at all -- without asking them to decide
anything about money first.

The heading changes from "Having some exposure beats waiting to be ready" to
"Wherever you are is a place to start from", and the summary drops "both are
better than eight months of research and no position." The rest of the guide is
unchanged: the rungs, the risk explanations, and the point that multisig is not
a mandatory destination were not what the finding was about.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
HodlDee added a commit that referenced this pull request Sep 7, 2026
Follow-up review of #117, and the error is mine. The replacement I wrote for
the purchase-pressure finding promised an exercise that needs no bitcoin and
then told the reader to "send a few thousand satoshis to yourself", while
claiming every mistake is free.

An empty wallet cannot send anything, and a real transfer risks both the amount
and the fee. So the paragraph fixed the finding and introduced a new one.

The unfunded exercise now ends where it can: set up a wallet, write the backup
down properly, record the first receiving address, wipe, restore from the
backup alone, and compare the address. Every step costs nothing and risks
nothing, because there is nothing in the wallet to lose -- and the comparison
is what makes it a test rather than a rehearsal of typing.

Sending is called out as the one thing the exercise cannot cover, needing coins
by definition, and pointed at the test-transaction guide as an explicitly later
and optional step for people who have some. The "every mistake is free"
guarantee stays only on the part where it is true.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@HodlDee HodlDee changed the title Say that starting on an exchange is a start, not a failure Say that custody is a journey, without arguing anyone into buying Sep 7, 2026
Follow-up review of #117, and the error is mine. The replacement I wrote for
the purchase-pressure finding promised an exercise that needs no bitcoin and
then told the reader to "send a few thousand satoshis to yourself", while
claiming every mistake is free.

An empty wallet cannot send anything, and a real transfer risks both the amount
and the fee. So the paragraph fixed the finding and introduced a new one.

The unfunded exercise now ends where it can: set up a wallet, write the backup
down properly, record the first receiving address, wipe, restore from the
backup alone, and compare the address. Every step costs nothing and risks
nothing, because there is nothing in the wallet to lose -- and the comparison
is what makes it a test rather than a rehearsal of typing.

Sending is called out as the one thing the exercise cannot cover, needing coins
by definition, and pointed at the test-transaction guide as an explicitly later
and optional step for people who have some. The "every mistake is free"
guarantee stays only on the part where it is true.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@HodlDee
HodlDee force-pushed the guide-custody-journey branch from 8e93808 to b0003ad Compare September 7, 2026 23:56
…ss-link

Three `related` arrays conflicted, each because two branches appended a
different guide to the same list. Resolved by union in every case, never by
choosing a side -- `related` is one-way in render.mjs, so dropping the other
side's entry would publish a guide with no route to it from anywhere.

  owning-your-bitcoin  + custody-journey, evaluating-a-monetary-asset
  quickstart           + custody-journey, bitcoin-core-wallet
  how-custody-fails    + custody-journey, evaluating-a-monetary-asset

Generated output was rebuilt from the resolved sources rather than merged.
docs/ is build output; a hand-merged generated file is a file that no longer
matches what produced it, which the reproducibility check exists to catch.

## The cross-link #87 asked for

The draft in #87 asked that the crypto piece and the custody journey link each
other once both were published. Neither could carry it before: the build guard
rejects prose linking to a page that does not exist yet, so the link had to
wait for the second of the two to land. Both are published as of this merge, so
it goes in now.

Each direction says why the other page is worth following rather than just
pointing at it. The custody journey reaches the eight questions as "the same
instinct pointed at the asset rather than the custodian"; the questions reach
the journey where the page is already talking about losses at platforms.

Both `related` lists updated too, since render.mjs does not infer the reverse
edge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@HodlDee
HodlDee merged commit 46831ce into main Sep 8, 2026
14 checks passed
@HodlDee
HodlDee deleted the guide-custody-journey branch September 8, 2026 05:25
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.

Custody models explained

1 participant