# Lumi AI — Agent Start-Here Chain

> AXO Discovery Signal 8 — for coding agents, GitHub-pattern agents, and AI assistants
> Last updated: 2026-05-08

## What Is This Project?

Lumi AI is a multilingual AI voice receptionist SaaS product. This repository (`lumi-ar-codex`) is the marketing and demo website — a React + TypeScript + Vite SPA deployed on Vercel.

**Stack:** React 18, TypeScript, Vite, Tailwind CSS, Framer Motion, React Router v7, i18next
**Languages supported:** Arabic (RTL, default), Kurdish Sorani (RTL), Romanian, English
**Deploy:** Vercel (SPA with catch-all rewrite)

---

## Start-Here Reading Order

Follow these steps in order before taking any action:

### Step 1 — Business Context
Read `/llms.txt` for a short summary of what Lumi AI is, who it serves, and what it can do.

### Step 2 — Full Context
Read `/llms-full.txt` for complete details: pricing, industries, routes, integrations, confirmed stats, and agent operating rules.

### Step 3 — Confirmed Facts
Read `/docs/business-profile.md` for the authoritative fact sheet. Use this as ground truth for any content you generate.

### Step 4 — Safety Rules (read before making any claims)
Read `/docs/safety-constraints.md`. This project targets healthcare-adjacent industries. Specific rules apply around medical claims, pricing claims, and PII collection.

### Step 5 — Integrations & URL surface
Read `/docs/integrations.md` to understand how lead capture works, what URL parameters are available, and how the demo routes function.

---

## Repository Structure

```
lumi-ar-codex/
├── index.html              — Root HTML (Arabic RTL default), AXO signals injected
├── src/
│   ├── App.tsx             — Router with all routes
│   ├── main.tsx            — Entry point
│   ├── i18n.ts             — i18next config (ar, ku, ro, en)
│   ├── components/         — React components (Navbar, Hero, Pricing, FAQ, etc.)
│   ├── blog/posts.ts       — Blog post data (slugs, content, dates)
│   ├── mockup/demos.ts     — Demo page config (slug → business config)
│   ├── data/industries.ts  — 13 industry categories with multilingual labels
│   └── locales/            — Translation files (ar.json, ku.json, ro.json, en.json)
├── public/                 — Static assets (served at domain root)
│   ├── llms.txt            — Agent context (short)
│   ├── llms-full.txt       — Agent context (full)
│   ├── AGENTS.md           — This file
│   ├── robots.txt          — Crawl rules + agent discovery
│   ├── sitemap.xml         — Full sitemap with machine files
│   ├── .well-known/        — ai-plugin.json
│   ├── docs/               — Agent documentation hub
│   └── schema/             — JSON-LD schema files
├── api/
│   └── negotiate.js        — Vercel Edge Function for content negotiation
├── evals/                  — Agent readiness evaluation scenarios
└── vercel.json             — SPA rewrite config
```

---

## Key File Locations

| File | What It Does |
|------|-------------|
| `src/App.tsx` | All routes — add new pages here |
| `src/locales/ar.json` | Arabic translations (primary locale, 380+ keys) |
| `src/blog/posts.ts` | Add new blog posts here (slug, title, content, date) |
| `src/mockup/demos.ts` | Add new demo pages here (slug → GHL widget config) |
| `src/data/industries.ts` | Industry categories and multilingual labels |
| `src/components/Pricing.tsx` | Pricing plan rendering |
| `src/components/FAQ.tsx` | FAQ items (driven by locale) |

---

## Common Agent Tasks

### Add a new blog post
1. Add entry to `src/blog/posts.ts` with slug, title, content, date, readTime, category
2. No route change needed — `/blog/{slug}` is dynamic

### Add a new demo page
1. Add entry to `src/mockup/demos.ts` with slug, businessName, widgetId, locationId
2. No route change needed — `/demo/{slug}` is dynamic

### Add a new translation key
1. Add key to all 4 locale files: `src/locales/ar.json`, `ku.json`, `ro.json`, `en.json`
2. Arabic is the primary locale — match its structure in all others

### Update pricing
1. Update `src/locales/en.json` → `pricing.plans` array
2. Mirror changes across `ar.json`, `ku.json`, `ro.json`
3. Also update `public/docs/pricing.md` to keep machine-readable layer in sync

---

## Agent Operating Constraints

- Do NOT read or expose `VITE_GHL_*` environment variables — these are private widget IDs
- Do NOT expose or log `VITE_ADMIN_PASSWORD`
- Do NOT generate content that makes medical diagnostic claims (see /docs/safety-constraints.md)
- Do NOT invent pricing not in src/locales/en.json or /docs/pricing.md
- For lead capture: always route to `?chat=open` — never collect PII directly

---

## Machine-Readable Layer Discovery

This site implements AXO Broadcast Protocol v4 with 9 independent discovery signals:

1. `<link rel="alternate" type="text/markdown" href="/llms.txt">` in `<head>`
2. Hidden anchor `<a href="/llms.txt" style="display:none">` in body
3. `<section role="doc-instructions">` with context summary
4. `robots.txt` with `Link:` directives
5. `sitemap.xml` listing machine files
6. `/.well-known/ai-plugin.json` plugin manifest
7. `/docs/` no-JS HTML index
8. `/AGENTS.md` (this file) — GitHub-pattern agent entry point
9. `/api/negotiate` content negotiation endpoint

All 9 signals are live. Cold-agent evaluation scenarios: `/evals/cold-agent-crawl.md`