@yugabytedb/meko-mcp 1.2.0 → 2.1.0

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

@@ -7,13 +7,13 @@ 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.** For Claude Desktop the default is `claude_desktop`; for cross-project common facts use `meko_agent`. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the 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.** For Claude Desktop the default is `claude_desktop`; use `meko_agent` when writing cross-project facts. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Memory reads and `conversation_list` span all of this user's agents regardless of the value passed; `conversation_get` requires the creating agent's exact value.
 
 ---
 
 ## Connection errors: "connection already closed"
 
-**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently. DB tools less often.
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently.
 
 **Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
 
@@ -21,87 +21,11 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 1. Retry the same call **once**.
 2. If it fails again, the memory subsystem is unhealthy for this session — stop trying memory calls and tell the user. Do not waste tokens re-sending the same payload.
-3. Direct-SQL fallback **does not apply** on cloud Free Tier (`db_run_read_only_query` returns `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`). On self-hosted / paid deployments where DB tools are available, inspect memory rows via the multi-tenant schema — tables are namespaced by datapack, not by agent_id. The old `{agent_id}_mem0_collection` per-agent-table layout is gone.
 
 **Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
 
 ---
 
-## RAG pipeline stuck at INIT
-
-**Affects:** `knowledgebase_trigger_index_creation` — the build triggers but never completes.
-
-**Symptoms:**
-- `knowledgebase_check_index_status` returns empty `pipeline_details` and `pipeline_stats`
-- Documents remain at `INIT` status indefinitely
-- Work queue tasks are `IN_PROGRESS` with `lease_expires_at` in the past
-
-**Diagnosis:** Query the work queue directly:
-```
-db_run_read_only_query(scope="read",
-    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
-```
-
-Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashed or hung workers.
-
-**What to do:**
-
-1. Poll status **at most 3 times** with 1-2 minute intervals
-2. If no progress after 3 checks, **stop polling** — the pipeline is stuck
-3. There is **no way to reset or retry stuck tasks via MCP tools**
-4. Creating a new index with a different name (e.g., `_v2`) is a workaround, but if the workers themselves are down, this will also get stuck
-5. Recommend the user check worker logs or restart the pipeline service
-
-**Anti-pattern from real sessions:** Agent created indexes `v1`, `v2`, `v3` — all stuck with the same symptoms. Even making the S3 bucket public didn't help. The issue was worker infrastructure, not permissions.
-
----
-
-## db_run_write_query guardrail error
-
-**Error:** `'dict' object has no attribute 'guardrail_config'`
-
-**Affects:** `db_run_write_query` in some deployments.
-
-**What to do:**
-
-1. Try the call once. If it fails with this specific error, write operations are unavailable in this deployment.
-2. For reads, always use `db_run_read_only_query` (never `db_run_write_query` for SELECT).
-3. Report the issue — it's a server-side bug, not a parameter problem.
-
----
-
-## knowledgebase_add_source_to_index failure
-
-**Error shape:** `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`
-
-You're on cloud Free Tier; the ingestion tools are gated off. There is no retry that will succeed. Point the user at the Meko UI's **Add Knowledge** file-upload flow (Datapack → Actions → Add Knowledge) instead.
-
-**Error shape:** `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`
-
-The `index_name` doesn't exist in this datapack's `dist_rag.vector_indexes` table. Either you're targeting the wrong datapack (check `datapack_id`), or the index hasn't been created yet — call `knowledgebase_trigger_index_creation` first.
-
-**Error shape:** tool returns `"build_triggered"` but `knowledgebase_check_index_status` shows documents stuck at `INIT` for >5 minutes.
-
-Most common cause on self-hosted deployments: the worker can't reach the S3 bucket. `S3BucketCrawler()` uses boto3's default credential chain — check `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / IAM role / `~/.aws/credentials` on the worker host, not on the MCP server. Second cause: the URI isn't `s3://`-prefixed (`aws_source_processor.py` rejects other schemes with `ValueError("Invalid source URI")` async).
-
-**Historical note:** the old `r_index_name` vs `r_index_id` parameter-mismatch bug is fixed on main — the MCP tool now resolves `index_name → index_id` internally via a `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` step. Older docs referencing this bug are stale.
-
----
-
-## 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.
@@ -116,7 +40,7 @@ Fix: always pass a concrete non-empty `agent_id`. For Claude Desktop use `agent_
 
 ### "My 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`: one call returns this user's memories across every agent. If results seem thin, check the `datapack_id`, confirm the write landed, and remember that mem0 extraction can be lossy. `conversation_get` is agent-owned and requires the exact creating `agent_id`; `conversation_list` is not agent-filtered.
 
 ### "I'm seeing rows tagged with legacy agent_id values"
 
@@ -124,32 +48,14 @@ Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, o
 
 ---
 
-## Permission denied on data tables
-
-**Error:** `permission denied for table customer_complaints`
-
-**Why:** The MCP database user may not have read access to all tables, particularly data tables created by the provisioning system within a datapack.
-
-**What to do:**
-
-1. This is a server-side configuration issue — not fixable via MCP tools.
-2. Don't retry. Don't try different query formulations.
-3. Use `db_summarize_database` to see which tables you CAN access.
-4. Report the permission gap to the Meko admin.
-
----
-
 ## Safe-to-retry vs not
 
 | 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 |
-| `db_run_write_query` (INSERT) | **No** | May double-insert rows |
-| `db_run_write_query` (CREATE TABLE) | **No** | "Table already exists" error |
-| `knowledgebase_trigger_index_creation` | **No** | Creates duplicate indexes |
 | `conversation_create` | **No** | Creates duplicate conversations |
 | `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
 | `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

package/assets/skills/meko-select-datapack-desktop/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: meko-select-datapack-desktop
+description: >-
+  Lists the user's Meko datapacks, shows authorization, supports search and
+  pagination, and pins one as the active datapack on Claude Desktop. Triggers
+  when the user says things like "switch datapack", "use the Acme datapack",
+  "list my datapacks", "which datapack am I on", "pin Acme", or any request
+  to change or inspect the active datapack. Persistence is via memory_add
+  (Desktop has no SessionStart hook), so the pin survives across sessions
+  until the user clears it.
+license: MIT
+metadata:
+  author: Meko
+  version: "1.2.0"
+  tags: meko, datapack, selection, project, claude-desktop, desktop
+---
+
+# meko-select-datapack-desktop — Pin a datapack for Claude Desktop
+
+Claude Desktop has no SessionStart hook, so the Claude Code variant's sidecar/hook design doesn't apply here. Instead, the pin is stored as a **memory** with a structured tag, scoped to `agent_id="claude_desktop"` (Desktop's project bucket), and you re-read it on every Desktop turn before issuing Meko MCP tool calls. The pin outlives a single Desktop conversation — it sticks until the user explicitly clears it. Same project-scoped semantic as the Claude Code variant; different mechanism.
+
+## How persistence works (Desktop)
+
+A single memory under `agent_id="claude_desktop"` carries the pin:
+
+```
+text:        "meko_active_datapack=<uuid> name=<name> selected_at=<iso8601>"
+metadata:    { "type": "active-datapack-pin" }
+```
+
+You discover it by calling `memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)` at the start of any turn that's about to make a Meko MCP write. If you find a pin, pass `datapack_id="<uuid>"` to every Meko call that accepts it. If you don't find one, fall back to the server default (omit the parameter).
+
+## When to invoke this skill
+
+Trigger immediately on any of these signals:
+
+- User says "switch datapack", "change datapack", "use datapack X", "select datapack", "pick a datapack".
+- User says "list my datapacks", "what datapacks do I have", "show me my datapacks".
+- User says "which datapack am I on", "which datapack is active", "what's pinned".
+- User says "clear datapack", "unpin datapack", "stop using <name>".
+- The first Meko MCP write of a turn AND `memory_search` for `meko_active_datapack` returned no result AND the user has more than one datapack — proactively offer to pin one.
+
+## On every Meko-touching turn (not just when this skill triggers)
+
+Before issuing a Meko MCP write tool call (memory_add, conversation_add_message, artifact_put, etc.), if you don't already know the active pin from this turn's earlier work:
+
+```
+memory_search(
+              query="meko_active_datapack",
+              agent_id="claude_desktop",
+              conversation_id="<this conversation's id>",
+              limit=1)
+```
+
+Parse the result. If a pin row is present, extract the UUID from the text body (after `meko_active_datapack=`) and pass it as `datapack_id` to every Meko MCP call this turn. If not, omit `datapack_id` and let the server resolve the default.
+
+This is once per turn, not once per call. Cache within the turn.
+
+## The flow
+
+### 1. List
+
+Use a **temporary** conversation for browsing only. Call
+`conversation_create(agent_id="claude_desktop", title="Claude
+Desktop datapack selection")` and use its returned ID for the read-only
+`datapack_list` below and for the pin `memory_add`/`memory_update` in step 4.
+
+**Do not reuse this conversation for later capture.** It lives in whatever
+datapack was active when it was created (typically the default), and a
+conversation cannot move between datapacks. Once a datapack is pinned, capture
+must flow through a *new* conversation created in the selected datapack — see
+step 5.
+
+```
+datapack_list(conversation_id="<this conversation's id>")
+```
+
+The response is an array; the fields you'll use are `datapack_id`,
+`datapack_name`, `created_at`, `account_id`, and `grant`.
+
+`grant` is the caller's actual authorization on the datapack — one of
+`"owner"`, `"maintainer"`, `"contributor"`, `"viewer"`. Display it verbatim in
+the Role column. Do not hardcode "Owner", do not invent or normalize the value
+(render `"maintainer"` as `maintainer`, not `Maintainer`). The deployed
+response is the source of truth — see `references/role-display-future.md` for
+the taxonomy.
+
+If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>')` to make one, or visit the Meko Cloud console."* Stop here.
+
+If the response has exactly **one** entry, **auto-select it**. Print: *"Only one datapack: `<name>`. Auto-selecting. Run `meko-select-datapack-desktop` again with `clear` to unset."* Skip the table; jump to step 4 (persist) and step 5 (confirm).
+
+### 2. Render the table
+
+For 2+ datapacks, render a numbered table. **Page size 10.** Default sort: `created_at DESC` (newest first).
+
+```
+Your datapacks (showing 1-10 of 14):
+
+#   Name                                   Role          Created       Status     Active?
+1   meko-local-setup                       owner         2026-04-30    ready       ←  (pinned)
+2   meko_default_datapack                  owner         2026-04-30    ready
+3   team-onboarding                        maintainer    2026-04-08    ready
+4   q2-roadmap                             viewer         2026-03-22    ready
+…
+
+Reply with: a number (1-10) to pin · a substring to search · `next` / `prev` to page
+            · `clear` to unset · `cancel` to leave the current pin alone
+```
+
+The **Role** column shows each datapack's `grant` value verbatim (`owner`,
+`maintainer`, `contributor`, `viewer`). Never hardcode "Owner" — shared
+datapacks legitimately carry other grants, and misreporting them (e.g. showing
+a `maintainer` grant as "Owner") misleads the user about their own access.
+
+Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any).
+
+### 3. Parse the user's reply
+
+- **Integer in range** → that row is the choice.
+- **Substring** → re-render filtered. If it narrows to one row, that's the choice.
+- **`next` / `prev`** → re-render next/previous page.
+- **`cancel`** → leave any existing pin in place; print *"Cancelled. Active datapack unchanged."* Stop.
+- **`clear` / `none` / `unpin`** → see step 4's clear path.
+- **Unrecognized** → re-prompt with the legend.
+
+### 4. Persist
+
+**On first pin (no existing pin memory):**
+
+```
+memory_add(
+           text="meko_active_datapack=<uuid> name=<name> selected_at=<iso8601>",
+           agent_id="claude_desktop",
+           conversation_id="<this conversation's id>",
+           metadata='{"type":"active-datapack-pin"}')
+```
+
+Verify the write with `memory_search` (the standard Meko verify-after-write rule from `meko-mcp-tools-desktop`). Capture the returned memory `id`.
+
+**On switch (existing pin memory found):**
+
+```
+memory_update(
+              memory_id="<existing pin id>",
+              text="meko_active_datapack=<new uuid> name=<new name> selected_at=<iso8601>",
+              agent_id="claude_desktop",
+              conversation_id="<this conversation's id>")
+```
+
+Always update — never `memory_add` a second pin. Two pin memories will produce ambiguous reads.
+
+**On clear:**
+
+```
+memory_delete_by_id(
+                    memory_id="<existing pin id>",
+                    agent_id="claude_desktop",
+                    conversation_id="<this conversation's id>")
+```
+
+If `memory_search` returned no pin, there's nothing to delete — print *"No pin was set; nothing to clear."* and stop.
+
+**Conversation transition after a clear (same rule as a switch).** The pin memory is now gone, but the session's current conversation still physically lives in the datapack that was pinned when it was created — a conversation cannot move to the default. You must pick exactly one of these; do not mix them:
+
+- **Option A — keep capturing to the current conversation this session.** It stays in its original (now-unpinned) datapack, so you must keep passing that **same old `datapack_id`** on its `conversation_add_message` calls — do NOT switch it to the default (that would fail). The clear only affects *new* sessions. Disclose: *"Pin cleared. This chat keeps saving to `<old datapack name>`; new chats will use the default datapack."*
+- **Option B — start default-datapack capture immediately.** Create a **new** conversation with no `datapack_id` (`conversation_create(agent_id="claude_desktop")`) and post all subsequent turns there. Stop posting to the old conversation. Disclose: *"Pin cleared. Started a new chat context saving to the default datapack."*
+
+Default to Option A (least disruptive) unless the user wants the switch to take effect right now. Either way, never send `datapack_id=default` to the pre-existing pinned conversation.
+
+### 5. Confirm
+
+```
+Pinned datapack `<name>` (`<uuid>`) for Claude Desktop.
+
+This is stored as a memory under agent_id="claude_desktop". It will persist
+across sessions until you run this skill again with `clear` (or `switch` to
+a different datapack).
+
+I'll read this pin via `memory_search` before each Meko MCP write so the
+right `datapack_id` flows through automatically.
+```
+
+**Then start a fresh conversation for capture in the selected datapack.** The
+temporary selection conversation from step 1 belongs to the datapack that was
+active when it was created and cannot be moved. For subsequent capture this
+session, call `conversation_create(agent_id="claude_desktop",
+datapack_id="<the newly pinned uuid>", title="<topic>")` and post turns
+(`conversation_add_message`) to *that* conversation with the same
+`datapack_id`. Do not keep posting to the selection conversation — doing so
+would split capture across the old and new datapacks or fail outright.
+
+## Edge cases
+
+- **Multiple pin memories somehow exist** — the user (or a buggy earlier run) created duplicates. Use the most recent (highest `selected_at`); offer to delete the others.
+- **The pinned datapack no longer exists on the server** — the next Meko MCP call will fail with a not-found error. Re-run the skill to pick a new one or `clear` the stale pin.
+- **memory_search times out or fails** — fall back to the server default (omit `datapack_id`) and tell the user *"Couldn't read the active-datapack pin. Using server default for this call."* Don't guess a UUID.
+- **User explicitly overrides for a single call** — pass the user's `datapack_id` for that one call. Do NOT update the pin memory.
+
+## Critical: do NOT use other persistence mechanisms
+
+Don't write to local files, don't use environment variables, don't ask the user to paste the UUID into every prompt. A single tagged memory is the entire mechanism. Anything else creates drift between what you think is pinned and what `memory_search` will report.
+
+## Reference sections
+
+| File | What it covers |
+|------|---------------|
+| `references/cookbook.md` | Sample list / search / select / clear transcripts on Desktop |
+| `references/troubleshooting.md` | Pin not recalled, duplicate pins, stale UUID recovery |

package/assets/skills/meko-select-datapack-desktop/references/cookbook.md

@@ -0,0 +1,121 @@
+# Cookbook — meko-select-datapack-desktop
+
+Concrete transcripts of the four flows the skill supports on Claude Desktop.
+
+## Flow 1 — First pin (no existing pin memory)
+
+**User:** `pin prod-research as my active datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[empty]
+
+> datapack_list()
+[14 entries returned, filtering by "prod-research"]
+
+One match: `prod-research`. Pinning.
+
+> memory_add(
+             text="meko_active_datapack=8b1c…f4a2 name=prod-research selected_at=2026-05-25T18:42:00Z",
+             agent_id="claude_desktop",
+             conversation_id="<conv-id>",
+             metadata='{"type":"active-datapack-pin"}')
+[returns id=mem_abc123]
+
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[verifies the row exists]
+
+Pinned datapack `prod-research` (`8b1c…f4a2`) for Claude Desktop.
+
+Stored as a memory under agent_id="claude_desktop"; persists across sessions
+until you run this skill again with `clear` or `switch`.
+
+I'll read this pin via memory_search before each Meko MCP write so the right
+datapack_id flows through automatically.
+```
+
+## Flow 2 — Switch (pin memory already exists)
+
+**User:** `switch to the q2-roadmap-deck datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
+
+> datapack_list()
+[14 entries returned, filtering by "q2-roadmap-deck"]
+
+One match: `q2-roadmap-deck`. Switching pin.
+
+> memory_update(
+                memory_id="mem_abc123",
+                text="meko_active_datapack=4c2e…a991 name=q2-roadmap-deck selected_at=2026-05-25T19:05:00Z",
+                agent_id="claude_desktop",
+                conversation_id="<conv-id>")
+
+Switched pin from `prod-research` to `q2-roadmap-deck` (`4c2e…a991`).
+```
+
+The `memory_update` is critical here — using `memory_add` again would create a duplicate pin memory.
+
+## Flow 3 — Single-datapack auto-select
+
+**User:** (first Meko write attempt, no pin yet)
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[empty]
+
+> datapack_list()
+[1 entry returned]
+
+Only one datapack: `meko-local-setup`. Auto-selecting.
+
+> memory_add(
+             text="meko_active_datapack=a17d…cc91 name=meko-local-setup selected_at=…",
+             agent_id="claude_desktop",
+             conversation_id="<conv-id>",
+             metadata='{"type":"active-datapack-pin"}')
+
+Pinned datapack `meko-local-setup` (`a17d…cc91`). Run this skill again with
+`clear` to unset.
+```
+
+## Flow 4 — Clear
+
+**User:** `unpin datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[returns id=mem_abc123]
+
+> memory_delete_by_id(
+                      memory_id="mem_abc123",
+                      agent_id="claude_desktop",
+                      conversation_id="<conv-id>")
+
+Pin cleared. Subsequent Meko MCP calls will use the server default.
+```
+
+If `memory_search` returned empty: *"No pin was set; nothing to clear."*
+
+## Flow 5 — Read-the-pin pattern (every Meko-touching turn)
+
+This isn't a user-triggered flow — it's the per-turn lookup the skill teaches you to do silently before any Meko MCP write:
+
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop",
+                conversation_id="<conv-id>", limit=1)
+[returns text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
+
+# Extract UUID after "meko_active_datapack=" → 8b1c…f4a2
+
+> memory_add(text="…", datapack_id="8b1c…f4a2",
+             agent_id="claude_desktop", conversation_id="<conv-id>")
+```
+
+Cache the UUID for the rest of the turn — don't call `memory_search` once per Meko tool call.

package/assets/skills/meko-select-datapack-desktop/references/role-display-future.md

@@ -0,0 +1,41 @@
+# Role display — current state
+
+## Today: render `grant` verbatim
+
+The deployed Meko `GET /datapacks` response includes a `grant` field on every datapack. Possible values (per maintainer guidance, 2026-05-26):
+
+- `"owner"` — datapacks the caller created.
+- `"maintainer"` — write access to a shared datapack including memories AND collective learnings/knowledge.
+- `"contributor"` — write access to a shared datapack: can generate own memories. (Cannot promote / publish collective learnings — that's the maintainer's job.)
+- `"viewer"` — read-only on a shared datapack.
+
+Use the field directly in the **Role** column:
+
+```
+#   Name                  Role          Created       Active?
+1   prod-research         owner         2026-04-12    ←  (pinned)
+2   team-onboarding       contributor   2026-04-08
+3   q2-roadmap            viewer        2026-03-22
+```
+
+Do not invent values, do not normalize the casing, do not display `"Owner"` if the field says `"owner"`. The deployed schema is the source of truth.
+
+Note that the upstream Go source (the `Datapack` struct in `api_server/internal/models/models.go` of the `meko` API-server repo) does NOT declare `grant` — the deployed server enriches the response beyond what the public Go code lists. Don't rely on the public struct for the wire schema; trust the actual response.
+
+## Other fields the live response includes
+
+Beyond the columns the skill renders by default, `datapack_list` returns counts that may be useful in some flows:
+
+- `memory_count` — total memories the caller has under this datapack (per `(user_id, agent_id)` scoping).
+- `knowledge_count` — knowledge-base entries on the datapack.
+- `learnings_count` — promoted-to-shared memories on the datapack.
+
+These aren't in the spec column set. Don't add them silently. If the user asks for counts, render them on request — and read the numbers from the live response, never invent them.
+
+## Sharing UI vs API state
+
+The Cloud console "Share <datapack>" page (`meko_ui/src/features/datapacks/pages/DatapackSharePage.tsx`) shows interactive controls with "Coming Soon" overlays on a few specific actions (e.g. invite-by-email link sharing, transfer-ownership). Those overlays mean *those specific UI affordances* aren't shipped — NOT that the underlying `grant`/sharing model is absent. Contributor/maintainer/viewer grants are functional in the data layer today; only the user-facing self-serve invite flow is gated.
+
+## Why the skill ships without Mine / Shared / All filter tabs
+
+The tagged pin memory (re-read via `memory_search` before each Meko write) delivers the user's actual ask ("don't make me remember a UUID"). Filter tabs are useful when the response is genuinely mixed-grant; for users with only owner-grant rows they're decorative. We add tabs when there's evidence users with mixed-grant responses want them.

package/assets/skills/meko-select-datapack-desktop/references/troubleshooting.md

@@ -0,0 +1,66 @@
+# Troubleshooting — meko-select-datapack-desktop
+
+## Symptom: I pinned a datapack but the next Meko call doesn't use it
+
+**Likely causes**
+
+1. **You forgot the per-turn `memory_search`.** Desktop has no SessionStart hook, so the skill teaches you to read the pin yourself at the top of every Meko-touching turn. If you skip that lookup, you'll send Meko calls with no `datapack_id` and the server resolves the default. Add the lookup; cache the result for the rest of the turn.
+2. **You used `agent_id="meko_agent"` for the pin write or read.** The pin lives under `agent_id="claude_desktop"`, exclusively. Cross-project facts go under `meko_agent`, but the pin is a Desktop-specific preference and should stay scoped.
+3. **The pin write failed silently.** Always verify-after-write — call `memory_search` for `meko_active_datapack` immediately after `memory_add` and confirm the row appears. If it doesn't, the write was lost (latency, server error, wrong scope) and the pin doesn't actually exist.
+
+## Symptom: `memory_search` returns multiple pin memories
+
+You (or an earlier run) created duplicates by using `memory_add` instead of `memory_update` on a switch. Resolution:
+
+1. Pick the most recent (highest `selected_at` in the text body).
+2. `memory_delete_by_id` the others.
+3. From now on, switch via `memory_update` on the surviving id — never `memory_add`.
+
+The cookbook's Flow 2 demonstrates the correct switch path.
+
+## Symptom: A pinned datapack returns "not found" when used
+
+The pin became stale — the datapack was deleted in another client. Tell the user:
+
+```
+The pinned datapack `<name>` (`<id>`) no longer exists on the server.
+Run `meko-select-datapack-desktop` to pick a fresh one, or `clear` to unpin.
+```
+
+Then either re-run the skill or delete the pin memory. Do not silently fall back to the default — the user explicitly asked for a specific datapack.
+
+## Symptom: Substring search matches multiple datapacks
+
+Never auto-pick when there's ambiguity. Re-render just the matching rows numbered from 1, and ask the user to pick a number from the filtered subset. Same as the Claude Code variant.
+
+## Symptom: `datapack_list` returns an empty array
+
+The user has zero datapacks. Print:
+
+```
+You don't have any datapacks yet. Create one with:
+
+  datapack_create(name="<your-datapack-name>")
+
+Or visit the Meko Cloud console (Datapacks → New datapack).
+```
+
+Stop. Don't `memory_add` an empty pin.
+
+## Symptom: User typed `cancel` after the table rendered
+
+Leave the existing pin memory alone. Print:
+
+```
+Cancelled. Active datapack unchanged.
+```
+
+Do NOT delete on `cancel` — that's `clear`'s job.
+
+## Symptom: `memory_search` for the pin times out
+
+Memory tools are slow on prod (search 2-6s observed). If the search exceeds a reasonable budget, fall back to the server default for that single call and tell the user *"Couldn't read the active-datapack pin within budget — using server default for this Meko call."* Don't guess a UUID; don't silently retry indefinitely.
+
+## Symptom: The pin survived a `claude_desktop` profile reset / app reinstall
+
+That's expected — the pin is a server-side memory, not local state. To explicitly forget across reinstalls, run the skill with `clear` BEFORE wiping local state, or `memory_delete_by_id` the pin row directly.