docit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85a7407aab5a5fea2aa0c679d469360f124884ebeac2e4479265cbcdd818210d
-  data.tar.gz: c946eea9c5a664931630b00726f33b8e5bb296c1493e799c67cd905f330cba1d
+  metadata.gz: ad97aecf5e4f97baffb4f944fa8f8a62b449846714e1c2dd2e8bbdc9a167ee22
+  data.tar.gz: f638754ff073096c6904db2e5d394413e2f1c579966b97af831cfe93ae91af51
 SHA512:
-  metadata.gz: 3dd0a62c6d0f138916839a7bcc445f98921abaf9e0ef477473e4dddba67f2033fd29ffb51a4803597d98f0807ee24c53d6b5a90a8d144d87c54669ee51155fef
-  data.tar.gz: d953ceef06cd91034fa79503a07da386dcefc7cdddabcb3567d1638d6546a2c484bdebd82f263d732a94b89447a9e9f6b659d7008c322d2e238e002aca286a1b
+  metadata.gz: 9efd42b242a8c94f0a4372689205e736819ff0fb8e75fa29e95e708899adefacbefec43af0987449fbd3fd766dbb78b1c3f750d51d3141ee4bcb353d08cf9490
+  data.tar.gz: b871fd59eabc84e1f135a4638527f7042b48ee033f17f7bd17378ab7002308e81202c37269912ca5883af30f06c1a7a6a8dc4d121d10573225cb464226f91251

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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

data/README.md

@@ -27,6 +27,8 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
   - [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)
@@ -44,12 +46,14 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
   - [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)
 
@@ -302,6 +306,37 @@ doc_for :index do
 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:
@@ -533,6 +568,34 @@ In `config/routes.rb`:
 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):

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.

data/app/controllers/docit/ui_controller.rb

@@ -21,26 +21,12 @@ module Docit
     end
 
     def system_spec
-      unless Docit.configuration.system_graph_enabled
-        return render(json: { error: "System graph disabled" }, status: :not_found)
-      end
+      return render(json: { error: "System graph disabled" }, status: :not_found) unless Docit.configuration.system_graph_enabled
 
       RouteInspector.eager_load_controllers!
       render json: SystemGraph::Generator.generate
     end
 
-    def system_insights
-      graph = system_graph
-      insight = Ai::SystemInsightGenerator.new(
-        graph: graph,
-        selected_node_ids: selected_node_ids,
-        mode: insight_mode
-      ).generate
-      render json: { insight: insight }
-    rescue Docit::Error => e
-      render json: { error: e.message }, status: :unprocessable_entity
-    end
-
     def spec
       RouteInspector.eager_load_controllers!
       render json: SchemaGenerator.generate
@@ -58,27 +44,11 @@ module Docit
       renderer = RENDERERS.fetch(ui_name).new(
         spec_url: spec_url,
         system_url: system_url,
-        system_insights_url: system_insights_url,
         nav_paths: nav_paths
       )
       render html: renderer.render.html_safe, layout: false
     end
 
-    def system_graph
-      RouteInspector.eager_load_controllers!
-      SystemGraph::Generator.generate
-    end
-
-    def selected_node_ids
-      params.fetch(:node_ids, "").to_s.split(",").reject(&:empty?)
-    end
-
-    # Validate at the boundary: only the known modes are honored, anything
-    # else falls back to the safe per-node default.
-    def insight_mode
-      params[:mode].to_s == "section" ? :section : :nodes
-    end
-
     def spec_url
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
     end
@@ -87,10 +57,6 @@ module Docit
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_spec_path}"
     end
 
-    def system_insights_url
-      "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_insights_path}"
-    end
-
     def nav_paths
       helpers = Docit::Engine.routes.url_helpers
       { swagger: helpers.swagger_path, scalar: helpers.scalar_path, system: helpers.system_path }

data/config/routes.rb

@@ -5,7 +5,6 @@ Docit::Engine.routes.draw do
   get "swagger", to: "ui#swagger"
   get "scalar", to: "ui#scalar"
   get "system.json", to: "ui#system_spec", defaults: { format: :json }, as: :system_spec
-  get "system/insights", to: "ui#system_insights", defaults: { format: :json }, as: :system_insights
   get "system", to: "ui#system", as: :system
   get "spec", to: "ui#spec", defaults: { format: :json }
 end

data/lib/docit/ai/autodoc_runner.rb

@@ -57,9 +57,7 @@ module Docit
         end
 
         initializer = Rails.root.join("config", "initializers", "docit.rb")
-        if File.exist?(initializer) == false
-          raise Docit::Error, "Docit is not installed. Run: rails generate docit:install"
-        end
+        raise Docit::Error, "Docit is not installed. Run: rails generate docit:install" if File.exist?(initializer) == false
 
         routes_file = Rails.root.join("config", "routes.rb")
         return unless File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
@@ -179,8 +177,15 @@ module Docit
           end
         end
 
+        endpoints = pluralize(@results[:generated], "endpoint")
+        files = pluralize(@results[:files].length, "file")
         @output.puts ""
-        @output.puts "Generated docs for #{@results[:generated]} endpoint#{"s" if @results[:generated] > 1} in #{@results[:files].length} file#{"s" if @results[:files].length > 1}."
+        @output.puts "Generated docs for #{endpoints} in #{files}."
+      end
+
+      # "1 endpoint" / "2 endpoints" — keeps the summary lines short and readable.
+      def pluralize(count, noun)
+        "#{count} #{noun}#{"s" unless count == 1}"
       end
 
       def inject_tags(generated)

data/lib/docit/ai/doc_writer.rb

@@ -20,7 +20,7 @@ module Docit
       end
 
       def doc_module_name
-        @controller_name.delete_suffix("Controller").gsub("::", "::") + "Docs"
+        "#{@controller_name.delete_suffix("Controller").gsub("::", "::")}Docs"
       end
 
       def file_exists?
@@ -44,7 +44,7 @@ module Docit
         match = content.match(class_pattern)
         return false if match.nil?
 
-        indent = match[1][/^\s*/] + "  "
+        indent = "#{match[1][/^\s*/]}  "
         use_docs_line = "#{indent}use_docs #{doc_module_name}\n"
         content = content.sub(class_pattern, "\\1\n#{use_docs_line}")
 
@@ -100,7 +100,7 @@ module Docit
           lines << "#{"  " * (@module_parts.length - 1 - i)}end"
         end
 
-        lines.join("\n") + "\n"
+        "#{lines.join("\n")}\n"
       end
 
       def indent_block(block, depth)

data/lib/docit/ai/groq_client.rb

@@ -59,18 +59,14 @@ module Docit
 
       def parse_retry_after(response, message)
         # Check Retry-After header first (seconds)
-        if (header = response["Retry-After"])
-          return header.to_f if header.to_f > 0
+        if (header = response["Retry-After"]) && header.to_f.positive?
+          return header.to_f
         end
 
         # Parse "try again in XmY.Zs" from error message
-        if message =~ /(\d+)m([\d.]+)s/
-          return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f
-        end
+        return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f if message =~ /(\d+)m([\d.]+)s/
 
-        if message =~ /([\d.]+)s/
-          return Regexp.last_match(1).to_f
-        end
+        return Regexp.last_match(1).to_f if message =~ /([\d.]+)s/
 
         nil
       end

data/lib/docit/ai/scaffold_generator.rb

@@ -50,8 +50,10 @@ module Docit
 
         inject_tags(grouped)
 
+        endpoints = "endpoint".pluralize(gaps.length)
+        files = "file".pluralize(@files_written.length)
         @output.puts ""
-        @output.puts "Scaffolded #{gaps.length} endpoint#{"s" if gaps.length > 1} in #{@files_written.length} file#{"s" if @files_written.length > 1}."
+        @output.puts "Scaffolded #{gaps.length} #{endpoints} in #{@files_written.length} #{files}."
         @output.puts "Fill in the TODO placeholders in your doc files."
         @files_written
       end

data/lib/docit/ai/tag_injector.rb

@@ -24,7 +24,7 @@ module Docit
         insertion_point = find_insertion_point(content)
         return [] if insertion_point.nil?
 
-        content = content.insert(insertion_point, "\n#{lines.join("\n")}")
+        content.insert(insertion_point, "\n#{lines.join("\n")}")
         File.write(initializer_path, content)
 
         new_tags

data/lib/docit/ai.rb

@@ -12,4 +12,3 @@ require_relative "ai/doc_writer"
 require_relative "ai/tag_injector"
 require_relative "ai/autodoc_runner"
 require_relative "ai/scaffold_generator"
-require_relative "ai/system_insight_generator"

data/lib/docit/builders/response_builder.rb

@@ -3,15 +3,16 @@
 module Docit
   module Builders
     # Builds the schema for a single HTTP response, including properties,
-    # examples, and schema references.
+    # examples, headers, and schema references.
     class ResponseBuilder
-      attr_reader :status, :description, :properties, :examples, :schema_ref
+      attr_reader :status, :description, :properties, :examples, :headers, :schema_ref
 
       def initialize(status:, description:)
         @status = status
         @description = description
         @properties = []
         @examples = []
+        @headers = []
         @schema_ref = nil
       end
 
@@ -19,6 +20,15 @@ module Docit
         @schema_ref = ref.to_sym
       end
 
+      # Declares a response header, e.g. a rate-limit or pagination header:
+      #   header "X-RateLimit-Remaining", type: :integer, description: "..."
+      def header(name, type: :string, description: nil, example: nil)
+        entry = { name: name.to_s, type: type.to_s }
+        entry[:description] = description if description
+        entry[:example] = example unless example.nil?
+        @headers << entry
+      end
+
       def property(name, type:, format: nil, example: nil, enum: nil, description: nil, items: nil, **opts, &block)
         prop = { name: name, type: type }
         prop[:format] = format if format

data/lib/docit/configuration.rb

@@ -27,9 +27,7 @@ module Docit
 
     def default_ui=(value)
       ui = value.to_sym
-      unless SUPPORTED_UIS.include?(ui)
-        raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}"
-      end
+      raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}" unless SUPPORTED_UIS.include?(ui)
 
       @default_ui = ui
     end

data/lib/docit/schema_generator.rb

@@ -104,10 +104,21 @@ module Docit
           entry[:content] = content
         end
 
+        entry[:headers] = build_response_headers(builder.headers) if builder.headers.any?
+
         hash[builder.status.to_s] = entry
       end
     end
 
+    def build_response_headers(headers)
+      headers.each_with_object({}) do |header, hash|
+        schema = { schema: { type: header[:type] } }
+        schema[:description] = header[:description] if header[:description]
+        schema[:schema][:example] = header[:example] if header.key?(:example)
+        hash[header[:name]] = schema
+      end
+    end
+
     def build_request_body(request_body_builder)
       if request_body_builder.schema_ref
         schema = { "$ref" => "#/components/schemas/#{request_body_builder.schema_ref}" }
@@ -138,43 +149,50 @@ module Docit
 
     def build_property_schema(prop)
       type = prop[:type].to_s
+      schema = base_property_schema(type, prop)
+
+      # These OpenAPI fields apply to any property shape, so set them once here
+      # rather than in each branch above. nil-checks let `false`/`0` through as
+      # explicit values (e.g. default: false), but skip unset options.
+      schema[:description] = prop[:description] if prop[:description]
+      schema[:example] = prop[:example] if prop[:example]
+      schema[:default] = prop[:default] unless prop[:default].nil?
+      schema[:nullable] = prop[:nullable] unless prop[:nullable].nil?
+      schema[:readOnly] = prop[:read_only] unless prop[:read_only].nil?
+      schema[:writeOnly] = prop[:write_only] unless prop[:write_only].nil?
+      schema
+    end
 
-      if type == "file"
-        schema = { type: "string", format: "binary" }
-        schema[:description] = prop[:description] if prop[:description]
-        schema
-      elsif type == "array"
-        schema = { type: "array" }
-        if prop[:children]
-          schema[:items] = {
-            type: "object",
-            properties: build_properties(prop[:children])
-          }
+    def base_property_schema(type, prop)
+      case type
+      when "file"
+        { type: "string", format: "binary" }
+      when "array"
+        { type: "array", items: array_items_schema(prop) }
+      else
+        # An object with declared children becomes a nested schema; everything
+        # else (including a childless "object") is a scalar with type/format/enum.
+        if type == "object" && prop[:children]
+          { type: "object", properties: build_properties(prop[:children]) }
         else
-          items_type = prop[:items]&.to_s || "string"
-          schema[:items] = { type: items_type }
+          scalar_property_schema(type, prop)
         end
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      elsif type == "object" && prop[:children]
-        schema = {
-          type: "object",
-          properties: build_properties(prop[:children])
-        }
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      else
-        schema = { type: type }
-        schema[:format] = prop[:format].to_s if prop[:format]
-        schema[:enum] = prop[:enum] if prop[:enum]
-        schema[:example] = prop[:example] if prop[:example]
-        schema[:description] = prop[:description] if prop[:description]
-        schema
       end
     end
 
+    def array_items_schema(prop)
+      return { type: "object", properties: build_properties(prop[:children]) } if prop[:children]
+
+      { type: prop[:items]&.to_s || "string" }
+    end
+
+    def scalar_property_schema(type, prop)
+      schema = { type: type }
+      schema[:format] = prop[:format].to_s if prop[:format]
+      schema[:enum] = prop[:enum] if prop[:enum]
+      schema
+    end
+
     def build_component_schemas
       Docit.schemas.each_with_object({}) do |(name, definition), hash|
         schema = {

data/lib/docit/system_graph/rails_analyzer.rb

@@ -16,6 +16,9 @@ module Docit
         add_schemas
         add_models
         add_source_nodes
+        # Runs last: Graph#add_edge drops edges to not-yet-created nodes, so
+        # schema-usage edges must be added after both doc and schema nodes exist.
+        add_schema_usage_edges
         graph
       end
 
@@ -110,6 +113,27 @@ module Docit
         graph.add_edge(edge(doc_id, action_id, "documents", "high", "Docit registry"))
       end
 
+      # Link each doc node to every shared schema it references via $ref (in its
+      # request body or any response). Runs as a final pass because add_edge only
+      # keeps edges whose endpoints already exist as nodes. Confidence is high —
+      # the references come straight from the Docit registry.
+      def add_schema_usage_edges
+        graph.nodes.values.select { |node| node.type == "doc" }.each do |doc|
+          operation = Registry.find(controller: doc.metadata[:controller], action: doc.metadata[:action])
+          next unless operation
+
+          schema_refs_for(operation).each do |ref|
+            graph.add_edge(edge(doc.id, node_id("schema", ref), "uses_schema", "high", "Docit registry $ref"))
+          end
+        end
+      end
+
+      def schema_refs_for(operation)
+        refs = [operation._request_body&.schema_ref]
+        operation._responses.each { |res| refs << res.schema_ref }
+        refs.compact.uniq
+      end
+
       def add_schemas
         Docit.schemas.each_key do |name|
           graph.add_node(Node.new(
@@ -147,7 +171,8 @@ module Docit
           target_id = node_id("model", target)
           next unless graph.nodes.key?(target_id)
 
-          graph.add_edge(edge(model_id, target_id, "association", "high", "ActiveRecord reflection: #{association.name}"))
+          graph.add_edge(edge(model_id, target_id, "association", "high",
+                              "ActiveRecord reflection: #{association.name}"))
         end
       end
 
@@ -156,12 +181,14 @@ module Docit
         source_nodes.each { |node| graph.add_node(node) }
 
         labels = graph.nodes.values.select { |node| %w[model service job mailer].include?(node.type) }.map(&:label)
-        graph.nodes.values.select { |node| %w[controller action service job mailer].include?(node.type) }.each do |source|
+        sources = graph.nodes.values.select { |node| %w[controller action service job mailer].include?(node.type) }
+        sources.each do |source|
           scanner.references_for(source.file, labels).each do |label|
             target = graph.nodes.values.find { |node| node.label == label }
             next unless target
 
-            graph.add_edge(edge(source.id, target.id, edge_type_for(target), "medium", "Constant reference in #{source.file}"))
+            graph.add_edge(edge(source.id, target.id, edge_type_for(target), "medium",
+                                "Constant reference in #{source.file}"))
           end
         end
       end
@@ -203,7 +230,7 @@ module Docit
       end
 
       def node_id(type, label)
-        "#{type}:#{label.to_s.underscore.tr('/', ':')}"
+        "#{type}:#{label.to_s.underscore.tr("/", ":")}"
       end
 
       def controller_file(controller)

data/lib/docit/system_graph/source_scanner.rb

@@ -41,8 +41,7 @@ module Docit
 
       private
 
-      attr_reader :root
-      attr_reader :excluded_paths
+      attr_reader :root, :excluded_paths
 
       def scan_dir(dir)
         full_dir = root.join(dir)
@@ -62,7 +61,7 @@ module Docit
       end
 
       def node_id(type, label)
-        "#{type}:#{label.underscore.tr('/', ':')}"
+        "#{type}:#{label.underscore.tr("/", ":")}"
       end
 
       def full_path(path)

data/lib/docit/ui/base_renderer.rb

@@ -3,12 +3,11 @@
 module Docit
   module UI
     class BaseRenderer
-      attr_reader :spec_url, :system_url, :system_insights_url, :title, :nav_paths
+      attr_reader :spec_url, :system_url, :title, :nav_paths
 
-      def initialize(spec_url:, system_url: nil, system_insights_url: nil, nav_paths: {})
+      def initialize(spec_url:, system_url: nil, nav_paths: {})
         @spec_url = spec_url
         @system_url = system_url
-        @system_insights_url = system_insights_url
         @nav_paths = nav_paths
         @title = ERB::Util.html_escape(Docit.configuration.title)
       end
@@ -54,9 +53,9 @@ module Docit
           </style>
           <nav class="docit-nav">
             <span style="font-weight: 600; margin-right: auto;">#{title}</span>
-            <a href="#{ERB::Util.html_escape(nav_paths[:swagger])}" class="docit-nav-link #{'active' if swagger_active}">Swagger</a>
-            <a href="#{ERB::Util.html_escape(nav_paths[:scalar])}" class="docit-nav-link #{'active' if scalar_active}">Scalar</a>
-            <a href="#{ERB::Util.html_escape(nav_paths[:system])}" class="docit-nav-link #{'active' if system_active}">System</a>
+            <a href="#{ERB::Util.html_escape(nav_paths[:swagger])}" class="docit-nav-link #{"active" if swagger_active}">Swagger</a>
+            <a href="#{ERB::Util.html_escape(nav_paths[:scalar])}" class="docit-nav-link #{"active" if scalar_active}">Scalar</a>
+            <a href="#{ERB::Util.html_escape(nav_paths[:system])}" class="docit-nav-link #{"active" if system_active}">System</a>
           </nav>
         HTML
       end
@@ -69,19 +68,15 @@ module Docit
         json_escape(JSON.generate(system_url))
       end
 
-      def system_insights_url_json
-        json_escape(JSON.generate(system_insights_url))
-      end
-
       def json_escape(json_string)
         json_string.to_s.gsub(/[&<>'\u2028\u2029]/, {
-          '&' => '\u0026',
-          '<' => '\u003c',
-          '>' => '\u003e',
-          "'" => '\u0027',
-          "\u2028" => '\u2028',
-          "\u2029" => '\u2029'
-        })
+                                "&" => '\u0026',
+                                "<" => '\u003c',
+                                ">" => '\u003e',
+                                "'" => '\u0027',
+                                "\u2028" => '\u2028',
+                                "\u2029" => '\u2029'
+                              })
       end
     end
   end

data/lib/docit/ui/system_renderer.rb

@@ -94,7 +94,7 @@ module Docit
                         <div class="stripe-detail-empty-icon" aria-hidden="true">
                           <svg width="26" height="26" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 1.5h6L13 5v9.5H3z"/><path d="M9 1.5V5h4"/><path d="M5.5 8.5h5M5.5 11h3"/></svg>
                         </div>
-                        <p>Select an endpoint to see how to call it, or use <strong>Explain section</strong> for an AI overview.</p>
+                        <p>Select an endpoint to see how to call it.</p>
                       </div>
                     </div>
                   </aside>
@@ -103,7 +103,7 @@ module Docit
               </div>
             </div>
             <div id="toast" class="toast" role="status"></div>
-            <script>#{SystemScript.javascript(graph_url: system_url, insights_url: system_insights_url)}</script>
+            <script>#{SystemScript.javascript(graph_url: system_url)}</script>
           </body>
           </html>
         HTML

data/lib/docit/ui/system_script.rb

@@ -3,7 +3,7 @@
 module Docit
   module UI
     module SystemScript
-      def self.javascript(graph_url:, insights_url:)
+      def self.javascript(graph_url:)
         <<~JS
           (function() {
           "use strict";
@@ -11,7 +11,6 @@ module Docit
           /* ───────────────────────── Configuration ───────────────────────── */
 
           const graphUrl  = #{json_escape(JSON.generate(graph_url))};
-          const insightsUrl = #{json_escape(JSON.generate(insights_url))};
 
           const TYPE_COLORS = {
             route:      "#4da6ff",
@@ -110,7 +109,6 @@ module Docit
             return '<svg width="' + s + '" height="' + s + '" viewBox="0 0 16 16" fill="none" stroke="currentColor" ' +
               'stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round">' + paths + '</svg>';
           }
-          const ICON_SPARKLE = '<path d="M8 1.5l1.6 4.3 4.4 1.6-4.4 1.6L8 13.4 6.4 9 2 7.4l4.4-1.6L8 1.5z"/>';
           const ICON_CLICK   = '<path d="M6 7V3.5a1.2 1.2 0 0 1 2.4 0V7m0-1.2a1.2 1.2 0 0 1 2.4 0V7m0-.6a1.2 1.2 0 0 1 2.4 0v3.2a4 4 0 0 1-4 4H9a4 4 0 0 1-3.3-1.7L3.5 8.8a1.2 1.2 0 0 1 2-1.3L6 8"/>';
           const ICON_DRAG    = '<path d="M3 8h10M8 3l5 5-5 5M3 8l5-5M3 8l5 5"/>';
           const ICON_SEARCH  = '<circle cx="7" cy="7" r="4.5"/><path d="M10.5 10.5l3 3"/>';
@@ -694,33 +692,6 @@ module Docit
             render();
           }
 
-          function formatMarkdown(text) {
-            return text
-              /* Mermaid blocks — label them clearly and show as readable code */
-              .replace(/```mermaid[\\s\\S]*?```/g, function(block) {
-                var code = block.replace(/```mermaid\\n?/, "").replace(/```$/, "").trim();
-                return '<div style="margin:10px 0">' +
-                  '<div style="font-size:10px;color:var(--haze);font-family:monospace;text-transform:uppercase;letter-spacing:.06em;margin-bottom:6px">Flow diagram</div>' +
-                  '<pre style="background:var(--bg-code);border:1px solid var(--border);border-radius:8px;padding:12px;font-size:11px;color:var(--smoke);overflow-x:auto;line-height:1.6">' + esc(code) + '</pre>' +
-                '</div>';
-              })
-              /* Generic code blocks */
-              .replace(/```[\\s\\S]*?```/g, function(block) {
-                var code = block.replace(/```\\w*\\n?/, "").replace(/```$/, "").trim();
-                return '<pre style="background:var(--bg-code);border:1px solid var(--border);border-radius:8px;padding:10px;font-size:11px;color:var(--smoke);overflow-x:auto">' + esc(code) + '</pre>';
-              })
-              .replace(/\\*\\*(.+?)\\*\\*/g, '<strong style="color:var(--text)">$1</strong>')
-              .replace(/`([^`]+)`/g, '<code style="background:var(--bg-code);border:1px solid var(--border);padding:1px 5px;border-radius:4px;font-size:11px;color:var(--smoke)">$1</code>')
-              /* Bullet lists — ember accent bar instead of purple */
-              .replace(/^- (.+)$/gm, '<div style="padding:3px 0 3px 12px;border-left:2px solid rgba(245,121,58,.35);margin:4px 0;color:var(--smoke)">$1</div>')
-              /* Numbered lists — ember number instead of purple */
-              .replace(/^(\\d+)\\. (.+)$/gm, '<div style="display:flex;gap:8px;padding:3px 0;margin:4px 0"><span style="color:var(--ember);font-weight:600;font-size:11px;min-width:18px">$1.</span><span style="color:var(--smoke)">$2</span></div>')
-              /* Inline arrows — keep readable */
-              .replace(/\\u2192|\\u2194|\\->/g, '<span style="color:var(--ember)">&rarr;</span>')
-              .replace(/\\n\\n/g, '<br>')
-              .replace(/\\n/g, ' ');
-          }
-
           /* ───────────────────────── Node Detail Panel ───────────────────────── */
 
           function showNodeDetail(id) {
@@ -1214,57 +1185,11 @@ module Docit
             return '<div class="detail-section"><div class="detail-section-title">Responses</div>' + rows + '</div>';
           }
 
-          /* Render the AI section explanation into the panel. The
-             undocumented-endpoint warning is handled by the caller. */
-          function showSectionExplain(controllerId) {
-            var ids = sectionActionIds(controllerId);
-            var controller = graph.nodes.find(function(n) { return n.id === controllerId; });
-            var sectionName = controller ? resourceName(controller.label).plural : "Section";
-
-            if (ids.length === 0) {
-              openDetailPanel('<div class="detail-kicker">Section</div><h2 class="detail-title">' + esc(sectionName) +
-                '</h2><div class="detail-error">No endpoints to explain in this section.</div>');
-              return;
-            }
-
-            openDetailPanel('<div class="detail-kicker">Section</div><h2 class="detail-title">' + esc(sectionName) + '</h2>' +
-              '<div class="detail-ai-head">' + lineIcon(ICON_SPARKLE) + ' How this section works</div>' +
-              '<div class="detail-loading">Generating explanation…</div>');
-
-            var url = insightsUrl + "?mode=section&node_ids=" + encodeURIComponent(ids.join(","));
-            fetch(url)
-              .then(function(r) { return r.json(); })
-              .then(function(data) {
-                if (data.error) throw new Error(data.error);
-                openDetailPanel('<div class="detail-kicker">Section</div><h2 class="detail-title">' + esc(sectionName) + '</h2>' +
-                  '<div class="detail-ai-head">' + lineIcon(ICON_SPARKLE) + ' How this section works</div>' +
-                  '<div class="detail-ai-body">' + formatMarkdown(data.insight) + '</div>');
-              })
-              .catch(function(err) {
-                openDetailPanel('<div class="detail-kicker">Section</div><h2 class="detail-title">' + esc(sectionName) + '</h2>' +
-                  '<div class="detail-error">Explanation unavailable: ' + esc(err.message) +
-                  '<br>Run <span class="mono">rails generate docit:ai_setup</span> to configure an AI provider.</div>');
-              });
-          }
-
-          /* One-time delegation on the docs content: section Explain + endpoint clicks. */
+          /* One-time delegation on the docs content: endpoint clicks. */
           (function bindDocsInteractions() {
             var content = $("stripe-content");
             if (!content) return;
             content.addEventListener("click", function(e) {
-              var sectionBtn = e.target.closest(".stripe-explain-btn");
-              if (sectionBtn) {
-                /* Gate: warn before spending tokens on a thinly-documented section. */
-                if (sectionBtn.dataset.fulldoc !== "1") {
-                  var ok = window.confirm(
-                    sectionBtn.dataset.undoc + " endpoint(s) in this section are undocumented.\\n\\n" +
-                    "The explanation may be weak and will use more tokens. For the best result, " +
-                    "document these endpoints first.\\n\\nGenerate anyway?");
-                  if (!ok) return;
-                }
-                showSectionExplain(sectionBtn.dataset.section);
-                return;
-              }
               /* Relation cards have their own behavior (jump to the diagram). */
               if (e.target.closest(".stripe-relation-card")) return;
               /* A click on an endpoint card (or its View details button) opens
@@ -1309,15 +1234,14 @@ module Docit
               if (actions.length === 0) return;
 
               const controllerAnchor = "controller-" + controller.id.replace(/:/g, "-");
-              
+
               sidebarHtml += '<div class="stripe-sidebar-group">';
               sidebarHtml += '<div class="stripe-sidebar-heading">' + esc(controller.label.replace("Controller", "")) + '</div>';
 
               var res = resourceName(controller.label);
 
-              /* Documentation coverage drives both the badge and the AI gate:
-                 a fully-documented section gives the model real input; a thin
-                 one yields a weak explanation and still costs tokens. */
+              /* Documentation coverage badge: how many of the section's
+                 endpoints carry a Docit doc-block. */
               var documentedCount = actions.filter(function(a) { return a.status === "documented"; }).length;
               var totalCount = actions.length;
               var fullyDocumented = documentedCount === totalCount;
@@ -1332,9 +1256,6 @@ module Docit
               contentHtml += '    <div class="stripe-controller-aside">';
               contentHtml += '      <span class="stripe-coverage" style="color:' + coverageColor + ';border-color:' + coverageColor + '40;background:' + coverageColor + '12">' +
                 documentedCount + '/' + totalCount + ' documented</span>';
-              contentHtml += '      <button class="stripe-explain-btn" type="button" ' +
-                'data-section="' + esc(controller.id) + '" data-fulldoc="' + (fullyDocumented ? "1" : "0") +
-                '" data-undoc="' + (totalCount - documentedCount) + '">Explain section</button>';
               contentHtml += '    </div>';
               contentHtml += '  </div>';
               contentHtml += '  <p class="stripe-controller-sub">' + actions.length + ' endpoint' + (actions.length === 1 ? '' : 's') +
@@ -1482,13 +1403,13 @@ module Docit
 
       def self.json_escape(json_string)
         json_string.to_s.gsub(/[&<>'\u2028\u2029]/, {
-          '&' => '\u0026',
-          '<' => '\u003c',
-          '>' => '\u003e',
-          "'" => '\u0027',
-          "\u2028" => '\u2028',
-          "\u2029" => '\u2029'
-        })
+                                "&" => '\u0026',
+                                "<" => '\u003c',
+                                ">" => '\u003e',
+                                "'" => '\u0027',
+                                "\u2028" => '\u2028',
+                                "\u2029" => '\u2029'
+                              })
       end
     end
   end

data/lib/docit/ui/system_styles.rb

@@ -68,10 +68,10 @@ module Docit
           button, input, select { font: inherit; }
 
           /* Inline icon alignment — SVG glyphs sit centered on the text baseline. */
-          .btn-icon, .tip-icon, .welcome-icon, .detail-ai-head svg {
+          .btn-icon, .tip-icon, .welcome-icon {
             display: inline-flex; align-items: center; justify-content: center;
           }
-          .btn-icon svg, .detail-ai-head svg { vertical-align: middle; }
+          .btn-icon svg { vertical-align: middle; }
 
           /* Shell */
           .system-shell { display: grid; grid-template-rows: auto 1fr; height: calc(100vh - 37px); min-height: 640px; }
@@ -394,17 +394,9 @@ module Docit
             font-size: 11px; font-weight: 700; padding: 4px 9px; border-radius: 999px;
             border: 1px solid; white-space: nowrap;
           }
-          .stripe-explain-btn {
-            display: inline-flex; align-items: center; gap: 6px; height: 32px; padding: 0 12px;
-            border: 1px solid rgba(124,77,219,.35); border-radius: 8px;
-            background: var(--bg-card); color: var(--dusk); font-size: 12px; font-weight: 600;
-            cursor: pointer; transition: background 120ms ease, border-color 120ms ease;
-          }
-          .stripe-explain-btn:hover { background: var(--bg-option-hover); border-color: var(--dusk); }
 
           /* ───────── Right-hand detail panel ─────────
-             Fills the third column: endpoint request/response on click, or the
-             AI section explanation from "Explain section". */
+             Fills the third column: endpoint request/response on click. */
           .stripe-detail {
             position: relative; border-left: 1px solid var(--border); background: var(--bg-panel);
             overflow-y: auto; height: 100%; min-height: 0;
@@ -477,14 +469,6 @@ module Docit
           .detail-response-head { display: flex; align-items: center; gap: 8px; margin-bottom: 3px; }
           .detail-response-desc { font-size: 12px; color: var(--smoke); line-height: 1.45; }
 
-          /* AI explanation inside the panel */
-          .detail-ai-head {
-            display: flex; align-items: center; gap: 8px; font-size: 12px; font-weight: 700;
-            color: var(--dusk); margin-bottom: 12px;
-          }
-          .detail-ai-body { font-size: 13px; line-height: 1.65; color: var(--smoke); }
-          .detail-ai-body strong { color: var(--text); }
-          .detail-loading { color: var(--haze); font-style: italic; font-size: 13px; }
           .detail-error { color: var(--warning); font-size: 13px; line-height: 1.5; }
 
           /* Slide-over drawer on narrow screens */

data/lib/docit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docit
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - S13G
@@ -41,8 +41,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TROUBLESHOOTING.md
 - app/controllers/docit/ui_controller.rb
 - config/routes.rb
+- docs/images/scalar_image.png
+- docs/images/swagger_image.png
 - lib/docit.rb
 - lib/docit/ai.rb
 - lib/docit/ai/anthropic_client.rb
@@ -56,7 +59,6 @@ files:
 - lib/docit/ai/openai_client.rb
 - lib/docit/ai/prompt_builder.rb
 - lib/docit/ai/scaffold_generator.rb
-- lib/docit/ai/system_insight_generator.rb
 - lib/docit/ai/tag_injector.rb
 - lib/docit/builders/parameter_builder.rb
 - lib/docit/builders/request_body_builder.rb

data/lib/docit/ai/system_insight_generator.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Docit
-  module Ai
-    class SystemInsightGenerator
-      # mode: :nodes  -> explain an arbitrary selection (diagram "AI Explain")
-      #       :section -> explain one resource and how its endpoints work together
-      def initialize(graph:, selected_node_ids: [], mode: :nodes)
-        @graph = graph
-        @selected_node_ids = selected_node_ids
-        @mode = mode
-      end
-
-      def generate
-        config = Configuration.load
-        Client.for(config).generate(prompt)
-      end
-
-      private
-
-      attr_reader :graph, :selected_node_ids, :mode
-
-      def prompt
-        mode == :section ? section_prompt : nodes_prompt
-      end
-
-      def nodes_prompt
-        <<~PROMPT
-          You are a senior engineer explaining a Rails system architecture to a developer. Keep your explanation extremely concise, professional, and clear. Avoid fluff, unnecessary details, or general tutorial information. Focus only on the provided components.
-
-          FORMAT YOUR RESPONSE EXACTLY LIKE THIS:
-
-          ## Overview
-          A 1-2 sentence plain-English summary of what this component/action does.
-
-          ## Data Flow
-          Show a simple, linear flow diagram using text and arrows (→). Keep it to 1 line if possible.
-          Example:
-            Client → GET /api/v1/users → UsersController#index → queries User model
-
-          ## Connections & Interactions
-          List only the direct, relevant relationships from the graph (max 3 bullets):
-          - **Component** (type): Action details/purpose.
-
-          Do not invent or assume anything outside of the provided graph. Keep the total response under 150 words.
-
-          ---
-
-          Selected node ids:
-          #{selected_node_ids.join("\n")}
-
-          Graph JSON:
-          #{JSON.pretty_generate(compact_graph)}
-        PROMPT
-      end
-
-      def section_prompt
-        <<~PROMPT
-          You are a senior engineer writing the introduction to a section of API documentation. The section covers ONE resource and all of its endpoints. Explain, for a developer new to this codebase, what the resource is for and how its endpoints work together as a workflow.
-
-          Use the documented summaries where available. Where an endpoint has no documentation, infer cautiously from its HTTP method and path, and do not fabricate behavior.
-
-          FORMAT YOUR RESPONSE EXACTLY LIKE THIS:
-
-          ## What this section does
-          1-2 sentences on the resource and its overall purpose.
-
-          ## How the endpoints work together
-          A short narrative (2-4 sentences) describing the typical flow across these endpoints — e.g. how a client lists, creates, then updates this resource. Reference endpoints by their HTTP method and path.
-
-          ## Notes
-          Up to 2 bullets on related models/services or anything a consumer must know. Omit this section if there is nothing concrete to say.
-
-          Do not invent endpoints, fields, or behavior not present in the graph. Keep the total response under 180 words.
-
-          ---
-
-          Endpoint node ids in this section:
-          #{selected_node_ids.join("\n")}
-
-          Graph JSON:
-          #{JSON.pretty_generate(compact_graph)}
-        PROMPT
-      end
-
-      def compact_graph
-        nodes = selected_nodes
-        node_ids = nodes.map { |node| node[:id] }
-
-        # Include edges where at least one end is in the selection
-        related_edges = graph[:edges].select do |edge|
-          node_ids.include?(edge[:source]) || node_ids.include?(edge[:target])
-        end
-
-        # Also include neighbor nodes (one hop away) for context
-        neighbor_ids = Set.new(node_ids)
-        related_edges.each do |edge|
-          neighbor_ids.add(edge[:source])
-          neighbor_ids.add(edge[:target])
-        end
-
-        neighbor_nodes = graph[:nodes].select { |node| neighbor_ids.include?(node[:id]) }
-
-        {
-          selected_nodes: nodes.map { |node| compact_hash(node, %i[id type label status file metadata]) },
-          context_nodes: (neighbor_nodes - nodes).map { |node| compact_hash(node, %i[id type label status]) },
-          edges: related_edges.map { |edge| compact_hash(edge, %i[source target type confidence evidence]) },
-          stats: graph[:stats]
-        }
-      end
-
-      def selected_nodes
-        return graph[:nodes] if selected_node_ids.empty?
-
-        graph[:nodes].select { |node| selected_node_ids.include?(node[:id]) }
-      end
-
-      def compact_hash(hash, keys)
-        keys.each_with_object({}) do |key, result|
-          result[key] = hash[key] if hash.key?(key)
-        end
-      end
-    end
-  end
-end