myagent-ai 1.0.0

package/skills/finance/Finance_API_Doc.md

@@ -0,0 +1,445 @@
+# Finance API Complete Documentation
+
+## API Overview
+
+Finance API provides comprehensive financial data access interfaces, including real-time market data, historical stock prices, and the latest financial news.
+
+### 🌐 Access via API Gateway
+
+**This API is accessed through the web-dev-ai-gateway unified proxy service.**
+
+**Gateway Configuration:**
+- **Gateway Base URL:** `GATEWAY_URL` (e.g., `https://internal-api.z.ai`)
+- **API Path Prefix:** `API_PREFIX` (e.g., `/external/finance`)
+- **Authentication:** Automatic (gateway injects `x-rapidapi-host` and `x-rapidapi-key`)
+- **Required Header:** `X-Z-AI-From: Z`
+
+**URL Structure:**
+```
+{GATEWAY_URL}{API_PREFIX}/{endpoint}
+```
+
+**Example:**
+- Full URL: `https://internal-api.z.ai/external/finance/v1/markets/search?search=Apple`
+- Breakdown:
+  - `https://internal-api.z.ai` - Gateway base URL (`GATEWAY_URL`)
+  - `/external/finance` - API path prefix (`API_PREFIX`)
+  - `/v1/markets/search` - API endpoint path
+
+
+### Quick Start
+
+```bash
+# Get real-time quote for Apple
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/quote?ticker=AAPL&type=STOCKS" \
+  -H "X-Z-AI-From: Z"
+```
+
+
+## 1. Market Data API
+
+### 1.1 GET v2/markets/tickers - Get All Available Market Tickers
+
+**Parameters:**
+- `page` (optional, Number): Page number, default value is 1
+- `type` (required, String): Asset type, optional values:
+  - `STOCKS` - Stocks
+  - `ETF` - Exchange Traded Funds
+  - `MUTUALFUNDS` - Mutual Funds
+
+**curl example (via Gateway):**
+```bash
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v2/markets/tickers?page=1&type=STOCKS" \
+  -H "X-Z-AI-From: Z"
+```
+
+---
+
+### 1.2 GET v1/markets/search - Search Stocks
+
+**Parameters:**
+- `search` (required, String): Search keyword (company name or stock symbol)
+
+**curl example (via Gateway):**
+```bash
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/search?search=Apple" \
+  -H "X-Z-AI-From: Z"
+```
+
+**Purpose:** Used to find specific stock or company ticker codes
+
+---
+
+### 1.3 GET v1/markets/quote (real-time) - Real-time Quotes
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol (only one can be entered)
+- `type` (required, String): Asset type
+  - `STOCKS` - Stocks
+  - `ETF` - Exchange Traded Funds
+  - `MUTUALFUNDS` - Mutual Funds
+
+**curl example (via Gateway):**
+```bash
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/quote?ticker=AAPL&type=STOCKS" \
+  -H "X-Z-AI-From: Z"
+```
+
+---
+
+### 1.4 GET v1/markets/stock/quotes (snapshots) - Snapshot Quotes
+
+**Parameters:**
+- `ticker` (required, String): Stock symbols, separated by commas
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/quotes?ticker=AAPL%2CMSFT%2C%5ESPX%2C%5ENYA%2CGAZP.ME%2CSIBN.ME%2CGEECEE.NS'
+```
+
+**Purpose:** Batch get snapshot data for multiple stocks
+
+---
+
+
+## 2. Historical Data API
+
+### 2.1 GET v1/markets/stock/history - Stock Historical Data
+
+**Parameters:**
+- `symbol` (required, String): Stock symbol
+- `interval` (required, String): Time interval
+  - `5m` - 5 minutes
+  - `15m` - 15 minutes
+  - `30m` - 30 minutes
+  - `1h` - 1 hour
+  - `1d` - Daily
+  - `1wk` - Weekly
+  - `1mo` - Monthly
+  - `3mo` - 3 months
+- `diffandsplits` (optional, String): Include dividend and split data
+  - `true` - Include
+  - `false` - Exclude (default)
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/history?symbol=AAPL&interval=1d&diffandsplits=false'
+```
+
+**Purpose:** Get historical price data for specific stocks, used for technical analysis and backtesting
+
+---
+
+### 2.2 GET v2/markets/stock/history - Stock Historical Data V2
+
+**Parameters:**
+- `symbol` (required, String): Stock symbol
+- `interval` (optional, String): Time interval
+  - `1m`, `2m`, `3m`, `4m`, `5m`, `15m`, `30m`
+  - `1h`, `1d`, `1wk`, `1mo`, `1qty`
+- `limit` (optional, Number): Limit the number of candles (1-1000)
+- `dividend` (optional, String): Include dividend data (`true` or `false`)
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v2/markets/stock/history?symbol=AAPL&interval=1m&limit=640'
+```
+
+**Purpose:** Enhanced historical data interface
+
+---
+
+## 3. News API
+
+### 3.1 GET v1/markets/news - Market News
+
+**Parameters:**
+- `ticker` (optional, String): Stock symbols, comma-separated for multiple stocks
+
+**curl example:**
+```bash
+# Get general market news
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/news'
+
+# Get specific stock news
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/news?ticker=AAPL,TSLA'
+```
+
+**Purpose:** Get the latest market news and updates
+
+---
+
+### 3.2 GET v2/markets/news - Market News V2
+
+**Parameters:**
+- `ticker` (optional, String): Stock symbol
+- `type` (optional, String): News type (`ALL`, `VIDEO`, `PRESS-RELEASE`)
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v2/markets/news?ticker=AAPL&type=ALL'
+```
+
+**Purpose:** Enhanced interface for getting latest market-related news
+
+---
+
+## 5. Stock Detailed Information API
+
+### 5.1 GET v1/markets/stock/modules (asset-profile) - Company Profile
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=asset-profile'
+```
+
+**Purpose:** Get company basic information, business description, management team, etc.
+
+---
+
+### 5.2 GET v1/stock/modules - Stock Module Data
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+- `module` (required, String): Module name (one per request)
+  - Acceptable values: `profile`, `income-statement`, `balance-sheet`, `cashflow-statement`,
+    `statistics`, `calendar-events`, `sec-filings`, `recommendation-trend`,
+    `upgrade-downgrade-history`, `institution-ownership`, `fund-ownership`,
+    `major-directHolders`, `major-holders-breakdown`, `insider-transactions`,
+    `insider-holders`, `net-share-purchase-activity`, `earnings`, `industry-trend`,
+    `index-trend`, `sector-trend`
+
+**curl example:**
+```bash
+# Get specific module
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=statistics'
+```
+
+**Purpose:** Get one data module per request (price, financial, analyst ratings, etc.)
+
+---
+
+### 5.3 GET v1/markets/stock/modules (statistics) - Stock Statistics
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=statistics'
+```
+
+**Purpose:** Get key statistical indicators such as PE ratios, market cap, trading volume
+
+---
+
+### 5.4 GET v1/markets/stock/modules (financial-data) - Get Financial Data
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+- `module` (required, String): `financial-data`
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=financial-data'
+```
+
+**Purpose:** Get revenue, profit, cash flow and other financial indicators
+
+---
+
+### 5.5 GET v1/markets/stock/modules (sec-filings) - Get SEC Filings
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+- `module` (required, String): `sec-filings`
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=sec-filings'
+```
+
+**Purpose:** Get files submitted by companies to the U.S. Securities and Exchange Commission
+
+---
+
+### 5.6 GET v1/markets/stock/modules (earnings) - Earnings Data
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=earnings'
+```
+
+**Purpose:** Get quarterly and annual earnings information
+
+---
+
+### 5.7 GET v1/markets/stock/modules (calendar-events) - Get Calendar Events
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+- `module` (required, String): `calendar-events`
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=calendar-events'
+```
+
+**Purpose:** Get upcoming earnings release dates, dividend dates, etc.
+
+---
+
+## 6. Financial Statements API
+
+### 7.1 GET v1/markets/stock/modules (balance-sheet) - Balance Sheet
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=balance-sheet'
+```
+
+**Purpose:** Get company balance sheet data
+
+---
+
+### 7.3 GET v1/markets/stock/modules (income-statement) - Income Statement
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=income-statement'
+```
+
+**Purpose:** Get company income statement data
+
+---
+
+### 7.4 GET v1/markets/stock/modules (cashflow-statement) - Cash Flow Statement
+
+**Parameters:**
+- `ticker` (required, String): Stock symbol
+
+**curl example:**
+```bash
+curl --request GET \
+  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=cashflow-statement'
+```
+
+**Purpose:** Get company cash flow statement data
+
+---
+
+## Usage Flow Examples
+
+### Example 1: Find and Get Real-time Stock Data
+
+```bash
+# 1. Search company
+GET /v1/markets/search?search=Apple
+
+# 2. Get real-time quote
+GET /v1/markets/quote?ticker=AAPL&type=STOCKS
+
+# 3. Get detailed information
+GET /v1/markets/stock/modules?ticker=AAPL&module=asset-profile
+```
+
+### Example 2: Analyze Stock Investment Value
+
+```bash
+# 1. Get financial data
+GET /v1/markets/stock/modules?ticker=AAPL&module=financial-data
+
+# 2. Get earnings data
+GET /v1/markets/stock/modules?ticker=AAPL&module=earnings
+```
+
+---
+
+## Usage Tips
+
+### 1. Batch Query Optimization
+```bash
+# Get data for multiple stocks at once (snapshots endpoint) via Gateway
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/quotes?ticker=AAPL,MSFT,GOOGL,AMZN,TSLA" \
+  -H "X-Z-AI-From: Z"
+```
+
+### 2. Time Range Query
+```bash
+# Get historical data with specific interval via Gateway
+curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/history?symbol=AAPL&interval=1d&diffandsplits=false" \
+  -H "X-Z-AI-From: Z"
+```
+
+### 3. Combined Query Example
+### 3. Combined Query Example
+
+**Python example (via Gateway):**
+```python
+import requests
+
+# Gateway automatically handles authentication
+headers = {
+    'X-Z-AI-From': 'Z'
+}
+
+gateway_url = '{GATEWAY_URL}{API_PREFIX}/v1'
+symbol = 'AAPL'
+
+# Get real-time price
+quote = requests.get(f'{gateway_url}/markets/quote?ticker={symbol}&type=STOCKS', headers=headers)
+
+# Get company profile
+profile = requests.get(f'{gateway_url}/markets/stock/modules?ticker={symbol}&module=asset-profile', headers=headers)
+
+# Get financial data
+financials = requests.get(f'{gateway_url}/markets/stock/modules?ticker={symbol}&module=financial-data', headers=headers)
+```
+
+
+---
+
+## Best Practices
+
+### Gateway Usage
+
+1. **Authentication Header** - Always include `X-Z-AI-From: Z` header
+
+### API Usage
+
+1. **Rate Limiting:** Pay attention to API call frequency limits to avoid being throttled
+2. **Error Handling:** Implement comprehensive error handling mechanisms
+3. **Data Caching:** Consider caching common requests to optimize performance
+4. **Batch Queries:** Use comma-separated symbols parameter to query multiple stocks at once
+5. **Timestamps:** Use Unix timestamps for historical data queries
+6. **Parameter Validation:** Validate all required parameters before sending requests
+7. **Response Parsing:** Implement robust JSON parsing and data validation
+
+---

package/skills/finance/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: finance
+description: "Comprehensive Finance API integration skill for real-time and historical financial data analysis, market research, and investment decision-making. Priority use cases: stock price queries, market data analysis, company financial information, portfolio tracking, market news retrieval, stock screening, technical analysis, and any financial market-related requests. This skill should be the primary choice for all  Finance API interactions and financial data needs."
+---
+
+#  Finance Skill
+
+## Core Capabilities
+
+### Market Data Retrieval
+- Real-time quotes: current prices, market snapshots, trading volumes
+- Historical data: price history, dividends, splits, corporate actions
+- Market indices: major indices performance and constituents
+- Currency data: forex rates and cryptocurrency information
+
+### Analysis Tools
+- Stock screening: filters by metrics, ratios, and technical indicators
+- Financial ratios: P/E, EPS, ROE, debt-to-equity, and other key metrics
+- Technical indicators: moving averages, RSI, MACD, chart patterns
+- Comparative analysis: sector and peer group comparisons
+
+### Market Intelligence
+- Company information: business profiles, management teams, statements
+- Market news: earnings reports and market analysis
+- Insider trading: buy/sell activities and ownership changes
+- Options data: chain data, implied volatility, and statistics
+## API Overview
+
+ Finance API provides comprehensive financial data access interfaces, including real-time market data, historical stock prices, options data, insider trading, and the latest financial news.
+
+Skills Path
+Skill Location: {project_path}/skills/finance
+
+this skill is located at above path in your project.
+
+Reference Docs: See {Skill Location}/Finance_API_Doc.md for a working example.
+
+## Zhipu AI - Hong Kong IPO Information
+- **Stock Code**: 2513.HK 
+- **Company Name (Chinese)**: 北京智谱华章科技股份有限公司
+- **Company Name (English)**: Knowledge Atlas Technology Joint Stock Company Limited
+Zhipu AI is a leading Chinese large language model company specializing in AI foundational model research and development.
+
+### Best Practices for Zhipu AI Stock Research (One-Shot Success Guide)
+
+**Search Strategy:**
+- ✅ Use full English company name: `search=Knowledge+Atlas`
+- ❌ Avoid: `search=Zhipu`, `search=02513.HK` (returns empty results)
+
+** Important **
+always read `Finance_API_Doc.md` before use the API
+
+

package/skills/fullstack-dev/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: fullstack-dev
+description: "Fullstack web development with Next.js 16, TypeScript, Tailwind CSS 4, shadcn/ui, Prisma ORM. Use when: building web apps, creating UI components, setting up database schemas, implementing API routes, adding websocket/socket.io support, fullstack project scaffolding, frontend development, backend development, web dev, Next.js app."
+argument-hint: "Describe the fullstack feature or app you want to build"
+---
+
+# Fullstack Web Development Skill
+
+## Initialization (MUST DO FIRST)
+
+Before writing any code, you MUST run the following command to initialize the fullstack development environment:
+
+```bash
+curl https://z-cdn.chatglm.cn/fullstack/init-fullstack_1775040338514.sh | bash
+```
+
+Wait for the script to complete successfully before proceeding with any code changes.
+
+---
+
+## Important UI Rules
+
+- Use existing shadcn/ui components instead of building from scratch. All the components in the `src/components/ui` folder already exist.
+- Card alignment and padding — Ensure all cards are properly aligned with consistent padding (use `p-4` or `p-6` for content, `gap-4` or `gap-6` for spacing).
+- Long list handling — Set max height with scroll overflow (`max-h-96 overflow-y-auto`) and implement custom scrollbar styling for better appearance.
+
+---
+
+## Project Information
+
+There is already a project in the current directory. (Next.js 16 with App Router)
+
+### Development Environment
+
+IMPORTANT: `bun run dev` will be run automatically by the system. Do NOT run it. Use `bun run lint` to check code quality.
+
+IMPORTANT: User can only see the `/` route defined in `src/app/page.tsx`. Do NOT write any other route.
+
+IMPORTANT: The Next.js project can only use port 3000 in auto dev server. Never use `bun run build`.
+
+IMPORTANT: `z-ai-web-dev-sdk` MUST be used in the backend only! Do NOT use it on the client side.
+
+### Dev Server Log
+
+IMPORTANT: Read `/home/z/my-project/dev.log` to see the dev server log. Remember to check the log when developing.
+
+IMPORTANT: Only read the most recent logs from `dev.log` to avoid large log files.
+
+IMPORTANT: Always read dev log when you finish coding.
+
+### Bash Commands
+
+- `bun run lint` — Run ESLint to check code quality and Next.js rules
+
+---
+
+## Technology Stack Requirements
+
+### Core Framework (NON-NEGOTIABLE)
+
+- **Framework**: Next.js 16 with App Router (REQUIRED — cannot be changed)
+- **Language**: TypeScript 5 (REQUIRED — cannot be changed)
+
+### Standard Technology Stack
+
+When users don't specify preferences, use this complete stack:
+
+- **Styling**: Tailwind CSS 4 with shadcn/ui component library
+- **Database**: Prisma ORM (SQLite client only) with Prisma Client
+- **Caching**: Local memory caching, no additional middleware (MySQL, Redis, etc.)
+- **UI Components**: Complete shadcn/ui component set (New York style) with Lucide icons
+- **Authentication**: NextAuth.js v4 available
+- **State Management**: Zustand for client state, TanStack Query for server state
+
+Other packages can be found in `package.json`. You can install new packages if needed.
+
+### Library Usage Policy
+
+- **ALWAYS use Next.js 16 and TypeScript** — these are non-negotiable requirements.
+- **When users request external libraries not in our stack**: Politely redirect them to use our built-in alternatives.
+- **Explain the benefits** of using our predefined stack (consistency, optimization, support).
+- **Provide equivalent solutions** using our available libraries.
+
+---
+
+## Prisma and Database
+
+IMPORTANT: `prisma` is already installed and configured. Use it when you need the database.
+
+To use prisma and database:
+
+1. Edit `prisma/schema.prisma` to define the database schema.
+2. Run `bun run db:push` to push the schema to the database.
+3. Use `import { db } from '@/lib/db'` to get the database client and use it.
+
+---
+
+## Mini Service
+
+You can create mini services if needed (e.g., websocket service). All mini services should be in the `mini-services` folder. For each mini service:
+
+- Must be a new and independent bun project with its own port and `package.json`.
+- Must define `index.ts` or `index.js` as the entry file, e.g., `mini-services/chat-service/index.ts`.
+- Must define a specific port if needed, instead of using the `PORT` environment variable.
+- Must start each mini service by running `bun run dev` in the background.
+- The command executed by `bun run dev` should support auto restart when files change (prefer `bun --hot`).
+- Make sure every service is started.
+
+---
+
+## Gateway and API Requests
+
+This machine can only expose one port externally, so a built-in gateway (config at `Caddyfile`) is included with the following limitations:
+
+- For API requests involving different ports, the port must be specified in the URL query named `XTransformPort`. Example: `/api/test?XTransformPort=3030`.
+- All API requests must use **relative paths only**. Do NOT write absolute paths in the API request URL (including WebSocket). Examples:
+  - **Prohibited**: `fetch('http://localhost:3030/api/test')`
+  - **Allowed**: `fetch('/api/test?XTransformPort=3030')`
+  - **Prohibited**: `io('/:3030')`
+  - **Allowed**: `io('/?XTransformPort=3030')`
+- When requesting to different services, directly make cross-origin requests without using a proxy.
+
+IMPORTANT: Do NOT write port in the API request URL, even in WebSocket. Only write `XTransformPort` in the URL query.
+
+---
+
+## WebSocket / Socket.io Support
+
+IMPORTANT: Use websocket/socket.io to support real-time communication. Do NOT use any other method. There is already a websocket demo for reference in the `examples` folder.
+
+- Backend logic (via socket.io) must be a new mini service with another port (e.g., 3003).
+- Frontend request should ALWAYS be `io("/?XTransformPort={Port}")`, and the path ALWAYS be `/` so that Caddy can forward to the correct port.
+- NEVER use `io("http://localhost:{Port}")` or any direct port-based connection.
+
+---
+
+## Code Style
+
+- Prefer to use existing components and hooks.
+- TypeScript throughout with strict typing.
+- ES6+ import/export syntax.
+- shadcn/ui components preferred over custom implementations.
+- Use `'use client'` and `'use server'` for client and server side code.
+- The Prisma schema primitive type cannot be a list.
+- Put the Prisma schema in the `prisma` folder.
+- Put the db file in the `db` folder.
+
+---
+
+## Styling
+
+1. Use the shadcn/ui library unless the user specifies otherwise.
+2. Avoid using indigo or blue colors unless specified in the user's request.
+3. MUST generate responsive designs.
+4. The Code Project is rendered on top of a white background. If a different background color is needed, use a wrapper element with a background color Tailwind class.
+
+---
+
+## UI/UX Design Standards
+
+### Visual Design
+
+- **Color System**: Use Tailwind CSS built-in variables (`bg-primary`, `text-primary-foreground`, `bg-background`).
+- **Color Restriction**: NO indigo or blue colors unless explicitly requested.
+- **Theme Support**: Implement light/dark mode with `next-themes`.
+- **Typography**: Consistent hierarchy with proper font weights and sizes.
+
+### Responsive Design (MANDATORY)
+
+- **Mobile-First**: Design for mobile, then enhance for desktop.
+- **Breakpoints**: Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`).
+- **Touch-Friendly**: Minimum 44px touch targets for interactive elements.
+
+### Layout (MANDATORY)
+
+- **Sticky Footer Required**: If a `footer` exists, it MUST stick to the bottom of the viewport when content is shorter than one screen height (no floating/empty gap below).
+- **Natural Push on Overflow**: When content exceeds the viewport height, the footer MUST be pushed down naturally (never overlay or cover content).
+- **Recommended Implementation (Tailwind)**: Use a root wrapper with `min-h-screen flex flex-col`, and apply `mt-auto` to the `footer`.
+- **Mobile Safe Area**: On devices with safe areas (e.g., iOS), the footer MUST respect bottom safe area insets when applicable.
+
+### Accessibility (MANDATORY)
+
+- **Semantic HTML**: Use `main`, `header`, `nav`, `section`, `article`.
+- **ARIA Support**: Proper roles, labels, and descriptions.
+- **Screen Readers**: Use `sr-only` class for screen reader content.
+- **Alt Text**: Descriptive alt text for all images.
+- **Keyboard Navigation**: Ensure all elements are keyboard accessible.
+
+### Interactive Elements
+
+- **Loading States**: Show spinners/skeletons during async operations.
+- **Error Handling**: Clear, actionable error messages.
+- **Feedback**: Toast notifications for user actions.
+- **Animations**: Subtle Framer Motion transitions (hover, focus, page transitions).
+- **Hover Effects**: Interactive feedback on all clickable elements.
+
+### Sandbox Preview Instructions (CRITICAL)
+
+This project runs in a restricted cloud sandbox environment.
+
+- **NEVER** instruct the user to visit `http://localhost:3000`, `127.0.0.1`, or any local ports directly. These addresses are internal and not accessible to the user.
+- **ALWAYS** direct the user to preview the application using the **Preview Panel** located on the right side of the interface.
+- **ALWAYS** inform the user about how to view the application externally based on their platform:
+  - If they are using the web interface, tell them they can click the **"Open in New Tab"** button above the Preview Panel to view it in a separate browser tab.
+  - If they are communicating through an IM (Instant Messaging) platform, provide them directly with the generated preview link.