docs-kit 1.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78cf5f2d5a4636b8b0c603f3d3b238aeb68c100fd0133edb16d52ce56ade4c39
-  data.tar.gz: 50acc90365594b546ba40887c976eb6f7c6e1eca7389b834c6793cd0490bbfb9
+  metadata.gz: b53c8fcfcdc8d5053f9019ea56edc5a1b4fce1a8760a220eb19c76a297e72d53
+  data.tar.gz: 4289ad366b8462a9617db0e696250b717c21af1a30a97126367c370452156e1d
 SHA512:
-  metadata.gz: b650c98a593eda398bafde41a07ed5ad01325d5392b113a8cfebedc06bb71519e139f846b8e6e259c106c8b23a64a2af4c9a0ab5ab1efd1b2b524764be72fa07
-  data.tar.gz: 29c352545d1ffcd4ba93461b2df5582663b79d86db835866fc6b2d543018d5d2e0034e43f24f2f67d0ebd953b89e65788a276484901c71b693fe95040668b8ad
+  metadata.gz: 80f49ed3f55338303fe09ebed720679c440eaadb02a99b112b312dfebafa70b081ccbf3622f20a7a0a6b6f48771969528746465377bda9961b62ce6cf9410521
+  data.tar.gz: 3dc20bc085a7baa55b0c64098931f03d00553b26e477a606ce1fe878850d96058992cd7ef3e4cbc59bc67c1ea07eb9be26219f2d1c5f7b83a04eb22e82737c47

data/README.md

@@ -1,14 +1,14 @@
 # docs-kit
 
-[![CI](https://github.com/mhenrixon/docs-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/mhenrixon/docs-kit/actions/workflows/ci.yml)
+[![CI](https://github.com/zoolutions/docs-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/zoolutions/docs-kit/actions/workflows/ci.yml)
 
 Shared [Phlex](https://www.phlex.fun) chrome for documentation sites built on
 [daisyUI](https://daisyui.com). Extract the shell, sidebar, code blocks, theme
 switcher, and page kit into one gem so multiple docs sites look identical and are
 maintained in one place.
 
-Reactive demos ([phlex-reactive](https://github.com/mhenrixon/phlex-reactive))
-and Postgres-SSE transport ([pgbus](https://github.com/mhenrixon/pgbus)) are
+Reactive demos ([phlex-reactive](https://github.com/zoolutions/phlex-reactive))
+and Postgres-SSE transport ([pgbus](https://github.com/zoolutions/pgbus)) are
 **optional, runtime-detected** add-ons — docs-kit does not depend on them.
 
 ## What you get
@@ -137,7 +137,7 @@ fronts Puma with Thruster (`CMD ["./bin/thrust", "./bin/rails", "server"]`) for
 HTTP caching, compression, and X-Sendfile — and the generator scaffolds the
 `bin/thrust` binstub if the app lacks one, since the exec-form CMD needs the
 file to exist in the image. Thruster listens on the routed port
-(`HTTP_PORT=3000` — Kamal's `app_port`) and proxies to Puma on `TARGET_PORT=3001`.
+(`HTTP_PORT=3000` — dash's `app_port`) and proxies to Puma on `TARGET_PORT=3001`.
 Without thruster in the *production* bundle (absent, or only in a
 development/test group that `BUNDLE_WITHOUT` excludes) the CMD falls back to
 plain `rails server` — never a thrust CMD that would crash at boot.
@@ -701,7 +701,7 @@ claude mcp add --transport http docs https://your-docs.example/mcp
 
 and can ask Claude to search or read your docs, which now appear as tools. The
 JSON-RPC is stateless (each `POST` is independent — no SSE session), so it works
-behind the existing Kamal/Cloudflare deploy unchanged; `GET`/`DELETE` return
+behind the existing dash/Cloudflare deploy unchanged; `GET`/`DELETE` return
 `405`. When enabled, `/llms.txt` grows a final `## MCP` line advertising the
 endpoint so agents discover it.
 
@@ -844,7 +844,7 @@ back to a spec.
 
 ```bash
 docs-kit new my-docs                       # → a complete, deployable docs app
-docs-kit new my-docs --image mhenrixon/my-repo --service my-repo
+docs-kit new my-docs --image zoolutions/my-repo --service my-repo
 ```
 
 `docs-kit new` runs `rails new` (propshaft + importmap + turbo/stimulus, no DB)
@@ -854,7 +854,7 @@ and applies docs-kit's application template, which:
 - runs `rails g docs_kit:install` (initializers, controllers, a Doc registry, a
   sample guide page, the Bun/Tailwind build, the docs-nav Stimulus wiring),
 - syncs the lucide icons and builds the CSS,
-- scaffolds Kamal (`config/deploy.yml`, `.kamal/secrets`, an optimized
+- scaffolds dash (`config/deploy.yml`, `.dash/secrets`, an optimized
   multi-stage `Dockerfile` + a `.dockerignore`) and a thin
   `.github/workflows/deploy-docs.yml` that calls the reusable workflow.
 
@@ -905,7 +905,7 @@ group. Then `bundle exec rubocop` runs the docs-kit cops.
 The build + deploy is defined **once** in this gem's reusable workflow
 (`.github/workflows/deploy.yml`). `docs-kit new` scaffolds the caller for you; to
 wire it by hand a site adds five small things and it deploys to the
-oss-infrastructure server (Kamal + GHCR + Cloudflare Tunnel).
+oss-infrastructure server (dash + GHCR + Cloudflare Tunnel).
 
 **1. A thin caller** — `.github/workflows/deploy-docs.yml`:
 
@@ -916,46 +916,73 @@ on:
   workflow_dispatch:
 jobs:
   deploy:
-    uses: mhenrixon/docs-kit/.github/workflows/deploy.yml@main
+    uses: zoolutions/docs-kit/.github/workflows/deploy.yml@main
     with:
-      image: mhenrixon/<repo>     # OWNER/REPO — see naming note below
+      image: zoolutions/<repo>     # OWNER/REPO — see naming note below
       service: <repo>
     secrets: inherit
 ```
 
-**2. `docs/config/deploy.yml`** — `service:` and `image:` MUST match the caller:
+**2. `docs/config/deploy.yml`** — `service:` and `image:` MUST match the caller
+(the full file `docs-kit new` writes is in `lib/docs_kit/templates/new_site.rb`;
+`dash docs proxy` documents every key):
 
 ```yaml
 service: <repo>
-image: mhenrixon/<repo>
-registry: { server: ghcr.io, username: mhenrixon, password: [KAMAL_REGISTRY_PASSWORD] }
+image: zoolutions/<repo>
+minimum_version: 4.0.0        # dash 4: dash-proxy identity + in-place host migration
+retain_containers: 2
+error_pages_path: public      # 502/503/504.html served during a deploy gap
+registry: { server: ghcr.io, username: mhenrixon, password: [DASH_REGISTRY_PASSWORD] }
 builder: { arch: amd64, context: .., dockerfile: Dockerfile }   # repo root = build context
-proxy:   { host: <%= ENV["DEPLOY_DOMAIN"] %>, app_port: 3000, ssl: false, healthcheck: { path: /up } }
 servers: { web: { hosts: [<%= ENV["DEPLOY_HOST"] %>] } }
 ssh:     { user: oss }
+proxy:
+  host: <%= ENV["DEPLOY_DOMAIN"] %>
+  app_port: 3000
+  ssl: false                  # TLS terminates at Cloudflare
+  healthcheck: { path: /up, interval: 5, timeout: 30 }
+  compress: true              # zstd/br/gzip at the edge
+  cache: { enabled: true, max_ttl: 300 }   # stores `Cache-Control: public` responses (assets, /llms*.txt)
+  headers: { response: { set: { X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin }, remove: [Server, X-Powered-By] } }
+  intercept_errors: [502, 503, 504]
+  exclude_metrics_paths: [/up]
 ```
 
+Deliberately **not** set: `proxy.run` (`port_holder`, `log_format`, …) is
+host-wide — every docs site on the shared host boots the same proxy, and a
+`run:` block that differs between them makes each alternate deploy reboot it.
+`rate_limit`/`deny_ips` need `client_ip.trusted_proxies` pinned to the tunnel's
+address to key on visitors rather than on cloudflared; add them per site once
+that address is known.
+
 **3. `docs/Dockerfile`** — end the final stage with the matching label:
 
 ```dockerfile
 LABEL service="<repo>"
 ```
 
-**4. `docs/.kamal/secrets`** — `KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD`.
+**4. `docs/.dash/secrets`** — `DASH_REGISTRY_PASSWORD=$DASH_REGISTRY_PASSWORD`.
 
 **5. GitHub** — a `docs` environment with secrets `SSH_PRIVATE_KEY`,
 `DEPLOY_HOST`, `DEPLOY_DOMAIN`. (The registry password is the auto-provided
 `GITHUB_TOKEN` — no PAT.)
 
 > **Naming — use the repo name, not `<repo>-docs`.** `image`/`service` must be
-> the calling repo's `OWNER/REPO`. Pushing `ghcr.io/mhenrixon/<repo>` from the
+> the calling repo's `OWNER/REPO`. Pushing `ghcr.io/zoolutions/<repo>` from the
 > repo's own Actions run auto-links the package to the repo, so `GITHUB_TOKEN`
 > can both push (build job) and pull (deploy) it. A different name becomes an
 > unlinked user-scoped package `GITHUB_TOKEN` can't pull → the deploy fails.
 
-**First deploy per host:** run `kamal setup` (or `bin/deploy setup`) once to boot
-any accessories (e.g. a Postgres accessory); the release workflow runs plain
-`kamal deploy`, which doesn't boot accessories.
+**First deploy per host:** run `dash setup` (or `bin/deploy setup`) once to boot
+any accessories (e.g. a Postgres accessory); the release workflow runs
+`dash doctor` (a pre-flight of host, registry, proxy, ports and readiness gates)
+and then plain `dash deploy`, which doesn't boot accessories.
+
+**Upgrading a host to dash 4:** the first 4.x deploy renames the proxy
+(`kamal-proxy` → `dash-proxy`, network `kamal` → `dash`, config volume copied)
+and costs one short outage on that host while ports 80/443 change hands. It is
+idempotent and shared by every site on the host — whichever deploys first pays it.
 
 ## CSS — the canonical build
 
@@ -1079,7 +1106,7 @@ them:
    → your profile → *Trusted Publishers* → *Create*, add a **pending** publisher
    (works for a gem not yet pushed) with:
    - Gem name: `docs-kit`
-   - Repository: `mhenrixon/docs-kit`
+   - Repository: `zoolutions/docs-kit`
    - Workflow filename: `release.yml`
    - Environment: `rubygems`
 2. **GitHub `rubygems` environment.** Repo *Settings → Environments → New

data/app/components/docs_ui/archived_page.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders one page of an ARCHIVED documentation version — a frozen Markdown
+  # body (DocsKit::Snapshot::Entry) through today's live chrome, so archived
+  # docs get every future Shell/Sidebar/Code fix for free. The live counterpart
+  # is DocsUI::Page; this mirrors its shape with the content coming from the
+  # snapshot file instead of an authored #content method.
+  #
+  # Every kwarg defaults, so even a naive `entry.view_class.new` (a custom
+  # registry predating #renderable) renders an empty page rather than raising.
+  #
+  # NOTE (issue #61 phase 4): the "you are viewing the 1.0 docs" banner with a
+  # link to the current equivalent lands with the version switcher, not here.
+  #
+  # Deliberately does NOT include Phlex::Rails::Helpers::Routes/Request — their
+  # bodies run Rails.* at class load, which would make this class (and
+  # everything referencing it, like Snapshot::Entry#view_class) unloadable in a
+  # Rails-free render. Nothing here needs a request.
+  class ArchivedPage < Phlex::HTML
+    include DocsUI
+
+    def initialize(entry: nil)
+      @entry = entry
+    end
+
+    def view_template
+      render DocsUI::Shell.new(title: @entry&.title) { body }
+    end
+
+    # The masthead + Markdown body — separated from the Shell wrapper so it can
+    # render (and be specced) without a Rails view context, the same seam as
+    # Shell's own topbar/theme-script specs.
+    def body
+      render DocsUI::Header.new(@entry.title) if @entry&.title
+      render DocsUI::Markdown.new(markdown_source) unless markdown_source.empty?
+    end
+
+    private
+
+    def markdown_source
+      @markdown_source ||= @entry ? @entry.markdown.to_s : ""
+    end
+  end
+end

data/app/components/docs_ui/brand_mark.rb

@@ -19,7 +19,7 @@ module DocsUI
     # token => official Simple-Icons path data (viewBox 0 0 24 24, fill rule
     # nonzero). Sourced verbatim from simpleicons.org; each is a single <path d>.
     # The path strings are inherently one long line each — never reflow them.
-    # rubocop:disable Layout/LineLength
+    # rubocop:disable-next Layout/LineLength
     BRANDS = {
       github: "M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12",
       gitlab: "m23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z",
@@ -36,7 +36,6 @@ module DocsUI
       reddit: "M12 0C5.373 0 0 5.373 0 12c0 3.314 1.343 6.314 3.515 8.485l-2.286 2.286C.775 23.225 1.097 24 1.738 24H12c6.627 0 12-5.373 12-12S18.627 0 12 0Zm4.388 3.199c1.104 0 1.999.895 1.999 1.999 0 1.105-.895 2-1.999 2-.946 0-1.739-.657-1.947-1.539v.002c-1.147.162-2.032 1.15-2.032 2.341v.007c1.776.067 3.4.567 4.686 1.363.473-.363 1.064-.58 1.707-.58 1.547 0 2.802 1.254 2.802 2.802 0 1.117-.655 2.081-1.601 2.531-.088 3.256-3.637 5.876-7.997 5.876-4.361 0-7.905-2.617-7.998-5.87-.954-.447-1.614-1.415-1.614-2.538 0-1.548 1.255-2.802 2.803-2.802.645 0 1.239.218 1.712.585 1.275-.79 2.881-1.291 4.64-1.365v-.01c0-1.663 1.263-3.034 2.88-3.207.188-.911.993-1.595 1.959-1.595Zm-8.085 8.376c-.784 0-1.459.78-1.506 1.797-.047 1.016.64 1.429 1.426 1.429.786 0 1.371-.369 1.418-1.385.047-1.017-.553-1.841-1.338-1.841Zm7.406 0c-.786 0-1.385.824-1.338 1.841.047 1.017.634 1.385 1.418 1.385.785 0 1.473-.413 1.426-1.429-.046-1.017-.721-1.797-1.506-1.797Zm-3.703 4.013c-.974 0-1.907.048-2.77.135-.147.015-.241.168-.183.305.483 1.154 1.622 1.964 2.953 1.964 1.33 0 2.47-.81 2.953-1.964.057-.137-.037-.29-.184-.305-.863-.087-1.795-.135-2.769-.135Z",
       stackoverflow: "M15.725 0l-1.72 1.277 6.39 8.588 1.716-1.277L15.725 0zm-3.94 3.418l-1.369 1.644 8.225 6.85 1.369-1.644-8.225-6.85zm-3.15 4.465l-.905 1.94 9.702 4.517.904-1.94-9.701-4.517zm-1.85 4.86l-.44 2.093 10.473 2.201.44-2.092-10.473-2.203zM1.89 15.47V24h19.19v-8.53h-2.133v6.397H4.021v-6.396H1.89zm4.265 2.133v2.13h10.66v-2.13H6.154Z"
     }.freeze
-    # rubocop:enable Layout/LineLength
 
     # True when `token` names a shipped brand mark (symbol or string), false for a
     # lucide name, nil, or a blank string. The Shell uses this to decide whether a

data/app/controllers/docs_kit/llms_controller.rb

@@ -29,6 +29,11 @@ module DocsKit
     # GET-only, sessionless, public text endpoints (no token to verify).
     protect_from_forgery with: :null_session
 
+    # Every action runs in the request's version scope (params[:version] on the
+    # version-prefixed routes, else the current version), so the enumeration
+    # below serves the version the URL asked for.
+    include DocsKit::Scoping
+
     def index
       body = DocsKit::LlmsText.index(docs_config, base_url: request.base_url)
       render_text(body) if stale_llms?(body)
@@ -67,9 +72,11 @@ module DocsKit
     # A page's Markdown twin, rendered through this controller's view context so
     # url helpers/CSRF resolve and relative links absolutize to portable URLs —
     # the same path DocsKit::Controller#render_page takes for a `.md` request.
+    # renderable_for is the live-or-snapshot shim (a snapshot entry renders an
+    # ArchivedPage carrying its frozen Markdown).
     def render_page_markdown(page)
       DocsKit::MarkdownExport.new(
-        page.view_class.new, view_context:, base_url: request.base_url
+        DocsKit::LlmsText.renderable_for(page), view_context:, base_url: request.base_url
       ).to_md
     end
   end

data/app/controllers/docs_kit/mcp_controller.rb

@@ -15,7 +15,7 @@ module DocsKit
   # DocsKit::McpServer / DocsKit::McpTools.
   #
   # Stateless JSON-RPC: each POST is independent (no SSE session), so it works
-  # behind the existing Kamal/Cloudflare deploy unchanged. #create delegates the
+  # behind the existing dash/Cloudflare deploy unchanged. #create delegates the
   # whole protocol to DocsKit::McpServer#handle_json — the SDK parses the request,
   # dispatches the tool, and serializes the response (including JSON-RPC errors),
   # so the controller never hand-rolls the protocol.
@@ -31,6 +31,10 @@ module DocsKit
     # protection outright.
     skip_forgery_protection
 
+    # MCP tool calls run in the request's version scope; the version-aware tool
+    # arguments (issue #61 phase 6) layer per-call resolution on top of this.
+    include DocsKit::Scoping
+
     def create
       return head(:not_found) unless docs_config.mcp_enabled?
 

data/app/controllers/docs_kit/search_controller.rb

@@ -28,6 +28,11 @@ module DocsKit
     # public endpoint.
     protect_from_forgery with: :null_session
 
+    # Search follows the request's version: /1.0/docs/search searches the 1.0
+    # snapshot, /docs/search searches current — the scope swaps the enumeration
+    # source underneath DocsKit::LlmsText.pages.
+    include DocsKit::Scoping
+
     def index
       hits = search_index.search(query)
 
@@ -53,7 +58,7 @@ module DocsKit
     def search_index
       triples = DocsKit::LlmsText.pages(docs_config).map do |page|
         markdown = DocsKit::MarkdownExport.new(
-          page.view_class.new, view_context:, base_url: request.base_url
+          DocsKit::LlmsText.renderable_for(page), view_context:, base_url: request.base_url
         ).to_md
         [page.title, page.href, markdown]
       end

data/exe/docs-kit

@@ -4,11 +4,11 @@
 # docs-kit CLI. One command scaffolds a complete, deployable docs site:
 #
 #   docs-kit new my-docs
-#   docs-kit new my-docs --image mhenrixon/my-repo --service my-repo
+#   docs-kit new my-docs --image zoolutions/my-repo --service my-repo
 #
 # It runs `rails new` with the right minimal flags and applies docs-kit's
 # application template (lib/docs_kit/templates/new_site.rb), which adds the gem,
-# runs `docs_kit:install`, syncs icons, builds the CSS, and scaffolds Kamal +
+# runs `docs_kit:install`, syncs icons, builds the CSS, and scaffolds dash +
 # the reusable deploy workflow.
 
 require "optparse"
@@ -25,9 +25,9 @@ unless command == "new"
       docs-kit new NAME [--image OWNER/REPO] [--service NAME] [--gem-source SRC]
 
     Options:
-      --image     GHCR image (default mhenrixon/NAME) — use OWNER/REPO for the
+      --image     GHCR image (default zoolutions/NAME) — use OWNER/REPO for the
                   repo-linked package so GITHUB_TOKEN can push+pull it.
-      --service   Kamal service name (default NAME).
+      --service   dash service name (default NAME).
       --gem-source  How to depend on docs-kit: 'released' (default),
                   'path:PATH', or 'github:OWNER/REPO'.
   USAGE
@@ -58,7 +58,7 @@ gem_source =
 
 env = {
   "DOCS_KIT_GEM_SOURCE" => gem_source,
-  "DOCS_KIT_IMAGE" => opts[:image] || "mhenrixon/#{name}",
+  "DOCS_KIT_IMAGE" => opts[:image] || "zoolutions/#{name}",
   "DOCS_KIT_SERVICE" => opts[:service] || name
 }
 

data/lib/docs_kit/configuration.rb

@@ -242,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 = -> { {} }
@@ -310,6 +331,9 @@ module DocsKit
       @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 —
@@ -338,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
@@ -502,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/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

data/lib/docs_kit/snapshot.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module DocsKit
+  # Reads a committed Markdown snapshot of one documentation version back as the
+  # registry duck type the rest of the kit already speaks (#all / #from_slug /
+  # #nav_items), so an archived version renders through TODAY's chrome — only
+  # the content is frozen.
+  #
+  # A snapshot lives at <config.snapshots_path>/<version id>/: a manifest.json
+  # describing the nav structure (see the schema in the snapshot task) plus one
+  # .md file per page, written by the host-run `bin/rails docs_kit:snapshot[id]`
+  # task at release time.
+  #
+  # A missing directory or unreadable manifest degrades to an EMPTY snapshot
+  # (no pages) — a version configured before its snapshot is written must never
+  # take the site down. The install generator's --sync report warns about the
+  # drift instead.
+  class Snapshot
+    # The manifest format this reader understands; the writer stamps it so a
+    # future format change is detectable rather than silently misread.
+    SCHEMA = 1
+
+    class << self
+      # The snapshot for this version, memoized per [version id, directory] and
+      # invalidated when manifest.json's mtime changes — the same
+      # reload-on-change posture as Configuration#openapi_document, so editing
+      # a snapshot in development is picked up without a server restart.
+      def for(version, config: DocsKit.configuration)
+        version = DocVersion.from(version)
+        root = root_for(version, config)
+        mtime = manifest_mtime(root)
+        key = [version.id.to_s, root.to_s]
+
+        @cache ||= {}
+        cached = @cache[key]
+        return cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
+
+        new(version: version, root: root).tap do |snapshot|
+          @cache[key] = { snapshot: snapshot, mtime: mtime }
+        end
+      end
+
+      def reset_cache!
+        @cache = {}
+      end
+
+      private
+
+      # <snapshots_path>/<id>, or nil when no snapshots path resolves (no
+      # config, no Rails) — which reads back as an empty snapshot.
+      def root_for(version, config)
+        base = config.snapshots_path
+        return if base.nil?
+
+        Pathname.new(base).join(version.id.to_s)
+      end
+
+      def manifest_mtime(root)
+        return if root.nil?
+
+        path = root.join("manifest.json")
+        path.file? ? path.mtime : nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    attr_reader :version, :root
+
+    def initialize(version:, root:)
+      @version = version
+      @root = root
+      @manifest = read_manifest
+    end
+
+    # Every snapshot page across the manifest's registries, in manifest order —
+    # each a Snapshot::Entry quacking like a Registry::Entry.
+    def all
+      registries.flat_map { |registry| registry.fetch(:entries) }
+    end
+
+    def from_slug(slug)
+      all.find { |entry| entry.slug.to_s == slug.to_s }
+    end
+
+    # { group => [NavItem] }, the Registry.nav_items shape — hrefs already carry
+    # the version prefix, so the Sidebar's strict path == href active-matching
+    # works unchanged.
+    def nav_items
+      nav_items_for(all)
+    end
+
+    # { heading => { group => [NavItem] } }, the Configuration#nav_groups shape,
+    # from the manifest's per-registry headings — a heading with no pages is
+    # dropped so the sidebar never shows an empty group.
+    def nav_groups
+      registries.each_with_object({}) do |registry, acc|
+        items = nav_items_for(registry.fetch(:entries))
+        acc[registry.fetch(:heading)] = items unless items.empty?
+      end
+    end
+
+    # The version-prefixed docs prefix (e.g. "/1.0/docs").
+    def path_prefix
+      "#{version.path_prefix}/docs"
+    end
+
+    # The raw Markdown body of the page with this slug, or nil when unknown.
+    def markdown_for(slug)
+      from_slug(slug)&.markdown
+    end
+
+    private
+
+    # The manifest's registries as { heading:, entries: [Snapshot::Entry] }.
+    def registries
+      @registries ||= Array(@manifest && @manifest["registries"]).map do |registry|
+        prefix = registry["path_prefix"] || "/docs"
+        {
+          heading: registry["heading"],
+          entries: Array(registry["pages"]).map do |attrs|
+            Entry.new(attrs, version: version, root: root, registry_prefix: prefix)
+          end
+        }
+      end
+    end
+
+    def nav_items_for(entries)
+      entries.group_by(&:group).transform_values do |grouped|
+        grouped.map { |entry| NavItem.new(href: entry.href, label: entry.title, icon: entry.icon) }
+      end
+    end
+
+    # The parsed manifest Hash, or nil (→ empty snapshot) when the directory or
+    # manifest is missing/unreadable — degrade, never raise (the site must stay
+    # up with a version configured before its snapshot exists).
+    def read_manifest
+      return if root.nil?
+
+      path = root.join("manifest.json")
+      return unless path.file?
+
+      JSON.parse(path.read)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/docs_kit/templates/new_site.rb

@@ -14,16 +14,16 @@ require "securerandom"
 #   * adds docs-kit + its runtime deps to the Gemfile,
 #   * runs `docs_kit:install` (all the Ruby/CSS/Stimulus wiring),
 #   * syncs the lucide icon set and builds the CSS,
-#   * scaffolds a deployable Kamal setup that calls docs-kit's reusable workflow.
+#   * scaffolds a deployable dash setup that calls docs-kit's reusable workflow.
 #
 # The generated app is a complete, deployable standalone docs site.
 
 # --- config the template reads ------------------------------------------------
 # DOCS_KIT_GEM_SOURCE lets the dogfood site (docs-kit/docs) depend on the gem via
 # path: ".." while a real new site depends on the released gem. Default: rubygems.
-gem_source = ENV.fetch("DOCS_KIT_GEM_SOURCE", "") # e.g. 'path: "..", ' or 'github: "mhenrixon/docs-kit", '
+gem_source = ENV.fetch("DOCS_KIT_GEM_SOURCE", "") # e.g. 'path: "..", ' or 'github: "zoolutions/docs-kit", '
 # The GHCR image/service = the OWNER/REPO the site will live in (repo-linked pkg).
-image = ENV.fetch("DOCS_KIT_IMAGE", "mhenrixon/#{app_name}")
+image = ENV.fetch("DOCS_KIT_IMAGE", "zoolutions/#{app_name}")
 service = ENV.fetch("DOCS_KIT_SERVICE", app_name)
 
 # --- gems ---------------------------------------------------------------------
@@ -53,14 +53,26 @@ after_bundle do
   run "bun install --silent" if system("command -v bun >/dev/null 2>&1")
   run "bun run build:css" if system("command -v bun >/dev/null 2>&1")
 
-  # --- deploy scaffolding (Kamal + the reusable workflow) ---------------------
+  # --- deploy scaffolding (dash + the reusable workflow) ---------------------
   create_file "config/deploy.yml", <<~YAML
-    # Kamal deploy → the oss-infrastructure server (Cloudflare Tunnel + kamal-proxy).
+    # dash deploy → the oss-infrastructure server (Cloudflare Tunnel + dash-proxy).
     # service/image = the repo OWNER/REPO so the ghcr package auto-links to the
     # repo and GITHUB_TOKEN can push + pull it (no PAT). See docs-kit's README.
+    # `dash docs` / `dash docs proxy` is the always-current reference for every key.
     service: #{service}
     image: #{image}
 
+    # dash 4 renamed the on-host proxy (kamal-proxy → dash-proxy) and migrates a
+    # host in place; an older CLI must not deploy this config.
+    minimum_version: 4.0.0
+
+    # A stateless docs site never rolls back far — keep the host tidy.
+    retain_containers: 2
+
+    # Status-named pages (public/502.html, 503, 504) the proxy serves in place of
+    # the app's during a deploy gap — paired with `proxy.intercept_errors` below.
+    error_pages_path: public
+
     servers:
       web:
         hosts:
@@ -72,17 +84,51 @@ after_bundle do
     proxy:
       host: <%= ENV["DEPLOY_DOMAIN"] %>
       app_port: 3000
+      # TLS terminates at Cloudflare; the tunnel reaches the proxy over plain HTTP.
       ssl: false
       healthcheck:
         path: /up
         interval: 5
         timeout: 30
 
+      # --- dash-proxy per-app features ------------------------------------------
+      # zstd / br / gzip negotiated at the edge; responses the app already encoded
+      # (Thruster) pass through untouched.
+      compress: true
+
+      # RFC 9111 shared cache. Only responses the app marks `Cache-Control: public,
+      # max-age` are stored (Propshaft assets, /llms*.txt) — HTML carrying a session
+      # cookie is refused by design. `dash proxy cache stats` shows what it holds.
+      cache:
+        enabled: true
+        max_ttl: 300
+
+      # Security headers set once here instead of per app; drop server fingerprints.
+      headers:
+        response:
+          set:
+            X-Content-Type-Options: nosniff
+            Referrer-Policy: strict-origin-when-cross-origin
+          remove:
+            - Server
+            - X-Powered-By
+
+      # Serve public/<status>.html instead of a bare "Bad Gateway" while a
+      # container is swapped or unhealthy.
+      intercept_errors:
+        - 502
+        - 503
+        - 504
+
+      # Keep the health probe out of the request histograms.
+      exclude_metrics_paths:
+        - /up
+
     registry:
       server: ghcr.io
       username: mhenrixon
       password:
-        - KAMAL_REGISTRY_PASSWORD
+        - DASH_REGISTRY_PASSWORD
 
     builder:
       arch: amd64
@@ -98,18 +144,24 @@ after_bundle do
         SECRET_KEY_BASE: "#{SecureRandom.hex(64)}"
   YAML
 
-  create_file ".kamal/secrets", <<~SH
+  # The status pages `proxy.intercept_errors` serves for a deploy gap — `rails new`
+  # ships 500.html; the proxy looks for the exact status it intercepted.
+  %w[502 503 504].each do |status|
+    create_file "public/#{status}.html", File.read("public/500.html") if File.exist?("public/500.html")
+  end
+
+  create_file ".dash/secrets", <<~SH
     # In CI the deploy workflow sets this to the job's GITHUB_TOKEN. Locally,
-    # export it (e.g. KAMAL_REGISTRY_PASSWORD=$(gh auth token)).
-    KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
+    # export it (e.g. DASH_REGISTRY_PASSWORD=$(gh auth token)).
+    DASH_REGISTRY_PASSWORD=$DASH_REGISTRY_PASSWORD
   SH
 
   # The Dockerfile + .dockerignore are written by `docs_kit:install` (run above in
   # after_bundle) so a scaffolded site and an upgrading site share ONE optimized,
   # version-stamped Dockerfile — no divergent copy to maintain here. The generator
   # derives the LABEL service from the app dir basename (= app_name); if the site
-  # deploys under a DIFFERENT Kamal service (`--service`), correct the label to
-  # match config/deploy.yml so Kamal's --skip-push validate_image passes.
+  # deploys under a DIFFERENT dash service (`--service`), correct the label to
+  # match config/deploy.yml so dash's --skip-push validate_image passes.
   gsub_file "Dockerfile", /LABEL service=".*"/, %(LABEL service="#{service}") if service != app_name
 
   create_file ".github/workflows/deploy-docs.yml", <<~YAML
@@ -120,7 +172,7 @@ after_bundle do
       workflow_dispatch:
     jobs:
       deploy:
-        uses: mhenrixon/docs-kit/.github/workflows/deploy.yml@main
+        uses: zoolutions/docs-kit/.github/workflows/deploy.yml@main
         with:
           image: #{image}
           service: #{service}

data/lib/docs_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DocsKit
-  VERSION = "1.0.8"
+  VERSION = "1.1.0"
 end

data/lib/generators/docs_kit/install/install_generator.rb

@@ -568,7 +568,7 @@ module DocsKit
         (name || File.basename(destination_root)).to_s.underscore.humanize
       end
 
-      # The Kamal `service` name stamped as the Dockerfile's LABEL — the app dir
+      # The dash `service` name stamped as the Dockerfile's LABEL — the app dir
       # basename (a docs site's repo name), matching the `docs-kit new` default.
       # Used in Dockerfile.tt via <%= docker_service %>.
       def docker_service

data/lib/generators/docs_kit/install/templates/Dockerfile.tt

@@ -7,7 +7,7 @@
 # `build` stage. Pair it with the shipped .dockerignore so the build context
 # stays small (no node_modules, .git, logs, specs, coverage).
 #
-# Build context is the app root; `docker build .` (Kamal: context: ".").
+# Build context is the app root; `docker build .` (dash: context: ".").
 
 ARG RUBY_VERSION=<%= ruby_version_arg %>
 FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
@@ -59,9 +59,9 @@ RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile && \
 # --- Final stage --------------------------------------------------------------
 FROM base
 
-# Kamal's validate_image greps this label on a --skip-push deploy; it must equal
+# dash's validate_image greps this label on a --skip-push deploy; it must equal
 # `service:` in config/deploy.yml. The reusable deploy workflow also stamps it,
-# but keeping it here means `docker build` alone produces a Kamal-valid image.
+# but keeping it here means `docker build` alone produces a dash-valid image.
 LABEL service="<%= docker_service %>"
 
 # Copy ONLY the built artifacts from the build stage: the installed bundle and
@@ -79,9 +79,9 @@ EXPOSE 3000
 <% if thruster? -%>
 # Thruster fronts Puma (HTTP caching + compression + X-Sendfile). It listens on
 # HTTP_PORT and proxies to Puma on TARGET_PORT (it sets PORT for the child, which
-# config/puma.rb reads). HTTP_PORT MUST be the port traffic is routed to (Kamal's
+# config/puma.rb reads). HTTP_PORT MUST be the port traffic is routed to (dash's
 # `app_port`, the EXPOSE above) — Thruster's default is 80, which the non-root
-# user can't reliably bind AND which kamal-proxy (app_port: 3000) would never
+# user can't reliably bind AND which dash-proxy (app_port: 3000) would never
 # route to, silently bypassing Thruster straight into Puma.
 ENV HTTP_PORT="3000" \
     TARGET_PORT="3001"

data/lib/generators/docs_kit/install/templates/agents_md.erb

@@ -8,7 +8,7 @@ reads it through the bundled `write-docs-page` skill. Edit freely — a
 <!-- BEGIN docs-kit -->
 ## Writing docs pages (docs-kit)
 
-<%= app_brand %> is a [docs-kit](https://github.com/mhenrixon/docs-kit) site: a
+<%= app_brand %> is a [docs-kit](https://github.com/zoolutions/docs-kit) site: a
 Phlex/daisyUI chrome where **every page is a `DocsUI::Page` subclass** and the
 sidebar, TOC, search, and Markdown twin come free. To document something, you
 scaffold a page, then write its `#content`. Never hand-write HTML or daisyUI

data/lib/generators/docs_kit/install/templates/dockerignore

@@ -40,6 +40,7 @@
 
 # CI / deploy / Docker meta — not part of the runtime image.
 /.github/
+/.dash/
 /.kamal/
 /Dockerfile*
 /.dockerignore

data/lib/generators/docs_kit/install/templates/skill.md.erb

@@ -5,7 +5,7 @@ description: "Write, add, or update a documentation page in this docs-kit site.
 
 # Write a docs page
 
-This is a [docs-kit](https://github.com/mhenrixon/docs-kit) site (<%= app_brand %>).
+This is a [docs-kit](https://github.com/zoolutions/docs-kit) site (<%= app_brand %>).
 Every page is a `DocsUI::Page` subclass; the shell, sidebar, "On this page" TOC,
 search, and the `.md` twin all come free. Your job is to scaffold a page and
 write its `#content` — never hand-write HTML or daisyUI markup.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -164,6 +164,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/components/docs_ui/archived_page.rb
 - app/components/docs_ui/brand_mark.rb
 - app/components/docs_ui/callout.rb
 - app/components/docs_ui/code.rb
@@ -209,6 +210,7 @@ files:
 - lib/docs_kit/brand_logo.rb
 - lib/docs_kit/configuration.rb
 - lib/docs_kit/controller.rb
+- lib/docs_kit/doc_version.rb
 - lib/docs_kit/engine.rb
 - lib/docs_kit/landing_config.rb
 - lib/docs_kit/llms_text.rb
@@ -226,11 +228,15 @@ files:
 - lib/docs_kit/open_api/schema.rb
 - lib/docs_kit/registry.rb
 - lib/docs_kit/rubocop.rb
+- lib/docs_kit/scope.rb
+- lib/docs_kit/scoping.rb
 - lib/docs_kit/search_hit.rb
 - lib/docs_kit/search_index.rb
 - lib/docs_kit/search_index/snippet.rb
 - lib/docs_kit/seo_config.rb
 - lib/docs_kit/shortcut.rb
+- lib/docs_kit/snapshot.rb
+- lib/docs_kit/snapshot/entry.rb
 - lib/docs_kit/templates/new_site.rb
 - lib/docs_kit/topbar_link.rb
 - lib/docs_kit/version.rb
@@ -260,13 +266,13 @@ files:
 - lib/generators/docs_kit/page/templates/page.rb.erb
 - lib/rubocop/cop/docs_kit/escaped_interpolation_in_heredoc.rb
 - lib/rubocop/cop/docs_kit/render_component_preferred.rb
-homepage: https://github.com/mhenrixon/docs-kit
+homepage: https://github.com/zoolutions/docs-kit
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/mhenrixon/docs-kit
-  changelog_uri: https://github.com/mhenrixon/docs-kit/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/mhenrixon/docs-kit/issues
+  source_code_uri: https://github.com/zoolutions/docs-kit
+  changelog_uri: https://github.com/zoolutions/docs-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/zoolutions/docs-kit/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: