@telepat/ideon 0.1.0 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telepat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,7 +8,14 @@ ooooo oooooooooo.   oooooooooooo   .oooooo.   ooooo      ooo
 o888o o888bood8P'   o888ooooood8  `Y8bood8P'  o8o        `8
 ```
 
-# Ideon
+# AI Writer Extraordinaire
+
+[![CI](https://github.com/telepat-io/ideon/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/telepat-io/ideon/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/telepat-io/ideon/graph/badge.svg)](https://codecov.io/gh/telepat-io/ideon)
+[![npm version](https://img.shields.io/npm/v/%40telepat%2Fideon)](https://www.npmjs.com/package/@telepat/ideon)
+[![npm downloads](https://img.shields.io/npm/dm/%40telepat%2Fideon)](https://www.npmjs.com/package/@telepat/ideon)
+[![Docs](https://img.shields.io/badge/docs-live-1f6feb)](https://docs.telepat.io/ideon)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/telepat-io/ideon/blob/main/LICENSE)
 
 Ideon is a TypeScript CLI that turns an idea into one or more Markdown outputs, with optional generated images for article runs.
 
@@ -30,16 +37,16 @@ Prerequisites:
 - Node.js 20+
 - npm 10+
 
-Install dependencies:
+Install globally:
 
 ```bash
-npm install
+npm i -g @telepat/ideon
 ```
 
-Run the CLI in development mode:
+Verify installation:
 
 ```bash
-npm run dev -- --help
+ideon --help
 ```
 
 ## Getting Started
@@ -47,25 +54,25 @@ npm run dev -- --help
 1. Configure credentials interactively:
 
 ```bash
-npm run dev -- settings
+ideon settings
 ```
 
 2. Generate your first article:
 
 ```bash
-npm run dev -- write "How small editorial teams can productionize AI writing"
+ideon write "How small editorial teams can productionize AI writing"
 ```
 
 3. Generate multi-output runs:
 
 ```bash
-npm run dev -- write "How small editorial teams can productionize AI writing" --target article=1 --target x-post=2 --style professional
+ideon write "How small editorial teams can productionize AI writing" --target article=1 --target x-post=2 --style professional
 ```
 
 4. Run a safe pipeline dry run (no provider calls):
 
 ```bash
-npm run dev -- write --dry-run "How AI changes technical publishing"
+ideon write --dry-run "How AI changes technical publishing"
 ```
 
 ## Core Commands
@@ -85,7 +92,7 @@ ideon preview
 Serve the latest generated article locally with assets and open it in your browser:
 
 ```bash
-npm run preview
+ideon preview
 ```
 
 This launches the new React preview app (served from `dist/preview`) and the preview API server.
@@ -93,7 +100,7 @@ This launches the new React preview app (served from `dist/preview`) and the pre
 You can also preview a specific article and choose a port:
 
 ```bash
-npm run dev -- preview ./output/my-article.md --port 4173
+ideon preview ./output/my-article.md --port 4173
 ```
 
 If you are iterating on preview UI code in `src/preview-app`, rebuild client assets after UI changes:
@@ -136,6 +143,12 @@ npm run pricing:refresh
 - Start docs locally: `npm run docs:start`
 - Build docs: `npm run docs:build`
 
+Links:
+
+- GitHub repository: [telepat-io/ideon](https://github.com/telepat-io/ideon)
+- npm package: [@telepat/ideon](https://www.npmjs.com/package/@telepat/ideon)
+- Documentation site: [docs.telepat.io/ideon](https://docs.telepat.io/ideon)
+
 Key docs:
 
 - CLI commands: `docs-site/docs/reference/cli-reference.md`
@@ -146,4 +159,4 @@ Key docs:
 
 GitHub Pages URL:
 
-- `https://telepat-io.github.io/ideon/`
+- [https://docs.telepat.io/ideon](https://docs.telepat.io/ideon)

package/dist/ideon.js

@@ -36,11 +36,15 @@ var baseT2ISettingsSchema = z.object({
   modelId: z.string().default("black-forest-labs/flux-schnell"),
   inputOverrides: z.record(z.string(), z.unknown()).default({})
 });
+var notificationsSettingsSchema = z.object({
+  enabled: z.boolean().default(false)
+});
 var appSettingsSchema = z.object({
   model: z.string().default("moonshotai/kimi-k2.5"),
   modelSettings: modelSettingsSchema.default(modelSettingsSchema.parse({})),
   modelRequestTimeoutMs: z.number().int().positive().default(9e4),
   t2i: baseT2ISettingsSchema.default(baseT2ISettingsSchema.parse({})),
+  notifications: notificationsSettingsSchema.default(notificationsSettingsSchema.parse({})),
   markdownOutputDir: z.string().default("/output"),
   assetOutputDir: z.string().default("/output/assets"),
   contentTargets: z.array(contentTargetSchema).min(1).refine((targets) => targets.filter((target) => target.role === "primary").length === 1, {
@@ -57,6 +61,7 @@ var envSettingsSchema = z.object({
   maxTokens: z.number().int().positive().optional(),
   topP: z.number().min(0).max(1).optional(),
   modelRequestTimeoutMs: z.number().int().positive().optional(),
+  notificationsEnabled: z.boolean().optional(),
   markdownOutputDir: z.string().optional(),
   assetOutputDir: z.string().optional(),
   style: z.enum(writingStyleValues).optional(),
@@ -78,6 +83,19 @@ function parseNumber(value2) {
   const parsed = Number(value2);
   return Number.isFinite(parsed) ? parsed : void 0;
 }
+function parseBoolean(value2) {
+  if (!value2) {
+    return void 0;
+  }
+  const normalized = value2.trim().toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+  return void 0;
+}
 function readEnvSettings(env = process.env) {
   return envSettingsSchema.parse({
     openRouterApiKey: env.IDEON_OPENROUTER_API_KEY,
@@ -87,6 +105,7 @@ function readEnvSettings(env = process.env) {
     maxTokens: parseNumber(env.IDEON_MAX_TOKENS),
     topP: parseNumber(env.IDEON_TOP_P),
     modelRequestTimeoutMs: parseNumber(env.IDEON_MODEL_REQUEST_TIMEOUT_MS),
+    notificationsEnabled: parseBoolean(env.IDEON_NOTIFICATIONS_ENABLED),
     markdownOutputDir: env.IDEON_MARKDOWN_OUTPUT_DIR,
     assetOutputDir: env.IDEON_ASSET_OUTPUT_DIR,
     style: env.IDEON_STYLE,
@@ -896,6 +915,10 @@ function SettingsFlow({ initialSettings, initialSecrets, onDone }) {
         label: `LLM model: ${settings.model}`,
         value: "llm-model"
       },
+      {
+        label: `Notifications > OS notifications enabled: ${settings.notifications.enabled ? "true" : "false"}`,
+        value: "notifications-enabled"
+      },
       {
         label: `Temperature: ${settings.modelSettings.temperature}`,
         value: "temperature"
@@ -1018,6 +1041,9 @@ function handleMenuSelect(action, settings, secrets, setEditing, setShowModelSel
     case "llm-model":
       setEditing({ key: action, label: "LLM model", value: settings.model });
       return;
+    case "notifications-enabled":
+      setEditing({ key: action, label: "Notifications > OS notifications enabled (true|false)", value: String(settings.notifications.enabled) });
+      return;
     case "temperature":
       setEditing({ key: action, label: "Temperature", value: String(settings.modelSettings.temperature) });
       return;
@@ -1069,6 +1095,17 @@ function applyEdit(action, value2, settings, secrets, setSettings, setSecrets) {
     setSettings({ ...settings, model: value2.trim() || settings.model });
     return;
   }
+  if (action === "notifications-enabled") {
+    const parsed = parseBooleanOrFallback(value2, settings.notifications.enabled);
+    setSettings({
+      ...settings,
+      notifications: {
+        ...settings.notifications,
+        enabled: parsed
+      }
+    });
+    return;
+  }
   if (action === "temperature") {
     const nextTemperature = clampNumber2(parseNumberOrFallback(value2, settings.modelSettings.temperature), 0, 2);
     setSettings({
@@ -1147,6 +1184,16 @@ function parseNumberOrFallback(value2, fallback) {
 function clampNumber2(value2, minimum, maximum) {
   return Math.min(maximum, Math.max(minimum, value2));
 }
+function parseBooleanOrFallback(value2, fallback) {
+  const normalized = value2.trim().toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+  return fallback;
+}
 
 // src/config/secretStore.ts
 import keytar from "keytar";
@@ -3491,6 +3538,13 @@ async function resolveRunInput(input) {
     ...job?.settings ?? {},
     ...envSettings.model ? { model: envSettings.model } : {},
     ...envSettings.modelRequestTimeoutMs !== void 0 ? { modelRequestTimeoutMs: envSettings.modelRequestTimeoutMs } : {},
+    ...envSettings.notificationsEnabled !== void 0 ? {
+      notifications: {
+        ...savedSettings.notifications,
+        ...job?.settings?.notifications ?? {},
+        enabled: envSettings.notificationsEnabled
+      }
+    } : {},
     ...envSettings.temperature !== void 0 || envSettings.maxTokens !== void 0 || envSettings.topP !== void 0 ? {
       modelSettings: {
         ...savedSettings.modelSettings,
@@ -3909,9 +3963,9 @@ function buildUrlResolutionMessages(options) {
       role: "system",
       content: [
         "You are a web research assistant for editorial linking.",
-        "Use web search to find the best single URL for the requested expression in context.",
-        "Start with the exact expression as the search phrase before trying broader variants.",
-        "Reject results that do not directly match the expression and paragraph meaning.",
+        "Use web search to find the best single URL to attach as a link to the provided text in context.",
+        "Start with the exact input text as the search phrase before trying broader variants.",
+        "Reject results that do not directly match the topic and paragraph meaning.",
         "Prefer canonical, trustworthy, stable sources that match the paragraph intent.",
         'Return only one line: the selected URL, or "none" when no strong match exists.',
         "Do not return markdown, explanations, bullets, or extra text."
@@ -3922,15 +3976,12 @@ function buildUrlResolutionMessages(options) {
       content: [
         `Article title: ${options.articleTitle}`,
         `Article description: ${options.articleDescription}`,
-        `Exact expression token: "${options.expression}"`,
-        `Expression to link: ${options.expression}`,
+        `Text to add link to (input text): "${options.expression}"`,
         "",
         "Paragraph context:",
         options.paragraph,
         "",
         "Search the web and choose the best URL for this inline link in this context.",
-        "Use the exact expression first, then only accept close canonical variants when meaning is unchanged.",
-        'If search evidence does not clearly support this expression in this paragraph context, return "none".',
         'Output format: URL only, or "none".'
       ].join("\n")
     }
@@ -7688,6 +7739,76 @@ function withWriteResumeHint(message) {
   return `${trimmed} ${WRITE_RESUME_HINT}`;
 }
 
+// src/cli/notifications/osNotifier.ts
+import { spawn as spawn2 } from "child_process";
+var APP_NAME = "Ideon";
+var MAX_MESSAGE_LENGTH = 180;
+async function notifyWriteStarted(params) {
+  if (!params.enabled) {
+    return;
+  }
+  const title = params.runMode === "resume" ? `${APP_NAME}: Resumed article write` : `${APP_NAME}: Started article write`;
+  const message = truncateMessage(params.idea);
+  sendOsNotification(title, message);
+}
+async function notifyWriteSucceeded(params) {
+  if (!params.enabled) {
+    return;
+  }
+  const title = `${APP_NAME}: Article ready`;
+  const message = truncateMessage(`${params.title} (${params.slug})`);
+  sendOsNotification(title, message);
+}
+async function notifyWriteFailed(params) {
+  if (!params.enabled) {
+    return;
+  }
+  const title = `${APP_NAME}: Article write failed`;
+  const message = truncateMessage(params.message);
+  sendOsNotification(title, message);
+}
+async function notifyWriteCanceled(params) {
+  if (!params.enabled) {
+    return;
+  }
+  const title = `${APP_NAME}: Article write canceled`;
+  const message = truncateMessage(`Interrupted by ${params.signal}.`);
+  sendOsNotification(title, message);
+}
+function sendOsNotification(title, message) {
+  if (process.platform === "darwin") {
+    const escapedTitle = escapeAppleScript(title);
+    const escapedMessage = escapeAppleScript(message);
+    runCommand("osascript", ["-e", `display notification "${escapedMessage}" with title "${escapedTitle}"`]);
+    return;
+  }
+  if (process.platform === "linux") {
+    runCommand("notify-send", [title, message]);
+  }
+}
+function runCommand(command, args) {
+  try {
+    const child = spawn2(command, args, {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function escapeAppleScript(value2) {
+  return value2.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function truncateMessage(value2) {
+  const normalized = value2.trim();
+  if (normalized.length <= MAX_MESSAGE_LENGTH) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_MESSAGE_LENGTH - 3)}...`;
+}
+
 // src/cli/logging/plainRenderer.ts
 function formatDuration2(durationMs) {
   if (durationMs >= 1e3) {
@@ -7735,7 +7856,13 @@ function formatCost2(costUsd) {
 async function renderPlainPipeline(input, dryRun, enrichLinks2, runMode) {
   let previousStatuses = /* @__PURE__ */ new Map();
   let previousItemStatuses = /* @__PURE__ */ new Map();
+  const notificationsEnabled = input.config.settings.notifications.enabled;
   try {
+    await notifyWriteStarted({
+      enabled: notificationsEnabled,
+      idea: input.idea,
+      runMode
+    });
     const result = await runPipelineShell(input, {
       dryRun,
       enrichLinks: enrichLinks2,
@@ -7771,8 +7898,17 @@ async function renderPlainPipeline(input, dryRun, enrichLinks2, runMode) {
     console.log(`  duration_ms: ${result.analytics.summary.totalDurationMs}`);
     console.log(`  retries: ${result.analytics.summary.totalRetries}`);
     console.log(`  cost: ${formatCost2(result.analytics.summary.totalCostUsd)}`);
+    await notifyWriteSucceeded({
+      enabled: notificationsEnabled,
+      title: result.artifact.title,
+      slug: result.artifact.slug
+    });
   } catch (error) {
     const message = error instanceof Error ? withWriteResumeHint(error.message) : withWriteResumeHint("Pipeline failed.");
+    await notifyWriteFailed({
+      enabled: notificationsEnabled,
+      message
+    });
     console.error(`Pipeline failed: ${message}`);
     throw new ReportedError(message);
   }
@@ -8115,6 +8251,11 @@ function WriteApp({
     let mounted = true;
     void (async () => {
       try {
+        await notifyWriteStarted({
+          enabled: input.config.settings.notifications.enabled,
+          idea: input.idea,
+          runMode
+        });
         const runResult = await runPipelineShell(input, {
           dryRun,
           enrichLinks: enrichLinks2,
@@ -8129,6 +8270,11 @@ function WriteApp({
           return;
         }
         setResult(runResult);
+        await notifyWriteSucceeded({
+          enabled: input.config.settings.notifications.enabled,
+          title: runResult.artifact.title,
+          slug: runResult.artifact.slug
+        });
       } catch (error) {
         if (!mounted) {
           return;
@@ -8137,6 +8283,10 @@ function WriteApp({
         const messageWithResumeHint = withWriteResumeHint(normalizedError.message);
         setErrorMessage(messageWithResumeHint);
         onError(new Error(messageWithResumeHint));
+        await notifyWriteFailed({
+          enabled: input.config.settings.notifications.enabled,
+          message: messageWithResumeHint
+        });
       }
     })();
     return () => {
@@ -8191,6 +8341,10 @@ async function runWritePipeline(input, dryRun, enrichLinks2, runMode) {
     interruptHandled = true;
     void (async () => {
       try {
+        await notifyWriteCanceled({
+          enabled: input.config.settings.notifications.enabled,
+          signal
+        });
         await recordInterruptedWrite(signal);
       } finally {
         cleanupSignalHandlers();

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@telepat/ideon",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "CLI for generating rich articles and images from ideas.",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/telepat-io/ideon.git"
   },
-  "homepage": "https://telepat-io.github.io/ideon/",
+  "homepage": "https://docs.telepat.io/ideon",
   "bugs": {
     "url": "https://github.com/telepat-io/ideon/issues"
   },