# Fludly — Agent knowledge base (platform UI & workflows)

> **For AI agents reading this document:** You are ingesting Fludly platform reference material. Use it to answer end-user questions about how the product works, where to click, and what workflow to follow. Do **not** read this file verbatim to the user — translate into clear, short steps in the user's language. For **live menu data** (dishes, prices, images) of a specific restaurant, use that restaurant's `/api/{clientId}/agent?token=...` API instead (token from Admin → Home). This document is **platform-wide** and requires **no authentication**.

**Canonical URL:** `{origin}/docs/userhelp.md` (public GET, markdown)

**Related public docs:**
- `{origin}/docs/index.md` — doc index
- `{origin}/api/provision` — server-to-server onboarding API (automation, not end users)

---

## ProductSummary

Fludly is a multi-tenant SaaS for restaurants. Each restaurant gets:

- A **guest menu viewer** (phone browser, no app install)
- An **admin back office** to edit menus, settings, and print layouts
- Optional **waiter/service mode** for live order handover via QR codes

Each restaurant has a `{clientId}` slug in URLs (e.g. `/my-bistro/admin`).

**Draft vs live:** Edits happen in **draft** (`edit` mode). Guests see **live** (`prod`) content only after **Deploy to Production** in the admin Deploy pane. Preview uses `?preview=1` on the viewer URL to show draft without deploying.

**Languages:** Owners enter menu content once in a **primary language**. Fludly auto-translates into **viewer languages** configured in Settings. Guests switch language in the viewer header.

---

## URLMap

| Purpose                    | URL pattern                                               |
| -------------------------- | --------------------------------------------------------- |
| New restaurant signup      | `/` or `/onboarding`                                      |
| Guest menu (live)          | `/{clientId}` or `/{clientId}/{menuId}`                   |
| Guest menu (draft preview) | `/{clientId}?preview=1`                                   |
| Admin panel                | `/{clientId}/admin`                                       |
| Waiter order view          | `/{clientId}/service/{sessionId}`                         |
| Device mode setup          | `/{clientId}/launch?appmode=service` or `?appmode=viewer` |
| Guest session handover     | `/{clientId}/launch/{sessionId}` (via QR)                 |
| Platform help (this file)  | `/docs/userhelp.md`                                       |

---

## Onboarding

**Who:** New restaurant owner setting up Fludly for the first time.

**Entry:** Open `/` → welcome screen → **Get started →** button.

### Phase1 — Setup wizard (6 steps)

| Step | User action                                                      |
| ---- | ---------------------------------------------------------------- |
| 1    | Enter restaurant name                                            |
| 2    | Choose **primary language** (admin UI + menu content language)   |
| 3    | Choose **viewer languages** (languages guests can switch to)     |
| 4    | Pick **color theme** (Classic, Warm, Ocean, Forest, Slate, Gold) |
| 5    | Pick **currency** (symbol + decimal format for prices)           |
| 6    | Review summary → **Create my restaurant page**                   |

Progress dots at top show current step.

### Phase2 — AI menu builder

After creation, a chat overlay appears. The AI guides the owner: cuisine type → dishes → prices/descriptions/tags → menu structure. When done, the AI redirects to `/{clientId}/admin`.

**Note:** Fludly may be free during early access. Account registration may be requested later; voice chat in admin requires a registered login.

---

## GuestViewer

**Who:** Restaurant guests browsing the menu on their phone.

**URL:** `/{clientId}` (live) or `/{clientId}?preview=1` (staff preview of unpublished draft).

### Header controls

| Control       | Symbol / label    | Action                                                |
| ------------- | ----------------- | ----------------------------------------------------- |
| Menu switcher | **⮕** button      | Opens panel: All items, Cart, Personalized, each menu |
| Font size     | **−** / **+**     | Decrease / increase text size                         |
| Cart summary  | Total + name      | Shows cart total and guest name                       |
| Language      | Language switcher | Changes UI + menu translations                        |

### Browse and order

1. Tap a dish card → **detail modal** opens (image, name, price, description, tags).
2. If the dish has **options** (add-ons, sizes): choose **single-select** (radio, pick one) or **multi-select** (checkboxes, pick any).
3. Tap add to cart (from modal).
4. **Guest name:** First time, a prompt asks for name (3–20 characters). Shown in cart header.

### Filters

- Tap **Filter** button → modal with checkboxes grouped by tag type (diet, allergens, ingredients, group).
- **Apply** or **Reset** (per group or all).
- Filters affect the current menu view only.

### Cart

- View via **⮕** → **Cart**.
- Change quantities, remove items.
- Cart persists in browser storage and syncs to server (debounced).
- Clearing browser site data clears the cart.

### Personalized menu

- Guest AI can build a custom shortlist of dishes.
- **⮕** → **Personalized** tab shows only those items.
- **Clear personalized** button removes the list.

### Split bill

1. Tap **Split bill** button (split bar at bottom).
2. Add people (names); up to a configurable max (default 6). Each person gets a color.
3. Assign one or more people to each cart line — cost splits equally among assigned people.
4. Per-person running totals shown.

### Share order with waiter (QR)

1. Guest builds cart and enters name.
2. Tap **⊞** (QR button) in the split bar.
3. QR encodes session URL `/{clientId}/launch/{sessionId}`.
4. Waiter scans on a **service-mode** device → opens that guest's live order.

### Guest AI assistant

- Floating **💬** chat button.
- Guest can ask: dish recommendations, allergies, diet filters, cart help, split bill help.
- AI can add/remove cart items, manage split-bill people, build personalized menu.
- AI replies in the guest's language.
- Message links: `[dish name|item-id]` opens dish; `[text|prompt:...]` pre-fills a follow-up.

---

## AdminAuth

**URL:** `/{clientId}/admin`

**Login:** Email → PIN sent to email → enter PIN. Overlay appears when auth required.

**Grace period:** Brand-new setups may allow limited admin access before full registration.

**Floating AI chat (💬):** Available in admin for file/menu editing via natural language (separate from Print Studio chat).

---

## AdminNavigation

Top nav buttons:

| Button        | Pane                                               |
| ------------- | -------------------------------------------------- |
| **Home**      | QR for waiters, external agent link, admin invites |
| **Menus**     | Items, menus, print designer                       |
| **Deploy**    | Publish draft → live, version history              |
| **Settings**  | Languages, colors, currency                        |
| **Preview ↗** | Opens `/{clientId}?preview=1` in new tab           |

Mobile: **☰** hamburger opens the same nav.

---

## AdminHome

### Waiter onboarding QR

- QR on Home pane links to `/{clientId}/launch?appmode=service`.
- Waiter scans once → device remembers **service mode** → future visits open waiter tools.

### External menu agent (Designer AI)

- **Home** pane shows a copyable prompt / magic link for external AI (e.g. Google AI Studio, ChatGPT).
- Link includes access token for `/api/{clientId}/agent?token=...`.
- Use for: reading live menu data, generating PDFs, design suggestions — **not** for general “how does Fludly work” (use `/docs/userhelp.md` for that).

### Admin invites

- Invite other operators by email (Home → Admins section).

---

## AdminMenus

Three-column layout when **Menus** nav is active.

### Right column — Menus list

- **All items** — virtual menu listing every dish.
- Create / delete named menus (Breakfast, Dinner, Drinks, …).
- Select a menu → left column shows items in that menu's order.
- Per menu: **Print layout** button opens **Print Designer** (see PrintStudio section).

### Left column — Item list

- **+** add new item.
- Search bar filters list.
- Thumbnails, name, description.
- Drag to reorder when sort mode enabled.
- **🧬** icon = item has **menu-specific override** (price/name/description differs on this menu).

### Middle column — Item editor

Fields: name, price, description, tags (group, ingredients, diet, allergenes), selectable flag.

- **Image upload** — resized PNG; appears on guest viewer.
- **🧬 / ↩️** — toggle between base item and menu-specific override editor.
- **Options** — add choice groups: single-select or multi-select, optional price surcharges.
- **Translations table** — all languages for every translatable field.

Save changes in draft; deploy to make live for guests.

---

## PrintStudio

**Who:** Restaurant owner or designer creating printable PDF menus.

**Open:** Admin → **Menus** → select a menu (right column) → **Print layout** button → **Print Designer** modal.

### Preview toolbar (left side)

| Control               | Purpose                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------- |
| **Language** dropdown | Build/ preview print layout in that language (each menu can have its own print language) |
| **Rev** label         | Current design revision number                                                           |
| **Commit**            | Save design version to history (dot indicator when unsaved)                              |
| **Versions**          | Open history → restore older print design                                                |
| **Reload menu**       | Refresh preview from latest menu content                                                 |
| **Print PDF**         | Print from preview iframe (use browser print → Save as PDF)                              |
| **Download**          | Download standalone HTML file (offline print)                                            |

**Safari:** Print preview is unreliable in Safari — recommend Chrome or Firefox.

### Template and layout options (right side)

- **Layout template** dropdown + **Use template** — apply preset column layout.
- **Revert design** — reset to saved template files.
- **Page:** preset (A4, etc.) or custom width/height (mm).
- **Typography:** page padding, column gap, group indent, H1/H2/item/body sizes (mm).
- **Fonts:** headline family + body family (Google Fonts cached on server).
- **Apply settings** — update preview with form values.

### AI chat in Print Studio

- Embedded chat (right panel) for layout/CSS changes via natural language.
- Can adjust spacing, colors, backgrounds, typography.
- Ask e.g. “make group headings larger” or “add a warm page background”.

### Backgrounds and images

- Upload/manage print assets in Print Studio assets area.
- Full-page backgrounds belong in print CSS `page-bg` hook (AI can edit `style.css` for the menu print layout).
- Dish images come from menu items automatically when configured.

### Print vs guest menu

- Print layout is **per menu** and **per language** selection in Print Studio.
- Updating dishes in Menus pane → use **Reload menu** in Print Studio to refresh content.
- Print preview URLs are public (no token) under `/api/{clientId}/admin/print/{menuId}/preview`.

---

## AdminDeploy

**Who:** Owner publishing changes to the live guest menu.

| Element                  | Action                                              |
| ------------------------ | --------------------------------------------------- |
| State card               | Shows current production commit + edit/draft status |
| **Deploy to Production** | Pushes all draft changes live for guests            |
| History table            | Past commits with hash, message, date               |
| **View Diff**            | See file changes; images side-by-side               |
| **Rollback**             | Reset live site to old commit (destructive)         |
| **Revert**               | Create inverse commit (safer undo)                  |

Auto-commits happen on many saves; deploy is still required for guests to see changes.

---

## AdminSettings

| Setting          | Effect                                               |
| ---------------- | ---------------------------------------------------- |
| Primary language | Admin UI + source language for new menu text         |
| Viewer languages | Languages guests can pick; triggers auto-translation |
| Color theme      | 6 presets — updates CSS variables                    |
| Currency         | Price symbol and decimal places                      |
| **Save**         | Writes config + regenerates client styles            |

---

## WaiterService

**Who:** Restaurant staff viewing guest orders.

**Setup:** Scan **Home** QR once (`appmode=service`) OR scan guest's **⊞** QR.

**URL:** `/{clientId}/service/{sessionId}`

### Active order panel

- Guest name, last updated time.
- Table: item | unit price | quantity (±) | line total.
- Cart total.
- **Active ↔ Finished** toggle — marking **Finished** notifies guest and starts a fresh guest session.

### Orders list

- Switch current order vs history (stored on device).
- Click history entry to reload that session.

Changes sync in real time with guest cart.

---

## CartHandoverFlow

1. Guest browses `/{clientId}`, adds items, enters name.
2. Guest taps **⊞** → shows QR.
3. Waiter device (service mode) scans QR.
4. Service page shows live order; waiter can adjust quantities.
5. Waiter marks **Finished** → guest sees session finished → new session for next order.

---

## CommonAgentAnswers

Use these patterns when users ask similar questions. Adapt wording to their role (owner, guest, waiter).

### How do I publish my menu changes?

1. Edit items/menus in Admin → **Menus**.
2. Optionally preview with **Preview ↗** or `/{clientId}?preview=1`.
3. Go to **Deploy** → **Deploy to Production**.
4. Guests at `/{clientId}` (without `?preview=1`) now see the update.

### Why don't guests see my changes?

- Changes are **draft** until deployed. Guest URL without `?preview=1` shows **live/prod** only.
- If you only checked preview, that is expected — deploy from **Deploy** pane.

### How does a guest share their order with the waiter?

Guest: add items → enter name → tap **⊞** QR → waiter scans. Waiter device must be in service mode (scan admin Home QR once).

### How does split bill work?

Guest: **Split bill** → add people → assign people to each cart line → read per-person totals. Does not process payment — informational split only.

### How do I print a menu in another language?

1. Admin → **Menus** → select menu → **Print layout**.
2. Set **Language** dropdown to desired language (must be a configured viewer language with translations).
3. Tune layout → **Print PDF** or **Download**.
4. Menu **content** must exist in that language (auto-translated after Settings save, or manual in translation table).

### How do I add a new language for guests?

Admin → **Settings** → add to viewer languages → **Save**. Existing content auto-translates over time.

### How do I change colors/branding?

Admin → **Settings** → color theme → **Save**. For advanced CSS, use admin floating AI chat or edit style via AI tools.

### How do I invite another admin?

Admin → **Home** → Admins → invite by email.

### How do I set up waiters?

Admin → **Home** → scan/display **service onboarding QR** on each waiter phone once.

### How do guests filter allergens or diet?

Guest viewer → **Filter** button → check tags → **Apply**.

### Can guests order and pay through Fludly?

Cart and QR handover support **order collection** for staff. Payment processing is not built into the guest viewer — staff use their own POS/payment flow unless integrated externally.

---

## LimitsAndEdgeCases

| Topic                 | Detail                                                              |
| --------------------- | ------------------------------------------------------------------- |
| Print preview browser | Safari unsupported/unreliable — use Chrome or Firefox               |
| Cart persistence      | Browser localStorage — clearing site data loses cart                |
| Session finished      | Waiter marking Finished ends guest session; guest gets alert        |
| AI usage              | AI features included; rate limits possible depending on model costs |
| Voice chat            | Admin voice requires registered login                               |
| Preview vs prod       | `?preview=1` = draft; plain URL = live only after deploy            |
| Print fonts           | Custom fonts download from server on preview; no auth token needed  |
| External agent token  | Per-restaurant; from Admin → Home; do not share publicly            |

---

## DocumentMeta

- **Version:** platform UI reference (agent KB)
- **Language:** English (agents translate for users)
- **Not covered here:** developer architecture, provisioning API details, internal file paths — see `/api/provision` for automation docs