docs: fix small inconsistencies in the documentation (#12)

Author: julio-rocketchat

.env.example

@@ -28,13 +28,13 @@ GITHUB_WEBHOOK_SECRET=
 # Set to true to enable verbose debug logging (git commands, file lists, API calls).
 # DEBUG_MODE=true
 
-# Required when any repo in config/repos.json has claude.enabled: true.
+# Required when any repo in config/layne.json has claude.enabled: true.
 # ANTHROPIC_API_KEY=
 
 # ── Notifications ─────────────────────────────────────────────────────────────
 
 # Global Rocket.Chat incoming webhook URL.
-# Reference this in config/repos.json as "$ROCKETCHAT_WEBHOOK_URL".
+# Reference this in config/layne.json as "$ROCKETCHAT_WEBHOOK_URL".
 # ROCKETCHAT_WEBHOOK_URL=
 
 # Add extra per-repo webhook variables here as needed, for example:

CLAUDE.md

@@ -85,7 +85,7 @@ Two separate Node.js processes:
 **Scanners (`src/adapters/`):**
 - `semgrep.js` — runs `semgrep scan --config auto --json`; exit code 1 = findings found (not an error); maps ERROR→high, WARNING→medium, INFO→low
 - `trufflehog.js` — runs `trufflehog filesystem --json --no-update`; exit code 183 = secrets found (not an error); batched at 200 files to stay under ARG_MAX; all findings are severity `high`
-- `claude.js` — calls the Anthropic API to detect malicious intent; **disabled by default**, opt in per repo; skips binary files; caps files at 50 KB; batches at 100 KB per API call; errors are caught and logged without failing the scan. Supports two modes (configured per-repo in `repos.json`):
+- `claude.js` — calls the Anthropic API to detect malicious intent; **disabled by default**, opt in per repo; skips binary files; caps files at 50 KB; batches at 100 KB per API call; errors are caught and logged without failing the scan. Supports two modes (configured per-repo in `config/layne.json`):
   - **Prompt mode** (default): single `messages.create` call with a system prompt; use `claude.prompt` to override
   - **Skill mode**: uses the Anthropic [API Skills beta](https://platform.claude.com/docs/en/build-with-claude/skills-guide) — adds a `code_execution` tool + an uploaded skill to each batch call, enabling runtime decoding, registry lookups, and richer static analysis; set `claude.skill: { id, version }` to enable; handles `pause_turn` continuations automatically (up to 10 turns per batch)
 

docs/configuration.md

@@ -107,7 +107,9 @@ Uses the [Anthropic API Skills beta](https://platform.claude.com/docs/en/build-w
 | `id` | string | — | Skill ID from the Anthropic Skills API (format: `skill_01...`) |
 | `version` | string | `"latest"` | Skill version to use. Pin to a timestamp for reproducible behaviour |
 
-> **Beta — expect breaking changes.** API Skills are in active development. The beta headers (`skills-2025-10-02`, `code-execution-2025-08-25`) may be superseded by Anthropic; when that happens, Layne will need to be updated to use the new headers before skill mode works again. Skill IDs (`skill_01...`) are opaque, tied to your Anthropic account, and are not portable — if Anthropic changes the Skills API in a way that invalidates existing uploads, you will need to re-upload your skill and update the `id` in `repos.json`. Skills are not ZDR-eligible. Use `claude-sonnet-4-6` or above — smaller models may not make effective use of code execution.
+> **Beta — expect breaking changes.** API Skills are in active development. The beta headers (`skills-2025-10-02`, `code-execution-2025-08-25`) may be superseded by Anthropic; when that happens, Layne will need to be updated to use the new headers before skill mode works again. Skill IDs (`skill_01...`) are opaque, tied to your Anthropic account, and are not portable — if Anthropic changes the Skills API in a way that invalidates existing uploads, you will need to re-upload your skill and update the `id` in `config/layne.json`.
+>
+> **Skills are not ZDR-eligible.** ZDR (Zero Data Retention) is an Anthropic compliance feature that guarantees prompts and outputs are not retained after the API call. Skills require data retention to function, so they cannot be used with ZDR-enabled Anthropic organizations. Use `claude-sonnet-4-6` or above — smaller models may not make effective use of code execution.
 
 **Uploading a skill:** Skills are managed outside of Layne. To upload one:
 ```python
@@ -483,7 +485,7 @@ Sends a POST request to a Rocket.Chat incoming webhook URL.
 | `webhookUrl` | string | yes | Webhook URL, or an env var reference like `"$ROCKETCHAT_WEBHOOK_URL"` |
 | `template` | string | no | Custom message template (see below). Omit for the default format |
 
-**`webhookUrl` — keeping secrets out of `repos.json`:**
+**`webhookUrl` — keeping secrets out of `config/layne.json`:**
 
 If the value starts with `$`, Layne treats the rest as an environment variable name and reads it at runtime. This way your webhook URL never needs to be committed to the repository.
 
@@ -540,7 +542,7 @@ Sends a POST request to a Slack incoming webhook URL.
 
 Create a Slack app, enable Incoming Webhooks, and add a webhook for your channel. Copy the resulting `https://hooks.slack.com/services/...` URL.
 
-**`webhookUrl` — keeping secrets out of `repos.json`:**
+**`webhookUrl` — keeping secrets out of `config/layne.json`:**
 
 Same `$ENV_VAR` resolution as Rocket.Chat — if the value starts with `$`, Layne reads it from the environment at runtime.
 

docs/extending.md

@@ -41,7 +41,7 @@ function toFinding(result, workspacePath) {
   return {
     file,                            // repo-root-relative path  (required)
     line:     result.line ?? 1,      // line number              (required)
-    severity: 'high',                // 'high' | 'medium' | 'low'
+    severity: 'high',                // 'critical' | 'high' | 'medium' | 'low' | 'info'
     message:  result.message,        // annotation body text
     ruleId:   `mytool/${result.id}`, // stable identifier for the rule
     tool:     'mytool',              // used in the check run summary
@@ -67,7 +67,7 @@ function exec(cmd, args, options = {}) {
 |---|---|---|
 | `file` | `string` | Path relative to the repo root (strip `workspacePath + '/'`) |
 | `line` | `number` | Line number for the annotation (use `1` if unavailable) |
-| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | Controls annotation styling in the GitHub UI |
+| `severity` | `'critical' \| 'high' \| 'medium' \| 'low' \| 'info'` | Controls annotation styling and whether the check fails |
 | `message` | `string` | Body text of the inline annotation |
 | `ruleId` | `string` | Stable identifier used to deduplicate or suppress findings |
 | `tool` | `string` | Name shown in the check run summary |
@@ -110,56 +110,77 @@ Pin the version so builds are reproducible. Pass `--build-arg MYTOOL_VERSION=x.y
 
 ---
 
-## Adding a New Notification Provider
+## How Findings Become GitHub Annotations
 
-Notifications are **modular**: each provider is an independent file in `src/notifiers/`. Adding a new provider (e.g. PagerDuty) requires three steps and no changes to core scan logic.
+Adapters return findings — they don't call the reporter directly. Understanding this flow helps when debugging or adding new scanners:
 
-### 1. Write the notifier
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Scanner A  │     │  Scanner B  │     │  Scanner C  │     │    ...      │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │                   │
+       │ findings[]        │ findings[]        │ findings[]        │
+       └───────────────────┴───────────────────┴───────────────────┘
+                                   │
+                                   ▼
+                            ┌─────────────┐
+                            │  dispatcher │  (src/dispatcher.js)
+                            └──────┬──────┘
+                                   │
+                                   │ merged findings[]
+                                   ▼
+                            ┌─────────────┐
+                            │   reporter  │  (src/reporter.js)
+                            └──────┬──────┘
+                                   │
+                                   │ { annotations, conclusion, summary }
+                                   ▼
+                            ┌─────────────┐
+                            │  GitHub API │  (Check Runs)
+                            └─────────────┘
+```
 
-Create `src/notifiers/pagerduty.js` exporting a `notify` function. The function must **never throw** — catch all errors internally so a notification failure never affects the scan result.
+**What the dispatcher does:**
 
-```js
-// src/notifiers/pagerduty.js
+1. Runs all scanners in parallel via `Promise.all`
+2. Merges all findings into a single array
+3. Returns the merged array to the worker
 
-export async function notify({ findings, owner, repo, prNumber, toolConfig }) {
-  const url = toolConfig.webhookUrl;
-  if (!url) return;
+**What the reporter does:**
 
-  try {
-    const res = await fetch(url, {
-      method:  'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body:    JSON.stringify({
-        summary: `${findings.length} finding(s) in ${owner}/${repo} PR #${prNumber}`,
-      }),
-    });
-    if (!res.ok) {
-      console.error(`[pagerduty] notification failed: HTTP ${res.status}`);
-    }
-  } catch (err) {
-    console.error(`[pagerduty] notification failed: ${err.message}`);
-  }
-}
-```
+The reporter (`src/reporter.js`) receives the merged findings array and produces GitHub Check Run output:
 
-### 2. Register the notifier in the orchestrator
+### Severity mapping
 
-Open `src/notifiers/index.js` and add two lines:
+GitHub Check Runs support three annotation levels: `failure`, `warning`, and `notice`.
 
-```js
-import { notify as notifyRocketchat } from './rocketchat.js';
-import { notify as notifySlack }      from './slack.js';
-import { notify as notifyPagerduty }  from './pagerduty.js';    // add this
-
-const NOTIFIERS = {
-  rocketchat: notifyRocketchat,
-  slack:      notifySlack,
-  pagerduty:  notifyPagerduty,                                  // add this
-};
-```
+| Finding severity | GitHub level | Merge blocked? |
+|---|---|---|
+| `critical` | `failure` | Yes — branch protection will block merge |
+| `high` | `failure` | Yes — branch protection will block merge |
+| `medium` | `warning` | No — visible in PR files tab, yellow marker |
+| `low` | `notice` | No — informational, minimal visibility |
+| `info` | `notice` | No — informational |
+
+### Check Run conclusion
+
+The overall Check Run conclusion determines whether GitHub shows a green check or red ✗:
+
+| Condition | Conclusion |
+|---|---|
+| One or more `critical` / `high` findings | `failure` |
+| No blocking findings | `success` |
+
+When branch protection requires the Layne check, `failure` blocks the PR from merging.
 
-The notifier key (`pagerduty`) is what operators use in `config/layne.json` under `notifications`.
+### Annotation summary
+
+The reporter generates a human-readable summary line shown in the Check Run header:
+
+```
+Found 3 issue(s): 0 critical, 1 high, 1 medium, 1 low.
+```
 
-### 3. Write tests
+### Annotation chunking
 
-Create `src/__tests__/notifiers/pagerduty.test.js` following the same pattern as the Rocket.Chat or Slack test files. Use `vi.stubGlobal('fetch', vi.fn())` to mock HTTP calls.
+GitHub's API limits Check Runs to 50 annotations per request. The reporter batches automatically — adapters don't need to worry about this limit. The worker posts chunked requests to GitHub, with the final request setting `status: completed`.

docs/local-development.md

@@ -93,7 +93,7 @@ After installation, look at the URL of the page you land on:
 https://github.com/settings/installations/NNNNNNNN
 ```
 
-Note that number — it is your **installation ID**. You will need it to update the fixture files later.
+**Installation ID:** The number in the URL (`NNNNNNNN`) is your installation ID. You will need it to update the fixture files later.
 
 ---
 

docs/reference.md

@@ -24,22 +24,15 @@ All scanners produce findings in a common format:
 ```js
 {
   file:     'src/app.js',      // repo-root-relative path
+  severity: 'high',            // 'critical' | 'high' | 'medium' | 'low' | 'info'
   line:     42,                // line number
-  severity: 'high',            // 'critical' | 'high' | 'medium' | 'low'
   message:  'SQL injection',   // annotation body text
   ruleId:   'semgrep/rule-id', // stable rule identifier
   tool:     'semgrep',         // scanner name
 }
 ```
 
-## Severity → GitHub annotation level
-
-| Severity | GitHub level | Effect |
-|---|---|---|
-| `critical` | `failure` | Blocks merge |
-| `high` | `failure` | Blocks merge |
-| `medium` | `warning` | Visible warning |
-| `low` | `notice` | Informational |
+For how findings are converted to GitHub annotations and how severities affect PR status, see [Extending Layne — How Findings Become GitHub Annotations](extending.md#how-findings-become-github-annotations).
 
 ## Scan timeout
 

docs/security-architecture.md

@@ -41,7 +41,7 @@ Used only when a repo has `claude.enabled: true`. The key is passed directly to
 
 ### Notification webhook URLs (`webhookUrl`)
 
-Rocket.Chat webhook URLs can be stored as environment variable references (e.g. `"$ROCKETCHAT_WEBHOOK_URL"`) in `repos.json` rather than as plaintext values. Layne resolves them at runtime from `process.env`. This keeps secrets out of the repository.
+Rocket.Chat webhook URLs can be stored as environment variable references (e.g. `"$ROCKETCHAT_WEBHOOK_URL"`) in `config/layne.json` rather than as plaintext values. Layne resolves them at runtime from `process.env`. This keeps secrets out of the repository.
 
 ---
 

src/adapters/claude.js

@@ -61,7 +61,7 @@ const REPORT_FINDINGS_TOOL = {
 export async function runClaude({ workspacePath, changedFiles, toolConfig = DEFAULT_CONFIG.claude }) {
   if (!changedFiles || changedFiles.length === 0) return [];
   if (!toolConfig.enabled) {
-    console.log('[claude] skipping — not enabled for this repo (set "claude": {"enabled": true} in config/repos.json)');
+    console.log('[claude] skipping — not enabled for this repo (set "claude": {"enabled": true} in config/layne.json)');
     return [];
   }