@warmdrift/kgauto-compiler 2.0.0-alpha.27 → 2.0.0-alpha.29

package/README.md

@@ -89,6 +89,48 @@ await record({
 });
 ```
 
+## Structured advisories API (alpha.29+)
+
+kgauto's compile-time advisories (`caching-off-on-claude`, `tool-bloat`,
+`archetype-perf-floor-breach`, etc.) used to vanish after the consumer read
+the compile result. alpha.29 ships a structured query + resolution surface
+so Admin UIs can render "what's open right now?" without log-scraping.
+
+```ts
+import {
+  getActionableAdvisories,
+  markAdvisoryResolved,
+} from '@warmdrift/kgauto-compiler';
+
+// Query open advisories for this app
+const open = await getActionableAdvisories({
+  appId: 'playbacksam',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+
+for (const a of open) {
+  console.log(`[${a.severity}] ${a.rule} — ${a.observationCount} firings since ${a.openedAt}`);
+  console.log(`  ${a.message}`);
+  if (a.suggestedFix?.docsLink) console.log(`  ↳ ${a.suggestedFix.docsLink}`);
+}
+
+// After the operator fixes the issue, mark it resolved:
+const r = await markAdvisoryResolved({
+  id: open[0].id,
+  resolutionNote: 'wired historyCachePolicy in compile() — PR #99',
+  brainEndpoint: process.env.KGAUTO_BRAIN_ENDPOINT!,
+  brainJwt: process.env.KGAUTO_BRAIN_JWT!,
+  brainAnonKey: process.env.KGAUTO_BRAIN_ANON_KEY!,
+});
+if (!r.ok) console.error(r.reason);
+```
+
+The view enforces server-side auto-resolution: advisories with no firing
+in the last 14 days flip to `status='resolved'` automatically; the next
+firing reopens the rule with a fresh stable `id`.
+
 ## Architecture
 
 ```