NODEDC_MISSION_CORE/AGENTS.md

# Repository operating rules

NODEDC MISSION CORE is a vendor-neutral mission-control monorepo. Its first
real device plugin investigates an owner-controlled XGRIDS/LixelKity K1 as a
black-box sensor. Preserve the device, the host, the working LAN, raw evidence,
and the boundary between Mission Core and vendor-specific integration code.

## Non-negotiable safety boundaries

- Default to non-mutating discovery or read-only operations. CoreBluetooth BLE
  scanning on macOS is active discovery, not passive radio sniffing.
- Do not send BLE writes until the exact service, characteristic, framing,
  payload semantics, rollback, and expected state transition are documented.
- BLE notification subscription may perform the standard temporary CCCD write;
  disclose it explicitly and do not conflate it with provisioning writes.
- Do not fuzz, brute-force, upload firmware, delete device files, guess SSH/ADB
  credentials, or probe unrelated LAN devices.
- Network probes must target the confirmed K1 IP. A full home-subnet scan is
  not a default operation.
- Never place a Wi-Fi password in CLI arguments, logs, manifests, source, test
  fixtures, or Git history.
- Do not install Python packages globally. Use the repository-local `.venv`
  managed by `uv`.
- Do not install or alter Homebrew/system components unless the user explicitly
  authorizes that concrete change.

## Local operator resource envelope

- The local operator machine is a 14-inch 2023 MacBook Pro with only 18 GB of
  physical memory. Treat local memory and swap as a hard shared operational
  limit, not as disposable build capacity.
- Run frontend tests, production builds, Docker builds, runtime startup, and
  browser QA sequentially. Do not launch parallel heavy local jobs.
- Do not start Docker Desktop, a Compose stack, a second browser automation
  session, or a full test/build pass merely for convenience. First prove that
  the operation is necessary, prefer the narrowest focused check, and keep no
  more than one memory-intensive validation job active at a time.
- Do not run load or stress tests on the Mac. Run bounded synthetic load only on
  Worker 006, and remove every temporary process after the measurement.
- Use only the canonical Mission Core endpoint on port `8000`; do not start
  duplicate application servers to work around stale state.
- Before a memory-intensive local operation, inspect current memory pressure and
  active Docker workload. If memory pressure is elevated or swap is growing,
  stop and remove temporary jobs before continuing. Prefer focused tests and
  existing build artifacts when they are sufficient for acceptance.
- After every local test, build, replay, browser-QA, or Docker operation, stop
  temporary workers, watchers, replay publishers, duplicate viewers, and
  containers that are not durable operator state. Keep only the canonical
  Mission Core service on `8000` and explicitly required operator services.
- Docker Desktop's configured VM ceiling is not evidence that the host can
  safely supply that memory. Do not change Docker Desktop CPU or memory limits
  without explicit owner approval.

## Evidence rules

- Reference inputs under `docs/reference/` are immutable; write corrections in
  audits or ADRs.
- Every real experiment gets a session ID, UTC and monotonic timestamps, a
  redacted manifest, operator notes, and SHA-256 hashes for raw artifacts.
- Real PCAP, K1 projects, logs, images, point clouds, credentials, serials, and
  router client lists stay out of normal Git. Git LFS solves size, not secrecy.
- Synthetic or explicitly redacted fixtures may be committed under
  `tests/fixtures/`.

## Onboard environment ownership — owner requirement, 2026-09-24

- Every onboard OS change belongs to the shipped, versioned installer or the
  application's environment/device preparation workflow from the first test.
  The operator installs the build and configures it in the application; never
  require hand-written service files, USB rules, permission fixes or commands.
- This applies to all Node features, including GUI/service autostart and USB
  recovery, not just individual camera drivers. Read-only SSH inspection and
  bounded artifact-owned build staging remain allowed.
- Detect the distribution, architecture and required capabilities. Maintain
  explicit supported environment profiles; do not claim arbitrary Linux
  compatibility from a qualified Ubuntu build. Preserve foreign configuration,
  report unsupported features, make preparation repeatable, and ship rollback.
- Do not add USB administration controls or port resets to inventory refresh.
  Automatic startup recovery may retry terminal enumeration failures only;
  preserve enumerated devices and active companion ports. Device identity and
  assignments must survive changes of USB port and tty number.

## Insta360 and clean-host installation — owner requirement, 2026-09-08

- The current X4 starting point is USB enumeration only. SDK installation,
  camera initialization and live video have not been accepted.
- Every Ubuntu change needed for Insta360 must execute through the shipped
  installer or the application's versioned device-preparation workflow from
  the first board experiment. Do not repair the board with an ad-hoc apt/pip
  install, copied library, chmod, environment override, service edit or root
  invocation and promise to package it later. Fix the product artifact first,
  then rerun that artifact. Read-only engineering inspection remains allowed.
- Document every relevant action and its before/after evidence in
  `docs/node/07_INSTA360_X4_INSTALLATION_LEDGER.md`; record the artifact version,
  owning installer step, dependencies, idempotency, failure behavior and rollback.
  Keep private logs/identifiers/media out of Git and redact their public summary.
- A working prepared Mini is not clean-Ubuntu acceptance. Qualify dependency
  closure on the declared clean OS image and actual USB operation separately;
  installer, preparation and GUI acceptance must use the same shipped code.
- X4 is operator live video and camera control (settings, photo, recording
  start/stop and file access), per the owner’s subsequent scope expansion.
  Preview and recording are separate operations. No stitching, AI, navigation
  or vehicle-control integration is admitted. Model support and physical device instances are separate: several
  cameras of the same model must retain independent identity and lifecycle.
- Follow the scoped implementation plan in
  `docs/node/06_INSTA360_X4_AND_MULTI_CAMERA_PLAN.md`. It is a proposed plan,
  not evidence that SDK compatibility, hardware capacity or installation passed.
- Subsequent owner direction: the existing Ubuntu Mini is the available build
  and qualification machine; do not depend on Worker 006 or another host for
  this X4 work. Its existing GCC may compile through a versioned build artifact
  in bounded temporary staging. This is a build step, not runtime installation:
  no system changes, SDK execution or camera access during compilation. The
  final installer must carry the compiled payload so a clean operator Ubuntu
  does not inherit an undeclared compiler/build-cache prerequisite. All board
  staging/build/install/test actions remain documented and artifact-owned.

## Implementation order

Follow the gates in `docs/01_IMPLEMENTATION_PLAN.md`. Do not build heavy
decoders before BLE/Wi-Fi/data-session evidence exists.

## Docker runtime governance

- Every new or migrated durable NODE.DC-owned Docker container, Compose project,
  network, named volume, and first-party image uses the lowercase `ndc-`
  namespace. The prefix is mandatory for anything that may leave a laboratory
  workstation; a legacy project/network name may survive only behind a bounded,
  documented migration barrier.
- Do not retag or rename unrelated third-party runtime owned by another product.
  Express NODE.DC ownership through the managed object name and
  `com.nodedc.product`, `com.nodedc.stack`, `com.nodedc.role`, and
  `com.nodedc.managed-by` labels.
- One operator-managed contour may be one Compose project while still using
  separate single-purpose containers. Do not merge a broker, normalizer,
  database, or application process into a multi-process container merely to
  make Docker Desktop show one row.
- Treat Compose and worker orchestration declarations as the source of truth.
  A live `docker rename` is allowed only as a bounded migration with exact
  predecessor IDs, a persisted declaration change, rollback, and post-change
  health acceptance.
- Keep bounded legacy-name fallback only for an explicit migration window.
  New defaults, UI probes, runbooks, and durable runtime names must use `ndc-`.

## Product UI governance

- For every Control Station, LAB, viewer, or product-presentation change, use
  `.codex/skills/mission-core-product-ui/SKILL.md` and follow
  `docs/17_PRODUCT_UI_AND_LAB_PRESENTATION_CANON.md` and
  `docs/18_APPLICATION_COMPONENT_ARCHITECTURE.md`.
- The integrated Control Station and API have one canonical local endpoint:
  `http://127.0.0.1:8000`. Never start a second Mission Core backend on another
  port to bypass a stale process. TCP `8765` is legacy Foxglove regression
  only, not an operator path. Restart the canonical `8000` process and finish
  with no Mission Core backend listening on `8765`.
- The canonical `8000` process is durable operator state. A completed test,
  build, browser QA pass, Codex turn, or implementation increment never
  authorizes stopping it. Every Control Station task starts by checking and, if
  necessary, starting the integrated service; every handoff verifies and leaves
  that exact service running on `8000`. A rebuild may replace it only when the
  replacement is confirmed listening before handoff.
- `NODEDC_DESIGN_GUIDELINE` is the only visual-design source of truth. Before
  editing UI, read its `registry/registry.json`, `registry/components.json`,
  `registry/icons.json`, and the relevant component documentation.
- Reuse `@nodedc/ui-react`, `@nodedc/ui-core`, tokens, icons, and page patterns.
  Do not create an application-local visual control, interaction state,
  geometry, color language, or copy of a design-system component.
- If the required visual entity is absent from the Design Guideline, stop and
  obtain explicit product-owner approval. After approval, add it to the Design
  Guideline first with registry, documentation, states, and validation; only
  then consume it here.
- Domain renderers may remain Mission Core code when they visualize Mission
  Core data. Their controls and containing surfaces must still be composed from
  canonical Design Guideline exports.
- Product UI must not expose implementation steps, roadmap gates, internal
  reason taxonomies, debug controls, placeholder status blocks, or temporary
  experiment scaffolding. Keep these in Ops, engineering reports, or developer
  tooling.
- Extend one reusable application pattern instead of adding per-LAB layouts.
  A new LAB supplies data and renderer configuration; it does not invent a new
  page hierarchy or visual language.
- Do not generalize the LAB hierarchy into a universal application template.
  For a new non-LAB interface, follow
  `docs/19_PRODUCT_SURFACE_EXTENSION_PROTOCOL.md`: identify the operator job,
  compare placement/composition alternatives, classify the novelty, and obtain
  product-owner agreement before adding a workspace, changing primary
  navigation, or introducing a new product root.
- Preserve one product grammar while allowing task-specific composition. A
  scene, map, timeline, queue, editor, topology, dashboard, and LAB review may
  have different layouts when their entity, lifecycle, or action model differs.
- Preserve the internal dependency direction:
  `core → components/renderers → workspaces → composition/App`. Core never
  imports workspaces or visual adapters; reusable components never import
  workspaces. New domains and LAB runs get their own feature module instead of
  growing `App.tsx`, `Workspaces.tsx`, or generic CSS buckets.
- Treat `productModel.ts`, executable versioned contracts, and the experimental
  vocabulary as the current local semantic sources. Do not add a parallel
  runtime ontology unless the admission conditions in
  `docs/18_APPLICATION_COMPONENT_ARCHITECTURE.md` are met.

## Laboratory presentation and reporting

- Use one fixed laboratory presentation contract: selectors, one compact
  canonical summary, admitted evidence viewer(s), result, and optional reusable
  technical details.
- Keep `missioncore.laboratory-report/v1` executable: bounded `ENNResult.tsx`
  modules supply all four `LaboratorySummary` brief fields and use
  `LaboratoryResultSummary` for metrics plus proved/not-proved/decision. They
  never own canonical summary/result markup. Anatomy changes require a new
  version and product-owner agreement.
- The compact summary must explain the decision question, immutable source,
  tested method/models/algorithms, experimental mode, principal result,
  limitations, and retained authority. It is not the engineering report.
- The complete engineering report belongs in the Mission Core Ops card as
  titled structured blocks: objective and architecture stage, source evidence,
  method/models/algorithms, worker/runtime, implementation, validation,
  results, regressions and limitations, decision, next stage, and acceptance
  checker.
- Spatial evidence uses 3D by default. Image-space reprojection may be offered
  as a 2D diagnostic mode inside the same reusable viewer. Primary evidence
  viewers must provide the canonical expand/restore action.