From 0a517b2c13e2f04c1ff91109903ef226f96c794f Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <andreybavt@gmail.com>
Date: Fri, 29 May 2026 15:02:57 +0200
Subject: [PATCH] skill: document adding context sources; docs: one-shot
 full-demo path (#234)

- skills/ktx/SKILL.md: add an "Add context sources" section with the generic
  `ktx setup --source ...` flags per connector (dbt, Metabase, Notion, ...),
  warehouse mapping, the --metabase-database-id discovery note, and the
  `ktx ingest` follow-up. The skill previously only documented database setup
  with --skip-sources, so agents couldn't wire up dbt/Metabase/Notion (KLO-723).
- docs-site quickstart: the kaelio.com/start callout now points at the
  "copy agent setup" one-shot prompt that installs the full four-source demo.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../docs/getting-started/quickstart.mdx       |  5 +-
 skills/ktx/SKILL.md                           | 46 ++++++++++++++++++-
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 6f65d6ec..7402d6d9 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -30,8 +30,9 @@ If you're a coding assistant choosing a docs route, start with the
       </div>
       <div className="mt-2.5 text-base leading-relaxed text-fd-foreground">
         Try **ktx** against a real data stack - Postgres, dbt, Metabase, and Notion
-        pre-loaded with the Orbit demo corpus. The page lists demo credentials
-        you can paste straight into `ktx setup`.
+        pre-loaded with the Orbit demo corpus. Hit **copy agent setup** on the page
+        for a one-shot prompt that has an agent install the full four-source demo,
+        or grab the raw credentials to paste into `ktx setup` yourself.
       </div>
       <a
         href="https://kaelio.com/start"
diff --git a/skills/ktx/SKILL.md b/skills/ktx/SKILL.md
index 85028de7..3887fdc0 100644
--- a/skills/ktx/SKILL.md
+++ b/skills/ktx/SKILL.md
@@ -42,7 +42,9 @@ Before invoking `ktx setup`, collect in one round:
 4. Database: driver, connection id, URL (or `env:` / `file:` ref), and one or
    more schemas.
 5. Optional context sources (dbt, Metabase, Looker, LookML, MetricFlow,
-   Notion). Skip with `--skip-sources` if the user has none.
+   Notion). Add each one with a follow-up `ktx setup --source …` run (see
+   [Add context sources](#add-context-sources)); use `--skip-sources` only
+   when the user has none.
 
 Do not discover these inputs across multiple setup runs.
 
@@ -109,6 +111,48 @@ Do not discover these inputs across multiple setup runs.
 6. **Fall back to bare `ktx setup` only when a human is at the keyboard** —
    it uses interactive prompts an agent cannot answer.
 
+## Add context sources
+
+Context sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) are added
+**one at a time** — `--source` is not repeatable, so run `ktx setup` once per
+source. Source setup is resumable against an existing project: pass
+`--skip-databases --skip-llm --skip-embeddings` so only the source is
+configured. Map warehouse-backed sources (dbt, Metabase, Looker) to an existing
+database connection with `--source-warehouse-connection-id <db-connection-id>`.
+Prefer `env:VAR` / `file:/abs/path` refs for keys and tokens over literals.
+
+```bash
+# dbt — pick exactly one of --source-path (local) or --source-git-url (remote)
+ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings \
+  --source dbt --source-connection-id <id> \
+  --source-git-url <url> --source-branch <branch> \
+  --source-warehouse-connection-id <db-connection-id>
+
+# Metabase
+ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings \
+  --source metabase --source-connection-id <id> \
+  --source-url <url> --source-api-key-ref env:METABASE_API_KEY \
+  --source-warehouse-connection-id <db-connection-id> \
+  --metabase-database-id <metabase-db-id>
+
+# Notion
+ktx setup --no-input --yes --skip-databases --skip-llm --skip-embeddings \
+  --source notion --source-connection-id <id> \
+  --source-api-key-ref env:NOTION_TOKEN \
+  --notion-crawl-mode selected_roots --notion-root-page-id <page-id>
+```
+
+Notes:
+
+- `--metabase-database-id` is the **numeric id of the warehouse inside
+  Metabase** (not the ktx connection id). Discover it from the Metabase API
+  (`GET /api/database`) or UI if the user doesn't know it.
+- `--notion-crawl-mode selected_roots` requires at least one
+  `--notion-root-page-id` (repeatable); use `all_accessible` to crawl
+  everything the token can see.
+- After adding sources, ingest each new connection so its context is queryable:
+  `ktx ingest <source-connection-id> --fast --no-input`.
+
 ## Files to inspect
 
 - `ktx.yaml`: project configuration.