@qaecy/cue-cli 0.0.46 → 0.0.48

package/main.js

@@ -372,7 +372,7 @@ var init_md5_builder_node = __esm({
 });
 
 // apps/desktop/cue-cli/src/main.ts
-var import_commander = require("commander");
+var import_commander2 = require("commander");
 var import_fs8 = require("fs");
 var import_path4 = require("path");
 
@@ -4721,6 +4721,53 @@ var prefixCC = {
   rex: "http://purl.obolibrary.org/obo/REX_"
 };
 
+// libs/js/prefixes/src/lib/compact-expand.ts
+var CompactExpand = class _CompactExpand {
+  static _instance;
+  // Opposite map is built once
+  _nsMap;
+  static getInstance() {
+    if (this._instance) {
+      return this._instance;
+    }
+    this._instance = new _CompactExpand();
+    return this._instance;
+  }
+  compactIRI(iri) {
+    let nsMap = this._nsMap;
+    if (nsMap === void 0)
+      nsMap = this._buildNSMap();
+    let ns = iri;
+    if (iri.includes("#"))
+      ns = `${iri.split("#")[0]}#`;
+    else {
+      const parts = iri.split("/");
+      parts.pop();
+      ns = parts.join("/") + "/";
+    }
+    if (ns === void 0)
+      return iri;
+    const pfx = nsMap[ns];
+    if (pfx === void 0)
+      return iri;
+    return iri.replace(ns, `${pfx}:`);
+  }
+  expandIRI(iri) {
+    const prefix = iri.split(":")[0];
+    const ns = prefixCC[prefix] ?? qaecyPrefixes[prefix];
+    return iri.replace(`${prefix}:`, ns);
+  }
+  _buildNSMap() {
+    const map = {};
+    Object.keys(prefixCC).forEach((key) => map[prefixCC[key]] = key);
+    Object.keys(qaecyPrefixes).forEach(
+      (key) => map[qaecyPrefixes[key]] = key
+    );
+    this._nsMap = map;
+    return map;
+  }
+};
+
 // libs/js/sync-tools/src/lib/list-remote-files.ts
 async function listRemoteFiles(spaceId, providerId, queryHandler2, verbose = false) {
   const firebase = CueFirebase.getInstance();
@@ -5097,8 +5144,10 @@ var ENDPOINT_CREATE_PROJECT = "/commands/admin/project";
 var ENDPOINT_SEARCH = "/assistant/search";
 var ENDPOINT_FUSEKI_QUERY = "/triplestore/query";
 var ENDPOINT_FUSEKI_UPDATE = "/triplestore/update";
+var ENDPOINT_FUSEKI_SHACL = "/triplestore/shacl";
 var ENDPOINT_QLEVER_QUERY = "/qlever-server/qlever/query";
 var ENDPOINT_QLEVER_UPDATE = "/qlever-server/qlever/update";
+var ENDPOINT_QLEVER_SHACL = "/qlever-server/qlever/shacl";
 var ENDPOINT_FSS_BATCH = "/commands/file-system-structure/batch";
 var MICROSOFT_PROVIDER_ID = "microsoft.com";
 var SUPERADMIN_ROLE = "superadmin";
@@ -5290,6 +5339,89 @@ var CueAuth = class {
   }
 };
 
+// libs/js/cue-sdk/src/lib/storage.ts
+var CueStorage = class {
+  constructor(_blob) {
+    this._blob = _blob;
+  }
+  /**
+   * Returns a Firebase authenticated download URL for a document stored in Cue.
+   *
+   * The storage path is `{projectId}/{uuid}{suffix}`, e.g. `my-project/abc-123.pdf`.
+   *
+   * @param projectId - The Cue project (space) ID.
+   * @param uuid - The document UUID.
+   * @param suffix - File suffix including the leading dot, e.g. `'.pdf'`, `'.ifc'`.
+   * @param bucket - `'raw'` (default, original uploads) or `'processed'` (derived artefacts).
+   */
+  async getDownloadUrl(projectId, uuid, suffix, bucket = "raw") {
+    const path = `${projectId}/${uuid}${suffix}`;
+    const url = await this._blob.getDownloadURL(bucket, path);
+    if (!url)
+      throw new Error(`File not found in storage: ${path} (bucket: ${bucket})`);
+    return url;
+  }
+  /**
+   * Returns a Firebase authenticated download URL for an alternative representation
+   * using its full `qcy:remoteRelativePath` stored in the processed bucket.
+   *
+   * Use this instead of `getDownloadUrl` when the document info was obtained via
+   * `fetchAlternativeRepresentations` and carries a `remoteRelativePath`.
+   *
+   * @param remoteRelativePath - The full path in the processed bucket,
+   *   e.g. `{projectId}/fragments/{uuid}.fragments`.
+   */
+  async getAltRepDownloadUrl(remoteRelativePath) {
+    const url = await this._blob.getDownloadURL("processed", remoteRelativePath);
+    if (!url)
+      throw new Error(`Alternative representation not found in storage: ${remoteRelativePath}`);
+    return url;
+  }
+};
+
+// libs/js/cue-sdk/src/lib/tables.ts
+var ENDPOINT_DATA_VIEWS_TABLES = "/data-views/tables";
+var ENDPOINT_COMMANDS_TABLES = "/commands/tables";
+var CueTables = class {
+  constructor(_auth, _gatewayUrl) {
+    this._auth = _auth;
+    this._gatewayUrl = _gatewayUrl;
+  }
+  async listTables(projectId) {
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_DATA_VIEWS_TABLES}`,
+      {
+        headers: {
+          "Content-Type": "application/json",
+          "x-project-id": projectId,
+          "cue-project-id": projectId
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to list tables: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+  async saveTables(tables, projectId) {
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_COMMANDS_TABLES}`,
+      {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          "x-project-id": projectId,
+          "cue-project-id": projectId
+        },
+        body: JSON.stringify(tables)
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to save tables: ${response.status} ${response.statusText}`);
+    }
+  }
+};
+
 // libs/js/cue-sdk/src/lib/api.ts
 var CueApi = class {
   constructor(_auth, _gatewayUrl, projects, sync) {
@@ -5297,6 +5429,14 @@ var CueApi = class {
     this._gatewayUrl = _gatewayUrl;
     this.projects = projects;
     this.sync = sync;
+    this.tables = new CueTables(_auth, _gatewayUrl);
+  }
+  tables;
+  /** Active language used for language-sensitive SPARQL queries across all project classes. */
+  language = "en";
+  /** Updates the active language. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this at query time. */
+  setLanguage(lang) {
+    this.language = lang;
   }
   /**
    * Returns standard authentication headers for the current user.
@@ -5368,6 +5508,57 @@ var CueApi = class {
     }
     return response.json();
   }
+  /**
+   * Validate a SHACL shape against the project's triplestore.
+   *
+   * @param shape     - SHACL shapes graph in Turtle syntax.
+   * @param projectId - Project to validate against.
+   * @param options   - `format`: `'json-ld'` (default, structured result) or `'turtle'` (raw string).
+   *                    `verbose`: include server-side timing logs.
+   *
+   * Returns a {@link ShaclValidationReport} for JSON-LD, or a Turtle string.
+   */
+  async shacl(shape, projectId, options) {
+    const fmt = options?.format ?? "json-ld";
+    const accept = fmt === "turtle" ? "text/turtle" : "application/ld+json";
+    if (options?.graphType === "fuseki") {
+      const response2 = await this._auth.authenticatedFetch(
+        `${this._gatewayUrl}${ENDPOINT_FUSEKI_SHACL}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "text/turtle",
+            "Accept": accept,
+            "x-project-id": projectId,
+            "cue-project-id": projectId
+          },
+          body: shape
+        }
+      );
+      if (!response2.ok) {
+        const msg = await response2.text().catch(() => "");
+        throw new Error(`SHACL validation failed: ${response2.status} ${response2.statusText}${msg ? " \u2014 " + msg.slice(0, 200) : ""}`);
+      }
+      return fmt === "turtle" ? response2.text() : response2.json();
+    }
+    const url = `${this._gatewayUrl}${ENDPOINT_QLEVER_SHACL}${options?.verbose ? "?verbose=true" : ""}`;
+    const body = new URLSearchParams({ shape });
+    const response = await this._auth.authenticatedFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": accept,
+        "x-project-id": projectId,
+        "cue-project-id": projectId
+      },
+      body
+    });
+    if (!response.ok) {
+      const msg = await response.text().catch(() => "");
+      throw new Error(`SHACL validation failed: ${response.status} ${response.statusText}${msg ? " \u2014 " + msg.slice(0, 200) : ""}`);
+    }
+    return fmt === "turtle" ? response.text() : response.json();
+  }
   async getConsumption(projectId) {
     const response = await this._auth.authenticatedFetch(
       `${this._gatewayUrl}${ENDPOINT_CONSUMPTION}`,
@@ -7552,19 +7743,20 @@ var CueProjectSchema = class {
     this._projectId = _projectId;
     this._queryCache = _queryCache;
     this._graphType = _graphType;
-    this._language = new CueSignal(language);
+    this._currentLang = language;
+    this._api.setLanguage(language);
     this._contentCategories = new CueSignal([]);
     this._entityCategories = new CueSignal([]);
     this._relationships = new CueSignal([]);
     this.availableContentCategories = this._contentCategories.asReadonly();
     this.availableEntityCategories = this._entityCategories.asReadonly();
     this.availableEntityRelationships = this._relationships.asReadonly();
-    this._load(language).catch(
+    this.ready = this._load(language).catch(
       (err) => console.error("[CueProjectSchema] Initial load failed:", err)
     );
   }
   _cache = /* @__PURE__ */ new Map();
-  _language;
+  _currentLang;
   _contentCategories;
   _entityCategories;
   _relationships;
@@ -7574,9 +7766,14 @@ var CueProjectSchema = class {
   availableEntityCategories;
   /** Currently active entity relationship types for the selected language. */
   availableEntityRelationships;
+  /**
+   * Resolves when the initial schema load for the constructor language has
+   * completed (or failed). Await this before reading signal values imperatively.
+   */
+  ready;
   /** Returns the currently active language. */
   get language() {
-    return this._language.get();
+    return this._api.language;
   }
   /**
    * Switch the active language. If the data for this language has already been
@@ -7584,9 +7781,10 @@ var CueProjectSchema = class {
    * is triggered.
    */
   setLanguage(lang) {
-    if (this._language.get() === lang)
+    if (this._currentLang === lang)
       return;
-    this._language.set(lang);
+    this._currentLang = lang;
+    this._api.setLanguage(lang);
     this._load(lang).catch(
       (err) => console.error("[CueProjectSchema] Language switch failed:", err)
     );
@@ -7596,7 +7794,7 @@ var CueProjectSchema = class {
    * Useful when the triplestore data has changed.
    */
   async refresh() {
-    const lang = this._language.get();
+    const lang = this._api.language;
     this._cache.delete(lang);
     await this._load(lang);
   }
@@ -7622,7 +7820,7 @@ var CueProjectSchema = class {
       },
       (snapshot) => {
         this._cache.set(lang, snapshot);
-        if (this._language.get() === lang)
+        if (this._currentLang === lang)
           this._apply(snapshot);
       },
       this._queryCache
@@ -7711,7 +7909,9 @@ var CueProjectEntities = class {
   baseURL;
   // ── Internal writable slices ───────────────────────────────────────────────
   _entityDetails = new CueSignal({});
-  _entityDocuments = new CueSignal({});
+  _entityDocuments = new CueSignal(
+    {}
+  );
   _entityRelationships = new CueSignal({});
   _entityOSMMap = new CueSignal({});
   _osmWKTMap = new CueSignal({});
@@ -7753,7 +7953,10 @@ var CueProjectEntities = class {
     this._entityGraph.set(void 0);
     this._fetchingOSMIds.clear();
     this._fetchEntityGraph().catch(
-      (err) => console.error("[CueProjectEntities] Entity graph fetch failed after reset:", err)
+      (err) => console.error(
+        "[CueProjectEntities] Entity graph fetch failed after reset:",
+        err
+      )
     );
   }
   // ── Public imperative API ──────────────────────────────────────────────────
@@ -7764,7 +7967,9 @@ var CueProjectEntities = class {
    * Data is merged into `entityInfoMap` once the SPARQL response arrives.
    */
   requestEntityData(uuids, includeMentionCount = false) {
-    const newUUIDs = uuids.filter((id) => this._entityDetails.get()[id] === void 0);
+    const newUUIDs = uuids.filter(
+      (id) => this._entityDetails.get()[id] === void 0
+    );
     if (newUUIDs.length === 0)
       return;
     const values = newUUIDs.map((id) => `r:${id}`).join(" ");
@@ -7782,7 +7987,9 @@ WHERE {
 GROUP BY ?id ?mentionCount`;
     this._api.sparql(q, this._projectId, this._graphType).then((data) => {
       const result = data;
-      const updates = { ...this._entityDetails.get() };
+      const updates = {
+        ...this._entityDetails.get()
+      };
       result.results.bindings.forEach((b) => {
         if (!b["id"])
           return;
@@ -7806,7 +8013,9 @@ GROUP BY ?id ?mentionCount`;
    * query and merged into `entityInfoMap` reactively once it arrives.
    */
   async requestEntityLocations(uuids) {
-    const newUUIDs = uuids.filter((id) => this._entityOSMMap.get()[id] === void 0);
+    const newUUIDs = uuids.filter(
+      (id) => this._entityOSMMap.get()[id] === void 0
+    );
     if (newUUIDs.length === 0)
       return;
     const osmInit = { ...this._entityOSMMap.get() };
@@ -7842,7 +8051,11 @@ WHERE {
   }
   BIND(REPLACE(STR(?iri), "^.*/([^/]*)$", "$1") AS ?id)
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const update = { ...this._entityOSMMap.get() };
     data.results.bindings.forEach((b) => {
       if (!b["id"] || !b["osm"])
@@ -7881,7 +8094,10 @@ WHERE {
       this._fetchIncomingRelationships(iri)
     ]);
     const result = { outgoing, incoming };
-    this._entityRelationships.set({ ...this._entityRelationships.get(), [uuid]: result });
+    this._entityRelationships.set({
+      ...this._entityRelationships.get(),
+      [uuid]: result
+    });
     return result;
   }
   /**
@@ -7905,11 +8121,111 @@ WHERE {
          qcy:about ?iri .
     BIND(REPLACE(STR(?doc), "^.*/([^/]*)$", "$1") AS ?id)
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const ids = data.results.bindings.filter((b) => b["id"] !== void 0).map((b) => b["id"].value);
     this._entityDocuments.set({ ...this._entityDocuments.get(), [uuid]: ids });
     return ids;
   }
+  /**
+   * Fetches all `qcy:EntityCategory` IRIs and their preferred labels for this
+   * project. Uses `api.language` (default `'en'`);
+   * falls back to an untagged label when no match is found.
+   */
+  async contentCategoriesInProject(orderByOccurences = true) {
+    const language = this._api.language;
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+PREFIX skos: <${prefixCC["skos"]}>
+SELECT ?iri (SAMPLE(?l) AS ?label) ?count
+WHERE {
+    ?iri a qcy:EntityCategory .
+    OPTIONAL { ?iri skos:prefLabel ?lang_label FILTER(LANG(?lang_label) = "${language}") }
+    OPTIONAL { ?iri skos:prefLabel ?no_lang_label }
+    BIND(COALESCE(?lang_label, ?no_lang_label) AS ?l)
+    ${orderByOccurences ? "{ SELECT (COUNT(?x) AS ?count) ?iri where { ?x a qcy:CanonicalEntity ; qcy:hasEntityCategory ?iri } GROUP BY ?iri }" : ""}
+}
+GROUP BY ?iri ?count
+ORDER BY ${orderByOccurences ? "DESC(?count)" : "ASC(?label)"}`;
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
+    return data.results.bindings.filter((b) => b["iri"] !== void 0).map((b) => {
+      const count = b["count"] ? parseInt(b["count"].value, 10) : 0;
+      const label = b["label"]?.value ?? b["iri"].value.split("#").at(-1);
+      const labelWithCount = count > 0 ? `${label} (${count})` : label ?? "";
+      return {
+        iri: b["iri"].value,
+        label: labelWithCount
+      };
+    });
+  }
+  async buildSummaryGraph(format) {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT
+  ?sourceCat
+  ?predicate
+  ?targetCat
+  (COUNT(*) AS ?weight)
+WHERE {
+  ?s a qcy:CanonicalEntity ;
+       qcy:hasEntityCategory ?sourceCat .
+  ?o a qcy:CanonicalEntity ;
+       qcy:hasEntityCategory ?targetCat .
+  ?s ?predicate ?o .
+  FILTER(isIRI(?s) && isIRI(?o))
+  FILTER(?predicate != qcy:relatedEntity)
+}
+GROUP BY ?sourceCat ?predicate ?targetCat
+ORDER BY DESC(?weight)`;
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
+    const bindings = data.results.bindings.filter(
+      (b) => b["sourceCat"] && b["predicate"] && b["targetCat"]
+    );
+    if (format === "graph") {
+      const irisSet = /* @__PURE__ */ new Set();
+      const relations = [];
+      for (const b of bindings) {
+        const sourceID = b["sourceCat"].value;
+        const predicate = b["predicate"].value;
+        const targetID = b["targetCat"].value;
+        const weight = parseInt(b["weight"].value, 10);
+        irisSet.add(sourceID);
+        irisSet.add(targetID);
+        relations.push({ sourceID, predicate, targetID, weight });
+      }
+      return {
+        entities: Array.from(irisSet).map((iri) => ({ iri })),
+        relations
+      };
+    }
+    if (format === "md") {
+      const ce = CompactExpand.getInstance();
+      const rows = bindings.map((b) => ({
+        src: ce.compactIRI(b["sourceCat"].value),
+        pred: ce.compactIRI(b["predicate"].value),
+        tgt: ce.compactIRI(b["targetCat"].value),
+        weight: parseInt(b["weight"].value, 10)
+      }));
+      if (rows.length === 0)
+        return "(no results)";
+      const maxSrc = Math.max(...rows.map((r) => r.src.length));
+      const maxPred = Math.max(...rows.map((r) => r.pred.length));
+      const maxTgt = Math.max(...rows.map((r) => r.tgt.length));
+      return rows.map(
+        (r) => `${r.src.padEnd(maxSrc)} -> ${r.pred.padEnd(maxPred)} -> ${r.tgt.padEnd(maxTgt)}  (${r.weight})`
+      ).join("\n");
+    }
+    return data;
+  }
   // ── Private helpers ────────────────────────────────────────────────────────
   _computeEntityInfoMap() {
     const details = this._entityDetails.get();
@@ -7983,7 +8299,11 @@ WHERE {
     FILTER(?rel != qcy:relatedEntity)
 }
 GROUP BY ?rel ?related`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const result = [];
     const detailsUpdate = { ...this._entityDetails.get() };
     data.results.bindings.forEach((b) => {
@@ -8017,7 +8337,11 @@ WHERE {
     FILTER(?rel != qcy:relatedEntity)
 }
 GROUP BY ?rel ?relating`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const result = [];
     const detailsUpdate = { ...this._entityDetails.get() };
     data.results.bindings.forEach((b) => {
@@ -8052,7 +8376,11 @@ GROUP BY ?e1Cat ?e2Cat`;
     await staleWhileRevalidate(
       q,
       async () => {
-        const data = await this._api.sparql(q, this._projectId, this._graphType);
+        const data = await this._api.sparql(
+          q,
+          this._projectId,
+          this._graphType
+        );
         const entities = [];
         const relations = [];
         data.results.bindings.forEach((b) => {
@@ -8109,7 +8437,11 @@ SELECT * WHERE {
         ?s geo:hasGeometry/geo:asWKT ?wkt
     }
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const update = { ...this._osmWKTMap.get() };
     data.results.bindings.forEach((b) => {
       if (!b["s"] || !b["wkt"])
@@ -8129,13 +8461,14 @@ var CueProjectDocuments = class {
     this._queryCache = _queryCache;
     this._graphType = _graphType;
     this.baseURL = `${rdfBase}${_projectId}/`;
-    this._language = language;
+    this._currentLang = language ?? this._api.language;
     this.documentInfoMap = this._documentInfoMap.asReadonly();
     this.projectDocumentsData = this._projectDocumentsData.asReadonly();
   }
   /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
   baseURL;
-  _language;
+  /** Tracks the language for which `_documentInfoMap` is currently populated. */
+  _currentLang;
   _documentInfoMap = new CueSignal({});
   _projectDocumentsData = new CueSignal({
     duplicateCount: 0,
@@ -8165,9 +8498,10 @@ var CueProjectDocuments = class {
    * `requestDocumentData()` call.
    */
   setLanguage(lang) {
-    if (this._language === lang)
+    if (this._currentLang === lang)
       return;
-    this._language = lang;
+    this._currentLang = lang;
+    this._api.setLanguage(lang);
     this._documentInfoMap.set({});
   }
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -8208,8 +8542,128 @@ var CueProjectDocuments = class {
     const newUUIDs = uuids.filter((id) => this._documentInfoMap.get()[id] === void 0);
     if (newUUIDs.length === 0)
       return;
-    const values = newUUIDs.map((id) => `r:${id}`).join(" ");
-    const lang = this._language;
+    this._fetchDocumentInfoBatch(newUUIDs).catch(
+      (err) => console.error("[CueProjectDocuments] requestDocumentData failed:", err)
+    );
+  }
+  /**
+   * Promise-based alternative to {@link requestDocumentData} for non-reactive contexts.
+   *
+   * Resolves with the `DocumentInfo` entries for every requested UUID once the
+   * SPARQL response arrives. UUIDs already present in the cache are returned
+   * immediately without a network request. The result is also written into
+   * `documentInfoMap` so reactive consumers stay in sync.
+   *
+   * UUIDs not found in the triplestore are omitted from the returned map.
+   *
+   * @example
+   * ```ts
+   * const docs = await cueProjectDocs.fetchDocumentData(['uuid1', 'uuid2']);
+   * console.log(docs['uuid1'].subject);
+   * ```
+   */
+  async fetchDocumentData(uuids) {
+    const current = this._documentInfoMap.get();
+    const newUUIDs = uuids.filter((id) => current[id] === void 0);
+    if (newUUIDs.length > 0) {
+      await this._fetchDocumentInfoBatch(newUUIDs);
+    }
+    const updated = this._documentInfoMap.get();
+    return Object.fromEntries(
+      uuids.filter((id) => updated[id] !== void 0).map((id) => [id, updated[id]])
+    );
+  }
+  /**
+   * Fetches a lightweight document metadata shape (id/path/suffix/size) for
+   * the given UUIDs and merges the results into `documentInfoMap`.
+   *
+   * This is useful for list/table contexts that do not need language-tagged
+   * fields (`subject`, `summary`) or category/tag enrichment.
+   *
+   * UUIDs already present in `documentInfoMap` are skipped.
+   */
+  async fetchDocumentDataSimple(uuids) {
+    const current = this._documentInfoMap.get();
+    const newUUIDs = uuids.filter((id) => current[id] === void 0);
+    if (newUUIDs.length > 0) {
+      await this._fetchSimpleDocumentInfoBatch(newUUIDs);
+    }
+    const updated = this._documentInfoMap.get();
+    return Object.fromEntries(
+      uuids.filter((id) => updated[id] !== void 0).map((id) => [id, updated[id]])
+    );
+  }
+  /**
+   * Returns the alternative representations of the given document UUID.
+   *
+   * Alternative representations are derived artefacts stored under
+   * `qcy:alternativeRepresentation` in the triplestore — for example a
+   * `.fragments` BIM tile derived from an `.ifc` source file.
+   *
+   * The returned `DocumentInfo` entries are also merged into
+   * `documentInfoMap` so reactive consumers stay in sync.
+   *
+   * @example
+   * ```ts
+   * const alts = await docs.fetchAlternativeRepresentations('abc-123');
+   * // alts[0].suffix => '.fragments'
+   * ```
+   */
+  async fetchAlternativeRepresentations(uuid) {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+PREFIX r: <${this.baseURL}>
+SELECT ?altId ?contentIRI ?suffix ?rrp
+WHERE {
+  r:${uuid} qcy:alternativeRepresentation ?contentIRI .
+  BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?altId)
+  ?contentIRI qcy:hasFileLocation ?loc .
+  ?loc qcy:suffix ?suffix .
+  OPTIONAL { ?loc qcy:remoteRelativePath ?rrp }
+}`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const updates = { ...this._documentInfoMap.get() };
+    const alts = [];
+    data.results.bindings.forEach((b) => {
+      if (!b["altId"] || !b["contentIRI"])
+        return;
+      const id = b["altId"].value;
+      const info = {
+        id,
+        contentIRI: b["contentIRI"].value,
+        path: "",
+        suffix: b["suffix"]?.value ?? "",
+        size: 0,
+        tags: [],
+        categories: [],
+        remoteRelativePath: b["rrp"]?.value
+      };
+      updates[id] = info;
+      alts.push(info);
+    });
+    this._documentInfoMap.set(updates);
+    return alts;
+  }
+  /**
+   * Returns a single arbitrary file path from the project's triplestore.
+   * Useful for pre-filling path-based query inputs with a realistic example.
+   */
+  async randomFilePath() {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?path
+WHERE {
+    ?fl a qcy:FileLocation ;
+        qcy:filePath ?path .
+}
+LIMIT 1`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    return data.results.bindings[0]?.["path"]?.value ?? null;
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  /** Executes the document-info SPARQL query for the given UUIDs, merges results
+   * into `documentInfoMap`, and returns the newly fetched entries. */
+  async _fetchDocumentInfoBatch(uuids) {
+    const values = uuids.map((id) => `r:${id}`).join(" ");
+    const lang = this._api.language;
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
 PREFIX r: <${this.baseURL}>
 SELECT ?id ?contentIRI ?suffix ?size ?subject ?summary
@@ -8237,32 +8691,73 @@ WHERE {
     BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?id)
 }
 GROUP BY ?id ?contentIRI ?suffix ?size ?subject ?summary`;
-    this._api.sparql(q, this._projectId).then((data) => {
-      const result = data;
-      const updates = { ...this._documentInfoMap.get() };
-      result.results.bindings.forEach((b) => {
-        if (!b["id"] || !b["contentIRI"])
-          return;
-        const id = b["id"].value;
-        updates[id] = {
-          id,
-          contentIRI: b["contentIRI"].value,
-          path: b["path"]?.value ?? "",
-          suffix: b["suffix"]?.value ?? "",
-          size: b["size"] ? parseInt(b["size"].value, 10) : 0,
-          tags: b["tags"]?.value?.split(";").filter(Boolean) ?? [],
-          categories: b["categories"]?.value?.split(";").filter(Boolean) ?? [],
-          subject: b["subject"]?.value,
-          summary: b["summary"]?.value,
-          providerId: b["pid"]?.value
-        };
-      });
-      this._documentInfoMap.set(updates);
-    }).catch(
-      (err) => console.error("[CueProjectDocuments] requestDocumentData failed:", err)
-    );
+    const result = await this._api.sparql(q, this._projectId);
+    const updates = { ...this._documentInfoMap.get() };
+    const fetched = {};
+    result.results.bindings.forEach((b) => {
+      if (!b["id"] || !b["contentIRI"])
+        return;
+      const id = b["id"].value;
+      const info = {
+        id,
+        contentIRI: b["contentIRI"].value,
+        path: b["path"]?.value ?? "",
+        suffix: b["suffix"]?.value ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : 0,
+        tags: b["tags"]?.value?.split(";").filter(Boolean) ?? [],
+        categories: b["categories"]?.value?.split(";").filter(Boolean) ?? [],
+        subject: b["subject"]?.value,
+        summary: b["summary"]?.value,
+        providerId: b["pid"]?.value
+      };
+      updates[id] = info;
+      fetched[id] = info;
+    });
+    this._documentInfoMap.set(updates);
+    return fetched;
+  }
+  /** Executes a reduced document-info query (id/path/suffix/size only), merges
+   * into `documentInfoMap`, and returns newly fetched entries. */
+  async _fetchSimpleDocumentInfoBatch(uuids) {
+    const values = uuids.map((id) => `r:${id}`).join(" ");
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+PREFIX r: <${this.baseURL}>
+SELECT ?id ?contentIRI ?suffix ?size (SAMPLE(?fp) AS ?path)
+WHERE {
+    VALUES ?contentIRI { ${values} }
+    ?contentIRI qcy:sizeBytes ?size ;
+                qcy:hasFileLocation ?loc .
+    ?loc qcy:filePath ?fp ;
+         qcy:suffix ?suffix .
+    BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?id)
+}
+GROUP BY ?id ?contentIRI ?suffix ?size`;
+    const result = await this._api.sparql(q, this._projectId, this._graphType);
+    const updates = { ...this._documentInfoMap.get() };
+    const fetched = {};
+    result.results.bindings.forEach((b) => {
+      if (!b["id"])
+        return;
+      const id = b["id"].value;
+      const existing = updates[id];
+      const info = {
+        id,
+        contentIRI: b["contentIRI"]?.value ?? existing?.contentIRI ?? id,
+        path: b["path"]?.value ?? existing?.path ?? id,
+        suffix: b["suffix"]?.value ?? existing?.suffix ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : existing?.size ?? 0,
+        tags: existing?.tags ?? [],
+        categories: existing?.categories ?? [],
+        subject: existing?.subject,
+        summary: existing?.summary,
+        providerId: existing?.providerId
+      };
+      updates[id] = info;
+      fetched[id] = info;
+    });
+    this._documentInfoMap.set(updates);
+    return fetched;
   }
-  // ── Private helpers ────────────────────────────────────────────────────────
   async _fetchDocumentsBySuffix() {
     return this._runDocumentsBySuffixQuery(this._buildDocumentsBySuffixQuery());
   }
@@ -8364,6 +8859,7 @@ var CueProjectView = class {
     this.availableContentCategories = this.schema.availableContentCategories;
     this.availableEntityCategories = this.schema.availableEntityCategories;
     this.availableEntityRelationships = this.schema.availableEntityRelationships;
+    this.schemaReady = this.schema.ready;
     this.entityInfoMap = this.entities.entityInfoMap;
     this.entityGraph = this.entities.entityGraph;
     this.documentInfoMap = this.documents.documentInfoMap;
@@ -8384,6 +8880,11 @@ var CueProjectView = class {
   availableEntityCategories;
   /** Available entity relationship types. Auto-fetched on init. */
   availableEntityRelationships;
+  /**
+   * Resolves when the initial schema load has completed. Await before reading
+   * schema signal values imperatively.
+   */
+  schemaReady;
   /** Merged per-entity detail map. Populated lazily via `requestEntityData()` etc. */
   entityInfoMap;
   /** Project-level entity co-occurrence graph. Fetched once on init. */
@@ -10191,10 +10692,14 @@ var Cue = class _Cue {
   profile;
   privileges;
   cache;
+  storage;
   _app;
   _endpoints;
   _isEmulator;
+  _storageRaw;
+  _storageProcessed;
   _gis = null;
+  _projectDocuments = /* @__PURE__ */ new Map();
   /**
    * Reactive GIS service. Lazily constructed on first access.
    *
@@ -10238,7 +10743,26 @@ var Cue = class _Cue {
     });
     this.auth = new CueAuth(this._app, this._isEmulator, this._endpoints);
     this.projects = new CueProjects(this.auth, this._app, this._isEmulator, this._endpoints);
+    this._storageRaw = (0, import_storage5.getStorage)(this._app, BUCKET_RAW2);
+    this._storageProcessed = (0, import_storage5.getStorage)(this._app, BUCKET_PROCESSED2);
+    const storagePublic = (0, import_storage5.getStorage)(this._app, BUCKET_PUBLIC2);
+    const storageLogs = (0, import_storage5.getStorage)(this._app, BUCKET_LOGS2);
+    const storageChatSessions = (0, import_storage5.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
+    const storagePersistence = (0, import_storage5.getStorage)(this._app, BUCKET_PERSISTENCE2);
+    if (this._isEmulator) {
+      (0, import_storage5.connectStorageEmulator)(this._storageRaw, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
+      (0, import_storage5.connectStorageEmulator)(this._storageProcessed, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
+    }
     this.api = this._buildApi(this.projects);
+    const blob = new CueBlobStorage({
+      storageRaw: this._storageRaw,
+      storageProcessed: this._storageProcessed,
+      storagePublic,
+      storageLogs,
+      storageChatSessions,
+      storagePersistence
+    });
+    this.storage = new CueStorage(blob);
     this.profile = new CueProfile(
       this.auth,
       this._app,
@@ -10246,7 +10770,6 @@ var Cue = class _Cue {
       this._endpoints.gatewayUrl
     );
     this.privileges = new CuePrivileges(this.auth.isSuperAdmin);
-    const storagePersistence = (0, import_storage5.getStorage)(this._app, BUCKET_PERSISTENCE2);
     if (this._isEmulator) {
       (0, import_storage5.connectStorageEmulator)(storagePersistence, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
     }
@@ -10294,16 +10817,20 @@ var Cue = class _Cue {
     const instance = Object.create(_Cue.prototype);
     const privileges = new CuePrivileges(auth.isSuperAdmin);
     const cache = new CueCache(storagePersistence);
+    const storage = new CueStorage(blob);
     Object.assign(instance, {
       _app: app,
       _endpoints: endpoints,
       _isEmulator: env === "emulator",
+      _storageRaw: storageRaw,
+      _storageProcessed: storageProcessed,
       auth,
       api,
       projects,
       profile,
       privileges,
-      cache
+      cache,
+      storage
     });
     return instance;
   }
@@ -10336,27 +10863,105 @@ var Cue = class _Cue {
     };
     return new CueProjectView(this.api, projectId, { ...opts, queryCache });
   }
+  /**
+   * Creates a `CueProjectEntities` instance for the given project, with the
+   * SDK query cache wired automatically.
+   *
+   * Prefer this over `new CueProjectEntities(cue.api, projectId)` — it avoids
+   * the manual cache setup and keeps the instance bound to the correct API.
+   *
+   * @example
+   * ```ts
+   * const entities = cue.createProjectEntities('my-project');
+   * entities.requestEntityData(['uuid1']);
+   * const info = entities.entityInfoMap.get()['uuid1'];
+   *
+   * // Promise-based (no signal polling needed):
+   * const graph = await entities.buildSummaryGraph('graph');
+   * ```
+   */
+  createProjectEntities(projectId, opts) {
+    const queryCache = opts?.queryCache ?? {
+      get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+      set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+    };
+    return new CueProjectEntities(
+      this.api,
+      projectId,
+      opts?.rdfBase,
+      queryCache,
+      opts?.graphType
+    );
+  }
+  /**
+   * Creates a `CueProjectDocuments` instance for the given project, with the
+   * SDK query cache wired automatically.
+   *
+   * Prefer this over `new CueProjectDocuments(cue.api, projectId)` — it avoids
+   * the manual cache setup and keeps the instance bound to the correct API.
+   *
+   * @example
+   * ```ts
+   * const docs = cue.createProjectDocuments('my-project');
+   * await docs.fetchOverview();
+   * const data = await docs.fetchDocumentData(['uuid1', 'uuid2']);
+   * ```
+   */
+  createProjectDocuments(projectId, opts) {
+    const hasCustomOptions = opts?.language !== void 0 || opts?.rdfBase !== void 0 || opts?.graphType !== void 0 || opts?.queryCache !== void 0;
+    if (!hasCustomOptions) {
+      const existing = this._projectDocuments.get(projectId);
+      if (existing) {
+        existing.setLanguage(this.api.language);
+        return existing;
+      }
+      const queryCache2 = {
+        get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+        set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+      };
+      const docs = new CueProjectDocuments(
+        this.api,
+        projectId,
+        this.api.language,
+        void 0,
+        queryCache2,
+        void 0
+      );
+      this._projectDocuments.set(projectId, docs);
+      return docs;
+    }
+    const queryCache = opts?.queryCache ?? {
+      get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+      set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+    };
+    return new CueProjectDocuments(
+      this.api,
+      projectId,
+      opts?.language ?? this.api.language,
+      opts?.rdfBase,
+      queryCache,
+      opts?.graphType
+    );
+  }
 };
 
 // libs/js/cue-sdk/src/lib/cue-node.ts
-var import_storage6 = require("firebase/storage");
+var import_storage8 = require("firebase/storage");
 var CueNode = class extends Cue {
   constructor(config) {
     super(config);
   }
   _buildApi(projects) {
-    const storageChatSessions = (0, import_storage6.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
-    const storageLogs = (0, import_storage6.getStorage)(this._app, BUCKET_LOGS2);
-    const storageRaw = (0, import_storage6.getStorage)(this._app, BUCKET_RAW2);
-    const storagePersistence = (0, import_storage6.getStorage)(this._app, BUCKET_PERSISTENCE2);
-    const storageProcessed = (0, import_storage6.getStorage)(this._app, BUCKET_PROCESSED2);
-    const storagePublic = (0, import_storage6.getStorage)(this._app, BUCKET_PUBLIC2);
+    const storageChatSessions = (0, import_storage8.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
+    const storageLogs = (0, import_storage8.getStorage)(this._app, BUCKET_LOGS2);
+    const storageRaw = this._storageRaw;
+    const storagePersistence = (0, import_storage8.getStorage)(this._app, BUCKET_PERSISTENCE2);
+    const storageProcessed = this._storageProcessed;
+    const storagePublic = (0, import_storage8.getStorage)(this._app, BUCKET_PUBLIC2);
     if (this._isEmulator) {
       const storageHost = this._endpoints.storageEmulatorHost;
       const storagePort = this._endpoints.storageEmulatorPort;
-      (0, import_storage6.connectStorageEmulator)(storageRaw, storageHost, storagePort);
-      (0, import_storage6.connectStorageEmulator)(storageProcessed, storageHost, storagePort);
-      (0, import_storage6.connectStorageEmulator)(storagePublic, storageHost, storagePort);
+      (0, import_storage8.connectStorageEmulator)(storagePublic, storageHost, storagePort);
     }
     const blob = new CueBlobStorage({
       storageChatSessions,
@@ -10519,21 +11124,21 @@ async function compareHandler(options) {
 }
 
 // apps/desktop/cue-cli/src/helpers/get-files-containing-substring.ts
-var import_storage7 = require("firebase/storage");
+var import_storage9 = require("firebase/storage");
 var import_path2 = require("path");
 var import_promises = require("fs/promises");
 async function getFilesContainingSubstring(bucket, subDir = "", subString = "") {
   const firebase = CueFirebase.getInstance();
   const storage = bucket === "raw" ? firebase.storageRaw : firebase.storageProcessed;
   console.log("Fetching files from storage bucket:", bucket, "in subdir:", subDir, "containing substring:", subString);
-  const listResult = await (0, import_storage7.listAll)((0, import_storage7.ref)(storage, subDir));
+  const listResult = await (0, import_storage9.listAll)((0, import_storage9.ref)(storage, subDir));
   const outputDir = (0, import_path2.join)(process.cwd(), "downloaded_blobs", bucket, subDir);
   await (0, import_promises.mkdir)(outputDir, { recursive: true });
   for (const fileRef of listResult.items) {
     console.log(fileRef.name);
     if (subDir && !fileRef.name.includes(subString))
       continue;
-    const bytes = await (0, import_storage7.getBytes)(fileRef);
+    const bytes = await (0, import_storage9.getBytes)(fileRef);
     const outputPath = (0, import_path2.join)(outputDir, fileRef.name);
     await (0, import_promises.writeFile)(outputPath, Buffer.from(bytes));
     console.log(`Downloaded ${fileRef.name} to ${outputPath} \u2705`);
@@ -10927,16 +11532,16 @@ async function dumpHandler(options) {
 }
 
 // apps/desktop/cue-cli/src/helpers/repair-remote-ttl.ts
-var import_storage8 = require("firebase/storage");
+var import_storage10 = require("firebase/storage");
 async function repairRemoteTTL(space, subString, regex, substituteString) {
   const firebase = CueFirebase.getInstance();
   const storage = firebase.storageProcessed;
   console.log("Fetching files from storage bucket 'triples' containing substring:", subString);
-  const listResult = await (0, import_storage8.listAll)((0, import_storage8.ref)(storage, `${space}/triples`));
+  const listResult = await (0, import_storage10.listAll)((0, import_storage10.ref)(storage, `${space}/triples`));
   for (const fileRef of listResult.items) {
     if (subString && !fileRef.name.match(subString))
       continue;
-    const stream = await (0, import_storage8.getStream)(fileRef);
+    const stream = await (0, import_storage10.getStream)(fileRef);
     const reader = stream.getReader();
     const chunks = [];
     let done = false;
@@ -10960,13 +11565,13 @@ async function repairRemoteTTL(space, subString, regex, substituteString) {
       const buffer = Buffer.from(fileContent, "utf8");
       let existingMetadata = {};
       try {
-        existingMetadata = await (0, import_storage8.getMetadata)(fileRef);
+        existingMetadata = await (0, import_storage10.getMetadata)(fileRef);
       } catch (err) {
         console.warn(`Could not fetch metadata for ${fileRef.name}, proceeding with default.`);
       }
       const customMetadata = { ...existingMetadata.customMetadata || {}, stored: "False" };
       const metadata = { customMetadata };
-      await (0, import_storage8.uploadBytesResumable)((0, import_storage8.ref)(storage, `${space}/triples/${fileRef.name}`), buffer, metadata);
+      await (0, import_storage10.uploadBytesResumable)((0, import_storage10.ref)(storage, `${space}/triples/${fileRef.name}`), buffer, metadata);
       console.log(`Fixed ${fileRef.name} \u2705`);
     } else {
       console.log(`No changes for ${fileRef.name}`);
@@ -11201,10 +11806,17 @@ async function syncHandler(options) {
     process.exit(0);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error ? err.cause : void 0;
+    const causeCode = cause instanceof Error ? cause.code : void 0;
+    const causeMsg = cause instanceof Error ? cause.message : void 0;
+    const isTimeout = causeCode === "UND_ERR_HEADERS_TIMEOUT" || causeCode === "UND_ERR_BODY_TIMEOUT" || causeCode === "UND_ERR_CONNECT_TIMEOUT" || causeMsg?.includes("Timeout") || msg.includes("fetch failed");
     if (msg.includes("GRAPH_UNAVAILABLE")) {
       console.error("The knowledge graph for this project has no database configured. Contact your administrator or check the project setup.");
-    } else if (msg.includes("GRAPH_TIMEOUT")) {
-      console.error("Could not reach the knowledge graph. Make sure all required services are running.");
+    } else if (msg.includes("GRAPH_TIMEOUT") || isTimeout) {
+      console.error("Could not reach the QAECY API \u2014 the request timed out or the server could not be reached.");
+      console.error("Check your internet connection and try again. If the problem persists, the service may be temporarily unavailable.");
+      if (verbose && causeCode)
+        console.error(`  Cause: ${causeMsg ?? causeCode}`);
     } else if (msg.includes("METADATA_SYNC_FAILED")) {
       console.error("Metadata sync failed. Try again.");
     } else if (msg.includes("LEDGER_WRITE_FAILED") || msg.includes("File structure batch POST failed")) {
@@ -11212,7 +11824,13 @@ async function syncHandler(options) {
         "Failed communication with the knowledge graph. The files are up to date but metadata is not. Run the tool again to sync metadata. This is a swift job."
       );
     } else {
-      console.error("[syncHandler] Unexpected error:", err);
+      console.error("An unexpected error occurred during sync.");
+      if (verbose) {
+        console.error("Details:", err);
+      } else {
+        console.error(`  ${msg}`);
+        console.error("Re-run with --verbose for more details.");
+      }
     }
     process.exit(1);
   }
@@ -11675,6 +12293,100 @@ Project created \u2705`);
   }
 }
 
+// apps/desktop/cue-cli/src/cue-cli-app-builder-tools.ts
+var import_commander = require("commander");
+async function buildCueClient(options) {
+  const key = options.key ?? process.env["CUE_API_KEY"];
+  if (!key) {
+    console.error("API key is required. Provide it via --key or CUE_API_KEY env variable.");
+    process.exit(1);
+  }
+  const cue = new CueNode({
+    apiKey: FIREBASE_CONFIG().apiKey,
+    appId: FIREBASE_CONFIG().appId,
+    measurementId: FIREBASE_CONFIG().measurementId,
+    environment: options.emulators ? "emulator" : "production",
+    ...options.emulators ? { endpoints: getEmulatorEndpoints() } : {}
+  });
+  await cue.auth.signInWithApiKey(key);
+  return cue;
+}
+async function listProjectsHandler(options) {
+  try {
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      console.error("Fetching projects...");
+    const projects = await cue.api.projects.listProjects();
+    const output = projects.map((p) => ({
+      id: p.id,
+      name: p.name,
+      organizationID: p.organizationID,
+      isPublic: p.isPublic,
+      graphType: p.projectSettings?.graph?.type ?? "qlever",
+      lastSync: p.lastSync
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function entitySummaryGraphHandler(options) {
+  try {
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      console.error(`Fetching entity summary graph for project ${options.space}...`);
+    const entities = new CueProjectEntities(cue.api, options.space);
+    if (options.format === "graph") {
+      const graph = await entities.buildSummaryGraph("graph");
+      console.log(JSON.stringify(graph, null, 2));
+    } else if (options.format === "md") {
+      const md = await entities.buildSummaryGraph("md");
+      console.log(md);
+    } else {
+      const raw = await entities.buildSummaryGraph();
+      console.log(JSON.stringify(raw, null, 2));
+    }
+    process.exit(0);
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function sparqlHandler(options) {
+  try {
+    let sparqlQuery = options.query;
+    if (!sparqlQuery) {
+      if (process.stdin.isTTY) {
+        console.error("Provide a SPARQL query via --query or pipe it via stdin.");
+        process.exit(1);
+      }
+      const chunks = [];
+      for await (const chunk of process.stdin)
+        chunks.push(chunk);
+      sparqlQuery = Buffer.concat(chunks).toString("utf8").trim();
+    }
+    if (!sparqlQuery) {
+      console.error("SPARQL query is empty.");
+      process.exit(1);
+    }
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      console.error(`Executing SPARQL query against project ${options.space}...`);
+    const result = await cue.api.sparql(sparqlQuery, options.space);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+var appBuilderToolsCommand = new import_commander.Command("app-builder-tools").description("Tools for agent-assisted Cue app development. Outputs JSON for machine consumption.");
+appBuilderToolsCommand.command("list-projects").description("List all projects accessible to the authenticated user").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-v, --verbose", "Enable verbose output", false).action(listProjectsHandler);
+appBuilderToolsCommand.command("entity-summary-graph").description("Fetch the entity category relationship summary graph for a project").requiredOption("-s, --space <id>", "Project ID (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-f, --format <format>", "Output format: md (aligned text), graph (JSON nodes+edges), json (raw SPARQL)", "md").option("-v, --verbose", "Enable verbose output", false).action(entitySummaryGraphHandler);
+appBuilderToolsCommand.command("sparql").description("Execute a SPARQL SELECT query against a project triplestore. Query via --query or stdin.").requiredOption("-s, --space <id>", "Project ID (required)").option("-q, --query <sparql>", "SPARQL query string (or pipe query via stdin)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-v, --verbose", "Enable verbose output", false).action(sparqlHandler);
+
 // apps/desktop/cue-cli/src/main.ts
 var packageJson;
 try {
@@ -11687,7 +12399,7 @@ try {
     console.warn("Could not find package.json, using fallback version");
   }
 }
-var program = new import_commander.Command();
+var program = new import_commander2.Command();
 program.name("cue-cli").description("Cue Command Line Interface").version(packageJson.version);
 program.command("sync").description("Sync files to Cue").option("-s, --space <id>", "Specify the space ID (omit to pick interactively)").requiredOption("-p, --path <id>", "Specify the folder path (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("--provider <provider ID>", "Specify the provider ID (eg. sharepoint, drive, dropbox) or leave empty for default provider", "").option("-v, --verbose", "Enable verbose output", false).option("-e, --emulators", "Uses emulators for sync", false).option("-z, --zip", 'Include zipped content (will be unzipped to path "<zip_path>_unzipped". Max uncompressed size: 500 MB, max recursion depth: 3)', false).option("--legacy", "Write RDF as BLOBs to the processed bucket instead of patching the graph directly", false).option("--metadata-only", "Push filesystem-structure metadata for all local files without checking credits or remote state", false).action(syncHandler);
 program.command("dump").description("Dump Cue Knowledge Graph data to file\n				Examples:\n				$ cue-cli dump -s <space_id> -l -v\n				$ cue-cli dump -s <space_id> -j -v").requiredOption("-s, --space <id>", "Specify the space ID (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-v, --verbose", "Enable verbose output", false).option("-e, --emulators", "Uses emulators for sync", false).option("-q, --query", "Uses a construct query to get the dump rather than using the /data endpoint", false).option("-j, --jelly", "Downloads a Jelly file rather than the standard Gzipped NQuads format", false).option("-l, --load", "Loads the dumped file into a local triplestore (requires emulators)", false).action(dumpHandler);
@@ -11697,4 +12409,5 @@ program.command("repair-ttl").description("Repair TTL files in the specified spa
 program.command("util-rdf-compare").description("Compare two Turtle (.ttl) files and report semantic differences").requiredOption("--file1 <path>", "Path to the first TTL file").requiredOption("--file2 <path>", "Path to the second TTL file").option("-v, --verbose", "Enable verbose output", false).action(utilRdfCompareHandler);
 program.command("util-remove-rdf-star").description("Remove RDF-star (quoted) triples from an NQuads file. Supports .nq and .nq.gz input/output.").requiredOption("-i, --input <path>", "Input file path (.nq or .nq.gz)").requiredOption("-o, --output <path>", "Output file path (.nq or .nq.gz)").option("-v, --verbose", "Enable verbose output", false).action(utilRemoveRdfStarHandler);
 program.command("create-project").description("Interactively create a new project under an organisation").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Uses emulators", false).option("-v, --verbose", "Enable verbose output", false).action(createProjectHandler);
+program.addCommand(appBuilderToolsCommand);
 program.parse(process.argv);