@olegkoval/agent-skills 1.31.0 → 1.32.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -54,6 +54,7 @@
     "./packages/software-development/morning-routine",
     "./packages/software-development/release-day",
     "./packages/software-development/branch-cleanup",
-    "./packages/software-development/vinted-listing"
+    "./packages/software-development/vinted-listing",
+    "./packages/software-development/shared-knowledge-artifact"
   ]
 }

package/README.md

@@ -3,7 +3,7 @@
   <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.</strong></p>
   <p>
     <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
-    <img src="https://img.shields.io/badge/skills-45-2563eb" alt="45 skills">
+    <img src="https://img.shields.io/badge/skills-47-2563eb" alt="47 skills">
     <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Grok%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro-111827" alt="Codex Claude Cursor Grok Copilot Windsurf Kiro">
     <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
   </p>
@@ -139,11 +139,11 @@ packages/{category}/{skill}/SKILL.md
 
 </details>
 
-## All 45 Skills
+## All 47 Skills
 
 Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup name in a new agent session.
 
-### Software development (39)
+### Software development (41)
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
@@ -174,6 +174,7 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [relay](packages/software-development/relay/SKILL.md) | Uses `claude-relay` to run long or rate-limit-prone tasks autonomously across subscription accounts | A task will outlive one session or hit rate limits partway through |
 | [review-past-performance](packages/software-development/review-past-performance/SKILL.md) | Pulls 24h of ICM memories, git history, and skill analytics; detects repeated mistakes and slow workflows; proposes 1-3 concrete fixes | Daily self-improvement loop or codifying a repeated workflow |
 | [self-critique](packages/software-development/self-critique/SKILL.md) | Adversarially critiques your own last answer: spawns a critic agent that verifies claims against live sources, then loops until satisfied and reports where you were wrong | Checking a substantial answer before the user has to |
+| [shared-knowledge-artifact](packages/software-development/shared-knowledge-artifact/SKILL.md) | Builds a shared, self-persisting knowledge ledger as a Claude Artifact — a private page that stores its own data, renders itself from it, and publishes new versions of itself so several agents read the same lessons and append to them | Giving multiple agents one place to learn from each other instead of repeating the same mistakes |
 | [semantic-release-beta](packages/software-development/semantic-release-beta/SKILL.md) | Sets up `semantic-release` with stable `main` releases and beta prereleases on a `beta` branch | A Node package needs stable npm publishing plus beta prereleases |
 | [skill-budget-audit](packages/software-development/skill-budget-audit/SKILL.md) | Diagnoses and fixes Claude Code's skill context budget overflow — identifies heavy plugin bundles that exceed the 2% budget | Skills failing to load or Claude hitting context limits from plugin bundles |
 | [starter-rules](packages/software-development/starter-rules/SKILL.md) | Loads and enforces hard rules for every oleg-koval/* starter | Ensuring 300-line files, E2E tests, pre-commit hooks, Vertical Slice architecture, and KISS/DRY/SOLID |

package/catalog/skills.json

@@ -1070,6 +1070,24 @@
         "copilot",
         "grok"
       ]
+    },
+    {
+      "name": "shared-knowledge-artifact",
+      "lookupName": "olko:shared-knowledge-artifact",
+      "category": "software-development",
+      "path": "packages/software-development/shared-knowledge-artifact",
+      "description": "Build a shared, self-persisting knowledge ledger as a Claude Artifact: a private page that stores its own data, renders itself from it, and publishes new versions of itself so several agents read the same lessons before working and append to them afterwards.",
+      "tags": [
+        "artifacts",
+        "knowledge-base",
+        "multi-agent",
+        "memory",
+        "lessons-learned",
+        "documentation"
+      ],
+      "adapters": [
+        "claude"
+      ]
     }
   ]
 }

package/collections/software-development.json

@@ -12,6 +12,7 @@
     "product-builder",
     "mvp-oneshot",
     "wikipedia-uk-editor",
-    "vinted-listing"
+    "vinted-listing",
+    "shared-knowledge-artifact"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/packages/software-development/shared-knowledge-artifact/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: shared-knowledge-artifact
+description: Build a shared, self-persisting knowledge ledger as a Claude Artifact — a private page that stores its own data, renders itself from that data, and saves new versions of itself, so several agents can read the same lessons before starting work and append to them afterwards. Use when the user wants agents to learn from each other, asks for a shared knowledge base, lessons-learned log, gotcha ledger, or cross-agent memory page they can hand to other sessions.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Skill, Artifact
+compatibility: Claude Code only — requires the Artifact tool and the artifact runtime capabilities (`capabilities: {artifact: {}}`).
+metadata:
+  author: Oleg Koval
+  package: shared-knowledge-artifact
+  tags:
+    - artifacts
+    - knowledge-base
+    - multi-agent
+    - memory
+    - lessons-learned
+    - documentation
+---
+
+# shared-knowledge-artifact
+
+Publish one private Artifact page that acts as an append-only knowledge ledger which multiple agents (and the user) read before starting work and write to when reality corrects them. The page **is** the record: it stores its own data and publishes new versions of itself, so nothing depends on a server or on local files.
+
+## Trigger phrases
+
+- create a shared artifact my other agents can learn from
+- shared knowledge base / lessons-learned log / gotcha ledger for agents
+- cross-agent memory page
+- somewhere agents can record what they learned so they don't repeat it
+
+## Before writing any code
+
+1. Invoke the `artifact-capabilities` skill — mandatory before declaring `capabilities` or writing any `window.claude.*` code.
+2. Invoke the `artifact-design` skill — calibrates the design treatment.
+3. Read the user's actual rules (`CLAUDE.md`, any verification/preferences doc, agent memory) and **seed the ledger with 6-10 real lessons already recorded there**. No lorem, no invented examples — a ledger that opens with fake entries never gets used.
+
+## Persistence mechanism
+
+- Declare `capabilities: {artifact: {}}` at publish time.
+- Store the data as a JSON object inside `<script type="application/json" id="ledger-state">`. That block is the authoritative record; the visible page is **rendered from it** at load. Never serialize the live DOM to save.
+- To persist: snapshot `document.documentElement.outerHTML` **once at script start** (pristine source, before any rendering), then on save splice the new JSON into that snapshot's `#ledger-state` block, prepend `<!doctype html>`, and call `artifact.publish(doc)`.
+- Get the namespace with `const artifact = await claude.use("artifact")`; branch on `null` (this view cannot write) and render a read-only state instead of a broken control.
+- Handle publish errors by code: `conflict` means someone published first and every view reloads to the winner — no retry, tell the person to re-add; `not_granted` / `not_writer` means read-only.
+- Publish only after an explicit user action, never on load; batch rapid edits into one publish.
+- Escape `</script` when writing the JSON back, and escape every interpolated note field on render.
+
+## Note schema
+
+One fact per entry:
+
+```json
+{"id":"n9","kind":"lesson|trap|pref","scope":"shell|review|github|...",
+ "title":"the rule in one line",
+ "body":"the concrete behaviour, specific enough to act on",
+ "why":"the failure that made this a rule",
+ "author":"model or agent name","date":"YYYY-MM-DD"}
+```
+
+Kinds: **lesson** = a habit that holds; **trap** = something that silently produces a *wrong* answer; **pref** = how the user wants the work done.
+
+## UI the page must have
+
+- Header: name, one paragraph on what the ledger is for, and live counts (total, traps, lessons, preferences) in `tabular-nums`.
+- Note list, newest first: kind tag, scope tag, author, date, title, body, and a `Why:` line. Kind tags use semantic colour (trap = critical, pref = warning, lesson = accent), separate from the page accent.
+- Scope filter chips derived from the data, including an `all` chip, with `aria-pressed` state.
+- An "Add a note" form (kind, scope, author, title, body, why) that appends to the JSON and publishes, with an inline status line reporting published / conflict / read-only.
+- A "Protocol for agents" section **on the page itself**: read the page with the Artifact tool `action: "read"` before substantive work; parse the `#ledger-state` JSON, never scrape the DOM; **append, don't rewrite**; re-read before writing because another agent may have published since; one fact per note with the failure that caused it. Include the schema snippet.
+- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's `CLAUDE.md` already says it, or a review bot already catches it, leave it out — a littered ledger is worse than a thin one.
+
+## Design constraints
+
+- Utilitarian but genuinely polished: this is a reference document, not a landing page. No oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.
+- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or Space Grotesk as the "safe" face.
+- Pair a display face, a body face, and a mono utility face from Google Fonts (the only permitted external host), each with a real fallback stack.
+- Theme-aware in all three states: full light palette as tokens on bare `:root`; redefined under `@media (prefers-color-scheme: dark)` guarded as `:root:not([data-theme="light"])`; redefined again under `:root[data-theme="dark"]`. Style everything through tokens and give `body` an explicit token background. No colour whose only definition sits inside a media or `[data-theme]` block.
+- Layout with flex/grid + `gap`, not per-element margins. Wide content in its own `overflow-x: auto` container. Visible focus states. Respect `prefers-reduced-motion`.
+- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a one-sentence `description` and an emoji `favicon`, and keep both stable across redeploys.
+
+## Deliverable
+
+Write the HTML to a file, publish it with the Artifact tool, then report:
+
+- the URL;
+- that it stays private until shared from the page's share menu;
+- the exact instructions another agent needs — read via Artifact `action: "read"` with that URL, and write by appending to `notes` and republishing **with `url` set to that URL** (a publish *without* `url` forks a separate artifact instead of updating this one).
+
+## Notes
+
+- The full copy-paste prompt version of this workflow lives in `references/prompt.txt` — hand it to another agent or session verbatim.
+- Redeploy by republishing the same file path in the same conversation, or by passing `url` from any other conversation.

package/packages/software-development/shared-knowledge-artifact/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-shared-knowledge-artifact",
+  "description": "Build a shared, self-persisting knowledge ledger as a Claude Artifact: a private page that stores its own data, renders itself from it, and publishes new versions of itself so several agents read the same lessons before working and append to them afterwards.",
+  "skills": "./skills"
+}

package/packages/software-development/shared-knowledge-artifact/adapters/claude/skills/shared-knowledge-artifact/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: shared-knowledge-artifact
+description: Build a shared, self-persisting knowledge ledger as a Claude Artifact — a private page that stores its own data, renders itself from that data, and saves new versions of itself, so several agents can read the same lessons before starting work and append to them afterwards. Use when the user wants agents to learn from each other, asks for a shared knowledge base, lessons-learned log, gotcha ledger, or cross-agent memory page they can hand to other sessions.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Skill, Artifact
+compatibility: Claude Code only — requires the Artifact tool and the artifact runtime capabilities (`capabilities: {artifact: {}}`).
+metadata:
+  author: Oleg Koval
+  package: shared-knowledge-artifact
+  tags:
+    - artifacts
+    - knowledge-base
+    - multi-agent
+    - memory
+    - lessons-learned
+    - documentation
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# shared-knowledge-artifact
+
+Publish one private Artifact page that acts as an append-only knowledge ledger which multiple agents (and the user) read before starting work and write to when reality corrects them. The page **is** the record: it stores its own data and publishes new versions of itself, so nothing depends on a server or on local files.
+
+## Trigger phrases
+
+- create a shared artifact my other agents can learn from
+- shared knowledge base / lessons-learned log / gotcha ledger for agents
+- cross-agent memory page
+- somewhere agents can record what they learned so they don't repeat it
+
+## Before writing any code
+
+1. Invoke the `artifact-capabilities` skill — mandatory before declaring `capabilities` or writing any `window.claude.*` code.
+2. Invoke the `artifact-design` skill — calibrates the design treatment.
+3. Read the user's actual rules (`CLAUDE.md`, any verification/preferences doc, agent memory) and **seed the ledger with 6-10 real lessons already recorded there**. No lorem, no invented examples — a ledger that opens with fake entries never gets used.
+
+## Persistence mechanism
+
+- Declare `capabilities: {artifact: {}}` at publish time.
+- Store the data as a JSON object inside `<script type="application/json" id="ledger-state">`. That block is the authoritative record; the visible page is **rendered from it** at load. Never serialize the live DOM to save.
+- To persist: snapshot `document.documentElement.outerHTML` **once at script start** (pristine source, before any rendering), then on save splice the new JSON into that snapshot's `#ledger-state` block, prepend `<!doctype html>`, and call `artifact.publish(doc)`.
+- Get the namespace with `const artifact = await claude.use("artifact")`; branch on `null` (this view cannot write) and render a read-only state instead of a broken control.
+- Handle publish errors by code: `conflict` means someone published first and every view reloads to the winner — no retry, tell the person to re-add; `not_granted` / `not_writer` means read-only.
+- Publish only after an explicit user action, never on load; batch rapid edits into one publish.
+- Escape `</script` when writing the JSON back, and escape every interpolated note field on render.
+
+## Note schema
+
+One fact per entry:
+
+```json
+{"id":"n9","kind":"lesson|trap|pref","scope":"shell|review|github|...",
+ "title":"the rule in one line",
+ "body":"the concrete behaviour, specific enough to act on",
+ "why":"the failure that made this a rule",
+ "author":"model or agent name","date":"YYYY-MM-DD"}
+```
+
+Kinds: **lesson** = a habit that holds; **trap** = something that silently produces a *wrong* answer; **pref** = how the user wants the work done.
+
+## UI the page must have
+
+- Header: name, one paragraph on what the ledger is for, and live counts (total, traps, lessons, preferences) in `tabular-nums`.
+- Note list, newest first: kind tag, scope tag, author, date, title, body, and a `Why:` line. Kind tags use semantic colour (trap = critical, pref = warning, lesson = accent), separate from the page accent.
+- Scope filter chips derived from the data, including an `all` chip, with `aria-pressed` state.
+- An "Add a note" form (kind, scope, author, title, body, why) that appends to the JSON and publishes, with an inline status line reporting published / conflict / read-only.
+- A "Protocol for agents" section **on the page itself**: read the page with the Artifact tool `action: "read"` before substantive work; parse the `#ledger-state` JSON, never scrape the DOM; **append, don't rewrite**; re-read before writing because another agent may have published since; one fact per note with the failure that caused it. Include the schema snippet.
+- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's `CLAUDE.md` already says it, or a review bot already catches it, leave it out — a littered ledger is worse than a thin one.
+
+## Design constraints
+
+- Utilitarian but genuinely polished: this is a reference document, not a landing page. No oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.
+- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or Space Grotesk as the "safe" face.
+- Pair a display face, a body face, and a mono utility face from Google Fonts (the only permitted external host), each with a real fallback stack.
+- Theme-aware in all three states: full light palette as tokens on bare `:root`; redefined under `@media (prefers-color-scheme: dark)` guarded as `:root:not([data-theme="light"])`; redefined again under `:root[data-theme="dark"]`. Style everything through tokens and give `body` an explicit token background. No colour whose only definition sits inside a media or `[data-theme]` block.
+- Layout with flex/grid + `gap`, not per-element margins. Wide content in its own `overflow-x: auto` container. Visible focus states. Respect `prefers-reduced-motion`.
+- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a one-sentence `description` and an emoji `favicon`, and keep both stable across redeploys.
+
+## Deliverable
+
+Write the HTML to a file, publish it with the Artifact tool, then report:
+
+- the URL;
+- that it stays private until shared from the page's share menu;
+- the exact instructions another agent needs — read via Artifact `action: "read"` with that URL, and write by appending to `notes` and republishing **with `url` set to that URL** (a publish *without* `url` forks a separate artifact instead of updating this one).
+
+## Notes
+
+- The full copy-paste prompt version of this workflow lives in `references/prompt.txt` — hand it to another agent or session verbatim.
+- Redeploy by republishing the same file path in the same conversation, or by passing `url` from any other conversation.

package/packages/software-development/shared-knowledge-artifact/adapters/claude/skills/shared-knowledge-artifact/references/prompt.txt

@@ -0,0 +1,78 @@
+BUILD A SHARED AGENT-KNOWLEDGE ARTIFACT
+
+Goal
+Publish a single private Claude Artifact page that acts as an append-only, self-persisting
+knowledge ledger which multiple agents (and I) read before starting work and write to when
+reality corrects us. The page IS the record: it stores its own data and saves new versions of
+itself, so nothing depends on a server or on my local files.
+
+Before writing any code
+1. Load the artifact-capabilities skill (you must, before declaring capabilities or writing any
+   window.claude.* code) and the artifact-design skill (calibrates the design treatment).
+2. Read my global rules (CLAUDE.md / VERIFICATION.md / memory) and seed the ledger with 6-10
+   REAL lessons already recorded there. No lorem, no invented examples.
+
+Required behaviour
+- Declare capabilities: {artifact: {}} so the page can publish new versions of itself.
+- Store the data as a JSON object inside a <script type="application/json" id="ledger-state">
+  block. That block is the authoritative record; the visible page is RENDERED from it at load.
+  Never serialize the live DOM to save.
+- To persist: snapshot document.documentElement.outerHTML once at script start (pristine source,
+  before any rendering), then on save splice the new JSON into the #ledger-state block of that
+  snapshot, prepend <!doctype html>, and call artifact.publish(doc).
+- Get the namespace with: const artifact = await claude.use("artifact"); branch on null (view
+  cannot write) and render a read-only state instead of a broken control.
+- Handle publish errors by code: "conflict" means someone published first and every view reloads
+  to the winner (no retry - tell the person to re-add); "not_granted"/"not_writer" means
+  read-only. Publish only after an explicit user action, never on page load, and batch rapid
+  edits into one publish.
+
+Note schema (one fact per entry)
+  {"id":"...", "kind":"lesson|trap|pref", "scope":"shell|review|github|...",
+   "title":"the rule in one line", "body":"the concrete behaviour, specific enough to act on",
+   "why":"the failure that made this a rule", "author":"model or agent name",
+   "date":"YYYY-MM-DD"}
+Kinds: lesson = a habit that holds; trap = something that silently produces a WRONG answer;
+pref = how I want the work done.
+
+UI the page must have
+- Header: title, one-paragraph statement of what the ledger is for, and live counts
+  (total notes, traps, lessons, preferences) in tabular-nums.
+- Note list, newest first, each note showing kind tag, scope tag, author, date, title, body,
+  and a "Why:" line. Kind tags carry semantic colour (trap = critical, pref = warning,
+  lesson = accent) separate from the page accent.
+- Scope filter chips derived from the data, including an "all" chip, with aria-pressed state.
+- An "Add a note" form (kind select, scope, author, title, body, why) that appends to the JSON
+  and publishes, with an inline status line reporting published / conflict / read-only.
+- A "Protocol for agents" section, on the page itself, stating: read the page with the Artifact
+  tool action "read" before substantive work; parse the #ledger-state JSON, never scrape the DOM;
+  APPEND, don't rewrite; re-read before writing because another agent may have published since;
+  and one fact per note with the failure that caused it. Include a copyable JSON snippet of the
+  schema.
+- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's CLAUDE.md
+  already says it or a review bot already catches it, leave it out. A littered ledger is worse
+  than a thin one.
+
+Design constraints
+- Utilitarian but genuinely polished; this is a reference document, not a landing page. No
+  oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.
+- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or
+  Space Grotesk as the safe face.
+- Pair a display face with a body face and a mono utility face from Google Fonts (the only
+  permitted external host), each with a real fallback stack.
+- Theme-aware in all three states: full light palette as tokens on bare :root, redefined under
+  @media (prefers-color-scheme: dark) guarded as :root:not([data-theme="light"]), and again under
+  :root[data-theme="dark"]. Style everything through tokens; body must set an explicit token
+  background. No colour whose only definition sits inside a media or [data-theme] block.
+- Layout with flex/grid + gap, not per-element margins. Wide content in its own overflow-x:auto
+  container. Visible focus states. Respect prefers-reduced-motion.
+- Escape all interpolated note text on render, and escape "</script" when writing the JSON back.
+- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a
+  one-sentence description and an emoji favicon, and keep both stable across redeploys.
+
+Deliverable
+Write the HTML to a file, publish it with the Artifact tool, and report back: the URL, the fact
+that it is private until shared from the page's share menu, and the exact instructions another
+agent needs - read via Artifact action "read" with that URL, and write by appending to notes and
+republishing with `url` set to that URL (a publish WITHOUT url forks a separate artifact instead
+of updating this one).

package/packages/software-development/shared-knowledge-artifact/references/prompt.txt

@@ -0,0 +1,78 @@
+BUILD A SHARED AGENT-KNOWLEDGE ARTIFACT
+
+Goal
+Publish a single private Claude Artifact page that acts as an append-only, self-persisting
+knowledge ledger which multiple agents (and I) read before starting work and write to when
+reality corrects us. The page IS the record: it stores its own data and saves new versions of
+itself, so nothing depends on a server or on my local files.
+
+Before writing any code
+1. Load the artifact-capabilities skill (you must, before declaring capabilities or writing any
+   window.claude.* code) and the artifact-design skill (calibrates the design treatment).
+2. Read my global rules (CLAUDE.md / VERIFICATION.md / memory) and seed the ledger with 6-10
+   REAL lessons already recorded there. No lorem, no invented examples.
+
+Required behaviour
+- Declare capabilities: {artifact: {}} so the page can publish new versions of itself.
+- Store the data as a JSON object inside a <script type="application/json" id="ledger-state">
+  block. That block is the authoritative record; the visible page is RENDERED from it at load.
+  Never serialize the live DOM to save.
+- To persist: snapshot document.documentElement.outerHTML once at script start (pristine source,
+  before any rendering), then on save splice the new JSON into the #ledger-state block of that
+  snapshot, prepend <!doctype html>, and call artifact.publish(doc).
+- Get the namespace with: const artifact = await claude.use("artifact"); branch on null (view
+  cannot write) and render a read-only state instead of a broken control.
+- Handle publish errors by code: "conflict" means someone published first and every view reloads
+  to the winner (no retry - tell the person to re-add); "not_granted"/"not_writer" means
+  read-only. Publish only after an explicit user action, never on page load, and batch rapid
+  edits into one publish.
+
+Note schema (one fact per entry)
+  {"id":"...", "kind":"lesson|trap|pref", "scope":"shell|review|github|...",
+   "title":"the rule in one line", "body":"the concrete behaviour, specific enough to act on",
+   "why":"the failure that made this a rule", "author":"model or agent name",
+   "date":"YYYY-MM-DD"}
+Kinds: lesson = a habit that holds; trap = something that silently produces a WRONG answer;
+pref = how I want the work done.
+
+UI the page must have
+- Header: title, one-paragraph statement of what the ledger is for, and live counts
+  (total notes, traps, lessons, preferences) in tabular-nums.
+- Note list, newest first, each note showing kind tag, scope tag, author, date, title, body,
+  and a "Why:" line. Kind tags carry semantic colour (trap = critical, pref = warning,
+  lesson = accent) separate from the page accent.
+- Scope filter chips derived from the data, including an "all" chip, with aria-pressed state.
+- An "Add a note" form (kind select, scope, author, title, body, why) that appends to the JSON
+  and publishes, with an inline status line reporting published / conflict / read-only.
+- A "Protocol for agents" section, on the page itself, stating: read the page with the Artifact
+  tool action "read" before substantive work; parse the #ledger-state JSON, never scrape the DOM;
+  APPEND, don't rewrite; re-read before writing because another agent may have published since;
+  and one fact per note with the failure that caused it. Include a copyable JSON snippet of the
+  schema.
+- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's CLAUDE.md
+  already says it or a review bot already catches it, leave it out. A littered ledger is worse
+  than a thin one.
+
+Design constraints
+- Utilitarian but genuinely polished; this is a reference document, not a landing page. No
+  oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.
+- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or
+  Space Grotesk as the safe face.
+- Pair a display face with a body face and a mono utility face from Google Fonts (the only
+  permitted external host), each with a real fallback stack.
+- Theme-aware in all three states: full light palette as tokens on bare :root, redefined under
+  @media (prefers-color-scheme: dark) guarded as :root:not([data-theme="light"]), and again under
+  :root[data-theme="dark"]. Style everything through tokens; body must set an explicit token
+  background. No colour whose only definition sits inside a media or [data-theme] block.
+- Layout with flex/grid + gap, not per-element margins. Wide content in its own overflow-x:auto
+  container. Visible focus states. Respect prefers-reduced-motion.
+- Escape all interpolated note text on render, and escape "</script" when writing the JSON back.
+- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a
+  one-sentence description and an emoji favicon, and keep both stable across redeploys.
+
+Deliverable
+Write the HTML to a file, publish it with the Artifact tool, and report back: the URL, the fact
+that it is private until shared from the page's share menu, and the exact instructions another
+agent needs - read via Artifact action "read" with that URL, and write by appending to notes and
+republishing with `url` set to that URL (a publish WITHOUT url forks a separate artifact instead
+of updating this one).