spaps 0.7.8 → 0.8.1

package/README.md

@@ -118,11 +118,12 @@ npm install spaps
 | `spaps quickstart` | Print quick-start instructions | `--port`, `--json` |
 | `spaps init` | Create a starter `.env.local` | `--json` |
 | `spaps create <name>` | Scaffold a SPAPS starter project directory and try local provisioning | `--template`, `--dir`, `--port`, `--force`, `--json` |
-| `spaps fixtures <subcommand>` | Manage repo-local `.spaps` auth fixtures | `--dir`, `--port`, `--base-url`, `--persona`, `--seed`, `--format`, `--force`, `--json` |
+| `spaps fixtures <subcommand>` | Manage repo-local `.spaps` auth fixtures | `--dir`, `--port`, `--base-url`, `--persona`, `--seed`, `--sync-server`, `--format`, `--force`, `--json` |
 | `spaps docs` | Browse or search bundled docs | `--interactive`, `--search`, `--json` |
-| `spaps tools` | Emit the AI tool spec (covers auth, stripe, dayrate, email, webhooks, policies, issue-reporting) | `--port`, `--format`, `--json` |
+| `spaps tools` | Emit the AI tool spec (covers auth, stripe, dayrate, email, webhooks, policies, billing, issue-reporting) | `--port`, `--format`, `--json` |
 | `spaps doctor` | Diagnose local environment problems and probe that every domain router is mounted | `--port`, `--stripe`, `--json` |
 | `spaps dayrate config` | Fetch the active dayrate admin config (requires admin JWT) | `--server-url`, `--port`, `--json` |
+| `spaps billing status\|attach\|verify` | Inspect, bind, and verify the current app's billing-account resolution (admin/operator) | `--billing-account-id`, `--server-url`, `--port`, `--json` |
 | `spaps email <verb>` | Thin email control-plane commands over the existing SPAPS email API | `--server-url`, `--port`, `--json`; run `spaps email --help` for verb-specific flags |
 | `spaps policy list\|create\|delete` | List, create, or delete authorization policies (admin) | `--name`, `--effect`, `--conditions`, `--id`, `--is-active`, `--limit`, `--json` |
 | `spaps webhook list\|register` | List registered webhooks or register a new outbound webhook | `--url`, `--events`, `--json` |
@@ -165,12 +166,16 @@ spaps verify --json
 spaps create my-app --template react
 spaps connect --json
 spaps fixtures apply --base-url http://localhost:5173
+spaps fixtures apply --sync-server --base-url http://localhost:5173
 spaps fixtures apply --seed --persona dayrate-entitled --base-url http://localhost:5173
 spaps fixtures storage-state --persona admin
 spaps docs --search secure-messages
 spaps doctor --stripe mock
 spaps local stop
 spaps dayrate config --json
+spaps billing status --json
+spaps billing attach --billing-account-id 11111111-1111-4111-8111-111111111111 --json
+spaps billing verify --json
 spaps email --help
 spaps email send --help
 spaps email send --template-key welcome --to user@example.com --context '{"user_name":"Jane"}' --json
@@ -268,10 +273,23 @@ Then run:
 
 ```bash
 npx spaps fixtures apply --base-url http://localhost:5173
+npx spaps fixtures apply --sync-server --base-url http://localhost:5173
 npx spaps fixtures apply --seed --persona issue-reporter-blocked --base-url http://localhost:5173
 npx spaps fixtures storage-state --persona admin
 ```
 
+Use `--sync-server` when a local app needs real SPAPS DB state. It calls the
+local-only `/api/dev/fixtures/apply` endpoint to upsert fixture users,
+memberships, and entitlements, then writes ownership metadata to
+`.spaps/fixtures.lock.json`. It refuses non-local targets and only runs when
+`/health/local-mode` reports local mode active.
+
+The default fixture pack includes shared personas (`user`, `admin`, `premium`),
+CFO-style `cfo-billing-demo` company entitlements, and HTMA-style
+`htma-local-auth` invite/template seed state. Browser artifacts keep
+entitlements as plain keys, while `--sync-server` can send structured grants
+with resource scope metadata to SPAPS.
+
 Use `--seed` when a persona declares backend seed steps in `.spaps/users.json`. Seeding is opt-in, only runs against a reachable local-mode SPAPS server, and reuses the persona selectors already defined in the fixture kernel instead of adding fixture-only backend routes.
 
 What `apply` emits:
@@ -295,6 +313,38 @@ That bridge does three things:
 - intercepts `/api/auth/user`, `/api/auth/login`, `/api/auth/logout`, `/api/entitlements`, and `/api/entitlements/check`
 - renders a tiny persona switcher so you can flip between `user`, `admin`, and `premium`
 
+Personas can also carry app-owned demo state in `.spaps/users.json`:
+
+```json
+{
+  "code": "pds-initiator",
+  "display_name": "PDS Initiator",
+  "profile": { "user_id": "00000000-0000-0000-0000-000000000001" },
+  "scenario": {
+    "pds": {
+      "dashboard": "work",
+      "role": "initiator"
+    }
+  }
+}
+```
+
+`scenario` is opaque to SPAPS. It is copied into `browser/<persona>.context.json`, persisted as `spaps.fixture.scenario`, and exposed by the bridge:
+
+```js
+const pdsScenario = window.__SPAPS_DEV_AUTH__.getScenario("pds");
+
+const unsubscribe = window.__SPAPS_DEV_AUTH__.onPersonaChange((event) => {
+  console.log(event.persona.code, event.scenario.pds);
+});
+
+window.addEventListener("spaps:persona-change", (event) => {
+  console.log(event.detail.persona.code);
+});
+```
+
+Use this for persona-specific dashboard stories, queues, and UI fixture hints. Keep product-specific data in the consuming app; SPAPS only owns the persona/auth/role/entitlement envelope.
+
 ## Middleware Example
 
 The main module exports admin and permission helpers for Express-style apps.

package/assets/local-runtime/Dockerfile

@@ -12,12 +12,13 @@ RUN apt-get update && \
         curl \
     && rm -rf /var/lib/apt/lists/*
 
-ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.0
+ARG SPAPS_SERVER_QUICKSTART_VERSION=0.5.1
 RUN pip install --no-cache-dir "spaps-server-quickstart==${SPAPS_SERVER_QUICKSTART_VERSION}"
 RUN python - <<'PY'
 from pathlib import Path
 
 from spaps_server_quickstart.domains.auth import schemas
+from spaps_server_quickstart.middleware import local_mode
 
 schema_path = Path(schemas.__file__)
 text = schema_path.read_text(encoding="utf-8")
@@ -26,6 +27,16 @@ text = text.replace(
     "    refresh_token: str | None = None\n",
 )
 schema_path.write_text(text, encoding="utf-8")
+
+local_mode_path = Path(local_mode.__file__)
+text = local_mode_path.read_text(encoding="utf-8")
+text = text.replace(
+    'default_factory=lambda: {"issue_reporting_required_capability": "view_products"}',
+    'default_factory=lambda: {"issue_reporting_required_capability": "view_products", "issue_reporting_input_modes": ["text", "voice"]}',
+)
+if '"issue_reporting_input_modes"' not in text:
+    raise RuntimeError("Failed to patch local-mode issue reporting input modes")
+local_mode_path.write_text(text, encoding="utf-8")
 PY
 
 COPY alembic.ini /app/alembic.ini

package/assets/local-runtime/alembic/versions/000000000024_app_links.py

@@ -0,0 +1,55 @@
+"""application-scoped short links
+
+Revision ID: 000000000024
+Revises: 000000000018
+Create Date: 2026-05-03
+
+Adds app_links, a reusable per-application short-link table for browser
+applications that need stable public URLs for compressed state.
+"""
+
+from alembic import op
+
+revision = "000000000024"
+down_revision = "000000000018"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS app_links (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            application_id UUID NOT NULL
+                REFERENCES applications(id) ON DELETE CASCADE,
+            owner_user_id UUID NOT NULL
+                REFERENCES users(id) ON DELETE CASCADE,
+            owner_username VARCHAR(64) NOT NULL,
+            slug VARCHAR(48) NOT NULL,
+            app_slug VARCHAR(64) NOT NULL,
+            resource_kind VARCHAR(64) NOT NULL,
+            title VARCHAR(160),
+            target_path TEXT NOT NULL,
+            metadata JSONB DEFAULT '{}'::jsonb,
+            click_count INTEGER NOT NULL DEFAULT 0,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            CONSTRAINT uq_app_links_application_owner_slug
+                UNIQUE (application_id, owner_username, slug)
+        );
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_app_links_application_owner_created
+        ON app_links (application_id, owner_user_id, created_at DESC);
+    """)
+    op.execute("""
+        CREATE INDEX IF NOT EXISTS ix_app_links_public_lookup
+        ON app_links (application_id, owner_username, slug);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_app_links_public_lookup;")
+    op.execute("DROP INDEX IF EXISTS ix_app_links_application_owner_created;")
+    op.execute("DROP TABLE IF EXISTS app_links;")
+

package/assets/local-runtime/alembic/versions/000000000025_x402_svm_fee_payer.py

@@ -0,0 +1,30 @@
+"""x402 SVM fee payer billing account ref
+
+Revision ID: 000000000025
+Revises: 000000000024
+Create Date: 2026-05-03
+
+Adds the trusted Solana fee-payer wallet reference required by exact SVM x402
+payment requirements.
+"""
+
+from alembic import op
+
+revision = "000000000025"
+down_revision = "000000000024"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        ALTER TABLE billing_accounts
+        ADD COLUMN IF NOT EXISTS x402_fee_payer_wallet_ref TEXT;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        ALTER TABLE billing_accounts
+        DROP COLUMN IF EXISTS x402_fee_payer_wallet_ref;
+    """)

package/assets/local-runtime/docker-compose.yml

@@ -4,7 +4,7 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        SPAPS_SERVER_QUICKSTART_VERSION: ${SPAPS_SERVER_QUICKSTART_VERSION:-0.5.0}
+        SPAPS_SERVER_QUICKSTART_VERSION: ${SPAPS_SERVER_QUICKSTART_VERSION:-0.5.1}
     restart: unless-stopped
     ports:
       - "${SPAPS_LOCAL_PORT:-3301}:8000"

package/assets/local-runtime/manifest.json

@@ -1,5 +1,5 @@
 {
-  "spaps_server_quickstart_version": "0.5.0",
+  "spaps_server_quickstart_version": "0.5.1",
   "portable_runtime": {
     "default_local_mode": true,
     "default_auth_base_url": "http://localhost:5173",

package/client.js

@@ -70,14 +70,22 @@ try {
     }
     
     async createCheckoutSession(priceId, successUrl, cancelUrl) {
-      return this.client.post('/api/stripe/create-checkout-session', 
-        { price_id: priceId, success_url: successUrl, cancel_url: cancelUrl },
+      return this.client.post('/api/stripe/checkout-sessions',
+        {
+          mode: 'payment',
+          line_items: [{ price_id: priceId, quantity: 1 }],
+          success_url: successUrl,
+          cancel_url: cancelUrl || successUrl
+        },
         { headers: { Authorization: `Bearer ${this.accessToken}` } }
       );
     }
     
-    async getSubscription() {
-      return this.client.get('/api/stripe/subscription', {
+    async getSubscription(subscriptionId) {
+      const path = subscriptionId
+        ? `/api/stripe/subscription/${encodeURIComponent(subscriptionId)}`
+        : '/api/stripe/subscriptions';
+      return this.client.get(path, {
         headers: { Authorization: `Bearer ${this.accessToken}` }
       });
     }
@@ -132,8 +140,11 @@ try {
       );
     }
     
-    async cancelSubscription() {
-      return this.client.delete('/api/stripe/subscription', {
+    async cancelSubscription(subscriptionId, options = {}) {
+      if (!subscriptionId) {
+        throw new Error('subscriptionId is required to cancel a subscription.');
+      }
+      return this.client.post(`/api/stripe/subscription/${encodeURIComponent(subscriptionId)}/cancel`, options, {
         headers: { Authorization: `Bearer ${this.accessToken}` }
       });
     }
@@ -144,4 +155,4 @@ try {
   module.exports.default = SPAPSClient;
   module.exports.SPAPS = SPAPSClient;
   module.exports.SweetPotatoSDK = SPAPSClient;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.8",
+  "version": "0.8.1",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {

package/src/cli-dispatcher.js

@@ -229,6 +229,7 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .option('--base-url <url>', 'Browser app base URL for generated storage-state files')
     .option('--persona <persona>', 'Persona code to target for apply or storage-state export')
     .option('--seed', 'Run persona-declared seed requests against the local SPAPS server', false)
+    .option('--sync-server', 'Reconcile fixture users, memberships, and entitlements into a local SPAPS server', false)
     .option('-f, --format <format>', 'Artifact format (playwright)', 'playwright')
     .option('--force', 'Overwrite fixture files during init', false)
     .option('--json', 'Output in JSON format')
@@ -241,6 +242,7 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
           baseUrl: opts.baseUrl || null,
           persona: opts.persona || null,
           seed: Boolean(opts.seed),
+          syncServer: Boolean(opts.syncServer),
           format: String(opts.format || 'playwright'),
           force: Boolean(opts.force),
           json: isJson,
@@ -345,6 +347,25 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     );
   allowDryRun(cmdDayrate);
 
+  // spaps billing <subcommand>
+  const cmdBilling = program
+    .command('billing <subcommand>')
+    .description('Billing-account operator commands (subcommand: status|attach|verify)')
+    .option('-p, --port <port>', 'Port (default: 3301)', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--billing-account-id <id>', 'Billing account id (attach)')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('billing', (opts, cmd, isJson) => ({
+        subcommand: cmd.args[0],
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        billingAccountId: opts.billingAccountId || null,
+        json: isJson,
+      }))
+    );
+  allowDryRun(cmdBilling);
+
   // spaps email
   const cmdEmail = program
     .command('email')

package/src/docs-html.js

@@ -520,13 +520,13 @@ app.post('/webhook', (req, res) => {
 // Visit: http://localhost:${port}/api/stripe/webhooks/test</code></pre>
         
         <h3>Subscription Management</h3>
-        <pre><code>// Get current subscription
-const subscription = await spaps.getSubscription();
+        <pre><code>// Get subscription by ID
+const subscription = await spaps.getSubscription(subscriptionId);
 console.log('Status:', subscription.data.status);
 console.log('Plan:', subscription.data.plan);
 
 // Cancel subscription
-await spaps.cancelSubscription();</code></pre>
+await spaps.cancelSubscription(subscriptionId);</code></pre>
         
         <h3>Usage Tracking</h3>
         <pre><code>// Check balance

package/src/docs-quick.js

@@ -17,7 +17,7 @@ function showQuickReference() {
     '  await spaps.register(email, password)',
     '  await spaps.getUser()',
     '  await spaps.createCheckoutSession(priceId, successUrl)',
-    '  await spaps.getSubscription()',
+    '  await spaps.getSubscription(subscriptionId)',
     '  await spaps.getUsageBalance()',
     '',
     chalk.green('Helper Methods:'),

package/src/docs-system.js

@@ -72,7 +72,7 @@ ${chalk.green('Token Management:')}
     content: `
 ${chalk.green('Stripe Checkout:')}
   ${chalk.gray('// Create checkout session')}
-  const session = await sdk.payments.createCheckoutSession({
+  const session = await sdk.payments.createPaymentCheckout({
     price_id: 'price_123abc',
     success_url: 'http://localhost:3000/success',
     cancel_url: 'http://localhost:3000/cancel'
@@ -86,7 +86,7 @@ ${chalk.green('Subscription Management:')}
   // Example subscription helpers would go here if enabled
   
   ${chalk.gray('// Cancel subscription')}
-  await spaps.cancelSubscription()
+  await spaps.cancelSubscription(subscriptionId)
 
 ${chalk.green('Usage Tracking:')}
   ${chalk.gray('// Check balance')}

package/src/domains.js

@@ -133,6 +133,21 @@ const POLICIES = {
   ],
 };
 
+const BILLING = {
+  key: 'billing',
+  label: 'Billing Accounts',
+  // Admin-gated; 401/403 still proves the operator route is mounted.
+  probe: { method: 'GET', path: '/api/admin/billing/status', ok_on_auth_error: true },
+  tools: [
+    { name: 'billing_status', method: 'GET', path: '/api/admin/billing/status',
+      description: 'Show current application billing-account resolution and redacted Stripe diagnostics.', admin_required: true },
+    { name: 'billing_verify', method: 'GET', path: '/api/admin/billing/verify',
+      description: 'Verify that the current application has usable Stripe secret and webhook configuration.', admin_required: true },
+    { name: 'billing_attach', method: 'POST', path: '/api/admin/billing/attach',
+      description: 'Bind the current application to an existing active Stripe billing account.', admin_required: true },
+  ],
+};
+
 const ISSUE_REPORTING = {
   key: 'issue_reporting',
   label: 'Issue Reporting',
@@ -145,16 +160,16 @@ const ISSUE_REPORTING = {
       description: 'List the caller\u2019s issue reports.' },
     { name: 'issue_report_status', method: 'GET', path: '/api/v1/issue-reports/status',
       description: 'Aggregate status for the caller\u2019s issues.' },
-    { name: 'issue_report_get', method: 'GET', path: '/api/v1/issue-reports/{report_id}',
+    { name: 'issue_report_get', method: 'GET', path: '/api/v1/issue-reports/{issue_report_id}',
       description: 'Fetch a single issue report.' },
-    { name: 'issue_report_update_note', method: 'PATCH', path: '/api/v1/issue-reports/{report_id}',
+    { name: 'issue_report_update_note', method: 'PATCH', path: '/api/v1/issue-reports/{issue_report_id}',
       description: 'Update the note on an existing report.' },
-    { name: 'issue_report_reply', method: 'POST', path: '/api/v1/issue-reports/{report_id}/replies',
+    { name: 'issue_report_reply', method: 'POST', path: '/api/v1/issue-reports/{issue_report_id}/replies',
       description: 'Reply to an issue; creates a child report and reopens the linked support case.' },
   ],
 };
 
-const DOMAINS = [DAYRATE, EMAIL, WEBHOOKS, POLICIES, ISSUE_REPORTING];
+const DOMAINS = [DAYRATE, EMAIL, WEBHOOKS, POLICIES, BILLING, ISSUE_REPORTING];
 
 function listDomains() {
   return DOMAINS;

package/src/fixture-kernel.js

@@ -17,6 +17,7 @@ const FIXTURE_KEYS = {
   profile: 'spaps.fixture.profile',
   roles: 'spaps.fixture.roles',
   entitlements: 'spaps.fixture.entitlements',
+  scenario: 'spaps.fixture.scenario',
   application: 'spaps.fixture.application',
   runtime: 'spaps.fixture.runtime',
   selector: 'spaps.fixture.selector',
@@ -305,6 +306,58 @@ const DEFAULT_PERSONAS = [
       },
     ],
   }),
+  makeDerivedPersona('cfo-billing-demo', 'CFO Billing Demo', 'admin', {
+    permissions: ['view_products', 'manage_company_billing', 'view_company_reports'],
+    profile: {
+      username: 'cfo-billing-demo',
+    },
+    scenario: {
+      cfo: {
+        pack: 'cfo.billing_demo',
+        company_id: '00000000-0000-4000-8000-00000000c001',
+        company_slug: 'fixture-cfo-company',
+        expected_entitlements: [
+          'fixture.cfo.company.billing_admin',
+          'fixture.cfo.company.reports',
+        ],
+      },
+    },
+  }),
+  makeDerivedPersona('htma-local-auth', 'HTMA Local Auth', 'user', {
+    permissions: ['view_products', 'manage_patient_protocols'],
+    profile: {
+      username: 'htma-local-auth',
+    },
+    scenario: {
+      htma: {
+        pack: 'htma.local_auth',
+        invite_template_key: 'fixture-htma-invite-{{global.run_id}}',
+        invite_action_url: 'http://localhost:5173/htma/invite/{{global.run_id}}',
+        expected_entitlements: ['fixture.htma.local_auth'],
+      },
+    },
+    seed: [
+      {
+        as: 'admin',
+        method: 'POST',
+        path: '/api/email/templates',
+        expected_statuses: [201, 409],
+        body: {
+          name: 'Fixture HTMA Invite',
+          template_key: 'fixture-htma-invite-{{global.run_id}}',
+          subject: 'HTMA invite for {{name}}',
+          html_body: '<p><a href="{{action_url}}">Open HTMA invite</a></p>',
+          text_body: 'Open HTMA invite: {{action_url}}',
+          from_email: 'noreply@example.com',
+          category: 'fixture',
+          sample_context: {
+            name: 'Fixture HTMA User',
+            action_url: 'http://localhost:5173/htma/invite/{{global.run_id}}',
+          },
+        },
+      },
+    ],
+  }),
   makeDerivedPersona('email-local-safe', 'Email Local Safe', 'user', {
     profile: {
       username: 'email-local-safe',
@@ -592,6 +645,8 @@ const DEFAULT_ROLE_GRANTS = {
   'dayrate-guest': ['user'],
   'dayrate-entitled': ['user'],
   'dayrate-overage': ['user'],
+  'cfo-billing-demo': ['admin', 'super_admin'],
+  'htma-local-auth': ['user'],
   'email-local-safe': ['user'],
   'webhook-signature-invalid': ['admin', 'super_admin'],
   'webhook-replay': ['admin', 'super_admin'],
@@ -608,6 +663,27 @@ const DEFAULT_ENTITLEMENT_GRANTS = {
   'dayrate-guest': [],
   'dayrate-entitled': ['fixture.dayrate.free.{{global.run_id}}'],
   'dayrate-overage': ['fixture.dayrate.overage.{{global.run_id}}'],
+  'cfo-billing-demo': [
+    {
+      key: 'fixture.cfo.company.billing_admin',
+      resource_type: 'company',
+      resource_id: '00000000-0000-4000-8000-00000000c001',
+      metadata: {
+        pack: 'cfo.billing_demo',
+        company_slug: 'fixture-cfo-company',
+      },
+    },
+    {
+      key: 'fixture.cfo.company.reports',
+      resource_type: 'company',
+      resource_id: '00000000-0000-4000-8000-00000000c001',
+      metadata: {
+        pack: 'cfo.billing_demo',
+        company_slug: 'fixture-cfo-company',
+      },
+    },
+  ],
+  'htma-local-auth': ['fixture.htma.local_auth'],
   'email-local-safe': [],
   'webhook-signature-invalid': [],
   'webhook-replay': [],
@@ -617,6 +693,37 @@ const DEFAULT_ENTITLEMENT_GRANTS = {
   'issue-reporter-blocked': [],
 };
 
+function normalizeEntitlementGrant(grant) {
+  if (typeof grant === 'string') {
+    return { key: grant };
+  }
+  if (!grant || typeof grant !== 'object') {
+    return { key: String(grant || '') };
+  }
+  return {
+    key: grant.key || grant.entitlement_key || '',
+    entitlement_type: grant.entitlement_type || grant.type || 'access',
+    resource_type: grant.resource_type || 'user',
+    resource_id: grant.resource_id || null,
+    metadata: grant.metadata || {},
+  };
+}
+
+function entitlementGrantKey(grant) {
+  return normalizeEntitlementGrant(grant).key;
+}
+
+function entitlementGrantKeys(grants = []) {
+  return grants.map(entitlementGrantKey).filter(Boolean);
+}
+
+function serializeEntitlementGrantForSync(grant) {
+  if (typeof grant === 'string') {
+    return grant;
+  }
+  return normalizeEntitlementGrant(grant);
+}
+
 function createCliError(code, message) {
   const error = new Error(message);
   error.code = code;
@@ -782,12 +889,14 @@ Common workflow:
 1. Run \`npx spaps fixtures init\`
 2. Edit \`.spaps/users.json\`, \`.spaps/roles.json\`, or \`.spaps/entitlements.json\`
 3. Run \`npx spaps fixtures apply\`
-4. Run \`npx spaps fixtures apply --seed --persona <code>\` when a domain persona needs real local DB state
-5. Point Playwright or local scripts at the generated browser artifacts
-6. Include \`/${DEFAULT_BRIDGE_SCRIPT_NAME}\` before your app boots if you want frontend-only persona switching
+4. Run \`npx spaps fixtures apply --sync-server\` to reconcile users, memberships, and entitlements into local SPAPS
+5. Run \`npx spaps fixtures apply --seed --persona <code>\` when a domain persona needs extra domain-specific DB state
+6. Point Playwright or local scripts at the generated browser artifacts
+7. Include \`/${DEFAULT_BRIDGE_SCRIPT_NAME}\` before your app boots if you want frontend-only persona switching
 
 Notes:
 
+- \`--sync-server\` only runs against a reachable localhost SPAPS server with local mode active
 - \`--seed\` only runs against a reachable SPAPS server with local mode active
 - Seed steps use the persona metadata already in \`.spaps/users.json\`; no extra backend-only fixture routes are required
 `;
@@ -1078,6 +1187,15 @@ function buildSeedUrl(apiUrl, requestPath, queryParams = {}) {
   return url.toString();
 }
 
+function isLocalServerUrl(apiUrl) {
+  try {
+    const parsed = new URL(apiUrl);
+    return ['localhost', '127.0.0.1', '::1'].includes(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
 function assertSeedingRuntime(runtime, port) {
   if (!runtime?.running) {
     throw createCliError(
@@ -1094,6 +1212,29 @@ function assertSeedingRuntime(runtime, port) {
   }
 }
 
+function assertServerSyncRuntime(runtime, appConfig, port) {
+  if (!runtime?.running) {
+    throw createCliError(
+      'ESYNC',
+      `Fixture server sync requires a running SPAPS server on port ${port}. Start it with "npx spaps local --port ${port}" or omit --sync-server.`
+    );
+  }
+
+  if (runtime.local_mode?.active !== true) {
+    throw createCliError(
+      'ESYNC',
+      'Fixture server sync requires SPAPS local mode. Refusing to sync fixtures into a non-local server.'
+    );
+  }
+
+  if (!isLocalServerUrl(appConfig.server.api_url)) {
+    throw createCliError(
+      'ESYNC',
+      `Fixture server sync refuses non-local SPAPS targets: ${appConfig.server.api_url}`
+    );
+  }
+}
+
 async function runSeedSequence({
   appConfig,
   usersConfig,
@@ -1237,6 +1378,136 @@ async function runFixtureSeeding({
   };
 }
 
+function buildFixtureServerSyncPayload({
+  appConfig,
+  usersConfig,
+  rolesConfig,
+  entitlementsConfig,
+  personaCode = null,
+}) {
+  const selectedCodes = personaCode
+    ? [ensurePersona(usersConfig, personaCode).code]
+    : usersConfig.personas.map((entry) => entry.code);
+
+  return {
+    source: 'spaps-fixtures',
+    application: {
+      id: appConfig.server.application_id || null,
+      slug: appConfig.server.application_slug || 'local-dev',
+      name: appConfig.server.application_slug || 'Local Development',
+      api_key: appConfig.server.api_key || null,
+      allowed_origins: [resolveStorageOrigin(appConfig.browser.base_url)],
+      settings: {
+        spaps_fixture_browser_base_url: appConfig.browser.base_url,
+      },
+    },
+    personas: selectedCodes.map((code) => {
+      const persona = ensurePersona(usersConfig, code);
+      return {
+        code,
+        display_name: persona.display_name || code,
+        profile: persona.profile || {},
+        roles: rolesConfig.grants?.[code] || [],
+        permissions: persona.permissions || [],
+        entitlements: (entitlementsConfig.grants?.[code] || []).map(serializeEntitlementGrantForSync),
+        metadata: {
+          selector: persona.selector || {},
+          scenario: persona.scenario || {},
+        },
+      };
+    }),
+  };
+}
+
+async function runFixtureServerSync({
+  appConfig,
+  runtime,
+  usersConfig,
+  rolesConfig,
+  entitlementsConfig,
+  personaCode = null,
+  port,
+}) {
+  assertServerSyncRuntime(runtime, appConfig, port);
+  const payload = buildFixtureServerSyncPayload({
+    appConfig,
+    usersConfig,
+    rolesConfig,
+    entitlementsConfig,
+    personaCode,
+  });
+
+  let response;
+  try {
+    response = await axios({
+      method: 'POST',
+      url: `${appConfig.server.api_url.replace(/\/+$/, '')}/api/dev/fixtures/apply`,
+      data: payload,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      timeout: 10000,
+      validateStatus: () => true,
+    });
+  } catch (error) {
+    throw createCliError(
+      'ESYNC',
+      `Fixture server sync failed at /api/dev/fixtures/apply: ${error.message}`
+    );
+  }
+
+  const body = unwrapEnvelope(response.data);
+  if (response.status < 200 || response.status >= 300) {
+    const message = body?.message || body?.error?.message || `status ${response.status}`;
+    throw createCliError('ESYNC', `Fixture server sync failed: ${message}`);
+  }
+
+  return body;
+}
+
+function applyServerSnapshotToUsers(usersConfig, appConfig, serverSync) {
+  if (!serverSync?.application || !Array.isArray(serverSync.personas)) {
+    return usersConfig;
+  }
+
+  const byCode = new Map(serverSync.personas.map((entry) => [entry.code, entry]));
+  appConfig.server.application_id = serverSync.application.id;
+  appConfig.server.application_slug = serverSync.application.slug;
+  appConfig.server.api_key = serverSync.application.api_key;
+
+  return {
+    ...usersConfig,
+    personas: usersConfig.personas.map((persona) => {
+      const synced = byCode.get(persona.code);
+      if (!synced) {
+        return persona;
+      }
+
+      return {
+        ...persona,
+        profile: {
+          ...(persona.profile || {}),
+          user_id: synced.user.id,
+          email: synced.user.email || persona.profile?.email,
+          username: synced.user.username || persona.profile?.username,
+          tier: synced.user.tier || persona.profile?.tier,
+        },
+        application: {
+          ...(persona.application || {}),
+          application_id: serverSync.application.id,
+          application_slug: serverSync.application.slug,
+          api_key: serverSync.application.api_key,
+        },
+        server_sync: {
+          membership_created: synced.membership_created,
+          entitlements_created: synced.entitlements_created,
+        },
+      };
+    }),
+  };
+}
+
 function stringifyStorageValue(value) {
   if (typeof value === 'string') {
     return value;
@@ -1253,10 +1524,18 @@ function buildRouteHint(appConfig, persona) {
 }
 
 function buildHeaderArtifact(appConfig, persona) {
+  const application = buildApplicationSummary(appConfig, persona);
+  const headers = {
+    ...(persona.selector?.headers || {}),
+  };
+  if (application.api_key && !headers['X-API-Key']) {
+    headers['X-API-Key'] = application.api_key;
+  }
+
   return {
     format: 'playwright-extra-http-headers',
     local_mode_active: appConfig.server.local_mode_active === true,
-    headers: persona.selector?.headers || {},
+    headers,
     route_hint: buildRouteHint(appConfig, persona),
     note:
       appConfig.server.local_mode_active === true
@@ -1297,31 +1576,32 @@ function buildFixtureTokens(appConfig, persona, roles) {
 }
 
 function buildEntitlementRecords(appConfig, persona, entitlementsConfig) {
-  const entitlementKeys = entitlementsConfig.grants?.[persona.code] || [];
+  const entitlementGrants = (entitlementsConfig.grants?.[persona.code] || []).map(normalizeEntitlementGrant);
   const application = buildApplicationSummary(appConfig, persona);
 
-  return entitlementKeys.map((entitlementKey, index) => ({
+  return entitlementGrants.map((grant, index) => ({
     id: `fixture-${persona.code}-${index + 1}`,
     application_id: application.application_id,
     beneficiary_user_id: persona.profile?.user_id || null,
     beneficiary_email: persona.profile?.email || null,
-    entitlement_key: entitlementKey,
-    entitlement_type: 'manual',
+    entitlement_key: grant.key,
+    entitlement_type: grant.entitlement_type || 'manual',
     source: 'fixture',
-    resource_type: 'user',
-    resource_id: null,
+    resource_type: grant.resource_type || 'user',
+    resource_id: grant.resource_id || null,
     starts_at: '2026-01-01T00:00:00.000Z',
     ends_at: null,
     revoked_at: null,
     metadata: {
       fixture_persona: persona.code,
+      ...(grant.metadata || {}),
     },
   }));
 }
 
 function buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig) {
   const roles = rolesConfig.grants?.[persona.code] || [];
-  const entitlements = entitlementsConfig.grants?.[persona.code] || [];
+  const entitlements = entitlementGrantKeys(entitlementsConfig.grants?.[persona.code] || []);
   const permissions = Array.isArray(persona.permissions) ? persona.permissions : [];
   const primaryRole = roles[0] || 'user';
   const application = buildApplicationSummary(appConfig, persona);
@@ -1382,8 +1662,9 @@ function buildBridgeConfig(appConfig, users, rolesConfig, entitlementsConfig) {
       application: buildApplicationSummary(appConfig, persona),
       user: buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig),
       tokens: buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []),
-      entitlement_keys: entitlementsConfig.grants?.[persona.code] || [],
+      entitlement_keys: entitlementGrantKeys(entitlementsConfig.grants?.[persona.code] || []),
       entitlements: buildEntitlementRecords(appConfig, persona, entitlementsConfig),
+      scenario: persona.scenario || {},
       browser: {
         local_storage: persona.browser?.local_storage || {},
       },
@@ -1407,8 +1688,14 @@ function buildDevAuthBridgeScript(config) {
   const PERSONA_LOCAL_STORAGE_KEYS = Array.from(new Set(
     CONFIG.personas.flatMap((persona) => Object.keys(persona.browser?.local_storage || {}))
   ));
+  const personaChangeListeners = [];
   const originalFetch = typeof window.fetch === 'function' ? window.fetch.bind(window) : null;
 
+  function clone(value) {
+    if (value === undefined || value === null) return value;
+    return JSON.parse(JSON.stringify(value));
+  }
+
   function toAbsoluteUrl(input) {
     if (input instanceof Request) return new URL(input.url, window.location.origin);
     return new URL(String(input), window.location.origin);
@@ -1427,6 +1714,63 @@ function buildDevAuthBridgeScript(config) {
     return getPersonaByCode(localStorage.getItem(ACTIVE_PERSONA_KEY)) || getPersonaByCode(getInitialPersonaCode()) || CONFIG.personas[0];
   }
 
+  function getScenario(namespace) {
+    const scenario = getCurrentPersona().scenario || {};
+    if (!namespace) return clone(scenario);
+    return Object.prototype.hasOwnProperty.call(scenario, namespace) ? clone(scenario[namespace]) : null;
+  }
+
+  function publicPersona(persona) {
+    if (!persona) return null;
+    return {
+      code: persona.code,
+      display_name: persona.display_name,
+      selector: clone(persona.selector || {}),
+      route_hint: persona.route_hint || null,
+      application: clone(persona.application || CONFIG.application),
+      user: clone(persona.user),
+      roles: clone(persona.user?.roles || []),
+      entitlements: clone(persona.entitlement_keys || []),
+      scenario: clone(persona.scenario || {})
+    };
+  }
+
+  function buildPersonaChangeDetail(previousPersona, persona) {
+    return {
+      persona: publicPersona(persona),
+      previous_persona: publicPersona(previousPersona),
+      user: clone(persona?.user || null),
+      scenario: clone(persona?.scenario || {})
+    };
+  }
+
+  function emitPersonaChange(previousPersona, persona) {
+    const detail = buildPersonaChangeDetail(previousPersona, persona);
+    personaChangeListeners.slice().forEach((listener) => {
+      try {
+        listener(detail);
+      } catch (error) {
+        console.error('[spaps-dev-auth] persona change listener failed', error);
+      }
+    });
+
+    if (typeof window.dispatchEvent === 'function' && typeof CustomEvent === 'function') {
+      window.dispatchEvent(new CustomEvent('spaps:persona-change', { detail }));
+    }
+  }
+
+  function onPersonaChange(callback) {
+    if (typeof callback !== 'function') {
+      return function noopUnsubscribe() {};
+    }
+
+    personaChangeListeners.push(callback);
+    return function unsubscribe() {
+      const index = personaChangeListeners.indexOf(callback);
+      if (index >= 0) personaChangeListeners.splice(index, 1);
+    };
+  }
+
   function clearPersonaBrowserStorage() {
     PERSONA_LOCAL_STORAGE_KEYS.forEach((key) => {
       localStorage.removeItem(key);
@@ -1441,6 +1785,7 @@ function buildDevAuthBridgeScript(config) {
     localStorage.setItem(STORAGE_KEYS.profile, JSON.stringify(persona.user));
     localStorage.setItem(STORAGE_KEYS.roles, JSON.stringify(persona.user.roles || []));
     localStorage.setItem(STORAGE_KEYS.entitlements, JSON.stringify(persona.entitlement_keys || []));
+    localStorage.setItem(STORAGE_KEYS.scenario, JSON.stringify(persona.scenario || {}));
     localStorage.setItem(STORAGE_KEYS.application, JSON.stringify(persona.application || CONFIG.application));
     localStorage.setItem(STORAGE_KEYS.runtime, JSON.stringify({
       auth_mode: CONFIG.auth_mode,
@@ -1458,11 +1803,21 @@ function buildDevAuthBridgeScript(config) {
   }
 
   function clearSession() {
-    [ACTIVE_PERSONA_KEY, STORAGE_KEYS.persona, STORAGE_KEYS.profile, STORAGE_KEYS.roles, STORAGE_KEYS.entitlements, STORAGE_KEYS.application, STORAGE_KEYS.runtime, STORAGE_KEYS.selector, TOKEN_USER_KEY, TOKEN_ACCESS_KEY, TOKEN_REFRESH_KEY, LEGACY_USER_KEY, ...PERSONA_LOCAL_STORAGE_KEYS].forEach((key) => {
+    [ACTIVE_PERSONA_KEY, STORAGE_KEYS.persona, STORAGE_KEYS.profile, STORAGE_KEYS.roles, STORAGE_KEYS.entitlements, STORAGE_KEYS.scenario, STORAGE_KEYS.application, STORAGE_KEYS.runtime, STORAGE_KEYS.selector, TOKEN_USER_KEY, TOKEN_ACCESS_KEY, TOKEN_REFRESH_KEY, LEGACY_USER_KEY, ...PERSONA_LOCAL_STORAGE_KEYS].forEach((key) => {
       localStorage.removeItem(key);
     });
   }
 
+  function switchPersona(code, options) {
+    const nextPersona = getPersonaByCode(code);
+    if (!nextPersona) return null;
+    const previousPersona = getCurrentPersona();
+    persistPersona(nextPersona);
+    emitPersonaChange(previousPersona, nextPersona);
+    if (!options || options.reload !== false) window.location.reload();
+    return nextPersona;
+  }
+
   function response(body, status) {
     return Promise.resolve(new Response(JSON.stringify(body), {
       status: status || 200,
@@ -1625,10 +1980,7 @@ function buildDevAuthBridgeScript(config) {
     button.textContent = 'Switch';
     button.style.cssText = 'background:#f59e0b;color:#111827;border:0;border-radius:8px;padding:4px 8px;cursor:pointer;font-weight:600;';
     button.onclick = function () {
-      const nextPersona = getPersonaByCode(select.value);
-      if (!nextPersona) return;
-      persistPersona(nextPersona);
-      window.location.reload();
+      switchPersona(select.value);
     };
 
     container.appendChild(label);
@@ -1648,20 +2000,17 @@ function buildDevAuthBridgeScript(config) {
         code: persona.code,
         display_name: persona.display_name,
         entitlements: persona.entitlement_keys,
-        roles: persona.user.roles || []
+        roles: persona.user.roles || [],
+        scenario: persona.scenario || {}
       }));
     },
     getCurrentPersona: getCurrentPersona,
     getCurrentUser: function () {
       return getCurrentPersona().user;
     },
-    switchPersona: function (code, options) {
-      const nextPersona = getPersonaByCode(code);
-      if (!nextPersona) return null;
-      persistPersona(nextPersona);
-      if (!options || options.reload !== false) window.location.reload();
-      return nextPersona;
-    },
+    getScenario: getScenario,
+    onPersonaChange: onPersonaChange,
+    switchPersona: switchPersona,
     clearSession: clearSession,
     installFetchBridge: installFetchBridge
   };
@@ -1697,7 +2046,11 @@ function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlements
     },
     {
       name: FIXTURE_KEYS.entitlements,
-      value: stringifyStorageValue(entitlementsConfig.grants?.[persona.code] || []),
+      value: stringifyStorageValue(entitlementGrantKeys(entitlementsConfig.grants?.[persona.code] || [])),
+    },
+    {
+      name: FIXTURE_KEYS.scenario,
+      value: stringifyStorageValue(persona.scenario || {}),
     },
     {
       name: FIXTURE_KEYS.application,
@@ -1764,7 +2117,7 @@ function buildPersonaContext(appConfig, persona, rolesConfig, entitlementsConfig
     profile: persona.profile || {},
     scenario: persona.scenario || {},
     roles: rolesConfig.grants?.[persona.code] || [],
-    entitlements: entitlementsConfig.grants?.[persona.code] || [],
+    entitlements: entitlementGrantKeys(entitlementsConfig.grants?.[persona.code] || []),
     user,
     tokens,
     application,
@@ -1785,6 +2138,7 @@ function writePersonaArtifacts({
   entitlements,
   personaCode = null,
   seedResultsByPersona = {},
+  serverSync = null,
 }) {
   const selectedCodes = personaCode ? [ensurePersona(users, personaCode).code] : users.personas.map((persona) => persona.code);
   const generated = [];
@@ -1795,6 +2149,7 @@ function writePersonaArtifacts({
     const headers = buildHeaderArtifact(appConfig, persona);
     const context = buildPersonaContext(appConfig, persona, roles, entitlements, paths);
     context.seed = seedResultsByPersona[code] || null;
+    context.server_sync = serverSync?.personas?.find((entry) => entry.code === code) || null;
 
     writeJson(context.artifacts.storage_state_path, storageState);
     writeJson(context.artifacts.headers_path, headers);
@@ -1816,6 +2171,20 @@ function writePersonaArtifacts({
     base_url: appConfig.browser.base_url,
     api_url: appConfig.server.api_url,
     local_mode_active: appConfig.server.local_mode_active,
+    ownership: serverSync
+      ? {
+          source: serverSync.source || 'spaps-fixtures',
+          application: {
+            id: serverSync.application.id,
+            slug: serverSync.application.slug,
+          },
+          personas: serverSync.personas.map((entry) => ({
+            code: entry.code,
+            user_id: entry.user.id,
+            entitlements: entry.entitlements,
+          })),
+        }
+      : null,
   });
 
   return generated;
@@ -1841,6 +2210,7 @@ async function applyFixtures({
   version = '0.0.0',
   persona = null,
   seed = false,
+  syncServer = false,
   subcommand = 'apply',
 } = {}) {
   const rootDir = resolveRepoRoot(dir);
@@ -1872,22 +2242,46 @@ async function applyFixtures({
   });
 
   const fixtureRunState = buildFixtureRunState(appConfig, runtime);
+  let resolvedUsers = {
+    ...kernel.users,
+    personas: kernel.users.personas.map((entry) => resolvePersonaDefinition(appConfig, entry, fixtureRunState)),
+  };
+  const resolvedRoles = resolveConfigTemplates(kernel.roles, fixtureRunState);
+  const resolvedEntitlements = resolveConfigTemplates(kernel.entitlements, fixtureRunState);
+  const serverSync = syncServer
+    ? await runFixtureServerSync({
+        appConfig,
+        runtime,
+        usersConfig: resolvedUsers,
+        rolesConfig: resolvedRoles,
+        entitlementsConfig: resolvedEntitlements,
+        personaCode: persona,
+        port,
+      })
+    : null;
+  if (serverSync) {
+    resolvedUsers = applyServerSnapshotToUsers(resolvedUsers, appConfig, serverSync);
+    writeJson(paths.app, appConfig);
+  }
   const seeding = seed
     ? await runFixtureSeeding({
         appConfig,
         runtime,
-        usersConfig: kernel.users,
+        usersConfig: resolvedUsers,
         personaCode: persona,
         fixtureRunState,
         port,
       })
     : null;
-  const resolvedUsers = {
-    ...kernel.users,
-    personas: kernel.users.personas.map((entry) => resolvePersonaDefinition(appConfig, entry, fixtureRunState)),
-  };
-  const resolvedRoles = resolveConfigTemplates(kernel.roles, fixtureRunState);
-  const resolvedEntitlements = resolveConfigTemplates(kernel.entitlements, fixtureRunState);
+  if (seeding) {
+    resolvedUsers = {
+      ...kernel.users,
+      personas: kernel.users.personas.map((entry) => resolvePersonaDefinition(appConfig, entry, fixtureRunState)),
+    };
+    if (serverSync) {
+      resolvedUsers = applyServerSnapshotToUsers(resolvedUsers, appConfig, serverSync);
+    }
+  }
   const seedResultsByPersona = Object.fromEntries(
     (seeding?.personas || []).map((entry) => [entry.persona, entry])
   );
@@ -1901,6 +2295,7 @@ async function applyFixtures({
     entitlements: resolvedEntitlements,
     personaCode: persona,
     seedResultsByPersona,
+    serverSync,
   });
   const bridge = writeDevAuthBridge({
     rootDir,
@@ -1919,6 +2314,7 @@ async function applyFixtures({
     fixture_dir: paths.fixtureDir,
     bootstrapped,
     runtime,
+    server_sync: serverSync,
     seeding,
     generated: {
       personas: generated,
@@ -1954,6 +2350,7 @@ async function exportStorageState(options = {}) {
     route_hint: personaArtifact.route_hint,
     bridge: result.generated.bridge,
     runtime: result.runtime,
+    server_sync: result.server_sync,
     seeding: result.seeding,
     next_steps: result.next_steps,
   };
@@ -1965,6 +2362,7 @@ async function resetFixtures({
   baseUrl = null,
   version = '0.0.0',
   seed = false,
+  syncServer = false,
 } = {}) {
   const rootDir = resolveRepoRoot(dir);
   const paths = resolveFixturePaths(rootDir);
@@ -1982,6 +2380,7 @@ async function resetFixtures({
     baseUrl,
     version,
     seed,
+    syncServer,
   });
 
   return {
@@ -1995,6 +2394,7 @@ async function resetFixtures({
     files_overwritten: initResult.files_overwritten,
     generated: applyResult.generated,
     runtime: applyResult.runtime,
+    server_sync: applyResult.server_sync,
     seeding: applyResult.seeding,
     next_steps: applyResult.next_steps,
   };

package/src/handlers.js

@@ -385,6 +385,7 @@ function createHandlers(version, logo) {
               version,
               persona: options.persona,
               seed: options.seed,
+              syncServer: options.syncServer,
             });
             break;
           case 'reset':
@@ -394,6 +395,7 @@ function createHandlers(version, logo) {
               baseUrl: options.baseUrl,
               version,
               seed: options.seed,
+              syncServer: options.syncServer,
             });
             break;
           case 'storage-state':
@@ -407,6 +409,7 @@ function createHandlers(version, logo) {
               version,
               persona: options.persona,
               seed: options.seed,
+              syncServer: options.syncServer,
             });
             break;
           default:
@@ -451,6 +454,14 @@ function createHandlers(version, logo) {
           });
         }
 
+        if (Array.isArray(result.server_sync?.personas) && result.server_sync.personas.length > 0) {
+          console.log(chalk.green('\nSynced server fixtures:'));
+          console.log(chalk.gray(`  app: ${result.server_sync.application.slug}`));
+          result.server_sync.personas.forEach((entry) => {
+            console.log(chalk.gray(`  • ${entry.code} (${entry.user.id})`));
+          });
+        }
+
         if (result.generated?.personas?.length) {
           console.log(chalk.green('\nGenerated personas:'));
           result.generated.personas.forEach((entry) => {
@@ -505,6 +516,7 @@ function createHandlers(version, logo) {
     logout: async (...args) => loadAuthCommandHandlers().logoutHandler(...args),
     whoami: async (...args) => loadAuthCommandHandlers().whoamiHandler(...args),
     token: async (...args) => loadAuthCommandHandlers().tokenHandler(...args),
+    billing: billingHandler,
     dayrate: dayrateHandler,
     email: emailHandler,
     policy: policyHandler,
@@ -600,6 +612,54 @@ async function dayrateHandler({ options }) {
   }
 }
 
+async function billingHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
+  const isJson = Boolean(options.json);
+  const sub = options.subcommand;
+  try {
+    if (sub === 'status') {
+      const result = await callEndpoint({
+        options,
+        method: 'GET',
+        path: '/api/admin/billing/status',
+      });
+      emit({ intent: 'billing.status', result, isJson });
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+
+    if (sub === 'verify') {
+      const result = await callEndpoint({
+        options,
+        method: 'GET',
+        path: '/api/admin/billing/verify',
+      });
+      emit({ intent: 'billing.verify', result, isJson });
+      if (!result.ok || result.data?.valid === false) process.exitCode = 1;
+      return;
+    }
+
+    if (sub === 'attach') {
+      if (!requireOption(options.billingAccountId, 'billing attach: --billing-account-id is required')) return;
+      const result = await callEndpoint({
+        options,
+        method: 'POST',
+        path: '/api/admin/billing/attach',
+        body: { billing_account_id: options.billingAccountId },
+      });
+      emit({ intent: 'billing.attach', result, isJson });
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+
+    console.error('billing: unknown subcommand. Supported: status, attach, verify');
+    process.exitCode = 2;
+  } catch (err) {
+    emitAuthError(`billing.${sub || 'unknown'}`, err, isJson);
+    process.exitCode = 1;
+  }
+}
+
 async function emailHandler({ options }) {
   const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);

package/src/help-system.js

@@ -320,7 +320,7 @@ SPAPS handles two payment types:
 const session = await spaps.createCheckoutSession(priceId, successUrl)
 
 // Check subscription
-const sub = await spaps.getSubscription()
+const sub = await spaps.getSubscription(subscriptionId)
 \`\`\`
         `
       }