@qaecy/cue-cli 0.0.48 → 0.0.49

package/main.js

@@ -5141,6 +5141,7 @@ var ENDPOINT_COMMANDS_PROFILE_API_KEYS = "/commands/admin/profile/api-keys";
 var ENDPOINT_COMMANDS_PROFILE_TERMS = "/commands/admin/profile/terms";
 var ENDPOINT_ORG_MEMBERS = (orgId) => `/data-views/admin/organizations/${orgId}/members`;
 var ENDPOINT_CREATE_PROJECT = "/commands/admin/project";
+var ENDPOINT_DELETE_PROJECT = (projectId) => `/commands/admin/project/${projectId}`;
 var ENDPOINT_SEARCH = "/assistant/search";
 var ENDPOINT_FUSEKI_QUERY = "/triplestore/query";
 var ENDPOINT_FUSEKI_UPDATE = "/triplestore/update";
@@ -5268,6 +5269,11 @@ var CueAuth = class {
     const result = await (0, import_auth3.signInWithCustomToken)(this._auth, token);
     return result.user;
   }
+  /** Sign in with a Firebase custom token (e.g. minted server-side for MCP/OAuth flows). */
+  async signInWithCustomToken(token) {
+    const result = await (0, import_auth3.signInWithCustomToken)(this._auth, token);
+    return result.user;
+  }
   /** Sign out the current user */
   async signOut() {
     await (0, import_auth3.signOut)(this._auth);
@@ -5422,6 +5428,55 @@ var CueTables = class {
   }
 };
 
+// libs/js/cue-sdk/src/lib/extraction.ts
+var ENDPOINT_EXTRACTION = "/semantic-extraction/extract";
+var CueExtraction = class {
+  constructor(_auth, _gatewayUrl) {
+    this._auth = _auth;
+    this._gatewayUrl = _gatewayUrl;
+  }
+  /**
+   * Run semantic extraction on a document page image.
+   *
+   * Sends a multipart/form-data POST to `/semantic-extraction/extract`.
+   * Always requests JSON-LD so the result can be displayed directly in
+   * `cue-rdf-graph` without any further parsing.
+   */
+  async extract(request) {
+    const fmt = request.rdfFormat ?? "json-ld";
+    const body = new FormData();
+    body.append("file", request.image, "page.png");
+    body.append("template", JSON.stringify(request.template));
+    body.append("space_id", request.projectId);
+    body.append("rdf_format", fmt);
+    if (request.category)
+      body.append("category", request.category);
+    if (request.text)
+      body.append("text", request.text);
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_EXTRACTION}`,
+      {
+        method: "POST",
+        // Do NOT set Content-Type; browser sets it with the correct boundary.
+        headers: {
+          "Accept": "application/ld+json",
+          "x-project-id": request.projectId,
+          "cue-project-id": request.projectId
+        },
+        body
+      }
+    );
+    if (!response.ok) {
+      const msg = await response.text().catch(() => "");
+      throw new Error(
+        `Extraction failed: ${response.status} ${response.statusText}${msg ? " \u2014 " + msg.slice(0, 300) : ""}`
+      );
+    }
+    const jsonld = await response.json();
+    return { jsonld };
+  }
+};
+
 // libs/js/cue-sdk/src/lib/api.ts
 var CueApi = class {
   constructor(_auth, _gatewayUrl, projects, sync) {
@@ -5430,8 +5485,11 @@ var CueApi = class {
     this.projects = projects;
     this.sync = sync;
     this.tables = new CueTables(_auth, _gatewayUrl);
+    this.extraction = new CueExtraction(_auth, _gatewayUrl);
   }
   tables;
+  /** Semantic extraction client — call document pages against a SemanticTemplate. */
+  extraction;
   /** 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. */
@@ -7394,6 +7452,19 @@ var CueProjects = class {
     const fn = (0, import_functions2.httpsCallable)(this._functions, "removeUserFromProject");
     await fn({ uid, spaceId: projectId });
   }
+  /**
+   * Delete a project by ID. Requires superadmin privileges on the server.
+   */
+  async deleteProject(projectId) {
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_DELETE_PROJECT(projectId)}`,
+      { method: "DELETE" }
+    );
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(`Failed to delete project: ${response.status} ${response.statusText}${body ? ` \u2014 ${body}` : ""}`);
+    }
+  }
 };
 
 // libs/js/cue-sdk/src/lib/profile.ts
@@ -7567,6 +7638,7 @@ var REQUIRED_ROLES = {
   createProvider: "superadmin",
   changeContentCategories: "syncer",
   deleteDocuments: "superadmin",
+  deleteProject: "admin",
   deleteUserFromProject: "admin",
   downloadDocuments: "member",
   editContentCategories: "syncer",
@@ -7581,8 +7653,10 @@ function defaultPrivileges() {
   return {
     changeContentCategories: false,
     createEntities: false,
+    createProject: false,
     createProvider: false,
     deleteDocuments: false,
+    deleteProject: false,
     deleteUserFromProject: false,
     downloadDocuments: false,
     editContentCategories: false,
@@ -7598,18 +7672,31 @@ var CuePrivileges = class {
   constructor(_isSuperAdmin) {
     this._isSuperAdmin = _isSuperAdmin;
     this._projectRoles = new CueSignal([]);
+    this._orgRole = new CueSignal(null);
     this.privileges = cueComputed(
-      [this._projectRoles, _isSuperAdmin],
+      [this._projectRoles, this._orgRole, _isSuperAdmin],
       () => this._compute()
     );
   }
   _projectRoles;
+  _orgRole;
   /**
    * Reactive signal — current user's privileges for the selected project.
    * Recomputes automatically when `setProjectRoles()` is called or when
    * the `isSuperAdmin` signal changes.
    */
   privileges;
+  /**
+   * Set the user's role within the organisation that owns the selected project.
+   * Pass `null` to clear the organisation role (e.g. when deselecting a project).
+   *
+   * Only organisation admins (and superadmins) may create projects.
+   */
+  setOrgRole(role) {
+    if (this._orgRole.get() !== role) {
+      this._orgRole.set(role);
+    }
+  }
   /**
    * Set the user's roles for the currently selected project.
    *
@@ -7636,10 +7723,12 @@ var CuePrivileges = class {
   }
   _compute() {
     const roles = this._projectRoles.get();
+    const isSuperAdmin = this._isSuperAdmin.get();
     const result = defaultPrivileges();
     for (const key of Object.keys(REQUIRED_ROLES)) {
       result[key] = roles.includes(REQUIRED_ROLES[key]);
     }
+    result.createProject = isSuperAdmin || this._orgRole.get() === "admin";
     return result;
   }
 };
@@ -7892,11 +7981,12 @@ GROUP BY ?iri ?parent`;
 var OSM_ENDPOINT = "https://qlever.dev/api/osm-planet";
 var EXCLUDE_OSM_RELATION = true;
 var CueProjectEntities = class {
-  constructor(_api, _projectId, rdfBase = RESOURCE_BASE, _queryCache, _graphType) {
+  constructor(_api, _projectId, rdfBase = RESOURCE_BASE, _queryCache, _graphType, _verbose = false) {
     this._api = _api;
     this._projectId = _projectId;
     this._queryCache = _queryCache;
     this._graphType = _graphType;
+    this._verbose = _verbose;
     this.baseURL = `${rdfBase}${_projectId}/`;
     this.entityInfoMap = this._entityInfoMapComputed;
     this.entityGraph = this._entityGraph.asReadonly();
@@ -7916,6 +8006,8 @@ var CueProjectEntities = class {
   _entityOSMMap = new CueSignal({});
   _osmWKTMap = new CueSignal({});
   _fetchingOSMIds = /* @__PURE__ */ new Set();
+  /** Cumulative unique entity UUIDs ever passed to request methods (survives cache hits). */
+  _seenIds = /* @__PURE__ */ new Set();
   _entityGraph = new CueSignal(void 0);
   // ── Derived signals ────────────────────────────────────────────────────────
   _entityInfoMapComputed = cueComputed(
@@ -7940,6 +8032,15 @@ var CueProjectEntities = class {
   entityIri(uuid) {
     return `${this.baseURL}${uuid}`;
   }
+  /** @internal Builds a full resource IRI from a UUID without a SPARQL round-trip. */
+  _resourceIri(uuid) {
+    return `${this.baseURL}${uuid}`;
+  }
+  _log(message) {
+    if (this._verbose) {
+      console.debug(`[CueProjectEntities pid=${this._projectId}] ${message}`);
+    }
+  }
   /**
    * Resets all entity state and re-fetches the entity graph.
    * Call when the active project changes.
@@ -7952,6 +8053,7 @@ var CueProjectEntities = class {
     this._osmWKTMap.set({});
     this._entityGraph.set(void 0);
     this._fetchingOSMIds.clear();
+    this._seenIds.clear();
     this._fetchEntityGraph().catch(
       (err) => console.error(
         "[CueProjectEntities] Entity graph fetch failed after reset:",
@@ -7967,11 +8069,14 @@ var CueProjectEntities = class {
    * Data is merged into `entityInfoMap` once the SPARQL response arrives.
    */
   requestEntityData(uuids, includeMentionCount = false) {
+    for (const id of uuids)
+      this._seenIds.add(id);
     const newUUIDs = uuids.filter(
       (id) => this._entityDetails.get()[id] === void 0
     );
     if (newUUIDs.length === 0)
       return;
+    this._log(`requestEntityData: ${newUUIDs.length} new / ${uuids.length} requested | cumulative: ${this._seenIds.size} seen`);
     const values = newUUIDs.map((id) => `r:${id}`).join(" ");
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
 PREFIX r: <${this.baseURL}>
@@ -8001,6 +8106,7 @@ GROUP BY ?id ?mentionCount`;
         };
       });
       this._entityDetails.set(updates);
+      this._log(`entityDetails: ${Object.keys(updates).length} with metadata / ${this._seenIds.size} seen (cumulative)`);
     }).catch(
       (err) => console.error("[CueProjectEntities] requestEntityData failed:", err)
     );
@@ -8018,6 +8124,9 @@ GROUP BY ?id ?mentionCount`;
     );
     if (newUUIDs.length === 0)
       return;
+    for (const id of uuids)
+      this._seenIds.add(id);
+    this._log(`requestEntityLocations: ${newUUIDs.length} new / ${uuids.length} requested | cumulative: ${this._seenIds.size} seen`);
     const osmInit = { ...this._entityOSMMap.get() };
     for (const id of newUUIDs)
       osmInit[id] = { direct: [], indirect: [] };
@@ -8074,6 +8183,7 @@ WHERE {
       update[id] = entry;
     });
     this._entityOSMMap.set(update);
+    this._log(`entityOSMMap: ${Object.keys(update).length} with OSM / ${this._seenIds.size} seen (cumulative)`);
   }
   /**
    * Fetches incoming and outgoing relationships for a single entity IRI.
@@ -8164,7 +8274,51 @@ ORDER BY ${orderByOccurences ? "DESC(?count)" : "ASC(?label)"}`;
       };
     });
   }
-  async buildSummaryGraph(format) {
+  async entitiesByCategory(categoryIris, includeMetadata = false) {
+    if (categoryIris.length === 0)
+      return [];
+    const ce = CompactExpand.getInstance();
+    const normalise = (iri) => iri.startsWith("http://") || iri.startsWith("https://") ? iri : ce.expandIRI(iri);
+    const values = categoryIris.map((c) => `<${normalise(c)}>`).join(" ");
+    const q = includeMetadata ? `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?id (SAMPLE(?val) AS ?value) (GROUP_CONCAT(DISTINCT STR(?allCat); SEPARATOR=";") AS ?categories)
+WHERE {
+    VALUES ?filterCat { ${values} }
+    ?iri a qcy:CanonicalEntity ;
+         qcy:hasEntityCategory ?filterCat ;
+         qcy:value ?val ;
+         qcy:hasEntityCategory ?allCat .
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}
+GROUP BY ?id` : `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT DISTINCT ?id
+WHERE {
+    VALUES ?filterCat { ${values} }
+    ?iri a qcy:CanonicalEntity ;
+         qcy:hasEntityCategory ?filterCat .
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}`;
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
+    return data.results.bindings.filter((b) => b["id"]).map((b) => {
+      const uuid = b["id"].value;
+      const base = { iri: this._resourceIri(uuid), uuid };
+      if (!includeMetadata)
+        return base;
+      return {
+        ...base,
+        value: b["value"]?.value ?? "",
+        categories: b["categories"]?.value?.split(";").filter(Boolean) ?? []
+      };
+    });
+  }
+  async buildSummaryGraph(format, entityIRI) {
+    const ce = CompactExpand.getInstance();
+    const expandedIRI = entityIRI ? entityIRI.includes("://") ? entityIRI : ce.expandIRI(entityIRI) : void 0;
+    const neighbourFilter = expandedIRI ? `  FILTER(?sourceCat = <${expandedIRI}> || ?targetCat = <${expandedIRI}>)` : "";
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
 SELECT
   ?sourceCat
@@ -8179,6 +8333,7 @@ WHERE {
   ?s ?predicate ?o .
   FILTER(isIRI(?s) && isIRI(?o))
   FILTER(?predicate != qcy:relatedEntity)
+${neighbourFilter}
 }
 GROUP BY ?sourceCat ?predicate ?targetCat
 ORDER BY DESC(?weight)`;
@@ -8208,7 +8363,6 @@ ORDER BY DESC(?weight)`;
       };
     }
     if (format === "md") {
-      const ce = CompactExpand.getInstance();
       const rows = bindings.map((b) => ({
         src: ce.compactIRI(b["sourceCat"].value),
         pred: ce.compactIRI(b["predicate"].value),
@@ -8453,557 +8607,6 @@ SELECT * WHERE {
   }
 };
 
-// libs/js/cue-sdk/src/lib/documents.ts
-var CueProjectDocuments = class {
-  constructor(_api, _projectId, language, rdfBase = RESOURCE_BASE, _queryCache, _graphType) {
-    this._api = _api;
-    this._projectId = _projectId;
-    this._queryCache = _queryCache;
-    this._graphType = _graphType;
-    this.baseURL = `${rdfBase}${_projectId}/`;
-    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;
-  /** Tracks the language for which `_documentInfoMap` is currently populated. */
-  _currentLang;
-  _documentInfoMap = new CueSignal({});
-  _projectDocumentsData = new CueSignal({
-    duplicateCount: 0,
-    documentsBySuffix: {},
-    documentsByContentCategory: {}
-  });
-  /** Lazily populated per-document detail map. */
-  documentInfoMap;
-  /** Project-level document overview (grouped counts + sizes). */
-  projectDocumentsData;
-  // ── Lifecycle ──────────────────────────────────────────────────────────────
-  /**
-   * Resets all document state. Call when the active project changes.
-   * Follow with `fetchOverview()` once the triplestore is ready.
-   */
-  reset() {
-    this._documentInfoMap.set({});
-    this._projectDocumentsData.set({
-      duplicateCount: 0,
-      documentsBySuffix: {},
-      documentsByContentCategory: {}
-    });
-  }
-  /**
-   * Updates the active language and clears the document info map so that
-   * language-sensitive fields (subject, summary) are re-fetched on the next
-   * `requestDocumentData()` call.
-   */
-  setLanguage(lang) {
-    if (this._currentLang === lang)
-      return;
-    this._currentLang = lang;
-    this._api.setLanguage(lang);
-    this._documentInfoMap.set({});
-  }
-  // ── Public API ─────────────────────────────────────────────────────────────
-  /**
-   * Fetches the three-part project overview (by suffix, by content category,
-   * duplicate count) in parallel and writes them as a single atomic update to
-   * `projectDocumentsData`. Safe to call again to refresh.
-   */
-  async fetchOverview() {
-    this._projectDocumentsData.set({
-      duplicateCount: 0,
-      documentsBySuffix: {},
-      documentsByContentCategory: {}
-    });
-    const qSuffix = this._buildDocumentsBySuffixQuery();
-    const qCategory = this._buildDocumentsByContentCategoryQuery();
-    const qDuplicates = this._buildDuplicateCountQuery();
-    await staleWhileRevalidate(
-      qSuffix + qCategory + qDuplicates,
-      async () => {
-        const [bySuffix, byCategory, duplicateCount] = await Promise.all([
-          this._runDocumentsBySuffixQuery(qSuffix),
-          this._runDocumentsByContentCategoryQuery(qCategory),
-          this._runDuplicateCountQuery(qDuplicates)
-        ]);
-        return { duplicateCount, documentsBySuffix: bySuffix, documentsByContentCategory: byCategory };
-      },
-      (overview) => this._projectDocumentsData.set(overview),
-      this._queryCache
-    );
-  }
-  /**
-   * Lazily batch-fetches core metadata for the given document UUIDs.
-   * Already-cached UUIDs are skipped. Data is merged into `documentInfoMap`
-   * once the SPARQL response arrives.
-   */
-  requestDocumentData(uuids) {
-    const newUUIDs = uuids.filter((id) => this._documentInfoMap.get()[id] === void 0);
-    if (newUUIDs.length === 0)
-      return;
-    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
-    (SAMPLE(?fp) AS ?path)
-    (GROUP_CONCAT(DISTINCT ?tag; SEPARATOR=";") AS ?tags)
-    (GROUP_CONCAT(DISTINCT STR(?cat); SEPARATOR=";") AS ?categories)
-WHERE {
-    VALUES ?contentIRI { ${values} }
-    ?contentIRI qcy:sizeBytes ?size ;
-                qcy:hasFileLocation ?loc .
-    ?loc qcy:filePath ?fp ;
-         qcy:suffix ?suffix .
-    OPTIONAL { ?contentIRI qcy:hasContentCategory ?cat }
-    OPTIONAL { ?contentIRI qcy:tag ?tag }
-    OPTIONAL { ?loc qcy:remoteProviderId ?pid }
-
-    OPTIONAL { ?contentIRI qcy:subject ?lang_subj FILTER(LANG(?lang_subj) = "${lang}") }
-    OPTIONAL { ?contentIRI qcy:subject ?no_lang_subj }
-    BIND(COALESCE(?lang_subj, ?no_lang_subj) AS ?subject)
-
-    OPTIONAL { ?contentIRI qcy:textSummary ?lang_summary FILTER(LANG(?lang_summary) = "${lang}") }
-    OPTIONAL { ?contentIRI qcy:textSummary ?no_lang_summary }
-    BIND(COALESCE(?lang_summary, ?no_lang_summary) AS ?summary)
-
-    BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?id)
-}
-GROUP BY ?id ?contentIRI ?suffix ?size ?subject ?summary`;
-    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;
-  }
-  async _fetchDocumentsBySuffix() {
-    return this._runDocumentsBySuffixQuery(this._buildDocumentsBySuffixQuery());
-  }
-  _buildDocumentsBySuffixQuery() {
-    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
-SELECT ?ext (SUM(?size) AS ?totalSize) (COUNT(*) AS ?docCount)
-WHERE {
-  {
-    SELECT DISTINCT ?fc ?ext ?size
-    WHERE {
-      ?fc a qcy:FileContent ;
-          qcy:sizeBytes ?size ;
-          qcy:hasFileLocation/qcy:suffix ?ext .
-      FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
-    }
-  }
-}
-GROUP BY ?ext
-ORDER BY DESC(?docCount)`;
-  }
-  async _runDocumentsBySuffixQuery(q) {
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
-    const result = {};
-    data.results.bindings.forEach((b) => {
-      if (!b["ext"])
-        return;
-      result[b["ext"].value] = {
-        size: b["totalSize"] ? parseInt(b["totalSize"].value, 10) : 0,
-        count: b["docCount"] ? parseInt(b["docCount"].value, 10) : 0
-      };
-    });
-    return result;
-  }
-  async _fetchDocumentsByContentCategory() {
-    return this._runDocumentsByContentCategoryQuery(this._buildDocumentsByContentCategoryQuery());
-  }
-  _buildDocumentsByContentCategoryQuery() {
-    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
-SELECT ?cat (SUM(?size) AS ?totalSize) (COUNT(*) AS ?docCount)
-WHERE {
-  {
-    SELECT DISTINCT ?fc ?cat ?size
-    WHERE {
-      ?fc a qcy:FileContent ;
-          qcy:hasContentCategory ?cat ;
-          qcy:sizeBytes ?size .
-      FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
-    }
-  }
-}
-GROUP BY ?cat
-ORDER BY DESC(?docCount)`;
-  }
-  async _runDocumentsByContentCategoryQuery(q) {
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
-    const result = {};
-    data.results.bindings.forEach((b) => {
-      if (!b["cat"])
-        return;
-      result[b["cat"].value] = {
-        size: b["totalSize"] ? parseInt(b["totalSize"].value, 10) : 0,
-        count: b["docCount"] ? parseInt(b["docCount"].value, 10) : 0
-      };
-    });
-    return result;
-  }
-  async _fetchDuplicateCount() {
-    return this._runDuplicateCountQuery(this._buildDuplicateCountQuery());
-  }
-  _buildDuplicateCountQuery() {
-    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
-SELECT (COUNT(*) AS ?count)
-WHERE {
-  SELECT ?fc
-  WHERE {
-    ?fc a qcy:FileContent ;
-        qcy:hasFileLocation ?fl .
-    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
-  }
-  GROUP BY ?fc
-  HAVING (COUNT(?fl) > 1)
-}`;
-  }
-  async _runDuplicateCountQuery(q) {
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
-    const first = data.results.bindings[0];
-    return first?.["count"] ? parseInt(first["count"].value, 10) : 0;
-  }
-};
-
-// libs/js/cue-sdk/src/lib/project-view.ts
-var CueProjectView = class {
-  constructor(_api, _projectId, { language, queryCache, rdfBase = RESOURCE_BASE, graphType }) {
-    this._api = _api;
-    this._projectId = _projectId;
-    this.schema = new CueProjectSchema(_api, _projectId, language, queryCache, graphType);
-    this.entities = new CueProjectEntities(_api, _projectId, rdfBase, queryCache, graphType);
-    this.documents = new CueProjectDocuments(_api, _projectId, language, rdfBase, queryCache, graphType);
-    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;
-    this.projectDocumentsData = this.documents.projectDocumentsData;
-    this.searchResults = this._searchResults.asReadonly();
-    this.documents.fetchOverview().catch((err) => console.error("[CueProjectView] fetchOverview failed:", err));
-  }
-  /** Direct access to the schema data class (available categories / relationships). */
-  schema;
-  /** Direct access to the entity data class. */
-  entities;
-  /** Direct access to the document data class. */
-  documents;
-  // ── Proxied signals ────────────────────────────────────────────────────────
-  /** Available content category definitions for this project. Auto-fetched on init. */
-  availableContentCategories;
-  /** Available entity category definitions for this project. Auto-fetched on init. */
-  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. */
-  entityGraph;
-  /** Per-document info map. Populated lazily via `requestDocumentData()`. */
-  documentInfoMap;
-  /** Project document overview (counts by suffix and category). Fetched on init. */
-  projectDocumentsData;
-  // ── Search state ───────────────────────────────────────────────────────────
-  _searchResults = new CueSignal(void 0);
-  /** The result of the most recent `search()` call. `undefined` before first search. */
-  searchResults;
-  _destroyed = false;
-  // ── Entity methods ─────────────────────────────────────────────────────────
-  /**
-   * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
-   * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.
-   */
-  requestEntityData(uuids, includeMentionCount = false) {
-    if (this._destroyed)
-      return;
-    this.entities.requestEntityData(uuids, includeMentionCount);
-  }
-  /**
-   * Lazily fetch OSM location data for the given entity UUIDs.
-   * Already-fetched UUIDs are skipped. Populates `entityInfoMap` geometry fields.
-   */
-  async requestEntityLocations(uuids) {
-    if (this._destroyed)
-      return;
-    return this.entities.requestEntityLocations(uuids);
-  }
-  /**
-   * Fetch incoming and outgoing relationships for a single entity IRI.
-   * Result is stored in `entityInfoMap[uuid].relationshipData`.
-   */
-  async fetchEntityRelationships(iri) {
-    if (this._destroyed)
-      throw new Error("CueProjectView is destroyed");
-    return this.entities.fetchEntityRelationships(iri);
-  }
-  /**
-   * Fetch UUIDs of documents that reference the given entity IRI.
-   * Result is stored in `entityInfoMap[uuid].documentRefs`.
-   */
-  async fetchEntityDocuments(iri) {
-    if (this._destroyed)
-      throw new Error("CueProjectView is destroyed");
-    return this.entities.fetchEntityDocuments(iri);
-  }
-  /** Constructs the full RDF IRI for an entity UUID. */
-  entityIri(uuid) {
-    return this.entities.entityIri(uuid);
-  }
-  // ── Document methods ───────────────────────────────────────────────────────
-  /**
-   * Lazily batch-fetch document info for the given UUIDs.
-   * Already-fetched UUIDs are skipped. Populates `documentInfoMap`.
-   */
-  requestDocumentData(uuids) {
-    if (this._destroyed)
-      return;
-    this.documents.requestDocumentData(uuids);
-  }
-  // ── Search ─────────────────────────────────────────────────────────────────
-  /**
-   * Run a natural-language search against the project.
-   * The result is stored in `searchResults` and replaces any previous result.
-   */
-  async search(term, options) {
-    if (this._destroyed)
-      return;
-    const result = await this._api.search({
-      term,
-      projectId: this._projectId,
-      categories: options?.categories
-    });
-    if (!this._destroyed) {
-      this._searchResults.set(result);
-    }
-  }
-  // ── Lifecycle ──────────────────────────────────────────────────────────────
-  /**
-   * Switch the active language for schema labels and document text fields.
-   * Schema responses are cached per language (instant if previously loaded).
-   * The document info map is cleared and lazily re-populated on next access.
-   */
-  setLanguage(lang) {
-    if (this._destroyed)
-      return;
-    this.schema.setLanguage(lang);
-    this.documents.setLanguage(lang);
-  }
-  /**
-   * Reset all entity and document state and re-fetch the project overview.
-   * Prefer creating a fresh `CueProjectView` when switching projects.
-   * Use `reset()` only when the same project's data needs to be invalidated.
-   */
-  reset() {
-    if (this._destroyed)
-      return;
-    this.entities.reset();
-    this.documents.reset();
-    this._searchResults.set(void 0);
-    this.documents.fetchOverview().catch((err) => console.error("[CueProjectView] fetchOverview failed after reset:", err));
-  }
-  /**
-   * Tear down this view instance. Clears all reactive state and blocks further
-   * updates. Call from the Angular adapter's `ngOnDestroy` or equivalent.
-   */
-  destroy() {
-    this._destroyed = true;
-    this._searchResults.set(void 0);
-  }
-};
-
-// libs/js/file-metadata-helpers/src/lib/js-file-metadata-helpers.ts
-init_src();
-
 // libs/js/models/src/lib/file-extensions.ts
 var fileExtensionsInfo = {
   [".aac" /* AAC */]: {
@@ -9866,41 +9469,706 @@ var fileExtensionsInfo = {
   }
 };
 
-// libs/js/models/src/lib/file-mime-categories.ts
-var fileTypeToMimeCategory = {
-  ["audio" /* AUDIO */]: "AudioFileContent" /* AUDIO */,
-  ["video" /* VIDEO */]: "VideoFileContent" /* VIDEO */,
-  ["image" /* IMAGE */]: "ImageFileContent" /* IMAGE */,
-  ["text" /* TEXT */]: "TextFileContent" /* TEXT */,
-  ["markup" /* MARKUP */]: "MarkupFileContent" /* MARKUP */,
-  ["script" /* SCRIPT */]: "ScriptFileContent" /* SCRIPT */,
-  ["data" /* DATA */]: "DataFileContent" /* DATA */,
-  ["archive" /* ARCHIVE */]: "ArchiveFileContent" /* ARCHIVE */,
-  ["installer" /* INSTALLER */]: "InstallerFileContent" /* INSTALLER */,
-  ["binary" /* BINARY */]: "BinaryFileContent" /* BINARY */,
-  ["backup" /* BACKUP */]: "BackupFileContent" /* BACKUP */,
-  ["automation" /* AUTOMATION */]: "AutomationFileContent" /* AUTOMATION */,
-  ["presentation" /* PRESENTATION */]: "PresentationFileContent" /* PRESENTATION */,
-  ["spreadsheet" /* SPREADSHEET */]: "SpreadsheetFileContent" /* SPREADSHEET */,
-  ["font" /* FONT */]: "FontFileContent" /* FONT */,
-  ["geospatial" /* GEOSPATIAL */]: "GeospatialFileContent" /* GEOSPATIAL */,
-  ["3d" /* THREE_D */]: "ThreeDFileContent" /* THREE_D */,
-  ["cad" /* CAD */]: "CADFileContent" /* CAD */,
-  ["bim" /* BIM */]: "BIMFileContent" /* BIM */,
-  ["planning" /* PLANNING */]: "PlanningFileContent" /* PLANNING */,
-  ["email" /* EMAIL */]: "EmailFileContent" /* EMAIL */,
-  ["multimedia" /* MULTIMEDIA */]: "MultimediaFileContent" /* MULTIMEDIA */,
-  ["unknown" /* UNKNOWN */]: "UnknownFileContent" /* UNKNOWN */
+// libs/js/models/src/lib/file-mime-categories.ts
+var fileTypeToMimeCategory = {
+  ["audio" /* AUDIO */]: "AudioFileContent" /* AUDIO */,
+  ["video" /* VIDEO */]: "VideoFileContent" /* VIDEO */,
+  ["image" /* IMAGE */]: "ImageFileContent" /* IMAGE */,
+  ["text" /* TEXT */]: "TextFileContent" /* TEXT */,
+  ["markup" /* MARKUP */]: "MarkupFileContent" /* MARKUP */,
+  ["script" /* SCRIPT */]: "ScriptFileContent" /* SCRIPT */,
+  ["data" /* DATA */]: "DataFileContent" /* DATA */,
+  ["archive" /* ARCHIVE */]: "ArchiveFileContent" /* ARCHIVE */,
+  ["installer" /* INSTALLER */]: "InstallerFileContent" /* INSTALLER */,
+  ["binary" /* BINARY */]: "BinaryFileContent" /* BINARY */,
+  ["backup" /* BACKUP */]: "BackupFileContent" /* BACKUP */,
+  ["automation" /* AUTOMATION */]: "AutomationFileContent" /* AUTOMATION */,
+  ["presentation" /* PRESENTATION */]: "PresentationFileContent" /* PRESENTATION */,
+  ["spreadsheet" /* SPREADSHEET */]: "SpreadsheetFileContent" /* SPREADSHEET */,
+  ["font" /* FONT */]: "FontFileContent" /* FONT */,
+  ["geospatial" /* GEOSPATIAL */]: "GeospatialFileContent" /* GEOSPATIAL */,
+  ["3d" /* THREE_D */]: "ThreeDFileContent" /* THREE_D */,
+  ["cad" /* CAD */]: "CADFileContent" /* CAD */,
+  ["bim" /* BIM */]: "BIMFileContent" /* BIM */,
+  ["planning" /* PLANNING */]: "PlanningFileContent" /* PLANNING */,
+  ["email" /* EMAIL */]: "EmailFileContent" /* EMAIL */,
+  ["multimedia" /* MULTIMEDIA */]: "MultimediaFileContent" /* MULTIMEDIA */,
+  ["unknown" /* UNKNOWN */]: "UnknownFileContent" /* UNKNOWN */
+};
+
+// libs/js/models/src/lib/project.ts
+var import_uuid3 = require("uuid");
+
+// libs/js/models/src/lib/search-log-entry.ts
+var import_uuid4 = require("uuid");
+
+// libs/js/models/src/lib/search-response.ts
+var import_uuid5 = require("uuid");
+
+// libs/js/cue-sdk/src/lib/documents.ts
+var CueProjectDocuments = class {
+  constructor(_api, _projectId, language, rdfBase = RESOURCE_BASE, _queryCache, _graphType, _verbose = false) {
+    this._api = _api;
+    this._projectId = _projectId;
+    this._queryCache = _queryCache;
+    this._graphType = _graphType;
+    this._verbose = _verbose;
+    this.baseURL = `${rdfBase}${_projectId}/`;
+    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;
+  /** Tracks the language for which `_documentInfoMap` is currently populated. */
+  _currentLang;
+  _documentInfoMap = new CueSignal({});
+  /** Cumulative unique document UUIDs ever passed to request methods (survives cache hits). */
+  _seenIds = /* @__PURE__ */ new Set();
+  _projectDocumentsData = new CueSignal({
+    duplicateCount: 0,
+    documentsBySuffix: {},
+    documentsByContentCategory: {}
+  });
+  /** Lazily populated per-document detail map. */
+  documentInfoMap;
+  /** Project-level document overview (grouped counts + sizes). */
+  projectDocumentsData;
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+  /**
+   * Resets all document state. Call when the active project changes.
+   * Follow with `fetchOverview()` once the triplestore is ready.
+   */
+  reset() {
+    this._documentInfoMap.set({});
+    this._seenIds.clear();
+    this._projectDocumentsData.set({
+      duplicateCount: 0,
+      documentsBySuffix: {},
+      documentsByContentCategory: {}
+    });
+  }
+  /**
+   * Updates the active language and clears the document info map so that
+   * language-sensitive fields (subject, summary) are re-fetched on the next
+   * `requestDocumentData()` call.
+   */
+  setLanguage(lang) {
+    if (this._currentLang === lang)
+      return;
+    this._currentLang = lang;
+    this._api.setLanguage(lang);
+    this._documentInfoMap.set({});
+  }
+  // ── Public API ─────────────────────────────────────────────────────────────
+  /**
+   * Fetches the three-part project overview (by suffix, by content category,
+   * duplicate count) in parallel and writes them as a single atomic update to
+   * `projectDocumentsData`. Safe to call again to refresh.
+   */
+  async fetchOverview() {
+    this._projectDocumentsData.set({
+      duplicateCount: 0,
+      documentsBySuffix: {},
+      documentsByContentCategory: {}
+    });
+    const qSuffix = this._buildDocumentsBySuffixQuery();
+    const qCategory = this._buildDocumentsByContentCategoryQuery();
+    const qDuplicates = this._buildDuplicateCountQuery();
+    await staleWhileRevalidate(
+      qSuffix + qCategory + qDuplicates,
+      async () => {
+        const [bySuffix, byCategory, duplicateCount] = await Promise.all([
+          this._runDocumentsBySuffixQuery(qSuffix),
+          this._runDocumentsByContentCategoryQuery(qCategory),
+          this._runDuplicateCountQuery(qDuplicates)
+        ]);
+        return { duplicateCount, documentsBySuffix: bySuffix, documentsByContentCategory: byCategory };
+      },
+      (overview) => this._projectDocumentsData.set(overview),
+      this._queryCache
+    );
+  }
+  /**
+   * Lazily batch-fetches core metadata for the given document UUIDs.
+   * Already-cached UUIDs are skipped. Data is merged into `documentInfoMap`
+   * once the SPARQL response arrives.
+   */
+  requestDocumentData(uuids) {
+    for (const id of uuids)
+      this._seenIds.add(id);
+    const newUUIDs = uuids.filter((id) => this._documentInfoMap.get()[id] === void 0);
+    if (newUUIDs.length === 0)
+      return;
+    this._log(`requestDocumentData: ${newUUIDs.length} new / ${uuids.length} requested | cumulative: ${this._seenIds.size} seen`);
+    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);
+    for (const id of uuids)
+      this._seenIds.add(id);
+    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);
+    for (const id of uuids)
+      this._seenIds.add(id);
+    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;
+  }
+  async documentsBySuffix(suffixes, includeMetadata = false) {
+    if (suffixes.length === 0)
+      return [];
+    const normalised = suffixes.map(
+      (s) => (s.startsWith(".") ? s : `.${s}`).toLowerCase()
+    );
+    const values = normalised.map((s) => `"${s}"`).join(" ");
+    const q = includeMetadata ? `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?id (SAMPLE(?fp) AS ?path) ?suffix (MAX(?sz) AS ?size)
+WHERE {
+    VALUES ?suffix { ${values} }
+    ?iri a qcy:FileContent ;
+         qcy:sizeBytes ?sz ;
+         qcy:hasFileLocation ?loc .
+    ?loc qcy:suffix ?suffix ;
+         qcy:filePath ?fp .
+    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?iri }
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}
+GROUP BY ?id ?suffix` : `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT DISTINCT ?id
+WHERE {
+    VALUES ?suffix { ${values} }
+    ?iri a qcy:FileContent ;
+         qcy:hasFileLocation/qcy:suffix ?suffix .
+    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?iri }
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    return data.results.bindings.filter((b) => b["id"]).map((b) => {
+      const uuid = b["id"].value;
+      const base = { iri: this._resourceIri(uuid), uuid };
+      if (!includeMetadata)
+        return base;
+      return {
+        ...base,
+        path: b["path"]?.value ?? "",
+        suffix: b["suffix"]?.value ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : 0
+      };
+    });
+  }
+  documentsByFileType(fileTypes, includeMetadata = false) {
+    const typeSet = new Set(fileTypes);
+    const suffixes = Object.values(fileExtensionsInfo).filter((info) => typeSet.has(info.type)).map((info) => info.suffix);
+    return this.documentsBySuffix(suffixes, includeMetadata);
+  }
+  async documentsByContentCategory(categoryIRIs, includeMetadata = false) {
+    if (categoryIRIs.length === 0)
+      return [];
+    const values = categoryIRIs.map((iri) => `<${iri}>`).join(" ");
+    const q = includeMetadata ? `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?id (SAMPLE(?fp) AS ?path) ?suffix (MAX(?sz) AS ?size)
+WHERE {
+    VALUES ?cat { ${values} }
+    ?iri a qcy:FileContent ;
+         qcy:hasContentCategory ?cat ;
+         qcy:sizeBytes ?sz ;
+         qcy:hasFileLocation ?loc .
+    ?loc qcy:suffix ?suffix ;
+         qcy:filePath ?fp .
+    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?iri }
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}
+GROUP BY ?id ?suffix` : `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT DISTINCT ?id
+WHERE {
+    VALUES ?cat { ${values} }
+    ?iri a qcy:FileContent ;
+         qcy:hasContentCategory ?cat .
+    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?iri }
+    BIND(REPLACE(STR(?iri), "^.*/", "") AS ?id)
+}`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    return data.results.bindings.filter((b) => b["id"]).map((b) => {
+      const uuid = b["id"].value;
+      const base = { iri: this._resourceIri(uuid), uuid };
+      if (!includeMetadata)
+        return base;
+      return {
+        ...base,
+        path: b["path"]?.value ?? "",
+        suffix: b["suffix"]?.value ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : 0
+      };
+    });
+  }
+  documentsByMime(mimeTypes, includeMetadata = false) {
+    const mimeSet = new Set(mimeTypes);
+    const suffixes = Object.values(fileExtensionsInfo).filter((info) => mimeSet.has(info.mime)).map((info) => info.suffix);
+    return this.documentsBySuffix(suffixes, includeMetadata);
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  /** Builds a full resource IRI from a UUID without a SPARQL round-trip. */
+  _resourceIri(uuid) {
+    return `${this.baseURL}${uuid}`;
+  }
+  _log(message) {
+    if (this._verbose) {
+      console.debug(`[CueProjectDocuments pid=${this._projectId}] ${message}`);
+    }
+  }
+  /** 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 ?suffix ?size ?subject ?summary
+    (SAMPLE(?fp) AS ?path)
+    (GROUP_CONCAT(DISTINCT ?tag; SEPARATOR=";") AS ?tags)
+    (GROUP_CONCAT(DISTINCT STR(?cat); SEPARATOR=";") AS ?categories)
+WHERE {
+    VALUES ?contentIRI { ${values} }
+    ?contentIRI qcy:sizeBytes ?size ;
+                qcy:hasFileLocation ?loc .
+    ?loc qcy:filePath ?fp ;
+         qcy:suffix ?suffix .
+    OPTIONAL { ?contentIRI qcy:hasContentCategory ?cat }
+    OPTIONAL { ?contentIRI qcy:tag ?tag }
+    OPTIONAL { ?loc qcy:remoteProviderId ?pid }
+
+    OPTIONAL { ?contentIRI qcy:subject ?lang_subj FILTER(LANG(?lang_subj) = "${lang}") }
+    OPTIONAL { ?contentIRI qcy:subject ?no_lang_subj }
+    BIND(COALESCE(?lang_subj, ?no_lang_subj) AS ?subject)
+
+    OPTIONAL { ?contentIRI qcy:textSummary ?lang_summary FILTER(LANG(?lang_summary) = "${lang}") }
+    OPTIONAL { ?contentIRI qcy:textSummary ?no_lang_summary }
+    BIND(COALESCE(?lang_summary, ?no_lang_summary) AS ?summary)
+
+    BIND(REPLACE(STR(?contentIRI), "^.*/", "") AS ?id)
+}
+GROUP BY ?id ?suffix ?size ?subject ?summary`;
+    const result = await this._api.sparql(q, this._projectId);
+    const updates = { ...this._documentInfoMap.get() };
+    const fetched = {};
+    result.results.bindings.forEach((b) => {
+      if (!b["id"])
+        return;
+      const id = b["id"].value;
+      const info = {
+        id,
+        contentIRI: this._resourceIri(id),
+        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);
+    this._log(`fetchDocumentInfoBatch: ${Object.keys(fetched).length} fetched | cumulative: ${Object.keys(updates).length} with metadata / ${this._seenIds.size} seen`);
+    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 ?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), "^.*/", "") AS ?id)
+}
+GROUP BY ?id ?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: this._resourceIri(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);
+    this._log(`fetchSimpleDocumentInfoBatch: ${Object.keys(fetched).length} fetched | cumulative: ${Object.keys(updates).length} with metadata / ${this._seenIds.size} seen`);
+    return fetched;
+  }
+  async _fetchDocumentsBySuffix() {
+    return this._runDocumentsBySuffixQuery(this._buildDocumentsBySuffixQuery());
+  }
+  _buildDocumentsBySuffixQuery() {
+    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?ext (SUM(?size) AS ?totalSize) (COUNT(*) AS ?docCount)
+WHERE {
+  {
+    SELECT DISTINCT ?fc ?ext ?size
+    WHERE {
+      ?fc a qcy:FileContent ;
+          qcy:sizeBytes ?size ;
+          qcy:hasFileLocation/qcy:suffix ?ext .
+      FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
+    }
+  }
+}
+GROUP BY ?ext
+ORDER BY DESC(?docCount)`;
+  }
+  async _runDocumentsBySuffixQuery(q) {
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const result = {};
+    data.results.bindings.forEach((b) => {
+      if (!b["ext"])
+        return;
+      result[b["ext"].value] = {
+        size: b["totalSize"] ? parseInt(b["totalSize"].value, 10) : 0,
+        count: b["docCount"] ? parseInt(b["docCount"].value, 10) : 0
+      };
+    });
+    return result;
+  }
+  async _fetchDocumentsByContentCategory() {
+    return this._runDocumentsByContentCategoryQuery(this._buildDocumentsByContentCategoryQuery());
+  }
+  _buildDocumentsByContentCategoryQuery() {
+    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?cat (SUM(?size) AS ?totalSize) (COUNT(*) AS ?docCount)
+WHERE {
+  {
+    SELECT DISTINCT ?fc ?cat ?size
+    WHERE {
+      ?fc a qcy:FileContent ;
+          qcy:hasContentCategory ?cat ;
+          qcy:sizeBytes ?size .
+      FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
+    }
+  }
+}
+GROUP BY ?cat
+ORDER BY DESC(?docCount)`;
+  }
+  async _runDocumentsByContentCategoryQuery(q) {
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const result = {};
+    data.results.bindings.forEach((b) => {
+      if (!b["cat"])
+        return;
+      result[b["cat"].value] = {
+        size: b["totalSize"] ? parseInt(b["totalSize"].value, 10) : 0,
+        count: b["docCount"] ? parseInt(b["docCount"].value, 10) : 0
+      };
+    });
+    return result;
+  }
+  async _fetchDuplicateCount() {
+    return this._runDuplicateCountQuery(this._buildDuplicateCountQuery());
+  }
+  _buildDuplicateCountQuery() {
+    return `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT (COUNT(*) AS ?count)
+WHERE {
+  SELECT ?fc
+  WHERE {
+    ?fc a qcy:FileContent ;
+        qcy:hasFileLocation ?fl .
+    FILTER NOT EXISTS { ?x qcy:alternativeRepresentation ?fc }
+  }
+  GROUP BY ?fc
+  HAVING (COUNT(?fl) > 1)
+}`;
+  }
+  async _runDuplicateCountQuery(q) {
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const first = data.results.bindings[0];
+    return first?.["count"] ? parseInt(first["count"].value, 10) : 0;
+  }
+};
+
+// libs/js/cue-sdk/src/lib/project-view.ts
+var CueProjectView = class {
+  constructor(_api, _projectId, { language, queryCache, rdfBase = RESOURCE_BASE, graphType, verbose }) {
+    this._api = _api;
+    this._projectId = _projectId;
+    this.schema = new CueProjectSchema(_api, _projectId, language, queryCache, graphType);
+    this.entities = new CueProjectEntities(_api, _projectId, rdfBase, queryCache, graphType, verbose);
+    this.documents = new CueProjectDocuments(_api, _projectId, language, rdfBase, queryCache, graphType, verbose);
+    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;
+    this.projectDocumentsData = this.documents.projectDocumentsData;
+    this.searchResults = this._searchResults.asReadonly();
+    this.documents.fetchOverview().catch((err) => console.error("[CueProjectView] fetchOverview failed:", err));
+  }
+  /** Direct access to the schema data class (available categories / relationships). */
+  schema;
+  /** Direct access to the entity data class. */
+  entities;
+  /** Direct access to the document data class. */
+  documents;
+  // ── Proxied signals ────────────────────────────────────────────────────────
+  /** Available content category definitions for this project. Auto-fetched on init. */
+  availableContentCategories;
+  /** Available entity category definitions for this project. Auto-fetched on init. */
+  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. */
+  entityGraph;
+  /** Per-document info map. Populated lazily via `requestDocumentData()`. */
+  documentInfoMap;
+  /** Project document overview (counts by suffix and category). Fetched on init. */
+  projectDocumentsData;
+  // ── Search state ───────────────────────────────────────────────────────────
+  _searchResults = new CueSignal(void 0);
+  /** The result of the most recent `search()` call. `undefined` before first search. */
+  searchResults;
+  _destroyed = false;
+  // ── Entity methods ─────────────────────────────────────────────────────────
+  /**
+   * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
+   * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.
+   */
+  requestEntityData(uuids, includeMentionCount = false) {
+    if (this._destroyed)
+      return;
+    this.entities.requestEntityData(uuids, includeMentionCount);
+  }
+  /**
+   * Lazily fetch OSM location data for the given entity UUIDs.
+   * Already-fetched UUIDs are skipped. Populates `entityInfoMap` geometry fields.
+   */
+  async requestEntityLocations(uuids) {
+    if (this._destroyed)
+      return;
+    return this.entities.requestEntityLocations(uuids);
+  }
+  /**
+   * Fetch incoming and outgoing relationships for a single entity IRI.
+   * Result is stored in `entityInfoMap[uuid].relationshipData`.
+   */
+  async fetchEntityRelationships(iri) {
+    if (this._destroyed)
+      throw new Error("CueProjectView is destroyed");
+    return this.entities.fetchEntityRelationships(iri);
+  }
+  /**
+   * Fetch UUIDs of documents that reference the given entity IRI.
+   * Result is stored in `entityInfoMap[uuid].documentRefs`.
+   */
+  async fetchEntityDocuments(iri) {
+    if (this._destroyed)
+      throw new Error("CueProjectView is destroyed");
+    return this.entities.fetchEntityDocuments(iri);
+  }
+  /** Constructs the full RDF IRI for an entity UUID. */
+  entityIri(uuid) {
+    return this.entities.entityIri(uuid);
+  }
+  // ── Document methods ───────────────────────────────────────────────────────
+  /**
+   * Lazily batch-fetch document info for the given UUIDs.
+   * Already-fetched UUIDs are skipped. Populates `documentInfoMap`.
+   */
+  requestDocumentData(uuids) {
+    if (this._destroyed)
+      return;
+    this.documents.requestDocumentData(uuids);
+  }
+  // ── Search ─────────────────────────────────────────────────────────────────
+  /**
+   * Run a natural-language search against the project.
+   * The result is stored in `searchResults` and replaces any previous result.
+   */
+  async search(term, options) {
+    if (this._destroyed)
+      return;
+    const result = await this._api.search({
+      term,
+      projectId: this._projectId,
+      categories: options?.categories
+    });
+    if (!this._destroyed) {
+      this._searchResults.set(result);
+    }
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+  /**
+   * Switch the active language for schema labels and document text fields.
+   * Schema responses are cached per language (instant if previously loaded).
+   * The document info map is cleared and lazily re-populated on next access.
+   */
+  setLanguage(lang) {
+    if (this._destroyed)
+      return;
+    this.schema.setLanguage(lang);
+    this.documents.setLanguage(lang);
+  }
+  /**
+   * Reset all entity and document state and re-fetch the project overview.
+   * Prefer creating a fresh `CueProjectView` when switching projects.
+   * Use `reset()` only when the same project's data needs to be invalidated.
+   */
+  reset() {
+    if (this._destroyed)
+      return;
+    this.entities.reset();
+    this.documents.reset();
+    this._searchResults.set(void 0);
+    this.documents.fetchOverview().catch((err) => console.error("[CueProjectView] fetchOverview failed after reset:", err));
+  }
+  /**
+   * Tear down this view instance. Clears all reactive state and blocks further
+   * updates. Call from the Angular adapter's `ngOnDestroy` or equivalent.
+   */
+  destroy() {
+    this._destroyed = true;
+    this._searchResults.set(void 0);
+  }
 };
 
-// libs/js/models/src/lib/project.ts
-var import_uuid3 = require("uuid");
-
-// libs/js/models/src/lib/search-log-entry.ts
-var import_uuid4 = require("uuid");
-
-// libs/js/models/src/lib/search-response.ts
-var import_uuid5 = require("uuid");
+// libs/js/file-metadata-helpers/src/lib/js-file-metadata-helpers.ts
+init_src();
 
 // libs/js/rdf-document-writers/src/lib/alternative-representation.ts
 var import_n33 = require("n3");
@@ -10700,6 +10968,7 @@ var Cue = class _Cue {
   _storageProcessed;
   _gis = null;
   _projectDocuments = /* @__PURE__ */ new Map();
+  _verbose;
   /**
    * Reactive GIS service. Lazily constructed on first access.
    *
@@ -10733,6 +11002,7 @@ var Cue = class _Cue {
     const env = config.environment ?? "production";
     this._endpoints = { ...ENDPOINTS[env], ...config.endpoints };
     this._isEmulator = env === "emulator";
+    this._verbose = config.verbose ?? false;
     this._app = (0, import_app2.getApps)().find((a5) => a5.name === "[DEFAULT]") ?? (0, import_app2.initializeApp)({
       apiKey,
       appId,
@@ -10861,7 +11131,7 @@ var Cue = class _Cue {
       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 CueProjectView(this.api, projectId, { ...opts, queryCache });
+    return new CueProjectView(this.api, projectId, { verbose: this._verbose, ...opts, queryCache });
   }
   /**
    * Creates a `CueProjectEntities` instance for the given project, with the
@@ -10890,7 +11160,8 @@ var Cue = class _Cue {
       projectId,
       opts?.rdfBase,
       queryCache,
-      opts?.graphType
+      opts?.graphType,
+      opts?.verbose ?? this._verbose
     );
   }
   /**
@@ -10925,7 +11196,8 @@ var Cue = class _Cue {
         this.api.language,
         void 0,
         queryCache2,
-        void 0
+        void 0,
+        opts?.verbose ?? this._verbose
       );
       this._projectDocuments.set(projectId, docs);
       return docs;
@@ -10940,7 +11212,8 @@ var Cue = class _Cue {
       opts?.language ?? this.api.language,
       opts?.rdfBase,
       queryCache,
-      opts?.graphType
+      opts?.graphType,
+      opts?.verbose ?? this._verbose
     );
   }
 };
@@ -12301,6 +12574,10 @@ async function buildCueClient(options) {
     console.error("API key is required. Provide it via --key or CUE_API_KEY env variable.");
     process.exit(1);
   }
+  if (options.verbose) {
+    const source = options.key ? "--key flag" : "CUE_API_KEY env variable";
+    console.error(`Authenticating with API key from ${source}...`);
+  }
   const cue = new CueNode({
     apiKey: FIREBASE_CONFIG().apiKey,
     appId: FIREBASE_CONFIG().appId,
@@ -12336,21 +12613,32 @@ async function entitySummaryGraphHandler(options) {
   try {
     const cue = await buildCueClient(options);
     if (options.verbose)
-      console.error(`Fetching entity summary graph for project ${options.space}...`);
+      console.error(`Fetching entity summary graph for project ${options.space}${options.entity ? ` (neighbourhood of ${options.entity})` : ""}...`);
     const entities = new CueProjectEntities(cue.api, options.space);
     if (options.format === "graph") {
-      const graph = await entities.buildSummaryGraph("graph");
+      const graph = await entities.buildSummaryGraph("graph", options.entity);
       console.log(JSON.stringify(graph, null, 2));
     } else if (options.format === "md") {
-      const md = await entities.buildSummaryGraph("md");
+      const md = await entities.buildSummaryGraph("md", options.entity);
       console.log(md);
     } else {
-      const raw = await entities.buildSummaryGraph();
+      const raw = await entities.buildSummaryGraph(void 0, options.entity);
       console.log(JSON.stringify(raw, null, 2));
     }
     process.exit(0);
   } catch (err) {
-    console.error("Error:", err instanceof Error ? err.message : String(err));
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("403")) {
+      console.error(`Error: ${msg}`);
+      console.error(
+        `Hint: 403 Forbidden usually means the API key does not have access to project "${options.space}".
+  - If targeting a local environment, add the -e / --emulators flag.
+  - If using a production project, verify the API key has access.
+  - API key source: ${options.key ? "--key flag" : "CUE_API_KEY env variable"}`
+      );
+    } else {
+      console.error("Error:", msg);
+    }
     process.exit(1);
   }
 }
@@ -12384,7 +12672,7 @@ async function sparqlHandler(options) {
 }
 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("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("--entity <iri>", "Filter to the one-hop neighbourhood of this category IRI (prefixed or full, e.g. qcy:Building)").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