chore: add curated Claude knowledge base and un-ignore it#3210
Open
vpetersson wants to merge 2 commits into
Open
chore: add curated Claude knowledge base and un-ignore it#3210vpetersson wants to merge 2 commits into
vpetersson wants to merge 2 commits into
Conversation
- Add force-tracked .claude/skills/ (testbed-qa, anthias-hardware, anthias-viewer, anthias-release) + seed .claude/MEMORY.md, distilled and PII-scrubbed from a retiring agent VM's local memory - Refresh CLAUDE.md: correct the stale layout (src/ tree, server-rendered Django + Alpine/htmx, not React) and add a Working conventions section - Replace the blanket .claude/ ignore with .claude/* + negations so the knowledge base tracks without -f while worktrees and unfiltered local memory stay ignored; keep common worktree folders excluded - Docker images still exclude .claude via .dockerignore Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Step-by-step release procedure: bump CalVer across package.json, pyproject.toml and uv.lock (semver form), merge, wait for the master Docker build, tag, publish - Publish flow uses GitHub auto-generated notes first, then a curated summary layered on top - Index it in .claude/MEMORY.md and CLAUDE.md; anthias-release stays the reference, cut-release is the runbook Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
There was a problem hiding this comment.
Pull request overview
This PR adds a curated, PII-scrubbed Claude knowledge base to the repository and updates repo guidance so fresh clones pick up the preserved operational/runbook context, while keeping non-curated local agent state ignored.
Changes:
- Add
.claude/MEMORY.mdplus several.claude/skills/*/SKILL.mdrunbooks (QA, hardware, viewer internals, release ops, and release cutting). - Refresh
CLAUDE.mdto match the currentsrc/layout and the server-rendered Django + Alpine.js/htmx UI architecture. - Update
.gitignoreto ignore.claude/*by default while explicitly tracking the curated knowledge base files.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
CLAUDE.md |
Updates architecture + directory layout docs; adds “Project knowledge base” and “Working conventions”. |
.gitignore |
Changes .claude/ ignore strategy to track curated knowledge while ignoring local worktrees/caches. |
.claude/MEMORY.md |
Adds a top-level index/map into the committed skills and key cross-cutting facts. |
.claude/skills/testbed-qa/SKILL.md |
Adds a physical testbed QA runbook and operational validation guidance. |
.claude/skills/cut-release/SKILL.md |
Adds a step-by-step release cutting runbook (CalVer bump + GH release sequencing). |
.claude/skills/anthias-viewer/SKILL.md |
Adds viewer/server architecture notes and known bug/fix mechanisms. |
.claude/skills/anthias-release/SKILL.md |
Adds release/CI/balena/Sentry operational knowledge and pitfalls. |
.claude/skills/anthias-hardware/SKILL.md |
Adds per-board display/codec/rotation/audio operational knowledge. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Project knowledge base | ||
|
|
||
| Deep, hard-won operational and hardware knowledge distilled from long-running debugging lives in force-added skills under `.claude/skills/` (auto-discovered on clone) — start at `.claude/MEMORY.md`: |
Comment on lines
+9
to
+13
| > `.claude/` is gitignored (it normally holds per-checkout worktrees and | ||
| > unfiltered local memory). These handoff files are the deliberate, force-added | ||
| > (`git add -f`) exceptions — same pattern as `.claude/skills/commit` and | ||
| > `create-pr`. Keep them scrubbed: **this is a public repo — never add IPs, | ||
| > usernames, emails, device UUIDs, tokens, ngrok URLs, or forum handles.** |
| ## Viewer memory / OOM behavior | ||
|
|
||
| - **Viewer stdout accumulation (issue #3138, fixed #3147, 2026-07-08).** `src/anthias_viewer/__init__.py` spawns `AnthiasViewer` via `sh.Command(...)(_bg=True, _err_to_out=True, ...)` with **no `_out` sink**. sh (2.3.0) accumulates the subprocess's entire merged stdout+stderr in viewer-process RAM for the whole session. Chatty decoder spam (e.g. ffmpeg AAC `channel element 0.0 duplicate` per frame) → unbounded RSS growth → swap thrash on 2 GB → multi-minute blank. Fix: a bounded `_BoundedWebviewOutput` as `_out` keeping the last 64 KiB (a **deque of chunks**, not `buf += chunk` reslice). Measured: OLD +76 MB RSS for 12 MB of spam; NEW +0.5 MB. | ||
| - **#3147 is NOT the fix for web-page OOM (forum #6731).** On a real 1 GB Pi3B+ (787 MB total, **no swap**) cycling web pages, `AnthiasViewer` emits ~304 KB one-time Qt startup dump then **~0 B/s**. The stdout leak needs *continuous* chatty stderr; bounding it changes nothing for web-page workloads. **Real pressure = Qt6 QtWebEngine footprint on a tiny board** — a 64-bit Pi3 OS now lands on the heavier Qt6 `pi3-64` stream (#2985, gated on userspace arch by #3076). **Fix #3178:** force Chromium's low-memory profile, gated on measured RAM via `is_low_ram_device()` (NOT board/DEVICE_TYPE — a 1 GB Pi5 exists). Prepend to `QTWEBENGINE_CHROMIUM_FLAGS`: `--enable-low-end-device-mode --js-flags=--max-old-space-size=64 --renderer-process-limit=1 --process-per-site --disable-dev-shm-usage`. HW-validated: Pi3B+ RSS 225→147 MB. Reverting Qt6→Qt5 is not an option. |
| - **Operator input validation leaking into Sentry as ERROR** (ANTHIAS-3D, `AuthSettingsError: New passwords do not match!`). Both settings-save surfaces caught it under broad `except Exception` + `logger.exception(...)`. Sentry's LoggingIntegration turns any ERROR-level log record into an event, so a password typo paged the team. **Fix #3068:** catch `AuthSettingsError` (a `ValueError` subclass with curated operator text) ahead of the generic handler; log at **warning** (no traceback → never a Sentry event) — the WARNING change is what actually stops the event; add to `_sentry_before_send`'s drop list as a backstop. **General rule: for input-validation Sentry noise, log at warning AND add to `before_send`.** | ||
| - **Celery 30 s hard-limit SIGKILL trio** (ANTHIAS-A / -9 / -B) are ONE incident fanned into three groups (9 and B carry no task identity). #3017 added `soft_time_limit` only to the asset-probe path, leaving `get_display_power` and `send_telemetry_task` with bare `time_limit=30`. Root cause for telemetry: `requests_post(timeout=5)` bounds connect+read but NOT `getaddrinfo` — a wedged resolver hangs DNS past 30 s → SIGKILL. **Fixed #3063 / #3180:** `soft_time_limit=30`/`time_limit=60` + `SoftTimeLimitExceeded` catch on every periodic task; display_power/telemetry-cooldown keys use a single `SET ... ex=` so a soft-limit signal can't strand them without a TTL. | ||
|
|
||
| ## Remote media (self-signed HTTPS + preview) — forum #6726 |
|
|
||
| ## Pi 2 blank / Qt5 armhf toolchain (release blocker) — RESOLVED | ||
|
|
||
| - **Pi 2 (and 32-bit Pi 3/armhf) blanks: deterministic ARMv7 alignment SIGBUS inside libQt5WebEngineCore (forum #6732).** AnthiasViewer handshakes on D-Bus then SIGBUSes post-handshake: `Alignment trap ... f9400adf`. A 64-bit NEON doubleword store (`vst1.8 {q8},[rN:64]`) stamped `:64` alignment lands on a 4-byte-aligned Chromium address; Cortex-A7 faults, kernel can't fix up NEON → SIGBUS. 100% deterministic even with empty playlist. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issues Fixed
Not associated with a tracked issue. This preserves hard-won engineering knowledge from a retiring agent VM before its local memory is lost, and moves it into the repo so a fresh clone picks it up.
Description
Distills a long-running agent's local memory (127 notes) into a curated, PII-scrubbed knowledge base that ships with the repo.
.claude/skills/(testbed-qa,anthias-hardware,anthias-viewer,anthias-release) and a seed.claude/MEMORY.mdmapping them. Skills auto-discover on clone.CLAUDE.md: corrects the stale layout (everything moved undersrc/; the UI is server-rendered Django + Alpine.js/htmx, not React/Redux) and adds a Working conventions section..claude/gitignore with.claude/*+ negations, so the knowledge base tracks without a forced add while git worktrees and unfiltered local memory stay ignored. Common worktree folders remain excluded..claude/is still excluded from Docker images via.dockerignore, so device images are unchanged.All notes were scrubbed of IP addresses, usernames, emails, device UUIDs, tokens, tunnel URLs, and forum handles before inclusion (public repo).
Checklist
🤖 Generated with Claude Code