zer0-image-generator 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94ef9be8acf2f3c67c09f13a916886b5cb902677a949948833ee75bf11da456b
-  data.tar.gz: 67da956c8c22361911764a8103a62a3075c615ea8ecde4145e1cf61a39152489
+  metadata.gz: b3ce0aa23d8bbc6d1dfe3572c2bd43f61441ad104b1d176538c2bd35b57546f1
+  data.tar.gz: db9e16c02e366d78b74cb98ac9697cc26a6c660f9aa7a349a93d678ab221a734
 SHA512:
-  metadata.gz: 81cdf3446d4352ec701b51a85e7051df57ae891a6cd2f22803cb5a383350076b7d4afc52a676c181bc5eb5832cbe99b0fd557c84732b03de945050a888d92403
-  data.tar.gz: a6687659e49d06b6b32cfb6c1e077ff625e014f88cef5e3be3d20c131720d59808370fc436d9f1d74d548b9679c05bf0fa4ffe3c3faaed22c49ca057be081460
+  metadata.gz: 88a563a299e10b07e9fce08ac2e781ff686e8c29d0650377e92d2f691441bf4294c8f374f49c3d2b576091a5ff02de325d56bfc8cba1cf6b8d3bf105d79c090b
+  data.tar.gz: 6c2121c4d2ce5215efa61c36ae546b25b26f93a4018859b6a3c57842c844f8ecbe62e6c72011351ddbb7c70b383a81bdaaf238b78865c0996268f3f024c83b22

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator/v0.8.0...zer0-image-generator/v0.9.0) (2026-10-07)
+
+
+### Features
+
+* **providers:** Grok Imagine through a refreshable xAI login — Kilo token refresh, aspect ratio, Cloudflare-safe requests, honest .jpg (contains [#23](https://github.com/bamr87/zer0-image-generator/issues/23)) ([#24](https://github.com/bamr87/zer0-image-generator/issues/24)) ([affdc8e](https://github.com/bamr87/zer0-image-generator/commit/affdc8ecf25efb574e92f68e582e83cfa0f9c5c7))
+* zer0 stack — design-token kit, engine Facade, and stack docs ([#22](https://github.com/bamr87/zer0-image-generator/issues/22)) ([9932668](https://github.com/bamr87/zer0-image-generator/commit/9932668b4f5666582c19ad30e33fed3833f5283b))
+
+
+### Bug Fixes
+
+* **web:** sync the zer0-ui-tokens kit's --maxw with application.css (1.0.1) ([#27](https://github.com/bamr87/zer0-image-generator/issues/27)) ([13ccd63](https://github.com/bamr87/zer0-image-generator/commit/13ccd633aea0a8f53c340f7d74a82c1bf277c43a))
+
 ## [0.8.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator/v0.7.0...zer0-image-generator/v0.8.0) (2026-10-03)
 
 

data/README.md

@@ -208,29 +208,35 @@ export ANTHROPIC_API_KEY="..."         # 3. console.anthropic.com
 
 Keys are read from the environment or a git-ignored `.env` at the site root. On a Claude Pro/Max subscription the orchestration costs nothing extra; only the renderer bills per image.
 
-### Grok OAuth (xAI renderer)
+### Grok OAuth (xAI renderer + art direction)
 
-`--provider xai` accepts a **Grok OAuth access token** as well as an API key, and tries them in that order — so a SuperGrok / X Premium+ login can render banners without a console.x.ai key:
+The same **Grok OAuth access token** authenticates `--provider xai` *and* `--prompt-engine xai` / `--review xai` (Grok writes the art brief and vision-reviews the render). SuperGrok / X Premium+ can drive the whole pipeline without a console.x.ai key:
 
 ```bash
 export XAI_OAUTH_TOKEN="..."           # 1. an OAuth access token (GROK_OAUTH_TOKEN also works)
 #    …or a credentials file from a Grok login — ~/.grok/auth.json by default,
-#    or set XAI_OAUTH_CREDENTIALS / GROK_OAUTH_CREDENTIALS to point elsewhere
-export XAI_API_KEY="..."               # 2. console.x.ai — and the automatic fallback
+#    ~/.local/share/kilo/auth.json (Kilo's xAI store), or set
+#    XAI_OAUTH_CREDENTIALS / GROK_OAUTH_CREDENTIALS / KILO_AUTH_PATH
+export XAI_API_KEY="..."               # 2. console.x.ai — renderer fallback only
 ```
 
-Both are `Authorization: Bearer` credentials on the same endpoint, which is what makes the fallback real rather than cosmetic: **if the OAuth token is expired or the API rejects it (401/403) and an `XAI_API_KEY` is present, the same request is retried with the key** and the page still renders. A token whose recorded expiry has already passed is skipped without spending a request at all. Other failures (a 500, a bad prompt) are *not* credential problems, so they never burn the fallback.
+Both are `Authorization: Bearer` credentials on the same endpoint, which is what makes the fallback real rather than cosmetic: **if the OAuth token is expired or the API rejects it (401/403) and an `XAI_API_KEY` is present, the same request is retried with the key** and the page still renders. A token whose recorded expiry has already passed, with nothing to refresh it with, is skipped without spending a request at all. Other failures (a 500, a bad prompt) are *not* credential problems, so they never burn the fallback.
 
-The engine only ever *reads* a token — it does not mint or refresh one, and never writes to the credentials file, because xAI publishes neither a device-code endpoint nor a public client id. Re-run your Grok login when a token expires.
+**Expired tokens are refreshed when their store can.** The engine never mints a token (that takes an interactive login), but a login that saved a refresh token and a client id — Kilo Code's does, as `{ "xai": { "access", "refresh", "expires" } }` — is renewed at `https://auth.x.ai/oauth2/token` (the endpoint auth.x.ai's OIDC discovery document publishes) right before the first request that needs it. The rotated pair is written back into that same file, atomically, keeping its key names, time units, other entries and permissions, so the login tool and your next run both see it. The client id comes from the store, else from the access token's JWT `client_id` or `aud` claim. Parallel workers share one refresh. A refresh is never retried, because a refresh token that rotated on a lost response is already spent. If it fails, the chain moves on to `XAI_API_KEY`; with no key the page fails with the reason. A token with no refresh token still needs you to re-run your Grok login.
 
 | variable | effect |
 | --- | --- |
 | `XAI_OAUTH_TOKEN` / `GROK_OAUTH_TOKEN` | OAuth access token, tried first |
 | `XAI_OAUTH_CREDENTIALS` / `GROK_OAUTH_CREDENTIALS` | explicit path to a Grok credentials JSON (wins outright over `~/.grok/auth.json`) |
+| `KILO_AUTH_PATH` | extra credentials file (Kilo store uses `{ "xai": { "access": "…", "refresh": "…" } }`; refreshed in place when expired) |
 | `XAI_API_KEY` | API key — the fallback rung |
 | `XAI_AUTH` | `auto` (default), `oauth` or `api_key` — pin one rung |
 | `XAI_BASE_URL` | override `https://api.x.ai/v1` |
 
+**Imagine models get a banner shape.** With `--model grok-imagine-image-2.0` (any `grok-imagine*` model) the request carries the `aspect_ratio` nearest your `size` — `1536x1024` sends `3:2` — because Imagine renders a square by default and a wide banner would crop it. `grok-2-image` requests are unchanged. Imagine answers JPEG, so the banner is saved as `<slug>.jpg` (front matter points there) rather than JPEG bytes under a `.png` name; the vision review and `--enhance` label every upload with the MIME type its bytes declare.
+
+Every request sends `User-Agent: zer0-image-generator` unless the caller names its own: `api.x.ai` and `auth.x.ai` sit behind Cloudflare, which answers a stock `Python-urllib` client with a 403 page or `error code: 1010`.
+
 The run's config banner names the credential it picked (`xai auth: XAI_OAUTH_TOKEN (Grok OAuth token), falling back to XAI_API_KEY (xAI API key)`), and a fallback mid-run is logged as a warning — a silent swap would hide a token that has quietly stopped working.
 
 ## CLI reference
@@ -326,6 +332,8 @@ The style catalog (`lib/zer0_image_generator/abc/art_styles.yml`) is the source
 
 The [zer0-mistakes](https://github.com/bamr87/zer0-mistakes) theme renders `preview:` values with a pure-Liquid include (GitHub-Pages-safe, no plugin needed) and currently vendors this engine at `scripts/lib/preview_generator.py`. This repo is the portable home: the theme is expected to consume the gem (or curl the engine from here) in a follow-up, so there is exactly ONE engine.
 
+How the engine fits the zer0 stack — the theme, zer0-CMS, the `Facade` API and the shared design tokens — is on one page: [docs/ZER0-STACK.md](docs/ZER0-STACK.md).
+
 ## Development
 
 ```bash

data/lib/zer0_image_generator/all.rb

@@ -26,8 +26,9 @@ require_relative "svg/local_renderer"
 require_relative "svg/rasterizer"
 require_relative "svg/lint"
 require_relative "svg/pixel_kit"
-require_relative "providers"
-require_relative "runner"
+  require_relative "providers"
+  require_relative "grok/client"
+  require_relative "runner"
 require_relative "cli"
 
 # ABC / alphabet-book plugin — additive and self-contained (touches none of the

data/lib/zer0_image_generator/claude/client.rb

@@ -156,6 +156,7 @@ module Zer0ImageGenerator
       end
       raise "no Anthropic credential configured" if @mode.nil?
 
+      image_bytes = File.binread(image_path.to_s)
       payload = {
         "model" => model,
         "max_tokens" => max_tokens,
@@ -165,8 +166,8 @@ module Zer0ImageGenerator
           "role" => "user",
           "content" => [
             { "type" => "image", "source" => {
-              "type" => "base64", "media_type" => "image/png",
-              "data" => Base64.strict_encode64(File.binread(image_path.to_s))
+              "type" => "base64", "media_type" => Zer0ImageGenerator.image_media_type(image_bytes),
+              "data" => Base64.strict_encode64(image_bytes)
             } },
             { "type" => "text", "text" => user_text }
           ]

data/lib/zer0_image_generator/cli.rb

@@ -26,8 +26,8 @@ module Zer0ImageGenerator
     ENHANCE_QUALITY_CHOICES = %w[low medium high auto].freeze
     ENHANCE_FIDELITY_CHOICES = %w[high low].freeze
     ENHANCE_FORMAT_CHOICES = %w[png jpeg webp].freeze
-    PROMPT_ENGINE_CHOICES = %w[template claude].freeze
-    REVIEW_CHOICES = %w[claude none].freeze
+    PROMPT_ENGINE_CHOICES = %w[template claude xai].freeze
+    REVIEW_CHOICES = %w[claude xai none].freeze
     RASTERIZER_CHOICES = %w[auto rsvg inkscape magick playwright none].freeze
 
     # The argparse Namespace, field-for-field. Booleans default false, parallel
@@ -200,6 +200,32 @@ module Zer0ImageGenerator
       end
     end
 
+    def degrade_llm(settings, ctx, deps:, logger:)
+      if settings.prompt_engine == "claude" || settings.review_engine == "claude"
+        if ctx.claude.available?
+          logger.info("Claude orchestration: #{ctx.claude.describe}")
+        else
+          logger.warn(deps.claude_credential_hint)
+          settings = settings.dup_with(
+            prompt_engine: (settings.prompt_engine == "claude" ? "template" : settings.prompt_engine),
+            review_engine: (settings.review_engine == "claude" ? "none" : settings.review_engine)
+          )
+        end
+      end
+      if settings.prompt_engine == "xai" || settings.review_engine == "xai"
+        if ctx.grok_client.available?
+          logger.info("Grok orchestration: #{ctx.grok_client.describe}")
+        else
+          logger.warn(XAIAuth::MISSING_HINT)
+          settings = settings.dup_with(
+            prompt_engine: (settings.prompt_engine == "xai" ? "template" : settings.prompt_engine),
+            review_engine: (settings.review_engine == "xai" ? "none" : settings.review_engine)
+          )
+        end
+      end
+      settings
+    end
+
     # Full run. Returns the process exit code (0/1). Usage errors and
     # error_exit escape as ExitError(status); CLI.start converts those for a
     # command-line binary.
@@ -239,19 +265,11 @@ module Zer0ImageGenerator
       ctx = deps.new_run_context(project_root, ENV.to_h)
       validate_credentials(settings, ctx, deps: deps, logger: logger)
 
-      # Claude orchestration (analyze/review) degrades gracefully: without a
-      # Claude credential the run continues on template prompts, unreviewed.
-      wants_claude =
-        settings.provider != "local" &&
-        (settings.prompt_engine == "claude" || settings.review_engine == "claude") &&
-        !(settings.dry_run || settings.list_only)
-      if wants_claude
-        if ctx.claude.available?
-          logger.info("Claude orchestration: #{ctx.claude.describe}")
-        else
-          logger.warn(deps.claude_credential_hint)
-          settings = deps.degrade_settings(settings)
-        end
+      # LLM orchestration degrades gracefully: without a credential the run
+      # continues on template prompts, unreviewed. Claude and Grok degrade
+      # independently so a missing Claude token does not disable a Grok review.
+      unless settings.dry_run || settings.list_only || settings.provider == "local"
+        settings = degrade_llm(settings, ctx, deps: deps, logger: logger)
       end
 
       output_dir = Pathname.new(project_root.to_s) / settings.output_dir

data/lib/zer0_image_generator/command.rb

@@ -32,8 +32,8 @@ module Zer0ImageGenerator
       ["--enhance-quality",  [:enhance_quality, "--enhance-quality Q", "low|medium|high|auto"]],
       ["--enhance-fidelity", [:enhance_fidelity, "--enhance-fidelity F", "high|low (implies --enhance)"]],
       ["--enhance-format",   [:enhance_format, "--enhance-format FMT", "png|jpeg|webp (implies --enhance)"]],
-      ["--prompt-engine",    [:prompt_engine, "--prompt-engine ENGINE", "claude (analyzes the article) or template"]],
-      ["--review",           [:review, "--review ENGINE", "claude (vision-reviews the render) or none"]],
+      ["--prompt-engine",    [:prompt_engine, "--prompt-engine ENGINE", "claude | xai | template"]],
+      ["--review",           [:review, "--review ENGINE", "claude | xai | none"]],
       ["--rasterizer",       [:rasterizer, "--rasterizer TOOL", "auto|rsvg|inkscape|magick|playwright|none"]],
       ["--style",            [:style, "--style TEXT", "Override the image style prompt"]],
       ["--assets-prefix",    [:assets_prefix, "--assets-prefix PREFIX", "Assets prefix for path normalization"]],

data/lib/zer0_image_generator/constants.rb

@@ -158,6 +158,17 @@ module Zer0ImageGenerator
   PROMPT
 
   PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+  JPEG_SIGNATURE = "\xff\xd8\xff".b.freeze
+
+  # The MIME type a raster's own bytes declare. Providers do not all answer PNG
+  # (xAI Imagine answers JPEG), and vision APIs check the label.
+  def self.image_media_type(data)
+    bytes = data.to_s.b
+    return "image/jpeg" if bytes[0, 3] == JPEG_SIGNATURE
+    return "image/webp" if bytes[0, 4] == "RIFF" && bytes[8, 4] == "WEBP"
+
+    "image/png"
+  end
 
   # Pause after each successful non-dry generation (Bash parity: polite pacing
   # between paid API calls).

data/lib/zer0_image_generator/facade.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+# Zer0ImageGenerator::Facade — the stable, Rails-free API for other apps.
+#
+# zer0-CMS (and any other host) asks the image engine two questions:
+#
+#   Zer0ImageGenerator::Facade.missing_previews(site_root)
+#     # => [MissingPreview(path:, relative:, collection:, title:, preview:), ...]
+#
+#   Zer0ImageGenerator::Facade.generate_one(site_root, "_posts/2026-01-01-x.md",
+#                                          provider: "local", env: {}, dry_run: false)
+#     # => Generation(status:, file:, provider:, preview:, image:, stats:,
+#     #               exit_code:, error:, log:)
+#
+# Both are compositions of the engine's own objects — read_config,
+# apply_source_root, resolve_settings, Runner#collection_path, Runner#discover,
+# Content.parse_front_matter / check_preview_exists, CLI.validate_credentials,
+# Runner#run — so "missing" and "generate" mean exactly what they mean to
+# `jekyll preview-images --list-missing` and `jekyll preview-images -f FILE`.
+# No pipeline logic lives here; the only things this file adds are path
+# confinement (every path must resolve inside the site root) and structured
+# results in place of printed lines.
+#
+# Contract (semver-stable from the release that ships this file):
+# - A caller error (site root not a directory, file not found, a path, `source:`
+#   or `collections_dir:`/`output_dir:` that resolves outside the site root)
+#   raises Facade::Error, a Zer0ImageGenerator::Error.
+# - An engine outcome (unknown provider, missing credential, a failed render)
+#   is returned as a Generation with status :error — never raised.
+# - `env:` is the credential environment handed to the providers (the same
+#   RunContext env the web app uses); the process ENV is never mutated.
+#   Settings precedence is the CLI's own — `preview_images:` config, overridden
+#   by the documented env vars (AI_PROVIDER, OUTPUT_DIR, ...) of the process.
+# - Thread-safe per call: each call builds its own Runner, logger and
+#   RunContext. Slice-level messages (front-matter writes, rasterizer notes)
+#   still go to Zer0ImageGenerator::Logging.logger, which this file never
+#   swaps, so concurrent callers cannot steal each other's output.
+#
+# Stdlib only, by policy.
+
+require "pathname"
+require "fileutils"
+
+require_relative "all"
+
+module Zer0ImageGenerator
+  module Facade
+    class Error < Zer0ImageGenerator::Error; end
+
+    # One content file whose preview is absent or points at nothing on disk.
+    # `path` is absolute; `relative` is relative to the site root (so it
+    # includes a `source:` directory); `preview` is the stale front-matter
+    # value, or nil when the key is absent.
+    MissingPreview = Struct.new(:path, :relative, :collection, :title, :preview,
+                                keyword_init: true)
+
+    # The outcome of generate_one.
+    #   status     :generated | :would_generate (dry run) | :skipped | :error
+    #   file       absolute path of the content file
+    #   provider   the provider the run resolved to
+    #   preview    the front-matter value after the run (nil when absent)
+    #   image      absolute path of that preview on disk (nil when not found)
+    #   stats      { processed:, generated:, enhanced:, skipped:, errors: }
+    #   exit_code  the engine's exit status (0 ok, 1 failure)
+    #   error      a human-readable reason when status is :error
+    #   log        [[level, text], ...] — the run's own log, ANSI stripped
+    Generation = Struct.new(:status, :file, :provider, :preview, :image, :stats,
+                            :exit_code, :error, :log, keyword_init: true) do
+      def ok?
+        status != :error
+      end
+    end
+
+    # Logger sink that records instead of printing (see logging.rb's sink
+    # contract: log / say / header).
+    class Recorder
+      ANSI = /\e\[[0-9;]*m/.freeze
+
+      def initialize
+        @entries = []
+        @lock = Mutex.new
+      end
+
+      def entries
+        @lock.synchronize { @entries.dup }
+      end
+
+      def log(message, level)
+        push(level, message)
+      end
+
+      def say(text)
+        push(:say, text)
+      end
+
+      def header(title)
+        push(:header, title)
+      end
+
+      private
+
+      def push(level, text)
+        @lock.synchronize { @entries << [level.to_sym, text.to_s.gsub(ANSI, "")] }
+      end
+    end
+
+    # Every content file in the site's configured collections that lacks a
+    # valid preview, in the order a run would visit them.
+    def self.missing_previews(site_root)
+      site = site_root!(site_root)
+      config = Zer0ImageGenerator.read_config(site)
+      root = project_root!(site, config)
+      settings = Zer0ImageGenerator.resolve_settings(Args.build({}), config)
+      runner = Runner.new(settings, root,
+                          ctx: RunContext.new(project_root: root, env: {}),
+                          logger: Logger.new(sink: Recorder.new))
+
+      settings.collections.uniq.flat_map do |name|
+        dir = runner.collection_path(name)
+        next [] unless dir.directory?
+        unless inside?(dir, site)
+          raise Error, "collection '#{name}' resolves outside the site root: #{dir}"
+        end
+
+        runner.discover(dir).filter_map do |path|
+          next unless inside?(path, site) # a symlink out of the site is not ours
+
+          cf = Content.parse_front_matter(path, settings.front_matter_key)
+          next if cf.nil?
+          next if cf.preview && Content.check_preview_exists(cf.preview, settings, root)
+
+          MissingPreview.new(path: path.to_s, relative: path.relative_path_from(site).to_s,
+                             collection: name, title: cf.title, preview: cf.preview)
+        end
+      end
+    end
+
+    # Generate (or, with dry_run, plan) the preview for ONE content file.
+    # `file` is absolute, or relative to the content root (`source:`), or
+    # relative to the site root — tried in that order, as the CLI does.
+    # `provider: nil` uses the site's configured provider.
+    def self.generate_one(site_root, file, provider: "local", env: {}, dry_run: false)
+      site = site_root!(site_root)
+      config = Zer0ImageGenerator.read_config(site)
+      root = project_root!(site, config)
+      target = content_file!(site, root, file)
+
+      args = Args.build(file: target.to_s, provider: provider, dry_run: dry_run ? true : false)
+      settings = Zer0ImageGenerator.resolve_settings(args, config)
+      unless inside?(root / settings.output_dir, site)
+        raise Error, "output_dir resolves outside the site root: #{settings.output_dir}"
+      end
+
+      recorder = Recorder.new
+      logger = Logger.new(sink: recorder)
+      ctx = RunContext.new(project_root: root, env: string_env(env))
+      runner = Runner.new(settings, root, ctx: ctx, logger: logger)
+      error = nil
+      begin
+        CLI.validate_credentials(settings, ctx, logger: logger)
+        FileUtils.mkdir_p((root / settings.output_dir).to_s) unless settings.dry_run
+        exit_code = runner.run
+      rescue ExitError => e
+        error = e.message
+        exit_code = e.status
+      end
+
+      stats = Stats::ATTRS.to_h { |name| [name, runner.stats.public_send(name)] }
+      log = recorder.entries
+      status =
+        if error || stats[:errors].positive? then :error
+        elsif stats[:generated].positive? then settings.dry_run ? :would_generate : :generated
+        else :skipped
+        end
+      if status == :error && error.nil?
+        error = log.select { |level, _| level == :warning }.map { |_, text| text.strip }.join("\n")
+      end
+
+      cf = Content.parse_front_matter(target, settings.front_matter_key)
+      preview = cf&.preview
+      image = preview && Content.find_preview_image(preview, settings, root)
+
+      Generation.new(status: status, file: target.to_s, provider: settings.provider,
+                     preview: preview, image: image && File.expand_path(image.to_s),
+                     stats: stats, exit_code: exit_code, error: error, log: log)
+    end
+
+    # --- confinement -----------------------------------------------------------
+
+    def self.site_root!(site_root)
+      raise Error, "site root is required" if site_root.nil? || site_root.to_s.strip.empty?
+
+      path = Pathname.new(File.expand_path(site_root.to_s))
+      raise Error, "site root is not a directory: #{site_root}" unless path.directory?
+
+      path
+    end
+
+    # Jekyll's `source:` shifts the content root; it may not leave the site.
+    def self.project_root!(site, config)
+      root = Zer0ImageGenerator.apply_source_root(site, config)
+      raise Error, "source: resolves outside the site root: #{config['source']}" unless inside?(root, site)
+
+      root
+    end
+
+    def self.content_file!(site, root, file)
+      raise Error, "file is required" if file.nil? || file.to_s.strip.empty?
+
+      raw = Pathname.new(file.to_s)
+      candidates = raw.absolute? ? [raw] : [root / raw, site / raw]
+      target = candidates.find(&:file?)
+      raise Error, "content file not found: #{file}" if target.nil?
+
+      target = Pathname.new(File.expand_path(target.to_s))
+      raise Error, "content file is outside the site root: #{file}" unless inside?(target, site)
+
+      target
+    end
+
+    # True when `path` — symlinks resolved, even for a not-yet-created tail —
+    # is `root` or lies beneath it.
+    def self.inside?(path, root)
+      resolved = canonical(path).to_s
+      base = canonical(root).to_s
+      resolved == base || resolved.start_with?(base.end_with?("/") ? base : "#{base}/")
+    end
+
+    def self.canonical(path)
+      probe = Pathname.new(File.expand_path(path.to_s))
+      tail = []
+      until probe.exist? || probe.root?
+        tail.unshift(probe.basename.to_s)
+        probe = probe.dirname
+      end
+      tail.inject(probe.realpath) { |acc, part| acc + part }
+    end
+
+    def self.string_env(env)
+      (env || {}).to_h.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = value.to_s unless value.nil?
+      end
+    end
+
+    private_class_method :site_root!, :project_root!, :content_file!, :inside?,
+                         :canonical, :string_env
+  end
+end

data/lib/zer0_image_generator/grok/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "base64"
+
+require_relative "../constants"
+require_relative "../http"
+require_relative "../providers/xai_auth"
+
+module Zer0ImageGenerator
+  # OpenAI-compatible chat client for api.x.ai. Duck-typed against
+  # AnthropicClient (`complete`, `complete_vision`, `available?`, `describe`)
+  # so the analyze/review stages can run on Grok with the same OAuth token
+  # the image renderer already uses.
+  class GrokClient
+    DEFAULT_MODEL = "grok-4"
+
+    def initialize(env = nil, transport: nil)
+      @env = env.nil? ? ENV.to_h : env.to_h
+      @transport = transport || Http
+      @credential = XAIAuth.chain(@env).first
+    end
+
+    def available?
+      !@credential.nil?
+    end
+
+    def describe
+      @credential ? @credential.source : "none"
+    end
+
+    def complete(system_text, user_text, model: DEFAULT_MODEL,
+                 max_tokens: 2048, effort: "")
+      raise "no xAI credential configured" unless @credential
+
+      payload = {
+        "model" => resolve_model(model),
+        "messages" => [
+          { "role" => "system", "content" => system_text },
+          { "role" => "user", "content" => user_text }
+        ],
+        "max_tokens" => max_tokens
+      }
+      message_text(api_call(payload, "xAI chat"))
+    end
+
+    def complete_vision(system_text, user_text, image_path, model: DEFAULT_MODEL,
+                        max_tokens: 2048, effort: "")
+      raise "no xAI credential configured" unless @credential
+
+      raw = File.binread(image_path.to_s)
+      b64 = Base64.strict_encode64(raw)
+      payload = {
+        "model" => resolve_model(model),
+        "messages" => [
+          { "role" => "system", "content" => system_text },
+          { "role" => "user", "content" => [
+            { "type" => "image_url",
+              "image_url" => { "url" => "data:#{Zer0ImageGenerator.image_media_type(raw)};base64,#{b64}" } },
+            { "type" => "text", "text" => user_text }
+          ] }
+        ],
+        "max_tokens" => max_tokens
+      }
+      message_text(api_call(payload, "xAI chat (review)"))
+    end
+
+    private
+
+    def resolve_model(model)
+      name = model.to_s.strip
+      return DEFAULT_MODEL if name.empty? || name.start_with?("claude")
+
+      name
+    end
+
+    def api_call(payload, what)
+      @credential = XAIAuth.ready_credential(@credential)
+      url = "#{XAIAuth.base_url(@env)}/chat/completions"
+      Http.with_retries(what) do
+        @transport.json(url, payload, @credential.headers, timeout: 900)
+      end
+    end
+
+    def message_text(data)
+      choices = data["choices"] || []
+      return "" if choices.empty?
+
+      message = choices[0]["message"] || {}
+      message["content"].to_s
+    end
+  end
+end

data/lib/zer0_image_generator/http.rb

@@ -138,7 +138,13 @@ module Zer0ImageGenerator
     MAX_REDIRECTS = 10
     REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
 
+    # Sent on every request that does not name its own client. api.x.ai and
+    # auth.x.ai sit behind Cloudflare, whose bot rules answer a stock client
+    # signature with a 403 page or `error code: 1010`.
+    USER_AGENT = "zer0-image-generator"
+
     def request(url, method: "GET", headers: nil, data: nil, timeout: 120)
+      headers = with_user_agent(headers)
       uri = URI(url)
       redirects = 0
       loop do
@@ -243,6 +249,14 @@ module Zer0ImageGenerator
     end
     private_class_method :perform
 
+    def with_user_agent(headers)
+      headers = (headers || {}).to_h
+      return headers if headers.keys.any? { |key| key.to_s.casecmp?("user-agent") }
+
+      headers.merge("User-Agent" => USER_AGENT)
+    end
+    private_class_method :with_user_agent
+
     def request_class(method)
       case method.to_s.upcase
       when "GET" then Net::HTTP::Get