thecorporation-form-and-operate

What this skill does

# 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 protected],role=director,officer_title=ceo,is_incorporator=true,address=123 Main St|Dover|DE|19901" \
  --member "name=John Doe,[email protected],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 [email protected] --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