@mavea/mavea 1.0.7

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to Mavéa are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed — the pre-launch pass
+
+Everything below was found by measuring, not by reading.
+
+- **OpenAI was broken for every substantive question.** A reasoning model spends its thinking tokens
+  out of the same `max_output_tokens` budget as its answer, and when it runs out mid-thought the run
+  ends `incomplete` having written nothing at all. Asking it to plan a three-day trip took 72 seconds
+  and returned the honest-fallback card. The thinking headroom Gemini and Anthropic already had now
+  extends to OpenAI and Grok; `response.incomplete` is surfaced instead of silently swallowed; and
+  reasoning effort is pinned to `low`, where it demonstrably works (above that, the reasoning runs
+  away — at ~18k tokens it thought for 119 seconds and still wrote nothing). Same question, search
+  on: **72s → 27s, one model call instead of two, a real eight-block itinerary with live sources.**
+- **Push-to-talk never worked in Live.** The hold listener refused to arm inside a text field, and
+  the composer takes focus whenever you aren't speaking — so the target was always an input. A bare
+  modifier types no character, so it now arms there and stands down the moment another key joins it
+  (a real combination like ⌥E).
+- **The app needed a refresh on `pnpm dev`, and could lose an answer mid-flight.** Vite's scanner
+  only follows static imports, so a package reached solely through `import()` was invisible to it;
+  the first time the running app touched one it re-bundled and hard-reloaded the page — a blank first
+  paint on arrival, and on the mic (which pulls in the voice model) a reload straight through
+  whatever turn was in flight.
+- **The block library now fits a phone.** 76 of ~580 blocks clipped their content at 320px. Two
+  shared rules caused most of it: the card footer could not wrap, and the card eyebrow carried
+  `nowrap` over a label the model writes.
+- **Nothing heavy loads before you ask for it.** The ~7MB on-device embedder was fetched the moment
+  Live mounted; someone who opened Live, looked around and left paid for all of it. It waits for a
+  sign you mean to ask something.
+- Photos were stamped "AI image" though Mavéa does not generate images; a re-ask replayed the old
+  answer when you toggled "explain simply"; a failed file read left the Synthesis drop zone spinning
+  forever; a broken chunk could reload the browser without end; and `GradientDescent` drew no surface
+  at all (it mixed data and pixel coordinates and emitted negative SVG rects, which browsers refuse).
+
+### Removed
+
+- `vercel.json`. It was never used, and its own comment conceded that BYOK Live could not work there
+  without serverless forwarders that were never written — so deploying with it would have shipped an
+  app with every provider call broken.
+
+### Added
+
+- **The voice-first redesign.** The spoken answer leads as a serif headline over the evidence;
+  six theme templates (paper / daylight / ink / console / marquee / original), each a complete
+  token re-skin with its own light **and** dark; honest turn states (a live listening card,
+  skeletons labeled with the real streaming block type, a said-vs-shown speak ribbon); a
+  "What are we figuring out?" welcome hub with starter chips and resumable moments cards.
+- **It points while it talks.** Mavéa draws hand-style circles, underlines, and arrows on the
+  exact figure each spoken line is about — targets are model-authored and located in the card's
+  real DOM (no reason, no ink), with a generous **teach mode** ("walk me through it"). Strokes
+  persist on the card, replay in shared Stories, and survive follow-up turns.
+- **Edit its mind** — every answer lists the constraints it rests on as tappable chips; fixing
+  one fires a single correction turn. **Self-healing history** — a genuine reversal marks the
+  earlier moment _corrected_ (was → now) in the rail and recap instead of rewriting it silently.
+- **Blocks fuse** — drag any card onto another for a grounded answer about the real relationship
+  between their data. **Ask about this** pins blocks so follow-ups are grounded in their exact
+  on-screen props.
+- **Time as a medium.** Per-turn frames with replay; a session **Recap** ("Tonight, so far.");
+  **semantic zoom** (pinch out to chapters, again to one breath); and **scrub-the-voice** — the
+  settled answer's real spoken track as a waveform that un-builds the canvas to what had been
+  _said_ at any moment, then rebuilds as it replays.
+- **Ghost blocks** — while you're still talking, dashed _forming / maybe_ cards sketch the answer
+  taking shape (speculative, abortable, off on the Fast quality dial).
+- **The companion.** **Hold my thought** catches unfinished sentences and offers one back at
+  wind-down; **whisper mode** dims the room and the voice during quiet hours (10 PM–6 AM,
+  opt-out); **think-out-loud** banks a ramble and sorts it into decisions / todos /
+  contradictions on "thoughts?".
+- **The Rehearsal** — practice a hard conversation against a counterpart grounded only in
+  context you supply, with a coach card between takes. **The Table** — two real agents negotiate
+  on your key inside code-enforced boundaries; the deal stays pending both humans.
+- **Living answers.** **Track this** turns anything you asked about into a **living dashboard**
+  (`#/dashboards`) that re-checks itself on a cadence you set — an honest re-ask on your own key,
+  never a fake background update — with a running check log, a spend ledger, tripwire alerts, and
+  a Rewind of how the answer changed; **bendable answers** carry model-authored formulas so
+  dragging the one number that matters recomputes the outputs, auditable (whitelist evaluator,
+  never `eval`).
+- **Reach.** **Share-to-Mavéa** — paste or drop a link/screenshot anywhere on Live for a
+  source-grounded claim check; **Present mode** — a full-theater stage with slide nav and the
+  mic left live so room questions become canvases ("from the room"); **Your Atlas** — every
+  conversation as a flyable map clustered by your own words; **Mavéa Story** — share a session as
+  a cinematic MP4 of the real components; **per-fact memory provenance** ("you said so" vs
+  inferred — and an inferred guess is never asserted as fact) with grouped view and JSON export,
+  plus memory that **learns how you like answers** — honoring a correction or a stated
+  format/depth on the very next turn, query-conditioned recall, all local and at no extra cost,
+  with a multi-turn eval that proves the lift.
+- **The new face** — an aurora jelly replaces the original orb: its bell gradient _is_ the mood,
+  and four tentacle curtains carry the state. Same data-attribute contract (state / emotion /
+  gaze), so templates, docking, and voice-energy sync carry over.
+- `pnpm new:block <family> <type>` — a scaffold that wires a new canvas block into the family
+  types, registry, and the `ComponentMeta` catalog — plus `docs/ADDING-A-COMPONENT.md` as the
+  one canonical guide to the block contract.
+- A registry ↔ `ComponentMeta` bijection test and a gallery-family coverage test: a block added
+  without metadata (so Live can never select it) or a family missing from the `#/gallery` QA
+  surface now fails the suite instead of slipping through silently.
+- `.env.example` documenting local service URLs, gateway credentials, and eval keys.
+- A Content-Security-Policy (meta + nginx headers) plus `X-Content-Type-Options`,
+  `Referrer-Policy`, `X-Frame-Options`, and a microphone/screen-capture-scoped
+  `Permissions-Policy` — verified against the production build with the policy enforcing.
+
+### Changed
+
+- **Kokoro is now the only voice.** The browser `speechSynthesis` engine is removed — when the
+  model isn't reachable, lines are captions-only rather than read in a robotic system voice.
+  Kokoro's container now runs by default (`docker compose up`), not only under `--profile live`,
+  so a hosted-model Live user hears the natural voice; Whisper stays live-profile-only.
+- Consolidated to a single documented block standard (`ComponentMeta`); the orphaned
+  `BlockDescriptor` "standard" that no code used was removed.
+- Wired the `code`, `compose`, `diagrams`, `everyday`, and `reference` families into the gallery
+  so their blocks group correctly instead of falling into a catch-all bucket.
+
+### Fixed
+
+- **Security** — add SRI integrity check (`sha384`) to the PDF.js worker `fetch()` call in
+  Prism; the code sandbox already pinned Pyodide the same way — this closes the asymmetric gap.
+- **Security** — sanitize the HTML render boundary for model- and search-derived content
+  (message-draft bodies, web-search excerpts, source snippets, accordion bodies). Closes an
+  entity-decode XSS in the search path and an un-neutralized message-draft body.
+- **Security** — validate and bound actions-gateway inputs: reject CR/LF in Gmail
+  recipients/subjects (MIME header injection) and length-cap every field.
+- **CSP** — `<object type="application/pdf">` silently blocked by `object-src 'none'`; replaced
+  with `<iframe>` (permitted by `default-src 'self'` for same-origin PDFs).
+- **Mobile nav** — More-menu and topbar divider failed to hide at ≤430px because `voice.css`
+  (imported later) was winning the cascade; added `!important` to the mobile CSS rules.
+- **Accessibility** — Combobox: added `role="combobox"`, `aria-expanded`, `aria-autocomplete`
+  so screen readers announce it as a combobox, not a bare text field.
+- **Accessibility** — Formpanel: labels were siblings without `for`/`id` pairing; added
+  `htmlFor`/`id` association on every field type (text, email, select, textarea).
+- **Accessibility** — Hidden file-picker inputs (attach + import settings) now carry
+  `aria-hidden="true"` so they are invisible to assistive technology.
+- **Accessibility** — Composer text input and the demo play-stop button were missing
+  `aria-label`; both are now properly labelled for screen readers.
+- **Tests** — `parsetree [extreme]` gauntlet fixture was O(exponential): `stressValue()` expanded
+  `children` arrays ×10 (cap 50), creating ~27 000 SVG nodes at 3 levels of nesting. Capped
+  `children`/`nodes` keys at 4 items; render time dropped from >20 s to 6 ms.
+- **Canvas** — `BlockBoundary` now calls `console.error` in `componentDidCatch` so block render
+  failures are visible in the browser console without crashing the canvas or the voice track.
+
+### Removed
+
+- Dead code — an unused descriptor system, an unused text-fitting module, and a chain of unused
+  exports; `pnpm knip` now reports zero.
+
+## [1.0.0]
+
+Initial release. Two surfaces that share one component library and one stylesheet:
+
+- **Demo** — a home library of spoken, two-voice persona conversations across a large
+  visualization library (the "living canvas").
+- **Live** — bring-your-own-key, multi-provider (Anthropic, OpenAI, Gemini, xAI Grok, OpenRouter)
+  talk-to-a-real-model mode with a real canvas, two-voice TTS, and web search.
+
+React 19 + Vite + TypeScript with a bespoke CSS design system; keys stay client-side; runs in
+Docker.

package/DISCLAIMER.md

@@ -0,0 +1,16 @@
+# Mavéa Disclaimer
+
+Effective: July 16, 2026
+
+Mavéa uses probabilistic AI systems and can be wrong.
+
+- AI-generated text, citations, calculations, classifications, transcriptions, translations, and visualizations may be inaccurate, incomplete, misleading, offensive, or outdated.
+- A citation, confidence label, validation step, or polished visualization does not guarantee that a claim is correct.
+- Verify important information with authoritative sources and qualified professionals before relying on it.
+- Mavéa does not provide medical, legal, financial, tax, accounting, safety, engineering, mental-health, or other professional advice. Do not use it for emergencies or as the sole basis for high-impact decisions.
+- You are responsible for the prompts, files, audio, accounts, credentials, and actions you provide or authorize.
+- Model, search, speech, hosting, OAuth, media, and connected-action providers are independent third parties. Their terms, privacy practices, availability, and charges apply. All costs are your responsibility.
+- Credentials and relevant content travel through the deployment operator's same-origin proxy before reaching selected providers. The operator can access them in transit.
+- Confirmed actions may create external communications, account changes, charges, or other consequences. Review every action and use test accounts and backups where appropriate.
+
+To the maximum extent permitted by law, Mavéa is provided as is and as available, without warranties, and you assume the risk of using it. The [Terms of Use](./TERMS.md) and [PolyForm Noncommercial License 1.0.0](./LICENSE) contain the controlling warranty disclaimers and liability limitations. This summary does not expand or replace them, and no document can waive rights or liabilities that applicable law does not allow to be waived.

package/LICENSE

@@ -0,0 +1,75 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright (c) 2026 Akash Maitra and Aryan Chordia
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/PRIVACY.md

@@ -0,0 +1,127 @@
+# Mavéa Privacy Notice
+
+Effective: July 19, 2026
+
+This notice describes the current, unmodified local and self-hosted Mavéa software. It does not describe a future hosted service. Local-first does not mean every feature stays on your device: connected features send data through the deployment to third parties you choose. If a person or organization deploys Mavéa for others, that operator must provide any additional privacy notices and controls required for its deployment.
+
+## 1. Who handles your information
+
+The Mavéa Maintainers publish software. They do not receive your prompts or browser-local data merely because you install or run it. The person or organization hosting the copy you use is the **deployment operator**. When you self-host, you control that deployment and its logs, storage, configuration, and provider accounts.
+
+The unmodified project has no Mavéa user-account system, first-party cloud database, advertising network, product-analytics service, telemetry, or conversation-retention service. Normal network requests can still be visible to the deployment host, infrastructure providers, and the third-party services described below. A modified or separately hosted deployment may behave differently, and its operator is responsible for disclosing any additional collection, logging, accounts, analytics, retention, or sharing it adds.
+
+The current repository does not set analytics or advertising cookies and does not include first-party usage tracking. A modified deployment that adds cookies, analytics, advertising, or other tracking must disclose and manage those technologies separately.
+
+## 2. Information kept in your browser or deployment
+
+Depending on the features you use, browser storage may contain:
+
+- conversations, saved canvases, bookmarks, memory items, and session history;
+- courses, lessons, flashcards, quiz progress, Ripple analyses, and dashboards;
+- preferences such as theme, performance, visual richness, voice, and setup state;
+- drafts, tracked items, presentation settings, and recent feature state;
+- provider and model configuration;
+- remembered provider, search, or optional GitHub credentials; and
+- short-lived demo, tour, route, and in-progress session data.
+
+Saved content is encrypted in browser storage only where the relevant feature and browser support it. Course data, mastery and progress, some Ripple data and analysis caches, preferences, metadata, and fallback content can be stored in ordinary local storage or IndexedDB. Anyone who can use your unlocked device or browser profile, and malicious extensions or same-origin code, may be able to access browser data.
+
+Because this browser data is encrypted to this specific browser, it does not carry over to a different browser, an incognito window, or another device. You can export a backup file of your dashboards, memory, flashcards, saved canvases, map, and courses, and import it elsewhere to move that data. The backup is plain, unencrypted JSON under your control, so store and share it carefully; it deliberately excludes your provider and search keys. Importing a backup merges into existing data and never deletes it, and importing a file you did not create can add content from that file — import only backups you trust.
+
+Browser and operating-system caches may retain application assets and optional voice models. The actions gateway may store connected-service credentials and configuration on the deployment operator's machine.
+
+## 3. Credentials and connected-service tokens
+
+Provider and search keys stay in memory until reload unless you choose Remember. When supported, Remember encrypts them with a non-extractable, device-bound browser key and stores ciphertext locally. Without the required browser cryptography, the unmodified app keeps them session-only rather than writing plaintext. Settings exports exclude provider and search keys.
+
+Keys are decrypted when needed and pass through the deployment's same-origin proxy to the provider you selected. The proxy and its host can technically access credentials and content in transit. Browser encryption does not protect against an active compromise of the device, browser, extension, deployment, proxy, or provider.
+
+Optional GitHub and Google connections can store access tokens, refresh tokens, or repository settings in the actions gateway or its host configuration. The unmodified gateway writes persisted OAuth tokens to an owner-readable host file and keeps limited audit metadata, not request bodies or provider response text. Whoever runs the gateway controls that file, its backups, logs, deletion, and security.
+
+The unmodified gateway has no separate Mavéa user accounts. On a shared deployment, everyone allowed to use action features may act through the deployment operator's connected GitHub or Google account. Use a dedicated, least-privilege gateway and do not expose it to people who should not share those permissions.
+
+## 4. Prompts, files, code, and generated content
+
+Text you type or paste, conversation context, remembered facts, attached files, extracted document text, images, repository content, diffs, search queries, and feature instructions may be sent through the deployment to the model, search, or connected provider needed for the feature you request. Responses and generated content return through the deployment to your browser.
+
+Prism and Synthesis stage and extract supported files locally where possible, but relevant content can still be sent for analysis. Ripple can parse code locally before optional model enrichment sends relevant code or diffs. Local staging is not a promise that later analysis remains local.
+
+## 5. Voice, microphone, speech, and reels
+
+If you enable listening, the browser captures microphone input and its speech-recognition implementation converts speech to text. Depending on the mode, browser, and operating system, audio may be processed by a remote browser-vendor service or sent through the deployment's configured speech-to-text endpoint. Recognized transcripts may then be sent to your selected model provider.
+
+Spoken answers send narration text to the configured text-to-speech service. Reel rendering and encoding are performed in the browser, but optional model direction and narration use the selected providers. A finished export leaves Mavéa only when you save, publish, or send it to a destination you choose.
+
+## 6. Services that can receive data
+
+According to the feature and configuration you choose, recipients can include:
+
+- Google Gemini, Anthropic Claude, OpenAI, xAI Grok, OpenRouter, or another model endpoint you configure;
+- configured web-search providers and Wikipedia;
+- your browser vendor's speech-recognition service and the configured speech-to-text or text-to-speech service;
+- GitHub, Google Calendar, or another configured action destination;
+- map-tile, font, image, and other content hosts such as OpenStreetMap, CARTO, Google Fonts, Wikimedia, or configured image sources used by a view you open;
+- a notification relay URL you configure, which can receive dashboard titles, alert labels, values, units, and timestamps;
+- the jsDelivr content-delivery network, from which the local command-line server downloads version-pinned voice-recognition assets once on first voice use and then serves them from its own cache; and
+- the deployment host, reverse proxy, network, and infrastructure providers.
+
+Those parties process data under their own terms and privacy notices. They may retain requests, use data for abuse prevention or service improvement, or process it in other countries according to your account settings and their policies. The Maintainers do not control those practices. Review each recipient's terms, retention, training, security, location, and deletion settings before use. Mavéa cannot delete data retained by those providers.
+
+## 7. Why information is processed
+
+Information is processed only as needed to:
+
+- provide the feature you request and return results;
+- save state and preferences on your device;
+- authenticate to providers and connected services you configure;
+- perform an external action after the required confirmation;
+- protect a deployment, enforce limits, diagnose failures, and prevent abuse; or
+- comply with law or protect rights and safety where legally required.
+
+The unmodified project does not sell personal information or use it for cross-context behavioral advertising. A deployment operator must separately disclose any different purpose it introduces.
+
+## 8. Retention and deletion
+
+Memory-only values disappear on reload. Session storage generally remains until the tab or browser session ends. Local storage and IndexedDB remain until a feature removes the item, you use an available clear, forget, or reset control, you clear site data, or the browser evicts it. Some session history is capped and expires, but many course, progress, dashboard, memory, and Ripple records have no automatic expiration. Clearing all browser site data is the broadest local deletion control. Removing browser data does not delete copies already sent elsewhere.
+
+Gateway tokens remain until disconnected or removed by the gateway operator. Server, proxy, infrastructure, browser-vendor, and provider retention depends on the relevant operator, logs, backups, account settings, and third-party policy. Contact those parties for deletion of data they control and revoke credentials at the issuing service.
+
+Exports, downloaded files, backups, browser sync, system backups, provider records, and recipients of anything you share must be deleted separately.
+
+## 9. Your controls and privacy rights
+
+You can reduce or remove data by:
+
+- leaving Remember off and using restricted, revocable provider keys;
+- using Mavéa's forget, delete, disconnect, reset, and clear controls where offered;
+- clearing this site's local storage, session storage, IndexedDB, cache, and permissions;
+- revoking model, search, GitHub, Google, and other connected credentials;
+- turning off microphone access and avoiding voice features;
+- not uploading information you do not want sent to a selected provider; and
+- contacting the deployment operator or relevant provider about data they control.
+
+Depending on where you live, you may have legal rights to access, correct, delete, restrict, object to, or obtain a copy of personal information held by a deployment operator. The Maintainers cannot retrieve browser-local or provider-held data they do not possess.
+
+## 10. Sensitive, confidential, and regulated information
+
+Mavéa is not designed as a system of record for health, financial, student, employment, government-identifier, biometric, trade-secret, or other regulated information. Do not submit such information unless you have authority, have assessed every recipient, and have put any legally required contracts and safeguards in place. A disclaimer does not make a deployment compliant with HIPAA, FERPA, GDPR, financial-services rules, workplace duties, or another regulatory regime.
+
+Do not submit children's data or another person's personal, confidential, privileged, or regulated information unless you have appropriate authority and a lawful basis. Mavéa is not a confidential or privileged channel.
+
+## 11. Security
+
+Mavéa uses safeguards such as browser encryption for supported stored data, content sanitization, same-origin request boundaries, confirmation for connected actions, and restricted gateway token-file permissions. No safeguard is perfect. Do not treat local storage or encryption as a guarantee, and do not use Mavéa as a password manager or secret vault.
+
+You are responsible for device security, access controls, backups, proxy configuration, least-privilege provider credentials, and connected-account security. Do not expose a local proxy, development server, or actions gateway to an untrusted network.
+
+## 12. Children
+
+Mavéa is intended for adults and is not directed to children. Do not allow anyone under 18 to use connected model, upload, microphone, or action features or submit personal information through Mavéa. If you believe a child's information reached a deployment or provider, contact that operator and the relevant provider promptly and revoke any affected connection.
+
+## 13. Changes, business transfers, and contact
+
+Material changes to this notice require an updated effective date and, where appropriate, a new in-product acceptance version. A deployment operator must provide its own identity and contact details where applicable law requires them.
+
+If a project, deployment, or relevant assets are reorganized, financed, sold, merged, or transferred, information actually controlled by the relevant operator may be disclosed to advisers and transferred to a successor as permitted by law. Browser-local and provider-held information that the operator does not possess cannot be transferred by that operator. A successor must describe its identity and any materially different data practices.
+
+For a hosted copy, contact the person or organization that gave you access. For the public repository, use the Mavéa GitHub issue tracker for non-sensitive questions. Do not put personal or confidential information in a public issue. Report security concerns through [SECURITY.md](./SECURITY.md).

package/README.md

@@ -0,0 +1,248 @@
+<div align="center">
+
+# Mavéa
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/mascot-dark.svg" />
+  <img src="docs/media/mascot-light.svg" width="150" alt="The Mavéa presence" />
+</picture>
+
+### Talk to AI. See what it means.
+
+<!-- HERO GIF — the single highest-leverage thing in this README. Record a 10-second autoplay loop
+     (voice asks → face listens → canvas blooms into charts → ink draws on the answer) from the Demo
+     (needs no keys) or via "Share as a Mavéa Story", save it to docs/media/hero.gif, and uncomment
+     the <img> below. Until then the signature-move line keeps the fold looking intentional. -->
+<!-- <img src="docs/media/hero.gif" alt="Mavéa in ten seconds — voice in, a living canvas out" width="820" /> -->
+
+It listens, speaks the headline the instant it forms, then draws the answer — in charts, timelines,
+and evidence you can check, marking the exact figure each line is about.
+[See it in motion →](docs/FEATURES.md)
+
+<p>
+  <a href="https://github.com/TryMaveaAI/mavea/actions/workflows/ci.yml"><img src="https://github.com/TryMaveaAI/mavea/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black" alt="React 19" />
+  <img src="https://img.shields.io/badge/TypeScript-6-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 6" />
+  <img src="https://img.shields.io/badge/Vite-8-646CFF?style=flat-square&logo=vite&logoColor=white" alt="Vite 8" />
+</p>
+
+**Try it in one command:** `npx @mavea/mavea`
+
+</div>
+
+---
+
+## What it does
+
+Mavéa is an AI you talk to and watch think. Ask out loud: a calm face listens, speaks the headline
+the instant it forms, then steps aside while a living canvas draws the answer in charts, timelines,
+and evidence you can check. As it talks, it draws on the answer, circling the exact figure each line
+is about. Sourced claims keep their links and estimates can be labelled. Provider keys stay in
+memory by default; optional remembering encrypts them locally. Live requests send them through the
+same-origin proxy you run or deploy, onward to the model provider you chose.
+
+A few specific things worth trying:
+
+- **Ink is the interface.** Draw on the answer to ask — circle a value to explain it, cross one
+  out, arrow between two figures, drop a "?". The gesture grounds the next turn on that exact bar,
+  row, or number.
+- **It draws while it talks.** It speaks each headline as it streams, then lands hand-style circles
+  and arrows on the figure it's narrating.
+- **It answers while you talk.** Mid-sentence, dashed ghost cards sketch the answer taking shape
+  behind your words, reshaping as your question turns.
+- **It maps your thinking.** Ramble for a minute and Mavéa clusters your words into the themes that
+  surface from what you actually said — never fixed buckets — with the tensions between them.
+- **The Blank Space.** When an answer needs a number only you have, Mavéa leaves a hole to fill —
+  by voice, type, or a dragged card — instead of quietly guessing.
+
+The full tour — Atlas, Rehearsal, living dashboards, Ripple, Share-as-a-Mavéa-Story, and ~30 more —
+is in [docs/FEATURES.md](docs/FEATURES.md). In the app, press **⌘K**.
+
+## Two ways in
+
+- **Demo replays** — recorded persona sessions (for example, a CFO reviewing her quarter or a
+  parent planning dinner). Each answer was generated once by a real model and frozen; it replays
+  on the same Live surface, without a key. The characters are fictional; the answers are real
+  model output.
+- **Live** — bring your own model (Anthropic, OpenAI, Gemini, xAI Grok, or OpenRouter) and ask
+  anything by voice or text, answered on the same canvas.
+
+Honesty is built in, not bolted on: confidence labels, sourced claims, and a Live
+[eval harness](docs/BENCHMARK.md) that scores whether a model picks the right visualization and
+labels its estimates honestly.
+
+## Quick start
+
+Just want to run it? All you need is **Node 20.19+**:
+
+```sh
+npx @mavea/mavea                # → http://localhost:4173 — tour + demo replays, no model key required
+```
+
+Working on the source? Use pnpm instead (`corepack enable` once to get the pinned version):
+
+```sh
+pnpm install
+pnpm dev                  # → http://localhost:5173 — dev server, with voice
+pnpm build                # → dist/ — production build
+pnpm preview              # → http://localhost:4173 — serves dist/ exactly as npx @mavea/mavea does, voice included
+```
+
+| Command        | What it does                                                                                                                                                                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pnpm dev`     | Starts everything: brings up the Kokoro voice container, then Vite. If Docker isn't running, it says so and serves the app anyway — answers appear as captions instead of being spoken.                                                                                  |
+| `pnpm dev:web` | Vite alone, no voice container. Faster to start if you don't need speech.                                                                                                                                                                                                |
+| `pnpm build`   | Type-checks, then produces the production bundle in `dist/`.                                                                                                                                                                                                             |
+| `pnpm preview` | Serves the `dist/` build with the exact server `npx @mavea/mavea` runs: same-origin `/tts` + `/llm` proxies included, and it offers to bring up the Kokoro voice container when Docker is present. Without Docker it says so in one line and answers appear as captions. |
+| `pnpm test`    | Runs the Vitest suite once.                                                                                                                                                                                                                                              |
+| `pnpm verify`  | The full pre-PR gate: reference-example + gallery-fixture freshness → typecheck → lint → format check → test → build → bundle-size budget → artifact + package boundary checks. Run this before opening a PR.                                                            |
+
+That's the everyday set. The rest of the scripts (linting, evals, one-off audits, internal tooling)
+are documented in full in [CONTRIBUTING.md](./CONTRIBUTING.md#scripts-reference).
+
+**Talk to a real model (Live):** click **"Open Mavéa"** and paste an Anthropic / OpenAI / Gemini /
+Grok / OpenRouter key. It stays in memory unless you opt into encrypted local remembering, and each
+provider request carries it through your same-origin proxy to that provider. Full options — models,
+actions, hosting, and the trust boundary — are in
+[docs/LIVE-SETUP.md](docs/LIVE-SETUP.md).
+
+**The voice:** Mavéa speaks through [Kokoro](https://github.com/remsky/Kokoro-FastAPI), a natural
+local TTS — the one thing that runs in Docker. `pnpm dev` and `pnpm preview` both start it for
+you; it's optional, and without it every line appears as captions. To run or stop it on its own:
+
+```sh
+docker compose up -d     # Kokoro TTS on :8880 — dev and preview both proxy /tts to it
+docker compose down      # stop it (it otherwise stays up between dev sessions)
+```
+
+## What it needs
+
+Mavéa runs on your machine, not in a cloud. One set of numbers covers both using it and working on
+it, because the toolchain is the heavier of the two and it still isn't heavy.
+
+|          | Minimum | Recommended |
+| -------- | ------- | ----------- |
+| **CPU**  | 4 cores | 8 cores     |
+| **RAM**  | 8 GB    | 16 GB       |
+| **Disk** | 3 GB    | 10 GB       |
+| **Node** | 24.11+  | 24.11+      |
+
+Both columns describe your whole machine rather than Mavéa's share of it, and neither is a bare
+floor. **Minimum** is the app and its toolchain with the voice off, alongside the browser and editor
+you already have open. **Recommended** adds the voice and Docker on top of that, with enough room
+left that you never think about any of it. Any browser in
+[Baseline Widely Available](https://web.dev/baseline) — current Chrome, Edge, Safari, or Firefox —
+on macOS, Windows, or Linux.
+
+For reference, Mavéa itself asks for far less, and it's worth knowing which part costs what.
+`npx @mavea/mavea` serves a static build and the work happens in your browser tab: the page it loads
+is 89 kB over the wire, and every surface becomes usable in under half a second on a CPU throttled
+6×. The toolchain is heavier and still modest — a production build peaks around 1.6 GB of memory and
+finishes in ~12 s, a full typecheck of all 2,200 TypeScript files peaks under 1 GB and takes ~3 s,
+and a checkout with dependencies and a build output on disk comes to ~750 MB. Everything caches, so
+only the first run after a fresh clone is slow.
+
+**The voice is the one part that costs real memory, and it's optional.** Kokoro's image is 4.9 GB on
+disk and holds ~1.3 GB resident, and Docker Desktop itself adds ~1.5 GB before a word is spoken.
+Synthesis briefly takes a few cores, and runs ahead of the playhead rather than at it. At the 8 GB
+minimum, leaving the voice off is usually the better trade: every line becomes a caption and nothing
+else changes. `docker compose down` reclaims all of it; the
+container otherwise stays up between sessions on purpose, so the next start is instant, and
+`pnpm dev:web` starts Vite without bringing Docker up at all.
+
+**Nothing here should make a fan audible.** The always-on costs are the animated face and the glass
+blur, so rather than guessing from core count, Mavéa watches its own frame pacing for the first few
+seconds and calms both if this particular machine is actually struggling — an integrated GPU choking
+on blurred glass is invisible to a spec sheet. It waits for two bad windows before demoting, so one
+hitch won't do it, and it never promotes back mid-session. You can also just decide for it:
+**Visual richness → Lite** in Live's settings is a per-device choice that takes effect immediately.
+Everything else is idle until you ask it something — the one part that will genuinely work a CPU is
+voice synthesis, and that only runs if you started Docker.
+
+## How it works
+
+Mavéa is one conversation surface (Live) plus a marketing landing, hash-routed in `main.tsx`.
+However a turn is triggered — voice, text, a chip, or a replayed demo frame — it resolves to
+the same shape:
+
+```
+ask ─▶ generateLive ─▶ validate/repair ─▶ settle (merge + tour) ─▶ Presence (the face) + Canvas (the blocks)
+```
+
+The canvas is data, not components: every answer is a list of typed `{ type, props }` blocks
+(`data/conversation.ts`). A model never emits UI — it emits those same blocks, which
+`live/generateLive` streams, validates, and repairs into the `ConversationSpec` contract. The
+demo replays are frozen outputs of this exact pipeline, so they render through the same
+contract and renderer. The generated selection catalog contains **600 component contracts across
+23 families**, and the gallery production-renders every one of them — including the types that are
+gated or surface-owned rather than offered in ordinary model selection. Every provider sits behind
+one `ProviderAdapter`; Live credentials and
+prompts cross the same-origin proxy operated by whoever runs the deployment before reaching the
+selected provider. This repository does not include a hosted account, analytics, or data-retention
+service.
+
+The full design — the turn contract, the validation core, the BYOK proxy diagram, and the eval
+harness — is in [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## Built with
+
+A deliberately small stack — React 19, TypeScript 6, Vite 8 — with no chart library and no UI
+framework beyond React: every chart, dial, diagram, and the face is hand-rolled SVG/CSS. Beyond
+`react`/`react-dom`, the runtime stays lean: `@ricky0123/vad-web` (Silero VAD for end-of-speech)
+plus a handful of feature-scoped libraries — KaTeX, Leaflet, jsPDF, pdfjs-dist, openchemlib,
+mediabunny, modern-screenshot, pptxgenjs, and Shiki — each lazy-loaded only when that feature is used and
+bundled rather than fetched from a CDN. JavaScript/TypeScript snippets run only after an explicit
+click in a bounded Worker; Python execution is disabled until it has an equally isolated runtime.
+The face is one hand-drawn SVG animated purely by CSS off `data-*` attributes — JS never transforms
+it.
+
+## Documentation
+
+| Doc                                                        | What's in it                                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------- |
+| [docs/FEATURES.md](./docs/FEATURES.md)                     | The detailed product feature tour                          |
+| [ARCHITECTURE.md](./ARCHITECTURE.md)                       | The turn lifecycle, the seams, and how the pieces fit      |
+| [docs/BENCHMARK.md](./docs/BENCHMARK.md)                   | The eval as a benchmark — score any model, leaderboard     |
+| [docs/LIVE-SETUP.md](./docs/LIVE-SETUP.md)                 | Running Live: models, voice, actions, troubleshooting      |
+| [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)                 | Edge contract: TLS, HTTP/2/3, compression, cache, headers  |
+| [docs/ADDING-A-COMPONENT.md](./docs/ADDING-A-COMPONENT.md) | The full contract + scaffold for a new canvas block        |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)                       | Setup, the full script reference, conventions, and recipes |
+| [docs/ENGINEERING.md](./docs/ENGINEERING.md)               | The review rubric: security, scalability, readability      |
+| [SECURITY.md](./SECURITY.md)                               | The BYOK security model and how to report a vulnerability  |
+| [TERMS.md](./TERMS.md)                                     | Terms for using the software and connected features        |
+| [PRIVACY.md](./PRIVACY.md)                                 | Local, provider, proxy, storage, and transfer data flows   |
+| [DISCLAIMER.md](./DISCLAIMER.md)                           | Plain-language AI and third-party risk summary             |
+
+## Feedback and maintenance
+
+Issues with code-free bug reports and feature suggestions are welcome. This repository does not
+accept external code, patch, or documentation pull requests; see [CONTRIBUTING.md](./CONTRIBUTING.md)
+for the maintainer workflow and feedback rules. Maintainer changes are held to the
+[engineering bar](./docs/ENGINEERING.md) (security, scalability, readability), and CI runs
+`typecheck → lint → format → test → build` plus bundle, dependency, secret, and static-analysis
+checks.
+
+Two checks the unit suite can't make, both against a running `pnpm dev`:
+
+```bash
+pnpm audit:ui             # every block, 280px → 4K, both themes: clipped · overlapping · illegible
+pnpm perf                 # every surface under CPU throttling — and nothing heavy loaded unasked
+```
+
+## 📄 License
+
+Mavéa is **source-available under the
+[PolyForm Noncommercial License 1.0.0](./LICENSE)**. It is not licensed under MIT and is not
+distributed under an Open Source Initiative-approved open-source license. The PolyForm license
+permits use, modification, and distribution only for purposes it defines as noncommercial.
+Commercial use requires separate written permission or a separate license from the applicable
+rights holder.
+
+That restriction applies to recipients of the PolyForm license. It does not stop an applicable
+rights holder from selling or commercially licensing Mavéa, offering it under different terms, or
+transferring rights it owns or controls, including as part of an acquisition. Third-party
+components remain under their own licenses.
+
+Copies of the software must keep the license's required notice:
+
+> Required Notice: Copyright (c) 2026 Akash Maitra and Aryan Chordia