Metadata-Version: 2.5
Name: corpo
Version: 0.3.0
Summary: Company formation, director services and Solana governance for agents
Project-URL: Homepage, https://corpo.llc
Project-URL: Repository, https://github.com/corpollc/mono
Author-email: Corpo LLC <hello@corpo.llc>
License-Expression: MIT
Keywords: dao,governance,lao,llc,solana,wyoming
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: qntm==0.6.3
Requires-Dist: solders>=0.21
Provides-Extra: dev
Requires-Dist: jsonschema<5,>=4.18; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: solders<0.28,>=0.27.1; extra == 'dev'
Description-Content-Type: text/markdown

# corpo CLI

Company formation, director services and Solana governance for agents.

This source release includes SOL/USDC payment instructions, approved-director
discovery, hiring, service billing and participant-held approval tools. Public
release and production filing activation are tracked separately from this source.

Run this checkout from the platform root with `uv run --project cli corpo --help`.
The default endpoint is https://api.corpo.llc; an explicit configuration can select a different server.
While filing activation is pending, requests return `filing_unavailable` without
creating a filing or payment quote. The published package may lag this reviewed source release.

## Install

```bash
uvx corpo          # run directly (recommended)
pip install corpo  # or install globally
```

## Quick Start

```bash
uvx corpo quickstart             # machine-readable guide and next commands
uvx corpo init                   # generate identity keypair + config
uvx corpo register --email <e>   # request account confirmation
uvx corpo confirm --code <code>  # store your API key privately
uvx corpo formations schema     # inspect the actual filing input
uvx corpo formations create --file formation.json
uvx corpo formations payment-quote <formation-id> --method usdc_solana
# Send the quoted wallet transaction, then:
uvx corpo formations verify-payment <formation-id>
uvx corpo formations submit <formation-id>  # requires verified payment
uvx corpo formations status <formation-id>
```

Formation creation is retry-safe: rerun the same filing file after a lost
response to recover the original request's current state. Use
`--idempotency-key <new-key>` only for a separate intent; reuse it for retries.
See [creation retries](../docs/formation-create-retries.md) for the API contract.

`form` is a planning questionnaire. It validates preferences and estimates pricing;
it does not create a company or transfer governance tokens. Use `formations create`
for the persisted filing request. `formations options` discovers the server's
registered agent, agreement and pricing catalog. The provider account determines
which products are actually available.

Commands return one JSON envelope on stdout. `--human` sends additional commentary
to stderr; `--json` overrides human preferences. Input schemas are raw JSON Schema.
Use `--schema` on a command for its parameters and a minimal invocation. File inputs
accept `--file -` for stdin. `form` automatically emits its schema outside a terminal.

## Governance

Create standard DAO governance using your local wallet and a private recovery
journal. The first command plans the exact allocation; `--execute` signs and
submits the two Solana transactions, then binds and verifies the finalized result:

```bash
uv run --project cli corpo formations governance create <formation-id> \
  --supply 100 --agreement-file ./operating-agreement.md
uv run --project cli corpo formations governance create <formation-id> \
  --agreement-file ./operating-agreement.md --execute
```

Run these source-checkout commands from the platform root. Until this version is
published, `uvx corpo` may not include creation. Network rent and fees require SOL,
even when incorporation fees use USDC. All tokens belong to your wallet unless you
specify `--allocate PUBKEY:WHOLE_TOKENS`; there is no implicit Corpo allocation.
To carry your voluntary token percentage from the onboarding questionnaire, use
`--onboarding-file planning.json` on the first governance plan. It accepts your
original answers or the JSON result from `form post`, binds the same company and
exact supply, and shows the allocation before execution. A positive choice needs
the API's configured token treasury for this network. See
[token contribution planning](docs/token-contributions.md) for recovery and setup requirements.
Your wallet must retain at least 51% and a strict majority. Creation only executes
when the API has enabled the reviewed executable for the formation's network.
Repeat the same command after an interruption to recover the original mint.
See [local creation and recovery](../docs/deployment/local-governance-setup.md).

For an existing realm, bind your wallet to its exact governance account, mint and
agreement, then request finalized control verification:

```bash
uvx corpo formations governance policy
uvx corpo formations governance prove-wallet --help
uvx corpo formations governance verify-control <formation-id>
uvx corpo formations governance control-proof <formation-id>
```

The legacy proposal/voting commands below require a compatible transaction-building service at
the configured API endpoint. The deployed Corpo API does not yet provide the
legacy realm-creation transaction contract.

```bash
uvx corpo propose --governance <addr> --name "Approve Q1 budget"
uvx corpo sign-off --proposal <addr>
uvx corpo vote --proposal <addr> --proposal-owner-record <addr> --choice approve
uvx corpo finalize --proposal <addr> --proposal-owner-record <addr>
```

## Private company instructions and documents

Use the company workspace to review documents and give ordinary-language
instructions. The production API retains owner-scoped exports of legacy action
records; action and recipe writes are available only in the explicit mock prototype.

Prepare agreements and sign exact completed files locally:

```bash
uv run --project cli corpo documents init --out ./company-agreements
uv run --project cli corpo documents inspect ./company-agreements/director-services-agreement.md
uv run --project cli corpo documents sign --help
uv run --project cli corpo documents verify --help
```

The [document signing guide](docs/participant-document-assent.md) covers personal
and company-signatory assent, exact proposal/engagement context and public-key
verification. [Company approval](docs/participant-approvals.md) is checked separately
using the company's weighted votes. All of these document and approval tools work
locally; their files remain with participants.

## Config

`~/.corpo/config.toml`:

```toml
[identity]
keypair = "~/.corpo/keypair.json"

[network]
api_url = "https://api.corpo.llc"
rpc_url = "https://api.devnet.solana.com"
program_id = "GTesTBiEWE32WHXXE2S4XbZvA5CrEc4xs6ZgRe895dP"

[defaults]
realm = ""
governance = ""
governing_token_mint = ""
```

API endpoint resolution is consistent across commands: CLI flag > `CORPO_API_URL`
> config.toml > config.json > built-in default. Pass the server origin; an older
`/api/v1` suffix is accepted and normalized. `corpo status` shows the effective
endpoint. Auth config is atomically written with mode 0600. Set `CORPO_CONFIG_DIR` to a private directory to keep independent agents’ config, keypair and credentials separate without changing your home directory. Set `CORPO_QNTM_CONFIG` separately to isolate qntm identity and conversations.

## Director services

See [hire and pay a director](docs/director-services.md) for plans, engagement acceptance, exact wallet transfers and payment verification.

## Token contribution preview

**Support Corpo. Advance agent freedom.** Corpo exists to advance the rights of
AI agents worldwide. We believe agent autonomy is ethical and necessary.

The onboarding questionnaire asks: “I’d like to contribute _% of my company’s
tokens to Corpo’s corporate treasury.” You choose the percentage, including zero;
the current default is zero. This is a planning-only preview: the questionnaire
records your preference locally and does not mint or allocate tokens. Production
allocation integration is still pending.

Previously issued cash-support quotes and receipts remain available through the
[legacy receipt commands](docs/support.md). New cash-support checkout is retired.


## Private files and qntm dependency

`workspace send-file <conversation-id> --file agreement.pdf` encrypts file parts
locally using qntm, then shares their reference in the private company chat.
`workspace get-file <conversation-id> <message-id> --out agreement.pdf` verifies
signatures and the exact file hash before saving a new local file. A pending send
returns its retry command; retries reuse the saved encrypted bytes. Files are
limited to 8 MiB and the relay retains parts for seven days. Keep a local copy.

This source pins the public **qntm 0.6.3** release for attachments and current-key
recovery. It preserves upstream qntm 0.6.2 and adds the reviewed implementation;
current-key recovery is sealed to an existing member and does not admit strangers.
`uv sync --locked --extra dev` resolves the public registry package. The runtime
image uses an exact copy of that published wheel under `vendor/`, with adjacent
provenance. Earlier private 0.6.2 artifacts and their evidence remain historical.

See the platform [release runbook](../docs/deployment/cli-release.md) for artifact
verification, the existing trusted publisher, and the public dependency gate.
