From ffb804e939ace8772632d5fee9c864e6c5e9522b Mon Sep 17 00:00:00 2001
From: mbeaulne <matt.beaulne@gmail.com>
Date: Thu, 12 Mar 2026 13:17:34 -0400
Subject: [PATCH] convert cursor rules to skills

---
 .claude/skills/accessibility/SKILL.md        | 145 +++++++++++
 .claude/skills/address-pr-comments/SKILL.md  | 141 +++++++++++
 .claude/skills/audit-tickets/SKILL.md        | 117 +++++++++
 .claude/skills/e2e-testing/SKILL.md          | 120 ++++++++++
 .claude/skills/list-skills/SKILL.md          |  41 ++++
 .claude/skills/open-source/SKILL.md          |  48 ++++
 .claude/skills/project-conventions/SKILL.md  |  89 +++++++
 .claude/skills/react-patterns/SKILL.md       | 125 ++++++++++
 .claude/skills/review/SKILL.md               |  88 +++++++
 .claude/skills/tangle-domain/SKILL.md        | 151 ++++++++++++
 .claude/skills/tanstack-query/SKILL.md       | 162 +++++++++++++
 .claude/skills/tanstack-router/SKILL.md      | 177 ++++++++++++++
 .claude/skills/typescript-standards/SKILL.md |  49 ++++
 .claude/skills/ui-primitives/SKILL.md        |  67 ++++++
 .claude/skills/validate/SKILL.md             |  29 +++
 .claude/skills/vitest-testing/SKILL.md       | 239 +++++++++++++++++++
 16 files changed, 1788 insertions(+)
 create mode 100644 .claude/skills/accessibility/SKILL.md
 create mode 100644 .claude/skills/address-pr-comments/SKILL.md
 create mode 100644 .claude/skills/audit-tickets/SKILL.md
 create mode 100644 .claude/skills/e2e-testing/SKILL.md
 create mode 100644 .claude/skills/list-skills/SKILL.md
 create mode 100644 .claude/skills/open-source/SKILL.md
 create mode 100644 .claude/skills/project-conventions/SKILL.md
 create mode 100644 .claude/skills/react-patterns/SKILL.md
 create mode 100644 .claude/skills/review/SKILL.md
 create mode 100644 .claude/skills/tangle-domain/SKILL.md
 create mode 100644 .claude/skills/tanstack-query/SKILL.md
 create mode 100644 .claude/skills/tanstack-router/SKILL.md
 create mode 100644 .claude/skills/typescript-standards/SKILL.md
 create mode 100644 .claude/skills/ui-primitives/SKILL.md
 create mode 100644 .claude/skills/validate/SKILL.md
 create mode 100644 .claude/skills/vitest-testing/SKILL.md

diff --git a/.claude/skills/accessibility/SKILL.md b/.claude/skills/accessibility/SKILL.md
new file mode 100644
index 000000000..6b30fa13a
--- /dev/null
+++ b/.claude/skills/accessibility/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: accessibility
+description: Accessibility patterns and requirements for this project. Use when creating interactive components, forms, dialogs, or any user-facing UI.
+---
+
+# Accessibility Patterns
+
+This project builds on **shadcn/ui** primitives which provide strong built-in a11y. Follow these patterns to maintain that standard.
+
+## ARIA Labels
+
+All interactive elements without visible text must have an `aria-label`:
+
+```typescript
+// Icon buttons
+<Button variant="ghost" aria-label="Home">
+  <Icon name="Home" />
+</Button>
+
+// Folder toggles
+<div role="button" aria-expanded={isOpen} aria-label={`Folder: ${folder.name}`}>
+```
+
+## Form Accessibility
+
+Link inputs to labels and error messages:
+
+```typescript
+<Input
+  id={id}
+  aria-invalid={!!error}
+  aria-describedby={`${id}-hint`}
+/>
+{!!error && <Text tone="critical">{error.join("\n")}</Text>}
+<div id={`${id}-hint`}>{hint}</div>
+```
+
+Use the shadcn/ui `Label` component for proper form associations.
+
+## Keyboard Navigation
+
+### Required keyboard support for custom interactive elements:
+
+- **Enter/Space**: Activate buttons and toggles
+- **Escape**: Close dialogs, cancel editing, deselect
+- **Tab**: Move focus between interactive elements
+
+```typescript
+// The Input component has built-in onEnter and onEscape props
+<Input onEnter={save} onEscape={cancel} />
+
+// For non-Input elements, handle manually
+onKeyDown={(e) => {
+  if (e.key === "Enter" && !e.shiftKey) {
+    e.preventDefault();
+    save();
+  } else if (e.key === "Escape") {
+    e.preventDefault();
+    cancel();
+  }
+}
+```
+
+### Non-button clickable elements need `role="button"` and `tabIndex={0}`:
+
+```typescript
+<div role="button" tabIndex={0} title="Click to edit">
+  {content}
+</div>
+```
+
+### Dialogs must prevent keyboard shortcuts from leaking to the canvas:
+
+The dialog component already handles this — use `preventKeyboardPropagation` prop when needed. This stops Ctrl+A, Ctrl+C, Ctrl+V, Tab, Enter, and Escape from reaching React Flow.
+
+## Screen Reader Support
+
+Use `sr-only` class for visually hidden but screen-reader-accessible text:
+
+```typescript
+// Close buttons with only an icon
+<DialogClose>
+  <Cross2Icon />
+  <span className="sr-only">Close</span>
+</DialogClose>
+
+// Command palette title
+<DialogHeader className="sr-only">
+  <DialogTitle>{title}</DialogTitle>
+  <DialogDescription>{description}</DialogDescription>
+</DialogHeader>
+```
+
+## Semantic HTML
+
+Use proper semantic elements and ARIA roles:
+
+```typescript
+// Navigation
+<nav aria-label="breadcrumb">
+
+// Current page in breadcrumb
+<span role="link" aria-disabled="true" aria-current="page">{children}</span>
+
+// Decorative separators
+<li role="presentation" aria-hidden="true">
+
+// Alerts
+<div role="alert">
+```
+
+## Focus Styling
+
+All focusable elements must use the project's focus-visible ring pattern:
+
+```
+focus-visible:ring-ring/50 focus-visible:ring-[3px] focus-visible:border-ring
+```
+
+Do not remove `outline-none` without replacing it with a visible focus indicator.
+
+## UI Primitives A11y
+
+The project's primitives already accept `AriaAttributes`:
+
+- `BlockStack` and `InlineStack` accept all ARIA props
+- `Text` accepts `role` and ARIA props
+- `Button` has built-in focus-visible and disabled states
+- `Input` supports `aria-invalid`, `onEnter`, `onEscape`
+- All shadcn/ui components (Dialog, Select, Checkbox, Switch, Tabs) handle focus trapping and keyboard navigation automatically
+
+## React Flow Considerations
+
+The pipeline editor has specific a11y needs:
+
+- **Handles**: Support click selection and Escape to deselect
+- **Task nodes**: Labels are interactive with visual feedback
+- **Folders in sidebar**: Use `role="button"` with `aria-expanded`
+- **Canvas keyboard shortcuts**: Must not interfere with dialog/modal focus
+
+When adding new interactive elements to the flow canvas, ensure they:
+
+1. Are keyboard accessible
+2. Have appropriate ARIA labels
+3. Don't capture keyboard events that should reach parent containers
diff --git a/.claude/skills/address-pr-comments/SKILL.md b/.claude/skills/address-pr-comments/SKILL.md
new file mode 100644
index 000000000..d8b66e79c
--- /dev/null
+++ b/.claude/skills/address-pr-comments/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: address-pr-comments
+description: Find the PR for the current branch, read review comments, and address them — either by fixing the code or pushing back with a reply. Use when the user wants to handle PR feedback.
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Bash(git *), Bash(gt *), Read, Edit, Write, Grep, Glob, Agent
+---
+
+# Address PR Comments
+
+Check the current branch for an open PR, read all unresolved review comments, and let the user pick which ones to address.
+
+## Step 1: Find the PR
+
+```bash
+gh pr view --json number,title,url,state --jq '{number, title, url, state}'
+```
+
+If no PR exists for the current branch, tell the user and stop.
+
+Also determine the current GitHub user:
+
+```bash
+gh api user --jq '.login'
+```
+
+## Step 2: Fetch review comments
+
+Get all review comments (not general PR comments):
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate --jq '.[] | {id, path, line, body, user: .user.login, created_at, in_reply_to_id, diff_hunk}'
+```
+
+## Step 3: Filter to actionable comments
+
+Build a thread map by grouping comments using `in_reply_to_id`. For each top-level comment thread:
+
+**Skip the thread if ANY of these are true:**
+
+- The thread is already resolved
+- The top-level comment was made by the current user
+- The top-level comment was made by a bot (dependabot, github-actions, etc.)
+- The comment is a pure approval with no actionable feedback
+- **The current user (or PR author) has already replied** in the thread — this means it was already addressed in a previous run or manually. Check if any reply in the thread was authored by the current GitHub user.
+
+This ensures running the command again won't double-reply to already-addressed comments.
+
+## Step 4: Analyze comments and present for selection
+
+Before presenting comments to the user, **read the relevant code and think critically about each comment**. Determine whether the suggestion is correct, already addressed, or a bad idea. Form a proposed action for each.
+
+Use the AskUserQuestion tool to show a **multi-select list** of all remaining unresolved, unaddressed comments. Each option should show:
+
+- The reviewer's username
+- The file path and line number
+- A truncated preview of the comment (first ~80 characters)
+- **Your proposed action** — what you plan to do (e.g., "Will fix: change X to Y", "Will push back: current approach is better because...", "Will answer: explain how X works")
+
+Example options:
+
+- `[reviewer] file.ts:42 — "Fix this typo..." → Will fix: rename varName to variableName`
+- `[reviewer] other.ts:10 — "This should use..." → Will push back: current pattern is more performant here`
+- `[reviewer] types.ts:5 — "Why not use...?" → Will answer: explain the tradeoff`
+
+The user picks which comments they want to address. Only proceed with the selected ones.
+
+If there are no actionable comments, tell the user everything has been addressed and stop.
+
+## Step 5: Address each selected comment
+
+**Do not blindly agree with every comment.** Critically evaluate each suggestion against the codebase, existing patterns, and correctness. If a suggestion would make the code worse, introduce inconsistency, or is factually wrong — push back respectfully. The reviewer is a collaborator, not an authority to obey unconditionally.
+
+For each selected comment, read the relevant file and surrounding context, then decide:
+
+### If the suggestion is correct and actionable:
+
+1. Make the code change
+2. Reply to the comment confirming the fix:
+
+```markdown
+Fixed — <brief description of what was changed>.
+```
+
+### If the suggestion is already addressed:
+
+Reply explaining that it's already handled:
+
+```markdown
+This is already handled — <explanation with file path/line reference>.
+```
+
+### If the suggestion is incorrect or not applicable:
+
+Reply respectfully pushing back:
+
+```markdown
+I think the current approach is better here because <reasoning>. <Optional: offer an alternative compromise>.
+```
+
+### If the comment is a question (not a change request):
+
+Reply with the answer:
+
+```markdown
+<Answer the question with relevant context/file references>.
+```
+
+## Step 6: Post replies
+
+For each comment, post the reply:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies -f body="<reply>"
+```
+
+## Step 7: Stage and commit fixes
+
+If any code changes were made:
+
+1. Stage only the files that were modified to address comments
+2. Create a commit with a message like: `address pr feedback`
+3. Do NOT push — tell the user the changes are committed and ready to push
+
+## Step 8: Show summary
+
+After all comments are addressed, show a summary table with columns:
+
+| #   | File | Comment | Action |
+| --- | ---- | ------- | ------ |
+
+Where **Action** clearly states what was done: "Fixed — ...", "Pushed back — ...", "Answered — ...", or "Already handled — ...".
+
+## Important
+
+- Always read the full file context before deciding how to address a comment
+- **Think critically** — do not default to agreeing. Push back when the suggestion is wrong, harmful, or inconsistent with the codebase
+- Never dismiss feedback rudely — be respectful even when pushing back
+- If a comment requires a large refactor or is out of scope, say so and suggest a follow-up issue
+- Group related comments that touch the same code — address them together
+- If unsure about a comment's intent, ask the user before responding
+- Show the user what you plan to reply before posting, so they can adjust
diff --git a/.claude/skills/audit-tickets/SKILL.md b/.claude/skills/audit-tickets/SKILL.md
new file mode 100644
index 000000000..1d7ca5888
--- /dev/null
+++ b/.claude/skills/audit-tickets/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: audit-tickets
+description: Audit open GitHub issues against the codebase to find tickets that have already been implemented. Use when the user wants to triage, audit, or clean up GitHub issues.
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Read, Grep, Glob, Agent
+---
+
+# Audit GitHub Tickets
+
+Scan open GitHub issues and check whether each one has already been addressed in the codebase. Post a comment on tickets that appear complete.
+
+## Arguments
+
+The user may provide:
+
+- A repo name (e.g., `TangleML/tangle-ui`, `TangleML/tangle`). If not specified, audit **both** `TangleML/tangle-ui` and `TangleML/tangle`.
+- A limit (e.g., `--limit 20`). Default: all open issues.
+- Specific issue numbers to audit (e.g., `#1641 #575`).
+
+## Process
+
+### Step 1: Fetch open issues
+
+```bash
+gh issue list -R <repo> --state open --limit 100 --json number,title,labels,body,author,assignees,comments
+```
+
+### Step 2: Filter candidates
+
+Skip issues that are:
+
+- **Epics** (title contains "epic" or "[Epic]")
+- **Design/brainstorm** issues (title starts with "design:" or "Brainstorm:")
+- **Issues created in the current session** (issues you just created in this conversation)
+- **Recently audited** — issues that already have a comment containing `:robot: This is an AI-generated audit` posted within the last 14 days. Check comments when fetching issues and skip any that match.
+
+Audit **everything else**, including feature requests and vague tickets. The goal is to close as many tickets as possible.
+
+### Step 3: Verify each candidate against the codebase
+
+For each candidate issue, use the Explore agent to search the codebase:
+
+- Search for the specific files, components, functions, or patterns described in the issue
+- Read the relevant code to confirm the feature/fix exists
+- Determine one of these statuses:
+  - **Done** — The described feature/fix is fully implemented
+  - **Partial** — Some aspects are done, others remain
+  - **Open** — Not implemented, clear what needs to be done
+  - **Vague** — Cannot determine if implemented because the issue lacks clear acceptance criteria or sufficient detail
+
+Be thorough but efficient. Use targeted searches (Grep/Glob) for quick checks, and Explore agents for deeper investigation when needed. Run multiple checks in parallel where possible.
+
+### Step 4: Report findings
+
+Present a summary table to the user:
+
+| Issue | Title | Status | Evidence |
+| ----- | ----- | ------ | -------- |
+
+Group by status: Done first, then Partial, then Vague, then Open.
+
+### Step 5: Post comments (with user approval)
+
+Ask the user which issues they'd like to comment on. Then for each approved issue:
+
+1. Look up the author and any assignees/commenters on the issue
+2. Post a comment using the appropriate template based on status:
+
+**For Done issues:**
+
+```markdown
+> :robot: This is an AI-generated audit of this ticket.
+
+@<author> [and @<assignees/commenters>] — What is the status of this issue? It appears to already be complete.
+
+<Evidence from the codebase with specific file paths>
+
+Can this be closed?
+```
+
+**For Vague issues (cannot determine implementation status):**
+
+```markdown
+> :robot: This is an AI-generated audit of this ticket.
+
+@<author> [and @<assignees/commenters>] — This ticket doesn't have enough detail to determine whether it's been addressed. Could you add more context — specific acceptance criteria, expected behavior, or details on what "done" looks like? Otherwise, can this be closed?
+```
+
+**For Partial issues:**
+
+```markdown
+> :robot: This is an AI-generated audit of this ticket.
+
+@<author> [and @<assignees/commenters>] — This issue appears to be partially addressed. Here's what we found:
+
+**Implemented:**
+<what's done, with file paths>
+
+**Still missing:**
+<what remains>
+
+Can the scope be updated, or should this be closed and a new issue opened for the remaining work?
+```
+
+## Codebase locations
+
+- **Frontend (tangle-ui):** `/Users/mattbeaulne/src/github.com/Shopify/pipeline-studio-app`
+- **Backend (tangle):** `/Users/mattbeaulne/src/github.com/Shopify/oasis-backend`
+
+## Important
+
+- Never close issues directly — always comment and ask
+- Always prefix comments with the AI audit disclaimer
+- Ping the issue author and any assignees/commenters
+- Include specific file paths as evidence
+- For "Partial" issues, clearly state what's done and what's remaining
+- Do not audit issues that were just created in the current conversation
diff --git a/.claude/skills/e2e-testing/SKILL.md b/.claude/skills/e2e-testing/SKILL.md
new file mode 100644
index 000000000..6e1eb601a
--- /dev/null
+++ b/.claude/skills/e2e-testing/SKILL.md
@@ -0,0 +1,120 @@
+---
+name: e2e-testing
+description: Playwright E2E testing best practices for this project. Use when writing, modifying, or reviewing E2E tests.
+---
+
+# E2E Testing Best Practices (Playwright)
+
+## Setup
+
+- Use Playwright helpers from `tests/e2e/helpers.ts`
+- Use `data-testid` attributes for stable selectors
+- Write descriptive test names that explain user behavior
+- Ensure tests are isolated and can run independently
+
+## Never Use Hard-Coded Timeouts
+
+```typescript
+// Bad
+await element.click();
+await page.waitForTimeout(200);
+
+// Good
+await element.click();
+await expect(otherElement).toBeVisible();
+```
+
+## Use Playwright's Auto-Waiting
+
+```typescript
+// Bad
+if (await element.isVisible()) {
+  await element.click();
+}
+
+// Good
+await expect(element).toBeVisible();
+await element.click();
+```
+
+## Never Use Non-Null Assertions
+
+```typescript
+// Bad
+const box = await element.boundingBox();
+const x = box!.x;
+
+// Good
+const box = await element.boundingBox();
+if (!box) {
+  throw new Error("Unable to locate element bounding box");
+}
+const x = box.x;
+```
+
+## Don't Await Locators (They're Lazy)
+
+```typescript
+// Bad
+const button = await page.getByTestId("submit");
+
+// Good
+const button = page.getByTestId("submit");
+await expect(button).toBeVisible();
+```
+
+## Use Consistent Assertion Patterns
+
+```typescript
+// Bad
+expect(await element).toHaveText("text");
+expect(await element.isVisible()).toBe(true);
+
+// Good
+await expect(element).toHaveText("text");
+await expect(element).toBeVisible();
+```
+
+## Prefer Semantic Selectors
+
+Priority order:
+
+1. `getByRole()` - Best for accessibility
+2. `getByTestId()` - Best for test stability (preferred for this app)
+3. `getByText()` - Good for static content
+4. `locator()` with data attributes - When above don't work
+5. CSS selectors - Last resort
+
+## Test Isolation
+
+- Each test should set up its own state
+- Don't depend on test execution order (unless using serial mode intentionally)
+- Clean up after tests in `afterEach` or `afterAll`
+
+## Helper Functions
+
+- Leverage existing helpers from `tests/e2e/helpers.ts`
+- Create new helpers for repeated workflows
+- Keep helpers focused and reusable
+
+## Add Meaningful Error Context
+
+```typescript
+// Okay
+await expect(element).toBeVisible();
+
+// Better
+await expect(element, "Component should appear after loading").toBeVisible();
+```
+
+## Test User Behavior, Not Implementation
+
+```typescript
+// Bad - implementation detail
+await expect(button).toHaveClass("bg-blue-500");
+
+// Good - user-visible behavior
+await expect(button).toBeVisible();
+await expect(button).toBeEnabled();
+await expect(button).toHaveText("Submit");
+```
diff --git a/.claude/skills/list-skills/SKILL.md b/.claude/skills/list-skills/SKILL.md
new file mode 100644
index 000000000..8692244a1
--- /dev/null
+++ b/.claude/skills/list-skills/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: list-skills
+description: List all available custom slash commands and skills. Use when the user asks what commands are available or wants to see all skills.
+disable-model-invocation: true
+allowed-tools: Bash(find *), Read, Glob, Grep
+---
+
+# List Skills
+
+List all custom skills defined in this project.
+
+## Process
+
+1. Find all skill files:
+
+```bash
+find .claude/skills -name 'SKILL.md' -type f
+```
+
+2. For each skill, extract:
+   - **Name** from the `name:` frontmatter field
+   - **Description** from the `description:` frontmatter field
+   - **Type**: If `disable-model-invocation: true` is set, the skill is a **slash command** (user-invocable via `/name`). Otherwise it's an **auto-triggered** skill that fires automatically based on context.
+
+3. Present the results in two groups:
+
+### Slash Commands
+
+These are invoked manually by typing `/<name>`:
+
+| Command | Description |
+| ------- | ----------- |
+
+### Auto-Triggered Skills
+
+These activate automatically when relevant to the task:
+
+| Skill | Description |
+| ----- | ----------- |
+
+Sort alphabetically within each group.
diff --git a/.claude/skills/open-source/SKILL.md b/.claude/skills/open-source/SKILL.md
new file mode 100644
index 000000000..6cb21fc43
--- /dev/null
+++ b/.claude/skills/open-source/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: open-source
+description: Open source guidelines for Tangle-UI. Use when writing user-facing text, UI copy, error messages, banners, documentation, or any content visible to users.
+---
+
+# Open Source Guidelines
+
+Tangle-UI is an **open source project**. All code, UI copy, and documentation must be vendor-neutral and usable by anyone — not just Shopify employees.
+
+## Do Not Include
+
+- **Company-specific references**: No mentions of Shopify, internal teams, internal tools, or internal infrastructure
+- **Internal URLs**: No links to internal dashboards, wikis, Slack channels, or internal services
+- **Infrastructure assumptions**: No references to specific cloud providers, internal clusters, or internal deployment targets as if they're the only option
+- **Internal warnings or notices**: No banners, alerts, or messages about internal systems, outages, or company-specific policies
+- **Employee-specific language**: No "talk to the platform team", "file a ticket in [internal tool]", or similar
+
+## What to Do Instead
+
+- Write **generic, vendor-neutral** copy that applies to any user
+- Reference **configurable settings** rather than hardcoded internal values (e.g., backend URL is configurable, not pointed at an internal endpoint)
+- Use **general cloud/ML terminology** (e.g., "your backend" not "the Shopify backend")
+- For infrastructure-specific behavior, make it **configurable** via environment variables or settings, not hardcoded
+- Error messages should guide users to **general troubleshooting steps**, not internal escalation paths
+
+## Examples
+
+```
+// Bad — Shopify-specific
+"Contact the ML Platform team on #ml-platform-support for help."
+"This pipeline requires access to the Shopify GCP project."
+"Warning: Shopify infrastructure maintenance scheduled."
+
+// Good — vendor-neutral
+"Check your backend connection settings."
+"This pipeline requires a configured backend endpoint."
+"Unable to connect to the backend. Verify your settings."
+```
+
+## When Internal Context Is Needed
+
+If Shopify-specific configuration or documentation is needed, it belongs in:
+
+- **Environment variables** (configured at deployment, not in code)
+- **External documentation** (internal wikis, not in-app)
+- **The backend** (server-side configuration, not frontend hardcoding)
+
+Never put it in the frontend source code, UI copy, or committed configuration files.
diff --git a/.claude/skills/project-conventions/SKILL.md b/.claude/skills/project-conventions/SKILL.md
new file mode 100644
index 000000000..18a2a3da1
--- /dev/null
+++ b/.claude/skills/project-conventions/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: project-conventions
+description: Project conventions for Tangle-UI including file structure, imports, code quality, and general rules. Use when writing new code, creating files, or organizing imports.
+---
+
+# Project Conventions
+
+## Project Overview
+
+React + TypeScript application for building and running ML pipelines using drag and drop. Uses Vite, TailwindCSS v4, shadcn/ui, React Flow, and Monaco Editor.
+
+## File Structure & Imports
+
+- Use absolute imports with `@/` prefix for src directory
+- Follow existing folder structure:
+  - `src/components/` for all React components
+  - `src/hooks/` for custom hooks
+  - `src/types/` for TypeScript definitions
+  - `src/utils/` for utility functions
+  - `src/services/` for API and business logic
+- **Import order**: external packages -> internal modules -> relative imports
+- Use simple-import-sort rules (already configured in ESLint)
+- Do not use barrel exports
+
+## Code Quality
+
+- Follow ESLint rules (configured in eslint.config.js)
+- Use Prettier for formatting
+- Write tests using Vitest for unit tests, Playwright for E2E
+- Use descriptive variable and function names
+- Add JSDoc comments for complex functions
+- Prefer early returns to reduce nesting
+
+## Comments & Documentation
+
+- Use JSDoc for public APIs
+- Add comments for complex business logic
+- **Explain "why" not "what" in comments**
+- Keep comments up to date with code changes
+- Avoid writing redundant comments for functions and variables that are self-explanatory
+
+## Error Handling
+
+- Use proper error boundaries
+- Handle async errors with try/catch
+- Use toast notifications for user-facing errors
+- Log errors appropriately
+
+## React Flow Specific
+
+- Use `@xyflow/react` for flow diagrams
+- Follow existing node types and edge patterns
+- Keep flow state management consistent with existing patterns
+- Use proper node and edge typing
+
+## Specific Project Patterns
+
+- Use Monaco Editor for code editing features
+- Use localforage for client-side storage
+- Follow existing authentication patterns
+- Use proper task node and pipeline handling patterns
+- Follow the existing component library structure
+- **Do not modify componentSpec structure** without express permission
+
+## Don't Do
+
+- Don't use CSS-in-JS or styled-components
+- Don't use inline styling (`style={styles}`) except where strictly necessary
+- Don't use relative imports for `@/components/ui`
+- Don't create new global state without good reason
+- Don't bypass existing abstractions without discussion
+
+## Planning & Documentation
+
+When asked to create planning documents, architecture decisions, or investigation notes:
+
+- **Always save to `.local/`** - This directory is gitignored for local-only files
+- Use descriptive filenames: `.local/feature-name-planning.md`, `.local/bug-investigation.md`
+
+## Optional "While We're Here" Cleanup
+
+After completing a code generation task, scan the surrounding area for small, low-risk improvements. **Only offer** if ALL conditions are met:
+
+1. **Small scope**: Affects < 30 lines of code
+2. **Low risk**: Purely cosmetic or minor refactoring (not logic changes)
+3. **Same file**: In a file you already modified
+4. **Clear benefit**: Improves readability, removes dead code, or fixes obvious issues
+
+Don't be naggy — only offer once per task, and only if genuinely worthwhile.
diff --git a/.claude/skills/react-patterns/SKILL.md b/.claude/skills/react-patterns/SKILL.md
new file mode 100644
index 000000000..b9cd37911
--- /dev/null
+++ b/.claude/skills/react-patterns/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: react-patterns
+description: React and React Compiler patterns for this project. Use when writing React components, hooks, providers, or working with React Compiler compatibility.
+---
+
+# React Patterns
+
+## Core Rules
+
+- Use functional components with hooks exclusively (no class components)
+- Use proper dependency arrays in useEffect
+- Follow the existing component structure
+- Use React 19 features and patterns
+- **Import modules from React**: `import module from react`. Do not use inline `React.[module]`
+
+## Component Structure
+
+```typescript
+// ComponentName/ComponentName.tsx — import directly, no index.ts barrel
+interface ComponentNameProps {
+  // props
+}
+
+export const ComponentName = ({ }: ComponentNameProps) => {
+  // component logic
+  return (
+    // JSX
+  );
+};
+```
+
+## Custom Hooks
+
+- Prefix with `use`
+- Return objects for multiple values, not arrays
+- Use proper TypeScript return types
+- Follow existing patterns in `src/hooks/`
+
+## Provider Pattern
+
+```typescript
+const Context = createContext<ContextType | null>(null);
+
+export const Provider = ({ children }: { children: ReactNode }) => {
+  // provider logic
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+};
+
+export const useContext = () => {
+  const context = useContext(Context);
+  if (!context) throw new Error('useContext must be used within Provider');
+  return context;
+};
+```
+
+## State Management
+
+- Use Tanstack Query for server state
+- Use Tanstack Router for routing
+- Use React hooks for local component state
+- Use Context providers for app-wide state (see existing providers in `src/providers/`)
+- **Use `useRequiredContext`** to simplify context usage and avoid null checks
+
+## React Compiler
+
+This project uses the React Compiler for automatic memoization. Files/directories are incrementally adopted in `react-compiler.config.js`.
+
+### Writing React Compiler Compatible Code
+
+**For new files**, ensure they follow React Compiler rules from the start:
+
+1. **Don't mutate values during render**
+
+   ```typescript
+   // Bad - mutating during render
+   const items = props.items;
+   items.push(newItem);
+
+   // Good - create new reference
+   const items = [...props.items, newItem];
+   ```
+
+2. **Don't read/write refs during render**
+
+   ```typescript
+   // Bad - reading ref during render
+   const value = myRef.current;
+   return <div>{value}</div>;
+
+   // Good - read refs in effects or callbacks
+   useEffect(() => {
+     const value = myRef.current;
+   }, []);
+   ```
+
+3. **Follow Rules of Hooks strictly** - no conditional hooks, no hooks in loops, proper dependency arrays
+
+4. **Avoid patterns the compiler can't optimize**
+   - Don't spread props with `{...props}` unnecessarily
+   - Avoid dynamic property access on objects when possible
+   - Keep component logic predictable
+
+### Adding Files to React Compiler
+
+When a file is added to `react-compiler.config.js`:
+
+- Remove unnecessary `useCallback` and `useMemo` (compiler handles this)
+- Verify no compiler violations with `npm run validate`
+- Test the component still works correctly
+- **Consolidate entries by folder** when all files in a directory are compiler-enabled (e.g., use `/path/to/folder` instead of listing each file individually)
+
+### React Compiler Config Structure
+
+Files are organized by cleanup effort in `react-compiler.config.js`:
+
+- Top section: Already enabled directories/files
+- Middle: Ready to enable (0 useCallback/useMemo)
+- Bottom (commented): Need cleanup before enabling
+
+## Performance
+
+- **Do not use `useMemo`, `useCallback`, or `memo` manually** — the React Compiler handles memoization automatically
+- If you encounter existing `useMemo`/`useCallback`/`memo` in a file, remove them when the file is enabled in `react-compiler.config.js`
+- Lazy load heavy components when possible
+- Follow existing patterns for optimization
diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md
new file mode 100644
index 000000000..e30ef6fe5
--- /dev/null
+++ b/.claude/skills/review/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: review
+description: Code review of current PR/commit changes against project coding standards. Use when the user asks for a code review or mentions reviewing changes.
+disable-model-invocation: true
+allowed-tools: Bash(git *), Bash(gt *), Read, Grep, Glob
+---
+
+# Code Review
+
+Review the current commit (HEAD) against project coding standards. This team uses **Graphite** for stacked PRs — each commit is a PR in a stack.
+
+## Review Process
+
+1. **Default scope**: Review the last commit (`git show HEAD`). Each commit = one Graphite PR.
+2. **Only review changed code**. Do not flag pre-existing issues unless they directly cause problems with the new changes.
+3. **Source of truth**: Use `git show HEAD --stat` to see changed files, then `git show HEAD` for the diff. Do NOT use `git diff main...HEAD` as this shows all commits in the stack, not just the current one.
+4. **Read files**: Always read the full files being reviewed to understand context, not just the diff.
+
+## What to Check
+
+Review changed code for violations, prioritizing:
+
+### High Priority
+
+- Unsafe type casting (`as`) - suggest type guards instead
+- Potential runtime errors (undefined access, null checks)
+- Missing error handling
+- Security concerns
+- Incorrect use of React hooks (missing deps, unnecessary async)
+- React Compiler violations (mutating during render, reading refs during render)
+
+### Medium Priority
+
+- Not using UI primitives (`BlockStack`, `InlineStack`, `Text`, `Icon`)
+- Import order violations
+- Duplicated logic that should be extracted
+
+### Low Priority
+
+- Redundant code (unnecessary null coalescing, etc.)
+- Minor style inconsistencies
+- Unused props or parameters
+
+## Review Output Format
+
+Present findings in this format:
+
+```markdown
+## Issues Found
+
+### 1. **[Issue Title]** - [File:Line]
+
+[Code snippet showing the problem]
+**Why**: [Brief explanation]
+**Fix**: [Suggested solution]
+
+---
+
+## What's Good
+
+- [Positive observations about the code]
+- Note if file was added to `react-compiler.config.js` (React Compiler enabled)
+
+---
+
+## Summary Table
+
+| Issue | Severity        | Location  |
+| ----- | --------------- | --------- |
+| ...   | High/Medium/Low | file:line |
+```
+
+## Review Principles
+
+- **Be specific**: Include file paths and line numbers
+- **Be actionable**: Provide concrete fixes, not vague suggestions
+- **Be proportional**: Don't over-engineer simple code
+- **Acknowledge good patterns**: Note when code follows best practices
+- **Don't nitpick**: Focus on meaningful improvements
+- **Offer to fix**: After review, ask "Want me to fix these?"
+
+## What NOT to Do
+
+- Don't review unchanged code (unless it causes issues with new code)
+- Don't suggest rewrites of working code just for style preferences
+- Don't flag issues that are already present in the codebase (pre-existing)
+- Don't recommend adding complexity without clear benefit
+- Don't suggest patterns that conflict with existing codebase conventions
diff --git a/.claude/skills/tangle-domain/SKILL.md b/.claude/skills/tangle-domain/SKILL.md
new file mode 100644
index 000000000..34db3ca1c
--- /dev/null
+++ b/.claude/skills/tangle-domain/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: tangle-domain
+description: Domain terminology and concepts for Tangle. Use whenever discussing, naming, or working with pipelines, runs, components, tasks, inputs, outputs, executions, or any Tangle domain concepts.
+---
+
+# Tangle Domain Terminology
+
+This application is called **Tangle** (or **Tangle-UI** for the frontend). Never refer to it as "Pipeline Studio" — that is a legacy name.
+
+- **tangle-ui**: This frontend repo (React + TypeScript)
+- **tangle**: The backend orchestration system
+- Together they form the **Tangle platform** for building and running ML pipelines
+
+## Core Concepts
+
+### Pipeline
+
+A **pipeline** is a directed acyclic graph (DAG) of components connected to produce a workflow. Represented as a `ComponentSpec` with a `GraphImplementation`. A pipeline defines:
+
+- **Inputs**: Data entry points (graph-level inputs)
+- **Outputs**: Data exit points (graph-level outputs)
+- **Tasks**: Configured component instances
+- **Connections**: Edges linking outputs to inputs
+
+### Component
+
+A **component** is a reusable unit of computation defined by a `ComponentSpec`. Every component has:
+
+- `name`, `description`
+- `inputs`: Array of `InputSpec`
+- `outputs`: Array of `OutputSpec`
+- `implementation`: Either **container** (Docker) or **graph** (subgraph)
+- `metadata`: Annotations, author, etc.
+
+### Component Spec (ComponentSpec)
+
+The canonical data structure that fully describes a component's interface, implementation, and metadata. Compatible with Google Cloud Vertex AI Pipelines and Kubeflow v1 formats. Stored/shared as YAML (`component.yaml`). The TypeScript type definitions live in `componentSpec.ts`. **Do not modify the ComponentSpec structure** without express permission.
+
+### Task
+
+A **task** is a configured instance of a component within a pipeline. A `TaskSpec` includes:
+
+- `componentRef`: Reference to the component definition
+- `arguments`: Configured input values (literals, graph input references, upstream task output references, or secrets)
+- `isEnabled`: Optional conditional execution predicate
+- `executionOptions`: Retry and caching strategies
+- `annotations`: Metadata
+
+### Task Node
+
+The visual representation of a task on the canvas. Has position, handles, and interaction callbacks. Node ID format: `task_{taskId}`.
+
+### Flex Node
+
+A **flex node** is a freeform annotation element on the canvas (like a sticky note). It has a title, content, customizable colors, and font sizes. Flex nodes are purely decorative — they do not participate in task execution or data flow. Stored in ComponentSpec metadata annotations under the `"flex-nodes"` key. They can be locked to prevent accidental edits.
+
+### Ghost Node
+
+A **ghost node** is a temporary, semi-transparent preview node that appears while the user is dragging to create a connection (with Meta key held). It shows what Input/Output node would be created if the user drops at that position. Ghost nodes are never persisted — they exist only during the drag interaction.
+
+### Input vs Input Component
+
+These are different things:
+
+- **Input** (`InputSpec`): A parameter definition on a component — has name, type, description, default value, optional flag
+- **Input Component** (Input Node): A visual node on the canvas representing a **graph-level input**. It serves as a data source that feeds into task inputs. Node ID format: `input_{inputName}`
+
+### Output vs Output Component
+
+Same distinction:
+
+- **Output** (`OutputSpec`): A parameter definition on a component — has name, type, description
+- **Output Component** (Output Node): A visual node on the canvas representing a **graph-level output**. It collects data from upstream task outputs. Node ID format: `output_{outputName}`
+
+### Task Type
+
+The `TaskType` union: `"task" | "input" | "output"` — used to distinguish node types on the canvas.
+
+### Subgraph
+
+A task whose component has a `GraphImplementation` instead of a `ContainerImplementation`. This enables nested pipelines. When viewing a subgraph, you navigate into its internal graph structure. Check with `isSubgraph()` from `src/utils/subgraphUtils.ts`.
+
+### Run / Pipeline Run
+
+A **run** is a submitted instance of a pipeline for execution. Each run has:
+
+- `id`: Unique identifier
+- `root_execution_id`: The root execution
+- `pipeline_name`, `pipeline_digest`
+- `status`, `statusCounts`
+- `created_at`, `created_by`
+
+### Execution
+
+An **execution** is a lower-level entity — the execution of a single task within a run. Executions form a tree:
+
+- A run has one **root execution**
+- The root execution branches into **child executions** for each task
+- Subgraph tasks have their own child execution trees
+
+**Run vs Execution**: A run is the top-level container users interact with. Executions are the internal task-level tracking.
+
+**`run_id` vs `execution_id`**: Use `run_id` (the `id` field on `PipelineRunResponse`) for run-level operations — listing, canceling, fetching metadata, and URL routes (`/runs/$id`). Use `execution_id` for task-level operations — fetching execution details, artifacts, logs, and container state (`/api/executions/{id}/...`). A run's `root_execution_id` bridges the two: it points to the root of the execution tree. Child execution IDs are found via `details.child_task_execution_ids[taskId]`.
+
+### Execution Status
+
+`ContainerExecutionStatus`: PENDING, RUNNING, SUCCEEDED, FAILED, etc. Runs aggregate these via `TaskStatusCounts`.
+
+### Edge / Connection
+
+A directed connection in the graph. Three types:
+
+- **Task Output → Task Input**: Data flows between tasks (`TaskOutputArgument`)
+- **Graph Input → Task Input**: Pipeline inputs feed into tasks (`GraphInputArgument`)
+- **Task Output → Graph Output**: Task outputs become pipeline outputs
+
+Edge IDs are generated from source/target handle and input/output names.
+
+### Handle
+
+A connection point on a node where edges attach:
+
+- **Input handles** (target): Left side of task nodes, one per task input. ID: `input_{inputName}`
+- **Output handles** (source): Right side of task nodes, one per task output. ID: `output_{outputName}`
+- **IO node handles**: Input nodes have a source handle; output nodes have a target handle
+
+### Component Library
+
+A hierarchical collection of components organized in folders. Types:
+
+- **Preloaded**: Built-in components
+- **User Libraries**: Custom user components
+- **Remote Libraries**: Fetched from external sources
+- **GitHub Libraries**: Components from GitHub repos
+
+### Annotations
+
+Arbitrary key-value metadata (`Record<string, unknown>`) on components, tasks, inputs, outputs, and graph nodes. Used for canvas position/layout, z-index, visual styling, and custom metadata.
+
+### Secrets
+
+Sensitive values (API keys, credentials) stored securely in the backend and referenced by name in task arguments via `SecretArgument`. Resolved at runtime — never embedded in pipeline definitions or exports.
+
+```typescript
+// SecretArgument structure
+{
+  secret: {
+    name: "my-api-key";
+  }
+}
+```
diff --git a/.claude/skills/tanstack-query/SKILL.md b/.claude/skills/tanstack-query/SKILL.md
new file mode 100644
index 000000000..6a8ac309a
--- /dev/null
+++ b/.claude/skills/tanstack-query/SKILL.md
@@ -0,0 +1,162 @@
+---
+name: tanstack-query
+description: TanStack Query v5 patterns for data fetching, mutations, and cache management. Use when writing queries, mutations, or working with server state.
+---
+
+# TanStack Query Patterns
+
+This project uses TanStack Query v5 for all server state management.
+
+**Prefer `useQuery` hooks over Context providers for server state.** When you need data from the server, first consider whether a custom `useQuery` hook solves the problem. Only reach for a Context provider when you need to share non-query app-wide state (theme, feature flags, backend config). Wrapping query results in Context bypasses TanStack Query's built-in caching and causes unnecessary re-renders.
+
+## Query Key Conventions
+
+Use **hierarchical array-based keys**. For domains with multiple related queries, use a query key factory:
+
+```typescript
+// Query key factory pattern (preferred for grouped queries)
+export const SecretsQueryKeys = {
+  All: () => ["secrets"] as const,
+  Id: (id: string) => ["secrets", id] as const,
+} as const;
+
+// Simple keys for standalone queries
+queryKey: ["pipeline-run", rootExecutionId];
+queryKey: ["execution-details", rootExecutionId];
+queryKey: ["component", "hydrate", componentQueryKey];
+```
+
+## Query Definition
+
+Define queries **inline in custom hooks** — this project does not use the `queryOptions` helper:
+
+```typescript
+export function usePipelineRuns(pipelineName?: string) {
+  return useSuspenseQuery({
+    queryKey: ["pipelineRuns", pipelineName],
+    queryFn: async () => {
+      if (!pipelineName) return [];
+      const res = await fetchPipelineRuns(pipelineName);
+      if (!res) return [];
+      return res.runs;
+    },
+    staleTime: 5 * MINUTES,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+  });
+}
+```
+
+## Suspense Queries
+
+Use `useSuspenseQuery` for components wrapped in `<SuspenseWrapper>` or error boundaries:
+
+```typescript
+export function useHydrateComponentReference(component: ComponentReference) {
+  const { data } = useSuspenseQuery({
+    queryKey: ["component", "hydrate", getComponentQueryKey(component)],
+    staleTime: 1000 * 60 * 60,
+    queryFn: () => hydrateComponentReference(component),
+  });
+  return data;
+}
+```
+
+## Dependent Queries
+
+Chain queries using the `enabled` option:
+
+```typescript
+const { data: rootExecutionId } = useQuery({
+  queryKey: ["pipeline-run-execution-id", id],
+  queryFn: () =>
+    fetchPipelineRun(id, backendUrl).then((res) => res.root_execution_id),
+  enabled: !!id && id.length > 0,
+});
+
+const { data: executionData } = useQuery({
+  enabled: !!rootExecutionId && !!executionDetails,
+  queryKey: ["pipeline-run", rootExecutionId],
+  queryFn: () => fetchData(rootExecutionId),
+});
+```
+
+## Mutation Pattern
+
+All mutations follow this structure — invalidate cache on success, toast on error:
+
+```typescript
+const { mutate, isPending } = useMutation({
+  mutationFn: () => addSecret(secret),
+  onSuccess: () => {
+    void queryClient.invalidateQueries({ queryKey: SecretsQueryKeys.All() });
+    onSuccess();
+  },
+  onError: () => {
+    notify("Failed to add secret", "error");
+  },
+});
+```
+
+Multiple invalidations in a single mutation are fine:
+
+```typescript
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: ["has-component", digest] });
+  queryClient.invalidateQueries({ queryKey: ["componentLibrary", "publishedComponents"] });
+},
+```
+
+## Cache Invalidation Strategy
+
+This project uses **post-mutation invalidation**, not optimistic updates. Do not use `setQueryData` in mutations — invalidate and let the query refetch.
+
+**QueryClient methods used:**
+
+- `queryClient.invalidateQueries()` — primary invalidation
+- `queryClient.fetchQuery()` — direct fetch in non-hook contexts (e.g., class-based libraries)
+- `queryClient.getQueryData()` — cache reading without triggering refetch
+- `queryClient.ensureQueryData()` — fetch-if-not-cached for recursive/dependent data
+
+## Stale Time Guidelines
+
+Match stale time to data volatility:
+
+| Data Type              | Stale Time | Example                                              |
+| ---------------------- | ---------- | ---------------------------------------------------- |
+| Immutable/rare changes | 24 hours   | Pipeline run metadata, component digests             |
+| User profile data      | 30 minutes | User details                                         |
+| Semi-stable data       | 1 hour     | Execution details, component hydration               |
+| Active lists           | 5 minutes  | Pipeline runs, published components, outdated checks |
+| Live/polling data      | 5 seconds  | Logs                                                 |
+| Always fresh           | 0          | User components                                      |
+
+Use time constants from `src/utils/constants.ts`: `ONE_MINUTE_IN_MS`, `MINUTES`, `HOURS`, `TWENTY_FOUR_HOURS_IN_MS`.
+
+## Polling with Dynamic Intervals
+
+Use `refetchInterval` with a function for conditional polling:
+
+```typescript
+refetchInterval: (data) => {
+  if (data instanceof Query) {
+    const { state } = data.state.data || {};
+    if (!state) return false;
+    return isExecutionComplete(stats) ? false : 5000;
+  }
+  return false;
+},
+```
+
+## Error Handling
+
+- Use `.catch(() => undefined)` for controlled fallbacks in queryFn
+- Use `onError` with toast notifications in mutations
+- Create custom error classes for domain-specific errors (e.g., `ComponentHydrationError`)
+
+## File Organization
+
+- **Service functions** (API calls): `src/services/`
+- **Query hooks**: `src/hooks/` or co-located in component directories
+- **Query key factories**: co-located with the feature (e.g., `types.ts` in the feature folder)
+- **Providers using queries**: `src/providers/`
diff --git a/.claude/skills/tanstack-router/SKILL.md b/.claude/skills/tanstack-router/SKILL.md
new file mode 100644
index 000000000..c59b2bb63
--- /dev/null
+++ b/.claude/skills/tanstack-router/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: tanstack-router
+description: TanStack Router patterns for routing, navigation, search params, and layouts. Use when creating routes, navigating, or working with URL state.
+---
+
+# TanStack Router Patterns
+
+This project uses **code-based routing** (not file-based) with TanStack Router v1.
+
+## Route Definitions
+
+All routes are defined in `src/routes/router.ts` using `createRoute` and assembled into a tree with `addChildren`:
+
+```typescript
+const mainLayout = createRoute({
+  id: "main-layout",
+  getParentRoute: () => rootRoute,
+  component: RootLayout,
+});
+
+const indexRoute = createRoute({
+  getParentRoute: () => mainLayout,
+  path: APP_ROUTES.HOME,
+  component: Editor,
+});
+
+// Assemble tree
+const appRouteTree = mainLayout.addChildren([
+  indexRoute,
+  quickStartRoute,
+  settingsRouteTree,
+  editorRoute,
+]);
+```
+
+## Route Path Constants
+
+Use the `APP_ROUTES` constant object for all route paths — never hardcode path strings:
+
+```typescript
+export const APP_ROUTES = {
+  HOME: "/",
+  QUICK_START: "/quick-start",
+  PIPELINE_EDITOR: `${EDITOR_PATH}/$name`,
+  RUN_DETAIL: `${RUNS_BASE_PATH}/$id`,
+  RUNS: RUNS_BASE_PATH,
+  SETTINGS: "/settings",
+} as const;
+```
+
+## Navigation
+
+**useNavigate hook:**
+
+```typescript
+const navigate = useNavigate();
+navigate({ to: `${APP_ROUTES.RUNS}/${runId}` });
+```
+
+**Handle Ctrl/Cmd+Click for new tabs:**
+
+```typescript
+const handleRowClick = (e: MouseEvent<HTMLElement>) => {
+  if (e.ctrlKey || e.metaKey) {
+    window.open(clickThroughUrl, "_blank");
+    return;
+  }
+  navigate({ to: clickThroughUrl });
+};
+```
+
+**Link component with active state:**
+
+```typescript
+import { Link } from "@tanstack/react-router";
+
+<Link
+  to={item.to}
+  replace
+  activeProps={{ className: "is-active" }}
+>
+  {({ isActive }) => (
+    <Button variant="ghost" className={cn("w-full", isActive && "bg-accent")}>
+      <Icon name={item.icon} size="sm" />
+      <Text size="sm">{item.label}</Text>
+    </Button>
+  )}
+</Link>
+```
+
+## Data Fetching
+
+This project uses **TanStack Query for data fetching**, not route loaders. Routes do not define `loader` functions — use query hooks in components instead.
+
+`beforeLoad` is only used for redirects and simple param extraction:
+
+```typescript
+const settingsIndexRoute = createRoute({
+  getParentRoute: () => settingsLayoutRoute,
+  path: "/",
+  beforeLoad: () => {
+    throw redirect({ to: APP_ROUTES.SETTINGS_BACKEND });
+  },
+});
+```
+
+## Search Params
+
+Use `useSearch` with type casting and manual validation (not Zod):
+
+```typescript
+type RunSectionSearch = { page_token?: string; filter?: string };
+const search = useSearch({ strict: false }) as RunSectionSearch;
+const filters = parseFilterParam(search.filter);
+```
+
+For complex search param management, see the `useRunSearchParams` hook in `src/hooks/useRunSearchParams.ts` which provides `setFilter`, `clearFilters`, `hasActiveFilters`, etc.
+
+Validate search params with **type guards**, not Zod:
+
+```typescript
+function isValidAnnotationFilter(value: unknown): value is AnnotationFilter {
+  return (
+    isRecord(value) &&
+    typeof value.key === "string" &&
+    (value.value === undefined || typeof value.value === "string")
+  );
+}
+```
+
+## Route Params
+
+```typescript
+const { id, subgraphExecutionId } = useParams();
+```
+
+## Router Hooks
+
+| Hook                           | Use Case                                          |
+| ------------------------------ | ------------------------------------------------- |
+| `useNavigate()`                | Programmatic navigation                           |
+| `useParams()`                  | Route parameters (`$id`, `$name`)                 |
+| `useSearch({ strict: false })` | Search/query params                               |
+| `useLocation()`                | Current pathname                                  |
+| `useRouter()`                  | Router instance (history, back navigation)        |
+| `useRouterState()`             | Advanced state (resolved location, pending state) |
+
+## Layout Nesting
+
+Layouts use `<Outlet />` for child routes. The root layout (`RootLayout`) wraps providers:
+
+```
+rootRoute
+├── mainLayout (RootLayout: BackendProvider > ComponentSpecProvider > AppMenu + Outlet)
+│   ├── indexRoute
+│   ├── settingsLayoutRoute (SettingsLayout: sidebar + Outlet)
+│   │   ├── settingsBackendRoute
+│   │   └── secretsRouteTree
+│   ├── editorRoute
+│   └── runDetailRoute
+└── Auth callback routes (no layout)
+```
+
+## Router Config
+
+```typescript
+export const router = createRouter({
+  routeTree: rootRouteTree,
+  defaultPreload: "intent",
+  scrollRestoration: true,
+  history,
+  basepath: IS_GITHUB_PAGES ? "" : basepath,
+});
+```
+
+- `defaultPreload: "intent"` — preloads routes on hover/focus
+- `scrollRestoration: true` — restores scroll position on back navigation
diff --git a/.claude/skills/typescript-standards/SKILL.md b/.claude/skills/typescript-standards/SKILL.md
new file mode 100644
index 000000000..d2689f3e9
--- /dev/null
+++ b/.claude/skills/typescript-standards/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: typescript-standards
+description: TypeScript coding standards for this project. Use when writing TypeScript code, defining types, or working with type safety.
+---
+
+# TypeScript Standards
+
+## Core Rules
+
+- Use strict TypeScript with proper typing
+- Prefer explicit types over `any` (only use `any` when absolutely necessary)
+- Use `interface` for object shapes, `type` for unions/primitives
+- Follow existing patterns for type definitions in `src/types/`
+
+## Avoid Unsafe Type Casting
+
+Don't use type assertions (`as`) unless absolutely necessary. Instead prefer:
+
+- Type guards and runtime validation
+- Proper typing from the source
+- Union types and type narrowing
+- Schema validation libraries (e.g., zod) for external data
+
+```typescript
+// Bad
+const something: string = myjson as string;
+
+// Good - use type guards or validate the data
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+```
+
+## API & Data Types
+
+- Use the generated API client in `src/api/`
+- **Prefer domain types**: Use types from `src/utils/componentSpec.ts`, `src/types/`, etc. for core business logic
+- **Use generated API types**: Only use `src/api/types.gen.ts` when directly interfacing with APIs or when domain types don't exist
+- Follow existing service patterns in `src/services/`
+- Use proper error handling with try/catch
+
+## Naming Conventions
+
+- Components: PascalCase
+- Files: PascalCase for components, camelCase for utilities
+- Variables/functions: camelCase
+- Constants: SCREAMING_SNAKE_CASE
+- Types/Interfaces: PascalCase
+- Directories: Follow the existing convention in the surrounding directory. The codebase uses both camelCase and PascalCase for folders — match what's already there
diff --git a/.claude/skills/ui-primitives/SKILL.md b/.claude/skills/ui-primitives/SKILL.md
new file mode 100644
index 000000000..322e3ff44
--- /dev/null
+++ b/.claude/skills/ui-primitives/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: ui-primitives
+description: UI primitive components for this project (BlockStack, InlineStack, Text, Heading, Paragraph, Button, Icon). Use when writing JSX, creating components, or working with layout and typography.
+---
+
+# UI Primitives
+
+Always prefer UI primitives over raw HTML elements.
+
+## Layout
+
+Use `BlockStack` and `InlineStack` from `@/components/ui/layout` instead of `<div className="flex ...">`:
+
+- `BlockStack` = vertical flex (`flex-col`)
+- `InlineStack` = horizontal flex (`flex-row`)
+- Both support `gap`, `align`, `blockAlign` props
+- Use `as` prop for semantic elements: `<BlockStack as="ul">`, `<InlineStack as="li">`
+
+## Typography
+
+All typography components are exported from `@/components/ui/typography`.
+
+**Use `Heading` for headings** instead of raw `<h1-h6>` or `Text as="h*"`:
+
+- `<Heading level={2}>Title</Heading>` — renders `<h2>` with `role="heading"` and `aria-level`
+- Automatically sets `size="md"` + `weight="semibold"` for level 1, `size="sm"` for others
+- Supports `tone`, `size`, `weight`, `font` overrides
+
+**Use `Paragraph` for paragraph text** instead of raw `<p>` or `Text as="p"`:
+
+- `<Paragraph size="sm" tone="subdued">` instead of `<p className="text-sm text-muted">`
+
+**Use `Text` for inline text** (`<span>`, `<dt>`, `<dd>`, etc.):
+
+- `<Text as="dt" weight="semibold">` instead of `<dt className="font-semibold">`
+- Supports: `as`, `size`, `weight`, `tone`, `font` props
+
+## Buttons
+
+Use `Button` from `@/components/ui/button`
+
+## Icons
+
+Use `Icon` from `@/components/ui/icon`
+
+## Styling
+
+- Use shadcn/ui components from `@/components/ui/` for all UI primitives
+- Use TailwindCSS v4 for styling (not CSS modules or styled-components)
+- **Only use inline styling** (`style={...}`) for dynamic/variable CSS values (e.g., `style={{height: h}}`). Never use inline styles for static values — use Tailwind classes instead
+- Use `cn()` utility for conditional classes (from `@/lib/utils`)
+- Prefer composition over prop drilling for complex components
+
+## Suggest Abstractions for Repeated Patterns
+
+When you see similar Tailwind class combinations used multiple times, suggest creating reusable components or utility classes:
+
+- Multiple buttons with similar styling -> Create a Button variant or new component
+- Repeated container/card patterns -> Abstract into reusable Card component
+- Common spacing/layout patterns -> Suggest utility classes or component abstractions
+- Similar form field styling -> Create form field components
+
+## When Raw HTML is Acceptable
+
+- Semantic elements not supported by primitives (e.g., `<dl>`, `<ul>`, `<ol>`, `<table>`)
+- Complex layouts where primitives don't fit
+- Performance-critical sections where abstraction overhead matters
diff --git a/.claude/skills/validate/SKILL.md b/.claude/skills/validate/SKILL.md
new file mode 100644
index 000000000..a5b0570fb
--- /dev/null
+++ b/.claude/skills/validate/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: validate
+description: Run validation and testing commands for the project. Use when the user asks to validate, lint, typecheck, or run tests.
+disable-model-invocation: true
+allowed-tools: Bash(npm run *)
+argument-hint: [test|e2e]
+---
+
+# Validate & Test
+
+Run project validation and testing commands.
+
+## Available Commands
+
+- **`npm run validate`** - Runs format, lint:fix, typecheck, and knip (use before committing)
+- **`npm run validate:test`** - Runs validate + unit tests (full validation)
+- **`npm run test:e2e`** - Runs Playwright E2E tests
+
+## Usage
+
+- `/validate` — Run `npm run validate`
+- `/validate test` — Run `npm run validate:test`
+- `/validate e2e` — Run `npm run test:e2e`
+
+## Local Development Ports
+
+- **Frontend**: `localhost:3000` (default for `npm start`)
+- **Backend API**: `localhost:8000`
+- **API Docs**: `localhost:8000/docs`
diff --git a/.claude/skills/vitest-testing/SKILL.md b/.claude/skills/vitest-testing/SKILL.md
new file mode 100644
index 000000000..0b2f9959b
--- /dev/null
+++ b/.claude/skills/vitest-testing/SKILL.md
@@ -0,0 +1,239 @@
+---
+name: vitest-testing
+description: Vitest unit and component testing patterns. Use when writing unit tests, component tests, or hook tests.
+---
+
+# Vitest Testing Patterns
+
+**Focus tests on the component/hook under test.** Assume that dependencies (services, hooks, utilities) are independently tested in their own test files. Only mock what's necessary to isolate the unit under test — don't re-test dependency behavior or create elaborate mock setups for services that aren't the focus of the test.
+
+## Setup
+
+- **Framework**: Vitest with jsdom environment
+- **Globals**: `describe`, `it`, `expect` are globally available (no imports needed)
+- **DOM matchers**: `@testing-library/jest-dom` is configured in `vitest-setup.js`
+- **Component rendering**: `@testing-library/react` with `render`, `screen`, `fireEvent`, `waitFor`
+- **No MSW**: Mock functions directly with `vi.mock()` and `vi.fn()`, not HTTP interception
+
+## Test File Location
+
+Tests are **co-located** next to source files:
+
+```
+src/utils/searchUtils.ts
+src/utils/searchUtils.test.ts
+
+src/hooks/useIOSelectionPersistence.ts
+src/hooks/useIOSelectionPersistence.test.ts
+
+src/components/shared/SuspenseWrapper.tsx
+src/components/shared/SuspenseWrapper.test.tsx
+```
+
+## Utility / Pure Function Tests
+
+```typescript
+describe("formatDuration", () => {
+  it("formats seconds correctly", () => {
+    const start = "2024-01-01T10:00:00.000Z";
+    const end = "2024-01-01T10:00:30.000Z";
+    expect(formatDuration(start, end)).toBe("30s");
+  });
+});
+```
+
+## Component Tests
+
+Render with providers using a wrapper function:
+
+```typescript
+const renderWithProviders = (component: React.ReactElement) => {
+  return render(component, {
+    wrapper: ({ children }) => (
+      <ComponentSpecProvider spec={mockComponentSpec}>
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      </ComponentSpecProvider>
+    ),
+  });
+};
+
+it("renders the toolbar", async () => {
+  renderWithProviders(<RunToolbar />);
+  await waitFor(() => {
+    expect(screen.getByTestId("inspect-pipeline-button")).toBeInTheDocument();
+  });
+});
+```
+
+## Hook Tests
+
+Use `renderHook` with a wrapper for hooks that need providers:
+
+```typescript
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+};
+
+it("should hydrate component", async () => {
+  vi.mocked(hydrateComponentReference).mockResolvedValue(mockHydratedRef);
+
+  const { result } = renderHook(
+    () => useHydrateComponentReference(mockComponent),
+    { wrapper: createWrapper() },
+  );
+
+  await waitFor(() => {
+    expect(result.current).toEqual(mockHydratedRef);
+  });
+});
+```
+
+Use `act` for state updates in hooks:
+
+```typescript
+act(() => {
+  result.current.preserveIOSelectionOnSpecChange(initialSpec);
+});
+expect(mockSetNodes).toHaveBeenCalledWith(expect.any(Function));
+```
+
+## Mocking Patterns
+
+### Module mocks with `vi.mock()`
+
+```typescript
+vi.mock("@/utils/localforage", () => ({
+  componentExistsByUrl: vi.fn(),
+  getComponentByUrl: vi.fn(),
+  saveComponent: vi.fn(),
+}));
+
+// React component mock
+vi.mock("@monaco-editor/react", () => ({
+  default: ({ defaultValue }: { defaultValue: string }) => (
+    <pre data-testid="monaco-mock">{defaultValue}</pre>
+  ),
+}));
+
+// Provider/context mock
+vi.mock("@/providers/ComponentSpecProvider", () => ({
+  useComponentSpec: () => ({
+    componentSpec: mockSpec,
+    setComponentSpec: mockSetComponentSpec,
+  }),
+}));
+```
+
+### Function spies
+
+```typescript
+const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+// ... test code
+expect(consoleSpy).toHaveBeenCalledWith("Error:", expect.any(Error));
+```
+
+### Global mocks
+
+```typescript
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+mockFetch.mockResolvedValue({
+  ok: true,
+  text: () => Promise.resolve(yamlContent),
+} as Response);
+```
+
+### Environment variables
+
+```typescript
+vi.stubEnv("VITE_GITHUB_CLIENT_ID", "test-client-id");
+```
+
+## Mock Factories
+
+Create inline helper functions for test data — don't over-abstract:
+
+```typescript
+const createMockNode = (
+  id: string,
+  type: "input" | "output" | "task",
+  label: string,
+  selected = false,
+) => ({
+  id,
+  type,
+  position: { x: 0, y: 0 },
+  data: { label },
+  selected,
+});
+```
+
+## Setup / Teardown
+
+```typescript
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  cleanup(); // Testing Library cleanup
+  queryClient.clear(); // Clear query cache if using QueryClient
+  vi.restoreAllMocks();
+});
+```
+
+## Assertion Patterns
+
+```typescript
+// DOM assertions
+expect(screen.getByTestId("submit")).toBeInTheDocument();
+expect(screen.queryByTestId("hidden")).not.toBeInTheDocument();
+
+// Mock assertions
+expect(mockFn).toHaveBeenCalledWith(url);
+expect(mockFn).toHaveBeenCalledTimes(1);
+expect(mockFn).not.toHaveBeenCalled();
+
+// Partial matching
+expect(mockSave).toHaveBeenCalledWith({
+  id: expect.stringMatching(/^component-\w+$/),
+  createdAt: expect.any(Number),
+});
+```
+
+## User Interactions
+
+Prefer `fireEvent` for simple interactions in this project:
+
+```typescript
+const input = screen.getByLabelText("Name") as HTMLInputElement;
+fireEvent.change(input, { target: { value: "NewName" } });
+fireEvent.blur(input);
+expect(mockCallback).toHaveBeenCalled();
+```
+
+## Async Testing
+
+```typescript
+// Wait for state updates
+await waitFor(() => {
+  expect(screen.getByTestId("content")).toBeInTheDocument();
+});
+
+// Assert on promises
+await expect(promise).resolves.toBe(expectedValue);
+```
+
+## npm Scripts
+
+- `npm test` — Run all unit tests once
+- `npm run test:coverage` — Run with coverage report
+- `npm run validate:test` — Full validate + unit tests