@sylphx/flow 2.28.6 → 2.28.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sylphx/flow
 
+## 2.28.7 (2026-01-04)
+
+Align all skills with platform-led SSOT principles:
+- billing/pricing: Platform is source of truth, Stripe syncs FROM platform
+- uiux: Radix UI + UnoCSS
+- admin: INITIAL_SUPERADMIN_EMAIL bootstrap
+- auth: Better Auth, database: Drizzle, i18n: next-intl, storage: Vercel Blob
+- account-security: Re-authentication flow
+
+### 📚 Documentation
+
+- **skills:** align skills with SSOT platform-led principles ([dbb868b](https://github.com/SylphxAI/flow/commit/dbb868be48a24b672fb739f81c5dd3590f3cbe29))
+
 ## 2.28.6 (2026-01-04)
 
 Switch styling from Tailwind to UnoCSS + Iconify

package/assets/skills/account-security/SKILL.md

@@ -7,26 +7,52 @@ description: Account security - MFA, sessions, recovery. Use when protecting use
 
 ## Tech Stack
 
-* **Auth**: better-auth
+* **Auth**: Better Auth
 * **Framework**: Next.js
+* **Database**: Neon (Postgres)
+
+## Re-authentication Flow
+
+All sensitive operations require explicit re-authentication:
+
+```
+    Sensitive action triggered
+                ↓
+        Check verified session
+                ↓
+    Does the user have a password?
+        ├─ Yes → Verify password
+        └─ No  → Send email OTP (6 digits, 10-minute expiry)
+                ↓
+        Verification succeeds
+                ↓
+        Mark session as verified
+                ↓
+    Allow scoped, time-bound sensitive actions
+    (2FA setup, email change, account deletion, etc.)
+```
+
+The verified state must:
+- Have explicit scope
+- Have explicit expiration
+- Never be implicitly reused
+- Never be shared across sessions or contexts
 
 ## Non-Negotiables
 
 * Session/device visibility and revocation must exist
 * All security-sensitive actions must be server-enforced and auditable
 * Account recovery must require step-up verification
+* MFA via Better Auth (no custom implementation)
 
 ## Context
 
 Account security is about giving users control over their own safety. Users should be able to see what's accessing their account, remove suspicious sessions, and understand when something unusual happens.
 
-But it's also about protecting users from threats they don't know about. Compromised credentials, session hijacking, social engineering attacks on support — these require proactive detection, not just user vigilance.
-
 ## Driving Questions
 
-* Can a user tell if someone else has access to their account?
-* What happens when an account is compromised — how fast can we detect and respond?
-* How does the recovery flow prevent social engineering attacks?
-* What security events should trigger user notification?
-* Where are we relying on user vigilance when we should be detecting threats?
-* What would a truly paranoid user want that we don't offer?
+* Can users see all active sessions and revoke them?
+* Is re-authentication required for all sensitive actions?
+* What happens when an account is compromised?
+* How does the recovery flow prevent social engineering?
+* What security events trigger user notification?

package/assets/skills/admin/SKILL.md

@@ -10,25 +10,66 @@ description: Admin panel - RBAC, config, admin tools. Use when building admin UI
 * **Framework**: Next.js
 * **API**: tRPC
 * **Database**: Neon (Postgres)
+* **ORM**: Drizzle
+* **Components**: Radix UI
+* **Styling**: UnoCSS
+
+## Bootstrap: Super Admin
+
+Simplest possible approach:
+
+```
+INITIAL_SUPERADMIN_EMAIL=your@email.com
+```
+
+Flow:
+1. Set env variable
+2. Register with that email
+3. Automatically elevated to super_admin
+4. Done
+
+Why singular:
+- Only one initial super_admin needed
+- They promote others via admin UI
+- Simple = fewer bugs
+
+The bootstrap must:
+- Execute exactly once
+- Be non-reentrant
+- Not be bypassable
+- Not become permanent logic dependency
 
 ## Non-Negotiables
 
-* Admin bootstrap must use secure allowlist, not file seeding; must be permanently disabled after first admin
+* Admin bootstrap via INITIAL_SUPERADMIN_EMAIL only
 * All privilege grants must be audited (who/when/why)
-* Actions affecting money/access/security require step-up controls
+* Actions affecting money/access/security require step-up verification
 * Secrets must never be exposed through admin UI
+* MFA required for admin roles
 
-## Context
+## Role Hierarchy
+
+```
+super_admin
+    ↓ (can promote to)
+  admin
+    ↓ (can manage)
+  users
+```
 
-The admin platform is where operational power lives — and where operational mistakes happen. A well-designed admin reduces the chance of human error while giving operators the tools they need to resolve issues quickly.
+Only super_admin can:
+- Promote users to admin
+- Access system configuration
+- View audit logs
+
+## Context
 
-Consider: what does an operator need at 3am when something is broken? What would prevent an admin from accidentally destroying data? How do we know if someone is misusing admin access?
+The admin platform is where operational power lives — and where operational mistakes happen. A well-designed admin reduces human error while giving operators tools to resolve issues quickly.
 
 ## Driving Questions
 
-* What would an operator need during an incident that doesn't exist today?
-* Where could an admin accidentally cause serious damage?
-* How would we detect if admin access was compromised or misused?
+* Is bootstrap using INITIAL_SUPERADMIN_EMAIL correctly?
+* Can an admin accidentally cause serious damage?
+* How would we detect admin access misuse?
 * What repetitive admin tasks should be automated?
-* Where is audit logging missing or insufficient?
-* What would make the admin experience both safer and faster?
+* Where is audit logging missing?

package/assets/skills/auth/SKILL.md

@@ -7,26 +7,42 @@ description: Authentication patterns - sign-in, SSO, passkeys, sessions. Use whe
 
 ## Tech Stack
 
-* **Auth**: better-auth
+* **Auth**: Better Auth
 * **Framework**: Next.js
+* **Database**: Neon (Postgres)
+* **ORM**: Drizzle
 
 ## Non-Negotiables
 
 * All authorization decisions must be server-enforced (no client-trust)
 * Email verification required for high-impact capabilities
 * If SSO provider secrets are missing, hide the option (no broken UI)
+* Session management via Better Auth (no custom implementation)
+
+## Auth Flow
+
+```
+User initiates sign-in
+        ↓
+Better Auth handles provider/credentials
+        ↓
+Session created server-side
+        ↓
+Session token in httpOnly cookie
+        ↓
+All requests validated server-side
+```
 
 ## Context
 
-Authentication is the front door to every user's data. It needs to be both secure and frictionless — a difficult balance. Users abandon products with painful sign-in flows, but weak auth leads to compromised accounts.
+Authentication is the front door to every user's data. It needs to be both secure and frictionless. Users abandon products with painful sign-in flows, but weak auth leads to compromised accounts.
 
-Consider the entire auth journey: first sign-up, return visits, account linking, recovery flows. Where is there unnecessary friction? Where are there security gaps? What would make auth both more secure AND easier?
+Better Auth is the SSOT for authentication. No custom auth implementations.
 
 ## Driving Questions
 
-* What's the sign-in experience for a first-time user vs. returning user?
-* Where do users get stuck or abandon the auth flow?
+* Is all auth handled by Better Auth?
+* Are we building custom auth logic that Better Auth already provides?
+* What's the sign-in experience for first-time vs returning users?
 * What happens when a user loses access to their primary auth method?
-* How does the system handle auth provider outages gracefully?
-* What would passwordless-first auth look like here?
 * Where is auth complexity hiding bugs or security issues?

package/assets/skills/billing/SKILL.md

@@ -9,26 +9,55 @@ description: Billing - Stripe, webhooks, subscriptions. Use when implementing pa
 
 * **Payments**: Stripe
 * **Workflows**: Upstash Workflows + QStash
+* **Database**: Neon (Postgres)
+* **ORM**: Drizzle
+
+## Platform-Led Billing
+
+Platform is the source of truth. Stripe syncs FROM platform, not TO it.
+
+- Platform defines products, prices, features, entitlements
+- Stripe is synced to match platform state
+- No manual Stripe dashboard configuration
+- Platform state → Stripe sync (never reverse)
+- Stripe webhooks confirm sync success, not drive state
 
 ## Non-Negotiables
 
 * Webhook signature must be verified (reject unverifiable events)
 * Stripe event ID must be used for idempotency
 * Webhooks must handle out-of-order delivery
-* No dual-write: billing truth comes from Stripe events only
-* UI must only display states derivable from server-truth
+* UI must only display states derivable from platform-truth
+* No Stripe dashboard design — all configuration in code
+
+## Subscription Lifecycle
+
+```
+Platform defines plan
+        ↓
+Sync to Stripe (create Product + Price)
+        ↓
+User selects plan in UI
+        ↓
+Create Stripe Checkout Session
+        ↓
+User completes payment
+        ↓
+Webhook confirms → Update platform state
+        ↓
+Entitlements derived from platform state
+```
 
 ## Context
 
 Billing is where trust meets money. A bug here isn't just annoying — it's a financial and legal issue. Users must always see accurate state, and the system must never lose or duplicate charges.
 
-Beyond correctness, consider the user experience of billing. Is the upgrade path frictionless? Are failed payments handled gracefully? Does the dunning process recover revenue or just annoy users?
+The platform owns billing logic. Stripe is a payment processor, not a product catalog.
 
 ## Driving Questions
 
+* Is all billing configuration in code, not Stripe dashboard?
+* Can we switch payment processors without redesigning billing?
 * What happens when webhooks arrive out of order?
-* Where could revenue leak (failed renewals, unhandled states)?
-* What billing states are confusing to users?
 * How are disputes and chargebacks handled end-to-end?
-* If Stripe is temporarily unavailable, what breaks?
-* What would make the billing experience genuinely excellent?
+* Where could revenue leak (failed renewals, unhandled states)?

package/assets/skills/data-modeling/SKILL.md

@@ -15,10 +15,24 @@ description: Data modeling - entities, relationships, schemas. Use when designin
 ## Non-Negotiables
 
 * All authorization must be server-enforced (no client-trust)
-* No dual-write: billing/entitlement truth comes from Stripe events only
+* Platform is source of truth for billing/entitlements (Stripe syncs FROM platform)
 * UI must never contradict server-truth
 * High-value mutations must have audit trail (who/when/why/before/after)
 
+## Platform-Led Data Flow
+
+```
+Platform State (SSOT)
+        ↓
+  Third-party services sync FROM platform
+        ↓
+  Webhooks confirm sync success
+        ↓
+  Never reverse the flow
+```
+
+Platform defines products, prices, entitlements. External services reflect platform state.
+
 ## Context
 
 Data architecture determines what's possible and what's painful. Good architecture makes new features easy; bad architecture makes everything hard. The question isn't "does it work today?" but "will it work when requirements change?"

package/assets/skills/database/SKILL.md

@@ -9,24 +9,42 @@ description: Database - schema, indexes, migrations. Use when working with datab
 
 * **Database**: Neon (Postgres)
 * **ORM**: Drizzle
+* **Migrations**: Drizzle Kit
 
 ## Non-Negotiables
 
 * Migration files must exist, be complete, and be committed
 * CI must fail if schema changes aren't represented by migrations
 * No schema drift between environments
+* All queries through Drizzle (no raw SQL unless necessary)
+
+## Schema Design
+
+```typescript
+// Drizzle schema is SSOT
+export const users = pgTable('users', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull().unique(),
+  role: text('role').notNull().default('user'),
+  createdAt: timestamp('created_at').defaultNow(),
+})
+
+// Relations explicit
+export const usersRelations = relations(users, ({ many }) => ({
+  sessions: many(sessions),
+}))
+```
 
 ## Context
 
-The database schema is the foundation everything else is built on. A bad schema creates friction for every feature built on top of it. Schema changes are expensive and risky — it's worth getting the design right.
+The database schema is the foundation everything else is built on. A bad schema creates friction for every feature built on top of it. Schema changes are expensive and risky — get the design right.
 
-Consider not just "does the schema work?" but "does this schema make the right things easy?" Are the relationships correct? Are we storing data in ways that will be painful to query? Are we missing constraints that would prevent bugs?
+Drizzle is the SSOT for database access. Type-safe, end-to-end.
 
 ## Driving Questions
 
-* If we were designing the schema from scratch, what would be different?
-* Where are missing indexes causing slow queries we haven't noticed yet?
-* What data relationships are awkward or incorrectly modeled?
-* How does the schema handle data lifecycle (soft deletes, archival, retention)?
+* Is all database access through Drizzle?
+* Are migrations complete and committed?
 * What constraints are missing that would prevent invalid state?
-* Where will the current schema hurt at 10x or 100x scale?
+* Where are missing indexes causing slow queries?
+* How does the schema handle data lifecycle?

package/assets/skills/i18n/SKILL.md

@@ -15,27 +15,38 @@ description: Internationalization - localization, translations. Use when adding
 * `/en/*` must not exist (permanently redirect to non-prefixed)
 * Missing translation keys must fail build
 * No hardcoded user-facing strings outside localization
-* Translation bundles must be split by namespace or route (no monolithic language files)
+* Translation bundles must be split by namespace (no monolithic files)
+* Server Components for translations wherever possible
+
+## Bundle Strategy
+
+```
+messages/
+├── en/
+│   ├── common.json      # Shared strings
+│   ├── auth.json        # Auth flow
+│   ├── dashboard.json   # Dashboard
+│   └── settings.json    # Settings
+└── zh/
+    ├── common.json
+    ├── auth.json
+    ├── dashboard.json
+    └── settings.json
+```
+
+Each route loads only its required namespaces.
+Client bundles must not include server-only translations.
 
 ## Context
 
-Internationalization isn't just translation — it's making the product feel native to each market. Bad i18n is obvious to users and signals that they're second-class citizens. Good i18n is invisible.
+Internationalization isn't just translation — it's making the product feel native to each market. Bad i18n signals users are second-class citizens. Good i18n is invisible.
 
-Consider: dates, numbers, currency, pluralization, text direction, cultural norms. Does the product feel like it was built for each locale, or does it feel like a translation of an English product?
+next-intl is the SSOT for i18n. No custom implementations.
 
 ## Driving Questions
 
-* What would make the product feel native to a non-English user?
-* Where do translations feel awkward or machine-generated?
-* What cultural assumptions are baked into the UX that don't translate?
-* How painful is the translation workflow for adding new strings?
-* What locales are we missing that represent real market opportunity?
-* Where do we fall back to English in ways users would notice?
-* How large are the translation bundles, and what's being sent to the client?
-
-## Bundle Constraints
-
-* No monolithic language files — split by namespace (`common`, `auth`, `dashboard`, etc.)
-* Server Components for translations wherever possible — client bundles must not include translations that could stay on server
-* Each route should load only its required namespaces
-* Measure client bundle size impact of translations
+* Is next-intl handling all translations?
+* Are bundles split by namespace?
+* What would make the product feel native to non-English users?
+* Where do translations feel awkward?
+* How large are client-side translation bundles?

package/assets/skills/ledger/SKILL.md

@@ -16,7 +16,21 @@ description: Financial ledger - transactions, audit trails. Use when tracking mo
 * Balances must be immutable ledger (append-only), not mutable fields
 * No floating-point for money (use deterministic precision)
 * All financial mutations must be idempotent
-* Monetary flows must be reconcilable with Stripe
+* Platform ledger is source of truth (Stripe syncs FROM platform)
+
+## Platform-Led Financial State
+
+```
+Platform Ledger (SSOT)
+        ↓
+  Stripe syncs from platform
+        ↓
+  Webhooks confirm sync success
+        ↓
+  Reconciliation verifies alignment
+```
+
+Platform defines credits, balances, transactions. Stripe reflects platform state, not the reverse.
 
 ## Context
 

package/assets/skills/observability/SKILL.md

@@ -14,19 +14,20 @@ description: Observability - logging, metrics, tracing. Use when adding monitori
 ## Non-Negotiables
 
 * Correlation IDs must exist end-to-end (request → job → webhook)
-* Alerts must exist for critical failures (webhook failures, auth attacks, drift)
+* Alerts must exist for critical failures
+* No PII in logs or error tracking
+* Errors must be actionable, not noise
 
 ## Context
 
-Observability is about answering questions when things go wrong. It's 3am, something is broken, users are complaining — can you figure out what happened? How fast?
+Observability is about answering questions when things go wrong. It's 3am, something is broken — can you figure out what happened? How fast?
 
-Good observability makes debugging easy. Bad observability means you're guessing, adding log lines, redeploying, and hoping. Consider: what questions would you need to answer during an incident, and can you answer them today?
+Good observability makes debugging easy. Bad observability means guessing, adding logs, redeploying, hoping.
 
 ## Driving Questions
 
-* If something breaks in production right now, how would we find out?
+* If something breaks now, how would we find out?
 * What blind spots exist where errors go unnoticed?
-* How long would it take to trace a user's request through the entire system?
-* What alerts exist, and do they fire for the right things?
-* Where do we have noise that's training people to ignore alerts?
-* What production issue in the last month was hard to debug, and why?
+* How long to trace a request through the system?
+* What alerts exist, and do they fire correctly?
+* Where is noise training people to ignore alerts?

package/assets/skills/pricing/SKILL.md

@@ -8,24 +8,53 @@ description: Pricing strategy - tiers, feature gating. Use when designing pricin
 ## Tech Stack
 
 * **Payments**: Stripe
+* **Database**: Neon (Postgres)
+* **ORM**: Drizzle
+
+## Platform-Led Pricing
+
+Platform is the source of truth for all pricing.
+
+- Products, prices, tiers, features defined in platform code
+- Stripe Products/Prices created via sync, not manually
+- No Stripe dashboard configuration
+- Pricing changes → code change → sync to Stripe
+- Historical prices remain in Stripe (immutable)
 
 ## Non-Negotiables
 
-* Stripe is system-of-record; internal systems must not contradict Stripe truth
-* Pricing changes must create new Stripe Prices (historical prices immutable)
-* Non-admin Stripe Dashboard changes must be detectable (drift)
+* All pricing configuration must be in code
+* No manual Stripe dashboard changes
+* Pricing drift must be detectable and auto-correctable
+* Feature entitlements derived from platform state, not Stripe metadata
+
+## Pricing Model
+
+```typescript
+// Platform defines pricing (code is SSOT)
+const plans = {
+  free: { price: 0, features: ['basic'] },
+  pro: { price: 29, features: ['basic', 'advanced', 'priority'] },
+  enterprise: { price: 299, features: ['basic', 'advanced', 'priority', 'sla'] }
+}
+
+// Sync to Stripe on deploy/startup
+await syncPricingToStripe(plans)
+```
 
 ## Context
 
-Pricing is strategy, not just configuration. The right pricing captures value, reduces friction, and aligns incentives. The wrong pricing leaves money on the table or drives users away.
+Pricing is strategy, not just configuration. The right pricing captures value, reduces friction, and aligns incentives.
 
-Consider the entire monetization journey: how users discover value, how they decide to pay, how they upgrade/downgrade. Where is there friction? Where are we undercharging? Where are we losing conversions?
+Platform owns pricing. Stripe is the payment processor. This separation allows:
+- A/B testing pricing without Stripe changes
+- Switching processors without repricing
+- Complex entitlement logic beyond Stripe's model
 
 ## Driving Questions
 
-* How does our pricing compare to competitors?
-* Where do users abandon the upgrade flow?
+* Is all pricing defined in code?
+* Can we change pricing without touching Stripe dashboard?
+* How do we test pricing changes before going live?
 * What would make upgrading feel like an obvious decision?
-* How do we communicate value at each pricing tier?
-* What pricing experiments would teach us the most?
-* If we could change one thing about pricing, what would have the biggest impact?
+* How do we communicate value at each tier?

package/assets/skills/storage/SKILL.md

@@ -9,24 +9,39 @@ description: File storage - uploads, CDN, blobs. Use when handling files.
 
 * **Storage**: Vercel Blob
 * **Platform**: Vercel
+* **Framework**: Next.js
 
 ## Non-Negotiables
 
-* Uploads must be intent-based and server-verified (no direct client uploads to permanent storage)
+* Uploads must be intent-based and server-verified
+* No direct client uploads to permanent storage
 * Server must validate blob ownership before attaching to resources
 * Abandoned uploads must be cleanable
 
+## Upload Flow
+
+```
+Client requests upload URL
+        ↓
+Server creates signed upload token
+        ↓
+Client uploads to Vercel Blob
+        ↓
+Server validates and attaches to resource
+        ↓
+Orphaned blobs cleaned periodically
+```
+
 ## Context
 
-File uploads are a common attack vector. Users upload things you don't expect. Files live longer than you plan. Storage costs accumulate quietly. A well-designed upload system is secure, efficient, and maintainable.
+File uploads are a common attack vector. Users upload things you don't expect. Files live longer than you plan. Storage costs accumulate quietly.
 
-Consider: what could a malicious user upload? What happens to files when the referencing entity is deleted? How does storage cost scale with usage?
+Vercel Blob is the SSOT for file storage. No custom implementations.
 
 ## Driving Questions
 
-* What could a malicious user do through the upload flow?
-* What happens to orphaned files when entities are deleted?
-* How much are we spending on storage, and is it efficient?
+* Is all storage through Vercel Blob?
+* Are uploads validated server-side?
+* What happens to orphaned files?
 * What file types do we accept, and should we?
-* How do we handle upload failures gracefully?
-* What content validation exists (type, size, safety)?
+* How much are we spending on storage?

package/assets/skills/uiux/SKILL.md

@@ -8,23 +8,48 @@ description: UI/UX - design system, accessibility. Use when building interfaces.
 ## Tech Stack
 
 * **Framework**: Next.js
+* **Components**: Radix UI
+* **Styling**: UnoCSS
 * **Icons**: Iconify
 
+## Radix UI Everywhere
+
+Use Radix UI comprehensively. If Radix has a primitive for it, use it.
+No custom implementations of solved problems.
+No alternative component libraries.
+
+Radix primitives are the SSOT for:
+- Dialogs, modals, sheets
+- Dropdowns, menus, context menus
+- Popovers, tooltips, hover cards
+- Tabs, accordions, collapsibles
+- Select, combobox, radio, checkbox, switch
+- Sliders, progress, scroll areas
+- Navigation, breadcrumbs
+- Toasts, alerts
+- Avatar, aspect ratio, separator
+
+When similar UI problems arise, solve once with Radix, then reuse.
+
 ## Non-Negotiables
 
 * WCAG AA accessibility compliance
+* Radix UI for all interactive components
+* UnoCSS for styling (no Tailwind)
+* Iconify for all icons
+* Responsive design for all viewports
 
 ## Context
 
 UI/UX determines how users perceive and interact with the product. A great UI isn't just "correct" — it's delightful, intuitive, and makes complex tasks feel simple.
 
-The review should consider: does the current design truly serve users well? Or does it need fundamental rethinking? Small tweaks to a flawed design won't make it excellent. If redesign is warranted, propose it.
+Radix provides accessible, unstyled primitives. UnoCSS provides atomic styling. Together they enable consistent, accessible UI without reinventing components.
 
 ## Driving Questions
 
-* Where do users get confused, frustrated, or give up?
-* If we were designing this from scratch today, what would be different?
-* What would make this experience genuinely delightful, not just functional?
-* How does the design system enable or constrain good UX?
-* What are competitors doing that users might expect?
-* Where is the UI just "okay" when it could be exceptional?
+* Is every interactive component using Radix?
+* Are we building custom components Radix already provides?
+* Is the design consistent across the product?
+* Where do users get confused or frustrated?
+* What would make this experience genuinely delightful?
+* How does the UI behave on mobile vs desktop?

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "2.28.6",
+	"version": "2.28.7",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {