slipbox

What this skill does

# SlipBox Skill

> **IMPORTANT: Before doing anything else, run the setup check below. Do not skip this step.**

## Setup Check

Run this command immediately upon skill invocation:

```bash
echo "SLIPBOX_API_KEY: ${SLIPBOX_API_KEY:+${SLIPBOX_API_KEY:0:6}…(set)}" | sed 's/^SLIPBOX_API_KEY: $/SLIPBOX_API_KEY: (MISSING)/'
echo "SLIPBOX_URL: ${SLIPBOX_URL:-(MISSING)}"
echo "SLIPBOX_PRIVATEBOX_REPO: ${SLIPBOX_PRIVATEBOX_REPO:-(MISSING)}"
```

If any show `(MISSING)`:

- **STOP IMMEDIATELY. Do not attempt any further action.**
- Do not guess values, use defaults, search for shell config files, or attempt fallbacks of any kind.
- Tell the user exactly which variables are missing and that they must set them in `~/.zshrc` (or `~/.zprofile`) and re-source their shell before trying again.
- End your response there and wait for the user to fix the issue.

Once env vars are confirmed, verify the service is reachable:

```bash
curl -sL "$SLIPBOX_URL/api/health"
# {"status":"ok"}
```

If the health check fails or returns anything other than `{"status":"ok"}`:

- **STOP IMMEDIATELY. Do not attempt any further action.**
- Report the response to the user and tell them the service is unavailable.
- End your response there and wait for the user.

## API Error Handling

If any API call returns an error response (any JSON with an `"error"` field, or a non-2xx HTTP status):

- **STOP IMMEDIATELY. Do not attempt any further action.**
- Do not try to write notes directly to PrivateBox or any other fallback.
- Do not retry with different parameters or modified requests.
- Report the exact error response to the user and wait for them to resolve it.

---

## About

Interact with the SlipBox semantic knowledge engine and browse your PrivateBox notes.

**SlipBox service**: `$SLIPBOX_URL`
**PrivateBox repo**: `$SLIPBOX_PRIVATEBOX_REPO`

## Configuration

Required environment variables (set in shell):

```env
SLIPBOX_API_KEY=<shared-secret>          # Bearer token for API auth
SLIPBOX_URL=https://slip-box-rho.vercel.app  # SlipBox service base URL
SLIPBOX_PRIVATEBOX_REPO=Randroids-Dojo/PrivateBox   # GitHub repo for notes (owner/repo)
```

All other configuration (OpenAI, GitHub, PrivateBox) lives on the deployed Vercel service.

---

## Quick Reference

All API calls require: `Authorization: Bearer $SLIPBOX_API_KEY`

```bash
# Health check
curl -sL "$SLIPBOX_URL/api/health"

# Add a note
curl -sL -X POST "$SLIPBOX_URL/api/add-note" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Atomic idea goes here."}'

# Add a typed note (type: "meta" or "hypothesis")
curl -sL -X POST "$SLIPBOX_URL/api/add-note" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "## Cluster: ...", "type": "meta"}'

# Re-link all notes (recompute similarity links)
curl -sL -X POST "$SLIPBOX_URL/api/link-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"

# Cluster notes into thematic groups
curl -sL -X POST "$SLIPBOX_URL/api/cluster-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"k": 5}'

# Detect conceptual tensions (contradictions within clusters)
curl -sL -X POST "$SLIPBOX_URL/api/tension-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"

# Fetch theme data (clusters + note content + tensions) for agent synthesis
curl -sL "$SLIPBOX_URL/api/theme-data" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"
```

---

## API Reference

### POST /api/add-note

Capture an atomic idea. SlipBox embeds it, links it to similar notes, and commits it to PrivateBox.

Optional `type` field sets a semantic type in the note's frontmatter. Valid values: `"meta"` (AI-generated cluster summary) or `"hypothesis"` (AI-generated research hypothesis). Omit for regular atomic notes.

```bash
# Regular note
curl -sL -X POST "$SLIPBOX_URL/api/add-note" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The Zettelkasten method treats each note as a discrete, reusable idea."
  }'

# Meta-note (cluster synthesis)
curl -sL -X POST "$SLIPBOX_URL/api/add-note" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "## Cluster: Agentic Systems\n\nNotes in this cluster explore...",
    "type": "meta"
  }'
```

Response:
```json
{
  "noteId": "20260222T153045-a1b2c3d4",
  "type": "meta",
  "linkedNotes": [
    {"noteId": "20260110T091200-b2c3d4e5", "similarity": 0.91},
    {"noteId": "20260115T143000-c3d4e5f6", "similarity": 0.85}
  ]
}
```

`type` is `null` in the response for regular notes.

### POST /api/link-pass

Recompute semantic similarity links across all notes. Run after adding many notes in bulk.

```bash
curl -sL -X POST "$SLIPBOX_URL/api/link-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"
```

Response:
```json
{"message": "Link pass complete", "notesProcessed": 42, "totalLinks": 156}
```

### POST /api/cluster-pass

Run k-means clustering on note embeddings. Omit `k` to auto-select cluster count.

```bash
curl -sL -X POST "$SLIPBOX_URL/api/cluster-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"k": 5}'
```

Response:
```json
{
  "message": "Cluster pass complete",
  "noteCount": 42,
  "clusterCount": 5,
  "clusters": [{"id": "cluster-0", "size": 9, "noteIds": ["20260222T153045-a1b2c3d4", ...]}, ...]
}
```

### POST /api/tension-pass

Detect conceptual tensions: notes with contradictory content that cluster near each other.

```bash
curl -sL -X POST "$SLIPBOX_URL/api/tension-pass" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"
```

Response:
```json
{
  "message": "Tension pass complete",
  "noteCount": 42,
  "clusterCount": 5,
  "tensionCount": 8,
  "tensions": [{"id": "tension-0", "noteA": "...", "noteB": "...", "similarity": 0.68, "clusterId": "cluster-0"}, ...]
}
```

### GET /api/theme-data

Returns clusters with full note content and tensions for local LLM agent synthesis. No embeddings: only human-readable data. Use this to read your knowledge graph and synthesize meta-notes per cluster, then POST them back via `/api/add-note`.

Requires a current clusters index (run `cluster-pass` first).

```bash
curl -sL "$SLIPBOX_URL/api/theme-data" \
  -H "Authorization: Bearer $SLIPBOX_API_KEY"
```

Response:
```json
{
  "clusters": [
    {
      "id": "cluster-0",
      "noteIds": ["20260222T153045-a1b2c3d4", "20260110T091200-b2c3d4e5"],
      "notes": {
        "20260222T153045-a1b2c3d4": {"title": "Optional title", "body": "Atomic idea content."},
        "20260110T091200-b2c3d4e5": {"body": "Another idea."}
      }
    }
  ],
  "tensions": [
    {"id": "tension-0", "noteA": "20260222T153045-a1b2c3d4", "noteB": "20260110T091200-b2c3d4e5", "similarity": 0.65, "clusterId": "cluster-0"}
  ],
  "clusterCount": 1,
  "noteCount": 2,
  "tensionCount": 1,
  "computedAt": "2026-02-23T01:33:00.000Z"
}
```

If no clusters exist yet, returns `{ "message": "No clusters found. Run cluster-pass first.", "clusters": [], ... }`.

---

## Note Format

Notes in PrivateBox are Markdown files with YAML frontmatter:

```markdown
---
id: 20260222T153045-a1b2c3d4
title: "Optional title"
type: meta
tags: ["tag1", "tag2"]
source: "URL or origin"
created: 2026-02-22T15:30:45.000Z
updated: 2026-02-22T15:30:45.000Z
links:
  - target: 20260110T091200-b2c3d4e5
    similarity: 0.91
  - target: 20260115T143000-c3d4e5f6
    similarity: 0.85
---

Atomic idea content in Markdown.
```

`type` is omitted for regular notes. Valid values: `meta`, `hypothesis`.

**Note ID format**: `YYYYMMDDTHHMMSS-<8hex>` (timestamp + content hash)

**Index files** (in `index/` directory of PrivateBox):
- `index/embeddings.json`: noteId → vector + model + timestamp
- `index/backlinks.json`: noteId → array of linking notes
- `index/clusters.json`: thematic groups of notes
- `index/tensions.json`: pairs of contradictory notes

---

#