Reframe the website around repeatable workflows

[taras]

Story

As someone discovering Executable.md, I want the website to explain that it turns documented procedures into repeatable workflows, so I understand the product outcome rather than seeing only a list of Markdown execution features.

Positioning decision

Use this as the primary tagline:

Turn documentation into repeatable workflows.

The active verb makes the product’s role explicit: Executable.md is what turns an existing documented procedure into something people can run repeatedly. “Repeatable” remains the central promise. It distinguishes Executable.md from open-ended agent harnesses whose job is to reach a goal despite changing obstacles. Executable.md systematizes procedures that are understood well enough to document and need to run consistently again.

Use reliable and resumable as supporting benefits when the surrounding copy names the concrete behavior that earns those claims. Use reusable for component composition and sharing, but not as the primary tagline.

“Markdown that runs” can remain as a compact product description, but it no longer carries the hero message by itself.

Product narrative

The site should teach this progression:

1. Document the procedure. The source remains readable Markdown that renders normally in GitHub, editors, and other Markdown viewers.
2. Compose the procedure. Components, props, content slots, providers, and declarative operations turn repeated instructions into named, reusable building blocks.
3. Run the procedure. xmd run executes the document against the current environment with ordinary operation-level correctness.
4. Make it repeatable. xmd workflow executes supported operations in a constrained, retained environment so a workflow can reattach and continue after interruption.

The constrained workflow environment is a feature rather than a limitation. Durable workflows do not require arbitrary native command compatibility. Declarative components such as <Dir>, <File>, <Branch>, and <Commit> express intent through contextual capabilities. Optional shell and JavaScript execution add imperative flexibility only where the environment can support it safely.

The same declarative document can run in both modes. Durability is supplied by the host and its installed capabilities:

• xmd run uses ordinary host capabilities and does not promise Workspace retention, reattachment, or continuation.
• xmd workflow uses durable Workspace-backed capabilities and never silently falls back to unrelated host filesystem or process behavior.

Homepage content brief

This section is implementation guidance for the website agent. It supplies examples and copy direction; it does not make unshipped syntax part of the public contract.

Intended first impression

Within the first screen and the first example, a visitor should understand four things:

• the source is documentation people can read and review;
• repeated parts become named Markdown components with typed inputs;
• xmd runs the documented procedure instead of asking a person to translate it into ad hoc commands; and
• repeatability comes from making intent explicit, while durable continuation is an additional guarantee of xmd workflow once shipped.

Do not open with MDX, Effection, middleware, modifier chains, V8, or journal internals. Those explain how the product works after the outcome is clear.

Suggested hero copy

Eyebrow: Open source · Early / experimental

Headline: Turn documentation into repeatable workflows.

Supporting copy:

Executable.md keeps procedures readable as Markdown, then gives them reusable components, typed inputs, and executable steps so the same process can run consistently.

Primary action: Run your first document

Secondary actions: See an example · View on GitHub

“Markdown that runs” may appear as a short explanatory phrase below the hero or in metadata, but not as the primary value proposition.

Product economics: inference becomes an authored asset

Section heading: Pay for reasoning once. Run it repeatedly.

Supporting line:

Spend tokens defining and improving the workflow—not asking a model to reinterpret every deterministic step each time it runs.

An instruction-only document leaves the entire procedure probabilistic on every invocation: a model reads it, reconstructs the plan, chooses tools and arguments, resolves ambiguities, and often verifies or retries the work. Executable.md lets a human or AI encode the stable parts once as a Markdown script. File discovery, input validation, control flow, filesystem changes, Git effects, and other declared operations then execute directly. Model calls remain visible in the document and are reserved for steps that actually require judgment.

The cost advantage is amortization:

• authoring and improving the executable procedure has an up-front reasoning cost;
• deterministic steps do not incur repeated LLM interpretation on every run;
• per-run token cost is limited to the explicit agent or sampling steps the workflow contains; and
• reduced interpretation also reduces latency, variance, retries, and human supervision.

Do not claim that every workflow pays for tokens literally once. A workflow containing <Prompt>, <Sample>, or another probabilistic step still spends tokens when that step runs. The defensible claim is that the deterministic portion stops paying an interpretation cost on every execution.

A compact alternate line is:

Use AI to write and improve the workflow—not reinterpret it every time it runs.

Do not publish a percentage or fixed savings claim until a representative benchmark compares:

• input and output tokens;
• agent turns and tool calls;
• retries and human interventions;
• end-to-end latency;
• successful completion rate; and
• ordinary script/runtime and external-service costs.

Primary example: publishable with current behavior

Lead with a workflow whose visible steps perform work. A prose checklist is still only documentation; it does not show why making the document executable changes the result.

This example deterministically discovers and reads repository instructions, uses an agent only for the judgment step, then writes the resulting review:

review-instructions.md:

# Review repository instructions

<Glob include={["**/AGENTS.md"]} as="instructionPaths" />

<Each in={instructionPaths} let="path" as="instructions">
## {path}

<File path={path} />
</Each>

<Agent>
<Prompt as="review">
Review these repository instructions for contradictions and missing safeguards.

{instructions}
</Prompt>
</Agent>

<File path="reports/instruction-review.md">
# Instruction review

{review}
</File>

The saved report:

<File path="reports/instruction-review.md" />

Run it with:

xmd run review-instructions.md --default-agent codex

Every structural step has operational meaning:

1. <Glob> deterministically selects the instruction files.
2. <Each> applies the same read procedure to every selected path.
3. <File> reads through the contextual filesystem capability.
4. <Prompt> is the one explicitly probabilistic judgment step and the one step that spends model tokens.
5. The write form of <File> atomically saves the review at a declared path.
6. The read form renders the saved artifact back into the document.

The example demonstrates the product thesis: documentation is the program, deterministic orchestration is not delegated to the model, and probabilistic behavior is visible exactly where it occurs.

This example uses currently shipped document constructs. Describe it under xmd run without claiming interruption recovery or Workspace reattachment. Confirm the final invocation syntax against the current coding-agent documentation when implementing the page.

The page may present the example as a four-part visual:

Discover → Read repeatedly → Apply judgment → Save the result
<Glob> <Each> + <File> <Prompt> <File>
deterministic deterministic model tokens deterministic

Future durable example: publish only with its owning features

Once the exact Workspace, repository, Git, and GitHub components ship, evolve the example from a report into a workflow that can safely act on its result. Every listed step must remain programmatic rather than reverting to a prose checklist:

# Update repository instructions

<Workspace>
<Worktree>
<Branch name="docs/instruction-review" />

<Glob include={["**/AGENTS.md"]} as="instructionPaths" />

<Agent>
<Prompt as="changes">
Resolve contradictions in these repository instructions:

<Each in={instructionPaths} let="path">
## {path}
<File path={path} />
</Each>
</Prompt>
</Agent>

<File path="reports/instruction-review.md">{changes}</File>
<Commit
 paths={["reports/instruction-review.md"]}
 message="Document instruction review"
 as="commit"
/>
<PullRequest
 commit={commit}
 title="Document instruction review"
/>
</Worktree>
</Workspace>

This is a conceptual content example, not a syntax decision. Before publishing it, replace it with the exact shipped contracts from #218, #293, #294, #295, and related issues. In particular, do not assume that <Branch>, <Commit>, <PullRequest>, or their props have the shapes sketched here.

The accompanying explanation should emphasize:

• the model performs the judgment and content-generation step, not filesystem or Git orchestration;
• known environmental effects are declarative and visible in the document;
• the constrained workflow host authorizes filesystem, repository, Git, and GitHub capabilities;
• completed durable effects are restored or reconciled rather than blindly repeated;
• an interrupted execution reattaches to the same retained Workspace and continues at the journal frontier; and
• an unsupported imperative operation fails instead of escaping to the host.

Do not imply arbitrary journal-prefix rewind, exactly-once external side effects, recovery from deleted Workspace state, or arbitrary native command support.

Execution-mode comparison

Add this comparison only as each row becomes shipped and documented:

	xmd run	xmd workflow
Environment	Current host environment	Retained provider-backed Workspace
Best for	Running and experimenting with executable documents	Procedures that must continue across executions
Operations	Host capabilities, including supported executable blocks	Explicit declarative capabilities plus supported constrained execution
Journal	Optional diagnostic trace; never replayed	Durable record used to restore completed effects and continue
Interruption	No XMD environment-restoration guarantee	Reattaches the same Workspace and resumes at the recorded frontier
Unsupported behavior	Ordinary host/runtime error	Explicitly rejected; never silently falls back to the host

The distinction is restoration, not basic correctness. A successful xmd run file write still completes correctly; XMD simply does not promise that another execution can reconstruct or reattach its environment.

Secondary use-case cards

After the primary example, show no more than three concise applications:

1. Release and repository procedures — files, branches, commits, pull requests, tests, and review steps expressed as one readable process.
2. Repeatable AI-assisted work — deterministic structure around visible probabilistic steps such as agents and sampling, with inputs and outputs named in the document.
3. Operational runbooks — documentation that can collect input, branch, retry, and eventually suspend or continue when those contracts ship.

Keep the existing multi-model provider demo as a deeper example or docs link. It demonstrates composition, but it should not define the product category from the hero because Executable.md is broader than LLM orchestration.

Current and future capability guardrail

Safe to demonstrate now: Markdown components, frontmatter metadata, typed props, content slots, <File>, <Glob>, <TempDir>, current control flow, executable fences, provider composition, coding-agent components, and diagnostic journals—using their current documented limitations.

Do not present as available until shipped: xmd workflow, provider-backed <Workspace>, restoration from a replay journal, <Branch>, <Commit>, <PullRequest>, durable suspension, and any declarative operation still marked unbuilt.

When a future capability is needed to explain direction before it ships, label it explicitly as product direction and keep it out of installation or getting-started paths.

Claims to avoid

• “Any Markdown becomes durable.”
• “Commands run exactly once.”
• “Workflows can run any native tool.”
• “Agents are deterministic.”
• “The diagnostic journal resumes a run.”
• “A Workspace can rewind to any journal entry.”
• “Reliable” without naming the implemented guarantee.

Prefer concrete language: the component validates its input; the file replacement is atomic; the journal restores a completed effect; the workflow reattaches the same Workspace; the unsupported operation fails explicitly.

Website changes

Homepage

• Replace the hero heading “Markdown that runs.” with “Turn documentation into repeatable workflows.”
• Rewrite the supporting paragraph around readable documentation, composable workflow components, and repeatable execution. Lead with the outcome; move runtime machinery such as executable fences and Effection lower on the page.
• Preserve the early/experimental disclosure.
• Reorder the page into a comprehension path: documented procedure → reusable components → execution modes → reliability/resumption → concrete example → installation.
• Retain “Still just markdown,” but connect readability to maintaining and reviewing the procedure rather than focusing first on fence-parser behavior.
• Replace the current feature inventory with benefits grouped around documentation, composition, execution, and observability/recovery. Keep links to detailed mechanics in the docs.
• Use an example that begins as an understandable procedure and demonstrates reuse or declarative intent. Avoid presenting an arbitrary shell block as the defining workflow abstraction.
• Explain xmd run and xmd workflow side by side once both are available, including their different environment and continuation guarantees.
• Reframe journals according to their shipped behavior. Diagnostic journals for xmd run must not be described as replayable; durable workflow continuation must be tied to the workflow journal and retained Workspace that actually implement it.
• Keep installation and GitHub/docs calls to action easy to find.

Metadata and navigation

• Update the homepage title, description, Open Graph, and Twitter copy in site/routes/_app.tsx to use the new positioning.
• Review navigation labels and anchors so the path through the page matches the new narrative rather than a flat “Features / Example” inventory.
• Keep terminology consistent between the homepage, docs landing page, CLI reference, and README where they make the same product-level claim.

Documentation entry points

• Update the docs landing page to introduce the distinction between running a document and running a durable workflow.
• Link each reliability claim to documentation for the concrete contract: journal behavior, Workspace retention, replay/resumption, unsupported operations, and provider boundaries.
• Make it explicit that ordinary operation correctness still applies to xmd run; “not durable” means there is no XMD guarantee of environment restoration or reattachment.

Truthfulness and sequencing

The website describes shipped behavior in the present tense. Do not publish xmd workflow, retained Workspace, replay, declarative Git/filesystem components, or other durability behavior as available before their implementations land.

Implement the content in two truthful layers if necessary:

1. Publish the tagline and outcome-oriented framing using capabilities that exist today.
2. Add the execution-mode and durability sections as their owning issues ship.

Do not use “reliable” as an unsupported general guarantee. Connect it to named contracts such as deterministic component execution, committed Workspace state, reattachment, or continuation.

Acceptance

• The homepage uses “Turn documentation into repeatable workflows.” as its primary headline.
• The first screen explains the user outcome without requiring knowledge of MDX, Effection, modifier chains, or runtime internals.
• The primary example is an executable procedure whose steps discover, read, decide, or write; it is not a prose checklist presented as a workflow.
• The page explains that executable workflows move deterministic work from repeated inference into direct execution.
• Token-cost copy says that explicit model-driven judgment still incurs per-run inference; it never promises that every workflow pays for tokens only once.
• No numeric savings claim appears without a reproducible representative benchmark.
• The page presents readable documentation and reusable composition as the path to repeatable execution.
• Shipped xmd run behavior and future or shipped xmd workflow behavior are never conflated.
• Every reliability or resumption claim corresponds to implemented behavior and links to its documentation.
• Unsupported workflow operations are described as explicit failures, not transparent host fallbacks.
• Homepage metadata and social copy use the same positioning.
• The docs landing page and relevant CLI reference use consistent run and workflow language.
• Existing installation instructions, examples, links, responsive behavior, theme behavior, and accessibility remain intact.
• The site build and repository verification gates pass.

Related work

• Quest: Resume workflows with their Workspace, repositories, and Agent state #218 defines provider-backed Workspace restoration.
• Deliver answers to suspended workflows for later resumption #300 owns automated workflow continuation.
• Define the local Workspace host topology #346 defines the Workspace host topology.
• Spike: run Cloudflare Worker Shell and Worker JavaScript natively in Deno #351 evaluates optional constrained imperative execution over the Deno-local Workspace.
• ✨ Compose and certify the supervised adversarial implementation workflow #181 is the living end-to-end workflow target.