# Custom app widgets — connect your repo to ZES-QRE

For programmers shipping Nail-OS or other GitHub apps under a ZES tenant.

Public twin of Operator knowledge templates in `/knowledge/*.txt`.

---

## What ZES injects on hosted HTML

When a file is served from `/api/github/custom/{tenantId}/…`, the host shell adds:

| Asset | Role |
|---|---|
| `qre-platform.js` | Tenant, modules, Firebase |
| `platform-chrome.js` | Copilot FAB, chrome |
| `support-widget.js` | QRE AI chat |
| `ai-knowledge.js` | Active apps, knowledge folder, product book |
| `nailos-zes-bridge.js` | Home/Admin rewrite, session mirror, network |
| `nailos-zes-widgets.js` | Widget API for your app |
| theme + app-launcher CSS | Visual match to ZES |

Home = `/starting_page.html` · Admin = `/admin.html` (never Nail index/admin on SaaS).

---

## Widget API (`window.QreNailosWidgets`)

```js
QreNailosWidgets.openCopilot('Where is art EEF9M?');
QreNailosWidgets.openPage('info.html?art=EEF9M');
QreNailosWidgets.registerProductBookProvider(async () => {
  return [{ art: 'EEF9M', name: 'F9M', description: '…' }];
});
QreNailosWidgets.registerContextProvider(async () => ({
  vertical: 'nail-os',
  tips: 'Prefer info catalog for machine questions'
}));
```

### Built-in widget ids

- `copilot` · `page-open` · `live-preview` · `product-book` · `workspace-home` · `platform-admin` · `network-bridge`

---

## Teaching Copilot about your app

1. **Operator Console → Tools → AI knowledge folder** — create/open `.txt` files (integration, widgets, product-book, navigation).  
2. **Publish to tenant** — save onto the customer workspace (`aiKnowledgeFiles`) so their Copilot categorizes and answers from your notes.  
3. Ship copies under `knowledge/` in future repos so every clone starts with ZES connection instructions.

Templates:

- `/knowledge/connect-custom-app-to-zes.txt`
- `/knowledge/zes-widgets-catalog.txt`
- `/knowledge/nailos-product-book.txt`

---

## Product book (Nail-OS)

Copilot calls `info_catalog_get` (or your registered provider). For SKU questions it:

1. Quotes tenant catalog text  
2. Offers **Open specific page** → `info.html?art=…` or `product.html?art=…`  
3. Only offers live preview when the user asks for a guided ZES module runthrough  

---

## Checklist before go-live

- [ ] Repo linked on custom tenant plan  
- [ ] No reliance on Nail `index.html` as SaaS home  
- [ ] Product book provider or info catalog populated  
- [ ] At least one tenant knowledge `.txt` describing your workflows  
- [ ] Network / storage_base configured in ZES Admin when apps need EXE storage