# xailon-review user guide

xailon-review writes evidence-graded engineering reports about a codebase, reviews pull requests, catches AI slop, and keeps architecture decisions enforced. It is a standalone binary. The analysis engine is the XailonCode CLI (`xailon`), which xailon-review runs in the background.

**Contents**
1. [Install and first run](#1-install-and-first-run)
2. [Five-minute tour](#2-five-minute-tour)
3. [Reading a report](#3-reading-a-report)
4. [Reports: readiness, follow-up, whiteboard](#4-reports)
5. [The interactive viewer](#5-the-interactive-viewer)
6. [Pull-request review bot](#6-pull-request-review-bot)
7. [AI-slop validator](#7-ai-slop-validator)
8. [Pattern index](#8-pattern-index)
9. [Competitive and architecture analysis](#9-competitive-and-architecture-analysis)
10. [Scanning, branch checks and the decision ledger](#10-scanning-branch-checks-and-the-decision-ledger)
11. [Integrations: console, MCP, guard hook, live mod, CI](#11-integrations)
12. [Configuration reference](#12-configuration-reference)
13. [Cost and time](#13-cost-and-time)
14. [Troubleshooting](#14-troubleshooting)
15. [FAQ](#15-faq)

---

## 1. Install and first run

**You need:**
- macOS on Apple Silicon (XailonCode is Apple Silicon only for now)
- the `xailon` CLI on your `PATH`, signed in, with a working model
- `git`
- optional: `gh` (GitHub CLI, signed in) for PR facts and the PR bot
- optional: Google Chrome or Chromium for PDF output

**Get the binary:**
```sh
node scripts/build-binary.mjs        # builds dist/xailon-review (~100 MB, no Node needed to run it)
cp dist/xailon-review /usr/local/bin/
```
To run from source instead, use Node 22.13 or later and run `npm link`.

**Check the engine:**
```sh
xailon-review engine check                # JSON mode (default)
xailon-review engine check --engine acp   # ACP mode
```
If this fails, fix XailonCode first (see [Troubleshooting](#14-troubleshooting)). If `xailon` is not on your `PATH`, set `XAILON_BIN=/path/to/xailon`.

**Where things are stored:**

| Location | What |
|---|---|
| `<repo>/.xailon-review/xailon-review.db` | Code index, findings, audit log (SQLite) |
| `<repo>/.xailon-review/reviews/` | Reports: `<id>.json`, `.html`, `.pdf`, `.interactive.html` |
| `<repo>/.xailon-review/decisions/*.md` | Decision ledger, meant to be committed |
| `~/.xailon-review/patterns/index.json` | Pattern index, shared across repos |
| `~/.xailon-review/cache/` | Shallow clones used for pattern learning |

Add `.xailon-review/*.db` and `.xailon-review/pr/` to `.gitignore`. Commit `decisions/`, and commit `reviews/` too if you want report history in git.

---

## 2. Five-minute tour

```sh
cd ~/code/my-service
xailon-review scan                          # index and run the deterministic scanners (seconds, no model)
xailon-review review readiness --org "Platform team"   # full review (5–8 min)
xailon-review view                          # explore it in the browser and ask questions
xailon-review review whiteboard             # architecture tour with diagrams (3–4 min)
xailon-review pr 128                        # dry-run review of PR #128 (posts nothing)
xailon-review slop src/                     # AI-slop check
```

All commands work on the current directory. To target another repo, pass `--root <dir>`, or pass the path after the review type: `review readiness ~/code/other`.

---

## 3. Reading a report

Every report follows the same rules, so you can read one, then trust the format of the others.

### Evidence tags
Every claim says how it is known:

| Tag | Meaning |
|---|---|
| **[observed]** | Read in the code, configuration or a merged PR at the reviewed commit |
| **[computed]** | Arithmetic on observed values (for example "4 MB × 1,000 connections = 4 GB") |
| **[inferred]** | Reasoning from what was read. Not run against a live system |

### Citation checking
Every `path:line` is checked against the repository at that commit after the model finishes. A citation that does not resolve is marked **†**. An `[observed]` claim whose citations all fail is downgraded to `[inferred]`. The "How to read this report" section shows the counts.

### Categories and IDs (readiness and follow-up)

| ID | Category | Meaning | What you do |
|---|---|---|---|
| **A#** | (a) Needs work | Defects a user or operator will hit | Fix |
| **C#** | (b) Constraint | Limits on deployment or use | Plan the rollout around them |
| **S#** | (c) SLA | Hard-failure behaviour that is fine once written down | Sign off in writing |
| **G#** | Architecture gap | Structural choice underneath many items | Make a design decision |

**One rule:** a failure with no recovery path never goes in SLA. An SLA can put a price on downtime or data loss. It cannot put one on "the system does not come back".

### Severity
`blocker` (do not ship), `high`, `medium`, `low`. Within a category, items are ordered by severity.

### ⚠ marks
In whiteboard tours and the code map, ⚠ marks a structural weak spot, or a module with open high or blocker scanner findings.

### The code map
The code map is drawn deterministically from build manifests, directory structure and resolved imports. No model is involved, so two runs at the same commit give the same map. A red dashed edge closes a dependency cycle.

---

## 4. Reports

### Production readiness review
```sh
xailon-review review readiness [path] [--org NAME] [--areas 7] [--parallel 3]
```
How it works:
1. **Facts (no model):** index, module graph, scanners, git churn, deploy and CI files, listening ports. With `gh`, it also collects merged PRs that had no second reviewer, and open issues.
2. **Area reviewers:** XailonCode agents work in parallel, read-only. There is one per area: the largest modules, security and identity, durability and recovery, and deployment and operations.
3. **Lead synthesis:** deduplicates, sorts into A, C and S, names the architecture gaps, and writes the summary, recommendation, process notes and next steps.
4. **Verification and render.**

**Sections:**
- Summary and recommendation
- How to read
- Architecture gaps
- (a) Needs work, (b) Constraints, (c) SLA
- Process
- What is already good
- Code map
- Next steps

**Tips:**
- `--areas` controls breadth: more areas cost more tokens and give more findings.
- `--parallel` controls speed. Keep it at 3–4 unless your XailonCode plan allows more concurrency.
- Run `scan` first on large repos so the facts step is fast.

### Follow-up review
```sh
xailon-review review followup --prior latest      # or --prior <review id>
```
Reloads the earlier readiness review and re-checks every item at the current commit. Each item is marked **closed**, **mostly closed** (with what is left) or **open**, and fixes are attributed to the merged PRs that made them. Only code that changed since the earlier review is reviewed again. Use it after a fix sprint.

### Whiteboard tour
```sh
xailon-review review whiteboard [path]
```
Explains how the system is built, diagrams first:
- the system on one page and the code map
- one section per mechanism (state, request routing, writes, replication, recovery …), with ⚠ weak spots
- a "bets" table (each design choice, what it buys and what it costs)
- a comparison with similar systems

Mermaid diagrams are syntax-checked in a headless browser, and broken ones are sent back to the engine for repair, up to two passes.

### Managing reports
```sh
xailon-review reports                 # list
xailon-review reports --open <id>     # open the PDF
xailon-review render <id>             # re-render HTML/PDF from the stored JSON (recomputes the code map, re-checks diagrams)
```
Report IDs look like `readiness-2026-10-28-8b10e2d` (type, date, commit). `latest` refers to the most recent readiness review.

---

## 5. The interactive viewer

```sh
xailon-review view                    # all reports, http://127.0.0.1:7421
xailon-review view <id>               # open a specific report
xailon-review view --port 8080 --no-open
xailon-review view <id> --static      # write <id>.interactive.html to share
```

| Tab | What you can do |
|---|---|
| **Overview** | Summary and recommendation. Clickable charts: findings by category × severity, how-known grade, findings by area. Gap → finding map: hover to trace, click to open |
| **Findings** | Filter by category, severity, grade, area, module or text. Click a row for detail, the gap it is rooted in, and the cited code with the lines highlighted |
| **Architecture gaps** | Each gap and the findings it causes |
| **Re-checks** | (follow-ups) closed, mostly closed or open, with a chart |
| **Code map** | Pan (drag), zoom (scroll), search, hide tests and tools. Hover traces imports, click shows a module's findings, double-click asks about the module |
| **Whiteboard / Bets** | Rendered diagrams with an "Ask about this section" button, the bets table and the comparison |
| **Feature map / Architecture / User reviews / Gaps / Sources** | (compete reports) matrix filterable to "where we lag" or "where we lead", every web source linked |
| **Report structure** | How the report was built (click each stage), what each part, ID and tag means, the citation-check counts |

**Ask the report.** Click **Ask the report** (top right) to open the chat.
- Ask anything about the report or the code. XailonCode reads the report, can open files in the repo (read-only), cites `path:line`, refers to items by ID, and says so when the report is wrong.
- **Focus:** "Ask about this" on an item, module or section adds it as context. **Clear focus** removes it.
- Suggested questions change with the report type and focus.
- A typical answer takes 30–90 seconds and 0.5–2M tokens. Progress steps stream while it works.

**Safety:** the server binds to 127.0.0.1 only. Code requests are confined to the repository root. Ask runs XailonCode read-only. If the port is busy, the viewer uses the next free one.

**Static export:** one HTML file with the report embedded. Charts, filters, the code map and diagrams all work offline (diagrams need internet to load Mermaid). Ask and code snippets need the live server, so they are hidden.

---

## 6. Pull-request review bot

```sh
xailon-review pr 2983                    # dry run: prints the review, posts nothing
xailon-review pr https://github.com/org/repo/pull/2983
xailon-review pr 2983 --post             # post ONE GitHub review (summary + inline comments)
xailon-review pr 2983 --post --block     # REQUEST_CHANGES and exit 1 on a blocker/high
xailon-review pr 2983 --max-comments 8
```

**What it does:**
1. Checks out the PR head in a throwaway worktree (`.xailon-review/pr/<n>`).
2. Runs the deterministic checks on **added lines only**: security rules, decision-ledger rules, slop detectors. It also computes the blast radius (who imports the changed files) and finds other open branches touching the same files.
3. Runs one focused engine pass over the diff and the surrounding code, using relevant patterns from the pattern index. It reports bugs, security problems, data loss, broken contracts and slop that matters. It never reports style.
4. Places comments only on lines that are in the diff. Anything else goes in the summary under "Outside the changed lines".

**Re-runs:** after a new push, run it again. It reads the hidden state marker in its earlier review and never repeats a comment.

**Each comment shows:**
- severity
- `[observed]` or `[inferred]`
- source: engine, static rule, slop or decision

**Requirements:** `gh` signed in, with write access to the repo for `--post`.

> Dry run is the default on purpose. Run without `--post` first on any repository you don't own.

---

## 7. AI-slop validator

```sh
xailon-review slop                    # whole repo: findings + slop index (per 1,000 lines)
xailon-review slop src/ api/          # specific paths
xailon-review slop src/ --deep        # + engine pass judged against the pattern index
xailon-review slop --json
```

| Detector | Catches | Severity |
|---|---|---|
| phantom-import | Package in no manifest or lockfile (hallucinated, or missing) | high |
| phantom-import | Package used but only installed transitively (undeclared) | medium |
| swallowed-error | Empty catch, log-only catch, `except: pass`, Go `_ = err` | medium |
| hollow-test | Assertions that cannot fail, tests with no assertions | medium |
| placeholder | TODO/stub/"implement later" in production code | medium |
| debug-leftover | `console.log`, `print(`, `debugger` left in production code | low |
| narrating-comment | Comments that restate the next line | low |
| copy-paste | 8-line blocks repeated across 2+ files | low |
| ai-artifact | Pasted model output ("As an AI…", "Here's the updated code") | high |

**`--deep`** sends the static hits plus a sample of the code to XailonCode, judged against the pattern index. It rejects false positives, adds problems the detectors cannot see (for example a rate limiter defeated by `trustProxy: true`), cites a pattern for each, and gives an overall verdict: clean, some slop, or sloppy.

**Known limits:**
- Phantom-import checks cover JS/TS and Go manifests. Python imports are not checked yet.
- Generated, migration, seed and data paths are excluded from copy-paste detection.

---

## 8. Pattern index

The index lists concrete engineering rules learned from well-regarded open-source repos. Slop `--deep` and PR reviews judge code against it.

```sh
xailon-review patterns repos                      # catalog (✓ = learned)
xailon-review patterns repos --lang go
xailon-review patterns learn fastify/fastify      # one repo (or any owner/repo, even outside the catalog)
xailon-review patterns learn --lang ts            # a language
xailon-review patterns learn --all                # everything not yet learned
xailon-review patterns learn --all --force        # re-learn everything
xailon-review patterns list --category error-handling
xailon-review patterns search timeout
```

**Catalog:** 24 repos across Go, TypeScript, Python, Rust and JVM, including healthcare/FHIR projects (medplum, HAPI FHIR).

**Each pattern has:**
- a rule you can check in a review
- the anti-pattern it avoids
- the failure it prevents
- a cited example (`path:lines` and a GitHub permalink)

Citations are checked against the clone, and patterns with bad citations are dropped.

**Categories:**
- error-handling
- input-validation
- resource-bounds
- concurrency
- persistence-transactions
- config-and-secrets
- security-authz
- shutdown-lifecycle
- observability
- testing
- api-design
- module-structure

Learning takes about 3–4 minutes and 1.5–2M tokens per repo, which is about 1.5 hours for the full catalog. The index is per user (`~/.xailon-review`), so you learn once and every repo benefits.

---

## 9. Competitive and architecture analysis

```sh
export PARALLEL_API_KEY=…     # Parallel Web Systems, or
export TINYFISH_API_KEY=…     # TinyFish
xailon-review compete                                     # discover competitors automatically
xailon-review compete --vs competitor-a.com,competitor-b.com   # name them
xailon-review compete --product "AI code review with cited reports" --max 4
xailon-review compete --web tinyfish --no-fetch
```

**Pipeline:**
1. **Self profile:** XailonCode reads your repo and lists its capabilities, each with maturity (solid, partial or stub) and code evidence. It also gives the market category and search queries.
2. **Research:**
   - Competitors are found by web search (or taken from `--vs`).
   - For each one it searches features and pricing, architecture and deployment, and independent user reviews (Reddit, HN, G2).
   - TinyFish also fetches full pages. With Parallel, pages are fetched directly unless you pass `--no-fetch`.
   - Every page becomes a numbered source **W1…Wn**.
3. **Synthesis:**
   - feature map: ● has it · ◐ partial · ○ does not · **?** no source says. It never guesses "does not".
   - architecture compared, with ⚠ weaknesses
   - what users praise and complain about
   - ranked gaps: must, should, could or skip, with effort S/M/L/XL. "Skip" is an explicit "not worth chasing".
   - where you are ahead, and next moves
4. **Verification:** unknown W ids and missing files are marked †. An `[observed]` claim with no valid source is downgraded.

Vendor pages are treated as claims. User reviews and documentation count for more. Open the result with `xailon-review view` for the filterable matrix.

---

## 10. Scanning, branch checks and the decision ledger

These run without any model. They are fast and deterministic, so they suit pre-commit hooks and CI.

### Scan
```sh
xailon-review scan                 # incremental: only changed files are re-indexed
xailon-review overview
```
**Analyzers:**
- secrets
- injection, TLS turned off, weak crypto
- import cycles (Tarjan), orphan files, god files
- churn × complexity hotspots
- decision violations

Findings are fingerprinted, so they keep their identity across scans and resolve automatically when the code is fixed.

### Search and impact
```sh
xailon-review search "rate limit"          # BM25 over code chunks + symbol boost
xailon-review symbol handleConn
xailon-review impact src/http/service.go   # who depends on this file (default depth 3, --depth N)
xailon-review context src/a.ts src/b.ts    # context pack: the files, their neighbours, decisions in scope
```

### Branch check
```sh
xailon-review check                        # vs origin/main
xailon-review check --base origin/develop
```
Reports issues on **added lines only**, decisions in scope, blast radius, and other branches editing the same files. Exits with code **1** on blocking issues, so it works as a pre-push hook or CI gate.

### Decision ledger
Architecture decisions are Markdown files in `.xailon-review/decisions/` that contain machine-checkable rules.

```sh
xailon-review decision new --title "HTTP goes through lib/http" \
  --decision "Services must not import axios directly" --rationale "Retries, timeouts and tracing live in lib/http" \
  --scope "src/**" --owner platform --status active \
  --rules '[{"type":"forbid_import","pattern":"axios","message":"Use lib/http"}]'
xailon-review decision list
xailon-review decision accept <slug>       # proposed → active
xailon-review decision retire <slug>
xailon-review decision supersede <slug>
```

**Rule types:**

| type | Fields | Meaning |
|---|---|---|
| `forbid_import` | `pattern` (glob or package) | Files in scope must not import it |
| `layer` | `from`, `to` (globs) | Files matching `from` must not depend on files matching `to` |
| `forbid_pattern` | `regex`, `flags` | No line may match |
| `require_pattern` | `regex`, `flags` | Every file in scope must contain it |

Every rule also accepts these optional fields: `in`, `except` (globs), `severity` (default `high`) and `message`.

You can also edit the Markdown directly. The rules go in an ` ```atlas-rules ` JSON block. Only `active` decisions are enforced.

---

## 11. Integrations

| Integration | How | What it gives you |
|---|---|---|
| **Console** | `xailon-review serve [--port 7420]` | Overview, findings triage, decisions, search, dependency graph, branch review, audit log |
| **MCP server** | `xailon-review mcp` (stdio) | 10 read-only tools for XailonCode or any MCP agent: search, impact, context packs, decisions, change checks |
| **Guard hook** | `hooks/settings.json` (PreToolUse → `xailon-review guard`) | Blocks an agent's edit when it would break an active decision, and tells the agent why |
| **Live mod** | `xailon --mod-dir mod/` | Side pane in XailonCode with live findings and the decisions in scope for the files being edited. Commands: review-scan, review-check, review-context, review-decide |
| **GitHub Action** | copy `integrations/github/xailon-review.yml` to `.github/workflows/` | PR review on every pull request |

**GitHub Action setup:**
- **Runner:** `macos-14` (Apple Silicon).
- **Secrets:** `XAILON_CONFIG_YAML` and `XAILON_SECRETS_YAML`, which hold your XailonCode config and secrets.
- **Repository variable:** `XAILON_REVIEW_BINARY_URL`, where the workflow downloads the binary from.

The Action posts with `--post`. Add `--block` if you want it to fail the check on blockers.

---

## 12. Configuration reference

### Global flags
| Flag | Meaning |
|---|---|
| `--root <dir>` | Repository to work on (default: current directory) |
| `--json` | Machine-readable output |
| `--version` | Print version |
| `--verbose` | Stream the engine's tool calls |

### Engine flags (any AI command)
| Flag | Meaning |
|---|---|
| `--engine json\|acp` | Transport to XailonCode (default `json`). ACP keeps one session per task and streams |
| `--model M`, `--provider P`, `--profile NAME` | Passed through to XailonCode |
| `--max-turns N` | Agent turn limit per task (default 60) |

### Environment variables
| Variable | Meaning |
|---|---|
| `XAILON_BIN` | Path to the `xailon` binary |
| `XREVIEW_ENGINE` | Default engine (`json` or `acp`) |
| `XREVIEW_ROOT` | Default repository root |
| `CHROME_PATH` | Chrome/Chromium for PDF and diagram checks |
| `PARALLEL_API_KEY` / `TINYFISH_API_KEY` | Web research for `compete` |

Your XailonCode models, privacy routing and spending limits apply to every AI command.

---

## 13. Cost and time

Rough figures from real runs (rqlite, about 100k lines of Go; a TypeScript monorepo):

| Command | Time | Tokens |
|---|---|---|
| `scan`, `check`, `slop` (static) | seconds | 0 |
| `review readiness` | 5–8 min | 12–17M |
| `review whiteboard` | 3–4 min | ~3.5M |
| `review followup` | 3–6 min | depends on changes |
| `pr` | ~3 min | 1–2M |
| `slop --deep` | 2–4 min | 1–3M |
| `patterns learn` (per repo) | 3–4 min | 1.5–2M |
| `compete` | 5–10 min | 3–6M, plus web API calls |
| `view` → one question | 30–90 s | 0.5–2M |

**To spend less:**
- lower `--areas`
- review a sub-path
- use a cheaper `--model` for `pr` and `slop --deep`

---

## 14. Troubleshooting

| Symptom | Fix |
|---|---|
| `engine check` fails | Run `xailon exec "say hi"` yourself. Check sign-in and model. Set `XAILON_BIN` if `xailon` is not on `PATH` |
| "no PDF" / only HTML written | Install Chrome or set `CHROME_PATH`. The HTML is complete either way |
| A diagram shows as source text | Run `xailon-review render <id>` to retry diagram repair. Mermaid needs internet to load in the HTML |
| Code map has one giant box | Run `xailon-review scan` again (to resolve aliases), then `render <id>` |
| Many † citations | The repo moved since the review. Re-render at the reviewed commit, or run a follow-up |
| `pr` says it cannot fetch | `gh auth status`. The repo needs a GitHub remote |
| Viewer port busy | It moves to the next free port automatically. Watch the printed URL |
| Ask is slow or times out | Large reports take longer. Ask narrower questions, or focus on one item |
| `compete`: "no web provider" | Set `PARALLEL_API_KEY` or `TINYFISH_API_KEY` |
| Old report shows K-numbers or gaps starting at G5 | Saved by an older version. Run `xailon-review render <id>` |
| Slop flags a package you do install | It may be transitive only. Declare it in your manifest, or ignore the medium finding |

---

## 15. FAQ

**Does my code leave my machine?**
Only through XailonCode, under your XailonCode privacy routing. `compete` sends search queries (product category and competitor names) to the web provider you choose. It never sends code.

**Does it run my code?**
No. Every review reads code. Claims about runtime behaviour are tagged `[inferred]`.

**Can the engine change my files?**
No. Reviews, PR reviews and Ask run read-only. Permission requests other than reads are rejected.

**How do I know a finding is real?**
Click the citation. The viewer shows the exact lines. `[observed]` with a resolved citation is the strongest grade. Ask the viewer "Is A3 right? check the code" for a second look.

**Can I use it in CI?**
Yes. Use `check` (no model, exit code) as a gate, and `pr --post` for review comments. See [Integrations](#11-integrations).

**How is this different from XailonCode itself?**
XailonCode is a general coding agent. xailon-review is a reviewer product built on it: deterministic facts, a fixed report format, mechanical citation checks, a decision ledger and a PR bot.