docs: context boundary, calibration page, runtime exception lifecycle, CLI install lifecycle

AGENTS.md

@@ -26,6 +26,9 @@
 - Use “AI authorship” and “line-level attribution,” not “AI detection.”
 - Use “coding agent” for tools such as Codex, Claude Code, Cursor, and GitHub Copilot.
 - Use “organization,” “repository,” “pull request,” and “merge request” where appropriate.
+- Use “Autter Runtime” only for the production telemetry product (the open source SDKs and ingester).
+- Use “review sandbox” for the isolated environment where the platform checks out, builds, or tests a pull request. Never call it a runtime.
+- Avoid generic “runtime” phrasing elsewhere; prefer “performance,” “execution,” or “while running” so “Runtime” stays unambiguous.
 
 ## Style preferences
 

cli/install.mdx

@@ -56,38 +56,43 @@ For fish, use `source "$HOME/.autter/env.fish"`. New terminals pick up the `PATH
 
 Interactive macOS, Linux, and WSL installs start onboarding automatically. If the installer runs without an interactive terminal, complete onboarding later with `autter onboard`.
 
-## Complete onboarding
+## What the installer changes
 
-The installer asks whether you want local-only or connected mode.
+Every install method makes the same changes, all scoped to your user account:
 
-<Frame caption="Replace this placeholder with the final onboarding terminal screenshot.">
-  <img src="/images/placeholders/cli-onboarding.svg" alt="Placeholder for the Autter CLI onboarding choices" />
-</Frame>
+| Change | Detail |
+| --- | --- |
+| Binary | `~/.autter/bin/autter` (Windows: `%USERPROFILE%\.autter\bin\autter.exe`). On macOS and Linux, a convenience symlink at `~/.local/bin/autter` when that directory exists. |
+| `PATH` | Writes `~/.autter/env` (and `~/.autter/env.fish`), then appends one line that sources it — marked `# Added by autter installer` — to the shell files that exist on your machine: `~/.bashrc`, `~/.bash_profile`, `~/.zshrc`, or `~/.config/fish/config.fish`. On Windows, adds `%USERPROFILE%\.autter\bin` to your user `PATH` (never the system `PATH`) and, when Git Bash is detected, a `PATH` export in `~/.bashrc`. |
+| Settings and state | Settings in `~/.autter/config.json`. Credentials in your operating system keyring when available, otherwise in `~/.autter/internal/credentials` with owner-only permissions. The telemetry audit log at `~/.autter/internal/telemetry.log`. |
+| Coding-agent integrations | Adds checkpoint hooks to each detected agent's own configuration (for example, Claude Code's `~/.claude/settings.json`) so edits are attributed as they happen. Refresh anytime with `autter install-hooks`. |
+| Git observation | Sets the global `trace2.eventTarget` and `trace2.eventNesting` Git configuration keys so the background service can observe when commits complete. Trace2 is Git's built-in event stream; it does not change how Git behaves. |
+| Background service | Starts the Autter background service, which turns recorded checkpoints into Git notes under `refs/notes/ai` after each commit. |
 
-<Tabs>
-  <Tab title="Local-only">
-    Choose local-only mode to keep prompts on the machine and use Git notes for attribution.
+Autter does not install Git hooks, does not wrap the `git` command, and does not edit any per-repository configuration.
 
-    You can select it again later:
-
-    ```bash
-    autter onboard --local --force
-    ```
-  </Tab>
-  <Tab title="Connected">
-    Choose connected mode to sign in and sync attribution to the Autter platform.
+## Complete onboarding
 
-    You can start the flow later:
+Interactive installs start `autter onboard` automatically; run it yourself anytime. The guided flow takes about a minute and asks two questions.
 
-    ```bash
-    autter onboard
-    ```
+<Frame caption="Replace this placeholder with the final onboarding terminal screenshot.">
+  <img src="/images/placeholders/cli-onboarding.svg" alt="Placeholder for the Autter CLI onboarding choices" />
+</Frame>
 
-    To select connected mode directly, run `autter onboard --connect`.
-
-    If onboarding cannot complete, use the [PAT fallback](/cli/connect-platform#pat-fallback).
-  </Tab>
-</Tabs>
+<Steps>
+  <Step title="Choose a storage mode">
+    - **Connected** links the machine to your Autter organization. Sign-in opens in your browser; the CLI never sees your password. Attribution is still written to local Git notes, and prompt and usage data also syncs to your organization's dashboards. If browser sign-in cannot complete, use the [PAT fallback](/cli/connect-platform#pat-fallback).
+    - **Local-only** keeps everything on the machine. No account is needed and nothing uploads. Switch anytime with `autter onboard --connect`.
+  </Step>
+  <Step title="Decide on anonymous telemetry">
+    Autter asks before sending anonymous usage analytics: a random install ID, coarse device info, and the Autter version — never code, prompts, or personal data. Every event sent is mirrored to `~/.autter/internal/telemetry.log` so you can audit it, and `autter telemetry off` disables it at any time.
+  </Step>
+  <Step title="Done — attribution is automatic">
+    The background service restarts with your choices, and authorship is recorded on every commit from here on. After your next AI-assisted commit, try `autter stats`, `autter blame <file>`, or `autter log`.
+  </Step>
+</Steps>
+
+To redo onboarding, run `autter onboard --force`. For unattended setups, script the same choices with flags: `autter onboard --local --no-telemetry` or `autter onboard --connect`.
 
 ## Verify the installation
 
@@ -130,6 +135,44 @@ Use `autter upgrade --force` to reinstall the latest release.
 
 This works for every install method, including npm: the npm package is only a bootstrapper, and `autter upgrade` (or the background service's automatic update) replaces the binary in `~/.autter/bin` directly. Running `npm update -g @autter/cli` is not required.
 
+## Uninstall
+
+Removal is the install in reverse. Autter keeps its state under `~/.autter`, so there is nothing scattered to hunt down.
+
+<Steps>
+  <Step title="Stop the background service and remove integrations">
+    ```bash
+    autter bg shutdown
+    autter uninstall-hooks
+    ```
+
+    `autter uninstall-hooks` removes the checkpoint entries Autter added to your coding agents' configuration files. If the machine was connected, run `autter logout` first to clear credentials.
+  </Step>
+  <Step title="Remove the Git tracing keys">
+    ```bash
+    git config --global --unset trace2.eventTarget
+    git config --global --unset trace2.eventNesting
+    ```
+  </Step>
+  <Step title="Delete the binary and state">
+    ```bash
+    rm -rf ~/.autter
+    rm -f ~/.local/bin/autter
+    ```
+
+    On Windows, run `Remove-Item -Recurse -Force "$HOME\.autter"`, then remove `%USERPROFILE%\.autter\bin` from your user `PATH` under **Settings → Environment variables**.
+  </Step>
+  <Step title="Drop the PATH line">
+    Delete the block marked `# Added by autter installer` from `~/.bashrc`, `~/.bash_profile`, `~/.zshrc`, or `~/.config/fish/config.fish` — whichever exist. For Git Bash on Windows, remove the same block from `~/.bashrc`.
+  </Step>
+</Steps>
+
+Attribution already recorded in your repositories is not touched: it lives in each repository's Git notes under `refs/notes/ai`. To remove it from one repository, run `git update-ref -d refs/notes/ai` there. Uninstalling also does not delete data previously uploaded in connected mode — see [Opt out of cloud storage](/cli/data-and-privacy#opt-out-of-cloud-storage).
+
+<Tip>
+  To stop syncing without uninstalling, switch the machine to local-only mode with `autter logout` followed by `autter onboard --local --force`. To turn Autter off for a single repository, see [Disable Autter for a repository](/cli/data-and-privacy#disable-autter-for-a-repository).
+</Tip>
+
 ## Next step
 
 <Card title="Connect to the platform" icon="cloud" href="/cli/connect-platform">

cli/overview.mdx

@@ -81,7 +81,7 @@ Autter does not guess whether code came from AI. Supported coding agents create
     Jump into the main reference hub for the CLI.
   </Card>
   <Card title="Performance FAQs" icon="gauge" href="/cli/performance-faqs">
-    Learn what affects CLI runtime on large repos.
+    Learn what affects CLI performance on large repos.
   </Card>
   <Card title="Add your agent" icon="plug" href="/guides/add-your-agent">
     Follow the integration path for a new coding agent.

cli/reference.mdx

@@ -19,7 +19,7 @@ If you need the full command list, open the [command reference](/cli/command-ref
     Review local-only, connected, and team storage behavior.
   </Card>
   <Card title="Performance FAQs" icon="gauge" href="/cli/performance-faqs">
-    Understand the CLI's runtime impact and scaling behavior.
+    Understand the CLI's performance impact and scaling behavior.
   </Card>
   <Card title="Troubleshooting" icon="wrench" href="/cli/troubleshooting">
     Fix missing attribution, connection problems, and service issues.

cli/windsurf.mdx

@@ -43,5 +43,5 @@ autter blame src/service.ts
 ```
 
 <Card title="Performance FAQs" icon="gauge" href="/cli/performance-faqs">
-  Check the CLI's runtime impact before rolling it out broadly.
+  Check the CLI's performance impact before rolling it out broadly.
 </Card>

configuration/overview.mdx

@@ -42,7 +42,7 @@ Use Autter platform settings to control what Autter reviews and how your team re
     Enable focused checks for the repository's languages, frameworks, and risk profile.
   </Step>
   <Step title="Expand after calibration">
-    Roll the same configuration to more repositories after the team agrees on the signal quality.
+    Roll the same configuration to more repositories after the team agrees on the signal quality. Use the acted-on rate on each repository's Health tab to judge it — see [Calibration](/features/calibration).
   </Step>
 </Steps>
 

docs.json

@@ -117,6 +117,7 @@
             "pages": [
               "features/platform-overview",
               "features/code-review",
+              "features/calibration",
               "features/codebase-scans",
               "features/wiki",
               "features/pipeline",
@@ -175,6 +176,7 @@
           {
             "group": "Reference",
             "pages": [
+              "runtime/error-lifecycle",
               "runtime/environment-variables",
               "runtime/architecture"
             ]

features/ai-chat.mdx

@@ -30,6 +30,10 @@ Use AI chat to ask about complex logic, architecture, repository patterns, or a
 
 Ask focused questions and name the relevant module or behavior. Specific questions make it easier to verify the answer against code.
 
+### What chat can read
+
+Chat is grounded in the same context as [review](/features/code-review#what-autter-reads-during-a-review): the repository index, the generated repository docs, and — on a pull request — the diff, the comment thread, and existing findings. When you mention `@autter` on a pull request, the agent additionally works from a checkout of the pull request head in an isolated review sandbox, so it can open any file in the repository to answer. Questions run read-only; asking for a fix uses the same sandbox and pushes a branch for your review.
+
 ## Suggested fixes
 
 Autter can propose concrete fixes for review findings. Before applying one:
@@ -48,7 +52,7 @@ Autter can propose concrete fixes for review findings. Before applying one:
 - write narrow, testable [review rules](/configuration/rules)
 - connect relevant issues and documentation
 - keep pull requests focused
-- use thumbs feedback where available to help calibrate results
+- give thumbs and reaction feedback on findings — it feeds [calibration](/features/calibration) directly
 - revise rules that repeatedly flag valid code
 
 {/* TODO: Add the exact chat entry points and feedback controls after the production UI is approved. */}

features/calibration.mdx

@@ -0,0 +1,73 @@
+---
+title: "Calibration"
+description: "How Autter measures whether findings earn attention and tunes every repository's review from your team's feedback."
+---
+
+An AI review is only useful if its findings get acted on. Autter treats that as a measurable number per repository, feeds reviewer feedback back into the next review, and demotes checks that cost attention without earning it. This page collects the whole loop in one place.
+
+## The signals Autter learns from
+
+Autter reads feedback the way your team already gives it — no extra process required:
+
+| Signal | What it tells Autter |
+| --- | --- |
+| Fixed before merge | The flagged lines changed between the review and the merged code |
+| Thumbs feedback | A direct rating on a finding, where available |
+| Replies | Pushback or agreement on a finding's thread |
+| 👎 reactions | A negative reaction on a finding comment |
+| Deleted comments | A maintainer removed an Autter comment |
+| Resolved without change | The thread was resolved while the flagged code stayed as it was |
+| Ignored | The pull request merged with the flagged lines untouched and no other signal |
+
+When a pull request closes, Autter records an outcome — **fixed**, **dismissed**, or **ignored** — for every finding that was actually shown to a reader. Findings on pull requests that close without merging are excluded, so abandoned work never skews the numbers.
+
+## The acted-on rate
+
+The **Review signal** section on a repository's **Health** tab shows the acted-on rate: of the findings Autter surfaced, how many were fixed before merge versus dismissed or ignored.
+
+- **Overall acted-on rate** — one headline number for the repository.
+- **Week-by-week trend** — whether the review is getting more or less useful over time.
+- **Worst-first breakdown by check** — the checks costing attention without earning it sit at the top.
+- **In your digest** — the headline number and the worst-performing check are included in the weekly digest email and Slack message.
+
+## What the feedback changes
+
+Four mechanisms turn those signals into different future reviews.
+
+### Learnings
+
+Feedback becomes repository-scoped learnings: durable conventions Autter applies to every later review of the same repository. Learnings never leak across repositories. View, accept, or reject them on the repository's **Learnings** tab, and let coding agents read or add them over [MCP](/features/mcp) with `get_learnings` and `add_learning`.
+
+### Muting
+
+Dismissing a finding — deleting the comment, a 👎 reaction, a pushback reply, or resolving the thread without changing the code — mutes that check on that file path in future reviews. The mute is stored as a learning, so it is visible and reversible on the **Learnings** tab.
+
+### Auto-demotion
+
+A check with a persistently low acted-on rate in your repository is automatically moved out of the way, in stages: first out of inline comments and into the review summary, then out of the pull request entirely. Demotion looks at the trailing 90 days of merged pull requests, so checks recover on their own when they start being useful again — and a full demotion appears on the **Learnings** tab, where rejecting it reverses the demotion.
+
+### Verification skepticism
+
+Precision history feeds the verification pass that runs before findings post. A check your team chronically dismisses needs stronger evidence to publish a finding; a check you consistently act on gets the benefit of the doubt.
+
+## Reviewer training
+
+Autter can also learn from reviews your team wrote before Autter existed. Name trusted reviewers for a repository, and Autter mines their past pull request comments, keeps the substantive ones, and distills up to twenty repository guidelines that are applied like accepted learnings. Re-running training replaces the previously trained guidelines, so the output always reflects the current trainer list. Training is opt-in per repository.
+
+## Controls
+
+- Learnings can be turned on or off for the organization and per repository.
+- Per repository, choose which signals create learnings: thumbs feedback, dismissed findings, and applied auto-fixes.
+- The trainer list for reviewer training is set per repository.
+- Every mute and demotion is a visible entry on the **Learnings** tab and can be rejected to reverse it.
+
+{/* TODO: Add exact navigation labels for the Health and Learnings tabs once the production UI is approved for documentation. */}
+
+<CardGroup cols={2}>
+  <Card title="Code review" icon="git-pull-request" href="/features/code-review">
+    See what context a review reads and how findings are produced.
+  </Card>
+  <Card title="Review rules" icon="shield-check" href="/configuration/rules">
+    Write the explicit standards that calibration then keeps honest.
+  </Card>
+</CardGroup>

features/code-review.mdx

@@ -30,18 +30,19 @@ Autter is designed to find issues that can survive a surface-level review:
 - dependency and scanner findings relevant to the diff
 - behavior that appears correct in isolation but fails in the wider codebase
 
-## How context changes the review
+## What Autter reads during a review
 
-A generic rule might flag every direct database call. A codebase-aware review can distinguish between an approved repository layer and a controller that bypasses it.
+"Codebase-aware" has a specific meaning. A review reasons over three layers of context:
 
-Autter can ground feedback in:
+1. **The diff.** Autter fetches the pull request's compare diff from your source control provider. Every review starts from the changed lines.
+2. **The repository index.** When you connect a repository, Autter indexes it: dependency and call graphs, per-file and per-symbol summaries, hotspots, and architecture and convention notes. During a review, Autter walks the index outward from the changed files — direct callers and callees, same-module neighbors, and heavily depended-on paths the change can affect — and fetches those specific files on demand through the provider API. The standard review does not clone your repository.
+3. **Connected knowledge.** Natural-language team rules, accepted [learnings](/features/calibration), linked issues, and reference documents attached to the repository, such as product or design docs and URLs. Attached documents contribute bounded summaries that are fenced off from code and findings: they inform the review, they cannot instruct it.
 
-- related files and dependencies
-- established repository patterns
-- natural-language team rules
-- prior review comments and team knowledge
-- linked issues and documentation
-- current linter and scanner results
+Deeper stages get more access. When findings need verification, a fix is generated, or build and test checks run, Autter checks out the pull request head at its exact commit into an isolated, single-use **review sandbox**. There it can search the full tree and run your build and tests. The sandbox is destroyed when the job ends.
+
+A review never reads other repositories in your organization — context is scoped to the repository under review — and never reads documents you have not connected.
+
+This context is what separates codebase-aware review from generic rules. A generic rule might flag every direct database call; because Autter sees the repository index, it can distinguish an approved repository layer from a controller that bypasses it.
 
 ## Use team rules
 
@@ -67,7 +68,7 @@ Keep rules specific and testable. See [Review rules](/configuration/rules) and [
     Push changes and review the latest Autter result alongside human feedback.
   </Step>
   <Step title="Improve noisy rules">
-    Refine a rule or pipeline check when it repeatedly flags valid code.
+    Refine a rule or pipeline check when it repeatedly flags valid code. Autter also [demotes low-precision checks automatically](/features/calibration).
   </Step>
 </Steps>