bulletin-deploy 0.7.5 → 0.7.6

package/README.md

@@ -1,23 +1,24 @@
 # bulletin-deploy
 
-Deploy static sites and apps to the Polkadot Triangle network with decentralized storage and human-readable `.dot` domains.
+`bulletin-deploy` publishes a static web app to Bulletin and binds it to a human-readable `.dot` domain.
+
+The main CLI is deploy-only. Pool bootstrap and other operator setup live in [`bulletin-bootstrap`](docs/bootstrap.md).
 
 ## Quick Start
 
 ```bash
 npm install -g bulletin-deploy
-# Build your app (e.g. npm run build)
+
+# Build your app first, then deploy it.
 bulletin-deploy ./dist my-app00.dot
 ```
 
-Your site is live at `https://my-app00.dot.li`
-
-> **Stable vs release candidate.** `npm install -g bulletin-deploy` (and `@latest`) always resolves to the latest stable version — never an RC. Release candidates are published under the `rc` dist-tag and can be installed explicitly with `npm install -g bulletin-deploy@rc` (or a literal version pin like `@0.6.9-rc.0`). Only use RCs for testing.
+On success, the CLI prints the CID and the `.dot` domain that now serves your app.
 
-## Prerequisites
+## Installation
 
 - **Node.js 22+**
-- **IPFS Kubo** (for merkleizing directories — not needed with `--js-merkle`)
+- **IPFS Kubo** if you want the default merkleization path
 
 ```bash
 # macOS
@@ -31,7 +32,17 @@ sudo bash kubo/install.sh
 ipfs init
 ```
 
-> **No Kubo?** Use `--js-merkle` to skip the Kubo requirement entirely. See [Merkleization modes](#merkleization-modes) below.
+If you do not want a Kubo dependency, pass `--js-merkle`.
+
+Stable installs:
+
+- `npm install -g bulletin-deploy`
+- `npm install -g bulletin-deploy@latest`
+
+Release candidates:
+
+- `npm install -g bulletin-deploy@rc`
+- `npm install -g bulletin-deploy@<exact-version>`
 
 ## CLI Usage
 
@@ -45,374 +56,109 @@ Examples:
 # Basic deploy
 bulletin-deploy ./dist my-app00.dot
 
-# Custom RPC endpoint
-bulletin-deploy --rpc wss://custom-bulletin.example.com ./dist my-app00.dot
+# Direct signer deploy
+bulletin-deploy ./dist my-app00.dot --mnemonic "..."
+
+# Custom Bulletin RPC
+bulletin-deploy ./dist my-app00.dot --rpc wss://custom-bulletin.example.com
 ```
 
-### All options
+### Options
 
-```
-Options:
-  --rpc wss://...          Bulletin RPC (or set BULLETIN_RPC env var)
-  --mnemonic "..."         DotNS owner mnemonic (or set MNEMONIC env var)
-  --derivation-path "..."  Substrate-style path applied to --mnemonic (e.g. //deploy/3).
-                           Use to select a sub-account of the given mnemonic — both the
-                           Bulletin direct signer and the DotNS registration signer then
-                           run as that derived account. Useful when running parallel
-                           deploys against the same root mnemonic without nonce contention.
-  --js-merkle              Use pure-JS merkleization (no IPFS Kubo binary required)
-  --pool-size N            Number of pool accounts (default: 10)
-  --tag "..."              Free-form label attached to the deploy span as deploy.tag
-                           (see Telemetry section). Use to isolate test/benchmark/canary
-                           runs from real-user traffic in Sentry dashboards. Also readable
-                           from DEPLOY_TAG env var.
-  --gh-pages-mirror        After a successful deploy, push the CAR to the current repo's
-                           gh-pages branch as a fast-path HTTP cache for host apps. Opt-in.
-                           See "GitHub Pages mirror" below.
-  --help                   Show help
-```
+| Flag | What it does |
+|---|---|
+| `--rpc wss://...` | Override the Bulletin RPC endpoint. Also readable from `BULLETIN_RPC`. |
+| `--mnemonic "..."` | Use a specific mnemonic as the direct signer for Bulletin uploads and DotNS updates. Also readable from `MNEMONIC`. |
+| `--derivation-path "..."` | Apply a Substrate derivation path to `--mnemonic`, for example `//deploy/3`. |
+| `--pool-size N` | Change the number of derived pool accounts available for pool-mode Bulletin uploads. Default: `10`. |
+| `--password "..."` | Encrypt SPA content before upload. Consumers must provide the password to decrypt it. |
+| `--js-merkle` | Use pure-JS merkleization instead of the Kubo binary. |
+| `--tag "..."` | Attach a free-form telemetry label. Also readable from `DEPLOY_TAG`. |
+| `--gh-pages-mirror` | After a successful deploy, push the generated CAR to the current repo's `gh-pages` branch as an HTTP mirror. |
+| `--version` | Print the CLI version. |
+| `--help` | Show help. |
 
-### GitHub Pages mirror (opt-in, experimental)
+## Concepts
 
-Loading a dapp via a smoldot light client is slow. As a short-term cache, `--gh-pages-mirror` pushes the CAR to the current repo's `gh-pages` branch so host apps (dot.li, desktop) can fetch it via HTTP while the chain path catches up.
+- `Bulletin`: the chain that stores the app payload in chunked transaction storage.
+- `.dot domain`: the DotNS name that points at the deployed content.
+- `CAR`: the content-addressed archive produced from your build output before upload.
+- `merkleization`: turning a directory into a content-addressed DAG and CAR file.
+- `pool accounts`: derived Bulletin uploader accounts used to spread nonce and authorization load.
+- `PoP`: Proof of Personhood, which some `.dot` names require before registration.
 
-```bash
-bulletin-deploy --gh-pages-mirror ./dist my-app.dot
-```
+## Domain Rules
 
-After the Bulletin upload + DotNS registration succeed, the CLI commits:
+DotNS classifies labels on-chain and may require a specific Proof of Personhood level before registration.
 
-```
-bulletin/my-app.dot.car     # the CAR, byte-for-byte identical to what's on Bulletin
-bulletin/my-app.dot.json    # {domain, cid, toolVersion, deployedAt, encrypted, bulletinRpc, sourceRepo, sourceCommit}
-```
+Typical cases:
+
+| Domain pattern | Typical classification |
+|---|---|
+| Base name, for example `my-app.dot` | `ProofOfPersonhoodFull` |
+| Name with trailing digits, for example `my-app00.dot` | often `NoStatus`, but not guaranteed |
 
-to `gh-pages` and pushes. The mirror URL is printed at the end of the deploy:
+Do not rely on the string shape alone. The on-chain classifier is authoritative.
 
-```
-Mirror: https://<owner>.github.io/<repo>/bulletin/my-app.dot.car
-```
+On testnets, `bulletin-deploy` self-grants PoP only when the classifier says it is needed. On mainnet, PoP cannot be self-granted.
 
-Requirements:
+## GitHub Pages Mirror
 
-- **GitHub Pages enabled** on the repo with `gh-pages` as the source branch (one-time, via repo Settings → Pages).
-- **Push permissions.** In CI, set `permissions: contents: write` on the workflow. Locally, your regular git credentials suffice.
-- **CAR ≤ 100 MB** (GitHub's single-file soft limit). Larger CARs are skipped with a log line; a Releases fallback for bigger CARs is a planned follow-up.
-- **Directory deploys only.** Pre-chunked `Array<Uint8Array>` / `Uint8Array` / single-file content doesn't produce a CAR and is skipped with a log line.
+`--gh-pages-mirror` is an opt-in cache path for hosts that want an HTTP fetch path in addition to Bulletin.
 
-Limitations / follow-ups:
+```bash
+bulletin-deploy ./dist my-app.dot --gh-pages-mirror
+```
 
-- **Discoverability is the caller's problem today.** The URL is printed at deploy time; host apps must be told which `<owner>/<repo>` to fetch from. A DotNS text record (or similar on-chain pointer) is the clean long-term answer and lives in a follow-up.
-- **Encrypted deploys mirror encrypted bytes.** `--password` deploys need the password to decrypt from the mirror too.
-- **Mirror failures are non-fatal.** The source of truth is Bulletin + DotNS; the mirror is a cache. Failures log and let the deploy succeed.
-- **GitHub Pages build latency.** The CAR lands on `gh-pages` immediately; Pages serves it after the build completes (~1–2 min in practice). Hosts should fall back to Bulletin while the 404 window lasts.
+After a successful deploy, the CLI pushes:
 
-## GitHub Actions
+- `bulletin/<domain>.dot.car`
+- `bulletin/<domain>.dot.json`
 
-1. Copy `workflows/deploy-on-pr.yml` to your repo's `.github/workflows/` directory
-2. Customize the **Build** step for your framework (Vite, Next.js, etc.)
-3. Push and watch the deploy
+to the current repo's `gh-pages` branch and prints the Pages URL.
 
-The template workflow:
-- Deploys on push to main and on PRs
-- Uses `nick-fields/retry@v3` for automatic retries on transient failures
-- Posts a comment on PRs with the live URL
-- Generates domain names as `<repo>-<branch>00.dot`
+Use it when you want to validate or consume the mirror feature. The source of truth remains Bulletin plus DotNS.
 
 ## Programmatic API
 
-```javascript
-import { deploy, DotNS } from "bulletin-deploy";
+```js
+import { deploy } from "bulletin-deploy";
 
 const result = await deploy("./dist", "my-app00.dot");
 console.log(result.cid, result.domainName);
 ```
 
-### JS merkleization and custom telemetry
-
-For environments without Kubo (WebContainers, serverless), use `jsMerkle`. The optional `attributes` field lets you inject telemetry context when git is unavailable:
+For environments without Kubo:
 
-```javascript
-const result = await deploy("./dist", "my-app00.dot", {
-  jsMerkle: true,
-  attributes: {
-    "deploy.source": "revx",
-    "deploy.repo": "user/project",
-  },
-});
+```js
+await deploy("./dist", "my-app00.dot", { jsMerkle: true });
 ```
 
-## Domain Names and Proof of Personhood
-
-DotNS domain names are classified by the PopOracle contract on Asset Hub. The classification determines what level of **Proof of Personhood (PoP)** is required to register. PopOracle is the authoritative source — query `POP_RULES.classifyName(label)` on chain for any name. As a rough guide:
-
-| Domain pattern | Typical classification |
-|---|---|
-| Base name (no trailing digits) — e.g. `my-app.dot` | `ProofOfPersonhoodFull` required |
-| Name with trailing digits — e.g. `my-app00.dot` | Usually `NoStatus` (open to all), **but see caveat below** |
-
-**Caveat — the classifier is non-obvious.** Two names that both end in trailing digits can land in different buckets. Observed examples on Paseo: `rc069pool00` classifies as `NoStatus`, `rc069dir00` classifies as `ProofOfPersonhoodLite`. The safe approach is to let `POP_RULES.classifyName` tell you — don't assume from the string.
-
-### Self-grant on testnets
-
-`bulletin-deploy` self-grants PoP before registration **only when the classifier says it's needed**. Specifically, when `classifyName(label)` returns something other than `NoStatus`, the tool calls `setUserPopStatus(requiredLevel)` so the signer matches the requirement. If the classifier returns `NoStatus`, no self-grant happens and the signer's current status is used as-is.
-
-On **mainnet** (Polkadot Hub, Kusama Hub), PoP cannot be self-granted (the contract enforces verification). You must have a verified account. Set `DOTNS_STATUS=none` explicitly or leave it unset.
-
-You can force a specific self-grant level on any network with `DOTNS_STATUS=full|lite|none`. See `tools/check-pop-status.mjs` to query an address's current status.
-
-If you see **"Requires Full Personhood verification"**, the deploy will fail early with an actionable error message before any gas is spent on commitment transactions.
-
 ## Environment Variables
 
 | Variable | Default | Description |
 |---|---|---|
 | `BULLETIN_RPC` | `wss://paseo-bulletin-rpc.polkadot.io` | Bulletin chain WebSocket RPC |
-| `BULLETIN_DEPLOY_TELEMETRY` | _(off for external users, on for internal)_ | `1` to opt in, `0` to force off — see **Telemetry** below |
-| `BULLETIN_DEPLOY_UPDATE_CHECK` | `1` (enabled) | Set to `0` to disable version check on errors |
-| `DOTNS_STATUS` | `full` (testnet) / `none` (mainnet) | PoP level to self-grant before registration: `none`, `lite`, or `full` |
-| `IPFS_CID` | _(none)_ | Skip storage, use pre-existing CID |
-
-## How It Works
-
-```
-Build output ──> Merkleize ──> CAR file ──> Chunk upload ──> DotNS
-    ./dist       (Kubo or JS)   .car         Bulletin        Asset Hub
-                                             Storage         Registry
-```
-
-1. **Merkleize** your build directory to produce a content-addressed CAR file
-2. **Chunk and upload** the CAR file to Bulletin's TransactionStorage (1MB chunks, 2 per batch)
-3. **Store the DAG root** that links all chunks together under a single CID
-4. **Register or update** your `.dot` domain on Asset Hub with the new contenthash
-
-Your site is immediately accessible at `https://your-domain.dot.li`
-
-## Merkleization modes
-
-bulletin-deploy supports two ways to merkleize your build directory into a CAR file:
-
-| Mode | Flag | Requires | Best for |
-|---|---|---|---|
-| **Kubo** (default) | _(none)_ | IPFS Kubo binary installed | CI pipelines, local development |
-| **JS** | `--js-merkle` | Nothing beyond Node.js | WebContainers, serverless, environments without system binaries |
-
-Both modes produce valid IPFS UnixFS DAGs. The CIDs may differ between modes for the same input (different chunking implementations), but this is fine — each deploy sets a fresh contenthash on DotNS regardless.
-
-### CLI
-
-```bash
-# Default (Kubo)
-bulletin-deploy ./dist my-app00.dot
-
-# JS merkleization
-bulletin-deploy --js-merkle ./dist my-app00.dot
-```
-
-### Programmatic
-
-```javascript
-import { deploy } from "bulletin-deploy";
-
-// Default (Kubo)
-await deploy("./dist", "my-app00.dot");
-
-// JS merkleization
-await deploy("./dist", "my-app00.dot", { jsMerkle: true });
-```
-
-The JS mode uses `ipfs-unixfs-importer` (the same chunker Kubo uses internally) and `@ipld/car` for CAR serialization. It runs entirely in-memory with no temp files.
-
-## Resilience Features
-
-### Chunk-level retry
-
-Each batch of chunks is submitted with `Promise.allSettled`. Failed chunks are retried up to 3 times with a fresh nonce, serialized to avoid nonce conflicts. If a chunk fails all retries, the deploy aborts with a clear error.
-
-### Account pool
-
-Instead of using a single account for all storage transactions, bulletin-deploy derives a pool of accounts from a mnemonic. Each deploy selects the account with the most remaining authorization capacity. This prevents nonce conflicts between concurrent deploys and distributes the storage authorization budget.
-
-### Auto-authorization
-
-When a pool account's authorization drops below thresholds (50 transactions or 50MB), bulletin-deploy automatically tops it up by submitting an `authorize_account` transaction from Alice.
-
-## Version Checking
-
-When a deploy fails, bulletin-deploy checks whether a newer version is available. This helps catch cases where the error was already fixed in a later release.
-
-Two sources are checked in parallel:
-- **npm registry** — reads the `minimumVersion` field from the latest published version
-- **GitHub kill switch** (`min-version.json` in the repo) — allows emergency deprecation without a release
-
-If either source indicates your version is below the minimum, the CLI tells you the version is unsupported and why. If you're simply outdated (but above the minimum), you get a suggestion to update.
-
-For **paritytech** contributors in an interactive terminal, the CLI offers to update and retry automatically. For everyone else (external users, CI), it prints the update command and exits.
-
-If you're already on the latest version and hit an error, the CLI offers to open a GitHub issue with collected debug info (paritytech contributors only).
-
-Set `BULLETIN_DEPLOY_UPDATE_CHECK=0` to disable version checking.
-
-## Telemetry
-
-Sentry telemetry is **off by default for external users**. It's automatically on for deploys originating from inside Parity — either Parity CI, or local development trees whose git origin points at `paritytech/*`, `w3f/*`, or `polkadot-fellows/*`.
-
-- `BULLETIN_DEPLOY_TELEMETRY=1` — explicit opt-in (useful if you want to help us debug an issue you're seeing).
-- `BULLETIN_DEPLOY_TELEMETRY=0` — force off regardless of context.
-- When running under **Bun**, the Parity-internal memory-report diagnostic bundle is skipped (basic deploy telemetry still works). The bundle relies on Node's `v8` module, which Bun implements only partially.
-
-Detection signals (OR'd together):
-1. `GITHUB_REPOSITORY` matches a known-internal org — Parity-owned CI workflow.
-2. `RUNNER_NAME` starts with `parity-` — Parity self-hosted runner.
-3. `git remote get-url origin` points at a known-internal org — internal local dev.
-
-What's tracked:
-- Deploy duration and success/failure
-- Storage phase timing (merkleize, chunk upload, root node)
-- DotNS phase timing (registration, contenthash update)
-- Pool account selection
-- Source metadata (repo, branch, PR number, CI vs local)
-- Tool version (`deploy.tool_version`)
-
-### Using bulletin-deploy as a library under your own Sentry
-
-If your tool embeds bulletin-deploy as a library and already runs its own Sentry SDK (for example, Parity's `playground-cli`), you can route bulletin-deploy's deploy spans, tags, and diagnostics through your existing Sentry client rather than clobbering it with ours. Set two env vars **before** importing or invoking bulletin-deploy:
-
-```sh
-BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1
-BULLETIN_DEPLOY_HOST_APP=<your-app-name>
-```
-
-What happens:
-
-- `BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1` makes `initTelemetry()` skip its own `Sentry.init()` call. bulletin-deploy reuses the global Sentry client your app already configured. All deploy spans, breadcrumbs, `captureWarning`/`captureMessage` calls route to your DSN.
-- `BULLETIN_DEPLOY_HOST_APP=<name>` attaches `deploy.host_app: <name>` to every deploy span **and** as a Sentry scope tag, so downstream events in the same process carry it too. Use it to facet dashboards by host.
-
-**Requirements:**
-
-- Your app must call its own `Sentry.init()` **before** importing or spawning bulletin-deploy; otherwise there is no ambient client to reuse and telemetry is effectively off.
-- Your Sentry project should live in the same Sentry organisation as `bulletin-deploy` (`o4511059872841728.ingest.de.sentry.io`) if you want our cross-project dashboards to aggregate your traffic. Different org = different world; no cross-aggregation is possible.
-- If your consumer app is maintained by Parity, we can add its name to the `PARITY_HOST_APPS` allowlist in `src/telemetry.ts` so end-user installs of the compiled binary qualify for the same diagnostics as our internal CI. Today: `playground-cli`.
-
-**Gotchas:**
-
-- Quotas are per-project. A traffic spike in your project will eat your quota and can drop bulletin-deploy spans routing through it without any signal in our dashboards.
-- Issue-feed fingerprints don't dedupe across projects: the same error in your project and ours surfaces as two separate Sentry issues.
-- `@sentry/node` major version must be compatible with ours (currently v8.x). Skew risks runtime errors on the first span call.
-
-### Tagging test and benchmark runs
-
-Real-user deploys and automated test/benchmark deploys share the same telemetry pipeline. Use `--tag` (or the `DEPLOY_TAG` env var) to label non-production runs so Sentry dashboards can filter them out:
-
-```bash
-bulletin-deploy --tag e2e-ci-pr ./build my-app.dot
-DEPLOY_TAG=load-test bulletin-deploy ./build my-app.dot
-```
-
-The `tag` value is attached to the deploy span as `deploy.tag` (plus propagated through every child span).
-
-Convention used in this repo:
-- `e2e-ci-pr` / `e2e-ci-nightly` — CI-driven E2E runs (per-PR and nightly matrices).
-- `e2e-local-smoke` / `e2e-local-pr` / `e2e-local-nightly` — maintainer-invoked E2E via `scripts/e2e-pass.sh`.
-- Untagged — real-user deploys.
-
-Sentry filter examples:
-- Exclude all test traffic from a dashboard: `!has:deploy.tag`
-- Only CI E2E: `deploy.tag:e2e-ci-*`
-- Only nightly runs (local or CI): `deploy.tag:e2e-ci-nightly OR deploy.tag:e2e-local-nightly`
-
-The shipped reusable workflow (`.github/workflows/deploy.yml`) exposes a `tag` input that feeds through to the CLI — pass it from caller workflows that do non-production deploys.
-
-Dashboards:
-- **Bulletin Deploy Health**: https://paritytech.sentry.io/dashboard/1669817/?project=4511093597405264 — overall deploy health across all consumer repos
-- **Deploy Failures Detail**: https://paritytech.sentry.io/dashboard/1669818/?project=4511093597405264 — error drill-down
-- **E2E Health (bulletin-deploy)**: https://paritytech.sentry.io/dashboard/1732713/?project=4511093597405264 — E2E suite pass rate, duration, and per-signer failure distribution (filtered by `deploy.tag:e2e-*`)
-
-## Testing
-
-Three layers of coverage: offline unit tests for pure helpers, live-testnet end-to-end tests that exercise the shipped reusable workflow, and CI matrices that run both per-PR and nightly.
-
-### Offline unit tests
-
-```bash
-npm test
-```
-
-Runs `test/test.js` + `test/pool.test.js` + `test/helpers/e2e-helpers.test.js` via `node --test`. No network. ~5 seconds. Always runs on every PR via GitHub Actions.
-
-### Live-testnet E2E
-
-Four scenarios land on Paseo Bulletin:
-
-- **S1** — happy path on a stable label (`e2epool.dot` / `e2edirect.dot`)
-- **S2** — fresh registration via commit-reveal (nightly only)
-- **S3** — deploy to `e2eowned.dot` (owned by a different account), expects `EXIT_CODE_NO_RETRY` (78) and the "owned by a different account" error message
-- **S4** — deploy with `--gh-pages-mirror`, waits for GitHub Pages to serve the just-pushed manifest (CID-freshness check), then byte-compares the CAR on Pages against a pre-upload dump to confirm the mirror is an exact copy of what went to Bulletin
-
-**Prerequisites** (one-time per testnet lifetime): see [`docs/e2e-bootstrap.md`](docs/e2e-bootstrap.md). Grants Alice PoP Full, funds+maps Bob, pre-registers `e2eowned.dot` to Bob via `dotns-cli`. S4 additionally needs GitHub Pages enabled on the repo with `gh-pages` as the source branch and a token with `contents: write` (the workflow's `GITHUB_TOKEN` provides this; locally your git credentials must be able to push).
-
-**Local launchers:**
-
-```bash
-npm run test:e2e:smoke      # 1 scenario  (S1 pool/js)           ~5 min
-npm run test:e2e:pr         # 4 scenarios (matches per-PR CI)    ~20 min
-npm run test:e2e:nightly    # 8 scenarios (matches nightly CI)   ~30–45 min
-```
-
-All three run through to completion even if one fails; a colored summary prints at the end with per-scenario pass/fail, timing, JUnit report paths, and a pre-filtered Sentry trace link.
-
-**Agent-friendly / quiet mode** — `E2E_QUIET=1` suppresses the live streaming output (`node:test` spec reporter + bulletin-deploy stdio + build logs) while still printing the summary and writing structured reports. Works with every mode:
-
-```bash
-E2E_QUIET=1 npm run test:e2e:smoke
-E2E_QUIET=1 npm run test:e2e:pr
-E2E_QUIET=1 npm run test:e2e:nightly
-```
-
-Equivalent flag form: `bash scripts/e2e-pass.sh --quiet <mode>`.
-
-**JUnit reports** — every scenario writes one to `e2e-reports/<scenario>-<signer>-<merkle>.xml` regardless of quiet mode. Consume via any JUnit-compatible tool, or just `cat` the XML — `<failure>` blocks carry the assertion message and stack.
-
-### CI matrices (`.github/workflows/e2e.yml`)
-
-The CI workflow **calls the shipped reusable `.github/workflows/deploy.yml`** for every scenario — so each E2E job runs exactly the code path real consumers hit. Per-PR tests HEAD via `bulletin-deploy-version: "git+https://...#<sha>"` (the `prepare` npm script builds `dist/` during install). Nightly leaves the version empty so it tests the latest published release.
-
-- **Per-PR** (3 jobs): on `pull_request` and `push` to `main`. S1 pool/js + S1 direct/kubo + S3 negative. Posts a sticky comment on the PR with results and updates in place on re-runs.
-- **Nightly** (11 jobs): scheduled `0 3 * * *` UTC. Full S1 signer×merkle×runner cube + S2 pool/direct fresh-registration + S3. Failures auto-open a GitHub issue.
-
-Every deploy job passes `tag: e2e-ci-pr` or `tag: e2e-ci-nightly` through to the CLI, so the E2E traffic is tagged in Sentry and can be filtered out of real-user dashboards (see Telemetry → Tagging test and benchmark runs above).
-
-### Tag convention in this repo
-
-| Trigger | `deploy.tag` |
-|---|---|
-| `npm run test:e2e:smoke` | `e2e-local-smoke` |
-| `npm run test:e2e:pr` | `e2e-local-pr` |
-| `npm run test:e2e:nightly` | `e2e-local-nightly` |
-| E2E workflow per-PR | `e2e-ci-pr` |
-| E2E workflow nightly | `e2e-ci-nightly` |
-| Real-user deploys | _none_ (`!has:deploy.tag`) |
+| `BULLETIN_DEPLOY_TELEMETRY` | off for external users, on for internal users | `1` to opt in, `0` to force off |
+| `BULLETIN_DEPLOY_UPDATE_CHECK` | `1` | Set to `0` to disable version checks on failure |
+| `DOTNS_STATUS` | `full` on testnet, `none` on mainnet | PoP level to self-grant before registration: `none`, `lite`, or `full` |
+| `IPFS_CID` | unset | Skip storage and reuse an existing CID |
+| `DEPLOY_TAG` | unset | Telemetry label equivalent to `--tag` |
 
 ## Troubleshooting
 
-| Error | Solution |
+| Error | What to check |
 |---|---|
-| `Requires Full Personhood verification` | Auto-handled on testnets (v0.5.4+). On mainnet, your account needs verified PoP status. |
-| `Payment` or authorization error | Pool account needs storage authorization — auto-authorization should handle this |
-| `Stale` or dropped from best chain | Bulletin chain reorg. Automatic retry handles this. |
-| `IPFS CLI not installed` | Install Kubo: `brew install ipfs && ipfs init` |
-| `CommitmentNotFound` | DotNS timing issue during registration. Retry the deploy. |
-| `All pool accounts exhausted` | Auto-authorization will top up the best available account |
-| `fetchNonce timed out` | Bulletin RPC may be down. Check endpoint or try a different one. |
-
-## Configuration for Different Chains
-
-By default, bulletin-deploy targets the **Paseo testnet**:
-- Bulletin: `wss://paseo-bulletin-rpc.polkadot.io`
-- Asset Hub: `wss://asset-hub-paseo.dotters.network`
-
-To point at a different chain, set the `BULLETIN_RPC` environment variable:
-
-```bash
-BULLETIN_RPC=wss://your-bulletin-rpc.example.com bulletin-deploy ./dist my-app00.dot
-```
+| `Requires Full Personhood verification` | The chosen label needs a higher PoP level. |
+| `Domain ... is owned by a different account` | The `.dot` name is already owned by the account indicated. Use that account as parameter or transfer the domain from that account to the new account you want to use |
+| `Account ... is not authorized for Bulletin storage` | The uploader account is not authorized on Bulletin yet. For operator-managed pools, see [`bulletin-bootstrap`](docs/bootstrap.md). |
+| `fetchNonce timed out` or connection errors | The Bulletin RPC may be unhealthy. Try another endpoint. |
+| `IPFS CLI not installed` | Install Kubo or switch to `--js-merkle`. |
+| Previous deploy did not exit cleanly / OOM hint | Retry with a larger Node heap, for example `NODE_OPTIONS='--max-old-space-size=8192'`. |
+
+## More Docs
+
+- [Bootstrap and operator setup](docs/bootstrap.md)
+- [Testing](docs/testing.md)
+- [Telemetry](docs/telemetry.md)
+- [E2E one-time setup](docs/e2e-bootstrap.md)

package/bin/bulletin-bootstrap

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { DEFAULT_BULLETIN_RPC, DEFAULT_POOL_SIZE } from "../dist/deploy.js";
+import { bootstrapPool } from "../dist/pool.js";
+import { VERSION } from "../dist/telemetry.js";
+
+const args = process.argv.slice(2);
+
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--pool-size") { flags.poolSize = parseInt(args[++i], 10); }
+  else if (args[i] === "--mnemonic") { flags.mnemonic = args[++i]; }
+  else if (args[i] === "--rpc") { flags.rpc = args[++i]; }
+  else if (args[i] === "--version" || args[i] === "-V") { flags.version = true; }
+  else if (args[i] === "--help" || args[i] === "-h") { flags.help = true; }
+  else {
+    console.error(`Error: unknown argument ${args[i]}`);
+    process.exit(1);
+  }
+}
+
+if (flags.version) {
+  console.log(`bulletin-bootstrap v${VERSION}`);
+  process.exit(0);
+}
+
+if (flags.help) {
+  console.log(`bulletin-bootstrap v${VERSION}
+
+Usage:
+  bulletin-bootstrap
+
+Options:
+  --mnemonic "..."  Pool root mnemonic (or set BULLETIN_POOL_MNEMONIC / MNEMONIC env var)
+  --rpc wss://...   Bulletin RPC (or set BULLETIN_RPC env var)
+  --pool-size N     Number of pool accounts to initialize (default: 10)
+  --version         Show version
+  --help            Show this help
+
+Initialize pool accounts for Bulletin storage authorization.`);
+  process.exit(0);
+}
+
+const rpc = flags.rpc ?? process.env.BULLETIN_RPC ?? DEFAULT_BULLETIN_RPC;
+const poolSize = flags.poolSize ?? parseInt(process.env.BULLETIN_POOL_SIZE ?? String(DEFAULT_POOL_SIZE), 10);
+const mnemonic = flags.mnemonic ?? process.env.BULLETIN_POOL_MNEMONIC ?? process.env.MNEMONIC;
+
+await bootstrapPool(rpc, poolSize, mnemonic);