nnlens 0.1.0__tar.gz

nnlens-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Normalize line endings; keep them LF in the repo.
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.ico binary

nnlens-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e ".[dev]" numpy
+      - name: Test
+        run: python -m pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nnlens-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# nnlens local render store
+.nnlens/
+*.rendered.html
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# tests
+.pytest_cache/
+.coverage
+tests/js/node_modules/
+tests/js/package-lock.json

nnlens-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to nnlens
+
+## Dev setup
+
+```bash
+py -3.12 -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]" numpy
+.venv/Scripts/python -m pytest
+```
+
+`numpy` isn't a runtime dependency of nnlens itself — it's only needed to run
+the bundled example's naive view (view 4).
+
+The renderer JS (`viewer.js`) has its own headless test suite (Node + jsdom),
+which covers the security-critical transforms (HTML escaping, math handling,
+`{{term}}` wiring, link/image policy):
+
+```bash
+cd tests/js
+npm install
+npm test        # node --test
+```
+
+## Layout
+
+```
+src/nnlens/
+  server.py        # MCP server: tools + the `explain` prompt
+  models.py        # the Explanation schema (pydantic)
+  sources.py       # arXiv + GitHub retrieval (stdlib only)
+  sandbox.py       # run_python (subprocess + timeout)
+  prompts.py       # the `explain` methodology prompt
+  renderer/
+    build.py       # explanation dict -> self-contained HTML
+    server.py      # background localhost static server
+    template.html  # the viewer (markdown-it + mermaid + katex + hover terms)
+examples/          # golden explanation fixtures
+scripts/           # build_example.py, demo_render.py
+tests/
+```
+
+## Adding an example
+
+Explanations are generated on demand by your host — they are **not** committed as a
+content library (that keeps view 5 free of any repo-redistribution concerns). The
+one checked-in example exists as a schema fixture and a format reference.
+
+If you improve the format, regenerate the fixture:
+
+```bash
+python scripts/build_example.py
+```
+
+It runs the naive code through the sandbox, so `run_ok` / `run_stdout` stay real.
+
+## Changing the schema
+
+Edit `models.py`, then update `prompts.py` (the JSON shape shown to the host) and
+`examples/transformer_attention.json` together — `tests/test_models.py` validates
+the fixture against the schema and will fail if they drift.
+
+## Changing the renderer
+
+`template.html` is plain HTML/JS with CDN libs; open the output of
+`python scripts/demo_render.py --once` in a browser to iterate. Keep the
+`{{plain-word}}` → hover-tooltip wiring working (`tests/test_renderer.py` checks
+the data is embedded and the token replaced).
+
+## Before you push
+
+- `python -m pytest` is green.
+- If you touched the renderer JS, `cd tests/js && npm test` is green.
+- If you touched anything with logic, run a Codex review over the diff.

nnlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nnlens 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
+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.

nnlens-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: nnlens
+Version: 0.1.0
+Summary: Explain neural-network architectures layer by layer in five linked views (structure, plain words, math, naive code, optimized code). An MCP server + local renderer driven by your own LLM subscription.
+Project-URL: Homepage, https://github.com/tsuzakiii/nnlens
+Project-URL: Repository, https://github.com/tsuzakiii/nnlens
+Project-URL: Issues, https://github.com/tsuzakiii/nnlens/issues
+Author: nnlens contributors
+License: MIT
+License-File: LICENSE
+Keywords: education,explainer,mcp,neural-networks,pytorch
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nnlens
+
+**Throw in a paper, a GitHub repo, or just the name of a technique — get back a
+layer-by-layer explanation of a neural network, in five linked views.**
+
+![nnlens rendering a Transformer block: multi-component sidebar, related-explanation chips, concept ledger, and the structure diagram](docs/img/screenshot.png)
+
+nnlens is an **MCP server + local renderer**. You connect it to an MCP host you
+already use (Claude Desktop, Claude Code, Cursor, …). The host's model — driven by
+**your own subscription** — does the explaining; nnlens gives it the methodology,
+fetches the real sources, runs the code, and renders the result to a local web page.
+
+> nnlens **never calls an LLM itself and never handles an API key.** The
+> reasoning happens in your MCP host, on your existing plan. That is the whole
+> point: no metered API, no shared credentials, no hosted service borrowing your
+> subscription.
+
+## The five views
+
+Every component (a layer, block, or technique) is explained five ways, and the
+views are **linked** by a shared *concept ledger* so the same idea keeps the same
+everyday word, symbol, and formal name across all of them:
+
+1. **構造** — a Mermaid diagram of the data flow, plus a short note.
+2. **言葉での説明** — plain language only. No symbols, no jargon.
+3. **数式** — the real notation, carrying over the everyday words from view 2 and
+   attaching each to its symbol (hover any highlighted word to see the mapping).
+4. **素の実装** — a from-scratch implementation that is *literally the math*
+   (pure Python / numpy, no torch), **actually executed** so the output is real.
+5. **最適化された実装** — the fast version, excerpted from the official repository
+   (with a source link) or written from scratch when none exists — numerically
+   cross-checked against the naive view when it's locally runnable.
+
+Beyond a single page:
+
+- **Library** — every explanation you generate is saved locally
+  (`~/.nnlens/store`) and listed in the sidebar; delete with the hover ✕.
+- **Cross-links** — explanations reference each other (`related` chips and
+  `[[slug]]` wikilinks in the prose). Links to explanations you haven't generated
+  yet show up greyed out — a built-in "what to explain next" list.
+- **Contract lint** — `render` returns warnings when the views drift apart
+  (a ledger term never marked, symbols leaking into the plain-words view, an
+  uncited optimized view, an unverified naive run), so the host fixes them.
+- **Self-healing pages** — pages are stamped with a template hash and rebuilt
+  automatically when nnlens updates its renderer.
+
+## Install
+
+```bash
+pip install nnlens        # or: pipx install nnlens
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/tsuzakiii/nnlens
+cd nnlens
+pip install -e .
+```
+
+## Connect it to your MCP host
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nnlens": { "command": "nnlens" }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add nnlens -- nnlens
+```
+
+(If the `nnlens` script isn't on your PATH, use
+`"command": "python", "args": ["-m", "nnlens"]` instead.)
+
+## Use it
+
+In your host, invoke the `explain` prompt (e.g. type `/nnlens` / `/explain`) or
+just ask:
+
+> nnlens で Scaled Dot-Product Attention を説明して
+
+The host will fetch the paper/repo, write the five views, run the naive code to
+verify it, and hand you a URL like `http://127.0.0.1:8787/e/…` — open it for the
+rendered page with diagrams, math, and hover-linked terms.
+
+## Try the renderer without a host
+
+```bash
+python scripts/build_example.py     # (re)build the bundled example, runs its code
+python scripts/demo_render.py --open
+```
+
+## How it fits together
+
+```
+MCP host (your subscription) ── drives ──► nnlens tools
+        │                                    ├─ fetch_paper / find_official_repo / fetch_repo_code
+        │  writes the 5 views                ├─ run_python   (proves view 4 runs)
+        └───────────────────────────────────► render        (→ local web page URL)
+```
+
+- **Tools** = the deterministic work (retrieval, code execution, rendering).
+- **`explain` prompt** = the methodology the host follows to assemble the views.
+
+## Limitations (read before trusting it)
+
+- **Correctness is not guaranteed.** The prose and math are written by the host
+  model. Diagrams are model-generated and are the weakest link — treat view 1 as a
+  sketch. View 4 is executed, so its output is real; the rest is best-effort.
+- **`run_python` is not a hardened sandbox.** It runs code your host produced, on
+  your machine, with a timeout — not untrusted third-party code. Don't point it at
+  untrusted input.
+- **View 5 excerpts** are fetched from public repos at view time and shown with
+  attribution; nothing is redistributed. Respect each source repo's license.
+- The renderer loads Markdown/Mermaid/KaTeX from a CDN, so viewing needs internet.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nnlens-0.1.0/PROGRESS.md

@@ -0,0 +1,109 @@
+# nnlens — progress / task board
+
+## Done (2026-07-03) — PUBLISHED on GitHub
+- [x] Public repo: https://github.com/tsuzakiii/nnlens (topics: mcp, neural-networks, education, explainer, claude).
+- [x] All 21 commits rewritten to `tsuzakiii <236340194+tsuzakiii@users.noreply.github.com>` before push (old name/email fully purged from history, backup refs expired; verified 0 traces).
+- [x] Hero screenshot (Transformer block page) + [project.urls] in pyproject.
+- [x] dist built + `twine check` PASSED. **PyPI upload pending: needs the user's PyPI account + API token** (`~/.pypirc` or `twine upload -u __token__ -p pypi-...`); everything else is ready.
+
+## Done (2026-07-03) — renamed layerlens → (layerlore) → nnlens
+- [x] "layerlens" was taken (PyPI 200; a "LayerLens" GitHub org with a 276★ repo). Interim pick "layerlore" was applied and working, then the user weighed in; final name **nnlens** — verified completely clean (PyPI 404, GitHub 0 repos, the cleanest of all candidates).
+- [x] Renamed package / console script / MCP server name / env vars (NNLENS_STORE, NNLENS_PORT) / branding; repo folder moved to C:\ClaudeCode\nnlens; fresh venv.
+- [x] Store auto-migration on first use: `~/.layerlore/store` or `~/.layerlens/store` → `~/.nnlens/store` (all 4 explanations carried over). Old pages auto-rebuilt under the new branding by the template-hash rebuilder.
+- [x] Re-registered in Claude Code (user scope) and Claude Desktop config (backups kept). Desktop needs a restart to pick it up.
+
+Working name: **nnlens** (final). Goal: MCP server + local renderer that
+explains NN components in five linked views, driven by the user's own LLM
+subscription (host does inference; server = tools + methodology + renderer).
+
+## Decisions locked
+- Form factor: **MCP server + local renderer** (not a hosted site, not CLI-shellout).
+- Host = the user's subscription (Claude Desktop / Claude Code / Cursor). Server never calls an LLM.
+- On-demand generation only; **no committed content library** (keeps view 5 free of repo-redistribution/license issues).
+- Backend not auto-detected — it's simply whichever MCP host the user configures.
+- Renderer: Markdown (markdown-it) + Mermaid + KaTeX + `{{term}}` hover tooltips.
+
+## Done (MVP v0.1)
+- [x] Project scaffold (pyproject, MIT, gitignore, README, CONTRIBUTING).
+- [x] Schema (`models.py`): Explanation → Component → 5 views + concept ledger.
+- [x] MCP server (`server.py`): tools `fetch_paper`, `find_official_repo`, `fetch_repo_code`, `run_python`, `render`, `explanation_schema`; `explain` prompt.
+- [x] Retrieval (`sources.py`, stdlib only), sandbox (`sandbox.py`).
+- [x] Renderer (`template.html`, `build.py`, background static `server.py`).
+- [x] Golden example (Transformer/attention) built by `scripts/build_example.py` (runs naive code).
+- [x] Tests: models, sandbox, renderer, sources(net-guarded).
+
+## Done (this session, cont.)
+- [x] venv + install, build example, pytest green (12 Python + 5 JS).
+- [x] Codex review #1 → 11 findings, ALL fixed:
+  - Renderer XSS (html:false + texmath math + DOM-walk term wiring + safeHref scheme allowlist).
+  - Extracted renderer JS to `viewer.js`; headless-tested via Node+jsdom (`tests/js/viewer.test.cjs`).
+  - sandbox: UTF-8 decode, bounded drain threads, process-tree kill on timeout (+regression tests).
+  - sources: arXiv via ElementTree (+no_results, old-style ids), capped/quoted repo fetch.
+  - static server restricted to `/e/<slug>.html`, no dir listing.
+  - prompt `kind` example fixed to a valid literal.
+- [x] git init (25 files staged; not yet committed).
+- [~] Browser visual check: BLOCKED — browser-scenario profile locked by another process. Renderer verified headlessly instead.
+
+## Done (this session, cont. 2)
+- [x] Codex re-review #2: main XSS rewrite / wrapTerms / traversal / sandbox / build escaping all confirmed sound. 3 minor findings, ALL fixed:
+  - slug() now ASCII-only (+hash fallback) so Unicode ids don't 404 on the render server.
+  - markdown links restricted to http(s)+anchors; images disabled (no external auto-load).
+  - arXiv id extraction strips trailing slash.
+- [x] Caught+fixed independently: markdown-it-texmath sets no browser global → createMd probes the bare `texmath` identifier (else math would render as raw `$...$` in a real browser).
+- [x] Regression tests added (link/image policy, unicode slug, arxiv id variants). Python 14 + JS 6 all green.
+
+## Done (this session, cont. 3)
+- [x] Runtime integration tests: render() serves over HTTP (200+content), static server 404s outside /e/<slug>.html, invalid explanation -> validation error. (16 Python tests)
+- [x] renderComponent assembly test via jsdom (5 views, ledger, badges, term wiring, safe link). (8 JS tests)
+- [x] Built wheel; verified template.html + viewer.js are packaged; fresh-install smoke test renders + MCP imports. `pip install` claim holds.
+- [x] 3 local commits (no push).
+
+## Done (2026-07-03, cont.) — real-host E2E passed (multi-component)
+- [x] Headless `claude -p` (a REAL host on the user's subscription), given only the explain prompt + the nnlens MCP tools, autonomously produced "Transformer Block (Pre-Norm)": kind=architecture with 4 components (block wiring / LayerNorm / MHA / FFN), all 4 naive views actually executed (run_ok true; row-sums/causal-mask/identity checks), optimized views excerpted from karpathy/nanoGPT, related+wikilinks to all 3 existing explanations, torch equivalence honestly skipped (no torch), **final render warnings: []**. Library now 5 entries; page visually verified.
+- [x] This validates the design bets: list_library-before-linking, run_python-not-fabricate, lint-as-quality-gate, and the multi-component schema — all under a host I didn't steer.
+
+## Needs the user / external (can't do autonomously)
+- [ ] Browser *visual* of mermaid/katex: browser-scenario profile stayed locked all session. Logic verified headlessly; retry when it frees.
+- [ ] End-to-end host-driven run: needs the user's own MCP host (Claude Desktop / Claude Code) — add nnlens, run /explain, confirm the round-trip.
+- [ ] Naming + PyPI availability before publishing ("nnlens" is a working name).
+- [ ] Open design Q: Codex-as-MCP-client support for ChatGPT-sub users (Claude hosts are solid).
+
+## Done (this session, cont. 4) — real-usage feedback + visual polish
+- [x] **Bug (from real use): `run_python` hung on trivial `print(2+2)` over MCP stdio.** Root-caused empirically (not `sys.executable` — the child inherited the parent's MCP-pipe stdin and deadlocked on Windows). Fix: spawn snippets with `stdin=DEVNULL`. Added an **E2E regression test** (`tests/test_mcp_stdio.py`) that launches the server over real stdio (normal pytest can't reproduce it). Also added a defensive `_python_interpreter()` resolver.
+- [x] **`fetch_paper` now surfaces `repos`** (github URLs from the abstract/links) so view 5 survives find_official_repo name collisions (e.g. PRISM → gpr-prism/prism).
+- [x] **Renderer full-width**: dropped `main { max-width: 900px }` → content uses the whole window (was wasting ~40% on wide screens). Verified visually via Playwright (before/after screenshots): Mermaid, KaTeX, syntax highlight, term hover, run badge, source link all render correctly.
+- [x] Feature scoping: in-page "Claude toolbox" (select-to-explain / revise) researched (workflow) — MCP sampling unsupported by Desktop/Code today; only viable via a separate warm-`claude`-CLI daemon. User declined the feature for now.
+
+## Done (2026-07-02) — cross-links between explanations
+- [x] Design doc `docs/DESIGN_related_links.md`; implemented by a Sonnet-5(high) subagent, reviewed + hardened here.
+- [x] `Explanation.related` (RelatedRef: slug/label/relation×4) + `[[slug|text]]` wikilinks in prose; header chips; two-stage pending→link/missing upgrade against the library index (missing = 「まだ生成されていません」= what to generate next).
+- [x] New MCP tool `list_library` so the host knows existing slugs before linking; prompt updated.
+- [x] Codex review #4 (4 findings, all fixed): prototype-pollution-safe slug map (Object.create(null)+hasOwnProperty), upgradeLinks reconciles in BOTH directions (deleted target downgrades a live link), slug allowlist unified with the server URL regex across RelatedRef/isSafeSlug/_clean_entry, list_library never raises. No XSS path found.
+- [x] Verified in-browser: attention↔layer-norm mutual chips click through both ways.
+
+## Done (2026-07-02, cont.) — template updates now reach old pages
+- [x] Pages are stamped with a template hash (`<meta name="nnlens-template">`; sha1 of template.html+viewer.js).
+- [x] `rebuild_store`: pages whose stamp differs (or is missing = legacy) are re-rendered losslessly from their embedded Explanation JSON; unparseable pages skipped untouched. Runs automatically at `ensure_server` startup.
+- [x] Proven on the real store: the PRISM page (stuck on the old max-width:900px CSS) auto-upgraded to the current layout + wikilink viewer on server restart.
+- [x] `write_explanation` atomic (temp+os.replace). Codex review #5 (2 findings, fixed): renders win over rebuilds via mtime guard (`_replace_if_unchanged`), fixed short temp prefix (Windows path limits), per-page failure isolation, rebuild/reconcile guarded separately at startup.
+
+## Done (2026-07-02, cont. 2) — render() lints the cross-view contract
+- [x] New `lint.py`: render() returns non-blocking `warnings` — ledger terms actually marked in prose, marks resolve to a ledger entry, words view symbol-free ($/non-ASCII symbols; single ASCII letters skipped), math view has notation, optimized view cites a source or declares self-impl, naive run verified (run_ok).
+- [x] Codex review #6 (3 findings, all fixed): lint now mirrors the RENDERER — code/math regions stripped before analysis (`` `{{x}}` `` doesn't count as wired; `` `$PATH` `` doesn't flag), and mark resolution is global across components (matches viewer.js's merged ledgerMap).
+- [x] Prompt: host is told to fix warnings and re-render. Dogfood test: bundled fixtures are lint-clean.
+
+## Verified state
+- Tests: 59 Python + 16 Node/jsdom, all green. Codex reviewed 6 times (23 findings, all fixed). Wheel installs and renders. Rendered page + cross-links visually verified in-browser; legacy-page auto-rebuild verified on the real store.
+
+## Known limitations (documented, not blockers)
+- Browser visual of mermaid/katex not yet eyeballed (profile locked all session); graceful fallback implemented.
+- `run_python` is a timeout+tree-kill subprocess, not a hardened sandbox (documented in README).
+- Renderer needs internet for CDN libs at view time.
+
+## Backlog / open questions
+- [ ] Verify the `explain` flow against a real MCP host end-to-end (needs Claude Desktop/Code).
+- [ ] Codex-as-MCP-client support? (affects ChatGPT-sub users; Claude hosts are solid.)
+- [ ] Architecture decomposition example (full Transformer block → attention/FFN/norm/residual).
+- [ ] Optional: offline/vendored CDN assets for the renderer.
+- [ ] Optional: `run_python` hardening (no-network mode).
+- [x] **Naming: RENAMED to `nnlens`** (2026-07-03, user delegated the pick). The original name "layerlens" was taken (PyPI 200; a "LayerLens" GitHub org with a 276★ repo). `nnlens` verified free on PyPI (404) and GitHub (0 repos) at rename time. Other free candidates at the time: layerscope, nnlens, explayn, fivelens.

nnlens-0.1.0/README.md

@@ -0,0 +1,126 @@
+# nnlens
+
+**Throw in a paper, a GitHub repo, or just the name of a technique — get back a
+layer-by-layer explanation of a neural network, in five linked views.**
+
+![nnlens rendering a Transformer block: multi-component sidebar, related-explanation chips, concept ledger, and the structure diagram](docs/img/screenshot.png)
+
+nnlens is an **MCP server + local renderer**. You connect it to an MCP host you
+already use (Claude Desktop, Claude Code, Cursor, …). The host's model — driven by
+**your own subscription** — does the explaining; nnlens gives it the methodology,
+fetches the real sources, runs the code, and renders the result to a local web page.
+
+> nnlens **never calls an LLM itself and never handles an API key.** The
+> reasoning happens in your MCP host, on your existing plan. That is the whole
+> point: no metered API, no shared credentials, no hosted service borrowing your
+> subscription.
+
+## The five views
+
+Every component (a layer, block, or technique) is explained five ways, and the
+views are **linked** by a shared *concept ledger* so the same idea keeps the same
+everyday word, symbol, and formal name across all of them:
+
+1. **構造** — a Mermaid diagram of the data flow, plus a short note.
+2. **言葉での説明** — plain language only. No symbols, no jargon.
+3. **数式** — the real notation, carrying over the everyday words from view 2 and
+   attaching each to its symbol (hover any highlighted word to see the mapping).
+4. **素の実装** — a from-scratch implementation that is *literally the math*
+   (pure Python / numpy, no torch), **actually executed** so the output is real.
+5. **最適化された実装** — the fast version, excerpted from the official repository
+   (with a source link) or written from scratch when none exists — numerically
+   cross-checked against the naive view when it's locally runnable.
+
+Beyond a single page:
+
+- **Library** — every explanation you generate is saved locally
+  (`~/.nnlens/store`) and listed in the sidebar; delete with the hover ✕.
+- **Cross-links** — explanations reference each other (`related` chips and
+  `[[slug]]` wikilinks in the prose). Links to explanations you haven't generated
+  yet show up greyed out — a built-in "what to explain next" list.
+- **Contract lint** — `render` returns warnings when the views drift apart
+  (a ledger term never marked, symbols leaking into the plain-words view, an
+  uncited optimized view, an unverified naive run), so the host fixes them.
+- **Self-healing pages** — pages are stamped with a template hash and rebuilt
+  automatically when nnlens updates its renderer.
+
+## Install
+
+```bash
+pip install nnlens        # or: pipx install nnlens
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/tsuzakiii/nnlens
+cd nnlens
+pip install -e .
+```
+
+## Connect it to your MCP host
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nnlens": { "command": "nnlens" }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add nnlens -- nnlens
+```
+
+(If the `nnlens` script isn't on your PATH, use
+`"command": "python", "args": ["-m", "nnlens"]` instead.)
+
+## Use it
+
+In your host, invoke the `explain` prompt (e.g. type `/nnlens` / `/explain`) or
+just ask:
+
+> nnlens で Scaled Dot-Product Attention を説明して
+
+The host will fetch the paper/repo, write the five views, run the naive code to
+verify it, and hand you a URL like `http://127.0.0.1:8787/e/…` — open it for the
+rendered page with diagrams, math, and hover-linked terms.
+
+## Try the renderer without a host
+
+```bash
+python scripts/build_example.py     # (re)build the bundled example, runs its code
+python scripts/demo_render.py --open
+```
+
+## How it fits together
+
+```
+MCP host (your subscription) ── drives ──► nnlens tools
+        │                                    ├─ fetch_paper / find_official_repo / fetch_repo_code
+        │  writes the 5 views                ├─ run_python   (proves view 4 runs)
+        └───────────────────────────────────► render        (→ local web page URL)
+```
+
+- **Tools** = the deterministic work (retrieval, code execution, rendering).
+- **`explain` prompt** = the methodology the host follows to assemble the views.
+
+## Limitations (read before trusting it)
+
+- **Correctness is not guaranteed.** The prose and math are written by the host
+  model. Diagrams are model-generated and are the weakest link — treat view 1 as a
+  sketch. View 4 is executed, so its output is real; the rest is best-effort.
+- **`run_python` is not a hardened sandbox.** It runs code your host produced, on
+  your machine, with a timeout — not untrusted third-party code. Don't point it at
+  untrusted input.
+- **View 5 excerpts** are fetched from public repos at view time and shown with
+  attribution; nothing is redistributed. Respect each source repo's license.
+- The renderer loads Markdown/Mermaid/KaTeX from a CDN, so viewing needs internet.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nnlens-0.1.0/docs/DESIGN_related_links.md

@@ -0,0 +1,102 @@
+# 設計書: 解説間リンク（related / wikilink）
+
+日付: 2026-07-02 / 対象: nnlens v0.1 / 状態: 実装待ち
+
+## 目的
+
+ライブラリが現状フラットで、解説同士の関係（「Transformer block は attention と LayerNorm を含む」「PRISM は TTT の並列化」）を表現できない。
+解説に **related フィールド**と**本文中の wikilink** を導入し、解説間を相互リンクして知識グラフとして育つようにする。
+
+## 変更一覧（この5点で完結。スコープ外のことはしない）
+
+### 1. スキーマ (`src/nnlens/models.py`)
+
+`Explanation` に追加:
+
+```python
+class RelatedRef(BaseModel):
+    slug: str = Field(..., description="Slug of the related explanation, e.g. 'layer-normalization'.")
+    label: str = Field("", description="Display label; defaults to the slug at render time.")
+    relation: Literal["contains", "part-of", "builds-on", "related"] = "related"
+
+class Explanation(BaseModel):
+    ...
+    related: list[RelatedRef] = Field(default_factory=list)
+```
+
+- `slug` は `Explanation.slug()` と同じ safe 形式を期待するが、**バリデーションで弾かない**（正規化は不要、レンダラー側で存在チェックするため）。ただし `/` `\` `..` を含むものは pydantic validator で reject する（リンク先パスに使うため）。
+- 既存 JSON（related 無し）は default `[]` で後方互換。
+
+### 2. MCP ツール追加 (`src/nnlens/server.py`)
+
+```python
+@mcp.tool()
+def list_library() -> dict:
+    """Return every explanation in the local library ({slug, title, kind} each)."""
+    return {"explanations": reconcile_index(config.store_dir())}
+```
+
+- ホストが**既存の解説の slug を知ってから** related / wikilink を張れるようにするのが目的。
+- `reconcile_index` は `nnlens.renderer` から import（既存関数、ディスク走査つき）。
+
+### 3. プロンプト (`src/nnlens/prompts.py`)
+
+`EXPLAIN_PROMPT` に追記（How to work セクションと JSON shape の両方）:
+
+- 手順に: 「最初に `list_library` を呼び、既存の解説一覧を確認する。関連する解説があれば `related` に張る。本文（words / math / summary / note）中で他の解説に言及するときは `[[slug]]` または `[[slug|表示テキスト]]` と書く（存在する slug のみ）。」
+- JSON shape 例に `"related": [{ "slug": "…", "label": "…", "relation": "contains | part-of | builds-on | related" }]` を追加。
+- 注意: このファイルは `.format(topic=...)` を使うので **literal な `{` `}` は `{{` `}}` にエスケープ**する（既存コード参照）。
+
+### 4. レンダラー (`src/nnlens/renderer/viewer.js` + `template.html` の CSS)
+
+#### 4a. 関連チップ（ヘッダー直下）
+
+- `DATA.related` が非空なら、header 内（`.src` の後）に `div.related-row` を描画。
+- 各エントリはチップ: `relation` の日本語ラベル + リンク。
+  - `contains` →「含む」/ `part-of` →「一部」/ `builds-on` →「基づく」/ `related` →「関連」
+- 表示テキストは `label || slug`（ライブラリ index にあれば index の title を優先して良い）。
+
+#### 4b. wikilink（本文中の `[[slug]]` / `[[slug|text]]`）
+
+- `wrapTerms` と同じ **DOM text-node walk** 方式で実装（`innerHTML` への文字列注入は禁止。code/pre/katex/mermaid/term/既存リンク内はスキップ — wrapTerms の skip 規則を流用しつつ `A` タグ内もスキップに追加）。
+- 正規表現: `/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g`。slug 部に `/` `\` `..` を含むものはリンク化せずプレーンテキストのまま。
+
+#### 4c. 存在チェックと2段階アップグレード
+
+- チップ / wikilink は最初 `<span class="wikilink pending" data-slug data-label>` として描画（この時点ではリンクでない）。
+- 既存の `refreshLibrary` が index を fetch した後に `upgradeLinks(doc, indexEntries)` を呼び:
+  - slug が index に**ある** → `<a href="./<encodeURIComponent(slug)>.html">` に置換（class `wikilink`）。
+  - **ない** → class を `wikilink missing` にし `title="まだ生成されていません"`（グレー表示のまま）。これは「次に生成すべきもの」の可視化を兼ねる。
+- `file://`（index が取れない）ではアップグレードが走らず pending 表示のまま = 安全に劣化。
+
+#### 4d. CSS（template.html）
+
+- `.related-row`（flex, gap, 小さめ）と `.chip`（角丸・枠線・relation ラベルは muted）。
+- `.wikilink`（accent 色 + 下線なし hover 下線）、`.wikilink.missing` / `.wikilink.pending`（muted、cursor:default）。
+
+### 5. 例・テスト
+
+- `examples/transformer_attention.json` と `examples/layer_norm.json` に相互の `related` を追加（relation は両方向 `related` で良い）。attention の words 内の LayerNorm 言及は無いので本文はいじらない（related チップのみで十分）。**ビルドスクリプト（scripts/build_example.py / build_layernorm.py）側の dict にも同じ変更を入れて再生成**すること（fixture は生成物）。
+- Python テスト (`tests/test_models.py` など):
+  - related 付き Explanation が validate を通る / 埋め込み JSON（build_html 出力）に related が現れる。
+  - `slug` に `../x` を入れると ValidationError。
+  - `list_library` ツールが登録されている（`server.mcp.list_tools()` に名前が出る — 既存の introspect パターン参照、または tests/test_integration.py 流に直接関数を呼ぶ）。
+- JS テスト (`tests/js/`):
+  - wikilink: `[[layer-normalization]]` がプロース中で span になり、`upgradeLinks` で `<a href="./layer-normalization.html">` になる。index に無い slug は `missing` になる。
+  - コードブロック内の `[[x]]` はそのまま（walk の skip）。
+  - related チップ: 描画される・XSS 安全（textContent / createElement のみ）。
+- 既存テストが全部 green のまま（23 Python + 8 JS + 追加分）。
+
+## 受け入れ条件
+
+1. `pytest`（venv: `.venv/Scripts/python.exe -m pytest -q`）と `cd tests/js && node --test` が全 green。
+2. `scripts/build_example.py` → `scripts/build_layernorm.py` を実行し直すと、attention / layer_norm のページ双方のヘッダーに相互の「関連」チップが出て、クリックで行き来できる（store: `~/.nnlens/store`、サーバー再起動が必要なら 8787 の既存プロセスを止めてから `scripts/demo_render.py` を background で）。
+3. 存在しない slug への related / wikilink はグレー表示（リンク化されない）で、ページは壊れない。
+4. XSS 安全: すべて createElement / textContent。`innerHTML` への注入を新規に増やさない。
+
+## 実装上の注意（このリポジトリの流儀）
+
+- Edit の前に必ず対象ファイルを Read する。
+- viewer.js はブラウザ + Node(jsdom) 両対応（末尾の `module.exports` に新関数 `upgradeLinks` / wikilink 処理関数を追加してテスト可能にする）。
+- `prompts.py` の `{` エスケープを壊さない（`.format()` が通ることをテストで確認: 既存の import + `EXPLAIN_PROMPT.format(topic="x")` がエラーにならない）。
+- コミットはしない（レビュー後にこちらで行う）。