your-ai-workflow-firebase-os 1.2.34 → 1.2.36

package/README.md

@@ -1,12 +1,12 @@
-# 🔥 Firebase OS
+# 🔥 Your AI Firebase
 
-**A complete, production-ready Firebase admin OS — packaged as a single React component.**
+**A complete, production-ready Firebase app — packaged as a single React component.**
 
-Authentication, user management, role-based access control, file storage, dynamic pages, form builder, theme customisation, and more — all behind one import.
+Authentication, user management, role-based access control, file storage, pages your AI assistant builds, a form builder, a theme engine and an inbox — all behind one import.
 
 ```tsx
-import { FirebaseOS } from 'firebase-os';
-import 'firebase-os/styles.css';
+import { FirebaseOS } from 'your-ai-workflow-firebase-os';
+import 'your-ai-workflow-firebase-os/styles.css';
 
 export default function App() {
   return <FirebaseOS />;
@@ -15,6 +15,10 @@ export default function App() {
 
 That's it. **One component. Zero configuration files.**
 
+> The component, the package and the `.firebase-os` CSS scope keep their original
+> names — renaming them would break every existing install. The product is called
+> Your AI Firebase.
+
 ---
 
 ## ✨ What you get
@@ -22,15 +26,17 @@ That's it. **One component. Zero configuration files.**
 | Feature | Details |
 |:--------|:--------|
 | 🔐 **Authentication** | Email/password, email verification, password reset |
-| 👥 **User Management** | Admin panel, role assignment, inactive user blocking |
-| 🗂️ **Dynamic Pages** | Create pages from the admin panel — no code needed |
-| 📋 **Templates** | Board (Kanban), Calendar, Table, Inline Form, Popup Form, Confirmation |
+| 👥 **User Management** | Admin panel, three access levels (Free · Internal · Admin), inactive user blocking |
+| 🗂️ **Pages** | Ask your AI assistant for a page — for anyone, signed-in users, your team or admins only — and it appears in `/pages`, where you rename it, reorder it, hide it or change its web address |
+| 📋 **Templates** | Board (Kanban), Calendar, Table, Drive, Inline Form, Popup Form, Confirmation |
 | 🎨 **Theme Engine** | Full dark/light mode, custom accent colours, fonts, corner radii, logo |
-| 📁 **File Storage** | Firebase Storage drive with folder structure |
-| 📬 **Form Builder** | Contact forms, support forms — fully customisable |
-| ⚙️ **Settings** | All admin settings via UI — no `.env` editing needed after setup |
+| 📁 **File Storage** | An admin-only Assets screen for public images, plus a drive preset any page can be built on |
+| 📬 **Forms** | Ask the AI for a form — it shows up in `/forms`, where the title, fields and button text are editable |
+| 📥 **Inbox** | Every form entry in one list at `/inbox`, filtered "From anyone" or "From signed-in users" |
+| 📖 **Guide** | A walkthrough at `/guide` with the sentences to paste into your assistant |
 | 📊 **Dashboard** | Personalised user dashboard |
-| 🧑‍💼 **Submissions & Requests** | Track form submissions and user requests |
+
+Ordering, visibility, renaming and deleting all live on the Pages screen — there is no separate settings screen, no Submissions screen and no Requests screen.
 
 ---
 
@@ -46,56 +52,59 @@ npm install firebase react react-dom react-router-dom
 
 **From npm:**
 ```bash
-npm install firebase-os
+npm install your-ai-workflow-firebase-os
 ```
 
 **From a local build (development):**
 ```bash
-npm pack  # in the firebase-os repo
-npm install /path/to/firebase-os-1.0.0.tgz  # in your app
+npm pack  # in this repo
+npm install /path/to/your-ai-workflow-firebase-os-1.0.0.tgz  # in your app
 ```
 
+Installing runs a postinstall step that patches the consumer project: it clears Vite's default CSS, writes `src/main.tsx` and `src/App.tsx` (both are owned by the library — see below), adds `yourAiFirebase()` from `your-ai-workflow-firebase-os/vite` and Tailwind to `vite.config.ts`, creates `src/your-ai-workflow-firebase-os/` with the editable theme and configs, and writes `GEMINI.md` / `AGENTS.md`.
+
+### What the build enforces
+
+The package ships a Vite plugin, `yourAiFirebase()`, that puts the project's structure out of the assistant's reach. `src/App.tsx` and `src/main.tsx` are owned files: the plugin serves its own canonical source for both and rewrites them on disk whenever they differ, so an edit there has no effect. Pages, forms and content files are discovered from `src/your-ai-workflow-firebase-os/configs/` and `microcomponents/` through a virtual module, so a deleted registry import can no longer make a page vanish. And every discovered file is validated before the build: a config file with the wrong name, a `route` that is not one string starting with `/`, an address used twice, a `*Tab.config.ts` without a valid `pageType`, a missing `*Config` export, a `systemName` that does not match the file, or a content file with no default export fails the build with one sentence that names the fix. A hand-written `<form>` in a content file only warns — its entries would never reach the Inbox.
+
+Manual-first recipe: the owner adds the page on `/pages` (or the form on `/forms`) and then asks the assistant for the content, which is a single `microcomponents/<PascalCaseName>Content.tsx` file — no config file, no second address.
+
 ---
 
 ## 🚀 Quick Start
 
 ### Option A — Zero config (recommended)
 
-On first load, Firebase OS shows a **Setup Wizard** that guides you through pasting your Firebase project credentials. Nothing is stored on any server — keys are saved in your browser's `localStorage`.
+On first load the app opens its **Setup screen**, which walks through connecting a Firebase project. Nothing is stored on any server — keys are saved in the browser's `localStorage`.
 
 ```tsx
 // App.tsx
-import { FirebaseOS } from 'firebase-os';
-import 'firebase-os/styles.css';
+import { FirebaseOS } from 'your-ai-workflow-firebase-os';
+import 'your-ai-workflow-firebase-os/styles.css';
 
 export default function App() {
   return <FirebaseOS />;
 }
 ```
 
-1. Run your app
-2. The Setup Wizard opens automatically
-3. Paste your Firebase config (from the Firebase Console)
-4. Done — the full OS loads
-
 ### Option B — Pre-configured (CI/CD, teams)
 
-Skip the wizard entirely by passing your Firebase config as props:
+Skip the setup screen entirely by passing the Firebase config as props:
 
 ```tsx
-import { FirebaseOS } from 'firebase-os';
-import 'firebase-os/styles.css';
+import { FirebaseOS } from 'your-ai-workflow-firebase-os';
+import 'your-ai-workflow-firebase-os/styles.css';
 
 export default function App() {
   return (
     <FirebaseOS
       firebaseConfig={{
-        apiKey: import.meta.env.VITE_API_KEY,
-        authDomain: import.meta.env.VITE_AUTH_DOMAIN,
-        projectId: import.meta.env.VITE_PROJECT_ID,
-        storageBucket: import.meta.env.VITE_STORAGE_BUCKET,
-        messagingSenderId: import.meta.env.VITE_MESSAGING_SENDER_ID,
-        appId: import.meta.env.VITE_APP_ID,
+        apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+        authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+        projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+        storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
+        messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
+        appId: import.meta.env.VITE_FIREBASE_APP_ID,
       }}
       adminEmails={['you@yourcompany.com']}
     />
@@ -110,8 +119,8 @@ export default function App() {
 ```typescript
 interface FirebaseOSProps {
   /**
-   * Pass Firebase config directly to skip the Setup Wizard.
-   * If omitted, the wizard runs on first load and saves config to localStorage.
+   * Pass Firebase config directly to skip the Setup screen.
+   * If omitted, setup runs on first load and saves config to localStorage.
    */
   firebaseConfig?: {
     apiKey: string;
@@ -123,24 +132,36 @@ interface FirebaseOSProps {
   };
 
   /**
-   * Email addresses that are automatically assigned the 'admin' role
-   * on their first login. Replaces the VITE_ADMIN_EMAILS env var.
+   * Email addresses that are automatically assigned the 'admin' role once
+   * they have verified their email. Replaces the VITE_ADMIN_EMAILS env var.
+   * The same addresses have to be in the Firestore rules you pasted during
+   * setup — /setup writes them in for you — since the rules, not the client,
+   * are what actually grant the role.
    */
   adminEmails?: string[];
 
-  /**
-   * Custom router basename (e.g. "/app" if your app lives at a subdirectory).
-   */
+  /** Theme defaults from your own theme.config.ts. */
+  themeConfig?: any;
+
+  /** Auto-discovered page content files, keyed by page id. */
+  microcomponents?: Record<string, React.ComponentType<any>>;
+
+  /** Local overrides for built-in components — `{ Home }` is the usual one. */
+  components?: { Home?: React.ComponentType<any> };
+
+  /** Default form configs shipped with your project. */
+  defaultConfigs?: { contactForm?: any; supportForm?: any };
+
+  /** Custom router basename (e.g. "/app" if your app lives at a subdirectory). */
   basename?: string;
 
-  /**
-   * Callback fired whenever the Firebase auth state changes.
-   * Useful for integrating with your own auth layer.
-   */
+  /** Callback fired whenever the Firebase auth state changes. */
   onAuthChange?: (user: any) => void;
 }
 ```
 
+The postinstall step writes an `App.tsx` that already passes `themeConfig`, `microcomponents`, `components` and `defaultConfigs` for you.
+
 ---
 
 ## 🪝 Advanced: Hooks
@@ -148,7 +169,7 @@ interface FirebaseOSProps {
 For advanced integrations, two hooks are exported from the library:
 
 ```tsx
-import { useAuth, useTheme } from 'firebase-os';
+import { useAuth, useTheme } from 'your-ai-workflow-firebase-os';
 
 // Access auth state anywhere inside <FirebaseOS />
 function MyWidget() {
@@ -170,6 +191,8 @@ function MyWidget() {
 4. Copy the `firebaseConfig` object
 5. Enable **Authentication** (Email/Password), **Firestore**, and **Storage** in your project
 
+The Setup screen in the app walks through all of this and generates the security rules to paste, so nobody has to work it out from here.
+
 ---
 
 ## 🎨 Theming
@@ -180,9 +203,17 @@ All CSS is scoped to `.firebase-os` — the library's styles **do not leak** int
 
 ---
 
+## 🤖 Working with the AI
+
+Your AI Firebase is built to be driven from an AI chat (Google AI Studio, Cursor, Claude Code…). On install it writes **`GEMINI.md` / `AGENTS.md`** into the project: what the assistant may build, which words to use with the owner, and what it must never touch.
+
+**That file is the contract, and it is the only copy.** It is generated by [`scripts/postinstall.js`](scripts/postinstall.js) — read it there, and change it there. This README deliberately does not restate it, so the two can never disagree.
+
+The short version for a person evaluating the library: you ask for a page or a form in plain language, the assistant writes it, and it appears on the `/pages` or `/forms` screen where the basics — name, web address, icon, linked form, order, visibility — are yours to edit. Everything else is the assistant's job; ask it in chat.
+
 ## 📐 CSS Isolation
 
-Firebase OS uses a `.firebase-os` container div for all its CSS variable scope. This means:
+The library uses a `.firebase-os` container div for all its CSS variable scope. This means:
 
 - ✅ Library's theme variables stay inside `.firebase-os`
 - ✅ Your own `:root` variables are untouched
@@ -198,7 +229,7 @@ Firebase OS uses a `.firebase-os` container div for all its CSS variable scope.
 - **Files** — your own Firebase Storage
 - **Theme / page config** — your own Firestore (`sys_configs` collection)
 
-You own all your data. Firebase OS is just the UI layer.
+You own all your data. Your AI Firebase is just the UI layer.
 
 ---
 
@@ -214,17 +245,18 @@ src/
 │   ├── AuthContext   ← Auth lifecycle (internal)
 │   ├── ThemeContext  ← CSS variable injection (internal)
 │   └── ConfigContext ← Library props → internal bridge
-├── pages/            ← 17 page components (internal)
-├── templates/        ← 8 template components (internal)
-├── components/       ← Shared UI (internal)
-└── configs/          ← Default configurations (internal)
+├── pages/            ← Page components (internal)
+├── templates/        ← Template components (internal)
+├── components/       ← Shared UI, incl. components/fields (internal)
+├── configs/          ← Default configurations (internal)
+└── contract/         ← Tests pinning the generated GEMINI.md contract
 ```
 
 ### Scripts
 
 ```bash
 npm run dev          # Run standalone app (for development)
-npm run test         # Run test suite (47 tests)
+npm run test         # Run the test suite
 npm run build:lib    # Build the distributable library
 npm pack             # Create .tgz for local testing
 ```