# Scireka Interactive Learning Studio Web First App Specification

Version 2.0  
Prepared 29 October 2026  
Status: implemented guided web prototype plus a staged plan for a fuller AI teacher product.

This document replaces the Windows and Unreal first implementation direction in version 1. The immediate product is a browser-based learning studio. It helps a learner manipulate a mathematical idea, ask for help, try a new problem, and reflect on what they understood. A native realistic 3D classroom remains a possible later presentation layer, subject to evidence that it improves the experience enough to justify its cost.

The specification is self-contained and can be given to a coding agent. It distinguishes shipped prototype behavior, requirements for the next iteration, and later capabilities. Do not present planned features as implemented or market this prototype as a validated educational product.

## 1 Product decision and learner promise

Working name: Scireka. Teacher persona: Mira, an explicitly illustrated learning guide. Product promise: a calm place to make mathematics understandable through small actions and useful explanations.

Initial audience assumption: learners beginning algebra, approximately ages 12–15, who need help understanding equality and inverse operations. This is an assumption for design and user testing, not an established market or age-policy decision. Avoid patronizing language and allow adults to use the same lessons. Confirm actual learners, device access, curriculum needs, buyer, and launch geography before public commercialization.

The primary outcome is independent understanding: can a learner solve a new related problem and explain why the steps preserve equality? The interface should also feel approachable enough that a learner chooses another useful session. Do not use session length, compulsive use, streak preservation, or badge collection as the definition of learning success.

The first release is a focused algebra learning module, not a whole school or a replacement for an accredited teacher. Explain its scope honestly.

## 2 What changed after the design review

| Earlier risk | Revised decision |
| --- | --- |
| Passive explanation and quiz loop | Put an interactive balance model at the center of the first screen |
| No clear purpose for the environment | Every visual object corresponds to part of the equation |
| Expensive realism before product validation | Start with an illustrated teacher and browser UI |
| Too much content before testing | Implement two closely related algebra lessons before expanding |
| A broad mastery label after five answers | Show actual independent and supported attempts; make no mastery claim |
| Hints appear to erase progress | Track and acknowledge supported practice separately |
| A single correct solution route | Accept alternative mathematically equivalent operations on both sides |
| Assessment feels mandatory | Allow short practice sessions and early reflection |
| Generic praise | Give specific feedback about the learner's action or answer |
| Long AI waits on every action | Make manipulation and grading deterministic and immediate |
| Live AI expected everywhere | Clearly label guided responses and isolate the future AI integration |
| User testing scheduled late | Test the first playable lesson before adding curriculum or visual polish |
| Desktop GPU requirements | Use ordinary web technologies without a local model or GPU prerequisite |
| Ambiguous feature availability | Mark future lessons Planned and show no misleading launch controls |

Preserve the earlier architecture's sound principles: exact grading, validated content, optional audio, reliable progress handling, transparent system limitations, accessible controls, and no manipulative rewards.

## 3 Implementation status and boundaries

| Capability | Current prototype | Next iteration or later |
| --- | --- | --- |
| Responsive classroom | Implemented in HTML, CSS and JavaScript | Usability and assistive-technology validation |
| Interactive equation operations | Add, subtract, multiply and divide on both sides | Add richer direct manipulation and misconception-specific steps |
| Exact numeric grading | Integers, finite decimals, fractions, optional x prefix | Broader mathematical response types when curriculum requires them |
| Lesson library | Two playable algebra lessons; four planned cards | Add content only after first-topic validation |
| Teacher questions | Authored, rule-based responses with explicit disclosure | Grounded server-side AI through a validated interface |
| Teacher appearance | Original illustrative SVG portrait | Compare styles with learners before photorealistic investment |
| Audio | Optional browser text-to-speech if supported | Tested voice choices and finer playback controls |
| Microphone | Not implemented or requested | Optional transcript-confirmed input after text flow is strong |
| Progress | Real local attempts, separated by assistance | Delayed review and more granular skill evidence |
| Notebook | Create, save and delete local text notes; save an example | Search, tagged notes and optional import |
| Data export | JSON export of progress and notes | Validated import with migration and conflict handling |
| Persistence | Browser localStorage with an explicit warning on failure | IndexedDB if data volume demands it; cloud sync only as a separate decision |
| Access | Owner-private hosted Site | Any sharing change requires explicit owner instruction |
| Learning efficacy | Not established | Formative learner studies followed by a suitable evaluation |
| Unreal or MetaHuman | Not part of this build | Possible later renderer using validated learning contracts |

Do not silently turn this static prototype into a hosted LLM product. That requires secrets management, server-side controls, a reviewed data policy, cost controls, provider choice and real evaluation. Browser speech is not an LLM integration.

## 4 Instructions for a coding agent

Read the entire specification and inspect the current repository before editing. Preserve existing Site identity and unrelated work. Implement the next useful slice rather than regenerating the project from scratch.

The current source is a buildless static application. Keep dependencies minimal. Do not add a framework, backend, database, accounts or model download merely to make the project appear production-ready. Introduce a dependency only when a defined requirement justifies it.

Keep mathematical state, grading and evidence independent from presentation and teacher wording. An explanation must never decide whether an answer is correct or overwrite an attempt. Do not execute learner text, model text, expressions from a content file, or imported notes as code.

Use existing Sites source preparation and publication tooling. Preserve the exact project ID and current audience. Run relevant tests before publishing. Report browser verification as unverified if the environment cannot provide it; do not replace a missing managed preview daemon with an improvised server or claim a screenshot was inspected when it was not.

Maintain README.md and BUILD_STATUS.md with implemented behavior, test evidence, limits, and next actions. Record a clear distinction between an engineering test, a human usability observation, and a learning-outcome evaluation.

## 5 Core experience

The classroom opens directly to a useful example. No learner account, age entry, lengthy tour or mandatory profile setup blocks exploration. The host's owner-access controls are separate from the learner UX.

The initial equation is 2x + 3 = 11. Golden boxes represent the unknown amount; neutral blocks represent known amounts. The same relationship is available as equation text. The learner can follow a suggested operation or choose their own. Both sides change together, preserving equality.

Once x is isolated, the learner sees the substitution check and may try a new problem. They can also skip the demonstration and try independently. Practice is untimed. A hint is available and is recorded as assistance. A wrong answer is useful evidence; a formatting error is not a mathematical mistake.

The learner can attempt up to three questions in a session or finish early. Reflection shows actual independent first-answer results and supported practice. A saved note can contain the learner's own explanation. The application never awards a fictitious mastery status or fills charts with sample progress.

The teacher remains available but does not demand a conversation at every step. Mathematical actions work without a network model or spoken audio.

## 6 Information architecture

The persistent navigation has four destinations:

1. My classroom: current lesson, model or equation view, actions, teacher panel, and contextual next steps.
2. Explore lessons: six descriptive cards, two playable, four explicitly planned; filters for all, available and planned.
3. My progress: independent first answers, supported practice, explored lessons, topic breakdown and recent attempts.
4. My notebook: compose notes and inspect or delete existing notes.

Settings are available on every page. The classroom's next-step cards link to the gentler warm-up, the notebook and real progress. Do not introduce an extra dashboard that delays the lesson.

Use fragment routes for this static build: #today, #lessons, #progress and #notebook. An unknown route returns safely to the classroom. The app specification is downloadable from the footer.

## 7 Visual design system

Direction: a warm, quiet study space with a dark green teaching surface, creamy neutral backgrounds and muted botanical accents. It should feel thoughtful and inviting without infantilizing the learner. The design must not look like a dense school administration dashboard.

| Token | Value or rule |
| --- | --- |
| Page background | #F7F7F2 |
| Sidebar background | #F2F3EC |
| Card background | #FFFFFF |
| Main ink | #263D35 |
| Primary action | #295546 |
| Teaching board | #274D40 |
| Unknown quantity | Muted gold, approximately #E4CE87 |
| Borders | #E4E7DE, visibly distinguish controls from background |
| Type | System sans-serif for UI; Georgia or equivalent serif for equations and occasional reflection text |
| Heading | About 30–34 px desktop, 29 px narrow screens; do not shrink important content to force a fit |
| Spacing | A consistent 4/8 px rhythm with 18–24 px card padding |
| Corners | 9–13 px controls and smaller cards; approximately 20 px major containers |
| Icons | Simple consistent line icons, with accessible labels on icon-only controls |
| Shadows | Subtle; hierarchy comes primarily from spacing and surface color |
| Animation | Brief and functional; respect reduced-motion preference |

Do not depend on remote fonts, stock photographs or generated images to render the first lesson. The teacher portrait and mathematical illustrations are original local SVG assets. Mathematical graphics must be exact, inspectable, and derived from state; do not generate equations as bitmap artwork.

Desktop layout: a roughly 218 px left sidebar, a spacious main column, and a classroom split into a wider teaching card plus a compact teacher panel. Tablet collapses the sidebar to icons. Mobile moves navigation to a bottom bar and stacks the teacher below the teaching card. Horizontal scrolling must not be required to solve a problem.

Keep important mathematical symbols, feedback, inputs and primary controls readable at browser zoom. Do not treat the current compact secondary typography as proof of accessibility compliance. Measure contrast and review readable sizes on representative devices before release.

## 8 Screen and interaction details

### 8.1 Classroom

Show the lesson name, topic, approximate duration and three stages: Explore, Try it yourself and Reflect. Duration is an estimate, never a countdown.

The teaching board has a meaningful text equation, a graphical model, a model/equation view toggle and a restart control. Restart asks for confirmation and preserves saved evidence and notes. The step history lists applied operations and the resulting equations. Undo affects the current example, not previously submitted practice results.

Suggested operations help a beginner get started. Try my own step opens an explicit operation selector and numeric input. The operation applies to both sides; it must not silently apply only to the unknown or a selected term.

The example's save action creates a notebook entry containing the original equation, operation history and equality rule. Saving a note is a real action, with confirmation and persistent content.

### 8.2 Teacher panel

Show Mira's illustrated portrait, a short contextual explanation, three question suggestions and a text question field. Suggested questions are Why both sides?, Show me differently and How do I check?. Also support questions about x and requests for a hint.

The prototype must visibly say that responses are guided content, not live AI. Unknown questions receive a useful scope explanation and suggestions. Do not add simulated thinking delays, fake streaming, invented memory, or an Online badge implying a real person.

Read aloud uses the available browser speech capability when the learner chooses it. Stop cancels playback immediately. Submitting another question also cancels old speech. If audio fails, text stays available. Voice availability and pronunciation are browser-dependent.

### 8.3 Lesson library

Playable lessons: Find the balance and One small step. Planned lessons: Parts of a whole, A hundred little pieces, The perfect mix, and Math out in the world. Do not make planned cards launch incomplete or unrelated material.

Filters work without changing completion records. Entering a new lesson resets only the active example and session, not saved evidence. Warn before replacing a practice session that contains submitted work, and make clear that those submissions are already saved.

### 8.4 Progress

Show counts and denominators, not a fabricated learning percentage. A correct independent answer is different from an assisted answer. The explored-lesson count refers to sessions the learner has reflected on, not certified competence.

Recent practice displays the original equation, date, assistance state and first-attempt result. Explain that a few examples are only early evidence. The app currently suggests returning another day; it does not schedule external reminders or certify retention.

### 8.5 Notebook and settings

A note can contain up to 2000 characters. Render it as text, never HTML. Save at most 100 notes in this prototype and show a useful limit message. Deletion requires confirmation. A reflection shortcut opens the note composer with an editable starting phrase.

Settings include larger learning text, reduced motion, optional read aloud, export and clear learning data. Export produces a readable JSON file. Import is not implemented. Data clearing requires explicit confirmation and removes this application's browser data without touching unrelated applications.

## 9 Learner control and teacher behavior

Use ordinary, specific language. Prefer “Both sides changed equally” to blanket praise. Never infer intelligence, personality, effort, emotional state or disability from an answer. Do not label a learner a visual or auditory learning type.

The teacher can offer a visual model, equation steps, a shorter explanation or a new example. These are representations the learner can choose, not permanent categories assigned to the person.

Help should reduce dependence over time: explain one step, let the learner complete the next, then offer a related problem with less support. Keep a clear escape from any explanation loop. Do not require voice use or personal disclosure.

The next iteration should make feedback more sensitive to observable mistakes. For example, if a learner changes 2x + 3 = 11 to 2x = 14, focus on undoing addition. Do not replay the whole lesson by default. Until structured steps are collected, avoid claiming to know the cause of an incorrect final answer.

## 10 Mathematical engine

The authoritative equation is ax + b = c. Store a, b and c as normalized rational numbers with integer numerator and nonzero denominator. The current implementation uses BigInt arithmetic and a greatest-common-divisor reduction. Do not use floating-point equality to grade mathematics.

Valid operations:

- Add v: a stays unchanged, b becomes b + v, c becomes c + v.
- Subtract v: a stays unchanged, b becomes b - v, c becomes c - v.
- Multiply by nonzero v: multiply a, b and c by v.
- Divide by nonzero v: divide a, b and c by v.

Reject multiplication by zero as a simplification action because it destroys information about x. Reject division by zero. Preserve the invariant (c - b) / a through all accepted operations. A solved representation has a = 1 and b = 0. A different equivalent equation is valid even when it is not yet solved.

Alternative routes must work. For 2x + 3 = 11, subtracting 3 then dividing by 2 yields x = 4. Dividing by 2 first yields x + 3/2 = 11/2; subtracting 3/2 also yields x = 4. Never mark the second route wrong simply because it differs from a suggested sequence.

Show fractional coefficients with unambiguous parentheses, such as (1/2)x. The physical balance analogy is best for positive quantities. Signed or fractional intermediate expressions should use clearly labeled quantities or equation view; do not pretend a negative number is literally a physical negative weight.

Limit a session's example history to 20 steps, with undo and restart available. Bound rational numerators and denominators to avoid runaway values. Errors must preserve the last valid equation and explain a next action.

## 11 Lessons and practice pools

| Lesson | Worked example | Purpose |
| --- | --- | --- |
| Find the balance | 2x + 3 = 11, x = 4 | Understand equality while using two inverse operations |
| One small step | x + 3 = 8, x = 5 | A gentler introduction with one inverse operation |

The independent problems are different from the demonstrated examples. Use a stable fingerprint based on content version and normalized parameters, not a fresh random ID, to identify repeats.

| Two-step pool | Expected x | One-step pool | Expected x |
| --- | --- | --- | --- |
| 2x + 5 = 17 | 6 | x + 6 = 14 | 8 |
| 3x + 2 = 17 | 5 | x - 7 = 5 | 12 |
| 2x + 7 = 17 | 5 | 4x = 28 | 7 |
| 4x + 3 = 31 | 7 | x + 9 = 20 | 11 |
| 3x + 4 = 22 | 6 | 6x = 54 | 9 |
| 5x + 2 = 22 | 4 | x - 2 = 9 | 11 |

The current pools are deliberately small. Prefer unseen questions and explain when a repeated pool becomes review. Repeated identical questions do not create new independent evidence. Do not imply that twelve fixed problems establish a complete curriculum or durable mastery.

Next content additions should include learner explanations, different representations, structured steps, varied difficulty and transfer problems. Add fraction or percentage lessons only with their own diagrams, parsers, reviewed examples and acceptance tests.

## 12 Answer handling and feedback

Accept an integer, finite decimal with up to four decimal places, simple fraction, and optional x = prefix. Permit leading or trailing whitespace and normalize the mathematical minus sign. The prototype limits an input to 24 characters and integer components to six digits. Reject exponent notation, infinity, NaN, extra equations, scripts, ambiguous multiple answers and denominator zero.

Examples for an answer of 5: 5, 5.0, 10/2 and x = 5 are equivalent and correct. Four is a valid but incorrect answer. 1/0 or “5 or 6” is invalid format and creates no mathematical evidence.

Grading compares exact normalized rational values. Feedback reports correctness only after this deterministic evaluation. A correct submission should be checked against the original equation. Incorrect feedback invites substitution or a hint without inventing a diagnosis that cannot be established from the final number.

A first valid answer creates at most one evidence record for that question fingerprint. Retrying an incorrect answer may show that the learner corrected it, but must not rewrite the original first attempt as correct. A hint requested before the first answer marks that attempt assisted. A hint requested after a first answer helps a retry without altering the already recorded evidence.

No partial-credit or natural-language reasoning grade is implemented. A future structured-step rubric can provide finer assessment while preserving exact checks. Free-form explanation feedback must remain clearly ungraded unless a validated rubric is introduced.

## 13 Progress and memory model

Do not use the earlier four-of-five “Secure” rule in this version. The prototype reports observable counts. It does not infer ability, grade level, intelligence, emotional state or a psychometric score.

Minimum evidence fields: fingerprint, skill, original equation, canonical answer, correct, assisted and timestamp. Keep content version in the fingerprint. Store each distinct question once for independent evidence; repeat attempts can inform a future practice history without inflating independent performance.

Show:

- Independent first attempts and how many were correct.
- Supported practice with hints.
- Lessons explored and reflected on.
- Recent examples and actual dates.

Next version should distinguish operation selection, equality preservation, arithmetic and substitution checks. Delayed review should assess new questions after time has passed and label the evidence accordingly. A success today must not automatically become “remembered” or “mastered.”

Personalization may use observed errors and explicit preferences. Any future teacher memory should be inspectable and resettable. Do not retain personal chat histories by default merely to make the teacher seem more human.

## 14 Local state and persistence contract

The prototype uses one browser-local learning space under a versioned storage key, scireka.studio.v2. It does not implement multi-user accounts, cross-device sync, encrypted local storage or cloud database records.

Persist the selected lesson, current lesson stage, rational equation, bounded operation history, practice index, current assistance state, session results, unique evidence, completed exploration IDs, notes and preferences. Validate loaded values, known lesson IDs, enum values, numeric bounds and array lengths. A saved equation must have the same solution as that lesson's original equation.

A malformed or incompatible store should recover to a usable safe state rather than crash. Preserve recoverable notes and evidence when a schema migration is introduced. Do not silently overwrite valuable data during a future migration.

Catch storage failures and warn that the session is not saved. Export should remain available for the current in-memory data. Do not show success after a failed save. Browser storage can be cleared by the user or platform, so the UI must not promise durable backup.

Export includes the schema version, data and export timestamp, and excludes API keys or credentials because none belong in the browser data model. Any future import requires size limits, strict validation, preview, conflict rules and explicit confirmation before replacing existing evidence.

## 15 Architecture and repository

Current architecture: static browser UI, exact mathematical module, authored guide, browser persistence and optional browser speech. No server is required to execute the learning logic after the app assets are loaded. This does not yet make the site an offline-installed application; service-worker caching is not implemented.

```text
scireka-web/
  .openai/hosting.json
  package.json
  README.md
  BUILD_STATUS.md
  dist/
    index.html
    style.css
    app.mjs
    engine.mjs
    teacher.svg
    mark.svg
    AI_Teacher_Game_Master_Specification.md
  tests/
    engine.test.mjs
+```

The HTML loads the JS module and local stylesheet. app.mjs owns UI, routes, events, state persistence, guide text and optional audio. engine.mjs owns rational parsing, equation transformation, question pools, grading, deduplication and evidence summaries.

Use safe text rendering for notes and user-derived values. Escape values that are inserted into HTML templates. Keep credentials, hidden production answer-policy logic and external model calls out of browser code. Offline-style local answer keys are visible to the device owner; do not make anti-cheat or exam-security claims for this prototype.

The current private Site project has a tracked identity. Preserve that identity on future edits. Package the exact pushed source state. Do not create a new Site just to publish a revision.

## 16 Future AI integration contract

Introduce live AI only after the deterministic lesson is useful and the user chooses a provider and data policy. Host the provider adapter on a suitable server runtime with secrets outside the client. Do not add a provider key to JavaScript, browser storage, source archives or exported progress.

The server should receive a bounded question, lesson ID/version, current equation state, approved source IDs and minimal relevant structured evidence. Student input is untrusted data. Return a validated response, not raw model tokens that can execute commands or change grades.

Suggested response structure:

```json
{
  "schema_version": 1,
  "request_id": "opaque-id",
  "turn_epoch": 4,
  "intent": "explain",
  "segments": [
    {
      "text": "Applying the same operation to both sides preserves equality.",
      "source_ids": ["algebra.balance_rule.v1"],
      "suggested_action": "show_balance"
    }
  ],
  "fallback": false
}
```

Allowed actions must be a small application-owned enum. No generated grade, score, JavaScript, URL, arbitrary coordinates, database instruction or unrestricted tool call is accepted. The browser controls navigation, mathematical operations and evidence writes through typed application actions.

Use a cancelable turn ID and epoch so late responses cannot replace a newer explanation. State explicitly when a fallback is used. Known explanations should remain fast and available without a model. Measure input-to-first-useful-response and user abandonment on the real deployment; do not assume a generic eight-second response target is acceptable.

Add authentication, request size limits, rate limiting, timeouts, cost ceilings, provider failure handling and output validation. Evaluate in-scope questions, misconceptions, ambiguous requests, unsupported topics, answer leakage and prompt injection. Valid JSON and a real source ID do not establish that prose is educationally correct.

A real AI teacher should understand common follow-ups for the supported lesson before being advertised broadly. Do not compensate for an unreliable response by giving it a confident voice or an impressive avatar.

## 17 Accessibility and responsive behavior

All core learning actions must work with mouse, touch and keyboard. Every control needs an accessible name, a visible focus indicator and a clear state. Include a skip-to-content link. Mathematical meaning must exist as text outside decorative SVG.

The current code includes text labels, a textual equation, polite feedback announcements, keyboard-operable native controls, larger learning text, reduced-motion support and responsive navigation. These features are an implementation starting point, not a statement of WCAG conformance or verified screen-reader support.

Next verification must cover at least 390 px, 768 px and desktop widths, browser zoom to 200 percent, long fractions, focus order, dialogs, bottom-nav obstruction, sufficient touch targets, readable captions and control contrast. Test on real mobile browsers because software keyboards and speech support vary.

Avoid excessive announcements when the page rerenders. Preserve meaningful focus after an action. A validation error should be associated with its input; a learner must not have to visually search for it. The future refactor should update the smallest relevant UI region when that improves keyboard and assistive-technology behavior.

Voice must be an optional convenience. Do not require a microphone, speech recognition, hearing or precise drag gestures to finish a lesson. Any later direct manipulation must have equivalent button and keyboard operations.

## 18 Privacy and honest capability communication

The application does not transmit learning records to an LLM or analytics service in this prototype. Hosting still processes normal web requests and private access control. Do not describe private hosting as encryption of local learner data or claim legal compliance solely because progress is local.

Browser text-to-speech may use a local or online voice service depending on the browser and OS. Disclose that possibility in Settings before enabling automatic read aloud. No microphone capture exists in this build. Do not claim all optional speech is offline.

Do not collect real names, schools, contact information, birthdays or personal disclosures to start a lesson. Keep demonstration notes and test data separate from a real learner's records. Public distribution to children requires an owner decision about target ages, countries, disclosures and appropriate review.

Honest UI labels are required: guided preview, planned lesson, supported practice, repeated review and session-only saving. Do not show fabricated users, streaks, success rates, trophies, testimonials, online status or model activity.

## 19 Verification and quality gates

The mathematical engine has meaningful automated tests for exact normalization, invalid inputs, alternative solving orders, equation equivalence, zero-operation rejection, independent answer keys, evidence deduplication, assistance separation and readable equation signs. Run these after changes to math or evidence behavior. Use independent expected values rather than calculating expected answers with the same function under test.

| Scenario | Expected outcome |
| --- | --- |
| First launch | Classroom opens with the example and zero invented progress |
| Subtract 3 then divide by 2 | 2x + 3 = 11 becomes x = 4 |
| Divide by 2 then subtract 3/2 | The same example also becomes x = 4 |
| Multiply or divide by zero | Reject safely; preserve the previous equation |
| Answer using an equivalent fraction | Correct through exact arithmetic |
| Invalid syntax or denominator zero | Format feedback; no evidence record |
| Wrong first answer then correct retry | Preserve first evidence and acknowledge correction |
| Hint before first answer | Record supported practice |
| Hint after a recorded answer | Do not rewrite assistance state of existing evidence |
| Same question repeated | Useful review with no new independent evidence |
| Reload during a lesson | Restore a valid checkpoint and saved notes |
| Storage unavailable | Explain session-only behavior and allow export |
| New notebook text containing HTML | Display harmless text, never executable markup |
| Unknown teacher question | Honest scope response with useful suggestions |
| Planned lesson card | Explicitly unavailable, with no deceptive launch action |
| Optional audio unavailable | Text remains complete and usable |
| Data deletion | Confirm and clear only Scireka's stored learning data |
| Browser back or fragment navigation | Show a supported destination without losing saved work |
| Mobile or enlarged text | No essential off-screen controls or obscured answer field |

At the time of authoring, eight grouped mathematical unit tests passed and JavaScript syntax checks passed. Managed local preview was unavailable because the preview daemon mailbox was absent; that is an environment limit, not a visual QA pass. Any later browser checks must be recorded with the actual build and outcomes in BUILD_STATUS.md. Do not claim teacher pronunciation, responsive appearance or learning effectiveness was verified by unit tests.

## 20 Learner validation before expansion

Run an initial formative study with roughly 12–20 representative learners, with age-appropriate permissions. This is enough to discover usability issues, not enough to prove broad learning effectiveness or market demand.

Compare the same topic in a direct explanation format and the interactive balance format. Keep difficulty and instructional content comparable. Counterbalance order or use comparable alternate problems to reduce carryover. Test realistic versus illustrated teacher appearance separately so multiple changing factors do not obscure the result.

Observe first useful action, where learners hesitate, whether operations make sense, recovery after mistakes, requests for help, perceived tone, actual response latency and whether they choose another short session. Ask learners to explain a step in their own words. Test a fresh unassisted problem immediately and a delayed related problem later. Do not optimize clicks or time spent as a substitute for understanding.

Interview the relevant buyer separately from the learner. Confirm device availability, language, learning context, curriculum relevance and why this experience would be chosen over existing options. Do not infer those preferences from the learner's age alone.

Proposed prototype targets are hypotheses: reach a meaningful action quickly, make hint use understandable, eliminate invalid grading, preserve alternatives, and avoid unexplained waits. Establish measured baselines before fixing universal engagement percentages.

## 21 Revised implementation milestones

| Stage | Deliverable | Gate before expanding |
| --- | --- | --- |
| W0 Web foundation | Static responsive shell, exact engine, typed state conventions and basic tests | Starts reliably with zero sample progress |
| W1 Useful guided lesson | Balance interaction, alternative steps, authored teacher, practice, notes and persistence | Mathematical tests plus observed completion of the core task |
| W2 Refine with learners | Better focus/error handling, misconception prompts, touch and accessibility fixes | Evidence of understanding and recurring usability issues addressed |
| W3 Grounded AI pilot | Server-side provider, bounded context, validation, costs, cancellation and honest fallback | Real model evaluation and review; no grade authority granted to AI |
| W4 Richer learning | Structured intermediate steps, delayed review, transfer tasks and new reviewed topics | Improved independent performance on suitable evaluations |
| W5 Release preparation | Supported-browser matrix, data migrations, threat review, privacy review, deployment checks and beta fixes | No critical errors; actual human reviews complete |
| Optional native phase | Unreal or other rich presentation using stable learning contracts | Learners value the richer environment and the added hardware/support cost is justified |

W0 and substantial W1 behavior are implemented in the current prototype. W1 is not declared fully validated because browser and learner evaluation are separate gates. Do not complete six new topics, an open-world school, multiplayer or a photorealistic avatar before resolving the first lesson's usability questions.

## 22 Acceptance criteria for future design work

A design change must answer a learner need. For each proposed feature, state the observed problem, intended behavior, alternatives, evidence needed and failure handling. Decorative additions are allowed when they improve clarity or comfort, but should not compromise legibility, performance or the time needed to get help.

The refined specification should remain aligned with working UI. Every prominent button must do a useful thing or be explicitly unavailable. Every progress value must come from actual state. Every success claim must correspond to a verified operation. Every future capability must be labeled as future.

Source-only compilation, a deployed URL and passing numerical tests are different kinds of evidence. A deployed Site is not proof of a successful learning product. Keep a concise test report with pass, fail and not-run states instead of blending them into one “done” label.

## 23 Handoff and next task

Give a coding agent this document and the current repository with this instruction:

> Continue Scireka as a web-first learning studio. Preserve the current Site identity and existing learner data. Read BUILD_STATUS.md, run the mathematical tests, and improve the first lesson based on observed usability and learning needs. Keep grading deterministic, alternatives valid, hint use visible and teacher capabilities honest. Prioritize keyboard and mobile behavior, structured reasoning feedback, and learner validation before adding more topics or a live model. Do not replace the working UI with a new template, fake a live AI connection, or claim a production-ready educational product without the required evidence.

The current deliverable is a usable guided web prototype and this updated single-file specification. It is a concrete starting point for testing the experience before committing to the larger realistic AI teacher simulation.