@vibecodr/cli 0.2.11 → 1.0.0-rc.0

package/docs/SECURITY.md

@@ -0,0 +1,227 @@
+# vc-tools Security Notes
+
+`vc-tools` is a trust-boundary CLI. It validates local input before submitting
+requests to the hosted Vibecodr Tools API, but the hosted API remains the source
+of truth for auth, grants, quota, audit logging, retention, and Cloudflare
+credential custody.
+
+## Local Rules
+
+- Plain `vc-tools login` is the default human path. It starts a browser/device
+  approval session, prints a user-checkable code, optionally opens the Vibecodr
+  approval page, and stores the durable credential returned to the polling CLI
+  when the parent API issues one. The browser approval response must never
+  include the signed grant, API key, OAuth token, refresh token, or private
+  device code.
+- Non-interactive credentials are preferably accepted through
+  `--credential-file`, `--credential-stdin`, `VC_TOOLS_CREDENTIAL_FILE`, or
+  local credentials. The input may be an existing vc-tools grant, a Clerk OAuth
+  access token, or a scoped Clerk API key.
+- Clerk OAuth access tokens and scoped Clerk API keys are exchanged through
+  Vibecodr Auth for short-lived scoped `vc-tools` grants. When supplied through
+  an explicit login path, they may be stored as the durable local credential so
+  future grants refresh automatically without another human approval.
+- Direct secret value flags and secret value environment variables
+  (`--credential`, `--token`, `VC_TOOLS_CREDENTIAL`, `VC_TOOLS_TOKEN`) remain
+  compatibility inputs for controlled automation, but public docs should prefer
+  file/stdin/native credential paths to avoid shell-history, process-list, and
+  environment leakage.
+- The local auth SSOT is account-wide: one durable local credential plus a
+  cached short-lived grant. Direct vc-tools grants can still be cached, but they
+  are not refreshable and should be treated as advanced/temporary credentials.
+- Stored credentials use the native OS credential store by default through
+  `@napi-rs/keyring`. The file-backed credential store is only for local
+  automation and must be explicitly selected with `VC_TOOLS_CREDENTIAL_STORE=file`.
+- Authority-bearing tokens are redacted from stdout, stderr, JSON responses,
+  warnings, hosted provider error details, and API error details. Safe operator
+  handles and counters such as `artifactId`, `jobId`, `requestId`, `traceId`,
+  `tokenCount`, `totalTokens`, and `tokenKind` remain visible so operators can
+  debug without seeing reusable authority.
+- API URLs must use HTTPS. Local HTTP API URLs are denied unless the operator
+  explicitly passes `--allow-insecure-local-api` or sets
+  `VC_TOOLS_ALLOW_INSECURE_LOCAL_API=true` for local development. This prevents a
+  poisoned local config or environment variable from receiving a stored token.
+- Browser URLs must use HTTPS and must not target localhost, private IP ranges,
+  link-local ranges, multicast/unspecified ranges, internal hostnames, or URL
+  credentials. IPv6 loopback, unique-local, link-local, IPv4-mapped, NAT64, and
+  6to4 forms are denied before remote browser calls.
+- Sandbox commands are remote submissions only. The CLI never executes them
+  locally.
+- Paid sandbox network access permits public HTTP(S) package/docs requests by
+  default. Cloudflare host policy plus the hosted outbound handler block URL
+  credentials, private/local/link-local/metadata/internal hosts, and hostnames
+  resolving to those ranges.
+- Mutations require explicit confirmation flags.
+- `--quiet`, `--no-input`, and `--no-color` are accepted CLI convention flags;
+  the CLI does not prompt or emit color by default.
+- Artifact downloads must stay inside the current workspace unless a future
+  release adds an explicitly audited export mode. Users may target a directory
+  or an explicit file path inside the workspace, and `--filename` names the file
+  inside a directory output without weakening the workspace boundary.
+- Artifact downloads resolve existing output paths and nearest existing parents
+  through real paths so symlinked or junctioned directories cannot redirect a
+  pull outside the workspace.
+- Artifact uploads must also originate inside the current workspace.
+- Artifact upload size is enforced by the hosted service from the active plan
+  contract, not by a separate CLI hardcode.
+
+## Hosted Service Rules
+
+The API must enforce these before any cost-bearing Cloudflare work:
+
+- user authentication
+- browser/device vc-tools login sessions in the parent Vibecodr API, stored as
+  hashed device and user codes, single-use on redemption, and expired quickly
+- Clerk OAuth/API-key verification in the parent Vibecodr Auth API before any
+  public user receives a `vc-tools` grant
+- scoped Vibecodr CLI grants with `vc-tools:use` plus a requested tool scope
+  such as `vc-tools:browser.render_url` or `vc-tools:*`, or an explicitly
+  configured static-token fallback for controlled deployments
+- vc-tools grant audience validation. Hosted Tools accepts only grants intended
+  for `vibecodr:vc-tools`, not broader Vibecodr CLI/API tokens.
+- actor-scoped job, artifact, usage, retention, and audit rows
+- authenticated hosted inspection and dashboard routes
+- workspace/project/user grant checks
+- plan entitlement checks
+- quota/spend checks
+- abuse/rate-limit checks
+- audit-log emission
+- retention policy classification
+- Browser Run policy: initial URL, DNS address records, and bounded redirect
+  chains must remain public HTTPS targets before cost-bearing dispatch and
+  before the hosted Quick Action or Workflow-owned paid Browser Session request
+  is sent; `browser.agent_task` is paid-only, capped at 20 minutes on Creator
+  and 1 hour on Pro, closes after 10 minutes without meaningful action/artifact
+  progress, and closes the browser in `finally` after storing a bounded artifact
+  plus closure metadata in the job result and audit stream
+- Browser mode policy: public-web browsing is broad by default for public HTTPS
+  targets, while authenticated third-party sessions, private networks,
+  Vibecodr-owned infrastructure, and provider credentials remain isolated unless
+  a future explicit grant opens a narrow lane
+- Browser auth boundary: hosted browser calls reject cookies, credentials,
+  authorization headers, custom auth headers, storage state, sessions, or
+  secrets before provider execution
+- Browser Run crawl policy: bounded public crawls use the same URL/DNS guards,
+  plan page/depth caps, hosted artifact retention, and usage metering as other
+  browser tools
+- Browser Run provider-pressure policy: provider 429 responses return queued
+  jobs to a retry/defer state instead of exposing provider secrets or marking
+  the job failed on first rate-limit pressure
+- Hosted capacity policy: Queue consumer concurrency, Workflow-owned Browser
+  Agent execution, Browser Run account caps, Sandbox account caps, and Sandbox
+  container `max_instances` are aligned to a 30-active-job launch ceiling so
+  plan entitlements cannot stampede the hosted Cloudflare account; Creator
+  sandbox jobs route to Cloudflare `standard-1` containers with 10-minute task
+  caps and Pro sandbox jobs route to `standard-2` containers with 30-minute task
+  caps instead of the `lite` lane; both paid plans cap active sandbox tasks at 2
+  per user
+- Sandbox quota policy: monthly sandbox seconds are reserved atomically before
+  queue insertion and reconciled when sandbox jobs are cancelled or reach a
+  terminal state
+- Sandbox egress policy: paid Agent Computer jobs can use public HTTP(S) egress
+  for package installs and public docs. Private/local/link-local/metadata/
+  internal CIDRs and host suffixes are denied by Cloudflare Sandbox host policy,
+  HTTPS interception is enabled on the Sandbox classes, and every HTTP(S)
+  request is rechecked in the outbound handler before forwarding. Raw non-HTTP
+  internet stays closed by the Sandbox startup policy.
+- Queue execution policy: the consumer checks current D1 job state before
+  setting a queued job to running, so a job canceled before delivery is marked
+  cancelled and skipped before stateless Browser Run Quick Action or Sandbox
+  work starts. Queue consumers reject `browser.agent_task`; Browser Agent work is
+  owned by the Cloudflare Workflow lane.
+- Admission fairness policy: accepted repeat-actor jobs expose metadata-only
+  queued-ahead counts without leaking payloads or adding a universal delay to
+  interactive tools. Scheduled QA may still use bounded Cloudflare Queue
+  per-message delays to spread due runs.
+- Queue completion policy: the consumer rechecks current D1 job state after
+  execution and cannot mark a job completed if cancellation was requested while
+  it was running
+- Retention policy: artifact retention is capped by the active plan, expired
+  artifacts are hidden from list/get/download paths, and a scheduled cleanup
+  removes expired R2 objects plus D1 metadata
+- Artifact storage policy: uploaded and generated artifacts are checked against
+  active actor storage before writes, D1 metadata insertion repeats the storage
+  predicate, and newly written R2 bytes are deleted if that metadata reservation
+  fails
+- Artifact deletion is actor-scoped and explicit: the hosted Worker deletes the
+  R2 object and D1 shelf row for the authenticated actor, and CLI deletion
+  requires `--yes`
+
+The CLI's validation is a usability and early-safety layer. It is not a
+replacement for hosted enforcement.
+
+## Open-Source Client Boundary
+
+The public `@vibecodr/vc-tools` package is a client/control-plane helper, not
+the quota or billing authority. Users can fork or edit the local CLI, local
+fallback plan constants, local help text, and local development API targets, but
+those edits do not change the official hosted service.
+
+Authoritative state remains hosted:
+
+- Vibecodr Auth verifies Clerk OAuth/API-key inputs passed through the generic
+  credential path and issues scoped `vc-tools` grants.
+- The hosted Tools API resolves the authenticated actor, plan, grants, and
+  server-side limits.
+- `/v1/usage` and the `usage.read` MCP tool expose read-only hosted account
+  state. In live mode the response is marked authoritative and
+  `mutableByClient: false`. User-facing usage and readiness responses stay
+  account-scoped: operator alert configuration, internal binding presence,
+  provider account caps, hosted account pressure, ntfy/webhook topics, and raw
+  actor ids belong only on operator-scoped endpoints.
+- `/v1/plans` and local fallback plan constants are packaging/reference data.
+  They are not authoritative for an actor's entitlement, usage, billing, quota,
+  or provider execution.
+- Cost-bearing Browser Run and Sandbox work is accepted only after hosted auth,
+  grant, plan, quota, audit, and reservation checks.
+
+If a user points `VC_TOOLS_API_URL` or `--api-url` at a forked service, that
+service can return different local display data. It is not Vibecodr Tools Cloud
+authority and cannot spend Vibecodr provider credentials or mutate official D1,
+R2, Queue, billing, grant, or usage state.
+
+## Remaining Hosted Proofs
+
+Local validation verifies the shipped control surface and contract behavior. A
+live production release must still produce fresh smoke evidence for:
+
+- deployed Worker secrets and routes
+- D1 migrations, including actor-scope columns
+- real Browser Run Quick Action execution with SSRF guards and metered-time
+  usage active
+- real Browser Run crawl execution with R2 artifact readback and crawl-page
+  usage active
+- real Sandbox execution with public HTTP(S) egress and private/internal denial
+- real Pro `standard-2` Sandbox execution after the split lane is deployed
+- R2 artifact download scoped to the authenticated actor
+- usage/quota counters scoped to the authenticated actor
+- audit rows written before cost-bearing Queue/Workflow dispatch
+
+## Secret Handling
+
+Do not add debug flags that print raw request headers, environment variables,
+stored credentials, Cloudflare tokens, OAuth tokens, or hosted API responses
+without redaction.
+
+Clerk server secrets and the ES256 `CLI_GRANT_PRIVATE_JWK` belong only in the
+parent Vibecodr API Worker secrets. The hosted Worker receives only
+`VC_TOOLS_CLI_GRANT_PUBLIC_JWKS` for normal vc-tools grants, plus
+`VC_TOOLS_TOKEN_SHA256`, `VC_TOOLS_INTERNAL_ALERT_TOKEN`, optional operator
+alert webhook/ntfy secrets, and Cloudflare provider credentials as hosted
+Worker secrets. Legacy HMAC grant secrets are beta/internal-only, require
+the explicit `*_LEGACY_HMAC_ENABLED="true"` switches on both parent and hosted
+surfaces, and should be removed by 2026-06-30 after live ES256 smoke and
+migration. None of those values belong in source, Wrangler plaintext vars, docs,
+tests, or package artifacts. Soft-cap operator alerts are account-wide capacity
+signals only and must remain metadata-only: surface, capability, plan name,
+current usage, included limit, percent used, and suggested action are allowed;
+raw commands, target URLs, bearer tokens, provider API tokens, actor
+identifiers, artifact contents, and user cookies are not. Per-user usage and
+quota pressure stays in usage/COGS/audit analytics without outbound operator
+notification fanout. D1 alert dedupe/reset-window rows may store capacity
+metadata details and suppression counts, but not user payload contents.
+
+The public npm artifact is a CLI/client package. Hosted Worker source,
+migrations, deployment configuration, repository-maintainer docs, and
+Cloudflare platform primitive packages must not be shipped as public CLI
+runtime surface.

package/docs/VALIDATION-MATRIX.md

@@ -0,0 +1,58 @@
+# vc-tools Validation Matrix
+
+This file maps `goal.md` and the `vc-tools-goal.md` product requirements to concrete CLI
+artifacts and tests.
+
+| Goal requirement | CLI artifact | Validation |
+| --- | --- | --- |
+| Separate tool from Vibecodr CLI | package `@vibecodr/vc-tools`, bin `vc-tools`, `VC_TOOLS_*` env namespace | `test/cli.behavior.test.ts` verifies help/version identity |
+| CLI Guidelines compliance | `src/cli/parser.ts`, `src/cli/run.ts`, `src/cli/output.ts`, `docs/CLI-GUIDELINES-AUDIT.md` | tests verify command-specific help, docs/support links, typo suggestions, stable JSON, product-safe default output, quiet mode, agent-computer primary nouns, and secure credential file/stdin sources |
+| Agent Computer first-use path | `vc-tools start`, `vc-tools setup`, `vc-tools try`, `vc-tools agent connect/status`, `vc-tools computer status` | tests verify `start` checks account identity, hosted health, MCP connection metadata, usage state, safe readiness output, and agent-native connection details without exposing tokens; `try` proves auth, hosted API, browser, computer, proof saving, and usage readback |
+| CLI login and auth diagnostics | `vc-tools login`, `vc-tools auth status`, `vc-tools auth diagnose`, `vc-tools auth export-agent-env`, safe generic credential file/stdin forms | tests verify browser/device auth starts when no credential is provided, `start` recovers from unreadable stored approval state by opening the normal browser login path, cost-bearing browser commands treat unreadable stored approval as missing auth instead of failing on credential storage shape, the private device code is never printed or stored, approval metadata points to `/settings/vc-tools/approve`, `--no-input` refuses interactive login without network calls, direct token grant caching, generic credential classification for Clerk OAuth/API-key exchange through Vibecodr Auth, durable API-key/OAuth local storage, expired grant refresh from stored API keys, file/stdin credential paths, one-off env credential auth without persistence, status reporting for active credential sources without exposing internal profiles, ambiguous credential denial, redaction, optional API verification, explicit file-store test mode, friendly expired-login errors, isolated config warnings, strict-permission agent credential-file export without printing the secret, and no stored-token forwarding to insecure local API URLs unless explicitly allowed |
+| Remote agent connection setup | `vc-tools agent connect`, advanced `vc-tools connect` | tests verify Streamable HTTP metadata, agent-native tool names, and no token leakage |
+| Remote MCP tool server | `/mcp` in `src/hosted/worker.ts` | tests verify MCP `initialize`, `tools/list`, and `tools/call` JSON-RPC contract flow with agent-native `browser.*`, `computer.*`, `work.*`, `proof.*`, and `usage.status` tool names mapped to hosted canonical capabilities |
+| Browser render/screenshot/markdown/PDF tests, crawl, snapshot, and paid agent tasks | `vc-tools browser *`, advanced `vc-tools tools test browser.*` | tests verify capability aliases including `browser.snapshot`, canonical browser and crawl payloads, default submit/wait behavior, `--out` proof saving without exposed IDs, Creator `browser.agent_task` acceptance up to 20 minutes, Pro acceptance up to 1 hour, Free denial, Quick Actions staying short, HTTPS-only validation, localhost/private/internal denial with safe-next-action messaging, URL credential denial, direct cookie/header/storage-state auth material denial, IPv4/IPv6 private, link-local, mapped, NAT64, and 6to4 denial, hosted unsafe redirect-chain denial before cost-bearing dispatch, and Workflow dispatch for paid browser agent tasks |
+| Agent Computer run/tests | `vc-tools computer run/test`, advanced `vc-tools tools test sandbox.*`, hosted Sandbox SDK queue execution | tests verify no local shell execution, bounded command payload, default submit/wait behavior, `--out` proof saving without exposed IDs, public HTTP(S) package/docs egress by default for paid Agent Computer jobs, explicit `--network public`/`--network off` payloads, no private-network opt-in flag, no per-command host allowlist requirement, Cloudflare host policy plus hosted outbound handler denial for private/local/internal destinations and private-resolving DNS, per-command Sandbox SDK timeout forwarding, timeout/fork-storm failure cleanup through sandbox teardown, minimal sandbox env injection, stdout/stderr truncation, sandbox-returned files/output-file paths ignored in favor of one fixed transcript artifact, artifact storage accounting, and sandbox-minute metering |
+| Proof store/read/save/delete | `vc-tools proof list/show/save/delete`, advanced `vc-tools artifacts list/get/pull/create/delete` | tests verify metadata shape, bounded list limits, safe filenames, overwrite guard, explicit in-workspace pull file targets, automatic proof saving from browser/computer aliases and `work follow --out`, explicit confirmation before delete, actor-scoped hosted deletion of D1 shelf rows plus R2 bytes, hosted plan-owned upload caps, hard total artifact storage caps, R2 cleanup after D1 reservation races, workspace-bounded upload/download paths, and symlink/junction escape denial |
+| Work status/cancel/list | `vc-tools work list/show/follow/cancel`, advanced `vc-tools jobs list/status/cancel` | tests verify list limit propagation, ID validation, alias routing, real follow polling until terminal status, optional terminal proof saving, queued fairness-delay metadata in status output, and `--yes` on cancellation |
+| Usage quotas and limits | `vc-tools usage`, `vc-tools limits`, `usage.status`/`usage.read` MCP tools | tests verify stable JSON output, human quota bars, alias routing, warning preservation, and no operator-only alert/account-pressure metadata in user-facing usage payloads |
+| Open-source client authority boundary | `vc-tools plans`, `/v1/plans`, `/v1/usage`, `/v1/health`, `/v1/mcp/connection`, `usage.read`, docs/SECURITY.md | tests verify local plan fallback is marked non-authoritative, hosted plan packaging is not actor entitlement authority, usage snapshots are read-only/not client-mutable, default product JSON excludes internal/future/operator/provider/auth metadata, and internal/future launch metadata plus overage-meter details are actor/operator-scoped instead of global while keeping operator readiness on operator-scoped endpoints |
+| Account identity | `vc-tools whoami`, `/v1/me` | tests verify the standard whoami command reads hosted identity and prints account-first Agent Computer output plus redacted payload data, and hosted JSON omits synthetic `@vibecodr.local` email fallbacks |
+| Tool grants | `vc-tools grants`, `vc-tools grants list` | tests verify default list routing and scoped grant rendering |
+| Retention settings | `vc-tools retention show/set` | tests verify day bounds, plan-capped artifact retention, recordings policy, `--yes` on mutation |
+| Usage dashboard | `vc-tools dashboard [section]` | tests verify safe dashboard section URL generation without auth leakage and shared API URL validation |
+| Plan packaging | `vc-tools plans` | tests verify local fallback plan contract and hosted response handling |
+| Free/Creator/Pro plan limits | `DEFAULT_PLANS`, `OVERAGE_METERS` in `src/core/contracts.ts` | `test/limits.test.ts` verifies the exact Free, Creator, and Pro launch matrix: prices, monthly/daily VC Tool credits, browser seconds, Creator 20-minute and Pro 1-hour Browser Session caps, crawl caps, scheduled QA, Creator `standard-1`/10-minute sandbox lane, Pro `standard-2`/30-minute sandbox lane, shared paid 2-active-sandbox cap, per-upload artifact caps, artifact limits, and compatibility meters |
+| Separate ledgers | Parent `PLAN_LIMITS[*].builds`, parent `PLAN_LIMITS[*].vcTools`, hosted `enforceQuota` | tests verify build seconds reserve independently from VC Tool credits; hosted quota checks count browser and sandbox work against one VC Tools ledger before Queue/Workflow dispatch; hosted quota tests deny plan-specific active browser run caps for Free/Creator/Pro plus monthly credit, daily credit, browser-second, and sandbox-second exhaustion before cost-bearing dispatch; a parallel atomic reservation race test proves only one dispatch wins when two requests contend for the same reservation window |
+| Account-wide hosted capacity breakers | parent `VC_TOOLS_GLOBAL_LIMITS`, child hosted/Browser Run/Sandbox account cap vars and kill-switch vars, Workflow binding, queue `max_concurrency`, container `max_instances`, scheduled-only bounded per-message Queue delays, internal-api alert codes, D1 `operator_alert_dedupe`, `JOB_QUEUE.metrics()`, `JOB_DLQ.metrics()`, account-wide active artifact bytes, expired-artifact cleanup failure alert, execution-health failure/timeout alert, hosted Worker 5xx alert, auth failure anomaly alert, Cloudflare spend anomaly alert, and API contract docs | parent tests verify soft/hard cap policy and filter all user-scoped vc-tools payloads before fanout; hosted tests verify browser and sandbox jobs do not start above hard caps, repeat-actor jobs report queued-ahead metadata without delaying interactive Queue sends, Browser Agent jobs create `BROWSER_AGENT_WORKFLOW` instances instead of Queue messages, Queue consumers reject Browser Agent execution, hard caps are operator-configurable, `VC_TOOLS_PAUSE_COST_BEARING_JOBS` pauses all cost-bearing work before D1 job insertion or Queue/Workflow dispatch, `VC_TOOLS_DISABLE_BROWSER_RUN`, `VC_TOOLS_DISABLE_BROWSER_SESSIONS`, and `VC_TOOLS_DISABLE_SANDBOX` pause their lanes separately, 70/85/95 soft-cap crossings fan sanitized alerts to internal-api plus ntfy/webhook surfaces, duplicate crossings in the same reset window are suppressed, missing notifier bindings are audit-visible, scheduled Queue/DLQ/artifact-storage/retention-cleanup/execution-health/auth-failure/Cloudflare-spend alerts stay account-scoped without user fanout, unexpected hosted 500 alerts omit user/query/token data, and auth-failure metrics omit token/query material |
+| Dashboard sections | `DASHBOARD_SECTIONS` and `OPERATOR_DASHBOARD_SECTIONS` in `src/core/contracts.ts`, authenticated hosted `/dashboard/*` | tests verify unauthenticated dashboard access is denied, authenticated customer dashboard sections stay beta-safe without internal/future billing metadata, configured internal-metadata actors can still inspect that launch metadata, the CLI does not print the internal COGS URL, customer grants cannot read `/dashboard/cogs/`, and an explicit operator grant can read the internal COGS section |
+| Tool grants | `LAUNCH_TOOL_GRANTS` in `src/core/contracts.ts`, hosted `/v1/grants` | tests verify workspace-scoped sandbox network metadata and paid-alpha grants |
+| No raw provider credential exposure | hosted API boundary only; CLI stores Vibecodr account credentials, not Cloudflare/provider credentials | redaction tests verify authority-bearing token values are hidden while safe operator handles/counters stay visible; OAuth/API-key exchange tests verify durable local storage plus output redaction; docs contract |
+| All tool calls quota-checked and logged | API contract requires hosted enforcement; CLI submits through `/v1/tools/test` only | hosted tests verify quota lookup before Queue/Workflow dispatch, audit/job state before Queue send or Workflow create, quota-denial audit metrics, and unsafe-URL denial audit metrics without notification fanout |
+| Browser Run timeout mapping | `src/hosted/worker.ts` Quick Action payload builders and Browser Session navigation | hosted tests verify Quick Action `goToOptions.timeout` clamps to 60s, non-PDF Quick Actions stay on a minimal provider-compatible payload without top-level `actionTimeout`, PDF keeps its documented `pdfOptions.timeout`, dynamic public-page navigation uses Cloudflare's recommended `networkidle2` default instead of the stricter `networkidle0`, Browser Sessions launch with bounded `keep_alive`, and Browser Session large-page navigation timeout failures close the browser, mark the job failed, and do not write artifacts or browser-minute usage |
+| Browser Run crawl provider path | `browser.crawl_site`, hosted `/crawl` Quick Action integration | CLI tests verify `browser.crawl` payloads; hosted tests verify crawl start, result fetch, artifact storage, browser-minute usage, and crawl-page usage |
+| Browser Run provider retry/defer | `src/hosted/worker.ts` queue failure handling | hosted tests verify provider 429 responses return jobs to queued/retryable state and do not mark them failed on first rate-limit pressure |
+| Human-use security hardening | CLI and hosted Worker trust-boundary controls | tests verify insecure local API opt-in, workspace-bounded artifacts including symlink/junction denial, scoped Vibecodr CLI grants with per-tool capability scopes, actor-scoped live job/artifact/usage/audit SQL, DNS address-record and redirect-chain enforcement with denial metrics, authenticated-browser material denial, Browser Run Quick Action routing and metered time, crawl metering, paid sandbox public HTTP(S) egress with private/local/internal denial, quota denial metrics, pre-execution and during-execution cancellation guards, hard artifact storage caps, D1/R2 artifact write cleanup, explicit artifact deletion cleanup, and retention-backed artifact expiry |
+| Hosted API/MCP scaffold | `src/hosted/worker.ts`, `wrangler.jsonc`, `migrations/0001_live_schema.sql`, `migrations/0002_actor_scope.sql`, `migrations/0003_quota_reservations.sql`, `migrations/0004_sandbox_quota_reservations.sql`, `migrations/0005_operator_alert_dedupe.sql`, `migrations/0006_scheduled_qa.sql`, `migrations/0007_job_queue_metadata.sql` | `npm run check:worker` and `test/hosted-worker.test.ts` verify health, auth fail-closed behavior, auth-failure audit metrics, user-safe public readiness, protected inspection/dashboard routes, scoped CLI grants, capability-scope denial, MCP metadata, MCP tool flow, dashboard contract, actor-scoped live acceptance, atomic quota reservation including sandbox seconds and parallel race conflict handling, queued-ahead metadata without interactive fairness delay, Workflow-owned paid agent browser dispatch without a Queue binding, Queue rejection for Browser Agent execution, Browser Run Quick Action hard-cap deferral, Browser Session hard-cap deferral, Sandbox hard-cap deferral, provider retry/defer handling, Browser Run large-page timeout bounds, failed-job DLQ retry-boundary behavior without provider re-execution, exhausted failed-job loop prevention, scheduled Queue/DLQ/artifact-storage/retention-cleanup/execution-health/auth-failure/Cloudflare-spend alerting, unexpected hosted 500 alerting, crawl artifacts, scheduled QA config/create/list/run-now enqueue/cron enqueue, sandbox execution timeout/env/output/teardown behavior, sandbox timeout/fork-storm failure cleanup, sandbox-returned file/path suppression, sandbox reservation reconciliation, unsafe redirect rejection before cost-bearing dispatch, D1-backed operator alert dedupe, and contract-mode tool acceptance |
+| Live Cloudflare provider | `src/hosted/worker.ts`, `wrangler.jsonc`, `Dockerfile`, `migrations/0001_live_schema.sql`, `migrations/0002_actor_scope.sql`, `migrations/0003_quota_reservations.sql`, `migrations/0004_sandbox_quota_reservations.sql`, `migrations/0005_operator_alert_dedupe.sql`, `migrations/0006_scheduled_qa.sql`, `migrations/0007_job_queue_metadata.sql` | hosted-required for live releases: apply all migrations, set Browser Run Quick Actions secrets and `BROWSER_AGENT_WORKFLOW`, deploy, then smoke health, authenticated login, real Quick Action browser job, real scheduled QA create/list/run-now enqueue/job-readback/monthly-cap denial plus natural cron-tick readback at a real trigger time, real Creator browser agent-task job through `BROWSER_AGENT_WORKFLOW`/`BROWSER`, real Pro browser agent-task job through `BROWSER_AGENT_WORKFLOW`/`BROWSER`, real crawl job, real Creator `standard-1` sandbox job capped at 10 minutes, real Pro `standard-2` sandbox job capped at 30 minutes, R2 artifact download, actor-scoped user-safe usage, crawl-page usage, sandbox-second quota denial, operator-alert dedupe/readback on operator surfaces, COGS dashboard readback, and audit rows against `https://tools.vibecodr.space` |
+| Cloudflare dynamic primitive fit | `docs/CLOUDFLARE-PRIMITIVE-FIT.md`, `docs/API-CONTRACT.md`, `wrangler.jsonc` | docs verify Cloudflare Workflows are the v1 durable `browser.agent_task` lane; Dynamic Workers/Facets/Dynamic Workflows remain future supervised dynamic-code capabilities, not replacements for v1 Browser Run Quick Actions, Sandbox SDK, D1, R2, Queue/DLQ, or platform-owned quota/audit/billing authority |
+| Production-grade packaging | build, typecheck, test, explicit npm exports, CLI-only runtime dependencies, pack verifier, CI | `npm run verify`; pack verifier rejects `docs/`, hosted Worker source, migrations, deployment config, tests, scripts, and Cloudflare primitive runtime dependencies from the public npm artifact |
+| Inspectable goal coverage | `vc-tools inspect`, `src/core/goal-coverage.ts`, `scripts/check-goal-coverage.mjs` | `npm run verify:goal` and `test/cli.behavior.test.ts` verify coverage output |
+
+## Completion Gate
+
+Before shipping:
+
+1. `npm run check`
+2. `npm run check:worker`
+3. `npm test`
+4. `npm run build`
+5. `npm run verify:artifact`
+6. `npm run verify:goal`
+7. Manual CLI smoke against a mock or real API
+8. Hosted service smoke against `https://tools.vibecodr.space`
+
+The CLI-contract release channel may ship with `live-hosted-production` marked
+`hosted-required`. A live release must clear that pending inspection with fresh
+production smoke evidence after any Worker binding, live tool execution,
+retention, quota, audit, queue, D1, R2, Browser Run, or Sandbox behavior change.

package/docs/commands.md

@@ -46,6 +46,17 @@ Syntax:
 
 Without `--probe`, this reads only local state.
 
+### `whoami`
+
+Syntax:
+
+`vibecodr whoami [--no-login]`
+
+Shows the connected Vibecodr account and plan by calling the protected
+`get_account_capabilities` MCP tool. It uses the same refresh and interactive
+login retry path as `call`, but prints only account identity, plan, CLI profile,
+server URL, and session state.
+
 ### `tools`
 
 Syntax:
@@ -54,39 +65,41 @@ Syntax:
 
 This always reads the live tool catalog from the MCP server.
 
-### `call`
-
-Syntax:
+### `call`
 
-`vibecodr call <tool-name> [--input-json <json>] [--input-file <path>] [--stdin] [--interactive] [--timeout-sec <n>] [--no-login] [--confirm]`
+Syntax:
+
+`vibecodr call <tool-name> [--input-json <json>] [--input-file <path>] [--stdin] [--interactive] [--timeout-sec <n>] [--no-login] [--confirm]`
 
 `--interactive` currently supports top-level scalar object fields.
 
 For `quick_publish_creation` with `payload.importMode: "direct_files"`, pass file paths as normal slash-separated project paths such as `src/main.tsx` or `src/server/binding-proof.js`. Do not pre-encode slashes as `%2F`; the hosted MCP gateway encodes each URL segment when it writes files to Vibecodr.
 
-Known mutating tools require explicit confirmation through `--confirm`. The CLI redacts secret, token, source, descriptor, and inline file-content fields from displayed arguments and results; the MCP gateway remains the authority boundary for OAuth, owner checks, confirmation, and output shaping.
-
-Use `--timeout-sec <n>` when a protected tool is expected to run longer than the default client wait, such as a build-backed publish retry. This changes only the local MCP transport timeout and is not forwarded as a server tool argument.
-
-### `upload`
-
-Syntax:
-
-`vibecodr upload --zip <path> [--idempotency-key <key>] [--root-hint <path>] [--entry-hint <path>] [--timeout-sec <n>] [--no-login]`
-
-`vibecodr upload --image <path> [--kind cover_image|avatar_image] [--content-type <mime>] [--timeout-sec <n>] [--no-login]`
-
-Stages a local ZIP or image through Vibecodr's API-owned upload session flow. The CLI asks the MCP gateway for a short-lived direct R2 PUT URL, uploads the bytes directly to R2, completes server-side verification, and prints safe identifiers only.
-
-ZIP uploads print a `quickPublishPayload` snippet using `payload.importMode: "staged_upload"`. The snippet asks Vibecodr to use the async staged-upload import path so larger projects can move to the heavy import lane automatically instead of making the CLI guess. Cover image uploads print a `thumbnailStagedUpload` snippet that can be passed to publish metadata tools. Avatar image uploads print an `avatarStagedUpload` identifier for avatar promotion flows.
-
-Cover images support PNG, JPEG, WebP, and AVIF. Avatar images support PNG, JPEG, WebP, and GIF.
-
-Staged upload MCP setup and completion calls use a longer client-side wait by default so large ZIP verification does not fail only because the local CLI stopped waiting. Use `--timeout-sec <n>` only when a slower network needs a different local wait; this value is transport behavior and is not forwarded as a server tool argument.
-
-The presigned URL is a bearer credential and is never printed in command output. Legacy `zip_import` / `fileBase64` remains a compatibility path for small payloads, not the preferred CLI path for whole repos or launch images.
-
-### `pulse-setup`
+Known mutating tools require explicit confirmation through `--confirm`. The CLI redacts secret, token, source, descriptor, and inline file-content fields from displayed arguments and results while preserving safe operator handles and counters such as `artifactId`, `jobId`, `requestId`, `traceId`, `errorCode`, `credentialType`, `tokenCount`, and `tokenKind`; the MCP gateway remains the authority boundary for OAuth, owner checks, confirmation, and output shaping.
+
+Use `--timeout-sec <n>` when a protected tool is expected to run longer than the default client wait, such as a build-backed publish retry. This changes only the local MCP transport timeout and is not forwarded as a server tool argument.
+
+Use `vibecodr call get_account_capabilities --json` to read the live model-safe plan snapshot before promising hosted tool work. The gateway returns Quick Checks, Agent Browser, Sandbox, Crawl, and Artifact Shelf limits when the platform API exposes them.
+
+### `upload`
+
+Syntax:
+
+`vibecodr upload --zip <path> [--idempotency-key <key>] [--root-hint <path>] [--entry-hint <path>] [--timeout-sec <n>] [--no-login]`
+
+`vibecodr upload --image <path> [--kind cover_image|avatar_image] [--content-type <mime>] [--timeout-sec <n>] [--no-login]`
+
+Stages a local ZIP or image through Vibecodr's API-owned upload session flow. The CLI asks the MCP gateway for a short-lived direct R2 PUT URL, uploads the bytes directly to R2, completes server-side verification, and prints safe identifiers only.
+
+ZIP uploads print a `quickPublishPayload` snippet using `payload.importMode: "staged_upload"`. The snippet asks Vibecodr to use the async staged-upload import path so larger projects can move to the heavy import lane automatically instead of making the CLI guess. Cover image uploads print a `thumbnailStagedUpload` snippet that can be passed to publish metadata tools. Avatar image uploads print an `avatarStagedUpload` identifier for avatar promotion flows.
+
+Cover images support PNG, JPEG, WebP, and AVIF. Avatar images support PNG, JPEG, WebP, and GIF.
+
+Staged upload MCP setup and completion calls use a longer client-side wait by default so large ZIP verification does not fail only because the local CLI stopped waiting. Use `--timeout-sec <n>` only when a slower network needs a different local wait; this value is transport behavior and is not forwarded as a server tool argument.
+
+The presigned URL is a bearer credential and is never printed in command output. Legacy `zip_import` / `fileBase64` remains a compatibility path for small payloads, not the preferred CLI path for whole repos or launch images.
+
+### `pulse-setup`
 
 Syntax:
 
@@ -153,15 +166,22 @@ Syntax:
 
 Syntax:
 
-`vibecodr install <codex|cursor|vscode|windsurf> [--scope user|project] [--path <dir>] [--name <server-name>] [--open-client] [--overwrite] [--dry-run]`
+`vibecodr install <codex|cursor|vscode|windsurf|claude-desktop> [--scope user|project] [--path <dir>] [--name <server-name>] [--open-client] [--overwrite] [--dry-run]`
 
 Install config only. Runtime auth remains CLI-owned or editor-owned depending on where the server is used.
 
+Claude Desktop does not load remote HTTP MCP servers natively, so the installer writes the documented `mcp-remote` stdio proxy entry (`{ command: "npx", args: ["mcp-remote", <url>] }`). Node.js / npx must be on PATH for the proxy to launch. Users can alternatively add the MCP URL via Settings -> Connectors -> Add custom connector in the desktop app.
+
+Platform support matrix:
+- **macOS**: writes to `~/Library/Application Support/Claude/claude_desktop_config.json`.
+- **Windows**: writes to `%APPDATA%\Claude\claude_desktop_config.json`.
+- **Linux**: Anthropic does not ship an official Claude Desktop build for Linux. The installer writes to `${XDG_CONFIG_HOME:-$HOME/.config}/Claude/claude_desktop_config.json`, the path used by community repackages. If you are not running such a build, install Claude Code and use `vibecodr install codex` / equivalent instead.
+
 ### `uninstall`
 
 Syntax:
 
-`vibecodr uninstall <codex|cursor|vscode|windsurf> [--scope user|project] [--path <dir>] [--name <server-name>] [--dry-run]`
+`vibecodr uninstall <codex|cursor|vscode|windsurf|claude-desktop> [--scope user|project] [--path <dir>] [--name <server-name>] [--dry-run]`
 
 ## Exit codes