@100xprompt/chitta 0.1.0

package/src/embedded/transformers-embeddings.ts

@@ -0,0 +1,100 @@
+// Real semantic embeddings via transformers.js (ONNX, in-process). Optional +
+// lazy: the package is only imported on first use, so the project runs fine
+// without it (falls back to LocalHashEmbeddings). Install to enable:
+//   bun add @huggingface/transformers
+// Select at runtime: CONTEXT_EMBEDDINGS=transformers [CONTEXT_EMBED_MODEL=...].
+
+import type { EmbeddingProvider } from "../provider"
+
+// Asymmetric models need a TASK PREFIX that differs for queries vs documents.
+// EmbeddingGemma (the current best sub-500M model, +8 MTEB over bge-small) is the
+// headline case; symmetric models (bge/gte) get no prefix.
+function prefixesFor(model: string): { query: string; doc: string } | null {
+  const m = model.toLowerCase()
+  if (m.includes("embeddinggemma")) return { query: "task: search result | query: ", doc: "title: none | text: " }
+  if (m.includes("e5") || m.includes("multilingual-e5")) return { query: "query: ", doc: "passage: " }
+  return null
+}
+
+export class TransformersEmbeddings implements EmbeddingProvider {
+  private extractor: ((text: string, opts: unknown) => Promise<{ data: ArrayLike<number> }>) | null = null
+  private readonly prefix: { query: string; doc: string } | null
+  // Matryoshka: truncate to CONTEXT_EMBED_DIM then re-normalize - big storage/speed
+  // win at minimal quality loss. EmbeddingGemma (native 768) defaults to 256; 0 ⇒ full.
+  private readonly dim: number
+  constructor(private readonly model = "Xenova/bge-small-en-v1.5") {
+    this.prefix = prefixesFor(model)
+    const envDim = Number(process.env.CONTEXT_EMBED_DIM ?? 0) || 0
+    this.dim = envDim || (model.toLowerCase().includes("embeddinggemma") ? 256 : 0)
+  }
+
+  private async pipe() {
+    if (this.extractor) return this.extractor
+    // Specifier typed as `string` so tsc doesn't require the optional dep to resolve.
+    const spec = "@huggingface/transformers"
+    const mod: any = await import(spec as string).catch(() => import("@xenova/transformers" as string))
+    if (mod?.env) mod.env.allowLocalModels = false
+    this.extractor = await mod.pipeline("feature-extraction", this.model)
+    return this.extractor!
+  }
+
+  private async embed(text: string, kind: "query" | "doc"): Promise<number[]> {
+    const ex = await this.pipe()
+    const input = this.prefix ? this.prefix[kind] + text : text
+    const out = await ex(input, { pooling: "mean", normalize: true })
+    let v = Array.from(out.data as ArrayLike<number>)
+    if (this.dim && this.dim < v.length) {
+      v = v.slice(0, this.dim) // Matryoshka truncation
+      let n = 0
+      for (const x of v) n += x * x
+      n = Math.sqrt(n) || 1
+      v = v.map((x) => x / n) // re-normalize the truncated vector
+    }
+    return v
+  }
+
+  async embedDense(text: string): Promise<number[]> {
+    return this.embed(text, "doc")
+  }
+  async embedQuery(text: string): Promise<number[]> {
+    return this.embed(text, "query")
+  }
+
+  // No native sparse vector from this model - retrieval runs dense-only here.
+  async embedSparse(): Promise<{ indices: number[]; values: number[] }> {
+    return { indices: [], values: [] }
+  }
+}
+
+// Default embedder: real semantic (transformers) when it can load, else the
+// offline keyword-hash. The first call decides and sticks, so ingest + query in a
+// session always use the SAME embedder (consistent vector space).
+import { LocalHashEmbeddings } from "./local-embeddings"
+export class AutoEmbeddings implements EmbeddingProvider {
+  private chosen: EmbeddingProvider | null = null
+  private readonly real: TransformersEmbeddings
+  private readonly fallback = new LocalHashEmbeddings()
+  constructor(model?: string) {
+    this.real = new TransformersEmbeddings(model)
+  }
+  private async pick(): Promise<EmbeddingProvider> {
+    if (this.chosen) return this.chosen
+    try {
+      await this.real.embedDense("warmup")
+      this.chosen = this.real
+    } catch {
+      this.chosen = this.fallback // no package / offline → keyword hash
+    }
+    return this.chosen
+  }
+  async embedDense(q: string) {
+    return (await this.pick()).embedDense(q)
+  }
+  async embedQuery(q: string) {
+    const e = await this.pick()
+    return e.embedQuery ? e.embedQuery(q) : e.embedDense(q)
+  }
+  async embedSparse(q: string) {
+    return (await this.pick()).embedSparse(q)
+  }
+}

package/src/embeddings.ts

@@ -0,0 +1,51 @@
+// EmbeddingProvider adapter. Dense embeddings come from an OpenAI-compatible
+// endpoint (PipesHub's air-gapped embedding server exposes /v1/embeddings); sparse
+// (BM25) comes from a configurable sparse endpoint. Both over fetch - no SDK,
+// nothing leaves the boundary if the endpoints are local.
+
+import type { EmbeddingProvider } from "./provider"
+
+export interface EmbeddingConfig {
+  /** OpenAI-compatible base, e.g. http://localhost:8002 */
+  denseEndpoint: string
+  denseModel: string
+  denseApiKey?: string
+  /** Endpoint returning { indices, values } for a BM25/sparse vector. Optional;
+   *  if absent, embedSparse throws (callers may run dense-only). */
+  sparseEndpoint?: string
+  fetchImpl?: typeof fetch
+}
+
+export class HttpEmbeddingProvider implements EmbeddingProvider {
+  private readonly fetch: typeof fetch
+  constructor(private readonly cfg: EmbeddingConfig) {
+    this.fetch = cfg.fetchImpl ?? fetch
+  }
+
+  async embedDense(query: string): Promise<number[]> {
+    const res = await this.fetch(`${this.cfg.denseEndpoint.replace(/\/$/, "")}/v1/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(this.cfg.denseApiKey ? { authorization: `Bearer ${this.cfg.denseApiKey}` } : {}),
+      },
+      body: JSON.stringify({ input: query, model: this.cfg.denseModel }),
+    })
+    const body = (await res.json()) as { data?: Array<{ embedding: number[] }>; error?: unknown }
+    const embedding = body.data?.[0]?.embedding
+    if (!embedding) throw new Error(`dense embed failed: ${JSON.stringify(body.error ?? res.status)}`)
+    return embedding
+  }
+
+  async embedSparse(query: string): Promise<{ indices: number[]; values: number[] }> {
+    if (!this.cfg.sparseEndpoint) throw new Error("no sparse endpoint configured")
+    const res = await this.fetch(this.cfg.sparseEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ input: query }),
+    })
+    const body = (await res.json()) as { indices?: number[]; values?: number[] }
+    if (!body.indices || !body.values) throw new Error(`sparse embed failed: ${res.status}`)
+    return { indices: body.indices, values: body.values }
+  }
+}

package/src/eval/goldset.ts

@@ -0,0 +1,46 @@
+// Gold-set generation - build a Q→relevant-record eval set from your OWN stored data,
+// so retrieval quality can be measured without hand-labeling. Two paths:
+//   • generateGoldSet (here): DETERMINISTIC - for each record, form a query from its
+//     chunk's salient terms; the source record is the gold label. Zero LLM, great for
+//     regression detection (does a query built from a record's own content retrieve it?).
+//   • LLM path (the frontier model): generate natural / multi-hop questions whose source
+//     chunk(s) are the gold labels - richer, but needs the calling model. (Doc only.)
+
+import type { SqliteStore } from "../embedded/sqlite-store"
+import type { GoldItem } from "./harness"
+
+const STOP = new Set([
+  "the", "a", "an", "and", "or", "but", "for", "with", "from", "into", "of", "on", "in", "at", "to", "by", "as",
+  "is", "are", "was", "were", "be", "this", "that", "these", "those", "it", "its", "will", "has", "have", "had",
+  "more", "after", "over", "across", "than", "their", "they", "you", "your", "our", "we",
+])
+
+/** One query per record (default), built from the most salient terms of its first chunk. */
+export function generateGoldSet(store: SqliteStore, opts: { terms?: number; perRecord?: number } = {}): GoldItem[] {
+  const nTerms = opts.terms ?? 6
+  const rows = store.db
+    .query(
+      `SELECT c.virtual_record_id v, c.content content
+       FROM chunks c
+       GROUP BY c.virtual_record_id`,
+    )
+    .all() as Array<{ v: string; content: string }>
+  const gold: GoldItem[] = []
+  for (const r of rows) {
+    const terms = salientTerms(r.content, nTerms)
+    if (terms.length >= 2) gold.push({ query: terms.join(" "), gold: [r.v] })
+  }
+  return gold
+}
+
+/** Top-N distinct content words by length (rare/specific terms first), boilerplate-free. */
+function salientTerms(text: string, n: number): string[] {
+  const seen = new Set<string>()
+  const words: string[] = []
+  for (const w of (text.toLowerCase().match(/[a-z0-9][a-z0-9-]{2,}/g) ?? [])) {
+    if (STOP.has(w) || seen.has(w)) continue
+    seen.add(w)
+    words.push(w)
+  }
+  return words.sort((a, b) => b.length - a.length).slice(0, n)
+}

package/src/eval/harness.ts

@@ -0,0 +1,65 @@
+// Eval harness - runs a gold Q→relevant-id set through any retrieval function and
+// reports aggregate metrics, so every retrieval change is MEASURED, not eyeballed.
+// The gold set is meant to be auto-synthesized from your OWN corpus/graph (the
+// frontier model that calls the MCP generates questions whose source record id IS the
+// gold label; 2-hop graph walks give multi-hop gold pairs). Here we keep the harness
+// retrieval-agnostic - pass any `retrieve(query) → ranked ids`.
+
+import { recallAtK, precisionAtK, reciprocalRank, ndcgAtK } from "./metrics"
+
+export interface GoldItem {
+  query: string
+  /** Ids that SHOULD be retrieved (record ids by default). */
+  gold: string[]
+  /** Optional graded relevance per id (0..3) for nDCG. */
+  grades?: Record<string, number>
+}
+
+export interface EvalReport {
+  n: number
+  k: number
+  recall: number
+  ndcg: number
+  mrr: number
+  precision: number
+  perQuery: Array<{ query: string; recall: number; precision: number; ndcg: number; rr: number; missed: boolean }>
+}
+
+const mean = (xs: number[]) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0)
+
+/** Run the gold set through `retrieve` and aggregate recall@k / nDCG@k / MRR / P@k. */
+export async function evaluate(
+  gold: GoldItem[],
+  retrieve: (query: string) => Promise<string[]>,
+  k = 10,
+): Promise<EvalReport> {
+  const per: EvalReport["perQuery"] = []
+  for (const item of gold) {
+    // dedupe the ranked ids (a record can yield several chunks/passages) - record-level
+    // metrics care about each record's FIRST position, so dupes must not double-count.
+    const seen = new Set<string>()
+    const ranked = (await retrieve(item.query)).filter((id) => (seen.has(id) ? false : (seen.add(id), true)))
+    const goldSet = new Set(item.gold)
+    const grades = item.grades ? new Map(Object.entries(item.grades)) : undefined
+    const recall = recallAtK(ranked, goldSet, k)
+    const precision = precisionAtK(ranked, goldSet, k)
+    const ndcg = ndcgAtK(ranked, goldSet, k, grades)
+    const rr = reciprocalRank(ranked, goldSet)
+    per.push({ query: item.query, recall, precision, ndcg, rr, missed: recall === 0 })
+  }
+  return {
+    n: gold.length,
+    k,
+    recall: mean(per.map((p) => p.recall)),
+    ndcg: mean(per.map((p) => p.ndcg)),
+    mrr: mean(per.map((p) => p.rr)),
+    precision: mean(per.map((p) => p.precision)),
+    perQuery: per,
+  }
+}
+
+/** Pretty one-line summary for CLI/CI diffing against a baseline. */
+export function formatReport(r: EvalReport): string {
+  const missed = r.perQuery.filter((p) => p.missed).length
+  return `eval n=${r.n} k=${r.k} | recall@${r.k}=${r.recall.toFixed(3)} nDCG@${r.k}=${r.ndcg.toFixed(3)} MRR=${r.mrr.toFixed(3)} | misses=${missed}`
+}

package/src/eval/metrics.ts

@@ -0,0 +1,38 @@
+// Retrieval metrics - pure functions over a ranked list of ids + the gold-relevant
+// set. No LLM, deterministic, repeatable: this is what replaces "tuning by eyeballing".
+// Track recall@k (did the right item come back?) + nDCG@k (is it ranked well?) as the
+// two headline numbers, per the 2026 RAG-eval consensus.
+
+/** Fraction of gold items present in the top-k ranked list. */
+export function recallAtK(ranked: string[], gold: Set<string>, k: number): number {
+  if (gold.size === 0) return 1
+  const top = ranked.slice(0, k)
+  let hit = 0
+  for (const g of gold) if (top.includes(g)) hit++
+  return hit / gold.size
+}
+
+/** Fraction of the top-k that are gold-relevant. */
+export function precisionAtK(ranked: string[], gold: Set<string>, k: number): number {
+  const top = ranked.slice(0, k)
+  if (top.length === 0) return 0
+  return top.filter((id) => gold.has(id)).length / top.length
+}
+
+/** Mean reciprocal rank: 1 / (rank of first gold hit), else 0. */
+export function reciprocalRank(ranked: string[], gold: Set<string>): number {
+  for (let i = 0; i < ranked.length; i++) if (gold.has(ranked[i])) return 1 / (i + 1)
+  return 0
+}
+
+/** nDCG@k with optional graded relevance (default binary). Rank-aware. */
+export function ndcgAtK(ranked: string[], gold: Set<string>, k: number, grades?: Map<string, number>): number {
+  const rel = (id: string) => (grades ? grades.get(id) ?? 0 : gold.has(id) ? 1 : 0)
+  let dcg = 0
+  for (let i = 0; i < Math.min(k, ranked.length); i++) dcg += (2 ** rel(ranked[i]) - 1) / Math.log2(i + 2)
+  // ideal DCG: sort all known-relevant grades descending
+  const ideal = [...(grades ? grades.values() : [...gold].map(() => 1))].sort((a, b) => b - a).slice(0, k)
+  let idcg = 0
+  for (let i = 0; i < ideal.length; i++) idcg += (2 ** ideal[i] - 1) / Math.log2(i + 2)
+  return idcg === 0 ? 0 : dcg / idcg
+}

package/src/http/server.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+// HTTP API over the REAL embedded backend - the dashboard's live wire. The backend
+// uses bun:sqlite + in-process transformers/reranker, so it can't run inside the
+// Next.js (Node) dashboard; this small bun server exposes it over HTTP (CORS-open for
+// localhost) so the UI drives genuine retrieval: hybrid BM25+dense+graph → RRF →
+// reranker → passage, KGQA exact answers, Personalized PageRank, and the eval harness.
+// Identity comes from the same CONTEXT_USER_ID/ORG_ID env as the MCP (single-user by
+// default). Run: bun run src/http/server.ts  (port CONTEXT_HTTP_PORT, default 4318).
+
+import { personalContext } from "../embedded/personal"
+import { generateGoldSet } from "../eval/goldset"
+import { evaluate } from "../eval/harness"
+
+const ctx = personalContext()
+const U = ctx.userId
+const O = ctx.orgId
+const PORT = Number(process.env.CONTEXT_HTTP_PORT ?? 4318)
+
+const CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Headers": "*",
+  "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
+  "content-type": "application/json",
+}
+const json = (data: unknown, status = 200) => new Response(JSON.stringify(data), { status, headers: CORS })
+
+Bun.serve({
+  port: PORT,
+  idleTimeout: 60, // retrieval can download a model on first call
+  async fetch(req) {
+    if (req.method === "OPTIONS") return new Response(null, { headers: CORS })
+    const url = new URL(req.url)
+    const body: any = req.method === "POST" ? await req.json().catch(() => ({})) : {}
+    try {
+      switch (url.pathname) {
+        case "/api/health":
+          return json({ ok: true, user: U, org: O })
+
+        // hybrid retrieval (BM25 + dense + graph → RRF → reranker → passage) + TRACE
+        case "/api/search": {
+          const { response, trace } = await ctx.searchTraced(String(body.query ?? ""), U, O)
+          return json({
+            query: body.query,
+            results: response.searchResults.map((r) => ({
+              content: r.content,
+              recordName: r.metadata.recordName ?? "untitled",
+              recordId: r.metadata.recordId,
+              score: r.score,
+              citationType: r.citationType,
+            })),
+            trace, // how the query flowed through the pipeline
+          })
+        }
+
+        // KGQA exact answer from the typed graph (null ⇒ fell back to ranked)
+        case "/api/ask":
+          return json({ answer: await ctx.ask(String(body.query ?? ""), U, O) })
+
+        // Personalized PageRank multi-hop walk
+        case "/api/walk": {
+          const seeds = Array.isArray(body.seeds)
+            ? body.seeds
+            : String(body.seed ?? "").split(/\s*,\s*/).filter(Boolean)
+          return json({ ranked: await ctx.graphQuery.walk(seeds, U, O, { limit: 25 }) })
+        }
+        case "/api/neighbors":
+          return json({ result: await ctx.graphQuery.neighbors(String(body.entity ?? ""), U, O) })
+        case "/api/path":
+          return json({ result: await ctx.graphQuery.pathBetween(String(body.a ?? ""), String(body.b ?? ""), U, O) })
+        case "/api/communities":
+          return json({ communities: await ctx.graphQuery.communities(U, O) })
+
+        // measure retrieval quality on a gold set auto-built from the user's own data
+        case "/api/eval": {
+          const gold = generateGoldSet(ctx.store, { terms: 6 })
+          const report = await evaluate(
+            gold,
+            async (q) => (await ctx.searchWithGraph(q, U, O)).searchResults.map((r) => r.metadata.recordId as string),
+            10,
+          )
+          return json({ report })
+        }
+
+        default:
+          return json({ error: "not found", paths: ["/api/health", "/api/search", "/api/ask", "/api/walk", "/api/neighbors", "/api/path", "/api/communities", "/api/eval"] }, 404)
+      }
+    } catch (e) {
+      return json({ error: String(e) }, 500)
+    }
+  },
+})
+
+console.error(`[context-http] backend API ready on http://localhost:${PORT} (user=${U}, org=${O})`)

package/src/index.ts

@@ -0,0 +1,44 @@
+// Context layer - the permission-aware retrieval moat, ported natively to TS.
+// See ./README.md for the port provenance and what still plugs in behind the seams.
+
+export * from "./permission"
+export * from "./types"
+export * from "./provider"
+export { ArangoGraphProvider } from "./arango-graph-provider"
+export { RetrievalService, type RetrievalDeps } from "./retrieval"
+export { ArangoHttpClient, type ArangoConfig } from "./arango-client"
+export { QdrantVectorService, type QdrantConfig } from "./qdrant-vector"
+export { HttpEmbeddingProvider, type EmbeddingConfig } from "./embeddings"
+export { buildContextService, type ContextConfig, type ContextService, type ContextLog } from "./service"
+
+import { ArangoGraphProvider } from "./arango-graph-provider"
+import { RetrievalService } from "./retrieval"
+import type { ArangoClient, EmbeddingProvider, VectorDBService } from "./provider"
+
+/** Build a ready retrieval service from the three backend seams. */
+export function createContext(opts: {
+  arango: ArangoClient
+  vector: VectorDBService
+  embeddings: EmbeddingProvider
+  collectionName: string
+  log?: RetrievalServiceLog
+}) {
+  const graph = new ArangoGraphProvider(opts.arango, opts.log)
+  const retrieval = new RetrievalService({
+    graph,
+    vector: opts.vector,
+    embeddings: opts.embeddings,
+    collectionName: opts.collectionName,
+    log: opts.log,
+  })
+  return { graph, retrieval }
+}
+
+type RetrievalServiceLog = {
+  info: (m: string) => void
+  debug: (m: string) => void
+  error: (m: string, ...a: unknown[]) => void
+}
+
+// Re-export the backend seam types for callers wiring adapters.
+export type { ArangoClient, EmbeddingProvider, VectorDBService } from "./provider"

package/src/install/index.ts

@@ -0,0 +1,139 @@
+// `chitta install` — wire Chitta into AI tools as an MCP server (everywhere) and a Skill
+// (where supported). One command; merges into existing config; idempotent.
+//
+//   chitta install                         # auto-detect installed tools (global), install to each
+//   chitta install --platform cursor,zed   # specific tools
+//   chitta install --all                    # every supported tool
+//   chitta install --platform claude-code --project [--project-dir .]   # project-scoped
+//   chitta install --print                  # print the generic MCP snippet, write nothing
+//   chitta install --list                   # list supported tools
+//   chitta install --user-id alice --org-id acme   # bake identity into the config env
+//   chitta uninstall [--platform ...] [--project]   # remove the chitta entry/skill
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { PLATFORMS, byId, type Platform } from "./platforms"
+import { serverEntry, writeJsonConfig, writeCodexToml, printSnippet } from "./writers"
+import { installSkill } from "./skill"
+
+const argv = process.argv.slice(2)
+const action = argv[0] // "install" | "uninstall"
+const flag = (name: string): string | undefined => {
+  const i = argv.indexOf(`--${name}`)
+  return i >= 0 && i + 1 < argv.length && !argv[i + 1].startsWith("--") ? argv[i + 1] : undefined
+}
+const has = (name: string) => argv.includes(`--${name}`)
+
+const env: Record<string, string> = {}
+if (flag("user-id")) env.CONTEXT_USER_ID = flag("user-id")!
+if (flag("org-id")) env.CONTEXT_ORG_ID = flag("org-id")!
+
+const project = has("project")
+const projectDir = resolve(flag("project-dir") ?? ".")
+const withSkill = !has("no-skill")
+
+function targetConfigPath(p: Platform): string | null {
+  if (project) return p.project ? join(projectDir, p.project) : null
+  return p.global
+}
+function targetSkillDir(p: Platform): string | null {
+  if (!withSkill) return null
+  if (project) return p.skillProject ? join(projectDir, p.skillProject) : null
+  return p.skillGlobal ?? null
+}
+
+/** A tool counts as "present" if its config dir/file already exists on this machine. */
+function detected(p: Platform): boolean {
+  if (!p.global) return false
+  return existsSync(p.global) || existsSync(dirname(p.global))
+}
+
+function resolvePlatforms(): Platform[] {
+  if (has("all")) return PLATFORMS
+  const csv = flag("platform")
+  if (csv) {
+    const ids = csv.split(",").map((s) => s.trim()).filter(Boolean)
+    const out: Platform[] = []
+    for (const id of ids) {
+      const p = byId(id)
+      if (!p) { console.error(`unknown platform "${id}" — run \`chitta install --list\``); process.exit(1) }
+      out.push(p)
+    }
+    return out
+  }
+  // no --platform: project mode defaults to Claude Code; global mode auto-detects.
+  if (project) return [byId("claude-code")!]
+  const found = PLATFORMS.filter(detected)
+  if (found.length === 0) {
+    console.error("No supported AI tools detected. Use --platform <id> or --all, or --list.")
+    process.exit(1)
+  }
+  return found
+}
+
+function doInstall(p: Platform): string {
+  const skillDir = targetSkillDir(p)
+  const skillNote = skillDir ? `  + skill → ${installSkill(skillDir)}` : ""
+  if (p.format === "manual" || (!project && p.global === null)) {
+    return `~ ${p.label}: no stable config path — add manually (see --print).${skillNote}`
+  }
+  const path = targetConfigPath(p)
+  if (!path) return `~ ${p.label}: no ${project ? "project" : "global"} config path.${skillNote}`
+  if (p.format === "toml") {
+    writeCodexToml(path, env)
+  } else {
+    writeJsonConfig(path, p.key!, serverEntry(p.entry!, env), p.format === "json-array")
+  }
+  return `✓ ${p.label} → ${path}${p.note ? `\n    (${p.note})` : ""}${skillNote}`
+}
+
+function doUninstall(p: Platform): string {
+  const path = targetConfigPath(p)
+  const lines: string[] = []
+  if (path && existsSync(path)) {
+    if (p.format === "toml") {
+      const t = readFileSync(path, "utf8").replace(/\n*\[mcp_servers\.chitta\][\s\S]*?(?=\n\[[^.\]]|\s*$)/g, "\n")
+      writeFileSync(path, t.replace(/\n{3,}/g, "\n\n").trimStart())
+    } else {
+      try {
+        const cfg = JSON.parse(readFileSync(path, "utf8"))
+        const c = cfg[p.key!]
+        if (Array.isArray(c)) cfg[p.key!] = c.filter((e: any) => e?.name !== "chitta")
+        else if (c && typeof c === "object") delete c["chitta"]
+        writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n")
+      } catch { /* ignore malformed */ }
+    }
+    lines.push(`✓ removed from ${path}`)
+  }
+  const skillDir = targetSkillDir(p)
+  if (skillDir && existsSync(join(skillDir, "chitta"))) {
+    rmSync(join(skillDir, "chitta"), { recursive: true, force: true })
+    lines.push(`✓ removed skill ${join(skillDir, "chitta")}`)
+  }
+  return `${p.label}:\n  ${lines.length ? lines.join("\n  ") : "(nothing to remove)"}`
+}
+
+// ── main ───────────────────────────────────────────────────────────────────────
+if (has("list")) {
+  console.log("Supported platforms:\n")
+  for (const p of PLATFORMS) {
+    const tags = [p.skillGlobal || p.skillProject ? "skill" : "", p.format].filter(Boolean).join(", ")
+    console.log(`  ${p.id.padEnd(15)} ${p.label.padEnd(22)} (${tags})`)
+  }
+  console.log(`\nUsage: chitta install --platform <id>[,<id>...] | --all   [--project] [--user-id X --org-id Y]`)
+  process.exit(0)
+}
+
+if (has("print")) {
+  console.log("Add this to your MCP client's config (key is usually `mcpServers`):\n")
+  console.log(printSnippet(env))
+  process.exit(0)
+}
+
+const platforms = resolvePlatforms()
+const run = action === "uninstall" ? doUninstall : doInstall
+console.log(`Chitta ${action} — ${project ? "project" : "global"} scope${project ? ` (${projectDir})` : ""}\n`)
+for (const p of platforms) console.log(run(p) + "\n")
+if (action === "install") {
+  console.log("Done. Restart the tool (or reload its MCP config) to pick up Chitta's tools:")
+  console.log("  context_ingest · get_context · context_graph")
+}