onlyharness

# SuperSkill

[superskill.sh](https://superskill.sh) is the single human-facing product for finding and installing reviewed AI-agent capabilities. It preserves existing registrations and workspaces, exposes one universal install link for Codex and Claude Code, and keeps exact release, trust, revocation and consent gates explicit.

The old OnlyHarness UI and host are compatibility-only: human routes redirect to SuperSkill, while old API/MCP coordinates, npm/package names, database identifiers and immutable archive URLs remain available for installed clients and data continuity. Internal package names still use `@harnesshub/*`; the published compatibility CLI package remains `onlyharness`.

## What is a native harness package?

A native harness package is the strict, verified package format inside the broader OnlyHarness resource catalog:

- `harness.yaml` manifest with runtime, tools, permissions, quality gates, and risk profile.
- Prompt, examples, eval cases, and expected outputs.
- CLI commands for validate, eval, gate, diff, import, and PR annotation.
- Social layer: stars, server-side remix forks, threads, verified gate runs, install confirms, heat, tags, outcomes, and maintainer review.

## Live MVP

- App: [https://superskill.sh](https://superskill.sh)
- API health: [https://superskill.sh/api/healthz](https://superskill.sh/api/healthz)
- Registry API: [https://superskill.sh/api/registry](https://superskill.sh/api/registry)
- Universal installer manifest: [https://superskill.sh/api/superskill/install](https://superskill.sh/api/superskill/install)

Supabase auth is enabled for signup/login, stars, local remix drafts, thread posts, and authenticated publish.

## Features

- HuggingFace-style discovery for agent resources, wrapped in a Win98 desktop with a real window manager (drag, minimize, z-order, taskbar, Start menu).
- Outcome filters, global search, leaderboard, Harness Heat, stars, server-side remix fork counters, threads, and verified gate-run counters.
- Harness detail opens as its own window with Overview, Install, Trust, Try sample, Thread, Files, and Versions tabs plus a plain-tone trust panel; Versions is backed by archive snapshot history.
- Authenticated quick publish flow (`New Resource Wizard`) that imports markdown into a small unverified scaffold.
- Share card window (`harness_flex.exe`), Wild West awards, Paint heat chart, and a paperclip mascot that opens the wizard.
- CLI package `onlyharness` with `hh` compatibility commands plus `superskill install`; `HH_REGISTRY_URL` targets another registry, default `https://superskill.sh/api`.
- Agent-friendly discovery: [`/llms.txt`](https://superskill.sh/llms.txt), [`/api/openapi.json`](https://superskill.sh/api/openapi.json), [`/server.json`](https://superskill.sh/server.json), and [`/mcp`](https://superskill.sh/mcp).
- Local bounty flow: create/claim/deliver/accept work-state over the existing `gate_escrow` rail; `paid` is set only after a matching escrow purchase captures against the delivered gate receipt.
- Semantic PR review and quality gate sidecar API.
- Docker production stack with system Caddy deployment mode for shared VPS hosts.

## Architecture

```mermaid
flowchart LR
  Web["React/Vite UI"] --> API["Fastify Harness API"]
  API --> Seeds["Seed harnesses"]
  API --> Imports["Imported harnesses"]
  Web --> Supabase["Supabase Auth + RLS tables"]
  API --> SupabaseAuth["Supabase token verification"]
  Caddy["System Caddy / superskill.sh"] --> Web
  CLI["hh CLI"] --> Schema["Schema, eval, gate, diff"]
```

## Run locally

```bash
npm install
npm run seed
npm run check
npm run smoke
npm run dev
```

Open:

- UI: `http://127.0.0.1:5177`
- API: `http://127.0.0.1:8787/healthz`
- Local Gitea forge: `http://127.0.0.1:3000`

## Operator Payouts

Payout reporting and ledger creation are manual-ops only. The script reads settled `purchases` plus `payout_accounts`, applies the current rates, and can create an idempotent draft payout ledger. It never calls a payout provider and never marks items paid.

```bash
npm run payout:report -- --month 2026-07
npm run payout:report -- --month 2026-07 --json
npm run payout:ledger -- --month 2026-07 --ledger-out data/payout-ledgers/2026-07.json
```

Use `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY`, or local JSON fixtures via `--purchases` and `--payout-accounts`. `--record-ledger` upserts `payout_runs`/`payout_items` through Supabase service role. Rows without `creator_user_id` are marked `MISSING_CREATOR_ID`; rows without payout account are blocked as `MISSING_PAYOUT_ACCOUNT`.

## CLI

The npm package is published:

```bash
npx onlyharness@latest search market research
npx onlyharness@latest suggest market research --json
npx onlyharness@latest resources search superpowers --json
npx onlyharness@latest resources detail github:obra/superpowers --json
npx onlyharness@latest resources open github:obra/superpowers --json
npx onlyharness@latest resources approve onlyharness:harnesses/deep-market-researcher --workspace acme --collection approved --json
npx onlyharness@latest install harnesses/deep-market-researcher --target claude-code --json
npx onlyharness@latest publish-resource ./agent-tool --name agent-tool --type command_pack --json
npx onlyharness@latest publish-resource ./agent-tool --workspace acme --name agent-tool --type command_pack --json
npx onlyharness@latest mcp-config deep-market-researcher --target claude-desktop --json
npm i -g onlyharness   # installs the `hh` command
```

Resource catalog, immutable `publish-resource`, workspace approval/setup/gates, membership expiry, the manual/provider-agnostic workspace subscription lifecycle, universal install, and SuperSkill managed commands are available in published `onlyharness@0.2.19`; `0.2.18` is a known-bad one-link release because its published universal-skill digest is stale. Server catalog flows are also available through MCP/HTTP.

For local development, build the workspace bundle and run it directly:

```bash
npm run build -w onlyharness
node packages/harness-cli/dist/hh.mjs doctor
node packages/harness-cli/dist/hh.mjs audit-setup
node packages/harness-cli/dist/hh.mjs suggest market research --apply --out suggested-deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs suggest market research --apply --target codex --out suggested-deep-market-researcher --adapter-out .codex/harnesses/deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs install harnesses/deep-market-researcher --target codex --out deep-market-researcher --adapter-out .codex/harnesses/deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs pull harnesses/deep-market-researcher --version 0.1.0 --out deep-market-researcher-0.1.0 --json
node packages/harness-cli/dist/hh.mjs mcp-config deep-market-researcher --target claude-desktop --out mcp.json
node packages/harness-cli/dist/hh.mjs benchmark benchmarks/research-discovery.yaml --json
node packages/harness-cli/dist/hh.mjs extract ~/.claude/skills/my-skill --out my-skill-harness
HH_TOKEN=<token> node packages/harness-cli/dist/hh.mjs publish git@github.com:acme/harnesses.git --path harnesses/my-harness --name my-harness --json
HH_TOKEN=<token> node packages/harness-cli/dist/hh.mjs publish-resource ./agent-tool --name agent-tool --type command_pack --json
HH_TOKEN=<token> node packages/harness-cli/dist/hh.mjs publish-resource https://github.com/acme/agent-tool.git --path packages/tool --name agent-tool --type command_pack --json
HH_WORKSPACE_TOKEN=<workspace-token> node packages/harness-cli/dist/hh.mjs publish-resource ./agent-tool --workspace acme --name agent-tool --type command_pack --json
HH_WORKSPACE_TOKEN=<workspace-token> node packages/harness-cli/dist/hh.mjs resources search agent-tool --workspace acme --json
HH_WORKSPACE_TOKEN=<workspace-token> node packages/harness-cli/dist/hh.mjs resources detail @acme/agent-tool --json
HH_WORKSPACE_TOKEN=<workspace-token> node packages/harness-cli/dist/hh.mjs workspace setup acme --target claude-code --json
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs setup @acme
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs publish workflow.md --org acme --name my-private-harness
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs sync git@github.com:acme/skills.git --org acme
TELEGRAM_BOT_TOKEN=<bot-token> HH_ORG_TOKEN=<org-token> TELEGRAM_CHANNEL_ID=<channel-id> npm run telegram:gate-bot
```

## SuperSkill internal alpha

SuperSkill is the task-first managed capability layer built on OnlyHarness. The checked-in catalog currently contains 12 exact immutable **candidates** and intentionally exposes zero approved showroom items until real Claude Code, Codex, and human review attestations exist.

- Public, read-only: `GET /api/showroom/capabilities` and `GET /api/showroom/capabilities/{id}`. These routes never recommend, download, or activate files.
- Selected shelf: `GET /api/showroom/selected` exposes the current reviewed-intake candidates as `selected_unreviewed` cards. They can fill the Daylight catalog, but cannot be recommended or activated until exact-release approval evidence exists.
- Confirmed-user Bearer: `/api/recommendations`, `/api/capabilities/{id}`, exact release/archive routes, hosted proof publish and managed lifecycle events use one confirmed Supabase user credential plus an active server-side `superskill:managed` grant. Headless clients inherit `HH_TOKEN` explicitly. `HH_SUPERSKILL_TOKEN` is legacy internal-alpha compatibility only and cannot produce public-GO evidence.
- Managed CLI release: `onlyharness@0.2.19` is the current one-link release, published and verified through a clean `npx` install, and pinned to official npm integrity in `plugins/superskill/runtime.json`. It binds hosted skill detail, archive headers and archive bytes to one immutable version/digest/size/trust tuple. `0.2.14` and `0.2.18` are known-bad one-link releases; never substitute `latest` for the exact runtime pin.
- Web: the Sup