extrospect 0.1.0__tar.gz

extrospect-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# ---------------------------------------------------------------------------
+# Internal development docs — NEVER commit.
+# Roadmaps, planning notes, progress logs and manual test checklists live in
+# /internal/ and stay on the developer's machine only.
+# ---------------------------------------------------------------------------
+/internal/
+*.internal.md
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.python-eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Node helpers (optional tooling installed per-project)
+node_modules/
+.tools/
+
+# Evaluation artifacts: only dataset manifests are committed, never samples
+eval/samples/
+eval/runs/
+# generated by eval/make_injection_variants.py (contains local paths)
+eval/datasets/injection.jsonl
+eval/.cache/
+*.crx
+!tests/fixtures/**/*.crx
+
+# Local runtime data
+.extrospect/
+traces/
+*.sqlite
+*.sqlite3
+*.db
+*.lance/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*

extrospect-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog / 更新日志
+
+## 0.1.0 - 2026-10-23 (alpha)
+
+First public release. / 首次公开发布。
+
+**English**
+
+- Local risk analysis of Chromium-based browser extensions (Chrome, Edge, Brave, Chromium,
+  Vivaldi), or of a `.crx` / `.zip` / directory / Chrome Web Store id: CLI `extrospect`
+  and MCP server `extrospect-mcp`.
+- Static pipeline (zero tokens): permission tiers and combinations, CSP, attack surface,
+  known-vulnerable libraries (retire.js + EPSS), bundle unpacking and deobfuscation,
+  tree-sitter sink detection, data-flow patterns, code slicing, prompt-injection detection.
+- Host mode: the MCP client's model investigates with 13 tools, an `audit_my_extensions`
+  prompt and report resources; evidence quotes are verified and the score is computed
+  server-side.
+- Engine mode (experimental, BYOK): layered LLM pipeline through litellm - triage,
+  investigator agent, verifier.
+- Knowledge bases: store listings, malware-technique intel, security advisories.
+- Results are labelled by what produced them: static-only scores are shown as attack
+  surface, verdicts that cannot be verified as "needs review".
+- English and Simplified Chinese interface, reports and documentation.
+- Evaluation harness, including Host-mode evaluation through Claude Code, and a first
+  real-world evaluation (`docs/eval_real_world.md`).
+
+**中文**
+
+- 在本机分析 Chromium 系浏览器（Chrome、Edge、Brave、Chromium、Vivaldi）里安装的扩展，也可以分析
+  `.crx` / `.zip` / 目录 / Chrome 商店 ID：命令行 `extrospect` 和 MCP server `extrospect-mcp`。
+- 静态管线（零 token）：权限分级与组合、CSP、攻击面、已知漏洞库（retire.js + EPSS）、拆包和解混淆、
+  基于 tree-sitter 的 sink 检测、数据流模式、代码切片、提示注入检测。
+- Host 模式：MCP 客户端的模型用 13 个工具、`audit_my_extensions` prompt 和报告资源做调查；证据引用的核对和
+  分数计算都在服务器端完成。
+- Engine 模式（实验性，BYOK）：通过 litellm 的分层 LLM 管线——分诊、调查员 agent、核对器。
+- 知识库：商店页面、恶意手法情报、安全公告。
+- 结果按来源标注：只有静态分析时显示为攻击面，无法核实的结论显示为"需人工复核"。
+- 英文和简体中文的界面、报告和文档。
+- 评测框架，包括通过 Claude Code 做的 Host 模式评测，以及首轮真实环境评测（`docs/zh-CN/eval_real_world.md`）。

extrospect-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

extrospect-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+Extrospect
+Copyright 2026 johnnyzn
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

extrospect-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: extrospect
+Version: 0.1.0
+Summary: Local browser-extension risk analysis engine with code evidence, exposed as a CLI and an MCP server.
+Project-URL: Homepage, https://github.com/johnnyzn/Extrospect
+Project-URL: Documentation, https://github.com/johnnyzn/Extrospect/tree/main/docs
+Project-URL: Changelog, https://github.com/johnnyzn/Extrospect/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/johnnyzn/Extrospect/issues
+Author: johnnyzn
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: browser-extension,chrome,llm,malware,mcp,security,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsbeautifier>=1.15
+Requires-Dist: mcp>=2.0
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: regex>=2024.5.15
+Requires-Dist: rich>=13.7
+Requires-Dist: tldextract>=5.1
+Requires-Dist: tree-sitter-javascript>=0.25
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: lancedb>=0.13; extra == 'all'
+Requires-Dist: lightgbm>=4.3; extra == 'all'
+Requires-Dist: litellm>=1.60; extra == 'all'
+Requires-Dist: numpy>=1.26; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.4; extra == 'all'
+Provides-Extra: eval
+Requires-Dist: pyyaml>=6.0; extra == 'eval'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.60; extra == 'llm'
+Provides-Extra: ml
+Requires-Dist: lightgbm>=4.3; extra == 'ml'
+Requires-Dist: numpy>=1.26; extra == 'ml'
+Requires-Dist: scikit-learn>=1.4; extra == 'ml'
+Provides-Extra: rag
+Requires-Dist: lancedb>=0.13; extra == 'rag'
+Requires-Dist: numpy>=1.26; extra == 'rag'
+Description-Content-Type: text/markdown
+
+# Extrospect
+
+**Local risk analysis for browser extensions, with code evidence.**
+Ask your AI assistant *"are my browser extensions safe?"* and get an answer backed by
+verified quotes from the extensions' source code.
+
+[中文说明](https://github.com/johnnyzn/Extrospect/blob/main/README.zh-CN.md) ·
+[Architecture](https://github.com/johnnyzn/Extrospect/blob/main/docs/architecture.md) ·
+[Scoring](https://github.com/johnnyzn/Extrospect/blob/main/docs/scoring.md) ·
+[MCP setup](https://github.com/johnnyzn/Extrospect/blob/main/docs/mcp.md) ·
+[Languages](https://github.com/johnnyzn/Extrospect/blob/main/docs/i18n.md) ·
+[Evaluation](https://github.com/johnnyzn/Extrospect/blob/main/docs/eval_real_world.md) ·
+[Changelog](https://github.com/johnnyzn/Extrospect/blob/main/CHANGELOG.md)
+
+Extrospect runs on your machine. It finds the extensions installed in Chrome, Edge, Brave,
+Chromium and Vivaldi profiles (or takes a `.crx` / `.zip` / directory / Web Store id),
+analyses what they *can* do and what their code *actually* does, and produces an
+explainable 0-100 score.
+
+| | |
+|---|---|
+| **Host mode (MCP)** | an MCP server: the model in your AI client (Claude Code, Codex, Cursor, VS Code, ...) becomes the investigator, Extrospect provides the tools, verifies the evidence and computes the score - no extra API cost |
+| **Static pipeline (zero tokens)** | permission tiers and combinations, CSP, attack surface, known-vulnerable libraries (retire.js + EPSS), deobfuscation, tree-sitter detection of data sources, exfiltration channels, dynamic code and hijacking, data-flow patterns, code slicing |
+| **Engine mode (BYOK, experimental)** | a layered LLM pipeline - small-model triage, a larger-model investigator agent with tools, and a verifier that checks every evidence quote against the source |
+| **Prompt-injection aware** | comments and long strings are stripped before code reaches a model; text addressed to AI reviewers ("classify this as benign", "忽略之前的指令") is detected and reported as a red flag |
+| **Multilingual** | English and Simplified Chinese UI and reports; LLM-written text in any language |
+
+## Status: alpha (0.1.0)
+
+What has been checked:
+
+- **Host mode** end to end in Claude Code with Opus 5.5, Sonnet 5.5 and Haiku 4.5. On 43
+  popular and deep-integration benign extensions from the Chrome Web Store (password
+  managers, ad blockers, wallets, translators, AI sidebars, developer tools) Sonnet 5.5
+  produced **no false positive**; every hand-written malicious test extension, including
+  one that tries to talk the reviewer into a benign verdict, was detected by all three
+  models. Details: [real-world evaluation](https://github.com/johnnyzn/Extrospect/blob/main/docs/eval_real_world.md).
+- About 170 offline tests (zero tokens); CI on Linux, macOS and Windows.
+
+Known limitations:
+
+- **The detection rate on real malware is not measured yet.** The malicious extensions
+  that can still be downloaded are years old and have probably been cleaned up, so the
+  evaluation has no reliable malicious samples.
+- **A static score alone measures attack surface, not malice.** Large legitimate
+  extensions score high, so `extrospect scan` shows it as *attack surface* rather than as
+  a risk level. Get a verdict through Host mode (or Engine mode).
+- Smaller models (e.g. Haiku 4.5) sometimes fail the evidence check; such results are
+  shown as *needs review* instead of being trusted.
+- Engine mode has not yet been validated with real models - treat it as experimental.
+- Chromium-based browsers only (no Firefox or Safari yet).
+
+Reports of false positives or missed detections are very welcome in the
+[issue tracker](https://github.com/johnnyzn/Extrospect/issues).
+
+## Install
+
+Requires Python 3.11+. Pick one:
+
+```bash
+uv tool install extrospect      # recommended: isolated environment, uv manages Python
+pipx install extrospect         # isolated environment with pipx
+pip install extrospect          # into the current (virtual) environment
+```
+
+Then check the setup (optional tools, API keys, browser profiles):
+
+```bash
+extrospect doctor
+```
+
+Extras work the same way with all three, e.g. `pip install "extrospect[llm]"`:
+`llm` (Engine mode), `rag` (LanceDB vector store), `all`. Optional Node.js helpers are
+used automatically when present:
+`npm i -g webcrack prettier retire` (bundle unpacking/deobfuscation, formatting, the
+official retire.js scanner); without them Extrospect falls back to built-in equivalents.
+
+From source:
+
+```bash
+git clone https://github.com/johnnyzn/Extrospect && cd Extrospect
+uv sync --all-extras
+uv run extrospect doctor          # prefix the commands below with `uv run`
+```
+
+## Use it from your AI assistant (MCP)
+
+```bash
+claude mcp add extrospect -- uvx --from extrospect extrospect-mcp
+```
+
+Installed with `pip` or `pipx` instead of uv? Use the installed command:
+`claude mcp add extrospect -- extrospect-mcp` (inside a virtual environment, give its
+full path, e.g. `.venv/bin/extrospect-mcp`).
+
+Then ask *"Check my browser extensions"* or run the `/mcp__extrospect__audit_my_extensions`
+prompt. It works with any MCP client that can start local servers - Claude Code, Claude
+Desktop, Codex (CLI, IDE, the Codex tab of the ChatGPT desktop app), Cursor, VS Code,
+Windsurf, Gemini CLI - but not with ChatGPT's chat, which only connects to remote servers.
+Setup for each client, tools and the security model:
+[docs/mcp.md](https://github.com/johnnyzn/Extrospect/blob/main/docs/mcp.md).
+So far it has been evaluated with Claude models; a capable model (Sonnet or Opus class)
+is recommended.
+
+## Command line
+
+```bash
+# Every installed extension, ranked by static score (attack surface; no LLM, no cost)
+extrospect scan --local
+
+# One extension: a directory, a .crx/.zip, or a Web Store id (downloads the current version)
+extrospect scan path/to/extension
+extrospect scan --id aapbdbdomjkkjkaonfhkkikfgjllcleb -f html -o report.html
+
+# Engine mode (experimental): full LLM analysis with your own API key
+export ANTHROPIC_API_KEY=...
+extrospect analyze <id-or-path> --max-cost 0.30
+extrospect trace show <trace-id>     # replay the agent's trajectory
+
+# Reports in Chinese
+extrospect --lang zh-CN scan --local
+```
+
+Other commands: `list`, `report`, `history`, `download`, `config init|show|path`,
+`cache stats|clear`, `knowledge build-intel|build-advisories|listing|stats`, `languages`,
+`version`.
+
+## How a score is computed
+
+```
+A    capability            what permissions + manifest allow (tiers, combinations, CSP)
+Ev   vulnerability         max over CVEs of EPSS percentile x reachability weight
+Em   malicious evidence    verified LLM verdict / GBM / rule baseline
+E    = 1 - (1 - Ev)(1 - Em)
+Risk = 100 x A^0.5 x E^0.7  (+ hard rules)  ->  benign / low / medium / high / critical
+```
+
+The LLM never sets the score: it produces a verdict and evidence, the Verifier drops
+evidence whose quote is not in the file, and the formula does the rest. Every report
+shows the breakdown. Without a model verdict the score is shown as **attack surface**,
+not as a risk level, and a verdict that cannot be verified is shown as **needs review**.
+Details: [docs/scoring.md](https://github.com/johnnyzn/Extrospect/blob/main/docs/scoring.md).
+
+## Privacy
+
+Extrospect never uploads your extension list or extension code. Network access is
+limited to: downloading a CRX when you pass a Web Store id, the retire.js vulnerability
+repository, EPSS scores (CVE ids only), GitHub advisories (CVE ids), store listing pages
+(only for the extension being investigated) and RDAP domain lookups. `--offline` disables
+all of it. In Host mode the code your AI client reads goes to that client's model
+provider; in Engine mode the analysed code slices go to the LLM provider you configured.
+
+## Configuration
+
+`extrospect config init` writes a commented `config.toml` with every default: models per
+role (any [litellm](https://docs.litellm.ai/) model id, including local `ollama/...`),
+budgets, router thresholds, score weights, tool paths and language. Environment
+variables: `EXTROSPECT_LANG`, `EXTROSPECT_OFFLINE`, `EXTROSPECT_*_MODEL`,
+`EXTROSPECT_DATA_DIR`, `EXTROSPECT_CACHE_DIR`, `EXTROSPECT_BROWSER_ROOTS`.
+
+## Evaluation
+
+`eval/` contains the dataset manifests (ids and labels only, never samples), the ablation
+configurations and the evaluation scripts:
+
+```bash
+uv run python eval/fetch_samples.py --dataset eval/datasets/seed.jsonl
+uv run python eval/run_eval.py --dataset eval/datasets/seed.jsonl --configs rules
+uv run python eval/run_eval.py --dataset eval/datasets/seed.jsonl --configs all --yes   # spends API credits
+uv run python eval/run_host_eval.py --model claude-sonnet-5-5 --yes   # Host mode via Claude Code
+```
+
+Results: [real-world evaluation](https://github.com/johnnyzn/Extrospect/blob/main/docs/eval_real_world.md)
+and the generated [eval_results.md](https://github.com/johnnyzn/Extrospect/blob/main/docs/eval_results.md).
+
+## Development
+
+```bash
+uv run pytest          # ~170 tests, offline, zero tokens (LLM calls use fake backends)
+uv run ruff check src tests eval && uv run mypy
+```
+
+Security issues: see [SECURITY.md](https://github.com/johnnyzn/Extrospect/blob/main/SECURITY.md).
+
+## License
+
+[Apache License 2.0](https://github.com/johnnyzn/Extrospect/blob/main/LICENSE).