docs-kit 1.0.7 → 1.1.0

data/lib/docs_kit/brand_logo.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # The normalized brand mark for the shell chrome (config.brand_logo) and the
+  # landing hero (config.landing.logo). A site configures a Hash in exactly one
+  # of five forms; DocsUI::Logo renders the result:
+  #
+  #   { svg: "M0 0Z", viewbox: "0 0 24 24", label: "Acme" }   # one path-d (landing-compat)
+  #   { paths: ["M0 0Z", "M4 4Z"], viewbox: "…", label: "…" } # multi-path wordmark
+  #   { markup: "<svg …>…</svg>", label: "Acme" }             # raw SVG markup, embedded verbatim
+  #   { file: "app/assets/images/mark.svg", label: "Acme" }   # a .svg file, embedded inline
+  #   { src: "logo.png", alt: "Acme" }                        # an <img> (not theme-adaptive)
+  #
+  # The svg:/paths: forms render each `d` as an ordinary Phlex-escaped attribute.
+  # The markup:/file: forms embed SITE-AUTHORED markup verbatim (see DocsUI::Logo
+  # for the trust rationale); both are shape-checked here — the content must be an
+  # <svg> element — so a mis-pasted snippet fails loudly at config time, never as
+  # a silently broken (or script-bearing) header. Mixing forms, or giving none,
+  # is ambiguous config and raises. `label`/`alt` fall back to each other so
+  # either knob names the mark for assistive tech.
+  #
+  # A file: mark memoizes its content and re-reads on an mtime change (the
+  # Configuration#openapi_document posture), so editing the SVG in development
+  # shows up without a server restart.
+  class BrandLogo
+    # The config keys that each select a render form — exactly one must be given.
+    FORM_KEYS = %i[svg paths markup file src].freeze
+
+    # A loose "is this an <svg> element" shape check for the markup:/file: forms.
+    SVG_SHAPE = /\A\s*<svg[\s>]/i
+
+    DEFAULT_VIEWBOX = "0 0 24 24"
+
+    attr_reader :paths, :viewbox, :markup, :file, :src
+
+    # Coerce a config value (Hash with symbol or string keys, or an
+    # already-normalized BrandLogo) into a BrandLogo.
+    def self.from(logo)
+      return logo if logo.is_a?(self)
+
+      new(logo.to_h)
+    end
+
+    def initialize(attrs = {})
+      attrs = attrs.transform_keys(&:to_sym)
+      given = attrs.slice(*FORM_KEYS).compact
+      unless given.size == 1
+        raise ArgumentError,
+              "brand_logo takes exactly one of #{FORM_KEYS.inspect} (got #{given.keys.inspect})"
+      end
+
+      @viewbox = attrs[:viewbox] || DEFAULT_VIEWBOX
+      @label = attrs[:label]
+      @alt = attrs[:alt]
+      build_form(given.keys.first, attrs)
+    end
+
+    # The single path-d, for the landing-compat svg: shape (first of #paths).
+    def svg = paths&.first
+
+    def inline? = !paths.nil?
+    def markup? = !markup.nil?
+    def file? = !file.nil?
+    def image? = !src.nil?
+
+    # Whether the mark embeds site-authored markup verbatim (markup: or file:).
+    def embed? = markup? || file?
+
+    # The accessible name — label falls back to alt (and vice versa) so a site
+    # setting either names the mark; nil defers to the render-time brand fallback.
+    def label = @label || @alt
+    def alt = @alt || @label
+
+    # The markup to embed: the literal markup: string, or the file's content —
+    # memoized per mtime so a dev edit re-reads without a restart.
+    def svg_markup
+      return @markup if markup?
+
+      mtime = begin
+        @file.mtime
+      rescue StandardError
+        nil
+      end
+      return @file_content if defined?(@file_content) && @file_mtime == mtime
+
+      @file_mtime = mtime
+      @file_content = check_svg_shape!(@file.read, "file #{@file}")
+    end
+
+    private
+
+    # Store the one given form. file: primes #svg_markup immediately so a bad
+    # file fails at config time (boot), not on first render.
+    def build_form(form, attrs)
+      case form
+      when :svg, :paths then @paths = Array(attrs[:paths] || attrs[:svg]).map(&:to_s)
+      when :markup then @markup = check_svg_shape!(attrs[:markup].to_s, "markup")
+      when :src then @src = attrs[:src]
+      when :file
+        @file = resolve_file!(attrs[:file])
+        svg_markup
+      end
+    end
+
+    # Validate + resolve the file: form eagerly, so a bad path fails at config
+    # time (boot), not on first render. Relative paths resolve against Rails.root
+    # when Rails is loaded, else the process working directory.
+    def resolve_file!(file)
+      path = Pathname.new(file.to_s)
+      path = Rails.root.join(path) if path.relative? && defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      raise ArgumentError, "brand_logo file must be a .svg (got #{path.basename})" unless path.extname.casecmp?(".svg")
+      raise ArgumentError, "brand_logo file not found: #{path}" unless path.file?
+
+      path
+    end
+
+    # The markup:/file: shape guard — the content must BE an <svg> element.
+    def check_svg_shape!(content, source)
+      return content if content.match?(SVG_SHAPE)
+
+      raise ArgumentError, "brand_logo #{source} must be an <svg> element (got #{content[0, 40].inspect})"
+    end
+  end
+end

data/lib/docs_kit/configuration.rb

@@ -193,6 +193,39 @@ module DocsKit
     # sidebar, and page-masthead links). Read via #app_link, never @app_link.
     attr_writer :app_link
 
+    # The opt-in shell brand mark, rendered by BOTH the topbar and the sidebar
+    # header in place of the text #brand (which stays the accessible-name
+    # fallback). A Hash in exactly one of the DocsKit::BrandLogo forms —
+    # svg:/paths: (inline path-d, theme-adaptive via currentColor), markup:/file:
+    # (site-authored <svg> embedded verbatim), or src: (an <img>, NOT
+    # theme-adaptive) — or an already-built BrandLogo. Defaults to nil → the
+    # text brand renders and the chrome is byte-identical to before. Sibling of
+    # c.landing.logo, which is the landing-hero mark. Read via #brand_logo,
+    # never @brand_logo.
+    def brand_logo=(value)
+      @brand_logo = nil
+      @brand_logo_raw = value
+    end
+
+    # Where the topbar renders the brand: :always (the default — byte-compat),
+    # or :mobile_only, which hides it at the drawer-pinned breakpoint (lg:)
+    # where the sidebar brand is already visible, deduplicating the mark.
+    attr_reader :topbar_brand
+
+    # The topbar-brand placements. At lg: the sidebar (with its own brand) is
+    # pinned open, so :mobile_only drops the duplicate; :always keeps it.
+    TOPBAR_BRAND_MODES = %i[always mobile_only].freeze
+
+    def topbar_brand=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless TOPBAR_BRAND_MODES.include?(mode)
+        raise ArgumentError,
+              "topbar_brand must be one of #{TOPBAR_BRAND_MODES.inspect} (got #{value.inspect})"
+      end
+
+      @topbar_brand = mode
+    end
+
     # External links rendered in the topbar next to the theme switcher — a repo
     # link, a chat invite, a social profile. Each entry is a Hash
     # ({ href:, label:, icon: }) or a DocsKit::TopbarLink; #topbar_links
@@ -209,6 +242,27 @@ module DocsKit
     # #openapi_document (which memoizes + reloads on file change), never @openapi.
     attr_accessor :openapi
 
+    # The documentation versions this site serves — a list of Hashes
+    # ({ id:, label:, ref:, current:, noindex: }) or DocsKit::DocVersion objects;
+    # #versions normalizes them. Defaults to [] → versioning is off and the site
+    # is byte-identical to before. The `current` entry keeps serving unprefixed
+    # at /docs; every other entry serves a committed Markdown snapshot at
+    # /<id>/docs (see DocsKit::Snapshot). A version id must match v?\d+(\.\d+)*
+    # so the host's static version route constraint recognizes it. Read via
+    # #versions, never @versions.
+    attr_writer :versions
+
+    # The site's source repository root (e.g. "https://github.com/me/repo"),
+    # used for the GitHub compare link between two versions' refs
+    # (#compare_url). Defaults to nil → no compare link renders.
+    attr_accessor :repo_url
+
+    # Where committed version snapshots live. Defaults to nil, which the reader
+    # resolves to Rails.root/"docs_snapshots" under Rails (nil outside Rails —
+    # the standalone suite points at fixtures explicitly). Read via
+    # #snapshots_path, never @snapshots_path.
+    attr_writer :snapshots_path
+
     # The sentinel "no explicit nav" lambda. #nav_groups compares against this
     # identity to decide whether to derive the sidebar from #nav_registries.
     DEFAULT_NAV = -> { {} }
@@ -274,6 +328,12 @@ module DocsKit
       @app_link = nil
       @topbar_links = []
       @openapi = nil
+      @brand_logo = nil
+      @brand_logo_raw = nil
+      @topbar_brand = :always
+      @versions = []
+      @repo_url = nil
+      @snapshots_path = nil
     end
 
     # The normalized App Home link (a DocsKit::TopbarLink), or nil when unset —
@@ -284,6 +344,17 @@ module DocsKit
       DocsKit::TopbarLink.from(@app_link)
     end
 
+    # The normalized shell brand mark (a DocsKit::BrandLogo), or nil when unset.
+    # Memoized (and invalidated on reassignment) — unlike #app_link's rebuild-
+    # per-read, because a file: mark shape-checks and reads its SVG on build;
+    # per-render re-normalization would repeat that IO. A malformed value raises
+    # here, on first read — loud, never a silently broken header.
+    def brand_logo
+      return if @brand_logo_raw.nil?
+
+      @brand_logo ||= DocsKit::BrandLogo.from(@brand_logo_raw)
+    end
+
     # The normalized topbar links (DocsKit::TopbarLink list), in declaration
     # order. Each configured Hash/TopbarLink is coerced via TopbarLink.from, so
     # the Shell only ever sees value objects. Blank/nil config yields [].
@@ -291,6 +362,61 @@ module DocsKit
       Array(@topbar_links).map { |link| DocsKit::TopbarLink.from(link) }
     end
 
+    # The normalized version list (DocsKit::DocVersion list), in declaration
+    # order. Each configured Hash/DocVersion is coerced via DocVersion.from, so
+    # the switcher and the snapshot reader only ever see value objects.
+    # Blank/nil config yields [].
+    def versions
+      Array(@versions).map { |version| DocsKit::DocVersion.from(version) }
+    end
+
+    # The version serving unprefixed at /docs: the entry marked current: true,
+    # else the first configured entry, else nil (an unversioned site).
+    def current_version
+      versions.find(&:current?) || versions.first
+    end
+
+    # The configured version with this id, or nil when unknown (or nil id).
+    def version(id)
+      return if id.nil?
+
+      versions.find { |version| version.id.to_s == id.to_s }
+    end
+
+    # The version a request's :version param resolves to: the strict #version
+    # lookup, falling back to #current_version for an unknown or missing id —
+    # one rule shared by DocsKit::Controller#render_page and the gem's own
+    # controllers (DocsKit::Scoping), so a bad param degrades to the current
+    # docs instead of 500ing.
+    def resolve_version(id)
+      version(id) || current_version
+    end
+
+    # Whether the version chrome (switcher, llms.txt Versions block) renders.
+    # A single configured version is not worth a switcher, so this needs two —
+    # and an unconfigured site stays byte-identical to before.
+    def versioning_enabled?
+      versions.size > 1
+    end
+
+    # The resolved snapshots directory: the configured value verbatim, else
+    # Rails.root/"docs_snapshots" under Rails, else nil (no Rails, no default —
+    # the standalone suite passes explicit paths).
+    def snapshots_path
+      return @snapshots_path if @snapshots_path
+
+      Rails.root.join("docs_snapshots") if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+    end
+
+    # The GitHub compare URL between two versions' refs
+    # ("{repo_url}/compare/{from.ref}...{to.ref}"), or nil unless #repo_url and
+    # BOTH refs are present — absent value, absent link, never a broken one.
+    def compare_url(from, to)
+      return if repo_url.nil? || from&.ref.nil? || to&.ref.nil?
+
+      "#{repo_url.chomp('/')}/compare/#{from.ref}...#{to.ref}"
+    end
+
     # The SEO / social-share knobs (DocsKit::SeoConfig), read by DocsUI::MetaTags.
     # Lazily built and memoized so a `c.seo.description = ...` block mutates the
     # one instance the Shell later reads. A site that never touches it gets the
@@ -455,11 +581,17 @@ module DocsKit
 
     # The resolved nav Hash for this request. Always returns a Hash.
     #
-    # An explicit #nav lambda wins. Otherwise the sidebar derives from
-    # #nav_registries: each heading maps to its registry's .nav_items, and a
-    # heading whose pages are all unauthored (empty nav_items) is dropped so no
-    # empty group renders.
+    # An ARCHIVED version in DocsKit::Scope wins outright: the sidebar derives
+    # from that version's snapshot manifest (hrefs already version-prefixed), so
+    # an archived page never links into the live docs — even a site's explicit
+    # #nav lambda describes the live pages, not the frozen ones. With no scope
+    # (or the current version) nothing changes: an explicit #nav lambda wins,
+    # else the sidebar derives from #nav_registries — each heading maps to its
+    # registry's .nav_items, and a heading whose pages are all unauthored
+    # (empty nav_items) is dropped so no empty group renders.
     def nav_groups
+      scope_version = DocsKit::Scope.version
+      return DocsKit::Snapshot.for(scope_version, config: self).nav_groups if scope_version&.archived?
       return nav_groups_from_registries unless @nav_explicit
 
       result = @nav.respond_to?(:call) ? @nav.call : @nav

data/lib/docs_kit/controller.rb

@@ -19,10 +19,19 @@ module DocsKit
     # from the SAME render (DocsKit::MarkdownExport walks the rendered HTML). So
     # `GET /docs/x.md` is faithful GFM of exactly what `/docs/x` shows — the
     # author writes nothing extra, and the two never drift.
+    #
+    # The render runs inside the request's DocsKit::Scope (the version resolved
+    # from params[:version], falling back to the current version), so the
+    # sidebar/meta tags/enumeration all see the version the URL asked for.
+    # `render` renders synchronously inside the action, so this block wrapper is
+    # sufficient — no around_action, no host code changes. On an unversioned
+    # site the scope is nil: today's behavior exactly.
     def render_page(view)
-      return render_markdown(view) if markdown_request?
+      DocsKit::Scope.with(version: DocsKit.configuration.resolve_version(params[:version])) do
+        return render_markdown(view) if markdown_request?
 
-      render view, layout: false
+        render view, layout: false
+      end
     end
 
     private

data/lib/docs_kit/doc_version.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # One documentation version a site serves. Sites declare these in config as
+  # plain Hashes; #versions normalizes each into a DocVersion so the chrome and
+  # the AI surfaces stay value-object-driven (like DocsKit::TopbarLink):
+  #
+  #   c.versions = [
+  #     { id: "1.1", ref: "v1.1.0", current: true },
+  #     { id: "1.0", ref: "v1.0.0" },
+  #   ]
+  #
+  # #id is the URL segment (an archived version serves at "/#{id}/docs/...");
+  # #label is the switcher text (defaults to the id); #ref is the git ref backing
+  # the GitHub compare link (optional); #current marks the version serving
+  # unprefixed at /docs (exactly today's URLs); #noindex defaults to the inverse
+  # of #current — archived copies are noindex'd so search engines keep pointing
+  # at the current docs, overridable per version with `noindex: false`.
+  #
+  # Named DocVersion, not Version — lib/docs_kit/version.rb already owns that
+  # file slot and defines DocsKit::VERSION.
+  DocVersion = Data.define(:id, :label, :ref, :current, :noindex) do
+    def initialize(id:, label: nil, ref: nil, current: false, noindex: nil)
+      super(
+        id: id,
+        label: label || id.to_s,
+        ref: ref,
+        current: current,
+        noindex: noindex.nil? ? !current : noindex
+      )
+    end
+
+    # Build a DocVersion from a Hash (symbol- OR string-keyed, so a YAML/JSON
+    # config loads cleanly) or pass an existing DocVersion through unchanged.
+    def self.from(version)
+      return version if version.is_a?(self)
+
+      attrs = version.to_h.transform_keys(&:to_sym)
+      new(
+        id: attrs[:id],
+        label: attrs[:label],
+        ref: attrs[:ref],
+        current: attrs.fetch(:current, false),
+        noindex: attrs[:noindex]
+      )
+    end
+
+    def current? = !!current
+
+    def archived? = !current?
+
+    # The root URL segment this version contributes: "" for the current version
+    # (existing sites and their SEO untouched), "/#{id}" for an archived one.
+    # Stacks with the i18n locale prefix later ("/de/1.0/docs/...").
+    def path_prefix
+      current? ? "" : "/#{id}"
+    end
+  end
+end

data/lib/docs_kit/landing_config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "brand_logo"
+
 module DocsKit
   # The per-site landing-page knobs, read by DocsUI::Landing to render a marketing
   # home page (hero + feature grid + doc index) without a site hand-rolling one.
@@ -90,11 +92,11 @@ module DocsKit
       { code: attrs[:code].to_s, filename: attrs[:filename], lexer: (attrs[:lexer] || :shell).to_sym }
     end
 
-    # The hero logo as a normalized Logo value object, or nil when unset.
+    # The hero logo as a normalized DocsKit::BrandLogo, or nil when unset.
     def hero_logo
       return if @logo.nil?
 
-      Logo.from(@logo)
+      DocsKit::BrandLogo.from(@logo)
     end
 
     # One hero call-to-action button. `style` maps to a daisyUI btn variant
@@ -134,27 +136,9 @@ module DocsKit
       end
     end
 
-    # The hero brand logo — either an inline single-path SVG mark (`svg` = the
-    # `<path d>` data, `viewbox` = its viewBox) rendered with fill: currentColor so
-    # it adapts to the theme, OR an image (`src` = an asset path/URL, `alt` = its
-    # accessible name). `label` is the accessible name for the inline mark.
-    Logo = Data.define(:svg, :viewbox, :src, :alt, :label) do
-      def initialize(svg: nil, viewbox: "0 0 24 24", src: nil, alt: nil, label: nil)
-        super
-      end
-
-      def self.from(logo)
-        return logo if logo.is_a?(self)
-
-        attrs = logo.to_h.transform_keys(&:to_sym)
-        new(
-          svg: attrs[:svg], viewbox: attrs[:viewbox] || "0 0 24 24",
-          src: attrs[:src], alt: attrs[:alt], label: attrs[:label]
-        )
-      end
-
-      # An inline SVG mark (vs. an <img>). True when `svg` path data is present.
-      def inline? = !svg.to_s.empty?
-    end
+    # The hero brand logo shape now lives in DocsKit::BrandLogo (shared with the
+    # shell's config.brand_logo); the old nested name stays as an alias so any
+    # site referencing LandingConfig::Logo keeps working.
+    Logo = DocsKit::BrandLogo
   end
 end

data/lib/docs_kit/llms_text.rb

@@ -54,13 +54,40 @@ module DocsKit
       end
     end
 
-    # The authored pages across every registry, in config/registry order — each
-    # responds to #title / #href / #view_class. The controller renders these to
-    # Markdown for .full.
-    def pages(config)
+    # The authored pages for one version of the docs, in config/registry order —
+    # each responds to #title / #href / #view_class (render via .renderable_for).
+    # This is the ONE enumeration seam every AI surface funnels through, so
+    # making IT version-aware makes llms-full.txt, search, and MCP follow the
+    # request's version for free.
+    #
+    # version: nil resolves through DocsKit::Scope (set per request by the
+    # controllers), then config.current_version — so an unversioned site, or the
+    # current version, enumerates the live registries exactly as before. An
+    # ARCHIVED version enumerates its Markdown snapshot instead
+    # (DocsKit::Snapshot — every entry is authored by definition).
+    def pages(config, version: nil)
+      version ||= DocsKit::Scope.version || config.current_version
+      return snapshot_pages(config, version) if version&.archived?
+
       config.nav_registries.values.flat_map { |registry| registry.all.select(&:view_class) }
     end
 
+    # An archived version's pages, from its committed snapshot. Every entry has
+    # a view_class by construction; the select keeps the authored-pages contract
+    # symmetric with the live branch.
+    def snapshot_pages(config, version)
+      DocsKit::Snapshot.for(version, config: config).all.select(&:view_class)
+    end
+
+    # The Phlex renderable for a page returned by .pages: the page's own
+    # #renderable (Registry v2 Entry, Snapshot::Entry) with a backwards-
+    # compatible fallback to view_class.new for a site's custom `entries`-style
+    # registry class that predates #renderable. The ONE shim — the controllers
+    # and MCP tools all call this rather than repeating the respond_to? check.
+    def renderable_for(page)
+      page.respond_to?(:renderable) ? page.renderable : page.view_class.new
+    end
+
     # The llms-full.txt body: each [title, markdown] pair as `# {title}` + body,
     # separated by a `---` rule. Empty pairs → "".
     def full(_config, title_markdown_pairs)

data/lib/docs_kit/markdown_export/blocks.rb

@@ -20,8 +20,9 @@ module DocsKit
       # yield nothing (whitespace-only text nodes) are dropped so no stray blank
       # lines accumulate.
       def render(node)
-        node.children.filter_map { |child| block(child) }
-                     .reject(&:empty?)
+        node.children
+            .filter_map { |child| block(child) }
+            .reject(&:empty?)
             .join("\n\n")
       end
 

data/lib/docs_kit/mcp_tools.rb

@@ -87,8 +87,9 @@ module DocsKit
 
     # A page's GFM Markdown twin, rendered through the view context so url helpers
     # and relative-link absolutization resolve — the LlmsController#full seam.
+    # renderable_for is the live-or-snapshot shim (see LlmsText.renderable_for).
     def render_markdown(page, base_url:, view_context:)
-      MarkdownExport.new(page.view_class.new, view_context:, base_url:).to_md
+      MarkdownExport.new(LlmsText.renderable_for(page), view_context:, base_url:).to_md
     end
 
     # A DocsKit::SearchIndex over every authored page's twin — the same triples

data/lib/docs_kit/registry.rb

@@ -147,6 +147,13 @@ module DocsKit
 
         "#{@view_namespace}::#{@view_name}".safe_constantize
       end
+
+      # The renderable instance for this page (nil when unauthored) — the seam
+      # DocsKit::Snapshot::Entry shares, so consumers render live pages and
+      # snapshot pages identically (see LlmsText.renderable_for).
+      def renderable
+        view_class&.new
+      end
     end
   end
 end

data/lib/docs_kit/scope.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # The ONE request-scoped content scope: which documentation version (and,
+  # come i18n M2, which locale) the current render serves. Controllers set it
+  # around an action (DocsKit::Controller#render_page, DocsKit::Scoping); the
+  # config and the components consult it (Configuration#nav_groups,
+  # LlmsText.pages) — so "which content tree?" is asked once per request, not
+  # threaded through every component.
+  #
+  #   DocsKit::Scope.with(version: v) { ... }   # block-scoped, restores in an ensure
+  #   DocsKit::Scope.version                    # the DocVersion in scope, or nil
+  #   DocsKit::Scope.locale                     # reserved for i18n M2 — nil today
+  #   DocsKit::Scope.path_prefix                # "" or "/1.0"
+  #
+  # Backed by Thread.current[] — fiber-local in Ruby, which is what a fibered
+  # server wants — and deliberately Rails-free (NOT CurrentAttributes), so bare
+  # Phlex component specs can set a scope without booting Rails. An empty scope
+  # (no `with` in flight) reads as nil version / nil locale, which every
+  # consumer treats as "the current version" — today's behavior exactly.
+  module Scope
+    KEY = :docs_kit_scope
+
+    EMPTY = { version: nil, locale: nil }.freeze
+    private_constant :EMPTY
+
+    module_function
+
+    # Run the block with this version/locale in scope, restoring the previous
+    # scope on the way out — even when the block raises — so nothing leaks
+    # across requests sharing a thread.
+    def with(version: nil, locale: nil)
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = { version: version, locale: locale }
+      yield
+    ensure
+      Thread.current[KEY] = previous
+    end
+
+    # The DocsKit::DocVersion in scope, or nil (treated as the current version).
+    def version
+      current[:version]
+    end
+
+    # Reserved for i18n M2 — always nil until the locale axis is wired.
+    def locale
+      current[:locale]
+    end
+
+    # The root URL prefix the in-scope version contributes ("" when none/current).
+    def path_prefix
+      version&.path_prefix || ""
+    end
+
+    def current
+      Thread.current[KEY] || EMPTY
+    end
+  end
+end

data/lib/docs_kit/scoping.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # Wraps a controller's actions in the request's DocsKit::Scope, so everything
+  # rendered or enumerated during the action (Configuration#nav_groups,
+  # LlmsText.pages, the search index) sees the same version the URL asked for.
+  # Included by the gem's own controllers (Llms, Search, Mcp); a host's docs
+  # controller gets the same behavior from DocsKit::Controller#render_page's own
+  # wrapper instead — including this module there would around_action every host
+  # action, which is not docs-kit's call to make.
+  #
+  # A plain module with an included hook, not an ActiveSupport::Concern — it has
+  # no dependency chain and stays loadable in the Rails-free suite.
+  module Scoping
+    def self.included(base)
+      base.around_action :docs_scope
+    end
+
+    private
+
+    # The requested version (params[:version], falling back to the current
+    # version — an unknown id degrades, never 500s) held in scope for the whole
+    # action. nil on an unversioned site: today's behavior exactly.
+    def docs_scope(&)
+      DocsKit::Scope.with(version: DocsKit.configuration.resolve_version(params[:version]), &)
+    end
+  end
+end

data/lib/docs_kit/snapshot/entry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DocsKit
+  class Snapshot
+    # One snapshot page — the duck type of DocsKit::Registry::Entry (#slug /
+    # #title / #group / #icon / #href / #view_class / #renderable), so the
+    # enumeration seam (LlmsText.pages) and its consumers treat a frozen
+    # Markdown page exactly like a live Ruby one. #view_class is the truthy
+    # DocsUI::ArchivedPage constant, so the `select(&:view_class)` authored-page
+    # filter passes unchanged.
+    class Entry
+      attr_reader :slug, :title, :group, :icon, :file, :digest, :href
+
+      def initialize(attrs, version:, root:, registry_prefix:)
+        @slug = attrs["slug"]
+        @title = attrs["title"]
+        @group = attrs["group"]
+        @icon = attrs["icon"]
+        @file = attrs["file"]
+        @digest = attrs["digest"]
+        @root = root
+        @href = "#{version.path_prefix}#{registry_prefix}/#{@slug}"
+      end
+
+      # The renderer for every archived page. Truthy (never nil): a snapshot
+      # page is by definition authored — its content is the committed .md file.
+      def view_class
+        DocsUI::ArchivedPage
+      end
+
+      # The renderable the controllers hand to Phlex — an ArchivedPage carrying
+      # this entry, where a live Registry::Entry builds `view_class.new`.
+      def renderable
+        DocsUI::ArchivedPage.new(entry: self)
+      end
+
+      # The raw Markdown body from the snapshot file. A missing/unreadable file
+      # degrades to "" — the page renders empty rather than 500ing.
+      def markdown
+        return "" if @root.nil? || @file.nil?
+
+        @root.join(@file).read
+      rescue SystemCallError
+        ""
+      end
+    end
+  end
+end