feat: academy-first CLI/MCP workflow and stronger quality gate (#114)

* feat: academy-first CLI/MCP workflow and stronger quality gate

Most agent-authored courses should start as an academy — a connected
curriculum of one or more courses — not a single course file. This makes
that the default path across CLI, MCP, backend auth, and the runbook.

- Add `graspful create academy` CLI command and `graspful_create_academy`
  MCP tool backed by shared `scaffoldAcademyObject`.
- Add `graspful_import_academy` MCP tool and `graspful import` support
  for academy manifests with `--course-dir` resolution and per-course
  publish.
- Allow API-key auth on `/orgs/:orgId/academies` by swapping
  `SupabaseAuthGuard` for `JwtOrApiKeyGuard` so the CLI can import
  academies without a browser session.
- Replace the weak `cross_concept_coverage` quality check with
  `problem_teaching_alignment`: problems must reference material
  introduced in the current KP, earlier KPs, or prerequisite concepts.
- Add advisory `kp_atomicity` warning that flags KP instructions with
  long parallel lists (6+ items) as likely teaching multiple facts.
- Surface warnings in `graspful review` output and analytics.
- Bump default KP stub count from 2 to 3 and teach the brand scaffold
  to take an optional `--topic` for specific landing copy.
- Optimistic quiz and section-exam UI: advance on submit via
  `startTransition`, show a "Saving answer..." indicator, and roll back
  on failure. Covered by new Vitest cases.
- Playwright config now builds the backend before starting it and
  raises the timeout to 120s so live e2e runs are reproducible.
- Add end-to-end Playwright spec that scaffolds, imports, and publishes
  an academy through the real CLI against a live backend.
- Refresh AGENTS.md, CLAUDE.md, README.md, docs/adding-a-course.md, and
  per-package READMEs so the academy-first workflow is canonical.
- Rewrite `posthog-use-case-selling.yaml` to pass the new teaching
  alignment and atomicity checks.
- Check in draft plan for the wrong-answer remediation loop.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: loosen teaching-alignment check to skip stubs and whole-KP drift

Harden checkProblemTeachingAlignment against false positives so a single
lexically drifted problem in an otherwise aligned KP no longer blocks the
review gate. Two changes:

- Skip the check when the teaching path has fewer than 8 distinct stems.
  Stub fixtures and in-progress drafts effectively have nothing to judge
  against and should not be punished by a content-quality gate.
- Only fail a KP when every judgable problem is off-topic. A drifted
  single problem is a content-author nit, not a gate violation.

Also extracts the alignment ignore list to a module-level constant for
clarity and updates tests to cover the new whole-KP-drift behavior plus
stub-fixture immunity.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: align e2e test course fixture with stricter teaching-alignment check

The publish-draft-course e2e test was failing because its minimal course
YAML had stub-style instruction and workedExample text that shared no
vocabulary with the problems. The new problem_teaching_alignment check
correctly flagged the KPs as content the instruction doesn't teach, so
publish returned passed=false.

Update the fixture so instruction and worked example actually teach the
material the problems test — arithmetic addition, Rayleigh scattering,
water chemistry (concept-alpha) and addition, Earth's orbit, chemical
symbols (concept-beta). This is the canonical fix: the fixture should
model a real well-authored course, not a content-quality workaround.

Also clean up a set of stale planning docs that were already removed in
the working tree.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: willwearing

AGENTS.md

@@ -41,12 +41,14 @@ If MCP is already configured, you have these tools available — no CLI needed:
 
 | Tool | Auth? | Description |
 |------|:---:|-------------|
+| `graspful_create_academy` | No | Generate academy manifest YAML |
 | `graspful_scaffold_course` | No | Generate course YAML skeleton |
 | `graspful_fill_concept` | No | Add KPs and problems to a concept |
 | `graspful_validate` | No | Validate YAML against schema |
-| `graspful_review_course` | No | Run 10 quality checks |
+| `graspful_review_course` | No | Run 10 quality checks, including teaching alignment |
 | `graspful_describe_course` | No | Course statistics |
 | `graspful_create_brand` | No | Generate brand YAML |
+| `graspful_import_academy` | **Yes** | Import academy manifest + course YAMLs (set `GRASPFUL_API_KEY` first) |
 | `graspful_import_course` | **Yes** | Import course to platform (set `GRASPFUL_API_KEY` first) |
 | `graspful_publish_course` | **Yes** | Publish a draft course (set `GRASPFUL_API_KEY` first) |
 | `graspful_import_brand` | **Yes** | Import brand config (set `GRASPFUL_API_KEY` first) |
@@ -73,38 +75,44 @@ The workflow is: scaffold -> fill -> validate -> review -> import.
 
 **Before writing any YAML**, follow the detailed runbook in `docs/adding-a-course.md`. Key steps:
 1. Gather source material (official docs, syllabi, PDFs — not marketing copy)
-2. Decide: single course or academy with multiple courses
-3. Build the prerequisite graph (roots -> trunk -> branches -> leaves)
-4. Write the YAML skeleton (graph first, content second)
-5. Fill concepts one at a time
-6. Validate and review
+2. Model it as an academy first, even if it starts with one course
+3. Decompose the academy into foundations -> structures -> operations -> applied judgment
+4. Build the prerequisite graph (roots -> trunk -> branches -> leaves)
+5. Write the YAML skeleton (graph first, content second)
+6. Spend a cycle on the academy landing page so the promise and proof are specific to the learner
+7. Fill concepts one at a time
+8. Validate and review
 
 ```bash
-# 1. Scaffold the knowledge graph
+# 1. Scaffold the academy shell
+graspful create academy --topic "Your Topic" -o academy.yaml
+
+# 2. Scaffold the first course knowledge graph
 graspful create course --topic "Your Topic" --hours 10 -o course.yaml
 
-# 2. Fill each concept with knowledge points and problems
+# 3. Fill each concept with knowledge points and problems
 graspful fill concept course.yaml <concept-id>
 
-# 3. Validate after every edit
+# 4. Validate after every edit
 graspful validate course.yaml
 
-# 4. Review — must score 10/10 to publish
+# 5. Review — must score 10/10 to publish
 graspful review course.yaml
 
-# 5. Import and publish
-graspful import course.yaml --org <org-slug> --publish
+# 6. Import and publish
+graspful import academy.yaml --org <org-slug> --course-dir . --publish
 ```
 
 Or with MCP tools:
 
 ```
+graspful_create_academy(topic: "Your Topic")
 graspful_scaffold_course(topic: "Your Topic", estimatedHours: 10)
 -> edit the YAML
 graspful_fill_concept(yaml: "...", conceptId: "concept-id")
 graspful_validate(yaml: "...")
 graspful_review_course(yaml: "...")
-graspful_import_course(yaml: "...", org: "org-slug", publish: true)
+graspful_import_academy(manifestYaml: "...", courseYamls: { "courses/course.yaml": "..." }, org: "org-slug", publish: true)
 ```
 
 ### Images, Videos, Links in Course Content
@@ -161,12 +169,18 @@ When building a course from a PDF or document:
 4. For visual content (photos, diagrams, comparisons), find or request publicly accessible image URLs and use `image` content blocks
 5. Do not copy-paste prose verbatim — rewrite for the lesson pattern (instruction -> worked example -> problems)
 
-### Step 4: Brand (optional)
+### Step 4: Brand and landing page
+
+Treat the landing page as part of the academy build:
+
+- the copy must describe the actual learner, outcome, and curriculum promise
+- the page should explain why this academy exists and why a learner should trust it
+- generic placeholder niche copy is not sufficient
 
 Create a white-label landing page and theme:
 
 ```bash
-graspful create brand --niche tech --name "My Academy" --org my-org -o brand.yaml
+graspful create brand --niche tech --topic "Your Topic" --name "My Academy" --org my-org -o brand.yaml
 graspful import brand.yaml
 ```
 

CLAUDE.md

@@ -40,12 +40,14 @@ If MCP is already configured, you have these tools available — no CLI needed:
 
 | Tool | Auth? | Description |
 |------|:---:|-------------|
+| `graspful_create_academy` | No | Generate academy manifest YAML |
 | `graspful_scaffold_course` | No | Generate course YAML skeleton |
 | `graspful_fill_concept` | No | Add KPs and problems to a concept |
 | `graspful_validate` | No | Validate YAML against schema |
-| `graspful_review_course` | No | Run 10 quality checks |
+| `graspful_review_course` | No | Run 10 quality checks, including teaching alignment |
 | `graspful_describe_course` | No | Course statistics |
 | `graspful_create_brand` | No | Generate brand YAML (required — every org needs a brand) |
+| `graspful_import_academy` | **Yes** | Import academy manifest + course YAMLs (set `GRASPFUL_API_KEY` first) |
 | `graspful_import_course` | **Yes** | Import course to platform (set `GRASPFUL_API_KEY` first) |
 | `graspful_publish_course` | **Yes** | Publish a draft course (set `GRASPFUL_API_KEY` first) |
 | `graspful_import_brand` | **Yes** | Import brand config — required for site to work (set `GRASPFUL_API_KEY` first) |
@@ -72,38 +74,44 @@ The workflow is: scaffold -> fill -> validate -> review -> import.
 
 **Before writing any YAML**, follow the detailed runbook in `docs/adding-a-course.md`. Key steps:
 1. Gather source material (official docs, syllabi, PDFs — not marketing copy)
-2. Decide: single course or academy with multiple courses
-3. Build the prerequisite graph (roots -> trunk -> branches -> leaves)
-4. Write the YAML skeleton (graph first, content second)
-5. Fill concepts one at a time
-6. Validate and review
+2. Model it as an academy first, even if it starts with one course
+3. Decompose the academy into foundations -> structures -> operations -> applied judgment
+4. Build the prerequisite graph (roots -> trunk -> branches -> leaves)
+5. Write the YAML skeleton (graph first, content second)
+6. Spend a cycle on the academy landing page so the promise and proof are specific to the learner
+7. Fill concepts one at a time
+8. Validate and review
 
 ```bash
-# 1. Scaffold the knowledge graph
+# 1. Scaffold the academy shell
+graspful create academy --topic "Your Topic" -o academy.yaml
+
+# 2. Scaffold the first course knowledge graph
 graspful create course --topic "Your Topic" --hours 10 -o course.yaml
 
-# 2. Fill each concept with knowledge points and problems
+# 3. Fill each concept with knowledge points and problems
 graspful fill concept course.yaml <concept-id>
 
-# 3. Validate after every edit
+# 4. Validate after every edit
 graspful validate course.yaml
 
-# 4. Review — must score 10/10 to publish
+# 5. Review — must score 10/10 to publish
 graspful review course.yaml
 
-# 5. Import and publish
-graspful import course.yaml --org <org-slug> --publish
+# 6. Import and publish
+graspful import academy.yaml --org <org-slug> --course-dir .
 ```
 
 Or with MCP tools:
 
 ```
+graspful_create_academy(topic: "Your Topic")
 graspful_scaffold_course(topic: "Your Topic", estimatedHours: 10)
 -> edit the YAML
 graspful_fill_concept(yaml: "...", conceptId: "concept-id")
 graspful_validate(yaml: "...")
 graspful_review_course(yaml: "...")
-graspful_import_course(yaml: "...", org: "org-slug", publish: true)
+graspful_import_academy(manifestYaml: "...", courseYamls: { "courses/course.yaml": "..." }, org: "org-slug", publish: true)
 ```
 
 ### Images, Videos, Links in Course Content
@@ -160,7 +168,7 @@ When building a course from a PDF or document:
 4. For visual content (photos, diagrams, comparisons), find or request publicly accessible image URLs and use `image` content blocks
 5. Do not copy-paste prose verbatim — rewrite for the lesson pattern (instruction -> worked example -> problems)
 
-### Step 4: Create or update the brand
+### Step 4: Create or update the academy landing page and brand
 
 Every org needs a brand for the site to work. Registration creates a minimal default, 
 but you should update it with content relevant to the course topic.
@@ -169,13 +177,19 @@ Use `graspful_create_brand` to generate a brand YAML tailored to the course topi
 then import it with `graspful_import_brand`. This updates the landing page headline, 
 features, and SEO to match the actual course content.
 
+Important:
+
+- do not leave the landing page as generic niche filler
+- the page should name the learner, the outcome, the curriculum shape, and the proof for why this academy is worth joining
+- treat landing-page authoring as part of the academy build, not post-launch polish
+
 If the org already has a brand (from registration), importing a new one updates it 
 in place (upsert by slug).
 
 Create a white-label landing page and theme:
 
 ```bash
-graspful create brand --niche tech --name "My Academy" --org my-org -o brand.yaml
+graspful create brand --niche tech --topic "Your Topic" --name "My Academy" --org my-org -o brand.yaml
 graspful import brand.yaml
 ```
 

README.md

@@ -1,28 +1,30 @@
 # Graspful
 
-> Create adaptive learning courses with AI agents. Launch in minutes.
+> Create adaptive learning academies and courses with AI agents. Launch in minutes.
 
 ## What Is Graspful?
 
-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.
+Graspful is an agent-first academy creation platform. Academies and 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 an academy, break it into prerequisite-aware courses, 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.
 
 ## How It Works
 
-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. **Scaffold academy** -- `graspful create academy --topic "CKA Exam"` generates the academy shell
+2. **Scaffold courses** -- `graspful create course --topic "Cluster Networking"` generates each course graph
+3. **Fill** -- `graspful fill concept course.yaml networking` adds KPs and practice problems
+4. **Review** -- `graspful review course.yaml` runs 10 quality checks, including whether problems only assess taught material
+5. **Import** -- `graspful import academy.yaml --org k8s-cert --course-dir . --publish` goes live
+6. **Brand** -- `graspful create brand --niche "Kubernetes" --topic "CKA Exam"` generates the landing page that actually sells the academy
 
-Two YAMLs (course + brand) produce one live product with adaptive learning, spaced repetition, and Stripe billing.
+Three YAMLs (academy + courses + brand) produce one live product with adaptive learning, spaced repetition, and Stripe billing.
 
 ## Quick Start
 
 ```bash
 npx @graspful/cli init
 # opens browser auth, then saves an API key locally
 graspful register --email you@example.com
-graspful create course --scaffold-only --topic "Your Topic" -o course.yaml
+graspful create academy --topic "Your Topic" -o academy.yaml
+graspful create course --topic "Foundations" -o courses/foundations.yaml
 ```
 
 ## Tech Stack
@@ -58,11 +60,12 @@ graspful/
 |---------|:---:|-------------|
 | `graspful register` | No | Create account + API key via browser auth |
 | `graspful login` | No | Authenticate with existing credentials |
+| `graspful create academy` | No | Generate academy manifest skeleton |
 | `graspful create course` | No | Generate course YAML skeleton |
 | `graspful create brand` | No | Generate brand YAML with theme presets |
 | `graspful fill concept` | No | Add KPs and problems to a concept |
 | `graspful validate` | No | Offline schema + DAG validation |
-| `graspful review` | No | 10 mechanical quality checks |
+| `graspful review` | No | 10 mechanical quality checks, including teaching alignment |
 | `graspful describe` | No | Course statistics |
 | `graspful import` | **Yes** | Push YAML to Graspful instance |
 | `graspful publish` | **Yes** | Publish a draft course |
@@ -96,12 +99,14 @@ Or manually add to your MCP config:
 | Tool | Auth? | Description |
 |------|:---:|-------------|
 | `graspful_scaffold_course` | No | Generate course YAML skeleton |
+| `graspful_create_academy` | No | Generate academy manifest scaffold |
 | `graspful_fill_concept` | No | Add KPs and problems to a concept |
 | `graspful_validate` | No | Validate YAML against schema |
-| `graspful_review_course` | No | Run 10 quality checks |
+| `graspful_review_course` | No | Run 10 quality checks, including teaching alignment |
 | `graspful_describe_course` | No | Course statistics |
 | `graspful_create_brand` | No | Generate brand YAML |
 | `graspful_import_course` | **Yes** | Import course to platform |
+| `graspful_import_academy` | **Yes** | Import academy manifest plus course YAMLs |
 | `graspful_publish_course` | **Yes** | Publish a draft course |
 | `graspful_import_brand` | **Yes** | Import brand config |
 | `graspful_list_courses` | **Yes** | List org courses |