element of a deck page: the part its PDF is printed from.""" start, end = page.find("") if start < 0 or end < 0: fail("a deck page needs one

element") return page[start:end + len("

")] # Pages made from content nouns ------------------------------------------------------------------- def mark_kinds(sentence: str) -> str: """Colour the words nouns and verbs, as the site's key does: nouns blue, verbs rust.""" sentence = re.sub(r"\bnouns\b", 'nouns', text(sentence), count=1) return re.sub(r"\bverbs\b", 'verbs', sentence, count=1) def keep_together(escaped: str) -> str: """Keep hyphenated words, such as two-sided, on one line.""" return re.sub(r"\b(\w+(?:-\w+)+)\b", r'\1', escaped) def deck_card(deck: dict, prefix: str, ui: dict, level: int) -> str: """A deck's card: its cover as a live thumbnail, its title and its one-line summary.""" spec, cover = deck["spec"], deck["slides"][0] href = f"{prefix}decks/{deck['id']}/" return "\n".join([ '

', f'', '

', f'

{len(deck["slides"])} {text(ui["slides"])}

', f'{text(spec["title"])}', f'

{text(spec["page"]["summary"])}

', f'

' f'{text(ui["pdf_short"])}

', "

", "

", ]) def film_cuts(videos: dict) -> tuple[dict, str]: """The film's default cut, and the buttons that switch between cuts when there is more than one.""" cuts = videos["cuts"] for cut in cuts: for key in ("src", "captions", "poster"): if not (SITE / cut[key]).is_file(): fail(f"home.json: the {cut['id']} cut's {key} is missing: {cut[key]}") if cut.get("clean_src") and not (SITE / cut["clean_src"]).is_file(): fail(f"home.json: the {cut['id']} cut's clean_src is missing: {cut['clean_src']}") default = next((cut for cut in cuts if cut["id"] == videos["default"]), None) if default is None: fail(f"home.json: the default cut {videos['default']!r} is not one of the cuts") if len(cuts) < 2: return default, "" buttons = "".join( f'' for cut in cuts) cc_toggle = ( '' ) return default, f'' def other_cut_links(videos: dict, default: dict) -> str: """Without JavaScript the cut buttons stay hidden, so the other cuts are plain links to their files.""" return "".join( f' · {text(cut["tab"])}' for cut in videos["cuts"] if cut is not default) def use_anchor(name: str) -> str: """The id of a use case on the use cases page, from its name.""" return "use-" + re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") def film_made_ready(start: dict) -> bool: """The film's production page is linked only once its production trace noun exists and says it is final.""" noun = ROOT / start["film_made"]["requires"] return noun.is_file() and json.loads(noun.read_text(encoding="utf-8")).get("status") == "final" def render_home(nouns: Nouns) -> str: """The home page, as the Agora-Home board lays it out: the film first, then Start here with the two public sites, then the decks, then the use cases.""" home, ui = nouns.home, nouns.site["deck"] videos, start, uses = home["videos"], home["start"], home["uses"] video, selector = film_cuts(videos) others = other_cut_links(videos, video) if selector else "" cards = "\n".join(deck_card(deck, "", ui, 3) for deck in nouns.decks) doors = "".join( f'

' f'{MARK}{text(card["name"])}' f'{text(card["host"])}' f'{text(card["line"])}

' for card in start["cards"]) made = (f'

{text(start["film_made"]["label"])}

' if film_made_ready(start) else "") use_cards = "".join( f'

' + (f'{text(uses["live"])}' if item["home"].get("live_href") else "") + f'{text(item["home"]["title"])}{text(item["home"]["line"])}

' for item in nouns.uses["flagships"] if item.get("home")) main = "\n".join(filter(None, [ '

', f'

', '

', f'

", '', "

", selector, f'

{text(video["label"])}' + others + (f' · {text(videos["outline"]["label"])}' if videos.get("outline") else "") + (f' · {text(videos["tour"]["label"])}' if videos.get("tour") else "") + (f' · {text(videos["judges"]["label"])}' if videos.get("judges") else "") + "

", "

", f'

', '

', f'

{text(start["heading"])}

', (f'

{text(start["subline"])}

' if start.get("subline") else ""), f'

{doors}', made, "

", "

", '

', '

', f'

{text(home["decks_heading"])}

' f'{text(home["drafts"]["label"])}

', f'

\n{cards}\n', "

", "

", '

', '

', f'

{text(uses["heading"])}

' f'

{text(uses["lead"])}

', f'

{use_cards}', f'

{text(uses["all"])}

', "

", "

", ])) return page_shell(home["title"], home["description"], main, body_class="home") def page_head(heading: str, lead: str = "", crumb: tuple[str, str] | None = None, dateline: str = "") -> str: parts = ['

'] if crumb: parts.append(f'

{text(crumb[1])}

') parts.append(f"

{text(heading)}

") if lead: parts.append(f'

{text(lead)}

') if dateline: parts.append(f'

{text(dateline)}

') parts.append("

") return "\n".join(parts) def render_decks_index(nouns: Nouns) -> str: page, ui = nouns.decks_page, nouns.site["deck"] cards = "\n".join(deck_card(deck, "../", ui, 2) for deck in nouns.decks) main = "\n".join([ '

', page_head(page["heading"], page["lead"]), '

', f'

\n{cards}\n', f'

{text(page["earlier"])} ' f'{text(page["earlier_about"])}

', "

", "

", ]) return page_shell(page["title"], page["description"], main) def draft_item(item: dict, prefix: str, level: int) -> str: return (f'

' f'{text(item["title"])}

{text(item["about"])}

') def render_earlier(nouns: Nouns) -> str: page = nouns.drafts prefix = "../../" versions = {v["version"]: v for v in nouns.manifest["versions"]} info = page["deck_versions"] decks = [] for item in info["items"]: version = versions[item["version"]] links = [] for download in version["downloads"]: target = prefix + download["path"] if "path" in download else download["url"] links.append(f'{text(info["formats"][download["format"]])}') links += [f'{text(extra["label"])}' for extra in item.get("extra", [])] decks.append(f'

' f'{text(item["title"])}

' f'

{version["slides"]} {text(info["slides"])}

' f'

{text(item["about"])}

' f'

{" · ".join(links)}

') groups = [f'

' f'{text(info["heading"])}

{"".join(decks)}

'] for group in page["groups"]: items = "".join(draft_item(item, prefix, 3) for item in group["items"]) groups.append(f'

' f'{text(group["heading"])}

{items}

') notes = "".join(f'

{text(note["text"])} {text(note["label"])}

' if not note["href"].startswith("https://") else f'

{text(note["text"])} {text(note["label"])}

' for note in page["notes"]) main = "\n".join([ '

', page_head(page["heading"], page["lead"], ("../", page["crumb"]), page["dateline"]), '

', "\n".join(groups), f'

{notes}

', "

", "

", ]) return page_shell(page["title"], page["description"], main) def film_board(board: dict | None) -> str: """The storyboard image, linked to its full size, when the film noun has one.""" if not board: return "" if not (SITE / board["src"]).is_file(): fail(f"film.json: the storyboard is missing: {board['src']}") src = attr("../" + board["src"]) return (f'

' f'

{text(board["caption"])} {text(board["link"])}

') def render_film(nouns: Nouns) -> str: """The full film's transcript and scene descriptions: its acts, and every narration line, word for word as its captions give it, with its time and what is on screen. It is the film's text alternative, and says so, along with the note that there is no separate audio-described cut yet.""" film = nouns.film sections = [] for act in film["acts"]: rows = "".join( f'

{text(line["at"])}

' f'

{text(film["words_label"])}: ' f'{text(line["words"])}

' + (f'

{text(film["picture_label"])} ' f'{text(line["picture"])}

' if line["picture"] else "") + '

' for line in film["lines"] if line["act"] == act["id"]) sections.append(f'

' f'

{text(act["from"])}–{text(act["to"])} ' f'{text(act["name"])}

{rows}

') main = "\n".join([ '

', page_head(film["heading"], film["lead"], ("../", film["crumb"]), film["audio_description"]), '

', film_board(film.get("storyboard")), "\n".join(sections), f'

{text(film["note"])}' + (f' {text(film["evidence"]["label"])}' if film.get("evidence") else "") + "

", "

", ]) return page_shell(film["title"], film["description"], main) def render_storyboards(nouns: Nouns) -> str: page = nouns.drafts["storyboards_page"] prefix = "../" groups = {group["id"]: group for group in nouns.drafts["groups"]} sections = [] for key in page["groups"]: group = groups[key] items = "".join(draft_item(item, prefix, 3) for item in group["items"]) sections.append(f'

' f'{text(group["heading"])}

{items}

') main = "\n".join([ '

', page_head(page["heading"], page["lead"], ("../decks/earlier-drafts/", page["crumb"])), '

', "\n".join(sections), "

", "

", ]) return page_shell(page["title"], page["description"], main) def chips(items: list[str], kind: str) -> str: return f'

{text(item)}

" def pack_links(ids: list[str], library: dict, prefix: str, what: str) -> str: """A use case's library packs by title, each linking to its card on the library page. The titles come from the library noun, so a use case names its packs by id only.""" packs = {pack["id"]: pack for pack in library["packs"]} low, high = USE_PACKS if not isinstance(ids, list) or not low <= len(ids) <= high or len(set(ids)) != len(ids): fail(f"use-cases.json: {what} names {low} to {high} different library packs") unknown = [pack_id for pack_id in ids if pack_id not in packs] if unknown: fail(f"use-cases.json: {what} names packs the library does not have: {', '.join(unknown)}") return ('

' f'{text(packs[pack_id]["title"])}

") def use_terms(item: dict, uses: dict, library: dict, prefix: str) -> str: return ('

{text(uses["nouns_label"])}: {chips(item["nouns"], "noun")}
{text(uses["verbs_label"])}: {chips(item["verbs"], "verb")}
{text(uses["packs_label"])}: {pack_links(item["packs"], library, prefix, item["name"])}

") def use_href(href: str, prefix: str) -> str: """A link on the use cases page: an outside address as it is, a page of this site from the page's folder.""" return attr(href) if href.startswith("https://") else prefix + attr(href) def use_link(link: dict, prefix: str) -> str: return f'{text(link["label"])}{CHEVRON}' def flagship_card(item: dict, uses: dict, library: dict, prefix: str, lead: bool) -> str: """One flagship idea: its name, a line or two, example nouns and verbs, the library packs that hold them, and where to read more. The first one leads, with buttons. An idea has no status and no evidence.""" rest = f' {text(item["rest"])}' if item.get("rest") else "" if lead: links = "".join(f'' f'{text(link["label"])}' for n, link in enumerate(item["links"])) else: links = "".join(use_link(link, prefix) for link in item["links"]) detail = f'

{text(item["detail"])}

' if item.get("detail") else "" return "\n".join([ f'

', '

', f"

{text(item['name'])}{rest}

", f'

{text(item["line"])}

{detail}

', "

", use_terms(item, uses, library, prefix), f'

{links}

', "

", ]) def render_use_cases(nouns: Nouns) -> str: uses = nouns.uses prefix = "../" cards = [flagship_card(item, uses, nouns.library, prefix, lead=n == 0) for n, item in enumerate(uses["flagships"])] fields = uses["fields"] main = "\n".join([ '

', page_head(uses["heading"], uses["lead"]), '

', '

', "\n".join(cards), "", '

', '

', f'

{text(fields["name"])}

', f'

{text(fields["line"])}

', "

", chips(fields["items"], "plain"), f'

{use_link(fields["link"], prefix)}

', "

", "

", ]) return page_shell(uses["title"], uses["description"], main) def learn_part(key: str, heading: str, lead: str, body: str) -> str: """One section of the learning page: its heading, an optional lead, then its body.""" intro = f"

{text(lead)}

" if lead else "" return (f'

' f"{text(heading)}

{intro}

{body}

") def render_learning(nouns: Nouns) -> str: """The learning page: what continuous learning means here, the loop, the measured results with their evidence, the safety rules, the limits and how to run it. A page of Agora, not a surface of its own. Every word comes from site/content/learning.json, and every measured result links to public evidence. The loop's step numbers are a CSS counter, so the ordered list carries them.""" page = nouns.learning prefix = "../" meaning, loop, results, run = page["meaning"], page["loop"], page["results"], page["run"] for item in results["items"]: if not item.get("link", "").startswith("https://github.com/ta-amps/"): fail(f"learning.json: the {item['model']} result needs a public evidence link") means = "".join( f'

{text(meaning["kinds"][item["kind"]])}

' f'

{text(item["name"])}

{text(item["text"])}

' for item in meaning["items"]) steps = "".join( f'

{text(step["verb"])}

' f'

{text(loop["leaves"])} {text(step["noun"])}

' f'

{text(step["text"])}

{arrow("loop-arrow")}

' for step in loop["steps"]) cards = "".join( f'

{text(item["model"])}

' f'

{text(item["before"])}' f' {text(results["to"])} {arrow("result-arrow")}' f'{text(item["after"])}

' f'

{text(item["line"])}

' f'

{text(results["evidence"])} ' f'{text(item["source"])}

' for item in results["items"]) rules = "".join(f"

{text(rule['name'])}

{text(rule['text'])}

" for rule in page["safety"]["items"]) limits = "".join(f"

{text(limit)}

" for limit in page["limits"]["items"]) main = "\n".join([ '

', '

', f"

{text(page['heading'])}

", f'

{text(page["lead"])}

', f'

{text(page["dateline"])}

', f'

' f'{text(page["deck"]["label"])}

', "

", '

', learn_part("meaning", meaning["heading"], "", f'

{means}

{text(meaning["note"])}

'), learn_part("loop", loop["heading"], loop["lead"], f'

{steps}

{text(loop["back"])}

'), learn_part("results", results["heading"], results["lead"], f'

{cards}'), learn_part("safety", page["safety"]["heading"], page["safety"]["lead"], f'

{rules}'), learn_part("limits", page["limits"]["heading"], "", f'

{limits}'), '

', '

', f'

{text(run["heading"])}

', f'

{text(run["text"])}

', f'

{text(run["pack"])}

', "

", f'

{"".join(use_link(item, prefix) for item in run["links"])}

', "

", "

", ]) return page_shell(page["title"], page["description"], main) def human_date(iso: str) -> str: when = dt.datetime.fromisoformat(iso) return f"{when:%B} {when.day}, {when.year}" def counted(n: int, one: str, many: str, cls: str = "") -> str: """A count and its word. The number sits in its own element, so every word on the page is the noun's.""" klass = f' class="{cls}"' if cls else "" return f'{n:,} {text(one if n == 1 else many)}' def pack_card(pack: dict, words: dict) -> str: """One pack: its status, its title linking to its folder at the pinned commit, its one-line purpose, its noun and verb counts, and a badge when it ships its own code and tests. The whole card is the title's link.""" kinds = [words["status"][pack["status"]]] + ([words["kit"]] if pack["kit"] else []) badge = f'{CODE_GLYPH}{text(words["badge"])}' if pack["code"] else "" return "\n".join([ f'

', '

' + " ".join(f"{text(kind)}" for kind in kinds) + f" {badge}

", f'

{text(pack["title"])}

', f'

{text(pack["purpose"])}

', '

' + counted(pack["nouns"], words["noun"], words["nouns"], "noun-word") + " " + counted(pack["verbs"], words["verb"], words["verbs"], "verb-word") + f'

', "

", ]) def explorer_section(explorer: dict, ecosystem: dict, library: dict) -> str: ctrl = explorer["controls"] kind_opts = "".join( f'' for k in explorer["kinds"] ) + "".join( f'' for k in explorer["eco_kinds"] ) cat_opts = f'' + "".join( f'' for cat in library["categories"] ) + "".join( f'' for ecat in ecosystem["categories"] ) ceil_opts = "".join(f'' for c in explorer["ceilings"]) harn_opts = "".join(f'' for h in explorer["harnesses"]) return "\n".join([ '

', '

', f'

{text(explorer["heading"])}

', f'

{text(explorer["lead"])}

', f'

{text(explorer["proposal_note"])}

', "

", f'

', '', '', "

", '", '

', f'

{text(ctrl["noscript"])}

', '

', f'

', "

", ]) def harness_feeds_section(explorer: dict) -> str: hf = explorer["harness_feeds"] cards = "".join( '

' f'

{text(item["name"])}

' f'

{text(item["role"])}

' f'

{text(item["detail"])}

' "

" for item in hf["harnesses"] ) rules = "".join( '

' f'

{text(rule["mode"])}

' f'

{text(rule["when"])}

' f'

{text(rule["outcome"])}

' "

" for rule in hf["routing"]["rules"] ) return "\n".join([ '

', '

', f'

{text(hf["kicker"])}

', f'

{text(hf["heading"])}

', f'

{text(hf["lead"])}

', f'

{text(hf["status_note"])}

', "

", f'

{cards}', '

', f'

{text(hf["routing"]["heading"])}

', f'

{text(hf["routing"]["lead"])}

', f'

{rules}', "

", "

", ]) def ecosystem_banner_section(explorer: dict, ecosystem: dict) -> str: call = explorer["ecosystem_callout"] return "\n".join([ '", ]) def explorer_payload_script(explorer: dict, ecosystem: dict) -> str: payload = { "labels": explorer["labels"], "harnesses": {h["id"]: h["label"] for h in explorer["harnesses"] if h["id"] != "all"}, "ceilings": {c["id"]: c["label"] for c in explorer["ceilings"] if c["id"] != "all"}, "items": explorer["items"], "projects": ecosystem["projects"], } encoded = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).replace("<", "\\u003c") return f'' def render_library(nouns: Nouns) -> str: """The library page: every seed pack at one pinned commit of the library, grouped by category, under the totals measured at that commit, plus the interactive Task & Task-Object Explorer, Agent Harness Research Feeds, and the Meta Hackathon 2026 Ecosystem Explorer. Every word comes from library.json, explorer.json, and ecosystem-catalog.json. A category link shows only that category through :target without needing a script.""" library, explorer, ecosystem = nouns.library, nouns.explorer, nouns.ecosystem words, source, totals = library["words"], library["source"], library["totals"] packs = {pack["id"]: pack for pack in library["packs"]} commit = source["commit"] stats = "".join( f'

{totals[key]:,} ' f'{text(words["stats"][key])}

' for key, kind in (("packs", ""), ("nouns", "noun"), ("verbs", "verb"), ("worked_examples", ""), ("with_code", ""))) filters = [f'

{text(words["all"])} {totals["packs"]:,}' "

"] filters += [f'

{text(category["short"])} ' f'{len(category["packs"]):,}

' for category in library["categories"]] groups = [] for category in library["categories"]: key = category["id"] cards = "\n".join(pack_card(packs[pack_id], words) for pack_id in category["packs"]) groups.append("\n".join([ f'

', '

', f'

{text(category["name"])} ' f'{counted(len(category["packs"]), words["pack"], words["packs"])}

', f'

{text(category["intro"])}

', f'{text(words["show_all"])}', "

", f'

\n{cards}\n', (f'{text(words["see_all"])} ' f'{counted(len(category["packs"]), words["pack"], words["packs"])}' if len(category["packs"]) > LIBRARY_FIRST else ""), "

", "

", ])) on_show = ",".join(f'.library:has(#{category["id"]}:target) .lib-filter a[href="#{category["id"]}"]' for category in library["categories"]) tree = f"{LIBRARY_REPOSITORY}/tree/{commit}" receipt = f"{LIBRARY_REPOSITORY}/blob/{commit}/packs/VALIDATION.json" jump_links = "".join(use_link(item, "") for item in explorer["jump_links"]) ext_links = "".join(use_link(item, "../") for item in words["links"]) main = "\n".join([ '

', page_head(library["heading"], library["lead"], dateline=library["dateline"]), '

', '

', f'', f'

{stats}', '

', f'

{text(words["counted"])} {commit[:7]} · ' f'{human_date(source["committed_at"])}

', f'

{text(words["checked"])} {text(words["receipt"])}

', f'

{CODE_GLYPH}{text(words["badge"])} ' f'{text(words["badge_note"])}

', "

", f'

{jump_links}{ext_links}

', "

", explorer_section(explorer, ecosystem, library), harness_feeds_section(explorer), ecosystem_banner_section(explorer, ecosystem), '

', f'", "\n".join(groups), "

", "

", ]) return page_shell(library["title"], library["description"], main, extra_head=f"", extra_body=explorer_payload_script(explorer, ecosystem)) def deploy_code_block(code_id: str, commands: str, copy_labels: dict) -> str: return "\n".join([ '

', '

', f'', f'', "

", f'

{text(commands)}

', "

", ]) def render_deploy(nouns: Nouns) -> str: page = nouns.deploy prefix = prefix_for(SITE / "deploy" / "index.html") copy_labels = page["copy_labels"] quick = "".join(use_link(item, prefix) for item in page["quick_links"]) slices = "".join( f'

' f'

{text(item["badge"])}

' f'

{text(item["title"])}

' f'

{text(item["summary"])}

' f'

{text(item["when"])}

' + deploy_code_block(item["code_id"], item["commands"], copy_labels) + "

" for item in page["slices"]["items"] ) partners = page["partners"] partner_cards = "".join( f'

' f'

{text(card["name"])}

{text(card["kind"])}

' f'

{text(card["role"])}

' f'

{text(card["status_title"])}

{text(card["status_text"])}

' f'

{text(card["checked_title"])}

' + '

{text(c)}

" + f'

{text(card["try_heading"])}

' + deploy_code_block(card["code_id"], card["commands"], copy_labels) + f'

{text(card["receipt_label"])}

' + "

" for card in partners["cards"] ) partner_notes = "".join( f'

{text(note["heading"])}

{text(note["text"])}

' for note in partners["notes"] ) surfaces = "".join( '

' f'

{text(item["title"])}

' f'

{text(item["detail"])}

' + deploy_code_block(item["code_id"], item["commands"], copy_labels) + "

" for item in page["surfaces"]["items"] ) rules = "".join( f'

{text(rule["name"])}

{text(rule["text"])}

' for rule in page["security"]["items"] ) verify = page["verify"] main = "\n".join([ '

', '

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', f'

{text(page["dateline"])}

', f'

{quick}

', "

", '

', learn_part("slices", page["slices"]["heading"], page["slices"]["lead"], f'

{slices}'), learn_part("partners", partners["heading"], partners["lead"], f'

{partner_cards}

{partner_notes}'), learn_part("surfaces", page["surfaces"]["heading"], page["surfaces"]["lead"], f'

{surfaces}'), learn_part("security", page["security"]["heading"], page["security"]["lead"], f'

{rules}'), learn_part("verify", verify["heading"], verify["text"], deploy_code_block(verify["code_id"], verify["commands"], copy_labels)), "

", "

", ]) return page_shell(page["title"], page["description"], main) def live_doors(section: dict) -> list[dict]: """The doors of a section that a recorded live check showed answering. The build refuses a door without one.""" doors = section.get("doors", []) for door in doors: check = door.get("check") or {} if not (200 <= int(check.get("status", 0)) < 300 and re.fullmatch(r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ", check.get("checked_utc", ""))): fail(f"contribute: the door {door.get('endpoint')} has no passing live check") if not door["endpoint"].startswith("https://"): fail(f"contribute: the door {door['endpoint']} is not an https address") return doors def render_contribute(nouns: Nouns) -> str: """The contribute page: the ways in that work today, each door with the live check that showed it answering. A section with nothing that works yet is left out rather than promised.""" page = nouns.contribute prefix = prefix_for(SITE / "contribute" / "index.html") labels = page["copy_labels"] parts = [] for section in page["sections"]: doors = live_doors(section) body = [] if section.get("steps"): body.append('

{text(step)}

") if section.get("code"): body.append(deploy_code_block(section["code_id"], section["code"], labels)) if section.get("repos"): commands = "\n".join(section["clone_prefix"] + repo + ".git" for repo in section["repos"]) body.append(deploy_code_block(section["code_id"], commands, labels)) body.append(f'

' f'{text(section["source_label"])}

') if doors: rows = "".join( f'

{text(door["name"])}' f'{text(door["endpoint"])}' f'{text(door["what"])}' f'{text(page["checked_label"])} {text(door["check"]["checked_utc"])}: ' f'{text(door["check"]["method"])} {text(door["check"]["kind"])}, HTTP {int(door["check"]["status"])}

' for door in doors) body.append(f'

{rows}') if section.get("note"): body.append(f'

{text(section["note"])}

') if not body: continue # nothing in this section works yet, so the page does not show it parts.append(learn_part(section["id"], section["heading"], section["lead"], "\n".join(body))) main = "\n".join([ '

', '

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', f'

{text(page["dateline"])}

', "

", '

', *parts, "

", "

", ]) return page_shell(page["title"], page["description"], main) def render_llms(nouns: Nouns, built: set[Path]) -> str: """Agora's llms.txt, from its noun, the endpoints noun and the pages that exist. The build refuses a page the site does not have.""" page = nouns.llms origin = page["origin"].rstrip("/") + "/" lines = [f"# {page['title']}", "", f"> {page['summary']}", "", f"## {page['do_title']}", ""] lines += [f"- {item}" for item in page["do"]] lines += ["", f"## {page['pages_title']}", ""] for item in page["pages"]: target = SITE / item["path"] / "index.html" if target not in built and not target.is_file(): fail(f"llms.txt names a page the site does not have: /{item['path']}") lines.append(f"- [{item['label']}]({origin}{item['path']}): {item['what']}") lines += ["", f"## {page['endpoints_title']}", ""] for row in nouns.site["endpoints"]["rows"]: lines.append(f"- {row['name']}: {row['what']}. MCP {row['mcp']}; llms.txt {row['llms']}") lines += ["", f"## {page['source_title']}", ""] + [f"- {item}" for item in page["source"]] lines += ["", f"## {page['rules_title']}", ""] + [f"- {item}" for item in page["rules"]] lines += ["", f"## {page['brief_title']}", "", page["brief_note"], ""] return "\n".join(lines) FEED_TOP_ITEMS = 40 # memory systems listed under Everything gathered, most stars first def feed_hosted(feed: dict) -> bool: """The feed's scans ran on hosted Tessera, so its schedule is real and the decks may say so.""" return feed["source"].get("hosted") is True def short_hash(value: str) -> str: return f'{text(value[:12])}' def render_feed(nouns: Nouns) -> str: """The memory-systems feed page, from the feed's own data noun: where and when it scanned, the count with its exact search, which project fits which setup, the quoted benchmark claims and what was gathered.""" feed, words = nouns.feed, nouns.feed_words last, count = feed["last_run"], feed["count"] hosted = feed_hosted(feed) where = words["where_hosted"] if hosted else words["where_local"] facts = [(words["last_scan"], f'{text(last["at"])}'), (words["scan_id"], f'{text(last["scan_id"])}'), (words["receipt"], short_hash(last["receipt_hash"]))] if hosted: facts.insert(1, (words["schedule"], text(last["schedule"]))) facts.append((words["scans"], ", ".join(f'{text(scan["scan_id"])}' for scan in feed["scans"]))) fact_list = "".join(f"

{text(k)}

{v}

" for k, v in facts) secondary = "; ".join(f'{text(item["label"])}: {int(item["total_count"]):,}' for item in count.get("secondary", [])) candidates = {i["repo"]: i for i in feed["items"]} | {c["repo"]: c for c in feed["candidates"]} def candidate(repo: str) -> str: c = candidates.get(repo) if not c: fail(f"feed: setup names a candidate the data does not hold: {repo}") claims = "".join(f'

{text(cl["metric"])} ' f'{text(cl["quote"])} source

' for cl in c.get("claims", [])) claims = f'

{claims}' if claims else f'

{text(words["not_reported"])}

' meta = " · ".join(text(str(x)) for x in (f'{int(c["stars"]):,} {words["stars"]}', c.get("licence") or "", c.get("language") or "", c.get("hosting") or "", f'{words["last_commit"]} {str(c.get("last_commit_at") or "")[:10]}') if x) return (f'

{text(repo)}

{meta}

{claims}

') setups = "".join( f'

{text(setup["label"])} ' f'{int(setup["fit_count"]):,} {text(words["fits_count"])}

' f'

{"".join(candidate(repo) for repo in setup["candidates"])}

' for n, setup in enumerate(feed["setups"])) claim_rows = "".join( f'{text(cl["source"])}{text(cl["metric"])}' f'{text(cl["quote"])}' for cl in feed["claims"]) memory = sorted((i for i in feed["items"] if i.get("memory_system")), key=lambda i: -int(i.get("stars") or 0)) item_rows = "".join( f'{text(i["repo"])}{int(i.get("stars") or 0):,}' f'{text(i.get("licence") or "")}{text(i.get("language") or "")}' f'{text(str(i.get("last_commit_at") or "")[:10])}' for i in memory[:FEED_TOP_ITEMS]) papers = "".join(f'

{text(p["title"])} {text(p["arxiv_id"])} · ' f'{text(p["published"][:10])}

' for p in feed["papers"]) answer = feed["answer_example"] head = lambda cols: "" + "".join(f"{text(c)}" for c in cols) + "" main = "\n".join([ '

', page_head(words["heading"], words["lead"], dateline=where), '

', f'

{fact_list}', learn_part("count", words["count_heading"], "", f'

{int(count["total_count"]):,} {text(words["count_line"])} ' f'{text(count["window_utc"]["end"])}

' f'

{text(words["count_query"])}: {text(count["query"])}

' f'

{text(count["reading"])} {text(words["count_secondary"])} {secondary}. ' f'{text(words["count_response"])} {short_hash(count["response_sha256"])}

'), learn_part("fits", words["fits_heading"], words["fits_lead"], f'

{setups}

'), learn_part("ask", words["answer_heading"], "", f'

{text(answer["question"])}

{text(words["answer_label"])}

' f'

{text(answer["text"])}

'), learn_part("claims", words["claims_heading"], words["claims_lead"], f'

{head(words["claims_cols"])}{claim_rows}

'), learn_part("gathered", words["items_heading"], "", f'

{len(memory):,} {text(words["items_summary"])} {int(feed["item_count"]):,} ' f'{text(words["items_summary_tail"])}

' f'

{head(words["items_cols"])}{item_rows}

'), learn_part("papers", words["papers_heading"], "", f'

{papers}'), learn_part("how", words["how_heading"], "", '

{text(x)}

"), "

", "

", ]) return page_shell(words["title"], words["description"], main) def render_not_found(nouns: Nouns) -> str: """One shared not-found page, as the NotFound board draws it: the missing address, where things live now, and the promise the worker keeps by redirecting every listed old address.""" moved = nouns.moved page = moved["not_found"] prefix = PAGES_PREFIX grouped: dict[str, list[dict]] = {} for item in moved["pages"]: grouped.setdefault(item["to"], []).append(item) # one entry per new home, naming every old address items = [] for to, group in grouped.items(): olds = f" {text(page['and'])} ".join(f"/{text(item['from'])}" for item in group) items.append(f'

{text(group[0]["what"])}' f'{text(page["was"])} {olds}. {text(group[0]["note"])}

') items.append(f'

{text(page["home"])}{text(page["home_note"])}

') main = "\n".join([ '

', '

', f'

{text(page["code"])}

', f"

{text(page['heading'])}

", f'

{text(page["lead"])}

', f'

{"".join(items)}', f'

{text(page["redirect_note"])}

', "

", "

", ]) return page_shell(page["title"], "", main, robots="noindex") # How it works and evidence ----------------------------------------------------------------------- HOW_PAGE = SITE / "how-it-works" / "index.html" EVIDENCE_DIR = SITE / "evidence" EVIDENCE_PAGE = EVIDENCE_DIR / "index.html" EVIDENCE_NOUN = CONTENT / "evidence.json" REPO_EVIDENCE = ROOT / "evidence" # Labels that stamp a page instead of saying what works. Neither page, nor the run it replays, carries one. STAMPS = ("planned", "not yet", "coming soon", "illustration", "synthetic example") REPLAY_IDS = ("request", "build", "build-receipt", "review", "held") HEX64 = re.compile(r"[0-9a-f]{64}\Z") ISO_DAY = re.compile(r"\d{4}-\d{2}-\d{2}\Z") NAME_DAY = re.compile(r"(\d{4})-?(\d{2})-?(\d{2})(?:T\d{6}Z)?(?:\.json)?\Z") # A thin arrow with a head, as the design board draws its edges; the page's styles turn it to point down. RR_ARROW = ('') CHECK_ICON = ('') def strings_in(value) -> list[str]: if isinstance(value, str): return [value] items = value.values() if isinstance(value, dict) else value if isinstance(value, list) else [] return [found for item in items for found in strings_in(item)] def no_stamps(noun: dict, what: str) -> None: for value in strings_in(noun): for stamp in STAMPS: if stamp in value.lower(): fail(f"{what}: {stamp!r} stamps the page; say what works instead") def seq_ranges(seqs: list[int]) -> str: """Event numbers as runs: 1, 2, 3, 5 reads 1–3, 5.""" parts, start = [], None for i, n in enumerate(seqs): start = n if start is None else start if i + 1 == len(seqs) or seqs[i + 1] != n + 1: parts.append(str(start) if start == n else f"{start}–{n}") start = None return ", ".join(parts) def recorded_number(value) -> str: """A number exactly as its record writes it.""" return json.dumps(value) def check_real_run(run: dict) -> dict[str, dict]: """The replay noun as scripts/sync_real_run.py writes it. Returns its steps by id.""" facts = run["run"] if not (facts["made_up_data_only"] is True and facts["private_or_ngo_data_sent"] is False and facts["raw_credentials_included"] is False): fail("real-run.json: the replay shows only a synthetic run that sent no private data and no credential") steps = run["steps"] if [s["id"] for s in steps] != list(REPLAY_IDS) or [s["n"] for s in steps] != list(range(1, len(REPLAY_IDS) + 1)): fail("real-run.json: the replay needs its five steps, in order: " + ", ".join(REPLAY_IDS)) for step in steps: receipt = (SITE / step["receipt"]).resolve() if not HEX64.fullmatch(step["hash"]["value"]): fail(f"real-run.json: step {step['n']} needs a SHA-256") if not receipt.is_relative_to(SITE.resolve()) or not receipt.is_file(): fail(f"real-run.json: step {step['n']}'s receipt is not a file of the site") if step["hash"]["value"] not in receipt.read_text(encoding="utf-8"): fail(f"real-run.json: step {step['n']}'s hash is not in its receipt file") if not (step["trace"] or step["events"]): fail(f"real-run.json: step {step['n']} comes from no recorded event") for path in run["files"].values(): if not (SITE / path).is_file(): fail(f"real-run.json: {path} is not a file of the site") no_stamps(run, "real-run.json") return {step["id"]: step for step in steps} def how_toc(toc: dict) -> str: items = "".join(f'

{text(item["label"])}

' for item in toc["items"]) return f'' def how_why(why: dict) -> str: for line in why["lines"]: if line["kind"] not in {"noun", "verb"}: fail("how-it-works.json: a highlighted word is a noun or a verb colour") lines = "".join(f'{text(line["before"])}' f'{text(line["word"])}{text(line["after"])}' for line in why["lines"]) items = "".join(f'

{text(item["name"])}

{text(item["text"])}

' for item in why["items"]) under = why["under"] return "\n".join([ '

', '

', f'

{lines}

', f'

{items}', f'

{text(under["strong"])} {text(under["text"])}

', "

", "

", ]) def how_map(words: dict) -> str: def side(part: dict, kind: str) -> str: chips_html = "".join(f"

{text(item)}

" for item in part["items"]) return (f'

{text(part["name"])}

' f'

{text(part["label"])} {text(part["text"])}

' f'

{chips_html}

') notes = "".join(f"

{text(note['name'])} {text(note['text'])}

" for note in words["notes"]) return "\n".join([ '

', '

', f'', f'

{side(words["verbs"], "verb")}{side(words["nouns"], "noun")}

', f'

{notes}', "

", "

", ]) def state_track(steps: list[dict]) -> tuple[dict[str, dict[str, str]], dict[str, str]]: """Each task's state after each step that changed it, and each task's kind.""" track: dict[str, dict[str, str]] = {} kinds: dict[str, str] = {} for step in steps: for change in step["changes"]: track.setdefault(change["task"], {})[str(step["n"])] = change["states"][-1] kinds[change["task"]] = change["kind"] return track, kinds def replay_stage(words: dict, run: dict, steps: dict[str, dict]) -> str: """The run as the design board draws it: verbs as rust pills, nouns as blue tiles with their hashes, receipts, and the request held for a person. Each part carries the step it appears at, and each task its state after each step, for the replay script. Without the script the stage shows the run's end. The ordered list below says the same in words, so the stage is hidden from assistive technology.""" dw, facts = words["diagram"], run["run"] track, kinds = state_track(run["steps"]) task_of = {kind: task for task, kind in kinds.items()} for kind in ("request", "build", "review"): if kind not in task_of: fail(f"real-run.json: the replay needs a {kind} task") def final(task: str) -> str: states = track[task] return states[max(states, key=int)] def verb(kind: str, name: str, extra: str = "") -> str: task = task_of[kind] states = attr(json.dumps(track[task], separators=(",", ":"))) return (f'

{text(kind)}' f'{text(name)}{text(final(task))}

') def link(at: int) -> str: return f'{RR_ARROW}' def receipt(at: int, value: str) -> str: return (f'

{CHECK_ICON}' f'{text(dw["receipt"])}{text(value[:8])}…

') at = {key: step["n"] for key, step in steps.items()} nouns = "".join(f'

{text(noun["path"])}' f'{text(dw["sha"])} {text(noun["sha256"][:8])}…

' for noun in steps["build"]["nouns"]) verdict = steps["review"]["verdict"] return "\n".join([ '

', f'

' + verb("request", steps["request"]["request_label"], " rr-verb-request") + "

", f'

', '

', verb("build", facts["builder"]["program"]), link(at["build"]), f'

{nouns}', link(at["build-receipt"]), receipt(at["build-receipt"], steps["build-receipt"]["hash"]["value"]), "

", '

', verb("review", facts["reviewer"]["program"]), link(at["review"]), f'

{text(dw["verdict"])}: ' f'{text(verdict["verdict"])}{verdict["tests_run"]} {text(dw["tests"])} · ' f'{verdict["coverage_violations"]} {text(dw["violations"])}

', link(at["review"]), receipt(at["review"], steps["review"]["hash"]["value"]), "

", "

", f'

{RR_ARROW}

{text(dw["held"])}' f'{text(dw["held_text"])}

', "

", ]) def replay_step(step: dict, words: dict, prefix: str, kinds: dict[str, str]) -> str: """One step in words: when, what happened, the actor, the tasks, the state changes, its hash, the events it comes from and its receipt file.""" labels = words["labels"] tasks = "".join(f'

{text(task)} {text(kinds[task])}

' for task in step["tasks"]) changes = "".join( f'

{text(change["kind"])}{" (" + text(labels["new"]) + ")" if change["new"] else ""}: ' + " → ".join(text(state) for state in change["states"]) + "

" for change in step["changes"]) source = [] if step["trace"]: source.append(f'{text(labels["trace"])} {seq_ranges(step["trace"])}') if step["events"]: source.append(f'{text(labels["events"])} {seq_ranges(step["events"])}') if step["model_calls"]: source.append(f'{step["model_calls"]} {text(labels["calls"])}') rows = [(labels["actor"], text(step["actor"])), (labels["tasks"], f'

{tasks}')] if changes: rows.append((labels["state"], f'

{changes}')) rows.append((step["hash"]["label"], f'{text(step["hash"]["value"])}')) rows.append((labels["from"], " · ".join(source))) meta = "".join(f"

{text(name)}

{value}

" for name, value in rows) return (f'

' f'

{text(step["at_utc"][11:19])} ' f'{text(labels["utc"])}

' f'

{text(step["title"])}

' f'

{text(step["text"])}

' f'

{meta}' f'

{text(labels["open"])}' f"{CHEVRON}

") def how_run(words: dict, run: dict, prefix: str) -> str: steps = check_real_run(run) facts, fw, labels = run["run"], words["facts"], words["labels"] _, kinds = state_track(run["steps"]) spend = facts["spend"] started = facts["started_utc"] fact_rows = [ (fw["when"], f'{text(human_date(started))}, {text(started[11:19])} ' f'{text(labels["utc"])}'), (fw["where"], text(facts["fabric"])), (fw["revision"], f'' f'{text(facts["tessera_revision"])}'), (fw["builder"], f'{text(facts["builder"]["program"])} {text(facts["builder"]["version"])} · ' f'{text(fw["key"])} {text(facts["builder"]["key_id"])}'), (fw["reviewer"], f'{text(facts["reviewer"]["program"])} {text(facts["reviewer"]["version"])} · ' f'{text(fw["key"])} {text(facts["reviewer"]["key_id"])}'), (fw["model"], f'{text(facts["model"])}'), (fw["data"], text(fw["data_text"])), (fw["spend"], f'{recorded_number(spend["total_actual_usd"])} {text(fw["usd"])} {text(fw["actual"])} · ' f'{recorded_number(spend["total_conservative_usd"])} {text(fw["usd"])} {text(fw["conservative"])} ' f'· {text(fw["cap"])} {recorded_number(spend["cap_usd"])} {text(fw["usd"])}'), (fw["records"], f'{facts["trace_events"]} {text(fw["trace_events"])} · {facts["model_calls"]} ' f'{text(fw["model_calls"])}'), ] fact_list = "".join(f"

{text(name)}

{value}

" for name, value in fact_rows) legend = "".join(f'

{text(item["state"])} ' f'{text(item["text"])}

' for item in words["legend"]) files = {**run["files"], "receipt": run["receipt"]} file_links = "".join(use_link({"href": files[item["key"]], "label": item["label"]}, prefix) for item in words["files"]) step_items = "".join(replay_step(step, words, prefix, kinds) for step in run["steps"]) return "\n".join([ '

', '

', f'

{text(words["heading"])}

', f'

{text(words["run_label"])} {text(facts["id"])} · ' f'{text(words["from_receipts"])}

', "

", f'

{text(words["lead"])}

', f'

{fact_list}', replay_stage(words, run, steps), f'

{text(words["legend_label"])}

{legend}

', f'', f'

{step_items}', f'', f'

{text(words["check"])}

', f'

{text(words["files_label"])}

{file_links}

', "

", "

", ]) def how_underneath(words: dict) -> str: herma, tessera = words["herma"], words["tessera"] parts = " · ".join(text(item) for item in tessera["items"]) return "\n".join([ '

', '

', f'

{text(words["heading"])}

', '

', f'

{text(words["harness"])}

', f'{RR_ARROW}', f'

{text(herma["name"])}{text(herma["text"])}

', f'{RR_ARROW}', f'

{text(words["model"])}

', f'

{RR_ARROW}{text(words["edge"])}

', f'

{text(tessera["name"])}{parts}

', "

", f'

{text(words["note"])}

', f'

{text(words["run_note"])}

', "

", "

", ]) def how_meta(words: dict, run: dict, learning: dict, prefix: str) -> str: """The measured results the page names, from the learning noun by model: its numbers, line and source. A result whose evidence this site serves links to the served copy.""" items = {item["model"]: item for item in learning["results"]["items"]} cards = [] for pick in words["results"]: item = items.get(pick["model"]) if item is None: fail(f"how-it-works.json: learning.json has no result for {pick['model']}") if "served" in pick: if not (SITE / pick["served"]).is_file(): fail(f"how-it-works.json: {pick['served']} is not a file of the site") href = prefix + attr(pick["served"]) elif item["link"].startswith("https://github.com/ta-amps/"): href = attr(item["link"]) else: fail(f"how-it-works.json: the {pick['model']} result needs public evidence") cards.append( f'

{text(item["model"])}

' f'

{text(item["before"])}' f' {text(words["to"])} {RR_ARROW}' f'{text(item["after"])}

' f'

{text(item["line"])}

' f'

{text(words["evidence"])} ' f'{text(item["source"])}

') links = "".join(use_link(item, prefix) for item in words["links"]) return "\n".join([ '

', '

', f'

{text(words["heading"])}

', f'

{text(words["lead_before"])} {text(run["run"]["model"])} {text(words["lead_after"])}

', "

", f'

{"".join(cards)}', f'

{links}

', "

", "

", ]) def render_how_it_works(nouns: Nouns) -> str: """The how-it-works page, after the design board: why, the map, a real run replayed from its receipts, what sits underneath, and the Meta models. Every word comes from site/content/how-it-works.json; the run and its words from site/content/real-run.json; the results from site/content/learning.json. The replay script animates the stage and marks the current step; without it the page shows the run's end and every step in order.""" page = nouns.how no_stamps(page, "how-it-works.json") prefix = prefix_for(HOW_PAGE) main = "\n".join([ '

', '

', f"

{text(page['heading'])}

", f'

{text(page["lead"])}

', how_toc(page["toc"]), "

", how_why(page["why"]), how_map(page["map"]), how_run(page["run"], nouns.real_run, prefix), how_underneath(page["underneath"]), how_meta(page["meta"], nouns.real_run, nouns.learning, prefix), "

", ]) return page_shell(page["title"], page["description"], main, extra_head=f'', extra_body=f'') def folder_day(name: str) -> str | None: """The date a dated evidence name ends with, as YYYY-MM-DD.""" found = NAME_DAY.search(name) return f"{found.group(1)}-{found.group(2)}-{found.group(3)}" if found else None def same_files(a: Path, b: Path) -> bool: files_a = {p.relative_to(a).as_posix(): p for p in a.rglob("*") if p.is_file()} files_b = {p.relative_to(b).as_posix(): p for p in b.rglob("*") if p.is_file()} return set(files_a) == set(files_b) and all(files_a[k].read_bytes() == files_b[k].read_bytes() for k in files_a) def fill_evidence(noun: dict) -> dict: """The evidence noun with its measured parts filled from the files: each served folder's files and the last live check's answers. A served folder without a line, a line without a folder, an item of the repository's evidence/ without a line, a copy that differs from its served folder, or a saved answer that changed stops the build.""" page = json.loads(json.dumps(noun)) no_stamps(page, "evidence.json") served = page["served"]["folders"] ids = [folder["id"] for folder in served] on_disk = sorted(p.name for p in EVIDENCE_DIR.iterdir() if p.is_dir()) missing, extra = sorted(set(on_disk) - set(ids)), sorted(set(ids) - set(on_disk)) if missing: fail("evidence.json: describe each served evidence folder in one line: " + ", ".join(missing)) if extra or len(ids) != len(set(ids)): fail("evidence.json: these lines name no served folder, or name one twice: " + ", ".join(extra or ids)) days = [] for folder in served: if not ISO_DAY.fullmatch(folder["date"]) or folder_day(folder["id"]) not in {None, folder["date"]}: fail(f"evidence.json: {folder['id']} needs the date its name carries") days.append(folder["date"]) root = EVIDENCE_DIR / folder["id"] folder["files"] = [{"path": p.relative_to(root).as_posix(), "bytes": p.stat().st_size} for p in sorted(root.rglob("*")) if p.is_file()] if days != sorted(days, reverse=True): fail("evidence.json: served folders go newest first") items = page["source"]["items"] named = [item["path"].rstrip("/") for item in items] repo = sorted("evidence/" + p.name for p in REPO_EVIDENCE.iterdir()) if sorted(named) != repo: fail("evidence.json: give each item of the repository's evidence/ one line: " + ", ".join(sorted(set(repo) ^ set(named)))) for item in items: path = ROOT / item["path"] if folder_day(path.name) not in {None, item["date"]}: fail(f"evidence.json: {item['path']} needs the date its name carries") if "same_as" in item: if item["same_as"] not in ids or not same_files(path, EVIDENCE_DIR / item["same_as"]): fail(f"evidence.json: {item['path']} is no longer the same as its served folder; give it its own line") elif not item.get("line"): fail(f"evidence.json: {item['path']} needs its line") live = page["live"] record_path = SITE / live["record"] record = load_json(record_path) checks = [] for check in record["checks"]: fields = None if check["body"]: body = (record_path.parent / check["body"]).read_bytes() if sha256(body) != check["body_sha256"]: fail(f"evidence.json: the saved answer {check['body']} changed after the check") answer = json.loads(body) fields = {key: answer[key] for key in live["fields"] if key in answer} checks.append({"name": check["name"], "url": check["url"], "started_utc": check["started_utc"], "http_status": check["http_status"], "body": f"{Path(live['record']).parent.as_posix()}/{check['body']}" if check["body"] else None, "fields": fields}) live["snapshot"] = {"checked_at": record["checked_at"], "how": record["how"], "checks": checks} return page def evidence_text(nouns: Nouns) -> str: return json.dumps(fill_evidence(nouns.evidence), indent=2, ensure_ascii=False) + "\n" def size_of(n: int) -> str: return f"{n} B" if n < 1024 else f"{n / 1024:.1f} KB" if n < 1024 * 1024 else f"{n / 1024 / 1024:.1f} MB" def evidence_files(folder: dict, words: dict, prefix: str) -> str: """A served folder's files: the top-level ones in a row, each subfolder behind a disclosure.""" def one(path: str, size: int, base: str) -> str: return (f'

{text(path[len(base):])}' f' {size_of(size)}

') top = [f for f in folder["files"] if "/" not in f["path"]] groups: dict[str, list[dict]] = {} for f in folder["files"]: if "/" in f["path"]: groups.setdefault(f["path"].split("/", 1)[0], []).append(f) parts = [f'

{"".join(one(f["path"], f["bytes"], "") for f in top)}'] if top else [] for name, files in groups.items(): count = f'{len(files)} {text(words["one_file"] if len(files) == 1 else words["many_files"])}' parts.append(f'

{CHEVRON}{text(name)}/ · {count}

' f'

{"".join(one(f["path"], f["bytes"], name + "/") for f in files)}' "

") return "".join(parts) def render_evidence(nouns: Nouns) -> str: """The evidence page: the last live check with its time, every served evidence folder with its date, one line and its files, and the evidence that is only in the source download, named by path and never linked. Every word comes from site/content/evidence.json; the files and answers are filled from the files themselves.""" page = fill_evidence(nouns.evidence) prefix = prefix_for(EVIDENCE_PAGE) live, served, source = page["live"], page["served"], page["source"] snap = live["snapshot"] checked = snap["checked_at"] rows = [] for check in snap["checks"]: fields = check["fields"] or {} answer = " · ".join(f"{text(key)}: {text(value if isinstance(value, str) else json.dumps(value))}" for key, value in fields.items()) saved = (f'{text(live["saved"])}' if check["body"] else "") note = live["notes"].get(check["url"], "") rows.append( f'

' f'

{text(check["name"])}

{text(check["url"])}

' f'

{text(live["http"])} {check["http_status"]}' f'{" · " + answer if answer else ""}

' + (f'

{text(note)}

' if note else "") + (f'

{saved}

' if saved else "") + "

") folders = [] for folder in served["folders"]: link_html = f'

{use_link(folder["link"], prefix)}

' if "link" in folder else "" folders.append( f'

' f'

{text(human_date(folder["date"]))}' f' · {text(folder["id"])}/

' f'

{text(folder["title"])}

{text(folder["line"])}

' f'

{text(served["files"])}

' f'{evidence_files(folder, served, prefix)}

{link_html}

') items = [] for item in source["items"]: line = (f'{text(source["same"])} {text(item["same_as"])}/.' if "same_as" in item else text(item["line"])) items.append(f'

{text(human_date(item["date"]))}' f'

{text(item["path"])}

{line}

') main = "\n".join([ '

', '

', f"

{text(page['heading'])}

", f'

{text(page["lead"])}

', how_toc(page["toc"]), "

", '

', '

', f'

{text(live["heading"])}

', f'

{text(live["lead"])}

', f'

{text(live["checked"])} ' f'{text(human_date(checked))} {text(live["at"])} {text(checked[11:16])} {text(live["utc"])}

', f'

{"".join(rows)}', "

", '

', f'

{text(served["heading"])}

', f'

{text(served["lead"])}

', f'

{"".join(folders)}', "

", '

', f'

{text(source["heading"])}

', f'

{text(source["lead"])}

', f'

{use_link(source["link"], prefix)}

', f'

{"".join(items)}', "

", "

", ]) return page_shell(page["title"], page["description"], main, extra_head=f'') # Manifest --------------------------------------------------------------------------------------- def manifest_text(nouns: Nouns, pdfs: dict[str, dict]) -> str: """site/decks.json with the current decks listed before the frozen versions, which stay as they are.""" data = nouns.manifest previous = {entry["id"]: entry for entry in data.get("decks", [])} entries = [] for deck in nouns.decks: spec, deck_id = deck["spec"], deck["id"] entry = {"id": deck_id, "title": spec["title"], "date": spec["page"]["date"], "path": f"decks/{deck_id}/", "source": f"decks/{deck_id}/source/", "slides": len(deck["slides"]), "unbranded": True} if deck["claims"]: entry["claim_review"] = f"decks/{deck_id}/source/claims.json" entry["downloads"] = [pdfs[deck_id]] if deck_id in pdfs else previous.get(deck_id, {}).get("downloads", []) entries.append(entry) out: dict = {} for key, value in data.items(): if key == "decks": continue if key == "versions": out["decks"] = entries out[key] = value return json.dumps(out, indent=2, ensure_ascii=False) + "\n" # PDF -------------------------------------------------------------------------------------------- def render_pdfs(decks: list[dict], mains: dict[str, str]) -> dict[str, dict]: try: from playwright.sync_api import sync_playwright except ImportError: fail("--pdf needs the Playwright package (pip install playwright)") class Quiet(SimpleHTTPRequestHandler): def log_message(self, *args) -> None: # keep the build output readable pass server = ThreadingHTTPServer(("127.0.0.1", 0), partial(Quiet, directory=str(SITE))) thread = threading.Thread(target=server.serve_forever, daemon=True) thread.start() entries = {} try: with sync_playwright() as p: launch = {"executable_path": os.environ["CHROMIUM_PATH"]} if os.environ.get("CHROMIUM_PATH") else {} browser = p.chromium.launch(**launch) for deck in decks: page = browser.new_page(viewport={"width": CANVAS_W, "height": CANVAS_H}) page.goto(f"http://127.0.0.1:{server.server_port}/decks/{deck['id']}/", wait_until="networkidle") page.emulate_media(media="print") page.evaluate("document.fonts.ready") missing = page.evaluate("""() => ['Space Grotesk', 'IBM Plex Sans', 'JetBrains Mono'] .filter(f => !document.fonts.check('16px "' + f + '"'))""") if missing: fail("web fonts did not load: " + ", ".join(missing)) page.evaluate("title => { document.title = title; }", deck["spec"]["page"]["pdf_title"]) out = deck["folder"] / deck["pdf_name"] page.pdf(path=str(out), prefer_css_page_size=True, print_background=True, tagged=True, outline=False) page.close() data = out.read_bytes() entries[deck["id"]] = {"format": "pdf", "path": f"decks/{deck['id']}/{deck['pdf_name']}", "sha256": sha256(data), "bytes": len(data), "printed_from_main_sha256": mains[deck["id"]]} browser.close() finally: server.shutdown() return entries # October 31 judges, status, feeds hub, scenarios, and trust pages -------------------------------- def render_judges(nouns: Nouns) -> str: page = nouns.judges totals = nouns.library["totals"] commit_short = nouns.library["source"]["commit"][:12] steps = "".join( f'

{text(step["title"])}

{text(step["text"])}

' f'{text(step["link_label"])}

' for step in page["steps"] ) doors = "".join( f'

{text(item["name"])}

' f'{text(item["host"])}

{text(item["text"])}

' for item in page["doors"]["items"] ) real_rows = [] fmt_vars = { "packs": totals["packs"], "nouns": totals["nouns"], "verbs": totals["verbs"], "with_code": totals["with_code"], "commit_short": commit_short, } for row in page["real"]["rows"]: claim_str = row["claim_template"].format(**fmt_vars) if "claim_template" in row else row["claim"] state_str = row["state_template"].format(**fmt_vars) if "state_template" in row else row["state"] real_rows.append( f'{text(claim_str)}{text(state_str)}' f'{text(row["check_label"])}' ) real_cols = "".join(f'{text(col)}' for col in page["real"]["columns"]) repos_info = page["repos"] repos = "".join( f'

{text(item["slug"])}' f'

{text(item["role"])}

' f'

' f'{text(repos_info["github_label"])}' f'{text(repos_info["mirror_label"])}' f'{text(repos_info["tar_label"])}' f'

' for item in repos_info["items"] ) looks = "".join( f'

{text(item["heading"])}' f'{text(item["text"])}

' for item in page["looks"] ) main = "\n".join([ '

', '

', f'

{text(page["kicker"])}

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', '

' f'{text(page["tour_cta"]["label"])}' f'{text(page["film_cta"]["label"])}' '

', '

', f'

{text(page["steps_heading"])}

', f'

{steps}', '

', '

', f'

{text(page["doors"]["heading"])}

', f'

{doors}', '

', '

', f'

{text(page["real"]["heading"])}

', f'

{text(page["real"]["lead"])}

', f'

{real_cols}' f'{"".join(real_rows)}

', '

', f'

{text(repos_info["heading"])}

', f'

{text(repos_info["lead"])}

', f'

{repos}', '

', '

', f'

{looks}', '

', '

Security and accessibility notes: see /security/ ' 'and /accessibility/.

', '

', ]) return page_shell(page["title"], page["description"], main) def render_status_page(nouns: Nouns) -> str: page = nouns.status_page checks = load_json(SITE / "evidence" / "live-check-2026-10-31" / "checks.json") overall = page["overall"] cols = "".join(f'{text(col)}' for col in page["columns"]) rows = [] for svc in page["services"]: probe_attr = f' data-probe-url="{attr(svc["probe_url"])}"' if svc.get("probe_url") else "" rows.append( f'' f'{text(svc["name"])}{text(svc["host"])}' f'{text(svc["what"])}' f'' f'' f'{text(svc["state"])}' f'{text(svc["since"])}' f'' ) snap = page["snapshot_card"] notes = "".join( f'

{text(item["when"])} · {text(item["state"])}

' f'

{text(item["text"])}

' for item in page["notes_card"]["items"] ) legend = "".join( f'

' f'{text(item["label"])}

' for item in page["foot"]["legend"] ) foot = page["foot"] main = "\n".join([ '

', '

', f'

{text(page["kicker"])}

', f'

{text(page["heading"])}

', '

', f'', '

', f'

{text(page["services_heading"])}

', f'

{cols}' f'{"".join(rows)}

', '

', f'

{text(snap["heading"])}

', f'

{text(snap["lead"])}

', '

{text(snap["labels"]["last_run"])}: {text(checks["checked_at"])}
{text(snap["labels"]["result"])}: {text(snap["result_text"])}
{text(snap["labels"]["receipt"])}: {text(snap["link_label"])}

', '

', f'

{text(page["notes_card"]["heading"])}

', f'

{text(page["notes_card"]["lead"])}

', f'

{notes}', '

', '

', f'

{text(foot["agents_heading"])}

' f'

{text(foot["agents_text"])} /status.json

', f'

{text(foot["scope_heading"])}

' f'

{text(foot["scope_text"])}

', f'

{text(foot["legend_heading"])}

' f'

{legend}

', '

', ]) return page_shell(page["title"], page["description"], main, extra_body='') def render_status_json(nouns: Nouns) -> str: page = nouns.status_page checks = load_json(SITE / "evidence" / "live-check-2026-10-31" / "checks.json") payload = { "schema": "ta-amps.agora.status.v1", "ok": True, "surface": "agora", "recorded_check_at": checks["checked_at"], "evidence": "/evidence/live-check-2026-10-31/checks.json", "services": [ { "id": svc["id"], "name": svc["name"], "host": svc["host"], "what": svc["what"], "state": svc["state"], "kind": svc["kind"], "since": svc["since"], } for svc in page["services"] ], } return json.dumps(payload, indent=2, ensure_ascii=False) + "\n" def render_feeds_index(nouns: Nouns) -> str: page = nouns.feeds_index pills = "".join(f"

{text(p)}

" for p in page["pills"]) cats = page["categories"] cat0 = cats[0] cat_btns = "".join( f'' for i, cat in enumerate(cats) ) cols = page["columns"] thead = ( f'{text(cols[0])}{text(cols[1])}' f'{text(cat0["metric"])}' f'{text(cols[3])}{text(cols[4])}' ) init_rows = [r for r in cat0["rows"] if r["runs"] in ("local", "either")] or cat0["rows"] tbody_rows = "".join( f'{idx + 1}' f'{text(r["name"])}' f'' f'{text(r["signal"])}' f'{text(r["runs_label"])}' f'{text(r["license"])}' for idx, r in enumerate(init_rows) ) wf = page["which_fits"] questions = [] for q in wf["questions"]: opts = "".join( f'' for opt in q["options"] ) questions.append( f'

{text(q["label"])}

' f'

{opts}

' ) best0 = init_rows[0] foot_cards = "".join( f'

{text(card["heading"])}

{text(card["text"])}

' for card in page["foot_cards"] ) embed = { "categories": cats, "forced_local_why": wf["forced_local_why"], "default_why": wf["default_why"], } encoded = json.dumps(embed, ensure_ascii=False, separators=(",", ":")).replace("<", "\\u003c") main = "\n".join([ '

', '

', f'

{text(page["kicker"])}

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', f'

{pills}', '

', '

' f'Who runs it: {text(page["who_runs"])}' f'Each scan: {text(page["each_run"])}' f'Raw task objects: /feeds/index.json' '

', f'

{cat_btns}

', '

', f'

{text(cat0["name"])}

', f'

{text(cat0["schedule"])} · {text(cat0["last_run"])} · receipt {text(cat0["receipt"])}

', f'

{text(cat0["rank"])}

', f'

{thead}' f'{tbody_rows}

', f'

{text(cat0["detail_label"])}

', '

', f'

{text(wf["heading"])}

', f'

{text(wf["lead"])}

', *questions, '

' f'

{text(wf["best_fit_label"])}

' f'

{text(best0["name"])} ({text(best0["runs_label"])}, {text(best0["license"])})

' f'

{text(wf["default_why"])}

' '

', f'

{text(wf["agent_heading"])}

', f'

which_fits({{ feed: "{text(cat0["key"])}", data: "private", runs: "local" }})

', '

', f'

{foot_cards}', f'', '

', '

', ]) return page_shell(page["title"], page["description"], main, extra_body='') def render_scenarios(nouns: Nouns) -> str: page = nouns.scenarios pills = "".join(f"

{text(p)}

" for p in page["pills"]) tiles = "".join( f'' for tile in page["tiles"] ) max_reason = max(r["count"] for r in page["why_blocked"]["reasons"]) reasons = "".join( f'

{text(r["label"])}' f'{int(r["count"])}

' f'' f'{text(r["code"])}

' for r in page["why_blocked"]["reasons"] ) stakes = "".join( f'

{text(item["label"])}' f'{int(item["blocked"])}%

' f'

' for item in page["stakeholders"]["items"] ) dom = page["domains_section"] filters = "".join( f'' for f in dom["filters"] ) legend = "".join( f'

{text(item["label"])}

' for item in dom["legend"] ) cols = "".join(f'{text(col)}' for col in dom["columns"]) dom_rows = [] for name, kind, d, s, b in dom["domains"]: total_row = d + s + b dom_rows.append( f'' f'{text(name)}' f'' f'{int(d)}{int(s)}{int(b)}' f'' ) samples = page["samples"] sample_cards = "".join( f'

{text(item["verdict"])}' f'

{text(item["tuple"])}

' f'

{text(item["text"])}

' f'

{text(samples["became_label"])} {text(item["became"])}

' f'

{text(samples["human_label"])} {text(item["human"])}

' for item in samples["items"] ) foot = page["foot"] main = "\n".join([ '

', '

', f'

{text(page["kicker"])}

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', f'

{pills}', '

', '

', f'

{tiles}

', '

', f'

{text(page["why_blocked"]["heading"])}

', f'

{text(page["why_blocked"]["lead"])}

', f'

{reasons}', '

', '

', f'

{text(page["stakeholders"]["heading"])}

', f'

{text(page["stakeholders"]["lead"])}

', f'

{stakes}', '

', '

', f'

{text(dom["heading"])}

', f'

{filters}

', '

', f'

{legend}', f'

Showing {len(dom["domains"])} of {len(dom["domains"])} kinds of work.

', f'

{cols}' f'{"".join(dom_rows)}

', '

', f'

{text(samples["heading"])}

', f'

{sample_cards}', '

', '

' f'

{text(foot["text"])} {text(foot["pack_label"])}

' f'

Digest: {text(foot["digest_label"])} · ' f'SHA-256 {text(foot["receipt_sha256"])}

' '

', '

', ]) return page_shell(page["title"], page["description"], main, extra_body='') def render_trust_page(nouns: Nouns, kind: str) -> str: page = nouns.trust[kind] blocks = [] for idx, block in enumerate(page["blocks"]): items = "".join(f"

{text(item)}

" for item in block["items"]) extra = ( f'

{text(block["link_label"])}

' if block.get("link_href") else "" ) blocks.append( f'

' f'

{text(block["heading"])}

' f'

{items}{extra}

' ) sec_txt = ( f'

{text(page["security_txt_label"])}

' if page.get("security_txt_href") else "" ) main = "\n".join(filter(None, [ '

', '

', f'

{text(page["kicker"])}

', f'

{text(page["heading"])}

', f'

{text(page["lead"])}

', '

', f'

{"".join(blocks)}

', sec_txt, f'

{text(page["foot"])}

', '

', ])) return page_shell(page["title"], page["description"], main) def render_security_txt(nouns: Nouns) -> str: sec = nouns.trust["security_txt"] lines = [ f"# {sec['comment']}", f"Contact: {sec['contact']}", f"Expires: {sec['expires']}", f"Preferred-Languages: {sec['languages']}", ] for canon in sec["canonical"]: lines.append(f"Canonical: {canon}") lines.append(f"Policy: {sec['policy']}") return "\n".join(lines) + "\n" # Main --------------------------------------------------------------------------------------------- def unique_ids(path: Path, content: str) -> None: ids = re.findall(r'\sid="([^"]+)"', content) repeated = sorted({i for i in ids if ids.count(i) > 1}) if repeated: fail(f"{path.relative_to(ROOT)}: repeated ids {', '.join(repeated)}") def outputs_for(nouns: Nouns) -> dict[Path, str]: generated = {deck["page"]: render_deck(deck, nouns) for deck in nouns.decks} generated[SITE / "index.html"] = render_home(nouns) generated[DECKS / "index.html"] = render_decks_index(nouns) generated[DECKS / "earlier-drafts" / "index.html"] = render_earlier(nouns) generated[SITE / "use-cases" / "index.html"] = render_use_cases(nouns) generated[SITE / "storyboards" / "index.html"] = render_storyboards(nouns) generated[SITE / "film" / "index.html"] = render_film(nouns) generated[SITE / "learning" / "index.html"] = render_learning(nouns) generated[SITE / "library" / "index.html"] = render_library(nouns) generated[SITE / "deploy" / "index.html"] = render_deploy(nouns) generated[SITE / "contribute" / "index.html"] = render_contribute(nouns) generated[SITE / "feeds" / "index.html"] = render_feeds_index(nouns) generated[SITE / "feeds" / "memory-systems" / "index.html"] = render_feed(nouns) generated[SITE / "judges" / "index.html"] = render_judges(nouns) generated[SITE / "status" / "index.html"] = render_status_page(nouns) generated[SITE / "scenarios" / "index.html"] = render_scenarios(nouns) generated[SITE / "security" / "index.html"] = render_trust_page(nouns, "security") generated[SITE / "accessibility" / "index.html"] = render_trust_page(nouns, "accessibility") generated[HOW_PAGE] = render_how_it_works(nouns) generated[EVIDENCE_PAGE] = render_evidence(nouns) generated[SITE / "404.html"] = render_not_found(nouns) if set(generated) & nouns.frozen: fail("a frozen page is never written") written = sorted( p for p in SITE.rglob("*.html") if "source" not in p.relative_to(SITE).parts and p not in generated and p not in nouns.frozen and not (bool({"studio", "hub-3d", "compare"} & set(p.relative_to(SITE).parts)) and not {"", ""} & set(re.findall(r"", p.read_text(encoding="utf-8")))) ) outputs = {path: render_page(path, content, nouns) for path, content in generated.items()} for path in written: outputs[path] = render_page(path, path.read_text(encoding="utf-8"), nouns) for path, content in outputs.items(): unique_ids(path, content) outputs[SITE / "llms.txt"] = render_llms(nouns, set(outputs)) outputs[SITE / "status.json"] = render_status_json(nouns) outputs[SITE / ".well-known" / "security.txt"] = render_security_txt(nouns) return {path: plain_words(repoint(content, nouns.links)) for path, content in outputs.items()} def build(check: bool, pdf: bool) -> list[str]: nouns = Nouns() outputs = outputs_for(nouns) mains = {deck["id"]: sha256(main_of(outputs[deck["page"]]).encode("utf-8")) for deck in nouns.decks} pdfs: dict[str, dict] = {} if pdf and not check: for path, content in outputs.items(): path.parent.mkdir(parents=True, exist_ok=True) path.write_text(content, encoding="utf-8") pdfs = render_pdfs(nouns.decks, mains) outputs[MANIFEST] = manifest_text(nouns, pdfs) outputs[EVIDENCE_NOUN] = evidence_text(nouns) stale = [] for path, content in outputs.items(): current = path.read_text(encoding="utf-8") if path.exists() else None if current != content: stale.append(path.relative_to(ROOT).as_posix()) if not check: path.parent.mkdir(parents=True, exist_ok=True) path.write_text(content, encoding="utf-8") for entry in json.loads(outputs[MANIFEST])["decks"]: deck = next(d for d in nouns.decks if d["id"] == entry["id"]) if not entry["downloads"]: stale.append(f"{entry['path']}{deck['pdf_name']} (missing; run --pdf)") for download in entry["downloads"]: if download.get("printed_from_main_sha256") != mains[entry["id"]]: stale.append(download["path"] + " (printed from an older deck; run --pdf)") return stale def main(argv: list[str]) -> int: parser = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0]) parser.add_argument("--check", action="store_true", help="report stale outputs without writing") parser.add_argument("--pdf", action="store_true", help="also print every current deck to PDF") args = parser.parse_args(argv) try: stale = build(args.check, args.pdf) except BuildError as error: print(f"build_site: {error}", file=sys.stderr) return 2 if args.check: if stale: print("build_site: stale outputs, run python3 scripts/build_site.py:", file=sys.stderr) for item in stale: print(" " + item, file=sys.stderr) return 1 print("build_site: outputs are up to date") return 0 pdf_stale = [s for s in stale if s.endswith("--pdf)")] for item in stale: print(("needs --pdf: " if item in pdf_stale else "wrote ") + item) return 1 if pdf_stale else 0 if __name__ == "__main__": sys.exit(main(sys.argv[1:]))

{text(overall["title"])}

{text(snap["heading"])}

{text(page["notes_card"]["heading"])}

{text(foot["agents_heading"])}

{text(foot["scope_heading"])}

{text(foot["legend_heading"])}

{text(cat0["name"])}

{text(page["why_blocked"]["heading"])}

{text(page["stakeholders"]["heading"])}

{text(dom["heading"])}