Add <Verbose> to xmd run - #690

Closes #691.

Why

Executable documents need a first-party way to include progress notes and diagnostic prose that are useful while watching a run, without adding that noise to ordinary output. And a document has to be able to say where such content applies: a single flag for the whole run cannot turn a section on for the one component that wants it.

What changes

Before:

--verbose printed journal events, but document authors did not have a built-in component for verbose-only document output.

After:

<Verbose>…</Verbose> is available in the CLI run profile. Ordinary runs skip the body without expanding it. --verbose runs render the body at the invocation site. A component may install a nearer verbosity for its own content, and that decides what its content renders and nothing else — the ancestors around it and the siblings after it read the value that already applied to them.

How it works

xmd run --verbose flag → CLI seeds Config.verbose for the run → <Verbose> reads Config.verbose where it expands → renders <Content /> or ""

Verbosity joins the three timeouts as a contextual Config field: a boolean, false unless configured, installed and overridden exactly the way a timeout is. <Verbose> is a single static registration — nothing about the host is baked into it — and its generator resolves the contextual value at every invocation, before it decides whether to call content(). A component installs an override with yield* Config.around({ verbose: () => true }, { at: "min" }), and Effection teardown restores the enclosing value whether the content finished, failed or was cancelled.

The component is a registered run-profile default from @executablemd/cli, not core syntax and not a reserved name. A repository components/Verbose.md still overrides it.

What the process presents is a separate question with a separate answer. The journal file, the --verbose event echo, a value root's observational output and the testing report's own verbosity read the resolved flag directly, so a document decides what it renders and never what the command prints. Contextual verbosity carries no authority and takes no part in durable identity, authorization, replay admission, retained-effect ownership or journal identity.

Review guide

Start with: packages/cli/src/verbose-component.ts

Then review:

1. Config.verbose and its validated operation in packages/runtime/config.ts
2. The public contract in specs/acp-client-spec.md (§Config) and specs/executable-mdx-spec.md (§6.20)
3. The seed and registration in installDocumentComponents(), and the run-profile registry in packages/cli/src/syntax.ts
4. The Markdown behavior suite in packages/cli/tests/document-suites/verbose/Verbose.test.md

Look carefully at:

• Verbosity is read before content(), so a non-verbose run does not expand the skipped body — effects and failures inside it do not happen.
• The seed is installed at { at: "min" }, which is what lets a nested override win rather than lose to the CLI's own handler.
• The <Verbose.Enable> / <Verbose.Disable> fixtures live only under the test suite's components/ directory and are selected with --include; no production profile registers them.

What must stay true

• <Verbose> is overridable — enforced by ordinary component registration precedence and checked by VB4.
• Skipped verbose content does not execute — enforced by reading verbosity before content() and checked by VB3 and VB10.
• A nearer verbosity is lexical — enforced by Config.around(…, { at: "min" }) and checked by VB9, VB10 and CF10/CF10a.
• Verbosity is a boolean, and anything else fails when it is read — enforced by the validated verbose operation and checked by CF11.
• Configuring verbosity moves no timeout, and configuring a timeout does not move verbosity — checked by CF10b.
• xmd syntax describes the component without invoking it — checked by VB5 and syntax-cli.test.ts.
• The profile boundaries are unchanged: xmd run, an approved Plan under xmd plan --run, and an <Execution host="run"> child have <Verbose>; a direct xmd test root does not, even with --verbose — checked by VB6, VB7 and VB8.

How to verify it

• deno check packages/runtime/config.ts packages/runtime/mod.ts packages/core/mod.ts packages/cli/src/verbose-component.ts packages/cli/src/cli.ts packages/cli/src/syntax.ts packages/core/tests/config-api.test.ts packages/cli/tests/verbose-component.test.ts packages/cli/tests/document-suites/verbose/verbose-markdown.test.ts packages/cli/tests/document-suites/verbose/components/Verbose/Enable.ts packages/cli/tests/document-suites/verbose/components/Verbose/Disable.ts

• deno task test packages/core/tests/config-api.test.ts packages/cli/tests/document-suites/verbose/verbose-markdown.test.ts packages/cli/tests/verbose-component.test.ts packages/cli/tests/plan-cli.test.ts

• deno task test packages/cli/tests/syntax-cli.test.ts

• deno task test --changed=origin/main

• deno task lint

• git diff --check

• VB9 proves a host-false run renders an enabled subtree and neither outer marker, and fails if the seed were read once at registration or if the override leaked to siblings.

• VB10 proves a host-true run skips a disabled body — a <Fail> sentinel inside it never runs — and still renders the sibling after it, so it fails if teardown did not restore the enclosing value.

• CF11 proves a non-boolean installed from untyped JavaScript is refused when read rather than treated as truthiness.

Scope

Included

• Config.verbose, its validated operation, and its re-export from runtime and core.
• CLI run-profile <Verbose> as a static registration that reads contextual verbosity.
• The CLI seed of Config.verbose from the already-resolved flag, for both xmd run and the isolated run child.
• Run-profile and syntax-catalog registration.
• Architecture, ACP client spec and executable MDX spec updates.
• Markdown behavior tests for ordinary output, verbose output, skipped-body execution, override precedence and both directions of lexical override; TypeScript coverage for the catalog, the Plan path and the Config Api.

Intentionally unchanged

• Core structural syntax is unchanged.
• Existing --verbose journal logging, value-root observational output and testing report verbosity are unchanged, and remain driven by the flag rather than by the contextual field.
• Profile membership is unchanged: nothing is added to or removed from a profile here.
• Repository component resolution precedence is unchanged.
• specs/testing-spec.md is unchanged: the direct-test and run-child contracts do not move.

New abstractions

• Config.verbose and the validated verbose operation exist because verbosity has to be a property of the scope an element expands in rather than of the registration, which is what lets a component scope it to its own content. It reuses the Config Api the three timeouts already use, adding no new mechanism.
• VERBOSE_REGISTRATION is one static declaration, shared by the run profile and the syntax catalog, with nothing about a particular host inside it. There is no per-host registration builder, because there is nothing per-host left to build one from.
• Each new abstraction has multiple concrete uses or a clear justification.
• No speculative functionality is included.

Risks and limitations

• The <Verbose.Enable> / <Verbose.Disable> fixtures are checked-in TypeScript components. They are reachable only through the --include the two Markdown rows pass, and adding them to a production registry would turn them into public components — which is what the review should confirm did not happen.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.