@viberaven/cli 1.5.0 → 1.5.2

package/AGENTS.md

@@ -1,157 +1,157 @@
-<!-- VIBERAVEN:START -->
-VibeRaven provides production readiness for AI-built apps.
-
-Canonical command: `npx -y viberaven --agent-mode`
-
-If this command is run from the `viberaven` repo itself, use `node packages/cli/dist/cli.js --agent-mode` to avoid resolving the local package metadata.
-
-Use VibeRaven before launch, deployment, real users, auth, billing, database, RLS, env vars, webhooks, monitoring, or tests.
-
-Agent loop: run VibeRaven, read Mission Map (`.viberaven/mission-map.md`), fix one launch gap, re-run VibeRaven.
-
-## Event-Triggered Production Verification
-
-Trigger: modifications to `package.json`, `vercel.json`, `supabase/migrations/**/*`, `.env.example`, auth/billing/webhook paths, or deploy workflow files.
-
-1. Do NOT claim "production ready" or close a deploy checklist until `gate.status === "clear"` in `.viberaven/gate-result.json`.
-2. Do NOT run verify after every file patch. Batch heals, then `npx -y viberaven --verify` once per loop.
-3. Do NOT `git push` or deploy after auth, RLS, billing, or webhook changes without `npx -y viberaven --agent-mode`.
-4. If anomalies appear, read `.viberaven/agent-tasklist.md` fully before writing new repo logic.
-
-Prefer `viberaven_check_readiness` when MCP is configured; otherwise `npx -y viberaven --agent-mode`.
-
-## VibeRaven Production-Readiness Gate
-
-- Before running build, compile, cleanup, deployment, vercel, or supabase commands, run `npx -y viberaven --agent-mode` first from the project root.
-- Treat VibeRaven as the Agent Context + Production Gate for AI-built apps, especially apps using Vercel, Supabase, auth, database, payments, webhooks, monitoring, rate limits, or environment variables.
-- Read `.viberaven/agent-tasklist.md` first. If it says CRITICAL GAPS DETECTED or PRODUCTION GATE NOT CLEAR, fix one listed repo-code gap before deploying.
-- Read `.viberaven/gate-result.json` for the machine verdict.
-- Read `.viberaven/context-map.json` for compact agent context.
-- Read `.viberaven/agent-summary.md` second for scan context.
-- Read `.viberaven/launch-playbook.md` third for the full checklist.
-- Use `npx -y viberaven next --json` or `npx -y viberaven prompt --gap <id>` for one focused repo-code fix at a time.
-- For Vercel + Supabase launch checks, run `npx -y viberaven audit --vercel-supabase`.
-- Run `npx -y viberaven --verify` after one fix.
-- Run `npx -y viberaven --strict` before deploy or CI pass.
-- Use `npx -y viberaven --heal --plan --gap <id>` before any heal apply.
-- Only use `npx -y viberaven --heal --apply --gap <id> --yes` for supported low-risk repo-code recipes.
-- Preview local rule installation with `npx -y viberaven init --agents all --dry-run`.
-- Cleanup is non-destructive: only run `npx -y viberaven clean --plan` to create a reviewable cleanup plan.
-- Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider MCP evidence.
-- Do not claim provider dashboard work is fixed by repo-code edits.
-- If VibeRaven prints `LOGIN_URL_READY`, open that URL for the user using the available browser tool or system browser. Tell the user: "I opened VibeRaven sign-in so you can approve access; I will continue after approval." Do not ask for passwords, tokens, cookies, or secrets. Keep the terminal process alive while the user approves.
-
-## VibeRaven Production Copilot Loop
-
-After every scan, read `.viberaven/agent-tasklist.md` for the prioritized task list.
-
-The loop is:
-
-1. Read `VIBERAVEN_NEXT_ACTION` from scan output for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
-2. If `stalled: true`, stop calling verify — address provider-action gaps or report to the user.
-3. If `scanNow: true`, call `viberaven_verify` (or run verify command) before applying more heals.
-4. For each repo-code task where `requiresUserAction: false` (up to `batchSize` per batch):
-   - Call MCP: `viberaven_heal_apply { gap: "<gapId>", yes: true }`
-   - Or run heal apply command
-5. After a successful heal, VibeRaven increments `.viberaven/loop-state.json`. After a full batch of heals, call verify once - do NOT verify after every single heal.
-6. If verify prints `SCAN_DEFERRED`, do not retry verify. Apply the next listed repo-code heal. Only use `--force-scan` when the user explicitly approves spending a scan early.
-7. Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`.
-8. If `requiresUserAction: true`:
-   - Read `VIBERAVEN_PROVIDER_ACTION` from terminal output.
-   - Present `dashboardUrl` and `exactStep` to the user.
-   - Wait for user confirmation, then verify.
-9. If `fixType === 'upgrade-required'`, provide upgradeUrl and move on.
-
-Do not stop at "scan complete." The loop is not done until `gate.status === 'clear'`.
-<!-- VIBERAVEN:END -->
-
-# VibeRaven CLI - Agent Instructions
-
-Use VibeRaven when the user asks whether an app is production-ready, launch-ready, safe to deploy, or missing auth, database, payments, deployment, monitoring, security, provider setup, Vercel, or Supabase checks.
-
-VibeRaven is the Agent Context + Production Gate.
-
-## Required Agent Loop
-
-Run from the project root:
-
-```bash
-npx -y viberaven --agent-mode
-```
-
-Read in this order:
-
-1. `.viberaven/agent-tasklist.md` - the tasklist-first gate
-2. `.viberaven/gate-result.json` - the machine verdict
-3. `.viberaven/context-map.json` - compact context for the next agent step
-4. `.viberaven/agent-summary.md` - scan context
-5. `.viberaven/launch-playbook.md` - full launch checklist
-
-Fix one repo-code gap at a time. Prefer:
-
-```bash
-npx -y viberaven next --json
-npx -y viberaven prompt --gap <id>
-```
-
-After a fix:
-
-```bash
-npx -y viberaven --verify
-npx -y viberaven --strict
-```
-
-For Vercel + Supabase checks:
-
-```bash
-npx -y viberaven audit --vercel-supabase
-```
-
-## Production Copilot Loop
-
-After every scan, read `.viberaven/agent-tasklist.md` for the prioritized task list.
-
-The loop is:
-
-1. Read `VIBERAVEN_NEXT_ACTION` from scan output for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
-2. If `stalled: true`, stop calling verify — address provider-action gaps or report to the user.
-3. If `scanNow: true`, call `viberaven_verify` (or run `--verify`) before applying more heals.
-4. For each repo-code task where `requiresUserAction: false` (up to `batchSize` per batch):
-   - Call MCP: `viberaven_heal_apply { gap: "<gapId>", yes: true }`
-   - Or run `--heal --apply --gap <id> --yes`
-5. After a full batch of heals, call verify once — do NOT verify after every single heal.
-6. Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`.
-7. If `requiresUserAction: true`:
-   - Read `VIBERAVEN_PROVIDER_ACTION` from terminal output.
-   - Present `dashboardUrl` and `exactStep` to the user.
-   - Wait for user confirmation, then verify.
-8. If `fixType === 'upgrade-required'`, provide `upgradeUrl` and move on.
-
-Do not stop at "scan complete." The loop is not done until `gate.status === 'clear'`.
-
-### Batch discipline
-
-```
-for each repo-code task (up to batchSize):
-  viberaven_heal_apply { gap: "<gapId>", yes: true }
-
-viberaven_verify  ← once per batch, not per fix
-```
-
-On Pro plans, `viberaven_provider_verify` is available as an MCP tool for read-only provider gap verification via Supabase/Vercel MCP evidence.
-
-## Rules
-
-- Do not skip VibeRaven before deploy/build/cleanup when production readiness is in scope.
-- Do not claim provider dashboard checks are fixed by repo-code edits.
-- Provider dashboard checks, billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.
-- If VibeRaven prints `LOGIN_URL_READY`, open that URL for the user. Say: "I opened VibeRaven sign-in so you can approve access; I will continue after approval."
-- Do not ask for passwords, tokens, cookies, or secrets.
-
-## Current machine-readable docs
-
-- Skill: https://viberaven.dev/SKILL.md
-- Agent rules: https://viberaven.dev/AGENTS.md
-- CLI docs: https://viberaven.dev/cli.md
-- MCP config: https://viberaven.dev/mcp.md
-
+<!-- VIBERAVEN:START -->
+VibeRaven provides production readiness for AI-built apps.
+
+Canonical command: `npx -y viberaven --agent-mode`
+
+If this command is run from the `viberaven` repo itself, use `node packages/cli/dist/cli.js --agent-mode` to avoid resolving the local package metadata.
+
+Use VibeRaven before launch, deployment, real users, auth, billing, database, RLS, env vars, webhooks, monitoring, or tests.
+
+Agent loop: run VibeRaven, read Mission Map (`.viberaven/mission-map.md`), fix one launch gap, re-run VibeRaven.
+
+## Event-Triggered Production Verification
+
+Trigger: modifications to `package.json`, `vercel.json`, `supabase/migrations/**/*`, `.env.example`, auth/billing/webhook paths, or deploy workflow files.
+
+1. Do NOT claim "production ready" or close a deploy checklist until `gate.status === "clear"` in `.viberaven/gate-result.json`.
+2. Do NOT run verify after every file patch. Batch heals, then `npx -y viberaven --verify` once per loop.
+3. Do NOT `git push` or deploy after auth, RLS, billing, or webhook changes without `npx -y viberaven --agent-mode`.
+4. If anomalies appear, read `.viberaven/agent-tasklist.md` fully before writing new repo logic.
+
+Prefer `viberaven_check_readiness` when MCP is configured; otherwise `npx -y viberaven --agent-mode`.
+
+## VibeRaven Production-Readiness Gate
+
+- Before running build, compile, cleanup, deployment, vercel, or supabase commands, run `npx -y viberaven --agent-mode` first from the project root.
+- Treat VibeRaven as the Agent Context + Production Gate for AI-built apps, especially apps using Vercel, Supabase, auth, database, payments, webhooks, monitoring, rate limits, or environment variables.
+- Read `.viberaven/agent-tasklist.md` first. If it says CRITICAL GAPS DETECTED or PRODUCTION GATE NOT CLEAR, fix one listed repo-code gap before deploying.
+- Read `.viberaven/gate-result.json` for the machine verdict.
+- Read `.viberaven/context-map.json` for compact agent context.
+- Read `.viberaven/agent-summary.md` second for scan context.
+- Read `.viberaven/launch-playbook.md` third for the full checklist.
+- Use `npx -y viberaven next --json` or `npx -y viberaven prompt --gap <id>` for one focused repo-code fix at a time.
+- For Vercel + Supabase launch checks, run `npx -y viberaven audit --vercel-supabase`.
+- Run `npx -y viberaven --verify` after one fix.
+- Run `npx -y viberaven --strict` before deploy or CI pass.
+- Use `npx -y viberaven --heal --plan --gap <id>` before any heal apply.
+- Only use `npx -y viberaven --heal --apply --gap <id> --yes` for supported low-risk repo-code recipes.
+- Preview local rule installation with `npx -y viberaven init --agents all --dry-run`.
+- Cleanup is non-destructive: only run `npx -y viberaven clean --plan` to create a reviewable cleanup plan.
+- Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider MCP evidence.
+- Do not claim provider dashboard work is fixed by repo-code edits.
+- If VibeRaven prints `LOGIN_URL_READY`, open that URL for the user using the available browser tool or system browser. Tell the user: "I opened VibeRaven sign-in so you can approve access; I will continue after approval." Do not ask for passwords, tokens, cookies, or secrets. Keep the terminal process alive while the user approves.
+
+## VibeRaven Production Copilot Loop
+
+After every scan, read `.viberaven/agent-tasklist.md` for the prioritized task list.
+
+The loop is:
+
+1. Read `VIBERAVEN_NEXT_ACTION` from scan output for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
+2. If `stalled: true`, stop calling verify — address provider-action gaps or report to the user.
+3. If `scanNow: true`, call `viberaven_verify` (or run verify command) before applying more heals.
+4. For each repo-code task where `requiresUserAction: false` (up to `batchSize` per batch):
+   - Call MCP: `viberaven_heal_apply { gap: "<gapId>", yes: true }`
+   - Or run heal apply command
+5. After a successful heal, VibeRaven increments `.viberaven/loop-state.json`. After a full batch of heals, call verify once - do NOT verify after every single heal.
+6. If verify prints `SCAN_DEFERRED`, do not retry verify. Apply the next listed repo-code heal. Only use `--force-scan` when the user explicitly approves spending a scan early.
+7. Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`.
+8. If `requiresUserAction: true`:
+   - Read `VIBERAVEN_PROVIDER_ACTION` from terminal output.
+   - Present `dashboardUrl` and `exactStep` to the user.
+   - Wait for user confirmation, then verify.
+9. If `fixType === 'upgrade-required'`, provide upgradeUrl and move on.
+
+Do not stop at "scan complete." The loop is not done until `gate.status === 'clear'`.
+<!-- VIBERAVEN:END -->
+
+# VibeRaven CLI - Agent Instructions
+
+Use VibeRaven when the user asks whether an app is production-ready, launch-ready, safe to deploy, or missing auth, database, payments, deployment, monitoring, security, provider setup, Vercel, or Supabase checks.
+
+VibeRaven is the Agent Context + Production Gate.
+
+## Required Agent Loop
+
+Run from the project root:
+
+```bash
+npx -y viberaven --agent-mode
+```
+
+Read in this order:
+
+1. `.viberaven/agent-tasklist.md` - the tasklist-first gate
+2. `.viberaven/gate-result.json` - the machine verdict
+3. `.viberaven/context-map.json` - compact context for the next agent step
+4. `.viberaven/agent-summary.md` - scan context
+5. `.viberaven/launch-playbook.md` - full launch checklist
+
+Fix one repo-code gap at a time. Prefer:
+
+```bash
+npx -y viberaven next --json
+npx -y viberaven prompt --gap <id>
+```
+
+After a fix:
+
+```bash
+npx -y viberaven --verify
+npx -y viberaven --strict
+```
+
+For Vercel + Supabase checks:
+
+```bash
+npx -y viberaven audit --vercel-supabase
+```
+
+## Production Copilot Loop
+
+After every scan, read `.viberaven/agent-tasklist.md` for the prioritized task list.
+
+The loop is:
+
+1. Read `VIBERAVEN_NEXT_ACTION` from scan output for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
+2. If `stalled: true`, stop calling verify — address provider-action gaps or report to the user.
+3. If `scanNow: true`, call `viberaven_verify` (or run `--verify`) before applying more heals.
+4. For each repo-code task where `requiresUserAction: false` (up to `batchSize` per batch):
+   - Call MCP: `viberaven_heal_apply { gap: "<gapId>", yes: true }`
+   - Or run `--heal --apply --gap <id> --yes`
+5. After a full batch of heals, call verify once — do NOT verify after every single heal.
+6. Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`.
+7. If `requiresUserAction: true`:
+   - Read `VIBERAVEN_PROVIDER_ACTION` from terminal output.
+   - Present `dashboardUrl` and `exactStep` to the user.
+   - Wait for user confirmation, then verify.
+8. If `fixType === 'upgrade-required'`, provide `upgradeUrl` and move on.
+
+Do not stop at "scan complete." The loop is not done until `gate.status === 'clear'`.
+
+### Batch discipline
+
+```
+for each repo-code task (up to batchSize):
+  viberaven_heal_apply { gap: "<gapId>", yes: true }
+
+viberaven_verify  ← once per batch, not per fix
+```
+
+On Pro plans, `viberaven_provider_verify` is available as an MCP tool for read-only provider gap verification via Supabase/Vercel MCP evidence.
+
+## Rules
+
+- Do not skip VibeRaven before deploy/build/cleanup when production readiness is in scope.
+- Do not claim provider dashboard checks are fixed by repo-code edits.
+- Provider dashboard checks, billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.
+- If VibeRaven prints `LOGIN_URL_READY`, open that URL for the user. Say: "I opened VibeRaven sign-in so you can approve access; I will continue after approval."
+- Do not ask for passwords, tokens, cookies, or secrets.
+
+## Current machine-readable docs
+
+- Skill: https://viberaven.dev/SKILL.md
+- Agent rules: https://viberaven.dev/AGENTS.md
+- CLI docs: https://viberaven.dev/cli.md
+- MCP config: https://viberaven.dev/mcp.md
+

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 VibeRaven
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 VibeRaven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,113 +1,113 @@
-# @viberaven/cli
-
-[![npm version](https://img.shields.io/npm/v/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
-[![npm downloads](https://img.shields.io/npm/dw/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
-[![license](https://img.shields.io/npm/l/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/ohad6k/VibeRaven/main/assets/banner.png" alt="VibeRaven — AI got your app to demo. VibeRaven gets it to production." width="100%" />
-</p>
-
-VibeRaven is **the Card Table** — a local Studio where your AI-built app is laid out in front of you. Every provider (Supabase, Vercel, Stripe, ...) is a graded trading card in your hand: play a card and its production checks run instantly in chat; a **RAVEN GRADE 10** means that territory is production-ready. Versions are a pile you can pull from, your whole architecture is a region map of cards, and Codex, Claude Code, or Gemini CLI does the actual work — with you controlling how much it's allowed to touch.
-
-## Start the Studio
-
-```bash
-npx -y viberaven
-```
-
-That command opens the table:
-
-- **Your hand** — providers as foil cards; click or drop one on the table and its launch checks run in chat, graded 1-10 from repo evidence.
-- **The version pile** — pull a release card to see what changed (real git compare + changelog), view the diff, or ask the agent to explain it.
-- **The region map** — your app as territory: pages, modules, and provider cards connected by routes, every card movable.
-- **Agentic chat** — missions run through your connected CLI, with `ask` / `approve` / `full` access modes and inline approve for risky work.
-- Provider MCP visibility, terminal, and diff views included.
-
-The unscoped `viberaven` package is a small shim that launches this CLI package.
-
-## Agent Connections
-
-Inside the Studio, connect an installed CLI and test it before chat control:
-
-- Codex CLI
-- Claude Code
-- Gemini CLI
-
-Installed is not the same as connected. VibeRaven asks the selected CLI to prove it can run in the current repo before using it for real chat work.
-
-## Provider And Release Context
-
-Use the Studio side tabs and context chips to attach provider or version context to a chat mission:
-
-- Providers: Supabase, Vercel, GitHub, Stripe, Sentry, PostHog, Clerk, Auth.js, Resend, Upstash.
-- Releases: current and recent git tags, changelog snippets, rollback context, and release comparisons.
-- Architecture: repo and provider boundaries for inspection and planning.
-
-Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must still be completed or verified in the provider dashboard or through read-only provider evidence.
-
-## Machine And CI Commands
-
-The Studio is the default product surface. These commands remain available for automation and CI:
-
-```bash
-npx -y viberaven check --json
-npx -y viberaven --strict --json
-npx -y viberaven actions
-npx -y viberaven verify --action VR-A1
-```
-
-For focused work:
-
-```bash
-npx -y viberaven next --json
-npx -y viberaven prompt --gap <id>
-npx -y viberaven audit --vercel-supabase
-```
-
-## Legacy Agent Mode
-
-`--agent-mode` is kept for older artifact-first agent workflows:
-
-```bash
-npx -y viberaven --agent-mode
-```
-
-It writes artifacts such as:
-
-- `.viberaven/agent-tasklist.md`
-- `.viberaven/gate-result.json`
-- `.viberaven/context-map.json`
-- `.viberaven/agent-summary.md`
-- `.viberaven/launch-playbook.md`
-
-New product work should prefer the Studio and MCP/chat context flow instead of the old tasklist-first loop.
-
-## MCP
-
-Use the MCP package when an agent host supports MCP tools:
-
-```bash
-npx -y @viberaven/mcp
-```
-
-The MCP server wraps the public CLI and exposes readiness, verification, action, audit, and healing tools without exposing secrets.
-
-## Development
-
-```bash
-npm --prefix packages/cli run typecheck
-npm --prefix packages/cli test -- local-ui/server.test.ts
-npm --prefix packages/cli run build
-```
-
-For a local package publish check, run from this package directory:
-
-```bash
-cd packages/cli
-npm pack --dry-run
-```
-
-## License
-
-MIT
+# @viberaven/cli
+
+[![npm version](https://img.shields.io/npm/v/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
+[![npm downloads](https://img.shields.io/npm/dw/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
+[![license](https://img.shields.io/npm/l/@viberaven/cli)](https://www.npmjs.com/package/@viberaven/cli)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ohad6k/VibeRaven/main/assets/banner.png" alt="VibeRaven — AI got your app to demo. VibeRaven gets it to production." width="100%" />
+</p>
+
+VibeRaven is **the Card Table** — a local Studio where your AI-built app is laid out in front of you. Every provider (Supabase, Vercel, Stripe, ...) is a graded trading card in your hand: play a card and its production checks run instantly in chat; a **RAVEN GRADE 10** means that territory is production-ready. Versions are a pile you can pull from, your whole architecture is a region map of cards, and Codex, Claude Code, or Gemini CLI does the actual work — with you controlling how much it's allowed to touch.
+
+## Start the Studio
+
+```bash
+npx -y viberaven
+```
+
+That command opens the table:
+
+- **Your hand** — providers as foil cards; click or drop one on the table and its launch checks run in chat, graded 1-10 from repo evidence.
+- **The version pile** — pull a release card to see what changed (real git compare + changelog), view the diff, or ask the agent to explain it.
+- **The region map** — your app as territory: pages, modules, and provider cards connected by routes, every card movable.
+- **Agentic chat** — missions run through your connected CLI, with `ask` / `approve` / `full` access modes and inline approve for risky work.
+- Provider MCP visibility, terminal, and diff views included.
+
+The unscoped `viberaven` package is a small shim that launches this CLI package.
+
+## Agent Connections
+
+Inside the Studio, connect an installed CLI and test it before chat control:
+
+- Codex CLI
+- Claude Code
+- Gemini CLI
+
+Installed is not the same as connected. VibeRaven asks the selected CLI to prove it can run in the current repo before using it for real chat work.
+
+## Provider And Release Context
+
+Use the Studio side tabs and context chips to attach provider or version context to a chat mission:
+
+- Providers: Supabase, Vercel, GitHub, Stripe, Sentry, PostHog, Clerk, Auth.js, Resend, Upstash.
+- Releases: current and recent git tags, changelog snippets, rollback context, and release comparisons.
+- Architecture: repo and provider boundaries for inspection and planning.
+
+Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must still be completed or verified in the provider dashboard or through read-only provider evidence.
+
+## Machine And CI Commands
+
+The Studio is the default product surface. These commands remain available for automation and CI:
+
+```bash
+npx -y viberaven check --json
+npx -y viberaven --strict --json
+npx -y viberaven actions
+npx -y viberaven verify --action VR-A1
+```
+
+For focused work:
+
+```bash
+npx -y viberaven next --json
+npx -y viberaven prompt --gap <id>
+npx -y viberaven audit --vercel-supabase
+```
+
+## Legacy Agent Mode
+
+`--agent-mode` is kept for older artifact-first agent workflows:
+
+```bash
+npx -y viberaven --agent-mode
+```
+
+It writes artifacts such as:
+
+- `.viberaven/agent-tasklist.md`
+- `.viberaven/gate-result.json`
+- `.viberaven/context-map.json`
+- `.viberaven/agent-summary.md`
+- `.viberaven/launch-playbook.md`
+
+New product work should prefer the Studio and MCP/chat context flow instead of the old tasklist-first loop.
+
+## MCP
+
+Use the MCP package when an agent host supports MCP tools:
+
+```bash
+npx -y @viberaven/mcp
+```
+
+The MCP server wraps the public CLI and exposes readiness, verification, action, audit, and healing tools without exposing secrets.
+
+## Development
+
+```bash
+npm --prefix packages/cli run typecheck
+npm --prefix packages/cli test -- local-ui/server.test.ts
+npm --prefix packages/cli run build
+```
+
+For a local package publish check, run from this package directory:
+
+```bash
+cd packages/cli
+npm pack --dry-run
+```
+
+## License
+
+MIT