Pratiyush
diff --git a/‎.gitignore‎
Lines changed: 6 additions & 0 deletions b/‎.gitignore‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎llmwiki/build.py‎
Lines changed: 87 additions & 2 deletions b/‎llmwiki/build.py‎
Lines changed: 87 additions & 2 deletions
diff --git a/‎llmwiki/project_topics.py‎
Lines changed: 215 additions & 0 deletions b/‎llmwiki/project_topics.py‎
Lines changed: 215 additions & 0 deletions
@@ -33,6 +33,12 @@ wiki/lint-report.md
 # so the structured schema + changelog timeline are visible on the
 # live demo build.
 !wiki/entities/ClaudeSonnet4.md
+# Project topics (v0.9): `wiki/projects/<slug>.md` is hand-curated
+# per-project metadata (topics, description, homepage). Small, stable,
+# user-curated — committed so the demo build ships with topic chips
+# on every project card. Users can add their own project profiles
+# and they'll be picked up automatically.
+!wiki/projects/
 
 # Generated static HTML site (Karpathy layer 3).
 site/
 
@@ -10,6 +10,7 @@ Versions below 1.0 are pre-production — API and file formats may change.
 
 ### Added
 
+- **Project topics — GitHub-style tag chips on project cards + pages** — new `llmwiki/project_topics.py` module and `wiki/projects/<slug>.md` per-project profile convention. Each profile file carries frontmatter with a `topics:` list (`[rust, blog, ssg]`), optional `description`, and optional `homepage` URL. Build-time surfaces topics as pill-shaped chips on the home-page project cards (4 chips + overflow collapse into `+N more`) AND as a hero strip on each project detail page (up to 12 chips, with the description paragraph and a clickable homepage link if present). When no profile exists, falls back to aggregating session `tags:` frontmatter with universal noise tags (`claude-code`, `session-transcript`, `demo`) filtered out and a `min_count ≥ 2` threshold so one-off stragglers don't crowd the strip. Full dark-mode styling via theme vars; chips hover with the accent color. Seeded four profiles to ship with the repo (`demo-blog-engine`, `demo-ml-pipeline`, `demo-todo-api`, `llm-wiki`) and added a gitignore exception for `wiki/projects/` so user profiles are committed by default. 24 new tests cover profile loading, topics normalization (lowercase + dedup), session-tag aggregation with noise filtering, precedence rules, chip rendering, overflow collapse, HTML escaping, URL encoding for linked chips.
 - **Append-only changelog field + timeline + pricing sparkline** (#56) — new `llmwiki/changelog_timeline.py` module consumes an optional `changelog:` list in model entity frontmatter and renders three surfaces: (1) a vertical **timeline widget** on each model detail page (newest-first, with from→to deltas colored by direction — price cuts green, price hikes red, benchmark lifts green, numeric context expansions shown with an up arrow), (2) an inline **pricing sparkline** (stdlib SVG) that appears when the changelog has ≥2 dated `input_per_1m` changes so readers can see the trend at a glance, and (3) a **"Recently updated · last 30 days"** card on the home page listing any model entity that changed recently. Append-only by design — if an entry is wrong, add a correcting entry rather than rewriting history. The frontmatter parser's naive comma-split on bracketed JSON arrays is papered over by a stitch-and-reparse fallback in `parse_changelog()`, with a regression test locking it in place. Numeric deltas get K/M suffix formatting, string deltas (e.g. license changes) render as strike-through → bold. All HTML-escaped. 27 new tests. Seeded `wiki/entities/ClaudeSonnet4.md` with a real 4-entry changelog (launch → price cut → context expansion → SWE-bench update) so the feature is visible immediately on the live build.
 - **Structured model-profile schema + `/models/` section** (#55) — new `llmwiki/schema.py` (stdlib-only TypedDict validator) and `llmwiki/models_page.py` (renderer) add an opt-in schema for entity pages with `entity_kind: ai-model`. Pages can declare `provider`, inline-JSON `model` / `pricing` / `benchmarks` blocks, and a `modalities` list. The build pipeline discovers every valid model page under `wiki/entities/`, validates it (bad data → warnings, not build crashes), renders a structured info-card at the top of a per-model detail page (`/models/<slug>.html`), and emits a sortable `/models/index.html` table with every benchmark key used anywhere as a column. 13 well-known benchmark keys get pretty labels (`gpqa_diamond` → "GPQA Diamond", `swe_bench` → "SWE-bench", `mmlu` → "MMLU", etc.); unknown keys pass through for forward compatibility. Price formatting supports USD/EUR/GBP and falls back to currency-prefixed for anything else. New nav-bar link "Models" active on the detail and index pages. Full docs in `docs/reference/entity-schema.md`, seeded example in `wiki/entities/ClaudeSonnet4.md`. 36 new tests across `test_schema.py` (21) and `test_models_page.py` (15): happy path, minimum-viable page, validation warnings, non-numeric benchmarks, out-of-range scores rejected, malformed JSON treated as empty + warning, unknown benchmark keys allowed, HTML escaping, benchmark sort order, table column union.
 - **Folder-level `_context.md` files** (#60) — new `llmwiki/context_md.py` module + convention, borrowed from [tobi/qmd](https://github.com/tobi/qmd)'s context pattern. An optional `_context.md` file can sit alongside pages in any wiki folder (e.g. `wiki/entities/_context.md`) to describe what the folder is for and which queries should traverse it. When a Claude Code `/wiki-query` session walks the tree, it reads the folder's context file first and uses the summary to decide whether to descend — saving context tokens on every deep query instead of sampling random pages to infer a folder's purpose. `build.py`'s `discover_sources()` now skips `_context.md` so these files never pollute the session index, search index, or AI-consumable exports. `CLAUDE.md` Query + Lint workflows document the convention, and `find_uncontexted_folders()` powers a new `/wiki-lint` warning for folders with >10 pages but no context stub. Ships with three seeded stubs (`wiki/entities/_context.md`, `wiki/concepts/_context.md`, `wiki/sources/_context.md`) to show the pattern. 19 new tests.
 
@@ -57,6 +57,11 @@
     render_model_info_card,
     render_models_index,
 )
+from llmwiki.project_topics import (
+    get_project_topics,
+    load_project_profile,
+    render_topic_chips,
+)
 from llmwiki.viz_heatmap import collect_session_counts, render_heatmap
 from llmwiki.viz_tokens import (
     render_project_token_card,
@@ -73,6 +78,9 @@
 RAW_DIR = REPO_ROOT / "raw"
 RAW_SESSIONS = RAW_DIR / "sessions"
 DEFAULT_OUT_DIR = REPO_ROOT / "site"
+# v0.7+: optional per-project metadata (topics, description, homepage).
+# Users drop a `wiki/projects/<slug>.md` file with frontmatter.
+PROJECTS_META_DIR = REPO_ROOT / "wiki" / "projects"
 
 
 # ─── frontmatter ───────────────────────────────────────────────────────────
@@ -776,7 +784,42 @@ def card(p: Path, meta: dict[str, Any]) -> str:
   </div>
 </section>"""
 
-    body = f"""{heatmap_block}
+    # Project topics strip — renders below the hero, above the heatmap.
+    # Explicit profile via wiki/projects/<slug>.md wins over the
+    # session-tag fallback. Projects with no topics render an empty
+    # strip (no chip row at all).
+    proj_profile = load_project_profile(PROJECTS_META_DIR, project_slug)
+    proj_topics = get_project_topics(PROJECTS_META_DIR, project_slug, proj_entries)
+    topics_html = render_topic_chips(
+        proj_topics, max_visible=12, classname="project-topics project-hero-topics"
+    )
+    description_html = ""
+    if proj_profile and proj_profile.get("description"):
+        description_html = (
+            f'<p class="project-description muted">'
+            f'{html.escape(proj_profile["description"])}</p>'
+        )
+    homepage_html = ""
+    if proj_profile and proj_profile.get("homepage"):
+        hp = proj_profile["homepage"]
+        homepage_html = (
+            f'<a class="project-homepage" href="{html.escape(hp)}" '
+            f'rel="noopener">{html.escape(hp)} ↗</a>'
+        )
+    topics_strip = ""
+    if topics_html or description_html or homepage_html:
+        topics_strip = (
+            '<section class="section project-topics-section">\n'
+            '  <div class="container">\n'
+            f'    {description_html}\n'
+            f'    {topics_html}\n'
+            f'    {homepage_html}\n'
+            '  </div>\n'
+            '</section>\n'
+        )
+
+    body = f"""{topics_strip}
+{heatmap_block}
 {tool_chart_block}
 {token_timeline_block}
 <section class="section">
@@ -1033,10 +1076,18 @@ def render_index(
     cards = []
     for project, sessions in sorted(groups.items(), key=lambda x: -len(x[1])):
         main_count = sum(1 for p, _, _ in sessions if "subagent" not in p.name)
+        # Project topics — explicit profile in wiki/projects/<slug>.md
+        # takes precedence, falls back to aggregated session tags with
+        # noise filtered out. Rendered as chips below the card meta.
+        proj_metas = [m for _, m, _ in sessions]
+        topics = get_project_topics(PROJECTS_META_DIR, project, proj_metas)
+        topics_html = render_topic_chips(topics, max_visible=4,
+                                         classname="project-topics card-topics")
         cards.append(
-            f"""  <a class="card" href="projects/{html.escape(project)}.html">
+            f"""  <a class="card card-project" href="projects/{html.escape(project)}.html">
     <div class="card-title">{html.escape(project)}</div>
     <div class="card-meta">{main_count} main · {len(sessions) - main_count} sub-agent</div>
+    {topics_html}
   </a>"""
         )
 
@@ -1774,6 +1825,40 @@ def build_search_index(
 .recently-updated-item a:hover { text-decoration: underline; }
 .recently-updated-date { font-family: 'JetBrains Mono', monospace; font-size: 0.78rem; }
 
+/* Project topics — GitHub-style tag chips on project cards, project
+   detail pages, and the home-page grid. Rendered by
+   llmwiki/project_topics.py. Tag colors are theme-neutral so the
+   same style reads on both project cards (light background) and
+   the project hero strip. */
+.project-topics { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 10px; }
+.topic-chip {
+  display: inline-block;
+  padding: 3px 10px;
+  background: var(--bg-alt);
+  color: var(--text-secondary);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  font-size: 0.72rem;
+  font-weight: 500;
+  line-height: 1.4;
+  text-decoration: none;
+  transition: all 0.1s;
+}
+a.topic-chip:hover {
+  color: var(--accent);
+  border-color: var(--accent);
+  background: var(--bg-card);
+}
+.topic-chip-more { opacity: 0.7; }
+.card-topics { margin-top: 8px; }
+.card-topics .topic-chip { font-size: 0.68rem; padding: 2px 8px; }
+.project-topics-section { padding-top: 0; padding-bottom: 0; }
+.project-topics-section .container { padding-top: 16px; padding-bottom: 4px; }
+.project-description { margin: 0 0 10px; font-size: 0.92rem; line-height: 1.5; max-width: 680px; }
+.project-hero-topics { margin-bottom: 6px; }
+.project-homepage { display: inline-block; margin-top: 6px; font-size: 0.82rem; color: var(--accent); text-decoration: none; }
+.project-homepage:hover { text-decoration: underline; }
+
 /* v0.4: Deep-link icon next to headings */
 .content h2 .deep-link, .content h3 .deep-link, .content h4 .deep-link { margin-left: 8px; font-size: 0.8em; opacity: 0; text-decoration: none; transition: opacity 0.15s; }
 .content h2:hover .deep-link, .content h3:hover .deep-link, .content h4:hover .deep-link { opacity: 0.7; }
 
@@ -0,0 +1,215 @@
+"""Project topics — GitHub-style tag chips on project cards + pages.
+
+Surfaces user-declared topic tags on the home page project cards, the
+per-project detail page, the projects index, and (as filterable chips)
+the sessions index. The same "topics" concept GitHub shows at the top
+of a repo page, so visitors can instantly see what a project is about.
+
+Data sources, in order of precedence:
+
+1. **Explicit**: `wiki/projects/<slug>.md` frontmatter. Users drop a
+   small file per project with `topics: [rust, blog, ssg]` and an
+   optional `description` + `homepage` URL. This is the primary
+   source — it's user-curated and stable.
+
+2. **Fallback**: session `tags:` frontmatter, aggregated across every
+   session in the project, with the universal noise tags
+   (`claude-code`, `session-transcript`, `demo`) filtered out. Sessions
+   rarely carry distinctive tags today, but this makes the feature
+   zero-config for projects where the user has added project-specific
+   tags to their sessions.
+
+Missing data gracefully returns an empty list — callers decide whether
+to render the empty state.
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional, TypedDict
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)$", re.DOTALL)
+
+# Tags that appear on nearly every session and carry no
+# project-specific signal. Filtered out of the session-tag fallback.
+_NOISE_TAGS: frozenset[str] = frozenset(
+    {"claude-code", "session-transcript", "demo", "codex-cli", "cursor"}
+)
+
+
+class ProjectTopicsProfile(TypedDict, total=False):
+    """Explicit metadata for a project, loaded from
+    `wiki/projects/<slug>.md` frontmatter."""
+    topics: list[str]
+    description: str
+    homepage: str
+
+
+def _parse_topics_frontmatter(text: str) -> dict[str, Any]:
+    """Tiny frontmatter parser — mirrors build.py's but self-contained
+    so this module can be tested in isolation. Supports plain key/value
+    and bracketed-list values."""
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    raw = m.group(1)
+    meta: dict[str, Any] = {}
+    for line in raw.splitlines():
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        if value.startswith("[") and value.endswith("]"):
+            inner = value[1:-1].strip()
+            meta[key.strip()] = (
+                [x.strip() for x in inner.split(",") if x.strip()]
+                if inner else []
+            )
+        else:
+            meta[key.strip()] = value
+    return meta
+
+
+def load_project_profile(
+    projects_dir: Path,
+    project_slug: str,
+) -> Optional[ProjectTopicsProfile]:
+    """Load `<projects_dir>/<slug>.md` and extract the topics profile.
+
+    Returns `None` if the file doesn't exist. Missing fields are
+    omitted from the result dict.
+    """
+    path = projects_dir / f"{project_slug}.md"
+    if not path.is_file():
+        return None
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    meta = _parse_topics_frontmatter(text)
+    profile: ProjectTopicsProfile = {}
+    topics = meta.get("topics")
+    if isinstance(topics, list):
+        # Normalize: strip, lowercase, dedup, keep order
+        seen: set[str] = set()
+        normalized: list[str] = []
+        for t in topics:
+            t_clean = str(t).strip().lower()
+            if t_clean and t_clean not in seen:
+                seen.add(t_clean)
+                normalized.append(t_clean)
+        profile["topics"] = normalized
+    elif isinstance(topics, str) and topics:
+        profile["topics"] = [t.strip().lower() for t in topics.strip("[]").split(",") if t.strip()]
+    description = meta.get("description")
+    if description:
+        profile["description"] = str(description)
+    homepage = meta.get("homepage")
+    if homepage:
+        profile["homepage"] = str(homepage)
+    return profile
+
+
+def extract_session_topics(
+    session_metas: Iterable[Mapping[str, Any]],
+    max_topics: int = 8,
+    min_count: int = 2,
+) -> list[str]:
+    """Aggregate tags across a project's sessions and return the most
+    common non-noise tags. Used as a fallback when there's no explicit
+    `wiki/projects/<slug>.md` profile.
+
+    A tag must appear in at least `min_count` sessions to be included —
+    filters out one-off stragglers. Returns at most `max_topics` tags,
+    ordered by frequency descending.
+    """
+    counts: Counter[str] = Counter()
+    for meta in session_metas:
+        raw = meta.get("tags")
+        if isinstance(raw, list):
+            for t in raw:
+                tag = str(t).strip().lower()
+                if tag and tag not in _NOISE_TAGS:
+                    counts[tag] += 1
+        elif isinstance(raw, str) and raw:
+            for t in raw.strip("[]").split(","):
+                tag = t.strip().lower()
+                if tag and tag not in _NOISE_TAGS:
+                    counts[tag] += 1
+    filtered = [(tag, c) for tag, c in counts.items() if c >= min_count]
+    filtered.sort(key=lambda kv: (-kv[1], kv[0]))
+    return [tag for tag, _ in filtered[:max_topics]]
+
+
+def get_project_topics(
+    projects_dir: Path,
+    project_slug: str,
+    session_metas: Iterable[Mapping[str, Any]],
+) -> list[str]:
+    """Return the topic list for a project using the precedence rules
+    above: explicit profile first, session-tag fallback second."""
+    profile = load_project_profile(projects_dir, project_slug)
+    if profile and profile.get("topics"):
+        return profile["topics"]
+    return extract_session_topics(session_metas)
+
+
+# ─── render ──────────────────────────────────────────────────────────────
+
+
+import html  # noqa: E402 — deliberately after the typed definitions
+
+
+def render_topic_chips(
+    topics: list[str],
+    max_visible: int = 6,
+    classname: str = "project-topics",
+) -> str:
+    """Render a list of topics as a row of chip elements. Empty list
+    returns an empty string. Overflow is collapsed into a `+N more`
+    chip so the row stays one line on narrow cards."""
+    if not topics:
+        return ""
+    visible = topics[:max_visible]
+    hidden = len(topics) - len(visible)
+    chip_html = "".join(
+        f'<span class="topic-chip">{html.escape(t)}</span>'
+        for t in visible
+    )
+    overflow = (
+        f'<span class="topic-chip topic-chip-more">+{hidden} more</span>'
+        if hidden > 0 else ""
+    )
+    return f'<div class="{html.escape(classname)}">{chip_html}{overflow}</div>'
+
+
+def render_topic_chips_linked(
+    topics: list[str],
+    href_template: str = "../projects/index.html?topic={topic}",
+    max_visible: int = 6,
+    classname: str = "project-topics",
+) -> str:
+    """Same as `render_topic_chips` but wraps each chip in an `<a>` so
+    clicking a topic can navigate to a filter view. The href is
+    rendered via `href_template.format(topic=...)` with URL escaping."""
+    if not topics:
+        return ""
+    import urllib.parse
+    visible = topics[:max_visible]
+    hidden = len(topics) - len(visible)
+    chip_html = "".join(
+        f'<a class="topic-chip" href="{html.escape(href_template.format(topic=urllib.parse.quote(t)))}">'
+        f'{html.escape(t)}</a>'
+        for t in visible
+    )
+    overflow = (
+        f'<span class="topic-chip topic-chip-more">+{hidden} more</span>'
+        if hidden > 0 else ""
+    )
+    return f'<div class="{html.escape(classname)}">{chip_html}{overflow}</div>'