docs: a bootstrap page for dolos bootstrap stelae

[scarmuega]

Plan: plans/dolos-stelae-bootstrap-docs.md (Brain/txpipe)

What changed

• docs/content/bootstrap/stelae.mdx (new) — a bootstrap page for
  dolos bootstrap stelae, in the shape the four sibling pages already have.
• docs/content/bootstrap/index.mdx — its LinkCard in the method grid.

Prose only: no new command surface, no new flag, no behavior change.

The page covers the six things the plan named, because each is a thing an
operator gets wrong without it:

point	where on the page
--source in both spellings (file://DIR, oci://HOST/PATH)	Execution
--point: latest or epoch-N, and that a repository holds both	Flags → --point
--continue is the resume; a run without it starts over properly	Flags → --continue is the resume
sync.max_history bounds what is fetched	What gets fetched
[stelae.registry], by link rather than restatement	Registry credentials
--insecure is loopback / in-cluster only	Flags → --insecure

--scratch-dir is documented too — it is the fourth flag in the subcommand's
--help and an operator staging a mainnet transfer needs it.

Done criterion 2 — every claim read off the binary

cargo build --bin dolos at 07d28245 (main), then:

$ ./target/debug/dolos bootstrap stelae --help
Usage: dolos bootstrap stelae [OPTIONS] --source <SOURCE>

Options:
      --force              Clear existing data before bootstrapping
      --source <SOURCE>    Where to restore from, as a URL: `file://DIR` naming a stele directory,
                           or `oci://HOST/PATH` naming a repository in a registry
      --point <POINT>      which stele in the repository to restore: `latest`, or `epoch-N` for the
                           stele published at the end of epoch N. Registry sources only [default:
                           latest]
      --skip-if-data       Skip bootstrap if data already exists (exit 0)
      --continue           Continue bootstrap even if data exists, trusting the subcommand to handle
                           resumption
      --insecure           talk to the repository over plaintext HTTP rather than HTTPS; for a
                           registry on a loopback address or a mirror inside a cluster, and for
                           nothing reachable from outside one
      --scratch-dir <DIR>  directory to stage pulled layers in; defaults to
                           `<storage.path>/scratch`. registry sources only — a `file://` restore
                           stages nothing
      --verbose            Enable verbose logging output
  -c, --config <CONFIG>
  -h, --help               Print help

$ ./target/debug/dolos bootstrap --help
Usage: dolos bootstrap [OPTIONS] [COMMAND]

Commands:
  relay
  mithril
  snapshot
  stelae
  help      Print this message or the help of the given subcommand(s)

Options:
      --force            Clear existing data before bootstrapping
      --skip-if-data     Skip bootstrap if data already exists (exit 0)
      --continue         Continue bootstrap even if data exists, trusting the subcommand to handle
                         resumption
      --verbose          Enable verbose logging output
  -c, --config <CONFIG>
  -h, --help             Print help

Claims that are not in --help are read off the source rather than off a plan:

• "--point / --insecure / --scratch-dir are ignored for a file://
  source rather than being an error" — run() in src/bin/dolos/bootstrap/stelae.rs
  dispatches Source::Dir to restore_dir, which takes none of them.
• "file://./stele and file://stele are relative; file:///abs is absolute" —
  a_file_source_names_a_directory in the same module.
• "a path with no scheme, an https:// URL, or an oci:// URL that names a tag
  are rejected at the command line" — an_unusable_source_is_refused.
• "epochs below the sync.max_history floor are never fetched at all" —
  retain_history / plan in crates/snapshot/src/restore.rs; unset max_history
  returns every epoch.
• The summary lines and their exact wording — report() in the same module,
  including that epochs: names sync.max_history only when skipped_epochs > 0
  and resumed: prints only when outlook.inherited > 0.
• "restore is bounded by transfer, not replay" and the boundary-state sizing —
  adrs/004_stelae_snapshots.md, Consequences.

Done criterion 3 — the docs site builds

Not verifiable in this repository, and reported rather than claimed. docs/
here is content only: no package.json, no astro.config.*, and no docs job in
.github/workflows/. The site is built elsewhere from this content.

What was verified instead: the new page carries the same frontmatter keys as its
siblings (title, sidebar.label, sidebar.order), imports only Aside from
@astrojs/starlight/components and uses only that component, and its
cross-document links follow the relative form already used across the tree
(../bootstrap, ../configuration/schema#sync-section,
../configuration/schema#stelaeregistry-section). A reviewer with the site
checkout should confirm the build and the two schema anchors resolve.

Judgment calls a reviewer should rule on

• Sidebar order 4, i.e. last, after relay. The plan says the method matters
  more than the others do — but it also says which method a release recommends
  is a product decision nobody has recorded, so the page does not take it by
  ordering. Move it up if that decision has since been made.
• No live registry URL. The example repository is
  oci://registry.example.com/dolos-snapshots/mainnet, a shape rather than an
  endpoint, because the official one is not provisioned yet
  (dolos-stelae-cloudflare-registry). Worth a follow-up edit once it exists.

Out of scope by the plan's own scope decisions and untouched: dolos snapshot publish docs, ADR-004, and the legacy bootstrap snapshot page.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added Stele to the available bootstrap methods.
  • Documented how to bootstrap Dolos from local steles or OCI repositories.
  • Added guidance on source validation, registry selection, supported options, resume behavior, credentials, restore costs, progress reporting, history limits, and chain synchronization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4a18af43-cbdd-40b9-ba4b-5f5bccccded6

📥 Commits

Reviewing files that changed from the base of the PR and between f97d92b and 68fc882.

📒 Files selected for processing (2)

• docs/content/bootstrap/index.mdx
• docs/content/bootstrap/stelae.mdx

Included review availability: Your plan includes up to 2 reviews per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds a dolos bootstrap stelae guide. It documents local and OCI sources, restore options, resume behavior, registry access, progress output, and post-restore synchronization. A bootstrap methods card links to the guide.

Changes

Stele bootstrap documentation

Layer / File(s)	Summary
Stele bootstrap guide and navigation docs/content/bootstrap/stelae.mdx, docs/content/bootstrap/index.mdx	Adds the complete Stele bootstrap guide and links it from the Bootstrap Methods card grid.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 68fc8

This documentation-only change adds guidance for an existing bootstrap command without changing product behavior; no actionable merge-blocking risk remains.

Possibly related PRs

• txpipe/dolos#1169: Introduces the bootstrap stelae functionality documented by this PR.
• txpipe/dolos#1176: Implements the registry restoration and resumable restore behavior covered by the guide.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the new documentation page for dolos bootstrap stelae, which is the main change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/bootstrap-stelae-page

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}