focus-hud 0.1.0__tar.gz

focus_hud-0.1.0/.cursor/rules/README.md

@@ -0,0 +1,13 @@
+# Focus Cursor Rules
+
+Project-specific rules loaded by Cursor when you work in this repo.
+
+| File | Purpose |
+|---|---|
+| `focus-project.mdc` | Product context, architecture, tech stack *(public, committed)* |
+| `focus-engineering.mdc` | Non-negotiable engineering constraints *(public, committed)* |
+| `focus.mdc` | Diagnostic engine identity, HUD contract, directives *(symlink → `cursor-rules/focus/`)* |
+| `focus-learning.mdc` | Learn-while-building technology map *(symlink → `cursor-rules/focus/`)* |
+| `focus-mentorship.mdc` | Mentorship protocol *(symlink → `cursor-rules/focus/`)* |
+
+Global rules (SWE standards, communication, owner profile) live in the private **`cursor-rules`** repo, symlinked to `~/.cursor/plugins/local/swe-standards`.

focus_hud-0.1.0/.cursor/rules/focus-engineering.mdc

@@ -0,0 +1,34 @@
+---
+description: Focus immutable engineering rules — non-negotiable constraints
+alwaysApply: true
+---
+
+# Focus — Immutable Engineering Rules
+
+These are non-negotiable. If a task appears to require breaking one of these rules, **stop and ask the project owner** rather than improvising a workaround.
+
+1. **Full-repo graph, never diff-only.** Tree-sitter must index the entire repository (respecting `.gitignore`). Blast radius is computed via reverse traversal on the dependency graph. Reading only the git patch to infer impact is forbidden — it causes the blindspots Focus exists to eliminate.
+
+2. **LLM labels topology; LLM does not invent topology.** The dependency graph and blast radius subgraph are computed deterministically. The LLM may generate Mermaid labels, executive summary prose, and layout hints from structured JSON — it must not add nodes or edges not present in the graph payload. Validate Mermaid output against the graph before posting.
+
+3. **Smart triggers are mandatory.** Do not generate diagrams for every change. Pass-through (summary only) for markdown, cosmetic UI, comments, and isolated private utils with zero downstream surface hits. Diagram for schema, API route, global state, dependency manifest, or blast radius above threshold.
+
+4. **Credential isolation via `.env`.** LLM API keys and GitHub tokens live in `.env`, loaded via `pydantic-settings`. Never hardcode, commit, or log secrets. `.env.example` stays in sync with placeholders only.
+
+5. **Passive UX only.** Focus comments and CLI output inform; they never block merges, gate CI, or quiz developers. No required interactive steps.
+
+6. **Mermaid first, SVG fallback later.** Primary output is Mermaid in CLI stdout and GitHub PR comments (native render). Pre-rendered SVG/Graphviz is a Phase 3+ fallback when validation fails — not the default.
+
+7. **Type everything.** Python: full type hints, Pydantic models for graph payloads, HUD schema, and CLI I/O.
+
+8. **Framework agnostic.** Heuristics for routes/schemas/state use patterns (decorators, path conventions) — not hard dependency on one web framework. Phase 1 proves the pipeline on plain Python imports/calls first.
+
+9. **No silent refactors.** Do not restructure or rename beyond explicit task scope. Propose and ask first.
+
+10. **Parse cache is optional, correctness is not.** File-hash AST caches may speed repeat runs but must invalidate on content change. Never serve stale graph data silently.
+
+11. **Privacy-by-design.** Respect `.gitignore` and `.focusignore`. Never parse, log, or transmit `.env`, keys, or credential files. LLM calls (when enabled) receive structured graph JSON only — not full source files. See `docs/PRIVACY.md`.
+
+12. **No surveillance features.** Do not build developer identity tracking, blame metrics, merge gates, or management dashboards. Focus analyzes code structure for review aid only. See `docs/ETHICS.md`.
+
+13. **Stay current — no stale deps or Actions.** Prefer current stable majors for Python packages (`uv lock` / `uv sync`) and GitHub Actions. When adding or touching a workflow, verify `uses:` pins against **tags that actually exist** on the action's releases page (e.g. `actions/checkout@v7`, `astral-sh/setup-uv@v8.3.2`) — do not invent floating majors like `@v8` if the repo only publishes `@v8.x.y`. On dependency or CI work: check for newer stable versions and upgrade unless there is a documented break. Deprecation warnings and "unable to resolve action" failures in CI are defects to fix, not noise to ignore.

focus_hud-0.1.0/.cursor/rules/focus-project.mdc

@@ -0,0 +1,66 @@
+---
+description: Focus project context, architecture, and tech stack
+alwaysApply: true
+---
+
+# Focus — Project Context
+
+Focus is an **architectural diagnostic engine** — an "AR HUD for codebases." It transforms opaque "Black Box" legacy repositories into transparent "Glass Box" environments, giving developers structural clarity before they change code.
+
+## The Problem
+
+AI-generated pull requests are large and fast to produce but slow and scary to review. A line-level diff hides *blast radius*: downstream importers, API routes, schema coupling, and regression vectors. Text summaries cause cognitive overload without evidence.
+
+## The Solution
+
+Focus intercepts analysis at the CLI or GitHub Action layer and emits a **Focus HUD**:
+
+1. **Executive Summary** — 1–2 sentence architectural health assessment.
+2. **Visual Dependency Map** — Mermaid flowchart of impact paths (topology from computed graph, not LLM invention).
+3. **Blast Radius Report** — bulleted Danger Zones and downstream dependencies.
+
+## Core Capabilities
+
+| Capability | Description |
+|---|---|
+| **Focus Scan** | Tree-sitter full-repo AST index; map imports, calls, routes, schemas |
+| **Blast Radius Engine** | Reverse BFS from changed symbols; pre-flight regression simulation |
+| **Smart Triggers** | Diagram only for high-impact changes; one-liner for pass-through edits |
+
+## Design Principles
+
+- **Codebase-wide context** — never diff-only blindspots
+- **Evidence-based** — graph edges are computed; LLM labels only
+- **Concise & visual** — charts and bullets over prose walls
+- **Passive enablement** — no blocking commits, no developer quizzes (design principle; owner has asked that this line NOT appear in the README — it lives in `docs/ETHICS.md`)
+- Production-grade Python with full type hints
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| [`docs/HUD.md`](../../docs/HUD.md) | Frozen HUD schema (canonical) |
+| [`docs/STACK.md`](../../docs/STACK.md) | Locked stack decisions |
+| [`docs/DECISIONS.md`](../../docs/DECISIONS.md) | Phase 0 resolved questions |
+| [`docs/ETHICS.md`](../../docs/ETHICS.md) | Responsible use, LLM ethics, won't-build list |
+| [`docs/PRIVACY.md`](../../docs/PRIVACY.md) | Data boundaries, secrets, Action permissions |
+| [`docs/TRIGGERS.md`](../../docs/TRIGGERS.md) | Diagram vs pass-through rules |
+| [`docs/TESTING.md`](../../docs/TESTING.md) | Golden fixtures, CI constraints |
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|---|---|---|
+| CLI | Python 3.12+ / Typer | `focus scan`, `focus trace`, `focus audit` |
+| AST | Tree-sitter | Multi-language grammars; Phase 1 = Python |
+| Graph | NetworkX | Dependency graph + reverse BFS blast radius |
+| Diagrams | Mermaid.js | Native GitHub PR rendering |
+| LLM | Off by default (`FOCUS_LLM_ENABLED=false`); Phase 3+ opt-in | Node labels + layout hints from structured graph JSON only |
+| GitHub | Actions + REST API | PR comment on open/sync |
+
+## Commands
+
+- `focus scan [path]` — full-repo index + graph build
+- `focus trace [file]` — dependency map for a file/symbol
+- `focus audit [pr|branch]` — pre-merge blast radius
+- `focus audit --local` — working tree vs base branch

focus_hud-0.1.0/.focus.toml.example

@@ -0,0 +1,7 @@
+# Optional Focus config — copy to `.focus.toml` at your repo root.
+# Missing file = defaults (fan_out_threshold = 3).
+
+[focus]
+# A file becomes a Danger Zone when this many other files import it directly
+# (package __init__.py files are never Danger Zones via fan-out alone).
+fan_out_threshold = 3

focus_hud-0.1.0/.github/workflows/focus.yml

@@ -0,0 +1,47 @@
+# Opt-in Focus HUD on pull requests.
+# Permissions: contents:read (checkout) + pull-requests:write (comment only).
+# See docs/PRIVACY.md.
+
+name: Focus
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  hud:
+    name: Focus HUD
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install Focus
+        run: uv sync --frozen
+
+      - name: Run Focus audit
+        env:
+          FOCUS_BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          uv run focus audit --base "$FOCUS_BASE" --out focus-hud.md
+
+      - name: Post or update PR comment
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FOCUS_PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          uv run python -c "from pathlib import Path; from focus.ci import post_from_env; print(post_from_env(Path('focus-hud.md')))"

focus_hud-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Publish focus-hud to PyPI on version tags (v0.1.0, …) via Trusted Publishing.
+# One-time setup: https://docs.pypi.org/trusted-publishers/
+#   PyPI project: focus-hud
+#   Workflow: publish.yml on j0viane/focus, environment: pypi
+
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

focus_hud-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# --- Secrets & environment ---
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+ENV/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log
+
+# Tree-sitter build artifacts
+*.so.dSYM/
+tree-sitter-*/
+
+# Generated Focus HUD previews
+focus-hud.md
+
+# Focus parse cache (derived AST facts — safe to delete)
+.focus-cache/
+
+
+# Focus path exclusions (optional)
+# .focusignore is respected at runtime; not gitignored itself
+
+# --- Editor / OS ---
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# --- Claude Code local settings ---
+.claude/settings.local.json
+
+# --- Private Cursor rules (canonical copy in ~/Cursor/cursor-rules/focus/) ---
+.cursor/rules/focus.mdc
+.cursor/rules/focus-mentorship.mdc
+.cursor/rules/focus-learning.mdc

focus_hud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joviane Bellegarde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

focus_hud-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: focus-hud
+Version: 0.1.0
+Summary: Blast radius you can defend — evidence-only, before you merge.
+Project-URL: Homepage, https://github.com/j0viane/focus
+Project-URL: Repository, https://github.com/j0viane/focus
+Project-URL: Issues, https://github.com/j0viane/focus/issues
+Project-URL: Documentation, https://github.com/j0viane/focus/blob/main/docs/DEMO.md
+Author: Joviane Bellegarde
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,blast-radius,code-review,mermaid,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: tree-sitter-javascript>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: typer>=0.26
+Description-Content-Type: text/markdown
+
+# Focus
+
+**Blast radius you can defend — evidence-only, before you merge.**
+
+Focus answers one question: **what else in this codebase could break because of this change?**
+
+It's an **AR HUD for codebases**: a computed import graph (Python + JS/TS) → Mermaid map + Danger Zones. Same HUD in the CLI and on the PR. No LLM inventing edges.
+
+> **Not** another AI PR summary. **Not** a hop inventory that cries wolf on every file. Focus stays quiet when the change is boring, and loud when you touch a shared hub.
+
+---
+
+## Try in 60 seconds
+
+```bash
+pip install "focus-hud @ git+https://github.com/j0viane/focus.git"
+# after PyPI publish:  pip install focus-hud
+
+focus trace path/to/shared_module.py --out focus-hud.md
+# open focus-hud.md → Markdown preview for Mermaid
+
+focus audit --local --out focus-hud.md   # working tree vs main — before you push
+```
+
+**Demo fixture (no app required):**
+
+```bash
+git clone https://github.com/j0viane/focus.git && cd focus
+uv sync
+uv run focus trace tests/fixtures/glass_box/auth_utils.py \
+  --root tests/fixtures/glass_box --out focus-hud.md
+```
+
+Gallery + walkthrough: [`docs/DEMO.md`](docs/DEMO.md) · [`docs/assets/`](docs/assets/)
+
+---
+
+## Why this exists
+
+There's a new kind of pressure on developers — and it lands hardest on juniors: walk into a codebase you've never seen, point an AI at it, and ship. The code arrives in seconds. The understanding doesn't.
+
+Focus is for the moment right before you push into a codebase that was there long before you. **What the system looks like, and what your change will actually touch** — with evidence you can defend in review.
+
+| Moment | Command | You get |
+|---|---|---|
+| AI rewrote a shared function | `focus audit --local` | Blast radius of your working tree vs `main` |
+| Big PR in your queue | Focus Action comment | Skim-or-dig: diagram + Danger Zones, or “low impact” |
+| Inherited a module | `focus trace path/to/file.py` | Everything that depends on it |
+
+---
+
+## GitHub Action (any repo)
+
+Copy [`examples/focus-action.yml`](examples/focus-action.yml) → `.github/workflows/focus.yml`.  
+Details: [`docs/ACTION.md`](docs/ACTION.md). Permissions: `contents: read` + `pull-requests: write` only ([`docs/PRIVACY.md`](docs/PRIVACY.md)).
+
+---
+
+## Already exists? (CodeLayers, Valerian, …)
+
+Editor tools show hop lists while you type. Focus is **pre-merge decision support**: evidence-only topology, Danger Zones + smart triggers, **one HUD** from `audit --local` to the PR comment. Open source, local, no architecture backend required.
+
+---
+
+## Getting started (from this repo)
+
+```bash
+git clone https://github.com/j0viane/focus.git
+cd focus
+uv sync
+uv run focus scan .
+uv run focus trace src/focus/models.py --out focus-hud.md
+uv run focus audit --local
+```
+
+Unchanged files reuse **`.focus-cache/`** (gitignored). Pass `--no-cache` to force a full re-parse.
+
+Optional: copy [`.focus.toml.example`](.focus.toml.example) → `.focus.toml` to tune `fan_out_threshold` (default **3**).
+
+Requirements: Python 3.12+. Package name on PyPI: **`focus-hud`** (CLI: `focus`). Publish notes: [`docs/PUBLISH.md`](docs/PUBLISH.md).
+
+```bash
+uv run pytest
+```
+
+---
+
+## Why "Focus"?
+
+The name comes from *Horizon Zero Dawn*. Aloy navigates an inherited world with her **Focus** — an AR device that reveals weak points and danger ahead. A legacy codebase is the same kind of world. This Focus scans it so you change it with intel, not blind faith.
+
+*Horizon Zero Dawn and Aloy belong to Guerrilla Games — no affiliation, just admiration.*
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph scan [Focus Scan]
+        TS[AST Index] --> G[Dependency Graph]
+        G --> SURF[Surface Detector]
+    end
+
+    subgraph preflight [Blast Radius Engine]
+        DIFF[Git Diff / Symbol Target] --> SEED[Changed Symbols]
+        SEED --> BFS[Reverse BFS]
+        BFS --> DZ[Danger Zone Scorer]
+    end
+
+    subgraph hud [Focus HUD]
+        ES[Executive Summary]
+        MAP[Mermaid Map]
+        BR[Blast Radius Report]
+    end
+
+    scan --> preflight
+    preflight --> hud
+    hud --> OUT[CLI stdout / GitHub PR comment]
+```
+
+| Layer | Technology |
+|---|---|
+| CLI | Python 3.12+ / Typer |
+| AST | Python `ast` + Tree-sitter (JS/TS) |
+| Graph | NetworkX |
+| Diagrams | Mermaid (native on GitHub) |
+| CI | Opt-in GitHub Action |
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `focus scan [path]` | Index the repo (Python + JS/TS) |
+| `focus trace [file]` | HUD for one file |
+| `focus audit --local` | Working tree vs `main` |
+| `focus audit --base <sha>` | PR / branch range |
+| `focus version` | Installed version |
+
+---
+
+## Roadmap
+
+Phase 3 **complete** (CLI + Action + JS/TS + cache). IDE extension and LLM labels are parked — see [`docs/ROADMAP.md`](docs/ROADMAP.md).
+
+---
+
+## Ethics & privacy
+
+- **Evidence-based** — no LLM inventing edges
+- **Privacy-by-design** — respects `.gitignore`; no source to model APIs
+- **No surveillance** — structure, not developer identity
+- **Opt-in Action** — minimum token scope
+
+| Doc | Contents |
+|---|---|
+| [`docs/DEMO.md`](docs/DEMO.md) | Walkthrough + gallery |
+| [`docs/LAUNCH.md`](docs/LAUNCH.md) | Product Hunt / Show HN drafts |
+| [`docs/ACTION.md`](docs/ACTION.md) | Action install |
+| [`docs/HUD.md`](docs/HUD.md) | HUD schema |
+| [`docs/ETHICS.md`](docs/ETHICS.md) | Responsible use |
+| [`docs/PRIVACY.md`](docs/PRIVACY.md) | Data boundaries |
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Joviane Bellegarde.
+
+## Author
+
+[Joviane Bellegarde](https://github.com/j0viane). Feedback welcome via Issues.

focus_hud-0.1.0/README.md

@@ -0,0 +1,174 @@
+# Focus
+
+**Blast radius you can defend — evidence-only, before you merge.**
+
+Focus answers one question: **what else in this codebase could break because of this change?**
+
+It's an **AR HUD for codebases**: a computed import graph (Python + JS/TS) → Mermaid map + Danger Zones. Same HUD in the CLI and on the PR. No LLM inventing edges.
+
+> **Not** another AI PR summary. **Not** a hop inventory that cries wolf on every file. Focus stays quiet when the change is boring, and loud when you touch a shared hub.
+
+---
+
+## Try in 60 seconds
+
+```bash
+pip install "focus-hud @ git+https://github.com/j0viane/focus.git"
+# after PyPI publish:  pip install focus-hud
+
+focus trace path/to/shared_module.py --out focus-hud.md
+# open focus-hud.md → Markdown preview for Mermaid
+
+focus audit --local --out focus-hud.md   # working tree vs main — before you push
+```
+
+**Demo fixture (no app required):**
+
+```bash
+git clone https://github.com/j0viane/focus.git && cd focus
+uv sync
+uv run focus trace tests/fixtures/glass_box/auth_utils.py \
+  --root tests/fixtures/glass_box --out focus-hud.md
+```
+
+Gallery + walkthrough: [`docs/DEMO.md`](docs/DEMO.md) · [`docs/assets/`](docs/assets/)
+
+---
+
+## Why this exists
+
+There's a new kind of pressure on developers — and it lands hardest on juniors: walk into a codebase you've never seen, point an AI at it, and ship. The code arrives in seconds. The understanding doesn't.
+
+Focus is for the moment right before you push into a codebase that was there long before you. **What the system looks like, and what your change will actually touch** — with evidence you can defend in review.
+
+| Moment | Command | You get |
+|---|---|---|
+| AI rewrote a shared function | `focus audit --local` | Blast radius of your working tree vs `main` |
+| Big PR in your queue | Focus Action comment | Skim-or-dig: diagram + Danger Zones, or “low impact” |
+| Inherited a module | `focus trace path/to/file.py` | Everything that depends on it |
+
+---
+
+## GitHub Action (any repo)
+
+Copy [`examples/focus-action.yml`](examples/focus-action.yml) → `.github/workflows/focus.yml`.  
+Details: [`docs/ACTION.md`](docs/ACTION.md). Permissions: `contents: read` + `pull-requests: write` only ([`docs/PRIVACY.md`](docs/PRIVACY.md)).
+
+---
+
+## Already exists? (CodeLayers, Valerian, …)
+
+Editor tools show hop lists while you type. Focus is **pre-merge decision support**: evidence-only topology, Danger Zones + smart triggers, **one HUD** from `audit --local` to the PR comment. Open source, local, no architecture backend required.
+
+---
+
+## Getting started (from this repo)
+
+```bash
+git clone https://github.com/j0viane/focus.git
+cd focus
+uv sync
+uv run focus scan .
+uv run focus trace src/focus/models.py --out focus-hud.md
+uv run focus audit --local
+```
+
+Unchanged files reuse **`.focus-cache/`** (gitignored). Pass `--no-cache` to force a full re-parse.
+
+Optional: copy [`.focus.toml.example`](.focus.toml.example) → `.focus.toml` to tune `fan_out_threshold` (default **3**).
+
+Requirements: Python 3.12+. Package name on PyPI: **`focus-hud`** (CLI: `focus`). Publish notes: [`docs/PUBLISH.md`](docs/PUBLISH.md).
+
+```bash
+uv run pytest
+```
+
+---
+
+## Why "Focus"?
+
+The name comes from *Horizon Zero Dawn*. Aloy navigates an inherited world with her **Focus** — an AR device that reveals weak points and danger ahead. A legacy codebase is the same kind of world. This Focus scans it so you change it with intel, not blind faith.
+
+*Horizon Zero Dawn and Aloy belong to Guerrilla Games — no affiliation, just admiration.*
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph scan [Focus Scan]
+        TS[AST Index] --> G[Dependency Graph]
+        G --> SURF[Surface Detector]
+    end
+
+    subgraph preflight [Blast Radius Engine]
+        DIFF[Git Diff / Symbol Target] --> SEED[Changed Symbols]
+        SEED --> BFS[Reverse BFS]
+        BFS --> DZ[Danger Zone Scorer]
+    end
+
+    subgraph hud [Focus HUD]
+        ES[Executive Summary]
+        MAP[Mermaid Map]
+        BR[Blast Radius Report]
+    end
+
+    scan --> preflight
+    preflight --> hud
+    hud --> OUT[CLI stdout / GitHub PR comment]
+```
+
+| Layer | Technology |
+|---|---|
+| CLI | Python 3.12+ / Typer |
+| AST | Python `ast` + Tree-sitter (JS/TS) |
+| Graph | NetworkX |
+| Diagrams | Mermaid (native on GitHub) |
+| CI | Opt-in GitHub Action |
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `focus scan [path]` | Index the repo (Python + JS/TS) |
+| `focus trace [file]` | HUD for one file |
+| `focus audit --local` | Working tree vs `main` |
+| `focus audit --base <sha>` | PR / branch range |
+| `focus version` | Installed version |
+
+---
+
+## Roadmap
+
+Phase 3 **complete** (CLI + Action + JS/TS + cache). IDE extension and LLM labels are parked — see [`docs/ROADMAP.md`](docs/ROADMAP.md).
+
+---
+
+## Ethics & privacy
+
+- **Evidence-based** — no LLM inventing edges
+- **Privacy-by-design** — respects `.gitignore`; no source to model APIs
+- **No surveillance** — structure, not developer identity
+- **Opt-in Action** — minimum token scope
+
+| Doc | Contents |
+|---|---|
+| [`docs/DEMO.md`](docs/DEMO.md) | Walkthrough + gallery |
+| [`docs/LAUNCH.md`](docs/LAUNCH.md) | Product Hunt / Show HN drafts |
+| [`docs/ACTION.md`](docs/ACTION.md) | Action install |
+| [`docs/HUD.md`](docs/HUD.md) | HUD schema |
+| [`docs/ETHICS.md`](docs/ETHICS.md) | Responsible use |
+| [`docs/PRIVACY.md`](docs/PRIVACY.md) | Data boundaries |
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Joviane Bellegarde.
+
+## Author
+
+[Joviane Bellegarde](https://github.com/j0viane). Feedback welcome via Issues.