feat: merge ingest and scan

* docs: add CLI component reuse guidance

* docs: add unified ingest ux design

* Refine unified ingest UX design after adversarial review iteration 1

* Refine unified ingest UX design after adversarial review iteration 2

* Refine unified ingest UX design after adversarial review iteration 3

* feat(cli): route public connection ingest command

* feat(cli): hide standalone scan from public help

* feat(cli): plan public ingest depth and query history

* feat(cli): execute public database ingest facets

* feat(ingest): read connection query history config

* fix(cli): use public ingest wording

* fix(config): stop generating ingest adapter allow lists

* docs: document public ingest command

* test: align ingest surface expectations

* docs: add unified ingest public CLI surface plan

* feat(cli): preflight deep public ingest readiness

* feat(setup): store query history in connection context

* feat(setup): store database context depth

* feat(setup): verify context readiness by database depth

* fix(setup): keep context build foreground only

* fix(config): reject reserved ingest connection ids

* test: close unified ingest v1 expectations

* docs: add unified ingest v1 closure plan

* fix(ingest): bypass adapter allow-list for public source ingest

* fix(ingest): honor query history window intent

* fix(ingest): hide scan internals from public database ingest

* feat(ingest): use foreground view for interactive public ingest

* fix(setup): use schema context and query history wording

* test(cli): verify unified ingest public output

* docs: add unified ingest v1 public output closure plan

* fix(setup): forward query history flags

* fix(setup): prompt for postgres query history

* fix(status): report query history readiness

* fix(ingest): remove legacy public guidance

* fix(ingest): polish foreground retry copy

* docs(examples): use unified query history wording

* chore(ingest): finish public query history cleanup

* docs: add unified ingest v1 query history status cleanup plan

* test(docs): cover unified ingest public docs

* docs: align ingest CLI reference with unified UX

* docs: update context build guides for unified ingest

* docs: update setup and primary source ingest wording

* docs: stop advertising adapter-backed example ingest

* docs: close unified ingest public docs gaps

* docs: add unified ingest v1 docs site closure plan

* fix: render unified ingest foreground warnings

* fix: explain query history schema order

* fix: add public ingest retry guidance

* fix: align setup next steps with unified ingest

* fix: remove scan wording from demo progress

* test: verify unified ingest ux closure

* docs: add unified ingest v1 foreground and retry closure plan

* fix(cli): preserve query-history pull config in public ingest

* fix(cli): omit hidden commands from docs command tree

* test(cli): close unified ingest final public surface checks

* docs: add unified ingest v1 final public surface closure plan

* fix(cli): use public source labels in ingest reports

* fix(cli): suppress low-level public ingest output

* test(cli): verify unified ingest public plain output

* docs: add unified ingest v1 public plain output closure plan

* fix(cli): add public ingest copy sanitizers

* fix(cli): sanitize public ingest progress copy

* fix(cli): rename setup schema scope prompt

* docs(plan): add progress copy closure; test: align setup back-nav fixture

Adds the iter9 plan and updates the setup back-navigation test fixture
to pass disableQueryHistory plus listSchemas/listTables stubs that the
unified ingest setup step now requires.

* docs(plan): add final ux labels plan with narrowed label scans

* fix(cli): aggregate unsupported query-history warnings

* fix(cli): align setup database labels

* test(cli): fix setup database test type-check

* fix(cli): remove primary-source wording from setup output

* test(cli): verify unified ingest setup closure

* docs(plan): add unified ingest v1 verification copy closure plan

* fix(cli): remove top-level scan command

* fix(cli): remove legacy ingest and wiki commands

* Merge scan into ingest flow

* feat(cli): split ingest progress into per-phase rows, rename work units to tasks

Each database target in the unified ingest dashboard now renders one row per
real subprocess (Schema, then Query history when enabled) instead of a single
combined bar. Each phase has its own monotonic 0-100% bar so the progress
never snaps back to zero when historic-sql starts after scan completes.
Completed phases keep their final bar, summary, and elapsed time visible as
an inline audit trail; queued and skipped phases are shown explicitly.

Also rename user-facing "work units" / "Failed work units" to "tasks" /
"Failed tasks" in ingest output and parseIngestSummary. The parser still
accepts the legacy "Work units:" wording in captured output for backward
compat. Internal memory-flow event names and type fields are left alone.

* Fix test harness failures

* Fix CI smoke checks

---------

Co-authored-by: Andrey Avtomonov <7889985+andreybavt@users.noreply.github.com>

examples/README.md

@@ -2,19 +2,15 @@
 
 ## local-warehouse
 
-`local-warehouse/` is a runnable standalone KTX project for local CLI smoke
-testing. It uses the fake ingest adapter and does not require a database or
-external app server.
+`local-warehouse/` is a contributor fixture for local CLI smoke tests. It uses
+the internal fake ingest adapter so tests can exercise memory-flow behavior
+without a live database or external service.
 
-Copy it before running commands:
+For normal context building, use the public connection-centric commands:
 
 ```bash
-pnpm --filter @ktx/cli run build
-EXAMPLE_DIR="$(mktemp -d)/local-warehouse"
-cp -R examples/local-warehouse "$EXAMPLE_DIR"
-node packages/cli/dist/bin.js knowledge list --project-dir "$EXAMPLE_DIR"
-node packages/cli/dist/bin.js sl list --project-dir "$EXAMPLE_DIR" --connection-id warehouse
-node packages/cli/dist/bin.js ingest run --project-dir "$EXAMPLE_DIR" --connection-id warehouse --adapter fake --source-dir "$EXAMPLE_DIR/source"
+ktx ingest <connectionId>
+ktx ingest --all
 ```
 
 The copied project initializes its own Git repository on first use.
@@ -29,10 +25,11 @@ warehouse credential.
 
 ## postgres-historic
 
-`postgres-historic/` is a manual Docker-backed smoke for Postgres historic-SQL
-ingest via `pg_stat_statements`. It verifies setup, unified Historic SQL artifacts,
-managed daemon batch SQL analysis, bounded pattern WorkUnit shards, and
-no-WorkUnit idempotency for unchanged bucketed table inputs and pattern shards.
+`postgres-historic/` is a manual Docker-backed smoke for Postgres
+query-history ingest via `pg_stat_statements`. It verifies setup, staged
+query-history artifacts, managed daemon batch SQL analysis, bounded pattern
+WorkUnit shards, and no-WorkUnit idempotency for unchanged bucketed table
+inputs and pattern shards.
 
 ## package-artifacts
 

examples/local-warehouse/README.md

@@ -1,20 +1,16 @@
-# Local Warehouse Example
+# local-warehouse fixture
 
-This example is a standalone KTX project that can be copied to a temp directory
-and used with the local CLI. It uses the `fake` ingest adapter so it does not
-require a database or external app server.
+This directory is a contributor fixture for KTX CLI smoke tests. It uses the
+internal fake ingest adapter so tests can run without a live database or
+external service.
 
-Run the example from the repository root after building the CLI:
+Normal users should build context with connection-centric ingest:
 
 ```bash
-pnpm --filter @ktx/cli run build
-EXAMPLE_DIR="$(mktemp -d)/local-warehouse"
-cp -R examples/local-warehouse "$EXAMPLE_DIR"
-node packages/cli/dist/bin.js knowledge list --project-dir "$EXAMPLE_DIR"
-node packages/cli/dist/bin.js sl list --project-dir "$EXAMPLE_DIR" --connection-id warehouse
-node packages/cli/dist/bin.js ingest run --project-dir "$EXAMPLE_DIR" --connection-id warehouse --adapter fake --source-dir "$EXAMPLE_DIR/source"
+ktx ingest <connectionId>
+ktx ingest --all
 ```
 
-The copied project creates its own Git repository on first use. Keep commands
-pointed at a copy when experimenting so the checked-in example fixture stays
-unchanged.
+The public ingest workflow is documented in
+`docs-site/content/docs/cli-reference/ktx-ingest.mdx` and
+`docs-site/content/docs/guides/building-context.mdx`.

examples/local-warehouse/ktx.yaml

@@ -11,7 +11,6 @@ storage:
 ingest:
   adapters:
     - fake
-    - live-database
 agent:
   run_research:
     enabled: false

examples/orbit-relationship-verification/ktx.yaml

@@ -10,8 +10,7 @@ storage:
     auto_commit: true
     author: "ktx <ktx@example.com>"
 ingest:
-  adapters:
-    - live-database
+  adapters: []
 scan:
   enrichment:
     backend: none

examples/postgres-historic/README.md

@@ -1,9 +1,9 @@
-# Postgres Historic SQL Example
+# Postgres Query History Example
 
-This example is a manual smoke for the redesigned Postgres historic-SQL ingest
-path through `pg_stat_statements`. It starts Postgres 14 with the extension
-preloaded, generates query workload under separate users, runs `ktx setup` with
-`--enable-historic-sql`, and verifies the unified staged artifacts:
+This example is a manual smoke for Postgres query-history ingest through
+`pg_stat_statements`. It starts Postgres 14 with the extension preloaded,
+generates query workload under separate users, runs `ktx setup` with
+`--enable-query-history`, and verifies the staged query-history artifacts:
 
 - `manifest.json`
 - `tables/*.json`
@@ -40,7 +40,7 @@ postgresql://ktx_reader:ktx_reader@127.0.0.1:55432/analytics # pragma: allowlist
 Set `KTX_POSTGRES_HISTORIC_KEEP_DOCKER=1` to leave the container running after
 the script exits.
 
-The smoke validates the historic-SQL raw snapshot path without requiring LLM
+The smoke validates the query-history raw snapshot path without requiring LLM
 credentials. It uses KTX's local stage-only ingest API after `ktx setup`, so the
 deterministic reader, batch SQL parser, stable artifact writer, and diff-based
 WorkUnit planning are checked independently from curation.
@@ -54,7 +54,7 @@ docker compose -f examples/postgres-historic/docker-compose.yml up -d --wait
 examples/postgres-historic/scripts/generate-workload.sh base
 ```
 
-Create a project and enable historic SQL:
+Create a project and enable query history:
 
 ```bash
 export WAREHOUSE_DATABASE_URL=postgresql://ktx_reader:ktx_reader@127.0.0.1:55432/analytics # pragma: allowlist secret
@@ -69,8 +69,8 @@ node packages/cli/dist/bin.js --project-dir /tmp/ktx-postgres-historic setup \
   --new-database-connection-id warehouse \
   --database-url env:WAREHOUSE_DATABASE_URL \
   --database-schema public \
-  --enable-historic-sql \
-  --historic-sql-min-executions 2 \
+  --enable-query-history \
+  --query-history-min-executions 2 \
   --yes \
   --no-input
 ```
@@ -87,24 +87,21 @@ The installed CLI form is:
 ktx status --project-dir /tmp/ktx-postgres-historic --no-input
 ```
 
-Expected output includes `PASS Postgres Historic SQL (warehouse)` when
+Expected output includes `PASS Postgres query history (warehouse)` when
 `pg_stat_statements` is installed, `pg_read_all_stats` is granted, and tracking
 is enabled. A low `pg_stat_statements.max` value is reported as an informational
 note, not a warning.
 
-Run local historic-SQL ingest:
+Run query-history ingest:
 
 ```bash
-pnpm run ktx -- ingest run --project-dir /tmp/ktx-postgres-historic \
-  --connection-id warehouse \
-  --adapter historic-sql \
-  --plain \
-  --yes \
+pnpm run ktx -- ingest warehouse --project-dir /tmp/ktx-postgres-historic \
+  --query-history \
   --no-input
 ```
 
-The full `ingest run` path also runs curation WorkUnits, so it requires a
-configured LLM provider.
+The public query-history ingest path also runs curation WorkUnits, so it
+requires a configured LLM provider.
 
 Inspect the latest manifest:
 
@@ -126,7 +123,7 @@ table.
   database.
 - Missing grants: confirm `GRANT pg_read_all_stats TO ktx_reader;`.
 - Empty snapshot: rerun `scripts/generate-workload.sh base` and keep
-  `--historic-sql-min-executions 2` for the smoke.
+  `--query-history-min-executions 2` for the smoke.
 - SQL-analysis failures: run `pnpm run ktx -- dev runtime status` from the KTX
   repository root and confirm `uv`, the bundled Python wheel, and the managed
   runtime all pass.

examples/postgres-historic/scripts/smoke.sh

@@ -215,8 +215,8 @@ node "$KTX_BIN" --project-dir "$PROJECT_DIR" setup \
   --new-database-connection-id warehouse \
   --database-url env:WAREHOUSE_DATABASE_URL \
   --database-schema public \
-  --enable-historic-sql \
-  --historic-sql-min-executions 2 \
+  --enable-query-history \
+  --query-history-min-executions 2 \
   --yes \
   --no-input