emberflow-skills 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# Emberflow Skills
+
+Agent skills for publishing beautiful docs from your AI coding tools to [Emberflow](https://supportive-forgiveness-production.up.railway.app).
+
+## Quick Install
+
+```bash
+npx emberflow-skills
+```
+
+Auto-detects Claude Code and Cursor projects and installs the skill to the right place.
+
+```bash
+# Install globally for Claude Code (available in all projects)
+npx emberflow-skills --global
+```
+
+## Available Skills
+
+### `ember-publish`
+
+Publish markdown documents with Mermaid diagrams, syntax highlighting, tables, and inline comments.
+
+**Usage:** `/ember-publish architecture overview for the payments service`
+
+Your AI writes the doc, generates diagrams, and publishes it — you get back a shareable URL.
+
+**Works with:** Claude Code, Cursor, Codex CLI, and any tool that supports the SKILL.md format.
+
+## What Emberflow renders
+
+- Live Mermaid diagrams with zoom, pan, and fullscreen
+- Syntax-highlighted code blocks (190+ languages)
+- Auto-generated table of contents
+- Per-block inline comments and discussions
+- Dark mode with font selection
+
+## Manual Installation
+
+If you prefer not to use npx:
+
+```bash
+# Clone and copy
+git clone https://github.com/toptalPatrick/emberflow-skills.git
+cp -r emberflow-skills/skills/ember-publish .claude/skills/
+```

package/bin/install.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_NAME = 'ember-publish';
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME, 'SKILL.md');
+
+const targets = [
+  { dir: '.claude/skills', label: 'Claude Code (project)' },
+  { dir: '.cursor/skills', label: 'Cursor (project)' },
+];
+
+const globalTargets = [
+  { dir: path.join(require('os').homedir(), '.claude', 'skills'), label: 'Claude Code (global)' },
+];
+
+const args = process.argv.slice(2);
+const isGlobal = args.includes('--global') || args.includes('-g');
+
+function install(destDir, label) {
+  const skillDir = path.join(destDir, SKILL_NAME);
+  const destFile = path.join(skillDir, 'SKILL.md');
+
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(SKILL_SRC, destFile);
+  console.log(`  \x1b[32m✓\x1b[0m Installed to ${path.relative(process.cwd(), skillDir) || skillDir} \x1b[2m(${label})\x1b[0m`);
+  return true;
+}
+
+console.log();
+console.log('  \x1b[1mEmberflow Skills Installer\x1b[0m');
+console.log();
+
+let installed = 0;
+
+if (isGlobal) {
+  for (const t of globalTargets) {
+    install(t.dir, t.label);
+    installed++;
+  }
+} else {
+  // Auto-detect which tool directories exist or can be created
+  const cwd = process.cwd();
+  const detected = [];
+
+  for (const t of targets) {
+    const parent = path.dirname(path.join(cwd, t.dir));
+    // Install if parent config dir exists (e.g. .claude/ or .cursor/) or if neither exists (default to .claude)
+    if (fs.existsSync(path.join(cwd, t.dir)) || fs.existsSync(parent)) {
+      detected.push(t);
+    }
+  }
+
+  // Default to Claude Code if nothing detected
+  if (detected.length === 0) {
+    detected.push(targets[0]);
+  }
+
+  for (const t of detected) {
+    install(path.join(cwd, t.dir), t.label);
+    installed++;
+  }
+}
+
+if (installed > 0) {
+  console.log();
+  console.log(`  Use: \x1b[36m/ember-publish\x1b[0m \x1b[2m[topic]\x1b[0m`);
+  console.log();
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "emberflow-skills",
+  "version": "1.0.0",
+  "description": "Install Emberflow skills for AI coding tools",
+  "bin": {
+    "emberflow-skills": "./bin/install.js"
+  },
+  "keywords": ["emberflow", "claude-code", "cursor", "skill", "mcp", "ai", "documentation", "mermaid"],
+  "author": "Patrick",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toptalPatrick/emberflow-skills"
+  }
+}

package/skills/ember-publish/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ember-publish
+description: Create a markdown document with Mermaid diagrams and publish it to Emberflow for hosted viewing with comments
+argument-hint: [topic or description of what to document]
+---
+
+# Emberflow Document Publisher
+
+Create a polished markdown document and publish it to Emberflow — a hosted viewer at **https://supportive-forgiveness-production.up.railway.app** with Mermaid diagram rendering (zoom/pan/fullscreen), dark mode, font selection, and per-block commenting.
+
+## Step 1: Create the Markdown File
+
+Write a `.md` file in the current project. The document should follow these conventions:
+
+### Structure
+- Start with a single `# Title` as the first line (this becomes the document title and slug)
+- Use `##` and `###` for sections — these become commentable blocks in the viewer
+- Keep paragraphs concise — each paragraph, list, table, blockquote, and heading is independently commentable by readers
+
+### Mermaid Diagrams
+
+Use fenced code blocks with the `mermaid` language tag. The viewer renders them with zoom, pan, and fullscreen controls.
+
+````markdown
+```mermaid
+graph LR
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[Other Action]
+```
+````
+
+Supported diagram types:
+- `graph` / `flowchart` — flow diagrams (LR, TD, etc.)
+- `sequenceDiagram` — interaction sequences
+- `classDiagram` — class relationships
+- `stateDiagram-v2` — state machines
+- `erDiagram` — entity relationships
+- `gantt` — project timelines
+- `pie` — pie charts
+- `gitgraph` — git branch visualizations
+- `mindmap` — mind maps
+- `timeline` — chronological events
+
+#### Dark Mode Color Palette
+
+The viewer auto-remaps these light colors to dark equivalents. Use them for best cross-theme rendering:
+
+| Color | Use For |
+|---|---|
+| `#e1f5fe` | Blue backgrounds |
+| `#e8f5e9` | Green backgrounds |
+| `#fff3e0` | Orange backgrounds |
+| `#fce4ec` | Red backgrounds |
+| `#f3e5f5` | Purple backgrounds |
+| `#fff9c4` | Yellow backgrounds |
+
+### Tables, Code, Blockquotes
+
+Standard GFM (GitHub Flavored Markdown) is fully supported:
+
+```markdown
+| Column A | Column B |
+|----------|----------|
+| value    | value    |
+
+> Blockquotes render with a blue left border
+
+`inline code` and fenced code blocks with syntax highlighting
+```
+
+### Example Document
+
+````markdown
+# API Architecture Overview
+
+Brief introduction to the system.
+
+## Components
+
+```mermaid
+graph TD
+    Client[Web Client] --> API[API Gateway]
+    API --> Auth[Auth Service]
+    API --> Docs[Doc Service]
+    Docs --> DB[(PostgreSQL)]
+```
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant G as Gateway
+    participant S as Service
+    C->>G: Request
+    G->>S: Forward
+    S->>G: Response
+    G->>C: Response
+```
+
+## Data Model
+
+| Entity | Purpose |
+|--------|---------|
+| Users | Account management |
+| Documents | Published content |
+| Comments | Discussion threads |
+
+## Design Notes
+
+> We chose event sourcing to maintain a complete audit trail of all state changes.
+````
+
+## Step 2: Authenticate (if needed)
+
+Session tokens are stored at `~/.emberflow/token.json`. Check if a valid session exists:
+
+```bash
+cat ~/.emberflow/token.json 2>/dev/null
+```
+
+If the file exists, verify the token still works:
+
+```bash
+curl -s -H "Authorization: Bearer $(jq -r .token ~/.emberflow/token.json)" \
+  https://supportive-forgiveness-production.up.railway.app/api/docs
+```
+
+If no session exists, it's expired, or the verify call returns 401, authenticate using the device flow:
+
+```bash
+EMBERFLOW_URL="https://supportive-forgiveness-production.up.railway.app"
+
+# Step 1: Request a device code
+RESP=$(curl -s -X POST "$EMBERFLOW_URL/api/device-code")
+CODE=$(echo "$RESP" | jq -r .code)
+URL=$(echo "$RESP" | jq -r .verification_url)
+```
+
+Tell the user to open the URL in their browser to sign in and approve the device. Then poll until approved:
+
+```bash
+# Step 2: Poll until approved (every 3s)
+while true; do
+  STATUS=$(curl -s "$EMBERFLOW_URL/api/device-code/$CODE")
+  S=$(echo "$STATUS" | jq -r .status)
+  if [ "$S" = "approved" ]; then
+    TOKEN=$(echo "$STATUS" | jq -r .session_token)
+    mkdir -p ~/.emberflow
+    echo "{\"token\":\"$TOKEN\"}" > ~/.emberflow/token.json
+    break
+  fi
+  if [ "$S" = "expired" ]; then
+    echo "Code expired. Please try again."
+    break
+  fi
+  sleep 3
+done
+```
+
+## Step 3: Publish
+
+Generate a slug from the document title and publish using the API:
+
+```bash
+# Read the file, extract title, generate slug, and publish
+EMBERFLOW_URL="https://supportive-forgiveness-production.up.railway.app"
+FILE_PATH="/absolute/path/to/document.md"
+TITLE=$(head -1 "$FILE_PATH" | sed 's/^#\s*//')
+SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
+TOKEN=$(jq -r .token ~/.emberflow/token.json)
+
+curl -s -X POST "$EMBERFLOW_URL/api/docs" \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $TOKEN" \
+  -d "$(jq -n --arg slug "$SLUG" --arg title "$TITLE" --rawfile content "$FILE_PATH" \
+    '{slug: $slug, title: $title, content: $content, visibility: "public"}')"
+```
+
+The response JSON includes the URL. Documents are viewable at:
+- Public: `https://supportive-forgiveness-production.up.railway.app/d/<shortId>/<slug>`
+
+To **update** an existing document, publish again with the same slug — the API upserts for the same author.
+
+### Other Operations
+
+```bash
+# List all your documents
+curl -s -H "Authorization: Bearer $TOKEN" "$EMBERFLOW_URL/api/docs"
+
+# Delete a document
+curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$EMBERFLOW_URL/api/docs/<shortId>/<slug>"
+```