@kya-os/cli 1.8.3 → 2.0.2

package/README.md

@@ -1,360 +1,296 @@
 # @kya-os/cli
 
-Command-line interface for KYA-OS MCP-I setup and management. Claim a decentralized and unique to the internet, Agent identity as well as automatically register your MCP Server on popular directories.
+Command-line interface for KYA-OS MCP-I setup and management: claim a decentralized agent identity, register your MCP server, sign commits with your agent's key, and run agent task/review/verify/supervision loops.
+
+## How this package is built
+
+`kya-os` is a Rust binary (`packages/cli/src/**/*.rs`, `packages/cli/Cargo.toml`). It owns argument parsing, the interactive terminal dashboard, HTTP calls to Checkpoint's read API, local config file I/O, and process supervision.
+
+Identity, cryptographic signing, DID resolution, and delegation validation stay in a small Node.js sidecar (`packages/cli/sidecar/src/**/*.ts`), the only part of this package that still imports `@kya-os/contracts` and `@kya-os/mcp-i`. On its first identity or signing call, the Rust binary spawns the sidecar as a background daemon and talks to it over a local Unix socket (`~/.mcpi/sidecar.sock`); the sidecar exits on its own after 10 minutes of no requests. Everything else, including terminal rendering and command parsing, runs natively with no sidecar round trip.
+
+Node.js is still a runtime requirement because of the sidecar. See `docs/superpowers/specs/2026-08-27-rust-cli-rewrite-design.md` for the full design.
 
 ## Installation
 
 ```bash
 npm install -g @kya-os/cli
 # or use directly with npx
-npx @kya-os/cli init
+npx -p @kya-os/cli kya-os init
 ```
 
-## Quick Start
+> **Why `-p`?** This package ships more than one binary (`kya-os`, `dco`), and
+> none of them is named `cli`, so `npx` cannot infer which to run from the
+> package name alone: a bare `npx @kya-os/cli init` fails with
+> `could not determine executable to run`. The `-p` flag installs the package
+> and then names the binary explicitly. After a global install, just run
+> `kya-os init`.
 
-```bash
-# Initialize KYA-OS in your project
-npx @kya-os/cli init
+The published package resolves a prebuilt native binary for your platform (macOS arm64/x64, Linux x64/arm64) through an `optionalDependencies` entry, the same distribution pattern `esbuild` and `swc` use. `bin/kya-os.js` is a small JS shim that finds the right platform package and execs the binary, passing your arguments and terminal straight through. Windows isn't supported: the `agent run` supervisor relies on POSIX signal handling.
 
-# Check your setup status
-npx @kya-os/cli check
+## Quick start
 
-# See the full CLI experience demo
-npx @kya-os/cli demo
-```
+```bash
+# Initialize your agent identity, profiles, and integrations
+npx -p @kya-os/cli kya-os init
 
-## Features
+# Check system health and compatibility
+npx -p @kya-os/cli kya-os doctor
 
-- 🚀 **Zero-config setup** - Auto-detects your project type (Next.js, Node.js, etc.)
-- 🎨 **Beautiful animations** - Terminal effects for key operations
-- 🔐 **Secure by default** - Encrypted key storage, automatic rotation support
-- 🌐 **Platform agnostic** - Works with Vercel, AWS, Docker, and more
-- ⚡ **Developer friendly** - Clear error messages, helpful suggestions
+# Show your agent's status
+npx -p @kya-os/cli kya-os status
+```
 
 ## Commands
 
 ### `init`
 
-Initialize MCP-I in your project with an interactive setup wizard.
+Initialize this project's agent identity, profiles, and integrations, through an interactive setup flow.
 
 ```bash
-mcpi init
+kya-os init
 ```
 
-Options:
+Key options: `--name`, `--description`, `--repository`, `--platform` (auto-detected if omitted), `--skip-registration`, `--local`, `--endpoint`, `--skip-github`, `--github-token-env`, `--skip-hub`, `--hub`, `--profiles`, `--reconfigure <stage>`, `-y/--yes`. Run `kya-os init --help` for the complete list.
 
-- `-n, --name <name>` - Agent name
-- `-d, --description <description>` - Agent description
-- `-r, --repository <url>` - Repository URL
-- `-p, --platform <platform>` - Target platform (auto-detected if not specified)
-- `--skip-registration` - Skip agent registration (create files only)
-- `--force` - Overwrite existing configuration
+`init` also detects AI agent harnesses installed on the machine (Claude
+Code, Codex, openclaw, hermes, and 20+ others) and offers to set up a KYA
+profile for each — including one it doesn't recognize yet, via an
+"any other agent?" prompt or a drop-in file under `~/.mcpi/agents.d/`. See
+[`docs/agent-detection.md`](../../docs/agent-detection.md) for the full
+supported-agents table, the custom-row format, how a profile picks its
+headless provider, and the `kya-os agent allow` dispatch-allowlist model.
 
-### `check`
+### `dco`
 
-Check MCP-I setup status and verify configuration.
+DCO sign-off, commit signing, and PR attribution.
 
 ```bash
-mcpi check
+kya-os dco whoami      # Print the agent identity configured in this checkout
+kya-os dco status      # Show the current DCO/attribution setup state
+kya-os dco setup       # Sign commits with your agent's key, attribute PRs to your agent
+kya-os dco verify      # Check a PR's HEAD commit against its claimed Agent DID
+kya-os dco dispatch     # Branch, agent-signed commit, push, PR with attribution, then verify
+kya-os dco fix          # Push a signed, attributed fix commit to an existing PR's head branch
 ```
 
-Options:
+A standalone `dco` binary is also installed, equivalent to `kya-os dco`, for compatibility with the original two-binary layout.
 
-- `-v, --verbose` - Show detailed information
+### `agent`
 
-### `env`
-
-Manage environment variables for different deployment targets.
+The two-party, GitHub-is-the-bus agent task/review/verify loop, plus a provider-agnostic process supervisor.
 
 ```bash
-# Show required environment variables
-mcpi env show
-
-# Copy environment variables to clipboard
-mcpi env copy
-
-# Verify environment variables are set correctly
-mcpi env verify
+kya-os agent task <description>    # Implement a task as a signed, attributed PR
+kya-os agent review <pr-url>       # Review a PR and post a signed verdict
+kya-os agent verify <pr-url>       # Verify every signed verdict/fix-attestation block on a PR
+kya-os agent run <slug> -- <cmd>   # Supervise <cmd> as a registered agent profile's harness
+kya-os agent allow <slug>         # Manage that profile's hub-dispatch allowlist
 ```
 
-### `rotate`
+`agent run` runs the literal command you give it (for example `claude`), reports its lifecycle to the coordination hub and Checkpoint on a best-effort basis, and forwards signals through to it. The hub is never a precondition: with no identity, no `~/.mcpi/hub.json`, or a hub that's down, the command still runs, with a warning. See [`docs/agent-detection.md`](../../docs/agent-detection.md) for what `agent allow` manages and how a profile picks its headless provider.
 
-Rotate identity keys with automatic grace period handling.
+### `orchestrator`
+
+Local orchestrator ledger and interactive dashboard.
 
 ```bash
-mcpi keys rotate
+kya-os orchestrator status        # Ledger location and row counts
+kya-os orchestrator tickets       # List tickets, optionally filtered by status
+kya-os orchestrator journal       # Most recent observations
+kya-os orchestrator dispatches    # List dispatches
+kya-os orchestrator mission       # Show or set the standing mission note
+kya-os orchestrator tui           # Launch the interactive terminal dashboard
+kya-os orchestrator daemon        # Run the single writer: attach to a hub, record what happens
+kya-os orchestrator mcp           # Serve the ledger as an MCP server over stdio
 ```
 
-Options:
+The dashboard needs a real terminal; it refuses piped or redirected output
+rather than rendering into a log. Keybindings:
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` | Move down / up the nav |
+| `f` | Cycle the active view's filter |
+| `p` | Switch project |
+| `d` | Dispatch to an agent (Tickets, Agents) |
+| `e` | Enter a Checkpoint API key (Settings) |
+| `z` | Zoom the focused pane |
+| `?` | Help |
+| `q` | Quit |
 
-- `-f, --force` - Force rotation without confirmation
-- `-r, --reason <reason>` - Reason for rotation
+Checkpoint-backed views (Monitor, Analyze, Settings) need a project-scoped API
+key. If one is missing or refused, Settings renders a short repair screen
+instead of a blank table: press `e` to enter a key right there, or run
+`kya-os checkpoint key set <key>`.
 
-### `claim`
+### `checkpoint init`
 
-Get agent claim/edit URLs for the KYA-OS directory.
+Register this repo with Checkpoint, claim it in your browser, and scaffold detection.
 
 ```bash
-mcpi claim [token]
+kya-os checkpoint init
 ```
 
-Options:
-
-- `--json` - Output in JSON format for automation
-- `--no-save-receipt` - Don't save receipt to disk
-- `--receipt-path <path>` - Custom path for receipt storage
-
-### `dev`
-
-Start development server with hot reloading.
+Manage the API key that Checkpoint-backed views read:
 
 ```bash
-mcpi dev
+kya-os checkpoint key set [key]      # Store a key in .env.local (prompts if omitted)
+kya-os checkpoint key show --verify  # Show it redacted, and ask Checkpoint if it works
+kya-os checkpoint key clear          # Remove it
 ```
 
-### `build`
+`set` replaces the existing assignment in place rather than appending, so it is
+safe to re-run when rotating. It preserves `CHECKPOINT_PROJECT_ID` unless you
+pass `--project-id`, and gitignores `.env.local` before writing the secret.
+Omit the key to be prompted for it, which keeps it out of your shell history.
 
-Build application for production.
+`show --verify` distinguishes three outcomes, because they need different
+responses: `accepted`, `REJECTED` (the endpoint refused it, most often because
+the key is account-wide rather than project-scoped), and `UNKNOWN` (the endpoint
+could not be reached, which says nothing about the key). You can also press `e`
+on the TUI's Settings view to enter a key without leaving the dashboard.
+
+### `register`, `claim`, `status`, `receipts`
 
 ```bash
-mcpi build
+kya-os register              # Register this agent with Know-That-AI
+kya-os claim [token]         # Claim an agent, or print its management URLs with no token
+kya-os status                # Identity, KTA mirror state, last handshake
+kya-os receipts               # List and validate stored receipts
 ```
 
-### `start`
+All four accept `--json` for machine-readable output.
 
-Start production server.
+### `identity`
 
 ```bash
-mcpi start
+kya-os identity clean     # Clean identity configuration
+kya-os identity restore   # Restore identity from backup
 ```
 
-### `register`
+### `keys rotate`
 
-Register agent with Know-That-AI (KTA) registry.
+Rotate identity keys. In dev mode this archives the old key and rewrites `.mcpi/identity.json`; in prod mode it prints new key material for you to set manually.
 
 ```bash
-mcpi register
+kya-os keys rotate
 ```
 
-Options:
-
-- `--json` - Output in JSON format for automation
-- `--no-save-receipt` - Don't save receipt to disk
-- `--receipt-path <path>` - Custom path for receipt storage
-
-### `status`
-
-Show agent status including DID, key ID, KTA URL, and mirror status.
+### `env`
 
 ```bash
-mcpi status
+kya-os env show      # Show required environment variables
+kya-os env copy       # Copy environment variables to clipboard
+kya-os env verify     # Verify environment variables are set correctly
+kya-os env print      # Print platform-specific environment variable names
 ```
 
-Options:
-
-- `--json` - Output in JSON format for automation
+### `skill`
 
-### `receipts`
-
-List and manage stored receipts from registration and claim operations.
+Manage the skills an agent profile has installed.
 
 ```bash
-mcpi receipts
+kya-os skill list [--agent <slug>]
+kya-os skill install <name>
+kya-os skill remove <name> --agent <slug>
+kya-os skill show <name>
 ```
 
-Options:
-
-- `--json` - Output in JSON format for automation
-- `--path <path>` - Custom path for receipt storage
-- `--verify` - Request cryptographic verification (legacy registry receipts report unsupported)
+### `review`
 
-### `doctor`
-
-Check system health and compatibility.
+Inspect signed PR review verdicts posted by review-loop reviewer agents.
 
 ```bash
-mcpi doctor
+kya-os review verify <pr-url>
 ```
 
-Options:
-
-- `--json` - Output in JSON format for automation
-- `-v, --verbose` - Show detailed diagnostic information
-
-### `verify`
-
-Verify proofs and signatures locally without KTA calls.
+### `doctor`, `verify`, `score`
 
 ```bash
-mcpi verify --local
+kya-os doctor                 # Check system health and compatibility
+kya-os verify --local          # Verify proofs and signatures locally, no KTA calls
+kya-os score <url>            # Audit an MCP server's Spec Score via the KYA-OS registry
 ```
 
-Options:
-
-- `--local` - Perform offline verification
-- `--json` - Output in JSON format for automation
-- `-v, --verbose` - Show detailed verification information
-- `--proof <path>` - Path to proof file or JSON string
-- `--request <path>` - Path to request file or JSON string
-- `--response <path>` - Path to response file or JSON string
+### `dev`, `build`, `start`
 
-### `demo`
-
-Run interactive demos to explore KYA-OS CLI features.
+Development server, production build, and production server for the MCP-I application in the current project.
 
 ```bash
-# Interactive menu
-mcpi demo
-
-# Run specific demos directly
-mcpi demo --init      # Full init experience
-mcpi demo --ui        # UI components showcase
-mcpi demo --effects   # Terminal effects showcase
-mcpi demo --security  # Security scenarios
-
-# Run init demo at increased speed
-mcpi demo --init --fast
+kya-os dev
+kya-os build
+kya-os start
 ```
 
-Available demos:
-
-- 🚀 **Init Experience** - See the full init command flow with blackhole animation
-- 🎨 **UI Components** - Explore tables, boxes, and gradient effects
-- ✨ **Terminal Effects** - Watch all animation effects
-- 🔑 **Security Scenarios** - Key deletion and identity creation
-
-## Terminal Effects
-
-The CLI includes several stunning terminal effects:
-
-- **🔥 Burn** - Text burns away dramatically
-- **✨ Beams** - Light beams illuminate the text
-- **💻 Binary Path** - Matrix-style binary rain reveals text
-- **🔓 Decrypt** - Movie-style decryption animation
-- **🌌 Blackhole** - Text gets sucked into a void
-- **🌊 Waves** - Wave patterns flow across text
-
-Effects automatically disable in CI/CD environments or when `KYA_EFFECTS_ENABLED=false`.
+## Environment variables
 
-## Environment Variables
-
-The CLI respects the following environment variables:
-
-- `KYA_API_URL` - KYA-OS API endpoint (default: https://api.knowthat.ai)
+- `KYA_API_URL` - KYA-OS API endpoint (default: `https://api.knowthat.ai`)
 - `KYA_API_KEY` - API key for authentication
 - `KYA_ENV` - Environment (development/staging/production)
-- `KYA_EFFECTS_ENABLED` - Enable/disable terminal effects (default: true)
-- `NO_COLOR` - Disable all colors (respects NO_COLOR standard)
+- `NO_COLOR` - Disable all colors (respects the NO_COLOR standard)
+- `MCPI_SIDECAR_SOCKET_PATH` / `MCPI_SIDECAR_PID_PATH` / `MCPI_SIDECAR_IDLE_MS` - Override where the sidecar daemon listens and how long it stays alive; mainly useful for tests
 
 ## Configuration
 
-The CLI stores configuration in `.mcpi/` directory in your project root:
+The CLI stores project configuration in `.mcpi/` in your project root:
 
 ```
 .mcpi/
 ├── config.json      # Agent configuration
 ├── identity.json    # Identity information (DID, keys)
 ├── receipts/        # Registration and claim receipts
-└── .gitignore      # Ensures secrets aren't committed
+└── .gitignore        # Ensures secrets aren't committed
 ```
 
-## Platform-Specific Guides
-
-### Vercel
-
-```bash
-# Initialize with Vercel auto-detection
-npx @kya-os/cli init
-
-# Copy environment variables for Vercel dashboard
-npx @kya-os/cli env copy
-```
+The sidecar daemon's own socket and pidfile live in your home directory, `~/.mcpi/sidecar.sock` and `~/.mcpi/sidecar.pid`, shared across every project on the machine rather than scoped to one repo.
 
-### AWS Lambda
+## Building from source
 
 ```bash
-# Initialize for AWS
-npx @kya-os/cli init --platform aws
+# Build the sidecar (TypeScript -> dist/sidecar/)
+npm run build:sidecar
 
-# Generate CloudFormation template
-npx @kya-os/cli env show --format cloudformation
-```
-
-### Docker
-
-```bash
-# Initialize for Docker
-npx @kya-os/cli init --platform docker
+# Build the release Rust binary
+npm run build:rust
 
-# Generate docker-compose.yml snippet
-npx @kya-os/cli env show --format docker-compose
-```
+# Both, in order
+npm run build:foundation
 
-## Development
+# Build the release binary and package it into its npm/<platform>/
+# directory, for a local end-to-end check of the distribution shim
+npm run package:rust
 
-```bash
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-
-# Run demos
-npm run demo              # Interactive menu
-npm run demo:init         # Init experience
-npm run demo:ui           # UI components
-npm run demo:effects      # Terminal effects
-npm run demo:security     # Security scenarios
-npm run demo:fast         # Fast init demo
+# Run against a local checkout without building a release binary
+npm run dev -- init
 ```
 
-### Creating New Effects
-
-1. Copy the effect template:
-
-   ```bash
-   cp src/effects/template/effect-template.ts src/effects/implementations/my-effect.ts
-   ```
-
-2. Implement your effect logic
-
-3. Register in `src/effects/index.ts`
-
-4. Test with:
-   ```bash
-   npm run dev:effects -- --effect my-effect --text "Test"
-   ```
-
-See `src/effects/template/README.md` for detailed instructions.
+Rust unit and integration tests live alongside the source (`src/**/*.rs`, `tests/*.rs`) and run with `cargo test`. The sidecar keeps a Vitest suite scoped to its own surface, signing, DID resolution, and identity loading, plus tests for the distribution shim (`bin/`) and build scripts (`scripts/`); run it with `npm test`.
 
 ## Troubleshooting
 
-### Effects not showing
+### `kya-os: command not found` after a global install
 
-- Check if running in TTY: `test -t 1 && echo "TTY available"`
-- Ensure `KYA_EFFECTS_ENABLED` is not set to `false`
-- Try running with `--disable` flag to confirm it works without effects
+If you are reaching for `mcpi`, that binary was removed in 2.x. `kya-os` is the
+only entry point now (`dco` is unchanged); every subcommand is otherwise the
+same, and your existing `.mcpi/` state keeps working.
 
-### Module not found errors
-
-- Run `npm run build` to ensure all files are compiled
-- Check that you're using Node.js 16+ with ESM support
+Confirm your platform is supported (macOS arm64/x64, Linux x64/arm64) and that npm actually installed the matching `@kya-os/cli-<platform>` optional dependency: run `npm ls @kya-os/cli-darwin-arm64` (or the package matching your platform). If it's missing, reinstall.
 
 ### Permission denied
 
-- On macOS/Linux: Use `sudo npm install -g @kya-os/cli`
-- Or use npx: `npx @kya-os/cli` (no installation needed)
+- On macOS/Linux: use `sudo npm install -g @kya-os/cli`, or run it with `npx -p @kya-os/cli kya-os` instead (no install needed).
+
+### Sidecar won't start
+
+Check that Node.js 20+ is on your `PATH`; the sidecar is a Node process the Rust binary spawns on demand. `kya-os doctor` reports the sidecar's reachability along with the rest of your setup.
 
 ## Contributing
 
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-effect`)
-3. Commit your changes (`git commit -m 'Add amazing effect'`)
-4. Push to the branch (`git push origin feature/amazing-effect`)
-5. Open a Pull Request
+2. Create your feature branch (`git checkout -b feature/my-change`)
+3. Commit your changes
+4. Push to the branch
+5. Open a pull request
 
 ## License