@mavea/mavea 1.0.16 → 1.0.18

package/DISCLAIMER.md

@@ -1,6 +1,6 @@
 # Mavéa Disclaimer
 
-Effective: July 16, 2026
+Effective: August 11, 2026
 
 Mavéa uses probabilistic AI systems and can be wrong.
 
@@ -10,6 +10,9 @@ Mavéa uses probabilistic AI systems and can be wrong.
 - 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.
+- Container engines and desktop tooling are separate products with their own licences and possible commercial subscription charges.
+- Open-media source licences, codec selections, and published patent commitments are not a guarantee that no third party will assert patent rights in every implementation, territory, or use. Obtain qualified patent advice where needed.
+- Copyright licences and attributions for third-party images, video, fonts, maps, documents, and demos do not necessarily clear privacy, publicity, trademark, property, or other depicted-subject rights. Preserve notices and obtain any additional permission your use requires.
 - 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.
 

package/PRIVACY.md

@@ -1,6 +1,6 @@
 # Mavéa Privacy Notice
 
-Effective: July 19, 2026
+Effective: August 11, 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.
 
@@ -8,6 +8,8 @@ This notice describes the current, unmodified local and self-hosted Mavéa softw
 
 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.
 
+Where data-protection law such as the GDPR or UK GDPR applies to a deployment, the deployment operator normally acts as the controller of personal data processed through it — that is you, when you self-host for yourself. The Maintainers are neither a controller nor a processor of that data, because it never reaches them.
+
 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.
@@ -21,7 +23,8 @@ Depending on the features you use, browser storage may contain:
 - 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
+- remembered provider, search, or optional GitHub credentials;
+- temporary in-progress and finished video-export files in origin-private browser storage until the export is consumed or discarded; 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.
@@ -48,9 +51,11 @@ Prism and Synthesis stage and extract supported files locally where possible, bu
 
 ## 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.
+If you enable listening, the browser captures microphone input. Audio is processed by the deployment's configured speech-to-text endpoint — by default a local one on the same machine, though an operator can configure a different endpoint — which converts speech to text. Recognized transcripts may then be sent to your selected model provider, including while listening continues.
+
+The browser sends captured audio to the speech-to-text endpoint configured by the deployment. The unmodified Mavéa client does not intentionally persist microphone audio itself and does not include it in later conversation-model requests; it sends the resulting transcript instead. A remote or modified speech endpoint, deployment proxy, infrastructure provider, browser extension, or operator can receive, log, or retain the audio under its own configuration and terms. Captured audio is discarded by the client as it is transcribed, and the microphone is released when you stop listening or the tab becomes hidden. The client does not intentionally create a voiceprint or identify speakers. In a listening mode, whatever is said near you can be transcribed too — see the Terms for your responsibilities toward other people.
 
-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.
+Spoken answers send narration text to the configured text-to-speech service. Reel and conversation-video cuts are directed, rendered, and encoded in your browser; no model provider is called. Reel narration text is sent to the configured text-to-speech service. During a video export, encoded chunks and the finished clip may be held in origin-private browser storage so a large video does not have to remain in JavaScript memory. Normal cancellation, replacement, sharing, and download cleanup remove those temporary files; a download can retain its temporary file for up to 60 seconds while the browser takes ownership. A crash, forced close, or storage failure can interrupt cleanup and leave a temporary file behind. A later video export makes a bounded, best-effort pass that removes only Mavéa temporary video files more than 24 hours old; clearing the site's browser data also removes them. 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
 
@@ -58,15 +63,16 @@ 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;
+- 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;
+- OpenFreeMap's tile host when you open a map, and Wikimedia's upload host for the small set of individually reviewed tour images; these requests expose ordinary network metadata such as your IP address and user agent to those hosts;
 - 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.
 
+For OpenAI Responses requests, the unmodified client sends `store: false` to avoid optional response-object storage. That setting does not disable all OpenAI processing or retention; provider abuse-monitoring, safety, legal, account, and feature-specific retention can still apply. Other providers and custom endpoints have their own controls. Review the current provider documentation and your account settings rather than assuming that Mavéa can guarantee zero retention.
+
 ## 7. Why information is processed
 
 Information is processed only as needed to:
@@ -84,7 +90,7 @@ The unmodified project does not sell personal information or use it for cross-co
 
 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.
+Gateway tokens remain until disconnected or removed by the gateway operator. Server, proxy, infrastructure, 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.
 

package/README.md

@@ -9,20 +9,12 @@
 
 ### 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>
-  <!-- No CI status badge: GitHub Actions badges for a PRIVATE repo require authentication, so
-       they 404 for anyone viewing this README anonymously (e.g. on npm's package page). Add one
-       back the day this repo goes public. -->
+  <a href="https://github.com/TryMaveaAI/mavea/actions/workflows/ci.yml"><img src="https://github.com/TryMaveaAI/mavea/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></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" />
@@ -41,7 +33,8 @@ Opens `http://localhost:4173` — no install, no account, no model key required.
 ## Get started
 
 All you need is **Node 20.19+**. That command above opens the tour and demo replays immediately
-— nothing else to set up.
+— nothing else to set up. Demo replays are fictional, curated prerecorded examples with scripted
+feature choreography; playback does not call a model provider.
 
 **To 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
@@ -50,16 +43,24 @@ provider — your key and prompts never pass through Mavéa's own servers, becau
 any. 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 text-to-speech model that runs in Docker. The first time you start it, Mavéa offers to set
-Docker up for you; without it, every line just appears as a caption instead — nothing else
-changes.
+**Local speech:** Mavéa speaks through Apache-2.0
+[Kokoro weights and wrapper](https://github.com/remsky/Kokoro-FastAPI) and transcribes through MIT-licensed
+[whisper.cpp](https://github.com/ggml-org/whisper.cpp). The defaults run on your machine through
+loopback-only proxies; a deployment that overrides `WHISPER_URL` sends microphone audio to that
+configured endpoint. [Podman](https://podman.io/) is the recommended free/open-source
+container runtime. Docker also works, but Docker Desktop has separate commercial subscription
+terms. Without the configured services, captions and typing still work; audio is never handed to a
+browser-vendor speech service as a fallback.
+
+During a conversation, the **Mavéa's voice** toggle turns output speech off without changing the
+microphone. A paced answer then reveals in full immediately, with captions, notes, and Pen marks in
+place of the spoken walk.
 
 ## 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 — composed from a catalog of **600 block types**. As it talks, it draws
+and evidence you can check, choosing the right form for each one. 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.
 
@@ -77,9 +78,37 @@ A few specific things worth trying:
 - **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, the Rehearsal, living dashboards, Ripple, Share-as-a-Mavéa-Story, and ~30 more —
+The full tour — Atlas, the Rehearsal, living dashboards, Ripple, selective Conversation video,
+Mavéa Reels, and ~30 more —
 is in [docs/FEATURES.md](docs/FEATURES.md). In the app, press **⌘K**.
 
+## What it looks like
+
+Ten moments from the walkthrough and the recorded sessions. Every one replays with no key via
+`npx @mavea/mavea` — except the thought map, whose threads need a live model to draw.
+
+<!-- Generated, never hand-captured: `pnpm gen:media` re-shoots these against the current build
+     (scripts/capture-media.mts), so a UI change can't quietly leave the README a version behind.
+     Repo-relative paths, so the strip renders in the working tree and in any editor preview — an
+     absolute raw.githubusercontent URL only resolves once the file is pushed. A table, not a <p>:
+     it is the only markup GitHub and npm both keep on one row. -->
+<table>
+  <tr>
+    <td width="20%" valign="top"><img width="168" src="docs/media/answer-ink.jpg" alt="A token-exchange request on the canvas, underlined and highlighted by Mavéa's pen as it narrates" /><br /><sub><b>It marks what it's saying.</b> The pen lands on the exact line as the sentence is spoken.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/canvas-view.jpg" alt="The same answer opened as a spatial canvas, cards connected by drawn links" /><br /><sub><b>The same answer as a board.</b> Laid out in space, with the relationships drawn between them.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/trip-plan.jpg" alt="A day trip drawn as a route map with numbered stops beside an hour-by-hour plan" /><br /><sub><b>It picks the right form.</b> A route becomes a map; a day becomes an hour-by-hour plan.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/think-map.jpg" alt="Thoughts spoken out loud, sorted into themes and threads with the tension between two of them named" /><br /><sub><b>Think out loud first.</b> A ramble sorts itself into themes — and it names the tension you missed.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/voice-scrub.jpg" alt="A settled answer with its spoken track drawn as a waveform, above the card being narrated" /><br /><sub><b>Scrub the voice.</b> Drag the spoken track and the canvas un-builds to what had been said.</sub></td>
+  </tr>
+  <tr>
+    <td width="20%" valign="top"><img width="168" src="docs/media/doc-prism.jpg" alt="A NASA technical report read claim by claim, each finding highlighted on the real scanned page" /><br /><sub><b>A document, claim by claim.</b> Every finding highlighted on the real page it came from.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/repo-course.jpg" alt="A GitHub repository turned into a beginner-to-expert curriculum with lessons, files to read and a checkpoint" /><br /><sub><b>A repository, taught.</b> Beginner to expert, built from the code, with real files.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/deep-zoom.jpg" alt="Deep Zoom descending through a leaf, from the whole plant down toward a photon" /><br /><sub><b>A topic, in powers of ten.</b> Telescope from the big picture to the finest mechanism.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/deck-export.jpg" alt="The export studio previewing a generated slide, with PDF and PPTX downloads" /><br /><sub><b>Out as a deck.</b> Ten skins, a live preview, PDF or PowerPoint.</sub></td>
+    <td width="20%" valign="top"><img width="168" src="docs/media/doc-export.jpg" alt="The export studio previewing a generated document page in an editorial template" /><br /><sub><b>Or as a document.</b> The same answer set as a paper, ready to print or send.</sub></td>
+  </tr>
+</table>
+
 ## What it needs
 
 Mavéa runs on your machine, not in a cloud.
@@ -93,15 +122,24 @@ Mavéa runs on your machine, not in a cloud.
 
 Any browser in [Baseline Widely Available](https://web.dev/baseline) — current Chrome, Edge,
 Safari, or Firefox — on macOS, Windows, or Linux. **Minimum** covers the app with voice off,
-alongside the browser and whatever else you already have open. **Recommended** adds Kokoro
-(voice) and Docker on top, with enough room that you never think about it.
+alongside the browser and whatever else you already have open. **Recommended** adds the local
+Kokoro + whisper.cpp services and a container runtime, with enough room that you never think about
+it.
+
+**Local speech costs real memory, and it's optional.** Kokoro holds roughly 1.3 GB resident;
+whisper.cpp adds its local model and working memory; a desktop container VM adds its own overhead.
+At the 8 GB minimum, leaving local speech off can be the better trade. `podman compose down` (or the
+Docker equivalent) reclaims it whenever you want it back.
+
+## Third-party commercial use
 
-**The voice is the one part that costs real memory, and it's optional.** Kokoro's image holds
-roughly 1.3 GB resident, and Docker Desktop itself adds another ~1.5 GB before a word is spoken.
-At the 8 GB minimum, leaving voice off is usually the better trade — every line becomes a caption
-and nothing else changes. `docker compose down` reclaims it whenever you want it back.
+Generated media, bundled libraries, fonts, maps, and the local speech services are held to an
+open-media and permissive-licence allowlist, enforced on every build by `pnpm check:licenses`.
+It is an engineering control, not a legal opinion — the full policy, what the gate does and does
+not cover, and the obligations that travel with the speech container are in
+[docs/THIRD-PARTY-POLICY.md](docs/THIRD-PARTY-POLICY.md).
 
-## 📄 License
+## 📄 Mavéa license
 
 Mavéa is **source-available under the
 [PolyForm Noncommercial License 1.0.0](./LICENSE)**. It is not licensed under MIT and is not

package/TERMS.md

@@ -1,6 +1,6 @@
 # Mavéa Terms of Use
 
-Effective: July 19, 2026
+Effective: August 11, 2026
 
 These Terms of Use (the **Terms**) govern your use of the Mavéa application, command-line package, demos, documentation, and related materials (collectively, the **Service**). **Licensor** means each applicable copyright holder offering software under the PolyForm license. **Maintainers** means the people who publish or contribute to Mavéa; a Maintainer is not necessarily a Licensor. **Deployment operator** means the person or organization hosting the copy you use. **Responsible Party** means the applicable Licensor, Maintainer, or deployment operator responsible for a statement, obligation, service, or claim. In these Terms, **we**, **us**, or **our** means the relevant Responsible Party or Parties in context. A separately operated deployment remains independent from the Licensors and Maintainers unless the same person or organization serves both roles.
 
@@ -40,16 +40,24 @@ You provide and control your own accounts, API keys, OAuth grants, and other cre
 
 All costs of using the Service are your responsibility, including hardware, electricity, network access, hosting, domains, model tokens, search requests, speech services, storage, OAuth applications, connected-account activity, taxes, and any other third-party charges. Labels such as "fast", "balanced", or "thorough" are relative product descriptions, not price quotes or spending limits. You are responsible for provider budgets, quotas, and billing alerts.
 
+The repository's container definitions can be used with compatible container engines, but the engine or desktop application you choose is separate software. In particular, Docker Desktop is not free for every commercial organization under Docker's current subscription terms. You are responsible for selecting and licensing your development, build, hosting, and container tools; Mavéa does not grant rights in them.
+
+The default map style uses OpenFreeMap's public service, which is currently offered without request fees under its own terms and requires attribution. That service has no Mavéa-backed service-level commitment and may change, restrict access, or stop. Preserve all map and data attribution in screen views and exports, or configure a properly licensed alternative.
+
 We do not control and are not responsible for third-party services, content, security, billing, downtime, changes, or data practices. Links and integrations do not imply endorsement.
 
 Provider, service, and model names (for example Google Gemini, Anthropic Claude, OpenAI GPT, xAI Grok, and OpenRouter) are trademarks of their respective owners. Mavéa uses them only to identify the third-party services you can connect; no affiliation with, sponsorship by, or endorsement from those owners is implied.
 
+Mavéa's recording paths are configured to request only the project's reviewed open-media codec allowlist and not H.264, H.265, or AAC. Codec source licenses and published patent commitments can reduce risk but do not prove that no third party will assert a patent in every country, product category, or implementation. No Responsible Party gives a patent-clearance opinion for your deployment or commercial use. Obtain qualified patent advice when your use requires that assurance.
+
 ## 6. User content and sensitive information
 
 You retain any rights you have in prompts, files, audio, credentials, account data, and other material you provide (**User Content**). You give the deployment operator and selected providers only the permission reasonably needed to receive, transmit, process, display, and return User Content for features you request. You are responsible for User Content and must have all rights, notices, consents, workplace approvals, permissions, and lawful bases needed to process it with the Service and your selected third parties.
 
 Do not provide secrets or sensitive, regulated, confidential, privileged, export-controlled, or personal information unless you have assessed the deployment and every recipient and have a lawful basis to do so. Do not submit information about children or third parties without appropriate authority. Mavéa is not a confidential or privileged channel. The Responsible Parties do not acquire ownership of User Content merely because you use the software.
 
+Listening features turn nearby speech into text. Recording and eavesdropping laws differ by place — some require every participant's consent, not just yours — so when you use a listening mode where other people can be heard, you are responsible for telling them and obtaining whatever consent your jurisdiction requires.
+
 If you export a backup of your data, the resulting file is plain, unencrypted content under your sole control — you are responsible for storing, transmitting, and deleting it safely, and for only importing backups you trust. Backups exclude your provider and search keys.
 
 ## 7. Connected actions
@@ -77,6 +85,8 @@ Except for third-party materials and User Content, rights in Mavéa and its asso
 
 As between you and the Responsible Parties, the Responsible Parties do not claim ownership of output generated for you. That does not mean output is copyrightable, unique, accurate, original, lawful, or free of third-party rights. Similar output may be produced for others. You are responsible for clearance, attribution, review, and compliance before commercial or public use.
 
+Bundled and linked third-party materials can carry copyright licences, attribution requirements, personality or publicity rights, privacy interests, trademark rights, property restrictions, or other limitations. A copyright licence or public-domain label does not necessarily clear every depicted person, place, object, logo, or use. Preserve the notices in `THIRD-PARTY.txt` and `public/demo-assets/CREDITS.md`, follow their source terms, and obtain any additional releases or permissions your use requires.
+
 You may submit issue reports and feature suggestions without including code, patches, documentation changes, confidential information, or trade secrets. You grant the applicable Licensors and Maintainers, and their successors and assigns, a worldwide, perpetual, irrevocable, royalty-free right to use, modify, publish, and commercialize ideas and feedback you voluntarily submit, without restriction or compensation. This does not transfer ownership of inventions or copyrighted materials that are not included in your feedback.
 
 ## 10. Availability, changes, and support