Install Prompt

# Understand First — Install

Install the "Understand First" hook into the current Claude Code environment — cross-platform (Windows / macOS / Linux).

This is the agent-driven installer. Its installed result is equivalent to `hooks/install.sh`: the same enforcement preamble + full protocol injected as `additionalContext` on every user input. Use it where `curl | sh` cannot run (notably native Windows), or whenever an agent-driven install is preferred.

## Goal

After installation, every time the user submits a prompt, Claude Code must display its understanding of the request BEFORE taking any action. This is achieved by registering a `UserPromptSubmit` hook that injects the protocol as `additionalContext`.

## Operating Rules

- Do NOT use `sudo`.
- Do NOT overwrite existing user files without explicit permission — append or merge instead.
- All operations must be idempotent — running the install twice must equal running it once.
- Back up any file before modifying it (save as `<filename>.bak`), then write via temp-file + atomic rename (never overwrite in place — an interrupted write corrupts the file).
- Resolve every path to an **absolute** path before writing it anywhere (especially into `settings.json`). Never write `~`, `$HOME`, or `%USERPROFILE%` placeholders into the registered command — Claude Code does not expand them reliably across platforms.
- Serialize JSON only through a JSON library (`json.dumps` / `ConvertTo-Json` / `jq`). **Never hand-build JSON** from the protocol text — it contains quotes, newlines, and unicode that will break naive string concatenation.
- Prefer Python for the hook (cross-platform, guaranteed-correct JSON via `json.dumps`, and `Path.home()` resolves the profile dir on every OS). Fall back to PowerShell (Windows) or POSIX `sh` + `jq` (Unix) only when no Python is available.

## Success Criteria

All of the following must be true after installation:

1. `~/.claude/hooks/understand-first-hook.py` exists, alongside `~/.claude/hooks/understand-first-protocol.txt` (the raw preamble + protocol, UTF-8).
2. Executing the **registered command** outputs valid JSON to stdout:
   ```json
   {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "<preamble + protocol>"}}
   ```
3. `additionalContext` starts with the enforcement preamble and contains the full protocol (non-empty, contains `Understand First`).
4. `~/.claude/settings.json` has a `UserPromptSubmit` entry whose `command` invokes the hook by absolute path.
5. `~/.claude/CLAUDE.md` contains the Understand First anchor line.

## Steps

### 1. Detect platform & interpreter

- Determine OS (Windows / macOS / Linux).
- Probe for a Python interpreter in this order; record the **first that runs** and prints a version: `py -3`, then `python3`, then `python`. Store the invocation prefix (e.g. `py -3`, `python3`, `python`) as `PY`.
- Resolve the hooks directory: `~/.claude/hooks` (use the Python `Path.home()` equivalent — do NOT assume `~` in strings).
- If **no Python at all** is found: use the **Fallback (no Python)** path below. If the fallback runtime is also unavailable (no PowerShell on Windows, no `jq` on Unix), STOP and ask the user to install Python 3.

### 2. Fetch the protocol

Resolve the protocol text in this order (mirrors `install.sh`):

1. **Offline first** — if a file `./CLAUDE.md` in the current working directory exists and its first line is exactly `# Understand First`, read it locally. No network needed. (This only applies when running inside a clone of this repo; the H1 check prevents injecting some other project's CLAUDE.md.)
2. Otherwise WebFetch: `https://raw.githubusercontent.com/luckybilly/understand-first/main/en-US/CLAUDE.md`
3. If the fetch fails, ask the user to paste the protocol content manually. Do not proceed with empty protocol text.

### 3. Create the hook (two self-contained files)

Create `~/.claude/hooks/` if needed, then write **two** files:

**`understand-first-protocol.txt`** — the raw injected context, UTF-8, no escaping: