Konnect naming conventions

Consistent names are part of Konnect's public API. They help contributors search the repository, let agents infer related operations, and prevent accidental compatibility breaks. New code and documentation must follow this guide. Existing public names are changed only with an explicit compatibility plan.

Product and protocol names

Use the official spelling in prose, comments, errors, and UI text:

Use	Do not introduce	Notes
Konnect	konnect as a product name	Lowercase remains correct for binaries, crates, commands, and paths.
KiCad	KiCAD, Kicad	Applies to NEW prose only — the existing codebase uses KiCAD widely (~400 occurrences) and is not to be mass-renamed; match surrounding style when editing existing text.
MCP	Mcp in prose	Rust type names use Mcp, for example McpHandler.
IPC	Ipc in prose	Rust type names use Ipc, for example KiCadIpcClient.
PCB, ERC, DRC, BOM	mixed-case variants in prose	Rust identifiers treat each acronym as a word.
JLCPCB, LCSC	informal abbreviations	Part IDs are called LCSC IDs.
S-expression	S-Expression, sexp in prose	sexp remains correct in Rust module and function names.

Prefer the domain's exact term: footprint for a PCB instance or library item, symbol for a schematic item, reference for R1, and value for 10 kΩ. Use component only for concepts that intentionally span symbols and footprints.

Rust

Follow the Rust API Guidelines and rustfmt, with these repository-specific choices:

• Crates and Cargo packages use kebab-case: konnect-core, konnect-ipc.
• Modules, files, functions, methods, variables, and fields use snake_case: pcb_components, ensure_board_is_active, ipc_address.
• Types and traits use UpperCamelCase. Acronyms are words: KiCadIpcClient, McpHandler, IpcFootprint, UuidCache.
• Constants and environment variables use SCREAMING_SNAKE_CASE: HOOK_SKILLS, KICAD_API_SOCKET, KONNECT_LOG.
• Boolean names describe a true state with is_, has_, can_, or should_ when the prefix adds clarity: is_error, has_pull_up.
• Fallible find_* functions return Option when absence is normal. get_* functions return Result when retrieval can fail. Mutation verbs should be precise: create, add, update, move, delete, write, or replace.

Handlers are named handle_<tool_name>. A tool definition named place_component therefore maps to handle_place_component in the same toolset module.

Public MCP tools and JSON

MCP tool names and toolset names are stable public API:

• Use lowercase snake_case: pcb_components, place_component, get_board_info.
• Begin tools with a concrete verb. Prefer get_ for one object, list_ for a collection, create_ for a new persisted object, and set_ for replacement.
• Do not encode the transport or implementation in a tool name unless it changes the user-visible contract. Describe IPC or file requirements in the tool description.
• Use the same noun across the tool name, schema, response, docs, and tests.
• Never silently rename or reuse a tool. Add an alias/deprecation period and document the migration when a public rename is unavoidable.

Tool arguments and Konnect-owned JSON keys use snake_case. Protocol-defined JSON-RPC and MCP fields retain the specification's spelling, such as jsonrpc, tools/list, and serverInfo. KiCad plugin manifests retain the KiCad schema's field names.

Collection responses use a plural noun plus count when useful:

{
  "count": 2,
  "components": []
}

Errors name the failed subject and action. Avoid a bare not found; prefer footprint 'R17' not found on the active board.

Units, paths, and identifiers

Make ambiguous values self-describing:

• Append units to non-domain-obvious values: _mm, _nm, _degrees, _ms, _bytes. Coordinates in established PCB/schematic tool schemas are millimetres; document that contract in the schema.
• Use _path for a file or unresolved filesystem path and _dir for a directory. A variable named board may be a public tool argument for compatibility; local Rust variables should prefer board_path when they contain a Path.
• Distinguish identifiers: uuid for a textual UUID, kiid for KiCad's item ID, lcsc_id for an LCSC part number, net_code for KiCad's numeric net code, and reference for a designator such as U3.
• Use _count for quantities and _index for zero-based positions. Avoid num when either meaning is possible.

Files, scripts, and documentation

• Rust and Python source files use snake_case.
• Command-line and packaging scripts use kebab-case: build-pcm.sh, validate-pcm.py.
• User-facing guides use uppercase names for repository-level conventions (CONTRIBUTING.md, DEV.md) and descriptive uppercase or kebab-case names under docs/. Do not rename an established guide solely to change its case.
• Tests describe observable behavior in snake_case, for example delete_items_surfaces_per_item_failure.
• Fixtures include the behavior or issue they represent; avoid test1 and sample2.
• Generated protobuf code and vendored protocol definitions keep upstream naming. Do not hand-edit generated files.

Branches, commits, and pull requests

Use a short lowercase branch name with a category and topic:

fix/indent-safe-wire-delete
feat/linux-pcm-support
docs/naming-conventions

Pull request titles use an imperative Conventional Commit-style prefix:

fix(schematic): preserve tab-indented wire blocks
feat(ipc): place footprints through typed KiCad messages
docs(contributing): define naming conventions

Recommended types are fix, feat, docs, test, refactor, build, ci, and chore. Keep each pull request focused on one reviewable outcome. Use the body for context and issue links rather than packing them into the title.

Commit subjects are imperative, specific, and under roughly 72 characters. Remove fixup!, merge noise, generated build output, and unrelated formatting before review.

Compatibility checklist

Before introducing or changing a name, check:

1. Is it public in MCP, CLI flags, environment variables, JSON, plugin metadata, logs, or documented filesystem paths?
2. Does the same concept already have a name elsewhere in the repository?
3. Can users and agents infer its type, unit, and scope without reading the body?
4. Would a rename require an alias, serde alias, migration note, or deprecation period?
5. Are tests, tool-directory metadata, examples, and error messages updated together?

When compatibility and style conflict, preserve compatibility and document the legacy name. Consistency is valuable; silently breaking users is worse.