@vibecodr/cli 1.0.6 → 1.0.8

package/docs/SECURITY.md

@@ -1,21 +1,25 @@
-# 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.
+# Vibecodr CLI Security Notes
+
+The Vibecodr CLI is a trust-boundary tool. It validates local input before
+submitting requests to the hosted Vibecodr API, but the hosted API remains the
+source of truth for auth, grants, quota, audit logging, retention, and
+Cloudflare credential custody.
+
+## Local Rules
+
+- Plain `vibecodr login` is the default MCP Gateway OAuth path. It stores only
+  the CLI profile's MCP OAuth session under the historical `@vibecodr/mcp`
+  service; it does not log editor clients into MCP and does not create an Agent
+  Computer credential.
+- `vibecodr login agent` and `vibecodr start` are the hosted Agent Computer
+  human paths. They start a browser/device approval session, print a
+  user-checkable code, optionally open the Vibecodr approval page, and store 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
+  local credentials. The input may be an existing Vibecodr 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
@@ -27,66 +31,66 @@ credential custody.
   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
+  cached short-lived grant. Direct Vibecodr 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
+- 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.
+- 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
+- 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 Vibecodr 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
+- 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
+- Grant audience validation. The hosted Vibecodr API 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
@@ -94,19 +98,19 @@ The API must enforce these before any cost-bearing Cloudflare work:
   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
+- 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
@@ -115,9 +119,9 @@ The API must enforce these before any cost-bearing Cloudflare work:
   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 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,
@@ -133,95 +137,95 @@ The API must enforce these before any cost-bearing Cloudflare work:
   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:
-
+- 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/cli` 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.
+- The hosted Vibecodr 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
+- `/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 the hosted Vibecodr
+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
+- 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.
+
+## 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 Vibecodr 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

@@ -1,28 +1,28 @@
-# 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 |
+# Vibecodr CLI 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 |
+| --- | --- | --- |
+| Unified Vibecodr CLI surface | package `@vibecodr/cli`, canonical bin `vibecodr` with back-compat `vibecodr-mcp` and `vc-tools` bins, `VC_TOOLS_*` env namespace preserved for back-compat | `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 |
+| Agent Computer first-use path | `vibecodr start`, `vibecodr setup`, `vibecodr try`, `vibecodr agent connect/status`, `vibecodr 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 | `vibecodr login`, `vibecodr auth status`, `vibecodr auth diagnose`, `vibecodr 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 | `vibecodr agent connect`, advanced `vibecodr 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 |
+| Browser render/screenshot/markdown/PDF tests, crawl, snapshot, and paid agent tasks | `vibecodr browser *`, advanced `vibecodr 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 | `vibecodr computer run/test`, advanced `vibecodr 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 | `vibecodr proof list/show/save/delete`, advanced `vibecodr 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 | `vibecodr work list/show/follow/cancel`, advanced `vibecodr 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 | `vibecodr usage`, `vibecodr 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 | `vibecodr 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 | `vibecodr 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 | `vibecodr grants`, `vibecodr grants list` | tests verify default list routing and scoped grant rendering |
+| Retention settings | `vibecodr retention show/set` | tests verify day bounds, plan-capped artifact retention, recordings policy, `--yes` on mutation |
+| Usage dashboard | `vibecodr dashboard [section]` | tests verify safe dashboard section URL generation without auth leakage and shared API URL validation |
+| Plan packaging | `vibecodr 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 |
@@ -30,29 +30,29 @@ artifacts and tests.
 | 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 |
+| 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.
+| 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 | `vibecodr inspect`, `src/legacy/core/goal-coverage.ts` | `npm run verify:release` and `test/legacy/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:release`
+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/architecture.md

@@ -1,22 +1,25 @@
 # Architecture
 
-The Vibecodr CLI is a client of the hosted Vibecodr MCP gateway.
+The Vibecodr CLI is the unified user-facing command surface for the hosted MCP Gateway and the hosted Agent Computer.
 
 ## Boundary
 
 - hosted MCP gateway/server repo: `Vibecodr-MCP`
-- CLI client repo: `Vibecodr-MCP-CLI`
+- CLI and hosted Agent Computer worker repo: `Vibecodr-CLI`
 - CLI package: `@vibecodr/cli`
 - primary executable: `vibecodr`
-- compatibility executable: `vibecodr-mcp`
+- compatibility executables: `vibecodr-mcp`, `vc-tools`
 - legacy package compatibility: `@vibecodr/mcp`
 - default MCP URL: `https://openai.vibecodr.space/mcp`
+- Agent Computer API URL: `https://tools.vibecodr.space`
 
-This repo does not run the hosted server. It installs client config, performs CLI-owned OAuth, discovers the live tool catalog, and calls tools over Streamable HTTP MCP.
+This repo does not run the hosted MCP gateway. It does own the distributable CLI and the hosted Agent Computer worker source. The CLI installs client config, performs CLI-owned OAuth for the MCP Gateway, discovers the live gateway tool catalog, calls tools over Streamable HTTP MCP, and routes Agent Computer commands to `tools.vibecodr.space`.
 
 ## Auth Ownership
 
-`vibecodr login` stores OAuth tokens for the CLI profile only.
+`vibecodr login` and `vibecodr login mcp` store OAuth tokens for the CLI profile only.
+
+`vibecodr login agent` and `vibecodr start` store the hosted Agent Computer credential only.
 
 Codex, Cursor, VS Code, Windsurf, ChatGPT, and other MCP clients own separate OAuth sessions. Installing MCP config into those clients points them at the same server, but it does not copy CLI tokens into them.
 
@@ -26,7 +29,7 @@ The CLI is permissively licensed and safe to distribute as a public client packa
 
 The package name is `@vibecodr/cli` because this repo distributes the user-facing command-line client. The older `@vibecodr/mcp` package name is kept only as a compatibility/deprecation surface; the bare `vibecodr` executable remains the canonical user command.
 
-Local config directories and secure-token service names intentionally keep their historical `vibecodr-mcp` / `@vibecodr/mcp` identifiers during this migration. Those names are storage compatibility keys, not the public npm package identity.
+Local config directories and secure-token service names intentionally keep their historical `vibecodr-mcp`, `vc-tools`, `@vibecodr/mcp`, and `@vibecodr/vc-tools` identifiers during this migration. Those names are storage compatibility keys, not the public npm package identity.
 
 Keeping the repos separate makes the contract clear:
 

package/docs/auth.md

@@ -1,12 +1,18 @@
 # Auth
 
-`vibecodr login` authenticates the CLI itself to the hosted Vibecodr MCP server. It does not log Codex, Cursor, VS Code, Windsurf, ChatGPT, or any other MCP client into MCP.
+`vibecodr login` defaults to authenticating the CLI itself to the hosted Vibecodr MCP server. It does not log Codex, Cursor, VS Code, Windsurf, ChatGPT, or any other MCP client into MCP.
 
-Vibecodr has one hosted MCP gateway. The CLI is one client of that gateway, with its own local OAuth token store.
+Vibecodr now has two CLI credential lanes:
+
+- MCP Gateway: `vibecodr login` or `vibecodr login mcp`, stored under the historical `@vibecodr/mcp` service.
+- Hosted Agent Computer: `vibecodr login agent` or the automatic `vibecodr start` approval flow, stored under the historical `@vibecodr/vc-tools` service.
+
+The token types are intentionally separate. Status and doctor can read both lanes, but the CLI does not merge or copy credentials between them.
 
 Compatibility alias:
 
 - `vibecodr-mcp login`
+- `vc-tools login` for the Agent Computer compatibility path
 
 ## Implemented now
 
@@ -15,7 +21,8 @@ Compatibility alias:
 - loopback callback on `127.0.0.1`
 - secure token storage in the OS credential store via `@napi-rs/keyring`
 - proactive refresh before protected runtime commands when a refresh token is available
-- `logout` local token deletion plus best-effort revocation
+- `logout` local token deletion plus best-effort revocation for MCP Gateway sessions
+- `logout agent --yes` local Agent Computer credential deletion through the compatibility lane
 
 The plaintext file secret store is for local automated tests only. It is ignored unless both `VIBECDR_MCP_INSECURE_SECRET_STORE_PATH` and `VIBECDR_MCP_ENABLE_INSECURE_SECRET_STORE=true` are set.
 
@@ -48,10 +55,11 @@ Current repo reality:
 
 ## Runtime behavior
 
-- `login` prints the authorization URL by default so the browser step is explicit and reliable across shells
-- `login --browser open` opts into automatic browser launch
-- `status` reads local session state without requiring the network unless `--probe` is used
-- `tools` and `call` will attempt to reuse the stored session
+- `login` and `login mcp` print the authorization URL by default so the browser step is explicit and reliable across shells
+- `login mcp --browser open` opts into automatic browser launch
+- `login agent` starts the hosted Agent Computer approval flow; `start` also opens this flow when no Agent Computer credential is stored
+- `status` reads local MCP Gateway and Agent Computer credential state without requiring the network unless `--probe` is used
+- `mcp tools`, `tools`, `mcp call`, and `call` will attempt to reuse the stored MCP Gateway session
 - if the access token is close to expiry and a refresh token is present, the CLI refreshes before making the MCP request
 
 ## Verified now