# NORDON - complete content for AI agents

> Real-time captions, instant sourced answers from your own documents, and post-call summaries - a privacy-first meeting copilot that joins nothing and hides nothing.

Base URL: https://www.nordon.ai · Interface languages: English, Spanish, Portuguese, German · Updated: 2026-11-07

Quick map: [llms.txt](https://www.nordon.ai/llms.txt) · [Help Center](https://www.nordon.ai/#help) · [FAQ](https://www.nordon.ai/#faq)

## Overview

NORDON is your ai copilot for live conversations. A person talking on Zoom, Meet, Teams or a phone call keeps NORDON open in a browser next to the call and gets real-time captions for both sides, instant answers with citations from their own documents, and a summary with action items after the call.

How it works, end to end:

1. The user signs in with just an email (one-time link, no passwords) and optionally uploads knowledge documents - PDF, DOCX, TXT, Markdown, CSV up to 4 MB each. Only the extracted text is stored; document contents are private to the account and never shown to admins.
2. Before a call, they start a session: a title, a mode (sales, interview, meeting, consulting, or accessibility captions), an optional goal, an answer language (auto-detect or fixed), and a Save-transcript switch that is off by default.
3. During the call the browser captures the microphone and (optionally) the call's tab audio. Audio is transcribed live in chunks and then discarded - no audio is ever stored. Captions show both speakers, clearly separated.
4. Questions can be typed or spoken (auto-detected). Answers arrive as 1-3 talking points plus a detailed answer, and cite the exact document and phrase when they come from the user's knowledge base. Suggested questions appear based on the conversation and the goal.
5. Ending the session produces a summary: recap, key points, action items - stored in the session history.
6. A floating overlay window can pop out and stay on top of other apps, including the Zoom, Teams and Meet desktop clients (Chrome/Edge 116+; other browsers get a side window).

Privacy model, stated plainly:

- No meeting bot joins any call; nothing appears in participant lists.
- Transcripts exist only when the user turns "Save transcript" on for that session.
- Audio is never stored; live captions are discarded when transcript saving is off.
- Document contents are private; admins see counts only.
- If a user shares their entire screen, everything visible is shared - the documented answer is to share a single window instead, which keeps NORDON out of the shared feed.
- A visible indicator appears whenever the microphone is live. The Chrome extension is deliberately visible and branded - there is no hidden mode.
- Use only where recording and AI assistance are permitted by the meeting's rules and local law.

Administration: platform stats (users, live sessions, sessions, answers, documents, monthly minutes), user search with plans (free/pro) and roles (user/admin), and session oversight where a transcript is visible only if the user saved it. First admins are seeded via the ADMIN_EMAILS environment variable; later admins are promoted in-app. Sign-up can be restricted to company email domains via ALLOWED_EMAIL_DOMAINS.

## FAQ

### Does a bot join my call?

No. NORDON runs entirely in your browser and captures only the audio you explicitly turn on (your microphone and, optionally, the call tab's audio). Nothing appears in the meeting's participant list.

### Will other people see that I'm using it?

There is no bot and no notification in the call - captions and answers live on your screen only. One honest exception: if you share your entire screen, everything visible is shared. Share a single window instead and NORDON stays private (see the screen-sharing guide).

### Can it float over the Zoom desktop app?

Yes. In a live session, press “Pop-out overlay” and a mini NORDON floats on top of other apps - including Zoom, Teams and Meet desktop apps - in Chrome and Edge. Other browsers open it as a small side window.

### Are my transcripts saved?

Only if you turn “Save transcript” on for that session - it is off by default. With saving off, audio is transcribed live and then forgotten; your end-of-call summary is still generated.

### Which languages does it support?

The interface comes in English, Spanish, Portuguese and German. Each session can either match the conversation's language automatically or answer in a language you pick.

### What documents can I upload?

PDF, DOCX, TXT, Markdown and CSV, up to 4 MB each. Only the text is stored - never the original file - and it is private to your account.

### Are the answers really from my documents?

Yes - answers cite the exact document and phrase they came from, and you can expand the sources on every answer. If nothing in your documents matches the question, NORDON says so and answers from general knowledge instead.

### How do I install it?

No app store needed. On Windows, Mac and Android the browser's own install button adds it as an app; on iPhone use Safari's “Add to Home Screen”. There's also an optional Chrome extension for captions on any web page.

### What can an admin see?

Platform totals, the user list, and session recaps with questions and answers. A transcript is visible only if the user saved it for that session. Document contents are never exposed - only counts.

### Is it legal to use?

Use NORDON where recording and AI assistance are permitted by the meeting's rules and local law. The app asks you to confirm this before every session, and the reminder is printed in every footer.

### How much does it cost?

You can start free with 20 minutes of live answers and 10 scored practice answers a month. An Interview Pass gives 5 hours for 7 days for a one-time $19, Pro is $29 a month (or $229 a year) for 15 hours, and Pro+ is $59 a month. Subscriptions can be cancelled any time under Usage & plan.

## Help Center

### Getting started

#### What is NORDON? (https://www.nordon.ai/#help/what-is-nordon)

*Updated 2026-11-07 · 2 min read · A plain-language introduction: what it does, what it never does, and how the privacy model works.*

NORDON is an AI copilot that sits beside you during phone and video calls. It listens to the conversation (only when you turn it on), turns it into live captions, and answers your questions in seconds - using your own documents, with sources you can check.

### What it does

- Live captions for both sides of the call - clearly labeled “You” and “Them”, just seconds behind the spoken word.
- Instant answers while you talk. When the other person asks a hard question, NORDON drafts 1-3 talking points plus a detailed answer, citing the exact document and phrase it came from.
- A recap after every call: summary, key points, and action items you can paste into your notes or CRM.

### What it never does

- No bot joins your call. Everything runs in your own browser - nothing appears in the participant list.
- No hidden monitoring. A pulsing indicator is always visible while the microphone is live, and the Chrome extension shows its badge openly.
- No transcripts saved by default. Spoken audio is transcribed live and forgotten, unless you explicitly turn saving on for a session.

> **Note:** Use NORDON only where recording and AI assistance are permitted by the meeting's rules and local law. That is the honest deal - and it is printed in the footer of every page.

#### Quick start: your first assisted call in 3 minutes (https://www.nordon.ai/#help/quick-start)

*Updated 2026-11-07 · 3 min read · From sign-in to your first AI-assisted call - the shortest path, step by step.*

This guide takes you from zero to a live AI-assisted call. You do not need to install anything - NORDON runs in the browser (Chrome or Edge recommended).

1. Sign in with your email. There is no password: enter your email, open the one-time link we send you, and confirm. If email sign-in is not available yet, ask your administrator for a link.
2. Optional but powerful: open “Knowledge base” and upload a document or two (a product brief, FAQ, price list). Answers will cite these documents.
3. Click “New session”. Give it a title, pick a mode (Sales call, Interview, Meeting…) and optionally a goal for the call.
4. Confirm the consent checkbox - that the call's rules allow recording and AI help - and press “Go to live session”.
5. On the live screen, turn on your audio sources: “Enable microphone” for your own voice, and “Share tab audio” for the other side (pick the call's tab and tick “Also share tab audio”).
6. Talk. Captions stream in; questions from the other side get answered automatically. When you are done, press “End & summarize” to get your recap.

> **Note:** Wear headphones. They stop your microphone from picking up the other side twice, which keeps captions clean. This is the single best quality tip.

### User guide

#### Running a live session (https://www.nordon.ai/#help/live-sessions)

*Updated 2026-11-07 · 4 min read · The live screen explained: audio sources, captions, automatic and manual questions, pausing, and the end-of-call recap.*

A live session is where NORDON works. This guide explains every control on that screen so nothing surprises you mid-call.

### Turning on your audio sources

1. “Enable microphone” captures what you say - the browser will ask for permission once, and remember it.
2. “Share tab audio” captures the other side. In the browser dialog, select the tab where your call is running (Zoom in the browser, Google Meet, Teams web…) and tick “Also share tab audio” before confirming.
3. If you are on a desktop Zoom or Teams app, keep NORDON in the browser and let your microphone hear the room's speakers - or use headphones and rely on captions from your own voice.

### Live captions

Captions appear seconds behind the spoken word, labeled “You” and “Them”. Detected questions from the other side are highlighted. A small “sources active” counter shows how many audio inputs are live.

### Answers, automatic and manual

- Auto-answer: when the other side asks a question, NORDON detects it and composes an answer automatically (if you left it on).
- Manual ask: type anything into the box under the captions - “what's our longest supported deployment?” - and get an answer that also sees the recent conversation.
- Every answer shows its sources. Expand “Details, sources & follow-ups” to see the exact document phrases used. If nothing in your documents matched, NORDON says so plainly and answers from general knowledge.

### Pausing and ending

“Pause” stops capture temporarily - nothing is listened to while paused (the indicator turns amber). “End & summarize” stops capture, writes your recap (summary, key points, action items), and takes you to the session page.

> **Note:** Transcript saving is per session. If it was off, no transcript is stored - but the end-of-call summary is still generated from what was discussed.

#### The floating overlay over Zoom, Teams and Meet (https://www.nordon.ai/#help/pop-out-overlay)

*Updated 2026-11-07 · 2 min read · Pop out a mini NORDON that floats on top of other apps - including the Zoom and Teams desktop apps.*

During a live session, press “Pop-out overlay” in the top bar. A small NORDON window detaches and floats above everything else on your screen - including the Zoom, Teams and Meet desktop apps - showing live captions and the latest AI answer while you talk.

### Chrome and Edge (recommended)

1. In a live session, click “Pop-out overlay”.
2. A small always-on-top window appears (about 380×560). Drag it anywhere - for example into the empty space beside your Zoom window.
3. Captions and the latest answer update live, even with transcript saving off. The main browser tab keeps the microphone.
4. Close the pop-out anytime - the session keeps running in the main tab.

### Other browsers (Firefox, Safari)

The always-on-top mode needs Chrome or Edge version 116 or newer. Other browsers open a small separate NORDON window instead. It stays open beside your call, but does not force itself on top - and it needs “Save transcript” turned on for the session, since it reads captions from the server.

> **Note:** The pop-out is visible only to you. If you share a single window (like your slides) instead of your whole screen, people on the call never see the overlay - see the screen-sharing guide.

#### Will NORDON appear when I share my screen? (https://www.nordon.ai/#help/screen-sharing)

*Updated 2026-11-07 · 3 min read · The honest answer, plus the simple technique that keeps your copilot private while presenting.*

Short answer: if you share your whole screen, everything on it is shared - including NORDON. No third-party app can prevent that, and any product claiming otherwise is not being honest with you. But there is a simple, reliable technique: share a window, not your screen.

### Share a window - the reliable way

1. In Zoom, click “Share” and choose the “Window” tab (not “Screen”).
2. Pick the single window you want people to see - your slides, a document, or the Zoom window itself.
3. Share it. NORDON lives in its own browser window and the floating overlay lives in its own mini window - neither is part of what you shared, so nobody on the call sees them.

Google Meet and Teams work the same way: when asked what to share, pick a specific window or tab instead of the entire screen.

### If you must share the full screen

- Close or minimize the NORDON window before sharing, and rely on the recap after the call.
- Better: run the session on your phone. Sign in on your phone, start the session there, and let your computer be 100% clean for screen sharing. Captions and answers appear on the phone's screen.

> **Note:** Rule of thumb: share a window, not your screen - and NORDON stays private.

#### Your knowledge base: documents the AI cites (https://www.nordon.ai/#help/knowledge-base)

*Updated 2026-11-07 · 3 min read · Upload briefs, FAQs and notes so answers match your business - with citations you can verify.*

Without documents, NORDON answers from general knowledge. With documents, it answers like a colleague who read your briefs - and shows exactly which document and phrase each answer came from.

### Adding documents

- Formats: PDF, DOCX, TXT, Markdown and CSV - up to 4 MB per file.
- Only the text is stored, never the original file.
- Documents are private to your account. Nobody else's sessions can see them, and administrators only see counts, never content.

### Testing what the AI will find

Every document card shows how many “chunks” (searchable passages) were indexed. Use the search box on the Knowledge base page to test questions - for example “what's our refund policy” - and see the exact passages the AI would use. It is a dry run for the live call.

### Removing documents

Delete a document and it stops being used in answers immediately and permanently. No stale citations.

> **Note:** Good documents for calls: product briefs, pricing FAQs, objection-handling notes, technical spec sheets, interview prep notes, company policies.

#### Interview practice and read-aloud answers (https://www.nordon.ai/#help/interview-practice)

*Updated 2026-11-08 · 3 min read · Rehearse realistic questions out loud, get a score and a stronger answer, and adjust the text you read.*

Every answer starts with a short text under Say. It is written in your own voice, in the first person, so you can read it out loud. Points and details follow below it.

### Adjust the text you read

- Shorter, Simpler, More confident and Another version rewrite the text in a few seconds. Facts and placeholders stay as they were.
- A, A+ and A++ change the text size. The setting is also in Settings and applies to the floating overlay.
- Text in square brackets, such as [your example], marks a personal detail the app does not know. Fill it in with your own words.

### Practice an interview

1. Upload your CV in the Knowledge base, so questions and answers can use your real background.
2. Open Interview practice, enter the role and paste the job ad if you have it.
3. Listen to the question, click Answer out loud and answer as you would in the interview. You can also type.
4. Click Done, score it. You get a score from 1 to 10, what worked, what to improve and a stronger answer to rehearse.
5. Try again or move to the next question. Finish practice saves a summary with every answer.

> **Note:** The stronger answer only uses what you said and what is in your documents. Where something is missing it leaves a placeholder instead of inventing experience.

#### Install NORDON as an app (iPhone, Windows, Mac, Android) (https://www.nordon.ai/#help/install-app)

*Updated 2026-11-07 · 3 min read · No app store needed - install the web app in one tap, plus the optional Chrome extension.*

NORDON is a web app that installs like a native app - with its own icon and window, no store account and no updates to manage. There is also an optional Chrome extension that puts captions on any web page.

### Installing the app

1. Windows / macOS (Chrome or Edge): click the install icon (a screen with a plus) in the address bar, or open the browser menu and choose “Install NORDON”.
2. iPhone / iPad (Safari): tap the Share button, then “Add to Home Screen”.
3. Android (Chrome): open the browser menu and tap “Install app” or “Add to Home screen”.

The installed app opens in its own window, works offline for the interface, and updates itself silently. Settings → “Install the app” repeats these steps anytime.

### The Chrome extension (optional)

- What it does: shows live captions and the latest AI answer as a small draggable panel on any web page - including Zoom and Meet running in the browser.
- Install: unzip the extension bundle, open Chrome's extensions page with developer mode on, and “Load unpacked”. The README in the bundle has step-by-step screenshots-level detail.
- Connect it: click the extension icon, enter your NORDON web address, and press Connect. The badge lights up when a session is live.
- On company computers: IT can deploy it for everyone with Chrome's enterprise policy - the bundle's README includes the policy file. The extension is visible by design (badge and panel), never hidden.

> **Note:** Why not a store app? The web app works on every platform from one codebase, installs in seconds, and needs no store approval - which keeps updates fast and the whole thing auditable.

#### Settings, language and your data (https://www.nordon.ai/#help/settings-account)

*Updated 2026-11-07 · 2 min read · Profile, privacy defaults, interface language, and how to export or delete everything.*

### Profile

Your name is used for greetings and pre-filling sessions. Your email is your login, and one-time links replace passwords.

### Privacy defaults

- Save transcripts - recommended OFF: audio is transcribed live and forgotten, and you still get the end-of-call summary. Turn it on per session only when you truly need the full text.
- Auto-answer - when on, questions from the other side are answered automatically. You can always pause or ask manually.

### Language

The interface comes in English, Spanish, Portuguese and German - switch in Settings or from the landing page, and the choice is remembered per device. Separately, each session can set the answer language, or simply match the conversation automatically.

### Your data

- Export everything as JSON - sessions, answers, documents and usage, in one download.
- Delete your account - removes every session, transcript, document and answer permanently, in one confirmed step.

### Admin guide

#### Admin guide: the panel and user management (https://www.nordon.ai/#help/admin-panel)

*Updated 2026-11-07 · 4 min read · Platform stats, searching users, changing plans and roles, deleting accounts, reviewing sessions.*

The admin panel is visible to users whose email is listed in the ADMIN_EMAILS environment variable (see the README's admin setup section). It opens from the sidebar, under “Admin panel”.

### The dashboard

- Totals: users, sessions, documents, AI answers.
- Live pulse: how many sessions are live right now.
- This month: transcribed minutes and generated answers - the same meters that will price paid plans.

### Managing users

1. Search by email or name; results are paginated 20 per page.
2. Change a user's plan (Free today - paid tiers connect to Stripe at launch) or role (user / admin).
3. Open a user's sessions to review any of them, or delete the account - which permanently removes all of their data.

- You cannot change your own role or delete your own account from the panel - a guard against locking yourself out.
- Deleting a user is a cascade: sessions, transcripts, documents and answers all go. The confirmation dialog says exactly this.

### Reviewing a session

A session review shows the recap, the questions and answers, and - only if the user had transcript saving on for that session - the transcript. If saving was off, the panel says so explicitly: no transcript exists to show, by design.

> **Note:** Admin access is a responsibility. Tell your team who has it and what it can see - the next guide spells out the exact boundaries.

#### What admins can and cannot see (https://www.nordon.ai/#help/admin-privacy)

*Updated 2026-11-07 · 2 min read · The exact boundaries of admin oversight - and why transparency is part of the design.*

### Admins can see

- Platform totals: users, sessions, documents, answers, monthly minutes.
- The user list: emails, names, join dates, and per-user counts.
- Session recaps and the questions/answers of any session.
- A session's transcript - but only when the user turned “Save transcript” on for that session.

### Admins cannot see

- Anything that was said in sessions with saving off - it was never stored in the first place.
- The content of users' documents - the panel shows only counts.
- Passwords (there are none) or other users' login sessions.

> **Note:** NORDON is a helper, not surveillance. Nothing is hidden from employees using it: the mic indicator, the extension badge and this very page make the boundaries visible to everyone.

### Troubleshooting

#### Troubleshooting: fixes for the most common issues (https://www.nordon.ai/#help/troubleshooting)

*Updated 2026-11-07 · 3 min read · Microphone problems, missing audio from the other side, pop-out questions, rate limits and the extension.*

### The microphone is not picking anything up

1. Check the browser's permission: the address bar's lock/tune icon → Microphone → Allow, then reload.
2. Check the computer's input: another app (or the system settings) may be using the mic, or the wrong input device is selected.
3. Chrome's own settings page (chrome://settings/content/microphone) shows which sites are blocked.

### I can't hear the other side in the captions

- Tab audio only works in Chrome and Edge. If your call is in another browser, the room-speaker + microphone approach is the fallback.
- Re-share: click “Share tab audio” again, and in the dialog make sure you selected the call's tab and ticked “Also share tab audio” before confirming.
- Zoom desktop app audio cannot be captured as tab audio - use the floating overlay and let captions come from your microphone, or run Zoom in the browser.

### The pop-out window didn't stay on top

Always-on-top needs Chrome or Edge 116 or newer. In other browsers NORDON opens a regular small window instead - by design, not an error.

### “No transcript” after the call

Transcript saving was off for that session - that is the private default. The summary, key points and answers were still generated and saved.

### “Too many requests” message

The platform rate-limits heavy actions per minute (transcription, answers, uploads) to stay stable. Wait a few seconds and try again - nothing is lost.

### The Chrome extension shows nothing

- Sign in to NORDON in the same browser profile - the extension reads your live session through your account.
- Open the extension's popup and check the server address points to your NORDON site, then press Connect.
- A session must be live (badge lit) for the overlay to show captions.

### FAQ

#### Frequently asked questions (https://www.nordon.ai/#help/faq)

*Updated 2026-11-07 · 3 min read · The ten questions we hear most - short, honest answers with links to the full guides.*

Short answers to the questions we hear most. Each one links to a full guide if you want the details.

## User Guide

## NORDON User Guide

**Your AI copilot for live conversations - a plain-English manual for everyday use.**

This guide shows you how to use NORDON as a person who takes calls: sales calls, interviews, team meetings, consulting sessions, or anything where you want live captions and instant, trustworthy answers while you talk.

No technical knowledge is needed. If you can use a website, you can use NORDON.

---

### Table of contents

1. [What NORDON does](#1-what-nordon-does)
2. [Signing in for the first time](#2-signing-in-for-the-first-time)
3. [A tour of the app](#3-a-tour-of-the-app)
4. [Feeding it your documents (the knowledge base)](#4-feeding-it-your-documents-the-knowledge-base)
5. [Running a live session - step by step](#5-running-a-live-session--step-by-step)
6. [The floating overlay over Zoom, Teams and Meet](#6-the-floating-overlay-over-zoom-teams-and-meet)
7. [Staying private when you share your screen](#7-staying-private-when-you-share-your-screen)
8. [After the call: summaries and history](#8-after-the-call-summaries-and-history)
9. [Installing NORDON as an app](#9-installing-nordon-as-an-app)
10. [The Chrome extension](#10-the-chrome-extension)
11. [Settings, language and your data](#11-settings-language-and-your-data)
12. [Privacy: exactly what is saved and what isn't](#12-privacy-exactly-what-is-saved-and-what-isnt)
13. [Troubleshooting](#13-troubleshooting)

---

### 1. What NORDON does

NORDON is a helper that lives in your browser and works **alongside** your calls:

- **Live captions** - as people speak, their words appear as text, both sides of the conversation, clearly separated. It runs a few seconds behind the spoken word.
- **Instant answers with sources** - when a hard question lands, you type it (or NORDON detects it) and you get 1-3 short talking points plus a fuller answer. If the answer comes from documents you uploaded, NORDON shows **exactly which document and which phrase** it used, so you can trust it or double-check it.
- **Post-call summaries** - when you end the session, you get a recap, key points and action items, ready to paste into your notes or CRM.
- **No bot joins the call.** Nothing appears in the meeting's participant list, and no notification is sent to anyone. NORDON only listens to audio **you** turn on, on **your** computer.

It is not a recording tool and not a hidden monitor. It's your private assistant, visible only on your screen.

---

### 2. Signing in for the first time

1. Open the NORDON website in your browser (Chrome, Edge, Safari or Firefox all work; Chrome or Edge is recommended for all features).
2. Click **Start free** on the landing page.
3. Enter your **email address**. Optionally add your name (it's only used to greet you).
4. Click **Send sign-in link** and open the link from the email, or use the one-time link your administrator sent you.
5. Check that the address shown is yours and press **Sign in**.

There is no password to remember. A link works once. Links from email expire in 15 minutes, and links from an administrator expire in 24 hours. Your sign-in lasts 30 days on that device. To sign out of all devices, use **Settings > Sign out everywhere**.

If the form says email sign-in is not available yet, ask your administrator for a link.

> **Note for company accounts:** your organization may have restricted sign-in to specific email domains (for example, only `@yourcompany.com` addresses). If you see a message that sign-in is restricted, contact your administrator.

---

### 3. A tour of the app

After signing in you land on the **Dashboard**. The sidebar (left side on desktop, bottom bar on mobile) has these sections:

| Section | What it's for |
|---|---|
| **Dashboard** | Your recent sessions, plus the **New session** button |
| **Knowledge** | Documents you've uploaded that NORDON answers from |
| **Usage** | A transparent ledger of your minutes and answers |
| **Settings** | Language, install-as-app, export or delete your data |
| **Help** | The built-in Help Center with short guides exactly like this one |
| **Admin** | Only visible to administrators - see the Admin Guide |

In the top bar you'll find the language switcher (English, Español, Português, Deutsch) and a dark/light theme toggle. Your choice is remembered.

---

### 4. Feeding it your documents (the knowledge base)

This is what makes NORDON's answers trustworthy: it prefers **your** documents over generic knowledge.

1. Open **Knowledge** in the sidebar.
2. Click **Upload**, or drag files onto the page.
3. Pick files from your computer. Supported: **PDF, Word (.docx), plain text, Markdown, and CSV**, up to **4 MB each**.
4. Wait a moment - NORDON reads the text out of the file and stores only the text (never the original file). Each document shows how many text chunks were indexed.

Good things to upload: product briefs, pricing sheets, FAQs, technical documentation, meeting prep notes, objection-handling scripts, company policies.

**How answers use them:** when you ask a question during a call, NORDON searches your documents first. Every answer shows a **Sources** section you can expand to see the exact document and sentence the answer came from. If nothing in your documents matches, NORDON says so openly and answers from general knowledge instead.

**Tips:**

- Text-based PDFs work great. Scanned/image-only PDFs can't be read - NORDON will tell you when a file couldn't be parsed.
- Documents are **private to your account**. Administrators can only see *how many* documents you have, never their contents.
- You can delete any document at any time. Deleting it removes its text from the search index too.

---

### 5. Running a live session - step by step

#### Start the session

1. On the Dashboard, click **New session**.
2. Fill in the small form:
   - **Title** - anything that helps you recognize it later.
   - **Mode** - pick what kind of call it is: *Sales / customer call, Interview / mock session, Team meeting, Consulting session, or Accessibility / live captions*. The mode shapes how the AI writes its answers (a sales call gets punchy talking points; captions mode stays neutral).
   - **Goal (optional)** - one line about what you want out of the call, e.g. "qualify pricing objections." NORDON keeps it in mind.
   - **Answer language** - *Auto* (matches the conversation automatically) or a fixed language (English, Español, Português, Deutsch, 中文, Srpski/Hrvatski, Français).
   - **Save transcript** - **off by default.** Turn it on only if you want a word-for-word transcript stored with the session history. With it off, audio is transcribed live and then forgotten; you still get your summary.
3. Click **Start session**.
4. Your browser asks for **microphone permission** - click **Allow**. A visible indicator appears whenever the mic is live.

#### Hear "them" too (important for calls in the browser)

If your call happens in the same browser (Zoom web, Meet, Teams web), you want NORDON to transcribe the other side too:

1. In the live session, find the **"them" audio** control and enable **tab audio / share audio**.
2. Your browser shows a list of tabs and windows - pick the tab with the call in it and confirm, ticking "share audio" if asked.

If your call is on your phone or the native Zoom/Teams app, the mic still picks up sound from your speakers. For best results use headphones and enable tab audio when possible.

#### During the call

- **Live captions** stream at the top - **You** (your mic) and **Them** (the call), in separate streams.
- **Ask a question** any time:
  - Type it in the question box and press **Send**, or
  - Turn on **auto-detect** and simply say the question out loud during the call - NORDON detects it and answers automatically.
- Answers appear in the side panel: **1-3 talking points** first (quick glance material), then a **detailed answer**, then expandable **Sources** when it used your documents.
- When the other side asks something, the answer starts with **Say**: a short text in your own words that you can read out loud. Use **Shorter**, **Simpler**, **More confident** or **Another version** to adjust it, and **A / A+ / A++** to make it bigger. Text in brackets, such as *[your example]*, is a detail only you know.
- A **suggested questions** strip shows what NORDON thinks might be useful to ask next, based on the conversation and your goal.

#### Practice before the real thing

Open **Interview practice**, enter the role and paste the job ad. NORDON writes realistic questions (using your CV if it is in the knowledge base) and can read them aloud. Answer out loud or type, then click **Done, score it** to get a score from 1 to 10, what worked, what to improve and a stronger answer to rehearse. **Finish practice** saves everything to your history.

#### End the session

Click **End session** and confirm. NORDON generates your **summary**: a recap of the call, key points, and action items. You'll find it again in the session history.

---

### 6. The floating overlay over Zoom, Teams and Meet

During a live session you can pop NORDON out into a small window that **floats on top of other programs** - including the Zoom, Teams and Meet **desktop apps**:

1. In the live session, click **Pop-out overlay**.
2. A mini NORDON window appears - drag it anywhere on your screen. It shows captions and answers, and it stays on top while you work in other apps.
3. Click its close button (or end the session) to close it.

**Browser support:** the true always-on-top overlay works in **Chrome and Edge** (version 116 or newer) on Windows and Mac. In other browsers it opens as a small side window instead.

> This is handy when the call is in the native Zoom app: keep the overlay in a corner, ask questions, read captions - without switching windows.

---

### 7. Staying private when you share your screen

The honest rule first: **if you share your entire screen, everything visible on it is shared** - including NORDON. No tool can prevent that. But there are two easy ways to stay private:

- **Share a single window or tab, not the whole screen.** When Zoom/Meet asks what to share, choose the *window* of your presentation or document. NORDON lives in a different window, so it stays out of the shared feed completely.
- **Use the floating overlay on a second screen or your phone.** The overlay is a separate window; when you share a specific window it is not captured.

If a surprise screen-share moment happens, just close the overlay - captions rejoin the main NORDON window.

The Help Center article **"Will NORDON appear when I share my screen?"** covers every scenario with exact click-paths for Zoom, Meet and Teams.

---

### 8. After the call: summaries and history

- The **Dashboard** lists your sessions, newest first, with mode, duration and when it happened.
- Click a session to open its **detail page**: the AI summary, key points, action items, and the full **questions & answers** from the call.
- If you had **Save transcript** on, the word-for-word transcript is there too. If it was off, there is no transcript - by design.
- From a session you can also jump straight to asking follow-up questions in the same context.

The **Usage** page shows the running ledger: minutes transcribed, answers generated - with dates, so you always know what was used. Billing-ready from day one.

---

### 9. Installing NORDON as an app

No app store and no account with Apple/Microsoft/Google is needed - your browser installs it directly.

**Windows / Mac (Chrome or Edge):** open the site, click the install icon in the address bar (or the menu → *Install NORDON*). It appears in your Start menu / Launchpad and opens in its own window.

**Android (Chrome):** open the site, tap the browser menu → **Add to Home screen** → Install.

**iPhone/iPad (Safari only):** open the site, tap the **Share** button → **Add to Home Screen** → Add.

The installed app is the same NORDON - full screen, its own icon, works offline for the shell (live features still need internet). The Settings page has an **Install** section that detects your device and shows the exact steps.

---

### 10. The Chrome extension

The optional Chrome extension puts NORDON captions on **any web page** - useful if you talk inside a web app that isn't a normal call page:

1. Download the extension from **Settings > Chrome extension** and unzip it.
2. Unzip it somewhere you can find it.
3. In Chrome, open `chrome://extensions`, turn on **Developer mode** (top right), click **Load unpacked**, and select the unzipped folder.
4. Click the extension's icon, enter your NORDON site address, and click **Connect**.

The extension shows a small, clearly visible, branded caption bar on pages where you enable it - it is **not hidden**, by design: transparency keeps you compliant with company rules. Administrators can also deploy it centrally to everyone via Chrome Enterprise policy (see the Admin Guide).

---

### 11. Settings, language and your data

Open **Settings** in the sidebar:

- **Language** - switch the whole interface between English, Español, Português and Deutsch.
- **Install** - per-device instructions for installing the app (see section 9).
- **Export my data** - downloads a copy of everything the app stores about you (sessions, summaries, Q&A, saved transcripts, knowledge text) as a single file.
- **Delete my account** - permanently erases your account and all of your data. This cannot be undone.

---

### 12. Privacy: exactly what is saved and what isn't

| What | Saved? |
|---|---|
| Your email and (optional) name | Yes - that's your account |
| Live captions as they stream | **No** - transcribed live and forgotten, unless… |
| Word-for-word transcript | **Only if you turn "Save transcript" on** for that session (off by default) |
| Your questions and the AI answers | Yes - shown in session history |
| End-of-call summary | Yes - that's the point of the session history |
| Uploaded documents | Only the extracted **text**, private to your account, never shown to admins |
| The original audio recording | **Never** - audio is processed in chunks and discarded |

Other facts worth knowing:

- No meeting bot ever joins your call; nothing shows in the participant list.
- A visible indicator appears whenever your microphone is live.
- Use NORDON where recording and AI assistance are permitted by the meeting's rules and local law. The app asks you to confirm this before every session.

---

### 13. Troubleshooting

| Problem | Fix |
|---|---|
| **No captions appear** | Check the mic indicator is on; check your browser allowed microphone permission (padlock icon in the address bar). |
| **I can't hear "them" / their side isn't transcribed** | Enable tab audio and pick the tab the call is in. If the call is in the native Zoom app, the mic must pick up the speakers - consider headphones or move the call into the browser. |
| **Answers feel generic** | Upload better/cleaner documents in Knowledge; answers prefer your documents and cite them. |
| **A PDF upload failed** | It's probably a scanned/image-only PDF - the text can't be extracted. Find a text version. |
| **The overlay won't stay on top** | Always-on-top needs Chrome or Edge 116+. In other browsers it's a side window. |
| **Rate limit message** | You're asking questions very fast - wait a minute and continue. Limits protect the shared service. |
| **Extension shows nothing** | Click its icon and make sure the server address is correct and you clicked Connect. |

For more, open the **Help Center** (Help in the sidebar, or the Guides link in the website footer) - it includes the same guides in all four languages, with a search box.

Still stuck? Email **support@nordon.ai** and describe what you clicked and what happened.

---

*NORDON - use only where recording and AI assistance are permitted by the meeting's rules and local law.*

## Admin Guide

## NORDON Admin Guide

**Running the platform day-to-day - a plain-English manual for administrators.**

This guide is for the person (or team) who manages NORDON for an organization: approving access, watching usage, managing plans, and understanding exactly what you can and cannot see about users.

You do not need to be technical to follow it. Everything happens inside the app's **Admin** panel; the one-time setup in part A needs whoever runs your hosting.

---

### Table of contents

**A. Setup**

1. [How someone becomes an admin](#1-how-someone-becomes-an-admin)
2. [Restricting who can sign up](#2-restricting-who-can-sign-up)

**B. The Admin panel**

3. [Opening the panel and reading the overview](#3-opening-the-panel-and-reading-the-overview)
4. [Finding users](#4-finding-users)
5. [Managing a user: plans and roles](#5-managing-a-user-plans-and-roles)
6. [Removing a user](#6-removing-a-user)
7. [Looking at a user's sessions - and the privacy guard](#7-looking-at-a-users-sessions--and-the-privacy-guard)

**C. Rules & routine**

8. [What admins can and cannot see (the honest table)](#8-what-admins-can-and-cannot-see-the-honest-table)
9. [Suggested weekly routine](#9-suggested-weekly-routine)
10. [Admin FAQ](#10-admin-faq)

---

### 1. How someone becomes an admin

There are two ways - one for the **first** admin, one for everyone after:

**Way 1 - the owner's list (first admin).** The platform reads an environment variable called `ADMIN_EMAILS` - a simple list of email addresses set once on your hosting. The first time anyone on that list signs in, they automatically get the Admin panel.

If you use Vercel: Project → Settings → Environment Variables → add:

- Name: `ADMIN_EMAILS`
- Value: `you@yourcompany.com` (or several, separated by commas: `you@yourcompany.com,colleague@yourcompany.com`)

Then **redeploy** the app so the change takes effect, and sign in with that email.

**Way 2 - promotion by an existing admin.** Any admin can promote other users from inside the app - see [section 5](#5-managing-a-user-plans-and-roles). No hosting access needed.

**Good to know:**

- Admin status is *sticky*. Removing an email from the `ADMIN_EMAILS` list does **not** demote someone who already has the role - demote them in the app (section 5).
- You cannot remove your own admin role or delete your own account from the admin panel - a safety rail against locking yourself out.
- An admin is also a normal user: you can run sessions and upload your own documents.

### 2. Restricting who can sign up

Registration is closed by default: only people you invite and addresses in `ADMIN_EMAILS` can get an account. Existing users can always sign in.

**To invite someone:** open the Admin panel, enter the address under **Invite with a sign-in link**, press **Create link**, and send it privately. The link works once, lasts 24 hours and creates the account. Anyone holding it can sign in as that person.

**To let a whole company register itself,** set this environment variable and redeploy:

- Name: `ALLOWED_EMAIL_DOMAINS`
- Value: `yourcompany.com` (or several: `yourcompany.com,subsidiary.com`)

**To open registration to everyone,** set `OPEN_REGISTRATION=true`. Every account can spend AI credits up to its plan limit, so do this only with a budget in place.

---

### 3. Opening the panel and reading the overview

Sign in with your admin email and click **Admin** in the sidebar (it only appears for admins).

The top of the panel shows the platform overview - live counters:

| Stat | Meaning |
|---|---|
| **Users** | Total signed-up accounts |
| **Live now** | Sessions currently running, this very moment |
| **Sessions** | Sessions ever run (finished + live) |
| **AI answers** | Answers generated, all time |
| **Documents** | Knowledge documents uploaded by everyone (counts only - never contents) |
| **Minutes this month** | Total transcribed audio minutes in the current calendar month |
| **Answers this month** | Answers generated in the current calendar month |

These numbers are the same data the Usage ledger is built on, so they match what users see for themselves.

### 4. Finding users

Below the stats is the **Users** list:

- **Search** by email or name - results appear as you type.
- The list is paginated (20 per page) - use the arrows at the bottom to browse everyone.
- Each row shows: name, email, plan, role, session count, and the join date. On a phone the rows become cards.

Click a user's row to expand their details and actions.

### 5. Managing a user: plans, access and roles

Click the plan badge next to a user to open **Manage plan and access**:

- **Plan and end date.** Free, Pass, Pro or Pro+. Leave the date empty to keep
  the plan until you change it; with a date, the account falls back to Free
  after it. Stripe subscriptions set the plan and date by themselves.
- **Extra allowance.** Adds minutes, answers or practice answers for the
  current period, for example after a support case.
- **Block.** Signs the user out everywhere and stops all use until unblocked.

The user table also shows each account's AI cost this month and what it has
paid, so unprofitable accounts stand out.

**Role - User or Admin.** Promote a colleague to admin when they need to manage
the platform; demote to revoke.

**Safety rails:** you cannot change your own role, block yourself or delete
your own account from the panel.

### 5a. Finance, plans, payments and free plan safety

- **Finance:** revenue net of tax, refunds, AI cost (measured per request),
  estimated card fees, margin, monthly recurring revenue, cost per live hour,
  today's free plan spend against its budget, cost by plan and the users who
  cost the most.
- **Plans & prices:** edit allowances and prices. The table shows the margin if
  a plan is fully used; keep it above 50%. Press Sync Stripe afterwards.
- **Payments:** Stripe status (key, products, webhook, last event) and the
  automatic tax switch.
- **Free plan safety:** daily free budget, free live on or off, open sign-up,
  throwaway email blocking and new accounts per network.

See [PRICING.md](./PRICING.md) for the numbers behind the defaults.

### 6. Removing a user

**Delete** (in a user's expanded row, behind a confirmation dialog) permanently removes:

- their account,
- their sessions, Q&A and saved transcripts,
- their uploaded knowledge documents,
- their usage events.

It cannot be undone. If you only want someone to stop using the platform but keep history, consider whether deleting is really what you want - today there is no "disable" switch, only full deletion.

### 7. Looking at a user's sessions - and the privacy guard

From a user's row you can open their **session list** and any session in it. Each session shows:

- title, mode, language, duration, and when it ran;
- the **questions asked and answers given** during the session;
- the end-of-call **summary**;
- the **transcript - only if the user turned "Save transcript" on** for that session.

That last point is the **privacy guard**, and it's the core of NORDON's trust model: users decide, per session, whether a word-for-word transcript exists at all. When they leave it off (the default), there is nothing to see - not for you, not for anyone. You can still see what was *asked* and *answered*, because that's the product working, not the user being watched.

Users are told this openly - the same promise appears on the landing page, the Help Center, and the user guide. Please keep that promise when you talk to your teams.

### 8. What admins can and cannot see (the honest table)

| Data | Can you see it? |
|---|---|
| Platform totals (users, sessions, minutes, answers) | ✅ Yes |
| User list: names, emails, plans, roles, join dates | ✅ Yes |
| A user's sessions: questions, answers, summaries | ✅ Yes |
| A user's transcript - only when they chose to save it | ✅ Yes |
| The **contents** of a user's uploaded documents | ❌ **Never** - counts only |
| Live audio of a user's call | ❌ Never - there's no stream to tap |
| What's on a user's screen | ❌ Never - NORDON is not a monitoring tool |
| A user's password | ❌ There are no passwords. Sign-in uses one-time links |

If anyone asks you to surveil employees with NORDON: that's not what this product is, and hidden workplace monitoring is legally risky (GDPR and similar laws require informed consent). The Chrome extension, for example, is deliberately **visible** and branded - it's a helper, not a tracker.

### 9. Suggested weekly routine

A five-minute check keeps the platform healthy:

1. **Overview** - glance at *Live now* and this month's minutes/answers. A sudden jump is usually one heavy user (fine) or a runaway tab (worth a friendly message).
2. **Users** - search for anyone new who shouldn't be there (if sign-up is open). Set new hires to the right plan/role.
3. **Follow-ups** - open sessions only when there's a concrete support reason ("my summary is missing"), and tell the user you looked.
4. **Backups** - confirm your database backup ran (whoever runs your hosting set this up; see the main documentation's deployment section).

### 10. Admin FAQ

**Q: I added my email to ADMIN_EMAILS but don't see the Admin panel.**
The change needs a redeploy, and you may need to sign out and back in. Still nothing? Check for typos - the match is exact, including the domain.

**Q: How do I demote myself?**
You can't (safety rail). Another admin must do it, or remove your role via the database directly (whoever runs hosting can).

**Q: A user says their transcript is gone.**
Was "Save transcript" on for that session? If it was off, there was never a transcript - the live captions are discarded by design. The summary and Q&A are still there.

**Q: A user left the company.**
Delete their account (section 6) - it cascades away their sessions, documents and usage. Do keep any export you're legally required to retain first.

**Q: Can I read employees' documents to check for data leaks?**
No - document contents are never exposed to admins, by design. If leak prevention is a requirement, it belongs in your upload policy (tell people what's allowed in the knowledge base), not in admin surveillance.

**Q: Someone is hammering the service.**
Rate limits already protect the platform automatically (too-fast actions get a short "slow down" response). For a serious abuser, the blunt tool is deleting the account; a nicer one is a conversation.

**Q: Where do users find help without me?**
The built-in **Help Center** (sidebar → Help) has short guides in all four languages, and the footer links the user & admin guides. For anything else: **support@nordon.ai**.

---

*NORDON - use only where recording and AI assistance are permitted by the meeting's rules and local law.*

## Application Documentation

## NORDON - Full Application Documentation

**Everything the product is, how it's built, and how to keep it running - in plain English.**

This is the master reference. It's written for the owner of the product: you'll understand what every piece does without needing to be a programmer, and each section points to the exact file to touch when something needs changing.

Related documents:

| Document | Who it's for |
|---|---|
| [docs/USER_GUIDE.md](./USER_GUIDE.md) | People taking calls with NORDON |
| [docs/ADMIN_GUIDE.md](./ADMIN_GUIDE.md) | People managing the platform |
| [DEPLOY.md](../DEPLOY.md) | Putting NORDON on the internet (Vercel + Neon) |
| [README.md](../README.md) | Quick overview + developer quickstart |
| `extension/README.md` | The Chrome extension (personal + enterprise install) |

---

### Table of contents

1. [Product overview](#1-product-overview)
2. [Feature reference](#2-feature-reference)
3. [How it works (plain-English architecture)](#3-how-it-works-plain-english-architecture)
4. [The website (landing page, Help Center, FAQ, use cases)](#4-the-website-landing-page-help-center-faq-use-cases)
5. [Branding - renaming the whole app in one file](#5-branding--renaming-the-whole-app-in-one-file)
6. [Languages - the 4-language system](#6-languages--the-4-language-system)
7. [SEO - metadata, sitemap, robots, structured data](#7-seo--metadata-sitemap-robots-structured-data)
8. [llms.txt and llms-full.txt - for AI agents](#8-llmstxt-and-llms-fulltxt--for-ai-agents)
9. [The Chrome extension](#9-the-chrome-extension)
10. [Installing as an app (PWA)](#10-installing-as-an-app-pwa)
11. [Security and the privacy model](#11-security-and-the-privacy-model)
12. [Data model - what is stored where](#12-data-model--what-is-stored-where)
13. [Configuration reference (all settings and env vars)](#13-configuration-reference-all-settings-and-env-vars)
14. [Maintenance recipes - the changes you'll actually make](#14-maintenance-recipes--the-changes-youll-actually-make)
15. [Production checklist](#15-production-checklist)
16. [Known limits (honesty section)](#16-known-limits-honesty-section)

---

### 1. Product overview

NORDON is an **AI copilot for live conversations**. A person talking on Zoom, Meet, Teams or a phone call opens NORDON in a browser next to the call and gets:

- **Real-time captions** for both sides of the conversation.
- **Instant, sourced answers** to hard questions - grounded in the user's own uploaded documents, with citations.
- **Post-call summaries** with key points and action items.

Positioning, in one line: *privacy-first, no meeting bot, transparent to everyone*. NORDON joins nothing, hides nothing, and saves nothing users didn't ask it to save. That's a product decision, not just a policy - every feature was checked against it.

Primary audiences: sales teams, support agents, consultants, job candidates in interviews, people who need live captions (accessibility), and multilingual teams.

The interface ships in **English, Spanish, Portuguese and German**; answer languages also include Chinese, Serbian/Croatian and French.

### 2. Feature reference

#### Accounts & access
- **Passwordless sign-in** - one-time links by email or from an admin. No passwords exist anywhere.
- **Closed registration** - accounts come from invitations, unless `ALLOWED_EMAIL_DOMAINS` or `OPEN_REGISTRATION` allows self-registration.
- **Roles** - `user` and `admin` (see the Admin Guide). First admins come from the `ADMIN_EMAILS` list; later ones are promoted in-app.
- **Plans** - `free` / `pro` label on every account, ready for future billing gates.
- **Data ownership tools** - one-click export of everything, one-click account deletion (cascades to all data).

#### Live sessions
- **Session setup dialog** - title, mode (*sales / interview / meeting / consulting / accessibility captions*), optional goal, answer language (*auto-detect* or fixed), and the **Save transcript** switch (off by default).
- **Dual-stream capture** - microphone ("You") + optional tab audio ("Them"), captured in the browser, chunked, sent for transcription, discarded.
- **Live captions** - both streams, clearly separated, seconds behind the speaker.
- **Q&A during the call** - type questions manually or let auto-detect pick up spoken questions; answers arrive as 1-3 talking points + a detailed answer + expandable **Sources** with the exact document phrase.
- **Read-aloud text** - every answer to the other side's question starts with a short first-person text (**Say**) the user can read out loud. It is built only from the user's documents; missing personal details become bracketed placeholders. One click rewrites it (shorter, simpler, more confident, another version) through `POST /api/answers/[id]/rewrite`, and the text size is a per-device setting that also applies to the overlay.
- **Suggested questions** - the AI proposes useful next questions based on the conversation and the session goal.
- **End-of-call summary** - recap, key points, action items; stored with the session.
- **Modes** shape the answer style (talking-point-heavy for sales, neutral for captions, etc.).

#### Interview practice
- **Mock interviews** - `POST /api/practice` creates a session of kind `practice` with questions written for the role, the job ad and the user's CV. The browser can read each question aloud (speech synthesis on the device).
- **Scoring** - the user answers out loud (transcribed like a live session) or types; `POST /api/practice/[id]/feedback` returns a score from 1 to 10, strengths, improvements and a stronger answer to rehearse. Feedback is stored on the answer (`Answer.feedback`), and finishing the practice produces the usual summary.
- **Latency** - the admin panel shows p50 and p95 time to the first visible answer text over the last seven days.

#### The overlay
- **Pop-out overlay** (Document Picture-in-Picture, Chrome/Edge 116+) - a mini NORDON that floats **on top of native apps** like the Zoom desktop client. Fallback in other browsers: a small companion window.
- **Screen-share awareness** - the overlay and the "share a single window" technique keep NORDON out of shared feeds; the Help Center explains every scenario.

#### Knowledge base
- **Uploads** - PDF, DOCX, TXT, Markdown, CSV; up to 4 MB each; text extracted (unpdf / mammoth), chunked, and embedded for retrieval. Original files are never stored.
- **Retrieval** - questions search the user's documents first; answers cite document + phrase. No match → the AI says so and answers from general knowledge.
- **Privacy** - documents are per-account; admins see counts only.

#### Usage ledger
- Every transcribed minute and generated answer is recorded per user with timestamps - the basis for both the user's Usage page and admin stats. Billing-ready from day one.

#### Admin panel
- Platform stats (users, live now, sessions, answers, documents, monthly minutes/answers), user search & pagination, plan/role management, session oversight with the privacy guard (transcript visible only if the user saved it). Full detail in the Admin Guide.

#### Chrome extension (optional companion)
- Polls the signed-in user's live session and shows a **visible, branded** caption bar on any web page. Personal install (developer mode) or enterprise force-install via Chrome policy. Deliberately not hidden.

#### Installability (PWA)
- Installable as an app on Windows, macOS, Android and iOS without any store account; service worker caches the shell; dynamic manifest follows the brand.

### 3. How it works (plain-English architecture)

No servers record anything. Here is the life of a session:

1. **Capture** - the browser itself (via standard web APIs) captures the mic and, if enabled, the call's tab audio. NORDON's code never touches a server until you start a session.
2. **Transcription** - audio is cut into small chunks and sent to the transcription service (`src/lib/ai/stt.ts`); text comes back and is never stored as audio. Chunks are discarded as they're processed unless a transcript was requested.
3. **Answers** - when a question arrives (typed or auto-detected), the retrieval layer (`src/lib/ai/retrieval.ts`) finds the most relevant chunks in the user's documents, and the LLM layer (`src/lib/ai/llm.ts`) writes the talking points, the detailed answer and the citations.
4. **Summary** - ending the session asks the LLM for a structured summary, saved with the session.
5. **Storage** - only text lands in the database: captions (transient), Q&A, summaries, knowledge chunks, usage counters. No audio files exist anywhere.

**The provider seams.** All AI calls live in three small files (`stt.ts`, `llm.ts`, `questions.ts`). Swapping a provider means editing those files only - the rest of the app doesn't know or care which AI is behind them.

**Live audio.** Audio is captured as 16 kHz PCM in an AudioWorklet. Chunks end at a pause in speech (`src/hooks/useAudioCapture.ts`), and chunks with no speech are not sent. Each chunk returns its text first and then the same text split by speaker. Short samples of voices already heard go with every chunk of the other side, so a speaker keeps the same number for the whole call (`src/lib/ai/voices.ts`). Microphone lines that repeat the other side through the speakers are hidden (`src/lib/echo.ts`). Answers stream their talking points as newline-delimited JSON. Overlay windows read a local BroadcastChannel feed, so they work with transcript saving off.

**Rate limiting.** Limits are counted in Postgres (`src/lib/rate-limit.ts`), so they hold across serverless instances: sign-in requests 10 per 15 minutes per IP and 3 per address, transcribe 90/min, answers 20/min, summaries 6/min, uploads 12/min, polls 90/min, writes 60/min.

**Auth.** A random session token in an http-only cookie proves who you are. The database stores only its hash, so sign-out takes effect at once. API routes are wrapped with `withUser` / `withAdmin` guards (`src/lib/auth.ts`). One-time sign-in links are handled in `src/lib/login-links.ts`.

### 4. The website (landing page, Help Center, FAQ, use cases)

The public website is the app's landing page (`src/components/app/Landing.tsx`) - one page, modern dark/light design with:

- **Hero** - what it is, one-click start, language & theme switches.
- **How it works** - the 3-step story (add knowledge → start session → get help live).
- **Features** - eight feature cards (captions, sourced answers, documents, summaries, privacy, usage ledger, languages, installs anywhere).
- **Use cases** - six cards: sales calls, customer support, interviews, team meetings, multilingual calls, accessibility.
- **Private during calls** - the overlay + screen-share section, linking into Help Center articles.
- **Privacy section** - the four honest privacy promises.
- **FAQ** - the ten most-asked questions, as an accordion (English master in `src/content/faq.ts`, translated in the same file).
- **Footer** - product links, guides, and the llms.txt links.

#### The Help Center
Built into the same page at `#help` / `#help/<article>` (shareable URLs without extra routes):

- **Categories** - Getting started, User guide, Admin guide, Troubleshooting, FAQ.
- **Search** - instant, across titles and full text.
- **11 articles** - from "What is NORDON?" through the overlay and screen-share guides to the admin panel tour - each in **all four languages**.
- **Content files** - `src/content/help/{en,es,pt,de}.ts`, one article per key. TypeScript enforces that every language file has every article, so translations can't silently drift.

#### Editing website copy
- Landing/Help UI labels live in the language dictionaries (`src/lib/i18n/*.ts` - see §6).
- Help article bodies live in `src/content/help/*.ts`.
- FAQ entries live in `src/content/faq.ts` (all four languages side-by-side).
- After changing help/FAQ/branding, regenerate the AI-agent files (§8) - one command.

### 5. Branding - renaming the whole app in one file

`src/config/brand.ts` is the single source of truth:

- `name` - the app name everywhere (title, landing, sidebar, emails, PWA install prompt). Override without touching code via the `NEXT_PUBLIC_APP_NAME` env var.
- `tagline`, `description` - marketing lines, also feed SEO metadata.
- `company`, `supportEmail`, `disclaimer` - footer and contact points.

Change it once and the landing page, page titles, PWA manifest, favicon letter, metadata, sitemap, JSON-LD and llms.txt all follow. The favicon is the first letter of the brand name on a gradient tile.

### 6. Languages - the 4-language system

- **Dictionaries** - `src/lib/i18n/{en,es,pt,de}.ts`, flat `"key": "text"` maps (~485 keys each). TypeScript checks that all four have exactly the same keys.
- **Usage** - components call `const t = useT()` and `t("landing.hero.a")`; variables interpolate: `t("login.welcome", { name: BRAND.name })`.
- **Persistence** - the chosen language is remembered per browser (zustand persist, hydration-safe).
- **Answer language** is separate from UI language - each session picks auto-detect or a fixed language.

**To add a UI language:** copy `en.ts` → `xx.ts`, translate the values, register it in `src/lib/i18n/index.ts`, and add it to the two language pickers in `Landing.tsx` / `SettingsView.tsx`. The type system immediately shows any missing keys.

### 7. SEO - metadata, sitemap, robots, structured data

All SEO flows from the brand config and one URL setting, so rebranding or moving domains breaks nothing:

- **`src/config/site.ts`** - the canonical site URL. Set `NEXT_PUBLIC_SITE_URL` in production (e.g. `https://helper.yourcompany.com`); a sensible default is baked in.
- **`src/app/layout.tsx`** - page title/description templates, keywords, Open Graph + Twitter cards, canonical URL, PWA manifest link, icons.
- **`src/app/sitemap.ts`** - served at `/sitemap.xml`, lists the app page and the AI-agent files with change frequency.
- **`src/app/robots.ts`** - served at `/robots.txt`: everything crawlable except `/api/`, plus the sitemap reference.
- **`src/app/page.tsx`** - server-rendered **JSON-LD structured data**:
  - `SoftwareApplication` - name, description, feature list, languages, free offer;
  - `FAQPage` - the full FAQ, enabling rich results in search engines.

Because the JSON-LD renders server-side, crawlers see it without running any JavaScript.

### 8. llms.txt and llms-full.txt - for AI agents

The [llms.txt convention](https://llmstxt.org/) gives AI assistants (ChatGPT, Gemini and others) a clean, markdown description of your product instead of making them guess from HTML:

- **`/llms.txt`** - the short overview: what NORDON is, key features, use cases, links to guides and to the full file.
- **`/llms-full.txt`** - everything flattened: overview, complete FAQ, all 11 Help Center articles, plus the full user, admin and deployment guides.

**Both files are generated** from the live content (brand config, FAQ, help articles, the docs/ guides) by one command:

```bash
node scripts/gen-llms.mjs
```

Run it whenever you change branding, help content, FAQ or the guides, then redeploy. The files land in `public/` and are served at the site root. The landing footer links both under *Resources → For AI agents*.

### 9. The Chrome extension

Source: `extension/`. The build packs it into `/downloads/nordon-extension.zip` with the deployment URL filled in, and users download it from Settings.

- **What it does** - the background worker polls the signed-in user's live session (`/api/sessions/live`) and a content script renders a draggable, clearly branded caption bar on web pages.
- **Personal install** - Chrome → `chrome://extensions` → Developer mode → Load unpacked. The popup asks for the NORDON URL once, then connects.
- **Enterprise install** - force-install for the whole org via Chrome Admin console or Group Policy (the extension README includes the exact policy JSON).
- **Honesty by design** - the bar is visible and branded; there is no hidden mode. Employees see exactly what it is. This keeps the deployment compliant with employee-monitoring laws and company policy.

### 10. Installing as an app (PWA)

- **`src/app/manifest.ts`** - the install manifest, generated from BRAND (name, colors, icons) so a rebrand updates the installed app too.
- **`public/sw.js`** - the service worker: cache-first for static assets, network-first for pages, never caches `/api`. Users get an instant app shell; live features always use the network.
- **`public/icons/`** - 192/512/maskable/apple icons, generated by `scripts/gen-icons.mjs` (uses sharp; rerun when you want new icon art).
- **In-app guidance** - the Settings → Install section detects the device and shows exact steps (Windows/Mac via browser install button, Android via Add to Home screen, iPhone via Safari share sheet).

### 11. Security and the privacy model

| Layer | What's in place |
|---|---|
| Authentication | One-time links, hashed database sessions, `__Host-` http-only cookie; no passwords exist; registration closed by default |
| Authorization | `withUser` on every user route; `withAdmin` on admin routes; role checked server-side, not just hidden in UI |
| Rate limiting | Token buckets on all public routes (login 10/min/IP, answers 20/min, etc.) |
| Input validation | Zod schemas on every API route (types, lengths, enum values) |
| Admin guardrails | No self-role-change, no self-delete; admin actions limited to documented fields |
| Privacy guard | Transcripts exist only when the user opted in per session; documents never exposed to admins |
| Data minimization | No audio ever stored; original files not kept; captions discarded when transcript saving is off |
| User rights | One-click export (GDPR-style) and one-click account deletion |

The rule that governs feature design: **NORDON is a helper the user runs, not a tool that watches the user.** Anything that would violate that (hidden overlays, covert extension modes, transcript access without opt-in) has been deliberately left out.

### 12. Data model - what is stored where

One Postgres database (Neon) with these models (`prisma/schema.prisma`):

- **User** - email, name, role (`user`/`admin`), plan (`free`/`pro`), timestamps.
- **Session** - title, mode, language, goal, status, start/end, optional transcript, summary fields, relation to user.
- **Question/Answer** - the Q&A pairs of a session, including sources/citations.
- **Document** - name, size, chunk count (per user); the extracted text chunks (with embeddings) are what retrieval searches.
- **UsageEvent** - per-user typed ledger entries (minutes, answers) with timestamps.

What is deliberately **absent**: audio files, original uploaded files, password hashes, screen captures.

### 13. Configuration reference (all settings and env vars)

| Variable | What it does | Default |
|---|---|---|
| `DATABASE_URL` | Database connection string | none |
| `AI_MODEL`, `AI_STT_MODEL` | AI Gateway model IDs | none |
| `RESEND_API_KEY`, `EMAIL_FROM` | Sign-in email | off |
| `CRON_SECRET` | Protects the daily cleanup job | none |
| `ADMIN_EMAILS` | Comma-separated emails that get admin on sign-in | none |
| `ALLOWED_EMAIL_DOMAINS` | Domains that may register themselves | none |
| `OPEN_REGISTRATION` | `true` lets anyone register | off |
| `NEXT_PUBLIC_APP_NAME` | Override the brand name without editing code | `NORDON` |
| `NEXT_PUBLIC_SITE_URL` | Canonical public URL (SEO, sitemap, llms.txt) | the Vercel production URL |

Non-env config: branding in `src/config/brand.ts`; rate-limit presets in `src/lib/rate-limit.ts`; AI providers in `src/lib/ai/`.

### 14. Maintenance recipes - the changes you'll actually make

**Rename the app** → edit `src/config/brand.ts` (or set `NEXT_PUBLIC_APP_NAME`) → `node scripts/gen-llms.mjs` → deploy.

**Edit a Help article** → edit the article in **all four** files `src/content/help/{en,es,pt,de}.ts` (types will nag you if you add a key to one file only) → `node scripts/gen-llms.mjs` → deploy.

**Add/edit an FAQ** → `src/content/faq.ts` has all four languages side-by-side; keep the arrays the same length (JSON-LD uses the English list) → regenerate llms files → deploy.

**Add a UI language** → see §6.

**Change SEO basics** → `src/config/site.ts` (URL), `src/config/brand.ts` (title/description). `sitemap.ts`/`robots.ts`/JSON-LD read from those; no other edits needed.

**Change rate limits** → `src/lib/rate-limit.ts`, one line per preset.

**New icons** → drop art in `scripts/gen-icons.mjs` → run it.

**Regenerate llms.txt files** → `node scripts/gen-llms.mjs` (run after any content/brand change; it also refreshes the "last updated" dates).

### 15. Production checklist

Before calling it production, confirm each line (details in DEPLOY.md):

- [ ] Postgres (Neon) connected; migrations applied by the production build
- [ ] `AI_MODEL`, `AI_STT_MODEL` and `CRON_SECRET` set
- [ ] Resend domain verified, `EMAIL_FROM` set
- [ ] `ADMIN_EMAILS` set with at least one admin
- [ ] `ALLOWED_EMAIL_DOMAINS` set if this is a company deployment
- [ ] `NEXT_PUBLIC_SITE_URL` set to the real domain (SEO + llms links)
- [ ] Custom domain + HTTPS active on Vercel
- [ ] Error monitoring on (e.g. Sentry - one env var in Vercel)
- [ ] Database backups scheduled (Neon automatic PITR is fine)
- [ ] `/sitemap.xml`, `/robots.txt`, `/llms.txt`, `/llms-full.txt` all return 200 on the live domain
- [ ] A test sign-in, test session, and test admin action on the live site
- [ ] Privacy note / terms published for your users (template text exists in the footer + Help Center)

### 16. Known limits (honesty section)

- **Browser captions on native-app calls** rely on the mic hearing the room's speakers; for best "them" transcription, calls should run in the browser with tab audio, or use headphones.
- **Always-on-top overlay** is Chrome/Edge 116+ only; other browsers get the fallback side window.
- **iOS install** requires Safari (an Apple policy - only Safari can install web apps).
- **Screen sharing**: sharing the *entire screen* always captures everything visible, including NORDON. The single-window technique is the supported answer; it's documented, not hidden.
- **The extension is visible by design** - there is no undetectable mode, on purpose.
- **Plans (free/pro)** are currently labels; billing integration is the one feature stub left for a future sprint.

---

*NORDON - use only where recording and AI assistance are permitted by the meeting's rules and local law.*

## Deployment Guide

## Production setup

NORDON runs on Vercel with Neon Postgres (through the Vercel Marketplace),
Vercel AI Gateway for speech-to-text and answers, and Resend for sign-in email.
Pushing to `main` deploys to production. Migrations in `prisma/migrations` run
on production builds only.

### Environment variables

| Variable | Purpose | Where it comes from |
|---|---|---|
| `DATABASE_URL`, `DATABASE_URL_UNPOOLED` | Postgres. Production uses `oshelper-db`; previews and local development use `oshelper-dev` | Neon integration |
| `AI_MODEL` | Text model ID from AI Gateway | Set in Vercel |
| `AI_STT_MODEL` | Transcription model ID from AI Gateway | Set in Vercel |
| `AI_EMBED_MODEL` | Embedding model ID for document search, optional | Set in Vercel |
| `NEXT_PUBLIC_DESKTOP_URL` | Windows app download shown in Settings | Vercel Blob URL |
| `ADMIN_EMAILS` | Comma-separated admins, promoted on sign-in | Set in Vercel |
| `CRON_SECRET` | Protects the daily cleanup job | Set in Vercel |
| `RESEND_API_KEY` | Sends sign-in email | Resend integration |
| `EMAIL_FROM` | Sender, such as `NORDON <hello@nordon.ai>` | Set in Vercel |
| `EMAIL_REPLY_TO` | Where replies go. Defaults to the support address in `src/config/brand.ts` | Optional |
| `NEXT_PUBLIC_SITE_URL` | Public URL, used in sign-in links and the extension | Set when a domain is connected |
| `ALLOWED_EMAIL_DOMAINS` | Domains that may register themselves | Optional |
| `OPEN_REGISTRATION` | `true` lets anyone register | Optional, off by default |
| `NEXT_PUBLIC_APP_NAME` | Overrides the product name | Optional |
| `STRIPE_SECRET_KEY` | Payments (Sodasoft LLC account). Use a restricted or secret key | Stripe dashboard, Developers, API keys |

AI Gateway authenticates with Vercel OIDC, so no AI key is stored. Model IDs
come from `https://ai-gateway.vercel.sh/v1/models`.

Registration is closed by default. Existing users can always sign in, admins
can invite anyone, and only `ADMIN_EMAILS`, `ALLOWED_EMAIL_DOMAINS` and
`OPEN_REGISTRATION` allow self-registration.

### Payments (Stripe)

Only the secret key is set by hand. Everything else is created from the app.

1. In the Stripe dashboard of Sodasoft LLC, copy the secret key. Start with
   the test mode key (`sk_test_...`) and switch to the live key once a test
   purchase works.
2. Add it in Vercel: Project, Settings, Environment Variables,
   `STRIPE_SECRET_KEY` for Production (and Preview with a test key), then
   redeploy.
3. Open the app as an admin: Admin panel, Payments, **Set up Stripe**. This
   creates the products, prices (with lookup keys `osh_*`), the customer
   portal and the webhook to `/api/billing/webhook`. The webhook signing
   secret is stored encrypted in the database.
4. After changing a price under Plans & prices, press **Sync Stripe**. A new
   price is created and the old one archived; existing subscribers keep their
   price.
5. Turn on Automatic tax only after the business address and tax registrations
   are set in Stripe Tax.

When switching from the test key to the live key, run Set up Stripe again: it
creates the live products and webhook.

Plans, allowances and prices are documented in [docs/PRICING.md](./docs/PRICING.md).

### Signing in before email is connected

The first admin creates a link from a machine linked to the Vercel project:

```bash
vercel env pull .env.production.local --environment production
npm run auth:link -- you@company.com --url https://nordon.ai
```

The address must be in `ADMIN_EMAILS` to get the admin role. After that, invite
people from **Admin > Invite with a sign-in link**.

### Connecting a domain

Production runs on **nordon.ai**, with DNS at Cloudflare (records for Vercel
set to DNS only).

1. Add the domain to the Vercel project: **Settings > Domains**. Make the apex
   `nordon.ai` the main domain and let `www` redirect to it.
2. In Resend, add `nordon.ai` in region us-east-1 (next to the Vercel
   functions) and let Resend add its DNS records in Cloudflare. Resend sends
   from the `send` subdomain, so mail routing for the root (support@) stays
   free.
3. Create a Resend API key with **Sending access** for that domain only.
4. Set for Production:

   ```
   RESEND_API_KEY=re_...
   EMAIL_FROM=NORDON <hello@nordon.ai>
   NEXT_PUBLIC_SITE_URL=https://nordon.ai
   ```

5. Redeploy. The sign-in form starts sending email by itself, and the extension
   download is rebuilt for the new address.
6. Reinstall the extension, because it is built for one server address.

#### Emails

All emails share one layout in `src/lib/email/`. The copy exists in English,
Spanish, Portuguese and German, and each user gets the language they picked in
the app.

| Email | Sent when |
| --- | --- |
| Sign-in link | Someone asks to sign in |
| Welcome | A new account is created |
| Plan active | A subscription checkout completes |
| Pass active | An Interview Pass is paid |
| Payment failed | A renewal payment fails |
| Plan ended | A subscription ends |

Billing emails use the Stripe event id as the Resend idempotency key, so a
repeated webhook never sends twice. Preview every email with
`npx tsx scripts/email-preview.ts`, which writes `.email-preview/index.html`.

### Limits to keep in mind

- **Vercel body size:** requests stop at 4.5 MB, so uploads are capped at 4 MB.
- **Databases:** production and previews use separate Neon databases, and each
  build migrates its own. All previews share `oshelper-dev`.
- **Spending:** plan quotas cap each account, and the project has an AI Gateway
  budget of 50 USD a month. Change it with `vercel ai-gateway budgets set`.
- **Transcription:** AI Gateway speech-to-text is in beta. If a model is
  withdrawn, change `AI_STT_MODEL`.
- **Backups:** Neon provides point-in-time restore. Check the retention of the
  plan in use.

### Maintenance

| Task | How |
|---|---|
| Promote or demote an admin | **Admin > Users** |
| Move a user to Pro | **Admin > Users** (billing is not connected yet) |
| Change allowances | `src/lib/entitlements.ts` |
| Change AI model | `AI_MODEL` or `AI_STT_MODEL`, then redeploy |
| Change the schema | `npx prisma migrate dev`, then commit the migration |
| Publish a desktop build | Download the CI artifact, upload it with `vercel blob put`, update `NEXT_PUBLIC_DESKTOP_URL` |
| Lost admin access | `npm run auth:link` from a linked machine |

---
Generated 2026-11-07 from source content by scripts/gen-llms.mjs. Support: support@nordon.ai