diff --git a/packages/cli/src/repl/file-recorder.ts b/packages/cli/src/repl/file-recorder.ts index 8412f90b5..035e2f5ab 100644 --- a/packages/cli/src/repl/file-recorder.ts +++ b/packages/cli/src/repl/file-recorder.ts @@ -1,4 +1,4 @@ -import { Err, Ok } from "effection"; +import { createContext, Err, Ok, scoped, useScope } from "effection"; import type { Operation, Result } from "effection"; import { FilesInvariantError, @@ -9,13 +9,28 @@ import { parseFileWriteSuccess, } from "@executablemd/runtime"; import type { + FileCopyInput, FilesHandler, FilesOperation, FilesPhase, FilePathInput, FileWriteSuccess, } from "@executablemd/runtime"; -import { registerFileRecorder, assembleFileCall } from "@executablemd/runtime/files-host"; +import { + registerFileRecorder, + assembleFileCall, + withHostCopyRoute, +} from "@executablemd/runtime/files-host"; +import { + checkCopyPublication, + copyReplayContext, + recordedLocalOperation, + retainedCopyAhead, + ReplLocalRecordError, + retainedSelectionAhead, + failCopy, +} from "./repositories/deno/local.ts"; +import type { LocalOperation } from "./repositories/deno/local.ts"; import type { Around } from "@effectionx/context-api"; import type { AuthoredFileOperation } from "@executablemd/core/host"; import type { @@ -34,7 +49,85 @@ export interface EntryFileCalls { read(authored: AuthoredFileOperation, input: FilePathInput): Operation>; ensure(authored: AuthoredFileOperation, input: FilePathInput): Operation>; } -function recordingBody(route: FileRecordingRoute) { +interface CopyRouting { + guard(): Operation; + restoreSelection?(): Operation; + route(source: string, destination: string): Operation | undefined>; +} + +function copyRecorder(routing: CopyRouting) { + const nextOrdinal = new Map(); + return function* ( + input: FileCopyInput, + perform: () => Operation>, + ): Operation> { + const context = yield* copyReplayContext(); + const ordinal = nextOrdinal.get(context.coroutineId) ?? 0; + nextOrdinal.set(context.coroutineId, ordinal + 1); + const identity: Pick = { + operation: "file-copy", + ordinal, + request: { cwd: input.cwd, source: input.source, path: input.destination }, + }; + yield* routing.guard(); + if (routing.restoreSelection !== undefined && (yield* retainedSelectionAhead())) { + yield* routing.restoreSelection(); + } + if (yield* retainedCopyAhead(ordinal)) { + const result = yield* recordedLocalOperation({ + ...identity, + *perform() { + throw new ReplLocalRecordError("Cannot perform a retained file-copy occurrence live."); + }, + }); + return result.ok ? Ok(undefined) : result; + } + + let covered = false; + let result: Result; + try { + result = yield* scoped(() => + withHostCopyRoute( + function* (source, destination) { + try { + yield* copyReplayContext(); + const hold = yield* routing.route(source, destination); + if (hold !== undefined) { + yield* checkCopyPublication(); + yield* hold; + covered = true; + } + yield* copyReplayContext(); + } catch (error) { + // A delegating layer may recover before the composed call settles. + throw yield* failCopy(error); + } + }, + (function* () { + return yield* unitOutcome(perform(), { operation: "copy", phase: "access" }); + })(), + ), + ); + } catch (error) { + throw yield* failCopy(error); + } + yield* copyReplayContext(); + if (covered) { + result = yield* recordedLocalOperation({ + ...identity, + perform: function* () { + return result; + }, + }); + } + return result.ok ? Ok(undefined) : result; + }; +} + +function recordingBody( + route: FileRecordingRoute, + copy: ReturnType | undefined, +) { return { *read( input: FilePathInput, @@ -71,6 +164,11 @@ function recordingBody(route: FileRecordingRoute) { const result = yield* route("file-write", { ...input }, () => writeOutcome(next(input))); return result.ok ? Ok(expectWritten(result.value)) : result; }, + ...(copy === undefined + ? {} + : { + copyFile: ([input], next) => copy(input, () => next(input)), + }), *deleteFile([input], next) { const result = yield* route("file-delete", { ...input }, () => unitOutcome(next(input), { operation: "delete", phase: "access" }), @@ -81,8 +179,17 @@ function recordingBody(route: FileRecordingRoute) { }, }; } -export function* useEntryFileRecorder(route: FileRecordingRoute): Operation { - const body = recordingBody(route); +const entryCopyInstalled = createContext("executablemd.repl.entry-copy-installed"); + +export function* useEntryFileRecorder( + route: FileRecordingRoute, + copy: CopyRouting, +): Operation { + // Repository initialization can precede mount fallback in the same execution. + const scope = yield* useScope(); + const alreadyInstalled = scope.hasOwn(entryCopyInstalled); + scope.set(entryCopyInstalled, true); + const body = recordingBody(route, alreadyInstalled ? undefined : copyRecorder(copy)); const handle = yield* registerFileRecorder(body.boundary()); const read = assembleFileCall(handle, "readTextFile"); const ensure = assembleFileCall(handle, "ensureDirectory"); diff --git a/packages/cli/src/repl/repositories/admission.ts b/packages/cli/src/repl/repositories/admission.ts index 641d13982..d3f5a6b1e 100644 --- a/packages/cli/src/repl/repositories/admission.ts +++ b/packages/cli/src/repl/repositories/admission.ts @@ -115,6 +115,7 @@ export function* admitReplRepositoryHistory(retained: readonly DurableEvent[]): // checkout it read, and nothing outside this snapshot may authorize one: the // route has to be a placement a preceding record in the same history made. const placements: ReplPlacement[] = []; + const lastCopy = new Map(); for (const event of retained) { if (event.type !== "yield") { continue; @@ -162,7 +163,13 @@ export function* admitReplRepositoryHistory(retained: readonly DurableEvent[]): yield* admitObservation(payload, event.description.name, placements); continue; } - yield* admitLocal(payload, event.description.name); + const ordinal = yield* admitLocal(payload, event.description.name); + if (ordinal !== undefined) { + if (ordinal <= (lastCopy.get(event.coroutineId) ?? -1)) { + throw malformed(REPL_REPOSITORY_LOCAL); + } + lastCopy.set(event.coroutineId, ordinal); + } } } @@ -244,21 +251,19 @@ function* admitObservation( } } -function* admitLocal(payload: unknown, name: string): Operation { +function* admitLocal(payload: unknown, name: string): Operation { const record = parseReplLocalRecord(payload); if (record === undefined) { throw malformed(REPL_REPOSITORY_LOCAL); } - const fingerprint = yield* replLocalFingerprint({ - operation: record.operation, - request: record.request, - }); + const fingerprint = yield* replLocalFingerprint(record); if (record.fingerprint !== fingerprint) { throw changed(REPL_REPOSITORY_LOCAL); } - if (name !== replLocalRecordName({ operation: record.operation, fingerprint })) { + if (name !== replLocalRecordName(record)) { throw misnamed(REPL_REPOSITORY_LOCAL); } + return record.ordinal; } /** diff --git a/packages/cli/src/repl/repositories/deno/files.ts b/packages/cli/src/repl/repositories/deno/files.ts index e90347f82..a91186a23 100644 --- a/packages/cli/src/repl/repositories/deno/files.ts +++ b/packages/cli/src/repl/repositories/deno/files.ts @@ -49,7 +49,7 @@ import { createMountPolicy } from "../../mount-files.ts"; */ import type { Operation, Result } from "effection"; -import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"; +import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { realpath } from "node:fs/promises"; import { Err, until } from "effection"; import { filesFailure, Permissions } from "@executablemd/runtime"; @@ -316,7 +316,51 @@ function* canonical(directory: string): Operation { */ function inside(checkoutRoot: string, target: string): boolean { const at = relative(checkoutRoot, target); - return at !== "" && !at.startsWith("..") && !isAbsolute(at); + return at !== "" && at !== ".." && !at.startsWith(".." + sep) && !isAbsolute(at); +} + +function* copyRoute( + recorder: ReplLocalRecorder, + source: string, + destination: string, + roots: readonly string[], +): Operation | undefined> { + const placements = recorder.placements(); + const read = covering(placements, source); + const write = covering(placements, destination); + const checkout = write === undefined ? yield* recorder.selection() : undefined; + const hold = + write?.commonDirectory ?? + (checkout !== undefined && inside(checkout.checkoutRoot, destination) + ? checkout.commonDirectory + : undefined); + let owned = false; + if (hold === undefined) { + for (const directory of roots) { + const root = yield* canonical(directory); + if (root === destination || inside(root, destination)) { + owned = true; + break; + } + } + } + if (hold === undefined && !owned) { + if (read !== undefined) { + yield* read.own(); + } + return undefined; + } + return (function* () { + if (read !== undefined && read !== write) { + yield* read.own(); + } + if (write !== undefined) { + yield* write.own(); + } + if (hold !== undefined) { + yield* recorder.hold(hold); + } + })(); } export function* useReplFileRecorder( @@ -327,8 +371,18 @@ export function* useReplFileRecorder( access?: HostFilesAccess, ): Operation { const policy = yield* createMountPolicy(mounts, directory); - const files = yield* useEntryFileRecorder((operation, request, perform, authored) => - routed(recorder, operation, request, perform, workspace, authored, policy, access), + const roots = [ + ...(workspace === undefined ? [] : [workspace]), + ...(access === undefined ? [] : [access.project, access.assets, access.components]), + ]; + const files = yield* useEntryFileRecorder( + (operation, request, perform, authored) => + routed(recorder, operation, request, perform, workspace, authored, policy, access), + { + guard: () => policy.guard(), + restoreSelection: () => recorder.selection(), + route: (source, destination) => copyRoute(recorder, source, destination, roots), + }, ); return { files, policy }; } diff --git a/packages/cli/src/repl/repositories/deno/local.ts b/packages/cli/src/repl/repositories/deno/local.ts index e785d7730..bdabf3b7f 100644 --- a/packages/cli/src/repl/repositories/deno/local.ts +++ b/packages/cli/src/repl/repositories/deno/local.ts @@ -42,6 +42,7 @@ import type { import { StaleInputError } from "@executablemd/durable-streams"; import { asFilesFatal, FilesInvariantError } from "@executablemd/runtime"; import { + copyOrdinalFromName, parseReplLocalRecord, parseReplSelectionRecord, replLocalFingerprint, @@ -77,6 +78,7 @@ export interface LocalOperation { readonly operation: ReplLocalOperation; /** What the document asked for. Names the record; never live state. */ readonly request: ReplLocalRequest; + readonly ordinal?: number; /** The ordinary composed call, run only when no result is saved. */ perform(): Operation>; } @@ -140,6 +142,47 @@ export function retainedResultAhead(name: string): Operation { return retainedRecordAhead(REPL_REPOSITORY_LOCAL, name); } +export function* copyReplayContext(): Operation { + const context = yield* DurableContext.expect(); + const failure = context.durability?.failure; + if (failure !== undefined) { + throw failure; + } + if (context.replayIndex.abandonedHistory(context.coroutineId)) { + throw new ReplLocalRecordError("Cannot continue File.Copy after abandoning retained history."); + } + return context; +} + +export function* retainedCopyAhead(ordinal: number): Operation { + const context = yield* copyReplayContext(); + const description = context.replayIndex.peekYield(context.coroutineId)?.description; + const retained = + description?.type === REPL_REPOSITORY_LOCAL ? copyOrdinalFromName(description.name) : undefined; + if (retained !== undefined && retained < ordinal) { + throw yield* failCopy( + new ReplLocalRecordError("A retained file-copy occurrence was passed over."), + ); + } + return retained === ordinal; +} + +export function* failCopy(error: unknown): Operation { + const context = yield* DurableContext.expect(); + const state = (context.durability ??= {}); + return (state.failure ??= classify(error)); +} + +export function* checkCopyPublication(): Operation { + const context = yield* copyReplayContext(); + if ( + context.replayIndex.peekYield(context.coroutineId) !== undefined || + context.replayIndex.hasClose(context.coroutineId) + ) { + throw new ReplLocalRecordError("A new file-copy outcome would precede retained history."); + } +} + /** * This entry's ambient routing, restored from the journal or discovered live. * @@ -189,11 +232,8 @@ export function recordedLocalOperation( } function* recording(operation: LocalOperation): Operation> { - const fingerprint = yield* replLocalFingerprint({ - operation: operation.operation, - request: operation.request, - }); - const name = replLocalRecordName({ operation: operation.operation, fingerprint }); + const fingerprint = yield* replLocalFingerprint(operation); + const name = replLocalRecordName({ ...operation, fingerprint }); // Whatever comes back is journal data on a replay, so it is handed on as the // unknown it is and parsed below rather than trusted as this code's own. @@ -207,9 +247,8 @@ function* recording(operation: LocalOperation): Operation throw outcome.error; } return replLocalRecordJson({ - operation: operation.operation, + ...operation, fingerprint, - request: operation.request, outcome, }); }, @@ -223,7 +262,11 @@ function* recording(operation: LocalOperation): Operation "says about work already done is unknown.", ); } - if (parsed.operation !== operation.operation || parsed.fingerprint !== fingerprint) { + if ( + parsed.operation !== operation.operation || + parsed.fingerprint !== fingerprint || + parsed.ordinal !== operation.ordinal + ) { throw new ReplLocalRecordError( `the saved result standing where "${operation.operation}" belongs describes another ` + "operation, so this history does not say what happened here.", diff --git a/packages/cli/src/repl/repositories/records.ts b/packages/cli/src/repl/repositories/records.ts index e9f328074..973e3bbaa 100644 --- a/packages/cli/src/repl/repositories/records.ts +++ b/packages/cli/src/repl/repositories/records.ts @@ -75,11 +75,17 @@ export const REPL_REPOSITORY_SELECTION = "repl_repository_selection"; export const RECORD_PREFIX = "executablemd.git.repl-repository"; /** Which local operation a record describes. */ -export type ReplLocalOperation = "file-read" | "file-write" | "file-delete" | "dir-ensure"; +export type ReplLocalOperation = + | "file-read" + | "file-write" + | "file-copy" + | "file-delete" + | "dir-ensure"; const LOCAL_OPERATIONS: readonly ReplLocalOperation[] = [ "file-read", "file-write", + "file-copy", "file-delete", "dir-ensure", ]; @@ -100,6 +106,7 @@ export interface ReplLocalRequest { readonly path: string; /** The exact expanded content a write asked for; absent for the other three. */ readonly content?: string; + readonly source?: string; } /** The routing facts the entry's ambient discovery found, or their absence. */ @@ -114,6 +121,7 @@ export interface ReplAmbientCheckout { export interface ReplLocalRecord { readonly version: typeof REPL_REPOSITORY_VERSION; readonly operation: ReplLocalOperation; + readonly ordinal?: number; /** The digest of the version, operation kind and authored request. */ readonly fingerprint: string; readonly request: ReplLocalRequest; @@ -141,16 +149,41 @@ export interface ReplSelectionRecord { export function replLocalRecordName(record: { readonly operation: ReplLocalOperation; readonly fingerprint: string; + readonly ordinal?: number; }): string { return canonicalJson([ RECORD_PREFIX, "local", REPL_REPOSITORY_VERSION, record.operation, + ...(record.ordinal === undefined ? [] : [record.ordinal]), record.fingerprint, ]); } +export function copyOrdinalFromName(name: string): number | undefined { + try { + const fields: unknown = JSON.parse(name); + if ( + Array.isArray(fields) && + fields.length === 6 && + fields[0] === RECORD_PREFIX && + fields[1] === "local" && + fields[2] === REPL_REPOSITORY_VERSION && + fields[3] === "file-copy" && + typeof fields[5] === "string" + ) { + return copyOrdinal(fields[4]); + } + } catch { + return undefined; + } +} + +function copyOrdinal(value: unknown): number | undefined { + return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined; +} + /** The stable name the entry's ambient routing record is journaled under. */ export function replSelectionRecordName(record: { readonly fingerprint: string }): string { return canonicalJson([RECORD_PREFIX, "selection", REPL_REPOSITORY_VERSION, record.fingerprint]); @@ -160,11 +193,13 @@ export function replSelectionRecordName(record: { readonly fingerprint: string } export function replLocalFingerprint(input: { readonly operation: ReplLocalOperation; readonly request: ReplLocalRequest; + readonly ordinal?: number; }): Operation { return digest({ version: REPL_REPOSITORY_VERSION, operation: input.operation, request: requestJson(input.request), + ...(input.ordinal === undefined ? {} : { ordinal: input.ordinal }), }); } @@ -179,11 +214,13 @@ export function replLocalRecordJson(input: { readonly fingerprint: string; readonly request: ReplLocalRequest; readonly outcome: Result; + readonly ordinal?: number; }): Json { const stated = { version: REPL_REPOSITORY_VERSION, operation: input.operation, fingerprint: input.fingerprint, + ...(input.ordinal === undefined ? {} : { ordinal: input.ordinal }), request: requestJson(input.request), }; if (input.outcome.ok) { @@ -222,10 +259,13 @@ export function replSelectionRecordJson(input: { * happened and may not. The caller refuses rather than guessing. */ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefined { - const refusal = members(value, ["version", "operation", "fingerprint", "request", "refusal"]); + const fields = ["version", "operation", "fingerprint", "request"]; + const refusal = + members(value, [...fields, "refusal"]) ?? members(value, [...fields, "ordinal", "refusal"]); const success = refusal === undefined - ? members(value, ["version", "operation", "fingerprint", "request", "success"]) + ? (members(value, [...fields, "success"]) ?? + members(value, [...fields, "ordinal", "success"])) : undefined; const read = refusal ?? success; if (read === undefined) { @@ -239,6 +279,10 @@ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefine if (fingerprint === undefined || operation === undefined) { return undefined; } + const ordinal = copyOrdinal(read.ordinal); + if (operation === "file-copy" ? ordinal === undefined : Object.hasOwn(read, "ordinal")) { + return undefined; + } const request = parseReplLocalRequest(read["request"], operation); if (request === undefined) { return undefined; @@ -247,13 +291,19 @@ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefine refusal === undefined ? parseSuccess(read["success"], operation) : parseRefusal(read["refusal"]); - if (outcome === undefined) { + if ( + outcome === undefined || + (operation === "file-copy" && + !outcome.ok && + parseFilesFailure(outcome.error)?.operation !== "copy") + ) { return undefined; } return Object.freeze({ version: REPL_REPOSITORY_VERSION, operation, fingerprint, + ...(ordinal === undefined ? {} : { ordinal }), request, outcome, }); @@ -314,6 +364,18 @@ function parseReplLocalRequest( value: unknown, operation: ReplLocalOperation, ): ReplLocalRequest | undefined { + if (operation === "file-copy") { + const read = members(value, ["cwd", "source", "destination"]); + if (read === undefined) { + return undefined; + } + const cwd = string(read.cwd); + const source = anyString(read.source); + const path = anyString(read.destination); + return cwd === undefined || source === undefined || path === undefined + ? undefined + : Object.freeze({ cwd, source, path }); + } const read = operation === "file-write" ? members(value, ["cwd", "path", "content"]) @@ -406,6 +468,9 @@ function carried(data: unknown): Error { } function requestJson(request: ReplLocalRequest): Json { + if (request.source !== undefined) { + return { cwd: request.cwd, source: request.source, destination: request.path }; + } return request.content === undefined ? { cwd: request.cwd, path: request.path } : { cwd: request.cwd, path: request.path, content: request.content }; diff --git a/packages/cli/src/repl/workspace-mount-installation.ts b/packages/cli/src/repl/workspace-mount-installation.ts index 4fce5a378..b881d06ed 100644 --- a/packages/cli/src/repl/workspace-mount-installation.ts +++ b/packages/cli/src/repl/workspace-mount-installation.ts @@ -1,6 +1,6 @@ import { hostFileAccessReason, filesFailure, fileWriteFailure } from "@executablemd/runtime"; import type { HostFilesAccess } from "@executablemd/runtime"; -import { Err } from "effection"; +import { Err, lift } from "effection"; import { admitReplRepositoryHistory } from "./repositories/admission.ts"; import { cwd } from "@executablemd/runtime"; import type { Operation, Result } from "effection"; @@ -49,6 +49,10 @@ export function workspaceMountInstallation( } else { const directory = yield* cwd(); const policy = yield* createMountPolicy(mounts, directory); + const roots = [ + ...(ownedDirectory === undefined ? [] : [ownedDirectory]), + ...(limits === undefined ? [] : [limits.project, limits.assets, limits.components]), + ]; const files = yield* useEntryFileRecorder( function* (operation, request, perform, authored): Operation> { yield* policy.guard(); @@ -62,10 +66,6 @@ export function workspaceMountInstallation( if (yield* retainedResultAhead(name)) { return yield* recordedLocalOperation({ operation, request, perform }); } - const roots = [ - ...(ownedDirectory === undefined ? [] : [ownedDirectory]), - ...(limits === undefined ? [] : [limits.project, limits.assets, limits.components]), - ]; const permitted = roots.length === 0 || ((yield* Permissions.operations.files( @@ -137,6 +137,19 @@ export function workspaceMountInstallation( } return yield* perform(); }, + { + guard: () => policy.guard(), + *route(_source, destination) { + for (const directory of roots) { + const root = (yield* API.Fs.operations.realpath(directory)) ?? resolve(directory); + const at = relative(root, destination); + if (at !== ".." && !at.startsWith(".." + sep) && !isAbsolute(at)) { + return lift(() => undefined)(); + } + } + return undefined; + }, + }, ); entry = { files, policy }; } diff --git a/packages/cli/tests/document-suites/file-copy/FileCopy.test.md b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md new file mode 100644 index 000000000..035a75e95 --- /dev/null +++ b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md @@ -0,0 +1,52 @@ +# File.Copy + + + + + +Generate the binary fixture in the test directory. + +```ts eval +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { until } from "effection"; +yield* (function* () { + const fixture = new Uint8Array(8 * 1024 * 1024 + 1); + fixture[fixture.length - 1] = 0xff; + yield* until(writeFile(join(directory, "source.bin"), fixture)); +})(); +``` + + + +```ts eval +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { until } from "effection"; +const verified = yield* (function* () { + const fixture = new Uint8Array(8 * 1024 * 1024 + 1); + fixture[fixture.length - 1] = 0xff; + const source = join(directory, "source.bin"); + const destination = join(directory, "destination.bin"); + const original = (yield* until(readFile(source))).equals(fixture); + const copy = (yield* until(readFile(destination))).equals(fixture); + yield* until(writeFile(destination, Uint8Array.of(42))); + return { original, copy, independent: (yield* until(readFile(source))).equals(fixture) }; +})(); +``` + + + + + + + +source +\n\nran\n\n\n'} as="child"> + + + + + + + diff --git a/packages/cli/tests/repl-repositories.test.ts b/packages/cli/tests/repl-repositories.test.ts index c1c9fab10..c819e9d74 100644 --- a/packages/cli/tests/repl-repositories.test.ts +++ b/packages/cli/tests/repl-repositories.test.ts @@ -19,14 +19,14 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { ensure, resource, scoped, until } from "effection"; +import { ensure, Err, resource, scoped, until } from "effection"; import type { Operation, Result } from "effection"; -import { exists, readTextFile, rm } from "@effectionx/fs"; +import { ensureDir, exists, readTextFile, rm } from "@effectionx/fs"; import { mkdtemp, realpath, writeFile } from "node:fs/promises"; import { appendFile, open } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative } from "node:path"; -import { API, Permissions, useHostFiles } from "@executablemd/runtime"; +import { API, filesFailure, Permissions, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { @@ -39,6 +39,11 @@ import { REPL_REPOSITORY_PLACEMENT, } from "../src/repl/repositories/placement-records.ts"; import { Execution } from "@executablemd/core/api"; +import { collect, inlineSource } from "@executablemd/core"; +import { executeInstalled } from "@executablemd/core/host"; +import { useCompositionComponents } from "@executablemd/git"; +import { useReplFileRecorder } from "../src/repl/repositories/deno/files.ts"; +import { workspaceMountInstallation } from "../src/repl/workspace-mount-installation.ts"; import type { Json } from "@executablemd/core"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { ordinaryGeneratedSelection } from "../src/evaluation-profile.ts"; @@ -455,6 +460,149 @@ describe("how a REPL entry gets its repository behavior", () => { expect(yield* exists(join(fixture.checkout, "made"))).toBe(false); }); + it("retains an authored byte copy in a managed Repository", function* () { + const fixture = yield* useFixture(); + const origin = yield* useOrigin(fixture); + const source = [ + ``, + 'original', + '', + "", + ].join("\n"); + const events = yield* submit(fixture, source, execution(), { initialized: 0 }); + const copies = recordsOf(events, REPL_REPOSITORY_LOCAL).flatMap((event) => { + const record = parseReplLocalRecord( + event.type === "yield" && event.result.status === "ok" ? event.result.value : undefined, + ); + return record?.operation === "file-copy" ? [record] : []; + }); + expect(copies).toHaveLength(1); + expect(copies).toHaveLength(1); + expect(copies[0]?.outcome).toEqual({ ok: true, value: undefined }); + const directory = copies[0]?.request.cwd; + if (directory === undefined) { + throw new Error("No managed copy directory"); + } + expect(yield* readTextFile(join(directory, "copy.md"))).toBe("original"); + }); + + it("uses both placement slots and only the destination mutation hold from a mounted cwd", function* () { + const fixture = yield* useFixture(); + const destination = join(fixture.root, "destination"); + yield* ensureDir(destination); + const sourceCommon = join(fixture.checkout, ".git"); + const destinationCommon = join(destination, ".git"); + const calls: string[] = []; + yield* useHostFiles({ + observe(event) { + if (event.operation === "copy") { + calls.push(event.phase); + } + }, + }); + let delegated = 0; + yield* API.Files.around( + { + *copyFile([input], next) { + if (input.destination !== "uncovered.md") { + return yield* next(input); + } + delegated++; + const copied = yield* next({ ...input, destination: "destination/rewritten.md" }); + expect(copied.ok).toBe(true); + return Err(filesFailure({ operation: "copy", phase: "target", reason: "occupied" })); + }, + }, + { at: "min" }, + ); + yield* useCompositionComponents(); + yield* useWorkingDirectory(fixture.root); + yield* Permissions.around({ + files: ([op], next) => (op === "absolute" ? true : next(op)), + }); + const mounts = [{ source: fixture.root, target: "/reference" }]; + function* runCopy(stream: InMemoryStream) { + const files = yield* useReplFileRecorder( + { + *selection() { + return undefined; + }, + *hold(common) { + calls.push(`hold ${common}`); + }, + placements() { + return [ + { + checkoutRoot: fixture.checkout, + commonDirectory: sourceCommon, + *own() { + calls.push("source slot"); + }, + }, + { + checkoutRoot: destination, + commonDirectory: destinationCommon, + *own() { + calls.push("destination slot"); + }, + }, + ]; + }, + }, + undefined, + mounts, + fixture.root, + ); + const source = [ + '', + '', + "", + '', + ].join("\n"); + return String( + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream }, [ + workspaceMountInstallation(mounts, () => files), + ]), + ), + ); + } + const stream = new InMemoryStream(); + const first = yield* scoped(() => runCopy(stream)); + expect(calls).toEqual([ + "source slot", + "destination slot", + `hold ${destinationCommon}`, + "target", + "access", + "source slot", + "destination slot", + `hold ${destinationCommon}`, + "target", + "access", + ]); + const records = recordsOf(yield* stream.readAll(), REPL_REPOSITORY_LOCAL); + const copy = records.flatMap((event) => { + const parsed = parseReplLocalRecord( + event.type === "yield" && event.result.status === "ok" ? event.result.value : undefined, + ); + return parsed?.operation === "file-copy" ? [parsed] : []; + }); + expect(copy).toHaveLength(2); + expect(copy[0]?.request.cwd).toBe(fixture.root); + expect(copy[1]?.request.path).toBe("uncovered.md"); + expect(copy[1]?.outcome.ok).toBe(false); + expect(first).toContain("already exists"); + expect(yield* readTextFile(join(destination, "..notes.md"))).toBe("seed\n"); + expect(yield* readTextFile(join(destination, "rewritten.md"))).toBe("seed\n"); + const prefix = (yield* stream.readAll()).filter((event) => event.type !== "close"); + calls.length = 0; + const restored = yield* scoped(() => runCopy(new InMemoryStream(prefix))); + expect(restored).toBe(first); + expect(calls).toEqual([]); + expect(delegated).toBe(1); + }); + it("E7: keeps two entries' equal records in their own segments", function* () { const fixture = yield* useFixture(); const counted: Counted = { initialized: 0 }; diff --git a/packages/cli/tests/retained-repository-git.test.ts b/packages/cli/tests/retained-repository-git.test.ts index 081510eee..39d244807 100644 --- a/packages/cli/tests/retained-repository-git.test.ts +++ b/packages/cli/tests/retained-repository-git.test.ts @@ -163,6 +163,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -350,6 +351,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-history.test.ts b/packages/cli/tests/retained-repository-history.test.ts index 0258e6e59..9151ddc07 100644 --- a/packages/cli/tests/retained-repository-history.test.ts +++ b/packages/cli/tests/retained-repository-history.test.ts @@ -212,6 +212,9 @@ function invocationFiles(temporary: string): InvocationFiles { const resolved = (input: FilePathInput): string => input.path.startsWith("/") ? input.path : join(input.cwd, input.path); const handler: FilesHandler = { + *copyFile() { + throw new Error("Unexpected copy"); + }, // deno-lint-ignore require-yield *checkFilePath(): Operation> { return Ok(undefined); diff --git a/packages/cli/tests/retained-repository-lifecycle.test.ts b/packages/cli/tests/retained-repository-lifecycle.test.ts index 2b7d7e115..6dd29b0f7 100644 --- a/packages/cli/tests/retained-repository-lifecycle.test.ts +++ b/packages/cli/tests/retained-repository-lifecycle.test.ts @@ -167,6 +167,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -247,6 +248,7 @@ function entry( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-local.test.ts b/packages/cli/tests/retained-repository-local.test.ts index a23a44106..b73a86d85 100644 --- a/packages/cli/tests/retained-repository-local.test.ts +++ b/packages/cli/tests/retained-repository-local.test.ts @@ -46,6 +46,7 @@ import { fileWriteSuccess, filesFailure, hostFilesHandler, + parseFilesFailure, Permissions, } from "@executablemd/runtime"; import type { FilePathInput, FilesHandler, FileWriteInput } from "@executablemd/runtime"; @@ -53,7 +54,13 @@ import { InMemoryStream, StaleInputError } from "@executablemd/durable-streams"; import type { DurableEvent, DurableStream, Json } from "@executablemd/durable-streams"; import { Execution } from "@executablemd/core/api"; import { executeInstalled } from "@executablemd/core/host"; -import { collect, Elicitation, inlineSource, useNormalizedOutput } from "@executablemd/core"; +import { + collect, + Elicitation, + inlineSource, + registerComponents, + useNormalizedOutput, +} from "@executablemd/core"; import { useDenoRepositoryOperations } from "@executablemd/git/deno"; import type { DenoRepositoryOperations } from "@executablemd/git/deno"; import { denoReplEntry } from "../src/deno-repositories.ts"; @@ -124,6 +131,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -210,6 +218,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, @@ -1451,3 +1460,329 @@ describe("marked workspace mount initialization", () => { ]); }); }); + +describe("retained File.Copy", () => { + const source = ''; + + it("replays success and occupied refusal before current permissions and routing", function* () { + for (const occupied of [false, true]) { + const fixture = yield* useFixture(); + const target = join(fixture.checkout, "copy.md"); + if (occupied) { + yield* writeTextFile(target, "occupied"); + } + const first = yield* run(fixture, source, new InMemoryStream(), counters()); + expect( + localRecords(first.events).map((record) => [record.operation, record.outcome.ok]), + ).toEqual([["file-copy", !occupied]]); + yield* writeTextFile(target, "external"); + const checked = counters(); + const asked: string[] = []; + const resumed = yield* run(fixture, source, unfinished(first.events), checked, { + *between() { + yield* Permissions.around({ + files: ([op]) => { + asked.push(op); + return false; + }, + }); + yield* API.Fs.around({ + *realpath([path], next) { + if (path.includes("seed.md") || path === fixture.checkout) { + checked.resolved++; + } + return yield* next(path); + }, + }); + }, + }); + expect(resumed.refusal).toBe(undefined); + expect(resumed.output).toBe(first.output); + expect(asked).toEqual([]); + expect(checked.discoveries).toEqual([]); + expect(checked.resolved).toBe(0); + expect(yield* readTextFile(target)).toBe("external"); + } + }); + + it("rejects either changed operand before routing and leaves uncovered copy live", function* () { + const fixture = yield* useFixture(); + const doc = ''; + const placement = { cwd: fixture.root, projectCwd: fixture.checkout }; + const first = yield* run(fixture, doc, new InMemoryStream(), counters(), placement); + expect(localRecords(first.events).map((record) => record.operation)).toEqual(["file-copy"]); + for (const change of [{ source: "checkout/other.md" }, { destination: "outside.md" }]) { + const checked = counters(); + const asked: string[] = []; + const resumed = yield* run(fixture, doc, unfinished(first.events), checked, { + ...placement, + *between() { + yield* API.Files.around({ copyFile: ([input], next) => next({ ...input, ...change }) }); + yield* Permissions.around({ + files: ([op]) => { + asked.push(op); + return true; + }, + }); + }, + }); + expect(resumed.refusal).toContain("file-copy"); + expect(asked).toEqual([]); + expect(checked.discoveries).toEqual([]); + expect(localRecords(resumed.events)).toEqual(localRecords(first.events)); + } + const outside = join(fixture.root, "outside.md"); + expect(yield* exists(outside)).toBe(false); + const uncovered = yield* run( + fixture, + doc.replace("checkout/copy.md", "outside.md"), + new InMemoryStream(), + counters(), + placement, + ); + expect(uncovered.refusal).toBe(undefined); + expect(localRecords(uncovered.events)).toEqual([]); + expect(yield* readTextFile(outside)).toBe("seed\n"); + }); + + it("keeps an uncovered or synthetic direct call separate from a later retained copy", function* () { + const fixture = yield* useFixture(); + const placement = { cwd: fixture.root, projectCwd: fixture.checkout }; + const a = "outside.md"; + const b = "checkout/copy.md"; + const doc = ""; + type Mode = "live" | "replay" | "insert" | "catch-insert" | "synthetic"; + const observed: string[] = []; + const caught: unknown[] = []; + function install(mode: Mode) { + return (function* () { + yield* registerComponents([ + { + name: "CopyPair", + origin: "test", + props: { type: "object", properties: {} }, + *fn() { + for (const destination of [a, b]) { + const outcome = yield* API.Files.operations.copyFile({ + cwd: fixture.root, + source: "checkout/seed.md", + destination, + }); + observed.push( + outcome.ok ? "ok" : (parseFilesFailure(outcome.error)?.reason ?? "failed"), + ); + } + return ""; + }, + }, + ]); + yield* API.Files.around( + { + *copyFile([input], next) { + observed.push(input.destination); + if (input.destination === a && mode === "synthetic") { + return Ok(undefined); + } + if (input.destination === a && mode === "catch-insert") { + try { + yield* next({ ...input, destination: "checkout/insert.md" }); + } catch (error) { + caught.push(error); + } + try { + yield* next({ ...input, destination: "retry-outside.md" }); + } catch (error) { + caught.push(error); + } + return Ok(undefined); + } + return yield* next( + input.destination === a && mode === "insert" + ? { ...input, destination: "checkout/insert.md" } + : input, + ); + }, + }, + { at: "min" }, + ); + yield* API.Fs.around({ + *stat([path], next) { + if (mode === "catch-insert" && path === join(fixture.checkout, "seed.md")) { + observed.push("classify " + path); + } + return yield* next(path); + }, + *lstat([path], next) { + if (path.endsWith("/" + a) || path.endsWith("/" + b) || path.endsWith("/insert.md")) { + observed.push("observe " + path); + } + return yield* next(path); + }, + }); + })(); + } + + const fresh = yield* run(fixture, doc, new InMemoryStream(), counters(), { + ...placement, + between: () => install("live"), + }); + expect(fresh.refusal).toBe(undefined); + expect(localRecords(fresh.events).map((record) => record.ordinal)).toEqual([1]); + expect(recordsOf(fresh.events, REPL_REPOSITORY_SELECTION)).toHaveLength(1); + yield* writeTextFile(join(fixture.checkout, "copy.md"), "historical edit"); + + observed.length = 0; + const replayed = counters(); + const resumed = yield* run(fixture, doc, unfinished(fresh.events), replayed, { + ...placement, + between: () => install("replay"), + }); + expect(resumed.refusal).toBe(undefined); + expect(observed).toEqual([a, "observe " + join(fixture.root, a), "occupied", "ok"]); + expect(replayed.discoveries).toEqual([]); + expect(yield* readTextFile(join(fixture.root, a))).toBe("seed\n"); + expect(yield* readTextFile(join(fixture.root, b))).toBe("historical edit"); + + observed.length = 0; + const inserted = yield* run(fixture, doc, unfinished(fresh.events), counters(), { + ...placement, + between: () => install("insert"), + }); + expect(inserted.refusal).toContain("precede retained history"); + expect(observed).toEqual([a]); + expect(yield* exists(join(fixture.checkout, "insert.md"))).toBe(false); + expect(localRecords(inserted.events)).toEqual(localRecords(fresh.events)); + + observed.length = 0; + const recovered = yield* run(fixture, doc, unfinished(fresh.events), counters(), { + ...placement, + between: () => install("catch-insert"), + }); + expect(recovered.refusal).toBe(inserted.refusal); + expect(caught).toHaveLength(2); + expect(caught[1]).toBe(caught[0]); + expect(observed).toEqual([a]); + expect(yield* exists(join(fixture.checkout, "insert.md"))).toBe(false); + expect(yield* exists(join(fixture.root, "retry-outside.md"))).toBe(false); + expect(localRecords(recovered.events)).toEqual(localRecords(fresh.events)); + expect( + recovered.events.some( + (event) => + event.type === "close" && event.coroutineId === "root" && event.result.status === "ok", + ), + ).toBe(false); + expect(yield* readTextFile(join(fixture.root, b))).toBe("historical edit"); + + yield* rm(join(fixture.root, a)); + yield* rm(join(fixture.root, b)); + observed.length = 0; + const synthetic = yield* run(fixture, doc, new InMemoryStream(), counters(), { + ...placement, + between: () => install("synthetic"), + }); + expect(synthetic.refusal).toBe(undefined); + expect(localRecords(synthetic.events).map((record) => record.ordinal)).toEqual([1]); + expect(yield* exists(join(fixture.root, a))).toBe(false); + }); + + it("distinguishes equal received pairs in one coroutine and starts each child at zero", function* () { + const fixture = yield* useFixture(); + const one = ''; + const doc = [ + one, + one, + "", + '', + '', + "", + ].join("\n"); + const first = yield* run(fixture, doc, new InMemoryStream(), counters()); + expect(first.refusal).toBe(undefined); + expect( + localRecords(first.events) + .map((record) => record.ordinal) + .sort(), + ).toEqual([0, 0, 0, 1]); + const names = recordNames(first.events); + expect(new Set(names).size).toBe(4); + const resumed = yield* run(fixture, doc, unfinished(first.events), counters()); + expect(resumed.refusal).toBe(undefined); + }); + + it("refuses occupancy after a native copy whose acknowledgement was halted", function* () { + const fixture = yield* useFixture(); + const events: DurableEvent[] = []; + const reached = withResolvers(); + const barrier: DurableStream = { + *readAll(): Operation { + return [...events]; + }, + *append(event: DurableEvent): Operation { + if (event.type === "yield" && event.description.type === REPL_REPOSITORY_LOCAL) { + reached.resolve(); + yield* suspend(); + } + events.push(event); + }, + }; + yield* scoped(function* () { + const task = yield* spawn(() => run(fixture, source, barrier, counters())); + yield* reached.operation; + yield* task.halt(); + }); + expect(localRecords(events)).toEqual([]); + const target = join(fixture.checkout, "copy.md"); + const copied = yield* readTextFile(target); + expect(copied).toBe(yield* readTextFile(join(fixture.checkout, "seed.md"))); + const resumed = yield* run(fixture, source, new InMemoryStream(events), counters()); + expect(resumed.output).toContain("already exists"); + expect(localRecords(resumed.events).map((record) => record.outcome.ok)).toEqual([false]); + expect(yield* readTextFile(target)).toBe(copied); + }); + + it("records copies in the mount installation fallback and restores without live copy", function* () { + const fixture = yield* useFixture(); + const owned = join(fixture.root, "owned"); + yield* ensureDir(owned); + yield* writeTextFile(join(owned, "seed.md"), "owned seed"); + const first = yield* scoped(function* () { + yield* API.Env.around({ + *cwd() { + return owned; + }, + }); + const host = hostFilesHandler(); + yield* API.Files.around({ copyFile: ([input]) => host.copyFile(input) }, { at: "min" }); + const stream = new InMemoryStream(); + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream }, [ + workspaceMountInstallation([], undefined, undefined, owned), + ]), + ); + return yield* stream.readAll(); + }); + expect(localRecords(first).map((record) => [record.operation, record.ordinal])).toEqual([ + ["file-copy", 0], + ]); + expect(recordsOf(first, REPL_REPOSITORY_SELECTION)).toEqual([]); + yield* writeTextFile(join(owned, "copy.md"), "changed"); + yield* scoped(function* () { + yield* API.Env.around({ + *cwd() { + return owned; + }, + }); + yield* Permissions.around({ + files: () => { + throw new Error("live policy"); + }, + }); + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream: unfinished(first) }, [ + workspaceMountInstallation([], undefined, undefined, owned), + ]), + ); + }); + expect(yield* readTextFile(join(owned, "copy.md"))).toBe("changed"); + }); +}); diff --git a/packages/cli/tests/retained-repository-pull-request.test.ts b/packages/cli/tests/retained-repository-pull-request.test.ts index d5c213ed8..06b073793 100644 --- a/packages/cli/tests/retained-repository-pull-request.test.ts +++ b/packages/cli/tests/retained-repository-pull-request.test.ts @@ -627,6 +627,7 @@ function hostFiles(): FilesHandler { globFiles: (input) => host.globFiles(input), temporaryDirectory: () => host.temporaryDirectory(), writeTextFile: (input: FileWriteInput) => host.writeTextFile(input), + copyFile: (input) => host.copyFile(input), deleteFile: (input) => host.deleteFile(input), ensureDirectory: (input) => host.ensureDirectory(input), }; @@ -829,6 +830,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-push.test.ts b/packages/cli/tests/retained-repository-push.test.ts index e3ff3316b..1b88bb781 100644 --- a/packages/cli/tests/retained-repository-push.test.ts +++ b/packages/cli/tests/retained-repository-push.test.ts @@ -173,6 +173,7 @@ function hostFiles(): FilesHandler { globFiles: (input) => host.globFiles(input), temporaryDirectory: () => host.temporaryDirectory(), writeTextFile: (input: FileWriteInput) => host.writeTextFile(input), + copyFile: (input) => host.copyFile(input), deleteFile: (input) => host.deleteFile(input), ensureDirectory: (input) => host.ensureDirectory(input), }; @@ -303,6 +304,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-records.test.ts b/packages/cli/tests/retained-repository-records.test.ts index ba5e87022..0b1e6d23a 100644 --- a/packages/cli/tests/retained-repository-records.test.ts +++ b/packages/cli/tests/retained-repository-records.test.ts @@ -140,18 +140,19 @@ function* localEvent( request: ReplLocalRequest, outcome = Ok(operation === "file-write" ? fileWriteSuccess("host-committed") : undefined), name?: string, + ordinal?: number, ): Operation { - const fingerprint = yield* replLocalFingerprint({ operation, request }); + const fingerprint = yield* replLocalFingerprint({ operation, request, ordinal }); return { type: "yield", coroutineId: "root", description: { type: REPL_REPOSITORY_LOCAL, - name: name ?? replLocalRecordName({ operation, fingerprint }), + name: name ?? replLocalRecordName({ operation, fingerprint, ordinal }), }, result: { status: "ok", - value: replLocalRecordJson({ operation, fingerprint, request, outcome }), + value: replLocalRecordJson({ operation, fingerprint, request, outcome, ordinal }), }, }; } @@ -534,6 +535,46 @@ describe("which histories one entry will continue", () => { ).toBe(undefined); }); + it("admits ordered physical copies with gaps and refuses malformed occurrences", function* () { + const pair = { cwd: "/work", source: "seed", path: "copy" }; + const first = yield* localEvent("file-copy", pair, undefined, undefined, 0); + const later = yield* localEvent( + "file-copy", + pair, + Err( + filesFailure({ + operation: "copy", + phase: "target", + reason: "occupied", + }), + ), + undefined, + 3, + ); + expect(yield* refusalOf([first, { ...first, coroutineId: "root.0" }, later])).toBe(undefined); + expect((yield* refusalOf([first, first]))?.reason).toBe("malformed-record"); + expect((yield* refusalOf([later, first]))?.reason).toBe("malformed-record"); + for (const ordinal of [undefined, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) { + const invalid = yield* localEvent("file-copy", pair, undefined, undefined, ordinal); + expect((yield* refusalOf([invalid]))?.reason).toBe("malformed-record"); + } + const wrongName = yield* localEvent("file-copy", pair, undefined, "invalid name", 0); + expect((yield* refusalOf([wrongName]))?.reason).toBe("request-fingerprint"); + for (const extra of [{ extra: true }, { fingerprint: "tampered" }]) { + expect( + yield* refusalOf([ + { + ...first, + result: { + status: "ok", + value: { ...Object(saved(first)), ...extra }, + }, + }, + ]), + ).toBeDefined(); + } + }); + it("refuses a record whose request no longer produces its name", function* () { const event = yield* localEvent("file-write", WRITE); // The request is changed after the work was saved, which is the one way a diff --git a/packages/cli/tests/retained-repository-selection.test.ts b/packages/cli/tests/retained-repository-selection.test.ts index fbdbb9d3b..7a3cac74e 100644 --- a/packages/cli/tests/retained-repository-selection.test.ts +++ b/packages/cli/tests/retained-repository-selection.test.ts @@ -164,6 +164,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -306,6 +307,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts index 5c6f339f5..3258ec8be 100644 --- a/packages/cli/tests/syntax-cli.test.ts +++ b/packages/cli/tests/syntax-cli.test.ts @@ -25,9 +25,19 @@ import { randomUUID } from "node:crypto"; import { platform, tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { API } from "@executablemd/runtime"; -import { CORE_COMPONENT_NAMES } from "@executablemd/core"; +import { + capturedDocumentation, + CORE_COMPONENT_NAMES, + documentationIndexFor, +} from "@executablemd/core"; +import { Syntax } from "@executablemd/core/api"; import type { PropsSchema, SyntaxSymbols } from "@executablemd/core"; -import { renderSyntaxJson, renderSyntaxMarkdown, syntaxSymbols } from "../src/syntax.ts"; +import { + renderSyntaxJson, + renderSyntaxMarkdown, + syntaxSymbols, + useCommandSyntax, +} from "../src/syntax.ts"; import { installPlugins } from "../src/plugin-host.ts"; import { BUNDLED_PLUGIN } from "../src/run-profile.ts"; @@ -283,9 +293,16 @@ describe("Tier SX — the run profile the command describes", () => { }); it("SX2: documents every complete built-in in the profile", function* () { - const catalog = yield* syntaxSymbols([]); + const { catalog, docs } = yield* scoped(function* () { + yield* useCommandSyntax([]); + return { + catalog: yield* Syntax.operations.symbols, + docs: documentationIndexFor(yield* capturedDocumentation()), + }; + }); const undocumented = catalog.categories[1].entries.filter( - (entry) => entry.description === undefined || entry.description.trim().length === 0, + (entry) => + !entry.description?.trim() && !docs.documentationFor(entry.name, entry.origin)?.trim(), ); expect(names(undocumented)).toEqual([]); @@ -563,6 +580,28 @@ describe("Tier SX — the command line", { sanitizeOps: false, sanitizeResources expect(unknown.stdout).toBe(""); }); + it("SX16: named File.Copy shows concise usage and two required paths", function* () { + const named = yield* runCli(["syntax", "File.Copy"], { cwd: "." }).expect(); + for (const text of [ + "**Forms:** ``", + "| `from` | `string` | yes |", + "| `to` | `string` | yes |", + [ + "Copy a file into an existing directory.", + "", + "```mdx", + '', + "```", + ].join("\n"), + ]) { + expect(named.stdout).toContain(text); + } + expect(named.stdout.match(/Copy a file into an existing directory\./g)).toHaveLength(1); + expect(named.stdout).not.toMatch( + /replay|working directory|occupied destination|<\/File.Copy>/i, + ); + }); + it("SX16: engine and selected installed structural names match canonical component references", function* () { const plugin = new URL("./fixtures/plugins/structural-reference.mjs", import.meta.url).pathname; for (const name of ["If", "All", "Banner", "BannerLine"]) { diff --git a/packages/core/src/components/FileCopy.ts b/packages/core/src/components/FileCopy.ts new file mode 100644 index 000000000..be698634d --- /dev/null +++ b/packages/core/src/components/FileCopy.ts @@ -0,0 +1,31 @@ +import { cwd, parseFilesFailure } from "@executablemd/runtime"; +import { printErrors } from "../component-failures.ts"; +import { copyFile } from "../files.ts"; +import type { FormDeclaration } from "../invocation-identity.ts"; +import { reason } from "./fs-error-phrases.ts"; + +export const props = { + type: "object", + properties: { + from: { type: "string", minLength: 1 }, + to: { type: "string", minLength: 1 }, + }, + required: ["from", "to"], + additionalProperties: false, +}; + +export const form: FormDeclaration = { + forms: "self-closing", + refuse: () => new Error(" requires a self-closing invocation."), + fn: printErrors(function* (props) { + const result = yield* copyFile({ + cwd: yield* cwd(), + source: String(props.from), + destination: String(props.to), + }); + if (!result.ok) { + throw new Error(`Cannot copy file: ${reason(parseFilesFailure(result.error)?.reason)}.`); + } + return ""; + }), +}; diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md index ea2879324..0df256ae9 100644 --- a/packages/core/src/components/components.md +++ b/packages/core/src/components/components.md @@ -2,9 +2,8 @@ Long-form documentation for the components canonical core owns. Each level-two heading below is the exact name of one component. The compact list of symbols — `xmd syntax`, or a bare `` — names every component -with its forms, props and one-line description. This file holds the part that -does not belong in a list: when to reach for a component, what it does at run -time, and what it will refuse. +with its forms, props and any description from its registration. Named help +adds the usage from this file. Every component this package supplies has a section here. A build in which one does not refuses rather than serving a reference with a silent hole in it: a @@ -22,10 +21,8 @@ is written. ``` The bare form lists the symbols available here: every name a document may write -at that site, with its forms, props and description. It is the same text -`xmd syntax` prints, built by the same code, so an operator reading a terminal -and an agent reading a document are never told different things about one -profile. +at that site, with its forms, props and any registered description. It prints +the same text as `xmd syntax` for that profile. ```mdx @@ -177,6 +174,14 @@ read rather than re-reading a file that has since changed. A read of a path that does not exist fails. The write form creates the file and the directories above it as needed. +## File.Copy + +Copy a file into an existing directory. + +```mdx + +``` + ## File.Delete Deletes a file, relative to the working directory. diff --git a/packages/core/src/components/documentation.ts b/packages/core/src/components/documentation.ts index a33144dde..78c05b98d 100644 --- a/packages/core/src/components/documentation.ts +++ b/packages/core/src/components/documentation.ts @@ -20,18 +20,12 @@ export interface ComponentDocumentation { /** * The same prose, as a first-party declaration is required to state it. * - * `as` and `context` are `string | null` rather than optional, so a first-party - * declaration decides whether each one applies instead of leaving an omitted - * field to mean either "not applicable" or "forgotten". `null` is the explicit - * "this component takes no binding" / "this component reads no content", and it - * contributes no field to the public catalog. - * - * The public registration contract stays the optional strings above: this is - * the discipline first-party packages hold themselves to, not a rule imposed on - * anybody who registers a component. + * Each field is explicit. Use `null` for a description supplied by the package's + * `components.md`, for a component with no binding to describe, or for one that + * reads no content. A null field is omitted from the public catalog. */ export interface FirstPartyDocumentation { - readonly description: string; + readonly description: string | null; readonly as: string | null; readonly context: string | null; } @@ -40,7 +34,7 @@ export interface FirstPartyDocumentation { export function documented(documentation: FirstPartyDocumentation): ComponentDocumentation { const { description, as, context } = documentation; return { - description, + ...(description === null ? {} : { description }), ...(as === null ? {} : { as }), ...(context === null ? {} : { context }), }; diff --git a/packages/core/src/components/fs-error-phrases.ts b/packages/core/src/components/fs-error-phrases.ts index 4a1506f79..1ea2b79ac 100644 --- a/packages/core/src/components/fs-error-phrases.ts +++ b/packages/core/src/components/fs-error-phrases.ts @@ -28,6 +28,7 @@ import type { FilesReason } from "@executablemd/runtime"; * directory or a special file, and a pattern that cannot be compiled. */ const PHRASES: ReadonlyMap = new Map([ + ["occupied", "the destination already exists"], ["missing", "no such file or directory"], ["not-directory", "a component of the path is not a directory"], ["directory", "it is a directory"], diff --git a/packages/core/src/components/registry.ts b/packages/core/src/components/registry.ts index b14aced37..ce7fa7342 100644 --- a/packages/core/src/components/registry.ts +++ b/packages/core/src/components/registry.ts @@ -32,6 +32,7 @@ import Cwd, { props as cwdProps, generated as cwdGenerated } from "./Cwd.ts"; import TempDir, { props as tempDirProps } from "./TempDir.ts"; import { form as failForm, props as failProps } from "./Fail.ts"; import Fetch, { generated as fetchGenerated, props as fetchProps } from "./Fetch.ts"; +import { form as fileCopyForm, props as fileCopyProps } from "./FileCopy.ts"; import Glob, { generated as globGenerated, props as globProps, @@ -102,9 +103,8 @@ interface CoreOptions { * * The accepted forms are read off that same declaration rather than restated, * so ``'s and ``'s one accepted form each is documented by the - * value that dispatches it. Documentation is a parameter rather than an option - * because a core default states what it is for, and says explicitly whether - * `as` and content apply to it. + * value that dispatches it. Each registration specifies which prose it + * contributes to the catalog. */ function core( name: string, @@ -232,6 +232,11 @@ export const CORE_REGISTRY: ComponentRegistry = new Map([ generated: fetchGenerated, }, ), + core("File.Copy", fileCopyForm, parseJsonObject(fileCopyProps), { + description: null, + as: null, + context: null, + }), core( "Glob", Glob, diff --git a/packages/core/src/files.ts b/packages/core/src/files.ts index 830106edc..97361ac6d 100644 --- a/packages/core/src/files.ts +++ b/packages/core/src/files.ts @@ -31,6 +31,7 @@ import { parseFilesFailure, } from "@executablemd/runtime"; import type { + FileCopyInput, FilePathInput, FilesOperation, FilesPhase, @@ -322,6 +323,10 @@ export function deleteFile(input: FilePathInput): Operation> { return unit(Files.operations.deleteFile(input), { operation: "delete", phase: "access" }); } +export function copyFile(input: FileCopyInput): Operation> { + return unit(Files.operations.copyFile(input), { operation: "copy", phase: "access" }); +} + /** * Make this authored path name a directory, with nothing coming back. * diff --git a/packages/core/tests/fixtures/syntax-generated-base.json b/packages/core/tests/fixtures/syntax-generated-base.json index 3e6e806d7..6cb9bf1c5 100644 --- a/packages/core/tests/fixtures/syntax-generated-base.json +++ b/packages/core/tests/fixtures/syntax-generated-base.json @@ -1,10 +1,10 @@ { "fragment-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n", "root-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `test://provider` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n", - "canonical-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", - "catalog-base.json": "{\"version\":1,\"categories\":[{\"kind\":\"structural\",\"entries\":[{\"kind\":\"structural\",\"name\":\"All\",\"origin\":{\"kind\":\"structural\",\"construct\":\"All\"},\"syntax\":[\"……\"],\"description\":\"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\"context\":\"The `` children this runs at the same time.\"},{\"kind\":\"structural\",\"name\":\"Answer\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answer\"},\"syntax\":[\"\",\"…\"],\"description\":\"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\"context\":\"A multiline template, in place of the single-line `template` prop.\"},{\"kind\":\"structural\",\"name\":\"Answers\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answers\"},\"syntax\":[\"…\"],\"description\":\"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\"context\":\"`` matchers, and the body they answer for.\"},{\"kind\":\"structural\",\"name\":\"Break\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Break\"},\"syntax\":[\"\"],\"description\":\"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"},{\"kind\":\"structural\",\"name\":\"Case\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Case\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\"context\":\"Markdown expanded when this case is selected.\"},{\"kind\":\"structural\",\"name\":\"Catch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Catch\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\"as\":\"Optional. Binds the ordinary Error by reference in this branch.\",\"context\":\"Recovery content.\"},{\"kind\":\"structural\",\"name\":\"Content\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Content\"},\"syntax\":[\"\",\"\"],\"description\":\"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"},{\"kind\":\"structural\",\"name\":\"Each\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Each\"},\"syntax\":[\"…\"],\"description\":\"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\"as\":\"Optional. Captures the whole rendered loop instead of emitting it.\",\"context\":\"Markdown rendered once per element.\"},{\"kind\":\"structural\",\"name\":\"Else\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Else\"},\"syntax\":[\"…\"],\"description\":\"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\"context\":\"The branch taken when the enclosing condition does not hold.\"},{\"kind\":\"structural\",\"name\":\"Finally\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Finally\"},\"syntax\":[\"…\"],\"description\":\"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\"context\":\"Completion content using the surrounding bindings.\"},{\"kind\":\"structural\",\"name\":\"If\",\"origin\":{\"kind\":\"structural\",\"construct\":\"If\"},\"syntax\":[\"…\"],\"description\":\"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\"context\":\"The branch taken when the condition holds, up to an ``.\"},{\"kind\":\"structural\",\"name\":\"Let\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Let\"},\"syntax\":[\"…\",\"\"],\"description\":\"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\"as\":\"Required. The binding name the value is available under.\",\"context\":\"Markdown whose rendered text becomes the binding, in the paired form.\"},{\"kind\":\"structural\",\"name\":\"Loop\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Loop\"},\"syntax\":[\"…\"],\"description\":\"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\"context\":\"Markdown expanded once per iteration.\"},{\"kind\":\"structural\",\"name\":\"Output\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Output\"},\"syntax\":[\"…\"],\"description\":\"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\"context\":\"The rendered output the run presents.\"},{\"kind\":\"structural\",\"name\":\"PrintErrors\",\"origin\":{\"kind\":\"structural\",\"construct\":\"PrintErrors\"},\"syntax\":[\"…\"],\"description\":\"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\"context\":\"The region whose failures are printed rather than raised.\"},{\"kind\":\"structural\",\"name\":\"Return\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Return\"},\"syntax\":[\"\"],\"description\":\"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"},{\"kind\":\"structural\",\"name\":\"Spawn\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Spawn\"},\"syntax\":[\"…\"],\"description\":\"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\"context\":\"Markdown expanded in its own child, beside its siblings.\"},{\"kind\":\"structural\",\"name\":\"Switch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Switch\"},\"syntax\":[\"…\"],\"description\":\"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\"context\":\"Direct `` branches considered in source order.\"},{\"kind\":\"structural\",\"name\":\"Try\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Try\"},\"syntax\":[\"………\"],\"description\":\"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\"context\":\"Attempted content followed by direct Catch and Finally branches.\"}]},{\"kind\":\"built-in\",\"entries\":[{\"kind\":\"component\",\"name\":\"CodeBlock\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{\"type\":\"string\"},\"language\":{\"type\":\"string\",\"pattern\":\"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"}},\"required\":[\"value\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\"as\":\"Optional. Captures the exact fenced Markdown instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Cwd\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read the working directory. `` renders its path without adding a newline.\",\"as\":\"Optional. Captures the directory path instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Dir\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Create or use a directory. `…` changes the working directory for its content.\",\"context\":\"The Markdown expanded in that directory.\"},{\"kind\":\"component\",\"name\":\"Elicit\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Ask a person a structured question. `…` shows the content as the request.\",\"as\":\"Required. The validated answer, as a structured value.\",\"context\":\"The request message the person is shown.\"},{\"kind\":\"component\",\"name\":\"Evaluate\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"text\":{\"type\":\"string\",\"description\":\"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"},\"allow\":{\"type\":\"array\",\"minItems\":1,\"uniqueItems\":true,\"items\":{\"enum\":[\"read\",\"write\"]},\"description\":\"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Evaluate program text. `` runs it.\",\"as\":\"Optional. Captures the fragment's rendered output instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Fail\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"message\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"message\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Stop authored work with an actionable failure. `` raises the message where it is written.\"},{\"kind\":\"component\",\"name\":\"Fetch\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"url\":{\"type\":\"string\"},\"method\":{\"type\":\"string\"},\"headers\":{\"type\":\"object\",\"additionalProperties\":{\"type\":\"string\"}},\"timeout\":{\"type\":\"string\"}},\"required\":[\"url\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\"as\":\"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"},{\"kind\":\"component\",\"name\":\"File\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\"as\":\"Optional. Captures the file's text instead of emitting it, in the reading form.\",\"context\":\"The text to write, in the writing form.\"},{\"kind\":\"component\",\"name\":\"File.Delete\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\"as\":\"Optional. Captures the empty string this renders, as for any text component.\"},{\"kind\":\"component\",\"name\":\"Glob\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"include\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1},\"exclude\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"default\":[]}},\"required\":[\"include\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"description\":\"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\"as\":\"Required. The matched paths, as a string array.\"},{\"kind\":\"component\",\"name\":\"Json\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as JSON text. `` writes the JSON where you put it.\",\"as\":\"Optional. Captures the JSON text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Parse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\"as\":\"Required. The validated value.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Query\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{},\"yq\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"value\",\"yq\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\"as\":\"Optional. Binds the selected value as data instead of writing it as JSON.\"},{\"kind\":\"component\",\"name\":\"SafeParse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"oneOf\":[{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":true},\"value\":{}},\"required\":[\"ok\",\"value\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":false},\"input\":{\"type\":\"string\"},\"errors\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"instancePath\":{\"type\":\"string\"},\"schemaPath\":{\"type\":\"string\"},\"keyword\":{\"type\":\"string\"},\"params\":{},\"message\":{\"type\":\"string\"}},\"required\":[\"instancePath\",\"schemaPath\",\"keyword\",\"params\",\"message\"],\"additionalProperties\":false}}},\"required\":[\"ok\",\"input\",\"errors\"],\"additionalProperties\":false}]},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\"as\":\"Required. The result: either the validated value or the issues that rejected it.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Slice\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"offset\":{\"type\":\"integer\",\"default\":0},\"length\":{\"type\":\"integer\",\"minimum\":1,\"default\":4096}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\"as\":\"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\"context\":\"The content whose completed rendering the window is taken from.\"},{\"kind\":\"component\",\"name\":\"Syntax\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1,\"uniqueItems\":true,\"description\":\"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\"as\":\"Optional. Captures the rendered text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"TempDir\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\"as\":\"Optional. Captures the rendered directory path instead of emitting it.\",\"context\":\"Markdown expanded with the temporary directory as its working directory.\"},{\"kind\":\"component\",\"name\":\"Test\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"timeout\":{\"type\":\"string\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\"context\":\"The body of the test: its assertions and the work they judge.\"},{\"kind\":\"component\",\"name\":\"Yaml\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as YAML text. `` writes the YAML where you put it.\",\"as\":\"Optional. Captures the YAML text instead of emitting it.\"}]},{\"kind\":\"user-provided\",\"entries\":[]}]}", - "ordinary-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `AGENTS.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | yes | Workspace package directory, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package directory, e.g. packages/workflow\"\n }\n },\n \"required\": [\n \"package\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `components/BootstrapNpmPackage.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | no | Workspace package to reserve on npm, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package to reserve on npm, e.g. packages/workflow\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `README.md`\n", - "cli-bare-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nSet the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches use this agent.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSet the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `defaultAgent` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown expanded with this provider installed.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nApprove every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are approved.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAsk about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are asked about.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAssert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `message` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\n\n**Body context:** The Markdown expected to fail.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCapture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The journal snapshot.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCapture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The child's accumulated output.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGive a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `host` | `string` | yes | |\n| `target` | `string` | no | |\n| `source` | `string` | no | |\n| `action` | `string` | no | |\n| `props` | `object` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\n\n**Body context:** The declarations for the child, then the assertions about it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStage paths for commit. `` resolves Git pathspecs from the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCompare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, each change's path, status and previous path, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCommit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | no | |\n| `ref` | `string` | no | |\n| `verify` | `boolean` | no | |\n| `yq` | `string` | no | |\n| `maxBytes` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\n\n**Body context:** The message body, expanded before the commit is made. A ref read takes none.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a comparison's patch. `` reads a window of the unified diff text.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a committed file. `` reads the text that commit holds, not the working copy.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `commit` | `string` | yes | |\n| `path` | `string` | yes | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `prefix` | `string` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The tracked paths, and the arguments of the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nPublish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSwitch or create a branch. `` starts a missing branch at the specified base.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | no | |\n| `title` | `string` | no | |\n| `tags` | `array` | no | |\n| `assignee` | `string` | no | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\n\n**Body context:** The issue's description, for the form that files one.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect an issue tracker. `…` expands its content with the specified tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown whose issues are filed there.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGenerate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\n\n**Body context:** The complete prompt, expanded once before authorship.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli/Plan.md` (declared Markdown)\n\n### ``\n\nSend a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n| `timeout` | `string` | no | |\n| `throwOnError` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the reply instead of emitting it.\n\n**Body context:** The prompt text, in the paired form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nOpen or update a pull request. `…` uses its content as the body after ``.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `number` | `integer` | no | |\n| `title` | `string` | yes | |\n| `base` | `string` | no | |\n| `draft` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The pull request's repository, number, url, state and head and base commits.\n\n**Body context:** The pull request's body.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request checks. `` reads check runs and commit statuses for its head.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each check's kind, name, head commit and outcome.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request comments. `` reads both conversation and review comments.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request reviews. `` reads reviews from the specified pull request.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each review's author, state, body, submission time, commit and url.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nClone or use a repository. `…` expands its content in the specified checkout.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `url` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the selected checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nConfigure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `model` | `string` | no | |\n| `effort` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches run in this session.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nLaunch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The instructions the native session starts from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nTurn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in testing mode.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nExpand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli` (registered default)\n\n### ``\n\nAsk a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n| `uiSchema` | JSON Schema | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated response.\n\n**Body context:** The Markdown shown above the form.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{}\n```\n\n**Origin:** `@executablemd/web` (registered default)\n\n### ``\n\nScope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The workflow-hosted executions this scope owns.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a worktree. `…` expands its content in the worktree.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the linked checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", - "cli-json-base.txt": "{\n \"version\": 1,\n \"categories\": [\n {\n \"kind\": \"structural\",\n \"entries\": [\n {\n \"kind\": \"structural\",\n \"name\": \"All\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"All\"\n },\n \"syntax\": [\n \"……\"\n ],\n \"description\": \"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\n \"context\": \"The `` children this runs at the same time.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answer\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answer\"\n },\n \"syntax\": [\n \"\",\n \"…\"\n ],\n \"description\": \"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\n \"context\": \"A multiline template, in place of the single-line `template` prop.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answers\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answers\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\n \"context\": \"`` matchers, and the body they answer for.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Break\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Break\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Case\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Case\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\n \"context\": \"Markdown expanded when this case is selected.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Catch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Catch\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\n \"as\": \"Optional. Binds the ordinary Error by reference in this branch.\",\n \"context\": \"Recovery content.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Content\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Content\"\n },\n \"syntax\": [\n \"\",\n \"\"\n ],\n \"description\": \"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Each\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Each\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\n \"as\": \"Optional. Captures the whole rendered loop instead of emitting it.\",\n \"context\": \"Markdown rendered once per element.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Else\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Else\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\n \"context\": \"The branch taken when the enclosing condition does not hold.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Finally\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Finally\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\n \"context\": \"Completion content using the surrounding bindings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"If\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"If\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\n \"context\": \"The branch taken when the condition holds, up to an ``.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Let\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Let\"\n },\n \"syntax\": [\n \"…\",\n \"\"\n ],\n \"description\": \"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\n \"as\": \"Required. The binding name the value is available under.\",\n \"context\": \"Markdown whose rendered text becomes the binding, in the paired form.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Loop\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Loop\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\n \"context\": \"Markdown expanded once per iteration.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Output\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Output\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\n \"context\": \"The rendered output the run presents.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"PrintErrors\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"PrintErrors\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\n \"context\": \"The region whose failures are printed rather than raised.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Return\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Return\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Spawn\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Spawn\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\n \"context\": \"Markdown expanded in its own child, beside its siblings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Switch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Switch\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\n \"context\": \"Direct `` branches considered in source order.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Try\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Try\"\n },\n \"syntax\": [\n \"………\"\n ],\n \"description\": \"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\n \"context\": \"Attempted content followed by direct Catch and Finally branches.\"\n }\n ]\n },\n {\n \"kind\": \"built-in\",\n \"entries\": [\n {\n \"kind\": \"component\",\n \"name\": \"Agent\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\",\n \"context\": \"Markdown whose prompts and launches use this agent.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AgentProvider\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\",\n \"context\": \"Markdown expanded with this provider installed.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"ApproveAll\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Approve every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\",\n \"context\": \"Markdown whose permission requests are approved.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AskPermission\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Ask about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\",\n \"context\": \"Markdown whose permission requests are asked about.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Assert\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertExists\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertFalse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreater\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreaterOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLess\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLessOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStringIncludes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertThrows\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"message\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\",\n \"as\": \"Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\",\n \"context\": \"The Markdown expected to fail.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CodeBlock\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\n \"as\": \"Optional. Captures the exact fenced Markdown instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\",\n \"as\": \"Required. The journal snapshot.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectOutput\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\",\n \"as\": \"Required. The child's accumulated output.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Cwd\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read the working directory. `` renders its path without adding a newline.\",\n \"as\": \"Optional. Captures the directory path instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"DiagnosticJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Give a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Dir\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a directory. `…` changes the working directory for its content.\",\n \"context\": \"The Markdown expanded in that directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Elicit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Ask a person a structured question. `…` shows the content as the request.\",\n \"as\": \"Required. The validated answer, as a structured value.\",\n \"context\": \"The request message the person is shown.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Evaluate\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Evaluate program text. `` runs it.\",\n \"as\": \"Optional. Captures the fragment's rendered output instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Execution\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\",\n \"as\": \"Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\",\n \"context\": \"The declarations for the child, then the assertions about it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fail\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stop authored work with an actionable failure. `` raises the message where it is written.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fetch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\n \"as\": \"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\n \"as\": \"Optional. Captures the file's text instead of emitting it, in the reading form.\",\n \"context\": \"The text to write, in the writing form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Delete\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\n \"as\": \"Optional. Captures the empty string this renders, as for any text component.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Add\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stage paths for commit. `` resolves Git pathspecs from the working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Changes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Compare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\",\n \"as\": \"Required. The comparison, each change's path, status and previous path, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Commit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Commit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\",\n \"as\": \"Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\",\n \"context\": \"The message body, expanded before the commit is made. A ref read takes none.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Diff\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a comparison's patch. `` reads a window of the unified diff text.\",\n \"as\": \"Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.File\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a committed file. `` reads the text that commit holds, not the working copy.\",\n \"as\": \"Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Files\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"List tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\",\n \"as\": \"Required. The tracked paths, and the arguments of the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Push\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Publish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Switch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Switch or create a branch. `` starts a missing branch at the specified base.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Glob\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"description\": \"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\n \"as\": \"Required. The matched paths, as a string array.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Issue\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Read or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\",\n \"as\": \"Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\",\n \"context\": \"The issue's description, for the form that files one.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"IssueTracker\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select an issue tracker. `…` expands its content with the specified tracker in scope.\",\n \"context\": \"The Markdown whose issues are filed there.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Json\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as JSON text. `` writes the JSON where you put it.\",\n \"as\": \"Optional. Captures the JSON text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Parse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\n \"as\": \"Required. The validated value.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Plan\",\n \"origin\": {\n \"kind\": \"declared-markdown\",\n \"origin\": \"@executablemd/cli/Plan.md\",\n \"digest\": \"d97953c7f65cde0a2858761245d94e06cd31aaba6feb15622256d4dddcaafec2\"\n },\n \"sourceKind\": \"declared-markdown\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Generate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\",\n \"as\": \"Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\",\n \"context\": \"The complete prompt, expanded once before authorship.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Prompt\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Send a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\",\n \"as\": \"Optional. Captures the reply instead of emitting it.\",\n \"context\": \"The prompt text, in the paired form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Open or update a pull request. `…` uses its content as the body after ``.\",\n \"as\": \"Optional. The pull request's repository, number, url, state and head and base commits.\",\n \"context\": \"The pull request's body.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Checks\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request checks. `` reads check runs and commit statuses for its head.\",\n \"as\": \"Required. Each check's kind, name, head commit and outcome.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Comments\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request comments. `` reads both conversation and review comments.\",\n \"as\": \"Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Reviews\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n },\n \"description\": \"Read pull request reviews. `` reads reviews from the specified pull request.\",\n \"as\": \"Required. Each review's author, state, body, submission time, commit and url.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Query\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\n \"as\": \"Optional. Binds the selected value as data instead of writing it as JSON.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Repository\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Clone or use a repository. `…` expands its content in the specified checkout.\",\n \"as\": \"Optional. The path of the selected checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"SafeParse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\n \"as\": \"Required. The result: either the validated value or the issues that rejected it.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Configure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\",\n \"context\": \"Markdown whose prompts and launches run in this session.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session.Launch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Launch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\",\n \"context\": \"The instructions the native session starts from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Slice\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\n \"as\": \"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\n \"context\": \"The content whose completed rendering the window is taken from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Syntax\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\n \"as\": \"Optional. Captures the rendered text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"TempDir\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\n \"as\": \"Optional. Captures the rendered directory path instead of emitting it.\",\n \"context\": \"Markdown expanded with the temporary directory as its working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Test\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\n \"context\": \"The body of the test: its assertions and the work they judge.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Testing\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Turn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\",\n \"context\": \"The Markdown expanded in testing mode.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Verbose\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/cli\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Expand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\",\n \"as\": \"Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WebForm\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/web\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {},\n \"description\": \"Ask a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\",\n \"as\": \"Required. The validated response.\",\n \"context\": \"The Markdown shown above the form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WorkflowRun\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Scope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\",\n \"context\": \"The workflow-hosted executions this scope owns.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Worktree\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a worktree. `…` expands its content in the worktree.\",\n \"as\": \"Optional. The path of the linked checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Yaml\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as YAML text. `` writes the YAML where you put it.\",\n \"as\": \"Optional. Captures the YAML text instead of emitting it.\"\n }\n ]\n },\n {\n \"kind\": \"user-provided\",\n \"entries\": []\n }\n ]\n}\n", + "canonical-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", + "catalog-base.json": "{\"version\":1,\"categories\":[{\"kind\":\"structural\",\"entries\":[{\"kind\":\"structural\",\"name\":\"All\",\"origin\":{\"kind\":\"structural\",\"construct\":\"All\"},\"syntax\":[\"……\"],\"description\":\"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\"context\":\"The `` children this runs at the same time.\"},{\"kind\":\"structural\",\"name\":\"Answer\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answer\"},\"syntax\":[\"\",\"…\"],\"description\":\"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\"context\":\"A multiline template, in place of the single-line `template` prop.\"},{\"kind\":\"structural\",\"name\":\"Answers\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answers\"},\"syntax\":[\"…\"],\"description\":\"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\"context\":\"`` matchers, and the body they answer for.\"},{\"kind\":\"structural\",\"name\":\"Break\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Break\"},\"syntax\":[\"\"],\"description\":\"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"},{\"kind\":\"structural\",\"name\":\"Case\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Case\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\"context\":\"Markdown expanded when this case is selected.\"},{\"kind\":\"structural\",\"name\":\"Catch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Catch\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\"as\":\"Optional. Binds the ordinary Error by reference in this branch.\",\"context\":\"Recovery content.\"},{\"kind\":\"structural\",\"name\":\"Content\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Content\"},\"syntax\":[\"\",\"\"],\"description\":\"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"},{\"kind\":\"structural\",\"name\":\"Each\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Each\"},\"syntax\":[\"…\"],\"description\":\"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\"as\":\"Optional. Captures the whole rendered loop instead of emitting it.\",\"context\":\"Markdown rendered once per element.\"},{\"kind\":\"structural\",\"name\":\"Else\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Else\"},\"syntax\":[\"…\"],\"description\":\"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\"context\":\"The branch taken when the enclosing condition does not hold.\"},{\"kind\":\"structural\",\"name\":\"Finally\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Finally\"},\"syntax\":[\"…\"],\"description\":\"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\"context\":\"Completion content using the surrounding bindings.\"},{\"kind\":\"structural\",\"name\":\"If\",\"origin\":{\"kind\":\"structural\",\"construct\":\"If\"},\"syntax\":[\"…\"],\"description\":\"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\"context\":\"The branch taken when the condition holds, up to an ``.\"},{\"kind\":\"structural\",\"name\":\"Let\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Let\"},\"syntax\":[\"…\",\"\"],\"description\":\"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\"as\":\"Required. The binding name the value is available under.\",\"context\":\"Markdown whose rendered text becomes the binding, in the paired form.\"},{\"kind\":\"structural\",\"name\":\"Loop\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Loop\"},\"syntax\":[\"…\"],\"description\":\"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\"context\":\"Markdown expanded once per iteration.\"},{\"kind\":\"structural\",\"name\":\"Output\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Output\"},\"syntax\":[\"…\"],\"description\":\"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\"context\":\"The rendered output the run presents.\"},{\"kind\":\"structural\",\"name\":\"PrintErrors\",\"origin\":{\"kind\":\"structural\",\"construct\":\"PrintErrors\"},\"syntax\":[\"…\"],\"description\":\"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\"context\":\"The region whose failures are printed rather than raised.\"},{\"kind\":\"structural\",\"name\":\"Return\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Return\"},\"syntax\":[\"\"],\"description\":\"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"},{\"kind\":\"structural\",\"name\":\"Spawn\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Spawn\"},\"syntax\":[\"…\"],\"description\":\"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\"context\":\"Markdown expanded in its own child, beside its siblings.\"},{\"kind\":\"structural\",\"name\":\"Switch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Switch\"},\"syntax\":[\"…\"],\"description\":\"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\"context\":\"Direct `` branches considered in source order.\"},{\"kind\":\"structural\",\"name\":\"Try\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Try\"},\"syntax\":[\"………\"],\"description\":\"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\"context\":\"Attempted content followed by direct Catch and Finally branches.\"}]},{\"kind\":\"built-in\",\"entries\":[{\"kind\":\"component\",\"name\":\"CodeBlock\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{\"type\":\"string\"},\"language\":{\"type\":\"string\",\"pattern\":\"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"}},\"required\":[\"value\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\"as\":\"Optional. Captures the exact fenced Markdown instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Cwd\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read the working directory. `` renders its path without adding a newline.\",\"as\":\"Optional. Captures the directory path instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Dir\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Create or use a directory. `…` changes the working directory for its content.\",\"context\":\"The Markdown expanded in that directory.\"},{\"kind\":\"component\",\"name\":\"Elicit\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Ask a person a structured question. `…` shows the content as the request.\",\"as\":\"Required. The validated answer, as a structured value.\",\"context\":\"The request message the person is shown.\"},{\"kind\":\"component\",\"name\":\"Evaluate\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"text\":{\"type\":\"string\",\"description\":\"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"},\"allow\":{\"type\":\"array\",\"minItems\":1,\"uniqueItems\":true,\"items\":{\"enum\":[\"read\",\"write\"]},\"description\":\"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Evaluate program text. `` runs it.\",\"as\":\"Optional. Captures the fragment's rendered output instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Fail\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"message\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"message\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Stop authored work with an actionable failure. `` raises the message where it is written.\"},{\"kind\":\"component\",\"name\":\"Fetch\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"url\":{\"type\":\"string\"},\"method\":{\"type\":\"string\"},\"headers\":{\"type\":\"object\",\"additionalProperties\":{\"type\":\"string\"}},\"timeout\":{\"type\":\"string\"}},\"required\":[\"url\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\"as\":\"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"},{\"kind\":\"component\",\"name\":\"File\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\"as\":\"Optional. Captures the file's text instead of emitting it, in the reading form.\",\"context\":\"The text to write, in the writing form.\"},{\"kind\":\"component\",\"name\":\"File.Copy\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"from\":{\"type\":\"string\",\"minLength\":1},\"to\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"from\",\"to\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"}},{\"kind\":\"component\",\"name\":\"File.Delete\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\"as\":\"Optional. Captures the empty string this renders, as for any text component.\"},{\"kind\":\"component\",\"name\":\"Glob\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"include\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1},\"exclude\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"default\":[]}},\"required\":[\"include\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"description\":\"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\"as\":\"Required. The matched paths, as a string array.\"},{\"kind\":\"component\",\"name\":\"Json\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as JSON text. `` writes the JSON where you put it.\",\"as\":\"Optional. Captures the JSON text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Parse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\"as\":\"Required. The validated value.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Query\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{},\"yq\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"value\",\"yq\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\"as\":\"Optional. Binds the selected value as data instead of writing it as JSON.\"},{\"kind\":\"component\",\"name\":\"SafeParse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"oneOf\":[{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":true},\"value\":{}},\"required\":[\"ok\",\"value\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":false},\"input\":{\"type\":\"string\"},\"errors\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"instancePath\":{\"type\":\"string\"},\"schemaPath\":{\"type\":\"string\"},\"keyword\":{\"type\":\"string\"},\"params\":{},\"message\":{\"type\":\"string\"}},\"required\":[\"instancePath\",\"schemaPath\",\"keyword\",\"params\",\"message\"],\"additionalProperties\":false}}},\"required\":[\"ok\",\"input\",\"errors\"],\"additionalProperties\":false}]},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\"as\":\"Required. The result: either the validated value or the issues that rejected it.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Slice\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"offset\":{\"type\":\"integer\",\"default\":0},\"length\":{\"type\":\"integer\",\"minimum\":1,\"default\":4096}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\"as\":\"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\"context\":\"The content whose completed rendering the window is taken from.\"},{\"kind\":\"component\",\"name\":\"Syntax\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1,\"uniqueItems\":true,\"description\":\"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\"as\":\"Optional. Captures the rendered text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"TempDir\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\"as\":\"Optional. Captures the rendered directory path instead of emitting it.\",\"context\":\"Markdown expanded with the temporary directory as its working directory.\"},{\"kind\":\"component\",\"name\":\"Test\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"timeout\":{\"type\":\"string\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\"context\":\"The body of the test: its assertions and the work they judge.\"},{\"kind\":\"component\",\"name\":\"Yaml\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as YAML text. `` writes the YAML where you put it.\",\"as\":\"Optional. Captures the YAML text instead of emitting it.\"}]},{\"kind\":\"user-provided\",\"entries\":[]}]}", + "ordinary-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `AGENTS.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | yes | Workspace package directory, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package directory, e.g. packages/workflow\"\n }\n },\n \"required\": [\n \"package\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `components/BootstrapNpmPackage.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | no | Workspace package to reserve on npm, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package to reserve on npm, e.g. packages/workflow\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `README.md`\n", + "cli-bare-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nSet the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches use this agent.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSet the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `defaultAgent` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown expanded with this provider installed.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nApprove every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are approved.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAsk about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are asked about.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAssert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `message` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\n\n**Body context:** The Markdown expected to fail.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCapture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The journal snapshot.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCapture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The child's accumulated output.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGive a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `host` | `string` | yes | |\n| `target` | `string` | no | |\n| `source` | `string` | no | |\n| `action` | `string` | no | |\n| `props` | `object` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\n\n**Body context:** The declarations for the child, then the assertions about it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStage paths for commit. `` resolves Git pathspecs from the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCompare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, each change's path, status and previous path, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCommit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | no | |\n| `ref` | `string` | no | |\n| `verify` | `boolean` | no | |\n| `yq` | `string` | no | |\n| `maxBytes` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\n\n**Body context:** The message body, expanded before the commit is made. A ref read takes none.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a comparison's patch. `` reads a window of the unified diff text.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a committed file. `` reads the text that commit holds, not the working copy.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `commit` | `string` | yes | |\n| `path` | `string` | yes | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `prefix` | `string` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The tracked paths, and the arguments of the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nPublish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSwitch or create a branch. `` starts a missing branch at the specified base.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | no | |\n| `title` | `string` | no | |\n| `tags` | `array` | no | |\n| `assignee` | `string` | no | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\n\n**Body context:** The issue's description, for the form that files one.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect an issue tracker. `…` expands its content with the specified tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown whose issues are filed there.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGenerate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\n\n**Body context:** The complete prompt, expanded once before authorship.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli/Plan.md` (declared Markdown)\n\n### ``\n\nSend a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n| `timeout` | `string` | no | |\n| `throwOnError` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the reply instead of emitting it.\n\n**Body context:** The prompt text, in the paired form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nOpen or update a pull request. `…` uses its content as the body after ``.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `number` | `integer` | no | |\n| `title` | `string` | yes | |\n| `base` | `string` | no | |\n| `draft` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The pull request's repository, number, url, state and head and base commits.\n\n**Body context:** The pull request's body.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request checks. `` reads check runs and commit statuses for its head.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each check's kind, name, head commit and outcome.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request comments. `` reads both conversation and review comments.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request reviews. `` reads reviews from the specified pull request.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each review's author, state, body, submission time, commit and url.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nClone or use a repository. `…` expands its content in the specified checkout.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `url` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the selected checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nConfigure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `model` | `string` | no | |\n| `effort` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches run in this session.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nLaunch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The instructions the native session starts from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nTurn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in testing mode.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nExpand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli` (registered default)\n\n### ``\n\nAsk a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n| `uiSchema` | JSON Schema | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated response.\n\n**Body context:** The Markdown shown above the form.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{}\n```\n\n**Origin:** `@executablemd/web` (registered default)\n\n### ``\n\nScope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The workflow-hosted executions this scope owns.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a worktree. `…` expands its content in the worktree.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the linked checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", + "cli-json-base.txt": "{\n \"version\": 1,\n \"categories\": [\n {\n \"kind\": \"structural\",\n \"entries\": [\n {\n \"kind\": \"structural\",\n \"name\": \"All\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"All\"\n },\n \"syntax\": [\n \"……\"\n ],\n \"description\": \"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\n \"context\": \"The `` children this runs at the same time.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answer\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answer\"\n },\n \"syntax\": [\n \"\",\n \"…\"\n ],\n \"description\": \"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\n \"context\": \"A multiline template, in place of the single-line `template` prop.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answers\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answers\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\n \"context\": \"`` matchers, and the body they answer for.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Break\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Break\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Case\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Case\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\n \"context\": \"Markdown expanded when this case is selected.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Catch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Catch\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\n \"as\": \"Optional. Binds the ordinary Error by reference in this branch.\",\n \"context\": \"Recovery content.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Content\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Content\"\n },\n \"syntax\": [\n \"\",\n \"\"\n ],\n \"description\": \"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Each\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Each\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\n \"as\": \"Optional. Captures the whole rendered loop instead of emitting it.\",\n \"context\": \"Markdown rendered once per element.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Else\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Else\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\n \"context\": \"The branch taken when the enclosing condition does not hold.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Finally\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Finally\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\n \"context\": \"Completion content using the surrounding bindings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"If\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"If\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\n \"context\": \"The branch taken when the condition holds, up to an ``.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Let\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Let\"\n },\n \"syntax\": [\n \"…\",\n \"\"\n ],\n \"description\": \"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\n \"as\": \"Required. The binding name the value is available under.\",\n \"context\": \"Markdown whose rendered text becomes the binding, in the paired form.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Loop\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Loop\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\n \"context\": \"Markdown expanded once per iteration.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Output\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Output\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\n \"context\": \"The rendered output the run presents.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"PrintErrors\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"PrintErrors\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\n \"context\": \"The region whose failures are printed rather than raised.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Return\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Return\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Spawn\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Spawn\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\n \"context\": \"Markdown expanded in its own child, beside its siblings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Switch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Switch\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\n \"context\": \"Direct `` branches considered in source order.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Try\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Try\"\n },\n \"syntax\": [\n \"………\"\n ],\n \"description\": \"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\n \"context\": \"Attempted content followed by direct Catch and Finally branches.\"\n }\n ]\n },\n {\n \"kind\": \"built-in\",\n \"entries\": [\n {\n \"kind\": \"component\",\n \"name\": \"Agent\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\",\n \"context\": \"Markdown whose prompts and launches use this agent.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AgentProvider\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\",\n \"context\": \"Markdown expanded with this provider installed.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"ApproveAll\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Approve every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\",\n \"context\": \"Markdown whose permission requests are approved.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AskPermission\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Ask about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\",\n \"context\": \"Markdown whose permission requests are asked about.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Assert\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertExists\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertFalse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreater\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreaterOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLess\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLessOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStringIncludes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertThrows\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"message\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\",\n \"as\": \"Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\",\n \"context\": \"The Markdown expected to fail.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CodeBlock\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\n \"as\": \"Optional. Captures the exact fenced Markdown instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\",\n \"as\": \"Required. The journal snapshot.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectOutput\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\",\n \"as\": \"Required. The child's accumulated output.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Cwd\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read the working directory. `` renders its path without adding a newline.\",\n \"as\": \"Optional. Captures the directory path instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"DiagnosticJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Give a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Dir\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a directory. `…` changes the working directory for its content.\",\n \"context\": \"The Markdown expanded in that directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Elicit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Ask a person a structured question. `…` shows the content as the request.\",\n \"as\": \"Required. The validated answer, as a structured value.\",\n \"context\": \"The request message the person is shown.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Evaluate\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Evaluate program text. `` runs it.\",\n \"as\": \"Optional. Captures the fragment's rendered output instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Execution\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\",\n \"as\": \"Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\",\n \"context\": \"The declarations for the child, then the assertions about it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fail\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stop authored work with an actionable failure. `` raises the message where it is written.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fetch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\n \"as\": \"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\n \"as\": \"Optional. Captures the file's text instead of emitting it, in the reading form.\",\n \"context\": \"The text to write, in the writing form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Copy\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n }\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Delete\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\n \"as\": \"Optional. Captures the empty string this renders, as for any text component.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Add\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stage paths for commit. `` resolves Git pathspecs from the working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Changes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Compare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\",\n \"as\": \"Required. The comparison, each change's path, status and previous path, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Commit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Commit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\",\n \"as\": \"Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\",\n \"context\": \"The message body, expanded before the commit is made. A ref read takes none.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Diff\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a comparison's patch. `` reads a window of the unified diff text.\",\n \"as\": \"Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.File\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a committed file. `` reads the text that commit holds, not the working copy.\",\n \"as\": \"Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Files\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"List tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\",\n \"as\": \"Required. The tracked paths, and the arguments of the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Push\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Publish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Switch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Switch or create a branch. `` starts a missing branch at the specified base.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Glob\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"description\": \"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\n \"as\": \"Required. The matched paths, as a string array.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Issue\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Read or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\",\n \"as\": \"Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\",\n \"context\": \"The issue's description, for the form that files one.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"IssueTracker\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select an issue tracker. `…` expands its content with the specified tracker in scope.\",\n \"context\": \"The Markdown whose issues are filed there.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Json\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as JSON text. `` writes the JSON where you put it.\",\n \"as\": \"Optional. Captures the JSON text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Parse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\n \"as\": \"Required. The validated value.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Plan\",\n \"origin\": {\n \"kind\": \"declared-markdown\",\n \"origin\": \"@executablemd/cli/Plan.md\",\n \"digest\": \"d97953c7f65cde0a2858761245d94e06cd31aaba6feb15622256d4dddcaafec2\"\n },\n \"sourceKind\": \"declared-markdown\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Generate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\",\n \"as\": \"Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\",\n \"context\": \"The complete prompt, expanded once before authorship.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Prompt\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Send a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\",\n \"as\": \"Optional. Captures the reply instead of emitting it.\",\n \"context\": \"The prompt text, in the paired form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Open or update a pull request. `…` uses its content as the body after ``.\",\n \"as\": \"Optional. The pull request's repository, number, url, state and head and base commits.\",\n \"context\": \"The pull request's body.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Checks\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request checks. `` reads check runs and commit statuses for its head.\",\n \"as\": \"Required. Each check's kind, name, head commit and outcome.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Comments\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request comments. `` reads both conversation and review comments.\",\n \"as\": \"Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Reviews\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n },\n \"description\": \"Read pull request reviews. `` reads reviews from the specified pull request.\",\n \"as\": \"Required. Each review's author, state, body, submission time, commit and url.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Query\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\n \"as\": \"Optional. Binds the selected value as data instead of writing it as JSON.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Repository\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Clone or use a repository. `…` expands its content in the specified checkout.\",\n \"as\": \"Optional. The path of the selected checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"SafeParse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\n \"as\": \"Required. The result: either the validated value or the issues that rejected it.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Configure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\",\n \"context\": \"Markdown whose prompts and launches run in this session.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session.Launch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Launch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\",\n \"context\": \"The instructions the native session starts from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Slice\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\n \"as\": \"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\n \"context\": \"The content whose completed rendering the window is taken from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Syntax\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\n \"as\": \"Optional. Captures the rendered text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"TempDir\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\n \"as\": \"Optional. Captures the rendered directory path instead of emitting it.\",\n \"context\": \"Markdown expanded with the temporary directory as its working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Test\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\n \"context\": \"The body of the test: its assertions and the work they judge.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Testing\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Turn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\",\n \"context\": \"The Markdown expanded in testing mode.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Verbose\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/cli\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Expand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\",\n \"as\": \"Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WebForm\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/web\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {},\n \"description\": \"Ask a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\",\n \"as\": \"Required. The validated response.\",\n \"context\": \"The Markdown shown above the form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WorkflowRun\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Scope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\",\n \"context\": \"The workflow-hosted executions this scope owns.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Worktree\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a worktree. `…` expands its content in the worktree.\",\n \"as\": \"Optional. The path of the linked checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Yaml\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as YAML text. `` writes the YAML where you put it.\",\n \"as\": \"Optional. Captures the YAML text instead of emitting it.\"\n }\n ]\n },\n {\n \"kind\": \"user-provided\",\n \"entries\": []\n }\n ]\n}\n", "cli-fragment-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n" } diff --git a/packages/core/tests/support/fragment-files.ts b/packages/core/tests/support/fragment-files.ts index ab6a280cf..572b1ae5d 100644 --- a/packages/core/tests/support/fragment-files.ts +++ b/packages/core/tests/support/fragment-files.ts @@ -132,6 +132,10 @@ export function recordedFiles( entries.set(input.path, input.content); return Ok(fileWriteSuccess("host-committed")); }, + *copyFile() { + performed.push("copy"); + throw new Error("Unexpected copy"); + }, *deleteFile(input: FilePathInput): Operation> { if (!(yield* Permissions.operations.files("write"))) { return Err( @@ -200,6 +204,9 @@ export function* useRecordedFiles(files: RecordedFiles): Operation { *writeTextFile([input]) { return yield* files.writeTextFile(input); }, + *copyFile([input]) { + return yield* files.copyFile(input); + }, *deleteFile([input]) { return yield* files.deleteFile(input); }, diff --git a/packages/core/tests/syntax-catalog.test.ts b/packages/core/tests/syntax-catalog.test.ts index c43ceea81..23b93dd24 100644 --- a/packages/core/tests/syntax-catalog.test.ts +++ b/packages/core/tests/syntax-catalog.test.ts @@ -26,7 +26,9 @@ import { API } from "@executablemd/runtime"; import type { DirectoryEntry, LinkStatResult, StatResult } from "@executablemd/runtime"; import { repositoryComponentName } from "../src/components/candidates.ts"; import { + capturedDocumentation, CORE_COMPONENT_NAMES, + documentationIndexFor, inspectComponent, inspectSyntax, PROTECTED_COMPONENT_NAMES, @@ -35,7 +37,7 @@ import { RESERVED_STRUCTURAL, STRUCTURAL_DECLARATIONS, } from "../mod.ts"; -import { AGENT_REGISTRATIONS, agentIdentityComponents } from "@executablemd/agent/host"; +import { agentIdentityComponents, useAgentComponents } from "@executablemd/agent/host"; import type { CompleteComponentSyntaxEntry, InstalledStructuralSyntaxEntry, @@ -1387,15 +1389,19 @@ describe("Tier SY: inspection is observation, never execution", () => { }); describe("Tier SY: first-party documentation", () => { - it("SY28: gives every core and Agent default a description", function* () { - const catalog = yield* scoped(function* () { + it("SY28: documents every core and Agent default", function* () { + const { catalog, docs } = yield* scoped(function* () { yield* useTree({}); - yield* registerComponents(AGENT_REGISTRATIONS); - return yield* inspectSyntax({ includes: [], components: agentIdentityComponents() }); + yield* useAgentComponents(); + return { + catalog: yield* inspectSyntax({ includes: [], components: agentIdentityComponents() }), + docs: documentationIndexFor(yield* capturedDocumentation()), + }; }); const undocumented = builtIn(catalog).filter( - (entry) => entry.description === undefined || entry.description.length === 0, + (entry) => + !entry.description?.trim() && !docs.documentationFor(entry.name, entry.origin)?.trim(), ); expect(names(undocumented)).toEqual([]); for (const name of [...CORE_COMPONENT_NAMES, "Agent", "Prompt", "Session"]) { diff --git a/packages/runtime/files-api.ts b/packages/runtime/files-api.ts index 90c0e8d23..c5eea3a3a 100644 --- a/packages/runtime/files-api.ts +++ b/packages/runtime/files-api.ts @@ -123,6 +123,7 @@ export function createFilesApi(terminal: FilesHandler): FilesApi { checkFilePath: call(terminal.checkFilePath, (layer) => layer.checkFilePath), readTextFile: call(terminal.readTextFile, (layer) => layer.readTextFile), writeTextFile: call(terminal.writeTextFile, (layer) => layer.writeTextFile), + copyFile: call(terminal.copyFile, (layer) => layer.copyFile), deleteFile: call(terminal.deleteFile, (layer) => layer.deleteFile), ensureDirectory: call(terminal.ensureDirectory, (layer) => layer.ensureDirectory), globFiles: call(terminal.globFiles, (layer) => layer.globFiles), diff --git a/packages/runtime/files-host.ts b/packages/runtime/files-host.ts index f66da9c72..7ef4e936f 100644 --- a/packages/runtime/files-host.ts +++ b/packages/runtime/files-host.ts @@ -1,3 +1,5 @@ +import { createContext } from "effection"; +import type { Operation } from "effection"; import { registerFileRecorder } from "./files.ts"; import type { FilesHandler } from "./files.ts"; import type { FileRecorderHandle } from "./files-api.ts"; @@ -7,3 +9,18 @@ export const assembleFileCall = ( handle: FileRecorderHandle, method: K, ): FilesHandler[K] => handle.assemble(method); + +export type HostCopyRoute = (source: string, destination: string) => Operation; + +const HostCopyRouting = createContext("executablemd.runtime.host-copy-routing"); + +export function withHostCopyRoute(route: HostCopyRoute, operation: Operation): Operation { + return HostCopyRouting.with(route, () => operation); +} + +export function* routeHostCopy(source: string, destination: string): Operation { + const route = yield* HostCopyRouting.get(); + if (route !== undefined) { + yield* route(source, destination); + } +} diff --git a/packages/runtime/files.ts b/packages/runtime/files.ts index 74edbba29..73228db76 100644 --- a/packages/runtime/files.ts +++ b/packages/runtime/files.ts @@ -96,6 +96,7 @@ export type FilesReason = | "absolute-path" | "lexical-escape" | "resolved-escape" + | "occupied" | "missing" | "directory" | "special-file" @@ -118,6 +119,7 @@ const REASONS: readonly FilesReason[] = [ "absolute-path", "lexical-escape", "resolved-escape", + "occupied", "missing", "directory", "special-file", @@ -140,6 +142,7 @@ const REASONS: readonly FilesReason[] = [ export type FilesOperation = | "check-file-path" | "read" + | "copy" | "delete" | "ensure-directory" | "glob" @@ -148,6 +151,7 @@ export type FilesOperation = const OPERATIONS: readonly FilesOperation[] = [ "check-file-path", "read", + "copy", "delete", "ensure-directory", "glob", @@ -243,6 +247,12 @@ export interface FilePathInput { readonly path: string; } +export interface FileCopyInput { + readonly cwd: string; + readonly source: string; + readonly destination: string; +} + export interface FileWriteInput extends FilePathInput { readonly content: string; } @@ -261,6 +271,8 @@ export interface FilesHandler { checkFilePath(input: FilePathInput): Operation>; readTextFile(input: FilePathInput): Operation>; writeTextFile(input: FileWriteInput): Operation>; + /** Copy a regular file to a vacant destination with an existing parent. */ + copyFile(input: FileCopyInput): Operation>; /** * Remove one entry this path names, and answer with nothing. * @@ -871,6 +883,10 @@ const composedFiles: FilesApi = createFilesApi({ throw new FilesProviderUnavailableError(); }, // deno-lint-ignore require-yield + *copyFile(_input: FileCopyInput): Operation> { + throw new FilesProviderUnavailableError(); + }, + // deno-lint-ignore require-yield *deleteFile(_input: FilePathInput): Operation> { throw new FilesProviderUnavailableError(); }, diff --git a/packages/runtime/host-files.ts b/packages/runtime/host-files.ts index e3b4a95f2..d5aafde8b 100644 --- a/packages/runtime/host-files.ts +++ b/packages/runtime/host-files.ts @@ -92,14 +92,16 @@ import type { Operation, Result } from "effection"; import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { randomUUID } from "node:crypto"; import { mkdtempSync } from "node:fs"; -import { realpath, rmdir } from "node:fs/promises"; +import { constants, copyFile as nativeCopyFile, realpath, rmdir } from "node:fs/promises"; import { fileURLToPath } from "node:url"; import { tmpdir } from "node:os"; import { FsApi, rm } from "@effectionx/fs"; import { API } from "./apis.ts"; import { fileWriteFailure, fileWriteSuccess, filesFailure, FilesInvariantError } from "./files.ts"; +import { routeHostCopy } from "./files-host.ts"; import { Permissions } from "./permissions.ts"; import type { + FileCopyInput, FilePathInput, FilesHandler, FilesOperation, @@ -121,7 +123,7 @@ import type { * observable rather than merely stated. */ export interface HostFilesEvent { - readonly operation: "read" | "write" | "delete" | "ensure-directory" | "glob"; + readonly operation: "copy" | "read" | "write" | "delete" | "ensure-directory" | "glob"; readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir"; } @@ -130,6 +132,8 @@ export type HostFilesObserver = (event: HostFilesEvent) => void; export interface HostFilesOptions { readonly observe?: HostFilesObserver; + /** Test boundary for the native copy and its settlement. */ + readonly nativeCopy?: typeof nativeCopyFile; readonly access?: HostFilesAccess; /** * The directory temporary directories are minted under, defaulting to the @@ -199,7 +203,7 @@ export function* hostFileAccessReason( } const resolved = operation === "delete" - ? yield* removalDestination(input) + ? yield* entryDestination(input) : operation === "ensure-directory" ? yield* directoryDestination(input) : yield* destination(input); @@ -352,12 +356,10 @@ function* destination(input: FilePathInput): Operation { } /** - * The path a removal would act on, with the final segment left alone. + * The path whose final directory entry a removal or copy addresses. * - * Deletion is the one operation whose target must *not* be resolved. A final - * symbolic link is the entry the document named, and following it would remove - * something the document never mentioned — possibly outside the working - * directory entirely. So only the parent prefix is resolved, and the authored + * A final symbolic link is the entry the document named. Only the parent + * prefix is resolved, and the authored * last segment is put back onto it unresolved. Resolving the parent is what * still catches a directory link leading out; leaving the last segment is what * keeps a link a link. @@ -368,7 +370,7 @@ function* destination(input: FilePathInput): Operation { * an escape. It is classified directly instead, and target classification then * refuses it for what it is. */ -function* removalDestination(input: FilePathInput): Operation { +function* entryDestination(input: FilePathInput): Operation { try { const base = (yield* API.Fs.operations.realpath(input.cwd)) ?? input.cwd; const named = resolve(input.cwd, input.path); @@ -627,6 +629,84 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { return Ok(fileWriteSuccess("host-committed")); } + function* copyFile(input: FileCopyInput): Operation> { + const source = { cwd: input.cwd, path: input.source }; + const target = { cwd: input.cwd, path: input.destination }; + const lexical = inadmissible(source) ?? inadmissible(target); + if (lexical !== undefined) { + return nonWriteFailure("copy", "lexical", lexical); + } + if ( + !(yield* Permissions.operations.files("read")) || + !(yield* Permissions.operations.files("write")) + ) { + return nonWriteFailure("copy", "resolution", "permission-denied"); + } + + const from = yield* destination(source); + if ("reason" in from) { + return nonWriteFailure("copy", "resolution", from.reason); + } + const to = yield* entryDestination(target); + if ("reason" in to) { + return nonWriteFailure("copy", "resolution", to.reason); + } + if ( + options.access !== undefined && + (!permits(options.access, from.path, false) || !permits(options.access, to.path, true)) + ) { + return nonWriteFailure("copy", "resolution", "resolved-escape"); + } + + yield* routeHostCopy(from.path, to.path); + notify(observe, { operation: "copy", phase: "target" }); + try { + const info = yield* API.Fs.operations.stat(from.path); + if (!info.exists) { + return nonWriteFailure("copy", "target", "missing"); + } + if (!info.isFile) { + return nonWriteFailure("copy", "target", info.isDirectory ? "directory" : "special-file"); + } + const parent = yield* API.Fs.operations.stat(dirname(to.path)); + if (!parent.exists || !parent.isDirectory) { + return nonWriteFailure("copy", "target", parent.exists ? "not-directory" : "missing"); + } + // Some runtimes follow a dangling final link even with COPYFILE_EXCL. + if ((yield* API.Fs.operations.lstat(to.path)).exists) { + return nonWriteFailure("copy", "target", "occupied"); + } + } catch (error) { + return nonWriteFailure("copy", "target", reasonOf(error)); + } + + notify(observe, { operation: "copy", phase: "access" }); + try { + yield* scoped(function* () { + let pending: Promise | undefined; + yield* ensure(function* () { + if (pending !== undefined) { + yield* until(pending); + } + }); + const operation = options.nativeCopy ?? nativeCopyFile; + const copy = operation(from.path, to.path, constants.COPYFILE_EXCL); + pending = copy.then( + () => undefined, + () => undefined, + ); + yield* until(copy); + }); + return Ok(undefined); + } catch (error) { + return nonWriteFailure( + "copy", + "access", + errorCode(error) === "EEXIST" ? "occupied" : reasonOf(error), + ); + } + } + /** * Remove one regular file or one final symbolic link. * @@ -653,7 +733,7 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { return nonWriteFailure("delete", "resolution", "permission-denied"); } - const target = yield* removalDestination(input); + const target = yield* entryDestination(input); if ("reason" in target) { return nonWriteFailure("delete", "resolution", target.reason); } @@ -901,6 +981,7 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { checkFilePath, readTextFile, writeTextFile, + copyFile, deleteFile, ensureDirectory, globFiles, @@ -983,6 +1064,9 @@ export function useHostFiles(options: HostFilesOptions = {}): Operation { *writeTextFile([input]) { return yield* handler.writeTextFile(input); }, + *copyFile([input]) { + return yield* handler.copyFile(input); + }, *deleteFile([input]) { return yield* handler.deleteFile(input); }, diff --git a/packages/runtime/mod.ts b/packages/runtime/mod.ts index 5ece5ca5c..46daef97a 100644 --- a/packages/runtime/mod.ts +++ b/packages/runtime/mod.ts @@ -115,6 +115,7 @@ export { parseFilesFatal, } from "./files.ts"; export type { + FileCopyInput, FilePathInput, FilesDeniableOperation, FilesErrorData, diff --git a/packages/runtime/tests/host-files.test.ts b/packages/runtime/tests/host-files.test.ts index 6b4d044d4..3511e8395 100644 --- a/packages/runtime/tests/host-files.test.ts +++ b/packages/runtime/tests/host-files.test.ts @@ -33,7 +33,16 @@ import { } from "effection"; import type { Operation, Result } from "effection"; import { exists, readTextFile, rm, writeTextFile } from "@effectionx/fs"; -import { lstat, mkdir, mkdtemp, readdir, realpath, symlink } from "node:fs/promises"; +import { + lstat, + mkdir, + mkdtemp, + readFile, + readdir, + realpath, + symlink, + writeFile, +} from "node:fs/promises"; import { renameSync, symlinkSync, unlinkSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, sep } from "node:path"; @@ -1405,6 +1414,26 @@ describe("host Files — permission", () => { }); } + it("copy authorizes both paths before target I/O", function* () { + const fixture = yield* useFixture(); + yield* useHostFiles(); + yield* writeTextFile(join(fixture.workspace, "source"), "fixture"); + const touched: string[] = []; + yield* census(touched); + const request = { cwd: fixture.workspace, source: "source", destination: "destination" }; + for (const denied of ["read", "write"]) { + yield* scoped(function* () { + yield* Permissions.around({ + files: ([operation], next) => (operation === denied ? false : next(operation)), + }); + const result = yield* Files.operations.copyFile(request); + expect(parseFilesFailure(failed(result))?.reason).toBe("permission-denied"); + }); + } + expect(touched).toEqual([]); + expect(yield* exists(join(fixture.workspace, request.destination))).toBe(false); + }); + it("HF absolute: default and explicit denial reach no target; opt-in intersects read/write", function* () { const fixture = yield* useFixture(); const files = handler(); @@ -1747,3 +1776,119 @@ describe("1113: outward session roots", () => { expect(yield* entries(fixture.outside)).toEqual(["canary"]); }); }); + +describe("host Files copy", () => { + it("preserves occupied entries and refuses missing or escaped paths", function* () { + const { workspace, outside } = yield* useFixture(); + yield* useHostFiles(); + const binary = new Uint8Array(8 * 1024 * 1024 + 1); + binary[binary.length - 1] = 0xff; + yield* until(writeFile(join(workspace, "source"), binary)); + yield* writeTextFile(join(workspace, "occupied"), "keep"); + yield* writeTextFile(join(outside, "outside.txt"), "keep outside"); + yield* linkDirectory(outside, join(workspace, "escape")); + yield* until(symlink(join(workspace, "missing"), join(workspace, "dangling"), "file")); + const copy = (source: string, destination: string) => + Files.operations.copyFile({ cwd: workspace, source, destination }); + + for (const [from, to, reason] of [ + ["source", "occupied", "occupied"], + ["source", "dangling", "occupied"], + ["source", "absent/target", "missing"], + ["source", "escape/target", "resolved-escape"], + ["escape/outside.txt", "target", "resolved-escape"], + ]) { + expect(parseFilesFailure(failed(yield* copy(from, to)))?.reason).toBe(reason); + } + expect(yield* readTextFile(join(workspace, "occupied"))).toBe("keep"); + expect((yield* until(lstat(join(workspace, "dangling")))).isSymbolicLink()).toBe(true); + for (const absent of [ + join(workspace, "missing"), + join(workspace, "absent"), + join(workspace, "target"), + join(outside, "target"), + ]) { + expect(yield* exists(absent)).toBe(false); + } + + expect(yield* copy("source", "copy")).toEqual({ ok: true, value: undefined }); + expect((yield* until(readFile(join(workspace, "copy")))).equals(binary)).toBe(true); + expect((yield* until(readFile(join(workspace, "source")))).equals(binary)).toBe(true); + }); + + it("joins a started native copy during halt without returning a Files result", function* () { + const { workspace } = yield* useFixture(); + yield* writeTextFile(join(workspace, "source"), "fixture"); + const started = withResolvers(); + let finish = () => {}; + const pending = new Promise((resolve) => { + finish = resolve; + }); + yield* useHostFiles({ + nativeCopy() { + started.resolve(undefined); + return pending; + }, + }); + let result: Result | undefined; + const task = yield* spawn(function* () { + result = yield* Files.operations.copyFile({ + cwd: workspace, + source: "source", + destination: "destination", + }); + }); + yield* started.operation; + const halted = task.halt(); + try { + const early = yield* race([ + (function* () { + yield* halted; + return true; + })(), + (function* () { + yield* sleep(0); + return false; + })(), + ]); + expect(early).toBe(false); + } finally { + finish(); + } + yield* halted; + expect(result).toBe(undefined); + }); + + it("applies captured roots to both effective copy operands", function* () { + const { root, workspace, outside } = yield* useFixture(); + const access = yield* captureHostFilesAccess({ + project: workspace, + private: join(workspace, "session"), + assets: join(workspace, "session", "assets"), + components: join(workspace, "session", "components"), + }); + yield* until(mkdir(access.assets, { recursive: true })); + yield* writeTextFile(join(access.assets, "source"), "asset"); + yield* writeTextFile(join(outside, "source"), "outside"); + const touched: HostFilesEvent[] = []; + yield* useHostFiles({ access, observe: (event) => touched.push(event) }); + const request = { + cwd: root, + source: "workspace/session/assets/source", + destination: "workspace/copy", + }; + for (const change of [ + { source: "outside/source" }, + { destination: "workspace/session/assets/copy" }, + ]) { + yield* scoped(function* () { + yield* API.Files.around({ copyFile: ([input], next) => next({ ...input, ...change }) }); + const result = yield* Files.operations.copyFile(request); + expect(parseFilesFailure(failed(result))?.reason).toBe("resolved-escape"); + }); + } + expect(touched).toEqual([]); + expect(yield* exists(join(workspace, "copy"))).toBe(false); + expect(yield* exists(join(access.assets, "copy"))).toBe(false); + }); +}); diff --git a/packages/workflow/src/deno/workspace/files.ts b/packages/workflow/src/deno/workspace/files.ts index 7e4377fa6..26dd5ea9e 100644 --- a/packages/workflow/src/deno/workspace/files.ts +++ b/packages/workflow/src/deno/workspace/files.ts @@ -32,6 +32,7 @@ import { parseFileWritePhase, } from "@executablemd/runtime"; import type { + FileCopyInput, FilePathInput, FilesPhase, FilesReason, @@ -121,6 +122,7 @@ function lexicalReason(error: Error): FilesReason { type FileEffectOutcome = | { readonly kind: "content"; readonly content: string } | { readonly kind: "written" } + | { readonly kind: "copied" } | { readonly kind: "deleted" } | { readonly kind: "ensured" } | { readonly kind: "paths"; readonly paths: string[] } @@ -145,6 +147,7 @@ function refused( const OUTCOME_MEMBERS: ReadonlyMap = new Map([ ["content", ["kind", "content"]], ["written", ["kind"]], + ["copied", ["kind"]], ["deleted", ["kind"]], ["ensured", ["kind"]], ["paths", ["kind", "paths"]], @@ -206,6 +209,9 @@ function parseOutcome( if (kind === "written") { return { kind: "written" }; } + if (kind === "copied") { + return { kind: "copied" }; + } if (kind === "deleted") { return { kind: "deleted" }; } @@ -451,6 +457,37 @@ function* writeOutcome( return { kind: "written" }; } +function* copyOutcome( + filesystem: DenoWorkspaceFilesystem, + source: string, + destination: string, +): Operation> { + if ( + !(yield* Permissions.operations.files("read")) || + !(yield* Permissions.operations.files("write")) + ) { + return refused("resolution", "permission-denied"); + } + const info = yield* statPath(filesystem, source); + if (!info.ok) { + return refused("resolution", refusalReason(info.error)); + } + if (info.value.kind !== "file") { + return refused("target", "directory"); + } + try { + const bytes = yield* filesystem.readFile(source); + // The exclusive writer resolves the parent and classifies the final entry + // by dirent before writing, with the same parent inode for both. + yield* savepoint(filesystem.writeFile(destination, bytes, undefined, true)); + return { kind: "copied" }; + } catch (error) { + const reason = + journalableWorkspaceCode(error) === "EEXIST" ? "occupied" : refusalReason(asRefusal(error)); + return refused("access", reason); + } +} + /** * Remove one file, or find that there is nothing to remove. * @@ -633,6 +670,7 @@ export interface WorkflowFilesHandler { checkFilePath(input: FilePathInput): Operation>; readTextFile(input: FilePathInput): Operation>; writeTextFile(input: FileWriteInput): Operation>; + copyFile(input: FileCopyInput): Operation>; deleteFile(input: FilePathInput): Operation>; ensureDirectory(input: FilePathInput): Operation>; globFiles(input: GlobInput): Operation>; @@ -706,6 +744,40 @@ export function workflowFilesHandler(database: WorkflowRunDatabase): WorkflowFil return Ok(fileWriteSuccess("transaction-staged")); }, + *copyFile(input: FileCopyInput): Operation> { + const source = resolveLogicalPath(input.cwd, input.source); + const destination = resolveLogicalPath(input.cwd, input.destination); + const invalid = !source.ok ? source : !destination.ok ? destination : undefined; + if (!source.ok || !destination.ok) { + return Err( + filesFailure({ + operation: "copy", + phase: "lexical", + reason: invalid === undefined ? "operation-failed" : lexicalReason(invalid.error), + }), + ); + } + const outcome = yield* performed( + database, + yield* describeFileEffect("copy", JSON.stringify([source.value, destination.value]), { + cwd: input.cwd, + source: input.source, + destination: input.destination, + }), + parseFilesPhase, + (filesystem) => copyOutcome(filesystem, source.value, destination.value), + ); + if (outcome.kind === "refused") { + return Err( + filesFailure({ operation: "copy", phase: outcome.phase, reason: outcome.reason }), + ); + } + if (outcome.kind !== "copied") { + throw new FilesInvariantError("protocol"); + } + return Ok(undefined); + }, + *deleteFile(input: FilePathInput): Operation> { const resolved = resolveLogicalPath(input.cwd, input.path); if (!resolved.ok) { @@ -824,6 +896,9 @@ export function useWorkflowFiles(database: WorkflowRunDatabase): Operation *writeTextFile([input]) { return yield* handler.writeTextFile(input); }, + *copyFile([input]) { + return yield* handler.copyFile(input); + }, *deleteFile([input]) { return yield* handler.deleteFile(input); }, diff --git a/packages/workflow/src/deno/workspace/filesystem.ts b/packages/workflow/src/deno/workspace/filesystem.ts index 1ae4087a1..d9fa958b7 100644 --- a/packages/workflow/src/deno/workspace/filesystem.ts +++ b/packages/workflow/src/deno/workspace/filesystem.ts @@ -36,7 +36,12 @@ export interface DenoWorkspaceFilesystem { lstat(path: string): Operation; readlink(path: string): Operation; readdir(path: string): Operation; - writeFile(path: string, content: string | Uint8Array, mode?: number): Operation; + writeFile( + path: string, + content: string | Uint8Array, + mode?: number, + exclusive?: boolean, + ): Operation; mkdir(path: string, options?: { recursive?: boolean; mode?: number }): Operation; remove(path: string, options?: { recursive?: boolean; force?: boolean }): Operation; rename(from: string, to: string): Operation; @@ -120,14 +125,14 @@ export function createDenoWorkspaceFilesystem( })); }, - *writeFile(path, content, mode): Operation { + *writeFile(path, content, mode, exclusive): Operation { const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content; execute(() => // The write belongs to the caller's savepoint on the same synchronous // SQLite connection; suspending inside it would let another operation // commit between the rows this single write is meant to place together. // oxlint-disable-next-line local/no-sync-filesystem - writeFileSync(dofs, path, bytes, mode === undefined ? {} : { mode }, filesystem.now), + writeFileSync(dofs, path, bytes, { mode, exclusive }, filesystem.now), ); }, diff --git a/packages/workflow/src/deno/workspace/guard.ts b/packages/workflow/src/deno/workspace/guard.ts index b42786b4a..40911196d 100644 --- a/packages/workflow/src/deno/workspace/guard.ts +++ b/packages/workflow/src/deno/workspace/guard.ts @@ -94,8 +94,8 @@ export function guardedWorkflowWorkspaceFilesystem( ): DenoWorkspaceFilesystem { return { ...guardedWorkflowWorkspaceReads(filesystem, held), - writeFile: (path, content, mode) => - gatedOperation(held, () => filesystem.writeFile(path, content, mode)), + writeFile: (path, content, mode, exclusive) => + gatedOperation(held, () => filesystem.writeFile(path, content, mode, exclusive)), mkdir: (path, options) => gatedOperation(held, () => filesystem.mkdir(path, options)), remove: (path, options) => gatedOperation(held, () => filesystem.remove(path, options)), rename: (from, to) => gatedOperation(held, () => filesystem.rename(from, to)), diff --git a/packages/workflow/tests/generated-agent-component.test.ts b/packages/workflow/tests/generated-agent-component.test.ts index 28be4fedb..dd3ed2dce 100644 --- a/packages/workflow/tests/generated-agent-component.test.ts +++ b/packages/workflow/tests/generated-agent-component.test.ts @@ -1317,6 +1317,48 @@ describe("Tier WGAC — the standard write table", () => { }); }); + it("WGAC15: an unoffered File.Copy stops an earlier admitted deletion", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + yield* plant(database, "obsolete.md", "sentinel"); + const reached: string[] = []; + const attempt = yield* scoped(function* () { + yield* API.Files.around({ + *deleteFile([input], next) { + reached.push("delete"); + return yield* next(input); + }, + *copyFile([input], next) { + reached.push("copy"); + return yield* next(input); + }, + }); + return yield* runDocument( + database, + evaluates( + '\n\n', + ["write"], + ), + ); + }); + expect(reported(attempt)).toBe( + "a generated fragment names a component this host did not admit.", + ); + expect(reached).toEqual([]); + expect( + attempt.events.filter( + (event) => + event.type === "yield" && + event.description.type === "workspace_file" && + /^(delete|copy):/.test(event.description.name), + ), + ).toEqual([]); + expect(yield* stored(database, "/obsolete.md")).toBe("sentinel"); + expect(yield* stored(database, "/copy.md")).toBe(undefined); + }); + }); + it("WGAC10: a self-closing File is not admitted by the write table", function* () { const root = yield* useStorageRoot(); yield* withStorage(root, function* () { diff --git a/packages/workflow/tests/workspace-files.test.ts b/packages/workflow/tests/workspace-files.test.ts index ef75a9cd3..b9441d151 100644 --- a/packages/workflow/tests/workspace-files.test.ts +++ b/packages/workflow/tests/workspace-files.test.ts @@ -243,13 +243,13 @@ function refusingWrite( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { + *writeFile(path, content, mode, exclusive) { if (path === target) { throwWorkspaceFilesystemFailure( Object.assign(new Error("planted"), { name: "WorkspaceFsError", code: "EACCES" }), ); } - yield* filesystem.writeFile(path, content, mode); + yield* filesystem.writeFile(path, content, mode, exclusive); }, }); } @@ -279,9 +279,9 @@ function countingWrites( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { + *writeFile(path, content, mode, exclusive) { written.push(path); - yield* filesystem.writeFile(path, content, mode); + yield* filesystem.writeFile(path, content, mode, exclusive); }, }); } @@ -356,8 +356,8 @@ function suspendingWrite( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { - yield* filesystem.writeFile(path, content, mode); + *writeFile(path, content, mode, exclusive) { + yield* filesystem.writeFile(path, content, mode, exclusive); if (path === target) { reached.resolve(); yield* suspend(); @@ -1763,17 +1763,17 @@ describe("Tier WF — the run's own directories", () => { * to win. What these assert is that current policy decides new work and says * nothing about work the journal already holds. */ -describe("workflow document filesystem — permission", () => { - /** Refuse one class of operation, recording every question asked. */ - function restricted(asked: string[], refuse: "read" | "write"): Operation { - return Permissions.around({ - files: ([operation], next) => { - asked.push(operation); - return operation === refuse ? false : next(operation); - }, - }); - } +/** Refuse one class of operation, recording every question asked. */ +function restricted(asked: string[], refuse: "read" | "write"): Operation { + return Permissions.around({ + files: ([operation], next) => { + asked.push(operation); + return operation === refuse ? false : next(operation); + }, + }); +} +describe("workflow document filesystem — permission", () => { it("WF27: a denied write is published as an ordinary refusal and keeps the root", function* () { const root = yield* useStorageRoot(); yield* withStorage(root, function* () { @@ -1918,3 +1918,190 @@ describe("workflow document filesystem — permission", () => { ); }); }); + +describe("Workspace file copy", () => { + const doc = ''; + const target = JSON.stringify(["/source.bin", "/destination.bin"]); + const bytes = Uint8Array.of(0, 255, 128); + + function* seed(database: WorkflowRunDatabase): Operation { + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/source.bin", bytes); + }); + } + + function read(database: WorkflowRunDatabase, path: string) { + return transactWorkspaceRoots(database, (workspace) => workspace.filesystem.readFile(path)); + } + + it("publishes exact independent bytes, Unit, and the resulting root", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + expect(yield* read(database, "/destination.bin")).toEqual({ ok: true, value: bytes }); + expect((yield* recordedFileEffects(database)).map((effect) => effect.result)).toEqual([ + { status: "ok", value: { kind: "copied" } }, + ]); + expect(committedEffects(path, "copy", target)).toBe(1); + expect(committedRoot(path)).toEqual(rootOfLastEvent(path)); + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/destination.bin", "changed"); + }); + expect(yield* read(database, "/source.bin")).toEqual({ ok: true, value: bytes }); + }); + }); + + it("publishes ordinary refusals without changing the frontier", function* () { + for (const denied of ["read", "write", "occupied"]) { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + if (denied === "occupied") { + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/destination.bin", "keep"); + }); + } + const before = committedRoot(path); + yield* scoped(function* () { + if (denied === "read" || denied === "write") { + yield* restricted([], denied); + } + yield* runDocument(database, doc); + }); + const reason = denied === "occupied" ? "occupied" : "permission-denied"; + expect((yield* recordedFileEffects(database))[0]?.result).toEqual({ + status: "ok", + value: { + kind: "refused", + phase: denied === "occupied" ? "access" : "resolution", + reason, + }, + }); + expect(committedRoot(path)).toBe(before); + if (denied === "occupied") { + expect(yield* workspaceText(database, "/destination.bin")).toBe("keep"); + } else { + expect((yield* read(database, "/destination.bin")).ok).toBe(false); + } + }); + } + }); + + it("rolls back an unpublished copy and performs it once on continuation", function* () { + const root = yield* useStorageRoot(); + let fail = true; + let copied = 0; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + const before = committedRoot(path); + expect(yield* raised(runDocument(database, doc))).toBeInstanceOf(Error); + expect(committedRoot(path)).toBe(before); + expect((yield* read(database, "/destination.bin")).ok).toBe(false); + expect(yield* recordedFileEffects(database)).toEqual([]); + expect(copied).toBe(1); + + fail = false; + yield* replayDocument(database, doc); + expect(copied).toBe(2); + expect(committedEffects(path, "copy", target)).toBe(1); + expect(yield* read(database, "/destination.bin")).toEqual({ ok: true, value: bytes }); + }, + { + decorateFilesystem: (filesystem) => ({ + ...filesystem, + *writeFile(path, content, mode, exclusive) { + yield* filesystem.writeFile(path, content, mode, exclusive); + if (exclusive) { + copied += 1; + if (fail) { + throw new Error("planted failure after the copy"); + } + } + }, + }), + }, + ); + }); + + it("restores an acknowledged copy without live access or a second publication", function* () { + const root = yield* useStorageRoot(); + const writes: string[] = []; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + const frontier = committedRoot(path); + dropRootClose(path); + const asked: string[] = []; + yield* scoped(function* () { + yield* restricted(asked, "write"); + yield* replayDocument(database, doc); + }); + expect(asked).toEqual([]); + expect(writes).toEqual(["/source.bin", "/destination.bin"]); + expect(committedRoot(path)).toBe(frontier); + expect(committedEffects(path, "copy", target)).toBe(1); + }, + { decorateFilesystem: countingWrites(writes) }, + ); + }); + + it("rejects a changed source or destination before the live copy", function* () { + for (const change of [{ source: "changed.bin" }, { destination: "changed.bin" }]) { + const root = yield* useStorageRoot(); + const writes: string[] = []; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + const frontier = committedRoot(path); + dropRootClose(path); + const failure = yield* scoped(function* () { + yield* API.Files.around({ + copyFile: ([input], next) => next({ ...input, ...change }), + }); + return yield* raised(replayDocument(database, doc)); + }); + expect(String(failure)).toContain("changed.bin"); + expect(writes).toEqual(["/source.bin", "/destination.bin"]); + expect(committedRoot(path)).toBe(frontier); + expect(committedEffects(path, "copy", target)).toBe(1); + }, + { decorateFilesystem: countingWrites(writes) }, + ); + } + }); + + it("refuses a malformed retained copy success", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + dropRootClose(path); + plantOutcome(path, "copy", target, { kind: "copied", path: "/destination.bin" }); + const failure = yield* raised(replayDocument(database, doc)); + expect(parseFilesFatal(fatalOf(failure))).toEqual({ + type: FILES_FATAL, + kind: "invariant", + category: "protocol", + }); + }); + }); +}); diff --git a/scripts/bench-repl-file-dir.ts b/scripts/bench-repl-file-dir.ts index a7f245fda..c1c799051 100644 --- a/scripts/bench-repl-file-dir.ts +++ b/scripts/bench-repl-file-dir.ts @@ -171,6 +171,7 @@ function counters(): Counters { function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { + copyFile: (input) => host.copyFile(input), *checkFilePath(input: FilePathInput) { counted.checks += 1; return yield* host.checkFilePath(input); @@ -380,6 +381,7 @@ function measure( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/scripts/files-contract-probe.ts b/scripts/files-contract-probe.ts index 2f3e13d82..0ac77b7dc 100644 --- a/scripts/files-contract-probe.ts +++ b/scripts/files-contract-probe.ts @@ -19,7 +19,7 @@ import { ensureDir, exists, readTextFile, writeTextFile } from "@effectionx/fs"; import { exit, main, scoped, until } from "effection"; import type { Result } from "effection"; -import { lstat, realpath, symlink } from "node:fs/promises"; +import { lstat, readFile, realpath, symlink, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { useTempDirectory } from "./lib/temp-directory.ts"; import process from "node:process"; @@ -87,6 +87,24 @@ await main(function* () { yield* useHostFiles(); + const binary = Uint8Array.of(0, 255, 128); + const copy = { cwd: workspace, source: "source.bin", destination: "destination.bin" }; + yield* until(writeFile(join(workspace, copy.source), binary)); + check("native copy returns Unit", (yield* Files.operations.copyFile(copy)).ok); + check( + "native copy preserves bytes", + (yield* until(readFile(join(workspace, copy.destination)))).equals(binary), + ); + yield* until(writeFile(join(workspace, copy.destination), Uint8Array.of(42))); + check( + "native copy refuses occupancy", + reasonOf(yield* Files.operations.copyFile(copy)) === "occupied", + ); + check( + "native copy preserves an occupied destination", + (yield* until(readFile(join(workspace, copy.destination)))).equals(Uint8Array.of(42)), + ); + check( "an empty path is refused lexically", reasonOf(yield* Files.operations.checkFilePath({ cwd: workspace, path: "" })) === "empty-path", diff --git a/scripts/lib/markdown-suites.ts b/scripts/lib/markdown-suites.ts index 83e796c46..957aeb217 100644 --- a/scripts/lib/markdown-suites.ts +++ b/scripts/lib/markdown-suites.ts @@ -7,6 +7,7 @@ interface DocumentSuite { /** The documents whose TypeScript launchers used the ordinary CLI profile. */ export const DOCUMENT_SUITES: ReadonlyMap = new Map([ ["packages/cli/tests/document-suites/evaluate/Evaluate.test.md", {}], + ["packages/cli/tests/document-suites/file-copy/FileCopy.test.md", {}], ["packages/cli/tests/document-suites/inline/Inline.test.md", {}], ["packages/cli/tests/document-suites/plan/Plan.test.md", { worker: true }], ["packages/cli/tests/document-suites/props/Props.test.md", {}], diff --git a/scripts/tests/test-file-discovery.test.ts b/scripts/tests/test-file-discovery.test.ts index 5c3e78428..a69fb0287 100644 --- a/scripts/tests/test-file-discovery.test.ts +++ b/scripts/tests/test-file-discovery.test.ts @@ -126,6 +126,7 @@ describe("the Markdown suites", () => { ), ).toEqual([ "packages/cli/tests/document-suites/evaluate/Evaluate.test.md", + "packages/cli/tests/document-suites/file-copy/FileCopy.test.md", "packages/cli/tests/document-suites/inline/Inline.test.md", "packages/cli/tests/document-suites/plan/Plan.test.md", "packages/cli/tests/document-suites/props/Props.test.md", diff --git a/specs/construct-inventory.md b/specs/construct-inventory.md index ba8c19045..42142b2cf 100644 --- a/specs/construct-inventory.md +++ b/specs/construct-inventory.md @@ -61,6 +61,7 @@ A non-normative table of the selected public vocabulary. In props, `?` marks an | Elicit | default component | @executablemd/core | schema: schema | value: schema | | Fail | default component | @executablemd/core | message: string | text: string | | Fetch | default component | @executablemd/core | url: string; method?: string; headers?: object; timeout?: string | text: string | +| File.Copy | default component | @executablemd/core | from: string; to: string | text: string | | Glob | default component | @executablemd/core | include: array; exclude?: array | value: array | | Json | default component | @executablemd/core | value: capture | text: string | | Parse | default component | @executablemd/core | schema: schema | value: schema | diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index d42a61034..5647381b8 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -3617,9 +3617,11 @@ yield* registrar.around(function* (request, next) { A registration may also carry `description`, `as` and `context` — the same three descriptive fields Markdown frontmatter carries, with the same meaning and the -same absence of behavior. Every component a first-party package registers -declares a description, and decides explicitly whether `as` and `context` apply -to it rather than leaving an omitted field to mean either. +same absence of behavior. A first-party component supplies its description in +the registration or in its section of the package's `components.md` (§5.3.1). +The compact catalog includes descriptions from registrations. Named help also +includes the matching Markdown sections. First-party registrations specify +whether `as` and `context` apply. **A return binds by reference.** `as` binds the value the component returned — the object itself, not a rendering of it — so a component can hand its caller @@ -9878,6 +9880,40 @@ semantics belong to the provider: `specs/workflow-workspace-spec.md` §§6.3 and --- +### 6.13.3 Copying a file: `` + +```mdx + +``` + +Core supplies `File.Copy` as an ordinary default. The canonical dispatcher +requires self-closing form and refuses paired form before expanding its +content. The `from` and `to` props are required nonempty strings. +The component passes `from` as `source` and `to` as `destination` in one call +to `API.Files.copyFile` with the contextual working directory. Success is Unit +and renders nothing. Ordinary filesystem refusals use the Files reporting +rules in §6.13. + +The performing provider authorizes read access to the effective source and +write access to the effective destination after middleware and before target +I/O. Each path is relative and subject to the provider's lexical and resolved +containment. The source must be a regular file. The destination requires an +existing directory and a vacant final entry. A dangling final link counts as +occupied. A successful copy preserves every source byte in an independent file. +A refusal for occupancy preserves the existing entry. + +Ordinary runs and host-backed Markdown tests use native exclusive copy under +the stable pathname namespace contract. The host checks the final entry +without following it and joins a started copy during cancellation. +An ordinary run starts fresh. Low-level partial host replay that reaches copy +performs it live. Completed-root replay returns the saved outcome without +expansion. [Workflow Workspace](workflow-workspace-spec.md#101-workspace-local-effects) +restores a published effect. [Retained REPL](repl-spec.md#the-files-an-entry-wrote-in-the-checkout-you-are-standing-in) +restores an acknowledged result within covered storage. + +Named `xmd syntax File.Copy` shows the invocation and required props. +Generated XMD requires a separate trusted offer for the name and form. + ### 6.14 Finding files: `` A document decides what to work on by looking at what is there. `` is @@ -13531,7 +13567,7 @@ so the include-boundary rows are the same on every host. Defined in §5.3. | SY24/SY25 | Complete contracts | ``'s two forms, ``'s one, ``'s one and its capture, and text and value return modes; declaration order of captures and forms survives, each canonical forms spelling is accepted, and every other one is refused | | SY7/SY7c/SY18 | Owned names keep their origin | A flat dotted candidate, an unreachable subtree and a link behind a prefix leave `` reported with canonical core's own origin rather than a registration's | | SY26–SY27 | Declared components | One is described without its factory being called and a repository file still overrides it; two declarations of one name are refused before either factory; and a declaration inspection refuses is refused identically by registration | -| SY28 | First-party documentation | Every complete built-in in the core and Agent profile states a description | +| SY28 | First-party documentation | Every complete built-in in the core and Agent profile has a registration description or a nonempty package documentation section | | SY29 | Determinism | Two inspections of one environment are equal, and entries are sorted within each category | ### Tier DV — Document validation @@ -13745,7 +13781,7 @@ would bind differently — belongs to `EP`, where profile capture is tested. | # | Test | Verify | |---|------|--------| | SX1–SX3 | The run profile | Core, Agent, testing and web defaults and `` are described from the declarations the runtime installers register, with no execution claimant minted | -| SX2 | Documentation completeness | Every complete built-in in the profile states a description, and the testing contracts read as they are: `` requires `message` and binds the caught error segment, an ordinary assertion binds its diagnostic report, and an assertion that refuses expected children reports one form | +| SX2 | Documentation completeness | Every complete built-in has a registration description or a nonempty package documentation section, and the testing contracts read as they are: `` requires `message` and binds the caught error segment, an ordinary assertion binds its diagnostic report, and an assertion that refuses expected children reports one form | | SX4–SX6 | Renderers take a value | Both formats render from a supplied symbols with the filesystem refusing every call, twice with identical bytes, under the fixed category headings; every table cell is escaped, a prop name holding a pipe included | | SX7/SX8 | Includes | Repeated values select in caller order and replace the defaults; absent, the defaults apply | | SX9 | Failure | An unusable include exits 1, reports on stderr and prints no symbols | diff --git a/specs/repl-spec.md b/specs/repl-spec.md index d7b8cda15..bc8ad5339 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -2286,14 +2286,39 @@ uncertain append establishes no saved value or Unit. Start the REPL inside a Git checkout and an entry's file work is retained too, under the ordinary physical records. The prospective mapped class above uses its -closed association record. Four operations are -kept: a self-closing `` text read; a paired +closed association record. The physical records keep a self-closing `` text read; a paired `…` write, after its content has expanded; a self-closing -``; and the directory a paired `…` +``; a self-closing ``; and the directory a paired `…` ensures, before its content is entered. The reads, writes and deletions an admitted `` fragment performs are kept on the same terms, because a fragment's operations go to the same document filesystem an authored one does. +A copy uses the physical record even when its working directory came from a +mount. Each entry numbers received copy calls from zero within each durable +coroutine, counting uncovered, refused and synthetic calls. The copy record +and name carry this ordinal. Its fingerprint binds the ordinal, the received +working directory and both ordered operands. Admission requires strictly +increasing nonnegative safe integer ordinals per coroutine and accepts gaps. +A copy record requires an ordinal. + +After restoring any pending ambient selection, an equal ordinal offers the +current fingerprint to the durable matcher before live work. A changed operand +at that occurrence diverges, including when the new destination is uncovered. +A lower retained ordinal fails before live work. A higher ordinal stays +pending while the current call takes the live path. Acknowledged Unit and +ordinary refusals restore before Files composition or target observations. + +The host routes each live delegation by its effective resolved operands after +authorization and containment. The destination's resolved parent and final +entry determine coverage. Both managed operand slots precede the destination +checkout's mutation hold. Owned-root coverage requires no Git lease. +A covered dispatch cannot insert an outcome ahead of retained history. +The outer recorder publishes the final composed answer after settlement when +at least one dispatch reached covered storage. Uncovered and purely synthetic +calls have no copy result. If native copy completed before an unacknowledged append, +a continuation attempts the operation live. An occupied destination then +produces an ordinary refusal with its bytes intact. + What that buys is the one thing experimentation needs: leave an entry at a question, come back to the printed location, and the work it already did is not done again. The question is offered again, and the write after it happens for diff --git a/specs/testing-spec.md b/specs/testing-spec.md index bffc6eb6b..14c137497 100644 --- a/specs/testing-spec.md +++ b/specs/testing-spec.md @@ -819,6 +819,7 @@ A Markdown suite is a regular `*.test.md` file directly inside these registered paths: - `packages/cli/tests/document-suites/evaluate/Evaluate.test.md` +- `packages/cli/tests/document-suites/file-copy/FileCopy.test.md` - `packages/cli/tests/document-suites/inline/Inline.test.md` - `packages/cli/tests/document-suites/plan/Plan.test.md` - `packages/cli/tests/document-suites/props/Props.test.md` diff --git a/specs/workflow-workspace-spec.md b/specs/workflow-workspace-spec.md index 034219b07..14f10bdcf 100644 --- a/specs/workflow-workspace-spec.md +++ b/specs/workflow-workspace-spec.md @@ -2369,6 +2369,10 @@ current sandbox. ### 8.4 Generated XMD +Authored `File.Copy` is available in Core. The standard generated selection +does not offer it. Preflight refuses its use in that selection before any +earlier admitted operation performs an effect. + A Prompt may return an XMD fragment rather than an ad hoc file-operation schema. The fragment is untrusted input: it carries data, never authorization. Only the trusted workflow host offers the vocabulary, and it does so through the ordinary @@ -3078,6 +3082,20 @@ cwd scope: later content failure or cancellation restores the enclosing cwd but does not remove the directory. `` neither reads nor changes the Repository selection in scope. +**Document copy** uses one `workspace_file` effect whose name binds the +expansion, the copy operation, and the ordered pair of resolved logical paths. +The live performer checks source read and destination write permission before +filesystem lookup. It reads the regular source as bytes and uses the logical +filesystem's exclusive writer to require an existing parent and a vacant +final entry. The writer uses the same parent inode for classification and +insertion and creates an independent file. + +A completed copy retains exactly `{ kind: "copied" }`. An ordinary refusal +retains `{ kind: "refused", phase, reason }`. Mutation, resulting root and +filtered result use the transaction described above. Replay restores a +published outcome before current permission or filesystem access. A copy +without a published outcome runs against the retained frontier. + **Document deletion** is one of them. `` (executable-mdx-spec §6.13.1) removes one file from the run's Workspace, resolving its path inside the logical filesystem so no host path is ever produced. One regular file or one