sync-creds

The "make a new machine work" skill. snappy-os owns .env.cache at the repo root (not the kernel path - see program.md Credentials section). But that file is .gitignored because it contains secrets, so pulling the repo alone doesn't give you credentials. This skill closes that gap.

When to run this

• New machine setup: clone the repo, run this skill, every credential-using

skill works immediately.

• After rotating a key on one machine: run this on every other machine to

propagate.

• Daily on the Mac Mini: cron entry keeps the Mac Mini in sync with the

laptop without manual intervention.

Sources (pick one, documented in order of preference)

1. Tailscale + rsync (the simplest working default)

If both machines are on Tailscale and have SSH keys set up:

# On the target machine, pull from the authoritative machine:
rsync -av macbook-pro:~/projects/snappy-os/.env.cache ~/projects/snappy-os/.env.cache
chmod 600 ~/projects/snappy-os/.env.cache

This is what runs today. Requires knowing which machine is "authoritative" (the one you most recently rotated keys on).

2. 1Password CLI (the durable answer)

Once op://snappy-os/env-cache is populated:

op read "op://snappy-os/env-cache" > ~/projects/snappy-os/.env.cache
chmod 600 ~/projects/snappy-os/.env.cache

No concept of "authoritative machine" - 1Password is the source. Every machine pulls the latest. Requires one-time op signin.

3. Doppler (if you prefer a devops-style secret store)

doppler secrets download --project snappy-os --no-file > ~/projects/snappy-os/.env.cache

Steps

1. Detect source: check which source is available (1Password CLI, Doppler

CLI, Tailscale peer reachable).

1. Pull: execute the source-specific command.
2. Chmod: chmod 600 - the file contains secrets.
3. Verify: check that a critical key (e.g., ANTHROPIC_API_KEY) is present:

   grep -q "^ANTHROPIC_API_KEY=" ~/projects/snappy-os/.env.cache || echo "MISSING"

1. Log: append a row to state/log/evals.ndjson with the source used and

the key count.

Eval

score("sync-creds", run_id, {
  score:
    verified_keys >= 10 && expected_keys.every(k => present.includes(k))
      ? 1.0
      : verified_keys > 0
        ? 0.5
        : 0.0,
  source_used,
  verified_keys,
  missing_expected: expected_keys.filter(k => !present.includes(k)),
  primary_issue:
    verified_keys === 0 ? "fetch-failed" :
    !expected_keys.every(k => present.includes(k)) ? "key-missing" :
    null,
});

Expected keys (baseline for any machine running snappy-os):

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GEMINI_API_KEY
• OPENROUTER_API_KEY
• SNAPPY_MASTER_KEY
• LINKEDIN_CLIENT_ID
• DO_SPACES_KEY

Hard rules

• Never commit .env.cache to git. The repo's .gitignore blocks it.
• Never log the actual credential values - only their names and presence.
• Always chmod 600 after writing.
• If the source is 1Password or Doppler, never cache the decrypted content

anywhere other than ~/projects/snappy-os/.env.cache.

Bootstrap on a fresh machine

git clone github.com/snappyai/snappy-os ~/projects/snappy-os
cd ~/projects/snappy-os
npm install -g snappy-skills
snappy-skills install

# Wire the PID self-improvement loop into the machine's Stop hook so skills
# regenerate automatically when eval trends drop:
mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/auto-regen-skills.sh <<'HOOK'
#!/usr/bin/env bash
set -euo pipefail
SNAPPY_OS="${HOME}/projects/snappy-os"
[ -x "$SNAPPY_OS/state/bin/auto-regen.sh" ] && "$SNAPPY_OS/state/bin/auto-regen.sh" || true
exit 0
HOOK
chmod +x ~/.claude/hooks/auto-regen-skills.sh

# Now run this skill:
# (from Claude Code: "skill: sync-creds")
# (from any shell: invoke the sync-creds verb via state/lib/env.ts loader)

After those commands, the machine has: the code, the hooks, the PID loop, the credentials. Every skill works. No further setup.

Rubric

criteria:
  - name: env_cache_file_created
    kind: deterministic
    check: "The file `~/projects/snappy-os/.env.cache` exists."
  - name: env_cache_permissions
    kind: deterministic
    check: "The file `~/projects/snappy-os/.env.cache` has permissions `600`."
  - name: critical_keys_present
    kind: deterministic
    check: "The `.env.cache` file contains `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `SNAPPY_MASTER_KEY`."
  - name: eval_log_entry_created
    kind: deterministic
    check: "A log entry for 'sync-creds' exists in `state/log/evals.ndjson` with 'source_used' and 'verified_keys' fields."

sync-creds - loader

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

Critical Rules

• NEVER commit .env.cache to git - .gitignore blocks it, but the rule is a hard line, not a safety net.
• NEVER log actual credential values. Log only key names and presence (e.g., verified_keys: 12, never ANTHROPIC_API_KEY=sk-...).
• ALWAYS chmod 600 ~/projects/snappy-os/.env.cache after writing.
• The canonical path is ~/projects/snappy-os/.env.cache. The kernel path ~/.claude/skills/snappy-settings/.env.cache is a back-compat symlink - do not write through it.
• Source preference order: 1Password CLI → Doppler → Tailscale rsync. 1Password is the durable answer; rsync requires knowing which machine is "authoritative".

Commands

| ui dashboard | state/skills/sync-creds/resources/ui.openui | |invoke (1password): op read "op://snappy-os/env-cache" > ~/projects/snappy-os/.env.cache && chmod 600 ~/projects/snappy-os/.env.cache |invoke (rsync): rsync -av macbook-pro:~/projects/snappy-os/.env.cache ~/projects/snappy-os/.env.cache && chmod 600 ~/projects/snappy-os/.env.cache |invoke (doppler): doppler secrets download --project snappy-os --no-file > ~/projects/snappy-os/.env.cache |verify: grep -q "^ANTHROPIC_API_KEY=" ~/projects/snappy-os/.env.cache || echo "MISSING" |eval log: state/log/evals.ndjson (skill: "sync-creds") - fields: source_used, verified_keys, missing_expected

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/sync-creds/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

• Expected baseline keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, SNAPPY_MASTER_KEY, LINKEDIN_CLIENT_ID, DO_SPACES_KEY. Missing any → score 0.5 with key-missing.
• Score 0.0 only when verified_keys === 0 (fetch-failed) - partial pulls land at 0.5.
• If using 1Password/Doppler, never cache decrypted content anywhere other than ~/projects/snappy-os/.env.cache.
• After running, every credential-using skill should work immediately - no further setup.

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to commit .env.cache
2. [ ] Run chmod 600 after writing the file
3. [ ] Detect source automatically (try op → doppler → tailscale reachability)

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] sync-creds: <what was missing>" >> state/log/loader-feedback.log

<!-- 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)] sync-creds: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• 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.

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.