@gobing-ai/knowledge-kit 0.0.10 → 0.0.12

package/plugins/ingestions/horizon-ingest/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "horizon-ingest",
+    "kind": "ingestion",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Wraps the Horizon CLI (uv run horizon) into Doc[] — one Doc per digest item block"
+}

package/plugins/ingestions/horizon-ingest/src/index.ts

@@ -0,0 +1,205 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { z } from 'zod';
+
+/**
+ * Ingestion adapter over the Horizon CLI (task 0089 contract).
+ * Runs `uv run horizon` (cwd = the Horizon repo), then parses the digest
+ * `<data-dir>/summaries/horizon-<date>-<lang>.md` written during this run —
+ * one Doc per `### [title](url)` item block.
+ */
+
+const InputConfigSchema = z.object({
+    data_dir: z.string().trim().min(1).optional(),
+    config: z.string().trim().min(1).optional(),
+    hours: z.number().int().min(1).optional(),
+    languages: z.array(z.string().trim().min(1)).optional(),
+    horizon_dir: z.string().trim().min(1).optional(),
+});
+
+export interface HorizonRunResult {
+    exitCode: number;
+    stderr: string;
+}
+
+/** Subprocess seam — tests inject a fake that pre-seeds a summaries file. */
+export type RunHorizon = (config: z.infer<typeof InputConfigSchema>, horizonDir: string) => Promise<HorizonRunResult>;
+
+export const defaultRunner: RunHorizon = async (config, horizonDir) => {
+    const argv = [process.env.HORIZON_UV ?? 'uv', 'run', 'horizon'];
+    if (config.hours !== undefined) argv.push('--hours', String(config.hours));
+    if (config.data_dir !== undefined) argv.push('-d', config.data_dir);
+    if (config.config !== undefined) argv.push('-c', config.config);
+    const proc = Bun.spawnSync(argv, { cwd: horizonDir, stdout: 'pipe', stderr: 'pipe' });
+    return { exitCode: proc.exitCode ?? 1, stderr: proc.stderr.toString() };
+};
+
+const HEADING_RE = /^### \[(.+)\]\((.+)\) ⭐️ ([\d.]+)\/10\s*$/m;
+const ANCHOR_RE = /<a id="item-([a-z0-9-]+)-(\d+)"><\/a>/;
+
+interface ParsedItem {
+    anchorProfile: string;
+    anchorN: string;
+    title: string;
+    url: string;
+    score: number;
+    block: string;
+}
+
+/** Split a digest markdown file into per-item blocks keyed off the item anchors. */
+export function splitItemBlocks(markdown: string): ParsedItem[] {
+    const items: ParsedItem[] = [];
+    const segments = markdown.split(/(?=<a id="item-)/);
+    for (const segment of segments) {
+        const anchor = segment.match(ANCHOR_RE);
+        const heading = segment.match(HEADING_RE);
+        if (!anchor || !heading) continue;
+        items.push({
+            anchorProfile: anchor[1] ?? '',
+            anchorN: anchor[2] ?? '',
+            title: heading[1] ?? '',
+            url: heading[2] ?? '',
+            score: Number(heading[3]),
+            block: segment,
+        });
+    }
+    return items;
+}
+
+/** Map one parsed item block to a Doc. */
+export function itemToDoc(item: ParsedItem, date: string, lang: string): Doc {
+    const lines = item.block.split('\n');
+    const bodyParts: string[] = [];
+    const references: string[] = [];
+    let sourceLine = '';
+    let tags: string[] = [];
+    let inDetails = false;
+    for (const line of lines.slice(1)) {
+        if (line.startsWith('<details')) inDetails = true;
+        if (line.startsWith('</details>')) {
+            inDetails = false;
+            continue;
+        }
+        if (inDetails) {
+            const href = line.match(/<a href="([^"]+)"/);
+            if (href?.[1]) references.push(href[1]);
+            continue;
+        }
+        const tagMatch = line.match(/^\*\*Tags\*\*:\s*(.+)$/);
+        if (tagMatch?.[1]) {
+            tags = [...tagMatch[1].matchAll(/#([^`,\s]+)/g)].map((m) => m[1] ?? '');
+            continue;
+        }
+        if (/^---\s*$/.test(line)) continue;
+        if (/^[a-z0-9_-]+ · /i.test(line) && !sourceLine) {
+            sourceLine = line.trim();
+            continue;
+        }
+        if (line.trim()) bodyParts.push(line);
+    }
+    const doc: Doc = {
+        id: `horizon:${date}-${item.anchorProfile}-${item.anchorN}`,
+        title: item.title,
+        body: bodyParts.join('\n').trim(),
+        sourceUri: item.url,
+        mediaType: 'text/markdown',
+        metadata: {
+            lang,
+            date,
+            profile: item.anchorProfile,
+            score: item.score,
+            source: sourceLine.split(' · ')[0] ?? '',
+            source_line: sourceLine,
+            tags,
+            references,
+        },
+    };
+    return doc;
+}
+
+/** Parse a full digest file into Doc[]. */
+export function digestToDocs(markdown: string, date: string, lang: string): Doc[] {
+    return DocListSchema.parse(splitItemBlocks(markdown).map((item) => itemToDoc(item, date, lang)));
+}
+
+export interface IngestionOptions {
+    out: string;
+}
+
+export async function processIngestionIO(
+    options: IngestionOptions,
+    config: z.infer<typeof InputConfigSchema>,
+    runner: RunHorizon = defaultRunner,
+    now: Date = new Date(),
+): Promise<{ docs: Doc[] }> {
+    const fs = createNodeFileSystem();
+    const horizonDir = config.horizon_dir ?? process.env.HORIZON_DIR ?? join(homedir(), 'tools', 'Horizon');
+    const dataDir = config.data_dir ?? join(horizonDir, 'data');
+
+    const runStartedAt = now.getTime();
+    const run = await runner(config, horizonDir);
+    if (run.exitCode !== 0) {
+        throw new Error(`horizon exited ${run.exitCode}: ${run.stderr.trim() || 'no stderr'}`);
+    }
+
+    // Collect digests written (or refreshed) during this run. The date comes from the
+    // FILENAME, not the run clock — Horizon names the digest for the date it finishes,
+    // which crosses UTC midnight when a long crawl runs late in the day (dogfood
+    // daily-ai-news-20260903: run started 23:35 UTC, digest written 00:03 UTC next day).
+    const langs = new Set(config.languages ?? ['zh', 'en']);
+    const summariesDir = join(dataDir, 'summaries');
+    const docs: Doc[] = [];
+    if (!(await fs.exists(summariesDir))) {
+        echoError(`horizon-ingest: no summaries dir at ${summariesDir} — emitting []`);
+    }
+    const digestRe = /^horizon-(\d{4}-\d{2}-\d{2})-([a-z-]+)\.md$/;
+    const entries = (await fs.exists(summariesDir)) ? await fs.readDir(summariesDir) : [];
+    for (const entry of entries) {
+        const match = entry.match(digestRe);
+        if (!match?.[1] || !match?.[2] || !langs.has(match[2])) continue;
+        const file = join(summariesDir, entry);
+        const stat = await fs.stat(file);
+        if (!stat || stat.mtimeMs < runStartedAt - 1000) continue; // stale file from an earlier run
+        docs.push(...digestToDocs(await fs.readFile(file), match[1], match[2]));
+    }
+    if (docs.length === 0) {
+        echoError(
+            `horizon-ingest: no fresh digest in ${summariesDir} (languages: ${[...langs].join(', ')}) — emitting []`,
+        );
+    }
+
+    const outDir = dirname(options.out);
+    if (outDir && outDir !== '.') await fs.ensureDir(outDir);
+    await atomicWriteJson(options.out, DocListSchema.parse(docs), fs);
+    return { docs };
+}
+
+export async function main(runner?: RunHorizon): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (err: unknown) {
+        echoError(`horizon-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('horizon-ingest failed: Missing required arguments: --in <config.json> --out <docs.json>');
+        return 1;
+    }
+    try {
+        const config = InputConfigSchema.parse(await readJsonFile(values.in));
+        await processIngestionIO({ out: values.out }, config, runner);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`horizon-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/ingestions/horizon-ingest/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/ingestions/last30days-ingest/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/last30days-ingest",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/ingestions/last30days-ingest/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "last30days-ingest",
+    "kind": "ingestion",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Wraps the last30days skill CLI (agent JSON contract) into Doc[] — one Doc per results[] item"
+}

package/plugins/ingestions/last30days-ingest/src/index.ts

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { z } from 'zod';
+
+/**
+ * Ingestion adapter over the last30days skill CLI (task 0089 contract).
+ * Shells out to `last30days.py --emit=json --json-profile=agent`, captures the
+ * agent JSON from `--output`, and maps `results[]` → `Doc[]` (one Doc per item).
+ * Without `SETUP_COMPLETE` the tool self-degrades to keyless web search — that
+ * degraded `Doc[]` is still valid output (exit 0).
+ */
+
+const InputConfigSchema = z.object({
+    topic: z.string().trim().min(1),
+    days: z.number().int().min(1).max(90).optional(),
+    web_backend: z.string().trim().min(1).optional(),
+    save_dir: z.string().trim().min(1).optional(),
+});
+
+export interface Last30DaysRunResult {
+    exitCode: number;
+    outputPath: string;
+    stderr: string;
+}
+
+/** Subprocess seam — tests inject a fake that writes a canned agent JSON. */
+export type RunLast30Days = (
+    config: z.infer<typeof InputConfigSchema>,
+    outputPath: string,
+) => Promise<Last30DaysRunResult>;
+
+export const defaultRunner: RunLast30Days = async (config, outputPath) => {
+    const skillDir = process.env.LAST30DAYS_SKILL_DIR ?? join(homedir(), '.agents', 'skills', 'last30days');
+    const argv = [
+        process.env.LAST30DAYS_PYTHON ?? 'python3',
+        join(skillDir, 'scripts', 'last30days.py'),
+        config.topic,
+        '--emit=json',
+        '--json-profile=agent',
+        '--output',
+        outputPath,
+    ];
+    if (config.days !== undefined) argv.push('--days', String(config.days));
+    if (config.web_backend !== undefined) argv.push('--web-backend', config.web_backend);
+    if (config.save_dir !== undefined) argv.push('--save-dir', config.save_dir);
+    const proc = Bun.spawnSync(argv, { cwd: skillDir, stdout: 'pipe', stderr: 'pipe' });
+    return { exitCode: proc.exitCode ?? 1, outputPath, stderr: proc.stderr.toString() };
+};
+
+const AgentJsonSchema = z.object({
+    schema_version: z.string().optional(),
+    window_days: z.number().optional(),
+    query: z.string().optional(),
+    results: z.array(z.record(z.string(), z.unknown())),
+});
+
+export function mapResultsToDocs(agentJson: unknown, topic: string): Doc[] {
+    const parsed = AgentJsonSchema.parse(agentJson);
+    const docs: Doc[] = [];
+    for (const item of parsed.results) {
+        try {
+            // Degraded/keyless mode uses the full URL as candidate_id — a 90-char URL id is
+            // brittle for downstream STORM citation (outline agents miscite them; dogfood
+            // run ff10095b failed assertKnownEvidence with 53 unknown IDs). Hash those.
+            const rawId =
+                typeof item.candidate_id === 'string' && item.candidate_id ? item.candidate_id : String(item.url ?? '');
+            const idSeed = rawId.startsWith('http')
+                ? createHash('sha256').update(rawId).digest('hex').slice(0, 16)
+                : rawId;
+            const doc: Doc = {
+                id: `last30days:${idSeed}`,
+                body: String(item.summary ?? ''),
+            };
+            if (typeof item.title === 'string' && item.title) doc.title = item.title;
+            if (typeof item.url === 'string' && item.url) doc.sourceUri = item.url;
+            doc.mediaType = 'text/markdown';
+            doc.metadata = {
+                topic,
+                window_days: parsed.window_days,
+                cluster: item.cluster,
+                source: item.source,
+                engagement: item.engagement,
+                relevance_score: item.relevance_score,
+                published_at: item.published_at,
+                schema_version: parsed.schema_version,
+            };
+            docs.push(doc);
+        } catch (err: unknown) {
+            echoError(
+                `last30days-ingest: skipping unparseable item (${err instanceof Error ? err.message : String(err)})`,
+            );
+        }
+    }
+    return DocListSchema.parse(docs);
+}
+
+export interface IngestionOptions {
+    out: string;
+}
+
+export async function processIngestionIO(
+    options: IngestionOptions,
+    config: z.infer<typeof InputConfigSchema>,
+    runner: RunLast30Days = defaultRunner,
+): Promise<{ docs: Doc[] }> {
+    const fs = createNodeFileSystem();
+    const outDir = dirname(options.out);
+    if (outDir && outDir !== '.') await fs.ensureDir(outDir);
+    const capturePath = join(outDir || '.', '.last30days-agent.json');
+    const run = await runner(config, capturePath);
+    if (run.exitCode !== 0) {
+        throw new Error(`last30days exited ${run.exitCode}: ${run.stderr.trim() || 'no stderr'}`);
+    }
+    const docs = mapResultsToDocs(await readJsonFile(capturePath), config.topic);
+    await atomicWriteJson(options.out, docs, fs);
+    return { docs };
+}
+
+export async function main(runner?: RunLast30Days): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (err: unknown) {
+        echoError(`last30days-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('last30days-ingest failed: Missing required arguments: --in <config.json> --out <docs.json>');
+        return 1;
+    }
+    try {
+        const config = InputConfigSchema.parse(await readJsonFile(values.in));
+        await processIngestionIO({ out: values.out }, config, runner);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`last30days-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/ingestions/last30days-ingest/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/kk/README.md

@@ -4,7 +4,7 @@ This directory is the **only** home for knowledge-kit agent capabilities (ADR-00
 It is a Claude Code / Superskill plugin, **not** a kk-core product plugin.
 
 | Path | Holds |
-|------|--------|
+| ------ | -------- |
 | `skills/` | Fat skills (`SKILL.md`) |
 | `commands/` | Thin slash-command wrappers |
 | `agents/` | Thin subagent wrappers (currently empty — see below) |
@@ -24,5 +24,5 @@ Install: `superskill install kk`.
 
 Capability files **omit a leading `kk-`**. `superskill install` prefixes the plugin name, so
 `skills/content-judge` installs as `kk:content-judge` (not `kk:kk-content-judge`). Same for `topic`,
-`storm-research`, `itc-generating`, and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
+`storm-research`, `itc-generating`, `explain-things` (via `/tell-me`), and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
 keeps its existing name — that is a workflow stem, not an installable agent capability.

package/plugins/kk/commands/tell-me.md

@@ -0,0 +1,16 @@
+---
+name: tell-me
+description: Explain the supplied or current topic with the smallest useful view; use ELI5 only when requested.
+argument-hint: "[topic] [--eli5]"
+allowed-tools: ["Skill"]
+---
+
+# tell-me
+
+Thin wrapper for the `explain-things` skill — all explanation and view-selection logic lives in
+the skill. Forward `$ARGUMENTS` unchanged, including empty arguments (the skill owns
+conversation-topic fallback).
+
+```text
+Skill(skill="kk:explain-things", args="$ARGUMENTS")
+```

package/plugins/kk/skills/explain-things/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: explain-things
+description: >-
+  Explain a topic, mechanism, or change with the smallest useful view — pseudocode,
+  call tree, component tree, file tree, Mermaid, diff, copyable block, or a focused
+  HTML artifact as a last resort. Use when the user says "explain", "tell me",
+  "how does X work", "ELI5", "like I'm 5", or "show me". Normal explanations are
+  concise inline views; the ELI5 register is opt-in. This is not for content authoring,
+  research, judging, publishing, or package/code review workflows.
+---
+
+# explain-things
+
+Explain the topic with the smallest useful view and only the prose needed to read it.
+Skip the preamble.
+
+## 1. Resolve the topic
+
+`$ARGUMENTS` carries an optional standalone `--eli5` modifier; strip it if present, and the
+remaining text is the explicit topic.
+
+- Explicit topic present → use it.
+- No explicit topic → use the current conversation topic.
+- Neither → stop before creating any artifact and say exactly:
+
+  > Provide a topic, for example `/tell-me <topic>`, or ask again while a topic is active.
+
+## 2. Choose the register
+
+- **Normal** (default): concise supporting prose beside one smallest useful inline view.
+- **ELI5**: picture-first, few words — use only when `--eli5` was passed or the user explicitly
+  asks for ELI5 / "like I'm 5". Lead with a familiar analogy; define unavoidable jargon.
+  ELI5 changes vocabulary and presentation, not the view catalog, and never forces HTML.
+
+## 3. Pick the smallest view
+
+Read `references/views.md` for the full decision catalog plus syntax examples. The default
+mapping:
+
+| Question shape | Smallest default view |
+| --- | --- |
+| Decision logic or algorithm | Pseudocode |
+| In-process call order | Call tree |
+| Multiple actors, timing, or data flow | Mermaid sequence/flow diagram |
+| UI composition, state, or ownership | Component tree |
+| File/module responsibility | Shallow file tree |
+| Change to an existing known shape | Focused `diff` block |
+| Mostly new, copyable target | Complete code/config block |
+| Dense spatial layout/comparison inline forms cannot express | One focused HTML artifact |
+
+Honor an explicitly requested format when feasible. Add a second view only when it answers a
+distinct missing question.
+
+## 4. Render
+
+Place the view directly beside only the prose it needs. If inline text, trees, code, diffs, and
+Mermaid cannot make the point, write one focused HTML file (match the product's look, real labels,
+desktop + mobile), then open it and report its path.

package/plugins/kk/skills/explain-things/references/views.md

@@ -0,0 +1,95 @@
+# View catalog
+
+Decision table first; syntax sketches below. Pick **one** view that makes the point (a second
+only for a distinct missing question). Provenance: distilled from `vendors/misc/eli5/SKILL.md`
+(picture-first few-words register) and `vendors/misc/show-me/SKILL.md` (view forms) — read them
+only to trace history; this file is the operative catalog.
+
+| Question shape | View |
+| --- | --- |
+| Decision logic or algorithm | Pseudocode |
+| In-process call order | Call tree |
+| Multiple actors, timing, or data flow | Mermaid sequence/flow diagram |
+| UI composition, state, or ownership | Component tree |
+| File/module responsibility, broad refactor | Shallow file tree |
+| Change to an existing known shape | Focused `diff` block |
+| Mostly new, copyable target | Complete code/config block |
+| Dense spatial layout/comparison the inline forms cannot express | One focused HTML artifact |
+
+## Syntax sketches
+
+Pseudocode — logic, not language:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+Call tree — who calls whom:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+Component tree — composition, with state/module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+File tree — responsibilities at one level:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+Mermaid — interaction/timing across actors:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+Diff — match its shape to the topic: component change, file-layout change, call-tree change, or
+state/control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+Copyable block — most of it is new, omitted context would hide ownership/order, or the user needs
+a target shape to paste:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1);
+  return `use the ${skillName} skill`;
+}
+```
+
+HTML artifact — last resort only. For a visual too dense for Mermaid (layout walk-through,
+before/after comparison, short slide deck): one focused HTML file matching the product's colors,
+type, spacing, and components; real labels and data; desktop + mobile. Open it and report the path.