# GitHub Showcase: Quickstart

## Requirements

- Node.js 18 or newer.
- An external agent command for live reviews, such as Claude Code, Codex, or an
  HTTP agent endpoint.

The tamper-evidence demo does not need an agent, API key, or cloned repo.

## Install

`npx cool-workflow …` needs no install. To put `cw` on your PATH, pick one:

**npm**

```bash
npm install -g cool-workflow
```

**Homebrew** — one tap of this repo; there is no separate `homebrew-*` tap repo:

```bash
brew tap coo1white/cool-workflow https://github.com/coo1white/cool-workflow
brew install coo1white/cool-workflow/cool-workflow
cw version   # prints the installed release
```

Upgrade later with `brew update && brew upgrade cool-workflow`. The formula
pins its source to the matching git tag, so `brew install` works without a new
release and needs no checksum step.

> If you also have an npm-global `cw`, the one earlier in your PATH wins when you
> type `cw`. To run the Homebrew build for sure, use its full path:
> `"$(brew --prefix)/bin/cw" version`.

## 1. Prove The Integrity Demo

```bash
npx cool-workflow demo tamper
```

Expected result: stdout ends with a `VERDICT: tamper-evidence holds` line. The
demo builds a signed report and forges it three ways — flipping a ledger verdict,
reusing a signature over inflated tokens, and editing a signed finding — and shows
all three being detected offline, with only the public key.

For a scriptable proof payload:

```bash
npx cool-workflow demo tamper --json
```

The JSON includes `proven: true`, the number of ledger records, and one result
per tamper layer.

## 2. Run A Real Repo Review

```bash
npx cool-workflow quickstart architecture-review \
  --repo /path/to/your/project \
  --question "What are the main risks in this codebase?" \
  --agent-command builtin:claude
```

Or point it at a folder from anywhere, or a remote repo by URL — no `cd` needed:

```bash
cw -q "What are the main risks here?" -dir /path/to/your/project
cw -q "What are the main risks here?" --link https://github.com/owner/repo
cw -q "What are the main risks here?" --link https://github.com/owner/repo/archive/refs/heads/main.tar.gz
```

`--link` clones any git host (or downloads a `.tar.gz`/`.zip`) into a content-addressed,
fail-closed cache and reviews the checkout. The report records `Source: <url>@<commit>`
plus a tamper-evident audit event; manage the cache with `cw clones list` / `cw clones gc`.
Validate a URL without fetching: `cw -q "…" --link <url> --check`.

While it runs you get a **calm, Claude-Code-style live view** — a compact rolling window that updates
in place instead of an endless wall:

```text
● Read(execution-backend.ts)
  ⎿ 910 lines
● Grep(spawnSync)
  ⎿ 17 matches
✶ Searching worker-isolation.ts… (3s)
```

Each tool folds to a `● ToolName(arg)` line with a dim `⎿` result summary; older steps fold away (the
window stays a few rows) and the worker collapses to one line when done. It's compact by default
(reasoning hidden); `--verbose` shows the full agent narration, `--full` also prints the report inline,
and `--no-color` drops ANSI (`NO_COLOR` / `FORCE_COLOR` are honored). The complete narration + tool I/O
is always saved to a per-worker `transcript.md`, and at the end CW prints a **compact findings table**
(id / severity / classification) with the report path and the run dir. It's vendor-neutral — CW renders
this itself for any agent backend (Claude / Codex / Gemini / OpenCode), with the `⎿` result lines on
Claude today — and with `--json` stdout stays pure data (all the chrome goes to stderr, on a TTY only).

The command prints JSON that includes a `runId`, status, worker counts, and a
`reportPath`.

Read the report:

```bash
cat /path/to/your/project/.cw/runs/<run-id>/report.md
```

If the agent is not configured, CW returns `status: blocked`. That is expected
fail-closed behavior: the run is saved for triage, but CW does not fabricate a
completed report.

Check the agent backend before a live run:

```bash
cw backend probe agent --json
```

When no command or endpoint is configured, the probe reports `ready: false` and
a reason naming the missing `CW_AGENT_COMMAND` or `CW_AGENT_ENDPOINT`.

## 3. Try A Resumable Run

Advance one step and stop:

```bash
cw quickstart architecture-review \
  --repo /path/to/your/project \
  --question "What should I audit first?" \
  --agent-command builtin:claude \
  --resume
```

Continue the same run:

```bash
cw quickstart architecture-review --run <run-id> --resume
```

You can also resume through the registry:

```bash
cw run resume <run-id> --drive
```

The default `run resume` view is read-only. Adding `--drive` hands pending work
to the existing agent delegation loop.

Re-running after a change? Add `--incremental` and CW reuses the cached result of
every step whose inputs are unchanged, so only the first changed task and what
depends on it run again:

```bash
cw run <app> --drive --incremental
```

## 4. Hand The Report To Someone (Verify Offline)

Seal a finished run into one portable file. The recipient needs nothing but the
file and the public key:

```bash
cw -q "…" --bundle                              # seal the run into report.cwrun.json
cw report verify-bundle report.cwrun.json       # they check it offline
cw report verify-bundle report.cwrun.json \
  --require-signatures                          # …and insist the findings are signed
```

`verify-bundle` re-proves the archive bytes, the telemetry and trust-audit chains,
and the ed25519 signatures, and confirms every signed finding is in the report
unaltered — all offline, with only the public key. See
[Trust And Audit](GitHub-Showcase-Trust-And-Audit.md) for exactly what this proves.

## From A Source Checkout

```bash
cd plugins/cool-workflow
npm install
npm run build
node scripts/cw.js app list
node scripts/cw.js demo tamper
```

Run the deterministic integration proof:

```bash
npm run golden-path
```

It exercises app validation, planning, dispatch, worker output, candidate
selection, verifier-gated commit, report generation, status, and graph views.

## Troubleshooting

| Symptom | What to do |
| --- | --- |
| `status: blocked` | Configure an agent with `--agent-command`, `CW_AGENT_COMMAND`, or `CW_AGENT_ENDPOINT`. |
| `claude: command not found` | Install Claude Code or use another agent command. |
| You want to see the next action only | Add `--preview`; it is read-only. |
| You want one step at a time | Add `--resume`, then continue with the printed `--run <run-id>` command. |
| You need a shorter review | Try `architecture-review-fast`; see [Workflow Apps](GitHub-Showcase-Workflow-Apps.md). |

## Next Pages

- [Workflow Apps](GitHub-Showcase-Workflow-Apps.md)
- [Trust And Audit](GitHub-Showcase-Trust-And-Audit.md)
- [Recovery And Restore](GitHub-Showcase-Recovery-And-Restore.md)