\n\n# Mavéa™\n\n\n \n \n\n\n### An AI that draws the answer.\n\nAsk a question — type it or say it — and Mavéa builds the reply on a living canvas: charts,\ntimelines, maps, and evidence you can check, with its pen circling the exact figure each line is\nabout.\n[See it in motion →](docs/FEATURES.md)\n\n
\n \n \n \n \n
\n\n```sh\nnpx @mavea/mavea@latest\n```\n\nOpens `http://localhost:4173` — no install, no account, no model key required.\n\nRuns locally · Your own API key · OpenAI, Claude, Gemini, Grok, OpenRouter\n\n\n\n\n**Ask \"how do we plan a day trip?\"** — and the answer arrives as a route map, an hour-by-hour\nplaybook and the totals that matter. Mavéa picks the form each answer needs.\n\n\n\n**Ask \"why did it happen?\"** — and the answer opens into the causal web behind it. Turn a cause\ndown and the whole web re-weighs, with every link traceable to a real quote.\n\n**Talk to AI. See what it means.** If that is a direction worth exploring, a ⭐ helps other people\nfind Mavéa.\n\n
\n\n---\n\n## Get started\n\nAll you need to run the published app is **Node 22.12+**; building Mavéa from this repo is stricter\nand wants **Node 24.15+**. That command above opens the tour and demo replays immediately\n— nothing else to set up. Demo replays are fictional, curated prerecorded examples with scripted\nfeature choreography; playback does not call a model provider.\n\nThe `@latest` tag matters: for a bare package name `npx` can reuse a previously cached copy rather\nthan fetching a newer one, so asking for `latest` is what reliably gets you the current release.\nPrefer a pinned local copy? `npm install -g @mavea/mavea`, then run `mavea`.\n\n**To talk to a real model (Live):** click **\"Open Mavéa\"** and paste an Anthropic / OpenAI /\nGemini / Grok / OpenRouter key. Model usage is billed by that provider under your key, at its\nrates — the model call is the part of a turn that costs money; the app and the speech services\nrun on your machine. The key stays in memory unless you opt into encrypted local\nremembering, and each provider request carries it through your same-origin proxy to that\nprovider — your key and prompts never pass through Mavéa's own servers, because there aren't\nany. Full options — models, hosting, and the trust boundary — are in\n[docs/LIVE-SETUP.md](docs/LIVE-SETUP.md).\n\n**Local speech:** Mavéa speaks through Apache-2.0\n[Kokoro weights and wrapper](https://github.com/remsky/Kokoro-FastAPI) and transcribes through MIT-licensed\n[whisper.cpp](https://github.com/ggml-org/whisper.cpp). Both cost nothing per use, and what they\nproduce is yours: publishing a transcript, or a video spoken in Mavéa's voices, owes no fee and no\ncredit line — those licenses cover the software, not its output. The defaults run on your machine through\nloopback-only proxies; a deployment that overrides `WHISPER_URL` sends microphone audio to that\nconfigured endpoint. [Podman](https://podman.io/) is the recommended open-source\ncontainer runtime. Docker also works, but Docker Desktop has separate commercial subscription\nterms. Without the configured services, captions and typing still work; audio is never handed to a\nbrowser-vendor speech service as a fallback.\n\nDuring a conversation, the **Mavéa's voice** toggle turns output speech off without changing the\nmicrophone. A paced answer then reveals in full immediately, with captions, notes, and Pen marks in\nplace of the spoken walk.\n\n## What it does\n\nMavéa is an AI you watch think. Type a question or ask it out loud: a calm face takes it, says the\nheadline the instant it forms, then steps aside while a living canvas draws the answer in charts,\ntimelines, and evidence you can check, choosing the right form for each one. As it narrates, it\ndraws on the answer, circling the exact figure each line is about. Sourced claims keep their links and\nestimates can be labelled.\n\nA few specific things worth trying:\n\n- **Ink is the interface.** Draw on the answer to ask — circle a value to explain it, cross one\n out, arrow between two figures, drop a \"?\". The gesture grounds the next turn on that exact bar,\n row, or number.\n- **It draws while it talks.** It speaks each headline as it streams, then lands hand-style circles\n and arrows on the figure it's narrating.\n- **One board, and a card you can look closer at.** The board lays the whole canvas out at once —\n nothing staged, nothing to pick. Click any card and it opens on its own stage, centred over the\n blurred board, with Mavéa's notes beside it: what it assumes, the pattern she sees, what the\n sources actually back, and the question that would break it. Step through the rest with the\n arrows, magnify if you want to, and Escape puts you back. When you'd rather be walked\n through the whole thing, _Guide me_ pulls the answer onto a lamplit desk.\n- **It answers while you talk.** Mid-sentence, dashed ghost cards sketch the answer taking shape\n behind your words, reshaping as your question turns.\n- **It maps your thinking.** Ramble for a minute and Mavéa clusters your words into the themes that\n surface from what you actually said — never fixed buckets — with the tensions between them.\n- **The Blank Space.** When an answer needs a number only you have, Mavéa leaves a hole to fill —\n by voice, type, or a dragged card — instead of quietly guessing.\n- **View any \"why\" as a living answer.** The answer opens into the causal web behind it: press\n _Walk me through it_ and the camera flies cause to cause while Mavéa narrates, or read the same\n web as contribution ribbons, a timeline, or a chart. Break a cause open and its parts are drawn by\n whichever component the library has for that shape — or simply named, where nothing measured them.\n Every figure on it can prove itself, every arrow says what it does _not_ claim, and pulling a\n what-if lever re-weights the world in words — never in invented numbers.\n\nThe full tour — the Study, Prism and Synthesis, Deep Zoom, Courses, Ripple, the Atlas, the\nRehearsal, living dashboards, selective Conversation video, Mavéa Reels, and deck/document export,\namong some thirty features — is in [docs/FEATURES.md](docs/FEATURES.md). In the app, press **⌘K**.\n\n## What it looks like\n\nTwelve moments from the walkthrough and the recorded sessions. Every one replays with no key via\n`npx @mavea/mavea@latest` — except the thought map, whose threads need a live model to draw.\n\n\n
\n
\n
It marks what it's saying. The pen lands on the exact line as the sentence is spoken.
\n
Guide me. The answer comes forward a card at a time on a lamplit desk, Mavéa’s notes pencilled in the margin.
\n
Think out loud first. A ramble sorts itself into themes — and it names the tension you missed.
\n
Scrub the voice. Drag the spoken track and the canvas un-builds to what had been said.
\n
\n
\n
Walk the why. A \"why\" answer opens into the causal web behind it — every cause traceable to a real quote.
\n
It builds you a course. Ask to master something and get real lessons — objectives, a checkpoint, next steps.
\n
A topic, in powers of ten. Telescope from the big picture to the finest mechanism.
\n
A document, claim by claim. Every finding highlighted on the real page it came from.
\n
\n
\n
It picks the right form. A route becomes a map; a day becomes an hour-by-hour plan.
\n
A repository, taught. Beginner to expert, built from the code, with real files.
\n
Out as a deck. Ten skins, a live preview, PDF or PowerPoint.
\n
Or as a document. The same answer set as a paper, ready to print or send.
\n
\n
\n\n## What it needs\n\nMavéa runs on your machine, not in a cloud.\n\n| | Minimum | Recommended |\n| -------- | ---------------------- | -------------------------- |\n| **CPU** | 4 cores | 8 cores |\n| **RAM** | 8 GB | 16 GB |\n| **Disk** | 3 GB | 10 GB |\n| **Node** | 22.12+ (published app) | 24.15+ (build from source) |\n\nAny browser in [Baseline Widely Available](https://web.dev/baseline) — current Chrome, Edge,\nSafari, or Firefox — on macOS, Windows, or Linux. **Minimum** covers the app with voice off,\nalongside the browser and whatever else you already have open. **Recommended** adds the local\nKokoro + whisper.cpp services and a container runtime, with enough room that you never think about\nit.\n\n**Local speech costs real memory, and it's optional.** Kokoro holds roughly 1.3 GB resident;\nwhisper.cpp adds its local model and working memory; a desktop container VM adds its own overhead.\nAt the 8 GB minimum, leaving local speech off can be the better trade. `podman compose down` (or the\nDocker equivalent) reclaims it whenever you want it back.\n\n## Third-party commercial use\n\nGenerated media, bundled libraries, fonts, maps, and the local speech services are held to an\nopen-media and permissive-licence allowlist, enforced on every build by `pnpm check:licenses`.\nIt is an engineering control, not a legal opinion — the full policy, what the gate does and does\nnot cover, and the obligations that travel with the speech container are in\n[docs/THIRD-PARTY-POLICY.md](docs/THIRD-PARTY-POLICY.md).\n\n## 📄 Mavéa license\n\nMavéa is **source-available under the\n[PolyForm Noncommercial License 1.0.0](./LICENSE)**. It is not licensed under MIT and is not\ndistributed under an Open Source Initiative-approved open-source license. The PolyForm license\npermits use, modification, and distribution only for purposes it defines as noncommercial.\nCommercial use requires separate written permission or a separate license from the applicable\nrights holder.\n\nThat restriction applies to recipients of the PolyForm license. It does not stop an applicable\nrights holder from selling or commercially licensing Mavéa, offering it under different terms, or\ntransferring rights it owns or controls, including as part of an acquisition. Third-party\ncomponents remain under their own licenses.\n\nCopies of the software must keep the license's required notice:\n\n> Required Notice: Copyright (c) 2026 Akash Maitra and Aryan Chordia\n\n## Contact\n\n- **Anything else** — \n- **Questions and feature ideas** — [GitHub Discussions](https://github.com/TryMaveaAI/mavea/discussions)\n- **Security** — follow [SECURITY.md](./SECURITY.md); never report a vulnerability in a public issue\n","readmeFilename":"README.md"}
![\"The](\"https://cdn.jsdelivr.net/npm/@mavea/mavea@latest/docs/media/mascot-dark.svg\")
\n![\"CI\"](\"https://github.com/TryMaveaAI/mavea/actions/workflows/ci.yml/badge.svg?branch=main\"){kind=icon}
\n ![\"React](\"https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black\"){kind=icon}
![\"TypeScript](\"https://img.shields.io/badge/TypeScript-6-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Vite](\"https://img.shields.io/badge/Vite-8-646CFF?style=flat-square&logo=vite&logoColor=white\"){kind=icon}
![\"A](\"https://cdn.jsdelivr.net/npm/@mavea/mavea@latest/docs/media/trip-plan.jpg\")
\n\n**Ask \"how do we plan a day trip?\"** — and the answer arrives as a route map, an hour-by-hour\nplaybook and the totals that matter. Mavéa picks the form each answer needs.\n\n![\"A](\"https://cdn.jsdelivr.net/npm/@mavea/mavea@latest/docs/media/living-answer.jpg\")
\n\n**Ask \"why did it happen?\"** — and the answer opens into the causal web behind it. Turn a cause\ndown and the whole web re-weighs, with every link traceable to a real quote.\n\n**Talk to AI. See what it means.** If that is a direction worth exploring, a ⭐ helps other people\nfind Mavéa.\n\n![\"A](\"docs/media/answer-ink.jpg\")
![\"Guide](\"docs/media/study-desk.jpg\")
![\"Thoughts](\"docs/media/think-map.jpg\")
![\"A](\"docs/media/voice-scrub.jpg\")
![\"A](\"docs/media/living-answer.jpg\")
![\"A](\"docs/media/course-lesson.jpg\")
![\"Deep](\"docs/media/deep-zoom.jpg\")
![\"A](\"docs/media/doc-prism.jpg\")
![\"A](\"docs/media/trip-plan.jpg\")
![\"A](\"docs/media/repo-course.jpg\")
![\"The](\"docs/media/deck-export.jpg\")
![\"The](\"docs/media/doc-export.jpg\")