# ASU Canvas Course Builder

A Claude Code and Codex plugin for building WCAG-compliant Canvas LMS courses following ASU instructional design standards.

## What's Included

- **28 Skills** — Guided concierge, structured needs analysis, course building, faculty mockups, assessment creation with tier-aware difficulty and regeneration, resource discovery, image search and AI generation, custom visual creation, media upload/embed, interactive media, NotebookLM media workflows, unified `course-audit` (Quick Check / Deep Audit / Guided Review covering accessibility, CRC, and pedagogy), `alignment` read-only CLO/MLO/assessment/material reporting, unified `bulk-edit` (content fix + guided remediation modes), `update-module` minimal-diff edits, `file-remediation` file-level accessibility (PDF/DOCX/PPTX), course navigation with caching/templates, staging with preflight quality checks and rollback, course-transfer via Canvas content migrations, and syllabus import
- **Three-Tier Course Level System** — Auto-detects Introductory (100-299) and Advanced (300-499) tiers from course code; 500+ defaults to Advanced. An opt-in Graduate tier is available for courses emphasizing scholarly synthesis, seminar discourse, and research deliverables (activate by saying "set this to graduate tier"). Calibrates Bloom's ranges, scaffolding, word counts, and rubric descriptors per tier.
- **Assessment Regeneration** — "Too easy / too hard / different angle" for quizzes, assignments, and discussions. Staged replacement workflow with side-by-side comparison and tier boundary enforcement.
- **Preflight Quality Checks** — Automatic Tier 1 checks on every stage (heading hierarchy, alt text, link text, placeholders, quiz feedback). The WCAG 2.1 A+AA static subset (contrast, alt, headings, accessible-name/ARIA, 1.4.1/1.4.4/2.4.2) runs on every content surface — pages, quizzes, assignments, discussions — as additive, non-blocking findings. On-demand Tier 2 checks with Canvas/config context (rubrics, due dates, Bloom's alignment).
- **12 Standards Docs** — Page design system, design taste standards, ASU Canvas standards (with CRC & FRAME), instructional design frameworks, assessment best practices with course tier system, image generation guidelines, scientific visual standards, Canvas content types, ASU design standards (25 standards, 173 criteria), ASU design standards enrichment (per-standard expectations, research references, and evidence tiers), ASU academic calendar data, and verbatim ASU syllabus policy boilerplate
- **100 Python Scripts** — Canvas API utilities, staging manager + secure local preview server (path-traversal and Origin-guard hardened), backup manager, atomic push with verification, build progress tracker, mockup manager, course navigator, content cache, template manager, preflight checks, reusable WCAG 2.1 A+AA validators (`wcag_checks.py`), vision audit, unified staging review, alignment validator (formerly alignment graph), Bloom's helpers, deterministic checks, criterion evaluator, link validator, audit report, diff engine, SVG converter, setup validator, interactive generator + WCAG preflight gate, interactive deployment, transcript and caption uploaders, audit pages, audience-lint, staging-server launcher, file-remediation engines (PDF/DOCX/PPTX assess, remediate, verify, deliver), and more
- **8 Page Templates** — 7 Gold Standard module pages (Overview, Prepare to Learn, Lesson, Knowledge Check, Guided Practice, Create an Artifact, Conclusion) plus a supplementary Resources template
- **2 Mockup Templates** — Self-contained preview HTML with sidebar navigation, placeholder cards for non-page content
- **Course Config Template** — JSON schema for defining course structure before building

## Installation

### Prerequisites

None for Claude Code. The plugin is plug-and-play on macOS: Python and all dependencies install automatically on first session start.

For Codex, use the same local plugin folder and set `ASUCB_PLUGIN_ROOT` to that folder path before running plugin scripts. This gives Codex the same stable root path Claude gets from `CLAUDE_PLUGIN_ROOT`.

### Claude Code install steps

1. Download the plugin zip file from the [latest release](https://github.com/AuryanASU/asu-canvas-builder/releases/latest)
2. Extract to a local directory:
   ```bash
   unzip asu-canvas-builder.zip -d ~/claude-plugins/
   ```
3. Add to your Claude Code settings. In `~/.claude/settings.json`, add:
   ```json
   {
     "plugins": ["~/claude-plugins/asu-canvas-builder"]
   }
   ```
4. Restart Claude Code

On first launch, the plugin's `SessionStart` hook provisions Python + dependencies automatically:

- If you already have Python 3.9+ on `PATH`, it uses that and installs deps into a plugin-local virtualenv (`.venv/`).
- If not, it installs [uv](https://docs.astral.sh/uv/) (Astral's Python installer), downloads a managed Python 3.12, and sets up the virtualenv.

No manual `pip install` required. The hook is idempotent (skips when `scripts/requirements.txt` is unchanged). If it fails, logs are at `/tmp/asucb-pip.log` / `/tmp/asucb-uv-*.log`.

### Codex install steps

Codex uses the `.codex-plugin/plugin.json` manifest and a personal marketplace entry. Both runtimes share one source tree (`skills/`, `hooks/`, `scripts/`, `templates/`, `standards/`).

Full steps — marketplace entry, `ASUCB_PLUGIN_ROOT`, dependency provisioning — are in **[docs/CODEX_PLUGIN_INSTALL.md](docs/CODEX_PLUGIN_INSTALL.md)**.

### Optional: Custom Visuals

Only needed for `visual-builder` SVG to PNG conversion.

- Install optional Python deps: `pip install -r ~/claude-plugins/asu-canvas-builder/scripts/requirements-optional.txt`
- macOS helper:
  - Check first: `python3 scripts/ensure_cairosvg.py --check`
  - If the check exits `1`, run: `python3 scripts/ensure_cairosvg.py`
- Manual macOS setup: `brew install cairo pkg-config`
- Other platforms: install the cairo system library for your OS, then install `requirements-optional.txt`

## Getting Started

Just start talking to Claude or Codex -- the **course concierge** guides you through setup and routes you to the right tool automatically. No skill names needed.

Examples of things you can say:
- "I need to build a course for BIO 101"
- "Create a mockup for this course" (with a Canvas URL)
- "Check my course for accessibility issues"
- "Add images to this page"
- "Create a quiz for Module 3"

The concierge handles Canvas connection, course selection, and skill routing. Credentials are stored in `.env` (git-ignored). Course context is managed per-course in `courses/{courseId}/`.

### Manual Setup (alternative)

If you prefer to configure manually:

1. Create `.env` at the plugin root:
   ```
   CANVAS_TOKEN=your_token_here
   CANVAS_DOMAIN=canvas.asu.edu
   ```
2. Course ID is selected per-session (not stored in `.env`). The plugin maintains a course registry at `courses/registry.json` synced from your Canvas account.

## Skills Reference

### Setup
| Skill | Purpose |
|---|---|
| `course-concierge` | Guided entry point -- routes you to the right skill through a friendly conversation, including connecting Canvas and selecting a course |

### Course Building
| Skill | Purpose |
|---|---|
| `course-build` | End-to-end course creation orchestrator -- interview, plan, build, QA, publish |
| `needs-analysis` | Structured intake before course design -- captures context, task analysis, learner analysis, and planning flags |
| `syllabus-generator` | Define course objectives, assessment architecture, and grading (source of truth) |

### Content & Assessment Generation
| Skill | Purpose |
|---|---|
| `quiz-generator` | NBME-style knowledge check quizzes (5 Qs, auto-graded) |
| `assignment-generator` | "Create an Artifact" assignments with rubrics |
| `discussion-generator` | Graded discussion prompts (5 types: debate, comparison, hypothetical, integration, reflective) |
| `rubric-creator` | Analytic rubrics (3-5 criteria, 4 performance levels) |
| `interactive-content` | Interactive HTML activities (5 built-in types + custom mode + interactive visualizations) |

### Resources
| Skill | Purpose |
|---|---|
| `resource-discovery` | Research and curate accredited academic resources per module |

### Images & Visuals
| Skill | Purpose |
|---|---|
| `images` | Find or generate images -- search-first for real content, AI for custom visuals |
| `visual-builder` | Create custom visuals (SVG to PNG) -- diagrams, illustrations, infographics, charts |

### Media Production
| Skill | Purpose |
|---|---|
| `notebooklm` | NotebookLM audio primers, lecture videos, and study notebooks |

### Mockup
| Skill | Purpose |
|---|---|
| `course-mockup` | Create, edit, and present faculty-facing course mockups; promote approved mockups into course builds |

### Editing & Navigation
| Skill | Purpose |
|---|---|
| `update-module` | Modify a single module post-build (pages, assessments, media, interactives) |
| `bulk-edit` | Batch edit, propagate, content fix, template cleanup across multiple pages |
| `canvas-nav` | Browse course tree, search items, gradebook summary, link validation |

### Staging & Safety
| Skill | Purpose |
|---|---|
| `staging` | Preview, push, and rollback -- all HTML body changes stage before push |

### Transfer
| Skill | Purpose |
|---|---|
| `course-transfer` | Copy modules/pages/assignments between Canvas courses |

### Quality Assurance
| Skill | Purpose |
|---|---|
| `course-audit` | Scan course against ASU standards |
| `alignment` | Validate CLO/MLO/assessment/material alignment with evidence-anchored HTML report |

### Assessment Assurance
Separate from the QA/standards audit: scores whether a course's assessment strategy can certify learning in an AI-capable world.
| Skill | Purpose |
|---|---|
| `assurance-audit` | Live-API assessment audit: Two-Lane assurance, AIAS, authenticity, Counterfeit Assurance; deterministic tier + Assurance Coverage; batch cohort ranking |

### Faculty Support
| Skill | Purpose |
|---|---|
| `instructor-guide` | Generate hidden Faculty Resources module with teaching notes and templates |

### Feedback
| Skill | Purpose |
|---|---|
| `plugin-feedback` | Send feedback, bug reports, or feature requests to the plugin team |

## Key Features

### Always-on Workflow Contract
`AGENTS.md` ships the plugin's operating contract — setup checks, intent routing, the Canvas write-safety gate, and the HPI/ID standard — and a `SessionStart` hook injects it into every session on both Claude Code and Codex. The workflow is followed automatically from the first message; no one has to prompt for it.

### Safe Canvas Writes
All Canvas writes go through a staging pipeline: content is staged locally for preview, backed up before publishing, pushed to Canvas, then automatically verified. If something goes wrong, you can roll it back.

### Build Progress Tracking
The plugin tracks where you left off in every course, page by page. Switch between courses and pick up exactly where you were. Detects if someone edited a page directly in Canvas since your last push.

### Timeline and Learnings Ledger
Structured per-course JSONL ledgers capture milestone events and reusable quirks without changing the existing course memory or build progress files.

### Course Memory
Faculty preferences, design decisions, and approvals are persisted between sessions automatically. No manual note-taking needed.

### Faculty Mockups
Create presentable course previews for faculty buy-in. Generates a self-contained HTML file you can email or screen-share. When faculty approves, promote directly into a course build.

### Cross-Course Dashboard
When working with multiple courses, see a status summary at session start before picking which course to work on.

## Per-Course Data

Each course gets its own directory at `courses/{courseId}/` (git-ignored) containing:
- `course-config.json` -- course objectives, modules, grading, policies
- `course-memory.md` -- cross-session context (faculty preferences, design decisions)
- `build-progress.json` -- module-by-module build progress
- `mockup/` -- faculty-facing mockup (preview HTML, placeholder cards, assessment briefs)
- `staging/` -- content staged for preview before push
- `backups/` -- timestamped backups of Canvas content before writes
- `reports/` -- audit and review HTML reports
- `content_cache/` -- local page dump for offline search

## Version

See `VERSION` file or `CHANGELOG.md` for current version and history.

## Release Automation

GitHub release packaging is automated on `v*` tags, and published releases can sync the current version block to Coda. Add the `CODA_API_TOKEN` repository secret as documented in `docs/CODA_SYNC_SETUP.md`.
