code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/locales/en/.agents/skills/n8n-pinecone-qdrant-supabase/agents/kimi.yaml

@@ -1,16 +1,16 @@
-name: "n8n-pinecone-qdrant-supabase"
-display_name: "n8n + Pinecone + Qdrant + Supabase"
-description: "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime). Use this skill when building AI pipelines, RAG systems, data automation, working with embeddings, semantic search, or any orchestration between these tools. Activate for questions about n8n workflows, vector search, embedding upsert, Supabase RLS, or building RAG on top of this stack."
-default_prompt: "Use $n8n-pinecone-qdrant-supabase when the task matches the \"n8n + Pinecone + Qdrant + Supabase\" skill."
-triggers:
-  - "n8n-pinecone-qdrant-supabase"
-  - "n8n pinecone qdrant supabase"
-  - "n8n + Pinecone + Qdrant + Supabase"
-  - "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime)"
-capabilities:
-  - "n8n"
-  - "pinecone"
-  - "qdrant"
-  - "supabase"
-tools: []
-implicit_invocation: true
+name: "n8n-pinecone-qdrant-supabase"
+display_name: "n8n + Pinecone + Qdrant + Supabase"
+description: "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime). Use this skill when building AI pipelines, RAG systems, data automation, working with embeddings, semantic search, or any orchestration between these tools. Activate for questions about n8n workflows, vector search, embedding upsert, Supabase RLS, or building RAG on top of this stack."
+default_prompt: "Use $n8n-pinecone-qdrant-supabase when the task matches the \"n8n + Pinecone + Qdrant + Supabase\" skill."
+triggers:
+  - "n8n-pinecone-qdrant-supabase"
+  - "n8n pinecone qdrant supabase"
+  - "n8n + Pinecone + Qdrant + Supabase"
+  - "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime)"
+capabilities:
+  - "n8n"
+  - "pinecone"
+  - "qdrant"
+  - "supabase"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/n8n-pinecone-qdrant-supabase-reference/SKILL.md

@@ -0,0 +1,594 @@
+---
+name: n8n-pinecone-qdrant-supabase-reference
+description: Canonical reference of templates for the n8n + Pinecone + Qdrant + Supabase + RAG stack — n8n Code-node templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Growing library of reference templates for ARCH+DEV gates.
+type: reference
+domain: development
+owners:
+  - architect
+  - senior_full_stack
+gates:
+  - ARCH
+  - DEV
+tech:
+  - n8n
+topic:
+  - architecture
+  - general
+triggers:
+  - n8n Code transform example
+  - Pinecone upsert batch
+  - Qdrant collection setup
+  - Supabase pgvector match_documents
+  - RAG prompt builder
+  - hybrid_search RRF
+related:
+  - n8n-pinecone-qdrant-supabase
+  - architecture-doc-reference
+  - api-contracts-reference
+  - security-baseline-dev
+  - observability-plan
+  - data-model
+budget_lines: 650
+schema_version: 1
+---
+
+
+# Skill: n8n + Pinecone + Qdrant + Supabase — Reference
+
+Canonical templates for the stack. Workflow rules + DO/DON'T + Output Template → `$n8n-pinecone-qdrant-supabase`.
+
+**Sections:**
+1. [n8n Code templates](#1-n8n-code-templates)
+2. [Pinecone JSON](#2-pinecone-json)
+3. [Qdrant JSON](#3-qdrant-json)
+4. [Supabase SQL+REST](#4-supabase-sqlrest)
+5. [RAG templates](#5-rag-templates)
+6. [n8n + Supabase JS](#6-n8n--supabase-js)
+7. [Growing library](#7-growing-library)
+
+---
+
+## 1. n8n Code templates
+
+### 1.1 Transform all items with early validation
+
+```js
+// n8n Code node — processes all items
+const results = [];
+
+for (const item of $input.all()) {
+  const { text, sourceId, metadata } = item.json;
+
+  // ✅ Early check — skip invalid items
+  if (!text || typeof text !== "string") {
+    continue; // or: throw new Error(`Item ${sourceId}: missing text`);
+  }
+
+  results.push({
+    json: {
+      id:       sourceId,
+      content:  text.trim().slice(0, 8000), // ✅ cut to embedding limit
+      metadata: {
+        ...metadata,
+        processedAt: new Date().toISOString(),
+      },
+    },
+  });
+}
+
+return results;
+```
+
+### 1.2 Chunking with overlap
+
+```js
+// Code node: chunking with overlap
+function chunkText(text, chunkSize = 1000, overlap = 200) {
+  const chunks = [];
+  let start = 0;
+
+  while (start < text.length) {
+    const end = Math.min(start + chunkSize, text.length);
+    chunks.push({
+      text:       text.slice(start, end),
+      chunkIndex: chunks.length,
+      startChar:  start,
+      endChar:    end,
+    });
+    start += chunkSize - overlap; // ✅ overlap preserves context at boundaries
+  }
+
+  return chunks;
+}
+
+const { content, docId, metadata } = $input.first().json;
+const chunks = chunkText(content);
+
+return chunks.map((chunk, i) => ({
+  json: {
+    id:      `${docId}_chunk_${i}`,
+    text:    chunk.text,
+    metadata: { ...metadata, docId, chunkIndex: i, totalChunks: chunks.length },
+  },
+}));
+```
+
+### 1.3 Error-workflow setup
+
+```
+1. Settings → Error Workflow → specify a dedicated error-workflow
+2. In error-workflow: get $execution.error → log to Supabase/Slack
+3. For HTTP Request nodes: enable "Continue on Fail" + check status in next node
+```
+
+### 1.4 HTTP response checker
+
+```js
+// Code node: check HTTP Request response
+const response = $input.first().json;
+
+if (response.error || response.statusCode >= 400) {
+  throw new Error(`API error: ${response.statusCode} — ${JSON.stringify(response.error)}`);
+}
+
+return [{ json: response }];
+```
+
+---
+
+## 2. Pinecone JSON
+
+### 2.1 Upsert batch (Code prep + HTTP body)
+
+```js
+// Code node: prepare batch for Pinecone upsert
+const items = $input.all();
+
+const vectors = items.map(item => ({
+  id:       item.json.id,          // unique string ID
+  values:   item.json.embedding,   // float[] from embedding model
+  metadata: {
+    // ✅ Only primitives: string, number, boolean, string[]
+    text:       item.json.text.slice(0, 1000), // Pinecone metadata limit ~40KB
+    sourceUrl:  item.json.sourceUrl,
+    docId:      item.json.docId,
+    chunkIndex: item.json.chunkIndex,
+    updatedAt:  new Date().toISOString(),
+  },
+}));
+
+// Batch of 100 (Pinecone upsert limit)
+const batchSize = 100;
+const batches = [];
+for (let i = 0; i < vectors.length; i += batchSize) {
+  batches.push({ json: { vectors: vectors.slice(i, i + batchSize) } });
+}
+
+return batches;
+```
+
+```
+HTTP Request: POST https://YOUR_INDEX.svc.YOUR_ENV.pinecone.io/vectors/upsert
+Headers: Api-Key: {{ $vars.PINECONE_API_KEY }}, Content-Type: application/json
+Body: { "vectors": {{ $json.vectors }}, "namespace": "docs_product" }
+```
+
+### 2.2 Query with filters
+
+```json
+{
+  "vector":          "{{ $json.queryEmbedding }}",
+  "topK":            10,
+  "namespace":       "docs_product",
+  "includeMetadata": true,
+  "filter": {
+    "docId":     { "$eq": "manual_v2" },
+    "updatedAt": { "$gte": "2024-01-01" }
+  }
+}
+```
+
+```js
+// Code node: process search results
+const matches = $input.first().json.matches ?? [];
+
+// ✅ Filter by score — cut weak matches
+const relevant = matches
+  .filter(m => m.score >= 0.75)
+  .map(m => ({
+    text:      m.metadata.text,
+    score:     m.score,
+    sourceUrl: m.metadata.sourceUrl,
+    chunkIndex: m.metadata.chunkIndex,
+  }));
+
+return [{ json: { matches: relevant, count: relevant.length } }];
+```
+
+### 2.3 Delete by filter
+
+```json
+{
+  "filter":    { "docId": { "$eq": "manual_v1" } },
+  "namespace": "docs_product",
+  "deleteAll": false
+}
+```
+
+---
+
+## 3. Qdrant JSON
+
+### 3.1 Collection setup
+
+```json
+{
+  "vectors": {
+    "size":     1536,
+    "distance": "Cosine"
+  },
+  "optimizers_config": {
+    "default_segment_number": 2
+  },
+  "replication_factor": 1
+}
+```
+
+### 3.2 Upsert points
+
+```js
+// Code node: prepare for Qdrant upsert
+const points = $input.all().map(item => ({
+  id:      item.json.id,         // ✅ uint64 or UUID string
+  vector:  item.json.embedding,
+  payload: {
+    text:       item.json.text,
+    docId:      item.json.docId,
+    chunkIndex: item.json.chunkIndex,
+    sourceUrl:  item.json.sourceUrl,
+    language:   item.json.language ?? "ru",
+    createdAt:  Math.floor(Date.now() / 1000), // ✅ unix timestamp for range filters
+  },
+}));
+
+return [{ json: { points } }];
+```
+
+```
+PUT /collections/documents/points
+Body: { "points": {{ $json.points }} }
+```
+
+### 3.3 Search with payload filters
+
+```json
+{
+  "vector":       "{{ $json.queryEmbedding }}",
+  "limit":        10,
+  "with_payload": true,
+  "filter": {
+    "must": [
+      { "key": "language", "match": { "value": "ru" } },
+      { "key": "createdAt", "range": { "gte": 1704067200 } }
+    ],
+    "must_not": [
+      { "key": "docId", "match": { "value": "draft_123" } }
+    ]
+  },
+  "score_threshold": 0.70
+}
+```
+
+### 3.4 Scroll (export / batch update)
+
+```json
+{
+  "limit":        100,
+  "with_payload": true,
+  "with_vector":  false,
+  "filter": {
+    "must": [{ "key": "docId", "match": { "value": "manual_v1" } }]
+  },
+  "offset": null
+}
+```
+
+Next page: `"offset": last_result.next_page_offset`.
+
+### 3.5 Named vectors (multi-modal)
+
+```json
+{
+  "vectors": {
+    "text":  { "size": 1536, "distance": "Cosine" },
+    "image": { "size": 512,  "distance": "Cosine" }
+  }
+}
+```
+
+Search only by text vector:
+```json
+{ "vector": { "name": "text", "vector": [...] }, "limit": 5 }
+```
+
+---
+
+## 4. Supabase SQL+REST
+
+### 4.1 pgvector setup + HNSW index + match_documents
+
+```sql
+-- Enable extension (once)
+create extension if not exists vector;
+
+-- Embeddings table
+create table documents (
+  id          uuid primary key default gen_random_uuid(),
+  content     text        not null,
+  embedding   vector(1536),          -- size per model
+  metadata    jsonb        default '{}',
+  user_id     uuid         references auth.users(id),
+  created_at  timestamptz  default now()
+);
+
+-- ✅ HNSW index — faster than IVFFlat in most cases
+create index on documents
+  using hnsw (embedding vector_cosine_ops)
+  with (m = 16, ef_construction = 64);
+
+-- Semantic search function
+create or replace function match_documents(
+  query_embedding vector(1536),
+  match_threshold float  default 0.75,
+  match_count     int    default 10,
+  filter_user_id  uuid   default null
+)
+returns table (
+  id         uuid,
+  content    text,
+  metadata   jsonb,
+  similarity float
+)
+language sql stable
+as $$
+  select
+    id,
+    content,
+    metadata,
+    1 - (embedding <=> query_embedding) as similarity
+  from documents
+  where
+    (filter_user_id is null or user_id = filter_user_id)
+    and 1 - (embedding <=> query_embedding) > match_threshold
+  order by embedding <=> query_embedding
+  limit match_count;
+$$;
+```
+
+### 4.2 RLS policies
+
+```sql
+-- ✅ Enable RLS on the table
+alter table documents enable row level security;
+
+-- User sees only their own documents
+create policy "users_own_documents"
+  on documents for all
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+
+-- service_role bypasses RLS — use only on backend/n8n
+-- anon/authenticated respects RLS — use on client
+```
+
+### 4.3 REST: call match_documents from n8n
+
+```
+POST https://YOUR_PROJECT.supabase.co/rest/v1/rpc/match_documents
+Headers:
+  apikey: {{ $vars.SUPABASE_SERVICE_KEY }}
+  Authorization: Bearer {{ $vars.SUPABASE_SERVICE_KEY }}
+  Content-Type: application/json
+```
+
+```json
+{
+  "query_embedding":  "{{ $json.embedding }}",
+  "match_threshold":  0.75,
+  "match_count":      10,
+  "filter_user_id":   null
+}
+```
+
+### 4.4 Realtime webhook setup
+
+```
+Supabase → Database Webhooks → on INSERT/UPDATE in table → POST to n8n Webhook URL
+
+Setup in Supabase Dashboard:
+  Database → Webhooks → Create Webhook
+    Table:  documents
+    Events: INSERT
+    URL:    https://YOUR_N8N.com/webhook/process-document
+    HTTP Method: POST
+```
+
+### 4.5 Storage upload
+
+```
+POST https://YOUR_PROJECT.supabase.co/storage/v1/object/documents/{{ $json.fileName }}
+Headers: apikey, Authorization, Content-Type: application/octet-stream
+Body: binary file
+```
+
+After upload — save metadata:
+```json
+// POST /rest/v1/document_metadata
+{
+  "file_path":   "documents/{{ $json.fileName }}",
+  "bucket":      "documents",
+  "size_bytes":  "{{ $json.fileSize }}",
+  "mime_type":   "{{ $json.mimeType }}",
+  "uploaded_by": "{{ $json.userId }}"
+}
+```
+
+---
+
+## 5. RAG templates
+
+### 5.1 RAG prompt builder
+
+```js
+// Code node: build RAG prompt
+const question = $input.first().json.question;
+const chunks   = $input.first().json.matches; // from vector search
+
+const context = chunks
+  .map((c, i) => `[${i + 1}] ${c.text}`)
+  .join("\n\n");
+
+const messages = [
+  {
+    role: "system",
+    content: `You are an assistant. Answer ONLY based on the provided context.
+If the answer is not in the context, say "Information not found".
+Context:
+${context}`,
+  },
+  {
+    role: "user",
+    content: question,
+  },
+];
+
+return [{ json: { messages } }];
+```
+
+### 5.2 hybrid_search RRF (Supabase)
+
+```sql
+-- Supabase: vector + full-text Reciprocal Rank Fusion
+create or replace function hybrid_search(
+  query_text      text,
+  query_embedding vector(1536),
+  match_count     int default 10
+)
+returns table (id uuid, content text, score float)
+language sql stable as $$
+  with semantic as (
+    select id, content,
+           1 - (embedding <=> query_embedding) as score,
+           row_number() over (order by embedding <=> query_embedding) as rank
+    from documents
+    limit 50
+  ),
+  fulltext as (
+    select id, content,
+           ts_rank(to_tsvector('english', content), plainto_tsquery('english', query_text)) as score,
+           row_number() over (order by score desc) as rank
+    from documents
+    where to_tsvector('english', content) @@ plainto_tsquery('english', query_text)
+    limit 50
+  )
+  select
+    coalesce(s.id, f.id) as id,
+    coalesce(s.content, f.content) as content,
+    coalesce(1.0/(60 + s.rank), 0) + coalesce(1.0/(60 + f.rank), 0) as score
+  from semantic s
+  full outer join fulltext f on s.id = f.id
+  order by score desc
+  limit match_count;
+$$;
+```
+
+---
+
+## 6. n8n + Supabase JS
+
+### 6.1 PostgREST query builder
+
+```js
+// Code node: build query with filters
+const { userId, status, limit = 20, offset = 0 } = $input.first().json;
+
+// ✅ Supabase PostgREST filters
+const params = new URLSearchParams({
+  user_id: `eq.${userId}`,
+  ...(status && { status: `eq.${status}` }),
+  order:  "created_at.desc",
+  limit:  limit.toString(),
+  offset: offset.toString(),
+});
+
+return [{ json: { queryString: params.toString() } }];
+```
+
+```
+HTTP Request: GET /rest/v1/documents?{{ $json.queryString }}
+Headers: apikey, Authorization, Range: 0-19 (for pagination)
+✅ Prefer: count=exact — returns Content-Range header with total count
+```
+
+### 6.2 Upsert with conflict resolution
+
+```
+POST /rest/v1/documents
+Headers: Prefer: resolution=merge-duplicates
+```
+
+```json
+{
+  "id":         "{{ $json.docId }}",
+  "content":   "{{ $json.content }}",
+  "updated_at": "{{ $now }}"
+}
+```
+
+`merge-duplicates` updates existing or creates new. `ignore-duplicates` skips if already present.
+
+### 6.3 Error handler
+
+```js
+// Code node after HTTP Request to Supabase
+const { statusCode, body } = $input.first().json;
+
+if (statusCode === 409) {
+  // Conflict — record already exists, that's OK
+  return [{ json: { status: "already_exists", ...body } }];
+}
+
+if (statusCode >= 400) {
+  // ✅ Throw with details — goes to error workflow
+  throw new Error(`Supabase error ${statusCode}: ${JSON.stringify(body)}`);
+}
+
+return [{ json: { status: "ok", data: body } }];
+```
+
+---
+
+## 7. Growing library
+
+Canonical templates are added via `update_skill` MCP tool as needs emerge. Extension candidates:
+
+- **Cost tracking** — Supabase table `embedding_costs` + n8n Code node to tally tokens × price
+- **Embedding cache** — Redis/Supabase lookup before OpenAI call, hash(text) → embedding
+- **Dimension migration helpers** — re-embed + re-upsert workflow when changing model
+- **Weaviate templates** — schema, hybrid search, multi-tenancy
+- **Chroma templates** — collection, query, persistence
+- **Milvus templates** — collection, index types (IVF/HNSW), partition keys
+- **Retrieval re-ranking** — Cohere Rerank / cross-encoder integration
+- **n8n sub-workflow throttling** — recursive workflows with rate-limit
+- **Embedding model variants** — Cohere / Voyage / sentence-transformers
+- **Vector dimension reduction** — Matryoshka embeddings (OpenAI dimensions param)
+
+---
+
+## See also
+- `$n8n-pinecone-qdrant-supabase` — workflow rules + DO/DON'T + RAG ASCII + Output Template
+- `$architecture-doc-reference` — canonical architecture-doc sections
+- `$api-contracts-reference` — REST endpoint templates
+- `$security-baseline-dev` — secrets management
+- `$observability-plan` — logging, metrics
+- `$data-model` — vector dimensions, schema

package/domains/development/locales/en/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/claude.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+  "description": "Canonical reference of templates for the n8n + Pinecone + Qdrant + Supabase + RAG stack — n8n Code-node templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Growing library of reference templates for ARCH+DEV gates.",
+  "default_prompt": "Use $n8n-pinecone-qdrant-supabase-reference when the task matches the \"n8n + Pinecone + Qdrant + Supabase Reference (Templates)\" skill.",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+    "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/copilot.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+  "description": "Canonical reference of templates for the n8n + Pinecone + Qdrant + Supabase + RAG stack — n8n Code-node templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Growing library of reference templates for ARCH+DEV gates.",
+  "default_prompt": "Use $n8n-pinecone-qdrant-supabase-reference when the task matches the \"n8n + Pinecone + Qdrant + Supabase Reference (Templates)\" skill.",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+    "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/gemini.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+  "description": "Canonical reference of templates for the n8n + Pinecone + Qdrant + Supabase + RAG stack — n8n Code-node templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Growing library of reference templates for ARCH+DEV gates.",
+  "default_prompt": "Use $n8n-pinecone-qdrant-supabase-reference when the task matches the \"n8n + Pinecone + Qdrant + Supabase Reference (Templates)\" skill.",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "n8n + Pinecone + Qdrant + Supabase Reference (Templates)",
+    "Integration patterns for n8n (workflow automation) with Vector DBs Pinecone and Qdrant and with Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}