[bug] Fixing docs and a few inconsistencies

Author: alexeyev

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 opencode-agent-cooper contributors
+Copyright (c) 2026 opencode-fireman contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -21,27 +21,61 @@ ships silently and surfaces weeks later.
 
 ## What Fireman does
 
-When your agent reads a TypeScript file, Fireman checks whether any
-function diverges structurally from its near-twins — for example, it sorts
-where its lookalikes don't. If so, it appends a short note to what the
-agent reads, **before** it plans an edit:
+When your agent reads a source file in a supported language, Fireman
+checks whether any function diverges structurally from its near-twins —
+siblings in the same directory or same-basename files across the package.
+If so, it appends a short note to what the agent reads, **before** it
+plans an edit:
 
 ```
 <fireman>
-⚠ Fireman: audit-serializer.ts:13-29 — serializeAudit sorts keys; 2 similar
-sibling functions do not. This asymmetry may be load-bearing (signature
-stability, wire-format determinism). Verify before deduplicating.
+⚠ Fireman: this file contains region(s) whose meaning depends on
+context outside the local function body (sibling/cross-file asymmetry,
+or imports from a compatibility path). The signals may encode an
+invariant — verify before editing:
+- audit-serializer.ts:13-29 [extra-call, conf=0.85]: createAuditRecord
+  has 2 extra call(s) vs 2 consensus siblings. This asymmetry may be
+  load-bearing; verify before unifying.
 </fireman>
 ```
 
 That's it. The agent gets a heads-up and decides for itself.
 
+## Supported languages
+
+TypeScript, JavaScript, Python, Java, C, C++, Scala, and PHP — via
+[tree-sitter](https://tree-sitter.github.io/) language grammars with
+dedicated adapters per language family. Unsupported file extensions are
+silently skipped (zero findings, zero overhead).
+
+## Two detectors
+
+1. **Structural asymmetry** — Fireman builds normalised ASTs for every
+   function in the file and its directory/cross-file siblings, forms
+   twin families via MinHash/Jaccard similarity, then characterises each
+   family's divergent member by shape (extra-call, extra-branch,
+   label-divergence, etc.) and data-flow critical-path analysis.
+
+2. **Compat-shim imports** — Fireman scans for import-like statements
+   whose paths contain markers like `legacy`, `compat`, `polyfill`,
+   `deprecated`, `shim`, `backport`, or versioned segments (`v1`, `v2`).
+   These imports signal explicit bridges to non-canonical implementations.
+
+Both detectors point at things outside the local function body:
+divergence from non-local twins, and explicit bridges to non-canonical
+code. Either way, "edit only this function" is unsafe advice.
+
 ## Safe by design
 
 - **Never edits your files** — it only annotates what the agent reads.
 - **Never blocks a tool call** — a warning, not a gate.
-- **Fast** — budgeted at ≤400 ms per file, with a hard timeout.
-- **Quiet** — ≤80 tokens per warning, no LLM calls, no network.
+- **Hard timeout** — 3000 ms per file, wrapped in `Promise.race`.
+- **Bounded output** — max 3 findings per warning.
+- **No network** — all analysis is local; no LLM calls in the hot path.
+- **Plugin-compatible** — tested alongside
+  [caveman](https://github.com/JuliusBrussee/caveman) and
+  [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode).
+  See [PLUGIN_COMPATIBILITY.md](./PLUGIN_COMPATIBILITY.md).
 
 ## Install
 
@@ -63,9 +97,12 @@ project, put the same two files under `~/.config/opencode/` instead.
 
 ## Good to know
 
-TypeScript / TSX only, and v0.1 ships a single detector (a function that
-sorts where its siblings don't). Fireman is a heuristic — it can miss, and
-it can occasionally over-warn. Treat a warning as *"look before you leap,"*
+v0.0.1 ships two detectors across 8 languages with a 105-case test
+bench (75 traps + 30 controls) covering TypeScript, JavaScript, Python,
+Java, C, C++, and PHP — including 10 cases from 7 hardware-accelerator
+ecosystems (NVIDIA CUDA, AMD HIP, Intel SYCL, Google TFLite, Huawei
+Ascend, Qualcomm SNPE). Fireman is a heuristic — it can miss, and it
+can occasionally over-warn. Treat a warning as *"look before you leap,"*
 not *"stop."*
 
 How it works in detail, the test bench, and the design guarantees: