Add <Syntax> to list the symbols available at its site

[taras]

Story

Authors can list or capture the symbols available where they are writing XMD, or request detailed documentation for selected components.

<Syntax />

<Syntax names={["Elicit", "File"]} />

<Syntax names={["Elicit"]} as="documentation" />

A symbol is one available component or control-flow construct. The bare form renders the compact symbol list. The named form renders selected components' symbol metadata and long-form documentation. Ordinary as capture binds the same text and emits nothing.

Approved description:

Inspect available components and control-flow constructs. <Syntax /> lists the symbols available here; <Syntax names={["Elicit"]} /> renders selected documentation.

Current gap

PR #759 delivered public protected <Syntax> and package-owned documentation middleware. Its collection rule still needs one composition correction: PR #765 currently refuses an identical documentation contribution when nested or independently layered hosts enter the same declarative package bootstrap. An identical repeated bootstrap is unambiguous and must behave like one bootstrap, while genuinely conflicting package documentation must still stop the execution before its root runs.

Contract

• <Syntax> is a public text component available in every supported XMD execution profile, including ordinary runs, workflows, declared Markdown components, and nested test executions.
• It is self-closing and accepts one optional names prop containing a non-empty array of unique, exact component names. It uses ordinary optional as capture.
• Omitted names renders the compact components and control-flow symbols available at the authored site: the actual host profile, directory and includes, workflow bundle or declared components, and trusted lexical restrictions.
• Supplied names renders each selected component's symbol metadata followed by its long-form documentation from the validated package-owned index defined by Generate website reference documentation from xmd CLI output #678. Entries render once in symbol order, independent of request order.
• Named lookup uses the enclosing authoring symbols. Inside <Evaluate>, it may therefore explain a component that the current evaluation cannot execute, but the rendered entry states whether that component is available there.
• Documentation joins to metadata by component name and origin together. A repository replacement never receives a standard built-in's documentation. A custom component without authored documentation renders its metadata and states that no long-form documentation is available.
• An empty or duplicate names list, a non-string entry, or an unknown name refuses before producing text. Paired content and undeclared props also refuse.
• Each occurrence reads its required symbols once and durably retains its complete rendered text. At a root, authoring and executable symbols are one value and are obtained once. A narrowed evaluation retains the genuinely distinct enclosing reference and admitted availability.
• Continuation restores the retained text without reading a moved environment or changed documentation asset. Retained data is closed and hostile-parsed. A failed or cancelled read produces no successful retained result.
• Symbol metadata and documentation never grant authority to execute anything they name.
• <Plan> invokes this public component. There is no private Syntax name or second implementation.
• xmd syntax lists <Syntax> with the approved description, and xmd syntax Elicit uses the same metadata-and-documentation renderer as named <Syntax>.

Documentation bootstrap

Documentation composes with the components it describes.

• Each package bootstrap installs its component registrations and documentation contribution through one stable, namespaced contextual middleware API.
• Canonical core supplies its own documentation as the middleware terminal. A host does not rebuild a central list of package documentation.
• Canonical execution collects the composed contributions once after trusted host bootstrap and snapshots them by value before root import or document execution.
• <Syntax names={...}> reads only that execution snapshot. Middleware installed later by document or component code cannot add, replace, or remove its documentation.
• One captured contribution consists of its owning package, asset identity, exact documentation text, and component-name set. Equality covers all four values. Set insertion order and JavaScript object identity do not matter.
• An identical repeated contribution adds nothing and succeeds. One bootstrap and two identical bootstraps produce the same captured documentation.
• Two non-identical contributions that overlap on one owning-package/component-name pair refuse before root execution, whichever middleware or bootstrap order supplied them. No order chooses a winner.
• A different owner is unequal but does not conflict by itself: documentation joins by component name and origin, so different packages may document same-spelled components. Disjoint component sets from one owner also coexist.
• Bootstrap and execution scopes are isolated. Collection is already execution-scoped, so “refuse only within one scope” is not a separate duplicate policy; it only describes which contribution list either policy would inspect.
• A nested or independently layered host may inherit a package bootstrap and enter the same declarative package again. Strictly refusing its identical contribution would make valid layering fail even though there is no ambiguous documentation winner. The repeated bootstrap must preserve both the selected package registrations and one documentation value.
• The manual runProfileDocumentation() list and equivalent ExecutionInstallation.documentation plumbing are not part of the design. A nested run receives the right documentation by invoking the same package bootstraps as an ordinary run.

Protection and lexical availability

Canonical core owns <Syntax>. A repository component, workflow bundle, declared Markdown component, ordinary or reserved registration, Component.importComponent middleware, document-authored context, or another loaded package copy cannot answer for or replace it.

Internally, canonical expansion carries a read-only SyntaxReference for the authored site:

interface SyntaxReference {
  symbols(): Operation<string>;
  documentation(names: readonly string[]): Operation<string>;
  available(symbols: SyntaxSymbols): SyntaxReference;
}

A trusted host may supply root symbols through a SyntaxSymbolsProvider. A canonical evaluator calls available(admittedSymbols) for the subtree it evaluates. Neither path exposes component definitions or execution authority to document-controlled state.

Under #713, bare <Syntax /> inside <Evaluate allow={...}> reports exactly the symbols admitted for that evaluation. Named <Syntax names={...} /> uses the enclosing authoring symbols for reference material and reports each selected component's availability inside the evaluation. A directly nested Plan can therefore request documentation without confusing information with authority. A deferred Plan reads the symbols at its own authored site; a later Evaluate still validates its text under that later evaluation's allow.

Evaluate narrows the enclosing execution's captured documentation reference; it does not recollect document-time middleware. Trusted nested-run or evaluation-host layers may repeat the same package bootstrap before a child's collection boundary. The identical contribution coalesces without losing registrations or documentation, while allow independently limits execution.

Naming and compatibility

SyntaxSymbols, SyntaxReference, SyntaxSymbolsProvider, symbols(), documentation() and available() are the canonical names for this surface. The durable operation is syntax_symbols and retains exactly { symbols: string }.

PR #759 is merged. Its earlier unmerged syntax_catalog record required no migration. The pre-1.0 TypeScript spelling SyntaxCatalog was replaced by SyntaxSymbols without a deprecated alias. xmd syntax --json uses version 2 and keeps its version and categories fields.

Acceptance

1. Bare output and ordinary as capture produce the same compact symbol list; paired and undeclared-prop forms refuse before reading symbols.
2. A valid named lookup renders each selected component's metadata and long documentation once in symbol order; capture receives identical text.
3. Empty, duplicate, malformed, and unknown names refuse atomically, with no partial output.
4. Ordinary runs, workflows, declared Markdown components, and nested run-profile tests read their own site rather than another profile or scope.
5. A nested run's named Syntax returns the same package-owned long documentation as an ordinary run, while preserving child-specific includes and availability.
6. Source, npm, JSR, and compiled xmd syntax each report one equivalent Syntax entry, and named component lookup returns equivalent documentation.
7. Repository, bundle, declaration, registration, middleware, context, and cross-copy replacement attempts cannot run a substitute; nearby non-conflicting controls still work.
8. Built-in documentation attaches only to the matching name and origin. A same-name repository replacement receives no built-in prose.
9. One bootstrap and two value-identical bootstraps produce the same documentation for named Syntax, bare Syntax, and a document containing no Syntax. Fresh contribution objects and differently ordered name sets prove value equality.
10. For one owner and an overlapping component, changed assets, text, or component sets refuse before root execution in either order. Disjoint sets and same-spelled components under distinct owners are non-conflicting controls; a changed owner is never silently coalesced.
11. Document-time middleware cannot change the captured index. Concurrent executions and separate scopes remain isolated.
12. Nested-run and Evaluate-related trusted layering may enter the same package bootstrap without losing its registrations or documentation. A non-identical owner/component overlap still refuses before child root or fragment effects.
13. Packaged Plan prompts through public Syntax and carries no private Syntax declaration or symbols provider.
14. One named root occurrence calls a changing or counting symbols provider exactly once; two occurrences are independent; continuation restores the closed retained value without another read; hostile data and actual cancellation fail closed.
15. Inside Evaluate, bare Syntax reports only admitted symbols while named Syntax can describe an enclosing-site component and truthfully marks whether that component is executable there.
16. Symbol or documentation text cannot grant any named execution authority.

Delivery

Correct PR #765 from signed commit 5c62cca2f365a41c7786b11a8cebfafd3733752c and return a new signed feedback commit with focused evidence for the amended duplicate matrix. The prior PASS on 5c62cca2 was correct for the former strict contract and does not approve this amended behavior. Any later branch head remains unreviewed until it is handed off by exact commit.

#765 lands before #713 implementation resumes. #762 builds the Plan information-request loop after <Syntax> and <Evaluate> are available.