@ysk-kit/cli 1.2.1 → 1.2.3

package/templates/agent/skills/add-module/SKILL.md

@@ -3,6 +3,15 @@ name: add-module
 description: >
   Add a hexagonal HTTP module with ysk-kit add module (contract, DTO, Express+Fastify, SDK, web page).
   Use when the user wants a new resource, new API route, ysk-kit add module, or /add-module.
+  中文：加模組、HTTP 切片、org 範圍、Express 與 Fastify 測試。
+  Do not use to mkdir apps/api/src/modules by hand or to restore llm/team/billing/push (add-capability).
 ---
 
 Read `docs/skills/add-module.md`. Law: `AGENTS.md`.
+
+1. `pnpm ysk-kit add module <kebab> --prisma --web`. Do not mkdir the slice.
+2. Fill DTO then `application/` rules. Schema → db-migration. Org-scoped: requireBiller + negative test.
+3. App tests on Express AND Fastify. Then verify-change.
+Gotcha: no parallel tree; no TypeScript enum; clients use the SDK only.
+Verify: `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`
+Full steps: `docs/skills/add-module.md`.

package/templates/agent/skills/contract-change/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: contract-change
+description: >
+  Change YSK Kit contracts first: breaking-change table, gen:openapi diff
+  (optional oasdiff), deprecation, new error codes, lockstep changeset bump.
+  Use when editing packages/contracts, ts-rest paths, DTOs, error codes,
+  OpenAPI, or a client-visible field.
+  中文：合約、OpenAPI、破壞性變更、錯誤碼、changeset。
+  Do not use for application-only rules with no DTO/path change, or for Prisma SQL (use db-migration).
+---
+
+Read `docs/skills/contract-change.md`. Law: `AGENTS.md`.
+
+1. Classify additive vs breaking. Ask before dropping a published field.
+2. Edit `@ysk-kit/contracts` first. `pnpm gen:openapi` then `git diff --exit-code docs/openapi.yaml`.
+3. Lockstep changeset (all 26) + CHANGELOG. Optional `npx oasdiff`.
+Gotcha: new error codes need ERROR_MESSAGE zh-HK+en and HTTP_STATUS.
+Verify: `pnpm --filter @ysk-kit/contracts test && pnpm gen:openapi`
+Full steps: `docs/skills/contract-change.md`.

package/templates/agent/skills/db-migration/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: db-migration
+description: >
+  Apply Prisma 7.10 migrations in YSK Kit: review generated SQL, expand/contract
+  for breaking changes, backfills, never migrate reset without explicit consent.
+  Use when schema.prisma changes, after add-module --prisma or add <capability>
+  with Prisma, or the user says migrate / rename column / backfill / reset.
+  中文：資料庫遷移、改欄位、改名、回填、migrate reset。
+  Do not use for Prisma 8 commands or for application rules with no schema change.
+---
+
+Read `docs/skills/db-migration.md`. Law: `AGENTS.md`.
+
+1. Pin Prisma 7.10: `migrate dev --create-only`, `migrate deploy`. No Prisma 8 CLI.
+2. Read generated SQL. Breaking changes use expand/contract + backfill.
+3. Update Prisma **and** memory repositories. Never `migrate reset` without this-turn consent.
+Full steps: `docs/skills/db-migration.md`.

package/templates/agent/skills/debug-issue/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: debug-issue
+description: >
+  Debug a YSK Kit failure by building a red feedback loop first: memory-port
+  tests, then HTTP on Express AND Fastify, then SDK, then e2e, then git bisect.
+  Use when a test, CI job, or user report is red; a flake; or /debug-issue.
+  中文：除錯、紅燈迴圈、回歸測試、bisect、日誌遮罩。
+  Do not use for green-field features (plan-feature) or a security audit (security-review).
+---
+
+Read `docs/skills/debug-issue.md`. Law: `AGENTS.md`.
+
+1. Write or isolate a red test first (memory-port, then Express+Fastify HTTP).
+2. Triage by error code. Fix the cause. Keep the regression test.
+3. Climb to SDK / e2e / git bisect only if the lower loop cannot see it.
+Gotcha: do not log OTP/sk_/whsec_. Do not set RATE_LIMIT_MAX=0 in production.
+Verify: the named Vitest is green, then the five verify commands.
+Full steps: `docs/skills/debug-issue.md`.

package/templates/agent/skills/desktop-electron/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: desktop-electron
+description: >
+  Harden the YSK Kit Electron desktop app: contextIsolation, sandbox, CSP,
+  navigation and new-window restrictions, IPC sender validation, safeStorage
+  with no plaintext fallback, auto-update signing.
+  Use when changing apps/desktop/src/main or preload, adding an IPC channel,
+  opening external URLs, filesystem access, auto-update, or packaging.
+  中文：Electron 安全、CSP、IPC、safeStorage、自動更新。
+  Do not use for renderer-only UI or web/admin token storage with no main-process change.
+---
+
+Read `docs/skills/desktop-electron.md`. Law: `AGENTS.md`.
+
+1. Keep contextIsolation, nodeIntegration false, sandbox, webSecurity, session CSP.
+2. Deny unexpected navigation / window.open. Validate IPC `senderFrame`.
+3. `safeStorage` only; memory if unavailable. No plaintext token file.
+Gotcha: do not `openExternal` a renderer string without an allowlist.
+Verify: `pnpm --filter @ysk-kit/desktop test`
+Full steps: `docs/skills/desktop-electron.md`.

package/templates/agent/skills/envelope-api/SKILL.md

@@ -3,6 +3,15 @@ name: envelope-api
 description: >
   Keep YSK Kit JSON routes on { ok, data } / { ok, error } unless the change is one of the four exceptions.
   Use when adding a route, SSE, PDF, error shape, or /envelope-api.
+  中文：envelope、錯誤碼、AppError、webhook JSON。
+  Do not use to invent a parallel error JSON or a fifth envelope exception without asking.
 ---
 
 Read `docs/skills/envelope-api.md`. Law: `AGENTS.md`.
+
+1. DTO + OkSchema/ErrSchema first. `throw new AppError('<CODE>')`.
+2. JSON stays envelope. Exceptions: LLM SSE, invoice PDF 302, GET /docs, GET /openapi.json.
+3. Webhooks: still envelope, raw body, off ts-rest. Sync ERROR_MESSAGE zh-HK and en.
+Gotcha: ask before a fifth exception. New codes need HTTP_STATUS too.
+Verify: fixtures show `{ ok, data }` / `{ ok, error }`.
+Full steps: `docs/skills/envelope-api.md`.

package/templates/agent/skills/fix-layers/SKILL.md

@@ -3,6 +3,15 @@ name: fix-layers
 description: >
   Repair a pnpm layers (dependency-cruiser) failure without disabling hexagonal rules.
   Use when pnpm layers fails, a client imported Prisma, or /fix-layers.
+  中文：分層、dependency-cruiser、客戶端 Prisma。
+  Do not use to edit .dependency-cruiser.cjs without explicit approval.
 ---
 
 Read `docs/skills/fix-layers.md`. Law: `AGENTS.md`.
+
+1. Read the cruiser rule name (`clients-no-server-infra`, `domain-no-infra`, …).
+2. Move the import (SDK / port in infra / type in contracts). Do not disable the rule.
+3. Re-run `pnpm layers`, then verify-change.
+Gotcha: never edit `.dependency-cruiser.cjs` without explicit this-turn approval.
+Verify: `pnpm layers`
+Full steps: `docs/skills/fix-layers.md`.

package/templates/agent/skills/llm-feature/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: llm-feature
+description: >
+  Build a YSK Kit LLM feature with a server-owned prompt, Zod-validated
+  output, untrusted-content delimiting, quota, and createFakeLlm evals.
+  Use when adding or changing /v1/llm, a product prompt, streaming, or ysk-kit add llm.
+  中文：LLM、system prompt、配額、createFakeLlm、評測。
+  Do not use for generic chat UI with no server prompt, or for a security
+  audit of non-LLM code (security-review).
+---
+
+Read `docs/skills/llm-feature.md`. Law: `AGENTS.md`.
+
+1. Client roles are user/assistant only (`LlmClientRoleSchema`). Server prepends `LLM_SYSTEM_PROMPT`.
+2. Fence untrusted user text. Parse structured output with Zod in application/.
+3. Quota `LLM_QUOTA_*` → RATE_LIMITED. Evals: ≥5 normal + ≥3 adversarial `createFakeLlm`. No live provider in CI.
+Gotcha: v1.2.2 already removed client `system` and added quota — describe current code, do not list those as gaps.
+Verify: `pnpm --filter @ysk-kit/api exec vitest run src/modules/llm`
+Full steps: `docs/skills/llm-feature.md`.

package/templates/agent/skills/new-product/SKILL.md

@@ -3,6 +3,15 @@ name: new-product
 description: >
   Scaffold a product from YSK Kit with create-ysk-app (flavor, preset, database).
   Use when the user wants a new product, create-ysk-app, or /new-product.
+  中文：開新產品、create-ysk-app、flavor、doctor。
+  Do not use to add a module inside this kit (add-module) or to invent a parallel monorepo.
 ---
 
 Read `docs/skills/new-product.md`. Law: `AGENTS.md`.
+
+1. Pick flavor (saas default; desktop / gateway / php-bridge / trading / static-web3).
+2. `pnpm create @ysk-kit/app <name> --preset thin --db mysql --flavor saas --yes`.
+3. migrate/seed when the flavor has an API. Run `pnpm ysk-kit doctor`.
+Gotcha: leave `eas.json` / `app.config.ts` projectId as `replace-me` for a human.
+Verify: `pnpm ysk-kit doctor`
+Full steps: `docs/skills/new-product.md`.

package/templates/agent/skills/plan-feature/SKILL.md

@@ -3,6 +3,15 @@ name: plan-feature
 description: >
   Write a YSK Kit feature plan to docs/plans/<yyyy-mm-dd>-<slug>.md before contracts and code.
   Use when the user wants a plan, plan.md, design, or a multi-surface change.
+  中文：計劃、plan.md、合約之前。
+  Do not use for typo-only or one-file mechanical renames.
 ---
 
 Read `docs/skills/plan-feature.md`. Law: `AGENTS.md`.
+
+1. Confirm a plan is required. Explore the tree (modules, contracts, SDK) first.
+2. `pnpm ysk-kit plan <slug>` and fill every template heading.
+3. `pnpm ysk-kit plan --check` both language files. Wait for approval.
+Gotcha: do not implement first and backfill. If rejected as too short, expand.
+Verify: `pnpm ysk-kit plan --check docs/plans/<date>-<slug>.md`
+Full steps: `docs/skills/plan-feature.md`.

package/templates/agent/skills/review-change/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: review-change
+description: >
+  Review a YSK Kit diff on two axes: Law (AGENTS.md hard rules, definition of
+  done, Do-not list) and Spec (the dated plan's scope and checklist). Flag
+  high-risk items for a human.
+  Use when asked to review a PR, a branch vs main, or uncommitted work; or /review-change.
+  中文：審查、法律軸、計劃軸、高風險人工、合理化表。
+  Do not use for implementing the change (plan-feature) or a dedicated
+  security/Prisma deep dive (security-review, db-migration).
+---
+
+Read `docs/skills/review-change.md`. Law: `AGENTS.md`.
+
+1. Diff is the report. Score Law (hard rules/DoD/Do-not) and Spec (dated plan).
+2. Flag authz, webhooks, SQL DROP, secrets, LLM, breaking contracts for a human.
+3. Run verify-change. Fill the rationalization table (no empty reasons).
+Gotcha: do not self-approve high-risk; link security-review / db-migration.
+Verify: `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`
+Full steps: `docs/skills/review-change.md`.

package/templates/agent/skills/security-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: security-review
+description: >
+  Review YSK Kit authz, tenant isolation, secrets, logging redaction, token
+  storage, webhook signatures, and LLM input against hexagonal modules and
+  the {ok,data}/{ok,error} envelope. Optional lightweight threat-model mode.
+  Use when the user asks for a security review or audit; the diff touches
+  auth, apikey, organizations, billing, files, crypto, webhooks, env/secrets,
+  or a new capability; or the plan's security section is not "none".
+  中文：安全審查、權限、跨租戶、密鑰、日誌遮罩、webhook 簽名。
+  Do not use for pure UI styling, docs typos, or generic dependency bumps.
+---
+
+Read `docs/skills/security-review.md`. Law: `AGENTS.md`.
+
+1. Diff is the report scope; the repo is research. HIGH confidence only.
+2. AuthZ in `application/` (membership + role). Cross-tenant memory tests.
+3. No secrets in logs. Webhook signatures. Client token stores.
+4. Threat-model sub-mode only when the user asks or a new trust boundary lands.
+Full steps: `docs/skills/security-review.md`.

package/templates/agent/skills/test-plan/SKILL.md

@@ -5,6 +5,15 @@ description: >
   mapped to contract, memory-port, API, SDK, client, and Playwright layers.
   Use when the user asks how to test a feature, what cases to cover, or for a QA
   checklist before writing tests or shipping.
+  中文：測試計劃、風險、given/when/then。
+  Do not use for comment-only edits or to write the tests themselves (write-tests).
 ---
 
 Read `docs/skills/test-plan.md`. Law: `AGENTS.md`.
+
+1. Restate the change. Rank data loss, auth, money, tenancy, secrets first.
+2. Map each risk to a layer and file. Write given/when/then cases.
+3. Name in-memory fixtures and explicit out of scope. Then write-tests.
+Gotcha: do not start Redis or Stripe to plan tests. E2E stays thin.
+Verify: every case has layer + file; out of scope is written.
+Full steps: `docs/skills/test-plan.md`.

package/templates/agent/skills/ui-design/SKILL.md

@@ -4,6 +4,15 @@ description: >
   Design and implement YSK Kit UI with existing tokens, @ysk-kit/ui, WCAG 2.2 AA,
   forms mapped from the API envelope, and no generic AI-slop chrome.
   Use when adding or changing web, admin, mobile, or desktop screens.
+  中文：畫面、zinc、表單、可及性。
+  Do not use for API-only changes or to invent a second component library.
 ---
 
 Read `docs/skills/ui-design.md`. Law: `AGENTS.md`.
+
+1. Reuse `@ysk-kit/ui` zinc tokens (`rounded-md`, `h-9`). No new palette.
+2. Loading / empty / error / disabled. Forms: FormField + contracts Zod.
+3. WCAG 2.2 AA, `zh-HK` length, no raw fetch. Then ui-review.
+Gotcha: no purple gradients, no placeholder-as-label, no `div` buttons.
+Verify: ui-review checklist, then verify-change.
+Full steps: `docs/skills/ui-design.md`.

package/templates/agent/skills/ui-review/SKILL.md

@@ -4,6 +4,15 @@ description: >
   QA checklist before declaring YSK Kit UI work done: visual, a11y, responsive,
   states, copy, performance — with Playwright, keyboard, and axe verification.
   Use when finishing a screen or when the user asks to review UI / UX / a11y.
+  中文：UI 審查、鍵盤、375 視埠。
+  Do not use to design the screen (ui-design) or to treat one screenshot as proof.
 ---
 
 Read `docs/skills/ui-review.md`. Law: `AGENTS.md`.
+
+1. Walk visual, a11y, states, copy. Fail if any required box is unchecked.
+2. Keyboard-only on web/admin/desktop. Check 375 / 768 / 1280.
+3. Exercise the flow (click, type, submit). Screenshot is not proof.
+Gotcha: do not add axe or screenshot diffs to CI unless asked.
+Verify: checklist + `pnpm e2e` when login/shell changed.
+Full steps: `docs/skills/ui-review.md`.

package/templates/agent/skills/verify-change/SKILL.md

@@ -3,6 +3,15 @@ name: verify-change
 description: >
   Run the YSK Kit verification chain after every feature (layers, typecheck, test, OpenAPI, check agent).
   Use when finishing a change, after add module/capability, or /verify-change.
+  中文：驗證、layers、typecheck、OpenAPI、check agent。
+  Do not use to skip commands and claim done, or to start Redis/Stripe in unit tests.
 ---
 
 Read `docs/skills/verify-change.md`. Law: `AGENTS.md`.
+
+1. Run `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`.
+2. `git diff --exit-code docs/openapi.yaml` (commit YAML if HTTP changed).
+3. Conditional: lint, check:links, zh pair, lockstep changeset, e2e.
+Gotcha: never claim done without running the five commands in this turn.
+Verify: emit the verification report in the skill output format.
+Full steps: `docs/skills/verify-change.md`.

package/templates/agent/skills/webhook-handling/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: webhook-handling
+description: >
+  Handle inbound webhooks in YSK Kit: verify signature on the raw body, ack
+  fast, idempotency by event id, out-of-order events, retries, replay tests.
+  Stripe is the main example; the same rules apply to other providers.
+  Use when adding or changing /v1/*/webhook, adding billing, or debugging
+  "paid but not activated" / duplicate fulfilments.
+  中文：webhook、驗簽、冪等、Stripe 回調、重送。
+  Do not use for outbound HTTP or a general security audit with no webhook route.
+---
+
+Read `docs/skills/webhook-handling.md`. Law: `AGENTS.md`.
+
+1. Mount raw body before JSON parsers on Express and Fastify.
+2. Verify HMAC; persist Stripe `event.id`; 200 envelope; skip duplicates.
+3. Replay tests in-memory. Do not call Stripe in CI.
+Gotcha: 401 on bad signature. Fulfilment should queue, not block the ack.
+Verify: `pnpm --filter @ysk-kit/api test`
+Full steps: `docs/skills/webhook-handling.md`.

package/templates/agent/skills/write-tests/SKILL.md

@@ -4,6 +4,15 @@ description: >
   Write professional YSK Kit tests: trophy per layer, in-memory ports, given/when/then,
   deterministic fixtures, envelope and authz cases, exact Vitest/Playwright commands.
   Use when adding tests, fixing a bug, or after test-plan.
+  中文：寫測試、Vitest、Playwright、回歸。
+  Do not use to plan cases (test-plan) or to start Redis/Stripe in CI.
 ---
 
 Read `docs/skills/write-tests.md`. Law: `AGENTS.md`.
+
+1. Put the case at the lowest layer that can fail it. Extend the generator test file.
+2. given/when/then; envelope `ok` / `error.code`; other-tenant negative when owned.
+3. Bug fixes: red regression test first. Express and Fastify for HTTP.
+Gotcha: in-memory ports only. Never mock Prisma from a client.
+Verify: `pnpm --filter @ysk-kit/<pkg> exec vitest run <file>`
+Full steps: `docs/skills/write-tests.md`.

package/templates/agent/ysk-kit.mdc

@@ -3,4 +3,4 @@ description: YSK Kit agent law — follow root AGENTS.md
 alwaysApply: true
 ---
 
-Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`.
+Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`. Daily loop: `contract-change`, `debug-issue`, `review-change`, `llm-feature`. Security / Prisma / webhooks / Electron: `docs/skills/security-review.md`, `db-migration.md`, `webhook-handling.md`, `desktop-electron.md`.

package/templates/capabilities/billing/apps/api/src/modules/billing/application/billing-service.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { createMemoryOrganizationRepository } from '../../organizations/infra/memory-organization-repository';
+import { createLogBilling } from '../infra/log-billing';
+import { createMemorySubscriptionRepository } from '../infra/memory-subscription-repository';
+import { createMemoryWebhookEventRepository } from '../infra/memory-webhook-event-repository';
+import { createBillingService } from './billing-service';
+
+describe('createBillingService webhooks', () => {
+  it('activates once and skips a replay plus a stale event', async () => {
+    const orgs = createMemoryOrganizationRepository();
+    const subscriptions = createMemorySubscriptionRepository();
+    const service = createBillingService({
+      subscriptions,
+      billing: createLogBilling(),
+      orgs,
+      webhookEvents: createMemoryWebhookEventRepository(),
+    });
+    const owner = await orgs.createWithOwner({ name: 'Pay', ownerUserId: 'user-1' });
+    await service.handleStripeEvent({
+      id: 'evt_new',
+      type: 'checkout.session.completed',
+      created: 100,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '4' },
+        },
+      },
+    });
+    await service.handleStripeEvent({
+      id: 'evt_new',
+      type: 'checkout.session.completed',
+      created: 100,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '4' },
+        },
+      },
+    });
+    await service.handleStripeEvent({
+      id: 'evt_old',
+      type: 'checkout.session.completed',
+      created: 50,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '1' },
+        },
+      },
+    });
+    const row = await subscriptions.findByOrganizationId(owner.id);
+    expect(row?.seatCount).toBe(4);
+    expect(row?.status).toBe('active');
+  });
+});

package/templates/capabilities/billing/apps/api/src/modules/billing/application/billing-service.ts

@@ -3,7 +3,9 @@ import { BILLING_PLANS, orgRoleCan } from '@ysk-kit/contracts';
 import { AppError } from '@ysk-kit/domain-kernel';
 import type { IOrganizationRepository } from '../../organizations/domain/organization-repository';
 import type { IBillingPort } from '../domain/billing-port';
+import type { StripeWebhookEvent } from '../domain/stripe-webhook-event';
 import type { ISubscriptionRepository } from '../domain/subscription-repository';
+import type { IProcessedWebhookRepository } from '../domain/webhook-event-repository';
 
 const PERIOD_MS = 1000 * 60 * 60 * 24 * 30;
 
@@ -30,6 +32,7 @@ export const createBillingService = (opts: {
   subscriptions: ISubscriptionRepository;
   billing: IBillingPort;
   orgs: IOrganizationRepository;
+  webhookEvents: IProcessedWebhookRepository;
   now?: () => Date;
 }) => {
   const now = () => opts.now?.() ?? new Date();
@@ -44,6 +47,25 @@ export const createBillingService = (opts: {
     return org;
   };
 
+  const activate = async (
+    organizationId: string,
+    planCode: SubscriptionDto['planCode'],
+    customerId?: string,
+    seatCount = 1,
+  ) => {
+    if (planCode === 'free') return;
+    const org = await opts.orgs.findById(organizationId);
+    if (!org) throw new AppError('NOT_FOUND');
+    await opts.subscriptions.upsert({
+      organizationId,
+      planCode,
+      status: 'active',
+      currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
+      seatCount,
+    });
+    if (customerId) await opts.orgs.setStripeCustomerId(organizationId, customerId);
+  };
+
   return {
     plans: () => BILLING_PLANS,
     subscription: async (userId: string, organizationId: string): Promise<SubscriptionDto> => {
@@ -64,24 +86,7 @@ export const createBillingService = (opts: {
         invoiceId,
       });
     },
-    activate: async (
-      organizationId: string,
-      planCode: SubscriptionDto['planCode'],
-      customerId?: string,
-      seatCount = 1,
-    ) => {
-      if (planCode === 'free') return;
-      const org = await opts.orgs.findById(organizationId);
-      if (!org) throw new AppError('NOT_FOUND');
-      await opts.subscriptions.upsert({
-        organizationId,
-        planCode,
-        status: 'active',
-        currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
-        seatCount,
-      });
-      if (customerId) await opts.orgs.setStripeCustomerId(organizationId, customerId);
-    },
+    activate,
     portal: async (userId: string, organizationId: string, returnUrl: string) => {
       const org = await requireBiller(userId, organizationId);
       const customerId = org.stripeCustomerId;
@@ -120,6 +125,54 @@ export const createBillingService = (opts: {
       }
       return { url: result.url };
     },
+    handleStripeEvent: async (event: StripeWebhookEvent) => {
+      if (!event.id) throw new AppError('VALIDATION_FAILED', 'Stripe event id required');
+      const organizationId = event.data.object.metadata?.organizationId;
+      const eventCreatedAt = new Date((Number.isFinite(event.created) ? event.created : 0) * 1000);
+      const claim = await opts.webhookEvents.tryClaim({
+        provider: 'stripe',
+        eventId: event.id,
+        eventType: event.type,
+        eventCreatedAt,
+        ...(organizationId ? { organizationId } : {}),
+      });
+      if (claim === 'duplicate') return { received: true as const };
+
+      try {
+        if (organizationId) {
+          const latest = await opts.webhookEvents.maxEventCreatedAt(
+            'stripe',
+            organizationId,
+            event.id,
+          );
+          if (latest && eventCreatedAt < latest) return { received: true as const };
+        }
+        if (event.type === 'checkout.session.completed') {
+          const planCode = event.data.object.metadata?.planCode;
+          const seatRaw = Number(event.data.object.metadata?.seatCount ?? '1');
+          const seatCount = Number.isFinite(seatRaw) && seatRaw >= 1 ? Math.floor(seatRaw) : 1;
+          if (organizationId && (planCode === 'pro' || planCode === 'free')) {
+            const customer = event.data.object.customer;
+            await activate(
+              organizationId,
+              planCode,
+              typeof customer === 'string' ? customer : undefined,
+              seatCount,
+            );
+          }
+        }
+        return { received: true as const };
+      } catch (error) {
+        if (
+          error instanceof AppError &&
+          (error.code === 'NOT_FOUND' || error.code === 'VALIDATION_FAILED')
+        ) {
+          return { received: true as const };
+        }
+        await opts.webhookEvents.release('stripe', event.id);
+        throw error;
+      }
+    },
     cancel: async (userId: string, organizationId: string) => {
       await requireBiller(userId, organizationId);
       const row = await opts.subscriptions.findByOrganizationId(organizationId);

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/stripe-webhook-event.ts

@@ -0,0 +1,12 @@
+export type StripeWebhookEvent = {
+  id: string;
+  type: string;
+  created: number;
+  data: {
+    object: {
+      metadata?: Record<string, string>;
+      customer?: string;
+      payment_status?: string;
+    };
+  };
+};

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/webhook-event-repository.ts

@@ -0,0 +1,19 @@
+export type ProcessedWebhookClaim = 'claimed' | 'duplicate';
+
+export type ProcessedWebhookRecord = {
+  provider: string;
+  eventId: string;
+  eventType: string;
+  eventCreatedAt: Date;
+  organizationId?: string;
+};
+
+export interface IProcessedWebhookRepository {
+  tryClaim(input: ProcessedWebhookRecord): Promise<ProcessedWebhookClaim>;
+  maxEventCreatedAt(
+    provider: string,
+    organizationId: string,
+    exceptEventId: string,
+  ): Promise<Date | null>;
+  release(provider: string, eventId: string): Promise<void>;
+}