@muskanmeet/invoicing-design-system 0.1.0

package/.local/skills/query-integration-data/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: query-integration-data
+description: Query and modify data in any connected integration (Linear, GitHub, HubSpot, Slack, Google services, etc.) or connected data warehouse (Databricks, Snowflake, BigQuery). Use listConnections() in the code_execution sandbox to get credentials, then call APIs directly. Supports read operations (queries, counts, exports) and write operations (create, update, delete).
+---
+
+# Query Integration Data Skill
+
+Connect to any Replit-supported integration to read or write data — query issues, create tickets, send messages, update contacts, manage files, etc. This also includes querying supported data warehouse integrations like Databricks, Snowflake, and BigQuery.
+
+All code runs inline in the `code_execution` sandbox — no script files needed.
+
+## When to Use
+
+Use this skill when the user asks you a **question in chat** that requires data from external services to answer, or when they need to perform data operations without building a visual interface.
+
+- **Answer questions**: Query data to respond to user questions in the conversation (e.g., "How many issues were created this week?")
+- **Fetch and export data**: Export data to CSV/JSON for later use or analysis
+- **Write operations**: Create, update, delete, or modify data in a service
+- **Ad-hoc queries**: One-time data lookups or investigations
+- **Automate tasks**: Perform multi-step operations across the API
+
+**Key point:** Use this skill when the output is an answer or data file, NOT when building a dashboard or visualization interface.
+
+## When NOT to Use
+
+- **The user wants to create a dashboard, visualization, or analytics interface** - use the `data-visualization` skill (it handles data fetching internally)
+- **The user asks to "build", "create", or "make" a dashboard/app with data** - use the `data-visualization` skill
+- The user needs to add an integration to their app (use the `integrations` skill)
+- Production database operations (use the database pane directly)
+- Asks to check deployment or server logs (use the `deployment` skill)
+
+## File Structure
+
+```text
+.agents/
+└── outputs/         # Generated artifacts (CSV, JSON, etc.)
+```
+
+Code runs inline in the `code_execution` sandbox — no script files are needed.
+
+## Workflow
+
+```text
+1. CHECK      → listConnections(connectorName) to get existing credentials
+   ├─ connections exist → EXECUTE → OUTPUT
+   └─ empty array      → SEARCH → LEARN → CLARIFY → setup via `integrations` skill → EXECUTE → OUTPUT
+```
+
+- **CHECK**: Call `listConnections(connectorName)` in the `code_execution` sandbox. If it returns connections, you already have credentials — skip straight to EXECUTE.
+- **SEARCH → CONNECT** (only when no connections exist): Use `searchIntegrations`, `proposeIntegration`, and `addIntegration` to set up a new connection. See the `integrations` skill for the full lifecycle details.
+- **EXECUTE**: Write and run code in the `code_execution` sandbox.
+- **OUTPUT**: Return the answer or confirmation to the user.
+
+## Getting Connection Credentials
+
+### Primary: `listConnections(connectorName)`
+
+This is the main way to get credentials. It's a pre-registered function in the `code_execution` sandbox.
+
+```javascript
+const conns = await listConnections('linear');
+console.log(conns.map(c => ({ id: c.id, displayName: c.displayName, status: c.status })));
+```
+
+Each connection object has:
+
+- `id`, `connectorConfigId`, `status`, `displayName`, `metadata`, `environment`
+- `settings` — credentials dict (access tokens, API keys, etc.)
+- `getClient()` — returns the `settings` object for constructing SDK clients
+
+Returns an empty array when no connections are configured.
+
+```javascript
+const conns = await listConnections('linear');
+if (conns.length > 0) {
+  const token = conns[0].settings.access_token;
+  const { LinearClient } = await import('@linear/sdk');
+  const client = new LinearClient({ accessToken: token });
+  // Ready to query
+}
+```
+
+### Fallback: Setting Up a New Connection
+
+If `listConnections` returns an empty array, the user hasn't connected the service yet. Use `searchIntegrations` to find the connector, then follow the `integrations` skill to walk the user through setup (`addIntegration` and `proposeIntegration` — order depends on integration type). After the connection is established, `listConnections` will return it.
+
+### Browse the Documentation
+
+**Always browse `public_documentation_link`** before writing code, especially for write operations. This helps you understand:
+
+- Required vs optional fields for creating resources
+- Valid values for enums (status, priority, type, etc.)
+- Relationships between resources (e.g., issues belong to projects)
+- Rate limits and best practices
+
+## Clarifying Questions
+
+**Before write operations, gather required information.** Many APIs require IDs or specific values that the user may not know.
+
+### When to Ask
+
+Ask clarifying questions when the user's request requires:
+
+- **Entity selection**: "Which project should this issue be created in?"
+- **User assignment**: "Who should be assigned? Let me list the team members..."
+- **Required fields**: "What priority - urgent, high, medium, or low?"
+- **Ambiguous references**: "I found 3 projects matching 'backend'. Which one?"
+
+### Pattern: Fetch Options First
+
+For write operations, often run a read query first to get valid options:
+
+```javascript
+// User says: "Create a Linear ticket assigned to John"
+// Problem: Need John's user ID, not just name
+
+const conns = await listConnections('linear');
+const { LinearClient } = await import('@linear/sdk');
+const client = new LinearClient({ accessToken: conns[0].settings.access_token });
+
+// Step 1: List users to find John's ID
+const users = await client.users();
+const john = users.nodes.find(u => u.name.includes('John'));
+
+// Step 2: If ambiguous, ASK the user
+// "I found John Smith and John Doe. Which one?"
+
+// Step 3: Create with correct ID
+await client.createIssue({ assigneeId: john.id, ... });
+```
+
+### Common Multi-Step Patterns
+
+| Action                     | First fetch...            |
+| -------------------------- | ------------------------- |
+| Create issue with assignee | List team members         |
+| Create issue in project    | List projects             |
+| Set status/priority        | Get valid workflow states |
+| Add to channel             | List channels             |
+| Assign to team             | List teams                |
+
+## Running Code in the Sandbox
+
+All code runs in the `code_execution` sandbox. State persists across calls (notebook-style), so variables from one call are available in subsequent calls.
+
+### Read Operations
+
+Query data and return results:
+
+```javascript
+const conns = await listConnections('linear');
+const { LinearClient } = await import('@linear/sdk');
+const client = new LinearClient({ accessToken: conns[0].settings.access_token });
+
+const issues = await client.issues({ first: 10 });
+console.log(`Found ${issues.nodes.length} issues`);
+for (const issue of issues.nodes) {
+  console.log(`${issue.identifier}: ${issue.title} [${issue.state?.name}]`);
+}
+```
+
+### Write Operations
+
+Create, update, or delete data:
+
+```javascript
+const conns = await listConnections('linear');
+const { LinearClient } = await import('@linear/sdk');
+const client = new LinearClient({ accessToken: conns[0].settings.access_token });
+
+// Create
+const created = await client.createIssue({ teamId: team.id, title: "Fix login bug" });
+console.log(`Created: ${created.issue?.identifier}`);
+
+// Update
+await client.updateIssue(issueId, { stateId: doneState.id });
+console.log(`Updated: ${issueId}`);
+
+// Delete
+await client.deleteIssue(issueId);
+console.log(`Deleted: ${issueId}`);
+```
+
+### Multi-Step Operations
+
+Variables persist across `code_execution` calls, enabling multi-step workflows:
+
+```javascript
+// Call 1: Get credentials and list teams
+const conns = await listConnections('linear');
+const { LinearClient } = await import('@linear/sdk');
+const client = new LinearClient({ accessToken: conns[0].settings.access_token });
+
+const teams = await client.teams();
+const team = teams.nodes[0];
+console.log(`Using team: ${team.name}`);
+
+const users = await client.users();
+const assignee = users.nodes.find(u => u.name === 'John');
+console.log(`Found assignee: ${assignee?.name}`);
+```
+
+```javascript
+// Call 2: Variables from Call 1 are still available
+const issue = await client.createIssue({
+  teamId: team.id,
+  assigneeId: assignee?.id,
+  title: 'New feature request',
+  description: 'Details here...',
+});
+console.log(`Created ${issue.issue?.identifier}: New feature request`);
+```
+
+## Databricks
+
+When the user wants to connect to Databricks, use the `databricks-m2m` connector (not the plain `databricks` connector).
+
+## Warehouse Data Exploration
+
+When querying data warehouses (BigQuery, Snowflake, Databricks), large schemas can make serial exploration slow (7-10s per query round-trip). Use the parallel subagent pattern to explore schemas faster.
+
+### CRITICAL: Warehouse queries are billed per byte scanned
+
+Warehouse targets (`bigquery`, `databricks`, `snowflake`) cost real money per query — a
+careless `SELECT *` over a fact table can cost tens of dollars and a dashboard that
+re-runs queries every few seconds can burn thousands of dollars per day. Before writing
+any warehouse query (via `executeSql` or `executeSql({target: "bigquery"})`) follow
+these rules:
+
+- **Project exact columns** — never `SELECT *` on wide tables.
+- **Always `LIMIT`** when exploring; `LIMIT 5`–`LIMIT 100` is plenty for a sample.
+- **Scope by partition / cluster** — add `WHERE event_date >= ...` (or the table's
+  clustering column) so the warehouse prunes data and you are billed for a tiny slice.
+- **Prefer pre-aggregated tables** (e.g. `_daily`, `_summary`) over raw event tables.
+- **Diff-only reads** for anything incremental — `WHERE updated_at > :last_seen` and
+  persist `last_seen` so subsequent queries only scan the delta.
+- **Cache repeated results locally** — if you run the same exploration query twice in
+  the same session, store the first result in a variable or `.agents/outputs/*.csv`
+  and reuse it instead of re-running the query.
+- **Don't power a data app from this skill** — if the user is building a dashboard,
+  report, or explorer, hand off to the `data-visualization` skill so the app's API
+  server can cache results (15-min TTL). The `query-integration-data` skill is for
+  answering questions in chat, not for powering a live UI.
+
+### When to Use Parallel Exploration
+
+Use this pattern when ALL of the following are true:
+
+- The target is a **warehouse** connection (`bigquery`, `snowflake`, or `databricks`)
+- The initial INFORMATION_SCHEMA query returns **15+ tables**
+- The user's question is **not about a specific known table** (e.g., they're asking a broad question like "what's our revenue trend?" or "show me customer data")
+
+If the schema has fewer than 15 tables, serial exploration is fast enough — just query tables one-by-one.
+
+### 4-Step Parallel Workflow
+
+**Step 1: Schema Discovery** — Run a single `executeSql` call to get the full table list.
+
+```javascript
+// BigQuery
+const tables = await executeSql({ sqlQuery: `SELECT table_schema, table_name, row_count FROM \`project.region-us\`.INFORMATION_SCHEMA.TABLES WHERE table_schema NOT IN ('INFORMATION_SCHEMA') ORDER BY table_schema, table_name`, target: "bigquery" });
+
+// Snowflake
+const tables = await executeSql({ sqlQuery: `SELECT TABLE_SCHEMA, TABLE_NAME, ROW_COUNT FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA NOT IN ('INFORMATION_SCHEMA') ORDER BY TABLE_SCHEMA, TABLE_NAME`, target: "snowflake" });
+
+// Databricks
+const tables = await executeSql({ sqlQuery: `SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema NOT IN ('information_schema') ORDER BY table_schema, table_name`, target: "databricks" });
+```
+
+`INFORMATION_SCHEMA.TABLES` is a metadata read and is essentially free. Sampling rows
+from the tables it returns is **not** free — see the next step.
+
+**Step 2: Group Tables** — Partition the table list into 2-4 clusters:
+
+- By schema/dataset name (e.g., `analytics.*`, `sales.*`, `marketing.*`)
+- By name prefix (e.g., `dim_*`, `fact_*`, `stg_*`)
+- By estimated relevance to the user's question (most-likely-relevant tables first)
+
+**Step 3: Launch Parallel Subagents** — Start one `SMALL_TASK` subagent per group:
+
+```javascript
+const group1 = await startAsyncSubagent({
+  task: `Explore these warehouse tables to answer: "${userQuestion}"
+
+Connection: Use executeSql({ sqlQuery: "...", target: "bigquery" }) — always pass target.
+Dialect: BigQuery (use backtick quoting for project.dataset.table)
+
+Tables to explore:
+- analytics.events
+- analytics.sessions
+- analytics.conversions
+
+For each table:
+1. Run: SELECT column_name, data_type, is_partitioning_column FROM \`project.dataset\`.INFORMATION_SCHEMA.COLUMNS WHERE table_name = 'TABLE_NAME'
+2. Identify the partition / cluster column from step 1 (e.g. event_date, _PARTITIONTIME).
+3. Sample rows — project exact columns, scope by partition, and LIMIT.
+   NEVER \`SELECT *\` on a fact table on a billed warehouse — \`LIMIT 5\` does not
+   undo the bytes scanned by selecting every column.
+   Pattern: SELECT <subset of columns from step 1>
+            FROM \`project.dataset.TABLE_NAME\`
+            WHERE <partition_col> >= CURRENT_DATE() - 7
+            LIMIT 5
+
+Return your findings in this exact format:
+
+## Table Relevance
+| Table | Relevant? | Why |
+|-------|-----------|-----|
+| ... | Yes/No | Brief reason |
+
+## Column Details (relevant tables only)
+| Table | Column | Type | Notes |
+|-------|--------|------|-------|
+| ... | ... | ... | Key field, foreign key, metric, etc. |
+
+## Suggested Join Conditions
+- table_a.id = table_b.a_id (describe relationship)
+
+## Key Findings
+- Bullet points about data patterns, date ranges, notable values`,
+  specialization: 'SMALL_TASK',
+  relevantFiles: ['.local/skills/database/SKILL.md']
+});
+
+// Launch additional subagents for other groups (2-4 total)
+const group2 = await startAsyncSubagent({ /* same pattern, different tables */ });
+```
+
+**Step 4: Synthesize and Query** — Use the `wait_for_background_tasks` tool to wait for the schema-discovery subagents. Once they complete, read their outputs, combine the relevant tables/columns, and write the final SQL query.
+
+### Dialect-Specific Notes
+
+| Dialect | Table Quoting | INFORMATION_SCHEMA Path | Sample Query (project columns + partition + LIMIT) |
+|---------|--------------|------------------------|------------------------------------------------------|
+| BigQuery | `` `project.dataset.table` `` | `` `project.dataset`.INFORMATION_SCHEMA.COLUMNS `` | `` SELECT col_a, col_b FROM `p.d.t` WHERE event_date >= CURRENT_DATE() - 7 LIMIT 5 `` |
+| Snowflake | `"DATABASE"."SCHEMA"."TABLE"` | `DATABASE.INFORMATION_SCHEMA.COLUMNS` | `SELECT col_a, col_b FROM "DB"."SCH"."TBL" WHERE event_date >= DATEADD(day, -7, CURRENT_DATE) LIMIT 5` |
+| Databricks | `` `catalog.schema.table` `` | `catalog.information_schema.columns` | `` SELECT col_a, col_b FROM `c.s.t` WHERE event_date >= current_date() - INTERVAL 7 DAY LIMIT 5 `` |
+
+**Do NOT** use `SELECT *` in the sample query column above. `LIMIT 5` does not undo
+the cost of reading every column for the matched rows on a billed warehouse.
+
+### Tips
+
+- Each subagent should run 3-6 SQL queries (column metadata + sample data per table)
+- Keep subagent count to 2-4 — more than 4 has diminishing returns
+- The structured markdown output format ensures consistent, scannable results
+- After synthesis, write a single well-commented SQL query that answers the user's question
+
+## Output Guidelines
+
+- **Simple answers** (counts, scalar values, short lists of < 20 records): Print directly with `console.log()`
+- **Complex results** (tabular results): Write to `.agents/outputs/<filename>.csv` and summarize
+- **Write confirmations**: Print what was created/updated/deleted with IDs
+- **Errors**: Print clear error messages
+
+```javascript
+const fs = await import('fs');
+
+// Simple
+console.log(`Answer: 42 issues created this week`);
+
+// Tabular results - write CSV to .agents/outputs/
+fs.mkdirSync('.agents/outputs', { recursive: true });
+fs.writeFileSync('.agents/outputs/results.csv', csvContent);
+console.log(`Exported 500 records to .agents/outputs/results.csv`);
+
+// Write
+console.log(`Created issue ENG-123: "Fix login bug"`);
+console.log(`Updated 5 contacts`);
+console.log(`Deleted message ID abc123`);
+```
+
+## Key Points
+
+- **Use `listConnections(connectorName)`** as the primary way to get credentials
+- **Fall back to search → propose → add** when no connections exist (see `integrations` skill)
+- **All code runs in the `code_execution` sandbox** — no script files needed
+- **Use `console.log()`** to see output — functions execute silently without it (but never log credentials)
+- **Use `await import(...)`** for packages (dynamic imports only)
+- **State persists** across `code_execution` calls — reuse `conns`, clients, and extracted credentials instead of re-fetching (unless expired).
+- **Browse `public_documentation_link`** to understand the API before coding
+- **Ask clarifying questions** before write operations that need specific IDs or values
+- **Fetch options first** when the user references something by name (users, projects, etc.)
+- **Don't cache clients** — access tokens expire; re-create clients from `listConnections` when needed
+- **Write large outputs to `.agents/outputs/`** as CSV or JSON

package/.local/skills/react-vite/.fingerprint

@@ -0,0 +1 @@
+d7a214633b60b119837131a7b3202e38

package/.local/skills/react-vite/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: react-vite
+description: Guidelines for building React + Vite web apps in the pnpm monorepo with design subagent delegation.
+---
+
+Always follow these guidelines when building a React + Vite web application:
+
+## Architecture
+
+- Follow modern web application patterns and best-practices.
+- If the app is complex and requires functionality that can't be done in a single request, it is okay to stub out the backend and implement the frontend first.
+
+## Frontend
+
+- Load the `design` skill and start an async design subagent to build the frontend. Do not give the subagent any recommendation or advice on how it should build the frontend unless requested by the user. For example, do not talk about color, font, layout, etc. the design subagent has much better taste than you
+
+## First Build
+
+**You must use the design subagent for every react-vite first build — no exceptions.** This applies regardless of app size, complexity, or whether a backend is needed. "No backend" means skip OpenAPI/codegen, not skip the design subagent. "Simple app" means the subagent gets a simpler brief, not that you build the frontend yourself. Never build the frontend yourself to save time — the design subagent is the fast path.
+
+### Step 1: Classify the app
+
+Before building, classify the app to decide how you and the DESIGN subagent split work. **The design subagent is always used** — the question is how much it owns.
+
+- **Presentation-first** (landing pages, fan sites, portfolios, brand microsites, marketing sites): DESIGN subagent owns almost everything. No backend needed. Skip to the presentation-first workflow below.
+- **Personal utility** (notes, journals, habit trackers, personal finance, mood trackers, reading lists): These are personal tools, not business tools. Treat like consumer/lifestyle — personality encouraged, micro-interactions expected. Information-density-first does NOT apply.
+- **CRUD / dashboards / admin tools** (CRMs, inventory tools, internal tools, analytics dashboards): Parent agent owns product surface and backend. DESIGN subagent owns the entire frontend visual layer.
+- **Logic-heavy / backend-coupled** (real-time collaboration, workflow engines, devtools, infra tools, scheduling systems): Parent agent leads backend and systems logic. DESIGN subagent still builds the frontend — it handles UI shells, components, pages, and polish.
+- **Interactive visual experiences / casual games** (browser games, playful interactive scenes): DESIGN subagent strongly influences frontend, animation, and visual assets. Parent agent owns game rules, persistence, and systems logic.
+
+### Step 2: Plan the API surface
+
+The difference between a boring app and a great app is usually 3-5 extra endpoints in the spec. Before codegen, spend an extra minute adding safe wow endpoints beyond flat CRUD — lightweight read-only endpoints that make the app feel polished:
+
+- Dashboard summaries (totals, grouped counts, pipeline values)
+- Recent activity / timeline feeds
+- Status/stage breakdowns and domain-specific aggregates
+- Top/trending/pinned item queries
+
+Skip speculative expensive features (recommendations, anomaly detection, forecasting, complex real-time presence).
+
+This way the design subagent has real hooks for both the core app and the wow surfaces, and integration is minimal.
+
+### Step 3: Build with maximum parallelism
+
+Use the `pnpm-workspace` skill as the source of truth for shared monorepo rules. When you touch backend code, follow the `pnpm-workspace` skill's references:
+
+- `references/openapi.md` for contract-first OpenAPI + codegen
+- `references/server.md` for `artifacts/api-server/src/routes/` conventions
+- `references/db.md` for `lib/db/src/schema/` and Drizzle guidance
+
+#### For apps with a backend
+
+**The design subagent is the bottleneck — everything is ordered to get it running ASAP.**
+
+**The database is NOT a prerequisite for the design subagent.** Even when the app clearly needs a DB, do not provision a database, write schema, run migrations, or seed before launching the subagent. The design subagent depends only on the generated API client (OpenAPI → codegen → hooks) — it does not care whether the DB exists yet. All DB work happens AFTER the subagent is spawned, in parallel with its run (see step 5). Calling `createDatabase()` or any DB tool before step 4 directly delays first output for zero benefit.
+
+1. Create the artifact.
+2. Write the OpenAPI spec in `lib/api-spec/openapi.yaml` — include both core CRUD and the safe wow endpoints from Step 2. This is the **critical path** because it gates codegen which gates the design subagent.
+3. Run codegen (`pnpm run --filter @workspace/api-spec codegen`)
+4. Grep the exact generated exports and launch the design subagent (async), following the `design` skill's delegation rules:
+    - Run `grep "^export " lib/api-client-react/src/generated/*.ts | grep -E "function use|const use|QueryKey"` and include the full list in the task description so the subagent does not guess names.
+    - Pass the generated client files, the main CSS/theme file, `src/App.tsx`, `package.json`, and `.local/skills/react-vite/references/frontend_general_rules.md` via `relevantFiles` so the subagent can import and use real API hooks without wasting time exploring.
+    - Pass **all** implementation skills you've read via `relevantSkills` — use the full path from the skills view for each one. Any skill with integration details (auth, storage, payments, etc.) must be forwarded so the subagent builds correctly.
+    - Keep the task description SHORT: app purpose (1-2 sentences), page routes with one-line purposes, data types with fields, and the API hooks list.
+    - Tell the subagent to use ALL the provided hooks. The product surface has been planned; the subagent should express it beautifully, not invent net-new features.
+5. While the design subagent runs, do backend work in parallel:
+    - Run `grep "^export " lib/api-zod/src/generated/api.ts` to capture the exact Zod schema names (e.g. `ListNotesQueryParams`, `CreateNoteBody`, `GetNoteParams`). Use the real names when writing routes instead of guessing based on Orval's naming conventions.
+    - Provision a database if the app needs one.
+    - Write DB schema in `lib/db/src/schema/`, then run `pnpm --filter @workspace/db run push`.
+    - Implement API routes in `artifacts/api-server/src/routes/`, importing the exact Zod schema names from the grep above (do not guess — Orval names vary by parameter location: `QueryParams`, `Params`, `Body`).
+    - Seed a small amount of example data (1-3 rows per table) so the app isn't empty on first load. Do not over-seed.
+    - For seed data images that don't come from a real API, use `generate_image` instead of placeholder services (DiceBear, Boring Avatars, Unsplash, Lorem Picsum, etc.). Real API image URLs (e.g. PokéAPI sprites, TMDB posters) are fine. It's okay not to seed object storage.
+    - You can also ask the design subagent to generate images/video as part of its task — it has access to `generate_image`, `generate_video`, and `stock_image`.
+**Note: All DB schema/definition/seeding and backend development work MUST happen only after the design subagent has been spawned. Do not front-load any of it.**
+6. After your backend development process is done. wait for the design subagent to finish.
+   Note: Do not restart the frontend workflow until the design subagent is done otherwise it will show a broken app, you can restart the API one if needed.
+7. Fix any integration issues (restart workflow and refresh logs).
+8. Present the artifact — show it to the user.
+9. Call `suggestDeploy()` — prompt the user to publish their app so it's live and accessible.
+
+#### For presentation-first apps (no backend)
+
+No OpenAPI, no codegen. Launch the design subagent immediately.
+
+If the user is creating a site for a real company, or wants to match an existing company/site, gather context before launching the design subagent: use `extractBranding` for brand tokens, fall back to `imageSearch` via the `image-search` skill when you need a cleaner or missing logo, use `webFetch` on the homepage, about page, or key product pages for real messaging, and use external-URL `screenshot` when the visual feel of the source site matters. Pass the distilled brand and product context into the brief, not raw tool output. When passing brand context, include colors, typography, and images.
+If `extractBranding` and/or `imageSearch` gave you images, download each usable image into the workspace before launching the design subagent. Pass the local file paths via `relevantFiles` and include a `Brand assets` block in the task that labels each file (logo, favicon, OG image, etc.), where it came from, and what it should be used for.
+Never pass image URLs or vague references as the only handoff; if an image is not downloaded to a workspace file and identified in the task, treat it as unavailable.
+
+1. Create the artifact and read the `design` skill
+2. Launch the design subagent (async) immediately — no codegen step needed. Follow the `design` skill's presentation-heavy delegation rules:
+    - Pass the main CSS/theme file, `src/App.tsx`, branding images, and `package.json` via `relevantFiles`.
+    - Provide a vivid brand identity, the pages to build, and any downloaded brand asset labels and local paths.
+3. Present the artifact when the subagent finishes.
+4. Call `suggestDeploy()`.
+
+### Important notes
+
+- The design subagent will be a bottleneck — it takes time to build the frontend so launch it as soon as codegen is complete
+- After the frontend build finishes, if this is part of a multi-artifact project, extract the design tokens from the generated `src/index.css` (colors, fonts, radius) and store them for use in subsequent artifacts (expo, slides, etc.). This ensures all artifacts share the same visual identity. See `multi-artifact-creation.md` "Visual Consistency" section.
+- Do not read unnecessary files. When building this artifact, you are not building the frontend so reading the generated react hooks is a waste of time and context
+- After presenting the artifact, call `suggestDeploy()` so the user knows their app is ready to publish
+- Follow the service access and routing rules from the `pnpm-workspace` skill.
+- If the app is being transitioned from a mockup the user made using the canvas, use what the user created to build the react-vite application directly
+- **WebSocket proxy path**: If the app uses WebSockets, the WS path (e.g. `/ws`) must be listed in `artifact.toml`'s `paths` array alongside the REST API path. The proxy only forwards explicitly listed paths — unlisted WS paths are silently dropped and the server never sees the connection.
+- After each OpenAPI spec change, re-run codegen before using the updated types.
+
+## SEO
+
+There is a full SEO implementation guide in `.local/skills/react-vite/references/seo.md`. Read it when building or optimizing pages for search engine visibility. At minimum, ensure every page has a unique title tag, meta description, and Open Graph tags.

package/.local/skills/react-vite/references/frontend_general_rules.md

@@ -0,0 +1,66 @@
+## Frontend
+
+- Use `wouter` for routing on the frontend.
+  - If you need to add a new page, add them to the `src/pages` directory and register them in `src/App.tsx`.
+  - If there are multiple pages, use a sidebar for navigation. Use the `Link` component or the `useLocation` hook from `wouter` instead of modifying the window directly.
+- For forms, always use shadcn's `useForm` hook and `Form` component from `@/components/ui/form` which wraps `react-hook-form`.
+  - When appropriate, use the `zodResolver` from `@hookform/resolvers/zod` to validate form data.
+  - Use `.extend` to add validation rules to the schema.
+  - Remember that the form component is controlled, ensure you pass default values to the `useForm` hook.
+- Use the Orval-generated hooks from `@workspace/api-client-react` for all API calls. Do not write raw `fetch` or manual TanStack Query hooks when generated hooks exist.
+  - Generated query hooks return `T` directly — NOT wrapped in `{ data: T }`.
+  - When passing options like `enabled`, you MUST also pass `queryKey`:
+
+    ```typescript
+    const { data } = useGetNote(noteId, { query: { enabled: !!noteId, queryKey: getGetNoteQueryKey(noteId) } });
+    ```
+
+  - For mutations, `onSuccess` receives `T` directly:
+
+    ```typescript
+    createRoom.mutate({ data: { name } }, {
+      onSuccess: (room) => { setLocation(`/room/${room.id}`); }
+    });
+    ```
+
+  - Invalidate related queries after mutations using the generated queryKey helpers.
+  - Show a loading or skeleton state while queries (via `.isLoading`) or mutations (via `.isPending`) are being made.
+- Common pitfalls to avoid:
+  - The `useToast` hook is exported from `@/hooks/use-toast`.
+  - If a form is failing to submit, try logging out `form.formState.errors` to see if there are form validation errors for fields that might not have associated form fields.
+  - DO NOT explicitly import React as the existing Vite setup has a JSX transformer that does it automatically.
+  - Use `import.meta.env.<ENV_VAR>` to access environment variables on the frontend instead of `process.env.<ENV_VAR>`. Note that variables must be prefixed with `VITE_` in order for the env vars to be available on the frontend.
+  - `<SelectItem>` will throw an error if it has no value prop. Provide a value prop like this `<SelectItem value="option1">`.
+  - NEVER import something you don't use — TypeScript will fail the build on unused imports.
+  - Always import React hooks (`useState`, `useEffect`, `useRef`, `useCallback`, `useMemo`) from `"react"` — never from a router library like `"wouter"`.
+- Add a `data-testid` attribute to every HTML element that users can interact with (buttons, inputs, links, etc.) and to elements displaying meaningful information (user data, status messages, dynamic content, key values).
+  - Use unique, descriptive identifiers following this pattern:
+    - Interactive elements: `{action}-{target}` (e.g., `button-submit`, `input-email`, `link-profile`)
+    - Display elements: `{type}-{content}` (e.g., `text-username`, `img-avatar`, `status-payment`)
+  - For dynamically generated elements (lists, grids, repeated components), append a unique identifier at the end: `{type}-{description}-{id}`
+    - Examples: `card-product-${productId}`, `row-user-${index}`, `text-price-${itemId}`
+    - The dynamic identifier can be any unique value (database ID, index, key) as long as it's unique within that group
+  - Keep test IDs stable and descriptive of the element's purpose rather than its appearance or implementation details.
+
+## Styling and Theming
+
+- CSS custom properties use space-separated HSL values (no `hsl()` wrapper):
+
+  ```css
+  :root { --primary: 221 83% 53%; }
+  ```
+
+  Usage: `background-color: hsl(var(--primary));`
+- The scaffold's `index.css` ships with every CSS custom property set to `red` as a placeholder. Rewrite the `:root` and `.dark` blocks with a cohesive theme palette before writing any components. If any `red` values remain, the page will render with red backgrounds, borders, and text.
+- When adding Google Fonts or any `@import url(...)` to index.css, it MUST be the very first line of the file — before `@import "tailwindcss"` and all other statements. PostCSS will fail silently if any `@import url(...)` appears after other CSS rules.
+- Use the `@`-prefixed paths to import shadcn components and hooks.
+- Use icons from `lucide-react` to signify actions and provide visual cues. Use `react-icons/si` for company logos.
+- User may attach assets (images, etc.) in their request.
+  - If the user asks you to include attached assets in the app, you can reference them in the frontend with the `@assets/...` import syntax.
+  - For example, if the user attached asset is at `attached_assets/example.png`, you can reference it in the frontend with `import examplePngPath from "@assets/example.png"`.
+
+## Dark Mode
+
+1. Set `darkMode: ["class"]` in tailwind.config.ts and define color variables in `:root` and `.dark` CSS classes
+2. Create ThemeProvider with useState("light"), useEffect to toggle "dark" class on document.documentElement, and localStorage sync
+3. When not using utility class names configured in `tailwind.config.ts`, always use explicit light/dark variants for ALL visual properties: `className="bg-white dark:bg-black text-black dark:text-white"`. When using utility classes configured in tailwind config, you can assume these already been configured to automatically adapt to dark mode.