@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/playwright/references/agent-browser-cli.md

@@ -0,0 +1,405 @@
+# agent-browser
+
+## When to Use
+
+- When you need Playwright-based browser automation via the agent-browser CLI.
+
+## When NOT to Use
+
+- When MCP-based browser control is required instead of a CLI workflow.
+
+
+## Installation
+
+```bash
+npm install -g agent-browser
+agent-browser install  # Download Chromium
+```
+
+Linux: `agent-browser install --with-deps`
+
+## Architecture
+
+- **Rust CLI** (fast native binary) parses commands, communicates with daemon
+- **Node.js daemon** manages Playwright browser instance, persists between commands
+- Daemon auto-starts on first command, stays alive for fast subsequent ops
+- Each session has own daemon process + Unix socket (or TCP on Windows)
+
+## Core Workflow
+
+1. **Open page**: `agent-browser open <url>`
+2. **Get snapshot**: `agent-browser snapshot -i` (interactive elements only)
+3. **Use refs**: `agent-browser click @e2` / `agent-browser fill @e3 "text"`
+4. **Repeat snapshot** after page changes
+
+## Refs (Primary Selection Method)
+
+Snapshot generates ARIA accessibility tree with `[ref=eN]` tags. Refs map to `getByRole()` locators internally.
+
+```bash
+agent-browser snapshot
+# - heading "Example Domain" [ref=e1] [level=1]
+# - button "Submit" [ref=e2]
+# - textbox "Email" [ref=e3]
+# - link "Learn more" [ref=e4]
+
+agent-browser click @e2           # Click button
+agent-browser fill @e3 "test@example.com"
+agent-browser get text @e1        # Get heading text
+```
+
+Ref syntax: `@e1`, `e1`, or `ref=e1` all work.
+
+**Why refs?**
+
+- Deterministic: points to exact element from snapshot
+- Fast: no DOM re-query, uses cached role/name locator
+- AI-friendly: snapshot + ref workflow optimal for LLMs
+
+### Interactive Roles (get refs automatically)
+
+`button`, `link`, `textbox`, `checkbox`, `radio`, `combobox`, `listbox`, `menuitem`, `option`, `searchbox`, `slider`, `spinbutton`, `switch`, `tab`, `treeitem`
+
+### Content Roles (get refs when named)
+
+`heading`, `cell`, `gridcell`, `columnheader`, `rowheader`, `listitem`, `article`, `region`, `main`, `navigation`
+
+## Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>          # Auto-prepends https:// if needed
+agent-browser back
+agent-browser forward
+agent-browser reload
+agent-browser close               # Closes browser + daemon
+```
+
+### Interaction
+
+```bash
+agent-browser click <sel>         # Left click
+agent-browser dblclick <sel>      # Double click
+agent-browser fill <sel> <text>   # Clear field + set value (atomic)
+agent-browser type <sel> <text>   # Type character by character (preserves existing)
+agent-browser press <key>         # Key press: Enter, Tab, Control+a, Shift+Tab
+agent-browser keydown <key>       # Hold key down
+agent-browser keyup <key>         # Release key
+agent-browser hover <sel>
+agent-browser focus <sel>
+agent-browser select <sel> <val>  # Select dropdown option by value
+agent-browser check <sel>         # Check checkbox
+agent-browser uncheck <sel>       # Uncheck checkbox
+agent-browser scroll up|down|left|right [px]  # Default 300px
+agent-browser scrollintoview <sel>
+agent-browser drag <src> <tgt>    # Drag and drop
+agent-browser upload <sel> <file1> [file2...]
+```
+
+### Get Info
+
+```bash
+agent-browser get text <sel>      # textContent
+agent-browser get html <sel>      # innerHTML
+agent-browser get value <sel>     # input value
+agent-browser get attr <sel> <attr>
+agent-browser get title
+agent-browser get url
+agent-browser get count <sel>     # Number of matching elements
+agent-browser get box <sel>       # Bounding box {x,y,width,height}
+```
+
+### Check State
+
+```bash
+agent-browser is visible <sel>
+agent-browser is enabled <sel>
+agent-browser is checked <sel>
+```
+
+### Snapshot Options
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (buttons, inputs, links)
+agent-browser snapshot -c         # Compact (remove empty structural elements)
+agent-browser snapshot -d 3       # Limit depth to 3 levels
+agent-browser snapshot -s "#main" # Scope to CSS selector
+agent-browser snapshot -i -c -d 5 # Combine options
+```
+
+### Screenshots & PDF
+
+```bash
+agent-browser screenshot [path]   # PNG to stdout (base64) or file
+agent-browser screenshot --full   # Full page screenshot
+agent-browser screenshot -f page.png
+agent-browser pdf <path>          # Save as PDF (format: Letter, A4, etc)
+```
+
+### Wait
+
+```bash
+agent-browser wait <selector>     # Wait for element visible
+agent-browser wait <ms>           # Wait for time (numeric = milliseconds)
+agent-browser wait --text "Welcome"
+agent-browser wait --url "**/dashboard"
+agent-browser wait --load networkidle  # load | domcontentloaded | networkidle
+agent-browser wait --fn "window.ready === true"  # Wait for JS condition
+```
+
+### Find (Semantic Locators)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find placeholder "Search" fill "query"
+agent-browser find alt "Logo" click        # By alt text
+agent-browser find title "Close" click     # By title attribute
+agent-browser find testid "submit-btn" click
+agent-browser find first ".item" click     # First match
+agent-browser find last ".item" click      # Last match
+agent-browser find nth 2 "a" text          # Nth match (0-indexed)
+```
+
+Actions: `click`, `fill`, `check`, `hover`, `text`
+
+### Sessions (Isolated Browser Instances)
+
+```bash
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+AGENT_BROWSER_SESSION=agent1 agent-browser click @e2
+
+agent-browser session list        # List active sessions
+agent-browser session             # Show current session
+```
+
+Each session has: own browser, cookies/storage, navigation history, auth state.
+
+### Storage & Cookies
+
+```bash
+agent-browser cookies             # Get all cookies
+agent-browser cookies set <name> <val>
+agent-browser cookies clear
+
+agent-browser storage local       # Get all localStorage
+agent-browser storage local <key> # Get specific key
+agent-browser storage local set <k> <v>
+agent-browser storage local clear
+agent-browser storage session     # Same for sessionStorage
+```
+
+### Tabs & Windows
+
+```bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab <n>             # Switch to tab n
+agent-browser tab close [n]       # Close tab
+agent-browser window new          # New window (new context)
+```
+
+### Frames
+
+```bash
+agent-browser frame <sel>         # Switch to iframe by selector
+agent-browser frame main          # Back to main frame
+```
+
+### Dialogs (alert/confirm/prompt)
+
+```bash
+agent-browser dialog accept [text]  # Accept (with optional prompt text)
+agent-browser dialog dismiss        # Dismiss
+```
+
+### Network Interception
+
+```bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body '{"mock":true}'  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter by URL pattern
+```
+
+### Browser Settings
+
+```bash
+agent-browser set viewport <w> <h>
+agent-browser set device "iPhone 14"   # Emulate device
+agent-browser set geo <lat> <lng>      # Geolocation
+agent-browser set offline [on|off]     # Toggle offline mode
+agent-browser set media dark|light     # Color scheme
+agent-browser set credentials <u> <p>  # HTTP basic auth
+agent-browser set headers '{"X-Custom":"value"}'
+```
+
+### Debug & Tracing
+
+```bash
+agent-browser --headed open <url>   # Show browser window (not headless)
+agent-browser console               # View console messages
+agent-browser console --clear       # Clear console
+agent-browser errors                # View page errors
+agent-browser errors --clear
+agent-browser highlight <sel>       # Highlight element visually
+agent-browser eval <js>             # Run JavaScript, returns result
+agent-browser trace start [path]    # Start recording trace
+agent-browser trace stop [path]     # Stop and save trace
+```
+
+### Auth State Persistence
+
+```bash
+agent-browser state save auth.json  # Save cookies, localStorage, sessionStorage
+agent-browser state load auth.json  # Load at next launch (must be at browser start)
+```
+
+### Mouse Control
+
+```bash
+agent-browser mouse move <x> <y>    # Move to coordinates
+agent-browser mouse down [button]   # left|right|middle
+agent-browser mouse up [button]
+agent-browser mouse wheel <dy> [dx] # Scroll wheel
+```
+
+## Options
+
+| Option             | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `--session <name>` | Isolated session (or `AGENT_BROWSER_SESSION` env) |
+| `--json`           | JSON output (for parsing)                         |
+| `--full, -f`       | Full page screenshot                              |
+| `--headed`         | Show browser window                               |
+| `--name, -n`       | Locator name filter                               |
+| `--exact`          | Exact text match                                  |
+| `--debug`          | Debug output                                      |
+
+## Selector Types
+
+1. **Refs** (preferred): `@e1`, `@e2` from snapshot
+2. **CSS**: `#id`, `.class`, `div > button`
+3. **Text**: `text=Submit`
+4. **XPath**: `xpath=//button`
+
+## JSON Output Format
+
+```bash
+agent-browser snapshot --json
+# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}
+
+agent-browser get text @e1 --json
+# {"success":true,"data":{"text":"Hello World"}}
+
+agent-browser is visible @e2 --json
+# {"success":true,"data":{"visible":true}}
+```
+
+## Patterns
+
+### Login Flow
+
+```bash
+agent-browser open https://example.com/login
+agent-browser snapshot -i
+# Identify refs for username, password, submit
+agent-browser fill @e2 "username"
+agent-browser fill @e3 "password"
+agent-browser click @e4
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json  # Persist auth for later
+```
+
+### Form Submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i --json
+# Parse refs from JSON response
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser select @e3 "option-value"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --text "Success"
+```
+
+### Scraping Data
+
+```bash
+agent-browser open https://example.com/data
+agent-browser snapshot
+agent-browser get text @e1
+agent-browser get attr @e2 "href"
+agent-browser eval "document.querySelectorAll('.item').length"
+agent-browser eval "JSON.stringify([...document.querySelectorAll('.price')].map(e => e.textContent))"
+```
+
+### Multi-page Navigation
+
+```bash
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e3  # Navigate to new page
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Fresh snapshot for new page
+```
+
+### Parallel Browser Sessions
+
+```bash
+# Terminal 1
+agent-browser --session scraper1 open https://site-a.com
+agent-browser --session scraper1 snapshot -i
+
+# Terminal 2
+agent-browser --session scraper2 open https://site-b.com
+agent-browser --session scraper2 snapshot -i
+```
+
+### Mock API Response
+
+```bash
+agent-browser network route "**/api/users" --body '[{"id":1,"name":"Mock User"}]'
+agent-browser open https://example.com  # App sees mocked data
+agent-browser network unroute "**/api/users"
+```
+
+### Handle File Downloads
+
+```bash
+agent-browser open https://example.com/downloads
+agent-browser snapshot -i
+agent-browser click @e2  # Download button
+# Download handled automatically, saved to suggested filename
+```
+
+## Anti-Patterns
+
+- **Don't use CSS selectors when refs available** - refs from snapshot are deterministic
+- **Don't skip snapshot after page changes** - refs become stale after navigation
+- **Don't use `type` when `fill` works** - `fill` atomically clears + sets, `type` appends
+- **Don't hardcode wait times** - use semantic waits (`--text`, `--url`, `--load`, `--fn`)
+- **Don't use `--headed` in automation** - only for debugging
+- **Don't call `state load` after browser started** - must be at launch time
+
+## Timeouts
+
+Default timeout: 10 seconds (Playwright default is 30s). Commands will fail after timeout if element not found or condition not met.
+
+## Browser Support
+
+| Platform    | Binary      | Fallback |
+| ----------- | ----------- | -------- |
+| macOS ARM64 | Native Rust | Node.js  |
+| macOS x64   | Native Rust | Node.js  |
+| Linux ARM64 | Native Rust | Node.js  |
+| Linux x64   | Native Rust | Node.js  |
+| Windows     | -           | Node.js  |

package/dist/template/.pi/skills/polar/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: polar
+description: Use when implementing payment flows, subscriptions, license keys, or customer portals with Polar. MUST load before writing any checkout, monetization, or billing code using Polar platform.
+---
+
+# Polar Integration
+
+## When to Use
+
+- When implementing Polar checkout, subscriptions, or license key flows.
+
+## When NOT to Use
+
+- When payments are handled by a different platform.
+
+
+## What I Do
+
+- Guide implementation of Polar checkout and payments
+- Help with subscription management and billing
+- Assist with license key validation
+- Set up webhook handlers for payment events
+
+## When to Use Me
+
+- Implementing checkout flow for a product
+- Adding subscription billing to an app
+- Setting up license key validation
+- Building a customer portal
+- Handling payment webhooks
+
+## Quick Start
+
+```bash
+npm install @polar-sh/sdk
+```
+
+```typescript
+import { Polar } from "@polar-sh/sdk";
+
+const polar = new Polar({
+  accessToken: process.env.POLAR_ACCESS_TOKEN!,
+  server: "production", // or "sandbox"
+});
+```
+
+## Key APIs
+
+| API                     | Purpose                           |
+| ----------------------- | --------------------------------- |
+| `polar.products.*`      | Create/manage products and prices |
+| `polar.checkouts.*`     | Create checkout sessions          |
+| `polar.subscriptions.*` | Manage subscriptions              |
+| `polar.orders.*`        | View order history                |
+| `polar.customers.*`     | Customer management               |
+| `polar.licenseKeys.*`   | Issue and validate licenses       |
+
+## Environment Variables
+
+| Variable               | Description                     |
+| ---------------------- | ------------------------------- |
+| `POLAR_ACCESS_TOKEN`   | Organization Access Token (OAT) |
+| `POLAR_WEBHOOK_SECRET` | Webhook signing secret          |
+
+## Common Patterns
+
+### Create Checkout
+
+```typescript
+const checkout = await polar.checkouts.create({
+  productId: "prod_xxx",
+  successUrl: "https://myapp.com/success",
+});
+// Redirect to checkout.url
+```
+
+### Validate License Key
+
+```typescript
+const result = await polar.licenseKeys.validate({
+  key: "XXXX-XXXX-XXXX-XXXX",
+  organizationId: "org_xxx",
+});
+```
+
+### Handle Webhook
+
+```typescript
+import { validateEvent } from "@polar-sh/sdk/webhooks";
+
+const event = validateEvent(body, signature, process.env.POLAR_WEBHOOK_SECRET!);
+// event.type: "subscription.created", "order.created", etc.
+```
+
+## Links
+
+- [Dashboard](https://polar.sh)
+- [API Docs](https://docs.polar.sh/api-reference)
+- [SDK](https://www.npmjs.com/package/@polar-sh/sdk)
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll test payments in production" | Payment bugs cost real money. Test in sandbox with every scenario. |
+| "The webhook handler is simple enough" | Webhook failures mean lost revenue. Validate signatures, handle retries, log everything. |
+| "Subscription logic can go in the frontend" | Pricing logic in the frontend is spoofable. Server-side validation is mandatory. |
+
+## Red Flags
+
+- Payment logic without error handling for all failure modes
+- Webhook signatures not verified
+- Test mode vs live mode not clearly separated in code
+- Subscription state stored locally without server reconciliation
+- Pricing changes deployed without migration plan for existing subscribers
+
+## Verification
+
+After implementing Polar payments:
+
+- [ ] All payment flows tested in sandbox mode
+- [ ] Webhook signatures are verified on every request
+- [ ] Test mode and live mode are explicitly separated in configuration
+- [ ] Error handling covers: declined, expired, insufficient funds, network failure
+- [ ] Subscription state is reconciled server-side, not client-authoritative

package/dist/template/.pi/skills/react-best-practices/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: react-best-practices
+description: MUST load when writing, reviewing, or refactoring React/Next.js code for performance. Covers Vercel Engineering patterns — components, data fetching, bundle optimization, server components. Critical for any Next.js performance work.
+---
+
+# Vercel React Best Practices
+
+## When to Use
+
+- Applying performance guidelines to React/Next.js components or pages.
+
+## When NOT to Use
+
+- Non-React codebases or UI-free/backend-only changes.
+
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category                  | Impact      | Prefix       |
+| -------- | ------------------------- | ----------- | ------------ |
+| 1        | Eliminating Waterfalls    | CRITICAL    | `async-`     |
+| 2        | Bundle Size Optimization  | CRITICAL    | `bundle-`    |
+| 3        | Server-Side Performance   | HIGH        | `server-`    |
+| 4        | Client-Side Data Fetching | MEDIUM-HIGH | `client-`    |
+| 5        | Re-render Optimization    | MEDIUM      | `rerender-`  |
+| 6        | Rendering Performance     | MEDIUM      | `rendering-` |
+| 7        | JavaScript Performance    | LOW-MEDIUM  | `js-`        |
+| 8        | Advanced Patterns         | LOW         | `advanced-`  |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-transitions` - Use startTransition for non-urgent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is straightforward, I don't need the full process" | Simple tasks mask hidden complexity. The process catches what "straightforward" misses. |
+| "I'll reference the docs instead of loading the skill" | Docs describe what. The skill describes how. Both are needed for reliable execution. |
+| "I've used this before, I know the patterns" | Patterns evolve. The skill captures current best practices, not remembered ones. |
+| "The skill's steps add overhead" | The overhead is minutes. The rework from skipping them is hours. |
+
+## Red Flags
+
+- Skill's process steps being skipped without explicit justification
+- Output that doesn't match the skill's expected quality standards
+- No evidence of verification before claiming completion
+- The same shortcut being taken repeatedly (pattern of avoidance)
+
+## Verification
+
+After completing work with this skill:
+
+- [ ] All relevant tests pass
+- [ ] Build succeeds with no new warnings
+- [ ] The skill's process steps were followed in order
+- [ ] No skipped steps without explicit justification
+- [ ] Evidence of completion is documented (test output, screenshots, logs)