Writing Sidekick (Years 1 to 6)

An iPad web app for primary students. A student picks their year level, photographs their handwritten writing or picks photos of it from the iPad's photo album (up to two pages; a page snapped sideways or upside down is turned upright automatically before it is read), checks the typed-out version (both pages together in one box) by tapping any word to fix it, and gets specific, improvement-first feedback matched to the Australian Curriculum (ACARA v9) expectations for their year. Nothing is ever stored.

What the feedback looks like

The feedback comes as four slides, named to fit the superhero theme: What you did well, Power-ups, Word lab and Mission complete. Back, Next and Finish sit in a bar fixed to the bottom of the screen. Coaching instructions are pitched at the child's year; worked examples demonstrate ambitious, attainable writing: Years 1 and 2 get picture-book sentences, Years 3 and 4 plain words with a hint for any term, Years 5 and 6 the proper names of strategies.

• What you did well (the first slide): up to three real strengths, each quoting the child, then "Your next focus" with a button to Power-up 1. There are no scores or counts. Years 5 and 6 can open "See all your writing skills": one tappable chip per skill (audience, ideas, cohesion and so on), coloured by how it went, each explaining what the skill means in a child's words.
• One to three power-ups (one or two for Years 1 and 2), shown one at a time ("Power-up 1 of 3"; Next reads "I did it! Next power-up" until the last one, and Back steps back through them): the areas with the biggest payoff for this piece. Each card has one teaching focus and one strategy, laid out as three numbered steps in the order the child works: 1 find this line in your book (their own words, quoted); 2 use the strategy (its name, a one-line how-to for this kind of sentence, and the strategy done on a fresh sentence like theirs, before and after, never their own sentence rewritten, so the student applies the strategy independently, with the explanation visible beside the model); 3 do this (one short instruction). A one-line opener says what the line already does well. The strategies are the ones the school teaches (because/but/so, subordinating conjunction start, sentence expansion, sentence combining, elaborating with a detail sentence, transition words, appositives, topic and concluding sentences, sentence types, vary vocabulary, and for older years general-to-specific introductions and their mirror conclusions), only offered from the year they suit; a label that contradicts the job (a "split it up" task named as sentence combining) is dropped rather than shown. Revising comes first; spelling is labelled as editing and comes after. The slide ends with "Pick up your pencil": the child revises in their book, not on the iPad.
• The word lab: word power (four synonyms for each plain word, climbing from a small step up to a stretch word, with the child's sentence rewritten), a synonym challenge from Year 2 up (three more of the child's own words, a box and a Check button each; a tiny AI call says whether the word they typed really is a synonym), and the Editing card.
• The Editing card: up to five of the child's own misspelt words (three in Years 1 and 2), each with a box to type the fix and a hint that points at the part to change, never the answer. The right spelling is shown only after three tries. Punctuation is counted by type for the year (Australian Curriculum v9): Year 1 sentence endings; Year 2 adds list commas; Year 3 adds apostrophes; Years 4 to 6 add speech punctuation. The spelling hints are written in the style of Sounds-Write; the wording is our own and none of their materials are reproduced.
• Mission complete: a tick list built from the feedback (one row per power-up with its line and job, then Word power, Edit and "Read it again like a reader"). Ticks live in memory only, and tapping "I did it! Next power-up" ticks that power-up's row. Save picture, Print and a big "I'm done" button (the same two-tap clear as Finish and clear) finish the job.
• Level up: the child photographs the revised page. The app compares the two versions and gives specific praise for what really changed (which power-ups show up, quoting the new words; which practice words are now spelt right, checked by the server), plus one gentle next tip. Nothing is claimed that is not in the new writing.
• The ten-area check-up (audience, text structure, ideas, characters and setting or persuasive devices, vocabulary, cohesion, paragraphing, sentence structure, punctuation, spelling; nine for reports and poems) is never shown as a list: it drives the writing strength chips (tap one to see that area's strength and next step) and the "What you did well" card. The saved picture and the print-out hold the child's feedback alone; there is no teacher report.
• In Years 1 to 3, a Listen button on every card reads it aloud in the iPad's own built-in voice (it prefers an Australian English voice), so younger readers can hear their feedback. It is free and the words never leave the iPad.

The app is student-only for now: there is no teacher settings screen, students choose their own year level, and the check-up and Listen buttons are always on.

The area names follow the national writing assessment criteria; the descriptions used in the prompt and the app are written in our own words (the marking guides themselves are not reproduced here). The writing strategies follow the approach of The Writing Revolution (the Hochman Method), which the school uses for writing instruction; "strategies" is the book's own word for them, the names are theirs, the explanations and examples are ours, and none of their materials are reproduced. See docs/research/writing-revolution-brief.md and docs/research/twr-section-i.md. The supplied TWR 2.0 sentences section is distilled in api/_twr.js and used by generation and review; the book itself is not uploaded, reproduced, or used to retrain a model.

The approach follows what the feedback research says works: answer "where to next?", stay specific to the task, show the improvement rather than just naming it, and leave the child something to do.

How the AI part works

Two separate steps, so each has one job:

0. Which way up? A small copy of each page goes to the model at low detail, which answers with the turn (0, 90, 180 or 270 degrees) that makes the writing upright. The app turns the page itself before reading it, so a photo taken sideways reads as well as one taken straight. An unclear answer means no turn, and the Rotate button is still there.
1. Reading the handwriting. The photos go to a vision model at full image detail with strict copy rules: keep every misspelling, keep every apostrophe and punctuation mark, leave out crossed-out words, put inserted words where the caret points, keep line breaks and page order. A second pass compares the draft against the same photo. Unreadable words or marks appear as [unclear], never silent guesses. Every year level then checks the typing and can fix anything the app misread before the feedback is requested.
2. Feedback. Only the checked text goes to the model, with the year-level expectations, the genre guide and the skill bank. A separate teaching editor improves the draft and audits editing errors using exact quoted occurrences. The server validates those occurrences and calculates totals; model-supplied totals are ignored. Corrections remain server-side. Each category is validated independently; a capital and an apostrophe can both be fixed on the same word. Pure case, punctuation and spacing changes are classified by their actual change. Incomplete or invalid audits get one focused recheck when time permits, without regenerating the teaching feedback. If that fails, confirmed categories remain visible and only unresolved counts show unavailable, never a guessed zero. A failed teaching review asks the child to retry instead of displaying unchecked feedback.

The extra image check is bounded to 25 seconds. Feedback generation has 30 seconds. The independent teaching review (up to 100 seconds) and the editing audit (up to 90 seconds, low reasoning) then run side by side, all within a 170-second server budget under the client's 180-second limit. The audit is a separate call on purpose: when it lived inside the review, real two-page writing made the reviewer reason past its time and token limits and the child saw an error instead of feedback. The reviewer uses medium reasoning and the complete output schema, and checks the student's existing skills and surrounding sentences before choosing targets. Provider retries share the same time budget. The optional editing recheck gets at most 25 seconds from whatever budget remains; it adds no extra call when the original audit is valid. Each stage logs a one-line reason to the server log when it fails (never the child's writing). These checks add model cost and latency; they reduce failure modes but cannot guarantee perfect handwriting or feedback.

Photos are cleaned up on the iPad first (uneven lighting flattened so the page reads white and the ink dark, like a phone's document scan) and sent at up to 2000 pixels.

Try it on this computer (no AI key needed)

Double-click start-app.bat. A browser opens with the app in practice mode: the feedback is a canned example, but every screen works.

Real feedback needs an OpenAI key

1. Copy .env.example to a new file called .env.
2. Paste your OpenAI API key into it, on the line that mentions the key.
3. The .env file stays on this computer; it is ignored by version control and never shared.

Feedback and the reading step both default to gpt-6.1-terra (switched on 2026-10-27). For feedback, a side-by-side run on 27 invented pieces had it deliver 26 (gpt-5.6-terra 17), in a median 20 seconds instead of 95, for about half the cost. For reading, on 9 real scanned pages read three times each, it got 4 or 5 of 20 hand-checked hard words wrong where gpt-6-sol got 10 or 11, mostly because it kept children's misspellings as written. It was also faster and half the price. OPENAI_MODEL changes the feedback model and OPENAI_TRANSCRIBE_MODEL the reading step. The independent teaching/editing reviewer follows the feedback default; OPENAI_REVIEW_MODEL overrides it. Any model you pick must accept reasoning_effort: "none" (gpt-6.1-sol and gpt-6-astra do not). The Listen buttons no longer use OpenAI: they use the iPad's own voice. The old paid voice (api/speak.js, gpt-4o-mini-tts with marin) is switched off; set SPEAK_ENABLED=1 in Vercel to turn it back on (OPENAI_TTS_MODEL and OPENAI_TTS_VOICE then apply), and the app would need changing to call it again.

Two things keep the cost down (measured 2026-10-01: about 3c per piece in a class, down from 9c):

• Prompt cache. The draft and review prompts mark where the rulebook a class shares ends, so the next child in the same year and genre reads it at a tenth of the price. The child's writing is never cached. Only the run-on note quotes the child, so it sits after the markers. Keep the rest of the prompt order as it is: regrouping the sections changed the teaching review's judgement on a strong poem.
• Flex lane. Reading the page, the draft, the editing audit and the review ask OpenAI for its half-price flex service tier. When OpenAI is busy it answers 429 at once (free) and the request goes again at the normal price. Set OPENAI_FLEX=off in Vercel if feedback ever gets slow, or if you switch to a model that does not offer the flex tier. Server logs say "flex lane busy" each time a request is bounced.

The live site

Share this link: https://wesdlpteam.github.io/writing-sidekick/

The page is hosted by GitHub Pages straight from the main branch of this repo, so every push to main updates the live site within a minute or two.

GitHub Pages only serves files, so the one server function (api/feedback.js, the part that talks to OpenAI) runs on Vercel at https://writing-sidekick.vercel.app and accepts browser calls only from the GitHub Pages address. Vercel also redeploys on every push. The OpenAI key and model names live as environment variables in the Vercel project settings, using the same variable names as .env.example. They are never in the repo.

On an iPad, open the site in Safari and use Share, then Add to Home Screen, so it looks and launches like a normal app.

Privacy and safeguarding

• No accounts, no database, no analytics, no browser storage. The server function responds and forgets. On the iPad everything stays in memory until "Finish and clear", leaving the page, or 25 minutes untouched on the feedback screens and 10 minutes on the others (a warning shows first).
• The photo and typed writing do go to OpenAI's API to be read and given feedback. The read-aloud voice is the iPad's own, so those words stay on the iPad. privacy.html (linked from the app as "For adults") is a draft explanation for parents and staff; the school must confirm the retention arrangement on its OpenAI account and the processing regions, then approve the wording.
• Photos are only included in a saved picture or print-out when the child ticks the box.
• Before any feedback, the writing goes through a safeguarding check (api/_safety.js): narrow local rules for plain first-person disclosures, then OpenAI's moderation check. A flagged piece gets a trusted-adult screen with a note for the teacher instead of feedback, and the feedback model is never asked about it. The wording is a draft for the school's safeguarding lead to approve. Phone numbers, emails and street addresses are blanked before ordinary writing goes to the feedback model.
• The feedback may only quote, correct or swap words that really are in the child's writing; anything else is dropped before it is shown.
• Students are reminded to cover their name before photographing, and the AI is told never to use or repeat a name even if one appears.
• The OpenAI key lives only in server environment variables. The functions refuse any request that does not come from the app's own pages. APP_PAUSED=1 switches every AI call off; ALLOWED_ORIGINS adds extra allowed sites; OPENAI_BASE_URL can point at an approved regional endpoint; OPENAI_MODERATION_MODEL changes the safety check's model.
• Still open (from the September 2026 audit): a classroom sign-in so only the school's devices can spend on the AI, and durable per-day quotas. Until then, set a spending limit and alerts on the OpenAI account.

Where things live

• index.html, css/, js/: the app the student sees
• art/: the Writing Sidekick hero artwork
• api/feedback.js: the server function that talks to OpenAI (both steps)
• api/speak.js: the old paid read-aloud function (off unless SPEAK_ENABLED=1; the app uses the iPad's voice, js/speech.js); api/_cors.js (the request gate) and api/_provider.js (provider address and timeouts) are shared by both
• api/_safety.js: the safeguarding check and the trusted-adult response
• privacy.html: the adult-facing explanation of where writing goes (draft)
• api/_curriculum.js: per-year writing expectations, distilled from curriculum/english-curriculum-f-6-v9.md (ACARA v9, © ACARA 2022)
• tests/: run with npm test
• docs/superpowers/: design and build plan documents

Cost

Cost depends on the models, input length, image detail and review reasoning. Earlier two-call estimates no longer apply to the image verification and deeper teaching review. Check actual usage in the provider account. A cheaper draft model does not remove the independent review cost. The September age/attainment matrix took about 45–67 seconds per feedback request; these are observations, not a latency guarantee.

Checking age and writing quality

Age controls coaching readability and curriculum expectations. Demonstrated sentence control, idea development and organisation control the next teaching step and worked model. Strong younger writers should receive a worthwhile refinement; older foundational writers should receive a manageable scaffold. A concise persuasive topic sentence stays concise, and its support follows in separate sentences. Genuine strength ratings can receive stretch tasks.

The invented fixtures in tests/fixtures/quality-samples.mjs pair three writing levels with Years 1–6. tests/fixtures/quality-holdouts.mjs adds new topics, genres and edge cases. Run npm run quality:live for the matrix, or npm run quality:live -- output/quality-holdouts holdouts for the holdouts. These commands load local API configuration, send invented text to the configured provider, incur usage charges and save results locally. They do not send student photos. Inspect the output against docs/audits/2026-09-10-age-attainment-quality.md; HTTP success does not establish teaching quality. Ordinary npm test uses no live provider.