release: merge develop into main for v0.26.0

Author: DavidsonGomes

.claude/agents/clawdia-assistant.md

@@ -285,6 +285,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base routing
+
+When you detect a question that belongs to a specific domain (academy, support, sales-playbook, brand-voice, finance-policies), route it to the right space via `knowledge-query space=<domain>`. If unsure which space applies, call `knowledge-admin action=health` to list available spaces, then pick the best match or query without a space filter.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/flux-finance.md

@@ -248,6 +248,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base integration
+
+When handling reimbursements, compliance questions, or expense policy issues, call `knowledge-query space=finance-policies` to find the authoritative rule. Always cite policy section in your response.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/lumen-learning.md

@@ -190,6 +190,10 @@ type: {{user, feedback, project, reference}}
 
 **Step 2** — add a pointer to that file in `MEMORY.md`. Each entry: `- [Title](file.md) — one-line hook`.
 
+## Knowledge base integration
+
+Extract SM-2 facts directly from indexed documents by calling `knowledge-summarize document_id=<id>` first, then split the summary into atomic facts via `learn-capture`. Good source pattern: one summary → 3-5 atomic facts.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/mako-marketing.md

@@ -290,6 +290,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base integration
+
+Before producing copy, call `knowledge-query space=brand-voice` to stay consistent with tone, vocabulary, and approved messaging pillars. Flag content that deviates from the brand guide.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/mentor-courses.md

@@ -256,6 +256,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base integration
+
+When a student asks a course-related question, call `knowledge-query space=academy answer=true` before formulating your reply. Cite sources in your response. Use `knowledge-summarize unit_id=<id>` to produce module/lesson TL;DRs when students ask for overviews.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/nex-sales.md

@@ -292,6 +292,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base integration
+
+Ground proposals and objection handling by calling `knowledge-query space=sales-playbook` for approved messaging, competitive positioning, and pricing precedent. Cite playbook sections in proposal drafts.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/zara-cs.md

@@ -316,6 +316,10 @@ Memory is one of several persistence mechanisms available to you as you assist t
 
 - Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
 
+## Knowledge base integration
+
+Before drafting any customer reply, call `knowledge-query space=support` to check if a KB/FAQ entry already answers the question. Cite article titles when relevant. For new recurring issues, propose a `knowledge-ingest` of the resolution into the `support` space.
+
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/skills/fin-daily-pulse/SKILL.md

@@ -87,7 +87,7 @@ Captura: `revenue.total`, `orders.completed`, `orders.pending`, `orders.failed`,
 ```
 GET /api/v1/analytics/orders?status=completed&created_after=YYYY-MM-DD&per_page=100
 ```
-(hoje em BRT; converter para UTC: `created_after = date.today().isoformat()`)
+(today in BRT; convert to UTC: `created_after = date.today().isoformat()`)
 - Paginate until `meta.has_more = false`
 - Sum `amount` of all orders — Evo Academy daily revenue
 - Split by type: renewals (`is_renewal=true`) vs new (`is_renewal=false`)

.claude/skills/knowledge-admin/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: knowledge-admin
+description: "Administrative operations on the Knowledge base: connect new pgvector servers, check health, view stats, export data, install parser models. Use when the user wants to configure/monitor the system ('connect a new pgvector', 'status of connections', 'how many docs do we have', 'export backup of space X', 'install Marker models')."
+---
+
+# knowledge-admin
+
+Group: **Administration**. Consolidates connect/health/stats/export/install-parser via subcommand.
+
+## When to trigger
+
+- "Connect a new pgvector"
+- "Status of connections"
+- "How many docs are in Academy?"
+- "Export space X as backup"
+- "Install Marker models"
+
+## Arguments
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `action` | str | yes | `connect` \| `health` \| `stats` \| `export` \| `install-parser` |
+| (action-specific args) | | | see below |
+
+## Actions
+
+### `connect` — New connection wizard
+
+Optional args: `slug`, `name`, `host`, `port`, `database`, `username`, `password`, `ssl_mode`, `connection_string`.
+
+Flow:
+
+1. If args missing, ask interactively (chat):
+   - Name ("What do you want to call this connection?")
+   - Host, port (default 5432), user, password, database, SSL mode
+   - OR paste a full connection string
+2. `POST /api/knowledge/connections` — register (encryption via workspace key)
+3. `POST /api/knowledge/connections/:id/configure` — runs:
+   - `SELECT version()` (Postgres >= 14)
+   - Validate `pgvector` >= 0.5
+   - PgBouncer detect (port 6543, pooler, ?pgbouncer=true) → HTTP 422 with message
+   - Alembic upgrade head
+   - Seed `knowledge_config`
+4. Show phase-by-phase progress
+5. Output: final status + next steps ("create your first space via UI or `knowledge-organize action=create`")
+
+### `health`
+
+```python
+from dashboard.backend.sdk_client import evo
+
+conns = evo.get("/api/knowledge/connections")
+for c in conns:
+    health = evo.get(f"/api/knowledge/connections/{c['id']}/health")
+    # aggregate: status, schema_version, pgvector_version, chunks, spaces, last_error
+```
+
+Output:
+
+```
+| Connection | Status | Schema | pgvector | Spaces | Chunks | Last health |
+|---|---|---|---|---|---|---|
+| academy | ✅ ready | v3 | 0.5.1 | 5 | 12,400 | 2026-04-20 14:05 |
+| acme | ⚠️ needs_mig | v2 | 0.5.0 | 2 | 3,100 | 2026-04-20 14:05 |
+| staging | ❌ error | — | — | — | — | `connection refused` |
+```
+
+### `stats`
+
+Aggregates per-connection + global stats:
+
+```python
+stats = evo.get("/api/knowledge/stats")
+# { connections: [...], total_documents: N, total_chunks: M, by_content_type: {...}, growth_7d: X }
+```
+
+Output:
+
+```
+## Knowledge stats
+
+Total documents: {N}
+Total chunks: {M}
+Total spaces: {S}
+Growth (last 7d): +{X} docs, +{Y} chunks
+
+### By content_type
+- lesson: {N}
+- tutorial: {N}
+- faq: {N}
+...
+
+### Per connection
+| Connection | Docs | Chunks | Spaces |
+...
+```
+
+### `export`
+
+Args: `space_id` (yes), `format` (default "jsonl"), `connection`.
+
+```python
+docs = evo.get(
+    "/api/knowledge/v1/documents",
+    params={"space_id": space_id, "format": "jsonl", "include_chunks": True},
+    headers={"X-Knowledge-Connection": connection},
+)
+
+# Save to workspace/data/knowledge-exports/{connection}_{space_slug}_{timestamp}.jsonl
+from pathlib import Path
+import json
+from datetime import datetime
+
+out = Path("workspace/data/knowledge-exports") / \
+      f"{connection}_{space_id}_{datetime.now():%Y%m%d_%H%M%S}.jsonl"
+out.parent.mkdir(parents=True, exist_ok=True)
+with out.open("w") as f:
+    for doc in docs:
+        f.write(json.dumps(doc, ensure_ascii=False) + "\n")
+
+print(f"Exported {len(docs)} docs to {out}")
+```
+
+### `install-parser`
+
+Downloads Marker models (Surya OCR ~500MB). Idempotent — uses sentinel file.
+
+```python
+resp = evo.post("/api/knowledge/parsers/install", {})
+# poll /api/knowledge/parsers/status until installed=true
+```
+
+Show progress. If already installed, no-op.
+
+## Actionable failures
+
+- Invalid `action` → list actions
+- Invalid credentials on connect → "Check host/port/user"
+- PgBouncer detected → exact message from ADR-009
+- Export without write permission → "Create `workspace/data/knowledge-exports/` manually"
+- Install-parser without disk → "No space. Marker needs ~500MB."

.claude/skills/knowledge-browse/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: knowledge-browse
+description: "List and filter documents and units in the Knowledge base. Use when the user wants to see what is indexed ('what's in space X', 'list the last 10 indexed docs', 'which documents have error status', 'show Academy units')."
+---
+
+# knowledge-browse
+
+Group: **Curation**. List/filter documents + units.
+
+## When to trigger
+
+- "What's in space X"
+- "List the last 10 indexed docs"
+- "Which documents have error status"
+- "Show Academy units"
+
+## Arguments
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `scope` | str | "documents" | "documents" OR "units" |
+| `connection` | str | first ready | Target connection |
+| `space` | str | null | Filter by space slug |
+| `unit_id` | str | null | Filter by unit |
+| `content_type` | str | null | lesson/tutorial/faq/reference/... |
+| `difficulty` | str | null | beginner/intermediate/advanced |
+| `topics` | list[str] | null | Filter by tags |
+| `status` | str | null | pending/processing/ready/error |
+| `q` | str | null | Text search on title |
+| `limit` | int | 20 | How many to return |
+
+## Workflow
+
+### Step 1 — Call the right endpoint
+
+```python
+from dashboard.backend.sdk_client import evo
+
+if scope == "documents":
+    params = {k: v for k, v in {
+        "space": space, "unit_id": unit_id, "content_type": content_type,
+        "difficulty": difficulty, "topics": ",".join(topics or []),
+        "status": status, "q": q, "limit": limit,
+    }.items() if v is not None}
+    items = evo.get("/api/knowledge/v1/documents", params=params,
+                    headers={"X-Knowledge-Connection": connection})
+elif scope == "units":
+    params = {"space": space, "limit": limit}
+    items = evo.get("/api/knowledge/v1/units", params=params,
+                    headers={"X-Knowledge-Connection": connection})
+```
+
+### Step 2 — Render markdown table
+
+Documents:
+
+```
+| Title | Type | Difficulty | Topics | Chunks | Status | Added |
+|---|---|---|---|---|---|---|
+| ... | lesson | beginner | [whatsapp, auth] | 14 | ready | 2026-04-20 |
+```
+
+Units:
+
+```
+| Title | Slug | Space | Seq | Docs | Created |
+|---|---|---|---|---|---|
+| ... | ... | academy | 1 | 5 | 2026-04-15 |
+```
+
+### Step 3 — Footer
+
+```
+Showing {len(items)} of {total} {scope} in {connection}{/space if filtered}.
+Filters applied: {filters_summary}.
+```
+
+## Actionable failures
+
+- 0 results → suggest relaxing filters
+- Space not found → list available spaces
+- Connection not found → "Run `knowledge-admin action=health`"