# SupStack OpenClaw Skill — Claude Code Briefing

> **What this is:** A complete handover document for continuing development of the SupStack OpenClaw skill. Feed this file + the skill zip to Claude Code.

---

## 1. What SupStack Is

SupStack is an **AI-powered supplement intelligence platform** delivered as an OpenClaw skill on WhatsApp and Telegram. It combines a curated REST API (225 supplements, 7,870+ PubMed studies, 460+ drug interactions, 1,760+ verified medical claims) with an AI agent that provides evidence-based supplement guidance.

**Key differentiator:** It covers the complete supplement lifecycle — from research to structured experimentation and ongoing optimisation. Generic AI stops at "consider taking X."

---

## 2. Current Architecture

```
┌─────────────────────────────────────────────────┐
│  User (WhatsApp / Telegram)                     │
│         ↕                                       │
│  OpenClaw Platform                              │
│         ↕                                       │
│  SupStack Skill (SKILL.md + supstack.sh)        │
│    ├── Evidence queries → SupStack REST API     │
│    ├── User memory → OpenClaw local storage     │
│    ├── Safety watchdog → passive behavior       │
│    ├── Research monitor → cron job              │
│    ├── Interest tracking → profile system       │
│    └── N-of-1 experiments → local state         │
│         ↕                                       │
│  SupStack REST API (Vercel)                     │
│  https://supstack.me/api/v1                     │
│    ├── 17 GET endpoints, public, stateless      │
│    ├── 225 supplements with evidence scores     │
│    └── Zero user data                           │
└─────────────────────────────────────────────────┘
```

**Privacy model:** All personal data (profile, stack, medications, experiments) lives on-device via OpenClaw's local storage. The API is read-only reference data with zero user information.

---

## 3. File Inventory

| File | Lines | Purpose |
|------|-------|---------|
| `SKILL.md` | 1,297 | **Main agent instructions.** OpenClaw reads this to know how to behave. Contains persona, API reference, command docs, behavioral rules, profile system, safety watchdog, research monitor, experiments, interest tracking. |
| `scripts/supstack.sh` | 1,614 | **Helper script.** Wraps all API calls, profile management, interest tracking, experiments, and monitor operations. The agent calls this via `bash scripts/supstack.sh <command> [args]`. |
| `API.md` | 1,816 | **Full API documentation.** All 17 endpoints with request/response schemas, examples, and field descriptions. Reference for building new features. |
| `README.md` | 383 | **User-facing readme.** Explains what SupStack does in plain language with conversation examples. |
| `templates/profile.md` | 45 | **Profile template.** Blank markdown template for new user profiles with all 11 sections. |
| `cron/research-monitor.json` | 7 | **Cron config.** Schedules the research monitor to run periodically and check for new studies on tracked supplements. |
| `tests/run-all-tests.sh` | 952 | **Test suite.** Automated tests for API endpoints, script commands, profile operations, and experiments. |
| `TRACKING-ENDPOINT-SPEC.md` | 660 | **N-of-1 experiment tracking spec.** Design doc for the `/supplements/:slug/tracking` API endpoint (now built). |

---

## 4. Script Commands (33 total)

### Evidence & Lookup
| Command | What it does |
|---------|-------------|
| `info <slug>` | Full supplement profile (score, studies, mechanisms, dosing) |
| `search <query>` | Full-text search across name, description, categories, tags, effects |
| `protocol <slug>` | Dosing protocol (dose, timing, form, cycling) |
| `studies --supplement=<slug>` | Studies for a specific supplement |

### Recommendations
| Command | What it does |
|---------|-------------|
| `match <g1> [g2] [g3] [limit]` | Goal-based matching (weighted) |
| `recommend [--goals=..] [--stack=..]` | Smart recs (stack-aware, synergy-boosted) |

### Safety & Interactions
| Command | What it does |
|---------|-------------|
| `safety <slug>` | Safety profile, contraindications |
| `interactions <slug> [medication]` | Drug/supplement interactions |
| `interactions-multi <s1> <s2>` | Cross-check multiple items |
| `synergies <slug>` | Synergy lookup for a supplement |
| `synergies-multi <s1> <s2>` | Multi-supplement synergy matrix |

### User Profile (11 sections)
| Command | What it does |
|---------|-------------|
| `profile` | Show full profile |
| `profile-update <section> <content>` | Replace a section |
| `profile-add <section> <line>` | Append to a section |
| `profile-get <section>` | Read one section |
| `profile-stack-slugs` | Extract supplement slugs from stack |
| `profile-medications` | Extract medication names |

### Interest & Search Tracking
| Command | What it does |
|---------|-------------|
| `profile-log-interest <slug> [context]` | Log supplement interest (auto-increments) |
| `profile-log-search <type> <subject> [context]` | Log search query to history |
| `profile-interests` | Return all interests sorted by frequency |

### N-of-1 Experiments
| Command | What it does |
|---------|-------------|
| `experiment-start <slug> <goal>` | Start a new experiment |
| `experiment-baseline <id> <data>` | Record baseline measurements |
| `experiment-checkin <id> <data>` | Record a check-in |
| `experiment-status [id]` | Check experiment progress |
| `experiment-evaluate <id>` | Compute experiment verdict |
| `experiment-list` | List all experiments |
| `experiment-questions <id> [type]` | Get questionnaire for an experiment |
| `timing-optimize [slugs]` | Optimal timing schedule for stack |

### Research Monitor
| Command | What it does |
|---------|-------------|
| `monitor-setup <slug1,slug2,...>` | Set up monitoring for supplements |
| `monitor-check` | Check for new studies (cron calls this) |
| `monitor-status` | Show what's being monitored |
| `monitor-add <slug>` | Add a supplement to monitoring |
| `monitor-remove <slug>` | Remove from monitoring |
| `monitor-clear` | Clear all monitoring |

### System
| Command | What it does |
|---------|-------------|
| `welcome` | First-run onboarding check |
| `help` | Command reference |

---

## 5. Profile System (11 Sections)

The user profile is a markdown file stored locally by OpenClaw. Sections:

1. **stack** — Supplements currently taking (slug, name, dose, timing)
2. **medications** — Prescriptions and OTC drugs
3. **goals** — Health priorities in order
4. **conditions** — Health conditions affecting safety
5. **allergies** — Allergens and intolerances
6. **trials** — Past supplements tried and stopped (with reason)
7. **interests** — Supplements researched but not yet taking (auto-tracked)
8. **history** — Recent search queries (rolling 30-entry log, auto-tracked)
9. **preferences** — Budget, form, timing constraints
10. **profile** — Demographics and lifestyle
11. **notes** — Anything else relevant

---

## 6. Key Behaviors (Implemented in SKILL.md)

### Safety Watchdog (Passive)
Always-on. Detects when user mentions medications, new prescriptions, health changes, or procedures in casual conversation. Auto-cross-references against supplement stack. This is NOT a command — it's behavioral.

### Interest Tracking (Automatic)
Logs every time the user asks about a supplement. Builds a frequency map. When a supplement hits 3+ queries, proactively offers a deep dive. Also detects topic patterns (e.g., "most of your questions are sleep-related").

### Research Monitor (Cron)
Periodic background job that checks for new studies on the user's tracked supplements. Sends proactive updates via the OpenClaw cron system.

### Onboarding (First-Run)
Checks if the user has been welcomed. If not, runs a brief intro explaining what SupStack can do, asks about current supplements and goals, and builds the initial profile.

### N-of-1 Experiments
Structured 4-week supplement trials with baseline questionnaire, weekly check-ins, and automated verdict (clear-win, probable-win, inconclusive, not-effective, stop). All experiment state stored locally.

### Timing Optimizer
Analyzes the user's full stack and generates an optimal daily schedule. Resolves conflicts (calcium/iron spacing, morning/evening timing, food requirements).

### API Resilience
If the API is down, the script falls back to the agent's own knowledge with a disclaimer that data may not be current.

---

## 7. What Could Be Built Next

### 7.1 — Marketplace Integration (FUTURE)

In-chat purchasing from verified suppliers. Auto-refill scheduling based on dosage protocol and pack size. This is a later-stage feature requiring partner integrations.

### 7.2 — Biomarker Integration (FUTURE)

Accept lab results (blood work) and map deficiencies to supplement recommendations via Medicus AI. Requires API integration with Medicus AI's medical LLM.

---

## 8. API Reference (Quick)

**Base URL:** `https://supstack.me/api/v1`

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/supplements` | GET | List all (supports `?category=`, `?goal=`) |
| `/supplements/:slug` | GET | Full supplement detail |
| `/supplements/:slug/protocol` | GET | Dosing protocol |
| `/supplements/:slug/tracking` | GET | N-of-1 experiment tracking protocol |
| `/goals` | GET | All 27 goals |
| `/match` | GET | Goal-based matching (weighted) |
| `/recommend` | GET | Smart recommendations (accepts `goals`, `stack`, `limit`) |
| `/studies` | GET | Research studies feed |
| `/compare` | GET | Side-by-side comparison |
| `/interactions` | GET | Drug & supplement interactions |
| `/synergies` | GET | Synergy lookup |
| `/safety` | GET | Full safety profile |
| `/definitions` | GET | Scientific glossary (80+ terms) |
| `/stack/analyze` | GET | Full stack audit |
| `/search` | GET | Full-text supplement search |
| `/search/suggest` | GET | Autocomplete / typeahead |
| `/categories` | GET | Category & type metadata |

Full schemas in `API.md`.

---

## 9. Brand & Tone

- **Voice:** Evidence-first, trustworthy, calm authority. Never salesy, never alarmist.
- **Evidence scores:** Always X/10 or X.X/10
- **Study counts:** "backed by N studies"
- **Severity:** 🔴 High / 🟡 Moderate / 🟢 Low
- **Supplement names:** Title case (Magnesium Glycinate)
- **Don't say:** "consult your doctor" (generic). **Say:** "worth confirming with your prescriber"
- **Don't say:** "research shows" (vague). **Say:** "based on N studies"

---

## 10. Technical Notes

- **Shell script:** `supstack.sh` uses `curl` + `jq` for API calls. All commands are in a single case statement.
- **Error handling:** 15-second timeout on API calls. Falls back to agent knowledge if API is down.
- **Profile storage:** Markdown file managed via sed/grep commands. Sections delimited by `## Section Name` headers.
- **Interest tracking:** JSON file with slug → {count, lastSeen, contexts[]} entries. Capped at 30 search history entries.
- **Experiments:** JSON files per experiment in local storage. State machine: baseline → check-ins → verdict.
- **Cron:** `research-monitor.json` defines the schedule. The `monitor-check` command is called by cron and returns new study info.
- **No authentication:** The API is public and stateless. No API keys needed.
- **Vercel deployment:** API runs on Vercel serverless. No cold start issues observed.

---

## 11. Testing Checklist

Before deploying changes, verify:

```bash
# Syntax check
bash -n scripts/supstack.sh

# Core queries
bash scripts/supstack.sh info magnesium
bash scripts/supstack.sh search "ashwa"
bash scripts/supstack.sh protocol creatine
bash scripts/supstack.sh safety ashwagandha
bash scripts/supstack.sh interactions magnesium
bash scripts/supstack.sh match deep-sleep
bash scripts/supstack.sh recommend --goals=deep-sleep

# Profile
bash scripts/supstack.sh profile
bash scripts/supstack.sh profile-log-interest lions-mane "test"
bash scripts/supstack.sh profile-interests

# Experiments
bash scripts/supstack.sh experiment-list

# Monitor
bash scripts/supstack.sh monitor-status

# Full test suite
bash tests/run-all-tests.sh --quick
```

---

*Last updated: March 2026*