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/.

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.