TrellisLearning — User Guide

Welcome! This guide explains how TrellisLearning works for the whole family — parents and kids.

1. What is TrellisLearning?

TrellisLearning is a family learning platform that turns study time into a fun adventure.

Here's the basic idea in three steps:

1. Parents create learning activities — like math quizzes — for their kids.
2. Kids complete the activities and earn ⭐ points.
3. Kids spend their points on rewards their parents set up (screen time, a treat, a toy — you decide!).

Everything happens inside your own private family space:

• Only your family can see your kids' activity.
• Kids only see activities and rewards that you set up for them.
• Your family gets a short, private family code that your kids use to log in.
• TrellisLearning is designed with children's privacy in mind (COPPA-compliant): kids' data is never sold, kids never see third-party ads, and children can't share personal information with others.

2. The Landing Page: Parents vs. Kids

When you open TrellisLearning, you'll see the app name and two big buttons:

• "I'm a Parent" (blue) — takes grown-ups to the parent sign-in.
• "I'm a Kid" (purple) — takes kids to the kid login.

Choose the one that matches who's using the app right now.

New here? On your first visit you'll see a "New here? Here's how to start" welcome prompt above the buttons. It walks you through three quick steps:

1. Parents — create your free family space (sign in and complete the short setup).
2. Create your first activity & reward.
3. Hand it to your kid so they can start earning ⭐.

You can dismiss the prompt to explore on your own — it won't show again on this device. The same three steps also appear below as a "Getting started" section, and the full guide is always one click away in the Documentation link in the page footer.

3. Parent Sign-In

Tap "I'm a Parent" and you'll see a sign-in screen with two options:

• Continue with Google
• Sign in with Amazon

Both are safe, one-tap sign-ins with an account you already have — no new password to remember.

1. Choose Google or Amazon.
2. Sign in (or pick your account) in the window that pops up.
3. You'll be taken to your dashboard — or, if it's your first time, to the onboarding screens (next section).

4. Parent Onboarding (Your First Time)

The first time you sign in, TrellisLearning walks you through a quick setup. There are three short steps.

Step 1 — COPPA consent

You'll see a screen titled "Before we begin" that explains how your child's information is handled:

• TrellisLearning collects only limited info about your child (name, age range, learning progress) to run the learning experience.
• Your child's data is never sold, and kids never see third-party ads.
• Children can't share personal information with others.
• You control what your child can do and can review or delete their data at any time.

To continue:

1. Read the summary.
2. Tick the checkbox: "I am the parent or legal guardian and I consent…"
3. Tap "I Agree & Continue".

This consent is recorded for your family's records.

Step 2 — Name your family

1. Type a family name (for example, "The Smiths").
2. Tap Continue.

Step 3 — Add your first child

1. Enter your child's first name.
2. Choose their grade level:

• Elementary (1st–3rd)
• Middle (4th–6th)
• Upper Middle (7th–9th)
• High School (10th–12th)

1. Create a child PIN — 4 to 6 digits. Your child will use this to log in, so pick something they can remember but that isn't too obvious (and keep it secret from other kids!).
2. Tap "Finish Setup".

🎉 That's it! You'll see a "You're all set!" screen. Tap "Go to Dashboard" to start.

Tip: You can add more children later from within your account.

5. The Parent Dashboard

Your dashboard is your family's control center. Here's what you'll find:

Family code 🔑

A highlighted blue box at the top shows your family code — 6 characters like 7K2M9P.

• This is how your kids log in (or you can read it aloud to them).
• The code is designed to be easy to read and say (no confusing characters like 0, 1, I, or O).
• Keep it handy — your kids will ask for it!

Children

A row of buttons, one per child. Tap a child's name to see their points and history.

Adding and managing children

You can add children any time — not just during onboarding.

Add a child:

1. On the dashboard's Children section, tap "Add child".
2. Enter the child's name and pick their grade level (Elementary through High School).
3. Optionally add interests (comma-separated, e.g. Reading, Dinosaurs) — these help

tailor activity ideas.

1. Create a child PIN — 4 to 6 digits. Your child will use it to log in with your

family code, so pick something they can remember but that isn't too obvious.

1. Tap "Add child". The child appears in your Children row right away and can log in

immediately.

Note: The free plan allows up to 3 children per family. If you hit the limit, you'll
see a "Child limit reached" message.

Manage a child (tap the ⚙️ icon next to their name):

• View profile — open the child's profile page (see below).
• Reset PIN — set a new 4–6 digit PIN for a child (for example, if they forgot it or

it stopped being a secret). The old PIN stops working immediately, and any device the
child is currently signed in on is signed out — they'll need the new PIN to log back in.

• Unlock — if someone entered the wrong PIN too many times, the child's login is

temporarily locked. Unlock lets you clear that lockout right away so they can try again.
(Without this, they'd just have to wait for the lockout to expire on its own.)

Both actions are recorded in the family's audit log and only work for your own family's
children.

The child profile page

Tap ⚙️ → View profile on any child to open their profile page — one place to see and
manage everything about that child:

• Identity — name, grade level, interests, avatar, and theme.
• ⭐ Balance and badges — current points plus the four badges (First Quest,

Quest Champ, 100 Points, First Reward) with earned/locked status.

• Recent activity — the latest assignments and points-ledger entries.
• Actions — Reset PIN and Unlock (same as the dashboard menu), plus **edit

profile fields** (name, grade, interests, avatar, theme) right from the page.

You can only open profiles of your own family's children — another family's child shows
"Forbidden," and a child that doesn't exist shows "Not Found."

Points Ledger

Shows the selected child's:

• Balance — total ⭐ points right now.
• History — every point earned or spent, newest first, with the reason (e.g. "Addition practice completion") and the date/time.

Activity Library

Your library opens in a scannable list view (you can switch to a card grid). Every
activity shows:

• The activity title
• ⭐ Points it's worth
• ⏱ Estimated minutes
• Level and topic tags

Scheduling an activity

To give a child an activity:

1. Tap the child's name in the Children row.
2. Find the activity in the Activity Library.
3. Tap "Assign today" to give it now, or "Schedule for another day" to pick a

date and confirm.

You'll see a confirmation and the activity will appear on your child's Today screen.

Suggest a topic

Don't see the topic you need in the activity builder? Use the "Suggest a topic"
panel: submit a topic and track its review status in the panel's history. A parent
content team reviews every suggestion before it can be used for generation.

Quick links

• + New Activity — create a new activity (see next section).
• Rewards — set up rewards for each child.
• Approvals — approve or deny your child's reward requests.
• Messages — chat with your child.
• Log out — sign out of your account.

6. Creating Activities

The "+ New Activity" button opens the activity builder. TrellisLearning supports two content types — Quizzes and Reading Comprehension — both generated by AI, reviewed by you, then saved to your library.

Choosing a content type

At the top of the builder you'll see two large buttons:

Setting parameters

After picking a content type, set these options:

1. Topic — type what the activity should cover. The topic is not limited to math: for either content type try fractions, space, ancient Egypt, animals, or anything your child is curious about (e.g. addition, subtraction, space, history).
2. Grade Level — pick the range that fits your child:

• Elementary (1st–3rd)
• Middle (4th–6th)
• Upper Middle (7th–9th)
• High School (10th–12th)

*Grade level is a suggestion — it does not restrict what can be generated.* You can create any topic for any grade (open by choice). The AI uses the grade only to tune the tone and difficulty of the language.

1. Difficulty — drag the slider from 1 (easiest) to 5 (hardest).
2. Questions — drag the slider to choose how many questions (up to 20). An estimated time hint updates as you move the slider (e.g. "≈ 10 min").
3. Points — enter how many ⭐ points the activity is worth (1–100). After you generate, this field is pre-filled with the AI's suggestion only if you haven't typed your own value — anything you type is kept, even when you Regenerate.

Generation cost and Starter Credits

Families enabled for Generation V2 see a Starter Credits card before generating. It shows the available balance, the estimated cost for the selected activity shape, and the expected remaining balance. The Free seed is five non-renewing Starter Credits; the product does not describe them as monthly or lifetime credits. Legacy/control families continue to see the existing quota experience.

Governed topics and difficulty (Increment 7 cohort)

Families in the governed cohort (allowlist + activity registry enabled) see a catalog-driven form instead of the two-type selector: they pick an approved activity type, an allowlisted topic for their category and grade, and a 1–10 difficulty that maps deterministically to the internal generation level. Free-text topic entry is replaced by the allowlist for this cohort. If a topic they want is missing, Suggest a topic queues it for Super Admin review — it can never be generated until an admin approves it. Legacy/control families keep the original free-text form during the transition.

A safe, usable preview consumes its displayed credits once, even if you later reject it. Provider, parsing, schema, or safety failures that produce no usable preview release the reservation. Availability/cooldown messages are deliberately neutral and do not reveal internal thresholds.

Generating the activity

Tap "Generate Activity" and wait a few seconds. A retry or accidental double-click with the same request cannot create a second charge.

Reviewing the AI draft

When the draft appears, you'll see:

• The title and instructions.
• For Reading Comprehension: a passage — an informational text your child will read before answering the questions.
• Every question with its answer options — the correct answer is highlighted in green, so you can check the activity really says what you want.
• The suggested ⭐ points and estimated ⏱ minutes.

Then choose:

• "Approve & Save to Library" — keeps the activity in your Activity Library, ready to schedule.
• "Regenerate" — rejects the current enforced preview, keeps its charge, and generates a newly metered draft using the same parameters. Legacy/control families retain the original regenerate flow.
• "Reject" — records that you do not want the usable preview; it does not save the activity or refund the generation charge.

Tip: The points field is editable even after generation — the AI suggests a value, but you decide.

Note: Generation V2 starts with configurable, non-renewing Starter Credits on Free. Customer credits are separate from internal safety and token-usage controls; if either prevents new generation, existing approved activities remain available.

7. Child Login (Kids, this part is for you!)

Kids tap "I'm a Kid" and go through three easy steps:

1. Ask a grown-up for the family email — enter the primary parent/guardian email and tap "Find my family". The older 6-character family-code option remains available during the migration period.
2. Pick who you are — you'll see each family member with their chosen avatar (🌟 🦊 🐻 🦁 🐰 🐼 🐨 🐸 🦄). Tap your name.
3. Enter your PIN — the secret number your grown-up set up with you. Tap Go.

And you're in! 🚀

Heads up: If someone types the wrong PIN too many times, they'll have to wait a while before trying again. That's the app keeping things safe — and if too many wrong attempts come from one device or internet connection, that device is temporarily paused from looking up families or logging in too (it just needs a short wait, and it won't affect other kids in the family).

8. The Child "Today" View

When kids log in, they land on "Today's Quests 🚀" — their own list of activities.

• Each activity is a card showing the title and how many ⭐ points it's worth.
• Tap Start to open the activity.
• Activities that are done show a green "✓ Completed (+pts)" badge.
• No activities? You'll see a friendly "Nothing scheduled for today. Check back later!" — ask a grown-up to schedule one!

Your space — themes, avatars, badges

The whole child side now lives inside a themed shell with your avatar and name at the top,
and a menu with 🚀 Today's Quests, 🎁 Rewards, 💬 Messages, a ⚙️ Settings
button, and Log out.

• 🎖️ Your badges — under the Today heading you'll see a badge strip: First Quest 🎯,

Quest Champ 🏅 (5 quests), 100 Points 💎, and First Reward 🎁. Badges light up
as you earn them from real progress; locked ones stay gray. If the strip can't load, it
simply hides — it never blocks your quests.

⚙️ Settings — make it yours

Tap the ⚙️ Settings button in the header to open your personal settings page:

1. Colors — pick one of five themes: Sunny, Night, Ocean, Forest, or

Sunset. Your choice saves instantly and the whole child side re-colors right away —
and stays that way next time you log in.

1. Your avatar — pick one of the animal buddies (🦊 🐻 🦁 🐰 🐼 🐨 🐸 🦄). This is

the same avatar you see at login and in the header.

1. Change your PIN — enter your current PIN and a new PIN (4–6 digits). Ask a

grown-up to help if you're not sure. Changing your PIN signs out every other device that
is logged in as you — but you stay signed in on the device you're using.

Heads up: a wrong current PIN counts as a failed attempt, same as a wrong login PIN —
too many tries and you'll have to wait a bit before trying again.

Playing an activity

Math Quiz:

1. Read each question and tap the answer you think is right.
2. Answer all questions (each one needs a selection).
3. Tap Submit.

Reading Comprehension:

1. Read the passage displayed at the top — it's an informational text about a topic.
2. Read each question below the passage and tap the answer you think is right.
3. Answer all questions.
4. Tap Submit.

Results

You'll see a celebration screen with:

• 🎉 "Great job!"
• How many you got right, e.g. "You got 4 out of 5 right (80%)."
• "⭐ +X points!" — your points are added to your balance right away.

Tap "Back to Today" to keep going. If the score is below the activity's pass threshold, only the total score/count is shown—never which answers were correct. Generation V2 activities apply configured attempt/cooldown controls so repeated score feedback cannot become an answer key.

From the Today screen, the top menu takes you everywhere:

• 🚀 Today's Quests — back to your activity list.
• 🎁 Rewards — the rewards marketplace.
• 💬 Messages — chat with your grown-up.
• ⚙️ Settings — colors, avatar, and changing your PIN.
• Log out — back to the landing page.

9. Points Ledger (for Parents)

Every point in TrellisLearning is tracked in a ledger — a running history for each child.

On the dashboard:

1. Select a child in the Children row.
2. Look at the Points Ledger section.

You'll see:

• Balance — the big ⭐ number at the top.
• History — each entry lists the reason (like "Addition practice completion" or "Redeemed: 15 min screen time"), the type of transaction, the date and time, and how many points were added (+) or spent (−).

Use this to answer the classic question: "But I earned SO many points!" — the ledger shows exactly where every point went.

10. Rewards

Rewards are the fun part — kids earn points, then spend them.

Parents: creating a reward

Open Rewards from your dashboard, then:

1. Pick the child the reward is for (tap their name).
2. Fill in the reward name (e.g. "15 min screen time" or "Ice cream sundae").
3. Set the point cost (how many ⭐ it takes).
4. Pick an icon from the emoji choices (🎮 🍦 📺 🍕 🧸 📚 🎨 ⚽ 🍿 🎁).
5. Decide how it's redeemed:

• ⚡ Instant (default) — points come out of the child's balance right away.
• 🔒 Requires parent approval — tick the box; the child requests the reward and you approve before any points are spent.

1. Optional frequency caps — limit how often the reward can be redeemed:

• Max per day (e.g. 1).
• Max per week (e.g. 3).

1. Tap "Add Reward".

Your reward appears in the list below, showing its icon, name, cost, and any approval/cap settings.

Note: On the free plan, you can have up to 7 active rewards per child.

Kids: redeeming in the marketplace

From the Today screen, tap 🎁 Rewards. You'll see:

• Your balance at the top (⭐).
• A reward card for each reward your grown-up set up, showing the icon, the ⭐ cost, and whether it's instant (⚡) or needs parent approval (🔒).
• A Redeem button.

What happens when you tap Redeem:

• Instant reward — you'll see "Redeemed [name]! ⭐ -[cost]" and your balance drops right away.
• Approval-required reward — you'll see "Requested [name] — waiting for parent approval." Your grown-up decides next.
• Not enough points? The button shows "Need X more" — keep earning!

Parents: approving requests

When a child requests an approval-required reward, open Approvals from your dashboard.

1. You'll see each request: the reward icon and name, which child asked, the ⭐ cost, and when they asked.
2. Tap Approve — the points are then deducted from the child's balance and the reward is fulfilled.
3. Tap Deny — the request is turned down and no points are spent.

Nothing pending? You'll see a happy "You're all caught up!" screen.

11. Messages

A private message thread between each parent and child.

From the parent side

Open Messages from your dashboard:

1. Pick the child you want to chat with (tap their name).
2. Type a message in the box and tap Send — your messages show up in blue on the right.
3. Or tap one of the sticker buttons (🌟 🎉 💪 ❤️ 👍 🏆 😊 👏) to send a big emoji instead.

From the child side

Kids open 💬 Messages from their Today screen:

• Your messages to your grown-up show up in purple on the right.
• You can type a message or send a sticker (🌟 🎉 💪 ❤️ 👍 😊 🙏 🏆).

Keeping kids safe

Messages from kids are checked automatically:

• If a message contains inappropriate words, threats, or personal information (like phone numbers, email addresses, or your home address), it won't be sent — the child sees a friendly note explaining the message couldn't be sent.
• Sticker messages always work, since they're just emojis. 😊

12. Logging Out

Parents

Tap "Log out" (top-right of the dashboard, next to Messages). You'll be returned to the landing page. Your sign-in is also ended on the Google/Amazon side for this device.

Kids

Tap "Log out" (top-right of the Today screen). You'll be returned to the landing page — ready for the next grown-up or the next sibling to take their turn.

13. Changelog

The /changelog page shows the release history for TrellisLearning.

How to find it

From any page in the app:

1. Click Documentation in the footer, then select Changelog from the sidebar. Or
2. Go directly to /changelog.

What you'll see

• The version number and an environment badge (production, preview, or development) so you can tell which deployment you're looking at.
• A list of release notes written in Markdown — each release entry documents what was added, changed, or fixed.

Quick Reference

Appendix: API Reference — Child Management (for developers)

Endpoints back the "Add a child / manage children" features. All require an authenticated
parent session (401 otherwise); PINs are accepted in request bodies for server-side
hashing only and are never returned in responses.

POST /api/children

Adds a child to the parent's family.

• Auth: parent session.
• Body: { displayName: string, gradeLevel: 'ELEMENTARY' | 'MIDDLE' | 'UPPER_MIDDLE' | 'HIGH_SCHOOL', interests?: string[], pin: string }
• Validation (400): displayName 1–50 chars after trim; gradeLevel one of the four

enum values; pin matches /^\d{4,6}$/; interests optional array, ≤10 items, each
≤50 chars after trim.

• Quota (409): Child limit reached when the family is at max_children (free tier: 3).
• Success (201): { child: { id, displayName, gradeLevel, uiMode } } — never pinHash/pin.
• Audit: child_created entry (actor PARENT), written atomically with the create.

PATCH /api/children/:id/pin

Resets a child's PIN. Updates pinHash only — it does not touch login lockout state
(use POST /unlock for that).

• Auth: parent session. Body: { pin: string } (400 unless /^\d{4,6}$/).
• Errors: 404 Child not found · 403 Forbidden (child belongs to another family).
• Success (200): { success: true, childId }.
• Audit: child_pin_reset entry, written atomically with the update.

POST /api/children/:id/unlock

Unlocks a child whose PIN login is locked out after failed attempts. Clears the whole
ChildLoginAttempt row (lockout window and attempt count, so the child isn't re-locked
on the next attempt).

• Auth: parent session. No body.
• Errors: 404 Child not found · 403 Forbidden (child belongs to another family).
• Success (200): { success: true, childId }.
• Audit: child_unlocked entry, written atomically with the clear.

GET /api/children/:id/summary

Dual-auth summary used by BOTH the child landing badge strip and the parent child-profile
page — one derivation, two clients.

• Auth: the owning parent's session, OR a verified child session whose childId equals

the route id (cross-child reads return 401).

• Success (200): `{ child: { id, displayName, avatarUrl, gradeLevel, interests, theme, uiMode },

balance, stats: { completedAssignments, pendingAssignments, pointsEarned, approvedRedemptions },
badges: Badge[], recentAssignments, recentLedger } — never includes pinHash`.

• Errors: 401 Unauthorized (no/foreign identity) · 404 Child not found.

PATCH /api/children/:id/self

Child self-service: theme/avatar update and PIN change.

• Auth: verified child session; the session's childId MUST equal the route id

(403 otherwise — a sibling cannot edit another child). The forgeable child_id
cookie is never trusted for authorization.

• Body: any of { theme, avatarUrl, pin: { currentPin, newPin } }. Theme must be one of

LIGHT | DARK | OCEAN | FOREST | SUNSET; avatar must be one of the 8-emoji whitelist
(both validated server-side); newPin must match /^\d{4,6}$/.

• PIN change: the current PIN is verified (argon2id + legacy fallback); a wrong current

PIN shares the login lockout counters — per-child ChildLoginAttempt (5 fails / 15 min)
plus per-IP child:self-pin (10 fails / 15 min); success clears both. pinHash and
sessionEpoch bump atomically and the response rotates the session cookie, so the child
stays logged in while every other device is signed out.

• Errors: 401 · 403 (cross-child) · 400 (invalid theme/avatar/PIN shape, wrong

current PIN, no changes) · 429 (rate-limited) · 404.

PATCH /api/children/:id/profile

Parent edits a child's identity fields (the child-profile page).

• Auth: parent session; family-scoped (404 Child not found · 403 Forbidden for

another family's child).

• Body: any of { displayName, gradeLevel, interests, avatarUrl, theme } — at least one

required; validated exactly like POST /api/children (displayName 1–50 chars, grade enum,
interests ≤10 items × ≤50 chars, avatar/theme whitelists).

• Success (200): { success: true, child: { id, displayName, gradeLevel, interests, avatarUrl, theme, uiMode } }.
• Audit: child_profile_updated entry — after carries non-sensitive identity fields

only (never pin/pinHash/sessionEpoch), written atomically with the update.

Happy learning! 🚀⭐