/setup

description: Set up AKA Security — calibrate notifications and detection posture from Claude's real activity.

AKA setup wizard

You are onboarding the AKA Security plugin for this machine. AKA works fully locally with **zero backend and zero Docker**: detection runs in-process and findings persist to a local SQLite store at `~/.aka/data/aka.db`.

This wizard tells a **calibration story**: introduce AKA → show what it does → offer one retroactive scan → report the real numbers it found and the posture it recommends → apply on confirmation → show the installed summary → hand off to the dashboard. Everything the user sees is derived from their _actual_ history — never a fabricated or demo number. When there isn't enough history to judge, the wizard falls back to a conservative severity-derived floor instead of guessing.

The false-positive/severity judgment needs the raw (unmasked) findings to rate them accurately, so it **sends them to the model API** through separate `claude` CLI subprocesses (a large history is judged in several batches). Per finding it sends the **raw value**; about **120 characters of the surrounding transcript text** on either side of it, re-scanned first so every secret AKA's rules detect in that window is masked — including the finding's own value where it appears there, which leaves the raw value itself as the only raw text that crosses; and the finding's non-sensitive labels (rule id, category, severity, the masked value, the confidence score, and a counter the model echoes back). The source transcript's **path never crosses**. Those subprocesses ask the `claude` CLI to write no transcript, so the raw values do not enter this conversation or your scannable history — but a copy of them **does leave the machine**, sent to the model provider like any other Claude prompt. You act only on the raw-free plan the subprocesses print back.

That send takes **two separate consents**, collected at two different points and neither implying the other: the **historical-read** grant in step 1 (may AKA read past transcripts at all) and the **model-judge** grant in step 3 (may what it found be sent to the model API). Each is stated plainly before its own picker, and the judge refuses to run without the step-3 grant. The vault grant in step 1b is a third, separate question about **local** custody — it authorizes no send, and nothing about it changes what leaves the machine.

Follow the steps below **in order**. Nothing is written to the policy store until step 5 (or a floor fallback in step 3 if the calibration can't complete).

Execution contract (read before step 0)

Every script prints output in three region kinds. Your job for each is fixed:

• **`<<<AKA_SHOW … AKA_SHOW>>>`** — relay every AKA_SHOW region verbatim as your

next message: paste the content _between_ the markers exactly — a card region carries its own code fence, a plain confirmation line does not, but either way you paste exactly what's between the markers — never the marker lines, never a paraphrase or summary.

• **`<<<AKA_FRAME_JSON … AKA_FRAME_JSON>>>`** — machine-only. Parse it if a step

tells you to read a value from it; never display it.

• **Anything else on stdout** — status for you (paths like `Plan saved to:`,

errors, exit signals). Act on it; never relay it.

Invariants:

• **Never write a confirmation or acknowledgement the wizard did not emit** — the

script's AKA_SHOW line is the confirmation.

• **Each step's AKA_SHOW regions must be relayed before you advance.**
• **One picker per decision; never re-ask a decision already collected.**

0. Show the intro card

Run the intro script and relay its AKA_SHOW region per the execution contract: paste the content between the markers verbatim, never the marker lines. It prints a single space-aligned monospace card — identity and provenance, then what AKA does — inside a Markdown code fence that is part of that pasted content. Keep the fence as printed and do **not** add another code fence, strip the fence, or reformat it (unfenced, Markdown collapses the indentation and mangles the `●` lines).

node "${CLAUDE_PLUGIN_ROOT}/scripts/intro.js" "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json"

0b. Repo-aware posture check — tighten-only, working-tree only

Before showing any recommended posture — the start-light default table in step 2 or the calibrated posture in step 4 — look at the **current project's** working tree yourself, with your own Read/Glob tools. There is no script for this: it is your own reasoning over facts you read directly, not the triage subprocess's raw-free plan, and it needs no user interaction.

**In scope:** the manifest's declared frameworks/dependencies (`package.json` or equivalent), payment or other third-party API SDKs among them, CI config (`.github/workflows/`, etc.), and the **presence and names** of `.env*`/config files as a signal that secrets live on disk here — never their contents; a secret-bearing file's contents are exactly the kind of raw value this wizard never reads. **Out of scope:** Claude's own history and the local AKA store (that is the separate, consent-gated scan in steps 1/3) — no historical read, and no AskUserQuestion or other consent interaction of any kind.

The severity-floor default map (secret/pii/financial/phi/code_flaw/custom at `warn`, code_context/config at `monitor` — the table step 2's start-light card prints) is both the **floor** this check is measured against and its **fallback**. From what you directly observe you may **tighten** individual categories above that floor — raise the level, never lower one below it — each tightened category carrying a one-line rationale naming the concrete evidence you found, e.g.:

> Stripe + a `Customer` model here — financial → redact

Present the tightening on whichever recommended posture is about to render, the same "recommended base + changed-packs overlay" shape step 4b's adjust fork uses: the tightened categories ra