@muskanmeet/invoicing-design-system 0.1.0

package/.local/skills/video-js/references/scene_selectors.md

@@ -0,0 +1,428 @@
+---
+name: video-scene-controls
+description: Add interactive scene controls (jump, lock-loop, progress bar) to video-js artifacts. Use when building or updating the scene selector overlay for animated videos. Replaces the old scene_selectors.md pattern with a cleaner hook-based architecture.
+---
+
+# Video Scene Controls
+
+Interactive control bar for video-js artifacts that lets viewers jump between scenes and lock-loop individual scenes. The bar renders only inside an iframe (the Replit preview pane) so exports stay clean.
+
+## Architecture
+
+Three files, clear separation of concerns:
+
+| File | Role |
+| --- | --- |
+| `useSceneControls.ts` | Hook that encapsulates all playback workarounds behind a clean index-based API |
+| `VideoWithControls.tsx` | Wrapper component: iframe gate, control bar UI, hover/tap reveal |
+| `VideoTemplate.tsx` | Scene renderer: accepts optional `durations`, `loop`, `onSceneChange` props |
+
+### Why the workarounds exist
+
+The `useVideoPlayer` hook in `src/lib/video/hooks.ts` is read-only (the recording/export pipeline depends on it). It accepts a static `durations` object and advances linearly. It has no `seekTo`, `loopCurrent`, or `setActiveScene` API. The `useSceneControls` hook works around these limitations:
+
+- **Jumping to a scene**: Rotate the durations object so the target scene is first, then remount `VideoTemplate` via a `mountKey` bump.
+- **Scene-lock looping**: Create a 2-entry durations object with the same scene under `_r1` / `_r2` suffixes. A single entry won't loop because `setCurrentScene(0)` is a no-op when already at 0.
+- **Tracking the active scene**: `VideoTemplate` calls `onSceneChange(rawKey)` on every scene transition. The hook strips `_r1`/`_r2` suffixes and maps back to the original index.
+
+These workarounds are hidden inside the hook. Consumers just use `jumpTo(index)` and `toggleLock()`.
+
+## When to use
+
+Run this step once, right after the design subagent finishes the initial video build and workflow logs are clean. Skip on iteration prompts. The main agent runs this directly — never delegate to a subagent.
+
+## Files to create/edit
+
+### 1. `useSceneControls.ts`
+
+```tsx
+import { useCallback, useMemo, useState } from 'react';
+
+const REPEAT_SUFFIX_RE = /_r[12]$/;
+
+export function stripRepeatSuffix(key: string): string {
+  return key.replace(REPEAT_SUFFIX_RE, '');
+}
+
+function rotateFromIndex(
+  durations: Record<string, number>,
+  startIndex: number,
+): Record<string, number> {
+  const keys = Object.keys(durations);
+  if (startIndex <= 0) return durations;
+  const result: Record<string, number> = {};
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[(startIndex + i) % keys.length];
+    result[key] = durations[key];
+  }
+  return result;
+}
+
+function buildLockedDurations(key: string, duration: number): Record<string, number> {
+  return { [`${key}_r1`]: duration, [`${key}_r2`]: duration };
+}
+
+export function useSceneControls(baseDurations: Record<string, number>) {
+  const sceneKeys = useMemo(() => Object.keys(baseDurations), [baseDurations]);
+
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [locked, setLocked] = useState(false);
+  const [mountKey, setMountKey] = useState(0);
+  const [tick, setTick] = useState(0);
+
+  const durations = useMemo(() => {
+    if (locked) {
+      const key = sceneKeys[activeIndex];
+      return buildLockedDurations(key, baseDurations[key]);
+    }
+    return rotateFromIndex(baseDurations, activeIndex);
+  }, [locked, activeIndex, sceneKeys, baseDurations]);
+
+  const onSceneChange = useCallback(
+    (rawKey: string) => {
+      const clean = stripRepeatSuffix(rawKey);
+      const idx = sceneKeys.indexOf(clean);
+      if (idx >= 0) setActiveIndex(idx);
+      setTick((t) => t + 1);
+    },
+    [sceneKeys],
+  );
+
+  const jumpTo = useCallback((index: number) => {
+    setActiveIndex(index);
+    setMountKey((k) => k + 1);
+    setTick((t) => t + 1);
+  }, []);
+
+  const toggleLock = useCallback(() => {
+    setLocked((prev) => !prev);
+    setMountKey((k) => k + 1);
+    setTick((t) => t + 1);
+  }, []);
+
+  return {
+    sceneKeys,
+    activeIndex,
+    locked,
+    mountKey,
+    tick,
+    durations,
+    activeDuration: baseDurations[sceneKeys[activeIndex]] ?? 0,
+    onSceneChange,
+    jumpTo,
+    toggleLock,
+  };
+}
+```
+
+**Hook API:**
+
+| Return value | Type | Description |
+| --- | --- | --- |
+| `sceneKeys` | `string[]` | Original scene keys in order |
+| `activeIndex` | `number` | Index of the currently playing scene |
+| `locked` | `boolean` | Whether scene-lock is on |
+| `mountKey` | `number` | Increments on jump/lock — use as `key` on `VideoTemplate` to force remount |
+| `tick` | `number` | Increments on every scene change — drives progress bar reset |
+| `durations` | `Record<string, number>` | Computed durations object to pass to `VideoTemplate` |
+| `activeDuration` | `number` | Duration of the currently active scene in ms |
+| `onSceneChange` | `(rawKey: string) => void` | Pass to `VideoTemplate`'s `onSceneChange` prop |
+| `jumpTo` | `(index: number) => void` | Jump to scene by index |
+| `toggleLock` | `() => void` | Toggle scene-lock |
+
+### 2. VideoTemplate changes
+
+Export `SCENE_DURATIONS` and accept optional props. Strip `_r[12]` suffixes to resolve scene components:
+
+```tsx
+export const SCENE_DURATIONS = { /* design subagent's values */ };
+const SCENE_COMPONENTS: Record<string, React.ComponentType> = {
+  /* map each duration key to its scene component */
+};
+export default function VideoTemplate({
+  durations = SCENE_DURATIONS,
+  loop = true,
+  onSceneChange,
+}: {
+  durations?: Record<string, number>;
+  loop?: boolean;
+  onSceneChange?: (sceneKey: string) => void;
+} = {}) {
+  const { currentScene, currentSceneKey } = useVideoPlayer({ durations, loop });
+  useEffect(() => { onSceneChange?.(currentSceneKey); }, [currentSceneKey, onSceneChange]);
+  const baseSceneKey = currentSceneKey.replace(/_r[12]$/, '') as keyof typeof SCENE_DURATIONS;
+  const sceneIndex = Object.keys(SCENE_DURATIONS).indexOf(baseSceneKey);
+  const SceneComponent = SCENE_COMPONENTS[baseSceneKey];
+  return (
+    <div className="relative w-full h-screen overflow-hidden">
+      {/* ... persistent background/midground layers using sceneIndex for position arrays ... */}
+      <AnimatePresence mode="popLayout">
+        {SceneComponent && <SceneComponent key={currentSceneKey} />}
+      </AnimatePresence>
+    </div>
+  );
+}
+```
+
+**IMPORTANT — AnimatePresence key must be `currentSceneKey`, NOT `baseSceneKey`.** When scene-lock is active, the hook creates two durations entries with `_r1` / `_r2` suffixes that both map to the same base scene. If you use `baseSceneKey` as the key, both iterations produce the same key and AnimatePresence won't re-mount/re-animate the scene — causing the loop to appear frozen. Using `currentSceneKey` (which includes the suffix) ensures the key alternates between e.g. `build2_r1` and `build2_r2`, triggering a proper exit/enter cycle on every loop.
+
+For persistent elements that use index-based position arrays (e.g. bottle position, background opacity), use `sceneIndex` (derived from `baseSceneKey`) instead of `currentScene` — this ensures they resolve to the correct position regardless of duration rotation.
+
+Defaults preserve existing behavior so the export path (`<VideoTemplate />` with no props) is identical to pre-controls behavior.
+
+### 3. VideoWithControls wrapper
+
+```tsx
+export default function VideoWithControls() {
+  const isIframed = typeof window !== 'undefined' && window.self !== window.top;
+
+  const {
+    sceneKeys, activeIndex, locked, mountKey, tick,
+    durations, activeDuration, onSceneChange, jumpTo, toggleLock,
+  } = useSceneControls(SCENE_DURATIONS);
+
+  // ... collapse/hover/tap state ...
+
+  // Export path: no props, preserves recording markers
+  if (!isIframed) return <VideoTemplate />;
+
+  return (
+    <div className="relative w-full h-screen">
+      <VideoTemplate
+        key={mountKey}
+        durations={durations}
+        loop
+        onSceneChange={onSceneChange}
+      />
+      {/* Control bar sensor + ControlBar component */}
+    </div>
+  );
+}
+```
+
+Update `App.tsx` to render `VideoWithControls` instead of `VideoTemplate`.
+
+## Control bar UI
+
+Full-width strip at the bottom of the video. Left-to-right inside the bar: **scene-lock button, vertical divider, segmented progress bar, scene counter, collapse chevron**. The bar sits inside a taller invisible hover sensor so it reappears on mouseover after the user has collapsed it.
+
+### Visibility behavior
+
+- Bar shows by default on load.
+- Clicking the chevron hides it (slides down via `translate-y-full opacity-0 pointer-events-none`).
+- While collapsed, moving the mouse into the bottom `height: 25%` of the video reveals it. Leaving the sensor hides it again.
+- Clicking the chevron a second time (it now reads `ChevronUp`) pins the bar visible again even when the mouse leaves.
+- On touch, tapping inside the sensor while collapsed pins the bar until the user taps outside the sensor.
+- Use `translate-y` + `opacity` for the slide — not `display: none`, which would kill the hover sensor.
+
+### ControlBar
+
+```tsx
+const PROGRESS_TICK_MS = 60;
+
+interface ControlBarProps {
+  visible: boolean;
+  collapsed: boolean;
+  locked: boolean;
+  sceneKeys: string[];
+  activeIndex: number;
+  activeDuration: number;
+  tick: number;
+  onToggleLock: () => void;
+  onJumpTo: (index: number) => void;
+  onToggleCollapsed: () => void;
+}
+
+function ControlBar({
+  visible, collapsed, locked, sceneKeys, activeIndex, activeDuration, tick,
+  onToggleLock, onJumpTo, onToggleCollapsed,
+}: ControlBarProps) {
+  return (
+    <div
+      className={`flex items-center gap-3 bg-black/50 backdrop-blur-sm px-5 py-4 transition-all duration-200 ease-out ${
+        visible
+          ? 'translate-y-0 opacity-100 pointer-events-auto'
+          : 'translate-y-full opacity-0 pointer-events-none'
+      }`}
+      aria-hidden={!visible}
+    >
+      <button
+        onClick={onToggleLock}
+        className={`w-14 h-14 flex items-center justify-center transition-colors rounded-lg shrink-0 ${
+          locked
+            ? 'text-white bg-white/15 hover:bg-white/25'
+            : 'text-white/60 hover:text-white hover:bg-white/10'
+        }`}
+        title={locked ? 'Loop current scene: on' : 'Loop current scene: off'}
+        aria-label={locked ? 'Loop current scene: on' : 'Loop current scene: off'}
+        aria-pressed={locked}
+      >
+        <Repeat className="w-8 h-8" />
+      </button>
+
+      <div className="w-px self-stretch bg-white/15" aria-hidden="true" />
+
+      <ProgressSegments
+        sceneKeys={sceneKeys}
+        activeIndex={activeIndex}
+        activeDuration={activeDuration}
+        tick={tick}
+        onJumpTo={onJumpTo}
+      />
+
+      <div className="text-xl text-white/60 font-mono tabular-nums shrink-0">
+        {activeIndex + 1}/{sceneKeys.length}
+      </div>
+
+      <button
+        onClick={onToggleCollapsed}
+        className="w-14 h-14 flex items-center justify-center text-white/60 hover:text-white hover:bg-white/10 transition-colors rounded-lg shrink-0"
+        title={collapsed ? 'Show controls' : 'Hide controls'}
+        aria-label={collapsed ? 'Show controls' : 'Hide controls'}
+        aria-expanded={!collapsed}
+      >
+        {collapsed ? <ChevronUp className="w-10 h-10" /> : <ChevronDown className="w-10 h-10" />}
+      </button>
+    </div>
+  );
+}
+```
+
+### ProgressSegments (isolated timer)
+
+The 60ms interval lives here so its ticks don't re-render `VideoWithControls` or `VideoTemplate`.
+
+```tsx
+function ProgressSegments({
+  sceneKeys, activeIndex, activeDuration, tick, onJumpTo,
+}: {
+  sceneKeys: string[];
+  activeIndex: number;
+  activeDuration: number;
+  tick: number;
+  onJumpTo: (index: number) => void;
+}) {
+  const [elapsed, setElapsed] = useState(0);
+
+  useEffect(() => {
+    setElapsed(0);
+    const start = performance.now();
+    const id = window.setInterval(() => {
+      setElapsed(performance.now() - start);
+    }, PROGRESS_TICK_MS);
+    return () => window.clearInterval(id);
+  }, [tick]);
+
+  const progress = activeDuration > 0 ? Math.min(1, elapsed / activeDuration) : 0;
+
+  return (
+    <div className="flex-1 flex items-center gap-1.5">
+      {sceneKeys.map((key, i) => {
+        const isActive = i === activeIndex;
+        const fill = isActive ? progress * 100 : 0;
+        return (
+          <button
+            key={key}
+            onClick={() => onJumpTo(i)}
+            className="flex-1 h-3 bg-white/20 rounded-full overflow-hidden cursor-pointer hover:h-4 hover:bg-white/25 transition-all relative min-h-[12px]"
+            aria-label={`Jump to scene ${i + 1}`}
+            aria-current={isActive ? 'true' : undefined}
+          >
+            <div
+              className="absolute inset-y-0 left-0 bg-white/90 rounded-full transition-[width] duration-100"
+              style={{ width: `${fill}%` }}
+            />
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+### Sizing notes
+
+- Scene-lock and chevron buttons are both `w-14 h-14` (56px). Scene-lock icon is `w-8 h-8`; chevron is `w-10 h-10` because `ChevronDown`/`ChevronUp` read visually lighter than `Repeat` at the same size.
+- Progress segments are `h-3` normally, `h-4` on hover (makes them easier to click). `flex-1` keeps them equal width.
+- Scene counter is `text-xl` so it reads alongside the 32–40px icons.
+- Bar container padding is `px-5 py-4`; gap between elements is `gap-3`.
+- No text labels on segments — `aria-label` only. The scene counter gives the "N/total" context.
+
+### Sensor + reveal (inside `VideoWithControls`)
+
+```tsx
+const sensorRef = useRef<HTMLDivElement | null>(null);
+const [collapsed, setCollapsed] = useState(false);
+const [hovering, setHovering] = useState(false);
+const [tapPinned, setTapPinned] = useState(false);
+
+const handlePointerEnter = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+  if (e.pointerType === 'mouse') setHovering(true);
+}, []);
+const handlePointerLeave = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+  if (e.pointerType === 'mouse') setHovering(false);
+}, []);
+const handlePointerDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+  if (e.pointerType === 'mouse') return;
+  if (collapsed) setTapPinned(true);
+}, [collapsed]);
+const handleToggleCollapsed = useCallback(() => {
+  setCollapsed(c => {
+    // Clear any stale hover/tap-pin state so the chevron click wins.
+    if (!c) { setHovering(false); setTapPinned(false); }
+    return !c;
+  });
+}, []);
+
+// Clear tapPinned when the user taps outside the sensor.
+useEffect(() => {
+  if (!(collapsed && tapPinned)) return;
+  const onDocPointerDown = (e: PointerEvent) => {
+    if (e.pointerType === 'mouse') return;
+    const sensor = sensorRef.current;
+    if (sensor && !sensor.contains(e.target as Node)) setTapPinned(false);
+  };
+  document.addEventListener('pointerdown', onDocPointerDown);
+  return () => document.removeEventListener('pointerdown', onDocPointerDown);
+}, [collapsed, tapPinned]);
+
+const barVisible = !collapsed || hovering || tapPinned;
+
+// In the return():
+<div
+  ref={sensorRef}
+  className="absolute bottom-0 left-0 right-0 z-50 flex flex-col justify-end"
+  style={{ height: '25%' }}
+  onPointerEnter={handlePointerEnter}
+  onPointerLeave={handlePointerLeave}
+  onPointerDown={handlePointerDown}
+>
+  <div className="flex-1 w-full" aria-hidden="true" />
+  <ControlBar
+    visible={barVisible}
+    collapsed={collapsed}
+    locked={locked}
+    sceneKeys={sceneKeys}
+    activeIndex={activeIndex}
+    activeDuration={activeDuration}
+    tick={tick}
+    onToggleLock={toggleLock}
+    onJumpTo={jumpTo}
+    onToggleCollapsed={handleToggleCollapsed}
+  />
+</div>
+```
+
+The invisible `flex-1 w-full` filler above the bar gives the pointer a target area to mouse into while the bar is hidden. The sensor stays mounted at all times so `onPointerEnter` re-fires on every re-entry, not just the first.
+
+## Recording safety
+
+- **Export path** (`!isIframed`): renders `<VideoTemplate />` with no props. `startRecording` fires on mount, `stopRecording` after the last scene. No rotation, no lock, no remounts.
+- **Preview path** (iframed): `window.startRecording` / `window.stopRecording` are undefined, so marker calls are no-ops. Mount key bumps are safe.
+
+## Validation
+
+1. Run `bash scripts/validate-recording.sh` — fix any issues.
+2. Restart the workflow.
+3. Read logs — fix build errors until clean.
+4. Call `presentArtifact`.

package/.local/skills/web-search/.fingerprint

@@ -0,0 +1 @@
+bc95ce25fa8d00f8d30221cd174df5bb

package/.local/skills/web-search/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: web-search
+description: Search the web, fetch content, extract branding profiles, and capture screenshots from URLs. Use for real-time information, API documentation, current events, design matching, and visual reference.
+---
+
+# Web Search Skill
+
+## When to Use
+
+- Real-time information (news, prices, events)
+- Looking up API documentation or SDK guides
+- Current technical information beyond training data
+- Verifying facts from authoritative sources
+
+## When NOT to Use
+
+- Replit-specific features (use the `replit-docs` skill)
+- Searching for real web images or logo files (use the `image-search` skill)
+- Image or video generation (use the `media-generation` skill)
+- Code search within the project (use grep/glob tools)
+
+## Available Functions
+
+### Single web search — webSearch(query)
+
+**Parameters:**
+
+- `query` (str, required): Natural language search query phrased as a complete question
+
+**Returns:** Dict with `searchAnswer` and `resultPages` (list of title/url/snippet dicts)
+
+**Example:**
+
+```javascript
+const results = await webSearch({ query: "OpenAI API rate limits 2026" });
+for (const page of results.resultPages) {
+    console.log(`${page.title}: ${page.url}`);
+}
+```
+
+### Multiple web searches — webSearch({ queries })
+
+Run multiple searches concurrently (max 10).
+
+**Parameters:**
+
+- `queries` (list[str]): List of natural language search queries phrased as complete questions
+
+**Returns:** List of result dicts, each with `searchAnswer` and `resultPages` (list of title/url/snippet dicts)
+
+**Example:**
+
+```javascript
+const results = await webSearch({
+    queries: ["OpenAI API rate limits 2026", "Anthropic API rate limits 2026"]
+});
+```
+
+### webFetch(url)
+
+Fetch and extract content from a URL as markdown.
+
+**Parameters:**
+
+- `url` (str, required): Full HTTPS URL to fetch
+
+**Returns:** Dict with `markdown` key containing page content
+
+**Example:**
+
+```javascript
+const content = await webFetch({ url: "https://platform.openai.com/docs/guides/rate-limits" });
+console.log(content.markdown.slice(0, 1000));
+```
+
+## Best Practices
+
+1. **Use natural language queries**: write queries as complete questions with context.
+2. **Chain search and fetch**: search first, then fetch specific pages for details.
+3. **Be specific**: include dates, versions, or other specifics in queries.
+4. **Verify with fetch**: don't rely only on search snippets for critical information.
+5. **Use branding for design matching**: when replicating a site's visual style, use `extractBranding` to get exact colors, fonts, and spacing.
+6. **Use screenshot for visual reference**: when you need to see what a site looks like before replicating its design.
+
+## Example Workflow
+
+```javascript
+// Find information about a topic
+const searchResult = await webSearch({ query: "FastAPI dependency injection tutorial 2026" });
+
+// Get full content from the most relevant result
+if (searchResult.resultPages.length > 0) {
+    const bestUrl = searchResult.resultPages[0].url;
+    const fullContent = await webFetch({ url: bestUrl });
+    console.log(fullContent.markdown);
+}
+```
+
+## Limitations
+
+- Cannot access social media platforms (LinkedIn, Twitter, Instagram, Facebook, Reddit, YouTube)
+- Cannot download media files (images, videos, audio)
+- Paywalled or authenticated content may be inaccessible
+
+## Copyright
+
+- Respect copyright for media content from websites.
+- You can reference or link to public content.
+- Do not copy media files (images, videos, audio) directly from websites.
+- Use the `media-generation` skill for images and videos instead.

package/.local/skills/whop/.fingerprint

@@ -0,0 +1 @@
+28bf49da5a3e237c44d0dbeb138b60ff

package/.local/skills/whop/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: whop
+description: Guidelines for using Whop to integrate commerce, payment plans, checkout, and subscription management
+---
+
+IMPORTANT: You have everything you need. Do NOT ask the user for Whop Company ID, Plan ID, or API key — retrieve them yourself (Step 1 and Step 3 below). Use Whop's hosted checkout (redirect-based) for payments (Step 4). For access control, verify the user's Whop account and ask Whop whether that account has access; do not treat a redirect, email string, or client state as proof of purchase. Execute the steps directly — do not plan or re-read references before acting.
+
+## Helper scripts — write these first
+
+Write these two files to the project root using the sources in `./references/`. Run via `shell_exec` (NOT `code_execution` — `process.env` is unavailable there). The proxy injects `api_key` automatically — no credentials needed.
+
+**whop-mcp.mjs** (source: `./references/whop-mcp.mjs`) — for MCP tools:
+```bash
+node whop-mcp.mjs --list-tools                              # discover available tools
+node whop-mcp.mjs --schema create_plan                      # check params before calling
+node whop-mcp.mjs create_product '{"title":"Pro Access"}'   # call a tool
+```
+
+**whop-api.mjs** (source: `./references/whop-api.mjs`) — for REST API:
+```bash
+node whop-api.mjs POST /api/v1/plans '{"company_id":"biz_xxx","product_id":"prod_xxx","initial_price":9.99,"currency":"usd","billing_period":30}'
+node whop-api.mjs POST /api/v1/checkout_configurations '{"plan_id":"plan_xxx","redirect_url":"https://myapp.repl.co/done"}'
+node whop-api.mjs GET '/api/v1/payments?company_id=biz_xxx&first=10&order=created_at&direction=desc'
+node whop-api.mjs GET '/api/v1/payments?company_id=biz_xxx&checkout_configuration_ids[]=ch_xxx'
+```
+
+Always run `--schema <tool>` before calling an unfamiliar MCP tool.
+
+## Step 1: Connect and get credentials
+
+1. Propose the Whop integration if not already connected (reference `integrations` skill).
+   The connection is auto-provisioned — no user login or OAuth. A Whop store is created automatically.
+2. Call `listConnections('whop')` in `code_execution` to get `company_id` (biz_xxx) and `api_key` (apik_xxx).
+3. Store `company_id` as a Replit Configuration named `WHOP_COMPANY_ID`.
+
+## Step 2: Write server code
+
+Write **whopClient.ts** to the API server directory (source: `./references/whopClient.ts`). This provides `getWhopClient()` which lazily fetches credentials from the Replit connection API. Never import it in frontend code.
+
+Install: `pnpm add @whop/sdk`
+
+Use the app's existing server and auth patterns. Read `./references/code-templates.md` only if you need route shape or SDK method names; adapt it instead of copying it verbatim.
+
+## Key facts and references
+
+- **Whop plan = Stripe product/price.** When user says "create a product," they mean create a Whop plan.
+- **Products** are just groupings — not directly purchasable.
+- Prices are in **dollars** (9.99 = $9.99, 100 = $100). NOT cents like Stripe.
+- Dates are **ISO 8601 strings** — parse with `new Date(str)`. Do NOT multiply by 1000.
+- Plans reference products via `plan.product.id`, NOT `plan.product_id`.
+- List endpoints return `{ data: [...] }`.
+- `company_id` is required for most SDK methods — read from `process.env.WHOP_COMPANY_ID`.
+- Whop is the system of record for purchases and membership access.
+- Purchases are tied to the buyer's Whop account. If a user cannot access a purchase, they are often logged into the wrong Whop account/email.
+- In a Whop app/iframe, verify the `x-whop-user-token` server-side to get the Whop `userId`, then call `users.checkAccess(resourceId, { id: userId })`. Gate paid features on Whop's response, not on local checkout state.
+- For non-Whop-hosted apps, use a real auth bridge such as Whop OAuth or a server-verified membership/payment flow. Do not rely on client-supplied email, membership ID, checkout ID, or `success=true`.
+
+- **API server directory**: `server/`
+- **Client app directory**: `client/`
+
+
+### Reference files
+
+- ./references/code-templates.md -- Example routes and checkout flow using the Whop SDK
+- ./references/whopClient.ts -- Server-side Whop SDK client that fetches credentials from the Replit connection API
+- ./references/whop-mcp.mjs -- Helper script for calling Whop MCP tools via the OpenInt proxy
+- ./references/whop-api.mjs -- Helper script for direct Whop REST API calls (plans, checkout configs, payments)
+
+## Step 3: Create product and plan
+
+Run these via `shell_exec` — do NOT ask the user for IDs:
+1. `node whop-mcp.mjs create_product '{"title":"<product name>"}'` → get `prod_xxx`
+2. `node whop-api.mjs POST /api/v1/plans '{"company_id":"biz_xxx","product_id":"prod_xxx","initial_price":<dollars>,"currency":"usd","billing_period":30}'` → get `plan_xxx`
+3. Store `plan_xxx` as a Replit Configuration `WHOP_PLAN_ID`
+
+## Step 4: Implement checkout flow
+
+1. User clicks "Subscribe" → app calls server `POST /api/whop/checkout` with `plan_id`
+2. Server creates checkout config: `POST /checkout_configurations` with `{ plan_id, redirect_url }` → returns `{ id: "ch_xxx", purchase_url }`
+3. Frontend redirects user to `purchase_url` (Whop hosted checkout)
+4. User pays → Whop redirects back to `redirect_url`
+5. Server verifies purchase/account access with Whop before granting paid access:
+   - For Whop apps, verify the Whop user token and call `users.checkAccess` for the product, experience, or company.
+   - For external apps, verify the matching payment/membership server-side and bind it to the authenticated user.
+6. Store only the minimal local mapping needed by the app; Whop remains the source of truth.
+
+## Step 5: Add manage subscription page
+
+Add `/account` or `/settings` page with cancel and view subscription. See `./references/code-templates.md` for routes.
+
+## Rules (read these last — they override any conflicting info above)
+
+- Do NOT ask the user for Company ID, Plan ID, or API key — get them yourself
+- Use `whop-mcp.mjs` and `whop-api.mjs` to manage the Whop account (create products, plans, list payments, etc.) — do NOT ask the user to do these in the Whop dashboard
+- Use Whop's hosted checkout (redirect-based) for all payment flows
+- Use `getWhopClient()` from `whopClient.ts` for all server-side API calls in the user's app
+- Do NOT import `whopClient.ts` in frontend code — it is server-only
+- Do NOT duplicate product/plan catalogs in your database — query Whop
+- Do NOT hardcode `api_key` in source — always fetch via `getWhopClient()`
+- In Whop apps, use Whop account login: verify `x-whop-user-token` and check access with Whop
+- For external apps, add a secure auth bridge before granting access
+- Never grant paid access from a redirect, client-supplied email, membership ID, checkout ID, or `success` query param
+- Store `company_id` in a Replit Configuration
+- Store only minimal purchase/access mappings needed by the app; keep Whop as the source of truth