Public docs site for the SQL Browser (docs.altinity.com)

[BorisTyshkevich]

Plan: Public docs/marketing site for Altinity SQL Browser

Context

altinity-sql-browser is a zero-dependency, OAuth-gated ClickHouse SQL browser
that builds to a single self-contained dist/sql.html. It has grown a rich
feature set (chart view, EXPLAIN pipeline graph, full schema-lineage graph,
autocomplete, find/replace, saved-query Library, share links) and three
distinct deployment modes — but there is no public site explaining any of
it. The README is the only narrative, and there are zero product
screenshots anywhere in the repo.

GitHub Pages is already live for this repo (verified via the Pages API):

• build_type: legacy (Jekyll, "deploy from a branch")
• source: main branch, /docs folder
• live URL: http://docs.altinity.com/altinity-sql-browser/ (custom domain, HTTPS cert approved)

So the site must live in /docs on main, and committing there publishes it.

Goal: a polished, multi-page static site covering the three deployment
modes (with the curl → local app install front-and-center), the full
feature set, and real screenshots captured from the live demo + the local
Python runner.

Decisions (confirmed with user)

• Multi-page site (Home + Features + Deployment + Local app + Screenshots).
• Hand-built static HTML/CSS, no framework — reuse the app's design tokens
  (teal #0079AD/#005F8A, system font stack, dark+light). Add .nojekyll
  so Pages serves the files verbatim (no Jekyll processing).
• After approval: post the plan as a GitHub issue, build the full site
  (with screenshots) on main, commit directly to main (deploys live).

Constraints / things to respect

• /docs already holds engineering markdown (ARCHITECTURE.md,
  DEPLOYMENT.md, CLICKHOUSE-OAUTH.md, CLICKHOUSE-OSS-OAUTH.md,
  ASSET-DISTRIBUTION.md, ONTIME-CHART-DEMO.md). Do not move or rename
  them — the root README.md links to them by relative path. The new site
  links out to these (GitHub blob URLs) for deep technical reading.
• Adding .nojekyll means those .md files serve as raw text via Pages (they
  are not the Pages landing content today anyway). Acceptable — they remain
  rendered on github.com and linked from the README.
• Keep the project ethos: no third-party requests (no CDN fonts/JS), small
  footprint, accessible HTML.

Proposed /docs layout

docs/
  .nojekyll                ← serve static files verbatim
  index.html               ← Home / landing (hero, value prop, 3 modes, CTA)
  features.html            ← full feature tour (grouped, screenshot-led)
  deployment.html          ← the 3 deployment modes compared + recipes
  local-app.html           ← "Install by curl as a local app" deep-dive
  screenshots.html         ← gallery (all captured shots, dark+light)
  assets/
    site.css               ← shared styles built from the app's design tokens
    site.js                ← tiny: nav toggle, theme toggle, lightbox (no deps)
    logo.svg / favicon     ← gradient-"A" mark from the design system
    img/                   ← captured screenshots (see Screenshot capture)
  (existing *.md stay in place, untouched)

Shared header/nav + footer inlined into each page (no build step; ~5 pages).

Content sourcing (already gathered — no re-exploration needed)

• Three deployment modes (from README.md, install.sh,
  build/local.py, build/bundle.sh, deploy/install.sh,
  deploy/http_handlers.xml):
  1. ClickHouse-hosted — SPA + config.json uploaded to user_files/,
     served by http_handlers.xml at /sql; OAuth (PKCE) via any OIDC IdP;
     queries carry the user's JWT. Installed by deploy/install.sh.
  2. Local app via curl | sh — install.sh downloads the latest release
     bundle (prebuilt sql.html + zero-dep build/local.py runner), installs
     a launcher to ~/.local/bin/altinity-sql-browser; runner serves
     localhost:8900/sql, reads ~/.clickhouse-client/config.xml, probes
     ports (443/8443, 8123/80). Needs only python3. This is the headline
     "local app" story.
  3. Local dev — npm run local / npm run dev for contributors.
• Feature inventory (from src/ui/* + src/core/*): table/JSON/chart
  views, 5-tab EXPLAIN incl. dagre pipeline graph, schema-lineage graph
  (drag-move, undo/redo, detail pane), autocomplete + signature help + hover
  docs from system.*, find/replace (regex), bracket matching, multi-tab
  workspace, saved-query Library + history + import/export (JSON/MD/SQL), share
  links, SSO (OIDC PKCE) + passwordless/basic, streaming results + live stats,
  CSV/TSV export, dark/light themes.
• The curl command (verbatim, from install.sh / README.md:187):
  curl -fsSL https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/install.sh | sh

Screenshot capture (real, not mockups)

Reachability already verified: live demo 200, ClickHouse public playground
200, Chrome DevTools on :9222 200, python3 + build deps present.

Two capture sources, via the chrome-devtools MCP (agent Chrome on :9222 — never launch Chrome myself):

1. Local-app mode (also the "curl local app" screenshots):
   npm run local builds dist/sql.html and boots build/local.py on
   localhost:8900. Point it at the public ClickHouse playground
   (sql-clickhouse.clickhouse.com, user play, passwordless) and the
   antalya demo (demo/demo basic) so I can log in without SSO and
   reach every feature. Capture: connection picker, main workspace
   (editor+sidebar+results), autocomplete popup, chart view (load
   examples/ontime-charts.json via File ▾ → Open), EXPLAIN pipeline graph,
   schema-lineage graph, find/replace, Library panel — in dark (primary)
   and a few in light.
2. Hosted login screen: navigate agent Chrome to
   https://antalya.demo.altinity.cloud/sql and screenshot the branded
   login/IdP screen (renders pre-auth).

Save PNGs to docs/assets/img/, reference them in features.html,
local-app.html, and screenshots.html. Use resize_page to a clean
viewport (e.g. 1440×900) before each shot; full-page where useful.

Build steps (after approval)

1. Post the plan as a GitHub issue on Altinity/altinity-sql-browser
   (title e.g. "Public docs site for the SQL Browser (docs.altinity.com)"),
   body = this plan, via gh issue create.
2. Build dist/sql.html (npm run build) and boot the local runner; capture
   all screenshots (above) into docs/assets/img/.
3. Author docs/.nojekyll, docs/assets/site.css (tokens lifted from
   src/styles.css), docs/assets/site.js, logo/favicon, and the 5 HTML
   pages with shared nav/footer and the screenshots embedded.
4. Distill docs/DEPLOYMENT.md + docs/CLICKHOUSE-OAUTH.md into the
   deployment/local-app pages; link the full markdown for depth.
5. Commit directly to main (Pages publishes from main /docs). Use a
   clear commit message; reference the issue. Verify the live site renders.

Verification

• Open http://localhost preview of docs/index.html and each page in agent
  Chrome; confirm nav, theme toggle, lightbox, and all <img> resolve (no
  broken links, no external requests — check DevTools network panel).
• Confirm the verbatim curl | sh command and the gh release download URLs
  on local-app.html are correct against install.sh.
• After committing to main, wait for the Pages build and load
  http://docs.altinity.com/altinity-sql-browser/; spot-check pages + images.
• npm test and npm run build must still pass (site is static, but confirm
  no accidental changes to src/ or build).

Files created / touched

• New: docs/.nojekyll, docs/index.html, docs/features.html,
  docs/deployment.html, docs/local-app.html, docs/screenshots.html,
  docs/assets/site.css, docs/assets/site.js, docs/assets/logo.svg,
  docs/assets/favicon.*, docs/assets/img/*.png.
• Unchanged: all existing docs/*.md, src/*, build/*, deploy/*.
• External: one GitHub issue (the plan); commits to main.