@akasecurity/ai-tc-codex 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,830 @@
1
+ ---
2
+ name: aka-setup
3
+ description: Set up AKA Security — calibrate notifications and detection posture from Codex's real activity.
4
+ ---
5
+
6
+ # AKA setup wizard
7
+
8
+ You are onboarding the AKA Security plugin for this machine. AKA works
9
+ fully locally with **zero backend and zero Docker**: detection runs in-process
10
+ and findings persist to a local SQLite store at `~/.aka/data/aka.db`.
11
+
12
+ This wizard tells a **calibration story**: introduce AKA → show what it does →
13
+ offer one retroactive scan → report the real numbers it found and the posture it
14
+ recommends → apply on confirmation → show the installed summary → hand off to the
15
+ dashboard. Everything the user sees is derived from their _actual_ history — never
16
+ a fabricated or demo number. When there isn't enough history to judge, the wizard
17
+ falls back to a conservative severity-derived floor instead of guessing.
18
+
19
+ The false-positive/severity judgment needs the raw (unmasked) findings to rate
20
+ them accurately, so it **sends them to the model API** through separate `codex`
21
+ CLI subprocesses (a large history is judged in several batches). Two things
22
+ cross for each finding: its **raw value**, and about **120 characters of the
23
+ surrounding transcript text** on either side of it — re-masked first, so any
24
+ _other_ detectable secret in that window never leaves raw. The rollout file's
25
+ path, the value's fingerprint, and the fingerprint key version are **dropped
26
+ before egress**. Those subprocesses run the `codex` CLI ephemerally so the raw
27
+ values are never written into `~/.codex/sessions` — they do not enter this
28
+ conversation or your scannable history — but ephemeral mode is a local-write
29
+ guard, **not network isolation**: a copy of the value **does leave the
30
+ machine**, sent to the model provider like any other Codex prompt. You act only
31
+ on the raw-free plan the subprocesses print back. Reading history is granted in
32
+ step 1; **sending findings to the model is a distinct consent, collected in
33
+ step 3 before the judgment pipe runs** — the judge refuses to run without it.
34
+
35
+ Follow the steps below **in order**. Nothing is written to the policy store
36
+ until step 5 (or a floor fallback in step 3 if the calibration can't complete).
37
+
38
+ ## Execution contract (read before step 0)
39
+
40
+ Every script prints output in three region kinds. Your job for each is fixed:
41
+
42
+ - **`<<<AKA_SHOW … AKA_SHOW>>>`** — relay every AKA_SHOW region verbatim as your
43
+ next message: paste the content _between_ the markers exactly — a card region
44
+ carries its own code fence, a plain confirmation line does not, but either way
45
+ you paste exactly what's between the markers — never the marker lines, never a
46
+ paraphrase or summary.
47
+ - **`<<<AKA_FRAME_JSON … AKA_FRAME_JSON>>>`** — machine-only. Parse it if a step
48
+ tells you to read a value from it; never display it.
49
+ - **Anything else on stdout** — status for you (paths like `Plan saved to:`,
50
+ errors, exit signals). Act on it; never relay it.
51
+
52
+ **Collecting a decision.** Wherever a step asks the user a question, ask it as a
53
+ normal conversational turn with numbered options for the user to pick from. This
54
+ wizard depends on no specific interactive-picker tool being available — present
55
+ each option clearly and wait for the user's reply before moving on. If Codex
56
+ exposes a native multi-choice picker in your environment, prefer that over plain
57
+ text; otherwise the numbered-list form is the fallback. Never answer a question
58
+ on the user's behalf.
59
+
60
+ Invariants:
61
+
62
+ - **Never write a confirmation or acknowledgement the wizard did not emit** — the
63
+ script's AKA_SHOW line is the confirmation.
64
+ - **Each step's AKA_SHOW regions must be relayed before you advance.**
65
+ - **One question per decision; never re-ask a decision already collected.**
66
+
67
+ ## 0. Show the intro card
68
+
69
+ Run the intro script and relay its AKA_SHOW region per the execution contract:
70
+ paste the content between the markers verbatim, never the marker lines. It
71
+ prints a single space-aligned monospace card — name, repository, version, and
72
+ what AKA adds — inside a Markdown code fence that is part of that pasted
73
+ content. Keep the fence as printed and do **not** add another code fence, strip
74
+ the fence, or reformat it (unfenced, Markdown collapses the indentation and
75
+ mangles the `●` lines).
76
+
77
+ ```bash
78
+ node "${PLUGIN_ROOT}/scripts/intro.js" "${PLUGIN_ROOT}/.codex-plugin/plugin.json"
79
+ ```
80
+
81
+ ## 0b. Repo-aware posture check — tighten-only, working-tree only
82
+
83
+ Before showing any recommended posture — the start-light default table in
84
+ step 2 or the calibrated posture in step 4 — look at the **current project's**
85
+ working tree yourself, with your own file-reading tools. There is no script for
86
+ this: it is your own reasoning over facts you read directly, not the triage
87
+ subprocess's raw-free plan, and it needs no user interaction.
88
+
89
+ **In scope:** the manifest's declared frameworks/dependencies
90
+ (`package.json` or equivalent), payment or other third-party API SDKs among
91
+ them, CI config (`.github/workflows/`, etc.), and the **presence and names**
92
+ of `.env*`/config files as a signal that secrets live on disk here — never
93
+ their contents; a secret-bearing file's contents are exactly the kind of raw
94
+ value this wizard never reads. **Out of scope:** Codex's own history and the
95
+ local AKA store (that is the separate, consent-gated scan in steps 1/3) — no
96
+ historical read, and no question or other consent interaction of any kind.
97
+
98
+ The severity-floor default map (secret/pii/financial/phi/code_flaw/custom at
99
+ `warn`, code_context/config at `monitor` — the table step 2's start-light card
100
+ prints) is both the **floor** this check is measured against and its
101
+ **fallback**. From what you directly observe you may **tighten** individual
102
+ categories above that floor — raise the level, never lower one below it —
103
+ each tightened category carrying a one-line rationale naming the concrete
104
+ evidence you found, e.g.:
105
+
106
+ > Stripe + a `Customer` model here — financial → redact
107
+
108
+ Present the tightening on whichever recommended posture is about to render, the
109
+ same "recommended base + changed-packs overlay" shape step 4b's adjust fork
110
+ uses: the tightened categories raise, every other category keeps its existing
111
+ recommended level, each carrying its rationale line. Where you compose the view
112
+ yourself (the adjust fork, the calibrated result) this tightened recommendation
113
+ IS that view; where the view is a script's AKA_SHOW card (the step-2
114
+ start-light card, relayed per the execution contract), show the tightened
115
+ recommendation and its rationale lines adjacent to that card rather than
116
+ rewriting the card's own printed levels.
117
+
118
+ This tightening is a **display-time recommendation**: it shapes the recommended
119
+ posture the user reads, not a separate write. Persisting a tightened level happens
120
+ only where the wizard already writes a per-category override — the adjust fork's
121
+ `onboard.js --posture` write (step 4b), where the user picks each category's level
122
+ explicitly. The keep-defaults path writes the severity floor (`--floor`, step 2)
123
+ and the calibrated accept path applies the triage subprocess's saved plan
124
+ verbatim (`--confirmed --plan`, step 5); neither carries the tightening on its
125
+ own, so a tightened level the user wants persisted is chosen through the adjust
126
+ fork. Do **not** bolt on an extra `onboard.js --posture` overlay to auto-re-persist
127
+ the tightening across the other paths: it would overwrite — and so could silently
128
+ **downgrade** — a category the user had hardened out of band (a tightening is only
129
+ guaranteed to raise above the severity floor, not above the user's stored level),
130
+ with no downgrade-approval gate. So the tightening is not auto-persisted across
131
+ those paths — a tightened level the user wants kept is set through the adjust fork.
132
+
133
+ **When nothing in the working tree is inferable, change nothing.** Render the
134
+ recommended posture exactly as the static frame already gives it — no rationale
135
+ line and no tightened category (fail-open).
136
+
137
+ ## 1. Offer the retroactive scan
138
+
139
+ Ask this **before** anything about detection posture — the posture
140
+ recommendation in step 4 is _derived from_ the answer to this question, so it
141
+ has to come first. Ask it per the execution contract's decision rules: a
142
+ conversational turn with numbered options, waiting for the user's reply.
143
+
144
+ **Disclose the model-API egress plainly before you show the options — this is what
145
+ the user is consenting to, so it must be visible before they choose.** State it in
146
+ your own words, without softening it: if they say yes, AKA scans the last 30 days
147
+ of Codex history, and to rate what it finds it **sends the raw, unmasked values —
148
+ including any secrets — to the model API through the `codex` CLI**. Name what
149
+ travels with each one: **its raw value, and about 120 characters of the
150
+ surrounding transcript text on either side** (any other secrets detected in
151
+ that window are masked; the rollout file's path stays local). That is real
152
+ network egress to the model provider (the same one your
153
+ Codex session already uses), not a purely local review. **A copy of each value
154
+ leaves the machine.** The rollouts those values came from stay on disk
155
+ untouched — nothing here removes them; that is the separate redaction step in
156
+ step 6. The values are kept out of your local Codex session history — the judge
157
+ subprocesses run ephemerally, so nothing lands in `~/.codex/sessions` — but that
158
+ is a local-write guard only, not network isolation. The findings are also
159
+ recorded, masked, to the local store. The grant is revocable from the
160
+ dashboard's **Settings → Historical access**, which stops future scans — it
161
+ cannot recall anything already sent. Do not present the options until you have
162
+ said this.
163
+
164
+ **Want me to look over what Codex has been up to?** — "I'll scan Codex's recent work — session rollouts, temp files, agent memory — and send what I find to the model to rate it, so I can tune what I bring you next."
165
+
166
+ Offer exactly two options:
167
+
168
+ 1. **Yes, take a look** — "scan my real work here; raw findings go to the model to be rated, then tune what you bring me"
169
+ 2. **Not now** — "start light and I'll learn as we go"
170
+
171
+ Choosing **Yes, take a look** records the same historical-review consent the wizard has
172
+ always recorded — the identical scope (which includes the model-API judgment disclosed
173
+ above), the one-time grant, and the same revocation semantics — so the simpler question
174
+ broadens nothing about what AKA may access. Those granular scope and revocation details
175
+ stay inspectable on request and in the dashboard, under **Settings → Historical access**,
176
+ whose own copy repeats the model-API disclosure.
177
+
178
+ ## 2. Save the answer, then branch
179
+
180
+ Branch on the answer from step 1. On the **Yes, take a look** path the onboarding
181
+ writer runs, and it must run **before** the backfill (step 3), because the
182
+ backfill script reads `historicalAccess` from the saved settings to decide
183
+ whether it's allowed to run. Omitting `--policy` is deliberate — the old global
184
+ redact/warn toggle no longer drives enforcement (posture is per-category now);
185
+ its field is kept for backward compatibility but this wizard doesn't ask about
186
+ it.
187
+
188
+ **Branch on the choice:**
189
+
190
+ - **If the user chose "Yes, take a look"** — record the historical-review consent and
191
+ continue to step 3 (which runs the scan and leads to the calibrated result in
192
+ step 4). "Yes, take a look" maps to the existing full historical-review path — no
193
+ access is granted beyond what that path already granted:
194
+
195
+ ```bash
196
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --historical full
197
+ ```
198
+
199
+ - **If the user chose "Not now"** — take the **start-light** path.
200
+ This path takes **zero historical access**: do **not** read any history, do
201
+ **not** run the backfill, and do **not** record consent — nothing about the
202
+ machine's past is touched.
203
+ Instead present the start-light posture card, write the posture the user picks
204
+ (this write **is** the applying frame — it stands in for step 5, which never
205
+ runs here because there is no scan plan to apply), and rejoin the spine at the
206
+ installed summary (step 6). **Skip steps 3, 4, and 5 entirely** — there is no
207
+ scan to triage, no calibrated result to confirm, and no suppression plan to
208
+ write. Do the following in order:
209
+
210
+ 1. **Show the start-light card.** Run the start-light script and relay its
211
+ AKA_SHOW card per the execution contract — the
212
+ `● Starting light — your detection categories` heading, the full 8-pack ×
213
+ 4-level default posture table, the per-pack rationale, and the re-tune
214
+ hint, pasted between the markers exactly as printed, fence included. It
215
+ reads no history and writes nothing; it only prints the card
216
+ (the severity-floor default map — secret, pii, financial, phi, code_flaw, custom at
217
+ `warn`; code_context, config at `monitor`).
218
+
219
+ ```bash
220
+ node "${PLUGIN_ROOT}/scripts/start-light.js"
221
+ ```
222
+
223
+ 2. **Confirm or adjust.** Ask — per the execution contract's decision rules —
224
+ whether to keep the recommended defaults or tune individual packs:
225
+
226
+ **Set your detection categories** — "Keep the defaults I'd recommend, or adjust any of them?"
227
+
228
+ 1. **Keep defaults** _(recommended)_ — "the careful defaults shown above"
229
+ 2. **Adjust** — "change one or more levels, keep the rest as I recommend"
230
+
231
+ If they choose **Adjust**, ask again — same decision rules — to collect the
232
+ new level (monitor/warn/redact/block) for each pack they want to change,
233
+ then merge those overrides over the severity-floor defaults to form the
234
+ full 8-pack map.
235
+
236
+ 3. **Write the chosen posture.** The default map is the severity floor,
237
+ so when the user keeps the defaults, write the floor directly; when they
238
+ adjusted packs, write the merged 8-pack map:
239
+
240
+ ```bash
241
+ # Kept the recommended defaults
242
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
243
+
244
+ # Adjusted one or more packs — <json> is the merged 8-pack map
245
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --posture '<json>'
246
+ ```
247
+
248
+ Either write prints only `✓ Set all K detection categories` (the `--floor`
249
+ write appends ` — safe defaults`) — which is the honest confirmation here,
250
+ because nothing was scanned or suppressed. Show that line to the user; do
251
+ **not** invent a dismissed count or any calibration counts.
252
+
253
+ 4. **Rejoin the spine at the installed summary (step 6).** Continue to step 6
254
+ to show the installed summary and hand off to the dashboard, using honest
255
+ no-scan copy. No scan ran, so there is **no surfaced count** — call
256
+ `firstrun.js` with **no `--surfaced` flag** (the same floor-fallback rule
257
+ step 6 already follows when no calibration frame was emitted). Step 7
258
+ then runs as written.
259
+
260
+ ## 3. Run the evidence triage — off-transcript judgment, nothing written yet
261
+
262
+ **Model-judge consent — a distinct opt-in, asked here before the pipe.** The
263
+ false-positive/severity judgment runs by sending each finding to the model API
264
+ through `codex`. That is a separate egress from the historical-read consent
265
+ collected in step 1 (which only let AKA _read_ the local rollouts), so it needs
266
+ its own explicit grant. Before running the pipe, restate plainly what leaves the
267
+ machine (the step-1 disclosure's payload: each raw value plus its masked context
268
+ window; the file path stays local), then ask as a normal conversational turn
269
+ with numbered options — and present both options flat: this grant sends the
270
+ user's data off the machine, so do **not** mark either one recommended.
271
+
272
+ **Send findings to the model to sort real leaks from noise?** — "I'll send each
273
+ detected value, plus a bit of surrounding context with any secrets in it masked,
274
+ to the model to tell real leaks from routine noise. The file path stays local.
275
+ This consent is saved machine-wide in AKA's settings, so it also covers the
276
+ same triage step in AKA's other harness plugins on this machine — revoke it
277
+ anytime from the dashboard."
278
+
279
+ 1. **Yes, send them** — "let the model triage what I found"
280
+ 2. **No, keep it local** — "skip the model triage and start from the safe defaults"
281
+
282
+ **Branch on the choice:**
283
+
284
+ - **If the user chose "Yes, send them"** — record the model-judge consent, then
285
+ run the pipe below:
286
+
287
+ ```bash
288
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --model-judge-consent
289
+ ```
290
+
291
+ - **If the user chose "No, keep it local"** — do **not** run the pipe. The judge
292
+ refuses to run without consent (it would only print a clean skip line and a
293
+ zero-count frame), so there is no calibrated plan to confirm. Fall back to the
294
+ conservative severity floor exactly as step 2's start-light path does — write
295
+ the floor, tell the user the model triage was skipped, and continue to step 6
296
+ with **no `--surfaced` flag**:
297
+
298
+ ```bash
299
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
300
+ ```
301
+
302
+ Pipe the backfill's triage stream straight into the `apply-suppressions`
303
+ adapter in **PREVIEW** mode (no `--confirmed`):
304
+
305
+ ```bash
306
+ node "${PLUGIN_ROOT}/scripts/backfill.js" --triage | node "${PLUGIN_ROOT}/scripts/apply-suppressions.js"
307
+ ```
308
+
309
+ The backfill sweeps prior Codex CLI session rollouts (last 30 days, all
310
+ sessions) and streams one masked-plus-raw triage hit per line; masked findings
311
+ are recorded to the local store as a side effect. The adapter runs the
312
+ false-positive/severity **judgment in separate `codex` subprocesses that send
313
+ each hit's raw value and masked context window — never its source path — to the
314
+ model API** (a large history is split into several batches; each runs
315
+ the CLI ephemerally so nothing lands in `~/.codex/sessions`), then prints back a
316
+ **raw-free plan** you can safely show the user:
317
+ the calibrated-result card (the real-count headline and the recommended posture),
318
+ the per-category reasoning, the masked false positives it would suppress, any
319
+ categories it skipped, and its notes.
320
+
321
+ The preview also **persists that exact raw-free plan to a temp file and prints
322
+ its path** — a line beginning `Plan saved to: <path>`. Capture that path: step 5
323
+ applies **this saved plan verbatim**, so the confirm step performs no second scan
324
+ and no second judgment. (The plan file carries only masked/fingerprint/enum data;
325
+ it is deleted after a successful apply.)
326
+
327
+ Alongside the human copy, the preview also emits a **machine-readable calibration
328
+ frame** — a single JSON block delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>`
329
+ carrying the raw-free calibration counts and categories, plus (when the scan
330
+ surfaced any) a `maskedFindings` array of raw-free secret-leak summaries. Do
331
+ **not** show this block to the user (it is additive to the human copy above).
332
+ Capture its `counts.important` value — the **surfaced count** — and pass it to the
333
+ first-run summary in step 6 as `--surfaced <count>` — but **only when the preview
334
+ also printed a `Plan saved to:` path** (a real calibrated plan to confirm in step
335
+ 4). The `Plan saved to:` line is the completion signal: a preview that omits it did
336
+ not calibrate a plan you can confirm. The fallback branches below carry no
337
+ surfaced count; the scan-ran-clean empty state (a scan that completed but
338
+ surfaced nothing) emits a zero-count frame but **no plan path**, so it too routes
339
+ to the floor branch below rather than step 4.
340
+
341
+ Also **retain the block's full text verbatim** (not just the counts you read out
342
+ of it) — step 6's "Review leaked keys" branch feeds this same text to the
343
+ secret-leak remediation entry, which reads its own `maskedFindings` from it,
344
+ and step 4's finding narration and step 6's secret-leak narration (both below)
345
+ read the same `maskedFindings` array off it too. When present, the block's
346
+ `falsePositivePatterns` array is what step 4's fixture/exception offer (below)
347
+ names its pattern and count from — never invent either off-signal.
348
+
349
+ Everything you show the user in step 4 comes from **this command's output**. You
350
+ never read the raw finding values yourself — do not echo, quote, or reconstruct
351
+ them; the judge subprocesses send them to the model API and return only the
352
+ raw-free plan, so they never enter this conversation.
353
+
354
+ **Failed or truncated triage — never proceed silently (fallback).** If this
355
+ command exits non-zero, or the adapter reports a truncated / sentinel-less
356
+ stream, the calibration could **not** complete. Do not guess a posture and do
357
+ not leave setup half-applied. Apply the conservative severity floor, **tell the
358
+ user it happened**, and continue to step 6:
359
+
360
+ ```bash
361
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
362
+ ```
363
+
364
+ Say plainly: the historical scan couldn't finish, so AKA is starting from the
365
+ conservative severity floor (high-impact categories at `warn`, observe-only at
366
+ `monitor`) instead of a calibrated posture, and it can be re-run any time with
367
+ the aka-setup skill.
368
+
369
+ **Nothing to calibrate.** A scan that **completes but surfaces nothing** prints
370
+ the honest **scan-ran-clean** card — `I looked over Codex's recent work —
371
+ nothing needs your attention right now. You're starting clean; here's what I'd
372
+ recommend:` over the recommended posture — with a zero-count calibration frame
373
+ (its `counts.important` is `0`) and **no `Plan saved to:` path**. A machine with
374
+ no history to scan instead prints the no-history card (`Nothing to learn from
375
+ yet — Codex hasn't left any work on this machine.` over the start-light table),
376
+ and a scan skipped for lack of consent prints `I didn't review anything —
377
+ historical access wasn't granted.`. In every one of these cases there's no
378
+ evidence to calibrate from and no plan to confirm: show the card the adapter
379
+ printed, take the floor branch (`onboard.js --floor`), tell the user the scan
380
+ found nothing to calibrate from, and skip to step 6 (with **no `--surfaced`**,
381
+ the floor-fallback rule there — nothing was surfaced to carry over). Do **not**
382
+ continue to step 4.
383
+
384
+ Otherwise (the preview printed a `Plan saved to:` path) continue to step 4.
385
+
386
+ ## 4. Show the calibrated result and get explicit confirmation — before any write
387
+
388
+ The preview output is raw-free. Lead with the **calibrated-result card** it
389
+ printed and show it in full:
390
+
391
+ 1. **The calibrated headline.** The `I went through Codex's recent work — N
392
+ detections, M results worth a look.` line — every count templated over the
393
+ real scan (surfaced findings are the `M results` worth a look; the rest are
394
+ routine noise a plain scanner would have screamed about). Show it verbatim;
395
+ never substitute a demo number.
396
+ 2. **The recommended posture.** The condensed one-row-per-pack recommended view
397
+ the card printed — the level AKA would set for each category. Show it in full.
398
+ - **Surface the downgrades the preview flags — this is not optional.** For the
399
+ recommended posture it is about to write, the preview compares each category
400
+ against its stored setting and flags any that would be **LOWERED** from a
401
+ stronger existing one (e.g. an existing `block`/`redact` dropping to
402
+ `warn`/`monitor`), printing a `WARNING` line summarizing them. Call these out
403
+ prominently: a user who hardened a category must **explicitly approve weakening
404
+ it** before applying.
405
+ 3. **The false positives to be suppressed (the human gate).** The masked value,
406
+ rule, and masked context for each detection the writeback would suppress —
407
+ the routine noise being dismissed. This is the checkpoint that stops a genuine
408
+ secret being silenced: the user reads the masked evidence and approves it.
409
+ 4. **Explain what surfaced, in plain language.** When the frame carries
410
+ `maskedFindings`, walk through them — what each one is, where it showed up,
411
+ and why it matters — grounded entirely in that array: every count you speak
412
+ equals the frame's own count for it (`counts.important`/`counts.total`, or
413
+ a specific finding kind's count), and every value you reference appears
414
+ masked, exactly as the frame gives it — never a raw value, never an
415
+ invented one. This is an actual explanation of the known findings, not a
416
+ restatement of the headline's counts. When the frame carries no
417
+ `maskedFindings` (nothing surfaced, or a fallback floor ran), skip this —
418
+ the calibrated-result card already said so; do not invent narration over a
419
+ missing signal.
420
+ 5. **Offer an exception for a grounded false-positive pattern.** When the
421
+ frame carries `falsePositivePatterns`, name each group's pattern and count
422
+ **strictly from that signal** — never invent a pattern name or fabricate a
423
+ count. For each group, ask — per the execution contract's decision rules —
424
+ whether to set a pre-filled exception, with a duration choice (the exception
425
+ scope axis — `once` / `temporary` / `permanent`):
426
+
427
+ **Make an exception for `<pattern>` (×N)?** — "This `<pattern>` looks like a
428
+ test fixture — want me to set an exception so it stops popping up?"
429
+
430
+ 1. **Once** — just this once — expires in 30 minutes
431
+ 2. **Temporary** — for a set window, then I'll check it again
432
+ 3. **Permanent** — stays until you revoke it
433
+ 4. **Not now** — skip — I won't write anything
434
+
435
+ **Temporary needs a concrete window.** `once` and `permanent` fully determine
436
+ the scope on their own, but `temporary` does not — resolving it into the
437
+ stored `{scope, expiresAt, maxUses}` triple requires an actual duration, and
438
+ you must **never** invent or default one. When the user picks **Temporary**,
439
+ follow up with a second question that offers concrete windows only
440
+ — `30m` / `1h` / `24h` (the exception scope resolver accepts `<n>m`/`<n>h`,
441
+ capped at 24h; a longer bypass is a `permanent` grant, not a forgotten timer)
442
+ — and resolve the exact chosen string through that resolver. **Once** and
443
+ **Permanent** take no follow-up.
444
+
445
+ Accepting surfaces the exact pre-filled exception — one **per distinct value
446
+ identity** (`ruleId`/`valueFingerprint`/`keyVersion`) at the chosen
447
+ `{scope, expiresAt, maxUses}` — for review, and the marked pattern is
448
+ suppressed as part of the calibration plan confirmed below (the same store
449
+ the aka-exceptions skill reads). A group whose displayed pattern covers more
450
+ than one distinct value surfaces one exception per distinct value — never a
451
+ single grant collapsing them — and a value missing its exact identity is not
452
+ offered for. Declining surfaces nothing; this offer is separate from the
453
+ calibration plan's suppressions confirmed below, so declining here changes
454
+ nothing about that confirmation. When the frame carries no
455
+ `falsePositivePatterns` (nothing was marked a likely false positive, or the
456
+ scan was declined), skip this entirely — no offer, nothing invented
457
+ (fail-open).
458
+
459
+ Then ask — per the execution contract's decision rules, never answering for the
460
+ user — to confirm:
461
+
462
+ **Want me to apply this?** — "I'll set these levels and suppress the false
463
+ positives above."
464
+
465
+ 1. **Yes, apply** _(recommended)_ — write the posture and suppressions exactly as
466
+ previewed.
467
+ 2. **Adjust a category** — "change one or more first; keep the rest as I
468
+ recommend"
469
+
470
+ Do **not** proceed until the user picks one. On **Yes, apply**, continue to
471
+ step 5 and apply the previewed plan verbatim — that is the confirm spine,
472
+ unchanged. On **Adjust a category**, take the **adjust fork** (step 4b), which
473
+ applies within the fork and rejoins the spine at the installed summary (step 6).
474
+
475
+ ## 4b. Adjust a category — the override fork
476
+
477
+ The **adjust base is the calibrated recommended posture the preview just
478
+ printed** — the condensed one-row-per-pack view from step 4, not the cold-start
479
+ severity floor. The user changes the packs they want and keeps the rest as
480
+ recommended.
481
+
482
+ 1. **Collect the changes.** Ask — per the execution contract's decision rules —
483
+ which packs to change and to which level (monitor/warn/redact/block), one
484
+ clear numbered-option question at a time.
485
+
486
+ 2. **Show the adjust-confirm table.** Compose the merged 8-pack map — the
487
+ recommended base with the user's picks overlaid — and render the adjust-confirm
488
+ card by passing the calibrated recommended posture as `--recommended` and that
489
+ merged map as `--posture`. Relay its AKA_SHOW region per the execution
490
+ contract — the fenced `category │ recommended │ yours` table, pasted between
491
+ the markers exactly as printed (it is space-aligned monospace; do **not** add
492
+ another code fence, strip the fence, or reformat it):
493
+
494
+ ```bash
495
+ node "${PLUGIN_ROOT}/scripts/start-light.js" --adjust-confirm --recommended '<recommended-json>' --posture '<merged-json>' --current '<current-json>'
496
+ ```
497
+
498
+ `<recommended-json>` is the calibrated recommended posture the preview printed
499
+ (the adjust base) — so the `recommended` column shows each pack's calibrated
500
+ level, and a pack calibration escalated above the floor never renders as a
501
+ spurious change. `<merged-json>` is the full 8-pack map — that same recommended
502
+ base with the user's overrides overlaid — so a changed pack reads as a different
503
+ `yours` value and every untouched pack repeats its recommended level.
504
+ `<current-json>` is the `current` object from the plan file at the path step 3
505
+ printed (`Plan saved to: <path>`) — the store's per-category action at preview
506
+ time, the baseline the downgrade check compares against. Pass it verbatim; do
507
+ not retype or summarize it.
508
+
509
+ 3. **Surface any downgrade — the card computes this, you do not.** With
510
+ `--current` passed, the card itself appends the `WARNING: N categories … would
511
+ be LOWERED from a stronger existing setting` footer whenever a pick weakens
512
+ enforcement — the same rule and the same wording as the confirm gate above,
513
+ from the same code. Show the card in full, footer included, and when that
514
+ footer is present get explicit approval before saving. Never let an enforcement
515
+ downgrade through without the user having seen it.
516
+
517
+ 4. **Save or back out.** Ask — per the execution contract's decision rules —
518
+ with **N** the number of packs the user changed and **M** the number kept as
519
+ recommended (`M = 8 − N`), both real — never a placeholder:
520
+
521
+ **Save your adjustments?**
522
+
523
+ 1. **Save adjusted — N changed, M as recommended** — apply with the adjusted
524
+ posture.
525
+ 2. **Back to recommended** — discard the changes and apply the recommended
526
+ posture instead.
527
+
528
+ 5. **On "Save adjusted" — produce the applying frame here, carrying the adjusted
529
+ posture, then rejoin the spine at the installed summary (step 6).** This fork
530
+ applies within itself and **stands in for step 5**, so step 5 never runs on
531
+ this path. First apply the previewed plan with the **unchanged confirm spine**,
532
+ so the reviewed false positives are dismissed and the recommended base is
533
+ written (the reviewed evidence packs overwrite; the severity floor fill-gaps the
534
+ rest, so a pack hardened out of band is never downgraded):
535
+
536
+ ```bash
537
+ node "${PLUGIN_ROOT}/scripts/apply-suppressions.js" --confirmed --plan <path>
538
+ ```
539
+
540
+ If that `--confirmed` run exits non-zero (or `--plan` is missing/unreadable),
541
+ handle it exactly as step 5 does: tell the user the write did not complete, fall
542
+ back to the floor (`onboard.js --floor`), and continue to step 6. Do **not** run
543
+ the overlay below on a failed spine — nothing was written, so there is no
544
+ recommended base to overlay the changes onto.
545
+
546
+ Then overwrite **only the packs the user changed** with their chosen levels:
547
+
548
+ ```bash
549
+ node "${PLUGIN_ROOT}/scripts/onboard.js" --posture '<changed-packs-json>'
550
+ ```
551
+
552
+ `<changed-packs-json>` carries **only** the packs the user adjusted (not the
553
+ full 8-pack map), so the packs kept as recommended keep the fill-gaps-safe
554
+ values the spine wrote and only the user's explicit, downgrade-approved changes
555
+ overwrite.
556
+
557
+ If that overlay exits non-zero, the spine already wrote the recommended base, so
558
+ the store holds a valid posture — but **not** the user's overrides. Tell the user
559
+ their adjustments did not save and the store holds the recommended posture, then
560
+ continue to step 6. Do **not** report the adjusted posture as saved on a failed
561
+ overlay.
562
+
563
+ On success, present the applying-frame confirmation the **spine** printed —
564
+ `✓ Set all 8 detection categories · set aside N routine results · Ready: …` —
565
+ the store now holds the adjusted posture. The overlay's own smaller
566
+ `✓ Set all N detection categories` line (the count of just the changed packs)
567
+ is bookkeeping — **do not show it**; the applying frame reports the full
568
+ 8-pack posture. Then continue to step 6.
569
+
570
+ **On "Back to recommended"** — take the **Yes, apply** path instead: continue
571
+ to step 5 and apply the previewed plan verbatim with no override.
572
+
573
+ Do **not** write anything until the user has explicitly confirmed at step 4
574
+ (Yes, apply) or saved at step 4b (Save adjusted).
575
+
576
+ ## 5. Write the posture and suppressions
577
+
578
+ On confirmation, run the adapter again with `--confirmed --plan <path>`, passing
579
+ the **plan-file path the preview printed in step 3** (`Plan saved to: <path>`). It
580
+ reads that saved plan back and applies it **exactly as previewed** — establishing
581
+ the **full 8-pack posture** the recommended view showed (the reviewed
582
+ evidence packs overwrite; the conservative severity floor fill-gaps the remaining
583
+ packs, so a pack the user had already hardened out of band is never downgraded) and
584
+ writing one 30-day suppression per confirmed false positive **without re-running the
585
+ backfill or the judge**. There is deliberately **no `backfill.js` pipe here**:
586
+ re-scanning and re-judging would produce a fresh, non-deterministic plan and
587
+ silently defeat the human gate the user just approved.
588
+
589
+ The posture overwrite and the suppression writes are applied as a **single
590
+ all-or-nothing transaction**: a mid-batch failure rolls back the posture change
591
+ too, so the store is never left half-applied. That is why the floor fallback below
592
+ is safe — a non-zero exit means **nothing** persisted, so re-applying the
593
+ conservative floor cannot collide with a partially-written posture.
594
+
595
+ ```bash
596
+ node "${PLUGIN_ROOT}/scripts/apply-suppressions.js" --confirmed --plan <path>
597
+ ```
598
+
599
+ The script prints the applying confirmation — `✓ Set all K detection categories
600
+ · set aside N routine results · Ready: …` — with both counts threaded from the
601
+ real write. Show that line to the user.
602
+
603
+ If `--plan` is missing or the file is unreadable/invalid, the adapter **fails loud
604
+ (non-zero) and writes nothing** — it never falls back to a re-judge. Treat that
605
+ like the `--confirmed` failure below: tell the user the write did not complete,
606
+ fall back to the floor, and continue to step 6.
607
+
608
+ If the `--confirmed` run exits non-zero, tell the user the write did not
609
+ complete, fall back to the floor (`onboard.js --floor`), and continue to step 6
610
+ so setup still finishes.
611
+
612
+ ## 6. Show the installed summary and hand off to the dashboard
613
+
614
+ Run the first-run script and relay its **install-complete summary** AKA_SHOW
615
+ region per the execution contract (live findings/recommendation counts, the
616
+ health score, and the per-category posture just written or floored). The
617
+ script wraps that summary in a Markdown code fence; paste it between the
618
+ markers exactly as printed and do **not** add another code fence, strip the
619
+ fence, or reformat it (it is space-aligned monospace that Markdown would
620
+ otherwise collapse).
621
+
622
+ Pass the **surfaced count** captured from step 3's calibration frame
623
+ (`counts.important`) as `--surfaced <count>` — this is the 'N worth a look' figure
624
+ the script emits in its own machine-readable handoff payload — but only when step 3
625
+ carried a surfaced count forward (it printed a `Plan saved to:` path). If the
626
+ calibration fell back to the floor (no plan path in step 3 — a fallback branch, or
627
+ the scan-ran-clean empty state whose zero-count frame carries nothing to look at),
628
+ **omit `--surfaced` entirely** — the script then withholds that payload rather than
629
+ fabricating a count.
630
+
631
+ Alongside it, pass the **surfaced live-key count** — the number of surfaced
632
+ live-key secret findings, which is the length of the calibration frame's
633
+ `maskedFindings` array (absent ⇒ 0) — as `--live-keys <count>`. This is the
634
+ narrower secret subset of the surfaced count; it gates the remediation
635
+ chain-entry the handoff offers, so a calibration that surfaced only non-secret
636
+ findings passes `--live-keys 0` and offers no remediation.
637
+
638
+ When `--surfaced` is passed, the script appends that handoff payload as a single
639
+ JSON block delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>` after the fenced
640
+ card. Like step 3's calibration frame, do **not** show this block to the user — it
641
+ is additive and machine-only; only the fenced install summary above is
642
+ user-facing.
643
+
644
+ ```bash
645
+ node "${PLUGIN_ROOT}/scripts/firstrun.js" --surfaced <count> --live-keys <count>
646
+ ```
647
+
648
+ **Then hand off to the dashboard.** When the payload carries a positive
649
+ `worthALook` count, ask explicitly — per the execution contract's decision rules
650
+ — using that count for `N`:
651
+
652
+ **N worth a look — want to see them in the browser?**
653
+
654
+ 1. **Review leaked keys** — "let's deal with the exposed keys I found" —
655
+ _(offer this option first only when the payload's `options` include
656
+ `enter-remediation`, i.e. `liveKeys > 0`)_; entering it starts the
657
+ secret-leak remediation chain on the surfaced live keys. This composes with —
658
+ never replaces — the dashboard handoff below, so both stay reachable.
659
+ 2. **Open dashboard** — "open the local dashboard on what I found"
660
+ 3. **Not now** — "stay here — you can open it anytime"
661
+
662
+ Use the payload's `worthALook` value for `N` verbatim — do not invent or round it.
663
+ Offer **Review leaked keys** exactly when the payload's `options` carry the
664
+ `enter-remediation` entry (never otherwise); the **Open dashboard** / **Not now**
665
+ handoff is always present. If the payload was withheld (the floor fallback, or
666
+ nothing surfaced), skip this handoff question rather than inventing a count.
667
+
668
+ **If they choose "Review leaked keys"** — run the secret-leak remediation entry's
669
+ **present** mode, feeding it the calibration frame block you captured in step 3
670
+ (the same text `maskedFindings` came from) on stdin:
671
+
672
+ ```bash
673
+ node "${PLUGIN_ROOT}/scripts/remediate.js" <<'AKA_FRAME'
674
+ <the <<<AKA_FRAME_JSON … AKA_FRAME_JSON>>> block captured in step 3, verbatim>
675
+ AKA_FRAME
676
+ ```
677
+
678
+ It prints the decision as human-facing text, then a machine-readable block
679
+ delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>` carrying the same decision
680
+ structured (do **not** show that block to the user). The human text has three
681
+ parts, all of which you **show to the user verbatim, in order**:
682
+
683
+ 1. the templated count line ("I found N exposed secret keys sitting in old
684
+ transcripts."),
685
+ 2. the fenced finding table (provider, masked token, where, state), and
686
+ 3. inside that same fence, a most-exposed-first recommendation line and a
687
+ secret-scan chaining line.
688
+
689
+ This entire human-text block is the entry's AKA_SHOW region — relay it per the
690
+ execution contract, pasting it between the markers exactly as printed — do not
691
+ drop the recommendation or chaining lines, and do not paraphrase.
692
+
693
+ Alongside that fenced block, explain the findings in plain language grounded
694
+ in the same `maskedFindings` array the block came from — what each finding is
695
+ and why it matters, not a bare recital of the count line above it. The same
696
+ grounding discipline as step 4's narration applies here: every count you
697
+ speak matches the frame's own count, and every value you reference stays
698
+ masked. With no `maskedFindings` present there is nothing to narrate beyond
699
+ the count line and table already shown — do not invent an explanation.
700
+
701
+ Then ask — per the execution contract's decision rules — offering exactly these
702
+ four options, in order (each option's label maps to the `--option` id shown in
703
+ parentheses):
704
+
705
+ 1. **Redact + rotation checklist** (`redact-rotation-checklist`)
706
+ 2. **Redact only** (`redact-only`)
707
+ 3. **Set 'secret' to redact** (`set-secret-redact`)
708
+ 4. **Leave** (`leave`)
709
+
710
+ **If they chose "Redact + rotation checklist" or "Redact only"** — before running
711
+ the route, ask a second question presenting the standing-posture prompt,
712
+ offering exactly these four options, in order (each option's label maps to the
713
+ `--posture` level in parentheses):
714
+
715
+ **Set the 'secret' detection level**
716
+
717
+ 1. **Redact** (`redact`)
718
+ 2. **Warn** (`warn`)
719
+ 3. **Block** (`block`)
720
+ 4. **Monitor** (`monitor`)
721
+
722
+ Then run the entry's **route** mode ONCE with the chosen redact option's id AND
723
+ the chosen posture level, feeding it the SAME calibration frame block again on
724
+ stdin:
725
+
726
+ ```bash
727
+ node "${PLUGIN_ROOT}/scripts/remediate.js" --option <id> --posture <level> <<'AKA_FRAME'
728
+ <the same block>
729
+ AKA_FRAME
730
+ ```
731
+
732
+ Never run the route a second time for this choice — a repeat call would strike
733
+ the already-redacted keys again and corrupt the reported count. Show its printed
734
+ result verbatim, in order. For "Redact only" that is the redaction confirmation
735
+ then the standing-posture confirmation. For "Redact + rotation checklist" it is
736
+ the standing-posture confirmation then the resolved rotation-checklist summary —
737
+ which reports the redaction itself, so the script does not print a separate
738
+ redaction confirmation ahead of it.
739
+
740
+ **If they chose "Set 'secret' to redact" or "Leave"** — run the entry's **route**
741
+ mode with the chosen option's id (the id in parentheses above, e.g. **Leave** →
742
+ `leave`), feeding it the SAME calibration frame block again on stdin:
743
+
744
+ ```bash
745
+ node "${PLUGIN_ROOT}/scripts/remediate.js" --option <id> <<'AKA_FRAME'
746
+ <the same block>
747
+ AKA_FRAME
748
+ ```
749
+
750
+ Show its printed result verbatim — a standing-posture confirmation, or (choosing
751
+ "Leave") a plain note that nothing changed. This entry reads its findings from the
752
+ calibration frame alone and holds no wizard state of its own, so it works
753
+ identically from any caller.
754
+
755
+ ## 7. Offer the AKA CLI + local dashboard (opt-in)
756
+
757
+ Now that the plugin is set up, offer the optional **AKA CLI + local dashboard** —
758
+ a richer, still-fully-local surface over the same `~/.aka` store this plugin
759
+ writes. The plugin works completely on its own; this is additive (and the path to
760
+ future multi-agent support). Ask — per the execution contract's decision rules:
761
+
762
+ **Want the AKA CLI + dashboard too?** — "The `aka` CLI adds a local user
763
+ interface + terminal dashboard and on-demand scans."
764
+
765
+ 1. **Yes, add it** _(recommended)_ — "adds the `aka` command: stats, a terminal
766
+ dashboard, a local user interface, and on-demand scans"
767
+ 2. **Not now** — "skip — you can add it anytime with the one-liner below"
768
+
769
+ **Yes, add it** is the install authorization — run the bootstrap installer
770
+ directly, with no second question (it downloads the self-contained `aka` binary for
771
+ their platform — no Node.js or npm required — and links it onto PATH). Run the
772
+ line for their OS:
773
+
774
+ ```bash
775
+ # macOS / Linux
776
+ curl -fsSL https://raw.githubusercontent.com/akasecurity/ai-tc/bin-latest/tools/installer/install.sh | sh
777
+
778
+ # Windows (PowerShell)
779
+ irm https://raw.githubusercontent.com/akasecurity/ai-tc/bin-latest/tools/installer/install.ps1 | iex
780
+ ```
781
+
782
+ The one-liner pins to the latest published binary release **tag** (`bin-latest`),
783
+ never `main` — each binary release (`bin-v*`) moves that tag to its commit, and
784
+ the installer verifies the downloaded binary against the release's `SHA256SUMS`
785
+ (fail-closed), so a corrupted or tampered download is refused. To pin an exact
786
+ version instead, set `AKA_INSTALL_REF=bin-v<version>` before running the line. If
787
+ no `bin-v*` release exists yet the one-liner fails closed rather than guessing.
788
+
789
+ After it completes, point them at `aka init` then `aka dashboard`. If they chose
790
+ **Not now**, show the one-liner once so they can add it later, and move on —
791
+ declining keeps the plugin fully functional standalone.
792
+
793
+ **Fail open.** This install is optional, so it must never derail the session. If
794
+ the installer fails for any reason — Node missing, network/registry error, a
795
+ non-zero exit, or the checksum check rejecting a bad download — briefly report
796
+ what happened, show the one-liner so they can retry later, and continue the
797
+ wizard normally. The plugin is already fully set up and works on its own; a
798
+ failed CLI install changes nothing about that.
799
+
800
+ **Close the wizard.** The first-run summary already confirmed the saved posture
801
+ and pointed at the aka-health skill. Whichever way the CLI offer went —
802
+ installed, declined, or a failed install you already reported — end with one
803
+ warm close: "That's it — I'm watching out for Codex going forward."
804
+
805
+ Before you finish, confirm every AKA_SHOW region on the path you took was
806
+ relayed to the user. If you summarized one instead of pasting it, paste it now.
807
+
808
+ ## Known limitation
809
+
810
+ Live PreToolUse/PostToolUse redaction currently covers `Bash` shell calls only —
811
+ Codex does not yet fire these hooks for `apply_patch` (file-write) calls (an
812
+ upstream Codex hook-coverage gap). File-write **content is not scanned at all**
813
+ on Codex — not live, and not after the fact either. The consent-gated historical
814
+ scan this wizard offers in steps 1/3 reads conversation messages only, and the
815
+ tool-call reconciler records a write's changed paths and byte sizes, never the
816
+ bytes themselves. So a secret written into a file through `apply_patch` is
817
+ neither redacted before it lands nor reported afterwards; only the path is
818
+ recorded. If the user asks why a secret in a file edit wasn't caught, say so
819
+ plainly rather than implying it is picked up somewhere else.
820
+
821
+ The reversible secret vault is not yet wired for Codex sessions, so this wizard
822
+ does not offer the vault-consent step: everything AKA redacts here is one-way
823
+ (the safe direction), and nothing this plugin captures is ever vaulted — even
824
+ when vault consent was granted through the Claude Code wizard on the same
825
+ machine. Vault pointers minted elsewhere still render as literal `[[aka:...]]`
826
+ tokens in Codex output (Codex has no display-side hook to badge them), and a
827
+ pointer inside a Bash command is denied rather than executed or substituted.
828
+ If the user asks about recovering a redacted value, point them at the vault
829
+ surfaces that do exist on this machine (`aka vault show`, the dashboard's
830
+ Vault page) rather than implying this plugin can reveal anything.