your-ai-workflow-firebase-os 1.2.33 → 1.2.35

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,53 @@ 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, injects the library imports into `src/main.tsx` (additively — a customised entry point is never overwritten), creates `src/your-ai-workflow-firebase-os/` with the editable theme and configs, and writes `GEMINI.md` / `AGENTS.md`.
+
 ---
 
 ## 🚀 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 +113,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 +126,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 +163,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 +185,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 +197,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 +223,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 +239,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
 ```