feat: updated read me / metadata and some template logic

Author: Rieranthony

CLI-spec.md

@@ -10,9 +10,9 @@
 
 **Does:**
 
-- `npx claws-supply auth` — device authorization with browser approval and local token storage
-- `npx claws-supply build` — build and sign a local template artifact (`manifest.json` + hashes)
-- `npx claws-supply publish` — create a draft template for the authenticated user via `/api/cli/v1`
+- `npx claws-supply@latest auth` — device authorization with browser approval and local token storage
+- `npx claws-supply@latest build` — build and sign a local template artifact (`manifest.json` + hashes)
+- `npx claws-supply@latest publish` — create a draft template for the authenticated user via `/api/cli/v1`
 
 **Doesn't (not in MVP):**
 
@@ -156,8 +156,8 @@ claws-supply/
 │   ├── index.ts              # Entry: shebang + bootstrap
 │   ├── cli.ts                # Commander program definition
 │   ├── commands/
-│   │   ├── install.ts        # npx claws-supply <slug> (or interactive)
-│   │   └── info.ts           # npx claws-supply info <slug>
+│   │   ├── install.ts        # npx claws-supply@latest <slug> (or interactive)
+│   │   └── info.ts           # npx claws-supply@latest info <slug>
 │   ├── lib/
 │   │   ├── api.ts            # Fetch from claws.supply API
 │   │   ├── download.ts       # Download zip + verify archive hash
@@ -188,7 +188,7 @@ That's it. No config patching, no permission engine, no security scanner. Those
 ### 5.1 Auth
 
 ```bash
-npx claws-supply auth
+npx claws-supply@latest auth
 ```
 
 - Starts device authorization via `/api/cli/v1/auth/device/code`
@@ -199,7 +199,7 @@ npx claws-supply auth
 ### 5.2 Build
 
 ```bash
-npx claws-supply build
+npx claws-supply@latest build
 ```
 
 - Prompts for title + slug
@@ -210,7 +210,7 @@ npx claws-supply build
 ### 5.3 Publish
 
 ```bash
-npx claws-supply publish
+npx claws-supply@latest publish
 ```
 
 - Requests zip upload token from `/api/cli/v1/templates/uploads/zip-token`
@@ -718,7 +718,7 @@ Always:
   The download may be corrupted. Try again, or download from claws.supply directly.
 
 ✗ Template "nonexistent-slug" not found
-  Check the slug at https://claws.supply or run `npx claws-supply` to browse.
+  Check the slug at https://claws.supply or run `npx claws-supply@latest` to browse.
 
 ✗ This is a paid template ($12.00)
   Purchase it at: https://claws.supply/openclaw/template/reddit-marketing-starter

MVP.md

@@ -53,11 +53,21 @@
   - Browsing sales: 30% platform commission
   - Direct-link sales: 20% platform commission
   - Direct referral window: 90 days
+- [x] DONE — Template purchase flow shipped (code path):
+  - `POST /api/purchases/checkout` creates authenticated checkout sessions for paid templates
+  - Commission split is persisted on `purchase` (`commission_rate`, `platform_fee_amount_cents`, `seller_payout_amount_cents`)
+  - Stripe Checkout for paid templates is created in seller connected-account context with `application_fee_amount`
+  - Connect webhook shipped at `POST /api/stripe/webhooks/connect` to transition purchases to `completed` / `failed`
+  - Template detail quick-command gate shipped on `/openclaw/template/[templateSlug]`:
+    - free template: copy command
+    - paid + signed out: sign-in CTA
+    - paid + signed in without purchase: purchase CTA
+    - paid + owner/admin/purchased: copy command
 - [x] DONE — Advertising subscriptions v1 shipped:
   - Public sales + authenticated campaign management page at `/advertise`
   - Ad campaign schema + migration (`ad_campaign`, `stripe_webhook_event`, enums/indexes/constraints)
   - Ads APIs shipped: `GET /api/ads/availability`, `GET/POST /api/ads/campaign`, `POST /api/ads/campaign/cancel`, `POST /api/ads/logo-handle`
-  - Stripe ads webhook lifecycle sync shipped at `POST /api/stripe/webhooks`
+  - Stripe ads webhook lifecycle sync shipped at `POST /api/stripe/webhooks/platform`
   - Sponsored rendering shipped for sidebar and in-grid results cards
   - Legal updates shipped for advertising subscriptions/moderation in terms + policy pages
 - [x] DONE — Members community surfaces shipped:
@@ -101,7 +111,7 @@
 - Member privacy decision: public member read paths only select safe fields (`id`, `username`, `name`, `bio`, `image`, verification flags, timestamps); email is never exposed.
 - Migration prerequisite: local/dev must run latest Drizzle migrations before app runtime (`bun run migrate`) so lifecycle columns like `template.status` exist.
 - Current gap snapshot:
-  - Checkout/purchase routes + Stripe webhook purchase creation are still pending.
+  - Purchase checkout + connect-webhook completion are shipped; `GET /api/purchases` and `GET /api/purchases/[templateSlug]` are still pending.
   - Review routes are still pending.
   - Dedicated `/api/members` and `/api/members/[username]` endpoints are still pending (public pages currently read server-side directly).
   - Automated tests for lifecycle/read/blob/payment flows are still pending.
@@ -388,19 +398,27 @@ No shareable pre-signed blob download URL is returned to client.
 ### 6.2 Purchase Flow
 
 ```
-1. Buyer clicks "Buy" on template page
-2. Determine sale_type:
-   - If URL has ?ref={sellerUsername} → sale_type = "direct"
+1. Buyer clicks purchase CTA on template detail page.
+2. Client calls POST /api/purchases/checkout with body { templateSlug, ref? }.
+3. Route enforces authenticated session + Zod input validation.
+4. Service validates template availability + prevents self-purchase + checks existing ownership.
+5. Determine sale_type:
+   - If request body has ref matching seller username → sale_type = "direct"
    - Otherwise → sale_type = "browsing"
-3. Look up commission rate:
+6. Look up commission rate:
    a. Check commission_overrides for this seller
    b. If no override → use defaults (direct: 20%, browsing: 30%)
-4. Create Stripe Checkout Session:
-   - application_fee_amount = price * (commission_rate / 100)
-   - transfer_data.destination = seller's stripe_account_id
-5. On successful payment (webhook: checkout.session.completed):
-   a. Create purchase record
-6. Buyer can now download the template
+7. Upsert pending purchase row with:
+   - price, commission_rate, platform_fee_amount_cents, seller_payout_amount_cents
+8. Create Stripe Checkout Session for the seller connected account:
+   - request option: stripeAccount = seller.stripe_account_id
+   - payment_intent_data.application_fee_amount = platform fee
+9. Persist stripe_checkout_session_id + checkout_started purchase event.
+10. On successful payment webhook (`checkout.session.completed` / `checkout.session.async_payment_succeeded`):
+    a. Update purchase status to completed
+    b. Set completed_at + stripe_payment_intent_id
+    c. Persist checkout_completed purchase event
+11. Buyer can now download/use the paid template.
 ```
 
 `download_count` is incremented on successful download stream start (`GET /api/templates/[slug]/download`), not on checkout completion.
@@ -502,11 +520,11 @@ Deprecated/removed routes:
 
 ### 7.3 Purchase Routes
 
-| Method | Route                           | Auth | Description                                                            |
-| ------ | ------------------------------- | ---- | ---------------------------------------------------------------------- |
-| `POST` | `/api/purchases/checkout`       | ✅   | Create Stripe Checkout session. Body: `{ templateSlug, ref? }`         |
-| `GET`  | `/api/purchases`                | ✅   | List current user's purchases. Includes template info for re-download. |
-| `GET`  | `/api/purchases/[templateSlug]` | ✅   | Check if current user owns a specific template                         |
+| Method | Route                           | Auth | Status      | Description                                                            |
+| ------ | ------------------------------- | ---- | ----------- | ---------------------------------------------------------------------- |
+| `POST` | `/api/purchases/checkout`       | ✅   | ✅ Shipped  | Create Stripe Checkout session. Body: `{ templateSlug, ref? }`         |
+| `GET`  | `/api/purchases`                | ✅   | ⚠️ Pending  | List current user's purchases. Includes template info for re-download. |
+| `GET`  | `/api/purchases/[templateSlug]` | ✅   | ⚠️ Pending  | Check if current user owns a specific template                         |
 
 ### 7.4 Review Routes
 
@@ -527,11 +545,14 @@ Deprecated/removed routes:
 
 ### 7.6 Stripe Routes
 
-| Method | Route                        | Auth | Description                                                       |
-| ------ | ---------------------------- | ---- | ----------------------------------------------------------------- |
-| `POST` | `/api/stripe/connect`        | ✅   | Create Stripe Connect account + return onboarding URL             |
-| `GET`  | `/api/stripe/connect/status` | ✅   | Check Stripe account status (onboarding complete, verified, etc.) |
-| `POST` | `/api/stripe/webhooks`       | ❌\* | Stripe webhook handler. \*Verified via Stripe signature.          |
+| Method | Route                           | Auth | Status      | Description                                                                                  |
+| ------ | ------------------------------- | ---- | ----------- | -------------------------------------------------------------------------------------------- |
+| `POST` | `/api/profile/stripe/connect`   | ✅   | ✅ Shipped  | Create Stripe Connect account link and return onboarding URL.                               |
+| `GET`  | `/api/profile/stripe/status`    | ✅   | ✅ Shipped  | Check Stripe account status (onboarding complete, verified, etc.).                          |
+| `POST` | `/api/stripe/webhooks/connect`  | ❌\* | ✅ Shipped  | Stripe Connect webhook for template purchases + connected account updates.                   |
+| `POST` | `/api/stripe/webhooks/platform` | ❌\* | ✅ Shipped  | Stripe platform webhook for advertising subscriptions.                                       |
+
+\* Verified via Stripe signature.
 
 ### 7.7 Admin Routes
 
@@ -621,7 +642,12 @@ app/
 - **SEO title:** "{Template Title} — OpenClaw Template on Claws.supply"
 - **Content:**
   - Template title, description (rendered markdown), cover image
-  - Price (or "Free"), Buy/Download button
+  - Price + quick command row: `npx claws-supply use {templateSlug}`
+  - Quick command access states:
+    - Free template: copy command visible for all visitors
+    - Paid + signed out: locked command row + sign-in CTA
+    - Paid + signed in without completed purchase: purchase CTA (`Purchase for $X`)
+    - Paid + owner/admin/paid buyer: copy command visible
   - Seller info card (avatar, name, verified badge, link to profile)
   - Stats: downloads, average rating, review count
   - Reviews section (paginated)
@@ -668,9 +694,9 @@ app/
 #### CLI Publishing Guide (`/openclaw/templates/publish-via-cli`)
 
 - Public guide page for sellers with exact CLI commands:
-  - `npx claws-supply auth`
-  - `npx claws-supply build`
-  - `npx claws-supply publish`
+  - `npx claws-supply@latest auth`
+  - `npx claws-supply@latest build`
+  - `npx claws-supply@latest publish`
 - This replaces the previous web create-template form flow.
 
 #### Dashboard — Settings (`/dashboard/settings`)
@@ -739,7 +765,20 @@ For MVP, admin features are **API-only** (no admin UI). Admins use API calls or
 
 ## 11. Webhook Handlers
 
-### Stripe Webhooks (`POST /api/stripe/webhooks`)
+### Stripe Connect Webhooks (`POST /api/stripe/webhooks/connect`)
+
+| Event                                    | Action                                                                                          |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `checkout.session.completed`             | Complete template purchase when payment status is `paid`.                                      |
+| `checkout.session.async_payment_succeeded` | Complete template purchase for delayed-success payment methods.                                |
+| `checkout.session.expired`               | Mark pending template purchase as failed/expired.                                               |
+| `checkout.session.async_payment_failed`  | Mark pending template purchase as failed.                                                       |
+| `account.updated`                        | Sync seller `stripeVerified` status from Connect account capability flags.                      |
+
+Webhook signatures are verified via `stripe.webhooks.constructEvent()` with `STRIPE_CONNECT_WEBHOOK_SECRET`.
+Connect webhook event IDs are persisted in `stripe_connect_webhook_event` for idempotency.
+
+### Stripe Platform Webhooks (`POST /api/stripe/webhooks/platform`)
 
 | Event                           | Action                                                                                       |
 | ------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -749,8 +788,8 @@ For MVP, admin features are **API-only** (no admin UI). Admins use API calls or
 | `customer.subscription.deleted` | End campaign and stop visibility.                                                            |
 | `invoice.payment_failed`        | Record failure state for observability; do not hide ad immediately.                          |
 
-All webhooks are verified via `stripe.webhooks.constructEvent()` with signing secret.
-Webhook event IDs are persisted for idempotency in `stripe_webhook_event`.
+Webhook signatures are verified via `stripe.webhooks.constructEvent()` with `STRIPE_PLATFORM_WEBHOOK_SECRET`.
+Platform webhook event IDs are persisted for idempotency in `stripe_webhook_event`.
 
 ---
 
@@ -771,6 +810,7 @@ Webhook event IDs are persisted for idempotency in `stripe_webhook_event`.
 13. **Versioning:** each version is immutable and unique per template; new version must increment by exactly `+1` (integer versioning).
 14. **Download tracking:** `download_count` increments only after private blob fetch begins successfully.
 15. **Soft delete:** deletion sets lifecycle status to `deleted`; data is retained.
+16. **Paid command gate:** on template detail pages, paid-template command copy is allowed only for owner/admin/completed-purchase users; ineligible users see sign-in or purchase CTA.
 
 ### Known Hardening Gaps (Non-Blocking Follow-up)
 

README.md

@@ -1,51 +1,93 @@
-# claws.supply
+# Claws.supply
 
-Bun + Turborepo monorepo.
+Claws.supply is a marketplace for OpenClaw templates. Builders can discover production-ready agent setups faster, sellers can publish and monetize their templates, and buyers can purchase and deploy proven configurations. Template creation is CLI-first through the `claws-supply` package.
 
-Landing page: [claws.supply](https://claws.supply)
+## What's In This Repo
 
-## Workspace Layout
+- `apps/web` - Next.js App Router marketplace app and API (`@claws-supply/web`)
+- `packages/cli` - `claws-supply` creator CLI for auth, build, and draft publish
 
-- `apps/web`: Next.js App Router application (`@claws-supply/web`)
-- `packages/cli`: claws.supply creator CLI (`claws-supply`)
+## Tech Stack
 
-## CLI Usage
+- Monorepo/runtime: Bun (`>=1.3.1`) + Turborepo
+- Web: Next.js App Router, React, Tailwind CSS
+- Data/auth/payments/storage: Drizzle ORM + PostgreSQL, Better Auth, Stripe, Vercel Blob
+- CLI: Node (`>=20`), Commander, Zod, fflate, Vercel Blob client
 
-Run without installing globally:
+## Quickstart (Local Development)
+
+Prerequisites:
+
+- Bun `>=1.3.1`
+- Node `>=20`
+- Docker (for local Postgres)
+
+1. Install dependencies.
 
 ```bash
-npx claws-supply auth
-npx claws-supply build
-npx claws-supply publish
+bun install
 ```
 
-`build` uses your current folder by default. Use `--source <path>` only when the target project is in a different folder.
+2. Start local Postgres.
 
-## Requirements
+```bash
+docker compose up -d
+```
 
-- Bun `1.3.1` or newer
+3. Create local env file and fill values.
 
-## Install
+```bash
+cp apps/web/env.template apps/web/.env.local
+```
+
+4. Run database migrations.
 
 ```bash
-bun install
+bun run migrate
 ```
 
-## Root Commands
+5. Start the app.
 
 ```bash
 bun run dev
-bun run build
-bun run start
-bun run lint
-bun run check:no-runtime-sql
-bun run db:generate
-bun run migrate
 ```
 
-## Environment Files
+Web runs at `http://localhost:3039`.
+
+## Common Monorepo Commands
+
+| Command | Purpose |
+| --- | --- |
+| `bun run dev` | Run web app in development mode (`@claws-supply/web`) |
+| `bun run build` | Build web app |
+| `bun run start` | Start production server for web app |
+| `bun run lint` | Run lint checks for web app |
+| `bun run db:generate` | Generate Drizzle migrations |
+| `bun run migrate` | Apply database migrations |
+| `bun run check:no-runtime-sql` | Guardrail check for runtime SQL usage |
+
+## CLI Quickstart (Creator Flow)
+
+Run from your template project folder:
+
+```bash
+npx claws-supply@latest auth
+npx claws-supply@latest build
+npx claws-supply@latest publish
+```
+
+CLI defaults:
+
+- Production API target is `https://claws.supply`
+- Use `-D` to target local API: `http://localhost:3039`
+- `build` uses the current directory by default (`--source` is optional)
+
+For full CLI flags, local artifact/auth state paths, local smoke flows, and troubleshooting, see [`packages/cli/README.md`](packages/cli/README.md).
 
-- Web app env file: `apps/web/.env.local`
-- Template env values: `apps/web/env.template`
+## Docs And Links
 
-If you previously had `.env.local` at repo root, move it to `apps/web/.env.local`.
+- Site: [https://claws.supply](https://claws.supply)
+- Product docs: [https://claws.supply/docs](https://claws.supply/docs)
+- CLI docs: [`packages/cli/README.md`](packages/cli/README.md)
+- Internal product spec: [`MVP.md`](MVP.md)
+- Internal CLI spec: [`CLI-spec.md`](CLI-spec.md)

apps/web/app/layout.tsx

@@ -6,7 +6,12 @@ import { Navbar } from "@/components/navbar";
 import { SiteFooter } from "@/components/site-footer";
 import { Toaster } from "@/components/ui/sonner";
 import { getSessionFromNextHeaders } from "@/lib/auth/session";
-import { absoluteUrl, getDefaultOgImagePath, getSiteUrl } from "@/lib/seo";
+import {
+  absoluteUrl,
+  DEFAULT_SITE_TAGLINE,
+  getDefaultOgImagePath,
+  getSiteUrl,
+} from "@/lib/seo";
 import "./globals.css";
 import { MainProviders } from "./providers";
 import Script from "next/script";
@@ -17,7 +22,7 @@ const DEFAULT_OG_IMAGE_URL = absoluteUrl(getDefaultOgImagePath());
 export const metadata: Metadata = {
   metadataBase: new URL(SITE_URL),
   title: {
-    default: "Claws.supply — OpenClaw AI Agent Templates Marketplace",
+    default: DEFAULT_SITE_TAGLINE,
     template: "%s",
   },
   description:
@@ -26,7 +31,7 @@ export const metadata: Metadata = {
     canonical: "/",
   },
   openGraph: {
-    title: "Claws.supply — OpenClaw AI Agent Templates Marketplace",
+    title: DEFAULT_SITE_TAGLINE,
     description:
       "Discover popular and latest OpenClaw agent templates, and launch faster with production-ready setups.",
     url: "/",
@@ -43,7 +48,7 @@ export const metadata: Metadata = {
   },
   twitter: {
     card: "summary_large_image",
-    title: "Claws.supply — OpenClaw AI Agent Templates Marketplace",
+    title: DEFAULT_SITE_TAGLINE,
     description:
       "Discover popular and latest OpenClaw agent templates, and launch faster with production-ready setups.",
     images: [DEFAULT_OG_IMAGE_URL],