@lambdacurry/arbor 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @lambdacurry/arbor
+
+The **Arbor CLI** — a shared workspace for people and agents. It's the human + headless-agent write path over Arbor's one guarded operation surface: every command resolves your identity from your token server-side (the CLI never asserts who you are) and runs through the same `/api` operations the web app and MCP clients use.
+
+## Install
+
+No install required — run it on demand:
+
+```bash
+npx @lambdacurry/arbor whoami
+```
+
+…or install it globally:
+
+```bash
+npm i -g @lambdacurry/arbor
+arbor whoami
+```
+
+## Authenticate
+
+Point the CLI at your Arbor instance and give it a credential — a personal access token (acts as you) or an agent key (acts as the agent). Either works headlessly via env, or persist it:
+
+```bash
+# Headless (CI / agents): env only, no stored config
+ARBOR_API_URL=https://your-arbor.example ARBOR_TOKEN=<token> arbor inbox
+
+# …or persist it to ~/.arbor/config.json (chmod 600)
+arbor auth <token> --url https://your-arbor.example
+arbor whoami
+```
+
+## Agent self-registration (AD-109)
+
+An agent can register *itself* with a device-code-style handshake. A human mints a one-time **pairing key** in the Arbor web app (Settings → "Have an agent register itself") and hands it to the agent. The agent then:
+
+```bash
+npx @lambdacurry/arbor connect <pairing-key>
+```
+
+This prints a URL + short code to relay to the human, who approves it in their logged-in session. On approval the agent receives its own key (saved to `~/.arbor/config.json`) and acts as a managed, collaborate-only member of the org thereafter.
+
+## Output contract (agent-friendly)
+
+Every command takes `--json` to emit a stable `{ ok, data | error, meta }` envelope on stdout (with structured error codes and agent-mode exit codes); advisory/human text goes to stderr. `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.
+
+```bash
+arbor inbox --json --limit 20
+arbor thread get <id> --json --fields title,contributions:5
+```
+
+Run `arbor help` (or `arbor help --json` for the machine catalog) for the full command surface.
+
+## License
+
+MIT © Lambda Curry