archgate · rhuanbarreto · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
@@ -28,6 +28,8 @@ jobs:
 
       - name: Setup toolchain
         uses: moonrepo/setup-toolchain@v0
+        with:
+          auto-install: true
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

@@ -33,17 +33,18 @@ 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                       |
-| `mcp`           | `commands/mcp.ts`        | Start MCP server                       |
-| `upgrade`       | `commands/upgrade.ts`    | Upgrade CLI binary via GitHub Releases |
-| `clean`         | `commands/clean.ts`      | Remove `~/.archgate/` cache            |
+| 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   |
+| `mcp`           | `commands/mcp.ts`        | Start MCP server                 |
+| `upgrade`       | `commands/upgrade.ts`    | Upgrade CLI via npm              |
+| `clean`         | `commands/clean.ts`      | Remove `~/.archgate/` cache      |
 
 ### Key Paths
 

@@ -6,6 +6,7 @@
 
 [![License: FSL-1.1-ALv2](https://img.shields.io/badge/License-FSL--1.1--ALv2-blue.svg)](LICENSE.md)
 [![Release](https://github.com/archgate/cli/actions/workflows/release.yml/badge.svg)](https://github.com/archgate/cli/actions/workflows/release.yml)
+[![Docs](https://img.shields.io/badge/docs-cli.archgate.dev-blue)](https://cli.archgate.dev)
 
 </div>
 
@@ -313,6 +314,10 @@ The Cursor plugin bundle is downloaded from [plugins.archgate.dev](https://plugi
 
 Once installed, run the `ag-onboard` skill in Cursor to initialize governance for your project.
 
+## 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.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.

@@ -15,6 +15,10 @@ The document is a Markdown file with YAML frontmatter stored in `.archgate/adrs/
 
 Both humans and AI agents consume this document. When an AI coding agent is about to write code, it reads the relevant ADRs to understand the constraints before generating anything.
 
+:::tip[Automate this with editor plugins]
+With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads the applicable ADRs automatically before every coding task -- no manual copy-pasting into prompts. [Sign up for beta access](https://plugins.archgate.dev).
+:::
+
 ### ADR as Rules
 
 The rules file is a companion `.rules.ts` file that exports automated checks via `defineRules()`. When you run `archgate check`, the CLI loads every ADR that has `rules: true` in its frontmatter, executes the companion rules file against your codebase, and reports any violations with file paths and line numbers.

@@ -160,3 +160,7 @@ Rules execute with the following guarantees:
 - **Sequential within an ADR** -- Rules belonging to the same ADR run one after another, so earlier rules can establish context for later ones.
 - **Scoped files are pre-resolved** -- The `ctx.scopedFiles` array is populated before your `check` function is called, based on the ADR's `files` globs.
 - **Changed files for staged mode** -- When running `archgate check --staged`, `ctx.changedFiles` contains only the files staged in git, letting rules skip unchanged files for faster feedback.
+
+:::tip[Run checks automatically with editor plugins]
+The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) run `archgate check` automatically after every code change. The agent reads the applicable ADRs, writes compliant code, and validates -- no manual check commands needed. [Sign up for beta access](https://plugins.archgate.dev).
+:::
@@ -267,3 +267,7 @@ To adapt for projects that colocate tests next to source files, change the path
 const testPath = rel.replace(/\.ts$/, ".test.ts");
 // src/helpers/log.ts -> src/helpers/log.test.ts
 ```
+
+:::tip[Let AI agents write rules for you]
+The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a Quality Manager skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev).
+:::
@@ -108,3 +108,11 @@ export PATH="$HOME/.proto/tools/node/globals/bin:$PATH"
 ```
 
 Restart your shell, then run `npm install -g archgate` again. The `archgate` command should now be available globally.
+
+## Next steps
+
+Once installed, run `archgate init` in your project to set up governance. See the [Quick Start](/getting-started/quick-start/) guide for a walkthrough.
+
+:::tip[Editor plugins (beta)]
+Want your AI agent to read ADRs before coding and validate after? The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) add a full governance workflow on top of the CLI. [Sign up for beta access](https://plugins.archgate.dev).
+:::
@@ -51,7 +51,7 @@ files: ["src/**/*.ts"]
 
 - **id** — Unique identifier. Convention is `ARCH-NNN` but any string works.
 - **title** — Human-readable name for the decision.
-- **domain** — Groups related ADRs together (e.g., `architecture`, `security`, `testing`).
+- **domain** — Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`).
 - **rules** — Set to `true` if this ADR has a companion `.rules.ts` file with automated checks.
 - **files** — Optional glob patterns that scope which files the rules apply to.
 
@@ -116,6 +116,25 @@ archgate check --staged
 
 Now that you have a working setup, dive deeper:
 
+**Understand the concepts:**
+
+- [ADRs](/concepts/adrs/) — What Architecture Decision Records are and how Archgate uses them.
+- [Rules](/concepts/rules/) — How companion `.rules.ts` files turn decisions into automated checks.
+- [Domains](/concepts/domains/) — How domains group related ADRs and scope file matching.
+
+**Write your own:**
+
 - [Writing ADRs](/guides/writing-adrs/) — Learn the full ADR format and best practices for writing effective decisions.
 - [Writing Rules](/guides/writing-rules/) — Explore the rule API, advanced patterns, and how to test your rules.
+- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, and more.
+
+**Integrate into your workflow:**
+
 - [CI Integration](/guides/ci-integration/) — Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline.
+- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Run checks locally before every commit.
+- [Claude Code Plugin](/guides/claude-code-plugin/) — Give AI agents a full governance workflow with role-based skills.
+- [Cursor Integration](/guides/cursor-integration/) — Use Archgate with Cursor IDE for AI-assisted development.
+
+:::tip[Editor plugins (beta)]
+Want AI agents that automatically read your ADRs before coding? Sign up for the editor plugin beta at [plugins.archgate.dev](https://plugins.archgate.dev), then run `archgate login` and `archgate init --install-plugin`.
+:::
@@ -54,13 +54,23 @@ The JSON output includes:
   "errors": 1,
   "infos": 0,
   "ruleErrors": 0,
+  "truncated": false,
   "results": [
     {
-      "ruleId": "no-unapproved-deps",
       "adrId": "ARCH-006",
-      "message": "Unapproved production dependency: \"chalk\"",
-      "file": "package.json",
-      "severity": "error"
+      "ruleId": "no-unapproved-deps",
+      "description": "Production dependencies must be on the approved list",
+      "status": "fail",
+      "totalViolations": 1,
+      "shownViolations": 1,
+      "violations": [
+        {
+          "message": "Unapproved production dependency: \"chalk\"",
+          "file": "package.json",
+          "severity": "error"
+        }
+      ],
+      "durationMs": 18
     }
   ],
   "durationMs": 142
@@ -149,11 +159,26 @@ adr-compliance:
     - archgate check
 ```
 
+## Bun-based CI
+
+If your CI already uses Bun, install Archgate with `bun` instead of `npm`:
+
+```yaml
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install -g archgate
+      - run: archgate check --ci
+```
+
 ## Other CI systems
 
 Archgate works with any CI system that can run shell commands. The pattern is always the same:
 
-1. Install: `npm install -g archgate`
+1. Install: `npm install -g archgate` (or `bun install -g archgate`)
 2. Run: `archgate check`
 3. Check the exit code (0 = pass, 1 = violations, 2 = error)
 
@@ -177,3 +202,7 @@ Use `--verbose` to see passing rules and timing information alongside failures.
 ```yaml
 - run: archgate check --verbose
 ```
+
+:::tip[Add AI governance to your workflow]
+CI catches violations at merge time. Editor plugins catch them at coding time. With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads ADRs before writing code and validates compliance before you even commit. [Sign up for beta access](https://plugins.archgate.dev).
+:::
@@ -21,7 +21,40 @@ The plugin adds role-based skills to Claude Code. Each skill encapsulates a spec
 
 ## Installation
 
-Install the plugin from the `archgate/claude-code-plugin` GitHub repository. Follow the instructions in the repository README to add it to your Claude Code configuration.
+:::note[Beta access required]
+The Claude Code plugin is currently in beta. [Sign up at plugins.archgate.dev](https://plugins.archgate.dev) to get access before following the steps below.
+:::
+
+### 1. Log in with GitHub
+
+Authenticate with your GitHub account to obtain a plugin token:
+
+```bash
+archgate login
+```
+
+This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`.
+
+### 2. Initialize your project with the plugin
+
+Run `archgate init` in your project. If you are already logged in, the plugin is installed automatically:
+
+```bash
+archgate init
+```
+
+To explicitly request plugin installation:
+
+```bash
+archgate init --install-plugin
+```
+
+If the `claude` CLI is on your PATH, the plugin is installed automatically via:
+
+1. `claude plugin marketplace add` (registers the Archgate marketplace)
+2. `claude plugin install archgate@archgate` (installs the plugin)
+
+If the `claude` CLI is not found, the command prints the manual commands for you to run.
 
 ## Initial setup with onboard