chore/admin dashboard template

admin-dashboard/.env.example

@@ -1,2 +1,6 @@
 VITE_INSFORGE_URL=https://your-appkey.region.insforge.app
 VITE_INSFORGE_ANON_KEY=your-anon-key
+
+# OSS dashboard origin for native-integration deep links (Stripe / OpenRouter).
+# Defaults to https://app.insforge.dev when unset.
+VITE_INSFORGE_OSS_URL=https://app.insforge.dev

admin-dashboard/README.md

@@ -27,7 +27,7 @@ A polished, end-to-end admin dashboard starter built with Vite, TanStack Router/
 
 Demo: [admindashboard.insforge.site](https://admindashboard.insforge.site)
 
-Sign up or sign in to get a personal workspace, then explore. Every page is hooked to live InsForge data — there is no mock layer.
+Sign up or sign in to get a personal workspace, then explore. Every page is hooked to live InsForge data. The Apps page renders out of the box with Stripe and OpenRouter wired to the InsForge dashboard; the seven Composio-backed integrations (GitHub, Slack, Notion, Discord, Figma, Linear, Vercel) appear as "Setup required" until you provision Composio (see [Connecting third-party apps](#connecting-third-party-apps)).
 
 ---
 
@@ -142,11 +142,55 @@ admin-dashboard/
 
 ---
 
+## Connecting third-party apps
+
+The `/apps` page lists every integration available to a workspace. Two kinds:
+
+- **InsForge-native** (Stripe, OpenRouter) — configured in the InsForge dashboard. The card opens the corresponding dashboard page in a new tab.
+- **Composio-backed** (GitHub, Notion, Slack, Discord, Figma, Linear, Vercel) — connected per workspace via Composio's hosted OAuth.
+
+### Default behavior without Composio
+
+Out of the box, the `/apps` page works with zero third-party setup: Stripe and OpenRouter cards deep-link to the InsForge dashboard, and the seven Composio cards render with a disabled **Connect** button and a "Setup required" label. A banner at the top points to this section. Follow the steps below to switch any of the seven on.
+
+The detection is per-toolkit: only the ones whose `COMPOSIO_AUTH_CONFIG_*` secret you provision become connectable. The rest stay disabled.
+
+### One-time Composio setup
+
+1. Sign up at [composio.dev](https://composio.dev) and create an API key in **Settings → API Keys**.
+2. For each of the 7 toolkits (`github`, `notion`, `slack`, `discord`, `figma`, `linear`, `vercel`), open the **Toolkits** page, click the toolkit, then **Create Auth Config** with OAuth 2.0. Copy the resulting `auth_config_id` (`ac_…`).
+3. Store every value in InsForge secrets:
+
+   ```bash
+   npx @insforge/cli secrets add COMPOSIO_API_KEY <your-api-key>
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_GITHUB  ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_NOTION  ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_SLACK   ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_DISCORD ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_FIGMA   ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_LINEAR  ac_xxx
+   npx @insforge/cli secrets add COMPOSIO_AUTH_CONFIG_VERCEL  ac_xxx
+   ```
+
+4. Deploy the three edge functions (already shipped under `functions/`):
+
+   ```bash
+   npx @insforge/cli functions deploy apps-connect    --file ./functions/apps-connect.ts
+   npx @insforge/cli functions deploy apps-poll       --file ./functions/apps-poll.ts
+   npx @insforge/cli functions deploy apps-disconnect --file ./functions/apps-disconnect.ts
+   ```
+
+Composio routes its OAuth callback to its own domain — you do **not** need to add any URLs to `insforge.toml`. You do need to allow popups in your browser; the connect flow opens one synchronously when the user clicks **Connect**.
+
+Connections are scoped per workspace: the same workspace user_id is passed to Composio so any member of that workspace can disconnect or replace the connection.
+
+---
+
 ## Customization
 
 - **Rebrand** — swap the app name, colors, and icon set. Tailwind CSS variables in `src/styles/globals.css` drive the entire palette; chart colors live there too.
 - **Add a page** — drop a new file under `src/routes/_authenticated/` and add a sidebar entry in `src/components/layout/sidebar-nav.ts`. TanStack Router picks it up on next build.
-- **Wire a real integration in Apps** — replace the toggle handler in `src/features/apps/use-toggle-app.ts` with an OAuth flow. The mock pattern keeps `app_connections.status` for free.
+- **Add or change Apps integrations** — see [Connecting third-party apps](#connecting-third-party-apps) below for the Composio + InsForge-native split. Add a new card by inserting a row into `apps_catalog` (set `integration_kind` and either `composio_toolkit_slug` for Composio toolkits or extend the `OSS_DEEP_LINKS` map in `src/features/apps/use-apps.ts` for native deep links).
 - **Email invitations** — V1 produces a copyable link. To email instead, wire `insforge.emails.send()` in `src/features/users/use-invitations.ts`.
 
 ---