zilmate 1.7.8 → 1.8.0

package/.agents/skills/supermemory-cli/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: supermemory-cli
+description: Use the Supermemory CLI to programmatically manage memories, documents, profiles, tags, connectors, keys, and teams from the terminal. Covers all commands, flags, and usage patterns.
+---
+
+The Supermemory CLI is the complete interface to Supermemory from the terminal. It lets you add memories, search, manage documents, configure projects, connect external data sources, and administer teams — all programmatically.
+
+## Installation & Auth
+
+```bash
+# Install globally
+npm install -g @supermemory/cli
+
+# Authenticate (opens browser OAuth flow)
+supermemory login
+
+# Or use an API key directly
+supermemory login --api-key sm_abc_xxx
+
+# Check auth status
+supermemory whoami
+```
+
+## Configuration
+
+The CLI supports three config scopes:
+
+| Scope | File | Use Case |
+|-------|------|----------|
+| `project` | `.supermemory/config.json` (gitignored) | Per-machine secrets, API keys |
+| `team` | `.supermemory/team.json` (committed) | Shared tag, team-wide defaults |
+| `global` | `~/.config/supermemory/config.json` | All projects on this machine |
+
+```bash
+# Interactive setup wizard
+supermemory init
+
+# Non-interactive
+supermemory init --scope project --tag my-bot
+supermemory init --scope team --tag shared-project
+supermemory init --scope global --output json
+
+# View/set config values
+supermemory config
+supermemory config set tag my-project
+supermemory config set verbose true
+supermemory config get tag
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SUPERMEMORY_API_KEY` | API key for authentication |
+| `SUPERMEMORY_TAG` | Override default container tag |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Force JSON output (machine-readable) |
+| `--tag` | Override default container tag for this command |
+| `--help` | Show help for any command |
+
+---
+
+## Core Commands
+
+### `add` — Ingest content
+
+Ingest text, files, or URLs and extract memories into a container tag.
+
+```bash
+# Add text
+supermemory add "User prefers TypeScript over JavaScript"
+
+# Add a file (PDF, markdown, text, etc.)
+supermemory add ./meeting-notes.pdf --tag meetings
+
+# Add a URL
+supermemory add https://docs.example.com/api --tag docs
+
+# Read from stdin
+cat file.txt | supermemory add --stdin
+echo "some content" | supermemory add --stdin --tag notes
+
+# With metadata
+supermemory add "Design doc v2" --metadata '{"category": "engineering", "priority": "high"}'
+
+# Custom document ID
+supermemory add "My doc" --id custom-doc-id --tag project
+
+# Batch mode (JSONL from stdin, each line: {"content": "...", "tag": "..."})
+cat batch.jsonl | supermemory add --batch
+```
+
+**Options:**
+- `--tag <string>` — Container tag
+- `--stdin` — Read content from stdin
+- `--title <string>` — Document title
+- `--metadata <json>` — JSON metadata object
+- `--id <string>` — Custom document ID
+- `--batch` — Batch mode, reads JSONL from stdin
+
+### `search` — Search memories
+
+Semantic search across memories with filtering and reranking.
+
+```bash
+# Basic search
+supermemory search "authentication patterns"
+
+# Scoped to a tag with limit
+supermemory search "auth" --tag api --limit 5
+
+# With reranking for better relevance
+supermemory search "database migrations" --rerank
+
+# Query rewriting (LLM rewrites query for better results)
+supermemory search "how do we handle auth" --rewrite
+
+# Different search modes
+supermemory search "user prefs" --mode memories    # extracted memories only
+supermemory search "user prefs" --mode hybrid      # memories + document chunks
+supermemory search "user prefs" --mode documents   # full documents only
+
+# Include specific fields
+supermemory search "api design" --include summary,chunks,memories
+
+# Metadata filtering
+supermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}'
+
+# Similarity threshold (0-1)
+supermemory search "preferences" --threshold 0.5
+```
+
+**Options:**
+- `--tag <string>` — Filter by container tag
+- `--limit <number>` — Max results (default: 10)
+- `--threshold <number>` — Similarity threshold 0-1 (default: 0)
+- `--rerank` — Enable reranking for better relevance
+- `--rewrite` — Rewrite query using LLM
+- `--mode <string>` — `memories` | `hybrid` | `documents` (default: memories)
+- `--include <string>` — Fields: summary, chunks, memories, document
+- `--filter <json>` — Metadata filter object
+
+### `remember` — Store a memory directly
+
+Store a specific fact or memory without ingesting a full document.
+
+```bash
+# Store a memory
+supermemory remember "User prefers dark mode" --tag user_123
+
+# Mark as permanent/static (won't decay)
+supermemory remember "User is a senior engineer at Acme Corp" --static --tag user_123
+
+# With metadata
+supermemory remember "Discussed Q3 roadmap" --tag meetings --metadata '{"type": "decision"}'
+```
+
+**Options:**
+- `--tag <string>` — Container tag
+- `--static` — Mark as permanent memory
+- `--metadata <json>` — JSON metadata
+
+### `forget` — Delete a memory
+
+```bash
+# Forget by memory ID
+supermemory forget mem_abc123 --tag default
+
+# Forget by content match
+supermemory forget --content "outdated preference" --tag default
+
+# With reason
+supermemory forget mem_abc123 --reason "User corrected this information"
+```
+
+**Options:**
+- `--tag <string>` — Container tag
+- `--reason <string>` — Reason for forgetting
+- `--content <string>` — Forget by content match instead of ID
+
+### `update` — Update an existing memory
+
+```bash
+supermemory update mem_123 "Updated preference: prefers Bun over Node"
+supermemory update mem_123 "New content" --metadata '{"updated": true}'
+```
+
+**Options:**
+- `--tag <string>` — Container tag
+- `--metadata <json>` — Updated metadata
+- `--reason <string>` — Reason for update
+
+### `profile` — Get user profile
+
+Retrieve the auto-generated user profile for a container tag.
+
+```bash
+# Get profile for default tag
+supermemory profile
+
+# Get profile for specific tag
+supermemory profile user_123
+
+# Search within the profile
+supermemory profile user_123 --query "programming preferences"
+```
+
+Returns static facts (long-term) and dynamic context (recent activity).
+
+---
+
+## Document Management
+
+### `docs` — Manage documents
+
+```bash
+# List documents
+supermemory docs list --tag default --limit 20
+
+# Get a specific document
+supermemory docs get doc_abc123
+
+# Check processing status
+supermemory docs status doc_abc123
+
+# View document chunks
+supermemory docs chunks doc_abc123
+
+# Delete a document
+supermemory docs delete doc_abc123 --yes
+```
+
+**Subcommands:** `list`, `get`, `delete`, `chunks`, `status`
+
+---
+
+## Container Tags
+
+### `tags` — Manage container tags
+
+Container tags scope memories to users, projects, or any logical grouping.
+
+```bash
+# List all tags
+supermemory tags list
+
+# Get tag info (memory count, doc count, etc.)
+supermemory tags info user_123
+
+# Create a new tag
+supermemory tags create my-new-project
+
+# Set context on a tag (injected into profile responses)
+supermemory tags context user_123 --set "This user is a premium customer"
+
+# Clear context
+supermemory tags context user_123 --clear
+
+# Merge tags (moves all memories from source to target)
+supermemory tags merge old-tag --into new-tag --yes
+
+# Delete a tag
+supermemory tags delete old-tag --yes
+```
+
+**Subcommands:** `list`, `info`, `create`, `delete`, `context`, `merge`
+
+---
+
+## API Keys
+
+### `keys` — Manage API keys
+
+```bash
+# List all keys
+supermemory keys list
+
+# Create a new key
+supermemory keys create --name my-agent --permission write
+
+# Create a scoped key (restricted to one container tag)
+supermemory keys create --name bot-key --tag user_123 --expires 30
+
+# Revoke a key
+supermemory keys revoke key_abc123 --yes
+
+# Toggle a key on/off
+supermemory keys toggle key_abc123
+```
+
+**Subcommands:** `list`, `create`, `revoke`, `toggle`
+
+---
+
+## Connectors
+
+### `connectors` — External data sources
+
+Connect Google Drive, Notion, OneDrive, and other services to automatically sync documents.
+
+```bash
+# List connected services
+supermemory connectors list
+
+# Connect a service (opens OAuth flow)
+supermemory connectors connect google-drive --tag docs
+supermemory connectors connect notion --tag notes
+
+# Trigger a sync
+supermemory connectors sync conn_abc123
+
+# View sync history
+supermemory connectors history conn_abc123 --limit 10
+
+# List synced resources
+supermemory connectors resources conn_abc123
+
+# Disconnect
+supermemory connectors disconnect conn_abc123 --yes
+```
+
+**Subcommands:** `list`, `connect`, `sync`, `history`, `disconnect`, `resources`
+
+---
+
+## Plugins
+
+### `plugins` — IDE and tool integrations
+
+Connect the CLI to Claude Code, Cursor, and other tools.
+
+```bash
+# List available plugins
+supermemory plugins list
+
+# Connect a plugin (with auto-configuration)
+supermemory plugins connect claude-code --auto-configure
+supermemory plugins connect cursor --auto-configure
+
+# Check plugin status
+supermemory plugins status claude-code
+
+# Revoke a plugin connection
+supermemory plugins revoke claude-code --yes
+```
+
+**Subcommands:** `list`, `connect`, `revoke`, `status`
+
+---
+
+## Team Management
+
+### `team` — Manage team members
+
+```bash
+# List team members
+supermemory team list
+
+# Invite a member
+supermemory team invite user@example.com --role admin
+supermemory team invite user@example.com --role member
+
+# Change a member's role
+supermemory team role member_123 admin
+
+# Remove a member
+supermemory team remove member_123 --yes
+
+# View pending invitations
+supermemory team invitations
+```
+
+**Subcommands:** `list`, `invite`, `remove`, `role`, `invitations`
+
+---
+
+## Monitoring
+
+### `status` — Account dashboard
+
+```bash
+supermemory status
+supermemory status --period 7d    # 24h, 7d, 30d, all
+```
+
+Shows memory count, document count, API usage, and storage.
+
+### `logs` — Request logs
+
+```bash
+# Recent logs
+supermemory logs
+
+# Filter by time period
+supermemory logs --period 7d
+
+# Filter by status
+supermemory logs --status error
+
+# Filter by request type
+supermemory logs --type search
+
+# Get a specific log entry
+supermemory logs get req_abc123
+```
+
+### `billing` — Usage and billing
+
+```bash
+supermemory billing          # Overview
+supermemory billing usage    # Detailed usage breakdown
+supermemory billing invoices # Past invoices
+```
+
+---
+
+## Utility Commands
+
+```bash
+# Open Supermemory console in browser
+supermemory open
+supermemory open graph       # Memory graph view
+supermemory open billing
+supermemory open settings
+supermemory open docs
+supermemory open keys
+
+# Machine-readable help (useful for LLM agents)
+supermemory help --json
+supermemory help --all
+
+# Per-command help
+supermemory search --help
+supermemory tags --help --json
+```
+
+---
+
+## Scoped Keys Mode
+
+When using a scoped API key (restricted to a single container tag), only these commands are available:
+
+`search`, `add`, `remember`, `forget`, `update`, `profile`, `whoami`
+
+The tag is automatically set from the key's scope — no need to pass `--tag`.
+
+---
+
+## Common Patterns
+
+### Pipe content from other tools
+
+```bash
+# Ingest git log
+git log --oneline -20 | supermemory add --stdin --tag git-history
+
+# Ingest command output
+curl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs
+
+# Pipe search results to jq
+supermemory search "auth" --json | jq '.results[].memory'
+```
+
+### Scripting with JSON output
+
+```bash
+# All commands support --json for machine-readable output
+supermemory search "query" --json
+supermemory tags list --json
+supermemory profile user_123 --json
+supermemory status --json
+```
+
+### CI/CD integration
+
+```bash
+# Use env var for auth
+export SUPERMEMORY_API_KEY=sm_abc_xxx
+
+# Ingest docs on deploy
+supermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest
+
+# Check status
+supermemory status --json | jq '.memoryCount'
+```

package/.agents/skills/tdd/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so that test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for deep modules (small interface, deep implementation) — run the `/codebase-design` skill for the vocabulary and the testability checks
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/.agents/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/.agents/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic