# AGENTS.md

## Scope

This file defines agent operating rules for the standalone LinuxCNC WASM
simulation port located under `wasm-port/`.

This workspace is separate from the upstream LinuxCNC tree in
`../linuxcnc/`.

## Primary Objective

Build a standalone CNC simulation system that:

- reuses LinuxCNC source as the semantic source of truth;
- compiles core CNC logic to WASM;
- uses HTML + JavaScript for the frontend;
- uses OPFS for browser persistence;
- does not drive real hardware;
- preserves LinuxCNC software behavior as closely as practical.

## Repository Boundaries

1. `../linuxcnc/` is upstream and must be treated as read-only input for the
   port effort.
2. Port-specific code must live under `wasm-port/`.
3. Vendored LinuxCNC source copies must live under
   `wasm-port/vendor/linuxcnc/`.
4. Any source-level adaptation must be applied to vendored copies only.
5. Never treat experimental files under `../linuxcnc/web/` as the official
   port target. The official port program is managed here.

## Engineering Rules

1. Reuse LinuxCNC source before reimplementing any CNC logic.
2. Prefer wrappers, shims, and extraction scripts over invasive source edits.
3. Preserve LinuxCNC semantics for:
   - G-code execution;
   - modal state;
   - parameter and variable behavior;
   - kinematics;
   - planner behavior;
   - machine and controller state visible to software.
4. Replace only the native runtime edges:
   - file IO;
   - process model;
   - HAL runtime;
   - IPC;
   - GUI.
5. Frontend code must be implemented with web technology, not migrated from
   native GUI code.

## Required Layout

The standalone port should use these major areas:

- `docs/`
- `vendor/`
- `patches/`
- `tools/`
- `runtime/core/`
- `runtime/sdk/`
- `runtime/ui/`
- `runtime/opfs/`
- `tests/`

Do not collapse these concerns back into the upstream tree.

## File Ownership

- `docs/`: planning, architecture, drift tracking, validation
- `vendor/`: copied upstream source
- `patches/`: patches against vendored copies
- `tools/`: extraction and sync scripts
- `runtime/core/`: standalone native/WASM simulation runtime
- `runtime/sdk/`: JS or TS SDK
- `runtime/ui/`: HTML + JavaScript simulation frontend
- `runtime/opfs/`: browser persistence layer
- `tests/`: standalone native and browser regression coverage

## Validation Requirements

Every migrated feature should be validated against LinuxCNC-native behavior
using one or more of:

- existing LinuxCNC tests;
- extracted native harness tests;
- WASM regression tests;
- browser smoke tests.

Validation should cover:

- path output;
- machine/controller state;
- parameter and variable behavior;
- kinematic transforms;
- file/config loading.

## Non-Goals

This project must not:

- attempt realtime hardware control;
- port LinuxCNC drivers to the browser;
- recreate LinuxCNC's native process topology;
- rewrite major CNC semantics in JavaScript if LinuxCNC source can be reused;
- depend on LinuxCNC native GUI code as implementation code.

## Working Style

When extending this workspace:

1. Update docs before or alongside structural changes.
2. Keep extraction and patching reproducible.
3. Keep adapters narrow and explicit.
4. Keep LinuxCNC-derived logic traceable to its upstream file origin.