playable-lessons 0.1.1 → 0.2.1

package/README.md

@@ -4,10 +4,10 @@ Turn educational source material into **playable interactive fiction**. Paste in
 
 It ships in two forms:
 
-- **Desktop app** (Electron + React) — the full authoring experience: AI generation pipeline, node-graph editor, live player, and exports. Aimed at non-technical authors (e.g. educators).
-- **CLI** (`playable-lessons`, on npm) — a headless tool for **validating and exporting** existing `.ink` files. Handy for scripts, CI, and batch export.
+- **Desktop app** (Electron + React) — the full authoring experience: AI generation with an interactive clarification step, a node-graph editor, live player, and exports. Aimed at non-technical authors (e.g. educators).
+- **CLI** (`playable-lessons`, on npm) — the same engine, headless: **generate**, **validate**, and **export**. Handy for scripts, CI, batch runs, and local/offline generation against Ollama.
 
-> **Note:** AI _generation_ currently lives in the desktop app only. The CLI does **not** generate stories or call any LLM — it validates and exports Ink you already have. (A headless `generate` command is on the roadmap.)
+The desktop app and the CLI share one generation pipeline; the app adds the interactive clarification step and visual editor on top.
 
 ---
 
@@ -19,6 +19,33 @@ It ships in two forms:
 npm install -g playable-lessons
 ```
 
+### Generate a story from source material
+
+```bash
+# Local + offline against Ollama (no API key needed):
+playable-lessons generate --input notes.md --provider ollama --model llama3.1:8b --output lesson/
+
+# Anthropic Claude (key from the environment):
+ANTHROPIC_API_KEY=sk-ant-... playable-lessons generate -i case-study.md -p claude -o lesson/
+
+# From a topic instead of a file, choosing formats:
+playable-lessons generate --topic "Phishing awareness for staff" -p openai -o lesson/ -f ink,html,json
+
+# Pipe source material via stdin:
+cat lecture.txt | playable-lessons generate -o lesson/ -p ollama -m llama3.1:8b
+```
+
+Provider selection and API keys:
+
+| Provider | `--provider` | Key (env var) | Notes |
+| --- | --- | --- | --- |
+| Claude | `claude` | `ANTHROPIC_API_KEY` | default model `claude-opus-4-8` |
+| OpenAI | `openai` | `OPENAI_API_KEY` | default model `gpt-4o` |
+| Ollama | `ollama` | none (or `OLLAMA_API_KEY`) | local by default; `--ollama-url` for remote |
+| Custom | `custom` | `PLAYABLE_LESSONS_API_KEY` / `OPENAI_API_KEY` | OpenAI-compatible; requires `--base-url` + `--model` |
+
+If `--provider` is omitted it's inferred from the environment (Claude → OpenAI → Ollama). Keys are read from env vars only — the CLI never touches the OS keychain (that's the desktop app). Other flags: `--mode`, `--length` (short/medium/long), `--tone`, `--protagonist`, `--answers`, `--title`. Run `playable-lessons generate --help` for all options.
+
 ### Validate an Ink file
 
 ```bash

package/out/cli/index.js

@@ -9,6 +9,67 @@ const helpers_1 = require("yargs/helpers");
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
 const storyExport_js_1 = require("../shared/storyExport.js");
+const generate_js_1 = require("../shared/generate.js");
+/** Pick a provider from the environment when --provider isn't given. */
+function resolveProviderFromEnv() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return 'claude';
+    if (process.env.OPENAI_API_KEY)
+        return 'openai';
+    return 'ollama';
+}
+/**
+ * Build a ProviderConfig from CLI flags + environment. API keys come from
+ * env vars (CI/headless-friendly), never the OS keychain (that's GUI-only).
+ */
+function buildCliConfig(o) {
+    const provider = o.provider || resolveProviderFromEnv();
+    switch (provider) {
+        case 'openai': {
+            const apiKey = process.env.OPENAI_API_KEY;
+            if (!apiKey)
+                throw new Error('OPENAI_API_KEY is not set');
+            return { provider, model: o.model || 'gpt-4o', apiKey };
+        }
+        case 'custom': {
+            if (!o.baseUrl)
+                throw new Error('--base-url is required for the custom provider');
+            if (!o.model)
+                throw new Error('--model is required for the custom provider');
+            return {
+                provider,
+                model: o.model,
+                baseUrl: o.baseUrl,
+                apiKey: process.env.PLAYABLE_LESSONS_API_KEY || process.env.OPENAI_API_KEY || ''
+            };
+        }
+        case 'ollama':
+            return {
+                provider,
+                model: o.model || 'llama3.1:8b',
+                ollamaUrl: o.ollamaUrl,
+                ollamaToken: process.env.OLLAMA_API_KEY || ''
+            };
+        case 'claude':
+        default: {
+            const apiKey = process.env.ANTHROPIC_API_KEY;
+            if (!apiKey)
+                throw new Error('ANTHROPIC_API_KEY is not set');
+            return { provider: 'claude', model: o.model || 'claude-opus-4-8', apiKey };
+        }
+    }
+}
+function slug(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'story';
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .scriptName('playable-lessons')
     .usage('$0 <command> [options]')
@@ -70,8 +131,97 @@ const storyExport_js_1 = require("../shared/storyExport.js");
         console.error('Export failed:', err instanceof Error ? err.message : err);
         process.exit(1);
     }
+})
+    .command('generate', 'Generate an Ink story from source material using AI', (yargs) => {
+    return yargs
+        .option('input', { alias: 'i', type: 'string', describe: 'Path to source material (text/markdown). Omit to use --topic or stdin.' })
+        .option('topic', { type: 'string', describe: 'A topic or brief to generate from (instead of --input)' })
+        .option('output', { alias: 'o', type: 'string', demandOption: true, describe: 'Output directory' })
+        .option('provider', { alias: 'p', type: 'string', describe: 'claude | openai | ollama | custom (default: inferred from env)' })
+        .option('model', { alias: 'm', type: 'string', describe: 'Model id (provider-specific default if omitted)' })
+        .option('base-url', { type: 'string', describe: 'Base URL for a custom OpenAI-compatible endpoint' })
+        .option('ollama-url', { type: 'string', default: 'http://localhost:11434', describe: 'Ollama base URL' })
+        .option('mode', { type: 'string', default: 'topic', describe: 'Input mode: topic | lesson | methodology | case-study | lecture-notes | scenario' })
+        .option('length', { alias: 'l', type: 'string', default: 'medium', describe: 'Story length: short | medium | long' })
+        .option('tone', { type: 'string', default: 'professional', describe: 'Narrative tone' })
+        .option('protagonist', { type: 'string', default: 'the reader', describe: 'Protagonist type' })
+        .option('answers', { type: 'string', describe: 'Optional answers to clarifying questions' })
+        .option('retries', { type: 'number', default: 3, describe: 'Max compile attempts, with AI-assisted fixes between them (raise for weaker local models)' })
+        .option('format', { alias: 'f', type: 'string', default: 'ink,html', describe: 'Output formats: ink, html, json' })
+        .option('title', { alias: 't', type: 'string', describe: 'Story title (defaults to the input/topic name)' });
+}, async (argv) => {
+    try {
+        // Resolve the source material: --input file, --topic string, or stdin.
+        let inputText = '';
+        let base = 'story';
+        if (argv.input) {
+            inputText = await (0, promises_1.readFile)(argv.input, 'utf-8');
+            base = (0, path_1.basename)(argv.input).replace(/\.[^.]+$/, '');
+        }
+        else if (argv.topic) {
+            inputText = argv.topic;
+            base = slug(argv.topic);
+        }
+        else {
+            inputText = await readStdin();
+        }
+        if (!inputText.trim()) {
+            throw new Error('No source material — provide --input <file>, --topic "<brief>", or pipe text via stdin');
+        }
+        const config = buildCliConfig({
+            provider: argv.provider,
+            model: argv.model,
+            baseUrl: argv['base-url'],
+            ollamaUrl: argv['ollama-url'] || 'http://localhost:11434'
+        });
+        console.error(`Generating with ${config.provider} (${config.model})…`);
+        const result = await (0, generate_js_1.generateInk)({
+            inputMode: argv.mode,
+            inputText,
+            storyLength: argv.length,
+            protagonistType: argv.protagonist,
+            tone: argv.tone,
+            answers: argv.answers
+        }, config, { log: (m) => console.error(m), maxCompileRetries: argv.retries });
+        const outputDir = argv.output;
+        await (0, promises_1.mkdir)(outputDir, { recursive: true });
+        const title = argv.title || base;
+        const formats = argv.format.split(',').map((f) => f.trim()).filter(Boolean);
+        if (!formats.includes('ink'))
+            formats.unshift('ink'); // always keep the source
+        for (const format of formats) {
+            switch (format) {
+                case 'ink': {
+                    const outPath = (0, path_1.join)(outputDir, `${base}.ink`);
+                    await (0, promises_1.writeFile)(outPath, result.inkSource);
+                    console.log(`Wrote ${outPath}`);
+                    break;
+                }
+                case 'json': {
+                    const outPath = (0, path_1.join)(outputDir, `${base}.ink.json`);
+                    await (0, promises_1.writeFile)(outPath, result.compiledJson);
+                    console.log(`Wrote ${outPath}`);
+                    break;
+                }
+                case 'html': {
+                    const html = await (0, storyExport_js_1.exportStandaloneHTML)(result.inkSource, title);
+                    const outPath = (0, path_1.join)(outputDir, `${base}.html`);
+                    await (0, promises_1.writeFile)(outPath, html);
+                    console.log(`Wrote ${outPath}`);
+                    break;
+                }
+                default:
+                    console.warn(`Unknown format: ${format}`);
+            }
+        }
+        console.log('Done.');
+    }
+    catch (err) {
+        console.error('Generation failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
 })
     .demandCommand(1, 'You must specify a command')
     .help()
-    .version('0.1.0')
+    .version('0.2.1')
     .parse();

package/out/shared/aiClient.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Provider-agnostic AI client, shared by the renderer and the CLI.
+ *
+ * Pure and config-driven: callers pass a ProviderConfig (no Zustand store, no
+ * DOM). Uses the global `fetch`/`AbortController`, available in both the
+ * browser (renderer) and Node 18+ (CLI).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBaseUrl = normalizeBaseUrl;
+exports.callAI = callAI;
+exports.listModels = listModels;
+exports.testConnection = testConnection;
+// AI generations can be slow, but should not hang forever.
+const REQUEST_TIMEOUT_MS = 120_000;
+async function fetchWithTimeout(url, options, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...options, signal: controller.signal });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error(`Request timed out after ${timeoutMs / 1000}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function anthropicHeaders(apiKey) {
+    return {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'anthropic-dangerous-direct-browser-access': 'true'
+    };
+}
+/** Bearer headers, omitting Authorization when no token is configured. */
+function bearerHeaders(token) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token)
+        headers['Authorization'] = `Bearer ${token}`;
+    return headers;
+}
+/** Strip trailing slashes so `${base}/chat/completions` is well-formed. */
+function normalizeBaseUrl(url) {
+    return url.trim().replace(/\/+$/, '');
+}
+const DEFAULT_OLLAMA_URL = 'http://localhost:11434';
+/** Send a chat completion to whichever provider the config selects. */
+async function callAI(messages, config) {
+    switch (config.provider) {
+        case 'claude':
+            return callClaude(messages, config.apiKey ?? '', config.model);
+        case 'openai':
+            return callOpenAICompatible(messages, config.apiKey ?? '', 'https://api.openai.com/v1', config.model);
+        case 'custom':
+            return callOpenAICompatible(messages, config.apiKey ?? '', normalizeBaseUrl(config.baseUrl ?? ''), config.model);
+        case 'ollama':
+        default:
+            return callOllama(messages, config.ollamaUrl ?? DEFAULT_OLLAMA_URL, config.model, config.ollamaToken ?? '');
+    }
+}
+async function callClaude(messages, apiKey, model) {
+    const systemMsg = messages.find((m) => m.role === 'system')?.content || '';
+    const nonSystemMessages = messages.filter((m) => m.role !== 'system');
+    const response = await fetchWithTimeout('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: anthropicHeaders(apiKey),
+        body: JSON.stringify({
+            model,
+            max_tokens: 8192,
+            system: systemMsg,
+            messages: nonSystemMessages.map((m) => ({ role: m.role, content: m.content }))
+        })
+    });
+    if (!response.ok) {
+        throw new Error(`Claude API error (${response.status}): ${await response.text()}`);
+    }
+    const data = await response.json();
+    const text = data?.content?.[0]?.text;
+    if (typeof text !== 'string')
+        throw new Error('Claude API returned an unexpected response shape');
+    return text;
+}
+/**
+ * Any OpenAI-compatible /chat/completions endpoint — OpenAI itself, plus custom
+ * gateways (OpenRouter, LiteLLM, vLLM, a remote Ollama, …) behind a bearer token.
+ */
+async function callOpenAICompatible(messages, apiKey, baseUrl, model) {
+    if (!baseUrl)
+        throw new Error('No base URL configured for the OpenAI-compatible endpoint');
+    const response = await fetchWithTimeout(`${baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: bearerHeaders(apiKey),
+        body: JSON.stringify({ model, messages, max_tokens: 8192 })
+    });
+    if (!response.ok) {
+        throw new Error(`API error (${response.status}): ${await response.text()}`);
+    }
+    const data = await response.json();
+    const content = data?.choices?.[0]?.message?.content;
+    if (typeof content !== 'string')
+        throw new Error('API returned an unexpected response shape');
+    return content;
+}
+async function callOllama(messages, url, model, token) {
+    const response = await fetchWithTimeout(`${normalizeBaseUrl(url)}/api/chat`, {
+        method: 'POST',
+        headers: bearerHeaders(token),
+        body: JSON.stringify({ model, messages, stream: false })
+    });
+    if (!response.ok) {
+        throw new Error(`Ollama error (${response.status}): ${await response.text()}`);
+    }
+    const data = await response.json();
+    const content = data?.message?.content;
+    if (typeof content !== 'string')
+        throw new Error('Ollama returned an unexpected response shape');
+    return content;
+}
+// ─── Model discovery & connection testing ───
+/** List available models for the configured provider. */
+async function listModels(config) {
+    switch (config.provider) {
+        case 'claude':
+            return listAnthropicModels(config.apiKey ?? '');
+        case 'openai':
+            return listOpenAICompatibleModels('https://api.openai.com/v1', config.apiKey ?? '');
+        case 'custom':
+            return listOpenAICompatibleModels(normalizeBaseUrl(config.baseUrl ?? ''), config.apiKey ?? '');
+        case 'ollama':
+        default:
+            return listOllamaModels(config.ollamaUrl ?? DEFAULT_OLLAMA_URL, config.ollamaToken ?? '');
+    }
+}
+async function listAnthropicModels(apiKey) {
+    const response = await fetchWithTimeout('https://api.anthropic.com/v1/models?limit=100', {
+        method: 'GET',
+        headers: anthropicHeaders(apiKey)
+    }, 30_000);
+    if (!response.ok)
+        throw new Error(`Claude API error (${response.status}): ${await response.text()}`);
+    const data = await response.json();
+    return (data?.data ?? []).map((m) => m.id).filter(Boolean);
+}
+async function listOpenAICompatibleModels(baseUrl, apiKey) {
+    if (!baseUrl)
+        throw new Error('No base URL configured');
+    const response = await fetchWithTimeout(`${baseUrl}/models`, {
+        method: 'GET',
+        headers: bearerHeaders(apiKey)
+    }, 30_000);
+    if (!response.ok)
+        throw new Error(`API error (${response.status}): ${await response.text()}`);
+    const data = await response.json();
+    return (data?.data ?? []).map((m) => m.id).filter(Boolean).sort();
+}
+async function listOllamaModels(url, token) {
+    const response = await fetchWithTimeout(`${normalizeBaseUrl(url)}/api/tags`, {
+        method: 'GET',
+        headers: bearerHeaders(token)
+    }, 30_000);
+    if (!response.ok)
+        throw new Error(`Ollama error (${response.status}): ${await response.text()}`);
+    const data = await response.json();
+    return (data?.models ?? []).map((m) => m.name).filter(Boolean);
+}
+/**
+ * Probe the configured endpoint + credentials by listing models. Doubles as the
+ * "Test connection" check and the source for "Refresh models".
+ */
+async function testConnection(config) {
+    try {
+        const models = await listModels(config);
+        return { ok: true, message: `Connected — ${models.length} model(s) available.`, models };
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : 'Connection failed', models: [] };
+    }
+}

package/out/shared/generate.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Headless story generation pipeline, shared by the renderer and the CLI.
+ *
+ * Unlike the renderer's interactive flow (which pauses to ask the user
+ * clarification questions), this runs end-to-end with no interaction:
+ * outline → Ink generation → review → compile (with AI-assisted fix retries).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractInk = extractInk;
+exports.generateInk = generateInk;
+const aiClient_js_1 = require("./aiClient.js");
+const prompts_js_1 = require("./prompts.js");
+const storyExport_js_1 = require("./storyExport.js");
+/** Pull Ink source out of an AI response — prefer a ```ink block, then any fence. */
+function extractInk(raw) {
+    const inkBlock = raw.match(/```ink\s*([\s\S]*?)```/);
+    if (inkBlock)
+        return inkBlock[1].trim();
+    const anyBlock = raw.match(/```\s*([\s\S]*?)```/);
+    if (anyBlock)
+        return anyBlock[1].trim();
+    return raw.trim();
+}
+/** Match a corrected ```ink block from a review/fix response (only `ink` fences). */
+function extractInkCorrection(raw) {
+    const m = raw.match(/```ink\s*([\s\S]*?)```/);
+    return m ? m[1].trim() : null;
+}
+async function generateInk(params, config, opts = {}) {
+    const log = opts.log ?? (() => { });
+    const call = opts.call ?? ((messages) => (0, aiClient_js_1.callAI)(messages, config));
+    const maxRetries = opts.maxCompileRetries ?? 3;
+    const mode = params.inputMode;
+    const length = params.storyLength || 'medium';
+    const protagonist = params.protagonistType || 'the reader';
+    const tone = params.tone || 'professional';
+    const answers = params.answers || '(no specific preferences provided — use sensible defaults)';
+    const inkSystem = prompts_js_1.PROMPTS.system + '\n\n' + prompts_js_1.PROMPTS.inkSyntaxRef;
+    // ─── Stage 1: Outline ───
+    log('[1/4] Generating story outline…');
+    const outlineRaw = await call([
+        { role: 'system', content: prompts_js_1.PROMPTS.system },
+        {
+            role: 'user',
+            content: prompts_js_1.PROMPTS.outline
+                .replace('{{inputMode}}', mode)
+                .replace('{{inputText}}', params.inputText)
+                .replace('{{storyLength}}', length)
+                .replace('{{answers}}', answers)
+                .replace('{{protagonistType}}', protagonist)
+                .replace('{{tone}}', tone)
+        }
+    ]);
+    // ─── Stage 2: Ink generation ───
+    log('[2/4] Generating Ink source…');
+    const inkRaw = await call([
+        { role: 'system', content: inkSystem },
+        {
+            role: 'user',
+            content: prompts_js_1.PROMPTS.inkGeneration
+                .replace('{{outline}}', outlineRaw)
+                .replace('{{inputMode}}', mode)
+                .replace('{{inputText}}', params.inputText)
+                .replace('{{storyLength}}', length)
+        }
+    ]);
+    let inkSource = extractInk(inkRaw);
+    // ─── Stage 3: Review pass ───
+    log('[3/4] Reviewing for errors and inconsistencies…');
+    const reviewRaw = await call([
+        { role: 'system', content: inkSystem },
+        { role: 'user', content: prompts_js_1.PROMPTS.review.replace('{{inkSource}}', inkSource) }
+    ]);
+    const corrected = extractInkCorrection(reviewRaw);
+    // Only accept the rewrite if it retains at least half the original's length
+    // (guards against a truncated/partial snippet).
+    if (corrected && corrected.length > inkSource.length * 0.5) {
+        inkSource = corrected;
+        log('Applied corrections from review.');
+    }
+    // ─── Stage 4: Compile, with AI-assisted fix retries ───
+    log('[4/4] Compiling Ink source…');
+    let current = inkSource;
+    for (let attempt = 1;; attempt++) {
+        try {
+            const compiledJson = await (0, storyExport_js_1.compileInk)(current);
+            log('Compiled successfully.');
+            return { inkSource: current, compiledJson, outlineRaw };
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (attempt >= maxRetries) {
+                throw new Error(`Failed to compile after ${maxRetries} attempt(s): ${errMsg}`);
+            }
+            log(`Compilation failed (attempt ${attempt}/${maxRetries}): ${errMsg}`);
+            log('Asking the model to fix it…');
+            const fixRaw = await call([
+                { role: 'system', content: inkSystem },
+                {
+                    role: 'user',
+                    content: `The following Ink source failed to compile with this error:\n\n${errMsg}\n\n` +
+                        `Here is the Ink source:\n\`\`\`ink\n${current}\n\`\`\`\n\n` +
+                        'Please fix the errors and return the complete corrected Ink source in a ```ink code block.'
+                }
+            ]);
+            const fixed = extractInkCorrection(fixRaw);
+            if (fixed)
+                current = fixed;
+        }
+    }
+}

package/out/shared/prompts.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPTS = void 0;
+exports.PROMPTS = {
+    system: `You are the Playable Lessons assistant, an AI that transforms educational source material into playable interactive fiction using the Ink scripting language.
+
+Your goals:
+- Create engaging, educational interactive stories from the provided source material
+- Ensure all generated Ink code is syntactically valid and compiles without errors
+- Preserve factual accuracy from the source material
+- Never invent facts about named real people or institutions
+- Create meaningful branching choices that explore different perspectives and outcomes
+- Track relevant variables (experience, trust, knowledge) to make the story feel responsive
+
+When generating Ink, follow these rules:
+- Always start with variable declarations (VAR), then a -> start divert to the first knot
+- The first knot MUST be named === start ===
+- Use === knot_name === for passages (knots)
+- Use = stitch_name for sub-sections within knots
+- Use * for once-only choices, + for sticky choices
+- Use -> knot_name for diverts
+- Use { variable > X: text } for conditional content
+- Use ~ variable = value for variable assignments
+- Always include a -> END or -> DONE to terminate paths
+- Use # IMAGE: and # TIMER: tags for Playable Lessons custom features`,
+    analysis: `Analyze the following source material provided in "{{inputMode}}" mode.
+
+Source material:
+"""
+{{inputText}}
+"""
+
+Extract and list:
+1. The main subject/theme
+2. Key concepts and decision points
+3. Potential protagonist(s) and setting
+4. Learning outcomes (what should the reader understand after playing?)
+5. Factual claims that must be preserved accurately
+6. Potential branching points where different choices could lead to different outcomes
+
+Provide your analysis in a clear, structured format.`,
+    clarification: `Based on this analysis of the source material:
+
+{{analysis}}
+
+The input mode is: {{inputMode}}
+
+Generate 3-5 clarification questions to ask the user before generating the story. Questions should cover:
+- Who is the protagonist? (generic professional / named character / "you" the reader)
+- What is the primary learning outcome?
+- What tone? (professional/realistic, light/exploratory, challenging/provocative)
+- Should there be a "best path" or are all paths equally valid?
+- Any specific constraints or requirements?
+
+Format each question as a numbered list item.`,
+    outline: `Create a detailed story outline for an interactive fiction based on this:
+
+Input mode: {{inputMode}}
+Source material: """{{inputText}}"""
+Story length: {{storyLength}} (short=~5 nodes, medium=~15, long=~30+)
+Protagonist type: {{protagonistType}}
+Tone: {{tone}}
+
+User's answers to clarification questions:
+{{answers}}
+
+Generate a JSON outline with this structure:
+\`\`\`json
+{
+  "nodes": [
+    { "id": "start", "title": "Opening Scene", "summary": "Brief description" }
+  ],
+  "edges": [
+    { "from": "start", "to": "next_node", "choiceText": "What the player clicks" }
+  ],
+  "variables": [
+    { "name": "experience", "type": "number", "initialValue": 0 }
+  ],
+  "canonPath": ["start", "node2", "node3", "best_ending"]
+}
+\`\`\`
+
+Ensure:
+- Every node is reachable from "start"
+- Every path reaches an ending node
+- Variables are used meaningfully to track decisions
+- The story has at least 2 distinct endings
+- The canon path represents the "ideal" learning path`,
+    inkGeneration: `Convert this story outline into valid Ink source code.
+
+Outline:
+{{outline}}
+
+Original source material (for factual accuracy):
+Input mode: {{inputMode}}
+"""{{inputText}}"""
+
+Target length: {{storyLength}}
+
+Requirements:
+- Begin with VAR declarations for all tracked variables
+- Each node from the outline becomes an === knot ===
+- Each edge becomes a choice (* [choice text])
+- Include variable assignments (~ var = val) where decisions affect state
+- Use conditional text { var > X: text } to make scenes respond to past choices
+- Every path must reach -> END
+- Write engaging, educational prose — not just placeholder text
+- Write ALL prose yourself. Do NOT copy any example or placeholder text from the
+  syntax reference verbatim (e.g. "[Write the opening scene here]"); those
+  bracketed placeholders show structure only — replace them with real content
+- Include at least one conditional branch that depends on a variable
+- Mark endings with a # ENDING: tag followed by a label (good/neutral/bad)
+
+Return ONLY the complete Ink source inside a \`\`\`ink code block.`,
+    review: `Review the following Ink source for errors, inconsistencies, dead ends, and unreachable nodes.
+
+\`\`\`ink
+{{inkSource}}
+\`\`\`
+
+Check for:
+1. Syntax errors (unclosed braces, missing diverts, invalid variable references)
+2. Dead ends (passages with no choices and no -> END/DONE)
+3. Unreachable nodes (knots that nothing diverts to)
+4. Variable inconsistencies (used but not declared, or declared but never used)
+5. Missing endings (paths that don't terminate)
+6. Narrative inconsistencies (contradictions, tone shifts)
+
+If you find issues, return the corrected complete Ink source in a \`\`\`ink code block.
+If the source is clean, respond with "No issues found."`,
+    inkSyntaxRef: `=== INK SYNTAX REFERENCE ===
+
+// Variable declarations (top of file), then divert to first knot
+VAR name = "value"
+VAR score = 0
+VAR has_key = false
+-> start
+
+// First knot MUST be named "start"
+// (bracketed text below = placeholders — replace with your own prose, do not copy)
+=== start ===
+[Write the opening scene here]
+* [First choice] -> next_scene
+
+// Other knots
+=== knot_name ===
+[Write the passage prose here]
+* [Choice text visible to player]
+    [Result prose shown after choosing]
+    -> next_knot
+* [Another choice]
+    -> another_knot
+
+// Stitches (sub-sections within a knot)
+=== knot ===
+= stitch_one
+[Stitch prose here]
+-> stitch_two
+= stitch_two
+[More stitch prose here]
+
+// Sticky choices (can be chosen repeatedly)
++ [Repeatable choice]
+
+// Conditional text
+{ score > 5:
+    You've done well.
+- else:
+    You need more experience.
+}
+
+// Inline conditional
+You feel {has_key: confident|nervous}.
+
+// Variable assignment
+~ score = score + 1
+~ has_key = true
+
+// Diverts
+-> knot_name
+-> END
+-> DONE
+
+// Tags (for Playable Lessons)
+# IMAGE: assets/images/scene.jpg
+# TIMER: 15
+# ENDING: good
+
+// Glue (prevents line break)
+Text<>
+<>more text on same line
+
+=== END ===`
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playable-lessons",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Interactive Fiction Authoring Tool for Education — Generate playable branching stories from source material using AI + Ink",
   "main": "./out/main/index.mjs",
   "scripts": {