@viberaven/cli 1.3.1 → 1.4.0

package/README.md

@@ -1,128 +1,115 @@
-# @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)
-
-VibeRaven is the Agent Context + Production Gate for AI-built apps. It gives Claude Code, Codex, Cursor, and other coding agents a production-readiness loop before Vercel/Supabase deployment.
-
-## Humans
-
-```bash
-npx -y viberaven
-```
-
-No subcommand is needed in a real terminal. It opens the interactive menu for sign-in, scan, report, provider guides, dashboards, prompts, and sign-out.
-
-## Coding Agents
-
-Agents should run:
-
-```bash
-npx -y viberaven --agent-mode
-```
-
-If running from the `viberaven` monorepo root, run:
-
-```bash
-node packages/cli/dist/cli.js --agent-mode
-```
-
-Then read artifacts in this order:
-
-1. `.viberaven/agent-tasklist.md`
-2. `.viberaven/gate-result.json`
-3. `.viberaven/context-map.json`
-4. `.viberaven/agent-summary.md`
-5. `.viberaven/launch-playbook.md`
-
-Fix one repo-code gap, then run:
-
-```bash
-npx -y viberaven --verify
-npx -y viberaven --strict
-```
-
-For focused work:
-
-```bash
-npx -y viberaven next --json
-npx -y viberaven prompt --gap <id>
-npx -y viberaven audit --vercel-supabase
-```
-
-## Chat-native production actions
-
-Agent mode writes a compact action surface for Codex, Claude Code, Cursor, and other agents:
-
-```bash
-npx -y viberaven --agent-mode
-npx -y viberaven actions
-npx -y viberaven verify --action VR-A1
-```
-
-VibeRaven writes `.viberaven/actions.json` as the V1 source of truth and renderer contract for the current action surface. The manifest is generated by `--agent-mode`; `.viberaven/action-registry.json` preserves stable action handles across runs.
-
-Chat output is intentionally limited to focused actions, provider targets, copy payloads, verification commands, repo-relative file targets, and resume prompts. It does not print secrets, raw env values, or generic dashboard link dumps.
-
-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 evidence.
-
-Preview the action surface without login, scan, or API spend:
-
-```bash
-npx -y viberaven preview --agent-mode
-```
-
-The preview uses sample renderer data to show the intended chat-native shape. It is not a production verdict for the current repository.
-
-## Agent infrastructure direction
-
-VibeRaven's action model is designed for normal Codex, Claude Code, Cursor, and MCP workflows today, and for richer agent hosts later.
-
-Managed-agent systems need durable sessions, observable event history, credential boundaries, bounded execution, and resumable action state. VibeRaven keeps those concerns in the manifest contract:
-
-- `.viberaven/actions.json` is the current action surface.
-- `.viberaven/action-registry.json` preserves stable IDs and lifecycle history.
-- Future session events can add an append-only timeline without changing the current action model.
-- Provider credentials and raw env values must stay out of chat output, manifests, MCP resources, and UI renderers.
-- Future local/hosted consoles should execute only narrow VibeRaven commands, not arbitrary shell text.
-
-## Production Copilot Loop
-
-VibeRaven runs a batch-disciplined loop until the production gate clears. Do not stop at "scan complete."
-
-1. **Scan** — Run `--agent-mode`. Read `.viberaven/agent-tasklist.md` and parse `VIBERAVEN_NEXT_ACTION` from stdout for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
-2. **Batch heals** — For each repo-code task where `requiresUserAction: false`, apply up to `batchSize` heals per batch (free=3, pro=10) via `viberaven_heal_apply { gap: "<gapId>", yes: true }` or `--heal --apply --gap <id> --yes`. When `scanNow: true`, verify before applying more heals.
-3. **Verify and clear** — Run `--verify` once per batch (not after every heal). Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`. For provider gaps, read `VIBERAVEN_PROVIDER_ACTION`, complete the dashboard step, then verify.
-
-If `stalled: true`, stop calling verify and address provider-action gaps or report to the user. Run `--strict` before deploy or CI pass.
-
-## Machine Output
-
-```bash
-npx -y viberaven --agent-mode --json
-npx -y viberaven --agent-mode --jsonl
-npx -y viberaven --strict --json
-```
-
-Machine artifact contract:
-
-```text
-docs/contracts/artifacts.md
-https://viberaven.dev/schemas/gate-result.schema.json
-https://viberaven.dev/schemas/context-map.schema.json
-https://viberaven.dev/schemas/gap.schema.json
-https://viberaven.dev/schemas/heal-result.schema.json
-```
-
-## Development
-
-```bash
-npm run cli:build
-npm run cli:test
-node packages/cli/dist/cli.js scan
-```
-
-## License
-
-The public npm CLI package is MIT licensed. Private monorepo code and extension packaging may have separate product terms.
+# @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="assets/report/assets/viberaven-hero.png" alt="VibeRaven — the raven fanning its hand of provider cards" width="460" />
+</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.
+
+![The VibeRaven Card Table](assets/report/assets/viberaven-table.png)
+
+## 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