kpis-snapshot

Producer skill that closes the catalog-to-cockpit drift gap for the KPIBlock shape: when the cockpit asks "give me a snappy-os pulse" or "what's the health of the system", the dispatcher used to fall back to plain text because no skill emitted a KPIBlock. kpis-snapshot reads three on-disk signals - distinct slugs in state/log/evals.ndjson over the last 7 days, scheduled agents in state/agents/*.json, and pending queue depth in state/log/regen-pending.txt plus state/log/eval-pending.txt - and emits one inline marker:

[[TOOL:KPIBlock]]{"title":"snappy-os pulse","value":"<N> skills","delta":"<M> scheduled","deltaTone":"info","subtitle":"<P> pending"}[[/TOOL]]

The server lifts the marker into a TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple; snappy-chat renders the KPIBlock card via web/src/genui-library.tsx → KPIBlockComponent.

The route handler at GET /kpis-snapshot (in state/bin/head-screen/server.ts) returns the same JSON shape so the LLM has a deterministic example it can mimic when it chooses to emit a KPIBlock during an SSE chat stream.

Pure read. Never writes. Scope-only by snappy-os convention.

Steps

1. Read state/log/evals.ndjson. Count distinct skill field values whose

ts is within the last 7 days (rolling). That count is value - render it as "<N> skills".

1. Read every JSON file in state/agents/*.json. Count those whose

status is "running" or "scheduled". That count is delta - render it as "<M> scheduled". Tone stays "info" regardless; this shape is informational, not pass/fail.

1. Read state/log/regen-pending.txt and state/log/eval-pending.txt.

Sum the non-empty line counts. That sum is subtitle - render it as "<P> pending".

1. Build the JSON object `{title:"snappy-os pulse", value, delta,

deltaTone:"info", subtitle} and emit a single [[TOOL:KPIBlock]]{...}[[/TOOL]]` marker on its own line in the assistant text stream. The server's marker-lifter does the rest.

Trigger phrases the dispatcher should recognize: "snappy-os pulse", "system pulse", "kpi snapshot", "health snapshot", "skills count", "how many skills".

Route handler

GET /kpis-snapshot on 127.0.0.1:3147 returns:

{
  "ok": true,
  "marker": "[[TOOL:KPIBlock]]{\"title\":\"snappy-os pulse\",\"value\":\"157 skills\",\"delta\":\"10 scheduled\",\"deltaTone\":\"info\",\"subtitle\":\"0 pending\"}[[/TOOL]]",
  "kpis": { "skills": 157, "scheduled": 10, "pending": 0 }
}

The kpis field carries the raw integers so callers (other skills, the brain layer) can read the same numbers without re-parsing the marker. The marker string is the canonical inline form the LLM mimics.

Eval

Actor: the route handler at GET /kpis-snapshot plus the prose Steps above (the agent walks the three reads and emits one marker). Auditor: independent shape check - the emitted marker MUST match the KPIBlockComponent Zod schema in snappy-chat/web/src/genui-library.tsx (positional order: title, value, delta, deltaTone, subtitle; deltaTone ∈ {ok, warn, info}).

Rubric

criteria:
  - name: shape_matches_schema
    kind: deterministic
    check: "marker has title, value, delta, deltaTone, subtitle keys; deltaTone in {ok,warn,info}; value/delta/subtitle are strings."
  - name: numbers_match_disk
    kind: deterministic
    check: "skills count equals distinct-slug count in evals.ndjson last 7d; scheduled equals running+scheduled agents in state/agents/*.json; pending equals non-empty line count across the two queue files."
  - name: single_emit_per_turn
    kind: deterministic
    check: "exactly one [[TOOL:KPIBlock]] marker per response; the dispatcher MUST NOT re-emit if llmEmittedNames already contains KPIBlock."

kpis-snapshot - loader

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

Critical Rules

1. Pure read. NEVER writes. Scope-only by snappy-os convention; no probe is allowed to mutate state. If asked to "refresh" or "rebuild" the pulse, re-read the three signals - do not write a derived cache.
2. deltaTone enum is ok|warn|info - exactly. The KPIBlockComponent Zod schema in snappy-chat/web/src/genui-library.tsx validates this; any off-enum value renders nothing or trips the fallback. For pulse snapshots default to info.
3. Single emit per turn. Exactly one [[TOOL:KPIBlock]] marker per response. The dispatcher MUST NOT re-emit if llmEmittedNames already contains KPIBlock.
4. Three reads, three numbers, no fabrication. value ← distinct skill slugs in state/log/evals.ndjson whose ts is within the last 7 days (rolling, Date.now() - 7*86400_000 - NOT calendar-week). delta ← agents whose status is running or scheduled in state/agents/*.json. subtitle ← non-empty line count summed across state/log/regen-pending.txt AND state/log/eval-pending.txt. If a file is missing, its contribution is 0; do not invent a number.
5. Marker stays on its own line. The server's marker-lifter scans the assistant text stream; markers split across tokens are tolerated, but a marker buried mid-prose can collide with surrounding punctuation.
6. Positional-key order matters. The marker JSON shape is fixed: {title, value, delta, deltaTone, subtitle}. The renderer reads by name (Zod), but the SKILL.md contract documents the order - keep emitter and rubric in lockstep.

Commands

| ui dashboard | state/skills/kpis-snapshot/resources/ui.openui |

OpenUI Resource

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

• KPIBlockComponent accepts value as string OR number. The route renders "<N> skills" (string) by convention; a bare number renders but loses the unit.
• On a fresh clone with empty evals.ndjson, value is "0 skills". That's honest, not a bug. Do not pad.
• Adding a fourth signal (e.g. open PRs) requires lockstep changes in BOTH state/bin/head-screen/server.ts (route handler) AND state/skills/kpis-snapshot/SKILL.md rubric block.
• The marker MUST land on its own line in the SSE text stream. Mid-prose embedding is tolerated by the lifter but increases false-negative rate against punctuation neighbours.
• Distinct-slug count is a 7-day ROLLING window, not "this week". Off-by-one bugs come from interpreting "this week" as calendar-week.

Self-Test

An agent reading this should correctly:

1. [ ] Know this is a prose-only producer skill backed by GET /kpis-snapshot in state/bin/head-screen/server.ts (no separate state/lib/kpis-snapshot.ts)?
2. [ ] Pick deltaTone from {ok, warn, info} only, defaulting to info for pulse snapshots?
3. [ ] Refuse to emit a KPIBlock if llmEmittedNames already contains it (single-emit-per-turn)?
4. [ ] Read three on-disk signals - last-7-days distinct slugs, running+scheduled agents, non-empty pending-queue lines - without fabricating?
5. [ ] Append the run to state/log/evals.ndjson with skill "kpis-snapshot" and eval_mode: auto-shape from the SKILL.md frontmatter?

<!-- 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)] kpis-snapshot: <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 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.