📝 Write down the Executable.md style guide

The bootstrap document was rewritten twice: once because the source read like a
shell script wearing Markdown, and again because the rendered output narrated
its own architecture while the most consequential action it took — granting a
repository npm publish rights — printed nothing at all.

Both rewrites came from one idea worth stating once: an executable document is
read twice, as source by someone deciding whether to trust it and as output by
the person running it, and both readings are designed. The rules that follow
from it, and the Markdown > JavaScript/TypeScript > Bash/SH ordering that keeps
each step at the level a reader can audit, now live beside the writing guide
rather than in a review comment.

Author: taras

AGENTS.md

@@ -261,7 +261,8 @@ here:
     `local/no-section-divider-comments` Oxlint rule
     (`scripts/oxlint-rules/`), which autofixes with `oxlint --fix`.
 11. Prefer expanding Executable.md capabilities over using JavaScript; Do not
-    use JavaScript in MD without verifying with the user or planner agent.
+    use JavaScript in MD without verifying with the user or planner agent. The
+    Executable.md Style Guide governs how an executable document is written.
 12. Use contextual APIs for environment-specific behavior in production code.
     Shared production modules must not access host-specific APIs or detect the
     active runtime. Runtime-named entrypoints and adapters install
@@ -302,6 +303,54 @@ here:
    alternatives, defensive qualifications, and exhaustive detail that does not
    help a reader understand or use the design.
 
+## Executable.md Style Guide
+
+An executable document is read twice: as source, by someone deciding whether to
+trust what it does, and as output, by the person running it. Both readings are
+designed. `scripts/BootstrapNpmPackage.md` is the worked example.
+
+1. **Write prose that executes, not a script with comments.** Each step explains
+   why it is necessary, performs it, and shows a useful result. The explanation
+   is the document's content, not commentary around it.
+2. **Explain a term where it first appears.** A document run once a year is run
+   by someone who has not learned its vocabulary. Do not assume — educate.
+3. **Lead with the practical consequence** rather than the principle, and
+   address the reader as `you`.
+4. **Report a completed action in the past tense.** A step that writes says that
+   it wrote, and what. Announcing an intention beforehand does not replace it.
+5. **Explain a refusal before it can happen**, and make it actionable: name the
+   command that resolves it, filled in with what the run actually found.
+6. **Keep machinery out of the output.** Captures, schemas, classifiers and
+   bindings render nothing. A command whose own chatter reads worse than the
+   document's sentence runs `silent`, and a command's raw output appears only
+   where that output is the evidence.
+7. **Put in `<Output>` only what the reader of a run can still act on.** How to
+   invoke the document is read before it runs, so it belongs outside the region.
+
+### Markdown > JavaScript/TypeScript > Bash/SH
+
+Express each step at the highest level that can carry it, and say why when
+dropping a level:
+
+- **Markdown** for control flow, I/O and composition — `<If>`, `<Each>`,
+  `<File>`, `<Parse>`, `<Capture>`, `<TempDir>`, and components. It is the layer
+  a reader can audit and the engine can journal and replay.
+- **TypeScript** in `eval` blocks for comparison, classification and formatting.
+  Typed, testable, and visible to the reader as a value rather than as text.
+- **Shell** to invoke a program, and for little else. Parsing, branching and
+  string assembly in shell are quoting hazards a reader cannot audit and a test
+  cannot reach.
+
+A document that needs a value from a command captures the command's output and
+decides in TypeScript; it does not decide in the shell and report the verdict.
+
+### Verifying a document
+
+Render the output and read it as the person running it before calling the
+document done. In a test, install `useNormalizedOutput()` — the CLI installs it
+and `execute()` does not, so a raw capture shows whitespace the operator never
+sees.
+
 ## PR Process
 
 1. Use .github/pull_request_template.md