Merge pull request #30 from willwearing/feat/cli-agent-platform

feat: CLI, MCP server, Stripe Connect — agent-first course creation platform

Author: willwearing

.github/workflows/publish-packages.yml

@@ -0,0 +1,113 @@
+name: Publish Packages to npm
+
+on:
+  # Manual trigger with package selection
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Package to publish (all, shared, cli, mcp)'
+        required: true
+        default: 'all'
+        type: choice
+        options:
+          - all
+          - shared
+          - cli
+          - mcp
+      dry_run:
+        description: 'Dry run (no actual publish)'
+        required: false
+        default: false
+        type: boolean
+
+  # Auto-publish on version tags
+  push:
+    tags:
+      - 'v*'           # Publish all packages on v* tags
+      - 'cli@*'        # Publish CLI only
+      - 'mcp@*'        # Publish MCP only
+      - 'shared@*'     # Publish shared only
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Determine which packages to publish
+        id: packages
+        run: |
+          TAG="${GITHUB_REF_NAME:-}"
+          INPUT="${{ github.event.inputs.package }}"
+
+          # Default to input if workflow_dispatch, otherwise parse tag
+          if [ -n "$INPUT" ]; then
+            echo "target=$INPUT" >> "$GITHUB_OUTPUT"
+          elif [[ "$TAG" == v* ]]; then
+            echo "target=all" >> "$GITHUB_OUTPUT"
+          elif [[ "$TAG" == cli@* ]]; then
+            echo "target=cli" >> "$GITHUB_OUTPUT"
+          elif [[ "$TAG" == mcp@* ]]; then
+            echo "target=mcp" >> "$GITHUB_OUTPUT"
+          elif [[ "$TAG" == shared@* ]]; then
+            echo "target=shared" >> "$GITHUB_OUTPUT"
+          else
+            echo "target=all" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build shared package
+        if: steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'shared' || steps.packages.outputs.target == 'cli' || steps.packages.outputs.target == 'mcp'
+        run: cd packages/shared && bun run build
+
+      - name: Build CLI package
+        if: steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'cli'
+        run: cd packages/cli && bun run build
+
+      - name: Build MCP package
+        if: steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'mcp'
+        run: cd packages/mcp && bun run build
+
+      # Publish shared first (cli and mcp depend on it)
+      - name: Publish @graspful/shared
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'shared') && github.event.inputs.dry_run != 'true'
+        run: cd packages/shared && bun publish --access public
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @graspful/cli
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'cli') && github.event.inputs.dry_run != 'true'
+        run: cd packages/cli && bun publish --access public
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish @graspful/mcp
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'mcp') && github.event.inputs.dry_run != 'true'
+        run: cd packages/mcp && bun publish --access public
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Dry run mode — show what would be published
+      - name: Dry run — @graspful/shared
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'shared') && github.event.inputs.dry_run == 'true'
+        run: cd packages/shared && bun publish --access public --dry-run
+
+      - name: Dry run — @graspful/cli
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'cli') && github.event.inputs.dry_run == 'true'
+        run: cd packages/cli && bun publish --access public --dry-run
+
+      - name: Dry run — @graspful/mcp
+        if: (steps.packages.outputs.target == 'all' || steps.packages.outputs.target == 'mcp') && github.event.inputs.dry_run == 'true'
+        run: cd packages/mcp && bun publish --access public --dry-run

README.md

@@ -1,64 +1,138 @@
-# Niche Audio Prep
+# Graspful
 
-White-labeled adaptive learning platform for professional certification exams. Audio instruction + mastery-based progression, powered by a knowledge graph.
+> Create adaptive learning courses with AI agents. Launch in minutes.
 
-## What This Is
+## What Is Graspful?
 
-Professionals in trades and regulated industries (firefighters, pilots, electricians, CDL drivers, real estate agents) need to memorize dense regulatory content to pass certification exams. They're on jobsites, in trucks, on shift -- they can't sit down and read a textbook.
+Graspful is an agent-first course creation platform. Courses are defined as YAML files with knowledge graphs, validated by schema, and imported via CLI or MCP server -- no UI clicking required. Agents (or humans) scaffold a course, fill in content concept by concept, run quality checks, and publish. The platform handles the rest: adaptive diagnostics, mastery-based progression, spaced repetition, white-label landing pages, and Stripe billing.
 
-This platform delivers that content via audio, then verifies understanding through active practice. One codebase serves every niche. Adding a new certification = content + config, not code.
+## How It Works
 
-## Guiding Principles
+1. **Scaffold** -- `graspful create course --topic "CKA Exam"` generates the knowledge graph skeleton
+2. **Fill** -- `graspful fill concept course.yaml networking` adds KPs and practice problems
+3. **Review** -- `graspful review course.yaml` runs 10 quality checks
+4. **Import** -- `graspful import course.yaml --org k8s-cert --publish` goes live
+5. **Brand** -- `graspful create brand --niche "Kubernetes"` generates the landing page
 
-### 1. Identify what the student already knows
-An adaptive diagnostic maps existing knowledge in 20-60 questions. No wasting time on material already mastered.
+Two YAMLs (course + brand) produce one live product with adaptive learning, spaced repetition, and Stripe billing.
 
-### 2. Build a personal knowledge profile on a knowledge graph
-Every course is a directed graph of concepts connected by prerequisite and encompassing edges. The student's diagnostic results overlay onto this graph, producing a personal map of what's known, partially known, and unknown.
+## Quick Start
 
-### 3. Teach only at the knowledge frontier
-The frontier is the boundary between known and unknown. The system teaches only concepts whose prerequisites are fully mastered. Every minute of study time is spent on exactly the right thing.
+```bash
+npx @graspful/cli init
+```
 
-### 4. Minimum effective dose of instruction + active practice
-Each lesson cycles: short audio explanation, worked example, 2-3 practice problems. Students spend most of their time solving problems, not passively listening.
+Or install globally:
 
-### 5. Enforce mastery relentlessly
-Can't consistently solve problems? You don't advance. The system routes you to parallel learning paths, identifies the specific weak prerequisite, remediates it, then brings you back.
+```bash
+bun add -g @graspful/cli
+graspful login
+graspful create course --scaffold-only --topic "Your Topic" -o course.yaml
+```
 
-### 6. Spaced repetition + broad-coverage quizzes
-Previously learned material decays. The system schedules reviews on an exponential spacing schedule and runs periodic timed quizzes across recent material.
+## Tech Stack
 
-### 7. Review old stuff by learning new stuff
-The key efficiency innovation. Advanced concepts implicitly practice their prerequisites as subskills. The system tracks this implicit repetition and credits it against the review schedule -- dramatically reducing explicit review burden. You advance by reviewing, not by going backwards.
+- **Backend:** NestJS, Prisma, PostgreSQL (Supabase-hosted)
+- **Frontend:** Next.js (App Router), React, Tailwind CSS, shadcn/ui
+- **CLI:** `@graspful/cli` (commander.js)
+- **MCP Server:** `@graspful/mcp` for AI agent integration
+- **Auth:** Supabase Auth (JWT) + API keys for agents
+- **Billing:** Stripe + Stripe Connect (70/30 revenue share)
+- **Monorepo:** Turborepo, bun
 
 ## Architecture
 
-- **Frontend:** Next.js 15, shadcn/ui, Tailwind -- single Vercel deployment, custom domains per niche, mobile-responsive
-- **Backend:** NestJS (TypeScript), Prisma, Supabase -- DDD bounded contexts
-- **Audio:** Kokoro TTS on Modal -- batch pre-generation
-- **Adaptive Learning:** Knowledge graph + FIRe spaced repetition + mastery enforcement
-- **Billing:** Stripe
-- **Mobile:** Deferred (see [mobile-plan.md](docs/mobile-plan.md))
+```
+graspful/
+├── apps/web/          # Next.js frontend
+├── backend/           # NestJS API
+├── packages/
+│   ├── shared/        # Zod schemas, types, quality gate
+│   ├── cli/           # @graspful/cli
+│   └── mcp/           # @graspful/mcp server
+├── content/
+│   ├── courses/       # Course YAML files
+│   ├── brands/        # Brand YAML files
+│   └── academies/     # Multi-course academy manifests
+└── docs/              # Documentation
+```
 
-## Docs
+## CLI Commands
 
-| Document | What It Covers |
-|----------|---------------|
-| [PLAN.md](docs/PLAN.md) | Master plan, architecture overview, 13-phase execution roadmap |
-| [adaptive-learning-architecture.md](docs/adaptive-learning-architecture.md) | Full adaptive learning system design -- knowledge graph, FIRe algorithm, diagnostic, mastery, DDD contexts, data model, API |
-| [backend-plan.md](docs/backend-plan.md) | NestJS backend architecture, Prisma schema, API design, content pipeline |
-| [frontend-plan.md](docs/frontend-plan.md) | Next.js frontend, white-label theming, audio player, 25 tasks |
-| [white-label-architecture-research.md](docs/white-label-architecture-research.md) | 4 approaches to white-labeling, recommendation |
-| [market-research.md](market-research.md) | 18+ niche markets analyzed, tier rankings |
-| [mobile-plan.md](docs/mobile-plan.md) | React Native (Expo), offline audio, background playback, 25 tasks (Deferred) |
+| Command | Description |
+|---------|-------------|
+| `graspful create course` | Generate course YAML skeleton |
+| `graspful create brand` | Generate brand YAML with theme presets |
+| `graspful fill concept` | Add KPs and problems to a concept |
+| `graspful validate` | Offline schema + DAG validation |
+| `graspful review` | 10 mechanical quality checks |
+| `graspful describe` | Course statistics |
+| `graspful import` | Push YAML to Graspful instance |
+| `graspful publish` | Publish a draft course |
+| `graspful login` | Authenticate |
 
-## Development Workflow
+## MCP Server
 
-- Each phase is executed by a separate Claude Code agent
-- Workflow: `/writing-plans` to create detailed specs, then `/subagent-driven-development` or `/executing-plans` to build
-- All phases use TDD with two-stage review
-- Status tracked per phase in [PLAN.md](docs/PLAN.md)
+For AI agent integration (Claude Code, Cursor, Codex):
 
-## Inspired By
+```bash
+npx @graspful/cli init  # Auto-configures MCP for your editor
+```
 
-The adaptive learning system is heavily inspired by [Math Academy](https://mathacademy.com) and Justin Skycak's published research on knowledge graphs, mastery-based learning, and the Fractional Implicit Repetition (FIRe) algorithm. See the [adaptive learning doc](docs/adaptive-learning-architecture.md#16-key-sources--further-reading) for all sources.
+Or manually add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "graspful": {
+      "command": "npx",
+      "args": ["@graspful/mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Start development servers
+bun run dev
+
+# Backend (port 3000)
+cd backend && bun run dev
+
+# Frontend (port 3001)
+cd apps/web && bun run dev
+
+# Build
+bun run build
+
+# Test
+bun run test
+
+# E2E tests
+cd apps/web && npx playwright test
+```
+
+## Revenue Model
+
+70/30 revenue share (Apple model):
+
+- Free to create and publish courses
+- When learners subscribe, Graspful collects payment
+- Graspful keeps 30%, creator receives 70% via Stripe Connect
+- No upfront cost, no monthly platform fee
+
+## Documentation
+
+- [Adding a Course](docs/adding-a-course.md) -- Step-by-step course creation guide
+- [Course Review Gate](docs/course-review-gate.md) -- Quality checks and review specification
+- [CLI Agent Strategy](docs/cli-agent-strategy.md) -- Full platform strategy and architecture
+- [Content Guide](content/README.md) -- YAML schema reference and authoring guidelines
+
+## License
+
+Private

apps/web/e2e/agents-page.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("Agents Page", () => {
+  test("agents page loads with hero heading", async ({ page }) => {
+    await page.goto("/agents");
+    const heading = page.getByRole("heading", { level: 1 });
+    await expect(heading).toBeVisible({ timeout: 10_000 });
+    await expect(heading).toContainText("agent", { ignoreCase: true });
+  });
+
+  test("agents page has MCP tools section", async ({ page }) => {
+    await page.goto("/agents");
+    await expect(page.getByText("MCP Tools")).toBeVisible();
+
+    // Verify specific tool names are rendered
+    await expect(page.getByText("create_course")).toBeVisible();
+    await expect(page.getByText("fill_concept")).toBeVisible();
+    await expect(page.getByText("review_course")).toBeVisible();
+    await expect(page.getByText("validate_course")).toBeVisible();
+    await expect(page.getByText("import_course")).toBeVisible();
+    await expect(page.getByText("create_brand")).toBeVisible();
+  });
+
+  test("agents page shows supported agents", async ({ page }) => {
+    await page.goto("/agents");
+    await expect(page.getByText("Works with your tools")).toBeVisible();
+    await expect(page.getByText("Claude Code")).toBeVisible();
+    await expect(page.getByText("Cursor")).toBeVisible();
+  });
+
+  test("agents page has workflow section", async ({ page }) => {
+    await page.goto("/agents");
+    await expect(page.getByText("Two YAMLs. One product.")).toBeVisible();
+    await expect(page.getByText("Course YAML")).toBeVisible();
+    await expect(page.getByText("Brand YAML")).toBeVisible();
+    await expect(page.getByText("Import & Launch")).toBeVisible();
+  });
+
+  test("agents page has pricing section", async ({ page }) => {
+    await page.goto("/agents");
+    await expect(page.getByText("70 / 30")).toBeVisible();
+    await expect(
+      page.getByText("Revenue share when learners pay", { exact: false })
+    ).toBeVisible();
+  });
+
+  test("agents page has CTA with CLI init command", async ({ page }) => {
+    await page.goto("/agents");
+    const cliCommand = page.getByText("npx @graspful/cli init");
+    // Should appear in both hero and bottom CTA
+    const count = await cliCommand.count();
+    expect(count).toBeGreaterThanOrEqual(2);
+  });
+
+  test("agents page has sign-up links", async ({ page }) => {
+    await page.goto("/agents");
+    const signUpLinks = page.getByRole("link", { name: /get started/i });
+    await expect(signUpLinks.first()).toBeVisible();
+    await expect(signUpLinks.first()).toHaveAttribute("href", "/sign-up");
+  });
+});