@miclivs/cadcli 0.2.0 → 0.3.0

package/README.md

@@ -41,6 +41,8 @@ cadcli entities <file>                   # entities, optionally filtered
 
 cadcli search <file> [query]             # search IDs, types, layers, text, raw fields
   --query "door" --type TEXT --layer A-TEXT --limit 10 --score --no-snippets
+cadcli query <file> --schema             # show SQL query tables
+cadcli query <file> --sql "select text from texts"
 
 cadcli view <file> [-o preview.svg]      # SVG preview
 cadcli edit <file> --set-text <text> --text-id <id> -o out.dwg
@@ -81,6 +83,51 @@ SEARCH HINTS
 ```
 
 
+## Text normalization
+
+Some CAD files store visible text through legacy code pages and SHX fonts. For example, a Hebrew DWG may store `jsr muu, 8` while AutoCAD displays it as `חדר צוות 8`. `cadcli` automatically normalizes these cases while loading the drawing, before `overview`, `search`, `entities`, `json`, and future query features consume the document.
+
+The normalizer is route-based: document metadata such as `codePage` is combined with per-entity text style/font metadata such as `gil.shx`, `narkism$.shx`, or `heb.shx`. When the route is confident, `cadcli` rewrites the in-memory `text` field to the intended text. It does not store both raw and normalized copies in caches or output.
+
+```txt
+raw DWG text:  jsr muu, 8
+cadcli text:   חדר צוות 8
+```
+
+The normalized document metadata records what happened:
+
+```json
+{
+  "metadata": {
+    "codePage": "ansi_1255",
+    "textNormalization": {
+      "applied": ["hebrew-keyboard"],
+      "entitiesChanged": 58
+    }
+  }
+}
+```
+
+This makes discovery work naturally:
+
+```bash
+cadcli overview office.dwg
+cadcli search office.dwg "חדר" --json
+```
+
+## Query
+
+`cadcli query` runs read-only SQL over a narrow in-memory projection of the normalized drawing. It does not create a user-visible database file.
+
+```bash
+cadcli query office.dwg --schema
+cadcli query office.dwg --schema --json
+cadcli query office.dwg --sql "select id, text, layer, x, y from texts where text like 'חדר%'" --json
+cadcli query office.dwg --file rooms.sql --json
+```
+
+The base tables are `summary`, `metadata`, `layers`, `blocks`, and `entities`. Convenience tables expose common drawing concepts such as `texts` and `inserts`.
+
 ## Viewing vs SVG export
 
 `cadcli view` renders SVG through acad-ts directly from the CAD document.

package/dist/commands/query.d.ts

@@ -0,0 +1,7 @@
+import type { DrawingCommandOptions } from "./shared.js";
+export interface QueryOptions extends DrawingCommandOptions {
+    sql?: string;
+    file?: string;
+    schema?: boolean;
+}
+export declare function query(file: string, options: QueryOptions): Promise<void>;

package/dist/commands/query.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { queryDrawing, querySchema, querySchemaTables } from "../core/query.js";
+import { output } from "../utils/output.js";
+import { drawingFor, handleCommandError, userError } from "./shared.js";
+function querySql(options) {
+    if (options.schema)
+        return "";
+    if (options.sql && options.file) {
+        throw userError("Use either --sql or --file, not both.", "QUERY_SOURCE_CONFLICT");
+    }
+    if (options.sql)
+        return options.sql;
+    if (options.file)
+        return readFileSync(options.file, "utf8");
+    throw userError("Provide --sql <query>, --file <path>, or --schema.", "MISSING_QUERY");
+}
+function printRows(rows) {
+    for (const row of rows) {
+        console.log(Object.values(row)
+            .map((value) => value ?? "")
+            .join("\t"));
+    }
+}
+export async function query(file, options) {
+    try {
+        if (options.schema) {
+            output(options, {
+                json: () => ({ tables: querySchemaTables() }),
+                human: () => console.log(querySchema()),
+            });
+            return;
+        }
+        const sql = querySql(options);
+        const doc = await drawingFor(file, options).document();
+        const result = await queryDrawing(doc, sql);
+        output(options, {
+            json: () => result,
+            human: () => printRows(result.rows),
+            quiet: () => console.log(String(result.rows.length)),
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/core/adapter.js

@@ -66,6 +66,14 @@ function blockName(entity) {
     const block = asRecord(entity).block;
     return valueString(asRecord(block).name);
 }
+function textStyle(entity) {
+    const style = asRecord(entity)._style ?? asRecord(entity).style;
+    const rec = asRecord(style);
+    return {
+        name: valueString(rec.name ?? rec._name),
+        file: valueString(rec.filename),
+    };
+}
 function vertices(entity) {
     const raw = asRecord(entity).vertices;
     if (!Array.isArray(raw))
@@ -112,8 +120,14 @@ function normalizeAcadEntity(entity) {
         data.startAngle = rec.startAngle;
     if (typeof rec.endAngle === "number")
         data.endAngle = rec.endAngle;
-    if (text)
+    if (text) {
+        const style = textStyle(entity);
         data.text = text;
+        if (style.name)
+            data.textStyle = style.name;
+        if (style.file)
+            data.textStyleFile = style.file;
+    }
     if (name)
         data.blockName = name;
     return data;
@@ -129,6 +143,7 @@ export function normalizeAcadDocument(doc) {
     const entities = items(doc.modelSpace?.entities).map(normalizeAcadEntity);
     return {
         version: doc.header?.versionString ?? String(doc.header?.version ?? ""),
+        codePage: doc.header?.codePage,
         layers,
         blocks,
         entities,

package/dist/core/drawing.js

@@ -4,13 +4,14 @@ import { DwgCliError } from "./errors.js";
 import { readCadFile } from "./files.js";
 import { normalizeDocument } from "./normalize.js";
 import { renderSvg } from "./svg.js";
+import { normalizeTextAuto } from "./text-normalize.js";
 function readerFor(opts) {
     return opts.reader ?? new AcadTsReader();
 }
 export async function loadDrawing(file, opts = {}) {
     const { bytes, format } = readCadFile(file);
     const raw = await readerFor(opts).parse(file, bytes, format);
-    return normalizeDocument(file, format, raw);
+    return normalizeTextAuto(normalizeDocument(file, format, raw));
 }
 export async function getInfo(file, opts) {
     return (await loadDrawing(file, opts)).summary;

package/dist/core/normalize.js

@@ -140,6 +140,9 @@ export function normalizeDocument(file, format, raw) {
     const layers = normalizeLayers(firstArray(root, LAYER_ARRAY_FIELDS), entities);
     const blocks = normalizeBlocks(firstArray(root, BLOCK_ARRAY_FIELDS));
     const version = stringField(root, ["version", "headerVersion", "dwgVersion"]);
+    const metadata = {
+        codePage: stringField(root, ["codePage", "encoding"]),
+    };
     const summary = {
         file: basename(file),
         format,
@@ -152,5 +155,5 @@ export function normalizeDocument(file, format, raw) {
         },
         bounds: computeBounds(entities),
     };
-    return { summary, layers, blocks, entities, unsupported, raw };
+    return { summary, metadata, layers, blocks, entities, unsupported, raw };
 }

package/dist/core/query.d.ts

@@ -0,0 +1,17 @@
+import type { DwgDocument } from "../types.js";
+export interface QuerySchemaColumn {
+    name: string;
+    type: "text" | "integer" | "real";
+}
+export interface QuerySchemaTable {
+    name: string;
+    description: string;
+    columns: QuerySchemaColumn[];
+}
+export interface QueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+}
+export declare function querySchema(): string;
+export declare function querySchemaTables(): QuerySchemaTable[];
+export declare function queryDrawing(doc: DwgDocument, sql: string): Promise<QueryResult>;

package/dist/core/query.js

@@ -0,0 +1,232 @@
+import { EXIT_UNAVAILABLE, EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { DwgCliError } from "./errors.js";
+const QUERY_SCHEMA_TABLES = [
+    {
+        name: "summary",
+        description: "One-row drawing summary.",
+        columns: [
+            { name: "file", type: "text" },
+            { name: "format", type: "text" },
+            { name: "version", type: "text" },
+            { name: "entity_count", type: "integer" },
+            { name: "layer_count", type: "integer" },
+            { name: "block_count", type: "integer" },
+            { name: "unsupported_count", type: "integer" },
+        ],
+    },
+    {
+        name: "metadata",
+        description: "Document metadata and normalization notes.",
+        columns: [
+            { name: "key", type: "text" },
+            { name: "value", type: "text" },
+        ],
+    },
+    {
+        name: "layers",
+        description: "Drawing layers and entity counts.",
+        columns: [
+            { name: "name", type: "text" },
+            { name: "entity_count", type: "integer" },
+        ],
+    },
+    {
+        name: "blocks",
+        description: "Block definitions and definition entity counts.",
+        columns: [
+            { name: "name", type: "text" },
+            { name: "entity_count", type: "integer" },
+        ],
+    },
+    {
+        name: "entities",
+        description: "All normalized model-space entities, projected narrowly.",
+        columns: [
+            { name: "id", type: "text" },
+            { name: "type", type: "text" },
+            { name: "layer", type: "text" },
+            { name: "color", type: "text" },
+        ],
+    },
+    {
+        name: "texts",
+        description: "TEXT and MTEXT entities with normalized text and insertion points.",
+        columns: [
+            { name: "id", type: "text" },
+            { name: "type", type: "text" },
+            { name: "layer", type: "text" },
+            { name: "text", type: "text" },
+            { name: "x", type: "real" },
+            { name: "y", type: "real" },
+            { name: "text_style", type: "text" },
+            { name: "text_style_file", type: "text" },
+        ],
+    },
+    {
+        name: "inserts",
+        description: "Placed block instances with insertion points.",
+        columns: [
+            { name: "id", type: "text" },
+            { name: "layer", type: "text" },
+            { name: "block_name", type: "text" },
+            { name: "x", type: "real" },
+            { name: "y", type: "real" },
+        ],
+    },
+];
+export function querySchema() {
+    return QUERY_SCHEMA_TABLES.map((table) => `${table.name}(${table.columns.map((column) => column.name).join(", ")})`).join("\n");
+}
+export function querySchemaTables() {
+    return QUERY_SCHEMA_TABLES;
+}
+async function openMemoryDatabase() {
+    try {
+        const { default: Database } = await import("better-sqlite3");
+        return new Database(":memory:");
+    }
+    catch {
+        throw new DwgCliError("cadcli query requires the optional better-sqlite3 dependency.", "QUERY_UNAVAILABLE", EXIT_UNAVAILABLE);
+    }
+}
+function sqlValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "number" || typeof value === "string")
+        return value;
+    return String(value);
+}
+function point(entity) {
+    const value = entity.data.insertionPoint ?? entity.data.position ?? entity.data.point;
+    if (!value || typeof value !== "object")
+        return { x: null, y: null };
+    const rec = value;
+    const x = Number(rec.x ?? rec.X);
+    const y = Number(rec.y ?? rec.Y);
+    return {
+        x: Number.isFinite(x) ? x : null,
+        y: Number.isFinite(y) ? y : null,
+    };
+}
+function textValue(entity) {
+    const value = entity.data.text ?? entity.data.value ?? entity.data.Text;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function blockName(entity) {
+    const value = entity.data.blockName ?? entity.data.block_name ?? entity.data.name;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function createSchema(db) {
+    db.exec(`
+    CREATE TABLE summary (
+      file TEXT,
+      format TEXT,
+      version TEXT,
+      entity_count INTEGER,
+      layer_count INTEGER,
+      block_count INTEGER,
+      unsupported_count INTEGER
+    );
+    CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT);
+    CREATE TABLE layers (name TEXT PRIMARY KEY, entity_count INTEGER);
+    CREATE TABLE blocks (name TEXT PRIMARY KEY, entity_count INTEGER);
+    CREATE TABLE entities (id TEXT PRIMARY KEY, type TEXT, layer TEXT, color TEXT);
+    CREATE TABLE texts (
+      id TEXT PRIMARY KEY,
+      type TEXT,
+      layer TEXT,
+      text TEXT,
+      x REAL,
+      y REAL,
+      text_style TEXT,
+      text_style_file TEXT
+    );
+    CREATE TABLE inserts (
+      id TEXT PRIMARY KEY,
+      layer TEXT,
+      block_name TEXT,
+      x REAL,
+      y REAL
+    );
+  `);
+}
+function registerFunctions(db) {
+    db.function("regexp", (pattern, value) => {
+        if (typeof pattern !== "string" || value === null || value === undefined) {
+            return 0;
+        }
+        try {
+            return new RegExp(pattern, "u").test(String(value)) ? 1 : 0;
+        }
+        catch {
+            return 0;
+        }
+    });
+}
+function insertDocument(db, doc) {
+    db.prepare("INSERT INTO summary VALUES (?, ?, ?, ?, ?, ?, ?)").run(doc.summary.file, doc.summary.format, doc.summary.version ?? null, doc.summary.counts.entities, doc.summary.counts.layers, doc.summary.counts.blocks, doc.summary.counts.unsupported);
+    const insertMetadata = db.prepare("INSERT INTO metadata VALUES (?, ?)");
+    if (doc.metadata.codePage)
+        insertMetadata.run("code_page", doc.metadata.codePage);
+    if (doc.metadata.textNormalization) {
+        insertMetadata.run("text_normalization_applied", doc.metadata.textNormalization.applied.join(","));
+        insertMetadata.run("text_normalization_entities_changed", doc.metadata.textNormalization.entitiesChanged);
+    }
+    const insertLayer = db.prepare("INSERT INTO layers VALUES (?, ?)");
+    const insertBlock = db.prepare("INSERT INTO blocks VALUES (?, ?)");
+    const insertEntity = db.prepare("INSERT INTO entities VALUES (?, ?, ?, ?)");
+    const insertText = db.prepare("INSERT INTO texts VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertInsert = db.prepare("INSERT INTO inserts VALUES (?, ?, ?, ?, ?)");
+    db.exec("BEGIN");
+    try {
+        for (const layer of doc.layers)
+            insertLayer.run(layer.name, layer.entityCount);
+        for (const block of doc.blocks)
+            insertBlock.run(block.name, block.entityCount);
+        for (const entity of doc.entities) {
+            insertEntity.run(entity.id, entity.type, entity.layer ?? null, sqlValue(entity.color));
+            const { x, y } = point(entity);
+            const text = textValue(entity);
+            if ((entity.type === "TEXT" || entity.type === "MTEXT") && text) {
+                insertText.run(entity.id, entity.type, entity.layer ?? null, text, x, y, sqlValue(entity.data.textStyle), sqlValue(entity.data.textStyleFile));
+            }
+            if (entity.type === "INSERT") {
+                insertInsert.run(entity.id, entity.layer ?? null, blockName(entity), x, y);
+            }
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function ensureSelectQuery(sql) {
+    const trimmed = sql.trim();
+    if (!/^(select|with)\b/i.test(trimmed)) {
+        throw new DwgCliError("Query SQL must be a SELECT statement.", "INVALID_QUERY_SQL", EXIT_USER_ERROR);
+    }
+}
+function ensureReadOnlyStatement(statement) {
+    if (statement.readonly === false) {
+        throw new DwgCliError("Query SQL must be read-only.", "INVALID_QUERY_SQL", EXIT_USER_ERROR);
+    }
+}
+export async function queryDrawing(doc, sql) {
+    ensureSelectQuery(sql);
+    const db = await openMemoryDatabase();
+    try {
+        createSchema(db);
+        registerFunctions(db);
+        insertDocument(db, doc);
+        const statement = db.prepare(sql);
+        ensureReadOnlyStatement(statement);
+        const rows = statement.all();
+        const columns = statement.columns?.().map((column) => column.name) ??
+            Object.keys(rows[0] ?? {});
+        return { columns, rows };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/core/text-normalize.d.ts

@@ -0,0 +1,3 @@
+import type { DwgDocument } from "../types.js";
+export declare function normalizeHebrewKeyboardText(text: string): string;
+export declare function normalizeTextAuto(doc: DwgDocument): DwgDocument;

package/dist/core/text-normalize.js

@@ -0,0 +1,104 @@
+import hebrewLayout from "convert-layout/he.js";
+const TEXT_NORMALIZATION_ROUTES = [
+    {
+        name: "hebrew-keyboard",
+        codePages: ["ansi_1255"],
+        textStyleFiles: ["gil.shx", "narkism$.shx", "heb.shx", "oron", "oron1"],
+        fromLatinKeyboard: hebrewLayout.fromEn,
+        targetScript: "hebrew",
+    },
+];
+function asText(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function normalizedToken(value) {
+    return value?.trim().toLowerCase();
+}
+function textStyleFile(entity) {
+    return normalizedToken(asText(entity.data.textStyleFile));
+}
+function isTextEntity(entity) {
+    return entity.type === "TEXT" || entity.type === "MTEXT";
+}
+function hasTargetScript(text, script) {
+    switch (script) {
+        case "hebrew":
+            return /[\u0590-\u05ff]/u.test(text);
+    }
+}
+function targetScriptCount(text, script) {
+    switch (script) {
+        case "hebrew":
+            return text.match(/[\u0590-\u05ff]/gu)?.length ?? 0;
+    }
+}
+function mostlyLatinKeyboardText(text, targetScript) {
+    const latinLetters = text.match(/[A-Za-z]/g)?.length ?? 0;
+    return latinLetters > 0 && targetScriptCount(text, targetScript) === 0;
+}
+function routeMatches(route, doc, entity) {
+    const codePage = normalizedToken(doc.metadata.codePage);
+    const styleFile = textStyleFile(entity);
+    return Boolean(codePage &&
+        styleFile &&
+        route.codePages.includes(codePage) &&
+        route.textStyleFiles.includes(styleFile));
+}
+function routeFor(doc, entity) {
+    return TEXT_NORMALIZATION_ROUTES.find((route) => routeMatches(route, doc, entity));
+}
+function normalizeEntityText(doc, entity) {
+    if (!isTextEntity(entity))
+        return { entity };
+    const route = routeFor(doc, entity);
+    if (!route)
+        return { entity };
+    const text = asText(entity.data.text);
+    if (!text || !mostlyLatinKeyboardText(text, route.targetScript)) {
+        return { entity };
+    }
+    const normalized = route.fromLatinKeyboard(text);
+    if (normalized === text || !hasTargetScript(normalized, route.targetScript)) {
+        return { entity };
+    }
+    return {
+        normalizer: route.name,
+        entity: {
+            ...entity,
+            data: {
+                ...entity.data,
+                text: normalized,
+            },
+        },
+    };
+}
+export function normalizeHebrewKeyboardText(text) {
+    return hebrewLayout.fromEn(text);
+}
+export function normalizeTextAuto(doc) {
+    const applied = new Set();
+    let entitiesChanged = 0;
+    const entities = doc.entities.map((entity) => {
+        const result = normalizeEntityText(doc, entity);
+        if (!result.normalizer)
+            return entity;
+        entitiesChanged++;
+        applied.add(result.normalizer);
+        return result.entity;
+    });
+    if (entitiesChanged === 0)
+        return doc;
+    const unsupportedIds = new Set(doc.unsupported.map((entity) => entity.id));
+    return {
+        ...doc,
+        entities,
+        unsupported: entities.filter((entity) => unsupportedIds.has(entity.id)),
+        metadata: {
+            ...doc.metadata,
+            textNormalization: {
+                applied: [...applied],
+                entitiesChanged,
+            },
+        },
+    };
+}

package/dist/main.js

@@ -9,6 +9,7 @@ import { info } from "./commands/info.js";
 import { json } from "./commands/json.js";
 import { layers } from "./commands/layers.js";
 import { overview } from "./commands/overview.js";
+import { query } from "./commands/query.js";
 import { search } from "./commands/search.js";
 import { svg } from "./commands/svg.js";
 import { thumbnail } from "./commands/thumbnail.js";
@@ -27,6 +28,7 @@ Examples:
   $ cadcli layers drawing.dwg --json     List layers for scripts/agents
   $ cadcli entities drawing.dwg --type LINE --limit 20
   $ cadcli search drawing.dwg "conference" --layer A-TEXT
+  $ cadcli query drawing.dwg --sql "select text, x, y from texts"
   $ cadcli view drawing.dwg -o drawing.svg
   $ cadcli edit drawing.dwg --set-text "Office" --text-id 2A -o edited.dwg
   $ cadcli edit drawing.dwg --add-line 0,0:10,0 --new-layer A-WALL -o edited.dwg
@@ -40,6 +42,7 @@ Inspecting:
   blocks <file>        List blocks
   entities <file>      List/filter entities
   search <file>        Search entities by text, type, layer, and raw fields
+  query <file>         Query normalized CAD tables with SQL
 
 Viewing and editing:
   view <file>          Render an SVG preview
@@ -50,6 +53,12 @@ Conversion:
   svg <file>           Render best-effort SVG from normalized JSON
   thumbnail <file>     Extract embedded thumbnail when available
 
+Querying:
+  query <file>         Query normalized CAD tables with SQL
+    --schema           Show available query tables
+    --sql <query>      Run an inline SELECT query
+    --file <path>      Read a SELECT query from a file
+
 Options:
   --json               Output as JSON
   -q, --quiet          Suppress non-essential output
@@ -119,6 +128,13 @@ program
     root.query = root.query || queryWords.join(" ");
     await search(file, root);
 });
+program
+    .command("query <file>")
+    .description("Query normalized CAD tables with SQL")
+    .option("--sql <query>", "SQL SELECT query to run")
+    .option("--file <path>", "Read SQL query from a file")
+    .option("--schema", "Show available query tables")
+    .action(async (file, opts, cmd) => query(file, { ...cmd.optsWithGlobals(), ...opts }));
 program
     .command("view <file>")
     .description("Render an SVG preview")

package/dist/types.d.ts

@@ -35,8 +35,17 @@ export interface DwgSummary {
     };
     bounds?: DwgBounds;
 }
+export interface DwgTextNormalizationMetadata {
+    applied: string[];
+    entitiesChanged: number;
+}
+export interface DwgMetadata {
+    codePage?: string;
+    textNormalization?: DwgTextNormalizationMetadata;
+}
 export interface DwgDocument {
     summary: DwgSummary;
+    metadata: DwgMetadata;
     layers: DwgLayer[];
     blocks: DwgBlock[];
     entities: DwgEntity[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miclivs/cadcli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent-friendly CAD inspection, search, viewing, and editing for DWG/DXF files.",
   "type": "module",
   "main": "dist/index.js",
@@ -68,6 +68,7 @@
     "@node-projects/acad-ts": "2.3.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
+    "convert-layout": "^0.11.1",
     "nanoid": "^5.1.6"
   },
   "optionalDependencies": {

package/skills/cadcli/SKILL.md

@@ -5,16 +5,40 @@ description: Inspect, search, summarize, preview, and safely edit DWG/DXF CAD dr
 
 # cadcli
 
-Use `cadcli` for progressive CAD file discovery. Start broad, then narrow down:
+Use `cadcli` for progressive CAD file discovery. Follow this order when trying to understand a drawing:
+
+```bash
+cadcli info <file> --json              # size, format, counts, bounds
+cadcli overview <file>                 # human clues: layers, labels, blocks, hints
+cadcli layers <file> --json            # major groupings
+cadcli blocks <file> --json            # reusable object definitions
+cadcli query <file> --schema           # learn query tables before writing SQL
+cadcli search <file> "query" --json    # fuzzy discovery from overview terms
+cadcli entities <file> --limit 20 --json # raw drilldown only when needed
+```
+
+When working with a drawing, build a human-readable understanding of what is in it. Do not stop at listing CAD primitives such as layers, blocks, handles, entity types, or raw coordinates. Use those details as evidence, then explain the drawing in the terms a person would use: rooms, entrances, furniture, doors, fixtures, workstations, corridors, core/service areas, labels, structural elements, mechanical/electrical items, or other project-specific objects.
+
+Do this as evidence-based discovery. Say what the file appears to contain and cite the clues that support it: layer names, block names, text samples, entity counts, and coordinates/handles where useful. Avoid imposing generic assumptions. Different drawings encode meaning differently: one file may identify rooms through text labels, another through room-tag blocks, another through closed polylines, and another not at all. Follow the file's own conventions and translate the underlying CAD structure into concepts users can understand.
+
+Use each command for a different job. `overview` is for clues and vocabulary. `search` is for fuzzy discovery when you have a term from the overview or the user. `query` is for tabular/repeatable questions. `entities` is for raw drilldown after you know what type or layer matters.
+
+Always run `cadcli query <file> --schema` before writing SQL for a file. The query engine exposes narrow in-memory tables: `summary`, `metadata`, `layers`, `blocks`, `entities`, `texts`, and `inserts`.
+
+For a question like "how many rooms are there", use this pattern:
 
 ```bash
-cadcli info <file> --json
 cadcli overview <file>
-cadcli layers <file> --json
-cadcli entities <file> --limit 20 --json
-cadcli search <file> "query" --json
+cadcli query <file> --schema
+cadcli query <file> --sql "select id, text, layer, x, y from texts where text like 'Room%'" --json
 ```
 
+Adapt the query terms to the drawing's language and labels. For Hebrew drawings, text may already be normalized by cadcli, so a room query may use `text like 'חדר%'`. For drawings where rooms are block tags rather than text labels, query `inserts` instead of `texts`.
+
+If the drawing shows furniture or door layers, inspect their `INSERT` entities and block names. Use `cadcli query` for questions like "where are the inserted chair blocks", "which labels start with room", or "which layers have the most entities". If it shows cryptic layers like `A2` or `A3`, infer cautiously from the entity mix and repeated block/text evidence rather than from the layer name alone.
+
+When answering the user, communicate in ordinary language. Use terms like "rooms", "furniture", "doors", "labels", "support spaces", "architectural linework", and "evidence". Do not lead with implementation details like entity types, raw JSON fields, SQL tables, or file internals unless they are needed to justify the answer or the user asks for them.
+
 For visual checks, render an SVG preview:
 
 ```bash