@fairmint/captable-ai 0.1.13 → 0.1.15

package/README.md

@@ -30,8 +30,12 @@ the login code back into the terminal. Credentials are stored in `~/.captable-ai
 
 ```bash
 captable-ai login
-captable-ai company use "Acme Inc"          # if you have more than one
+captable-ai onboarding status
+captable-ai onboarding setup ...            # only when you have no workspace
+captable-ai company use "Acme Inc"           # if you have more than one
+captable-ai import start
 captable-ai documents upload ./docs/*.pdf
+captable-ai import status <session-id>
 captable-ai documents trigger-extraction    # once all docs are CLASSIFIED
 captable-ai documents list                  # poll until PROCESSED
 captable-ai commit --dry-run                 # preview
@@ -84,6 +88,8 @@ automated, but a few habits make extraction faster and more accurate:
 |---------|-------------|
 | `login` / `logout` | Authenticate / clear stored credentials |
 | `auth status` | Show the current session |
+| `onboarding status\|setup` | Inspect onboarding or create the first workspace |
+| `import start\|status` | Start an import session and poll existing document processing |
 | `company list\|use\|current\|create\|delete` | Manage and select the active company |
 | `documents upload\|list\|download\|delete` | Manage source documents |
 | `documents trigger-extraction\|cancel-extraction\|restart-extraction\|reprocess` | Control the OCF extraction pipeline |

package/dist/index.js

@@ -170,8 +170,8 @@ function parsePortals(body) {
   if (!portals.every(isStoredPortal)) return null;
   return portals;
 }
-async function refreshPortalsIfStale(creds) {
-  if (creds.portalsLastFetchedAt && Date.now() - Date.parse(creds.portalsLastFetchedAt) < PORTALS_TTL_MS) {
+async function refreshPortalsIfStale(creds, force = false) {
+  if (!force && creds.portalsLastFetchedAt && Date.now() - Date.parse(creds.portalsLastFetchedAt) < PORTALS_TTL_MS) {
     return creds;
   }
   if (isTokenExpired(creds.accessToken)) {
@@ -508,6 +508,108 @@ var COMMAND_REGISTRY = [
     requiresPortal: false,
     flags: [{ name: "yes", description: "Skip the confirmation prompt.", type: "boolean" }]
   },
+  {
+    name: "onboarding status",
+    group: "onboarding",
+    description: "Show the next first-workspace or import action. Works for authenticated users with zero companies.",
+    usage: "captable-ai onboarding status [--session <import-session-id>] [--json]",
+    requiresAuth: true,
+    requiresPortal: false,
+    flags: [
+      {
+        name: "session",
+        description: "Inspect this import session instead of local workspace state.",
+        type: "string"
+      }
+    ]
+  },
+  {
+    name: "onboarding setup",
+    group: "onboarding",
+    description: "Idempotently create the authenticated user's first production workspace. Only --accept-terms is required; the company profile is read from uploaded documents.",
+    usage: "captable-ai onboarding setup --accept-terms [--legal-name <name>] [--company-type <type>] [--country <code>] [--role <role>] [--other-role <role>] [--cap-table-source <source>] [--other-cap-table-source <source>] [--stakeholder-count <bucket>] [--json]",
+    requiresAuth: true,
+    requiresPortal: false,
+    flags: [
+      {
+        name: "accept-terms",
+        description: "Confirm acceptance of Fairmint's Terms of Service (required).",
+        type: "boolean"
+      },
+      {
+        name: "legal-name",
+        description: "Company name. Left unset until you or document extraction supplies one.",
+        type: "string"
+      },
+      {
+        name: "company-type",
+        description: "Legal entity type. Left unrecorded when omitted.",
+        type: "string",
+        enum: ["us_c_corporation", "us_llc", "foreign_entity", "not_incorporated"]
+      },
+      {
+        name: "country",
+        description: "ISO 3166-1 alpha-2 code. Only with --company-type foreign_entity.",
+        type: "string"
+      },
+      {
+        name: "role",
+        description: "Your role at the company.",
+        type: "string",
+        enum: [
+          "CEO",
+          "COO",
+          "CMO",
+          "CFO",
+          "CTO",
+          "CRO",
+          "Director",
+          "Founder",
+          "co-founder",
+          "co-CEO",
+          "other"
+        ]
+      },
+      {
+        name: "other-role",
+        description: "Free-text role. Required when --role other.",
+        type: "string"
+      },
+      {
+        name: "cap-table-source",
+        description: "Where the cap table is maintained today.",
+        type: "string",
+        enum: ["none", "spreadsheet", "carta", "pulley", "angellist", "other"]
+      },
+      {
+        name: "other-cap-table-source",
+        description: "Free-text source. Required when --cap-table-source other.",
+        type: "string"
+      },
+      {
+        name: "stakeholder-count",
+        description: "Approximate number of stakeholders on the cap table.",
+        type: "string",
+        enum: ["1_10", "11_25", "26_50", "50_100", "100_plus"]
+      }
+    ]
+  },
+  {
+    name: "import start",
+    group: "onboarding",
+    description: "Start or reuse a secure import session for existing document upload APIs.",
+    usage: "captable-ai import start [--json]",
+    requiresAuth: true,
+    requiresPortal: true
+  },
+  {
+    name: "import status",
+    group: "onboarding",
+    description: "Show import processing progress and the next existing-pipeline action.",
+    usage: "captable-ai import status <session-id> [--json]",
+    requiresAuth: true,
+    requiresPortal: false
+  },
   {
     name: "summary",
     group: "captable",
@@ -1184,7 +1286,7 @@ var COMMAND_REGISTRY = [
   }
 ];
 async function runCommands(_args) {
-  printJson({ schemaVersion: "9", version: "0.0.1", commands: COMMAND_REGISTRY });
+  printJson({ schemaVersion: "10", version: "0.0.1", commands: COMMAND_REGISTRY });
 }
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
@@ -16598,60 +16700,109 @@ var hasControlCharacter = (value) => Array.from(value).some((character) => {
 });
 var legalNameSchema = shortTextSchema(255).refine((value) => !hasControlCharacter(value), "Legal name cannot contain control characters").describe("Confirmed legal name of the company.");
 var countryCodeSchema = external_exports.string().trim().transform((value) => value.toUpperCase()).pipe(external_exports.string().regex(/^[A-Z]{2}$/, "Must be an ISO 3166-1 alpha-2 country code")).describe("ISO 3166-1 alpha-2 country of incorporation. Required for foreign entities.");
-var roleSchema = external_exports.discriminatedUnion("role", [
-  external_exports.object({
-    role: external_exports.enum(ONBOARDING_ROLES).describe("Founder's role at the company."),
-    otherRole: external_exports.never().optional().describe("Omit unless role is other.")
-  }),
-  external_exports.object({
-    role: external_exports.literal(ONBOARDING_OTHER_ROLE).describe("Founder's role at the company."),
-    otherRole: shortTextSchema(100).describe("Free-text role when role is other.")
-  })
-]);
-var capTableSourceSchema = external_exports.discriminatedUnion("capTableSource", [
-  external_exports.object({
-    capTableSource: external_exports.enum([
-      ONBOARDING_CAP_TABLE_SOURCES.NONE,
-      ONBOARDING_CAP_TABLE_SOURCES.SPREADSHEET,
-      ONBOARDING_CAP_TABLE_SOURCES.CARTA,
-      ONBOARDING_CAP_TABLE_SOURCES.PULLEY,
-      ONBOARDING_CAP_TABLE_SOURCES.ANGELLIST
-    ]).describe("Where the current cap table is maintained."),
-    otherCapTableSource: external_exports.never().optional().describe("Omit unless capTableSource is other.")
-  }),
-  external_exports.object({
-    capTableSource: external_exports.literal(ONBOARDING_CAP_TABLE_SOURCES.OTHER).describe("Where the current cap table is maintained."),
-    otherCapTableSource: shortTextSchema(100).describe("Free-text cap table tool when capTableSource is other.")
-  })
-]);
-var commonSetupSchema = external_exports.object({
-  legalName: legalNameSchema,
-  stakeholderCount: external_exports.enum(ONBOARDING_STAKEHOLDER_COUNT_BUCKETS).describe("Approximate number of stakeholders on the cap table."),
-  termsAccepted: external_exports.literal(true).describe("Whether the user accepted Fairmint's Terms of Service; must be true.")
-}).and(roleSchema).and(capTableSourceSchema);
-var companySchema = external_exports.discriminatedUnion("companyType", [
-  external_exports.object({
-    companyType: external_exports.enum([ONBOARDING_COMPANY_TYPES.US_C_CORPORATION, ONBOARDING_COMPANY_TYPES.US_LLC]).describe("Confirmed company type."),
-    country: external_exports.never().optional().describe("Omit for US companies.")
-  }),
-  external_exports.object({
-    companyType: external_exports.literal(ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY).describe("Confirmed company type."),
-    country: countryCodeSchema.refine((country) => country !== "US", {
-      message: "Foreign entities must use a non-US country"
-    }).describe("ISO 3166-1 alpha-2 country of incorporation. Required for foreign entities.")
-  }),
-  external_exports.object({
-    companyType: external_exports.literal(ONBOARDING_COMPANY_TYPES.NOT_INCORPORATED).describe("Confirmed company type."),
-    country: external_exports.never().optional().describe("Omit until the company is incorporated.")
-  })
-]);
-var onboardingWorkspaceSetupInputSchema = commonSetupSchema.and(companySchema);
+var onboardingWorkspaceSetupInputSchema = external_exports.object({
+  termsAccepted: external_exports.literal(true).describe("Whether the user accepted Fairmint's Terms of Service; must be true."),
+  legalName: legalNameSchema.optional(),
+  companyType: external_exports.enum([
+    ONBOARDING_COMPANY_TYPES.US_C_CORPORATION,
+    ONBOARDING_COMPANY_TYPES.US_LLC,
+    ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY,
+    ONBOARDING_COMPANY_TYPES.NOT_INCORPORATED
+  ]).optional().describe("Confirmed company type. Left unrecorded when omitted."),
+  country: countryCodeSchema.optional(),
+  role: external_exports.enum([...ONBOARDING_ROLES, ONBOARDING_OTHER_ROLE]).optional().describe("Founder's role at the company."),
+  otherRole: shortTextSchema(100).optional().describe("Free-text role when role is other."),
+  capTableSource: external_exports.enum([
+    ONBOARDING_CAP_TABLE_SOURCES.NONE,
+    ONBOARDING_CAP_TABLE_SOURCES.SPREADSHEET,
+    ONBOARDING_CAP_TABLE_SOURCES.CARTA,
+    ONBOARDING_CAP_TABLE_SOURCES.PULLEY,
+    ONBOARDING_CAP_TABLE_SOURCES.ANGELLIST,
+    ONBOARDING_CAP_TABLE_SOURCES.OTHER
+  ]).optional().describe("Where the current cap table is maintained."),
+  otherCapTableSource: shortTextSchema(100).optional().describe("Free-text cap table tool when capTableSource is other."),
+  stakeholderCount: external_exports.enum(ONBOARDING_STAKEHOLDER_COUNT_BUCKETS).optional().describe("Approximate number of stakeholders on the cap table.")
+}).superRefine((value, ctx) => {
+  if (value.companyType === ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY) {
+    if (value.country === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["country"],
+        message: "Foreign entities must provide a country of incorporation"
+      });
+    } else if (value.country === "US") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["country"],
+        message: "Foreign entities must use a non-US country"
+      });
+    }
+  } else if (value.country !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["country"],
+      message: "Omit country unless companyType is foreign_entity"
+    });
+  }
+  if (value.role === ONBOARDING_OTHER_ROLE) {
+    if (value.otherRole === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["otherRole"],
+        message: "Describe the role when role is other"
+      });
+    }
+  } else if (value.otherRole !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["otherRole"],
+      message: "Omit otherRole unless role is other"
+    });
+  }
+  if (value.capTableSource === ONBOARDING_CAP_TABLE_SOURCES.OTHER) {
+    if (value.otherCapTableSource === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["otherCapTableSource"],
+        message: "Describe the cap table source when capTableSource is other"
+      });
+    }
+  } else if (value.otherCapTableSource !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["otherCapTableSource"],
+      message: "Omit otherCapTableSource unless capTableSource is other"
+    });
+  }
+});
+function dropOrphanOnboardingSetupDetails(input) {
+  const next = { ...input };
+  if (next.companyType !== void 0 && next.companyType !== ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY) {
+    delete next.country;
+  }
+  if (next.role !== void 0 && next.role !== ONBOARDING_OTHER_ROLE) {
+    delete next.otherRole;
+  }
+  if (next.capTableSource !== void 0 && next.capTableSource !== ONBOARDING_CAP_TABLE_SOURCES.OTHER) {
+    delete next.otherCapTableSource;
+  }
+  return next;
+}
+function resolveOnboardingCompanyProfile(input) {
+  const companyType = input.companyType ?? null;
+  const country = companyType === null ? null : companyType === ONBOARDING_COMPANY_TYPES.FOREIGN_ENTITY ? input.country ?? null : ONBOARDING_COMPANY_TYPE_TO_ISSUER[companyType].countryOfFormation;
+  return {
+    legalName: input.legalName ?? null,
+    companyType,
+    country
+  };
+}
 var onboardingWorkspaceSetupResultSchema = external_exports.object({
   portalId: external_exports.uuid().describe("ID of the user's first production workspace."),
   state: external_exports.literal(ONBOARDING_WORKSPACE_STATES.WORKSPACE_READY).describe("Workspace is created or reused and ready for import."),
   created: external_exports.boolean().describe("True when this request inserted a new portal."),
-  commitReady: external_exports.boolean().describe("True when the draft issuer has formation date and country of formation."),
-  commitBlockers: external_exports.array(external_exports.enum(["formation_date", "country_of_formation"])).describe("Issuer fields that still block a live commit."),
+  commitReady: external_exports.boolean().describe("True when the draft issuer has legal name, formation date, and country of formation."),
+  commitBlockers: external_exports.array(external_exports.enum(["legal_name", "formation_date", "country_of_formation"])).describe("Issuer fields that still block a live commit."),
   session: external_exports.object({
     action: external_exports.enum([
       ONBOARDING_SESSION_ACTIONS.NONE,
@@ -16982,6 +17133,13 @@ async function refreshTokens(creds) {
   await writeCredentials(updated);
   return updated;
 }
+async function refreshSession() {
+  const credentials = await readCredentials();
+  if (!credentials) {
+    exitWithError("Not logged in. Run: captable-ai login", "AUTH_REQUIRED", void 0, EXIT.AUTH);
+  }
+  return refreshTokens(credentials);
+}
 async function getAuthHeaders(softFail = false) {
   let creds = await readCredentials();
   if (!creds) return {};
@@ -17194,6 +17352,40 @@ function argvRequestsHelp(argv) {
 }
 
 // src/help-text.ts
+var HELP_ONBOARDING = `onboarding \u2014 Create a first workspace and inspect next steps
+
+Usage:
+  captable-ai onboarding status [--session <import-session-id>] [--json]
+  captable-ai onboarding setup --accept-terms [--legal-name <name>] [options] [--json]
+
+Accepting the Terms is all that is required. The legal name, entity type, and
+country are read from the documents you upload, so you can skip them here and
+start importing right away.
+
+Setup values:
+  --accept-terms        Confirm acceptance of Fairmint's Terms of Service (required)
+  --legal-name          Company name. Left unset until you or document
+                        extraction supplies one; commit stays blocked until then.
+  --company-type        us_c_corporation | us_llc | foreign_entity | not_incorporated
+  --country             ISO country code (only with --company-type foreign_entity)
+  --role                CEO | COO | CMO | CFO | CTO | CRO | Director | Founder |
+                        co-founder | co-CEO | other
+  --other-role          Required when --role other
+  --cap-table-source    none | spreadsheet | carta | pulley | angellist | other
+  --other-cap-table-source  Required when --cap-table-source other
+  --stakeholder-count   1_10 | 11_25 | 26_50 | 50_100 | 100_plus`;
+var HELP_IMPORT = `import \u2014 Start and inspect a secure document-import session
+
+Usage:
+  captable-ai import start [--json]
+  captable-ai import status <session-id> [--json]
+
+For local files, the recommended data path remains:
+  captable-ai documents upload <file...>
+
+It performs prepare \u2192 direct presigned S3 PUT \u2192 confirm without routing file bytes
+through the CaptableAI API. After processing finishes, review drafts with
+\`objects list\` and commit with the existing \`commit --dry-run\` / \`commit --all\` commands.`;
 var HELP_AUTH = `auth \u2014 Session information
 
 Usage:
@@ -20767,6 +20959,344 @@ async function runObjectsVersions(args, rawArgv) {
   }
 }
 
+// src/commands/onboarding.ts
+function nextAction(id, label, command) {
+  return command ? { id, label, required: true, command } : { id, label, required: true };
+}
+async function runOnboardingStatus(args) {
+  validateFlags(args, { flags: ["session"], booleans: [] });
+  const sessionId = typeof args.flags.session === "string" ? args.flags.session : void 0;
+  if (sessionId) {
+    await runImportStatus(parseArgs([sessionId]));
+    return;
+  }
+  const credentials = await readCredentials();
+  if (!credentials) {
+    exitWithError("Not logged in. Run: captable-ai login", "AUTH_REQUIRED", void 0, EXIT.AUTH);
+  }
+  const active = resolveActiveCompany(await readConfig(), credentials.portals);
+  const data = credentials.portals.length === 0 ? {
+    state: ONBOARDING_STATES.NEEDS_COMPANY_SETUP,
+    nextActions: [
+      nextAction(
+        "setup_workspace",
+        "Create your first workspace",
+        "captable-ai onboarding setup --accept-terms"
+      )
+    ],
+    question: "Do you accept Fairmint's Terms of Service? That is all we need to open your workspace."
+  } : !active ? {
+    state: ONBOARDING_STATES.NEEDS_COMPANY_SELECTION,
+    companies: credentials.portals,
+    nextActions: [
+      nextAction(
+        "select_company",
+        "Choose the company to import into",
+        "captable-ai company use <id-or-name>"
+      )
+    ],
+    question: "Which company should receive this cap table import?"
+  } : {
+    state: ONBOARDING_STATES.READY_TO_IMPORT,
+    company: active,
+    nextActions: [
+      nextAction(
+        "start_import",
+        "Start a secure import session",
+        "captable-ai import start"
+      ),
+      nextAction(
+        "upload_cli",
+        "Upload local documents directly to S3",
+        "captable-ai documents upload <file...>"
+      )
+    ],
+    question: `Should I start a secure import session for ${active.name ?? active.id}?`
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printKeyValue([
+    ["State", data.state],
+    ["Question", data.question]
+  ]);
+  for (const action of data.nextActions) {
+    printLine(`  Next: ${String(action.command)}`);
+  }
+}
+function setupInput(args) {
+  const flagMap = {
+    legalName: "legal-name",
+    companyType: "company-type",
+    country: "country",
+    role: "role",
+    otherRole: "other-role",
+    capTableSource: "cap-table-source",
+    otherCapTableSource: "other-cap-table-source",
+    stakeholderCount: "stakeholder-count"
+  };
+  const input = {
+    termsAccepted: hasFlag(args, "accept-terms")
+  };
+  for (const [field, flag] of Object.entries(flagMap)) {
+    const value = args.flags[flag];
+    if (typeof value === "string") input[field] = value;
+  }
+  return input;
+}
+async function runOnboardingSetup(args) {
+  validateFlags(args, {
+    flags: [
+      "legal-name",
+      "company-type",
+      "country",
+      "role",
+      "other-role",
+      "cap-table-source",
+      "other-cap-table-source",
+      "stakeholder-count"
+    ],
+    booleans: ["accept-terms"]
+  });
+  const parsed = onboardingWorkspaceSetupInputSchema.safeParse(
+    dropOrphanOnboardingSetupDetails(setupInput(args))
+  );
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((issue2) => ({
+      path: issue2.path.join("."),
+      message: issue2.message
+    }));
+    exitWithError(
+      "Company setup answers are invalid. Only `--accept-terms` is required on its own, but some answers require a partner flag: `--company-type foreign_entity` needs `--country`, `--role other` needs `--other-role`, and `--cap-table-source other` needs `--other-cap-table-source`. Run `captable-ai onboarding setup --help` for accepted values.",
+      "VALIDATION_FAILED",
+      details,
+      EXIT.VALIDATION
+    );
+  }
+  const input = parsed.data;
+  const { legalName } = resolveOnboardingCompanyProfile(input);
+  const workspaceLabel = legalName ?? "your new workspace";
+  const response = await apiRequest("/onboarding/workspace", { method: "POST", body: input });
+  const result = onboardingWorkspaceSetupResultSchema.safeParse(response.data ?? response);
+  if (!result.success) {
+    exitWithError(
+      "Unexpected onboarding setup response from server.",
+      "SERVER_ERROR",
+      void 0,
+      EXIT.SERVER_ERROR
+    );
+  }
+  if (result.data.session.action === ONBOARDING_SESSION_ACTIONS.REFRESH) {
+    const refreshed = await refreshSession();
+    const withPortals = await refreshPortalsIfStale(refreshed, true);
+    const portal = withPortals.portals.find(({ id }) => id === result.data.portalId);
+    if (!portal) {
+      exitWithError(
+        "Workspace was created, but the refreshed session did not include it.",
+        "SESSION_REFRESH_FAILED",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+    }
+    await setActivePortal(portal);
+    const data2 = {
+      ...result.data,
+      state: ONBOARDING_STATES.READY_TO_IMPORT,
+      nextActions: [
+        nextAction("start_import", "Start the secure document import", "captable-ai import start")
+      ],
+      question: "Your workspace is ready. Start the document import now?"
+    };
+    if (isJsonMode()) {
+      printJson({ data: data2 });
+      return;
+    }
+    printSuccess(`Workspace ready: ${workspaceLabel} (${result.data.portalId})`);
+    printLine("Start the import: captable-ai import start");
+    return;
+  }
+  const data = {
+    ...result.data,
+    nextActions: [
+      nextAction("reconnect", "Reconnect to activate the workspace", "captable-ai login"),
+      nextAction("start_import", "Start an import after reconnecting", "captable-ai import start")
+    ],
+    question: "Your workspace is ready. Please run `captable-ai login` again, then start the import."
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printSuccess(`Workspace ready: ${workspaceLabel} (${result.data.portalId})`);
+  printLine("Reconnect so your session can access it: captable-ai login");
+}
+async function runImportStart(args) {
+  validateFlags(args, { flags: [], booleans: [] });
+  const portalId = await getActivePortalId();
+  const response = await apiRequest(
+    "/import-sessions",
+    {
+      method: "POST",
+      body: { portalId }
+    }
+  );
+  const session = response.data?.session;
+  if (!session?.id) {
+    exitWithError(
+      "Unexpected import session response from server.",
+      "SERVER_ERROR",
+      void 0,
+      EXIT.SERVER_ERROR
+    );
+  }
+  const data = {
+    ...response.data,
+    nextActions: [
+      nextAction(
+        "upload_cli",
+        "Upload local documents directly to S3",
+        "captable-ai documents upload <file...>"
+      ),
+      nextAction(
+        "check_status",
+        "Check import progress",
+        `captable-ai import status ${session.id}`
+      )
+    ],
+    question: "Which cap table documents should be uploaded with `documents upload`?"
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printSuccess(`Import session ${response.data?.reused ? "reused" : "started"}: ${session.id}`);
+  printLine("Upload documents: captable-ai documents upload <file...>");
+  printLine(`Check progress: captable-ai import status ${session.id}`);
+}
+var TERMINAL_DOCUMENT_STATUSES = /* @__PURE__ */ new Set(["PROCESSED", "COMMITTED", "FAILED", "CANCELLED"]);
+function documentsForImportSession(documents, sessionCreatedAt) {
+  if (typeof sessionCreatedAt !== "string" || sessionCreatedAt.length === 0) return [];
+  return documents.filter(
+    (document) => typeof document.lastActivityAt === "string" && document.lastActivityAt >= sessionCreatedAt
+  );
+}
+function summarizeImportDocuments(documents) {
+  const statuses = documents.map((document) => (document.status ?? "").toUpperCase());
+  const failed = statuses.filter((status) => ["FAILED", "CANCELLED"].includes(status)).length;
+  const classified = statuses.filter((status) => status === "CLASSIFIED").length;
+  const pendingUpload = statuses.filter((status) => status === "PENDING_UPLOAD").length;
+  const processing = statuses.filter(
+    (status) => status !== "" && !TERMINAL_DOCUMENT_STATUSES.has(status) && status !== "CLASSIFIED" && status !== "PENDING_UPLOAD"
+  ).length;
+  return {
+    total: documents.length,
+    processing,
+    classified,
+    pendingUpload,
+    failed,
+    complete: documents.length - failed - processing - classified - pendingUpload
+  };
+}
+async function runImportStatus(args) {
+  validateFlags(args, { flags: [], booleans: [] });
+  const sessionId = args.positional[0];
+  if (!sessionId) {
+    exitWithUsage(
+      "Import session ID is required.",
+      "Usage: captable-ai import status <session-id> [--json]"
+    );
+  }
+  const response = await apiRequest(
+    `/import-sessions/${encodeURIComponent(sessionId)}/status`
+  );
+  const documents = documentsForImportSession(
+    response.data?.processing?.documents ?? [],
+    response.data?.session?.createdAt
+  );
+  const summary = summarizeImportDocuments(documents);
+  const sessionState = response.data?.session?.state;
+  if (documents.length > 0 && summary.processing === 0 && summary.classified === 0 && summary.pendingUpload === 0 && summary.failed === 0 && sessionState !== "completed") {
+    const completed = await apiRequest(
+      `/import-sessions/${encodeURIComponent(sessionId)}/complete`,
+      {
+        method: "POST",
+        body: {}
+      }
+    );
+    if (response.data && completed.data?.session) {
+      response.data.session = { ...response.data.session, ...completed.data.session };
+    }
+  }
+  const state = documents.length === 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.processing > 0 ? ONBOARDING_STATES.PROCESSING : summary.classified > 0 || summary.pendingUpload > 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.failed > 0 ? ONBOARDING_STATES.BLOCKED : ONBOARDING_STATES.NEEDS_REVIEW;
+  const nextActions = documents.length === 0 || summary.pendingUpload > 0 ? [
+    nextAction(
+      "upload_cli",
+      "Upload local documents directly to S3",
+      "captable-ai documents upload <file...>"
+    ),
+    ...summary.classified > 0 ? [
+      nextAction(
+        "trigger_extraction",
+        "Start OCF extraction for classified documents",
+        "captable-ai documents trigger-extraction"
+      )
+    ] : []
+  ] : summary.classified > 0 ? [
+    nextAction(
+      "trigger_extraction",
+      "Start OCF extraction for classified documents",
+      "captable-ai documents trigger-extraction"
+    )
+  ] : summary.processing > 0 ? [
+    nextAction(
+      "check_status",
+      "Check import progress again",
+      `captable-ai import status ${sessionId}`
+    )
+  ] : summary.failed > 0 ? [
+    nextAction(
+      "review_failures",
+      "Review failed documents",
+      "captable-ai documents list --status FAILED"
+    )
+  ] : [
+    nextAction(
+      "review_drafts",
+      "Review extracted drafts",
+      "captable-ai objects list --status draft --all"
+    ),
+    nextAction(
+      "preview_commit",
+      "Preview the first commit",
+      "captable-ai commit --dry-run"
+    ),
+    nextAction("confirm_commit", "Commit reviewed drafts", "captable-ai commit --all")
+  ];
+  const data = {
+    ...response.data,
+    state,
+    summary,
+    nextActions
+  };
+  if (isJsonMode()) {
+    printJson({ data });
+    return;
+  }
+  printKeyValue([
+    ["Session", sessionId],
+    ["State", data.state],
+    ["Documents", summary.total],
+    ["Classified", summary.classified],
+    ["Processing", summary.processing],
+    ["Complete", summary.complete],
+    ["Failed", summary.failed]
+  ]);
+  for (const action of nextActions) {
+    printLine(`  Next: ${String(action.command)}`);
+  }
+}
+
 // src/commands/pro-forma.ts
 var SCENARIO_TYPES2 = ["financing", "convertible", "warrant", "option-pool"];
 function buildScenarioBody(type, args) {
@@ -21597,7 +22127,9 @@ var PROFILE_AWARE_COMMANDS = /* @__PURE__ */ new Set([
   "company",
   "documents",
   "export",
+  "import",
   "objects",
+  "onboarding",
   "pro-forma",
   "register",
   "logs",
@@ -21621,6 +22153,12 @@ Company:
   company create            Create a test portal (super admin)
   company delete <id>       Delete a test portal (dev only, super admin)
 
+Onboarding:
+  onboarding status         Show the next setup/import action (works with zero companies)
+  onboarding setup          Create the first production workspace
+  import start              Start or reuse a document import session
+  import status <id>        Check import processing via existing document APIs
+
 Cap Table (read):
   summary                   Full cap table snapshot (capitalization, stakeholders, metrics)
                              Options: --as-of, --include-pending, --skip-stakeholders, --page
@@ -21897,6 +22435,50 @@ async function main() {
       case "company":
         await routeCompany(positionalArgs);
         break;
+      case "onboarding":
+        if (isHelpToken(sub) || argvRequestsHelp(positionalArgs.slice(2))) {
+          process.stdout.write(`${HELP_ONBOARDING}
+`);
+          process.exit(0);
+        }
+        switch (sub) {
+          case "status":
+            await runOnboardingStatus(parseArgs(positionalArgs.slice(2)));
+            break;
+          case "setup":
+            await runOnboardingSetup(parseArgs(positionalArgs.slice(2)));
+            break;
+          default:
+            exitWithError(
+              `Unknown onboarding command: ${sub ?? "(none)"}. Try: onboarding status | setup`,
+              "UNKNOWN_COMMAND",
+              void 0,
+              EXIT.USAGE
+            );
+        }
+        break;
+      case "import":
+        if (isHelpToken(sub) || argvRequestsHelp(positionalArgs.slice(2))) {
+          process.stdout.write(`${HELP_IMPORT}
+`);
+          process.exit(0);
+        }
+        switch (sub) {
+          case "start":
+            await runImportStart(parseArgs(positionalArgs.slice(2)));
+            break;
+          case "status":
+            await runImportStatus(parseArgs(positionalArgs.slice(2)));
+            break;
+          default:
+            exitWithError(
+              `Unknown import command: ${sub ?? "(none)"}. Try: import start | status`,
+              "UNKNOWN_COMMAND",
+              void 0,
+              EXIT.USAGE
+            );
+        }
+        break;
       case "summary":
         if (argvRequestsHelp(positionalArgs.slice(1))) {
           process.stdout.write(`${HELP_SUMMARY}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairmint/captable-ai",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Agent-native CLI for Captable AI — manage companies, upload documents, run OCF extraction, and commit cap tables from the terminal.",
   "keywords": [
     "captable",