bitlabs-cli-linux-amd64 1.0.9 → 2.0.0

package/GETTING_STARTED.md

@@ -0,0 +1,44 @@
+# Getting started with agent-assisted onboarding
+
+Distribution: **v2.0.0**. The tools and source-only dashboard handoff are published through the existing distribution channels. Real publisher staging certification, dashboard embedding and production review remain separate checks. Use an exact reviewed release and its bundled guide.
+
+Read [onboarding/START.md](onboarding/START.md), or `bitlabs setup guide` from the matching reviewed release. That router is canonical and works offline. A portable prompt and setup manifest select only the first `iframe-node-sqlite-v1` recipe.
+
+## Existing app, dashboard-managed
+
+Select the app in the authenticated dashboard, retain its ID in `bitlabs.setup.json`, and preserve existing financial settings. No Management API key is needed. The publisher supplies the public App Token in public configuration and reviews settings in the dashboard. The agent inspects the repository, existing auth and wallet; it asks only for missing business choices.
+
+```text
+bitlabs-onboard validate --plan bitlabs.setup.json
+bitlabs callbacks endpoint-template --framework generic --output-dir ./bitlabs-callback
+```
+
+The output directory must be new. Review the generated source and the bundled callback and host guides. Follow the [iframe recipe](onboarding/integrations/iframe-node-sqlite-v1.md) and [host guide](onboarding/hosts/node-sqlite.md). A backend, stable account mapping and authoritative durable wallet are required. If absent, the deliverable is a backend integration plan, not a working rewards integration.
+
+## Optional human-run provisioning
+
+Only the publisher runs the reviewed standalone helper outside the agent environment:
+
+```text
+bitlabs-onboard provision --plan bitlabs.setup.json --state bitlabs.setup-state.json
+```
+
+The helper shows its target, privately reads a Management API key, then reads current settings and presents the exact before/after changes for approval; it does not accept that key through chat, agent environment, a command argument, or saved project configuration. Use the matching reviewed executable/source digest; source builds are for local validation. See [credentials](onboarding/credentials.md) for the actual isolation boundary and [provisioning](onboarding/provisioning.md) for supported operations/recovery. S2S credentials are not required.
+
+## Verify before reporting completion
+
+Callbacks are part of the integration. Local fixtures prove signature handling, durable deduplication, reconciliation and debug isolation. The publisher enters `BITLABS_APP_SECRET` into the reviewed backend runtime, registers the callback in the dashboard and triggers the dashboard Callback Tester. Collect sanitized server/ledger evidence; a 200 response or rendered iframe is insufficient.
+
+```text
+bitlabs-onboard verify --plan bitlabs.setup.json --evidence bitlabs.evidence.json
+```
+
+Report implementation, staging evidence and human production review separately. Verification imports evidence and labels it reported; it cannot independently authenticate an attestation or authorize deployment. `doctor` is only broad CLI diagnostics. Human review remains required before production changes or migrations.
+
+For a plan with `app.mode: create`, verification also requires the helper state:
+
+```text
+bitlabs-onboard verify --plan bitlabs.setup.json --evidence bitlabs.evidence.json --state bitlabs.setup-state.json
+```
+
+That state must bind the same plan digest and resulting app ID and record `CONFIGURATION_VERIFIED`. Existing-app verification does not require this extra state. An uncertain or incomplete create cannot acquire completion evidence for an arbitrary app.

package/GO-LIVE.md

@@ -0,0 +1,19 @@
+# Publisher integration release gates
+
+Status: **v2.0.0 tooling distribution; publisher staging certification NOT_RUN**. Source code, local tests and the self-contained dashboard button are available through the existing owner-approved distribution channels. Publication does not mean the authenticated dashboard is integrated, live API contracts are certified, or a publisher deployment is production-approved.
+
+## Narrow supported recipe
+
+First release: existing BitLabs app, web iframe, stable publisher account IDs, generic Node callback adapter, durable SQLite on one persistent host, and dashboard-managed configuration. Optional helper provisioning supports only reviewed operations; all currency/callback-registration contracts and token retrieval remain explicit manual actions unless independently validated. Native SDK/API/serverless recipes are deferred.
+
+## Required work before publisher production approval
+
+1. BitLabs engineering validates current app-create/name/link/demand contracts on an approved staging app. Record supported fields, permissions and sanitized fixtures. Confirm currency and callback macros/settings independently; unknown contracts stay manual.
+2. Certify the callback core and generic host with real signed staging delivery, durable ledger checks and appropriate negative/failure cases. Local fixtures remain synthetic.
+3. Review the constrained helper, exact source revision, per-platform executable digest, dependency/release provenance and disclosure contact. Use the exact reviewed distribution version and verify its source and executable identity. The existing distribution uses `kaspanvo/bitlabs-cli-releases`, npm `bitlabs-cli` and `bitlabs-cli.pages.dev`; these are not evidence of BitLabs platform certification. CI actions are pinned to official release commits; review those dependencies as part of production release.
+4. The dashboard team embeds the self-contained copy-button assets and optionally supplies selected workspace/app metadata. No dashboard API access or helper release config is required for that button. An optional advanced provisioning form separately requires reviewed platform-specific release metadata. Test the chosen path with representative publisher repositories.
+5. Obtain invite-only pilot evidence and explicit human production review. Imported reports are reported evidence; they are not independent attestations or deploy permission.
+
+The owner has authorized publication through the existing distribution channels. Follow [distribution-release.md](docs/distribution-release.md) to build and verify all six platform archives, npm packages and the download site. The optional advanced form builder still requires a local executable, its SHA256, exact version, checked-out source commit and immutable guide URL; its preview keeps copy/download disabled. The source-only button remains usable independently. Build tasks assemble files locally; publication and dashboard embedding are separate actions.
+
+CI exposes external staging certification as `NOT_RUN`. An optional job that silently skips because credentials are unavailable must never count toward live certification. See [TESTING.md](TESTING.md) and [onboarding/verification.md](onboarding/verification.md).

package/README.md

@@ -0,0 +1,42 @@
+# 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.0 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](docs/dashboard-team-handoff.md). It works without a published CLI/helper or dashboard API access: the copied prompt carries the instructions, callback code and tests. 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](onboarding/START.md), the canonical workflow. The first recipe is web iframe + standalone Node + durable SQLite on a persistent host. It preserves the publisher's accounts and wallet; secure reward callbacks are mandatory. Native SDKs, direct API integrations and serverless hosts require separate certified recipes.
+
+Existing-app setup managed through the dashboard is the default and needs no Management API key. The coding agent receives only a declarative, secret-free plan. For optional automated provisioning, the publisher independently runs a reviewed helper release and enters the key privately. Never place the key in chat, the agent host, repository, environment variables or application runtime. Runtime App Secrets go directly into the backend's secret store after generated code review. No S2S token is required by the recipe.
+
+## Local development
+
+Go version is pinned in `go.mod`; Node 22.13+ is required for callback tests.
+
+```text
+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. Select an existing app in the dashboard and prepare `bitlabs.setup.json` with the compact setup form. Prefilled workspace/app IDs are metadata, not credentials.
+2. Load the reviewed matching workflow via `bitlabs setup guide`; validate using `bitlabs-onboard validate --plan bitlabs.setup.json`.
+3. Implement the iframe, existing account mapping, durable wallet integration and bundled callback handler. Have the publisher perform manual dashboard settings or run the private helper.
+4. Test locally, then verify signed callback delivery and ledger outcomes in staging. Import sanitized evidence using `bitlabs-onboard verify --plan bitlabs.setup.json --evidence bitlabs.evidence.json`.
+5. Report implementation, staging evidence and human production review separately. Evidence import is reported evidence, not independent attestation or authorization to deploy.
+
+See [getting started](GETTING_STARTED.md), [verification](onboarding/verification.md), [security](SECURITY.md) and [release gates](GO-LIVE.md). The source-only button and optional form are described in [site](site/README.md); actual production dashboard integration is outside this repository.
+
+## General CLI
+
+The broad CLI remains an operator/reference tool. `bitlabs --help` and subcommand help describe its API, iframe, callback, reporting and local archive commands. Its legacy credential/bootstrap/configuration paths are not the V1 onboarding credential boundary. Do not substitute them, arbitrary authenticated requests, or MCP execution for the constrained human-run helper.
+
+`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](docs/distribution-release.md) binds a full source revision and platform-specific helper executable digest.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+Report vulnerabilities privately through the BitLabs/Prodege security contact confirmed for the distribution channel. Do not publish credentials or raw signed callback URLs in an issue. Confirm the public disclosure address and response commitments before release; this source tree does not establish them.
+
+## V1 onboarding boundary
+
+The standalone reviewed `bitlabs-onboard` helper is human-controlled. It accepts only a schema-validated plan, fixed supported BitLabs operations and private terminal credential input. Management keys stay in process memory for the approved operation. They must never be pasted into chat, provisioned into an agent host, added to application runtime or persisted in a plan. The default existing-app/dashboard path uses no Management key. No S2S key is requested for the iframe recipe.
+
+Install/build dependencies before credential entry; do not execute agent-edited helper source while credentialed. A separate same-user terminal is not secret isolation. Use dashboard-only provisioning or a real restricted agent environment with no access to the helper's credentials/processes. Human review of generated application code remains necessary before a runtime receives the App Secret.
+
+Only the App Token is publishable client configuration. The App Secret belongs in the backend provider's secret store. Never retrieve private values with browser tools, screenshots, cookies or terminal inspection; never pull remote secrets into an agent workspace.
+
+## Runtime and release controls
+
+The callback core verifies raw URL HMAC, app/environment binding and fixed-precision rewards before durable wallet mutation. Debug cannot change real balances; duplicates and reconciliations are auditable. SQLite requires one persistent host and stable shared database storage; ephemeral or distributed deployments are unsupported by this recipe.
+
+Pin helper executable SHA256, version, source commit and the matching workflow/templates. The site build rejects mutable or missing release metadata. Structural checks do not establish repository ownership: a release owner must review actual BitLabs-controlled distribution and provenance. Imported completion evidence is not an authenticated external attestation.
+
+The broad legacy `bitlabs` CLI and MCP expose additional capabilities and are not the constrained provisioning boundary. Their command flags, environment credentials and general secret storage must not be used as shortcuts in onboarding. An agent's written rules/ignore files alone are not access control.
+
+## Upgrading from the legacy CLI
+
+Earlier CLI versions could cache full Management API responses, including private values if an API response exposed them. This is a code-path risk, not a finding that a particular user's credentials were leaked. Blocking new cache writes does not erase old data.
+
+Close other BitLabs CLI/MCP processes, then run the reviewed human-admin cleanup command:
+
+```text
+bitlabs setup purge-sensitive-cache --confirm
+```
+
+It removes recognizable Management configuration responses from `~/.cache/bitlabs/http/*.json`, and management/callback rows from the generic, typed, search and sync tables in `~/.local/share/bitlabs/data.db`. Other cache records and saved credentials remain. It reports counts only. Oversized, malformed or unrecognized JSON cache files are left for human inspection; do not paste their contents into an agent conversation. A failure can follow partial cleanup, so resolve the stated issue and rerun.
+
+This operation does not certify forensic erasure and cannot remove OS backups, terminal logs or chat history. If private values may have reached an untrusted location, review and rotate the affected keys using existing dashboard controls. `bitlabs setup clear-credentials` separately removes stored credentials; it does not revoke keys at BitLabs.

package/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: bitlabs
+description: Implement BitLabs web iframe integrations from the self-contained dashboard source kit or reviewed CLI workflow, with human-controlled credentials.
+---
+<!-- Generated by scripts/sync-onboarding.py; START.md sha256: c905c17be8e35fcea1d3f60655aa2d1da83e40d8592d8af48b49e585eef35347 -->
+# BitLabs agent onboarding
+
+If the user supplies the self-contained dashboard prompt/source kit, follow its
+bundled instructions and verify its files. That source-only path does not require
+CLI installation, a helper release or a callback URL before repository discovery.
+
+Load the canonical workflow with `bitlabs setup guide` from the reviewed release
+whose identity matches `bitlabs.setup.json`; it embeds `onboarding/START.md`.
+If working in the source bundle, read that file directly. This skill is a thin
+router, not a separate policy. Distribution publication does not certify a
+publisher integration or replace staging evidence.
+
+Do not install or update to an unspecified latest version. Do not run credentialed
+commands from an agent-edited helper checkout. Existing-app dashboard provisioning
+is the default. Private credentials belong neither in chat nor in the agent host.
+A backend, stable account mapping, durable wallet, secure callbacks and evidence
+are mandatory. Do not treat a `doctor` success or iframe render as completion.
+
+The publisher can independently run the reviewed `bitlabs-onboard` helper.
+Optional `bitlabs skill install` registers this router. It is not required by the
+portable prompt. Preserve the publisher's existing instruction files.

package/TESTING.md

@@ -0,0 +1,31 @@
+# Testing and evidence boundaries
+
+Run local checks without private credentials:
+
+```text
+python3 scripts/sync-onboarding.py --check
+python3 scripts/credential-ux-audit.py
+go test ./...
+go vet ./...
+go build ./...
+node --test packages/callback-core/test/*.test.cjs site/test/*.test.cjs
+python3 -m unittest discover -s site/test -p 'test_*.py'
+./site/build.sh --preview
+```
+
+The callback tests exercise the reviewed protocol and SQLite wallet, including concurrency, duplicate content, environment separation, debug isolation and reconciliations. The form tests execute manifest/prompt generation, selected-app context, rejection of credential fields, invalid money/URLs, and failure to copy from unreleased configuration. The release builder tests reject mismatched source/executable identity and mutable guide URLs. CLI tests include request contracts against local mocks. None is evidence that BitLabs reached a deployed endpoint.
+
+The optional agent harness grades non-credentialed workflow behavior: orientation, canonical guide loading and validated iframe generation. It never provisions apps and cannot certify a generated publisher repository merely from call order. `--mock` exercises the harness itself; recorded logs are behavior evidence only.
+
+```text
+python3 scripts/agent-e2e.py --mock --scenario iframe
+python3 scripts/agent-e2e.py --mock --scenario onboarding
+```
+
+Do not use real keys in routine tests. Do not run credentialed integration tests against an agent-editable helper checkout. A maintainer may approve a staging contract-validation pass using a reviewed release and a dedicated non-production app. Document exact API contracts, artifact identity and sanitized results before enabling an automated capability.
+
+## Release gates
+
+Local CI is necessary but insufficient. A live gate with missing staging access is **NOT_RUN**, never a green live check. After local tests, use an approved staging deployment and the dashboard Callback Tester; record callback signature validation, test ledger outcomes, replay/concurrency behavior, reconciliation and unknown-user handling. Dashboard actions without independent evidence are `HUMAN_CONFIRMED`.
+
+Use the release's `schemas/evidence.schema.json` and `bitlabs-onboard verify`. Bind evidence to the plan digest, implementation revision, app/environment, recipe and observation time. Never include raw secrets, signed URLs, private account identifiers or real wallet data in output. Imported evidence remains reported evidence; human production approval is separate and never inferred by CI.

package/docs/agent-setup-hosted.md

@@ -0,0 +1,61 @@
+# Set up BitLabs with your coding agent
+
+Use this workflow to add a BitLabs web iframe and secure reward callbacks to an existing publisher project. The coding agent prepares and tests the implementation. The publisher controls dashboard settings, private runtime credentials and deployment approval. Callback processing and the authoritative wallet are part of the implementation from the start.
+
+## Start with the complete setup handoff
+
+If your dashboard provides **Set up with your coding agent**, select the intended app, copy its complete prompt and paste it into your coding agent with your project open. The prompt includes implementation instructions, non-secret app context when available, callback source, a persistent-host adapter, tests and a file inventory. Download the prompt if the clipboard or conversation truncates it.
+
+If that button is not available, request the complete source handoff from the dashboard team or your BitLabs contact. Its `setup-prompt.md` provides the same starting point without a button. This page is the public workflow; it does not contain the executable source kit. Do not assume that a button, package or new CLI release has been published just because this page describes it. Installing an arbitrary latest CLI is not a substitute for the handoff.
+
+The agent must check the end marker, file count, UTF-8 byte counts and file hashes before using bundled source. Materialize it in a new, reviewed directory without overwriting publisher files. If content is missing or verification fails, request the complete handoff and continue independent repository inspection. Hashes identify the supplied bytes; they do not certify a deployment or establish who supplied the package.
+
+## Inspect the project before finalizing setup
+
+Inspect the framework, authentication, existing account identifiers, wallet, backend, tests and hosting without reading secret files. Preserve existing account identity and the authoritative wallet. Ask only for missing non-secret choices that the repository and supplied context cannot establish. Discover the backend and propose the callback route before requesting its deployed URL or completing a strict setup plan.
+
+Default to an existing app managed through the [Publisher Dashboard](https://dashboard.bitlabs.ai/). Confirm the intended app if its ID is missing; a similar app name is not authorization to select or change it. If a new placement is needed, the publisher can follow [Creating a new placement](https://developer.bitlabs.ai/docs/creating-a-new-placement) in the dashboard and provide its non-secret ID. The agent does not need a Management API key to implement this path.
+
+The supplied reference covers a web iframe with standalone Node >=22.13 and an atomic SQLite wallet on durable local disk on one persistent host. It is not a ready-to-deploy recipe for serverless or ephemeral hosts, native SDKs, direct APIs, every demand format or arbitrary databases. For another architecture, prepare the missing backend or transactional wallet adapter and its tests. Do not create a second balance system alongside an existing wallet or describe an unimplemented adapter as complete.
+
+## Keep credentials separate
+
+| Value | Purpose and handling |
+| --- | --- |
+| App ID and workspace ID | Non-secret identifiers that select the intended setup. They do not authenticate API calls. |
+| Public App Token | Client configuration used by the iframe. The publisher supplies it in the designated public configuration; it is not an App Secret or Management key. |
+| App Secret | Server-side callback authentication. After reviewing the backend code, the publisher enters it directly into the deployment provider's secret interface. |
+| Management API key and S2S token | Not required by this existing-app, dashboard-managed workflow. Do not request or retrieve them. |
+
+Private credentials must never enter the conversation, agent environment, agent-accessible files, client bundle or logs. Do not obtain them through screenshots, browser sessions, cookies, shell history or process inspection. A separate terminal does not isolate secrets from an unrestricted same-user agent. Synthetic local fixtures need no real credentials.
+
+## Implement the iframe and wallet together
+
+Use the [iFrame & Web integration reference](https://developer.bitlabs.ai/docs/iframeweb-integration) for the public token and opening parameters. Derive the iframe UID from the authenticated account and preserve that mapping. The supplied callback recipe uses opaque UIDs of at most 65 ASCII letters, digits, underscores or hyphens. A browser-generated visitor ID is not a redeemable wallet account. Iframe messages and other client events must not credit rewards.
+
+Preserve the app's existing demand access, currency conversion, reward share, precision and rounding policy. Missing settings are unknown, not permission to insert defaults. Keep base currency units per USD separate from the effective user reward. Use the authenticated callback's publisher-currency reward exactly once; do not substitute its USD payment or multiply the reward again. Review the currency scale and maximum reward bound explicitly. The reference rejects excessive precision rather than silently rounding a signed reward.
+
+Read [Callbacks Introduction](https://developer.bitlabs.ai/docs/callbacks), [Securing callbacks through hashing](https://developer.bitlabs.ai/docs/securing-callbacks-through-hashing) and [Reward & Reconciliation callbacks](https://developer.bitlabs.ai/docs/general-reward-callbacks) before configuring the endpoint. Keep the bundled raw-URL verification, trusted public origin, exact decimal parsing and durable transaction behavior. Preserve URL bytes during signature verification and authenticate before processing a reward.
+
+Register wallet accounts through the trusted account lifecycle. Unknown callback users must not create accounts automatically. Commit the callback receipt and wallet update atomically; retries and concurrent duplicate deliveries must have one financial effect. Scope identities to the app and environment. Isolate debug callbacks from real balances and production deduplication state. Reconciliations default to durable human review; unresolved references and unsupported adjustments must remain visible. Enabling supported full reversals requires an explicit financial policy decision.
+
+## Configure and verify staging
+
+After implementation review, provide the publisher with the exact runtime settings and HTTPS callback destination. The publisher enters the App Secret into the backend's secret interface, saves the callback URL and required macros in the dashboard, and uses the dashboard Callback Tester. Include the user ID, publisher-currency reward, USD payment, transaction ID, reconciliation reference and activity type expected by the supplied handler. Never put secrets or a fabricated signature in the registered URL. Do not invent registration or callback-test APIs.
+
+Run the bundled synthetic fixtures, the publisher build and meaningful tests of its actual account, wallet and hosting integration. Required checks include:
+
+- Valid signatures are accepted; missing, malformed and tampered signatures are rejected without changing balances.
+- Exact reward amounts reach the intended account once, including retries and concurrent duplicates; conflicting reuse of an identity is rejected.
+- Receipts and balances survive restart, remain scoped to the correct app/environment, and cannot diverge through partial writes.
+- Debug callbacks leave real balances and production deduplication state unchanged.
+- Reconciliations follow the approved policy; unmatched or unsupported adjustments are held for review without guessed debits.
+- Unknown users and invalid amounts do not create accounts or credit balances.
+
+Then collect sanitized staging evidence from actual signed callbacks and corresponding ledger outcomes, including test isolation. A synthetic signature proves only local behavior. A dashboard tester response or HTTP 200 alone does not prove correct authentication, crediting or production readiness. Obtain authorization for migrations, deployments, production callback changes and changes to existing financial settings.
+
+## Report what is proved and what remains
+
+Report changed files, tests actually run, their outcomes and remaining publisher actions. Mark checks `PASS`, `FAIL`, `NOT_RUN` or `HUMAN_CONFIRMED`, and identify whether evidence came from local tests, server receipts or human confirmation. Bind reports to the app, environment and implementation revision; omit secret values and raw sensitive payloads.
+
+Keep **implementation prepared**, **staging evidence collected** and **human production review** separate. Agent reports are reported evidence, not independently authenticated attestations or deployment authorization. A copied prompt, rendered iframe, successful diagnostic command or missing failure report does not establish completion. Unsupported infrastructure, absent source files, missing decisions and unperformed live checks must remain explicit while independent implementation work proceeds.

package/docs/agent-setup.md

@@ -0,0 +1,24 @@
+<!-- Generated by scripts/sync-onboarding.py; START.md sha256: c905c17be8e35fcea1d3f60655aa2d1da83e40d8592d8af48b49e585eef35347 -->
+# 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.
+
+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.
+
+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.
+
+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.

package/docs/dashboard-team-handoff.md

@@ -0,0 +1,66 @@
+# Dashboard team: drop-in agent setup button
+
+**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.
+
+## Embed in the dashboard
+
+Copy `button.js` and `button.css` into the dashboard's existing static assets. Add a container, load the files through the dashboard's normal asset pipeline, then mount:
+
+```html
+<link rel="stylesheet" href="/assets/bitlabs/button.css">
+<div id="bitlabs-agent-setup"></div>
+<script src="/assets/bitlabs/button.js"></script>
+```
+
+```javascript
+const widget = BitLabsSetup.mount(
+  document.getElementById('bitlabs-agent-setup'),
+  () => ({
+    workspace_id: selectedWorkspace.id,
+    app_id: selectedApp.id,
+  })
+);
+// 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.
+
+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.
+
+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.
+
+If the dashboard already has its own button and styling, use the same payload generator:
+
+```javascript
+const prompt = BitLabsSetup.buildPrompt({
+  workspace_id: selectedWorkspace.id,
+  app_id: selectedApp.id,
+});
+// Copy prompt using the dashboard's existing clipboard UX and manual fallback.
+```
+
+`button.js` contains all source content. It performs no fetches, reads no cookies/storage, and uses no external fonts or scripts. The split asset version works with the dashboard's normal Content Security Policy; it requires no inline-script exception. The standalone `index.html` uses inline assets only to make the portable demo self-contained.
+
+## What the publisher gets
+
+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.
+
+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.
+
+## Files and acceptance
+
+- `index.html`: ready-to-open standalone demo; no placeholders or setup needed.
+- `button.js` and `button.css`: dashboard assets, including all prompt source content.
+- `setup-prompt.md`: the same complete prompt with unknown context, usable without the button.
+- `bundle.json`: versioned source inventory and SHA256 identifiers.
+- `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.
+
+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.

package/docs/distribution-release.md

@@ -0,0 +1,46 @@
+# Distribution release: v2.0.0
+
+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.
+
+## Prepare the release
+
+Commit the reviewed source and run the local release checks. Build all six platform archives with GoReleaser from that exact clean tagged commit. Set `BITLABS_SOURCE_DIGEST` to the output of `python3 scripts/source-digest.py`; the release hook rejects a missing or mismatched value. Use `goreleaser release --skip=publish` to prepare and inspect artifacts before publishing them. Every current archive must include `bitlabs`, `bitlabs-onboard`, `bitlabs-mcp`, license/notices, matching guides, schemas and callback source/tests. Verify the native binaries' reported version/revision and the MCP initialization version; confirm the other binaries' build metadata. Record each platform's **helper executable** SHA256 separately from the archive checksum.
+
+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.
+
+## Assemble the public site locally
+
+The builder requires Python 3 and Node on PATH to construct the source handoff. It performs no network operations and deploys nothing. The checked-out commit must equal `--source-revision`, the tree must be clean, and `--out` must be a new directory. Omitting `--out` chooses a new temporary directory. Existing output is never deleted or replaced.
+
+```text
+python3 scripts/build-distribution-site.py \
+  --release-dir /reviewed/current-artifacts \
+  --version 2.0.0 \
+  --source-revision <full-committed-revision> \
+  --previous-site /reviewed/previous-site \
+  --prior-release-dir /reviewed/releases/v1.0.9 \
+  --require-prior-version 1.0.9 \
+  --out /reviewed/new-public-site
+```
+
+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.
+
+The output provides:
+
+- `/`: working source-only copy button, complete handoff download and documentation/download links.
+- `/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.
+- `/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.
+
+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.
+
+The explicit legacy `bitlabs update` command checks archive SHA256 and replaces only the `bitlabs` executable. It does not update the companion MCP/helper binaries or bundled guides; a complete archive or exact npm upgrade keeps all three tools together. Release checksums identify downloaded bytes but are not independent publisher signatures. The separate Ed25519 background-updater machinery is inactive in the normal GoReleaser distribution unless its release/key/ownership metadata is deliberately configured; do not claim that this release is automatically signed or auto-updated.

package/docs/onboard-button.html

@@ -0,0 +1,34 @@
+<!-- Advanced release-bound form. For the ready-to-hand-over source button use docs/dashboard-team-handoff.md.
+     Dashboard embed: inject non-secret BITLABS_DASHBOARD_CONTEXT {workspace_id, app_id}
+     and the reviewed BITLABS_ONBOARDING_RELEASE before this fragment. No credentials. -->
+<style>
+.bl-setup{max-width:780px;padding:28px;background:#fff;color:#18181b;border-radius:20px;font:15px/1.5 system-ui,sans-serif;box-shadow:0 8px 40px #0002}.bl-setup [hidden]{display:none!important}.bl-setup h1{font-size:26px;margin:0 0 8px}.bl-setup p{margin:8px 0 18px}.bl-setup form{display:grid;grid-template-columns:1fr 1fr;gap:14px}.bl-setup label{display:flex;flex-direction:column;gap:4px}.bl-setup input,.bl-setup select{font:inherit;min-width:0;padding:9px;border:1px solid #ccc;border-radius:7px}.bl-setup input[readonly]{background:#f4f4f5}.bl-setup fieldset{grid-column:1/-1;border:1px solid #ddd;border-radius:8px}.bl-setup fieldset label{display:inline-flex;flex-direction:row;margin-right:18px}.bl-setup small{color:#52525b}.bl-setup .wide{grid-column:1/-1}.bl-setup button{font:600 15px system-ui;padding:11px 16px;border:0;border-radius:8px;background:#5b21b6;color:white;cursor:pointer}.bl-setup button:disabled{opacity:.45;cursor:not-allowed}.bl-setup pre{max-height:300px;overflow:auto;background:#f4f4f5;padding:12px;font-size:12px;white-space:pre-wrap;word-break:break-word}.bl-setup [data-status]{min-height:24px}.bl-setup .actions{display:flex;gap:10px;flex-wrap:wrap}@media(max-width:560px){.bl-setup{padding:18px}.bl-setup form{grid-template-columns:1fr}}
+</style>
+<section class="bl-setup" id="bl-onboard">
+<h1>Set up with your coding agent</h1>
+<p>Choose a staging setup. Your agent implements the web integration and secure reward callbacks. You handle private credentials in the dashboard or reviewed helper.</p>
+<form>
+<input type="hidden" name="setup_id">
+<label>Workspace ID<input name="workspace_id" autocomplete="off" required maxlength="80"></label>
+<label>App setup<select name="app_mode"><option value="existing">Use an existing app</option><option value="create">Create with the human-run helper</option></select></label>
+<label>Existing app ID<input name="app_id" autocomplete="off" maxlength="80"></label>
+<label>New app name<input name="app_name" autocomplete="off" maxlength="100"></label>
+<label>Provisioning<select name="provisioning"><option value="dashboard">I manage settings in the dashboard</option><option value="helper">I run the reviewed helper privately</option></select></label>
+<label>Product URL (optional)<input name="product_url" type="url" placeholder="https://your-app.example"></label>
+<fieldset><legend>Demand (subject to your existing access)</legend><label><input name="offers" type="checkbox" checked>Games and offers</label><label><input name="surveys" type="checkbox">Surveys</label></fieldset>
+<p class="wide"><b>Web iframe + persistent Node/SQLite backend</b><br><small>This first recipe requires an existing account mapping and authoritative wallet. Native SDK, direct API and serverless recipes are not yet certified.</small></p>
+<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>
+<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>
+</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>
+<details><summary>Review the secret-free setup</summary><pre data-output></pre></details>
+</section>
+<script>{{ONBOARDING_FORM_JS}}</script>
+<script>BitLabsOnboarding.mount(document.getElementById('bl-onboard'), window.BITLABS_DASHBOARD_CONTEXT || {}, window.BITLABS_ONBOARDING_RELEASE || null);</script>

package/docs/pairing-flow-proposal.md

@@ -0,0 +1,7 @@
+# Deferred: delegated agent authorization
+
+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).
+
+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.0.md

@@ -0,0 +1,13 @@
+# BitLabs publisher tools v2.0.0
+
+This major version replaces credential-first agent onboarding with a self-contained dashboard handoff. The copied prompt includes callback code and tests, starts by inspecting the publisher project, and needs no private key or CLI installation to begin.
+
+- Adds `bitlabs-onboard` for independently human-controlled, pinned, staging-only optional provisioning and explicit evidence reports.
+- Adds durable callback receipts and atomic wallet updates, exact decimal rewards, retry/concurrency handling, debug isolation and reconciliation review.
+- Bundles the canonical guide, schemas, callback sources/tests and license notices with all three tools on macOS, Linux and Windows (amd64 and arm64).
+- Disables unsafe legacy onboarding bootstrap, configuration and callback-mutation paths. Sensitive output/cache handling and retries are tightened. Existing automation using these paths must migrate to the new guide.
+- Adds the portable dashboard button, complete prompt/download, hosted guide, six-platform archive checksums and helper executable identities.
+
+Install the exact release: `npm install -g bitlabs-cli@2.0.0`, or use the matching archive and `checksums.txt` from the public releases repository. The default workflow uses an existing app configured by its publisher in the dashboard. Skills and MCP are optional.
+
+Local fixtures and CI verify the implementation; they do not certify real publisher staging delivery. Live callback/ledger verification, actual dashboard embedding and publisher production approval remain separate. Private credentials must not be supplied to the agent. See GO-LIVE.md and the bundled setup guide.

package/onboarding/IMPLEMENTATION.md

@@ -0,0 +1,61 @@
+# 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.
+
+## Dashboard-team handoff scope
+
+The deliverable is the [drop-in copy button](../docs/dashboard-team-handoff.md), not direct access to or implementation inside the private dashboard. Its portable package includes a working standalone HTML demo, reusable JS/CSS assets, a complete prompt and the callback reference source/tests. The dashboard team can supply selected workspace/app metadata through a small local adapter; the button also works with unknown context and lets the agent resolve missing details after inspection.
+
+Validation of the handoff: 58 Node tests and 15 Python package/release tests pass. An isolated headless Chrome run verified the standalone page, enabled copying without configuration, selected-text fallback, current-app copying, exact prompt download, mobile layout, zero HTTP requests and zero browser errors. The extracted package runs all 19 callback fixtures.
+
+This source-only path has no prerequisite helper release, private GitHub URL, API credential or known callback endpoint. It defaults to an existing app managed through the dashboard. The stricter release-bound provisioning form remains a separate option. Integrating/publishing the button in the dashboard belongs to that team and is not a request for dashboard access in this task.
+
+## 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.
+- 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.
+- Imported evidence is explicitly reported evidence. The helper cannot independently authenticate reports or authorize deployment; human production review is recorded separately.
+
+## Implemented locally
+
+| Deliverable | Local implementation | External limit |
+|---|---|---|
+| Setup manifest | Strict schema, typed validation, non-secret plan identity | Publisher/app values require actual selected context |
+| Provisioning helper | Separate binary, private ephemeral key, allowlisted operation surface, approval/read-back and recovery state | Approved live staging API contract validation NOT_RUN |
+| Callback module | Shared raw-URL verification, fixed precision, durable SQLite receipt/wallet behavior, debug/reconciliation controls and adapters | Generic persistent-host deployment certification NOT_RUN |
+| Dashboard form | Selected-app metadata, iframe recipe, currency intent, staging callback URL, secret-free JSON/pinned prompt | Production dashboard embed NOT_RUN |
+| Workflow | Canonical START router, generated thin docs/skill wrappers, bundled guide, checklist/MCP reference | Reviewed publisher pilot NOT_RUN |
+| Completion evidence | Bound plan/app/environment/revision/time checks, typed reported phases and manual actions | Independent provider evidence and human production review NOT_RUN |
+| Release assembly | Third binary, npm shim, publishing disabled by default, explicit version/commit/digest binding, unreleased copy-disabled preview | BitLabs-owned release, actual immutable URL and release approval NOT_RUN |
+
+## Local validation
+
+Local checks cover Go commands/contracts; the Node callback suite covers wallet and protocol behavior; setup-form tests cover secret rejection, selected app, required backend, amount intent, pinned prompt and disabled unreleased state. Release-builder tests reject changed binary/source, dirty source, mutable URLs and artifact path escape. Workflow audit verifies generated sources and removes the previous credential-first/callbacks-last policy.
+
+Verified locally on 22 September 2026:
+
+- Complete `go test ./... -count=1` and `go vet ./...` passed, including the generated standalone callback handler exercised over localhost HTTP. The run used synthetic credentials, disabled keyring access and isolated configuration/cache paths; default API destinations were loopback.
+- All three binaries built. The isolated onboarding helper also cross-compiled for macOS, Linux and Windows on amd64 and arm64.
+- 36 Node tests passed: 19 protocol/durable-wallet tests and 17 setup-form/npm-shim tests. This workstation used Node 23.10.0; CI is configured to run Node 22 and 24, whose hosted runs remain unobserved here.
+- Eleven release/output-assembly tests, the canonical-workflow audit and both non-credentialed MCP workflow fixtures passed. Output tests verify that rebuilding cannot delete data through a symbolic-link destination.
+- The form-generated fractional-currency manifest passed the helper validator. The preview remains visibly unreleased with portable copying disabled.
+- Browser visual inspection was attempted but the local automation kernel failed before opening a browser (`TIOCSTI`). Executable form tests cover mounted input state, read-only app context, errors, and copy controls; visual rendering is not claimed as verified.
+
+These checks establish local behavior only. Live provider delivery and deployment certification remain NOT_RUN. The new explicit sensitive-cache cleanup command was tested on synthetic cache files; no actual user caches or saved credentials were purged.
+
+## Release gates still requiring an operator or external system
+
+1. Confirm supported Management API contracts and callback/currency semantics with BitLabs engineering and an approved non-production app. Keep unsupported operations disabled/manual.
+2. Review actual immutable source and every platform-specific helper executable. Verify BitLabs ownership and distribution provenance, review the pinned release automation dependencies, and establish disclosure/support ownership. The site requires real values and never fabricates release links.
+3. Wire the form into the authenticated dashboard, supply selected workspace/app and matching publisher-platform release config, and preserve the manual path.
+4. Deploy a reviewed staging callback backend with persistent storage; register its URL in the dashboard and observe real signed delivery, wallet/test isolation, retries and reconciliations. Do not infer this from synthetic fixtures or HTTP 200 alone.
+5. Exercise representative publisher repositories and interruption/recovery with local-isolated and cloud-assisted/dashboard paths. Close manual actions and record human production review before production changes.
+
+See [GO-LIVE.md](../GO-LIVE.md) for the release sequence and [verification](verification.md) for evidence requirements. Local implementation progress must not turn any external NOT_RUN gate into a success claim.
+
+CI action provenance: [checkout v4.3.1](https://github.com/actions/checkout/releases/tag/v4.3.1), [setup-go v5.5.0](https://github.com/actions/setup-go/releases/tag/v5.5.0), [setup-node v4.4.0](https://github.com/actions/setup-node/releases/tag/v4.4.0). Workflow pins use the full commits linked by those official release pages.
+
+Create-mode verification requires sanitized `--state` at `CONFIGURATION_VERIFIED`, bound to the plan digest and resulting app ID. The state requirement prevents assigning evidence to an arbitrary app after an uncertain create. Existing-app plans remain directly app-bound.