quiver-cli 0.6.0 → 0.8.0

package/template/.agents/skills/apps/skybridge/references/open-external-links.md

@@ -1,71 +0,0 @@
-# Open external links
-
-- "Open in App" button URL → `useSetOpenInAppUrl`
-- External redirect → `useOpenExternal`
-
-## "Open in App" button
-
-Top right corner in fullscreen mode. Set programmatically. If the origin matches the view server URL, ChatGPT navigates to the full href (any path). If the origin differs, ChatGPT falls back to the view server URL.
-
-**Example**:
-```tsx
-import { useSetOpenInAppUrl } from "skybridge/web";
-import { useEffect } from "react";
-
-function ProductDetail({ productId }: { productId: string }) {
-  const setOpenInAppUrl = useSetOpenInAppUrl();
-
-  useEffect(() => {
-    setOpenInAppUrl(`https://example.com/products/${productId}`).catch(console.error);
-  }, [productId]);
-
-  return <div>{/* Product details */}</div>;
-}
-```
-
-## External redirect
-
-**Example**:
-```tsx
-import { useOpenExternal } from "skybridge/web";
-
-function ExternalLink() {
-  const openExternal = useOpenExternal();
-
-  return (
-    <button onClick={() => openExternal("https://example.com")}>
-      Visit Website
-    </button>
-  );
-}
-```
-
-
-You can control return-path behavior with an optional second argument (ChatGPT only):
-
-```tsx
-openExternal("https://example.com", { redirectUrl: false });
-```
-
-Use `redirectUrl: false` to skip automatic `?redirectUrl=...` appending.
-
-Shows confirmation dialog unless domain is whitelisted:
-
-```typescript
-// src/server.ts
-server.registerTool(
-  {
-    name: "search-flights",
-    description: "Search for flights",
-    inputSchema: { destination: z.string(), dates: z.string() },
-    view: {
-      component: "search-flights",
-      description: "Flight results",
-      csp: {
-        redirectDomains: ["https://airline.example.com"],
-      },
-    },
-  },
-  async ({ destination, dates }) => { /* ... */ }
-);
-```

package/template/.agents/skills/apps/skybridge/references/prompt-llm.md

@@ -1,20 +0,0 @@
-# Prompt model
-
-Trigger an LLM completion from user interaction with `useSendFollowUpMessage`.
-
-**Example:**
-```tsx
-import { useSendFollowUpMessage } from "skybridge/web";
-
-export function FindBestFlightButton() {
-  const sendMessage = useSendFollowUpMessage();
-
-  return (
-    <button onClick={() => sendMessage({
-      prompt: "Find the best flight option, based on user preferences and agenda."
-    })}>
-      Find Best Flight
-    </button>
-  );
-}
-```

package/template/.agents/skills/apps/skybridge/references/publish.md

@@ -1,19 +0,0 @@
-# Publish to Directories
-
-## 1. Audit Annotations
-
-**Common cause of rejection.** Ensure all tools and views have correct annotations. See [fetch-and-render-data.md](fetch-and-render-data.md).
-
-## 2. Audit CSP
-
-Ensure all external domains are declared in the tool's `view.csp`. See [csp.md](csp.md).
-
-## 3. Submit
-
-### ChatGPT
-Guide user to submit the app at [platform.openai.com](https://platform.openai.com) → Apps.
-
-OpenAI verifies app ownership via `/.well-known/openai-apps-challenge`. Guide user to Alpic **Distribution** tab → **OpenAI Apps Verification Token** → paste the token from OpenAI.
-
-### Claude
-Guide user to submit the app on the [Anthropic Connectors Directory FAQ](https://support.claude.com/en/articles/11596036-anthropic-connectors-directory-faq).

package/template/.agents/skills/apps/skybridge/references/run-locally.md

@@ -1,51 +0,0 @@
-# Running Locally Workflow
-
-## 1. Start Dev Server
-
-Install dependencies and start the dev server in the background:
-
-```bash
-{pm} install && {pm} run dev
-```
-
-For Deno projects, use `deno task dev` instead.
-
-When started, output the local MCP server and devtools URL.
-
-Hot reload enabled (nodemon for server, HMR for views).
-
-## 2. Connect to AI Assistants (Optional)
-
-Ask user if they want to test in ChatGPT/Claude or just use local devtools.
-
-If yes, expose the local server via Alpic tunnel:
-
-```bash
-alpic tunnel --port 3000
-```
-
-Extract the forwarding URL from Alpic tunnel output (e.g., `https://cool-marmot-fondue-420.alpic.dev`).
-
-### Connect to ChatGPT
-Provide the user with these instructions to create the app in ChatGPT:
-1. Go to [Apps Settings](https://chatgpt.com/apps#settings/Connectors) → Create App
-2. Enter a name and description for the app
-3. Paste this URL: `{tunnel-url}/mcp`
-4. Set the appropriate Authentication scheme. In doubt, pick "No Authentication"
-5. Click Create
-6. Test by typing `@{app-name}` in a ChatGPT chat
-
-**Troubleshooting:**
-- 'Create App' button missing: ask user to enable Developer mode in Settings → Apps → Advanced Settings
-- 'Create App' button not working: confirm they have ChatGPT Plus, Pro, Business, or Enterprise/Edu plan
-
-
-### Connect to Claude
-Provide the user with these instructions to create the app in Claude:
-1. Go to [Connector Settings](https://claude.ai/settings/connectors) → Add Custom Connector
-2. Enter a name and URL: `{tunnel-url}/mcp`
-3. Click Create
-4. In Claude chat, click the `+` button and select `@{app-name}`
-
-**Troubleshooting:**
-- 'Add Custom Connector' button missing: confirm they have a Claude paid plan

package/template/.agents/skills/apps/skybridge/references/state-and-context.md

@@ -1,151 +0,0 @@
-# Manage View State and LLM Context
-
-- View state (`useViewState`/`createStore`) persists and is visible to LLM as structured data.
-- `data-llm` gives LLM context for referential language ("this one").
-- React `useState` is ephemeral and invisible to LLM.
-
-**Decision guide:**
-| Need | Use |
-|------|-----|
-| Persist data, single component | `useViewState` |
-| Persist data, shared across components, complex mutations | `createStore` |
-| Help LLM understand "this one" | `data-llm` |
-| Ephemeral UI only (hover, animation) | `useState` |
-
-## useViewState
-
-Single component, simple access patterns.
-
-```tsx
-function SeatPicker({ seats }) {
-  const [{ selectedSeat }, setState] = useViewState({ selectedSeat: null });
-
-  return (
-    <div className="seat-grid">
-      {seats.map(seat => (
-        <button
-          key={seat.id}
-          onClick={() => setState((prev) => ({ ...prev, selectedSeat: seat.id }))}
-          className={selectedSeat === seat.id ? "selected" : ""}
-        >
-          {seat.id}
-        </button>
-      ))}
-    </div>
-  );
-}
-```
-
-**Why useViewState:** Single component reads `selectedSeat` to highlight button. View or LLM reads when booking.
-
-## createStore
-
-Shared across components, complex mutations. `createStore` is a thin wrapper around Zustand.
-
-```tsx
-import { createStore } from "skybridge/web";
-
-const useCartStore = createStore<CartState>((set) => ({
-  cart: [],
-  add: (item) => set((s) => ({ cart: [...s.cart, item] })),
-  remove: (id) => set((s) => ({ cart: s.cart.filter(i => i.id !== id) })),
-}));
-
-// ProductCard.tsx
-function ProductCard({ product }) {
-  const add = useCartStore((s) => s.add);
-  return <button onClick={() => add(product)}>Add to Cart</button>;
-}
-
-// CartSummary.tsx
-function CartSummary() {
-  const cart = useCartStore((s) => s.cart);
-  return <span>{cart.length} items</span>;
-}
-```
-
-**Why createStore:** Cart accessed by multiple components. View or LLM reads items at checkout.
-
-## data-llm
-
-Tell the LLM what user is viewing/doing. One-way—view doesn't read it back. These are annotations—don't put complex objects here.
-
-```tsx
-function ProductDetail({ product }) {
-  return (
-    <div data-llm={`Viewing: ${product.name}, $${product.price}, ${product.inStock ? "in stock" : "out of stock"}`}>
-      <h1>{product.name}</h1>
-      <p>${product.price}</p>
-    </div>
-  );
-}
-```
-
-**Why data-llm:** When user asks "Is this one good?" or "Add this to cart", LLM knows what "this" refers to.
-
-## Common mistakes
-
-```tsx
-// DON'T: useState is not persisted, LLM can't see it
-const [selected, setSelected] = useState(null);
-
-// DO: useViewState persists and LLM sees it
-const [{ selected }, setState] = useViewState({ selected: null });
-```
-
-```tsx
-// DON'T: Complex object in data-llm
-<div data-llm={JSON.stringify(cart)}>
-
-// DO: Human-readable summary
-<div data-llm={`Cart: ${cart.length} items, $${total}`}>
-```
-
-## Combined example
-
-Todo list. User checks off tasks, asks "what should I prioritize?"
-
-```tsx
-function TaskList() {
-  // PERSIST: All tasks with completed status
-  const [{ tasks }, setState] = useViewState({
-    tasks: [
-      { id: 1, title: "Buy groceries", completed: false },
-      { id: 2, title: "Call mom", completed: true },
-    ]
-  });
-
-  // EPHEMERAL: Task user is viewing — reset on reopen
-  const [viewing, setViewing] = useState(null);
-
-  return (
-    // CONTEXT: What user is looking at — LLM answers "how should I handle this task?"
-    <div data-llm={viewing
-      ? `Viewing: "${viewing.title}"`
-      : `${tasks.filter(t => !t.completed).length} tasks remaining`
-    }>
-      {tasks.map(t => (
-        <Task
-          key={t.id}
-          task={t}
-          onView={() => setViewing(t)}
-          onToggle={() => setState((prev) => ({
-            ...prev,
-            tasks: prev.tasks.map(task =>
-              task.id === t.id ? { ...task, completed: !task.completed } : task
-            )
-          }))}
-        />
-      ))}
-    </div>
-  );
-}
-```
-
-**Why each?**
-
-| What | API | Why |
-|------|-----|-----|
-| `tasks` | `useViewState` | Persists. Tasks and progress survive reopen. |
-| `viewing` | `useState` | Ephemeral. Current focus resets on reopen. |
-| `"Viewing: Buy groceries"` | `data-llm` | LLM context. Understands "this task" in conversation. |

package/template/.agents/skills/apps/skybridge/references/ui-guidelines.md

@@ -1,205 +0,0 @@
-# UI Guidelines
-
-## Contents
-- [Display Modes](#display-modes) — inline, fullscreen, PiP, switching
-- [Modal](#modal) — overlay on top of any display mode
-- [Adapting to Host](#adapting-to-host) — layout constraints, theme
-- [Adapting to User](#adapting-to-user) — device, locale
-
-## Display Modes
-
-Views render **inline by default**. Add fullscreen and/or PiP when the use case benefits from it—implement triggers (button, gesture) to let users switch.
-
-### Inline (default)
-
-View appears embedded in conversation above the model response.
-
-**Use for:** Single result display, quick actions, browsing items.
-
-**Constraints:**
-- Max 2 CTAs (one primary, one secondary)
-- No `overflow: scroll/auto`—content must fit within available space
-- No tabs or deep navigation
-
-**Patterns:**
-- **Card** — Single-purpose view (order confirmation, weather, status)
-- **Carousel** — 3-8 browsable items with image + title + max 3 lines metadata
-
-### Fullscreen
-
-Immersive experience for complex tasks. Host composer remains overlaid at bottom.
-
-**Use for:** Multi-step workflows, rich editing, explorable content, detailed comparisons.
-
-**Constraints:**
-- Composer overlay always visible at bottom
-- User can still chat while in fullscreen
-
-### Picture-in-Picture (PiP)
-
-Persistent floating window that stays visible during conversation.
-
-**Use for:** Live sessions (timers, streams), games, real-time status.
-
-**Constraints:**
-- Must update/respond to user interaction—don't use for static content
-- Minimal controls—this is a glanceable surface
-- On mobile, PiP coerces to fullscreen
-
-### Switching Modes
-
-Use `useDisplayMode` to read current mode and request changes.
-
-**Constraints:**
-- User-triggered only—never switch programmatically
-- Host may reject the request
-
-```tsx
-import { useDisplayMode } from "skybridge/web";
-
-function ExpandableView() {
-  const [displayMode, setDisplayMode] = useDisplayMode();
-  const isFullscreen = displayMode === "fullscreen";
-
-  if (isFullscreen) {
-    return (
-      <div className="fullscreen-view">
-        {/* Expanded layout */}
-        <button onClick={() => setDisplayMode("inline")}>Collapse</button>
-      </div>
-    );
-  }
-
-  return (
-    <div className="inline-view">
-      {/* Compact layout */}
-      <button onClick={() => setDisplayMode("fullscreen")}>Expand</button>
-    </div>
-  );
-}
-```
-
-## Modal
-
-Overlay rendered outside the view iframe, on top of the current display mode.
-
-**Use for:** Confirmations, additional input before an action.
-
-**Constraints:**
-- Triggered by user interaction only
-- Host injects close controls
-
-```tsx
-import { useRequestModal } from "skybridge/web";
-
-function SettingsView() {
-  const { isOpen, open, params } = useRequestModal();
-
-  if (isOpen) {
-    return (
-      <div className="modal">
-        <h2>Are you sure?</h2>
-        <p>This will delete item {params.itemId}</p>
-        <button onClick={() => console.log("Confirmed")}>Yes, Delete</button>
-        <button onClick={() => console.log("Cancelled")}>Cancel</button>
-      </div>
-    );
-  }
-
-  return (
-    <button onClick={() => open({ title: "Confirm", params: { itemId: "123" } })}>
-      Delete Item
-    </button>
-  );
-}
-```
-
-## Adapting to Host
-
-Use `useLayout` to read host environment constraints.
-
-### Layout Constraints
-
-- `maxHeight`: Maximum height available for the view in pixels
-- `safeArea.insets`: Padding to avoid device notches, composer overlay, and navigation bars
-
-```tsx
-import { useLayout } from "skybridge/web";
-
-function Container({ children }) {
-  const { maxHeight, safeArea } = useLayout();
-  const { top, right, bottom, left } = safeArea.insets;
-
-  return (
-    <div style={{ maxHeight, padding: `${top}px ${right}px ${bottom}px ${left}px` }}>
-      {children}
-    </div>
-  );
-}
-```
-
-### Theme
-
-Match the host color scheme using `theme` from `useLayout`.
-
-```tsx
-import { useLayout } from "skybridge/web";
-
-function Container({ children }) {
-  const { theme } = useLayout();
-  const isDark = theme === "dark";
-
-  return <div className={isDark ? "bg-surface-dark" : "bg-surface-light"}>{children}</div>;
-}
-```
-
-## Adapting to User
-
-Use `useUser` to read user context.
-
-### Device
-
-- `device.type`: `"mobile" | "tablet" | "desktop" | "unknown"`
-- `capabilities.hover`: `true` if device supports hover (mouse)
-- `capabilities.touch`: `true` if device supports touch
-
-```tsx
-import { useUser } from "skybridge/web";
-
-function ProductCard({ product }) {
-  const { userAgent } = useUser();
-  const { device, capabilities } = userAgent;
-
-  return (
-    <div className={capabilities.hover ? "hover:shadow-lg" : ""}>
-      <img src={product.image} alt={product.name} />
-      <h3>{product.name}</h3>
-      {device.type === "mobile" && <button>Add to Cart</button>}
-      {capabilities.touch && <p className="hint">Swipe for more</p>}
-    </div>
-  );
-}
-```
-
-### Locale
-
-Use `locale` from `useUser` to adapt content to user's language.
-
-```tsx
-import { useUser } from "skybridge/web";
-
-function LocalizedGreeting() {
-  const { locale } = useUser();
-
-  const greetings = {
-    en: "Hello!",
-    fr: "Bonjour!",
-    zh: "你好!",
-  };
-
-  const language = locale.split("-")[0];
-  const greeting = greetings[language] || greetings.en;
-
-  return <h1>{greeting}</h1>;
-}
-```