BitLabs publisher tools and agent-assisted onboarding

This repository contains the general bitlabs CLI, optional bitlabs-mcp adapter, and the constrained bitlabs-onboard onboarding helper. The v2.0.6 distribution includes the source-only dashboard handoff and optional onboarding helper. Local tests are not BitLabs staging certification or production approval.

For the dashboard team, deliver the self-contained copy-button package. The button works without dashboard API access: its copied prompt carries the instructions, callback code and tests. The managed setup it starts uses a trusted installed CLI 2.0.6 after the publisher privately enables local keyring access. Generate it with python3 scripts/build-dashboard-handoff.py; the output is handoff/bitlabs-dashboard-button.zip. The team embeds the assets and optionally supplies its selected app IDs.

Start with onboarding/START.md, the canonical workflow. Onboarding routes to iframe, user-based API or an official mobile SDK. It preserves the publisher's accounts and wallet; secure reward callbacks are mandatory. The optional strict helper validates only the iframe + standalone Node + durable SQLite reference; API/mobile implementations and other hosts require their own tests and staging evidence.

The agent asks one question at a time and waits, skipping known values: workspace ID first, secure Management API access next, then a named app picker with a Create new option. 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. Then ask separately about demand formats, currency name and base currency units per USD. Show observed defaults for confirmation; skip only choices the publisher already made explicitly. The human runs bitlabs setup credentials --store --workspace-id WORKSPACE_ID in their own terminal; the hidden prompt stores the Management key in the OS keyring. The agent then uses sanitized management-apps list/get/create/update-config commands for the authorized workspace. No private key belongs in chat, agent tool inputs, command arguments, environment variables, project files or the backend; no plaintext fallback is allowed. Runtime App Secrets go directly into the reviewed backend secret store. No S2S token is required.

CLI 2.0.6 includes named app discovery, reviewed public configuration fields and the matching embedded guide. Check the trusted installed executable's version and provenance; never use 1.x or an agent-edited build for this flow. Dashboard-managed setup is the fallback when secure local access is unavailable or declined.

For later changes to an app, follow app settings. The source catalog records 56 known identifiers with verification, write policy and visibility, including branding and promotions. The agent reuses the selected app, changes only the requested setting and verifies the result. Historical names require current contract verification; callback, authentication and test-mode writes remain blocked. CLI 2.0.6 includes these additions. Check the installed version and command help before use; older releases require an upgrade or the documented fallback.

Local development

Go version is pinned in go.mod; Node 22.13+ is required for callback tests.

python3 scripts/sync-onboarding.py --check
go test ./...
go build ./...
node --test packages/callback-core/test/*.test.cjs site/test/*.test.cjs
python3 scripts/credential-ux-audit.py
./site/build.sh --preview

A source build can validate plans and run local fixtures; it cannot impersonate a reviewed release for credentialed provisioning.

Publisher workflow

1. Ask only for the workspace ID if missing; wait. Next have the human establish secure local access and confirm it.
2. List/read apps, verify any supplied selection, and ask to choose or create only if the target is unclear. Read settings before asking each missing preference.
3. Preserve financial and unrelated settings, checkpoint before creation, apply authorized documented changes and verify read-back. Reconcile uncertain creates before retrying. Currency names and exchange rates get separate suggestions. New virtual currencies default to integers; do not ask routine precision or rounding questions. Preserve existing wallets and explicit decimal choices. Public-token and callback fields may need a later individual question or dashboard step.
4. Implement the chosen iframe, user-based API or mobile SDK, authenticated account mapping, authoritative wallet and secure callbacks. Continue compatible work while awaiting answers; discover the backend before asking for a deployed callback URL.
5. Run local tests and collect actual staging callback/ledger evidence. In a sanitized local evidence file, record implementation prepared, staging evidence collected and human production review separately.

Sanitized management state is not the strict helper manifest. The reviewed bitlabs-onboard plan-based path remains optional; its schema accepts only provisioning: dashboard|helper and must not be a prerequisite for discovery.

See getting started, verification, security and release gates. The source-only button and optional form are described in site; actual production dashboard integration is outside this repository.

General CLI

The trusted installed CLI is the managed workflow's API client. Use its sanitized management commands within the authorized workspace and the published API contract. bitlabs --help describes other tools but does not authorize unrelated operations. Broad setup bootstrap remains disabled. The independently human-run helper is a separate optional boundary.

bitlabs doctor diagnoses broad CLI health, not project or financial correctness. WebView snippets are examples, not official native SDK recipes. Optional bitlabs skill install registers a thin router; skills and MCP are not required by the portable prompt.

Use exact reviewed versions and verify release provenance. Do not bootstrap from latest, silently update during onboarding, or mix unversioned online instructions with an older callback/helper bundle. Release packaging binds a full source revision and platform-specific helper executable digest.

User identity is resolved automatically during integration: reuse the publisher account ID or its persistent server-side opaque mapping. If no identity system exists, generate a cryptographically random demo UID and persist it per demo session. Never initialize with zero, a numeric-only placeholder or the nil UUID. Demo identities remain separate from real wallet accounts.