hyperstack-core 1.5.1 → 1.5.3

package/README.md

@@ -1,6 +1,10 @@
 # hyperstack-core
 
-The Memory Hub for AI agents. Typed graph memory with episodic/semantic/working APIs, decision replay, utility-weighted edges, git-style branching, and agent identity. The only memory layer where agents can verify what they know, trace why they know it, and coordinate without an LLM in the loop. $0 per operation at any scale.
+**The Agent Provenance Graph for AI agents** — the only memory layer where agents can prove what they knew, trace why they knew it, and coordinate without an LLM in the loop. $0 per operation at any scale.
+
+*Timestamped facts. Auditable decisions. Deterministic trust. Build agents you can trust at $0/operation.*
+
+Current version: **v1.5.2**
 
 ```
 npm i hyperstack-core
@@ -31,11 +35,12 @@ import { HyperStackClient } from "hyperstack-core";
 const hs = new HyperStackClient({ apiKey: "hs_..." });
 
 // Store a decision with typed relations
-await hs.decide({
+await hs.store({
   slug: "use-clerk",
   title: "Use Clerk for auth",
   body: "Better DX, lower cost, native Next.js support",
-  affects: ["auth-api"],
+  cardType: "decision",
+  links: [{ target: "auth-api", relation: "affects" }],
 });
 
 // Store a blocker
@@ -53,10 +58,35 @@ const result = await hs.blockers("deploy-prod");
 // What breaks if auth changes?
 const impact = await hs.impact("use-clerk");
 // → [auth-api, deploy-prod, billing-v2]
+
+// Batch store
+await hs.bulkStore([{ slug: "p1", title: "Project A", body: "..." }, { slug: "p2", title: "Project B", body: "..." }]);
+
+// Agentic routing (deterministic, no LLM)
+const canDo = await hs.can({ query: "what breaks if auth changes?", slug: "auth-api" });
+const steps = await hs.plan({ goal: "add 2FA to auth-api" });
+
+// Parse markdown/logs into cards (CLI: npx hyperstack-core ingest)
+await hs.parse("# DECISIONS.md content", { source: "decisions" });
+
+// Ingest conversation transcript
+await hs.autoRemember("Alice is senior engineer. We decided Clerk for auth.");
+
+// Memory hub: working / semantic / episodic
+const cards = await hs.hsMemory({ surface: "semantic" });
 ```
 
 Typed relations, not text blobs. `task→blocks→deploy` is queryable. A paragraph in DECISIONS.md is not.
 
+**REST API:** Always use `X-API-Key`, never `Authorization: Bearer`:
+
+```bash
+curl -X POST "https://hyperstack-cloud.vercel.app/api/cards" \
+  -H "X-API-Key: hs_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"slug":"use-clerk","title":"Use Clerk","body":"Auth decision"}'
+```
+
 ---
 
 ## MCP — Works in Cursor, Claude Desktop, VS Code, Windsurf
@@ -77,7 +107,7 @@ Typed relations, not text blobs. `task→blocks→deploy` is queryable. A paragr
 }
 ```
 
-15 MCP tools: `hs_store`, `hs_search`, `hs_smart_search`, `hs_decide`, `hs_commit`, `hs_feedback`, `hs_blockers`, `hs_graph`, `hs_impact`, `hs_recommend`, `hs_fork`, `hs_diff`, `hs_merge`, `hs_discard`, `hs_identify`, `hs_profile`, `hs_prune`, `hs_ingest`, `hs_inbox`, `hs_stats`
+10 MCP tools: `hs_store`, `hs_search`, `hs_get`, `hs_list`, `hs_graph`, `hs_blockers`, `hs_impact`, `hs_feedback`, `hs_fork`, `hs_identify`
 
 ---
 
@@ -112,6 +142,28 @@ GET /api/cards?workspace=X&memoryType=working&includeExpired=true
 
 ---
 
+## Card Fields
+
+| Field | Description |
+|-------|-------------|
+| `confidence` | 0.0–1.0 confidence score |
+| `truthStratum` | `draft` \| `hypothesis` \| `confirmed` |
+| `verifiedBy` | e.g. `"human:deeq"` |
+| `verifiedAt` | Auto-set server-side |
+| `memoryType` | `working` \| `semantic` \| `episodic` |
+| `ttl` | Working memory expiry (seconds) |
+| `sourceAgent` | Auto-stamped after `identify()` |
+
+---
+
+## Conflict Detection & Staleness
+
+**Conflict detection** — structural, no LLM. Auto-detects contradicting cards (e.g. same slug, conflicting `truthStratum`).
+
+**Staleness cascade** — upstream changes mark dependents stale. When a card is updated, linked cards get `isStale` until refreshed.
+
+---
+
 ## Decision Replay
 
 Reconstruct exactly what an agent knew when a decision was made.
@@ -135,7 +187,7 @@ Use cases: compliance audits, agent debugging, post-mortems.
 The graph gets smarter the more you use it. Report success/failure after every agent task.
 
 ```javascript
-// Report which cards helped the agent succeed
+// Report success/failure — updates utility scores on edges
 await hs.feedback({
   cardSlugs: ["use-clerk", "auth-api"],
   outcome: "success",
@@ -300,8 +352,8 @@ hs.merge(branch_workspace_id=branch["branchWorkspaceId"], strategy="branch-wins"
 ```
 
 ```python
-from hyperstack_langgraph import HyperStackMemory
-memory = HyperStackMemory(api_key="hs_...", workspace="my-project")
+from hyperstack_langgraph import HyperStackClient
+client = HyperStackClient(api_key="hs_...", workspace="my-project")
 ```
 
 ---
@@ -317,7 +369,7 @@ memory = HyperStackMemory(api_key="hs_...", workspace="my-project")
 | Provenance layer | ✅ | ❌ | ❌ | ❌ |
 | Time-travel | ✅ | ❌ | ❌ | ❌ |
 | Decision replay | ✅ | ❌ | ❌ | ❌ |
-| Memory Hub segmentation | ✅ | ❌ | ❌ | ❌ |
+| Three memory surfaces | ✅ | ❌ | ❌ | ❌ |
 | Self-hosted Docker | ✅ 1 command | ✅ complex | ✅ | ✅ |
 | Cross-tool MCP | ✅ Cursor+Claude | ❌ | ❌ | ❌ |
 | Cost per retrieval | **$0** | ~$0.002 LLM | ~$0.002 LLM | usage-based |
@@ -334,10 +386,10 @@ Mem0 finds "similar" cards. HyperStack finds **exactly** what blocks task #42.
 
 | Plan | Price | Cards | Features |
 |------|-------|-------|---------|
-| Free | $0 | 10 | Search only |
-| Pro | $29/mo | 100 | All modes + branching + identity + Memory Hub |
-| Team | $59/mo | 500 | All modes + webhooks + agent tokens |
-| Business | $149/mo | 2,000 | All modes + SSO + 20 members |
+| Free | $0 | 50 | ALL features — graph, impact, replay (no gate) |
+| Pro | $29/mo | 500+ | Branching, priority support |
+| Team | $59/mo | 500, 5 API keys | Everything in Pro + collaboration |
+| Business | $149/mo | 2,000, 20 members | Everything in Team + scale |
 | Self-hosted | $0 | Unlimited | Full feature parity |
 
 ---

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * hyperstack-core CLI
@@ -37,6 +37,7 @@ hyperstack-core — Typed graph memory for AI agents
 Commands:
   login               Authenticate via browser (OAuth device flow)
   logout              Remove saved credentials
+  quickstart          Scan current dir, ingest docs, show graph — 90 seconds to value
   init <template>     Initialize a project with a template
   ingest <path>       Auto-parse files into cards + edges (markdown/text/logs)
   search <query>      Search the knowledge graph
@@ -387,6 +388,116 @@ async function run() {
     return;
   }
 
+  // ─── Quickstart command ─────────────────────────────
+
+  if (command === "quickstart") {
+    console.log("\n🧠 HyperStack Quickstart\n");
+
+    // 1. Auth check
+    const qsApiKey = getApiKey();
+    if (!qsApiKey) {
+      console.log("  Not authenticated.\n");
+      console.log("  Option A: npx hyperstack-core login");
+      console.log("  Option B: export HYPERSTACK_API_KEY=hs_your_key");
+      console.log("  Get a free key: https://cascadeai.dev/hyperstack\n");
+      process.exit(1);
+    }
+    console.log("  ✅ Authenticated\n");
+
+    // 2. Scan current directory for ingestable files
+    const cwd = process.cwd();
+    const scanDirs = [cwd];
+    const docsDir = join(cwd, "docs");
+    if (existsSync(docsDir) && statSync(docsDir).isDirectory()) scanDirs.push(docsDir);
+
+    const found = [];
+    for (const dir of scanDirs) {
+      const entries = readdirSync(dir).filter((f) => /\.(md|txt)$/i.test(f));
+      for (const f of entries) {
+        const full = join(dir, f);
+        const stat = statSync(full);
+        const rel = dir === cwd ? f : `docs/${f}`;
+        found.push({ path: full, name: rel, size: stat.size });
+      }
+    }
+
+    if (!found.length) {
+      console.log("  No .md or .txt files found in current directory.\n");
+      console.log("  Try: npx hyperstack-core ingest <file>");
+      process.exit(0);
+    }
+
+    console.log("  Found files:\n");
+    for (const f of found) {
+      const kb = (f.size / 1024).toFixed(1);
+      console.log(`    📄 ${f.name} (${kb} KB)`);
+    }
+
+    const workspace = getFlag("workspace", "default");
+    console.log(`\n  Workspace: ${workspace}`);
+    console.log(`  Files: ${found.length}\n`);
+
+    // 3. Confirm (skip with --yes)
+    if (!args.includes("--yes") && !args.includes("-y")) {
+      const { createInterface } = await import("readline");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise((res) => {
+        rl.question("  Ingest these files? [Y/n] ", (a) => { rl.close(); res(a.trim().toLowerCase()); });
+      });
+      if (answer === "n" || answer === "no") {
+        console.log("\n  Cancelled.\n");
+        return;
+      }
+    }
+
+    // 4. Parse all files
+    console.log("\n  Parsing...\n");
+    let allCards = [];
+    let totalEdges = 0;
+
+    for (const f of found) {
+      const content = readFileSync(f.path, "utf-8");
+      const prefix = slugify(f.name.replace(/\.[^.]+$/, ""));
+      const result = parse(content, { prefix });
+      allCards.push(...result.cards);
+      totalEdges += result.edgeCount;
+      console.log(`    📄 ${f.name} → ${result.cards.length} cards, ${result.edgeCount} edges (${result.format})`);
+    }
+
+    if (!allCards.length) {
+      console.log("\n  No cards extracted. Files may be empty.\n");
+      return;
+    }
+
+    // 5. Store
+    console.log(`\n  Storing ${allCards.length} cards...`);
+    const qsClient = new HyperStackClient({ apiKey: qsApiKey, workspace });
+
+    const result = await qsClient.ingest(allCards, {
+      onProgress: () => process.stdout.write("."),
+    });
+
+    console.log("\n");
+    if (result.failed) {
+      console.log(`  ✅ ${result.stored} cards stored, ${result.failed} failed`);
+      for (const e of result.errors) console.log(`    ❌ [${e.slug}] ${e.error}`);
+    } else {
+      console.log(`  ✅ ${result.stored} cards stored, ${totalEdges} edges from ${found.length} file(s)`);
+    }
+
+    // 6. Next steps
+    const firstSlug = allCards[0]?.slug || "";
+    const searchTerm = allCards[0]?.title?.split(" ").slice(0, 3).join(" ") || "getting started";
+    console.log(`
+  Next steps:
+
+    npx hyperstack-core search "${searchTerm}"
+    npx hyperstack-core graph ${firstSlug} --depth 2 --reverse
+    npx hyperstack-core list
+`);
+    return;
+  }
+
   // ─── Ingest command ─────────────────────────────────
 
   if (command === "ingest") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperstack-core",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Typed graph memory for AI agents. Replace GOALS.md with queryable cards + relations. Works with OpenClaw, Claude Desktop, Cursor.",
   "type": "module",
   "main": "index.js",

package/src/parser.js

@@ -1,305 +1,307 @@
-/**
- * hyperstack-core parser
- *
- * Zero-dependency markdown/text/conversation → HyperStack cards + edges.
- * No LLM. Pure regex. Preserves document structure as typed graph edges.
- */
-
-function slugify(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 80);
-}
-
-function inferCardType(title, body) {
-  const text = `${title} ${body}`.toLowerCase();
-  if (/\b(decided?|chose|picked|selected|agreed|ruling)\b/.test(text)) return "decision";
-  if (/\b(todo|task|sprint|milestone|epic|ticket|backlog)\b/.test(text)) return "project";
-  if (/\b(always|never|prefer|convention|standard|rule|must)\b/.test(text)) return "preference";
-  if (/\b(step|process|how.to|guide|install|setup|deploy|workflow|tutorial)\b/.test(text)) return "workflow";
-  if (/\b(bug|fix|error|issue|patch|regression|incident)\b/.test(text)) return "event";
-  if (/\b(person|team|role|engineer|manager|founder)\b/.test(text)) return "person";
-  return "general";
-}
-
-function extractKeywords(title, body) {
-  const kw = new Set();
-  let m;
-  const backticks = /`([^`]+)`/g;
-  while ((m = backticks.exec(body)) !== null) kw.add(m[1].toLowerCase());
-  const mentions = /@(\w+)/g;
-  while ((m = mentions.exec(body)) !== null) kw.add(m[1].toLowerCase());
-  return [...kw].slice(0, 15);
-}
-
-function extractLinksFromBody(body) {
-  const links = [];
-
-  // Markdown links → related edges for internal refs
-  const mdLink = /\[([^\]]+)\]\(([^)]+)\)/g;
-  let m;
-  while ((m = mdLink.exec(body)) !== null) {
-    const href = m[2];
-    if (href.startsWith("#")) {
-      links.push({ target: slugify(href.slice(1)), relation: "related" });
-    } else if (/\.md(#|$)/.test(href)) {
-      const slug = slugify(href.replace(/\.md.*$/, "").replace(/^.*\//, ""));
-      if (slug) links.push({ target: slug, relation: "related" });
-    }
-  }
-
-  // Semantic patterns → typed edges
-  const patterns = [
-    { re: /depends\s+on\s+["`']?([\w][\w-]*)["`']?/gi, relation: "depends_on" },
-    { re: /blocked?\s+by\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocked_by" },
-    { re: /blocks?\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocks" },
-    { re: /decided\s+by\s+@?([\w][\w-]*)/gi, relation: "decided" },
-    { re: /assigned\s+to\s+@?([\w][\w-]*)/gi, relation: "assigned_to" },
-    { re: /owned?\s+by\s+@?([\w][\w-]*)/gi, relation: "owns" },
-  ];
-  for (const { re, relation } of patterns) {
-    while ((m = re.exec(body)) !== null) {
-      const target = slugify(m[1]);
-      if (target && target.length > 1) links.push({ target, relation });
-    }
-  }
-
-  return links;
-}
-
-// ─── Markdown Parser ──────────────────────────────────
-
-function parseMarkdown(content, prefix) {
-  const cards = [];
-  const headingRe = /^(#{1,6})\s+(.+)$/gm;
-  const headings = [];
-  let m;
-
-  while ((m = headingRe.exec(content)) !== null) {
-    headings.push({
-      level: m[1].length,
-      title: m[2].trim(),
-      pos: m.index,
-      contentStart: m.index + m[0].length,
-    });
-  }
-
-  if (headings.length === 0) return parsePlainText(content, prefix);
-
-  const usedSlugs = new Set();
-  function uniqueSlug(base) {
-    let slug = base;
-    let i = 2;
-    while (usedSlugs.has(slug)) { slug = `${base}-${i}`; i++; }
-    usedSlugs.add(slug);
-    return slug;
-  }
-
-  // Preamble before first heading
-  const preamble = content.slice(0, headings[0].pos).trim();
-  if (preamble.length > 30) {
-    const slug = uniqueSlug(prefix ? `${prefix}/intro` : "intro");
-    cards.push({
-      slug,
-      title: prefix ? `${prefix} — Introduction` : "Introduction",
-      body: preamble.slice(0, 1000),
-      cardType: "general",
-      keywords: extractKeywords("intro", preamble),
-      links: [],
-    });
-  }
-
-  // Parent stack for hierarchy: [{level, slug}]
-  const stack = [];
-  let edgeCount = 0;
-
-  for (let i = 0; i < headings.length; i++) {
-    const h = headings[i];
-    const bodyEnd = i + 1 < headings.length ? headings[i + 1].pos : content.length;
-    const body = content.slice(h.contentStart, bodyEnd).trim();
-
-    const baseSlug = slugify(h.title);
-    if (!baseSlug) continue;
-    const slug = uniqueSlug(prefix ? `${prefix}/${baseSlug}` : baseSlug);
-    const links = [];
-
-    // Hierarchy edge
-    while (stack.length > 0 && stack[stack.length - 1].level >= h.level) stack.pop();
-    if (stack.length > 0) {
-      links.push({ target: stack[stack.length - 1].slug, relation: "subtask_of" });
-      edgeCount++;
-    }
-    stack.push({ level: h.level, slug });
-
-    // Content-derived edges
-    const bodyLinks = extractLinksFromBody(body);
-    for (const l of bodyLinks) {
-      const target = prefix && !l.target.includes("/") ? `${prefix}/${l.target}` : l.target;
-      links.push({ target, relation: l.relation });
-      edgeCount++;
-    }
-
-    cards.push({
-      slug,
-      title: h.title,
-      body: body.slice(0, 1000),
-      cardType: inferCardType(h.title, body),
-      keywords: extractKeywords(h.title, body),
-      links,
-    });
-  }
-
-  return { cards, edgeCount, format: "markdown" };
-}
-
-// ─── Conversation Parser ──────────────────────────────
-
-const SPEAKER_RE = /^(User|Human|Assistant|AI|System|Bot)\s*:/i;
-
-function isConversationLog(text) {
-  const lines = text.split("\n");
-  let hits = 0;
-  for (const line of lines) {
-    if (SPEAKER_RE.test(line.trim())) hits++;
-    if (hits >= 2) return true;
-  }
-  return false;
-}
-
-function parseConversation(content, prefix) {
-  const cards = [];
-  const turnRe = /^(User|Human|Assistant|AI|System|Bot)\s*:/gim;
-  const starts = [];
-  let m;
-  while ((m = turnRe.exec(content)) !== null) {
-    starts.push({ index: m.index, speaker: m[1].toLowerCase(), after: m.index + m[0].length });
-  }
-
-  if (starts.length === 0) return parsePlainText(content, prefix);
-
-  let prevSlug = null;
-  let edgeCount = 0;
-
-  for (let i = 0; i < starts.length; i++) {
-    const t = starts[i];
-    const end = i + 1 < starts.length ? starts[i + 1].index : content.length;
-    const message = content.slice(t.after, end).trim();
-    if (!message) continue;
-
-    const idx = i + 1;
-    const slug = prefix ? `${prefix}/turn-${idx}` : `turn-${idx}`;
-    const snippet = message.slice(0, 60) + (message.length > 60 ? "..." : "");
-    const links = [];
-
-    if (prevSlug) {
-      links.push({ target: prevSlug, relation: "related" });
-      edgeCount++;
-    }
-
-    cards.push({
-      slug,
-      title: `[${t.speaker}] ${snippet}`,
-      body: message.slice(0, 1000),
-      cardType: "event",
-      keywords: [t.speaker, `turn-${idx}`],
-      links,
-      meta: { speaker: t.speaker, turnIndex: idx },
-    });
-
-    prevSlug = slug;
-  }
-
-  return { cards, edgeCount, format: "conversation" };
-}
-
-// ─── Plain Text Parser ────────────────────────────────
-
-function parsePlainText(content, prefix) {
-  const cards = [];
-  const paragraphs = content
-    .split(/\n\s*\n/)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 20);
-
-  if (paragraphs.length === 0) {
-    return { cards: [], edgeCount: 0, format: "text" };
-  }
-
-  const usedSlugs = new Set();
-  let prevSlug = null;
-  let edgeCount = 0;
-
-  for (let i = 0; i < paragraphs.length; i++) {
-    const para = paragraphs[i];
-    const firstLine = para.split(/[.\n]/)[0].trim().slice(0, 80) || `Section ${i + 1}`;
-    let slug = slugify(firstLine);
-    if (!slug) slug = `section-${i + 1}`;
-
-    if (prefix) slug = `${prefix}/${slug}`;
-    let unique = slug;
-    let n = 2;
-    while (usedSlugs.has(unique)) { unique = `${slug}-${n}`; n++; }
-    usedSlugs.add(unique);
-    slug = unique;
-
-    const links = [];
-    if (prevSlug) {
-      links.push({ target: prevSlug, relation: "related" });
-      edgeCount++;
-    }
-
-    cards.push({
-      slug,
-      title: firstLine,
-      body: para.slice(0, 1000),
-      cardType: inferCardType(firstLine, para),
-      keywords: extractKeywords(firstLine, para),
-      links,
-    });
-    prevSlug = slug;
-  }
-
-  return { cards, edgeCount, format: "text" };
-}
-
-// ─── Main Entry ───────────────────────────────────────
-
-/**
- * Parse any text into HyperStack cards + edges.
- * Auto-detects: markdown, conversation log, or plain text.
- *
- * @param {string} content — raw input
- * @param {object} [opts]
- * @param {string} [opts.prefix] — slug prefix (e.g. "readme", "docs/api")
- * @param {string} [opts.defaultType] — override cardType for "general" cards
- * @returns {{ cards: Array, edgeCount: number, format: string }}
- */
-function parse(content, opts = {}) {
-  if (!content || typeof content !== "string") {
-    return { cards: [], edgeCount: 0, format: "empty" };
-  }
-
-  const prefix = opts.prefix ? slugify(opts.prefix) : "";
-
-  let result;
-  if (isConversationLog(content)) {
-    result = parseConversation(content, prefix);
-  } else if (/^#{1,6}\s+/m.test(content)) {
-    result = parseMarkdown(content, prefix);
-  } else {
-    result = parsePlainText(content, prefix);
-  }
-
-  if (opts.defaultType) {
-    for (const card of result.cards) {
-      if (card.cardType === "general") card.cardType = opts.defaultType;
-    }
-  }
-
-  return result;
-}
-
-export { parse, parseMarkdown, parseConversation, parsePlainText, slugify, inferCardType };
-export default parse;
+/**
+ * hyperstack-core parser
+ *
+ * Zero-dependency markdown/text/conversation → HyperStack cards + edges.
+ * No LLM. Pure regex. Preserves document structure as typed graph edges.
+ */
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function inferCardType(title, body) {
+  const text = `${title} ${body}`.toLowerCase();
+  if (/\b(decided?|chose|picked|selected|agreed|ruling)\b/.test(text)) return "decision";
+  if (/\b(todo|task|sprint|milestone|epic|ticket|backlog)\b/.test(text)) return "project";
+  if (/\b(always|never|prefer|convention|standard|rule|must)\b/.test(text)) return "preference";
+  if (/\b(step|process|how.to|guide|install|setup|deploy|workflow|tutorial)\b/.test(text)) return "workflow";
+  if (/\b(bug|fix|error|issue|patch|regression|incident)\b/.test(text)) return "event";
+  if (/\b(person|team|role|engineer|manager|founder)\b/.test(text)) return "person";
+  return "general";
+}
+
+function extractKeywords(title, body) {
+  const kw = new Set();
+  let m;
+  const backticks = /`([^`]+)`/g;
+  while ((m = backticks.exec(body)) !== null) kw.add(m[1].toLowerCase());
+  const mentions = /@(\w+)/g;
+  while ((m = mentions.exec(body)) !== null) kw.add(m[1].toLowerCase());
+  return [...kw].slice(0, 15);
+}
+
+function extractLinksFromBody(body) {
+  const links = [];
+
+  // Markdown links → related edges for internal refs
+  const mdLink = /\[([^\]]+)\]\(([^)]+)\)/g;
+  let m;
+  while ((m = mdLink.exec(body)) !== null) {
+    const href = m[2];
+    if (href.startsWith("#")) {
+      links.push({ target: slugify(href.slice(1)), relation: "related" });
+    } else if (/\.md(#|$)/.test(href)) {
+      const slug = slugify(href.replace(/\.md.*$/, "").replace(/^.*\//, ""));
+      if (slug) links.push({ target: slug, relation: "related" });
+    }
+  }
+
+  // Semantic patterns → typed edges
+  const patterns = [
+    { re: /depends\s+on\s+["`']?([\w][\w-]*)["`']?/gi, relation: "depends_on" },
+    { re: /blocked?\s+by\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocked_by" },
+    { re: /blocks?\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocks" },
+    { re: /decided\s+by\s+@?([\w][\w-]*)/gi, relation: "decided" },
+    { re: /assigned\s+to\s+@?([\w][\w-]*)/gi, relation: "assigned_to" },
+    { re: /owned?\s+by\s+@?([\w][\w-]*)/gi, relation: "owns" },
+  ];
+  for (const { re, relation } of patterns) {
+    while ((m = re.exec(body)) !== null) {
+      const target = slugify(m[1]);
+      if (target && target.length > 1) links.push({ target, relation });
+    }
+  }
+
+  return links;
+}
+
+// ─── Markdown Parser ──────────────────────────────────────────────
+
+function parseMarkdown(content, prefix) {
+  const cards = [];
+  const headingRe = /^(#{1,6})\s+(.+)$/gm;
+  const headings = [];
+  let m;
+
+  while ((m = headingRe.exec(content)) !== null) {
+    headings.push({
+      level: m[1].length,
+      title: m[2].trim(),
+      pos: m.index,
+      contentStart: m.index + m[0].length,
+    });
+  }
+
+  if (headings.length === 0) return parsePlainText(content, prefix);
+
+  const usedSlugs = new Set();
+  function uniqueSlug(base) {
+    let slug = base;
+    let i = 2;
+    while (usedSlugs.has(slug)) { slug = `${base}-${i}`; i++; }
+    usedSlugs.add(slug);
+    return slug;
+  }
+
+  // Preamble before first heading
+  const preamble = content.slice(0, headings[0].pos).trim();
+  if (preamble.length > 30) {
+    const slug = uniqueSlug(prefix ? `${prefix}/intro` : "intro");
+    cards.push({
+      slug,
+      title: prefix ? `${prefix} — Introduction` : "Introduction",
+      body: preamble.slice(0, 1000),
+      cardType: "general",
+      keywords: extractKeywords("intro", preamble),
+      links: [],
+    });
+  }
+
+  // Parent stack for hierarchy: [{level, slug}]
+  const stack = [];
+  let edgeCount = 0;
+
+  for (let i = 0; i < headings.length; i++) {
+    const h = headings[i];
+    const bodyEnd = i + 1 < headings.length ? headings[i + 1].pos : content.length;
+    const rawBody = content.slice(h.contentStart, bodyEnd).trim();
+    // FIX: fallback to title when heading has no body content
+    const body = rawBody.length > 0 ? rawBody : h.title;
+
+    const baseSlug = slugify(h.title);
+    if (!baseSlug) continue;
+    const slug = uniqueSlug(prefix ? `${prefix}/${baseSlug}` : baseSlug);
+    const links = [];
+
+    // Hierarchy edge
+    while (stack.length > 0 && stack[stack.length - 1].level >= h.level) stack.pop();
+    if (stack.length > 0) {
+      links.push({ target: stack[stack.length - 1].slug, relation: "subtask_of" });
+      edgeCount++;
+    }
+    stack.push({ level: h.level, slug });
+
+    // Content-derived edges
+    const bodyLinks = extractLinksFromBody(body);
+    for (const l of bodyLinks) {
+      const target = prefix && !l.target.includes("/") ? `${prefix}/${l.target}` : l.target;
+      links.push({ target, relation: l.relation });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: h.title,
+      body: body.slice(0, 1000),
+      cardType: inferCardType(h.title, body),
+      keywords: extractKeywords(h.title, body),
+      links,
+    });
+  }
+
+  return { cards, edgeCount, format: "markdown" };
+}
+
+// ─── Conversation Parser ──────────────────────────────────────────────
+
+const SPEAKER_RE = /^(User|Human|Assistant|AI|System|Bot)\s*:/i;
+
+function isConversationLog(text) {
+  const lines = text.split("\n");
+  let hits = 0;
+  for (const line of lines) {
+    if (SPEAKER_RE.test(line.trim())) hits++;
+    if (hits >= 2) return true;
+  }
+  return false;
+}
+
+function parseConversation(content, prefix) {
+  const cards = [];
+  const turnRe = /^(User|Human|Assistant|AI|System|Bot)\s*:/gim;
+  const starts = [];
+  let m;
+  while ((m = turnRe.exec(content)) !== null) {
+    starts.push({ index: m.index, speaker: m[1].toLowerCase(), after: m.index + m[0].length });
+  }
+
+  if (starts.length === 0) return parsePlainText(content, prefix);
+
+  let prevSlug = null;
+  let edgeCount = 0;
+
+  for (let i = 0; i < starts.length; i++) {
+    const t = starts[i];
+    const end = i + 1 < starts.length ? starts[i + 1].index : content.length;
+    const message = content.slice(t.after, end).trim();
+    if (!message) continue;
+
+    const idx = i + 1;
+    const slug = prefix ? `${prefix}/turn-${idx}` : `turn-${idx}`;
+    const snippet = message.slice(0, 60) + (message.length > 60 ? "..." : "");
+    const links = [];
+
+    if (prevSlug) {
+      links.push({ target: prevSlug, relation: "related" });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: `[${t.speaker}] ${snippet}`,
+      body: message.slice(0, 1000),
+      cardType: "event",
+      keywords: [t.speaker, `turn-${idx}`],
+      links,
+      meta: { speaker: t.speaker, turnIndex: idx },
+    });
+
+    prevSlug = slug;
+  }
+
+  return { cards, edgeCount, format: "conversation" };
+}
+
+// ─── Plain Text Parser ──────────────────────────────────────────────
+
+function parsePlainText(content, prefix) {
+  const cards = [];
+  const paragraphs = content
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 20);
+
+  if (paragraphs.length === 0) {
+    return { cards: [], edgeCount: 0, format: "text" };
+  }
+
+  const usedSlugs = new Set();
+  let prevSlug = null;
+  let edgeCount = 0;
+
+  for (let i = 0; i < paragraphs.length; i++) {
+    const para = paragraphs[i];
+    const firstLine = para.split(/[.\n]/)[0].trim().slice(0, 80) || `Section ${i + 1}`;
+    let slug = slugify(firstLine);
+    if (!slug) slug = `section-${i + 1}`;
+
+    if (prefix) slug = `${prefix}/${slug}`;
+    let unique = slug;
+    let n = 2;
+    while (usedSlugs.has(unique)) { unique = `${slug}-${n}`; n++; }
+    usedSlugs.add(unique);
+    slug = unique;
+
+    const links = [];
+    if (prevSlug) {
+      links.push({ target: prevSlug, relation: "related" });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: firstLine,
+      body: para.slice(0, 1000),
+      cardType: inferCardType(firstLine, para),
+      keywords: extractKeywords(firstLine, para),
+      links,
+    });
+    prevSlug = slug;
+  }
+
+  return { cards, edgeCount, format: "text" };
+}
+
+// ─── Main Entry ───────────────────────────────────────────────────────
+
+/**
+ * Parse any text into HyperStack cards + edges.
+ * Auto-detects: markdown, conversation log, or plain text.
+ *
+ * @param {string} content — raw input
+ * @param {object} [opts]
+ * @param {string} [opts.prefix] — slug prefix (e.g. "readme", "docs/api")
+ * @param {string} [opts.defaultType] — override cardType for "general" cards
+ * @returns {{ cards: Array, edgeCount: number, format: string }}
+ */
+function parse(content, opts = {}) {
+  if (!content || typeof content !== "string") {
+    return { cards: [], edgeCount: 0, format: "empty" };
+  }
+
+  const prefix = opts.prefix ? slugify(opts.prefix) : "";
+
+  let result;
+  if (isConversationLog(content)) {
+    result = parseConversation(content, prefix);
+  } else if (/^#{1,6}\s+/m.test(content)) {
+    result = parseMarkdown(content, prefix);
+  } else {
+    result = parsePlainText(content, prefix);
+  }
+
+  if (opts.defaultType) {
+    for (const card of result.cards) {
+      if (card.cardType === "general") card.cardType = opts.defaultType;
+    }
+  }
+
+  return result;
+}
+
+export { parse, parseMarkdown, parseConversation, parsePlainText, slugify, inferCardType };
+export default parse;