From bd1c45fd60edc3184ab70dd3f123d88f3339202d Mon Sep 17 00:00:00 2001 From: Taras Mankovski <74687+taras@users.noreply.github.com> Date: Fri, 21 Aug 2026 22:12:41 -0400 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=8E=A8=20Say=20where=20judgment=20goe?= =?UTF-8?q?s,=20and=20give=20the=20answer=20a=20section=20of=20its=20own?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The home page argued that known work should be executable but never said where the remaining judgment goes. The design canvas answers that between the README section and the agent section, so the page now carries it: an agent for what you do not know how to do, a program for what you do, and the agent kept only for the judgment that is left. The README lede said "procedure", which named the artifact rather than the thing being moved. It now says what you already know how to do, which is what the new section then acts on. --- site/routes/index.tsx | 69 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/site/routes/index.tsx b/site/routes/index.tsx index 80a8710ee..47bb86077 100644 --- a/site/routes/index.tsx +++ b/site/routes/index.tsx @@ -15,6 +15,9 @@ const P_SM = "margin:0;font-size:0.875rem;line-height:1.6;color:var(--body);"; const P_MD = "margin:0;max-width:74ch;font-size:0.9375rem;line-height:1.6;color:var(--body);"; const P_MEASURED = `${P_SM}max-width:74ch;`; +/** A panel's opening claim, set at the weight of a heading. */ +const PANEL_LEDE = + "margin:0;font-size:1.0625rem;line-height:1.45;color:var(--ink);font-weight:800;letter-spacing:-0.01em;"; const CHAIN_ITEM = `${MONO}font-size:0.8125rem;font-weight:700;color:var(--ink);`; const STEP_NUMBER = @@ -475,6 +478,13 @@ function Step( } /** One of the three runtimes the same CLI installs under. */ +/** Where the work goes once you know how to do it. */ +const PRINCIPLES: { label: string; body: string }[] = [ + { label: "Don't know how", body: "Use an agent to figure it out." }, + { label: "Know how", body: "Make it a program." }, + { label: "Judgment remains", body: "Keep only that part agentic." }, +]; + const RUNTIMES: { name: string; body: string; lines: string[][] }[] = [ { name: "Deno", @@ -563,7 +573,7 @@ export default define.page(function Home({ url }) {
What you read is what runs
-

+

There is no workflow hidden behind the document. The document is the workflow.

@@ -581,12 +591,12 @@ export default define.page(function Home({ url }) {

The README as a CLI.

- Procedure belongs in the document; judgment belongs where the - document asks for it. xmd{" "} - moves procedure out of probabilistic interpretation and into + What you already know how to do belongs in the document; judgment + belongs where the document asks for it. xmd{" "} + moves known work out of probabilistic interpretation and into executable software: tests, file loading, sequencing, retries, and cleanup run as code, while planning, review, interpretation, and - design decisions stay with people or agents. Once procedure is + design decisions stay with people or agents. Once known work is executable, documentation does not need a parallel implementation to stay in sync — a README can explain the work to a person and expose the same work as runnable entry points for a CLI or an agent. @@ -655,6 +665,55 @@ export default define.page(function Home({ url }) {

+ {/* Principles */} +
+
+

When you know how, make it a program.

+
+

+ xmd{" "} + is not trying to make agents more autonomous. It is trying to + minimize how much work needs to remain agentic. When you know what + you want but don't know how to get there, use an agent. When you + know how to get there, make it a program and leave the agent only + the judgment that remains. +

+ +
+
The point
+
+

+ The goal isn't autonomous agents. It's to minimize how much work + needs to remain agentic. +

+
+
+ +
+ {PRINCIPLES.map((principle) => ( +
+ {principle.label} +

+ {principle.body} +

+
+ ))} +
+ +

+ One-off work can stay agentic. Repeated work that you know how to do + can become an xmd workflow. +

+ + + Read the docs → + +
+ {/* Agents */}
From 0d74401717add3eabd63184e065452a750aaf712 Mon Sep 17 00:00:00 2001 From: Taras Mankovski <74687+taras@users.noreply.github.com> Date: Fri, 21 Aug 2026 22:53:29 -0400 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20Name=20what=20the=20homepage?= =?UTF-8?q?=20offers,=20without=20renaming=20the=20pages=20that=20borrow?= =?UTF-8?q?=20it?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The homepage title and description are what a search result and a link preview show, and they described the site as turning documentation into workflows. They now name the work: repeatable work becomes a program, and agents are kept for the judgment that is left. The copy is set on the "/" entry rather than on DEFAULT_TITLE and DEFAULT_DESC, because /docs/control-flow and /docs/journal have no entry of their own and read those constants as their fallback. Editing the constants would have retitled two documentation pages as well. --- site/routes/_app.tsx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/site/routes/_app.tsx b/site/routes/_app.tsx index 33b8d6b11..f3426a504 100644 --- a/site/routes/_app.tsx +++ b/site/routes/_app.tsx @@ -16,7 +16,11 @@ const DEFAULT_DESC = // Per-route metadata so each page has a distinct title and its own canonical URL. const META: Record = { - "/": { title: DEFAULT_TITLE, desc: DEFAULT_DESC }, + "/": { + title: "executable.md — turn repeatable work into programs", + desc: + "Turn repeatable work into readable Markdown programs. Encode what you already know how to do, and use agents only where judgment remains.", + }, "/docs": { title: "Getting started · executable.md docs", desc: From eb6d116c4e33cab82a84e68f338972a116bbf916 Mon Sep 17 00:00:00 2001 From: Taras Mankovski <74687+taras@users.noreply.github.com> Date: Fri, 21 Aug 2026 23:01:10 -0400 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=84=20Give=20the=20workflow-design?= =?UTF-8?q?=20argument=20a=20page,=20and=20the=20links=20a=20destination?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The home page's principles section ends by pointing somewhere, and the nav offers a second destination, but the page they point at only existed in the design canvas. Both pointed at /docs instead. This is that page: least autonomy first, encode what is known, and the ladder a task climbs as it stops being unknown. The tokenizer and the prose styles moved to components/ because a second page needs them; index.tsx now reads them from there instead of holding the only copy. --- site/components/Header.tsx | 10 +- site/components/Prose.tsx | 71 ++++++++ site/components/Source.tsx | 41 +++++ site/routes/_app.tsx | 5 + site/routes/designing-workflows.tsx | 246 ++++++++++++++++++++++++++++ site/routes/index.tsx | 126 ++++---------- 6 files changed, 401 insertions(+), 98 deletions(-) create mode 100644 site/components/Prose.tsx create mode 100644 site/components/Source.tsx create mode 100644 site/routes/designing-workflows.tsx diff --git a/site/components/Header.tsx b/site/components/Header.tsx index f60278496..072eabc62 100644 --- a/site/components/Header.tsx +++ b/site/components/Header.tsx @@ -9,7 +9,9 @@ const LINK_ACTIVE = "font-weight:700;letter-spacing:0.06em;text-transform:uppercase;color:var(--green);border-bottom:var(--rule) solid var(--green);padding-bottom:1px;"; /** `active` marks the top-level section the current page belongs to. */ -export function Header({ active }: { active?: "docs" } = {}) { +export function Header( + { active }: { active?: "docs" | "workflows" } = {}, +) { return (
@@ -1051,14 +990,7 @@ export default define.page(function Home({ url }) {
- +