@openparachute/hub 0.6.4-rc.2 → 0.6.4-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.4-rc.2",
+  "version": "0.6.4-rc.4",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-home-ui.test.ts

@@ -175,7 +175,7 @@ describe("renderAccountHome", () => {
     expect(html).not.toContain('data-testid="mcp-connect"');
   });
 
-  test("get-started card — links to the two onboarding prompts, placed before the vault card", () => {
+  test("get-started card — links to the two onboarding prompts, placed AFTER the vault card", () => {
     const html = renderAccountHome({
       username: "alice",
       assignedVaults: ["alice"],
@@ -195,8 +195,10 @@ describe("renderAccountHome", () => {
     expect(html).toContain('data-testid="starter-surface-build"');
     // External links open safely.
     expect(html).toContain('rel="noopener"');
-    // Placed prominently — before the vault card in document order.
-    expect(html.indexOf('data-testid="get-started-card"')).toBeLessThan(
+    // Connect-before-prompts: the prompts are only useful once connected, so
+    // they now sit AFTER the vault card in document order (and after the
+    // onboarding checklist, which leads the page).
+    expect(html.indexOf('data-testid="get-started-card"')).toBeGreaterThan(
       html.indexOf('data-testid="vault-card"'),
     );
   });
@@ -529,4 +531,122 @@ describe("renderAccountHome", () => {
     // Error render must NOT also show a token.
     expect(html).not.toContain('data-testid="minted-token-banner"');
   });
+
+  // --- first-run onboarding checklist --------------------------------------
+
+  test("onboarding checklist — renders 3 steps with the correct /mcp endpoint (not connected)", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: false,
+    });
+    expect(html).toContain('data-testid="onboarding-checklist"');
+    expect(html).toContain('data-connected="false"');
+    // All three numbered steps render.
+    expect(html).toContain('data-testid="onboarding-step-1"');
+    expect(html).toContain('data-testid="onboarding-step-2"');
+    expect(html).toContain('data-testid="onboarding-step-3"');
+    expect(html).toContain("Your account is ready");
+    expect(html).toContain("Connect your AI");
+    expect(html).toContain("Set up your vault");
+    // Step ② shows the canonical /vault/<name>/mcp endpoint inline — the /mcp
+    // suffix is load-bearing (only it returns the WWW-Authenticate header).
+    expect(html).toContain(`${HUB_ORIGIN}/vault/alice/mcp`);
+    expect(html).toMatch(/data-testid="onboarding-mcp-endpoint">[^<]*\/vault\/alice\/mcp</);
+    // Both connect methods are inline in step ②.
+    expect(html).toContain('data-testid="onboarding-mcp-add-command"');
+    expect(html).toContain("Add custom connector");
+    expect(html).toContain("claude mcp add");
+    // Step ③ links the vault-setup starter prompt.
+    expect(html).toContain('data-testid="onboarding-vault-setup-link"');
+    expect(html).toContain("https://parachute.computer/onboarding/vault-setup/");
+  });
+
+  test("onboarding checklist — condenses to 'you're connected' when a grant exists", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: true,
+    });
+    // Still the same section, but in its condensed done-state.
+    expect(html).toContain('data-testid="onboarding-checklist"');
+    expect(html).toContain('data-connected="true"');
+    expect(html).toContain('data-testid="onboarding-done-line"');
+    expect(html).toContain("You're connected");
+    // The full 3-step list is gone (no nagging) — but the vault card below
+    // remains the working surface.
+    expect(html).not.toContain('data-testid="onboarding-step-2"');
+    expect(html).toContain('data-testid="vault-card"');
+  });
+
+  test("onboarding checklist — leads the page: BEFORE the vault card and the starter prompts", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: false,
+    });
+    const checklistIdx = html.indexOf('data-testid="onboarding-checklist"');
+    const vaultIdx = html.indexOf('data-testid="vault-card"');
+    const promptsIdx = html.indexOf('data-testid="get-started-card"');
+    // Net first-run order: checklist (connect) → vault details → prompts.
+    expect(checklistIdx).toBeGreaterThanOrEqual(0);
+    expect(checklistIdx).toBeLessThan(vaultIdx);
+    expect(vaultIdx).toBeLessThan(promptsIdx);
+  });
+
+  test("onboarding checklist — absent on the admin and no-vault branches", () => {
+    const admin = renderAccountHome({
+      username: "admin",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: true,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(admin).not.toContain('data-testid="onboarding-checklist"');
+
+    const noVault = renderAccountHome({
+      username: "ghost",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(noVault).not.toContain('data-testid="onboarding-checklist"');
+  });
+
+  test("onboarding checklist — multi-vault uses the first vault for the connect step", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["personal", "family"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      connectedVault: false,
+    });
+    // The checklist's connect step references the first/primary vault; the
+    // per-vault tiles below still list every vault.
+    expect(html).toMatch(/data-testid="onboarding-mcp-endpoint">[^<]*\/vault\/personal\/mcp</);
+    expect(html).toContain(`${HUB_ORIGIN}/vault/family/mcp`); // still present in the vault tiles
+  });
 });

package/src/__tests__/grants.test.ts

@@ -11,6 +11,7 @@ import {
   listGrantsForUser,
   recordGrant,
   revokeGrant,
+  userHasVaultGrant,
 } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { createUser } from "../users.ts";
@@ -177,7 +178,13 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
         redirectUris: ["https://app.example/cb"],
         clientName: "claude-code",
       });
-      recordGrant(h.db, h.userId, reg1.client.clientId, ["a", "b"], new Date("2026-04-10T00:00:00Z"));
+      recordGrant(
+        h.db,
+        h.userId,
+        reg1.client.clientId,
+        ["a", "b"],
+        new Date("2026-04-10T00:00:00Z"),
+      );
       // Second DCR: same client_name="claude-code", fresh client_id, no grant yet
       const reg2 = registerClient(h.db, {
         redirectUris: ["https://app.example/cb"],
@@ -249,8 +256,20 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
         clientName: "claude-code",
       });
       recordGrant(h.db, h.userId, reg1.client.clientId, ["a"], new Date("2026-04-01T00:00:00Z"));
-      recordGrant(h.db, h.userId, reg3.client.clientId, ["a", "c"], new Date("2026-04-15T00:00:00Z"));
-      recordGrant(h.db, h.userId, reg2.client.clientId, ["a", "b"], new Date("2026-04-10T00:00:00Z"));
+      recordGrant(
+        h.db,
+        h.userId,
+        reg3.client.clientId,
+        ["a", "c"],
+        new Date("2026-04-15T00:00:00Z"),
+      );
+      recordGrant(
+        h.db,
+        h.userId,
+        reg2.client.clientId,
+        ["a", "b"],
+        new Date("2026-04-10T00:00:00Z"),
+      );
       const grant = findGrantByClientName(h.db, h.userId, "claude-code");
       // Most recent = reg3's grant (2026-04-15)
       expect(grant?.clientId).toBe(reg3.client.clientId);
@@ -267,9 +286,19 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
         redirectUris: ["https://app.example/cb"],
         clientName: "claude-code",
       });
-      recordGrant(h.db, h.userId, reg.client.clientId, ["vault:default:read", "vault:default:write"]);
-      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read"])).toBe(true);
-      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read", "vault:default:write"])).toBe(true);
+      recordGrant(h.db, h.userId, reg.client.clientId, [
+        "vault:default:read",
+        "vault:default:write",
+      ]);
+      expect(
+        isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read"]),
+      ).toBe(true);
+      expect(
+        isCoveredByGrantForClientName(h.db, h.userId, "claude-code", [
+          "vault:default:read",
+          "vault:default:write",
+        ]),
+      ).toBe(true);
     } finally {
       h.cleanup();
     }
@@ -284,8 +313,15 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
       });
       recordGrant(h.db, h.userId, reg.client.clientId, ["vault:default:read"]);
       // Asking for write — not previously granted
-      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:write"])).toBe(false);
-      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read", "vault:default:write"])).toBe(false);
+      expect(
+        isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:write"]),
+      ).toBe(false);
+      expect(
+        isCoveredByGrantForClientName(h.db, h.userId, "claude-code", [
+          "vault:default:read",
+          "vault:default:write",
+        ]),
+      ).toBe(false);
     } finally {
       h.cleanup();
     }
@@ -304,4 +340,58 @@ describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () =
       h.cleanup();
     }
   });
+
+  // --- userHasVaultGrant (onboarding "has connected an AI?" signal) --------
+
+  test("userHasVaultGrant: false when the user has no grants at all", async () => {
+    const h = await harness();
+    try {
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("userHasVaultGrant: true when a grant's scopes touch the vault", async () => {
+    const h = await harness();
+    try {
+      recordGrant(h.db, h.userId, h.clientId, ["vault:default:read", "vault:default:write"]);
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("userHasVaultGrant: false when the grant touches a DIFFERENT vault", async () => {
+    const h = await harness();
+    try {
+      recordGrant(h.db, h.userId, h.clientId, ["vault:work:read"]);
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(false);
+      expect(userHasVaultGrant(h.db, h.userId, "work")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("userHasVaultGrant: non-vault scopes don't count as a connection", async () => {
+    const h = await harness();
+    try {
+      recordGrant(h.db, h.userId, h.clientId, ["parachute:host:auth", "vault:read"]);
+      // `vault:read` (no name segment) is a generic scope, not vault:<name>:.
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("userHasVaultGrant: prefix isn't substring-fooled (vault:default-2 ≠ default)", async () => {
+    const h = await harness();
+    try {
+      recordGrant(h.db, h.userId, h.clientId, ["vault:default-2:read"]);
+      expect(userHasVaultGrant(h.db, h.userId, "default")).toBe(false);
+      expect(userHasVaultGrant(h.db, h.userId, "default-2")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
 });

package/src/__tests__/users.test.ts

@@ -304,6 +304,45 @@ describe("deleteUser", () => {
       cleanup();
     }
   });
+
+  test("deletes a user holding an auth_codes row (hub#559 — OAuth-authorize FK regression)", async () => {
+    // A user who completed an OAuth authorize has an `auth_codes` row whose
+    // NOT-NULL, non-cascading FK to users(id) outlives its 60s TTL. Before the
+    // fix, that pinned the FK and `DELETE FROM users` threw
+    // SQLITE_CONSTRAINT_FOREIGNKEY → a 500 on the admin "delete user" action.
+    const { db, cleanup } = makeDb();
+    try {
+      const u = await createUser(db, "ag", "ag-strong-passphrase");
+      // auth_codes.client_id FKs to clients — seed a minimal client first.
+      db.prepare(
+        "INSERT INTO clients (client_id, redirect_uris, scopes, registered_at) VALUES (?, ?, ?, ?)",
+      ).run("client-x", "https://app.example/cb", "vault:default:read", "2026-06-04T00:00:00.000Z");
+      db.prepare(
+        `INSERT INTO auth_codes
+           (code, client_id, user_id, redirect_uri, scopes, code_challenge, code_challenge_method, expires_at, used_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      ).run(
+        "dead-code",
+        "client-x",
+        u.id,
+        "https://app.example/cb",
+        "vault:default:read",
+        "challenge",
+        "S256",
+        "2026-06-04T00:00:00.000Z", // long-expired
+        "2026-06-04T00:00:00.000Z", // already used
+        "2026-06-04T00:00:00.000Z",
+      );
+      expect(deleteUser(db, u.id)).toBe(true);
+      expect(getUserById(db, u.id)).toBeNull();
+      // The dead auth_code is gone too (hard-deleted with the user).
+      expect(db.query("SELECT COUNT(*) c FROM auth_codes WHERE user_id = ?").get(u.id)).toEqual({
+        c: 0,
+      });
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 describe("validateUsername", () => {

package/src/account-home-ui.ts

@@ -151,6 +151,17 @@ export interface RenderAccountHomeOpts {
    * on the normal GET render.
    */
   mintError?: string;
+  /**
+   * Whether this user has already connected an AI to (any of) their assigned
+   * vault(s) — true when a `grants` row touches one of their vaults (see
+   * `userHasVaultGrant`). Drives the first-run onboarding checklist: when
+   * `false`, the checklist leads with the hero "Connect your AI" step (inline
+   * endpoint + both methods); when `true`, the checklist condenses to a quiet
+   * "you're connected" line so it stops nagging returning users. The full vault
+   * card below remains the working surface either way. Omitted (defaults to
+   * `false`) on the admin / no-vault branches, where no checklist is shown.
+   */
+  connectedVault?: boolean;
 }
 
 /**
@@ -192,6 +203,22 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
   const hasNoVault = !isFirstAdmin && assignedVaults.length === 0;
   const startedCard = hasNoVault ? "" : renderGetStartedCard();
 
+  // First-run onboarding checklist — the lead surface for a friend with at
+  // least one assigned vault. Walks them through the obvious path: account
+  // ready → connect your AI (the hero step, inline endpoint + both methods) →
+  // set up your vault. Once connected (a grant touches one of their vaults) it
+  // condenses to a quiet "you're connected" line so it stops nagging. Shown
+  // only on the assigned-vault branch — the admin + no-vault branches have no
+  // single "your vault" to connect, so the checklist would be misleading there.
+  const checklist =
+    assignedVaults.length > 0
+      ? renderOnboardingChecklist({
+          primaryVault: assignedVaults[0] as string,
+          trimmedOrigin,
+          connected: opts.connectedVault ?? false,
+        })
+      : "";
+
   const vaultCard = renderVaultCard({
     assignedVaults,
     trimmedOrigin,
@@ -216,13 +243,120 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
       </div>
       ${mintedBanner}
       ${mintErrorBanner}
-      ${startedCard}
+      ${checklist}
       ${vaultCard}
+      ${startedCard}
       ${accountCard}
     </div>${COPY_SCRIPT}`;
   return baseDocument(`${username} — Parachute`, body);
 }
 
+interface OnboardingChecklistOpts {
+  /**
+   * The vault the checklist's "Connect your AI" step shows the endpoint for.
+   * For the common single-vault case this is their only vault; for the rare
+   * multi-vault case it's the first/primary one (the per-vault tiles below
+   * still list every vault). Already validated/escaped at render time.
+   */
+  primaryVault: string;
+  trimmedOrigin: string;
+  /** Whether they've already connected an AI (a grant touches a vault). */
+  connected: boolean;
+}
+
+/**
+ * The first-run "Get set up" checklist — the lead surface on `/account/` for a
+ * friend with an assigned vault. Three numbered steps give a non-technical
+ * person an obvious path:
+ *
+ *   ① Your account is ready  — always done (they're signed in, password set).
+ *   ② Connect your AI        — the hero. Inline endpoint (`/vault/<name>/mcp`)
+ *                              with a copy button + the two short connect
+ *                              methods (Claude.ai connector, Claude Code
+ *                              `claude mcp add`). Marked done when `connected`.
+ *   ③ Set up your vault      — links the vault-setup starter prompt.
+ *
+ * When `connected` is true the whole thing condenses to a quiet "✓ You're
+ * connected" line so it doesn't nag returning users — the full vault card below
+ * stays the working surface either way.
+ *
+ * Server-rendered, no-JS-required: the copy button is progressive enhancement
+ * (the endpoint stays selectable text without it), matching the rest of the page.
+ */
+function renderOnboardingChecklist(opts: OnboardingChecklistOpts): string {
+  const { primaryVault, trimmedOrigin, connected } = opts;
+  const safeVault = escapeHtml(primaryVault);
+  const endpoint = accountMcpEndpoint(trimmedOrigin, primaryVault);
+  const addCmd = accountClaudeMcpAddCommand(trimmedOrigin, primaryVault);
+  const safeEndpoint = escapeHtml(endpoint);
+  const safeAddCmd = escapeHtml(addCmd);
+
+  // Condensed state — they've connected, so the checklist shrinks to a single
+  // reassuring line. The vault card below remains the place to actually work.
+  if (connected) {
+    return `
+    <section class="section onboarding onboarding-done" data-testid="onboarding-checklist"
+             data-connected="true">
+      <p class="onboarding-done-line" data-testid="onboarding-done-line">
+        <span class="onboarding-check" aria-hidden="true">✓</span>
+        You're connected — here's your vault.</p>
+    </section>`;
+  }
+
+  return `
+    <section class="section onboarding" data-testid="onboarding-checklist"
+             data-connected="false">
+      <h2>Get set up</h2>
+      <p class="onboarding-intro">Three quick steps to start using your vault with your AI.</p>
+      <ol class="onboarding-steps">
+        <li class="onboarding-step onboarding-step-done" data-testid="onboarding-step-1">
+          <span class="onboarding-num onboarding-num-done" aria-hidden="true">✓</span>
+          <div class="onboarding-step-body">
+            <p class="onboarding-step-title">Your account is ready</p>
+            <p class="onboarding-step-sub">You're signed in and your password is set. Nothing to
+               do here.</p>
+          </div>
+        </li>
+
+        <li class="onboarding-step onboarding-step-hero" data-testid="onboarding-step-2">
+          <span class="onboarding-num" aria-hidden="true">2</span>
+          <div class="onboarding-step-body">
+            <p class="onboarding-step-title">Connect your AI</p>
+            <p class="onboarding-step-sub">Point Claude (or another AI) at your vault using this
+               address — no token to copy, you'll sign in and approve the first time:</p>
+            <div class="copy-row">
+              <code data-testid="onboarding-mcp-endpoint">${safeEndpoint}</code>
+              <button type="button" class="btn btn-copy" data-copy="${safeEndpoint}"
+                      data-testid="copy-onboarding-endpoint">Copy</button>
+            </div>
+            <p class="onboarding-method"><strong>Claude.ai (web):</strong> open
+               Settings → Connectors → Add custom connector, and paste the address above.</p>
+            <p class="onboarding-method"><strong>Claude Code (terminal):</strong> run this command:</p>
+            <div class="copy-row">
+              <code data-testid="onboarding-mcp-add-command">${safeAddCmd}</code>
+              <button type="button" class="btn btn-copy" data-copy="${safeAddCmd}"
+                      data-testid="copy-onboarding-add-command">Copy</button>
+            </div>
+          </div>
+        </li>
+
+        <li class="onboarding-step" data-testid="onboarding-step-3">
+          <span class="onboarding-num" aria-hidden="true">3</span>
+          <div class="onboarding-step-body">
+            <p class="onboarding-step-title">Set up your vault</p>
+            <p class="onboarding-step-sub">Open a new Claude chat and paste the
+               <a href="https://parachute.computer/onboarding/vault-setup/" target="_blank"
+                  rel="noopener" data-testid="onboarding-vault-setup-link">vault-setup prompt</a> —
+               your AI interviews you and structures your vault around how you think.</p>
+          </div>
+        </li>
+      </ol>
+      <p class="onboarding-foot" data-testid="onboarding-foot">Your vault is
+         <code>${safeVault}</code>. Full connect details, Notes, backup, and access tokens are
+         just below.</p>
+    </section>`;
+}
+
 /**
  * The "Get started with your AI" card — the real first stop for a friend
  * landing on `/account/`. Mirrors the operator setup-wizard's
@@ -231,9 +365,9 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
  * live on parachute.computer rather than embedded here so they iterate
  * without a hub release; this card just links.
  *
- * Placed near the top of the page (after any banners, before the vault card)
- * because "what do I actually do with this?" is the friend's first question —
- * the connect details below answer "how", this answers "what next".
+ * Placed AFTER the connect/vault card (connect-before-prompts): the prompts are
+ * only useful once the vault is connected, so the page leads with the connect
+ * checklist + vault details, and these "what next" prompts sit below them.
  */
 function renderGetStartedCard(): string {
   return `
@@ -748,6 +882,87 @@ const STYLES = `
     .starter-grid { grid-template-columns: 1fr; }
   }
 
+  .onboarding-intro { color: ${PALETTE.fgMuted}; font-size: 0.95rem; margin: 0 0 0.4rem; }
+  .onboarding-steps {
+    list-style: none;
+    margin: 0.75rem 0 0.4rem;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.85rem;
+  }
+  .onboarding-step {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.7rem;
+  }
+  .onboarding-num {
+    flex: 0 0 auto;
+    width: 1.5rem;
+    height: 1.5rem;
+    border-radius: 999px;
+    background: ${PALETTE.accent};
+    color: ${PALETTE.cardBg};
+    font-size: 0.85rem;
+    font-weight: 600;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    margin-top: 0.1rem;
+  }
+  .onboarding-num-done {
+    background: ${PALETTE.successSoft};
+    color: ${PALETTE.success};
+    border: 1px solid ${PALETTE.success};
+  }
+  .onboarding-step-body { flex: 1 1 auto; min-width: 0; }
+  .onboarding-step-title {
+    font-weight: 600;
+    font-size: 0.95rem;
+    color: ${PALETTE.fg};
+    margin: 0 0 0.15rem;
+  }
+  .onboarding-step-sub {
+    font-size: 0.85rem;
+    color: ${PALETTE.fgMuted};
+    margin: 0 0 0.4rem;
+  }
+  .onboarding-step-done .onboarding-step-title { color: ${PALETTE.fgMuted}; font-weight: 500; }
+  .onboarding-method {
+    font-size: 0.85rem;
+    color: ${PALETTE.fgMuted};
+    margin: 0.5rem 0 0.3rem;
+  }
+  .onboarding-method strong { color: ${PALETTE.fg}; }
+  .onboarding-step .copy-row { margin: 0.35rem 0; }
+  .onboarding-foot {
+    font-size: 0.82rem;
+    color: ${PALETTE.fgMuted};
+    margin: 0.6rem 0 0;
+  }
+  .onboarding-done-line {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-size: 1rem;
+    font-weight: 500;
+    color: ${PALETTE.fg};
+    margin: 0;
+  }
+  .onboarding-check {
+    flex: 0 0 auto;
+    width: 1.4rem;
+    height: 1.4rem;
+    border-radius: 999px;
+    background: ${PALETTE.successSoft};
+    color: ${PALETTE.success};
+    border: 1px solid ${PALETTE.success};
+    font-size: 0.85rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
   .account-security {
     margin: 0.9rem 0 0;
     padding-top: 0.6rem;
@@ -1053,8 +1268,13 @@ const STYLES = `
     h1, h2 { color: #f0ece4; }
     .subtitle, .kv dt, .mcp-field-label, .mcp-connect-hint,
     .mcp-connect-intro, .mcp-method-sub, .mcp-method-note,
-    .vault-notes-cta-sub, .vault-usage { color: #a8a29a; }
-    .vault-name strong, .mcp-connect-label, .mcp-method-title { color: #f0ece4; }
+    .vault-notes-cta-sub, .vault-usage,
+    .onboarding-intro, .onboarding-step-sub, .onboarding-method,
+    .onboarding-foot { color: #a8a29a; }
+    .vault-name strong, .mcp-connect-label, .mcp-method-title,
+    .onboarding-step-title, .onboarding-method strong,
+    .onboarding-done-line { color: #f0ece4; }
+    .onboarding-step-done .onboarding-step-title { color: #a8a29a; }
     code { background: #1f1c18; color: #e8e4dc; }
     .copy-row code { background: transparent; }
     .section { border-top-color: #3a362f; }

package/src/account-vault-token.ts

@@ -69,6 +69,7 @@ import {
 } from "./account-home-ui.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import { userHasVaultGrant } from "./grants.ts";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
 import { vaultTokenMintRateLimiter } from "./rate-limit.ts";
@@ -189,6 +190,7 @@ export async function handleAccountVaultTokenPost(
         csrfToken: csrf.token,
         twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
         mintableVerbs: buildMintableVerbs(deps.db, user.id, user.assignedVaults),
+        connectedVault: user.assignedVaults.some((v) => userHasVaultGrant(deps.db, user.id, v)),
         ...extras,
       }),
       status,

package/src/api-account.ts

@@ -53,6 +53,7 @@ import { fetchVaultUsage, formatUsageStat } from "./account-usage.ts";
 import { POST_LOGIN_DEFAULT } from "./admin-handlers.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import { userHasVaultGrant } from "./grants.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findActiveSession } from "./sessions.ts";
@@ -553,6 +554,12 @@ export async function handleAccountHomeGet(req: Request, deps: AccountHomeDeps):
     );
   }
 
+  // "Has this user connected an AI to any of their vaults yet?" — drives the
+  // onboarding checklist's "Connect your AI" step (done/condensed when true).
+  // A grant row only lands after the user clicks through an OAuth consent for a
+  // client wired to one of their vaults.
+  const connectedVault = user.assignedVaults.some((v) => userHasVaultGrant(deps.db, user.id, v));
+
   return htmlResponse(
     renderAccountHome({
       username: user.username,
@@ -564,6 +571,7 @@ export async function handleAccountHomeGet(req: Request, deps: AccountHomeDeps):
       twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
       mintableVerbs,
       usageStats,
+      connectedVault,
     }),
     200,
     extra,

package/src/grants.ts

@@ -188,6 +188,31 @@ export function isCoveredByGrantForClientName(
   return true;
 }
 
+const VAULT_SCOPE_PREFIX_RE = /^vault:([^:]+):/;
+
+/**
+ * True when the user has approved at least one OAuth client whose granted
+ * scopes touch `vaultName` (any `vault:<name>:<verb>` scope). This is the
+ * "has this person actually connected an AI to this vault yet?" signal — the
+ * `/account/` onboarding checklist uses it to mark the "Connect your AI" step
+ * done (a grant row only lands once the user has clicked through the consent
+ * screen for a client wired to this vault).
+ *
+ * Mirrors the per-grant vault filter in `admin-grants.ts`; kept here so the
+ * detection lives next to the rest of the grants helpers and can be unit-tested
+ * without the admin route harness.
+ */
+export function userHasVaultGrant(db: Database, userId: string, vaultName: string): boolean {
+  const grants = listGrantsForUser(db, userId);
+  for (const g of grants) {
+    for (const s of g.scopes) {
+      const m = s.match(VAULT_SCOPE_PREFIX_RE);
+      if (m && m[1] === vaultName) return true;
+    }
+  }
+  return false;
+}
+
 /** All grants for a user, ordered most-recent first. Used by `parachute auth list-grants`. */
 export function listGrantsForUser(db: Database, userId: string): Grant[] {
   const rows = db

package/src/users.ts

@@ -601,8 +601,10 @@ export async function resetUserPassword(
  *     parent users row. The audit trail survives via the `subject`
  *     column we backfill from the username plus the existing
  *     `created_at`, `scopes`, `client_id`, `revoked_at` fields.
- *   - `sessions.user_id` and `grants.user_id` are NOT NULL with a
- *     non-cascading FK. Both are deleted before the users row drops.
+ *   - `sessions.user_id`, `grants.user_id`, and `auth_codes.user_id` are
+ *     NOT NULL with a non-cascading (RESTRICT) FK. All three are deleted
+ *     before the users row drops — auth_codes are ephemeral OAuth codes
+ *     (60s TTL, no audit value), so a hard-delete is correct (hub#559).
  *   - `user_vaults.user_id` has `ON DELETE CASCADE` (migration v10), so
  *     vault assignments are dropped automatically when the parent row
  *     goes. No explicit cleanup needed.
@@ -630,10 +632,16 @@ export function deleteUser(db: Database, userId: string): boolean {
     db.prepare(
       "UPDATE tokens SET subject = COALESCE(subject, ?), user_id = NULL WHERE user_id = ?",
     ).run(row.username, userId);
-    // 2. Drop sessions + grants. Both have non-cascading FKs on user_id;
-    //    leaving rows behind would RESTRICT the users delete below.
+    // 2. Drop sessions + grants + auth_codes. All have NOT-NULL, non-cascading
+    //    (RESTRICT) FKs on user_id; leaving rows behind blocks the users delete
+    //    below with SQLITE_CONSTRAINT_FOREIGNKEY. auth_codes are short-lived
+    //    (60s TTL) OAuth authorization codes with no audit value — hard-delete,
+    //    same as sessions. (Omitting this 500'd a real delete of a user who had
+    //    completed an OAuth authorize: the code row outlived its TTL but still
+    //    pinned the FK. hub#559.)
     db.prepare("DELETE FROM sessions WHERE user_id = ?").run(userId);
     db.prepare("DELETE FROM grants WHERE user_id = ?").run(userId);
+    db.prepare("DELETE FROM auth_codes WHERE user_id = ?").run(userId);
     // 3. Drop the user row itself.
     db.prepare("DELETE FROM users WHERE id = ?").run(userId);
   })();