euthyna 0.2.0 → 0.3.0

package/.agents/skills/euthyna-en/references/meta-mechanisms.md

@@ -0,0 +1,174 @@
+# Meta-mechanisms: six things that make the process actually work
+
+> Stages A / B / C are the **process**. This file is the **mechanisms** that keep the process from degrading into going through the motions.
+>
+> What they share: **none of them relies on self-discipline**. Any constraint that depends on "remember to be careful" fails in long sessions.
+
+---
+
+## 1. Against "wrong numbers": separate measurement from judgment
+
+**Rule**: every measurable quantity is produced by a command or script. The model only interprets.
+
+Number of callers, test coverage, dependency versions, line numbers, commit hashes, how many times a function is invoked —
+**none of these may be answered from memory**. When a tool is unavailable, say "not measurable" —
+**never estimate and then write the estimate into a conclusion as fact**.
+
+### Why this rule must be hardened
+
+Model estimates of such numbers are not "slightly off" — they are **systematically wrong**, and wrong in a way nobody notices:
+
+- a package shows 5+ maintainers on the code-hosting platform, while its actual permission list in the package manager has **1 person**
+- a package downloaded 160 million times a week shows **zero downloads** in some data source
+
+Both are real cases that failed in measurement. What they show is not "be more careful" — it is
+**estimating numbers by feel is unreliable no matter how hard you try**.
+
+### How it is implemented
+
+For this, the project provides producers and defines the contract (`fact-contract.md`):
+
+```powershell
+# <euthyna repo> = where this project is checked out, not the audited project's path
+node <euthyna repo>/bin/euthyna.js history  --base <rev> --repo <audited repo>
+node <euthyna repo>/bin/euthyna.js coverage --coverage <file> --symbol <name>
+```
+
+⚠️ Writing the relative `node bin/euthyna.js` fails: during an audit the current directory is the audited project.
+Commands, exit codes, and failure modes: see `fact-producers.md`.
+
+---
+
+## 2. Against "fabricated findings": evidence enforcement + the barrier dichotomy
+
+### 2.1 Enforce evidence down to `file:line`
+
+- every claim cites a concrete location: `path:L123`, or `path:L123 (commit abc1234)` when a version exists
+- `probably` / `likely` / "roughly" are banned — chase the real code; when you cannot, **say you cannot**
+- no `TODO`, `...`, or `// the attacker does something here` in demonstration code
+- **the moment a demonstration uses an artificial bypass** (mock, stub, disabled check), that demonstration is judged **invalid**
+
+### 2.2 "Raising the bar" is not "eliminating the defect"
+
+This is the easiest point to confuse, and the easiest place to overestimate severity. Protections fall into two classes:
+
+| Class | Example | Meaning |
+|---|---|---|
+| **fully prevents** | Rust's safe type system against memory corruption; parameterized queries against SQL injection | that class of defect cannot occur |
+| **only raises the bar** | ASLR, stack canaries, CFI | harder, but **not eliminated** |
+
+Likewise, keep apart:
+
+- **primary security control** vs **defense in depth** — when the primary protection is intact, a failing defense-in-depth layer is **not a defect**
+- **mathematically impossible** / **practically infeasible** / **feasible** — the three states must be stated clearly, not conflated
+
+---
+
+## 3. Against "missing the real thing": two-way skepticism + three-state honesty
+
+A system that only guards against false positives degenerates into "nothing is ever a defect" — as useless as "everything is a defect".
+
+### 3.1 The devil's advocate must work both ways
+
+Besides the questions arguing against a defect (guarding against false positives), these two **must** also be asked:
+
+> **12. Did I dismiss a real defect because the exploitation is complex or unlikely?**
+> **13. Did I invent mitigations or validation logic that I did not verify in the source?** (**re-read the code** after concluding)
+
+Questions 12 and 13 must be asked **in every case**. The model's default bias is "report too much", so most mechanisms suppress it;
+**over-suppressing misses real vulnerabilities** — these two questions are the symmetric counterweight.
+
+### 3.2 Three states, not two
+
+Every criterion lands in exactly one of: **evaluated · clean / evaluated · flagged / not evaluable for a stated reason**.
+
+- a run that measured nothing produces "not evaluable", **not** "no issues found"
+- before citing any "clean" conclusion, look at the coverage table first
+- **numbers must be quoted verbatim** — no re-deriving, no rounding, no dressing up
+- **finding nothing is not an endorsement**
+
+### 3.3 Verdicts need a third state
+
+With only "true / false" states, "not finished checking" is forced to be written as "false" — that manufactures false negatives.
+
+So verdicts must have `INCONCLUSIVE`, and **must state what is missing and why it is missing**.
+
+---
+
+## 4. Against "laziness": enumerate the excuses in advance
+
+**"Be careful" is useless. What works is listing in advance the lazy impulses a model will produce in a real audit, and shutting each one down.**
+
+| Excuse | Why it is wrong | What you must do |
+|---|---|---|
+| the change is small, take a quick look | the most severe historical vulnerabilities can be two lines | classify by **risk**, not by size |
+| I know this codebase | familiarity creates blind spots | establish a baseline explicitly |
+| digging through git history takes too long | history reveals regressions | origin attribution is **not skippable** |
+| the impact is obvious at a glance | transitive callers get missed | compute quantitatively |
+| missing tests are not my problem | missing tests = escalated risk | write it in the report and **raise** the severity |
+| it is just a refactor, no security impact | refactors break invariants | analyze as high risk until **proven** low risk |
+| I can explain it verbally | no artifact = lost findings | a report file is mandatory |
+| this pattern looks dangerous | pattern recognition is not analysis | no conclusion without completing the data-flow trace |
+| similar code elsewhere is a vulnerability | context, callers, and protections differ per site | verify this instance independently |
+| this is obviously a severe vulnerability | the model is biased toward seeing bugs and overestimating severity | complete the devil's advocate review and prove it with evidence |
+| skip full verification to save time | partial analysis is not allowed | execute **all** steps of the chosen path |
+
+**This table must be explicitly loaded at the start of every audit**, and it **grows with real incidents** —
+every new lazy pattern found adds a row. It is a living list.
+
+---
+
+## 5. Against "loss": output must be written to disk
+
+- **output to chat only counts as failure**. a report file must be written
+- fallback order when writing fails: current working directory → desktop → temp directory → **last resort** only: output to chat and prompt for manual saving
+- filenames carry the project name and date
+
+Design intent: chat transcripts scroll away and get compressed; **files do not**. A deliverable's survival should not depend on session length.
+
+---
+
+## 6. Against "contamination": isolate capabilities by stage
+
+### 6.1 Gates must not be delegated
+
+Some stages need **cross-stage integrated judgment**; handing them to a subagent shreds the responsibility:
+
+- impact assessment
+- devil's advocate review
+- gate adjudication
+
+**These three must not be delegated.**
+
+### 6.2 Subagent permissions are deliberately asymmetric
+
+| Role | Permission |
+|---|---|
+| data-flow analysis | **read-only** |
+| exploitability verification | **read-only** |
+| PoC building | the only one that may write |
+
+Rationale: **the ability to manufacture evidence is concentrated in a single stage**. Earlier stages may only observe —
+if the analysis stage could write files, it could "conveniently" reshape the evidence to support its own conclusions.
+
+### 6.3 Never start the next stage before dependencies are done
+
+Mark tasks in-progress when they start; **only concrete evidence marks them completed**.
+Parallel substages start concurrently; before entering the next dependent gate, **collect all results**.
+
+---
+
+## How the six relate
+
+```
+1. separate measurement from judgment ─┐
+                                       ├─→ makes "facts" trustworthy
+2. evidence enforcement ────────────────┘
+                                       ├─→ makes "conclusions" trustworthy
+3. two-way skepticism ──────────────────┘
+4. excuse table ───────────────────────────→ keeps the process from being bypassed
+5. written to disk ────────────────────────→ keeps output alive
+6. capability isolation ───────────────────→ keeps the process from being contaminated
+```
+
+The first three decide **conclusion quality**; the last three decide **process quality**. Missing any one, and the whole thing degrades at some point.

package/.agents/skills/euthyna-en/references/verification-gates.md

@@ -0,0 +1,291 @@
+# Stage C: claim verification (adjudication layer)
+
+> **Role**: it does not find bugs — it only adjudicates whether an existing suspected bug is real.
+> Trigger phrases: "is this true", "verify this finding", "is it exploitable".
+>
+> This file is euthyna's core asset. Anyone can do the measurement layer; **adjudication discipline is the differentiator**.
+> Methodology source and license: see `NOTICE.md`.
+
+---
+
+## C.0 Step zero: restate the claim (not skippable)
+
+Restate it in your own words, item by item, in writing. **No jumping straight into analysis.**
+
+| What to restate | What to cover |
+|---|---|
+| Exact vulnerability claim | One sentence, decidable as true or false |
+| Claimed root cause | Where the defect is, and **why** |
+| Claimed trigger path | What the attacker does |
+| Claimed impact | Lands on RCE / privilege escalation / information disclosure |
+| **Threat model** | What privileges does the code run with? Is it sandboxed? What can the attacker already do before triggering? |
+| Defect class | One of the 9 classes (see `bug-classes.md`) |
+| Execution context | Single-threaded? Synchronized? Lifecycle? |
+| Caller analysis | Who calls it, and with what arguments |
+| Architecture context | Where it sits in the system |
+| Historical context | When and why this code was added |
+
+> **Half of all false positives collapse at this step** — when the claim is restated precisely, it simply does not hold together.
+> So this is not formalism: it is the highest-value filter.
+
+**Output**: write the restatement as `subject.claim` in the fact contract (see `docs/fact-contract.md`).
+
+---
+
+## C.1 Routing: standard verification vs deep verification
+
+### Standard verification (linear single-pass checklist) — **all** must hold
+
+- The claim is clear and specific
+- Single component (no cross-component interaction)
+- The defect class is known
+- No concurrency or async
+- The data flow is straightforward
+
+### Deep verification (task-based orchestration + subagents) — **any** one triggers it
+
+- The claim is vague or has multiple readings
+- Cross-component (data flows through 3+ modules)
+- Involves race conditions or TOCTOU
+- A logic defect with no clear spec to compare against
+- Standard verification cannot reach a conclusion, or was escalated
+- The user explicitly asks
+
+**Start with standard by default.** Standard verification has two built-in escalation checkpoints:
+
+1. After Step 1: if more than 3 trust boundaries, callback/async control flow, or an ambiguous validation chain appear → escalate
+2. After Step 5: if any issue leaves unresolvable genuine uncertainty → escalate
+
+**On escalation, hand over all evidence gathered so far** — deep verification continues from where it stopped and **does not redo completed work**.
+
+---
+
+## C.2 The 6 steps of standard verification
+
+### Step 1: data flow
+
+1. Map the trust boundaries crossed (internal trusted vs external untrusted)
+2. Identify **all** validation and sanitization between source and sink
+3. Check API contracts — some APIs carry their own boundary protection
+4. Check environmental defenses, and **distinguish** "fully prevents" from "only raises the bar"
+5. Apply the class-specific checks for the defect class (`bug-classes.md`)
+
+> **Pitfall: analyzing code in isolation.** Upstream conditional logic can make the defect mathematically unreachable.
+> You must follow the full validation chain — not just the few lines around the dangerous operation.
+
+### Step 2: exploitability
+
+- **Attacker-controlled**: internal storage written by trusted components is **not** attacker-controlled
+- **Boundary proof**: write out an explicit algebraic proof verifying "IF the check passes THEN the boundary guarantee holds"
+- **Race feasibility**: single-threaded initialization and synchronized contexts **cannot** race
+
+### Step 3: impact
+
+- Distinguish **real security impact** (RCE, privilege escalation, information disclosure) from **operational robustness** (crash recovery, cleanup failures)
+- Distinguish **primary security controls** from **defense in depth**
+
+### Step 4: demonstration sketch
+
+```
+Data flow: [Source] → [validation?] → [transformation?] → [fragile operation] → [impact]
+```
+
+Write down: what the attacker controls, how, and the triggering pseudocode.
+
+### Step 5: devil's advocate spot-check (7 questions)
+
+5 opposing questions (against **false positives**) + 2 supporting questions (against **false negatives**, marked always ask).
+
+See C.5.
+
+### Step 6: gate review
+
+Run all 6 gates + all 13 items of the false-positive checklist.
+
+---
+
+## C.3 The six gates (all must pass before something is reported as a vulnerability)
+
+| # | Gate | Criterion | Pass | Fail |
+|---|---|---|---|---|
+| 1 | **Process** | All stages completed with written evidence | Evidence at every stage | A stage lacks concrete evidence |
+| 2 | **Reachability** | The attacker can reach and control the data in question | Clear evidence of an attacker-controlled path + PoC confirmation | Control or reachability cannot be shown |
+| 3 | **Real Impact** | Exploitation leads to RCE, privilege escalation, or information disclosure | Direct impact in a concrete scenario | Only operational-robustness issues |
+| 4 | **PoC Verification** | The PoC demonstrates the attack path | Shows control, triggering, and impact | The PoC fails to show the path or the impact |
+| 5 | **Mathematical Boundary** | Mathematical analysis confirms the fragile condition can occur | Algebraic proof that the condition is possible | Mathematical proof that the check prevents it |
+| 6 | **Environment** | No environmental defense can fully prevent exploitation | Defenses do not eliminate the vulnerability | An environmental defense fully blocks it |
+
+### Adjudication rules (fixed)
+
+| Condition | Verdict |
+|---|---|
+| **All** 6 gates `pass` | `TRUE POSITIVE` |
+| Any gate `fail`s | `FALSE POSITIVE` |
+| No `fail`, but some `not_evaluated` | **`INCONCLUSIVE`** |
+
+**Key rule**: if any stage's verification fails, **record the failure evidence and continue through the remaining stages**;
+only when **all stages are complete** do you issue the `FALSE POSITIVE` verdict.
+
+> `INCONCLUSIVE` is an outcome **added** by euthyna beyond Trail of Bits' original definition.
+> Reason: the original implementation used the Stop hook to force continuation indefinitely until complete, while DSH's Stop hook
+> **must rate-limit itself** (otherwise it loops forever) and cannot force indefinitely. See `docs/dsh-stop-gate.md`.
+
+### Adjudication format (evidence required)
+
+```
+BUG #3 FALSE POSITIVE — integer underflow in packet_handler.c:142
+  Gate 5 (Mathematical Boundary) FAIL: line 98's check guarantees packet_size >= 16,
+  so (packet_size - header_size) >= 8. Underflow is mathematically impossible.
+
+BUG #4 TRUE POSITIVE — command injection
+  All gates passed. Evidence: src/archive.js:42 (abc1234)
+  Reproduce: node tools/poc.js
+  Exploitability: EASY
+  Impact: arbitrary command execution as the service account
+```
+
+**The format is machine-enforced**: after writing, validate with `euthyna gate <report file>` (see the "programmatic gate validation" section of SKILL.md). A TRUE POSITIVE that lacks evidence, lacks reproduction, or carries a FAIL gate is **downgraded to "observation"** by the validator and reported with exit code 10 — discipline does not depend on the adjudicator's self-awareness.
+
+---
+
+## C.4 The thirteen-item false-positive checklist (apply item by item to **every** suspected defect)
+
+| # | Item | Question to ask |
+|---|---|---|
+| 1 | **Trace the full validation chain** | What are all the prior checks before the dangerous operation? Do not analyze isolated fragments |
+| 1a | **Map the full conditional logic flow** | Is the seemingly unsafe `buffer[length-4]` only reachable when `length > 12`? |
+| 2 | **Recognize defensive programming** | `ASSERT(size == expected)` is defense, not a vulnerability |
+| 3 | **Confirm an exploitable data path** | Report only vulnerabilities with a **confirmed** exploitable data flow; do not assume network data reaches the dangerous function |
+| 4 | **Understand the data source context** | API return values, compile-time constants, and network data carry different risk levels. Determine the true source |
+| 5 | **Analyze the boundary-check logic** | If `size >= MIN` is checked and `MIN >= sizeof(header)`, the subtraction **cannot** underflow |
+| 6 | **Verify the TOCTOU claim** | Can the checked value change between the check and the use? Checked then immediately used within the same function with no external modification = no TOCTOU |
+| 7 | **Understand API contracts and trust boundaries** | Some APIs carry their own boundary protection and never write out of bounds regardless of input |
+| 8 | **Distinguish internal storage from external input** | Config stores and registries are controlled by trusted components — they are **not** attacker-controlled |
+| 9 | **Do not mistake pattern recognition for vulnerability analysis** | Code that "looks fragile" can be safe given the context and API contracts |
+| 10 | **Verify concurrent access is actually possible** | Single-threaded initialization contexts cannot race; verify the threading model and synchronization mechanisms |
+| 11 | **Assess real vs theoretical impact** | Failed storage of non-critical data is an operational issue. Ask: does it lead to code execution, privilege escalation, or information disclosure? |
+| 12 | **Distinguish defense in depth from primary controls** | When the primary defense exists, a failing defense-in-depth layer is not necessarily a vulnerability |
+| 13 | **Apply this checklist rigorously, not superficially** | Having a checklist does not stop false positives. **Every** suspected vulnerability must go through **all** items |
+
+---
+
+## C.5 Devil's advocate (two-way symmetric doubt)
+
+This is the most elegant part of the whole design: **it prevents false positives and false negatives at the same time**.
+
+### Opposing the defect (11 questions, against false positives)
+
+1. Am I **hallucinating** this defect? (models are biased toward seeing bugs everywhere and rating them all critical)
+2. Am I doing **pattern matching** rather than analysis?
+3. Am I **confusing trust boundaries**?
+4. Is my proof **rigorous**? (any "probably" / "should"?)
+5. Am I treating **defense in depth** as a primary control?
+6. Does the attacker really **control** this input?
+7. Is this path really **reachable**?
+8. Am I **ignoring upstream validation**?
+9. Does the environmental defense **fully prevent** exploitation?
+10. Is the impact **real** or operational?
+11. Am I **overestimating severity**?
+
+### Supporting the defect (2 questions, **asked in every case**, against false negatives)
+
+12. **Am I dismissing a real defect because the exploitation path is complex or unlikely?**
+13. **Am I inventing mitigations or validation logic that I did not verify in the source code?**
+    → After reaching a conclusion, **re-read the code**.
+
+> Questions 12 and 13 are the key to preventing false negatives. The model's default bias is "reporting too much",
+> so most false-positive defenses suppress it; but over-suppression misses real defects.
+> These two questions are the symmetric counterweight — they must not be skipped.
+
+---
+
+## C.6 Deep verification: task dependency structure
+
+```
+Phase 1: 1.1 map trust boundaries + trace data flow
+           ├─ 1.2 research API contracts and security guarantees   ┐
+           ├─ 1.3 environmental defense analysis                  ├─ all blocked by 1.1
+           └─ 1.4 cross-reference analysis                        ┘
+Phase 2 (blocked by P1): 2.1 confirm attacker-controlled input    ┐
+                         2.2 mathematical boundary verification   ├─ parallel
+                         2.3 race-condition feasibility proof     ┘
+                         └→ 2.4 adversarial analysis (blocked by 2.1/2.2/2.3)
+Phase 3 (blocked by P2): 3.1 prove real security impact         ┐ parallel
+                         3.2 primary control vs defense in depth ┘
+Phase 4 (blocked by P3): 4.1 pseudocode PoC + data-flow diagram (always required)
+                         ├─ 4.2 executable PoC (if feasible)       ┐
+                         ├─ 4.3 unit-test PoC (if feasible)        ├─ parallel
+                         └─ 4.4 Negative PoC                       ┘
+                         └→ 4.5 verify the PoC actually demonstrates the vulnerability
+Phase 5 (blocked by P4): 5.1 devil's advocate review (13 questions)
+Gate Review (blocked by P5): 6-gate assessment → verdict
+```
+
+### Execution rules
+
+- Mark a task in-progress when it starts; mark it completed **only with concrete evidence**
+- Launch parallel substages with concurrent subagents; **collect all results** before entering the next dependency gate
+- **Never start a stage before all its dependencies are complete**
+- **Phase 3 / Phase 5 / Gate Review must not be delegated** — they require cross-stage synthesis
+
+### Subagent permissions are deliberately asymmetric
+
+| Subagent | Permission |
+|---|---|
+| Data-flow analysis | **read-only** |
+| Exploitability verification | **read-only** |
+| PoC construction | the only one with write access |
+
+**The ability to manufacture evidence is concentrated in a single stage**; the earlier stages can only observe — this reduces the risk of contaminating evidence.
+
+---
+
+## C.7 PoC rules
+
+### Feasibility skip conditions (skipping requires a reason)
+
+**Executable PoC**:
+
+- Requires hardware or network unavailable locally
+- The target language runtime is not installed
+- Exploitation requires **modifying** production code (rather than calling it)
+- The defect is in a closed-source component
+
+**Unit-test PoC**:
+
+- The project has no test infrastructure
+- The fragile code cannot be invoked in isolation (deep dependency chain with no test fixtures)
+- The build system is broken
+
+### The 5 PoC-verification questions
+
+1. Does the pseudocode accurately trace Step 1's data flow?
+2. Did the executable PoC **actually run** and show the impact? (capture **real output**, not expected output)
+3. Does the unit test pass and demonstrate the problem?
+4. Does the Negative PoC correctly identify the preconditions?
+5. **Is there any artificial bypass** (mocks, stubs, disabled checks)? — **if so, the PoC is invalid**
+
+### The purpose of the Negative PoC (not optional)
+
+Shows the same path working normally under **benign input** → shows the **specific preconditions** exploitation requires →
+explains why it does not hold under normal use, but the attacker can force it to hold.
+
+**This is not proving the defect false** — it records the delta between the safe and unsafe conditions, which is useful for fixes.
+
+---
+
+## C.8 Batch triage
+
+When there are multiple suspected bugs:
+
+1. Run step zero on **all** of them first (restatement often dismantles obvious false positives outright)
+2. Route each one independently
+3. **Process all standard-routed ones first, then deep-routed ones**
+4. After all verifications, check for **exploit chains** — findings that individually fail the gates may combine into a viable attack
+
+## C.9 Final summary format
+
+1. Count: X TRUE POSITIVE, Y FALSE POSITIVE, Z INCONCLUSIVE
+2. TRUE POSITIVE list: each with a brief vulnerability description
+3. FALSE POSITIVE list: each with a brief rejection reason
+4. INCONCLUSIVE list: **each with what is missing and why**

package/.claude/commands/euthyna.md

@@ -0,0 +1,18 @@
+---
+description: 代码安全审计：按 euthyna 纪律审一段代码、一次变更或一条漏洞结论，产出带证据的报告
+argument-hint: "<路径 或 diff 范围>"
+allowed-tools: Read, Grep, Glob, Bash, Task
+---
+
+# /euthyna — 代码安全审计（判定纪律）
+
+**审计目标：** $ARGUMENTS
+
+按 euthyna 技能执行一次完整审计：
+
+1. **先加载纪律**：找到 euthyna 技能目录（`~/.claude/skills/euthyna/`、项目 `.claude/skills/euthyna/` 或 `.agents/skills/euthyna/`），读 `SKILL.md`，需要时再读 `references/`。找不到就明说「技能缺失」，不要凭印象执行。
+2. **按入口决策树走**：单条漏洞结论 → 阶段 C；一次变更 → 阶段 B；依赖面 → 阶段 A；整体审计 → 阶段 B 为主。
+3. **先测量再读码**：diff 有删除行先跑 `history`；谈测试覆盖先跑 `coverage`；依赖声明先跑 `deps`（操作手册在 `references/fact-producers.md`）。
+4. **每条结论过六道门禁**：证据到 `文件:行号`、可复现命令、影响说明；拿不出证据的降级为「观察」。
+5. **三态裁定**：`BUG #N TRUE POSITIVE / FALSE POSITIVE / INCONCLUSIVE`。
+6. **报告落盘**：`<项目>_EUTHYNA_AUDIT_<日期>.md`，并跑 `euthyna gate <报告>` 校验（退出码 0 才算过）。

package/.opencode/commands/euthyna.md

@@ -0,0 +1,8 @@
+---
+description: Run the euthyna code security audit CLI
+---
+Run the euthyna CLI with these arguments and report the measured result:
+
+    euthyna $ARGUMENTS
+
+If `euthyna` is not installed, use `npx -y euthyna $ARGUMENTS` instead. Quote the command's output verbatim, exit code included — never estimate or re-derive numbers. If the euthyna skill is installed (`.agents/skills/euthyna/` or `~/.agents/skills/euthyna/`), read its SKILL.md and interpret the output under the six-gate adjudication format; claims without evidence are downgraded to observations.

package/README.md

@@ -10,6 +10,8 @@
 
 <p align="center">
   <a href="https://github.com/slow-stack/euthyna/actions/workflows/ci.yml"><img src="https://github.com/slow-stack/euthyna/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.skills.sh/slow-stack/euthyna"><img src="https://skills.sh/b/slow-stack/euthyna.svg" alt="Agent skills installs"></a>
+  <a href="https://awesome-dsh-plugin.com/p/slow-stack/euthyna/"><img src="https://img.shields.io/badge/DSH%20plugin-listed-blue" alt="Listed in the awesome-dsh-plugin catalog"></a>
 </p>
 
 **euthyna is a code security audit framework for AI coding agents.** It is not another
@@ -93,13 +95,19 @@ the project is deliberately zero-dependency.
 
 | Host | The skill (audit discipline) | The CLI (fact producers) |
 |---|---|---|
-| **DSH** | Copy `.agents/skills/euthyna/` into `~/.agents/skills/` (user-wide) or `<project>/.agents/skills/`. Markdown hot-reloads; no restart needed. | `npm install -g euthyna` — runs in any terminal |
-| **Claude Code** | Copy the same folder into `~/.claude/skills/` | Same |
+| **DSH** | `dsh plugin --profile web add euthyna` — the npm package mounts its own skill; or copy `.agents/skills/euthyna/` into `~/.agents/skills/` (user-wide) or `<project>/.agents/skills/`. Markdown hot-reloads; no restart needed. | `npm install -g euthyna` — runs in any terminal |
+| **Claude Code** | `/plugin marketplace add slow-stack/euthyna` then `/plugin install euthyna@euthyna`, or copy `.agents/skills/euthyna/` into `~/.claude/skills/` | Same |
 | **Codex** | The same Markdown layer works; packaging goes through Codex's plugin/marketplace format | Same |
-| **Hermes** | Copy the same folder into `~/.hermes/skills/` under a category folder (Hermes reads the open skill standard; or install from a repo with `hermes skills install`) | Same |
-| **OpenCode** | Copy the same folder into `~/.agents/skills/` or `~/.config/opencode/skills/` (OpenCode loads both; unknown frontmatter fields are ignored) | Same |
+| **Hermes** | Copy the same folder into `~/.hermes/skills/` under a category folder, or install from a repo with `hermes skills install` — and for the slash command, install the repo as a plugin (see below) | Same |
+| **OpenCode** | Copy the same folder into `~/.agents/skills/` or `~/.config/opencode/skills/` (OpenCode loads both; unknown frontmatter fields are ignored). For a `/euthyna` slash command, copy `.opencode/commands/euthyna.md` into `~/.config/opencode/commands/` — it is a prompt template that tells the model to run the CLI | Same |
+| **OpenClaw** | Copy the same folder into `~/.agents/skills/` (or `<workspace>/.agents/skills/`) — OpenClaw exposes every `user-invocable` skill as a slash command natively, so `/euthyna` works with no extra file | Same |
 | **Any terminal** | — | `npm install -g euthyna`, then `euthyna …` |
 
+The skill ships in two languages. The directory above is the Chinese original (`euthyna`);
+an English mirror lives at `.agents/skills/euthyna-en/` (skill name `euthyna-en`) — install
+that one for an English-speaking agent, or translate the folder yourself. Both define the
+same discipline, and `euthyna gate` accepts report markers in either language.
+
 Two honest notes:
 
 - **The skill is the instructions; the CLI is the measurement.** The skill directory
@@ -107,9 +115,47 @@ Two honest notes:
   keep this repository checked out; on a host without the CLI, the skill requires the
   unmeasurable criteria to be recorded as *not evaluated* rather than guessed at — that
   fallback is the design, not a gap.
-- **The skill text and the CLI's reports are currently written in Chinese.** The
-  discipline is host-agnostic Markdown, but an English reader should expect Chinese
-  output from the tool itself.
+- **The CLI speaks Chinese by default, English on request.** Output is Chinese unless you
+  pass `--lang en` (any command) or set `EUTHYNA_LANG=en`; the default never changes for
+  existing users. The skill text and the CLI's reports exist in both languages — the
+  English reader should expect Chinese only from a run that did not ask for English.
+
+---
+
+## 🎯 First use
+
+euthyna is **user-invoked, not auto-triggering**. The skill declares
+`disable-model-invocation: true`, so the model will not load it on its own —
+you have to ask for the audit explicitly. That is also how you tell it apart
+from other security skills you may have installed: **if you did not name it,
+it did not run.**
+
+### Triggering the audit
+
+Say it plainly in conversation:
+
+> 「用 euthyna 审计一下 `D:\some-project`，审完再交付」
+
+The agent then loads the skill and runs the audit discipline: it produces the
+deterministic facts (`history` / `coverage` / `deps`) first, walks every
+suspect through the six gates, and writes a report file instead of only
+replying in chat.
+
+### Slash commands
+
+| Host | Command | Setup |
+|---|---|---|
+| Claude Code | `/euthyna <path>` | copy `.claude/commands/euthyna.md` from the package into `~/.claude/commands/` (user-wide) or `.claude/commands/` (project) |
+| Codex | — | Codex's custom-prompt slash commands (`~/.codex/prompts/`) are deprecated upstream; the same Markdown can still be placed there manually |
+| DSH | `/euthyna` | installed with the plugin; after a restart the command prints the usage manual (DSH slash commands run without reaching the model) |
+| Hermes | `/euthyna <subcommand> <args…>` | install this repository as a Hermes plugin: `hermes plugins install slow-stack/euthyna` then `hermes plugins enable euthyna` (needs Node >= 20 on PATH; the repo root carries `plugin.yaml` + `__init__.py`). The command forwards to the CLI and prints its output without reaching the model. The skill itself can still be installed separately with `hermes skills install slow-stack/euthyna/.agents/skills/euthyna` |
+
+### How to tell it was euthyna that audited
+
+- the report filename is `<PROJECT>_EUTHYNA_AUDIT_<YYYY-MM-DD>.md`
+- verdicts use the three-state shape `BUG #N TRUE POSITIVE / FALSE POSITIVE / INCONCLUSIVE`
+- every claim cites `path:L123` evidence and a reproduce command
+- missing data is recorded as *not evaluated*, never as "clean"
 
 ---
 
@@ -258,6 +304,7 @@ This project tries to be explicit about the difference. Current state:
 euthyna/
 ├── bin/  src/  test/        Fact producers (zero dependencies, Node >= 20)
 ├── .agents/skills/euthyna/  The audit discipline, as a portable skill
+├── plugin.yaml  __init__.py  Hermes plugin: the /euthyna slash command
 ├── bench/                   Blind recall benchmark + results
 ├── docs/                    Design notes and case studies (English and Chinese)
 ├── tools/                   Research and verification scripts