ltcai 2.2.7 → 3.1.0

package/latticeai/services/search_service.py

@@ -0,0 +1,346 @@
+"""Backend search orchestration for Lattice AI v3.
+
+The service composes the existing knowledge graph, the local vector index, and
+keyword search into UI-ready contracts without tying routers to store internals.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Mapping, Optional
+
+
+DEFAULT_HYBRID_WEIGHTS = {
+    "keyword": 0.35,
+    "vector": 0.40,
+    "graph": 0.25,
+}
+
+
+def _clean(text: Any, limit: int = 1000) -> str:
+    return " ".join(str(text or "").split())[:limit]
+
+
+def _result_key(result: Mapping[str, Any]) -> str:
+    return str(result.get("id") or result.get("node_id") or "")
+
+
+@dataclass
+class SearchService:
+    graph_store: Any
+
+    def _require_graph(self) -> Any:
+        if self.graph_store is None:
+            raise ValueError("knowledge graph is disabled")
+        return self.graph_store
+
+    def keyword_search(self, query: str, *, limit: int = 30) -> Dict[str, Any]:
+        graph = self._require_graph()
+        payload = graph.search(query, limit)
+        matches = []
+        for rank, match in enumerate(payload.get("matches", []), start=1):
+            matches.append({
+                "id": match["id"],
+                "node_id": match["id"],
+                "item_type": "node",
+                "type": match.get("type"),
+                "title": match.get("title"),
+                "summary": _clean(match.get("summary")),
+                "score": round(1.0 / rank, 6),
+                "rank": rank,
+                "sources": ["keyword"],
+                "source_scores": {"keyword": round(1.0 / rank, 6)},
+                "metadata": match.get("metadata") or {},
+                "updated_at": match.get("updated_at"),
+            })
+        return {"query": query, "mode": "keyword", "matches": matches}
+
+    def vector_search(self, query: str, *, limit: int = 30, min_score: float = 0.0) -> Dict[str, Any]:
+        graph = self._require_graph()
+        payload = graph.vector_search(query, limit=limit, min_score=min_score)
+        matches = []
+        for rank, match in enumerate(payload.get("matches", []), start=1):
+            score = float(match.get("score") or 0.0)
+            matches.append({
+                "id": match.get("id"),
+                "node_id": match.get("node_id"),
+                "item_type": match.get("item_type"),
+                "type": match.get("type"),
+                "title": match.get("title"),
+                "summary": _clean(match.get("summary")),
+                "score": round(score, 6),
+                "rank": rank,
+                "sources": ["vector"],
+                "source_scores": {"vector": round(score, 6)},
+                "metadata": match.get("metadata") or {},
+                "updated_at": match.get("updated_at"),
+            })
+        return {
+            "query": query,
+            "mode": "vector",
+            "embedding_model": payload.get("embedding_model"),
+            "embedding_dim": payload.get("embedding_dim"),
+            "matches": matches,
+        }
+
+    def graph_search(self, query: str, *, limit: int = 30, expand_depth: int = 1) -> Dict[str, Any]:
+        graph = self._require_graph()
+        limit = max(1, min(int(limit or 30), 100))
+        expand_depth = max(0, min(int(expand_depth or 1), 3))
+        direct = graph.search(query, limit=max(limit, 10)).get("matches", [])
+        relationships = graph.relationship_search(query=query, limit=limit).get("relationships", [])
+        by_id: Dict[str, Dict[str, Any]] = {}
+
+        def add_node(node: Mapping[str, Any], score: float, reason: str, edge: Optional[Mapping[str, Any]] = None) -> None:
+            node_id = str(node.get("id") or "")
+            if not node_id:
+                return
+            current = by_id.get(node_id)
+            if not current:
+                current = {
+                    "id": node_id,
+                    "node_id": node_id,
+                    "item_type": "node",
+                    "type": node.get("type"),
+                    "title": node.get("title"),
+                    "summary": _clean(node.get("summary")),
+                    "score": 0.0,
+                    "sources": ["graph"],
+                    "source_scores": {"graph": 0.0},
+                    "metadata": node.get("metadata") or {},
+                    "updated_at": node.get("updated_at"),
+                    "graph_context": [],
+                }
+                by_id[node_id] = current
+            current["score"] = max(float(current["score"]), score)
+            current["source_scores"]["graph"] = max(float(current["source_scores"]["graph"]), score)
+            context = {"reason": reason}
+            if edge:
+                context["relationship"] = {
+                    "id": edge.get("id"),
+                    "type": edge.get("type"),
+                    "weight": edge.get("weight"),
+                    "from": edge.get("from") or (edge.get("source") or {}).get("id"),
+                    "to": edge.get("to") or (edge.get("target") or {}).get("id"),
+                }
+            current["graph_context"].append(context)
+
+        for rank, match in enumerate(direct, start=1):
+            add_node(match, 1.0 / rank, "direct_match")
+            if expand_depth <= 0:
+                continue
+            try:
+                neighborhood = graph.traverse(match["id"], depth=expand_depth, limit=limit * 3)
+            except Exception:
+                neighborhood = {"nodes": [], "edges": []}
+            edge_by_pair = {
+                (edge.get("from"), edge.get("to")): edge
+                for edge in neighborhood.get("edges", [])
+            }
+            for node in neighborhood.get("nodes", []):
+                if node.get("id") == match.get("id"):
+                    continue
+                related_edge = None
+                for pair, edge in edge_by_pair.items():
+                    if match.get("id") in pair and node.get("id") in pair:
+                        related_edge = edge
+                        break
+                add_node(node, 0.45 / rank, "neighbor_expansion", related_edge)
+
+        for rank, rel in enumerate(relationships, start=1):
+            rel_score = 0.75 / rank
+            add_node(rel.get("source") or {}, rel_score, "relationship_match", rel)
+            add_node(rel.get("target") or {}, rel_score, "relationship_match", rel)
+
+        matches = sorted(by_id.values(), key=lambda item: item["score"], reverse=True)[:limit]
+        for rank, match in enumerate(matches, start=1):
+            match["rank"] = rank
+            match["score"] = round(float(match["score"]), 6)
+            match["source_scores"]["graph"] = round(float(match["source_scores"]["graph"]), 6)
+        return {"query": query, "mode": "graph", "expand_depth": expand_depth, "matches": matches}
+
+    def hybrid_search(
+        self,
+        query: str,
+        *,
+        limit: int = 30,
+        keyword_limit: int = 30,
+        vector_limit: int = 30,
+        graph_limit: int = 30,
+        weights: Optional[Mapping[str, float]] = None,
+    ) -> Dict[str, Any]:
+        weights = {**DEFAULT_HYBRID_WEIGHTS, **dict(weights or {})}
+        channels = {
+            "keyword": self.keyword_search(query, limit=keyword_limit),
+            "vector": self.vector_search(query, limit=vector_limit),
+            "graph": self.graph_search(query, limit=graph_limit),
+        }
+        fused: Dict[str, Dict[str, Any]] = {}
+        for source, payload in channels.items():
+            source_weight = float(weights.get(source, 0.0))
+            for rank, result in enumerate(payload.get("matches", []), start=1):
+                key = _result_key(result)
+                if not key:
+                    continue
+                source_score = float((result.get("source_scores") or {}).get(source, result.get("score") or 0.0))
+                rank_score = 1.0 / rank
+                contribution = source_weight * max(source_score, rank_score)
+                current = fused.get(key)
+                if not current:
+                    current = {
+                        **result,
+                        "sources": [],
+                        "source_scores": {},
+                        "score": 0.0,
+                    }
+                    fused[key] = current
+                current["score"] = float(current["score"]) + contribution
+                if source not in current["sources"]:
+                    current["sources"].append(source)
+                current["source_scores"][source] = round(source_score, 6)
+                if result.get("graph_context"):
+                    current.setdefault("graph_context", [])
+                    current["graph_context"].extend(result.get("graph_context") or [])
+
+        matches = sorted(fused.values(), key=lambda item: item["score"], reverse=True)[: max(1, min(limit, 100))]
+        for rank, match in enumerate(matches, start=1):
+            match["rank"] = rank
+            match["score"] = round(float(match["score"]), 6)
+            match["fusion"] = {
+                "weights": weights,
+                "sources": match.get("sources", []),
+            }
+        return {
+            "query": query,
+            "mode": "hybrid",
+            "weights": weights,
+            "channels": {
+                name: {
+                    key: value
+                    for key, value in payload.items()
+                    if key not in {"matches"}
+                }
+                for name, payload in channels.items()
+            },
+            "matches": matches,
+        }
+
+    def graph(self, *, limit: int = 300) -> Dict[str, Any]:
+        return self._require_graph().graph(limit=limit)
+
+    def node(self, node_id: str, *, include_neighbors: bool = True, depth: int = 1, limit: int = 100) -> Dict[str, Any]:
+        graph = self._require_graph()
+        payload = {"node": graph.get_node(node_id)}
+        if include_neighbors:
+            payload["neighborhood"] = graph.traverse(node_id, depth=depth, limit=limit)
+        return payload
+
+    def relationships(
+        self,
+        *,
+        query: str = "",
+        node_id: str = "",
+        relationship_type: str = "",
+        limit: int = 30,
+    ) -> Dict[str, Any]:
+        return self._require_graph().relationship_search(
+            query=query,
+            node_id=node_id,
+            relationship_type=relationship_type,
+            limit=limit,
+        )
+
+    def index_status(self) -> Dict[str, Any]:
+        return self._require_graph().index_status()
+
+    def embeddings_status(
+        self,
+        *,
+        resolved: Optional[Mapping[str, Any]] = None,
+        refresh: bool = False,
+    ) -> Dict[str, Any]:
+        """Report the active embedding provider for the Models → Embeddings UI.
+
+        Combines the resolved-provider info (requested vs active, fallback,
+        health) with the vector index's identity and last build time. The
+        ``state`` is one of ``production`` | ``fallback`` | ``unavailable`` so
+        the UI never shows a down provider as live.
+        """
+        resolved = dict(resolved or {})
+        graph = self.graph_store
+        embedder = getattr(graph, "_embedding_model", None)
+
+        meta: Dict[str, Any] = {}
+        if embedder is not None and hasattr(embedder, "metadata"):
+            try:
+                meta = dict(embedder.metadata())
+            except Exception:
+                meta = {}
+        else:  # legacy LocalEmbeddingModel
+            meta = {
+                "provider": "hash",
+                "model": getattr(embedder, "model_id", "lattice-local-hash-v1"),
+                "model_id": getattr(embedder, "model_id", "lattice-local-hash-v1"),
+                "dim": getattr(embedder, "dim", 384),
+                "grade": "fallback",
+            }
+
+        health = resolved.get("health") or {"status": "unknown", "detail": ""}
+        if refresh and embedder is not None and hasattr(embedder, "health"):
+            try:
+                health = embedder.health()
+            except Exception as exc:  # pragma: no cover - defensive
+                health = {"status": "unavailable", "detail": str(exc)}
+
+        fell_back = bool(resolved.get("fell_back"))
+        grade = str(meta.get("grade") or ("fallback" if fell_back else "production"))
+        if fell_back or health.get("status") == "unavailable":
+            state = "unavailable" if fell_back else "fallback"
+        else:
+            state = "fallback" if grade == "fallback" else "production"
+
+        index: Dict[str, Any] = {}
+        last_indexed_at = None
+        if graph is not None:
+            try:
+                status = graph.index_status()
+                index = {
+                    "status": status.get("status"),
+                    "source_items": status.get("source_items"),
+                    "indexed_items": status.get("indexed_items"),
+                    "ready_items": status.get("ready_items"),
+                    "pending_items": status.get("pending_items"),
+                    "stale_items": status.get("stale_items"),
+                    "embedding_model": (status.get("storage") or {}).get("embedding_model"),
+                    "embedding_dim": (status.get("storage") or {}).get("embedding_dim"),
+                }
+                for op in status.get("operations", []):
+                    if op.get("status") == "completed" and op.get("completed_at"):
+                        last_indexed_at = op.get("completed_at")
+                        break
+            except Exception as exc:  # pragma: no cover - defensive
+                index = {"error": str(exc)}
+
+        return {
+            "provider": meta.get("provider"),
+            "requested_provider": resolved.get("requested_provider") or meta.get("provider"),
+            "active_provider": resolved.get("active_provider") or meta.get("provider"),
+            "model": meta.get("model"),
+            "model_id": meta.get("model_id"),
+            "dimensions": meta.get("dim"),
+            "grade": grade,
+            "state": state,
+            "fell_back": fell_back,
+            "health": health,
+            "detail": resolved.get("detail", ""),
+            "last_indexed_at": last_indexed_at,
+            "index": index,
+            "available_providers": list(resolved.get("available_providers") or []),
+        }
+
+    def rebuild_index(self, *, full: bool = False, include_nodes: bool = True, include_chunks: bool = True) -> Dict[str, Any]:
+        return self._require_graph().rebuild_vector_index(
+            full=full,
+            include_nodes=include_nodes,
+            include_chunks=include_chunks,
+        )

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ltcai",
-  "version": "2.2.7",
-  "description": "Local-first AI workspace for knowledge graphs, AI pipelines, and multi-agent coding workflows.",
+  "version": "3.1.0",
+  "description": "Lattice AI v3 local-first AI workspace platform with knowledge graph, vector index, hybrid search, agents, and workspace modes.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
     "type": "git",
@@ -17,10 +17,12 @@
   "scripts": {
     "start": "LTCAI",
     "dev": "python3 ltcai_cli.py --reload",
-    "build": "npm run build:python",
+    "build": "npm run build:assets && npm run build:python",
+    "build:assets": "node scripts/build_v3_assets.mjs",
     "build:python": "python3 -m build",
-    "check:python": "python3 -m py_compile ltcai_cli.py server.py latticeai/server_app.py latticeai/api/chat.py latticeai/api/computer_use.py latticeai/api/deps.py latticeai/api/garden.py latticeai/api/local_files.py latticeai/api/permissions.py latticeai/api/setup.py latticeai/api/static_routes.py latticeai/api/tools.py latticeai/api/plugins.py latticeai/api/workflow_designer.py latticeai/api/agents.py latticeai/api/realtime.py latticeai/api/marketplace.py latticeai/services/app_context.py latticeai/services/model_runtime.py latticeai/services/model_catalog.py latticeai/services/model_recommendation.py latticeai/services/tool_dispatch.py latticeai/services/upload_service.py latticeai/core/tool_registry.py latticeai/core/enterprise.py latticeai/core/enterprise_admin.py latticeai/core/agent_prompts.py latticeai/core/workspace_os.py latticeai/core/plugins.py latticeai/core/marketplace.py latticeai/core/workflow_engine.py latticeai/core/multi_agent.py latticeai/core/realtime.py knowledge_graph.py knowledge_graph_api.py local_knowledge_api.py llm_router.py p_reinforce.py telegram_bot.py tools.py codex_telegram_bot.py",
-    "lint": "node --check static/scripts/account.js && node --check static/scripts/admin.js && node --check static/scripts/chat.js && node --check static/scripts/graph.js && node --check static/scripts/platform.js && node --check static/scripts/ux.js && node --check static/scripts/workspace.js && node --check tests/visual/mock_server.cjs",
+    "check:python": "python3 -m py_compile ltcai_cli.py server.py latticeai/server_app.py latticeai/api/auth.py latticeai/api/chat.py latticeai/api/computer_use.py latticeai/api/deps.py latticeai/api/garden.py latticeai/api/local_files.py latticeai/api/permissions.py latticeai/api/setup.py latticeai/api/static_routes.py latticeai/api/tools.py latticeai/api/plugins.py latticeai/api/workflow_designer.py latticeai/api/agents.py latticeai/api/realtime.py latticeai/api/marketplace.py latticeai/api/search.py latticeai/services/search_service.py latticeai/core/local_embeddings.py latticeai/core/embedding_providers.py latticeai/services/agent_runtime.py latticeai/core/config.py latticeai/api/admin.py latticeai/services/app_context.py latticeai/services/model_runtime.py latticeai/services/model_catalog.py latticeai/services/model_recommendation.py latticeai/services/tool_dispatch.py latticeai/services/upload_service.py latticeai/core/tool_registry.py latticeai/core/enterprise.py latticeai/core/enterprise_admin.py latticeai/core/agent_prompts.py latticeai/core/workspace_os.py latticeai/core/plugins.py latticeai/core/marketplace.py latticeai/core/workflow_engine.py latticeai/core/multi_agent.py latticeai/core/realtime.py knowledge_graph.py knowledge_graph_api.py local_knowledge_api.py llm_router.py p_reinforce.py telegram_bot.py tools.py codex_telegram_bot.py",
+    "lint": "node --check static/scripts/account.js && node --check static/scripts/admin.js && node --check static/scripts/chat.js && node --check static/scripts/graph.js && node --check static/scripts/platform.js && node --check static/scripts/ux.js && node --check static/scripts/workspace.js && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:v3",
+    "lint:v3": "node scripts/lint_v3.mjs",
     "typecheck": "cd vscode-extension && npm run build",
     "test": "python3 -m pytest tests/ -v",
     "test:unit": "python3 -m pytest tests/unit/ -v",
@@ -31,7 +33,7 @@
     "capture:skills": "node scripts/capture/capture_skills.js",
     "capture:enterprise": "node scripts/capture/capture_enterprise.js",
     "capture:onboarding": "node scripts/capture/capture_onboarding.js",
-    "release:artifacts": "npm run build:python && npm pack && cd vscode-extension && npm run package:vsix",
+    "release:artifacts": "npm run build:assets && npm run build:python && npm pack && cd vscode-extension && npm run package:vsix",
     "release:validate": "python3 scripts/validate_release_artifacts.py $npm_package_version --require-vsix --require-tgz",
     "publish:npm": "npm pack && npm publish ltcai-$npm_package_version.tgz --access public",
     "publish:pypi": "npm run build:python && python3 -m twine upload --skip-existing dist/ltcai-$npm_package_version.tar.gz dist/ltcai-$npm_package_version-py3-none-any.whl",
@@ -89,9 +91,14 @@
     "static/platform.css",
     "static/scripts/",
     "static/css/",
+    "static/v3/",
     "static/icons/",
     "plugins/",
+    "scripts/",
     "docs/",
+    "!docs/images/tmp_frames/",
+    "!**/__pycache__/",
+    "!**/*.pyc",
     "requirements.txt",
     "README.md"
   ],

package/scripts/build_v3_assets.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/*
+ * Build the v3 browser asset manifest.
+ *
+ * The source files stay importable in development. This script writes hashed
+ * siblings next to each runtime asset, rewrites ES-module imports to those
+ * hashed siblings, and emits static/v3/asset-manifest.json for /app.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, extname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const staticRoot = join(repoRoot, "static");
+const manifestPath = join(staticRoot, "v3", "asset-manifest.json");
+
+const cssSources = [
+  "static/css/tokens.css",
+  "static/v3/css/lattice.tokens.css",
+  "static/v3/css/lattice.base.css",
+  "static/v3/css/lattice.components.css",
+  "static/v3/css/lattice.shell.css",
+  "static/v3/css/lattice.views.css",
+];
+
+const moduleRoot = join(staticRoot, "v3", "js");
+const entry = "static/v3/js/app.js";
+
+function posix(p) {
+  return p.replaceAll("\\", "/");
+}
+
+function sha(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 8);
+}
+
+function repoPath(abs) {
+  return posix(relative(repoRoot, abs));
+}
+
+function publicUrl(repoRel) {
+  return "/" + posix(repoRel);
+}
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p));
+    else if (name.endsWith(".js")) out.push(p);
+  }
+  return out;
+}
+
+function removeGenerated(dir, ext) {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) removeGenerated(p, ext);
+    else if (new RegExp(`\\.[0-9a-f]{8}\\${ext}$`).test(name)) rmSync(p);
+  }
+}
+
+removeGenerated(join(staticRoot, "css"), ".css");
+removeGenerated(join(staticRoot, "v3", "css"), ".css");
+removeGenerated(moduleRoot, ".js");
+
+const modules = new Map();
+for (const abs of walk(moduleRoot)) {
+  modules.set(repoPath(abs), {
+    abs,
+    rel: repoPath(abs),
+    source: readFileSync(abs, "utf8"),
+    deps: [],
+  });
+}
+
+const importFromRe = /\b(?:import|export)\s+(?:[^"'()]*?\s+from\s*)?["']([^"']+\.js)["']/g;
+for (const mod of modules.values()) {
+  const deps = [];
+  let match;
+  while ((match = importFromRe.exec(mod.source))) {
+    const spec = match[1];
+    if (!spec.startsWith(".")) continue;
+    const depRel = repoPath(join(dirname(mod.abs), spec));
+    if (modules.has(depRel)) deps.push(depRel);
+  }
+  mod.deps = deps;
+}
+
+const hashMemo = new Map();
+function moduleHash(rel, stack = []) {
+  if (hashMemo.has(rel)) return hashMemo.get(rel);
+  if (stack.includes(rel)) return sha(modules.get(rel).source);
+  const mod = modules.get(rel);
+  const depHashes = mod.deps
+    .sort()
+    .map((dep) => `${dep}:${moduleHash(dep, [...stack, rel])}`)
+    .join("\n");
+  const h = sha(`${mod.source}\n/* dependency-hashes */\n${depHashes}`);
+  hashMemo.set(rel, h);
+  return h;
+}
+
+for (const rel of modules.keys()) moduleHash(rel);
+
+function hashedRel(rel, hash) {
+  const ext = extname(rel);
+  return posix(join(dirname(rel), `${basename(rel, ext)}.${hash}${ext}`));
+}
+
+const assets = {};
+
+for (const sourceRel of cssSources) {
+  const abs = join(repoRoot, sourceRel);
+  const source = readFileSync(abs, "utf8");
+  const outRel = hashedRel(sourceRel, sha(source));
+  writeFileSync(join(repoRoot, outRel), source, "utf8");
+  assets[sourceRel] = publicUrl(outRel);
+}
+
+function rewriteModule(mod) {
+  return mod.source.replace(importFromRe, (full, spec) => {
+    if (!spec.startsWith(".")) return full;
+    const depRel = repoPath(join(dirname(mod.abs), spec));
+    const depHash = hashMemo.get(depRel);
+    if (!depHash) return full;
+    const depOutAbs = join(repoRoot, hashedRel(depRel, depHash));
+    const nextSpec = posix(relative(dirname(join(repoRoot, hashedRel(mod.rel, hashMemo.get(mod.rel)))), depOutAbs));
+    const normalized = nextSpec.startsWith(".") ? nextSpec : `./${nextSpec}`;
+    return full.replace(spec, normalized);
+  });
+}
+
+for (const mod of modules.values()) {
+  const outRel = hashedRel(mod.rel, hashMemo.get(mod.rel));
+  mkdirSync(dirname(join(repoRoot, outRel)), { recursive: true });
+  writeFileSync(join(repoRoot, outRel), rewriteModule(mod), "utf8");
+  assets[mod.rel] = publicUrl(outRel);
+}
+
+const manifest = {
+  version: "3.1.0",
+  generated_at: "deterministic",
+  entrypoints: {
+    app: assets[entry],
+    styles: cssSources.map((rel) => assets[rel]),
+  },
+  assets,
+};
+
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+console.log(`wrote ${repoPath(manifestPath)} with ${Object.keys(assets).length} assets`);

package/scripts/capture/README.md

@@ -0,0 +1,28 @@
+# Screenshot Capture
+
+Reproducible Playwright capture scripts for release screenshots.
+
+Prerequisites:
+
+```bash
+npm ci
+npx playwright install chromium
+LTCAI
+```
+
+Optional environment:
+
+- `LTCAI_CAPTURE_BASE_URL` defaults to `http://localhost:4825`
+- `SESSION_TOKEN` or `LTCAI_SESSION_TOKEN` injects an authenticated session cookie
+- `LTCAI_CAPTURE_OUT` defaults to `docs/images`
+- `LTCAI_CAPTURE_HEADED=1` runs with a visible browser
+
+Commands:
+
+```bash
+npm run capture:workspace
+npm run capture:graph
+npm run capture:skills
+npm run capture:enterprise
+npm run capture:onboarding
+```

package/scripts/capture/capture_enterprise.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/admin#enterprise", waitFor: "#enterprise-capability-status", filename: "enterprise.png" })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_graph.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/graph", waitFor: "#graph", filename: "graph.png", settleMs: 1400 })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_onboarding.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { capturePage } = require("./capture_page");
+
+capturePage({ path: "/onboarding", waitFor: "#onboarding-steps", filename: "onboarding.png" })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/scripts/capture/capture_page.js

@@ -0,0 +1,43 @@
+const fs = require("fs");
+const path = require("path");
+
+async function loadPlaywright() {
+  try {
+    return require("@playwright/test");
+  } catch (_) {
+    return require("playwright");
+  }
+}
+
+async function capturePage(options) {
+  const { chromium } = await loadPlaywright();
+  const baseURL = process.env.LTCAI_CAPTURE_BASE_URL || "http://localhost:4825";
+  const outDir = path.resolve(process.env.LTCAI_CAPTURE_OUT || path.join(__dirname, "..", "..", "docs", "images"));
+  const sessionToken = process.env.SESSION_TOKEN || process.env.LTCAI_SESSION_TOKEN || "";
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: process.env.LTCAI_CAPTURE_HEADED !== "1" });
+  const context = await browser.newContext({
+    viewport: { width: Number(process.env.LTCAI_CAPTURE_WIDTH || 1440), height: Number(process.env.LTCAI_CAPTURE_HEIGHT || 920) },
+    deviceScaleFactor: Number(process.env.LTCAI_CAPTURE_SCALE || 2),
+  });
+  if (sessionToken) {
+    const host = new URL(baseURL).hostname;
+    await context.addCookies([{ name: "session_token", value: sessionToken, domain: host, path: "/", httpOnly: true, secure: false }]);
+  }
+
+  const page = await context.newPage();
+  const target = new URL(options.path, baseURL).toString();
+  await page.goto(target, { waitUntil: "networkidle", timeout: Number(process.env.LTCAI_CAPTURE_TIMEOUT || 30_000) });
+  if (options.hash) await page.evaluate((hash) => { location.hash = hash; }, options.hash);
+  if (options.waitFor) await page.waitForSelector(options.waitFor, { timeout: 15_000 });
+  await page.waitForTimeout(Number(process.env.LTCAI_CAPTURE_SETTLE_MS || options.settleMs || 900));
+
+  const outPath = path.join(outDir, options.filename);
+  await page.screenshot({ path: outPath, fullPage: Boolean(options.fullPage) });
+  await browser.close();
+  console.log(outPath);
+  return outPath;
+}
+
+module.exports = { capturePage };