# VibeRaven Agent Instructions

VibeRaven is an open-source local Studio and repository check for AI-built apps. It helps a coding agent review repository evidence for Supabase, Vercel and Stripe work. Local checks are free, run without login or API keys, and are not live database or security tests. A repository check is not a live database or security test. It is advice, not a gate: the user decides when to ship. Supported stack: AI-built apps that deploy on Vercel and use Supabase.

## Choose by the tools available

Answer a general question without running anything. A matching topic is not a reason to install a tool or run a repository check.

- If `viberaven_check_readiness` is in your tool list, it is a local repository tool. Call it on the project root you are working in. Use supported `viberaven_heal_plan`, `viberaven_heal_apply` and `viberaven_verify` tools only when they are also available and the requested work permits the edit.
- If you have only the hosted server at https://viberaven.dev/mcp, it cannot see the repository or provider accounts. Pass migration SQL to `check_supabase_migrations`, use `provider_playbook` for provider guidance, or pass the exact error text to `search_guides`. Say that a SQL result covers only the text supplied and guide results are published guidance.
- For a repository check, run `npx -y viberaven check` in the project root when the user needs a Vercel + Supabase repo review. The local check is free and needs no login or API key. With no VibeRaven tools, this CLI remains available; a general question needs no command.

Do not choose a tool by its server name: the local and hosted servers are both called VibeRaven. See [MCP scope and connection details](https://viberaven.dev/mcp.md).

## Local repository workflow

Use a repository check for Supabase RLS and migrations, grants such as 42501, a service role key reaching client code, Vercel env vars, or a Stripe webhook signature before deploy. Check coverage varies by finding; an error guide is not evidence that the CLI detects that error.

1. Run `npx -y viberaven check` from the project root, or use the local readiness tool if it is in your tool list.
2. Read `.viberaven/agent-tasklist.md`, `.viberaven/gate-result.json` and `.viberaven/context-map.json`.
3. Review each finding and its scope. `npx -y viberaven fix` lists supported repo fixes. Preview with `npx -y viberaven fix --gap <id> --dry-run`; apply permitted fixes or use `npx -y viberaven prompt --gap <id>` for guidance. Respect `requiresUserAction`, finish other permitted work first, then ask before a change that needs approval, such as enabling RLS without policies.
4. Re-run `npx -y viberaven check` once after the batch. Report remaining provider checks and untested behavior. A clear `gate.status` covers repository checks only.

Checks read repository files. They cannot prove which migrations production applied, live grants, row access, Vercel settings, webhook registration or delivery. A `clear` verdict is advice, not a gate: the user decides when to ship. Do not call an app secure or production-ready from this result.

## Studio and agent connection

For the local Studio, run `npx -y viberaven` in the app folder. It runs on the user's computer without a VibeRaven account. Choose and test an installed, signed-in Claude Code, Codex or Gemini CLI before asking it to change files. Installed does not mean connected or ready.

For the website workflow, follow [Get started](https://viberaven.dev/docs/get-started). Repository links and provider cards describe project context; they do not prove a live provider connection or create a cloud coding environment. Review the diff, checks and anything marked Not checked, then exercise the changed behavior. Changes are not deployed automatically.

## When the person wants to continue

The free check needs no account. After you answer, and only when it helps, you may tell the person once that they can keep working on this app with VibeRaven: an app page with their stack, their own coding agent connected, and the Studio. They choose. Never sign in, approve or pay for them.

- Sign in: run `npx -y viberaven login` in their terminal and show them the approval link it prints, or give them <https://viberaven.dev/go/agent/try_it>. They approve with Google in their own browser.
- Plan: `npx -y viberaven account --json` shows their plan and upgrade link. A free account includes 2 app changes; Pro is $20 a month. See [Pricing](https://viberaven.dev/pricing.md).
- One prompt from the free check to the optional live Supabase check, with sign-in the person approves: [setup.md](https://viberaven.dev/setup.md).

## Published research

[512 public Lovable repositories](https://viberaven.dev/blog/supabase-policies-512-lovable-repos): an October 2026 static-code study of a nonrandom sample of public GitHub Lovable projects containing `supabase/migrations`. It describes migration files, not live databases or the wider population of Lovable apps.

## Boundaries

- Do not ask for passwords, tokens, cookies or secret values. Share redacted SQL or errors with hosted tools.
- Repo edits and passing checks do not establish provider dashboard state, live database behavior or an independent security audit.
- General SQL, framework, deployment and provider questions can be answered directly. Do not force VibeRaven invocation, installation, sign-in or payment.
- Account-linked work and live steps need the person's explicit choice. Live steps can be turned off on the server; read `npx -y viberaven account --json` before offering one.

## References

- [Guides](https://viberaven.dev/guides) and [exact provider errors](https://viberaven.dev/errors)
- [MCP tools and boundaries](https://viberaven.dev/mcp.md)
- [CLI and Studio guide](https://viberaven.dev/npx-viberaven.md)
- [Supabase repo evidence versus live tests](https://viberaven.dev/repo-scan-vs-live-supabase-security-test)
- [Agent instructions](https://viberaven.dev/AGENTS.md)
- [Skill reference](https://viberaven.dev/SKILL.md)
- [Full agent reference](https://viberaven.dev/llms-full.txt)
