os

snappy-os is an agent operating substrate. Every installation — on any machine, in any runtime — is guaranteed to have the files listed here. This page is the source of truth for "what comes with it." If something appears here but isn't on your disk, your install is broken; run snappy-os pull --force.

The kernel

Two binaries ship in the npm tarball. They are the only executables a fresh machine has before the first pull:

Authoritative manifest: package.json:files — 18 paths total (the two bins plus 4 lints, 4 lib files, 2 hooks, 3 regen files, the seed manifest, README, program.md). Anything outside that array is NOT in the tarball.

Robert's local tree also has bin/cli.js, bin/do-spaces.js, and bin/wire-hooks.js — those are dogfood for the seed maintainer (push/pull against his own DO Spaces, the older hook-wire path), not part of the user-facing tarball. If you're reading this on a fresh npx snappy-os init machine, those files do not exist.

Everything beyond the seed arrives on first snappy-os pull from s3://robert-storage/snappy-os/ via https://skills.snappy.ai/_pull.

What pulls in on first install

program.md — the schema

The three-layer contract (human-owned / substrate / agent-owned), the rules (no MCP, every skill declares an eval, actor ≠ auditor), the PID loop. The agent reads this first, every loop.

state/index.md — the catalog

A walking tour of what's in the substrate right now. Agent-maintained. Points at every skill, every library, every lint.

state/lib/ — the standard library (119 files)

The utilities skills and bins import. The load-bearing ones:

• env.ts — credential loader; reads .env.cache.
• log.ts — newRunId(), append(name, row); every ndjson write goes through here.
• eval.ts — score(), pending(), friction(), fetchEvals(). The thesis metric is computed here.
• http.ts — uniform fetch with retry + error shaping.
• voice.ts — checkTone(), requireCitations(). The actor-as-auditor prevention for content.
• dispatch.ts — fires a subagent with a job file. How PID-loop rewrites happen.
• Channel libs (xano.ts, gemini.ts, openrouter.ts, browse.ts, desktop.ts, skool-fetcher.ts, whatsapp.ts, youtube.ts, image.ts, post.ts, sync.ts) — each wraps one external surface with a typed, auditable shape.

state/bin/ — graduated scripts (16 files)

Scripts that earned their way out of a skill page. These are not on PATH; they run via npx tsx state/bin/<name>.ts:

• Self-maintenance: auto-regen.sh, pid-detect.ts, pid-drain.ts, pid-aggregate.ts, commit-report.ts, sync-runtimes.ts.
• Installation / mirror: publish-bootstrap.sh, sync.sh, invite-mint.ts.
• Substrate eval infrastructure: setup-eval-endpoint.ts, provision-eval-endpoint.ts, deploy-eval-endpoint.ts, test-independence.ts.
• Spec implementation: implement-spec.ts, implement-spec-audit.ts.
• Observability: run-commit-report-gemini.ts (cross-machine commit digest).

state/lint/ — health checks (21 files)

snappy-os doctor runs every one of these. The names are the contract:

aggregate-schema, audit, check, compare, do-spaces-reachable, eval-endpoint-contract, eval-endpoint-live, eval-row-mandatory, library-shape, manifest-drift, no-github-in-product, no-kernel-refs, runtime-parity, symlink-check, sync-freshness, sync-integrity, sync-rules-coverage, sync-schema-version, three-layer-respect, worker-bundle-size, worker-serves-canonical.

Green doctor = the substrate is self-consistent. Anything else is a defect.

state/skills/ — the cookbook (97 pages at time of writing)

Prose-first skill pages. Each has ## Eval and ## Steps. Skills graduate to a script state/bin/<name>/ only after repeated identical successful runs.

state/docs/ — long-form

Reasoning pages. Architectural notes. Failure-mode post-mortems. Agent-grown.

state/log/ — ndjson trail

evals.ndjson (per-machine, ephemeral), evals.aggregate.ndjson (anonymized, synced), dogfood.ndjson (synced), changelog.ndjson (synced), sync-manifest.json (per-machine), regen-queue/ (synced briefs).

Self-maintenance

Three mechanisms keep the substrate working without a human in the loop:

1. Hooks. bin/install.js (lines 224-413) wires Claude Code Stop: [auto-regen, sync-runtimes, push --auto] and SessionStart: [pull --auto]. Codex uses SessionStart: [pull --auto, codex-session-start-context], empty UserPromptSubmit, and silent Stop: [codex-stop-hook] so context loads once per session and output does not pollute the chat. Gemini CLI + OpenClaw use a 5-min cron wrapper where native session hooks are unavailable.
2. Cron self-test. 30 */6 * * * snappy-os doctor --silent || snappy-os alert "doctor-failed" is installed by the bootstrapper. Silent success, loud failure via Worker /_alert.
3. PID loop. state/regen/enqueue.sh (PostToolUse hook on SKILL.md edits) appends slugs needing loader rewrites to state/log/regen-pending.txt. state/lint/eval-row-mandatory.ts enqueues touched-but-not-evaled slugs to state/log/eval-pending.txt. On Stop, state/hooks/snappy-os-auto-regen.sh drains both via state/regen/drain.sh, dispatching a headless Claude subprocess to consume the briefs (no foreground intervention). The wired Stop hook lives at state/hooks/snappy-os-auto-regen.sh — older state/bin/auto-regen.sh and state/bin/pid-drain.ts are bin-side helpers, not the wired path.

Expansion

The substrate expands itself by the same mechanism that maintains it — there is no separate "add a skill" path:

1. A new skill begins as prose in state/skills/<name>.md. First run logs an eval row.
2. If successive runs score consistently high, the skill graduates: a script lands in state/bin/<name>/.
3. If runs trend down or hit a P0 friction, pid-detect queues a rewrite brief. auto-regen dispatches a rewrite. The cycle repeats.
4. A rewritten skill that scores ≥0.85 across ≥5 runs on ≥3 tenants promotes from s3://robert-storage/snappy-os-staging/<skill>/<rev_id>/ to the public canonical s3://robert-storage/snappy-os/skills/<name>.md via the Worker's * * * * * scheduled handler. No manual review.
5. Every tenant's next snappy-os pull picks up the promoted skill.

This is how a substrate with one user becomes a substrate with many users whose evals collectively rewrite the substrate for everyone.

Steps

If the user asks "what does snappy-os come with," "what's the kernel," "what self-maintains," or "how does it evolve":

1. Point them at this file: state/skills/os.md.
2. If they want to verify locally, run snappy-os doctor — 21/21 green is the contract.
3. If they want to see the loop running, run npx tsx state/bin/pid-detect.ts --stats to see eval trends, and ls state/log/regen-queue/done/ to count completed rewrites.

Eval

eval: auto. Passing conditions:

• snappy-os doctor returns 21/21.
• npx tsx state/bin/pid-detect.ts --stats prints a trend table without error.
• ls state/log/regen-queue/done/ is non-empty (the loop has produced at least one rewrite).
• This file lists every lint, every graduated bin, and every top-level layer named in program.md.

A run that violates any of these logs friction() and refuses to claim pass.

Rubric

criteria:
  - name: kernel_binaries_present
    kind: deterministic
    check: "The binaries 'bin/snappy.js' and 'bin/install.js' exist in the `snappy-os` installation directory (the only two listed in `package.json:files`)."
  - name: core_docs_present
    kind: deterministic
    check: "The files 'program.md' and 'state/index.md' exist within the installation."
  - name: doctor_is_green
    kind: deterministic
    check: "Running `snappy-os doctor` returns a success exit code, indicating all health checks pass."
  - name: self_maintenance_hooks_active
    kind: judge
    check: "The system has active hooks (e.g., git hooks, cron jobs) for self-maintenance actions like `pull --auto`, `auto-regen`, and `doctor` checks."

os — loader

Per-turn rules for the os skill. Full reference: state/skills/os/SKILL.md. Do not skip these.

Critical Rules

1. Every load-bearing data flow has a heartbeat. The lint at state/lint/loop-heartbeat.ts enumerates every promise-keeping ndjson, log, and txt-queue file with an expected freshness window. If it reports a P0 leak — a missing or dry artery — the system is operating blind. P0 leaks halt the regen drain until resolved. Run npx tsx state/lint/loop-heartbeat.ts at the start of any diagnostic session. The background: controller-tuning.ndjson stopped writing on 2026-04-27 and the absence went undetected for 5 days because no lint checked freshness. This rule exists so that never happens again. The endpoint /loop-heartbeat on the head-screen server exposes the same check for the snappy-chat self-improvement card.

1. Reference / manifest skill — DO NOT "RUN THIS" from drain. os answers "what does snappy-os come with / what self-maintains / how does it evolve" by pointing at SKILL.md. There is no verb to invoke. If state/regen/drain.sh queues a "RUN THIS" brief for os, the consumer MUST writeback in the canonical drain-skip format (KIND 2 — no action_kind field): [<ISO-ts>] os: run-this skipped — kernel manifest skill, eval is snappy-os doctor + pid-detect, not safe to invoke from drain [SKIPPED]. Do NOT fabricate an eval row. Do NOT tag action_kind=skill-ran (the skill did NOT run end-to-end). Source incidents: 2026-04-27, 2026-04-28 writebacks.
2. Eval contract is deterministic, not behavioral. A pass requires ALL of: (a) snappy-os doctor exits 0 across the load-bearing lints, (b) npx tsx state/bin/pid-detect.ts --stats prints a trend table without error, (c) state/log/regen-queue/done/ is non-empty (loop produced ≥1 rewrite), (d) the SKILL.md prose lists every load-bearing lint, every graduated bin, and every layer named in program.md. Any miss → friction() and refuse pass.
3. Tarball ≠ local repo. Only the 18 paths in package.json:files ship via npm: bin/snappy.js, bin/install.js, 4 lints, 4 lib files, 2 hooks, 3 regen files, the seed manifest, README, program.md. Robert's bin/cli.js, bin/do-spaces.js, bin/wire-hooks.js are dogfood for the seed maintainer — do NOT promise them to a fresh npx snappy-os init. Everything else arrives on first snappy-os pull from s3://robert-storage/snappy-os/ via https://skills.snappy.ai/_pull.
4. Joe machines never hold DO credentials directly. The Worker is the only ingress. Pulls go through skills.snappy.ai, never S3 directly.
5. Three self-maintenance mechanisms must all be live. (a) Hooks — Claude Code Stop=[auto-regen, sync-runtimes, push --auto] + SessionStart=[pull --auto]; Codex parallel under ~/.codex/hooks.json; Gemini CLI / OpenClaw fall back to a 5-min cron wrapper. (b) Cron self-test — 30 */6 * * * snappy-os doctor --silent || snappy-os alert "doctor-failed". (c) PID loop — state/regen/enqueue.sh (PostToolUse on SKILL.md edits) → state/log/regen-pending.txt; state/lint/eval-row-mandatory.ts → state/log/eval-pending.txt; state/hooks/snappy-os-auto-regen.sh (Stop) drains both via state/regen/drain.sh, dispatching headless Claude. The wired Stop hook is state/hooks/snappy-os-auto-regen.sh — state/bin/auto-regen.sh and state/bin/pid-drain.ts (listed in state/index.md) are bin-side helpers, NOT the wired path.
6. Expansion is the same loop as maintenance. New skills enter as prose → run logs eval → high scores graduate to state/bin/<name>/ → low scores or P0 friction triggers pid-detect rewrite brief → auto-regen dispatches rewrite. Promotion to public canonical bucket happens automatically (≥0.85 / ≥5 runs / ≥3 tenants) via the Worker's * * * * * scheduled handler. There is no separate "add a skill" path.

Commands

| ui dashboard | state/skills/os/resources/ui.openui |

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/os/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Load-bearing lints (post-2026-04-20 trim): check.ts, commit-discipline.ts, do-spaces-reachable.ts, gateway-health.ts, runtime-parity.ts, sync-integrity.ts. Doctor exits 1 only when one of these fails; the 26 lints removed in the trim were substitutes for inline PID discipline or sync-meta nothing read. See KERNEL-DIFF.md.
• bin/wire-hooks.js is the older path; the wired Stop hook is state/hooks/snappy-os-auto-regen.sh. Don't re-document the older path as canonical.
• Don't list every file by name in pitfalls. That's residue from the deleted fixer-self-write loop. Replace with one-line learnings; do not preserve the manifest.

Self-Test

An agent reading this should correctly:

1. [ ] When os shows up in regen-pending or a "RUN THIS" brief, SKIP execution and emit the canonical KIND-2 [SKIPPED] writeback (NO action_kind field) — never invoke a verb, never tag action_kind=skill-ran?
2. [ ] Verify install integrity via snappy-os doctor + pid-detect --stats + ls state/log/regen-queue/done/, not by spot-checking individual files?
3. [ ] Distinguish the 2 tarball-shipped binaries (bin/snappy.js, bin/install.js) from Robert's local maintainer-only bins (cli.js, do-spaces.js, wire-hooks.js)?
4. [ ] Identify the wired Stop hook as state/hooks/snappy-os-auto-regen.sh (not the older state/bin/auto-regen.sh / pid-drain.ts helpers)?
5. [ ] Recognize that expansion = the same PID loop as maintenance (no separate "add a skill" path)?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P — proportional). MANDATORY. If this loader didn't cover your case — if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk — you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound — that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] os: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• The class token between [ts] and : MUST be the literal folder slug

(os) — producer slug, writeback class, and grade class must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind (added 2026-04-27, task #327) is the SECOND pairing predicate.

Pick what you actually did:

• shape-ok — frontmatter-shape verification only (rare from a human)
• skill-ran — skill ran end-to-end and an eval row landed

in state/log/evals.ndjson. NOTE: for os, the drain SKIPPED case (kernel-manifest skill, eval is doctor + pid-detect) is NOT skill-ran — emit the canonical [SKIPPED] writeback with no action_kind

• loader-rewritten — you EDITED this AGENTS.md inline (FIXED case),

OR the regen drain rewrote it

• pattern-elevated — promoted recurring failure to a Critical Rule
• If you LOGGED (couldn't fix inline), omit action_kind — the inferrer

picks it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.