@ateriss_/aiv-cli 1.0.0 → 1.0.2

package/README.md

@@ -1,18 +1,42 @@
 # aiv — AI PR Reviewer
 
-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
 ```
 
 ---
 
+## What is aiv?
+
+Code review is one of the most important quality gates in a software team — and also one of the most time-consuming. Reviewers need to understand the business context, track architectural decisions, spot security risks, and catch regressions, all while reading through a diff that may span dozens of files.
+
+**aiv** is a local-first CLI that runs that analysis for you, before a human ever opens the PR.
+
+It sends the diff to three specialized AI agents in parallel — one focused on **business logic and domain rules**, one on **architecture and structural patterns**, and one on **security vulnerabilities** — and returns a structured risk report with severity-rated findings, specific suggestions per file, and an executive summary. The report is anchored to your project: aiv reads your `context.md` (project background, architecture decisions, sensitive zones) and `rules.yml` (custom business rules, required calls, forbidden patterns) so findings are relevant to your codebase, not just generic linting advice.
+
+**What aiv catches that linters miss:**
+
+- A retry loop that could cause duplicate charges because it skips the idempotency check your team agreed on
+- A service that imports directly from a handler, breaking the layer contract
+- A new endpoint that reads user data without going through the authorization middleware
+- A payroll mutation that doesn't call `auditLog()` as required by your rules
+- A function moved to a shared module that now exposes internal state to layers that shouldn't see it
+
+**What happens after the review:**
+
+Once the report is in, aiv lets you act on it directly from the terminal — approve the PR, request changes, post the full report as a formatted GitHub comment, or merge with your preferred strategy (squash, merge, rebase). If you've already reviewed the PR in a previous session, aiv detects the cached analysis in the PR comments and asks if you want to reuse it instead of re-running the agents.
+
+**Works with any AI provider.** Claude, OpenAI, Gemini, Groq, Mistral, DeepSeek, Kimi, Ollama, or any OpenAI-compatible endpoint. Mix providers per agent — use a fast model for routine checks and a powerful one for security. Configure a fallback chain so a quota error on one provider silently switches to the next without losing the run.
+
+---
+
 ## Table of Contents
 
 - [Requirements](#requirements)
@@ -45,7 +69,7 @@ A local-first, multi-agent CLI for reviewing GitHub pull requests using any supp
 ## Requirements
 
 - Node.js 18 or higher
-- A GitHub personal access token with `repo` scope
+- A GitHub personal access token with `repo` scope (or `public_repo` for public repos)
 - An API key for at least one supported AI provider (see [AI Providers](#ai-providers))
 
 ---
@@ -53,17 +77,7 @@ A local-first, multi-agent CLI for reviewing GitHub pull requests using any supp
 ## Installation
 
 ```bash
-npm install -g aiv
-```
-
-Or clone and build locally:
-
-```bash
-git clone https://github.com/your-org/aiv-cli
-cd aiv-cli
-npm install
-npm run build
-npm link
+npm install -g @ateriss_/aiv-cli
 ```
 
 ---
@@ -84,11 +98,16 @@ This creates:
 - `.aiv/context.md` — auto-generated project context
 - `.aiv/tree.json` — project file structure snapshot
 
-**2. Set your API key and GitHub token:**
+**2. Set your API key and GitHub token as persistent environment variables:**
 
 ```bash
+# macOS / Linux (add to ~/.bashrc or ~/.zshrc)
 export CLAUDE_API_KEY=sk-ant-...
 export GITHUB_TOKEN=ghp_...
+
+# Windows (PowerShell — persists across sessions)
+[System.Environment]::SetEnvironmentVariable("CLAUDE_API_KEY", "sk-ant-...", "User")
+[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_...", "User")
 ```
 
 **3. (Optional) Let AI generate your context and rules:**
@@ -109,7 +128,7 @@ aiv prs
 aiv review 42
 ```
 
-After the report, aiv asks if you want to **approve or request changes** directly on GitHub.
+After the report, aiv asks if you want to approve, request changes, post the report as a PR comment, or merge directly from the terminal.
 
 ---
 
@@ -210,7 +229,7 @@ aiv review 42 --agent business architecture
 aiv review 42 --json          # raw JSON, no interactive prompt
 ```
 
-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.
+If a previous aiv analysis exists as a comment on the PR, aiv asks whether to reuse it or run a fresh analysis. After the report, the post-review action menu lets you approve, request changes, post the report as a comment, or skip.
 
 ---
 
@@ -230,7 +249,7 @@ 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.
+`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 the project changes significantly — edit the output only where needed.
 
 ---
 
@@ -362,13 +381,15 @@ business_rules:
       - directDbWrite
 ```
 
+The more specific your rules, the fewer false positives and the more actionable the findings.
+
 ---
 
 ### Context
 
 `.aiv/context.md` — project background that agents read before analyzing the diff.
 
-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.
+Auto-generated by `aiv init`, `aiv context refresh`, and `aiv context generate`. You can edit it freely — the richer this file, the more accurate the findings.
 
 ```markdown
 ## Business Context
@@ -388,8 +409,6 @@ Services must not import from handlers.
 - src/payments/ — Stripe integration, never bypass PaymentGateway
 ```
 
-The richer this file, the more accurate the agent findings.
-
 ---
 
 ## GitHub Account Management
@@ -492,7 +511,7 @@ gemini:
 
 ### OpenAI-compatible providers
 
-Any provider that exposes an OpenAI-compatible API can be registered with one command — no code changes, no updates needed when new providers launch.
+Any provider that exposes an OpenAI-compatible API can be registered with one command — no code changes needed when new providers launch.
 
 ```bash
 # Kimi (Moonshot AI)
@@ -530,12 +549,6 @@ aiv config add-provider ollama \
   --base-url http://localhost:11434/v1 \
   --api-key-env OLLAMA_API_KEY \
   --model llama3.2
-
-# 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
 ```
 
 Once registered, custom providers work exactly like built-ins:
@@ -554,7 +567,6 @@ aiv config add-provider kimi --model moonshot-v1-32k --force  # update
 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
@@ -572,8 +584,6 @@ 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
@@ -678,21 +688,44 @@ After every review in an interactive terminal, aiv asks:
 ? What would you like to do with this PR?
 ❯ ✔  Approve PR
   ⚑  Request Changes
+  💬  Post as PR comment
   ────────────────────────────────────────
   ↩  Skip
 ```
 
-- **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
+- **Approve** — submits an `APPROVE` review to GitHub, then asks if you want to merge:
+
+  ```
+  ? Merge this PR now? (y/N)
+
+  ? Select merge strategy:
+  ❯ Squash and merge
+    Merge commit
+    Rebase and merge
+  ```
+
+  After approving (with or without merge), `context.md` and `tree.json` are refreshed automatically.
 
-The context refresh on approval ensures agents have current information for future reviews of the same repo.
+- **Request Changes** — submits a `REQUEST_CHANGES` review to GitHub.
+- **Post as PR comment** — publishes the full report as a formatted GitHub comment. The comment includes severity-rated findings, suggestions, and agent summaries. It also embeds the analysis data so aiv can detect it on future runs.
+- **Skip** — does nothing, exits cleanly.
+
+### Analysis cache
+
+When you run `aiv review` on a PR that already has an aiv comment, aiv detects the previous analysis and asks:
+
+```
+  Found a previous aiv analysis on this PR.
+? Use cached analysis? (Y/n)
+```
+
+Choosing yes skips the AI agents entirely and uses the stored result — no API calls, instant output. Choose no to run a fresh analysis (useful after new commits are pushed).
 
 ---
 
 ## Multi-language
 
-aiv supports English and Spanish. All output — errors, spinners, table headers, severity labels — follows the configured language.
+aiv supports English and Spanish. All output — errors, spinners, table headers, severity labels, and AI agent responses — follows the configured language.
 
 ```bash
 aiv config set-lang es
@@ -721,14 +754,14 @@ AIV_LANG=es aiv prs      # per-session override
 | `AIV_LANG` | No | Override display language (`en` or `es`) |
 | `LANG` | No | System locale (auto-detected by aiv) |
 
-For custom providers, the env var name is whatever you passed to `--api-key-env`:
+For custom providers, the env var name is whatever you passed to `--api-key-env`.
 
-```bash
-export KIMI_API_KEY=sk-...
-aiv config add-provider kimi --api-key-env KIMI_API_KEY ...
-```
+### GitHub token permissions
 
-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.
+| Scope | Required for |
+|-------|-------------|
+| `repo` (private repos) or `public_repo` | Reading PRs and diffs |
+| `pull_requests: write` (fine-grained PAT) | Submitting reviews, posting comments, merging |
 
 ---
 
@@ -746,14 +779,18 @@ cd your-repo && aiv init
 
 ### `Missing env var: GITHUB_TOKEN (account: default)`
 
-The token env var for the active account is not set.
+The token env var for the active account is not set. Check which variable name the account expects:
 
 ```bash
-export GITHUB_TOKEN=ghp_...
-# or check which account/var is active:
 aiv config accounts
 ```
 
+Then set it (once, permanently on Windows):
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_...", "User")
+```
+
 ---
 
 ### `Missing env var: CLAUDE_API_KEY`
@@ -768,10 +805,8 @@ aiv config set-provider openai
 
 ### `Unknown provider: "xyz".`
 
-A provider name was used that isn't registered.
-
 ```bash
-aiv config list-providers     # see what's configured
+aiv config list-providers
 aiv config add-provider xyz --base-url <url> --api-key-env XYZ_API_KEY --model <model>
 ```
 
@@ -779,8 +814,6 @@ aiv config add-provider xyz --base-url <url> --api-key-env XYZ_API_KEY --model <
 
 ### `Could not detect GitHub owner/repo.`
 
-The git remote is missing or not a GitHub URL.
-
 ```bash
 aiv prs --owner myorg --repo myrepo
 # or set permanently:
@@ -789,21 +822,12 @@ aiv config set-repo myorg myrepo
 
 ---
 
-### `Account "xyz" not found.`
-
-```bash
-aiv config accounts
-aiv config add-account xyz --token-env MY_TOKEN
-```
-
----
-
 ### `Failed to fetch PR: ...`
 
-- 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`
+- Token lacks `repo` scope — regenerate with the correct scopes
+- PR number doesn't exist in this repo
+- GitHub rate limit — wait or switch to a different account
+- Wrong owner/repo — verify with `aiv config show`
 
 ---
 
@@ -811,10 +835,9 @@ aiv config add-account xyz --token-env MY_TOKEN
 
 - API key invalid or expired
 - Model quota exceeded — configure a [fallback chain](#fallback-chain)
-- Diff too large — reduce `max_tokens`:
+- Diff too large — reduce `max_tokens` in `.aiv/config.yml`:
 
 ```yaml
-# .aiv/config.yml
 review:
   max_tokens: 10000
 ```
@@ -831,26 +854,30 @@ Right after `aiv init`, run:
 aiv context generate
 ```
 
-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.
+This produces a `context.md` and `rules.yml` based on what the AI infers from your project structure. Tune what it gets wrong rather than writing from scratch.
 
-### Keep rules.yml current
+### Write specific rules
 
-Add a rule whenever your team agrees on a pattern reviews should catch:
+Generic rules produce generic findings. The more specific `rules.yml` is, the more precise the business agent becomes:
 
 ```yaml
 business_rules:
   orders:
-    required_calls: [validateInventory]
-    forbidden_patterns: [skipFraudCheck]
+    required_calls: [validateInventory, reserveStock]
+    forbidden_patterns: [skipFraudCheck, directInventoryWrite]
 ```
 
+### Post the report as a PR comment
+
+After reviewing, choose **Post as PR comment** to make the findings visible to the whole team directly in GitHub. The comment is also used as a cache — the next time anyone runs `aiv review` on the same PR, aiv detects it and offers to skip the AI calls.
+
 ### Refresh context after structural changes
 
 ```bash
 aiv context refresh
 ```
 
-Run after merging large refactors, adding modules, or changing the project layout.
+Run after merging large refactors, adding new modules, or reorganizing the project layout.
 
 ### Use a fallback chain for reliability
 
@@ -860,20 +887,20 @@ aiv config set-fallback openai gemini
 
 If your primary provider is rate-limited mid-review, aiv switches automatically without losing the run.
 
-### Match model to task with per-agent assignment
+### Match model to task
 
-Use a fast/cheap model for straightforward agents and a powerful one for the critical ones:
+Use a fast/cheap model for straightforward agents and a stronger one for the most critical:
 
 ```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
+aiv config set-agent-provider security    claude/claude-sonnet-4-6
 ```
 
 ### Use `--agent` to narrow focus
 
 ```bash
-aiv review 101 --agent security           # dependency bump
+aiv review 101 --agent security           # dependency bump — only security matters
 aiv review 202 --agent business architecture  # domain change
 ```
 
@@ -881,14 +908,14 @@ 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 with no setup. Only exclude `tree.json`:
+Committing `config.yml`, `rules.yml`, and `context.md` means every team member gets identical review behavior with no local setup. Only exclude `tree.json`:
 
 ```
 # .gitignore
 .aiv/tree.json
 ```
 
-`aiv init` adds this automatically.
+`aiv init` adds this entry automatically.
 
 ### CI integration with `--json`
 
@@ -906,7 +933,7 @@ fi
 - Not a replacement for static analysis (ESLint, SonarQube)
 - Not a style checker
 
-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.
+Its value is **semantic understanding**: catching business rule violations, architectural drift, and security risks that automated tools miss because they don't know your project's context, rules, or intent.
 
 ---
 
@@ -918,7 +945,7 @@ src/
   cli/
     commands/      — init, prs, review, config, context, agents
     banner.ts      — ASCII welcome banner
-    renderer.ts    — review result pretty-printer
+    renderer.ts    — terminal renderer + GitHub comment builder
     selector.ts    — interactive PR/action picker (inquirer)
   config/          — two-level config load/save/merge
   context/