@doquflow/server 1.7.0 → 2.0.0

package/README.md

@@ -1,82 +1,34 @@
-# @doquflow/server
+# @doquflow/server (DEPRECATED ALIAS)
 
-MCP server that lets AI agents read any codebase and build a persistent, incrementally-maintained knowledge base using the **LLM Wiki pattern**. 15 tools. Zero AI inside — the agent does all the thinking.
+This package was the original DocuFlow MCP server distribution.
+In v2.0+ it is a thin alias that depends on `@doquflow/studio`.
 
-```
-AI Agent (Claude, Copilot, Cursor)
-       │ calls MCP tools
-@doquflow/server          ← reads files, builds wiki, answers questions
-       │ filesystem only
-Any project on disk       ← any language, any structure
-```
+## Why does this still exist?
 
-## Install
+Existing users have `@doquflow/server` registered in their `.mcp.json`
+files. The DocuFlow project's commitment is **zero breakage** for
+existing installs. This package will continue to install and run
+identically through all v2.x releases.
 
-```bash
-npx @doquflow/cli init
-```
+## What you should install instead
 
-The CLI registers this server automatically. You do not need to install `@doquflow/server` directly.
+- **Full surface** (UI, REST API, daemons, 15 MCP tools):
+  `npm i -g @doquflow/studio`
+- **Irreducible value pipe** (4 MCP tools, no daemon, no UI):
+  `npm i -g @doquflow/core`
+- **All-in-one CLI** (transitively pulls core + studio):
+  `npm i -g @doquflow/cli`
 
-## Tools (15 total)
+## Migration
 
-### Code Extraction
+See [MIGRATION.md](../../MIGRATION.md) and [release/v2.0.0.md](../../release/v2.0.0.md).
 
-| Tool | Input | Output |
-|------|-------|--------|
-| `read_module` | `{ path }` | Language, classes, functions, dependencies, DB tables, endpoints, config refs, raw content |
-| `list_modules` | `{ path, extensions? }` | All modules in a directory tree (bulk extraction, no raw content) |
-| `write_spec` | `{ project_path, filename, content }` | Writes markdown spec to `.docuflow/specs/` |
-| `read_specs` | `{ project_path, module_name? }` | Reads existing specs; includes `stale: boolean` per spec |
+Run `docuflow doctor` (v2.0+) for a personalized recommendation.
 
-### Wiki Pipeline
+## Deprecation timeline
 
-| Tool | What it does |
-|------|-------------|
-| `ingest_source` | Parse source doc → extract entities/concepts → create wiki pages with context |
-| `update_index` | Regenerate `index.md` and append to `log.md` |
-| `list_wiki` | List wiki pages by category; includes `stale: boolean` per page and `stale_pages` count |
-| `wiki_search` | BM25-inspired relevance search across all wiki pages |
-| `query_wiki` | Main interface: search + synthesize answer from wiki |
-| `answer_synthesis` | Build structured markdown answer from selected pages |
-| `save_answer_as_page` | Save synthesised answer back to wiki |
-
-### Health & Guidance
-
-| Tool | What it does |
-|------|-------------|
-| `lint_wiki` | Health checks: orphan pages, stale content, broken links, metadata gaps, contradictions. Returns 0-100 health score. |
-| `get_schema_guidance` | Detect domain → recommend missing wiki pages |
-| `preview_generation` | Show what a tool will do before running (reads real wiki state) |
-
-### Dependency Analysis
-
-| Tool | What it does |
-|------|-------------|
-| `generate_dependency_graph` | Build import/shared-table/shared-endpoint graph. Returns `nodes`, `edges`, `most_connected` top 10 (highest-risk files). |
-
-## Languages supported
-
-TypeScript, JavaScript, Python, Go (structs, funcs, gin/gorilla routes, GORM), Ruby/Rails (classes, ActiveRecord, Rails routes), Rust, Java, C#, PHP, Kotlin, Swift, SQL, Shell, YAML, JSON, and more.
-
-Unknown file types return full raw content — never fails on unfamiliar files.
-
-## Extraction engine
-
-| Field | Detected from |
-|-------|--------------|
-| `classes` | `class`, `interface`, `struct`, `enum`, `record`, Go `type … struct/interface`, Ruby `module` |
-| `functions` | Keyword-prefixed declarations, arrow functions, Go `func`, Ruby `def` |
-| `dependencies` | `import`, `require()`, Go import blocks, Ruby require |
-| `db_tables` | SQL `FROM/JOIN/INTO`, EF `DbSet<T>`, GORM `db.Table()`, ActiveRecord associations |
-| `endpoints` | .NET attributes, Express/NestJS, gin/gorilla/chi routes, Rails route helpers |
-| `config_refs` | `process.env`, `os.Getenv`, `ENV['KEY']`, `IConfiguration`, `appsettings` |
-
-## Requirements
-
-- Node.js 18+
-- No API keys, no network calls, no AI dependencies
-
-## License
-
-MIT — [github.com/doquflows/docuflow](https://github.com/doquflows/docuflow)
+- v2.0 — alias maintained, no behavior change
+- v2.x — alias maintained, no behavior change
+- v3.0 — removal *considered* based on download stats. We will publish
+  a clear deprecation notice at least one minor version before any
+  removal.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "@doquflow/studio/mcp";

package/dist/index.js

@@ -1,331 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
-const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
-const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
-const read_module_1 = require("./tools/read-module");
-const list_modules_1 = require("./tools/list-modules");
-const write_spec_1 = require("./tools/write-spec");
-const read_specs_1 = require("./tools/read-specs");
-const ingest_source_1 = require("./tools/ingest-source");
-const update_index_1 = require("./tools/update-index");
-const list_wiki_1 = require("./tools/list-wiki");
-const wiki_search_1 = require("./tools/wiki-search");
-const answer_synthesis_1 = require("./tools/answer-synthesis");
-const query_wiki_1 = require("./tools/query-wiki");
-const save_answer_as_page_1 = require("./tools/save-answer-as-page");
-const lint_wiki_1 = require("./tools/lint-wiki");
-const get_schema_guidance_1 = require("./tools/get-schema-guidance");
-const preview_generation_1 = require("./tools/preview-generation");
-const generate_dependency_graph_1 = require("./tools/generate-dependency-graph");
-const server = new index_js_1.Server({ name: "docuflow", version: "0.1.0" }, { capabilities: { tools: {} } });
-server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: "read_module",
-            description: "Read a single source file, detect its language, and extract classes, functions, dependencies, DB tables, endpoints, and config references. Returns raw content truncated at 8000 chars.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    path: { type: "string", description: "Absolute or relative path to the source file." },
-                },
-                required: ["path"],
-            },
-        },
-        {
-            name: "list_modules",
-            description: "Walk a project directory and return extracted facts for every non-binary file. Skips node_modules, dist, build, .git, vendor, obj, bin, .docuflow, *.min.js, *.map, *.lock, and files >300KB. Raw content is omitted for bulk results.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    path: { type: "string", description: "Root directory to scan." },
-                    extensions: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Optional extension filter e.g. [\".cs\",\".ts\"]. If omitted all non-binary files are included.",
-                    },
-                },
-                required: ["path"],
-            },
-        },
-        {
-            name: "write_spec",
-            description: "Write a markdown spec file to <project_path>/.docuflow/specs/<filename>.md and update the index. The agent provides the full markdown content.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project (where .docuflow/ will be created)." },
-                    filename: { type: "string", description: "Name for the spec file, without extension." },
-                    content: { type: "string", description: "Full markdown content to write." },
-                },
-                required: ["project_path", "filename", "content"],
-            },
-        },
-        {
-            name: "read_specs",
-            description: "Read previously written specs from <project_path>/.docuflow/specs/. Optionally filter by module name.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    module_name: {
-                        type: "string",
-                        description: "Optional: name of a specific spec to retrieve (with or without .md).",
-                    },
-                },
-                required: ["project_path"],
-            },
-        },
-        {
-            name: "ingest_source",
-            description: "Ingest a markdown source document from .docuflow/sources/ and generate wiki pages (entities, concepts) with cross-references. Returns pages created and entities discovered.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    source_filename: {
-                        type: "string",
-                        description: "Filename in .docuflow/sources/ to ingest (e.g., 'overview.md').",
-                    },
-                },
-                required: ["project_path", "source_filename"],
-            },
-        },
-        {
-            name: "update_index",
-            description: "Scan all wiki pages in .docuflow/wiki/ and regenerate .docuflow/index.md organized by category. Appends operation to log.md.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                },
-                required: ["project_path"],
-            },
-        },
-        {
-            name: "list_wiki",
-            description: "List all wiki pages in .docuflow/wiki/, optionally filtered by category. Returns metadata (title, created_at, sources, tags, stale) and page counts by category. Pages not updated in 30+ days are flagged stale:true.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    category: {
-                        type: "string",
-                        enum: ["entity", "concept", "timeline", "synthesis"],
-                        description: "Optional: filter to a specific category.",
-                    },
-                },
-                required: ["project_path"],
-            },
-        },
-        {
-            name: "wiki_search",
-            description: "Search the wiki for pages matching a query using relevance scoring. Returns ranked results with preview snippets and matched terms. BM25-inspired ranking weights entity pages higher.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    query: { type: "string", description: "Search query (e.g., 'MCP protocol design')." },
-                    limit: {
-                        type: "number",
-                        description: "Optional: max results to return (default: 10).",
-                    },
-                    category: {
-                        type: "string",
-                        enum: ["entity", "concept", "timeline", "synthesis"],
-                        description: "Optional: filter to a specific category.",
-                    },
-                },
-                required: ["project_path", "query"],
-            },
-        },
-        {
-            name: "synthesize_answer",
-            description: "Generate a synthesis answer from multiple wiki pages. Extracts relevant sentences, key concepts, and builds a markdown answer with citations.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    query: { type: "string", description: "The question being answered." },
-                    source_page_ids: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "List of wiki page IDs to synthesize from.",
-                    },
-                },
-                required: ["project_path", "query", "source_page_ids"],
-            },
-        },
-        {
-            name: "query_wiki",
-            description: "Ask a question against the wiki. Automatically searches for relevant pages, synthesizes an answer, and returns source pages with confidence score. One-stop tool for querying accumulated knowledge.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    question: { type: "string", description: "The question to ask (e.g., 'How does the MCP protocol work?')." },
-                    max_sources: {
-                        type: "number",
-                        description: "Optional: max source pages to use in synthesis (default: 5).",
-                    },
-                },
-                required: ["project_path", "question"],
-            },
-        },
-        {
-            name: "save_answer_as_page",
-            description: "Save a generated answer as a new wiki page. Allows query results to compound back into the knowledge base, growing the wiki with new synthesis pages. Automatically adds frontmatter and updates log.md.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    question: { type: "string", description: "The original question that was answered." },
-                    answer: { type: "string", description: "The markdown answer text to save." },
-                    page_title: { type: "string", description: "Title for the new page (e.g., 'How MCP Protocol Works')." },
-                    category: {
-                        type: "string",
-                        enum: ["synthesis", "entity", "concept", "timeline"],
-                        description: "Optional: wiki category for the page (default: synthesis).",
-                    },
-                    source_page_ids: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Optional: list of source wiki page IDs used to generate this answer.",
-                    },
-                },
-                required: ["project_path", "question", "answer", "page_title"],
-            },
-        },
-        {
-            name: "lint_wiki",
-            description: "Health check wiki for quality issues: orphan pages, broken references, stale content, metadata gaps, and contradictions. Returns issues found, metrics, health score, and recommendations.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    check_type: {
-                        type: "string",
-                        enum: ["all", "orphans", "contradictions", "stale", "metadata"],
-                        description: "Optional: type of check to run (default: all).",
-                    },
-                },
-                required: ["project_path"],
-            },
-        },
-        {
-            name: "get_schema_guidance",
-            description: "Analyze what documents should exist based on project schema and current wiki. Removes decision fatigue by suggesting what to create next.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root of the project." },
-                    domain: {
-                        type: "string",
-                        description: "Optional: domain hint (Code/Architecture, Research, Business, Personal). Auto-detected if not provided.",
-                    },
-                },
-                required: ["project_path"],
-            },
-        },
-        {
-            name: "preview_generation",
-            description: "Preview what a tool will generate before running it. Removes black-box feeling by showing predicted actions, outputs, and impact.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    tool_name: { type: "string", description: "Name of the tool to preview (e.g., ingest_source, query_wiki)." },
-                    project_path: { type: "string", description: "Root of the project." },
-                    params: { type: "object", description: "Parameters you would pass to that tool." },
-                },
-                required: ["tool_name", "project_path", "params"],
-            },
-        },
-        {
-            name: "generate_dependency_graph",
-            description: "Scan a project and build a dependency graph showing how modules import each other, which DB tables are shared, and which files are most connected. Returns nodes, edges, shared tables, and the top 10 most-connected modules. Use this to understand coupling and identify risky files to change.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_path: { type: "string", description: "Root directory of the project to analyse." },
-                    extensions: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Optional extension filter e.g. [\".ts\",\".go\"]. If omitted, all non-binary files are scanned.",
-                    },
-                    focus: {
-                        type: "string",
-                        description: "Optional: filter graph to neighbours of a specific file or module name (partial match, e.g. 'user-service').",
-                    },
-                },
-                required: ["project_path"],
-            },
-        },
-    ],
-}));
-server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-        let result;
-        if (name === "read_module") {
-            result = await (0, read_module_1.readModule)(args);
-        }
-        else if (name === "list_modules") {
-            result = await (0, list_modules_1.listModules)(args);
-        }
-        else if (name === "write_spec") {
-            result = await (0, write_spec_1.writeSpec)(args);
-        }
-        else if (name === "read_specs") {
-            result = await (0, read_specs_1.readSpecs)(args);
-        }
-        else if (name === "ingest_source") {
-            result = await (0, ingest_source_1.ingestSource)(args);
-        }
-        else if (name === "update_index") {
-            result = await (0, update_index_1.updateIndex)(args);
-        }
-        else if (name === "list_wiki") {
-            result = await (0, list_wiki_1.listWiki)(args);
-        }
-        else if (name === "wiki_search") {
-            result = await (0, wiki_search_1.wikiSearch)(args);
-        }
-        else if (name === "synthesize_answer") {
-            result = await (0, answer_synthesis_1.synthesizeAnswer)(args);
-        }
-        else if (name === "query_wiki") {
-            result = await (0, query_wiki_1.queryWiki)(args);
-        }
-        else if (name === "save_answer_as_page") {
-            result = await (0, save_answer_as_page_1.saveAnswerAsPage)(args);
-        }
-        else if (name === "lint_wiki") {
-            result = await (0, lint_wiki_1.lintWiki)(args);
-        }
-        else if (name === "get_schema_guidance") {
-            result = await (0, get_schema_guidance_1.getSchemataGuidance)(args);
-        }
-        else if (name === "preview_generation") {
-            result = await (0, preview_generation_1.previewGeneration)(args);
-        }
-        else if (name === "generate_dependency_graph") {
-            result = await (0, generate_dependency_graph_1.generateDependencyGraph)(args);
-        }
-        else {
-            result = { error: `Unknown tool: ${name}` };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    }
-    catch (e) {
-        return { content: [{ type: "text", text: JSON.stringify({ error: e?.message ?? String(e) }) }] };
-    }
-});
-async function main() {
-    const transport = new stdio_js_1.StdioServerTransport();
-    await server.connect(transport);
-}
-main().catch((e) => {
-    process.stderr.write(`DocuFlow MCP fatal error: ${e?.message ?? e}\n`);
-    process.exit(1);
-});
+// @doquflow/server v2.0 is a back-compat alias of @doquflow/studio.
+// New installs should use @doquflow/studio (full surface) or
+// @doquflow/core (4-tool minimal). See release/v2.0.0.md.
+//
+// This entry re-uses studio's MCP server binary.
+require("@doquflow/studio/mcp");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doquflow/server",
-  "version": "1.7.0",
-  "description": "Docuflow MCP server — lets AI agents read codebases and persist living specs",
+  "version": "2.0.0",
+  "description": "DEPRECATED ALIAS: this package now re-exports @doquflow/studio. New installs should use @doquflow/studio or @doquflow/core. See https://github.com/doquflows/docuflow/blob/main/MIGRATION.md.",
   "author": "Docuflow <hello@doquflows.dev>",
   "license": "MIT",
   "homepage": "https://github.com/doquflows/docuflow",
@@ -28,15 +28,13 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
-    "test": "vitest run"
+    "build": "tsc"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@doquflow/studio": "2.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^4.1.6"
+    "typescript": "^5.6.0"
   }
 }

package/dist/category-dir.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.categoryDir = categoryDir;
-const CATEGORY_PLURAL = {
-    entity: "entities",
-    concept: "concepts",
-    timeline: "timelines",
-    synthesis: "syntheses",
-};
-function categoryDir(category) {
-    return CATEGORY_PLURAL[category];
-}

package/dist/extractor-rules.js

@@ -1,166 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.passesEntityRules = passesEntityRules;
-const extractor_stoplist_1 = require("./extractor-stoplist");
-/**
- * Rule 1 — Stop-list rejection (fast path)
- * Candidate is rejected when:
- *   (a) the whole normalized phrase is on the stop-list, or
- *   (b) it is a single word on the stop-list, or
- *   (c) it is a multi-word phrase whose words are *all* on the stop-list
- *       (e.g. "key components" — both "key" and "components" are generic).
- */
-function ruleStopList(c) {
-    const normalized = c.name
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9 ]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-    if (!normalized)
-        return { ok: true };
-    if (extractor_stoplist_1.ENTITY_STOPLIST.has(normalized)) {
-        return { ok: false, reason: `"${c.name}" is a generic stop-list term` };
-    }
-    const words = normalized.split(/\s+/).filter(Boolean);
-    if (words.length === 1 && extractor_stoplist_1.ENTITY_STOPLIST.has(words[0])) {
-        return { ok: false, reason: `"${c.name}" is a generic stop-list term` };
-    }
-    if (words.length > 1 && words.every((w) => extractor_stoplist_1.ENTITY_STOPLIST.has(w))) {
-        return { ok: false, reason: `"${c.name}" contains only generic stop-list terms` };
-    }
-    return { ok: true };
-}
-/**
- * Rule 2 — No emoji-only or punctuation-only slugs (fast path)
- * Strip emoji; reject if resulting slug is empty or only underscores/dashes.
- */
-function ruleNoEmojiOrPunctSlug(c) {
-    const stripped = c.name
-        .replace(/[\p{Emoji}\p{Emoji_Modifier}\p{Emoji_Component}]/gu, "")
-        .replace(/[^a-z0-9]/gi, "_")
-        .toLowerCase();
-    if (!stripped || /^[_\-]+$/.test(stripped)) {
-        return { ok: false, reason: `"${c.name}" produces an empty or punctuation-only slug` };
-    }
-    return { ok: true };
-}
-/**
- * Rule 3 — Structural anchor
- * Bold-text candidates are only accepted when they sit inside a meaningful
- * structural paragraph (not a bare bullet point with no prose).
- * Heading candidates always pass this rule.
- */
-function ruleStructuralAnchor(c) {
-    if (c.source === "heading")
-        return { ok: true };
-    const stripped = c.context.replace(/^\s*[-*+]\s+/, "").trim();
-    const wordCount = stripped.split(/\s+/).filter(Boolean).length;
-    if (wordCount < 4) {
-        return { ok: false, reason: "bold text in bare bullet with no sentence context" };
-    }
-    return { ok: true };
-}
-/**
- * Rule 4 — Minimum token signal
- * Must be ≥2 words, OR ≥1 word with a non-sentence-start capital (camelCase/PascalCase),
- * OR contain a code-like separator (_, -, (), ::, .).
- * Heading candidates are exempt — structural position grants authority.
- */
-function ruleMinimumTokenSignal(c) {
-    if (c.source === "heading")
-        return { ok: true };
-    const name = c.name.trim();
-    const words = name.split(/\s+/).filter(Boolean);
-    if (words.length >= 2)
-        return { ok: true };
-    const word = words[0] ?? "";
-    const hasInternalCap = /(?<!^)[A-Z]/.test(word);
-    const hasCodeSeparator = /[_\-().::]/.test(word);
-    if (hasInternalCap || hasCodeSeparator)
-        return { ok: true };
-    return { ok: false, reason: "single generic word with no distinguishing signal" };
-}
-/**
- * Rule 5 — Context requirement
- * Bold text must have at least 1 sentence of real context (≥6 words).
- * Heading candidates are exempt.
- */
-function ruleContextRequirement(c) {
-    if (c.source === "heading")
-        return { ok: true };
-    const sentences = c.context.split(/[.!?]+/).filter((s) => s.trim().split(/\s+/).length >= 6);
-    if (sentences.length === 0) {
-        return { ok: false, reason: "no surrounding sentence context (≥6 words) found" };
-    }
-    return { ok: true };
-}
-/**
- * Rule 6 — Section-heading noise patterns
- * Reject candidates whose surface form matches well-known structural noise:
- * numbered list items ("1. Foo"), file references ("foo.md"), question-form
- * headings ("What is X"), preposition-led phrases ("For X"), layer/phase
- * markers ("Layer 1"), and full sentences captured as entities ("X is a Y").
- */
-function ruleSectionHeadingNoise(c) {
-    const name = c.name.trim();
-    // Numbered list items: "1. Foo", "2) Bar"
-    if (/^\d+[.)]\s/.test(name)) {
-        return { ok: false, reason: `"${name}" is a numbered list item, not an entity` };
-    }
-    // File references masquerading as entities
-    if (/\.(md|ts|tsx|js|jsx|json|ya?ml|css|scss|sh|py|go|rb)$/i.test(name)) {
-        return { ok: false, reason: `"${name}" looks like a file reference, not an entity` };
-    }
-    // Question-form headings
-    if (/^(what|how|why|where|when|who|which)\s/i.test(name)) {
-        return { ok: false, reason: `"${name}" is a question-form section heading` };
-    }
-    // Preposition-led phrases (common bullet-list openings)
-    if (/^(for|with|by|to|in|on|at|of|from|about)\s/i.test(name)) {
-        return { ok: false, reason: `"${name}" starts with a preposition (section-heading form)` };
-    }
-    // Layer / phase / step markers
-    if (/^(layer|phase|step|chapter|part|section)\s+\d/i.test(name)) {
-        return { ok: false, reason: `"${name}" is a layer/phase marker, not an entity` };
-    }
-    // Sentence-form: "X is a Y", "X is not a Y" — full sentences captured as entities
-    if (/\bis\s+(not\s+)?(a|an|the)\s+/i.test(name)) {
-        return { ok: false, reason: `"${name}" looks like a sentence, not an entity name` };
-    }
-    // Starts with emoji-as-decoration (e.g. "❌ Anti-pattern", "🔧 Storage", "✅ Allowed").
-    // These are section dividers / status markers, not entity names.
-    if (/^[\p{Emoji_Presentation}\p{Extended_Pictographic}]/u.test(name)) {
-        return { ok: false, reason: `"${name}" starts with an emoji (heading decoration, not an entity)` };
-    }
-    // "The X" pattern — descriptive references, not entity names
-    if (/^the\s+/i.test(name)) {
-        return { ok: false, reason: `"${name}" starts with "the " (descriptive reference, not an entity)` };
-    }
-    // Date strings captured as entities ("Date: 2026-04-27", "2026-04-27")
-    if (/\b\d{4}[-/_]\d{1,2}[-/_]\d{1,2}\b/.test(name)) {
-        return { ok: false, reason: `"${name}" contains a date (metadata, not an entity)` };
-    }
-    return { ok: true };
-}
-const RULES = [
-    ruleStopList,
-    ruleNoEmojiOrPunctSlug,
-    ruleSectionHeadingNoise,
-    ruleStructuralAnchor,
-    ruleMinimumTokenSignal,
-    ruleContextRequirement,
-];
-/**
- * Run all entity quality rules against a candidate.
- * Returns { ok: true } if the candidate passes all rules,
- * or { ok: false, reason } for the first rule that rejects it.
- */
-function passesEntityRules(candidate) {
-    for (const rule of RULES) {
-        const result = rule(candidate);
-        if (!result.ok)
-            return result;
-    }
-    return { ok: true };
-}