docs

The canonical spec is stack.md. Every primitive named there is backed by a file path in the repo — if a word isn't, that's a bug in the doc.

stack.md

— snappy-os, the full stack, named honestly
  1. §1 The atom: one skill — four on-disk parts — Skill, api.ts, scripts, Loader
  2. §2 The cross-cutting parts — hooks per runtime, regen footer, sessionId() — same across every skill
  3. §3 Feedback ledgers — evals.ndjson and agents-md-feedback.log — the write side of the PID loop
  4. §4 The PID loop: three honest modes — [FIXED] inline, [LOGGED] to drain queue, drain-on-Stop
  5. §5 Actor ≠ auditor, enforced — sessionId() guarantees the grader is a different process
  6. §6 The lint suite — state/lint/check.ts is the master; 40+ scripts; shape enforcement via --publish
  7. §7 Sync: two layers, bidirectional — git for code + gateway via bin/cli.js push --auto for runtime artifacts
  8. §8 Recipes and engagement — named verb chains; engagement is a file (state/engaged.json), not a flag
  9. §9 Cron: two classes — Class A banned; Class B allowed only with actor ≠ auditor
  10. §10 Environment and credentials — .env.cache at repo root is canonical; the skills-dir path is a back-compat symlink
  11. §11 Seed-owned vs user-owned — what ships from the seed repo vs what each install accumulates locally
  12. §12 Distribution: Option A / Option B — Option A = full tree; Option B = plain skills only; never "plugin"
  13. §13 Index of every named file — canonical roster of files referenced above — grep here before inventing a name
  14. §14 What is NOT in the system — the taxonomy words retired — do not reintroduce "core," "runner," "plugin," "starter"

Operations

All wiki pages

42 files under state/wiki/. Curated entries above are duplicated in this list.