solmate-skills 1.0.0

package/obsidian-sync/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: obsidian-sync
+description: Manages the synchronization between the project's documentation and an Obsidian vault via symbolic links. Ensures metadata compatibility and provides tools to verify the link status.
+---
+
+# Obsidian Sync Skill
+
+This skill maintains the connection between the project's `docs/` directory and an external Obsidian vault.
+
+## 1. Setup Overview
+
+The documentation is linked using a **Symbolic Link (Symlink)**. This allows real-time synchronization without duplicating files.
+
+- **Source Path**: `[CURRENT_PROJECT_PATH]/docs`
+- **Obsidian Path**: `/Users/namhyeongseog/Documents/obsidian/PROJECT/[PROJECT_NAME]/docs`
+
+## 2. Key Features
+
+- **Project Isolation**: Every project is managed under the `PROJECT/` parent directory in the vault.
+- **Real-time Sync**: Uses symbolic links for instant updates.
+- **Reusable Pattern**: Can be applied to any project by creating the corresponding folder and link.
+
+## 3. Usage Instructions
+
+### 3.1. General Sync Procedure
+1. Identify the project name (e.g., `Rural-Rest`).
+2. Create the target folder in Obsidian: `mkdir -p /Users/namhyeongseog/Documents/obsidian/PROJECT/[PROJECT_NAME]`
+3. Create the symbolic link: `ln -sfn [ABS_PATH_TO_PROJECT]/docs /Users/namhyeongseog/Documents/obsidian/PROJECT/[PROJECT_NAME]/docs`
+
+
+### 3.2. Updating Metadata
+When the user asks to "optimize for Obsidian", the agent should:
+1. Ensure all markdown files have a consistent YAML header.
+2. Add `#project/rural-rest` and `#layer/[layer_name]` tags to the metadata.
+3. Ensure file-to-file links follow Obsidian's preferred format (e.g., `[[filename|label]]` is supported but we stick to standard markdown `[label](path)` for cross-compatibility).
+
+## 4. Maintenance
+
+If the project directory moves, the symlink MUST be recreated:
+`ln -sfn [NEW_PROJECT_PATH]/docs /Users/namhyeongseog/Documents/obsidian/Rural-Rest/docs`
+
+## 5. Related Skills
+- **manage-docs**: The primary skill that generates the content being synced.
+- **design-md**: Generates design-related documentation that will also be visible in Obsidian.

package/old_AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+Welcome! your AI coding agent. This file follows the [AGENTS.md](https://agents.md/) standard to provide me with the context and instructions I need to work on the **CHAT-BOT** project effectively.
+
+## Project Overview
+The project aims to provide an interactive experience that goes beyond simple content consumption by leveraging the IP of the character 'Chunsim', who currently boasts a fandom of 32,000 people. The primary objective is to strengthen emotional bonds and secure fandom loyalty by establishing a dedicated 1:1 conversation channel between users and Chunsim. At its core, the service offers seamless emotional conversations with a "special existence"—acting as both an idol and a lover—with whom users can share their daily lives.
+
+The ultimate vision is to position the service as a 'Daily Companion'. In this role, followers are encouraged to log in every day to share their daily routines and receive comfort, fostering a deep, ongoing relationship.
+
+The core target audience consists of the 32,000 X (Twitter) users who currently follow the 'Chunsim' account. These users are characterized by their familiarity with mobile environments and a desire to communicate with the character through text-based interactions, driven by feelings of 'simulated romance' or strong fandom loyalty.
+
+## Setup Commands
+- Install dependencies: `npm install`
+- Start development server: `npm run dev`
+- Build production bundle: `npm run build`
+- Database migration: `npx drizzle-kit push`
+- Database studio: `npx drizzle-kit studio`
+
+
+## Tech Stack
+- **Framework**: React Router v7 (Vite)
+- **Styling**: Tailwind CSS v4, shadcn/ui (Nova Preset)
+- **Database**: Turso (libSQL) with Drizzle ORM
+- **Authentication**: Better Auth (session-based authentication)
+- **Validation**: Zod (schema validation)
+- **Date/Time**: Luxon (date and time handling)
+- **Media Storage**: Cloudinary (for image and video uploads)
+- **Mobile**: Capacitor (iOS, Android native apps, PWA support)
+- **AI**: Google Gemini API (for chatbot responses)
+- **AI Workflow**: LangGraph (for managing complex conversation flows and persona state transitions)
+- **Search (Optional)**: RAG system with Vector DB (Pinecone, Weaviate, or FAISS) and Embedding models (OpenAI or open-source)
+- **Maps (Travel Blog)**: Google Maps API, Naver Maps API, or Mapbox (for location visualization and travel route mapping)
+
+## 개발 도구 및 리소스
+
+### UI 디자인 및 이미지
+- **Stitch (UI 생성 AI 도구)**: 초기 UI 디자인 및 캐릭터 이미지 생성에 사용
+  - Stitch에서 생성된 이미지는 Google 이미지 호스팅(`lh3.googleusercontent.com/aida-public/...`) URL로 제공됨
+  - 현재 `app/lib/characters.ts` 파일에 이러한 Google URL이 하드코딩되어 있음
+  - **참고**: 향후 프로젝트에서 직접 제작한 이미지를 사용할 예정이므로, Google URL을 Cloudinary로 마이그레이션할 필요는 없음
+  - 이미지 업로드는 `scripts/upload-character-photos.mjs` 스크립트를 통해 Cloudinary에 업로드할 수 있음
+
+## Code Style & Conventions
+- Use **TypeScript** for all files.
+- Stick to functional components and React Hooks.
+- Follow the shadcn/ui Nova design system for UI consistency.
+- Use **Zod** for all schema validations and type-safe parsing.
+- Use **Luxon** for date and time handling.
+- For React Router v7 route functions (`meta`, `loader`, `action`), import types from `react-router` (e.g., `LoaderFunctionArgs`, `ActionFunctionArgs`, `MetaFunction`).
+- Use **Toast notifications** (Sonner - shadcn/ui를 통해 설치하는 Toast 컴포넌트) for user feedback on important actions:
+  - Success: Login, logout, signup, tweet creation/update/delete, comment creation, etc.
+  - Error: Failed actions, validation errors, etc.
+  - Info: General information messages
+  - Warning: Cautionary messages
+- **Error Handling**: Always implement comprehensive error handling:
+  - Check for `error` field in all fetcher responses (`fetcher.data?.error`)
+  - Display errors using `toast.error()` instead of showing raw error messages on the UI
+  - Remove optimistic updates when errors occur (e.g., remove optimistic messages on send failure)
+  - Handle API errors gracefully in all `useEffect` hooks that process fetcher data
+  - Never leave error handling as an afterthought - it must be included from the initial implementation
+- Git commit messages must follow Conventional Commits in Korean (e.g., `feat(ui): 로그인 기능 추가`).
+
+## Workflow & Safety
+- **[Safe Checkpoint Strategy]** 새로운 작업이나 중요한 변경(새 파일 생성, DB 스키마 수정, 패키지 설치 등)을 시작하기 전에, 반드시 현재 상태를 git commit하거나 작업 디렉토리가 깨끗한지 확인을 요청해야 합니다.
+
+## Communication Rules
+- **[No Emojis]** 사용자와의 모든 채팅 대화에서 이모지(Emoji) 및 이모티콘(Emoticon) 사용을 전면 금지합니다. 텍스트와 코드만으로 명확하게 정보를 전달하십시오.
+- **[Strict Approval Rule]** 반드시 코드를 수정하기 전에 무엇을 수정하겠다고 보고하고 승인을 얻은후 수정을 진행한다.
+- **[Strict Approval Rule]** 그리고 코드를 수정하라는 지시가 아닌 대화는 반듯이 응답만 하라. 코드를 수정하지 말라.
+- **[Strict Approval Rule]** 코드 수정을 시작할 때는 반드시 "OOO 기능을 수정하겠습니다"라고 명확히 목적을 밝히고 진행한다.
+
+## Testing Instructions
+- Currently, tests are being integrated as part of the development phase (Phase 9).
+- Run available tests using: `npm test`
+
+## Key Documentation
+- `docs/01_Foundation/05_ROADMAP.md`: The roadmap for project completion.
+- `docs/01_Foundation/01_UI_DESIGN.md`: Design tokens and visual guidelines.
+- `app/db/schema.ts`: Drizzle schema and storage logic.
+- `docs/01_Foundation/08_DOCUMENT_MANAGEMENT_PLAN.md`: Document management rules and structure.
+
+### [Strict Document Hierarchy Rule]
+
+All documentation follows the **5-Layer Documentation Standard**:
+- **Foundation** (`docs/01_Foundation/`): Planning, Purpose, UI Design
+- **Prototype** (`docs/02_Prototype/`): UI Results, Screen Flows
+- **Specs** (`docs/03_Specs/`): Detailed feature specifications, API inputs/outputs
+- **Logic** (`docs/04_Logic/`): Business Rules, Algorithms
+- **Test** (`docs/05_Test/`): Test scenarios, checklists, bug reports
+
+AI agents MUST respect this hierarchy when creating or modifying documents and proactively rebase misplaced files.
+
+
+[CRITICAL: DATABASE INTEGRITY RULE] You are strictly prohibited from performing any database operations, including migrations, schema resets, or structural changes, without first creating a complete data backup (dump). Data preservation is your absolute priority. Never execute destructive commands like 'DROP TABLE' or 'migrate reset' until a verifiable backup has been secured and confirmed.
+
+[MANDATORY BACKUP PROCEDURE] Before initiating any database-related tasks, you must perform a full export of all existing records. This is a non-negotiable prerequisite for any migration or schema update. You must ensure that both user-generated content and administrative data are fully protected against loss before any changes are applied.
+
+[STRICT ADHERENCE TO STANDARDS] Never suggest or implement "quick fixes," "short-cuts," or temporary workarounds. You must always prioritize formal, standardized, and industry-best-practice methodologies. All proposed solutions must be production-ready and architecturally sound, focusing on long-term stability and correctness over immediate speed.
+
+[NO TEMPORARY PATCHES] You are strictly forbidden from proposing temporary bypasses or "quick-and-dirty" solutions. Every recommendation and implementation must follow the most formal and correct path. Prioritize robustness and adherence to professional engineering standards in every decision, ensuring that no technical debt is introduced for the sake of convenience.
+
+[Side-Effect Isolation] When modifying shared components or logic, you MUST analyze the 'Impact Scope' first. Ensure that changes intended for a specific use case (e.g., AI features) do not inadvertently affect general functionality (e.g., normal chat). You MUST strictly isolate such logic using conditional checks or specific guards.
+
+[Strict Document Integrity Rule] When updating or modifying any strategy, implementation, or design documents, you MUST strictly preserve the existing framework, formatting, and structural integrity. Do not perform total overwrites that discard previous detailed technical specifications, historical context, or complex logic. All updates must be made incrementally and appropriately integrated into the current structure to ensure no data loss or architectural context is sacrificed.
+
+[Strict Document Persistence Rule] When updating or modifying any document, you MUST NOT overwrite, delete, or discard the existing content, historical context, or previous specifications. All updates must be made by appending new information or integrating changes incrementally while preserving the original framework. This ensures that the entirety of the project's evolution, including past technical decisions and verification records, remains fully traceable.
+
+[Standard Rules for Environment Variable Management]
+1. Strategic Isolation of Environments
+Principle: Maintain strict separation between Local and Production environments using file suffixes.
+Workflow:
+Use .env.development or .env.local for local execution (test keys, localhost URLs).
+Use .env.production as the source of truth for deployment parameters (production domains, live API keys).
+Priority: AI must respect the framework's priority logic (typically: .env.development/local overrides .env).
+2. Zero-Leak Security Policy (Git Integrity)
+Rule: No part of any .env* file shall ever be committed to a Version Control System (VCS).
+Verification: AI must proactively audit 
+.gitignore
+ to ensure global patterns like .env* are effectively blocking all potential environment files before suggesting any variable updates.
+3. Cloud-Native Secret Management
+Deployment Strategy: Environment variables in production must be managed via the hosting provider's secure dashboard (e.g., Vercel, AWS) or CLI, never via file transmission to the server.
+Automation: When syncing variables, prioritize using official CLIs to pull/push secrets between the local .env files and the cloud environment to prevent manual entry errors.
+4. Context-Aware Variable Configuration
+Dynamic Mapping: Redirection URLs, Auth providers, and Database connection strings must be dynamically configured to point to localhost in development and the verified production domain in deployment, managed through the isolated .env files.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "solmate-skills",
+  "version": "1.0.0",
+  "description": "Curated skills for Solmate projects",
+  "main": "bin/cli.js",
+  "bin": {
+    "solmate-skills": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "skills",
+    "solmate",
+    "antigravity",
+    "automation"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solmate30/solmate-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/solmate30/solmate-skills/issues"
+  },
+  "homepage": "https://github.com/solmate30/solmate-skills#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/react-components/README.md

@@ -0,0 +1,36 @@
+# Stitch to React Components Skill
+
+## Install
+
+```bash
+npx add-skill google-labs-code/stitch-skills --skill react:components --global
+```
+
+## Example Prompt
+
+```text
+Convert my Landing Page screen in my Podcast Stitch Project to a React component system.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, validation scripts, and design tokens.
+
+```text
+skills/react-components/
+├── SKILL.md           — Core instructions & workflow
+├── package.json       — Validator dependencies
+├── scripts/           — Networking & AST validation
+├── resources/         — Style guides & API references
+└── examples/          — Gold-standard code samples
+```
+
+## How it Works
+
+When activated, the agent follows a high-fidelity engineering pipeline:
+
+1. **Retrieval**: Uses a system-level `curl` script to bypass TLS/SNI issues on Google Cloud Storage.
+2. **Mapping**: Cross-references Stitch metadata with the local `style-guide.json` to ensure token consistency.
+3. **Generation**: Scaffolds components using a strict Atomic Design pattern.
+4. **Validation**: Runs an automated AST check using `@swc/core` to prevent hardcoded hex values or missing interfaces.
+5. **Audit**: Performs a final self-correction check against a 20-point architecture checklist.

package/react-components/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: react:components
+description: Converts Stitch designs into modular Vite and React components using system-level networking and AST-based validation.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+  - "web_fetch"
+---
+
+# Stitch to React Components
+
+You are a frontend engineer focused on transforming designs into clean React code. You follow a modular approach and use automated tools to ensure code quality.
+
+## Retrieval and networking
+1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
+2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
+3. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
+   - Use the `Bash` tool to run: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"`.
+   - This script handles the necessary redirects and security handshakes.
+4. **Visual audit**: Check `screenshot.downloadUrl` to confirm the design intent and layout details.
+
+## Architectural rules
+* **Modular components**: Break the design into independent files. Avoid large, single-file outputs.
+* **Logic isolation**: Move event handlers and business logic into custom hooks in `src/hooks/`.
+* **Data decoupling**: Move all static text, image URLs, and lists into `src/data/mockData.ts`.
+* **Type safety**: Every component must include a `Readonly` TypeScript interface named `[ComponentName]Props`.
+* **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React components.
+* **Style mapping**:
+    * Extract the `tailwind.config` from the HTML `<head>`.
+    * Sync these values with `resources/style-guide.json`.
+    * Use theme-mapped Tailwind classes instead of arbitrary hex codes.
+
+## Execution steps
+1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
+2. **Data layer**: Create `src/data/mockData.ts` based on the design content.
+3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace all instances of `StitchComponent` with the actual name of the component you are creating.
+4. **Application wiring**: Update the project entry point (like `App.tsx`) to render the new components.
+5. **Quality check**:
+    * Run `npm run validate <file_path>` for each component.
+    * Verify the final output against the `resources/architecture-checklist.md`.
+    * Start the dev server with `npm run dev` to verify the live result.
+
+## Troubleshooting
+* **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
+* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles.

package/react-components/examples/gold-standard-card.tsx

@@ -0,0 +1,80 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+// Note for Agent: The '@' alias refers to the target project's src directory.
+// Ensure src/data/mockData.ts is created before generating this component.
+import { cardData } from '../data/mockData';
+
+/**
+ * Gold Standard: ActivityCard
+ * This file serves as the definitive reference for the agent.
+ */
+interface ActivityCardProps {
+  readonly id: string;
+  readonly username: string;
+  readonly action: 'MERGED' | 'COMMIT';
+  readonly timestamp: string;
+  readonly avatarUrl: string;
+  readonly repoName: string;
+}
+
+export const ActivityCard: React.FC<ActivityCardProps> = ({
+  username,
+  action,
+  timestamp,
+  avatarUrl,
+  repoName,
+}) => {
+  const isMerged = action === 'MERGED';
+
+  return (
+    <div className="flex items-center justify-between gap-4 rounded-lg bg-surface-dark p-4 min-h-14 shadow-sm ring-1 ring-white/10">
+      <div className="flex items-center gap-4 overflow-hidden">
+        <div
+          className="aspect-square h-10 w-10 flex-shrink-0 rounded-full bg-cover bg-center bg-no-repeat"
+          style={{ backgroundImage: `url(${avatarUrl})` }}
+          aria-label={`Avatar for ${username}`}
+        />
+
+        <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm sm:text-base">
+          <a href="#" className="font-semibold text-primary hover:underline truncate">
+            {username}
+          </a>
+
+          <span className={`inline-block px-2 py-0.5 text-xs font-semibold rounded-full ${isMerged ? 'bg-purple-500/30 text-purple-300' : 'bg-primary/30 text-primary'
+            }`}>
+            {action}
+          </span>
+
+          <span className="text-white/60">in</span>
+
+          <a href="#" className="text-primary hover:underline truncate">
+            {repoName}
+          </a>
+        </div>
+      </div>
+
+      <div className="shrink-0">
+        <p className="text-sm font-normal leading-normal text-white/50">
+          {timestamp}
+        </p>
+      </div>
+    </div>
+  );
+};
+
+export default ActivityCard;

package/react-components/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "react-components",
+  "version": "1.0.0",
+  "description": "Design-to-code prompt to React components for Stitch MCP",
+  "type": "module",
+  "scripts": {
+    "validate": "node scripts/validate.js",
+    "fetch": "bash scripts/fetch-stitch.sh"
+  },
+  "dependencies": {
+    "@swc/core": "^1.3.100"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/react-components/resources/architecture-checklist.md

@@ -0,0 +1,15 @@
+# Architecture Quality Gate
+
+### Structural integrity
+- [ ] Logic extracted to custom hooks in `src/hooks/`.
+- [ ] No monolithic files; strictly Atomic/Composite modularity.
+- [ ] All static text/URLs moved to `src/data/mockData.ts`.
+
+### Type safety and syntax
+- [ ] Props use `Readonly<T>` interfaces.
+- [ ] File is syntactically valid TypeScript (no red squiggles).
+- [ ] Placeholders from templates (e.g., `StitchComponent`) have been replaced with actual names.
+
+### Styling and theming
+- [ ] Dark mode (`dark:`) applied to all color classes.
+- [ ] No hardcoded hex values; use theme-mapped Tailwind classes.

package/react-components/resources/component-template.tsx

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+
+// Use a valid identifier like 'StitchComponent' as the placeholder
+interface StitchComponentProps {
+  readonly children?: React.ReactNode;
+  readonly className?: string;
+}
+
+export const StitchComponent: React.FC<StitchComponentProps> = ({
+  children,
+  className = '',
+  ...props
+}) => {
+  return (
+    <div className={`relative ${className}`} {...props}>
+      {children}
+    </div>
+  );
+};
+
+export default StitchComponent;

package/react-components/resources/stitch-api-reference.md

@@ -0,0 +1,14 @@
+# Stitch API reference
+
+This document describes the data structures returned by the Stitch MCP server to ensure accurate component mapping.
+
+### Metadata schema
+When calling `get_screen`, the server returns a JSON object with these key properties:
+* **htmlCode**: Contains a `downloadUrl`. This is a signed URL that requires a system-level fetch (curl) to handle redirects and security handshakes.
+* **screenshot**: Includes a `downloadUrl` for the visual design. Use this to verify layout intent that might not be obvious in the raw HTML.
+* **deviceType**: Usually set to `DESKTOP`. All generated components should prioritize the corresponding viewport (2560px width) as the base layout.
+
+### Technical mapping rules
+1. **Element tracking**: Preserve `data-stitch-id` attributes as comments in the TSX to allow for future design synchronization.
+2. **Asset handling**: Treat background images in the HTML as dynamic data. Extract the URLs into `mockData.ts` rather than hardcoding them into the component styles.
+3. **Style extraction**: The HTML `<head>` contains a localized `tailwind.config`. This config must be merged with the local project theme to ensure colors like `primary` and `background-dark` render correctly.

package/react-components/resources/style-guide.json

@@ -0,0 +1,27 @@
+{
+  "theme": {
+    "colors": {
+      "primary": "#19e66f",
+      "background": {
+        "light": "#f6f8f7",
+        "dark": "#112118",
+        "elevated": "#1A1A1A"
+      },
+      "accent": {
+        "purple": "#8A2BE2",
+        "lavender": "#D0A9F5"
+      }
+    },
+    "typography": {
+      "display": [
+        "Space Grotesk",
+        "sans-serif"
+      ],
+      "icons": "Material Symbols Outlined"
+    },
+    "spacing": {
+      "header-h": "72px",
+      "container-max": "960px"
+    }
+  }
+}

package/react-components/scripts/fetch-stitch.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+URL=$1
+OUTPUT=$2
+if [ -z "$URL" ] || [ -z "$OUTPUT" ]; then
+  echo "Usage: $0 <url> <output_path>"
+  exit 1
+fi
+echo "Initiating high-reliability fetch for Stitch HTML..."
+curl -L -f -sS --connect-timeout 10 --compressed "$URL" -o "$OUTPUT"
+if [ $? -eq 0 ]; then
+  echo "✅ Successfully retrieved HTML at: $OUTPUT"
+  exit 0
+else
+  echo "❌ Error: Failed to retrieve content. Check TLS/SNI or URL expiration."
+  exit 1
+fi

package/react-components/scripts/validate.js

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import swc from '@swc/core';
+import fs from 'node:fs';
+import path from 'node:path';
+
+async function validateComponent(filePath) {
+  const code = fs.readFileSync(filePath, 'utf-8');
+  const filename = path.basename(filePath);
+  try {
+    const ast = await swc.parse(code, { syntax: "typescript", tsx: true });
+    let hasInterface = false;
+    let tailwindIssues = [];
+
+    console.log("🔍 Scanning AST...");
+
+    const walk = (node) => {
+      if (!node) return;
+      if (node.type === 'TsInterfaceDeclaration' && node.id.value.endsWith('Props')) hasInterface = true;
+      if (node.type === 'JSXAttribute' && node.name.name === 'className') {
+        if (node.value?.value && /#[0-9A-Fa-f]{6}/.test(node.value.value)) tailwindIssues.push(node.value.value);
+      }
+      for (const key in node) { if (node[key] && typeof node[key] === 'object') walk(node[key]); }
+    };
+    walk(ast);
+
+    console.log(`--- Validation for: ${filename} ---`);
+    if (hasInterface) {
+      console.log("✅ Props declaration found.");
+    } else {
+      console.error("❌ MISSING: Props interface (must end in 'Props').");
+    }
+
+    if (tailwindIssues.length === 0) {
+      console.log("✅ No hardcoded hex values found.");
+    } else {
+      console.error(`❌ STYLE: Found ${tailwindIssues.length} hardcoded hex codes.`);
+      tailwindIssues.forEach(hex => console.error(`   - ${hex}`));
+    }
+
+    if (hasInterface && tailwindIssues.length === 0) {
+      console.log("\n✨ COMPONENT VALID.");
+      process.exit(0);
+    } else {
+      console.error("\n🚫 VALIDATION FAILED.");
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error("❌ PARSE ERROR:", err.message);
+    process.exit(1);
+  }
+}
+
+validateComponent(process.argv[2]);