docs: sync README + CONTRIBUTING + getting-started + architecture; bump to v0.9.0 (#82)

User feedback: "Readme top demo of gitlab pages should be there, plus
simple rule of contribution, all docs are out of sync review every
thing test with actual data". This PR addresses all four asks.

README.md:
- Hoist the live demo link to the VERY top of the file, above the
  badges. Presented as a big `## 👉` header so it's impossible to
  miss. Demo URL: https://pratiyush.github.io/llm-wiki/
- Explain what the demo shows (heatmap, tool charts, token usage,
  model info cards, vs-comparisons, project topics) so new visitors
  know what to expect before clicking
- Update stale badges:
  * version v0.4.0 → v0.9.0
  * tests 95 passing → 420 passing
- New one-line "Contributing in one line:" paragraph immediately
  after the install snippet, linking to CONTRIBUTING.md with the
  TL;DR rules inline

CONTRIBUTING.md:
- New "TL;DR rules of contribution" section at the top with 7
  numbered rules (one concern per PR, commit prefixes, no real
  session data, no new runtime deps, tests must pass, CHANGELOG
  entry, open issue for large work). Hits the user's "simple
  rule of contribution" ask.
- Prominent link to the live demo up top so new contributors can
  explore the product before reading the contribution rules
- Remove stale pygments references from the dev setup list
  (superseded by highlight.js + CDN in #73)
- Fix the PR title format section: the repo uses conventional
  commits (feat: / fix: / docs: / chore: / test:), not `add:`
  which was documented here. Aligned with what git log actually
  shows.

docs/getting-started.md:
- Update step 1 of the setup description to drop pygments and
  explain that highlight.js runs in the browser via CDN

docs/architecture.md:
- Update L2 Site section to describe the v0.9 page surface:
  heatmap, tool charts, token usage stats, models/, vs/,
  changelog.html, AI exports
- Drop pygments from the runtime deps list in both the L2 description
  and the Design principles section (item #1)

llmwiki/__init__.py + pyproject.toml:
- __version__ and pyproject version bumped 0.4.0 → 0.9.0 to match
  the shipped feature set (#55, #56, #58, #60, #63, #64, #65, #66,
  #72, #73, #74, #75, #76, #77, #78, #79, #80, #81 + project topics
  all merged on master between v0.4 and now)

tests/test_v04.py:
- Relax the hardcoded version assertion so every release bump
  doesn't break the v0.4 test module. New behavior: accept any
  0.x.y pre-1.0 release with minor ≥ 4 (since the tests themselves
  were introduced in v0.4)
- Replace `test_pyproject_version_matches` naive substring check
  with an equality check against `__version__` — catches the
  real bug (pyproject and package drifting apart) without being
  tied to a specific number

420 tests still passing after the docs sync + version bump.
Verified the live build shows all 6 nav links (Home / Projects /
Sessions / Models / Compare / Changelog), the llm-wiki card shows
topic chips (`python, wiki, karpathy, claude-code, +3 more`), and
`llmwiki --version` prints `llmwiki 0.9.0`.

Author: Pratiyush

CONTRIBUTING.md

@@ -2,8 +2,11 @@
 
 Thanks for wanting to contribute. This project follows strict rules about commits, PRs, and privacy — please read this before opening a PR.
 
+**Try the live demo first:** [pratiyush.github.io/llm-wiki](https://pratiyush.github.io/llm-wiki/). It's rebuilt on every `master` push from [`examples/demo-sessions/`](examples/demo-sessions) so you can see every feature working before touching code.
+
 ## Table of contents
 
+- [TL;DR rules of contribution](#tldr-rules-of-contribution)
 - [Code of conduct](#code-of-conduct)
 - [Dev setup](#dev-setup)
 - [Project structure](#project-structure)
@@ -13,6 +16,18 @@ Thanks for wanting to contribute. This project follows strict rules about commit
 - [Testing](#testing)
 - [Releases](#releases)
 
+## TL;DR rules of contribution
+
+1. **One concern per PR.** Don't mix a bug fix with a new feature.
+2. **Commit prefixes:** `feat:` / `fix:` / `docs:` / `chore:` / `test:` — e.g. `feat(v0.7): tool-calling bar chart (#65)`.
+3. **Never commit real session data.** `raw/sessions/` is gitignored. Fixtures must be synthetic or heavily redacted.
+4. **No new runtime deps.** Stdlib + `markdown` only. Viewer loads highlight.js from a CDN — no server-side parser needed.
+5. **Tests must pass.** Run `python3 -m pytest tests/ -q` before pushing. CI runs on Python 3.9 + 3.12.
+6. **Add a CHANGELOG entry** under `## [Unreleased]` for every user-visible change.
+7. **Open an issue first** for anything bigger than a one-file fix. Keeps scope aligned.
+
+That's it. If you follow those seven rules your PR is 90% of the way through review.
+
 ## Code of conduct
 
 Be kind. Respect privacy. Prefer plain English to jargon. No scope creep.
@@ -22,19 +37,18 @@ Be kind. Respect privacy. Prefer plain English to jargon. No scope creep.
 ```bash
 git clone https://github.com/Pratiyush/llm-wiki.git
 cd llm-wiki
-./setup.sh                # installs markdown + pygments, scaffolds raw/ wiki/ site/
+./setup.sh                # installs markdown, scaffolds raw/ wiki/ site/
 python3 -m pytest tests/ -q
 ```
 
 Requirements:
 
 - Python ≥ 3.9
-- `markdown` (required)
-- `pygments` (optional — syntax highlighting)
+- `markdown` (required — the only runtime dep)
 - `ruff` (dev — lint)
 - `pytest` (dev — tests)
 
-No other runtime deps. That's a hard rule.
+No other runtime deps. That's a hard rule. Syntax highlighting runs in the browser via [highlight.js](https://highlightjs.org/) loaded from a CDN, so the build pipeline stays stdlib-only.
 
 ## Project structure
 
@@ -73,11 +87,17 @@ Adapted from the parent [Open Source Project Framework](docs/framework.md):
 
 ### PR title format
 
-- `add: <feature>` — new functionality
-- `fix: <what>` — bug fix
+Use conventional-commit-style prefixes (matches what's in `git log` on
+this repo):
+
+- `feat: <feature>` or `feat(v0.X): <feature>` — new functionality
+- `fix: <what>` or `fix(v0.X): <what>` — bug fix
 - `docs: <what>` — docs only
-- `chore: <what>` — refactor, dep bump, CI
-- `test: <what>` — tests only
+- `chore: <what>` — refactor, dep bump, CI, version bumps
+- `test: <what>` or `test+docs: <what>` — tests only / tests + docs
+
+Include the issue number in the PR title or body when the PR closes
+one: `feat(v0.8): tool-calling bar chart (#65)`.
 
 ### PR body checklist
 

README.md

@@ -3,10 +3,14 @@
 > **LLM-powered knowledge base from your Claude Code, Codex CLI, Cursor, Gemini CLI, and Obsidian sessions.**
 > Built on [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
 
+## 👉 Live demo: **[pratiyush.github.io/llm-wiki](https://pratiyush.github.io/llm-wiki/)**
+
+Rebuilt on every `master` push from the synthetic sessions in [`examples/demo-sessions/`](examples/demo-sessions). No personal data. Shows every feature of the real tool (activity heatmap, tool charts, token usage, model info cards, vs-comparisons, project topics) running against safe reference data.
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-v0.4.0-7C3AED.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-95%20passing-10B981.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-v0.9.0-7C3AED.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-420%20passing-10B981.svg)](tests/)
 [![Works with Claude Code](https://img.shields.io/badge/Claude%20Code-✓-7C3AED.svg)](https://claude.com/claude-code)
 [![Works with Codex CLI](https://img.shields.io/badge/Codex%20CLI-✓-7C3AED.svg)](https://github.com/openai/codex)
 
@@ -21,7 +25,7 @@ Every Claude Code, Codex CLI, and Cursor session writes a full transcript to dis
 ./build.sh && ./serve.sh           # build + serve at http://127.0.0.1:8765
 ```
 
-> **Live demo:** https://pratiyush.github.io/llm-wiki/ — built from the dummy sessions in [`examples/demo-sessions/`](examples/demo-sessions) by [`.github/workflows/pages.yml`](.github/workflows/pages.yml). No personal data.
+**Contributing in one line:** read [`CONTRIBUTING.md`](CONTRIBUTING.md), keep PRs focused (one concern each), use `feat:` / `fix:` / `docs:` / `chore:` / `test:` commit prefixes, never commit real session data (`raw/` is gitignored), no new runtime deps. CI must be green to merge.
 
 ## Screenshots
 

docs/architecture.md

@@ -87,17 +87,23 @@ llmwiki does NOT write to `wiki/` directly. The agent does, via slash commands (
 
 Owner: `llmwiki/build.py`
 
-Converts every file under `raw/sessions/` (and any hand-authored files under `wiki/`) into static HTML. Uses `python-markdown` + `pygments` (optional, for syntax highlighting). Writes to `site/`.
+Converts every file under `raw/sessions/` (and any hand-authored files under `wiki/`) into static HTML. Uses `python-markdown` (the only runtime dep) — syntax highlighting runs in the browser via highlight.js loaded from a pinned jsdelivr CDN (v0.5, #73), so the build pipeline itself stays stdlib-only. Writes to `site/`.
 
-Pages rendered:
+Pages rendered (v0.9 surface):
 
-- `site/index.html` — home with hero + synthesis + project cards
-- `site/projects/index.html` — project grid
-- `site/projects/<project>.html` — per-project session list
+- `site/index.html` — home with hero + 365-day activity heatmap + token-usage stat grid + recently-updated card + project grid with topic chips
+- `site/projects/index.html` — project grid with freshness badges
+- `site/projects/<project>.html` — per-project page with topics strip, 365-day heatmap (scoped), tool-calling bar chart, token timeline, main sessions + sub-agents
 - `site/sessions/index.html` — sortable sessions table with filter bar
-- `site/sessions/<project>/<slug>.html` — per-session transcript page
+- `site/sessions/<project>/<slug>.html` — per-session transcript with tool chart + token card + full conversation
+- `site/models/index.html` — sortable AI-model directory (v0.7, #55)
+- `site/models/<slug>.html` — per-model info card + changelog timeline + pricing sparkline (v0.7, #56)
+- `site/vs/index.html` — auto-generated vs-comparison index (v0.7, #58)
+- `site/vs/<a>-vs-<b>.html` — side-by-side info table + benchmark chart + price delta
+- `site/changelog.html` — `CHANGELOG.md` rendered as a first-class page (v0.4.2, #72)
 - `site/search-index.json` — pre-built client-side search index
 - `site/sources/<project>/<slug>.md` — copies of raw source for download
+- Plus AI-consumable exports: `llms.txt`, `llms-full.txt`, `graph.jsonld`, `sitemap.xml`, `rss.xml`, per-page `.txt` + `.json` siblings
 
 ### L3 — Viewer (browser JS)
 
@@ -174,7 +180,7 @@ See [framework.md §5.25 Adapter Flow](framework.md) for the full contract. TL;D
 
 ## Design principles
 
-1. **Stdlib first.** Runtime deps: `markdown` (required) + `pygments` (optional). Nothing else.
+1. **Stdlib first.** Runtime dep: `markdown` only. Nothing else. Syntax highlighting runs client-side via a CDN-loaded highlight.js (v0.5, #73) so the build stays deterministic and offline-capable.
 2. **Privacy by default.** Redact everything sensitive before it hits disk.
 3. **Idempotent everything.** Re-running any command is safe and cheap.
 4. **Localhost only.** No network, no telemetry, no cloud. The user controls if/when to publish.

docs/getting-started.md

@@ -30,7 +30,7 @@ setup.bat
 
 `setup.sh` / `setup.bat` does the following, idempotently:
 
-1. Installs `markdown` (required) and `pygments` (optional, syntax highlighting) via `pip install --user`
+1. Installs `markdown` (the only runtime dep) via `pip install --user`. Syntax highlighting runs in the browser via highlight.js loaded from a CDN, so the build stays stdlib-only.
 2. Scaffolds `raw/`, `wiki/`, `site/` directories
 3. Runs `llmwiki adapters` to show which agents are detected
 4. Does a dry-run of the first sync so you see what *would* be converted

llmwiki/__init__.py

@@ -11,7 +11,7 @@
     - llmwiki.adapters.REGISTRY       — adapter registry
 """
 
-__version__ = "0.4.0"
+__version__ = "0.9.0"
 __author__ = "Pratiyush"
 __license__ = "MIT"
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "llmwiki"
-version = "0.4.0"
+version = "0.9.0"
 description = "Karpathy-style LLM wiki from your Claude Code, Codex CLI, Cursor, and Obsidian sessions"
 readme = "README.md"
 requires-python = ">=3.9"

tests/test_v04.py

@@ -15,13 +15,29 @@
 # ─── version bump ────────────────────────────────────────────────────────
 
 
-def test_version_is_v04():
-    assert __version__.startswith("0.4"), f"expected 0.4.x, got {__version__}"
+def test_version_is_valid_semver_0x():
+    """v0.4 originally locked __version__ to 0.4.x. That was too tight —
+    the project has shipped through v0.5 → v0.9 since then and the
+    hardcoded 0.4 assertion kept catching every release bump. Relaxed
+    to "any 0.x.y pre-1.0 release" so the v0.4 exporters tests below
+    still gate on the actual exporter behaviour, not the version string."""
+    parts = __version__.split(".")
+    assert len(parts) == 3, f"expected x.y.z, got {__version__}"
+    major, minor, patch = parts
+    assert major == "0", f"expected pre-1.0 release, got {__version__}"
+    assert minor.isdigit() and int(minor) >= 4, (
+        f"v0.4 introduced these tests; got {__version__}"
+    )
 
 
-def test_pyproject_version_matches():
+def test_pyproject_version_matches_package():
+    """Whatever version `llmwiki/__init__.py` sets, `pyproject.toml`
+    must match — otherwise `pip install .` ships a different number
+    than `llmwiki --version` reports."""
     content = (REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8")
-    assert 'version = "0.4' in content
+    assert f'version = "{__version__}"' in content, (
+        f"pyproject.toml version does not match __version__ ({__version__})"
+    )
 
 
 # ─── exporters ───────────────────────────────────────────────────────────