#!/usr/bin/env python3 """Build the Noema documentation section as static HTML. Usage: python3 docs/site/build.py OUTPUT_DIR Sources: the repository's Markdown documents, the OpenAPI document, the UI screenshots, and the authored pages in docs/site/pages/*.md. A page file may pull a repository document in with a line `{{include path [demote]}}`. The output follows the dixon.cx page skeleton; the section is deliberately not linked from the site navigation and is marked noindex. """ import html import json import os import re import shutil import sys import markdown ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) PAGES = os.path.join(ROOT, "docs", "site", "pages") BASE = "/noema/" SITE = "https://dixon.cx" # Order, slug, title, summary. The page body comes from pages/.md. CHAPTERS = [ ("index", "Noema", "A persistent, inspectable artificial cognitive runtime: minds that remember, reason with evidence, say how sure they are, and can always show their working."), ("concepts", "Concepts and vocabulary", "Minds, events, epistemic kinds, memory kinds, beliefs, drives and the interpretation boundary."), ("architecture", "Architecture", "The daemon, the cognitive cycle, the storage model and the boundaries between deterministic code and language models."), ("configuration", "Cognitive configuration", "The per-mind settings that shape a mind: workspace capacity, attention weights, budgets and background cognition."), ("personality", "Identity and personality", "Versioned personalities, templates, traits and how they modulate attention and voice."), ("cognition", "The cognitive cycle", "Processes, attention scoring, the global workspace, executive dispatch, modes and metacognition."), ("memory", "Memory", "Episodic, semantic, procedural and autobiographical memory; retrieval, decay, consolidation and provenance."), ("beliefs", "Beliefs and evidence", "Evidence-derived scores, what the numbers mean, statuses including unknown, temporal scope, source reliability, contradictions and operator corrections."), ("epistemics", "Epistemic honesty", "The 0.2 review: assertions before beliefs, evidence provenance, honest scores, unknowns, time, reliability, reproducible replay and redaction."), ("conversation", "Conversation", "How a message becomes an observation, a perception, a response intent and finally language."), ("motivation", "Goals, drives and affect", "The goal tree, the closed drive set, rule-driven affect and how they bias attention."), ("predictions", "Predictions and calibration", "Explicit predictions with criteria, deterministic resolution, prediction error and calibration."), ("graph", "Relationship graph", "Entities, evidenced edges, merges and the canvas explorer."), ("llm-providers", "Language models", "Roles, providers (OpenAI-compatible, Anthropic, Ollama, Amazon Bedrock), per-mind routing, budgets, recorded calls, replay and versioned prompts."), ("capabilities", "Capabilities and policy", "The only path to action: ALLOW / ASK / DENY, approvals, locked capabilities and tool output as data."), ("integrations", "Integrations", "Research folder, git mirrors, Prometheus and signed webhooks as provenance-tagged observations."), ("dreaming", "Dreaming", "The opt-in idle mode: replay, association and speculative hypotheses that can never act."), ("snapshots-replay", "Snapshots, forks, replay and experiments", "Capturing state, branching minds, re-running cognition under a recorded runtime identity, and comparing forks that differ in one thing, including the model."), ("ui-tour", "Interface tour", "Every screen of the web interface, what it shows and what an operator does there."), ("api", "HTTP API", "Authentication, roles, the error envelope, streaming and every route."), ("cli", "Command line", "What an operator can do from a terminal: every command, with examples."), ("security", "Security and threat model", "Trust boundaries, secret handling, sessions, two-factor authentication and the threat-by-threat verification table."), ("privacy", "Privacy and redaction", "Append-only history and the one audited path that removes content while keeping its shape."), ("decisions", "Architecture decision records", "The recorded decisions and the alternatives they rejected."), ("development", "How it was built", "The phased plan, what each phase delivered, measured performance, release notes and changelog."), ("glossary", "Glossary", "Short definitions of every term used across the documentation."), ] STYLE = """ """ HEAD = """ {titletag} | Andy Dixon {style}

""" TAIL = """

""" LINK_MAP = { "ARCHITECTURE.md": "architecture", "SECURITY.md": "security", "THREAT_MODEL.md": "security", "PLAN.md": "development", "CONTRIBUTING.md": "development", "CHANGELOG.md": "development", "README.md": "index", "docs/interpretation.md": "concepts", "docs/configuration.md": "configuration", "docs/ENVIRONMENT.md": "configuration", "docs/personality.md": "personality", "docs/cognition.md": "cognition", "docs/memory.md": "memory", "docs/beliefs.md": "beliefs", "docs/conversation.md": "conversation", "docs/motivation.md": "motivation", "docs/predictions.md": "predictions", "docs/graph.md": "graph", "docs/llm-providers.md": "llm-providers", "docs/capabilities.md": "capabilities", "docs/integrations.md": "integrations", "docs/dreaming.md": "dreaming", "docs/snapshots-replay.md": "snapshots-replay", "docs/performance.md": "development", "docs/RELEASE_NOTES.md": "development", "docs/privacy.md": "privacy", "docs/epistemics.md": "epistemics", "docs/openapi.json": "api", "docs/adr": "decisions", } def read(path): with open(os.path.join(ROOT, path), encoding="utf-8") as f: return f.read() def demote(md, levels): out = [] fence = False for line in md.split("\n"): if line.startswith("```"): fence = not fence if not fence and line.startswith("#"): line = "#" * levels + line out.append(line) return "\n".join(out) def strip_h1(md): lines = md.split("\n") for i, l in enumerate(lines): if l.startswith("# "): return "\n".join(lines[:i] + lines[i + 1:]) return md def expand(md): """Resolve {{include path [demote N] [keep-title]}} and {{openapi}} directives.""" def inc(m): parts = m.group(1).split() path = parts[0] body = read(path) d = 0 keep = False for p in parts[1:]: if p.startswith("demote"): d = int(p.split("=")[1]) if "=" in p else 1 if p == "keep-title": keep = True if not keep: body = strip_h1(body) if d: body = demote(body, d) return body md = re.sub(r"\{\{include ([^}]+)\}\}", inc, md) md = md.replace("{{openapi}}", openapi_markdown()) return md def rewrite_links(html_text): def fix(m): href = m.group(1) if href.startswith(("http://", "https://", "#", "mailto:", "/")): return m.group(0) anchor = "" if "#" in href: href, anchor = href.split("#", 1) anchor = "#" + anchor if href.startswith("docs/screenshots/"): return 'href="' + BASE + "img/" + os.path.basename(href) + '"' for k, v in LINK_MAP.items(): if href == k or href.rstrip("/") == k or href.startswith(k + "/"): return 'href="' + BASE + v + anchor + '"' if href.endswith(".md"): slug = os.path.splitext(os.path.basename(href))[0] return 'href="' + BASE + slug + anchor + '"' return m.group(0) html_text = re.sub(r'href="([^"]+)"', fix, html_text) html_text = re.sub(r'src="docs/screenshots/([^"]+)"', r'src="' + BASE + r'img/\1"', html_text) return html_text def openapi_markdown(): doc = json.loads(read("internal/api/openapi.json")) groups = {} for path, ops in doc["paths"].items(): for method, op in ops.items(): tag = (op.get("tags") or ["root"])[0] groups.setdefault(tag, []).append((path, method.upper(), op)) out = [] for tag in sorted(groups): out.append(f"\n### {tag}\n") out.append("| Method | Path | Minimum role | Operation |\n|---|---|---|---|") for path, method, op in sorted(groups[tag], key=lambda x: (x[0], x[1])): role = str(op.get("x-required-role", "")).replace("(", "").replace(")", "") summary = op.get("summary", op.get("operationId", "")) out.append(f"| `{method}` | `{path}` | {role} | {summary} |") return "\n".join(out) + "\n" def render_page(idx, slug, title, summary, md): md = expand(md) conv = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "sane_lists", "attr_list", "def_list", "md_in_html"], extension_configs={"toc": {"toc_depth": "2-3"}}) body = conv.convert(md) body = rewrite_links(body) body = re.sub(r"", '

', body).replace("

", "") # Split into section boxes at h2 boundaries. parts = re.split(r"(?=

(.*?)

', sec, re.S) if not m: boxes.append('

' + sec + "

") continue hid, htext = m.group(1), m.group(2) headings.append((hid, re.sub("<[^>]+>", "", htext))) rest = sec[m.end():] boxes.append(f'

{htext}

{rest}

') contents = "" if headings: contents = '

{html.escape(title)}

{html.escape(summary)}

{intro} {contents}

''' canonical = SITE + BASE + ("" if slug == "index" else slug) page = HEAD.format(title=html.escape(title), titletag=html.escape(title if slug == "index" else title + " | Noema"), desc=html.escape(summary), canonical=canonical, style=STYLE) + head_box + "\n".join(boxes) + nav_box + TAIL return page def main(): if len(sys.argv) != 2: sys.exit("usage: build.py OUTPUT_DIR") out = sys.argv[1] os.makedirs(os.path.join(out, "img"), exist_ok=True) for f in os.listdir(os.path.join(ROOT, "docs", "screenshots")): if f.endswith(".png"): shutil.copy(os.path.join(ROOT, "docs", "screenshots", f), os.path.join(out, "img", f)) shutil.copy(os.path.join(ROOT, "internal", "api", "openapi.json"), os.path.join(out, "openapi.json")) shutil.copy(os.path.join(ROOT, "docs", "site", "htaccess"), os.path.join(out, ".htaccess")) for i, (slug, title, summary) in enumerate(CHAPTERS): with open(os.path.join(PAGES, slug + ".md"), encoding="utf-8") as f: md = f.read() page = render_page(i, slug, title, summary, md) with open(os.path.join(out, slug + ".html"), "w", encoding="utf-8") as f: f.write(page) print("wrote", slug + ".html", len(page) // 1024, "KB") if __name__ == "__main__": main()

Phone:

Email:

web@dixon.cx

(.*?)

{htext}

On this page

Noema documentation

{html.escape(title)}