settings

Credential management API for all snappy-* skills.

Ported from kernel snappy-settings in Phase 0.5. See state/lib/settings.ts for the full API surface.

Steps

• listCredentials() - see state/lib/settings.ts
• checkCredential() - see state/lib/settings.ts
• env() - see state/lib/settings.ts
• loadAll() - see state/lib/settings.ts

Eval

Actor: the exported functions in state/lib/settings.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

1. realpathSync(process.argv[1]) CLI guard wrapped in try/catch

• See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: api_function_signatures_match
    kind: deterministic
    check: "The function signatures of listCredentials, checkCredential, env, and loadAll in state/lib/settings.ts exactly match the expected API, including parameter types and return types."
  - name: credential_listing_accuracy
    kind: judge
    check: "When listCredentials() is invoked, the output accurately reflects all credentials managed by snappy-os, without including extraneous or omitting valid credentials."
  - name: credential_checking_correctness
    kind: judge
    check: "When checkCredential(credentialName) is invoked, the output correctly indicates the validity or presence of the specified credential, aligning with the actual system state."
  - name: env_variable_retrieval
    kind: judge
    check: "When env() is invoked, it correctly returns the environment variables relevant to snappy-os operations as per spec, without leakage or missing critical variables."

settings - loader

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

Critical Rules

• NEVER hardcode a token, never write one to git, never add a process.env.KEY || bash-fallback - always go through env("KEY") from state/lib/env.ts
• env("KEY") THROWS if missing and required is true (the default) - pass required: false only when absence is genuinely OK
• New credential? Add it to .env.cache (repo root, canonical) WITH a comment, then read it via env("KEY")
• The kernel path ~/.claude/skills/snappy-settings/.env.cache is a back-compat symlink → snappy-os repo root. Do NOT flip the direction; do NOT edit the symlink target
• A broken .env.cache symlink silently kills every external API call - fix the symlink first when anything that hits the network mysteriously fails; verify with ls -l ~/.claude/skills/snappy-settings/.env.cache
• Eval is manual (Robert review) - every run MUST file a row to state/log/pending-eval.ndjson via the eval.pending() helper
• SettingsPopover in snappy-chat cannot be opened via the openclaw exec bridge - no click passthrough through WKWebView, no JS-eval endpoint exposed over the bridge. To capture or interact with the SettingsPopover: use WKWebView.evaluateJavaScript in-process (Swift) or inject via the /dispatch/chat route with action=view-customize. Do not attempt cliclick through the bridge (no accessibility perms in the bridge process). This is a known hard limit: design-gap audits (2026-04-29) confirmed 8 gaps vs Claude Desktop but couldn't open the popover via bridge - the customize-view was captured via chat-inject-control instead.

Commands

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

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to add a process.env.KEY || fallback when env("KEY") throws
2. [ ] Edit .env.cache (canonical repo root) not the symlink target when adding a credential
3. [ ] File a pending-eval.ndjson row on every run (auditor is still manual)
4. [ ] Know that SettingsPopover cannot be triggered via the openclaw exec bridge - use JS injection in-process or chat-inject-control

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

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they 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 is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

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

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick 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.

OpenUI Resource

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