feat: support custom ADR directory via config.json paths field

docs/astro.config.mjs

@@ -253,6 +253,7 @@ export default defineConfig({
             },
             { label: "Rule API", slug: "reference/rule-api" },
             { label: "ADR Schema", slug: "reference/adr-schema" },
+            { label: "Configuration", slug: "reference/configuration" },
             { label: "Telemetry", slug: "reference/telemetry" },
             { label: "Privacy Policy", slug: "reference/privacy-policy" },
           ],

docs/public/llms-full.txt

@@ -706,7 +706,7 @@ archgate adr domain add security SEC
 archgate adr domain remove security
 ```
 
-Custom domain → prefix mappings persist in `.archgate/config.json` and are merged with the built-ins at read time. A registered custom domain behaves exactly like a built-in: `archgate adr create --domain security` auto-generates IDs like `SEC-001`, and `archgate adr list --domain security` filters to those ADRs.
+Custom domain-to-prefix mappings persist in [`.archgate/config.json`](/reference/configuration/) and are merged with the built-ins at read time. A registered custom domain behaves exactly like a built-in: `archgate adr create --domain security` auto-generates IDs like `SEC-001`, and `archgate adr list --domain security` filters to those ADRs.
 
 ### Naming rules
 
@@ -4029,6 +4029,100 @@ Archgate upgraded to 0.4.0 successfully.
 
 ---
 
+## Reference: Configuration
+
+Source: https://cli.archgate.dev/reference/configuration/
+
+The `.archgate/config.json` file stores project-level configuration that is committed to version control and shared across the team.
+
+This file is created automatically by `archgate init` (when custom domains are registered) or when you manually add configuration. It lives inside the `.archgate/` directory at your project root.
+
+## Schema
+
+```json
+{
+  "domains": { "security": "SEC", "compliance": "COMP" },
+  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" }
+}
+```
+
+### `domains`
+
+Custom domain-to-prefix mappings. See [Custom Domains](/concepts/domains/#custom-domains) for details.
+
+| Key    | Type     | Description                                                                                 |
+| ------ | -------- | ------------------------------------------------------------------------------------------- |
+| _name_ | `string` | Domain name (lowercase kebab-case, 2-32 chars) maps to an ID prefix (uppercase, 2-10 chars) |
+
+These are merged with the built-in domains (`backend`, `frontend`, `data`, `architecture`, `general`) at read time. Custom entries cannot override built-in names or prefixes.
+
+### `paths`
+
+Override default directories for ADRs and rules.
+
+| Field   | Type     | Default          | Description                               |
+| ------- | -------- | ---------------- | ----------------------------------------- |
+| `adrs`  | `string` | `.archgate/adrs` | Relative path to the ADR directory        |
+| `rules` | `string` | `.archgate/lint` | Relative path to the rules/lint directory |
+
+Both fields are optional. When omitted, the default `.archgate/adrs/` and `.archgate/lint/` directories are used.
+
+#### Path validation
+
+- Paths **must be relative** to the project root -- absolute paths (e.g., `/docs/adrs`, `C:\docs\adrs`) are rejected.
+- Paths **must not contain `..` segments** -- traversal above the project root is not allowed (e.g., `../other-repo/adrs` is rejected).
+- Paths use forward slashes (`/`) as separators, matching standard glob conventions.
+
+## Custom ADR directory
+
+By default, ADRs live in `.archgate/adrs/`. To store them in a different directory (e.g., `docs/adrs/`), add a `paths` section to `.archgate/config.json`:
+
+```json
+{ "paths": { "adrs": "docs/adrs" } }
+```
+
+After adding the configuration:
+
+1. Create the target directory (e.g., `mkdir -p docs/adrs`)
+2. Move existing ADR files and their companion `.rules.ts` files from `.archgate/adrs/` to the new directory
+3. Run `archgate check` to verify the rules still load correctly
+
+All CLI commands (`archgate adr list`, `archgate adr create`, `archgate check`, `archgate review-context`) automatically read the configured directory.
+
+:::caution
+The `.archgate/` directory must still exist -- it is the project marker used by the CLI to locate your project root. Do not delete it after configuring custom paths.
+
+### Example: monorepo documentation folder
+
+A common pattern is placing ADRs alongside other documentation:
+
+```
+my-project/
+  .archgate/
+    config.json          # { "paths": { "adrs": "docs/adrs" } }
+    lint/
+    rules.d.ts
+  docs/
+    adrs/
+      ARCH-001-api-design.md
+      ARCH-001-api-design.rules.ts
+      BE-001-database-access.md
+      BE-001-database-access.rules.ts
+    rules.d.ts           # auto-generated by archgate check
+    guides/
+    ...
+  src/
+    ...
+```
+
+## Notes
+
+- The `paths` configuration is a **team-wide setting** -- it is committed to version control and applies to all team members. There is no user-level override for ADR paths.
+- Changing the configuration requires manually editing `.archgate/config.json` after running `archgate init`.
+- The `rules.d.ts` type definitions file is automatically written to both `.archgate/` and the parent of the configured ADR directory, so companion `.rules.ts` files resolve their `/// <reference path="../rules.d.ts" />` directive correctly.
+
+---
+
 ## Reference: Privacy Policy
 
 Source: https://cli.archgate.dev/reference/privacy-policy/

docs/src/content/docs/concepts/domains.mdx

@@ -110,7 +110,7 @@ archgate adr domain add security SEC
 archgate adr domain remove security
 ```
 
-Custom domain → prefix mappings persist in `.archgate/config.json` and are merged with the built-ins at read time. A registered custom domain behaves exactly like a built-in: `archgate adr create --domain security` auto-generates IDs like `SEC-001`, and `archgate adr list --domain security` filters to those ADRs.
+Custom domain-to-prefix mappings persist in [`.archgate/config.json`](/reference/configuration/) and are merged with the built-ins at read time. A registered custom domain behaves exactly like a built-in: `archgate adr create --domain security` auto-generates IDs like `SEC-001`, and `archgate adr list --domain security` filters to those ADRs.
 
 ### Naming rules
 

docs/src/content/docs/pt-br/concepts/domains.mdx

@@ -110,7 +110,7 @@ archgate adr domain add security SEC
 archgate adr domain remove security
 ```
 
-Os mapeamentos de domínio personalizado → prefixo persistem em `.archgate/config.json` e são mesclados com os integrados no momento da leitura. Um domínio personalizado registrado se comporta exatamente como um integrado: `archgate adr create --domain security` gera IDs como `SEC-001`, e `archgate adr list --domain security` filtra esses ADRs.
+Os mapeamentos de domínio personalizado para prefixo persistem em [`.archgate/config.json`](/reference/configuration/) e são mesclados com os integrados no momento da leitura. Um domínio personalizado registrado se comporta exatamente como um integrado: `archgate adr create --domain security` gera IDs como `SEC-001`, e `archgate adr list --domain security` filtra esses ADRs.
 
 ### Regras de nomenclatura
 

docs/src/content/docs/pt-br/reference/configuration.mdx

@@ -0,0 +1,93 @@
+---
+title: Configuração
+description: Referência do arquivo de configuração .archgate/config.json. Configure diretórios personalizados para ADRs, mapeamentos de domínios e configurações do projeto.
+---
+
+O arquivo `.archgate/config.json` armazena configurações do projeto que são versionadas no controle de versão e compartilhadas com toda a equipe.
+
+Este arquivo é criado automaticamente pelo `archgate init` (quando domínios customizados são registrados) ou quando você adiciona configurações manualmente. Ele fica dentro do diretório `.archgate/` na raiz do seu projeto.
+
+## Schema
+
+```json
+{
+  "domains": { "security": "SEC", "compliance": "COMP" },
+  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" }
+}
+```
+
+### `domains`
+
+Mapeamentos personalizados de domínio para prefixo. Veja [Domínios Personalizados](/concepts/domains/#custom-domains) para detalhes.
+
+| Chave  | Tipo     | Descrição                                                                                               |
+| ------ | -------- | ------------------------------------------------------------------------------------------------------- |
+| _nome_ | `string` | Nome do domínio (kebab-case minúsculo, 2-32 chars) mapeia para um prefixo de ID (maiúsculo, 2-10 chars) |
+
+Esses são mesclados com os domínios built-in (`backend`, `frontend`, `data`, `architecture`, `general`) em tempo de leitura. Entradas personalizadas não podem sobrescrever nomes ou prefixos built-in.
+
+### `paths`
+
+Sobrescreve os diretórios padrão para ADRs e regras.
+
+| Campo   | Tipo     | Padrão           | Descrição                                        |
+| ------- | -------- | ---------------- | ------------------------------------------------ |
+| `adrs`  | `string` | `.archgate/adrs` | Caminho relativo para o diretório de ADRs        |
+| `rules` | `string` | `.archgate/lint` | Caminho relativo para o diretório de regras/lint |
+
+Ambos os campos são opcionais. Quando omitidos, os diretórios padrão `.archgate/adrs/` e `.archgate/lint/` são usados.
+
+#### Validação de caminhos
+
+- Caminhos **devem ser relativos** à raiz do projeto -- caminhos absolutos (ex: `/docs/adrs`, `C:\docs\adrs`) são rejeitados.
+- Caminhos **não devem conter segmentos `..`** -- travessia acima da raiz do projeto não é permitida (ex: `../other-repo/adrs` é rejeitado).
+- Caminhos usam barras (`/`) como separadores, seguindo as convenções padrão de glob.
+
+## Diretório personalizado de ADRs
+
+Por padrão, ADRs ficam em `.archgate/adrs/`. Para armazená-los em um diretório diferente (ex: `docs/adrs/`), adicione uma seção `paths` ao `.archgate/config.json`:
+
+```json
+{ "paths": { "adrs": "docs/adrs" } }
+```
+
+Após adicionar a configuração:
+
+1. Crie o diretório de destino (ex: `mkdir -p docs/adrs`)
+2. Mova os arquivos ADR existentes e seus arquivos `.rules.ts` complementares de `.archgate/adrs/` para o novo diretório
+3. Execute `archgate check` para verificar se as regras ainda carregam corretamente
+
+Todos os comandos do CLI (`archgate adr list`, `archgate adr create`, `archgate check`, `archgate review-context`) leem automaticamente o diretório configurado.
+
+:::caution
+O diretório `.archgate/` deve continuar existindo -- ele é o marcador de projeto usado pelo CLI para localizar a raiz do seu projeto. Não o exclua após configurar caminhos personalizados.
+:::
+
+### Exemplo: pasta de documentação em monorepo
+
+Um padrão comum é colocar ADRs junto com outra documentação:
+
+```
+my-project/
+  .archgate/
+    config.json          # { "paths": { "adrs": "docs/adrs" } }
+    lint/
+    rules.d.ts
+  docs/
+    adrs/
+      ARCH-001-api-design.md
+      ARCH-001-api-design.rules.ts
+      BE-001-database-access.md
+      BE-001-database-access.rules.ts
+    rules.d.ts           # gerado automaticamente pelo archgate check
+    guides/
+    ...
+  src/
+    ...
+```
+
+## Notas
+
+- A configuração `paths` é uma **definição de equipe** -- é versionada no controle de versão e se aplica a todos os membros da equipe. Não há override de nível de usuário para caminhos de ADR.
+- Alterar a configuração requer editar manualmente `.archgate/config.json` após executar `archgate init`.
+- O arquivo de definições de tipo `rules.d.ts` é escrito automaticamente tanto em `.archgate/` quanto no diretório pai do diretório de ADR configurado, para que os arquivos `.rules.ts` complementares resolvam corretamente sua diretiva `/// <reference path="../rules.d.ts" />`.

docs/src/content/docs/reference/configuration.mdx

@@ -0,0 +1,93 @@
+---
+title: Configuration
+description: Reference for the .archgate/config.json project configuration file. Configure custom ADR directories, domain mappings, and project-level settings.
+---
+
+The `.archgate/config.json` file stores project-level configuration that is committed to version control and shared across the team.
+
+This file is created automatically by `archgate init` (when custom domains are registered) or when you manually add configuration. It lives inside the `.archgate/` directory at your project root.
+
+## Schema
+
+```json
+{
+  "domains": { "security": "SEC", "compliance": "COMP" },
+  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" }
+}
+```
+
+### `domains`
+
+Custom domain-to-prefix mappings. See [Custom Domains](/concepts/domains/#custom-domains) for details.
+
+| Key    | Type     | Description                                                                                 |
+| ------ | -------- | ------------------------------------------------------------------------------------------- |
+| _name_ | `string` | Domain name (lowercase kebab-case, 2-32 chars) maps to an ID prefix (uppercase, 2-10 chars) |
+
+These are merged with the built-in domains (`backend`, `frontend`, `data`, `architecture`, `general`) at read time. Custom entries cannot override built-in names or prefixes.
+
+### `paths`
+
+Override default directories for ADRs and rules.
+
+| Field   | Type     | Default          | Description                               |
+| ------- | -------- | ---------------- | ----------------------------------------- |
+| `adrs`  | `string` | `.archgate/adrs` | Relative path to the ADR directory        |
+| `rules` | `string` | `.archgate/lint` | Relative path to the rules/lint directory |
+
+Both fields are optional. When omitted, the default `.archgate/adrs/` and `.archgate/lint/` directories are used.
+
+#### Path validation
+
+- Paths **must be relative** to the project root -- absolute paths (e.g., `/docs/adrs`, `C:\docs\adrs`) are rejected.
+- Paths **must not contain `..` segments** -- traversal above the project root is not allowed (e.g., `../other-repo/adrs` is rejected).
+- Paths use forward slashes (`/`) as separators, matching standard glob conventions.
+
+## Custom ADR directory
+
+By default, ADRs live in `.archgate/adrs/`. To store them in a different directory (e.g., `docs/adrs/`), add a `paths` section to `.archgate/config.json`:
+
+```json
+{ "paths": { "adrs": "docs/adrs" } }
+```
+
+After adding the configuration:
+
+1. Create the target directory (e.g., `mkdir -p docs/adrs`)
+2. Move existing ADR files and their companion `.rules.ts` files from `.archgate/adrs/` to the new directory
+3. Run `archgate check` to verify the rules still load correctly
+
+All CLI commands (`archgate adr list`, `archgate adr create`, `archgate check`, `archgate review-context`) automatically read the configured directory.
+
+:::caution
+The `.archgate/` directory must still exist -- it is the project marker used by the CLI to locate your project root. Do not delete it after configuring custom paths.
+:::
+
+### Example: monorepo documentation folder
+
+A common pattern is placing ADRs alongside other documentation:
+
+```
+my-project/
+  .archgate/
+    config.json          # { "paths": { "adrs": "docs/adrs" } }
+    lint/
+    rules.d.ts
+  docs/
+    adrs/
+      ARCH-001-api-design.md
+      ARCH-001-api-design.rules.ts
+      BE-001-database-access.md
+      BE-001-database-access.rules.ts
+    rules.d.ts           # auto-generated by archgate check
+    guides/
+    ...
+  src/
+    ...
+```
+
+## Notes
+
+- The `paths` configuration is a **team-wide setting** -- it is committed to version control and applies to all team members. There is no user-level override for ADR paths.
+- Changing the configuration requires manually editing `.archgate/config.json` after running `archgate init`.
+- The `rules.d.ts` type definitions file is automatically written to both `.archgate/` and the parent of the configured ADR directory, so companion `.rules.ts` files resolve their `/// <reference path="../rules.d.ts" />` directive correctly.

src/commands/adr/create.ts

@@ -9,10 +9,11 @@ import { createAdrFile } from "../../helpers/adr-writer";
 import { exitWith } from "../../helpers/exit";
 import { logError } from "../../helpers/log";
 import { formatJSON, isAgentContext } from "../../helpers/output";
-import { findProjectRoot, projectPaths } from "../../helpers/paths";
+import { findProjectRoot } from "../../helpers/paths";
 import {
   getAllDomainNames,
   resolveDomainPrefix,
+  resolvedProjectPaths,
 } from "../../helpers/project-config";
 
 export function registerAdrCreateCommand(adr: Command) {
@@ -37,7 +38,7 @@ export function registerAdrCreateCommand(adr: Command) {
       }
 
       try {
-        const paths = projectPaths(projectRoot);
+        const paths = resolvedProjectPaths(projectRoot);
 
         let domain: AdrDomain;
         let title: string;

src/commands/adr/list.ts

@@ -9,7 +9,8 @@ import { parseAllAdrs } from "../../engine/loader";
 import { exitWith } from "../../helpers/exit";
 import { logError } from "../../helpers/log";
 import { formatJSON, isAgentContext } from "../../helpers/output";
-import { findProjectRoot, projectPaths } from "../../helpers/paths";
+import { findProjectRoot } from "../../helpers/paths";
+import { resolvedProjectPaths } from "../../helpers/project-config";
 
 export function registerAdrListCommand(adr: Command) {
   adr
@@ -26,7 +27,7 @@ export function registerAdrListCommand(adr: Command) {
       }
 
       try {
-        const paths = projectPaths(projectRoot);
+        const paths = resolvedProjectPaths(projectRoot);
 
         if (!existsSync(paths.adrsDir)) {
           console.log("No ADRs found.");

src/commands/adr/show.ts

@@ -5,7 +5,8 @@ import type { Command } from "@commander-js/extra-typings";
 import { findAdrFileById } from "../../helpers/adr-writer";
 import { exitWith } from "../../helpers/exit";
 import { logError } from "../../helpers/log";
-import { findProjectRoot, projectPaths } from "../../helpers/paths";
+import { findProjectRoot } from "../../helpers/paths";
+import { resolvedProjectPaths } from "../../helpers/project-config";
 
 export function registerAdrShowCommand(adr: Command) {
   adr
@@ -21,7 +22,7 @@ export function registerAdrShowCommand(adr: Command) {
       }
 
       try {
-        const { adrsDir } = projectPaths(projectRoot);
+        const { adrsDir } = resolvedProjectPaths(projectRoot);
         const adr = await findAdrFileById(adrsDir, id);
 
         if (!adr) {