Altinity · hodgesrm · May 10, 2026
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,6 @@
 **/.claude/
 output/
 altinity-expert-clickhouse/skills/.system/
-releases/*.zip
+**/releases/*.zip
 __pycache__/
 *.pyc
diff --git a/altinity-deploy-clickhouse/Makefile b/altinity-deploy-clickhouse/Makefile
@@ -0,0 +1,91 @@
+# Altinity Deploy ClickHouse - Skills Build System
+# Builds zips, links into ~/.claude/skills, and lists skills in this domain.
+# Scope: altinity-deploy-clickhouse/skills/*/SKILL.md only.
+
+DOMAIN_DIR := $(shell pwd)
+BUILD_DIR  := $(DOMAIN_DIR)/releases
+SKILL_DIRS := $(shell find skills -maxdepth 2 -name "SKILL.md" ! -path "*/.system/*" -exec dirname {} \; 2>/dev/null | sort)
+SKILL_ZIPS := $(foreach dir,$(SKILL_DIRS),$(BUILD_DIR)/$(notdir $(dir)).zip)
+
+CLAUDE_SKILLS_DIR ?= $(HOME)/.claude/skills
+
+.PHONY: all clean list help link unlink relink links
+
+all: $(BUILD_DIR) $(SKILL_ZIPS)
+	@echo "Built $(words $(SKILL_ZIPS)) skill packages in $(BUILD_DIR)/"
+
+$(BUILD_DIR):
+	@mkdir -p $(BUILD_DIR)
+
+define ZIP_template
+$(BUILD_DIR)/$(notdir $(1)).zip: $(1)/SKILL.md
+	@echo "Packaging $(notdir $(1))..."
+	@cd $(1) && zip -r $(BUILD_DIR)/$(notdir $(1)).zip . -x "*.DS_Store" -x "*__MACOSX*" -x "*.git*" -x "*__pycache__*" -x "*.pyc"
+endef
+
+$(foreach dir,$(SKILL_DIRS),$(eval $(call ZIP_template,$(dir))))
+
+clean:
+	@echo "Cleaning build directory..."
+	@rm -rf $(BUILD_DIR)
+
+list:
+	@echo "Deploy skills found:"
+	@$(foreach dir,$(SKILL_DIRS),echo "  - $(notdir $(dir)) ($(dir))";)
+
+link: | $(CLAUDE_SKILLS_DIR)
+	@$(foreach dir,$(SKILL_DIRS), \
+	    target="$(CLAUDE_SKILLS_DIR)/$(notdir $(dir))"; \
+	    src="$(DOMAIN_DIR)/$(dir)"; \
+	    if [ -L "$$target" ]; then \
+	        cur=$$(readlink "$$target"); \
+	        if [ "$$cur" = "$$src" ]; then \
+	            echo "ok       $(notdir $(dir))"; \
+	        else \
+	            echo "CONFLICT $(notdir $(dir)) -> $$cur (run 'make relink' to replace)"; \
+	        fi; \
+	    elif [ -e "$$target" ]; then \
+	        echo "SKIP     $(notdir $(dir)) (real dir/file exists, not touching)"; \
+	    else \
+	        ln -s "$$src" "$$target" && echo "linked   $(notdir $(dir))"; \
+	    fi;)
+
+unlink:
+	@$(foreach dir,$(SKILL_DIRS), \
+	    target="$(CLAUDE_SKILLS_DIR)/$(notdir $(dir))"; \
+	    if [ -L "$$target" ]; then \
+	        rm "$$target" && echo "unlinked $(notdir $(dir))"; \
+	    fi;)
+
+relink: unlink link
+
+links:
+	@echo "Deploy skills in $(CLAUDE_SKILLS_DIR):"
+	@$(foreach dir,$(SKILL_DIRS), \
+	    target="$(CLAUDE_SKILLS_DIR)/$(notdir $(dir))"; \
+	    if [ -L "$$target" ]; then \
+	        echo "  $(notdir $(dir)) -> $$(readlink $$target)"; \
+	    else \
+	        echo "  $(notdir $(dir)) (not linked)"; \
+	    fi;)
+
+$(CLAUDE_SKILLS_DIR):
+	@mkdir -p $(CLAUDE_SKILLS_DIR)
+
+help:
+	@echo "Altinity Deploy ClickHouse - Skills Build System"
+	@echo ""
+	@echo "Usage:"
+	@echo "  make          Build all skill zip files"
+	@echo "  make all      Same as 'make'"
+	@echo "  make clean    Remove all built zip files"
+	@echo "  make list     List all detected deploy skills"
+	@echo "  make link     Symlink all deploy skills into ~/.claude/skills"
+	@echo "  make unlink   Remove those symlinks (leaves real dirs alone)"
+	@echo "  make relink   unlink + link"
+	@echo "  make links    Show current link state"
+	@echo "  make help     Show this help"
+	@echo ""
+	@echo "Output: releases/<skill-name>.zip"
+	@echo ""
+	@echo "Override link destination: make link CLAUDE_SKILLS_DIR=./.claude/skills"
diff --git a/altinity-deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/SKILL.md b/altinity-deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/SKILL.md
diff --git a/...deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/assets/find-latest-versions.sh b/...deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/assets/find-latest-versions.sh
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+#
+# find-latest-versions.sh
+#
+# Discover the latest ClickHouse build versions by querying GitHub releases.
+# Prints one line per matching tag, sorted by version number (highest first).
+#
+# Note: "highest version" is determined by version-sort on the tag, NOT by
+# publication date. For Altinity Stable in particular, older lines (e.g. 24.8
+# LTS) receive ongoing patch backports, so the most-recently-published tag may
+# not be the highest version number. This script returns the highest version.
+#
+# Usage:
+#   ./find-latest-versions.sh                    # all flavors, top 1 each
+#   ./find-latest-versions.sh official           # only ClickHouse Official
+#   ./find-latest-versions.sh stable             # only Altinity Stable
+#   ./find-latest-versions.sh antalya            # only Altinity Antalya
+#   ./find-latest-versions.sh fips               # only Altinity FIPS
+#   COUNT=5 ./find-latest-versions.sh stable     # show top 5 by version number
+#   ARCH=aarch64 ./find-latest-versions.sh       # filter to aarch64 (info only)
+#
+# Auth:
+#   Uses `gh` CLI if available (higher rate limits when authenticated).
+#   Falls back to unauthenticated `curl` (60 req/hr; sufficient for single
+#   lookups but will rate-limit on repeated `all` calls).
+#
+# Dependencies:
+#   - bash 4+ (associative arrays)
+#   - curl OR gh
+#   - jq
+#
+# Output contract:
+#   <flavor>  <tag>  <published_at>  <html_url>
+#
+# Exit codes:
+#   0 success (at least one match printed)
+#   1 usage error
+#   2 dependency missing
+#   3 GitHub query failed for at least one flavor
+#   4 no matching tags found
+
+set -euo pipefail
+
+#-----------------------------------------------------------------------------
+# Configuration — VERIFY before relying on these in production.
+# Repos and tag patterns can change over time. If a query returns nothing,
+# the most likely cause is that the pattern below no longer matches the
+# current release tags.
+#-----------------------------------------------------------------------------
+
+declare -A REPOS=(
+    [official]="ClickHouse/ClickHouse"
+    [stable]="Altinity/ClickHouse"
+    [antalya]="Altinity/ClickHouse"
+    [fips]="Altinity/ClickHouse"
+)
+
+declare -A TAG_PATTERNS=(
+    # Patterns use awk extended regex; [.] matches a literal dot.
+    # Upstream tags look like v24.8.14.10459-stable or v25.1.1.123-lts.
+    [official]='^v[0-9]+[.][0-9]+[.][0-9]+[.][0-9]+(-(stable|lts|prestable|testing))?$'
+    # Altinity Stable tags carry an .altinitystable suffix.
+    [stable]='[.]altinitystable$'
+    # Altinity Antalya tags carry an .altinityantalya suffix.
+    [antalya]='[.]altinityantalya$'
+    # Altinity FIPS tags carry an .altinityfips suffix.
+    [fips]='[.]altinityfips$'
+)
+
+#-----------------------------------------------------------------------------
+
+COUNT="${COUNT:-1}"
+ARCH="${ARCH:-}"
+FLAVOR="${1:-all}"
+
+require() {
+    command -v "$1" >/dev/null 2>&1 || {
+        echo "error: '$1' is required but not found in PATH." >&2
+        exit 2
+    }
+}
+
+require jq
+if ! command -v gh >/dev/null 2>&1; then
+    require curl
+fi
+
+fetch_releases() {
+    local repo="$1"
+    if command -v gh >/dev/null 2>&1; then
+        gh api -H "Accept: application/vnd.github+json" \
+            "/repos/${repo}/releases?per_page=100"
+    else
+        curl -fsS -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${repo}/releases?per_page=100"
+    fi
+}
+
+print_flavor() {
+    local flavor="$1"
+    local repo="${REPOS[$flavor]:-}"
+    local pattern="${TAG_PATTERNS[$flavor]:-}"
+
+    if [[ -z "$repo" ]]; then
+        printf '%-9s  (no public GitHub repo configured — verify with Altinity)\n' "$flavor"
+        return
+    fi
+
+    local json
+    if ! json=$(fetch_releases "$repo" 2>/dev/null); then
+        printf '%-9s  ERROR querying %s (rate-limited or network failure)\n' "$flavor" "$repo" >&2
+        FAILED=1
+        return
+    fi
+
+    # Emit tab-separated rows: tag\tpublished_at\thtml_url, then filter on
+    # the tag (first column) only so URL/date contents can't accidentally
+    # match the pattern. Sort version-descending on the tag column so the
+    # highest version number is first (NOT the most recently published).
+    local rows
+    rows=$(echo "$json" \
+        | jq -r '.[] | [.tag_name, .published_at, .html_url] | @tsv' \
+        | awk -F'\t' -v pat="$pattern" '$1 ~ pat' \
+        | sort -t$'\t' -k1,1 -V -r \
+        | head -n "$COUNT" || true)
+
+    if [[ -z "$rows" ]]; then
+        printf '%-9s  no tags matched pattern: %s\n' "$flavor" "$pattern"
+        NO_MATCH=$((NO_MATCH + 1))
+        return
+    fi
+
+    while IFS=$'\t' read -r tag published_at url; do
+        printf '%-9s  %-40s  %s  %s\n' "$flavor" "$tag" "${published_at%T*}" "$url"
+        FOUND=$((FOUND + 1))
+    done <<< "$rows"
+}
+
+FOUND=0
+NO_MATCH=0
+FAILED=0
+
+case "$FLAVOR" in
+    all)
+        for f in official antalya stable fips; do
+            print_flavor "$f"
+        done
+        ;;
+    official|antalya|stable|fips)
+        print_flavor "$FLAVOR"
+        ;;
+    -h|--help)
+        sed -n '2,/^set -/p' "$0" | sed 's/^# \{0,1\}//' | head -n -1
+        exit 0
+        ;;
+    *)
+        echo "error: unknown flavor: $FLAVOR" >&2
+        echo "usage: $0 [official|antalya|stable|fips|all]" >&2
+        exit 1
+        ;;
+esac
+
+if [[ -n "$ARCH" ]]; then
+    echo
+    echo "note: ARCH=$ARCH set; this script reports tags only — confirm architecture coverage"
+    echo "      via the registry / repo (e.g. 'docker manifest inspect <image>')."
+fi
+
+if [[ "$FAILED" -eq 1 ]]; then
+    exit 3
+fi
+if [[ "$FOUND" -eq 0 ]]; then
+    exit 4
+fi
+exit 0
diff --git a/...-deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/references/INDEX.md b/...-deploy-clickhouse/skills/altinity-deploy-clickhouse-builds/references/INDEX.md
@@ -0,0 +1,102 @@
+# Documentation References — ClickHouse Build Selection
+
+Canonical sources Claude should consult to verify facts that change over time
+(repo paths, supported architectures, distribution coverage, FIPS support
+matrix, current versions). Each entry is a pointer; fetch the URL with
+`WebFetch` when current data is needed.
+
+---
+
+## Build Flavors
+
+### Altinity Antalya Builds — feature-forward Altinity track
+- **Landing / overview:** https://altinity.com/blog/getting-started-with-altinitys-project-antalya
+- **Documentation:** https://docs.altinity.com/altinityantalya/
+- **GitHub releases (Antalya tags):** https://github.com/Altinity/ClickHouse/releases?q=altinityantalya
+- **Use when:** user asks about Antalya feature scope (OAuth/OIDC, swarm clusters, Iceberg/Parquet reads, tiered storage to Iceberg), version cadence, or upstream-compatibility statement.
+
+### Altinity Stable Builds — long-term-support Altinity track
+- **Landing:** https://altinity.com/altinity-stable/
+- **Documentation:** https://docs.altinity.com/altinitystablebuilds/
+- **GitHub releases (Stable tags):** https://github.com/Altinity/ClickHouse/releases?q=altinitystable
+- **Use when:** user asks about supported Stable lines, support window, qualification process, security backports, EOL dates.
+
+### Altinity FIPS Builds — FIPS 140-3 compatible Altinity track
+- **Landing page and documentation:** https://docs.altinity.com/altinitystablebuilds/fips-compatible-altinity-builds/
+- **GitHub releases (FIPS tags):** https://github.com/Altinity/ClickHouse/releases?q=altinityfips
+- **Use when:** user asks about FIPS 140-3 scope, validated module identity, supported feature surface, subscription requirements, compliance evidence.
+
+### ClickHouse Official Builds — upstream from ClickHouse, Inc.
+- **Documentation root:** https://clickhouse.com/docs
+- **Release notes / changelog:** https://clickhouse.com/docs/whats-new/changelog
+- **GitHub releases:** https://github.com/ClickHouse/ClickHouse/releases
+- **Use when:** user asks about upstream version policy, LTS tags, feature availability per upstream version, EOL.
+
+---
+
+## Artifact Locations
+
+### Container registries
+- **Altinity server image:** https://hub.docker.com/r/altinity/clickhouse-server
+- **Altinity Keeper image:** https://hub.docker.com/r/altinity/clickhouse-keeper
+- **ClickHouse Inc. server image:** https://hub.docker.com/r/clickhouse/clickhouse-server
+- **ClickHouse Inc. Keeper image:** https://hub.docker.com/r/clickhouse/clickhouse-keeper
+- **Use when:** verifying that a tag exists, listing available tags by flavor suffix, or confirming multi-arch coverage.
+
+### Package & tarball repositories
+- **ClickHouse Inc. packages:** https://packages.clickhouse.com
+- **ClickHouse Inc. install docs:** https://clickhouse.com/docs/install
+- **Altinity build host (DEB / RPM / tarball):** https://builds.altinity.cloud
+- **Altinity install / packaging docs:** https://docs.altinity.com/altinitystablebuilds/stablequickstartguide/
+- **Use when:** configuring apt/yum/dnf repos, downloading tarballs, or finding the canonical install command for a given OS.
+
+### GitHub source / release tracking
+- **ClickHouse, Inc. repo:** https://github.com/ClickHouse/ClickHouse
+- **Altinity ClickHouse repo (Stable, Antalya, FIPS releases):** https://github.com/Altinity/ClickHouse
+- **Altinity clickhouse-operator (K8s):** https://github.com/Altinity/clickhouse-operator
+- **Use when:** discovering latest tags, reading release notes, or locating a specific commit / SHA.
+
+---
+
+## Architecture & Build Support
+
+- **ClickHouse system requirements:** https://clickhouse.com/docs/install#system-requirements
+- **ClickHouse supported platforms / OS:** https://clickhouse.com/docs/operations/tips
+- **Altinity build support matrix:** https://docs.altinity.com/altinitystablebuilds/
+- **Use when:** user asks whether a specific OS, kernel version, or architecture is supported; or whether multi-arch images cover their target.
+
+---
+
+## Compliance & Support
+
+### FIPS 140-3 background
+- **NIST CMVP program (validations search):** https://csrc.nist.gov/projects/cryptographic-module-validation-program
+- **NIST FIPS 140-3 standard:** https://csrc.nist.gov/publications/detail/fips/140/3/final
+- **Use when:** explaining what FIPS 140-3 means, validating a vendor's certificate number, or confirming that a specific cryptographic module is in-scope.
+
+### Altinity support
+- **Altinity support / subscriptions:** https://altinity.com/support/
+- **Altinity contact for FIPS-specific questions:** https://altinity.com/contact
+- **Use when:** user asks about commercial support coverage, subscription tiers, or FIPS-validated artifact access.
+
+### Altinity Cloud
+- **Altinity BYOC cloud subscriptions:** (Runs in user account) https://altinity.com/managed-clickhouse/bring-your-own-cloud/
+- **Altinity SaaS cloud subscriptions:** (Runs in Altinity account) https://altinity.com/managed-clickhouse/
+- **Altinity contact for cloud-specific questions:** https://altinity.com/contact
+- **Use when:** User asks for an Altinity-managed service for ClickHouse, BYOC vs. SaaS choice, cloud subscription tiers. 
+
+---
+
+## Latest-Version Discovery
+
+The `assets/find-latest-versions.sh` script in this skill is the primary
+mechanism for discovering current versions across all four flavors. It
+queries GitHub releases directly. See `SKILL.md` Step 5 for usage.
+
+---
+
+## Maintenance
+
+When a `(verify)` link is confirmed (or corrected), remove the marker.
+When a link returns 404 or redirects unexpectedly, replace it with the
+current canonical URL and note the change in the commit message.