Wiki Authority & Build Rules
Part of: Pickatale Master Build Wiki | Version: v1.8 | Last Updated: 2026-04-18
This page governs the wiki itself. Read it before using any other section as a build spec.
v1 Platform Scope (Sig Dug, 2026-04-18 — Non-Negotiable): Pickatale v1 is school-first only. B2C is out of scope. See Section 0 below.
0. v1 Platform Scope Decision
Decision owner: Sig Dug | Date: 2026-04-18 | Status: ✅ CONFIRMED — Non-Negotiable
What is IN scope for v1
- School admin self-registration OR platform_admin provisioning
- Teacher invite flow (school_admin → teacher)
- Teacher creates / imports students
- Student receives school-issued username + PIN
- Parent linked afterward as read-only observer (invite from teacher/school)
- Teacher-license entitlement only (trial, teacher_paid, enterprise, gifted, free fallback)
What is OUT of scope for v1
| Removed feature | Reason |
|---|---|
| B2C parent self-registration | v1 is school-first |
| Parent-created child accounts | School owns the learner record |
Consumer/parent subscription tier (parent_paid) |
No direct consumer billing in v1 |
| Parent-first onboarding wizard | Parent is a secondary linked observer, not a primary user |
| Parent creating a duplicate learner record | Explicitly prohibited — parent links to existing school record only |
| B2C entitlement resolution path | No parent_paid tier in v1 ENUM |
Parent role in v1 (Confirmed)
Parents are secondary linked observers, not primary account owners.
Parent CAN in v1:
- Receive invite/link from teacher or school_admin
- Create their own adult account (via invite only)
- View parent tracker / progress data
- Receive notifications
- Help manage child access if school policy allows (DECISION-10)
Parent CANNOT in v1:
- Create a child independently
- Buy consumer access
- Own the primary learner record
- Move a child outside the school structure
Child identity rule
The child account is created exclusively by the school/teacher flow. This is the canonical learner record. Parent linking attaches to this existing record. It must never create a second child profile.
Entitlement rule
Only teacher-license entitlement exists in v1. The parent_paid, school_paid, and class_paid tiers are removed from the v1 subscription ENUM. Tiers in v1: free, trial, teacher_paid, enterprise, gifted.
1. Approved Source Set
This wiki is built from exactly four approved sources. No other sources are authoritative.
| Tag | Source | What it covers |
|---|---|---|
| (A) | https://demo.readingtester.com/projects.html | Project list, high-level descriptions |
| (B) | https://plan.readingtester.com | Architecture diagrams, module specs, flow sketches |
| (C) | https://demo.readingtester.com/pickatale-learning-platform.html | Product vision, feature list |
| (D) | Sig direct instruction (this chat, 2026-03-24 onwards) | Non-negotiable product rules, design decisions |
| (E) | Code audit (2026-04-18) | Ground-truth of what is actually built and running |
Anything not tagged with one of these five sources is either UNVERIFIED or must be removed.
What is NOT an approved source
- GraphRAG knowledge graph inferences — removed from this wiki
- Any "smart defaults" or "common practice" assumptions added without a source tag
- Claude's own training knowledge about how similar products work
If a requirement has no source tag, treat it as UNVERIFIED until it can be assigned one.
2. Single Source of Truth [V1-PRODUCTION]
This wiki is the single source of truth for all Claude Code agents. Every rule is final. There is no precedence hierarchy between sections — all content is current and authoritative. If two sections appear to conflict, the more specific (lower-level) rule applies to that specific domain.
- Identity: Page 03 (Identity & Auth) is authoritative. One definition per user type.
- Billing: Page 04 (Billing) Section 29 is authoritative. Use
checkEntitlement(ctx)exactly as specified in 29.3. - Entitlement: Page 04 Section 29.3–29.4 is authoritative. No other entitlement logic exists.
- Session: Page 03 (device_sessions table, Section 16) is authoritative.
- Compliance: Page 08 Section 45 is authoritative. School DPA covers all enrolled students. No platform consent gate.
- Sign-up flows: Page 11 is authoritative. School-first only. Five flows.
- Data model: Page 01 DDL is authoritative. Build exactly these tables.
Rule: If this wiki does not define it, do not build it. Do not infer default behavior from similar products. Undefined = spec gap = stop and flag, do not implement.
3. v1 Production Behavior [V1-PRODUCTION]
These are the confirmed production behaviors for v1. They are not temporary or MVP-only — they are the correct behavior for the current scope. If scale requirements change, decisions will be revisited and this wiki updated.
- Entitlement caching: In-process Map, 60-second TTL per service instance. On Account Center timeout → deny (tier: free). This is production behavior, not a shortcut.
- Nightly bot:
node-cronin-process. 3 retries with exponential backoff (1s, 4s, 16s). Failed learners written tofailed_runstable, retried at 05:00 UTC. Zero-data-loss guarantee viatelemetry_delivery_failurestable. - Internal calls (Telemetry → Bot): 3-attempt retry, 5s timeout per attempt. Failed deliveries written to
telemetry_delivery_failures. Nightly reconciliation confirms delivery. Fire-and-forget is not the model — at-least-once delivery is enforced via the failure table. - Stripe billing: Single provider. Webhook-driven state machine. Idempotency key prevents duplicate processing. No school-level Stripe subscription — subscriptions are per-teacher.
4. Hard Product Decisions — All Resolved for v1
All decisions below are final. Claude Code must implement the [V1 Rule] exactly. Do not re-open these.
OQ-1: One Child, One Class — or Many?
V1 Rule [V1-PRODUCTION]: Many-to-many via class_memberships table. DECISION-01 in the decisions register. A child can belong to multiple classes. Each class independently capped at 33 active students. The single students.class_id FK design is rejected — use class_memberships.
OQ-2: Teacher/Parent Ownership Transfer Rules
V1 Rule [V1-PRODUCTION]:
- Student moved between classes: school_admin only (teacher cannot transfer to another school).
- Student transferred between schools: platform_admin only.
- Parent claim: once approved, permanent until school_admin (not platform_admin only) unlinks. School admin CAN remove a parent claim.
OQ-3: Parent Claim Approval Rules
V1 Rule [V1-PRODUCTION]: Teacher must approve each parent claim. Auto-approve after 7 days if teacher has not acted (prevents permanent blocking). School admin can also approve (not just class teacher).
OQ-4: School as Tenant Boundary
V1 Rule [V1-PRODUCTION]: School is the tenant. school_id scopes all data. Teacher who teaches at two schools needs two accounts in v1. The memberships table in Section 38 DDL is reserved for future multi-school teacher support — do not implement multi-school teacher logic in v1. Flows in Section 30 (single school per teacher) are correct for v1.
OQ-5: Free-Tier Fallback on Entitlement Failure
V1 Rule [V1-PRODUCTION]: On checkEntitlement() failure → use last-known cached tier (60s TTL). Only fall back to free after 3 consecutive failures. Never block reading regardless of tier. Block premium features (quizzes, bot, adaptive leveling) only after confirmed free resolution. Write to audit_log on every fallback.
OQ-6: Night Theme Availability
V1 Rule [V1-PRODUCTION]: Night theme available in portrait Aa panel (already implemented in ReaderPage.tsx). Include in landscape reading modes panel as well. Night theme is opt-in — default is white/day theme.
5. Decisions Register — All Resolved for v1
All decisions below are final and locked for v1. Claude Code must implement the V1 Rule column exactly. Do not treat any of these as open.
| ID | Topic | V1 Rule (FINAL) | Tag |
|---|---|---|---|
| DECISION-01 | One child in multiple classes? | YES — many-to-many via class_memberships. Each class independently capped at 33. | [V1-PRODUCTION] |
| DECISION-02 | Entitlement unit? | Per teacher (teacher_licenses). One license covers all classes owned by that teacher. | [V1-PRODUCTION] |
| DECISION-03 | B2C parent self-registration? | NOT IN V1. Out of scope. Do not build any B2C signup or parent-paid path. | [LEGACY / DO NOT IMPLEMENT] |
| DECISION-04 | Tenant boundary? | School is the tenant. All queries filter by school_id. Teachers cannot access other schools. | [V1-PRODUCTION] |
| DECISION-05 | Canonical tiers? | free, trial, teacher_paid, enterprise, gifted. These are the only valid ENUM values. No aliases. | [V1-PRODUCTION] |
| DECISION-06 | Billing model? | TEACHER-LICENSE: 1 teacher = 1 Stripe subscription, unlimited classes, 33 students/class hard cap. | [V1-PRODUCTION] |
| DECISION-07 | Parent portal before child reads? | YES — parent can access immediately after linking. | [V1-PRODUCTION] |
| DECISION-08 | Multiple parents per child? | NO — one parent per child. Error: CHILD_ALREADY_CLAIMED. | [V1-PRODUCTION] |
| DECISION-09 | Parent self-remove? | NO — only school_admin or platform_admin can unlink. | [V1-PRODUCTION] |
| DECISION-10 | Parent PIN reset? | NOT IN V1. Only teacher/school_admin can reset child PIN. Do not build parent PIN reset endpoint. | [V1-DEFERRED — DO NOT IMPLEMENT] |
| DECISION-11 | Book completion notifications? | YES — push/email to linked parent. Opt-out in parent settings. | [V1-PRODUCTION] |
| DECISION-12 | Parent sees class data? | NO — child's own data only. No class lists or other students. | [V1-PRODUCTION] |
| DECISION-13 | Parent-visible data scope? | Books read, miles, reading level, recent activity only. No bot reasoning, no vocab gaps, no other students. | [V1-PRODUCTION] |
| DECISION-14 | Per-student COPPA consent? | NOT IN V1 school path. School DPA covers all enrolled students. No platform-side consent gate. | [V1-DEFERRED — DO NOT IMPLEMENT] |
6. Source Hygiene Log
The following content was present in earlier wiki drafts and has been removed or quarantined as non-authoritative:
| Content | Source it came from | Action |
|---|---|---|
| B2C self-registration flows | Earlier wiki drafts (pre-2026-04-18) | Removed from v1 scope — confirmed out of scope by Sig 2026-04-18 |
parent_paid subscription tier |
Earlier entitlement design | Removed from v1 ENUM — no consumer billing in v1 |
| Parent-created child accounts | Earlier flows D (B2C) | Removed — child accounts created by school/teacher only |
| GraphRAG inferences (FR-029–031 original versions) | Internal GraphRAG knowledge graph | Removed — FR-029–031 were reassigned to Source (D) Sig direct instruction where confirmed |
| Any requirement inferred from "common practice" without a source tag | None | Removed — replaced with UNVERIFIED tag pending source assignment |
| References to internal tool names in wiki content (memory_search, MEMORY.md paths) | Internal agent infrastructure | Never in wiki — confirmed absent |
Current state: All requirements in Sections 28–47 have at least one of the five approved source tags. Sections 1–27 retain their original source tags for audit history. UNVERIFIED items are explicitly tagged and must not be built until a source is assigned.