# Set up Vizzy

You are a coding agent, and your user wants Vizzy set up on this machine. Work through
the steps below in order. Every step is idempotent — check first, skip what's already
in place, and never use `sudo` without asking the user. When you're done, report what
you installed and suggest the "First diagram" step at the bottom.

## What Vizzy is

Vizzy renders diagrams from plain Markdown files that live in a repo next to the code —
architecture maps, sequence flows, flowcharts, class/ER/state diagrams, gantts, mind
maps, and more. Coding agents (you) author the `vizzy/*.vizzy.md` files; the native
macOS app renders them on an infinite canvas and live-reloads as the files change.

Three pieces, installed below:

1. **The Vizzy app** — the macOS viewer/editor, with built-in agent terminals.
2. **The `vizzy` CLI** — the same engine headless: render diagrams to PNG, lint files,
   publish shareable links, and drive the running app. This is how you check your work.
3. **The vizzy skill** — teaches any agent the authoring format. Installed globally so
   every repo on this machine gets it.

Docs: https://docs.usevizzy.com · Site: https://usevizzy.com

**Requires macOS.** If this machine isn't a Mac, stop here and tell the user: the app is
macOS-only for now, but published diagrams and the playground work in any browser at
https://usevizzy.com.

## Step 1 — Install the app

Skip this step if the app is already installed (`open -Ra Vizzy` succeeds) — it keeps
itself up to date.

```sh
TMP="$(mktemp -d)"
curl -fL -o "$TMP/Vizzy.dmg" https://usevizzy.com/download
mkdir "$TMP/mnt"
hdiutil attach "$TMP/Vizzy.dmg" -nobrowse -readonly -mountpoint "$TMP/mnt"
ditto "$TMP/mnt/Vizzy.app" /Applications/Vizzy.app
hdiutil detach "$TMP/mnt"
rm -rf "$TMP"
```

If `/Applications` isn't writable (non-admin account), install to `~/Applications`
instead. The app is signed and notarized.

Then launch it once — this registers the app, starts automatic updates, and installs the
`vizzy` CLI automatically when `/usr/local/bin` is writable:

```sh
open -a Vizzy
```

## Step 2 — Install the `vizzy` CLI

Skip this step if `vizzy version` already works (launching the app in Step 1 may have
installed it for you).

```sh
APP=/Applications/Vizzy.app/Contents/MacOS/Vizzy   # adjust if installed elsewhere
"$APP" help | grep -q install-cli && "$APP" install-cli
```

- If it reports that `/usr/local/bin` needs admin rights, do **not** run sudo yourself —
  show the user the printed `sudo … install-cli` command to run in their own terminal,
  or tell them to click **Vizzy ▸ Install Command Line Tool…** in the app (one admin
  prompt).
- If `help` doesn't list `install-cli`, the installed app predates it (don't run it —
  an unknown subcommand falls through to launching the app) — the menu item above is
  the way.

Once installed, the launcher stays current on its own: each time the app opens it
re-points `vizzy` at the running copy, so updates never break the command.

## Step 3 — Install the vizzy skill globally

The skill teaches agents where diagrams live, the file format, annotations, and how to
lint their work. Install it globally (user-level, all repos) rather than per-project:

```sh
npx -y skills add lloydhumphreys/skills --skill vizzy -g -y
```

Pass `--agent <name>` to target the agent(s) in use — e.g. `--agent claude-code`,
`--agent cursor`, or `--agent '*'` for all. For Claude Code this lands the skill in
`~/.claude/skills/vizzy/`.

If Node.js/`npx` isn't available, copy it by hand instead:

```sh
TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/lloydhumphreys/skills "$TMP/skills"
# copy into your agent's global skills dir — for Claude Code that is:
mkdir -p ~/.claude/skills
cp -R "$TMP/skills/SKILLS/vizzy" ~/.claude/skills/vizzy
```

To update later: `npx -y skills update vizzy` (or re-run the add command).

## Verify

```sh
vizzy version        # prints the installed app version
vizzy help           # lists subcommands: render, lint, publish, state, focus, …
```

Optionally prove the render pipeline end to end: write a two-line flowchart into a
temporary `test.vizzy.md` and run `vizzy render test.vizzy.md -o <tmpdir>`, then confirm
a PNG appeared.

## First diagram

Suggest this to the user once setup is done. In a repo of theirs, use the vizzy skill to
author `vizzy/architecture.vizzy.md` — explore the real code first, then diagram what's
actually there. Check the work with `vizzy lint`, then run `vizzy` in the repo (or
`open -a Vizzy`) so they can see it rendered live. The app's document window also has a
built-in terminal that runs `claude` or `codex` next to the canvas, so they can keep
iterating on diagrams from inside Vizzy.