learn-anything-cli 0.3.0 → 0.4.0-beta.1

package/dist/core/init.d.ts

@@ -16,6 +16,8 @@ export declare class InitCommand {
     private hasToolDir;
     private interactiveSelect;
     private generateSkillsForTool;
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    private readCompiledScript;
     private generateCommandsForTool;
 }
 export {};

package/dist/core/init.js

@@ -2,6 +2,7 @@ import path from 'path';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { AI_TOOLS, LEARN_DIR } from './config.js';
 import { isInteractive } from '../utils/interactive.js';
@@ -28,7 +29,14 @@ export class InitCommand {
         await FileSystemUtils.ensureDir(resolvedPath);
         // Create .learn/ directory in the target project
         const learnDir = path.join(resolvedPath, LEARN_DIR);
-        await FileSystemUtils.ensureDir(path.join(learnDir, 'topics'));
+        const topicsDir = path.join(learnDir, 'topics');
+        await FileSystemUtils.ensureDir(topicsDir);
+        // Run v0→v1 migration for any existing learning data
+        const { migrateAll } = await import('./learn-protocol/index.js');
+        const report = await migrateAll(topicsDir);
+        if (report.migratedCount > 0) {
+            console.log(chalk.green(m.init.migrationComplete(report.migratedCount)));
+        }
         console.log(chalk.bold(m.init.header));
         // Detect available tools
         const availableTools = await this.detectTools(resolvedPath);
@@ -119,8 +127,27 @@ export class InitCommand {
             const skillFile = path.join(skillDir, 'SKILL.md');
             const content = generateSkillContent(entry.template, VERSION);
             await FileSystemUtils.writeFile(skillFile, content);
+            const scriptsDir = path.join(skillDir, 'scripts');
+            // topic / explain / practice → utils.mjs + render.mjs
+            if (entry.dirName === 'learn-anything-topic' ||
+                entry.dirName === 'learn-anything-explain' ||
+                entry.dirName === 'learn-anything-practice') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'render.mjs'), this.readCompiledScript('render.mjs'));
+            }
+            // status → utils.mjs + status.mjs
+            if (entry.dirName === 'learn-anything-status') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'status.mjs'), this.readCompiledScript('status.mjs'));
+            }
+            // review → no scripts needed
         }
     }
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    readCompiledScript(filename) {
+        const scriptPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', filename);
+        return fs.readFileSync(scriptPath, 'utf-8');
+    }
     async generateCommandsForTool(resolvedPath, tool) {
         const adapter = CommandAdapterRegistry.get(tool.value);
         if (!adapter)

package/dist/core/learn-protocol/index.d.ts

@@ -0,0 +1,8 @@
+export type { ConceptStatus, Concept, Domain, StateV1, Detail, V0Concept, V0State, ParsedConcept, ParsedDomain, ParsedKnowledgeMap, } from './types.js';
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export type { StateV1Schema, ValidationResult } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+export type { MigrationResult, MigrationReport } from './migrate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/learn-protocol/index.js

@@ -0,0 +1,5 @@
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+//# sourceMappingURL=index.js.map

package/dist/core/learn-protocol/migrate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import type { V0State } from './types.js';
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export declare function isV0State(data: unknown): data is V0State;
+export interface MigrationResult {
+    migrated: boolean;
+    topic: string;
+    reason?: 'already_migrated' | 'already_v1' | 'not_v0' | 'no_state_yaml' | 'error';
+    error?: string;
+}
+export interface MigrationReport {
+    migratedCount: number;
+    skippedCount: number;
+    results: MigrationResult[];
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export declare function migrateV0ToV1(topicDir: string): Promise<MigrationResult>;
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export declare function migrateAll(baseDir: string): Promise<MigrationReport>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/core/learn-protocol/migrate.js

@@ -0,0 +1,259 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { parseKnowledgeMap } from './parser.js';
+import { generateSlug } from './slug.js';
+import { stateV1Schema } from './schema.js';
+import { render } from '../../scripts/render.mjs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+// ---- Public API ---------------------------------------------------------
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export function isV0State(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    // v0: has topic (string) and concepts (array), no version field
+    if (typeof obj.topic !== 'string' || !obj.topic)
+        return false;
+    if (!Array.isArray(obj.concepts))
+        return false;
+    if (obj.version !== undefined)
+        return false;
+    return true;
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export async function migrateV0ToV1(topicDir) {
+    const stateYamlPath = path.join(topicDir, 'state.yaml');
+    const knowledgeMapPath = path.join(topicDir, 'knowledge-map.md');
+    const stateJsonPath = path.join(topicDir, 'state.json');
+    const stateYamlBackup = path.join(topicDir, 'state.yaml.v0.bak');
+    const knowledgeMapBackup = path.join(topicDir, 'knowledge-map.md.v0.bak');
+    // 1. Skip if state.json already exists (already migrated)
+    if (await FileSystemUtils.fileExists(stateJsonPath)) {
+        try {
+            const existing = JSON.parse(await fs.readFile(stateJsonPath, 'utf-8'));
+            return {
+                migrated: false,
+                topic: existing.topic || path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+        catch {
+            return {
+                migrated: false,
+                topic: path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+    }
+    // 2. Check state.yaml exists
+    if (!(await FileSystemUtils.fileExists(stateYamlPath))) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'no_state_yaml',
+        };
+    }
+    // 3. Read and parse state.yaml
+    let v0Data;
+    try {
+        const yamlContent = await fs.readFile(stateYamlPath, 'utf-8');
+        v0Data = parseYaml(yamlContent);
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'error',
+            error: `Failed to parse state.yaml: ${err.message}`,
+        };
+    }
+    // 4. Check v0 format (has topic + concepts, no version field)
+    if (!isV0State(v0Data)) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'not_v0',
+        };
+    }
+    const v0State = v0Data;
+    // 7. Read and parse knowledge-map.md
+    let parsedMap;
+    if (await FileSystemUtils.fileExists(knowledgeMapPath)) {
+        try {
+            const kmContent = await fs.readFile(knowledgeMapPath, 'utf-8');
+            parsedMap = parseKnowledgeMap(kmContent);
+        }
+        catch (err) {
+            return {
+                migrated: false,
+                topic: v0State.topic,
+                reason: 'error',
+                error: `Failed to parse knowledge-map.md: ${err.message}`,
+            };
+        }
+    }
+    else {
+        // Without knowledge-map.md we can't build the hierarchy; skip
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: 'knowledge-map.md not found',
+        };
+    }
+    // 8. Merge: build a lookup from v0 path -> V0Concept
+    const conceptLookup = new Map();
+    for (const c of v0State.concepts) {
+        conceptLookup.set(c.path, c);
+    }
+    // 9. Build StateV1 from parsed hierarchy + v0 state data
+    const domains = parsedMap.domains.map((pd) => ({
+        name: pd.name,
+        slug: generateSlug(pd.name),
+        concepts: pd.concepts.map((pc) => {
+            const v0Path = `${pd.name}/${pc.name}`;
+            const v0Concept = conceptLookup.get(v0Path);
+            return {
+                name: pc.name,
+                slug: generateSlug(pc.name),
+                status: mapStatus(v0Concept?.status),
+                confidence: v0Concept?.confidence ?? 0,
+                practice_count: v0Concept?.practice_count ?? 0,
+                explain_count: v0Concept?.explain_count ?? 0,
+                last_explained: v0Concept?.last_session ?? null,
+                last_practiced: v0Concept?.last_practiced ?? null,
+                details: pc.children,
+            };
+        }),
+    }));
+    const stateV1 = {
+        version: 1,
+        topic: v0State.topic,
+        slug: generateSlug(v0State.topic),
+        created: v0State.created,
+        domains,
+    };
+    // 10. Validate the generated state against the schema
+    const validation = stateV1Schema.safeParse(stateV1);
+    if (!validation.success) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Generated state.json failed validation: ${validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,
+        };
+    }
+    // 11. Write state.json
+    try {
+        await FileSystemUtils.writeFile(stateJsonPath, JSON.stringify(stateV1, null, 2) + '\n');
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Failed to write state.json: ${err.message}`,
+        };
+    }
+    // 12. Create backup files, then remove originals
+    //     After migration, state.json is the single source of truth,
+    //     so the v0 files should not remain alongside it.
+    try {
+        await fs.copyFile(stateYamlPath, stateYamlBackup);
+        await fs.copyFile(knowledgeMapPath, knowledgeMapBackup);
+        await fs.rm(stateYamlPath, { force: true });
+        await fs.rm(knowledgeMapPath, { force: true });
+    }
+    catch (err) {
+        // Backup/cleanup failure is non-fatal — state.json was already written
+        console.error(`Warning: Failed to create backup files or clean up originals in ${topicDir}: ${err.message}`);
+    }
+    // 13. Regenerate knowledge-map.md from state.json (v1 format)
+    try {
+        const rendered = render(stateV1);
+        await FileSystemUtils.writeFile(knowledgeMapPath, rendered);
+    }
+    catch (err) {
+        // Render failure is non-fatal — migration itself succeeded
+        console.error(`Warning: Failed to regenerate knowledge-map.md in ${topicDir}: ${err.message}`);
+    }
+    return {
+        migrated: true,
+        topic: v0State.topic,
+    };
+}
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export async function migrateAll(baseDir) {
+    const results = [];
+    let entryNames;
+    try {
+        entryNames = await fs.readdir(baseDir);
+    }
+    catch {
+        // Directory doesn't exist — nothing to migrate
+        return { migratedCount: 0, skippedCount: 0, results: [] };
+    }
+    // Check each entry to see if it's a directory
+    const topicDirs = [];
+    for (const name of entryNames) {
+        const fullPath = path.join(baseDir, name);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (stat.isDirectory())
+                topicDirs.push(fullPath);
+        }
+        catch {
+            // Skip entries we can't stat
+        }
+    }
+    for (const dir of topicDirs) {
+        const result = await migrateV0ToV1(dir);
+        results.push(result);
+    }
+    const migratedCount = results.filter((r) => r.migrated).length;
+    const skippedCount = results.filter((r) => !r.migrated).length;
+    return { migratedCount, skippedCount, results };
+}
+// ---- Helpers -----------------------------------------------------------
+/** Map v0 status string to v1 ConceptStatus; default to 'unexplored'. */
+function mapStatus(status) {
+    if (status === 'in_progress' || status === 'needs_practice' || status === 'mastered') {
+        return status;
+    }
+    return 'unexplored';
+}
+//# sourceMappingURL=migrate.js.map

package/dist/core/learn-protocol/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Markdown parser for v0 knowledge-map.md.
+ *
+ * Uses unified + remark-parse to extract the hierarchical structure
+ * (domains -> concepts -> details) from the v0 knowledge-map format.
+ *
+ * This is used ONLY during migration (init/update), not at AI runtime.
+ *
+ * v0 knowledge-map.md format:
+ *
+ * ```md
+ * # Topic Name
+ * ## Domain 1
+ * - Concept A
+ *   - Detail A1
+ *   - Detail A2
+ * - Concept B
+ * ## Domain 2
+ * - Concept C
+ * ```
+ */
+import type { ParsedKnowledgeMap } from './types.js';
+/**
+ * Parse a v0 knowledge-map.md file content into a structured representation.
+ *
+ * The parser walks the mdast tree:
+ * - `# Title` (h1) -> topic name
+ * - `## DomainName` (h2) -> start a new domain
+ * - `- Concept` (top-level list item) -> add concept to current domain
+ * - `  - Detail` (nested list item) -> add detail to preceding concept
+ */
+export declare function parseKnowledgeMap(markdown: string): ParsedKnowledgeMap;
+//# sourceMappingURL=parser.d.ts.map

package/dist/core/learn-protocol/parser.js

@@ -0,0 +1,150 @@
+/**
+ * Markdown parser for v0 knowledge-map.md.
+ *
+ * Uses unified + remark-parse to extract the hierarchical structure
+ * (domains -> concepts -> details) from the v0 knowledge-map format.
+ *
+ * This is used ONLY during migration (init/update), not at AI runtime.
+ *
+ * v0 knowledge-map.md format:
+ *
+ * ```md
+ * # Topic Name
+ * ## Domain 1
+ * - Concept A
+ *   - Detail A1
+ *   - Detail A2
+ * - Concept B
+ * ## Domain 2
+ * - Concept C
+ * ```
+ */
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+// ---- Helpers -----------------------------------------------------------
+/** Recursively extract plain text from an AST node.
+ *
+ * Does NOT descend into nested `list` nodes — those are structural
+ * children (details under a concept) and should not contribute to
+ * the parent concept's name.
+ */
+function extractText(node) {
+    if (!node || typeof node !== 'object')
+        return '';
+    const n = node;
+    if (n.type === 'text' && typeof n.value === 'string') {
+        return n.value;
+    }
+    // Don't descend into lists: their content belongs to child concepts/details.
+    if (n.type === 'list')
+        return '';
+    if (Array.isArray(n.children)) {
+        return n.children.map(extractText).join('');
+    }
+    return '';
+}
+/** Narrow a child node to a specific type. */
+function isHeading(node, depth) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const n = node;
+    return n.type === 'heading' && n.depth === depth;
+}
+function isList(node) {
+    if (!node || typeof node !== 'object')
+        return false;
+    return node.type === 'list';
+}
+// ---- Public API ---------------------------------------------------------
+/**
+ * Parse a v0 knowledge-map.md file content into a structured representation.
+ *
+ * The parser walks the mdast tree:
+ * - `# Title` (h1) -> topic name
+ * - `## DomainName` (h2) -> start a new domain
+ * - `- Concept` (top-level list item) -> add concept to current domain
+ * - `  - Detail` (nested list item) -> add detail to preceding concept
+ */
+export function parseKnowledgeMap(markdown) {
+    const tree = unified().use(remarkParse).parse(markdown);
+    let topic = '';
+    const domains = [];
+    let currentDomain = null;
+    for (const node of tree.children) {
+        // # Title
+        if (isHeading(node, 1)) {
+            topic = extractText(node).trim();
+            continue;
+        }
+        // ## DomainName
+        if (isHeading(node, 2)) {
+            if (currentDomain)
+                domains.push(currentDomain);
+            currentDomain = {
+                name: extractText(node).trim(),
+                concepts: [],
+            };
+            continue;
+        }
+        // - Concept list (only process if we're inside a domain)
+        if (isList(node) && currentDomain) {
+            const list = node;
+            for (const item of list.children) {
+                processListItem(item, currentDomain, markdown);
+            }
+        }
+    }
+    // Push the last domain
+    if (currentDomain)
+        domains.push(currentDomain);
+    return { topic, domains };
+}
+/**
+ * Get list-item text via source position slicing.
+ *
+ * remark-parse consumes `__init__` as `<strong>init</strong>`, losing the
+ * underscores. By slicing the original markdown source at the paragraph's
+ * position offsets, we preserve the exact original text including any
+ * markdown formatting characters.
+ */
+function extractListItemText(item, source) {
+    for (const child of item.children) {
+        if (child.type === 'paragraph') {
+            const para = child;
+            const pos = para.position;
+            if (pos?.start && pos?.end) {
+                const start = pos.start;
+                const end = pos.end;
+                if (start.offset !== undefined && end.offset !== undefined) {
+                    return source.slice(start.offset, end.offset);
+                }
+            }
+        }
+    }
+    // Fallback to recursive text extraction
+    return extractText(item);
+}
+/** Strip common Markdown escape backslashes (e.g. `\_` → `_`, `\*` → `*`). */
+function unescapeMarkdown(text) {
+    return text.replace(/\\([\\`*{}[\]()#+\-.!_>~|])/g, '$1');
+}
+/** Extract a concept (and its optional details) from a list item. */
+function processListItem(item, domain, source) {
+    const name = unescapeMarkdown(extractListItemText(item, source).trim());
+    if (!name)
+        return;
+    const concept = { name, children: [] };
+    // Look for a nested list inside this list item (these are third-level details)
+    for (const child of item.children) {
+        if (isList(child)) {
+            for (const nestedItem of child.children) {
+                const detailName = unescapeMarkdown(extractListItemText(nestedItem, source).trim());
+                if (detailName) {
+                    concept.children.push(detailName);
+                }
+            }
+        }
+    }
+    domain.concepts.push(concept);
+}
+//# sourceMappingURL=parser.js.map

package/dist/core/learn-protocol/schema.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export declare const stateV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    topic: z.ZodString;
+    slug: z.ZodString;
+    created: z.ZodString;
+    domains: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        concepts: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            slug: z.ZodString;
+            status: z.ZodEnum<{
+                unexplored: "unexplored";
+                in_progress: "in_progress";
+                needs_practice: "needs_practice";
+                mastered: "mastered";
+            }>;
+            confidence: z.ZodNumber;
+            practice_count: z.ZodNumber;
+            explain_count: z.ZodNumber;
+            last_explained: z.ZodNullable<z.ZodString>;
+            last_practiced: z.ZodNullable<z.ZodString>;
+            details: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StateV1Schema = z.infer<typeof stateV1Schema>;
+export type ValidationResult = {
+    success: true;
+    data: StateV1Schema;
+} | {
+    success: false;
+    errors: z.ZodIssue[];
+};
+/** Validate an unknown value against the StateV1 schema. */
+export declare function validateStateV1(value: unknown): ValidationResult;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/learn-protocol/schema.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+// ---- Helpers -----------------------------------------------------------
+/** Datetime: YYYY-MM-DD or YYYY-MM-DD HH:mm:ss. */
+const dateTimeStr = () => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$/, 'Expected YYYY-MM-DD or YYYY-MM-DD HH:mm:ss');
+const nullableDateTimeStr = () => dateTimeStr().nullable();
+// ---- Concept schema ----------------------------------------------------
+const conceptSchema = z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+    status: z.enum(['unexplored', 'in_progress', 'needs_practice', 'mastered']),
+    confidence: z.number().min(0).max(1),
+    practice_count: z.number().int().min(0),
+    explain_count: z.number().int().min(0),
+    last_explained: nullableDateTimeStr(),
+    last_practiced: nullableDateTimeStr(),
+    details: z.array(z.string()),
+});
+// ---- Domain schema -----------------------------------------------------
+const domainSchema = z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+    concepts: z.array(conceptSchema),
+});
+// ---- Top-level StateV1 schema ------------------------------------------
+export const stateV1Schema = z.object({
+    version: z.literal(1),
+    topic: z.string().min(1),
+    slug: z.string().min(1),
+    created: dateTimeStr(),
+    domains: z.array(domainSchema),
+});
+// ---- Public API ---------------------------------------------------------
+/** Validate an unknown value against the StateV1 schema. */
+export function validateStateV1(value) {
+    const result = stateV1Schema.safeParse(value);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, errors: result.error.issues };
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/learn-protocol/slug.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate a stable kebab-case slug from a human-readable name.
+ *
+ * Rules (applied in order):
+ * 1. Replace `/` with `-`
+ * 2. Replace spaces with `-`
+ * 3. Remove characters that are NOT letters, digits, `-`, or `_`
+ * 4. Convert ASCII letters to lowercase; preserve non-ASCII characters
+ * 5. Collapse consecutive `-` into a single `-`
+ * 6. Trim leading / trailing `-`
+ */
+export declare function generateSlug(name: string): string;
+//# sourceMappingURL=slug.d.ts.map