From 0139356a86d206b3aa73ab257d4a34fce30efc72 Mon Sep 17 00:00:00 2001 From: nivSwisa1 Date: Mon, 12 Oct 2026 11:57:12 +0300 Subject: [PATCH 1/7] LINBEE-29986 | feat: changelog site on GitHub Pages Builds a searchable, filterable changelog page and Atom feed from each plugin's CHANGELOG.md and deploys it on merge to main. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pages.yml | 52 +++++ .gitignore | 1 + README.md | 3 +- scripts/build-changelog-site.py | 377 ++++++++++++++++++++++++++++++++ tests/site/build_test.sh | 39 ++++ 5 files changed, 471 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/pages.yml create mode 100755 scripts/build-changelog-site.py create mode 100755 tests/site/build_test.sh diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..a2e8ca6 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,52 @@ +name: Changelog site + +on: + workflow_dispatch: + push: + branches: + - main + paths: + - plugins/*/CHANGELOG.md + - plugins/*/.claude-plugin/plugin.json + - .claude-plugin/marketplace.json + - scripts/build-changelog-site.py + +permissions: + contents: read + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + timeout-minutes: 5 + + steps: + - uses: actions/checkout@v7 + + - name: Build site from CHANGELOGs + run: scripts/build-changelog-site.py _site + + - uses: actions/configure-pages@v6 + + - uses: actions/upload-pages-artifact@v5 + with: + path: _site + + deploy: + needs: build + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index a953c9c..090b086 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ *.tmp .env .env.* +_site/ diff --git a/README.md b/README.md index 7bfdaad..de5a9f8 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ Plugins · How it works · Privacy · + Changelog · Security

@@ -46,7 +47,7 @@ export LINEARB_API_TOKEN="" **3. Restart Claude Code** from that shell. Hooks and the skill read the environment at launch. -**Stay up to date:** third-party marketplaces don't auto-update by default. Enable it in `/plugin` → Marketplaces → `linearb-ai` → Enable auto-update, or run `claude plugin update agentic-advisor@linearb-ai` and restart. See each plugin's `CHANGELOG.md` (e.g. [agentic-advisor](plugins/agentic-advisor/CHANGELOG.md)) or [Releases](https://github.com/linear-b/agent-plugins/releases) for what changed. +**Stay up to date:** third-party marketplaces don't auto-update by default. Enable it in `/plugin` → Marketplaces → `linearb-ai` → Enable auto-update, or run `claude plugin update agentic-advisor@linearb-ai` and restart. See the [changelog](https://linear-b.github.io/agent-plugins/) for what changed in each release. That's it. Start a code task (`fix the retry bug in billing/client.ts`) and the agent prints its verdict before it edits anything: diff --git a/scripts/build-changelog-site.py b/scripts/build-changelog-site.py new file mode 100755 index 0000000..096ffa3 --- /dev/null +++ b/scripts/build-changelog-site.py @@ -0,0 +1,377 @@ +#!/usr/bin/env python3 +"""Build the GitHub Pages changelog site from plugins/*/CHANGELOG.md. + +Usage: scripts/build-changelog-site.py [out_dir] (default: _site) +Writes index.html and feed.xml. Standard library only. +""" +import datetime +import html +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +SITE_URL = "https://linear-b.github.io/agent-plugins/" +REPO_URL = "https://github.com/linear-b/agent-plugins" +MARKETPLACE = "linearb-ai" + +VERSION_RE = re.compile(r"^## \[([^\]]+)\](?:\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$") +SECTION_RE = re.compile(r"^### (.+?)\s*$") +ITEM_RE = re.compile(r"^[-*] (.*)$") + + +def parse_changelog(text): + """Keep-a-Changelog subset -> [{version, date, sections: [{name, items}]}].""" + releases, rel, sec = [], None, None + for line in text.splitlines(): + m = VERSION_RE.match(line) + if m: + rel = {"version": m.group(1), "date": m.group(2) or "", "sections": []} + releases.append(rel) + sec = None + continue + if rel is None or re.match(r"^\[[^\]]+\]: ", line): + continue + m = SECTION_RE.match(line) + if m: + sec = {"name": m.group(1), "items": []} + rel["sections"].append(sec) + continue + m = ITEM_RE.match(line) + if m: + if sec is None: # bullet without a ### heading + sec = {"name": "Changed", "items": []} + rel["sections"].append(sec) + sec["items"].append(m.group(1).strip()) + elif line.startswith(" ") and line.strip() and sec and sec["items"]: + sec["items"][-1] += " " + line.strip() # wrapped bullet + return releases + + +def inline(md): + """Escape, then render `code`, [text](http...) and **bold**.""" + codes = [] + + def keep_code(m): + codes.append("" + html.escape(m.group(1)) + "") + return "\x00%d\x00" % (len(codes) - 1) + + s = re.sub(r"`([^`]+)`", keep_code, md) + s = html.escape(s) + + def link(m): + text, url = m.group(1), html.unescape(m.group(2)) + if not re.match(r"^https?://", url): + return m.group(0) + cls = ' class="pr"' if re.fullmatch(r"#\d+", text) else "" + return '%s' % (cls, html.escape(url, quote=True), text) + + s = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", link, s) + s = re.sub(r"\(((?:]*>[^<]*(?:,\s*)?)+)\)", r"\1", s) # "(#10)" -> pill + s = re.sub(r"\*\*(.+?)\*\*", r"\1", s) + return re.sub(r"\x00(\d+)\x00", lambda m: codes[int(m.group(1))], s) + + +def load_plugins(): + market = json.loads((ROOT / ".claude-plugin/marketplace.json").read_text()) + short = {p["name"]: p.get("description", "") for p in market.get("plugins", [])} + plugins = [] + for d in sorted((ROOT / "plugins").iterdir()): + cl, manifest = d / "CHANGELOG.md", d / ".claude-plugin/plugin.json" + if not cl.is_file() or not manifest.is_file(): + continue + meta = json.loads(manifest.read_text()) + name = meta["name"] + plugins.append({ + "name": name, + "version": meta.get("version", ""), + "description": short.get(name) or meta.get("description", ""), + "releases": parse_changelog(cl.read_text()), + }) + return plugins + + +def slug(s): + return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-") + + +def render_release(p, r, latest): + rid = "%s-v%s" % (slug(p["name"]), slug(r["version"])) + kinds = " ".join(sorted({slug(s["name"]) for s in r["sections"]})) + out = ['
' % (rid, kinds)] + out.append('
') + out.append('' + % (rid, html.escape(r["version"]))) + out.append('

#%s

' + % (rid, html.escape(r["version"]), html.escape(r["version"]))) + if latest: + out.append('Latest') + if r["date"]: + out.append('' % (r["date"], r["date"])) + tag = "%s--v%s" % (p["name"], r["version"]) + out.append('Release notes' + % (REPO_URL, html.escape(tag, quote=True))) + out.append("
") + out.append('
' % rid) + for s in r["sections"]: + k = slug(s["name"]) + out.append('
' % k) + out.append('

%s

    ' % (k, html.escape(s["name"]))) + out.extend("
  • %s
    • " % inline(i) for i in s["items"]) + out.append("
") + out.append("
") + return "\n".join(out) + + +def render(plugins): + built = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d") + kinds = [] + for p in plugins: + for r in p["releases"]: + for s in r["sections"]: + if s["name"] not in kinds: + kinds.append(s["name"]) + chips = "".join('' + % (slug(k), slug(k), html.escape(k)) for k in kinds) + + nav, body = [], [] + for p in plugins: + nav.append('

%s

    ' % html.escape(p["name"])) + for i, r in enumerate(p["releases"]): + rid = "%s-v%s" % (slug(p["name"]), slug(r["version"])) + nav.append('
  1. %s%s
    2. ' + % (rid, html.escape(r["version"]), html.escape(r["date"]))) + nav.append("
") + install = "/plugin install %s@%s" % (p["name"], MARKETPLACE) + body.append('
' % slug(p["name"])) + body.append('

%s

v%s
' + % (html.escape(p["name"]), html.escape(p["version"]))) + body.append('

%s

' % html.escape(p["description"])) + body.append('
%s
' + % (html.escape(install), html.escape(install, quote=True))) + body.append('

Already installed? claude plugin update %s@%s, then restart Claude Code.

' + % (html.escape(p["name"]), MARKETPLACE)) + body.append('
') + body.extend(render_release(p, r, i == 0) for i, r in enumerate(p["releases"])) + body.append("
") + + return (TEMPLATE + .replace("{{CHIPS}}", chips) + .replace("{{NAV}}", "\n".join(nav)) + .replace("{{BODY}}", "\n".join(body)) + .replace("{{REPO}}", REPO_URL) + .replace("{{BUILT}}", built)) + + +def render_feed(plugins): + entries, newest = [], "1970-01-01" + for p in plugins: + for r in p["releases"]: + date = r["date"] or "1970-01-01" + newest = max(newest, date) + rid = "%s-v%s" % (slug(p["name"]), slug(r["version"])) + content = "".join("

%s

    %s
" % (html.escape(s["name"]), + "".join("
  • %s
    • " % inline(i) for i in s["items"])) + for s in r["sections"]) + entries.append((date, "%s %s%s#%s" + '%sT00:00:00Z' + '%s' + % (html.escape(p["name"]), html.escape(r["version"]), SITE_URL, rid, + SITE_URL, rid, date, html.escape(content)))) + entries.sort(key=lambda e: e[0], reverse=True) + return ('\n' + 'LinearB Agent Plugins changelog' + '%s%sT00:00:00Z%s\n' + % (SITE_URL, SITE_URL, SITE_URL, newest, "".join(e[1] for e in entries))) + + +TEMPLATE = r""" + + + + +Changelog · LinearB Agent Plugins + + + + + + +
    +LinearB Agent Plugins + +Feed +GitHub + +
    +
    + +
    +

    Changelog

    What changed in each release, newest first.

    +
    {{CHIPS}}
    +{{BODY}} +

    No changes match. Clear filters

    +
    Generated from each plugin's CHANGELOG.md on {{BUILT}} · All releases
    +
    +
    + + + +""" + + +def main(): + out = Path(sys.argv[1] if len(sys.argv) > 1 else "_site") + plugins = load_plugins() + if not any(p["releases"] for p in plugins): + sys.exit("no CHANGELOG releases found under plugins/") + out.mkdir(parents=True, exist_ok=True) + (out / "index.html").write_text(render(plugins), encoding="utf-8") + (out / "feed.xml").write_text(render_feed(plugins), encoding="utf-8") + (out / ".nojekyll").write_text("") + print("wrote %s (%d plugin(s), %d release(s))" + % (out, len(plugins), sum(len(p["releases"]) for p in plugins))) + + +if __name__ == "__main__": + main() diff --git a/tests/site/build_test.sh b/tests/site/build_test.sh new file mode 100755 index 0000000..76a7899 --- /dev/null +++ b/tests/site/build_test.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Changelog site: builds from the real CHANGELOGs, every release shows up, markup is escaped. +set -uo pipefail + +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +pass=0; fail=0 +check() { + local name=$1; shift + if "$@"; then pass=$((pass+1)); printf 'ok %s\n' "$name"; else fail=$((fail+1)); printf 'FAIL %s\n' "$name"; fi +} + +W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT +"$ROOT/scripts/build-changelog-site.py" "$W/site" >/dev/null +check "index.html built" test -s "$W/site/index.html" +check "feed.xml is valid XML" python3 -c "import sys,xml.dom.minidom; xml.dom.minidom.parse(sys.argv[1])" "$W/site/feed.xml" + +for cl in "$ROOT"/plugins/*/CHANGELOG.md; do + name="$(basename "$(dirname "$cl")")" + while read -r v; do + check "$name $v on the page" grep -qF "id=\"$name-v${v//./-}\"" "$W/site/index.html" + done < <(sed -n 's/^## \[\([^]]*\)\].*/\1/p' "$cl") +done + +# Inline rendering: code and links render, raw HTML in an entry is escaped, non-http links stay text. +cat > "$W/inline.py" <<'PY' +import importlib.util, sys +s = importlib.util.spec_from_file_location("b", sys.argv[1]); b = importlib.util.module_from_spec(s); s.loader.exec_module(b) +print(b.inline("use `` and ([#7](https://github.com/o/r/pull/7)) [bad](javascript:alert(1))")) +PY +out="$(python3 "$W/inline.py" "$ROOT/scripts/build-changelog-site.py")" +has() { grep -qF -- "$1" <<<"$out"; } +lacks() { ! has "$1"; } +check "code span escaped" has '<x>' +check "raw html escaped" lacks ' - - -""" - - -def main(): - out = Path(sys.argv[1] if len(sys.argv) > 1 else "_site") - plugins = load_plugins() - if not any(p["releases"] for p in plugins): - sys.exit("no CHANGELOG releases found under plugins/") - out.mkdir(parents=True, exist_ok=True) - (out / "index.html").write_text(render(plugins), encoding="utf-8") - (out / "feed.xml").write_text(render_feed(plugins), encoding="utf-8") - (out / ".nojekyll").write_text("") - print("wrote %s (%d plugin(s), %d release(s))" - % (out, len(plugins), sum(len(p["releases"]) for p in plugins))) - - -if __name__ == "__main__": - main() diff --git a/scripts/build-site.py b/scripts/build-site.py new file mode 100755 index 0000000..5e74c34 --- /dev/null +++ b/scripts/build-site.py @@ -0,0 +1,737 @@ +#!/usr/bin/env python3 +"""Build the GitHub Pages site: home, one page per plugin, changelog, Atom feed. + +Usage: scripts/build-site.py [out_dir] [repo_root] (defaults: _site, this repo) +Every plugins// with a .claude-plugin/plugin.json gets a page from its README.md; +its CHANGELOG.md feeds the changelog. Standard library only. +""" +import html +import json +import re +import sys +from pathlib import Path + +SITE_URL = "https://linear-b.github.io/agent-plugins/" +REPO_URL = "https://github.com/linear-b/agent-plugins" +MARKETPLACE = "linearb-ai" +# Diagrams: plugin READMEs hold ```mermaid blocks (GitHub renders them too); the site draws them hand-drawn. +MERMAID_JS = ("https://cdn.jsdelivr.net/npm/mermaid@12.1.0/dist/mermaid.min.js", + "sha384-EbBpjO7rlR6eqZEcG7GaPpyk9H9WrMyPWX4d3KvPYltgt8Z8l0z6R56B1qP40pR4") + +VERSION_RE = re.compile(r"^## \[([^\]]+)\](?:\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$") +SECTION_RE = re.compile(r"^### (.+?)\s*$") +ITEM_RE = re.compile(r"^[-*] (.*)$") + + +# ---------- parsing ---------- + +def parse_changelog(text): + """Keep-a-Changelog subset -> [{version, date, sections: [{name, items}]}].""" + releases, rel, sec = [], None, None + for line in text.splitlines(): + m = VERSION_RE.match(line) + if m: + rel = {"version": m.group(1), "date": m.group(2) or "", "sections": []} + releases.append(rel) + sec = None + continue + if rel is None or re.match(r"^\[[^\]]+\]: ", line): + continue + m = SECTION_RE.match(line) + if m: + sec = {"name": m.group(1), "items": []} + rel["sections"].append(sec) + continue + m = ITEM_RE.match(line) + if m: + if sec is None: # bullet without a ### heading + sec = {"name": "Changed", "items": []} + rel["sections"].append(sec) + sec["items"].append(m.group(1).strip()) + elif line.startswith(" ") and line.strip() and sec and sec["items"]: + sec["items"][-1] += " " + line.strip() # wrapped bullet + return releases + + +def slug(s): + return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-") + + +def gh_slug(s): + """GitHub's heading anchor, so README #links keep working on the site.""" + s = re.sub(r"<[^>]+>", "", s).lower() + return re.sub(r"[^\w\- ]", "", s).replace(" ", "-") + + +def inline(md, link_base=None): + """Escape, then render `code`, [text](url) and **bold**. Relative links resolve against link_base.""" + codes = [] + + def keep_code(m): + codes.append("" + html.escape(m.group(1)) + "") + return "\x00%d\x00" % (len(codes) - 1) + + s = re.sub(r"`([^`]+)`", keep_code, md) + s = html.escape(s) + + def link(m): + text, url = m.group(1), html.unescape(m.group(2)) + if url.startswith("#"): + pass + elif link_base and not re.match(r"^[a-z][a-z0-9+.-]*:", url, re.I): + url = link_base + url.lstrip("./") + elif not re.match(r"^https?://", url): + return m.group(0) + cls = ' class="pr"' if re.fullmatch(r"#\d+", text) else "" + return '%s' % (cls, html.escape(url, quote=True), text) + + s = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", link, s) + s = re.sub(r"\(((?:]*>[^<]*(?:,\s*)?)+)\)", r"\1", s) # "(#10)" -> pill + s = re.sub(r"\*\*(.+?)\*\*", r"\1", s) + return re.sub(r"\x00(\d+)\x00", lambda m: codes[int(m.group(1))], s) + + +def markdown(text, link_base=None): + """README subset -> (html, [(id, h2 text)]). Raw HTML lines are dropped, never passed through.""" + lines, out, toc, i = text.splitlines(), [], [], 0 + il = lambda s: inline(s, link_base) # noqa: E731 + + def is_block_start(l): + return (not l.strip() or l.startswith(("#", ">", "|", "```", "<")) + or re.match(r"^\s*([-*]|\d+\.) ", l) is not None) + + while i < len(lines): + line = lines[i] + if not line.strip() or line.lstrip().startswith("<"): + i += 1 + continue + if line.startswith("```"): + lang, body = line[3:].strip(), [] + i += 1 + while i < len(lines) and not lines[i].startswith("```"): + body.append(lines[i]) + i += 1 + i += 1 + src = html.escape("\n".join(body)) + if lang == "mermaid": + out.append('
    %s
    ' % src) + else: + out.append(code_block("\n".join(body))) + continue + m = re.match(r"^(#{1,6}) (.+?)\s*#*$", line) + if m: + level, title = len(m.group(1)), m.group(2) + hid = gh_slug(title) + if level == 2: + toc.append((hid, re.sub(r"<[^>]+>", "", il(title)))) + out.append('%s' % (level, hid, il(title), level)) + i += 1 + continue + if line.startswith(">"): + quote = [] + while i < len(lines) and lines[i].startswith(">"): + quote.append(lines[i][1:].strip()) + i += 1 + out.append("

    %s

    " % il(" ".join(quote))) + continue + if line.startswith("|") and i + 1 < len(lines) and re.match(r"^\|[\s:|-]+\|?\s*$", lines[i + 1]): + cells = lambda l: [c.strip() for c in l.strip().strip("|").split("|")] # noqa: E731 + head = cells(line) + i += 2 + rows = [] + while i < len(lines) and lines[i].startswith("|"): + rows.append(cells(lines[i])) + i += 1 + out.append('
    %s%s
    ' % ( + "".join("%s" % il(c) for c in head), + "".join("%s" % "".join("%s" % il(c) for c in r) for r in rows))) + continue + m = re.match(r"^([-*]|\d+\.) ", line) + if m: + ordered = m.group(1)[0].isdigit() + items = [] + while i < len(lines): + m2 = re.match(r"^([-*]|\d+\.) (.*)$", lines[i]) + if m2 and m2.group(1)[0].isdigit() == ordered: + items.append(m2.group(2)) + elif lines[i].startswith(" ") and lines[i].strip() and items: + items[-1] += " " + lines[i].strip() + elif not lines[i].strip() and i + 1 < len(lines) and re.match( + r"^\d+\. " if ordered else r"^[-*] ", lines[i + 1]): + pass # blank line between items of the same list + else: + break + i += 1 + tag = "ol" if ordered else "ul" + out.append("<%s>%s" % (tag, "".join("
  • %s
    • " % il(x) for x in items), tag)) + continue + para = [] + while i < len(lines) and not (para and is_block_start(lines[i])): + para.append(lines[i].strip()) + i += 1 + out.append("

    %s

    " % il(" ".join(para))) + return "\n".join(out), toc + + +def split_readme(text): + """README -> (lede markdown, rest markdown): drop the H1, take the first paragraph as the lede.""" + lines = text.splitlines() + if lines and lines[0].startswith("# "): + lines = lines[1:] + while lines and not lines[0].strip(): + lines = lines[1:] + lede = [] + while lines and lines[0].strip() and not lines[0].startswith(("#", "```", ">", "|", "-")): + lede.append(lines.pop(0).strip()) + return " ".join(lede), "\n".join(lines) + + +def load_plugins(root): + market = json.loads((root / ".claude-plugin/marketplace.json").read_text()) + short = {p["name"]: p.get("description", "") for p in market.get("plugins", [])} + plugins = [] + for d in sorted((root / "plugins").iterdir()): + manifest = d / ".claude-plugin/plugin.json" + if not manifest.is_file(): + continue + meta = json.loads(manifest.read_text()) + name = meta["name"] + cl, readme = d / "CHANGELOG.md", d / "README.md" + plugins.append({ + "name": name, + "dir": d.name, + "version": meta.get("version", ""), + "description": short.get(name) or meta.get("description", ""), + "readme": readme.read_text() if readme.is_file() else "", + "releases": parse_changelog(cl.read_text()) if cl.is_file() else [], + }) + return market, plugins + + +# ---------- rendering ---------- + +def managed_settings(names): + """Claude.ai admin console > Claude Code > Managed settings: installs and enables for the whole org.""" + return json.dumps({ + "env": {"LINEARB_API_TOKEN": " Settings > API Tokens>"}, + "extraKnownMarketplaces": {MARKETPLACE: { + "source": {"source": "github", "repo": REPO_URL.split("github.com/")[1]}, "autoUpdate": True}}, + "enabledPlugins": {"%s@%s" % (n, MARKETPLACE): True for n in names}, + }, indent=2) + + +def code_block(src): + return ('
    %s
    ' + % (html.escape(src), html.escape(src, quote=True))) + + +def rollout(names): + return """
    +

    Roll out to your whole org

    +

    Admins can install and enable this for every developer from Claude.ai admin console → Claude Code → Managed settings. Paste this, then replace the token placeholder.

    +

    The token in managed settings is pushed to every developer's machine. Use a token created for this purpose, so you can rotate it on its own.

    + %s
    """ % code_block(managed_settings(names)) + + +def rel_id(p, r): + return "%s-v%s" % (slug(p["name"]), slug(r["version"])) + + +def install_box(cmd): + return ('
    %s
    ' + % (html.escape(cmd), html.escape(cmd, quote=True))) + + +def render_release(p, r, latest, base): + rid = rel_id(p, r) + out = ['
    ' % rid, '
    ', + '' + % (rid, html.escape(r["version"])), + '

    #%s

    ' + % (rid, html.escape(r["version"]), html.escape(r["version"]))] + if latest: + out.append('Latest') + if r["date"]: + out.append('' % (r["date"], r["date"])) + tag = "%s--v%s" % (p["name"], r["version"]) + out.append('Release notes' + % (REPO_URL, html.escape(tag, quote=True))) + out.append('
    ' % rid) + for s in r["sections"]: + k = slug(s["name"]) + out.append('

    %s

      ' + % (k, k, html.escape(s["name"]))) + out.extend("
    • %s
      • " % inline(i) for i in s["items"]) + out.append("
    ") + out.append("
    ") + return "\n".join(out) + + +def logo(root): + svg = (root / "site/assets/linearb-logo.svg").read_text() + return re.sub(r'\s(width|height)="[^"]*"', "", svg, count=2).replace("Updated ' % (latest["date"], latest["date"]) + if latest and latest["date"] else "") + cards.append( + '' + % (p["dir"], html.escape(p["name"]), html.escape(p["version"]), html.escape(p["description"]), meta, + install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), p["dir"], slug(p["name"]))) + news = [] + for p, r in sorted(((p, r) for p in plugins for r in p["releases"][:3]), + key=lambda x: (x[1]["date"], x[1]["version"]), reverse=True)[:4]: + first_item = next((s["items"][0] for s in r["sections"] if s["items"]), "") + summary = re.sub(r"\s*\(\[#\d+\]\([^)]*\)\)", "", first_item) + news.append('
  • %s %s

    %s

    • ' + % (rel_id(p, r), html.escape(p["name"]), html.escape(r["version"]), + r["date"], r["date"], inline(summary))) + body = """ +
    +

    Claude Code plugins

    +

    Engineering context from LinearB, right inside your AI coding agent.

    +

    Plugins that give your agent the context a senior engineer would have: how healthy the repo is, how fragile the files are, and how much care the change deserves.

    + {box} +
    Browse pluginsWhat's new
    +
    +

    Quick start

      +

    1. Add the marketplace

      In Claude Code, run /plugin marketplace add linear-b/agent-plugins.

      2. +

    2. Install a plugin

      For example /plugin install {first}@{mk}.

      3. +

    3. Connect LinearB

      Create a token in LinearB → Settings → API Tokens, export LINEARB_API_TOKEN=…, then restart Claude Code.

      4. +
    {rollout}
    +

    Plugins

    {cards}
    +
    +

    What's new

      {news}
    Full changelog →
    +

    Built to stay out of the way

    +
    +
    Your data stays in your org
    Usage is reported only to the LinearB org your token belongs to. Source code and full prompts are never sent.
    +
    Never blocks
    If LinearB can't be reached, plugins fall back to safe defaults and your agent keeps working.
    +
    Open source
    Apache-2.0. Report vulnerabilities to security@linearb.io, per SECURITY.md.
    +
    +
    +
    +""".format(box=install_box("/plugin marketplace add linear-b/agent-plugins"), + first=html.escape(first), mk=MARKETPLACE, rollout=rollout([p["name"] for p in plugins]), cards="".join(cards), news="".join(news), repo=REPO_URL) + return page(root, "LinearB Agent Plugins", desc, body, "", "home") + + +def render_plugin(root, p): + base = "../" + lede, rest = split_readme(p["readme"]) + link_base = "%s/blob/main/plugins/%s/" % (REPO_URL, p["dir"]) + body_html, toc = markdown(rest, link_base) + toc_html = "".join('
  • %s
    • ' % (h, t) for h, t in toc) + recent = "".join(render_release(p, r, i == 0, base) for i, r in enumerate(p["releases"][:3])) + body = """ +
    + +
    +""".format(toc=toc_html, name=html.escape(p["name"]), ver=html.escape(p["version"]), lede=inline(lede), + install=install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), rollout=rollout([p["name"]]), + pslug=slug(p["name"]), repo=REPO_URL, dir=p["dir"], body=body_html, recent=recent) + head, scripts = "", "" + if 'class="mermaid"' in body_html: + head = '' + scripts = '' % ( + MERMAID_JS[0], MERMAID_JS[1], DIAGRAM_JS) + return page(root, "%s · LinearB Agent Plugins" % p["name"], p["description"], body, base, "plugin", head, scripts) + + +def render_changelog(root, plugins): + base = "../" + kinds = [] + for p in plugins: + for r in p["releases"]: + for s in r["sections"]: + if s["name"] not in kinds: + kinds.append(s["name"]) + chips = "".join('' + % (slug(k), slug(k), html.escape(k)) for k in kinds) + nav, main = [], [] + for p in plugins: + if not p["releases"]: + continue + nav.append('

    %s

      ' % html.escape(p["name"])) + nav.extend('
    1. %s%s
      2. ' + % (rel_id(p, r), html.escape(r["version"]), html.escape(r["date"])) for r in p["releases"]) + nav.append("
    ") + main.append('

    %s

    ' + 'v%s
    %s
    ' + % (slug(p["name"]), base, p["dir"], html.escape(p["name"]), html.escape(p["version"]), + "".join(render_release(p, r, i == 0, base) for i, r in enumerate(p["releases"])))) + body = """ +
    + +
    +

    Changelog

    What changed in each release, newest first. Subscribe with the Atom feed.

    +
    {chips}
    +{main} +

    No changes match. Clear filters

    +
    +""".format(nav="\n".join(nav), chips=chips, main="\n".join(main)) + return page(root, "Changelog · LinearB Agent Plugins", "What changed in each release of LinearB's Claude Code plugins.", + body, base, "changelog", "", "" % CHANGELOG_JS) + + +def render_feed(plugins): + entries, newest = [], "1970-01-01" + for p in plugins: + for r in p["releases"]: + date = r["date"] or "1970-01-01" + newest = max(newest, date) + url = "%schangelog/#%s" % (SITE_URL, rel_id(p, r)) + content = "".join("

    %s

      %s
    " % (html.escape(s["name"]), + "".join("
  • %s
    • " % inline(i) for i in s["items"])) + for s in r["sections"]) + entries.append((date, "%s %s%s" + '%sT00:00:00Z' + '%s' + % (html.escape(p["name"]), html.escape(r["version"]), url, url, date, + html.escape(content)))) + entries.sort(key=lambda e: e[0], reverse=True) + return ('\n' + 'LinearB Agent Plugins changelog' + '%sLinearB' + '%sT00:00:00Z%s\n' + % (SITE_URL, SITE_URL, SITE_URL, newest, "".join(e[1] for e in entries))) + + +# ---------- assets ---------- + +# LinearB "Buzz" design system (linweb): Outfit, slate primary, bright-blue brand, Buzz status colors. +CSS = r""" +:root{--bg:#ffffff;--surface:#f5f6fa;--card:#ffffff;--fg:#0a0a0a;--primary:#383f48;--muted:#61656c;--line:#e4e4e7; +--brand:#5467ff;--brand-strong:#1831f4;--brand-soft:#eef0ff;--on-brand:#ffffff;--code:#f1f2f6; +--success:#16a34a;--success-soft:#e7f6ec;--attention:#b45309;--attention-soft:#fef3e2;--destructive:#bf1245;--destructive-soft:#fce8ee; +--font:"Outfit",ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; +--radius:12px;color-scheme:light} +@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626; +--brand:#7c88ff;--brand-strong:#9aa3ff;--brand-soft:#1c1f45;--on-brand:#0a0a0a;--code:#1d1d21; +--success:#4ade80;--success-soft:#11281a;--attention:#fbbf24;--attention-soft:#2e2209;--destructive:#fb7194;--destructive-soft:#331520;color-scheme:dark}} +:root[data-theme="dark"]{--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626; +--brand:#7c88ff;--brand-strong:#9aa3ff;--brand-soft:#1c1f45;--on-brand:#0a0a0a;--code:#1d1d21; +--success:#4ade80;--success-soft:#11281a;--attention:#fbbf24;--attention-soft:#2e2209;--destructive:#fb7194;--destructive-soft:#331520;color-scheme:dark} +*{box-sizing:border-box} +html{scroll-behavior:smooth;scroll-padding-top:84px} +@media (prefers-reduced-motion:reduce){html{scroll-behavior:auto}*{transition:none!important}} +body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.65 var(--font);-webkit-font-smoothing:antialiased} +a{color:var(--brand-strong);text-decoration:none}a:hover{text-decoration:underline} +:focus-visible{outline:2px solid var(--brand);outline-offset:2px;border-radius:4px} +h1,h2,h3{color:var(--fg);text-wrap:balance;letter-spacing:-.015em;line-height:1.2} +code{font:.85em var(--mono);background:var(--code);padding:1px 6px;border-radius:6px;word-break:break-word} +.top{position:sticky;top:0;z-index:5;background:color-mix(in srgb,var(--bg) 88%,transparent);backdrop-filter:blur(10px);border-bottom:1px solid var(--line)} +.top-in{max-width:1160px;margin:0 auto;padding-inline:20px;height:64px;display:flex;align-items:center;gap:20px} +.brand{display:flex;align-items:center;gap:12px;color:var(--fg);font-weight:500} +.brand svg{height:22px;width:auto;display:block} +.brand span{padding-left:12px;border-left:1px solid var(--line);color:var(--muted)} +.brand:hover{text-decoration:none} +.top nav{display:flex;gap:4px;margin-left:auto;align-items:center} +.top nav a{color:var(--muted);padding:6px 12px;border-radius:8px;font-size:15px} +.top nav a:hover,.top nav a[aria-current]{color:var(--fg);background:var(--surface);text-decoration:none} +.icon-btn{border:1px solid var(--line);background:var(--card);color:var(--fg);border-radius:8px;width:34px;height:34px;cursor:pointer;font:inherit} +.wrap{max-width:1160px;margin:0 auto;padding:40px 20px 72px} +.btn{display:inline-flex;align-items:center;border-radius:9px;padding:9px 16px;font:500 15px var(--font);background:var(--primary);color:var(--bg);border:1px solid transparent;cursor:pointer} +.btn:hover{text-decoration:none;filter:brightness(1.15)} +.btn.ghost{background:transparent;color:var(--fg);border-color:var(--line)} +.btn.ghost:hover{border-color:var(--brand);filter:none} +.btn.small{padding:6px 12px;font-size:13px} +.pill{font-size:12px;font-weight:600;border-radius:999px;padding:2px 10px;white-space:nowrap} +.ver{background:var(--brand-soft);color:var(--brand-strong)} +.latest{background:var(--success-soft);color:var(--success)} +.muted{color:var(--muted);font-size:14px} +.eyebrow{text-transform:uppercase;letter-spacing:.12em;font-size:13px;font-weight:600;color:var(--brand-strong);margin:0 0 14px} +.lede{color:var(--muted);font-size:18px;max-width:62ch;margin:0 0 22px} +.install{display:flex;align-items:center;gap:8px;background:var(--code);border:1px solid var(--line);border-radius:10px;padding:6px 6px 6px 14px;max-width:560px} +.install code{background:none;padding:0;flex:1;min-width:0;overflow-x:auto;white-space:nowrap;font-size:14px} +.copy{border:0;background:var(--brand);color:var(--on-brand);border-radius:7px;padding:7px 14px;font:600 13px var(--font);cursor:pointer} +.copy.ghost{background:var(--card);color:var(--muted);border:1px solid var(--line)} +.hero-actions{display:flex;flex-wrap:wrap;gap:10px;margin-top:20px} +/* home */ +.hero{padding-block:36px 56px;max-width:820px} +.hero h1{font-size:clamp(34px,5vw,54px);font-weight:600;margin:0 0 18px} +section+section{margin-top:56px} +.wrap>section>h2,.split h2{font-size:26px;margin:0 0 20px} +.steps ol{list-style:none;counter-reset:s;padding:0;margin:0;display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:16px} +.steps li{counter-increment:s;background:var(--surface);border-radius:var(--radius);padding:22px;min-width:0} +.steps li:before{content:counter(s);display:grid;place-items:center;width:30px;height:30px;border-radius:50%;background:var(--brand);color:var(--on-brand);font-weight:600;margin-bottom:12px} +.steps h3{margin:0 0 6px;font-size:18px}.steps p{margin:0;color:var(--muted)} +.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(min(100%,420px),1fr));gap:18px} +.card{background:var(--card);border:1px solid var(--line);border-radius:var(--radius);padding:24px;display:flex;flex-direction:column;gap:14px;min-width:0} +.card-top{display:flex;align-items:center;gap:10px} +.card h3{margin:0;font-size:22px}.card h3 a{color:var(--fg)} +.card p{margin:0;color:var(--muted)} +.card-actions{display:flex;flex-wrap:wrap;gap:10px;margin-top:auto} +.split{display:grid;grid-template-columns:minmax(0,1.2fr) minmax(0,1fr);gap:40px} +.news{list-style:none;padding:0;margin:0 0 14px} +.news li{padding:14px 0;border-bottom:1px solid var(--line);display:grid;grid-template-columns:auto 1fr;gap:2px 12px} +.news-ver{font-weight:600}.news time{color:var(--muted);font-size:14px;justify-self:end} +.news p{grid-column:1/-1;margin:0;color:var(--muted);font-size:15px} +.trust{align-self:start;background:var(--surface);border-radius:var(--radius);padding:24px 26px} +.trust dl{margin:0}.trust dt{font-weight:600;margin-top:16px}.trust dt:first-child{margin-top:0}.trust dd{margin:2px 0 0;color:var(--muted)} +/* docs + changelog layout */ +.doc{display:grid;grid-template-columns:210px minmax(0,1fr);gap:48px} +.side{position:sticky;top:88px;align-self:start;max-height:calc(100vh - 110px);overflow:auto} +.side-label{font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin:0 0 10px;font-weight:600} +.toc,.vers{list-style:none;margin:0 0 22px;padding:0;border-left:2px solid var(--line)} +.toc a,.vers a{display:flex;justify-content:space-between;gap:8px;padding:5px 12px;margin-left:-2px;border-left:2px solid transparent;color:var(--muted);font-size:14px} +.toc a:hover,.vers a:hover{color:var(--fg);text-decoration:none} +.toc a.active,.vers a.active{color:var(--brand-strong);border-left-color:var(--brand);font-weight:600} +.vers a.dim{opacity:.35}.vers small{font-size:12px} +.crumb{font-size:14px;color:var(--muted);margin:0 0 10px} +.doc-hero{padding-bottom:28px;border-bottom:1px solid var(--line);margin-bottom:8px} +.hero-top{display:flex;align-items:center;gap:12px;flex-wrap:wrap} +.doc-hero h1,.intro h1{font-size:clamp(32px,4vw,44px);margin:0;font-weight:600} +.doc-hero .lede{margin-top:12px} +.intro .lede{margin-top:8px} +.prose>*{max-width:76ch}.prose>.diagram,.prose>.table{max-width:none} +.prose h2{font-size:26px;margin:44px 0 12px;padding-top:4px} +.prose h3{font-size:19px;margin:28px 0 8px} +.prose p,.prose li{color:var(--fg)} +.prose ul,.prose ol{padding-left:22px}.prose li{margin:6px 0} +.prose blockquote{margin:14px 0;padding:12px 16px;background:var(--surface);border-radius:10px;font-family:var(--mono);font-size:14px;color:var(--primary)} +.prose blockquote p{margin:0} +.codeblock{position:relative;margin:16px 0} +.codeblock pre{margin:0;background:var(--code);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow-x:auto} +.codeblock pre code{background:none;padding:0;font-size:14px;white-space:pre;word-break:normal} +.codeblock .copy{position:absolute;top:8px;right:8px;opacity:0;transition:opacity .15s} +.codeblock:hover .copy,.codeblock .copy:focus-visible{opacity:1} +.table{overflow-x:auto;margin:16px 0;border:1px solid var(--line);border-radius:10px} +table{border-collapse:collapse;width:100%;font-size:14.5px} +th,td{text-align:left;padding:10px 14px;border-bottom:1px solid var(--line);vertical-align:top} +th{background:var(--surface);font-weight:600}tr:last-child td{border-bottom:0} +.diagram{margin:22px 0;background:var(--surface);border-radius:var(--radius);padding:20px;overflow-x:auto;text-align:center} +.diagram pre.mermaid{margin:0;font-family:var(--mono);font-size:13px;text-align:left;white-space:pre;color:var(--muted)} +.diagram pre.mermaid[data-processed]{text-align:center;white-space:normal} +.diagram svg{max-width:min(100%,720px);height:auto} +.rollout{margin-top:18px;display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.1fr);gap:24px;align-items:start;background:var(--card);border:1px solid var(--line);border-radius:var(--radius);padding:22px} +.rollout h3{margin:0 0 8px;font-size:18px}.rollout p{margin:0 0 10px;color:var(--muted)} +.rollout .codeblock{margin:0} +.note{font-size:14px;border-left:3px solid var(--attention);padding-left:10px} +details.team{margin-top:14px;max-width:760px} +details.team summary{cursor:pointer;color:var(--brand-strong);font-weight:500;width:max-content} +details.team .rollout{grid-template-columns:minmax(0,1fr)} +.recent{margin-top:56px}.recent h2{font-size:26px;margin:0 0 18px} +/* changelog */ +.toolbar{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:24px 0} +.search{flex:1 1 240px;min-width:0;border:1px solid var(--line);background:var(--card);color:var(--fg);border-radius:10px;padding:10px 14px;font:inherit;font-size:15px} +.search:focus{outline:2px solid var(--brand);outline-offset:-1px;border-color:transparent} +.cl-plugin+.cl-plugin{margin-top:48px} +.cl-head{display:flex;align-items:center;gap:10px;margin-bottom:16px}.cl-head h2{margin:0;font-size:24px}.cl-head h2 a{color:var(--fg)} +.chip{display:inline-block;font-size:12px;font-weight:600;border-radius:999px;padding:3px 11px;border:1px solid transparent;background:var(--surface);color:var(--muted)} +.chip-added{background:var(--success-soft);color:var(--success)}.chip-changed{background:var(--brand-soft);color:var(--brand-strong)} +.chip-fixed{background:var(--attention-soft);color:var(--attention)}.chip-removed,.chip-security,.chip-deprecated{background:var(--destructive-soft);color:var(--destructive)} +button.filter{cursor:pointer;font-family:inherit} +button.filter[aria-pressed="true"]{border-color:currentColor;box-shadow:0 0 0 1px currentColor inset} +.timeline{position:relative;padding-left:24px} +.timeline:before{content:"";position:absolute;left:5px;top:8px;bottom:8px;width:2px;background:var(--line)} +.release{position:relative;background:var(--card);border:1px solid var(--line);border-radius:var(--radius);padding:16px 22px;margin-bottom:14px} +.release:before{content:"";position:absolute;left:-24px;top:23px;width:12px;height:12px;border-radius:50%;background:var(--bg);border:2px solid var(--brand)} +.release:target{border-color:var(--brand);box-shadow:0 0 0 3px var(--brand-soft)} +.rel-head{display:flex;flex-wrap:wrap;align-items:center;gap:10px;cursor:pointer} +.rel-head h3{margin:0;font-size:19px} +.rel-head time{color:var(--muted);font-size:14px} +.rel-head .gh{margin-left:auto;font-size:14px} +.anchor{opacity:0;margin-left:-14px;width:14px;display:inline-block;color:var(--muted)} +.rel-head h3:hover .anchor{opacity:1} +.fold{border:0;background:none;color:var(--muted);width:24px;height:24px;margin-left:-6px;border-radius:6px;cursor:pointer;display:grid;place-items:center;padding:0} +.fold:before{content:"";width:7px;height:7px;border-right:2px solid currentColor;border-bottom:2px solid currentColor;transform:rotate(45deg);margin-top:-3px;transition:transform .15s} +.fold:hover{background:var(--surface);color:var(--fg)} +.release.collapsed .fold:before{transform:rotate(-45deg);margin-top:0;margin-left:-3px} +.release.collapsed .rel-body{display:none} +.kind h4{margin:14px 0 6px}.kind ul{margin:0;padding-left:20px}.kind li{margin:5px 0}.kind li::marker{color:var(--muted)} +a.pr{font-size:12px;font-weight:600;background:var(--brand-soft);border-radius:999px;padding:1px 8px} +mark{background:#ffe58a;color:#0a0a0a;border-radius:3px;padding:0 1px} +.empty{display:none;text-align:center;color:var(--muted);padding:40px 0} +.hidden{display:none!important} +footer{border-top:1px solid var(--line);color:var(--muted);font-size:14px} +.foot{max-width:1160px;margin:0 auto;padding:24px 20px;display:flex;flex-wrap:wrap;gap:8px 20px;align-items:center} +.foot .spacer{flex:1} +@media (max-width:860px){.doc{grid-template-columns:minmax(0,1fr);gap:0}.side{display:none}.split,.rollout{grid-template-columns:minmax(0,1fr)} +.brand span{display:none}.wrap{padding-top:24px}.release{padding:14px 16px}.rel-head .gh{margin-left:0}.search{flex-basis:100%}.top nav a{padding:6px 8px}} +@media (max-width:480px){.top-in{gap:8px}.top nav .gh-link{display:none}.top nav{gap:0}} +""" + +SHELL = r""" + + + + +{{TITLE}} + + + + + +{{HEAD}} + + + + +
    +{{LOGO}}Agent Plugins + +
    +
    +{{BODY}} +
    + + +{{SCRIPTS}} + + +""" + +JS = r""" +(function(){ + var root=document.documentElement; + function save(k,v){try{localStorage.setItem(k,v)}catch(e){}} + document.getElementById("theme").onclick=function(){ + var cur=root.getAttribute("data-theme"),dark=cur?cur==="dark":matchMedia("(prefers-color-scheme: dark)").matches; + var next=dark?"light":"dark";root.setAttribute("data-theme",next);save("theme",next); + document.dispatchEvent(new Event("themechange"))}; + document.querySelectorAll(".copy").forEach(function(b){b.onclick=function(e){ + e.stopPropagation();var label=b.textContent; + var done=function(){b.textContent="Copied";setTimeout(function(){b.textContent=label},1500)}; + if(navigator.clipboard)navigator.clipboard.writeText(b.dataset.copy).then(done,function(){})}}); + // Relative dates, absolute on hover. + var now=Date.now();document.querySelectorAll("time[datetime]").forEach(function(el){ + var d=Math.floor((now-new Date(el.dateTime+"T00:00:00Z"))/864e5);if(isNaN(d)||d<0)return; + el.title=el.dateTime;el.textContent=d===0?"today":d===1?"yesterday":d<30?d+" days ago":el.dateTime}); + // Highlight the section in view in the sidebar. + var links={};document.querySelectorAll(".side a[href^='#']").forEach(function(a){links[a.getAttribute("href").slice(1)]=a}); + var targets=Object.keys(links).map(function(id){return document.getElementById(id)}).filter(Boolean); + if(targets.length&&"IntersectionObserver"in window){var io=new IntersectionObserver(function(es){es.forEach(function(e){ + if(e.isIntersecting){Object.keys(links).forEach(function(k){links[k].classList.remove("active")});links[e.target.id].classList.add("active")}})},{rootMargin:"-90px 0px -65% 0px"}); + targets.forEach(function(t){io.observe(t)})} + // Collapsible releases. + var rels=[].slice.call(document.querySelectorAll(".release")),foldAll=document.getElementById("foldall"); + window.setFold=function(r,closed){r.classList.toggle("collapsed",closed);var b=r.querySelector(".fold"); + b.setAttribute("aria-expanded",closed?"false":"true");b.setAttribute("aria-label",(closed?"Expand ":"Collapse ")+r.querySelector("h3").lastChild.textContent);syncAll()}; + function syncAll(){if(foldAll)foldAll.textContent=rels.every(function(r){return r.classList.contains("collapsed")})?"Expand all":"Collapse all"} + rels.forEach(function(r){r.querySelector(".rel-head").addEventListener("click",function(e){ + if(e.target.closest("a"))return;setFold(r,!r.classList.contains("collapsed"))})}); + if(foldAll)foldAll.onclick=function(){var close=foldAll.textContent==="Collapse all";rels.forEach(function(r){setFold(r,close)})}; + function openHash(){var r=location.hash&&document.getElementById(location.hash.slice(1));if(r&&r.classList.contains("release"))setFold(r,false)} + window.addEventListener("hashchange",openHash);openHash(); +})(); +""" + +CHANGELOG_JS = r""" +(function(){ + var q=document.getElementById("q"),empty=document.getElementById("empty"),active={}; + var links={};document.querySelectorAll(".side a").forEach(function(a){links[a.getAttribute("href").slice(1)]=a}); + var items=[].slice.call(document.querySelectorAll(".kind li"));items.forEach(function(li){li._html=li.innerHTML}); + function esc(s){return s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")} + // Wrap matches in , text nodes only, so links and code stay intact. + function highlight(node,re){[].slice.call(node.childNodes).forEach(function(n){ + if(n.nodeType===1){highlight(n,re);return} + if(n.nodeType!==3)return; + var parts=n.data.split(re);if(parts.length<2)return; + var frag=document.createDocumentFragment(); + parts.forEach(function(p,i){if(!p)return;if(i%2){var m=document.createElement("mark");m.textContent=p;frag.appendChild(m)}else frag.appendChild(document.createTextNode(p))}); + n.replaceWith(frag)})} + function apply(){ + var term=q.value.trim(),kinds=Object.keys(active).filter(function(k){return active[k]}),re=term?new RegExp("("+esc(term)+")","i"):null,shown=0; + items.forEach(function(li){ + var kindOk=!kinds.length||kinds.indexOf(li.closest(".kind").dataset.kind)>=0; + var textOk=!re||li.textContent.toLowerCase().indexOf(term.toLowerCase())>=0; + li.innerHTML=li._html; + if(re&&textOk)highlight(li,re); + li.classList.toggle("hidden",!(kindOk&&textOk))}); + document.querySelectorAll(".kind").forEach(function(s){s.classList.toggle("hidden",!s.querySelector("li:not(.hidden)"))}); + document.querySelectorAll(".release").forEach(function(r){var v=!!r.querySelector(".kind:not(.hidden)"); + r.classList.toggle("hidden",!v);if(links[r.id])links[r.id].classList.toggle("dim",!v); + if(v&&(term||kinds.length))setFold(r,false);if(v)shown++}); + document.querySelectorAll(".cl-plugin").forEach(function(s){s.classList.toggle("hidden",!s.querySelector(".release:not(.hidden)"))}); + empty.style.display=shown?"none":"block"} + q.addEventListener("input",apply); + document.querySelectorAll("button.filter").forEach(function(b){b.onclick=function(){ + active[b.dataset.kind]=!active[b.dataset.kind];b.setAttribute("aria-pressed",active[b.dataset.kind]?"true":"false");apply()}}); + document.getElementById("clear").onclick=function(e){e.preventDefault();q.value="";active={}; + document.querySelectorAll("button.filter").forEach(function(b){b.setAttribute("aria-pressed","false")});apply()}; + document.addEventListener("keydown",function(e){if(e.key==="/"&&document.activeElement!==q){e.preventDefault();q.focus()} + else if(e.key==="Escape"&&document.activeElement===q){q.value="";apply();q.blur()}}); +})(); +""" + +# Hand-drawn (Excalidraw-style) diagrams in the site's colors; redrawn when the theme flips. +DIAGRAM_JS = r""" +(function(){ + if(!window.mermaid)return; // CDN blocked: the diagram source stays readable as text + var blocks=[].slice.call(document.querySelectorAll("pre.mermaid")); + blocks.forEach(function(b){b.dataset.src=b.textContent}); + function css(v){return getComputedStyle(document.documentElement).getPropertyValue(v).trim()} + function draw(){ + blocks.forEach(function(b){b.removeAttribute("data-processed");b.textContent=b.dataset.src}); + mermaid.initialize({startOnLoad:false,look:"handDrawn",theme:"base",securityLevel:"strict", + fontFamily:"Kalam, var(--font)",flowchart:{curve:"basis"}, + themeVariables:{fontFamily:"Kalam, cursive",fontSize:"17px",background:css("--surface"), + primaryColor:css("--card"),primaryBorderColor:css("--primary"),primaryTextColor:css("--fg"), + secondaryColor:css("--brand-soft"),tertiaryColor:css("--surface"), + lineColor:css("--muted"),textColor:css("--fg"),edgeLabelBackground:css("--surface")}}); + mermaid.run({nodes:blocks}).catch(function(){})} + draw();document.addEventListener("themechange",draw); + matchMedia("(prefers-color-scheme: dark)").addEventListener("change",draw); +})(); +""" + + +def main(): + out = Path(sys.argv[1] if len(sys.argv) > 1 else "_site") + root = Path(sys.argv[2]).resolve() if len(sys.argv) > 2 else Path(__file__).resolve().parent.parent + market, plugins = load_plugins(root) + if not plugins: + sys.exit("no plugins found under %s/plugins" % root) + (out / "assets").mkdir(parents=True, exist_ok=True) + (out / "changelog").mkdir(exist_ok=True) + (out / "index.html").write_text(render_home(root, market, plugins), encoding="utf-8") + for p in plugins: + (out / p["dir"]).mkdir(exist_ok=True) + (out / p["dir"] / "index.html").write_text(render_plugin(root, p), encoding="utf-8") + (out / "changelog" / "index.html").write_text(render_changelog(root, plugins), encoding="utf-8") + (out / "feed.xml").write_text(render_feed(plugins), encoding="utf-8") + for a in (root / "site/assets").iterdir(): + (out / "assets" / a.name).write_bytes(a.read_bytes()) + (out / ".nojekyll").write_text("") + print("wrote %s (%d plugin page(s), %d release(s))" + % (out, len(plugins), sum(len(p["releases"]) for p in plugins))) + + +if __name__ == "__main__": + main() diff --git a/site/assets/linearb-logo.svg b/site/assets/linearb-logo.svg new file mode 100644 index 0000000..fb60116 --- /dev/null +++ b/site/assets/linearb-logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/site/assets/linearb-mark.svg b/site/assets/linearb-mark.svg new file mode 100644 index 0000000..ea3b5a4 --- /dev/null +++ b/site/assets/linearb-mark.svg @@ -0,0 +1,3 @@ + + + diff --git a/tests/site/build_test.sh b/tests/site/build_test.sh index 76a7899..11558a8 100755 --- a/tests/site/build_test.sh +++ b/tests/site/build_test.sh @@ -1,39 +1,71 @@ #!/usr/bin/env bash -# Changelog site: builds from the real CHANGELOGs, every release shows up, markup is escaped. +# Site: builds from the real repo, every plugin gets a page and every release shows up, a new plugin +# is picked up with no code change, and markup in READMEs/CHANGELOGs is escaped. set -uo pipefail ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +BUILD="$ROOT/scripts/build-site.py" pass=0; fail=0 check() { local name=$1; shift if "$@"; then pass=$((pass+1)); printf 'ok %s\n' "$name"; else fail=$((fail+1)); printf 'FAIL %s\n' "$name"; fi } +has() { grep -qF -- "$2" "$1"; } +lacks() { ! has "$1" "$2"; } W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT -"$ROOT/scripts/build-changelog-site.py" "$W/site" >/dev/null -check "index.html built" test -s "$W/site/index.html" -check "feed.xml is valid XML" python3 -c "import sys,xml.dom.minidom; xml.dom.minidom.parse(sys.argv[1])" "$W/site/feed.xml" -for cl in "$ROOT"/plugins/*/CHANGELOG.md; do - name="$(basename "$(dirname "$cl")")" +# The real repo. +"$BUILD" "$W/site" >/dev/null +for f in index.html changelog/index.html feed.xml assets/linearb-logo.svg .nojekyll; do + check "built $f" test -e "$W/site/$f" +done +check "feed.xml is valid XML" python3 -c "import sys,xml.dom.minidom; xml.dom.minidom.parse(sys.argv[1])" "$W/site/feed.xml" +for d in "$ROOT"/plugins/*/; do + name="$(basename "$d")" + check "$name has a page" test -s "$W/site/$name/index.html" + check "$name is on the home page" has "$W/site/index.html" "href=\"$name/\"" + check "$name managed settings enable it" has "$W/site/$name/index.html" ""$name@linearb-ai": true" while read -r v; do - check "$name $v on the page" grep -qF "id=\"$name-v${v//./-}\"" "$W/site/index.html" - done < <(sed -n 's/^## \[\([^]]*\)\].*/\1/p' "$cl") + check "$name $v in the changelog" has "$W/site/changelog/index.html" "id=\"$name-v${v//./-}\"" + done < <(sed -n 's/^## \[\([^]]*\)\].*/\1/p' "$d/CHANGELOG.md") done +check "README diagram rendered as a diagram" has "$W/site/agentic-advisor/index.html" '
    '
+check "README #anchors kept" has "$W/site/agentic-advisor/index.html" 'id="usage-telemetry-on-by-default"'
+
+# A second plugin appears with no code change; a plugin without a CHANGELOG still gets a page.
+F="$W/repo"; mkdir -p "$F"
+cp -R "$ROOT/.claude-plugin" "$ROOT/plugins" "$ROOT/site" "$F/"
+mkdir -p "$F/plugins/demo-tool/.claude-plugin" "$F/plugins/bare/.claude-plugin"
+printf '{"name":"demo-tool","version":"0.3.0","description":"Demo plugin."}\n' > "$F/plugins/demo-tool/.claude-plugin/plugin.json"
+cat > "$F/plugins/demo-tool/README.md" <<'MD'
+# demo-tool
+
+Does a demo thing .
+
+## Setup
+
+Run `demo ` and see [docs](docs/guide.md) or [bad](javascript:alert(1)).
 
-# Inline rendering: code and links render, raw HTML in an entry is escaped, non-http links stay text.
-cat > "$W/inline.py" <<'PY'
-import importlib.util, sys
-s = importlib.util.spec_from_file_location("b", sys.argv[1]); b = importlib.util.module_from_spec(s); s.loader.exec_module(b)
-print(b.inline("use `` and  ([#7](https://github.com/o/r/pull/7)) [bad](javascript:alert(1))"))
-PY
-out="$(python3 "$W/inline.py" "$ROOT/scripts/build-changelog-site.py")"
-has() { grep -qF -- "$1" <<<"$out"; }
-lacks() { ! has "$1"; }
-check "code span escaped" has '<x>'
-check "raw html escaped" lacks '.
 
 ## Setup
 
-Run `demo ` and see [docs](docs/guide.md) or [bad](javascript:alert(1)).
+Run `demo ` and see [docs](docs/guide.md), [shared](../shared.md), [root](/SECURITY.md) or [bad](javascript:alert(1)).
+
+## Setup
+
+Literal {{CSS}} stays text.
 
 | a | b |
 | --- | --- |
@@ -53,6 +58,10 @@ Run `demo ` and see [docs](docs/guide.md) or [bad](javascript:alert(1)).
 MD
 printf '# Changelog\n\n## [0.3.0] - 2026-10-01\n\n### Added\n\n- First release ([#1](https://github.com/o/r/pull/1))\n' > "$F/plugins/demo-tool/CHANGELOG.md"
 printf '{"name":"bare","version":"0.0.1"}\n' > "$F/plugins/bare/.claude-plugin/plugin.json"
+mkdir -p "$F/plugins/unlisted/.claude-plugin"
+printf '{"name":"unlisted","version":"9.9.9"}\n' > "$F/plugins/unlisted/.claude-plugin/plugin.json"
+jq '.plugins += [{"name":"demo-tool","source":"./plugins/demo-tool"},{"name":"bare","source":"./plugins/bare"}]' \
+  "$ROOT/.claude-plugin/marketplace.json" > "$F/.claude-plugin/marketplace.json"
 "$BUILD" "$W/site2" "$F" >/dev/null
 P="$W/site2/demo-tool/index.html"
 check "new plugin gets a page" test -s "$P"
@@ -65,6 +74,12 @@ check "table cell html escaped" lacks "$P" 'demo <x>'
 check "relative link points at the repo" has "$P" 'href="https://github.com/linear-b/agent-plugins/blob/main/plugins/demo-tool/docs/guide.md"'
 check "javascript: link not linked" lacks "$P" 'href="javascript'
+check "../ link keeps its parent path" has "$P" 'href="https://github.com/linear-b/agent-plugins/blob/main/plugins/shared.md"'
+check "/ link is repo-root relative" has "$P" 'href="https://github.com/linear-b/agent-plugins/blob/main/SECURITY.md"'
+check "duplicate headings get unique ids" has "$P" 'id="setup-1"'
+check "literal {{CSS}} in a README not substituted" has "$P" 'Literal {{CSS}} stays text'
+check "unpublished plugin folder gets no page" test ! -e "$W/site2/unlisted/index.html"
+check "unpublished plugin not on the home page" lacks "$W/site2/index.html" 'unlisted@linearb-ai'
 check "PR link becomes a pill without parens" has "$W/site2/changelog/index.html" '#1'
 
 echo "$pass passed, $fail failed"

From 151f050b30e6fac8b61272b21974ca11f3a5bec9 Mon Sep 17 00:00:00 2001
From: nivSwisa1 
Date: Mon, 12 Oct 2026 13:58:49 +0300
Subject: [PATCH 5/7] feat: header Install popover (Ask Claude or one terminal
 command)

Co-Authored-By: Claude Opus 5.5 
---
 scripts/build-site.py    | 93 ++++++++++++++++++++++++++++++++++------
 tests/site/build_test.sh |  2 +
 2 files changed, 82 insertions(+), 13 deletions(-)

diff --git a/scripts/build-site.py b/scripts/build-site.py
index 0492dc5..fcad00a 100755
--- a/scripts/build-site.py
+++ b/scripts/build-site.py
@@ -239,6 +239,42 @@ def rollout(names):
   %s""" % code_block(managed_settings(names))
 
 
+ICON_SPARK = ('')
+ICON_TERM = ('')
+ICON_COPY = ('')
+ICON_KEY = ('')
+
+
+def install_panel(names):
+    """Header 'Install' popover: a prompt for Claude Code, or one terminal command."""
+    ids = ["%s@%s" % (n, MARKETPLACE) for n in names]
+    repo = REPO_URL.split("github.com/")[1]
+    cmd = " && ".join(["claude plugin marketplace add %s" % repo] + ["claude plugin install %s" % i for i in ids])
+    what = names[0] if len(names) == 1 else "the LinearB plugins"
+    prompt = ("Install %s for me: run `claude plugin marketplace add %s`, then %s. "
+              "Then check whether LINEARB_API_TOKEN is set in my environment. If it isn't, tell me how to create one "
+              "(LinearB > Settings > API Tokens) and export it before restarting Claude Code."
+              % (what, repo, ", ".join("`claude plugin install %s`" % i for i in ids)))
+    return """""".format(key=ICON_KEY, spark=ICON_SPARK, term=ICON_TERM, copy=ICON_COPY,
+                 prompt=html.escape(prompt, quote=True), cmd=html.escape(cmd, quote=True), cmd_text=html.escape(cmd))
+
+
 def rel_id(p, r):
     return "%s-v%s" % (slug(p["name"]), slug(r["version"]))
 
@@ -278,12 +314,12 @@ def logo(root):
     return re.sub(r'\s(width|height)="[^"]*"', "", svg, count=2).replace("
 
    
 {{LOGO}}Agent Plugins
-
+
+{{INSTALL}}
 
    
 
    
 {{BODY}}
@@ -624,10 +685,16 @@ def render_feed(plugins):
     var cur=root.getAttribute("data-theme"),dark=cur?cur==="dark":matchMedia("(prefers-color-scheme: dark)").matches;
     var next=dark?"light":"dark";root.setAttribute("data-theme",next);save("theme",next);
     document.dispatchEvent(new Event("themechange"))};
-  document.querySelectorAll(".copy").forEach(function(b){b.onclick=function(e){
-    e.stopPropagation();var label=b.textContent;
-    var done=function(){b.textContent="Copied";setTimeout(function(){b.textContent=label},1500)};
+  document.querySelectorAll(".copy,.way-btn").forEach(function(b){b.onclick=function(e){
+    e.stopPropagation();var t=b.querySelector("span")||b,label=t.textContent;
+    var done=function(){t.textContent="Copied";setTimeout(function(){t.textContent=label},1500)};
     if(navigator.clipboard)navigator.clipboard.writeText(b.dataset.copy).then(done,function(){})}});
+  // Install popover.
+  var ib=document.getElementById("install-btn"),pop=document.getElementById("install-pop");
+  function openPop(o){pop.hidden=!o;ib.setAttribute("aria-expanded",o?"true":"false")}
+  ib.onclick=function(e){e.stopPropagation();openPop(pop.hidden)};
+  document.addEventListener("click",function(e){if(!pop.hidden&&!pop.contains(e.target))openPop(false)});
+  document.addEventListener("keydown",function(e){if(e.key==="Escape"&&!pop.hidden){openPop(false);ib.focus()}});
   // Relative dates, absolute on hover.
   var now=Date.now();document.querySelectorAll("time[datetime]").forEach(function(el){
     var d=Math.floor((now-new Date(el.dateTime+"T00:00:00Z"))/864e5);if(isNaN(d)||d<0)return;
diff --git a/tests/site/build_test.sh b/tests/site/build_test.sh
index 3ee629b..70f0f18 100755
--- a/tests/site/build_test.sh
+++ b/tests/site/build_test.sh
@@ -30,6 +30,8 @@ for src in $(jq -r '.plugins[].source' "$ROOT/.claude-plugin/marketplace.json");
     check "$name $v in the changelog" has "$W/site/changelog/index.html" "id=\"$name-v${v//./-}\""
   done < <(sed -n 's/^## \[\([^]]*\)\].*/\1/p' "$d/CHANGELOG.md")
 done
+check "install popover has the one-line command" has "$W/site/agentic-advisor/index.html" 'claude plugin marketplace add linear-b/agent-plugins && claude plugin install agentic-advisor@linearb-ai'
+check "install popover has the Claude prompt" has "$W/site/agentic-advisor/index.html" 'Install agentic-advisor for me'
 check "README diagram rendered as a diagram" has "$W/site/agentic-advisor/index.html" '
    '
 check "README #anchors kept" has "$W/site/agentic-advisor/index.html" 'id="usage-telemetry-on-by-default"'
 

From b1312225ae297e07dbed5b6a40fcb18af9dae5f8 Mon Sep 17 00:00:00 2001
From: nivSwisa1 
Date: Mon, 12 Oct 2026 14:04:55 +0300
Subject: [PATCH 6/7] docs: hand-drawn diagram of what agentic-advisor reads
 and reports

Shows every input (LinearB API, local git, the request), how the grade
is picked, and what is and isn't sent to the org. The README shows the
SVG; the site inlines it in the site theme with a phone layout.

Co-Authored-By: Claude Opus 5.5 
---
 .github/workflows/pages.yml           |   1 +
 docs/agentic-advisor/context.svg      | 111 +++++++++++++++++
 docs/agentic-advisor/context.tall.svg | 101 +++++++++++++++
 docs/agentic-advisor/draw.py          | 169 ++++++++++++++++++++++++++
 plugins/agentic-advisor/README.md     |   9 +-
 scripts/build-site.py                 |  56 +++++++--
 tests/site/build_test.sh              |  19 ++-
 7 files changed, 450 insertions(+), 16 deletions(-)
 create mode 100644 docs/agentic-advisor/context.svg
 create mode 100644 docs/agentic-advisor/context.tall.svg
 create mode 100644 docs/agentic-advisor/draw.py

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 33aacbe..5f42137 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -9,6 +9,7 @@ on:
       - plugins/*/CHANGELOG.md
       - plugins/*/README.md
       - site/**
+      - docs/**
       - plugins/*/.claude-plugin/plugin.json
       - .claude-plugin/marketplace.json
       - scripts/build-site.py
diff --git a/docs/agentic-advisor/context.svg b/docs/agentic-advisor/context.svg
new file mode 100644
index 0000000..809b6ba
--- /dev/null
+++ b/docs/agentic-advisor/context.svg
@@ -0,0 +1,111 @@
+
+What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history on the files you touch; and your request. Effort is the highest of the three. Only the grade and its metadata are reported to your own LinearB org; never code, file contents or full prompts.
+What LinearB looks at before your agent writes code
+
+
+
+You start a code task
+prompt, ticket key,or first file edit
+
+
+
+1. LinearB API (your org, read-only)
+repo health cached 24h · ticket only when a key is named
+
+
+
+Repo health
+rework % (30d)unreviewedmerges
+
+
+
+Incidents
+recent + open,org-wide
+
+
+
+Ticket
+type, priority,points, labels
+
+
+
+2. Local git (stays on your machine)
+only on fragile repos or sensitive files
+
+
+
+Files you'll touch
+lines rewritten (90d)fix / revert hints
+
+
+
+Ownership
+who owns the lines,is it your code?
+
+
+
+3. Your request (no calls)
+
+
+
+scope, breadth, tricky logic, blast radius
+
+
+
+
+
+
+
+
+
+
+
+
+Effort =
+highest of 1, 2, 3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+LOW
+lean, small diff
+
+
+
+MEDIUM
+normal care
+
+
+
+HIGH
+guards, tests, questions
+printed as one verdict line
+
+
+
+Reported to your own LinearB org (turn off: LINEARB_TELEMETRY=0)
+
+
+
+Sent
+grade + evidence, repo, branch, ticket key,your email, token counts
+
+
+
+Never sent
+source code, file contents,full prompts
+
+
+
+
diff --git a/docs/agentic-advisor/context.tall.svg b/docs/agentic-advisor/context.tall.svg
new file mode 100644
index 0000000..6e881bf
--- /dev/null
+++ b/docs/agentic-advisor/context.tall.svg
@@ -0,0 +1,101 @@
+
+What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history on the files you touch; and your request. Effort is the highest of the three. Only the grade and its metadata are reported to your own LinearB org; never code, file contents or full prompts.
+What LinearB looks at
+before your agent writes code
+
+
+
+You start a code task
+prompt, ticket key, or first file edit
+
+
+
+
+
+
+1. LinearB API (your org, read-only)
+repo health is cached for 24 hours
+
+
+
+Repo health
+rework % (30d)unreviewed merges
+
+
+
+Incidents
+recent + openorg-wide
+
+
+
+Ticket
+type, priority, points, labels(only when a key is named)
+
+
+
+2. Local git (stays on your machine)
+only on fragile repos or sensitive files
+
+
+
+Files you'll touch
+lines rewritten(90d), fix/revert
+
+
+
+Ownership
+who owns the lines,is it your code?
+
+
+
+3. Your request (no calls)
+
+
+
+scope, breadth, tricky logic, blast radius
+
+
+
+
+
+
+Effort =
+highest of 1, 2, 3
+
+
+
+
+
+
+LOW
+lean, small diff
+
+
+
+MEDIUM
+normal care
+
+
+
+HIGH
+guards + tests
+printed as one verdict line
+
+
+
+
+
+
+Reported to your own LinearB org
+turn off: LINEARB_TELEMETRY=0
+
+
+
+Sent
+grade + evidence, repo, branch,ticket key, your email, token counts
+
+
+
+Never sent
+source code, file contents, full prompts
+
diff --git a/docs/agentic-advisor/draw.py b/docs/agentic-advisor/draw.py
new file mode 100644
index 0000000..ca33eee
--- /dev/null
+++ b/docs/agentic-advisor/draw.py
@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Draw the agentic-advisor context diagram as hand-drawn SVGs. Usage: docs/agentic-advisor/draw.py docs/agentic-advisor"""
+import math
+import random
+import sys
+from html import escape
+
+OUT = sys.argv[1]
+
+# Fill/stroke per kind; var() picks up the site's theme, the fallback is used when shown as  (GitHub).
+KINDS = {
+    "lb": ("var(--brand-soft,#eef0ff)", "var(--brand,#5467ff)", "var(--brand-strong,#1831f4)"),
+    "git": ("var(--success-soft,#e7f6ec)", "var(--success,#16a34a)", "var(--success,#15803d)"),
+    "req": ("var(--dg-purple-soft,#f1ecff)", "var(--dg-purple,#7c5cff)", "var(--dg-purple,#6d28d9)"),
+    "warn": ("var(--attention-soft,#fef3e2)", "var(--attention,#b45309)", "var(--attention,#b45309)"),
+    "ok": ("var(--success-soft,#e7f6ec)", "var(--success,#16a34a)", "var(--success,#15803d)"),
+    "bad": ("var(--destructive-soft,#fce8ee)", "var(--destructive,#bf1245)", "var(--destructive,#bf1245)"),
+}
+FG, MUTED = "var(--fg,#0a0a0a)", "var(--muted,#61656c)"
+
+
+class Pen:
+    def __init__(self, seed):
+        self.r = random.Random(seed)
+        self.out = []
+
+    def j(self, a=1.6):
+        return self.r.uniform(-a, a)
+
+    def rough_rect(self, x, y, w, h, fill, stroke, sw=1.8, opacity=None):
+        if fill:
+            op = ' fill-opacity="%s"' % opacity if opacity else ""
+            self.out.append(''
+                            % (x, y, w, h, fill, op))
+        for _ in range(2):  # two loose passes, Excalidraw-style
+            p = [(x + self.j(), y + self.j()), (x + w + self.j(), y + self.j()),
+                 (x + w + self.j(), y + h + self.j()), (x + self.j(), y + h + self.j())]
+            d = "M%.1f %.1f " % (p[0][0] + 8, p[0][1])
+            for a, b in zip(p, p[1:] + p[:1]):
+                mx, my = (a[0] + b[0]) / 2 + self.j(1.2), (a[1] + b[1]) / 2 + self.j(1.2)
+                d += "L%.1f %.1f " % (mx, my)
+                d += "L%.1f %.1f " % (b[0] + self.j(0.8), b[1] + self.j(0.8))
+            self.out.append('' % (d, stroke or MUTED, sw))
+
+    def text(self, x, y, lines, size, color=FG, anchor="start", weight=None):
+        if isinstance(lines, str):
+            lines = [lines]
+        lh = size * 1.25
+        wt = ' font-weight="%s"' % weight if weight else ""
+        spans = "".join('%s' % (x, 0 if i == 0 else lh, escape(l))
+                        for i, l in enumerate(lines))
+        self.out.append('%s'
+                        % (x, y, size, anchor, color, wt, spans))
+
+    def box(self, x, y, w, h, kind, lines, size=19):
+        fill, stroke, _ = KINDS[kind]
+        self.rough_rect(x, y, w, h, fill, stroke)
+        lines = lines if isinstance(lines, list) else [lines]
+        lh = size * 1.25
+        top = y + h / 2 - (len(lines) - 1) * lh / 2 + size * 0.35
+        self.text(x + w / 2, top, lines[:1], size + 1, anchor="middle", weight="700")
+        if len(lines) > 1:
+            self.text(x + w / 2, top + lh, lines[1:], size, color=FG, anchor="middle")
+
+    def card(self, x, y, w, h, kind, lines, size=19):
+        _, stroke, _ = KINDS[kind]
+        self.rough_rect(x, y, w, h, "var(--card,#ffffff)", stroke)
+        lines = lines if isinstance(lines, list) else [lines]
+        lh = size * 1.25
+        top = y + h / 2 - (len(lines) - 1) * lh / 2 + size * 0.35
+        self.text(x + w / 2, top, lines[:1], size + 1, anchor="middle", weight="700")
+        if len(lines) > 1:
+            self.text(x + w / 2, top + lh, lines[1:], size, color=MUTED, anchor="middle")
+
+    def zone(self, x, y, w, h, kind, title, note=None):
+        fill, stroke, ink = KINDS[kind]
+        self.rough_rect(x, y, w, h, fill, stroke, sw=1.4)
+        self.text(x + 18, y + 32, title, 22, color=ink, weight="700")
+        if note:
+            self.text(x + 18, y + h - 14, note, 17, color=ink)
+
+    def arrow(self, pts, color=MUTED, dashed=False):
+        d = "M%.1f %.1f " % pts[0]
+        for p in pts[1:]:
+            d += "L%.1f %.1f " % (p[0] + self.j(0.6), p[1] + self.j(0.6))
+        dash = ' stroke-dasharray="7 7"' if dashed else ""
+        self.out.append(''
+                        % (d, color, dash))
+        (x1, y1), (x2, y2) = pts[-2], pts[-1]
+        a = math.atan2(y2 - y1, x2 - x1)
+        for s in (2.6, -2.6):
+            hx, hy = x2 - 13 * math.cos(a + s / 6), y2 - 13 * math.sin(a + s / 6)
+            self.out.append('' % (hx, hy, x2, y2, color))
+
+    def svg(self, w, h, title, cls):
+        return ('\n%s\n%s\n\n'
+                % (cls, w, h, escape(title, quote=True), escape(title), "\n".join(self.out)))
+
+
+TITLE = ("What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history on the files "
+         "you touch; and your request. Effort is the highest of the three. Only the grade and its metadata are "
+         "reported to your own LinearB org; never code, file contents or full prompts.")
+
+
+def wide():
+    p = Pen(7)
+    p.text(590, 40, "What LinearB looks at before your agent writes code", 30, anchor="middle", weight="700")
+    p.box(20, 330, 220, 130, "warn", ["You start a code task", "prompt, ticket key,", "or first file edit"], 18)
+    p.zone(290, 80, 560, 250, "lb", "1. LinearB API (your org, read-only)", "repo health cached 24h · ticket only when a key is named")
+    p.card(308, 130, 170, 145, "lb", ["Repo health", "rework % (30d)", "unreviewed", "merges"], 18)
+    p.card(493, 130, 170, 145, "lb", ["Incidents", "recent + open,", "org-wide"], 18)
+    p.card(678, 130, 155, 145, "lb", ["Ticket", "type, priority,", "points, labels"], 18)
+    p.zone(290, 350, 560, 220, "git", "2. Local git (stays on your machine)", "only on fragile repos or sensitive files")
+    p.card(308, 400, 255, 120, "git", ["Files you'll touch", "lines rewritten (90d)", "fix / revert hints"], 18)
+    p.card(578, 400, 255, 120, "git", ["Ownership", "who owns the lines,", "is it your code?"], 18)
+    p.zone(290, 590, 560, 125, "req", "3. Your request (no calls)")
+    p.card(308, 638, 525, 58, "req", ["scope, breadth, tricky logic, blast radius"], 18)
+    for (x, y) in ((290, 205), (290, 460), (290, 652)):
+        p.arrow([(240, 395), (x, y)])
+    p.box(905, 300, 255, 100, "warn", ["Effort =", "highest of 1, 2, 3"], 20)
+    for (x, y) in ((850, 205), (850, 460), (850, 652)):
+        p.arrow([(x, y), (905, 350)])
+    p.arrow([(1032, 400), (1032, 440)])
+    p.box(905, 440, 255, 56, "ok", ["LOW", "lean, small diff"], 17)
+    p.box(905, 506, 255, 56, "warn", ["MEDIUM", "normal care"], 17)
+    p.box(905, 572, 255, 66, "bad", ["HIGH", "guards, tests, questions"], 17)
+    p.text(1032, 665, "printed as one verdict line", 17, color=MUTED, anchor="middle")
+    p.zone(290, 740, 870, 150, "warn", "Reported to your own LinearB org (turn off: LINEARB_TELEMETRY=0)")
+    p.card(308, 788, 500, 84, "ok", ["Sent", "grade + evidence, repo, branch, ticket key,", "your email, token counts"], 17)
+    p.card(825, 788, 318, 84, "bad", ["Never sent", "source code, file contents,", "full prompts"], 17)
+    p.arrow([(1160, 605), (1185, 605), (1185, 760), (1162, 760)], color="var(--attention,#b45309)", dashed=True)
+    return p.svg(1200, 910, TITLE, "wide")
+
+
+def tall():
+    p = Pen(11)
+    p.text(300, 38, "What LinearB looks at", 30, anchor="middle", weight="700")
+    p.text(300, 70, "before your agent writes code", 20, color=MUTED, anchor="middle")
+    p.box(40, 95, 520, 80, "warn", ["You start a code task", "prompt, ticket key, or first file edit"], 19)
+    p.arrow([(300, 175), (300, 205)])
+    p.zone(20, 205, 560, 310, "lb", "1. LinearB API (your org, read-only)", "repo health is cached for 24 hours")
+    p.card(40, 255, 250, 115, "lb", ["Repo health", "rework % (30d)", "unreviewed merges"], 19)
+    p.card(310, 255, 250, 115, "lb", ["Incidents", "recent + open", "org-wide"], 19)
+    p.card(40, 385, 520, 85, "lb", ["Ticket", "type, priority, points, labels", "(only when a key is named)"], 18)
+    p.zone(20, 535, 560, 225, "git", "2. Local git (stays on your machine)", "only on fragile repos or sensitive files")
+    p.card(40, 585, 250, 125, "git", ["Files you'll touch", "lines rewritten", "(90d), fix/revert"], 19)
+    p.card(310, 585, 250, 125, "git", ["Ownership", "who owns the lines,", "is it your code?"], 19)
+    p.zone(20, 780, 560, 130, "req", "3. Your request (no calls)")
+    p.card(40, 830, 520, 60, "req", ["scope, breadth, tricky logic, blast radius"], 18)
+    p.arrow([(300, 910), (300, 940)])
+    p.box(130, 940, 340, 80, "warn", ["Effort =", "highest of 1, 2, 3"], 21)
+    p.arrow([(300, 1020), (300, 1050)])
+    p.box(20, 1050, 175, 80, "ok", ["LOW", "lean, small diff"], 18)
+    p.box(212, 1050, 175, 80, "warn", ["MEDIUM", "normal care"], 18)
+    p.box(404, 1050, 176, 80, "bad", ["HIGH", "guards + tests"], 18)
+    p.text(300, 1160, "printed as one verdict line", 18, color=MUTED, anchor="middle")
+    p.arrow([(300, 1172), (300, 1198)], color="var(--attention,#b45309)", dashed=True)
+    p.zone(20, 1200, 560, 300, "warn", "Reported to your own LinearB org", "turn off: LINEARB_TELEMETRY=0")
+    p.card(40, 1250, 520, 95, "ok", ["Sent", "grade + evidence, repo, branch,", "ticket key, your email, token counts"], 18)
+    p.card(40, 1360, 520, 90, "bad", ["Never sent", "source code, file contents, full prompts"], 18)
+    return p.svg(600, 1520, TITLE, "tall")
+
+
+open(OUT + "/context.svg", "w").write(wide())
+open(OUT + "/context.tall.svg", "w").write(tall())
+print("ok")
diff --git a/plugins/agentic-advisor/README.md b/plugins/agentic-advisor/README.md
index d4b606b..fae24f2 100644
--- a/plugins/agentic-advisor/README.md
+++ b/plugins/agentic-advisor/README.md
@@ -23,14 +23,7 @@ The agent prints a one-line verdict before writing code, e.g.:
 
 ## How it decides
 
-```mermaid
-flowchart LR
-    T[Code task starts] --> X{Trivial edit?}
-    X -- yes --> LOW[LOW effort]
-    X -- no --> R[Repo health
    LinearB API] & K[Task + ticket
    from the prompt] & F[Changed files
    git history, when fragile]
-    R & K & F --> M[Effort =
    highest of the three]
-    M --> V[Verdict line,
    then the code]
-```
+![What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history; your request. Only the grade is reported to your org, never code or prompts.](../../docs/agentic-advisor/context.svg)
 
 - **Effort bands** match LinearB's own rework benchmark: ELITE <3% / STRONG 3–6% → **LOW**; FAIR 6–7% → **MEDIUM**; NEEDS FOCUS >7% → **HIGH**. Effort = the highest-firing signal (rework, unreviewed merges, or a recent serious incident).
 - **Task complexity:** the request itself is graded too (scope, breadth, tricky logic, blast radius), so a demanding change in a calm repo still gets real care. If the prompt or branch names a ticket, its type, priority and estimate from LinearB count too (a Highest-priority bug raises the grade). The final effort is the highest of repo health, task complexity and (when it runs) phase 2.
diff --git a/scripts/build-site.py b/scripts/build-site.py
index fcad00a..7c3b635 100755
--- a/scripts/build-site.py
+++ b/scripts/build-site.py
@@ -72,7 +72,17 @@ def keep_code(m):
         codes.append("" + html.escape(m.group(1)) + "")
         return "\x00%d\x00" % (len(codes) - 1)
 
+    def keep_img(m):
+        url = html.unescape(m.group(2))
+        if link_base and not re.match(r"^[a-z][a-z0-9+.-]*:", url, re.I):
+            url = urljoin(link_base, url) + "?raw=1"
+        elif not re.match(r"^https://", url):
+            return html.escape(m.group(1))
+        codes.append('%s' % (html.escape(url, quote=True), html.escape(m.group(1), quote=True)))
+        return "\x00%d\x00" % (len(codes) - 1)
+
     s = re.sub(r"`([^`]+)`", keep_code, md)
+    s = re.sub(r"!\[([^\]]*)\]\(([^)\s]+)\)", keep_img, s)
     s = html.escape(s)
 
     def link(m):
@@ -92,7 +102,27 @@ def link(m):
     return re.sub(r"\x00(\d+)\x00", lambda m: codes[int(m.group(1))], s)
 
 
-def markdown(text, link_base=None):
+def figure(src, alt, src_dir, root):
+    """A README's own SVG, inlined so it takes the site's theme; a sibling .tall.svg is the phone layout."""
+    if not src_dir or re.match(r"^[a-z][a-z0-9+.-]*:", src, re.I) or not src.endswith(".svg"):
+        return None
+    path = (src_dir / src).resolve()
+    if not path.is_file() or root.resolve() not in path.parents:
+        return None
+    out = []
+    for f, cls in ((path, "wide"), (path.with_name(path.stem + ".tall.svg"), "tall")):
+        if not f.is_file():
+            continue
+        svg = re.sub(r"<\?xml[^>]*>\s*", "", f.read_text())
+        if re.search(r"]*\sclass="', svg):
+            svg = svg.replace("%s' % (" has-tall" if len(out) > 1 else "", "".join(out))
+
+
+def markdown(text, link_base=None, src_dir=None, root=None):
     """README subset -> (html, [(id, h2 text)]). Raw HTML lines are dropped, never passed through."""
     lines, out, toc, i = text.splitlines(), [], [], 0
     il = lambda s: inline(s, link_base)  # noqa: E731
@@ -171,6 +201,12 @@ def is_block_start(l):
             tag = "ol" if ordered else "ul"
             out.append("<%s>%s" % (tag, "".join("
  • %s
    • " % il(x) for x in items), tag))
             continue
+        m = re.match(r"^!\[([^\]]*)\]\(([^)\s]+)\)\s*$", line)
+        fig = m and figure(m.group(2), m.group(1), src_dir, root)
+        if fig:
+            out.append(fig)
+            i += 1
+            continue
         para = []
         while i < len(lines) and not (para and is_block_start(lines[i])):
             para.append(lines[i].strip())
@@ -206,6 +242,7 @@ def load_plugins(root):
         plugins.append({
             "name": entry["name"],
             "dir": d.name,
+            "path": d,
             "version": meta.get("version", ""),
             "description": entry.get("description") or meta.get("description", ""),
             "readme": readme.read_text() if readme.is_file() else "",
@@ -379,7 +416,7 @@ def render_plugin(root, p):
     base = "../"
     lede, rest = split_readme(p["readme"])
     link_base = "%s/blob/main/plugins/%s/" % (REPO_URL, p["dir"])
-    body_html, toc = markdown(rest, link_base)
+    body_html, toc = markdown(rest, link_base, p["path"], root)
     toc_html = "".join('
  • %s
    • ' % (h, t) for h, t in toc)
     recent = "".join(render_release(p, r, i == 0, base) for i, r in enumerate(p["releases"][:3]))
     body = """
@@ -400,8 +437,9 @@ def render_plugin(root, p):
            install=install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), rollout=rollout([p["name"]]),
            pslug=slug(p["name"]), repo=REPO_URL, dir=p["dir"], body=body_html, recent=recent)
     head, scripts = "", ""
-    if 'class="mermaid"' in body_html:
+    if 'class="mermaid"' in body_html or 'class="figure' in body_html:
         head = ''
+    if 'class="mermaid"' in body_html:
         scripts = '' % (
             MERMAID_JS[0], MERMAID_JS[1], DIAGRAM_JS)
     return page(root, "%s · LinearB Agent Plugins" % p["name"], p["description"], body, base, "plugin", [p["name"]], head, scripts)
@@ -470,15 +508,15 @@ def render_feed(plugins):
 
 # LinearB "Buzz" design system (linweb): Outfit, slate primary, bright-blue brand, Buzz status colors.
 CSS = r"""
-:root{--claude:#c4623f;--claude-btn:#d97757;--claude-soft:#fbeee8;--bg:#ffffff;--surface:#f5f6fa;--card:#ffffff;--fg:#0a0a0a;--primary:#383f48;--muted:#61656c;--line:#e4e4e7;
+:root{--dg-purple:#7c5cff;--dg-purple-soft:#f1ecff;--claude:#c4623f;--claude-btn:#d97757;--claude-soft:#fbeee8;--bg:#ffffff;--surface:#f5f6fa;--card:#ffffff;--fg:#0a0a0a;--primary:#383f48;--muted:#61656c;--line:#e4e4e7;
 --brand:#5467ff;--brand-strong:#1831f4;--brand-soft:#eef0ff;--on-brand:#ffffff;--code:#f1f2f6;
 --success:#16a34a;--success-soft:#e7f6ec;--attention:#b45309;--attention-soft:#fef3e2;--destructive:#bf1245;--destructive-soft:#fce8ee;
 --font:"Outfit",ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
 --radius:12px;color-scheme:light}
-@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--claude:#e8957a;--claude-soft:#2a1d18;--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626;
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--dg-purple:#a18cff;--dg-purple-soft:#221a3d;--claude:#e8957a;--claude-soft:#2a1d18;--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626;
 --brand:#7c88ff;--brand-strong:#9aa3ff;--brand-soft:#1c1f45;--on-brand:#0a0a0a;--code:#1d1d21;
 --success:#4ade80;--success-soft:#11281a;--attention:#fbbf24;--attention-soft:#2e2209;--destructive:#fb7194;--destructive-soft:#331520;color-scheme:dark}}
-:root[data-theme="dark"]{--claude:#e8957a;--claude-soft:#2a1d18;--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626;
+:root[data-theme="dark"]{--dg-purple:#a18cff;--dg-purple-soft:#221a3d;--claude:#e8957a;--claude-soft:#2a1d18;--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626;
 --brand:#7c88ff;--brand-strong:#9aa3ff;--brand-soft:#1c1f45;--on-brand:#0a0a0a;--code:#1d1d21;
 --success:#4ade80;--success-soft:#11281a;--attention:#fbbf24;--attention-soft:#2e2209;--destructive:#fb7194;--destructive-soft:#331520;color-scheme:dark}
 *{box-sizing:border-box}
@@ -575,7 +613,7 @@ def render_feed(plugins):
 .doc-hero h1,.intro h1{font-size:clamp(32px,4vw,44px);margin:0;font-weight:600}
 .doc-hero .lede{margin-top:12px}
 .intro .lede{margin-top:8px}
-.prose>*{max-width:76ch}.prose>.diagram,.prose>.table{max-width:none}
+.prose>*{max-width:76ch}.prose>.diagram,.prose>.table,.prose>.figure{max-width:none}
 .prose h2{font-size:26px;margin:44px 0 12px;padding-top:4px}
 .prose h3{font-size:19px;margin:28px 0 8px}
 .prose p,.prose li{color:var(--fg)}
@@ -602,6 +640,10 @@ def render_feed(plugins):
 details.team{margin-top:14px;max-width:760px}
 details.team summary{cursor:pointer;color:var(--brand-strong);font-weight:500;width:max-content}
 details.team .rollout{grid-template-columns:minmax(0,1fr)}
+.figure{margin:24px 0}.figure svg{display:block;width:100%;height:auto}
+.figure .tall{display:none;max-width:600px;margin:0 auto}
+@media (max-width:700px){.figure.has-tall .wide{display:none}.figure.has-tall .tall{display:block}}
+.prose img{max-width:100%;height:auto}
 .recent{margin-top:56px}.recent h2{font-size:26px;margin:0 0 18px}
 /* changelog */
 .toolbar{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:24px 0}
diff --git a/tests/site/build_test.sh b/tests/site/build_test.sh
index 70f0f18..49e8a31 100755
--- a/tests/site/build_test.sh
+++ b/tests/site/build_test.sh
@@ -32,7 +32,8 @@ for src in $(jq -r '.plugins[].source' "$ROOT/.claude-plugin/marketplace.json");
 done
 check "install popover has the one-line command" has "$W/site/agentic-advisor/index.html" 'claude plugin marketplace add linear-b/agent-plugins && claude plugin install agentic-advisor@linearb-ai'
 check "install popover has the Claude prompt" has "$W/site/agentic-advisor/index.html" 'Install agentic-advisor for me'
-check "README diagram rendered as a diagram" has "$W/site/agentic-advisor/index.html" '
    '
+check "README diagram inlined with a phone layout" has "$W/site/agentic-advisor/index.html" '
    '
+check "diagram follows the site theme" has "$W/site/agentic-advisor/index.html" 'var(--brand-soft,#eef0ff)'
 check "README #anchors kept" has "$W/site/agentic-advisor/index.html" 'id="usage-telemetry-on-by-default"'
 
 # A plugin added to the marketplace appears with no code change; one without a CHANGELOG still builds;
@@ -54,10 +55,22 @@ Run `demo ` and see [docs](docs/guide.md), [shared](../shared.md), [root](/SE
 
 Literal {{CSS}} stays text.
 
+![flow](docs/flow.svg)
+
+![evil](docs/evil.svg)
+
+```mermaid
+flowchart LR
+  A --> B
+```
+
 | a | b |
 | --- | --- |
 | 1 |  |
 MD
+mkdir -p "$F/plugins/demo-tool/docs"
+printf '\n' > "$F/plugins/demo-tool/docs/flow.svg"
+printf '\n' > "$F/plugins/demo-tool/docs/evil.svg"
 printf '# Changelog\n\n## [0.3.0] - 2026-10-01\n\n### Added\n\n- First release ([#1](https://github.com/o/r/pull/1))\n' > "$F/plugins/demo-tool/CHANGELOG.md"
 printf '{"name":"bare","version":"0.0.1"}\n' > "$F/plugins/bare/.claude-plugin/plugin.json"
 mkdir -p "$F/plugins/unlisted/.claude-plugin"
@@ -82,6 +95,10 @@ check "duplicate headings get unique ids" has "$P" 'id="setup-1"'
 check "literal {{CSS}} in a README not substituted" has "$P" 'Literal {{CSS}} stays text'
 check "unpublished plugin folder gets no page" test ! -e "$W/site2/unlisted/index.html"
 check "unpublished plugin not on the home page" lacks "$W/site2/index.html" 'unlisted@linearb-ai'
+check "README svg inlined" has "$P" '
    '
 check "PR link becomes a pill without parens" has "$W/site2/changelog/index.html" '#1'
 
 echo "$pass passed, $fail failed"

From 16757a5014e763552bdd785e7760d3c469f9ddbc Mon Sep 17 00:00:00 2001
From: nivSwisa1 
Date: Mon, 12 Oct 2026 14:05:47 +0300
Subject: [PATCH 7/7] fix: address Copilot review (contrast, keyboard
 permalink, dead changelog links)

Co-Authored-By: Claude Opus 5.5 
---
 scripts/build-site.py    | 27 ++++++++++++++++-----------
 tests/site/build_test.sh |  2 ++
 2 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/scripts/build-site.py b/scripts/build-site.py
index 7c3b635..40ee3cf 100755
--- a/scripts/build-site.py
+++ b/scripts/build-site.py
@@ -371,10 +371,10 @@ def render_home(root, market, plugins):
                 if latest and latest["date"] else "")
         cards.append(
             '
    %s
    v%s
    '
-            '
    %s
    %s%s
    Read the docs'
-            'Changelog
    '
+            '
    %s
    %s%s
    Read the docs%s
    '
             % (p["dir"], html.escape(p["name"]), html.escape(p["version"]), html.escape(p["description"]), meta,
-               install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), p["dir"], slug(p["name"])))
+               install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), p["dir"],
+               'Changelog' % slug(p["name"]) if p["releases"] else ""))
     news = []
     for p, r in sorted(((p, r) for p in plugins for r in p["releases"][:3]),
                        key=lambda x: (x[1]["date"], x[1]["version"]), reverse=True)[:4]:
@@ -418,24 +418,29 @@ def render_plugin(root, p):
     link_base = "%s/blob/main/plugins/%s/" % (REPO_URL, p["dir"])
     body_html, toc = markdown(rest, link_base, p["path"], root)
     toc_html = "".join('
  • %s
    • ' % (h, t) for h, t in toc)
-    recent = "".join(render_release(p, r, i == 0, base) for i, r in enumerate(p["releases"][:3]))
+    recent, recent_toc, cl_btn = "", "", ""
+    if p["releases"]:  # a plugin without a CHANGELOG gets no changelog links
+        recent = ('
    Recent releases
    %s
    '
+                  'All releases →
    '
+                  % ("".join(render_release(p, r, i == 0, base) for i, r in enumerate(p["releases"][:3])), slug(p["name"])))
+        recent_toc = '
  • Recent releases
    • '
+        cl_btn = 'Changelog' % slug(p["name"])
     body = """
 
    
-
+
 
    
 """.format(toc=toc_html, name=html.escape(p["name"]), ver=html.escape(p["version"]), lede=inline(lede, link_base),
            install=install_box("/plugin install %s@%s" % (p["name"], MARKETPLACE)), rollout=rollout([p["name"]]),
-           pslug=slug(p["name"]), repo=REPO_URL, dir=p["dir"], body=body_html, recent=recent)
+           recent_toc=recent_toc, cl_btn=cl_btn, repo=REPO_URL, dir=p["dir"], body=body_html, recent=recent)
     head, scripts = "", ""
     if 'class="mermaid"' in body_html or 'class="figure' in body_html:
         head = ''
@@ -510,7 +515,7 @@ def render_feed(plugins):
 CSS = r"""
 :root{--dg-purple:#7c5cff;--dg-purple-soft:#f1ecff;--claude:#c4623f;--claude-btn:#d97757;--claude-soft:#fbeee8;--bg:#ffffff;--surface:#f5f6fa;--card:#ffffff;--fg:#0a0a0a;--primary:#383f48;--muted:#61656c;--line:#e4e4e7;
 --brand:#5467ff;--brand-strong:#1831f4;--brand-soft:#eef0ff;--on-brand:#ffffff;--code:#f1f2f6;
---success:#16a34a;--success-soft:#e7f6ec;--attention:#b45309;--attention-soft:#fef3e2;--destructive:#bf1245;--destructive-soft:#fce8ee;
+--success:#15803d;--success-soft:#e7f6ec;--attention:#b45309;--attention-soft:#fef3e2;--destructive:#bf1245;--destructive-soft:#fce8ee;
 --font:"Outfit",ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
 --radius:12px;color-scheme:light}
 @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--dg-purple:#a18cff;--dg-purple-soft:#221a3d;--claude:#e8957a;--claude-soft:#2a1d18;--bg:#0a0a0a;--surface:#111113;--card:#161618;--fg:#fafafa;--primary:#e4e4e7;--muted:#a1a1aa;--line:#262626;
@@ -666,7 +671,7 @@ def render_feed(plugins):
 .rel-head time{color:var(--muted);font-size:14px}
 .rel-head .gh{margin-left:auto;font-size:14px}
 .anchor{opacity:0;margin-left:-14px;width:14px;display:inline-block;color:var(--muted)}
-.rel-head h3:hover .anchor{opacity:1}
+.rel-head h3:hover .anchor,.anchor:focus-visible{opacity:1}
 .fold{border:0;background:none;color:var(--muted);width:24px;height:24px;margin-left:-6px;border-radius:6px;cursor:pointer;display:grid;place-items:center;padding:0}
 .fold:before{content:"";width:7px;height:7px;border-right:2px solid currentColor;border-bottom:2px solid currentColor;transform:rotate(45deg);margin-top:-3px;transition:transform .15s}
 .fold:hover{background:var(--surface);color:var(--fg)}
diff --git a/tests/site/build_test.sh b/tests/site/build_test.sh
index 49e8a31..80cccb0 100755
--- a/tests/site/build_test.sh
+++ b/tests/site/build_test.sh
@@ -84,6 +84,8 @@ check "new plugin on the home page" has "$W/site2/index.html" 'href="demo-tool/"
 check "new plugin in the changelog" has "$W/site2/changelog/index.html" 'id="demo-tool-v0-3-0"'
 check "new plugin in home managed settings" has "$W/site2/index.html" '"demo-tool@linearb-ai": true'
 check "plugin without README/CHANGELOG still builds" test -s "$W/site2/bare/index.html"
+check "no changelog link for a plugin without releases" lacks "$W/site2/bare/index.html" 'changelog/#bare'
+check "no home changelog button for a plugin without releases" lacks "$W/site2/index.html" 'changelog/#bare'
 check "README raw html escaped" lacks "$P" '