git:20261009.46298b0 to git:20261021.2153b76

# AGENTS.md

This file provides guidance to Codex and other coding agents when working in

this repository. Treat `CLAUDE.md` as the upstream source of truth; this file is

the Codex-compatible mirror of those project rules.

## Multi-IDE Rules

This repo is developed across multiple AI-assisted environments. The following

rules apply to all code changes:

1. **Update docs on code change** - When changing behavior, architecture, or

APIs, update both the English and Vietnamese docs. Keep numbers, flows,

endpoints, and states accurate with the code. Platform docs are in `docs/`;

lamp-specific docs are in `robots/lamp/docs/`.

**Platform docs** (`docs/` + `docs/vi/`):

| Code area | English doc | Vietnamese doc |

|-----------|-------------|----------------|

| os-server, API, startup | `docs/os-server.md` | `docs/vi/os-server_vi.md` |

| Setup flow, provisioning | `docs/setup-flow.md` | `docs/vi/setup-flow_vi.md` |

| Web UI, configuration pages | `docs/web-ui.md` | `docs/vi/web-ui_vi.md` |

| Flow Monitor (turn pipeline, JSONL, SSE) | `docs/flow-monitor.md` | `docs/vi/flow-monitor_vi.md` |

| Overall structure | `docs/overview.md` | `docs/vi/overview_vi.md` |

| MQTT, dispatch, publish | `docs/mqtt.md` | `docs/vi/mqtt_vi.md` |

| OTA, bootstrap | `docs/bootstrap-ota.md` | `docs/vi/bootstrap-ota.md` |

| Speech emotion recognition (SER) | `docs/speech-emotion.md` | `docs/vi/speech-emotion_vi.md` |

| Realtime voice agent (HAL `realtime`, Gemini Live / OpenAI Realtime, delegate) | `docs/realtime-voice.md` | `docs/vi/realtime-voice_vi.md` |

| Perception service (cloud DL inference), load balancer, encryption, models | `docs/perception-service.md` | `docs/vi/perception-service_vi.md` |

| Hermes agent backend (`agent_runtime`, runtimes/hermes) | `docs/agentic/hermes.md` | `docs/vi/agentic/hermes_vi.md` |

| PicoClaw agent backend (`agent_runtime`, runtimes/picoclaw, WebSocket) | `docs/agentic/picoclaw.md` | `docs/vi/agentic/picoclaw_vi.md` |

| Adding/changing an agentic backend (AgentGateway contract, switch, install/presync, migration, skills, hooks, reset) | `docs/agentic/adding-agent-runtime.md` | `docs/vi/agentic/adding-agent-runtime_vi.md` |

| Safety engine (SAFETY.md bounds, deterministic enforcement gate) | `docs/safety.md` | `docs/vi/safety_vi.md` |

| Device telemetry (adding a tracker, `hal/telemetry`, `system/telemetry`, `/api/telemetry/event`) | `docs/telemetry.md` | `docs/vi/telemetry_vi.md` |

| Voice response metrics (`hal/telemetry`, `system/telemetry`, `/api/telemetry/event`) | `docs/voice-metrics.md` | `docs/vi/voice-metrics_vi.md` |

**Lamp-specific docs** (`robots/lamp/docs/` + `robots/lamp/docs/vi/`):

| Code area | English doc | Vietnamese doc |

|-----------|-------------|----------------|

| LED, effects, states, animations | `robots/lamp/docs/led-control.md` | `robots/lamp/docs/vi/led-control_vi.md` |

| Sensing behavior, sound escalation, reactions | `robots/lamp/docs/sensing-behavior.md` | `robots/lamp/docs/vi/sensing-behavior_vi.md` |

| Sensing threshold tuning | `robots/lamp/docs/sensing-tuning.md` | `robots/lamp/docs/vi/sensing-tuning_vi.md` |

| Habit tracking, pattern building, habit-aware nudge phrasing | `robots/lamp/docs/habit-tracking.md` | `robots/lamp/docs/vi/habit-tracking_vi.md` |

| Vision tracking, object follow, servo track | `robots/lamp/docs/vision-tracking.md` | `robots/lamp/docs/vi/vision-tracking_vi.md` |

| Physical controls (GPIO button, TTP223 touchpad, gestures, pet response) | `robots/lamp/docs/physical-controls.md` | `robots/lamp/docs/vi/physical-controls_vi.md` |

| Autonomous Buddy (Mac companion app) | `integrations/companions/autonomous-buddy/docs/autonomous-buddy.md`, `integrations/companions/autonomous-buddy/docs/autonomous-buddy-mvp.md`, `integrations/companions/autonomous-buddy/docs/release-signing.md` | `integrations/companions/autonomous-buddy/docs/vi/autonomous-buddy_vi.md`, `integrations/companions/autonomous-buddy/docs/vi/autonomous-buddy-mvp_vi.md`, `integrations/companions/autonomous-buddy/docs/vi/release-signing_vi.md` |

| Security test checklist | `robots/lamp/docs/security-test.md` | _(no vi version)_ |

2. **Comments in English** - Project standard.

3. **Code is the single source of truth** - Docs reflect code, not the other

way around.

4. **Do not commit binary artifacts** - Version is injected via ldflags at

build time.

5. **Web/TSX lint is a required quality gate** - For every change under

`system/web/`, work freely on the implementation but finish with both

`npm run lint` and `npm run build` from `system/web/`. Do not hand off a

change with ESLint warnings or errors, TypeScript errors, or a skipped

validation command. Fix React Hook diagnostics by restructuring the code;

do not silence them with `eslint-disable` unless the exception is narrowly

scoped, documented in English with why it is safe, and has no practical

compliant alternative. Report the exact commands run and any limitation.

6. **Go validation must follow CI order** - For Go changes, run from the repo

root, sequentially: `go build ./...`, then `go vet ./...`, then

`go test ./...`. Fix a failed stage before advancing to the next. The vet

checks run implicitly by `go test` are only a subset and do not replace

the explicit `go vet ./...` gate. For concurrency changes, also run

`go test -race` on the affected packages. Complete these checks before

reporting the change ready to commit or push; report exact commands and

any failures or skipped checks. Device tests do not replace local gates.

7. **Design and verify latency when implementing features** - Treat response

time as part of functional correctness, especially for touch, buttons, voice,

and other direct interactions. Before implementation, identify the path from

user action to feedback and readiness, set a concrete latency target, and

inspect blocking I/O, network calls, polling, debounce, and cold initialization.

Keep immediate feedback and input handling independent of slow work where

possible, without signaling readiness before the system can accept input.

When adding asynchronous work, preserve ordering, cancellation, and bounded

resource usage. Before declaring an interactive feature complete, measure

latency as well as functional behavior: cover first use, repeated actions,

and slow dependencies on the target hardware when authorized. For latency

fixes, report comparable before/after measurements, their exact boundaries,

and any unverified device or end-to-end behavior. Passing functional tests

alone does not demonstrate responsive UX.

8. **Robot behavior must read as a living thing, not a machine** - Before

shipping any autonomous motion, sound, light, or speech, ask: does the lamp

act like a human, or like a living thing? Would a person or a pet do this

here? Judge what the user sees, not whether the algorithm reaches its goal.

Unprompted behavior stays small and natural: a lamp that turns to a voice

and finds nobody glances left and right and lets it go; it does not scan

the room at 18 positions like a WiFi camera. Exhaustive, mechanical

behavior is only for when the user explicitly asks for it (e.g. "look

around for my keys"). When a design passes its tests but would look odd,

awkward, or robotic to someone in the room, it is not done.

See `docs/DEV-MULTI-IDE.md` for full conventions.

## Working Style

- The user reviews and commits by hand. Do not create commits unless explicitly

asked. When asked: `git add` the exact files of that change (never `git add -A`),

check `git status --short` for unrelated dirty or untracked files and leave them

alone, then commit with a single-line message and **nothing else in it** — no

`Co-Authored-By` trailer, no "Generated with" footer, no body. Commit only; do

not push unless told to.

- Work in small, reviewable chunks. When a task spans multiple concerns, split

it by concern and verify each batch before moving to the next.

- Stay in scope. Flag unrelated issues instead of fixing them opportunistically.

- Verify with concrete evidence such as focused tests, builds, greps, `bash -n`,

or compile checks. Report what was and was not verified.

- Do not "clean up" inherited drift such as unrelated gofmt churn, duplicate

dependency metadata, or upstream-preserved style unless it is required for the

task.

- Do not auto-deploy to devices. Default to repo changes plus local verification;

any on-device SSH/SCP/restart step is opt-in and must be confirmed first.

### Waiting for tools and background jobs

**Avoid model turns that only ask whether a job has finished.**

- Follow the active tool's completion contract. If it explicitly delivers the

result automatically, do independent work or use its supported yield/wait

mechanism. End a turn to await delivery only when the tool explicitly

guarantees that it will resume the task; never assume a wakeup.

- Do not use shell `sleep` loops, repeated `ps` / `pgrep` / `top`, or repeated

log/status reads to wait for a job that already has a completion mechanism.

Targeted process/log inspection is still appropriate to diagnose a failure

or a suspected stall.

- Retain the returned handle and use its matching continuation tool. In Codex,

an `exec_command` session ID uses `write_stdin`; a yielded `functions.exec`

cell ID uses `functions.wait`. For agents/tasks, use the available native

wait tool and preserve any returned cursor. These handles are not

interchangeable, and receiving one does not mean the job succeeded.

- For a long-running job, use a bounded wait suited to its expected duration

(normally 30-60 seconds, within the active tool and communication limits).

Avoid repeated zero/short-timeout checks; read only new output and report

meaningful progress instead of narrating unchanged status.

- When an external job has no notification or native wait support, use a

bounded watcher or read-only polling with backoff and an overall deadline.

Do not rerun the original operation just to obtain its status.

- Inspect the final output and exit code or terminal status before claiming

completion. A timeout, background handle, or quiet log is not success.

This governs coding-agent orchestration. It does not remove application/API

polling, test synchronization, or service-readiness checks required by their

own contracts.

## Parallel Work / Subagents

When work can be split across independent, file-scoped tasks, use available

parallelism instead of doing everything sequentially. In Codex, prefer

`multi_tool_use.parallel` for independent local reads/checks, and use subagents

only when the tool is available and the overhead is justified.

Common cases in this repo:

- Repetitive edits across many files, such as rebranding strings across EN + VI

docs: split by file or language, with exact rules and a verification grep.

- Long-running builds or cross-compile checks, such as `swift build` or

`GOOS=linux GOARCH=arm64 go build`: run in parallel/background when possible

and continue with independent work.

- Repo-wide audits, such as stale paths after folder moves or broken cross-refs:

use audit-only scope unless edits are explicitly part of the task.

- Independent English and Vietnamese doc updates after a code change: keep both

sides consistent and verify matching numbers, endpoints, states, and flows.

Rules:

- Brief any delegated worker with goal, context, exact files/scope, verification

step, and concise report format.

- Do not delegate when the overhead is larger than the work itself, especially

for one or two quick edits in files already open.

- Trust but verify: spot-check actual diffs and run focused greps/tests before

considering delegated work done.

## Device Access Rules

- Always ask the user before running any `sshpass` or `ssh` command to the Pi.

Do not SSH automatically.

- Pi SSH: `ssh pi@<IP>` (credentials stored in the team password manager; IP

varies per session).

## Harness integration context

Before changing `skills/harness-use`, `system/harness` or the OS Harness UI/API, read

[the integration context and ownership](docs/harness.md) and its

[Vietnamese counterpart](docs/vi/harness_vi.md). Harness app/device support is

maintained by a separate team in `autonomous-harness` and

`autonomous-harness-desktop`. This repo owns the OS client and skill only; keep

implementation edits here. Verify cross-repository contract changes against the

Harness team's current code and coordinate them rather than inventing another

pairing flow, transport or credential. Buddy stays independent.

## Project Overview

Autonomous is an open-source OS for physical AI agents. The Go backend

(`system`) provides device onboarding (WiFi, LLM provider, messaging

channel setup), OTA updates, and agent gateway integration. The brain is a

swappable agentic runtime (OpenClaw, Hermes, or any LLM + skills + memory).

**Go module:** `go.autonomous.ai/os` (rooted at repo root — covers `system/` and `runtimes/`) | **Go 1.24** | **Target:** Linux ARM64

## Build & Development Commands

All targets run from the repo root via the top-level `Makefile`.

```bash

# Build Go services (cross-compiles to linux/arm64)

make os-build # Builds os-server binary

make os-build-bootstrap # Builds bootstrap-server binary

# Code generation (Google Wire DI)

make os-generate # Runs from repo root: GOFLAGS=-mod=mod go generate ./...

# Lint + tests (Go)

make os-lint # golangci-lint run (repo root, covers runtimes/)

make os-test # go test ./... (repo root, covers runtimes/)

# HAL (Python hardware runtime, hal)

make hal-dev # Install deps + run HAL locally

make hal-lint # Catch broken local imports + undefined names

make hal-test # Run HAL tests

# Web frontend (React/Vite/Tailwind in system/web)

make web-install # npm install

make web-dev # Vite dev server

make web-build # Production build to dist/

cd system/web && npm run lint # Required after every web/TSX change

cd system/web && npm run build # Required type-check + production build

```

Go version is injected at build time via ldflags. HAL/web versions live in

`system/VERSION_OS_SERVER` and `hal/VERSION_HAL` and are auto-bumped by the

`make upload-*` release targets — do not hand-edit for releases.

## Architecture

### Two Executables

- `system/cmd/os-server/main.go` - Main HTTP API server (Gin). Handles device

setup, network management, LED control, health checks, and agent gateway

integration.

- `system/cmd/bootstrap/main.go` - OTA bootstrap worker. Periodically

checks for and applies updates.

### Dependency Injection

Uses Google Wire for compile-time DI. After changing provider signatures, run

`make os-generate` to regenerate `wire_gen.go` files.

### Package Layout

**Agentic runtimes - `runtimes/` (repo root):** swappable backends,

one folder per brain: `runtimes/{openclaw,hermes,picoclaw,codex,claudecode}`.

Selected by `system/agent` (AgentGateway factory).

**Go backend - `system/` (single Go module rooted at the repo root):**

- `system/<domain>/` - System managers, one folder per diagram chip (ambient,

beclient, buddy, device, healthwatch, intent, monitor, network, skills,

statusled, vision) plus `system/agent/` (AgentGateway factory + migration).

- `system/server/` - HTTP layer: Gin router, handlers by domain

(`delivery/http/handler.go` convention); `server/serializers/`,

`server/config/`.

- `system/bootstrap/` - OTA worker: metadata fetching, update execution,

state persistence.

- `system/domain/` - Shared data structures.

- `system/lib/` - Shared libraries (mqtt, core/system, i18n, logger, hal HAL

client, safego, ...).

- `system/web/` - React 19 + TypeScript + Vite + Tailwind CSS 4 SPA.

**HAL - `hal/` (Python hardware runtime, FastAPI on :5001):**

- `drivers/` - Hardware drivers by subsystem (rgb, motors, voice, sensing,

display, gpio_button, ...).

- `board/` - Per-board profiles (pin maps, debounce).

- `routes/` - FastAPI route modules (servo, led, camera, audio, emotion, ...).

**OS-level dirs (repo root):** `skills/` (agent skills), `robots/` (per-device

declarations + docs; `robots/contract/` device specs, `robots/contract/cts/`

compliance tests), `scripts/imager/` (OrangePi image build), `scripts/` (setup +

OTA upload), `integrations/perception-service/`, `integrations/companions/`.

### API Response Format

All HTTP endpoints return:

```json

{"status": 1, "data": {}, "message": null}

```

on success, and:

```json

{"status": 0, "data": null, "message": "error"}

```

on failure.

### Configuration

Config lives in `config/config.json` (path relative to the os-server working

dir) and is managed by `system/server/config/config.go`. It supports a

notification channel for config change propagation.

## Coding Standards

### Error Handling

```go

if err != nil {

return fmt.Errorf("operation: %w", err)

}

```

Always wrap errors with useful context.

### Logging

```go

log.Println("[component] message")

log.Printf("[component] formatted %v", value)

```

### Goroutines

Always use `context.Context` for cancellation. Background goroutines must

respect `ctx.Done()`.

### Validation

Use `go-playground/validator` for struct validation. Validate at the HTTP

handler level before passing data to services.

### Naming (paths under `system/`)

- Handlers: `server/<domain>/delivery/http/handler.go`

- Services: `<domain>/service.go` (system managers live at `system/<domain>/`, e.g. `ambient/service.go`)

- Wire providers: `server/wire.go`, `bootstrap/wire.go`

- Domain types: `domain/<type>.go`