docit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39589c6800b65d7a0ad55701378b345f18277735df3511cce965bc889035e74f
-  data.tar.gz: 91c392bded5bbd0897222859feab4d68e8c0d3064d4054e6b75509a325ced2d0
+  metadata.gz: ad97aecf5e4f97baffb4f944fa8f8a62b449846714e1c2dd2e8bbdc9a167ee22
+  data.tar.gz: f638754ff073096c6904db2e5d394413e2f1c579966b97af831cfe93ae91af51
 SHA512:
-  metadata.gz: 1ea253c903e6a90eb3754ed9f4a586adcc7339c831d9623401cc4bb53256359c81e069bba4067a12379da350fbf354b50bfd14420ae0aa75c3841c74942ae5f2
-  data.tar.gz: 8441b41ae22a25f1bd29514fbdcb425b4bbd56b591da6904df0c9ad070a7ac830b1eb9338783a8c751d8f648db4826d69b7755a0f42cd320baaf8e3ebeb7c628
+  metadata.gz: 9efd42b242a8c94f0a4372689205e736819ff0fb8e75fa29e95e708899adefacbefec43af0987449fbd3fd766dbb78b1c3f750d51d3141ee4bcb353d08cf9490
+  data.tar.gz: b871fd59eabc84e1f135a4638527f7042b48ee033f17f7bd17378ab7002308e81202c37269912ca5883af30f06c1a7a6a8dc4d121d10573225cb464226f91251

data/CHANGELOG.md

@@ -1,4 +1,28 @@
-## [Unreleased]
+## [0.6.0] - 2026-06-20
+
+### Added
+- Property options for richer schemas: `default`, `nullable`, `read_only`, and `write_only` on any `property` in a request body, response, or shared schema — emitted as OpenAPI `default`, `nullable`, `readOnly`, and `writeOnly`. Falsy values like `default: false` and `default: 0` are preserved
+- Response headers: declare them inside a `response` block with `header "X-RateLimit-Remaining", type: :integer, description: "..."`, emitted as an OpenAPI `headers` object on that response
+- System Map `uses_schema` edges: documented endpoints that reference a shared schema (`schema ref: :User`) are now linked to that schema node in the graph
+- `TROUBLESHOOTING.md` covering common questions (missing routes, ignored options, AI setup, production exposure)
+- README section on restricting access to the docs endpoints in production
+
+### Changed
+- README documents the new property options and response headers
+
+### Removed
+- The AI "Explain section" / system insights feature and its endpoint (`/api-docs/system/insights`). It was unauthenticated — exposing an outbound, billable AI call and rendering AI output without escaping — so it has been removed. The rest of the System Map (diagram, docs view, search, theming, PNG export) is unchanged, and `rails docit:autodoc` is unaffected
+
+## [0.5.0] - 2026-05-31
+
+### Added
+- **System Map**: a local, deterministic architecture graph at `/api-docs/system` (JSON at `/api-docs/system.json`), built from Rails routes, controllers, actions, Docit docs coverage, schemas, models, and source-derived service/job/mailer nodes — no external service required
+- System Map navigation alongside the Scalar and Swagger UIs
+- Light and dark themes for the System Map (light by default), with a toolbar toggle persisted across visits
+- **Diagram view**: interactive architecture graph with drag-to-arrange, scroll-to-zoom, pan, fit-to-screen, and PNG export; click a node to inspect its connections, with neighbouring nodes highlighted; `/` focuses node search
+- Endpoints-section filter for the diagram (Users, Orders, …) that narrows the graph to one resource and everything it touches
+- **Docs view**: a request/response reference grouped by resource, with human-readable endpoint titles derived from doc summaries (falling back to REST conventions), a documentation-coverage indicator per section, and a detail panel showing parameters, request body, and responses
+- AI section explanations in the Docs view: "Explain section" summarises how a resource's endpoints work together, gated by a coverage warning so undocumented sections don't silently spend tokens
 
 ## [0.4.0] - 2026-04-18
 

data/README.md

@@ -11,7 +11,51 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
 ### Swagger
 ![Swagger UI](docs/images/swagger_image.png)
 
-> **Full documentation:** [docitruby.dev/docs](https://docitruby.dev/docs)
+> **Full documentation:** [doc-it.dev/docs](https://doc-it.dev/docs)
+
+## Table Of Contents
+
+- Getting started
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Usage](#usage)
+- Documentation styles
+  - [Style 1: Inline (simple APIs)](#style-1-inline-simple-apis)
+  - [Style 2: Separate doc files (recommended for larger APIs)](#style-2-separate-doc-files-recommended-for-larger-apis)
+- Endpoint DSL reference
+  - [Endpoint documentation DSL](#endpoint-documentation-dsl)
+  - [Request bodies](#request-bodies)
+  - [Path parameters](#path-parameters)
+  - [Enums](#enums)
+  - [Property options](#property-options)
+  - [Response headers](#response-headers)
+  - [Security](#security)
+  - [Deprecated endpoints](#deprecated-endpoints)
+  - [Nested objects and arrays](#nested-objects-and-arrays)
+  - [Response examples](#response-examples)
+  - [Shared schemas (`$ref`)](#shared-schemas-ref)
+  - [File uploads](#file-uploads)
+- AI documentation
+  - [AI Automatic Documentation](#ai-automatic-documentation)
+  - [Quick start (included in install)](#quick-start-included-in-install)
+  - [Standalone commands](#standalone-commands)
+  - [Supported providers](#supported-providers)
+  - [What the AI generates](#what-the-ai-generates)
+- Runtime and development
+  - [Documentation UIs](#documentation-uis)
+  - [System Map](#system-map)
+  - [How it works](#how-it-works)
+  - [Mounting at a different path](#mounting-at-a-different-path)
+  - [Restricting access in production](#restricting-access-in-production)
+  - [JSON spec only](#json-spec-only)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+- Project docs
+  - [CHANGELOG](CHANGELOG.md)
+  - [TROUBLESHOOTING](TROUBLESHOOTING.md)
+  - [CONTRIBUTING](CONTRIBUTING.md)
+  - [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
 
 ## Installation
 
@@ -39,6 +83,8 @@ The install generator does everything in one step:
 
 Visit `/api-docs` to see your interactive API documentation (Scalar by default, Swagger UI also available at `/api-docs/swagger`).
 
+If you choose AI setup, Docit stores your provider config in `.docit_ai.yml` with restricted file permissions and adds that file to `.gitignore` when possible.
+
 ## Configuration
 
 Edit `config/initializers/docit.rb`:
@@ -48,19 +94,39 @@ Docit.configure do |config|
   config.title       = "My API"
   config.version     = "1.0.0"
   config.description = "Backend API documentation"
-  config.default_ui  = :scalar    # :scalar (default) or :swagger
 
-  config.auth :bearer              # Bearer token (JWT)
+  # Documentation UI: :scalar (default) or :swagger
+  config.default_ui  = :scalar
+
+  # Authentication: pick one (or multiple):
+  config.auth :bearer                              # Bearer token (JWT by default)
+  config.auth :basic                               # HTTP Basic
+  config.auth :api_key, name: "X-API-Key",         # API key in header
+                         location: "header"
+
+  # Tag descriptions (shown in the documentation sidebar):
   config.tag "Users", description: "User account management"
+  config.tag "Auth",  description: "Authentication endpoints"
+
+  # Server URLs (shown in the server dropdown):
   config.server "https://api.example.com", description: "Production"
+  config.server "https://staging.example.com", description: "Staging"
+  config.server "http://localhost:3000", description: "Development"
+
+  # License information:
+  config.license name: "MIT", url: "https://opensource.org/licenses/MIT"
+
+  # Contact information:
+  config.contact name: "API Team", email: "api@example.com", url: "https://example.com/support"
+
+  # Terms of service:
+  config.terms_of_service "https://example.com/tos"
 end
 ```
 
-See the [full configuration reference](https://docitruby.dev/docs/configuration) for all options including `license`, `contact`, `terms_of_service`, multiple auth schemes, and server URLs.
-
-## Quick Start
+## Usage
 
-Docit supports two styles. Choose whichever fits your project or mix both.
+Docit supports two styles for documenting endpoints. Choose whichever fits your project or mix both.
 
 ### Style 1: Inline (simple APIs)
 
@@ -73,7 +139,6 @@ class Api::V1::UsersController < ApplicationController
     tags "Users"
     response 200, "Users retrieved"
   end
-
   def index
     # your code
   end
@@ -93,62 +158,451 @@ module Api::V1::UsersDocs
 
   doc :index do
     summary "List all users"
+    description "Returns a paginated list of users"
     tags "Users"
 
+    parameter :page, location: :query, type: :integer, description: "Page number"
+
     response 200, "Users retrieved" do
       property :users, type: :array, items: :object do
         property :id, type: :integer, example: 1
         property :email, type: :string, example: "user@example.com"
       end
+      property :total, type: :integer, example: 42
+    end
+  end
+
+  doc :create do
+    summary "Create a user"
+    tags "Users"
+
+    request_body required: true do
+      property :email, type: :string, required: true
+      property :password, type: :string, required: true, format: :password
+    end
+
+    response 201, "User created" do
+      property :id, type: :integer
+    end
+
+    response 422, "Validation failed" do
+      property :errors, type: :object do
+        property :email, type: :array, items: :string
+      end
     end
   end
 end
-```
 
-```ruby
-# app/controllers/api/v1/users_controller.rb
+# app/controllers/api/v1/users_controller.rb — stays clean!
 class Api::V1::UsersController < ApplicationController
   use_docs Api::V1::UsersDocs
 
   def index
     # pure business logic
   end
+
+  def create
+    # pure business logic
+  end
+end
+```
+
+You can also mix both styles — use `use_docs` for most actions and add inline `doc_for` for one-offs:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  use_docs Api::V1::UsersDocs        # loads :index and :create from doc file
+
+  doc_for :destroy do             # inline doc for this one action
+    summary "Delete user"
+    tags "Users"
+    response 204, "Deleted"
+  end
+
+  def index; end
+  def create; end
+  def destroy; end
+end
+```
+
+### Endpoint documentation DSL
+
+The following examples work in both `doc_for` blocks and `doc` blocks.
+
+### Request bodies
+
+```ruby
+doc_for :create do
+  summary "Create a user"
+  tags "Users"
+
+  request_body required: true do
+    property :email, type: :string, required: true, example: "user@example.com"
+    property :password, type: :string, required: true, format: :password
+    property :name, type: :string, example: "Jane Doe"
+    property :profile, type: :object do
+      property :bio, type: :string
+      property :avatar_url, type: :string, format: :uri
+    end
+  end
+
+  response 201, "User created" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string, example: "user@example.com"
+  end
+
+  response 422, "Validation failed" do
+    property :errors, type: :object do
+      property :email, type: :array, items: :string
+    end
+  end
+end
+def create
+  # your code
+end
+```
+
+### Path parameters
+
+```ruby
+doc_for :show do
+  summary "Get a user"
+  tags "Users"
+
+  parameter :id, location: :path, type: :integer, required: true, description: "User ID"
+
+  response 200, "User found" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string
+    property :name, type: :string
+  end
+
+  response 404, "User not found" do
+    property :error, type: :string, example: "Not found"
+  end
+end
+def show
+  # your code
+end
+```
+
+### Enums
+
+```ruby
+doc_for :index do
+  summary "List orders"
+  tags "Orders"
+
+  parameter :status, location: :query, type: :string,
+            enum: %w[pending shipped delivered],
+            description: "Filter by status"
+
+  response 200, "Orders list" do
+    property :orders, type: :array do
+      property :id, type: :integer
+      property :status, type: :string, enum: %w[pending shipped delivered]
+    end
+  end
+end
+```
+
+### Property options
+
+Any `property` (in a request body, response, or shared schema) accepts these OpenAPI 3.0.3 options:
+
+```ruby
+request_body required: true do
+  property :id,       type: :integer, read_only: true        # readOnly: present in responses, not accepted as input
+  property :password, type: :string,  write_only: true       # writeOnly: accepted as input, never returned
+  property :role,     type: :string,  default: "member"      # default value
+  property :nickname, type: :string,  nullable: true         # may be null
+  property :active,   type: :boolean, default: false         # falsy defaults are preserved
+end
+```
+
+These map to `readOnly`, `writeOnly`, `default`, and `nullable` in the generated spec.
+
+### Response headers
+
+Document the headers a response returns with `header` inside a `response` block:
+
+```ruby
+response 200, "Orders list" do
+  header "X-Total-Count", type: :integer, description: "Total orders available"
+  header "X-RateLimit-Remaining", type: :integer, description: "Requests left in the window"
+
+  property :orders, type: :array do
+    property :id, type: :integer
+  end
+end
+```
+
+### Security
+
+Mark endpoints as requiring authentication:
+
+```ruby
+doc_for :destroy do
+  summary "Delete a user"
+  tags "Users"
+  security :bearer_auth      # references the scheme from your config
+
+  response 204, "User deleted"
+  response 401, "Unauthorized"
+end
+```
+
+### Deprecated endpoints
+
+```ruby
+doc_for :legacy_search do
+  summary "Search (legacy)"
+  tags "Search"
+  deprecated
+
+  response 200, "Results"
+end
+```
+
+### Nested objects and arrays
+
+```ruby
+response 200, "Success" do
+  property :user, type: :object do
+    property :id, type: :integer
+    property :name, type: :string
+    property :addresses, type: :array do
+      property :street, type: :string
+      property :city, type: :string
+      property :zip, type: :string
+    end
+  end
+end
+```
+
+### Response examples
+
+```ruby
+response 200, "User found" do
+  property :id, type: :integer
+  property :email, type: :string
+
+  example "admin_user",
+          { id: 1, email: "admin@example.com" },
+          description: "An admin user"
+
+  example "regular_user",
+          { id: 2, email: "user@example.com" },
+          description: "A regular user"
+end
+```
+
+### Shared schemas (`$ref`)
+
+Define reusable schemas once and reference them across multiple endpoints:
+
+```ruby
+# In config/initializers/docit.rb or a dedicated file:
+Docit.define_schema :User do
+  property :id,    type: :integer, example: 1
+  property :email, type: :string,  example: "user@example.com"
+  property :name,  type: :string,  example: "Jane Doe"
+  property :address, type: :object do
+    property :street, type: :string
+    property :city,   type: :string
+  end
+end
+
+Docit.define_schema :Error do
+  property :error,   type: :string, example: "Not found"
+  property :details, type: :array, items: :string
+end
+```
+
+Reference them in any endpoint with `schema ref:`:
+
+```ruby
+doc_for :show do
+  summary "Get user"
+  tags "Users"
+
+  response 200, "User found" do
+    schema ref: :User
+  end
+
+  response 404, "Not found" do
+    schema ref: :Error
+  end
+end
+
+doc_for :create do
+  summary "Create user"
+  tags "Users"
+
+  request_body required: true do
+    schema ref: :User
+  end
+
+  response 201, "Created" do
+    schema ref: :User
+  end
+end
+```
+
+This outputs `$ref: '#/components/schemas/User'` in the spec — Swagger UI resolves it automatically.
+
+### File uploads
+
+Use `type: :file` with `content_type: "multipart/form-data"` for file upload endpoints:
+
+```ruby
+doc_for :upload_avatar do
+  summary "Upload avatar"
+  tags "Users"
+
+  request_body required: true, content_type: "multipart/form-data" do
+    property :avatar, type: :file, required: true, description: "Avatar image"
+    property :caption, type: :string
+  end
+
+  response 201, "Avatar uploaded" do
+    property :url, type: :string, format: :uri
+  end
 end
 ```
 
-See the [full DSL reference](https://docitruby.dev/docs/dsl-reference) for request bodies, path parameters, enums, security, nested objects, file uploads, shared schemas, and more.
+`type: :file` maps to `{ type: "string", format: "binary" }` in the OpenAPI spec.
+
+## AI Automatic Documentation
+
+Docit can generate complete API documentation using AI. This works with OpenAI, Anthropic, or Groq (free tier available).
 
-## AI Documentation
+### Quick start (included in install)
 
-Docit can generate complete API documentation using AI. Works with OpenAI, Anthropic, or Groq (free tier available).
+When you run `rails generate docit:install` and choose option 1 (AI automatic docs), everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
 
-When you run `rails generate docit:install` and choose AI automatic docs, everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
+Before the first AI request, Docit warns that your controller source code will be sent to the selected provider and asks for confirmation in interactive terminals.
+
+### Standalone commands
+
+You can also set up AI docs separately:
 
 ```bash
-# Or set up AI docs separately:
+# Configure your AI provider (one-time setup)
 rails generate docit:ai_setup
+
+# Generate docs for all undocumented endpoints
 rails docit:autodoc
 
-# Preview without writing files:
+# Generate docs for a specific controller
+rails docit:autodoc[Api::V1::UsersController]
+
+# Preview what would be generated without writing files
 DRY_RUN=1 rails docit:autodoc
 ```
 
-See the [full AI documentation guide](https://docitruby.dev/docs/ai-documentation) for provider details, safety considerations, and standalone commands.
+### Supported providers
+
+| Provider   | Notes |
+|------------|-------|
+| OpenAI     | Requires API key from platform.openai.com |
+| Anthropic  | Requires API key from console.anthropic.com |
+| Groq       | Free tier at console.groq.com |
+
+All providers automatically retry on rate-limit (429) errors with exponential backoff, so free-tier usage works out of the box.
+
+AI configuration is stored in `.docit_ai.yml`.
+If your app does not have a `.gitignore`, add `.docit_ai.yml` manually.
+
+### What the AI generates
+
+For each undocumented endpoint, Docit:
+
+1. Reads the controller source code
+2. Inspects the route (HTTP method, path, parameters)
+3. Writes the generated doc block to `app/docs/`
+4. Injects `use_docs` into the controller
+5. Adds tag descriptions to the initializer
+
+Do not use AI autodoc on controllers that contain secrets, proprietary business rules, or internal comments you do not want sent to an external provider.
 
 ## Documentation UIs
 
+Docit ships with two documentation UIs, both reading from the same OpenAPI spec:
+
 | Path | UI | Notes |
 |------|------|-------|
 | `/api-docs` | Default (Scalar) | Configurable via `config.default_ui` |
-| `/api-docs/scalar` | Scalar API Reference | Modern UI with API client, dark mode |
+| `/api-docs/scalar` | Scalar API Reference | Modern UI with built-in API client, dark mode, code samples |
 | `/api-docs/swagger` | Swagger UI | Classic OpenAPI explorer |
+| `/api-docs/system` | System Map | Local architecture graph for routes, controllers, docs coverage, and app structure |
 | `/api-docs/spec` | Raw JSON | OpenAPI 3.0.3 spec |
 
-## How It Works
+Both UIs include a navigation bar to switch between them. Set `config.default_ui = :swagger` to make Swagger the default at `/api-docs`.
+
+## System Map
+
+Docit includes a local system map for understanding how your Rails API fits together. It builds a **deterministic** graph from Rails routes, controller actions, Docit docs, schemas, models, and source references — no external service is required to view it.
+
+Visit `/api-docs/system` to open it. It has two views, a light/dark theme toggle, and PNG export:
+
+- **Diagram** — an interactive architecture graph. Drag nodes to rearrange, scroll to zoom, and click a node to inspect its connections (its neighbours highlight while the rest fade back). Filter to a single resource with the section dropdown, or press `/` to search nodes.
+- **Docs** — a request/response reference grouped by resource. Each endpoint shows a human-readable title, its method and path, parameters, request body, and responses, drawn from your Docit docs. A coverage indicator shows how many endpoints in each section are documented.
+
+If you have an AI provider configured, the Docs view's **Explain section** button summarises how a resource's endpoints work together. It warns before running on sections with undocumented endpoints, so documenting first gives a better result.
+
+## How it works
 
 1. `doc_for` registers an **Operation** for each controller action in a global **Registry**
 2. When someone visits `/api-docs/spec`, Docit's **SchemaGenerator** combines all registered operations with your Rails routes (via **RouteInspector**) to produce an OpenAPI 3.0.3 JSON document
 3. The **Engine** serves the configured documentation UI at `/api-docs`, pointing it at the generated spec
+4. The **SystemGraph** builds a local architecture graph for `/api-docs/system`
+
+The DSL is included in all controllers automatically via a Rails Engine initializer — no manual `include` needed if you're using `ActionController::API` or `ActionController::Base`.
+
+## Mounting at a different path
+
+In `config/routes.rb`:
+
+```ruby
+mount Docit::Engine => "/docs"        # now at /docs instead of /api-docs
+```
+
+## Restricting access in production
+
+The Docit endpoints (`/api-docs`, `/api-docs/spec`, `/api-docs/system`, `/api-docs/system.json`) are **unauthenticated by default** and expose your full API surface, the OpenAPI spec, and — for the System Map — your app's structure and source file paths. That is convenient in development, but in production you almost always want to gate them.
+
+Mount the engine inside an authenticated constraint, or behind whatever auth your app already uses:
+
+```ruby
+# config/routes.rb
+
+# Option A — only mount outside production
+mount Docit::Engine => "/api-docs" unless Rails.env.production?
+
+# Option B — gate behind an authenticated constraint (e.g. Devise admins)
+authenticate :user, ->(u) { u.admin? } do
+  mount Docit::Engine => "/api-docs"
+end
+
+# Option C — HTTP Basic auth via a Rack constraint
+admins_only = ->(request) do
+  ActiveSupport::SecurityUtils.secure_compare(
+    request.authorization.to_s, ENV.fetch("DOCS_AUTH", "")
+  )
+end
+constraints(admins_only) { mount Docit::Engine => "/api-docs" }
+```
+
+If you disable the System Map specifically, set `config.system_graph_enabled = false` — `/api-docs/system.json` then returns `404`.
+
+## JSON spec only
+
+If you just want the raw OpenAPI JSON (e.g., for code generation):
+
+```
+GET /api-docs/spec
+```
 
 ## Development
 
@@ -156,7 +610,7 @@ See the [full AI documentation guide](https://docitruby.dev/docs/ai-documentatio
 git clone https://github.com/S13G/docit.git
 cd docit
 bundle install
-bundle exec rspec
+bundle exec rspec        # run all tests
 ```
 
 ## Contributing

data/TROUBLESHOOTING.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+Common questions and fixes when working with Docit.
+
+## My route isn't showing up in the spec
+
+Docit only documents an endpoint if **both** are true:
+
+1. The route exists in `config/routes.rb` (visible in `rails routes`).
+2. A doc is registered for that controller + action — either inline with `doc_for :action do ... end` or via `use_docs SomeDocs`.
+
+A route with no matching `doc_for`/`use_docs` is simply absent from `/api-docs/spec`. It will still appear on the **System Map** (`/api-docs/system`) marked `undocumented`, which is the quickest way to see your coverage gaps.
+
+Checklist:
+
+- Is the action name spelled exactly the same in the route and in `doc_for`?
+- Is the controller actually loaded? Docit eager-loads controllers when generating the spec, but a controller in a non-standard path may be missed.
+- If using `use_docs`, does the doc module define a `doc :action` block for that action?
+
+## A doc_for option seems to be ignored
+
+Docit's DSL methods are explicit. If you mistype one (e.g. `summmary` instead of `summary`), the call currently does nothing rather than raising — so the option silently disappears.
+
+Double-check the spelling of DSL methods against the [DSL reference in the README](README.md). The supported response/property options include `summary`, `description`, `tags`, `response`, `request_body`, `parameter`, `property` (with `type`, `format`, `example`, `enum`, `default`, `nullable`, `read_only`, `write_only`), `header`, `schema ref:`, `security`, `deprecated`, and `operation_id`.
+
+## A System Map section says "undocumented" or shows low coverage
+
+That section's endpoints have no registered docs. Add `doc_for`/`use_docs` for those actions, or accept the gap — coverage is informational, not an error.
+
+## Schemas aren't linked on the System Map
+
+`uses_schema` edges only appear when a documented endpoint references a shared schema with `schema ref: :Name` (in its request body or a response), and that schema is defined with `Docit.define_schema :Name`. A plain inline `property` block does not create a schema node.
+
+## I documented an action twice and my changes are ignored
+
+Docit's registry keeps the **first** doc registered for a given controller + action and ignores later ones. So if an action is already documented (e.g. via `use_docs SomeDocs`) and you also add an inline `doc_for :same_action do ... end`, the inline block is silently dropped — the `use_docs` version wins.
+
+Document each action in exactly one place. If you need to override a shared doc module for one action, change it in the module rather than re-declaring it on the controller.
+
+## AI autodoc / scaffolding isn't working
+
+- Run `rails generate docit:ai_setup` once to configure a provider (OpenAI, Anthropic, or Groq). The key is written to `.docit_ai.yml`, which the generator adds to `.gitignore` — **never commit it.**
+- `rails docit:autodoc` sends controller **source code** to your configured provider. In an interactive terminal it asks for confirmation first; in a non-interactive context (CI, piping) it proceeds without prompting, so only run it where sending source is acceptable.
+- Preview without writing files: `DRY_RUN=1 rails docit:autodoc`.
+- Rate-limit / 429 errors are retried with backoff automatically; a persistent failure usually means an invalid key or an unsupported model name.
+
+## The System Map or docs pages are exposed in production
+
+The Docit endpoints are **unauthenticated by default**. They expose your API surface, the OpenAPI spec, and your app structure. In production, gate the engine — see [Restricting access in production](README.md#restricting-access-in-production) in the README. To disable the System Map specifically, set `config.system_graph_enabled = false`.
+
+## Spec generation is slow on a large app
+
+Generating the spec eager-loads controllers and walks every route. For very large apps this is a one-time cost per request; put the docs behind a cache or a non-production-only mount if it matters. The System Map graph is rebuilt per request — if that becomes a bottleneck, mount it behind auth and access it sparingly.
+
+## Still stuck?
+
+Open an issue at <https://github.com/S13G/docit/issues> with your Docit version, Rails version, and a minimal `doc_for` / route example.