@vellumai/assistant 0.6.5 → 0.6.6

package/src/cli/commands/oauth/__tests__/providers-register.test.ts

@@ -148,7 +148,7 @@ const sampleProviderRow = {
   userinfoUrl: null,
   baseUrl: null,
   defaultScopes: "[]",
-  scopePolicy: "{}",
+  availableScopes: null,
   scopeSeparator: null,
   authorizeParams: null,
   managedServiceConfigKey: null,

package/src/cli/commands/oauth/__tests__/providers-update.test.ts

@@ -148,7 +148,7 @@ const sampleProviderRow = {
   userinfoUrl: null,
   baseUrl: null,
   defaultScopes: "[]",
-  scopePolicy: "{}",
+  availableScopes: null,
   scopeSeparator: null,
   authorizeParams: null,
   managedServiceConfigKey: null,

package/src/cli/commands/oauth/connect.ts

@@ -105,8 +105,8 @@ Arguments:
   provider   Provider name (e.g. google, slack, notion).
              Run 'assistant oauth providers list' to see available providers.
 
-In managed mode, --scopes must be in the provider's allowed set (use full
-scope URLs). In BYO mode, --scopes are appended to the provider's defaults.
+When --scopes is provided, the specified scopes replace the provider's
+defaults entirely (use full scope URLs).
 By default, the browser opens automatically and the command waits for
 completion. Use --no-browser to print the URL instead (useful for headless
 or SSH sessions).

package/src/cli/commands/oauth/providers.ts

@@ -13,7 +13,10 @@ import {
   registerProvider,
   updateProvider,
 } from "../../../oauth/oauth-store.js";
-import { serializeProvider } from "../../../oauth/provider-serializer.js";
+import {
+  type SerializedProvider,
+  serializeProvider,
+} from "../../../oauth/provider-serializer.js";
 import { isProviderVisible } from "../../../oauth/provider-visibility.js";
 import { SEEDED_PROVIDER_KEYS } from "../../../oauth/seed-providers.js";
 import { getCliLogger } from "../../logger.js";
@@ -23,6 +26,137 @@ const log = getCliLogger("cli");
 
 const LOOPBACK_CALLBACK_PATH = "/oauth/callback";
 
+// ---------------------------------------------------------------------------
+// Text formatting helpers (non-JSON output)
+// ---------------------------------------------------------------------------
+
+/**
+ * Format available scopes for text output.
+ * Returns a single-line string for URLs, or a multi-line bullet list for
+ * structured scope arrays.
+ */
+function formatAvailableScopes(
+  availableScopes: unknown,
+  indent: string = "    ",
+): string | null {
+  if (!availableScopes) return null;
+  if (typeof availableScopes === "string") return availableScopes;
+  if (Array.isArray(availableScopes)) {
+    return (
+      "\n" +
+      (availableScopes as Array<{ scope: string; description?: string }>)
+        .map(
+          (s) =>
+            `${indent}- ${s.scope}${s.description ? ` — ${s.description}` : ""}`,
+        )
+        .join("\n")
+    );
+  }
+  return null;
+}
+
+/** Render a single provider as a concise summary line for `list`. */
+function formatProviderSummary(p: SerializedProvider): string {
+  const name = p.displayName ?? p.providerKey;
+  const desc = p.description ? ` — ${p.description}` : "";
+  const managed = p.supportsManagedMode ? " [managed]" : "";
+  const scopes =
+    (p.defaultScopes as string[])?.length > 0
+      ? `  Scopes: ${(p.defaultScopes as string[]).join(", ")}`
+      : "";
+  return (
+    `${p.providerKey} (${name})${desc}${managed}` +
+    `${scopes ? "\n" + scopes : ""}` +
+    `\n  Run \`assistant oauth providers get ${p.providerKey}\` for full details.`
+  );
+}
+
+/** Format a JSON value as indented text for `get` detail output. */
+function formatJsonValue(value: unknown, indent: string = "    "): string {
+  const json = JSON.stringify(value, null, 2);
+  return json
+    .split("\n")
+    .map((line, i) => (i === 0 ? line : indent + line))
+    .join("\n");
+}
+
+/** Render a single provider as structured text for `get` with all fields. */
+function formatProviderDetail(p: SerializedProvider): string {
+  const lines: string[] = [];
+  const name = p.displayName ?? p.providerKey;
+  lines.push(`${p.providerKey} (${name})`);
+  if (p.description) lines.push(`  Description: ${p.description}`);
+  if (p.supportsManagedMode) lines.push(`  Managed mode: yes`);
+  if (p.managedServiceIsPaid) lines.push(`  Managed service is paid: yes`);
+  if (p.dashboardUrl) lines.push(`  Dashboard: ${p.dashboardUrl}`);
+  if (p.appType) lines.push(`  App type: ${p.appType}`);
+  lines.push(
+    `  Requires client secret: ${p.requiresClientSecret ? "yes" : "no"}`,
+  );
+  if (p.clientIdPlaceholder)
+    lines.push(`  Client ID format: ${p.clientIdPlaceholder}`);
+  lines.push(`  Auth URL: ${p.authUrl}`);
+  lines.push(`  Token URL: ${p.tokenUrl}`);
+  if (p.refreshUrl) lines.push(`  Refresh URL: ${p.refreshUrl}`);
+  if (p.tokenEndpointAuthMethod)
+    lines.push(`  Token auth method: ${p.tokenEndpointAuthMethod}`);
+  if (p.tokenExchangeBodyFormat && p.tokenExchangeBodyFormat !== "form")
+    lines.push(`  Token exchange body format: ${p.tokenExchangeBodyFormat}`);
+  if ((p.defaultScopes as string[])?.length > 0)
+    lines.push(`  Default scopes: ${(p.defaultScopes as string[]).join(", ")}`);
+  const avail = formatAvailableScopes(p.availableScopes);
+  if (avail) lines.push(`  Available scopes: ${avail}`);
+  if (p.scopeSeparator && p.scopeSeparator !== " ")
+    lines.push(`  Scope separator: "${p.scopeSeparator}"`);
+  if (p.extraParams)
+    lines.push(`  Authorize params: ${formatJsonValue(p.extraParams)}`);
+  if (p.redirectUri) lines.push(`  Redirect URI: ${p.redirectUri}`);
+  if (p.loopbackPort) lines.push(`  Loopback port: ${p.loopbackPort}`);
+  if (p.baseUrl) lines.push(`  Base URL: ${p.baseUrl}`);
+  if (p.userinfoUrl) lines.push(`  Userinfo URL: ${p.userinfoUrl}`);
+  if (p.pingUrl) lines.push(`  Ping URL: ${p.pingUrl}`);
+  if (p.pingMethod) lines.push(`  Ping method: ${p.pingMethod}`);
+  if (p.pingHeaders)
+    lines.push(`  Ping headers: ${formatJsonValue(p.pingHeaders)}`);
+  if (p.pingBody) lines.push(`  Ping body: ${formatJsonValue(p.pingBody)}`);
+  if (p.revokeUrl) lines.push(`  Revoke URL: ${p.revokeUrl}`);
+  if (p.revokeBodyTemplate)
+    lines.push(
+      `  Revoke body template: ${formatJsonValue(p.revokeBodyTemplate)}`,
+    );
+  if (p.injectionTemplates)
+    lines.push(
+      `  Injection templates: ${formatJsonValue(p.injectionTemplates)}`,
+    );
+  if (p.identityUrl) lines.push(`  Identity URL: ${p.identityUrl}`);
+  if (p.identityMethod) lines.push(`  Identity method: ${p.identityMethod}`);
+  if (p.identityHeaders)
+    lines.push(`  Identity headers: ${formatJsonValue(p.identityHeaders)}`);
+  if (p.identityBody)
+    lines.push(`  Identity body: ${formatJsonValue(p.identityBody)}`);
+  if (p.identityResponsePaths)
+    lines.push(
+      `  Identity response paths: ${(p.identityResponsePaths as string[]).join(", ")}`,
+    );
+  if (p.identityFormat) lines.push(`  Identity format: ${p.identityFormat}`);
+  if (p.identityOkField)
+    lines.push(`  Identity ok field: ${p.identityOkField}`);
+  if (p.setupNotes) {
+    if (Array.isArray(p.setupNotes)) {
+      lines.push(
+        `  Setup notes:\n${(p.setupNotes as string[]).map((n) => `    - ${n}`).join("\n")}`,
+      );
+    } else {
+      lines.push(`  Setup notes: ${formatJsonValue(p.setupNotes)}`);
+    }
+  }
+  if (p.featureFlag) lines.push(`  Feature flag: ${p.featureFlag}`);
+  if (p.logoUrl) lines.push(`  Logo: ${p.logoUrl}`);
+  lines.push(`  Created: ${p.createdAt}`);
+  lines.push(`  Updated: ${p.updatedAt}`);
+  return lines.join("\n");
+}
+
 /**
  * Resolve a logo URL from CLI flags, enforcing mutual exclusion between
  * --logo-url and --logo-simpleicons-slug. Returns:
@@ -171,11 +305,17 @@ Examples:
             rows = rows.filter((r) => r && r.supportsManagedMode);
           }
 
-          if (!shouldOutputJson(cmd)) {
-            log.info(`Found ${rows.length} provider(s)`);
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, rows);
+          } else {
+            const validRows = rows.filter(
+              (r): r is NonNullable<typeof r> => r != null,
+            );
+            const lines = validRows.map(formatProviderSummary);
+            process.stdout.write(
+              `${validRows.length} provider(s):\n\n${lines.join("\n\n")}\n`,
+            );
           }
-
-          writeOutput(cmd, rows);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           writeOutput(cmd, { ok: false, error: message });
@@ -199,7 +339,7 @@ Arguments:
                  Must match the key used during registration or seeding.
 
 Returns the full provider configuration including auth URL, token URL,
-default scopes, scope policy, and extra parameters. Exits with code 1
+default scopes, available scopes, and extra parameters. Exits with code 1
 if the provider key is not found.
 
 Examples:
@@ -228,7 +368,12 @@ Examples:
           return;
         }
 
-        writeOutput(cmd, parseProviderRow(row));
+        const parsed = parseProviderRow(row);
+        if (shouldOutputJson(cmd)) {
+          writeOutput(cmd, parsed);
+        } else if (parsed) {
+          process.stdout.write(formatProviderDetail(parsed) + "\n");
+        }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         writeOutput(cmd, { ok: false, error: message });
@@ -371,6 +516,10 @@ Examples:
       "--setup-notes <json>",
       'JSON array of setup instruction notes shown during guided setup (e.g. \'["Enable the Gmail API","Add test users"]\')',
     )
+    .option(
+      "--available-scopes <value>",
+      "Available scopes: either a JSON array of {scope, description?} objects or a URL to the provider scope docs",
+    )
     .addHelpText(
       "after",
       `
@@ -473,6 +622,7 @@ Examples:
           identityFormat?: string;
           identityOkField?: string;
           setupNotes?: string;
+          availableScopes?: string;
         },
         cmd: Command,
       ) => {
@@ -492,7 +642,11 @@ Examples:
             baseUrl: opts.baseUrl,
             userinfoUrl: opts.userinfoUrl,
             defaultScopes: opts.scopes ? opts.scopes.split(",") : [],
-            scopePolicy: {},
+            availableScopes: opts.availableScopes
+              ? opts.availableScopes.startsWith("http")
+                ? opts.availableScopes
+                : JSON.parse(opts.availableScopes)
+              : undefined,
             scopeSeparator: opts.scopeSeparator,
             tokenEndpointAuthMethod: opts.tokenAuthMethod,
             tokenExchangeBodyFormat: opts.tokenExchangeBodyFormat,
@@ -679,6 +833,10 @@ Examples:
       "--setup-notes <json>",
       'JSON array of setup instruction notes shown during guided setup (e.g. \'["Enable the Gmail API","Add test users"]\')',
     )
+    .option(
+      "--available-scopes <value>",
+      "Available scopes: either a JSON array of {scope, description?} objects or a URL to the provider scope docs",
+    )
     .addHelpText(
       "after",
       `
@@ -749,6 +907,7 @@ Examples:
           identityFormat?: string;
           identityOkField?: string;
           setupNotes?: string;
+          availableScopes?: string;
         },
         cmd: Command,
       ) => {
@@ -868,6 +1027,15 @@ Examples:
             params.identityOkField = opts.identityOkField;
           if (opts.setupNotes !== undefined)
             params.setupNotes = JSON.parse(opts.setupNotes);
+          if (opts.availableScopes !== undefined) {
+            if (opts.availableScopes === "") {
+              params.availableScopes = null;
+            } else {
+              params.availableScopes = opts.availableScopes.startsWith("http")
+                ? opts.availableScopes
+                : JSON.parse(opts.availableScopes);
+            }
+          }
 
           // Check if any fields were actually provided
           if (Object.keys(params).length === 0) {

package/src/cli/commands/oauth/status.ts

@@ -1,7 +1,6 @@
 import type { Command } from "commander";
 
 import { getProvider, listConnections } from "../../../oauth/oauth-store.js";
-import { getCliLogger } from "../../logger.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
 import {
   fetchActiveConnections,
@@ -9,7 +8,36 @@ import {
   requirePlatformClient,
 } from "./shared.js";
 
-const log = getCliLogger("cli");
+// ---------------------------------------------------------------------------
+// Text formatting helpers
+// ---------------------------------------------------------------------------
+
+interface ConnectionSummary {
+  id: string;
+  account: string | null;
+  grantedScopes: string[];
+  status: string;
+  expiresAt?: string | null;
+  hasRefreshToken?: boolean;
+}
+
+function formatConnection(c: ConnectionSummary, mode: string): string {
+  const lines: string[] = [];
+  lines.push(`  ${c.account ?? "(no account)"}`);
+  lines.push(`    Connection ID: ${c.id}`);
+  lines.push(`    Status: ${c.status}`);
+  if (c.grantedScopes.length > 0) {
+    lines.push(`    Granted scopes: ${c.grantedScopes.join(", ")}`);
+  } else {
+    lines.push(`    Granted scopes: (none)`);
+  }
+  if (mode === "byo") {
+    if (c.expiresAt) lines.push(`    Expires: ${c.expiresAt}`);
+    if (c.hasRefreshToken !== undefined)
+      lines.push(`    Refresh token: ${c.hasRefreshToken ? "yes" : "no"}`);
+  }
+  return lines.join("\n");
+}
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -95,25 +123,20 @@ Examples:
               return;
             }
 
-            // Human output
+            // Text output
             if (connections.length === 0) {
-              log.info(
-                `No active connections for ${provider}. Connect with 'assistant oauth connect ${provider}'.`,
+              process.stdout.write(
+                `No active connections for ${provider}.\nConnect with \`assistant oauth connect ${provider}\`.\n`,
               );
               return;
             }
 
-            log.info(`Provider: ${provider} (managed)`);
-            log.info(`${connections.length} active connection(s):`);
-            for (const c of connections) {
-              const scopes =
-                c.grantedScopes.length > 0
-                  ? `[${c.grantedScopes.join(", ")}]`
-                  : "[]";
-              log.info(
-                `  \u2022 ${c.id}  ${c.account ?? "(no account)"}  ${scopes}  ${c.status}`,
-              );
-            }
+            const blocks = connections.map((c) =>
+              formatConnection(c, "managed"),
+            );
+            process.stdout.write(
+              `${provider} (managed) — ${connections.length} active connection(s):\n\n${blocks.join("\n\n")}\n`,
+            );
           } else {
             // ---------------------------------------------------------------
             // BYO path
@@ -155,31 +178,18 @@ Examples:
               return;
             }
 
-            // Human output
+            // Text output
             if (connections.length === 0) {
-              log.info(
-                `No active connections for ${provider}. Connect with 'assistant oauth connect ${provider}'.`,
+              process.stdout.write(
+                `No active connections for ${provider}.\nConnect with \`assistant oauth connect ${provider}\`.\n`,
               );
               return;
             }
 
-            log.info(`Provider: ${provider} (byo)`);
-            log.info(`${connections.length} active connection(s):`);
-            for (const c of connections) {
-              const scopes =
-                c.grantedScopes.length > 0
-                  ? `[${c.grantedScopes.join(", ")}]`
-                  : "[]";
-              const expires = c.expiresAt
-                ? `expires ${c.expiresAt}`
-                : "no expiry";
-              const refresh = c.hasRefreshToken
-                ? "refresh: yes"
-                : "refresh: no";
-              log.info(
-                `  \u2022 ${c.id}  ${c.account ?? "(no account)"}  ${scopes}  ${expires}  ${refresh}`,
-              );
-            }
+            const blocks = connections.map((c) => formatConnection(c, "byo"));
+            process.stdout.write(
+              `${provider} (byo) — ${connections.length} active connection(s):\n\n${blocks.join("\n\n")}\n`,
+            );
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);

package/src/cli/commands/skills.ts

@@ -78,7 +78,8 @@ Examples:
         const config = getConfig();
         const resolved = resolveSkillStates(localCatalog, config);
         const bundled = resolved.filter(
-          (r) => r.summary.source === "bundled",
+          (r) =>
+            r.summary.source === "bundled" || r.summary.source === "plugin",
         );
         const installed = resolved.filter(
           (r) =>
@@ -365,9 +366,7 @@ Examples:
 
         // ── Display bundled/installed results ─────────────────────────
         if (bundledMatches.length > 0) {
-          log.info(
-            `Bundled & installed skills (${bundledMatches.length}):\n`,
-          );
+          log.info(`Bundled & installed skills (${bundledMatches.length}):\n`);
           for (const s of bundledMatches) {
             const emoji = s.emoji ? `${s.emoji} ` : "";
             const tag = s.source === "bundled" ? " [bundled]" : " [installed]";

package/src/cli/program.ts

@@ -5,7 +5,6 @@ import { Command } from "commander";
 import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getConfigReadOnly } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
-import { registerHooksCommand } from "../hooks/cli.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
 import { registerAttachmentCommand } from "./commands/attachment.js";
@@ -18,6 +17,7 @@ import { registerBashCommand } from "./commands/bash.js";
 import { registerBrowserCommand } from "./commands/browser.js";
 import { registerCacheCommand } from "./commands/cache.js";
 import { registerChannelVerificationSessionsCommand } from "./commands/channel-verification-sessions.js";
+import { registerClientsCommand } from "./commands/clients.js";
 import { registerCompletionsCommand } from "./commands/completions.js";
 import { registerConfigCommand } from "./commands/config.js";
 import { registerContactsCommand } from "./commands/contacts.js";
@@ -37,7 +37,6 @@ import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPlatformCommand } from "./commands/platform/index.js";
 import { registerRoutesCommand } from "./commands/routes.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
-import { registerShotgunCommand } from "./commands/shotgun.js";
 import { registerSkillsCommand } from "./commands/skills.js";
 import { registerSttCommand } from "./commands/stt.js";
 import { registerTaskCommand } from "./commands/task.js";
@@ -72,49 +71,46 @@ Examples:
   );
 
   registerDefaultAction(program);
+
+  registerAttachmentCommand(program);
+  registerAuditCommand(program);
+  registerAuthCommand(program);
+  registerAutonomyCommand(program);
+  registerAvatarCommand(program);
   registerBackupCommand(program);
   registerBashCommand(program);
   registerBrowserCommand(program);
   registerCacheCommand(program);
-  registerTaskCommand(program);
-  registerConversationsCommand(program);
+  registerChannelVerificationSessionsCommand(program);
+  registerClientsCommand(program);
+  registerCompletionsCommand(program);
   registerConfigCommand(program);
-  registerKeysCommand(program);
-  registerCredentialsCommand(program);
+  registerContactsCommand(program);
+  registerConversationsCommand(program);
   registerCredentialExecutionCommand(program);
-  registerTrustCommand(program);
-  registerMemoryCommand(program);
-  registerAuditCommand(program);
-  registerAuthCommand(program);
-  registerAttachmentCommand(program);
-  registerAvatarCommand(program);
-  registerHooksCommand(program);
-  registerMcpCommand(program);
+  registerCredentialsCommand(program);
   if (isEmailEnabled(getConfigReadOnly())) {
     registerDomainCommand(program);
     registerEmailCommand(program);
   }
-  registerContactsCommand(program);
-  registerChannelVerificationSessionsCommand(program);
-  registerAutonomyCommand(program);
-  registerCompletionsCommand(program);
+  registerImageGenerationCommand(program);
+  registerInferenceCommand(program);
+  registerKeysCommand(program);
+  registerMcpCommand(program);
+  registerMemoryCommand(program);
   registerNotificationsCommand(program);
-  registerPlatformCommand(program);
   registerOAuthCommand(program);
+  registerPlatformCommand(program);
   registerRoutesCommand(program);
-  registerSkillsCommand(program);
-  registerUsageCommand(program);
-  registerWatchersCommand(program);
-
-  registerImageGenerationCommand(program);
-  registerUiCommand(program);
-
-  registerShotgunCommand(program);
   registerSequenceCommand(program);
+  registerSkillsCommand(program);
   registerSttCommand(program);
+  registerTaskCommand(program);
+  registerTrustCommand(program);
   registerTtsCommand(program);
-
-  registerInferenceCommand(program);
+  registerUiCommand(program);
+  registerUsageCommand(program);
+  registerWatchersCommand(program);
 
   // Fail fast when no assistant workspace exists on disk. The workspace is
   // created by `vellum hatch` and must be present for any command to work.

package/src/config/__tests__/backup-schema.test.ts

@@ -12,12 +12,17 @@ describe("BackupConfigSchema", () => {
     expect(parsed).toEqual({
       enabled: false,
       intervalHours: 6,
-      retention: 7,
+      retention: 3,
       offsite: { enabled: true, destinations: null },
       localDirectory: null,
     });
   });
 
+  test("default retention is 3 (ATL-193 — snapshots are full copies, not incremental)", () => {
+    const parsed = BackupConfigSchema.parse({});
+    expect(parsed.retention).toBe(3);
+  });
+
   test("rejects intervalHours: 0 (must be >= 1)", () => {
     const result = BackupConfigSchema.safeParse({ intervalHours: 0 });
     expect(result.success).toBe(false);
@@ -105,7 +110,7 @@ describe("BackupConfigSchema", () => {
     expect(parsed).toEqual({
       enabled: true,
       intervalHours: 6,
-      retention: 7,
+      retention: 3,
       offsite: { enabled: true, destinations: null },
       localDirectory: null,
     });

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -260,7 +260,7 @@ app_refresh(app_id)
 - Preact for UI (not React) - `import { render } from 'preact'`
 - TypeScript encouraged for all `.tsx`/`.ts` files
 - No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
-- Design for 400-600px width with graceful resizing
+- Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
 - The WebView blocks all navigation - links and form `action` attributes won't work
 <!-- feature:app-builder-multifile:end -->
 
@@ -275,7 +275,7 @@ Write a complete, self-contained HTML document.
 - Single HTML string - no external files, CDNs, or imports
 - All CSS in `<style>` in `<head>`, all JavaScript in `<script>` before `</body>`
 - No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
-- Design for 400-600px width with graceful resizing
+- Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
 - The WebView blocks all navigation - links and form `action` attributes won't work
 
 <!-- feature:app-builder-multifile:alt:end -->

package/src/config/bundled-skills/app-builder/references/WIDGETS.md

@@ -37,16 +37,16 @@ A CSS/JS widget library is auto-injected alongside the design system. Use these
 
 ## Content & landing page components
 
-| Widget                                           | Purpose                                             |
-| ------------------------------------------------ | --------------------------------------------------- |
-| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word |
-| `.v-section-header` / `.v-section-label`         | Section intro with label                            |
-| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                    |
-| `.v-pullquote`                                   | Blockquote with gradient accent border              |
-| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)             |
-| `.v-page`                                        | Centered container (max-width 600px)                |
-| `.v-gradient-text`                               | Accent-colored gradient text                        |
-| `.v-animate-in`                                  | Staggered fade-in for children                      |
+| Widget                                           | Purpose                                                |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word    |
+| `.v-section-header` / `.v-section-label`         | Section intro with label                               |
+| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                       |
+| `.v-pullquote`                                   | Blockquote with gradient accent border                 |
+| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)                |
+| `.v-page`                                        | Centered flex-column container (fills available width) |
+| `.v-gradient-text`                               | Accent-colored gradient text                           |
+| `.v-animate-in`                                  | Staggered fade-in for children                         |
 
 ## Widget JavaScript utilities