@synergenius/flow-weaver 0.10.12 → 0.12.0

package/dist/runtime/checkpoint.js

@@ -0,0 +1,225 @@
+/**
+ * Checkpoint serialization for crash recovery.
+ *
+ * Writes workflow state to disk after each node completes. If the process
+ * crashes, the checkpoint file persists and can be used to resume execution
+ * from the last completed node.
+ *
+ * Checkpoint files live in .fw-checkpoints/ next to the workflow file and
+ * are auto-deleted after successful workflow completion.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+function isUnserializableMarker(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__fw_unserializable__ === true);
+}
+/**
+ * Try to serialize a value. If it contains functions, invoke them first.
+ * If serialization fails, return a marker.
+ */
+function serializeValue(key, value, unsafeNodes) {
+    // Resolve function values (pull execution lazy evaluation)
+    if (typeof value === 'function') {
+        try {
+            value = value();
+        }
+        catch {
+            const parts = key.split(':');
+            unsafeNodes.add(parts[0]);
+            return {
+                __fw_unserializable__: true,
+                nodeId: parts[0],
+                portName: parts[1] || 'unknown',
+                reason: 'Function invocation failed',
+            };
+        }
+    }
+    // Handle Promises: can't serialize, mark as unsafe
+    if (value instanceof Promise) {
+        const parts = key.split(':');
+        unsafeNodes.add(parts[0]);
+        return {
+            __fw_unserializable__: true,
+            nodeId: parts[0],
+            portName: parts[1] || 'unknown',
+            reason: 'Promise value',
+        };
+    }
+    // Test serialization
+    try {
+        JSON.stringify(value);
+        return value;
+    }
+    catch {
+        const parts = key.split(':');
+        unsafeNodes.add(parts[0]);
+        return {
+            __fw_unserializable__: true,
+            nodeId: parts[0],
+            portName: parts[1] || 'unknown',
+            reason: 'Not JSON-serializable',
+        };
+    }
+}
+/**
+ * Compute SHA-256 hash of a file's contents.
+ */
+function hashFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// CheckpointWriter
+// ---------------------------------------------------------------------------
+export class CheckpointWriter {
+    dir;
+    filePath;
+    workflowName;
+    runId;
+    params;
+    workflowHash;
+    checkpointPath;
+    writeLock = Promise.resolve();
+    constructor(workflowFilePath, workflowName, runId, params = {}) {
+        this.filePath = path.resolve(workflowFilePath);
+        this.workflowName = workflowName;
+        this.runId = runId;
+        this.params = params;
+        this.dir = path.join(path.dirname(this.filePath), '.fw-checkpoints');
+        this.checkpointPath = path.join(this.dir, `${workflowName}-${runId}.json`);
+        this.workflowHash = hashFile(this.filePath);
+    }
+    /**
+     * Write a checkpoint after a node completes. Uses a write lock so
+     * concurrent calls from parallel nodes are serialized.
+     */
+    async write(completedNodes, executionOrder, position, ctx) {
+        // Serialize under a lock to prevent concurrent writes (parallel nodes)
+        this.writeLock = this.writeLock.then(() => this._writeCheckpoint(completedNodes, executionOrder, position, ctx));
+        await this.writeLock;
+    }
+    /** Clean up checkpoint file after successful completion */
+    cleanup() {
+        try {
+            if (fs.existsSync(this.checkpointPath)) {
+                fs.unlinkSync(this.checkpointPath);
+            }
+            // Remove directory if empty
+            if (fs.existsSync(this.dir)) {
+                const remaining = fs.readdirSync(this.dir);
+                if (remaining.length === 0) {
+                    fs.rmdirSync(this.dir);
+                }
+            }
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+    getCheckpointPath() {
+        return this.checkpointPath;
+    }
+    _writeCheckpoint(completedNodes, executionOrder, position, ctx) {
+        const serialized = ctx.serialize();
+        const unsafeNodes = new Set();
+        // Serialize variables, handling unserializable values
+        const variables = {};
+        for (const [key, value] of Object.entries(serialized.variables)) {
+            variables[key] = serializeValue(key, value, unsafeNodes);
+        }
+        const data = {
+            version: 1,
+            workflowHash: this.workflowHash,
+            workflowName: this.workflowName,
+            filePath: this.filePath,
+            params: this.params,
+            timestamp: new Date().toISOString(),
+            completedNodes: [...completedNodes],
+            executionOrder: [...executionOrder],
+            position,
+            variables,
+            executions: serialized.executions,
+            executionCounter: serialized.executionCounter,
+            nodeExecutionCounts: serialized.nodeExecutionCounts,
+            unsafeNodes: [...unsafeNodes],
+        };
+        // Ensure directory exists
+        if (!fs.existsSync(this.dir)) {
+            fs.mkdirSync(this.dir, { recursive: true });
+        }
+        fs.writeFileSync(this.checkpointPath, JSON.stringify(data, null, 2), 'utf8');
+    }
+}
+// ---------------------------------------------------------------------------
+// Checkpoint reading and resume
+// ---------------------------------------------------------------------------
+/**
+ * Load a checkpoint file and validate it against the current workflow.
+ * Returns the checkpoint data and a list of nodes that need to be re-run
+ * (because their outputs weren't serializable).
+ */
+export function loadCheckpoint(checkpointPath, workflowFilePath) {
+    const raw = fs.readFileSync(checkpointPath, 'utf8');
+    const data = JSON.parse(raw);
+    if (data.version !== 1) {
+        throw new Error(`Unsupported checkpoint version: ${data.version}`);
+    }
+    // Check if the workflow has changed since the checkpoint was written
+    let stale = false;
+    if (workflowFilePath) {
+        const currentHash = hashFile(path.resolve(workflowFilePath));
+        stale = currentHash !== data.workflowHash;
+    }
+    // Determine which nodes can be skipped (all outputs serialized) vs
+    // which need re-running (any output was unserializable)
+    const unsafeSet = new Set(data.unsafeNodes);
+    const rerunNodes = [];
+    const skipNodes = new Map();
+    // Walk execution order up to the checkpoint position.
+    // Once we hit an unsafe node, everything from that point forward re-runs.
+    let hitUnsafe = false;
+    for (const nodeId of data.completedNodes) {
+        if (hitUnsafe || unsafeSet.has(nodeId)) {
+            hitUnsafe = true;
+            rerunNodes.push(nodeId);
+            continue;
+        }
+        // Collect this node's outputs from the variables map
+        const nodeOutputs = {};
+        const prefix = `${nodeId}:`;
+        for (const [key, value] of Object.entries(data.variables)) {
+            if (key.startsWith(prefix) && !isUnserializableMarker(value)) {
+                // Store with portName:executionIndex as key
+                const rest = key.substring(prefix.length);
+                nodeOutputs[rest] = value;
+            }
+        }
+        skipNodes.set(nodeId, nodeOutputs);
+    }
+    return { data, stale, rerunNodes, skipNodes };
+}
+/**
+ * Find the most recent checkpoint file for a workflow.
+ */
+export function findLatestCheckpoint(workflowFilePath, workflowName) {
+    const dir = path.join(path.dirname(path.resolve(workflowFilePath)), '.fw-checkpoints');
+    if (!fs.existsSync(dir))
+        return null;
+    const files = fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .filter((f) => !workflowName || f.startsWith(`${workflowName}-`));
+    if (files.length === 0)
+        return null;
+    // Sort by modification time, newest first
+    const sorted = files
+        .map((f) => ({ name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+    return path.join(dir, sorted[0].name);
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/runtime/debug-controller.d.ts

@@ -0,0 +1,110 @@
+/**
+ * DebugController intercepts workflow execution at node boundaries,
+ * enabling step-through debugging and checkpoint/resume.
+ *
+ * Injected via globalThis.__fw_debug_controller__ (same pattern as
+ * __fw_debugger__ and __fw_agent_channel__). The generated code calls
+ * beforeNode/afterNode at each node boundary; the controller decides
+ * whether to skip, pause, checkpoint, or continue.
+ */
+import type { GeneratedExecutionContext } from './ExecutionContext.js';
+import type { CheckpointWriter } from './checkpoint.js';
+export type DebugMode = 'step' | 'continue' | 'continueToBreakpoint' | 'run';
+export interface DebugPauseState {
+    /** Node we're paused at */
+    currentNodeId: string;
+    /** Whether we paused before or after the node executed */
+    phase: 'before' | 'after';
+    /** Nodes that have finished executing */
+    completedNodes: string[];
+    /** Full topological execution order */
+    executionOrder: string[];
+    /** Current index in executionOrder */
+    position: number;
+    /** All variable values, keyed by "nodeId:portName" */
+    variables: Record<string, unknown>;
+    /** Outputs of the most recently completed node (convenience shortcut) */
+    currentNodeOutputs?: Record<string, unknown>;
+    /** Active breakpoints */
+    breakpoints: string[];
+}
+export type DebugResumeAction = {
+    type: 'step';
+} | {
+    type: 'continue';
+} | {
+    type: 'continueToBreakpoint';
+} | {
+    type: 'abort';
+};
+export interface DebugControllerConfig {
+    /** Enable step-through debugging (pauses before first node) */
+    debug?: boolean;
+    /** Enable checkpointing to disk after each node */
+    checkpoint?: boolean;
+    /** Checkpoint writer instance (required when checkpoint=true) */
+    checkpointWriter?: CheckpointWriter;
+    /** Initial breakpoint node IDs */
+    breakpoints?: string[];
+    /** Execution order (set by executor after compilation) */
+    executionOrder?: string[];
+    /** Nodes to skip on resume (loaded from checkpoint) */
+    skipNodes?: Map<string, Record<string, unknown>>;
+}
+export declare class DebugController {
+    private mode;
+    private breakpoints;
+    private completedNodes;
+    private completedSet;
+    private executionOrder;
+    private position;
+    private lastCompletedNodeId;
+    private checkpointEnabled;
+    private checkpointWriter;
+    private skipNodes;
+    private _gateResolve;
+    private _pauseResolve;
+    private _pausePromise;
+    private pendingModifications;
+    constructor(config?: DebugControllerConfig);
+    /** Set the execution order (called by executor after compilation) */
+    setExecutionOrder(order: string[]): void;
+    /**
+     * Called before a node executes.
+     * Returns true if the node should execute, false to skip.
+     */
+    beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<boolean>;
+    /**
+     * Called after a node completes successfully.
+     */
+    afterNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<void>;
+    /**
+     * Awaited by the executor to detect when the controller pauses.
+     * Resolves with the current debug state.
+     */
+    onPause(): Promise<DebugPauseState>;
+    /**
+     * Called by MCP tools or CLI to resume execution.
+     */
+    resume(action: DebugResumeAction): void;
+    /**
+     * Queue a variable modification. Applied before the next node runs.
+     * Key format: "nodeId:portName:executionIndex"
+     */
+    setVariable(key: string, value: unknown): void;
+    addBreakpoint(nodeId: string): void;
+    removeBreakpoint(nodeId: string): void;
+    getBreakpoints(): string[];
+    /** Build the current debug state for external consumers */
+    buildState(nodeId: string, phase: 'before' | 'after', ctx: GeneratedExecutionContext): DebugPauseState;
+    /** Get completed nodes list */
+    getCompletedNodes(): string[];
+    private pause;
+    private applyAction;
+    private applyPendingModifications;
+    private restoreNodeOutputs;
+    private extractVariables;
+    private extractNodeOutputs;
+    private _createPausePromise;
+}
+//# sourceMappingURL=debug-controller.d.ts.map

package/dist/runtime/debug-controller.js

@@ -0,0 +1,247 @@
+/**
+ * DebugController intercepts workflow execution at node boundaries,
+ * enabling step-through debugging and checkpoint/resume.
+ *
+ * Injected via globalThis.__fw_debug_controller__ (same pattern as
+ * __fw_debugger__ and __fw_agent_channel__). The generated code calls
+ * beforeNode/afterNode at each node boundary; the controller decides
+ * whether to skip, pause, checkpoint, or continue.
+ */
+// ---------------------------------------------------------------------------
+// DebugController
+// ---------------------------------------------------------------------------
+export class DebugController {
+    mode;
+    breakpoints;
+    completedNodes = [];
+    completedSet = new Set();
+    executionOrder = [];
+    position = 0;
+    lastCompletedNodeId = null;
+    // Checkpoint
+    checkpointEnabled;
+    checkpointWriter;
+    // Skip nodes (for resume from checkpoint)
+    skipNodes;
+    // Pause/resume channel (mirrors AgentChannel pattern)
+    _gateResolve = null;
+    _pauseResolve = null;
+    _pausePromise;
+    // Variable modification buffer: applied before next node runs
+    pendingModifications = new Map();
+    constructor(config = {}) {
+        this.mode = config.debug ? 'step' : 'run';
+        this.breakpoints = new Set(config.breakpoints ?? []);
+        this.checkpointEnabled = config.checkpoint ?? false;
+        this.checkpointWriter = config.checkpointWriter ?? null;
+        this.executionOrder = config.executionOrder ?? [];
+        this.skipNodes = config.skipNodes ?? new Map();
+        this._pausePromise = this._createPausePromise();
+    }
+    /** Set the execution order (called by executor after compilation) */
+    setExecutionOrder(order) {
+        this.executionOrder = order;
+    }
+    // -----------------------------------------------------------------------
+    // Node boundary hooks (called by generated code)
+    // -----------------------------------------------------------------------
+    /**
+     * Called before a node executes.
+     * Returns true if the node should execute, false to skip.
+     */
+    async beforeNode(nodeId, ctx) {
+        // Apply any pending variable modifications
+        this.applyPendingModifications(ctx);
+        // If this node should be skipped (resume from checkpoint), restore its
+        // outputs into the context and return false
+        if (this.skipNodes.has(nodeId)) {
+            const savedOutputs = this.skipNodes.get(nodeId);
+            this.restoreNodeOutputs(nodeId, savedOutputs, ctx);
+            this.completedNodes.push(nodeId);
+            this.completedSet.add(nodeId);
+            this.lastCompletedNodeId = nodeId;
+            this.position++;
+            return false;
+        }
+        // Check if we should pause here
+        const shouldPause = this.mode === 'step' ||
+            (this.mode === 'continueToBreakpoint' && this.breakpoints.has(nodeId));
+        if (shouldPause) {
+            const action = await this.pause(nodeId, 'before', ctx);
+            if (action.type === 'abort') {
+                throw new Error(`Debug session aborted at node "${nodeId}"`);
+            }
+            // Action may change mode for subsequent nodes
+            this.applyAction(action);
+        }
+        return true;
+    }
+    /**
+     * Called after a node completes successfully.
+     */
+    async afterNode(nodeId, ctx) {
+        this.completedNodes.push(nodeId);
+        this.completedSet.add(nodeId);
+        this.lastCompletedNodeId = nodeId;
+        this.position++;
+        // Write checkpoint to disk
+        if (this.checkpointEnabled && this.checkpointWriter) {
+            await this.checkpointWriter.write(this.completedNodes, this.executionOrder, this.position, ctx);
+        }
+        // Pause after node in step mode
+        if (this.mode === 'step') {
+            const action = await this.pause(nodeId, 'after', ctx);
+            if (action.type === 'abort') {
+                throw new Error(`Debug session aborted after node "${nodeId}"`);
+            }
+            this.applyAction(action);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Pause/resume channel
+    // -----------------------------------------------------------------------
+    /**
+     * Awaited by the executor to detect when the controller pauses.
+     * Resolves with the current debug state.
+     */
+    onPause() {
+        return this._pausePromise;
+    }
+    /**
+     * Called by MCP tools or CLI to resume execution.
+     */
+    resume(action) {
+        if (action.type !== 'abort') {
+            this.applyAction(action);
+        }
+        this._gateResolve?.(action);
+        this._gateResolve = null;
+        this._pausePromise = this._createPausePromise();
+    }
+    // -----------------------------------------------------------------------
+    // Variable modification
+    // -----------------------------------------------------------------------
+    /**
+     * Queue a variable modification. Applied before the next node runs.
+     * Key format: "nodeId:portName:executionIndex"
+     */
+    setVariable(key, value) {
+        this.pendingModifications.set(key, value);
+    }
+    // -----------------------------------------------------------------------
+    // Breakpoints
+    // -----------------------------------------------------------------------
+    addBreakpoint(nodeId) {
+        this.breakpoints.add(nodeId);
+    }
+    removeBreakpoint(nodeId) {
+        this.breakpoints.delete(nodeId);
+    }
+    getBreakpoints() {
+        return [...this.breakpoints];
+    }
+    // -----------------------------------------------------------------------
+    // State inspection
+    // -----------------------------------------------------------------------
+    /** Build the current debug state for external consumers */
+    buildState(nodeId, phase, ctx) {
+        const variables = this.extractVariables(ctx);
+        const currentNodeOutputs = this.lastCompletedNodeId
+            ? this.extractNodeOutputs(this.lastCompletedNodeId, variables)
+            : undefined;
+        return {
+            currentNodeId: nodeId,
+            phase,
+            completedNodes: [...this.completedNodes],
+            executionOrder: [...this.executionOrder],
+            position: this.position,
+            variables,
+            currentNodeOutputs,
+            breakpoints: [...this.breakpoints],
+        };
+    }
+    /** Get completed nodes list */
+    getCompletedNodes() {
+        return [...this.completedNodes];
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    async pause(nodeId, phase, ctx) {
+        const state = this.buildState(nodeId, phase, ctx);
+        // Signal the executor that we're paused
+        this._pauseResolve?.(state);
+        // Suspend on a gate Promise until resume() is called
+        return new Promise((resolve) => {
+            this._gateResolve = (action) => resolve(action);
+        });
+    }
+    applyAction(action) {
+        switch (action.type) {
+            case 'step':
+                this.mode = 'step';
+                break;
+            case 'continue':
+                this.mode = 'continue';
+                break;
+            case 'continueToBreakpoint':
+                this.mode = 'continueToBreakpoint';
+                break;
+            // 'abort' is handled by the caller (throws)
+        }
+    }
+    applyPendingModifications(ctx) {
+        if (this.pendingModifications.size === 0)
+            return;
+        for (const [key, value] of this.pendingModifications) {
+            // Key format: "nodeId:portName:executionIndex"
+            const parts = key.split(':');
+            if (parts.length >= 3) {
+                const address = {
+                    id: parts[0],
+                    portName: parts[1],
+                    executionIndex: parseInt(parts[2], 10),
+                };
+                ctx.setVariable(address, value);
+            }
+        }
+        this.pendingModifications.clear();
+    }
+    restoreNodeOutputs(nodeId, outputs, ctx) {
+        // outputs is keyed by "portName:executionIndex" -> value
+        // Don't call ctx.addExecution here: the generated code's else block handles
+        // execution registration so local variables (e.g. dIdx) are set correctly.
+        for (const [portKey, value] of Object.entries(outputs)) {
+            const colonIdx = portKey.lastIndexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const portName = portKey.substring(0, colonIdx);
+            const executionIndex = parseInt(portKey.substring(colonIdx + 1), 10);
+            ctx.setVariable({ id: nodeId, portName, executionIndex }, value);
+        }
+    }
+    extractVariables(ctx) {
+        const serialized = ctx.serialize();
+        return serialized.variables;
+    }
+    extractNodeOutputs(nodeId, allVariables) {
+        const outputs = {};
+        const prefix = `${nodeId}:`;
+        for (const [key, value] of Object.entries(allVariables)) {
+            if (key.startsWith(prefix)) {
+                // Extract portName from key "nodeId:portName:executionIndex"
+                const rest = key.substring(prefix.length);
+                const colonIdx = rest.lastIndexOf(':');
+                const portName = colonIdx >= 0 ? rest.substring(0, colonIdx) : rest;
+                outputs[portName] = value;
+            }
+        }
+        return outputs;
+    }
+    _createPausePromise() {
+        return new Promise((resolve) => {
+            this._pauseResolve = resolve;
+        });
+    }
+}
+//# sourceMappingURL=debug-controller.js.map

package/dist/runtime/index.d.ts

@@ -1,5 +1,9 @@
 export { GeneratedExecutionContext } from "./ExecutionContext.js";
 export { CancellationError } from "./CancellationError.js";
+export { DebugController } from "./debug-controller.js";
+export type { DebugMode, DebugPauseState, DebugResumeAction, DebugControllerConfig } from "./debug-controller.js";
+export { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from "./checkpoint.js";
+export type { CheckpointData } from "./checkpoint.js";
 export * from "./events.js";
 export * from "./function-registry.js";
 export * from "./parameter-resolver.js";

package/dist/runtime/index.js

@@ -1,5 +1,7 @@
 export { GeneratedExecutionContext } from "./ExecutionContext.js";
 export { CancellationError } from "./CancellationError.js";
+export { DebugController } from "./debug-controller.js";
+export { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from "./checkpoint.js";
 export * from "./events.js";
 export * from "./function-registry.js";
 export * from "./parameter-resolver.js";

package/docs/reference/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: CLI Reference
 description: Complete reference for all Flow Weaver CLI commands, flags, and options
-keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates]
+keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context]
 ---
 
 # CLI Reference
@@ -34,6 +34,7 @@ Complete reference for all `flow-weaver` CLI commands.
 | `changelog` | Generate changelog from git |
 | `market` | Marketplace packages |
 | `plugin` | External plugins |
+| `context` | Generate LLM context bundle |
 | `docs` | Browse reference documentation |
 | `ui` | Send commands to the editor |
 | `listen` | Stream editor events |
@@ -176,6 +177,10 @@ flow-weaver run <input> [options]
 | `--timeout <ms>` | Execution timeout in milliseconds | — |
 | `--mocks <json>` | Mock config for built-in nodes as JSON | — |
 | `--mocks-file <path>` | Path to JSON file with mock config | — |
+| `-d, --debug` | Start in step-through debug mode | `false` |
+| `--checkpoint` | Enable checkpointing to disk after each node | `false` |
+| `--resume [file]` | Resume from a checkpoint file (auto-detects latest if no file given) | — |
+| `-b, --breakpoint <nodeIds...>` | Set initial breakpoints (repeatable) | — |
 
 **Examples:**
 ```bash
@@ -183,9 +188,13 @@ flow-weaver run workflow.ts --params '{"amount": 500}'
 flow-weaver run workflow.ts --params-file input.json --trace
 flow-weaver run workflow.ts --mocks '{"fast": true, "events": {"app/approved": {"status": "ok"}}}'
 flow-weaver run workflow.ts --timeout 30000 --json
+flow-weaver run workflow.ts --debug
+flow-weaver run workflow.ts --checkpoint
+flow-weaver run workflow.ts --resume
+flow-weaver run workflow.ts --debug --breakpoint processData --breakpoint validate
 ```
 
-> See also: [Built-in Nodes](built-in-nodes) for mock configuration details.
+> See also: [Built-in Nodes](built-in-nodes) for mock configuration details, [Debugging](debugging) for debug REPL commands and checkpoint details.
 
 ---
 
@@ -797,6 +806,37 @@ flow-weaver docs search "missing workflow"
 
 ---
 
+### context
+
+Generate a self-contained LLM context bundle from documentation and annotation grammar. Two profiles control the output format: `standalone` produces a complete reference for pasting into any LLM, `assistant` produces a leaner version that assumes MCP tools are available.
+
+```bash
+flow-weaver context [preset] [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--profile <profile>` | `standalone` or `assistant` | `standalone` |
+| `--topics <slugs>` | Comma-separated topic slugs (overrides preset) | — |
+| `--add <slugs>` | Extra topic slugs on top of preset | — |
+| `--no-grammar` | Omit EBNF grammar section | grammar included |
+| `-o, --output <path>` | Write to file instead of stdout | stdout |
+| `--list` | List available presets and exit | — |
+
+Built-in presets: `core` (concepts, grammar, tutorial), `authoring` (concepts, grammar, annotations, built-in nodes, scaffold, node-conversion, patterns), `ops` (CLI, compilation, deployment, export, debugging, error-codes), `full` (all 16 topics).
+
+**Examples:**
+```bash
+flow-weaver context core | pbcopy
+flow-weaver context full -o .flow-weaver-context.md
+flow-weaver context authoring --profile assistant
+flow-weaver context --topics concepts,jsdoc-grammar,error-codes
+flow-weaver context core --add error-codes
+flow-weaver context --list
+```
+
+---
+
 ## Editor Integration
 
 ### ui focus-node