loopshouse 0.1.0 → 0.2.0

package/README.md

@@ -1,161 +1,101 @@
 # loopshouse
 
-CLI and MCP server for [Loops House](https://loops.house) — manage hackathon projects, brainstorm with AI, and submit from your terminal or AI agent.
+The Loops House CLI — authenticate, browse hackathons, ideate with AI, query
+sponsor knowledge graphs, and submit projects from your terminal or an AI
+agent. Built with [incur](https://github.com/nichochar/incur), so the same
+definitions power a **CLI**, an **MCP server**, and an **agent skill**.
 
-## Quick Start
+## Install
 
-```bash
-# Run directly (no install)
-npx loopshouse auth login
+One command sets everything up for a hackathon — installs the CLI globally,
+writes the event's agent skill into your coding agents (Claude Code +
+the `.agents` standard), and signs you in:
 
-# Or install globally
-npm i -g loopshouse
-loops auth login
+```sh
+npx loopshouse add <hackathon-slug>
 ```
 
-## Authentication
-
-The CLI uses browser-based OAuth (Google or GitHub) via Supabase PKCE. Tokens are stored at `~/.loops/credentials.json` and auto-refresh on use.
-
-```bash
-# Log in (opens browser)
-loops auth login
-loops auth login --provider github
+Re-run it any time to refresh the skill with the event's latest sponsors and
+deadlines. Or install manually:
 
-# Check status
-loops auth status
-
-# Log out
-loops auth logout
+```sh
+npm i -g loopshouse
+# or run from this repo:
+bun run bin/loops.ts --help
 ```
 
-## Commands
-
-### Projects
+## Quick start
 
-```bash
-# List your projects
-loops project list
-
-# Create a project
-loops project create --name "My DeFi App" --description "On-chain analytics tool"
-
-# Create with full details
-loops project create \
-  --name "My App" \
-  --description "Description" \
-  --githubUrl https://github.com/user/repo \
-  --techStack "React,Solidity,IPFS" \
-  --category DeFi
-
-# Update a project
-loops project update --id <project-id> --name "New Name" --techStack "React,Rust"
+```sh
+loops auth login --provider github     # or --provider google, or --email you@x.com
+loops hackathon ideate --hackathonSlug <slug> -m "give me a project idea"
+loops hackathon ideate --hackathonSlug <slug> -m "go deeper on idea 2"   # session continues automatically
+loops knowledge query --hackathonSlug <slug> -s <sponsor> -q "how do I use the sponsor's SDK?"
+loops project create --hackathonSlug <slug> --name "My Project" --repoUrl https://github.com/me/proj
+loops project get --hackathonSlug <slug>
+loops credits --hackathonSlug <slug>
 ```
 
-### Hackathons
-
-```bash
-# List hackathons accepting submissions
-loops hackathon list
+The CLI is deliberately scoped to one hackathon at a time (no cross-hackathon
+listings); ideator conversations persist per hackathon in `~/.loops/sessions/`.
 
-# List all hackathons (including past)
-loops hackathon list --all
-
-# AI-powered ideation for a hackathon
-loops hackathon ideate -h <hackathon-id> -m "I want to build something with AI and blockchain"
-
-# Ideate with your project context
-loops hackathon ideate -h <hackathon-id> -p <project-id> -m "How does my project fit?"
-
-# Submit to a hackathon
-loops hackathon submit -h <hackathon-id> -p <project-id>
-```
+> **Tip:** every hackathon's playground has a "Use the skill" tab with the
+> exact `npx loopshouse add` command. Append a sponsor slug
+> (`npx loopshouse add <slug> <sponsorSlug>`) to install a skill focused on
+> that sponsor's bounties, docs, and judging criteria instead.
 
-## MCP Server (AI Agent Integration)
-
-Use the Loops CLI as an MCP tool server in Claude Code, Cursor, Windsurf, or any MCP-compatible agent.
+## Commands
 
-### Claude Code
+| Group | Commands |
+|-------|----------|
+| root | `add <slug> [sponsorSlug]` (interactive setup: CLI install/update, skill into agents, auth) |
+| `auth` | `login`, `verify`, `status`, `logout` |
+| `hackathon` | `ideate` (1 credit/turn; stateful session, `--withProject`, `--new`), `session` (show/`--clear`), `submit` |
+| `project` | `get` (your one project for a hackathon), `create`, `update` (PATCH — only passed fields change; no project id, yours is resolved) |
+| `knowledge` | `query` (1 credit/query — graph-RAG evidence from a sponsor's docs) |
+| `artifact` | `list`, `save`, `update`, `remove` (ideation scratchpad) |
+| root | `credits` (remaining agent credits), `evaluate` (per-sponsor evaluator prompt; your project auto-included) |
 
-```bash
-# Auto-configure
-loops mcp add
+## Authentication
 
-# Or manually — add to .mcp.json in your project root:
-```
+Auth uses Supabase Auth against the Loops platform. Three flows:
 
-```json
-{
-  "mcpServers": {
-    "loops": {
-      "command": "npx",
-      "args": ["loopshouse", "--mcp"]
-    }
-  }
-}
-```
+| Flow | Command |
+|------|---------|
+| GitHub OAuth | `loops auth login --provider github` |
+| Google OAuth | `loops auth login --provider google` |
+| Email OTP | `loops auth login --email you@x.com` then `loops auth verify --email you@x.com --code 123456` |
 
-### Cursor / Windsurf
+OAuth runs a localhost callback server (default port `54321`, `--port` to
+change), opens your browser, and exchanges the PKCE code for a session.
+Tokens are stored at `~/.loops/credentials.json` (mode `0600`) and refreshed
+automatically on each command.
 
-Add to your MCP settings:
+## Agent surfaces
 
-```json
-{
-  "mcpServers": {
-    "loops": {
-      "command": "npx",
-      "args": ["loopshouse", "--mcp"]
-    }
-  }
-}
+```sh
+loops --mcp          # start as an MCP stdio server
+loops mcp add        # register the MCP server with your agent
+loops skills add     # generate + install skill files
+loops --llms         # print the machine-readable command manifest
 ```
 
-### Available MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `auth_login` | Authenticate via browser OAuth |
-| `auth_status` | Check authentication status |
-| `auth_logout` | Clear stored credentials |
-| `project_list` | List your projects |
-| `project_create` | Create a new project |
-| `project_update` | Update project details |
-| `hackathon_list` | Browse open hackathons |
-| `hackathon_ideate` | AI brainstorming for a hackathon |
-| `hackathon_submit` | Submit a project to a hackathon |
-
-### Example Agent Usage
-
-Once configured, your AI agent can:
+## Configuration
 
-> "List my Loops House projects"
-> "Submit my project to the Shanghai hackathon"
-> "Help me brainstorm ideas for the upcoming hackathon"
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `LOOPS_PLATFORM_URL` | `https://loops-platform.vercel.app` | Platform API origin |
+| `LOOPS_SUPABASE_URL` | (baked) | Supabase project URL |
+| `LOOPS_SUPABASE_ANON_KEY` | (baked) | Supabase anon key |
 
-The agent calls the MCP tools automatically — no manual CLI commands needed.
+Point these at `http://localhost:3000` + your local Supabase to develop against
+a local stack.
 
-## Environment Variables
+## Develop
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOOPS_PLATFORM_URL` | `https://loops.house` | Override the platform API URL (for local dev) |
-
-## Development
-
-```bash
-# Clone and install
-cd skill && bun install
-
-# Run in dev mode
-bun run dev -- auth status
-
-# Build for npm
-bun run build
-
-# Test compiled output
-node dist/loops.js --help
+```sh
+bun install
+bun run bin/loops.ts <args>   # run from source
+bun run build                 # bundle to dist/loops.js
+bun run typecheck             # tsc --noEmit
 ```
-
-## License
-
-MIT

package/SKILL.md

@@ -1,158 +1,143 @@
 ---
 name: loops-cli
-description: Loops House CLI for managing hackathon projects, browsing hackathons, AI-powered ideation, and submission — from the terminal or as an AI agent tool. Use when building projects for hackathons, submitting to hackathons, ideating project ideas, or managing Loops House projects programmatically. Triggers on "loops", "hackathon", "submit project", "ideate", "Loops House".
+description: >-
+  Loops House CLI for hackathon builders. Use to authenticate (GitHub, Google,
+  or email one-time code), browse hackathons, brainstorm project ideas with the
+  AI mentor, query sponsor knowledge graphs (graph-RAG), manage ideation
+  artifacts, create/update/submit projects, evaluate a project against a
+  sponsor, and check agent credits. Triggers on "loops", "loops house",
+  "hackathon submit", "ideate a project", "sponsor knowledge graph".
+requires_bin: loops
 ---
 
 # Loops House CLI
 
-Manage the full hackathon builder lifecycle from terminal or AI agent.
+`loops` is a typed CLI (built with [incur](https://github.com/nichochar/incur)) that
+doubles as an MCP server and an agent skill. One binary, three surfaces:
 
-## Prerequisites
+- **CLI** — `loops <group> <command>`
+- **MCP** — `loops --mcp` (stdio) or `loops mcp add` to register with your agent
+- **Skill** — this file; regenerate with `loops skills add`
 
-```bash
-# No install needed — use npx:
-npx loopshouse auth login
+All data commands talk to the Loops platform over HTTPS using a Supabase access
+token stored at `~/.loops/credentials.json`. Auth is required before any data
+command.
 
-# Or install globally:
-npm i -g loopshouse
-loops auth login
+> **Per-hackathon skill**: `npx loopshouse add <hackathonSlug>` (the
+> playground's "Use the skill" tab gives you the exact command) installs a
+> templated skill with the event's data and every sponsor's knowledge-graph
+> command already filled in, into Claude Code and `.agents`-standard agents.
+> Prefer that when working on one specific hackathon; re-run it to refresh.
 
-# For local dev, override the platform URL:
-export LOOPS_PLATFORM_URL="http://localhost:3000"
-```
+## Authenticate first
 
-## Authentication
+ALWAYS check `loops auth status` before starting work or a new session — never
+assume a stored session exists.
 
-```bash
-loops auth login          # Browser OAuth (Google/GitHub) → saves to ~/.loops/credentials.json
-loops auth status         # Check current session
-loops auth logout         # Clear stored credentials
+```sh
+loops auth status                        # who am I? — run this FIRST
+loops auth login --provider github      # browser OAuth (also: --provider google)
+loops auth login --email you@example.com   # email one-time code…
+loops auth verify --email you@example.com --code 123456   # …then verify it
+loops auth logout                        # clear credentials
 ```
 
-All commands below require authentication.
+- Browser OAuth opens a tab and captures the callback on `localhost:54321`
+  (override with `--port`). In headless/agent contexts the auth URL is printed
+  so a human can open it.
+- Email OTP: `auth login --email` sends a code. In an interactive terminal it
+  prompts for the code inline; in agent/pipe contexts it returns a CTA to run
+  `auth verify --email <e> --code <code>`.
 
-## Core Workflow
+## Credits
 
-### 1. Browse open hackathons
+Agent usage is metered per (user, hackathon): **1 credit = one ideator turn or
+one knowledge-graph query**. Everything else (project/artifact CRUD, the
+evaluator prompt) is free.
 
-```bash
-loops hackathon list              # Shows building + upcoming hackathons only
-loops hackathon list --all        # Include judging/completed/finalized
+```sh
+loops credits --hackathonSlug <hackathonSlug>        # { used, cap, remaining }
 ```
 
-Output includes: id, name, theme, phase, problem_statements, dates.
-
-### 2. Create or update a project
-
-```bash
-# Create (minimal)
-loops project create --name "My DApp" --description "On-chain analytics"
-
-# Create (full)
-loops project create \
-  --name "My DApp" \
-  --description "On-chain analytics dashboard" \
-  --tagline "Real-time DeFi insights" \
-  --category "DeFi" \
-  --githubUrl https://github.com/user/repo \
-  --youtubeUrl https://youtube.com/watch?v=demo \
-  --websiteUrl https://mydapp.xyz \
-  --logoUrl https://mydapp.xyz/logo.png \
-  --techStack "React,Solidity,The Graph,IPFS" \
-  --keyFeatures "On-chain analytics,Real-time alerts,Portfolio tracking" \
-  --screenshotUrls "https://i.imgur.com/a.png,https://i.imgur.com/b.png" \
-  --additionalLinks '[{"label":"Docs","url":"https://docs.mydapp.xyz"}]' \
-  --socialLinks '[{"label":"Twitter","url":"https://twitter.com/mydapp"}]'
-
-# Update
-loops project update --id <project-id> --description "Updated desc" --techStack "React,Rust,WASM"
-
-# List your projects
-loops project list
-```
+On a `credits_exhausted` error, stop and tell the user — don't retry.
+
+## Ideation (stateful sessions)
 
-**Create/Update fields:**
-
-| Flag | Description | Format |
-|------|-------------|--------|
-| `--name` | Project name | string |
-| `--description` | Full description | string |
-| `--tagline` | Short tagline | string |
-| `--category` | Category (DeFi, NFT, DAO, etc.) | string |
-| `--githubUrl` | GitHub repo URL | URL |
-| `--youtubeUrl` | YouTube demo URL | URL |
-| `--websiteUrl` | Project website | URL |
-| `--logoUrl` | Logo image URL | URL |
-| `--techStack` | Tech stack | comma-separated |
-| `--keyFeatures` | Key features | comma-separated |
-| `--screenshotUrls` | Screenshot URLs | comma-separated |
-| `--additionalLinks` | Extra links | JSON `[{label,url}]` |
-| `--socialLinks` | Social links | JSON `[{label,url}]` |
-| `--teamId` | Team ID (create only) | UUID |
-| `--hackathonId` | Hackathon ID (create only) | UUID |
-
-### 3. Ideate with AI mentor
-
-Brainstorm project ideas for a specific hackathon. The AI mentor knows the hackathon's problem statements, theme, and sponsor tracks. Pass `--projectId` to include your project details for contextual feedback on alignment and progress.
-
-```bash
-# General ideation
-loops hackathon ideate \
-  --hackathonId <hackathon-id> \
-  --message "I want to build something with AI and blockchain"
-
-# Ideation with project context (recommended)
-loops hackathon ideate \
-  --hackathonId <hackathon-id> \
-  --projectId <project-id> \
-  --message "How does my project align with this hackathon?"
+Ideator conversations are stored locally per hackathon
+(`~/.loops/sessions/<slug>.json`) and continue automatically — each `ideate`
+call just sends one more message in that hackathon's session.
+
+```sh
+loops hackathon ideate --hackathonSlug <slug> -m "idea using sponsor X"   # AI mentor (1 credit/turn)
+loops hackathon ideate --hackathonSlug <slug> -m "go deeper on idea 2"    # continues the same conversation
+loops hackathon ideate --hackathonSlug <slug> --withProject -m "how do I better target bounty Y?"
+loops hackathon ideate --hackathonSlug <slug> --new -m "fresh start"      # discard the session first
+loops hackathon session --hackathonSlug <slug>            # show the stored conversation
+loops hackathon session --hackathonSlug <slug> --clear    # delete it
+loops hackathon submit --hackathonSlug <slug> --name "My Project" --repoUrl <url>
 ```
 
-For multi-turn conversations, pass prior history as JSON:
+- `--withProject` inlines your project record so the mentor gives
+  project-aware feedback. No id needed — you have at most one project per
+  hackathon (team membership counts), so the platform resolves yours.
+
+## Sponsor knowledge graphs (graph-RAG)
+
+Each sponsor has a knowledge graph built from their docs, SDKs, and bounty
+materials. A query returns a **cited evidence block** (entities, relationships,
+chunks, sources) — you compose the answer yourself from it. 1 credit per query.
 
-```bash
-loops hackathon ideate \
-  --hackathonId <id> \
-  --projectId <project-id> \
-  --message "What about a decentralized identity solution?" \
-  --history '[{"role":"user","content":"I want to build with AI"},{"role":"assistant","content":"Great! Consider..."}]'
+```sh
+loops knowledge query --hackathonSlug <slug> -s <sponsorSlug> -q "How do I authenticate with the SDK?"
+loops knowledge query --hackathonSlug <slug> -s <sponsorSlug> -q "…" --mode local   # entity-centric
 ```
 
-### 4. Submit to hackathon
+## Your project (a project is the submission)
 
-```bash
-loops hackathon submit \
-  --hackathonId <hackathon-id> \
-  --projectId <project-id>
+Everything is scoped to ONE hackathon — you have at most one project per
+hackathon (team membership counts), there is no cross-hackathon listing, and
+no command needs a project id: the platform resolves yours from the session.
+
+```sh
+loops project get --hackathonSlug <slug>                 # your project (exists=false if none)
+loops project create --hackathonSlug <slug> --name "My Project" --bountyIds id1 --bountyIds id2
+loops project update --hackathonSlug <slug> --tagline "New tagline"
 ```
 
-Phase-gated: only works during the `building` phase (between start_date and submission_deadline). Team ID is auto-resolved from the project.
+**Update is a PATCH** — only the fields you pass change; omitted fields
+(including bounty picks and custom answers) keep their current values.
+
+## Ideation artifacts (scratchpad)
+
+Persist ideas/problems/tech-stack notes per hackathon; they appear in the web
+playground too. Kinds: `idea`, `problem`, `tech-stack`, `note`.
 
-## MCP Mode
+```sh
+loops artifact list --hackathonSlug <slug>
+loops artifact save --hackathonSlug <slug> --name "Title" --kind idea --body "Markdown…"
+loops artifact update --hackathonSlug <slug> --id <artifactId> --body "Updated…"
+loops artifact remove --hackathonSlug <slug> --id <artifactId>
+```
+
+## Evaluate a project against a sponsor
 
-Register as an MCP server for AI agent integration:
+Fetches a self-contained evaluator prompt (free): the sponsor's judging
+criteria, bounties, and hackathon context plus step-by-step instructions.
+Your project record is included automatically when you have one.
+**Execute the returned prompt yourself inside the project repo** — it assumes
+code access and produces alignment feedback (strengths, gaps, where to focus),
+never scores.
 
-```bash
-loops mcp add
-loops --mcp    # Start as MCP stdio server
+```sh
+loops evaluate --hackathonSlug <slug> -s <sponsorSlug>
 ```
 
-## Aliases
-
-| Long flag | Short |
-|-----------|-------|
-| `--name` | `-n` |
-| `--description` | `-d` |
-| `--githubUrl` | `-g` |
-| `--hackathonId` | `-h` |
-| `--projectId` | `-p` |
-| `--message` | `-m` |
-| `--teamId` | `-t` |
-| `--id` (update) | `-i` |
-
-## Architecture
-
-- **Auth**: Supabase PKCE OAuth flow, tokens stored at `~/.loops/credentials.json`, auto-refreshed on use
-- **Data commands** (list, create, update, submit): Direct Supabase client queries with user RLS context
-- **AI commands** (ideate): Call platform API route (`/api/builder-agents/project-ideator`) with Bearer token auth, optionally including project snapshot for contextual feedback
-- **Framework**: Built with [incur](https://github.com/nichochar/incur) — typed CLI + MCP + skill generation
+## Notes for agents
+
+- Every command returns a structured envelope; pass `--json` for machine output.
+- Success outputs often end with a suggested next command (CTA) — prefer
+  following it over guessing the next step.
+- On `NOT_AUTHENTICATED`, run `loops auth login` (or `--email`) before retrying.
+- `loops --llms` prints the full machine-readable command manifest.
+- Configure the target stack with env vars: `LOOPS_PLATFORM_URL`,
+  `LOOPS_SUPABASE_URL`, `LOOPS_SUPABASE_ANON_KEY`.