From ae37ca521eb9510c135def4a1e3730e137fb014b Mon Sep 17 00:00:00 2001
From: Gabor Szabo <168316277+w7-mgfcode@users.noreply.github.com>
Date: Mon, 18 May 2026 21:51:32 +0200
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20cut=20v0.2.13=20=E2=80=94=20explore?=
 =?UTF-8?q?r=20interactivity,=20knowledge=20&=20guide=20pages=20(#191)=20(?=
 =?UTF-8?q?#192)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(data): implement MarkdownGenerator age_days trigger via heuristic (#94) (#127)

Resolves #94 via the heuristic path documented in the issue. No schema
column, no Alembic migration, no FIFO cohort tracking — the trigger
self-reads the existing per-(store, product) on_hand_qty series and
fires when inventory has been "unrefreshed" past
`cfg.age_days_threshold`.

Decision rationale (schema column vs. heuristic):
- The schema column path would add `oldest_unit_age_days` to
  `inventory_snapshot_daily`, plus an Alembic migration, plus FIFO
  cohort tracking in `InventorySnapshotGenerator`. No downstream
  consumer reads this column today — adding it for one generator
  trigger violates the "don't design for hypothetical future
  requirements" rule in CLAUDE.md.
- The heuristic path is self-contained in MarkdownGenerator,
  deterministic (preserves the zero-rng-draw regression invariant),
  and additive (no migration, no model change). 354 LOC net, all
  inside one slice.

Heuristic spec:
- A "refresh" is a day where `on_hand_qty` rose by >=
  `_AGE_DAYS_SPIKE_THRESHOLD` (0.3 = 30% jump) vs the prior day.
- Age at day t = days since most recent refresh (or `dates[0]` if no
  refresh has been observed).
- Firing requires age >= `age_days_threshold` AND on_hand >=
  `markdown_min_units_remaining` — never markdown an empty shelf.
- After firing, refresh anchor resets to the day AFTER the markdown
  window ends, so back-to-back fires can't happen and the next age
  clock starts from a "clear shelf" baseline.

Wiring: `MarkdownGenerator.generate()` gains an optional kwarg
`inventory_records: list[dict[str, Any]] | None = None` which `core.py`
passes through from `InventorySnapshotGenerator`. Disabled-path and
non-age_days-path behavior is byte-identical (kwarg ignored).

Tests: +7 new in `TestAgeDaysTrigger`, -1 obsolete
`NotImplementedError` test. Coverage: no-records defensive, threshold
not-met, threshold met, spike resets age, post-fire reset avoids
back-to-back, low-inventory skip, unknown-product skip, rng
non-consumption.

Validation (local):
- ruff check + format: clean
- mypy --strict: 0 issues, 192 files
- pyright --strict: 0 errors
- pytest -m "not integration": 969 passed (+7 vs pre-PR)

Closes #94.

* feat(api,docs): e2e demo pipeline + showcase script (#128) (#129)

* docs(docs): add INITIAL-14 + PRP-15 e2e demo pipeline plan (#128)

Adds the planning documents for the end-to-end demo pipeline work tracked
in #128. Implementation commits follow on this branch.

- INITIAL-14.md: PRD for `make demo` (problem, solution, success metrics,
  open questions resolved in the PRP).
- PRPs/PRP-15-e2e-demo-pipeline.md: full execution plan (16 tasks → 6
  commits, additive only — no schema changes, no API edits).

* feat(data): add demo_minimal scenario preset (#128)

Tiny preset that powers the upcoming `make demo` target. Three stores ×
ten products × 92 days (2024-10-01..2024-12-31) — wide enough to satisfy
an expanding backtest with n_splits=3, horizon=14, min_train_size=30
(needs >= 72 days, 92 leaves margin), small enough to keep the demo
loop comfortable on a laptop.

Mirrors the retail_standard tuning (mild linear trend, noise_sigma=0.10,
modest promotion + stockout probabilities) so backtest WAPE stays
non-NaN across all three baseline models.

- app/shared/seeder/config.py: add DEMO_MINIMAL enum + from_scenario branch
- app/features/seeder/service.py: add ScenarioInfo entry in list_scenarios
- tests cover the new preset and the updated scenario count

* feat(api,docs): scripts/run_demo.py end-to-end pipeline driver (#128)

Single-file async driver that walks the published HTTP surface
(precheck -> reset? -> seed -> status -> features -> train x3 ->
backtest x3 -> register -> verify -> agent -> cleanup). Mirrors the
shape of scripts/seed_random.py and scripts/check_db.py.

- HttpClient: thin httpx.AsyncClient wrapper with explicit 60 s
  timeout (default 5 s is too short for /seeder/generate); surfaces
  RFC 7807 problem+json bodies as a typed StepError that echoes
  title / detail / request_id (never the raw body — secrets-safe).
- DemoContext + StepOutcome dataclasses thread cross-step references.
- Reporter renders the output-formatting.md glyphs (verbose by
  default, --quiet collapses to one line per step).
- Per-step error handling converts httpx + StepError into fail
  outcomes; precheck failure exits 2, any other failure exits 1,
  green exits 0.
- Agent step (10/11) skips with ⏭️ when neither OPENAI_API_KEY nor
  ANTHROPIC_API_KEY is set; reads via app.core.config.get_settings()
  to honor the no-os.environ-in-feature-code rule.
- Registry handshake uses the mandatory pending -> running -> success
  transition and the wire alias "model_config" (not "model_config_data");
  artifact_hash is computed client-side via sha256 since we share the
  FS with the API on this single-host system.
- Winner selection: lowest aggregated WAPE, skipping NaN folds.

Also adds scripts/__init__.py so tests can `import scripts.run_demo`
without invoking the file as a script.

* feat(repo): top-level Makefile with demo / demo-quick / demo-clean (#128)

Wraps scripts/run_demo.py so reviewers can run the full end-to-end
demo with one command. Recipes mirror the three modes the script
supports: full run, skip-seed iteration, destructive reset.

Make targets:
- demo        — docker compose up -d + alembic + run_demo
- demo-quick  — run_demo --skip-seed (no compose/migration touch)
- demo-clean  — full reset (--reset) before seeding
- help        — default goal; lists targets + preconditions

Tab-indented recipes and .PHONY declarations per make conventions.
Preconditions (Postgres on :5433, uvicorn on :8123) documented in
the help block; the script itself enforces them via the precheck
step and exits 2 on failure.

* test(api): unit + integration coverage for run_demo (#128)

Unit (`tests/test_run_demo_unit.py`, 32 cases):
- argparse defaults + all-flags variants
- DemoContext defaults (no leaking state across runs)
- _select_winner: lowest-WAPE, NaN-skip, all-NaN -> None, empty -> None
- _model_config_payload: discriminated-union shape per baseline; rejects
  unsupported model_type (defends the "no lightgbm in PRP-15" boundary)
- Reporter: glyph mapping; verbose + quiet output; summary green / failure
  / over-budget soft-warn branches
- StepError formats RFC 7807 (title/detail/request_id) without leaking
  the raw response body
- HttpClient (mocked httpx.AsyncClient): 2xx, 204, non-2xx -> StepError
- Step payload sanity: seed sends demo_minimal+correct dims+ISO dates;
  features sends cutoff_date as ISO; train fires three model_types in
  parallel; agent step skips with ⏭️ when no LLM key

Integration (`tests/test_e2e_demo.py`, @pytest.mark.integration):
- Skips if Postgres on :5433 isn't reachable
- Boots uvicorn on :8124 as a subprocess (avoids the dev :8123 default)
- Runs scripts/run_demo.py --reset against it; asserts exit 0 +
  canonical "runs=3 winner=... alias=demo-production" summary
- Second case asserts a bogus URL exits 2 (no silent success)
- Cleans up uvicorn on teardown with terminate/kill fallback
- Resolves `uv` via shutil.which to keep ruff S607 happy and avoid
  PATH-dependent exec at test time

* ci(repo): nightly e2e demo workflow (#128)

Adds .github/workflows/e2e-nightly.yml — runs scripts/run_demo.py
against a fresh Postgres+pgvector service every night at 07:00 UTC
(plus on-demand via workflow_dispatch). Catches regressions in the
documented end-to-end pipeline before they bleed into the per-PR
gate.

Per PRP-15 + INITIAL-14 risk note: this workflow is intentionally
NOT a required status check on dev or main. Flake-budget lives in
the nightly slot, not in ci.yml.

- pgvector/pgvector:pg16 service container (same as ci.yml `test` job)
- uvicorn started in background; /health polled with a 30 s deadline
- run_demo.py called with --seed 42 (deterministic)
- LLM-key env vars intentionally absent — agent step auto-skips via
  ⏭️, keeping the workflow self-contained
- uvicorn logs uploaded as artifact on failure (7-day retention) so
  postmortems can read what the API was doing when the script broke
- astral-sh/setup-uv pinned by 40-char SHA per security-patterns.md
- permissions: contents: read (least-privilege)

* docs(docs): cross-link make demo from README + RUNBOOKS + REPO_MAP_INDEX (#128)

Discoverability layer for PRP-15.

- README.md: new 'Try it: end-to-end demo' step right after the curl
  /health verification; shows the canonical final-line summary so
  reviewers know what green looks like.
- docs/DAILY-FLOW.md: new 'First-Run Smoke (Demo Pipeline)' section
  documenting all three Make targets.
- docs/_base/RUNBOOKS.md: new 'make demo fails at step X' Common
  Incidents entry with a 7-point diagnosis flow keyed to the script's
  step names + a postmortem-capture recipe.
- docs/_base/REPO_MAP_INDEX.md: Makefile and scripts/run_demo.py rows
  added to the Document Index table.

Pure additive; no existing content removed or renamed.

* fix(data): update /seeder/scenarios route test for demo_minimal preset (#128)

Companion to feat(data): add demo_minimal scenario preset — the
route-level assertion in TestListScenarios.test_returns_scenarios still
expected 6 scenarios; bumping to 7 and adding the demo_minimal name
membership check to match the service-layer + config-layer tests
already updated in 005c189.

* fix(api): harden run_demo for integration test + real DB (#128)

Three real failures surfaced when first running the integration test
against docker-compose Postgres + a freshly booted uvicorn; all three
are now closed:

scripts/run_demo.py:
1. step_status: discover the real (store_id, product_id) from
   /dimensions/stores + /dimensions/products instead of hardcoding 1.
   Postgres auto-increment does NOT reset after delete, so the freshly
   seeded IDs are NOT 1 (they were ~150-260 on this branch after a few
   delete/seed cycles).
2. step_register: copy the trained-model artifact into the registry's
   own root (settings.registry_artifact_root) and record a registry-
   relative URI. The registry verify endpoint resolves artifact_uri
   against its own root, which is separate from where /forecasting/train
   writes (settings.forecast_model_artifacts_dir). Pre-fix, verify
   returned 404 even though the artifact existed on disk.
3. step_agent: skip with the soft-skip glyph on any LLM provider failure
   (invalid key, model unavailable, 5xx), and make _llm_key_present
   provider-aware so it matches the right env var to the configured
   agent_default_model. Pre-fix, an .env with anthropic/openai keys but
   a Gemini default model failed hard at chat-time.
4. Bumped DEFAULT_TIMEOUT_S from 60 to 120 because /seeder/generate
   for demo_minimal can spend 60-90 s on slower laptops once you
   include inventory + prices + promotions inserts.
5. step_seed detail string: GenerateResult.records_created uses 'sales'
   (singular), not 'sales_daily'; cosmetic fix.

tests/test_e2e_demo.py:
- Redirect uvicorn stdout to a temp file rather than subprocess.PIPE.
  The seeder + structlog produce enough INFO log volume to fill a
  64-KB pipe buffer; once full, uvicorn blocks on write and seeder
  requests hang for the full --timeout. Verified locally: integration
  suite now passes in ~6.5 s instead of timing out at 120 s.
- Cleanup leaves the log file on disk only when the test failed
  (postmortem-friendly).

tests/test_run_demo_unit.py:
- Bump test_defaults timeout expectation to match the new 120 s
  default.

End-to-end manual run on this machine: 11 steps, wall_clock=2 s,
exit 0. Integration test: 2 passed in 6.48 s.

* chore(repo): bump authlib + fastmcp to clear Socket-flagged CVEs (#130) (#131)

Headline:
- authlib  1.6.6  -> 1.7.2  (clears GHSA-wvwj-cvrp-7pv5 — JWS signature
  verification bypass; patched at >= 1.6.9)
- fastmcp  2.14.4 -> 3.2.4  (clears GHSA-vv7q-7jx5-f767 — OpenAPI
  Provider SSRF + path traversal; patched at >= 3.2.0)

Both CVEs were flagged on PR #129 by Socket Security and are
pre-existing on dev (not introduced by #128).

Wider scope — read before merging:
`uv lock --upgrade-package authlib --upgrade-package fastmcp` triggers
a full re-resolve of the dependency graph. Because dev's uv.lock had
drifted from pyproject.toml (the project's constraint envelope had
loosened over time), this single command also brings the lockfile in
sync with current pyproject.toml. Net diff: 243 insertions / 369
deletions on uv.lock; no other files touched.

Transitive cascades worth flagging:
- anthropic    0.77.0 -> 0.102.0 (pydantic-ai-slim extra)
- pydantic-graph 1.51.0 -> 1.96.0
- temporalio   1.20.0 -> 1.27.2
- alembic      1.18.1 -> 1.18.4
- aws-* and cohere transitives bumped along
- griffe 1.15.0 dropped in favor of griffelib 2.0.2 (fastmcp 3.x switched)
- Removed: cloudpickle, diskcache, fakeredis, invoke, lupa, prometheus
  exporter, pydocket, redis, rsa, sortedcontainers — these were
  transitives of fastmcp 2.x that fastmcp 3.x no longer pulls in.

Verification on this host:
- uv sync --extra dev  -> green
- ruff check .         -> clean
- mypy --strict app/   -> 192 files clean
- pyright app/         -> 0 errors (50 warnings, pre-existing)
- pytest -m 'not integration' -> 969 passed

Known install quirk: griffelib 2.0.2 ships a top-level `griffe/`
package whose RECORD files don't always materialize on first install
when uv replaces an older `griffe` dist in the same sync. A clean
venv install (which CI does via `uv sync --frozen`) is unaffected;
local devs who upgrade in place may need a one-shot
`uv pip install --force-reinstall griffelib` if `import griffe` fails.

* feat(api,ui): in-product demo showcase page (#132) (#133)

* feat(api): add demo slice driving the e2e pipeline via /demo endpoints (#132)

New app/features/demo slice exposing POST /demo/run and WS /demo/stream. It
drives the published API surface in-process via httpx.ASGITransport (no
cross-slice imports, satisfying the vertical-slice rule) and streams one
StepEvent per pipeline step: precheck -> reset -> seed -> status -> features
-> train x3 -> backtest x3 -> register -> verify -> agent -> cleanup.

A module-level asyncio.Lock enforces single-flight; concurrent runs get an
RFC 7807 409. The orchestration is a faithful in-process port of
scripts/run_demo.py (PR #129). Implements PRP-17.

* test(api): cover the demo slice pipeline, routes, and e2e integration (#132)

Unit tests mock the in-process HTTP client to exercise step sequencing,
winner selection, and fail-fast; route tests cover POST /demo/run (200 +
409) and the WS /demo/stream handler. The integration test seeds
demo_minimal and asserts an end-to-end green run against real Postgres.

Implements PRP-17.

* feat(ui): add showcase page streaming the live demo pipeline (#132)

New /showcase route and nav entry. The page opens a one-shot WebSocket to
/demo/stream via a use-demo-pipeline hook (wrapping useWebSocket) and renders
the 11 pipeline steps as live status cards: glyph, detail, duration, the
backtest per-model WAPE breakdown with the winner highlighted, and a
pass/fail summary banner.

Also block-scopes a pre-existing no-case-declarations lint error in
chat.tsx so pnpm lint is green for this PR. Implements PRP-17.

* test(ui): add vitest setup and use-demo-pipeline hook coverage (#132)

Adds the frontend test stack (vitest + jsdom + @testing-library/react), a
test script, and vitest.config.ts. use-demo-pipeline.test.ts covers the
pure event reducer (idle -> running -> pass transitions, summary assembly,
error phase) and a renderHook smoke test.

The package.json pnpm.onlyBuiltDependencies entry is the RUNBOOKS-documented
fix for pnpm 11's esbuild build-script gate. Implements PRP-17.

* docs(docs): document the demo slice and showcase page (#132)

Adds the PRP-17 spec; a 'Try it in the browser' pointer in README; the
/demo/run + /demo/stream rows and a WebSocket Events section in
API_CONTRACTS; a 'Showcase pipeline fails' runbook incident; and
REPO_MAP_INDEX rows for the demo slice and showcase page.

Implements PRP-17.

* chore(repo): back-merge main into dev to absorb v0.2.10 release commits (#136) (#137)

* chore(main): release 0.2.9 (#126)

* feat: release v0.2.10 — demo showcase page + e2e pipeline (#134)

* feat(data): implement MarkdownGenerator age_days trigger via heuristic (#94) (#127)

Resolves #94 via the heuristic path documented in the issue. No schema
column, no Alembic migration, no FIFO cohort tracking — the trigger
self-reads the existing per-(store, product) on_hand_qty series and
fires when inventory has been "unrefreshed" past
`cfg.age_days_threshold`.

Decision rationale (schema column vs. heuristic):
- The schema column path would add `oldest_unit_age_days` to
  `inventory_snapshot_daily`, plus an Alembic migration, plus FIFO
  cohort tracking in `InventorySnapshotGenerator`. No downstream
  consumer reads this column today — adding it for one generator
  trigger violates the "don't design for hypothetical future
  requirements" rule in CLAUDE.md.
- The heuristic path is self-contained in MarkdownGenerator,
  deterministic (preserves the zero-rng-draw regression invariant),
  and additive (no migration, no model change). 354 LOC net, all
  inside one slice.

Heuristic spec:
- A "refresh" is a day where `on_hand_qty` rose by >=
  `_AGE_DAYS_SPIKE_THRESHOLD` (0.3 = 30% jump) vs the prior day.
- Age at day t = days since most recent refresh (or `dates[0]` if no
  refresh has been observed).
- Firing requires age >= `age_days_threshold` AND on_hand >=
  `markdown_min_units_remaining` — never markdown an empty shelf.
- After firing, refresh anchor resets to the day AFTER the markdown
  window ends, so back-to-back fires can't happen and the next age
  clock starts from a "clear shelf" baseline.

Wiring: `MarkdownGenerator.generate()` gains an optional kwarg
`inventory_records: list[dict[str, Any]] | None = None` which `core.py`
passes through from `InventorySnapshotGenerator`. Disabled-path and
non-age_days-path behavior is byte-identical (kwarg ignored).

Tests: +7 new in `TestAgeDaysTrigger`, -1 obsolete
`NotImplementedError` test. Coverage: no-records defensive, threshold
not-met, threshold met, spike resets age, post-fire reset avoids
back-to-back, low-inventory skip, unknown-product skip, rng
non-consumption.

Validation (local):
- ruff check + format: clean
- mypy --strict: 0 issues, 192 files
- pyright --strict: 0 errors
- pytest -m "not integration": 969 passed (+7 vs pre-PR)

Closes #94.

* feat(api,docs): e2e demo pipeline + showcase script (#128) (#129)

* docs(docs): add INITIAL-14 + PRP-15 e2e demo pipeline plan (#128)

Adds the planning documents for the end-to-end demo pipeline work tracked
in #128. Implementation commits follow on this branch.

- INITIAL-14.md: PRD for `make demo` (problem, solution, success metrics,
  open questions resolved in the PRP).
- PRPs/PRP-15-e2e-demo-pipeline.md: full execution plan (16 tasks → 6
  commits, additive only — no schema changes, no API edits).

* feat(data): add demo_minimal scenario preset (#128)

Tiny preset that powers the upcoming `make demo` target. Three stores ×
ten products × 92 days (2024-10-01..2024-12-31) — wide enough to satisfy
an expanding backtest with n_splits=3, horizon=14, min_train_size=30
(needs >= 72 days, 92 leaves margin), small enough to keep the demo
loop comfortable on a laptop.

Mirrors the retail_standard tuning (mild linear trend, noise_sigma=0.10,
modest promotion + stockout probabilities) so backtest WAPE stays
non-NaN across all three baseline models.

- app/shared/seeder/config.py: add DEMO_MINIMAL enum + from_scenario branch
- app/features/seeder/service.py: add ScenarioInfo entry in list_scenarios
- tests cover the new preset and the updated scenario count

* feat(api,docs): scripts/run_demo.py end-to-end pipeline driver (#128)

Single-file async driver that walks the published HTTP surface
(precheck -> reset? -> seed -> status -> features -> train x3 ->
backtest x3 -> register -> verify -> agent -> cleanup). Mirrors the
shape of scripts/seed_random.py and scripts/check_db.py.

- HttpClient: thin httpx.AsyncClient wrapper with explicit 60 s
  timeout (default 5 s is too short for /seeder/generate); surfaces
  RFC 7807 problem+json bodies as a typed StepError that echoes
  title / detail / request_id (never the raw body — secrets-safe).
- DemoContext + StepOutcome dataclasses thread cross-step references.
- Reporter renders the output-formatting.md glyphs (verbose by
  default, --quiet collapses to one line per step).
- Per-step error handling converts httpx + StepError into fail
  outcomes; precheck failure exits 2, any other failure exits 1,
  green exits 0.
- Agent step (10/11) skips with ⏭️ when neither OPENAI_API_KEY nor
  ANTHROPIC_API_KEY is set; reads via app.core.config.get_settings()
  to honor the no-os.environ-in-feature-code rule.
- Registry handshake uses the mandatory pending -> running -> success
  transition and the wire alias "model_config" (not "model_config_data");
  artifact_hash is computed client-side via sha256 since we share the
  FS with the API on this single-host system.
- Winner selection: lowest aggregated WAPE, skipping NaN folds.

Also adds scripts/__init__.py so tests can `import scripts.run_demo`
without invoking the file as a script.

* feat(repo): top-level Makefile with demo / demo-quick / demo-clean (#128)

Wraps scripts/run_demo.py so reviewers can run the full end-to-end
demo with one command. Recipes mirror the three modes the script
supports: full run, skip-seed iteration, destructive reset.

Make targets:
- demo        — docker compose up -d + alembic + run_demo
- demo-quick  — run_demo --skip-seed (no compose/migration touch)
- demo-clean  — full reset (--reset) before seeding
- help        — default goal; lists targets + preconditions

Tab-indented recipes and .PHONY declarations per make conventions.
Preconditions (Postgres on :5433, uvicorn on :8123) documented in
the help block; the script itself enforces them via the precheck
step and exits 2 on failure.

* test(api): unit + integration coverage for run_demo (#128)

Unit (`tests/test_run_demo_unit.py`, 32 cases):
- argparse defaults + all-flags variants
- DemoContext defaults (no leaking state across runs)
- _select_winner: lowest-WAPE, NaN-skip, all-NaN -> None, empty -> None
- _model_config_payload: discriminated-union shape per baseline; rejects
  unsupported model_type (defends the "no lightgbm in PRP-15" boundary)
- Reporter: glyph mapping; verbose + quiet output; summary green / failure
  / over-budget soft-warn branches
- StepError formats RFC 7807 (title/detail/request_id) without leaking
  the raw response body
- HttpClient (mocked httpx.AsyncClient): 2xx, 204, non-2xx -> StepError
- Step payload sanity: seed sends demo_minimal+correct dims+ISO dates;
  features sends cutoff_date as ISO; train fires three model_types in
  parallel; agent step skips with ⏭️ when no LLM key

Integration (`tests/test_e2e_demo.py`, @pytest.mark.integration):
- Skips if Postgres on :5433 isn't reachable
- Boots uvicorn on :8124 as a subprocess (avoids the dev :8123 default)
- Runs scripts/run_demo.py --reset against it; asserts exit 0 +
  canonical "runs=3 winner=... alias=demo-production" summary
- Second case asserts a bogus URL exits 2 (no silent success)
- Cleans up uvicorn on teardown with terminate/kill fallback
- Resolves `uv` via shutil.which to keep ruff S607 happy and avoid
  PATH-dependent exec at test time

* ci(repo): nightly e2e demo workflow (#128)

Adds .github/workflows/e2e-nightly.yml — runs scripts/run_demo.py
against a fresh Postgres+pgvector service every night at 07:00 UTC
(plus on-demand via workflow_dispatch). Catches regressions in the
documented end-to-end pipeline before they bleed into the per-PR
gate.

Per PRP-15 + INITIAL-14 risk note: this workflow is intentionally
NOT a required status check on dev or main. Flake-budget lives in
the nightly slot, not in ci.yml.

- pgvector/pgvector:pg16 service container (same as ci.yml `test` job)
- uvicorn started in background; /health polled with a 30 s deadline
- run_demo.py called with --seed 42 (deterministic)
- LLM-key env vars intentionally absent — agent step auto-skips via
  ⏭️, keeping the workflow self-contained
- uvicorn logs uploaded as artifact on failure (7-day retention) so
  postmortems can read what the API was doing when the script broke
- astral-sh/setup-uv pinned by 40-char SHA per security-patterns.md
- permissions: contents: read (least-privilege)

* docs(docs): cross-link make demo from README + RUNBOOKS + REPO_MAP_INDEX (#128)

Discoverability layer for PRP-15.

- README.md: new 'Try it: end-to-end demo' step right after the curl
  /health verification; shows the canonical final-line summary so
  reviewers know what green looks like.
- docs/DAILY-FLOW.md: new 'First-Run Smoke (Demo Pipeline)' section
  documenting all three Make targets.
- docs/_base/RUNBOOKS.md: new 'make demo fails at step X' Common
  Incidents entry with a 7-point diagnosis flow keyed to the script's
  step names + a postmortem-capture recipe.
- docs/_base/REPO_MAP_INDEX.md: Makefile and scripts/run_demo.py rows
  added to the Document Index table.

Pure additive; no existing content removed or renamed.

* fix(data): update /seeder/scenarios route test for demo_minimal preset (#128)

Companion to feat(data): add demo_minimal scenario preset — the
route-level assertion in TestListScenarios.test_returns_scenarios still
expected 6 scenarios; bumping to 7 and adding the demo_minimal name
membership check to match the service-layer + config-layer tests
already updated in 005c189.

* fix(api): harden run_demo for integration test + real DB (#128)

Three real failures surfaced when first running the integration test
against docker-compose Postgres + a freshly booted uvicorn; all three
are now closed:

scripts/run_demo.py:
1. step_status: discover the real (store_id, product_id) from
   /dimensions/stores + /dimensions/products instead of hardcoding 1.
   Postgres auto-increment does NOT reset after delete, so the freshly
   seeded IDs are NOT 1 (they were ~150-260 on this branch after a few
   delete/seed cycles).
2. step_register: copy the trained-model artifact into the registry's
   own root (settings.registry_artifact_root) and record a registry-
   relative URI. The registry verify endpoint resolves artifact_uri
   against its own root, which is separate from where /forecasting/train
   writes (settings.forecast_model_artifacts_dir). Pre-fix, verify
   returned 404 even though the artifact existed on disk.
3. step_agent: skip with the soft-skip glyph on any LLM provider failure
   (invalid key, model unavailable, 5xx), and make _llm_key_present
   provider-aware so it matches the right env var to the configured
   agent_default_model. Pre-fix, an .env with anthropic/openai keys but
   a Gemini default model failed hard at chat-time.
4. Bumped DEFAULT_TIMEOUT_S from 60 to 120 because /seeder/generate
   for demo_minimal can spend 60-90 s on slower laptops once you
   include inventory + prices + promotions inserts.
5. step_seed detail string: GenerateResult.records_created uses 'sales'
   (singular), not 'sales_daily'; cosmetic fix.

tests/test_e2e_demo.py:
- Redirect uvicorn stdout to a temp file rather than subprocess.PIPE.
  The seeder + structlog produce enough INFO log volume to fill a
  64-KB pipe buffer; once full, uvicorn blocks on write and seeder
  requests hang for the full --timeout. Verified locally: integration
  suite now passes in ~6.5 s instead of timing out at 120 s.
- Cleanup leaves the log file on disk only when the test failed
  (postmortem-friendly).

tests/test_run_demo_unit.py:
- Bump test_defaults timeout expectation to match the new 120 s
  default.

End-to-end manual run on this machine: 11 steps, wall_clock=2 s,
exit 0. Integration test: 2 passed in 6.48 s.

* chore(repo): bump authlib + fastmcp to clear Socket-flagged CVEs (#130) (#131)

Headline:
- authlib  1.6.6  -> 1.7.2  (clears GHSA-wvwj-cvrp-7pv5 — JWS signature
  verification bypass; patched at >= 1.6.9)
- fastmcp  2.14.4 -> 3.2.4  (clears GHSA-vv7q-7jx5-f767 — OpenAPI
  Provider SSRF + path traversal; patched at >= 3.2.0)

Both CVEs were flagged on PR #129 by Socket Security and are
pre-existing on dev (not introduced by #128).

Wider scope — read before merging:
`uv lock --upgrade-package authlib --upgrade-package fastmcp` triggers
a full re-resolve of the dependency graph. Because dev's uv.lock had
drifted from pyproject.toml (the project's constraint envelope had
loosened over time), this single command also brings the lockfile in
sync with current pyproject.toml. Net diff: 243 insertions / 369
deletions on uv.lock; no other files touched.

Transitive cascades worth flagging:
- anthropic    0.77.0 -> 0.102.0 (pydantic-ai-slim extra)
- pydantic-graph 1.51.0 -> 1.96.0
- temporalio   1.20.0 -> 1.27.2
- alembic      1.18.1 -> 1.18.4
- aws-* and cohere transitives bumped along
- griffe 1.15.0 dropped in favor of griffelib 2.0.2 (fastmcp 3.x switched)
- Removed: cloudpickle, diskcache, fakeredis, invoke, lupa, prometheus
  exporter, pydocket, redis, rsa, sortedcontainers — these were
  transitives of fastmcp 2.x that fastmcp 3.x no longer pulls in.

Verification on this host:
- uv sync --extra dev  -> green
- ruff check .         -> clean
- mypy --strict app/   -> 192 files clean
- pyright app/         -> 0 errors (50 warnings, pre-existing)
- pytest -m 'not integration' -> 969 passed

Known install quirk: griffelib 2.0.2 ships a top-level `griffe/`
package whose RECORD files don't always materialize on first install
when uv replaces an older `griffe` dist in the same sync. A clean
venv install (which CI does via `uv sync --frozen`) is unaffected;
local devs who upgrade in place may need a one-shot
`uv pip install --force-reinstall griffelib` if `import griffe` fails.

* feat(api,ui): in-product demo showcase page (#132) (#133)

* feat(api): add demo slice driving the e2e pipeline via /demo endpoints (#132)

New app/features/demo slice exposing POST /demo/run and WS /demo/stream. It
drives the published API surface in-process via httpx.ASGITransport (no
cross-slice imports, satisfying the vertical-slice rule) and streams one
StepEvent per pipeline step: precheck -> reset -> seed -> status -> features
-> train x3 -> backtest x3 -> register -> verify -> agent -> cleanup.

A module-level asyncio.Lock enforces single-flight; concurrent runs get an
RFC 7807 409. The orchestration is a faithful in-process port of
scripts/run_demo.py (PR #129). Implements PRP-17.

* test(api): cover the demo slice pipeline, routes, and e2e integration (#132)

Unit tests mock the in-process HTTP client to exercise step sequencing,
winner selection, and fail-fast; route tests cover POST /demo/run (200 +
409) and the WS /demo/stream handler. The integration test seeds
demo_minimal and asserts an end-to-end green run against real Postgres.

Implements PRP-17.

* feat(ui): add showcase page streaming the live demo pipeline (#132)

New /showcase route and nav entry. The page opens a one-shot WebSocket to
/demo/stream via a use-demo-pipeline hook (wrapping useWebSocket) and renders
the 11 pipeline steps as live status cards: glyph, detail, duration, the
backtest per-model WAPE breakdown with the winner highlighted, and a
pass/fail summary banner.

Also block-scopes a pre-existing no-case-declarations lint error in
chat.tsx so pnpm lint is green for this PR. Implements PRP-17.

* test(ui): add vitest setup and use-demo-pipeline hook coverage (#132)

Adds the frontend test stack (vitest + jsdom + @testing-library/react), a
test script, and vitest.config.ts. use-demo-pipeline.test.ts covers the
pure event reducer (idle -> running -> pass transitions, summary assembly,
error phase) and a renderHook smoke test.

The package.json pnpm.onlyBuiltDependencies entry is the RUNBOOKS-documented
fix for pnpm 11's esbuild build-script gate. Implements PRP-17.

* docs(docs): document the demo slice and showcase page (#132)

Adds the PRP-17 spec; a 'Try it in the browser' pointer in README; the
/demo/run + /demo/stream rows and a WebSocket Events section in
API_CONTRACTS; a 'Showcase pipeline fails' runbook incident; and
REPO_MAP_INDEX rows for the demo slice and showcase page.

Implements PRP-17.

* chore(main): release 0.2.10 (#135)

* docs(docs): fix broken PRP-0/INITIAL-0 relative links in phase 0 doc (#138) (#139)

* docs(repo): fix readme dev-deps command and stale .github template placeholders (#140) (#141)

* docs(docs): fill DEV_GUIDE.md onboarding stub sections (#142) (#143)

* docs(repo): refresh stale CLAUDE.md note, document /demo API, align PR template (#144) (#145)

* fix(ui): chart series render black — drop hsl() wrapper on oklch chart vars (#149) (#153)

index.css defines --chart-N twice: legacy shadcn-v3 HSL triplets and
Tailwind-4 / shadcn-v4 complete oklch() colours. The oklch definitions win
the cascade, so at runtime --chart-N is a full colour. The chart components
still wrapped it as hsl(var(--chart-N)) → hsl(oklch(...)), which is invalid
CSS, so recharts fell back to a black fill/stroke — invisible on the dark
theme.

Reference var(--chart-N) directly in backtest-folds-chart.tsx and
time-series-chart.tsx. Verified in a browser: the backtest per-fold bars
and the forecast line now render in colour.

* fix(jobs): backtest job result keeps fold metrics, stability and baselines (#148) (#152)

* fix(jobs): backtest job result keeps fold metrics, stability and baselines (#148)

_execute_backtest ran BacktestingService.run_backtest — which computes
per-fold metrics, stability indices and a naive/seasonal baseline comparison
— but stored only four aggregated values and discarded the rest. The
dashboard (/visualize/backtest) reads aggregated_metrics.{*_mean,
stability_index}, fold_metrics[] and baseline_comparison, so it showed
"0 folds", all-zero metrics and an empty chart.

Add _shape_backtest_result(), which flattens a BacktestResponse into the
contract the dashboard expects, and _finite(), which coerces NaN/inf to 0.0
so the result stays JSONB-safe (stability is NaN with fewer than two folds).

Add app/features/jobs/tests/test_service.py with unit coverage for the
shaping logic: fold metrics, *_mean keys, stability, baseline comparison,
the no-baselines path, and NaN coercion.

* refactor(jobs): centralize backtest metric keys and surface drift (#148)

Addresses review feedback on PR #152.

- Hoist the dashboard's metric set into _BACKTEST_METRICS and the headline
  stability metric into _STABILITY_METRIC, so the hardcoded keys live in one
  documented place instead of being repeated across the shaping logic.
- Log jobs.backtest_metrics_missing when an expected metric is absent from the
  backtest response, so a future rename in the backtesting service fails loud
  instead of silently emitting 0.0.
- Document the WAPE stability convention in the _shape_backtest_result docstring.
- Tests: assert backtest_id / model_type / duration_ms pass through unchanged,
  and add a regression test for the missing-metric default path.

* fix(ui): forecast page reads forecasts/forecast from predict job result (#147) (#151)

The /visualize/forecast page never rendered the chart for a valid completed
predict job. It read job.result.predictions with field `predicted`, but
POST /jobs (job_type="predict") returns job.result.forecasts with field
`forecast`. forecastData was therefore always undefined and the page fell
through to "No prediction data available in job result".

Read result.forecasts with field `forecast`, and pass predictedKey="forecast"
to TimeSeriesChart (which already supports a configurable data key).

Verified in a browser: entering a completed predict job ID now renders the
14-day forecast line chart with correct tooltip values.

* fix(registry): tolerate multiple matches in _find_duplicate (#146) (#150)

Under the default registry_duplicate_policy="detect", duplicate runs are
created intentionally, so multiple non-archived model_run rows can share one
config hash. _find_duplicate used scalar_one_or_none(), which raised
MultipleResultsFound once two duplicates existed — POST /registry/runs then
returned HTTP 500. This made the demo/Showcase register step fail
deterministically on any DB with repeated runs.

Order the lookup by created_at desc, LIMIT 1, and use scalars().first() so it
returns the most recent matching run instead of asserting a single match.

Add an integration regression test that POSTs an identical run three times
under the detect policy and asserts all three return 201.

* fix(ui): derive TimeSeriesChart line stroke from the config key (#156) (#157)

TimeSeriesChart builds chartConfig with dynamic keys ([actualKey] /
[predictedKey]), so shadcn's ChartContainer injects --color-<key> CSS
variables. The <Line> elements, however, hardcoded stroke="var(--color-actual)"
and stroke="var(--color-predicted)". The forecast page passes
predictedKey="forecast", so the injected variable is --color-forecast;
var(--color-predicted) was undefined, the stroke was invalid, and SVG fell
back to its initial value `none` — the forecast line was invisible.

Build the stroke from the key: stroke={`var(--color-${actualKey})`} /
stroke={`var(--color-${predictedKey})`}.

Verified in a browser: the forecast line now renders in colour.

* feat(ui): job picker dropdown on forecast and backtest pages (#154) (#155)

The visualization pages only accepted a job ID typed into a text box, so
users had to already know the ID. Add a JobPicker component: a dropdown of
completed jobs of the relevant type (predict / backtest), newest first, with
each option labelled by short id, model and timestamp.

- New shared component src/components/common/job-picker.tsx, used by both
  forecast.tsx and backtest.tsx.
- The manual job-ID input stays alongside the dropdown for pasting an ID.
- The most recent completed job auto-loads on mount so a chart shows
  immediately without interaction.

No backend change — GET /jobs?job_type=&status=completed already exists.
Verified in a browser on both pages.

* chore(repo): back-merge main into dev after v0.2.11 (#160) (#161)

* chore(main): release 0.2.9 (#126)

* feat: release v0.2.10 — demo showcase page + e2e pipeline (#134)

* feat(data): implement MarkdownGenerator age_days trigger via heuristic (#94) (#127)

Resolves #94 via the heuristic path documented in the issue. No schema
column, no Alembic migration, no FIFO cohort tracking — the trigger
self-reads the existing per-(store, product) on_hand_qty series and
fires when inventory has been "unrefreshed" past
`cfg.age_days_threshold`.

Decision rationale (schema column vs. heuristic):
- The schema column path would add `oldest_unit_age_days` to
  `inventory_snapshot_daily`, plus an Alembic migration, plus FIFO
  cohort tracking in `InventorySnapshotGenerator`. No downstream
  consumer reads this column today — adding it for one generator
  trigger violates the "don't design for hypothetical future
  requirements" rule in CLAUDE.md.
- The heuristic path is self-contained in MarkdownGenerator,
  deterministic (preserves the zero-rng-draw regression invariant),
  and additive (no migration, no model change). 354 LOC net, all
  inside one slice.

Heuristic spec:
- A "refresh" is a day where `on_hand_qty` rose by >=
  `_AGE_DAYS_SPIKE_THRESHOLD` (0.3 = 30% jump) vs the prior day.
- Age at day t = days since most recent refresh (or `dates[0]` if no
  refresh has been observed).
- Firing requires age >= `age_days_threshold` AND on_hand >=
  `markdown_min_units_remaining` — never markdown an empty shelf.
- After firing, refresh anchor resets to the day AFTER the markdown
  window ends, so back-to-back fires can't happen and the next age
  clock starts from a "clear shelf" baseline.

Wiring: `MarkdownGenerator.generate()` gains an optional kwarg
`inventory_records: list[dict[str, Any]] | None = None` which `core.py`
passes through from `InventorySnapshotGenerator`. Disabled-path and
non-age_days-path behavior is byte-identical (kwarg ignored).

Tests: +7 new in `TestAgeDaysTrigger`, -1 obsolete
`NotImplementedError` test. Coverage: no-records defensive, threshold
not-met, threshold met, spike resets age, post-fire reset avoids
back-to-back, low-inventory skip, unknown-product skip, rng
non-consumption.

Validation (local):
- ruff check + format: clean
- mypy --strict: 0 issues, 192 files
- pyright --strict: 0 errors
- pytest -m "not integration": 969 passed (+7 vs pre-PR)

Closes #94.

* feat(api,docs): e2e demo pipeline + showcase script (#128) (#129)

* docs(docs): add INITIAL-14 + PRP-15 e2e demo pipeline plan (#128)

Adds the planning documents for the end-to-end demo pipeline work tracked
in #128. Implementation commits follow on this branch.

- INITIAL-14.md: PRD for `make demo` (problem, solution, success metrics,
  open questions resolved in the PRP).
- PRPs/PRP-15-e2e-demo-pipeline.md: full execution plan (16 tasks → 6
  commits, additive only — no schema changes, no API edits).

* feat(data): add demo_minimal scenario preset (#128)

Tiny preset that powers the upcoming `make demo` target. Three stores ×
ten products × 92 days (2024-10-01..2024-12-31) — wide enough to satisfy
an expanding backtest with n_splits=3, horizon=14, min_train_size=30
(needs >= 72 days, 92 leaves margin), small enough to keep the demo
loop comfortable on a laptop.

Mirrors the retail_standard tuning (mild linear trend, noise_sigma=0.10,
modest promotion + stockout probabilities) so backtest WAPE stays
non-NaN across all three baseline models.

- app/shared/seeder/config.py: add DEMO_MINIMAL enum + from_scenario branch
- app/features/seeder/service.py: add ScenarioInfo entry in list_scenarios
- tests cover the new preset and the updated scenario count

* feat(api,docs): scripts/run_demo.py end-to-end pipeline driver (#128)

Single-file async driver that walks the published HTTP surface
(precheck -> reset? -> seed -> status -> features -> train x3 ->
backtest x3 -> register -> verify -> agent -> cleanup). Mirrors the
shape of scripts/seed_random.py and scripts/check_db.py.

- HttpClient: thin httpx.AsyncClient wrapper with explicit 60 s
  timeout (default 5 s is too short for /seeder/generate); surfaces
  RFC 7807 problem+json bodies as a typed StepError that echoes
  title / detail / request_id (never the raw body — secrets-safe).
- DemoContext + StepOutcome dataclasses thread cross-step references.
- Reporter renders the output-formatting.md glyphs (verbose by
  default, --quiet collapses to one line per step).
- Per-step error handling converts httpx + StepError into fail
  outcomes; precheck failure exits 2, any other failure exits 1,
  green exits 0.
- Agent step (10/11) skips with ⏭️ when neither OPENAI_API_KEY nor
  ANTHROPIC_API_KEY is set; reads via app.core.config.get_settings()
  to honor the no-os.environ-in-feature-code rule.
- Registry handshake uses the mandatory pending -> running -> success
  transition and the wire alias "model_config" (not "model_config_data");
  artifact_hash is computed client-side via sha256 since we share the
  FS with the API on this single-host system.
- Winner selection: lowest aggregated WAPE, skipping NaN folds.

Also adds scripts/__init__.py so tests can `import scripts.run_demo`
without invoking the file as a script.

* feat(repo): top-level Makefile with demo / demo-quick / demo-clean (#128)

Wraps scripts/run_demo.py so reviewers can run the full end-to-end
demo with one command. Recipes mirror the three modes the script
supports: full run, skip-seed iteration, destructive reset.

Make targets:
- demo        — docker compose up -d + alembic + run_demo
- demo-quick  — run_demo --skip-seed (no compose/migration touch)
- demo-clean  — full reset (--reset) before seeding
- help        — default goal; lists targets + preconditions

Tab-indented recipes and .PHONY declarations per make conventions.
Preconditions (Postgres on :5433, uvicorn on :8123) documented in
the help block; the script itself enforces them via the precheck
step and exits 2 on failure.

* test(api): unit + integration coverage for run_demo (#128)

Unit (`tests/test_run_demo_unit.py`, 32 cases):
- argparse defaults + all-flags variants
- DemoContext defaults (no leaking state across runs)
- _select_winner: lowest-WAPE, NaN-skip, all-NaN -> None, empty -> None
- _model_config_payload: discriminated-union shape per baseline; rejects
  unsupported model_type (defends the "no lightgbm in PRP-15" boundary)
- Reporter: glyph mapping; verbose + quiet output; summary green / failure
  / over-budget soft-warn branches
- StepError formats RFC 7807 (title/detail/request_id) without leaking
  the raw response body
- HttpClient (mocked httpx.AsyncClient): 2xx, 204, non-2xx -> StepError
- Step payload sanity: seed sends demo_minimal+correct dims+ISO dates;
  features sends cutoff_date as ISO; train fires three model_types in
  parallel; agent step skips with ⏭️ when no LLM key

Integration (`tests/test_e2e_demo.py`, @pytest.mark.integration):
- Skips if Postgres on :5433 isn't reachable
- Boots uvicorn on :8124 as a subprocess (avoids the dev :8123 default)
- Runs scripts/run_demo.py --reset against it; asserts exit 0 +
  canonical "runs=3 winner=... alias=demo-production" summary
- Second case asserts a bogus URL exits 2 (no silent success)
- Cleans up uvicorn on teardown with terminate/kill fallback
- Resolves `uv` via shutil.which to keep ruff S607 happy and avoid
  PATH-dependent exec at test time

* ci(repo): nightly e2e demo workflow (#128)

Adds .github/workflows/e2e-nightly.yml — runs scripts/run_demo.py
against a fresh Postgres+pgvector service every night at 07:00 UTC
(plus on-demand via workflow_dispatch). Catches regressions in the
documented end-to-end pipeline before they bleed into the per-PR
gate.

Per PRP-15 + INITIAL-14 risk note: this workflow is intentionally
NOT a required status check on dev or main. Flake-budget lives in
the nightly slot, not in ci.yml.

- pgvector/pgvector:pg16 service container (same as ci.yml `test` job)
- uvicorn started in background; /health polled with a 30 s deadline
- run_demo.py called with --seed 42 (deterministic)
- LLM-key env vars intentionally absent — agent step auto-skips via
  ⏭️, keeping the workflow self-contained
- uvicorn logs uploaded as artifact on failure (7-day retention) so
  postmortems can read what the API was doing when the script broke
- astral-sh/setup-uv pinned by 40-char SHA per security-patterns.md
- permissions: contents: read (least-privilege)

* docs(docs): cross-link make demo from README + RUNBOOKS + REPO_MAP_INDEX (#128)

Discoverability layer for PRP-15.

- README.md: new 'Try it: end-to-end demo' step right after the curl
  /health verification; shows the canonical final-line summary so
  reviewers know what green looks like.
- docs/DAILY-FLOW.md: new 'First-Run Smoke (Demo Pipeline)' section
  documenting all three Make targets.
- docs/_base/RUNBOOKS.md: new 'make demo fails at step X' Common
  Incidents entry with a 7-point diagnosis flow keyed to the script's
  step names + a postmortem-capture recipe.
- docs/_base/REPO_MAP_INDEX.md: Makefile and scripts/run_demo.py rows
  added to the Document Index table.

Pure additive; no existing content removed or renamed.

* fix(data): update /seeder/scenarios route test for demo_minimal preset (#128)

Companion to feat(data): add demo_minimal scenario preset — the
route-level assertion in TestListScenarios.test_returns_scenarios still
expected 6 scenarios; bumping to 7 and adding the demo_minimal name
membership check to match the service-layer + config-layer tests
already updated in 005c189.

* fix(api): harden run_demo for integration test + real DB (#128)

Three real failures surfaced when first running the integration test
against docker-compose Postgres + a freshly booted uvicorn; all three
are now closed:

scripts/run_demo.py:
1. step_status: discover the real (store_id, product_id) from
   /dimensions/stores + /dimensions/products instead of hardcoding 1.
   Postgres auto-increment does NOT reset after delete, so the freshly
   seeded IDs are NOT 1 (they were ~150-260 on this branch after a few
   delete/seed cycles).
2. step_register: copy the trained-model artifact into the registry's
   own root (settings.registry_artifact_root) and record a registry-
   relative URI. The registry verify endpoint resolves artifact_uri
   against its own root, which is separate from where /forecasting/train
   writes (settings.forecast_model_artifacts_dir). Pre-fix, verify
   returned 404 even though the artifact existed on disk.
3. step_agent: skip with the soft-skip glyph on any LLM provider failure
   (invalid key, model unavailable, 5xx), and make _llm_key_present
   provider-aware so it matches the right env var to the configured
   agent_default_model. Pre-fix, an .env with anthropic/openai keys but
   a Gemini default model failed hard at chat-time.
4. Bumped DEFAULT_TIMEOUT_S from 60 to 120 because /seeder/generate
   for demo_minimal can spend 60-90 s on slower laptops once you
   include inventory + prices + promotions inserts.
5. step_seed detail string: GenerateResult.records_created uses 'sales'
   (singular), not 'sales_daily'; cosmetic fix.

tests/test_e2e_demo.py:
- Redirect uvicorn stdout to a temp file rather than subprocess.PIPE.
  The seeder + structlog produce enough INFO log volume to fill a
  64-KB pipe buffer; once full, uvicorn blocks on write and seeder
  requests hang for the full --timeout. Verified locally: integration
  suite now passes in ~6.5 s instead of timing out at 120 s.
- Cleanup leaves the log file on disk only when the test failed
  (postmortem-friendly).

tests/test_run_demo_unit.py:
- Bump test_defaults timeout expectation to match the new 120 s
  default.

End-to-end manual run on this machine: 11 steps, wall_clock=2 s,
exit 0. Integration test: 2 passed in 6.48 s.

* chore(repo): bump authlib + fastmcp to clear Socket-flagged CVEs (#130) (#131)

Headline:
- authlib  1.6.6  -> 1.7.2  (clears GHSA-wvwj-cvrp-7pv5 — JWS signature
  verification bypass; patched at >= 1.6.9)
- fastmcp  2.14.4 -> 3.2.4  (clears GHSA-vv7q-7jx5-f767 — OpenAPI
  Provider SSRF + path traversal; patched at >= 3.2.0)

Both CVEs were flagged on PR #129 by Socket Security and are
pre-existing on dev (not introduced by #128).

Wider scope — read before merging:
`uv lock --upgrade-package authlib --upgrade-package fastmcp` triggers
a full re-resolve of the dependency graph. Because dev's uv.lock had
drifted from pyproject.toml (the project's constraint envelope had
loosened over time), this single command also brings the lockfile in
sync with current pyproject.toml. Net diff: 243 insertions / 369
deletions on uv.lock; no other files touched.

Transitive cascades worth flagging:
- anthropic    0.77.0 -> 0.102.0 (pydantic-ai-slim extra)
- pydantic-graph 1.51.0 -> 1.96.0
- temporalio   1.20.0 -> 1.27.2
- alembic      1.18.1 -> 1.18.4
- aws-* and cohere transitives bumped along
- griffe 1.15.0 dropped in favor of griffelib 2.0.2 (fastmcp 3.x switched)
- Removed: cloudpickle, diskcache, fakeredis, invoke, lupa, prometheus
  exporter, pydocket, redis, rsa, sortedcontainers — these were
  transitives of fastmcp 2.x that fastmcp 3.x no longer pulls in.

Verification on this host:
- uv sync --extra dev  -> green
- ruff check .         -> clean
- mypy --strict app/   -> 192 files clean
- pyright app/         -> 0 errors (50 warnings, pre-existing)
- pytest -m 'not integration' -> 969 passed

Known install quirk: griffelib 2.0.2 ships a top-level `griffe/`
package whose RECORD files don't always materialize on first install
when uv replaces an older `griffe` dist in the same sync. A clean
venv install (which CI does via `uv sync --frozen`) is unaffected;
local devs who upgrade in place may need a one-shot
`uv pip install --force-reinstall griffelib` if `import griffe` fails.

* feat(api,ui): in-product demo showcase page (#132) (#133)

* feat(api): add demo slice driving the e2e pipeline via /demo endpoints (#132)

New app/features/demo slice exposing POST /demo/run and WS /demo/stream. It
drives the published API surface in-process via httpx.ASGITransport (no
cross-slice imports, satisfying the vertical-slice rule) and streams one
StepEvent per pipeline step: precheck -> reset -> seed -> status -> features
-> train x3 -> backtest x3 -> register -> verify -> agent -> cleanup.

A module-level asyncio.Lock enforces single-flight; concurrent runs get an
RFC 7807 409. The orchestration is a faithful in-process port of
scripts/run_demo.py (PR #129). Implements PRP-17.

* test(api): cover the demo slice pipeline, routes, and e2e integration (#132)

Unit tests mock the in-process HTTP client to exercise step sequencing,
winner selection, and fail-fast; route tests cover POST /demo/run (200 +
409) and the WS /demo/stream handler. The integration test seeds
demo_minimal and asserts an end-to-end green run against real Postgres.

Implements PRP-17.

* feat(ui): add showcase page streaming the live demo pipeline (#132)

New /showcase route and nav entry. The page opens a one-shot WebSocket to
/demo/stream via a use-demo-pipeline hook (wrapping useWebSocket) and renders
the 11 pipeline steps as live status cards: glyph, detail, duration, the
backtest per-model WAPE breakdown with the winner highlighted, and a
pass/fail summary banner.

Also block-scopes a pre-existing no-case-declarations lint error in
chat.tsx so pnpm lint is green for this PR. Implements PRP-17.

* test(ui): add vitest setup and use-demo-pipeline hook coverage (#132)

Adds the frontend test stack (vitest + jsdom + @testing-library/react), a
test script, and vitest.config.ts. use-demo-pipeline.test.ts covers the
pure event reducer (idle -> running -> pass transitions, summary assembly,
error phase) and a renderHook smoke test.

The package.json pnpm.onlyBuiltDependencies entry is the RUNBOOKS-documented
fix for pnpm 11's esbuild build-script gate. Implements PRP-17.

* docs(docs): document the demo slice and showcase page (#132)

Adds the PRP-17 spec; a 'Try it in the browser' pointer in README; the
/demo/run + /demo/stream rows and a WebSocket Events section in
API_CONTRACTS; a 'Showcase pipeline fails' runbook incident; and
REPO_MAP_INDEX rows for the demo slice and showcase page.

Implements PRP-17.

* chore(main): release 0.2.10 (#135)

* feat: release v0.2.11 — visualization fixes, job picker, demo showcase (#158)

* feat(data): implement MarkdownGenerator age_days trigger via heuristic (#94) (#127)

Resolves #94 via the heuristic path documented in the issue. No schema
column, no Alembic migration, no FIFO cohort tracking — the trigger
self-reads the existing per-(store, product) on_hand_qty series and
fires when inventory has been "unrefreshed" past
`cfg.age_days_threshold`.

Decision rationale (schema column vs. heuristic):
- The schema column path would add `oldest_unit_age_days` to
  `inventory_snapshot_daily`, plus an Alembic migration, plus FIFO
  cohort tracking in `InventorySnapshotGenerator`. No downstream
  consumer reads this column today — adding it for one generator
  trigger violates the "don't design for hypothetical future
  requirements" rule in CLAUDE.md.
- The heuristic path is self-contained in MarkdownGenerator,
  deterministic (preserves the zero-rng-draw regression invariant),
  and additive (no migration, no model change). 354 LOC net, all
  inside one slice.

Heuristic spec:
- A "refresh" is a day where `on_hand_qty` rose by >=
  `_AGE_DAYS_SPIKE_THRESHOLD` (0.3 = 30% jump) vs the prior day.
- Age at day t = days since most recent refresh (or `dates[0]` if no
  refresh has been observed).
- Firing requires age >= `age_days_threshold` AND on_hand >=
  `markdown_min_units_remaining` — never markdown an empty shelf.
- After firing, refresh anchor resets to the day AFTER the markdown
  window ends, so back-to-back fires can't happen and the next age
  clock starts from a "clear shelf" baseline.

Wiring: `MarkdownGenerator.generate()` gains an optional kwarg
`inventory_records: list[dict[str, Any]] | None = None` which `core.py`
passes through from `InventorySnapshotGenerator`. Disabled-path and
non-age_days-path behavior is byte-identical (kwarg ignored).

Tests: +7 new in `TestAgeDaysTrigger`, -1 obsolete
`NotImplementedError` test. Coverage: no-records defensive, threshold
not-met, threshold met, spike resets age, post-fire reset avoids
back-to-back, low-inventory skip, unknown-product skip, rng
non-consumption.

Validation (local):
- ruff check + format: clean
- mypy --strict: 0 issues, 192 files
- pyright --strict: 0 errors
- pytest -m "not integration": 969 passed (+7 vs pre-PR)

Closes #94.

* feat(api,docs): e2e demo pipeline + showcase script (#128) (#129)

* docs(docs): add INITIAL-14 + PRP-15 e2e demo pipeline plan (#128)

Adds the planning documents for the end-to-end demo pipeline work tracked
in #128. Implementation commits follow on this branch.

- INITIAL-14.md: PRD for `make demo` (problem, solution, success metrics,
  open questions resolved in the PRP).
- PRPs/PRP-15-e2e-demo-pipeline.md: full execution plan (16 tasks → 6
  commits, additive only — no schema changes, no API edits).

* feat(data): add demo_minimal scenario preset (#128)

Tiny preset that powers the upcoming `make demo` target. Three stores ×
ten products × 92 days (2024-10-01..2024-12-31) — wide enough to satisfy
an expanding backtest with n_splits=3, horizon=14, min_train_size=30
(needs >= 72 days, 92 leaves margin), small enough to keep the demo
loop comfortable on a laptop.

Mirrors the retail_standard tuning (mild linear trend, noise_sigma=0.10,
modest promotion + stockout probabilities) so backtest WAPE stays
non-NaN across all three baseline models.

- app/shared/seeder/config.py: add DEMO_MINIMAL enum + from_scenario branch
- app/features/seeder/service.py: add ScenarioInfo entry in list_scenarios
- tests cover the new preset and the updated scenario count

* feat(api,docs): scripts/run_demo.py end-to-end pipeline driver (#128)

Single-file async driver that walks the published HTTP surface
(precheck -> reset? -> seed -> status -> features -> train x3 ->
backtest x3 -> register -> verify -> agent -> cleanup). Mirrors the
shape of scripts/seed_random.py and scripts/check_db.py.

- HttpClient: thin httpx.AsyncClient wrapper with explicit 60 s
  timeout (default 5 s is too short for /seeder/generate); surfaces
  RFC 7807 problem+json bodies as a typed StepError that echoes
  title / detail / request_id (never the raw body — secrets-safe).
- DemoContext + StepOutcome dataclasses thread cross-step references.
- Reporter renders the output-formatting.md glyphs (verbose by
  default, --quiet collapses to one line per step).
- Per-step error handling converts httpx + StepError into fail
  outcomes; precheck failure exits 2, any other failure exits 1,
  green exits 0.
- Agent step (10/11) skips with ⏭️ when neither OPENAI_API_KEY nor
  ANTHROPIC_API_KEY is set; reads via app.core.config.get_settings()
  to honor the no-os.environ-in-feature-code rule.
- Registry handshake uses the mandatory pending -> running -> success
  transition and the wire alias "model_config" (not "model_config_data");
  artifact_hash is computed client-side via sha256 since we share the
  FS with the API on this single-host system.
- Winner selection: lowest aggregated WAPE, skipping NaN folds.

Also adds scripts/__init__.py so tests can `import scripts.run_demo`
without invoking the file as a script.

* feat(repo): top-level Makefile with demo / demo-quick / demo-clean (#128)

Wraps scripts/run_demo.py so reviewers can run the full end-to-end
demo with one command. Recipes mirror the three modes the script
supports: full run, skip-seed iteration, destructive reset.

Make targets:
- demo        — docker compose up -d + alembic + run_demo
- demo-quick  — run_demo --skip-seed (no compose/migration touch)
- demo-clean  — full reset (--reset) before seeding
- help        — default goal; lists targets + preconditions

Tab-indented recipes and .PHONY declarations per make conventions.
Preconditions (Postgres on :5433, uvicorn on :8123) documented in
the help block; the script itself enforces them via the precheck
step and exits 2 on failure.

* test(api): unit + integration coverage for run_demo (#128)

Unit (`tests/test_run_demo_unit.py`, 32 cases):
- argparse defaults + all-flags variants
- DemoContext defaults (no leaking state across runs)
- _select_winner: lowest-WAPE, NaN-skip, all-NaN -> None, empty -> None
- _model_config_payload: discriminated-union shape per baseline; rejects
  unsupported model_type (defends the "no lightgbm in PRP-15" boundary)
- Reporter: glyph mapping; verbose + quiet output; summary green / failure
  / over-budget soft-warn branches
- StepError formats RFC 7807 (title/detail/request_id) without leaking
  the raw response body
- HttpClient (mocked httpx.AsyncClient): 2xx, 204, non-2xx -> StepError
- Step payload sanity: seed sends demo_minimal+correct dims+ISO dates;
  features sends cutoff_date as ISO; train fires three model_types in
  parallel; agent step skips with ⏭️ when no LLM key

Integration (`tests/test_e2e_demo.py`, @pytest.mark.integration):
- Skips if Postgres on :5433 isn't reachable
- Boots uvicorn on :8124 as a subprocess (avoids the dev :8123 default)
- Runs scripts/run_demo.py --reset against it; asserts exit 0 +
  canonical "runs=3 winner=... alias=demo-production" summary
- Second case asserts a bogus URL exits 2 (no silent success)
- Cleans up uvicorn on teardown with terminate/kill fallback
- Resolves `uv` via shutil.which to keep ruff S607 happy and avoid
  PATH-dependent exec at test time

* ci(repo): nightly e2e demo workflow (#128)

Adds .github/workflows/e2e-nightly.yml — runs scripts/run_demo.py
against a fresh Postgres+pgvector service every night at 07:00 UTC
(plus on-demand via workflow_dispatch). Catches regressions in the
documented end-to-end pipeline before they bleed into the per-PR
gate.

Per PRP-15 + INITIAL-14 risk note: this workflow is intentionally
NOT a required status check on dev or main. Flake-budget lives in
the nightly slot, not in ci.yml.

- pgvector/pgvector:pg16 service container (same as ci.yml `test` job)
- uvicorn started in background; /health polled with a 30 s deadline
- run_demo.py called with --seed 42 (deterministic)
- LLM-key env vars intentionally absent — agent step auto-skips via
  ⏭️, keeping the workflow self-contained
- uvicorn logs uploaded as artifact on failure (7-day retention) so
  postmortems can read what the API was doing when the script broke
- astral-sh/setup-uv pinned by 40-char SHA per security-patterns.md
- permissions: contents: read (least-privilege)

* docs(docs): cross-link make demo from README + RUNBOOKS + REPO_MAP_INDEX (#128)

Discoverability layer for PRP-15.

- README.md: new 'Try it: end-to-end demo' step right after the curl
  /health verification; shows the canonical final-line summary so
  reviewers know what green looks like.
- docs/DAILY-FLOW.md: new 'First-Run Smoke (Demo Pipeline)' section
  documenting all three Make targets.
- docs/_base/RUNBOOKS.md: new 'make demo fails at step X' Common
  Incidents entry with a 7-point diagnosis flow keyed to the script's
  step names + a postmortem-capture recipe.
- docs/_base/REPO_MAP_INDEX.md: Makefile and scripts/run_demo.py rows
  added to the Document Index table.

Pure additive; no existing content removed or renamed.

* fix(data): update /seeder/scenarios route test for demo_minimal preset (#128)

Companion to feat(data): add demo_minimal scenario preset — the
route-level assertion in TestListScenarios.test_returns_scenarios still
expected 6 scenarios; bumping to 7 and adding the demo_minimal name
membership check to match the service-layer + config-layer tests
already updated in 005c189.

* fix(api): harden run_demo for integration test + real DB (#128)

Three real failures surfaced when first running the integration test
against docker-compose Postgres + a freshly booted uvicorn; all three
are now closed:

scripts/run_demo.py:
1. step_status: discover the real (store_id, product_id) from
   /dimensions/stores + /dimensions/products instead of hardcoding 1.
   Postgres auto-increment does NOT reset after delete, so the freshly
   seeded IDs are NOT 1 (they were ~150-260 on this branch after a few
   delete/seed cycles).
2. step_register: copy the trained-model artifact into the registry's
   own root (settings.registry_artifact_root) and record a registry-
   relative URI. The registry verify endpoint resolves artifact_uri
   against its own root, which is separate from where /forecasting/train
   writes (settings.forecast_model_artifacts_dir). Pre-fix, verify
   returned 404 even though the artifact existed on disk.
3. step_agent: skip with the soft-skip glyph on any LLM provider failure
   (invalid key, model unavailable, 5xx), and make _llm_key_present
   provider-aware so it matches the right env var to the configured
   agent_default_model. Pre-fix, an .env with anthropic/openai keys but
   a Gemini default model failed hard at chat-time.
4. Bumped DEFAULT_TIMEOUT_S from 60 to 120 because /seeder/generate
   for demo_minimal can spend 60-90 s on slower laptops once you
   include inventory + prices + promotions inserts.
5. step_seed detail string: GenerateResult.records_created uses 'sales'
   (singular), not 'sales_daily'; cosmetic fix.

tests/test_e2e_demo.py:
- Redirect uvicorn stdout to a temp file rather than subprocess.PIPE.
  The seeder + structlog produce enough INFO log volume to fill a
  64-KB pipe buffer; once full, uvicorn blocks on write and seeder
  requests hang for the full --timeout. Verified locally: integration
  suite now passes in ~6.5 s instead of timing out at 120 s.
- Cleanup leaves the log file on disk only when the test failed
  (postmortem-friendly).

tests/test_run_demo_unit.py:
- Bump test_defaults timeout expectation to match the new 120 s
  default.

End-to-end manual run on this machine: 11 steps, wall_clock=2 s,
exit 0. Integration test: 2 passed in 6.48 s.

* chore(repo): bump authlib + fastmcp to clear Socket-flagged CVEs (#130) (#131)

Headline:
- authlib  1.6.6  -> 1.7.2  (clears GHSA-wvwj-cvrp-7pv5 — JWS signature
  verification bypass; patched at >= 1.6.9)
- fastmcp  2.14.4 -> 3.2.4  (clears GHSA-vv7q-7jx5-f767 — OpenAPI
  Provider SSRF + path traversal; patched at >= 3.2.0)

Both CVEs were flagged on PR #129 by Socket Security and are
pre-existing on dev (not introduced by #128).

Wider scope — read before merging:
`uv lock --upgrade-package authlib --upgrade-package fastmcp` triggers
a full re-resolve of the dependency graph. Because dev's uv.lock had
drifted from pyproject.toml (the project's constraint envelope had
loosened over time), this single command also brings the lockfile in
sync with current pyproject.toml. Net diff: 243 insertions / 369
deletions on uv.lock; no other files touched.

Transitive cascades worth flagging:
- anthropic    0.77.0 -> 0.102.0 (pydantic-ai-slim extra)
- pydantic-graph 1.51.0 -> 1.96.0
- temporalio   1.20.0 -> 1.27.2
- alembic      1.18.1 -> 1.18.4
- aws-* and cohere transitives bumped along
- griffe 1.15.0 dropped in favor of griffelib 2.0.2 (fastmcp 3.x switched)
- Removed: cloudpickle, diskcache, fakeredis, invoke, lupa, prometheus
  exporter, pydocket, redis, rsa, sortedcontainers — these were
  transitives of fastmcp 2.x that fastmcp 3.x no longer pulls in.

Verification on this host:
- uv sync --extra dev  -> green
- ruff check .         -> clean
- mypy --strict app/   -> 192 files clean
- pyright app/         -> 0 errors (50 warnings, pre-existing)
- pytest -m 'not integration' -> 969 passed

Known install quirk: griffelib 2.0.2 ships a top-level `griffe/`
package whose RECORD files don't always materialize on first install
when uv replaces an older `griffe` dist in the same sync. A clean
venv install (which CI does via `uv sync --frozen`) is unaffected;
local devs who upgrade in place may need a one-shot
`uv pip install --force-reinstall griffelib` if `import griffe` fails.

* feat(api,ui): in-product demo showcase page (#132) (#133)

* feat(api): add demo slice driving the e2e pipeline via /demo endpoints (#132)

New app/features/demo slice exposing POST /demo/run and WS /demo/stream. It
drives the published API surface in-process via httpx.ASGITransport (no
cross-slice imports, satisfying the vertical-slice rule) and streams one
StepEvent per pipeline step: precheck -> reset -> seed -> status -> features
-> train x3 -> backtest x3 -> register -> verify -> agent -> cleanup.

A module-level asyncio.Lock enforces single-flight; concurrent runs get an
RFC 7807 409. The orchestration is a faithful in-process port of
scripts/run_demo.py (PR #129). Implements PRP-17.

* test(api): cover the demo slice pipeline, routes, and e2e integration (#132)

Unit tests mock the in-process HTTP client to exercise step sequencing,
winner selection, and fail-fast; route tests cover POST /demo/run (200 +
409) and the WS /demo/stream handler. The integration test seeds
demo_minimal and asserts an end-to-end green run against real Postgres.

Implements PRP-17.

* feat(ui): add showcase page streaming the live demo pipeline (#132)

New /showcase route and nav entry. The page opens a one-shot WebSocket to
/demo/stream via a use-demo-pipeline hook (wrapping useWebSocket) and renders
the 11 pipeline steps as live status cards: glyph, detail, duration, the
backtest per-model WAPE breakdown with the winner highlighted, and a
pass/fail summary banner.

Also block-scopes a pre-existing no-case-declarations lint error in
chat.tsx so pnpm lint is green for this PR. Implements PRP-17.

* test(ui): add vitest setup and use-demo-pipeline hook coverage (#132)

Adds the frontend test stack (vitest + jsdom + @testing-library/react), a
test script, and vitest.config.ts. use-demo-pipeline.test.ts covers the
pure event reducer (idle -> running -> pass transitions, summary assembly,
error phase) and a renderHook smoke test.

The package.json pnpm.onlyBuiltDependencies entry is the RUNBOOKS-documented
fix for pnpm 11's esbuild build-script gate. Implements PRP-17.

* docs(docs): document the demo slice and showcase page (#132)

Adds the PRP-17 spec; a 'Try it in the browser' pointer in README; the
/demo/run + /demo/stream rows and a WebSocket Events section in
API_CONTRACTS; a 'Showcase pipeline fails' runbook incident; and
REPO_MAP_INDEX rows for the demo slice and showcase page.

Implements PRP-17.

* chore(repo): back-merge main into dev to absorb v0.2.10 release commits (#136) (#137)

* chore(main): release 0.2.9 (#126)

* feat: release v0.2.10 — demo showcase page + e2e pipeline (#134)

* feat(data): implement MarkdownGenerator age_days trigger via heuristic (#94) (#127)

Resolves #94 via the heuristic path documented in the issue. No schema
column, no Alembic migration, no FIFO cohort tracking — the trigger
self-reads the existing per-(store, product) on_hand_qty series and
fires when inventory has been "unrefreshed" past
`cfg.age_days_threshold`.

Decision rationale (schema column vs. heuristic):
- The schema column path would add `oldest_unit_age_days` to
  `inventory_snapshot_daily`, plus an Alembic migration, plus FIFO
  cohort tracking in `InventorySnapshotGenerator`. No downstream
  consumer reads this column today — adding it for one generator
  trigger violates the "don't design for hypothetical future
  requirements" rule in CLAUDE.md.
- The heuristic path is self-contained in MarkdownGenerator,
  deterministic (preserves the zero-rng-draw regression invariant),
  and additive (no migration, no model change). 354 LOC net, all
  inside one slice.

Heuristic spec:
- A "refresh" is a day where `on_hand_qty` rose by >=
  `_AGE_DAYS_SPIKE_THRESHOLD` (0.3 = 30% jump) vs the prior day.
- Age at day t = days since most recent refresh (or `dates[0]` if no
  refresh has been observed).
- Firing requires age >= `age_days_threshold` AND on_hand >=
  `markdown_min_units_remaining` — never markdown an empty shelf.
- After firing, refresh anchor resets to the day AFTER the markdown
  window ends, so back-to-back fires can't happen and the next age
  clock starts from a "clear shelf" baseline.

Wiring: `MarkdownGenerator.generate()` gains an optional kwarg
`inventory_records: list[dict[str, Any]] | None = None` which `core.py`
passes through from `InventorySnapshotGenerator`. Disabled-path and
non-age_days-path behavior is byte-identical (kwarg ignored).

Tests: +7 new in `TestAgeDaysTrigger`, -1 obsolete
`NotImplementedError` test. Coverage: no-records defensive, threshold
not-met, threshold met, spike resets age, post-fire reset avoids
back-to-back, low-inventory skip, unknown-product skip, rng
non-consumption.

Validation (local):
- ruff check + format: clean
- mypy --strict: 0 issues, 192 files
- pyright --strict: 0 errors
- pytest -m "not integration": 969 passed (+7 vs pre-PR)

Closes #94.

* feat(api,docs): e2e demo pipeline + showcase script (#128) (#129)

* docs(docs): add INITIAL-14 + PRP-15 e2e demo pipeline plan (#128)

Adds the planning documents for the end-to-end demo pipeline work tracked
in #128. Implementation commits follow on this branch.

- INITIAL-14.md: PRD for `make demo` (problem, solution, success metrics,
  open questions resolved in the PRP).
- PRPs/PRP-15-e2e-demo-pipeline.md: full execution plan (16 tasks → 6
  commits, additive only — no schema changes, no API edits).

* feat(data): add demo_minimal scenario preset (#128)

Tiny preset that powers the upcoming `make demo` target. Three stores ×
ten products × 92 days (2024-10-01..2024-12-31) — wide enough to satisfy
an expanding backtest with n_splits=3, horizon=14, min_train_size=30
(needs >= 72 days, 92 leaves margin), small enough to keep the demo
loop comfortable on a laptop.

Mirrors the retail_standard tuning (mild linear trend, noise_sigma=0.10,
modest promotion + stockout probabilities) so backtest WAPE stays
non-NaN across all three baseline models.

- app/shared/seeder/config.py: add DEMO_MINIMAL enum + from_scenario branch
- app/features/seeder/service.py: add ScenarioInfo entry in list_scenarios
- tests cover the new preset and the updated scenario count

* feat(api,docs): scripts/run_demo.py end-to-end pipeline driver (#128)

Single-file async driver that walks the published HTTP surface
(precheck -> reset? -> seed -> status -> features -> train x3 ->
backtest x3 -> register -> verify -> agent -> cleanup). Mirrors the
shape of scripts/seed_random.py and scripts/check_db.py.

- HttpClient: thin httpx.AsyncClient wrapper with explicit 60 s
  timeout (default 5 s is too short for /seeder/generate); surfaces
  RFC 7807 problem+json bodies as a typed StepError that echoes
  title / detail / request_id (never the raw body — secrets-safe).
- DemoContext + StepOutcome dataclasses thread cross-step references.
- Reporter renders the output-formatting.md glyphs (verbose by
  default, --quiet collapses to one line per step).
- Per-step error handling converts httpx + StepError into fail
  outcomes; precheck failure exits 2, any other failure exits 1,
  green exits 0.
- Agent step (10/11) skips with ⏭️ when neither OPENAI_API_KEY nor
  ANTHROPIC_API_KEY is set; reads via app.core.config.get_settings()
  to honor the no-os.environ-in-feature-code rule.
- Registry handshake uses the mandatory pending -> running -> success
  transition and the wire alias "model_config" (not "model_config_data");
  artifact_hash is computed client-side via sha256 since we share the
  FS with the API on this single-host system.
- Winner selection: lowest aggregated WAPE, skipping NaN folds.

Also adds scripts/__init__.py so tests can `import scripts.run_demo`
without invoking the file as a script.

* feat(repo): top-level Makefile with demo / demo-quick / demo-clean (#128)

Wraps scripts/run_demo.py so reviewers can run the full end-to-end
demo with one command. Recipes mirror the three modes the script
supports: full run, skip-seed iteration, destructive reset.

Make targets:
- demo        — docker compose up -d + alembic + run_demo
- demo-quick  — run_demo --skip-seed (no compose/migration touch)
- demo-clean  — full reset (--reset) before seeding
- help        — default goal; lists targets + preconditions

Tab-indented recipes and .PHONY declarations per make conventions.
Preconditions (Postgres on :5433, uvicorn on :8123) documented in
the help block; the script itself enforces them via the precheck
step and exits 2 on failure.

* test(api): unit + integration coverage for run_demo (#128)

Unit (`tests/test_run_demo_unit.py`, 32 cases):
- argparse defaults + all-flags variants
- DemoContext defaults (no leaking state across runs)
- _select_winner: lowest-WAPE, NaN-skip, all-NaN -> None, empty -> None
- _model_config_payload: discriminated-union shape per baseline; rejects
  unsupported model_type (defends the "no lightgbm in PRP-15" boundary)
- Reporter: glyph mapping; verbose + quiet output; summary green / failure
  / over-budget soft-warn branches
- StepError formats RFC 7807 (title/detail/request_id) without leaking
  the raw response body
- HttpClient (mocked httpx.AsyncClient): 2xx, 204, non-2xx -> StepError
- Step payload sanity: seed sends demo_minimal+correct dims+ISO dates;
  features sends cutoff_date as ISO; train fires three model_types in
  parallel; agent step skips with ⏭️ when no LLM key

Integration (`tests/test_e2e_demo.py`, @pytest.mark.integration):
- Skips if Postgres on :5433 isn't reachable
- Boots uvicorn on :8124 as a subprocess (avoids the dev :8123 default)
- Runs scripts/run_demo.py --reset against it; asserts exit 0 +
  canonical "runs=3 winner=... alias=demo-production" summary
- Second case asserts a bogus URL exits 2 (no silent success)
- Cleans up uvicorn on teardown with terminate/kill fallback
- Resolves `uv` via shutil.which to keep ruff S607 happy and avoid
  PATH-dependent exec at test time

* ci(repo): nightly e2e demo workflow (#128)

Adds .github/workflows/e2e-nightly.yml — runs scripts/run_demo.py
against a fresh Postgres+pgvector service every night at 07:00 UTC
(plus on-demand via workflow_dispatch). Catches regressions in the
documented end-to-end pipeline before they bleed into the per-PR
gate.

Per PRP-15 + INITIAL-14 risk note: this workflow is intentionally
NOT a required status check on dev or main. Flake-budget lives in
the nightly slot, not in ci.yml.

- pgvector/pgvector:pg16 service container (same as ci.yml `test` job)
- uvicorn started in background; /health polled with a 30 s deadline
- run_demo.py called with --seed 42 (deterministic)
- LLM-key env vars intentionally absent — agent step auto-skips via
  ⏭️, keeping the workflow self-contained
- uvicorn logs uploaded as artifact on failure (7-day retention) so
  postmortems can read what the API was doing when the script broke
- astral-sh/setup-uv pinned by 40-char SHA per security-patterns.md
- permissions: contents: read (least-privilege)

* docs(docs): cross-link make demo from README + RUNBOOKS + REPO_MAP_INDEX (#128)

Discoverability layer for PRP-15.

- README.md: new 'Try it: end-to-end demo' step right after the curl
  /health verification; shows the canonical final-line summary so
  reviewers know what green looks like.
- docs/DAILY-FLOW.md: new 'First-Run Smoke (Demo Pipeline)' section
  documenting all three Make targets.
- docs/_base/RUNBOOKS.md: new 'make demo fails at step X' Common
  Incidents entry with a 7-point diagnosis flow keyed to the script's
  step names + a postmortem-capture recipe.
- docs/_base/REPO_MAP_INDEX.md: Makefile and scripts/run_demo.py rows
  added to the Document Index table.

Pure additive; no existing content removed or renamed.

* fix(data): update /seeder/scenarios route test for demo_minimal preset (#128)

Companion to feat(data): add demo_minimal scenario preset — the
route-level assertion in TestListScenarios.test_returns_scenarios still
expected 6 scenarios; bumping to 7 and adding the demo_minimal name
membership check to match the service-layer + config-layer tests
already updated in 005c189.

* fix(api): harden run_demo for integration test + real DB (#128)

Three real failures surfaced when first running the integration test
against docker-compose Postgres + a freshly booted uvicorn; all three
are now closed:

scripts/run_demo.py:
1. step_status: discover the real (store_id, product_id) from
   /dimensions/stores + /dimensions/products instead of hardcoding 1.
   Postgres auto-increment does NOT reset after delete, so the freshly
   seeded IDs are NOT 1 (they were ~150-260 on this branch after a few
   delete/seed cycles).
2. step_register: copy the trained-model artifact into the registry's
   own root (settings.registry_artifact_root) and record a registry-
   relative URI. The registry verify endpoint resolves artifact_uri
   against its own root, which is separate from where /forecasting/train
   writes (settings.forecast_model_artifacts_dir). Pre-fix, verify
   returned 404 even though the artifact existed on disk.
3. step_agent: skip with the soft-skip glyph on any LLM provider failure
   (invalid key, model unavailable, 5xx), and make _llm_key_present
   provider-aware so it matches the right env var to the configured
   agent_default_model. Pre-fix, an .env with anthropic/openai keys but
   a Gemini default model failed hard at chat-time.
4. Bumped DEFAULT_TIMEOUT_S from 60 to 120 because /seeder/generate
   for demo_minimal can spend 60-90 s on slower laptops once you
   include inventory + prices + promotions inserts.
5. step_seed detail string: GenerateResult.records_created uses 'sales'
   (singular), not 'sales_daily'; cosmetic fix.

tests/test_e2e_demo.py:
- Redirect uvicorn stdout to a temp file rather than subprocess.PIPE.
  The seeder + structlog produce enough INFO log volume to fill a
  64-KB pipe buffer; once full, uvicorn blocks on write and seeder
  requests hang for the full --timeout. Verified locally: integration
  suite now passes in ~6.5 s instead of timing out at 120 s.
- Cleanup leaves the log file on disk only when the test failed
  (postmortem-friendly).

tests/test_run_demo_unit.py:
- Bump test_defaults timeout expectation to match the new 120 s
  default.

End-to-end manual run on this machine: 11 steps, wall_clock=2 s,
exit 0. Integration test: 2 passed in 6.48 s.

* chore(repo): bump authlib + fastmcp to clear Socket-flagged CVEs (#130) (#131)

Headline:
- authlib  1.6.6  -> 1.7.2  (clears GHSA-wvwj-cvrp-7pv5 — JWS signature
  verification bypass; patched at >= 1.6.9)
- fastmcp  2.14.4 -> 3.2.4  (clears GHSA-vv7q-7jx5-f767 — OpenAPI
  Provider SSRF + path traversal; patched at >= 3.2.0)

Both CVEs were flagged on PR #129 by Socket Security and are
pre-existing on dev (not introduced by #128).

Wider scope — read before merging:
`uv lock --upgrade-package authlib --upgrade-package fastmcp` triggers
a full re-resolve of the dependency graph. Because dev's uv.lock had
drifted from pyproject.toml (the project's constraint envelope had
loosened over time), this single command also brings the lockfile in
sync with current pyproject.toml. Net diff: 243 insertions / 369
deletions on uv.lock; no other files touched.

Transitive cascades worth flagging:
- anthropic    0.77.0 -> 0.102.0 (pydantic-ai-slim extra)
- pydantic-graph 1.51.0 -> 1.96.0
- temporalio   1.20.0 -> 1.27.2
- alembic      1.18.1 -> 1.18.4
- aws-* and cohere transitives bumped along
- griffe 1.15.0 dropped in favor of griffelib 2.0.2 (fastmcp 3.x switched)
- Removed: cloudpickle, diskcache, fakeredis, invoke, lupa, prometheus
  exporter, pydocket, redis, rsa, sortedcontainers — these were
  transitives of fastmcp 2.x that fastmcp 3.x no longer pulls in.

Verification on this host:
- uv sync --extra dev  -> green
- ruff check .         -> clean
- mypy --strict app/   -> 192 files clean
- pyright app/         -> 0 errors (50 warnings, pre-existing)
- pytest -m 'not integration' -> 969 passed

Known install quirk: griffelib 2.0.2 ships a top-level `griffe/`
package whose RECORD files don't always materialize on first install
when uv replaces an older `griffe` dist in the same sync. A clean
venv install (which CI does via `uv sync --frozen`) is unaffected;
local devs who upgrade in place may need a one-shot
`uv pip install --force-reinstall griffelib` if `import griffe` fails.

* feat(api,ui): in-product demo showcase page (#132) (#133)

* feat(api): add demo slice driving the e2e pipeline via /demo endpoints (#132)

New app/features/demo slice exposing POST /demo/run and WS /demo/stream. It
drives the published API surface in-process via httpx.ASGITransport (no
cross-slice imports, satisfying the vertical-slice rule) and streams one
StepEvent per pipeline step: precheck -> reset -> seed -> status -> features
-> train x3 -> backtest x3 -> register -> verify -> agent -> cleanup.

A module-level asyncio.Lock enforces single-flight; concurrent runs get an
RFC 7807 409. The orchestration is a faithful in-process port of
scripts/run_demo.py (PR #129). Implements PRP-17.

* test(api): cover the demo slice pipeline, routes, and e2e integration (#132)

Unit tests mock the in-process HTTP client to exercise step sequencing,
winner selection, and fail-fast; route tests cover POST /demo/run (200 +
409) and the WS /demo/stream handler. The integration test seeds
demo_minimal and asserts an end-to-end green run against real Postgres.

Implements PRP-17.

* feat(ui): add showcase page streaming the live demo pipeline (#132)

New /showcase route and nav entry. The page opens a one-shot WebSocket to
/demo/stream via a use-demo-pipeline hook (wrapping useWebSocket) and renders
the 11 pipeline steps as live status cards: glyph, detail, duration, the
backtest per-model WAPE breakdown with the winner highlighted, and a
pass/fail summary banner.

Also block-scopes a pre-existing no-case-declarations lint error in
chat.tsx so pnpm lint is green for this PR. Implements PRP-17.

* test(ui): add vitest setup and use-demo-pipeline hook coverage (#132)

Adds the frontend test stack (vitest + jsdom + @testing-library/react), a
test script, and vitest.config.ts. use-demo-pipeline.test.ts covers the
pure event reducer (idle -> running -> pass transitions, summary assembly,
error phase) and a renderHook smoke test.

The package.json pnpm.onlyBuiltDependencies entry is the RUNBOOKS-documented
fix for pnpm 11's esbuild build-script gate. Implements PRP-17.

* docs(docs): document the demo slice and showcase page (#132)

Adds the PRP-17 spec; a 'Try it in the browser' pointer in README; the
/demo/run + /demo/stream rows and a WebSocket Events section in
API_CONTRACTS; a 'Showcase pipeline fails' runbook incident; and
REPO_MAP_INDEX rows for the demo slice and showcase page.

Implements PRP-17.

* chore(main): release 0.2.10 (#135)

* docs(docs): fix broken PRP-0/INITIAL-0 relative links in phase 0 doc (#138) (#139)

* docs(repo): fix readme dev-deps command and stale .github template placeholders (#140) (#141)

* docs(docs): fill DEV_GUIDE.md onboarding stub sections (#142) (#143)

* docs(repo): refresh stale CLAUDE.md note, document /demo API, align PR template (#144) (#145)

* fix(ui): chart series render black — drop hsl() wrapper on oklch chart vars (#149) (#153)

index.css defines --chart-N twice: legacy shadcn-v3 HSL triplets and
Tailwind-4 / shadcn-v4 complete oklch() colours. The oklch definitions win
the cascade, so at runtime --chart-N is a full colour. The chart components
still wrapped it as hsl(var(--chart-N)) → hsl(oklch(...)), which is invalid
CSS, so recharts fell back to a black fill/stroke — invisible on the dark
theme.

Reference var(--chart-N) directly in backtest-folds-chart.tsx and
time-series-chart.tsx. Verified in a browser: the backtest per-fold bars
and the forecast line now render in colour.

* fix(jobs): backtest job result keeps fold metrics, stability and baselines (#148) (#152)

* fix(jobs): backtest job result keeps fold metrics, stability and baselines (#148)

_execute_backtest ran BacktestingService.run_backtest — which computes
per-fold metrics, stability indices and a naive/seasonal baseline comparison
— but stored only four aggregated values and discarded the rest. The
dashboard (/visualize/backtest) reads aggregated_metrics.{*_mean,
stability_index}, fold_metrics[] and baseline_comparison, so it showed
"0 folds", all-zero metrics and an empty chart.

Add _shape_backtest_result(), which flattens a BacktestResponse into the
contract the dashboard expects, and _finite(), which coerces NaN/inf to 0.0
so the result stays JSONB-safe (stability is NaN with fewer than two folds).

Add app/features/jobs/tests/test_service.py with unit coverage for the
shaping logic: fold metrics, *_mean keys, stability, baseline comparison,
the no-baselines path, and NaN coercion.

* refactor(jobs): centralize backtest metric keys and surface drift (#148)

Addresses review feedback on PR #152.

- Hoist the dashboard's metric set into _BACKTEST_METRICS and the headline
  stability metric into _STABILITY_METRIC, so the hardcoded keys live in one
  documented place instead of being repeated across the shaping logic.
- Log jobs.backtest_metrics_missing when an expected metric is absent from the
  backtest response, so a future rename in the backtesting service fails loud
  instead of silently emitting 0.0.
- Document the WAPE stability convention in the _shape_backtest_result docstring.
- Tests: assert backtest_id / model_type / duration_ms pass through unchanged,
  and add a regression test for the missing-metric default path.

* fix(ui): forecast page reads forecasts/forecast from predict job result (#147) (#151)

The /visualize/forecast page never rendered the chart for a valid completed
predict job. It read job.result.predictions with field `predicted`, but
POST /jobs (job_type="predict") returns job.result.forecasts with field
`forecast`. forecastData was therefore always undefined and the page fell
through to "No prediction data available in job result".

Read result.forecasts with field `forecast`, and pass predictedKey="forecast"
to TimeSeriesChart (which already supports a configurable data key).

Verified in a browser: entering a completed predict job ID now renders the
14-day forecast line chart with correct tooltip values.

* fix(registry): tolerate multiple matches in _find_duplicate (#146) (#150)

Under the default registry_duplicate_policy="detect", duplicate runs are
created intentionally, so multiple non-archived model_run rows can share one
config hash. _find_duplicate used scalar_one_or_none(), which raised
MultipleResultsFound once two duplicates existed — POST /registry/runs then
returned HTTP 500. This made the demo/Showcase register step fail
deterministically on any DB with repeated runs.

Order the lookup by created_at desc, LIMIT 1, and use scalars().first() so it
returns the most recent matching run instead of asserting a single match.

Add an integration regression test that POSTs an identical run three times
under the detect policy and asserts all three return 201.

* fix(ui): derive TimeSeriesChart line stroke from the config key (#156) (#157)

TimeSeriesChart builds chartConfig with dynamic keys ([actualKey] /
[predictedKey]), so shadcn's ChartContainer injects --color-<key> CSS
variables. The <Line> elements, however, hardcoded stroke="var(--color-actual)"
and stroke="var(--color-predicted)". The forecast page passes
predictedKey="forecast", so the injected variable is --color-forecast;
var(--color-predicted) was undefined, the stroke was invalid, and SVG fell
back to its initial value `none` — the forecast line was invisible.

Build the stroke from the key: stroke={`var(--color-${actualKey})`} /
stroke={`var(--color-${predictedKey})`}.

Verified in a browser: the forecast line now renders in colour.

* feat(ui): job picker dropdown on forecast and backtest pages (#154) (#155)

The visualization pages only accepted a job ID typed into a text box, so
users had to already know the ID. Add a JobPicker component: a dropdown of
completed jobs of the relevant type (predict / backtest), newest first, with
each option labelled by short id, model and timestamp.

- New shared component src/components/common/job-picker.tsx, used by both
  forecast.tsx and backtest.tsx.
- The manual job-ID input stays alongside the dropdown for pasting an ID.
- The most recent completed job auto-loads on mount so a chart shows
  immediately without interaction.

No backend change — GET /jobs?job_type=&status=completed already exists.
Verified in a browser on both pages.

* chore(main): release 0.2.11 (#159)

* feat(api,ui): add AI model admin console with Ollama support (#162) (#163)

* feat(api,ui): add AI model admin console with Ollama support (#162)

* fix(db): register AppConfig model in alembic env for schema-drift check (#162)

* fix(agents): handle model tool-retry crash gracefully (#164) (#165)

A casual message to the Experiment agent could crash the WebSocket
stream with a raw 'Tool ... exceeded max retries count of 1' error
when the model produced an invalid tool call.

- Catch PydanticAI's UnexpectedModelBehavior in stream_chat and chat;
  surface a clean, recoverable error event / message instead of
  leaking the internal exception string.
- Make tool_compare_backtest_results tolerant of missing/empty args
  (return a self-correcting hint) so a malformed call no longer burns
  the retry budget and crashes the run.
- Add a conversational-fallback line to the experiment system prompt
  so greetings are answered without invoking workflow tools.
- Add regression tests for both the chat and stream-chat paths.

* fix(agents): round-trip agent message history through pydantic-ai type adapter (#166) (#167)

* fix(agents): round-trip agent message history through pydantic-ai type adapter (#166)

Multi-turn agent chat crashed with a dict-has-no-attribute-conversation_id
error: _deserialize_messages returned the raw stored dicts unchanged, but
PydanticAI 1.96 requires real ModelMessage objects (it accesses
msg.conversation_id on every history item).

- _serialize_messages now uses ModelMessagesTypeAdapter.dump_python
  (mode=json), so stored history can be round-tripped.
- _deserialize_messages uses ModelMessagesTypeAdapter.validate_python,
  degrading to an empty history (with a warning) when stored data
  predates this format instead of crashing the run.
- Replace the serialization tests with a real round-trip test and a
  legacy-format fallback test.

* fix(agents): broaden deserialize-failure handling and log session id (#166)

Address code-review feedback on the message-history round-trip fix:

- _deserialize_messages now catches any Exception, not only
  ValidationError, so a malformed stored record (wrong shape, type
  errors) can never crash an otherwise-valid agent run.
- The warning logs exc_info (full type, message, traceback) instead of
  just str(e), and includes session_id so a failure can be correlated
  with the specific stored record.
- Add a regression test that a non-ValidationError adapter failure also
  degrades to an empty history.

* fix(agents): apply configured agent_retry_attempts to the agents (#170) (#171)

Settings.agent_retry_attempts (default 3, set in .env) was never passed
to the PydanticAI Agent constructor, so both agents silently used the
framework default of 1. Agent runs failed with "Exceeded maximum output
retries (1)" — a weaker model got only one attempt to emit a valid
structured ExperimentReport / RAGAnswer.

- Add get_agent_retries() helper in agents/base.py.
- Pass output_retries and tool_retries to the experiment and
  rag_assistant Agent constructors (PydanticAI 1.96 deprecated the
  combined retries kwarg in favour of the two explicit ones).
- Add tests asserting both agents are built with the configured budget.

* fix(agents): complete tool-using runs — sequential session use + PromptedOutput (#172, #173) (#174)

* fix(agents): run agent tool calls sequentially over the shared session (#172)

When the model emitted multiple DB-touching tool calls in one turn,
PydanticAI executed them concurrently. Every agent tool shares the
single AgentDeps.db AsyncSession, and SQLAlchemy forbids concurrent
operations on one session, so the run failed intermittently with
"InvalidRequestError: concurrent operations are not permitted".

- Wrap agent.run() (chat) and agent.run_stream() (stream_chat) in
  Agent.parallel_tool_call_execution_mode("sequential").
- Add a regression test asserting chat() runs under sequential mode.

* fix(agents): use PromptedOutput so weaker models can produce structured output (#173)

Both agents declared output_type as a plain model, which PydanticAI
serves via its default ToolOutput mode (the model must call a hidden
final_result tool). Weaker/local models answer in plain prose instead,
PydanticAI rejects it as json_invalid, and the run fails with
"Exceeded maximum output retries".

- Wrap the experiment and rag_assistant output_type in PromptedOutput,
  which places the JSON schema in the prompt and parses the model's
  text reply. Works for local and cloud models alike.
- Add tests asserting both agents build with a PromptedOutputSchema.

* refactor(agents): centralize sequential-tool-execution policy and harden agent tests (#173)

Addresses code-review feedback on PR #174:

- Extract the duplicated Agent.parallel_tool_call_execution_mode("sequential")
  wrapping from chat() and stream_chat() into a _sequential_tool_execution()
  helper, so the issue-#172 execution-mode policy lives in one place.
- Replace test reliance on private internals. test_base.py no longer asserts
  agent._output_schema's class-name string; it now verifies PromptedOutput
  behaviorally via the public FunctionModel test double (no final_result
  output tool registered, plain-text JSON reply parsed into the schema).
- test_service.py drops the private _parallel_execution_mode_ctx_var import
  and asserts the public Agent.parallel_tool_call_execution_mode API instead.
- Add test_stream_chat_runs_tools_sequentially mirroring the chat() test so
  the streaming path is covered against issue #172 regressions.

* fix(agents): correct prompt tool names and recover from tool errors (#175) (#177)

Two coupled robustness fixes for the agent layer, both surfaced by a
capture_run_messages diagnostic. The changes share base.py and
experiment.py, so they land in one commit.

#175 — the experiment prompt named tools as run_backtest / list_runs /
compare_backtest_results, but the registered tools are tool_-prefixed
(tool_run_backtest, ...). Weaker models trusted the prompt and called
unknown tool names. TOOL_USAGE_INSTRUCTIONS and the EXPERIMENT_SYSTEM_PROMPT
workflow now use the exact registered names.

#176 — a tool raising a plain exception aborted the whole run (observed:
ValueError "No data found for store=..."). New recoverable() decorator
wraps every async DB-touching tool so an expected ValueError becomes a
ModelRetry the model can correct from; other exceptions still propagate.

- Add recoverable() to agents/base.py; decorate the 6 experiment tools
  and the 2 rag_assistant tools (tool_plain pure tools left alone).
- Tests: prompt names use tool_* ; recoverable converts ValueError to
  ModelRetry, passes other exceptions through, is transparent on success.

* fix(data): anchor seeded data window to the current date (#181) (#182)

* fix(agents): wire FallbackModel so a primary 503 retries the fallback (#183) (#184)

* fix(agents): wire FallbackModel so a primary 503 retries the fallback (#183)

* test(agents): assert FallbackModel wiring order and primary fail-fast (#183)

* feat(ui): Knowledge page + Agent Guide page (PRP-19) (#186)

* feat(api): expose agent session limits on GET /config/ai (#185)

* feat(ui): add knowledge and agent guide pages with nav (#185)

* test(ui): cover knowledge-utils pure helpers (#185)

* docs(docs): document the knowledge and agent guide pages (#185)

* feat(ui): Explorer interactivity — detail views, richer tables, Sales charts, cross-filtering (PRP-20) (#188)

* feat(analytics): add GET /analytics/timeseries aggregated sales endpoint (#187)

* feat(dimensions): add sort_by/sort_order to store and product listings (#187)

* feat(ui): add explorer detail pages, sortable tables, and sales charts (#187)

* test(ui): cover the csv-export pure helper (#187)

* docs(docs): document the explorer interactivity extension (#187)

* feat(ui): Explorer interactivity — Model Runs & Jobs detail views, comparison, verify, sorting (PRP-21) (#190)

* feat(registry): add sort_by/sort_order to model-run listing (#189)

* feat(jobs): add sort_by/sort_order to job listing (#189)

* test(registry,jobs): cover list-endpoint sorting (#189)

* feat(ui): add run/job detail and run-comparison pages (#189)

* feat(ui): make Runs and Jobs tables interactive (#189)

* docs(docs): document explorer runs/jobs interactivity (#189)
---
 .../PRP-19-knowledge-and-agent-guide-pages.md |  952 +++++++++++++++
 PRPs/PRP-20-explorer-interactivity.md         | 1002 ++++++++++++++++
 ...PRP-21-explorer-runs-jobs-interactivity.md | 1022 +++++++++++++++++
 README.md                                     |    5 +
 app/features/agents/agents/base.py            |   51 +
 app/features/agents/agents/experiment.py      |   10 +-
 app/features/agents/agents/rag_assistant.py   |   10 +-
 app/features/agents/tests/test_base.py        |   62 +
 app/features/analytics/routes.py              |   95 ++
 app/features/analytics/schemas.py             |   63 +
 app/features/analytics/service.py             |  106 +-
 app/features/analytics/tests/conftest.py      |  156 ++-
 .../tests/test_routes_integration.py          |  180 +++
 app/features/analytics/tests/test_schemas.py  |   77 ++
 app/features/config/schemas.py                |    7 +
 app/features/config/service.py                |    5 +
 app/features/config/tests/test_routes.py      |   21 +
 app/features/config/tests/test_schemas.py     |   32 +
 app/features/config/tests/test_service.py     |   18 +
 app/features/demo/pipeline.py                 |   14 +-
 app/features/dimensions/routes.py             |   28 +
 app/features/dimensions/service.py            |   52 +-
 app/features/dimensions/tests/conftest.py     |  151 +++
 app/features/dimensions/tests/test_sort.py    |  156 +++
 app/features/jobs/routes.py                   |   16 +
 app/features/jobs/service.py                  |   28 +-
 app/features/jobs/tests/conftest.py           |  108 +-
 app/features/jobs/tests/test_routes.py        |  115 ++
 app/features/registry/routes.py               |   15 +
 app/features/registry/service.py              |   29 +-
 app/features/registry/tests/test_routes.py    |   91 ++
 app/features/seeder/schemas.py                |   10 +-
 app/features/seeder/service.py                |   36 +-
 app/features/seeder/tests/test_service.py     |   13 +-
 app/shared/seeder/config.py                   |   45 +-
 app/shared/seeder/tests/test_config.py        |   26 +-
 app/shared/seeder/tests/test_core.py          |   13 +-
 docs/_base/API_CONTRACTS.md                   |    9 +-
 docs/_base/REPO_MAP_INDEX.md                  |    7 +
 frontend/src/App.tsx                          |   63 +
 frontend/src/components/charts/index.ts       |    1 +
 .../components/charts/revenue-bar-chart.tsx   |   56 +
 frontend/src/components/common/index.ts       |    1 +
 frontend/src/components/common/json-block.tsx |   28 +
 .../data-table/data-table-column-header.tsx   |   41 +
 .../data-table/data-table-view-options.tsx    |   45 +
 .../src/components/data-table/data-table.tsx  |   21 +
 frontend/src/components/data-table/index.ts   |    2 +
 frontend/src/hooks/index.ts                   |    2 +
 frontend/src/hooks/use-jobs.ts                |    8 +-
 frontend/src/hooks/use-lifecycle-curve.ts     |   27 +
 frontend/src/hooks/use-products.ts            |    8 +-
 frontend/src/hooks/use-rag-sources.ts         |   18 +-
 frontend/src/hooks/use-runs.ts                |   35 +-
 frontend/src/hooks/use-stores.ts              |    8 +-
 frontend/src/hooks/use-timeseries.ts          |   41 +
 frontend/src/lib/constants.ts                 |   13 +
 frontend/src/lib/csv-export.test.ts           |   56 +
 frontend/src/lib/csv-export.ts                |   41 +
 frontend/src/lib/knowledge-utils.test.ts      |   91 ++
 frontend/src/lib/knowledge-utils.ts           |   43 +
 frontend/src/pages/chat.tsx                   |   12 +-
 frontend/src/pages/explorer/job-detail.tsx    |  208 ++++
 frontend/src/pages/explorer/jobs.tsx          |  212 ++--
 .../src/pages/explorer/product-detail.tsx     |  215 ++++
 frontend/src/pages/explorer/products.tsx      |  155 ++-
 frontend/src/pages/explorer/run-compare.tsx   |  271 +++++
 frontend/src/pages/explorer/run-detail.tsx    |  272 +++++
 frontend/src/pages/explorer/runs.tsx          |  185 ++-
 frontend/src/pages/explorer/sales.tsx         |  157 ++-
 frontend/src/pages/explorer/store-detail.tsx  |  200 ++++
 frontend/src/pages/explorer/stores.tsx        |  178 ++-
 frontend/src/pages/guide.tsx                  |  362 ++++++
 frontend/src/pages/knowledge.tsx              |  344 ++++++
 frontend/src/types/api.ts                     |   85 ++
 scripts/run_demo.py                           |   14 +-
 scripts/seed_random.py                        |   16 +-
 tests/test_demo_showcase_integration.py       |   11 +-
 tests/test_run_demo_unit.py                   |   14 +-
 79 files changed, 8051 insertions(+), 345 deletions(-)
 create mode 100644 PRPs/PRP-19-knowledge-and-agent-guide-pages.md
 create mode 100644 PRPs/PRP-20-explorer-interactivity.md
 create mode 100644 PRPs/PRP-21-explorer-runs-jobs-interactivity.md
 create mode 100644 app/features/analytics/tests/test_routes_integration.py
 create mode 100644 app/features/analytics/tests/test_schemas.py
 create mode 100644 app/features/dimensions/tests/test_sort.py
 create mode 100644 app/features/jobs/tests/test_routes.py
 create mode 100644 frontend/src/components/charts/revenue-bar-chart.tsx
 create mode 100644 frontend/src/components/common/json-block.tsx
 create mode 100644 frontend/src/components/data-table/data-table-column-header.tsx
 create mode 100644 frontend/src/components/data-table/data-table-view-options.tsx
 create mode 100644 frontend/src/hooks/use-lifecycle-curve.ts
 create mode 100644 frontend/src/hooks/use-timeseries.ts
 create mode 100644 frontend/src/lib/csv-export.test.ts
 create mode 100644 frontend/src/lib/csv-export.ts
 create mode 100644 frontend/src/lib/knowledge-utils.test.ts
 create mode 100644 frontend/src/lib/knowledge-utils.ts
 create mode 100644 frontend/src/pages/explorer/job-detail.tsx
 create mode 100644 frontend/src/pages/explorer/product-detail.tsx
 create mode 100644 frontend/src/pages/explorer/run-compare.tsx
 create mode 100644 frontend/src/pages/explorer/run-detail.tsx
 create mode 100644 frontend/src/pages/explorer/store-detail.tsx
 create mode 100644 frontend/src/pages/guide.tsx
 create mode 100644 frontend/src/pages/knowledge.tsx

diff --git a/PRPs/PRP-19-knowledge-and-agent-guide-pages.md b/PRPs/PRP-19-knowledge-and-agent-guide-pages.md
new file mode 100644
index 00000000..2991a0df
--- /dev/null
+++ b/PRPs/PRP-19-knowledge-and-agent-guide-pages.md
@@ -0,0 +1,952 @@
+name: "PRP-19 — Knowledge page + Agent Guide page (in-product self-documentation)"
+description: |
+  Add two new React pages to the ForecastLabAI dashboard, frontend-led and
+  fully additive:
+
+  1. **Knowledge** (`/knowledge`) — presents, in detail, *what ForecastLabAI
+     currently knows*: the RAG knowledge base (indexed sources + a live semantic
+     search box) plus a summary of the live system state the agents can query
+     (seeded data, registered model runs, deployment aliases).
+  2. **Agent Guide** (`/guide`) — explains, in detail, *how to use the Chat
+     agents*: the two agent types, their tools, the human-in-the-loop approval
+     flow, session limits, the streaming protocol, and copy-paste example prompts.
+
+  Frontend-led, with one small additive backend change: the existing
+  `GET /config/ai` response gains read-only agent-limit fields so the Guide
+  shows session limits live. No new backend slice, no migration, no new env var.
+  Every other endpoint these pages consume already exists with a frontend hook.
+
+## Purpose
+Close the in-product self-documentation gap. Today a dashboard visitor can open
+`/chat` and talk to an agent, but nothing in the UI tells them (a) what the
+RAG assistant actually has indexed to answer from, or (b) how the agents work,
+what they can do, or how the approval gate behaves. The two pages turn implicit
+system knowledge into a visible, browsable surface — a natural onboarding pair:
+**Knowledge** = "what it knows" → **Agent Guide** = "how to ask it".
+
+> **PRP numbering:** `PRP-16` is reserved (Phase-2 LightGBM, per PRP-15).
+> `PRP-17` (Showcase) and `PRP-18` (AI Model console) are used. This is `PRP-19`.
+
+## Core Principles
+1. **Context is King** — every endpoint shape, hook name, schema field, and
+   pattern referenced below is linked to a real source file + line.
+2. **Reuse existing patterns** — both pages are lazy routes registered exactly
+   like `Showcase` (PRP-17); data comes through existing TanStack Query hooks
+   (`useRagSources`, `useSeederStatus`, `useAIConfig`, …); UI uses existing
+   shadcn primitives (`Card`, `Badge`, `Input`, `Tabs`, `Button`). No new
+   streaming primitive, no new fetch wrapper.
+3. **Additive only** — no new backend slice, no Alembic migration, no new
+   `.env` var. The one backend change is additive: read-only agent-limit fields
+   appended to the existing `AIModelConfig` (`GET /config/ai`) response. Plus
+   one new hook (`useRetrieve`), three new TS interfaces, two new pages, one
+   pure-helper module.
+4. **Read-only, no duplication** — the Knowledge page is *presentational*. It
+   does NOT duplicate Admin's RAG management (index / delete) — those stay in
+   `frontend/src/pages/admin.tsx`. It adds the semantic-search exploration that
+   Admin lacks.
+5. **Strict gates honored** — `pnpm tsc --noEmit` + `pnpm lint` + `pnpm test`
+   green; AND because the `config` slice `.py` files change, the repo-wide
+   `ruff`/`mypy`/`pyright`/`pytest` CI jobs must be run and stay green — the
+   `/config/ai` change ships with `config` slice tests.
+6. **UI through skills** — pages built via `frontend-design` + `shadcn-ui` and
+   dogfooded via `webapp-testing` / `agent-browser` per `.claude/rules/ui-design.md`.
+   A green type-check is NOT proof the UI works.
+
+---
+
+## Goal
+Two new nav items route to two new pages.
+
+**`/knowledge` — Knowledge**
+- A **Knowledge Base** section: `total_sources` / `total_chunks` summary, a
+  read-only list of every indexed RAG source (path, type badge, chunk count,
+  indexed date), and a **semantic search box** that POSTs to `/rag/retrieve`
+  and renders the matching chunks with relevance scores + source citations.
+- A **Live System State** section: the seeded-data summary (stores / products /
+  sales / date range), the count of registered model runs, and the deployment
+  aliases — i.e. what the *experiment* agent can query through its tools.
+- A short explainer tying it together: "the RAG assistant answers from the
+  Knowledge Base; the experiment agent acts on the Live System State."
+
+**`/guide` — Agent Guide**
+- Describes the **two agents** (`rag_assistant`, `experiment`), each with its
+  purpose, its exact tool names, and what it returns.
+- Walks through **how a chat session works**: pick agent → Start Session →
+  send a message → streamed text + tool-call chips → approval prompts →
+  New Session.
+- Explains the **human-in-the-loop approval gate** (`create_alias`,
+  `archive_run`).
+- Lists **session limits** (token budget, tool-call cap, timeout, TTL, retries)
+  — rendered **live** from `/config/ai`, which is extended to return them.
+- Gives **copy-paste example prompts** per agent.
+- Surfaces the **currently configured agent model** (live, from `/config/ai`)
+  and links to Chat and Admin → AI Models.
+- Reachable both from a flat top-level nav item AND from a help link on the
+  Chat page.
+
+## Why
+- **Portfolio identity.** `.claude/rules/product-vision.md` principle 1 —
+  "portfolio-grade, end-to-end … every phase ships working code". The agentic
+  layer (PRP-10) and RAG layer (PRP-9) are fully built but invisible as
+  *capabilities* — a reviewer has to read code to learn what the agents do.
+- **Onboarding.** A first-time user opening `/chat` has no idea what to ask the
+  RAG assistant (it can only answer from indexed docs) or that the experiment
+  agent can run real backtests. These two pages remove that guesswork.
+- **Low-cost surface.** Almost everything needed already exists server-side;
+  the only backend work is a small additive `/config/ai` extension. This is
+  high-value-per-line work: mostly composition of shipped endpoints into two
+  polished pages.
+
+## What
+Frontend-led. Two lazy-loaded pages mirroring the `Showcase` registration
+(PRP-17), two new `ROUTES` entries, two `NAV_ITEMS` entries, a help link to
+`/guide` on the Chat page, one new mutation hook (`useRetrieve` for
+`POST /rag/retrieve`), three new TS interfaces, and one pure-helper module with
+a vitest. Plus one additive backend change: the `config` slice's `AIModelConfig`
+schema + `get_effective_config` service gain read-only agent-limit fields
+(`agent_max_tool_calls`, `agent_timeout_seconds`, `agent_retry_attempts`,
+`agent_session_ttl_minutes`, `agent_require_approval`) so the Guide's limits are
+live; shipped with `config` slice tests. No migration, no new env var.
+
+### Success Criteria
+- [ ] `GET /knowledge` in the running SPA renders the Knowledge Base section
+      (source list + summary) and the Live System State section.
+- [ ] The semantic search box on `/knowledge` POSTs `/rag/retrieve` and renders
+      `ChunkResult`s with a relevance score; an empty query is rejected client-side;
+      a `502` (no embedding provider) shows a graceful "search unavailable" state
+      while the source list still renders.
+- [ ] An empty knowledge base shows a friendly empty state pointing at
+      Admin → RAG Sources (not a crash, not a blank card).
+- [ ] `GET /guide` renders both agent cards with the **exact** tool names from
+      the agent definitions, the approval-gate explainer, the example prompts,
+      and the session limits + agent model rendered **live** from `/config/ai`.
+- [ ] Both pages appear in the top nav (desktop + mobile sheet) and in `App.tsx`
+      as lazy `<Route>`s wrapped in `<Suspense>`; the Chat page links to `/guide`.
+- [ ] `cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run` all clean.
+- [ ] `frontend/src/lib/knowledge-utils.test.ts` passes (pure-helper coverage).
+- [ ] `GET /config/ai` returns the five additive agent-limit fields; the `config`
+      slice tests (`test_schemas.py`/`test_service.py`/`test_routes.py`) cover
+      them and `ruff`/`mypy`/`pyright`/`pytest` stay green.
+- [ ] Only the `config` slice changes server-side; no Alembic migration; no
+      `.env`/`.env.example` var.
+- [ ] Admin's RAG index/delete management is untouched and NOT duplicated.
+- [ ] Both pages dogfooded in a real browser (screenshot captured).
+
+---
+
+## All Needed Context
+
+### Documentation & References
+```yaml
+- url: https://tanstack.com/query/latest/docs/framework/react/guides/queries
+  why: useQuery (GET) vs useMutation (POST) — the Knowledge search is a mutation
+  critical: |
+    GET data → useQuery({ queryKey, queryFn }). POST actions → useMutation({
+    mutationFn }). The repo's hooks follow this exactly (see use-rag-sources.ts).
+    Semantic search is a POST → a useMutation, NOT a useQuery.
+
+- url: https://reactrouter.com/en/main/route/lazy
+  why: react-router v6 route registration; the repo lazy-loads every page
+  critical: Mirror App.tsx — `lazy(() => import('@/pages/x'))` + `<Suspense>`.
+
+- file: PRPs/PRP-17-demo-showcase-page.md
+  why: The most recent "add a new page" PRP. Its frontend tasks (constants +
+    App.tsx + lazy route + nav entry) are the exact pattern to copy.
+  critical: This PRP follows PRP-17's frontend half precisely; the only deltas
+    are "two pages instead of one" and "no backend slice".
+
+- file: frontend/src/App.tsx
+  why: Lazy-route registration. Add `KnowledgePage` and `GuidePage` lazily and a
+    `<Route path={ROUTES.KNOWLEDGE}>` / `<Route path={ROUTES.GUIDE}>` exactly
+    like the existing `ShowcasePage` block (lines 12, 42-49).
+  critical: Pages are `lazy(() => import(...))`; each route element is wrapped in
+    `<Suspense fallback={<PageLoader />}>`.
+
+- file: frontend/src/lib/constants.ts
+  why: ROUTES + NAV_ITEMS. Add `KNOWLEDGE: '/knowledge'` and `GUIDE: '/guide'`
+    to ROUTES, and two NAV_ITEMS entries.
+  critical: |
+    NAV_ITEMS is `as const`. Knowledge and Agent Guide are flat top-level items
+    (not grouped). Place `Knowledge` after `Visualize` and `Agent Guide` after
+    `Chat` so the nav reads: Dashboard · Showcase · Explorer · Visualize ·
+    Knowledge · Chat · Agent Guide · Admin (a "know it → chat → how to chat"
+    cluster). No new WS URL needed.
+
+- file: frontend/src/pages/admin.tsx
+  why: THE reference page. `RagSourcesPanel` (lines 116-253) already lists
+    `/rag/sources` data — copy its source-row markup. `SeederPanel`'s `StatCard`
+    (lines 769-785) is the data-summary tile to reuse on the Knowledge page.
+  critical: |
+    - admin.tsx keeps all sub-components in ONE file (RagSourcesPanel,
+      AliasesPanel, SeederPanel, StatCard helpers). Mirror that: knowledge.tsx
+      and guide.tsx each hold their own internal function components — do NOT
+      create a components/knowledge/ directory.
+    - The Knowledge page is READ-ONLY. Copy the source LIST markup but DROP the
+      "Index Document" dialog and the per-row delete AlertDialog — those are
+      management actions that stay in Admin.
+    - Reuse loading/error states: `<LoadingState message=.../>` and
+      `<ErrorDisplay error={error} onRetry={refetch} />`.
+
+- file: frontend/src/hooks/use-rag-sources.ts
+  why: Existing RAG hooks. `useRagSources()` (GET /rag/sources) is reused as-is.
+    ADD a new `useRetrieve()` mutation hook here for POST /rag/retrieve.
+  critical: |
+    useRagSources already returns SourceListResponse. The new useRetrieve wraps
+    `api<RetrieveResponse>('/rag/retrieve', { method: 'POST', body })`. It is a
+    useMutation (no cache invalidation needed — search is ephemeral).
+
+- file: frontend/src/lib/api.ts
+  why: The `api<T>()` fetch wrapper + `ApiError` (carries the RFC 7807
+    ProblemDetail) + `getErrorMessage()`.
+  critical: |
+    `api('/rag/retrieve', { method: 'POST', body: {...} })` JSON-encodes `body`.
+    On non-2xx it throws `ApiError` with `.status` and `.detail`. The Knowledge
+    search must catch this: `502` → "search unavailable, configure an embedding
+    provider"; other → `getErrorMessage(err)`.
+
+- file: app/features/rag/routes.py
+  why: The RAG endpoints the Knowledge page consumes.
+  critical: |
+    - GET  /rag/sources   → SourceListResponse  (no embeddings needed — always works)
+    - POST /rag/retrieve  → RetrieveResponse    (needs an embedding provider;
+      returns 502 application/problem+json if embedding generation fails — see
+      routes.py:214-224). The page must degrade gracefully on 502.
+
+- file: app/features/rag/schemas.py
+  why: AUTHORITATIVE wire shapes. Mirror these field-for-field into types/api.ts.
+  critical: |
+    RetrieveRequest (model_config = ConfigDict(extra="forbid") — send NOTHING
+    extra): query:str(1..2000), top_k:int(1..50, default 5),
+    similarity_threshold:float|null(0..1, default from settings — OMIT to use
+    the server default), filters:dict|null.
+    ChunkResult: chunk_id, source_id, source_path, source_type, content,
+    relevance_score:float(0..1), metadata:dict|null.
+    RetrieveResponse: results:ChunkResult[], query_embedding_time_ms:float,
+    search_time_ms:float, total_chunks_searched:int.
+    SourceResponse (already typed as `RagSource` in types/api.ts:157): source_id,
+    source_type, source_path, chunk_count, content_hash, indexed_at, metadata.
+
+- file: frontend/src/types/api.ts
+  why: TS type surface. `RagSource` + `SourceListResponse` (lines 157-171),
+    `AgentType` (line 199), `AIModelConfig`/`ProviderHealth` (lines 360-415)
+    already exist. ADD `RetrieveRequest`, `ChunkResult`, `RetrieveResponse`
+    near the `// === RAG ===` block (line 156).
+  critical: snake_case field names on the wire — match the Pydantic models exactly.
+
+- file: app/features/agents/agents/experiment.py
+  why: The experiment agent's EXACT tool names + behavior for the Guide page.
+  critical: |
+    Tools (use these EXACT names on the Guide page): tool_list_runs,
+    tool_get_run, tool_run_backtest, tool_compare_backtest_results,
+    tool_compare_runs, tool_create_alias (REQUIRES APPROVAL),
+    tool_archive_run (REQUIRES APPROVAL). The system prompt (lines 45-72)
+    describes the workflow — paraphrase it, do not invent capabilities.
+
+- file: app/features/agents/agents/rag_assistant.py
+  why: The RAG assistant's EXACT tool names + behavior for the Guide page.
+  critical: |
+    Tools: tool_retrieve_context, tool_format_citations, tool_check_evidence,
+    tool_list_sources. It answers ONLY from retrieved evidence, cites
+    source_path:chunk_id, and says "I don't have enough information" when the
+    knowledge base lacks coverage (system prompt lines 38-67).
+
+- file: app/features/agents/agents/base.py
+  why: Shared agent behavior + the approval helper for the Guide page.
+  critical: |
+    `requires_approval(name)` checks `settings.agent_require_approval`.
+    SYSTEM_PROMPT_HEADER / SAFETY_INSTRUCTIONS (lines 269-294) state the safety
+    contract — the Guide's "approval" section paraphrases SAFETY_INSTRUCTIONS.
+
+- file: app/core/config.py
+  why: The agent session limits to state on the Guide page (lines 147-172).
+  critical: |
+    Defaults to quote on the Guide (label them "default"): agent_max_tokens=4096,
+    agent_max_tool_calls=10, agent_timeout_seconds=120, agent_retry_attempts=3,
+    agent_require_approval=["create_alias","archive_run"],
+    agent_session_ttl_minutes=120, agent_default_model="anthropic:claude-sonnet-4-5".
+    The LIVE model is shown via /config/ai (useAIConfig) — the static numbers
+    above are config defaults; phrase them as "default" since an operator can
+    change them in Admin → AI Models.
+
+- file: frontend/src/hooks/use-config.ts
+  why: `useAIConfig()` (GET /config/ai) — the Guide page uses it to show the
+    currently-configured agent model AND the (now live) session limits.
+  critical: Reuse the hook as-is; do NOT add a config hook. The hook's response
+    type `AIModelConfig` in types/api.ts gains the five new agent-limit fields.
+
+- file: app/features/config/schemas.py
+  why: `AIModelConfig` (GET /config/ai response, lines 65-83). Extend it with
+    read-only agent-limit fields so the Guide renders limits live.
+  critical: |
+    ADD to AIModelConfig (NOT to AIModelConfigUpdate — these stay read-only,
+    not operator-settable here): agent_max_tool_calls:int,
+    agent_timeout_seconds:int, agent_retry_attempts:int,
+    agent_session_ttl_minutes:int, agent_require_approval:list[str].
+    agent_max_tokens is ALREADY present — do not re-add it.
+
+- file: app/features/config/service.py
+  why: `get_effective_config` (line 129) builds AIModelConfig from the Settings
+    singleton. Populate the five new fields from `settings.*`.
+  critical: The new fields are sourced from Settings exactly like the existing
+    agent_* fields (app/core/config.py lines 147-172) — pure read, no DB, no
+    migration. Mirror the existing `agent_max_tokens=settings.agent_max_tokens`
+    line.
+
+- file: app/features/config/tests/
+  why: test_schemas.py / test_service.py / test_routes.py — extend each so the
+    five new fields are covered (construction, service mapping from Settings,
+    and the GET /config/ai route response). Required by test-requirements.md.
+
+- file: frontend/src/pages/chat.tsx
+  why: The actual chat flow the Guide page describes — keep the Guide accurate
+    to it: pick agent in a Select → "Start Session" → type → stream → approval
+    prompt → "New Session".
+  critical: |
+    Client → server WS frame is `{ session_id, message }`. Server → client
+    events: text_delta, tool_call_start, tool_call_end, approval_required,
+    complete, error (see types/api.ts:185-197 AgentEventType). Describe these
+    accurately; do not invent event names.
+
+- file: docs/_base/API_CONTRACTS.md
+  why: Cross-check the /rag and /agents endpoint contracts + WS event list.
+  critical: The "WebSocket Events (/agents/stream)" section is the source of
+    truth for the Guide's streaming description.
+
+- file: frontend/src/hooks/use-demo-pipeline.test.ts
+  why: The vitest pattern — test PURE exported helpers (applyEvent,
+    createInitialSteps), not the React component. `knowledge-utils.test.ts`
+    mirrors this.
+
+- file: frontend/src/lib/date-utils.ts  &  frontend/src/lib/status-utils.ts
+  why: Precedent for a `lib/*.ts` pure-helper module. `knowledge-utils.ts` joins
+    them — pure functions, no React, easy to unit-test.
+
+- file: frontend/src/hooks/use-runs.ts  &  frontend/src/hooks/use-seeder.ts
+  why: The Live System State section reuses these. use-seeder.ts exports
+    `useSeederStatus()` (GET /seeder/status → SeederStatus). use-runs.ts exports
+    the runs + aliases hooks used by admin.tsx (`useAliases`) and
+    explorer/runs.tsx.
+  critical: VERIFY the exact export names in use-runs.ts before wiring — reuse
+    whatever it exports for runs (paginated) + aliases; do not add new hooks.
+
+- file: .claude/rules/ui-design.md
+  why: UI built/dogfooded via frontend-design + shadcn-ui + webapp-testing.
+- file: .claude/rules/output-formatting.md
+  why: If the Guide uses status glyphs, reuse the ✅/⚠️/⏭️ vocabulary.
+- file: .claude/rules/test-requirements.md
+  why: New TS component owning non-trivial state SHOULD have a vitest — satisfied
+    by extracting pure helpers into knowledge-utils.ts and testing them.
+- file: .claude/rules/commit-format.md
+  why: `type(scope): description (#issue)`; scope `ui` for frontend/**, `docs`
+    for README/docs. Open the tracking issue FIRST.
+- file: .claude/rules/branch-naming.md
+  why: `<type>/<kebab-slug>` off dev → `feat/knowledge-and-guide-pages`.
+```
+
+### Current Codebase tree (relevant)
+```bash
+frontend/src/
+├── App.tsx                       # MOD — add /knowledge + /guide lazy routes
+├── lib/
+│   ├── api.ts                    # reuse api<T>() + ApiError + getErrorMessage
+│   ├── constants.ts              # MOD — ROUTES + NAV_ITEMS
+│   ├── date-utils.ts             # precedent: pure lib helper module
+│   ├── status-utils.ts           # precedent: pure lib helper module
+│   └── knowledge-utils.ts        # NEW — pure helpers for the Knowledge page
+├── types/api.ts                  # MOD — +RetrieveRequest, ChunkResult, RetrieveResponse
+├── hooks/
+│   ├── use-rag-sources.ts        # MOD — +useRetrieve mutation
+│   ├── use-seeder.ts             # reuse useSeederStatus
+│   ├── use-runs.ts               # reuse runs + aliases hooks
+│   └── use-config.ts             # reuse useAIConfig
+├── pages/
+│   ├── admin.tsx                 # reference (RagSourcesPanel, StatCard) — UNCHANGED
+│   ├── chat.tsx                  # reference for the Guide's accuracy — UNCHANGED
+│   ├── showcase.tsx              # reference page registration (PRP-17)
+│   ├── knowledge.tsx             # NEW — the Knowledge page
+│   └── guide.tsx                 # NEW — the Agent Guide page
+└── components/
+    ├── ui/                       # reuse Card, Badge, Input, Button, Tabs, Separator
+    └── common/                   # reuse LoadingState, ErrorDisplay
+```
+
+### Desired Codebase tree (files added / changed)
+```bash
+NEW  frontend/src/pages/knowledge.tsx           # Knowledge page (KB + live state)
+NEW  frontend/src/pages/guide.tsx               # Agent Guide page
+NEW  frontend/src/lib/knowledge-utils.ts        # pure helpers (testable, no React)
+NEW  frontend/src/lib/knowledge-utils.test.ts   # vitest — pure-helper coverage
+MOD  frontend/src/types/api.ts                  # +RetrieveRequest/ChunkResult/RetrieveResponse; +5 AIModelConfig fields
+MOD  frontend/src/hooks/use-rag-sources.ts      # +useRetrieve mutation hook
+MOD  frontend/src/lib/constants.ts              # +KNOWLEDGE/GUIDE routes, +2 NAV_ITEMS
+MOD  frontend/src/App.tsx                       # +2 lazy imports, +2 <Route>s
+MOD  frontend/src/pages/chat.tsx                # + help link to /guide
+MOD  app/features/config/schemas.py             # +5 read-only agent-limit fields on AIModelConfig
+MOD  app/features/config/service.py             # populate the 5 fields in get_effective_config
+MOD  app/features/config/tests/test_schemas.py  # cover the new fields
+MOD  app/features/config/tests/test_service.py  # cover get_effective_config mapping
+MOD  app/features/config/tests/test_routes.py   # cover GET /config/ai response
+MOD  README.md                                  # mention the two new pages in the feature list
+MOD  docs/_base/REPO_MAP_INDEX.md               # +rows for knowledge.tsx + guide.tsx
+KEEP frontend/src/pages/admin.tsx               # UNCHANGED — management stays here
+KEEP all other app/** (backend)                 # UNCHANGED — only the config slice changes
+```
+
+### Known Gotchas & Library Quirks
+```typescript
+// CRITICAL: FRONTEND-LED PRP with ONE additive backend change — the config
+//   slice only (schemas.py + service.py + tests). No new slice, no Alembic
+//   migration, no .env var. Because .py files DO change, the repo-wide
+//   ruff/mypy/pyright/pytest gates genuinely apply — run them (see Validation
+//   Level 4), do not assume they pass trivially. The three pnpm gates still
+//   gate the frontend half.
+
+// CRITICAL: /rag/retrieve needs an embedding provider (OpenAI key or Ollama).
+//   With none configured it returns 502 application/problem+json. The Knowledge
+//   page MUST degrade gracefully: the source LIST (GET /rag/sources) needs NO
+//   embeddings and always works; only the SEARCH box can 502 — catch ApiError,
+//   show "Semantic search unavailable — configure an embedding provider in
+//   Admin → AI Models", keep the rest of the page functional.
+
+// CRITICAL: RetrieveRequest is ConfigDict(extra="forbid"). Send ONLY
+//   { query, top_k } (+ optional similarity_threshold/filters). Any stray field
+//   → 422. OMIT similarity_threshold entirely to use the server-side default.
+
+// CRITICAL: search is a useMutation, NOT a useQuery. The query string is
+//   user-typed and submitted on click/Enter — it is an imperative action with
+//   ephemeral results, exactly the useMutation shape. (useQuery would re-fire
+//   on every keystroke / refetch.)
+
+// CRITICAL: the Knowledge page is READ-ONLY. Do NOT add index/delete actions —
+//   they already live in Admin → RAG Sources (admin.tsx RagSourcesPanel). The
+//   Knowledge page COPIES the source-row display markup but DROPS the dialog
+//   and the delete AlertDialog. Duplicating management UI is the anti-pattern.
+
+// CRITICAL: the Guide page must use the EXACT agent tool names from the agent
+//   definitions (experiment.py / rag_assistant.py). Do not paraphrase tool
+//   names. A user copying "tool_run_backtest" into chat must match reality.
+
+// GOTCHA: agent limit numbers (4096 tokens, 10 tool calls, 120s, TTL 120 min)
+//   are config DEFAULTS — an operator can change them. Label them "default" on
+//   the Guide. The LIVE agent model comes from /config/ai (useAIConfig); render
+//   that dynamically, not a hardcoded model string.
+
+// GOTCHA: empty knowledge base — a fresh DB has zero RAG sources. The Knowledge
+//   Base section must show a friendly empty state ("No documents indexed yet —
+//   add some in Admin → RAG Sources, or run the RAG seeder scenario"), not a
+//   blank card and not a crash.
+
+// GOTCHA: NAV_ITEMS is declared `as const`. Adding two flat entries is fine;
+//   keep the object shape `{ label, href }` identical to the existing flat
+//   items (Dashboard/Showcase/Chat/Admin) so top-nav.tsx's `'items' in item`
+//   discriminator still works.
+
+// GOTCHA: react-router lazy route — the page file MUST `export default` the
+//   component (App.tsx does `lazy(() => import('@/pages/knowledge'))`). Named
+//   helper exports from the SAME file are allowed, but the Knowledge page's
+//   pure helpers live in lib/knowledge-utils.ts so they are import-cheap to
+//   unit-test (mirrors use-demo-pipeline.ts exporting applyEvent et al.).
+
+// GOTCHA: new frontend files use LF line endings (the repo's CRLF note in
+//   memory applies to .py files only). Match the surrounding .tsx files — they
+//   are LF. eslint.config.js + tsc are the enforcers.
+
+// GOTCHA: every commit needs an open issue (commit-format.md). Open the
+//   tracking issue BEFORE the first commit. No AI co-author trailer, ever.
+```
+
+### Known Tradeoffs (decided — do not re-litigate)
+```yaml
+interpretation:
+  decision: "ForecastLab's current knowledge" = the RAG knowledge base (what the
+    rag_assistant answers from) PLUS the live system state (what the experiment
+    agent acts on: seeded data, runs, aliases). The Knowledge page shows both.
+  why: The agentic layer has two agents with two distinct knowledge surfaces.
+    Showing only the RAG corpus would under-represent "what the system knows"
+    and would also thinly duplicate Admin's RAG tab. Showing both makes the page
+    a genuine "knowledge dashboard" and a true counterpart to the Agent Guide.
+  status: confirmed — Resolved Decision 1 keeps both the RAG corpus and the
+    Live System State section; not scoped down to RAG-only.
+minimal-backend:
+  decision: no NEW backend slice and no /knowledge or /guide API. The only
+    server-side change is additive: read-only agent-limit fields on the existing
+    AIModelConfig (GET /config/ai) response.
+  why: Every page datum except the live session limits is already served
+    (/rag/sources, /rag/retrieve, /seeder/status, /registry/runs,
+    /registry/aliases, /config/ai). The maintainer chose live limits over static
+    text (Resolved Decision 3), and /config/ai is the natural, already-existing
+    home for them — extending it beats a new endpoint.
+guide-content-plus-live-config:
+  decision: the Guide page is hand-authored content + live /config/ai data (the
+    configured model AND the session limits).
+  why: It is documentation; the prose (agents, tools, approval flow, example
+    prompts) is stable. The two things that legitimately drift — the model and
+    the limits — are both fetched live from /config/ai.
+search-is-mutation:
+  decision: semantic search uses useMutation, not useQuery.
+  why: it is a user-initiated imperative action with throwaway results.
+```
+
+---
+
+## Implementation Blueprint
+
+### Data models / types (`frontend/src/types/api.ts`, add near line 156 `// === RAG ===`)
+```typescript
+// Append to the existing RAG block — mirror app/features/rag/schemas.py exactly.
+
+export interface RetrieveRequest {
+  query: string
+  top_k?: number              // 1..50, server default 5
+  similarity_threshold?: number  // 0..1 — OMIT to use the server default
+  filters?: Record<string, unknown> | null
+}
+
+export interface ChunkResult {
+  chunk_id: string
+  source_id: string
+  source_path: string
+  source_type: string
+  content: string
+  relevance_score: number     // 0..1
+  metadata: Record<string, unknown> | null
+}
+
+export interface RetrieveResponse {
+  results: ChunkResult[]
+  query_embedding_time_ms: number
+  search_time_ms: number
+  total_chunks_searched: number
+}
+```
+
+### Backend change (`app/features/config/schemas.py` + `service.py`)
+```python
+# schemas.py — append to AIModelConfig (the GET /config/ai response model),
+# NOT to AIModelConfigUpdate (these are read-only, not operator-settable here):
+agent_max_tool_calls: int = Field(description="Per-session tool-call cap")
+agent_timeout_seconds: int = Field(description="Per-run agent timeout (seconds)")
+agent_retry_attempts: int = Field(description="Agent retry attempts on failure")
+agent_session_ttl_minutes: int = Field(description="Session time-to-live (minutes)")
+agent_require_approval: list[str] = Field(
+    description="Tool names gated by human-in-the-loop approval"
+)
+# agent_max_tokens is ALREADY on AIModelConfig — do not re-add it.
+
+# service.py — get_effective_config(): populate each from the Settings singleton,
+# mirroring the existing `agent_max_tokens=settings.agent_max_tokens` line.
+```
+
+### Frontend type extension (`frontend/src/types/api.ts`, existing `AIModelConfig`)
+```typescript
+// EXTEND the existing AIModelConfig interface (~line 360) with the five fields
+// the backend now returns — snake_case, matching the Pydantic model:
+//   agent_max_tool_calls: number
+//   agent_timeout_seconds: number
+//   agent_retry_attempts: number
+//   agent_session_ttl_minutes: number
+//   agent_require_approval: string[]
+// agent_max_tokens already exists on AIModelConfig — do not duplicate it.
+```
+
+### Hook (`frontend/src/hooks/use-rag-sources.ts`, append)
+```typescript
+// Pseudocode — mirror the existing useIndexDocument mutation shape.
+import type { RetrieveRequest, RetrieveResponse } from '@/types/api'
+
+export function useRetrieve() {
+  return useMutation({
+    mutationFn: (body: RetrieveRequest) =>
+      api<RetrieveResponse>('/rag/retrieve', { method: 'POST', body }),
+    // no onSuccess cache invalidation — search results are ephemeral
+  })
+}
+```
+
+### Pure helpers (`frontend/src/lib/knowledge-utils.ts`)
+```typescript
+// Pure, React-free, unit-testable. Exact helper set is implementer's choice;
+// at minimum provide these two so knowledge-utils.test.ts has real coverage:
+
+import type { RagSource, ChunkResult } from '@/types/api'
+
+/** Relevance score (0..1) → a display percentage string, e.g. 0.873 -> "87%". */
+export function formatRelevance(score: number): string { /* clamp 0..1, round */ }
+
+/** Group indexed sources by source_type for the "by type" summary. */
+export function groupSourcesByType(sources: RagSource[]): Record<string, RagSource[]> { /* ... */ }
+
+/** Optional: short, single-line excerpt of a chunk for the result card. */
+export function chunkExcerpt(chunk: ChunkResult, maxChars?: number): string { /* ... */ }
+```
+
+### Knowledge page (`frontend/src/pages/knowledge.tsx`)
+```text
+export default function KnowledgePage()
+Layout (build with frontend-design + shadcn-ui; mirror admin.tsx structure):
+
+- Header: <h1>Knowledge</h1> + one sentence: "Everything ForecastLabAI can
+  currently draw on — the RAG knowledge base its assistant answers from, and the
+  live data its experiment agent acts on."
+
+- SECTION 1 — Knowledge Base (Card):
+    * useRagSources() → SourceListResponse.
+    * CardDescription: "{total_sources} sources • {total_chunks} chunks".
+    * Source list: read-only rows (path, <Badge>{source_type}</Badge>,
+      "{chunk_count} chunks", "Indexed {date}"). COPY the row markup from
+      admin.tsx RagSourcesPanel lines 209-243 MINUS the delete AlertDialog.
+    * Empty state when sources.length === 0 → friendly message + link to
+      ROUTES.ADMIN ("Index documents in Admin → RAG Sources").
+    * isLoading → <LoadingState/>; error → <ErrorDisplay onRetry={refetch}/>.
+
+- SECTION 2 — Semantic Search (Card, inside or below Section 1):
+    * Controlled <Input> for the query + a "Search" <Button>.
+    * useRetrieve() mutation. On submit: trim query; if empty, do nothing
+      (button disabled). Call mutateAsync({ query, top_k: 5 }).
+    * Render results: for each ChunkResult a small card — relevance badge
+      (formatRelevance), source_path:source_type, chunkExcerpt(content).
+    * mutation.isPending → spinner on the button.
+    * mutation.error → if ApiError.status === 502: "Semantic search unavailable
+      — configure an embedding provider in Admin → AI Models"; else
+      getErrorMessage(error). The source list above stays usable regardless.
+    * Empty results (200, results.length === 0) → "No matching content found."
+
+- SECTION 3 — Live System State (Card or grid of Cards):
+    * useSeederStatus() → StatCard grid (reuse the StatCard pattern from
+      admin.tsx lines 769-785): Stores, Products, Sales, date range.
+    * Reuse the runs hook from use-runs.ts → show the registered model-run
+      count; reuse the aliases hook → list deployment aliases (name + model_type).
+    * One explainer line: "The RAG assistant answers from the Knowledge Base;
+      the experiment agent acts on this Live System State." Link to /guide and
+      /chat.
+```
+
+### Agent Guide page (`frontend/src/pages/guide.tsx`)
+```text
+export default function GuidePage()
+Mostly static, well-structured content. Build with frontend-design + shadcn-ui.
+
+- Header: <h1>Agent Guide</h1> + "How to use the Chat agents."
+
+- Live config callout: useAIConfig() → "Agents currently run on
+  {config.agent_model}." (graceful if loading/errored — just omit the callout).
+  Link: "manage in Admin → AI Models".
+
+- SECTION — The two agents (two Cards, side by side on desktop):
+    * RAG Assistant (rag_assistant):
+        - Purpose: evidence-grounded Q&A over the knowledge base; cites
+          source_path:chunk_id; says "I don't have enough information" when
+          coverage is missing.
+        - Tools: tool_retrieve_context, tool_list_sources,
+          tool_format_citations, tool_check_evidence.
+        - Link: "See what it can answer from → /knowledge".
+    * Experiment Agent (experiment):
+        - Purpose: plan + run backtests, compare models, recommend/deploy a
+          winner.
+        - Tools: tool_list_runs, tool_get_run, tool_run_backtest,
+          tool_compare_backtest_results, tool_compare_runs,
+          tool_create_alias (⚠ requires approval), tool_archive_run (⚠ requires
+          approval).
+
+- SECTION — How a chat session works (ordered list, mirror chat.tsx):
+    1. Open Chat, pick an agent type, click "Start Session".
+    2. Type a message and send.
+    3. Watch the reply stream token-by-token; tool calls show as chips
+       (tool_call_start → tool_call_end).
+    4. If the agent proposes a guarded action, an approval prompt appears —
+       approve or reject.
+    5. "New Session" starts a fresh conversation.
+
+- SECTION — Human-in-the-loop approval:
+    * Explain create_alias + archive_run pause for approval (from
+      agent_require_approval). Paraphrase base.py SAFETY_INSTRUCTIONS.
+
+- SECTION — Session limits (a small table, rendered LIVE from useAIConfig()):
+    * Token budget (agent_max_tokens) · Tool calls (agent_max_tool_calls) ·
+      Timeout (agent_timeout_seconds) · Retries (agent_retry_attempts) ·
+      Session TTL (agent_session_ttl_minutes) · Approval-gated tools
+      (agent_require_approval). All from GET /config/ai. Graceful when the
+      query is loading/errored (show a skeleton or omit the table, never crash).
+      Note: configurable in Admin → AI Models.
+
+- SECTION — Example prompts (copy-paste, in <code>/Card blocks):
+    * RAG Assistant: "What forecasting models does ForecastLabAI support?",
+      "How does backtesting prevent data leakage?", "What is in your knowledge
+      base?"
+    * Experiment Agent: "Backtest a seasonal_naive model for store 1 product 1
+      over the last 90 days and compare it to the naive baseline.",
+      "List the most recent model runs and tell me which has the lowest WAPE."
+
+- CTA: <Button> linking to ROUTES.CHAT — "Open Chat".
+```
+
+### list of tasks (in execution order)
+```yaml
+Task 1 — Tracking GitHub issue: ✅ DONE — issue #185
+  https://github.com/w7-mgfcode/ForecastLabAI/issues/185
+  Do NOT open another issue. Every commit below references (#185).
+
+Task 2 — Backend: extend GET /config/ai with agent-limit fields:
+  MODIFY app/features/config/schemas.py
+    - Append to AIModelConfig (NOT AIModelConfigUpdate): agent_max_tool_calls:int,
+      agent_timeout_seconds:int, agent_retry_attempts:int,
+      agent_session_ttl_minutes:int, agent_require_approval:list[str].
+      agent_max_tokens is already present — leave it.
+  MODIFY app/features/config/service.py
+    - In get_effective_config (line 129), populate each new field from the
+      Settings singleton, mirroring `agent_max_tokens=settings.agent_max_tokens`.
+  MODIFY app/features/config/tests/{test_schemas.py,test_service.py,test_routes.py}
+    - Cover the five new fields: schema construction, service mapping from
+      Settings, and the GET /config/ai route response shape.
+  VALIDATE: uv run ruff check app/ && uv run mypy app/ && uv run pyright app/ &&
+    uv run pytest -v app/features/config/tests
+
+Task 3 — Types:
+  MODIFY frontend/src/types/api.ts
+    - Add RetrieveRequest, ChunkResult, RetrieveResponse to the `// === RAG ===`
+      block (after SourceListResponse / IndexDocumentResponse, ~line 182).
+    - EXTEND the existing AIModelConfig interface (~line 360) with the five new
+      fields from Task 2 (agent_max_tool_calls, agent_timeout_seconds,
+      agent_retry_attempts, agent_session_ttl_minutes, agent_require_approval).
+    - Field names snake_case, matching the Pydantic models exactly.
+
+Task 4 — Hook:
+  MODIFY frontend/src/hooks/use-rag-sources.ts
+    - Add `useRetrieve()` — a useMutation wrapping POST /rag/retrieve (see
+      pseudocode). Import RetrieveRequest/RetrieveResponse from @/types/api.
+    - hooks/index.ts already re-exports use-rag-sources — no change there.
+    - useAIConfig() already exists in use-config.ts — no new config hook.
+
+Task 5 — Pure helpers + routing + constants:
+  CREATE frontend/src/lib/knowledge-utils.ts — formatRelevance,
+    groupSourcesByType, chunkExcerpt (pure, no React import).
+  MODIFY frontend/src/lib/constants.ts
+    - ROUTES: add `KNOWLEDGE: '/knowledge'` and `GUIDE: '/guide'`.
+    - NAV_ITEMS: add `{ label: 'Knowledge', href: ROUTES.KNOWLEDGE }` after the
+      Visualize group, and `{ label: 'Agent Guide', href: ROUTES.GUIDE }` after
+      the Chat entry (before Admin). Keep the flat `{ label, href }` shape.
+  MODIFY frontend/src/App.tsx
+    - `const KnowledgePage = lazy(() => import('@/pages/knowledge'))`
+    - `const GuidePage = lazy(() => import('@/pages/guide'))`
+    - Two `<Route>`s wrapped in `<Suspense fallback={<PageLoader/>}>`, mirroring
+      the ShowcasePage block.
+
+Task 6 — Knowledge page:
+  CREATE frontend/src/pages/knowledge.tsx
+    - `export default function KnowledgePage()` (see "Knowledge page" layout).
+    - Section 1: useRagSources() — read-only source list + summary + empty state.
+    - Section 2: useRetrieve() — search box, results cards, 502 graceful state.
+    - Section 3: useSeederStatus() + useRuns()/useAliases() — StatCard grid +
+      runs count + alias list + explainer linking /guide and /chat.
+    - Reuse LoadingState / ErrorDisplay; reuse Card/Badge/Input/Button.
+    - Build via the frontend-design + shadcn-ui skills (.claude/rules/ui-design.md).
+
+Task 7 — Agent Guide page + Chat help-link:
+  CREATE frontend/src/pages/guide.tsx
+    - `export default function GuidePage()` (see "Agent Guide page" layout).
+    - useAIConfig() for the live model callout AND the live session-limits table
+      (graceful when loading/errored).
+    - EXACT agent tool names from experiment.py / rag_assistant.py.
+    - Example prompts; CTA → ROUTES.CHAT.
+  MODIFY frontend/src/pages/chat.tsx
+    - Add a small, unobtrusive help link to ROUTES.GUIDE (e.g. near the agent
+      Select or the page header) — "New here? Read the Agent Guide". Do not
+      restructure the chat flow; this is one link.
+
+Task 8 — Frontend test:
+  CREATE frontend/src/lib/knowledge-utils.test.ts
+    - vitest, mirror use-demo-pipeline.test.ts structure (describe/it/expect).
+    - formatRelevance: 0.873 -> "87%"; clamps 0 and 1; handles out-of-range.
+    - groupSourcesByType: groups a mixed RagSource[] into per-type buckets;
+      empty array -> {}.
+    - chunkExcerpt: truncates long content; short content returned intact.
+
+Task 9 — Docs:
+  MODIFY README.md — add the two pages to the feature/endpoint list (near where
+    Showcase / dashboard pages are described).
+  MODIFY docs/_base/REPO_MAP_INDEX.md — add rows for frontend/src/pages/knowledge.tsx
+    and frontend/src/pages/guide.tsx in the document index table.
+
+Task 10 — Dogfood the running UI (mandatory per ui-design.md):
+  - docker compose up -d ; uv run alembic upgrade head ; seed data once
+    (uv run python scripts/seed_random.py --full-new --seed 42 --confirm).
+  - uv run uvicorn app.main:app --port 8123 & ; cd frontend && pnpm dev.
+  - Use webapp-testing / agent-browser: open /knowledge — confirm the source
+    list renders, run a semantic search, confirm result cards + relevance
+    badges, confirm the Live System State tiles. Open /guide — confirm both
+    agent cards, the live model callout, and the LIVE limits table (values
+    match GET /config/ai). Confirm the Chat page's help link reaches /guide.
+    Capture screenshots.
+  - Optional: with no embedding key, confirm the search box shows the graceful
+    502 state while the rest of /knowledge still works.
+
+Task 11 — Commit + PR:
+  Branch: feat/knowledge-and-guide-pages (off dev, per branch-naming.md).
+  Commits (each referencing the Task-1 issue; no AI co-author trailer).
+  Scope note: the config slice has no dedicated scope in commit-format.md;
+  it was introduced under `api,ui` (commit db530d5), so use `api` for it.
+    1. feat(api): expose agent session limits on GET /config/ai (#185)
+    2. feat(ui): knowledge page — RAG corpus + live system state (#185)
+    3. feat(ui): agent guide page explaining the chat agents (#185)
+    4. test(ui): knowledge-utils pure-helper coverage (#185)
+    5. docs(docs): document the knowledge + agent guide pages (#185)
+  Open PR into dev; CI green; merge.
+```
+
+### Integration Points
+```yaml
+DATABASE:    NONE — no migration, no DB schema change.
+BACKEND:     config slice ONLY — AIModelConfig schema + get_effective_config
+             service gain five read-only agent-limit fields; config slice tests
+             updated. No new slice, no new endpoint, all other app/** unchanged.
+CONFIG:      NONE — no new env var (the limits already exist in Settings).
+FRONTEND ROUTING:
+  - ROUTES.KNOWLEDGE + ROUTES.GUIDE + two NAV_ITEMS entries (constants.ts).
+  - Two lazy <Route>s in App.tsx; a help link to /guide on chat.tsx.
+CI:
+  - No new workflow. ci.yml's existing jobs cover it. The frontend gates run as
+    today; the Python jobs now genuinely exercise the config-slice change —
+    they must be GREEN, not assumed-trivial.
+```
+
+---
+
+## Validation Loop
+
+### Level 1: Type & Lint (frontend)
+```bash
+cd frontend
+pnpm install
+pnpm tsc --noEmit        # zero type errors — new types + pages must compile
+pnpm lint                # eslint clean
+# Expected: no errors. Fix any before proceeding.
+```
+
+### Level 2: Unit test (frontend)
+```bash
+cd frontend
+pnpm test --run          # vitest — knowledge-utils.test.ts must pass
+# Expected: all green, including the new knowledge-utils suite.
+```
+
+### Level 3: Manual end-to-end (the maintainer's actual UX)
+```bash
+docker compose up -d && uv run alembic upgrade head
+uv run python scripts/seed_random.py --full-new --seed 42 --confirm   # data + RAG
+uv run uvicorn app.main:app --port 8123 &
+until curl -fs http://127.0.0.1:8123/health; do sleep 2; done
+cd frontend && pnpm dev          # http://localhost:5173
+
+# Browser checks (via webapp-testing / agent-browser):
+#  /knowledge — source list renders; type a query, click Search, see ChunkResult
+#               cards with relevance %; Live System State tiles show seeded data.
+#  /guide     — both agent cards with exact tool names; live model callout;
+#               limits table; example prompts; "Open Chat" button works.
+#  Nav        — "Knowledge" and "Agent Guide" appear in desktop nav + mobile sheet.
+```
+
+### Level 4: Backend gates (the config slice .py files DID change)
+```bash
+uv run ruff check . && uv run ruff format --check .
+uv run mypy app/ && uv run pyright app/              # both --strict, both gate
+uv run pytest -v -m "not integration" app/features/config/tests
+docker compose up -d
+uv run pytest -v -m integration app/features/config/tests
+# Expected: all green. The config slice change is additive + read-only.
+```
+
+---
+
+## Final Validation Checklist
+- [ ] `cd frontend && pnpm tsc --noEmit` clean
+- [ ] `cd frontend && pnpm lint` clean
+- [ ] `cd frontend && pnpm test --run` all green (incl. `knowledge-utils.test.ts`)
+- [ ] `uv run ruff check . && uv run mypy app/ && uv run pyright app/` clean
+- [ ] `uv run pytest -v app/features/config/tests` green (new agent-limit fields)
+- [ ] `GET /config/ai` returns agent_max_tool_calls, agent_timeout_seconds,
+      agent_retry_attempts, agent_session_ttl_minutes, agent_require_approval
+- [ ] `/knowledge` renders: source list + summary, semantic search, Live System
+      State tiles; empty-KB and 502-search states both handled gracefully
+- [ ] `/guide` renders: both agent cards with EXACT tool names, approval-gate
+      section, LIVE limits table + live model from `/config/ai`, example prompts
+- [ ] Both pages reachable from desktop nav AND mobile sheet; Chat links to /guide
+- [ ] Both pages dogfooded in a real browser (screenshots captured)
+- [ ] Admin → RAG Sources is unchanged; no index/delete management duplicated
+- [ ] Only the `config` slice changed under `app/**`; no Alembic migration; no
+      `.env` var added
+- [ ] README + `docs/_base/REPO_MAP_INDEX.md` updated
+- [ ] Branch `feat/knowledge-and-guide-pages`; every commit references the
+      Task-1 issue; no AI co-author trailer
+
+---
+
+## Anti-Patterns to Avoid
+- ❌ Don't add a NEW backend slice or endpoint — the only backend change is
+  five additive read-only fields on the existing `AIModelConfig` response.
+- ❌ Don't add the new limit fields to `AIModelConfigUpdate` (the PATCH body) —
+  they are read-only on the GET response, not operator-settable here.
+- ❌ Don't duplicate Admin's RAG index/delete management on the Knowledge page —
+  it is READ-ONLY; management stays in `admin.tsx`.
+- ❌ Don't use `useQuery` for the semantic search — it is a user-initiated POST →
+  `useMutation`.
+- ❌ Don't send extra fields on `RetrieveRequest` — it is `extra="forbid"`; omit
+  `similarity_threshold` to use the server default.
+- ❌ Don't let a `502` from `/rag/retrieve` blank the page — the source list does
+  not need embeddings; degrade only the search box.
+- ❌ Don't invent agent tool names on the Guide — copy them verbatim from
+  `experiment.py` / `rag_assistant.py`.
+- ❌ Don't hardcode the agent model string on the Guide — render it from
+  `/config/ai`.
+- ❌ Don't hand-roll the pages without the `frontend-design` / `shadcn-ui` skills,
+  and don't claim "done" on a green type-check — dogfood in a real browser
+  (`.claude/rules/ui-design.md`).
+- ❌ Don't create a `components/knowledge/` directory — keep sub-components inside
+  the page file, mirroring `admin.tsx`.
+- ❌ Don't `git push --force` on dev/main; don't add AI co-author trailers; every
+  commit references the open issue.
+
+---
+
+## Resolved Decisions (maintainer-confirmed 2026-05-18)
+1. **Knowledge page scope → RAG + Live System State.** The `/knowledge` page
+   ships all three sections — Knowledge Base, Semantic Search, and Live System
+   State (seeded data, runs, aliases). Not scoped down to RAG-only.
+2. **Navigation → two flat nav items AND a Chat help-link.** Both `Knowledge`
+   and `Agent Guide` are flat top-level nav entries (8 items total); ADDITIONALLY
+   the Chat page carries a help link to `/guide` (Task 5 + Task 7).
+3. **Guide limits → live, backend folded into this PRP.** The session limits are
+   rendered live from `/config/ai`, which is extended in this PRP (Task 2) with
+   five read-only agent-limit fields. PRP-19 is therefore frontend-led with one
+   small additive backend change — it is no longer "frontend-only".
+
+---
+
+## Confidence Score
+
+**8 / 10** for one-pass implementation success.
+
+**Why high:**
+- Frontend-led and almost entirely additive — two new pages + a handful of small
+  edits. The one backend change is a five-field, read-only, additive extension
+  of an existing response model (`AIModelConfig`), sourced straight from
+  `Settings` — no migration, no new endpoint, no behavioural change.
+- Every endpoint is already shipped and already has a hook; the page-registration
+  pattern is a verbatim copy of PRP-17's `Showcase` wiring, cited file+line.
+- `admin.tsx` already renders `/rag/sources` data — the source-list markup is
+  lifted, not invented. The one new hook (`useRetrieve`) is a ~6-line clone of
+  the existing `useIndexDocument` mutation.
+- Validation gates are concrete and fast: three pnpm gates for the frontend,
+  plus the config-slice backend gates (ruff/mypy/pyright/pytest).
+- All three Open Questions are now Resolved Decisions — no scoping ambiguity.
+
+**Why not 10:**
+- Both pages are genuine UI composition work — layout, hierarchy, and the
+  Guide's content density need a real-browser dogfooding pass (Task 10); a green
+  `tsc` will not catch a cramped layout or a broken nav link.
+- The `502`-graceful search path depends on the local embedding-provider state;
+  it must be exercised both with and without a key to confirm the degrade path.
+- The backend change is small but DOES make the repo-wide mypy/pyright/pytest
+  gates load-bearing — the config-slice tests must be extended, not skipped.
+
+All risks are caught by the validation loop (browser dogfood + the 502 toggle +
+the config-slice test run) and the fixes are local.
diff --git a/PRPs/PRP-20-explorer-interactivity.md b/PRPs/PRP-20-explorer-interactivity.md
new file mode 100644
index 00000000..12fe1ab6
--- /dev/null
+++ b/PRPs/PRP-20-explorer-interactivity.md
@@ -0,0 +1,1002 @@
+name: "PRP-20 — Explorer Interactivity Extension (Sales / Stores / Products)"
+description: |
+  Turn the three primary Explorer pages of the ForecastLabAI dashboard —
+  **Sales**, **Stores**, **Products** — from flat, read-only list/drilldown
+  views into an interactive analysis surface:
+
+  1. **Click-through detail views** — two new deep-linkable routes
+     (`/explorer/stores/:storeId`, `/explorer/products/:productId`) reached by
+     clicking a table row. Each shows the entity's profile, date-scoped KPIs, a
+     revenue-over-time chart, and a top-contributors drilldown.
+  2. **Richer tables** — server-side column sorting, CSV export, and
+     column-visibility toggles on the Stores / Products / Runs DataTables.
+  3. **Charts on the Sales page** — a revenue-by-dimension bar chart and a
+     revenue-over-time line chart alongside the existing ranked drilldown list.
+  4. **Cross-filtering** — filter / date / dimension state persisted in the URL
+     query string, and a "View in Sales" link from detail pages that carries
+     `store_id` / `product_id` into the Sales analytics page.
+
+  Backend-touching but additive: one new read-only endpoint
+  (`GET /analytics/timeseries`) supplies the aggregated series the charts need,
+  and the two `/dimensions` list endpoints gain additive `sort_by` / `sort_order`
+  query params. **No Alembic migration** (every query is a read aggregate over
+  existing tables), **no new slice**, **no new env var**, **no `app/main.py`
+  change** (the `analytics` router is already wired).
+
+> **PRP numbering:** `PRP-16` is reserved (Phase-2 LightGBM, per PRP-15).
+> `PRP-17` (Showcase), `PRP-18` (AI Model console), `PRP-19` (Knowledge + Agent
+> Guide) are used. This is `PRP-20`. Source plan:
+> `.agents/plans/explorer-interactivity-extension.md`.
+
+## Purpose
+Close the "the Explorer pages are terminal" gap. Today Stores and Products are
+static paginated tables with no row interaction, no sorting, no export; Sales is
+a ranked text list with no visual trend; filter state is lost on every refresh;
+and there is no way to scope analytics to a single entity from the UI — an
+analyst must drop to Swagger (`/docs`) or `curl`. This PRP makes the Explorer a
+place you can actually *investigate* in.
+
+## Core Principles
+1. **Context is King** — every endpoint shape, hook name, schema field, service
+   method, and pattern below is linked to a real source file + line.
+2. **Reuse existing patterns** — the new endpoint mirrors `compute_kpis`; the
+   new pages mirror `sales.tsx` / `dashboard.tsx`; charts reuse `TimeSeriesChart`
+   and the `backtest-folds-chart.tsx` Recharts pattern; detail routes register
+   exactly like the existing Explorer routes in `App.tsx`.
+3. **Additive only** — no new slice, no migration, no new `.env` var, no
+   `app/main.py` edit. The backend deltas are one new route on the existing
+   `analytics` router + two optional query params on `/dimensions`.
+4. **Strict gates honored** — because `.py` files in the `analytics` and
+   `dimensions` slices change, the repo-wide `ruff` / `mypy --strict` /
+   `pyright --strict` / `pytest` CI jobs genuinely apply and must stay green —
+   each backend change ships with slice tests.
+5. **UI through skills** — pages built via `frontend-design` + `shadcn-ui` and
+   dogfooded via `webapp-testing` / `agent-browser` per `.claude/rules/ui-design.md`.
+   A green `tsc` is NOT proof the UI works.
+
+---
+
+## Goal
+
+**Backend (additive, no migration):**
+- `GET /analytics/timeseries` — daily / weekly / monthly / quarterly aggregated
+  sales (`total_revenue`, `total_units`, `total_transactions` + derived
+  averages), filterable by `store_id` / `product_id` / `category`, ordered by
+  period ascending.
+- `GET /dimensions/stores` and `GET /dimensions/products` gain optional
+  `sort_by` + `sort_order` params (allow-listed columns; unknown → default
+  order, never an error).
+
+**Frontend:**
+- Two new routes — `/explorer/stores/:storeId` and `/explorer/products/:productId`
+  — reached by clicking a Stores/Products row. Each: entity profile card, a
+  `DateRangePicker`, four `KPICard`s, a revenue-over-time `TimeSeriesChart`, a
+  top-contributors drilldown, and a "View in Sales" link. Product detail also
+  shows the existing `/dimensions/products/{id}/lifecycle-curve`.
+- Stores / Products / Runs tables gain CSV export + column-visibility toggles;
+  Stores / Products additionally gain server-side column sorting and row-click
+  navigation.
+- The Sales page gains a revenue-by-dimension bar chart + a revenue-over-time
+  line chart, and reads `store_id` / `product_id` from the URL for cross-filtering.
+- Filter / date / dimension state on Sales / Stores / Products persists in the
+  URL query string (`useSearchParams`).
+
+## Why
+- **Portfolio identity.** `.claude/rules/product-vision.md` principle 1 —
+  "portfolio-grade, end-to-end … every phase ships working code". The analytics
+  layer (`/analytics/kpis`, `/analytics/drilldowns`) and the dimension catalog
+  are fully built but the dashboard exposes them as flat tables — a reviewer
+  cannot *explore* a single store or product without leaving the UI.
+- **Analyst workflow.** "Why is revenue moving" is the core question; today it
+  is unanswerable in-product. Detail views + charts + cross-filtering make the
+  Explorer a genuine investigation surface.
+- **High value per line.** Almost everything is composition of shipped endpoints
+  and shipped components; the only new server code is one read-only aggregate
+  query and two query params.
+
+## What
+Backend-touching but additive. One new route + service method + two schemas on
+the `analytics` slice; two query params + allow-listed ordering on the
+`dimensions` slice; integration tests for both (the `analytics` slice has **no
+test files today** — this PRP also closes that gap). Frontend: 2 new pages, 2
+new routes, ~6 new hooks/components/utils, 4 existing pages upgraded, new TS
+types. No migration, no new env var, no new slice.
+
+### Success Criteria
+- [ ] `GET /analytics/timeseries?start_date=…&end_date=…&granularity=day|week|month|quarter`
+      returns period-ascending aggregated points; honors `store_id` /
+      `product_id` / `category` filters; reuses `validate_date_range` so an
+      inverted range and an over-730-day range both 400 with RFC 7807.
+- [ ] `GET /dimensions/stores` and `/dimensions/products` accept `sort_by` +
+      `sort_order`; omitting them preserves the current default order
+      (`Store.code` / `Product.sku`); an unknown `sort_by` falls back to the
+      default order without erroring.
+- [ ] Clicking a Stores/Products row navigates to a working
+      `/explorer/stores/:id` / `/explorer/products/:id` page with profile,
+      date-scoped KPIs, a revenue-over-time chart, and a top-contributors list.
+- [ ] Stores & Products tables support server-side column sorting, CSV export,
+      and column-visibility toggles; Runs supports export + column visibility.
+- [ ] The Sales page shows a revenue-by-dimension bar chart + a revenue-over-time
+      line chart in addition to the ranked list, and applies `?store_id` /
+      `?product_id` from the URL.
+- [ ] Filter / date / dimension state round-trips through the URL (paste a
+      filtered URL into a fresh tab → identical view); "View in Sales" carries
+      the entity filter.
+- [ ] `uv run ruff check . && uv run ruff format --check . && uv run mypy app/ &&
+      uv run pyright app/` clean; `uv run pytest -v -m "not integration"` and
+      `-m integration` for the `analytics` + `dimensions` slices green.
+- [ ] `cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run` clean
+      (incl. the new `csv-export.test.ts`).
+- [ ] No Alembic migration; no new slice; no `app/main.py` change; no `.env` var.
+- [ ] Both detail pages + the upgraded Sales page dogfooded in a real browser
+      (screenshots captured).
+
+---
+
+## All Needed Context
+
+### Documentation & References
+```yaml
+# ---- External docs ----
+- url: https://tanstack.com/query/latest/docs/framework/react/guides/queries
+  why: useQuery shape for the new GET hooks (timeseries, lifecycle-curve)
+  critical: GET data → useQuery({ queryKey, queryFn, enabled }). The repo's
+    hooks (use-drilldowns.ts, use-kpis.ts) follow this exactly — copy that shape.
+
+- url: https://tanstack.com/table/v8/docs/guide/sorting#manual-server-side-sorting
+  why: DataTable already sets `manualSorting: true` — this section shows how
+    SortingState (`[{id, desc}]`) maps to server-side sort params.
+  critical: With manualSorting, sorting MUST round-trip through the backend
+    `sort_by`/`sort_order`; a client-only sort would only reorder the visible page.
+
+- url: https://tanstack.com/table/v8/docs/guide/column-visibility
+  why: column-visibility dropdown — `columnVisibility` state,
+    `onColumnVisibilityChange`, `column.getCanHide()`, `column.toggleVisibility()`.
+
+- url: https://reactrouter.com/6.30.1/hooks/use-params
+  why: `/explorer/stores/:storeId` dynamic-segment extraction.
+  critical: `useParams()` returns `Record<string,string|undefined>` — the id is
+    a STRING and may be undefined; parse with Number() and guard Number.isNaN.
+
+- url: https://reactrouter.com/6.30.1/hooks/use-search-params
+  why: URL filter persistence + cross-filtering (Sales reads ?store_id).
+  critical: `useSearchParams()` → `[params, setParams]`; `params.get('x')` is
+    `string | null`. Treat it like controlled state initialised from the URL.
+
+- url: https://recharts.org/en-US/api/BarChart
+  why: the new RevenueBarChart. Prefer mirroring backtest-folds-chart.tsx
+    (already in the repo) over raw Recharts.
+
+- url: https://www.postgresql.org/docs/16/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC
+  why: Postgres `date_trunc(field, source)` — `field` ∈ {day,week,month,quarter};
+    all four TimeGranularity values are valid field strings.
+
+- url: https://docs.sqlalchemy.org/en/20/core/sqlelement.html#sqlalchemy.sql.expression.cast
+  why: `cast(expr, Date)` to coerce the date_trunc timestamp back to a DATE so
+    TimeSeriesPoint.period (a `date`) validates.
+
+# ---- Backend: the pattern to mirror ----
+- file: app/features/analytics/routes.py
+  why: THE route pattern. `validate_date_range` (lines 32-57) — reuse verbatim,
+    it also enforces the 730-day cap via settings.analytics_max_date_range_days.
+    `get_kpis` (lines 65-147) is the route shape to copy for `get_timeseries`.
+  critical: The `analytics` router is already included in app/main.py — the new
+    route attaches to the existing `router` object; do NOT touch app/main.py.
+
+- file: app/features/analytics/service.py
+  why: `compute_kpis` (lines 39-116) is the closest aggregation: coalesced sums,
+    inclusive date `where`, optional store/product filters, the `category`
+    `.join(Product, …)`. `compute_drilldown` (lines 199-209) shows group_by/order_by.
+  critical: |
+    NAME COLLISION — service.py already does `from typing import Any, cast`
+    (line 8) and uses `cast(ColumnElement[Any], Store.code)`. SQLAlchemy ALSO
+    exports `cast`. You MUST import the SQLAlchemy one aliased:
+    `from sqlalchemy import Date` and `from sqlalchemy import cast as sa_cast`.
+    Then `sa_cast(func.date_trunc(granularity.value, SalesDaily.date), Date)`.
+    Importing plain `cast` from sqlalchemy would shadow typing.cast and break
+    the existing drilldown code + the strict type-check.
+
+- file: app/features/analytics/schemas.py
+  why: `KPIMetrics` (lines 48-80) — REUSE for per-period metrics. `TimeGranularity`
+    enum (lines 18-28: day/week/month/quarter, str-Enum) ALREADY EXISTS — REUSE
+    it for the `granularity` param. `KPIResponse` (lines 83-112) is the
+    response-envelope pattern; `DrilldownItem` (lines 120-152) shows `from_attributes`.
+
+- file: app/features/analytics/tests/conftest.py
+  why: currently holds ONLY unit fixtures (Pydantic objects, no DB). The slice
+    has NO test_*.py at all — see "Testing gap" gotcha.
+
+- file: app/features/dimensions/routes.py
+  why: stores-list handler (lines 33-92) + products-list handler (lines 144-203)
+    — add `sort_by`/`sort_order` `Query` params here, mirroring the existing
+    `region`/`store_type`/`category` params.
+
+- file: app/features/dimensions/service.py
+  why: `list_stores` (lines 35-100) + `list_products` (lines 148-213) — current
+    default order is `stmt.order_by(Store.code)` (line 81) and
+    `stmt.order_by(Product.sku)` (line 194). Add allow-listed sorting here.
+    `get_product_lifecycle_curve` (lines 261-343) backs the product detail page.
+
+- file: app/features/dimensions/schemas.py
+  why: `StoreResponse`/`ProductResponse` field names (the sort allow-list keys);
+    `LifecycleCurveResponse` (lines 208-234): product_id, sku, launch_date,
+    discontinue_date, start_date, end_date, points:[{date,stage,multiplier}],
+    total — mirror field-for-field into types/api.ts.
+
+- file: app/features/backtesting/tests/conftest.py
+  why: THE integration-test DB fixture set to COPY. `db_session`, `client`
+    (with `app.dependency_overrides[get_db]`), `sample_store`, `sample_product`,
+    `sample_calendar_120`, `sample_sales_120` (2024-01-01..2024-04-29, qty 1..120).
+  critical: test rows use `TEST-<uuid8>` code/sku prefixes; the conftest cleanup
+    deletes `SalesDaily` + `Product/Store LIKE 'TEST-%'` + the test calendar range.
+
+- file: app/features/backtesting/tests/test_routes_integration.py
+  why: the `@pytest.mark.integration` + `@pytest.mark.asyncio` class style,
+    `AsyncClient` POST/GET, `response.json()` assertions (lines 1-67).
+
+- file: app/core/config.py
+  why: `analytics_max_date_range_days: int = 730` (line 115) — `validate_date_range`
+    already enforces it; reusing that helper means the new endpoint inherits the cap.
+
+# ---- Frontend: the pattern to mirror ----
+- file: frontend/src/pages/explorer/sales.tsx
+  why: current Sales page (DateRangePicker + Tabs + useDrilldowns + error/loading
+    scaffold). Charts + URL state are added here.
+
+- file: frontend/src/pages/explorer/stores.tsx  &  products.tsx
+  why: current table pages — pagination + DataTableToolbar + DataTable. Row-click,
+    sorting, export, column visibility, URL state are added here.
+
+- file: frontend/src/pages/explorer/runs.tsx
+  why: a third DataTable page — gets export + column visibility (no detail page,
+    no server sort in scope).
+
+- file: frontend/src/pages/dashboard.tsx
+  why: reference for the KPICard grid layout used on the new detail pages.
+
+- file: frontend/src/components/data-table/data-table.tsx
+  why: `manualSorting: true` is already set; `sorting`/`onSortingChange` props
+    exist but are unused by pages. Add an optional `onRowClick` + an optional
+    `enableColumnVisibility` (internal columnVisibility state). KEEP every change
+    additive so runs.tsx and other callers still compile.
+
+- file: frontend/src/components/data-table/data-table-pagination.tsx
+  why: a page-size selector ALREADY EXISTS here (`pageSizeOptions=[10,25,50,100]`).
+    Do NOT re-implement page size.
+
+- file: frontend/src/components/data-table/data-table-toolbar.tsx
+  why: search + select filters + reset. Export/view-options buttons sit alongside it.
+
+- file: frontend/src/components/charts/time-series-chart.tsx
+  why: REUSE for revenue-over-time. Props: `data:{date,actual?,predicted?}[]`,
+    `actualKey`, `showPredicted`. Feed revenue as `actual`, pass `showPredicted={false}`.
+  critical: the Line's legend label is hardcoded "Actual" — acceptable here
+    (the series IS actual historical revenue). The `--chart-N` CSS vars are full
+    oklch() — reference them directly, never wrap in hsl() (see file comment l.42-43).
+
+- file: frontend/src/components/charts/backtest-folds-chart.tsx
+  why: the Recharts `BarChart` + `ChartContainer` pattern to mirror for RevenueBarChart.
+
+- file: frontend/src/components/charts/kpi-card.tsx
+  why: REUSE on the detail pages. Props: title, value, description?, icon?, isLoading?.
+
+- file: frontend/src/components/ui/dropdown-menu.tsx
+  why: exports `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
+    `DropdownMenuCheckboxItem`, `DropdownMenuLabel`, `DropdownMenuSeparator` —
+    everything DataTableViewOptions needs.
+
+- file: frontend/src/lib/api.ts
+  why: `api<T>(endpoint,{params})` client (drops undefined/null/'' params),
+    `formatCurrency`/`formatNumber`/`formatPercent`, `ApiError`, `getErrorMessage`.
+
+- file: frontend/src/lib/date-utils.ts
+  why: `dateRangeToStrings` / `stringsToDateRange` for DateRange ↔ API string.
+
+- file: frontend/src/lib/constants.ts
+  why: `ROUTES` (EXPLORER block lines 5-11) + `NAV_ITEMS`. Add 2 detail routes to
+    ROUTES.EXPLORER. Do NOT add them to NAV_ITEMS (reached by click-through).
+
+- file: frontend/src/App.tsx
+  why: lazy-route registration (lines 13-19 imports, 52-91 Explorer routes).
+    Add 2 lazy imports + 2 `<Route>`s with dynamic `:storeId`/`:productId`.
+
+- file: frontend/src/hooks/use-drilldowns.ts
+  why: THE hook template — useQuery + queryKey array + keepPreviousData + enabled.
+
+- file: frontend/src/hooks/use-stores.ts  &  use-products.ts
+  why: paginated list hooks + the existing `useStore(id)` / `useProduct(id)`
+    detail hooks (reused by the detail pages). Extend the list hooks with
+    `sortBy`/`sortOrder`.
+
+- file: frontend/src/hooks/use-kpis.ts
+  why: `useKPIs({startDate,endDate,storeId,productId,category})` — reused on the
+    detail pages as-is.
+
+- file: frontend/src/hooks/index.ts
+  why: barrel re-export — add `use-timeseries` and `use-lifecycle-curve` lines.
+
+- file: frontend/src/components/data-table/index.ts  &  components/charts/index.ts
+  why: barrels — add the new view-options/column-header + revenue-bar-chart exports.
+
+- file: frontend/src/types/api.ts
+  why: `Store`, `Product`, `KPIMetrics`, `KPIResponse`, `DrilldownResponse`,
+    `DrilldownDimension`, `PaginatedResponse<T>` (lines 1-76). Add the new
+    time-series + lifecycle types here.
+
+- file: frontend/src/lib/knowledge-utils.ts  &  knowledge-utils.test.ts
+  why: precedent for a pure `lib/*.ts` helper + its colocated vitest — the model
+    for `csv-export.ts` + `csv-export.test.ts`.
+
+- file: frontend/src/hooks/use-demo-pipeline.test.ts
+  why: vitest structure (describe/it/expect) for the csv-export test.
+
+- file: PRPs/PRP-19-knowledge-and-agent-guide-pages.md
+  why: the most recent "add pages + small additive backend change" PRP — the
+    frontend registration pattern (constants + App.tsx + lazy route) is identical.
+
+# ---- Rules ----
+- file: .claude/rules/ui-design.md
+  why: UI built/dogfooded via frontend-design + shadcn-ui + webapp-testing.
+- file: .claude/rules/security-patterns.md
+  why: "Allow-lists over deny-lists" — the sort_by param MUST resolve through an
+    allow-list dict to a real mapped column, never interpolate the raw string.
+- file: .claude/rules/test-requirements.md
+  why: new endpoint → route test (2xx + 1 error path); new param → test;
+    new pure util → vitest. Integration tests use real Postgres, never mocked.
+- file: .claude/rules/commit-format.md  &  branch-naming.md
+  why: `type(scope): description (#issue)`; scopes `analytics`/`dimensions`/`ui`/
+    `api`/`docs`; branch `feat/explorer-interactivity` off `dev`; open the issue FIRST.
+```
+
+### Current Codebase tree (relevant)
+```bash
+app/features/
+├── analytics/
+│   ├── routes.py            # MOD — +GET /analytics/timeseries
+│   ├── service.py           # MOD — +compute_timeseries
+│   ├── schemas.py           # MOD — +TimeSeriesPoint/TimeSeriesResponse
+│   └── tests/
+│       ├── conftest.py      # MOD — +DB fixtures (copied from backtesting)
+│       ├── test_schemas.py            # NEW
+│       └── test_routes_integration.py # NEW
+└── dimensions/
+    ├── routes.py            # MOD — +sort_by/sort_order on stores+products lists
+    ├── service.py           # MOD — allow-listed ordering in list_stores/list_products
+    └── tests/
+        ├── conftest.py      # MOD — +DB fixtures + multi-row fixtures
+        └── test_sort.py     # NEW
+
+frontend/src/
+├── App.tsx                  # MOD — +2 lazy detail routes
+├── lib/
+│   ├── constants.ts         # MOD — +ROUTES.EXPLORER.STORE_DETAIL/PRODUCT_DETAIL
+│   ├── csv-export.ts        # NEW — pure CSV util + downloadCsv
+│   └── csv-export.test.ts   # NEW — vitest
+├── types/api.ts             # MOD — +TimeGranularity/TimeSeries*/LifecycleCurveResponse
+├── hooks/
+│   ├── index.ts             # MOD — +2 barrel lines
+│   ├── use-stores.ts        # MOD — +sortBy/sortOrder
+│   ├── use-products.ts      # MOD — +sortBy/sortOrder
+│   ├── use-timeseries.ts    # NEW
+│   └── use-lifecycle-curve.ts # NEW
+├── components/
+│   ├── data-table/
+│   │   ├── data-table.tsx              # MOD — +onRowClick, +enableColumnVisibility
+│   │   ├── data-table-view-options.tsx # NEW — column-visibility dropdown
+│   │   ├── data-table-column-header.tsx# NEW — sortable header button
+│   │   └── index.ts                    # MOD — +2 barrel lines
+│   └── charts/
+│       ├── revenue-bar-chart.tsx       # NEW
+│       └── index.ts                    # MOD — +1 barrel line
+└── pages/explorer/
+    ├── sales.tsx            # MOD — +charts, +URL state, +cross-filter
+    ├── stores.tsx           # MOD — +row-click, +sorting, +export, +view-options, +URL state
+    ├── products.tsx         # MOD — same as stores
+    ├── runs.tsx             # MOD — +export, +view-options
+    ├── store-detail.tsx     # NEW
+    └── product-detail.tsx   # NEW
+```
+
+### Desired Codebase tree (files added / changed)
+```bash
+NEW  app/features/analytics/tests/test_schemas.py            # unit — new schemas
+NEW  app/features/analytics/tests/test_routes_integration.py # integration — /timeseries (+ kpis/drilldowns smoke)
+NEW  app/features/dimensions/tests/test_sort.py              # integration — sort params
+NEW  frontend/src/hooks/use-timeseries.ts                    # GET /analytics/timeseries
+NEW  frontend/src/hooks/use-lifecycle-curve.ts               # GET /dimensions/products/{id}/lifecycle-curve
+NEW  frontend/src/components/charts/revenue-bar-chart.tsx    # revenue-by-dimension bar chart
+NEW  frontend/src/components/data-table/data-table-view-options.tsx   # column-visibility dropdown
+NEW  frontend/src/components/data-table/data-table-column-header.tsx  # sortable header button
+NEW  frontend/src/lib/csv-export.ts                          # pure toCsv + downloadCsv
+NEW  frontend/src/lib/csv-export.test.ts                     # vitest — toCsv coverage
+NEW  frontend/src/pages/explorer/store-detail.tsx            # store detail route page
+NEW  frontend/src/pages/explorer/product-detail.tsx          # product detail route page
+MOD  app/features/analytics/{routes,service,schemas}.py      # +timeseries endpoint
+MOD  app/features/analytics/tests/conftest.py                # +DB fixtures
+MOD  app/features/dimensions/{routes,service}.py             # +sort_by/sort_order
+MOD  app/features/dimensions/tests/conftest.py               # +DB + multi-row fixtures
+MOD  frontend/src/types/api.ts                               # +TimeGranularity/TimeSeries*/LifecycleCurveResponse
+MOD  frontend/src/hooks/{use-stores,use-products,index}.ts   # +sort params, +barrel
+MOD  frontend/src/components/data-table/{data-table,index}.ts(x)  # +onRowClick/+visibility
+MOD  frontend/src/components/charts/index.ts                 # +revenue-bar-chart export
+MOD  frontend/src/lib/constants.ts                           # +2 detail routes
+MOD  frontend/src/App.tsx                                    # +2 lazy routes
+MOD  frontend/src/pages/explorer/{sales,stores,products,runs}.tsx  # interactive upgrades
+MOD  README.md                                               # feature list
+MOD  docs/_base/API_CONTRACTS.md                             # +/analytics/timeseries row, +sort params
+MOD  docs/_base/REPO_MAP_INDEX.md                            # +store-detail/product-detail rows
+KEEP app/main.py                                             # UNCHANGED — analytics router already wired
+KEEP alembic/**                                              # UNCHANGED — NO migration (read-only queries)
+```
+
+### Known Gotchas & Library Quirks
+```python
+# CRITICAL: `cast` NAME COLLISION in analytics/service.py. The file already does
+#   `from typing import Any, cast` and uses typing.cast for drilldown columns.
+#   SQLAlchemy also exports `cast`. Import the SQLAlchemy one ALIASED:
+#       from sqlalchemy import Date
+#       from sqlalchemy import cast as sa_cast
+#   Use `sa_cast(func.date_trunc(granularity.value, SalesDaily.date), Date)`.
+#   A plain `from sqlalchemy import cast` would shadow typing.cast and break the
+#   existing code AND the strict type-check.
+
+# CRITICAL: `func.date_trunc` is untyped. Under mypy --strict / pyright --strict
+#   annotate the bucket column explicitly — `bucket: ColumnElement[Any]` (mirror
+#   `dimension_col: ColumnElement[Any]` at service.py:143). For granularity=DAY
+#   use the raw `SalesDaily.date` column (no date_trunc needed); only week/month/
+#   quarter need date_trunc + sa_cast.
+
+# CRITICAL: NO Alembic migration. Every new query is a read aggregate over
+#   existing tables (sales_daily, store, product). Adding a migration would be
+#   wrong. `.claude/rules` only require a migration when the SCHEMA changes.
+
+# CRITICAL: TESTING GAP — the `analytics` slice has NO test files (only
+#   tests/conftest.py with unit fixtures). The `dimensions` tests/conftest.py
+#   has only dict fixtures. Neither has a DB session/client fixture. Task 4 must
+#   COPY db_session/client/sample_store/sample_product/sample_calendar_120/
+#   sample_sales_120 from app/features/backtesting/tests/conftest.py. Budget time.
+
+# CRITICAL: sort_by is user input. Resolve it through an explicit allow-list
+#   dict {str: mapped_column} → a real SQLAlchemy column. NEVER interpolate the
+#   raw string into the query (security-patterns.md). Unknown sort_by → fall
+#   back to the current default order; do NOT 400 (keeps it backward-compatible
+#   and avoids 500s from stale frontend state).
+
+# CRITICAL: DataTable has `manualSorting: true`. Server-side sort is mandatory —
+#   thread SortingState → sort_by/sort_order → useStores/useProducts. A
+#   client-only sort would silently reorder only the current page.
+
+# GOTCHA: money fields serialize to JSON STRINGS (Decimal). `KPIMetrics.total_revenue`
+#   is `string` in types/api.ts. ALWAYS `Number(x)` before feeding Recharts.
+
+# GOTCHA: data-table-pagination.tsx ALREADY has a page-size selector
+#   (pageSizeOptions=[10,25,50,100]). Do NOT add another one.
+
+# GOTCHA: every change to DataTableProps must be ADDITIVE & optional — runs.tsx
+#   and any other DataTable caller must compile unchanged.
+
+# GOTCHA: useParams() returns string|undefined. Parse the :storeId/:productId
+#   with Number() and guard Number.isNaN → render a not-found ErrorDisplay state.
+
+# GOTCHA: the lifecycle-curve endpoint is NEVER empty — for a product with no
+#   launch_date it returns a flat curve at multiplier 1.0 (service.py:300-301),
+#   `points` always has ≥1 entry. Handle the "flat" curve gracefully; there is
+#   no "empty points" case to special-case.
+
+# GOTCHA: TimeSeriesChart hardcodes the Line name "Actual" and `--chart-N` are
+#   full oklch() vars — reference directly, never hsl() (file comment l.42-43).
+
+# GOTCHA: new .tsx/.ts files are LF. Editing existing .py files preserves their
+#   CRLF (repo .py files are CRLF, no .gitattributes — see project memory).
+#   For the 3 NEW .py test files, after writing run `git diff --stat` and
+#   confirm no whole-file EOL churn slipped into the diff.
+
+# GOTCHA: the `analytics` router is already in app/main.py. Do NOT edit main.py —
+#   the new route attaches to the existing `router` object in analytics/routes.py.
+
+# GOTCHA: every commit references the open tracking issue (commit-format.md);
+#   NO AI co-author trailer, ever. Branch off `dev`.
+```
+
+### Resolved Decisions (user-confirmed 2026-05-18)
+```yaml
+interactivity-scope:
+  decision: all four directions ship — click-through detail views, richer
+    tables, charts on Sales, and cross-filtering.
+  status: confirmed (AskUserQuestion, multi-select all four).
+timeseries-data-source:
+  decision: add a backend endpoint `GET /analytics/timeseries` for the
+    per-store/per-product daily series rather than reusing
+    /analytics/drilldowns?dimension=date.
+  why: drilldowns caps at max_items=100, orders by revenue (not date), and has
+    no week/month bucketing. A dedicated endpoint is cleaner, cheap (read-only,
+    indexed on ix_sales_daily_date_store / ix_sales_daily_date_product), and
+    reuses KPIMetrics + TimeGranularity.
+  status: confirmed (user chose "Add a backend endpoint (Recommended)").
+detail-ux:
+  decision: entity detail views are dedicated React Router route pages
+    (/explorer/stores/:storeId, /explorer/products/:productId), NOT a Sheet or
+    Dialog — they are deep-linkable and enable the cross-filtering "View in
+    Sales" link.
+  status: confirmed (user chose "Dedicated route page").
+```
+
+---
+
+## Implementation Blueprint
+
+### Backend data models (`app/features/analytics/schemas.py`, append after `DrilldownResponse`)
+```python
+# REUSE the existing KPIMetrics + TimeGranularity from this file — do NOT redefine.
+# These are RESPONSE models — do NOT add ConfigDict(strict=True) (the strict-mode
+# policy / AST linter only governs request bodies). Every Field needs a description.
+
+class TimeSeriesPoint(BaseModel):
+    """One aggregated period of the sales time series."""
+    model_config = ConfigDict(from_attributes=True)
+    period: date = Field(..., description="Bucket start date (day, or first day of week/month/quarter).")
+    metrics: KPIMetrics = Field(..., description="Aggregated KPI metrics for this period.")
+
+class TimeSeriesResponse(BaseModel):
+    """Period-bucketed sales time series for charting."""
+    granularity: TimeGranularity = Field(..., description="Bucket size used for aggregation.")
+    points: list[TimeSeriesPoint] = Field(..., description="Points in ascending period order.")
+    total_points: int = Field(..., ge=0, description="Number of points returned.")
+    start_date: date = Field(..., description="Start of the analysis period (inclusive).")
+    end_date: date = Field(..., description="End of the analysis period (inclusive).")
+    store_id: int | None = Field(None, description="Store filter applied (if any).")
+    product_id: int | None = Field(None, description="Product filter applied (if any).")
+    category: str | None = Field(None, description="Category filter applied (if any).")
+```
+
+### Backend service (`app/features/analytics/service.py`, new method on `AnalyticsService`)
+```python
+# IMPORTS to add: `from sqlalchemy import Date` ; `from sqlalchemy import cast as sa_cast`
+# and TimeGranularity/TimeSeriesPoint/TimeSeriesResponse to the schemas import block.
+
+async def compute_timeseries(self, db, start_date, end_date,
+                              granularity=TimeGranularity.DAY,
+                              store_id=None, product_id=None, category=None) -> TimeSeriesResponse:
+    # PATTERN: bucket expression. DAY → raw date column; coarser → date_trunc.
+    bucket: ColumnElement[Any]
+    if granularity == TimeGranularity.DAY:
+        bucket = SalesDaily.date
+    else:
+        bucket = sa_cast(func.date_trunc(granularity.value, SalesDaily.date), Date)
+
+    # PATTERN: identical aggregation/filters to compute_kpis (service.py:62-76)
+    stmt = select(
+        bucket.label("period"),
+        func.coalesce(func.sum(SalesDaily.total_amount), 0).label("total_revenue"),
+        func.coalesce(func.sum(SalesDaily.quantity), 0).label("total_units"),
+        func.count().label("total_transactions"),
+    ).where((SalesDaily.date >= start_date) & (SalesDaily.date <= end_date))
+    if store_id is not None:   stmt = stmt.where(SalesDaily.store_id == store_id)
+    if product_id is not None: stmt = stmt.where(SalesDaily.product_id == product_id)
+    if category is not None:
+        stmt = stmt.join(Product, SalesDaily.product_id == Product.id).where(Product.category == category)
+    stmt = stmt.group_by(bucket).order_by(bucket)
+
+    rows = (await db.execute(stmt)).all()
+    points: list[TimeSeriesPoint] = []
+    for row in rows:
+        revenue = Decimal(str(row.total_revenue)); units = int(row.total_units)
+        txns = int(row.total_transactions)
+        points.append(TimeSeriesPoint(period=row.period, metrics=KPIMetrics(
+            total_revenue=revenue, total_units=units, total_transactions=txns,
+            avg_unit_price=(revenue / units if units > 0 else None),
+            avg_basket_value=(revenue / txns if txns > 0 else None))))
+    logger.info("analytics.timeseries_computed", granularity=granularity.value,
+                start_date=str(start_date), end_date=str(end_date),
+                store_id=store_id, product_id=product_id, points=len(points))
+    return TimeSeriesResponse(granularity=granularity, points=points,
+                              total_points=len(points), start_date=start_date,
+                              end_date=end_date, store_id=store_id,
+                              product_id=product_id, category=category)
+```
+
+### Backend route (`app/features/analytics/routes.py`, new `@router.get("/timeseries")`)
+```python
+# Mirror get_kpis (lines 65-147): rich description=, Query(...) params, reuse
+# validate_date_range(start_date, end_date), then AnalyticsService().compute_timeseries(...).
+# granularity: TimeGranularity = Query(TimeGranularity.DAY, description="Bucket size: day|week|month|quarter.")
+```
+
+### Backend sort params (`app/features/dimensions/`)
+```python
+# routes.py — add to BOTH list handlers:
+#   sort_by:  str | None = Query(None, description="Sort column. Stores: code|name|region|city|store_type.")
+#   sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort direction.")
+# service.py — list_stores / list_products:
+_STORE_SORT = {"code": Store.code, "name": Store.name, "region": Store.region,
+               "city": Store.city, "store_type": Store.store_type}
+column = _STORE_SORT.get(sort_by) if sort_by else None
+if column is not None:
+    stmt = stmt.order_by(column.desc() if sort_order == "desc" else column.asc())
+else:
+    stmt = stmt.order_by(Store.code)   # UNCHANGED default — keeps existing tests green
+# Products allow-list: sku|name|category|brand|base_price ; default order Product.sku.
+```
+
+### Frontend types (`frontend/src/types/api.ts`, append near the `// === Analytics ===` block)
+```typescript
+export type TimeGranularity = 'day' | 'week' | 'month' | 'quarter'
+export interface TimeSeriesPoint { period: string; metrics: KPIMetrics }
+export interface TimeSeriesResponse {
+  granularity: TimeGranularity
+  points: TimeSeriesPoint[]
+  total_points: number
+  start_date: string; end_date: string
+  store_id: number | null; product_id: number | null; category: string | null
+}
+// Mirror app/features/dimensions/schemas.py LifecycleCurveResponse (lines 208-234):
+export interface LifecyclePoint { date: string; stage: string; multiplier: number }
+export interface LifecycleCurveResponse {
+  product_id: number; sku: string
+  launch_date: string | null; discontinue_date: string | null
+  start_date: string; end_date: string
+  points: LifecyclePoint[]; total: number
+}
+```
+
+### Frontend hooks (`use-timeseries.ts`, `use-lifecycle-curve.ts` — mirror use-drilldowns.ts)
+```typescript
+// use-timeseries.ts
+export function useTimeseries({ startDate, endDate, granularity = 'day',
+  storeId, productId, category, enabled = true }: UseTimeseriesParams) {
+  return useQuery({
+    queryKey: ['timeseries', { startDate, endDate, granularity, storeId, productId, category }],
+    queryFn: () => api<TimeSeriesResponse>('/analytics/timeseries', { params: {
+      start_date: startDate, end_date: endDate, granularity,
+      store_id: storeId, product_id: productId, category } }),
+    placeholderData: keepPreviousData,
+    enabled: enabled && !!startDate && !!endDate,
+  })
+}
+// use-lifecycle-curve.ts
+export function useLifecycleCurve(productId: number,
+  { startDate, endDate, enabled = true }: UseLifecycleCurveParams = {}) {
+  return useQuery({
+    queryKey: ['lifecycle-curve', productId, { startDate, endDate }],
+    queryFn: () => api<LifecycleCurveResponse>(
+      `/dimensions/products/${productId}/lifecycle-curve`,
+      { params: { start_date: startDate, end_date: endDate } }),
+    enabled: enabled && productId > 0,
+  })
+}
+```
+
+### Detail page layout (`store-detail.tsx`; `product-detail.tsx` is the symmetric twin)
+```text
+export default function StoreDetailPage()
+- const { storeId } = useParams(); const id = Number(storeId); guard Number.isNaN → ErrorDisplay.
+- Header: "Back to Stores" Link + <h1>{store.name}</h1>; profile Card (code/region/city/type) from useStore(id).
+- <DateRangePicker> — default last 30 days (subDays(new Date(),30)..new Date()).
+- 4 <KPICard>s from useKPIs({ storeId:id, startDate, endDate }) — revenue/units/transactions/avg basket.
+- <TimeSeriesChart title="Revenue over time" data={points.map(p => ({date:p.period, actual:Number(p.metrics.total_revenue)}))} showPredicted={false}/>
+  from useTimeseries({ storeId:id, startDate, endDate, granularity:'day' }).
+- "Top products" — useDrilldowns({ dimension:'product', storeId:id, startDate, endDate }) → list or <RevenueBarChart>.
+- "View in Sales" <Link to={`/explorer/sales?store_id=${id}`}>.
+- Reuse LoadingState / ErrorDisplay; build with frontend-design + shadcn-ui.
+
+product-detail.tsx delta: useProduct(id); useKPIs/useTimeseries with productId;
+useDrilldowns({ dimension:'store', productId:id }) for "Top stores"; PLUS
+useLifecycleCurve(id) → <TimeSeriesChart title="Lifecycle demand curve"
+data={points.map(p=>({date:p.date, actual:p.multiplier}))} showPredicted={false}/>.
+"View in Sales" → /explorer/sales?product_id=${id}.
+```
+
+### list of tasks (in execution order)
+```yaml
+Task 1 — Tracking GitHub issue:
+  - Open ONE issue: "Explorer interactivity: detail views, richer tables, Sales
+    charts, cross-filtering". Note it spans analytics + dimensions + ui scopes.
+  - Confirm: `gh issue view <N> --json state`. Every commit below references (#N).
+  - Branch: `git switch -c feat/explorer-interactivity` off an up-to-date dev.
+
+Task 2 — Backend: /analytics/timeseries endpoint:
+  MODIFY app/features/analytics/schemas.py
+    - Append TimeSeriesPoint + TimeSeriesResponse (see "Backend data models").
+      Reuse KPIMetrics + TimeGranularity; do NOT add strict=True.
+  MODIFY app/features/analytics/service.py
+    - Add `from sqlalchemy import Date` and `from sqlalchemy import cast as sa_cast`.
+    - Add TimeGranularity/TimeSeriesPoint/TimeSeriesResponse to the schemas import.
+    - Add `compute_timeseries` (see "Backend service" pseudocode).
+  MODIFY app/features/analytics/routes.py
+    - Add TimeGranularity/TimeSeriesResponse to the schemas import.
+    - Add `@router.get("/timeseries", response_model=TimeSeriesResponse, ...)`
+      mirroring get_kpis; reuse validate_date_range.
+  VALIDATE: uv run ruff check app/features/analytics/ && uv run mypy app/features/analytics/ &&
+    uv run pyright app/features/analytics/ &&
+    uv run python -c "from app.main import app; assert any('timeseries' in r.path for r in app.routes)"
+
+Task 3 — Backend: dimensions sort params:
+  MODIFY app/features/dimensions/routes.py — add sort_by/sort_order Query params
+    to the stores-list (lines 33-92) and products-list (lines 144-203) handlers;
+    pass them into the service calls.
+  MODIFY app/features/dimensions/service.py — add sort_by/sort_order params to
+    list_stores/list_products; allow-list dict → mapped column; apply .order_by();
+    UNKNOWN/None sort_by keeps the existing default (Store.code / Product.sku).
+  VALIDATE: uv run ruff check app/features/dimensions/ && uv run mypy app/features/dimensions/ &&
+    uv run pyright app/features/dimensions/
+
+Task 4 — Backend: tests (closes the analytics test gap):
+  MODIFY app/features/analytics/tests/conftest.py
+    - Append DB fixtures copied verbatim from app/features/backtesting/tests/
+      conftest.py: db_session, client, sample_store, sample_product,
+      sample_calendar_120, sample_sales_120. Keep the existing unit fixtures.
+  CREATE app/features/analytics/tests/test_schemas.py
+    - Unit: construct TimeSeriesPoint/TimeSeriesResponse; assert total_points>=0,
+      granularity enum coercion. Runs under -m "not integration".
+  CREATE app/features/analytics/tests/test_routes_integration.py
+    - @pytest.mark.integration class: GET /analytics/timeseries 200 for
+      granularity=day and granularity=week against sample_sales_120; assert
+      points ascending by period and len(points)==total_points; test store_id
+      filter; test end_date<start_date → 400. Smoke-test /analytics/kpis +
+      /analytics/drilldowns (slice had none).
+  MODIFY app/features/dimensions/tests/conftest.py
+    - Append the same DB fixtures + a multi-row fixture (e.g. sample_stores_multi
+      / sample_products_multi: 3 rows with TEST-* codes/skus and deliberately
+      non-aligned names so asc-by-code != asc-by-name).
+  CREATE app/features/dimensions/tests/test_sort.py
+    - @pytest.mark.integration: sort_by=name asc/desc correctness on stores +
+      products; unknown sort_by → default order, no error; omitted params ==
+      prior behavior.
+  GOTCHA: new .py files — run `git diff --stat` afterwards, confirm no EOL churn.
+  VALIDATE: uv run pytest -v -m "not integration" app/features/analytics/tests/test_schemas.py
+    then: docker compose up -d && uv run alembic upgrade head &&
+    uv run pytest -v -m integration app/features/analytics/tests app/features/dimensions/tests
+
+Task 5 — Frontend: types + hooks:
+  MODIFY frontend/src/types/api.ts — add TimeGranularity, TimeSeriesPoint,
+    TimeSeriesResponse, LifecyclePoint, LifecycleCurveResponse (see "Frontend types").
+  CREATE frontend/src/hooks/use-timeseries.ts + use-lifecycle-curve.ts (see pseudocode).
+  MODIFY frontend/src/hooks/use-stores.ts + use-products.ts — add optional
+    sortBy?:string / sortOrder?:'asc'|'desc'; thread into queryKey + api params
+    as sort_by/sort_order. Keep optional so existing call sites compile.
+  MODIFY frontend/src/hooks/index.ts — add `export * from './use-timeseries'`
+    and `export * from './use-lifecycle-curve'`.
+  VALIDATE: cd frontend && pnpm tsc --noEmit
+
+Task 6 — Frontend: shared interactive components:
+  MODIFY frontend/src/components/data-table/data-table.tsx
+    - Add optional `onRowClick?: (row: TData) => void`; when set, add
+      onClick + `cursor-pointer` to each data <TableRow> (NOT skeleton/empty rows).
+    - Add optional `enableColumnVisibility?: boolean`; add internal
+      useState<VisibilityState> + onColumnVisibilityChange + state.columnVisibility;
+      when enabled render <DataTableViewOptions table={table}/> above the table.
+    - All additive — runs.tsx and every caller must still compile.
+  CREATE frontend/src/components/data-table/data-table-view-options.tsx
+    - DropdownMenu of DropdownMenuCheckboxItem per table.getAllColumns()
+      .filter(c=>c.getCanHide()), bound to getIsVisible()/toggleVisibility().
+  CREATE frontend/src/components/data-table/data-table-column-header.tsx
+    - <DataTableColumnHeader column title> — a Button that calls
+      column.toggleSorting(); shows an up/down/none chevron from lucide-react.
+  MODIFY frontend/src/components/data-table/index.ts — barrel +2 lines.
+  CREATE frontend/src/components/charts/revenue-bar-chart.tsx
+    - RevenueBarChart({title,description?,data:{label,revenue}[],height?,className?})
+      — Recharts BarChart in ChartContainer/Card; mirror backtest-folds-chart.tsx.
+  MODIFY frontend/src/components/charts/index.ts — barrel +1 line.
+  CREATE frontend/src/lib/csv-export.ts
+    - toCsv<T>(rows, columns:{key,header}[]) : string — RFC-4180 quoting, CRLF rows.
+    - downloadCsv(filename, csv) — Blob + createObjectURL + <a download> + revoke.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 7 — Frontend: routing:
+  MODIFY frontend/src/lib/constants.ts — ROUTES.EXPLORER += STORE_DETAIL:
+    '/explorer/stores/:storeId', PRODUCT_DETAIL: '/explorer/products/:productId'.
+    Do NOT add to NAV_ITEMS.
+  MODIFY frontend/src/App.tsx — 2 lazy imports (StoreDetailPage, ProductDetailPage)
+    + 2 <Route>s wrapped in <Suspense fallback={<PageLoader/>}>, inside <AppShell/>.
+
+Task 8 — Frontend: detail pages:
+  CREATE frontend/src/pages/explorer/store-detail.tsx (see "Detail page layout").
+  CREATE frontend/src/pages/explorer/product-detail.tsx (symmetric twin +
+    useLifecycleCurve). Build with frontend-design + shadcn-ui.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 9 — Frontend: richer Stores + Products tables:
+  MODIFY frontend/src/pages/explorer/stores.tsx
+    - useNavigate(); onRowClick → `/explorer/stores/${s.id}`.
+    - SortingState; pass sorting/onSortingChange to DataTable; derive sortBy/
+      sortOrder from sorting[0] → useStores. Sortable columns use DataTableColumnHeader.
+    - useSearchParams: persist search/region/store_type/page/sort; init state from URL.
+    - "Export CSV" Button (toCsv+downloadCsv on data.stores); enableColumnVisibility.
+    - Reset pageIndex to 0 on sort/filter/search change.
+  MODIFY frontend/src/pages/explorer/products.tsx — same treatment
+    (search/category/brand/page/sort in URL; row-click → /explorer/products/:id).
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 10 — Frontend: Runs table (export + view-options only):
+  MODIFY frontend/src/pages/explorer/runs.tsx — add CSV export + enableColumnVisibility.
+    NO server sort, NO detail route (out of scope for Runs).
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 11 — Frontend: Sales page charts + cross-filtering:
+  MODIFY frontend/src/pages/explorer/sales.tsx
+    - useSearchParams: read store_id/product_id (cross-filter) → pass to
+      useDrilldowns; show a dismissible Badge "Filtered to store/product #N".
+    - Persist dimension + date range in the URL.
+    - <RevenueBarChart> fed by drilldown items ({label:dimension_value,
+      revenue:Number(metrics.total_revenue)}).
+    - <TimeSeriesChart> fed by useTimeseries({startDate,endDate,granularity:'day',
+      storeId,productId}); guard behind data?.points?.length.
+    - Keep the existing ranked list below the charts.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 12 — Frontend test:
+  CREATE frontend/src/lib/csv-export.test.ts — vitest (mirror use-demo-pipeline.test.ts):
+    toCsv empty rows → header-only; quoting/escaping of , " \n; header order.
+    Do NOT test downloadCsv (DOM side-effect).
+  VALIDATE: cd frontend && pnpm lint && pnpm tsc --noEmit && pnpm test --run
+
+Task 13 — Docs:
+  MODIFY README.md — mention store/product detail pages + Sales charts in the
+    feature list.
+  MODIFY docs/_base/API_CONTRACTS.md — add the `GET /analytics/timeseries` row
+    to the HTTP Endpoints table; note the new `/dimensions` sort params.
+  MODIFY docs/_base/REPO_MAP_INDEX.md — add rows for store-detail.tsx /
+    product-detail.tsx.
+
+Task 14 — Dogfood the running UI (mandatory per ui-design.md):
+  - docker compose up -d ; uv run alembic upgrade head ;
+    uv run python scripts/seed_random.py --full-new --seed 42 --confirm.
+  - uv run uvicorn app.main:app --port 8123 & ; cd frontend && pnpm dev.
+  - Via webapp-testing / agent-browser, exercise the 9 scenarios in
+    Validation Level 4 below. Capture screenshots of both detail pages + Sales.
+
+Task 15 — Commit + PR:
+  Branch feat/explorer-interactivity (Task 1). Commits, each (#issue), no AI trailer:
+    1. feat(analytics): add GET /analytics/timeseries aggregated sales endpoint (#N)
+    2. feat(dimensions): add sort_by/sort_order to store + product listings (#N)
+    3. feat(ui): explorer store + product detail pages (#N)
+    4. feat(ui): richer explorer tables — sorting, csv export, column visibility (#N)
+    5. feat(ui): sales charts + url-state cross-filtering (#N)
+    6. test(ui): csv-export pure-helper coverage (#N)
+    7. docs(docs): document the explorer interactivity extension (#N)
+  Open PR into dev; CI green; merge.
+```
+
+### Integration Points
+```yaml
+DATABASE:  NONE — no migration, no schema change. Read aggregates only.
+BACKEND:   analytics slice — +1 route, +1 service method, +2 schemas.
+           dimensions slice — +2 query params, allow-listed ordering.
+           app/main.py UNCHANGED (analytics router already wired).
+CONFIG:    NONE — no new env var. The 730-day cap reuses
+           settings.analytics_max_date_range_days via validate_date_range.
+FRONTEND ROUTING:
+  - ROUTES.EXPLORER.STORE_DETAIL + PRODUCT_DETAIL (constants.ts).
+  - Two lazy dynamic <Route>s in App.tsx (:storeId / :productId).
+  - NAV_ITEMS unchanged (detail pages are click-through, not nav items).
+CI:
+  - No new workflow. ci.yml covers it. Because analytics + dimensions .py files
+    change, the ruff/mypy/pyright/pytest jobs are load-bearing — keep green.
+```
+
+---
+
+## Validation Loop
+
+### Level 1: Syntax & Style
+```bash
+uv run ruff check . && uv run ruff format --check .
+cd frontend && pnpm lint
+# Expected: zero errors. Fix before proceeding.
+```
+
+### Level 2: Type Checks
+```bash
+uv run mypy app/ && uv run pyright app/        # both --strict, both gate merge
+cd frontend && pnpm tsc --noEmit
+# Watch: the sa_cast alias + the ColumnElement[Any] bucket annotation in
+# compute_timeseries are the most likely failures here.
+```
+
+### Level 3: Unit + Integration Tests
+```bash
+uv run pytest -v -m "not integration"          # incl. analytics test_schemas.py
+docker compose up -d && uv run alembic upgrade head
+uv run pytest -v -m integration app/features/analytics/tests app/features/dimensions/tests
+cd frontend && pnpm test --run                 # incl. csv-export.test.ts
+# If integration tests fail on stale local Postgres:
+#   docker compose down -v && docker compose up -d && uv run alembic upgrade head
+```
+
+### Level 4: Manual end-to-end (dogfood — REQUIRED, ui-design.md)
+```bash
+docker compose up -d && uv run alembic upgrade head
+uv run python scripts/seed_random.py --full-new --seed 42 --confirm
+uv run uvicorn app.main:app --port 8123 &
+until curl -fs http://127.0.0.1:8123/health; do sleep 2; done
+cd frontend && ./node_modules/.bin/vite --host 0.0.0.0     # http://localhost:5173
+
+# Browser checks via webapp-testing / agent-browser:
+#  1. /explorer/stores → click a row → /explorer/stores/:id with KPIs + revenue chart + top products.
+#  2. Sort the Stores table by Name desc → order changes ACROSS pages (server-side).
+#  3. Export CSV → file downloads with the visible columns.
+#  4. Toggle a column off via "View" → column hides.
+#  5. /explorer/products/:id → lifecycle curve renders (flat at 1.0 if no launch_date).
+#  6. /explorer/sales → bar chart + line chart render; switch dimension tab → charts update.
+#  7. From a store detail page click "View in Sales" → Sales scoped to that store (badge shown).
+#  8. Apply filters on Stores, copy the URL, open in a new tab → identical filtered view.
+#  9. curl "http://localhost:8123/analytics/timeseries?start_date=2026-04-01&end_date=2026-05-01&granularity=week"
+#     → 200 with ascending points.
+```
+
+---
+
+## Final Validation Checklist
+- [ ] `uv run ruff check . && uv run ruff format --check .` clean
+- [ ] `uv run mypy app/ && uv run pyright app/` clean (both --strict)
+- [ ] `uv run pytest -v -m "not integration"` green (incl. analytics test_schemas.py)
+- [ ] `uv run pytest -v -m integration app/features/analytics/tests app/features/dimensions/tests` green
+- [ ] `cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run` clean
+- [ ] `GET /analytics/timeseries` returns ascending points for day/week/month/quarter,
+      honors store/product/category filters, 400s on inverted/over-cap range
+- [ ] `GET /dimensions/stores|products` accept sort_by/sort_order; omitted == prior
+      behavior; unknown sort_by → default order, no error
+- [ ] Row-click on Stores/Products → working detail pages with KPIs + chart + drilldown
+- [ ] Stores/Products tables: server sorting + CSV export + column visibility; Runs: export + visibility
+- [ ] Sales page shows bar chart + line chart; applies ?store_id/?product_id; URL state round-trips
+- [ ] "View in Sales" carries the entity filter; detail pages dogfooded in a real browser (screenshots)
+- [ ] No Alembic migration; no app/main.py change; no new slice; no .env var
+- [ ] README + API_CONTRACTS.md + REPO_MAP_INDEX.md updated
+- [ ] Branch `feat/explorer-interactivity`; every commit references the Task-1 issue; no AI co-author trailer
+
+---
+
+## Anti-Patterns to Avoid
+- ❌ Don't import `cast` plain from sqlalchemy in analytics/service.py — it
+  shadows the existing `typing.cast`. Alias it: `cast as sa_cast`.
+- ❌ Don't add an Alembic migration — every new query is a read aggregate; the
+  schema does not change.
+- ❌ Don't interpolate `sort_by` into the query — resolve it through an
+  allow-list dict to a real mapped column; unknown → default order, never 400.
+- ❌ Don't reuse `/analytics/drilldowns?dimension=date` for the charts — it caps
+  at 100 items, orders by revenue, and has no week/month bucketing.
+- ❌ Don't do client-only table sorting — DataTable is `manualSorting:true`;
+  sort MUST round-trip to the backend.
+- ❌ Don't re-implement a page-size selector — `data-table-pagination.tsx`
+  already has one.
+- ❌ Don't make `DataTableProps` changes non-optional — every existing caller
+  (runs.tsx etc.) must compile unchanged.
+- ❌ Don't feed string Decimals into Recharts — `Number(x)` first.
+- ❌ Don't edit `app/main.py` — the analytics router is already wired.
+- ❌ Don't hand-roll the pages without `frontend-design` / `shadcn-ui`, and
+  don't claim "done" on a green `tsc` — dogfood in a real browser.
+- ❌ Don't `git push --force` on dev/main; no AI co-author trailers; every
+  commit references the open issue.
+
+---
+
+## Confidence Score
+
+**7 / 10** for one-pass implementation success.
+
+**Why solid:**
+- Almost entirely additive and well-patterned. The new endpoint is a near-clone
+  of `compute_kpis`; the detail pages mirror `sales.tsx` + `dashboard.tsx`; the
+  charts reuse `TimeSeriesChart` and the `backtest-folds-chart.tsx` pattern; the
+  routes register exactly like the existing Explorer routes. No migration, no
+  new slice, no `main.py` change.
+- Every cited file carries verified line numbers; the two highest-risk backend
+  traps (`cast` name collision, `date_trunc` strict typing) are called out with
+  the exact fix.
+- Validation gates are concrete, layered, and fast; the dogfood checklist has 9
+  explicit scenarios.
+
+**Why not higher:**
+- Genuinely large — 15 tasks across two layers, ~25 files. More surface = more
+  room for a small mistake; the per-task `VALIDATE` keeps it recoverable but a
+  single pass is ambitious.
+- The `analytics` slice has **no test infrastructure** — Task 4 must stand up DB
+  fixtures from scratch (copied from `backtesting`). This is the least
+  mechanical task and the most likely to need a second pass.
+- The four upgraded pages are real UI composition — layout/hierarchy/URL-state
+  need the real-browser dogfood (Task 14); a green `tsc` will not catch a
+  cramped detail page or a dropped `useSearchParams` sync.
+
+All identified risks are caught by the validation loop (strict type-check +
+integration tests + browser dogfood) and the fixes are local. Executing the
+tasks in order and running each `VALIDATE` before moving on is what carries it.
diff --git a/PRPs/PRP-21-explorer-runs-jobs-interactivity.md b/PRPs/PRP-21-explorer-runs-jobs-interactivity.md
new file mode 100644
index 00000000..d18abb09
--- /dev/null
+++ b/PRPs/PRP-21-explorer-runs-jobs-interactivity.md
@@ -0,0 +1,1022 @@
+name: "PRP-21 — Explorer Interactivity: Model Runs & Jobs (detail views, comparison, verify, sorting)"
+description: |
+  Extend the **Model Runs** and **Jobs** pages of the ForecastLabAI dashboard
+  Explorer menu from flat, read-only tables into an interactive investigation
+  surface — the direct sibling of PRP-20 (`#187`/`#188`, which did this for
+  Sales / Stores / Products), applied to the `registry` and `jobs` slices:
+
+  1. **Click-through detail views** — three new deep-linkable routes:
+     - `/explorer/runs/:runId` — model-run profile, JSON config/metrics/runtime
+       info, store/product cross-links, an artifact section with a "Verify
+       integrity" button, and a "Compare with…" link.
+     - `/explorer/jobs/:jobId` — job profile, `params`/`result` JSON, error
+       details, a linked `run_id`, and a cancel action; live-polls while running.
+     - `/explorer/runs/compare?a=<id>&b=<id>` — run-vs-run comparison: side-by-side
+       profile table, `config_diff`, and `metrics_diff` with delta indicators.
+  2. **Artifact verify action** — a button on the run detail page calling the
+     existing `GET /registry/runs/{run_id}/verify` (SHA-256 integrity check).
+  3. **Richer tables** — server-side column sorting + row-click navigation on both
+     tables; the Jobs table additionally gains CSV export + column-visibility
+     toggles (the Runs table already has both from PRP-20).
+  4. **URL state** — filter / sort / page state on both tables persisted in the
+     URL query string (`useSearchParams`), so a pasted URL reproduces the view.
+
+  Backend-touching but **additive**: the only server change is two optional
+  `sort_by` / `sort_order` query params on `GET /registry/runs` and `GET /jobs`
+  (allow-listed columns; unknown → default order, never an error). **No Alembic
+  migration**, **no new slice**, **no new env var**, **no `app/main.py` change**
+  (both routers are already wired). Every detail/compare/verify endpoint the
+  frontend needs **already exists**; three of four hooks (`useRun`, `useJob`,
+  `useCompareRuns`) already exist and are currently unused.
+
+> **PRP numbering:** `PRP-16` is reserved (Phase-2 LightGBM). `PRP-17`–`PRP-20`
+> are used. This is `PRP-21`. Source plan:
+> `.agents/plans/explorer-runs-jobs-interactivity.md`.
+
+## Purpose
+Close the "Model Runs / Jobs Explorer pages are terminal" gap. Today a row shows a
+truncated `run_id`/`job_id`, a status badge, and a few columns — there is no way to
+see a run's `model_config`, `metrics`, `runtime_info`, the artifact hash, or a job's
+`params`/`result`/`error_message` from the UI. Two runs cannot be compared. Artifact
+integrity cannot be checked. Neither table sorts, the Jobs table cannot export, and
+filter state is lost on every refresh. Every one of those answers already exists in
+the backend; the dashboard simply does not surface them. PRP-20 solved the identical
+gap for Stores/Products — this PRP applies the same pattern to the remaining two
+Explorer pages.
+
+## Core Principles
+1. **Context is King** — every endpoint shape, hook name, schema field, service
+   method, and pattern below is linked to a real source file + verified line numbers.
+2. **Reuse existing patterns** — the backend change is a verbatim copy of the
+   `dimensions` allow-listed-sort pattern; the new pages mirror `store-detail.tsx`;
+   the table upgrades mirror `stores.tsx`; the routes register exactly like the
+   existing Explorer detail routes in `App.tsx`.
+3. **Additive only** — no new slice, no migration, no new `.env` var, no
+   `app/main.py` edit. The backend delta is two optional query params on two
+   already-wired list endpoints.
+4. **Strict gates honored** — because `.py` files in the `registry` and `jobs`
+   slices change, the repo-wide `ruff` / `mypy --strict` / `pyright --strict` /
+   `pytest` CI jobs genuinely apply and must stay green; each backend change ships
+   with slice tests.
+5. **UI through skills** — pages built via `frontend-design` + `shadcn-ui` and
+   dogfooded via `webapp-testing` / `agent-browser` per `.claude/rules/ui-design.md`.
+   A green `tsc` is NOT proof the UI works.
+
+---
+
+## Goal
+
+**Backend (additive, no migration):**
+- `GET /registry/runs` gains optional `sort_by` + `sort_order` params (allow-listed
+  columns; unknown `sort_by` → default `created_at desc`, never an error).
+- `GET /jobs` gains the identical `sort_by` + `sort_order` params.
+
+**Frontend:**
+- Three new routes — `/explorer/runs/:runId`, `/explorer/jobs/:jobId`,
+  `/explorer/runs/compare` — composed entirely from already-shipped endpoints.
+- Row-click navigation from the Runs / Jobs tables into the detail pages.
+- Server-side column sorting on both tables; CSV export + column-visibility on the
+  Jobs table (Runs already has them).
+- Filter / sort / page state on both tables persisted in the URL query string.
+- One new hook (`useVerifyArtifact`), one new shared component (`JsonBlock`), one new
+  TS type (`ArtifactVerifyResponse`); `sortBy`/`sortOrder` added to `useRuns`/`useJobs`.
+
+## Why
+- **Portfolio identity.** `.claude/rules/product-vision.md` principle 1 —
+  "portfolio-grade, end-to-end … every phase ships working code". The registry and
+  jobs slices are fully built (`GET /registry/runs/{id}`, `/registry/compare/{a}/{b}`,
+  `/registry/runs/{id}/verify`, `GET /jobs/{id}`) but the dashboard exposes them only
+  as flat tables — a reviewer cannot inspect a single run or compare two without
+  leaving the UI for Swagger.
+- **Analyst workflow.** "Why did this run perform worse" and "what did this job
+  return" are core questions; today they are unanswerable in-product.
+- **Consistency.** Stores/Products already have detail pages, sorting, export and URL
+  state (PRP-20). Runs/Jobs being flat is a visible, jarring inconsistency.
+- **High value per line.** Almost everything is composition of shipped endpoints and
+  shipped components; the only new server code is two query params.
+
+## What
+Backend-touching but additive. Two `sort_by`/`sort_order` query params + allow-listed
+ordering on the `registry` and `jobs` list endpoints, with tests for both (the `jobs`
+slice has **no DB test fixtures and no route tests today** — this PRP also closes that
+gap). Frontend: 3 new pages, 3 new routes, 1 new hook, 1 new component, 1 new TS type,
+2 existing table pages upgraded to interactive. No migration, no new env var, no new
+slice, no `app/main.py` change.
+
+### Success Criteria
+- [ ] `GET /registry/runs` and `GET /jobs` accept `sort_by` + `sort_order`; omitting
+      them preserves the current `created_at desc` default; an unknown `sort_by`
+      falls back to the default order without erroring; `sort_order` outside
+      `{asc,desc}` is rejected (422 via the `Query` regex).
+- [ ] Clicking a Model Runs row navigates to a working `/explorer/runs/:runId` page
+      with status, model type, store/product links, data window, hashes,
+      timestamps, and the `model_config`/`feature_config`/`metrics`/`runtime_info`/
+      `agent_context` JSON.
+- [ ] Clicking a Jobs row navigates to a working `/explorer/jobs/:jobId` page with
+      status, type, timestamps, linked `run_id`, `params`/`result` JSON, error
+      details, and a cancel action for pending jobs; the page live-polls until terminal.
+- [ ] `/explorer/runs/compare?a=&b=` shows two run pickers, a side-by-side profile
+      table, `config_diff`, and `metrics_diff` with delta indicators; the comparison
+      is deep-linkable via the URL.
+- [ ] The run detail "Verify integrity" button calls `GET /registry/runs/{id}/verify`
+      and surfaces pass/fail (incl. the `verified:false` checksum-mismatch branch).
+- [ ] Both tables support server-side column sorting + row-click; the Jobs table
+      also supports CSV export + column-visibility; the Jobs table's in-row cancel
+      button cancels WITHOUT navigating.
+- [ ] Filter / sort / page state on both tables round-trips through the URL (paste a
+      filtered URL into a fresh tab → identical view).
+- [ ] `uv run ruff check . && uv run ruff format --check . && uv run mypy app/ &&
+      uv run pyright app/` clean; `uv run pytest -v -m "not integration"` and the
+      `registry` + `jobs` integration tests green.
+- [ ] `cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run` clean.
+- [ ] No Alembic migration; no new slice; no `app/main.py` change; no `.env` var.
+- [ ] All three new pages dogfooded in a real browser (screenshots captured).
+
+---
+
+## All Needed Context
+
+### Documentation & References
+```yaml
+# ---- External docs ----
+- url: https://tanstack.com/query/latest/docs/framework/react/guides/queries
+  why: useQuery shape for the new useVerifyArtifact hook.
+  critical: GET data → useQuery({ queryKey, queryFn, enabled }). The repo hooks
+    (use-runs.ts, use-jobs.ts) follow this exactly — copy that shape.
+
+- url: https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries
+  why: useVerifyArtifact is a button-gated GET — `enabled` toggled by component
+    state, then refetch(). This is exactly how useCompareRuns (use-runs.ts:50-56)
+    is already built — mirror it.
+
+- url: https://tanstack.com/table/v8/docs/guide/sorting#manual-server-side-sorting
+  why: DataTable already sets `manualSorting: true`; SortingState (`[{id,desc}]`)
+    MUST round-trip through the backend sort_by/sort_order params.
+  critical: A client-only sort reorders ONLY the visible page. Server-side is
+    mandatory — thread SortingState → sort_by/sort_order → useRuns/useJobs.
+
+- url: https://tanstack.com/table/v8/docs/guide/column-visibility
+  why: column-visibility dropdown — already implemented in DataTable via
+    `enableColumnVisibility`; the Jobs table just needs to pass the prop.
+
+- url: https://reactrouter.com/6.30.1/hooks/use-params
+  why: `:runId` / `:jobId` dynamic-segment extraction.
+  critical: useParams() returns `Record<string,string|undefined>`. Run/Job IDs
+    are UUID-hex STRINGS — guard truthiness only, do NOT Number()-parse them
+    (unlike store-detail.tsx / product-detail.tsx which parse numeric ids).
+
+- url: https://reactrouter.com/6.30.1/hooks/use-search-params
+  why: URL filter/sort/page persistence + reading ?a=&b= on the compare page.
+  critical: useSearchParams() → [params, setParams]; params.get('x') is
+    `string | null`. Treat it as controlled state initialised from the URL.
+
+- url: https://reactrouter.com/6.30.1/route/route
+  why: route ranking. v6 ranks routes by specificity — the static
+    `/explorer/runs/compare` outranks the dynamic `/explorer/runs/:runId`, so
+    `compare` is never captured as a `:runId`. Registration order does not matter;
+    register `compare` first anyway for readability.
+
+# ---- THE sibling PRP to mirror ----
+- file: PRPs/PRP-20-explorer-interactivity.md
+  why: this PRP's direct precedent. Read its "Known Gotchas", "list of tasks",
+    "Validation Loop", and "Anti-Patterns" — this PRP applies the same shape to
+    the registry/jobs slices. PRP-20 added DataTable's onRowClick / sorting /
+    enableColumnVisibility, csv-export.ts, DataTableColumnHeader, and the
+    store-detail/product-detail pages — all REUSED here, not rebuilt.
+
+# ---- Backend: the sort pattern to copy verbatim ----
+- file: app/features/dimensions/service.py
+  why: lines 29-45 — `_STORE_SORT_COLUMNS` / `_PRODUCT_SORT_COLUMNS` allow-list
+    dicts typed `dict[str, InstrumentedAttribute[Any]]`; import on line 12
+    (`from sqlalchemy.orm import InstrumentedAttribute`). Lines 105-113 — the
+    resolve-or-default ordering logic. COPY this dict + logic exactly.
+
+- file: app/features/dimensions/routes.py
+  why: lines 70-91 / 195-216 — the `sort_by` / `sort_order` `Query(...)`
+    declarations + docstrings. `sort_order` uses
+    `Query("asc", pattern="^(asc|desc)$", description=...)`.
+
+# ---- Backend: registry slice (gets sort params) ----
+- file: app/features/registry/routes.py
+  why: `list_runs` handler lines 147-182 — add sort_by/sort_order Query params
+    here (after `product_id`), pass into service.list_runs(). get_run (185-217),
+    verify_artifact (311-383), compare_runs (566-606) ALREADY EXIST — do NOT
+    modify, the frontend just consumes them.
+  critical: verify_artifact returns HTTP 200 with `{"verified": false, ...}` on a
+    checksum mismatch (lines 377-383) — it does NOT raise. Only a missing
+    run/artifact 404s. The frontend must handle both the 200-false branch and
+    the error branch.
+
+- file: app/features/registry/service.py
+  why: `list_runs` lines 257-310 — default order is
+    `stmt.order_by(ModelRun.created_at.desc())` (line 300). Imports already have
+    `from typing import Any` (line 19) and `from sqlalchemy import func, select`
+    (line 22). Add `InstrumentedAttribute` import + `_RUN_SORT_COLUMNS` here.
+
+- file: app/features/registry/tests/conftest.py
+  why: ALREADY has integration DB fixtures — `db_session` (lines 26-56), `client`
+    (lines 59-79) — plus sample run fixtures. REUSE these.
+  critical: the `db_session` cleanup deletes runs via
+    `ModelRun.model_type.like("test-%")` (lines 49,53). Every run a sort test
+    creates MUST use a `model_type` starting with `test-` or it will not be
+    cleaned up. Aliases for those runs are cleaned too.
+
+- file: app/features/registry/tests/test_routes.py
+  why: already has `@pytest.mark.integration` route tests using the `client`
+    fixture. Add the sort-param test cases here in that same style.
+
+# ---- Backend: jobs slice (gets sort params; needs DB test fixtures) ----
+- file: app/features/jobs/routes.py
+  why: `list_jobs` handler lines 169-195 — add sort_by/sort_order Query params
+    (after `status`). get_job (222-247), cancel_job (265-297) ALREADY EXIST.
+
+- file: app/features/jobs/service.py
+  why: `list_jobs` lines 204-251 — default order is
+    `stmt.order_by(Job.created_at.desc())` (line 240). Imports: `from typing
+    import TYPE_CHECKING, Any` (line 14), `from sqlalchemy import func, select`
+    (line 16). Add `InstrumentedAttribute` import + `_JOB_SORT_COLUMNS` here.
+
+- file: app/features/jobs/models.py
+  why: the `Job` ORM model. Columns for the sort allow-list: `created_at`,
+    `completed_at` (both `DateTime`, `completed_at` nullable), `job_type`,
+    `status` (both `String`). `params`/`result` are JSONB — NOT sortable.
+    `job_id` is `String(32)` (exactly a uuid4 hex).
+
+- file: app/features/jobs/tests/conftest.py
+  why: currently UNIT-ONLY (`sample_train_job_create` etc.). It has NO
+    `db_session` / `client` fixture; the `jobs` slice has NO `test_routes.py`.
+  critical: Task 4 must COPY `db_session` + `client` from
+    app/features/registry/tests/conftest.py:26-79, swapping the cleanup to delete
+    `Job` rows. Job has no `model_type` — use a `job_id` prefix for the cleanup
+    key (see Gotchas).
+
+# ---- Frontend: hooks (3 of 4 already exist) ----
+- file: frontend/src/hooks/use-runs.ts
+  why: `useRuns` (list, lines 15-40), `useRun(runId, enabled)` (42-48),
+    `useCompareRuns(a, b, enabled)` (50-56). Add sortBy/sortOrder to UseRunsParams;
+    add a new `useVerifyArtifact` hook here.
+
+- file: frontend/src/hooks/use-jobs.ts
+  why: `useJobs` (list, 13-35), `useJob(jobId, enabled)` (37-47 — ALREADY polls
+    every 2s while pending/running, stops otherwise), `useCancelJob` (60-69). Add
+    sortBy/sortOrder to UseJobsParams.
+
+- file: frontend/src/hooks/use-stores.ts
+  why: the PRP-20 precedent for adding optional sortBy/sortOrder to a list hook —
+    threaded into both the queryKey array and the api params. Mirror it.
+
+# ---- Frontend: components (all already exist — REUSED, not built) ----
+- file: frontend/src/components/data-table/data-table.tsx
+  why: ALREADY supports `sorting`, `onSortingChange`, `onRowClick`,
+    `enableColumnVisibility` (PRP-20, props at lines 31-36). NO change needed —
+    just pass the props from runs.tsx / jobs.tsx.
+
+- file: frontend/src/components/data-table/data-table-column-header.tsx
+  why: `<DataTableColumnHeader column title />` — a sortable header button. Use it
+    in the runs/jobs column defs for sortable columns. A column is sortable unless
+    its def sets `enableSorting: false`.
+
+- file: frontend/src/components/common/status-badge.tsx + frontend/src/lib/status-utils.ts
+  why: `StatusBadge` + `getStatusVariant(status)`. status-utils ALREADY maps every
+    RunStatus (pending/running/success/failed/archived) and JobStatus
+    (pending/running/completed/failed/cancelled) value — no change needed.
+
+- file: frontend/src/components/common/error-display.tsx
+  why: `ErrorDisplay` (error + optional onRetry/title) — used on every detail
+    page for the invalid-id and query-error states.
+
+- file: frontend/src/components/common/job-picker.tsx
+  why: an existing entity-picker component — read it as the pattern for the
+    run-picker `<select>` on the compare page (or use shadcn Select directly).
+
+- file: frontend/src/components/common/index.ts
+  why: barrel — add `export * from './json-block'` for the new JsonBlock component.
+
+- file: frontend/src/components/ui/select.tsx
+  why: shadcn Select — read for exact exports (Select, SelectTrigger, SelectValue,
+    SelectContent, SelectItem) for the compare-page run pickers.
+
+- file: frontend/src/components/charts/kpi-card.tsx
+  why: OPTIONAL — `KPICard` (title, value, icon?, isLoading?) could surface a
+    run's headline metrics; JsonBlock is the minimum.
+
+- file: frontend/src/lib/csv-export.ts
+  why: `toCsv(rows, columns)` + `downloadCsv(filename, csv)` + `CsvColumn<T>`
+    (`key: keyof T & string`, `header`). Already used by runs.tsx — the Jobs table
+    needs the same `csvColumns` + export button.
+
+- file: frontend/src/lib/api.ts
+  why: `api<T>(endpoint, {params, method, body})` client (drops undefined/null/''
+    params), `formatNumber`, `ApiError`, `getErrorMessage`.
+
+# ---- Frontend: routing + pages ----
+- file: frontend/src/lib/constants.ts
+  why: `ROUTES.EXPLORER` (lines 5-15). STORE_DETAIL/PRODUCT_DETAIL are already
+    there as dynamic routes (13-14). Add RUN_DETAIL, JOB_DETAIL, RUN_COMPARE.
+    NAV_ITEMS (27-51) is UNCHANGED — detail pages are click-through, not nav items.
+
+- file: frontend/src/App.tsx
+  why: lazy imports (10-25), `<Route>`s inside `<AppShell/>` (37-158).
+    StoreDetailPage / ProductDetailPage are already registered (lines 15, 17,
+    70-93) — add the 3 new pages identically.
+
+- file: frontend/src/pages/explorer/store-detail.tsx
+  why: THE detail-page template — useParams + guard (22-24), ErrorDisplay states
+    (56-75), "Back to …" Button-asChild-Link (86-91), profile Card `<dl>` grid
+    (108-133), section cards with empty-state fallbacks (162-197).
+
+- file: frontend/src/pages/explorer/stores.tsx
+  why: THE interactive-table-page template — useSearchParams URL state (57-95),
+    handleSortingChange (102-110), handlePaginationChange (97-100), CSV export
+    (125-127), onRowClick → navigate() (191), DataTableColumnHeader in column defs
+    (22-45). runs.tsx + jobs.tsx must converge on this exact shape.
+
+- file: frontend/src/pages/explorer/runs.tsx
+  why: current Model Runs page (176 lines). ALREADY has CSV export +
+    enableColumnVisibility. Gets URL state, row-click, server sort, a "Compare" link.
+
+- file: frontend/src/pages/explorer/jobs.tsx
+  why: current Jobs page (192 lines). Has NEITHER export NOR column visibility NOR
+    URL state. The `columns` array is built INSIDE the component (closes over
+    handleCancelJob); the `actions` column (91-122) renders an AlertDialog cancel
+    button inside the row.
+
+- file: frontend/src/types/api.ts
+  why: `ModelRun` (122-145), `RunListResponse` (147-149), `RunCompareResponse`
+    (161-166: run_a, run_b, config_diff, metrics_diff:Record<string,{a,b,diff}>),
+    `RunStatus` (120), `Job` (172-185), `JobListResponse` (187-189),
+    `JobStatus`/`JobType` (169-170). Add one new `ArtifactVerifyResponse` type.
+
+# ---- Rules ----
+- file: .claude/rules/ui-design.md
+  why: UI built/dogfooded via frontend-design + shadcn-ui + webapp-testing.
+- file: .claude/rules/security-patterns.md
+  why: "Allow-lists over deny-lists" — sort_by MUST resolve through an allow-list
+    dict to a real mapped column, never interpolate the raw string into SQL.
+- file: .claude/rules/test-requirements.md
+  why: new endpoint param → test; new SQLAlchemy-touching path → integration test
+    against real Postgres, never mocked.
+- file: .claude/rules/commit-format.md & branch-naming.md
+  why: `type(scope): description (#issue)`; scopes `registry`/`jobs`/`ui`/`api`/
+    `docs` (comma-pairs allowed); branch `feat/explorer-runs-jobs-interactivity`
+    off `dev`; open the tracking issue FIRST.
+```
+
+### Current Codebase tree (relevant)
+```bash
+app/features/
+├── registry/
+│   ├── routes.py            # MOD — +sort_by/sort_order on list_runs
+│   ├── service.py           # MOD — +_RUN_SORT_COLUMNS, allow-listed ordering
+│   └── tests/
+│       ├── conftest.py      # REUSE — db_session/client already exist
+│       └── test_routes.py   # MOD — +sort-param integration tests
+└── jobs/
+    ├── routes.py            # MOD — +sort_by/sort_order on list_jobs
+    ├── service.py           # MOD — +_JOB_SORT_COLUMNS, allow-listed ordering
+    └── tests/
+        ├── conftest.py      # MOD — +db_session/client (copied from registry) + sample_jobs_multi
+        └── test_routes.py   # NEW — integration tests (closes the jobs route-test gap)
+
+frontend/src/
+├── App.tsx                  # MOD — +3 lazy detail/compare routes
+├── lib/constants.ts         # MOD — +ROUTES.EXPLORER.RUN_DETAIL/JOB_DETAIL/RUN_COMPARE
+├── types/api.ts             # MOD — +ArtifactVerifyResponse
+├── hooks/
+│   ├── use-runs.ts          # MOD — +sortBy/sortOrder on useRuns, +useVerifyArtifact
+│   └── use-jobs.ts          # MOD — +sortBy/sortOrder on useJobs
+├── components/common/
+│   ├── json-block.tsx       # NEW — formatted-JSON viewer
+│   └── index.ts             # MOD — +1 barrel line
+└── pages/explorer/
+    ├── runs.tsx             # MOD — +row-click, +sorting, +url state, +compare link
+    ├── jobs.tsx             # MOD — +row-click, +sorting, +export, +visibility, +url state
+    ├── run-detail.tsx       # NEW
+    ├── job-detail.tsx       # NEW
+    └── run-compare.tsx      # NEW
+```
+
+### Desired Codebase tree (files added / changed)
+```bash
+NEW  app/features/jobs/tests/test_routes.py            # integration — /jobs list + sort + /jobs/{id}
+NEW  frontend/src/components/common/json-block.tsx     # JSON viewer component
+NEW  frontend/src/pages/explorer/run-detail.tsx        # /explorer/runs/:runId
+NEW  frontend/src/pages/explorer/job-detail.tsx        # /explorer/jobs/:jobId
+NEW  frontend/src/pages/explorer/run-compare.tsx       # /explorer/runs/compare
+MOD  app/features/registry/{routes,service}.py         # +sort_by/sort_order
+MOD  app/features/registry/tests/test_routes.py        # +sort integration tests
+MOD  app/features/jobs/{routes,service}.py             # +sort_by/sort_order
+MOD  app/features/jobs/tests/conftest.py               # +db_session/client + sample_jobs_multi
+MOD  frontend/src/types/api.ts                         # +ArtifactVerifyResponse
+MOD  frontend/src/hooks/{use-runs,use-jobs}.ts         # +sort params, +useVerifyArtifact
+MOD  frontend/src/components/common/index.ts           # +json-block barrel line
+MOD  frontend/src/lib/constants.ts                     # +3 routes
+MOD  frontend/src/App.tsx                              # +3 lazy routes
+MOD  frontend/src/pages/explorer/{runs,jobs}.tsx       # interactive upgrades
+MOD  README.md                                         # feature list
+MOD  docs/_base/API_CONTRACTS.md                       # +sort params on /registry/runs & /jobs
+MOD  docs/_base/REPO_MAP_INDEX.md                      # +run-detail/job-detail/run-compare rows
+KEEP app/main.py                                       # UNCHANGED — both routers already wired
+KEEP alembic/**                                        # UNCHANGED — NO migration (sort is read-only)
+```
+
+### Known Gotchas & Library Quirks
+```python
+# CRITICAL: NO Alembic migration. Sorting is a read-only ORDER BY change; the
+#   schema does not change. `.claude/rules` require a migration only when the
+#   SCHEMA changes. Adding one would be wrong.
+
+# CRITICAL: sort_by is user input. Resolve it through an explicit allow-list dict
+#   {str: InstrumentedAttribute} → a real SQLAlchemy mapped column. NEVER
+#   interpolate the raw string into the query (security-patterns.md). Unknown
+#   sort_by → fall back to the default order; do NOT 400 (keeps it
+#   backward-compatible and avoids 500s from stale frontend state).
+
+# CRITICAL: ModelRun.metrics / ModelRun.runtime_info and Job.params / Job.result
+#   are JSONB columns — they are NOT in the sort allow-list (cannot ORDER BY a
+#   JSONB blob meaningfully). Allow-list runs by created_at|model_type|status|
+#   store_id|product_id; jobs by created_at|completed_at|job_type|status.
+
+# CRITICAL: registry verify_artifact (routes.py:377-383) returns HTTP 200 with
+#   {"verified": false, ...} on a checksum MISMATCH — it does NOT raise. Only a
+#   missing run (404) or missing artifact (400) is an error. useVerifyArtifact
+#   must handle the 200-false success branch AND the ApiError branch.
+
+# CRITICAL: jobs slice has NO DB test infrastructure. jobs/tests/conftest.py has
+#   only unit fixtures; there is no test_routes.py. Task 4 copies db_session +
+#   client from registry/tests/conftest.py:26-79. Budget time — this is the
+#   least-mechanical task (mirrors PRP-20's analytics test gap).
+
+# CRITICAL: registry's db_session cleanup deletes runs via
+#   ModelRun.model_type.like("test-%"). A sort test that creates runs MUST set
+#   model_type to a value starting with "test-" (e.g. "test-aaa", "test-bbb")
+#   or the rows leak. Sorting by model_type still works on those values.
+
+# CRITICAL: Job has no model_type column for a cleanup key. The jobs db_session
+#   cleanup must key on job_id. Job.job_id is String(32) (exactly a uuid4 hex).
+#   Create test jobs with job_id = "test" + uuid.uuid4().hex[:28] (32 chars,
+#   starts "test"); cleanup: delete(Job).where(Job.job_id.like("test%")).
+
+# GOTCHA: run_id / job_id are UUID-hex STRINGS, not integers. The detail pages
+#   guard useParams() values by truthiness only — do NOT Number()-parse them
+#   (store-detail.tsx / product-detail.tsx parse numeric ids; this is different).
+
+# GOTCHA: React Router v6 ranks `/explorer/runs/compare` (static) ABOVE
+#   `/explorer/runs/:runId` (dynamic) — `compare` is never captured as a runId.
+#   Registration order in <Routes> does not matter; register compare first anyway.
+
+# GOTCHA: jobs.tsx renders an AlertDialog cancel button inside each row
+#   (lines 91-122). Once onRowClick makes the row clickable, the cancel cell
+#   MUST stopPropagation — wrap the AlertDialogTrigger/cell with
+#   onClick={(e) => e.stopPropagation()} so cancelling does not also navigate.
+
+# GOTCHA: DataTable has `manualSorting: true`. Server-side sort is mandatory —
+#   thread SortingState → sort_by/sort_order → useRuns/useJobs → URL. A
+#   client-only sort would silently reorder only the current page.
+
+# GOTCHA: a DataTableColumnHeader column's `column.id` (= accessorKey) must equal
+#   the backend allow-list key. runs.tsx accessorKeys status|model_type|store_id|
+#   product_id|created_at already match _RUN_SORT_COLUMNS; jobs.tsx status|
+#   job_type|created_at|completed_at match _JOB_SORT_COLUMNS.
+
+# GOTCHA: data-table-pagination.tsx ALREADY has a page-size selector. Do NOT add
+#   another one.
+
+# GOTCHA: keep useRuns/useJobs sortBy/sortOrder params OPTIONAL — nothing else
+#   calls these hooks, but optionality keeps the diff minimal and safe.
+
+# GOTCHA: new .tsx/.ts files are LF. Editing existing .py files preserves their
+#   CRLF (repo .py files are CRLF, no .gitattributes — project memory). After
+#   writing the NEW .py test file run `git diff --stat` and confirm no whole-file
+#   EOL churn slipped in.
+
+# GOTCHA: both routers are already in app/main.py. Do NOT edit main.py — the sort
+#   params attach to the existing list handlers in routes.py.
+
+# GOTCHA: every commit references the open tracking issue (commit-format.md);
+#   NO AI co-author trailer, ever. Branch off `dev`.
+```
+
+### Resolved Decisions (user-confirmed 2026-05-18)
+```yaml
+interactivity-scope:
+  decision: all four directions ship — detail pages + row-click, run-vs-run
+    comparison, artifact verify action, and server-side table sorting.
+  status: confirmed (AskUserQuestion, multi-select all four).
+compare-ux:
+  decision: run-vs-run comparison is a dedicated deep-linkable route
+    (/explorer/runs/compare?a=<id>&b=<id>), NOT a modal/inline panel — shareable
+    via URL, consistent with the deep-linkable detail-page pattern.
+  status: confirmed (user chose "Dedicated deep-linkable route").
+metrics-diff-rendering:
+  decision: metrics_diff is rendered as a table with delta indicators (▲/▼ on the
+    sign of `diff`), NOT a chart. The PRP does not colour-code "better/worse" —
+    the backend does not classify metric direction.
+  status: confirmed (matches the user-approved AskUserQuestion preview).
+```
+
+---
+
+## Implementation Blueprint
+
+### Backend — registry sort (`app/features/registry/service.py`)
+```python
+# IMPORTS to add: `from sqlalchemy.orm import InstrumentedAttribute`
+# `Any` and `func, select` are already imported (lines 19, 22).
+
+# Module level, after `logger = ...`. Mirror dimensions/service.py:32-45.
+_RUN_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "created_at": ModelRun.created_at,
+    "model_type": ModelRun.model_type,
+    "status": ModelRun.status,
+    "store_id": ModelRun.store_id,
+    "product_id": ModelRun.product_id,
+}
+
+# In list_runs: add params `sort_by: str | None = None`, `sort_order: str = "asc"`.
+# Replace the line-300 order_by with the resolve-or-default block:
+sort_column = _RUN_SORT_COLUMNS.get(sort_by) if sort_by else None
+if sort_column is not None:
+    order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+else:
+    order_by = ModelRun.created_at.desc()  # UNCHANGED default — keeps existing tests green
+stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
+```
+
+### Backend — registry route (`app/features/registry/routes.py`, in `list_runs`)
+```python
+# Add after the product_id Query param (mirror dimensions/routes.py:70-91):
+sort_by: str | None = Query(
+    None,
+    description="Sort column: created_at|model_type|status|store_id|product_id. "
+    "Unknown values use the default order.",
+),
+sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort direction."),
+# ...then thread sort_by=sort_by, sort_order=sort_order into service.list_runs(...).
+```
+
+### Backend — jobs sort (`app/features/jobs/service.py` + `routes.py`)
+```python
+# service.py — add `from sqlalchemy.orm import InstrumentedAttribute`; module-level:
+_JOB_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "created_at": Job.created_at,
+    "completed_at": Job.completed_at,
+    "job_type": Job.job_type,
+    "status": Job.status,
+}
+# list_jobs: +sort_by/sort_order params; replace line-240 order_by with the same
+# resolve-or-default block; default Job.created_at.desc().
+# routes.py — list_jobs: +sort_by/sort_order Query params (after `status`),
+# thread into service.list_jobs(...). completed_at is nullable — Postgres default
+# NULLS LAST on .asc() is acceptable; do NOT add special null handling.
+```
+
+### Frontend — type (`frontend/src/types/api.ts`, after `RunCompareResponse`)
+```typescript
+// Response from GET /registry/runs/{run_id}/verify (SHA-256 integrity check).
+// On a checksum mismatch the endpoint returns HTTP 200 with verified:false + error.
+export interface ArtifactVerifyResponse {
+  verified: boolean
+  run_id: string
+  artifact_uri: string
+  stored_hash?: string
+  computed_hash?: string
+  error?: string
+}
+```
+
+### Frontend — hooks (`use-runs.ts` / `use-jobs.ts`)
+```typescript
+// use-runs.ts — add to UseRunsParams: sortBy?: string; sortOrder?: 'asc' | 'desc'
+// thread into useRuns queryKey + api params as sort_by / sort_order.
+// New hook (mirror useCompareRuns at use-runs.ts:50-56):
+export function useVerifyArtifact(runId: string, enabled = false) {
+  return useQuery({
+    queryKey: ['runs', runId, 'verify'],
+    queryFn: () => api<ArtifactVerifyResponse>(`/registry/runs/${runId}/verify`),
+    enabled: enabled && !!runId,
+    retry: false,   // surface a 404 / mismatch immediately
+  })
+}
+// use-jobs.ts — add sortBy/sortOrder to UseJobsParams, thread into useJobs the
+// same way. Leave useJob's refetchInterval polling (lines 42-46) untouched.
+```
+
+### Frontend — JsonBlock (`frontend/src/components/common/json-block.tsx`)
+```typescript
+// Pure presentational. value: unknown; className?: string.
+// null/undefined → a muted "—". Otherwise:
+//   <pre class="max-h-96 overflow-auto rounded-md border bg-muted/40 p-3
+//               text-xs font-mono whitespace-pre-wrap break-all">
+//     {JSON.stringify(value, null, 2)}
+//   </pre>
+// No syntax-highlighter dependency. Add `export * from './json-block'` to
+// components/common/index.ts.
+```
+
+### Frontend — run-detail page (`frontend/src/pages/explorer/run-detail.tsx`)
+```text
+export default function RunDetailPage()
+- const { runId } = useParams(); guard !runId → ErrorDisplay "Invalid run".
+- const runQuery = useRun(runId ?? '', !!runId); runQuery.error → ErrorDisplay + retry.
+- const [verifyOn, setVerifyOn] = useState(false)
+  const verifyQuery = useVerifyArtifact(runId ?? '', verifyOn)
+- Header: "Back to Model Runs" Button-asChild-Link → ROUTES.EXPLORER.RUNS;
+  <h1> mono run_id; StatusBadge variant={getStatusVariant(run.status)}.
+- Profile Card (<dl> grid, mirror store-detail.tsx:108-133): model_type;
+  store_id → Link `/explorer/stores/${store_id}`; product_id → Link
+  `/explorer/products/${product_id}`; data window; config_hash (mono); git_sha;
+  created_at / started_at / completed_at (format via date-fns).
+- if status==='failed' && error_message → destructive-styled Card.
+- Metrics Card: <JsonBlock value={run.metrics} />.
+- Config Card: <JsonBlock value={run.model_config} /> + feature_config.
+- Runtime Card: <JsonBlock value={run.runtime_info} />.
+- Agent context Card: <JsonBlock value={run.agent_context} /> (render only if non-null).
+- Artifact Card: artifact_uri, artifact_hash (mono), artifact_size_bytes;
+  a "Verify integrity" Button — onClick: verifyOn ? verifyQuery.refetch() :
+  setVerifyOn(true). disabled={!run.artifact_uri}. While verifyQuery.isFetching →
+  spinner; verifyQuery.data?.verified===true → green check + computed_hash;
+  verified===false OR verifyQuery.error → destructive alert.
+- "Compare with…" Button-asChild-Link → `${ROUTES.EXPLORER.RUN_COMPARE}?a=${runId}`.
+- Build with frontend-design + shadcn-ui; reuse LoadingState/ErrorDisplay.
+```
+
+### Frontend — job-detail page (`frontend/src/pages/explorer/job-detail.tsx`)
+```text
+export default function JobDetailPage()
+- const { jobId } = useParams(); guard !jobId → ErrorDisplay.
+- const jobQuery = useJob(jobId ?? '', !!jobId)  // already polls while pending/running
+- Header: "Back to Jobs" Link → ROUTES.EXPLORER.JOBS; mono job_id; StatusBadge.
+- Profile Card: job_type (capitalize); created_at/started_at/completed_at;
+  run_id → if non-null, Link `/explorer/runs/${run_id}` (cross-link to run detail).
+- Params Card: <JsonBlock value={job.params} />.
+- Result Card: <JsonBlock value={job.result} /> — muted "No result yet" when
+  result==null and status is pending/running.
+- if status==='failed' → destructive Card with error_message + error_type.
+- if status==='pending' → "Cancel job" Button wrapped in the AlertDialog
+  confirmation copied from jobs.tsx:99-119, wired to useCancelJob.mutateAsync.
+- GOTCHA: after cancel, also invalidate ['jobs', jobId] so this page reflects the
+  cancelled status (useCancelJob.onSuccess currently invalidates only ['jobs']).
+```
+
+### Frontend — run-compare page (`frontend/src/pages/explorer/run-compare.tsx`)
+```text
+export default function RunComparePage()
+- const [params, setParams] = useSearchParams()
+  const a = params.get('a') ?? ''; const b = params.get('b') ?? ''
+- Two run pickers: shadcn Select populated by useRuns({ page:1, pageSize:100 });
+  each option label `${run_id.slice(0,8)} · ${model_type} · ${status}`.
+  Selecting updates the URL via setParams → comparison is deep-linkable.
+- const cmp = useCompareRuns(a, b, !!a && !!b)  // RunCompareResponse
+- Empty state when !a || !b → Card prompting the user to pick two runs.
+- Profile table: rows model_type / status / data window / config_hash / created_at
+  from cmp.data.run_a vs run_b (side-by-side, Table component).
+- config_diff Card: <JsonBlock value={cmp.data.config_diff} />.
+- metrics_diff table: Object.entries(cmp.data.metrics_diff) → one row each:
+  Metric | Run A (m.a) | Run B (m.b) | Δ (m.diff with ▲ if diff>0 / ▼ if diff<0 /
+  "—" if diff==null). Guard nullable numbers. Do NOT colour-code better/worse.
+- "Back to Model Runs" Link.
+```
+
+### list of tasks (in execution order)
+```yaml
+Task 1 — Tracking GitHub issue + branch:
+  - Open ONE issue: "Explorer interactivity: Model Runs & Jobs detail views, run
+    comparison, artifact verify, table sorting". Note scopes registry/jobs/ui/api/docs.
+  - Confirm: `gh issue view <N> --json state` → OPEN. Every commit references (#N).
+  - Branch: `git fetch origin && git switch -c
+    feat/explorer-runs-jobs-interactivity origin/dev`.
+  - GOTCHA: do NOT reuse the current local `feat/explorer-interactivity` branch
+    (that is merged PRP-20). Branch fresh off `dev`.
+
+Task 2 — Backend: registry sort params:
+  MODIFY app/features/registry/service.py
+    - Add `from sqlalchemy.orm import InstrumentedAttribute`.
+    - Add module-level `_RUN_SORT_COLUMNS` (see Blueprint).
+    - Add `sort_by`/`sort_order` params to `list_runs`; replace the line-300
+      order_by with the resolve-or-default block.
+  MODIFY app/features/registry/routes.py
+    - Add `sort_by`/`sort_order` Query params to `list_runs` (after product_id);
+      thread into `service.list_runs(...)`.
+  VALIDATE: uv run ruff check app/features/registry/ &&
+    uv run mypy app/features/registry/ && uv run pyright app/features/registry/ &&
+    uv run python -c "from app.main import app"
+
+Task 3 — Backend: jobs sort params:
+  MODIFY app/features/jobs/service.py
+    - Add `from sqlalchemy.orm import InstrumentedAttribute`.
+    - Add module-level `_JOB_SORT_COLUMNS` (see Blueprint).
+    - Add `sort_by`/`sort_order` params to `list_jobs`; replace the line-240
+      order_by with the resolve-or-default block.
+  MODIFY app/features/jobs/routes.py
+    - Add `sort_by`/`sort_order` Query params to `list_jobs` (after status);
+      thread into `service.list_jobs(...)`.
+  VALIDATE: uv run ruff check app/features/jobs/ &&
+    uv run mypy app/features/jobs/ && uv run pyright app/features/jobs/
+
+Task 4 — Backend tests (registry sort + jobs DB infra & route tests):
+  MODIFY app/features/registry/tests/test_routes.py
+    - Add @pytest.mark.integration test(s): POST 3 runs with model_type
+      "test-aaa"/"test-bbb"/"test-ccc"; GET /registry/runs?sort_by=model_type&
+      sort_order=desc asserts descending; sort_by=metrics (unknown) falls back to
+      default order, HTTP 200; omitted params == created_at desc.
+  MODIFY app/features/jobs/tests/conftest.py
+    - Copy `db_session` + `client` from registry/tests/conftest.py:26-79 VERBATIM,
+      swapping the cleanup to `delete(Job).where(Job.job_id.like("test%"))`
+      (import `Job` from app.features.jobs.models, `delete` from sqlalchemy).
+    - Add a `sample_jobs_multi` fixture inserting 3 Job ORM rows directly:
+      job_id=f"test{uuid.uuid4().hex[:28]}", distinct job_type + status, staggered
+      created_at, params={} (JSONB non-null).
+  CREATE app/features/jobs/tests/test_routes.py
+    - @pytest.mark.integration class (mirror registry/tests/test_routes.py style):
+      GET /jobs 200 happy path; GET /jobs?sort_by=job_type&sort_order=asc ordered;
+      unknown sort_by → default order, 200; GET /jobs/{id} 200 + 404.
+  GOTCHA: new .py file (test_routes.py) — run `git diff --stat` after, confirm no
+    EOL churn. Integration tests need `docker compose up -d` + alembic upgrade head.
+  VALIDATE:
+    docker compose up -d && uv run alembic upgrade head &&
+    uv run pytest -v -m integration app/features/registry/tests/test_routes.py
+      app/features/jobs/tests/
+
+Task 5 — Frontend: type + hooks:
+  MODIFY frontend/src/types/api.ts — add `ArtifactVerifyResponse` (see Blueprint).
+  MODIFY frontend/src/hooks/use-runs.ts — add sortBy/sortOrder to UseRunsParams +
+    useRuns; add `useVerifyArtifact` hook; import ArtifactVerifyResponse.
+  MODIFY frontend/src/hooks/use-jobs.ts — add sortBy/sortOrder to UseJobsParams +
+    useJobs.
+  VALIDATE: cd frontend && pnpm tsc --noEmit
+
+Task 6 — Frontend: JsonBlock component:
+  CREATE frontend/src/components/common/json-block.tsx (see Blueprint).
+  MODIFY frontend/src/components/common/index.ts — add the barrel line.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 7 — Frontend: routing:
+  MODIFY frontend/src/lib/constants.ts — ROUTES.EXPLORER +=
+    RUN_DETAIL:'/explorer/runs/:runId', JOB_DETAIL:'/explorer/jobs/:jobId',
+    RUN_COMPARE:'/explorer/runs/compare'. Do NOT touch NAV_ITEMS.
+  MODIFY frontend/src/App.tsx — 3 lazy imports (RunDetailPage, JobDetailPage,
+    RunComparePage) + 3 <Route>s in <Suspense> inside <AppShell/>; register
+    RUN_COMPARE before RUN_DETAIL.
+  NOTE: pnpm tsc will fail here until Tasks 8-10 exist — re-run after Task 10.
+
+Task 8 — Frontend: run-detail page:
+  CREATE frontend/src/pages/explorer/run-detail.tsx (see Blueprint).
+    Build with frontend-design + shadcn-ui.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 9 — Frontend: job-detail page:
+  CREATE frontend/src/pages/explorer/job-detail.tsx (see Blueprint).
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 10 — Frontend: run-compare page:
+  CREATE frontend/src/pages/explorer/run-compare.tsx (see Blueprint).
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 11 — Frontend: interactive Runs table:
+  MODIFY frontend/src/pages/explorer/runs.tsx
+    - Convert useState filters/pagination → useSearchParams URL state (copy
+      stores.tsx:57-127 — updateParams/handlePaginationChange/handleSortingChange/
+      handleFilterChange/handleReset). URL keys: model_type, status, page,
+      sort_by, sort_order.
+    - Wrap sortable headers (status, model_type, store_id, product_id, created_at)
+      in <DataTableColumnHeader>; set enableSorting:false on run_id, data_window,
+      metrics.
+    - Derive sortBy/sortOrder from sorting[0]; pass to useRuns; pass
+      sorting/onSortingChange to DataTable.
+    - useNavigate(); onRowClick={(run)=>navigate(`/explorer/runs/${run.run_id}`)}.
+    - Add a "Compare runs" Button-asChild-Link → ROUTES.EXPLORER.RUN_COMPARE.
+    - Keep the existing CSV export + enableColumnVisibility.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint
+
+Task 12 — Frontend: interactive Jobs table:
+  MODIFY frontend/src/pages/explorer/jobs.tsx
+    - Same URL-state conversion (keys: job_type, status, page, sort_by, sort_order).
+    - Add `csvColumns: CsvColumn<Job>[]` (job_id, job_type, status, run_id,
+      created_at, completed_at — exclude JSONB params/result) + "Export CSV"
+      Button (mirror runs.tsx:71-80,106-108,157-162).
+    - Add `enableColumnVisibility` to DataTable.
+    - Sortable headers via DataTableColumnHeader (status, job_type, created_at,
+      completed_at); job_id/params/actions non-sortable.
+    - useNavigate(); onRowClick={(job)=>navigate(`/explorer/jobs/${job.job_id}`)}.
+    - CRITICAL: wrap the `actions` cell content with
+      onClick={(e)=>e.stopPropagation()} so the cancel AlertDialog does not also
+      navigate to the job detail page.
+  VALIDATE: cd frontend && pnpm tsc --noEmit && pnpm lint &&
+    cd frontend && pnpm test --run
+
+Task 13 — Docs:
+  MODIFY README.md — mention run/job detail pages, run comparison, artifact verify,
+    table sorting in the feature list.
+  MODIFY docs/_base/API_CONTRACTS.md — note the new sort_by/sort_order params on the
+    GET /registry/runs and GET /jobs rows (mirror the /dimensions sort note from PRP-20).
+  MODIFY docs/_base/REPO_MAP_INDEX.md — add rows for run-detail.tsx / job-detail.tsx /
+    run-compare.tsx.
+
+Task 14 — Dogfood the running UI (mandatory per ui-design.md):
+  - docker compose up -d ; uv run alembic upgrade head ;
+    uv run python scripts/seed_random.py --full-new --seed 42 --confirm.
+  - Run `make demo` (or POST a few /jobs) so the registry + jobs tables have rows.
+  - uv run uvicorn app.main:app --port 8123 & ; cd frontend &&
+    ./node_modules/.bin/vite --host 0.0.0.0.
+  - Via webapp-testing / agent-browser, exercise the 10 scenarios in Validation
+    Level 4. Capture screenshots of all three new pages.
+
+Task 15 — Commit + PR:
+  Branch feat/explorer-runs-jobs-interactivity. Commits, each (#issue), no AI trailer:
+    1. feat(registry): add sort_by/sort_order to model-run listing (#N)
+    2. feat(jobs): add sort_by/sort_order to job listing (#N)
+    3. test(registry,jobs): cover list-endpoint sorting (#N)
+    4. feat(ui): add model-run and job detail pages (#N)
+    5. feat(ui): add run-vs-run comparison page (#N)
+    6. feat(ui): interactive Runs/Jobs tables — sorting, row-click, export, url state (#N)
+    7. docs(docs): document explorer runs/jobs interactivity (#N)
+  Open PR into dev; CI green; merge.
+```
+
+### Per-task pseudocode (highest-risk tasks)
+```python
+# Task 2/3 — the backend resolve-or-default ordering (registry shown; jobs identical)
+async def list_runs(self, db, page=1, page_size=20, model_type=None, status=None,
+                     store_id=None, product_id=None,
+                     sort_by=None, sort_order="asc"):
+    stmt = select(ModelRun)
+    # ... existing filter .where() clauses UNCHANGED ...
+    # ... existing count_stmt UNCHANGED ...
+    offset = (page - 1) * page_size
+    # PATTERN: allow-list resolve (dimensions/service.py:105-113). NEVER raw string.
+    sort_column = _RUN_SORT_COLUMNS.get(sort_by) if sort_by else None
+    if sort_column is not None:
+        order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+    else:
+        order_by = ModelRun.created_at.desc()  # UNCHANGED default
+    stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
+    # ... rest UNCHANGED ...
+```
+```typescript
+// Task 8 — the verify button (the one piece of genuinely new UI logic)
+const [verifyOn, setVerifyOn] = useState(false)
+const verify = useVerifyArtifact(runId ?? '', verifyOn)
+function onVerify() {
+  if (!verifyOn) setVerifyOn(true)   // first click → enable the query
+  else void verify.refetch()         // subsequent clicks → re-run
+}
+// render: verify.isFetching → spinner; verify.error → destructive alert (404/400);
+//   verify.data?.verified === true → green check + verify.data.computed_hash;
+//   verify.data?.verified === false → destructive alert + verify.data.error
+```
+
+### Integration Points
+```yaml
+DATABASE:  NONE — no migration, no schema change. ORDER BY only.
+BACKEND:   registry slice — +2 query params, allow-listed ordering on list_runs.
+           jobs slice — +2 query params, allow-listed ordering on list_jobs.
+           app/main.py UNCHANGED (both routers already wired).
+CONFIG:    NONE — no new env var.
+FRONTEND ROUTING:
+  - ROUTES.EXPLORER.RUN_DETAIL + JOB_DETAIL + RUN_COMPARE (constants.ts).
+  - Three lazy <Route>s in App.tsx (:runId / :jobId / static compare).
+  - NAV_ITEMS unchanged (detail/compare pages are click-through, not nav items).
+CI:
+  - No new workflow. ci.yml covers it. Because registry + jobs .py files change,
+    the ruff/mypy/pyright/pytest jobs are load-bearing — keep green.
+```
+
+---
+
+## Validation Loop
+
+### Level 1: Syntax & Style
+```bash
+uv run ruff check . && uv run ruff format --check .
+cd frontend && pnpm lint
+# Expected: zero errors. Fix before proceeding.
+```
+
+### Level 2: Type Checks
+```bash
+uv run mypy app/ && uv run pyright app/        # both --strict, both gate merge
+cd frontend && pnpm tsc --noEmit
+# Watch: the InstrumentedAttribute import + _RUN_SORT_COLUMNS / _JOB_SORT_COLUMNS
+# dict typing are the most likely strict-mode failures.
+```
+
+### Level 3: Unit + Integration Tests
+```bash
+uv run pytest -v -m "not integration"
+docker compose up -d && uv run alembic upgrade head
+uv run pytest -v -m integration app/features/registry/tests app/features/jobs/tests
+cd frontend && pnpm test --run
+# If integration tests fail on a stale local Postgres:
+#   docker compose down -v && docker compose up -d && uv run alembic upgrade head
+```
+
+### Level 4: Manual end-to-end (dogfood — REQUIRED, ui-design.md)
+```bash
+docker compose up -d && uv run alembic upgrade head
+uv run python scripts/seed_random.py --full-new --seed 42 --confirm
+make demo                                       # populate registry + jobs tables
+uv run uvicorn app.main:app --port 8123 &
+until curl -fs http://127.0.0.1:8123/health; do sleep 2; done
+cd frontend && ./node_modules/.bin/vite --host 0.0.0.0     # http://localhost:5173
+
+# Browser checks via webapp-testing / agent-browser:
+#  1. /explorer/runs → click a row → /explorer/runs/:id with profile, JSON
+#     config, metrics, runtime info.
+#  2. On a run detail page click "Verify integrity" → pass (or fail) result renders.
+#  3. Click "Compare with…" → /explorer/runs/compare?a=<id>; pick a second run →
+#     side-by-side + config_diff + metrics_diff render; URL carries ?a=&b=.
+#  4. Sort the Runs table by Model Type desc → order changes ACROSS pages.
+#  5. /explorer/jobs → click a row → /explorer/jobs/:id with params + result JSON.
+#  6. On a pending job detail page click "Cancel job" → status → cancelled.
+#  7. In the Jobs table, click a row's cancel ✕ → it cancels WITHOUT navigating.
+#  8. Export the Jobs table to CSV; toggle a column off via "View".
+#  9. Apply a filter + a sort on Runs, copy the URL, open in a new tab → identical.
+# 10. curl "http://localhost:8123/jobs?sort_by=status&sort_order=desc" → 200, ordered.
+```
+
+---
+
+## Final validation Checklist
+- [ ] `uv run ruff check . && uv run ruff format --check .` clean
+- [ ] `uv run mypy app/ && uv run pyright app/` clean (both --strict)
+- [ ] `uv run pytest -v -m "not integration"` green
+- [ ] `uv run pytest -v -m integration app/features/registry/tests app/features/jobs/tests` green
+- [ ] `cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run` clean
+- [ ] `GET /registry/runs` & `GET /jobs` accept sort_by/sort_order; omitted == prior
+      `created_at desc`; unknown sort_by → default order, no error
+- [ ] Row-click on Runs/Jobs → working detail pages with JSON config/metrics/result
+- [ ] Run comparison page renders config_diff + metrics_diff; deep-linkable via ?a=&b=
+- [ ] "Verify integrity" button surfaces pass/fail incl. the verified:false branch
+- [ ] Jobs table: CSV export + column visibility; in-row cancel does NOT navigate
+- [ ] Filter/sort/page state round-trips through the URL on both tables
+- [ ] No Alembic migration; no app/main.py change; no new slice; no .env var
+- [ ] README + API_CONTRACTS.md + REPO_MAP_INDEX.md updated
+- [ ] Branch `feat/explorer-runs-jobs-interactivity`; every commit references the
+      Task-1 issue; no AI co-author trailer
+- [ ] All three new pages dogfooded in a real browser (screenshots captured)
+
+---
+
+## Anti-Patterns to Avoid
+- ❌ Don't add an Alembic migration — sorting is a read-only ORDER BY; the schema
+  does not change.
+- ❌ Don't interpolate `sort_by` into the query — resolve it through the allow-list
+  dict to a real mapped column; unknown → default order, never 400.
+- ❌ Don't put `metrics`/`runtime_info`/`params`/`result` (JSONB) in the sort
+  allow-list — they cannot be ordered meaningfully.
+- ❌ Don't do client-only table sorting — DataTable is `manualSorting:true`; sort
+  MUST round-trip to the backend.
+- ❌ Don't `Number()`-parse `:runId` / `:jobId` — they are UUID-hex strings, not
+  integers (this differs from store-detail.tsx / product-detail.tsx).
+- ❌ Don't forget `e.stopPropagation()` on the Jobs table's in-row cancel button —
+  the row is now clickable.
+- ❌ Don't re-implement a page-size selector — `data-table-pagination.tsx` has one.
+- ❌ Don't edit `app/main.py` — both routers are already wired.
+- ❌ Don't rebuild DataTable / DataTableColumnHeader / csv-export / store-detail —
+  PRP-20 already shipped them; this PRP reuses them.
+- ❌ Don't mock the database in integration tests; don't create test runs without a
+  `test-` model_type prefix (registry cleanup) or test jobs without a `test`
+  job_id prefix (jobs cleanup).
+- ❌ Don't hand-roll the pages without `frontend-design` / `shadcn-ui`, and don't
+  claim "done" on a green `tsc` — dogfood in a real browser.
+- ❌ Don't `git push --force` on dev/main; no AI co-author trailers; every commit
+  references the open issue.
+
+---
+
+## Confidence Score
+
+**8 / 10** for one-pass implementation success.
+
+**Why solid:**
+- Almost entirely additive and mechanically patterned by PRP-20 — the backend
+  change is a verbatim copy of the `dimensions` allow-listed-sort pattern; the
+  three pages mirror `store-detail.tsx`; the table upgrades mirror `stores.tsx`;
+  the routes register exactly like the existing Explorer detail routes.
+- Every detail/compare/verify endpoint already exists and is tested — no new
+  backend route, no new service method, no new schema. Three of four hooks
+  (`useRun`/`useJob`/`useCompareRuns`) already exist; `DataTable` already supports
+  `onRowClick`/`sorting`/`enableColumnVisibility`. Only `useVerifyArtifact`,
+  `JsonBlock`, and `ArtifactVerifyResponse` are genuinely new.
+- Every cited file carries verified line numbers; the real traps (UUID-vs-numeric
+  id parsing, `stopPropagation` on the in-row cancel, the two test-cleanup prefix
+  conventions, verify returning 200-on-mismatch) are called out with the exact fix.
+- Validation gates are concrete, layered, and fast; the dogfood checklist has 10
+  explicit scenarios.
+
+**Why not higher:**
+- The `jobs` slice has **no DB test infrastructure** — Task 4 must stand up
+  `db_session`/`client` from scratch (copied from `registry`) plus a new
+  `test_routes.py`. This is the least-mechanical task and the most likely to need
+  a second pass (the same risk PRP-20 flagged for the `analytics` slice).
+- The three new pages are genuine UI composition — layout, hierarchy, the
+  verify-button state machine, and the URL-state sync need the real-browser
+  dogfood (Task 14); a green `tsc` will not catch a cramped detail page or a
+  dropped `useSearchParams` round-trip.
+- ≈22 files across two layers is a wide surface; the per-task `VALIDATE` keeps it
+  recoverable but a single clean pass is ambitious.
+
+All identified risks are caught by the validation loop (strict type-check +
+integration tests + browser dogfood) and the fixes are local. Executing the tasks
+in order and running each `VALIDATE` before moving on is what carries it.
diff --git a/README.md b/README.md
index 3dbd92dc..3e6d6f28 100644
--- a/README.md
+++ b/README.md
@@ -9,10 +9,13 @@ Portfolio-grade end-to-end retail demand forecasting system.
 - **Serving Layer**: Typed FastAPI endpoints (Pydantic v2 validation)
 - **Model Registry**: Run configs, metrics, artifacts, and data windows for reproducibility
 - **Dashboard**: React 19 + Vite + Tailwind CSS 4 + shadcn/ui for data exploration and model management
+- **Explorer**: Click-through detail pages for stores, products, model runs, and jobs; run-vs-run comparison and SHA-256 artifact integrity verification; server-side sortable, CSV-exportable tables with column-visibility toggles and URL-shareable filter/sort/page state across every Explorer page; date-scoped KPIs, revenue bar/line charts, and cross-filtering on the Sales page
 - **RAG Knowledge Base**: Postgres pgvector embeddings + evidence-grounded answers with citations
 - **Agentic Layer**: PydanticAI agents for autonomous experimentation and evidence-grounded Q&A with human-in-the-loop approval
 - **Data Seeder (The Forge)**: Reproducible synthetic data generator with realistic time-series patterns, scenario presets, and retail effects
 - **AI Models Console**: `/admin` → AI Models tab — swap the agent LLM (incl. fully-local Ollama), the RAG embedding model, and provider API keys at runtime; changes apply live with no restart
+- **Knowledge Page**: `/knowledge` — browse the indexed RAG corpus, run a live semantic search, and see the live system state (seeded data, model runs, deployment aliases) the agents draw on
+- **Agent Guide**: `/guide` — in-product reference for the two chat agents — their tools, the human-in-the-loop approval gate, live session limits, and copy-paste example prompts
 
 ## Quick Start
 
@@ -449,11 +452,13 @@ curl "http://localhost:8123/dimensions/products?search=Cola&category=Beverage"
 - 1-indexed pagination (page=1 is first page)
 - Case-insensitive search in code/sku and name fields
 - Filter by region, store_type, category, or brand
+- Optional `sort_by` / `sort_order` on the store and product lists (allow-listed columns; unknown values fall back to the default order)
 
 ### Analytics
 
 - `GET /analytics/kpis` - Compute aggregated KPIs for a date range
 - `GET /analytics/drilldowns` - Drill into data by dimension (store, product, category, region, date)
+- `GET /analytics/timeseries` - Period-bucketed sales series (day/week/month/quarter) for revenue-over-time charts
 
 **Example KPI Request:**
 ```bash
diff --git a/app/features/agents/agents/base.py b/app/features/agents/agents/base.py
index abade6c2..272e59e8 100644
--- a/app/features/agents/agents/base.py
+++ b/app/features/agents/agents/base.py
@@ -14,6 +14,7 @@
 import structlog
 from pydantic_ai import ModelRetry
 from pydantic_ai.models import Model
+from pydantic_ai.models.fallback import FallbackModel
 from pydantic_ai.models.openai import OpenAIChatModel
 from pydantic_ai.providers.ollama import OllamaProvider
 
@@ -120,6 +121,56 @@ def get_fallback_model() -> str:
     return settings.agent_fallback_model
 
 
+def build_agent_model_with_fallback() -> Model | str:
+    """Build the PydanticAI ``model`` argument, wrapping primary + fallback.
+
+    When the primary model raises a provider error — HTTP 5xx, rate limit,
+    timeout, i.e. any ``pydantic_ai.exceptions.ModelAPIError`` — PydanticAI's
+    :class:`FallbackModel` transparently retries the request against
+    ``agent_fallback_model``. This keeps an agent run alive through a transient
+    provider outage (e.g. a Gemini ``503 UNAVAILABLE``) instead of surfacing a
+    hard error. ``FallbackModel``'s default ``fallback_on=(ModelAPIError,)``
+    already covers that case.
+
+    The primary model is returned alone (no fallback wrapper) when:
+
+    - no fallback is configured, or it equals the primary identifier; or
+    - the fallback provider has no API key — wrapping it would only move the
+      failure, so the agent runs primary-only and logs a warning.
+
+    Returns:
+        A :class:`FallbackModel` (primary then fallback) when a usable fallback
+        is configured, otherwise the primary model argument from
+        :func:`build_agent_model`.
+
+    Raises:
+        ValueError: If the primary provider's API key is not configured
+            (fail-fast — an agent with no usable primary cannot run).
+    """
+    primary_id = get_model_identifier()
+    validate_api_key_for_model(primary_id)  # fail-fast on the primary
+    primary = build_agent_model(primary_id)
+
+    fallback_id = get_fallback_model()
+    if not fallback_id or fallback_id == primary_id:
+        return primary
+
+    try:
+        validate_api_key_for_model(fallback_id)
+    except ValueError:
+        logger.warning(
+            "agents.fallback_disabled",
+            reason="missing_api_key",
+            primary=primary_id,
+            fallback=fallback_id,
+        )
+        return primary
+
+    fallback = build_agent_model(fallback_id)
+    logger.info("agents.fallback_enabled", primary=primary_id, fallback=fallback_id)
+    return FallbackModel(primary, fallback)
+
+
 def get_agent_retries() -> int:
     """Get the configured retry budget for agent tool calls and output validation.
 
diff --git a/app/features/agents/agents/experiment.py b/app/features/agents/agents/experiment.py
index 22311139..7a2de475 100644
--- a/app/features/agents/agents/experiment.py
+++ b/app/features/agents/agents/experiment.py
@@ -19,13 +19,11 @@
     SAFETY_INSTRUCTIONS,
     SYSTEM_PROMPT_HEADER,
     TOOL_USAGE_INSTRUCTIONS,
-    build_agent_model,
+    build_agent_model_with_fallback,
     get_agent_retries,
-    get_model_identifier,
     get_model_settings,
     recoverable,
     requires_approval,
-    validate_api_key_for_model,
 )
 from app.features.agents.deps import AgentDeps
 from app.features.agents.schemas import ExperimentReport
@@ -83,9 +81,9 @@ def create_experiment_agent() -> Agent[AgentDeps, ExperimentReport]:
     Returns:
         Configured Agent instance with tools registered.
     """
-    identifier = get_model_identifier()
-    validate_api_key_for_model(identifier)  # Fail-fast validation
-    model = build_agent_model(identifier)  # str for cloud, Model object for ollama
+    # Primary model, wrapped in a FallbackModel so a transient provider error
+    # (HTTP 5xx, rate limit) on the primary transparently retries the fallback.
+    model = build_agent_model_with_fallback()
 
     retries = get_agent_retries()
     agent: Agent[AgentDeps, ExperimentReport] = Agent(
diff --git a/app/features/agents/agents/rag_assistant.py b/app/features/agents/agents/rag_assistant.py
index c2288409..8095c597 100644
--- a/app/features/agents/agents/rag_assistant.py
+++ b/app/features/agents/agents/rag_assistant.py
@@ -18,12 +18,10 @@
 from app.features.agents.agents.base import (
     SAFETY_INSTRUCTIONS,
     SYSTEM_PROMPT_HEADER,
-    build_agent_model,
+    build_agent_model_with_fallback,
     get_agent_retries,
-    get_model_identifier,
     get_model_settings,
     recoverable,
-    validate_api_key_for_model,
 )
 from app.features.agents.deps import AgentDeps
 from app.features.agents.schemas import RAGAnswer
@@ -78,9 +76,9 @@ def create_rag_assistant_agent() -> Agent[AgentDeps, RAGAnswer]:
     Returns:
         Configured Agent instance with tools registered.
     """
-    identifier = get_model_identifier()
-    validate_api_key_for_model(identifier)  # Fail-fast validation
-    model = build_agent_model(identifier)  # str for cloud, Model object for ollama
+    # Primary model, wrapped in a FallbackModel so a transient provider error
+    # (HTTP 5xx, rate limit) on the primary transparently retries the fallback.
+    model = build_agent_model_with_fallback()
 
     retries = get_agent_retries()
     agent: Agent[AgentDeps, RAGAnswer] = Agent(
diff --git a/app/features/agents/tests/test_base.py b/app/features/agents/tests/test_base.py
index 83193aed..ddfcd02b 100644
--- a/app/features/agents/tests/test_base.py
+++ b/app/features/agents/tests/test_base.py
@@ -8,6 +8,7 @@
 import pytest
 from pydantic_ai import ModelRetry
 from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart
+from pydantic_ai.models.fallback import FallbackModel
 from pydantic_ai.models.function import AgentInfo, FunctionModel
 from pydantic_ai.models.openai import OpenAIChatModel
 
@@ -15,6 +16,7 @@
 from app.features.agents.agents.base import (
     TOOL_USAGE_INSTRUCTIONS,
     build_agent_model,
+    build_agent_model_with_fallback,
     get_agent_retries,
     recoverable,
     validate_api_key_for_model,
@@ -62,6 +64,66 @@ def test_validate_api_key_for_model_ollama_skips_key_check():
     validate_api_key_for_model("ollama:llama3.1")
 
 
+def test_build_agent_model_with_fallback_wraps_primary_and_fallback():
+    """A distinct, key-backed fallback yields a FallbackModel wired primary-then-fallback.
+
+    Asserts the *order* via the public ``FallbackModel.models`` list — ``models[0]``
+    must be the primary (``agent_default_model``) and ``models[1]`` the fallback
+    (``agent_fallback_model``) — so a swap or misconfiguration is caught, not just
+    the wrapper type.
+    """
+    settings = get_settings()
+    settings.agent_default_model = "anthropic:claude-sonnet-4-5"
+    settings.agent_fallback_model = "openai:gpt-4o"
+    settings.anthropic_api_key = "test-anthropic-key"
+    settings.openai_api_key = "test-openai-key"
+
+    model = build_agent_model_with_fallback()
+
+    assert isinstance(model, FallbackModel)
+    # Each member model exposes its provider via `.system` and name via
+    # `.model_name`; recombine to the `provider:model` identifier we configured.
+    wired = [f"{m.system}:{m.model_name}" for m in model.models]
+    assert wired == [settings.agent_default_model, settings.agent_fallback_model]
+
+
+def test_build_agent_model_with_fallback_raises_when_primary_api_key_missing():
+    """Fail fast: a non-Ollama primary with no API key raises before any wrapping."""
+    settings = get_settings()
+    settings.agent_default_model = "anthropic:claude-sonnet-4-5"
+    settings.agent_fallback_model = "openai:gpt-4o"
+    settings.anthropic_api_key = ""
+    settings.openai_api_key = "test-openai-key"
+
+    with pytest.raises(ValueError, match="Anthropic API key not configured"):
+        build_agent_model_with_fallback()
+
+
+def test_build_agent_model_with_fallback_primary_only_when_fallback_key_missing():
+    """With no API key for the fallback provider, the primary is returned alone."""
+    settings = get_settings()
+    settings.agent_default_model = "anthropic:claude-sonnet-4-5"
+    settings.agent_fallback_model = "openai:gpt-4o"
+    settings.anthropic_api_key = "test-anthropic-key"
+    settings.openai_api_key = ""
+
+    model = build_agent_model_with_fallback()
+
+    assert model == "anthropic:claude-sonnet-4-5"
+
+
+def test_build_agent_model_with_fallback_primary_only_when_fallback_equals_primary():
+    """A fallback identical to the primary adds no resilience — primary returned alone."""
+    settings = get_settings()
+    settings.agent_default_model = "anthropic:claude-sonnet-4-5"
+    settings.agent_fallback_model = "anthropic:claude-sonnet-4-5"
+    settings.anthropic_api_key = "test-anthropic-key"
+
+    model = build_agent_model_with_fallback()
+
+    assert model == "anthropic:claude-sonnet-4-5"
+
+
 def test_prompts_only_reference_registered_tool_names() -> None:
     """Every `tool_*` name in the agent prompts must be an actually-registered tool.
 
diff --git a/app/features/analytics/routes.py b/app/features/analytics/routes.py
index c2dbf4c7..eab4b9fb 100644
--- a/app/features/analytics/routes.py
+++ b/app/features/analytics/routes.py
@@ -16,6 +16,8 @@
     DrilldownDimension,
     DrilldownResponse,
     KPIResponse,
+    TimeGranularity,
+    TimeSeriesResponse,
 )
 from app.features.analytics.service import AnalyticsService
 
@@ -247,3 +249,96 @@ async def get_drilldowns(
         product_id=product_id,
         max_items=max_items,
     )
+
+
+# =============================================================================
+# Time Series Endpoints
+# =============================================================================
+
+
+@router.get(
+    "/timeseries",
+    response_model=TimeSeriesResponse,
+    summary="Compute a period-bucketed sales time series",
+    description="""
+Aggregate sales into a time series bucketed by day, week, month, or quarter.
+
+**Purpose**: Drive revenue-over-time charts. Unlike `/drilldowns?dimension=date`,
+this endpoint orders points by period (not revenue), supports week/month/quarter
+bucketing, and is not capped at 100 items.
+
+**Metrics per period**: same `KPIMetrics` shape as `/analytics/kpis` —
+`total_revenue`, `total_units`, `total_transactions`, `avg_unit_price`,
+`avg_basket_value`.
+
+**Filtering Options**:
+- `store_id`: scope the series to a single store
+- `product_id`: scope the series to a single product
+- `category`: scope the series to a product category (exact match)
+
+**Date Range**:
+- Both `start_date` and `end_date` are inclusive
+- Maximum range: 730 days (2 years)
+
+**Example Use Cases**:
+1. Daily revenue trend: `GET /analytics/timeseries?start_date=2024-01-01&end_date=2024-03-31&granularity=day`
+2. Weekly trend for a store: `GET /analytics/timeseries?store_id=5&start_date=2024-01-01&end_date=2024-12-31&granularity=week`
+""",
+)
+async def get_timeseries(
+    start_date: date = Query(
+        ...,
+        description="Start of analysis period (inclusive). Format: YYYY-MM-DD.",
+    ),
+    end_date: date = Query(
+        ...,
+        description="End of analysis period (inclusive). Format: YYYY-MM-DD.",
+    ),
+    granularity: TimeGranularity = Query(
+        TimeGranularity.DAY,
+        description="Bucket size: day, week, month, or quarter.",
+    ),
+    store_id: int | None = Query(
+        None,
+        description="Filter by store ID. Use GET /dimensions/stores to find valid IDs.",
+    ),
+    product_id: int | None = Query(
+        None,
+        description="Filter by product ID. Use GET /dimensions/products to find valid IDs.",
+    ),
+    category: str | None = Query(
+        None,
+        description="Filter by product category name (exact match).",
+    ),
+    db: AsyncSession = Depends(get_db),
+) -> TimeSeriesResponse:
+    """Compute a period-bucketed sales time series with optional filters.
+
+    Args:
+        start_date: Start of analysis period (inclusive).
+        end_date: End of analysis period (inclusive).
+        granularity: Bucket size (day, week, month, quarter).
+        store_id: Filter by store ID (optional).
+        product_id: Filter by product ID (optional).
+        category: Filter by category (optional).
+        db: Database session.
+
+    Returns:
+        Time series response with points in ascending period order.
+
+    Raises:
+        HTTPException: If date range is invalid.
+    """
+    # Validate date range before processing
+    validate_date_range(start_date, end_date)
+
+    service = AnalyticsService()
+    return await service.compute_timeseries(
+        db=db,
+        start_date=start_date,
+        end_date=end_date,
+        granularity=granularity,
+        store_id=store_id,
+        product_id=product_id,
+        category=category,
+    )
diff --git a/app/features/analytics/schemas.py b/app/features/analytics/schemas.py
index 576cd671..f5528b33 100644
--- a/app/features/analytics/schemas.py
+++ b/app/features/analytics/schemas.py
@@ -191,6 +191,69 @@ class DrilldownResponse(BaseModel):
     )
 
 
+# =============================================================================
+# Time Series Response Schemas
+# =============================================================================
+
+
+class TimeSeriesPoint(BaseModel):
+    """One aggregated period of the sales time series."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    period: date = Field(
+        ...,
+        description="Bucket start date (the day itself, or the first day of "
+        "the week/month/quarter bucket).",
+    )
+    metrics: KPIMetrics = Field(
+        ...,
+        description="Aggregated KPI metrics for this period.",
+    )
+
+
+class TimeSeriesResponse(BaseModel):
+    """Period-bucketed sales time series for charting.
+
+    Points are ordered ascending by period. Use this to render
+    revenue-over-time trends scoped to a store, product, or category.
+    """
+
+    granularity: TimeGranularity = Field(
+        ...,
+        description="Bucket size used for aggregation (day, week, month, quarter).",
+    )
+    points: list[TimeSeriesPoint] = Field(
+        ...,
+        description="Time series points in ascending period order.",
+    )
+    total_points: int = Field(
+        ...,
+        ge=0,
+        description="Number of points returned (equals len(points)).",
+    )
+    start_date: date = Field(
+        ...,
+        description="Start of the analysis period (inclusive).",
+    )
+    end_date: date = Field(
+        ...,
+        description="End of the analysis period (inclusive).",
+    )
+    store_id: int | None = Field(
+        None,
+        description="Store filter applied (if any). Null means all stores included.",
+    )
+    product_id: int | None = Field(
+        None,
+        description="Product filter applied (if any). Null means all products included.",
+    )
+    category: str | None = Field(
+        None,
+        description="Category filter applied (if any). Null means all categories included.",
+    )
+
+
 # =============================================================================
 # Date Range Validation
 # =============================================================================
diff --git a/app/features/analytics/service.py b/app/features/analytics/service.py
index 4654efed..51d6f17b 100644
--- a/app/features/analytics/service.py
+++ b/app/features/analytics/service.py
@@ -7,7 +7,8 @@
 from decimal import Decimal
 from typing import Any, cast
 
-from sqlalchemy import ColumnElement, func, select
+from sqlalchemy import ColumnElement, Date, func, select
+from sqlalchemy import cast as sa_cast
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 
@@ -19,6 +20,9 @@
     DrilldownResponse,
     KPIMetrics,
     KPIResponse,
+    TimeGranularity,
+    TimeSeriesPoint,
+    TimeSeriesResponse,
 )
 from app.features.data_platform.models import Product, SalesDaily, Store
 
@@ -282,3 +286,103 @@ async def compute_drilldown(
             store_id=store_id,
             product_id=product_id,
         )
+
+    async def compute_timeseries(
+        self,
+        db: AsyncSession,
+        start_date: date,
+        end_date: date,
+        granularity: TimeGranularity = TimeGranularity.DAY,
+        store_id: int | None = None,
+        product_id: int | None = None,
+        category: str | None = None,
+    ) -> TimeSeriesResponse:
+        """Compute a period-bucketed sales time series.
+
+        Args:
+            db: Database session.
+            start_date: Start of analysis period (inclusive).
+            end_date: End of analysis period (inclusive).
+            granularity: Bucket size (day, week, month, quarter).
+            store_id: Filter by store ID (optional).
+            product_id: Filter by product ID (optional).
+            category: Filter by category (optional).
+
+        Returns:
+            Time series response with points in ascending period order.
+        """
+        # Bucket expression: DAY uses the raw date column; coarser
+        # granularities truncate via date_trunc and cast back to a DATE so
+        # the resulting period validates as a `datetime.date`.
+        bucket: ColumnElement[Any]
+        if granularity == TimeGranularity.DAY:
+            bucket = cast(ColumnElement[Any], SalesDaily.date)
+        else:
+            bucket = cast(
+                ColumnElement[Any],
+                sa_cast(func.date_trunc(granularity.value, SalesDaily.date), Date),
+            )
+
+        # Same aggregation/filter shape as compute_kpis, grouped per bucket.
+        stmt = select(
+            bucket.label("period"),
+            func.coalesce(func.sum(SalesDaily.total_amount), 0).label("total_revenue"),
+            func.coalesce(func.sum(SalesDaily.quantity), 0).label("total_units"),
+            func.count().label("total_transactions"),
+        ).where((SalesDaily.date >= start_date) & (SalesDaily.date <= end_date))
+
+        if store_id is not None:
+            stmt = stmt.where(SalesDaily.store_id == store_id)
+        if product_id is not None:
+            stmt = stmt.where(SalesDaily.product_id == product_id)
+        if category is not None:
+            stmt = stmt.join(Product, SalesDaily.product_id == Product.id).where(
+                Product.category == category
+            )
+
+        stmt = stmt.group_by(bucket).order_by(bucket)
+
+        result = await db.execute(stmt)
+        rows = result.all()
+
+        points: list[TimeSeriesPoint] = []
+        for row in rows:
+            revenue = Decimal(str(row.total_revenue))
+            units = int(row.total_units)
+            transactions = int(row.total_transactions)
+            avg_unit_price = revenue / units if units > 0 else None
+            avg_basket_value = revenue / transactions if transactions > 0 else None
+            points.append(
+                TimeSeriesPoint(
+                    period=row.period,
+                    metrics=KPIMetrics(
+                        total_revenue=revenue,
+                        total_units=units,
+                        total_transactions=transactions,
+                        avg_unit_price=avg_unit_price,
+                        avg_basket_value=avg_basket_value,
+                    ),
+                )
+            )
+
+        logger.info(
+            "analytics.timeseries_computed",
+            granularity=granularity.value,
+            start_date=str(start_date),
+            end_date=str(end_date),
+            store_id=store_id,
+            product_id=product_id,
+            category=category,
+            points=len(points),
+        )
+
+        return TimeSeriesResponse(
+            granularity=granularity,
+            points=points,
+            total_points=len(points),
+            start_date=start_date,
+            end_date=end_date,
+            store_id=store_id,
+            product_id=product_id,
+            category=category,
+        )
diff --git a/app/features/analytics/tests/conftest.py b/app/features/analytics/tests/conftest.py
index 827960ad..b0e07620 100644
--- a/app/features/analytics/tests/conftest.py
+++ b/app/features/analytics/tests/conftest.py
@@ -1,10 +1,17 @@
 """Test fixtures for analytics module."""
 
-from datetime import date
+import uuid
+from collections.abc import AsyncGenerator
+from datetime import date, timedelta
 from decimal import Decimal
 
 import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
+from app.core.config import get_settings
+from app.core.database import get_db
 from app.features.analytics.schemas import (
     DrilldownDimension,
     DrilldownItem,
@@ -12,6 +19,8 @@
     KPIMetrics,
     KPIResponse,
 )
+from app.features.data_platform.models import Calendar, Product, SalesDaily, Store
+from app.main import app
 
 
 @pytest.fixture
@@ -80,3 +89,148 @@ def sample_drilldown_response(
         store_id=None,
         product_id=None,
     )
+
+
+# =============================================================================
+# Database Fixtures for Integration Tests
+# =============================================================================
+
+
+@pytest.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    """Create an async database session for integration tests.
+
+    Yields a session, then cleans up TEST-prefixed data and the test
+    calendar range. Requires PostgreSQL (docker-compose up -d).
+    """
+    settings = get_settings()
+    engine = create_async_engine(settings.database_url, echo=False)
+
+    async_session_maker = async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+    async with async_session_maker() as session:
+        try:
+            yield session
+        finally:
+            # Clean up test data (delete in FK-safe order).
+            await session.execute(delete(SalesDaily))
+            await session.execute(delete(Product).where(Product.sku.like("TEST-%")))
+            await session.execute(delete(Store).where(Store.code.like("TEST-%")))
+            await session.execute(
+                delete(Calendar).where(
+                    (Calendar.date >= date(2024, 1, 1)) & (Calendar.date <= date(2024, 4, 29))
+                )
+            )
+            await session.commit()
+
+    await engine.dispose()
+
+
+@pytest.fixture
+async def client(db_session: AsyncSession) -> AsyncGenerator[AsyncClient, None]:
+    """Create a test client with the database dependency overridden."""
+
+    async def override_get_db() -> AsyncGenerator[AsyncSession, None]:
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as ac:
+        yield ac
+
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture
+async def sample_store(db_session: AsyncSession) -> Store:
+    """Create a sample store with a unique TEST- code."""
+    unique_id = uuid.uuid4().hex[:8]
+    store = Store(
+        code=f"TEST-{unique_id}",
+        name="Test Store",
+        region="Test Region",
+        city="Test City",
+        store_type="supermarket",
+    )
+    db_session.add(store)
+    await db_session.commit()
+    await db_session.refresh(store)
+    return store
+
+
+@pytest.fixture
+async def sample_product(db_session: AsyncSession) -> Product:
+    """Create a sample product with a unique TEST- SKU."""
+    unique_id = uuid.uuid4().hex[:8]
+    product = Product(
+        sku=f"TEST-{unique_id}",
+        name="Test Product",
+        category="Test Category",
+        brand="Test Brand",
+        base_price=Decimal("19.99"),
+        base_cost=Decimal("9.99"),
+    )
+    db_session.add(product)
+    await db_session.commit()
+    await db_session.refresh(product)
+    return product
+
+
+@pytest.fixture
+async def sample_calendar_120(db_session: AsyncSession) -> list[Calendar]:
+    """Create 120 calendar records starting from 2024-01-01 (idempotent)."""
+    start = date(2024, 1, 1)
+    calendars = []
+
+    for i in range(120):
+        d = start + timedelta(days=i)
+        calendar = Calendar(
+            date=d,
+            day_of_week=d.weekday(),
+            month=d.month,
+            quarter=(d.month - 1) // 3 + 1,
+            year=d.year,
+            is_holiday=False,
+        )
+        merged = await db_session.merge(calendar)
+        calendars.append(merged)
+
+    await db_session.commit()
+    return calendars
+
+
+@pytest.fixture
+async def sample_sales_120(
+    db_session: AsyncSession,
+    sample_store: Store,
+    sample_product: Product,
+    sample_calendar_120: list[Calendar],
+) -> list[SalesDaily]:
+    """Create 120 days of sequential sales (quantity = day number 1..120)."""
+    sales_records = []
+
+    for i, calendar in enumerate(sample_calendar_120):
+        quantity = i + 1
+        unit_price = Decimal("9.99")
+        sales = SalesDaily(
+            date=calendar.date,
+            store_id=sample_store.id,
+            product_id=sample_product.id,
+            quantity=quantity,
+            unit_price=unit_price,
+            total_amount=unit_price * quantity,
+        )
+        sales_records.append(sales)
+        db_session.add(sales)
+
+    await db_session.commit()
+    for sale in sales_records:
+        await db_session.refresh(sale)
+    return sales_records
diff --git a/app/features/analytics/tests/test_routes_integration.py b/app/features/analytics/tests/test_routes_integration.py
new file mode 100644
index 00000000..7a74e678
--- /dev/null
+++ b/app/features/analytics/tests/test_routes_integration.py
@@ -0,0 +1,180 @@
+"""Integration tests for analytics routes.
+
+Runs against a real PostgreSQL database to verify the full flow from API
+request through SQL aggregation to response.
+
+Requires PostgreSQL to be running: docker-compose up -d
+"""
+
+from decimal import Decimal
+
+import pytest
+from httpx import AsyncClient
+
+from app.features.data_platform.models import Product, SalesDaily, Store
+
+# Sum of quantities 1..120 = 7260; revenue = 9.99 * 7260.
+_EXPECTED_UNITS = 7260
+_EXPECTED_REVENUE = Decimal("9.99") * _EXPECTED_UNITS
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+class TestAnalyticsTimeseriesIntegration:
+    """Integration tests for GET /analytics/timeseries."""
+
+    async def test_timeseries_day_granularity(
+        self,
+        client: AsyncClient,
+        sample_store: Store,
+        sample_product: Product,
+        sample_sales_120: list[SalesDaily],
+    ) -> None:
+        """Day granularity returns one ascending point per sales day."""
+        response = await client.get(
+            "/analytics/timeseries",
+            params={
+                "start_date": "2024-01-01",
+                "end_date": "2024-04-29",
+                "granularity": "day",
+                "store_id": sample_store.id,
+            },
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["granularity"] == "day"
+
+        points = data["points"]
+        assert len(points) == 120
+        assert len(points) == data["total_points"]
+
+        periods = [p["period"] for p in points]
+        assert periods == sorted(periods), "Points must be ascending by period"
+
+        # quantity == day number: first day sold 1 unit.
+        assert points[0]["period"] == "2024-01-01"
+        assert points[0]["metrics"]["total_units"] == 1
+
+    async def test_timeseries_week_granularity(
+        self,
+        client: AsyncClient,
+        sample_store: Store,
+        sample_product: Product,
+        sample_sales_120: list[SalesDaily],
+    ) -> None:
+        """Week granularity buckets days into ascending weekly periods."""
+        response = await client.get(
+            "/analytics/timeseries",
+            params={
+                "start_date": "2024-01-01",
+                "end_date": "2024-04-29",
+                "granularity": "week",
+                "store_id": sample_store.id,
+            },
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["granularity"] == "week"
+
+        points = data["points"]
+        assert 0 < len(points) < 120, "Weekly buckets collapse the 120 days"
+        assert len(points) == data["total_points"]
+
+        periods = [p["period"] for p in points]
+        assert periods == sorted(periods), "Points must be ascending by period"
+
+    async def test_timeseries_store_filter_isolates_revenue(
+        self,
+        client: AsyncClient,
+        sample_store: Store,
+        sample_product: Product,
+        sample_sales_120: list[SalesDaily],
+    ) -> None:
+        """The store_id filter scopes the series and is echoed in the response."""
+        response = await client.get(
+            "/analytics/timeseries",
+            params={
+                "start_date": "2024-01-01",
+                "end_date": "2024-04-29",
+                "granularity": "day",
+                "store_id": sample_store.id,
+            },
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["store_id"] == sample_store.id
+
+        total = sum(Decimal(p["metrics"]["total_revenue"]) for p in data["points"])
+        assert total == _EXPECTED_REVENUE
+
+    async def test_timeseries_inverted_range_returns_400(
+        self,
+        client: AsyncClient,
+    ) -> None:
+        """end_date before start_date is rejected with a 400."""
+        response = await client.get(
+            "/analytics/timeseries",
+            params={
+                "start_date": "2024-04-29",
+                "end_date": "2024-01-01",
+                "granularity": "day",
+            },
+        )
+
+        assert response.status_code == 400
+        assert "detail" in response.json()
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+class TestAnalyticsSmokeIntegration:
+    """Smoke tests for the pre-existing analytics endpoints (no slice tests today)."""
+
+    async def test_kpis_smoke(
+        self,
+        client: AsyncClient,
+        sample_store: Store,
+        sample_product: Product,
+        sample_sales_120: list[SalesDaily],
+    ) -> None:
+        """GET /analytics/kpis aggregates the seeded sales for the test store."""
+        response = await client.get(
+            "/analytics/kpis",
+            params={
+                "start_date": "2024-01-01",
+                "end_date": "2024-04-29",
+                "store_id": sample_store.id,
+            },
+        )
+
+        assert response.status_code == 200
+        metrics = response.json()["metrics"]
+        assert metrics["total_units"] == _EXPECTED_UNITS
+        assert metrics["total_transactions"] == 120
+        assert Decimal(metrics["total_revenue"]) == _EXPECTED_REVENUE
+
+    async def test_drilldowns_smoke(
+        self,
+        client: AsyncClient,
+        sample_store: Store,
+        sample_product: Product,
+        sample_sales_120: list[SalesDaily],
+    ) -> None:
+        """GET /analytics/drilldowns by date returns ranked items."""
+        response = await client.get(
+            "/analytics/drilldowns",
+            params={
+                "dimension": "date",
+                "start_date": "2024-01-01",
+                "end_date": "2024-04-29",
+                "store_id": sample_store.id,
+            },
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["dimension"] == "date"
+        assert len(data["items"]) >= 1
diff --git a/app/features/analytics/tests/test_schemas.py b/app/features/analytics/tests/test_schemas.py
new file mode 100644
index 00000000..1eb97a46
--- /dev/null
+++ b/app/features/analytics/tests/test_schemas.py
@@ -0,0 +1,77 @@
+"""Unit tests for analytics time-series schemas.
+
+These tests run without a database (-m "not integration").
+"""
+
+from datetime import date
+from decimal import Decimal
+
+import pytest
+from pydantic import ValidationError
+
+from app.features.analytics.schemas import (
+    KPIMetrics,
+    TimeGranularity,
+    TimeSeriesPoint,
+    TimeSeriesResponse,
+)
+
+
+def test_time_series_point_construct() -> None:
+    """A TimeSeriesPoint carries a period date and nested KPI metrics."""
+    point = TimeSeriesPoint(
+        period=date(2024, 1, 1),
+        metrics=KPIMetrics(
+            total_revenue=Decimal("100.00"),
+            total_units=10,
+            total_transactions=2,
+            avg_unit_price=Decimal("10.00"),
+            avg_basket_value=Decimal("50.00"),
+        ),
+    )
+    assert point.period == date(2024, 1, 1)
+    assert point.metrics.total_units == 10
+    assert point.metrics.total_revenue == Decimal("100.00")
+
+
+def test_time_series_response_construct(sample_kpi_metrics: KPIMetrics) -> None:
+    """A TimeSeriesResponse aggregates points with metadata; filters default None."""
+    points = [
+        TimeSeriesPoint(period=date(2024, 1, day), metrics=sample_kpi_metrics) for day in (1, 2, 3)
+    ]
+    response = TimeSeriesResponse(
+        granularity=TimeGranularity.WEEK,
+        points=points,
+        total_points=len(points),
+        start_date=date(2024, 1, 1),
+        end_date=date(2024, 1, 3),
+    )
+    assert response.total_points == 3
+    assert response.granularity == TimeGranularity.WEEK
+    assert response.store_id is None
+    assert response.product_id is None
+    assert response.category is None
+
+
+def test_time_series_response_granularity_coercion() -> None:
+    """A bare string granularity coerces to the TimeGranularity enum."""
+    response = TimeSeriesResponse(
+        granularity="day",  # type: ignore[arg-type]
+        points=[],
+        total_points=0,
+        start_date=date(2024, 1, 1),
+        end_date=date(2024, 1, 1),
+    )
+    assert response.granularity is TimeGranularity.DAY
+
+
+def test_time_series_response_rejects_negative_total_points() -> None:
+    """total_points has a ge=0 constraint."""
+    with pytest.raises(ValidationError):
+        TimeSeriesResponse(
+            granularity=TimeGranularity.DAY,
+            points=[],
+            total_points=-1,
+            start_date=date(2024, 1, 1),
+            end_date=date(2024, 1, 1),
+        )
diff --git a/app/features/config/schemas.py b/app/features/config/schemas.py
index cca1ae0d..60d75c1e 100644
--- a/app/features/config/schemas.py
+++ b/app/features/config/schemas.py
@@ -72,6 +72,13 @@ class AIModelConfig(BaseModel):
     agent_thinking_budget: int | None = Field(
         description="Extended-reasoning token budget (Gemini 2.5+); None disables it"
     )
+    agent_max_tool_calls: int = Field(description="Per-session tool-call cap")
+    agent_timeout_seconds: int = Field(description="Per-run agent timeout (seconds)")
+    agent_retry_attempts: int = Field(description="Agent retry attempts on failure")
+    agent_session_ttl_minutes: int = Field(description="Session time-to-live (minutes)")
+    agent_require_approval: list[str] = Field(
+        description="Tool names gated by human-in-the-loop approval"
+    )
     rag_embedding_provider: str = Field(description="RAG embedding provider: 'openai' | 'ollama'")
     rag_embedding_model: str = Field(description="OpenAI embedding model name")
     rag_embedding_dimension: int = Field(description="Embedding vector dimension")
diff --git a/app/features/config/service.py b/app/features/config/service.py
index a9c5da6e..b4967ef8 100644
--- a/app/features/config/service.py
+++ b/app/features/config/service.py
@@ -144,6 +144,11 @@ async def get_effective_config(db: AsyncSession) -> AIModelConfig:
         agent_temperature=settings.agent_temperature,
         agent_max_tokens=settings.agent_max_tokens,
         agent_thinking_budget=settings.agent_thinking_budget,
+        agent_max_tool_calls=settings.agent_max_tool_calls,
+        agent_timeout_seconds=settings.agent_timeout_seconds,
+        agent_retry_attempts=settings.agent_retry_attempts,
+        agent_session_ttl_minutes=settings.agent_session_ttl_minutes,
+        agent_require_approval=list(settings.agent_require_approval),
         rag_embedding_provider=settings.rag_embedding_provider,
         rag_embedding_model=settings.rag_embedding_model,
         rag_embedding_dimension=settings.rag_embedding_dimension,
diff --git a/app/features/config/tests/test_routes.py b/app/features/config/tests/test_routes.py
index 2f064afe..4675d145 100644
--- a/app/features/config/tests/test_routes.py
+++ b/app/features/config/tests/test_routes.py
@@ -27,6 +27,11 @@ def _sample_config(
         agent_temperature=agent_temperature,
         agent_max_tokens=4096,
         agent_thinking_budget=None,
+        agent_max_tool_calls=10,
+        agent_timeout_seconds=120,
+        agent_retry_attempts=3,
+        agent_session_ttl_minutes=120,
+        agent_require_approval=["create_alias", "archive_run"],
         rag_embedding_provider="openai",
         rag_embedding_model="text-embedding-3-small",
         rag_embedding_dimension=1536,
@@ -65,6 +70,22 @@ def test_returns_effective_config(self, client):
         assert data["agent_default_model"] == "anthropic:claude-sonnet-4-5"
         assert data["api_keys"][0]["masked"] == "sk-ant-…1234"
 
+    def test_returns_agent_session_limits(self, client):
+        """GET /config/ai exposes the read-only agent session-limit fields."""
+        with patch(
+            "app.features.config.routes.service.get_effective_config",
+            new=AsyncMock(return_value=_sample_config()),
+        ):
+            response = client.get("/config/ai")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["agent_max_tool_calls"] == 10
+        assert data["agent_timeout_seconds"] == 120
+        assert data["agent_retry_attempts"] == 3
+        assert data["agent_session_ttl_minutes"] == 120
+        assert data["agent_require_approval"] == ["create_alias", "archive_run"]
+
 
 class TestUpdateAIConfig:
     """Tests for PATCH /config/ai."""
diff --git a/app/features/config/tests/test_schemas.py b/app/features/config/tests/test_schemas.py
index c11232df..c1fd8712 100644
--- a/app/features/config/tests/test_schemas.py
+++ b/app/features/config/tests/test_schemas.py
@@ -105,6 +105,11 @@ def test_ai_model_config_constructs(self):
             agent_temperature=0.1,
             agent_max_tokens=4096,
             agent_thinking_budget=None,
+            agent_max_tool_calls=10,
+            agent_timeout_seconds=120,
+            agent_retry_attempts=3,
+            agent_session_ttl_minutes=120,
+            agent_require_approval=["create_alias", "archive_run"],
             rag_embedding_provider="openai",
             rag_embedding_model="text-embedding-3-small",
             rag_embedding_dimension=1536,
@@ -115,6 +120,33 @@ def test_ai_model_config_constructs(self):
         )
         assert cfg.agent_thinking_budget is None
 
+    def test_ai_model_config_carries_agent_limits(self):
+        """AIModelConfig exposes the read-only agent session-limit fields."""
+        cfg = AIModelConfig(
+            agent_default_model="anthropic:claude-sonnet-4-5",
+            agent_fallback_model="openai:gpt-4o",
+            agent_temperature=0.1,
+            agent_max_tokens=4096,
+            agent_thinking_budget=None,
+            agent_max_tool_calls=10,
+            agent_timeout_seconds=120,
+            agent_retry_attempts=3,
+            agent_session_ttl_minutes=120,
+            agent_require_approval=["create_alias", "archive_run"],
+            rag_embedding_provider="openai",
+            rag_embedding_model="text-embedding-3-small",
+            rag_embedding_dimension=1536,
+            ollama_base_url="http://localhost:11434",
+            ollama_embedding_model="nomic-embed-text",
+            api_keys=[],
+            overridden_keys=[],
+        )
+        assert cfg.agent_max_tool_calls == 10
+        assert cfg.agent_timeout_seconds == 120
+        assert cfg.agent_retry_attempts == 3
+        assert cfg.agent_session_ttl_minutes == 120
+        assert cfg.agent_require_approval == ["create_alias", "archive_run"]
+
     def test_api_key_status(self):
         """ApiKeyStatus carries presence + a masked preview."""
         status = ApiKeyStatus(provider="anthropic", is_set=True, masked="sk-ant-…3f9a")
diff --git a/app/features/config/tests/test_service.py b/app/features/config/tests/test_service.py
index edaf5866..e97009c1 100644
--- a/app/features/config/tests/test_service.py
+++ b/app/features/config/tests/test_service.py
@@ -97,6 +97,24 @@ async def test_get_effective_config_masks_secrets(self):
         assert anthropic.masked is not None
         assert "supersecretvalue" not in config.model_dump_json()
 
+    @pytest.mark.asyncio
+    async def test_get_effective_config_maps_agent_limits(self):
+        """The agent session-limit fields are sourced from the Settings singleton."""
+        settings = get_settings()
+        settings.agent_max_tool_calls = 7
+        settings.agent_timeout_seconds = 99
+        settings.agent_retry_attempts = 2
+        settings.agent_session_ttl_minutes = 45
+        settings.agent_require_approval = ["create_alias"]
+
+        config = await service.get_effective_config(_mock_db())
+
+        assert config.agent_max_tool_calls == 7
+        assert config.agent_timeout_seconds == 99
+        assert config.agent_retry_attempts == 2
+        assert config.agent_session_ttl_minutes == 45
+        assert config.agent_require_approval == ["create_alias"]
+
 
 # =============================================================================
 # Unit tests — update_config
diff --git a/app/features/demo/pipeline.py b/app/features/demo/pipeline.py
index 4302565f..10669ce1 100644
--- a/app/features/demo/pipeline.py
+++ b/app/features/demo/pipeline.py
@@ -29,7 +29,7 @@
 import time
 from collections.abc import AsyncIterator, Awaitable, Callable
 from dataclasses import dataclass, field
-from datetime import date, timedelta
+from datetime import UTC, date, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
@@ -55,8 +55,10 @@
 DEMO_SCENARIO = "demo_minimal"
 DEMO_SEED_STORES = 3
 DEMO_SEED_PRODUCTS = 10
-DEMO_SEED_START = date(2024, 10, 1)
-DEMO_SEED_END = date(2024, 12, 31)
+# Seed window is anchored to *today* so the showcase always demos
+# current-looking data; it runs DEMO_SEED_SPAN_DAYS back from today (92 days
+# inclusive). Must stay >= 72 for a non-NaN backtest WAPE (see step_backtest).
+DEMO_SEED_SPAN_DAYS = 91
 
 DEMO_MODEL_TYPES: tuple[str, ...] = ("naive", "seasonal_naive", "moving_average")
 
@@ -272,6 +274,8 @@ async def step_seed(ctx: DemoContext, client: _Client) -> StepResult:
     """Seed the ``demo_minimal`` scenario (skipped when ``skip_seed`` is set)."""
     if ctx.skip_seed:
         return ("skip", "skip_seed=true (assuming a seeded database)", {})
+    seed_end = datetime.now(UTC).date()
+    seed_start = seed_end - timedelta(days=DEMO_SEED_SPAN_DAYS)
     body = await client.request(
         "seed",
         "POST",
@@ -281,8 +285,8 @@ async def step_seed(ctx: DemoContext, client: _Client) -> StepResult:
             "seed": ctx.seed,
             "stores": DEMO_SEED_STORES,
             "products": DEMO_SEED_PRODUCTS,
-            "start_date": DEMO_SEED_START.isoformat(),
-            "end_date": DEMO_SEED_END.isoformat(),
+            "start_date": seed_start.isoformat(),
+            "end_date": seed_end.isoformat(),
             "sparsity": 0.0,
             "dry_run": False,
         },
diff --git a/app/features/dimensions/routes.py b/app/features/dimensions/routes.py
index 9042966e..07d5b5e8 100644
--- a/app/features/dimensions/routes.py
+++ b/app/features/dimensions/routes.py
@@ -67,6 +67,16 @@ async def list_stores(
         min_length=2,
         description="Search in code and name (case-insensitive)",
     ),
+    sort_by: str | None = Query(
+        None,
+        description="Sort column: code, name, region, city, or store_type. "
+        "Unknown values fall back to the default order (code).",
+    ),
+    sort_order: str = Query(
+        "asc",
+        pattern="^(asc|desc)$",
+        description="Sort direction: asc or desc.",
+    ),
 ) -> StoreListResponse:
     """List stores with pagination and filtering.
 
@@ -77,6 +87,8 @@ async def list_stores(
         region: Filter by region.
         store_type: Filter by store type.
         search: Search in code and name.
+        sort_by: Allow-listed sort column (unknown values use default order).
+        sort_order: Sort direction (asc or desc).
 
     Returns:
         Paginated list of stores.
@@ -89,6 +101,8 @@ async def list_stores(
         region=region,
         store_type=store_type,
         search=search,
+        sort_by=sort_by,
+        sort_order=sort_order,
     )
 
 
@@ -178,6 +192,16 @@ async def list_products(
         min_length=2,
         description="Search in SKU and name (case-insensitive)",
     ),
+    sort_by: str | None = Query(
+        None,
+        description="Sort column: sku, name, category, brand, or base_price. "
+        "Unknown values fall back to the default order (sku).",
+    ),
+    sort_order: str = Query(
+        "asc",
+        pattern="^(asc|desc)$",
+        description="Sort direction: asc or desc.",
+    ),
 ) -> ProductListResponse:
     """List products with pagination and filtering.
 
@@ -188,6 +212,8 @@ async def list_products(
         category: Filter by category.
         brand: Filter by brand.
         search: Search in SKU and name.
+        sort_by: Allow-listed sort column (unknown values use default order).
+        sort_order: Sort direction (asc or desc).
 
     Returns:
         Paginated list of products.
@@ -200,6 +226,8 @@ async def list_products(
         category=category,
         brand=brand,
         search=search,
+        sort_by=sort_by,
+        sort_order=sort_order,
     )
 
 
diff --git a/app/features/dimensions/service.py b/app/features/dimensions/service.py
index 4f88d91c..54854aba 100644
--- a/app/features/dimensions/service.py
+++ b/app/features/dimensions/service.py
@@ -5,9 +5,11 @@
 """
 
 from datetime import UTC, date, datetime, timedelta
+from typing import Any
 
 from sqlalchemy import func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import InstrumentedAttribute
 
 from app.core.logging import get_logger
 from app.features.data_platform.models import Product, Store
@@ -24,6 +26,24 @@
 
 logger = get_logger(__name__)
 
+# Allow-listed sort columns for the dimension list endpoints. sort_by is user
+# input — it MUST resolve through these maps to a real mapped column; an
+# unknown key falls back to the default order (never an error, never raw SQL).
+_STORE_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "code": Store.code,
+    "name": Store.name,
+    "region": Store.region,
+    "city": Store.city,
+    "store_type": Store.store_type,
+}
+_PRODUCT_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "sku": Product.sku,
+    "name": Product.name,
+    "category": Product.category,
+    "brand": Product.brand,
+    "base_price": Product.base_price,
+}
+
 
 class DimensionService:
     """Service for discovering stores and products.
@@ -40,6 +60,8 @@ async def list_stores(
         region: str | None = None,
         store_type: str | None = None,
         search: str | None = None,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
     ) -> StoreListResponse:
         """List stores with pagination and filtering.
 
@@ -50,6 +72,9 @@ async def list_stores(
             region: Filter by region (exact match).
             store_type: Filter by store type (exact match).
             search: Search in store code and name (case-insensitive).
+            sort_by: Allow-listed sort column (code, name, region, city,
+                store_type). Unknown values fall back to the default order.
+            sort_order: Sort direction ("asc" or "desc").
 
         Returns:
             Paginated list of stores.
@@ -76,9 +101,16 @@ async def list_stores(
         total_result = await db.execute(count_stmt)
         total = total_result.scalar_one()
 
-        # Apply pagination and ordering
+        # Apply ordering: allow-listed sort column, else the default (code).
+        sort_column = _STORE_SORT_COLUMNS.get(sort_by) if sort_by else None
+        if sort_column is not None:
+            order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+        else:
+            order_by = Store.code.asc()
+
+        # Apply pagination
         offset = (page - 1) * page_size
-        stmt = stmt.order_by(Store.code).offset(offset).limit(page_size)
+        stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
 
         # Execute query
         result = await db.execute(stmt)
@@ -153,6 +185,8 @@ async def list_products(
         category: str | None = None,
         brand: str | None = None,
         search: str | None = None,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
     ) -> ProductListResponse:
         """List products with pagination and filtering.
 
@@ -163,6 +197,9 @@ async def list_products(
             category: Filter by category (exact match).
             brand: Filter by brand (exact match).
             search: Search in SKU and name (case-insensitive).
+            sort_by: Allow-listed sort column (sku, name, category, brand,
+                base_price). Unknown values fall back to the default order.
+            sort_order: Sort direction ("asc" or "desc").
 
         Returns:
             Paginated list of products.
@@ -189,9 +226,16 @@ async def list_products(
         total_result = await db.execute(count_stmt)
         total = total_result.scalar_one()
 
-        # Apply pagination and ordering
+        # Apply ordering: allow-listed sort column, else the default (sku).
+        sort_column = _PRODUCT_SORT_COLUMNS.get(sort_by) if sort_by else None
+        if sort_column is not None:
+            order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+        else:
+            order_by = Product.sku.asc()
+
+        # Apply pagination
         offset = (page - 1) * page_size
-        stmt = stmt.order_by(Product.sku).offset(offset).limit(page_size)
+        stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
 
         # Execute query
         result = await db.execute(stmt)
diff --git a/app/features/dimensions/tests/conftest.py b/app/features/dimensions/tests/conftest.py
index 46db27ac..9befdffe 100644
--- a/app/features/dimensions/tests/conftest.py
+++ b/app/features/dimensions/tests/conftest.py
@@ -1,6 +1,19 @@
 """Test fixtures for dimensions module."""
 
+import uuid
+from collections.abc import AsyncGenerator
+from datetime import date
+from decimal import Decimal
+
 import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import get_settings
+from app.core.database import get_db
+from app.features.data_platform.models import Calendar, Product, SalesDaily, Store
+from app.main import app
 
 
 @pytest.fixture
@@ -26,3 +39,141 @@ def sample_product_data():
         "base_price": "2.99",
         "base_cost": "1.50",
     }
+
+
+# =============================================================================
+# Database Fixtures for Integration Tests
+# =============================================================================
+
+
+@pytest.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    """Create an async database session for integration tests.
+
+    Yields a session, then cleans up TEST-prefixed data. Requires
+    PostgreSQL (docker-compose up -d).
+    """
+    settings = get_settings()
+    engine = create_async_engine(settings.database_url, echo=False)
+
+    async_session_maker = async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+    async with async_session_maker() as session:
+        try:
+            yield session
+        finally:
+            # Clean up test data (delete in FK-safe order).
+            await session.execute(delete(SalesDaily))
+            await session.execute(delete(Product).where(Product.sku.like("TEST-%")))
+            await session.execute(delete(Store).where(Store.code.like("TEST-%")))
+            await session.execute(
+                delete(Calendar).where(
+                    (Calendar.date >= date(2024, 1, 1)) & (Calendar.date <= date(2024, 4, 29))
+                )
+            )
+            await session.commit()
+
+    await engine.dispose()
+
+
+@pytest.fixture
+async def client(db_session: AsyncSession) -> AsyncGenerator[AsyncClient, None]:
+    """Create a test client with the database dependency overridden."""
+
+    async def override_get_db() -> AsyncGenerator[AsyncSession, None]:
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as ac:
+        yield ac
+
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture
+async def sample_stores_multi(db_session: AsyncSession) -> list[Store]:
+    """Create 3 stores sharing a unique TEST- prefix.
+
+    Codes and names are deliberately non-aligned so that an ascending
+    sort by ``code`` differs from an ascending sort by ``name``.
+    """
+    prefix = f"TEST-{uuid.uuid4().hex[:6]}"
+    stores = [
+        Store(
+            code=f"{prefix}-A",
+            name="Zulu Store",
+            region="North",
+            city="Alpha City",
+            store_type="express",
+        ),
+        Store(
+            code=f"{prefix}-B",
+            name="Alpha Store",
+            region="South",
+            city="Zeta City",
+            store_type="warehouse",
+        ),
+        Store(
+            code=f"{prefix}-C",
+            name="Mike Store",
+            region="East",
+            city="Mid City",
+            store_type="supermarket",
+        ),
+    ]
+    for store in stores:
+        db_session.add(store)
+    await db_session.commit()
+    for store in stores:
+        await db_session.refresh(store)
+    return stores
+
+
+@pytest.fixture
+async def sample_products_multi(db_session: AsyncSession) -> list[Product]:
+    """Create 3 products sharing a unique TEST- prefix.
+
+    SKUs and names are deliberately non-aligned so that an ascending
+    sort by ``sku`` differs from an ascending sort by ``name``.
+    """
+    prefix = f"TEST-{uuid.uuid4().hex[:6]}"
+    products = [
+        Product(
+            sku=f"{prefix}-A",
+            name="Zulu Widget",
+            category="Cat-Z",
+            brand="Brand-M",
+            base_price=Decimal("9.99"),
+            base_cost=Decimal("5.00"),
+        ),
+        Product(
+            sku=f"{prefix}-B",
+            name="Alpha Widget",
+            category="Cat-A",
+            brand="Brand-Z",
+            base_price=Decimal("1.99"),
+            base_cost=Decimal("1.00"),
+        ),
+        Product(
+            sku=f"{prefix}-C",
+            name="Mike Widget",
+            category="Cat-M",
+            brand="Brand-A",
+            base_price=Decimal("5.99"),
+            base_cost=Decimal("3.00"),
+        ),
+    ]
+    for product in products:
+        db_session.add(product)
+    await db_session.commit()
+    for product in products:
+        await db_session.refresh(product)
+    return products
diff --git a/app/features/dimensions/tests/test_sort.py b/app/features/dimensions/tests/test_sort.py
new file mode 100644
index 00000000..0ce019ae
--- /dev/null
+++ b/app/features/dimensions/tests/test_sort.py
@@ -0,0 +1,156 @@
+"""Integration tests for dimension list sorting (sort_by / sort_order).
+
+Runs against a real PostgreSQL database. Each test scopes its assertions
+to a unique TEST- prefix via the ``search`` filter so pre-existing seeded
+rows do not interfere.
+
+Requires PostgreSQL to be running: docker-compose up -d
+"""
+
+import pytest
+from httpx import AsyncClient
+
+from app.features.data_platform.models import Product, Store
+
+
+def _prefix(code_or_sku: str) -> str:
+    """Recover the shared TEST- prefix from a ``{prefix}-A`` code/sku."""
+    return code_or_sku.rsplit("-", 1)[0]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+class TestStoreSort:
+    """Sorting on GET /dimensions/stores."""
+
+    async def test_sort_by_name_asc(
+        self, client: AsyncClient, sample_stores_multi: list[Store]
+    ) -> None:
+        """sort_by=name&sort_order=asc orders stores by name ascending."""
+        prefix = _prefix(sample_stores_multi[0].code)
+        response = await client.get(
+            "/dimensions/stores",
+            params={"search": prefix, "sort_by": "name", "sort_order": "asc"},
+        )
+        assert response.status_code == 200
+        stores = response.json()["stores"]
+        assert len(stores) == 3
+        assert [s["name"] for s in stores] == [
+            "Alpha Store",
+            "Mike Store",
+            "Zulu Store",
+        ]
+
+    async def test_sort_by_name_desc(
+        self, client: AsyncClient, sample_stores_multi: list[Store]
+    ) -> None:
+        """sort_by=name&sort_order=desc orders stores by name descending."""
+        prefix = _prefix(sample_stores_multi[0].code)
+        response = await client.get(
+            "/dimensions/stores",
+            params={"search": prefix, "sort_by": "name", "sort_order": "desc"},
+        )
+        assert response.status_code == 200
+        stores = response.json()["stores"]
+        assert [s["name"] for s in stores] == [
+            "Zulu Store",
+            "Mike Store",
+            "Alpha Store",
+        ]
+
+    async def test_unknown_sort_by_falls_back_to_default(
+        self, client: AsyncClient, sample_stores_multi: list[Store]
+    ) -> None:
+        """An unknown sort_by falls back to the default code order (no error)."""
+        prefix = _prefix(sample_stores_multi[0].code)
+        response = await client.get(
+            "/dimensions/stores",
+            params={"search": prefix, "sort_by": "not_a_real_column"},
+        )
+        assert response.status_code == 200
+        codes = [s["code"] for s in response.json()["stores"]]
+        assert codes == sorted(codes)
+
+    async def test_omitted_sort_is_default_code_order(
+        self, client: AsyncClient, sample_stores_multi: list[Store]
+    ) -> None:
+        """Omitting sort params preserves the prior default (code ascending)."""
+        prefix = _prefix(sample_stores_multi[0].code)
+        response = await client.get(
+            "/dimensions/stores",
+            params={"search": prefix},
+        )
+        assert response.status_code == 200
+        codes = [s["code"] for s in response.json()["stores"]]
+        assert codes == sorted(codes)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+class TestProductSort:
+    """Sorting on GET /dimensions/products."""
+
+    async def test_sort_by_name_asc(
+        self, client: AsyncClient, sample_products_multi: list[Product]
+    ) -> None:
+        """sort_by=name&sort_order=asc orders products by name ascending."""
+        prefix = _prefix(sample_products_multi[0].sku)
+        response = await client.get(
+            "/dimensions/products",
+            params={"search": prefix, "sort_by": "name", "sort_order": "asc"},
+        )
+        assert response.status_code == 200
+        products = response.json()["products"]
+        assert len(products) == 3
+        assert [p["name"] for p in products] == [
+            "Alpha Widget",
+            "Mike Widget",
+            "Zulu Widget",
+        ]
+
+    async def test_sort_by_name_desc(
+        self, client: AsyncClient, sample_products_multi: list[Product]
+    ) -> None:
+        """sort_by=name&sort_order=desc orders products by name descending."""
+        prefix = _prefix(sample_products_multi[0].sku)
+        response = await client.get(
+            "/dimensions/products",
+            params={"search": prefix, "sort_by": "name", "sort_order": "desc"},
+        )
+        assert response.status_code == 200
+        products = response.json()["products"]
+        assert [p["name"] for p in products] == [
+            "Zulu Widget",
+            "Mike Widget",
+            "Alpha Widget",
+        ]
+
+    async def test_sort_by_base_price_asc(
+        self, client: AsyncClient, sample_products_multi: list[Product]
+    ) -> None:
+        """sort_by=base_price orders by the numeric price column."""
+        prefix = _prefix(sample_products_multi[0].sku)
+        response = await client.get(
+            "/dimensions/products",
+            params={"search": prefix, "sort_by": "base_price", "sort_order": "asc"},
+        )
+        assert response.status_code == 200
+        products = response.json()["products"]
+        assert [p["name"] for p in products] == [
+            "Alpha Widget",
+            "Mike Widget",
+            "Zulu Widget",
+        ]
+
+    async def test_unknown_sort_by_falls_back_to_default(
+        self, client: AsyncClient, sample_products_multi: list[Product]
+    ) -> None:
+        """An unknown sort_by falls back to the default sku order (no error)."""
+        prefix = _prefix(sample_products_multi[0].sku)
+        response = await client.get(
+            "/dimensions/products",
+            params={"search": prefix, "sort_by": "not_a_real_column"},
+        )
+        assert response.status_code == 200
+        skus = [p["sku"] for p in response.json()["products"]]
+        assert skus == sorted(skus)
diff --git a/app/features/jobs/routes.py b/app/features/jobs/routes.py
index 2347fa26..9af5d63d 100644
--- a/app/features/jobs/routes.py
+++ b/app/features/jobs/routes.py
@@ -159,11 +159,17 @@ async def create_job(
 - `job_type`: Filter by job type (train, predict, backtest)
 - `status`: Filter by status (pending, running, completed, failed, cancelled)
 
+**Sorting**:
+- `sort_by`: Allow-listed column (created_at, completed_at, job_type, status).
+  Unknown values fall back to the default order.
+- `sort_order`: `asc` or `desc` (default: `asc`).
+
 **Example Use Cases**:
 1. List all jobs: `GET /jobs`
 2. List failed jobs: `GET /jobs?status=failed`
 3. List train jobs: `GET /jobs?job_type=train`
 4. Paginate: `GET /jobs?page=2&page_size=10`
+5. Sort by status: `GET /jobs?sort_by=status&sort_order=desc`
 """,
 )
 async def list_jobs(
@@ -172,6 +178,12 @@ async def list_jobs(
     page_size: int = Query(20, ge=1, le=100, description="Jobs per page (max 100)"),
     job_type: JobType | None = Query(None, description="Filter by job type"),
     status: JobStatus | None = Query(None, description="Filter by status"),
+    sort_by: str | None = Query(
+        None,
+        description="Sort column: created_at|completed_at|job_type|status. "
+        "Unknown values use the default order (created_at desc).",
+    ),
+    sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort direction."),
 ) -> JobListResponse:
     """List jobs with pagination and filtering.
 
@@ -181,6 +193,8 @@ async def list_jobs(
         page_size: Number of jobs per page.
         job_type: Filter by job type (optional).
         status: Filter by status (optional).
+        sort_by: Allow-listed sort column; unknown values use the default order.
+        sort_order: Sort direction ("asc" or "desc").
 
     Returns:
         Paginated list of jobs.
@@ -192,6 +206,8 @@ async def list_jobs(
         page_size=page_size,
         job_type=job_type,
         status=status,
+        sort_by=sort_by,
+        sort_order=sort_order,
     )
 
 
diff --git a/app/features/jobs/service.py b/app/features/jobs/service.py
index 46b071cf..e559fb99 100644
--- a/app/features/jobs/service.py
+++ b/app/features/jobs/service.py
@@ -15,6 +15,7 @@
 
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import InstrumentedAttribute
 
 from app.core.config import get_settings
 from app.core.logging import get_logger
@@ -46,6 +47,17 @@
 # most meaningful single number; change this constant to pick a different one.
 _STABILITY_METRIC: str = "wape"
 
+# Allow-listed sort columns for the job list endpoint. sort_by is user input —
+# it MUST resolve through this map to a real mapped column; an unknown key
+# falls back to the default order (never an error, never raw SQL). JSONB
+# columns (params, result) are intentionally excluded — not meaningfully sortable.
+_JOB_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "created_at": Job.created_at,
+    "completed_at": Job.completed_at,
+    "job_type": Job.job_type,
+    "status": Job.status,
+}
+
 
 def _finite(value: float) -> float:
     """Coerce NaN/inf to 0.0 so a job result stays JSON/JSONB-safe.
@@ -208,6 +220,8 @@ async def list_jobs(
         page_size: int = 20,
         job_type: JobType | None = None,
         status: JobStatus | None = None,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
     ) -> JobListResponse:
         """List jobs with pagination and filtering.
 
@@ -217,6 +231,10 @@ async def list_jobs(
             page_size: Number of jobs per page.
             job_type: Filter by job type (optional).
             status: Filter by status (optional).
+            sort_by: Allow-listed sort column (created_at, completed_at,
+                job_type, status). Unknown values fall back to the default
+                order (created_at desc).
+            sort_order: Sort direction ("asc" or "desc").
 
         Returns:
             Paginated list of jobs.
@@ -235,9 +253,17 @@ async def list_jobs(
         count_result = await db.execute(count_stmt)
         total = count_result.scalar_one()
 
+        # Apply ordering: allow-listed sort column, else the default
+        # (created_at desc — UNCHANGED, keeps existing callers/tests green).
+        sort_column = _JOB_SORT_COLUMNS.get(sort_by) if sort_by else None
+        if sort_column is not None:
+            order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+        else:
+            order_by = Job.created_at.desc()
+
         # Apply pagination
         offset = (page - 1) * page_size
-        stmt = stmt.order_by(Job.created_at.desc()).offset(offset).limit(page_size)
+        stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
 
         # Execute query
         result = await db.execute(stmt)
diff --git a/app/features/jobs/tests/conftest.py b/app/features/jobs/tests/conftest.py
index 273dee37..41589643 100644
--- a/app/features/jobs/tests/conftest.py
+++ b/app/features/jobs/tests/conftest.py
@@ -1,14 +1,120 @@
 """Test fixtures for jobs module."""
 
+import uuid
+from collections.abc import AsyncGenerator
 from datetime import UTC, datetime
 
 import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
-from app.features.jobs.models import JobStatus, JobType
+from app.core.config import get_settings
+from app.core.database import get_db
+from app.features.jobs.models import Job, JobStatus, JobType
 from app.features.jobs.schemas import (
     JobCreate,
     JobResponse,
 )
+from app.main import app
+
+# =============================================================================
+# Database Fixtures for Integration Tests
+# =============================================================================
+
+
+@pytest.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    """Create async database session for integration tests.
+
+    Provides a session and cleans up test data (jobs whose job_id starts
+    with "test"). Requires PostgreSQL to be running (docker-compose up -d).
+    """
+    settings = get_settings()
+    engine = create_async_engine(settings.database_url, echo=False)
+
+    async_session_maker = async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+    async with async_session_maker() as session:
+        try:
+            yield session
+        finally:
+            # Job has no model_type column for a cleanup key — key on the
+            # "test" job_id prefix every fixture/test uses.
+            await session.execute(delete(Job).where(Job.job_id.like("test%")))
+            await session.commit()
+
+    await engine.dispose()
+
+
+@pytest.fixture
+async def client(db_session: AsyncSession) -> AsyncGenerator[AsyncClient, None]:
+    """Create test client with database dependency override."""
+
+    async def override_get_db() -> AsyncGenerator[AsyncSession, None]:
+        try:
+            yield db_session
+            await db_session.commit()
+        except Exception:
+            await db_session.rollback()
+            raise
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as ac:
+        yield ac
+
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture
+async def sample_jobs_multi(db_session: AsyncSession) -> list[Job]:
+    """Insert three jobs with distinct job_type / status / created_at.
+
+    Drives the list-endpoint sort tests. Every job_id starts with "test"
+    so the db_session cleanup removes them. created_at is set explicitly
+    (overriding the server_default) so created_at sorting is deterministic.
+    """
+    jobs = [
+        Job(
+            job_id=f"test{uuid.uuid4().hex[:28]}",
+            job_type=JobType.TRAIN.value,
+            status=JobStatus.PENDING.value,
+            params={},
+            created_at=datetime(2024, 1, 1, tzinfo=UTC),
+        ),
+        Job(
+            job_id=f"test{uuid.uuid4().hex[:28]}",
+            job_type=JobType.PREDICT.value,
+            status=JobStatus.RUNNING.value,
+            params={},
+            created_at=datetime(2024, 1, 2, tzinfo=UTC),
+        ),
+        Job(
+            job_id=f"test{uuid.uuid4().hex[:28]}",
+            job_type=JobType.BACKTEST.value,
+            status=JobStatus.COMPLETED.value,
+            params={},
+            created_at=datetime(2024, 1, 3, tzinfo=UTC),
+        ),
+    ]
+    db_session.add_all(jobs)
+    await db_session.commit()
+    for job in jobs:
+        await db_session.refresh(job)
+    return jobs
+
+
+# =============================================================================
+# Unit Test Fixtures
+# =============================================================================
 
 
 @pytest.fixture
diff --git a/app/features/jobs/tests/test_routes.py b/app/features/jobs/tests/test_routes.py
new file mode 100644
index 00000000..4981873d
--- /dev/null
+++ b/app/features/jobs/tests/test_routes.py
@@ -0,0 +1,115 @@
+"""Integration tests for jobs API routes.
+
+These tests require PostgreSQL to be running (docker-compose up -d).
+Run with: pytest app/features/jobs/tests/ -v -m integration
+"""
+
+import uuid
+from typing import Any
+
+import pytest
+from httpx import AsyncClient
+
+from app.features.jobs.models import Job
+
+pytestmark = pytest.mark.integration
+
+
+class TestListJobsEndpoint:
+    """Tests for GET /jobs endpoint."""
+
+    async def test_list_jobs_ok(self, client: AsyncClient) -> None:
+        """GET /jobs returns 200 with the paginated envelope."""
+        response = await client.get("/jobs")
+        assert response.status_code == 200
+        data = response.json()
+        assert "jobs" in data
+        assert data["page"] == 1
+        assert data["page_size"] == 20
+
+    async def test_list_jobs_returns_seeded_rows(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """Seeded jobs appear in the listing."""
+        response = await client.get("/jobs?page_size=100")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["total"] >= 3
+        listed_ids = {j["job_id"] for j in data["jobs"]}
+        assert {job.job_id for job in sample_jobs_multi} <= listed_ids
+
+
+class TestListJobsSortEndpoint:
+    """Tests for sort_by / sort_order on GET /jobs."""
+
+    @staticmethod
+    def _test_job_types(payload: dict[str, Any]) -> list[str]:
+        """Job types of the test-prefixed jobs, in response order."""
+        return [j["job_type"] for j in payload["jobs"] if str(j["job_id"]).startswith("test")]
+
+    async def test_sort_by_job_type_asc(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """sort_by=job_type&sort_order=asc orders jobs ascending."""
+        response = await client.get("/jobs?sort_by=job_type&sort_order=asc&page_size=100")
+        assert response.status_code == 200
+        assert self._test_job_types(response.json()) == ["backtest", "predict", "train"]
+
+    async def test_sort_by_job_type_desc(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """sort_by=job_type&sort_order=desc orders jobs descending."""
+        response = await client.get("/jobs?sort_by=job_type&sort_order=desc&page_size=100")
+        assert response.status_code == 200
+        assert self._test_job_types(response.json()) == ["train", "predict", "backtest"]
+
+    async def test_sort_by_status_asc(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """sort_by=status&sort_order=asc orders jobs by status value."""
+        response = await client.get("/jobs?sort_by=status&sort_order=asc&page_size=100")
+        assert response.status_code == 200
+        # status asc: completed < pending < running -> backtest, train, predict
+        assert self._test_job_types(response.json()) == ["backtest", "train", "predict"]
+
+    async def test_sort_by_created_at_desc(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """sort_by=created_at&sort_order=desc returns newest first."""
+        response = await client.get("/jobs?sort_by=created_at&sort_order=desc&page_size=100")
+        assert response.status_code == 200
+        # created_at 2024-01-03 > 01-02 > 01-01 -> backtest, predict, train
+        assert self._test_job_types(response.json()) == ["backtest", "predict", "train"]
+
+    async def test_unknown_sort_by_falls_back_to_default(
+        self, client: AsyncClient, sample_jobs_multi: list[Job]
+    ) -> None:
+        """An unknown sort_by uses the default order, never errors."""
+        default = await client.get("/jobs?page_size=100")
+        unknown = await client.get("/jobs?sort_by=params&page_size=100")
+        assert default.status_code == 200
+        assert unknown.status_code == 200
+        default_ids = [j["job_id"] for j in default.json()["jobs"]]
+        unknown_ids = [j["job_id"] for j in unknown.json()["jobs"]]
+        assert unknown_ids == default_ids
+
+    async def test_invalid_sort_order_rejected(self, client: AsyncClient) -> None:
+        """sort_order outside {asc,desc} is rejected with 422 via the Query regex."""
+        response = await client.get("/jobs?sort_order=sideways")
+        assert response.status_code == 422
+
+
+class TestGetJobEndpoint:
+    """Tests for GET /jobs/{job_id} endpoint."""
+
+    async def test_get_job_success(self, client: AsyncClient, sample_jobs_multi: list[Job]) -> None:
+        """GET /jobs/{job_id} returns the job."""
+        job_id = sample_jobs_multi[0].job_id
+        response = await client.get(f"/jobs/{job_id}")
+        assert response.status_code == 200
+        assert response.json()["job_id"] == job_id
+
+    async def test_get_job_not_found(self, client: AsyncClient) -> None:
+        """GET /jobs/{job_id} returns 404 for an unknown job."""
+        response = await client.get(f"/jobs/test{uuid.uuid4().hex[:28]}")
+        assert response.status_code == 404
diff --git a/app/features/registry/routes.py b/app/features/registry/routes.py
index 701a15d7..55f81b59 100644
--- a/app/features/registry/routes.py
+++ b/app/features/registry/routes.py
@@ -142,6 +142,11 @@ async def create_run(
 **Pagination:**
 - `page`: Page number (1-indexed, default: 1)
 - `page_size`: Runs per page (default: 20, max: 100)
+
+**Sorting:**
+- `sort_by`: Allow-listed column (created_at, model_type, status, store_id,
+  product_id). Unknown values fall back to the default order.
+- `sort_order`: `asc` or `desc` (default: `asc`).
 """,
 )
 async def list_runs(
@@ -152,6 +157,12 @@ async def list_runs(
     run_status: RunStatus | None = Query(None, alias="status", description="Filter by status"),
     store_id: int | None = Query(None, ge=1, description="Filter by store ID"),
     product_id: int | None = Query(None, ge=1, description="Filter by product ID"),
+    sort_by: str | None = Query(
+        None,
+        description="Sort column: created_at|model_type|status|store_id|product_id. "
+        "Unknown values use the default order (created_at desc).",
+    ),
+    sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort direction."),
 ) -> RunListResponse:
     """List model runs with filtering and pagination.
 
@@ -163,6 +174,8 @@ async def list_runs(
         run_status: Filter by status.
         store_id: Filter by store ID.
         product_id: Filter by product ID.
+        sort_by: Allow-listed sort column; unknown values use the default order.
+        sort_order: Sort direction ("asc" or "desc").
 
     Returns:
         Paginated list of runs.
@@ -177,6 +190,8 @@ async def list_runs(
         status=run_status,
         store_id=store_id,
         product_id=product_id,
+        sort_by=sort_by,
+        sort_order=sort_order,
     )
 
     return response
diff --git a/app/features/registry/service.py b/app/features/registry/service.py
index 71243ae3..ceb0b4bf 100644
--- a/app/features/registry/service.py
+++ b/app/features/registry/service.py
@@ -21,6 +21,7 @@
 import structlog
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import InstrumentedAttribute
 
 from app.core.config import get_settings
 from app.features.registry.models import DeploymentAlias, ModelRun
@@ -39,6 +40,18 @@
 
 logger = structlog.get_logger()
 
+# Allow-listed sort columns for the run list endpoint. sort_by is user input —
+# it MUST resolve through this map to a real mapped column; an unknown key
+# falls back to the default order (never an error, never raw SQL). JSONB
+# columns (metrics, runtime_info, agent_context) are intentionally excluded.
+_RUN_SORT_COLUMNS: dict[str, InstrumentedAttribute[Any]] = {
+    "created_at": ModelRun.created_at,
+    "model_type": ModelRun.model_type,
+    "status": ModelRun.status,
+    "store_id": ModelRun.store_id,
+    "product_id": ModelRun.product_id,
+}
+
 
 class InvalidTransitionError(ValueError):
     """Invalid state transition attempted."""
@@ -263,6 +276,8 @@ async def list_runs(
         status: RunStatus | None = None,
         store_id: int | None = None,
         product_id: int | None = None,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
     ) -> RunListResponse:
         """List runs with filtering and pagination.
 
@@ -274,6 +289,10 @@ async def list_runs(
             status: Filter by status.
             store_id: Filter by store ID.
             product_id: Filter by product ID.
+            sort_by: Allow-listed sort column (created_at, model_type, status,
+                store_id, product_id). Unknown values fall back to the default
+                order (created_at desc).
+            sort_order: Sort direction ("asc" or "desc").
 
         Returns:
             Paginated list of runs.
@@ -295,9 +314,17 @@ async def list_runs(
         total_result = await db.execute(count_stmt)
         total = total_result.scalar_one()
 
+        # Apply ordering: allow-listed sort column, else the default
+        # (created_at desc — UNCHANGED, keeps existing callers/tests green).
+        sort_column = _RUN_SORT_COLUMNS.get(sort_by) if sort_by else None
+        if sort_column is not None:
+            order_by = sort_column.desc() if sort_order == "desc" else sort_column.asc()
+        else:
+            order_by = ModelRun.created_at.desc()
+
         # Apply pagination
         offset = (page - 1) * page_size
-        stmt = stmt.order_by(ModelRun.created_at.desc()).offset(offset).limit(page_size)
+        stmt = stmt.order_by(order_by).offset(offset).limit(page_size)
 
         result = await db.execute(stmt)
         runs = result.scalars().all()
diff --git a/app/features/registry/tests/test_routes.py b/app/features/registry/tests/test_routes.py
index 0b9e2e5e..2c4b1c3c 100644
--- a/app/features/registry/tests/test_routes.py
+++ b/app/features/registry/tests/test_routes.py
@@ -215,6 +215,97 @@ async def test_list_runs_pagination(self, client: AsyncClient) -> None:
         assert data["page_size"] == 2
 
 
+class TestListRunsSortEndpoint:
+    """Tests for sort_by / sort_order on GET /registry/runs."""
+
+    @staticmethod
+    async def _create_run(client: AsyncClient, model_type: str) -> str:
+        """Create a run with the given model_type, return its run_id."""
+        response = await client.post(
+            "/registry/runs",
+            json={
+                "model_type": model_type,
+                "model_config": {},
+                "data_window_start": "2024-01-01",
+                "data_window_end": "2024-01-31",
+                "store_id": 1,
+                "product_id": 1,
+            },
+        )
+        assert response.status_code == 201
+        return str(response.json()["run_id"])
+
+    @staticmethod
+    def _test_model_types(payload: dict[str, object]) -> list[str]:
+        """Model types of the test-prefixed runs, in response order."""
+        runs = payload["runs"]
+        assert isinstance(runs, list)
+        return [r["model_type"] for r in runs if str(r["model_type"]).startswith("test-sort-")]
+
+    async def test_sort_by_model_type_desc(self, client: AsyncClient) -> None:
+        """sort_by=model_type&sort_order=desc orders runs descending."""
+        for model_type in ("test-sort-aaa", "test-sort-bbb", "test-sort-ccc"):
+            await self._create_run(client, model_type)
+
+        response = await client.get(
+            "/registry/runs?sort_by=model_type&sort_order=desc&page_size=100"
+        )
+        assert response.status_code == 200
+        assert self._test_model_types(response.json()) == [
+            "test-sort-ccc",
+            "test-sort-bbb",
+            "test-sort-aaa",
+        ]
+
+    async def test_sort_by_model_type_asc(self, client: AsyncClient) -> None:
+        """sort_by=model_type&sort_order=asc orders runs ascending."""
+        for model_type in ("test-sort-ccc", "test-sort-aaa", "test-sort-bbb"):
+            await self._create_run(client, model_type)
+
+        response = await client.get(
+            "/registry/runs?sort_by=model_type&sort_order=asc&page_size=100"
+        )
+        assert response.status_code == 200
+        assert self._test_model_types(response.json()) == [
+            "test-sort-aaa",
+            "test-sort-bbb",
+            "test-sort-ccc",
+        ]
+
+    async def test_unknown_sort_by_falls_back_to_default(self, client: AsyncClient) -> None:
+        """An unknown sort_by uses the default order (created_at desc), never errors."""
+        for model_type in ("test-sort-fallback-1", "test-sort-fallback-2"):
+            await self._create_run(client, model_type)
+
+        default = await client.get("/registry/runs?page_size=100")
+        unknown = await client.get("/registry/runs?sort_by=metrics&page_size=100")
+        assert default.status_code == 200
+        assert unknown.status_code == 200
+        default_ids = [r["run_id"] for r in default.json()["runs"]]
+        unknown_ids = [r["run_id"] for r in unknown.json()["runs"]]
+        assert unknown_ids == default_ids
+
+    async def test_default_matches_explicit_created_at_desc(self, client: AsyncClient) -> None:
+        """Omitting sort params == explicit created_at desc (default unchanged)."""
+        for model_type in ("test-sort-def-1", "test-sort-def-2", "test-sort-def-3"):
+            await self._create_run(client, model_type)
+
+        default = await client.get("/registry/runs?page_size=100")
+        explicit = await client.get(
+            "/registry/runs?sort_by=created_at&sort_order=desc&page_size=100"
+        )
+        assert default.status_code == 200
+        assert explicit.status_code == 200
+        assert [r["run_id"] for r in default.json()["runs"]] == [
+            r["run_id"] for r in explicit.json()["runs"]
+        ]
+
+    async def test_invalid_sort_order_rejected(self, client: AsyncClient) -> None:
+        """sort_order outside {asc,desc} is rejected with 422 via the Query regex."""
+        response = await client.get("/registry/runs?sort_order=sideways")
+        assert response.status_code == 422
+
+
 class TestGetRunEndpoint:
     """Tests for GET /registry/runs/{run_id} endpoint."""
 
diff --git a/app/features/seeder/schemas.py b/app/features/seeder/schemas.py
index 90331aad..7c86d5e2 100644
--- a/app/features/seeder/schemas.py
+++ b/app/features/seeder/schemas.py
@@ -6,6 +6,8 @@
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
+from app.shared.seeder.config import default_seed_end_date, default_seed_start_date
+
 VALID_CHANNELS: frozenset[str] = frozenset({"in_store", "online", "click_collect", "wholesale"})
 """Allow-list for ``sales_daily.channel`` — mirrors the SQL CHECK."""
 
@@ -98,12 +100,12 @@ class GenerateParams(BaseModel):
         description="Number of products to generate",
     )
     start_date: date = Field(
-        default_factory=lambda: date(2024, 1, 1),
-        description="Start of date range",
+        default_factory=default_seed_start_date,
+        description="Start of date range (defaults to one year before today)",
     )
     end_date: date = Field(
-        default_factory=lambda: date(2024, 12, 31),
-        description="End of date range",
+        default_factory=default_seed_end_date,
+        description="End of date range (defaults to today)",
     )
     sparsity: float = Field(
         default=0.0,
diff --git a/app/features/seeder/service.py b/app/features/seeder/service.py
index d8b5dfb8..5dc0f63f 100644
--- a/app/features/seeder/service.py
+++ b/app/features/seeder/service.py
@@ -4,7 +4,7 @@
 
 import time
 from dataclasses import replace
-from datetime import date, datetime
+from datetime import date, datetime, timedelta
 
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -26,6 +26,7 @@
 from app.features.seeder import schemas
 from app.shared.seeder import DataSeeder, ScenarioPreset, SeederConfig
 from app.shared.seeder.config import (
+    DEMO_MINIMAL_SPAN_DAYS,
     BundleConfig,
     ChangepointConfig,
     ChangepointEvent,
@@ -39,6 +40,8 @@
     ReturnsConfig,
     SparsityConfig,
     SubstitutionConfig,
+    default_seed_end_date,
+    default_seed_start_date,
 )
 
 logger = get_logger(__name__)
@@ -315,14 +318,21 @@ def list_scenarios() -> list[schemas.ScenarioInfo]:
     Returns:
         List of ScenarioInfo with preset details.
     """
+    # Date ranges are anchored to *today* so the picker reflects the windows the
+    # seeder will actually produce. holiday_rush is the one exception: it is
+    # deliberately calendar-pinned to a 2024 Q4 holiday window.
+    today = default_seed_end_date()
+    year_ago = default_seed_start_date()
+    demo_start = today - timedelta(days=DEMO_MINIMAL_SPAN_DAYS)
+
     scenarios = [
         schemas.ScenarioInfo(
             name="retail_standard",
             description="Normal retail patterns with mild seasonality and linear trend",
             stores=10,
             products=50,
-            start_date=date(2024, 1, 1),
-            end_date=date(2024, 12, 31),
+            start_date=year_ago,
+            end_date=today,
         ),
         schemas.ScenarioInfo(
             name="holiday_rush",
@@ -337,40 +347,40 @@ def list_scenarios() -> list[schemas.ScenarioInfo]:
             description="Noisy, unpredictable data with frequent anomalies for robustness testing",
             stores=10,
             products=50,
-            start_date=date(2024, 1, 1),
-            end_date=date(2024, 12, 31),
+            start_date=year_ago,
+            end_date=today,
         ),
         schemas.ScenarioInfo(
             name="stockout_heavy",
             description="Frequent stockouts (25% probability) for inventory modeling",
             stores=10,
             products=50,
-            start_date=date(2024, 1, 1),
-            end_date=date(2024, 12, 31),
+            start_date=year_ago,
+            end_date=today,
         ),
         schemas.ScenarioInfo(
             name="new_launches",
             description="100 products with gradual launch ramp patterns",
             stores=10,
             products=100,
-            start_date=date(2024, 1, 1),
-            end_date=date(2024, 12, 31),
+            start_date=year_ago,
+            end_date=today,
         ),
         schemas.ScenarioInfo(
             name="sparse",
             description="50% missing combinations and random date gaps for gap handling",
             stores=10,
             products=50,
-            start_date=date(2024, 1, 1),
-            end_date=date(2024, 12, 31),
+            start_date=year_ago,
+            end_date=today,
         ),
         schemas.ScenarioInfo(
             name="demo_minimal",
             description="Tiny preset for the make demo target (3 stores x 10 products x 92 days)",
             stores=3,
             products=10,
-            start_date=date(2024, 10, 1),
-            end_date=date(2024, 12, 31),
+            start_date=demo_start,
+            end_date=today,
         ),
     ]
 
diff --git a/app/features/seeder/tests/test_service.py b/app/features/seeder/tests/test_service.py
index b712db95..f21aa28b 100644
--- a/app/features/seeder/tests/test_service.py
+++ b/app/features/seeder/tests/test_service.py
@@ -1,11 +1,12 @@
 """Unit tests for seeder service layer."""
 
-from datetime import date
+from datetime import date, timedelta
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
 from app.features.seeder import schemas, service
+from app.shared.seeder.config import DEMO_MINIMAL_SPAN_DAYS, default_seed_end_date
 
 
 class TestListScenarios:
@@ -27,14 +28,18 @@ def test_returns_all_scenarios(self):
         assert "demo_minimal" in names
 
     def test_demo_minimal_dimensions(self):
-        """Test that demo_minimal is the small preset for the make demo target."""
+        """Test that demo_minimal is the small preset for the make demo target.
+
+        The window is anchored to *today* so the scenario picker reflects what
+        the seeder will actually produce.
+        """
         scenarios = service.list_scenarios()
 
         demo = next(s for s in scenarios if s.name == "demo_minimal")
         assert demo.stores == 3
         assert demo.products == 10
-        assert demo.start_date == date(2024, 10, 1)
-        assert demo.end_date == date(2024, 12, 31)
+        assert demo.end_date == default_seed_end_date()
+        assert demo.start_date == default_seed_end_date() - timedelta(days=DEMO_MINIMAL_SPAN_DAYS)
 
     def test_scenario_info_structure(self):
         """Test that scenarios have required fields."""
diff --git a/app/shared/seeder/config.py b/app/shared/seeder/config.py
index cdcdc94a..67e21654 100644
--- a/app/shared/seeder/config.py
+++ b/app/shared/seeder/config.py
@@ -3,10 +3,30 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import date
+from datetime import UTC, date, datetime, timedelta
 from enum import Enum
 from typing import Literal
 
+DEFAULT_SEED_SPAN_DAYS = 365
+"""Span of the default seeded window. Generated data ends *today* and runs
+this many days backwards, so datasets, forecasts, and the demo showcase
+always look current instead of being frozen in a hard-coded calendar year."""
+
+DEMO_MINIMAL_SPAN_DAYS = 91
+"""Span of the ``demo_minimal`` window (92 calendar days inclusive). Must stay
+>= 72 so an expanding backtest with n_splits=3 + horizon=14 +
+min_train_size=30 produces a non-NaN WAPE."""
+
+
+def default_seed_end_date() -> date:
+    """End of the default seeded window — anchored to the current (UTC) date."""
+    return datetime.now(UTC).date()
+
+
+def default_seed_start_date() -> date:
+    """Start of the default seeded window — ``DEFAULT_SEED_SPAN_DAYS`` before today."""
+    return datetime.now(UTC).date() - timedelta(days=DEFAULT_SEED_SPAN_DAYS)
+
 
 class ScenarioPreset(str, Enum):
     """Pre-built scenario presets for common testing needs."""
@@ -472,8 +492,8 @@ class SeederConfig:
     """
 
     seed: int = 42
-    start_date: date = field(default_factory=lambda: date(2024, 1, 1))
-    end_date: date = field(default_factory=lambda: date(2024, 12, 31))
+    start_date: date = field(default_factory=default_seed_start_date)
+    end_date: date = field(default_factory=default_seed_end_date)
     dimensions: DimensionConfig = field(default_factory=DimensionConfig)
     time_series: TimeSeriesConfig = field(default_factory=TimeSeriesConfig)
     retail: RetailPatternConfig = field(default_factory=RetailPatternConfig)
@@ -519,6 +539,10 @@ def from_scenario(cls, scenario: ScenarioPreset, seed: int = 42) -> SeederConfig
             )
 
         if scenario == ScenarioPreset.HOLIDAY_RUSH:
+            # Deliberately calendar-pinned: the holiday dates and Q4 monthly
+            # seasonality below model a specific 2024 Black Friday / Christmas
+            # window, so this scenario is NOT re-anchored to today. Pass an
+            # explicit start_date/end_date to shift it.
             return cls(
                 seed=seed,
                 start_date=date(2024, 10, 1),
@@ -606,14 +630,17 @@ def from_scenario(cls, scenario: ScenarioPreset, seed: int = 42) -> SeederConfig
             )
 
         if scenario == ScenarioPreset.DEMO_MINIMAL:
-            # Tiny preset for the `make demo` target. Keeps wall-clock comfortable
-            # on a developer laptop while still producing a non-NaN backtest WAPE
-            # with strategy=expanding, n_splits=3, horizon=14, min_train_size=30
-            # (needs >= 30 + 3*14 = 72 days; 92 days here leaves margin).
+            # Tiny preset for the `make demo` target. Anchored to *today* so the
+            # showcase always demos current-looking data; the window runs
+            # DEMO_MINIMAL_SPAN_DAYS back from today (92 days inclusive). Keeps
+            # wall-clock comfortable on a developer laptop while still producing
+            # a non-NaN backtest WAPE with strategy=expanding, n_splits=3,
+            # horizon=14, min_train_size=30 (needs >= 30 + 3*14 = 72 days).
+            demo_end = default_seed_end_date()
             return cls(
                 seed=seed,
-                start_date=date(2024, 10, 1),
-                end_date=date(2024, 12, 31),
+                start_date=demo_end - timedelta(days=DEMO_MINIMAL_SPAN_DAYS),
+                end_date=demo_end,
                 dimensions=DimensionConfig(stores=3, products=10),
                 time_series=TimeSeriesConfig(
                     base_demand=100,
diff --git a/app/shared/seeder/tests/test_config.py b/app/shared/seeder/tests/test_config.py
index b4875652..aaed5f9f 100644
--- a/app/shared/seeder/tests/test_config.py
+++ b/app/shared/seeder/tests/test_config.py
@@ -1,11 +1,14 @@
 """Tests for seeder configuration."""
 
-from datetime import date
+from datetime import date, timedelta
 
 from app.shared.seeder.config import (
+    DEMO_MINIMAL_SPAN_DAYS,
     ScenarioPreset,
     SeederConfig,
     TimeSeriesConfig,
+    default_seed_end_date,
+    default_seed_start_date,
 )
 
 
@@ -39,12 +42,16 @@ class TestSeederConfig:
     """Tests for SeederConfig."""
 
     def test_default_values(self):
-        """Test default configuration values."""
+        """Test default configuration values.
+
+        The default date window is anchored to *today* and runs
+        DEFAULT_SEED_SPAN_DAYS backwards, so seeded data always looks current.
+        """
         config = SeederConfig()
 
         assert config.seed == 42
-        assert config.start_date == date(2024, 1, 1)
-        assert config.end_date == date(2024, 12, 31)
+        assert config.end_date == default_seed_end_date()
+        assert config.start_date == default_seed_start_date()
         assert config.dimensions.stores == 10
         assert config.dimensions.products == 50
         assert config.batch_size == 1000
@@ -93,15 +100,16 @@ def test_from_scenario_sparse(self):
     def test_from_scenario_demo_minimal(self):
         """Test demo_minimal scenario preset.
 
-        This preset powers the `make demo` target; the date range MUST cover at
-        least 72 days so an expanding backtest with n_splits=3 + horizon=14 +
-        min_train_size=30 produces non-NaN WAPE.
+        This preset powers the `make demo` target; the window is anchored to
+        *today* and MUST cover at least 72 days so an expanding backtest with
+        n_splits=3 + horizon=14 + min_train_size=30 produces non-NaN WAPE.
         """
         config = SeederConfig.from_scenario(ScenarioPreset.DEMO_MINIMAL, seed=42)
 
         assert config.seed == 42
-        assert config.start_date == date(2024, 10, 1)
-        assert config.end_date == date(2024, 12, 31)
+        assert config.end_date == default_seed_end_date()
+        assert config.start_date == default_seed_end_date() - timedelta(days=DEMO_MINIMAL_SPAN_DAYS)
+        assert (config.end_date - config.start_date).days >= 72
         assert config.dimensions.stores == 3
         assert config.dimensions.products == 10
         assert config.time_series.trend == "linear"
diff --git a/app/shared/seeder/tests/test_core.py b/app/shared/seeder/tests/test_core.py
index 944b69a0..61dedc12 100644
--- a/app/shared/seeder/tests/test_core.py
+++ b/app/shared/seeder/tests/test_core.py
@@ -5,7 +5,12 @@
 
 import pytest
 
-from app.shared.seeder.config import SeederConfig, SparsityConfig
+from app.shared.seeder.config import (
+    SeederConfig,
+    SparsityConfig,
+    default_seed_end_date,
+    default_seed_start_date,
+)
 from app.shared.seeder.core import DataSeeder, SeederResult
 
 
@@ -402,12 +407,12 @@ def test_default_dimensions(self):
         assert seeder.config.dimensions.products == 50
 
     def test_default_date_range(self):
-        """Test default date range is full year 2024."""
+        """Test the default date range is anchored to today and runs backwards."""
         config = SeederConfig()
         seeder = DataSeeder(config)
 
-        assert seeder.config.start_date == date(2024, 1, 1)
-        assert seeder.config.end_date == date(2024, 12, 31)
+        assert seeder.config.start_date == default_seed_start_date()
+        assert seeder.config.end_date == default_seed_end_date()
 
     def test_custom_sparsity(self):
         """Test custom sparsity configuration."""
diff --git a/docs/_base/API_CONTRACTS.md b/docs/_base/API_CONTRACTS.md
index b8eea632..e5d864fa 100644
--- a/docs/_base/API_CONTRACTS.md
+++ b/docs/_base/API_CONTRACTS.md
@@ -9,19 +9,20 @@ All endpoints serve JSON; error responses use `application/problem+json` (RFC 78
 |-------|--------|------|---------|
 | health | GET | `/health` | Liveness probe — `{"status":"ok"}` |
 | ingest | POST | `/ingest/sales-daily` | Batch upsert with natural-key resolution, idempotent `ON CONFLICT DO UPDATE` |
-| dimensions | GET | `/dimensions/stores` | List stores (1-indexed pagination, region/store_type filter, case-insensitive search) |
+| dimensions | GET | `/dimensions/stores` | List stores (1-indexed pagination, region/store_type filter, case-insensitive search, optional allow-listed `sort_by`/`sort_order`) |
 | dimensions | GET | `/dimensions/stores/{store_id}` | Get store by ID |
-| dimensions | GET | `/dimensions/products` | List products (category/brand filter, sku/name search) |
+| dimensions | GET | `/dimensions/products` | List products (category/brand filter, sku/name search, optional allow-listed `sort_by`/`sort_order`) |
 | dimensions | GET | `/dimensions/products/{product_id}` | Get product by ID |
 | analytics | GET | `/analytics/kpis` | Aggregated KPIs (revenue, units, transactions, avg unit price, avg basket) |
 | analytics | GET | `/analytics/drilldowns` | Group-by dimension: store / product / category / region / date |
+| analytics | GET | `/analytics/timeseries` | Period-bucketed sales series (`granularity` = day/week/month/quarter) for revenue-over-time charts; reuses `validate_date_range` (inverted/over-730-day ranges 400) |
 | featuresets | POST | `/featuresets/compute` | Compute time-safe features (lag/rolling/calendar, leakage-prevented) |
 | featuresets | POST | `/featuresets/preview` | Preview features with sample rows |
 | forecasting | POST | `/forecasting/train` | Train a model (naive / seasonal_naive / moving_average / lightgbm) |
 | forecasting | POST | `/forecasting/predict` | Generate horizon predictions from a trained model |
 | backtesting | POST | `/backtesting/run` | Time-series CV (rolling/expanding splits, MAE/sMAPE/WAPE/bias/stability) |
 | registry | POST | `/registry/runs` | Create model run (pending) |
-| registry | GET | `/registry/runs` | List with filters + pagination |
+| registry | GET | `/registry/runs` | List with filters + pagination + optional allow-listed `sort_by`/`sort_order` (created_at/model_type/status/store_id/product_id; unknown → default `created_at desc`) |
 | registry | GET | `/registry/runs/{run_id}` | Run details + JSONB metrics + runtime_info |
 | registry | PATCH | `/registry/runs/{run_id}` | Update status / metrics / artifact_uri |
 | registry | GET | `/registry/runs/{run_id}/verify` | SHA-256 artifact integrity check |
@@ -31,7 +32,7 @@ All endpoints serve JSON; error responses use `application/problem+json` (RFC 78
 | registry | DELETE | `/registry/aliases/{alias_name}` | Delete alias |
 | registry | GET | `/registry/compare/{run_id_a}/{run_id_b}` | Diff two runs |
 | jobs | POST | `/jobs` | Submit `train` / `predict` / `backtest` (returns 202-style job_id) |
-| jobs | GET | `/jobs` | List with filters |
+| jobs | GET | `/jobs` | List with filters + optional allow-listed `sort_by`/`sort_order` (created_at/completed_at/job_type/status; unknown → default `created_at desc`) |
 | jobs | GET | `/jobs/{job_id}` | Status + result JSON |
 | jobs | DELETE | `/jobs/{job_id}` | Cancel pending |
 | rag | POST | `/rag/index` | Index a markdown/openapi document; idempotent via content hash |
diff --git a/docs/_base/REPO_MAP_INDEX.md b/docs/_base/REPO_MAP_INDEX.md
index bceb6157..eb251ee2 100644
--- a/docs/_base/REPO_MAP_INDEX.md
+++ b/docs/_base/REPO_MAP_INDEX.md
@@ -23,6 +23,13 @@ ForecastLabAI is a portfolio-grade, single-host retail-demand-forecasting system
 | [`scripts/run_demo.py`](../../scripts/run_demo.py) | End-to-end pipeline driver — seed → features → train ×3 → backtest → register → alias → agent | First-run demonstrability, integration debugging |
 | [`app/features/demo/`](../../app/features/demo/) | In-process e2e demo slice — `POST /demo/run` + `WS /demo/stream` drive the pipeline via `ASGITransport` (no cross-slice imports) | Showcase page, in-product demo |
 | [`frontend/src/pages/showcase.tsx`](../../frontend/src/pages/showcase.tsx) | The Showcase page — streams the live pipeline into the dashboard as status cards | Demoing the system in-browser |
+| [`frontend/src/pages/knowledge.tsx`](../../frontend/src/pages/knowledge.tsx) | The Knowledge page — indexed RAG corpus, live semantic search, and live system state | Surfacing what the agents can draw on |
+| [`frontend/src/pages/guide.tsx`](../../frontend/src/pages/guide.tsx) | The Agent Guide page — agent tools, approval gate, live session limits, example prompts | Explaining how to use the chat agents |
+| [`frontend/src/pages/explorer/store-detail.tsx`](../../frontend/src/pages/explorer/store-detail.tsx) | The store detail page — entity profile, date-scoped KPIs, revenue-over-time chart, top-products drilldown | Investigating a single store |
+| [`frontend/src/pages/explorer/product-detail.tsx`](../../frontend/src/pages/explorer/product-detail.tsx) | The product detail page — profile, KPIs, revenue + lifecycle-demand curves, top-stores drilldown | Investigating a single product |
+| [`frontend/src/pages/explorer/run-detail.tsx`](../../frontend/src/pages/explorer/run-detail.tsx) | The model-run detail page — profile, JSON config/metrics/runtime info, store/product cross-links, artifact integrity verify, compare link | Investigating a single model run |
+| [`frontend/src/pages/explorer/job-detail.tsx`](../../frontend/src/pages/explorer/job-detail.tsx) | The job detail page — profile, params/result JSON, error details, linked run, cancel action, live polling | Investigating a single job |
+| [`frontend/src/pages/explorer/run-compare.tsx`](../../frontend/src/pages/explorer/run-compare.tsx) | The run-comparison page — two run pickers, side-by-side profile, config_diff, metrics_diff with delta indicators; deep-linkable via `?a=&b=` | Comparing two model runs |
 | [`alembic/versions/`](../../alembic/versions/) | Six migrations through `d6e0f2g3h456_create_agent_session_table.py` | DB-schema questions, migration drift |
 | [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md) | Phase-by-phase architecture narrative | High-level component reasoning |
 | [`docs/PHASE-index.md`](../PHASE-index.md) | Index of all 11 phase docs | Locating per-phase deep-dive |
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index c853e202..bf953b13 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -12,12 +12,19 @@ const DashboardPage = lazy(() => import('@/pages/dashboard'))
 const ShowcasePage = lazy(() => import('@/pages/showcase'))
 const SalesExplorerPage = lazy(() => import('@/pages/explorer/sales'))
 const StoresExplorerPage = lazy(() => import('@/pages/explorer/stores'))
+const StoreDetailPage = lazy(() => import('@/pages/explorer/store-detail'))
 const ProductsExplorerPage = lazy(() => import('@/pages/explorer/products'))
+const ProductDetailPage = lazy(() => import('@/pages/explorer/product-detail'))
 const RunsExplorerPage = lazy(() => import('@/pages/explorer/runs'))
+const RunDetailPage = lazy(() => import('@/pages/explorer/run-detail'))
+const RunComparePage = lazy(() => import('@/pages/explorer/run-compare'))
 const JobsMonitorPage = lazy(() => import('@/pages/explorer/jobs'))
+const JobDetailPage = lazy(() => import('@/pages/explorer/job-detail'))
 const ForecastPage = lazy(() => import('@/pages/visualize/forecast'))
 const BacktestPage = lazy(() => import('@/pages/visualize/backtest'))
 const ChatPage = lazy(() => import('@/pages/chat'))
+const KnowledgePage = lazy(() => import('@/pages/knowledge'))
+const GuidePage = lazy(() => import('@/pages/guide'))
 const AdminPage = lazy(() => import('@/pages/admin'))
 
 function PageLoader() {
@@ -63,6 +70,14 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.EXPLORER.STORE_DETAIL}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <StoreDetailPage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.EXPLORER.PRODUCTS}
                 element={
@@ -71,6 +86,14 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.EXPLORER.PRODUCT_DETAIL}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <ProductDetailPage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.EXPLORER.RUNS}
                 element={
@@ -79,6 +102,22 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.EXPLORER.RUN_COMPARE}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <RunComparePage />
+                  </Suspense>
+                }
+              />
+              <Route
+                path={ROUTES.EXPLORER.RUN_DETAIL}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <RunDetailPage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.EXPLORER.JOBS}
                 element={
@@ -87,6 +126,14 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.EXPLORER.JOB_DETAIL}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <JobDetailPage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.VISUALIZE.FORECAST}
                 element={
@@ -103,6 +150,14 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.KNOWLEDGE}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <KnowledgePage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.CHAT}
                 element={
@@ -111,6 +166,14 @@ function App() {
                   </Suspense>
                 }
               />
+              <Route
+                path={ROUTES.GUIDE}
+                element={
+                  <Suspense fallback={<PageLoader />}>
+                    <GuidePage />
+                  </Suspense>
+                }
+              />
               <Route
                 path={ROUTES.ADMIN}
                 element={
diff --git a/frontend/src/components/charts/index.ts b/frontend/src/components/charts/index.ts
index 1144d92d..2e439f7a 100644
--- a/frontend/src/components/charts/index.ts
+++ b/frontend/src/components/charts/index.ts
@@ -1,3 +1,4 @@
 export * from './kpi-card'
 export * from './time-series-chart'
 export * from './backtest-folds-chart'
+export * from './revenue-bar-chart'
diff --git a/frontend/src/components/charts/revenue-bar-chart.tsx b/frontend/src/components/charts/revenue-bar-chart.tsx
new file mode 100644
index 00000000..58ff87b9
--- /dev/null
+++ b/frontend/src/components/charts/revenue-bar-chart.tsx
@@ -0,0 +1,56 @@
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid } from 'recharts'
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+} from '@/components/ui/chart'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+
+interface RevenueBarDatum {
+  label: string
+  revenue: number
+}
+
+interface RevenueBarChartProps {
+  title: string
+  description?: string
+  data: RevenueBarDatum[]
+  height?: number
+  className?: string
+}
+
+// The --chart-N vars are complete oklch() colours (Tailwind 4 / shadcn v4);
+// reference them directly — wrapping in hsl() produces invalid CSS (black).
+const chartConfig: ChartConfig = {
+  revenue: { label: 'Revenue', color: 'var(--chart-1)' },
+}
+
+/** Revenue-by-dimension bar chart. Feed Number()-coerced revenue values. */
+export function RevenueBarChart({
+  title,
+  description,
+  data,
+  height = 300,
+  className,
+}: RevenueBarChartProps) {
+  return (
+    <Card className={className}>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+        {description && <CardDescription>{description}</CardDescription>}
+      </CardHeader>
+      <CardContent>
+        <ChartContainer config={chartConfig} className={`h-[${height}px] w-full`}>
+          <BarChart data={data} accessibilityLayer>
+            <CartesianGrid strokeDasharray="3 3" />
+            <XAxis dataKey="label" tickLine={false} axisLine={false} />
+            <YAxis tickLine={false} axisLine={false} />
+            <ChartTooltip content={<ChartTooltipContent />} />
+            <Bar dataKey="revenue" name="Revenue" fill="var(--chart-1)" radius={[4, 4, 0, 0]} />
+          </BarChart>
+        </ChartContainer>
+      </CardContent>
+    </Card>
+  )
+}
diff --git a/frontend/src/components/common/index.ts b/frontend/src/components/common/index.ts
index c74b7e8a..913b7710 100644
--- a/frontend/src/components/common/index.ts
+++ b/frontend/src/components/common/index.ts
@@ -3,3 +3,4 @@ export * from './date-range-picker'
 export * from './error-display'
 export * from './loading-state'
 export * from './job-picker'
+export * from './json-block'
diff --git a/frontend/src/components/common/json-block.tsx b/frontend/src/components/common/json-block.tsx
new file mode 100644
index 00000000..656f894c
--- /dev/null
+++ b/frontend/src/components/common/json-block.tsx
@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils'
+
+interface JsonBlockProps {
+  value: unknown
+  className?: string
+}
+
+/**
+ * Read-only formatted-JSON viewer. Renders a muted em-dash for null/undefined,
+ * otherwise a scrollable, pretty-printed <pre> block. Intentionally has no
+ * syntax-highlighter dependency — it surfaces run/job JSONB payloads as-is.
+ */
+export function JsonBlock({ value, className }: JsonBlockProps) {
+  if (value === null || value === undefined) {
+    return <span className="text-sm text-muted-foreground">—</span>
+  }
+
+  return (
+    <pre
+      className={cn(
+        'max-h-96 overflow-auto whitespace-pre-wrap break-all rounded-md border bg-muted/40 p-3 font-mono text-xs',
+        className,
+      )}
+    >
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  )
+}
diff --git a/frontend/src/components/data-table/data-table-column-header.tsx b/frontend/src/components/data-table/data-table-column-header.tsx
new file mode 100644
index 00000000..69212ad0
--- /dev/null
+++ b/frontend/src/components/data-table/data-table-column-header.tsx
@@ -0,0 +1,41 @@
+import { Column } from '@tanstack/react-table'
+import { ArrowDown, ArrowUp, ChevronsUpDown } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+
+interface DataTableColumnHeaderProps<TData, TValue> {
+  column: Column<TData, TValue>
+  title: string
+  className?: string
+}
+
+/** Sortable column header — clicking toggles the column's sort direction. */
+export function DataTableColumnHeader<TData, TValue>({
+  column,
+  title,
+  className,
+}: DataTableColumnHeaderProps<TData, TValue>) {
+  if (!column.getCanSort()) {
+    return <span className={className}>{title}</span>
+  }
+
+  const sorted = column.getIsSorted()
+
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      className={cn('-ml-3 h-8', className)}
+      onClick={() => column.toggleSorting(sorted === 'asc')}
+    >
+      <span>{title}</span>
+      {sorted === 'desc' ? (
+        <ArrowDown className="ml-2 h-4 w-4" />
+      ) : sorted === 'asc' ? (
+        <ArrowUp className="ml-2 h-4 w-4" />
+      ) : (
+        <ChevronsUpDown className="ml-2 h-4 w-4 opacity-50" />
+      )}
+    </Button>
+  )
+}
diff --git a/frontend/src/components/data-table/data-table-view-options.tsx b/frontend/src/components/data-table/data-table-view-options.tsx
new file mode 100644
index 00000000..0a72f647
--- /dev/null
+++ b/frontend/src/components/data-table/data-table-view-options.tsx
@@ -0,0 +1,45 @@
+import { Table } from '@tanstack/react-table'
+import { SlidersHorizontal } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+
+interface DataTableViewOptionsProps<TData> {
+  table: Table<TData>
+}
+
+/** Column-visibility dropdown — toggles which DataTable columns are shown. */
+export function DataTableViewOptions<TData>({ table }: DataTableViewOptionsProps<TData>) {
+  const hideableColumns = table.getAllColumns().filter((column) => column.getCanHide())
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline" size="sm" className="h-8">
+          <SlidersHorizontal className="mr-2 h-4 w-4" />
+          View
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-[180px]">
+        <DropdownMenuLabel>Toggle columns</DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        {hideableColumns.map((column) => (
+          <DropdownMenuCheckboxItem
+            key={column.id}
+            className="capitalize"
+            checked={column.getIsVisible()}
+            onCheckedChange={(value) => column.toggleVisibility(!!value)}
+          >
+            {column.id}
+          </DropdownMenuCheckboxItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/frontend/src/components/data-table/data-table.tsx b/frontend/src/components/data-table/data-table.tsx
index dc4b9091..2224a87c 100644
--- a/frontend/src/components/data-table/data-table.tsx
+++ b/frontend/src/components/data-table/data-table.tsx
@@ -1,3 +1,4 @@
+import { useState } from 'react'
 import {
   ColumnDef,
   flexRender,
@@ -6,6 +7,7 @@ import {
   PaginationState,
   OnChangeFn,
   SortingState,
+  VisibilityState,
 } from '@tanstack/react-table'
 import {
   Table,
@@ -16,7 +18,9 @@ import {
   TableRow,
 } from '@/components/ui/table'
 import { DataTablePagination } from './data-table-pagination'
+import { DataTableViewOptions } from './data-table-view-options'
 import { Skeleton } from '@/components/ui/skeleton'
+import { cn } from '@/lib/utils'
 
 interface DataTableProps<TData, TValue> {
   columns: ColumnDef<TData, TValue>[]
@@ -26,6 +30,10 @@ interface DataTableProps<TData, TValue> {
   onPaginationChange: OnChangeFn<PaginationState>
   sorting?: SortingState
   onSortingChange?: OnChangeFn<SortingState>
+  /** When set, each data row becomes clickable and calls this with the row. */
+  onRowClick?: (row: TData) => void
+  /** When true, renders a column-visibility dropdown above the table. */
+  enableColumnVisibility?: boolean
   isLoading?: boolean
   emptyMessage?: string
 }
@@ -38,9 +46,13 @@ export function DataTable<TData, TValue>({
   onPaginationChange,
   sorting,
   onSortingChange,
+  onRowClick,
+  enableColumnVisibility = false,
   isLoading = false,
   emptyMessage = 'No results.',
 }: DataTableProps<TData, TValue>) {
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
+
   const table = useReactTable({
     data,
     columns,
@@ -48,9 +60,11 @@ export function DataTable<TData, TValue>({
     state: {
       pagination,
       sorting,
+      columnVisibility,
     },
     onPaginationChange,
     onSortingChange,
+    onColumnVisibilityChange: setColumnVisibility,
     getCoreRowModel: getCoreRowModel(),
     manualPagination: true,
     manualSorting: true,
@@ -58,6 +72,11 @@ export function DataTable<TData, TValue>({
 
   return (
     <div className="space-y-4">
+      {enableColumnVisibility && (
+        <div className="flex justify-end">
+          <DataTableViewOptions table={table} />
+        </div>
+      )}
       <div className="rounded-md border">
         <Table>
           <TableHeader>
@@ -93,6 +112,8 @@ export function DataTable<TData, TValue>({
                 <TableRow
                   key={row.id}
                   data-state={row.getIsSelected() && 'selected'}
+                  onClick={onRowClick ? () => onRowClick(row.original) : undefined}
+                  className={cn(onRowClick && 'cursor-pointer')}
                 >
                   {row.getVisibleCells().map((cell) => (
                     <TableCell key={cell.id}>
diff --git a/frontend/src/components/data-table/index.ts b/frontend/src/components/data-table/index.ts
index 36742e9b..75d3d28f 100644
--- a/frontend/src/components/data-table/index.ts
+++ b/frontend/src/components/data-table/index.ts
@@ -1,3 +1,5 @@
 export * from './data-table'
 export * from './data-table-pagination'
 export * from './data-table-toolbar'
+export * from './data-table-view-options'
+export * from './data-table-column-header'
diff --git a/frontend/src/hooks/index.ts b/frontend/src/hooks/index.ts
index 8f26c454..43fdc939 100644
--- a/frontend/src/hooks/index.ts
+++ b/frontend/src/hooks/index.ts
@@ -2,6 +2,8 @@ export * from './use-stores'
 export * from './use-products'
 export * from './use-kpis'
 export * from './use-drilldowns'
+export * from './use-timeseries'
+export * from './use-lifecycle-curve'
 export * from './use-runs'
 export * from './use-jobs'
 export * from './use-rag-sources'
diff --git a/frontend/src/hooks/use-jobs.ts b/frontend/src/hooks/use-jobs.ts
index aee1b26b..46c4f6d1 100644
--- a/frontend/src/hooks/use-jobs.ts
+++ b/frontend/src/hooks/use-jobs.ts
@@ -7,6 +7,8 @@ interface UseJobsParams {
   pageSize: number
   jobType?: JobType
   status?: JobStatus
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
   enabled?: boolean
 }
 
@@ -15,10 +17,12 @@ export function useJobs({
   pageSize,
   jobType,
   status,
+  sortBy,
+  sortOrder,
   enabled = true,
 }: UseJobsParams) {
   return useQuery({
-    queryKey: ['jobs', { page, pageSize, jobType, status }],
+    queryKey: ['jobs', { page, pageSize, jobType, status, sortBy, sortOrder }],
     queryFn: () =>
       api<JobListResponse>('/jobs', {
         params: {
@@ -26,6 +30,8 @@ export function useJobs({
           page_size: pageSize,
           job_type: jobType,
           status,
+          sort_by: sortBy,
+          sort_order: sortOrder,
         },
       }),
     placeholderData: keepPreviousData,
diff --git a/frontend/src/hooks/use-lifecycle-curve.ts b/frontend/src/hooks/use-lifecycle-curve.ts
new file mode 100644
index 00000000..84395e48
--- /dev/null
+++ b/frontend/src/hooks/use-lifecycle-curve.ts
@@ -0,0 +1,27 @@
+import { useQuery } from '@tanstack/react-query'
+import { api } from '@/lib/api'
+import type { LifecycleCurveResponse } from '@/types/api'
+
+interface UseLifecycleCurveParams {
+  startDate?: string
+  endDate?: string
+  enabled?: boolean
+}
+
+/** GET /dimensions/products/{id}/lifecycle-curve — reference demand curve for a product. */
+export function useLifecycleCurve(
+  productId: number,
+  { startDate, endDate, enabled = true }: UseLifecycleCurveParams = {}
+) {
+  return useQuery({
+    queryKey: ['lifecycle-curve', productId, { startDate, endDate }],
+    queryFn: () =>
+      api<LifecycleCurveResponse>(`/dimensions/products/${productId}/lifecycle-curve`, {
+        params: {
+          start_date: startDate,
+          end_date: endDate,
+        },
+      }),
+    enabled: enabled && productId > 0,
+  })
+}
diff --git a/frontend/src/hooks/use-products.ts b/frontend/src/hooks/use-products.ts
index 6e00d04d..8f08b791 100644
--- a/frontend/src/hooks/use-products.ts
+++ b/frontend/src/hooks/use-products.ts
@@ -8,6 +8,8 @@ interface UseProductsParams {
   category?: string
   brand?: string
   search?: string
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
   enabled?: boolean
 }
 
@@ -17,10 +19,12 @@ export function useProducts({
   category,
   brand,
   search,
+  sortBy,
+  sortOrder,
   enabled = true,
 }: UseProductsParams) {
   return useQuery({
-    queryKey: ['products', { page, pageSize, category, brand, search }],
+    queryKey: ['products', { page, pageSize, category, brand, search, sortBy, sortOrder }],
     queryFn: () =>
       api<ProductListResponse>('/dimensions/products', {
         params: {
@@ -29,6 +33,8 @@ export function useProducts({
           category,
           brand,
           search: search && search.length >= 2 ? search : undefined,
+          sort_by: sortBy,
+          sort_order: sortOrder,
         },
       }),
     placeholderData: keepPreviousData,
diff --git a/frontend/src/hooks/use-rag-sources.ts b/frontend/src/hooks/use-rag-sources.ts
index 24663567..ee80cc93 100644
--- a/frontend/src/hooks/use-rag-sources.ts
+++ b/frontend/src/hooks/use-rag-sources.ts
@@ -1,6 +1,12 @@
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import { api } from '@/lib/api'
-import type { SourceListResponse, IndexDocumentRequest, IndexDocumentResponse } from '@/types/api'
+import type {
+  SourceListResponse,
+  IndexDocumentRequest,
+  IndexDocumentResponse,
+  RetrieveRequest,
+  RetrieveResponse,
+} from '@/types/api'
 
 export function useRagSources() {
   return useQuery({
@@ -33,3 +39,13 @@ export function useIndexDocument() {
     },
   })
 }
+
+// Mutation: semantic search over the knowledge base (POST /rag/retrieve).
+// Search results are ephemeral — no cache invalidation. A 502 (no embedding
+// provider configured) surfaces as an ApiError the caller degrades gracefully.
+export function useRetrieve() {
+  return useMutation({
+    mutationFn: (body: RetrieveRequest) =>
+      api<RetrieveResponse>('/rag/retrieve', { method: 'POST', body }),
+  })
+}
diff --git a/frontend/src/hooks/use-runs.ts b/frontend/src/hooks/use-runs.ts
index e1d0ffbe..1234919a 100644
--- a/frontend/src/hooks/use-runs.ts
+++ b/frontend/src/hooks/use-runs.ts
@@ -1,6 +1,13 @@
 import { useQuery, useMutation, useQueryClient, keepPreviousData } from '@tanstack/react-query'
 import { api } from '@/lib/api'
-import type { RunListResponse, ModelRun, Alias, RunCompareResponse, RunStatus } from '@/types/api'
+import type {
+  RunListResponse,
+  ModelRun,
+  Alias,
+  RunCompareResponse,
+  RunStatus,
+  ArtifactVerifyResponse,
+} from '@/types/api'
 
 interface UseRunsParams {
   page: number
@@ -9,6 +16,8 @@ interface UseRunsParams {
   status?: RunStatus
   storeId?: number
   productId?: number
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
   enabled?: boolean
 }
 
@@ -19,10 +28,15 @@ export function useRuns({
   status,
   storeId,
   productId,
+  sortBy,
+  sortOrder,
   enabled = true,
 }: UseRunsParams) {
   return useQuery({
-    queryKey: ['runs', { page, pageSize, modelType, status, storeId, productId }],
+    queryKey: [
+      'runs',
+      { page, pageSize, modelType, status, storeId, productId, sortBy, sortOrder },
+    ],
     queryFn: () =>
       api<RunListResponse>('/registry/runs', {
         params: {
@@ -32,6 +46,8 @@ export function useRuns({
           status,
           store_id: storeId,
           product_id: productId,
+          sort_by: sortBy,
+          sort_order: sortOrder,
         },
       }),
     placeholderData: keepPreviousData,
@@ -55,6 +71,21 @@ export function useCompareRuns(runIdA: string, runIdB: string, enabled = false)
   })
 }
 
+/**
+ * Button-gated artifact integrity check. Pass `enabled` from component state
+ * (false until the user clicks "Verify"), then call `refetch()` to re-run.
+ * The endpoint returns HTTP 200 with `verified:false` on a checksum mismatch
+ * and only errors (404/400) for a missing run/artifact.
+ */
+export function useVerifyArtifact(runId: string, enabled = false) {
+  return useQuery({
+    queryKey: ['runs', runId, 'verify'],
+    queryFn: () => api<ArtifactVerifyResponse>(`/registry/runs/${runId}/verify`),
+    enabled: enabled && !!runId,
+    retry: false,
+  })
+}
+
 export function useUpdateRun() {
   const queryClient = useQueryClient()
   return useMutation({
diff --git a/frontend/src/hooks/use-stores.ts b/frontend/src/hooks/use-stores.ts
index 7c8512c9..8c11adcf 100644
--- a/frontend/src/hooks/use-stores.ts
+++ b/frontend/src/hooks/use-stores.ts
@@ -8,6 +8,8 @@ interface UseStoresParams {
   region?: string
   storeType?: string
   search?: string
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
   enabled?: boolean
 }
 
@@ -17,10 +19,12 @@ export function useStores({
   region,
   storeType,
   search,
+  sortBy,
+  sortOrder,
   enabled = true,
 }: UseStoresParams) {
   return useQuery({
-    queryKey: ['stores', { page, pageSize, region, storeType, search }],
+    queryKey: ['stores', { page, pageSize, region, storeType, search, sortBy, sortOrder }],
     queryFn: () =>
       api<StoreListResponse>('/dimensions/stores', {
         params: {
@@ -29,6 +33,8 @@ export function useStores({
           region,
           store_type: storeType,
           search: search && search.length >= 2 ? search : undefined,
+          sort_by: sortBy,
+          sort_order: sortOrder,
         },
       }),
     placeholderData: keepPreviousData,
diff --git a/frontend/src/hooks/use-timeseries.ts b/frontend/src/hooks/use-timeseries.ts
new file mode 100644
index 00000000..ad775e52
--- /dev/null
+++ b/frontend/src/hooks/use-timeseries.ts
@@ -0,0 +1,41 @@
+import { useQuery, keepPreviousData } from '@tanstack/react-query'
+import { api } from '@/lib/api'
+import type { TimeGranularity, TimeSeriesResponse } from '@/types/api'
+
+interface UseTimeseriesParams {
+  startDate: string
+  endDate: string
+  granularity?: TimeGranularity
+  storeId?: number
+  productId?: number
+  category?: string
+  enabled?: boolean
+}
+
+/** GET /analytics/timeseries — period-bucketed sales for revenue-over-time charts. */
+export function useTimeseries({
+  startDate,
+  endDate,
+  granularity = 'day',
+  storeId,
+  productId,
+  category,
+  enabled = true,
+}: UseTimeseriesParams) {
+  return useQuery({
+    queryKey: ['timeseries', { startDate, endDate, granularity, storeId, productId, category }],
+    queryFn: () =>
+      api<TimeSeriesResponse>('/analytics/timeseries', {
+        params: {
+          start_date: startDate,
+          end_date: endDate,
+          granularity,
+          store_id: storeId,
+          product_id: productId,
+          category,
+        },
+      }),
+    placeholderData: keepPreviousData,
+    enabled: enabled && !!startDate && !!endDate,
+  })
+}
diff --git a/frontend/src/lib/constants.ts b/frontend/src/lib/constants.ts
index ff5acf62..e6c749bc 100644
--- a/frontend/src/lib/constants.ts
+++ b/frontend/src/lib/constants.ts
@@ -8,12 +8,23 @@ export const ROUTES = {
     PRODUCTS: '/explorer/products',
     RUNS: '/explorer/runs',
     JOBS: '/explorer/jobs',
+    // Click-through detail routes (dynamic segments) — reached from table rows,
+    // intentionally NOT in NAV_ITEMS.
+    STORE_DETAIL: '/explorer/stores/:storeId',
+    PRODUCT_DETAIL: '/explorer/products/:productId',
+    RUN_DETAIL: '/explorer/runs/:runId',
+    JOB_DETAIL: '/explorer/jobs/:jobId',
+    // Static — must out-rank RUN_DETAIL's :runId segment (React Router v6
+    // ranks by specificity, so registration order does not matter).
+    RUN_COMPARE: '/explorer/runs/compare',
   },
   VISUALIZE: {
     FORECAST: '/visualize/forecast',
     BACKTEST: '/visualize/backtest',
   },
+  KNOWLEDGE: '/knowledge',
   CHAT: '/chat',
+  GUIDE: '/guide',
   ADMIN: '/admin',
 } as const
 
@@ -38,7 +49,9 @@ export const NAV_ITEMS = [
       { label: 'Backtest Results', href: ROUTES.VISUALIZE.BACKTEST },
     ],
   },
+  { label: 'Knowledge', href: ROUTES.KNOWLEDGE },
   { label: 'Chat', href: ROUTES.CHAT },
+  { label: 'Agent Guide', href: ROUTES.GUIDE },
   { label: 'Admin', href: ROUTES.ADMIN },
 ] as const
 
diff --git a/frontend/src/lib/csv-export.test.ts b/frontend/src/lib/csv-export.test.ts
new file mode 100644
index 00000000..4112527c
--- /dev/null
+++ b/frontend/src/lib/csv-export.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest'
+import { toCsv, type CsvColumn } from './csv-export'
+
+interface Row {
+  name: string
+  city: string
+  qty: number
+}
+
+const columns: CsvColumn<Row>[] = [
+  { key: 'name', header: 'Name' },
+  { key: 'city', header: 'City' },
+  { key: 'qty', header: 'Quantity' },
+]
+
+describe('toCsv', () => {
+  it('emits a header-only string for empty rows', () => {
+    expect(toCsv([], columns)).toBe('Name,City,Quantity')
+  })
+
+  it('serializes rows joined with CRLF', () => {
+    const csv = toCsv([{ name: 'Acme', city: 'Springfield', qty: 3 }], columns)
+    expect(csv).toBe('Name,City,Quantity\r\nAcme,Springfield,3')
+  })
+
+  it('quotes and escapes fields containing commas and quotes', () => {
+    const csv = toCsv([{ name: 'A, Inc', city: 'Say "Hi"', qty: 1 }], columns)
+    expect(csv).toBe('Name,City,Quantity\r\n"A, Inc","Say ""Hi""",1')
+  })
+
+  it('quotes a field containing a newline', () => {
+    const csv = toCsv([{ name: 'Line1\nLine2', city: 'X', qty: 0 }], columns)
+    expect(csv).toContain('"Line1\nLine2"')
+  })
+
+  it('preserves the column order from the columns argument', () => {
+    const reordered: CsvColumn<Row>[] = [
+      { key: 'qty', header: 'Quantity' },
+      { key: 'name', header: 'Name' },
+    ]
+    const csv = toCsv([{ name: 'Acme', city: 'X', qty: 7 }], reordered)
+    expect(csv).toBe('Quantity,Name\r\n7,Acme')
+  })
+
+  it('renders null and undefined as empty fields', () => {
+    interface NullableRow {
+      a: string | null
+      b: number | undefined
+    }
+    const nullableColumns: CsvColumn<NullableRow>[] = [
+      { key: 'a', header: 'A' },
+      { key: 'b', header: 'B' },
+    ]
+    expect(toCsv([{ a: null, b: undefined }], nullableColumns)).toBe('A,B\r\n,')
+  })
+})
diff --git a/frontend/src/lib/csv-export.ts b/frontend/src/lib/csv-export.ts
new file mode 100644
index 00000000..692cbdc7
--- /dev/null
+++ b/frontend/src/lib/csv-export.ts
@@ -0,0 +1,41 @@
+/** Column descriptor for CSV export: a row key plus a human-readable header. */
+export interface CsvColumn<T> {
+  key: keyof T & string
+  header: string
+}
+
+/** Quote a single CSV field per RFC 4180 (wrap + double internal quotes). */
+function quoteField(value: unknown): string {
+  const str = value === null || value === undefined ? '' : String(value)
+  if (/[",\r\n]/.test(str)) {
+    return `"${str.replace(/"/g, '""')}"`
+  }
+  return str
+}
+
+/**
+ * Serialize rows to an RFC 4180 CSV string.
+ *
+ * Always emits the header row; rows are joined with CRLF. Empty `rows`
+ * yields a header-only string.
+ */
+export function toCsv<T>(rows: T[], columns: CsvColumn<T>[]): string {
+  const header = columns.map((column) => quoteField(column.header)).join(',')
+  const body = rows.map((row) =>
+    columns.map((column) => quoteField(row[column.key])).join(',')
+  )
+  return [header, ...body].join('\r\n')
+}
+
+/** Trigger a browser download of `csv` content as `filename`. */
+export function downloadCsv(filename: string, csv: string): void {
+  const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = filename
+  document.body.appendChild(link)
+  link.click()
+  document.body.removeChild(link)
+  URL.revokeObjectURL(url)
+}
diff --git a/frontend/src/lib/knowledge-utils.test.ts b/frontend/src/lib/knowledge-utils.test.ts
new file mode 100644
index 00000000..c00e0663
--- /dev/null
+++ b/frontend/src/lib/knowledge-utils.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import { formatRelevance, groupSourcesByType, chunkExcerpt } from './knowledge-utils'
+import type { RagSource, ChunkResult } from '@/types/api'
+
+/** Build a RagSource with sensible defaults for the fields not under test. */
+function makeSource(partial: Partial<RagSource> & Pick<RagSource, 'source_id'>): RagSource {
+  return {
+    source_id: partial.source_id,
+    source_type: partial.source_type ?? 'markdown',
+    source_path: partial.source_path ?? 'docs/example.md',
+    chunk_count: partial.chunk_count ?? 3,
+    content_hash: partial.content_hash ?? 'hash',
+    indexed_at: partial.indexed_at ?? '2026-05-18T00:00:00Z',
+    metadata: partial.metadata ?? null,
+  }
+}
+
+/** Build a ChunkResult with sensible defaults for the fields not under test. */
+function makeChunk(partial: Partial<ChunkResult> & Pick<ChunkResult, 'content'>): ChunkResult {
+  return {
+    chunk_id: partial.chunk_id ?? 'chunk-1',
+    source_id: partial.source_id ?? 'src-1',
+    source_path: partial.source_path ?? 'docs/example.md',
+    source_type: partial.source_type ?? 'markdown',
+    content: partial.content,
+    relevance_score: partial.relevance_score ?? 0.8,
+    metadata: partial.metadata ?? null,
+  }
+}
+
+describe('formatRelevance', () => {
+  it('renders a score as a rounded percentage', () => {
+    expect(formatRelevance(0.873)).toBe('87%')
+  })
+
+  it('clamps the endpoints', () => {
+    expect(formatRelevance(0)).toBe('0%')
+    expect(formatRelevance(1)).toBe('100%')
+  })
+
+  it('clamps out-of-range values', () => {
+    expect(formatRelevance(1.4)).toBe('100%')
+    expect(formatRelevance(-0.2)).toBe('0%')
+  })
+
+  it('treats a non-finite score as zero', () => {
+    expect(formatRelevance(Number.NaN)).toBe('0%')
+    expect(formatRelevance(Number.POSITIVE_INFINITY)).toBe('0%')
+  })
+})
+
+describe('groupSourcesByType', () => {
+  it('groups a mixed source list into per-type buckets', () => {
+    const groups = groupSourcesByType([
+      makeSource({ source_id: 'a', source_type: 'markdown' }),
+      makeSource({ source_id: 'b', source_type: 'openapi' }),
+      makeSource({ source_id: 'c', source_type: 'markdown' }),
+    ])
+    expect(Object.keys(groups).sort()).toEqual(['markdown', 'openapi'])
+    expect(groups.markdown).toHaveLength(2)
+    expect(groups.openapi).toHaveLength(1)
+  })
+
+  it('returns an empty object for an empty array', () => {
+    expect(groupSourcesByType([])).toEqual({})
+  })
+
+  it('falls back to "unknown" for a blank source_type', () => {
+    const groups = groupSourcesByType([makeSource({ source_id: 'a', source_type: '' })])
+    expect(groups.unknown).toHaveLength(1)
+  })
+})
+
+describe('chunkExcerpt', () => {
+  it('returns short content intact with collapsed whitespace', () => {
+    const chunk = makeChunk({ content: '  hello   world\n\tagain  ' })
+    expect(chunkExcerpt(chunk)).toBe('hello world again')
+  })
+
+  it('truncates long content with an ellipsis', () => {
+    const chunk = makeChunk({ content: 'x'.repeat(500) })
+    const excerpt = chunkExcerpt(chunk)
+    expect(excerpt.endsWith('…')).toBe(true)
+    expect(excerpt.length).toBeLessThanOrEqual(241)
+  })
+
+  it('honours a custom maxChars', () => {
+    const chunk = makeChunk({ content: 'abcdefghij' })
+    expect(chunkExcerpt(chunk, 5)).toBe('abcde…')
+  })
+})
diff --git a/frontend/src/lib/knowledge-utils.ts b/frontend/src/lib/knowledge-utils.ts
new file mode 100644
index 00000000..386bac4d
--- /dev/null
+++ b/frontend/src/lib/knowledge-utils.ts
@@ -0,0 +1,43 @@
+// Pure, React-free helpers for the Knowledge page. Kept separate from the page
+// component so they are cheap to unit-test (see knowledge-utils.test.ts) —
+// mirrors the use-demo-pipeline.ts / status-utils.ts precedent.
+import type { RagSource, ChunkResult } from '@/types/api'
+
+/**
+ * Convert a relevance score (0..1) into a display percentage string.
+ * Non-finite or out-of-range inputs are clamped: 0.873 -> "87%",
+ * 1.4 -> "100%", -0.2 -> "0%".
+ */
+export function formatRelevance(score: number): string {
+  const safe = Number.isFinite(score) ? score : 0
+  const clamped = Math.min(1, Math.max(0, safe))
+  return `${Math.round(clamped * 100)}%`
+}
+
+/**
+ * Group indexed sources by their source_type (e.g. "markdown", "openapi").
+ * An empty array yields an empty object; a missing type falls back to "unknown".
+ */
+export function groupSourcesByType(sources: RagSource[]): Record<string, RagSource[]> {
+  const groups: Record<string, RagSource[]> = {}
+  for (const source of sources) {
+    const key = source.source_type || 'unknown'
+    if (!groups[key]) {
+      groups[key] = []
+    }
+    groups[key].push(source)
+  }
+  return groups
+}
+
+/**
+ * Single-line excerpt of a chunk's content for a result card. Collapses runs of
+ * whitespace and truncates with an ellipsis past `maxChars` (default 240).
+ */
+export function chunkExcerpt(chunk: ChunkResult, maxChars = 240): string {
+  const collapsed = chunk.content.replace(/\s+/g, ' ').trim()
+  if (collapsed.length <= maxChars) {
+    return collapsed
+  }
+  return `${collapsed.slice(0, maxChars).trimEnd()}…`
+}
diff --git a/frontend/src/pages/chat.tsx b/frontend/src/pages/chat.tsx
index f1da0a15..1a987401 100644
--- a/frontend/src/pages/chat.tsx
+++ b/frontend/src/pages/chat.tsx
@@ -1,5 +1,6 @@
 import { useState, useRef, useEffect, useCallback } from 'react'
-import { Bot, Plus } from 'lucide-react'
+import { Link } from 'react-router-dom'
+import { Bot, Plus, BookOpen } from 'lucide-react'
 import { useWebSocket } from '@/hooks/use-websocket'
 import { ChatMessage, StreamingMessage } from '@/components/chat/chat-message'
 import { ChatInput, ApprovalPrompt } from '@/components/chat/chat-input'
@@ -15,7 +16,7 @@ import {
   SelectValue,
 } from '@/components/ui/select'
 import { api } from '@/lib/api'
-import { WS_URL } from '@/lib/constants'
+import { WS_URL, ROUTES } from '@/lib/constants'
 import type { ChatMessage as ChatMessageType, AgentStreamEvent, AgentType, AgentSession } from '@/types/api'
 
 export default function ChatPage() {
@@ -217,6 +218,13 @@ export default function ChatPage() {
             >
               {isCreatingSession ? 'Creating...' : 'Start Session'}
             </Button>
+            <Link
+              to={ROUTES.GUIDE}
+              className="flex items-center justify-center gap-1.5 text-sm text-muted-foreground underline-offset-2 hover:underline"
+            >
+              <BookOpen className="h-3.5 w-3.5" />
+              New here? Read the Agent Guide
+            </Link>
           </CardContent>
         </Card>
       </div>
diff --git a/frontend/src/pages/explorer/job-detail.tsx b/frontend/src/pages/explorer/job-detail.tsx
new file mode 100644
index 00000000..e112b18a
--- /dev/null
+++ b/frontend/src/pages/explorer/job-detail.tsx
@@ -0,0 +1,208 @@
+import { Link, useParams } from 'react-router-dom'
+import { format } from 'date-fns'
+import { ArrowLeft, Loader2, XCircle } from 'lucide-react'
+import { useQueryClient } from '@tanstack/react-query'
+import { useJob, useCancelJob } from '@/hooks/use-jobs'
+import { JsonBlock } from '@/components/common/json-block'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { LoadingState } from '@/components/common/loading-state'
+import { StatusBadge } from '@/components/common/status-badge'
+import { getStatusVariant } from '@/lib/status-utils'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog'
+import { ROUTES } from '@/lib/constants'
+
+function fmtDate(value: string | null | undefined): string {
+  return value ? format(new Date(value), 'MMM d, yyyy HH:mm') : '—'
+}
+
+function Field({
+  label,
+  children,
+}: {
+  label: string
+  children: React.ReactNode
+}) {
+  return (
+    <div>
+      <dt className="text-xs text-muted-foreground">{label}</dt>
+      <dd className="font-medium">{children}</dd>
+    </div>
+  )
+}
+
+export default function JobDetailPage() {
+  const { jobId } = useParams()
+  // useJob already polls every 2s while the job is pending/running.
+  const jobQuery = useJob(jobId ?? '', !!jobId)
+  const cancelJob = useCancelJob()
+  const queryClient = useQueryClient()
+
+  if (!jobId) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Job Detail</h1>
+        <ErrorDisplay error={new Error('No job id in the URL.')} title="Invalid job" />
+      </div>
+    )
+  }
+
+  if (jobQuery.error) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Job Detail</h1>
+        <ErrorDisplay error={jobQuery.error} onRetry={() => void jobQuery.refetch()} />
+      </div>
+    )
+  }
+
+  if (jobQuery.isLoading || !jobQuery.data) {
+    return <LoadingState message="Loading job..." />
+  }
+
+  const job = jobQuery.data
+
+  async function handleCancel() {
+    await cancelJob.mutateAsync(jobId)
+    // useCancelJob invalidates ['jobs']; refresh this detail query explicitly
+    // so the page reflects the cancelled status immediately.
+    void queryClient.invalidateQueries({ queryKey: ['jobs', jobId] })
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+        <div className="space-y-1">
+          <Button asChild variant="ghost" size="sm" className="-ml-2 h-7">
+            <Link to={ROUTES.EXPLORER.JOBS}>
+              <ArrowLeft className="mr-1 h-4 w-4" />
+              Back to Jobs
+            </Link>
+          </Button>
+          <div className="flex flex-wrap items-center gap-3">
+            <h1 className="break-all font-mono text-2xl font-bold">{job.job_id}</h1>
+            <StatusBadge variant={getStatusVariant(job.status)}>{job.status}</StatusBadge>
+          </div>
+          <p className="text-sm capitalize text-muted-foreground">{job.job_type} job</p>
+        </div>
+        {job.status === 'pending' && (
+          <AlertDialog>
+            <AlertDialogTrigger asChild>
+              <Button variant="destructive" disabled={cancelJob.isPending}>
+                {cancelJob.isPending ? (
+                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                ) : (
+                  <XCircle className="mr-2 h-4 w-4" />
+                )}
+                Cancel job
+              </Button>
+            </AlertDialogTrigger>
+            <AlertDialogContent>
+              <AlertDialogHeader>
+                <AlertDialogTitle>Cancel Job</AlertDialogTitle>
+                <AlertDialogDescription>
+                  Are you sure you want to cancel this job? This action cannot be undone.
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogCancel>No, keep it</AlertDialogCancel>
+                <AlertDialogAction onClick={() => void handleCancel()}>
+                  Yes, cancel
+                </AlertDialogAction>
+              </AlertDialogFooter>
+            </AlertDialogContent>
+          </AlertDialog>
+        )}
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Job profile</CardTitle>
+          <CardDescription>Execution record for this job.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <dl className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
+            <Field label="Type">
+              <span className="capitalize">{job.job_type}</span>
+            </Field>
+            <Field label="Status">
+              <span className="capitalize">{job.status}</span>
+            </Field>
+            <Field label="Run">
+              {job.run_id ? (
+                <Link
+                  className="break-all font-mono text-sm text-primary hover:underline"
+                  to={`/explorer/runs/${job.run_id}`}
+                >
+                  {job.run_id}
+                </Link>
+              ) : (
+                '—'
+              )}
+            </Field>
+            <Field label="Created">{fmtDate(job.created_at)}</Field>
+            <Field label="Started">{fmtDate(job.started_at)}</Field>
+            <Field label="Completed">{fmtDate(job.completed_at)}</Field>
+          </dl>
+        </CardContent>
+      </Card>
+
+      {job.status === 'failed' && (
+        <Card className="border-destructive/50">
+          <CardHeader>
+            <CardTitle className="text-destructive">Error</CardTitle>
+            {job.error_type && (
+              <CardDescription className="font-mono text-destructive/80">
+                {job.error_type}
+              </CardDescription>
+            )}
+          </CardHeader>
+          <CardContent>
+            <p className="text-sm text-destructive/90">
+              {job.error_message ?? 'The job failed without an error message.'}
+            </p>
+          </CardContent>
+        </Card>
+      )}
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Parameters</CardTitle>
+          <CardDescription>Input configuration this job ran with.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <JsonBlock value={job.params} />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Result</CardTitle>
+          <CardDescription>Output payload produced by the job.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          {job.result == null ? (
+            <p className="text-sm text-muted-foreground">
+              {job.status === 'pending' || job.status === 'running'
+                ? 'No result yet — the job is still running.'
+                : 'This job produced no result.'}
+            </p>
+          ) : (
+            <JsonBlock value={job.result} />
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
diff --git a/frontend/src/pages/explorer/jobs.tsx b/frontend/src/pages/explorer/jobs.tsx
index 2410e203..380a732c 100644
--- a/frontend/src/pages/explorer/jobs.tsx
+++ b/frontend/src/pages/explorer/jobs.tsx
@@ -1,10 +1,11 @@
-import { useState } from 'react'
 import { format } from 'date-fns'
-import { ColumnDef, PaginationState } from '@tanstack/react-table'
-import { XCircle } from 'lucide-react'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { ColumnDef, OnChangeFn, PaginationState, SortingState } from '@tanstack/react-table'
+import { Download, XCircle } from 'lucide-react'
 import { useJobs, useCancelJob } from '@/hooks/use-jobs'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
+import { DataTableColumnHeader } from '@/components/data-table/data-table-column-header'
 import { StatusBadge } from '@/components/common/status-badge'
 import { getStatusVariant } from '@/lib/status-utils'
 import { ErrorDisplay } from '@/components/common/error-display'
@@ -20,21 +21,44 @@ import {
   AlertDialogTitle,
   AlertDialogTrigger,
 } from '@/components/ui/alert-dialog'
+import { toCsv, downloadCsv, type CsvColumn } from '@/lib/csv-export'
 import type { Job, JobStatus, JobType } from '@/types/api'
 import { DEFAULT_PAGE_SIZE } from '@/lib/constants'
 
+const csvColumns: CsvColumn<Job>[] = [
+  { key: 'job_id', header: 'Job ID' },
+  { key: 'job_type', header: 'Type' },
+  { key: 'status', header: 'Status' },
+  { key: 'run_id', header: 'Run ID' },
+  { key: 'created_at', header: 'Created' },
+  { key: 'completed_at', header: 'Completed' },
+]
+
 export default function JobsMonitorPage() {
-  const [pagination, setPagination] = useState<PaginationState>({
-    pageIndex: 0,
+  const navigate = useNavigate()
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // URL query string is the single source of truth for filter/sort/page state,
+  // so a pasted URL reproduces the exact view.
+  const jobType = searchParams.get('job_type') ?? undefined
+  const status = searchParams.get('status') ?? undefined
+  const page = Number(searchParams.get('page')) || 1
+  const sortBy = searchParams.get('sort_by') ?? undefined
+  const sortOrder: 'asc' | 'desc' = searchParams.get('sort_order') === 'desc' ? 'desc' : 'asc'
+
+  const pagination: PaginationState = {
+    pageIndex: page - 1,
     pageSize: DEFAULT_PAGE_SIZE,
-  })
-  const [filters, setFilters] = useState<Record<string, string | undefined>>({})
+  }
+  const sorting: SortingState = sortBy ? [{ id: sortBy, desc: sortOrder === 'desc' }] : []
 
   const { data, isLoading, error, refetch } = useJobs({
-    page: pagination.pageIndex + 1,
+    page,
     pageSize: pagination.pageSize,
-    jobType: filters.jobType as JobType | undefined,
-    status: filters.status as JobStatus | undefined,
+    jobType: jobType as JobType | undefined,
+    status: status as JobStatus | undefined,
+    sortBy,
+    sortOrder: sortBy ? sortOrder : undefined,
   })
 
   const cancelJob = useCancelJob()
@@ -47,13 +71,15 @@ export default function JobsMonitorPage() {
     {
       accessorKey: 'job_id',
       header: 'Job ID',
+      enableSorting: false,
+      enableHiding: false,
       cell: ({ row }) => (
         <span className="font-mono text-xs">{row.original.job_id.substring(0, 8)}...</span>
       ),
     },
     {
       accessorKey: 'status',
-      header: 'Status',
+      header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
       cell: ({ row }) => (
         <StatusBadge variant={getStatusVariant(row.original.status)}>
           {row.original.status}
@@ -62,7 +88,7 @@ export default function JobsMonitorPage() {
     },
     {
       accessorKey: 'job_type',
-      header: 'Type',
+      header: ({ column }) => <DataTableColumnHeader column={column} title="Type" />,
       cell: ({ row }) => (
         <span className="capitalize font-medium">{row.original.job_type}</span>
       ),
@@ -70,6 +96,7 @@ export default function JobsMonitorPage() {
     {
       accessorKey: 'params',
       header: 'Model',
+      enableSorting: false,
       cell: ({ row }) => {
         const modelType = row.original.params?.model_type
         return modelType ? String(modelType) : '-'
@@ -77,12 +104,12 @@ export default function JobsMonitorPage() {
     },
     {
       accessorKey: 'created_at',
-      header: 'Created',
+      header: ({ column }) => <DataTableColumnHeader column={column} title="Created" />,
       cell: ({ row }) => format(new Date(row.original.created_at), 'MMM d, HH:mm'),
     },
     {
       accessorKey: 'completed_at',
-      header: 'Completed',
+      header: ({ column }) => <DataTableColumnHeader column={column} title="Completed" />,
       cell: ({ row }) =>
         row.original.completed_at
           ? format(new Date(row.original.completed_at), 'MMM d, HH:mm')
@@ -91,54 +118,89 @@ export default function JobsMonitorPage() {
     {
       id: 'actions',
       header: '',
+      enableSorting: false,
+      enableHiding: false,
       cell: ({ row }) => {
         const job = row.original
         if (job.status !== 'pending') return null
 
         return (
-          <AlertDialog>
-            <AlertDialogTrigger asChild>
-              <Button variant="ghost" size="icon-sm">
-                <XCircle className="h-4 w-4 text-destructive" />
-              </Button>
-            </AlertDialogTrigger>
-            <AlertDialogContent>
-              <AlertDialogHeader>
-                <AlertDialogTitle>Cancel Job</AlertDialogTitle>
-                <AlertDialogDescription>
-                  Are you sure you want to cancel this job? This action cannot be undone.
-                </AlertDialogDescription>
-              </AlertDialogHeader>
-              <AlertDialogFooter>
-                <AlertDialogCancel>No, keep it</AlertDialogCancel>
-                <AlertDialogAction onClick={() => handleCancelJob(job.job_id)}>
-                  Yes, cancel
-                </AlertDialogAction>
-              </AlertDialogFooter>
-            </AlertDialogContent>
-          </AlertDialog>
+          // The row is clickable (onRowClick navigates) — stop the cancel
+          // control's clicks from bubbling up and also triggering navigation.
+          <div onClick={(e) => e.stopPropagation()}>
+            <AlertDialog>
+              <AlertDialogTrigger asChild>
+                <Button variant="ghost" size="icon-sm">
+                  <XCircle className="h-4 w-4 text-destructive" />
+                </Button>
+              </AlertDialogTrigger>
+              <AlertDialogContent>
+                <AlertDialogHeader>
+                  <AlertDialogTitle>Cancel Job</AlertDialogTitle>
+                  <AlertDialogDescription>
+                    Are you sure you want to cancel this job? This action cannot be undone.
+                  </AlertDialogDescription>
+                </AlertDialogHeader>
+                <AlertDialogFooter>
+                  <AlertDialogCancel>No, keep it</AlertDialogCancel>
+                  <AlertDialogAction onClick={() => handleCancelJob(job.job_id)}>
+                    Yes, cancel
+                  </AlertDialogAction>
+                </AlertDialogFooter>
+              </AlertDialogContent>
+            </AlertDialog>
+          </div>
         )
       },
     },
   ]
 
+  function updateParams(updates: Record<string, string | undefined>) {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev)
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined || value === '') next.delete(key)
+        else next.set(key, value)
+      }
+      return next
+    })
+  }
+
+  const handlePaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(pagination) : updater
+    updateParams({ page: String(next.pageIndex + 1) })
+  }
+
+  const handleSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(sorting) : updater
+    const first = next[0]
+    updateParams({
+      sort_by: first?.id,
+      sort_order: first ? (first.desc ? 'desc' : 'asc') : undefined,
+      page: '1',
+    })
+  }
+
   const handleFilterChange = (key: string, value: string | undefined) => {
-    setFilters((prev) => ({ ...prev, [key]: value }))
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+    const paramKey = key === 'jobType' ? 'job_type' : key
+    updateParams({ [paramKey]: value, page: '1' })
   }
 
   const handleReset = () => {
-    setFilters({})
-    setPagination({ pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE })
+    setSearchParams(new URLSearchParams())
   }
 
-  const hasActiveFilters = Object.values(filters).some(Boolean)
+  const handleExport = () => {
+    downloadCsv('jobs.csv', toCsv(data?.jobs ?? [], csvColumns))
+  }
+
+  const hasActiveFilters = !!jobType || !!status || !!sortBy
 
   if (error) {
     return (
       <div className="space-y-6">
         <h1 className="text-3xl font-bold">Jobs</h1>
-        <ErrorDisplay error={error} onRetry={refetch} />
+        <ErrorDisplay error={error} onRetry={() => void refetch()} />
       </div>
     )
   }
@@ -149,41 +211,51 @@ export default function JobsMonitorPage() {
     <div className="space-y-6">
       <h1 className="text-3xl font-bold">Jobs Monitor</h1>
 
-      <DataTableToolbar
-        filters={[
-          {
-            key: 'jobType',
-            label: 'Type',
-            options: [
-              { label: 'Train', value: 'train' },
-              { label: 'Predict', value: 'predict' },
-              { label: 'Backtest', value: 'backtest' },
-            ],
-          },
-          {
-            key: 'status',
-            label: 'Status',
-            options: [
-              { label: 'Pending', value: 'pending' },
-              { label: 'Running', value: 'running' },
-              { label: 'Completed', value: 'completed' },
-              { label: 'Failed', value: 'failed' },
-              { label: 'Cancelled', value: 'cancelled' },
-            ],
-          },
-        ]}
-        filterValues={filters}
-        onFilterChange={handleFilterChange}
-        onReset={handleReset}
-        hasActiveFilters={hasActiveFilters}
-      />
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <DataTableToolbar
+          filters={[
+            {
+              key: 'jobType',
+              label: 'Type',
+              options: [
+                { label: 'Train', value: 'train' },
+                { label: 'Predict', value: 'predict' },
+                { label: 'Backtest', value: 'backtest' },
+              ],
+            },
+            {
+              key: 'status',
+              label: 'Status',
+              options: [
+                { label: 'Pending', value: 'pending' },
+                { label: 'Running', value: 'running' },
+                { label: 'Completed', value: 'completed' },
+                { label: 'Failed', value: 'failed' },
+                { label: 'Cancelled', value: 'cancelled' },
+              ],
+            },
+          ]}
+          filterValues={{ jobType, status }}
+          onFilterChange={handleFilterChange}
+          onReset={handleReset}
+          hasActiveFilters={hasActiveFilters}
+        />
+        <Button variant="outline" size="sm" className="h-8" onClick={handleExport}>
+          <Download className="mr-2 h-4 w-4" />
+          Export CSV
+        </Button>
+      </div>
 
       <DataTable
         columns={columns}
         data={data?.jobs ?? []}
         pageCount={pageCount}
         pagination={pagination}
-        onPaginationChange={setPagination}
+        onPaginationChange={handlePaginationChange}
+        sorting={sorting}
+        onSortingChange={handleSortingChange}
+        onRowClick={(job) => navigate(`/explorer/jobs/${job.job_id}`)}
+        enableColumnVisibility
         isLoading={isLoading}
         emptyMessage="No jobs found."
       />
diff --git a/frontend/src/pages/explorer/product-detail.tsx b/frontend/src/pages/explorer/product-detail.tsx
new file mode 100644
index 00000000..380f0f5f
--- /dev/null
+++ b/frontend/src/pages/explorer/product-detail.tsx
@@ -0,0 +1,215 @@
+import { useState } from 'react'
+import { Link, useParams } from 'react-router-dom'
+import { subDays } from 'date-fns'
+import { ArrowLeft, DollarSign, ShoppingCart, TrendingUp, Users } from 'lucide-react'
+import { DateRange } from 'react-day-picker'
+import { useProduct } from '@/hooks/use-products'
+import { useKPIs } from '@/hooks/use-kpis'
+import { useTimeseries } from '@/hooks/use-timeseries'
+import { useDrilldowns } from '@/hooks/use-drilldowns'
+import { useLifecycleCurve } from '@/hooks/use-lifecycle-curve'
+import { KPICard } from '@/components/charts/kpi-card'
+import { TimeSeriesChart } from '@/components/charts/time-series-chart'
+import { RevenueBarChart } from '@/components/charts/revenue-bar-chart'
+import { DateRangePicker } from '@/components/common/date-range-picker'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { dateRangeToStrings } from '@/lib/date-utils'
+import { formatCurrency, formatNumber } from '@/lib/api'
+import { ROUTES } from '@/lib/constants'
+
+export default function ProductDetailPage() {
+  const { productId } = useParams()
+  const id = Number(productId)
+  const validId = !Number.isNaN(id) && id > 0
+
+  const [dateRange, setDateRange] = useState<DateRange | undefined>({
+    from: subDays(new Date(), 30),
+    to: new Date(),
+  })
+  const { startDate, endDate } = dateRangeToStrings(dateRange)
+  const rangeReady = !!startDate && !!endDate
+
+  const productQuery = useProduct(id, validId)
+  const kpiQuery = useKPIs({
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    productId: id,
+    enabled: validId && rangeReady,
+  })
+  const timeseriesQuery = useTimeseries({
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    granularity: 'day',
+    productId: id,
+    enabled: validId && rangeReady,
+  })
+  const topStoresQuery = useDrilldowns({
+    dimension: 'store',
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    productId: id,
+    maxItems: 10,
+    enabled: validId && rangeReady,
+  })
+  const lifecycleQuery = useLifecycleCurve(id, { enabled: validId })
+
+  if (!validId) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Product Detail</h1>
+        <ErrorDisplay
+          error={new Error(`"${productId}" is not a valid product id.`)}
+          title="Invalid product"
+        />
+      </div>
+    )
+  }
+
+  if (productQuery.error) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Product Detail</h1>
+        <ErrorDisplay error={productQuery.error} onRetry={() => void productQuery.refetch()} />
+      </div>
+    )
+  }
+
+  const product = productQuery.data
+  const metrics = kpiQuery.data?.metrics
+  const points = timeseriesQuery.data?.points ?? []
+  const topStores = topStoresQuery.data?.items ?? []
+  const lifecyclePoints = lifecycleQuery.data?.points ?? []
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+        <div className="space-y-1">
+          <Button asChild variant="ghost" size="sm" className="-ml-2 h-7">
+            <Link to={ROUTES.EXPLORER.PRODUCTS}>
+              <ArrowLeft className="mr-1 h-4 w-4" />
+              Back to Products
+            </Link>
+          </Button>
+          <h1 className="text-3xl font-bold">{product?.name ?? 'Product'}</h1>
+          {product && (
+            <p className="text-sm text-muted-foreground">
+              {product.sku}
+              {product.category ? ` · ${product.category}` : ''}
+            </p>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          <DateRangePicker value={dateRange} onChange={setDateRange} />
+          <Button asChild variant="outline">
+            <Link to={`${ROUTES.EXPLORER.SALES}?product_id=${id}`}>View in Sales</Link>
+          </Button>
+        </div>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Product profile</CardTitle>
+          <CardDescription>Dimension record for this product.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <dl className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+            <div>
+              <dt className="text-xs text-muted-foreground">SKU</dt>
+              <dd className="font-medium">{product?.sku ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Category</dt>
+              <dd className="font-medium">{product?.category ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Brand</dt>
+              <dd className="font-medium">{product?.brand ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Base Price</dt>
+              <dd className="font-medium">{formatCurrency(product?.base_price)}</dd>
+            </div>
+          </dl>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+        <KPICard
+          title="Total Revenue"
+          value={formatCurrency(metrics?.total_revenue)}
+          icon={DollarSign}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Units Sold"
+          value={formatNumber(metrics?.total_units)}
+          icon={ShoppingCart}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Transactions"
+          value={formatNumber(metrics?.total_transactions)}
+          icon={TrendingUp}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Avg Basket Value"
+          value={formatCurrency(metrics?.avg_basket_value)}
+          icon={Users}
+          isLoading={kpiQuery.isLoading}
+        />
+      </div>
+
+      {points.length > 0 ? (
+        <TimeSeriesChart
+          title="Revenue over time"
+          description="Daily revenue for the selected period."
+          data={points.map((p) => ({
+            date: p.period,
+            actual: Number(p.metrics.total_revenue),
+          }))}
+          showPredicted={false}
+        />
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Revenue over time</CardTitle>
+            <CardDescription>No sales in the selected period.</CardDescription>
+          </CardHeader>
+        </Card>
+      )}
+
+      {lifecyclePoints.length > 0 && (
+        <TimeSeriesChart
+          title="Lifecycle demand curve"
+          description="Reference demand multiplier across the product lifecycle."
+          data={lifecyclePoints.map((p) => ({
+            date: p.date,
+            actual: p.multiplier,
+          }))}
+          showPredicted={false}
+        />
+      )}
+
+      {topStores.length > 0 ? (
+        <RevenueBarChart
+          title="Top stores"
+          description="Highest-revenue stores selling this product."
+          data={topStores.map((item) => ({
+            label: item.dimension_value,
+            revenue: Number(item.metrics.total_revenue),
+          }))}
+        />
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Top stores</CardTitle>
+            <CardDescription>No store sales in the selected period.</CardDescription>
+          </CardHeader>
+        </Card>
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/pages/explorer/products.tsx b/frontend/src/pages/explorer/products.tsx
index 3daa09e6..893ee81e 100644
--- a/frontend/src/pages/explorer/products.tsx
+++ b/frontend/src/pages/explorer/products.tsx
@@ -1,10 +1,14 @@
-import { useState } from 'react'
-import { ColumnDef, PaginationState } from '@tanstack/react-table'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { ColumnDef, OnChangeFn, PaginationState, SortingState } from '@tanstack/react-table'
+import { Download } from 'lucide-react'
 import { useProducts } from '@/hooks/use-products'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
+import { DataTableColumnHeader } from '@/components/data-table/data-table-column-header'
 import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
 import { formatCurrency } from '@/lib/api'
+import { toCsv, downloadCsv, type CsvColumn } from '@/lib/csv-export'
 import type { Product } from '@/types/api'
 import { DEFAULT_PAGE_SIZE } from '@/lib/constants'
 
@@ -12,73 +16,120 @@ const columns: ColumnDef<Product>[] = [
   {
     accessorKey: 'id',
     header: 'ID',
+    enableSorting: false,
+    enableHiding: false,
     cell: ({ row }) => <span className="font-mono text-xs">{row.original.id}</span>,
   },
   {
     accessorKey: 'sku',
-    header: 'SKU',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="SKU" />,
     cell: ({ row }) => <span className="font-medium">{row.original.sku}</span>,
   },
   {
     accessorKey: 'name',
-    header: 'Name',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
   },
   {
     accessorKey: 'category',
-    header: 'Category',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Category" />,
     cell: ({ row }) => row.original.category ?? '-',
   },
   {
     accessorKey: 'brand',
-    header: 'Brand',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Brand" />,
     cell: ({ row }) => row.original.brand ?? '-',
   },
   {
     accessorKey: 'base_price',
-    header: 'Base Price',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Base Price" />,
     cell: ({ row }) => formatCurrency(row.original.base_price),
   },
 ]
 
+const csvColumns: CsvColumn<Product>[] = [
+  { key: 'id', header: 'ID' },
+  { key: 'sku', header: 'SKU' },
+  { key: 'name', header: 'Name' },
+  { key: 'category', header: 'Category' },
+  { key: 'brand', header: 'Brand' },
+  { key: 'base_price', header: 'Base Price' },
+]
+
 export default function ProductsExplorerPage() {
-  const [pagination, setPagination] = useState<PaginationState>({
-    pageIndex: 0,
+  const navigate = useNavigate()
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // URL query string is the single source of truth for filter/sort/page state.
+  const search = searchParams.get('search') ?? ''
+  const category = searchParams.get('category') ?? undefined
+  const page = Number(searchParams.get('page')) || 1
+  const sortBy = searchParams.get('sort_by') ?? undefined
+  const sortOrder: 'asc' | 'desc' = searchParams.get('sort_order') === 'desc' ? 'desc' : 'asc'
+
+  const pagination: PaginationState = {
+    pageIndex: page - 1,
     pageSize: DEFAULT_PAGE_SIZE,
-  })
-  const [search, setSearch] = useState('')
-  const [filters, setFilters] = useState<Record<string, string | undefined>>({})
+  }
+  const sorting: SortingState = sortBy ? [{ id: sortBy, desc: sortOrder === 'desc' }] : []
 
   const { data, isLoading, error, refetch } = useProducts({
-    page: pagination.pageIndex + 1,
+    page,
     pageSize: pagination.pageSize,
     search: search.length >= 2 ? search : undefined,
-    category: filters.category,
-    brand: filters.brand,
+    category,
+    sortBy,
+    sortOrder: sortBy ? sortOrder : undefined,
   })
 
-  const handleFilterChange = (key: string, value: string | undefined) => {
-    setFilters((prev) => ({ ...prev, [key]: value }))
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+  function updateParams(updates: Record<string, string | undefined>) {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev)
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined || value === '') next.delete(key)
+        else next.set(key, value)
+      }
+      return next
+    })
+  }
+
+  const handlePaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(pagination) : updater
+    updateParams({ page: String(next.pageIndex + 1) })
+  }
+
+  const handleSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(sorting) : updater
+    const first = next[0]
+    updateParams({
+      sort_by: first?.id,
+      sort_order: first ? (first.desc ? 'desc' : 'asc') : undefined,
+      page: '1',
+    })
   }
 
   const handleSearchChange = (value: string) => {
-    setSearch(value)
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+    updateParams({ search: value || undefined, page: '1' })
+  }
+
+  const handleFilterChange = (key: string, value: string | undefined) => {
+    updateParams({ [key]: value, page: '1' })
   }
 
   const handleReset = () => {
-    setSearch('')
-    setFilters({})
-    setPagination({ pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE })
+    setSearchParams(new URLSearchParams())
   }
 
-  const hasActiveFilters = !!search || Object.values(filters).some(Boolean)
+  const handleExport = () => {
+    downloadCsv('products.csv', toCsv(data?.products ?? [], csvColumns))
+  }
+
+  const hasActiveFilters = !!search || !!category || !!sortBy
 
   if (error) {
     return (
       <div className="space-y-6">
         <h1 className="text-3xl font-bold">Products</h1>
-        <ErrorDisplay error={error} onRetry={refetch} />
+        <ErrorDisplay error={error} onRetry={() => void refetch()} />
       </div>
     )
   }
@@ -89,34 +140,44 @@ export default function ProductsExplorerPage() {
     <div className="space-y-6">
       <h1 className="text-3xl font-bold">Products</h1>
 
-      <DataTableToolbar
-        searchValue={search}
-        onSearchChange={handleSearchChange}
-        searchPlaceholder="Search by SKU or name..."
-        filters={[
-          {
-            key: 'category',
-            label: 'Category',
-            options: [
-              { label: 'Beverage', value: 'Beverage' },
-              { label: 'Snacks', value: 'Snacks' },
-              { label: 'Dairy', value: 'Dairy' },
-              { label: 'Grocery', value: 'Grocery' },
-            ],
-          },
-        ]}
-        filterValues={filters}
-        onFilterChange={handleFilterChange}
-        onReset={handleReset}
-        hasActiveFilters={hasActiveFilters}
-      />
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <DataTableToolbar
+          searchValue={search}
+          onSearchChange={handleSearchChange}
+          searchPlaceholder="Search by SKU or name..."
+          filters={[
+            {
+              key: 'category',
+              label: 'Category',
+              options: [
+                { label: 'Beverage', value: 'Beverage' },
+                { label: 'Snacks', value: 'Snacks' },
+                { label: 'Dairy', value: 'Dairy' },
+                { label: 'Grocery', value: 'Grocery' },
+              ],
+            },
+          ]}
+          filterValues={{ category }}
+          onFilterChange={handleFilterChange}
+          onReset={handleReset}
+          hasActiveFilters={hasActiveFilters}
+        />
+        <Button variant="outline" size="sm" className="h-8" onClick={handleExport}>
+          <Download className="mr-2 h-4 w-4" />
+          Export CSV
+        </Button>
+      </div>
 
       <DataTable
         columns={columns}
         data={data?.products ?? []}
         pageCount={pageCount}
         pagination={pagination}
-        onPaginationChange={setPagination}
+        onPaginationChange={handlePaginationChange}
+        sorting={sorting}
+        onSortingChange={handleSortingChange}
+        onRowClick={(product) => navigate(`/explorer/products/${product.id}`)}
+        enableColumnVisibility
         isLoading={isLoading}
         emptyMessage="No products found."
       />
diff --git a/frontend/src/pages/explorer/run-compare.tsx b/frontend/src/pages/explorer/run-compare.tsx
new file mode 100644
index 00000000..3aff8672
--- /dev/null
+++ b/frontend/src/pages/explorer/run-compare.tsx
@@ -0,0 +1,271 @@
+import { Link, useSearchParams } from 'react-router-dom'
+import { format } from 'date-fns'
+import { ArrowDown, ArrowLeft, ArrowUp } from 'lucide-react'
+import { useRuns, useCompareRuns } from '@/hooks/use-runs'
+import { JsonBlock } from '@/components/common/json-block'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { LoadingState } from '@/components/common/loading-state'
+import { StatusBadge } from '@/components/common/status-badge'
+import { getStatusVariant } from '@/lib/status-utils'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
+import { formatNumber } from '@/lib/api'
+import { ROUTES } from '@/lib/constants'
+import type { ModelRun } from '@/types/api'
+
+function fmtDate(value: string | null | undefined): string {
+  return value ? format(new Date(value), 'MMM d, yyyy HH:mm') : '—'
+}
+
+/** Neutral delta indicator — sign only, no better/worse colour-coding. */
+function DeltaCell({ diff }: { diff: number | null }) {
+  if (diff == null) {
+    return <span className="text-muted-foreground">—</span>
+  }
+  if (diff > 0) {
+    return (
+      <span className="inline-flex items-center gap-1">
+        <ArrowUp className="h-3 w-3" />
+        {formatNumber(diff, 4)}
+      </span>
+    )
+  }
+  if (diff < 0) {
+    return (
+      <span className="inline-flex items-center gap-1">
+        <ArrowDown className="h-3 w-3" />
+        {formatNumber(diff, 4)}
+      </span>
+    )
+  }
+  return <span>{formatNumber(diff, 4)}</span>
+}
+
+function RunPicker({
+  label,
+  value,
+  runs,
+  onSelect,
+}: {
+  label: string
+  value: string
+  runs: ModelRun[]
+  onSelect: (runId: string) => void
+}) {
+  return (
+    <div className="space-y-1">
+      <span className="text-xs text-muted-foreground">{label}</span>
+      <Select value={value || undefined} onValueChange={onSelect}>
+        <SelectTrigger className="w-full">
+          <SelectValue placeholder="Select a run…" />
+        </SelectTrigger>
+        <SelectContent>
+          {runs.map((run) => (
+            <SelectItem key={run.run_id} value={run.run_id}>
+              {run.run_id.slice(0, 8)} · {run.model_type} · {run.status}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  )
+}
+
+export default function RunComparePage() {
+  const [params, setParams] = useSearchParams()
+  const a = params.get('a') ?? ''
+  const b = params.get('b') ?? ''
+
+  const runsQuery = useRuns({ page: 1, pageSize: 100 })
+  const compareQuery = useCompareRuns(a, b, !!a && !!b)
+
+  function selectRun(slot: 'a' | 'b', runId: string) {
+    setParams((prev) => {
+      const next = new URLSearchParams(prev)
+      next.set(slot, runId)
+      return next
+    })
+  }
+
+  const runs = runsQuery.data?.runs ?? []
+  const comparison = compareQuery.data
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-1">
+        <Button asChild variant="ghost" size="sm" className="-ml-2 h-7">
+          <Link to={ROUTES.EXPLORER.RUNS}>
+            <ArrowLeft className="mr-1 h-4 w-4" />
+            Back to Model Runs
+          </Link>
+        </Button>
+        <h1 className="text-3xl font-bold">Compare runs</h1>
+        <p className="text-sm text-muted-foreground">
+          Pick two model runs to compare their configuration and metrics side by side.
+        </p>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Select runs</CardTitle>
+          <CardDescription>
+            The comparison is deep-linkable — the URL carries the two run ids.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-4 sm:grid-cols-2">
+          <RunPicker label="Run A" value={a} runs={runs} onSelect={(id) => selectRun('a', id)} />
+          <RunPicker label="Run B" value={b} runs={runs} onSelect={(id) => selectRun('b', id)} />
+        </CardContent>
+      </Card>
+
+      {(!a || !b) && (
+        <Card>
+          <CardContent className="py-10 text-center text-sm text-muted-foreground">
+            Select two runs above to see the comparison.
+          </CardContent>
+        </Card>
+      )}
+
+      {a && b && compareQuery.error && (
+        <ErrorDisplay error={compareQuery.error} onRetry={() => void compareQuery.refetch()} />
+      )}
+
+      {a && b && compareQuery.isLoading && <LoadingState message="Comparing runs..." />}
+
+      {a && b && comparison && (
+        <>
+          <Card>
+            <CardHeader>
+              <CardTitle>Profile</CardTitle>
+              <CardDescription>Side-by-side registry records.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>Field</TableHead>
+                    <TableHead>Run A</TableHead>
+                    <TableHead>Run B</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  <TableRow>
+                    <TableCell className="font-medium">Run ID</TableCell>
+                    <TableCell className="break-all font-mono text-xs">
+                      {comparison.run_a.run_id}
+                    </TableCell>
+                    <TableCell className="break-all font-mono text-xs">
+                      {comparison.run_b.run_id}
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell className="font-medium">Model type</TableCell>
+                    <TableCell>{comparison.run_a.model_type}</TableCell>
+                    <TableCell>{comparison.run_b.model_type}</TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell className="font-medium">Status</TableCell>
+                    <TableCell>
+                      <StatusBadge variant={getStatusVariant(comparison.run_a.status)}>
+                        {comparison.run_a.status}
+                      </StatusBadge>
+                    </TableCell>
+                    <TableCell>
+                      <StatusBadge variant={getStatusVariant(comparison.run_b.status)}>
+                        {comparison.run_b.status}
+                      </StatusBadge>
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell className="font-medium">Data window</TableCell>
+                    <TableCell className="text-xs">
+                      {comparison.run_a.data_window_start} → {comparison.run_a.data_window_end}
+                    </TableCell>
+                    <TableCell className="text-xs">
+                      {comparison.run_b.data_window_start} → {comparison.run_b.data_window_end}
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell className="font-medium">Config hash</TableCell>
+                    <TableCell className="break-all font-mono text-xs">
+                      {comparison.run_a.config_hash}
+                    </TableCell>
+                    <TableCell className="break-all font-mono text-xs">
+                      {comparison.run_b.config_hash}
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell className="font-medium">Created</TableCell>
+                    <TableCell className="text-xs">{fmtDate(comparison.run_a.created_at)}</TableCell>
+                    <TableCell className="text-xs">{fmtDate(comparison.run_b.created_at)}</TableCell>
+                  </TableRow>
+                </TableBody>
+              </Table>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Config diff</CardTitle>
+              <CardDescription>Keys whose values differ between the two runs.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              {Object.keys(comparison.config_diff).length === 0 ? (
+                <p className="text-sm text-muted-foreground">
+                  The two runs share an identical configuration.
+                </p>
+              ) : (
+                <JsonBlock value={comparison.config_diff} />
+              )}
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Metrics diff</CardTitle>
+              <CardDescription>
+                Δ is Run B minus Run A — sign only, not a quality judgement.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              {Object.keys(comparison.metrics_diff).length === 0 ? (
+                <p className="text-sm text-muted-foreground">No metrics to compare.</p>
+              ) : (
+                <Table>
+                  <TableHeader>
+                    <TableRow>
+                      <TableHead>Metric</TableHead>
+                      <TableHead>Run A</TableHead>
+                      <TableHead>Run B</TableHead>
+                      <TableHead>Δ</TableHead>
+                    </TableRow>
+                  </TableHeader>
+                  <TableBody>
+                    {Object.entries(comparison.metrics_diff).map(([metric, m]) => (
+                      <TableRow key={metric}>
+                        <TableCell className="font-medium">{metric}</TableCell>
+                        <TableCell>{m.a != null ? formatNumber(m.a, 4) : '—'}</TableCell>
+                        <TableCell>{m.b != null ? formatNumber(m.b, 4) : '—'}</TableCell>
+                        <TableCell>
+                          <DeltaCell diff={m.diff} />
+                        </TableCell>
+                      </TableRow>
+                    ))}
+                  </TableBody>
+                </Table>
+              )}
+            </CardContent>
+          </Card>
+        </>
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/pages/explorer/run-detail.tsx b/frontend/src/pages/explorer/run-detail.tsx
new file mode 100644
index 00000000..1a41ca5e
--- /dev/null
+++ b/frontend/src/pages/explorer/run-detail.tsx
@@ -0,0 +1,272 @@
+import { useState } from 'react'
+import { Link, useParams } from 'react-router-dom'
+import { format } from 'date-fns'
+import {
+  AlertTriangle,
+  ArrowLeft,
+  CheckCircle2,
+  GitCompare,
+  Loader2,
+  ShieldCheck,
+} from 'lucide-react'
+import { useRun, useVerifyArtifact } from '@/hooks/use-runs'
+import { JsonBlock } from '@/components/common/json-block'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { LoadingState } from '@/components/common/loading-state'
+import { StatusBadge } from '@/components/common/status-badge'
+import { getStatusVariant } from '@/lib/status-utils'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { formatNumber, getErrorMessage } from '@/lib/api'
+import { ROUTES } from '@/lib/constants'
+
+function fmtDate(value: string | null | undefined): string {
+  return value ? format(new Date(value), 'MMM d, yyyy HH:mm') : '—'
+}
+
+function Field({ label, value, mono = false }: { label: string; value: string; mono?: boolean }) {
+  return (
+    <div>
+      <dt className="text-xs text-muted-foreground">{label}</dt>
+      <dd className={mono ? 'break-all font-mono text-sm' : 'font-medium'}>{value}</dd>
+    </div>
+  )
+}
+
+export default function RunDetailPage() {
+  const { runId } = useParams()
+  const runQuery = useRun(runId ?? '', !!runId)
+
+  // The verify GET is button-gated: disabled until the first click, then refetch.
+  const [verifyOn, setVerifyOn] = useState(false)
+  const verifyQuery = useVerifyArtifact(runId ?? '', verifyOn)
+
+  if (!runId) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Run Detail</h1>
+        <ErrorDisplay error={new Error('No run id in the URL.')} title="Invalid run" />
+      </div>
+    )
+  }
+
+  if (runQuery.error) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Run Detail</h1>
+        <ErrorDisplay error={runQuery.error} onRetry={() => void runQuery.refetch()} />
+      </div>
+    )
+  }
+
+  if (runQuery.isLoading || !runQuery.data) {
+    return <LoadingState message="Loading run..." />
+  }
+
+  const run = runQuery.data
+
+  function handleVerify() {
+    if (!verifyOn) setVerifyOn(true)
+    else void verifyQuery.refetch()
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+        <div className="space-y-1">
+          <Button asChild variant="ghost" size="sm" className="-ml-2 h-7">
+            <Link to={ROUTES.EXPLORER.RUNS}>
+              <ArrowLeft className="mr-1 h-4 w-4" />
+              Back to Model Runs
+            </Link>
+          </Button>
+          <div className="flex flex-wrap items-center gap-3">
+            <h1 className="break-all font-mono text-2xl font-bold">{run.run_id}</h1>
+            <StatusBadge variant={getStatusVariant(run.status)}>{run.status}</StatusBadge>
+          </div>
+          <p className="text-sm text-muted-foreground">{run.model_type}</p>
+        </div>
+        <Button asChild variant="outline">
+          <Link to={`${ROUTES.EXPLORER.RUN_COMPARE}?a=${run.run_id}`}>
+            <GitCompare className="mr-2 h-4 w-4" />
+            Compare with…
+          </Link>
+        </Button>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Run profile</CardTitle>
+          <CardDescription>Registry record for this model run.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <dl className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
+            <Field label="Model type" value={run.model_type} />
+            <div>
+              <dt className="text-xs text-muted-foreground">Store</dt>
+              <dd className="font-medium">
+                <Link
+                  className="text-primary hover:underline"
+                  to={`/explorer/stores/${run.store_id}`}
+                >
+                  #{run.store_id}
+                </Link>
+              </dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Product</dt>
+              <dd className="font-medium">
+                <Link
+                  className="text-primary hover:underline"
+                  to={`/explorer/products/${run.product_id}`}
+                >
+                  #{run.product_id}
+                </Link>
+              </dd>
+            </div>
+            <Field
+              label="Data window"
+              value={`${run.data_window_start} → ${run.data_window_end}`}
+            />
+            <Field label="Config hash" value={run.config_hash} mono />
+            <Field label="Git SHA" value={run.git_sha ?? '—'} mono />
+            <Field label="Created" value={fmtDate(run.created_at)} />
+            <Field label="Started" value={fmtDate(run.started_at)} />
+            <Field label="Completed" value={fmtDate(run.completed_at)} />
+          </dl>
+        </CardContent>
+      </Card>
+
+      {run.status === 'failed' && run.error_message && (
+        <Card className="border-destructive/50">
+          <CardHeader>
+            <CardTitle className="text-destructive">Error</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-sm text-destructive/90">{run.error_message}</p>
+          </CardContent>
+        </Card>
+      )}
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Metrics</CardTitle>
+          <CardDescription>Evaluation metrics recorded for this run.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <JsonBlock value={run.metrics} />
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-6 lg:grid-cols-2">
+        <Card>
+          <CardHeader>
+            <CardTitle>Model config</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <JsonBlock value={run.model_config} />
+          </CardContent>
+        </Card>
+        <Card>
+          <CardHeader>
+            <CardTitle>Feature config</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <JsonBlock value={run.feature_config} />
+          </CardContent>
+        </Card>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Runtime info</CardTitle>
+          <CardDescription>Environment captured at training time.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <JsonBlock value={run.runtime_info} />
+        </CardContent>
+      </Card>
+
+      {run.agent_context && (
+        <Card>
+          <CardHeader>
+            <CardTitle>Agent context</CardTitle>
+            <CardDescription>The agent session that created this run.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <JsonBlock value={run.agent_context} />
+          </CardContent>
+        </Card>
+      )}
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Artifact</CardTitle>
+          <CardDescription>Stored model artifact and SHA-256 integrity check.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <dl className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+            <Field label="Artifact URI" value={run.artifact_uri ?? '—'} mono />
+            <Field label="Artifact hash" value={run.artifact_hash ?? '—'} mono />
+            <Field
+              label="Size"
+              value={
+                run.artifact_size_bytes != null
+                  ? `${formatNumber(run.artifact_size_bytes)} bytes`
+                  : '—'
+              }
+            />
+          </dl>
+
+          <div className="flex items-center gap-3">
+            <Button onClick={handleVerify} disabled={!run.artifact_uri || verifyQuery.isFetching}>
+              {verifyQuery.isFetching ? (
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              ) : (
+                <ShieldCheck className="mr-2 h-4 w-4" />
+              )}
+              Verify integrity
+            </Button>
+            {!run.artifact_uri && (
+              <span className="text-sm text-muted-foreground">This run has no artifact.</span>
+            )}
+          </div>
+
+          {verifyOn && !verifyQuery.isFetching && verifyQuery.error && (
+            <div className="flex items-start gap-2 rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive">
+              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+              <span>{getErrorMessage(verifyQuery.error)}</span>
+            </div>
+          )}
+
+          {verifyOn &&
+            !verifyQuery.isFetching &&
+            verifyQuery.data &&
+            (verifyQuery.data.verified ? (
+              <div className="flex items-start gap-2 rounded-md border border-green-600/40 bg-green-600/10 p-3 text-sm text-green-700 dark:text-green-400">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 shrink-0" />
+                <span>
+                  Artifact verified — the stored checksum matches.
+                  {verifyQuery.data.computed_hash && (
+                    <span className="block break-all font-mono text-xs">
+                      {verifyQuery.data.computed_hash}
+                    </span>
+                  )}
+                </span>
+              </div>
+            ) : (
+              <div className="flex items-start gap-2 rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive">
+                <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+                <span>
+                  Integrity check failed — the artifact does not match its stored hash.
+                  {verifyQuery.data.error && (
+                    <span className="block text-xs">{verifyQuery.data.error}</span>
+                  )}
+                </span>
+              </div>
+            ))}
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
diff --git a/frontend/src/pages/explorer/runs.tsx b/frontend/src/pages/explorer/runs.tsx
index 31b1c436..c6fb43fc 100644
--- a/frontend/src/pages/explorer/runs.tsx
+++ b/frontend/src/pages/explorer/runs.tsx
@@ -1,26 +1,32 @@
-import { useState } from 'react'
+import { Link, useNavigate, useSearchParams } from 'react-router-dom'
 import { format } from 'date-fns'
-import { ColumnDef, PaginationState } from '@tanstack/react-table'
+import { ColumnDef, OnChangeFn, PaginationState, SortingState } from '@tanstack/react-table'
+import { Download, GitCompare } from 'lucide-react'
 import { useRuns } from '@/hooks/use-runs'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
+import { DataTableColumnHeader } from '@/components/data-table/data-table-column-header'
 import { StatusBadge } from '@/components/common/status-badge'
 import { getStatusVariant } from '@/lib/status-utils'
 import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
+import { toCsv, downloadCsv, type CsvColumn } from '@/lib/csv-export'
 import type { ModelRun, RunStatus } from '@/types/api'
-import { DEFAULT_PAGE_SIZE } from '@/lib/constants'
+import { DEFAULT_PAGE_SIZE, ROUTES } from '@/lib/constants'
 
 const columns: ColumnDef<ModelRun>[] = [
   {
     accessorKey: 'run_id',
     header: 'Run ID',
+    enableSorting: false,
+    enableHiding: false,
     cell: ({ row }) => (
       <span className="font-mono text-xs">{row.original.run_id.substring(0, 8)}...</span>
     ),
   },
   {
     accessorKey: 'status',
-    header: 'Status',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
     cell: ({ row }) => (
       <StatusBadge variant={getStatusVariant(row.original.status)}>
         {row.original.status}
@@ -29,20 +35,21 @@ const columns: ColumnDef<ModelRun>[] = [
   },
   {
     accessorKey: 'model_type',
-    header: 'Model Type',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Model Type" />,
     cell: ({ row }) => <span className="font-medium">{row.original.model_type}</span>,
   },
   {
     accessorKey: 'store_id',
-    header: 'Store',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Store" />,
   },
   {
     accessorKey: 'product_id',
-    header: 'Product',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Product" />,
   },
   {
     accessorKey: 'data_window_start',
     header: 'Data Window',
+    enableSorting: false,
     cell: ({ row }) => (
       <span className="text-xs">
         {format(new Date(row.original.data_window_start), 'MMM d')} -{' '}
@@ -53,6 +60,7 @@ const columns: ColumnDef<ModelRun>[] = [
   {
     accessorKey: 'metrics',
     header: 'MAE',
+    enableSorting: false,
     cell: ({ row }) => {
       const mae = row.original.metrics?.mae
       return mae !== undefined ? mae.toFixed(2) : '-'
@@ -60,42 +68,95 @@ const columns: ColumnDef<ModelRun>[] = [
   },
   {
     accessorKey: 'created_at',
-    header: 'Created',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Created" />,
     cell: ({ row }) => format(new Date(row.original.created_at), 'MMM d, HH:mm'),
   },
 ]
 
+const csvColumns: CsvColumn<ModelRun>[] = [
+  { key: 'run_id', header: 'Run ID' },
+  { key: 'status', header: 'Status' },
+  { key: 'model_type', header: 'Model Type' },
+  { key: 'store_id', header: 'Store' },
+  { key: 'product_id', header: 'Product' },
+  { key: 'data_window_start', header: 'Data Window Start' },
+  { key: 'data_window_end', header: 'Data Window End' },
+  { key: 'created_at', header: 'Created' },
+]
+
 export default function RunsExplorerPage() {
-  const [pagination, setPagination] = useState<PaginationState>({
-    pageIndex: 0,
+  const navigate = useNavigate()
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // URL query string is the single source of truth for filter/sort/page state,
+  // so a pasted URL reproduces the exact view.
+  const modelType = searchParams.get('model_type') ?? undefined
+  const status = searchParams.get('status') ?? undefined
+  const page = Number(searchParams.get('page')) || 1
+  const sortBy = searchParams.get('sort_by') ?? undefined
+  const sortOrder: 'asc' | 'desc' = searchParams.get('sort_order') === 'desc' ? 'desc' : 'asc'
+
+  const pagination: PaginationState = {
+    pageIndex: page - 1,
     pageSize: DEFAULT_PAGE_SIZE,
-  })
-  const [filters, setFilters] = useState<Record<string, string | undefined>>({})
+  }
+  const sorting: SortingState = sortBy ? [{ id: sortBy, desc: sortOrder === 'desc' }] : []
 
   const { data, isLoading, error, refetch } = useRuns({
-    page: pagination.pageIndex + 1,
+    page,
     pageSize: pagination.pageSize,
-    modelType: filters.modelType,
-    status: filters.status as RunStatus | undefined,
+    modelType,
+    status: status as RunStatus | undefined,
+    sortBy,
+    sortOrder: sortBy ? sortOrder : undefined,
   })
 
+  function updateParams(updates: Record<string, string | undefined>) {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev)
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined || value === '') next.delete(key)
+        else next.set(key, value)
+      }
+      return next
+    })
+  }
+
+  const handlePaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(pagination) : updater
+    updateParams({ page: String(next.pageIndex + 1) })
+  }
+
+  const handleSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(sorting) : updater
+    const first = next[0]
+    updateParams({
+      sort_by: first?.id,
+      sort_order: first ? (first.desc ? 'desc' : 'asc') : undefined,
+      page: '1',
+    })
+  }
+
   const handleFilterChange = (key: string, value: string | undefined) => {
-    setFilters((prev) => ({ ...prev, [key]: value }))
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+    const paramKey = key === 'modelType' ? 'model_type' : key
+    updateParams({ [paramKey]: value, page: '1' })
   }
 
   const handleReset = () => {
-    setFilters({})
-    setPagination({ pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE })
+    setSearchParams(new URLSearchParams())
   }
 
-  const hasActiveFilters = Object.values(filters).some(Boolean)
+  const handleExport = () => {
+    downloadCsv('model-runs.csv', toCsv(data?.runs ?? [], csvColumns))
+  }
+
+  const hasActiveFilters = !!modelType || !!status || !!sortBy
 
   if (error) {
     return (
       <div className="space-y-6">
         <h1 className="text-3xl font-bold">Model Runs</h1>
-        <ErrorDisplay error={error} onRetry={refetch} />
+        <ErrorDisplay error={error} onRetry={() => void refetch()} />
       </div>
     )
   }
@@ -104,44 +165,62 @@ export default function RunsExplorerPage() {
 
   return (
     <div className="space-y-6">
-      <h1 className="text-3xl font-bold">Model Runs</h1>
-
-      <DataTableToolbar
-        filters={[
-          {
-            key: 'modelType',
-            label: 'Model',
-            options: [
-              { label: 'Naive', value: 'naive' },
-              { label: 'Seasonal Naive', value: 'seasonal_naive' },
-              { label: 'Moving Average', value: 'moving_average' },
-              { label: 'LightGBM', value: 'lightgbm' },
-            ],
-          },
-          {
-            key: 'status',
-            label: 'Status',
-            options: [
-              { label: 'Pending', value: 'pending' },
-              { label: 'Running', value: 'running' },
-              { label: 'Success', value: 'success' },
-              { label: 'Failed', value: 'failed' },
-              { label: 'Archived', value: 'archived' },
-            ],
-          },
-        ]}
-        filterValues={filters}
-        onFilterChange={handleFilterChange}
-        onReset={handleReset}
-        hasActiveFilters={hasActiveFilters}
-      />
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h1 className="text-3xl font-bold">Model Runs</h1>
+        <Button asChild variant="outline" size="sm" className="h-8">
+          <Link to={ROUTES.EXPLORER.RUN_COMPARE}>
+            <GitCompare className="mr-2 h-4 w-4" />
+            Compare runs
+          </Link>
+        </Button>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <DataTableToolbar
+          filters={[
+            {
+              key: 'modelType',
+              label: 'Model',
+              options: [
+                { label: 'Naive', value: 'naive' },
+                { label: 'Seasonal Naive', value: 'seasonal_naive' },
+                { label: 'Moving Average', value: 'moving_average' },
+                { label: 'LightGBM', value: 'lightgbm' },
+              ],
+            },
+            {
+              key: 'status',
+              label: 'Status',
+              options: [
+                { label: 'Pending', value: 'pending' },
+                { label: 'Running', value: 'running' },
+                { label: 'Success', value: 'success' },
+                { label: 'Failed', value: 'failed' },
+                { label: 'Archived', value: 'archived' },
+              ],
+            },
+          ]}
+          filterValues={{ modelType, status }}
+          onFilterChange={handleFilterChange}
+          onReset={handleReset}
+          hasActiveFilters={hasActiveFilters}
+        />
+        <Button variant="outline" size="sm" className="h-8" onClick={handleExport}>
+          <Download className="mr-2 h-4 w-4" />
+          Export CSV
+        </Button>
+      </div>
 
       <DataTable
         columns={columns}
         data={data?.runs ?? []}
         pageCount={pageCount}
         pagination={pagination}
-        onPaginationChange={setPagination}
+        onPaginationChange={handlePaginationChange}
+        sorting={sorting}
+        onSortingChange={handleSortingChange}
+        onRowClick={(run) => navigate(`/explorer/runs/${run.run_id}`)}
+        enableColumnVisibility
         isLoading={isLoading}
         emptyMessage="No model runs found."
       />
diff --git a/frontend/src/pages/explorer/sales.tsx b/frontend/src/pages/explorer/sales.tsx
index b2a7b9b9..ba32036b 100644
--- a/frontend/src/pages/explorer/sales.tsx
+++ b/frontend/src/pages/explorer/sales.tsx
@@ -1,54 +1,169 @@
 import { useState } from 'react'
+import { useSearchParams } from 'react-router-dom'
 import { format, subDays } from 'date-fns'
+import { X } from 'lucide-react'
 import { DateRange } from 'react-day-picker'
 import { useDrilldowns } from '@/hooks/use-drilldowns'
+import { useTimeseries } from '@/hooks/use-timeseries'
 import { DateRangePicker } from '@/components/common/date-range-picker'
-import { dateRangeToStrings } from '@/lib/date-utils'
 import { ErrorDisplay } from '@/components/common/error-display'
 import { LoadingState } from '@/components/common/loading-state'
+import { RevenueBarChart } from '@/components/charts/revenue-bar-chart'
+import { TimeSeriesChart } from '@/components/charts/time-series-chart'
+import { Badge } from '@/components/ui/badge'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { dateRangeToStrings, stringsToDateRange } from '@/lib/date-utils'
 import { formatCurrency, formatNumber } from '@/lib/api'
 import type { DrilldownDimension } from '@/types/api'
 
 export default function SalesExplorerPage() {
-  const [dateRange, setDateRange] = useState<DateRange | undefined>({
-    from: subDays(new Date(), 30),
-    to: new Date(),
-  })
-  const [dimension, setDimension] = useState<DrilldownDimension>('store')
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // dimension + cross-filter state live in the URL so the view is shareable.
+  const dimension = (searchParams.get('dimension') as DrilldownDimension | null) ?? 'store'
+  const storeIdParam = searchParams.get('store_id')
+  const productIdParam = searchParams.get('product_id')
+  const storeId = storeIdParam ? Number(storeIdParam) : undefined
+  const productId = productIdParam ? Number(productIdParam) : undefined
+
+  const startParam = searchParams.get('start_date')
+  const endParam = searchParams.get('end_date')
+  const [dateRange, setDateRange] = useState<DateRange | undefined>(() =>
+    startParam
+      ? stringsToDateRange(startParam, endParam ?? undefined)
+      : { from: subDays(new Date(), 30), to: new Date() }
+  )
 
   const { startDate, endDate } = dateRangeToStrings(dateRange)
+  const rangeReady = !!startDate && !!endDate
 
-  const { data, isLoading, error, refetch } = useDrilldowns({
+  function updateParams(updates: Record<string, string | undefined>) {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev)
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined || value === '') next.delete(key)
+        else next.set(key, value)
+      }
+      return next
+    })
+  }
+
+  const handleDateChange = (range: DateRange | undefined) => {
+    setDateRange(range)
+    const { startDate: nextStart, endDate: nextEnd } = dateRangeToStrings(range)
+    updateParams({ start_date: nextStart, end_date: nextEnd })
+  }
+
+  const drilldown = useDrilldowns({
     dimension,
     startDate: startDate ?? '',
     endDate: endDate ?? '',
+    storeId,
+    productId,
     maxItems: 20,
-    enabled: !!startDate && !!endDate,
+    enabled: rangeReady,
+  })
+
+  const timeseries = useTimeseries({
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    granularity: 'day',
+    storeId,
+    productId,
+    enabled: rangeReady,
   })
 
-  if (error) {
+  if (drilldown.error) {
     return (
       <div className="space-y-6">
         <h1 className="text-3xl font-bold">Sales Explorer</h1>
-        <ErrorDisplay error={error} onRetry={refetch} />
+        <ErrorDisplay error={drilldown.error} onRetry={() => void drilldown.refetch()} />
       </div>
     )
   }
 
+  const items = drilldown.data?.items ?? []
+  const points = timeseries.data?.points ?? []
+  const dimensionLabel = dimension.charAt(0).toUpperCase() + dimension.slice(1)
+
   return (
     <div className="space-y-6">
       <div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
         <h1 className="text-3xl font-bold">Sales Explorer</h1>
-        <DateRangePicker
-          value={dateRange}
-          onChange={setDateRange}
-          placeholder="Select date range"
-        />
+        <DateRangePicker value={dateRange} onChange={handleDateChange} />
+      </div>
+
+      {(storeId !== undefined || productId !== undefined) && (
+        <div className="flex flex-wrap gap-2">
+          {storeId !== undefined && (
+            <Badge variant="secondary" className="gap-1">
+              Filtered to store #{storeId}
+              <button
+                type="button"
+                aria-label="Clear store filter"
+                onClick={() => updateParams({ store_id: undefined })}
+                className="ml-1 rounded-full hover:text-foreground"
+              >
+                <X className="h-3 w-3" />
+              </button>
+            </Badge>
+          )}
+          {productId !== undefined && (
+            <Badge variant="secondary" className="gap-1">
+              Filtered to product #{productId}
+              <button
+                type="button"
+                aria-label="Clear product filter"
+                onClick={() => updateParams({ product_id: undefined })}
+                className="ml-1 rounded-full hover:text-foreground"
+              >
+                <X className="h-3 w-3" />
+              </button>
+            </Badge>
+          )}
+        </div>
+      )}
+
+      <div className="grid gap-4 lg:grid-cols-2">
+        {items.length > 0 ? (
+          <RevenueBarChart
+            title={`Revenue by ${dimensionLabel}`}
+            description="Top contributors for the selected period."
+            data={items.map((item) => ({
+              label: item.dimension_value,
+              revenue: Number(item.metrics.total_revenue),
+            }))}
+          />
+        ) : (
+          <Card>
+            <CardHeader>
+              <CardTitle>Revenue by {dimensionLabel}</CardTitle>
+              <CardDescription>No sales data for the selected period.</CardDescription>
+            </CardHeader>
+          </Card>
+        )}
+        {points.length > 0 ? (
+          <TimeSeriesChart
+            title="Revenue over time"
+            description="Daily revenue for the selected period."
+            data={points.map((p) => ({
+              date: p.period,
+              actual: Number(p.metrics.total_revenue),
+            }))}
+            showPredicted={false}
+          />
+        ) : (
+          <Card>
+            <CardHeader>
+              <CardTitle>Revenue over time</CardTitle>
+              <CardDescription>No sales data for the selected period.</CardDescription>
+            </CardHeader>
+          </Card>
+        )}
       </div>
 
-      <Tabs value={dimension} onValueChange={(v) => setDimension(v as DrilldownDimension)}>
+      <Tabs value={dimension} onValueChange={(v) => updateParams({ dimension: v })}>
         <TabsList>
           <TabsTrigger value="store">By Store</TabsTrigger>
           <TabsTrigger value="product">By Product</TabsTrigger>
@@ -58,22 +173,22 @@ export default function SalesExplorerPage() {
         </TabsList>
 
         <TabsContent value={dimension} className="mt-6">
-          {isLoading ? (
+          {drilldown.isLoading ? (
             <LoadingState message="Loading sales data..." />
           ) : (
             <Card>
               <CardHeader>
-                <CardTitle>Sales by {dimension.charAt(0).toUpperCase() + dimension.slice(1)}</CardTitle>
+                <CardTitle>Sales by {dimensionLabel}</CardTitle>
                 <CardDescription>
-                  {data?.total_items ?? 0} items found for{' '}
+                  {drilldown.data?.total_items ?? 0} items found for{' '}
                   {startDate && format(new Date(startDate), 'MMM d, yyyy')} -{' '}
                   {endDate && format(new Date(endDate), 'MMM d, yyyy')}
                 </CardDescription>
               </CardHeader>
               <CardContent>
-                {data?.items.length ? (
+                {items.length ? (
                   <div className="space-y-3">
-                    {data.items.map((item, idx) => (
+                    {items.map((item, idx) => (
                       <div
                         key={idx}
                         className="flex items-center justify-between py-2 border-b last:border-0"
diff --git a/frontend/src/pages/explorer/store-detail.tsx b/frontend/src/pages/explorer/store-detail.tsx
new file mode 100644
index 00000000..24f950d2
--- /dev/null
+++ b/frontend/src/pages/explorer/store-detail.tsx
@@ -0,0 +1,200 @@
+import { useState } from 'react'
+import { Link, useParams } from 'react-router-dom'
+import { subDays } from 'date-fns'
+import { ArrowLeft, DollarSign, ShoppingCart, TrendingUp, Users } from 'lucide-react'
+import { DateRange } from 'react-day-picker'
+import { useStore } from '@/hooks/use-stores'
+import { useKPIs } from '@/hooks/use-kpis'
+import { useTimeseries } from '@/hooks/use-timeseries'
+import { useDrilldowns } from '@/hooks/use-drilldowns'
+import { KPICard } from '@/components/charts/kpi-card'
+import { TimeSeriesChart } from '@/components/charts/time-series-chart'
+import { RevenueBarChart } from '@/components/charts/revenue-bar-chart'
+import { DateRangePicker } from '@/components/common/date-range-picker'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { dateRangeToStrings } from '@/lib/date-utils'
+import { formatCurrency, formatNumber } from '@/lib/api'
+import { ROUTES } from '@/lib/constants'
+
+export default function StoreDetailPage() {
+  const { storeId } = useParams()
+  const id = Number(storeId)
+  const validId = !Number.isNaN(id) && id > 0
+
+  const [dateRange, setDateRange] = useState<DateRange | undefined>({
+    from: subDays(new Date(), 30),
+    to: new Date(),
+  })
+  const { startDate, endDate } = dateRangeToStrings(dateRange)
+  const rangeReady = !!startDate && !!endDate
+
+  const storeQuery = useStore(id, validId)
+  const kpiQuery = useKPIs({
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    storeId: id,
+    enabled: validId && rangeReady,
+  })
+  const timeseriesQuery = useTimeseries({
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    granularity: 'day',
+    storeId: id,
+    enabled: validId && rangeReady,
+  })
+  const topProductsQuery = useDrilldowns({
+    dimension: 'product',
+    startDate: startDate ?? '',
+    endDate: endDate ?? '',
+    storeId: id,
+    maxItems: 10,
+    enabled: validId && rangeReady,
+  })
+
+  if (!validId) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Store Detail</h1>
+        <ErrorDisplay
+          error={new Error(`"${storeId}" is not a valid store id.`)}
+          title="Invalid store"
+        />
+      </div>
+    )
+  }
+
+  if (storeQuery.error) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-3xl font-bold">Store Detail</h1>
+        <ErrorDisplay error={storeQuery.error} onRetry={() => void storeQuery.refetch()} />
+      </div>
+    )
+  }
+
+  const store = storeQuery.data
+  const metrics = kpiQuery.data?.metrics
+  const points = timeseriesQuery.data?.points ?? []
+  const topProducts = topProductsQuery.data?.items ?? []
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+        <div className="space-y-1">
+          <Button asChild variant="ghost" size="sm" className="-ml-2 h-7">
+            <Link to={ROUTES.EXPLORER.STORES}>
+              <ArrowLeft className="mr-1 h-4 w-4" />
+              Back to Stores
+            </Link>
+          </Button>
+          <h1 className="text-3xl font-bold">{store?.name ?? 'Store'}</h1>
+          {store && (
+            <p className="text-sm text-muted-foreground">
+              {store.code}
+              {store.region ? ` · ${store.region}` : ''}
+            </p>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          <DateRangePicker value={dateRange} onChange={setDateRange} />
+          <Button asChild variant="outline">
+            <Link to={`${ROUTES.EXPLORER.SALES}?store_id=${id}`}>View in Sales</Link>
+          </Button>
+        </div>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Store profile</CardTitle>
+          <CardDescription>Dimension record for this store.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <dl className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+            <div>
+              <dt className="text-xs text-muted-foreground">Code</dt>
+              <dd className="font-medium">{store?.code ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Region</dt>
+              <dd className="font-medium">{store?.region ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">City</dt>
+              <dd className="font-medium">{store?.city ?? '-'}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">Type</dt>
+              <dd className="font-medium">{store?.store_type ?? '-'}</dd>
+            </div>
+          </dl>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+        <KPICard
+          title="Total Revenue"
+          value={formatCurrency(metrics?.total_revenue)}
+          icon={DollarSign}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Units Sold"
+          value={formatNumber(metrics?.total_units)}
+          icon={ShoppingCart}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Transactions"
+          value={formatNumber(metrics?.total_transactions)}
+          icon={TrendingUp}
+          isLoading={kpiQuery.isLoading}
+        />
+        <KPICard
+          title="Avg Basket Value"
+          value={formatCurrency(metrics?.avg_basket_value)}
+          icon={Users}
+          isLoading={kpiQuery.isLoading}
+        />
+      </div>
+
+      {points.length > 0 ? (
+        <TimeSeriesChart
+          title="Revenue over time"
+          description="Daily revenue for the selected period."
+          data={points.map((p) => ({
+            date: p.period,
+            actual: Number(p.metrics.total_revenue),
+          }))}
+          showPredicted={false}
+        />
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Revenue over time</CardTitle>
+            <CardDescription>No sales in the selected period.</CardDescription>
+          </CardHeader>
+        </Card>
+      )}
+
+      {topProducts.length > 0 ? (
+        <RevenueBarChart
+          title="Top products"
+          description="Highest-revenue products sold at this store."
+          data={topProducts.map((item) => ({
+            label: item.dimension_value,
+            revenue: Number(item.metrics.total_revenue),
+          }))}
+        />
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Top products</CardTitle>
+            <CardDescription>No product sales in the selected period.</CardDescription>
+          </CardHeader>
+        </Card>
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/pages/explorer/stores.tsx b/frontend/src/pages/explorer/stores.tsx
index 36f19d35..99914107 100644
--- a/frontend/src/pages/explorer/stores.tsx
+++ b/frontend/src/pages/explorer/stores.tsx
@@ -1,9 +1,13 @@
-import { useState } from 'react'
-import { ColumnDef, PaginationState } from '@tanstack/react-table'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { ColumnDef, OnChangeFn, PaginationState, SortingState } from '@tanstack/react-table'
+import { Download } from 'lucide-react'
 import { useStores } from '@/hooks/use-stores'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
+import { DataTableColumnHeader } from '@/components/data-table/data-table-column-header'
 import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
+import { toCsv, downloadCsv, type CsvColumn } from '@/lib/csv-export'
 import type { Store } from '@/types/api'
 import { DEFAULT_PAGE_SIZE } from '@/lib/constants'
 
@@ -11,74 +15,124 @@ const columns: ColumnDef<Store>[] = [
   {
     accessorKey: 'id',
     header: 'ID',
+    enableSorting: false,
+    enableHiding: false,
     cell: ({ row }) => <span className="font-mono text-xs">{row.original.id}</span>,
   },
   {
     accessorKey: 'code',
-    header: 'Code',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Code" />,
     cell: ({ row }) => <span className="font-medium">{row.original.code}</span>,
   },
   {
     accessorKey: 'name',
-    header: 'Name',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
   },
   {
     accessorKey: 'region',
-    header: 'Region',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Region" />,
     cell: ({ row }) => row.original.region ?? '-',
   },
   {
     accessorKey: 'city',
-    header: 'City',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="City" />,
     cell: ({ row }) => row.original.city ?? '-',
   },
   {
     accessorKey: 'store_type',
-    header: 'Type',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Type" />,
     cell: ({ row }) => row.original.store_type ?? '-',
   },
 ]
 
+const csvColumns: CsvColumn<Store>[] = [
+  { key: 'id', header: 'ID' },
+  { key: 'code', header: 'Code' },
+  { key: 'name', header: 'Name' },
+  { key: 'region', header: 'Region' },
+  { key: 'city', header: 'City' },
+  { key: 'store_type', header: 'Type' },
+]
+
 export default function StoresExplorerPage() {
-  const [pagination, setPagination] = useState<PaginationState>({
-    pageIndex: 0,
+  const navigate = useNavigate()
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // URL query string is the single source of truth for filter/sort/page state,
+  // so a pasted URL reproduces the exact view.
+  const search = searchParams.get('search') ?? ''
+  const region = searchParams.get('region') ?? undefined
+  const storeType = searchParams.get('store_type') ?? undefined
+  const page = Number(searchParams.get('page')) || 1
+  const sortBy = searchParams.get('sort_by') ?? undefined
+  const sortOrder: 'asc' | 'desc' = searchParams.get('sort_order') === 'desc' ? 'desc' : 'asc'
+
+  const pagination: PaginationState = {
+    pageIndex: page - 1,
     pageSize: DEFAULT_PAGE_SIZE,
-  })
-  const [search, setSearch] = useState('')
-  const [filters, setFilters] = useState<Record<string, string | undefined>>({})
+  }
+  const sorting: SortingState = sortBy ? [{ id: sortBy, desc: sortOrder === 'desc' }] : []
 
-  // Convert 0-indexed pageIndex to 1-indexed page for API
   const { data, isLoading, error, refetch } = useStores({
-    page: pagination.pageIndex + 1,
+    page,
     pageSize: pagination.pageSize,
     search: search.length >= 2 ? search : undefined,
-    region: filters.region,
-    storeType: filters.storeType,
+    region,
+    storeType,
+    sortBy,
+    sortOrder: sortBy ? sortOrder : undefined,
   })
 
-  const handleFilterChange = (key: string, value: string | undefined) => {
-    setFilters((prev) => ({ ...prev, [key]: value }))
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+  function updateParams(updates: Record<string, string | undefined>) {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev)
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined || value === '') next.delete(key)
+        else next.set(key, value)
+      }
+      return next
+    })
+  }
+
+  const handlePaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(pagination) : updater
+    updateParams({ page: String(next.pageIndex + 1) })
+  }
+
+  const handleSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const next = typeof updater === 'function' ? updater(sorting) : updater
+    const first = next[0]
+    updateParams({
+      sort_by: first?.id,
+      sort_order: first ? (first.desc ? 'desc' : 'asc') : undefined,
+      page: '1',
+    })
   }
 
   const handleSearchChange = (value: string) => {
-    setSearch(value)
-    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+    updateParams({ search: value || undefined, page: '1' })
+  }
+
+  const handleFilterChange = (key: string, value: string | undefined) => {
+    const paramKey = key === 'storeType' ? 'store_type' : key
+    updateParams({ [paramKey]: value, page: '1' })
   }
 
   const handleReset = () => {
-    setSearch('')
-    setFilters({})
-    setPagination({ pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE })
+    setSearchParams(new URLSearchParams())
   }
 
-  const hasActiveFilters = !!search || Object.values(filters).some(Boolean)
+  const handleExport = () => {
+    downloadCsv('stores.csv', toCsv(data?.stores ?? [], csvColumns))
+  }
+
+  const hasActiveFilters = !!search || !!region || !!storeType || !!sortBy
 
   if (error) {
     return (
       <div className="space-y-6">
         <h1 className="text-3xl font-bold">Stores</h1>
-        <ErrorDisplay error={error} onRetry={refetch} />
+        <ErrorDisplay error={error} onRetry={() => void refetch()} />
       </div>
     )
   }
@@ -89,43 +143,53 @@ export default function StoresExplorerPage() {
     <div className="space-y-6">
       <h1 className="text-3xl font-bold">Stores</h1>
 
-      <DataTableToolbar
-        searchValue={search}
-        onSearchChange={handleSearchChange}
-        searchPlaceholder="Search by code or name..."
-        filters={[
-          {
-            key: 'region',
-            label: 'Region',
-            options: [
-              { label: 'North', value: 'North' },
-              { label: 'South', value: 'South' },
-              { label: 'East', value: 'East' },
-              { label: 'West', value: 'West' },
-            ],
-          },
-          {
-            key: 'storeType',
-            label: 'Type',
-            options: [
-              { label: 'Supermarket', value: 'Supermarket' },
-              { label: 'Convenience', value: 'Convenience' },
-              { label: 'Hypermarket', value: 'Hypermarket' },
-            ],
-          },
-        ]}
-        filterValues={filters}
-        onFilterChange={handleFilterChange}
-        onReset={handleReset}
-        hasActiveFilters={hasActiveFilters}
-      />
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <DataTableToolbar
+          searchValue={search}
+          onSearchChange={handleSearchChange}
+          searchPlaceholder="Search by code or name..."
+          filters={[
+            {
+              key: 'region',
+              label: 'Region',
+              options: [
+                { label: 'North', value: 'North' },
+                { label: 'South', value: 'South' },
+                { label: 'East', value: 'East' },
+                { label: 'West', value: 'West' },
+              ],
+            },
+            {
+              key: 'storeType',
+              label: 'Type',
+              options: [
+                { label: 'Supermarket', value: 'Supermarket' },
+                { label: 'Convenience', value: 'Convenience' },
+                { label: 'Hypermarket', value: 'Hypermarket' },
+              ],
+            },
+          ]}
+          filterValues={{ region, storeType }}
+          onFilterChange={handleFilterChange}
+          onReset={handleReset}
+          hasActiveFilters={hasActiveFilters}
+        />
+        <Button variant="outline" size="sm" className="h-8" onClick={handleExport}>
+          <Download className="mr-2 h-4 w-4" />
+          Export CSV
+        </Button>
+      </div>
 
       <DataTable
         columns={columns}
         data={data?.stores ?? []}
         pageCount={pageCount}
         pagination={pagination}
-        onPaginationChange={setPagination}
+        onPaginationChange={handlePaginationChange}
+        sorting={sorting}
+        onSortingChange={handleSortingChange}
+        onRowClick={(store) => navigate(`/explorer/stores/${store.id}`)}
+        enableColumnVisibility
         isLoading={isLoading}
         emptyMessage="No stores found."
       />
diff --git a/frontend/src/pages/guide.tsx b/frontend/src/pages/guide.tsx
new file mode 100644
index 00000000..787a24e8
--- /dev/null
+++ b/frontend/src/pages/guide.tsx
@@ -0,0 +1,362 @@
+import { Link } from 'react-router-dom'
+import {
+  Bot,
+  Search,
+  FlaskConical,
+  ShieldCheck,
+  Workflow,
+  Gauge,
+  MessageSquare,
+  ArrowRight,
+  Settings,
+  AlertTriangle,
+} from 'lucide-react'
+import { useAIConfig } from '@/hooks/use-config'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { Skeleton } from '@/components/ui/skeleton'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { ROUTES } from '@/lib/constants'
+
+// Tool inventories — kept verbatim in sync with the agent definitions
+// (app/features/agents/agents/experiment.py + rag_assistant.py). The
+// `approval` flag mirrors agent_require_approval (create_alias / archive_run).
+interface ToolInfo {
+  name: string
+  desc: string
+  approval?: boolean
+}
+
+const RAG_TOOLS: ToolInfo[] = [
+  { name: 'tool_retrieve_context', desc: 'Semantic search over the indexed knowledge base.' },
+  { name: 'tool_list_sources', desc: 'List indexed sources and chunk counts.' },
+  { name: 'tool_format_citations', desc: 'Turn retrieval results into stable citations.' },
+  { name: 'tool_check_evidence', desc: 'Decide whether the evidence is sufficient to answer.' },
+]
+
+const EXPERIMENT_TOOLS: ToolInfo[] = [
+  { name: 'tool_list_runs', desc: 'Browse existing model runs in the registry.' },
+  { name: 'tool_get_run', desc: 'Fetch the full detail of one model run.' },
+  { name: 'tool_run_backtest', desc: 'Run a time-series backtest for a store / product.' },
+  {
+    name: 'tool_compare_backtest_results',
+    desc: 'Compare two backtest results and recommend a winner.',
+  },
+  { name: 'tool_compare_runs', desc: 'Diff two registered runs (config + metrics).' },
+  { name: 'tool_create_alias', desc: 'Promote a successful run to a deployment alias.', approval: true },
+  { name: 'tool_archive_run', desc: 'Archive a model run.', approval: true },
+]
+
+const SESSION_STEPS = [
+  'Open Chat, pick an agent type, and click "Start Session".',
+  'Type a message and send it.',
+  'Watch the reply stream token-by-token; tool calls appear as chips (start → end).',
+  'If the agent proposes a guarded action, an approval prompt appears — approve or reject it.',
+  '"New Session" starts a fresh conversation with a clean history.',
+]
+
+const RAG_PROMPTS = [
+  'What forecasting models does ForecastLabAI support?',
+  'How does backtesting prevent data leakage?',
+  'What is in your knowledge base?',
+]
+
+const EXPERIMENT_PROMPTS = [
+  'Backtest a seasonal_naive model for store 1 product 1 over the last 90 days and compare it to the naive baseline.',
+  'List the most recent model runs and tell me which has the lowest WAPE.',
+]
+
+export default function GuidePage() {
+  const { data: config, isLoading: configLoading } = useAIConfig()
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div>
+        <h1 className="text-3xl font-bold">Agent Guide</h1>
+        <p className="mt-1 text-muted-foreground">How to use the Chat agents.</p>
+      </div>
+
+      {/* Live model callout */}
+      {config && (
+        <div className="flex flex-wrap items-center gap-2 rounded-lg border bg-muted/40 px-4 py-3 text-sm">
+          <Bot className="h-4 w-4 text-muted-foreground" />
+          <span>
+            Agents currently run on{' '}
+            <span className="font-mono font-semibold">{config.agent_default_model}</span>.
+          </span>
+          <Link
+            to={ROUTES.ADMIN}
+            className="inline-flex items-center text-muted-foreground underline underline-offset-2"
+          >
+            <Settings className="mr-1 h-3 w-3" />
+            Manage in Admin → AI Models
+          </Link>
+        </div>
+      )}
+
+      {/* The two agents */}
+      <div className="grid gap-6 md:grid-cols-2">
+        <AgentCard
+          icon={Search}
+          title="RAG Assistant"
+          agentId="rag_assistant"
+          purpose="Evidence-grounded Q&A over the knowledge base. It answers only from retrieved
+            evidence, cites sources as source_path:chunk_id, and says 'I don't have enough
+            information' when coverage is missing."
+          tools={RAG_TOOLS}
+          footer={
+            <Link
+              to={ROUTES.KNOWLEDGE}
+              className="inline-flex items-center text-sm text-muted-foreground underline underline-offset-2"
+            >
+              See what it can answer from → Knowledge
+              <ArrowRight className="ml-1 h-3 w-3" />
+            </Link>
+          }
+        />
+        <AgentCard
+          icon={FlaskConical}
+          title="Experiment Agent"
+          agentId="experiment"
+          purpose="Plans and runs backtests, compares model performance against baselines, and
+            recommends — or, with approval, deploys — a winning model."
+          tools={EXPERIMENT_TOOLS}
+          footer={
+            <Link
+              to={ROUTES.EXPLORER.RUNS}
+              className="inline-flex items-center text-sm text-muted-foreground underline underline-offset-2"
+            >
+              See the runs it acts on → Model Runs
+              <ArrowRight className="ml-1 h-3 w-3" />
+            </Link>
+          }
+        />
+      </div>
+
+      {/* How a chat session works */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <Workflow className="h-5 w-5 text-muted-foreground" />
+            <CardTitle>How a chat session works</CardTitle>
+          </div>
+          <CardDescription>
+            Each session is one conversation. Replies stream over a WebSocket — text arrives as{' '}
+            <code className="rounded bg-muted px-1 py-0.5 text-xs">text_delta</code> events and tool
+            calls as <code className="rounded bg-muted px-1 py-0.5 text-xs">tool_call_start</code> /{' '}
+            <code className="rounded bg-muted px-1 py-0.5 text-xs">tool_call_end</code> events.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <ol className="space-y-2">
+            {SESSION_STEPS.map((step, i) => (
+              <li key={i} className="flex gap-3 text-sm">
+                <span className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-primary text-xs font-semibold text-primary-foreground">
+                  {i + 1}
+                </span>
+                <span>{step}</span>
+              </li>
+            ))}
+          </ol>
+        </CardContent>
+      </Card>
+
+      {/* Human-in-the-loop approval */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <ShieldCheck className="h-5 w-5 text-muted-foreground" />
+            <CardTitle>Human-in-the-loop approval</CardTitle>
+          </div>
+          <CardDescription>
+            Tools that change registry state never run unattended.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-3 text-sm">
+          <p>
+            When an agent calls a guarded tool, the run pauses and the Chat page shows an approval
+            prompt. The action only proceeds once you approve it; rejecting it returns control to
+            the agent. This keeps every mutation of the model registry under human control.
+          </p>
+          <div className="flex flex-wrap items-center gap-2">
+            <span className="text-muted-foreground">Approval-gated tools:</span>
+            {config ? (
+              config.agent_require_approval.map((tool) => (
+                <Badge key={tool} variant="outline" className="font-mono">
+                  <AlertTriangle className="mr-1 h-3 w-3" />
+                  {tool}
+                </Badge>
+              ))
+            ) : (
+              <Skeleton className="h-5 w-40" />
+            )}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Session limits */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <Gauge className="h-5 w-5 text-muted-foreground" />
+            <CardTitle>Session limits</CardTitle>
+          </div>
+          <CardDescription>
+            Live from <code className="rounded bg-muted px-1 py-0.5 text-xs">GET /config/ai</code>.
+            These are the configured defaults — an operator can change them in Admin → AI Models.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {configLoading && <Skeleton className="h-48 w-full" />}
+          {config && (
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Limit</TableHead>
+                  <TableHead>Value</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                <TableRow>
+                  <TableCell className="font-medium">Token budget per session</TableCell>
+                  <TableCell>{config.agent_max_tokens.toLocaleString()} tokens</TableCell>
+                </TableRow>
+                <TableRow>
+                  <TableCell className="font-medium">Tool calls per session</TableCell>
+                  <TableCell>{config.agent_max_tool_calls}</TableCell>
+                </TableRow>
+                <TableRow>
+                  <TableCell className="font-medium">Per-run timeout</TableCell>
+                  <TableCell>{config.agent_timeout_seconds} seconds</TableCell>
+                </TableRow>
+                <TableRow>
+                  <TableCell className="font-medium">Retry attempts</TableCell>
+                  <TableCell>{config.agent_retry_attempts}</TableCell>
+                </TableRow>
+                <TableRow>
+                  <TableCell className="font-medium">Session time-to-live</TableCell>
+                  <TableCell>{config.agent_session_ttl_minutes} minutes</TableCell>
+                </TableRow>
+                <TableRow>
+                  <TableCell className="font-medium">Approval-gated tools</TableCell>
+                  <TableCell className="font-mono text-xs">
+                    {config.agent_require_approval.join(', ') || 'none'}
+                  </TableCell>
+                </TableRow>
+              </TableBody>
+            </Table>
+          )}
+          {!configLoading && !config && (
+            <p className="text-sm text-muted-foreground">
+              Session limits are unavailable right now — the configuration endpoint could not be
+              reached.
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Example prompts */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <MessageSquare className="h-5 w-5 text-muted-foreground" />
+            <CardTitle>Example prompts</CardTitle>
+          </div>
+          <CardDescription>Copy one of these into Chat to get started.</CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-6 md:grid-cols-2">
+          <PromptList title="RAG Assistant" prompts={RAG_PROMPTS} />
+          <PromptList title="Experiment Agent" prompts={EXPERIMENT_PROMPTS} />
+        </CardContent>
+      </Card>
+
+      {/* CTA */}
+      <div className="flex justify-center pb-2">
+        <Button asChild size="lg">
+          <Link to={ROUTES.CHAT}>
+            <MessageSquare className="mr-2 h-4 w-4" />
+            Open Chat
+          </Link>
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+function AgentCard({
+  icon: Icon,
+  title,
+  agentId,
+  purpose,
+  tools,
+  footer,
+}: {
+  icon: React.ComponentType<{ className?: string }>
+  title: string
+  agentId: string
+  purpose: string
+  tools: ToolInfo[]
+  footer: React.ReactNode
+}) {
+  return (
+    <Card className="flex flex-col">
+      <CardHeader>
+        <div className="flex items-center gap-2">
+          <Icon className="h-5 w-5 text-muted-foreground" />
+          <CardTitle>{title}</CardTitle>
+          <Badge variant="secondary" className="font-mono text-xs">
+            {agentId}
+          </Badge>
+        </div>
+        <CardDescription>{purpose}</CardDescription>
+      </CardHeader>
+      <CardContent className="flex flex-1 flex-col gap-4">
+        <div>
+          <p className="mb-2 text-sm font-medium">Tools</p>
+          <ul className="space-y-2">
+            {tools.map((tool) => (
+              <li key={tool.name} className="text-sm">
+                <div className="flex flex-wrap items-center gap-2">
+                  <code className="rounded bg-muted px-1.5 py-0.5 text-xs">{tool.name}</code>
+                  {tool.approval && (
+                    <Badge variant="outline" className="text-[10px]">
+                      <AlertTriangle className="mr-1 h-3 w-3" />
+                      requires approval
+                    </Badge>
+                  )}
+                </div>
+                <p className="mt-0.5 text-xs text-muted-foreground">{tool.desc}</p>
+              </li>
+            ))}
+          </ul>
+        </div>
+        <div className="mt-auto pt-2">{footer}</div>
+      </CardContent>
+    </Card>
+  )
+}
+
+function PromptList({ title, prompts }: { title: string; prompts: string[] }) {
+  return (
+    <div className="space-y-2">
+      <p className="text-sm font-medium">{title}</p>
+      {prompts.map((prompt) => (
+        <code
+          key={prompt}
+          className="block rounded-md border bg-muted/50 px-3 py-2 text-xs leading-relaxed"
+        >
+          {prompt}
+        </code>
+      ))}
+    </div>
+  )
+}
diff --git a/frontend/src/pages/knowledge.tsx b/frontend/src/pages/knowledge.tsx
new file mode 100644
index 00000000..1335ae88
--- /dev/null
+++ b/frontend/src/pages/knowledge.tsx
@@ -0,0 +1,344 @@
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+import { format } from 'date-fns'
+import {
+  Library,
+  Search,
+  FileText,
+  Loader2,
+  Store,
+  Package,
+  TrendingUp,
+  CalendarRange,
+  Database,
+  Tag,
+  ArrowRight,
+  FolderOpen,
+} from 'lucide-react'
+import { useRagSources, useRetrieve } from '@/hooks/use-rag-sources'
+import { useSeederStatus } from '@/hooks/use-seeder'
+import { useRuns, useAliases } from '@/hooks/use-runs'
+import { LoadingState } from '@/components/common/loading-state'
+import { ErrorDisplay } from '@/components/common/error-display'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { Input } from '@/components/ui/input'
+import { Skeleton } from '@/components/ui/skeleton'
+import { ApiError, getErrorMessage } from '@/lib/api'
+import { ROUTES } from '@/lib/constants'
+import { formatRelevance, chunkExcerpt, groupSourcesByType } from '@/lib/knowledge-utils'
+
+export default function KnowledgePage() {
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div>
+        <h1 className="text-3xl font-bold">Knowledge</h1>
+        <p className="mt-1 text-muted-foreground">
+          Everything ForecastLabAI can currently draw on — the RAG knowledge base its assistant
+          answers from, and the live data its experiment agent acts on.
+        </p>
+      </div>
+
+      <KnowledgeBaseSection />
+      <SemanticSearchSection />
+      <LiveSystemStateSection />
+    </div>
+  )
+}
+
+// === Section 1 — Knowledge Base (indexed RAG sources, read-only) ===
+
+function KnowledgeBaseSection() {
+  const { data, isLoading, error, refetch } = useRagSources()
+
+  if (error) {
+    return <ErrorDisplay error={error} onRetry={refetch} title="Could not load the knowledge base" />
+  }
+  if (isLoading) {
+    return <LoadingState message="Loading the knowledge base..." />
+  }
+
+  const sources = data?.sources ?? []
+  const byType = groupSourcesByType(sources)
+
+  return (
+    <Card>
+      <CardHeader>
+        <div className="flex items-center gap-2">
+          <Library className="h-5 w-5 text-muted-foreground" />
+          <CardTitle>Knowledge Base</CardTitle>
+        </div>
+        <CardDescription>
+          {data?.total_sources ?? 0} sources • {data?.total_chunks ?? 0} chunks
+          {sources.length > 0 && (
+            <>
+              {' • '}
+              {Object.entries(byType)
+                .map(([type, items]) => `${items.length} ${type}`)
+                .join(', ')}
+            </>
+          )}
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        {sources.length > 0 ? (
+          <div className="space-y-3">
+            {sources.map((source) => (
+              <div
+                key={source.source_id}
+                className="flex items-center justify-between gap-4 border-b py-2 last:border-0"
+              >
+                <div className="flex min-w-0 items-center gap-3">
+                  <FileText className="h-4 w-4 shrink-0 text-muted-foreground" />
+                  <div className="min-w-0">
+                    <p className="truncate font-medium">{source.source_path}</p>
+                    <p className="text-xs text-muted-foreground">
+                      {source.chunk_count} chunks • Indexed{' '}
+                      {format(new Date(source.indexed_at), 'MMM d, yyyy')}
+                    </p>
+                  </div>
+                </div>
+                <Badge variant="secondary" className="shrink-0">
+                  {source.source_type}
+                </Badge>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <div className="flex flex-col items-center justify-center gap-3 py-10 text-center">
+            <FolderOpen className="h-10 w-10 text-muted-foreground" />
+            <div>
+              <p className="font-medium">No documents indexed yet</p>
+              <p className="text-sm text-muted-foreground">
+                The RAG assistant has nothing to answer from. Index documents in Admin → RAG
+                Sources, or run the RAG seeder scenario.
+              </p>
+            </div>
+            <Button asChild variant="outline" size="sm">
+              <Link to={ROUTES.ADMIN}>
+                Go to Admin → RAG Sources
+                <ArrowRight className="ml-2 h-4 w-4" />
+              </Link>
+            </Button>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
+
+// === Section 2 — Semantic Search (POST /rag/retrieve) ===
+
+function SemanticSearchSection() {
+  const [query, setQuery] = useState('')
+  const retrieve = useRetrieve()
+
+  const trimmed = query.trim()
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!trimmed || retrieve.isPending) return
+    retrieve.mutate({ query: trimmed, top_k: 5 })
+  }
+
+  const searchUnavailable = retrieve.error instanceof ApiError && retrieve.error.status === 502
+  const results = retrieve.data?.results ?? []
+
+  return (
+    <Card>
+      <CardHeader>
+        <div className="flex items-center gap-2">
+          <Search className="h-5 w-5 text-muted-foreground" />
+          <CardTitle>Semantic Search</CardTitle>
+        </div>
+        <CardDescription>
+          Search the indexed knowledge base the way the RAG assistant does — by meaning, not
+          keywords.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <form onSubmit={handleSubmit} className="flex gap-2">
+          <Input
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="e.g. How does backtesting prevent data leakage?"
+            aria-label="Semantic search query"
+          />
+          <Button type="submit" disabled={!trimmed || retrieve.isPending}>
+            {retrieve.isPending ? (
+              <Loader2 className="h-4 w-4 animate-spin" />
+            ) : (
+              <Search className="h-4 w-4" />
+            )}
+            <span className="ml-2">Search</span>
+          </Button>
+        </form>
+
+        {searchUnavailable && (
+          <p className="rounded-md border border-dashed bg-muted/40 px-4 py-3 text-sm text-muted-foreground">
+            Semantic search is unavailable — configure an embedding provider in{' '}
+            <Link to={ROUTES.ADMIN} className="font-medium underline underline-offset-2">
+              Admin → AI Models
+            </Link>
+            . The source list above does not need embeddings and still works.
+          </p>
+        )}
+
+        {retrieve.isError && !searchUnavailable && (
+          <p className="rounded-md border border-dashed bg-muted/40 px-4 py-3 text-sm text-destructive">
+            {getErrorMessage(retrieve.error)}
+          </p>
+        )}
+
+        {retrieve.isSuccess && results.length === 0 && (
+          <p className="rounded-md border border-dashed bg-muted/40 px-4 py-3 text-sm text-muted-foreground">
+            No matching content found. Try rephrasing the query.
+          </p>
+        )}
+
+        {results.length > 0 && (
+          <div className="space-y-3">
+            <p className="text-xs text-muted-foreground">
+              {results.length} match{results.length === 1 ? '' : 'es'} •{' '}
+              {retrieve.data?.total_chunks_searched ?? 0} chunks searched in{' '}
+              {Math.round(retrieve.data?.search_time_ms ?? 0)} ms
+            </p>
+            {results.map((chunk) => (
+              <div key={chunk.chunk_id} className="rounded-lg border p-3">
+                <div className="mb-1.5 flex items-center justify-between gap-3">
+                  <p className="truncate font-mono text-xs text-muted-foreground">
+                    {chunk.source_path}
+                    <span className="ml-1 text-muted-foreground/70">({chunk.source_type})</span>
+                  </p>
+                  <Badge variant="outline" className="shrink-0">
+                    {formatRelevance(chunk.relevance_score)} match
+                  </Badge>
+                </div>
+                <p className="text-sm leading-relaxed">{chunkExcerpt(chunk)}</p>
+              </div>
+            ))}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
+
+// === Section 3 — Live System State (what the experiment agent acts on) ===
+
+function StatCard({
+  icon: Icon,
+  label,
+  value,
+}: {
+  icon: React.ComponentType<{ className?: string }>
+  label: string
+  value: string | number
+}) {
+  return (
+    <div className="rounded-lg bg-muted p-3 text-center">
+      <Icon className="mx-auto mb-1 h-4 w-4 text-muted-foreground" />
+      <p className="text-lg font-bold">{typeof value === 'number' ? value.toLocaleString() : value}</p>
+      <p className="text-xs text-muted-foreground">{label}</p>
+    </div>
+  )
+}
+
+function LiveSystemStateSection() {
+  const { data: status, isLoading: statusLoading } = useSeederStatus()
+  const { data: runs, isLoading: runsLoading } = useRuns({ page: 1, pageSize: 1 })
+  const { data: aliases, isLoading: aliasesLoading } = useAliases()
+
+  const dateRange =
+    status?.date_range_start && status?.date_range_end
+      ? `${status.date_range_start} → ${status.date_range_end}`
+      : 'No data'
+
+  return (
+    <Card>
+      <CardHeader>
+        <div className="flex items-center gap-2">
+          <Database className="h-5 w-5 text-muted-foreground" />
+          <CardTitle>Live System State</CardTitle>
+        </div>
+        <CardDescription>
+          The seeded data and registered models the experiment agent can query through its tools.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        {/* Seeded data tiles */}
+        {statusLoading ? (
+          <div className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+            {Array.from({ length: 4 }).map((_, i) => (
+              <Skeleton key={i} className="h-20" />
+            ))}
+          </div>
+        ) : (
+          <div className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+            <StatCard icon={Store} label="Stores" value={status?.stores ?? 0} />
+            <StatCard icon={Package} label="Products" value={status?.products ?? 0} />
+            <StatCard icon={TrendingUp} label="Sales records" value={status?.sales ?? 0} />
+            <StatCard icon={CalendarRange} label="Date range" value={dateRange} />
+          </div>
+        )}
+
+        {/* Registry summary */}
+        <div className="grid gap-4 md:grid-cols-2">
+          <div className="rounded-lg border p-4">
+            <div className="flex items-center gap-2">
+              <TrendingUp className="h-4 w-4 text-muted-foreground" />
+              <p className="text-sm font-medium">Registered model runs</p>
+            </div>
+            <p className="mt-2 text-2xl font-bold">
+              {runsLoading ? '—' : (runs?.total ?? 0).toLocaleString()}
+            </p>
+            <Link
+              to={ROUTES.EXPLORER.RUNS}
+              className="mt-1 inline-flex items-center text-xs text-muted-foreground underline underline-offset-2"
+            >
+              Browse all runs
+              <ArrowRight className="ml-1 h-3 w-3" />
+            </Link>
+          </div>
+
+          <div className="rounded-lg border p-4">
+            <div className="flex items-center gap-2">
+              <Tag className="h-4 w-4 text-muted-foreground" />
+              <p className="text-sm font-medium">Deployment aliases</p>
+            </div>
+            {aliasesLoading ? (
+              <p className="mt-2 text-sm text-muted-foreground">Loading…</p>
+            ) : aliases && aliases.length > 0 ? (
+              <ul className="mt-2 space-y-1">
+                {aliases.map((alias) => (
+                  <li key={alias.alias_name} className="flex items-center justify-between text-sm">
+                    <span className="font-medium">{alias.alias_name}</span>
+                    <Badge variant="secondary">{alias.model_type}</Badge>
+                  </li>
+                ))}
+              </ul>
+            ) : (
+              <p className="mt-2 text-sm text-muted-foreground">No aliases yet.</p>
+            )}
+          </div>
+        </div>
+
+        {/* Explainer */}
+        <p className="text-sm text-muted-foreground">
+          The RAG assistant answers from the Knowledge Base above; the experiment agent acts on this
+          Live System State. Learn how to use them in the{' '}
+          <Link to={ROUTES.GUIDE} className="font-medium text-foreground underline underline-offset-2">
+            Agent Guide
+          </Link>
+          , or start a conversation in{' '}
+          <Link to={ROUTES.CHAT} className="font-medium text-foreground underline underline-offset-2">
+            Chat
+          </Link>
+          .
+        </p>
+      </CardContent>
+    </Card>
+  )
+}
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index c356c6ab..ecd51d02 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -76,6 +76,46 @@ export interface DrilldownResponse {
   product_id: number | null
 }
 
+// Bucket size for GET /analytics/timeseries.
+export type TimeGranularity = 'day' | 'week' | 'month' | 'quarter'
+
+// One aggregated period of the sales time series.
+export interface TimeSeriesPoint {
+  period: string // ISO date (bucket start)
+  metrics: KPIMetrics
+}
+
+// Response from GET /analytics/timeseries (points ascending by period).
+export interface TimeSeriesResponse {
+  granularity: TimeGranularity
+  points: TimeSeriesPoint[]
+  total_points: number
+  start_date: string
+  end_date: string
+  store_id: number | null
+  product_id: number | null
+  category: string | null
+}
+
+// One day of a product's lifecycle demand curve.
+export interface LifecyclePoint {
+  date: string // ISO date
+  stage: string
+  multiplier: number
+}
+
+// Response from GET /dimensions/products/{id}/lifecycle-curve.
+export interface LifecycleCurveResponse {
+  product_id: number
+  sku: string
+  launch_date: string | null
+  discontinue_date: string | null
+  start_date: string
+  end_date: string
+  points: LifecyclePoint[]
+  total: number
+}
+
 // === Registry ===
 export type RunStatus = 'pending' | 'running' | 'success' | 'failed' | 'archived'
 
@@ -125,6 +165,17 @@ export interface RunCompareResponse {
   metrics_diff: Record<string, { a: number | null; b: number | null; diff: number | null }>
 }
 
+// Response from GET /registry/runs/{run_id}/verify (SHA-256 integrity check).
+// On a checksum mismatch the endpoint returns HTTP 200 with verified:false + error.
+export interface ArtifactVerifyResponse {
+  verified: boolean
+  run_id: string
+  artifact_uri: string
+  stored_hash?: string
+  computed_hash?: string
+  error?: string
+}
+
 // === Jobs ===
 export type JobType = 'train' | 'predict' | 'backtest'
 export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
@@ -181,6 +232,35 @@ export interface IndexDocumentResponse {
   chunks_created: number
 }
 
+// Semantic-search request for POST /rag/retrieve.
+// Mirrors app/features/rag/schemas.py RetrieveRequest (extra="forbid" — send
+// nothing beyond these fields). Omit similarity_threshold to use the server default.
+export interface RetrieveRequest {
+  query: string
+  top_k?: number // 1..50, server default 5
+  similarity_threshold?: number // 0..1
+  filters?: Record<string, unknown> | null
+}
+
+// One matching chunk from a semantic search.
+export interface ChunkResult {
+  chunk_id: string
+  source_id: string
+  source_path: string
+  source_type: string
+  content: string
+  relevance_score: number // 0..1
+  metadata: Record<string, unknown> | null
+}
+
+// Response from POST /rag/retrieve.
+export interface RetrieveResponse {
+  results: ChunkResult[]
+  query_embedding_time_ms: number
+  search_time_ms: number
+  total_chunks_searched: number
+}
+
 // === Agents WebSocket ===
 export type AgentEventType =
   | 'text_delta'
@@ -373,6 +453,11 @@ export interface AIModelConfig {
   agent_temperature: number
   agent_max_tokens: number
   agent_thinking_budget: number | null
+  agent_max_tool_calls: number
+  agent_timeout_seconds: number
+  agent_retry_attempts: number
+  agent_session_ttl_minutes: number
+  agent_require_approval: string[]
   rag_embedding_provider: string
   rag_embedding_model: string
   rag_embedding_dimension: number
diff --git a/scripts/run_demo.py b/scripts/run_demo.py
index 03d26913..8acfc255 100644
--- a/scripts/run_demo.py
+++ b/scripts/run_demo.py
@@ -43,7 +43,7 @@
 import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
-from datetime import date, timedelta
+from datetime import UTC, date, datetime, timedelta
 from pathlib import Path
 from typing import Any, Final
 
@@ -75,8 +75,10 @@
 DEMO_SCENARIO: Final[str] = "demo_minimal"
 DEMO_SEED_STORES: Final[int] = 3
 DEMO_SEED_PRODUCTS: Final[int] = 10
-DEMO_SEED_START: Final[date] = date(2024, 10, 1)
-DEMO_SEED_END: Final[date] = date(2024, 12, 31)
+# Seed window is anchored to *today* so the demo always runs on
+# current-looking data; it spans DEMO_SEED_SPAN_DAYS back from today (92 days
+# inclusive). Must stay >= 72 for a non-NaN backtest WAPE.
+DEMO_SEED_SPAN_DAYS: Final[int] = 91
 
 DEMO_MODEL_TYPES: Final[tuple[str, ...]] = ("naive", "seasonal_naive", "moving_average")
 
@@ -411,6 +413,8 @@ async def step_seed(ctx: DemoContext, client: HttpClient) -> StepOutcome:
             detail="--skip-seed set",
             duration_ms=(time.monotonic() - start) * 1000,
         )
+    seed_end = datetime.now(UTC).date()
+    seed_start = seed_end - timedelta(days=DEMO_SEED_SPAN_DAYS)
     body = await client.request(
         "seed",
         "POST",
@@ -420,8 +424,8 @@ async def step_seed(ctx: DemoContext, client: HttpClient) -> StepOutcome:
             "seed": ctx.seed,
             "stores": DEMO_SEED_STORES,
             "products": DEMO_SEED_PRODUCTS,
-            "start_date": DEMO_SEED_START.isoformat(),
-            "end_date": DEMO_SEED_END.isoformat(),
+            "start_date": seed_start.isoformat(),
+            "end_date": seed_end.isoformat(),
             "sparsity": 0.0,
             "dry_run": False,
         },
diff --git a/scripts/seed_random.py b/scripts/seed_random.py
index 27263e96..c544ad43 100644
--- a/scripts/seed_random.py
+++ b/scripts/seed_random.py
@@ -40,6 +40,8 @@
     RetailPatternConfig,
     SparsityConfig,
     TimeSeriesConfig,
+    default_seed_end_date,
+    default_seed_start_date,
 )
 from app.shared.seeder.rag_scenario import run_rag_scenario
 
@@ -112,8 +114,10 @@ def load_config_from_yaml(path: Path) -> SeederConfig:
 
     # Parse date range
     date_range = data.get("date_range", {})
-    start_date = parse_date(date_range["start"]) if "start" in date_range else date(2024, 1, 1)
-    end_date = parse_date(date_range["end"]) if "end" in date_range else date(2024, 12, 31)
+    start_date = (
+        parse_date(date_range["start"]) if "start" in date_range else default_seed_start_date()
+    )
+    end_date = parse_date(date_range["end"]) if "end" in date_range else default_seed_end_date()
 
     # Parse time series config
     ts_data = data.get("time_series", {})
@@ -243,14 +247,14 @@ def create_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--start-date",
         type=parse_date,
-        default=date(2024, 1, 1),
-        help="Start of date range (default: 2024-01-01)",
+        default=default_seed_start_date(),
+        help="Start of date range (default: one year before today)",
     )
     parser.add_argument(
         "--end-date",
         type=parse_date,
-        default=date(2024, 12, 31),
-        help="End of date range (default: 2024-12-31)",
+        default=default_seed_end_date(),
+        help="End of date range (default: today)",
     )
     parser.add_argument(
         "--sparsity",
diff --git a/tests/test_demo_showcase_integration.py b/tests/test_demo_showcase_integration.py
index a9538551..5c0c5b38 100644
--- a/tests/test_demo_showcase_integration.py
+++ b/tests/test_demo_showcase_integration.py
@@ -7,14 +7,21 @@
 ``integration`` so it is excluded from the fast unit run.
 """
 
+from datetime import timedelta
+
 import pytest
 
+from app.shared.seeder.config import DEMO_MINIMAL_SPAN_DAYS, default_seed_end_date
+
 pytestmark = pytest.mark.integration
 
 
 async def test_demo_run_pipeline_end_to_end(client):
     """Seed demo_minimal, run the demo pipeline, and verify the registered winner."""
     # Precondition: seed the demo_minimal scenario so skip_seed=true has data.
+    # The window is anchored to today, mirroring the demo pipeline's own seed step.
+    seed_end = default_seed_end_date()
+    seed_start = seed_end - timedelta(days=DEMO_MINIMAL_SPAN_DAYS)
     seed_resp = await client.post(
         "/seeder/generate",
         json={
@@ -22,8 +29,8 @@ async def test_demo_run_pipeline_end_to_end(client):
             "seed": 42,
             "stores": 3,
             "products": 10,
-            "start_date": "2024-10-01",
-            "end_date": "2024-12-31",
+            "start_date": seed_start.isoformat(),
+            "end_date": seed_end.isoformat(),
             "sparsity": 0.0,
             "dry_run": False,
         },
diff --git a/tests/test_run_demo_unit.py b/tests/test_run_demo_unit.py
index 4140d95a..0630b1d1 100644
--- a/tests/test_run_demo_unit.py
+++ b/tests/test_run_demo_unit.py
@@ -8,16 +8,19 @@
 from __future__ import annotations
 
 import math
+from datetime import timedelta
 from typing import Any
 from unittest.mock import AsyncMock
 
 import pytest
 
+from app.shared.seeder.config import default_seed_end_date
 from scripts import run_demo
 from scripts.run_demo import (
     DEMO_ALIAS,
     DEMO_HORIZON,
     DEMO_MODEL_TYPES,
+    DEMO_SEED_SPAN_DAYS,
     GLYPHS,
     DemoArgs,
     DemoContext,
@@ -341,7 +344,11 @@ class TestStepPayloads:
     async def test_step_seed_sends_demo_minimal(
         self,
     ) -> None:
-        """Seed step posts demo_minimal scenario with correct dims + dates."""
+        """Seed step posts demo_minimal scenario with correct dims + dates.
+
+        The seed window is anchored to *today* and runs DEMO_SEED_SPAN_DAYS
+        backwards, so the demo always seeds current-looking data.
+        """
         calls: list[dict[str, Any]] = []
 
         class _RecordingClient:
@@ -374,8 +381,9 @@ async def request(
         assert body["seed"] == 42
         assert body["stores"] == 3
         assert body["products"] == 10
-        assert body["start_date"] == "2024-10-01"
-        assert body["end_date"] == "2024-12-31"
+        today = default_seed_end_date()
+        assert body["end_date"] == today.isoformat()
+        assert body["start_date"] == (today - timedelta(days=DEMO_SEED_SPAN_DAYS)).isoformat()
 
     @pytest.mark.asyncio
     async def test_step_seed_skipped(self) -> None:

From f4737389f44f1f40c6fc9caf6f1d7fd02f8eeb18 Mon Sep 17 00:00:00 2001
From: Gabor Szabo <168316277+w7-mgfcode@users.noreply.github.com>
Date: Mon, 18 May 2026 21:53:36 +0200
Subject: [PATCH 2/2] chore(main): release 0.2.13 (#193)

---
 .release-please-manifest.json | 2 +-
 CHANGELOG.md                  | 7 +++++++
 pyproject.toml                | 2 +-
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index bf1a075f..45f2163e 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.2.12"
+  ".": "0.2.13"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 101e404c..8d99b4ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.13](https://github.com/w7-mgfcode/ForecastLabAI/compare/v0.2.12...v0.2.13) (2026-05-18)
+
+
+### Features
+
+* cut v0.2.13 — explorer interactivity, knowledge & guide pages ([#191](https://github.com/w7-mgfcode/ForecastLabAI/issues/191)) ([#192](https://github.com/w7-mgfcode/ForecastLabAI/issues/192)) ([ae37ca5](https://github.com/w7-mgfcode/ForecastLabAI/commit/ae37ca521eb9510c135def4a1e3730e137fb014b))
+
 ## [0.2.12](https://github.com/w7-mgfcode/ForecastLabAI/compare/v0.2.11...v0.2.12) (2026-05-18)
 
 
diff --git a/pyproject.toml b/pyproject.toml
index 46dcc482..7a42992e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "forecastlabai"
-version = "0.2.12"
+version = "0.2.13"
 description = "Portfolio-grade end-to-end retail demand forecasting system"
 readme = "README.md"
 requires-python = ">=3.12"