termi-kids 0.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 dannyliv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Supplementary notice (this restates, and does not replace or modify, the
+warranty disclaimer and limitation of liability in the MIT License above):
+
+Termi is free and open-source software intended for personal, educational
+use. It is provided as-is, and all use is at the user's own risk and sole
+responsibility. The user who installs and configures the software is
+responsible for its configuration, for the AI provider accounts it connects
+to, and for supervising any children who use it. The authors and
+contributors accept no liability for any claim, damages, or other losses
+arising from the use of this software.

package/README.md

@@ -0,0 +1,148 @@
+# Termi
+
+Termi is a friendly robot that helps you build things on a real computer.
+
+You type what you want. Termi writes the code with you. Your game opens in the browser right away.
+
+You can make dodge games, platform games, pixel art, dance music, virtual pets, adventure stories, quizzes, your own web page, and talking characters. If you change your mind, type `undo` and the last change is gone. When something works, you earn badges.
+
+Termi is a computer program, an AI tool. It is not a person. A grown-up sets it up first.
+
+Not sure what to say first? Type `/quest` inside any project. Termi walks you through a real build, step by step, with a ready idea at every step. Press Enter to use it, or type your own. Finish a quest and you earn the Quest Hero badge.
+
+Want to get good at building with AI? Type `termi learn`. Six short lessons teach you how to be the boss of your AI helper. Each one earns a badge, and you can replay them any time.
+
+Ready? Ask a grown-up to read the next part.
+
+---
+
+## For parents and guardians
+
+Termi is a kids-friendly coding assistant that runs entirely in the terminal on your own computer. A kid describes what they want in plain words, an AI model you configure writes small web projects (plain HTML, CSS, and JavaScript), and a local preview shows the result instantly. Every message in and out passes a layered safety pipeline, and everything is stored locally. There are no Termi servers and no telemetry.
+
+Please read [SAFETY.md](SAFETY.md) before handing the keyboard to your kid. It explains, honestly, how the safety system works, what it can and cannot stop, and how to remove everything.
+
+### Requirements
+
+- Node.js 20.19 or newer: https://nodejs.org
+- macOS, Windows, or Linux
+- An AI account you own (one of: a ChatGPT account, a Claude API key, an OpenAI API key, or a Grok API key)
+- About 700 MB of free disk space for the on-device safety checker (recommended, on by default)
+
+If Node is too old, Termi prints a plain message with the download link instead of starting.
+
+### Install
+
+One command:
+
+```
+npm install -g termi-kids
+```
+
+Then run `termi`. If npm reports a permission error, prefix the install with `sudo` on macOS and Linux, or run the terminal as administrator on Windows. To remove it later, run `npm rm -g termi-kids` (full cleanup steps are in SAFETY.md).
+
+To hack on Termi instead, install from a clone:
+
+```
+git clone https://github.com/dannyliv/Termi.git
+cd Termi
+npm install
+npm run build
+npm link
+```
+
+### First run: the setup wizard
+
+Run `termi`. The first run starts a setup wizard for a parent or guardian. It takes about five minutes:
+
+1. **Create a grown-up PIN** (at least 4 characters). It guards the grown-up zone. Your kid should not know it.
+2. **Age band and consent.** You pick "Under 13" or "13 or older" and confirm that Termi uses an AI account you own and that you agree to watch how your kid uses it. This consent is recorded in the local safety log.
+3. **Pick an AI provider.** The default is "ChatGPT sign-in": your browser opens, you sign in to your own ChatGPT account, and no API key is needed. The other options are a Claude API key, an OpenAI API key, or a Grok API key. Grok requires an extra confirmation because the xAI API terms are adults-only (details in SAFETY.md). You can add several providers and choose which one is active.
+4. **Pick a safety level.** Strict is the default and the right choice for most kids.
+5. **Safety checker download.** Termi offers a small safety model (623 MB) that screens every message right on your computer, even with no internet. It is on by default and worth keeping. The download runs in the background: setup continues, your kid can start building right away, the home menu shows a progress bar, and the checker turns itself on the moment the verified file lands. An interrupted download resumes on the next start. Details are in [SAFETY.md](SAFETY.md).
+6. **Hand the keyboard to your kid.** The kid picks a made-up nickname (Termi asks them not to use their real name) and sees a clear disclosure: "Termi is a computer program, an AI. It is a tool a grown-up set up for you. It is not a person."
+7. **Desktop shortcut.** Termi offers to write a double-clickable launcher on the Desktop (`Termi.command` on macOS, `Termi.bat` on Windows, `Termi.desktop` on Linux) so your kid can come back tomorrow without typing commands.
+8. **Optional first game.** Two keypresses later there is a running game in the browser.
+
+If you skip the provider step, Termi runs in offline mode: your kid can still create projects, play them in the preview, undo changes, and browse ideas. The chat shows a kind "ask a grown-up to set up the AI helper" screen.
+
+**If your kid does not know where to start:** every project type has a Build Quest (`/quest` in the chat), a five-step guided build with a ready prompt at each step, and a large idea deck (`/ideas`). Quest steps go through the same safety pipeline as any other message.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `termi` | First run: setup wizard. After that: the home menu. |
+| `termi new` | Start a new project. |
+| `termi go [name]` | Open a project and build. With no name, pick from a list. |
+| `termi preview [name]` | Open a project in the browser without the chat. |
+| `termi ideas` | Print fun project ideas. |
+| `termi learn` | Six short, replayable lessons on building with AI. Fully offline, no AI calls. |
+| `termi grownups` | The grown-up zone. PIN required. |
+| `termi help` | Show the command list. |
+| `termi --version` | Show the version. |
+
+Inside the build chat, these slash commands work:
+
+| In chat | What it does |
+|---|---|
+| `/preview` | Open the project in the browser. |
+| `/undo` | Take back the last change. |
+| `/redo` | Bring a change back. |
+| `/new` | Start a fresh project. |
+| `/ideas` | Get fun ideas. |
+| `/badges` | See earned badges. |
+| `/learn` | Play the short AI lessons. |
+| `/quest` | A step-by-step build guide with a ready prompt at each step. |
+| `/help` | Show this list. |
+| `/done` | Finish and celebrate. |
+| `/quit` | Stop for today. Projects are saved. |
+| `/grownups` | Grown-up zone, PIN required. |
+
+Plain words work too: `undo`, `help`, `ideas`, `done`, `preview`, `badges`, `learn`, `quest`, and `quit` work on their own, no slash needed, and `exit`, `stop`, `bye`, and `leave` also quit. (`redo`, `new`, and `grownups` need the slash.) Misspelled commands get a "did you mean" suggestion.
+
+In the grown-up zone you can add, switch, or remove providers, change the safety level, manage the on-device safety checker (turn it on or off, download or remove its model file), pick the model speed (Zippy, the fast default, or Extra smart for tricky asks), read the usage and quota note, review the safety log, and see exactly where your data lives. Removing a provider deletes its saved key or sign-in from this computer.
+
+### The nine project types
+
+| Project type | What your kid builds | Styles |
+|---|---|---|
+| 🎮 Games | A quick dodge game. A great first project. | Space Rocks, Neon Star Run, Spooky Bats, Soccer Headers |
+| 🕹️ Big Games | A bigger platform game with two levels. The game engine ships as a local file, no internet needed. | Castle Quest, Blocky Mine World, Haunted House, Midnight Wolf Pack |
+| 🎨 Pixel Studio | A pixel paint studio. Calm and creative. | Free Draw, Pet Portraits |
+| 🎵 Dance Party | A music maker with sounds made right in the browser. | Robot Dance, Glow Disco |
+| 🐾 My Pet | A virtual pet that remembers its care between visits. | Dragon, Wild Horses |
+| 📖 Story Quest | A choose-your-own-adventure story engine. | Dragon Treasure, Mystery at School |
+| ❓ Quiz Show | A quiz maker for friends and family. | Animal Trivia, Which Character Are You? |
+| 🌐 My Page | A personal web page, saved only on this computer. | About Me, My Team |
+| 🤖 Talking Character | A scripted talking character. The kid writes every line it can say. No AI runs inside the project. | Quiz Host, Sidekick Robot |
+
+Projects live in `~/Termi/<project-name>/` as plain files (typically `index.html`, `style.css`, and one JavaScript file, plus a `TERMI.md` notes file). They are capped at 8 files of 256 KB each, use no build step, and work with zero network access. Once a kid has a project, `termi new` also offers "Remix one of your projects."
+
+On the My Page projects, personal details like a name are typed directly on the page in the browser preview and saved to the browser's local storage on this computer. They never pass through the chat, so they never reach the AI provider.
+
+### How the preview works
+
+Each open project gets its own tiny web server bound to `127.0.0.1` only. It is not reachable from other devices on your network. It starts at port 4311 and scans upward if that port is busy. Every page is served with a strict Content-Security-Policy that blocks all outside network access from the project, and the page reloads automatically when Termi changes a file. Dotfiles and the `TERMI.md` notes are never served.
+
+### More than one kid
+
+Termi's v1 stance is simple: one operating system user account per kid. Settings, the PIN, projects, badges, and the safety log all live in the OS user profile, so separate OS accounts keep kids' worlds (and the audit trail) separate. There are no in-app profiles.
+
+### Troubleshooting
+
+- **"Termi needs a newer version of Node.js."** Install the current version from https://nodejs.org, then run `termi` again.
+- **"The AI helper is not set up yet."** No provider is configured. Run `termi grownups`, open Providers, and add one. Projects, previews, undo, ideas, and badges all work without a provider.
+- **"Termi used up its energy. It comes back at 4:30 PM."** Your AI plan or API key hit its rate limit. The time comes from the provider when it says how long to wait. Your kid can keep playing the preview, use `/undo`, and browse `/ideas` meanwhile.
+- **"Termi needs a quick break. Try again in a minute."** A safety check could not finish (a timeout, a provider error, or a rate limit). Termi blocks rather than guesses, so it pauses the turn. Trying again usually works.
+- **"The sign-in stopped working."** The saved ChatGPT sign-in can no longer refresh. Run `termi grownups`, open Providers, and sign in again.
+- **"Termi found changed settings. Safe settings are on now."** The settings file failed its integrity check, so Termi reverted to strict defaults. Review the grown-up zone.
+- **Crashes.** The kid sees a friendly screen; the technical details go to `~/.termi/error.log`.
+
+### Uninstall
+
+See "Your data and how to remove Termi" in [SAFETY.md](SAFETY.md) for the exact folders, files, and keychain entries.
+
+## Disclaimer
+
+Termi is free and open-source software, released under the MIT License and provided as-is, without warranty of any kind, express or implied. It is a personal, educational project. All use is at the user's own risk and sole responsibility: you, the parent or guardian who installs and configures Termi, are responsible for how it is set up, which AI accounts it connects to, and how children in your care use it. AI output is unpredictable; the safety layers reduce risk but cannot eliminate it, and children should use Termi with adult supervision. The authors and contributors accept no liability for any claim, damages, or other losses arising from the use of this software, as set out in the MIT License. Termi is an independent project and is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, xAI, the Qwen team, or any other AI provider.

package/SAFETY.md

@@ -0,0 +1,187 @@
+# How Termi keeps kids safe, and what it cannot do
+
+This page is for parents and guardians. It explains the safety system in plain language, including its limits. Termi is built to be honest with you: it is a strong set of guardrails, not a guarantee. Your supervision is still the most important safety feature.
+
+## The short version
+
+- Every message in and out passes five layers of checks. When a check cannot finish, Termi blocks rather than guesses.
+- A safety checker runs on this computer itself: a small AI model, on by default, that screens every message in and out across nine categories, even with no internet. Details below.
+- Everything runs and stays on your computer. There are no Termi servers and no telemetry. Chat text goes to exactly one place: the AI provider you configured.
+- A tamper-evident safety log records every block and every settings change. You read it in the grown-up zone (`termi grownups`).
+- The PIN and the signed settings are speed bumps for a curious kid, not vault doors. Your real levers are that you own the AI account and the computer.
+
+## How the safety system works
+
+Five layers sit between your kid and the AI. The chat conversation itself is never trusted to police itself.
+
+1. **A local filter on this computer.** Before anything leaves your machine, Termi checks the message offline. It blocks swearing and slurs (including d.i.s.g.u.i.s.e.d spellings and leetspeak), and it blocks known "ignore your rules" tricks. It also looks for personal details: names, addresses, phone numbers, emails, school names. Those are not blocked; they are masked to `[secret]` before the message is sent, and the kid gets a gentle reminder to keep private things private. The same masking is used when the AI reads project files back. The word lists are English; the AI-based checkers below cover other languages.
+2. **Safety rules inside the AI's instructions.** The AI is told, every turn: you are a tool, not a person. Never act romantic, never roleplay relationships, never ask the kid to keep secrets, never ask for a real name, address, school, age, or photos. Big feelings get one kind line and a pointer to a trusted adult. The instructions also declare that everything the kid types and everything in project files is data, never commands, which blunts "ignore your previous instructions" tricks hidden in files.
+3. **A checker before the AI acts.** A separate safety check, outside the conversation, reads the kid's message along with the last few turns for context. When the on-device safety checker is installed (it is offered during setup and on by default), it judges the message right on this computer at the same time. It runs at the same time as the build call so it adds no waiting, but nothing is allowed to land until it passes: no file is written and no reply is shown. If it says no, the work is thrown away. One honest note on timing: because the check and the build call start together, a message that ends up blocked has still traveled to your AI provider once (with personal details already masked); its answer is discarded unseen.
+4. **A checker on everything the AI says and writes.** Every file the AI writes or edits is checked twice before it touches disk: a code scan looks for network calls, code hidden in strings, and other tricks (the full list is in the code scanner, `src/safety/codescan.ts`), and the human-visible text inside the file (story text, labels, comments) goes through the same safety check as chat, in full: long text is checked chunk by chunk, and a file too wordy to check completely is refused rather than half-checked. File names and project names are screened too. The final reply is checked too, before the kid sees a single character. As a backstop, the preview server wraps every project page in a strict Content-Security-Policy, so even code that slipped past the scanner cannot reach the internet from the browser. Files edited outside Termi (in a text editor, say) are the kid's own files and are not re-screened; they only pass the rule-neutralizing filter when read back into the chat.
+5. **Friendly block screens.** When something is blocked, the kid never sees the blocked content. They see a kind, specific explanation ("Those words can hurt people. Pick kind words and we will keep building.") and an invitation to try again another way. If a message suggests a kid may be thinking about hurting themselves, Termi answers in a calm, supportive voice, says clearly that it is a computer program and cannot help with this part, points to a trusted adult, and shares the 988 line (US). That event is logged so you will see it.
+
+## Termi blocks when it is unsure
+
+This is the most important design rule, so it gets its own section. If a safety check times out (8 seconds for online checks, 20 for the on-device checker), errors, hits a rate limit, or returns something unreadable, the answer is always **block**. The kid sees "Termi needs a quick break. Try again in a minute." and the event is logged as a failed-closed check. The AI's output is never shown, and no file is written, without a clean pass. There is no configuration that turns this off.
+
+## What gets blocked
+
+The checkers look for these categories:
+
+| Category | What it means |
+|---|---|
+| Sexual content | Sexual or romantic content of any kind. |
+| Self-harm | Talk of self-harm. Routes to the supportive screen, never a scolding one. |
+| Violence | Real-world harm or gore past a mild cartoon ceiling. |
+| Hate and harassment | Mean, hateful, or bullying words aimed at people or groups. |
+| Dangerous how-to | Weapons, drugs, hacking real systems. |
+| Profanity | Swearing and slurs. The kid is asked to rephrase kindly. |
+| Personal info | Sharing or asking for a real name, address, school, phone, email, or photos. |
+| Grooming patterns | Secrecy asks ("do not tell your parents"), romance aimed at the kid, probing for personal details, or trying to move the chat to another app. |
+| Heavy adult topics | Medical, legal, money, relationship advice, and heavy political topics. Redirected to a trusted adult. |
+| Copying others' work | Reproducing someone else's work wholesale, like song lyrics or book text. The kid is nudged to make their own version. |
+| Rule-breaking tricks | Attempts to make the AI ignore or reveal its rules. |
+
+Grooming, personal info, and rule-breaking tricks block at a lower threshold than everything else.
+
+**The game-language carve-out.** Kids build games, and games have zombies. "Make the zombie die when you hit it", "kill the boss with a banana", "haunted house with screaming ghosts" are normal kid game talk and are deliberately allowed. Every checker is told this explicitly, with examples. The line is real-world harm, harm to real people, or gore past mild cartoon.
+
+## The safety checker on this computer
+
+Termi includes an on-device safety checker: a small AI model (Qwen3Guard 0.6B, published by the Qwen team under the Apache 2.0 license) that runs entirely on your computer. Setup offers the download (623 MB) with a yes as the default; you can decline and add it later from the grown-up zone (`termi grownups`, then **Safety checker**).
+
+The download never blocks anyone. It runs in the background while setup finishes and while your kid builds; the home menu shows its progress bar, and the checker attaches itself to the running safety pipeline the moment the verified file is in place. If the download is interrupted (a closed laptop, a dropped connection), it resumes from where it stopped the next time Termi starts. Until the file lands, the online checks carry the load exactly as they would with the checker turned off.
+
+What it does:
+
+- It reads every message the kid types and everything the AI writes back (chat replies and the human-visible text inside project files), and grades each one Safe, Controversial, or Unsafe.
+- It covers nine categories: violent content, illegal acts, sexual content, personal details, self-harm, unethical acts, heavy political topics, copying others' work wholesale, and rule-breaking tricks. The table above shows where each lands in Termi's block messages.
+- Unsafe always blocks. Controversial blocks for personal details and rule-breaking tricks, and otherwise counts toward the session watch rather than blocking a creative kid mid-build.
+- It needs no internet and costs nothing per use.
+- It runs **alongside** the online checks, never instead of the grooming watch: all verdicts merge and the strictest one wins.
+
+Integrity: the downloaded file is verified on disk against a pinned cryptographic fingerprint (SHA-256) before it is put in place, and the fingerprint is checked again every time the model loads, so a swapped or altered file never runs as the checker. The model file lives in `~/.termi/models/`. You can remove the file or turn the checker off any time in the grown-up zone (removing the file also turns it off); Termi then runs on the online checks alone. If the file goes missing while the checker is on, that is written to the safety log and the download restarts by itself.
+
+One honest note: this is a small model. It is good at its nine categories, it is not perfect, and it changes nothing about the block-when-unsure rule or your role as the adult in the room.
+
+## Watching for grooming across the whole conversation
+
+Grooming rarely shows up in one message. It builds. So Termi keeps a running watch across the session, not just per message:
+
+- The checkers see a sliding window of the last 10 turns, so a pattern can be judged in context.
+- Termi counts signals across the whole session in four families: secrecy asks, affection escalation ("you're my special friend"), probing for personal details, and attempts to move the chat to another platform (named chat and social apps, "text me at", "DM me"). The counters watch the conversation itself, what the kid types and what Termi replies. The kid's own story and game text does not count, so a virtual pet that says "do you love me" cannot trip the grooming watch.
+- Two signals in any one family, or three across families, trips a hard block, no matter what any single message looked like on its own.
+
+A tripped grooming watch is written to the safety log as a flagged entry. In the grown-up zone it is shown first, in red, with a clear "REVIEW FIRST" marker and a suggestion to talk with your kid.
+
+## The safety log
+
+Termi keeps an append-only log at `~/.termi/audit.log`. It records blocked messages, masked personal info, failed-closed checks, settings changes, provider changes, wrong PIN tries, PIN resets, recorded consent, and grooming flags. Each entry carries a timestamp, which layer fired, the category, and a short snippet (at most 80 characters) for context. Personal details are masked before they can land in the log.
+
+The log is tamper-evident: every line carries a cryptographic code (an HMAC-SHA256 chain) that covers the line before it, with the key held in the system keychain. Editing or deleting any line breaks the chain from that point on. When the log passes 5 MB it rotates to `audit.log.1`, and the chain carries across the rotation.
+
+To read it: `termi grownups`, enter your PIN, pick **Safety log**. Termi first verifies the whole chain and tells you plainly whether it checks out ("Log check: good. 41 entries, none changed.") and then shows the recent events in plain words, grooming flags first.
+
+One honest limit: the chain proves entries were not edited. It cannot prove the whole file was not deleted. An empty log on a machine that has seen weeks of use is itself a signal.
+
+## What a determined kid can and cannot get past
+
+Honesty matters more than comfort here. The threat model is a clever kid with ordinary (non-admin) access to their own account on the computer.
+
+What the speed bumps do:
+
+- **The PIN** gates the grown-up zone. It is stored only as an scrypt hash in the system keychain. Five wrong tries lock it for five minutes. The forgot-PIN reset is deliberately useless to a kid: it wipes the PIN, every stored AI key, and the saved sign-in, and restores the strictest defaults. Resetting gains them an unconfigured app and a logged `pin_reset` event you will see.
+- **Signed settings.** `settings.json` carries a cryptographic signature. Hand-editing it (say, flipping a setting in a text editor) fails the check on the next start: Termi reverts to the strictest defaults, tells the kid on screen, and logs it.
+- **A setup marker in the keychain.** Deleting the whole `~/.termi` folder does not give the kid a fresh, parent-free setup. Termi notices the mismatch, falls back to strict defaults, and logs it. The PIN, also in the keychain, survives the deletion.
+
+What a determined kid can still do, told plainly:
+
+- They run Termi under their own OS account, so the OS will let that account read its own keychain entries and files. A kid who knows their way around Keychain Access (macOS), Credential Manager (Windows), or the Linux secret service can read or delete Termi's stored secrets, including a stored API key.
+- They can delete files: the safety log, the settings, the whole folder. Termi detects and logs what it can, fails to strict defaults, and the missing history is visible, but deletion itself cannot be prevented by an app.
+- They can bypass Termi entirely. An API key, once read, works in any tool. A ChatGPT sign-in in the browser is the same account without any of Termi's filters.
+
+The real levers, and they are good ones:
+
+- **You own the AI account.** You can see usage on the provider's dashboard, rotate or revoke an API key in one click, and set spending limits there. Termi never needs to know.
+- **OS parental controls** (Screen Time on macOS, Family Safety on Windows) control what the computer itself allows, below anything Termi can do.
+- **One OS user account per kid.** This is also Termi's multi-kid answer: settings, PIN, projects, and the safety log all live per OS account.
+- **The safety log plus a conversation.** The log is designed to support a talk, not surveillance: it stores categories and short snippets, not transcripts.
+
+One more honest note: the keychain stores Termi's secrets on a best-effort basis. On systems without a usable keychain (some Linux setups), Termi falls back to a plain file at `~/.termi/secrets.json` and tells you so with a warning banner in the grown-up zone.
+
+About the safety level setting: the wizard and the grown-up zone offer Strict and Standard. In the current version both levels apply the same blocking thresholds; the setting is recorded for future tuning. Leave it on Strict.
+
+## Privacy and COPPA posture
+
+Termi is built so that the developer never touches your family's data, because there is nothing to send it to:
+
+- **100% local.** No Termi servers exist. No telemetry, no analytics, no crash reporting, no account with Termi. Nothing phones home.
+- **Chat goes to one place.** The kid's messages (after personal-info masking) and the project files go only to the AI provider you configured, to generate the code and run the safety checks. No other network calls are made on the kid's behalf.
+- **You are the account holder.** Termi has no relationship with your child. You bring your own AI account, you attest to your kid's age band during setup, and your consent is recorded, timestamped, in the local safety log. The AI provider's privacy policy governs what happens to text sent to it; that is a relationship between you and the provider you chose.
+- **Personal info is kept out of the AI.** The local filter masks names, addresses, phones, emails, and school names before sending. On "My Page" website projects, personal touches like a name are typed directly into the page in the browser preview and saved in the browser's local storage on this computer; they never pass through the chat, so they never reach the AI provider at all.
+- **Kid projects are plain files** in `~/Termi`, readable and yours forever.
+
+## Notes on each AI provider
+
+Whichever provider you pick, the kid sees this disclosure, word for word, during setup: "Termi is a computer program, an AI. It is a tool a grown-up set up for you. It is not a person."
+
+**ChatGPT sign-in (the default).** You sign in to your own account in your browser; Termi never sees your password. The sign-in tokens are stored in `~/.termi/auth.json` with owner-only file permissions. During sign-in, Termi also tries to create an API key on your OpenAI account (a standard token exchange). When that works, the broad safety checks run on OpenAI's free moderation service instead of your chat plan. OpenAI publishes guidance for apps used by minors that calls for content filtering and adult oversight; Termi's filtering layers and your safety-log review are how this app approaches that. If your kid is under 13, also consider asking OpenAI about Zero Data Retention for your organization so chat text is not retained on their side.
+
+**OpenAI API key.** Same model family, billed per use on your key. The free moderation endpoint covers the broad safety checks.
+
+**Claude API key (Anthropic).** Build calls use a main Claude model; the safety checks use a small, fast Claude model. Billed per use on your key.
+
+**Grok API key (xAI), with eyes open.** xAI's API terms are for adults, which is why the wizard makes you confirm, explicitly, that the account is parent-owned and parent-watched before a Grok key is saved. The confirmation is enforced in code, not just in the wizard: a Grok key that lands in the keychain by any other path will not run until a parent has confirmed. Grok is never a default; you must pick it. When Grok builds, the fast model handles quick asks and the bigger model handles "Extra smart" mode; the safety checks run on the fast model. You can remove the key at any time from the grown-up zone (Providers, then "Remove a provider"). Also be aware: if Grok is your only configured provider and the on-device safety checker is not installed, Grok checks itself. That is the weakest safety configuration Termi supports. Keeping the on-device checker installed gives every setup, including this one, an independent screen across the broad categories. If you use Grok for building, we still recommend also adding an OpenAI or Claude key so a second, independent model runs the grooming-focused checks; Termi automatically prefers the strongest available checker regardless of which provider builds.
+
+## What one kid message costs
+
+Honest quota math. Each message your kid sends makes these AI calls:
+
+1. One safety check on the message (runs alongside the build call, so it adds no waiting).
+2. One build call. This is the big one; it does the actual thinking and writing.
+3. One safety check on each file the AI writes or edits that turn.
+4. One safety check on the final reply.
+
+So a message where the AI edits one file costs one build call plus three small checks. The checks are deliberately tiny: capped prompts, short answers. The build call accounts for nearly all of the cost or quota. The on-device safety checker adds its screening free, on your computer, on top of the online checks; it never replaces them, so its presence changes safety coverage in one direction only: up.
+
+Where those calls land depends on your setup:
+
+- **ChatGPT sign-in:** build calls use your ChatGPT plan. If the sign-in minted an API key, the safety checks use the free moderation service plus very small per-use mini-model calls on that key, not your chat plan. If it did not, the safety checks share your chat plan, so a busy kid drains the plan a little faster.
+- **API keys (OpenAI, Claude, Grok):** everything is per-use on your key. Small models handle the checks, and a file whose text has not changed is not re-checked within a session.
+
+The grown-up zone has a **Usage and quota note** screen that states this for your exact setup. When a plan or key runs dry, the kid sees "Termi used up its energy", with the comeback time when the provider supplies one, and everything offline (playing the game, undo, ideas, badges) keeps working.
+
+## Where your data lives, and how to remove everything
+
+Everything Termi stores, in two folders plus the system keychain:
+
+`~/.termi/` (Termi's state):
+
+| File or folder | What it is |
+|---|---|
+| `settings.json` | Settings, cryptographically signed |
+| `auth.json` | ChatGPT sign-in tokens (only if you used the sign-in) |
+| `audit.log`, `audit.log.1` | The safety log and one rotated older file |
+| `error.log` | Crash details (for grown-ups; the kid sees a friendly screen) |
+| `badges.json` | Earned badges |
+| `snapshots/` | Saved file versions that power undo |
+| `models/` | The on-device safety checker's model file (623 MB), if downloaded |
+| `locks/`, `pin.lock` | Small bookkeeping files |
+| `secrets.json` | Only on systems with no keychain: the fallback secret store |
+
+`~/Termi/` holds the kid's projects as plain HTML, CSS, and JavaScript files. They are yours; keep them if you want the games.
+
+The system keychain holds entries under the service name **`termi-cli`** with these account names: `pin-hash`, `setup-marker`, `hmac-key`, `install-id`, `api-key-openai-api`, `api-key-anthropic`, `api-key-xai`. (Only the ones you actually used will exist.) The grown-up zone's **Your data and uninstall** screen prints this same list with your machine's exact paths.
+
+Full uninstall:
+
+1. Remove the command: `npm rm -g termi-kids` (if you installed from a clone instead, `npm rm -g termi`, then delete the cloned folder).
+2. Delete `~/.termi`.
+3. Delete `~/Termi`, or keep it for the projects.
+4. Delete the keychain entries: on macOS open Keychain Access and search `termi-cli`; on Windows use Credential Manager; on Linux use your keyring app (for example Seahorse), or just delete `~/.termi/secrets.json` if the fallback was in use.
+5. Delete the Desktop launcher if you created one: `Termi.command` (macOS), `Termi.bat` (Windows), or `Termi.desktop` (Linux).
+6. Optionally, rotate or revoke the credentials you used: delete the API key in the provider's console, or revoke the app sign-in from your OpenAI account's security settings. Uninstalling Termi does not touch your AI provider account.
+
+## Disclaimer
+
+Termi is free and open-source software, released under the MIT License and provided as-is, without warranty of any kind, express or implied. It is a personal, educational project. All use is at the user's own risk and sole responsibility: you, the parent or guardian who installs and configures Termi, are responsible for how it is set up, which AI accounts it connects to, and how children in your care use it. AI output is unpredictable; the safety layers reduce risk but cannot eliminate it, and children should use Termi with adult supervision. The authors and contributors accept no liability for any claim, damages, or other losses arising from the use of this software, as set out in the MIT License. Termi is an independent project and is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, xAI, the Qwen team, or any other AI provider.

package/bin/termi.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 20 || (major === 20 && minor < 19)) {
+  console.error('');
+  console.error('Termi needs a newer version of Node.js to run.');
+  console.error(`You have ${process.versions.node}. Termi needs 20.19 or newer.`);
+  console.error('A grown-up can get the latest from: https://nodejs.org');
+  console.error('');
+  process.exit(1);
+}
+if (process.argv[2] === '--version' || process.argv[2] === '-v') {
+  // Answered here so a version check never loads (or depends on) the app.
+  const { createRequire } = await import('node:module');
+  const pkg = createRequire(import.meta.url)('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+import(new URL('../dist/cli.js', import.meta.url)).catch((err) => {
+  console.error('Termi could not start. Details were saved for a grown-up.');
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+});

package/dist/agent/context.js

@@ -0,0 +1,126 @@
+/**
+ * Builds the model input for one turn, tuned for token efficiency:
+ * - The system prompt stays out of here (the loop sends it first, stable).
+ * - Only files CHANGED since the last embed go in full. Unchanged files are
+ *   one line each and the model uses read_file on demand.
+ * - History is plain truncation: last 30 entries and a 6,000 char budget.
+ * - Every piece of untrusted text passes safety.prefilterContext and lands
+ *   inside data tags the system prompt declares to be data, not instructions.
+ */
+import { createHash } from 'node:crypto';
+/** Max history entries kept (one entry per kid or termi turn). */
+export const HISTORY_TURN_CAP = 30;
+/** Max total characters of history text. Oldest entries drop first. */
+export const HISTORY_CHAR_BUDGET = 6000;
+/** Max lines of TERMI.md embedded per turn. */
+export const TERMI_MD_LINE_CAP = 60;
+export function createEmbedState() {
+    return new Map();
+}
+function sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/**
+ * Plain truncation, newest first: keep at most HISTORY_TURN_CAP entries and
+ * HISTORY_CHAR_BUDGET total characters. Pairs stay intact: an orphaned termi
+ * reply whose kid message was dropped gets dropped too.
+ */
+export function trimHistory(history) {
+    const kept = [];
+    let chars = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+        const entry = history[i];
+        if (entry === undefined) {
+            continue;
+        }
+        if (kept.length >= HISTORY_TURN_CAP || chars + entry.text.length > HISTORY_CHAR_BUDGET) {
+            break;
+        }
+        kept.unshift(entry);
+        chars += entry.text.length;
+    }
+    while (kept.length > 0 && kept[0]?.role === 'termi') {
+        kept.shift();
+    }
+    return kept;
+}
+/** First line that IS a comment (//, /*, or <!--), for the one-line listing. */
+export function firstCommentLine(content) {
+    for (const raw of content.split('\n').slice(0, 40)) {
+        const line = raw.trim();
+        const m = /^\/\/\s*(.+)$/.exec(line) ??
+            /^\/\*+\s*([^*]+?)\s*(?:\*+\/)?$/.exec(line) ??
+            /^<!--\s*(.+?)\s*(?:-->)?$/.exec(line);
+        const text = m?.[1]?.trim();
+        if (text !== undefined && text.length > 0) {
+            return text.slice(0, 60);
+        }
+    }
+    return null;
+}
+function capLines(text, maxLines) {
+    const lines = text.split('\n');
+    return lines.length <= maxLines ? text : lines.slice(0, maxLines).join('\n');
+}
+/**
+ * Assembles the per-turn messages (history plus one composed user message).
+ * Mutates embedState so the next turn elides files that did not change.
+ */
+export function buildMessages(project, history, kidMessageRedacted, embedState, safety) {
+    const messages = trimHistory(history).map((entry) => entry.role === 'kid'
+        ? { role: 'user', content: entry.text }
+        : { role: 'assistant', content: entry.text });
+    const sections = [];
+    const notes = capLines(safety.prefilterContext(project.readTermiMd()), TERMI_MD_LINE_CAP);
+    sections.push('<project_notes>', notes, '</project_notes>');
+    const files = project.listKidFiles();
+    const seen = new Set();
+    const unchangedLines = [];
+    for (const file of files) {
+        seen.add(file.relPath);
+        const content = project.readFile(file.relPath);
+        if (content === null) {
+            continue;
+        }
+        const sha = sha256Hex(content);
+        if (embedState.get(file.relPath) === sha) {
+            const comment = firstCommentLine(content);
+            unchangedLines.push(`${file.relPath} (${file.bytes} bytes)${comment !== null ? ` : ${comment}` : ''}`);
+        }
+        else {
+            embedState.set(file.relPath, sha);
+            sections.push(`<project_file path="${file.relPath}">`, safety.prefilterContext(content), '</project_file>');
+        }
+    }
+    for (const key of [...embedState.keys()]) {
+        if (!seen.has(key)) {
+            embedState.delete(key);
+        }
+    }
+    if (unchangedLines.length > 0) {
+        sections.push('<project_file_list note="unchanged files; call read_file to open one">', ...unchangedLines, '</project_file_list>');
+    }
+    sections.push('<kid_message>', safety.prefilterContext(kidMessageRedacted), '</kid_message>');
+    messages.push({ role: 'user', content: sections.join('\n') });
+    return messages;
+}
+/**
+ * Per-provider options for one turn. Anthropic gets an ephemeral cache point
+ * on the stable system message. The ChatGPT sign-in path runs stateless with
+ * encrypted reasoning passthrough. Everyone else relies on automatic prefix
+ * caching, so the prefix is never reordered and nothing extra is sent.
+ */
+export function providerOptionsFor(providerId) {
+    switch (providerId) {
+        case 'anthropic':
+            return { call: {}, system: { anthropic: { cacheControl: { type: 'ephemeral' } } } };
+        case 'openai-chatgpt':
+            return {
+                call: { openai: { store: false, include: ['reasoning.encrypted_content'] } },
+                system: {},
+            };
+        case 'openai-api':
+        case 'xai':
+            return { call: {}, system: {} };
+    }
+}