@fairmint/captable-ai 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fairmint, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @fairmint/captable-ai
+
+Agent-native command-line interface for [Captable AI](https://captable.ai). Manage
+companies, upload documents, run OCF (Open Cap Format) extraction, review and edit
+extracted objects, and commit cap tables — all from your terminal or an AI agent.
+
+Built for both humans and AI agents: every command supports `--json` for structured,
+parseable output, uses a stable exit-code taxonomy, and rejects unknown flags with
+helpful errors.
+
+## Installation
+
+```bash
+npm install -g @fairmint/captable-ai
+```
+
+This exposes two binaries: `captable-ai` and the short alias `cai`. Requires Node.js >= 20.
+
+## Authentication
+
+```bash
+captable-ai login
+```
+
+Opens your browser to authenticate. After approving, click "Finish in browser" or paste
+the login code back into the terminal. Credentials are stored in `~/.captable-ai/`. Use
+`captable-ai logout` to clear them and `captable-ai auth status` to inspect the session.
+
+## Quickstart
+
+```bash
+captable-ai login
+captable-ai company use "Acme Inc"          # if you have more than one
+captable-ai documents upload ./docs/*.pdf
+captable-ai documents trigger-extraction    # once all docs are CLASSIFIED
+captable-ai documents list                  # poll until PROCESSED
+captable-ai commit --dry-run                 # preview
+captable-ai commit --all                     # commit all drafts (or --objects id1,id2)
+captable-ai summary
+```
+
+## Uploading documents — the optimal flow
+
+CaptableAI builds your cap table by reading your legal documents. The pipeline is
+automated, but a few habits make extraction faster and more accurate:
+
+1. **Upload everything first.** Add all of your cap table documents up front, in one
+   batch where possible — incorporation docs, SAFEs, stock and option agreements, board
+   consents. Supported: PDF, DOCX, XLSX, DOC, and images, up to 50 MB per file via the CLI.
+   `captable-ai documents upload ./docs/*.pdf`
+2. **Wait for classification.** Each document is OCR'd and classified (type + effective
+   date). Don't trigger extraction until every document shows `CLASSIFIED`.
+   `captable-ai documents list`
+3. **Check the classification dates.** The effective date set during classification
+   determines processing order. Fix a wrong date before triggering extraction:
+   `captable-ai documents classification-update`
+4. **Trigger extraction once.** Extraction does **not** start automatically for CLI
+   uploads — run it a single time after all documents are classified.
+   `captable-ai documents trigger-extraction`
+5. **Let the FIFO queue run.** Documents are extracted one at a time, in ascending order
+   of their classification date (earliest first), so later events build on earlier ones.
+   Expect a few minutes per document.
+6. **Validation runs automatically.** Once the last document finishes extraction, a
+   company-wide validator runs across all objects to repair cross-document issues — no
+   action needed.
+7. **Review, then commit.** When all documents reach `PROCESSED`, review and commit.
+   `captable-ai objects list --status draft` → `captable-ai commit --dry-run` → `captable-ai commit --all`
+   (commit requires `--all` or `--objects id1,id2,...`).
+
+**Be patient — and when to retry:**
+
+- Extraction and validation are asynchronous. Poll `captable-ai documents list` (or
+  `captable-ai documents processing-status`) rather than re-triggering — duplicate
+  triggers just slow things down.
+- Per-document extraction and the validator are only considered stuck after roughly **15
+  minutes** of no progress. Wait out that window before assuming a problem.
+- Retry commands are a last resort, used only after the wait window: `documents reprocess`
+  (a `FAILED` doc), `documents cancel-extraction` / `documents restart-extraction` (a
+  genuinely stuck doc), or `retrigger-validation` (a stalled validator).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `login` / `logout` | Authenticate / clear stored credentials |
+| `auth status` | Show the current session |
+| `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 |
+| `documents processing-status\|classification-types\|classification-update` | Inspect document status / classification |
+| `objects list\|get\|update\|patch\|revert\|versions\|delete` | Work with extracted OCF objects |
+| `schemas list\|get` | Browse the OCF object-type registry |
+| `commit` | Commit drafts to the cap table — `--all` or `--objects id1,id2` (`--dry-run` to preview) |
+| `summary` | Full cap table snapshot |
+| `export` / `register` | Export the cap table (Excel) / shareholder register |
+| `pro-forma run` | Model financing, convertible, warrant, and option-pool scenarios |
+| `retrigger-validation` | Re-queue a stalled validator |
+| `jobs list\|get\|prune` | Track async operations |
+| `profile save\|use\|list\|get\|delete` | Named configuration profiles |
+| `logs` | View agent/extraction logs |
+| `feedback` | Report CLI friction to the maintainers |
+| `commands` | Machine-readable list of all commands and flags |
+
+Run `captable-ai <command> --help` for full usage, or `captable-ai commands --json` for the
+authoritative machine-readable list.
+
+## Structured output
+
+Pass `--json` to any command for machine-readable output. Data goes to stdout, errors go
+to stderr, and the process exits with a typed code:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage error (bad/unknown flag, missing argument) |
+| 3 | Auth required / session expired |
+| 4 | Not found |
+| 5 | Conflict (version conflict, nothing to commit) |
+| 6 | Validation error |
+| 7 | Server error (5xx) |
+| 8 | Network error |
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CAPTABLE_AI_STAGE` / `STAGE` | Target environment: `production` (default), `staging`, `dev`, `local` |
+| `CAPTABLE_AI_API_URL` | Override the API base URL |
+| `CAPTABLE_AI_AUTH_URL` | Override the login page URL |
+| `CAPTABLE_AI_PORTAL_ID` | Override the active company for a single invocation |
+| `CAPTABLE_AI_FEEDBACK_URL` | Endpoint for `feedback send` |
+
+## License
+
+MIT © Fairmint, Inc.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node