circuitRF: Instructions file for Claude Code

circuitRF

Lightweight cross-platform RF circuit simulator (DC, S-parameters, harmonic balance, loadpull/sourcepull). See docs/PRD.md for scope - may not be update to date.

Searching this repo

Use grep (or ripgrep) directly whenever possible instead of spawning a search agent. This repo's structure is well-known and its files are plain text — a targeted grep -n finds a symbol, class, or XAML control faster and far cheaper than delegating a "find X" task to an agent. Reach for an agent only when the search genuinely needs multi-step reasoning across many unrelated locations, not for straightforward lookups.

Resolving Issues

If significant findings were found during bug fixes or changes, write to the relevant RESOLVED.md files never CLAUDE.md. This helps keep the CLAUDE.md files small.

Never quote the owner or users in git commit comments, RESOLVED.md files or anywhere in the code. Instead, briefly paraphrase owner/user messages. Pre-existing quotes are ok.

Stack

• .NET 10 (LTS), C# 14

• Avalonia 12 (UI), SkiaSharp (canvas rendering), CommunityToolkit.MVVM (MVVM)

• CSparse.NET (sparse complex LU for large MNA), NumFlat (dense linear algebra)

  The architectural boundary is unchanged and does not depend on directory placement — it is enforced by assembly-reference checks in tests/Firewall.Tests.

Build / test / run

• Build: dotnet build

• Test: dotnet test

• Run CLI: dotnet run --project src/Cli -- <args>

• For faster simulations, run the Release build: dotnet run --project src/Ui -c Release

  The installed circuitRF executable IS the CLI (AUT-13): src/Ui/Program.Main's first statement hands a verb to CliEntry.Run (IsVerb comes from Run's own switch; the verb must be args[0]). The verbs build as the library src/Cli.Verbs, which compiles src/Cli/*.cs in place; src/Cli's project is Program.cs only. Windows adds a console-subsystem circuitRF.com twin of the stub. Detail: docs/design/cli.md §20. Verbs: sparam, dc, hb, lp, lpp, em, convert, new, import, check, explain, history, render, netlist, plot, find, rail, smith, snp, lvs, elab. The CLI has its own design doc — docs/design/cli.md — covering the five-step anatomy of a run verb, the stdout/stderr split, and the rules below; read it before adding a verb. hb/lp/lpp run the netlist's harmonic-balance, loadpull and loadpull-pursuit analyses, and each runs the whole sweep when a parametric_sweep wraps it (naming the inner analysis is promoted to its wrapper, since running the inner alone silently drops the sweep axis — a freq-swept loadpull is exactly this shape). They evaluate the TestBench's measure lines exactly as the GUI does, so a .cnl that works headless works when opened. --set var=expr overrides a global before elaboration; every other override replaces the DIRECTIVE in the TestBench, because the sweep engine re-resolves it at each point and an override handed to one engine instance is discarded after the first. -o out.{mat,npy,txt} exports, and lp also writes .spl/.lpcwave — the loadpull interchange the Data Display reads back. em takes a .cem and needs no other arguments (2026-08-26). Both references it must follow are WALK-UPS, not flags: the layout is relative to the nearest ancestor .cws above the .cem (falling back to the .cem's own directory), and the technology resolves against the LAYOUT's own parent workspace. It writes exactly where Simulate writes — EmRunService.ResolveSnpPath is predictable by design so a schematic's SnP reference survives a re-run — and -o moves the Touchstone only, never the .npy that carries the diagnostics group. A refusal stays a refusal: Refused/NoLayout/EngineError exit 1 with the run service's own sentence, Cancelled exits 130. The gate is tests/Ui.Tests/Em/EmCliVerbTests.cs, which compares the CLI's .sNp byte for byte against EmRunService.Run's — every line but the provenance write-timestamp and run stamp, which the file carries by design; the .npy differs only by that stamp. The setup's Output name decides every result file, .cemr record included; -o is EmRunTarget.TouchstoneDestination (CP-1, cli.md §8.2). convert is one import and one export (2026-09): every ordered pair of clay/gdsii/dxf/ gerber/board works because every reader lands on a cell folder plus a technology and every writer starts from one — a .clay target stops after the import, anything else exports out of a scratch directory (--keep-cells keeps it). A clay target is a DIRECTORY; a file-shaped path is a refusal naming the directory spelling (AUT-12). Formats infer from the paths (a FOLDER is a Gerber file set; an unknown extension is classified by CONTENT through the import's own classifier); --from/ --to override. Two things the GUI asks in a dialog: the layer mapping takes the same default the dialog pre-selects, and an unstated Excellon coordinate format is a REFUSAL, never a guess — leading vs trailing suppression differ by four orders of magnitude on identical text, so it prints the inference and the flags that answer it. Headless there is no open workspace to graft layers onto, so it writes a .ctech of its own; passing a null destination technology to any importer silently drops every layer — src/Design/RESOLVED.md records why. Gate: tests/Ui.Tests/ConvertCliVerbTests.cs (all 24 pairs, plus byte identity against the in-process GdsiiExport/GerberExport the GUI's own File ▸ Export calls). new workspace <dir>, new cell <ws> <name> and import part <file> --into <dir> create a correct INITIAL document headlessly (2026-09-05) — and none of them contains any creation logic: each calls the one function the GUI's own command calls (WorkspaceCreate.Create, CellCreate, ComponentImport.Import, all in src/Design). An operation that lives only in a view model is not a capability, and a verb that re-implements one diverges from it silently — so the extraction is the feature and src/Cli/Authoring.cs is only argument parsing, refusals and reporting. new is ONE verb with a noun, not three; new schematic would be a fourth noun, never a fourth verb. There are deliberately no per-primitive edit verbs — no place-instance, no set-parameter: once a document exists, the way to change it is to WRITE it, because the format is the contract. Every default is the GUI dialog's — --tech opens on what the New Workspace combobox opens on (--tech none is its "None" row, and an unknown id is a refusal listing the real ones, never a fallback), --views defaults to schematic because that is what New Cell creates, and the layer mapping takes the same default convert's does. Anything the dialog would have ASKED is a refusal naming the flag that answers it: a source holding several parts prints them and stops (--cell / --variant / --list-parts). import part reports the layers its technology lacks and writes none unless --add-layers says so — the GUI's own install is session-only and writes nothing to disk either. The paths created ARE the result, on stdout and in --json. Gate: tests/Ui.Tests/AuthoringCliVerbTests.cs — the CLI as a process, byte for byte against the in-process call, a comment-stripped source scan proving the view model kept no second copy, and the end-to-end that authors a design and simulates it with no display at any step. ShippedTechnologies and its .ctech resources moved to src/Design for this; moving such a class without its EmbeddedResource items leaves it enumerating nothing, silently. check <path> and explain <path> are read-only, and neither runs an analysis (2026-09-05). check answers "is it well formed, does it resolve, is it sound" over a workspace, a cell folder or one document — the kind inferred from the path exactly as convert infers a format, and a foreign file classified through convert's OWN classifier so a GDSII or Gerber file is named rather than called unreadable. It writes NO validation logic of its own: every finding comes from a validator the GUI already uses (CellViewFileValidator, CellFolder.ResolvePrimary, NameValidator, TechValidation, TechnologyResolver, EmSetupResolver, CellSymbolResolver, NetExtractor, Elaborator, ChainSelector, DrcPredicateParser, DrcEngine) — a rule living only in check is a rule the application does not enforce, so a design would pass headlessly and be refused when someone opened it. Exit 0 unless something at or above --severity (default error) was found; warnings are ALWAYS reported and still exit 0, because a check that hid them to keep the exit code clean makes the exit code useless. It writes nothing at all, so it runs on a read-only tree and on a workspace another process has open. explain answers the question that is not a failure — what did circuitRF decide — and reports the WALK as well as the answer, because resolution here is a series of walk-ups and which one produced an answer is the part a caller cannot otherwise see (a .cem's layout and technology walks start from different files and can land on different workspaces). --expr evaluates in the design's own resolved scope through the one expression engine, with --set applied first exactly as a run verb applies it; --analysis reports every declared chain, which one dispatches and for which verb, and whether a named inner analysis would be promoted; --ref resolves a relative reference and says whether it leaves the workspace. A sweep is reported in base SI WITH its unit and its scale — reading a mark without its scale once produced a run at 2 Hz that looked entirely normal. --extents also emits a window string in the spelling render --window takes (AUT-12). A .csch reaches the elaborator through the .cnl, in memory, because that is what the GUI's own Simulate does and the two readers disagree about bare words: skipping the round trip reports errors the application does not have. The DRC engine and the .wasm rule model moved to src/Design to make the layout half of check possible. Gate: tests/Ui.Tests/CheckAndExplainCliVerbTests.cs. history is ONE verb with nouns, and every revision-control operation has a spelling on it (docs/design/revision-control.md §5.3d) — checkpoint, list, restore, commit, versions, and RC-9's clone, pins, pin, unpin, fetch, send. It exists because the governing motive of that whole feature is a floor under an AI-authored edit and the agent is out of process: a safety net reachable only from a window is worth nothing to it. Each noun calls the src/Design function the GUI's own command calls and holds no logic of its own — the rule Authoring.cs already states, and a comment-stripped source scan is what holds it. The batch's open and close are deliberately NOT here: they carry session state a process that exits after one command cannot, so they stay on serve; history checkpoint --intent IS what a batch's open takes. clone derives nothing — both the address and the destination folder are required, because git would work a folder name out of the address and a folder appearing somewhere the caller did not name is a surprise nobody is there to notice on a build machine. pins/pin name an ALIAS and there is no per-cell spelling: one referenced workspace is one repository with one commit identity, and pinning per cell would let one design reference two mutually inconsistent versions of one library. pins exits 1 on a pin that cannot be honoured — a build machine treating that as a warning would produce a result against content the design was never verified against, which is the one outcome the pin exists to prevent. Nothing reaches a network without being asked (fetch/send only), and circuitRF holds no credential and asks for none: it uses whatever git is already configured with, and GIT_TERMINAL_PROMPT=0 turns an operation that would have asked into a refusal rather than a process that never returns. pins/pin/unpin need no repository — the pin lives in the consuming design's .cws, which is very often a workspace circuitRF has never kept a history for. Gates: tests/Ui.Tests/Revision/CloneAndPinsTests.cs and the RC-5/RC-7 files beside it. render <path> -o out.{svg,pdf,png} turns a .csch, .csym or .clay into a picture, and it owns no rendering (2026-09-07) — every pixel comes out of the three Skia renderers in CircuitRF.Render that the application draws each frame with, which is the whole reason RND-1 put that project below the firewall. src/Cli/Render.cs is argument parsing, viewport arithmetic, refusals and reporting, on Authoring.cs' terms. One verb over every document kind, inferred through DocumentKinds.Classify exactly as check infers it; a cell folder takes --view (more than one view is a refusal LISTING them), a workspace takes --cell, and a document belonging to no workspace is a first-class input — it resolves no technology, renders on the fallback palette as the layout editor does, and says so as a NOTE rather than a warning. -o is required and its extension picks the format: there is no picture on stdout, because stdout is the result document and --json has to co-exist with the write. --fit (the default), --window and --center/--span are refused together rather than ordered, and on a layout every coordinate carries an SI unit — a bare number is a refusal, because --window 0,0,500,300 could mean DBU, µm or mm and all three are plausible. A window of a different aspect is letterboxed, never cropped. --detail full (the default) turns every LOD tier off so what is STORED is what is drawn; --detail screen engages them as a canvas would, and on a real board that is the difference between a 23.5 MB SVG in 1.44 s and a 6.2 MB one in 0.36 s. --layers/--hide-layers apply to a CLONE of the resolved technology (TechnologyLayerSelection, in src/Design) — TechnologyCache hands back a shared instance and mutating it would narrow every later render in the same process, which is the defect that only appears on the second call. --fit-layers frames the fit on some layers and draws all of them; --layer-colors name=#rrggbb[aa] recolours one for this render only — eight digits sets FILL OPACITY, the only alpha the renderer reads (AUT-12). Rulers stay ON (document content, not overlay state); every other overlay is off by construction. Progress and cancellation ride RunHost's RunControl like em's, so a cancelled render exits 130 and writes nothing. Gate: tests/Ui.Tests/Render/RenderCliVerbTests.cs, which compares the verb run as a PROCESS against the in-process CircuitRF.Render call byte for byte — schematic, symbol and layout, SVG and PDF, and all four came back identical with no exclusion at all. render x.c3d -o out.png --field <plot> draws a clip-plane field plot; --list-fields lists them (brief-em3d-84) — resolution is FieldPlotResolver in src/Render, shared with the 3D view; cli.md §13.8.1. A clip-plane TEMPERATURE plot renders too, wires painted from their T(s); --labels --tight --axes --scale-bar (brief-em3d-88). netlist <path.csch> [-o out.cnl] writes the extraction Simulate performs, and every run verb now takes a .csch too (2026-09-08) — until then nothing headless could simulate a design anyone had DRAWN: a run handed the JSON to CnlReader, which reported its first key as a missing cell name. Both halves go through CircuitSource.CnlTextOf, so the file written is the same BYTES a run consumes; the provenance comment is a constant for that reason, and the gate scans src/Cli for a second CnlWriter.Write — the WRITER, not NetExtractor.Extract, which check calls on its own account. Any other document kind is a refusal BY KIND. plot <result> -o out.svg --trace cube=S,i=2,j=1,y=db is one picture with no .cdd to author first, and not a second plotting path: it builds the document render --data consumes and hands it to the same composer (--write-cdd gives that document back). cube= is the trace card's own shorthand. An integer on an i/j axis is a 1-based PORT NUMBER, not an index — converting it draws S12 for i=2,j=1 in silence, which is invisible on a reciprocal part. find <root> [--depth n] says what is here — workspaces, cells, views, declared analyses. The walk is bounded and says when it stopped short; a directory symlink is never followed. Gate for all three: tests/Ui.Tests/Cli/MissingVerbsCliTests.cs; detail in src/Cli/RESOLVED.md and cli.md §14-16. new workspace also creates missing PARENT directories now. lvs <path> compares a cell's layout against its schematic (2026-09-21) — a cell folder, a workspace, a .clay or a .csch, the kind inferred as check infers it. It owns no comparison: every finding comes out of LvsRun.Run in src/Design/Layout/Lvs, the function the GUI panel calls, so a design that passes headlessly passes when it is opened. Read-only on check's terms — -o report.txt is the only thing it ever writes. A cell with one of the two views is INFO and skipped, not a refusal: that is the ordinary mid-design state. Exit 0/1 on --severity (default error; warnings always reported), 130 on cancellation, and never 2 — nothing here solves. cli.md §19; gate tests/Ui.Tests/Lvs/LvsCliVerbTests.cs.

• Package: exactly one script per platform, and each builds everything that platform ships — packaging/windows/build-windows.ps1 (9 files: .msi x64/arm64/x86 in both install scopes, plus the .zip the updater fetches), packaging/macos/build-macos.sh (2 .dmgs, both architectures; wraps the existing src/Ui/bundleFor*MacOS.sh), packaging/linux/build-linux.sh (4 files: .deb and .tar.gz for x64/arm64; fpm is needed only for the .deb). All write to dist/. Flags narrow a run; the no-argument form is the release form, because 1.0.0-beta.2 shipped 7 of its 15 artifacts when Windows defaulted to one architecture in one scope and Linux was two scripts — silently, since a missing update payload stops updates with no error. Held by tests/Ui.Tests/PackagingScriptTests.cs. Every script runs tools/CliSmoke against its own publish tree and fails unless the CLI answers — beta.1–32 shipped no CLI because nothing did; an architecture the host cannot execute fails unless CRF_ALLOW_UNSMOKED=1. Each must run ON its own platform (WiX is Windows-only, codesign/hdiutil macOS-only, and the Windows PE icon is only embedded when the publish happens on Windows). Step-by-step instructions live in BUILDING.md, which README.md links to; keep the two in step. App icons (.icns/.ico/.png) are build products rasterised from the committed brand SVGs by dotnet run --project tools/IconGen, which every packaging script runs first — no icon binary is ever committed.