Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,6 @@ vars.ps1
# Claude Code local settings
.claude/settings.local.json
__pycache__/

# StackQL MCP server logs (any directory)
stackql_mcp_server_*.log
7 changes: 4 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Project guide for Claude Code working in this repository. Tells you what this si

stackql.io is the marketing and documentation site for StackQL, built on Docusaurus 3.10. Three audiences:

- **Humans** - default site nav. This is a docs-only site: the docs tree is the site root (`/installing-stackql`, `/providers`, `/getting-started/*`, `/command-line-usage/*`, `/mcp/*`, `/language-spec/*`, `/developers/*`, `/quick-starts/*`) and [docs/index.md](docs/index.md) is the homepage. Blog at `/blog/<section>/*` (three sections, see "The blog" below). Two top-level React pages remain: `/privacy` and `/contact-us` (a real page: community channels, email, phone and address). There are no meta-refresh stub pages: every alias URL is a Netlify 301 (see "Redirects are Netlify 301s, never pages" below).
- **Humans** - default site nav. This is a docs-only site: the docs tree is the site root (`/installing-stackql`, `/providers`, `/getting-started/*`, `/command-line-usage/*`, `/mcp/*`, `/language-spec/*`, `/developers/*`, `/quick-starts/*`) and [docs/index.md](docs/index.md) is the homepage. Blog at `/blog/<section>/*` (three sections, see "The blog" below). Four top-level pages remain: `/privacy`, `/terms` and `/support` (MDX in `src/pages`) and `/contact-us` (a React page: community channels, email, phone and address). The three MDX pages are the privacy, terms and support URLs that the ChatGPT and Claude plugin directory listings point at (issue #305), so keep those paths stable. There are no meta-refresh stub pages: every alias URL is a Netlify 301 (see "Redirects are Netlify 301s, never pages" below).
- **AI agents and answer engines** - a parallel content surface at `/ai/*` (canonical definitions, comparisons, how-tos, FAQs, troubleshooting, etc.) reachable by deep link, via `llms.txt` and from one "AI Reference" link in the footer, but **not** from the header nav. The footer link exists so the tree has a crawl path: with no internal link at all Google left its 44 sitemap URLs as "Discovered - currently not indexed".
- **LLM crawlers** - `llms.txt` and `llms-full.txt` at site root; a plain-markdown twin (`/foo.md`) for every doc and blog page, advertised from each page by `<link rel="alternate" type="text/markdown">`.

Expand Down Expand Up @@ -39,7 +39,7 @@ The classic preset's docs instance has `routeBasePath: '/'` (Docusaurus docs-onl
- Inbound `/docs/*` links are Netlify 301s to the same path without the prefix (`/docs` -> `/`, `/docs.md` -> `/index.md`, `/docs/*` -> `/:splat`). Those rules sit below the `/docs/query-library/*` proxy and the specific legacy `/docs/...` rules in [netlify.toml](netlify.toml). Netlify applies the first matching rule, so keep that order.
- The query library stays proxied at `/docs/query-library/*`: it is a separate site whose `baseUrl` is a cross-repo contract (see "The query library" below). It is the only thing left under `/docs`.
- Internal links use root paths (`/installing-stackql`, never `/docs/installing-stackql`). `onBrokenLinks: 'throw'` catches relative mistakes; absolute `stackql.io/docs/...` links need a grep.
- Root-level routes that are not docs: `/blog/*`, `/ai/*`, `/privacy`, `/contact-us`, `/search`, and the Netlify 301 aliases (`/install`, `/downloads`, `/stackqldocs`, `/stackql-deploy`, `/features`, `/tutorials`, `/cookbooks`, `/providers/<slug>`, `/registry/*`). A new doc whose slug collides with one of these would clash with it (a built file shadows a Netlify rule), so check before adding root-level docs.
- Root-level routes that are not docs: `/blog/*`, `/ai/*`, `/privacy`, `/terms`, `/support`, `/contact-us`, `/search`, and the Netlify 301 aliases (`/install`, `/downloads`, `/stackqldocs`, `/stackql-deploy`, `/features`, `/tutorials`, `/cookbooks`, `/providers/<slug>`, `/registry/*`). A new doc whose slug collides with one of these would clash with it (a built file shadows a Netlify rule), so check before adding root-level docs.
- Getting Started and Command Line Usage are sidebar categories with generated index pages (`/getting-started`, `/command-line-usage`), so every major section has a landing page Google can surface as a sitelink: installation, providers, getting started, command line usage, MCP.

## AEO architecture
Expand Down Expand Up @@ -148,6 +148,7 @@ The preset blog is disabled (`blog: false`). Three `@docusaurus/plugin-content-b
- `/llms.txt` and `/llms-full.txt` -> `text/plain; charset=utf-8`
- All three get `X-Robots-Tag: index, follow` and `max-age=300` cache
- `/providers.json` (the published provider catalog, see "Provider catalog" below) -> `application/json; charset=utf-8`, the same 5-minute cache and `Access-Control-Allow-Origin: *`
- `/.well-known/openai-apps-challenge` -> `text/plain; charset=utf-8`, no cache, `noindex`. The file is not in the repo: when the OpenAI plugin portal asks for domain verification, save the token it shows as `static/.well-known/openai-apps-challenge` (token only, no trailing newline). Docusaurus copies `static/` dotfiles into the build.

Without these rules Netlify serves `.md` as `application/octet-stream` (browsers download instead of display) and crawlers may skip it.

Expand Down Expand Up @@ -276,7 +277,7 @@ When the live site changes, AI fetch tools (Claude.ai's web_fetch, ChatGPT's bro

### `/blog`, `/blog/<section>`, `/contact-us`, `/privacy`, generated category indexes

These routes are React pages, the blog landing plugin route, blog list pages, or generated category index pages (`/getting-started`, `/command-line-usage`, `/quick-starts/*`) with **no source markdown**. The AEO plugin correctly does not emit `.md` companions for them. They appear in the human nav but not in `llms.txt` or anywhere requiring a `.md` twin. This is by design - do not "fix" by trying to force `.md` emission. The navbar and footer link to the canonical pages (`/`, `/installing-stackql`, `/providers`), so crawlers see real site structure; keep it that way when adding chrome links. `/install`, `/downloads`, `/stackqldocs`, `/stackql-deploy`, `/features`, `/tutorials`, `/cookbooks`, `/providers/<slug>` and `/registry/<name>` are Netlify 301s, so they 404 under `yarn serve`. `/privacy` is an MDX page and does get a companion; `/contact-us` is a React page and does not.
These routes are React pages, the blog landing plugin route, blog list pages, or generated category index pages (`/getting-started`, `/command-line-usage`, `/quick-starts/*`) with **no source markdown**. The AEO plugin correctly does not emit `.md` companions for them. They appear in the human nav but not in `llms.txt` or anywhere requiring a `.md` twin. This is by design - do not "fix" by trying to force `.md` emission. The navbar and footer link to the canonical pages (`/`, `/installing-stackql`, `/providers`), so crawlers see real site structure; keep it that way when adding chrome links. `/install`, `/downloads`, `/stackqldocs`, `/stackql-deploy`, `/features`, `/tutorials`, `/cookbooks`, `/providers/<slug>` and `/registry/<name>` are Netlify 301s, so they 404 under `yarn serve`. `/privacy`, `/terms` and `/support` are MDX pages under `src/pages`; the AEO plugin mirrors only the docs and blog instances, so they get no companion either (checked in the November 2026 build), and `/contact-us` is a React page and does not.

### Mobile breakpoint for Ask AI

Expand Down
4 changes: 2 additions & 2 deletions ai-content/architecture/stackql-architecture-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ faq:
- question: Where does the actual SQL processing happen?
answer: In two stages. The query engine pushes whatever it can to the provider API (routing parameters, supported predicates), then materializes API responses into the SQL backend - embedded SQLite by default, optionally an external PostgreSQL - where joins, aggregates, sorting, and expressions are executed.
- question: How does StackQL know how to call each provider's API?
answer: From provider definitions in the StackQL Registry - versioned, extended-OpenAPI specifications describing each provider's services, resources, methods, parameters, authentication, and pagination. Definitions are pulled on demand with REGISTRY PULL and interpreted by the provider SDK (any-sdk); no provider-specific code is compiled into the engine.
answer: From provider definitions in the StackQL Registry - versioned, extended-OpenAPI specifications describing each provider's services, resources, methods, parameters, authentication, and pagination. Definitions are pulled on demand with REGISTRY PULL and interpreted by the provider SDK (omnisdk); no provider-specific code is compiled into the engine.
- question: Is StackQL a single binary?
answer: Yes. The engine, parser, provider SDK, embedded SQL backend, PostgreSQL wire server, and MCP server ship in one Go binary for macOS, Linux, and Windows.
---
Expand All @@ -28,7 +28,7 @@ StackQL is a single Go binary implementing a SQL engine over cloud and SaaS prov

**Query engine.** Plans the AST: decides what is pushed down to the provider API (routing parameters, supported predicates) versus what is processed locally, coordinates API execution - including parallel fan-out when a query spans regions or multiple calls - and aggregates results.

**Provider SDK (any-sdk).** The generic API client. It loads provider specifications from the registry, handles per-provider authentication, builds HTTP requests from query parameters, walks paginated responses regardless of pagination scheme (cursor, offset, token), and relationalizes JSON responses into rows.
**Provider SDK (omnisdk).** The generic API client, which replaced any-sdk in StackQL v1.0. It loads provider specifications from the registry, handles per-provider authentication, plans each statement as a graph of provider exchanges, builds HTTP requests from query parameters, pushes supported predicates and limits into those requests, walks paginated responses regardless of pagination scheme (cursor, offset, token), and relationalizes JSON responses into rows as they arrive.

**SQL backend.** Materialized API results land in an embedded SQLite database by default (an external PostgreSQL can be configured instead), where joins - including cross-provider joins - aggregates, sorting, subqueries, and expressions execute with full SQL semantics.

Expand Down
Loading