okfy-ai 0.1.4 → 0.2.0

package/README.md

@@ -4,21 +4,24 @@ Turn docs into agent-readable Open Knowledge Format v0.1-conformant bundles, the
 
 ## Use With Agents
 
-Create a bundle:
+Create a registered source and print a client-ready setup preview:
 
 ```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 init stripe https://docs.stripe.com/checkout --client generic --max-pages 100 --max-depth 4
 ```
 
-Add it to an MCP client:
+`init` prints the MCP launch command, client config, and a first prompt. It does not write client config files by default. The generated launch command will look like `npx -y okfy-ai serve stripe --mcp --auto-refresh`.
+
+The MCP server uses the cached local bundle immediately. When the source is stale, `--auto-refresh` refreshes it according to the source policy while exposing freshness metadata through `bundle_summary`.
+
+Add the source-backed server to an MCP client:
 
 ```json
 {
   "mcpServers": {
     "stripe-okf": {
       "command": "npx",
-      "args": ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+      "args": ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
     }
   }
 }
@@ -35,7 +38,8 @@ Use the stripe-okf MCP server. Search for Checkout Sessions, read the most relev
 Claude Code:
 
 ```bash
-claude mcp add --transport stdio stripe-okf -- npx -y okfy-ai serve ./stripe-checkout-okf --mcp
+npx -y okfy-ai init stripe https://docs.stripe.com/checkout --client claude-code
+claude mcp add --transport stdio stripe-okf -- npx -y okfy-ai serve stripe --mcp --auto-refresh
 ```
 
 Codex:
@@ -43,7 +47,7 @@ Codex:
 ```toml
 [mcp_servers.stripe_okf]
 command = "npx"
-args = ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+args = ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60
 enabled = true
@@ -51,9 +55,47 @@ enabled = true
 
 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
 
+If setup is not working, run:
+
+```bash
+npx -y okfy-ai doctor stripe --client codex
+```
+
+`doctor` checks the registered source, bundle validity, freshness, `npx` availability, generated command shape, MCP tool visibility, and JSON-RPC-clean stdout, then tells you the next repair command or config edit.
+
+## Keep Sources Fresh
+
+Registered sources are the local-first workflow for third-party docs sites that change over time:
+
+```bash
+npx -y okfy-ai add stripe https://docs.stripe.com/checkout --max-pages 100 --max-depth 4
+npx -y okfy-ai sources
+npx -y okfy-ai check stripe
+npx -y okfy-ai doctor stripe
+npx -y okfy-ai update stripe
+npx -y okfy-ai remove stripe
+npx -y okfy-ai serve stripe --mcp --auto-refresh
+```
+
+If you want registration plus client-specific setup artifacts, use `npx -y okfy-ai init stripe https://docs.stripe.com/checkout --client generic --max-pages 100 --max-depth 4`.
+
+By default, okfy stores registered sources under `~/.okfy`. Set `OKFY_HOME` to use a different local cache for CI, tests, or per-project isolation.
+
+Freshness is age-based. A registered bundle is fresh when it exists, validates, and was successfully refreshed within its configured max age. The default mode is `stale-while-refresh`: if the bundle is stale, MCP search and read tools keep serving the current cached bundle while a background refresh runs.
+
+Use blocking mode when you want the server to refresh before answering tool calls:
+
+```bash
+npx -y okfy-ai serve stripe --mcp --auto-refresh --refresh-mode blocking
+```
+
+Use `--refresh-mode off` when MCP serving should never trigger network fetches; you can still run `npx -y okfy-ai update stripe` manually.
+
 ## Create Bundles
 
-Docs website:
+The original crawl/import path still works for one-off snapshots and project-local bundles.
+
+Docs website snapshot:
 
 ```bash
 npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
@@ -68,6 +110,14 @@ npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --for
 npx -y okfy-ai validate ./docs-okf
 ```
 
+Serve an existing bundle path when you already manage the bundle yourself:
+
+```bash
+npx -y okfy-ai serve ./docs-okf --mcp
+```
+
+Direct bundle paths do not use source auto-refresh.
+
 ## 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.
@@ -88,9 +138,9 @@ After installing, this MCP config is equivalent:
 ```json
 {
   "mcpServers": {
-    "docs-okf": {
+    "stripe-okf": {
       "command": "okfy",
-      "args": ["serve", "./docs-okf", "--mcp"]
+      "args": ["serve", "stripe", "--mcp", "--auto-refresh"]
     }
   }
 }
@@ -107,9 +157,9 @@ npx -y okfy-ai demo
 ```json
 {
   "mcpServers": {
-    "docs-okf": {
+    "stripe-okf": {
       "command": "npx",
-      "args": ["-y", "okfy-ai", "serve", "./docs-okf", "--mcp"]
+      "args": ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
     }
   }
 }
@@ -118,11 +168,18 @@ npx -y okfy-ai demo
 ## CLI Commands
 
 ```bash
+okfy init <name> <url>
+okfy doctor <name>
+okfy add <name> <url>
+okfy sources
+okfy check <name-or-bundle>
+okfy update <name>
+okfy remove <name>
 okfy crawl <url> --out <dir>
 okfy import <path> --out <dir>
 okfy validate <bundle>
 okfy inspect <bundle>
-okfy serve <bundle> --mcp
+okfy serve <name-or-bundle> --mcp
 okfy demo
 ```
 
@@ -130,7 +187,7 @@ okfy demo
 
 | Tool | Purpose |
 | --- | --- |
-| `bundle_summary` | Show bundle stats and validation status. |
+| `bundle_summary` | Show bundle stats, validation status, and source freshness when available. |
 | `search_concepts` | Search concept previews by query, type, or tags. |
 | `read_concept` | Read one concept body, frontmatter, links, backlinks, and source. |
 | `get_neighbors` | Traverse outbound links and backlinks around a concept. |
@@ -140,8 +197,8 @@ okfy demo
 ## What okfy Generates
 
 ```text
-docs site or Markdown folder
-  -> OKF bundle: Markdown files + YAML frontmatter + links
+registered docs source or Markdown folder
+  -> local OKF bundle: Markdown files + YAML frontmatter + links
   -> MCP server: search_concepts, read_concept, get_neighbors
   -> source-backed agent answers
 ```