From b23a67b8613b170dcc31fcda8a7c7fd9687f5407 Mon Sep 17 00:00:00 2001 From: Elmehdi Aitbrahim Date: Fri, 28 Aug 2026 19:58:48 -0400 Subject: [PATCH] feat(site): the AI-assistant page, and the evidence stack + MCP on the home cards (#118 #119) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #118 — keel's answer to JesseGPT-style hosted assistants is "point your own assistant at your own keel": the engine's read-only MCP server (keel mcp, 8 tools, stdio), exposed locally. New trilingual page /{en,ar,fr}/assistant/ (component + i18n dict + rev markers, nav after Docs): what an MCP server is in one sentence, the engine's own run command and mcpServers config quoted verbatim from docs/mcp-server.md (single-sourced in RUN_COMMAND and CLIENT_CONFIG so no locale can drift), the honest boundary (keel hosts nothing, sees nothing, relays nothing; no account, nothing to log into — and the stated caveat that the assistant's own provider is the user's arrangement), the cannot-do list naming the query_only enforcement (tests/mcp/test_readonly.py committed before the server existed; PRAGMA query_only = ON makes row writes impossible at the engine level — by construction, not policy), and the honest fit mirroring keel#579: the assistant proposes, the gate decides. The full server reference is synced, not duplicated: docs/mcp-server.md joins engine-docs.manifest.json and renders under Docs at the pinned release tag (v0.12.2), the fetch-engine-docs.mjs pattern the issue asked for. Every claim on the page carries a verify link into the repo at that tag (#91). #119 — the home cards said nothing about the evidence stack or the MCP server. Now five cards across all three locales, each with a verify pointer: screening, rails, gates (existing, now with verify links) + the evidence stack (hash- chained trials ledger with keel trials verify; significance, PBO/CSCV, Deflated Sharpe + MinBTL, Monte Carlo + candle bootstrap, walk-forward — all report-only under the Strathern rail: a score may report, and may gate, but may never be a ranking key) + the read-only MCP server, which links to the assistant page as its front door. The honest result stays above the fold where it was. Closes #118 Closes #119 --- engine-docs.manifest.json | 9 + src/components/Header.astro | 1 + src/components/pages/AssistantPage.astro | 148 ++++++++ src/components/pages/HomePage.astro | 21 +- src/i18n/config.ts | 1 + src/i18n/pages/assistant.ts | 419 +++++++++++++++++++++++ src/i18n/pages/home.ts | 76 +++- src/i18n/pages/index.ts | 3 + src/i18n/ui.ts | 3 + src/pages/ar/assistant.astro | 4 + src/pages/en/assistant.astro | 4 + src/pages/fr/assistant.astro | 4 + src/styles/global.css | 37 ++ 13 files changed, 720 insertions(+), 10 deletions(-) create mode 100644 src/components/pages/AssistantPage.astro create mode 100644 src/i18n/pages/assistant.ts create mode 100644 src/pages/ar/assistant.astro create mode 100644 src/pages/en/assistant.astro create mode 100644 src/pages/fr/assistant.astro diff --git a/engine-docs.manifest.json b/engine-docs.manifest.json index 6b59fdf..353e7c2 100644 --- a/engine-docs.manifest.json +++ b/engine-docs.manifest.json @@ -48,6 +48,15 @@ "section": "guides", "fr": "Le chemin vers un premier ordre réel supervisé — promotion, papier et étapes soumises à une validation humaine." }, + { + "path": "docs/mcp-server.md", + "slug": "mcp-server", + "title": "The read-only MCP server", + "en": "keel mcp: the eight read-only tools an assistant can call — doctor, capabilities, profiles, orders, veto_log, purification, trials, reports — and the fence, in six walls, that keeps them read-only.", + "ar": "‏keel mcp: الأدوات الثماني للقراءة فقط التي يستطيع المساعدُ الذكي استدعاءها — doctor وcapabilities وprofiles وorders وveto_log وpurification وtrials وreports — والسياجُ الذي يُبقيها للقراءة فقط.", + "section": "reference", + "fr": "keel mcp : les huit outils en lecture seule qu'un assistant peut appeler — doctor, capabilities, profiles, orders, veto_log, purification, trials, reports — et la clôture, en six murs, qui les garde en lecture seule." + }, { "path": "docs/experiments/2026-08-13-restated-under-a-production-faithful-engine.md", "slug": "experiment-honest-result-restated", diff --git a/src/components/Header.astro b/src/components/Header.astro index fa69268..2b4ae0c 100644 --- a/src/components/Header.astro +++ b/src/components/Header.astro @@ -15,6 +15,7 @@ const navItems: { key: Exclude; label: string }[] = [ { key: "features", label: chrome.nav.features }, { key: "install", label: chrome.nav.install }, { key: "docs", label: chrome.nav.docs }, + { key: "assistant", label: chrome.nav.assistant }, { key: "news", label: chrome.nav.news }, { key: "changelog", label: chrome.nav.changelog }, { key: "community", label: chrome.nav.community }, diff --git a/src/components/pages/AssistantPage.astro b/src/components/pages/AssistantPage.astro new file mode 100644 index 0000000..256f6bb --- /dev/null +++ b/src/components/pages/AssistantPage.astro @@ -0,0 +1,148 @@ +--- +import Base from "../../layouts/Base.astro"; +import CodeBlock from "../CodeBlock.astro"; +import ForOperators from "../ForOperators.astro"; +import HonestBox from "../HonestBox.astro"; +import { + assistant, + assistantVerify, + RUN_COMMAND, + CLIENT_CONFIG, +} from "../../i18n/pages/assistant"; +import { alternatesFor, localePath, type Locale } from "../../i18n/config"; +import { engineSourceUrl } from "../../lib/engine-url"; + +/** + * #118 — the AI-assistant page: keel's honest answer to hosted chatbots is + * "point your own assistant at your own keel". Every claim carries a verify + * link into the engine repository at the ref this build resolved (#91), the + * two command blocks are single-sourced verbatim from docs/mcp-server.md, and + * the full document is fetched into Docs by scripts/fetch-engine-docs.mjs. + */ +interface Props { + locale: Locale; +} + +const { locale } = Astro.props; +const c = assistant[locale]; + +const serverDocHref = engineSourceUrl(assistantVerify.serverDoc); +const toolsHref = engineSourceUrl(assistantVerify.tools); +const readonlyTestHref = engineSourceUrl(assistantVerify.readonlyTest); +/** The full document, rendered from the fetched content collection. */ +const docsPageHref = `${localePath("en", "docs")}mcp-server/`; + +const boundaryLinks = [ + { + label: + locale === "ar" + ? "صفحةُ الخادم في مستودع المحرّك" + : locale === "fr" + ? "la page du serveur dans le dépôt du moteur" + : "the server's page in the engine repository", + href: serverDocHref, + }, +]; + +const operatorLinks = + locale === "ar" + ? [ + { label: "المرجعُ الكامل للخادم (الوثائق، بالإنجليزية)", href: docsPageHref }, + { label: "كتاب تشغيل المشغّل (الوثائق)", href: localePath("ar", "docs") }, + { label: "شيفرة المحرّك", href: "https://github.com/CodeGateSoftware/keel" }, + ] + : locale === "fr" + ? [ + { label: "La référence complète du serveur (Documentation, EN)", href: docsPageHref }, + { label: "Le runbook opérateur (Documentation)", href: `${localePath("en", "docs")}operator-runbook/` }, + { label: "Le code source du moteur", href: "https://github.com/CodeGateSoftware/keel" }, + ] + : [ + { label: "The full server reference (Docs)", href: docsPageHref }, + { label: "Operator runbook (Docs)", href: `${localePath("en", "docs")}operator-runbook/` }, + { label: "Engine source", href: "https://github.com/CodeGateSoftware/keel" }, + ]; +--- + + +
+
+

{c.hero.eyebrow}

+

{c.hero.heading}

+

{c.hero.sub}

+
+ +
+ + +
+

{c.whatIs.title}

+

{c.whatIs.sentence}

+ {c.whatIs.body.map((paragraph) =>

{paragraph}

)} +
+ +
+

{c.connect.title}

+

{c.connect.intro}

+

{c.connect.runLabel}

+ +

{c.connect.configLabel}

+ +

{c.connect.clientsNote}

+

+ {c.connect.verifyNote}{locale === "fr" ? "\u00A0:" : ":"} + {assistantVerify.serverDoc.label} · + {c.docsNote} +

+
+ +
+

{c.tools.title}

+

{c.tools.intro}

+
    + { + c.tools.items.map((tool) => ( +
  • + {tool.name} — {tool.what} +
    • + )) + } +
+

+ {c.tools.verifyNote}{locale === "fr" ? "\u00A0:" : ":"} {assistantVerify.tools.label} +

+
+ +
+

{c.cannot.title}

+

{c.cannot.intro}

+
    + {c.cannot.points.map((point) =>
  • {point}
    • )} +
+ {c.cannot.enforcement.map((paragraph) =>

{paragraph}

)} +

+ {c.cannot.verifyNote}{locale === "fr" ? "\u00A0:" : ":"} {assistantVerify.readonlyTest.label} +

+
+ +
+

{c.fit.title}

+ {c.fit.body.map((paragraph) =>

{paragraph}

)} +

+ keel#579 · + {assistantVerify.serverDoc.label} +

+

{c.fit.punchline}

+
+ + +
+
+ diff --git a/src/components/pages/HomePage.astro b/src/components/pages/HomePage.astro index 26d724f..16dea5f 100644 --- a/src/components/pages/HomePage.astro +++ b/src/components/pages/HomePage.astro @@ -11,7 +11,7 @@ import { ENGINE_URL, } from "../../i18n/config"; import { t } from "../../i18n/ui"; -import { engineBlobUrl } from "../../lib/engine-url"; +import { engineBlobUrl, engineSourceUrl } from "../../lib/engine-url"; interface Props { locale: Locale; @@ -115,9 +115,22 @@ const fiqhHref =