# Cap MVP

`cap` is the first local prototype of an agent-native capability resolver for CLI-backed tools.

The long-term product is an app-store registry where mostly untrusted third-party publishers can submit CLI tools. The main value prop is not manual browsing. It is autonomous discovery: Codex, Claude Code, and similar agents should be able to start from a task, find the right CLI-backed capability among a very large registry, evaluate safety and fit, try it under policy, and use it without a human choosing packages one by one.

This first iteration does not include accounts, payments, L402/x402, remote services, SBOMs, sandbox review workers, or full MCP host registration. It should prove the local loop and data model that make autonomous resolution possible.

## MVP Goal

A fresh agent-assisted user should be able to:

1. Ask an agent to solve a task.
2. Have the agent run `cap resolve <task> --json`.
3. Receive ranked candidates with capability-card data and policy decisions.
4. Inspect a candidate with `cap info <package> --json`.
5. Try a candidate with an ephemeral smoke test or dry run.
6. Install a pinned package version after an exact install preview.
7. Invoke the package through `cap run <package> -- ...` without relying on global `PATH`.

Human approval can still be required by policy. "Autonomous" means the host can proceed when standing policy already authorizes the action.

## Primary Use Case

The first end-to-end use case is Codex or Claude Code helping a user set up a new Lightning testnet-style node through `lightningnode/voltage-sandbox`. See [use-case-codex-claude-code-new-lightning-testnet-node.md](use-case-codex-claude-code-new-lightning-testnet-node.md).

## Current Prototype Flow

Hosted install:

```bash
curl -fsSL https://capcli.com/install.sh | sh && export PATH="$HOME/.cap/bin:$PATH" && cap doctor
cap setup codex
cap setup claude
```

Local repo development:

```bash
node src/cap.js doctor
node src/cap.js resolve "set up a new lightning testnet node" --json
node src/cap.js search voltage
node src/cap.js info lightningnode/voltage-sandbox
node src/cap.js try lightningnode/voltage-sandbox --json
node src/cap.js add lightningnode/voltage-sandbox --yes
node src/cap.js run lightningnode/voltage-sandbox -- brief
node src/cap.js run lightningnode/voltage-sandbox -- credentials
```

The installer still appends the CAP command directory to the user's shell profile:

```bash
export PATH="$HOME/.cap/bin:$PATH"
```

That direct command path is useful for humans, but it is not the preferred long-term agent interface. Agents should prefer `cap run`, generated MCP wrappers, or host-registered tools so invocation remains policy-mediated.

Initial host-native surface:

```text
plugins/voltage-sandbox/
```

This repo-local Codex plugin adds a thin MCP wrapper and skill for `voltage-sandbox`. The wrapper still invokes the package through `cap run`; it does not reimplement Voltage API behavior or bypass the CLI credential boundary.

## Target MVP Commands

- `cap resolve <task>`: return ranked, policy-aware candidate capability cards.
- `cap search <query>`: task-oriented search over the registry.
- `cap info <package>`: package summary, capability card, review summary, permissions, and exact install plan.
- `cap try <package>`: run a declared smoke test or dry run without persistent install.
- `cap add <package>`: install a pinned immutable package version into the current project's package scope after approval, or immediately when policy and `--yes` allow it. Use `--global` or `-g` for the global package scope.
- `cap install` / `cap sync`: review policy for all project `Capfile.lock` entries, then install them after approval or `--yes`.
- `cap remove <package>`: remove a package from the project `Capfile`, lockfile, and installed record.
- `cap list`: installed packages in the active package scope, plus project pins when present.
- `cap run <package> -- <args>`: run the selected package command without relying on `PATH`.
- `cap doctor`: show store paths, policy state, PATH setup, and host integration status.
- `cap setup codex|claude`: install host integration so future agents discover CAP before scanning the workspace.
- `cap uninstall`: remove local cap files, shell profile PATH setup, and CAP host integrations from Codex and tracked Claude Code projects.
- `cap bin`: print the active package scope's bin directory.
- `cap init`, `cap preview`, `cap review`, `cap publish --local`: create and validate a local `capability.json`, then publish it into a checked-in registry JSON file.

Most commands should support `--json` for agents.

See [publisher-workflow.md](publisher-workflow.md) for the current local publish workflow, supported manifest fields, and preflight checks.

## Policy And Review Model

CAP keeps the default path simple and structured:

- **Review** means package facts: approval status, review tier, risk, publisher verification, artifact digest, safe trials, and requested permissions.
- **Policy** means local host rules. The default `balanced` policy allows reviewed medium-risk packages to run declared safe trials, while install and runtime actions still require approval.
- **Decision** means the result for each action: `allowed`, `requires-approval`, or `blocked`.

Action decisions have direct meanings:

- `resolve: allowed`: CAP may show the package in search or resolve results.
- `info: allowed`: CAP may inspect metadata and exact install plans.
- `try: allowed`: CAP may run declared safe trial commands.
- `install: requires-approval`: CAP can install only after explicit approval or `--yes`.
- `run: requires-approval`: using the installed tool still crosses a runtime boundary.
- `blocked`: approval is not enough; policy says no.

For `lightningnode/voltage-sandbox`, the default `balanced` policy sees a `verified-runtime`, medium-risk package. That means safe read-only trials are allowed, but installing it or running live commands still needs approval. Under `safe`, `try` is blocked because the safe profile only allows low-risk packages.

Advanced users can select a different profile:

```bash
cap info lightningnode/voltage-sandbox --policy-profile safe --json
CAP_POLICY_PROFILE=power cap try lightningnode/voltage-sandbox --json
```

Supported profiles:

- `balanced`: default; reviewed medium-risk packages may run declared safe trials.
- `safe`: stricter; only low-risk reviewed packages.
- `prototype-local`: looser prototype experimentation.
- `power`: broader local experimentation while keeping installs and runtime calls approval-gated.

Advanced users can also use a JSON overlay:

```bash
cap resolve "set up a voltage sandbox node" --policy-file ./cap-policy.json --json
```

Example:

```json
{
  "profile": "balanced",
  "autonomous_install": false,
  "max_risk": "medium",
  "min_review_tier": {
    "install": "verified-runtime"
  }
}
```

Resolver and info payloads include normalized `review`, `policy_decision`, the effective policy summary, and per-check pass/fail metadata. `cap try`, `cap add`, and `cap run` enforce hard `blocked` decisions. `requires-approval` remains usable after an explicit prompt or `--yes`, depending on the command.

## Registry

The prototype registry is checked in at:

```text
registry/packages.json
```

Use a different registry with:

```bash
cap resolve "set up a voltage sandbox node" --registry ./other-registry.json
cap search postgres --registry ./other-registry.json
CAP_REGISTRY=./other-registry.json cap search postgres
```

The next registry shape should include a capability card for every package:

```json
{
  "name": "lightningnode/voltage-sandbox",
  "kind": "cli-tool",
  "bestFor": ["create mutinynet voltage node", "inspect voltage sandbox lnd status"],
  "agentInterface": {
    "commands": ["brief", "report", "doctor", "credentials"],
    "mcpTools": [],
    "skill": null,
    "rawCliOnly": true
  },
  "safeTrials": [
    {"command": "voltage-sandbox brief --json"},
    {"command": "voltage-sandbox doctor --json"}
  ],
  "permissions": {
    "filesystem": ["cap-state:read", "cap-state:write"],
    "network": ["api.voltage.cloud"],
    "secrets": ["voltage-api-key", "voltage-node-password"]
  }
}
```

For the current prototype, `lightningnode/voltage-sandbox` is enough to prove the loop. Future registries need this metadata for millions of CLI packages.

## Install Store

Default package scope:

```text
./.cap/
```

Global package scope:

```text
~/.cap/
```

Override:

```bash
node src/cap.js add lightningnode/voltage-sandbox --yes --global
CAP_HOME=/tmp/cap-demo node src/cap.js add lightningnode/voltage-sandbox --yes --global
```

Project `cap add` writes a JSON `Capfile` and `Capfile.lock` next to the active project:

```json
{
  "schema": "capfile.v0",
  "version": 1,
  "capabilities": [
    "lightningnode/voltage-sandbox@0.1.7"
  ],
  "policy": {
    "profile": "balanced"
  }
}
```

The lockfile records the resolved registry source, install backend/source, review summary, policy decision, and a reviewable install plan. `cap install` and `cap sync` install from `Capfile.lock` without needing to reload the registry, but they still apply the active local policy before installing. `cap run` also falls back to lockfile review metadata when the registry is unavailable.

## Supported Install Backends

### `local-bin`

Symlinks a reviewed local executable into the active package scope's `bin` directory.

This remains useful for reviewed repo-local tools and development fixtures. It is acceptable for the prototype, but large-scale autonomous agent use should prefer `cap run` or host-registered MCP tools over ambient PATH lookup.

### `single-file-url`

Downloads one executable file, optionally verifies SHA-256, marks it executable, and links it into the active package scope's `bin` directory.

This gives the prototype a real download path while avoiding arbitrary install scripts. It is the backend used by the checked-in `lightningnode/voltage-sandbox` package.

## Complete Uninstall

Use the built-in uninstall command:

```bash
cap uninstall
```

This removes:

- the local cap store, normally `~/.cap`
- installed CLI links under `~/.cap/bin`
- the PATH line the installer added to the shell profile
- the CAP Codex skill and MCP config entry, when present
- CAP Claude Code MCP config entries and marked `CLAUDE.md` sections recorded during `cap setup claude`

For Claude Code projects set up before host tracking existed, include the project path:

```bash
cap uninstall --project .
```

To preview the removal plan without deleting anything:

```bash
cap uninstall --json
```

Manual fallback:

```bash
rm -rf "$HOME/.cap"
```

Then remove this line from `~/.zshrc`, `~/.bashrc`, or `~/.profile`:

```bash
export PATH="$HOME/.cap/bin:$PATH"
```

## Non-Goals For This Iteration

- No paywalls.
- No arbitrary shell installer scripts.
- No dependency resolution.
- No OCI/MCPB unpacking yet.
- No background daemon.
- No publisher auth.
- No remote publish endpoint yet; publishing is local registry JSON only.
- No remote MCP attachment.
- No claim that registry review replaces local host policy.
- No autonomous access to secrets without human or policy approval.

## First Quality Bar

A fresh Codex- or Claude-assisted user should be able to:

1. Resolve a task to `lightningnode/voltage-sandbox`.
2. Inspect why it matched and what it can access.
3. Try safe read-only commands such as `brief --json` or `doctor --json`.
4. Install the package after seeing exact actions.
5. Run `cap run lightningnode/voltage-sandbox -- brief`.
6. Run `voltage-sandbox credentials --gui` when human secret entry is needed.
7. Have the CLI save secrets in macOS Keychain by default on macOS, or in `~/.cap/secrets/voltage-sandbox/credentials.env` with private file permissions and a warning elsewhere.