@vibecodr/cli 0.2.10 → 1.0.0-rc.0

package/docs/CLOUDFLARE-PRIMITIVE-FIT.md

@@ -0,0 +1,212 @@
+# Cloudflare Primitive Fit
+
+Last checked against Cloudflare docs: 2026-05-17.
+
+This document records which current Cloudflare primitives belong in
+`vc-tools`, and which ones are intentionally deferred. The goal is to avoid
+shipping an older Durable Object mental model where Cloudflare now has a
+better dynamic primitive, while also avoiding a novelty-driven replatform that
+would weaken the hosted Tools Cloud boundary.
+
+## Current Decision
+
+`vc-tools` should use Cloudflare's newest dynamic offerings when it is loading
+customer- or agent-authored Worker code at runtime. It should not use them as a
+replacement for the platform-owned quota, audit, artifact, job, Browser Run, or
+Sandbox control plane.
+
+The v1 production substrate remains:
+
+- Browser Run Quick Actions for stateless screenshots, PDFs, markdown, rendered
+  HTML, and first-class bounded crawl artifacts.
+- Cloudflare Workflows for durable `browser.agent_task` execution. The Workflow
+  owns the long-running task lifecycle and retries, while Browser Run Sessions
+  remain the browser provider inside that lane: Creator up to 20 minutes and Pro
+  up to 1 hour per task, both with 10-minute idle closure and artifact output.
+- Cloudflare Sandbox SDK for hosted shell/test command execution, with Creator
+  on `standard-1` and Pro on `standard-2` container lanes.
+- D1 for actor-scoped job, usage, audit, retention, and artifact indexes.
+- R2 for artifact bytes.
+- Queues plus DLQ for bounded async dispatch and retry of stateless browser,
+  sandbox, scheduled QA, and other single-step jobs.
+- The Sandbox SDK's required Durable Object and Container binding for sandbox
+  lifecycle and process isolation.
+
+That is not a rejection of Dynamic Workers. It is a boundary decision: Dynamic
+Workers are an execution substrate for dynamically loaded Worker modules, not a
+ledger, not an artifact store, not a Browser Run substitute, and not a shell
+container.
+
+## Current Cloudflare Facts
+
+Cloudflare Browser Run is the correct browser provider, but its lanes should be
+split by workflow shape:
+
+- Quick Actions remain the best default for `vc-tools` public-web browser work
+  because the hosted service can submit a bounded request, meter browser time,
+  store an artifact, and avoid local browser execution.
+- Browser Sessions support direct browser control and session reuse. They carry
+  separate concurrency/pricing pressure and belong only inside the paid
+  `browser.agent_task` lane, not the stateless Quick Actions lane.
+- `/crawl` is a Browser Run Quick Action, not a Dynamic Workers feature. It
+  starts an async provider crawl job and returns site records as a hosted
+  artifact under `vc-tools` quota, retention, and audit.
+
+Cloudflare Workflows are the right durable primitive for long paid browser
+tasks:
+
+- Workflow classes extend `WorkflowEntrypoint` and are bound through Wrangler
+  with `name`, `binding`, and `class_name`.
+- Workers create instances through the Workflow binding with an instance `id`
+  and typed `params`, which maps cleanly to the existing D1 job id and queued
+  job payload.
+- `step.do()` provides durable execution, retry configuration, and resume from
+  the last successful step instead of relying on a Queue consumer invocation.
+- Cloudflare Workers limits cap Queue Consumers at 15 minutes of wall-clock
+  time, while Workflows are designed for durable multi-step work. That makes
+  Queue consumers a poor owner for the 20-minute Creator and 1-hour Pro browser
+  agent-task lane.
+
+Cloudflare Dynamic Workers provide a Worker Loader binding that can load Worker
+code at runtime:
+
+- `load(code)` creates a fresh Dynamic Worker for one-time execution.
+- `get(id, callback)` caches a Dynamic Worker by ID so it can stay warm across
+  requests.
+- Dynamic Workers can be given selected bindings and can have outbound network
+  disabled with `globalOutbound: null`.
+- Dynamic Workers are priced by Dynamic Workers created daily, requests, and
+  CPU time.
+
+Cloudflare Durable Object Facets build on Dynamic Workers:
+
+- A platform-owned supervisor Durable Object loads dynamic code.
+- The dynamically loaded facet runs as a child of the supervisor.
+- Each facet gets its own isolated SQLite database.
+- The supervisor controls access and decides what requests reach the facet.
+
+Cloudflare Dynamic Workflows add durable steps to runtime-loaded code:
+
+- Dynamic Worker code can create Workflow instances without pre-registering
+  each tenant's Workflow class.
+- Workflow steps can retry, sleep, wait for events, and resume after isolate
+  restarts.
+
+Cloudflare Sandbox SDK is different:
+
+- The Sandbox SDK is explicitly built from Workers, Durable Objects, and
+  Containers.
+- Its Wrangler configuration requires `containers`, a `durable_objects` binding,
+  and a migration for the `Sandbox` class.
+- `getSandbox()` returns a Durable Object-backed sandbox whose container starts
+  lazily and can execute shell commands, manage files, expose ports, and be
+  destroyed after use.
+
+## Fit Matrix
+
+| Need | Preferred primitive | Why |
+| --- | --- | --- |
+| Screenshot, PDF, markdown, rendered page inspection, bounded crawl | Browser Run Quick Actions | Stateless, Cloudflare-hosted, no Worker code loading required |
+| Paid browser agent task up to 20 minutes on Creator or 1 hour on Pro | Cloudflare Workflow plus Browser Run Session | Workflow owns durable job execution/retry; Browser Session provides browser-native control with explicit close/finally behavior, 10-minute idle closure, and saved JSON artifacts |
+| Shell command or test execution | Sandbox SDK | Real isolated container/process/filesystem boundary; Creator uses `standard-1`, Pro uses `standard-2` |
+| Agent-authored JavaScript tool code | Dynamic Workers `load(code)` | Runtime-loaded Worker module with controlled bindings and egress |
+| Reused user-defined HTTP tool/app code | Dynamic Workers `get(id, callback)` | Stable ID can keep the Worker warm and avoid reloading every call |
+| User-defined durable object/reducer with private storage | Durable Object Facets | Supervisor-owned dynamic code plus isolated facet SQLite |
+| Long-running user-defined workflow steps | Dynamic Workflows | Runtime-loaded code with Workflow retry/sleep/event semantics |
+| Product billing, quota, audit, grants, retention, artifact index | D1 plus platform Worker logic | Needs platform-owned authority and queryability, not dynamic user code |
+| Artifact bytes | R2 | Large binary/object storage, not Durable Object storage |
+| Cross-user reporting and dashboards | D1 or Analytics Engine | Cross-object query/reporting plane |
+| Job dispatch and retries for single-step tools | Queues plus DLQ | Simple bounded retry and backpressure path for non-agent long-running jobs |
+
+## vc-tools Invariants
+
+- Dynamic Workers must not receive raw Cloudflare account tokens, Stripe
+  secrets, Vibecodr grant-signing secrets, D1 global authority, R2 bucket-wide
+  authority, or the Browser Run API token.
+- Dynamic Workers, if added, must receive only a purpose-built host proxy with
+  explicit inputs, output size limits, egress policy, timeout, plan quota, and
+  audit context.
+- Durable Object Facets, if added, must be children of a platform supervisor
+  Durable Object. The facet may own facet-local state, but it must not own
+  subscription authority, grant validation, global quota, or billing.
+- Cloudflare Workflows are allowed as platform-owned durable execution for
+  `browser.agent_task`. Dynamic Workflows, if added later for runtime-loaded
+  user code, must persist only user-defined workflow state and step outputs.
+  Platform admission, quota reservation, audit, and cancellation must still
+  happen before dynamic code starts.
+- The Sandbox SDK Durable Object is not optional ceremony. It is part of
+  Cloudflare's current Sandbox architecture and should remain while Sandbox SDK
+  is the shell/test execution provider.
+- For the current v1 toolset, using Dynamic Workers to replace Browser Run
+  Quick Actions or Sandbox SDK would be a downgrade: Dynamic Workers do not
+  provide Chrome sessions and do not provide a shell/container boundary.
+- Browser access should be liberal for public HTTPS targets and strict at trust
+  boundaries. Browser Run must not cross into private networks, authenticated
+  user accounts, Vibecodr infrastructure, or provider secrets without an
+  explicit future grant.
+
+## Adoption Gate
+
+Add Dynamic Workers only when at least one of these product capabilities exists:
+
+1. `tool.dynamic_worker.run`: execute a bounded JavaScript/Worker module as a
+   hosted tool.
+2. `tool.dynamic_worker.app`: reuse a stable user-defined Worker by ID.
+3. `tool.facet.run`: run a user-defined durable reducer/object behind a
+   supervisor Durable Object.
+4. `tool.dynamic_workflow.run`: run user-defined multi-step workflows that need
+   retries, sleep, waits, or approvals.
+
+Before shipping any of those capabilities:
+
+- Add a Worker Loader binding and generated Worker types.
+- Add strict module/source validation and output limits.
+- Disable outbound by default with `globalOutbound: null`.
+- Pass only least-privilege bindings or host proxies.
+- Reserve quota before loading dynamic code.
+- Record audit before and after dynamic code execution.
+- Add cancellation and timeout proof.
+- Add tests proving no raw platform secret, binding, D1, R2, Browser Run, or
+  Sandbox authority leaks into the dynamic code.
+
+## Current Conclusion
+
+I agree that Cloudflare's dynamic offerings are the right future substrate for
+agent-authored Worker code and user-defined durable logic. I disagree that they
+should replace the current `vc-tools` v1 Browser Run/Sandbox/D1/R2/Queue shape.
+
+The best production architecture is:
+
+- Keep the current control plane on platform-owned Worker, D1, R2, Queue,
+  Workflows, and explicit provider bindings.
+- Keep Browser Run Quick Actions as the default browser lane.
+- Keep Cloudflare Workflows as the durable paid `browser.agent_task` execution
+  lane, with Browser Run Sessions as the browser provider inside that Workflow.
+- Keep `browser.crawl_site` in that Quick Actions lane, with plan-owned page and
+  depth limits.
+- Keep Queues plus DLQ for stateless browser, sandbox, scheduled QA, and other
+  single-step work; do not use a universal Queue fairness delay for interactive
+  tools.
+- Keep Sandbox SDK for command/test execution, with the paid user-facing lane
+  split by plan: Creator `standard-1`, Pro `standard-2`.
+- Add Dynamic Workers/Facets later as a separate, explicitly named capability
+  family for supervised user-defined code, with no ambient platform authority.
+
+## Source Links
+
+- Cloudflare Dynamic Workers:
+  https://developers.cloudflare.com/dynamic-workers/getting-started/
+- Cloudflare Dynamic Workers API reference:
+  https://developers.cloudflare.com/dynamic-workers/api-reference/
+- Cloudflare Dynamic Workers custom limits:
+  https://developers.cloudflare.com/dynamic-workers/usage/limits/
+- Cloudflare Durable Object Facets:
+  https://developers.cloudflare.com/dynamic-workers/usage/durable-object-facets/
+- Cloudflare Dynamic Workflows:
+  https://developers.cloudflare.com/dynamic-workers/usage/dynamic-workflows/
+- Cloudflare Browser Run:
+  https://developers.cloudflare.com/browser-run/
+- Cloudflare Sandbox SDK architecture:
+  https://developers.cloudflare.com/sandbox/concepts/architecture/
+- Cloudflare Sandbox SDK Wrangler configuration:
+  https://developers.cloudflare.com/sandbox/configuration/wrangler/

package/docs/RELEASE-CHECKLIST.md

@@ -0,0 +1,297 @@
+# vc-tools Release Checklist
+
+Use this checklist before publishing `@vibecodr/vc-tools`.
+
+## Repository Boundary
+
+- `git rev-parse --show-toplevel` prints the `tools/vc-tools` repository root.
+- No files are staged or committed from the parent Vibecodr repository.
+- The package name is `@vibecodr/vc-tools`.
+- The binary name is `vc-tools`.
+- Environment variables use the `VC_TOOLS_*` namespace.
+- Stored credentials use the native credential store unless
+  `VC_TOOLS_CREDENTIAL_STORE=file` is explicitly set for tests.
+
+## Required Verification
+
+```powershell
+npm ci
+npm run check
+npm run check:worker
+npm test
+npm run build
+npm run verify:artifact
+npm run verify:goal
+npm run verify:release
+npm run verify
+node dist/bin/vc-tools.js --help
+node dist/bin/vc-tools.js help agent
+node dist/bin/vc-tools.js help computer
+node dist/bin/vc-tools.js help browser
+node dist/bin/vc-tools.js --quiet usage
+node dist/bin/vc-tools.js --json plans
+node dist/bin/vc-tools.js usage
+node dist/bin/vc-tools.js --json limits
+node dist/bin/vc-tools.js --json dashboard usage
+node dist/bin/vc-tools.js --json inspect
+node dist/bin/vc-tools.js --json browser render https://127.0.0.1
+npx wrangler deploy --dry-run --outdir tmp\wrangler-dry-run
+npx wrangler d1 migrations apply vc-tools-db --remote
+VC_TOOLS_RELEASE_CHANNEL=live npm run verify:release
+```
+
+Expected results:
+
+- TypeScript exits `0`.
+- Worker type generation and Worker TypeScript checks exit `0`.
+- Tests exit `0`.
+- Build exits `0`.
+- Package artifact verifier exits `0`.
+- Goal coverage verifier exits `0`.
+- Release readiness verifier exits `0` for `VC_TOOLS_RELEASE_CHANNEL=cli-contract`.
+- `VC_TOOLS_RELEASE_CHANNEL=live npm run verify:release` exits `0` only after
+  `live-hosted-production` is marked locally verified by fresh production smoke
+  evidence. It is expected to fail while that inspection is still
+  `hosted-required`.
+- Help identifies `vc-tools`, not `vibecodr`.
+- Help exposes examples, docs/support links, secure credential file/stdin
+  inputs, and command-specific help via both `vc-tools help <command>` and
+  `<command> --help`.
+- `--quiet` suppresses non-essential human success output while `--json` remains
+  stable.
+- `plans` works without auth using local launch packaging fallback.
+- `plans` includes Free, Creator, Pro, overage meters, and launch safety
+  policies.
+- `plans` fallback and `/v1/plans` are explicitly non-authoritative for actor
+  entitlement; `usage`/`limits` are the account-state surface and are marked
+  read-only/not client-mutable.
+- `usage` renders allotted limits, numeric usage, and 0-100% quota bars; `limits`
+  returns the same hosted usage state and keeps stable JSON.
+- `dashboard usage` and `dashboard cogs` return hosted dashboard URLs without
+  requiring or printing credentials.
+- `inspect` reports one hosted-required check for CLI-contract releases and zero
+  hosted-required checks after live production smoke.
+- Unsafe browser URL smoke exits non-zero before any hosted request.
+- The Worker returns health, MCP metadata, and fail-closed auth responses; tests
+  keep contract-mode coverage for no-cost route validation.
+- The contract-mode Worker supports MCP `initialize`, `tools/list`, and
+  `tools/call` JSON-RPC requests.
+- Hosted dashboard sections render overview, usage, activity, artifacts, grants,
+  retention, billing, and internal COGS launch-contract data.
+
+## Hosted Service Production Checks
+
+Run these after hosted Worker, D1, R2, Queue, Browser Run, Sandbox,
+`VC_TOOLS_BROWSER_RUN_ACCOUNT_ID`, `VC_TOOLS_BROWSER_RUN_API_TOKEN`, and the
+hosted/Browser/Sandbox account-cap vars plus `VC_TOOLS_CLI_GRANT_PUBLIC_JWKS`
+or the controlled static `VC_TOOLS_TOKEN_SHA256` secret are configured. Also configure
+`VC_TOOLS_INTERNAL_ALERT_TOKEN` through the repo-owned
+`scripts/vc-tools-secrets.ps1` flow; that script stores the managed alert signer
+in WinCred and uploads the same value to `vibecodr-internal-api` as
+`INTERNAL_BINDING_TOKEN_NEXT` so the current internal mesh token is not rotated
+just to enable vc-tools alerting. Keep the `VC_TOOLS_INTERNAL_API_WORKER`
+service binding deployed, confirm internal-api `ALERT_CODES` includes
+`E-VIBECODR-VC-TOOLS-SOFT-CAP`, and confirm internal-api has `NTFY_TOPIC`
+configured if ntfy delivery is expected. vc-tools operator emails are reserved
+for account-wide hosted, Browser Run, and Sandbox capacity pressure; per-user
+quota/usage pressure remains enforced and audit-visible without outbound
+operator email.
+For the public auth paths, also configure parent API Worker secrets
+`CLERK_SECRET_KEY` and `CLI_GRANT_PRIVATE_JWK`, set the parent/hosted grant
+audience to `vibecodr:vc-tools`, and set the hosted Worker
+`VC_TOOLS_CLI_GRANT_PUBLIC_JWKS` to the matching public JWKS. Legacy HMAC grants
+require `CLI_GRANT_LEGACY_HMAC_ENABLED="true"` and
+`VC_TOOLS_CLI_GRANT_LEGACY_HMAC_ENABLED="true"`, are beta/internal-only, and
+should be removed by 2026-06-30 after live ES256 smoke and migration:
+
+```powershell
+$env:VC_TOOLS_API_URL = "https://tools.vibecodr.space"
+vc-tools login
+vc-tools login --credential-file .\clerk-oauth-token.txt
+vc-tools login --credential-file .\vc-tools-api-key.txt
+vc-tools start --client codex
+vc-tools auth diagnose
+vc-tools agent connect --client codex
+vc-tools tools list
+vc-tools browser render https://example.com
+vc-tools browser screenshot https://example.com --format png
+vc-tools browser read https://example.com
+vc-tools browser pdf https://example.com
+vc-tools browser crawl https://example.com/docs --max-pages 5 --max-depth 1
+vc-tools browser ask https://example.com --timeout-ms 1200000 --idle-timeout-ms 600000 --instructions "Inspect the page and save a concise snapshot."
+vc-tools computer run "node --version"
+vc-tools usage
+vc-tools grants list
+vc-tools retention show
+```
+
+Expected hosted guarantees:
+
+- Auth secrets are configured as Worker secrets, not committed config.
+- Public human login uses `https://api.vibecodr.space/auth/vc-tools/device/*`;
+  the verification URI opens `/settings/vc-tools/approve?vc_tools_code=...`,
+  the browser approval response does not contain the grant, and the private
+  device code is not printed or persisted.
+- Public automation login accepts generic credential files/stdin, identifies
+  Clerk OAuth tokens or scoped Clerk API keys, and exchanges them through
+  `https://api.vibecodr.space/auth/cli/exchange`; explicit login paths store
+  the durable local credential so short-lived vc-tools grants can refresh.
+- 2026-05-15 live OAuth proof: Clerk PKCE from the production
+  `/agent/vibe` metadata completed through the in-app browser, and
+  `scripts/smoke-vc-tools-oauth-token.mjs` exchanged the returned Clerk access
+  token over stdin. Run `codex-oauth-20260515230549-tgn17r` passed
+  `login-oauth-token`, `whoami-oauth-token`, and `usage-oauth-token` with
+  `authMode=oauth`, `grantProfile=vc_tools`, scopes
+  `["vc-tools:use","vc-tools:*"]`, plan `Pro`, `providerMode=live`,
+  `secretPrinted=false`, and temporary config cleanup confirmed.
+- Vibecodr CLI grants include the `vc-tools:use` scope, the requested tool
+  scope such as `vc-tools:browser.render_url` or `vc-tools:*`, current plan,
+  subject, `grant_profile`, `kid`, `iat`, `nbf`, `exp`, `jti`, and
+  `vibecodr:vc-tools` audience; static-token fallback is reserved for
+  controlled deployments.
+- D1 migrations `0001_live_schema.sql`, `0002_actor_scope.sql`,
+  `0003_quota_reservations.sql`, and
+  `0004_sandbox_quota_reservations.sql`, and
+  `0005_operator_alert_dedupe.sql`, and
+  `0006_scheduled_qa.sql`, and `0007_job_queue_metadata.sql` are applied.
+- Browser/Sandbox calls are quota checked by the API before cost-bearing
+  Cloudflare work.
+- Operator kill switches must be known before launch: setting
+  `VC_TOOLS_PAUSE_COST_BEARING_JOBS=true` pauses all Browser/Sandbox work,
+  `VC_TOOLS_DISABLE_BROWSER_RUN=true` pauses Browser Run Quick Actions and
+  crawl, `VC_TOOLS_DISABLE_BROWSER_SESSIONS=true` pauses paid
+  `browser.agent_task`, and `VC_TOOLS_DISABLE_SANDBOX=true` pauses Sandbox.
+  Each pause returns `503 ops.cost_bearing_paused`, writes
+  `tools.cost_bearing_paused`, and avoids D1 job insertion and Queue/Workflow
+  dispatch.
+- Crossing hosted, Browser Run, or Sandbox account-wide 70%, 85%, or 95%
+  pressure emits a sanitized `E-VIBECODR-VC-TOOLS-SOFT-CAP` operator alert.
+  User quota/usage thresholds do not emit operator emails. Alerts flow through
+  internal-api email/ntfy fanout; optional
+  `VC_TOOLS_OPERATOR_ALERT_WEBHOOK_URLS` and `VC_TOOLS_OPERATOR_NTFY_TOPIC`
+  secrets are additive fallback channels. D1 dedupe suppresses repeats in the
+  same reset window, and missing notifier bindings are audit-visible.
+- Queue and DLQ backlog are checked by the scheduled Worker via
+  `JOB_QUEUE.metrics()` and `JOB_DLQ.metrics()` and emit sanitized
+  account-scoped `queue.backlog_messages` / `queue.dlq_messages` operator
+  alerts. Tune `VC_TOOLS_QUEUE_BACKLOG_SOFT_CAP`,
+  `VC_TOOLS_QUEUE_BACKLOG_HARD_CAP`, `VC_TOOLS_DLQ_MESSAGES_SOFT_CAP`, and
+  `VC_TOOLS_DLQ_MESSAGES_HARD_CAP` only as platform-level thresholds; do not
+  fan out per-user quota/usage alerts.
+- Account-wide active artifact storage is checked by summing active,
+  non-expired artifact bytes in D1 during the scheduled Worker pass and emits a
+  sanitized account-scoped `artifact.storage_gb` operator alert. Tune
+  `VC_TOOLS_ARTIFACT_STORAGE_ACCOUNT_SOFT_GB` and
+  `VC_TOOLS_ARTIFACT_STORAGE_ACCOUNT_HARD_GB` as platform-level thresholds,
+  separate from the customer plan allotment SSOT.
+- Expired-artifact cleanup failures emit the account-scoped
+  `E-VIBECODR-VC-TOOLS-RETENTION-CLEANUP-FAILED` /
+  `retention.cleanup_failed` operator alert. Keep this code in the parent
+  internal-api `ALERT_CODES` allowlist alongside
+  `E-VIBECODR-VC-TOOLS-SOFT-CAP`; internal-api filters all user-scoped
+  `source=vc-tools` payloads before email/ntfy fanout.
+- Browser Run and Sandbox execution failure/timeout rates are checked from
+  recent terminal job rows during the scheduled Worker pass and emit the
+  account-scoped `E-VIBECODR-VC-TOOLS-EXECUTION-HEALTH-DEGRADED` alert with
+  `browser.failure_rate`, `browser.timeout_rate`, `sandbox.failure_rate`, or
+  `sandbox.timeout_rate`. Tune
+  `VC_TOOLS_EXECUTION_HEALTH_WINDOW_MINUTES`,
+  `VC_TOOLS_EXECUTION_HEALTH_MIN_TERMINAL_JOBS`,
+  `VC_TOOLS_FAILURE_RATE_ALERT_PERCENT`, and
+  `VC_TOOLS_TIMEOUT_RATE_ALERT_PERCENT` as platform-level thresholds.
+- Unexpected hosted Worker HTTP 500s emit the account-scoped
+  `E-VIBECODR-VC-TOOLS-HOSTED-WORKER-5XX` /
+  `hosted.worker_5xx` operator alert through the same fanout path. Keep this
+  code in parent internal-api `ALERT_CODES`; payloads must stay sanitized to
+  method, path pattern, status, and redacted error text only.
+- Hosted API/MCP auth failures write anonymous `auth.failed` audit rows. The
+  scheduled Worker aggregates them and emits the account-scoped
+  `E-VIBECODR-VC-TOOLS-AUTH-FAILURE-ANOMALY` /
+  `auth.failure_anomaly` operator alert when
+  `VC_TOOLS_AUTH_FAILURE_ALERT_THRESHOLD` is crossed inside
+  `VC_TOOLS_AUTH_FAILURE_WINDOW_MINUTES`. Keep this code in parent internal-api
+  `ALERT_CODES`; payloads must stay token/query/body/actor-free.
+- Cloudflare spend anomaly checks are internal account-level early warnings,
+  not user notifications and not invoice-backed billing truth. The scheduled
+  Worker estimates current-month raw cost from vc-tools COGS meters and
+  env-configured assumptions, then emits the account-scoped
+  `E-VIBECODR-VC-TOOLS-CLOUDFLARE-SPEND-ANOMALY` /
+  `cloudflare.estimated_spend_usd` alert when
+  `VC_TOOLS_CLOUDFLARE_SPEND_SOFT_USD` is crossed. Keep this code in parent
+  internal-api `ALERT_CODES`, tune
+  `VC_TOOLS_CLOUDFLARE_SPEND_SOFT_USD` and
+  `VC_TOOLS_CLOUDFLARE_SPEND_HARD_USD` only as platform thresholds, and compare
+  any alert with Cloudflare Billable Usage / Budget Alerts before raising
+  capacity or changing pricing.
+- Unsafe URL and quota denials write analytics-only D1 audit metrics as
+  `tools.denied_unsafe_url` and `tools.denied_quota`. These are intentionally
+  per-actor COGS/ops signals and must not be promoted into email/ntfy fanout.
+- `/dashboard/cogs` renders internal-only cost pressure by actor, plan, surface,
+  warning threshold, and env-configured cost assumptions.
+- Jobs, artifacts, usage, retention, and audit rows are scoped to the
+  authenticated actor.
+- All tool calls are logged by the hosted service without secrets before
+  Queue/Workflow dispatch.
+- Stateless browser jobs complete through Browser Run Quick Actions and produce
+  R2 artifacts with metered browser time; paid browser agent jobs complete
+  through Workflow-owned Browser Sessions with closure metadata.
+- 2026-05-17 Workflow migration smoke: deployed `vc-tools-api`
+  `aeeaab85-93ab-4219-acf7-fffbe2be834e` at 100%, then completed synthetic
+  Creator `browser.agent_task`
+  `job_0e8b0cc2-9a3c-4791-8e77-ce0da1191a3c` with
+  `queue_delay_seconds=0`, `reserved_browser_seconds=120`, D1 audit event
+  `tools.workflow_started`, and R2 artifact
+  `art_466de507-1432-41eb-9253-c9f79aac8148` downloaded through
+  `vc-tools proof save`.
+- Scheduled QA create/list/update/delete works for a paid actor; explicit
+  `--run-now` create/resume enqueues immediately, and due configs are enqueued
+  by the Worker cron into the same D1 jobs and Queue path as manual Browser
+  Quick Actions, with run/readback evidence and no cookies, credentials, or
+  private targets accepted. Monthly cap denial leaves `lastJobId=null` and a
+  skipped run row with `quota.scheduled_qa_monthly_runs_exceeded`. Natural
+  cron-tick readback should be captured at a real deployed trigger time because
+  Cloudflare's fire-now cron route is local Wrangler-dev-only.
+- Creator browser agent tasks complete through the `BROWSER` Browser Session
+  binding at up to 20 minutes; Pro browser agent tasks complete through the
+  same binding at up to 1 hour. Both close in `finally`, record closure
+  metadata/audit, and produce R2 artifacts.
+- Browser crawl jobs complete through Browser Run `/crawl`, produce R2 crawl
+  artifacts, and write crawl-page usage.
+- Browser jobs reject unsafe initial URLs, DNS records without A/AAAA answers,
+  unsafe redirects/subrequests, and unsafe final URLs.
+- Creator sandbox jobs complete through Sandbox SDK `standard-1`; Pro sandbox
+  jobs complete through the `ProSandbox` `standard-2` lane; Creator is capped
+  at 10 minutes, Pro at 30 minutes, both paid plans cap active sandbox tasks at
+  2 per user, and both produce R2 artifacts.
+- Queue failures are bounded by the `vc-tools-jobs` consumer config:
+  `max_batch_size=1`, `max_retries=3`, and
+  `dead_letter_queue="vc-tools-jobs-dlq"`. A failed job message may rethrow only
+  inside that retry window so Cloudflare can move it to the DLQ; retry
+  deliveries of an already-failed job must not re-run Browser, Sandbox, R2, or
+  other cost-bearing provider work.
+- DLQ replay is operator-controlled, not automatic. Before replaying a message
+  from `vc-tools-jobs-dlq`, fix the root cause, inspect and redact the message
+  body, correlate the job id and actor id against D1 `jobs` and `audit_events`,
+  confirm the payload is still a valid `ToolJobMessage`, and re-send only the
+  intended message body into `vc-tools-jobs` with a fresh audit note. Do not
+  attach a broad automatic DLQ consumer or replay unknown payloads.
+- `/v1/usage` reflects browser and sandbox job usage after the smoke.
+- Sandbox network remains disabled unless a grant and explicit request allow it.
+- Browser recordings remain off by default.
+- Authenticated browsing is not available to Creator or ordinary users by default.
+
+## Publish Readiness
+
+- `npm pack --dry-run` shows only intended package files.
+- The public npm artifact contains only `dist`, `README.md`, `LICENSE`, and
+  `package.json`; repository-maintainer docs, hosted Worker source, migrations,
+  deployment config, tests, and scripts stay out of the package.
+- Runtime `dependencies` contain only CLI-installed dependencies. Cloudflare
+  platform primitive packages stay in repository development dependencies for
+  hosted Worker verification and deployment.
+- No token-like string appears in `dist`, docs, test fixtures, or package
+  metadata.
+- `docs/API-CONTRACT.md` matches the hosted service route contract.
+- `docs/VALIDATION-MATRIX.md` maps every goal-file command and safety gate to
+  implementation evidence.
+- Release notes mention any hosted-service dependency that is degraded or paused.