obolos 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# obolos CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`obolos` is the command line for operating obolos companies. It speaks in business terms (shares,
+dollars, dates, vesting schedules), asks when something is missing, prepares every change as a
+reviewed run, and only sends with a key you own. It calls `@obolos/sdk` directly; there is no hosted
+service in between.
+
+## Install
+
+```bash
+npm install --global obolos
+obolos --help
+```
+
+Inside this workspace:
+
+```bash
+pnpm install --filter obolos...
+pnpm --filter @obolos/sdk build
+pnpm --filter obolos build
+node cli/dist/cli.js --help
+```
+
+## Configure
+
+```bash
+export OBOLOS_RPC_URL=https://your-rpc.example   # or --rpc-url
+obolos login                                     # connect this terminal as one of your agent wallets
+obolos login --key                               # or sign in with your own key (OBOLOS_PRIVATE_KEY or --keystore)
+obolos doctor --json                             # RPC, chain, deployments, key
+```
+
+Pick the company once, like choosing a project:
+
+```bash
+obolos companies                 # the companies your wallet holds a role in
+obolos use '#3'                  # by factory id, or an address
+obolos whoami                    # your roles there, or your agent wallet and its powers
+obolos company show
+```
+
+The selection lives in `./.obolos/config.json`; `--company <#id|address>` overrides it per command.
+
+An agent wallet acts within the powers you give it on the Passport page: Read, Vote, Manage equity,
+Raise and Create a company. Granting roles, upgrading the company and withdrawing from its treasury
+take your own key (`obolos login --key`).
+
+## Operate
+
+Commands are noun-verb and take human units: shares `1,000`, money `250,000`, dates `2026-01-01`
+or `now`, durations `4y`, `18m`, `90d`, vesting `4y/1y/monthly`. Examples:
+
+```bash
+obolos shares issue --to 0xabc --shares 1,000 --document obolos://rooms/<room>/folders/<folder>/doc/<n>
+obolos shares class create --name "Series A Preferred" --authorized 2,000,000
+obolos vesting create --to 0xabc --shares 480,000 --start 2026-01-01 --vesting 4y/1y/monthly
+obolos grant issue --type option --to 0xabc --shares 40,000 --vesting 4y/1y/monthly
+obolos fundraise create --type safe --name Seed --target 2,000,000 --agreement bafy...
+obolos transfer request --to 0xdef --shares 1,000
+```
+
+`obolos <noun> --help` lists every verb and flag.
+
+### When something is missing
+
+A command that lacks a business input does not guess. It stops with exit code 6 and lists the
+questions, each with the flag that answers it and, where there are choices, the options with the
+default marked:
+
+```
+Create a share class needs a few answers first:
+
+  Which traits should the class have?
+    --traits standard        Standard: 1x liquidation preference, 1 vote per share, no par value  (default)
+    --traits non-voting      Non-voting: 1x liquidation preference, no votes, no par value
+    --traits custom          Custom: give liquidationPreference, votingWeight and parValue
+```
+
+With `--json` the same questions arrive on stderr under `error.code = "cli.needs_input"`.
+
+### Review and send
+
+Preparing never sends. Each write command runs the preflight (capability, authority, freeze,
+simulation of the exact call as the actor, credit quote), writes a hash-verified run file under
+`.obolos/runs/`, and prints the review block: summary, checks, warnings, the stages with the current
+one marked and its stage hash, and the postconditions.
+
+```bash
+obolos send .obolos/runs/shares.issue-1-c887e01e.json   # confirms, then sends with your key
+obolos status <run>                                      # where a run stands
+obolos resume <run>                                      # continue an interrupted run
+```
+
+Multi-step operations are one run: funding an escrow before a schedule, request then verdict then
+finalize, room then round. `send` walks the stages it can and stops when a stage waits on time,
+another party, or a verdict. Add `--send` to a command to send right after preparing (still asks
+for confirmation unless `--yes`). A run file that was edited by hand is refused.
+
+Run files contain private cross-stage state needed to resume. They are written owner-only (`0600`;
+new run directories use `0700`) and should not be printed or attached. With `--json`, write
+commands return a redacted `obolos-run-view/v1` containing workflow, check and stage statuses plus
+the stage hash and private run-file path. Normalized inputs, private state, calldata and stage
+outputs stay out of machine-readable logs.
+
+### Confidential values
+
+Amounts on vesting schedules, grants, valuations and financing terms are sealed before they go on
+chain and only readable by the parties the protocol allows. Sealing needs only the acting wallet:
+your key's, or the wallet your agent wallet works for after `obolos login`. Reading (`--reveal` on
+`show` commands) needs your key, or Read for the agent wallet; verdict publishing needs your key.
+
+## Agent skill
+
+The `obolos` Agent Skill ships with this package and teaches a coding agent to drive these
+commands: how to route a request, answer the questions a command asks, review a run before sending,
+and never invent a business value.
+
+```bash
+npm install -g obolos
+obolos skills install             # every agent detected in your home directory
+obolos skills list                # where it is installed, and whether each copy is current
+```
+
+The skill always goes to `~/.agents/skills`, the cross-agent root that Codex, Cursor, Gemini CLI and
+others read, plus the private directory of every agent found: Claude Code, Cursor, OpenCode, GitHub
+Copilot and Factory Droid. Codex needs nothing extra: it reads the shared root, and `--agent codex`
+(like `gemini`, `amp`, `cline`, `warp`) is a name for that same directory. Use `--agent <id...>` to
+pick specific ones, `--project <path>` to install
+into a repository (the shared root only, unless `--agent` names more), and `--replace` to back up a
+locally edited copy before overwriting it. A reinstall of an unchanged copy does nothing.
+
+Invoke it as `/obolos` in Claude Code or `$obolos` in Codex.
+
+Claude Code can also take the skill as a plugin, which tracks the repo instead of a copied
+directory. From a checkout of `equitylayer/services`:
+
+```
+/plugin marketplace add equitylayer/services
+/plugin install obolos@obolos
+```
+
+The marketplace manifest lives at `.claude-plugin/marketplace.json` and points at this package;
+`obolos skills install` stays the path for every other agent.
+
+## Keys
+
+The CLI never takes a private key as an argument. Use a dedicated environment variable or an
+encrypted keystore:
+
+```bash
+export OBOLOS_PRIVATE_KEY=0x...                         # or --key-env NAME
+export OBOLOS_KEYSTORE_PASSWORD='...'; obolos send <run> --keystore ./signer.json
+```
+
+Keys, keystore passwords, confidential plaintext and session material never belong in flags, run
+files, logs or agent conversations.
+
+## Low-level access
+
+`obolos sdk actions`, `obolos sdk read <module.method>`, `obolos sdk prepare <module.method>` and
+`obolos sdk batch` expose the SDK client one builder at a time for integration work; builders that
+need sealed confidential inputs are refused there and point to the matching command. `obolos decode
+<revert-data>` decodes protocol errors.
+
+## Exit codes
+
+`0` done, `1` unexpected failure, `2` input or usage, `3` configuration, `4` preflight or simulation
+failure, `5` send failure, `6` more input needed.