PRDCT-502: add Semantic Layer documentation (private beta)

[jordanrburger]

What

Adds public documentation for the Semantic Layer (private beta) under AI Features:

• New page: /ai/semantic-layer/ — what the semantic layer is, the six semantic object types (semantic-model, semantic-dataset, semantic-metric, semantic-relationship, semantic-glossary, semantic-constraint), how AI assistants use it through the MCP Server's four read-only semantic tools (search_semantic_context, get_semantic_context, get_semantic_schema, validate_semantic_query), the typical discover → load → validate → query flow, and how to build/migrate models with the AI Kit plugins.
• AI Features index — new Semantic Layer entry.
• MCP Server page — Semantic Layer added to the Available Tools list.
• AI Kit page — documents the sl-toolkit and powerbi-to-sl plugins and adds them to the install snippet.
• Sidebar — _data/navigation.yml entry + regenerated src/sidebar.mjs (npm run gen:sidebar).

Accuracy notes

• Tool names, object types, and read-only behavior verified against keboola/mcp-server source (tools/semantic/).
• Plugin commands and behavior verified against the keboola/ai-kit plugin READMEs (plugins/sl-toolkit, plugins/powerbi-to-sl).
• The page presents the feature as private beta with enablement via the support team.

Verification

• npm run build clean (259 pages).
• node scripts/audit-phase2.mjs — no new issues on the touched pages (remaining flags are pre-existing).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 8, 2026 12:08am

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 2/5) · profile docs

Well-formed docs PR for the Semantic Layer, but nav-data changes and unverifiable product-behaviour claims require a maintainer.

Concerns:

• _data/navigation.yml: Nav/structure data change — always needs human per policy.
• src/content/docs/ai/semantic-layer/index.md: New product-behaviour claims (object types, MCP tools) unverifiable from diff.

Suggested reviewers: @keboola/docs

[jordanrburger]

We need to mention that this is feature-gated and must be turned on.

Also, we should make an explicit callout that Kai can automatically make use of the semantic layer if defined.

[jordanrburger]

Review summary

Verdict: needs a trivial rebase, then ready.

Content is clean — valid frontmatter (title+slug+description), unique slug ai/semantic-layer, :::caution[Private Beta] framing consistent across all four touched pages, sidebar correctly regenerated (not hand-edited), and the #restricting-tool-access anchor resolves.

Only blocker:

• One-file merge conflict in src/content/docs/ai/index.md. Both this PR and main inserted a new ### section at the same spot (after "MCP Server"). Main added "Machine-Readable API Index" (docs(ai): link machine-readable API index for agentic usage #1026); this PR adds "Semantic Layer". Resolution is trivial — keep both sibling sections, no overlap. (_data/navigation.yml does NOT conflict — the two edits are far apart and auto-merge.)

Product facts to verify (author checked against keboola/mcp-server + keboola/ai-kit, not verifiable from the diff): the six semantic object types; the four read-only MCP tools (search_semantic_context, get_semantic_context, get_semantic_schema, validate_semantic_query) and their availability under X-Read-Only-Mode; the private-beta enablement path (contact support@keboola.com); the powerbi-to-sl TMDL-export detail.

Automated review pass (Claude Code), flagged for a human maintainer — not an approval.

[cjayyy]

@jordanrburger What are u waiting for with this PR?

[jordanrburger]

@jordanrburger What are u waiting for with this PR?

Fair question 😅 I guess nothing. I have a few notes from David to add here. Then I'll merge it.

But if the UI is close to ready, maybe I should wait and update it with new info?

[linear-code]

PRDCT-502

AI-3610

[cjayyy]

@jordanrburger Shouldn't this be in production already?

[jordanrburger]

@jordanrburger Shouldn't this be in production already?

Yeah, it should :/ sry

[Iamfle4ka]

Reviewed this against current main and the live sources. The content was accurate when it was written — the product moved underneath it in the seven weeks since, and every blocker below is a change that landed after this PR opened. I've re-cut the page on current main with these fixed in #1103; take it over or close whichever of the two you prefer.

1. The enablement path no longer matches how the feature is reached. The mcp-semantic-tooling feature flag was deleted from keboola/mcp-server in 8ab508e2 (2026-07-10, merged via keboola/mcp-server#619) — two days after this PR opened — and replaced with project_has_semantic_models(), a per-request metastore probe that fails closed (src/keboola_mcp_server/mcp.py:103-117, applied at on_list_tools :1023-1025 and on_call_tool :1117-1125). The four tools appear only once the project already contains a semantic model. So a reader who follows L8 ("contact support to have it enabled") and L39 ("tools automatically appear") emails support, is told it is already on, connects, and still sees nothing — the in-product message they hit is "This project has no semantic models, so semantic tools are unavailable."

That also inverts the page's order: MCP usage (L37) comes before model building (L61), when the model has to exist first.

2. Two paths that exist today are missing. The page presents the two AI Kit plugins as the only way to build a model. main already documents a full kbagent semantic-layer command group (_data/cli/command-reference.md:2155+, surfaced on /cli/commands/) — omitting it is an add-alongside of something the docs already cover. And the Semantic Layer editor shipped in the UI (AI-3589), which is the "fix the copy that still calls the SL headless" item from your 07-27 project update.

3. get_semantic_schema doesn't return a schema. L35 and L45 tell readers (and their agents) to fetch the JSON Schema with it. It calls the bare api/v1/schema/{type} endpoint (tools/semantic/tools.py:723 passes no version; clients/metastore.py:94-96 only versions the path when given one), which returns a {"versions": [...]} listing. keboola/cli documents exactly this and calls it "an upstream gap we deliberately do NOT mirror".

4. /sl-build and /sl-validate --deep use the kbagent binary (sl-build.md Step 0). The install snippet doesn't mention it — without it /sl-build falls back to asking the user to describe their tables, and --deep is silently skipped.

5. Duplicate bullet, invisible in the diff. main gained - **Semantic layer** – Explore the project's semantic models and validate queries against them. in the MCP Server "Available Tools" list during the 75 commits this branch is behind. This PR appends a second bullet for the same category at mcp-server/index.md:255, with different capitalisation.

6. ai/ai-kit/index.md collides head-on with #1095 (agent/kbagent-marketplace-repoint) — same paragraph, same install block, same two plugin sections added twice.

Two notes not against this PR: CLAUDE.md:63 on main still says "don't document … semantic layer", which should go when either PR lands; and #1074 will move the #restricting-tool-access heading, so whichever semantic-layer page merges first, #1074 should carry the anchor when it rebases.

Verified correct and unchanged in #1103: the four tool names, all four registered readOnlyHint=True, the X-Read-Only-Mode interaction, the six object-type descriptions against the JSON schemas, the constraint severity enum, and both plugin descriptions.

[cjayyy]

Closing as superseded by #1103