docs-kit 1.0.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa41c41824768d1db2a5ad5a7ba9b983b0f81032c8b5a3f80277e2611e203449
-  data.tar.gz: 60cd31b54d83c9c6920ff48d27ec177f81b7a240fdf513e65f9617837cc6c738
+  metadata.gz: b53c8fcfcdc8d5053f9019ea56edc5a1b4fce1a8760a220eb19c76a297e72d53
+  data.tar.gz: 4289ad366b8462a9617db0e696250b717c21af1a30a97126367c370452156e1d
 SHA512:
-  metadata.gz: e23f649705ac6216e4961c389eab64965961023123937364e4915b608264bf994ec0885c1958929884449d4eb4f6d9202ed6a5fa7fb9dd373c6a2202e8850ea1
-  data.tar.gz: 0a047f0b8b45fdce21b9121b13461a5c003ec307586ef4b49bbb3ead0c4d79f44db00a243eda7792fc5be173f3b135195efad4212360527cb2ef5e143eafd5e5
+  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.
@@ -166,6 +166,10 @@ DocsKit.configure do |c|
   # once in the topbar, right after the brand. Unset (default) renders nothing.
   c.app_link = { href: "/", label: "Back to the app" }
 
+  # Your own mark in the topbar + sidebar header instead of the text brand.
+  c.brand_logo   = { paths: ["M4 2h9l5 5…Z"], viewbox: "0 0 81 45" }
+  c.topbar_brand = :mobile_only                             # drop the desktop duplicate (default :always)
+
   # Repo/social links in the topbar (next to the theme switcher).
   c.topbar_links = [
     { href: "https://github.com/you/phlex-reactive", label: "GitHub", icon: :github },
@@ -185,6 +189,12 @@ registry maps a heading to its authored pages (`Doc.nav_items`); a page that
 isn't written yet is skipped, so there are no dead links. Register a page with
 one line (see [Add a page](#add-a-page)) and it appears in the sidebar.
 
+The registry's page groups ("Getting started", "REST API", …) are the top level
+of the rendered menu — each an open, collapsible section. The heading above them
+only appears when you register **several** headings, and then as a static label
+(no fold): a site with one registry gets no redundant "Documentation" level, and
+nothing in the sidebar is indented deeper than group → page.
+
 ### The two homes, the brand link, and dark code themes
 
 These knobs cover what sites used to shim by subclassing `DocsUI::Shell` or
@@ -194,6 +204,8 @@ overriding route helpers:
 |------|---------|--------------|
 | `c.brand_href` | `"/"` | The **docs home** — the href of the topbar brand, the sidebar brand, and each page's "← Docs home" masthead link. Set it (e.g. `"/docs"`) when the docs live under a subpath, instead of subclassing `Shell` or overriding `root_path`. |
 | `c.app_link` | `nil` | The **app home** — an opt-in `{ href:, label: }` link back to the application hosting the docs, rendered once in the topbar right after the brand (e.g. `{ href: "/", label: "Back to the app" }`). Unset renders nothing, so a standalone docs site is unchanged. External hrefs open in a new tab with `rel=noopener`. |
+| `c.brand_logo` | `nil` | Your **brand mark**, rendered inside the brand anchor of BOTH the topbar and the sidebar header in place of the text `c.brand` (which stays the accessible name / `aria-label` fallback). Unset renders the text brand, byte-identical to before. Takes exactly one of five forms — see [The brand mark](#the-brand-mark) below. |
+| `c.topbar_brand` | `:always` | Where the topbar renders the brand. At the drawer-pinned breakpoint (`lg:`) the sidebar brand is always visible, so the topbar copy is a duplicate — `:mobile_only` hides it there (`lg:hidden`). The default keeps today's markup verbatim. |
 | `c.code_theme_dark` | `nil` | A second Rouge theme for **dark** daisyUI themes. `nil` keeps the single-theme behavior (fully backwards compatible). When set, `DocsUI::Code` also emits this theme's CSS scoped under `[data-theme=X] .code-highlight` for each shipped dark theme, so code blocks stay readable when the switcher flips to a dark theme. |
 | `c.dark_themes` | daisyUI's built-in dark theme names | Which theme names count as dark for `code_theme_dark`. Intersected with `c.themes` at render time, so only shipped themes emit CSS. Override to name custom dark themes (e.g. `%w[zazu-dark]`). |
 
@@ -203,6 +215,33 @@ blocks with no JavaScript and no flash. The Rouge CSS is inlined per block
 (not part of the Tailwind build), so the [theme-sync invariant](#css--the-canonical-build)
 is unaffected — a `code_theme_dark` doesn't need a CSS rebuild.
 
+### The brand mark
+
+`c.brand_logo` replaces the text brand in the shell chrome (topbar + sidebar
+header) with your own mark — no more copying private `Shell`/`Sidebar` methods
+that go stale on upgrades. It takes **exactly one** of five forms (mixing forms,
+or a malformed value, raises at config time):
+
+```ruby
+c.brand_logo = { svg: "M4 2h9l5 5…Z", viewbox: "0 0 22 24", label: "Acme" } # one path-d
+c.brand_logo = { paths: ["M4 2…Z", "M9 7…Z"], viewbox: "0 0 81 45" }        # multi-path wordmark
+c.brand_logo = { markup: File.read("mark.svg") }                            # raw <svg> markup, embedded verbatim
+c.brand_logo = { file: "app/assets/images/mark.svg" }                       # a .svg file, embedded inline
+c.brand_logo = { src: "logo.png", alt: "Acme" }                             # an <img> from the asset pipeline
+```
+
+- The `svg:`/`paths:` forms render with `fill="currentColor"`, so the mark
+  **recolors with the active daisyUI theme**. `markup:`/`file:` are embedded
+  as-authored — use `currentColor` inside them to stay theme-adaptive. An
+  `src:` `<img>` **cannot** inherit `currentColor` and won't adapt.
+- `markup:`/`file:` embed your own SVG verbatim (they are your site's content,
+  same trust domain as your views); both are shape-checked to be an `<svg>`
+  element at config time, and a `file:` re-reads on change in development.
+- `label:`/`alt:` name the mark for assistive tech; unset, the mark falls back
+  to `c.brand`. The sidebar keeps the `version_badge` next to the mark.
+- Sizing is fixed per surface (topbar `h-6`, sidebar `h-7`, landing hero `h-9`).
+- `c.landing.logo` (the landing-hero mark) accepts the same five forms.
+
 ### Topbar links (repo & social)
 
 Point readers at your source repo, chat, or socials from the topbar (next to the
@@ -662,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.
 
@@ -805,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)
@@ -815,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.
 
@@ -866,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`:
 
@@ -877,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
 
@@ -1040,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/components/docs_ui/landing.rb

@@ -31,9 +31,6 @@ module DocsUI
   # walks the same #docs-content region Shell stamps.
   class Landing < Phlex::HTML
     include Phlex::Rails::Helpers::Request
-    # For the image-form hero logo (c.landing.logo = { src: … }): resolve the asset
-    # path through the site's pipeline to its digested /assets URL.
-    include Phlex::Rails::Helpers::ImageURL
 
     def view_template
       render DocsUI::Shell.new(title: landing.eyebrow || config.brand) do
@@ -63,20 +60,12 @@ module DocsUI
       end
     end
 
-    # The brand mark — an inline single-path SVG (currentColor, theme-adaptive) or
-    # an <img>. Rendered above the eyebrow, like a product wordmark.
+    # The brand mark — the shared DocsUI::Logo renderer (any DocsKit::BrandLogo
+    # form) at hero size. Rendered above the eyebrow, like a product wordmark.
     def logo
       return unless (mark = landing.hero_logo)
 
-      if mark.inline?
-        svg(viewbox: mark.viewbox, class: "h-9 w-auto text-primary", fill: "currentColor",
-            role: "img", aria_label: mark.label) do |s|
-          s.title { mark.label } if mark.label
-          s.path(d: mark.svg)
-        end
-      else
-        img(src: image_url(mark.src), alt: mark.alt.to_s, class: "h-9 w-auto")
-      end
+      render DocsUI::Logo.new(mark, class: "h-9 w-auto text-primary")
     end
 
     def eyebrow
@@ -162,15 +151,17 @@ module DocsUI
       div(class: "mt-16") do
         h2(class: "text-sm font-semibold uppercase tracking-wide text-base-content/50") { "Documentation" }
         div(class: "mt-6 grid gap-8 sm:grid-cols-2") do
-          groups.each { |heading, items| doc_index_group(heading, items) }
+          # A lone heading would just repeat the h2 above (often literally
+          # "Documentation"), so only label the columns when there are several.
+          groups.each { |heading, items| doc_index_group(heading, items, labeled: groups.size > 1) }
         end
       end
     end
 
-    def doc_index_group(heading, items)
+    def doc_index_group(heading, items, labeled:)
       div do
-        h3(class: "text-xs font-semibold uppercase tracking-wide text-base-content/40") { heading }
-        ul(class: "mt-3 flex flex-col gap-2") do
+        h3(class: "text-xs font-semibold uppercase tracking-wide text-base-content/40") { heading } if labeled
+        ul(class: labeled ? "mt-3 flex flex-col gap-2" : "flex flex-col gap-2") do
           items.each { |item| li { a(href: item.href, class: "link link-hover text-sm") { item.label } } }
         end
       end

data/app/components/docs_ui/logo.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders a DocsKit::BrandLogo (config.brand_logo / config.landing.logo) as the
+  # brand mark — an inline currentColor <svg> (theme-adaptive), a verbatim
+  # site-authored <svg> embed, or an <img>.
+  #
+  #   render DocsUI::Logo.new(config.brand_logo, class: "h-6 w-auto", label: config.brand)
+  #
+  # label: is the accessible-name fallback when the logo itself carries none
+  # (callers pass config.brand, so the mark always announces the site).
+  #
+  # The svg:/paths: forms emit each path-d as an ordinary Phlex-escaped
+  # attribute — config free text never bypasses the escape. The markup:/file:
+  # forms DO embed markup verbatim via raw(safe(...)): that content is the
+  # site's own deliberately-configured SVG (its initializer / its asset file —
+  # the same trust domain as the site's own views, which can already render
+  # anything), not third-party free text, and DocsKit::BrandLogo shape-checks it
+  # to be an <svg> element at config time. That authored-by-the-trusting-site
+  # rationale is the same carve-out DocsUI::BrandMark uses for its gem-authored
+  # path constants.
+  class Logo < Phlex::HTML
+    # For the src: image form — resolve the asset path through the site's
+    # pipeline to its digested /assets URL, exactly like DocsUI::Landing's img.
+    include Phlex::Rails::Helpers::ImageURL
+
+    def initialize(logo, label: nil, **attributes)
+      @logo = DocsKit::BrandLogo.from(logo)
+      @label = label
+      @attributes = attributes
+    end
+
+    def view_template
+      if @logo.image?
+        img(src: resolved_src, alt: accessible_name.to_s, **@attributes)
+      elsif @logo.embed?
+        embedded_svg
+      else
+        inline_svg
+      end
+    end
+
+    private
+
+    def accessible_name = @logo.label || @label
+
+    # The svg:/paths: forms: a currentColor mark that recolors with the active
+    # daisyUI theme; every path-d is an escaped attribute value.
+    def inline_svg
+      svg(viewBox: @logo.viewbox, fill: "currentColor", role: "img",
+          aria_label: accessible_name, **@attributes) do |s|
+        s.title { accessible_name } if accessible_name
+        @logo.paths.each { |d| s.path(d: d) }
+      end
+    end
+
+    # The markup:/file: forms: the site's own <svg> embedded verbatim (see the
+    # class comment for the trust rationale) inside a wrapper that carries the
+    # caller's sizing — the inner svg fills it. Literal arbitrary variants so
+    # Tailwind scans them from this file.
+    def embedded_svg
+      classes = [@attributes[:class], "inline-flex [&>svg]:h-full [&>svg]:w-auto"].compact.join(" ")
+      span(role: "img", aria_label: accessible_name, **@attributes, class: classes) do
+        raw(safe(@logo.svg_markup))
+      end
+    end
+
+    # The digested asset URL when a view context is present; off a request (an
+    # isolated render) degrade to the raw src — the DocsUI::MetaTags posture.
+    def resolved_src
+      view_context ? image_url(@logo.src) : @logo.src
+    end
+  end
+end

data/app/components/docs_ui/shell.rb

@@ -156,7 +156,7 @@ module DocsUI
         div(class: "flex-1 items-center gap-2") do
           label(for: DRAWER_ID, class: "btn btn-square btn-ghost btn-sm lg:hidden",
                 aria_label: "Open menu") { render DocsUI::Icon.new("menu", class: "size-5") }
-          a(href: config.brand_href, class: "btn btn-ghost text-lg font-bold") { config.brand }
+          a(href: config.brand_href, class: topbar_brand_classes) { brand_mark }
           app_home_link
         end
         render DocsUI::SearchBox.new if config.search_enabled?
@@ -169,6 +169,26 @@ module DocsUI
       end
     end
 
+    # The brand anchor's classes. config.topbar_brand = :mobile_only adds
+    # lg:hidden — at the drawer-pinned breakpoint the sidebar brand is already
+    # visible, so a site can drop the duplicate. The default (:always) keeps
+    # the pre-knob classes verbatim.
+    def topbar_brand_classes
+      base = "btn btn-ghost text-lg font-bold"
+      config.topbar_brand == :mobile_only ? "#{base} lg:hidden" : base
+    end
+
+    # The brand: the configured mark (config.brand_logo) when set, else the
+    # text brand — byte-identical to before for a site that sets nothing. The
+    # text brand stays the mark's accessible-name fallback.
+    def brand_mark
+      if (logo = config.brand_logo)
+        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand)
+      else
+        plain config.brand
+      end
+    end
+
     # The opt-in App Home link (config.app_link) — the way back to the hosting
     # app, rendered once, right after the brand. Nothing renders when unset, so
     # the topbar stays byte-identical for a site that never configures it.

data/app/components/docs_ui/sidebar.rb

@@ -8,6 +8,11 @@ module DocsUI
   #
   # nav_groups is an ordered Hash:
   #   { "Heading" => { "Subgroup" => [DocsKit::NavItem, ...] } }
+  #
+  # Subgroups are the top level of the rendered menu. A lone heading (the common
+  # single-registry site) is not rendered at all — the brand masthead already
+  # labels the sidebar; with several headings, each renders as a STATIC
+  # `.menu-title` label (no fold) and only subgroups collapse.
   class Sidebar < Phlex::HTML
     include Phlex::Rails::Helpers::Request
     include DaisyUI
@@ -29,7 +34,8 @@ module DocsUI
         header_section
         div(class: "flex-1 overflow-y-auto px-2 pb-6") do
           Menu(class: "w-full gap-1") do
-            nav_groups.each { |heading, grouped| nav_group(heading, grouped) }
+            groups = nav_groups.reject { |_, grouped| grouped.nil? || grouped.empty? }
+            groups.each { |heading, grouped| nav_group(heading, grouped, labeled: groups.size > 1) }
           end
         end
       end
@@ -42,27 +48,37 @@ module DocsUI
 
     def header_section
       div(class: "flex min-h-16 items-center gap-2 px-4") do
-        a(href: config.brand_href, class: "text-lg font-bold text-base-content") { config.brand }
+        a(href: config.brand_href, class: "text-lg font-bold text-base-content") { brand_mark }
         badge = config.version_badge_text
         span(class: "badge badge-sm badge-ghost") { badge } if badge
       end
     end
 
-    # A top-level collapsible group (e.g. "Docs") holding collapsible sub-groups
-    # (e.g. "Guide", "Examples"). `grouped` is a { subgroup => [items] } Hash.
-    def nav_group(heading, grouped)
-      return if grouped.nil? || grouped.empty?
+    # The brand: the configured mark (config.brand_logo) when set, else the
+    # text brand — byte-identical to before for a site that sets nothing.
+    # Slightly taller than the topbar's h-6: this is the masthead.
+    def brand_mark
+      if (logo = config.brand_logo)
+        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand)
+      else
+        plain config.brand
+      end
+    end
 
-      li do
-        details(open: true) do
-          summary(class: "text-xs font-semibold uppercase tracking-wider text-base-content/50 #{MARKER_RESET}") do
-            heading
-          end
-          ul do
-            grouped.each { |subgroup, items| nav_subgroup(subgroup, items) }
-          end
+    # A top-level group (e.g. "Docs") holding collapsible sub-groups (e.g.
+    # "Guide", "Examples"). `grouped` is a { subgroup => [items] } Hash. The
+    # heading label only renders when the sidebar shows SEVERAL groups
+    # (labeled:) — as a static `.menu-title`, never a <details>, so subgroups
+    # stay at the menu's top level instead of gaining a nesting indent. The
+    # mt-4/first:mt-0 pair is the breathing room between one group's links and
+    # the next group's label.
+    def nav_group(heading, grouped, labeled:)
+      if labeled
+        li(class: "menu-title mt-4 text-xs font-semibold uppercase tracking-wider text-base-content/50 first:mt-0") do
+          heading
         end
       end
+      grouped.each { |subgroup, items| nav_subgroup(subgroup, items) }
     end
 
     # A collapsible sub-group: its title is a <summary> so the whole section folds

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
 }