okfy-ai 0.1.2 → 0.1.3

package/README.md

@@ -1,27 +1,59 @@
 # okfy-ai
 
-Turn docs into agent-readable Open Knowledge Format bundles.
+Turn docs into agent-readable Open Knowledge Format bundles, then serve them to Claude, Codex, Cursor, or any MCP client.
 
-## Install
+## Use With Agents
 
-Run without installing:
+Create a bundle:
 
 ```bash
-npx -y okfy-ai demo
+npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
+npx -y okfy-ai validate ./stripe-checkout-okf
+```
+
+Add it to an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "stripe-okf": {
+      "command": "npx",
+      "args": ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+    }
+  }
+}
 ```
 
-Or install globally:
+Ask your agent:
+
+```text
+Use the stripe-okf MCP server. Search for Checkout Sessions, read the most relevant concepts, inspect neighbors if needed, and explain the minimum backend flow with source URLs.
+```
+
+## Client Setup
+
+Claude Code:
 
 ```bash
-npm install -g okfy-ai
-okfy demo
+claude mcp add --transport stdio stripe-okf -- npx -y okfy-ai serve ./stripe-checkout-okf --mcp
 ```
 
-Requires Node.js 20+.
+Codex:
+
+```toml
+[mcp_servers.stripe_okf]
+command = "npx"
+args = ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+enabled = true
+```
 
-## Quick Start
+Claude Desktop, Cursor, and other `mcpServers` clients can use the JSON config above. More setup: https://github.com/0dust/OKFy/blob/main/docs/mcp-clients.md
 
-Convert a docs site into an OKF bundle:
+## Create Bundles
+
+Docs website:
 
 ```bash
 npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
@@ -29,37 +61,58 @@ npx -y okfy-ai validate ./stripe-checkout-okf
 npx -y okfy-ai inspect ./stripe-checkout-okf
 ```
 
-Serve it to an MCP client:
+Local Markdown:
 
 ```bash
-npx -y okfy-ai serve ./stripe-checkout-okf --mcp
+npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
+npx -y okfy-ai validate ./docs-okf
 ```
 
-## Local Markdown
+## Optional CLI Install
+
+You do not need global install for MCP configs. `npx -y okfy-ai ...` is usually better because the MCP client can launch okfy directly.
+
+Install only if you want shorter local commands:
 
 ```bash
-npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
-npx -y okfy-ai validate ./docs-okf
-npx -y okfy-ai serve ./docs-okf --mcp
+npm install -g okfy-ai
+okfy demo
 ```
 
-## MCP Config
+`okfy-ai` is the npm package name. `okfy` is the installed CLI command.
+
+Requires Node.js 20+.
+
+After installing, this MCP config is equivalent:
 
 ```json
 {
   "mcpServers": {
     "docs-okf": {
-      "command": "npx",
-      "args": ["-y", "okfy-ai", "serve", "./docs-okf", "--mcp"]
+      "command": "okfy",
+      "args": ["serve", "./docs-okf", "--mcp"]
     }
   }
 }
 ```
 
-Ask your agent:
+## Demo
 
-```text
-Use the docs-okf MCP server. Search for the relevant topic, read the best matching concepts, inspect neighbors if needed, and answer with source URLs.
+```bash
+npx -y okfy-ai demo
+```
+
+## No-Install MCP Config
+
+```json
+{
+  "mcpServers": {
+    "docs-okf": {
+      "command": "npx",
+      "args": ["-y", "okfy-ai", "serve", "./docs-okf", "--mcp"]
+    }
+  }
+}
 ```
 
 ## CLI Commands

package/dist/{chunk-C46QXZDU.js → chunk-6AP7LVJG.js}

@@ -455,6 +455,7 @@ async function crawlWebsite(options) {
   let skipped = 0;
   let failed = 0;
   const limit = pLimit(options.concurrency ?? 4);
+  options.onProgress?.({ type: "start", seed, maxPages, maxDepth });
   while (queue.length > 0 && visited.size < maxPages) {
     const batch = queue.splice(0, Math.min(queue.length, maxPages - visited.size));
     const results = await Promise.all(
@@ -464,9 +465,11 @@ async function crawlWebsite(options) {
           visited.add(item.url);
           if (!shouldVisit(item.url, seed, options, robots)) {
             skipped += 1;
+            options.onProgress?.({ type: "skipped", url: item.url, fetched: documents.length, queued: queue.length, maxPages });
             return;
           }
           planned.push(item.url);
+          options.onProgress?.({ type: "fetch", url: item.url, fetched: documents.length, queued: queue.length, maxPages });
           try {
             const fetched = await fetchText(item.url);
             const contentType = contentTypeFromHeader(fetched.contentType);
@@ -483,6 +486,7 @@ async function crawlWebsite(options) {
             };
             const doc = normalizeDocument(raw);
             if (!options.dryRun) documents.push(doc);
+            let discovered = 0;
             if (item.depth < maxDepth) {
               const links = options.dryRun && contentType === "html" ? extractRawHtmlLinks(fetched.text) : doc.links;
               for (const link of links) {
@@ -491,14 +495,24 @@ async function crawlWebsite(options) {
                   if (!queued.has(next) && shouldVisit(next, seed, options, robots) && queued.size < maxPages * 4) {
                     queued.add(next);
                     queue.push({ url: next, depth: item.depth + 1 });
+                    discovered += 1;
                   }
                 } catch {
                   skipped += 1;
                 }
               }
             }
+            options.onProgress?.({
+              type: "fetched",
+              url: item.url,
+              fetched: options.dryRun ? planned.length : documents.length,
+              queued: queue.length,
+              discovered,
+              maxPages
+            });
           } catch {
             failed += 1;
+            options.onProgress?.({ type: "failed", url: item.url, fetched: documents.length, queued: queue.length, maxPages });
           }
         })
       )
@@ -509,6 +523,7 @@ async function crawlWebsite(options) {
     return { pagesFetched: planned.length, skipped, failed, written: [], documents: [], dryRunPages: planned.slice(0, maxPages) };
   }
   if (documents.length === 0) throw new Error("Crawl generated zero concepts.");
+  options.onProgress?.({ type: "writing", concepts: documents.length, outDir: options.outDir });
   const written = await writeOkfBundle(documents, {
     outDir: options.outDir,
     title: options.title,

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   inspectBundle,
   serveMcpStdio,
   validateBundle
-} from "./chunk-C46QXZDU.js";
+} from "./chunk-6AP7LVJG.js";
 
 // src/cli.ts
 import fs from "fs";
@@ -15,6 +15,16 @@ import { Command } from "commander";
 import pc from "picocolors";
 var program = new Command();
 var packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+var isTty = Boolean(process.stderr.isTTY);
+function readPackageVersion() {
+  try {
+    const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 function collect(value, previous) {
   previous.push(value);
   return previous;
@@ -46,14 +56,50 @@ function printStats(stats) {
     for (const [domain, count] of Object.entries(stats.sourceDomains)) console.log(`  ${domain}: ${count}`);
   }
 }
-program.name("okfy").description("Turn docs into agent memory with Open Knowledge Format and MCP.").version("0.1.0");
+function printStatus(message) {
+  process.stderr.write(`${message}
+`);
+}
+function printCrawlProgress(event) {
+  const clear = isTty ? "\r\x1B[K" : "";
+  switch (event.type) {
+    case "start":
+      process.stderr.write(`okfy crawl: starting ${event.seed} (max ${event.maxPages} pages, depth ${event.maxDepth})
+`);
+      break;
+    case "fetch":
+      process.stderr.write(`${clear}okfy crawl: fetching ${event.fetched}/${event.maxPages}, queued ${event.queued}: ${event.url}`);
+      if (!isTty) process.stderr.write("\n");
+      break;
+    case "fetched":
+      process.stderr.write(
+        `${clear}okfy crawl: fetched ${event.fetched}/${event.maxPages}, queued ${event.queued}, discovered +${event.discovered}: ${event.url}
+`
+      );
+      break;
+    case "skipped":
+      process.stderr.write(`${clear}okfy crawl: skipped ${event.fetched}/${event.maxPages}, queued ${event.queued}: ${event.url}
+`);
+      break;
+    case "failed":
+      process.stderr.write(`${clear}okfy crawl: failed ${event.fetched}/${event.maxPages}, queued ${event.queued}: ${event.url}
+`);
+      break;
+    case "writing":
+      process.stderr.write(`${clear}okfy crawl: writing ${event.concepts} concepts to ${event.outDir}
+`);
+      break;
+  }
+}
+program.name("okfy").description("Turn docs into agent memory with Open Knowledge Format and MCP.").version(readPackageVersion());
 program.command("crawl").argument("<url>", "Docs URL to crawl").requiredOption("--out <dir>", "Output OKF bundle directory").option("--max-pages <n>", "Maximum pages", (value) => Number(value), 100).option("--max-depth <n>", "Maximum crawl depth", (value) => Number(value), 4).option("--include <pattern>", "Include glob or regex", collect, []).option("--exclude <pattern>", "Exclude glob or regex", collect, []).option("--same-origin", "Stay on same origin", true).option("--no-same-origin", "Allow cross-origin links").option("--respect-robots", "Respect robots.txt", true).option("--no-respect-robots", "Ignore robots.txt").option("--concurrency <n>", "Fetch concurrency", (value) => Number(value), 4).option("--title <name>", "Bundle title").option("--force", "Overwrite output directory", false).option("--dry-run", "List pages that would be crawled", false).option("--allow-private-network", "Allow localhost/private IP crawl targets", false).option("--stable-timestamps", "Use a deterministic timestamp in generated frontmatter", false).action(async (url, options) => {
   try {
     const result = await crawlWebsite({
       seedUrl: url,
       outDir: options.out,
       ...options,
-      timestamp: options.stableTimestamps ? "2026-06-14T00:00:00.000Z" : void 0
+      timestamp: options.stableTimestamps ? "2026-06-14T00:00:00.000Z" : void 0,
+      onProgress: printCrawlProgress
     });
     if (options.dryRun) {
       console.log("okfy crawl dry run");
@@ -75,6 +121,8 @@ program.command("crawl").argument("<url>", "Docs URL to crawl").requiredOption("
 });
 program.command("import").argument("<path>", "Local docs folder or file").requiredOption("--out <dir>", "Output OKF bundle directory").option("--source-name <name>", "Source name").option("--include <glob>", "Include glob", collect, []).option("--exclude <glob>", "Exclude glob", collect, []).option("--force", "Overwrite output directory", false).option("--stable-timestamps", "Use a deterministic timestamp in generated frontmatter", false).action(async (input, options) => {
   try {
+    printStatus(`okfy import: reading ${input}`);
+    printStatus(`okfy import: writing bundle to ${options.out}`);
     const result = await importLocal({
       inputPath: input,
       outDir: options.out,
@@ -85,19 +133,25 @@ program.command("import").argument("<path>", "Local docs folder or file").requir
     console.log(`Source: ${input}`);
     console.log(`Concepts: ${result.written.length} written`);
     console.log(`Output: ${options.out}`);
+    printStatus(`okfy import: done, wrote ${result.written.length} concepts`);
   } catch (error) {
     console.error(pc.red(error?.message ?? "Import failed."));
     process.exitCode = 1;
   }
 });
 program.command("validate").argument("<bundle>", "OKF bundle directory").option("--json", "Print JSON report", false).action(async (bundle, options) => {
+  printStatus(`okfy validate: checking ${bundle}`);
   const report = await validateBundle(bundle);
   printValidation(report, options.json);
+  printStatus(`okfy validate: ${report.valid ? "valid" : "invalid"}, ${report.conceptCount} concepts`);
   if (!report.valid) process.exitCode = 1;
 });
 program.command("inspect").argument("<bundle>", "OKF bundle directory").action(async (bundle) => {
   try {
-    printStats(await inspectBundle(bundle));
+    printStatus(`okfy inspect: reading ${bundle}`);
+    const stats = await inspectBundle(bundle);
+    printStats(stats);
+    printStatus(`okfy inspect: done, ${stats.conceptCount} concepts, ${stats.linkCount} links`);
   } catch (error) {
     console.error(pc.red(error?.message ?? "Inspect failed."));
     process.exitCode = 1;
@@ -114,7 +168,11 @@ program.command("serve").argument("<bundle>", "OKF bundle directory").option("--
     process.exitCode = 1;
     return;
   }
+  printStatus(`okfy serve: loading ${bundle}`);
+  printStatus(`okfy serve: starting MCP stdio server "${options.name}"`);
   await serveMcpStdio({ bundleDir: bundle, name: options.name, maxResultChars: options.maxResultChars });
+  printStatus("okfy serve: ready on stdio (stdout is reserved for MCP JSON-RPC)");
+  printStatus("okfy serve: tools bundle_summary, search_concepts, read_concept, get_neighbors, list_types, list_tags");
 });
 function resolveDemoBundle() {
   const relativeBundle = "examples/bundles/okfy-docs";
@@ -137,7 +195,7 @@ program.command("demo").description("Run offline demo against committed example
   console.log("MCP config:");
   console.log(
     JSON.stringify(
-      { mcpServers: { "okfy-docs": { command: "npx", args: ["okfy-ai", "serve", bundle, "--mcp"] } } },
+      { mcpServers: { "okfy-docs": { command: "npx", args: ["-y", "okfy-ai", "serve", bundle, "--mcp"] } } },
       null,
       2
     )

package/dist/index.d.ts

@@ -86,6 +86,42 @@ type CrawlOptions = {
     dryRun?: boolean;
     allowPrivateNetwork?: boolean;
     timestamp?: string;
+    onProgress?: (event: CrawlProgressEvent) => void;
+};
+type CrawlProgressEvent = {
+    type: "start";
+    seed: string;
+    maxPages: number;
+    maxDepth: number;
+} | {
+    type: "fetch";
+    url: string;
+    fetched: number;
+    queued: number;
+    maxPages: number;
+} | {
+    type: "fetched";
+    url: string;
+    fetched: number;
+    queued: number;
+    discovered: number;
+    maxPages: number;
+} | {
+    type: "skipped";
+    url: string;
+    fetched: number;
+    queued: number;
+    maxPages: number;
+} | {
+    type: "failed";
+    url: string;
+    fetched: number;
+    queued: number;
+    maxPages: number;
+} | {
+    type: "writing";
+    concepts: number;
+    outDir: string;
 };
 type CrawlResult = {
     pagesFetched: number;
@@ -176,4 +212,4 @@ type WriteBundleOptions = {
 };
 declare function writeOkfBundle(docs: NormalizedDocument[], options: WriteBundleOptions): Promise<string[]>;
 
-export { BundleSearch, type BundleStats, type Concept, type ContentType, type CrawlOptions, type CrawlResult, type ImportOptions, type KnowledgeGraph, type NormalizedDocument, type RawDocument, type SearchResult, type ServeOptions, type ValidationIssue, type ValidationReport, type WriteBundleOptions, buildGraph, crawlWebsite, createMcpServer, descriptionFromMarkdown, extractHeadings, extractInternalLinks, extractMarkdownLinks, importLocal, inferTags, inferType, inspectBundle, normalizeDocument, readBundle, readConceptFile, serveMcpStdio, validateBundle, writeOkfBundle };
+export { BundleSearch, type BundleStats, type Concept, type ContentType, type CrawlOptions, type CrawlProgressEvent, type CrawlResult, type ImportOptions, type KnowledgeGraph, type NormalizedDocument, type RawDocument, type SearchResult, type ServeOptions, type ValidationIssue, type ValidationReport, type WriteBundleOptions, buildGraph, crawlWebsite, createMcpServer, descriptionFromMarkdown, extractHeadings, extractInternalLinks, extractMarkdownLinks, importLocal, inferTags, inferType, inspectBundle, normalizeDocument, readBundle, readConceptFile, serveMcpStdio, validateBundle, writeOkfBundle };

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   serveMcpStdio,
   validateBundle,
   writeOkfBundle
-} from "./chunk-C46QXZDU.js";
+} from "./chunk-6AP7LVJG.js";
 export {
   BundleSearch,
   buildGraph,

package/docs/mcp-clients.md

@@ -3,19 +3,23 @@
 okfy exposes OKF bundles through a local stdio MCP server:
 
 ```bash
-npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+okfy serve ./tmp/okfy-docs --mcp
 ```
 
-Use stdio for local bundles. MCP stdio means the client launches `okfy` as a subprocess, sends JSON-RPC messages on stdin, and reads JSON-RPC responses on stdout. okfy logs should go to stderr.
+Shell examples assume `npm install -g okfy-ai`, then the `okfy` CLI command.
+
+MCP config examples use `npx -y okfy-ai` by default. That is normal for stdio MCP servers because the MCP client can launch the npm package without requiring a global install.
+
+Use stdio for local bundles. MCP stdio means the client launches a local command as a subprocess, sends JSON-RPC messages on stdin, and reads JSON-RPC responses on stdout. okfy logs should go to stderr.
 
 ## Prepare a Bundle
 
 Offline fixture:
 
 ```bash
-npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force
-npx -y okfy-ai validate ./tmp/okfy-docs
-npx -y okfy-ai inspect ./tmp/okfy-docs
+okfy import ./examples/local-markdown --out ./tmp/okfy-docs --force
+okfy validate ./tmp/okfy-docs
+okfy inspect ./tmp/okfy-docs
 ```
 
 Expected output:
@@ -29,15 +33,22 @@ Broken links: 0
 Docs-site crawl:
 
 ```bash
-npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
-npx -y okfy-ai validate ./stripe-checkout-okf
-npx -y okfy-ai serve ./stripe-checkout-okf --mcp
+okfy crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
+okfy validate ./stripe-checkout-okf
+okfy serve ./stripe-checkout-okf --mcp
 ```
 
 ## Claude Code
 
 Add okfy as a local stdio server:
 
+```bash
+claude mcp add --transport stdio okfy-docs -- okfy serve ./tmp/okfy-docs --mcp
+claude mcp list
+```
+
+No-install equivalent:
+
 ```bash
 claude mcp add --transport stdio okfy-docs -- npx -y okfy-ai serve ./tmp/okfy-docs --mcp
 claude mcp list
@@ -85,9 +96,10 @@ Troubleshooting:
 
 - `spawn npx ENOENT`: install Node.js >=20 and ensure `npx` is on `PATH`.
 - Server pending: run `/mcp`; approve project-scoped `.mcp.json` if prompted.
-- Empty tools: run `npx -y okfy-ai validate ./tmp/okfy-docs`; invalid bundles should fail before serving.
+- Empty tools: run `okfy validate ./tmp/okfy-docs`; invalid bundles should fail before serving.
 - Output too large: lower `--max-result-chars`, or ask the agent to search before reading concepts.
 - Wrong bundle path: use an absolute path in config if client starts from another working directory.
+- Already installed globally: use `"command": "okfy"` and args `["serve", "./tmp/okfy-docs", "--mcp"]`.
 
 ## Claude Desktop
 
@@ -133,6 +145,7 @@ Troubleshooting:
 - Server exits immediately: run exact command in terminal and fix bundle validation errors.
 - No okfy tools visible: restart Claude Desktop after config changes.
 - Relative path fails: use absolute bundle path.
+- Already installed globally: use `"command": "okfy"` and args `["serve", "/absolute/path/to/okfy/tmp/okfy-docs", "--mcp"]`.
 
 ## Codex
 
@@ -169,6 +182,13 @@ npx -y okfy-ai serve ./tmp/okfy-docs --mcp
 
 CLI alternative:
 
+```bash
+codex mcp add okfy_docs -- okfy serve ./tmp/okfy-docs --mcp
+codex mcp --help
+```
+
+No-install CLI alternative:
+
 ```bash
 codex mcp add okfy_docs -- npx -y okfy-ai serve ./tmp/okfy-docs --mcp
 codex mcp --help
@@ -204,6 +224,7 @@ Troubleshooting:
 - Tool timeout: increase `tool_timeout_sec` for large bundles.
 - Relative path wrong: set `cwd` or use absolute bundle path.
 - Need current server list: run `/mcp` in TUI.
+- Already installed globally: use `command = "okfy"` and `args = ["serve", "./tmp/okfy-docs", "--mcp"]`.
 
 ## Generic MCP stdio
 
@@ -255,6 +276,7 @@ Troubleshooting:
 - `tools/list` empty: confirm `okfy serve` was started with `--mcp`.
 - Search returns weak matches: run `okfy inspect` and verify titles, descriptions, and tags were generated.
 - Agent reads too much: ask it to call `search_concepts` first and `read_concept` with `max_chars`.
+- Already installed globally: use `"command": "okfy"` and args `["serve", "./tmp/okfy-docs", "--mcp"]`.
 
 ## Available okfy MCP Tools
 

package/examples/README.md

@@ -63,7 +63,7 @@ Purpose: deterministic offline input for `okfy import`.
 Source command:
 
 ```bash
-npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps
+okfy import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps
 ```
 
 Expected concept count:
@@ -81,14 +81,14 @@ valid
 Validate:
 
 ```bash
-npx -y okfy-ai validate ./tmp/okfy-docs
-npx -y okfy-ai inspect ./tmp/okfy-docs
+okfy validate ./tmp/okfy-docs
+okfy inspect ./tmp/okfy-docs
 ```
 
 Serve through MCP:
 
 ```bash
-npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+okfy serve ./tmp/okfy-docs --mcp
 ```
 
 Suggested agent questions:

package/examples/bundles/okfy-docs/guides/import-local-markdown.md

@@ -14,8 +14,8 @@ timestamp: "2026-06-14T00:00:00.000Z"
 Use `okfy import` when docs already live in a local project checkout, wiki export, Obsidian vault, or static-site source folder.
 
 ```bash
-npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force
-npx -y okfy-ai validate ./tmp/okfy-docs
+okfy import ./examples/local-markdown --out ./tmp/okfy-docs --force
+okfy validate ./tmp/okfy-docs
 ```
 
 Expected result:

package/examples/bundles/okfy-docs/guides/serve-over-mcp.md

@@ -15,7 +15,7 @@ timestamp: "2026-06-14T00:00:00.000Z"
 After generating an OKF bundle, serve it over stdio MCP:
 
 ```bash
-npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+okfy serve ./tmp/okfy-docs --mcp
 ```
 
 Agents should not read the whole bundle first. The efficient flow is:

package/examples/local-markdown/guides/import-local-markdown.md

@@ -3,8 +3,8 @@
 Use `okfy import` when docs already live in a local project checkout, wiki export, Obsidian vault, or static-site source folder.
 
 ```bash
-npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force
-npx -y okfy-ai validate ./tmp/okfy-docs
+okfy import ./examples/local-markdown --out ./tmp/okfy-docs --force
+okfy validate ./tmp/okfy-docs
 ```
 
 Expected result:

package/examples/local-markdown/guides/serve-over-mcp.md

@@ -3,7 +3,7 @@
 After generating an OKF bundle, serve it over stdio MCP:
 
 ```bash
-npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+okfy serve ./tmp/okfy-docs --mcp
 ```
 
 Agents should not read the whole bundle first. The efficient flow is:

package/examples/local-markdown/okfy-example.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommand": "npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps",
+  "sourceCommand": "okfy import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps",
   "expectedConceptCount": 9,
   "expectedValidationStatus": "valid",
   "suggestedAgentQuestions": [

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "okfy-ai",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Convert docs into Open Knowledge Format bundles and serve them to MCP agents.",
   "type": "module",
   "bin": {
-    "okfy": "dist/cli.js"
+    "okfy": "dist/cli.js",
+    "okfy-ai": "dist/cli.js"
   },
   "files": [
     "dist",
     "README.md",
     "LICENSE",
-    "assets/logo.svg",
+    "assets/logo-dark.png",
+    "assets/logo-light.png",
     "assets/demo.gif",
     "docs/mcp-clients.md",
     "examples"

package/assets/logo.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="720" height="220" viewBox="0 0 720 220" role="img" aria-labelledby="title desc">
-  <title id="title">okfy</title>
-  <desc id="desc">okfy wordmark with linked knowledge nodes</desc>
-  <rect width="720" height="220" rx="28" fill="#f7f5ef"/>
-  <g transform="translate(54 44)">
-    <path d="M34 28h74c22 0 40 18 40 40v20c0 22-18 40-40 40H34C12 128-6 110-6 88V68c0-22 18-40 40-40Z" fill="#20342d"/>
-    <circle cx="36" cy="78" r="18" fill="#d6f36a"/>
-    <circle cx="106" cy="58" r="12" fill="#f7f5ef"/>
-    <circle cx="108" cy="100" r="12" fill="#f7f5ef"/>
-    <path d="M52 73 94 61M53 84l43 13" stroke="#d6f36a" stroke-width="9" stroke-linecap="round"/>
-    <path d="M190 124V31h32v36h10l26-36h37l-35 46 38 47h-39l-28-36h-9v36h-32Zm123 0V31h77v27h-45v15h39v26h-39v25h-32Zm95 0 34-52-32-41h38l15 21 15-21h36l-33 43 38 50h-39l-19-26-18 26h-35Zm127 0V92l-36-61h37l16 32 17-32h35l-37 61v32h-32Z" fill="#20342d"/>
-  </g>
-  <text x="360" y="184" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="20" letter-spacing="1.5" fill="#5f5a4f">OPEN KNOWLEDGE FORMAT FOR AGENTS</text>
-</svg>