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: