fix: resolve documentation inconsistencies and minor code issues

.archgate/adrs/ARCH-002-error-handling.md

@@ -54,6 +54,7 @@ Use three exit codes with clear semantics:
 - Don't catch and swallow unexpected errors — let them propagate
 - Don't show stack traces for user errors
 - Don't use `console.error()` directly — use `logError()` for consistent formatting
+- Don't use `console.log()` or `console.warn()` directly in helper or engine files — use `logInfo()` or `logWarn()` (command files are the I/O layer and may use console directly)
 - Don't exit with code 0 when an operation fails
 - Don't use exit codes other than 0, 1, or 2
 
@@ -122,7 +123,7 @@ try {
 ### Risks
 
 - **Swallowed errors in async code** — Async functions that catch errors without re-throwing can silently fail. Unhandled promise rejections in Bun terminate the process with a non-zero exit code, which provides a safety net, but the error message may be unclear.
-  - **Mitigation:** The `logError()` convention makes explicit error handling visible in code review. The `use-log-error` automated rule flags direct `console.error()` usage, nudging developers toward the standard pattern.
+  - **Mitigation:** The log helper convention makes explicit error handling visible in code review. The `use-log-error` rule flags direct `console.error()` usage, and the `use-log-helpers` rule flags direct `console.log()`/`console.warn()` in helper and engine files, nudging developers toward the standard pattern.
 - **Exit code 2 masking real issues** — If an unexpected error occurs in a rule file, the CLI exits with code 2 ("internal error") rather than code 1 ("violations"). This could confuse CI systems that only check for non-zero exit.
   - **Mitigation:** The check engine wraps rule execution with timeout and error boundaries, reporting rule errors separately from violations. The `--verbose` flag shows which rules errored.
 
@@ -131,6 +132,7 @@ try {
 ### Automated Enforcement
 
 - **Archgate rule** `ARCH-002/use-log-error`: Scans all source files (excluding `helpers/log.ts` and test files) for `console.error()` usage and flags violations. Severity: `error`.
+- **Archgate rule** `ARCH-002/use-log-helpers`: Scans helper and engine files for direct `console.log()`, `console.warn()`, or `console.info()` usage. Excludes `helpers/log.ts` (canonical implementation), `engine/reporter.ts` (check output system), `helpers/login-flow.ts` (interactive device flow UI), and test files. Command files are exempt since they are the I/O layer. Severity: `error`.
 - **Archgate rule** `ARCH-002/exit-code-convention`: Scans all source files for `process.exit()` calls and verifies the exit code is 0, 1, or 2. Severity: `error`.
 
 ### Manual Enforcement

.archgate/adrs/ARCH-002-error-handling.rules.ts

@@ -24,6 +24,34 @@ export default defineRules({
       }
     },
   },
+  "use-log-helpers": {
+    description:
+      "Use log helpers instead of console.log/warn/info in helper and engine files",
+    async check(ctx) {
+      const files = ctx.scopedFiles.filter(
+        (f) =>
+          (f.includes("helpers/") || f.includes("engine/")) &&
+          !f.endsWith("helpers/log.ts") &&
+          !f.endsWith("engine/reporter.ts") &&
+          !f.endsWith("helpers/login-flow.ts") &&
+          !f.includes("tests/")
+      );
+      const matches = await Promise.all(
+        files.map((file) => ctx.grep(file, /console\.(log|warn|info)\s*\(/))
+      );
+      for (const fileMatches of matches) {
+        for (const m of fileMatches) {
+          ctx.report.violation({
+            message:
+              "Use logInfo/logWarn/logDebug from helpers/log.ts instead of direct console output",
+            file: m.file,
+            line: m.line,
+            fix: "Import { logInfo, logWarn } from '../helpers/log' and use logInfo() or logWarn()",
+          });
+        }
+      }
+    },
+  },
   "exit-code-convention": {
     description: "Process.exit should use codes 0, 1, or 2 only",
     async check(ctx) {

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs) — combining human-readable docs with machine-checkable rules. The CLI dogfoods itself via ADRs in `.archgate/adrs/`. AI features are delivered as a Claude Code plugin (`archgate/claude-code-plugin`), not via direct API calls.
+Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs) — combining human-readable docs with machine-checkable rules. The CLI dogfoods itself via ADRs in `.archgate/adrs/`. AI features are delivered as a Claude Code plugin (`../plugins/claude-code`), not via direct API calls.
 
 ## Technology Stack
 
@@ -19,7 +19,7 @@ bun run format                # oxfmt --write
 bun run format:check          # oxfmt --check
 bun test                      # all tests
 bun run validate              # MANDATORY: lint + typecheck + format + test + ADR check + build check
-bun run build                 # binaries → dist/ (darwin-arm64, linux-x64, win32-x64)
+bun run build:check            # verify build compiles (CI builds binaries via release workflow)
 bun run commit                # conventional commit wizard
 ```
 
@@ -33,19 +33,27 @@ bun run commit                # conventional commit wizard
 
 Entry point: `src/cli.ts` (shebang `#!/usr/bin/env bun`). Commands registered via `register*Command(program)`.
 
-| Command           | File                                | Description                                  |
-| ----------------- | ----------------------------------- | -------------------------------------------- |
-| `init`            | `commands/init.ts`                  | Initialize `.archgate/` skeleton             |
-| `check`           | `commands/check.ts`                 | Run ADR compliance checks                    |
-| `adr create`      | `commands/adr/create.ts`            | Create ADR interactively                     |
-| `adr list`        | `commands/adr/list.ts`              | List ADRs (`--json`, `--domain`)             |
-| `adr show <id>`   | `commands/adr/show.ts`              | Show ADR by ID                               |
-| `adr update`      | `commands/adr/update.ts`            | Update ADR by ID                             |
-| `login`           | `commands/login.ts`                 | GitHub auth for editor plugins               |
-| `review-context`  | `commands/review-context.ts`        | Pre-compute review context for changed files |
-| `session-context` | `commands/session-context/index.ts` | Read AI editor session transcripts           |
-| `upgrade`         | `commands/upgrade.ts`               | Upgrade CLI via npm                          |
-| `clean`           | `commands/clean.ts`                 | Remove `~/.archgate/` cache                  |
+| Command                       | File                                      | Description                                                     |
+| ----------------------------- | ----------------------------------------- | --------------------------------------------------------------- |
+| `init`                        | `commands/init.ts`                        | Initialize Archgate governance in the current project           |
+| `check`                       | `commands/check.ts`                       | Run ADR compliance checks                                       |
+| `adr create`                  | `commands/adr/create.ts`                  | Create a new ADR                                                |
+| `adr list`                    | `commands/adr/list.ts`                    | List all ADRs (`--json`, `--domain`)                            |
+| `adr show <id>`               | `commands/adr/show.ts`                    | Show a specific ADR by ID                                       |
+| `adr update`                  | `commands/adr/update.ts`                  | Update an existing ADR by ID                                    |
+| `login`                       | `commands/login.ts`                       | Authenticate with GitHub to access archgate plugins             |
+| `login status`                | `commands/login.ts`                       | Show current authentication status                              |
+| `login logout`                | `commands/login.ts`                       | Remove stored credentials                                       |
+| `login refresh`               | `commands/login.ts`                       | Re-authenticate and claim a new token                           |
+| `review-context`              | `commands/review-context.ts`              | Pre-compute review context with ADR briefings for changed files |
+| `session-context`             | `commands/session-context/index.ts`       | Read AI editor session transcripts                              |
+| `session-context claude-code` | `commands/session-context/claude-code.ts` | Read Claude Code session transcript for the project             |
+| `session-context cursor`      | `commands/session-context/cursor.ts`      | Read Cursor agent session transcript for the project            |
+| `plugin`                      | `commands/plugin/index.ts`                | Manage archgate editor plugins                                  |
+| `plugin install`              | `commands/plugin/install.ts`              | Install the archgate plugin for the specified editor            |
+| `plugin url`                  | `commands/plugin/url.ts`                  | Print the authenticated plugin repository URL                   |
+| `upgrade`                     | `commands/upgrade.ts`                     | Upgrade Archgate to the latest version                          |
+| `clean`                       | `commands/clean.ts`                       | Clean the CLI temp files                                        |
 
 ### Key Paths
 
@@ -69,17 +77,19 @@ Zod schemas are the single source of truth. Types derived via `z.infer<>` — ne
 
 ## Toolchain (`.prototools`)
 
-Bun 1.3.8, Moon 1.39.4, Node LTS, npm 11.6.0. Minimum user-facing Bun: `>=1.2.21` (enforced in `src/cli.ts`).
+Bun 1.3.9, Node LTS, npm 11.11.0. Minimum user-facing Bun: `>=1.2.21` (enforced in `src/cli.ts`).
 
 ## Self-Governance ADRs (`.archgate/adrs/`)
 
 - `ARCH-001` — Command structure (register pattern, no business logic)
-- `ARCH-002` — Error handling (exit codes, logError)
+- `ARCH-002` — Error handling (exit codes, log helpers)
 - `ARCH-003` — Output formatting (styleText, --json, no emoji)
 - `ARCH-004` — No barrel files (direct imports only)
 - `ARCH-005` — Testing standards (Bun test, fixtures, 80% coverage)
 - `ARCH-006` — Dependency policy (minimal deps, Bun built-ins)
 - `ARCH-007` — Cross-platform subprocess execution (Bun.spawn, no Bun.$)
+- `ARCH-008` — Typed command options (use addOption for choices/argParser)
+- `ARCH-009` — Centralized platform detection (use helpers/platform)
 - `GEN-001` — Documentation site (Astro Starlight)
 - `GEN-002` — Documentation internationalization (en + pt-br parity)
 

README.md

@@ -110,7 +110,6 @@ See the [writing rules guide](https://cli.archgate.dev/guides/writing-rules/) fo
 | `archgate adr show <id>` | Print a specific ADR                                       |
 | `archgate adr update`    | Update an ADR's frontmatter                                |
 | `archgate login`         | Authenticate with GitHub for editor plugins                |
-| `archgate mcp`           | Start the MCP server for AI agent integration              |
 | `archgate upgrade`       | Upgrade to the latest release                              |
 | `archgate clean`         | Remove the CLI cache (`~/.archgate/`)                      |
 
@@ -135,7 +134,7 @@ Add `archgate check` to your CI pipeline or pre-commit hooks to block merges tha
 
 ## Documentation
 
-Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI and MCP reference.
+Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference.
 
 ## Contributing
 

docs/public/llms-full.txt

@@ -3291,6 +3291,81 @@ archgate adr update \
 
 ---
 
+## archgate review-context
+
+Pre-compute review context with ADR briefings for changed files. Designed for CI and editor plugin integrations that need a summary of which ADRs apply to the files being changed.
+
+```bash
+archgate review-context [options]
+```
+
+### Options
+
+| Option              | Description                          |
+| ------------------- | ------------------------------------ |
+| `--staged`          | Only include git-staged files        |
+| `--run-checks`      | Include ADR compliance check results |
+| `--domain <domain>` | Filter to a single domain            |
+
+### Example
+
+```bash
+archgate review-context --staged
+```
+
+---
+
+## archgate session-context
+
+Read AI editor session transcripts for the project. Useful for auditing what an AI agent did during a coding session.
+
+```bash
+archgate session-context <subcommand> [options]
+```
+
+### Subcommands
+
+#### archgate session-context claude-code
+
+Read the Claude Code session transcript for the project.
+
+```bash
+archgate session-context claude-code [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+
+#### archgate session-context cursor
+
+Read the Cursor agent session transcript for the project.
+
+```bash
+archgate session-context cursor [options]
+```
+
+| Option              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200) |
+| `--session-id <id>` | Specific session UUID to read            |
+
+### Examples
+
+Read the latest Claude Code session:
+
+```bash
+archgate session-context claude-code
+```
+
+Read a specific Cursor session:
+
+```bash
+archgate session-context cursor --session-id abc123
+```
+
+---
+
 ## archgate upgrade
 
 Upgrade Archgate to the latest version via npm.

docs/src/content/docs/pt-br/reference/cli-commands.mdx

@@ -514,6 +514,81 @@ archgate adr update \
 
 ---
 
+## archgate review-context
+
+Pré-computa o contexto de revisão com briefings de ADRs para arquivos alterados. Projetado para integrações de CI e plugins de editor que precisam de um resumo de quais ADRs se aplicam aos arquivos sendo alterados.
+
+```bash
+archgate review-context [options]
+```
+
+### Opções
+
+| Opção               | Descrição                                |
+| ------------------- | ---------------------------------------- |
+| `--staged`          | Incluir apenas arquivos no git stage     |
+| `--run-checks`      | Incluir resultados de verificação de ADR |
+| `--domain <domain>` | Filtrar por um único domínio             |
+
+### Exemplo
+
+```bash
+archgate review-context --staged
+```
+
+---
+
+## archgate session-context
+
+Lê transcrições de sessão de editores de IA para o projeto. Útil para auditar o que um agente de IA fez durante uma sessão de codificação.
+
+```bash
+archgate session-context <subcomando> [options]
+```
+
+### Subcomandos
+
+#### archgate session-context claude-code
+
+Lê a transcrição de sessão do Claude Code para o projeto.
+
+```bash
+archgate session-context claude-code [options]
+```
+
+| Opção               | Descrição                                   |
+| ------------------- | ------------------------------------------- |
+| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
+
+#### archgate session-context cursor
+
+Lê a transcrição de sessão do agente Cursor para o projeto.
+
+```bash
+archgate session-context cursor [options]
+```
+
+| Opção               | Descrição                                   |
+| ------------------- | ------------------------------------------- |
+| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) |
+| `--session-id <id>` | UUID específico da sessão a ser lida        |
+
+### Exemplos
+
+Ler a última sessão do Claude Code:
+
+```bash
+archgate session-context claude-code
+```
+
+Ler uma sessão específica do Cursor:
+
+```bash
+archgate session-context cursor --session-id abc123
+```
+
+---
+
 ## archgate upgrade
 
 Atualiza o Archgate para a versão mais recente via npm.