merge: integrate TanStack Query migration and refactor template library

Resolve merge conflict with main (PR #298 TanStack Query migration).
Refactor TemplateLibraryPage from Zustand useTemplateStore to TanStack
Query hooks with staleTime: Infinity for static template data. Add
template query keys, idle prefetch, and route chunk prefetch.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>

Author: krishna9358

.claude/skills/performance-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: performance-review
+description: Review frontend code changes for performance anti-patterns and guideline compliance. Checks query hooks, stale times, bundle impact, rendering patterns, and Zustand selectors.
+user_invocable: true
+---
+
+# Frontend Performance Review
+
+**Reference:** `frontend/docs/performance.md`
+
+---
+
+## When to Invoke
+
+- Before submitting a PR that adds or modifies query hooks, page components, Zustand stores, or real-time features
+- When the user asks for a "performance review" or "perf check"
+- As part of the component-development workflow for new pages
+
+## Agent Instructions
+
+When invoked, perform the following checks in order. Report PASS/FAIL/WARN for each. Group failures by severity: **CRITICAL** (must fix before merge), **WARNING** (should fix), **INFO** (consider).
+
+### Step 1: Identify Scope
+
+Read the diff or the files specified by the user. If no files specified, use `git diff --name-only` to find changed frontend files. Identify which categories apply: query hooks, page routes, stores, real-time, bundle.
+
+### Step 2: Query Hook Checks
+
+1. Search for `useState` + `useEffect` + `api.` within 20 lines of each other in changed files. If found: **CRITICAL** — should be a TanStack Query hook.
+2. Check that new `useQuery` calls reference a key from `queryKeys.ts`, not an inline array. If inline: **CRITICAL**.
+3. Check that new query hook files are named `use<Domain>Queries.ts` and placed in `src/hooks/queries/`. If misplaced: **WARNING**.
+4. Check that `useMutation` calls include `onSuccess` with `queryClient.invalidateQueries()`. If missing: **WARNING**.
+5. Check for `skipToken` usage on conditional queries vs. `enabled: false`. Flag `enabled: false` without `skipToken` as **WARNING**.
+
+### Step 3: Stale Time Audit
+
+1. For each new `useQuery`, check if `staleTime` is set explicitly or inherits the 30s default appropriately.
+2. Cross-reference the data type: if the query fetches components, templates, or providers — flag missing `staleTime: Infinity` as **CRITICAL**.
+3. For execution queries, verify they use `executionQueryOptions.ts` factories rather than inline values. Flag inconsistency as **WARNING**.
+4. For queries on terminal runs, verify `terminalStaleTime()` is used rather than a hardcoded number.
+
+### Step 4: Bundle Impact
+
+1. For each new page added to `App.tsx`: verify it uses `React.lazy(() => import(...))`. Static imports are **CRITICAL**.
+2. Verify new sidebar pages are added to `routePrefetchMap` in `src/lib/prefetch-routes.ts`. Missing entry is **WARNING**.
+3. If a new conditionally-visible component imports a library > 100KB (check for `@xterm`, `posthog-js`, `lucide-react` barrel imports): flag as **WARNING** — consider deferred load pattern.
+
+### Step 5: Rendering Checks
+
+1. Search for `const [*, set*] = useState` followed by `set*` inside a `useEffect` that references query data — **CRITICAL** (should use `useMemo`).
+2. Look for derived data calculations inline in JSX without `useMemo` involving array operations (filter, sort, reduce) — **WARNING**.
+3. Check for `React.memo` usage on new components in `timeline/` or `workflow/` directories that re-render frequently — **INFO** if missing.
+
+### Step 6: Zustand Store Checks
+
+1. Search for `const store = use<X>Store()` or destructuring from `use<X>Store()` without a selector — full store subscription. **WARNING**.
+2. For new stores using `persist`, verify `partialize` is present. Missing is **WARNING**.
+3. For new `persist` stores, verify action functions are excluded from `partialize`.
+
+### Step 7: Generate Report
+
+Format the output as follows:
+
+```
+## Performance Review: [description of scope]
+
+### Critical (must fix before merge)
+- [file:line] Description of issue. See: performance.md § [section]
+
+### Warnings (should fix)
+- [file:line] Description of issue. See: performance.md § [section]
+
+### Info (consider)
+- [file:line] Description. See: performance.md § [section]
+
+### Passed Checks
+- [n] query hooks using TanStack Query correctly
+- [n] page routes using React.lazy
+- [n] Zustand selectors properly scoped
+- staleTime: appropriate tiers applied
+
+### Summary
+[1-2 sentences on overall performance hygiene of the change]
+```
+
+## Rules
+
+- This is a **review only** — do NOT make code changes unless the user explicitly asks
+- Always cite the file and line number for each finding
+- Always reference `frontend/docs/performance.md` for the relevant pattern section
+- If no frontend files are in the diff, report "No frontend changes detected" and exit

.claude/skills/stress-test-frontend/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: stress-test-frontend
+description: Run a frontend load testing audit. Seeds data, tests all pages via Chrome DevTools MCP, records network calls, TanStack queries, DOM sizes, and generates a timestamped report.
+user_invocable: true
+---
+
+# Frontend Load Testing Audit
+
+**Testing plan:** `frontend/docs/load-testing-plan.md`
+**Previous reports:** `frontend/docs/audits/`
+
+---
+
+## Agent Instructions
+
+When the user invokes `/stress-test-frontend`, perform a full frontend load testing audit:
+
+### 1. Setup
+
+1. Read the testing plan at `frontend/docs/load-testing-plan.md` for the full methodology
+2. Seed data: `bun backend/scripts/seed-stress-test.ts --tier medium`
+3. Verify nginx is responding on `localhost` (not the direct Vite port)
+
+### 2. Discover Routes
+
+1. Read `frontend/src/App.tsx` and extract all `<Route path="...">` entries
+2. Compare against the **Known Pages** table in the testing plan
+3. Add any new routes to the audit list; skip removed routes and note them in the report
+4. For parameterized routes (e.g., `/workflows/:id`), use real entities from seeded data
+
+### 3. Audit Every Page
+
+Follow the discovered route list (Known Pages + any new routes). For each page:
+
+1. Navigate via `localhost` (nginx reverse proxy) — **never use the direct Vite dev server port**
+2. Wait for data to load (spinners gone, tables populated)
+3. Take a screenshot and save to `.context/`
+4. Record all fetch/XHR network requests with timing
+5. Extract TanStack Query cache state using the snippet in the testing plan
+6. Measure DOM element count: `document.querySelectorAll('*').length`
+7. Note anomalies: ghost queries, duplicate calls, missing pagination, large payloads
+
+For Page 1 (Workflow List), also run a Chrome performance trace to get LCP, CLS, TTFB.
+
+### 4. Generate Report
+
+1. Compile all per-page data into a report following the format of previous reports in `frontend/docs/audits/`
+2. Include cross-page analysis: DOM comparison, API call counts, shared queries, pagination gaps
+3. Summarize findings with severity ratings (MEDIUM/LOW/INFO)
+4. Save the report as `frontend/docs/audits/load-audit-<YYYY-MM-DDTHH-MM>.md` using the current datetime
+5. If a previous report exists, note any improvements or regressions compared to the most recent one
+
+### 5. Important Rules
+
+- This is an **audit only** — do NOT make any code changes or fixes
+- All testing must go through `localhost` (nginx), not the direct Vite dev server port
+- Use Chrome DevTools MCP tools for all browser interaction
+- Save screenshots to `.context/` directory

AGENTS.md

@@ -98,6 +98,35 @@ bun --cwd backend run db:studio            # View data
 4. **E2E Tests**: Mandatory for significant features. Place in `e2e-tests/` folder.
 5. **GitHub CLI**: Use `gh` for all GitHub operations (issues, PRs, actions, releases). Never use browser automation for GitHub tasks.
 
+### Frontend: Read Before Writing Code
+
+Before writing ANY frontend code that fetches data or adds a page, you MUST read these files first:
+
+1. `frontend/docs/state.md` — Decision guide: TanStack Query vs Zustand, hook patterns, anti-patterns
+2. `frontend/docs/performance.md` — Stale time tiers, bundle splitting, prefetch patterns, query key architecture
+3. `frontend/src/lib/queryKeys.ts` — Existing query key factories (add new keys here, never inline)
+4. Browse `frontend/src/hooks/queries/` — Follow existing hook naming conventions (`use<Domain>Queries.ts`)
+
+### Frontend Data Fetching (Mandatory)
+
+6. **All API data must use TanStack Query hooks** in `frontend/src/hooks/queries/`. Never use `useState` + `useEffect` to fetch backend data — this is the single most important frontend rule.
+7. **Query keys** go in `frontend/src/lib/queryKeys.ts` (org-scoped, factory functions).
+8. **After mutations**, invalidate the relevant query cache via `queryClient.invalidateQueries()` — do not manually update local state.
+9. **Derive data** from query results using `useMemo`, not by copying into separate `useState`.
+10. **Zustand stores** are for client-only UI state (canvas, timeline, auth). Never store API data in Zustand.
+
+See `frontend/docs/state.md` for patterns, anti-patterns, and the full decision guide.
+
+### Frontend Performance (Mandatory)
+
+See `frontend/docs/performance.md` for the complete reference with code examples.
+
+11. **Every new page must use `React.lazy()`** in `App.tsx`. Add the route to `routePrefetchMap` in `src/lib/prefetch-routes.ts`.
+12. **Set `staleTime: Infinity` for static/reference data** (components, templates, providers). The 30s default is wrong for them.
+13. **Use `skipToken` for conditional queries** instead of `enabled: false` alone. See `useRunQueries.ts`.
+14. **Granular Zustand selectors**: `useStore((s) => s.field)`, never `const store = useStore()`.
+15. **No N+1 queries**: never call a query hook inside `.map()`. Use a batched endpoint (see `useMcpGroupsWithServers`).
+
 ---
 
 ## Architecture
@@ -140,6 +169,16 @@ When tasks match a skill, load it: `cat .claude/skills/<name>/SKILL.md`
 <description>Creating components (inline/docker). Dynamic ports, retry policies, PTY patterns, IsolatedContainerVolume.</description>
 <location>project</location>
 </skill>
+<skill>
+<name>performance-review</name>
+<description>Review code changes for frontend performance anti-patterns. Checks stale times, bundle splitting, Zustand selectors, N+1 queries, and React rendering.</description>
+<location>project</location>
+</skill>
+<skill>
+<name>stress-test-frontend</name>
+<description>Run a frontend load testing audit. Seeds data, tests all pages via Chrome DevTools MCP, records network calls, TanStack queries, DOM sizes, and generates a timestamped report.</description>
+<location>project</location>
+</skill>
 </available_skills>
 
 </skills_system>