/tarot — the Gwelh-di-nees living board

$SKILL below means the directory containing this SKILL.md (it holds engine/ and assets/cards/). User state lives in ~/.gwelh-di-nees/ — the engine creates it automatically; it must NEVER be written inside the plugin directory.

Privacy (tell the user on their first run): this skill reads their local Claude Code session logs (~/.claude/projects). Everything — transcripts, annotations, profile — stays on their machine in ~/.gwelh-di-nees/. Nothing leaves it unless they choose to publish the rendered board as an artifact.

Pipeline (run all steps, in order)

1. Ingest

python3 "$SKILL/engine/ingest.py" --n 20

Writes ~/.gwelh-di-nees/sessions.json (default 20 sessions, clamp 15-25; pass the user's number if they gave one). Sessions include human-typed messages, titles, and telemetry.

2. Annotate (you do this — the LLM pass)

Read ~/.gwelh-di-nees/sessions.json. For each session not already present in ~/.gwelh-di-nees/readings.json (merge — never re-annotate cached session_ids, and drop cached entries no longer in the window), produce a reading. Write readings.json:

{"readings": [{
  "session_id": "<uuid>",
  "theme": "short-kebab-slug of what the session was about",
  "topical": ["new_start"|"ending"|"decision"|"shipped"|"stuck"|"reflection"|"structure"|"convention"|"tending"|"retro"|"purpose"|"play"|"crisis"|"recovery"|"external_change"|"shortcut"|"names_compulsion"],
  "emotions": {"<goemotions-label>": 0.0-1.0},
  "valence": 0.0-1.0, "arousal": 0.0-1.0,
  "outcome": "resolved"|"unresolved"|"abandoned"|"partial"|"n/a",
  "evidence": [{"quote": "verbatim user words, <=200 chars", "why": "what it signals"}]
}]}

Annotation rules (binding — see docs/SPEC-archetype-signatures.md in the plugin repo for the full spec):

• Judge ONLY the user's human messages — never the assistant's replies.
• Technical jargon is NOT emotional negativity ("kill the process", "fatal", "crash" are neutral).
• Multi-label emotions with honest confidences; presence over magnitude; when uncertain, lower the confidence rather than dropping the label.
• Valence x arousal matter more than labels: stressed-frustrated = low valence HIGH arousal; flat-fogbound = low valence LOW arousal.
• Evidence quotes must be verbatim, specific, falsifiable. They ground your synthesis internally and are NEVER shown in the UI.

3. Score

python3 "$SKILL/engine/score.py"

Deterministic: constellation gates, 7-day half-life decay, suppression pairs, shadow flags, confidence. Writes ~/.gwelh-di-nees/board-state.json.

3.5 Synthesize insights + maintain the profile (you do this)

The board shows SYNTHESIS, never sources — the user trusts the process and judges accuracy against their own life.

Read board-state.json, readings.json, and profile.json (if present) from ~/.gwelh-di-nees/. Write insights.json:

{
 "persona": {"title": "The <evocative chapter name for this window>", "body": "2-3 sentences naming who they were this window"},
 "draw": [{"card_id": "...", "heading": "...", "body": "..."}],
 "crooked": {"card_id": "...", "heading": "...", "body": "..."},
 "changes": [{"card_id": "...", "direction": "rising"|"waning", "body": "1-2 sentences on what shifted and what it suggests"}],
 "stats": [{"label": "...", "value": "...", "note": "..."}],
 "atlas": {"<every card_id>": "1-2 sentence second-person reading, including the dark cards"}
}

Writing rules (binding):

• Second person, psychologically specific, grounded ONLY in what the readings/telemetry actually show — never invent. Dark cards get insights too ("dark, and healthily so").
• Spotify-Wrapped energy inside the tarot world: name their window like a chapter, surface patterns they'd recognize but haven't named (speech tics, rhythms, tensions), keep it fun and a little profound. No quotes, no dates, no session names, no jargon.
• draw = top 3 cards; crooked = the most notable reversed card (omit if none).
• stats = 5-6 wrapped-style tiles in world language, computed from sessions.json (messages, tokens, longest session, walk-aways (away_summaries), late nights, favorite phrases — count them with a quick python one-liner).
• changes: empty on first run. Otherwise diff board intensities vs profile.last_board — narrate the 2-4 biggest movements (rising/waning) against the profile's threads and tensions.

Then update ~/.gwelh-di-nees/profile.json: bump updated_at and readings_count, append to persona_history, refresh baseline threads/tensions/rhythms where the new window genuinely changes them (evolve, don't rewrite), and overwrite last_board with the new intensities. If no profile exists, seed it (baseline: dominant_arcana, rhythms, threads, tensions, speech_signature) and tell the user their profile has been seeded.

4. Render

python3 "$SKILL/engine/render.py"

Writes self-contained ~/.gwelh-di-nees/board.html (card art inlined as data URIs).

5. Launch

• If artifact publishing is available: publish ~/.gwelh-di-nees/board.html (favicon 🔮, keep it stable; reuse the URL recorded in ~/.gwelh-di-nees/artifact-url.txt via the url param; write that file on first publish).
• Also deliver the file directly (SendUserFile with display: render, or open ~/.gwelh-di-nees/board.html).

After launching

Give a 3-5 sentence reading in prose: the persona line, the draw, whether anything is reversed, one conspicuously dark card, and (from the second reading on) the biggest turning since last time. Tone: reflective mirror, never prediction or diagnosis. Remind the user they can argue with any card — and that the full lore lives in the plugin's docs/guidebook.html.

Regenerating card art

Card art ships in $SKILL/assets/cards/*.jpg (style + original Higgsfield job IDs in assets/jobs.json). Only regenerate if the user asks and has Higgsfield access; keep the locked style preamble from jobs.json.