thecorporation-form-and-operate

How to use the `npx corp` CLI to manage corporate entities, governance, cap tables, finance, agents, and compliance for TheCorporation platform. Use this skill whenever the user mentions `npx corp`, TheCorporation, corporate formation, entity governance, cap table management, equity issuance, 409A valuations, board meetings, written consent, SAFE instruments, corporate agents, work items, or any task involving programmatic corporate governance. Also use when the user wants to form an LLC or C-Corp, manage board seats, issue stock options, run payroll, generate legal documents, or automate corporate compliance workflows.

# npx corp CLI Skill

The `npx corp` CLI is the command-line interface for TheCorporation platform — a corporate governance system built by agents, for agents. It manages the full lifecycle of business entities: formation, governance, cap tables, finance, documents, tax, compliance, agents, and work items.

## Quick Start

### Setup

```bash
npx corp setup
```

Choose a hosting mode:

- **Local (your machine)** — no server needed. Data stored in `~/.corp/data`. Each command invokes the Rust binary directly (~6ms).
- **TheCorporation cloud** — hosted service, authenticates via magic link.
- **Self-hosted server** — point to your own API server URL.

### Local mode (recommended for development)

```bash
npx corp setup              # choose "Local (your machine)"
npx corp status             # verify — all local, no network
```

### Cloud mode

```bash
npx corp setup              # choose "TheCorporation cloud"
# Follow the magic link auth flow
```

### Advanced: Local server mode

For development with a persistent HTTP server:

```bash
npx corp serve --port 8020
npx corp config set api_url http://localhost:8020 --force
```

### Verify Context

```bash
npx corp context
```

Shows active workspace, user, entity, and hosting mode.

## Reference Resolution

The CLI supports flexible reference formats across all commands:

| Format | Example | Description |
|--------|---------|-------------|
| Full UUID | `763dde4d-ca62-4e20-90ba-662c462d4b09` | Canonical ID |
| Short ID | `763dde4d` | First segment of UUID |
| `@last` | `@last` | Most recently created resource of that type |
| Name/Handle | `"Acme Corp"` | Unique name match |

Use `npx corp resolve <kind> <ref>` to test resolution. Use `npx corp find <kind> <query>` to list matches.

## Entity Formation

### One-Shot Formation (Recommended for Agents)

Form an entity in a single command using key=value member syntax:

```bash
npx corp form \
  --type c_corp \
  --name "Acme Inc" \
  --jurisdiction US-DE \
  --member "name=Jane Doe,email=jane@acme.com,role=director,officer_title=ceo,is_incorporator=true,address=123 Main St|Dover|DE|19901" \
  --member "name=John Doe,email=john@acme.com,role=director,officer_title=cto,address=456 Oak Ave|Dover|DE|19901" \
  --json
```

**One-shot flags:**
- `--type <type>` — Entity type (see below)
- `--name <name>` — Legal name of the entity
- `--jurisdiction <jurisdiction>` — e.g. `US-DE`, `US-WY`
- `--member <spec>` — Founder (repeatable); key=value format with keys: `name`, `email`, `role` (director|officer|manager|member|chair), `officer_title` (ceo|cfo|cto|coo|secretary|treasurer|president|vp|other), `is_incorporator` (true|false), `address` (street|city|state|zip), `pct` (ownership %), `shares` (shares purchased)
- `--address <address>` — Company address as `street,city,state,zip`
- `--fiscal-year-end <date>` — Fiscal year end (MM-DD, default "12-31")
- `--s-corp` — Elect S-Corp status
- `--transfer-restrictions` — Enable transfer restrictions
- `--rofr` — Enable right of first refusal

**Important:** Member addresses use pipe `|` as separator (street|city|state|zip), NOT commas.

### Staged Formation

For more control, use the staged flow:

1. **Create** — `npx corp form create --type c_corp --name "Acme Inc" --jurisdiction US-DE --json`
2. **Add Founders** — `npx corp form add-founder @last --name "Jane Doe" --email jane@acme.com --role director --pct 100 --officer-title ceo --incorporator --address "123 Main St,Dover,DE,19901" --json`
3. **Finalize** — `npx corp form finalize @last --board-size 1 --company-address "123 Main St,Dover,DE,19901" --json`
4. **Activate** — `npx corp form activate @last --json`

The `activate` step transitions from `documents_generated` to `active` status by auto-signing formation documents.

**Staged `add-founder` flags:**
- `--name` (required), `--email` (required), `--role` (required: director|officer|manager|member|chair), `--pct` (required: ownership %)
- `--officer-title <title>` (choices: ceo, cfo, cto, coo, secretary, treasurer, president, vp, other)
- `--incorporator` (boolean flag — mark as sole incorporator)
- `--address <address>` (as `street,city,state,zip`)

**Staged `finalize` flags:**
- `--board-size <n>`, `--authorized-shares <n>`, `--par-value <value>`
- `--company-address`, `--incorporator-name`, `--incorporator-address`
- `--principal-name` (LLC manager name)

### Entity Types

`c_corp`, `llc`, `lp`, `llp`, `gp`, `sole_prop`, `cooperative`, `nonprofit`

### Setting Active Entity

Most commands require an active entity context:

```bash
npx corp config set active_entity_id <entity-ref>
```

## Governance

Governance operates through bodies (e.g., Board of Directors), seats, meetings, and resolutions.

### Full Meeting Lifecycle

```
create-body → add-seat → convene (with --agenda) → notice → open (--present-seat) → vote → resolve → finalize-item → adjourn
```

1. **Create a governance body**
   ```bash
   npx corp governance create-body --name "Board of Directors" --body-type board_of_directors --json
   ```
   Body types: `board_of_directors`, `llc_member_vote`

2. **Add seats** — `<body-ref>` is a positional argument
   ```bash
   npx corp governance add-seat @last --holder <contact-ref> --role member --json
   ```
   Roles: `chair`, `member`, `officer`, `observer`

3. **Convene a meeting** — `--type` and `--body` are required
   ```bash
   npx corp governance convene --body @last --type board_meeting --title "Board Meeting Q1" --date 2026-04-01 --agenda "Approve equity grant" --agenda "Review financials" --json
   ```
   Meeting types: `board_meeting`, `shareholder_meeting`, `member_meeting`, `written_consent`

   Agenda items are added via repeatable `--agenda` flags on `convene`. There is no separate `agenda-items add` command.

4. **List agenda items** — `npx corp governance agenda-items <meeting-ref> --json`

5. **Send notice** — `npx corp governance notice <meeting-ref> --json`

6. **Open meeting with present seats**
   ```bash
   npx corp governance open <meeting-ref> --present-seat <seat-ref> --json
   ```
   Repeat `--present-seat` for each seat present.

7. **Vote on agenda item**
   ```bash
   npx corp governance vote <meeting-ref> <item-ref> --voter <contact-ref> --vote for --json
   ```
   Vote values: `for`, `against`, `abstain`, `recusal`

8. **Compute resolution** — requires both `<meeting-ref>` and `<item-ref>` as positional args
   ```bash
   npx corp governance resolve <meeting-ref> <item-ref> --text "RESOLVED: The board approves the equity grant" --json
   ```

9. **Finalize item**
   ```bash
   npx corp governance finalize-item <meeting-ref> <item-ref> --status voted --json
   ```
   Status choices: `discussed`, `voted`, `tabled`, `withdrawn`

10. **Adjourn** — `npx corp governance adjourn <meeting-ref> --json`

### Written Consent (Alternative to Meetings)

For board approvals without a formal meeting:

```bash
npx corp governance written-consent --body <body-ref> --title "Approve Equity Grant" --description "Approve 10000 shares to Jane Doe" --json
```

Written consent produces a `meeting_id` and resolution that can be used for downstream operations like equity issuance. List the agenda items and vote to complete:

```bash
npx corp governance agenda-items @last
npx corp governance vote @last <item-ref> --voter <contact-ref> --vote for --json
```

## Cap Table

### Instruments

Create equity instruments before issuing shares:

```bash
npx corp cap-table create-instrument --kind common_equity --symbol COMMON --authorized-units 10000000 --issue-price-cents 1 --json
```

**Instrument kinds:** `common_equity`, `preferred_equity`, `membership_unit`, `option_grant`, `safe`

**Flags:**
- `--kind <kind>` (required) — instrument kind
- `--symbol <symbol>` (required) — e.g. COMMON, SERIES-A, OPTION-PLAN
- `--authorized-units <n>` — total authorized shares/units
- `--issue-price-cents <n>` — issue price in cents
- `--issuer-legal-entity-id <ref>` — auto-resolved if omitted
- `--terms-json <json>` — JSON o