npm - @ateriss_/aiv-cli - Versions diffs - 0.1.0 → 1.0.0 - Mend

@ateriss_/aiv-cli 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -3,14 +3,12 @@
 A local-first, multi-agent CLI for reviewing GitHub pull requests using any supported AI provider. Runs three specialized agents in parallel (Business, Architecture, Security) and produces a structured risk report with findings, suggestions, and an executive summary.
 ```
- █████╗ ██╗    ██████╗ ██████╗     ██████╗ ███████╗██╗   ██╗██╗███████╗██╗    ██╗███████╗██████╗
-██╔══██╗██║    ██╔══██╗██╔══██╗    ██╔══██╗██╔════╝██║   ██║██║██╔════╝██║    ██║██╔════╝██╔══██╗
-███████║██║    ██████╔╝██████╔╝    ██████╔╝█████╗  ██║   ██║██║█████╗  ██║ █╗ ██║█████╗  ██████╔╝
-██╔══██║██║    ██╔═══╝ ██╔══██╗    ██╔══██╗██╔══╝  ╚██╗ ██╔╝██║██╔══╝  ██║███╗██║██╔══╝  ██╔══██╗
-██║  ██║██║    ██║     ██║  ██║    ██║  ██║███████╗ ╚████╔╝ ██║███████╗╚███╔███╔╝███████╗██║  ██║
-╚═╝  ╚═╝╚═╝    ╚═╝     ╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝  ╚═══╝  ╚═╝╚══════╝ ╚══╝╚══╝ ╚══════╝╚═╝  ╚═╝
-													                                                             by Ateriss
+  █████╗ ██╗██╗   ██╗
+ ██╔══██╗██║██║   ██║
+ ███████║██║██║   ██║
+ ██╔══██║██║╚██╗ ██╔╝
+ ██║  ██║██║ ╚████╔╝
+ ╚═╝  ╚═╝╚═╝  ╚═══╝   by Ateriss
 ```
 ---
@@ -22,13 +20,21 @@ A local-first, multi-agent CLI for reviewing GitHub pull requests using any supp
 - [Quick Start](#quick-start)
 - [Commands Reference](#commands-reference)
 - [Configuration](#configuration)
-  - [Global Config](#global-config-aivconfig-yml)
-  - [Repo Config](#repo-config-aivconfigyml)
-  - [Rules](#rules-aivrules-yml)
-  - [Context](#context-aivcontextmd)
+  - [Global Config](#global-config)
+  - [Repo Config](#repo-config)
+  - [Rules](#rules)
+  - [Context](#context)
 - [GitHub Account Management](#github-account-management)
 - [AI Providers](#ai-providers)
+  - [Built-in: Claude](#claude-default)
+  - [Built-in: OpenAI](#openai)
+  - [Built-in: Gemini](#google-gemini)
+  - [OpenAI-compatible (custom)](#openai-compatible-providers)
+  - [Per-agent assignment](#per-agent-provider-assignment)
+  - [Fallback chain](#fallback-chain)
+  - [Mock](#mock-offline-testing)
 - [Review Output](#review-output)
+- [Post-review Actions](#post-review-actions)
 - [Multi-language](#multi-language)
 - [Environment Variables](#environment-variables)
 - [Error Reference](#error-reference)
@@ -72,7 +78,7 @@ aiv init
 ```
 This creates:
-- `~/.aiv/config.yml` — global config (AI provider, GitHub accounts)
+- `~/.aiv/config.yml` — global config (AI providers, GitHub accounts)
 - `.aiv/config.yml` — repo config (owner, repo, account override)
 - `.aiv/rules.yml` — custom review rules for agents
 - `.aiv/context.md` — auto-generated project context
@@ -85,19 +91,25 @@ export CLAUDE_API_KEY=sk-ant-...
 export GITHUB_TOKEN=ghp_...
 ```
-**3. List open pull requests:**
+**3. (Optional) Let AI generate your context and rules:**
+```bash
+aiv context generate
+```
+**4. List open pull requests:**
 ```bash
 aiv prs
 ```
-**4. Review a PR:**
+**5. Review a PR:**
 ```bash
 aiv review 42
 ```
-That's it. The three agents run in parallel and print a full report.
+After the report, aiv asks if you want to **approve or request changes** directly on GitHub.
 ---
@@ -105,150 +117,135 @@ That's it. The three agents run in parallel and print a full report.
 Every command has a short alias. Long and short forms are identical.
-| Long form                              | Short alias   | Description                                       |
-|----------------------------------------|---------------|---------------------------------------------------|
-| `aiv init`                             | `aiv i`       | Initialize aiv in the current repo                |
-| `aiv prs`                              | `aiv p`       | List open PRs and optionally review one           |
-| `aiv review [pr-number]`               | `aiv r`       | Review a PR or pick one interactively             |
-| `aiv context refresh`                  | `aiv ctx refresh` | Rebuild `context.md` and `tree.json`         |
-| `aiv context show`                     | `aiv ctx show` | Print current `context.md`                      |
-| `aiv config show`                      | `aiv cf show` | Show global and repo config                       |
-| `aiv config set-provider <provider>`   | `aiv cf set-provider` | Switch AI provider                      |
-| `aiv config set-repo <owner> <repo>`   | `aiv cf set-repo` | Set GitHub owner/repo in repo config        |
-| `aiv config set-lang <lang>`           | `aiv cf set-lang` | Change display language (`en` / `es`)       |
-| `aiv config rules`                     | `aiv cf rules` | Print `rules.yml`                               |
-| `aiv config accounts`                  | `aiv cf accounts` | List GitHub accounts                        |
-| `aiv config add-account <name>`        | `aiv cf add-account` | Add a GitHub account                     |
-| `aiv config remove-account <name>`     | `aiv cf remove-account` | Remove a GitHub account               |
-| `aiv config default-account <name>`    | `aiv cf default-account` | Set global default account           |
-| `aiv config use-account <name>`        | `aiv cf use-account` | Use an account for this repo             |
-| `aiv agents`                           | `aiv a`       | List available agents and their focus areas       |
+### Core
+| Long form | Short | Description |
+|-----------|-------|-------------|
+| `aiv init` | `aiv i` | Initialize aiv globally and in the current repo |
+| `aiv prs` | `aiv p` | List open PRs, then optionally review one |
+| `aiv review [pr-number]` | `aiv r` | Review a PR or pick interactively |
+| `aiv agents` | `aiv a` | List available agents and their focus areas |
+### Context
+| Long form | Short | Description |
+|-----------|-------|-------------|
+| `aiv context refresh` | `aiv ctx refresh` | Rebuild `context.md` and `tree.json` from the codebase |
+| `aiv context show` | `aiv ctx show` | Print current `context.md` |
+| `aiv context generate` | `aiv ctx generate` | Use AI to generate `context.md` and `rules.yml` |
+### Config — general
+| Long form | Short | Description |
+|-----------|-------|-------------|
+| `aiv config show` | `aiv cf show` | Show global and repo config files |
+| `aiv config set-provider <name>` | `aiv cf set-provider` | Set default AI provider |
+| `aiv config set-repo <owner> <repo>` | `aiv cf set-repo` | Set GitHub owner/repo in repo config |
+| `aiv config set-lang <lang>` | `aiv cf set-lang` | Change display language (`en` / `es`) |
+| `aiv config rules` | `aiv cf rules` | Print `rules.yml` |
+### Config — providers
+| Long form | Description |
+|-----------|-------------|
+| `aiv config add-provider <name>` | Add or update a provider (built-in or custom OpenAI-compatible) |
+| `aiv config remove-provider <name>` | Remove a custom provider |
+| `aiv config list-providers` | List all configured providers and their status |
+| `aiv config set-agent-provider <agent> [spec]` | Assign a specific provider/model to one agent |
+| `aiv config set-fallback [providers...]` | Set ordered fallback chain for quota/rate errors |
+| `aiv config show-agents` | Show per-agent provider assignments and fallback chain |
+### Config — GitHub accounts
+| Long form | Description |
+|-----------|-------------|
+| `aiv config accounts` | List GitHub accounts |
+| `aiv config add-account <name>` | Add a GitHub account |
+| `aiv config remove-account <name>` | Remove a GitHub account |
+| `aiv config default-account <name>` | Set global default account |
+| `aiv config use-account <name>` | Use a specific account for this repo |
 ---
 ### `aiv init`
-Initializes aiv globally and in the current repository.
 ```bash
 aiv init
 aiv i
 ```
-Safe to run in any order — if `~/.aiv/config.yml` already exists it is preserved. Re-running `init` inside a repo always rebuilds `context.md` and `tree.json` to reflect the current state of the project.
+Safe to re-run — if `~/.aiv/config.yml` already exists it is preserved. Re-running inside a repo always rebuilds `context.md` and `tree.json`.
 ---
 ### `aiv prs`
-Fetches and displays open pull requests in a table, then opens an interactive selector.
+Fetches open PRs in a table, then launches an interactive selector.
 ```bash
 aiv prs
 aiv p
-# Limit results
 aiv prs --limit 10
-# Override repo auto-detection
 aiv prs --owner myorg --repo myrepo
-# List only, skip interactive selector
-aiv prs --no-select
+aiv prs --no-select           # list only, skip selector
 ```
-The table shows PR number, title, author, branch, diff size (`+additions/-deletions`), and creation date. After the table, an interactive prompt lets you select a PR and launch a review without typing a number.
-**Repo auto-detection:** aiv reads `git remote get-url origin` to detect the GitHub owner and repo. If the remote is not a GitHub URL or is missing, use `--owner`/`--repo` flags or configure them in `.aiv/config.yml`.
+**Repo auto-detection:** reads `git remote get-url origin`. If it fails, pass `--owner`/`--repo` or set them with `aiv config set-repo`.
 ---
 ### `aiv review`
-Reviews a pull request. Accepts a PR number directly or launches an interactive selector if omitted.
+Reviews a pull request. Omit the number to pick interactively.
 ```bash
-# Review by number
 aiv review 42
 aiv r 42
-# Interactive selector (fetches open PRs first)
-aiv review
-aiv r
-# Override repo
+aiv review                    # interactive selector
 aiv review 42 --owner myorg --repo myrepo
-# Run specific agents only
 aiv review 42 --agent security
 aiv review 42 --agent business architecture
-# Output raw JSON (useful for scripting and CI)
-aiv review 42 --json
+aiv review 42 --json          # raw JSON, no interactive prompt
 ```
-Available agents: `business`, `architecture`, `security`. All three run in parallel by default.
+After the report prints, aiv asks whether to **approve**, **request changes**, or **skip** — and submits the decision directly to GitHub. If you approve, `context.md` and `tree.json` are refreshed automatically.
 ---
 ### `aiv context`
-Manages the project context used by agents during reviews.
 ```bash
-# Rebuild context.md and tree.json from the current directory
-aiv context refresh
+aiv context refresh            # rebuild from codebase (static analysis)
 aiv ctx refresh
-# Print the current context.md
-aiv context show
+aiv context show               # print context.md
 aiv ctx show
-```
-Run `context refresh` after major structural changes to the project (new modules, new dependencies, large refactors) so agents have accurate background information.
----
-### `aiv config`
-All configuration subcommands. Running `aiv config` or `aiv cf` alone prints help.
-```bash
-# Show global and repo config files
-aiv config show
-aiv cf show
-# Switch AI provider
-aiv config set-provider openai
-aiv cf set-provider claude
-# Set repo owner/repo explicitly
-aiv config set-repo myorg myrepo
-# Change display language
-aiv config set-lang es
-aiv config set-lang en
-# Show rules.yml
-aiv config rules
+aiv context generate           # AI-powered generation
+aiv ctx generate
+aiv ctx generate --context-only
+aiv ctx generate --rules-only
+aiv ctx generate --force       # overwrite without asking
 ```
+`generate` uses the configured AI provider (or `providers.agents.context` if set) to analyze the project structure and produce a `context.md` and `rules.yml` tailored to your stack. Run it after `init` or whenever a new AI agent type is added — edit the output only where needed.
 ---
 ### `aiv agents`
-Lists all available agents with their description and focus areas.
 ```bash
 aiv agents
 aiv a
 ```
-| Agent        | Focus areas                                                              |
-|--------------|--------------------------------------------------------------------------|
-| business     | Business logic, domain invariants, rule violations, functional regressions |
+| Agent | Focus areas |
+|-------|-------------|
+| business | Business logic, domain invariants, rule violations, functional regressions |
 | architecture | Layer violations, coupling, SRP, dependency direction, abstraction quality |
-| security     | Auth bypass, injection, data leakage, OWASP Top 10, sensitive data handling |
+| security | Auth bypass, injection, data leakage, OWASP Top 10, sensitive data handling |
 ---
@@ -256,36 +253,58 @@ aiv a
 aiv uses a two-level configuration system:
-| File                  | Scope  | Purpose                                           |
-|-----------------------|--------|---------------------------------------------------|
-| `~/.aiv/config.yml`  | Global | AI providers, GitHub accounts, default settings   |
-| `.aiv/config.yml`    | Repo   | Owner/repo override, account override, token limits |
+| File | Scope | Purpose |
+|------|-------|---------|
+| `~/.aiv/config.yml` | Global | AI providers, GitHub accounts, defaults |
+| `.aiv/config.yml` | Repo | Owner/repo override, account override, token limits |
-Repo-level settings always override global defaults.
+Repo settings always override global defaults.
 ---
-### Global Config (`~/.aiv/config.yml`)
+### Global Config
-Created automatically by `aiv init`. Edit manually or use `aiv config` subcommands.
+`~/.aiv/config.yml` — created by `aiv init`, shared across all repos.
 ```yaml
 lang: en                        # 'en' or 'es'
 providers:
-  default: claude               # 'claude', 'openai', or 'mock'
+  default: claude               # active provider
+  fallback: [openai, gemini]    # tried in order on quota/rate errors
+  agents:                       # per-agent overrides (provider or provider/model)
+    business:     claude/claude-sonnet-4-6
+    architecture: gemini/gemini-2.0-flash
+    security:     openai/gpt-4.1
+    context:      claude/claude-sonnet-4-6
+# Built-in providers
 claude:
   model: claude-sonnet-4-6
-  api_key_env: CLAUDE_API_KEY   # env var holding your Anthropic key
+  api_key_env: CLAUDE_API_KEY
 openai:
   model: gpt-4.1
-  api_key_env: OPENAI_API_KEY   # env var holding your OpenAI key
+  api_key_env: OPENAI_API_KEY
+gemini:
+  model: gemini-2.0-flash
+  api_key_env: GEMINI_API_KEY
+# Custom OpenAI-compatible providers
+custom_providers:
+  kimi:
+    base_url: https://api.moonshot.cn/v1
+    api_key_env: KIMI_API_KEY
+    model: moonshot-v1-8k
+  groq:
+    base_url: https://api.groq.com/openai/v1
+    api_key_env: GROQ_API_KEY
+    model: llama-3.3-70b-versatile
 review:
-  max_tokens: 20000             # max tokens sent to the model per agent
-  max_findings: 20              # max findings returned per review
+  max_tokens: 20000
+  max_findings: 20
 github:
   default_account: personal
@@ -302,9 +321,9 @@ github:
 ---
-### Repo Config (`.aiv/config.yml`)
+### Repo Config
-Created in each repository by `aiv init`. Overrides global defaults for that repo.
+`.aiv/config.yml` — created per repository by `aiv init`.
 ```yaml
 github:
@@ -317,13 +336,11 @@ review:
   max_findings: 30
 ```
-Leave any field out to inherit from global config. The `account` field references a named account defined in `~/.aiv/config.yml`.
 ---
-### Rules (`.aiv/rules.yml`)
+### Rules
-Defines custom rules that all agents respect. Edit after `aiv init`.
+`.aiv/rules.yml` — custom review rules passed to every agent on every review.
 ```yaml
 sensitive_modules:
@@ -345,25 +362,25 @@ business_rules:
       - directDbWrite
 ```
-Rules are passed verbatim to every agent on every review. The business and security agents use them to flag violations explicitly.
 ---
-### Context (`.aiv/context.md`)
+### Context
+`.aiv/context.md` — project background that agents read before analyzing the diff.
-Auto-generated by `aiv init` and `aiv context refresh`. Contains a summary of the project that agents use as background knowledge before reading the diff. You can append custom sections manually — they are preserved on the next refresh.
+Auto-generated by `aiv init`, `aiv context refresh`, and `aiv context generate`. You can edit it freely — custom sections are preserved on the next refresh.
 ```markdown
 ## Business Context
-This is an e-commerce platform handling real-money transactions.
-All changes touching `src/payments/` must include an audit log entry.
-The `UserBalance` model must never be modified outside the `billing` module.
+E-commerce platform handling real-money transactions.
+All changes in `src/payments/` must include an audit log entry.
+`UserBalance` must never be modified outside the `billing` module.
 ## Architecture
 Three-layer: HTTP handlers → service layer → repositories.
-Cross-layer imports are forbidden; services must not import from handlers.
+Services must not import from handlers.
 ## Sensitive Zones
@@ -377,63 +394,32 @@ The richer this file, the more accurate the agent findings.
 ## GitHub Account Management
-aiv supports multiple GitHub accounts (personal, work, CI bot) stored globally and activated per repo.
 ### Add accounts
 ```bash
-# Minimum — just the env var name
 aiv config add-account personal --token-env GITHUB_TOKEN
-# With optional metadata
 aiv config add-account work \
   --token-env GITHUB_TOKEN_WORK \
   --username alice-corp \
-  --description "Work GitHub account"
-# Overwrite an existing account
-aiv config add-account work --token-env NEW_VAR --force
+  --description "Work GitHub"
+aiv config add-account work --token-env NEW_VAR --force   # overwrite
 ```
-### List accounts
-```bash
-aiv config accounts
-```
-Shows all configured accounts, their token env vars, which ones are set, and which is the global default.
-### Set global default
-```bash
-aiv config default-account work
-```
-All repos without an explicit account override will use this account.
-### Use a specific account for one repo
-```bash
-cd my-work-repo
-aiv config use-account work
-```
-This writes `github.account: work` into `.aiv/config.yml`. Only affects the current repo.
-### Remove an account
+### Manage accounts
 ```bash
+aiv config accounts                     # list all accounts + token status
+aiv config default-account work         # set global default
+aiv config use-account work             # use this account for current repo
 aiv config remove-account old-account
 ```
 ### Account resolution order
-When aiv needs a GitHub token it checks:
-1. `github.account` in `.aiv/config.yml` (repo-level override)
+1. `github.account` in `.aiv/config.yml`
 2. `github.default_account` in `~/.aiv/config.yml`
-3. First account listed in `~/.aiv/config.yml`
-4. Fallback to `GITHUB_TOKEN` env var directly
+3. First account in `~/.aiv/config.yml`
+4. `GITHUB_TOKEN` env var directly
 ---
@@ -443,9 +429,9 @@ aiv supports three kinds of providers:
 | Type | Examples | Notes |
 |------|----------|-------|
-| **Built-in** | Claude, OpenAI, Gemini | Native adapters, configured in `~/.aiv/config.yml` |
-| **OpenAI-compatible** | Kimi, Groq, Mistral, DeepSeek, Ollama, Together AI, … | Any new provider with a compatible endpoint — no code changes |
-| **Mock** | — | Deterministic offline responses for testing |
+| **Built-in** | Claude, OpenAI, Gemini | Native adapters, no extra setup |
+| **OpenAI-compatible** | Kimi, Groq, Mistral, DeepSeek, Ollama, … | Any provider with a compatible endpoint |
+| **Mock** | — | Deterministic offline responses |
 ---
@@ -456,7 +442,7 @@ export CLAUDE_API_KEY=sk-ant-...
 aiv config set-provider claude
 ```
-Update model or key env without editing the file:
+Update model or key env:
 ```bash
 aiv config add-provider claude --model claude-opus-4-7
@@ -464,7 +450,6 @@ aiv config add-provider claude --api-key-env MY_CLAUDE_KEY
 ```
 ```yaml
-# ~/.aiv/config.yml
 claude:
   model: claude-sonnet-4-6
   api_key_env: CLAUDE_API_KEY
@@ -489,17 +474,12 @@ openai:
 ### Google Gemini
-Gemini uses a dedicated REST adapter (no extra SDK required).
+Gemini uses a dedicated REST adapter — no extra SDK or dependency required.
 ```bash
 export GEMINI_API_KEY=AIza...
 aiv config set-provider gemini
-```
-Update model:
-```bash
-aiv config add-provider gemini --model gemini-2.0-flash-exp
+aiv config add-provider gemini --model gemini-2.0-flash-exp   # change model
 ```
 ```yaml
@@ -510,27 +490,24 @@ gemini:
 ---
-### OpenAI-compatible providers (custom)
+### OpenAI-compatible providers
-Any provider that exposes an OpenAI-compatible API can be registered with one command. This includes every new provider that adopts the OpenAI spec — no code changes or updates needed.
+Any provider that exposes an OpenAI-compatible API can be registered with one command — no code changes, no updates needed when new providers launch.
 ```bash
 # Kimi (Moonshot AI)
-export KIMI_API_KEY=sk-...
 aiv config add-provider kimi \
   --base-url https://api.moonshot.cn/v1 \
   --api-key-env KIMI_API_KEY \
   --model moonshot-v1-8k
 # Groq
-export GROQ_API_KEY=gsk_...
 aiv config add-provider groq \
   --base-url https://api.groq.com/openai/v1 \
   --api-key-env GROQ_API_KEY \
   --model llama-3.3-70b-versatile
 # Mistral
-export MISTRAL_API_KEY=...
 aiv config add-provider mistral \
   --base-url https://api.mistral.ai/v1 \
   --api-key-env MISTRAL_API_KEY \
@@ -548,26 +525,25 @@ aiv config add-provider together \
   --api-key-env TOGETHER_API_KEY \
   --model meta-llama/Llama-3-70b-chat-hf
-# Ollama (local, no key needed)
+# Ollama (local, no key required)
 aiv config add-provider ollama \
   --base-url http://localhost:11434/v1 \
   --api-key-env OLLAMA_API_KEY \
   --model llama3.2
-```
-Once registered, use any custom provider exactly like a built-in:
-```bash
-aiv config set-provider kimi
-aiv config set-agent-provider security groq/llama-3.3-70b-versatile
-aiv config set-fallback groq openai
+# Any future provider that adopts the OpenAI spec
+aiv config add-provider newprovider \
+  --base-url https://api.newprovider.com/v1 \
+  --api-key-env NEWPROVIDER_API_KEY \
+  --model their-model-name
 ```
-Manage custom providers:
+Once registered, custom providers work exactly like built-ins:
 ```bash
-aiv config list-providers                   # show all built-in + custom
-aiv config remove-provider kimi             # remove a custom provider
+aiv config set-provider kimi
+aiv config list-providers                    # built-ins + custom
+aiv config remove-provider kimi
 aiv config add-provider kimi --model moonshot-v1-32k --force  # update
 ```
@@ -575,36 +551,41 @@ aiv config add-provider kimi --model moonshot-v1-32k --force  # update
 ### Per-agent provider assignment
-Run each agent with a different provider or model:
+Each agent (and the context generator) can use a different provider or model:
 ```bash
+# Assign provider/model per agent
 aiv config set-agent-provider business    claude/claude-sonnet-4-6
 aiv config set-agent-provider security    openai/gpt-4.1
 aiv config set-agent-provider architecture gemini/gemini-2.0-flash
 aiv config set-agent-provider context     kimi/moonshot-v1-8k
+# Use just a provider name (uses that provider's default model)
+aiv config set-agent-provider business groq
 # View current assignments
 aiv config show-agents
-# Remove an override (reverts to default)
+# Remove override (reverts to default provider)
 aiv config set-agent-provider business --clear
 ```
+Valid agent roles: `business`, `architecture`, `security`, `context`.
+The `context` role is used by `aiv context generate`. All other roles map to the review agents.
 ---
 ### Fallback chain
-If a provider hits a rate limit or quota error, aiv automatically switches to the next in the chain:
+If any provider hits a rate limit or quota error (HTTP 429, overloaded, insufficient quota), aiv automatically switches to the next provider in the chain — for the rest of that run.
 ```bash
-# Try openai first, then gemini, then kimi
-aiv config set-fallback openai gemini kimi
-# Clear the chain
-aiv config set-fallback
+aiv config set-fallback openai gemini groq   # try in this order
+aiv config set-fallback                       # clear the chain
 ```
-When a fallback fires, aiv prints:
+When a fallback fires:
 ```
   ⚡ "claude" quota/rate limit — switching to "openai"
@@ -618,17 +599,14 @@ When a fallback fires, aiv prints:
 aiv config set-provider mock
 ```
-Returns deterministic placeholder findings. Use this to test the CLI locally without consuming API credits.
+Returns deterministic placeholder findings. Use this to test the CLI without consuming API credits.
 ---
 ## Review Output
-A typical review looks like:
 ```
   aiv review — PR #42
   Account: personal (GITHUB_TOKEN)
 ✔ PR loaded: "Add payment retry logic" (8 files)
@@ -649,10 +627,8 @@ A typical review looks like:
   ───────────────
   [HIGH]  Missing idempotency key on retry
           File: src/payments/retry.ts
-          Retry attempts do not include an idempotency key, allowing
-          the payment provider to process the same charge multiple times.
-          Suggestion: Pass a stable idempotency key derived from the
-          original transaction ID.
+          Suggestion: Pass a stable idempotency key derived from
+          the original transaction ID.
   Business Risks
   ──────────────
@@ -662,8 +638,6 @@ A typical review looks like:
   Architecture Issues
   ───────────────────
   [MEDIUM]  Direct database write outside billing module
-            src/payments/retry.ts imports UserBalance from outside
-            the billing boundary.
   Agent Summaries
   ───────────────
@@ -674,8 +648,6 @@ A typical review looks like:
 ### Risk score
-Computed as `max_score × 0.6 + average_score × 0.4` across all agents.
 | Score  | Label    |
 |--------|----------|
 | 0–25   | LOW      |
@@ -683,62 +655,80 @@ Computed as `max_score × 0.6 + average_score × 0.4` across all agents.
 | 51–75  | HIGH     |
 | 76–100 | CRITICAL |
-### JSON output
+Computed as `max_score × 0.6 + average_score × 0.4` across all agents.
-Use `--json` to get the full structured result for scripts or CI pipelines:
+### JSON output
 ```bash
 aiv review 42 --json | jq '.riskScore'
 aiv review 42 --json > review-42.json
 ```
-The JSON shape matches the `ReviewResult` type: `prNumber`, `prTitle`, `riskScore`, `riskLabel`, `executiveSummary`, `agents[]`, `securityIssues[]`, `businessRisks[]`, `architectureIssues[]`, `possibleRegressions[]`.
+Shape: `prNumber`, `prTitle`, `riskScore`, `riskLabel`, `executiveSummary`, `agents[]`, `securityIssues[]`, `businessRisks[]`, `architectureIssues[]`, `possibleRegressions[]`.
+`--json` skips the post-review action prompt.
 ---
-## Multi-language
+## Post-review Actions
+After every review in an interactive terminal, aiv asks:
-aiv supports English and Spanish. All terminal output — errors, spinners, table headers, severity labels — follows the configured language.
+```
+? What would you like to do with this PR?
+❯ ✔  Approve PR
+  ⚑  Request Changes
+  ────────────────────────────────────────
+  ↩  Skip
+```
-### Switch language
+- **Approve** — submits an `APPROVE` review to GitHub, then auto-refreshes `context.md` and `tree.json`
+- **Request Changes** — submits a `REQUEST_CHANGES` review to GitHub
+- **Skip** — does nothing, exits cleanly
+The context refresh on approval ensures agents have current information for future reviews of the same repo.
+---
+## Multi-language
+aiv supports English and Spanish. All output — errors, spinners, table headers, severity labels — follows the configured language.
 ```bash
-# Permanently (saved to ~/.aiv/config.yml)
 aiv config set-lang es
 aiv config set-lang en
-# Per-session via env var (overrides config)
-AIV_LANG=es aiv prs
-AIV_LANG=en aiv review 42
+AIV_LANG=es aiv prs      # per-session override
 ```
-### Language detection order
+### Detection order
 1. `AIV_LANG` environment variable
 2. `lang` in `~/.aiv/config.yml`
-3. System `LANG` environment variable (auto-detected `es_*` locales use Spanish)
+3. System `LANG` variable (`es_*` locales → Spanish)
 4. Default: `en`
 ---
 ## Environment Variables
-| Variable              | Required | Description                                          |
-|-----------------------|----------|------------------------------------------------------|
-| `GITHUB_TOKEN`        | Yes      | GitHub personal access token (default account)       |
-| `CLAUDE_API_KEY`      | Yes*     | Anthropic API key (*required when using Claude)      |
-| `OPENAI_API_KEY`      | Yes*     | OpenAI API key (*required when using OpenAI)         |
-| `AIV_LANG`            | No       | Override display language (`en` or `es`)             |
-| `LANG`                | No       | System locale (auto-detected by aiv)                 |
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITHUB_TOKEN` | Yes | GitHub personal access token (default account) |
+| `CLAUDE_API_KEY` | Yes* | Anthropic API key (*when using Claude) |
+| `OPENAI_API_KEY` | Yes* | OpenAI API key (*when using OpenAI) |
+| `GEMINI_API_KEY` | Yes* | Google AI API key (*when using Gemini) |
+| `AIV_LANG` | No | Override display language (`en` or `es`) |
+| `LANG` | No | System locale (auto-detected by aiv) |
-For additional GitHub accounts, the env var name is whatever you passed to `--token-env`:
+For custom providers, the env var name is whatever you passed to `--api-key-env`:
 ```bash
-export GITHUB_TOKEN_WORK=ghp_...
-aiv config add-account work --token-env GITHUB_TOKEN_WORK
+export KIMI_API_KEY=sk-...
+aiv config add-provider kimi --api-key-env KIMI_API_KEY ...
 ```
-GitHub tokens require `repo` scope to read pull requests and diffs.
+GitHub tokens require `repo` scope to read pull requests and diffs. To submit reviews (approve/request changes), the token also needs `pull_requests:write` scope.
 ---
@@ -746,26 +736,21 @@ GitHub tokens require `repo` scope to read pull requests and diffs.
 ### `Not initialized. Run aiv init first.`
-You ran a command that requires `.aiv/config.yml` but it doesn't exist in the current directory.
+`.aiv/config.yml` does not exist in the current directory.
 ```bash
-cd your-repo
-aiv init
+cd your-repo && aiv init
 ```
 ---
 ### `Missing env var: GITHUB_TOKEN (account: default)`
-The token env var for the active account is not set in the environment.
+The token env var for the active account is not set.
 ```bash
 export GITHUB_TOKEN=ghp_...
-```
-If you use a named account with a different env var, check which account is active and what it expects:
-```bash
+# or check which account/var is active:
 aiv config accounts
 ```
@@ -773,71 +758,60 @@ aiv config accounts
 ### `Missing env var: CLAUDE_API_KEY`
-The AI provider API key is not set. Set the env var or switch providers:
 ```bash
 export CLAUDE_API_KEY=sk-ant-...
-# or switch to OpenAI
+# or switch providers:
 aiv config set-provider openai
-export OPENAI_API_KEY=sk-...
 ```
 ---
-### `Could not detect GitHub owner/repo.`
+### `Unknown provider: "xyz".`
-aiv could not parse the GitHub owner and repo from `git remote get-url origin`. This happens when the remote is not a GitHub URL, the repo has no remote, or the remote uses an unsupported format.
+A provider name was used that isn't registered.
-Fix — pass flags directly:
 ```bash
-aiv prs --owner myorg --repo myrepo
-aiv review 42 --owner myorg --repo myrepo
-```
-Fix — set permanently in repo config:
-```bash
-aiv config set-repo myorg myrepo
+aiv config list-providers     # see what's configured
+aiv config add-provider xyz --base-url <url> --api-key-env XYZ_API_KEY --model <model>
 ```
 ---
-### `Account "xyz" not found.`
+### `Could not detect GitHub owner/repo.`
-You referenced an account name that doesn't exist in `~/.aiv/config.yml`.
+The git remote is missing or not a GitHub URL.
 ```bash
-aiv config accounts                               # list what's available
-aiv config add-account xyz --token-env MY_TOKEN  # add the missing account
+aiv prs --owner myorg --repo myrepo
+# or set permanently:
+aiv config set-repo myorg myrepo
 ```
 ---
-### `Account "xyz" already exists. Use --force to overwrite.`
+### `Account "xyz" not found.`
 ```bash
-aiv config add-account xyz --token-env NEW_VAR --force
+aiv config accounts
+aiv config add-account xyz --token-env MY_TOKEN
 ```
 ---
 ### `Failed to fetch PR: ...`
-Network or GitHub API error. Common causes:
-- Token lacks `repo` scope — regenerate with full repo permissions
-- PR number does not exist in the target repository
-- GitHub rate limit hit — wait or switch to a token with higher limits
-- Wrong `owner`/`repo` — verify with `aiv config show`
+- Token lacks `repo` scope — regenerate
+- PR number doesn't exist
+- GitHub rate limit — wait or switch token
+- Wrong owner/repo — check with `aiv config show`
 ---
 ### `Review failed: ...`
-The AI provider returned an error. Common causes:
-- API key is invalid or expired
-- Model quota exceeded
-- Network timeout on a very large diff — reduce `max_tokens` in config:
+- API key invalid or expired
+- Model quota exceeded — configure a [fallback chain](#fallback-chain)
+- Diff too large — reduce `max_tokens`:
 ```yaml
 # .aiv/config.yml
@@ -849,81 +823,90 @@ review:
 ## Best Practices
-### Fill in context before the first review
+### Let AI bootstrap your context and rules
+Right after `aiv init`, run:
+```bash
+aiv context generate
+```
-After `aiv init`, open `.aiv/context.md` and describe your project: what it does, which modules are critical, invariants that must never be violated. This is the single most impactful thing you can do to improve finding accuracy.
+This gives you a ready-to-edit `context.md` and `rules.yml` based on what the AI infers from your project. Tune what it gets wrong rather than writing from scratch.
-### Define rules for your domain
+### Keep rules.yml current
-Add a rule every time your team agrees on a pattern that reviews should enforce. Rules are passed to every agent on every review — they act as a live checklist that doesn't drift.
+Add a rule whenever your team agrees on a pattern reviews should catch:
 ```yaml
 business_rules:
   orders:
-    required_calls:
-      - validateInventory
-    forbidden_patterns:
-      - skipFraudCheck
+    required_calls: [validateInventory]
+    forbidden_patterns: [skipFraudCheck]
 ```
-### Refresh context after major changes
+### Refresh context after structural changes
 ```bash
 aiv context refresh
 ```
-Run this after merging a large refactor, adding a new module, or changing the project structure significantly. Stale context silently reduces finding quality.
+Run after merging large refactors, adding modules, or changing the project layout.
-### Use `--agent` to narrow the focus
-Not every PR needs all three agents. If you're reviewing a dependency bump, only security matters. If it's a UI-only change, skip security and architecture:
+### Use a fallback chain for reliability
 ```bash
-aiv review 101 --agent security
-aiv review 202 --agent business architecture
+aiv config set-fallback openai gemini
 ```
-Fewer agents means faster results and lower API cost.
+If your primary provider is rate-limited mid-review, aiv switches automatically without losing the run.
+### Match model to task with per-agent assignment
-### Use named accounts from day one
+Use a fast/cheap model for straightforward agents and a powerful one for the critical ones:
-Even with a single GitHub account, naming it makes configuration explicit and makes it trivial to add a second account later:
+```bash
+aiv config set-agent-provider business    claude/claude-haiku-4-5
+aiv config set-agent-provider architecture claude/claude-haiku-4-5
+aiv config set-agent-provider security    claude/claude-sonnet-4-6   # strongest model here
+```
+### Use `--agent` to narrow focus
 ```bash
-aiv config add-account personal \
-  --token-env GITHUB_TOKEN \
-  --username alice \
-  --description "Personal GitHub"
+aiv review 101 --agent security           # dependency bump
+aiv review 202 --agent business architecture  # domain change
 ```
+Fewer agents = faster, cheaper, more focused output.
 ### Commit `.aiv/` to the repository
-Committing `config.yml`, `rules.yml`, and `context.md` means every team member gets identical review behavior without any manual setup. Add only `tree.json` to `.gitignore` since it's a generated snapshot:
+Committing `config.yml`, `rules.yml`, and `context.md` means every team member gets identical review behavior with no setup. Only exclude `tree.json`:
 ```
 # .gitignore
 .aiv/tree.json
 ```
-`aiv init` adds this entry automatically.
+`aiv init` adds this automatically.
-### Integrate into CI with `--json`
+### CI integration with `--json`
 ```bash
 SCORE=$(aiv review $PR_NUMBER --json | jq '.riskScore')
 if [ "$SCORE" -gt 75 ]; then
-  echo "High-risk PR — human review required before merge"
+  echo "High-risk PR — human review required"
   exit 1
 fi
 ```
 ### What aiv is not
-- Not a linter or formatter — it won't tell you about semicolons
-- Not a replacement for static analysis tools (ESLint, SonarQube)
-- Not checking code style
+- Not a linter — it won't flag semicolons or indentation
+- Not a replacement for static analysis (ESLint, SonarQube)
+- Not a style checker
-Its value is **semantic understanding**: catching what automated tools miss — business rule violations, architectural drift, and security risks that only make sense in context.
+Its value is **semantic understanding**: catching business rule violations, architectural drift, and security risks that automated tools miss because they require project context to understand.
 ---
@@ -931,20 +914,30 @@ Its value is **semantic understanding**: catching what automated tools miss —
 ```
 src/
-  agents/          — business, architecture, security (extend BaseAgent)
+  agents/          — business, architecture, security reviewers
   cli/
-    commands/      — one file per command (init, prs, review, config, context, agents)
+    commands/      — init, prs, review, config, context, agents
     banner.ts      — ASCII welcome banner
     renderer.ts    — review result pretty-printer
-    selector.ts    — interactive PR picker (inquirer)
+    selector.ts    — interactive PR/action picker (inquirer)
   config/          — two-level config load/save/merge
-  context/         — project tree scanner and context builder
-  git/             — GitHub REST client and git remote detection
+  context/
+    builder.ts     — static project analysis
+    generator.ts   — AI-powered context + rules generation
+    manager.ts     — context reader + refreshContextFiles helper
+    tree.ts        — file tree scanner
+  git/             — GitHub REST client + remote detection
   i18n/            — EN/ES translations (all user-facing strings)
   orchestrator/    — runs agents in parallel, aggregates results
-  providers/       — Claude, OpenAI, Mock AI client wrappers
+  providers/
+    claude.ts      — Anthropic adapter
+    openai.ts      — OpenAI adapter (supports custom baseURL)
+    gemini.ts      — Google Gemini REST adapter
+    fallback.ts    — FallbackProvider (quota/rate pivot)
+    factory.ts     — resolves provider by name or agent role
+    mock.ts        — offline test provider
   types.ts         — shared TypeScript interfaces
-  index.ts         — CLI entry point (Commander root)
+  index.ts         — CLI entry point
 ```
 ---

package/dist/index.js CHANGED Viewed

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-"use strict";var Ut=Object.create;var Ee=Object.defineProperty;var Bt=Object.getOwnPropertyDescriptor;var Ht=Object.getOwnPropertyNames;var qt=Object.getPrototypeOf,zt=Object.prototype.hasOwnProperty;var Jt=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Vt=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of Ht(t))!zt.call(e,i)&&i!==n&&Ee(e,i,{get:()=>t[i],enumerable:!(o=Bt(t,i))||o.enumerable});return e};var u=(e,t,n)=>(n=e!=null?Ut(qt(e)):{},Vt(t||!e||!e.__esModule?Ee(n,"default",{value:e,enumerable:!0}):n,e));var Be=Jt((Bn,Wt)=>{Wt.exports={name:"@ateriss_/aiv-cli",version:"0.1.0",description:"AI-powered PR reviewer CLI \u2014 local-first, multi-agent semantic analysis",main:"dist/index.js",bin:{aiv:"dist/index.js"},scripts:{build:"tsup",typecheck:"tsc",dev:"ts-node src/index.ts",start:"node dist/index.js",prepublishOnly:"npm run build"},keywords:["ai","pr-review","cli","github","claude","openai"],author:"",license:"MIT",dependencies:{"@anthropic-ai/sdk":"^0.37.0",chalk:"^5.3.0",commander:"^12.1.0",inquirer:"^9.3.7","js-yaml":"^4.1.0","node-fetch":"^3.3.2",ora:"^8.1.1",openai:"^4.77.0",table:"^6.8.2"},devDependencies:{"@types/inquirer":"^9.0.7","@types/js-yaml":"^4.0.9","@types/node":"^22.10.0","ts-node":"^10.9.2",tsup:"^8.3.5",typescript:"^5.7.2"},engines:{node:">=18.0.0"}}});var Ot=require("commander");var se=u(require("fs")),Ge=u(require("path")),Me=u(require("os"));var Ae={notInitialized:"Not initialized. Run `aiv init` first.",invalidProvider:"Invalid provider. Choose: claude, openai, mock",invalidPrNumber:"Invalid PR number.",repoNotDetected:"Could not detect GitHub owner/repo. Use --owner and --repo flags or configure in .aiv/config.yml",initAlreadyDone:"aiv is already initialized. Use --force to reinitialize.",initTitle:`  aiv \u2014 AI PR Reviewer
+"use strict";var Ut=Object.create;var Ee=Object.defineProperty;var Bt=Object.getOwnPropertyDescriptor;var Ht=Object.getOwnPropertyNames;var qt=Object.getPrototypeOf,zt=Object.prototype.hasOwnProperty;var Jt=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Vt=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of Ht(t))!zt.call(e,i)&&i!==n&&Ee(e,i,{get:()=>t[i],enumerable:!(o=Bt(t,i))||o.enumerable});return e};var u=(e,t,n)=>(n=e!=null?Ut(qt(e)):{},Vt(t||!e||!e.__esModule?Ee(n,"default",{value:e,enumerable:!0}):n,e));var Be=Jt((Bn,Wt)=>{Wt.exports={name:"@ateriss_/aiv-cli",version:"1.0.0",description:"AI-powered PR reviewer CLI \u2014 local-first, multi-agent semantic analysis",main:"dist/index.js",bin:{aiv:"dist/index.js"},scripts:{build:"tsup",typecheck:"tsc",dev:"ts-node src/index.ts",start:"node dist/index.js",prepublishOnly:"npm run build"},keywords:["ai","pr-review","cli","github","claude","openai"],author:"",license:"MIT",dependencies:{"@anthropic-ai/sdk":"^0.37.0",chalk:"^5.3.0",commander:"^12.1.0",inquirer:"^9.3.7","js-yaml":"^4.1.0","node-fetch":"^3.3.2",ora:"^8.1.1",openai:"^4.77.0",table:"^6.8.2"},devDependencies:{"@types/inquirer":"^9.0.7","@types/js-yaml":"^4.0.9","@types/node":"^22.10.0","ts-node":"^10.9.2",tsup:"^8.3.5",typescript:"^5.7.2"},engines:{node:">=18.0.0"}}});var Ot=require("commander");var se=u(require("fs")),Ge=u(require("path")),Me=u(require("os"));var Ae={notInitialized:"Not initialized. Run `aiv init` first.",invalidProvider:"Invalid provider. Choose: claude, openai, mock",invalidPrNumber:"Invalid PR number.",repoNotDetected:"Could not detect GitHub owner/repo. Use --owner and --repo flags or configure in .aiv/config.yml",initAlreadyDone:"aiv is already initialized. Use --force to reinitialize.",initTitle:`  aiv \u2014 AI PR Reviewer
 `,initWritingGlobalConfig:"Writing global config (~/.aiv/config.yml)...",initGlobalConfigCreated:"Global config created (~/.aiv/config.yml)",initGlobalConfigExists:"Global config already exists (~/.aiv/config.yml)",initWritingConfig:"Writing repo config (.aiv/config.yml)...",initConfigCreated:"Repo config created (.aiv/config.yml)",initRulesCreated:"rules.yml created",initScanningTree:"Scanning project structure...",initTreeCreated:"tree.json created",initTreeSkipped:"tree.json skipped (could not scan)",initBuildingContext:"Building project context...",initContextCreated:"context.md created",initContextSkipped:"context.md skipped (could not analyze)",initGitignoreUpdated:".gitignore updated",initSuccessTitle:`
   Initialized! Next steps:
 `,initStep1:e=>`  Set your API key:    export ${e}=your-key`,initStep2:e=>`  Set GitHub token:    export ${e}=your-token`,initStep3:"  List PRs:            aiv prs",initStep4:"  Review a PR:         aiv review <pr-number>",initEditContext:e=>`  Edit ${e} to add business context.`,initEditRules:e=>`  Edit ${e} to define your rules.`,initGlobalHint:"  Global config: ~/.aiv/config.yml",initAddAccountHint:"  Add accounts:  aiv config add-account <name> --token-env <VAR>",selectorSelectPR:"Select a PR to review:",selectorConfirmReview:"Review",selectorCancelled:`  Cancelled.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name":  "@ateriss_/aiv-cli",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "AI-powered PR reviewer CLI — local-first, multi-agent semantic analysis",
   "main": "dist/index.js",
   "bin": {