@zibby/skills 0.2.23 → 0.2.24

package/docs/skills/lark.md

@@ -1,85 +0,0 @@
----
-sidebar_position: 3
-title: Lark
----
-
-# Lark skill
-
-Send messages, reply in threads, list chats, and read chat history on Lark / Feishu.
-
-- **ID:** `lark`
-- **MCP server:** `lark` (tools exposed as `mcp__lark__*`)
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `lark_send_message` | Send a text message. `receive_id` accepts chat_id (`oc_*`), open_id (`ou_*`), union_id (`on_*`), or email — the receive id type is inferred from the prefix |
-| `lark_reply` | Reply to a specific `message_id` (creates a thread) |
-| `lark_list_chats` | List chats the bot is a member of |
-| `lark_get_chat_history` | Fetch recent messages in a `chat_id` (newest first), default `page_size: 20` |
-
-## Setup
-
-Lark bots authenticate with App ID + App Secret. The bot needs `im:message` and `im:chat:readonly` (or wider) permissions, and must be added to any chat it should read or post into.
-
-1. Create a custom app at [open.feishu.cn](https://open.feishu.cn/) (or Lark's open platform).
-2. Enable **Bot** capability and grant the IM permissions above.
-3. In the Zibby dashboard, **Settings → Integrations → Connect Lark**, paste your `App ID` and `App Secret`.
-4. The backend exchanges them for a `tenant_access_token` on demand and caches it (TTL ~100 min, just under Lark's 2h).
-
-For self-hosted Lark deployments, set `host` on the integration config; the default is the standard Feishu host.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class IncidentNotifier extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('notify', {
-      agent: 'claude',
-      skills: [SKILLS.LARK],
-      prompt: (state) => `Post a summary of incident ${state.incidentId} to the on-call
-      chat (chat_id: oc_xxxxx). If a previous thread exists in state.threadMessageId,
-      use lark_reply instead of lark_send_message.`,
-    });
-    return graph;
-  }
-}
-```
-
-## Output example
-
-`lark_send_message`:
-
-```json
-{ "ok": true, "message_id": "om_d2e6e3a1f24c9d3..." }
-```
-
-`lark_get_chat_history`:
-
-```json
-{
-  "messages": [
-    {
-      "message_id": "om_abc...",
-      "sender_id": "ou_xyz...",
-      "sender_type": "user",
-      "msg_type": "text",
-      "content": "{\"text\":\"deploy is green\"}",
-      "create_time": "1715839203000"
-    }
-  ]
-}
-```
-
-## Implementation notes
-
-Spawns `packages/skills/bin/mcp-lark.mjs`. Like Sentry, auth is fetched through the backend's `resolveIntegrationToken('lark')` endpoint and the tenant access token is cached in-process.
-
-`receive_id_type` is required by Lark and is inferred from the id prefix (`oc_` → chat_id, `ou_` → open_id, `on_` → union_id, `cli_` → app_id, anything with `@` → email). Callers pass whichever id they have.
-
-The MCP server uses `alwaysLoad: true` so tools land in the system prompt — same fix as Sentry. The `assistant` agent strategy can call the in-process `handleToolCall` for OpenAI Assistant API runs.

package/docs/skills/memory.md

@@ -1,92 +0,0 @@
----
-sidebar_position: 7
-title: Memory (test)
----
-
-# Memory skill
-
-Query the test memory database — prior test runs, known selectors with stability metrics, page models, navigation transitions — and save insights for future runs. Dolt-backed (git-style versioned SQL).
-
-- **ID:** `memory`
-- **MCP server:** `memory` (tools exposed as `mcp__memory__*`)
-- **Underlying server:** `@zibby/ui-memory/mcp-server`
-
-For persistent **chat** memory (not test history) see [Chat memory](./chat-memory.md).
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `memory_get_test_history` | Recent test runs with pass/fail + timing. Filter by `specPath` substring |
-| `memory_get_selectors` | Known selectors for a page with stability metrics. Filter by `pageUrl` substring |
-| `memory_get_page_model` | Page structure — elements, roles, selectors. Filter by `url` substring |
-| `memory_get_navigation` | Known page-to-page transitions. Filter by `fromUrl` substring |
-| `memory_save_insight` | Save an observation. Categories: `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |
-
-## Setup
-
-Requires [Dolt](https://docs.dolthub.com/introduction/installation) and an initialized memory database in your workspace.
-
-```bash
-# macOS
-brew install dolt
-# then, in your agent workspace:
-zibby init --mem
-```
-
-`zibby init --mem` creates `.zibby/memory/` (a Dolt repo). The memory tools only activate after at least one completed test run — until then the skill returns `null` from `resolve()` and is skipped.
-
-Override the bin location for development with `MCP_MEMORY_PATH`.
-
-See [Tests → Memory](../tests/memory.md) for the full memory lifecycle.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class FlakyTestInvestigator extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('investigate', {
-      agent: 'claude',
-      skills: [SKILLS.MEMORY, SKILLS.BROWSER],
-      prompt: (state) => `Before running the test:
-      1. Call memory_get_test_history with specPath="${state.specPath}" — review prior failures.
-      2. Call memory_get_selectors with pageUrl matching the target page.
-      Then run the test using the browser tools. When done, save a memory_save_insight
-      capturing any selectors that worked when an older one failed.`,
-    });
-    return graph;
-  }
-}
-```
-
-The skill's prompt fragment auto-instructs the agent to consult prior runs and call `memory_save_insight` mid-run when a fallback selector works, and at minimum once at end-of-run.
-
-## Output example
-
-`memory_get_selectors`:
-
-```json
-{
-  "selectors": [
-    {
-      "pageUrl": "/dashboard",
-      "role": "button",
-      "stableId": "e7a1",
-      "selector": "[data-testid='new-project']",
-      "successCount": 42,
-      "failureCount": 1,
-      "lastSeen": "2026-05-15T14:00:00Z"
-    }
-  ]
-}
-```
-
-## Implementation notes
-
-`resolve({ workspace })` resolves `@zibby/ui-memory/mcp-server` and spawns it with `--db-path .zibby/memory`. Before spawning it sanity-checks Dolt is on the PATH and the database has at least one `test_runs` row; if not, returns `null` (skill skipped silently) or throws a clear "install Dolt" error.
-
-The skill also exports `middleware()` that loads `createMemoryMiddleware()` from `@zibby/ui-memory` when the package is present — this runs before/after each node to inject test history into the prompt and persist new insights.

package/docs/skills/sentry.md

@@ -1,80 +0,0 @@
----
-sidebar_position: 2
-title: Sentry
----
-
-# Sentry skill
-
-Read-only access to a connected Sentry organization — list projects, list issues, fetch issue details.
-
-- **ID:** `sentry`
-- **MCP server:** `sentry` (tools exposed as `mcp__sentry__*`)
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `sentry_list_projects` | List projects in the connected organization (slug, name, platform) |
-| `sentry_list_issues` | List issues. Supports `project`, `query` (Sentry search syntax, default `is:unresolved`), `sort` (`date`/`new`/`priority`/`freq`/`user`), `limit` |
-| `sentry_get_issue` | Detailed info for one issue by `issueId` — title, culprit, counts, first/last seen, level, status |
-
-## Setup
-
-Sentry uses OAuth 2.0 with PKCE (public client — no client secret).
-
-1. In the Zibby dashboard, go to **Settings → Integrations**.
-2. Click **Connect Sentry**.
-3. Approve the organization in the Sentry consent screen.
-4. You're redirected back; the access token + organization slug are stored encrypted on the project.
-
-The backend (`/integrations/sentry/connect` and `/integrations/sentry/callback`) handles the PKCE exchange. Tokens auto-refresh on use; if refresh fails, click **Reconnect** in the same settings panel.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class SentryTriage extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('triage', {
-      agent: 'claude',
-      skills: [SKILLS.SENTRY],
-      prompt: () => `Use sentry_list_issues with query "is:unresolved level:error" to find the
-      top 10 unresolved errors. Then call sentry_get_issue for the highest-frequency one
-      and summarize what's failing.`,
-    });
-    return graph;
-  }
-}
-```
-
-## Output example
-
-`sentry_list_issues`:
-
-```json
-{
-  "issues": [
-    {
-      "id": "5712345678",
-      "title": "TypeError: Cannot read properties of undefined (reading 'id')",
-      "culprit": "src/handlers/checkout.ts in handleSubmit",
-      "count": 1247,
-      "firstSeen": "2026-05-01T14:22:10Z",
-      "lastSeen": "2026-05-16T09:11:03Z",
-      "level": "error",
-      "status": "unresolved"
-    }
-  ]
-}
-```
-
-## Implementation notes
-
-Spawns `packages/skills/bin/mcp-sentry.mjs` via `node`. Auth is delegated: the bin calls the Zibby backend's `resolveIntegrationToken('sentry')` endpoint using `PROJECT_API_TOKEN` + `PROGRESS_API_URL` (passed through from the Fargate environment).
-
-`alwaysLoad: true` is set on the MCP server config so Sentry tools land in the initial system prompt instead of behind the Claude SDK's lazy `ToolSearch` (which misses MCP-served tools by keyword).
-
-The skill also implements `handleToolCall` for the `assistant` agent strategy (OpenAI Assistant API), which doesn't speak MCP — same Sentry API, dispatched in-process.

package/docs/skills/slack.md

@@ -1,89 +0,0 @@
----
-sidebar_position: 5
-title: Slack
----
-
-# Slack skill
-
-Read/write a Slack workspace — list channels, post messages, reply in threads, react, read history, list users.
-
-- **ID:** `slack`
-- **MCP server:** `slack` (tools exposed as `mcp__slack__*`)
-- **Underlying server:** `npx @modelcontextprotocol/server-slack@latest`
-
-## Tools provided
-
-| Tool | What it does |
-|---|---|
-| `slack_list_channels` | List public channels (id, name, topic) |
-| `slack_post_message` | Post a top-level message. Requires `channel` and `text` |
-| `slack_reply_to_thread` | Post a reply with `thread_ts` |
-| `slack_add_reaction` | Add an emoji reaction to a message |
-| `slack_get_channel_history` | Recent messages in a channel (`limit` default 20) |
-| `slack_get_thread_replies` | All replies in a thread |
-| `slack_get_users` | Workspace members (excludes bots and deleted) |
-| `slack_get_user_profile` | Detailed profile for a `user_id` |
-
-## Setup
-
-Slack uses a bot token + workspace team id.
-
-1. Create (or reuse) a Slack app at [api.slack.com/apps](https://api.slack.com/apps).
-2. Add Bot Token Scopes — the full set this skill's tools need:
-   `chat:write`, `channels:read`, `channels:history`, `groups:read`, `groups:history`,
-   `reactions:write`, `users:read`, `users:read.email`, `users.profile:read`, `usergroups:read`.
-   (`users:read.email` backs `slack_find_user_by_email`; `usergroups:read` backs
-   `slack_list_usergroups` / `slack_get_usergroup_members` — omit either and those
-   tools fail with `missing_scope`.)
-3. Install the app to your workspace; copy the **Bot User OAuth Token** (`xoxb-…`) and **Team ID**.
-4. Set them on the agent's env (locally) or via **Cloud → Env vars**:
-
-```bash
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_TEAM_ID=T01234567
-```
-
-The skill declares `envKeys: ['SLACK_BOT_TOKEN', 'SLACK_TEAM_ID']` and the official `@modelcontextprotocol/server-slack` consumes them.
-
-## Use in an agent
-
-```js
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { SKILLS } from '@zibby/skills';
-
-export class DeployAnnouncer extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-    graph.addNode('announce', {
-      agent: 'claude',
-      skills: [SKILLS.SLACK],
-      prompt: (state) => `Post to #deploys: "v${state.version} deployed to ${state.env}".
-      If state.threadTs is set, use slack_reply_to_thread instead of slack_post_message.`,
-    });
-    return graph;
-  }
-}
-```
-
-## Output example
-
-`slack_post_message`:
-
-```json
-{ "ok": true, "ts": "1715839203.000400", "channel": "C0123ABC" }
-```
-
-`slack_list_channels`:
-
-```json
-{
-  "channels": [
-    { "id": "C0123ABC", "name": "deploys", "topic": "Release announcements" },
-    { "id": "C0456DEF", "name": "incidents", "topic": "P0/P1 coordination" }
-  ]
-}
-```
-
-## Implementation notes
-
-`resolve()` spawns the official `@modelcontextprotocol/server-slack` via `npx` and passes through `SLACK_BOT_TOKEN` + `SLACK_TEAM_ID`. The in-process `handleToolCall` (used by the `assistant` strategy) talks directly to `https://slack.com/api/<method>` with the same bot token resolved via the backend's integration token service.

package/docs/tests/memory.md

@@ -1,131 +0,0 @@
----
-sidebar_position: 1
-title: Test memory
----
-
-# Test memory
-
-Zibby's `zibby test` runner has a local-first **memory database** at `.zibby/memory/.dolt/` that learns from every run — selectors that worked, page-element fingerprints, navigation transitions, timing quirks, recorded insights. Cross-spec via per-domain keying, optionally synced across the team.
-
-The package powering this is [`@zibby/ui-memory`](../packages/ui-memory) — read that for the schema and SDK. This page is a **usage walkthrough**.
-
-## What's in the box
-
-- **Local DB** — `.zibby/memory/.dolt/` (Dolt SQL, version-controlled like git)
-- **5 MCP tools** auto-exposed when `zibby test` runs and the DB exists
-- **Auto-pull / auto-push** before and after each test run when a remote is configured
-- **CLI** — `zibby memory <verb>` for stats, cost, compact, reset, pull, push, remote management
-
-## Why per-domain keying matters
-
-Memory is keyed on the **domain**, not the spec file. Selectors learned by `login.txt` for `myapp.com/login` are immediately available when `checkout.txt` lands on `myapp.com/checkout` and asks "what's a stable selector for the email field on this site?"
-
-In practice this means a multi-spec suite gets sharper with every run — the agent's Nth run on a domain is meaningfully cheaper and more reliable than its first.
-
-## The 5 MCP tools
-
-When `zibby test` runs and `.zibby/memory/.dolt/` exists, the agent gets these auto-exposed:
-
-| Tool | What it does |
-|---|---|
-| `memory_get_test_history` | Recent runs (filter by spec-path substring) — pass/fail and timing |
-| `memory_get_selectors` | Known selectors per page with success/fail counts |
-| `memory_get_page_model` | Page elements (URL, ARIA role, accessible name, best-known selector) |
-| `memory_get_navigation` | Known transitions (from URL → to URL via what trigger) |
-| `memory_save_insight` | Save an observation: `selector_tip | timing | navigation | workaround | flaky | general` |
-
-> **The agent must call `memory_save_insight` at least once per run.** It's required by the memory skill's prompt fragment. Without insights, only the structural data (selectors / runs) compounds; insights are how the system learns "the site shows a banner on Tuesdays" or "this button needs a 200ms wait after focus".
-
-## CLI commands
-
-```bash
-zibby memory init               # initialize (auto-runs on first `zibby test -m`)
-zibby memory stats              # row counts, last commit, per-spec breakdown
-zibby memory cost               # real LLM token spend per spec / per domain (input/output/cache)
-zibby memory compact            # prune old runs + Dolt GC (--max-runs 50, --max-age 90d)
-zibby memory reset -f           # wipe the DB (destructive — confirm)
-```
-
-`compact` is the maintenance lever once the DB grows. `cost` is the most-asked-after view — it answers "which spec is the expensive one?" with real numbers.
-
-## Team sync
-
-Memory is local-first by default. Opt into a shared remote so teammates' learnings flow back to you:
-
-```bash
-# Option A: bring your own bucket
-zibby memory remote add aws://my-bucket/team/proj/main      # S3
-zibby memory remote add gs://bucket/team/proj/main          # GCS
-zibby memory remote add https://www.dolthub.com/repositories/<owner>/<repo>
-zibby memory remote add file:///abs/path/to/local-shared    # filesystem
-
-# Option B: Zibby-managed S3 (signed-in users only)
-zibby memory remote use --hosted
-
-# Inspect / disconnect
-zibby memory remote info
-zibby memory remote remove [name]   # default: origin
-```
-
-Once a remote is configured:
-
-- `zibby test` auto-pulls before each run
-- `zibby test` auto-pushes after each **passing** run (failing runs don't pollute team memory)
-- `zibby memory pull` / `zibby memory push` for manual override
-
-### Auto-wire teammates with `memorySync.remote`
-
-Drop this into `.zibby.config.mjs` and commit it:
-
-```js
-export default {
-  agent: { claude: { model: 'auto' } },
-  memorySync: {
-    remote: 'hosted',                       // or 'aws://my-bucket/team/proj/main' or null
-  },
-};
-```
-
-Now when a teammate clones the repo and runs `zibby init`, the CLI reads `memorySync.remote` and auto-configures the matching remote. For `'hosted'`, init prompts for `zibby login` if they're not signed in but never blocks the init itself.
-
-### Hosted vs BYO at a glance
-
-| | Hosted (`--hosted`) | BYO |
-|---|---|---|
-| Setup time | One command | Provision bucket + IAM (+ KMS if you want) |
-| Where data lives | Zibby-managed AWS account | Your account |
-| Access | Anyone with Zibby project access | Whoever your IAM grants |
-| Compliance / data residency | Limited regions | Wherever you want |
-| Cost | Included in plan | Your S3 bill |
-
-If you have any data-residency requirement or a regulated workload, prefer BYO. Otherwise hosted is the path of least resistance.
-
-## Run-level controls
-
-`zibby test` exposes one memory-relevant flag:
-
-```bash
-zibby test test-specs/login.txt -m            # enable test memory (auto-init if needed)
-zibby test test-specs/login.txt --no-sync     # don't push to cloud (does not affect memory remote)
-```
-
-Memory is independent of the cloud-results sync (`--sync` / `--no-sync` controls run upload to the Zibby dashboard; memory sync is its own remote).
-
-## Inspecting the DB by hand
-
-It's just Dolt:
-
-```bash
-cd .zibby/memory
-dolt log
-dolt sql -q "SELECT spec_path, passed, duration_ms FROM test_runs ORDER BY created_at DESC LIMIT 20"
-dolt diff HEAD~1 HEAD
-```
-
-Branching works too — `dolt branch experiment` to try out a memory mutation in isolation.
-
-## See also
-
-- [`@zibby/ui-memory` package](../packages/ui-memory) — schema, SDK, middleware
-- [`zibby test` recipe](../recipes/test) — the primary consumer
-- [CLI reference: memory](../cli-reference#memory) — full command list