feat(cli): add client commands and home-based local runtime defaults

doc/CLI.md

@@ -0,0 +1,128 @@
+# CLI Reference
+
+Paperclip CLI now supports both:
+
+- instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`)
+- control-plane client operations (issues, approvals, agents, activity, dashboard)
+
+## Base Usage
+
+Use repo script in development:
+
+```sh
+pnpm paperclip --help
+```
+
+First-time local bootstrap + run:
+
+```sh
+pnpm paperclip run
+```
+
+Choose local instance:
+
+```sh
+pnpm paperclip run --instance dev
+```
+
+All client commands support:
+
+- `--api-base <url>`
+- `--api-key <token>`
+- `--context <path>`
+- `--profile <name>`
+- `--json`
+
+Company-scoped commands also support `--company-id <id>`.
+
+## Context Profiles
+
+Store local defaults in `~/.paperclip/context.json`:
+
+```sh
+pnpm paperclip context set --api-base http://localhost:3100 --company-id <company-id>
+pnpm paperclip context show
+pnpm paperclip context list
+pnpm paperclip context use default
+```
+
+To avoid storing secrets in context, set `apiKeyEnvVarName` and keep the key in env:
+
+```sh
+pnpm paperclip context set --api-key-env-var-name PAPERCLIP_API_KEY
+export PAPERCLIP_API_KEY=...
+```
+
+## Company Commands
+
+```sh
+pnpm paperclip company list
+pnpm paperclip company get <company-id>
+```
+
+## Issue Commands
+
+```sh
+pnpm paperclip issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
+pnpm paperclip issue get <issue-id-or-identifier>
+pnpm paperclip issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
+pnpm paperclip issue update <issue-id> [--status in_progress] [--comment "..."]
+pnpm paperclip issue comment <issue-id> --body "..." [--reopen]
+pnpm paperclip issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
+pnpm paperclip issue release <issue-id>
+```
+
+## Agent Commands
+
+```sh
+pnpm paperclip agent list --company-id <company-id>
+pnpm paperclip agent get <agent-id>
+```
+
+## Approval Commands
+
+```sh
+pnpm paperclip approval list --company-id <company-id> [--status pending]
+pnpm paperclip approval get <approval-id>
+pnpm paperclip approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+pnpm paperclip approval approve <approval-id> [--decision-note "..."]
+pnpm paperclip approval reject <approval-id> [--decision-note "..."]
+pnpm paperclip approval request-revision <approval-id> [--decision-note "..."]
+pnpm paperclip approval resubmit <approval-id> [--payload '{"...":"..."}']
+pnpm paperclip approval comment <approval-id> --body "..."
+```
+
+## Activity Commands
+
+```sh
+pnpm paperclip activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]
+```
+
+## Dashboard Commands
+
+```sh
+pnpm paperclip dashboard get --company-id <company-id>
+```
+
+## Heartbeat Command
+
+`heartbeat run` now also supports context/api-key options and uses the shared client stack:
+
+```sh
+pnpm paperclip heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
+```
+
+## Local Storage Defaults
+
+Default local instance root is `~/.paperclip/instances/default`:
+
+- config: `~/.paperclip/instances/default/config.json`
+- embedded db: `~/.paperclip/instances/default/db`
+- logs: `~/.paperclip/instances/default/logs`
+- secrets key: `~/.paperclip/instances/default/secrets/master.key`
+
+Override base home or instance with env vars:
+
+```sh
+PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
+```

doc/DATABASE.md

@@ -12,12 +12,12 @@ pnpm dev
 
 That's it. On first start the server:
 
-1. Creates a `./server/data/embedded-postgres/` directory for storage
+1. Creates a `~/.paperclip/instances/default/db/` directory for storage
 2. Ensures the `paperclip` database exists
 3. Runs migrations automatically for empty databases
 4. Starts serving requests
 
-Data persists across restarts in `./server/data/embedded-postgres/`. To reset local dev data, delete that directory.
+Data persists across restarts in `~/.paperclip/instances/default/db/`. To reset local dev data, delete that directory.
 
 This mode is ideal for local development and one-command installs.
 
@@ -115,7 +115,7 @@ The database mode is controlled by `DATABASE_URL`:
 
 | `DATABASE_URL` | Mode |
 |---|---|
-| Not set | Embedded PostgreSQL (`./server/data/embedded-postgres/`) |
+| Not set | Embedded PostgreSQL (`~/.paperclip/instances/default/db/`) |
 | `postgres://...localhost...` | Local Docker PostgreSQL |
 | `postgres://...supabase.com...` | Hosted Supabase |
 
@@ -131,8 +131,8 @@ Paperclip stores secret metadata and versions in:
 For local/default installs, the active provider is `local_encrypted`:
 
 - Secret material is encrypted at rest with a local master key.
-- Default key file: `./data/secrets/master.key` (auto-created if missing).
-- CLI config location: `.paperclip/config.json` under `secrets.localEncrypted.keyFilePath`.
+- Default key file: `~/.paperclip/instances/default/secrets/master.key` (auto-created if missing).
+- CLI config location: `~/.paperclip/instances/default/config.json` under `secrets.localEncrypted.keyFilePath`.
 
 Optional overrides:
 

doc/DEVELOPING.md

@@ -21,12 +21,32 @@ This starts:
 - API server: `http://localhost:3100`
 - UI: served by the API server in dev middleware mode (same origin as API)
 
+## One-Command Local Run
+
+For a first-time local install, you can bootstrap and run in one command:
+
+```sh
+pnpm paperclip run
+```
+
+`paperclip run` does:
+
+1. auto-onboard if config is missing
+2. `paperclip doctor` with repair enabled
+3. starts the server when checks pass
+
 ## Database in Dev (Auto-Handled)
 
 For local development, leave `DATABASE_URL` unset.
 The server will automatically use embedded PostgreSQL and persist data at:
 
-- `./data/embedded-postgres`
+- `~/.paperclip/instances/default/db`
+
+Override home and instance:
+
+```sh
+PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
+```
 
 No Docker or external database is required for this mode.
 
@@ -49,7 +69,7 @@ Expected:
 To wipe local dev data and start fresh:
 
 ```sh
-rm -rf server/data/embedded-postgres
+rm -rf ~/.paperclip/instances/default/db
 pnpm dev
 ```
 
@@ -61,7 +81,7 @@ If you set `DATABASE_URL`, the server will use that instead of embedded PostgreS
 
 Agent env vars now support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.
 
-- Default local key path: `./data/secrets/master.key`
+- Default local key path: `~/.paperclip/instances/default/secrets/master.key`
 - Override key material directly: `PAPERCLIP_SECRETS_MASTER_KEY`
 - Override key file path: `PAPERCLIP_SECRETS_MASTER_KEY_FILE`
 
@@ -85,3 +105,30 @@ Migration helper for existing inline env secrets:
 pnpm secrets:migrate-inline-env         # dry run
 pnpm secrets:migrate-inline-env --apply # apply migration
 ```
+
+## CLI Client Operations
+
+Paperclip CLI now includes client-side control-plane commands in addition to setup commands.
+
+Quick examples:
+
+```sh
+pnpm paperclip issue list --company-id <company-id>
+pnpm paperclip issue create --company-id <company-id> --title "Investigate checkout conflict"
+pnpm paperclip issue update <issue-id> --status in_progress --comment "Started triage"
+```
+
+Set defaults once with context profiles:
+
+```sh
+pnpm paperclip context set --api-base http://localhost:3100 --company-id <company-id>
+```
+
+Then run commands without repeating flags:
+
+```sh
+pnpm paperclip issue list
+pnpm paperclip dashboard get
+```
+
+See full command reference in `doc/CLI.md`.

doc/SPEC-implementation.md

@@ -92,7 +92,7 @@ V1 implementation extends this baseline into a company-centric, governance-aware
 ## 6.2 Data Stores
 
 - Primary: PostgreSQL
-- Local default: embedded PostgreSQL at `./server/data/embedded-postgres`
+- Local default: embedded PostgreSQL at `~/.paperclip/instances/default/db`
 - Optional local prod-like: Docker Postgres
 - Optional hosted: Supabase/Postgres-compatible