b32d316023
- SCHEMA.md: full specification for index.json and YAML knowledge files - knowledge/global/pitfalls.yaml: 8 cross-repo pitfalls - knowledge/global/tool-quirks.yaml: 7 environment quirk facts - knowledge/repos/hermes-agent.yaml: 8 per-repo pitfalls (cron, paths, SSH) - knowledge/repos/the-nexus.yaml: 6 per-repo pitfalls (merge, server, deploy) - scripts/validate_knowledge.py: schema validator (29 facts, all passing) - knowledge/index.json: populated with 29 seed facts from real fleet data Design decisions: - YAML for humans, index.json for machines - ID format: domain:category:sequence for dedup and linking - 5 categories: fact, pitfall, pattern, tool-quirk, question - Confidence 0.0-1.0 with defined ranges - Related facts by ID for graph traversal - Tags for searchability - Source count + dates for decay/expiry Acceptance criteria: - [x] Directory structure created - [x] Schema documented (SCHEMA.md) - [x] index.json with real facts (29 total) - [x] Example knowledge files for 2 repos (hermes-agent, the-nexus) - [x] Validation script passes
64 lines
1.7 KiB
YAML
64 lines
1.7 KiB
YAML
---
|
|
domain: the-nexus
|
|
category: pitfall
|
|
version: 1
|
|
last_updated: "2026-04-13"
|
|
---
|
|
|
|
# Pitfalls (the-nexus)
|
|
|
|
## Git & Merging
|
|
|
|
- id: the-nexus:pitfall:001
|
|
fact: "Merges fail with HTTP 405 due to branch protection - must use merge API with 1 approval"
|
|
confidence: 0.95
|
|
tags: [git, merge, branch-protection, gitea]
|
|
source_count: 12
|
|
first_seen: "2026-04-05"
|
|
last_confirmed: "2026-04-13"
|
|
related: [global:pitfall:001]
|
|
|
|
- id: the-nexus:pitfall:002
|
|
fact: "ThreadingHTTPServer required for multi-user bridge - standard HTTPServer blocks on concurrent requests"
|
|
confidence: 0.95
|
|
tags: [server, concurrency, bridge]
|
|
source_count: 5
|
|
first_seen: "2026-04-10"
|
|
last_confirmed: "2026-04-13"
|
|
|
|
- id: the-nexus:pitfall:003
|
|
fact: "ChatLog.log() crashes on message persistence when index.html has orphaned button tags"
|
|
confidence: 0.9
|
|
tags: [html, crash, chatlog]
|
|
source_count: 3
|
|
first_seen: "2026-04-12"
|
|
last_confirmed: "2026-04-13"
|
|
|
|
## Three.js & Performance
|
|
|
|
- id: the-nexus:pitfall:004
|
|
fact: "Three.js LOD not implemented - local hardware struggles with full scene without texture optimization"
|
|
confidence: 0.85
|
|
tags: [threejs, performance, lod]
|
|
source_count: 4
|
|
first_seen: "2026-04-09"
|
|
last_confirmed: "2026-04-13"
|
|
|
|
- id: the-nexus:pitfall:005
|
|
fact: "Duplicate content blocks appear in index.html when PR merges conflict silently"
|
|
confidence: 0.8
|
|
tags: [html, merge-conflict, duplicate]
|
|
source_count: 3
|
|
first_seen: "2026-04-11"
|
|
last_confirmed: "2026-04-13"
|
|
|
|
## Deployment
|
|
|
|
- id: the-nexus:pitfall:006
|
|
fact: "Unified HTTP + WebSocket server required for proper URL deployment - separate servers break CORS"
|
|
confidence: 0.9
|
|
tags: [deploy, websocket, http, cors]
|
|
source_count: 4
|
|
first_seen: "2026-04-10"
|
|
last_confirmed: "2026-04-13"
|