Merge remote-tracking branch 'origin/main' into rewrite-sl-internals-reactflow

# Conflicts:
#	docs-site/content/docs/cli-reference/ktx-setup.mdx

docs-site/content/agents-setup.md

@@ -67,7 +67,6 @@ Drive the existing wizard non-interactively (verify exact flag names with `ktx s
 ```
 ktx setup \
   --project-dir <path> \
-  --new \
   --no-input --yes \
   --llm-backend <claude-code|anthropic|vertex> --llm-model <model> \
   [--anthropic-api-key-env ANTHROPIC_API_KEY | --anthropic-api-key-file <path>] \
@@ -75,14 +74,22 @@ ktx setup \
   --embedding-backend <sentence-transformers|openai> \
   [--embedding-api-key-env OPENAI_API_KEY] \
   --skip-sources \
-  --database <driver> --new-database-connection-id <name> --database-url <url|env:VAR|file:/path> \
+  --database <driver> --database-connection-id <name> --database-url <url|env:VAR|file:/path> \
     [--database-schema <schema> …]
-  # repeat the --database / --new-database-connection-id / --database-url / --database-schema block per connection
 ```
 
 Notes on the flags above:
-- **`--new`** is required when bootstrapping an empty directory; use `--existing` instead when re-running setup against a project that already has a `ktx.yaml`.
-- **There is no `--skip-agents` flag.** The agent integration step is opt-in: setup leaves it alone unless you pass `--agents --target <target>`. So you do not need to skip it — just don't pass `--agents`.
+- **Project creation is automatic with `--no-input --yes`.** When
+  `ktx.yaml` exists, setup resumes it. When it doesn't exist, setup creates it
+  at `--project-dir`.
+- **`--database-connection-id` is dual-purpose.** With `--database` or
+  `--database-url`, it names the new connection. Without those flags, it
+  selects an existing connection id.
+- **Configure one new database connection per setup command.** If the user
+  wants multiple new connections, run setup again for each connection.
+- **You don't need `--skip-agents` in this flow.** The agent integration step
+  is opt-in: setup leaves it alone unless you pass `--agents --target
+  <target>`.
 - **`--skip-sources`** is correct and is the documented way to leave BI/metadata sources unconfigured.
 
 ### Known soft-failure: `ktx setup` exits 1 after a successful fast build
@@ -172,7 +179,7 @@ Verdict:     ready
 
 Then **Next steps** (copy-pasteable):
 1. Enrich with AI descriptions and embeddings: `ktx ingest <connection> --deep` (several minutes per connection).
-2. Add more connections later by rerunning this setup or via `ktx setup --existing --database … --new-database-connection-id …`.
+2. Add more connections later by rerunning this setup or via `ktx setup --database … --database-connection-id …`.
 3. Configure BI sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) — see `ktx setup --help` for `--source …` flags.
 4. Install agent integration: `ktx setup --agents --target <claude-code|claude-desktop|codex|cursor|opencode|universal>` (with optional `--global` for `claude-code`/`codex`).
 5. Connect the agent / MCP: see docs at `https://docs.kaelio.com/ktx/`.

docs-site/content/docs/cli-reference/ktx-setup.mdx

@@ -27,9 +27,9 @@ below.
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--agents` | Install agent configuration and rules only | `false` |
-| `--target <target>` | Agent target: `claude-code`, `codex`, `cursor`, `opencode`, or `universal` | - |
+| `--target <target>` | Agent target: `claude-code`, `claude-desktop`, `codex`, `cursor`, `opencode`, or `universal` | - |
 | `--global` | Install agent integration into the global target scope for `claude-code` or `codex` | `false` |
-| `--yes` | Accept safe defaults in non-interactive setup | `false` |
+| `--yes` | Accept project creation and runtime install defaults where setup asks for confirmation | `false` |
 | `--no-input` | Disable interactive terminal input | - |
 
 Use the global `--project-dir <path>` option when setup should target a
@@ -40,12 +40,12 @@ specific directory.
 These flags are useful for repeatable setup in examples, tests, CI fixtures, and
 scripted project creation. They are not shown in `ktx setup --help`.
 
-### Project Mode
+### Project Creation
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--new` | Create a new KTX project before setup | `false` |
-| `--existing` | Use an existing KTX project | `false` |
+Setup resumes an existing `ktx.yaml` when one is present. When no project
+exists, interactive setup prompts for where to create it. In scripts, pass
+`--project-dir <dir> --no-input --yes` to create the target directory without
+prompts.
 
 ### LLM Provider
 
@@ -56,7 +56,6 @@ scripted project creation. They are not shown in `ktx setup --help`.
 | `--llm-model <model>` | LLM model ID or backend model alias to validate and save |
 | `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
 | `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
-| `--anthropic-model <model>` | Legacy alias for `--llm-model` |
 | `--vertex-project <project>` | Vertex AI project ID, `env:NAME`, or `file:/path` reference |
 | `--vertex-location <location>` | Vertex AI location, `env:NAME`, or `file:/path` reference |
 | `--skip-llm` | Leave LLM setup incomplete |
@@ -105,8 +104,7 @@ runtime features are missing.
 | Flag | Description |
 |------|-------------|
 | `--database <driver>` | Database driver to configure; repeatable. Choices: `sqlite`, `postgres`, `mysql`, `sqlserver`, `bigquery`, `snowflake` |
-| `--database-connection-id <id>` | Existing selected connection id; repeatable |
-| `--new-database-connection-id <id>` | Connection id for one new database connection |
+| `--database-connection-id <id>` | Existing selected connection id; repeatable. With `--database` or `--database-url`, connection id for the new connection. |
 | `--database-url <url>` | URL, `env:NAME`, or `file:/path` for one new URL-style database connection; also used as the SQLite path |
 | `--database-schema <schema>` | Database schema or dataset to include; repeatable |
 | `--skip-databases` | Leave database setup incomplete |
@@ -177,10 +175,11 @@ ktx setup \
 ktx setup \
   --project-dir ./analytics \
   --no-input \
+  --yes \
   --skip-llm \
   --skip-embeddings \
   --database postgres \
-  --new-database-connection-id warehouse \
+  --database-connection-id warehouse \
   --database-url env:DATABASE_URL \
   --database-schema public
 
@@ -188,7 +187,7 @@ ktx setup \
 ktx setup \
   --project-dir ./analytics \
   --database postgres \
-  --new-database-connection-id warehouse \
+  --database-connection-id warehouse \
   --database-url env:DATABASE_URL \
   --enable-query-history \
   --query-history-min-executions 5
@@ -236,4 +235,5 @@ Use `ktx status` for repeatable readiness checks after setup exits.
 | `--enable-query-history` is rejected | The selected database driver does not support query history | Use Postgres, BigQuery, or Snowflake, or rerun without query-history flags |
 | Source setup rejects location flags | Both `--source-path` and `--source-git-url` were supplied | Choose the local path or the Git URL, not both |
 | Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target <target>` |
+| Agent setup cannot prompt for a target | Non-TTY `ktx setup --agents` needs a target | Run `ktx setup --agents --target <target>` or rerun in a TTY |
 | Global agent install is rejected | `--global` was used with a target other than `claude-code` or `codex` | Omit `--global`, or choose `--target claude-code` or `--target codex` |

docs-site/content/docs/getting-started/quickstart.mdx

@@ -216,10 +216,11 @@ For repeatable fixtures and automation, skip prompts with flags:
 ktx setup \
   --project-dir ./analytics \
   --no-input \
+  --yes \
   --skip-llm \
   --skip-embeddings \
   --database postgres \
-  --new-database-connection-id warehouse \
+  --database-connection-id warehouse \
   --database-url env:DATABASE_URL \
   --database-schema public
 ```