create-gentiq-app 0.14.0 → 0.15.0-beta.2

package/README.md

@@ -32,7 +32,7 @@ pnpm create gentiq-app my-awesome-ai
 - ⚡ **AI Streaming**: Real-time agent responses via PydanticAI and Vercel AI SDK.
 - 🛠️ **Admin Dashboard**: Built-in analytics, history logs, and user management.
 - 💰 **Atomic Balance**: Native tracking and enforcement of per-user token and request limits.
-- 📂 **Flexible Persistence**: Integrated MinIO/S3 for file storage and MongoDB for state.
+- 📂 **Flexible Persistence**: SQLite + local filesystem out of the box; MongoDB + MinIO/S3 for production.
 - 🔒 **Enterprise-Grade Security**: Full JWT authentication suite and encrypted sessions.
 
 ---
@@ -45,11 +45,12 @@ When you initialize a new app, the CLI generates a modern, monorepo-friendly str
 my-awesome-ai/
 ├── backend/            # FastAPI + PydanticAI application
 │   ├── main.py         # App entry point
-│   └── pyproject.toml  # Python dependencies (UV managed)
+│   ├── pyproject.toml  # Python dependencies (UV managed)
+│   ├── .env.example    # Environment variable template
+│   └── .env            # Generated, with real secrets — gitignored
 ├── frontend/           # Vite + React application
 │   ├── src/            # UI components and hooks
 │   └── package.json    # Frontend dependencies
-├── .env.example        # Environment variable template
 └── README.md           # Your project documentation
 ```
 
@@ -59,24 +60,27 @@ my-awesome-ai/
 
 Once your project is scaffolded, follow these steps to get running:
 
-### 1. Environment Setup
-Copy the example environment file and add your API keys and modify other variables as desired:
-```bash
-cp .env.example .env
-```
+The CLI does the setup for you: it installs the backend dependencies with `uv sync`,
+installs the frontend dependencies with your package manager, and writes `backend/.env`
+with freshly generated `JWT_SECRET_KEY` and `BACKEND_API_KEY` values. So once it
+finishes, the project runs.
+
+### 1. Launch Backend
 
-### 2. Launch Backend
-The backend uses `uv` for lightning-fast Python package management.
 ```bash
 cd backend
-uv sync
 uv run uvicorn main:app.api --reload --port 8000
 ```
 
-### 3. Launch Frontend
+The only value you have to supply yourself is the AI provider key. If you did not paste
+one at the prompt, set `OPENAI_API_KEY` in `backend/.env` before starting — the agent
+definition in `main.py` builds its provider client on import, so an absent key is a
+startup error rather than a failed chat. Using a different provider? Change the model
+string in `backend/main.py` and set that provider's key instead.
+
+### 2. Launch Frontend
 ```bash
 cd frontend
-npm install
 npm run dev
 ```
 
@@ -84,6 +88,143 @@ Your app is now live at `http://localhost:5173`!
 
 ---
 
+## Options
+
+```bash
+npx create-gentiq-app@latest [directory] [options]
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--pm <name>` | Package manager for the frontend install: `pnpm`, `npm`, `yarn` or `bun`. Defaults to the one that invoked the CLI. |
+| `--no-install` | Scaffold only — skip `uv sync` and the frontend install. |
+| `--openai-key <key>` | Write this `OPENAI_API_KEY` into `backend/.env` instead of prompting. |
+| `-y`, `--yes` | Accept every default and never prompt. Also the automatic behaviour when there is no TTY, so the CLI is usable from CI. |
+| `-h`, `--help` | Show usage. |
+
+Missing tools are reported, not fatal: without `uv` the backend install is skipped with
+an install link, and a package manager that is not on `PATH` falls back to one that is.
+The scaffold itself is complete either way, and the printed next steps name whatever is
+left to run by hand.
+
+---
+
+## Using Tailwind in a Gentiq app
+
+The scaffold ships **no Tailwind** — `gentiq/style.css` is already compiled, and the chat
+and admin UIs are fully styled by it. You only need Tailwind if you are writing your own
+components (a custom tool card, say). If you add it, read this section first: two Tailwind
+builds in one document need one extra line to coexist, and without it they break each
+other silently.
+
+### Why it needs care
+
+Tailwind guarantees that a variant (`md:`, `hover:`) is emitted *after* the plain utility
+it is meant to override — that is the whole reason `flex-col md:flex-row` works. The
+guarantee holds **per build**. Gentiq ships precompiled CSS, so adding Tailwind to your app
+creates a second, independently sorted set of utilities, and concatenating them destroys
+the ordering: whichever set lands later wins every tie, regardless of which stylesheet
+"owns" the class.
+
+Both directions are broken, and neither announces itself:
+
+| Your utilities last | Gentiq's utilities last |
+| --- | --- |
+| Your `.flex-col` beats gentiq's `.md:flex-row` — the admin header collapses into a vertical stack at every width | Gentiq's `.grid-cols-2` beats your `.sm:grid-cols-3` — your own grids stop responding |
+
+Reordering does not fix it, because the problem is not the order. It is that there are two
+sorts. The fix is to collapse them back to one.
+
+### The setup
+
+Put this at the top of `src/index.css`, and delete `import 'gentiq/style.css'` from
+`src/App.tsx` (this file has to load first, so it must own that import):
+
+```css
+/* Layer order for the document: gentiq's layers first, yours last. */
+@layer properties, gentiq-theme, gentiq-base, gentiq-components, gentiq-utilities,
+       theme, base, components, utilities;
+
+@import 'gentiq/style.css';
+
+/* Theme + utilities only — NOT `@import 'tailwindcss'`. That bundles preflight,
+   and gentiq's stylesheet already ships one; a second copy lands after gentiq's
+   rules and its `border: 0 solid` resets border-color to currentColor, which
+   paints every unstyled border in the app the foreground colour. */
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+/* The line that actually makes the two coexist: scan gentiq's bundles so YOUR
+   build emits gentiq's classes too. One build, one sort, every variant back
+   after its base utility. Gentiq's precompiled layer is then shadowed for every
+   class you regenerate, and still supplies its custom `@utility` rules (`glass`,
+   the loader animations), whose names contend with nothing you emit. */
+@source '../node_modules/gentiq/dist/gentiq-index.es.js';
+@source '../node_modules/gentiq/dist/gentiq-admin.es.js';
+
+/* Gentiq's design tokens, registered with YOUR Tailwind instance. Gentiq declares
+   the same map in its own `@theme inline`, but that lives in its compiled
+   stylesheet, which your compiler never sees — so without this block utilities
+   like `hover:border-primary/40` silently generate nothing. `inline` is what makes
+   them resolve at runtime, so ThemeProvider can keep rewriting accent and theme. */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+```
+
+Do not set `body { font-family: … !important }` here. `ThemeProvider` composes the
+configured face with `var(--font-script)` and writes it inline to `<html>` and `<body>`;
+an `!important` rule beats that inline style and strips the per-script fallback, leaving
+Persian and Arabic text in a serif default.
+
+The `@source` lines cost roughly 10–13 kB gzipped, because your build re-emits the
+utilities gentiq already shipped. That is the price of a correct cascade; the duplicate
+rules are identical and fully shadowed.
+
+### Layers
+
+Gentiq publishes into `gentiq-theme`, `gentiq-base`, `gentiq-components` and
+`gentiq-utilities` rather than the bare `theme` / `base` / `components` / `utilities`
+(versions up to and including `0.15.0-beta.1` used the bare names). Those generic names belong to your document, and gentiq
+claiming them is what let the two builds merge by accident in the first place. Gentiq
+deliberately does **not** pre-register your layer names, so your stylesheet keeps the
+position it has always had; the `@layer` statement above is where you decide the order.
+
+The setup above works against older versions too — the `gentiq-*` layers just stay empty
+and gentiq's stylesheet lands in `theme` / `base` / `utilities` instead, still ahead of
+your regenerated superset.
+
+### Checking it
+
+The admin dashboard header is the fastest canary — it is the layout in the product that
+leans hardest on `md:` overrides. Open `/admin` above 768px: the logo and the navigation
+tabs sit on one row. If they are stacked vertically, your utilities are beating gentiq's
+variants and `@source` is missing or pointing at the wrong path.
+
+---
+
 ## Why Gentiq?
 
 Unlike generic boilerplates, Gentiq is built with **developer velocity** and **production scalability** in mind. It provides the "boring" parts of AI development—authentication, rate limiting, and persistence—so you can focus on building your agents.

package/copy-template.js

@@ -2,6 +2,8 @@ import fs from 'fs-extra';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
+import { shouldSkipEntry } from './skipped-entries.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -15,10 +17,7 @@ async function copyTemplate() {
     await fs.emptyDir(dest);
 
     await fs.copy(src, dest, {
-        filter: (src) => {
-            const basename = path.basename(src);
-            return !['node_modules', '.venv', '__pycache__', '.ruff_cache', 'dist', '.storage', 'gentiq.db', 'uv.lock', 'package-lock.json', 'pnpm-lock.yaml'].includes(basename);
-        }
+        filter: (src) => !shouldSkipEntry(path.basename(src)),
     });
 
     console.log('Template copied successfully!');