aboutsummaryrefslogtreecommitdiffstats
path: root/AGENTS.md
diff options
context:
space:
mode:
authorDanilo M. <danix@danix.xyz>2026-11-16 13:29:32 +0100
committerDanilo M. <danix@danix.xyz>2026-11-16 13:29:32 +0100
commit63c676e60b21334a2d21329b0d409da7908ba560 (patch)
treebafe15dcaae86c637e65cc85f5995749ed3774ac /AGENTS.md
parentff52144a55d994c642930df3378bcdb7f299e98f (diff)
downloadagent-lamp-63c676e60b21334a2d21329b0d409da7908ba560.tar.gz
agent-lamp-63c676e60b21334a2d21329b0d409da7908ba560.zip
docs: wiring and runtime notesHEADmaster
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat (limited to 'AGENTS.md')
-rw-r--r--AGENTS.md17
1 files changed, 17 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
index 3eada0c..70fde0f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,23 @@ longer follows the wallpaper accent.
- Pairing trades the security code on the gateway label for an identity and
key, stored in `~/.config/agent-lamp/tradfri.json` (mode 0600).
+## Runtime
+
+- State: `$XDG_RUNTIME_DIR/agent-lamp/state.json`, every read-modify-write
+ under `flock` on `state.lock`. One renderer (`--run`) at a time holds
+ `run.lock`; a second exits at once. The renderer drops `run.lock` under
+ the state lock when it decides to exit, and writers spawn only after
+ releasing the state lock, so no event is lost. Spawns happen only when
+ the state changed.
+- A colour is never sent while a brightness fade runs (`level_at`): the
+ gateway would drop it.
+- `coap-client` exits 0 on a 4.xx/5.xx response and prints the code on
+ stderr only; `coap()` treats that as failure.
+- Install is a symlink, `~/bin/agent-lamp`, so edits are live; a running
+ renderer keeps the old code until it exits.
+- Known limit: opencode's notifier has no "permission granted" event, so an
+ opencode permission stays purple until that session's next event.
+
## Conventions
- Unknown state words exit 0 silently: hook callers must never break.