Parse, scope, and type-check C⏚ source without running it. Returns {ok, diagnostics:[{file,line,message}], summary}. Call this first on any draft; fix every diagnostic before simulating. extra_files maps filename → content for imported bundles/tasks (e.g. {"Defs.cg": "..."}). For a MULTI-FILE project, pass package_dir (the folder holding your .cg files, e.g. "fpga/src/main/cg", relative to the project root): the tool then reads every sibling .cg there, so tasks defined in other files of the same package resolve — just like the IDE. A task you only got from cg_example is text; it must be saved to a file in that dir to resolve.

Simulate C⏚ source. Returns {ok, simulator, timed_out, diagnostics, output}. output holds port values and print() lines; a properties { test: {...} } block self-checks and fails the run on mismatch. This is the ground-truth correctness check — iterate until ok is true.

simulator picks the backend: 'bytecode' (default — the compiler's fast simulator, no HDL toolchain) or 'iverilog' (generate Verilog + testbench and run Icarus Verilog, a Verilog-level cross-check; needs a network <Name>_test). 'verilator' is accepted but reported unavailable unless installed.

For a MULTI-FILE project, pass package_dir (the folder with your .cg files, e.g. "fpga/src/main/cg") so every sibling task in the same package resolves — a cg_example you pulled must be saved to a file in that dir, not just referenced.

report_dir DEFAULTS to "fpga/build" — this run's PASS/FAIL + output is recorded into that dir's accumulating report.html (see cg_report). Pass report_dir="" to disable.

Generate synthesizable HDL from C⏚. target is 'verilog' (default) or 'vhdl'. Returns {ok, file_count, files:{path:content}}. Use after cg_simulate passes, to hand off RTL.

Pass output_dir (e.g. "fpga/build/verilog", relative to the project root) to WRITE the files to disk and KEEP them — the result then also carries {output_dir, written:[paths]}. Without it the files are only returned inline and the temp dir is cleaned. Prefer output_dir when the host needs the .v on disk (to inspect or run yosys).

For a MULTI-FILE project, pass package_dir (the folder with your .cg files) so sibling tasks in the same package resolve during generation.

Get a VERIFIED C⏚ base to seed-and-adapt from (don't synthesize hard kernels from scratch — adapt a known-good one). This is a curated dictionary of validated code with scored lazy lookup, NOT free-form search. No pattern → a compact index (name + kind + use_when + tags). A pattern → the single best-matching source plus its metadata and 1-2 runners_up so you can self-correct on an ambiguous query. k>1 also returns the next sources when the task implies composition.

Matching is specificity-weighted (exact name ≫ name word ≫ full tag phrase ≫ partial overlap), so e.g. "1/sqrt" → RSqrt while a bare "sqrt" → FixedSqrt. kind distinguishes general PRIMITIVES (the reusable library: Recip, Divide, SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct, Fir, Integ, Distance, Counter) from application EXAMPLES (Force, GalaxyForce). Every entry passes simulate + generate + iverilog + yosys. Workflow: cg_example → edit only the dataflow → cg_check → cg_simulate → cg_generate_verilog → cg_synth.

Map a compiler error/diagnostic to the recipe that demonstrates the synthesizable pattern for what was rejected. Returns {ok, recipe, hint, source}. div/shift-by-a-variable → Recip (bit-serial long division); a data-dependent/runtime loop bound → SeqDiv (sequential FSM divider). cg_check/cg_simulate/cg_generate_verilog already auto-attach this as a suggestion when a diagnostic matches; call this directly to look one up.

Synthesize the generated Verilog with yosys — the strongest signal that a design maps to real hardware (catches non-synthesizable constructs that simulate/iverilog accept). Returns {ok, verdict, top, flow, cells, arith_ops, latches, warnings, stat, problems, output}. verdict is the one-word classification so you can't confabulate success: REAL (a genuine datapath), FOLDED (0 datapath cells — inputs weren't on ports, dead hardware), SUSPECT (latches inferred — a data-dependent loop / missing reset), or ERROR (yosys failed). cells is the gate count; problems lists any ERROR/Warning lines.

warnings flags the two silent failure modes: a DEGENERATE datapath (arith_ops == 0 → the design constant-folded; drive it with input ports) and inferred LATCHES (latches > 0 → a data-dependent loop bound or incomplete assignment; expected a clocked FSM). A clean synth has ok: true, a sensible cells, arith_ops > 0, and empty warnings.

NOT a correctness oracle: a REAL verdict means real (synthesizable) hardware, NOT correct hardware — it can't tell a good sequential FSM from a buggy one. cg_simulate (the asserting test network) is the correctness check; run it FIRST, then cg_synth to confirm the hardware is real, not folded or latched.

top defaults to the first non-testbench task/network (the DUT); pass it when a file holds several designs. flow selects the synthesis flow: 'generic' (default, portable check) or a vendor FPGA family — 'ice40', 'ecp5', 'xilinx', 'gowin', 'intel' — to map to that part's primitives. Override the yosys binary with the $YOSYS env var. Run after cg_simulate passes. A constant-bound for synthesizes (it's unrolled); a data-dependent loop becomes an FSM (also fine).

report_dir DEFAULTS to "fpga/build", so each synth automatically records THIS kernel's verdict + cell counts as a row in /report.html — synthesizing the kernels builds the whole report as a byproduct, no separate step (see cg_report). Pass report_dir="" to disable.

Finalize the FPGA report: (re)render /report.html — a self-contained HTML with the synthesis table (REAL/FOLDED/SUSPECT verdict

• cell/arith/latch counts), the simulation PASS/FAIL + output, the generated-Verilog file list, and (best-effort) datapath schematic SVGs.

This does NO synthesis — the rows are built incrementally by passing the SAME report_dir to cg_synth (per kernel) and cg_simulate as you run them; cg_report just aggregates those fragments + the Verilog under /verilog and renders. Workflow: cg_generate_verilog(output_dir="/verilog", package_dir=...) cg_simulate(..., report_dir="") cg_synth(..., report_dir="") # once per kernel cg_report(report_dir="") # finalize + schematics Returns {ok, report (the .html path), kernels, sim_ok, message}. Set schematics=False to skip the SVGs (faster).

Show a task's compiled state machine (states + transitions). Useful to confirm an FSM has the intended number of states.

Show a network's compiled graph (instances, ports with widths and interfaces, connections). Useful to confirm wiring.

Fetch a markdown knowledge doc. No topic → an index of available topics with descriptions; a topic → its full content. Topics: 'context' (the core C⏚ language pack — load before writing any Cg) and 'riscv' (the worked RV32I CPU reference: the loadable single-cycle core and the reusable patterns for CPU-shaped hardware in Cg — barrel shifter, signed/unsigned widening, sub-word load/store, count-prefixed boot-stream program loading, and the lossless-capture / address-filtered testbench patterns). Read 'riscv' when building or extending a processor, instruction decoder, datapath, or stack machine.