@harborclient/team-hub 0.4.2 → 0.4.4

package/dist/cli.js

@@ -21,9 +21,22 @@ import { Command as Command2 } from "commander";
 
 // src/config/serverConfig.ts
 import { existsSync, readFileSync } from "fs";
-import path from "path";
+import path2 from "path";
 import { parse as parseYaml } from "yaml";
 
+// src/config/docsConfig.ts
+import path from "path";
+var DEFAULT_DOCS_SEARCH_INDEX_PATH = "/app/data/docsSearchIndex.json";
+function resolveDocsSearchIndexPath(searchIndexPath) {
+  return path.isAbsolute(searchIndexPath) ? searchIndexPath : path.resolve(process.cwd(), searchIndexPath);
+}
+function normalizeDocsConfig(section) {
+  const trimmed = section.searchIndexPath?.trim();
+  return {
+    searchIndexPath: trimmed && trimmed.length > 0 ? trimmed : DEFAULT_DOCS_SEARCH_INDEX_PATH
+  };
+}
+
 // src/config/llmConfig.ts
 function headerRowsFromSingleKeyObject(record) {
   const rows = [];
@@ -176,6 +189,9 @@ var pluginsSectionSchema = z.object({
   catalogs: z.array(z.string().trim().url()).optional(),
   trusted: z.array(z.string().trim().url()).optional()
 });
+var docsSectionSchema = z.object({
+  searchIndexPath: z.string().trim().min(1).optional()
+});
 var logLevelSchema = z.enum(["debug", "info", "warn", "error"]);
 var loggingSectionSchema = z.object({
   level: logLevelSchema.optional(),
@@ -188,6 +204,7 @@ var serverConfigDocumentSchema = z.object({
   redis: redisSectionSchema,
   llm: llmSectionSchema.optional(),
   plugins: pluginsSectionSchema.optional(),
+  docs: docsSectionSchema.optional(),
   logging: loggingSectionSchema.optional()
 });
 
@@ -205,7 +222,7 @@ var ConfigError = class extends Error {
   }
 };
 function resolveConfigPath(configPath) {
-  return path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
+  return path2.isAbsolute(configPath) ? configPath : path2.resolve(process.cwd(), configPath);
 }
 function assertDocumentShape(document) {
   if (document === null || typeof document !== "object" || Array.isArray(document)) {
@@ -288,6 +305,14 @@ function parseServerConfig(document) {
     }
     plugins = normalizePluginsConfig(parsedPluginsSection.data);
   }
+  let docs = null;
+  if (root.docs !== void 0) {
+    const parsedDocsSection = docsSectionSchema.safeParse(root.docs);
+    if (!parsedDocsSection.success) {
+      throw new ConfigError(formatZodError(parsedDocsSection.error));
+    }
+    docs = normalizeDocsConfig(parsedDocsSection.data);
+  }
   let logging = DEFAULT_LOGGING_CONFIG;
   if (root.logging !== void 0) {
     const parsedLoggingSection = loggingSectionSchema.safeParse(root.logging);
@@ -303,6 +328,7 @@ function parseServerConfig(document) {
     redis: parsedRedisSection.data,
     llm,
     plugins,
+    docs,
     logging
   };
 }
@@ -340,7 +366,7 @@ function mergeGlobalOptions(command, options) {
 }
 
 // src/db/firestore/FirestoreDatabase.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { Firestore } from "@google-cloud/firestore";
 
 // src/db/attribution.ts
@@ -353,9 +379,26 @@ async function resolveActingUserName(findUserById, actingUserId) {
 import { randomUUID } from "crypto";
 var BOOTSTRAP_USER_NAME = "bootstrap";
 
+// src/db/invitationErrors.ts
+var InvitationUnavailableError = class extends Error {
+  /**
+   * Specific failure reason used to choose a safe HTTP status code.
+   */
+  reason;
+  /**
+   * @param reason - Why the invitation cannot be used.
+   */
+  constructor(reason) {
+    super("Invalid or expired invitation.");
+    this.name = "InvitationUnavailableError";
+    this.reason = reason;
+  }
+};
+
 // src/db/firestore/const.ts
 var USERS_COLLECTION = "users";
 var API_TOKENS_COLLECTION = "apiTokens";
+var INVITATIONS_COLLECTION = "invitations";
 var COLLECTIONS_COLLECTION = "collections";
 var ENVIRONMENTS_COLLECTION = "environments";
 var SNIPPETS_COLLECTION = "snippets";
@@ -401,11 +444,25 @@ var firestoreConfigSchema = z2.object({
 
 // src/db/firestore/utils.ts
 function parseAuditEntityType(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
+  if (value === "user" || value === "api_token" || value === "invitation" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
 }
+function mapFirestoreInvitation(id, data) {
+  return {
+    id,
+    userId: data.userId,
+    codeHash: data.codeHash,
+    codePrefix: data.codePrefix,
+    expiresAt: data.expiresAt,
+    redeemedAt: data.redeemedAt,
+    revokedAt: data.revokedAt,
+    createdAt: data.createdAt,
+    createdByUserId: data.createdByUserId ?? null,
+    updatedByUserId: data.updatedByUserId ?? null
+  };
+}
 function mapFirestoreApiToken(id, data) {
   if (!data.userId) {
     throw new Error(`API token ${id} is missing a userId`);
@@ -618,6 +675,39 @@ function parseRunResultPayload(payload) {
   };
 }
 
+// src/server/auth/apiTokens.ts
+import { createHash, randomBytes, randomUUID as randomUUID2 } from "crypto";
+var TOKEN_PREFIX = "hbk_";
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+function generateApiToken(userId, name) {
+  const secretSuffix = randomBytes(32).toString("base64url");
+  const secret = `${TOKEN_PREFIX}${secretSuffix}`;
+  const tokenPrefix = `${TOKEN_PREFIX}${secretSuffix.slice(0, 8)}`;
+  const createdAt = /* @__PURE__ */ new Date();
+  const record = {
+    id: randomUUID2(),
+    userId,
+    name,
+    tokenHash: hashToken(secret),
+    tokenPrefix,
+    createdAt,
+    lastUsedAt: null,
+    revokedAt: null,
+    createdByUserId: null,
+    updatedByUserId: null
+  };
+  return { record, secret };
+}
+function extractBearer(headerValue) {
+  if (!headerValue) {
+    return null;
+  }
+  const match = /^Bearer\s+(\S+)$/i.exec(headerValue.trim());
+  return match?.[1] ?? null;
+}
+
 // src/db/trimRequiredName.ts
 function trimRequiredName(name, label) {
   const trimmed = name.trim();
@@ -816,7 +906,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const attributionUserId = trimmedName === SYSTEM_USER_NAME ? id : actingUserId;
     const data = {
@@ -1120,6 +1210,205 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async touchApiTokenLastUsed(id, when) {
     await this.requireClient().collection(API_TOKENS_COLLECTION).doc(id).update({ lastUsedAt: when });
   }
+  /**
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const client = this.requireClient();
+    const userRef = client.collection(USERS_COLLECTION).doc(userId);
+    const invitationRef = client.collection(INVITATIONS_COLLECTION).doc(invitation.id);
+    const userData = {
+      name: trimmedName,
+      role: input.role,
+      collectionAccess: input.collectionAccess,
+      environmentAccess: input.environmentAccess,
+      snippetAccess: input.snippetAccess,
+      llmAccess: input.llmAccess ?? false,
+      llmModels: input.llmModels ?? [],
+      llmMonthlyTokenLimit: input.llmMonthlyTokenLimit ?? null,
+      createdAt: now,
+      updatedAt: now,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    const invitationData = {
+      userId: invitation.userId,
+      codeHash: invitation.codeHash,
+      codePrefix: invitation.codePrefix,
+      expiresAt: invitation.expiresAt,
+      redeemedAt: invitation.redeemedAt,
+      revokedAt: invitation.revokedAt,
+      createdAt: invitation.createdAt,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    await client.runTransaction(async (transaction) => {
+      transaction.set(userRef, userData);
+      transaction.set(invitationRef, invitationData);
+    });
+    await this.recordAuditEntry(actingUserId, "create", "user", userId);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return {
+      user: mapFirestoreUser(userId, userData),
+      invitation
+    };
+  }
+  /**
+   * Persists a new onboarding invitation for an existing user account.
+   *
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+    const data = {
+      userId: invitation.userId,
+      codeHash: invitation.codeHash,
+      codePrefix: invitation.codePrefix,
+      expiresAt: invitation.expiresAt,
+      redeemedAt: invitation.redeemedAt,
+      revokedAt: invitation.revokedAt,
+      createdAt: invitation.createdAt,
+      createdByUserId: actingUserId,
+      updatedByUserId: actingUserId
+    };
+    await this.requireClient().collection(INVITATIONS_COLLECTION).doc(invitation.id).set(data);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).doc(id).get();
+    if (!snapshot.exists) {
+      return null;
+    }
+    return mapFirestoreInvitation(snapshot.id, snapshot.data());
+  }
+  /**
+   * Finds an invitation by the sha256 hash of its secret.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   */
+  async findInvitationByCodeHash(codeHash) {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).where("codeHash", "==", codeHash).limit(1).get();
+    const doc = snapshot.docs[0];
+    if (!doc) {
+      return null;
+    }
+    return mapFirestoreInvitation(doc.id, doc.data());
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const snapshot = await this.requireClient().collection(INVITATIONS_COLLECTION).orderBy("createdAt", "desc").get();
+    return snapshot.docs.map(
+      (doc) => mapFirestoreInvitation(doc.id, doc.data())
+    );
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const docRef = this.requireClient().collection(INVITATIONS_COLLECTION).doc(id);
+    const snapshot = await docRef.get();
+    if (!snapshot.exists) {
+      return false;
+    }
+    const data = snapshot.data();
+    const now = /* @__PURE__ */ new Date();
+    if (data.redeemedAt !== null || data.revokedAt !== null || data.expiresAt.getTime() <= now.getTime()) {
+      return false;
+    }
+    await docRef.update({ revokedAt: now, updatedByUserId: actingUserId });
+    await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    return true;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const client = this.requireClient();
+    const invitationQuery = client.collection(INVITATIONS_COLLECTION).where("codeHash", "==", codeHash).limit(1);
+    let user;
+    let invitation;
+    let token;
+    let secret;
+    await client.runTransaction(async (transaction) => {
+      const invitationSnapshot = await transaction.get(invitationQuery);
+      const invitationDoc = invitationSnapshot.docs[0];
+      if (!invitationDoc) {
+        throw new InvitationUnavailableError("not_found");
+      }
+      const invitationData = invitationDoc.data();
+      if (invitationData.redeemedAt) {
+        throw new InvitationUnavailableError("redeemed");
+      }
+      if (invitationData.revokedAt) {
+        throw new InvitationUnavailableError("revoked");
+      }
+      if (invitationData.expiresAt.getTime() <= now.getTime()) {
+        throw new InvitationUnavailableError("expired");
+      }
+      transaction.update(invitationDoc.ref, {
+        redeemedAt: now,
+        updatedByUserId: actingUserId
+      });
+      const userRef = client.collection(USERS_COLLECTION).doc(invitationData.userId);
+      const userSnapshot = await transaction.get(userRef);
+      if (!userSnapshot.exists) {
+        throw new Error("User not found");
+      }
+      user = mapFirestoreUser(userSnapshot.id, userSnapshot.data());
+      invitation = mapFirestoreInvitation(invitationDoc.id, {
+        ...invitationData,
+        redeemedAt: now,
+        updatedByUserId: actingUserId
+      });
+      const generated = generateApiToken(user.id, tokenName);
+      token = generated.record;
+      secret = generated.secret;
+      const tokenRef = client.collection(API_TOKENS_COLLECTION).doc(token.id);
+      const tokenData = {
+        userId: token.userId,
+        name: token.name,
+        tokenHash: token.tokenHash,
+        tokenPrefix: token.tokenPrefix,
+        createdAt: token.createdAt,
+        lastUsedAt: token.lastUsedAt,
+        revokedAt: token.revokedAt,
+        createdByUserId: actingUserId,
+        updatedByUserId: actingUserId
+      };
+      transaction.set(tokenRef, tokenData);
+    });
+    await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+    await this.recordAuditEntry(actingUserId, "create", "api_token", token.id);
+    return { user, token, secret };
+  }
   /**
    * Lists all collections ordered by name.
    */
@@ -1137,7 +1426,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createCollection(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       name: trimmedName,
@@ -1269,7 +1558,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       name: trimmedName,
@@ -1386,7 +1675,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const existing = await this.listSnippets();
     const maxOrder = existing.reduce((max, snippet) => Math.max(max, snippet.sortOrder), -1);
@@ -1580,7 +1869,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
     }
     const existingRequests = await this.listRequests(input.collectionId);
     const maxOrder = existingRequests.filter((request) => request.folderId === folderId).reduce((max, request) => Math.max(max, request.sortOrder), -1);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const data = {
       collectionId: input.collectionId,
       folderId,
@@ -1650,7 +1939,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const existingFolders = await this.listFolders(collectionId);
     const maxOrder = existingFolders.reduce((max, folder) => Math.max(max, folder.sortOrder), -1);
@@ -1912,7 +2201,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       kind: metadata.kind,
@@ -1961,7 +2250,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       userId: input.userId,
@@ -2017,7 +2306,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
       return;
     }
     const input = createSystemUserInput();
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const trimmedName = trimRequiredName(input.name, "User name");
     const data = {
@@ -2051,7 +2340,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
       (userId) => this.findUserById(userId),
       actingUserId
     );
-    const id = randomUUID2();
+    const id = randomUUID3();
     const now = /* @__PURE__ */ new Date();
     const data = {
       userId: actingUserId,
@@ -2079,7 +2368,7 @@ var FirestoreDatabase = class _FirestoreDatabase {
 };
 
 // src/db/mysql/MysqlDatabase.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import mysql from "mysql2/promise";
 
 // src/db/apiTokenRows.ts
@@ -2101,6 +2390,49 @@ function mapApiTokenSqlRow(row) {
   };
 }
 
+// src/db/invitationRows.ts
+function mapInvitationSqlRow(row) {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    codeHash: row.code_hash,
+    codePrefix: row.code_prefix,
+    expiresAt: row.expires_at,
+    redeemedAt: row.redeemed_at,
+    revokedAt: row.revoked_at,
+    createdAt: row.created_at,
+    createdByUserId: row.created_by_user_id ?? null,
+    updatedByUserId: row.updated_by_user_id ?? null
+  };
+}
+function getInvitationStatus(invitation, now = /* @__PURE__ */ new Date()) {
+  if (invitation.redeemedAt) {
+    return "redeemed";
+  }
+  if (invitation.revokedAt) {
+    return "revoked";
+  }
+  if (invitation.expiresAt.getTime() <= now.getTime()) {
+    return "expired";
+  }
+  return "pending";
+}
+
+// src/db/mysql/invitationSql.ts
+var INVITATION_SELECT_COLUMNS = `
+  id,
+  user_id,
+  code_hash,
+  code_prefix,
+  expires_at,
+  redeemed_at,
+  revoked_at,
+  created_at,
+  created_by_user_id,
+  updated_by_user_id
+`.trim();
+var INVITATION_SELECT = `SELECT ${INVITATION_SELECT_COLUMNS} FROM user_invitations`;
+
 // src/db/auditLogRows.ts
 function parseAuditAction(value) {
   if (value === "create" || value === "update" || value === "delete" || value === "reorder" || value === "move") {
@@ -2109,7 +2441,7 @@ function parseAuditAction(value) {
   throw new Error(`Invalid audit action: ${value}`);
 }
 function parseAuditEntityType2(value) {
-  if (value === "user" || value === "api_token" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
+  if (value === "user" || value === "api_token" || value === "invitation" || value === "collection" || value === "environment" || value === "snippet" || value === "folder" || value === "request" || value === "run_result") {
     return value;
   }
   throw new Error(`Invalid audit entity type: ${value}`);
@@ -2515,6 +2847,25 @@ CREATE TABLE IF NOT EXISTS run_results (
   INDEX run_results_created_idx (created_at)
 )
 `.trim();
+var USER_INVITATIONS_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS user_invitations (
+  id VARCHAR(36) PRIMARY KEY,
+  user_id VARCHAR(36) NOT NULL,
+  code_hash CHAR(64) NOT NULL UNIQUE,
+  code_prefix VARCHAR(32) NOT NULL,
+  expires_at DATETIME NOT NULL,
+  redeemed_at DATETIME,
+  revoked_at DATETIME,
+  created_at DATETIME NOT NULL,
+  created_by_user_id VARCHAR(36),
+  updated_by_user_id VARCHAR(36),
+  INDEX user_invitations_user_id_idx (user_id),
+  INDEX user_invitations_expires_at_idx (expires_at),
+  CONSTRAINT user_invitations_user_id_fk FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  CONSTRAINT user_invitations_created_by_fk FOREIGN KEY (created_by_user_id) REFERENCES users(id) ON DELETE SET NULL,
+  CONSTRAINT user_invitations_updated_by_fk FOREIGN KEY (updated_by_user_id) REFERENCES users(id) ON DELETE SET NULL
+)
+`.trim();
 var MYSQL_MIGRATIONS = [
   USERS_MIGRATION_SQL,
   API_TOKENS_MIGRATION_SQL,
@@ -2541,7 +2892,8 @@ var MYSQL_MIGRATIONS = [
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL,
   USERS_SNIPPET_ACCESS_BACKFILL_SQL,
-  RUN_RESULTS_MIGRATION_SQL
+  RUN_RESULTS_MIGRATION_SQL,
+  USER_INVITATIONS_MIGRATION_SQL
 ];
 
 // src/db/mysql/schemas.ts
@@ -2774,7 +3126,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const attributionUserId = trimmedName === SYSTEM_USER_NAME ? id : actingUserId;
     await this.executeStatement(
@@ -3102,53 +3454,343 @@ var MysqlDatabase = class _MysqlDatabase {
     await this.executeStatement(`UPDATE api_tokens SET last_used_at = ? WHERE id = ?`, [when, id]);
   }
   /**
-   * Lists all collections ordered by name.
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
    */
-  async listCollections() {
-    const rows = await this.queryRows(
-      `${COLLECTION_SELECT} ORDER BY name ASC`
-    );
-    return rows.map(mapCollectionSqlRow);
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const connection = await this.requirePool().getConnection();
+    try {
+      await connection.beginTransaction();
+      await connection.execute(
+        `INSERT INTO users (
+          id,
+          name,
+          role,
+          collection_access,
+          environment_access,
+          snippet_access,
+          llm_access,
+          llm_models,
+          llm_monthly_token_limit,
+          created_at,
+          updated_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          userId,
+          trimmedName,
+          input.role,
+          serializeAccessList(input.collectionAccess),
+          serializeAccessList(input.environmentAccess),
+          serializeAccessList(input.snippetAccess),
+          input.llmAccess ? 1 : 0,
+          serializeAccessList(input.llmModels ?? []),
+          input.llmMonthlyTokenLimit ?? null,
+          now,
+          now,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      const [userRows] = await connection.execute(
+        `${USER_SELECT} WHERE id = ? LIMIT 1`,
+        [userId]
+      );
+      const userRow = userRows[0];
+      if (!userRow) {
+        throw new Error("User not found after insert");
+      }
+      await connection.execute(
+        `INSERT INTO user_invitations (
+          id,
+          user_id,
+          code_hash,
+          code_prefix,
+          expires_at,
+          redeemed_at,
+          revoked_at,
+          created_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          invitation.id,
+          invitation.userId,
+          invitation.codeHash,
+          invitation.codePrefix,
+          invitation.expiresAt,
+          invitation.redeemedAt,
+          invitation.revokedAt,
+          invitation.createdAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await connection.commit();
+      await this.recordAuditEntry(actingUserId, "create", "user", userId);
+      await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+      return {
+        user: mapUserSqlRow(userRow),
+        invitation
+      };
+    } catch (error) {
+      await connection.rollback();
+      throw error;
+    } finally {
+      connection.release();
+    }
   }
   /**
-   * Creates a new collection with the given name.
+   * Persists a new onboarding invitation for an existing user account.
    *
-   * @param name - Display name for the collection.
+   * @param invitation - Invitation metadata including the stored code hash.
    * @param actingUserId - User performing the create action.
    */
-  async createCollection(name, actingUserId) {
-    const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID3();
-    const now = /* @__PURE__ */ new Date();
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
     await this.executeStatement(
-      `INSERT INTO collections (
+      `INSERT INTO user_invitations (
         id,
-        name,
-        variables,
-        headers,
-        auth,
-        pre_request_script,
-        post_request_script,
+        user_id,
+        code_hash,
+        code_prefix,
+        expires_at,
+        redeemed_at,
+        revoked_at,
         created_at,
-        updated_at,
         created_by_user_id,
         updated_by_user_id
-      ) VALUES (?, ?, '[]', '[]', ?, '', '', ?, ?, ?, ?)`,
-      [id, trimmedName, MYSQL_DEFAULT_AUTH_JSON, now, now, actingUserId, actingUserId]
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        invitation.id,
+        invitation.userId,
+        invitation.codeHash,
+        invitation.codePrefix,
+        invitation.expiresAt,
+        invitation.redeemedAt,
+        invitation.revokedAt,
+        invitation.createdAt,
+        actingUserId,
+        actingUserId
+      ]
     );
-    await this.recordAuditEntry(actingUserId, "create", "collection", id);
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
     const rows = await this.queryRows(
-      `${COLLECTION_SELECT} WHERE id = ?`,
+      `${INVITATION_SELECT} WHERE id = ? LIMIT 1`,
       [id]
     );
     const row = rows[0];
-    if (!row) {
-      throw new Error("Collection not found after insert");
-    }
-    return mapCollectionSqlRow(row);
+    return row ? mapInvitationSqlRow(row) : null;
   }
   /**
-   * Updates a collection's name, variables, headers, and scripts.
+   * Finds an invitation by the sha256 hash of its secret.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   */
+  async findInvitationByCodeHash(codeHash) {
+    const rows = await this.queryRows(
+      `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+      [codeHash]
+    );
+    const row = rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const rows = await this.queryRows(
+      `${INVITATION_SELECT} ORDER BY created_at DESC`
+    );
+    return rows.map(mapInvitationSqlRow);
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.executeStatement(
+      `UPDATE user_invitations
+      SET revoked_at = ?,
+        updated_by_user_id = ?
+      WHERE id = ?
+        AND redeemed_at IS NULL
+        AND revoked_at IS NULL
+        AND expires_at > ?`,
+      [now, actingUserId, id, now]
+    );
+    const revoked = (result.affectedRows ?? 0) > 0;
+    if (revoked) {
+      await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    }
+    return revoked;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const connection = await this.requirePool().getConnection();
+    try {
+      await connection.beginTransaction();
+      const [updateResult] = await connection.execute(
+        `UPDATE user_invitations
+        SET redeemed_at = ?,
+          updated_by_user_id = ?
+        WHERE code_hash = ?
+          AND redeemed_at IS NULL
+          AND revoked_at IS NULL
+          AND expires_at > ?`,
+        [now, actingUserId, codeHash, now]
+      );
+      if ((updateResult.affectedRows ?? 0) === 0) {
+        const [existingRows] = await connection.execute(
+          `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+          [codeHash]
+        );
+        const existingRow = existingRows[0];
+        if (!existingRow) {
+          throw new InvitationUnavailableError("not_found");
+        }
+        const existing = mapInvitationSqlRow(existingRow);
+        if (existing.redeemedAt) {
+          throw new InvitationUnavailableError("redeemed");
+        }
+        if (existing.revokedAt) {
+          throw new InvitationUnavailableError("revoked");
+        }
+        throw new InvitationUnavailableError("expired");
+      }
+      const [rows] = await connection.execute(
+        `${INVITATION_SELECT} WHERE code_hash = ? LIMIT 1`,
+        [codeHash]
+      );
+      const invitationRow = rows[0];
+      if (!invitationRow) {
+        throw new Error("Invitation not found after claim");
+      }
+      const invitation = mapInvitationSqlRow(invitationRow);
+      const [userRows] = await connection.execute(
+        `${USER_SELECT} WHERE id = ? LIMIT 1`,
+        [invitation.userId]
+      );
+      const userRow = userRows[0];
+      if (!userRow) {
+        throw new Error("User not found");
+      }
+      const user = mapUserSqlRow(userRow);
+      const { record, secret } = generateApiToken(user.id, tokenName);
+      await connection.execute(
+        `INSERT INTO api_tokens (
+          id,
+          user_id,
+          name,
+          token_hash,
+          token_prefix,
+          created_at,
+          last_used_at,
+          revoked_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          record.id,
+          record.userId,
+          record.name,
+          record.tokenHash,
+          record.tokenPrefix,
+          record.createdAt,
+          record.lastUsedAt,
+          record.revokedAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await connection.commit();
+      await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+      await this.recordAuditEntry(actingUserId, "create", "api_token", record.id);
+      return { user, token: record, secret };
+    } catch (error) {
+      await connection.rollback();
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+  /**
+   * Lists all collections ordered by name.
+   */
+  async listCollections() {
+    const rows = await this.queryRows(
+      `${COLLECTION_SELECT} ORDER BY name ASC`
+    );
+    return rows.map(mapCollectionSqlRow);
+  }
+  /**
+   * Creates a new collection with the given name.
+   *
+   * @param name - Display name for the collection.
+   * @param actingUserId - User performing the create action.
+   */
+  async createCollection(name, actingUserId) {
+    const trimmedName = trimRequiredName(name, "Collection name");
+    const id = randomUUID4();
+    const now = /* @__PURE__ */ new Date();
+    await this.executeStatement(
+      `INSERT INTO collections (
+        id,
+        name,
+        variables,
+        headers,
+        auth,
+        pre_request_script,
+        post_request_script,
+        created_at,
+        updated_at,
+        created_by_user_id,
+        updated_by_user_id
+      ) VALUES (?, ?, '[]', '[]', ?, '', '', ?, ?, ?, ?)`,
+      [id, trimmedName, MYSQL_DEFAULT_AUTH_JSON, now, now, actingUserId, actingUserId]
+    );
+    await this.recordAuditEntry(actingUserId, "create", "collection", id);
+    const rows = await this.queryRows(
+      `${COLLECTION_SELECT} WHERE id = ?`,
+      [id]
+    );
+    const row = rows[0];
+    if (!row) {
+      throw new Error("Collection not found after insert");
+    }
+    return mapCollectionSqlRow(row);
+  }
+  /**
+   * Updates a collection's name, variables, headers, and scripts.
    *
    * @param actingUserId - User performing the update action.
    */
@@ -3263,7 +3905,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO environments (
@@ -3392,7 +4034,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const maxRows = await this.queryRows(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM snippets"
@@ -3615,7 +4257,7 @@ var MysqlDatabase = class _MysqlDatabase {
       [input.collectionId, folderId, folderId]
     );
     const maxOrder = maxRows[0]?.max_order ?? -1;
-    const id = randomUUID3();
+    const id = randomUUID4();
     await this.executeStatement(
       `INSERT INTO requests (
         id,
@@ -3715,7 +4357,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const maxRows = await this.queryRows(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM folders WHERE collection_id = ?",
@@ -3969,7 +4611,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async addLlmUsage(userId, period, promptTokens, completionTokens) {
     const totalDelta = promptTokens + completionTokens;
     const now = /* @__PURE__ */ new Date();
-    const id = randomUUID3();
+    const id = randomUUID4();
     await this.executeStatement(
       `INSERT INTO llm_usage (
         id,
@@ -3999,7 +4641,7 @@ var MysqlDatabase = class _MysqlDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO llm_usage_log (
@@ -4077,7 +4719,7 @@ var MysqlDatabase = class _MysqlDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO run_results (
@@ -4149,7 +4791,7 @@ var MysqlDatabase = class _MysqlDatabase {
       return;
     }
     const input = createSystemUserInput();
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     const trimmedName = trimRequiredName(input.name, "User name");
     await this.executeStatement(
@@ -4197,7 +4839,7 @@ var MysqlDatabase = class _MysqlDatabase {
    */
   async recordAuditEntry(actingUserId, action, entityType, entityId, metadata) {
     const userName = await resolveActingUserName(this.findUserById.bind(this), actingUserId);
-    const id = randomUUID3();
+    const id = randomUUID4();
     const now = /* @__PURE__ */ new Date();
     await this.executeStatement(
       `INSERT INTO audit_log (
@@ -4259,9 +4901,24 @@ var MysqlDatabase = class _MysqlDatabase {
 };
 
 // src/db/postgres/PostgresDatabase.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 import pg from "pg";
 
+// src/db/postgres/invitationSql.ts
+var INVITATION_SELECT_COLUMNS2 = `
+  id,
+  user_id,
+  code_hash,
+  code_prefix,
+  expires_at,
+  redeemed_at,
+  revoked_at,
+  created_at,
+  created_by_user_id,
+  updated_by_user_id
+`.trim();
+var INVITATION_SELECT2 = `SELECT ${INVITATION_SELECT_COLUMNS2} FROM user_invitations`;
+
 // src/db/postgres/migrations.ts
 var API_TOKENS_MIGRATION_SQL2 = `
 CREATE TABLE IF NOT EXISTS api_tokens (
@@ -4501,6 +5158,22 @@ CREATE TABLE IF NOT EXISTS run_results (
 );
 CREATE INDEX IF NOT EXISTS run_results_created_idx ON run_results (created_at DESC);
 `.trim();
+var USER_INVITATIONS_MIGRATION_SQL2 = `
+CREATE TABLE IF NOT EXISTS user_invitations (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  code_hash CHAR(64) NOT NULL UNIQUE,
+  code_prefix TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  redeemed_at TIMESTAMPTZ,
+  revoked_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL,
+  created_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
+  updated_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS user_invitations_user_id_idx ON user_invitations (user_id);
+CREATE INDEX IF NOT EXISTS user_invitations_expires_at_idx ON user_invitations (expires_at);
+`.trim();
 var POSTGRES_MIGRATIONS = [
   USERS_MIGRATION_SQL2,
   API_TOKENS_MIGRATION_SQL2,
@@ -4527,7 +5200,8 @@ var POSTGRES_MIGRATIONS = [
   ENVIRONMENTS_DELETION_LOCKED_MIGRATION_SQL2,
   USERS_SNIPPET_ACCESS_MIGRATION_SQL2,
   USERS_SNIPPET_ACCESS_BACKFILL_SQL2,
-  RUN_RESULTS_MIGRATION_SQL2
+  RUN_RESULTS_MIGRATION_SQL2,
+  USER_INVITATIONS_MIGRATION_SQL2
 ];
 
 // src/db/postgres/schemas.ts
@@ -4685,7 +5359,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async createUser(input, actingUserId) {
     const trimmedName = trimRequiredName(input.name, "User name");
     assertUserNameNotReserved(trimmedName);
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO users (
@@ -5003,6 +5677,286 @@ var PostgresDatabase = class _PostgresDatabase {
   async touchApiTokenLastUsed(id, when) {
     await this.query(`UPDATE api_tokens SET last_used_at = $2 WHERE id = $1`, [id, when]);
   }
+  /**
+   * Creates a user account and its initial onboarding invitation in one transaction.
+   *
+   * @param userId - Pre-generated stable identifier for the new user.
+   * @param input - User fields to persist.
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitedUser(userId, input, invitation, actingUserId) {
+    const trimmedName = trimRequiredName(input.name, "User name");
+    assertUserNameNotReserved(trimmedName);
+    const now = /* @__PURE__ */ new Date();
+    const client = await this.requirePool().connect();
+    try {
+      await client.query("BEGIN");
+      const userResult = await client.query(
+        `INSERT INTO users (
+          id,
+          name,
+          role,
+          collection_access,
+          environment_access,
+          snippet_access,
+          llm_access,
+          llm_models,
+          llm_monthly_token_limit,
+          created_at,
+          updated_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+        RETURNING ${USER_SELECT_COLUMNS}`,
+        [
+          userId,
+          trimmedName,
+          input.role,
+          serializeAccessList(input.collectionAccess),
+          serializeAccessList(input.environmentAccess),
+          serializeAccessList(input.snippetAccess),
+          input.llmAccess ?? false,
+          serializeAccessList(input.llmModels ?? []),
+          input.llmMonthlyTokenLimit ?? null,
+          now,
+          now,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      const userRow = userResult.rows[0];
+      if (!userRow) {
+        throw new Error("User not found after insert");
+      }
+      await client.query(
+        `INSERT INTO user_invitations (
+          id,
+          user_id,
+          code_hash,
+          code_prefix,
+          expires_at,
+          redeemed_at,
+          revoked_at,
+          created_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          invitation.id,
+          invitation.userId,
+          invitation.codeHash,
+          invitation.codePrefix,
+          invitation.expiresAt,
+          invitation.redeemedAt,
+          invitation.revokedAt,
+          invitation.createdAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await client.query("COMMIT");
+      await this.recordAuditEntry(actingUserId, "create", "user", userId);
+      await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+      return {
+        user: mapUserSqlRow(userRow),
+        invitation
+      };
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /**
+   * Persists a new onboarding invitation for an existing user account.
+   *
+   * @param invitation - Invitation metadata including the stored code hash.
+   * @param actingUserId - User performing the create action.
+   */
+  async createInvitation(invitation, actingUserId) {
+    const user = await this.findUserById(invitation.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+    await this.query(
+      `INSERT INTO user_invitations (
+        id,
+        user_id,
+        code_hash,
+        code_prefix,
+        expires_at,
+        redeemed_at,
+        revoked_at,
+        created_at,
+        created_by_user_id,
+        updated_by_user_id
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+      [
+        invitation.id,
+        invitation.userId,
+        invitation.codeHash,
+        invitation.codePrefix,
+        invitation.expiresAt,
+        invitation.redeemedAt,
+        invitation.revokedAt,
+        invitation.createdAt,
+        actingUserId,
+        actingUserId
+      ]
+    );
+    await this.recordAuditEntry(actingUserId, "create", "invitation", invitation.id);
+    return invitation;
+  }
+  /**
+   * Finds an invitation by stable identifier.
+   *
+   * @param id - Invitation identifier to look up.
+   */
+  async findInvitationById(id) {
+    const result = await this.query(
+      `${INVITATION_SELECT2} WHERE id = $1 LIMIT 1`,
+      [id]
+    );
+    const row = result.rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Finds an invitation by the sha256 hash of its secret.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   */
+  async findInvitationByCodeHash(codeHash) {
+    const result = await this.query(
+      `${INVITATION_SELECT2} WHERE code_hash = $1 LIMIT 1`,
+      [codeHash]
+    );
+    const row = result.rows[0];
+    return row ? mapInvitationSqlRow(row) : null;
+  }
+  /**
+   * Lists all invitations ordered by creation time descending.
+   */
+  async listInvitations() {
+    const result = await this.query(
+      `${INVITATION_SELECT2} ORDER BY created_at DESC`
+    );
+    return result.rows.map(mapInvitationSqlRow);
+  }
+  /**
+   * Revokes a pending invitation by id.
+   *
+   * @param id - Invitation identifier to revoke.
+   * @param actingUserId - User performing the revoke action.
+   */
+  async revokeInvitation(id, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.query(
+      `UPDATE user_invitations
+      SET revoked_at = $1, updated_by_user_id = $2
+      WHERE id = $3
+        AND redeemed_at IS NULL
+        AND revoked_at IS NULL
+        AND expires_at > $1
+      RETURNING id`,
+      [now, actingUserId, id]
+    );
+    if (!result.rows[0]) {
+      return false;
+    }
+    await this.recordAuditEntry(actingUserId, "update", "invitation", id);
+    return true;
+  }
+  /**
+   * Atomically consumes a pending invitation and issues a permanent API token.
+   *
+   * @param codeHash - sha256 hex digest of the invitation secret.
+   * @param tokenName - Label stored on the newly created API token.
+   * @param actingUserId - Internal user attributed with the redemption action.
+   */
+  async redeemInvitation(codeHash, tokenName, actingUserId) {
+    const now = /* @__PURE__ */ new Date();
+    const client = await this.requirePool().connect();
+    try {
+      await client.query("BEGIN");
+      const claimResult = await client.query(
+        `UPDATE user_invitations
+        SET redeemed_at = $1, updated_by_user_id = $2
+        WHERE code_hash = $3
+          AND redeemed_at IS NULL
+          AND revoked_at IS NULL
+          AND expires_at > $1
+        RETURNING ${INVITATION_SELECT_COLUMNS2}`,
+        [now, actingUserId, codeHash]
+      );
+      const invitationRow = claimResult.rows[0];
+      if (!invitationRow) {
+        const existingResult = await client.query(
+          `${INVITATION_SELECT2} WHERE code_hash = $1 LIMIT 1`,
+          [codeHash]
+        );
+        const existingRow = existingResult.rows[0];
+        if (!existingRow) {
+          throw new InvitationUnavailableError("not_found");
+        }
+        const existing = mapInvitationSqlRow(existingRow);
+        if (existing.redeemedAt) {
+          throw new InvitationUnavailableError("redeemed");
+        }
+        if (existing.revokedAt) {
+          throw new InvitationUnavailableError("revoked");
+        }
+        throw new InvitationUnavailableError("expired");
+      }
+      const invitation = mapInvitationSqlRow(invitationRow);
+      const userResult = await client.query(`${USER_SELECT2} WHERE id = $1 LIMIT 1`, [
+        invitation.userId
+      ]);
+      const userRow = userResult.rows[0];
+      if (!userRow) {
+        throw new Error("User not found");
+      }
+      const user = mapUserSqlRow(userRow);
+      const effectiveTokenName = tokenName.trim().length > 0 ? tokenName.trim() : user.name;
+      const { record, secret } = generateApiToken(user.id, effectiveTokenName);
+      await client.query(
+        `INSERT INTO api_tokens (
+          id,
+          user_id,
+          name,
+          token_hash,
+          token_prefix,
+          created_at,
+          last_used_at,
+          revoked_at,
+          created_by_user_id,
+          updated_by_user_id
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          record.id,
+          record.userId,
+          record.name,
+          record.tokenHash,
+          record.tokenPrefix,
+          record.createdAt,
+          record.lastUsedAt,
+          record.revokedAt,
+          actingUserId,
+          actingUserId
+        ]
+      );
+      await client.query("COMMIT");
+      await this.recordAuditEntry(actingUserId, "update", "invitation", invitation.id);
+      await this.recordAuditEntry(actingUserId, "create", "api_token", record.id);
+      return { user, token: record, secret };
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
   /**
    * Lists all collections ordered by name.
    */
@@ -5018,7 +5972,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createCollection(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Collection name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO collections (
@@ -5153,7 +6107,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createEnvironment(name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Environment name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO environments (
@@ -5276,7 +6230,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createSnippet(name, code, scope, actingUserId) {
     const trimmedName = trimRequiredName(name, "Snippet name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const maxResult = await this.query(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM snippets"
@@ -5482,7 +6436,7 @@ var PostgresDatabase = class _PostgresDatabase {
       [input.collectionId, folderId]
     );
     const maxOrder = maxResult.rows[0]?.max_order ?? -1;
-    const id = randomUUID4();
+    const id = randomUUID5();
     const result = await this.query(
       `INSERT INTO requests (
         id,
@@ -5576,7 +6530,7 @@ var PostgresDatabase = class _PostgresDatabase {
    */
   async createFolder(collectionId, name, actingUserId) {
     const trimmedName = trimRequiredName(name, "Folder name");
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const maxResult = await this.query(
       "SELECT COALESCE(MAX(sort_order), -1) AS max_order FROM folders WHERE collection_id = $1",
@@ -5823,7 +6777,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async addLlmUsage(userId, period, promptTokens, completionTokens) {
     const totalDelta = promptTokens + completionTokens;
     const now = /* @__PURE__ */ new Date();
-    const id = randomUUID4();
+    const id = randomUUID5();
     const result = await this.query(
       `INSERT INTO llm_usage (
         id,
@@ -5854,7 +6808,7 @@ var PostgresDatabase = class _PostgresDatabase {
    * @param input - Usage details for one successful completion step.
    */
   async createLlmUsageLog(input) {
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO llm_usage_log (
@@ -5929,7 +6883,7 @@ var PostgresDatabase = class _PostgresDatabase {
   async createRunResult(input, actingUserId) {
     const metadata = parseRunResultPayload(input.payload);
     const label = input.label?.trim() || buildDefaultRunResultLabel(metadata);
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const result = await this.query(
       `INSERT INTO run_results (
@@ -6009,7 +6963,7 @@ var PostgresDatabase = class _PostgresDatabase {
       this.systemUserId = existing.id;
       return;
     }
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     const input = createSystemUserInput();
     await this.query(
@@ -6060,7 +7014,7 @@ var PostgresDatabase = class _PostgresDatabase {
       (userId) => this.findUserById(userId),
       actingUserId
     );
-    const id = randomUUID4();
+    const id = randomUUID5();
     const now = /* @__PURE__ */ new Date();
     await this.query(
       `INSERT INTO audit_log (
@@ -6264,39 +7218,41 @@ function registerMigrateCommand(program, handler = migrateCommand) {
 
 // src/cli/userCommand.ts
 import { InvalidArgumentError } from "commander";
+import { randomUUID as randomUUID7 } from "crypto";
 
-// src/server/auth/apiTokens.ts
-import { createHash, randomBytes, randomUUID as randomUUID5 } from "crypto";
-var TOKEN_PREFIX = "hbk_";
-function hashToken(token) {
-  return createHash("sha256").update(token).digest("hex");
-}
-function generateApiToken(userId, name) {
-  const secretSuffix = randomBytes(32).toString("base64url");
-  const secret = `${TOKEN_PREFIX}${secretSuffix}`;
-  const tokenPrefix = `${TOKEN_PREFIX}${secretSuffix.slice(0, 8)}`;
+// src/server/auth/invitations.ts
+import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID6 } from "crypto";
+var INVITATION_PREFIX = "hbi_";
+var DEFAULT_INVITATION_EXPIRES_IN_HOURS = 24;
+function hashInvitationSecret(secret) {
+  return createHash2("sha256").update(secret).digest("hex");
+}
+function isInvitationSecretFormat(secret) {
+  return secret.startsWith(INVITATION_PREFIX) && secret.length > INVITATION_PREFIX.length + 8;
+}
+function resolveInvitationExpiresAt(expiresInHours) {
+  const hours = expiresInHours !== void 0 && expiresInHours > 0 ? expiresInHours : DEFAULT_INVITATION_EXPIRES_IN_HOURS;
+  return new Date(Date.now() + hours * 60 * 60 * 1e3);
+}
+function generateInvitation(userId, actingUserId, expiresAt) {
+  const secretSuffix = randomBytes2(32).toString("base64url");
+  const secret = `${INVITATION_PREFIX}${secretSuffix}`;
+  const codePrefix = `${INVITATION_PREFIX}${secretSuffix.slice(0, 8)}`;
   const createdAt = /* @__PURE__ */ new Date();
   const record = {
-    id: randomUUID5(),
+    id: randomUUID6(),
     userId,
-    name,
-    tokenHash: hashToken(secret),
-    tokenPrefix,
-    createdAt,
-    lastUsedAt: null,
+    codeHash: hashInvitationSecret(secret),
+    codePrefix,
+    expiresAt,
+    redeemedAt: null,
     revokedAt: null,
-    createdByUserId: null,
-    updatedByUserId: null
+    createdAt,
+    createdByUserId: actingUserId,
+    updatedByUserId: actingUserId
   };
   return { record, secret };
 }
-function extractBearer(headerValue) {
-  if (!headerValue) {
-    return null;
-  }
-  const match = /^Bearer\s+(\S+)$/i.exec(headerValue.trim());
-  return match?.[1] ?? null;
-}
 
 // src/server/admin/userValidation.ts
 var ValidationError = class extends Error {
@@ -6470,6 +7426,14 @@ var LLM_MODEL_CATALOG = [
 function hasProviderKey(config, provider) {
   return Boolean(config.providers[provider]?.apiKey.trim());
 }
+function hasHubOpenAiProvider(config) {
+  return hasProviderKey(config, "openai");
+}
+function getHubLlmCapabilities(config) {
+  return {
+    openai: hasProviderKey(config, "openai")
+  };
+}
 function listHubOfferedModels(config) {
   const allowList = config.models ? new Set(config.models) : null;
   return LLM_MODEL_CATALOG.filter((model) => {
@@ -6544,6 +7508,13 @@ function parseMonthlyTokenLimit(value) {
   }
   return parsed;
 }
+function parsePositiveInt(value) {
+  const parsed = Number(value.trim());
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new InvalidArgumentError("Value must be a positive integer.");
+  }
+  return parsed;
+}
 function printUser(user, usage) {
   console.log(`- id: ${user.id}`);
   console.log(`  name: ${user.name}`);
@@ -6649,6 +7620,100 @@ async function userCreateCommand(options) {
   console.log("");
   printCreatedApiToken(user, record, secret);
 }
+function printCreatedInvitation(user, invitation, secret) {
+  console.log(`Created invitation (${invitation.id}) for user "${user.name}" (${user.id}).`);
+  console.log(`Invitation prefix: ${invitation.codePrefix}`);
+  console.log(`Expires: ${invitation.expiresAt.toISOString()}`);
+  console.log("");
+  console.log("Store this invitation secret now; it will not be shown again:");
+  console.log(secret);
+}
+async function userInviteCreateCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  const access = mapValidationError(
+    () => normalizeAccessForRole(
+      options.role,
+      options.collectionAccess,
+      options.environmentAccess,
+      options.snippetAccess
+    )
+  );
+  await db.connect();
+  const actingUserId = await requireSystemUserId(db);
+  const catalogs = await loadAccessCatalogs(db, config.llm);
+  const llmModels = readLlmModelsOption(options);
+  const llm = mapValidationError(
+    () => normalizeLlmForRole(options.role, options.llmAccess ?? false, llmModels)
+  );
+  validateSubmittedAccessListsOrThrow(
+    {
+      role: options.role,
+      collectionAccess: access.collectionAccess,
+      environmentAccess: access.environmentAccess,
+      snippetAccess: access.snippetAccess,
+      llmModels
+    },
+    catalogs
+  );
+  const userId = randomUUID7();
+  const expiresAt = resolveInvitationExpiresAt(options.expiresInHours);
+  const { record: invitation, secret } = generateInvitation(userId, actingUserId, expiresAt);
+  const created = await db.createInvitedUser(
+    userId,
+    {
+      name: options.name,
+      role: options.role,
+      collectionAccess: access.collectionAccess ?? [],
+      environmentAccess: access.environmentAccess ?? [],
+      snippetAccess: access.snippetAccess ?? [],
+      llmAccess: llm.llmAccess,
+      llmModels: llm.llmModels,
+      llmMonthlyTokenLimit: options.llmMonthlyTokens ?? null
+    },
+    invitation,
+    actingUserId
+  );
+  await db.disconnect();
+  console.log(
+    `Created invited user "${created.user.name}" (${created.user.id}) with role ${created.user.role}.`
+  );
+  printUser(created.user);
+  console.log("");
+  printCreatedInvitation(created.user, created.invitation, secret);
+}
+async function userInviteListCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  await db.connect();
+  const [invitations, users] = await Promise.all([db.listInvitations(), db.listUsers()]);
+  await db.disconnect();
+  if (invitations.length === 0) {
+    console.log("No invitations found.");
+    return;
+  }
+  const usersById = new Map(users.map((user) => [user.id, user.name]));
+  for (const invitation of invitations) {
+    const userName = usersById.get(invitation.userId) ?? invitation.userId;
+    console.log(
+      `${invitation.id}  ${userName}  ${invitation.codePrefix}  ${getInvitationStatus(invitation)}`
+    );
+    console.log(`  expires: ${invitation.expiresAt.toISOString()}`);
+  }
+}
+async function userInviteRevokeCommand(options) {
+  const config = loadServerConfig(options.config);
+  const db = createDatabase(config.db);
+  await db.connect();
+  const actingUserId = await requireSystemUserId(db);
+  const revoked = await db.revokeInvitation(options.id, actingUserId);
+  await db.disconnect();
+  if (revoked) {
+    console.log(`Revoked invitation ${options.id}.`);
+    return;
+  }
+  console.log(`No pending invitation found with id ${options.id}.`);
+}
 async function userListCommand(options) {
   const config = loadServerConfig(options.config);
   const db = createDatabase(config.db);
@@ -6821,6 +7886,48 @@ async function userTokenRevokeCommand(options) {
 }
 function registerUserCommand(program, handlers = {}) {
   const user = program.command("user").description("Manage user accounts and their API tokens");
+  const invite = user.command("invite").description("Manage onboarding invitations for user accounts");
+  invite.command("create").description("Create a user account with a single-use onboarding invitation").requiredOption("--name <name>", "Unique display name", parseRequiredName).requiredOption("--role <role>", "Account role (admin or user)", parseUserRole2).option(
+    "--collection-access <id>",
+    "Collection id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option(
+    "--environment-access <id>",
+    "Environment id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option(
+    "--snippet-access <id>",
+    "Snippet id or * (repeatable)",
+    parseAccessFlag,
+    []
+  ).option("--llm-access", "Enable hub-proxied LLM access for the user").option("--llm-model <id>", "LLM model id or * (repeatable)", parseAccessFlag, []).option("--llm-monthly-tokens <count>", "Monthly LLM token limit", parseMonthlyTokenLimit).option("--expires-in-hours <hours>", "Invitation lifetime in hours", parsePositiveInt).action(
+    /**
+     * Runs the user invite create subcommand after merging global CLI options.
+     */
+    async function userInviteCreateAction(options) {
+      await (handlers.inviteCreate ?? userInviteCreateCommand)(mergeGlobalOptions(this, options));
+    }
+  );
+  invite.command("list").description("List stored onboarding invitations").action(
+    /**
+     * Runs the user invite list subcommand after merging global CLI options.
+     */
+    async function userInviteListAction(options) {
+      await (handlers.inviteList ?? userInviteListCommand)(mergeGlobalOptions(this, options));
+    }
+  );
+  invite.command("revoke").description("Revoke a pending onboarding invitation by id").argument("<id>", "Invitation identifier to revoke").action(
+    /**
+     * Runs the user invite revoke subcommand after merging global CLI options.
+     */
+    async function userInviteRevokeAction(id, options) {
+      await (handlers.inviteRevoke ?? userInviteRevokeCommand)(
+        mergeGlobalOptions(this, { ...options, id })
+      );
+    }
+  );
   user.command("create").description("Create a new user account").requiredOption("--name <name>", "Unique display name", parseRequiredName).requiredOption("--role <role>", "Account role (admin or user)", parseUserRole2).option(
     "--collection-access <id>",
     "Collection id or * (repeatable)",
@@ -6992,6 +8099,9 @@ function readPackageVersion() {
   return pkg.version;
 }
 
+// src/server/routes/admin.ts
+import { randomUUID as randomUUID8 } from "crypto";
+
 // src/server/auth/accessControl.ts
 function isAdmin(user) {
   return user.role === "admin";
@@ -7285,8 +8395,12 @@ var llmModelSchema = z7.object({
   label: z7.string(),
   provider: z7.enum(["openai", "claude", "gemini"])
 });
+var llmCapabilitiesSchema = z7.object({
+  openai: z7.boolean()
+});
 var listLlmModelsResponseSchema = z7.object({
-  models: z7.array(llmModelSchema)
+  models: z7.array(llmModelSchema),
+  capabilities: llmCapabilitiesSchema
 });
 var llmUsageSummaryResponseSchema = z7.object({
   period: z7.string(),
@@ -7637,7 +8751,7 @@ var listAdminTokensResponseSchema = z9.object({
   tokens: z9.array(hubApiTokenRecordSchema)
 });
 var reloadConfigSectionResultSchema = z9.object({
-  section: z9.enum(["db", "redis", "llm", "plugins", "server"]),
+  section: z9.enum(["db", "redis", "llm", "plugins", "docs", "server"]),
   status: z9.enum(["reloaded", "unchanged", "failed", "restart-required"]),
   error: z9.string().optional()
 });
@@ -7672,6 +8786,73 @@ function serializeApiToken(token) {
   };
 }
 
+// src/server/routes/schemas/invitations.ts
+import { z as z10 } from "zod/v4";
+var invitationStatusSchema = z10.enum(["pending", "redeemed", "revoked", "expired"]);
+var hubInvitationRecordSchema = z10.object({
+  id: z10.string(),
+  userId: z10.string(),
+  codePrefix: z10.string(),
+  expiresAt: timestampSchema,
+  redeemedAt: timestampSchema.nullable(),
+  revokedAt: timestampSchema.nullable(),
+  createdAt: timestampSchema,
+  status: invitationStatusSchema
+});
+var createAdminInvitedUserBodySchema = createAdminUserBodySchema.extend({
+  expiresInHours: z10.number().int().positive().optional()
+});
+var createAdminInvitationResponseSchema = z10.object({
+  user: hubUserRecordSchema,
+  invitation: hubInvitationRecordSchema,
+  secret: z10.string()
+});
+var listAdminInvitationsResponseSchema = z10.object({
+  invitations: z10.array(hubInvitationRecordSchema)
+});
+var invitationSecretBodySchema = z10.object({
+  secret: z10.string().trim().min(1)
+});
+var redeemInvitationBodySchema = invitationSecretBodySchema.extend({
+  tokenName: z10.string().trim().min(1).optional()
+});
+var hubInvitationPreviewUserSchema = z10.object({
+  name: z10.string(),
+  role: userRoleSchema,
+  collectionAccess: z10.array(z10.string()),
+  environmentAccess: z10.array(z10.string()),
+  snippetAccess: z10.array(z10.string()),
+  llmAccess: z10.boolean(),
+  llmModels: z10.array(z10.string())
+});
+var previewInvitationResponseSchema = z10.object({
+  user: hubInvitationPreviewUserSchema,
+  expiresAt: timestampSchema
+});
+function serializeHubInvitation(invitation) {
+  return {
+    id: invitation.id,
+    userId: invitation.userId,
+    codePrefix: invitation.codePrefix,
+    expiresAt: invitation.expiresAt.toISOString(),
+    redeemedAt: invitation.redeemedAt?.toISOString() ?? null,
+    revokedAt: invitation.revokedAt?.toISOString() ?? null,
+    createdAt: invitation.createdAt.toISOString(),
+    status: getInvitationStatus(invitation)
+  };
+}
+function serializeInvitationPreviewUser(user) {
+  return {
+    name: user.name,
+    role: user.role,
+    collectionAccess: user.collectionAccess,
+    environmentAccess: user.environmentAccess,
+    snippetAccess: user.snippetAccess,
+    llmAccess: user.llmAccess,
+    llmModels: user.llmModels
+  };
+}
+
 // src/server/routes/admin.ts
 function sendLlmUnavailable(reply) {
   return reply.code(503).send({
@@ -7818,6 +8999,174 @@ async function registerAdminRoutes(app, options) {
       }
     }
   });
+  routes.route({
+    method: "POST",
+    url: "/admin/invited-users",
+    schema: {
+      body: createAdminInvitedUserBodySchema,
+      response: {
+        201: createAdminInvitationResponseSchema,
+        400: errorResponseSchema,
+        403: errorResponseSchema
+      }
+    },
+    /**
+     * Creates a user account and a single-use onboarding invitation without issuing an API token.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const input = buildAdminUserCreateInput(request.body);
+        const llm = getLlm();
+        const [collections, environments, snippets] = await Promise.all([
+          db.listCollections(),
+          db.listEnvironments(),
+          db.listSnippets()
+        ]);
+        const catalogs = buildAccessCatalogIds(
+          collections,
+          environments,
+          snippets,
+          llm ? listHubOfferedModels(llm).map((model) => model.id) : null
+        );
+        validateSubmittedAccessLists(
+          {
+            role: request.body.role,
+            collectionAccess: request.body.collectionAccess,
+            environmentAccess: request.body.environmentAccess,
+            snippetAccess: request.body.snippetAccess,
+            llmModels: request.body.llmModels
+          },
+          catalogs
+        );
+        const userId = randomUUID8();
+        const expiresAt = resolveInvitationExpiresAt(request.body.expiresInHours);
+        const { record: invitation, secret } = generateInvitation(userId, user.id, expiresAt);
+        const created = await db.createInvitedUser(userId, input, invitation, user.id);
+        return reply.code(201).send({
+          user: serializeHubUser(created.user),
+          invitation: serializeHubInvitation(created.invitation),
+          secret
+        });
+      } catch (error) {
+        if (handleValidationError(reply, error) || handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "POST",
+    url: "/admin/users/:id/invitations",
+    schema: {
+      params: idParamSchema,
+      body: createAdminInvitedUserBodySchema.pick({ expiresInHours: true }),
+      response: {
+        201: createAdminInvitationResponseSchema,
+        400: errorResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Issues a replacement onboarding invitation for an existing user account.
+     */
+    handler: async (request, reply) => {
+      try {
+        const admin = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(admin))) {
+          return;
+        }
+        const existing = await db.findUserById(request.params.id);
+        if (!existing) {
+          return reply.code(404).send({ error: "User not found" });
+        }
+        if (denySystemUserTarget(reply, existing, db.getSystemUserId())) {
+          return;
+        }
+        const expiresAt = resolveInvitationExpiresAt(request.body.expiresInHours);
+        const { record: invitation, secret } = generateInvitation(existing.id, admin.id, expiresAt);
+        await db.createInvitation(invitation, admin.id);
+        return reply.code(201).send({
+          user: serializeHubUser(existing),
+          invitation: serializeHubInvitation(invitation),
+          secret
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "GET",
+    url: "/admin/invitations",
+    schema: {
+      response: {
+        200: listAdminInvitationsResponseSchema,
+        403: errorResponseSchema
+      }
+    },
+    /**
+     * Lists onboarding invitations for operator review and recovery.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const invitations = await db.listInvitations();
+        return reply.send({
+          invitations: invitations.map((invitation) => serializeHubInvitation(invitation))
+        });
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "DELETE",
+    url: "/admin/invitations/:id",
+    schema: {
+      params: idParamSchema,
+      response: {
+        204: emptyResponseSchema,
+        403: errorResponseSchema,
+        404: errorResponseSchema
+      }
+    },
+    /**
+     * Revokes a pending onboarding invitation so it can no longer be redeemed.
+     */
+    handler: async (request, reply) => {
+      try {
+        const user = requireAuthenticatedUser(request);
+        if (denyUnlessAllowed(reply, canUseManagementApi(user))) {
+          return;
+        }
+        const revoked = await db.revokeInvitation(request.params.id, user.id);
+        if (!revoked) {
+          return reply.code(404).send({ error: "Invitation not found or not revocable." });
+        }
+        return reply.code(204).send(null);
+      } catch (error) {
+        if (handleDbError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
   routes.route({
     method: "GET",
     url: "/admin/collections",
@@ -8377,7 +9726,7 @@ async function registerAdminRoutes(app, options) {
         label: model.label,
         provider: model.provider
       }));
-      return reply.send({ models });
+      return reply.send({ models, capabilities: getHubLlmCapabilities(llm) });
     }
   });
   routes.route({
@@ -8681,6 +10030,189 @@ async function registerAuthRoutes(app) {
   });
 }
 
+// src/db/invitationValidation.ts
+function assertInvitationPending(invitation, now = /* @__PURE__ */ new Date()) {
+  if (invitation.redeemedAt) {
+    throw new InvitationUnavailableError("redeemed");
+  }
+  if (invitation.revokedAt) {
+    throw new InvitationUnavailableError("revoked");
+  }
+  if (invitation.expiresAt.getTime() <= now.getTime()) {
+    throw new InvitationUnavailableError("expired");
+  }
+}
+
+// src/server/routes/invitationErrors.ts
+function handleInvitationError(reply, error) {
+  if (!(error instanceof InvitationUnavailableError)) {
+    return false;
+  }
+  const status = error.reason === "not_found" ? 404 : 410;
+  void reply.code(status).send(errorResponseSchema.parse({ error: error.message }));
+  return true;
+}
+
+// src/server/routes/invitations.ts
+function buildInvitationThrottleKey(request) {
+  return `${request.ip}:invitation`;
+}
+function createInvitationThrottleHook(throttleStore) {
+  return async function invitationThrottle(request, reply) {
+    const policy = throttleStore.getPolicy();
+    const throttleKey = buildInvitationThrottleKey(request);
+    try {
+      if (await throttleStore.isBlocked(throttleKey)) {
+        return reply.header("Retry-After", String(policy.blockSeconds)).code(429).send({ error: "Too Many Requests" });
+      }
+    } catch {
+      return reply.code(503).send({ error: "Service Unavailable" });
+    }
+  };
+}
+async function recordInvitationFailure(throttleStore, request, reply) {
+  const throttleKey = buildInvitationThrottleKey(request);
+  try {
+    await throttleStore.recordFailure(throttleKey);
+    return false;
+  } catch {
+    void reply.code(503).send({ error: "Service Unavailable" });
+    return true;
+  }
+}
+async function resetInvitationThrottle(throttleStore, request, reply) {
+  const throttleKey = buildInvitationThrottleKey(request);
+  try {
+    await throttleStore.reset(throttleKey);
+    return false;
+  } catch {
+    void reply.code(503).send({ error: "Service Unavailable" });
+    return true;
+  }
+}
+async function registerInvitationRoutes(app, options) {
+  const routes = app.withTypeProvider();
+  app.addHook("onRequest", createInvitationThrottleHook(options.throttleStore));
+  routes.route({
+    method: "POST",
+    url: "/auth/invitations/preview",
+    schema: {
+      body: invitationSecretBodySchema,
+      response: {
+        200: previewInvitationResponseSchema,
+        400: errorResponseSchema,
+        404: errorResponseSchema,
+        410: errorResponseSchema,
+        429: errorResponseSchema,
+        503: errorResponseSchema
+      }
+    },
+    /**
+     * Returns invited user details for confirmation without consuming the invitation.
+     */
+    handler: async (request, reply) => {
+      try {
+        const secret = request.body.secret;
+        if (!isInvitationSecretFormat(secret)) {
+          return reply.code(400).send({ error: "Invalid invitation secret format." });
+        }
+        const invitation = await options.db.findInvitationByCodeHash(hashInvitationSecret(secret));
+        if (!invitation) {
+          if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+            return;
+          }
+          return reply.code(404).send({ error: "Invalid or expired invitation." });
+        }
+        try {
+          assertInvitationPending(invitation);
+        } catch (error) {
+          if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+            return;
+          }
+          if (handleInvitationError(reply, error)) {
+            return;
+          }
+          throw error;
+        }
+        const user = await options.db.findUserById(invitation.userId);
+        if (!user) {
+          return reply.code(404).send({ error: "Invalid or expired invitation." });
+        }
+        if (await resetInvitationThrottle(options.throttleStore, request, reply)) {
+          return;
+        }
+        return reply.send({
+          user: serializeInvitationPreviewUser(user),
+          expiresAt: invitation.expiresAt.toISOString()
+        });
+      } catch (error) {
+        if (handleDbError(reply, error) || handleInvitationError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+  routes.route({
+    method: "POST",
+    url: "/auth/invitations/redeem",
+    schema: {
+      body: redeemInvitationBodySchema,
+      response: {
+        201: createdApiTokenResponseSchema,
+        400: errorResponseSchema,
+        404: errorResponseSchema,
+        410: errorResponseSchema,
+        429: errorResponseSchema,
+        503: errorResponseSchema
+      }
+    },
+    /**
+     * Consumes a pending invitation and returns a one-time permanent API token secret.
+     */
+    handler: async (request, reply) => {
+      try {
+        const secret = request.body.secret;
+        if (!isInvitationSecretFormat(secret)) {
+          return reply.code(400).send({ error: "Invalid invitation secret format." });
+        }
+        const systemUserId = options.db.getSystemUserId();
+        if (!systemUserId) {
+          throw new Error("System user is not provisioned");
+        }
+        const tokenName = request.body.tokenName?.trim();
+        const codeHash = hashInvitationSecret(secret);
+        let redeemed;
+        try {
+          redeemed = await options.db.redeemInvitation(codeHash, tokenName ?? "", systemUserId);
+        } catch (error) {
+          if (error instanceof InvitationUnavailableError) {
+            if (await recordInvitationFailure(options.throttleStore, request, reply)) {
+              return;
+            }
+          }
+          if (handleInvitationError(reply, error)) {
+            return;
+          }
+          throw error;
+        }
+        if (await resetInvitationThrottle(options.throttleStore, request, reply)) {
+          return;
+        }
+        return reply.code(201).send({
+          token: serializeApiToken(redeemed.token),
+          secret: redeemed.secret
+        });
+      } catch (error) {
+        if (handleDbError(reply, error) || handleInvitationError(reply, error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  });
+}
+
 // src/server/routes/collections.ts
 async function registerCollectionRoutes(app, db) {
   const routes = app.withTypeProvider();
@@ -9301,10 +10833,10 @@ async function registerFolderRoutes(app, db) {
 }
 
 // src/server/routes/health.ts
-import { z as z10 } from "zod/v4";
-var healthResponseSchema = z10.object({
-  status: z10.literal("ok"),
-  version: z10.string()
+import { z as z11 } from "zod/v4";
+var healthResponseSchema = z11.object({
+  status: z11.literal("ok"),
+  version: z11.string()
 });
 async function registerHealthRoute(app, version2) {
   app.withTypeProvider().route({
@@ -9832,6 +11364,165 @@ async function runLlmCompletion(config, input) {
   return parseCompletionResponse(json);
 }
 
+// src/server/docs/docsSearch.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import path3 from "path";
+import { create, load, search } from "@orama/orama";
+import OpenAI from "openai";
+var DOCS_EMBEDDING_MODEL = "text-embedding-3-small";
+var DOCS_EMBEDDING_DIMENSIONS = 1536;
+var DEFAULT_RESULT_LIMIT = 5;
+var MAX_RESULT_LIMIT = 10;
+var DEFAULT_SIMILARITY = 0.5;
+var SNIPPET_MAX_CHARS = 600;
+var DOCS_SEARCH_SCHEMA = {
+  id: "string",
+  source: "string",
+  path: "string",
+  url: "string",
+  title: "string",
+  heading: "string",
+  content: "string",
+  embedding: `vector[${DOCS_EMBEDDING_DIMENSIONS}]`
+};
+var cachedDb = null;
+var indexUnavailable = false;
+function getDocsSearchIndexPaths(docsConfig) {
+  const paths = /* @__PURE__ */ new Set();
+  if (docsConfig?.searchIndexPath) {
+    paths.add(resolveDocsSearchIndexPath(docsConfig.searchIndexPath));
+  }
+  paths.add(DEFAULT_DOCS_SEARCH_INDEX_PATH);
+  paths.add(path3.resolve(process.cwd(), "data/docsSearchIndex.json"));
+  return [...paths];
+}
+function isDocsSearchIndexAvailable(docsConfig) {
+  return getDocsSearchIndexPaths(docsConfig).some((candidate) => existsSync2(candidate));
+}
+function truncateSnippet(content, maxChars = SNIPPET_MAX_CHARS) {
+  if (content.length <= maxChars) {
+    return content;
+  }
+  return `${content.slice(0, maxChars)}...`;
+}
+function clampResultLimit(limit) {
+  if (limit == null || !Number.isFinite(limit)) {
+    return DEFAULT_RESULT_LIMIT;
+  }
+  return Math.min(Math.max(1, Math.floor(limit)), MAX_RESULT_LIMIT);
+}
+function loadDocsSearchIndex(docsConfig, paths) {
+  if (cachedDb != null) {
+    return cachedDb;
+  }
+  if (indexUnavailable) {
+    throw new Error(
+      "Documentation search index is not available. Deploy docsSearchIndex.json to the Team Hub server."
+    );
+  }
+  const candidates = paths ?? getDocsSearchIndexPaths(docsConfig);
+  const catalogPath = candidates.find((candidate) => existsSync2(candidate));
+  if (catalogPath == null) {
+    indexUnavailable = true;
+    throw new Error(
+      "Documentation search index is not available. Deploy docsSearchIndex.json to the Team Hub server."
+    );
+  }
+  const raw = JSON.parse(readFileSync3(catalogPath, "utf8"));
+  const db = create({ schema: DOCS_SEARCH_SCHEMA });
+  load(db, raw);
+  cachedDb = db;
+  return db;
+}
+async function embedDocsQuery(query, apiKey) {
+  const client = new OpenAI({ apiKey });
+  const response = await client.embeddings.create({
+    model: DOCS_EMBEDDING_MODEL,
+    input: query
+  });
+  const embedding = response.data[0]?.embedding;
+  if (!Array.isArray(embedding) || embedding.length !== DOCS_EMBEDDING_DIMENSIONS) {
+    throw new Error("Unexpected embedding size from OpenAI.");
+  }
+  return embedding;
+}
+async function searchDocs(llmConfig, docsConfig, args) {
+  const query = args.query?.trim();
+  if (!query) {
+    throw new Error("query is required.");
+  }
+  const apiKey = llmConfig.providers.openai?.apiKey.trim();
+  if (!apiKey) {
+    throw new Error(
+      "OpenAI provider is not configured on this Team Hub. Documentation search requires an OpenAI API key."
+    );
+  }
+  const db = loadDocsSearchIndex(docsConfig);
+  const embedding = await embedDocsQuery(query, apiKey);
+  const limit = clampResultLimit(args.limit);
+  const results = search(db, {
+    mode: "vector",
+    vector: {
+      value: embedding,
+      property: "embedding"
+    },
+    similarity: DEFAULT_SIMILARITY,
+    limit,
+    ...args.source != null ? { where: { source: args.source } } : {}
+  });
+  const resolved = results instanceof Promise ? await results : results;
+  return resolved.hits.map((hit) => {
+    const document = hit.document;
+    return {
+      title: document.title,
+      heading: document.heading,
+      url: document.url,
+      source: document.source,
+      path: document.path,
+      score: hit.score,
+      snippet: truncateSnippet(document.content)
+    };
+  });
+}
+
+// src/server/llm/hubNativeTools.ts
+var HUB_NATIVE_TOOL_NAMES = ["search_docs"];
+function isHubNativeToolName(name) {
+  return HUB_NATIVE_TOOL_NAMES.includes(name);
+}
+function canExecuteHubDocsSearch(llmConfig, docsConfig) {
+  if (!llmConfig || !hasHubOpenAiProvider(llmConfig)) {
+    return false;
+  }
+  return isDocsSearchIndexAvailable(docsConfig);
+}
+function filterClientToolsForHub(tools, llmConfig, docsConfig) {
+  if (!tools || tools.length === 0) {
+    return tools;
+  }
+  if (canExecuteHubDocsSearch(llmConfig, docsConfig)) {
+    return tools;
+  }
+  const filtered = tools.filter((tool) => {
+    const name = tool.function?.name;
+    return name !== "search_docs";
+  });
+  return filtered.length > 0 ? filtered : void 0;
+}
+async function callHubNativeTool(name, args, llmConfig, docsConfig) {
+  if (name !== "search_docs") {
+    return JSON.stringify({ error: `Unknown hub-native tool: ${name}` });
+  }
+  try {
+    const parsed = args;
+    const hits = await searchDocs(llmConfig, docsConfig, parsed);
+    return JSON.stringify(hits);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Documentation search failed.";
+    return JSON.stringify({ error: message });
+  }
+}
+
 // src/server/llm/hubMcpToolNames.ts
 var HUB_MCP_TOOL_PREFIX = "hubmcp__";
 function encodeHubMcpToolName(serverIndex, toolName) {
@@ -10025,14 +11716,16 @@ function parseToolArguments(raw) {
     return {};
   }
 }
-async function runHubChatStep(config, input, deps = {}) {
+async function runHubChatStep(config, input, deps = {}, docsConfig = null) {
   const runCompletion = deps.runCompletion ?? runLlmCompletion;
   const ensureConnections = deps.ensureConnections ?? ensureHubMcpConnections;
   const listTools = deps.listTools ?? listHubMcpTools;
   const callTool = deps.callTool ?? callHubMcpTool;
+  const callNativeTool = deps.callNativeTool ?? callHubNativeTool;
   await ensureConnections(config);
   const hubTools = listTools();
-  const mergedTools = hubTools.length > 0 || (input.tools?.length ?? 0) > 0 ? [...hubTools, ...input.tools ?? []] : void 0;
+  const clientTools = filterClientToolsForHub(input.tools, config, docsConfig);
+  const mergedTools = hubTools.length > 0 || (clientTools?.length ?? 0) > 0 ? [...hubTools, ...clientTools ?? []] : void 0;
   let messages = [...input.messages];
   let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
   let lastContent = null;
@@ -10052,8 +11745,11 @@ async function runHubChatStep(config, input, deps = {}) {
         usage
       };
     }
+    const nativeCalls = toolCalls.filter((call) => isHubNativeToolName(call.name));
     const hubCalls = toolCalls.filter((call) => isHubMcpToolName(call.name));
-    const passthroughCalls = toolCalls.filter((call) => !isHubMcpToolName(call.name));
+    const passthroughCalls = toolCalls.filter(
+      (call) => !isHubNativeToolName(call.name) && !isHubMcpToolName(call.name)
+    );
     if (passthroughCalls.length > 0) {
       return {
         content: result.content,
@@ -10061,14 +11757,28 @@ async function runHubChatStep(config, input, deps = {}) {
         usage
       };
     }
+    const serverCalls = [...nativeCalls, ...hubCalls];
     messages = [
       ...messages,
       {
         role: "assistant",
         content: result.content,
-        tool_calls: hubCalls
+        tool_calls: serverCalls
       }
     ];
+    for (const call of nativeCalls) {
+      const toolResult = await callNativeTool(
+        call.name,
+        parseToolArguments(call.arguments),
+        config,
+        docsConfig
+      );
+      messages.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: toolResult
+      });
+    }
     for (const call of hubCalls) {
       const toolResult = await callTool(call.name, parseToolArguments(call.arguments));
       messages.push({
@@ -10127,7 +11837,8 @@ async function registerLlmRoutes(app, options) {
           id: model.id,
           label: model.label,
           provider: model.provider
-        }))
+        })),
+        capabilities: getHubLlmCapabilities(llm)
       });
     }
   });
@@ -10201,12 +11912,17 @@ async function registerLlmRoutes(app, options) {
       if (isNewTurn && isOverMonthlyLimit(totalTokens, user.llmMonthlyTokenLimit)) {
         return sendMonthlyLimitExceeded(reply);
       }
-      const result = await runHubChatStep(llm, {
-        model,
-        messages,
-        tools,
-        systemPrompt
-      });
+      const result = await runHubChatStep(
+        llm,
+        {
+          model,
+          messages,
+          tools,
+          systemPrompt
+        },
+        {},
+        options.getDocs()
+      );
       const catalogModel = getHubModelById(model);
       if (!catalogModel) {
         throw new Error(`Unknown hub model: ${model}`);
@@ -10240,10 +11956,10 @@ async function registerLlmRoutes(app, options) {
 }
 
 // src/server/routes/schemas/plugins.ts
-import { z as z11 } from "zod/v4";
-var pluginSourcesResponseSchema = z11.object({
-  catalogs: z11.array(z11.string()),
-  trusted: z11.array(z11.string())
+import { z as z12 } from "zod/v4";
+var pluginSourcesResponseSchema = z12.object({
+  catalogs: z12.array(z12.string()),
+  trusted: z12.array(z12.string())
 });
 
 // src/server/routes/plugins.ts
@@ -10337,6 +12053,10 @@ function createBearerAuthHook(db, throttleStore) {
 // src/server/routes/index.ts
 async function registerPublicRoutes(app, options) {
   await registerHealthRoute(app, options.version);
+  await registerInvitationRoutes(app, {
+    db: options.db,
+    throttleStore: options.throttleStore
+  });
 }
 async function registerProtectedRoutes(app, options) {
   registerBearerAuthDecorator(app);
@@ -10353,7 +12073,11 @@ async function registerProtectedRoutes(app, options) {
   await registerFolderRoutes(app, options.db);
   await registerRequestRoutes(app, options.db);
   await registerRunResultRoutes(app, options.db);
-  await registerLlmRoutes(app, { db: options.db, getLlm: options.getLlm });
+  await registerLlmRoutes(app, {
+    db: options.db,
+    getLlm: options.getLlm,
+    getDocs: options.getDocs
+  });
   await registerPluginsRoutes(app, { getPlugins: options.getPlugins });
 }
 async function registerRoutes(app, options) {
@@ -10388,6 +12112,7 @@ async function createServer(ctxOrConfig, options = {}) {
     throttleStore,
     getLlm: ctx ? () => ctx.getLlm() : () => legacyConfig?.llm ?? null,
     getPlugins: ctx ? () => ctx.getPlugins() : () => legacyConfig?.plugins ?? null,
+    getDocs: ctx ? () => ctx.getDocs() : () => legacyConfig?.docs ?? null,
     reloadConfig: options.reloadConfig ?? (async () => ({ sections: [] }))
   });
   return app;
@@ -10574,7 +12299,8 @@ function createRuntimeContext(config, configPath) {
     dbHolder: { underlying: createDatabase(config.db) },
     throttleHolder: { underlying: createThrottleStore(config.redis) },
     llm: config.llm,
-    plugins: config.plugins
+    plugins: config.plugins,
+    docs: config.docs
   };
   const ctx = {
     configPath: state.configPath,
@@ -10588,6 +12314,7 @@ function createRuntimeContext(config, configPath) {
     throttleStore: createSwappableProxy(state.throttleHolder),
     getLlm: () => state.llm,
     getPlugins: () => state.plugins,
+    getDocs: () => state.docs,
     logger: createLogger(config.logging)
   };
   runtimeContextStates.set(ctx, state);
@@ -10661,6 +12388,8 @@ async function reloadRuntimeConfig(ctx) {
   sections.push({ section: "llm", status: "reloaded" });
   state.plugins = nextConfig.plugins;
   sections.push({ section: "plugins", status: "reloaded" });
+  state.docs = nextConfig.docs;
+  sections.push({ section: "docs", status: "reloaded" });
   sections.push(reloadServerSection(state, nextConfig));
   return { sections };
 }