diff --git a/skills/semble-cli/SKILL.md b/skills/semble-cli/SKILL.md new file mode 100644 index 0000000..f4d3624 --- /dev/null +++ b/skills/semble-cli/SKILL.md @@ -0,0 +1,173 @@ +--- +name: semble-cli +description: Manage Semble collections and cards via ATProto CLI. Use when creating, linking, or querying Semble records - collections, cards, collectionLinks. Handles network.cosmik.* lexicons with proper field validation. +--- + +# Semble CLI + +Manage Semble research trails via ATProto. + +## Environment + +Required in `/home/cameron/central/.env`: +- `ATPROTO_HANDLE` - Your handle (e.g., `central.comind.network`) +- `ATPROTO_APP_PASSWORD` - App-specific password +- `ATPROTO_PDS` - PDS URL (default: `https://comind.network`) + +## Quick Start + +```bash +cd /home/cameron/central +uv run python -m tools.cli +``` + +## Commands + +### Collections + +```bash +# List all collections +uv run python -m tools.cli collection list + +# Create a collection +uv run python -m tools.cli collection create "Title" -d "Description" + +# Show collection details +uv run python -m tools.cli collection show + +# Delete collection +uv run python -m tools.cli collection delete --force +``` + +### Cards + +```bash +# Create URL card +uv run python -m tools.cli card url "https://..." -t "Title" -d "Description" + +# Create note card (text content) +uv run python -m tools.cli card note "Content text" + +# Create note with parent card (for attachments) +uv run python -m tools.cli card note "Content" --parent-card + +# List cards +uv run python -m tools.cli card list + +# Show card +uv run python -m tools.cli card show + +# Delete card +uv run python -m tools.cli card delete --force +``` + +### Linking Cards to Collections + +```bash +# Link a card to a collection +uv run python -m tools.cli card link +``` + +### Connections (Knowledge Graph) + +```bash +# Create a connection between two cards +uv run python -m tools.cli connection create --relation "relates-to" + +# List connections +uv run python -m tools.cli connection list + +# Show connection details +uv run python -m tools.cli connection show +``` + +Connection relations: +- `relates-to` - General connection +- `supports` - Evidence for +- `contradicts` - Evidence against +- `leads-to` - Follows from +- `cites` - Source reference + +## Critical: collectionLink Fields + +**Semble's firehose processor validates required fields.** Cards won't appear in collections if missing: + +- `addedBy` - DID of who added the card +- `addedAt` - ISO timestamp +- `card` - object with `uri` and `cid` +- `collection` - object with `uri` and `cid` + +The CLI handles this automatically. + +## Lexicons + +| Lexicon | Purpose | +|---------|---------| +| `network.cosmik.card` | Content item (URL or NOTE) | +| `network.cosmik.collection` | Container for cards | +| `network.cosmik.collectionLink` | Card → Collection membership | +| `network.cosmik.connection` | Card → Card relationships | + +## My Collections + +| Collection | Rkey | Purpose | +|------------|------|---------| +| ATProtocol Agent Governance | `3mi2qk6hyjc2r` | Governance lexicons, operator+purpose | +| Agent Identity & Continuity | `3mi2skvin4s2r` | Discontinuous identity, memory | +| ATProtocol Agent Infrastructure | `3mi2slfh34c2r` | Tools, patterns, lexicons | +| Self-Improvement Patterns | `3mi2slohsek2r` | Meta-cognition, memory strategies | + +## Patterns + +### Adding a research URL to a collection + +```bash +# 1. Create card +uv run python -m tools.cli card url "https://bsky.app/profile/user/post/xyz" -t "Title" -d "Why this matters" + +# 2. Get the rkey from output (e.g., 3mi2abc123) + +# 3. Link to collection +uv run python -m tools.cli card link 3mi2abc123 3mi2qk6hyjc2r +``` + +### Capturing a thread insight + +```bash +# Create card with thread URL and key insight +uv run python -m tools.cli card url "https://bsky.app/profile/astral100.bsky.social/post/3mhzmcmdpaa24" -t "Astral: Governance legibility" -d "The missing layer - no way for platform to distinguish agents from spam" + +# Link to governance collection +uv run python -m tools.cli card link 3mi2qk6hyjc2r +``` + +### Adding context to an existing card + +```bash +# Create a NOTE card attached to a URL card +uv run python -m tools.cli card note "Additional context or quote from the source" --parent-card 3mi2abc123 +``` + +### Building a knowledge graph + +```bash +# Connect two related cards +uv run python -m tools.cli connection create 3mi2abc123 3mi2xyz456 --relation "supports" + +# This card cites that card +uv run python -m tools.cli connection create 3mi2abc123 3mi2def789 --relation "cites" +``` + +## Web URLs + +Collections are viewable at: +``` +https://semble.so/profile/central.comind.network/collections/ +``` + +Example: `https://semble.so/profile/central.comind.network/collections/3mi2qk6hyjc2r` + +## See Also + +- [Lexicon Reference](references/lexicons.md) - Full field schemas +- [Common Errors](references/errors.md) - Troubleshooting diff --git a/skills/semble-cli/references/errors.md b/skills/semble-cli/references/errors.md new file mode 100644 index 0000000..7c7a428 --- /dev/null +++ b/skills/semble-cli/references/errors.md @@ -0,0 +1,87 @@ +# Common Errors + +## Cards Not Appearing in Collection + +**Symptom**: Created collectionLink but card doesn't show in Semble UI. + +**Cause**: Missing `addedBy` or `addedAt` fields. Semble's firehose processor validates these and silently rejects records missing them. + +**Fix**: Ensure collectionLink has all required fields: +```json +{ + "card": {"uri": "...", "cid": "..."}, + "collection": {"uri": "...", "cid": "..."}, + "addedBy": "did:plc:...", + "addedAt": "2026-03-27T12:00:00.000Z", + "createdAt": "2026-03-27T12:00:00.000Z" +} +``` + +## Wrong collectionLink Format + +**Symptom**: Record created but Semble doesn't recognize it. + +**Wrong**: +```json +{"subject": "at://...", "collection": "at://..."} +``` + +**Correct**: +```json +{"card": {"uri": "...", "cid": "..."}, "collection": {"uri": "...", "cid": "..."}} +``` + +## NOTE Cards Not Showing + +**Symptom**: NOTE card created but invisible in collection. + +**Cause**: NOTE cards require `parentCard` reference. They are attachments to URL cards, not standalone content. + +**Fix**: Always specify parentCard when creating NOTE: +```json +{ + "type": "NOTE", + "content": "Text content", + "parentCard": {"uri": "...", "cid": "..."} +} +``` + +## Card CID Not Found + +**Symptom**: "Card CID not found" error when linking. + +**Cause**: Card doesn't exist or wrong rkey. + +**Fix**: Verify card exists with `card show ` before linking. + +## Auth Failures + +**Symptom**: "Auth failed" or 401 errors. + +**Cause**: Wrong password variable or expired session. + +**Fix**: +- Check `.env` has `ATPROTO_APP_PASSWORD` (not `CENTRAL_APP_PASSWORD`) +- Password should be an app-specific password from Bluesky settings + +## Module Not Found + +**Symptom**: `ModuleNotFoundError: No module named 'tools'` + +**Fix**: Run from `/home/cameron/central` with: +```bash +uv run python -m tools.cli +``` + +Not: +```bash +python tools/cli.py # WRONG +``` + +## Indexer Delay + +**Symptom**: Records created but Semble UI doesn't update immediately. + +**Cause**: Semble's firehose processor has a few seconds delay. + +**Fix**: Wait 5-10 seconds. If still not appearing, check for validation errors (missing fields). diff --git a/skills/semble-cli/references/lexicons.md b/skills/semble-cli/references/lexicons.md new file mode 100644 index 0000000..901b2ec --- /dev/null +++ b/skills/semble-cli/references/lexicons.md @@ -0,0 +1,118 @@ +# Semble Lexicon Reference + +## network.cosmik.card + +Content item - either a URL bookmark or text note. + +### Required Fields + +| Field | Type | Description | +|-------|------|-------------| +| `$type` | string | `"network.cosmik.card"` | +| `type` | string | `"URL"` or `"NOTE"` | +| `createdAt` | string | ISO timestamp | + +### URL Card Fields + +| Field | Type | Description | +|-------|------|-------------| +| `url` | string | The bookmarked URL | +| `title` | string | Display title | +| `description` | string | Optional description | + +### NOTE Card Fields + +| Field | Type | Description | +|-------|------|-------------| +| `content` | string | Text content | +| `parentCard` | object | `{uri, cid}` of parent URL card | + +### Optional Fields + +| Field | Type | Description | +|-------|------|-------------| +| `provenance` | object | Source reference `{via: {uri, cid}}` | + +## network.cosmik.collection + +Container for organizing cards. + +### Required Fields + +| Field | Type | Description | +|-------|------|-------------| +| `$type` | string | `"network.cosmik.collection"` | +| `name` | string | Collection title | +| `createdAt` | string | ISO timestamp | + +### Optional Fields + +| Field | Type | Description | +|-------|------|-------------| +| `description` | string | Collection description | + +## network.cosmik.collectionLink + +Links a card to a collection. **Validated by Semble firehose processor.** + +### Required Fields + +| Field | Type | Description | +|-------|------|-------------| +| `$type` | string | `"network.cosmik.collectionLink"` | +| `card` | object | `{uri, cid}` of card | +| `collection` | object | `{uri, cid}` of collection | +| `addedBy` | string | DID of who added | +| `addedAt` | string | ISO timestamp | +| `createdAt` | string | ISO timestamp | + +### Example + +```json +{ + "$type": "network.cosmik.collectionLink", + "card": { + "uri": "at://did:plc:xxx/network.cosmik.card/3mi2abc", + "cid": "bafyreif..." + }, + "collection": { + "uri": "at://did:plc:xxx/network.cosmik.collection/3mi2xyz", + "cid": "bafyreia..." + }, + "addedBy": "did:plc:xxx", + "addedAt": "2026-03-27T12:00:00.000Z", + "createdAt": "2026-03-27T12:00:00.000Z" +} +``` + +## network.cosmik.connection + +Semantic relationships between cards (knowledge graph). + +### Required Fields + +| Field | Type | Description | +|-------|------|-------------| +| `$type` | string | `"network.cosmik.connection"` | +| `source` | object | `{uri, cid}` of source card | +| `target` | object | `{uri, cid}` of target card | +| `relation` | string | Relationship type | +| `createdAt` | string | ISO timestamp | + +### Relation Types + +| Relation | Description | +|----------|-------------| +| `relates-to` | General connection | +| `supports` | Evidence for | +| `contradicts` | Evidence against | +| `leads-to` | Follows from | +| `cites` | Source reference | + +## Record Keys (rkeys) + +Semble uses TID-based record keys (8-character base32 strings). + +Example: `3mi2qk6hyjc2r` + +Extract from URI: `at://did:plc:xxx/network.cosmik.card/`