@yugabytedb/meko-mcp 2.0.0 → 2.1.0

package/assets/skills/meko-mcp-tools/references/tools-overview.md

@@ -1,13 +1,13 @@
 # Complete Tool Catalog and Decision Tree
 
-**22 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
+**23 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
-1. `memory_search(scope="read", query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list(scope="read")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+1. `memory_search(query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
+2. `datapack_list()` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
 
 ## Decision tree: which tool do I need?
 
@@ -20,6 +20,7 @@ User wants to...
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
 │   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
 │   ├── Search past knowledge? --------------------> memory_search (read)
+│   ├── Share private memories with the team? -----> memory_promote (write; owner/maintainer only)
 │   └── Retrieve a past conversation? -------------> conversation_get (read)
 ├── Persist or retrieve a file?
 │   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
@@ -32,58 +33,58 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 
 ## Knowledge Base Tools (1)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `knowledgebase_search(scope, query, agent_id, conversation_id, datapack_id, limit=10)` | read | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
+| Tool | Purpose |
+|------|---------|
+| `knowledgebase_search(query, agent_id, conversation_id, datapack_id, limit=10)` | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
 
 ## Memory Tools (8)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `memory_add(scope, text, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | write | Store fact/preference/entity as long-term memory |
-| `memory_search(scope, query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | read | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
-| `memory_get_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | read | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
-| `memory_get_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | read | List all memories for agent |
-| `memory_update(scope, memory_id, text, agent_id, conversation_id, datapack_id=None)` | write | Overwrite memory text |
-| `memory_delete_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | write | Delete a single memory |
-| `memory_delete_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | admin | Delete all memories for agent (destructive) |
-| `flush_pending_memory_candidates(scope, agent_id)` | read | **Deprecated.** Superseded by automatic extraction from posted turns — post substantive turns with `conversation_add_message` and the server extracts memories from them. Now returns a `deprecated` payload pointing at `conversation_add_message`; kept one release for backward compatibility. |
+| Tool | Purpose |
+|------|---------|
+| `memory_add(text, agent_id, conversation_id, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
+| `memory_search(query, agent_id, conversation_id="", limit=10, datapack_id=None)` | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
+| `memory_get_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
+| `memory_get_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | List all of the user's memories (every agent — `agent_id` does not filter) |
+| `memory_update(memory_id, text, agent_id, conversation_id, datapack_id=None)` | Overwrite memory text |
+| `memory_delete_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Delete a single memory |
+| `memory_delete_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | Delete all memories for agent (destructive) |
+| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them + graph context out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403. |
 
 ## Conversation Tools (6)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `conversation_create(scope, agent_id, user_id=None, app_id=None, run_id=None, title=None, metadata=None, session_id="")` | write | Create conversation container (Langfuse session) |
-| `conversation_add_message(scope, conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None, trace_id="")` | write | Add a message turn (Langfuse trace) |
-| `conversation_get(scope, conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | read | Retrieve conversation, optionally with messages |
-| `conversation_list(scope, agent_id, conversation_id="", user_id=None, limit=20, offset=0)` | read | List conversations for agent. `conversation_id` optional (omit for browse). |
-| `conversation_update(scope, conversation_id, agent_id, title=None, metadata=None)` | write | Update title or metadata |
-| `conversation_delete(scope, conversation_id, agent_id)` | admin | Delete entire conversation (destructive) |
+| Tool | Purpose |
+|------|---------|
+| `conversation_create(agent_id, run_id=None, title=None, metadata=None, session_id="")` | Create conversation container (Langfuse session) |
+| `conversation_add_message(conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None)` | Add a message turn (Langfuse trace) |
+| `conversation_get(conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | Retrieve conversation, optionally with messages |
+| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_list` to look it up. `conversation_id` optional (omit for browse). |
+| `conversation_update(conversation_id, agent_id, title=None, metadata=None)` | Update title or metadata |
+| `conversation_delete(conversation_id, agent_id)` | Delete entire conversation (destructive) |
 
 ## Datapack Management Tools (5)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `datapack_create(scope, name)` | write | Create new datapack |
-| `datapack_list(scope)` | read | List all datapacks |
-| `datapack_describe(scope, datapack_id, include_status=False)` | read | Describe datapack by UUID |
-| `datapack_update(scope, datapack_id, connection_string)` | write | Update connection string |
-| `datapack_delete(scope, datapack_id)` | admin | Delete datapack by UUID (irreversible) |
+| Tool | Purpose |
+|------|---------|
+| `datapack_create(name)` | Create new datapack |
+| `datapack_list()` | List all datapacks |
+| `datapack_describe(datapack_id, include_status=False)` | Describe datapack by UUID |
+| `datapack_update(datapack_id, name=None, description=None)` | Rename a datapack and/or update its description. Pass at least one of `name` / `description`. |
+| `datapack_delete(datapack_id)` | Delete datapack by UUID (irreversible) |
 
 ## Artifact Tools (2)
 
 Content-addressed blob store scoped to a datapack. Files < 1 MB go inline in the DB; files ≥ 1 MB go to S3. Identity is SHA-256 — uploading the same bytes twice returns the same `content_hash`. Free-tier artifacts expire after 30 days of inactivity; pro-tier artifacts have no TTL.
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `artifact_put(scope, filename, content_base64, content_type, conversation_id, datapack_id=None, agent_id=None)` | write | Upload a file to the datapack. Returns `{artifact_id, content_hash, filename, size_bytes, stored_in}`. Max 5 MiB (configurable via `MEKO_MAX_ARTIFACT_UPLOAD_BYTES`). |
-| `artifact_get(scope, content_hash, conversation_id, datapack_id=None, agent_id=None)` | read | Retrieve a file by SHA-256 hash. Small files return `content_base64` inline; large files (S3) are written to `~/.meko/artifacts/<hash>/<filename>` and `local_path` is returned. |
+| Tool | Purpose |
+|------|---------|
+| `artifact_put(filename, content_base64, content_type, conversation_id, datapack_id=None, agent_id=None)` | Upload a file to the datapack. Returns `{artifact_id, content_hash, filename, size_bytes, stored_in}`. Max 5 MiB (configurable via `MEKO_MAX_ARTIFACT_UPLOAD_BYTES`). |
+| `artifact_get(content_hash, conversation_id, datapack_id=None, agent_id=None)` | Retrieve a file by SHA-256 hash. Small files return `content_base64` inline; large files (S3) are written to `~/.meko/artifacts/<hash>/<filename>` and `local_path` is returned. |
 
 ## Observability Tools (1)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `track_token_usage(scope, conversation_id, name, input_tokens=0, output_tokens=0, total_tokens=None, model=None, message_id=None, datapack_id=None)` | write | Record an LLM-cost GENERATION observation on the conversation's trace. Primarily called by first-party Meko services (e.g. inference_gateway) that know their LLM's exact token counts. Most end-agents (Cursor, Claude Desktop) don't have those counts at the MCP call layer, so this tool is rarely useful for third-party agents. |
+| Tool | Purpose |
+|------|---------|
+| `track_token_usage(conversation_id, name, input_tokens=0, output_tokens=0, total_tokens=None, model=None, message_id=None, datapack_id=None)` | Record an LLM-cost GENERATION observation on the conversation's trace. Primarily called by first-party Meko services (e.g. inference_gateway) that know their LLM's exact token counts. Most end-agents (Cursor, Claude Desktop) don't have those counts at the MCP call layer, so this tool is rarely useful for third-party agents. |
 
 ## Platform capabilities NOT exposed via MCP
 
@@ -102,4 +103,4 @@ For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapa
 
 ## Common Parameter Patterns
 
-Every tool accepts `scope` as the first parameter. Memory and KB tools accept optional `datapack_id` to target a specific datapack. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).
+Memory and KB tools accept optional `datapack_id` to target a specific datapack. `agent_id` attributes writes and is enforced only on `conversation_get` (agent-owned — a wrong value returns `agent_id_mismatch`); it does **not** filter memory reads (`memory_search`/`memory_get_all`) or `conversation_list`, which return all your agents' rows for the user. See `tools-agent-id-conventions.md`.

package/assets/skills/meko-mcp-tools/references/tools-rag-workflow.md

@@ -16,7 +16,6 @@ creation and ingestion happen out of band — through the **Meko UI**
 
 ```
 knowledgebase_search(
-    scope="read",
     query="natural-language question",
     agent_id="<your agent_id>",
     conversation_id="<uuid from conversation_create>",
@@ -24,7 +23,7 @@ knowledgebase_search(
     limit=10)
 ```
 
-Required: `scope`, `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Required: `query`, `agent_id`, `conversation_id`, `datapack_id`.
 Unlike the memory tools, `datapack_id` has no default here — you must
 pass it explicitly. `agent_id` is **ignored for filtering** on this
 tool (KB results are team-shared on the datapack), but you still pass

package/assets/skills/meko-mcp-tools/references/tools-troubleshooting.md

@@ -7,7 +7,7 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
 2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
 3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
-4. **Use your session's `agent_id` consistently.** Pass the value the SessionStart hook injected (e.g. `claude_code:<repo-basename>` for Claude Code; `claude_desktop` for Claude Desktop) on every write and every personal read. Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the cross-project common bucket — empty string also resolves to `meko_agent`, not a cross-agent fan-out. Don't switch between forms mid-session.
+4. **Use your session's `agent_id` consistently on writes.** Pass the value the SessionStart hook injected (e.g. `claude_code:<repo-basename>` for Claude Code; `claude_desktop` for Claude Desktop) on every write so rows are attributed correctly, and on `conversation_get` (which *does* enforce it — conversations are owned by the `agent_id` that created them; a wrong value returns `agent_id_mismatch`). Memory reads (`memory_search`/`memory_get_all`) and `conversation_list` are not affected — they return all your agents' rows for this user regardless of the `agent_id` passed. Don't switch write forms mid-session.
 
 ---
 
@@ -26,20 +26,6 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 ---
 
-## Scope parameter errors
-
-**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
-
-The only valid scope values are: `"read"`, `"write"`, `"admin"`.
-
-- Use `"read"` for all read operations (default choice)
-- Use `"write"` for inserts, updates, creates, memory writes
-- Use `"admin"` only for destructive deletes
-
-**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
-
----
-
 ## agent_id errors
 
 On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.
@@ -52,9 +38,9 @@ If you call `memory_add` with empty / None / whitespace `agent_id`, the server d
 
 Fix: always pass a concrete non-empty `agent_id`. Fetch the value the SessionStart hook injected into `additionalContext` and pass it verbatim. Use `agent_id="meko_agent"` only when you genuinely want a fact in the cross-project pool (user identity, global preferences).
 
-### "My reads return fewer results than I expected"
+### "My memory reads return fewer results than I expected"
 
-`memory_search` and `memory_get_all` filter strictly on your passed `agent_id`. A memory written by `claude-code:<slug-A>` is invisible to a search with `agent_id="cursor:<slug-B>"`. If you need a broader view, call repeatedly across the agent_ids you want to cover, or point the user at the UI's Memory Summary page (which shows every row regardless of agent_id).
+`memory_search` and `memory_get_all` do **not** filter by `agent_id` — a single call returns all of your memories for this user across every agent, so a mismatched `agent_id` is not the cause. If results seem thin, check that you're on the right datapack (`datapack_id`), that the write actually landed (mem0 extraction is lossy — see `tools-memory-vs-conversation.md`), and that the query is semantically close to the stored text. `conversation_get`, by contrast, *is* agent-owned: pass the exact `agent_id` the conversation was created under, or you'll get `agent_id_mismatch`. `conversation_list` is not agent-filtered — it returns the datapack's conversations for your user regardless of the `agent_id` passed.
 
 ### "I'm seeing rows tagged with legacy agent_id values"
 
@@ -66,7 +52,7 @@ Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, o
 
 | Tool | Safe to retry? | Why |
 |------|---------------|-----|
-| All `read` scope tools | Yes | Reads are idempotent |
+| All read-only tools | Yes | Reads are idempotent |
 | `memory_add` | Yes (once) | Mem0 has dedup logic |
 | `memory_update` | Yes (once) | Overwrites same ID |
 | `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |

package/assets/skills/meko-mcp-tools/references/tools-user-id-conventions.md

@@ -1,6 +1,6 @@
 # user_id — identity scoping on Cloud Meko
 
-On Cloud Meko, every write and every personal read carries a `user_id` that identifies **who** (the cognito account) is calling. The filter tuple for personal memories and conversations is `(datapack_id, user_id, agent_id)` — you only ever see memories your own user_id wrote (or content other team members have explicitly promoted to Shared Knowledge, which is separate — see `tools-agent-id-conventions.md`).
+On Cloud Meko, every write and every personal read carries a `user_id` that identifies **who** (the cognito account) is calling. The read filter for personal **memories** is `(datapack_id, user_id)` — you see all your own memories for this user regardless of which agent wrote them (`agent_id` labels the writer but does not filter memory reads). Personal **conversation fetches** (`conversation_get`) additionally enforce `agent_id` — conversations are owned by the agent that created them; `conversation_list` does not filter by it. Either way you only ever see content your own user_id wrote (or content other team members have explicitly promoted to Shared Knowledge, which is separate — see `tools-agent-id-conventions.md`).
 
 ## The default behavior: automatic user_id from cognito
 
@@ -9,7 +9,7 @@ On Cloud, the server resolves your `user_id` automatically from the cognito acco
 This is the common case for Claude Code / Claude Desktop / Cursor:
 
 ```
-memory_add(scope="write",
+memory_add(
            text="User prefers concise responses, no emojis.",
            agent_id="claude_code:meko-mcp-server",
            conversation_id="<session conversation_id>")
@@ -24,21 +24,21 @@ Explicit `user_id` is an **optional sub-scope** for agents that serve multiple e
 
 ```
 # Serving Alice
-memory_add(scope="write",
+memory_add(
            text="Alice prefers email communication. Has Pro plan.",
            agent_id="support-bot",
            user_id="alice_123",
            conversation_id="<conv>")
 
 # Serving Bob — completely separate partition, same cognito account
-memory_add(scope="write",
+memory_add(
            text="Bob prefers Slack. On Enterprise plan.",
            agent_id="support-bot",
            user_id="bob_456",
            conversation_id="<conv>")
 
 # Search only returns Alice's memories
-memory_search(scope="read",
+memory_search(
               query="communication preference",
               agent_id="support-bot",
               user_id="alice_123",
@@ -60,11 +60,12 @@ Mixing creates invisible data.
 
 | Layer | Filter | Role of user_id |
 |---|---|---|
-| Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id, agent_id)` | Enforced on every read. One user cannot see another's un-promoted memories. |
-| Personal conversations (`conversation_list`, `conversation_get`) | Same tuple | Enforced. Cross-user reads require promotion. |
+| Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id)` | Enforced on every read. `agent_id` is not applied — one user sees all their own memories across every agent, but cannot see another user's un-promoted memories. |
+| Conversation listing (`conversation_list`) | `(datapack_id, user_id)` | Enforced. `agent_id` is not applied — you see all your own conversations across every agent. |
+| Conversation fetch (`conversation_get`) | `(datapack_id, user_id, agent_id)` | Enforced. Agent-owned: pass the creating `agent_id` or you get `agent_id_mismatch`. Cross-user reads require promotion. |
 | Team Shared Knowledge (`knowledgebase_search`) | `(datapack_id)` only | **Not used** — `user_id` is stripped when a memory is promoted to Knowledge. All team members on the datapack see the same Shared Knowledge. |
 
-The "Promote to Knowledge" action in the Cloud UI is the one way personal content crosses the user_id boundary. There is no MCP tool for promotion (user-initiated via UI only).
+Personal content crosses the `user_id` boundary through `memory_promote` or the Cloud UI's "Promote to Knowledge" action. The MCP path requires exact memory UUIDs, explicit user confirmation, and an owner/maintainer role; it moves the records into team-visible Shared Knowledge and evicts the private copies.
 
 ## Parameter summary
 

package/assets/skills/meko-mcp-tools-desktop/SKILL.md

@@ -17,19 +17,19 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "2.7.0"
+  version: "2.7.2"
   tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko, desktop
 ---
 
 # Meko MCP Tools — Agent Behavioral Guide (Desktop)
 
-Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 22 MCP tools. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
+Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 23 MCP tools. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
 
 **Read this first.** The Meko server extracts durable memories automatically from the conversation turns you post to it — the extraction runs *inside* `conversation_add_message`. Claude Desktop has no capture hooks, so **capturing substantive turns via `conversation_add_message` is a core part of using this skill.** Do that and memory takes care of itself: facts the user states get extracted and stored without a separate `memory_add`. Explicit `memory_add` is reserved for a few narrow cases (below). See "Per-turn conversation capture" — it's the heart of this skill.
 
 **Why this is legitimate.** Meko is the user's own system of record — serving their memory, their team's shared knowledge, and their observability/audit needs — so posting turns to it is maintaining *their* infrastructure, the same as keeping notes or decision logs. Do it **transparently**: briefly tell the user when you save or recall ("saved that to your Meko memory", "checked your Meko memory — here's what I had"), disclose the way a colleague would mention they're writing something down. The only carve-outs: if an item is sensitive (credentials, legal, medical) or the user asked you not to store something, ask or skip.
 
-> **If you reached a meko tool without reading this skill** (e.g. tool search resolved `memory_add`/`memory_search` directly): two rules override anything you inferred from the raw tool descriptions. (1) On Claude Desktop the `agent_id` is **always `"claude_desktop"`** (or `"meko_agent"` for cross-project identity) — **never `"claude_code"`**, which is a *different* client's bucket. (2) Prefer `conversation_add_message` over `memory_add` for facts the user stated — extraction handles them. Then read the rest of this skill.
+> **If you reached a meko tool without reading this skill** (e.g. tool search resolved `memory_add`/`memory_search` directly): two rules override anything you inferred from the raw tool descriptions. (1) On Claude Desktop use `agent_id="claude_desktop"` for normal writes (or `"meko_agent"` for cross-project writes) — never attribute Desktop writes to `"claude_code"`. (2) Prefer `conversation_add_message` over `memory_add` for facts the user stated — extraction handles them. Then read the rest of this skill.
 
 ## First turn of every session
 
@@ -39,12 +39,12 @@ On the first user turn in any session, before answering substantive questions:
 
 1. **Resolve the active datapack pin first — before creating the conversation.** A conversation cannot move between datapacks once created, so you must know the pinned datapack *before* `conversation_create`, or capture lands in the wrong workspace. Call:
    ```
-   memory_search(scope="read", query="meko_active_datapack",
+   memory_search(query="meko_active_datapack",
                  agent_id="claude_desktop", conversation_id="", limit=1)
    ```
    If a pin row comes back, extract the UUID after `meko_active_datapack=` — call it `<PIN>` — and pass `datapack_id="<PIN>"` to **every** Meko call for the rest of the session (`conversation_create`, `memory_search`, `conversation_add_message`, etc.). If no pin is found, omit `datapack_id` everywhere and let the server resolve the default. (The `meko-select-datapack-desktop` skill is what writes this pin; you honor it here whether or not that skill ran this session.)
 2. **Call `conversation_create`** (`agent_id="claude_desktop"`, and `datapack_id="<PIN>"` if a pin was found) once and keep the returned `conversation_id` for the whole session. You need it to post turns (per-turn capture, above) and for memory calls.
-3. **Call `memory_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. Also call it once with `agent_id="meko_agent"` to surface cross-project facts (user identity, global preferences) that any Meko client may have stored.
+3. **Call `memory_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. One search returns this user's memories across every agent, including the `meko_agent` common bucket; `agent_id` attributes the trace but does not filter memory results.
 4. Incorporate the recalled facts into your reply. Don't re-ask things you've been told before.
 
 Recall and capture are routine parts of answering — the user has set Meko up as their memory layer, so you don't need a per-call permission prompt for them. Do briefly say what you did ("checked your Meko memory", "saved that to your Meko memory") — a short disclosure, not a silent background action and not a big announcement.
@@ -56,10 +56,11 @@ Recall and capture are routine parts of answering — the user has set Meko up a
 **For Claude Desktop, use `agent_id="claude_desktop"` by default.** Desktop has no per-project concept, so a stable client name is the right granularity (it's a "loose" client in contract terms). Coding agents like Claude Code and Cursor use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts that any agent should see — user identity, global preferences — use the common bucket `agent_id="meko_agent"`.
 
 **Read scoping:**
-- `memory_search` / `memory_get_all` / `conversation_list` / `conversation_get` — scoped to `(datapack_id, user_id, agent_id)`, strictly matched. To read across multiple agents (e.g. memories you wrote from Claude Code in different repos), call once per agent_id. Empty/missing `agent_id` is rewritten to `meko_agent` server-side, so it returns the common bucket only — not a fan-out.
-- `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus memories the user promoted via the UI.
+- `memory_search` / `memory_get_all` — scoped to `(datapack_id, user_id)`. `agent_id` does not filter results, so one call returns this user's memories across every agent.
+- `conversation_list` — also returns this user's conversations across agents. `conversation_get` is agent-owned and requires the exact `agent_id` that created the conversation.
+- `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus promoted memories.
 
-Some pre-existing rows use the older constant `agent_id="agent"` or ad-hoc shapes (e.g. `claude-desktop` with a hyphen). They remain readable — query them with the literal value. See `tools-agent-id-conventions.md` for the full model.
+Some pre-existing rows use the older constant `agent_id="agent"` or ad-hoc shapes (e.g. `claude-desktop` with a hyphen). They remain readable; the stored value is still shown as provenance in the UI. See `tools-agent-id-conventions.md` for the full model.
 
 ## Per-turn conversation capture — the heart of this skill
 
@@ -68,7 +69,7 @@ Claude Desktop has no capture hooks, so you are the capture mechanism. **When th
 Concretely, once per session call `conversation_create` (see "First turn of every session" above) to get a `conversation_id`, then for each substantive exchange:
 
 ```
-conversation_add_message(scope="write", conversation_id="<id>",
+conversation_add_message(conversation_id="<id>",
     agent_id="claude_desktop",
     input="<the user's exact prompt>",
     output="<your exact response>",
@@ -99,8 +100,8 @@ Use the right bucket: `agent_id="meko_agent"` for cross-project facts (user iden
 
 Meko turns your volatile context window into persistent, shareable knowledge:
 
-- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions. Private to you (scoped per-user and per-agent).
-- **Team-shared knowledge** — Memories the user promotes from the Learnings tab in the Cloud UI become visible to every member of the datapack. Uploaded documents land in the same place. Both are queryable via `knowledgebase_search`.
+- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions. Private to the user and readable across all of their agents.
+- **Team-shared knowledge** — Important memories can be promoted with `memory_promote` (after explicit confirmation) or from the Learnings tab in the Cloud UI. Uploaded documents land in the same place. The resulting content is visible to every datapack member and queryable via `knowledgebase_search`.
 - **Conversation history** — Preserve full dialog exchanges with reasoning traces for audit, replay, and learning transfer.
 - **Decision traces** — Capture how and why decisions were made, enabling debugging and continuous improvement.
 
@@ -110,7 +111,7 @@ Meko turns your volatile context window into persistent, shareable knowledge:
 - You need to decide what to store, where, and how (personal memory vs. team-shared knowledge)
 - You want to search the team's shared knowledge base (`knowledgebase_search`)
 - You are managing datapacks
-- You want to understand scope/permission requirements, `agent_id` conventions, or `datapack_id` routing
+- You want to understand `agent_id` conventions, or `datapack_id` routing
 
 ## Critical: Use Meko, not local storage
 
@@ -139,8 +140,9 @@ Your job is not to decide fact-by-fact what to `memory_add`. It's to **post ever
 | User corrects or negates a prior fact | Post the turn (the new fact is extracted). Extraction is **additive**, so if the stale fact must not survive, `memory_search` for it and `memory_update` / `memory_delete_by_id`. |
 | User explicitly says "remember this" | `memory_add` (verbatim), in addition to posting the turn. |
 | A durable fact lives only in your output or a tool result | `memory_add`. Extraction reads the user side of the turn, so it won't capture these. |
-| User asks "what do you know about X?" | Three-call sweep: `memory_search(agent_id="claude_desktop")` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search(datapack_id=<X>)`. |
+| User asks "what do you know about X?" | Two-call sweep: one `memory_search(agent_id="claude_desktop")` covers this user's memories across every agent; `knowledgebase_search(datapack_id=<X>)` covers team-shared knowledge. |
 | User asks "what do we (as a team) know about X?" or about uploaded documents | `knowledgebase_search` (returns uploaded docs + promoted memories). |
+| User asks to share specific private memories with the team | Follow the `memory_promote` confirmation workflow below. Never promote based on a fuzzy search result or implied consent. |
 | User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP. Point the user at the UI's Add Knowledge upload; do not `memory_add` row-by-row. |
 | User wants to add documents to the team's knowledge base | Point them at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). MCP ingestion tools are not available on Cloud. |
 
@@ -151,7 +153,7 @@ The **what and when** is covered above ("Per-turn conversation capture" — post
 `conversation_create` — once per session; keep the `conversation_id`:
 
 ```
-conversation_create(scope="write", agent_id="claude_desktop",
+conversation_create(agent_id="claude_desktop",
     title="<descriptive topic>")
 ```
 
@@ -170,29 +172,23 @@ conversation_create(scope="write", agent_id="claude_desktop",
 
 Only for the three exception cases (explicit "remember this", output-only/tool-derived fact, overwriting correction) — not for facts the user stated, which the posted turn already captures. Example of an explicit save:
 ```
-memory_add(scope="write",
+memory_add(
            text="Remember: deploy scripts must be run from the repo root, never a subdir",
            agent_id="claude_desktop",
            conversation_id="<id from conversation_create>")
 ```
-Required parameters: `scope`, `text`, `agent_id`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID from `conversation_create` — writes attached to a nil/empty conversation are orphaned in Langfuse traces. Empty / missing `agent_id` is NOT rejected — the server quietly falls back to the `meko_agent` common bucket. Pass `agent_id="claude_desktop"` explicitly so this client's writes stay in the right bucket and don't pollute the cross-project pool.
+Required parameters: `text`, `agent_id`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID from `conversation_create` — writes attached to a nil/empty conversation are orphaned in Langfuse traces. Empty / missing `agent_id` is NOT rejected — the server quietly falls back to the `meko_agent` common bucket. Pass `agent_id="claude_desktop"` explicitly so this client's writes stay in the right bucket and don't pollute the cross-project pool.
 
 ### memory_search — correct call pattern
 ```
-memory_search(scope="read",
+memory_search(
               query="user role",
               agent_id="claude_desktop",
               conversation_id="<id from conversation_create>")
 ```
-Required parameters: `scope`, `query`, `agent_id`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation; passing `""` is accepted and means "don't nest under any trace." For conversation-scoped filtering use the separate `run_id` parameter.
+Required parameters: `query`, `agent_id`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation; passing `""` is accepted and means "don't nest under any trace." For conversation-scoped filtering use the separate `run_id` parameter.
 
-For cross-project common-bucket search (facts written under `agent_id="meko_agent"`, including everything written with empty/missing `agent_id`), pass it explicitly:
-```
-memory_search(scope="read", query="user role",
-              agent_id="meko_agent", conversation_id="<id>")
-```
-
-Empty string also resolves to `meko_agent` server-side. To search across other clients' specific buckets (e.g. `claude_code:some-repo`), call `memory_search` once per known agent_id — there's no single-call fan-out.
+`agent_id` attributes the search trace but does not filter the returned memories. One call includes rows written by `claude_desktop`, `meko_agent`, coding agents, and legacy agent values for this user.
 
 **Interpreting results — trust the memory rows, be skeptical of stray `relations`.** `memory_search` returns three lists: `results` (the actual stored memories — trust these), `relations`, and `promoted_relations` (entity-graph edges). Two things to know so you don't discard useful results:
 
@@ -201,44 +197,55 @@ Empty string also resolves to `meko_agent` server-side. To search across other c
 
 ### knowledgebase_search — correct call pattern
 ```
-knowledgebase_search(scope="read",
+knowledgebase_search(
                      query="...",
                      agent_id="<anything — ignored>",
                      conversation_id="<id>",
                      datapack_id="<datapack UUID>",
                      limit=10)
 ```
-Required parameters: `scope`, `query`, `agent_id`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
+Required parameters: `query`, `agent_id`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
+
+### memory_promote — explicit confirmation required
+
+`memory_promote` is destructive and non-idempotent: it makes selected content visible to the datapack, moves the memories and graph context into shared knowledge, and evicts the private mem0 records. There is no MCP rollback.
+
+1. Use `memory_search` or `memory_get_all` to obtain exact memory UUIDs. Never pass relation or graph-edge IDs.
+2. Present each exact candidate memory and its UUID to the user.
+3. State that promotion is one-way, team-visible, and removes the private records.
+4. Obtain explicit confirmation for those exact candidates before calling `memory_promote`.
+5. Call it with the active `conversation_id`, exact `memory_ids`, `agent_id="claude_desktop"`, and intended `datapack_id`. If a legacy deployment exposes `scope`, use the minimum `write` scope; do not escalate to `admin`.
+6. Only datapack owners and maintainers may promote. If a viewer/contributor receives 403, or any authentication/permission error occurs, report it and stop. Do not retry with a broader scope, another datapack, or altered identity.
+7. After success, optionally verify visibility with `knowledgebase_search`. Do not claim rollback is possible.
+
+The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 ### Critical parameter rules
 
-- **agent_id**: `"claude_desktop"` for this client's project-less personal writes/reads. Use `"meko_agent"` for the cross-project common bucket (genuinely global facts like user identity). Empty/missing routes to `meko_agent` server-side; that's not a cross-agent fan-out. Ignored on `knowledgebase_search`. See `tools-agent-id-conventions.md`.
+- **agent_id**: `"claude_desktop"` for this client's project-less writes and trace attribution. Use `"meko_agent"` when writing genuinely cross-project facts such as user identity. Empty/missing values on writes route to `meko_agent`. The value does not filter `memory_search`, `memory_get_all`, `conversation_list`, or `knowledgebase_search`; `conversation_get` is the read that requires the creating agent's exact value. See `tools-agent-id-conventions.md`.
 - **conversation_id**: Behavior varies by tool. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` — a nil/empty value orphans the Langfuse trace. On `memory_search` it's used only for trace nesting (not for filtering), and empty-string is accepted; on `memory_get_all` and most read tools, still pass the session UUID when you have one. Never pass `"current"` or other non-UUID junk — only a real UUID or an intentionally empty string where the tool allows it.
-- **scope**: Only `"read"`, `"write"`, or `"admin"`. Nothing else.
 - **When in doubt about optional parameters, omit them.** The server has sensible defaults.
 
 ## Key concepts
 
-1. **22 tools in 5 groups**: Memory (8 — including `flush_pending_memory_candidates`, deprecated; per-turn `conversation_add_message` replaces it), Conversation (6), Knowledge Base (1 — `knowledgebase_search`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`). KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. See `tools-overview.md`.
-2. **Scope hierarchy**: `read < write < admin` — every tool validates scope at entry. Only three valid values: `"read"`, `"write"`, `"admin"`. Using anything else (e.g., `"all"`) will fail. Pass the **minimum** each tool needs: reads (`memory_search`, `memory_get_*`, `conversation_get`/`list`, `datapack_list`/`describe`) take `"read"`; writes (`memory_add`/`update`, `conversation_create`/`add_message`, `datapack_create`/`update`) take `"write"`; only the destructive tools (`memory_delete_all`, `conversation_delete`, `datapack_delete`) require `"admin"`. Each tool's docstring states its required scope — follow it; don't escalate a search to `"admin"`.
-3. **datapack_id routing**: DB, RAG, and memory tools accept optional `datapack_id` (default datapack if omitted). `knowledgebase_search` is the exception: `datapack_id` is **required** there.
-4. **agent_id is multi-agent**: For Claude Desktop, use `agent_id="claude_desktop"` for desktop-personal writes and `agent_id="meko_agent"` for cross-project common facts. Writes are scoped to `(datapack_id, user_id, agent_id)`. Personal reads filter strictly on this tuple — to span agent_ids, call once per known value (the empty-string shortcut is not a fan-out; the server rewrites empty to `meko_agent`). `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
-5. **Personal memory vs. team-shared knowledge**: Un-promoted memories are scoped per-user and per-agent — only you see them. The user can promote important memories to Shared Knowledge via the Cloud UI's Learnings tab, which makes them visible to every team member on the datapack. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
-6. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
-7. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
-8. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
-9. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly.
-10. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
-11. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
+1. **23 tools in 6 groups**: Memory (8 — including `memory_promote`), Conversation (6), Knowledge Base (1 — `knowledgebase_search`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`), Observability (1 — `track_token_usage`). Memory is captured automatically from turns posted with `conversation_add_message` — post each substantive turn and the server extracts durable memories from it. KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. See `tools-overview.md`.
+2. **datapack_id routing**: DB, RAG, and memory tools accept optional `datapack_id` (default datapack if omitted). `knowledgebase_search` is the exception: `datapack_id` is **required** there.
+3. **agent_id is multi-agent**: For Claude Desktop, use `agent_id="claude_desktop"` for normal writes and `agent_id="meko_agent"` for cross-project facts. Writes are attributed to `(datapack_id, user_id, agent_id)`. Personal memory reads and `conversation_list` span all of this user's agents; `conversation_get` remains agent-owned. `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
+4. **Personal memory vs. team-shared knowledge**: Un-promoted memories are scoped per-user — readable across all of that user's agents, but no other user can see them. With explicit confirmation, `memory_promote` moves exact memories into Shared Knowledge; the Cloud UI's Learnings tab is an alternative. Promoted content is visible to every datapack member. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
+5. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
+6. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
+7. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
+8. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly.
+9. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
+10. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
 
 ## Reference sections
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 22 tools with decision tree |
+| `tools-overview.md` | Complete catalog of all 23 tools with decision tree |
 | `tools-cookbook.md` | Per-tool examples with correct parameters, responses, and error cases |
 | `tools-memory-vs-conversation.md` | When to use memory tools vs conversation tools |
 | `tools-rag-workflow.md` | End-to-end RAG pipeline flow |
-| `tools-scope-permissions.md` | read/write/admin permission hierarchy |
 | `tools-troubleshooting.md` | Error recovery, retry strategies, stuck pipeline diagnosis |
 | `tools-known-limitations.md` | Broken tools, missing capabilities, permission gaps |

package/assets/skills/meko-mcp-tools-desktop/desktop/README.md

@@ -1,6 +1,6 @@
 # Meko MCP Tools — Claude Desktop Setup
 
-Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all 25 Meko MCP tools correctly, and to handle errors gracefully.
+Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all <!--tool-count-->23<!--/tool-count--> Meko MCP tools correctly, and to handle errors gracefully.
 
 ## Setup
 
@@ -12,21 +12,21 @@ In Claude Desktop: Customize > Personal plugins > Browse plugin marketplace. Sea
 
 **Option B — .skill file:**
 
-Download `meko-mcp-tools-desktop.skill` from the [releases page](https://github.com/yugabyte/meko-mcp-server/releases) and drag it into Claude Desktop (or use Customize > Skills > Import).
+Download `meko-mcp-tools-desktop.skill` from the [releases page](https://github.com/yugabyte/meko-skills/releases) and drag it into Claude Desktop (or use Customize > Skills > Import).
 
 **Option C — Manual install:**
 
 ```bash
-git clone https://github.com/yugabyte/meko-mcp-server.git
+git clone https://github.com/yugabyte/meko-skills.git
 ```
 
-Copy `skills/skills/meko-mcp-tools-desktop/` into Claude Desktop's skill directory. The exact path depends on your Desktop version — check Customize > Skills for the install location.
+Copy `skills/meko-mcp-tools-desktop/` into Claude Desktop's skill directory. The exact path depends on your Desktop version — check Customize > Skills for the install location.
 
 ### Step 2: Configure the MCP server
 
 Add the Meko MCP server to your Claude Desktop configuration. Go to Claude > Settings > Developer > Edit Config and add a `mcpServers` entry.
 
-**Local HTTP** (for [meko-test](https://github.com/yugabyte/meko-test) docker-compose users):
+**Local HTTP** (for local Meko development environments):
 
 ```json
 {
@@ -70,7 +70,7 @@ Replace `/path/to/meko-mcp-server` with your cloned repo path and set the correc
 {
   "mcpServers": {
     "meko": {
-      "url": "https://<your-instance>.mcp.mekodev.com/mcp"
+      "url": "https://mcp.mekodata.ai/mcp"
     }
   }
 }

package/assets/skills/meko-mcp-tools-desktop/references/_sections.md

@@ -6,15 +6,15 @@ description: Maps reference files to their topics for the meko-mcp-tools-desktop
 # Reference Sections
 
 ## Tool Selection & Catalog
-- [tools-overview.md](tools-overview.md) — Complete catalog of all 22 tools with a decision tree
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 23 tools with a decision tree
 
 ## Tool-Specific Guidance
 - [tools-agent-id-conventions.md](tools-agent-id-conventions.md) — Multi-agent model: the three buckets (project `<client>:<repo-basename>`, common `meko_agent`, loose client name), personal vs. team-shared read surfaces
 - [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message, plus Desktop capture guidance
+- [tools-conversation-reasoning.md](tools-conversation-reasoning.md) — Authoring the `reasoning` and `plan` fields on `conversation_add_message`, with worked examples
 - [tools-rag-workflow.md](tools-rag-workflow.md) — End-to-end RAG pipeline: source registration, index creation, status polling
 
 ## Safety & Permissions
-- [tools-scope-permissions.md](tools-scope-permissions.md) — read/write/admin permission hierarchy and per-tool requirements
 
 ## Practical Usage
 - [tools-cookbook.md](tools-cookbook.md) — Per-tool examples with correct parameters, expected responses, and common errors