# PhonoLogic — Full Documentation for AI Agents

> AI-powered decodable story generator for phonics-based literacy education.
> Website: https://phonologic.ca
> Contact: feedback@phonologic.ca
> Company: PhonoLogic Learning Systems Inc., Toronto, Canada

## Table of Contents

- Overview
- How It Works
- Reading Levels & Phonics Scopes
- Key Features
- Story Generation
- Story Worlds
- Assessments
- Pricing
- Target Audience
- Technical Details
- Pages & Navigation
- API Information

---

## Overview

**Mission: practice matched to what the child was actually taught.** PhonoLogic is built especially for struggling and dyslexic readers, and the parents, tutors, and teachers helping them. Reading practice fails when the text contains words a child was never taught to decode (an "instructional mismatch"); PhonoLogic fixes that by generating stories from only the patterns the learner knows and is working on.

PhonoLogic is a web application that generates reading stories using only words a learner can decode based on their current phonics skill level. Unlike generic AI story generators, PhonoLogic validates every word in each story against a curated wordbank of 6,500+ words spanning 200+ phonics patterns (212 subscopes) across 7 reading levels.

The core value proposition: teachers, tutors, and parents can generate unlimited decodable stories that are precisely calibrated to what a specific child can read — not too easy, not too hard, and focused on the exact phonics patterns being taught.

PhonoLogic is a Canadian EdTech product built on the Science of Reading and structured literacy. Its curriculum, scope, and sequence were designed by Marysia Robins, a literacy interventionist and certified Orton-Gillingham practitioner.

---

## How It Works

1. **Set the learner's level**: Either take a 5-minute assessment or manually select a reading level (L1–L7)
2. **Choose phonics patterns**: Mark each phonics subscope as Focus (teaching now), Known (already learned), or Unknown (not yet learned)
3. **Generate a story**: The AI writes a story using only words from Known and Focus patterns, with ~10-15% of words being Focus words
4. **Validate**: Every word is checked against the phonics wordbank. Disallowed words (from Unknown patterns) are flagged
5. **Read together**: Focus words are highlighted/underlined so the educator can guide the learner to practice decoding them
6. **Track progress**: Mark individual words as Strong or Trouble during reading to build a per-learner word profile
7. **Review comprehension**: Each story includes 3 comprehension questions to check understanding

---

## Reading Levels & Phonics Scopes

PhonoLogic uses its own Reading Level system (L1–L7) based on phonics progression, not school grades. A 3rd grader might be at L2, while a strong 1st grader could be at L3.

### Level 1: Foundations
- **Scope I — CVC**: Short vowel words (cat, sit, map, hot, cup)
- **Scope II — Blends**: Consonant clusters (stop, clap, frog, nest, jump)
- **Scope III — Digraphs**: ch, sh, th, wh, ck (chip, ship, this, when, back)

### Level 2: Inflections & Silent E
- **Scope IV — Inflections**: -s, -es, -ed, -ing, -er, -est (jumping, played, foxes)
- **Scope V — VCe (Silent E)**: a_e, i_e, o_e, u_e, e_e (cake, bike, home, cube)

### Level 3: R-Controlled & Vowel Teams
- **Scope VI — R-Controlled**: ar, or, er, ir, ur (start, born, her, bird, burn)
- **Scope VII — Vowel Teams**: ai/ay, ea/ee, oa/oe, ue/ui, ow (long) (rain, boat, green, true)

### Level 4: Complex Vowels & Compounds
- **Scope VIII — Complex Vowels**: oo, au/aw, ou/ow, oi/oy, igh (moon, cloud, coin, night)
- **Scope IX — Compound Words**: Combinations of known words (cupcake, sometimes, into)

### Level 5: Advanced Patterns
- **Scope X — Final Stable Syllables**: -ble, -tle, -dle, -gle, -cle, -fle (table, gentle, middle)
- **Scope XI — Silent Letters**: kn, wr, gn, mb, gh (knight, wrinkle, comb)

### Level 6: Morphology
- **Scope XII — Soft C/G**: ce, ci, cy, ge, gi, gy, dge (city, giant, bridge)
- **Scope XIII — Common Suffixes**: -ful, -less, -ness, -ment, -ly, -tion, -sion (helpful, kindness, station)

### Level 7: Prefixes & Latin Suffixes
- **Scope XIV — Prefixes**: un-, re-, pre-, dis-, mis-, para-, tri- (unhappy, redo, preview, disagree, mistake)
- **Scope XV — Latin Suffixes**: -tion, -sion, -ture, -ive, -ous, -able, -ible, -ist, -ity, -ence/ance, -ent/ant (action, vision, picture, active, famous, capable)

---

## Key Features

### Story Generation Modes
- **Phonics Focus**: Emphasizes specific patterns being taught. Aims for 10-15% focus words
- **Fluency Review**: Uses only mastered patterns for building reading speed and confidence

### Story Customization
- **Story length**: 5 options from short (~70 words) to long (~280 words)
- **Teacher prompt**: Describe a topic, setting, or characters for the AI to use
- **Narrator personas**: Multiple narrator styles for variety
- **Conjugation rules**: Toggle whether the AI can use -s/-es, -ed, -ing forms

### Story Worlds
Persistent narrative universes that maintain continuity across stories:
- **Characters**: Named characters with personalities that persist
- **Settings**: Locations that carry across stories
- **Memory**: AI remembers plot threads, events, and relationships from previous stories
- **Context extraction**: Automatic extraction of characters, settings, and key events after each story
- Each world has its own character roster, memory bank, and story history
- World context is included in AI prompts so new stories build on previous ones

### Comprehension Questions
- Every generated story includes 3 comprehension questions
- Questions test recall, inference, and vocabulary understanding
- Designed to be age-appropriate and phonics-level appropriate

### Assessment System
- **Flashcard assessment**: 5-minute screening using individual word flashcards per phonics pattern
- **Story-based assessment (v2)**: Three AI-generated stories at easy/target/challenge difficulty with per-word rating
- **Offline assessment**: Printable packets for classroom use without internet
- **Auto-leveling**: Assessment results automatically configure the learner's profile with mastered/focus/unknown patterns

### Progress Tracking
- **Strong words**: Words the learner reads confidently (tracked per profile)
- **Trouble words**: Words the learner struggles with (tracked for focused review)
- **Pattern mastery**: Visual tracking of mastered vs. focus vs. unknown subscopes
- **Assessment history**: Timeline of all completed assessments with trend data

### Library & Export
- **Story library**: Saved stories per profile, searchable by prompt and date
- **Favorites**: Pin stories to protect from auto-cleanup
- **PDF export**: Download stories for printing or offline use
- **Shared stories**: Generate shareable public links for any story
- **Data export**: Full JSON export of all account data (PIPEDA compliance)

---

## Story Generation — How It Works Internally

1. The teacher selects phonics patterns and writes an optional prompt
2. PhonoLogic builds a word list from the 6,500+ word phonics wordbank based on which subscopes are Known or Focus
3. If a Story World is active, world context (characters, settings, memories) is included in the prompt
4. The AI (Google Gemini) generates a story using detailed phonics constraints
5. Multiple variants are generated in parallel; the best-passing one is selected
6. The story is validated word-by-word against the allowed word list
7. Focus words are identified and highlighted for the educator
8. Comprehension questions are generated alongside the story
9. Validation stats are computed: focus %, disallowed word count, word count
10. The story is saved to the learner's library

### Validation Rules
- 100% of words must be from Known or Focus subscopes (plus basic function words)
- At least 10% of content words should be Focus words
- Disallowed words (from Unknown subscopes) are flagged in red
- Basic function words (the, a, is, was, etc.) are always allowed regardless of level

---

## Pricing

Three plans (see https://phonologic.ca/pricing for current details). All include unlimited decodable story generation, assessments, progress tracking, and Story Worlds across all 7 reading levels.

### Page — for one learner
- $15 CAD/month (annual: billed $150/year)

### Chapter — for a family (up to 4 learners)
- $30 CAD/month (annual: billed $300/year)
- Everything in Page, for up to four learner profiles on one account

### Library — for tutors, co-ops, and small schools
- $10 CAD/seat/month, minimum 5 seats (annual: $96/seat/year)
- Per-seat billing, curriculum tools, CSV export, and view-only sharing for parents

### Trials & free access
- A free 14-day trial is available on Page and Chapter (a card is collected at the start; cancel before the trial ends and you won't be charged)
- A free five-minute reading assessment is available with no account

### Payment
- Processed through Stripe
- Accepts Visa, Mastercard, American Express
- Plan switching supported (with prorated credit for upgrades)
- Cancellation retains access until end of billing period

---

## Target Audience

### Primary Users
- **Parents** homeschooling or supplementing school phonics instruction
- **Private tutors** working with struggling or beginning readers
- **Classroom teachers** needing decodable text matched to their phonics curriculum
- **Reading specialists** and literacy interventionists

### Use Cases
- Generate practice stories for a specific phonics pattern being taught this week
- Create fluency passages using only patterns a student has mastered
- Assess a new student's reading level in 5 minutes
- Track which words a student struggles with across multiple reading sessions
- Build an engaging story world that motivates reluctant readers
- Generate comprehension questions without manual authoring
- Print offline assessment packets for classroom use

### Educational Approach
PhonoLogic is built on the Science of Reading / Structured Literacy approach:
- Systematic phonics instruction with explicit pattern progression
- Decodable text that matches instruction (not leveled readers)
- Assessment-driven instruction (teach what the student needs next)

---

## Technical Details

- **Platform**: Web application (responsive, works on desktop, tablet, and mobile)
- **Backend**: Node.js on Vercel serverless functions
- **AI Model**: Google Gemini for story generation and comprehension questions
- **Database**: Google Cloud Firestore
- **Caching**: Redis (Upstash) for rate limiting and session management
- **Payments**: Stripe (Checkout, Customer Portal, Webhooks)
- **Authentication**: Google OAuth + email/password with bcrypt hashing
- **Wordbank**: 6,500+ words, 200+ phonics patterns (212 subscopes), built from curated linguistic CSV data
- **Analytics**: Google BigQuery for generation and assessment telemetry

---

## Pages & Navigation

### Public Pages (no login required)
- `/` — Homepage and story configurator
- `/dyslexia` — Help for struggling and dyslexic readers (parent guide + FAQ)
- `/faq` — Frequently asked questions (with search)
- `/pricing` — Subscription plans and pricing
- `/partnerships` — Partnerships for school districts, boards, tutoring companies, and governments (large-scale deployments; contact-based, no self-serve pricing)
- `https://blog.phonologic.ca` — The PhonoLogic blog (guides for parents, tutors, and teachers)
- `/changelog` — Product updates and release notes
- `/register` — Account creation (Google OAuth or email)
- `/signup` — Alternative signup flow (beta)
- `/privacy-policy` — Privacy policy (PIPEDA-compliant; COPPA readiness in progress)
- `/terms` — Terms and conditions
- `/cookie-policy` — Cookie usage policy
- `/share?id=...` — View shared stories (no login needed)

### Authenticated Pages (login required)
- `/` — Story generator (same page, shows app after login)
- `/library` — Saved story library
- `/progress` — Learner progress dashboard
- `/assessment-history` — Past assessment results
- `/settings` — Account and profile settings
- `/results` — Story display page: fresh generations, saved-story re-opens, and mad libs results, with highlights
- `/worlds` — Manage Story Worlds
- `/flashcards` — Phonics flashcard decks
- `/assessment-v2` — Story-based assessment
- `/assessment-gateway` — Assessment selection hub
- `/calibration` — Quick level calibration

### Machine-Readable Files
- `/llms.txt` — Summary for AI agents (this file's shorter version)
- `/llms-full.txt` — Full documentation for AI agents (this file)
- `/robots.txt` — Crawler directives
- `/sitemap.xml` — XML sitemap for search engines
- `/.well-known/ai-plugin.json` — OpenAI plugin manifest

---

## API Information

PhonoLogic's API endpoints are designed for the web application and require authentication via HTTP-only cookies. There is no public API key access at this time.

### Notable Endpoints (internal, auth-required)
- `POST /api/generate` — Generate a story (requires account + profile)
- `POST /api/validate-text` — Validate text against phonics wordbank
- `GET /api/wordbank-words` — Query the phonics wordbank
- `GET /api/flashcard-decks` — Get flashcard decks for a profile
- `POST /api/assessment-v2` — Run a story-based assessment

### Rate Limiting
All API endpoints are rate-limited using Redis. Public endpoints also require reCAPTCHA verification.

---

## Contact & Support

- **General**: feedback@phonologic.ca
- **Privacy**: privacy@phonologic.ca
- **Website**: https://phonologic.ca
- **FAQ**: https://phonologic.ca/faq
- **Company**: PhonoLogic Learning Systems Inc., Toronto, Ontario, Canada