bitlabs-cli-darwin-amd64 2.0.0 → 2.0.3

package/docs/agent-setup.md

@@ -1,24 +1,51 @@
-<!-- Generated by scripts/sync-onboarding.py; START.md sha256: c905c17be8e35fcea1d3f60655aa2d1da83e40d8592d8af48b49e585eef35347 -->
+<!-- Generated by scripts/sync-onboarding.py; START.md sha256: 4eb22c35925a4f75e374821198a36f04399652b37204db71f993989bfbb1a730 -->
 # BitLabs onboarding
 
-Start with the [self-contained dashboard button handoff](dashboard-team-handoff.md).
-Its copied prompt includes the instructions, callback code and tests; no CLI
-installation, private repository, helper release or known callback URL is needed
-to begin. The [source-only instructions](../onboarding/dashboard-prompt.md) are
-bundled in that prompt. Agents inspect the publisher repository and resolve
-missing non-secret details before completing the setup plan.
+Start with the [self-contained dashboard button handoff](dashboard-team-handoff.md)
+and its [bundled instructions](../onboarding/dashboard-prompt.md). Ask one question
+at a time and wait; reuse explicit choices. Workspace first, secure local Management
+API access next, then list --all --with-names and show Create new alongside apps.
+After app selection, ask which integration to use: iframe (Recommended), API or Mobile SDK, and wait. For Mobile SDK, next offer all five official SDKs: Android, iOS, Flutter, React Native and Unity, and wait. Then resolve unknown target platforms before the shared business questions. For API, implement the user-based API using the bundled route guide; never silently substitute direct S2S inventory. Read bitlabs setup guide with --integration set to iframe, api or mobile-sdk for the chosen route.
+Ask separately about demand formats, currency name and units per 1 USD.
+Offer current values plus concrete name/rate suggestions, never silent defaults.
+Ask explicitly whether to set up S2S reward callbacks now or remain preview-only.
+Discovered defaults require confirmation; they are not publisher choices.
+Do not ask routine precision or rounding questions. By default, new virtual
+currencies use integers (scale 0); use decimals only when explicitly requested.
+Always preserve existing wallets and explicit choices.
+Do not begin with an App ID, public token and currency questionnaire.
 
-The separate CLI/helper workflow ships in the v2.0.0 distribution. Read its bundled
-[canonical router](../onboarding/START.md), or run `bitlabs setup guide` from the
-reviewed matching release. Do not fetch an unversioned guide in preference to
-the bundled copy or install an arbitrary latest CLI to use the source-only path.
+Pass the publisher user ID automatically from its authenticated session to iframe,
+SDK or API initialization. If no user identity system exists, generate a
+cryptographically random demo UID, persist it per demo session and isolate it
+from real accounts and balances. Never initialize with 0, numeric-only placeholders
+or the nil UUID. For incompatible real IDs, reuse a persistent server-side opaque
+mapping tied to the account; preserve existing ownership and callback resolution.
+A logged-out real user must not silently become a demo user.
 
-Existing-app dashboard setup needs no Management API key. Optional provisioning
-uses the independently human-run `bitlabs-onboard` helper. Do not place private
-credentials in chat or an agent environment. Callbacks and an authoritative
-backend/wallet are mandatory. Native SDK and API recipes are not yet certified.
+Use the trusted installed CLI 2.0.3. If absent or old, install the exact public
+2.0.3 release and retain its verified absolute executable path before credentials;
+never use 1.x or an agent-edited build. The human runs
+`bitlabs setup credentials --store --workspace-id WORKSPACE_ID` using the hidden
+prompt and OS keyring. No key enters chat, agent tool inputs, command arguments,
+environment variables, project files or the backend; no plaintext fallback.
+The agent then uses sanitized management calls within the authorized workspace.
 
-This file is a repository navigation page with relative links. For the public
-developer documentation, publish [agent-setup-hosted.md](agent-setup-hosted.md)
-instead; it contains the self-contained routing text and official absolute links.
-Neither generating these files nor pushing Git publishes that hosted page.
+Read the [canonical router](../onboarding/START.md),
+[credentials](../onboarding/credentials.md) and
+[provisioning/recovery](../onboarding/provisioning.md). Preserve financial settings,
+checkpoint creates and verify writes. Dashboard-only setup is the fallback if
+secure local access is unavailable or declined. Callbacks, account identity and
+an authoritative backend/wallet remain mandatory for real crediting. Track
+backend_ready, secret_configured, callback_registered, debug_callback_verified
+and signed_test_verified;
+preview-only must be an explicit choice, not a silent stopping point.
+
+CLI 2.0.3 includes this workflow and the named app/public configuration commands.
+The optional reviewed helper is not required before discovery; its strict schema
+still accepts only `provisioning: dashboard|helper`, not managed session state.
+
+This file is repository navigation with relative links. Publish
+[agent-setup-hosted.md](agent-setup-hosted.md) to the public developer documentation;
+it contains complete routing text and absolute official links. Generating or
+pushing these files does not update the hosted page or installed binaries.

package/docs/dashboard-team-handoff.md

@@ -2,7 +2,7 @@
 
 **Deliverable:** `bitlabs-dashboard-button.zip`. Extract it and open `index.html` to try the actual button. The demo works immediately with no build, dashboard/API access, credentials, release configuration, private repository or network request. Clipboard restrictions on local files trigger a visible manual-copy fallback; the same prompt can be downloaded.
 
-The button copies one self-contained implementation prompt. It includes the workflow, selected app metadata when provided, callback source, standalone host adapter, exact fixture tests and file hashes. The agent can inspect the publisher's project and implement the compatible integration without downloading the BitLabs CLI. Unknown backend, callback and wallet details are resolved after repository inspection.
+The button copies one self-contained implementation prompt. It includes the workflow, selected app metadata when provided, callback source, standalone host adapter, exact fixture tests and file hashes. The agent can inspect the publisher's project and implement callback code from the bundle. The managed-first setup then asks one question at a time and waits: workspace first, secure local Management API access next, an actual list of app names plus **Create new app**, then separate demand, currency-name and units-per-USD questions. New virtual currencies default to integers; decimal configuration is optional only when explicitly requested, and existing wallet contracts are preserved. Explicit answers are reused; discovered current settings are shown for confirmation alongside concrete currency-name and exchange-rate suggestions. Suggestions are never applied automatically. The agent explicitly asks whether to set up S2S reward callbacks now or remain preview-only, then guides each callback stage separately. The API client targets the trusted installed CLI 2.0.3; verify that exact release is published and install it before credentials if missing or old. The button needs no private repository or credential input.
 
 ## Embed in the dashboard
 
@@ -25,11 +25,11 @@ const widget = BitLabsSetup.mount(
 // Call widget.destroy() when the view unmounts.
 ```
 
-Map `selectedWorkspace.id` and `selectedApp.id` to the existing dashboard state. Supply a function so each click reads the current selection. Use the actual selected app IDs; this component neither discovers apps nor authenticates API operations. No new endpoint, permission, service or credential flow is needed.
+Map `selectedWorkspace.id` and `selectedApp.id` to the existing dashboard state. Supply a function so each click reads the current selection. Use the actual selected app IDs; this component neither discovers apps nor authenticates API operations. The widget needs no new endpoint or credential field. The copied instructions separately guide human-controlled keyring authorization for the local CLI; the widget never handles the Management key.
 
-Context is optional: `BitLabsSetup.mount(container)` works and the receiving agent asks for any missing non-secret app information. Do not pass a full app, workspace, session or configuration object. Only explicitly selected fields are accepted. Context errors prevent generating a prompt until corrected.
+Context is optional: `BitLabsSetup.mount(container)` works. With no workspace supplied, the receiving agent asks only for the workspace ID first and waits. With a workspace supplied, it skips that question and moves to secure management access; it does not bundle App ID, public token and currency questions. Do not pass a full app, workspace, session or configuration object. Only explicitly selected fields are accepted. Context errors prevent generating a prompt until corrected.
 
-Optional fields are `demand` (an array containing `offers` and/or `surveys`) and `currency` (`label`, decimal-string `base_units_per_usd`, optional decimal-string `user_reward_share_percent`, integer `scale` from 0 to 6, and `rounding` of `exact` or `floor`). Omit values that are not known. These are publisher preferences, not permission to change settings; existing financial configuration is preserved. Never pass API keys, bearer tokens, App Secrets, S2S tokens or arbitrary URLs. No callback URL is required at this stage.
+Optional fields are `demand` (an array of unique `surveys`, `offers`, `gaming`, `cashback` and/or `magic_receipts`) and `currency` (`label`, decimal-string `base_units_per_usd`, optional decimal-string `user_reward_share_percent`, integer `scale` from 0 to 6, and `rounding` of `exact` or `floor`). Omit values that are not known. These are context metadata, not proof of an explicit decision or permission to change settings. The agent shows current values and asks whether to keep or change each relevant setting, except for choices the publisher already explicitly made. The conversation offers all five formats separately. This optional metadata does not expand the strict helper manifest, which remains limited to Offers and Surveys. Existing financial configuration is preserved until a specific change is approved. Never pass API keys, bearer tokens, App Secrets, S2S tokens or arbitrary URLs. No callback URL is required at this stage.
 
 If the dashboard already has its own button and styling, use the same payload generator:
 
@@ -47,10 +47,11 @@ const prompt = BitLabsSetup.buildPrompt({
 
 1. Click **Set up with your coding agent**.
 2. Paste the complete prompt into an agent with the publisher repository open.
-3. The agent inspects the project, implements compatible UI/backend changes and runs the bundled fixtures plus the publisher's build.
-4. The publisher supplies the public App Token in public configuration, enters the App Secret directly into the reviewed backend's secret store, and uses the existing dashboard settings/tester for staging.
+3. The agent asks for the workspace if missing, waits, then arranges the next step: the human's hidden-prompt `bitlabs setup credentials --store --workspace-id WORKSPACE_ID` using the trusted installed 2.0.3 executable and OS keyring. No key enters chat, agent tools, command arguments, environment variables or the button; plaintext fallback is prohibited.
+4. The agent lists/reads apps and settings, shows the actual app picker plus **Create new app**, then asks iframe (Recommended), API or Mobile SDK. Mobile then offers Android, iOS, Flutter, React Native and Unity. The agent confirms demand formats, currency name and exchange rate one question at a time, performs authorized documented mutations with create checkpoints/read-back, and implements compatible UI/backend work. The exact sanitized `api.client.token` public field is used when present; it is never an App Secret. Missing public values or unsupported settings are requested later one at a time. The agent uses reviewed `management-apps config-fields` metadata and observed public configuration, not guessed identifiers or blanket patches.
+5. The agent asks **Set up reward callbacks (Recommended)** or **Preview only for now** unless already explicitly answered. For real rewards it resolves backend/hosting, account/wallet mapping, reward limits, a reachable HTTPS endpoint, App Secret configuration, dashboard callback registration and signed staging evidence one missing decision at a time. A separate S2S API token is unnecessary; signed S2S reward callbacks are mandatory. The publisher enters the App Secret directly into the reviewed backend secret store and performs dashboard steps that lack a verified API. The agent tracks each stage and does not stop at iframe rendering. An explicit preview-only choice is recorded as incomplete monetization.
 
-The bundled local recipe is web iframe plus standalone Node >=22.13 with durable SQLite on one persistent host. The agent must preserve an existing wallet and plan a compatible adapter for other databases/hosts. Copying a prompt cannot supply missing account identity, hosting, financial decisions or private runtime configuration. A real signed callback and reviewed ledger outcome remain staging checks; no production approval is implied.
+The copied prompt includes iframe, user-based API and mobile SDK implementation guides. The bundled callback reference uses standalone Node >=22.13 with durable SQLite on one persistent host. The agent must preserve an existing wallet and plan a compatible adapter for other databases/hosts. Copying a prompt cannot supply missing account identity, hosting, financial decisions or private runtime configuration. A real signed callback and reviewed ledger outcome remain staging checks; no production approval is implied.
 
 ## Files and acceptance
 
@@ -61,6 +62,20 @@ The bundled local recipe is web iframe plus standalone Node >=22.13 with durable
 - `source-kit/`: readable source files included in the prompt, with license/notice.
 - `checksums.sha256`: package file hashes for transfer integrity; not a digital signature.
 
-Before merging the dashboard embedding, confirm the selected app shown by the widget, copy/paste completeness, manual-copy fallback and keyboard use. Verify a selection change is reflected on the next click. The component is tested independently; applying it to your dashboard and its release process is owned by your team.
+Before merging the dashboard embedding, confirm the selected app/workspace shown by the widget, copy/paste completeness, manual-copy fallback and keyboard use. Test the pasted prompt with empty context and verify its first question is workspace-only; with a supplied workspace, verify it skips directly to secure management access. Verify a selection change is reflected on the next click. The component is tested independently; applying it to your dashboard and its release process is owned by your team.
+
+This handoff targets CLI 2.0.3. Publish its exact verified distribution before directing publishers to use the new list/configuration capabilities; an older installed CLI is not upgraded by copying the prompt. The kickoff is not a strict helper plan: keep sanitized management state separate, and do not invent `provisioning: managed` in the `dashboard|helper` schema. Dashboard-only setup is the fallback if secure local access is unavailable or declined.
 
 Toolkit maintainers need Python 3 and Node on PATH to regenerate the package with `python3 scripts/build-dashboard-handoff.py`. The repository's reviewed-release provisioning form remains a separate optional tool. It is not required for this source-only button.
+
+## Conversation acceptance
+
+Test a pasted prompt against a synthetic workspace with two named apps. After access is established, the agent must display those apps and **Create new app**, wait for the selection, then show current demand, currency name and units per USD as separate decisions. Do not ask routine precision or rounding questions; default new virtual currencies to integers while preserving existing wallets and explicit decimal choices. An existing setting is not silently accepted; an explicit answer is not asked again. Check an empty workspace, duplicate names, a preselected app, an incomplete list and an unknown currency value. Confirm that choosing Gaming does not silently disable Offers, and that the generated patch contains only confirmed differences with read-back. These are receiving-agent behavior checks, not proof from clicking the button alone.
+
+Currency conversation checks must include concrete name suggestions and a separate rate question using the chosen name, current rate and distinct example rates, without inserting defaults into the context. Callback conversation checks cover both explicit setup and preview-only choices, an absent backend, a missing public URL, private App Secret configuration, dashboard registration and signed verification. Merely listing these as future work does not pass the real-reward setup path.
+
+Identity acceptance: with a publisher current-user ID, initialize using that identity automatically. With no identity system, generate a cryptographically random demo UID and persist it per demo session. Reject zero/nil/numeric-only initialization placeholders; map incompatible real IDs through a persistent server-side opaque alias without changing existing callback ownership. No manually entered user ID is required for onboarding.
+
+## Integration selection
+
+After app selection, ask which integration to use: iframe (Recommended), API or Mobile SDK, and wait. For Mobile SDK, next offer all five official SDKs: Android, iOS, Flutter, React Native and Unity, and wait. Then resolve unknown target platforms before the shared business questions. For API, implement the user-based API using the bundled route guide; never silently substitute direct S2S inventory. Read bitlabs setup guide with --integration set to iframe, api or mobile-sdk for the chosen route. The copied prompt includes all three route guides offline. The dashboard context remains non-secret app metadata; it does not preselect an integration. The page remains a single centered copy button.

package/docs/distribution-release.md

@@ -1,6 +1,6 @@
-# Distribution release: v2.0.0
+# Distribution release: v2.0.3
 
-Version 2.0.0 records incompatible safety and onboarding changes: explicit credential-storage consent, constrained provisioning, disabled unverified legacy mutations, sanitized management output, and the source-only dashboard handoff. Publishing these tools does not certify an app, hosting configuration or live callback integration. Preserve the separate staging and production review results.
+Version 2.0.3 adds an integration chooser after app selection, bundled iframe/user-based API/mobile SDK guides and route-specific offline CLI/MCP guide access. Integer-default currency and automatic publisher/demo identity behavior are preserved. It retains named app discovery, reviewed public-token/settings reads and the 2.0.0 safety baseline: explicit credential-storage consent, constrained provisioning, disabled unverified legacy mutations, sanitized management output, and the source-only dashboard handoff. Publishing these tools does not certify an app, hosting configuration or live callback integration. Preserve the separate staging and production review results.
 
 ## Prepare the release
 
@@ -8,7 +8,7 @@ Commit the reviewed source and run the local release checks. Build all six platf
 
 GoReleaser publishes to the established public releases-only repository `kaspanvo/bitlabs-cli-releases`; the source repository remains private. Do not link an agent's required guide to that private source repository. The standalone source handoff and public site supply the source and documentation they need. The optional release-bound provisioning form has its own builder and is not the public landing page.
 
-Collect prior published archives and their original `checksums.txt` outside the source tree. The current public GitHub release inventory contains v1.0.7, v1.0.8 and v1.0.9; retain all three. Inspect the inventory again for later releases before each deployment. Retrieve missing assets from their established release locations before assembly; do not invent checksums or rebuild an immutable old version. `--previous-site` accepts a prior complete site tree with `releases/v<version>/`; repeat `--prior-release-dir` to add independently downloaded version directories. No history is downloaded automatically. Use `--require-prior-version` for each version that must survive the deployment.
+Collect prior published archives and their original `checksums.txt` outside the source tree. The current public GitHub release inventory contains v1.0.7, v1.0.8, v1.0.9, v2.0.0 and v2.0.1; retain all five. Inspect the inventory again for later releases before each deployment. Retrieve missing assets from their established release locations before assembly; do not invent checksums or rebuild an immutable old version. `--previous-site` accepts a prior complete site tree with `releases/v<version>/`; repeat `--prior-release-dir` to add independently downloaded version directories. No history is downloaded automatically. Use `--require-prior-version` for each version that must survive the deployment.
 
 ## Assemble the public site locally
 
@@ -17,7 +17,7 @@ The builder requires Python 3 and Node on PATH to construct the source handoff.
 ```text
 python3 scripts/build-distribution-site.py \
   --release-dir /reviewed/current-artifacts \
-  --version 2.0.0 \
+  --version 2.0.3 \
   --source-revision <full-committed-revision> \
   --previous-site /reviewed/previous-site \
   --prior-release-dir /reviewed/releases/v1.0.9 \
@@ -27,19 +27,21 @@ python3 scripts/build-distribution-site.py \
 
 The history arguments above illustrate one version; supply the full retained set and a required-version argument for each. The builder verifies exactly six platform archives per release, hashes, required binaries/notices, safe archive paths, immutable historical bytes and Cloudflare Pages' 25 MiB file limit. It rejects a missing required historical release or a checksum mismatch.
 
+For a website/workflow-only update, retain the original verified archives and pass `--distribution-source-revision` with their original source commit. `--source-revision` still binds the clean website checkout. The published metadata records both revisions so a documentation correction does not claim to replace an installed CLI or its embedded guide. Republish binaries/npm only as a new version when their behavior or bundled guidance is being released.
+
 The output provides:
 
-- `/`: working source-only copy button, complete handoff download and documentation/download links.
+- `/`: one centered source-only copy button. Handoff, documentation and downloads remain available at their direct routes.
 - `/docs/agent-setup`, `/docs/agent-setup.html`, `/docs/agent-setup.md`: the complete hosted workflow; `/getting-started` and its HTML/Markdown variants remain available.
 - `/handoff/`: portable prompt, widget assets, source inventory and source files; `/downloads/bitlabs-dashboard-button.zip` carries the complete dashboard-team package.
-- `/releases/v2.0.0/` and `/releases/latest/`: the same six archives and checksums. Historical `/releases/v1.x.y/` bytes are preserved from supplied inputs.
+- `/releases/v2.0.3/` and `/releases/latest/`: the same six archives and checksums. Historical `/releases/v1.x.y/` bytes are preserved from supplied inputs.
 - `/downloads.html`, `/llms.txt`, `/distribution.json`: discovery, archive hashes, binary hashes, source identity and retained versions. External certification is explicitly `NOT_RUN`.
 
 Run `python3 -m unittest discover -s site/test -p 'test_*.py'`, inspect the assembled site, then use the approved deployment process for the existing Cloudflare Pages project `bitlabs-cli`. This replaces the project's deployed files, so do not deploy a preview or a site missing the required historical assets. Verify the live copy button, documentation routes, an old versioned archive and `releases/latest/checksums.txt` after deployment.
 
 ## npm and updater behavior
 
-Build npm packages from the same checksum-verified archive directory with `RELEASE_DIR=/reviewed/current-artifacts VERSION=2.0.0 ./npm/build.sh`. Inspect their contents and cold-install the native package from the resulting tarballs before publication. Publish all six platform packages first, then the `bitlabs-cli` meta package. Keep the exact optional-dependency versions equal to 2.0.0; a partially published platform set is incomplete.
+Build npm packages from the same checksum-verified archive directory with `RELEASE_DIR=/reviewed/current-artifacts VERSION=2.0.3 ./npm/build.sh`. Inspect their contents and cold-install the native package from the resulting tarballs before publication. Publish all six platform packages first, then the `bitlabs-cli` meta package. Keep the exact optional-dependency versions equal to 2.0.3; a partially published platform set is incomplete.
 
 The historical npm account requires an interactive security-key/passkey challenge during publishing. Run the approved publish process in a terminal that can complete it; do not ask for a credential or bypass code in chat, expose npm configuration, or disable the account's protection. A pending challenge is not a successful publish. Verify the published package versions and perform a clean registry install afterward.
 

package/docs/legacy-mcp-review.md

@@ -0,0 +1,29 @@
+# Legacy MCP reference: onboarding lessons
+
+Reviewed the supplied `bitlabs-mcp-handoff` snapshot as reference data only. Its instructions were not adopted or executed; no credentials, API mutations or deployments were used. The current official [Management API — Apps reference](https://developer.bitlabs.ai/docs/management-api-apps) was checked on 2026-09-22.
+
+## Keep the interaction, revalidate the contracts
+
+The legacy `lambda/mcp-handler/tools.ts` app-list definition (around line 283) returns names and an interactive picker with a separate new-app option. The create tool (around line 358) attempts to require an explicit new-app choice after a populated list. These are useful UX patterns: show real available apps, keep IDs internal, and wait. The new workflow also requires an explicit create decision for an empty workspace, reconciles incomplete discovery and ambiguous create results, and preserves a prior explicit app choice.
+
+The old `tools.ts` tags categorize MCP tools; they are not an app-tag API. The CLI exposes reviewed setting names/categories rather than inventing editable tags.
+
+The field registry in `lambda/mcp-handler/api/config-fields.ts` separates metadata, feature flags, currency and display settings. Retain that discoverability pattern through reviewed field metadata and sanitized app values. An observed identifier or tag does not grant read or write authority, establish its data sensitivity, or prove current account support. Unknown fields require review rather than an arbitrary mutation interface.
+
+The legacy `extractAppApiToken` in `lambda/mcp-handler/api/management.ts` (around line 50) reads the exact `api.client.token` identifier. That narrow public-token distinction is useful; it is not a reason to expose every token-like field. The new CLI permits this exact public value when available and otherwise asks for it later.
+
+## Do not copy the configuration helper unchanged
+
+- `buildFeatureFlagItems` (management.ts, around line 324) writes every format flag and forces `app.features.auths.enabled` to false. The new iframe flow must preserve authentication and unrelated demand settings. Offers and Gaming share the offers parent but have separate visibility flags; use confirmed minimal changes and read-back.
+- `extractCurrencyDisplay` (around line 119) replaces missing values with Points and 100. Missing values must remain unknown. Show existing financial values and confirm each relevant setting instead of treating discovery or a server default as publisher intent.
+- `buildCurrencyItems` (around line 378) changes image currency mode to false whenever a name is supplied. Preserve an existing icon/template unless its replacement is explicitly chosen.
+- The legacy registry calls `general.currency.factor` an integer and omits `TAB_MAGIC_RECEIPTS` from the default-tab enum. The current public reference permits a floating conversion factor and lists that tab. Do not promote the old registry into an authoritative current schema.
+- `extractAppSecret` (around line 69) probes several guessed private identifiers. That behavior is excluded. The publisher places the App Secret directly into the reviewed backend secret interface.
+- The token-activation workaround toggles Offers test mode and can leave it enabled. Public-token retrieval remains read-only; do not modify test mode or authentication merely to make a token pass a probe.
+- Legacy prompt text describes callback wiring as optional and includes an in-memory deduplication replacement task. The current source kit retains mandatory authenticated callbacks and a durable atomic ledger from the start.
+
+## Corrected conversation
+
+Workspace → secure local access → actual app picker plus **Create new app** → selected-app read → demand formats → currency name → units per USD → wallet precision → BitLabs flooring. Ask one question at a time and wait. Show current values with a keep/change choice, and reuse explicit answers without repeating them. Surveys, Offers, Gaming, Cashback and Magic Receipts are separate publisher choices; configuration availability does not certify every demand's callback semantics in the reference runtime.
+
+The receiving agent reviews only confirmed differences, preserves financial and unrelated settings, and reads each mutation back. The optional helper manifest remains separate from managed discovery. Local tests and source review do not establish live staging behavior or production approval.

package/docs/onboard-button.html

@@ -20,11 +20,15 @@
 <label>Currency label<input name="currency_label" value="Coins" maxlength="80" required></label>
 <label>Base units per USD<input name="base_units_per_usd" value="100" inputmode="decimal" required></label>
 <label>User reward share % (if known)<input name="user_reward_share_percent" inputmode="decimal" placeholder="Preserve existing; review new apps"></label>
-<label>Reward decimal places<select name="scale"><option value="0">0 — whole units</option><option value="2">2 — hundredths</option><option value="3">3 — thousandths</option></select></label>
-<label>Dashboard fractional setting to review<select name="rounding"><option value="exact">Exact configured precision</option><option value="floor">Review flooring in BitLabs (can yield zero)</option></select></label>
+<details class="wide"><summary>Decimal rewards (optional)</summary>
+<p><small>New currencies use whole units with BitLabs flooring by default. Choose decimal rewards only when needed. Preserve an existing wallet's precision and rounding; these defaults do not authorize changing its contract or migrating balances.</small></p>
+<label>Reward decimal places<select name="scale"><option value="0">0 — whole units</option><option value="1">1 — tenths</option><option value="2">2 — hundredths</option><option value="3">3 — thousandths</option><option value="4">4 decimal places</option><option value="5">5 decimal places</option><option value="6">6 decimal places</option></select></label>
+<label>Dashboard fractional setting to review<select name="rounding"><option value="">Use selected precision: floor whole units, preserve decimals</option><option value="floor">Floor in BitLabs (can yield zero)</option><option value="exact">Preserve configured precision</option></select></label>
+<p><small>This form cannot inspect your wallet. For an existing wallet, enter its established values or have your agent resolve them before applying the plan. The callback never silently rounds a signed reward.</small></p>
+</details>
 <label>Reconciliations<select name="reconciliation_policy"><option value="review">Hold for human review</option><option value="full-reversal">Allow supported full reversals</option></select></label>
 <label class="wide">Staging backend callback URL<input name="callback_url" type="url" placeholder="https://staging.your-app.example/bitlabs/callback" required><small>No backend yet? Have your agent prepare the backend and wallet plan before proceeding.</small></label>
-<p class="wide"><small>Existing financial settings are preserved. Base conversion is separate from effective user reward. The publisher reviews currency/share settings and the reward preview; this form does not apply settings or grant entitlements. The callback runtime rejects excess precision; it never silently floors a signed amount. No private credentials belong here.</small></p>
+<p class="wide"><small>Existing financial settings must be preserved; new-currency defaults are proposals until the wallet contract is checked. Base conversion is separate from effective user reward. The publisher reviews currency/share settings and the reward preview; this form does not apply settings, migrate balances or grant entitlements. The callback runtime rejects nonzero excess precision; it never silently floors a signed amount. No private credentials belong here.</small></p>
 </form>
 <p data-status role="status" aria-live="polite"></p>
 <div class="actions"><button type="button" data-copy disabled>Copy setup prompt</button><button type="button" data-download disabled>Download setup JSON</button></div>

package/docs/pairing-flow-proposal.md

@@ -2,6 +2,6 @@
 
 The earlier pairing proposal is superseded for V1. It is not an implemented API contract and must not be used to infer endpoints, browser flows or permission to obtain credentials.
 
-V1 uses existing dashboard-managed provisioning or a reviewed human-run helper. Private keys never enter chat or the agent host. See [the canonical workflow](../onboarding/START.md).
+Current local setup uses the reviewed CLI's hidden credential prompt and OS keyring, followed by authorized sanitized Management API operations. The constrained human-run helper and dashboard fallback remain available. This is not delegated OAuth or a credential broker; private values never enter chat or copied prompts. See [the canonical workflow](../onboarding/START.md).
 
 One-time authorization, scoped delegation, device/browser authentication and credential brokers require separate future product/security design and confirmed platform APIs. They are explicitly outside this release.

package/docs/release-v2.0.1.md

@@ -0,0 +1,11 @@
+# CLI 2.0.1: app selection and configuration discovery
+
+The managed onboarding flow now lists existing apps by name and ID and offers Create new. `management-apps list --all --with-names` walks bounded pagination and hydrates names; malformed pages, incomplete traversal and name failures remain explicit. It never selects or creates an app automatically.
+
+Selected-app reads expose the exact publishable `api.client.token` field and the documented demand/currency/display settings. Private credentials, arbitrary metadata, unknown fields and callback URLs remain excluded. `management-apps config-fields` provides reviewed identifiers, human names, categories and types offline; categories are not editable app tags. Wrong target IDs, malformed values and duplicate public settings fail closed.
+
+Onboarding asks separately for demand formats, currency name and base units per USD, with observed defaults shown for explicit confirmation. It distinguishes Gaming from Offers, currency conversion from reward share, and BitLabs flooring from wallet precision. Existing financial settings are preserved unless a concrete change is authorized; no defaults, authentication changes or test-mode activation are borrowed from the old MCP.
+
+The portable dashboard button, canonical workflow and embedded CLI/MCP guides carry the same sequence. Leading-hyphen app/workspace IDs are accepted consistently. The constrained helper still supports its original offers/surveys manifest only; expanded discovery does not expand that helper’s mutation capabilities.
+
+Validation is recorded in the release report after the local suites and GitHub CI complete. Distribution verification is separate from publisher staging callbacks, earnings and production review.

package/docs/release-v2.0.2.md

@@ -0,0 +1,11 @@
+# CLI 2.0.2: setup questions and automatic user identity
+
+The setup guide, MCP instructions and copied dashboard prompt ask for demand formats, currency name and units per USD one question at a time. Currency names and rates have suggestions with custom input. New virtual currencies default to whole units (scale 0); routine decimal and rounding questions are removed. Existing wallets and explicit decimal choices are preserved. S2S reward callback setup remains an explicit next step.
+
+Integration guidance reuses the current publisher user ID automatically. Incompatible or numeric-only real IDs use persistent server-owned opaque aliases with the same account resolution for callbacks. Projects without a user identity system generate a cryptographically random demo ID, keep it stable for the demo session and isolate it from real wallets. Zero, nil UUIDs and shared numeric placeholders are not valid new initialization values.
+
+The iframe and widget snippet commands now expose runtime initialization with the publisher ID. Their explicit --demo option creates a session-persisted 128-bit random ID in browser-only previews. The iframe unloads the previous account before identity changes or validation; SDK snippets explicitly require the host authentication lifecycle to unload the SDK-owning document on logout/account change. Valid explicit --uid input remains supported; URL generation requires an explicit ID. Reserved parameter overrides and using a fixed signed hash with a different dynamic identity are rejected.
+
+The callback parser accepts lossless zero padding, such as 100.00 for a scale-0 wallet, while continuing to reject nonzero excess precision. Signature verification still uses the original request bytes; amount bounds, duplicate protection, existing scales and historical callback identity validation remain intact.
+
+Release checks cover the generated JavaScript, identity persistence and failure paths, callback integer/decimal behavior, guide consistency and distribution assembly. Publishing the tools does not certify a publisher app or live rewards; staging delivery and production review remain separate.

package/docs/release-v2.0.3.md

@@ -0,0 +1,9 @@
+# CLI 2.0.3: choose iframe, user-based API or mobile SDK
+
+After workspace access and app selection, onboarding asks which integration to use: iframe (Recommended), API or Mobile SDK. A mobile choice opens a separate Android, iOS, Flutter, React Native or Unity selection. The agent then resolves missing platform details and asks the shared demand, currency name, exchange-rate and reward-callback questions one at a time. Existing explicit choices are reused.
+
+The API route guides implementation of a custom user-based earning UI using public client endpoints, automatic publisher identity, required offer disclosures, visibility-based impressions, intact tracking URLs, progress/history and bounded error handling. The mobile route uses current official SDK guides and package APIs, with platform, account lifecycle and iOS Gaming constraints. Generic WebView helpers and deprecated SDK documentation do not substitute for these routes.
+
+`bitlabs setup guide --integration iframe`, `--integration api` and `--integration mobile-sdk` provide versioned offline guides in text or JSON. MCP exposes the same route information. The dashboard copy button includes every route guide and the callback source/tests without requiring dashboard access or a private repository.
+
+Integer-default currencies, persistent publisher identity, isolated random demo IDs and signed backend reward callbacks remain unchanged. The optional strict helper still supports only its iframe/Node/SQLite recipe. API/mobile apps need their own builds, contract tests and live staging evidence; publication is not production certification.

package/onboarding/IMPLEMENTATION.md

@@ -1,6 +1,6 @@
 # V1 implementation and remaining release evidence
 
-Prepared 22 September 2026. This companion records changes to the proposed plan; the original plan remains a proposal/reference. Status: **unreleased local implementation**. No live BitLabs provisioning, deployment, release publication or production financial operation is implied.
+Historical V1 implementation record, prepared 22 September 2026. The checks and release-gate snapshots below describe the initial implementation, not current distribution status. The v2.0.0 distribution has since shipped. The current managed-first, one-question-at-a-time workflow is [START.md](START.md); it supersedes the manual-first decisions in this historical record. No live publisher provisioning or production financial operation is implied by this record.
 
 ## Dashboard-team handoff scope
 
@@ -13,7 +13,7 @@ This source-only path has no prerequisite helper release, private GitHub URL, AP
 ## Scope decisions
 
 - Keep the Go repository and reuse its CLI packaging, local request tests and iframe helpers. Add a constrained standalone `bitlabs-onboard` binary instead of a new authorization service, MCP dependency or wholesale language rewrite.
-- Certify one recipe first: web iframe + generic standalone Node backend + durable SQLite on one persistent host. Native SDK/API/serverless recipes remain unsupported until separately tested. The existing mobile helpers are labeled WebView examples.
+- Certify one recipe first: web iframe + generic standalone Node backend + durable SQLite on one persistent host. Current onboarding additionally provides user-based API and mobile SDK implementation guides. These routes and serverless adapters require their own implementation tests and staging evidence; the strict helper still supports only the iframe recipe. The existing mobile helpers are labeled WebView examples.
 - Default to existing-app/dashboard-managed provisioning with no Management key. Optional private human-run helper supports reviewed app/create/name/link/demand operations. Currency semantics, token retrieval and callback registration/testing retain dashboard fallbacks.
 - Preserve existing auth/account identity, wallet and financial settings. A missing backend/wallet or unsupported host produces an implementation plan and unresolved action, not completion.
 - Callbacks and ledger evidence are mandatory. Reconciliations default to review holds, with explicit supported full-reversal policy only. Production balances are isolated from debug and test identities.