feat: update README and documentation for CLI-first workflow and agent instructions

Author: prasad-kumkar

README.md

@@ -2,11 +2,11 @@
 
 # *Contextful*
 
-**Context Management + Search Engine for Agentic AI.**
+**Local Context Management + Search Engine + Memory for Agentic AI.**
 
-Contextful is a runtime contextual layer & local search engine for agents that gives them one fast way to find, compress, cite, and remember project context. 
+Contextful is a runtime contextual layer and local search engine for agents that gives them one fast way to find, compress, cite, and remember project context.
 
-Available as a `cli` + MCP & Skill, it integrates seemlessly with Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, and Zed.
+Available as a CLI-first tool with an MCP runtime bridge and generated agent instructions, it integrates seamlessly with Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, and Zed.
 
 <img src="docs/supported.png" alt="Contextful screenshot" width="450px" style="border-radius: 20px;" />
 
@@ -15,9 +15,9 @@ Instead of making an agent read 40 files every session, Contextful indexes the p
 
 ## Why?
 
-Context has always been a bottleneck for agentic AI. Large context window models (eg. 1m tokens) are :
+Context has always been a bottleneck for agentic AI. Large context window models (for example, 1M tokens) are:
 1. Expensive and require significantly more compute & processing time.
-2. Halucinate & loose key information as context window fills up. 
+2. More likely to lose key information as the context window fills up.
 3. Most projects have millions of lines of code, but agents can only fit in limited tokens per context window.
 
 The current solution is to make the agent guess which files to read, then pay the token cost to read them every session. This is slow, expensive, and lossy.
@@ -26,7 +26,7 @@ Apart from this, agents have no way to store or share learnings across sessions.
 
 <img src="docs/context-window.png" alt="Contextful screenshot" width="450px" style="border-radius: 20px;" />
 
-I started developing Contextful to keep context window smaller by enabling efficient knowledge retrieval. We can index the project and return a ranked, cited, token-budgeted context pack, we can:
+I started developing Contextful to keep the context window smaller by enabling efficient knowledge retrieval. If we index the project and return a ranked, cited, token-budgeted context pack, we can:
 - **100x more efficient token usage:** stop paying tokens to re-read the same files.
 - **Fewer tool calls:** one context pack can replace dozens of grep, glob, and read-file calls.
 - **No lost context between sessions:** agents can store session learnings in an evidence-backed memory ledger.
@@ -65,15 +65,15 @@ Contextful is an MCP server, local indexer, and small CLI:
 
 - **MCP server:** the agent interface.
 - **Local daemon / watcher:** indexing, rebuilds, freshness, and future benchmarks.
-- **CLI (`cxf`):** human debugging, reports, memory writes, and local smoke tests.
+- **CLI (`cxf`):** human setup, indexing, search, memory writes, and local smoke tests.
 
 MCP is the right interface because tools, resources, and prompts are exactly what MCP standardizes. The agent asks for context; Contextful returns compact evidence.
 
 ## Install
 
 ```bash
-npx @inferensys/contextful index --workspace .
-npx @inferensys/contextful query "where is user auth handled" --workspace . --budget 2000
+npx @inferensys/contextful init --workspace .
+npx @inferensys/contextful search "where is user auth handled" --workspace . --budget 2000
 ```
 
 Run as an MCP server:
@@ -87,10 +87,10 @@ npx @inferensys/contextful server
 The primary binary is `cxf`; `contextful` is also provided as a readable alias.
 
 ```bash
+cxf init --workspace <path>
 cxf index --workspace <path> [--watch]
 cxf daemon --workspace <path>
-cxf query "<query>" --workspace <path> --budget 2000 --json
-cxf report --workspace <path> --format markdown|json|html
+cxf search "<query>" --workspace <path> --budget 2000 --json
 cxf memory add --workspace <path> --claim <text> --evidence <ref>
 cxf server
 ```
@@ -128,14 +128,17 @@ Codex:
 codex mcp add contextful -- npx -y @inferensys/contextful server
 ```
 
-## Viral Receipts
+## CLI-First Agent Flow
 
-Contextful reports should make the value visible:
+Use `cxf init` once per workspace. It indexes the project and writes `.contextful/AGENT_INSTRUCTIONS.md`, a compact skill-style guide that tells agents when to call `context_pack`, when to search more narrowly, and when memory writes are allowed.
 
-- "Context pack saved 18 tool calls."
-- "100k+ tokens avoided by not re-reading files."
-- "2x faster context gathering."
-- "3 session learnings reused from the memory ledger."
+Use `cxf search` when a human wants to test the same evidence pack an agent will receive:
+
+```bash
+cxf search "how does auth load user profiles?" --workspace . --budget 2000
+```
+
+The MCP server remains the agent interface. The CLI is for setup, inspection, and repeatable local tests.
 
 ## Privacy
 

docs/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Contextful | MCP Context Engine for Coding Agents</title>
+    <title>Contextful | Local Context Management + Search Engine + Memory for Coding Agents</title>
     <meta
       name="description"
       content="Contextful is a local-first MCP context management layer for AI coding agents. It gives Codex, Claude Code, Cursor, Windsurf, Copilot, VS Code, Cline, Roo, Continue, and Zed fast code search, context packs, graph context, and evidence-backed memory."
@@ -14,15 +14,15 @@
     />
     <link rel="canonical" href="https://inferensys.github.io/contextful/" />
     <meta property="og:type" content="website" />
-    <meta property="og:title" content="Contextful | MCP Context Engine for Coding Agents" />
+    <meta property="og:title" content="Contextful | Local Context Management + Search Engine + Memory for Coding Agents" />
     <meta
       property="og:description"
       content="Give AI coding agents one ranked, cited, token-budgeted context pack instead of dozens of repeated file reads."
     />
     <meta property="og:url" content="https://inferensys.github.io/contextful/" />
     <meta property="og:image" content="https://inferensys.github.io/contextful/cover.svg" />
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="Contextful | MCP Context Engine for Coding Agents" />
+    <meta name="twitter:title" content="Contextful | Local Context Management + Search Engine + Memory for Coding Agents" />
     <meta
       name="twitter:description"
       content="Local-first MCP code search, graph context, evidence packs, and memory for agentic AI development."
@@ -54,7 +54,10 @@
           "BM25 lexical search",
           "Typed graph tables for files, symbols, chunks, and edges",
           "Token-budgeted context_pack tool",
-          "Evidence-backed memory ledger"
+          "Evidence-backed memory ledger",
+          "Compatible with Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, Zed, and any MCP stdio client",
+          "Agentic memory",
+          "Context Management for AI coding agents",
         ]
       }
     </script>
@@ -530,10 +533,11 @@
     <main id="top">
       <section class="hero">
         <div class="shell">
-          <p class="eyebrow">Local-first MCP context management for agentic AI</p>
-          <h1>Contextful gives coding agents the project context they need at runtime.</h1>
+          <p class="eyebrow">grep isn't enough</p>
+          <h1>Give coding agents the context they need, efficiently.</h1>
           <p class="lead">
-            Contextful is a highly efficient context layer for Codex, Claude Code, Cursor, Windsurf, GitHub Copilot,
+            Contextful is a context layer management harness + search engine + cross-session memory for AI coding agents.
+            Available for Codex, Claude Code, Cursor, Windsurf, GitHub Copilot,
             VS Code, Cline, Roo Code, Continue, Zed, and any MCP-compatible coding tool. It indexes your workspace once,
             then returns ranked, cited, token-budgeted evidence packs instead of making agents re-read the same files in
             every session.
@@ -660,7 +664,8 @@ <h3>Token-budgeted evidence packs</h3>
           <h2>Built as the runtime layer agents actually use</h2>
           <p class="section-lead">
             Contextful is not a hosted code search product and not a vector-only RAG demo. It is a small local system:
-            a CLI for humans, an indexer for the workspace, a SQLite state store, and an MCP server for the agent.
+            a CLI for setup and search, an indexer for the workspace, a SQLite state store, generated agent instructions,
+            and an MCP server for runtime agent calls.
           </p>
           <div class="flow" aria-label="Contextful architecture flow">
             <div class="step">
@@ -805,10 +810,10 @@ <h3>Explain architecture paths</h3>
               </p>
             </article>
             <article class="tile">
-              <h3>Write better reports</h3>
+              <h3>Test retrieval before the agent uses it</h3>
               <p>
-                Export Contextful reports that show indexed files, language coverage, recent packs, stale memory warnings,
-                and estimated tool calls saved.
+                Run <code>cxf search</code> locally to inspect the same cited evidence pack the agent will receive through
+                MCP.
               </p>
             </article>
             <article class="tile">
@@ -893,13 +898,13 @@ <h2>Compatible with MCP-aware coding tools</h2>
         <div class="shell">
           <h2>Install Contextful</h2>
           <p class="section-lead">
-            The npm package ships the <code>cxf</code> CLI and the MCP server. Start by indexing one workspace, then add
-            the server to your agent client.
+            The npm package ships the <code>cxf</code> CLI and the MCP server. Start with <code>init</code>, which indexes
+            the workspace and writes <code>.contextful/AGENT_INSTRUCTIONS.md</code> for your coding agent.
           </p>
           <div class="commands">
-            <pre>npx @inferensys/contextful index --workspace .
-npx @inferensys/contextful query "where is auth handled" --workspace . --budget 2000
-npx @inferensys/contextful report --workspace . --format markdown</pre>
+            <pre>npx @inferensys/contextful init --workspace .
+npx @inferensys/contextful search "where is auth handled" --workspace . --budget 2000
+npx @inferensys/contextful memory add --workspace . --claim "..." --evidence file:src/example.ts:1-20</pre>
             <pre>codex mcp add contextful -- \
   npx -y @inferensys/contextful server
 
@@ -947,11 +952,11 @@ <h2>FAQ</h2>
               </p>
             </details>
             <details>
-              <summary>What makes context_pack different from search?</summary>
+              <summary>How should agents use Contextful?</summary>
               <p>
-                Search returns hits. <code>context_pack</code> returns a ready-to-use bundle: summary, citations, files,
-                symbols, graph paths, memory hits, confidence, and token estimate. It is designed to be the agent's first
-                retrieval call.
+                Agents should call <code>context_pack</code> before broad file exploration. Humans can run
+                <code>cxf search</code> to preview the same kind of ready-to-use bundle: summary, citations, files,
+                symbols, graph paths, memory hits, confidence, and token estimate.
               </p>
             </details>
             <details>

docs/llms.txt

@@ -11,12 +11,13 @@ CLI: cxf
 
 ## What Contextful Does
 
-Contextful indexes one workspace and returns ranked, cited, token-budgeted evidence packs through MCP tools. It helps Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, Zed, and other MCP clients find project context without repeatedly reading raw files.
+Contextful indexes one workspace and returns ranked, cited, token-budgeted evidence packs through the CLI and MCP tools. It helps Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, Zed, and other MCP clients find project context without repeatedly reading raw files.
 
 ## Key Features
 
 - MCP stdio server for coding agents.
-- CLI for indexing, querying, reports, memory writes, and local smoke tests.
+- CLI-first workflow for initialization, indexing, search, memory writes, and local smoke tests.
+- cxf init writes .contextful/AGENT_INSTRUCTIONS.md with skill-style instructions for coding agents.
 - Local SQLite state under .contextful/.
 - FTS5 and BM25 lexical search over code, docs, symbols, and memories.
 - Typed graph tables for files, chunks, symbols, graph nodes, graph edges, node props, and edge props.
@@ -37,8 +38,8 @@ Contextful indexes one workspace and returns ranked, cited, token-budgeted evide
 ## Install
 
 ```bash
-npx @inferensys/contextful index --workspace .
-npx @inferensys/contextful query "where is auth handled" --workspace . --budget 2000
+npx @inferensys/contextful init --workspace .
+npx @inferensys/contextful search "where is auth handled" --workspace . --budget 2000
 codex mcp add contextful -- npx -y @inferensys/contextful server
 ```
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inferensys/contextful",
   "version": "0.1.0",
-  "description": "Highly efficient context management for agentic AI: search, evidence packs, and memory for Claude Code, Codex, Cursor, Windsurf, and Copilot.",
+  "description": "CLI-first context engine for agentic AI: local code search, evidence packs, MCP runtime context, and memory for Claude Code, Codex, Cursor, Windsurf, and Copilot.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

src/cli.ts

@@ -2,12 +2,12 @@
 
 import process from "node:process";
 import { Command } from "commander";
+import { initWorkspace, renderInitSummary } from "./init.js";
 import { indexWorkspace, watchWorkspace } from "./indexer.js";
 import { writeLesson } from "./memory.js";
-import { generateReport, renderEvidencePackMarkdown, renderReport } from "./report.js";
-import { createContextPack, searchContext } from "./search.js";
+import { renderEvidencePackMarkdown } from "./report.js";
+import { createContextPack } from "./search.js";
 import { runMcpServer } from "./mcp-server.js";
-import { type ReportFormat } from "./types.js";
 
 const program = new Command();
 
@@ -16,6 +16,16 @@ program
   .description("Contextful: local-first context search, evidence packs, and memory for coding agents.")
   .version("0.1.0");
 
+program
+  .command("init")
+  .description("Initialize Contextful for a workspace and write agent instructions.")
+  .option("--workspace <path>", "Workspace path.", process.cwd())
+  .option("--json", "Print JSON instead of a human summary.")
+  .action(async (options: { workspace: string; json?: boolean }) => {
+    const result = await initWorkspace({ workspace: options.workspace });
+    process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderInitSummary(result));
+  });
+
 program
   .command("index")
   .description("Index a workspace into .contextful.")
@@ -41,37 +51,8 @@ program
     });
   });
 
-program
-  .command("query")
-  .description("Create an evidence pack for a query.")
-  .argument("<query>", "Query to answer from indexed context.")
-  .option("--workspace <path>", "Workspace path.", process.cwd())
-  .option("--budget <tokens>", "Approximate token budget.", parseInteger, 2000)
-  .option("--json", "Print JSON instead of Markdown.")
-  .action(async (query: string, options: { workspace: string; budget: number; json?: boolean }) => {
-    const pack = await createContextPack({ workspace: options.workspace, query, budget: options.budget });
-    process.stdout.write(options.json ? `${JSON.stringify(pack, null, 2)}\n` : renderEvidencePackMarkdown(pack));
-  });
-
-program
-  .command("search")
-  .description("Search indexed context without compiling a full evidence pack.")
-  .argument("<query>", "Search query.")
-  .option("--workspace <path>", "Workspace path.", process.cwd())
-  .option("--limit <count>", "Max hits.", parseInteger, 10)
-  .option("--kind <kind>", "all|code|docs|symbols|memory", "all")
-  .action(async (query: string, options: { workspace: string; limit: number; kind: "all" | "code" | "docs" | "symbols" | "memory" }) => {
-    process.stdout.write(`${JSON.stringify(await searchContext({ ...options, query }), null, 2)}\n`);
-  });
-
-program
-  .command("report")
-  .description("Generate a context report.")
-  .option("--workspace <path>", "Workspace path.", process.cwd())
-  .option("--format <format>", "markdown|json|html", "markdown")
-  .action(async (options: { workspace: string; format: ReportFormat }) => {
-    process.stdout.write(renderReport(await generateReport({ workspace: options.workspace }), parseReportFormat(options.format)));
-  });
+addEvidencePackCommand("search", "Search project context and return a token-budgeted evidence pack.");
+addEvidencePackCommand("query", "Alias for search.", true);
 
 const memory = program.command("memory").description("Manage evidence-backed agent memory.");
 
@@ -117,7 +98,16 @@ function parseInteger(value: string): number {
   return parsed;
 }
 
-function parseReportFormat(value: string): ReportFormat {
-  if (value === "markdown" || value === "json" || value === "html") return value;
-  throw new Error(`Unsupported report format: ${value}`);
+function addEvidencePackCommand(name: string, description: string, hidden = false): void {
+  program
+    .command(name, hidden ? { hidden: true } : undefined)
+    .description(description)
+    .argument("<query>", "Query to answer from indexed context.")
+    .option("--workspace <path>", "Workspace path.", process.cwd())
+    .option("--budget <tokens>", "Approximate token budget.", parseInteger, 2000)
+    .option("--json", "Print JSON instead of Markdown.")
+    .action(async (query: string, options: { workspace: string; budget: number; json?: boolean }) => {
+      const pack = await createContextPack({ workspace: options.workspace, query, budget: options.budget });
+      process.stdout.write(options.json ? `${JSON.stringify(pack, null, 2)}\n` : renderEvidencePackMarkdown(pack));
+    });
 }

src/index.ts

@@ -1,4 +1,5 @@
 export { indexWorkspace, watchWorkspace } from "./indexer.js";
+export { initWorkspace, renderInitSummary } from "./init.js";
 export { createContextPack, searchContext, searchCode, traceGraph, tracePath, impactAnalysis, whyChanged, getIndexStatus, classifyQuery } from "./search.js";
 export { writeLesson, recallMemory } from "./memory.js";
 export { generateReport, renderReport } from "./report.js";
@@ -13,3 +14,4 @@ export type {
   SearchHit,
   SearchIntent
 } from "./types.js";
+export type { InitResult } from "./init.js";