io.neosyn/cg-agent-kit

What this host can actually do — PROBED, not assumed. Call it before deciding how to verify a design. Returns {jar, jar_present, bytecode_simulator:{available,reason,detail}, simulators:[...], tools:{iverilog,vvp,verilator,yosys,ghdl}, advice}. The fast bytecode simulator ships with the commercial Neosyn distribution and is absent from the open-source compiler, so any fixed claim about it is wrong for one of the two audiences. `advice` is written from what was actually found here.

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.

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); 'handshakes' (port protocols push/stream/confirm, back-pressure, and the pacing gotcha when feeding a registered built-in — read before wiring a network); 'arithmetic' (what *, /, %, <<, >> synthesize to and when they need a std.math built-in or a barrel shifter — read before writing math); 'fsm' (control FSMs: enum state register, Moore vs Mealy, and the two timing rules that break first drafts — read before writing a sequencer, protocol controller or serial block like UART/SPI); 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.

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.

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

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.

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

Finalize the FPGA report: (re)render <report_dir>/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 <report_dir>/verilog and renders. Workflow: cg_generate_verilog(output_dir="<report_dir>/verilog", package_dir=...) cg_simulate(..., report_dir="<report_dir>") cg_synth(..., report_dir="<report_dir>") # once per kernel cg_report(report_dir="<report_dir>") # finalize + schematics Returns {ok, report (the .html path), kernels, sim_ok, message}. Set `schematics=False` to skip the SVGs (faster).

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.

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_dir>/report.html — synthesizing the kernels builds the whole report as a byproduct, no separate step (see cg_report). Pass report_dir="…