Teach Course Builder

Set the API URL (optional if using default):

export TEACH_API_URL="http://localhost:4100/api"

Start the authoring API:

cd /path/to/teach
pnpm dev:authoring-api

Workflow Phases

Phase 1: Analyze

Analyze source documents to understand their structure.

deno run --allow-read --allow-env scripts/analyze-sources.ts /path/to/sources

This produces a course plan showing:

• Suggested course title
• Proposed units (based on directories)
• Proposed lessons (based on files)
• Detected audience layers
• Suggested competencies

Phase 2: Plan

Review the generated plan with the user. Modify as needed:

• Adjust unit titles and ordering
• Merge or split lessons
• Refine audience layer assignments
• Add or remove competencies

Phase 3: Research (Optional)

If content needs expansion, use the research skill:

• Identify gaps in the source material
• Research supplementary topics
• Find authoritative sources for claims

Phase 4: Build

Create the course structure via API:

# Create the course
deno run --allow-net --allow-env scripts/create-course.ts \
  --title "Working with AI" \
  --description "A practical guide"

# Add units
deno run --allow-net --allow-env scripts/add-unit.ts \
  --course-id <course-id> \
  --title "Foundations"

# Add lessons with content
deno run --allow-net --allow-env --allow-read scripts/add-lesson.ts \
  --unit-id <unit-id> \
  --title "What AI Is and Isn't" \
  --content-file /path/to/what-ai-is-and-isnt.md \
  --audience-layer general

# Add competencies
deno run --allow-net --allow-env scripts/add-competency.ts \
  --course-id <course-id> \
  --name "Understanding AI Limitations" \
  --cluster-name "AI Literacy"

Phase 5: Review

Verify the course in the authoring UI:

• Open http://localhost:4101/courses/<course-id>
• Check Content tab for unit/lesson hierarchy
• Check Competencies tab for learning objectives
• Edit and refine as needed

Available Scripts

analyze-sources.ts

Analyze a directory of markdown files and propose course structure.

# Human-readable output
deno run --allow-read --allow-env scripts/analyze-sources.ts /path/to/sources

# JSON output (for programmatic use)
deno run --allow-read --allow-env scripts/analyze-sources.ts /path/to/sources --json

What it does:

• Recursively finds all .md files (excluding READMEs)
• Extracts titles, descriptions, and headings
• Groups files by directory into units
• Infers audience layers from directory/file names
• Counts words for scope estimation
• Suggests competencies from heading keywords

create-course.ts

Create a new course.

deno run --allow-net --allow-env scripts/create-course.ts \
  --title "Course Title" \
  --description "Description" \
  --json

add-unit.ts

Add a unit to a course.

deno run --allow-net --allow-env scripts/add-unit.ts \
  --course-id <id> \
  --title "Unit Title" \
  --description "Description" \
  --order 1

add-lesson.ts

Add a lesson to a unit.

deno run --allow-net --allow-env --allow-read scripts/add-lesson.ts \
  --unit-id <id> \
  --title "Lesson Title" \
  --description "Description" \
  --content-file /path/to/content.md \
  --audience-layer general \
  --order 1

Audience layers:

• general - Introductory content for all learners
• practitioner - Intermediate content for regular users
• specialist - Advanced/technical content for experts

add-competency.ts

Add a competency to a course.

# Creates cluster if needed
deno run --allow-net --allow-env scripts/add-competency.ts \
  --course-id <id> \
  --name "Competency Name" \
  --cluster-name "Cluster Name"

# Use existing cluster
deno run --allow-net --allow-env scripts/add-competency.ts \
  --cluster-id <id> \
  --name "Competency Name"

list-courses.ts

List existing courses.

deno run --allow-net --allow-env scripts/list-courses.ts
deno run --allow-net --allow-env scripts/list-courses.ts --json

Example Interaction

User: "Build a course from inbox/ai-education/"

Workflow:

1. Analyze the source directory:

   deno run --allow-read --allow-env scripts/analyze-sources.ts inbox/ai-education/
   

2. Review the proposed structure:

   # Course Plan: AI Education
   
   **Source:** inbox/ai-education/
   **Total:** 12 lessons, ~15,000 words
   
   ## Proposed Structure
   
   ### 1. Layer 1: Foundations
   - **What AI Is and Isn't** [general]
   - **Basic Prompting** [general]
   - **When to Use AI** [general]
   - **Data and Privacy** [general]
   
   ### 2. Layer 2: Effective Use
   - **Why AI Gives Mediocre Results** [practitioner]
   - **Framework-First Prompting** [practitioner]
   ...
   

3. Confirm structure with user, then build:

   # Create course
   deno run --allow-net --allow-env scripts/create-course.ts \
     --title "Working with AI: A Practical Guide" \
     --description "Standalone articles about working effectively with AI tools"
   
   # Get course ID from output, then create units and lessons...
   

4. Direct user to http://localhost:4101/courses/<id> to review

Integration Points

Research Skill

For content gaps:

• Use research skill's Tavily integration to find sources
• Expand thin lessons with researched content
• Verify claims in source documents

Competency Skill

For learning objectives:

• Use competency skill to define progression paths
• Map competencies to lessons
• Define rubrics for assessment

Gentle-Teaching Skill

For content design:

• Apply gentle-teaching principles to lesson content
• Ensure appropriate scaffolding
• Design for learner empowerment

Anti-Patterns

The Copy-Paste Course

Problem: Just copying files without structure analysis Fix: Always run analyze-sources.ts first; review and refine structure

The Flat Course

Problem: All lessons at same level without units Fix: Group related lessons into units; use directory structure as guide

The Gapless Course

Problem: Assuming source materials are complete Fix: Identify gaps; use research skill to expand; ask user about missing topics

The Competency-Free Course

Problem: Course without learning objectives Fix: Always add competencies; extract from headings or define explicitly

Output Persistence

Course data is persisted via the authoring API:

• Database: apps/authoring-api/data/authoring.db
• Accessible via: http://localhost:4101

What Gets Stored

Environment Configuration

# API endpoint (default: http://localhost:4100/api)
export TEACH_API_URL="http://localhost:4100/api"

# For research integration
export TAVILY_API_KEY="your-key-here"

Troubleshooting

"Connection refused" errors

The authoring API isn't running:

cd /path/to/teach
pnpm dev:authoring-api

"Course not found" errors

Use list-courses.ts to verify course ID:

deno run --allow-net --allow-env scripts/list-courses.ts

Empty course plan

Source directory may only contain READMEs (which are skipped):

• Check for .md files that aren't named README.md
• Verify the path is correct

What You Do NOT Do

• You do not bypass the authoring API (always use scripts)
• You do not create courses without user review of structure
• You do not copy content verbatim without structure analysis
• You do not skip competency definition
• You propose structure; the user decides final organization