spaps 0.7.7 → 0.8.0

package/README.md

@@ -77,9 +77,11 @@ Restore order is always: restore base dump first, then let the API container run
 Run it without installing:
 
 ```bash
-npx spaps
+npx --yes spaps
 ```
 
+For CI, SSH automation, or the first run on a fresh box, prefer `npx --yes spaps ...` so npm does not block on its install confirmation prompt.
+
 Install globally:
 
 ```bash
@@ -293,6 +295,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "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/auth/env.js

@@ -23,6 +23,10 @@ function isHeadless(env = process.env, platform = process.platform) {
   return isSsh(env) || !hasGui(env, platform);
 }
 
+function hasInteractiveTerminal(stdin = process.stdin, stdout = process.stdout) {
+  return Boolean(stdin && stdin.isTTY && stdout && stdout.isTTY);
+}
+
 function tryOpenBrowser(url, { env = process.env, platform = process.platform } = {}) {
   if (isHeadless(env, platform)) return false;
   try {
@@ -53,5 +57,6 @@ module.exports = {
   isSsh,
   hasGui,
   isHeadless,
+  hasInteractiveTerminal,
   tryOpenBrowser,
 };

package/src/docs-quick.js

@@ -0,0 +1,37 @@
+const chalk = require('chalk');
+
+function showQuickReference() {
+  const output = [
+    '',
+    chalk.yellow('🍠 SPAPS SDK Quick Reference'),
+    '',
+    chalk.green('Installation:'),
+    '  npm install spaps-sdk',
+    '',
+    chalk.green('Basic Setup:'),
+    chalk.gray(`  import { SPAPSClient } from 'spaps-sdk'`),
+    chalk.gray(`  const spaps = new SPAPSClient()`),
+    '',
+    chalk.green('Common Methods:'),
+    '  await spaps.login(email, password)',
+    '  await spaps.register(email, password)',
+    '  await spaps.getUser()',
+    '  await spaps.createCheckoutSession(priceId, successUrl)',
+    '  await spaps.getSubscription()',
+    '  await spaps.getUsageBalance()',
+    '',
+    chalk.green('Helper Methods:'),
+    `  spaps.isAuthenticated()  ${chalk.gray('// Check auth status')}`,
+    `  spaps.isLocalMode()       ${chalk.gray('// Check if local mode')}`,
+    `  spaps.getAccessToken()    ${chalk.gray('// Get current token')}`,
+    '',
+    chalk.blue('📚 Full docs: npx spaps docs --interactive'),
+    '',
+  ].join('\n');
+
+  process.stdout.write(`${output}\n`);
+}
+
+module.exports = {
+  showQuickReference,
+};

package/src/docs-system.js

@@ -5,6 +5,7 @@
 
 const chalk = require('chalk');
 const prompts = require('prompts');
+const { showQuickReference } = require('./docs-quick');
 
 const SDK_DOCS = {
   quickstart: {
@@ -676,37 +677,6 @@ async function showInteractiveDocs() {
   }
 }
 
-function showQuickReference() {
-  console.log(chalk.yellow('\n🍠 SPAPS SDK Quick Reference\n'));
-  
-  console.log(chalk.green('Installation:'));
-  console.log('  npm install spaps-sdk');
-  console.log();
-  
-  console.log(chalk.green('Basic Setup:'));
-  console.log(chalk.gray(`  import { SPAPSClient } from 'spaps-sdk'`));
-  console.log(chalk.gray(`  const spaps = new SPAPSClient()`));
-  console.log();
-  
-  console.log(chalk.green('Common Methods:'));
-  console.log('  await spaps.login(email, password)');
-  console.log('  await spaps.register(email, password)');
-  console.log('  await spaps.getUser()');
-  console.log('  await spaps.createCheckoutSession(priceId, successUrl)');
-  console.log('  await spaps.getSubscription()');
-  console.log('  await spaps.getUsageBalance()');
-  console.log();
-  
-  console.log(chalk.green('Helper Methods:'));
-  console.log('  spaps.isAuthenticated()  ' + chalk.gray('// Check auth status'));
-  console.log('  spaps.isLocalMode()       ' + chalk.gray('// Check if local mode'));
-  console.log('  spaps.getAccessToken()    ' + chalk.gray('// Get current token'));
-  console.log();
-  
-  console.log(chalk.blue('📚 Full docs: npx spaps docs --interactive'));
-  console.log();
-}
-
 function searchDocs(query) {
   const results = [];
   const searchTerm = query.toLowerCase();

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',
@@ -1384,6 +1385,7 @@ function buildBridgeConfig(appConfig, users, rolesConfig, entitlementsConfig) {
       tokens: buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []),
       entitlement_keys: entitlementsConfig.grants?.[persona.code] || [],
       entitlements: buildEntitlementRecords(appConfig, persona, entitlementsConfig),
+      scenario: persona.scenario || {},
       browser: {
         local_storage: persona.browser?.local_storage || {},
       },
@@ -1407,8 +1409,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 +1435,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 +1506,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 +1524,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 +1701,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 +1721,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
   };
@@ -1699,6 +1769,10 @@ function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlements
       name: FIXTURE_KEYS.entitlements,
       value: stringifyStorageValue(entitlementsConfig.grants?.[persona.code] || []),
     },
+    {
+      name: FIXTURE_KEYS.scenario,
+      value: stringifyStorageValue(persona.scenario || {}),
+    },
     {
       name: FIXTURE_KEYS.application,
       value: stringifyStorageValue(application),

package/src/handlers.js

@@ -2,26 +2,30 @@ const chalk = require('chalk');
 const fs = require('fs');
 const { DEFAULT_PORT } = require('./config');
 const { handleError } = require('./error-handler');
-const { showInteractiveHelp, showQuickHelp } = require('./help-system');
-const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-system');
-const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
-const { buildToolSpec } = require('./ai-tool-spec');
-const { runDoctor } = require('./doctor');
-const { buildHomeView, renderHomeView } = require('./home-view');
-const {
-  applyFixtures,
-  exportStorageState,
-  initFixtureKernel,
-  resetFixtures,
-} = require('./fixture-kernel');
-const { createProjectStarter } = require('./project-scaffolder');
-const {
-  loginHandler,
-  logoutHandler,
-  whoamiHandler,
-  tokenHandler,
-} = require('./auth/handlers');
-const { callEndpoint, emit, emitAuthError } = require('./domain-cli');
+const { hasInteractiveTerminal } = require('./auth/env');
+const { showQuickHelp } = require('./help-quick');
+const { showQuickReference } = require('./docs-quick');
+
+function lazy(factory) {
+  let value;
+  return () => {
+    if (value === undefined) {
+      value = factory();
+    }
+    return value;
+  };
+}
+
+const loadHelpSystem = lazy(() => require('./help-system'));
+const loadDocsSystem = lazy(() => require('./docs-system'));
+const loadAiHelper = lazy(() => require('./ai-helper'));
+const loadAiToolSpec = lazy(() => require('./ai-tool-spec'));
+const loadDoctor = lazy(() => require('./doctor'));
+const loadHomeView = lazy(() => require('./home-view'));
+const loadFixtureKernel = lazy(() => require('./fixture-kernel'));
+const loadProjectScaffolder = lazy(() => require('./project-scaffolder'));
+const loadAuthCommandHandlers = lazy(() => require('./auth/handlers'));
+const loadDomainCli = lazy(() => require('./domain-cli'));
 
 function createHandlers(version, logo) {
   function invalidArgument(message) {
@@ -30,7 +34,14 @@ function createHandlers(version, logo) {
     return error;
   }
 
+  function emitInteractiveFallback(message) {
+    console.log(
+      chalk.yellow(`\n⚠️  ${message}. Showing the quick reference instead.\n`)
+    );
+  }
+
   const verifyHandler = async ({ options }) => {
+    const { runQuickTest } = loadAiHelper();
     const result = await runQuickTest({
       port: options.port,
       serverUrl: options.serverUrl,
@@ -65,6 +76,7 @@ function createHandlers(version, logo) {
 
   return {
     home: async ({ options }) => {
+      const { buildHomeView, renderHomeView } = loadHomeView();
       const view = await buildHomeView({
         port: options.port,
         serverUrl: options.serverUrl,
@@ -135,6 +147,7 @@ function createHandlers(version, logo) {
       }
     },
     quickstart: async ({ options }) => {
+      const { getQuickStartInstructions } = loadAiHelper();
       const instructions = await getQuickStartInstructions(options.port);
       if (options.json) {
         console.log(JSON.stringify(instructions, null, 2));
@@ -153,6 +166,7 @@ function createHandlers(version, logo) {
       }
     },
     status: async ({ options }) => {
+      const { getServerStatus } = loadAiHelper();
       const status = await getServerStatus(options.port);
       if (options.json) {
         console.log(JSON.stringify(status));
@@ -204,6 +218,7 @@ function createHandlers(version, logo) {
     },
     create: async ({ options }) => {
       const isJson = options.json;
+      const { createProjectStarter } = loadProjectScaffolder();
 
       try {
         const result = await createProjectStarter({
@@ -269,7 +284,12 @@ function createHandlers(version, logo) {
     },
     help: async ({ options }) => {
       if (options.interactive) {
-        await showInteractiveHelp();
+        if (!hasInteractiveTerminal()) {
+          emitInteractiveFallback('Interactive help requires a TTY');
+          showQuickHelp();
+          return;
+        }
+        await loadHelpSystem().showInteractiveHelp();
       } else if (options.quick) {
         showQuickHelp();
       } else {
@@ -278,7 +298,7 @@ function createHandlers(version, logo) {
     },
     docs: async ({ options }) => {
       if (options.search) {
-        const results = searchDocs(options.search);
+        const results = loadDocsSystem().searchDocs(options.search);
         if (options.json) {
           console.log(JSON.stringify({ results }, null, 2));
         } else {
@@ -296,12 +316,18 @@ function createHandlers(version, logo) {
           console.log(chalk.blue('  to browse full documentation\n'));
         }
       } else if (options.interactive) {
-        await showInteractiveDocs();
+        if (!hasInteractiveTerminal()) {
+          emitInteractiveFallback('Interactive docs require a TTY');
+          showQuickReference();
+          return;
+        }
+        await loadDocsSystem().showInteractiveDocs();
       } else {
         showQuickReference();
       }
     },
     tools: async ({ options }) => {
+      const { buildToolSpec } = loadAiToolSpec();
       const spec = await buildToolSpec({
         format: options.format || 'openai',
         port: options.port,
@@ -328,6 +354,12 @@ function createHandlers(version, logo) {
     },
     fixtures: async ({ options }) => {
       const isJson = options.json;
+      const {
+        applyFixtures,
+        exportStorageState,
+        initFixtureKernel,
+        resetFixtures,
+      } = loadFixtureKernel();
 
       try {
         if (options.format && options.format !== 'playwright') {
@@ -465,13 +497,14 @@ function createHandlers(version, logo) {
       }
     },
     doctor: async ({ options }) => {
+      const { runDoctor } = loadDoctor();
       await runDoctor({ port: options.port || DEFAULT_PORT, stripe: options.stripe || null, json: options.json });
     },
     test: verifyHandler,
-    login: loginHandler,
-    logout: logoutHandler,
-    whoami: whoamiHandler,
-    token: tokenHandler,
+    login: async (...args) => loadAuthCommandHandlers().loginHandler(...args),
+    logout: async (...args) => loadAuthCommandHandlers().logoutHandler(...args),
+    whoami: async (...args) => loadAuthCommandHandlers().whoamiHandler(...args),
+    token: async (...args) => loadAuthCommandHandlers().tokenHandler(...args),
     dayrate: dayrateHandler,
     email: emailHandler,
     policy: policyHandler,
@@ -481,6 +514,7 @@ function createHandlers(version, logo) {
 }
 
 function emitText({ intent, result, isJson, successMessage = null }) {
+  const { emit } = loadDomainCli();
   if (isJson) {
     emit({ intent, result, isJson, successMessage });
     return;
@@ -548,6 +582,7 @@ function assignIfDefined(target, key, value) {
 }
 
 async function dayrateHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   if (sub !== 'config') {
@@ -566,6 +601,7 @@ async function dayrateHandler({ options }) {
 }
 
 async function emailHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
 
@@ -777,6 +813,7 @@ async function emailHandler({ options }) {
 }
 
 async function policyHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   try {
@@ -832,6 +869,7 @@ async function policyHandler({ options }) {
 }
 
 async function webhookHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   try {
@@ -863,6 +901,7 @@ async function webhookHandler({ options }) {
 }
 
 async function issueReportsHandler({ options }) {
+  const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
   const sub = options.subcommand;
   if (sub !== 'list-mine') {

package/src/help-quick.js

@@ -0,0 +1,42 @@
+const chalk = require('chalk');
+
+function showQuickHelp() {
+  const output = [
+    '',
+    chalk.yellow('🍠 SPAPS Quick Reference'),
+    '',
+    chalk.green('Common Commands:'),
+    `  npx spaps local                  ${chalk.gray('# Start local server')}`,
+    `  npx spaps init                   ${chalk.gray('# Initialize in project')}`,
+    `  npx spaps create <name>          ${chalk.gray('# Scaffold a SPAPS starter project')}`,
+    `  npx spaps fixtures apply         ${chalk.gray('# Generate repo-local auth fixtures')}`,
+    `  npx spaps fixtures storage-state ${chalk.gray('# Export one persona artifact')}`,
+    `  npx spaps types                  ${chalk.gray('# Generate types (v0.4.0)')}`,
+    '',
+    chalk.green('Local Development:'),
+    `  npx spaps local --port 3001      ${chalk.gray('# Custom port')}`,
+    `  npx spaps local --open           ${chalk.gray('# Open browser')}`,
+    `  npx spaps local --json           ${chalk.gray('# JSON output')}`,
+    '',
+    chalk.green('SDK Usage:'),
+    `  npm install spaps-sdk            ${chalk.gray('# Install SDK')}`,
+    '',
+    chalk.gray('  import { SPAPSClient } from "spaps-sdk"'),
+    chalk.gray('  const spaps = new SPAPSClient()'),
+    chalk.gray('  await spaps.login(email, password)'),
+    '',
+    chalk.green('Debugging:'),
+    `  curl http://localhost:3301/health   ${chalk.gray('# Check server')}`,
+    `  npx spaps help --interactive         ${chalk.gray('# Interactive help')}`,
+    '',
+    chalk.blue('📚 Docs: https://sweetpotato.dev'),
+    chalk.blue('💬 Discord: https://discord.gg/sweetpotato'),
+    '',
+  ].join('\n');
+
+  process.stdout.write(`${output}\n`);
+}
+
+module.exports = {
+  showQuickHelp,
+};

package/src/help-system.js

@@ -7,6 +7,7 @@ const chalk = require('chalk');
 const prompts = require('prompts');
 
 const { DEFAULT_PORT } = require('./config');
+const { showQuickHelp } = require('./help-quick');
 
 const HELP_TREE = {
   root: {
@@ -448,42 +449,6 @@ async function showInteractiveHelp() {
   }
 }
 
-function showQuickHelp() {
-  console.log(chalk.yellow('\n🍠 SPAPS Quick Reference\n'));
-  
-  console.log(chalk.green('Common Commands:'));
-  console.log('  npx spaps local                  ' + chalk.gray('# Start local server'));
-  console.log('  npx spaps init                   ' + chalk.gray('# Initialize in project'));
-  console.log('  npx spaps create <name>          ' + chalk.gray('# Scaffold a SPAPS starter project'));
-  console.log('  npx spaps fixtures apply         ' + chalk.gray('# Generate repo-local auth fixtures'));
-  console.log('  npx spaps fixtures storage-state ' + chalk.gray('# Export one persona artifact'));
-  console.log('  npx spaps types                  ' + chalk.gray('# Generate types (v0.4.0)'));
-  console.log();
-  
-  console.log(chalk.green('Local Development:'));
-  console.log('  npx spaps local --port 3001      ' + chalk.gray('# Custom port'));
-  console.log('  npx spaps local --open           ' + chalk.gray('# Open browser'));
-  console.log('  npx spaps local --json           ' + chalk.gray('# JSON output'));
-  console.log();
-  
-  console.log(chalk.green('SDK Usage:'));
-  console.log('  npm install spaps-sdk            ' + chalk.gray('# Install SDK'));
-  console.log();
-  console.log(chalk.gray('  import { SPAPSClient } from "spaps-sdk"'));
-  console.log(chalk.gray('  const spaps = new SPAPSClient()'));
-  console.log(chalk.gray('  await spaps.login(email, password)'));
-  console.log();
-  
-  console.log(chalk.green('Debugging:'));
-  console.log('  curl http://localhost:3301/health   ' + chalk.gray('# Check server'));
-  console.log('  npx spaps help --interactive         ' + chalk.gray('# Interactive help'));
-  console.log();
-  
-  console.log(chalk.blue('📚 Docs: https://sweetpotato.dev'));
-  console.log(chalk.blue('💬 Discord: https://discord.gg/sweetpotato'));
-  console.log();
-}
-
 module.exports = {
   showInteractiveHelp,
   showQuickHelp,