Updates

.claude/skills/altinity-kb-article-writer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: altinity-kb-article-writer
+description: Write new Altinity Knowledge Base articles in the repository's established style, including section selection, target markdown file path, Hugo frontmatter, and full draft content. Use when asked to create or draft KB articles for ClickHouse topics in this repository.
+---
+
+# Altinity KB Article Writer
+
+Write a complete KB-ready draft that matches this repository's style.
+
+## Use this workflow
+
+1. Identify article intent from the prompt:
+- Problem statement or topic
+- Target audience (operator, developer, data engineer, mixed)
+- Desired depth (`quick how-to`, `troubleshooting`, `deep explanation`)
+- Environment constraints (Cloud, Kubernetes, replication, version constraints)
+
+2. Select the best section using `references/section-map.md`.
+
+3. Propose the destination path in this format:
+- `content/en/<section>/<slug>.md`
+
+4. Build frontmatter using the defaults in `references/kb-style-guide.md`:
+- Required: `title`, `linkTitle`, `description`
+- Optional: `keywords`, `weight` (only when explicitly needed for ordering)
+
+5. Draft the article using `references/article-template.md` and style rules:
+- Short practical intro
+- Clear `##` and `###` headings
+- Language-tagged code fences (`sql`, `bash`, `yaml`, `xml`, etc.)
+- Actionable examples and caveats
+- Related resources at the end
+
+6. Run a self-review using `references/qa-checklist.md`.
+
+7. Return output in this order:
+- Suggested path
+- Full markdown (frontmatter + body)
+- QA checklist result (pass/fail bullets)
+- If section routing is ambiguous, include one alternative path
+
+## Authoring rules
+
+- Prefer practical, operator-useful guidance over theory.
+- Use concise technical English.
+- Preserve ClickHouse naming and SQL syntax exactly.
+- Do not add uncommon frontmatter fields (`alias`, `manualLink`, redirects) unless explicitly requested.
+- Avoid unsupported claims; if unsure, state assumptions.
+
+## File and slug rules
+
+- Use lowercase kebab-case slugs.
+- Prefer `altinity-kb-<topic>.md` in sections where that convention is common.
+- If a likely collision exists, append a disambiguator (for example `-v2` or `-on-kubernetes`).
+

.claude/skills/altinity-kb-article-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Altinity KB Article Writer"
+  short_description: "Draft KB articles in local Altinity style"
+  default_prompt: "Use $altinity-kb-article-writer to draft a new KB article with section path, frontmatter, and full markdown in this repository style."

.claude/skills/altinity-kb-article-writer/references/article-template.md

@@ -0,0 +1,65 @@
+# KB Article Template
+
+Use this template as the baseline shape, then adjust to topic.
+
+```markdown
+---
+title: "<Human title>"
+linkTitle: "<Navigation title>"
+description: >
+    <One sentence summary of the page purpose.>
+keywords:
+  - <optional-keyword-1>
+  - <optional-keyword-2>
+---
+
+<Short practical intro: what this solves, when to use it.>
+
+## Problem
+
+<Describe symptom, failure mode, or task objective.>
+
+## Solution
+
+<Explain approach and why it works.>
+
+### Step 1: <Name>
+
+```sql
+-- or bash/yaml/etc
+```
+
+<Explain expected output or interpretation.>
+
+### Step 2: <Name>
+
+```sql
+-- or bash/yaml/etc
+```
+
+<Explain expected output or interpretation.>
+
+## Validation
+
+<How to confirm the fix/design works. Include checks and thresholds if relevant.>
+
+## Caveats
+
+- <Version caveat>
+- <Performance caveat>
+- <Operational caveat>
+
+## Related resources
+
+- [<Internal KB link>](</altinity-kb-.../>)
+- [<Official docs link>](https://clickhouse.com/docs/)
+```
+
+## Minimal variant
+
+For short pages (for example function or setting notes), keep:
+- frontmatter
+- short intro
+- one or two focused sections
+- at least one example block
+

.claude/skills/altinity-kb-article-writer/references/kb-style-guide.md

@@ -0,0 +1,71 @@
+# Altinity KB Style Guide (Repository Baseline)
+
+This guide captures the dominant style used under `content/en/**` in this repository.
+
+## Frontmatter defaults for normal KB pages
+
+Use:
+
+```yaml
+---
+title: "Page title"
+linkTitle: "Left nav title"
+description: >
+    One-sentence summary.
+---
+```
+
+Optional:
+- `keywords`: list of 2-5 useful search terms
+- `weight`: only if explicit ordering in section navigation is needed
+
+Avoid unless explicitly requested:
+- `manualLink`, `alias`/`aliases`, redirect `type`/`target`, `draft`
+
+## Content structure
+
+- Start with a short practical intro (1-3 paragraphs).
+- Use `##` for major sections and `###` for subsections.
+- Keep sections task-oriented:
+  - Context/problem
+  - Steps or examples
+  - Validation or expected outcome
+  - Caveats / edge cases
+
+## Code and command blocks
+
+- Use fenced blocks with language tags:
+  - `sql`, `bash`, `yaml`, `xml`, `json`, `text`
+- Keep runnable snippets minimal and focused.
+- Prefer realistic table/settings names.
+
+## Length
+
+KB articles are short. Median is ~430 words; 90% are under 1100.
+
+- Target under 1000 words; over 1500 needs a clear reason.
+- Cut mechanism write-ups, source-code walkthroughs, stack traces, and evidence
+  tables — those belong in the PR description. Give the operational rule and its
+  version scope, not the derivation.
+
+See the length budget in `AGENTS.md` for the authoritative wording.
+
+## Writing tone
+
+- Technical and direct.
+- Emphasize actionable guidance for operators and engineers.
+- Prefer concrete examples over abstract descriptions.
+- Use concise English; avoid marketing wording.
+
+## Links
+
+- Add internal KB links when relevant.
+- Add official external links for docs/blog/release notes.
+- End with a "Related resources" section when useful.
+
+## Filename and slug
+
+- Lowercase kebab-case filename.
+- Prefer `altinity-kb-<topic>.md` where section convention suggests it.
+- Place in best-fit section under `content/en`.
+

.claude/skills/altinity-kb-article-writer/references/qa-checklist.md

@@ -0,0 +1,43 @@
+# QA Checklist for Generated KB Articles
+
+Run this checklist before returning output.
+
+This checklist covers mechanical correctness only. Also answer the **Review
+questions** in `AGENTS.md` — they cover whether the reader needs the content, how
+you know the examples work, and whether the article actually solves the problem
+end-to-end. A draft can pass every box below and still be the wrong article.
+
+## Metadata
+
+- [ ] Path is under `content/en/<section>/`.
+- [ ] Filename uses lowercase kebab-case.
+- [ ] Frontmatter has `title`, `linkTitle`, `description`.
+- [ ] Optional fields are justified (`keywords`, `weight`).
+- [ ] Uncommon fields are not present unless requested.
+
+## Structure and readability
+
+- [ ] Intro clearly states problem and scope.
+- [ ] Headings are logical (`##` then `###`).
+- [ ] Steps or examples are easy to follow.
+- [ ] Caveats or assumptions are explicit.
+
+## Technical quality
+
+- [ ] SQL/commands are syntactically plausible.
+- [ ] Code fences include language tags.
+- [ ] Version-sensitive behavior is called out if relevant.
+- [ ] No unsupported claims are presented as facts.
+
+## Linking
+
+- [ ] Includes relevant internal KB links when possible.
+- [ ] Includes high-quality official external references when useful.
+
+## Final output contract
+
+- [ ] Output includes suggested path.
+- [ ] Output includes full markdown draft.
+- [ ] Output includes brief QA result (`PASS` or `FAIL` with reasons).
+- [ ] If routing was ambiguous, one alternative path is included.
+

.claude/skills/altinity-kb-article-writer/references/section-map.md

@@ -0,0 +1,48 @@
+# Section Map for `content/en`
+
+Select the section that best matches the user topic.
+
+## Primary routing rules
+
+- `altinity-kb-queries-and-syntax`
+  - SQL syntax, query behavior, joins, window functions, TTL syntax, query semantics
+- `altinity-kb-setup-and-maintenance`
+  - Operational troubleshooting, replication operations, backup/restore, upgrades in practice, cluster setup
+- `altinity-kb-schema-design`
+  - `ORDER BY`, `PARTITION BY`, materialized views, table modeling, codecs, LowCardinality design
+- `altinity-kb-integrations`
+  - Kafka, MySQL, Spark, BI tools, external systems and connectors
+- `altinity-kb-useful-queries`
+  - Reusable diagnostics queries against `system.*` and operational SQL snippets
+- `altinity-kb-dictionaries`
+  - External dictionaries, layouts, dictionary performance and configuration
+- `altinity-kb-functions`
+  - Function behavior, function-specific examples, expression patterns
+- `engines`
+  - Engine internals and engine-specific behavior (MergeTree family, Atomic, etc.)
+- `altinity-kb-kubernetes`
+  - Altinity Operator, Kubernetes deployment and networking issues
+- `upgrade`
+  - Upgrade strategy, compatibility notes, known upgrade pitfalls
+
+## Tie-break rules
+
+1. If article is mostly query text and reusable snippets, prefer `altinity-kb-useful-queries`.
+2. If article is mostly conceptual SQL behavior, prefer `altinity-kb-queries-and-syntax`.
+3. If topic is schema/key design, prefer `altinity-kb-schema-design`.
+4. If issue is runtime operations and incidents, prefer `altinity-kb-setup-and-maintenance`.
+5. If still ambiguous, choose the section with the highest overlap and provide one alternative path.
+
+## Path format
+
+Use:
+- `content/en/<section>/<slug>.md`
+
+Where:
+- `<slug>` is lowercase kebab-case
+- Prefix with `altinity-kb-` when it fits section naming patterns
+
+Examples:
+- `content/en/altinity-kb-useful-queries/altinity-kb-find-heavy-merges.md`
+- `content/en/altinity-kb-schema-design/altinity-kb-choosing-order-by-for-events.md`
+

.github/workflows/cla.yml

@@ -12,7 +12,7 @@ jobs:
       - name: "CLA Assistant"
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
         # Beta Release
-        uses: cla-assistant/github-action@v2.1.3-beta
+        uses: cla-assistant/github-action@v2.4.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # the below token should have repo scope and must be manually added by you in the repository's secret

.github/workflows/gh-pages.yml

@@ -8,36 +8,36 @@ on:
 
 jobs:
   deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Git checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           submodules: true  # Fetch Hugo themes (true OR recursive)
           fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
           ref: main
 
       - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v2
+        uses: peaceiris/actions-hugo@v3
         with:
-          hugo-version: 'latest'
+          hugo-version: '0.128.2'
           extended: true
 
       - name: Cache Hugo modules
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: /tmp/hugo_cache
           key: ${{ runner.os }}-hugomod-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-hugomod-
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
 
       - name: Cache dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
@@ -51,7 +51,7 @@ jobs:
         # run: hugo --gc
 
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,5 +1,13 @@
+docs/
 *.DS_Store*
 node_modules/
 .vscode/*
 yarn.lock
 .hugo_build.lock
+/.idea/.gitignore
+/.idea/altinityknowledgebase.iml
+/resources/_gen/assets/scss/scss/main.scss_3f90599f3717b4a4920df16fdcadce3d.content
+/resources/_gen/assets/scss/scss/main.scss_3f90599f3717b4a4920df16fdcadce3d.json
+/.idea/modules.xml
+/.idea/vcs.xml
+/.idea/inspectionProfiles/Project_Default.xml