stack

> **OmegaOS skill — the build half of the Blueprint OS chain.** > `/blueprint-os` designs an OS. `/stack` turns that design into a running app on the > canonical stack. Triggers `/stack` and `/omg-stack`. ## The stack, non negotiable (R-BLUEPRINT-STACK) | Layer | Techno | Role | |---|---|---| | **Shell / UI** | **Stax** | The panel grammar. Every OS wears the same navigation | | Front | Next.js (App Router) | The app | | Data + realtime | Convex | The single model. Reactive by default | | Auth | Clerk | Identity, organizations, roles | | AI | Claude, called from a **Convex action** | Never from the client | If a design suggests something else, the design changes, not the stack. **Stripe is opt-in, not part of the default.** Pass `--stripe` when the app actually charges someone. Most OS products are built and used long before they are sold, and a billing surface nobody calls is dead code that still demands keys, a webhook endpoint, and a dashboard setup. Scaffold it when it earns its place. ## Stax is pulled every single time Before any scaffold, `stack-new.sh` runs the Stax sync — fast-forward only, never clobbering local commits. The app is always vendored from the **current** `main` of `github.com/agentik-os/stax`. The commit that was vendored is written into `stax.lock.json` at the app root, so a build is always traceable to a Stax revision. This is the rule, not an optimization: an app scaffolded from a stale Stax drifts from the rest of the family, and the drift is invisible until the panel grammar disagrees. --- ## How to run it ```bash bash ~/.omega/skills/stack/scripts/stack-new.sh <app-name> [--blueprint <dir>] [--dir <parent>] [--stripe] ``` | Flag | Effect | |---|---| | `--blueprint <dir>` | Read a Blueprint OS folder: phase `09-data/schema.ts` becomes the Convex schema, phase `10-stax/panneaux.md` drives the panel registry | | `--dir <parent>` | Where the app is created. Defaults to `~/Station/SideBusiness` | | `--stripe` | **Opt-in billing.** Adds the checkout route, the webhook route, `lib/stripe.ts`, the `stripe` dependency, and the Stripe env block | | `--no-install` | Scaffold the files, skip `npm install` (offline / inspection) | The script is **idempotent on a fresh dir and refuses to overwrite an existing app** — rerunning it on a live project is a destructive act, so it stops instead (R-DESTRUCT). --- ## What the script does, in order 1. **Sync Stax** — `stax-sync.sh`, ff-only. Records the commit. 2. **`create-next-app`** — TypeScript, App Router, Tailwind, `src/`. 3. **Vendor Stax** — calls the existing `stax-scaffold.sh` (never reimplemented here): `panels-core.ts`, `panels-react.tsx`, `tokens.css`, `stax-ui.css` into `src/stax/`. 4. **Convex** — `convex/schema.ts` (from the blueprint if given, else the canonical pattern), `convex/auth.config.ts` wired to Clerk, an example query and mutation. 5. **Clerk** — middleware, provider, and the Convex `ConvexProviderWithClerk` bridge. 6. **Stripe — only with `--stripe`** — checkout route, webhook route, and `lib/stripe.ts`. The **price IDs are left as named placeholders** because only the operator can create them. Without the flag, none of this is written and `stripe` is not installed. 7. **`.env.example`** — every key, with who provides it and where to get it. 8. **`NEEDS-OPERATOR.md`** — the exact list of what a human must do before the app runs. Then it prints the list. It never invents a key, never fakes a Stripe ID, and never claims the app runs before `npm run dev` has actually been executed. --- ## The Stripe IDs — read this before promising anything *Only relevant when the app was scaffolded with `--stripe`.* Stripe is the one layer that **cannot** be fully scaffolded. Products and prices live in the operator's Stripe account, and their IDs (`price_…`, `prod_…`) do not exist until a human creates them. The scaffold therefore writes placeholders and lists them. Never guess a `price_…`. A wrong price ID fails at checkout, in production, on a real customer. See `references/stripe.md` for the full setup path and the webhook events that actually matter. --- ## Building from a blueprint When `--blueprint` points at a Blueprint OS folder, the chain is: | Blueprint phase | Becomes | |---|---| | `09-data/schema.ts` | `convex/schema.ts`, verbatim if valid | | `10-stax/panneaux.md` | The panel registry and the inspector stubs | | `06-features/features.md` | The `NEEDS-BUILD.md` checklist, layer by layer | | `08-ia/system-prompts.md` | `convex/ai/` action stubs, one per agent | **Gate, enforced mechanically.** `stack-new.sh` runs `blueprint-check.sh --gates-only` before it scaffolds anything, and **refuses** on an unfranchised gate. Building from a blueprint that failed the parity gate produces a demo whose missing socle is discovered at delivery, which is exactly the failure mode phase 5 exists to prevent. `--force-gates` overrides it. Use it knowing what it costs, and it says so out loud. Run the full check yourself when you want more than the gates: ```bash bash ~/.omega/skills/blueprint-os/scripts/blueprint-check.sh <blueprint-dir> ``` --- ## Rules of conduct **Pull Stax first, always.** No exception, no "it was synced this morning". **Never fabricate an ID or a key.** Placeholder plus a line in `NEEDS-OPERATOR.md`. **Never start a dev server to "verify" (R-TEST)** — except here, where the code is brand-new and not yet deployed. That is the documented exception: one `npm run dev`, one HTTP probe, then kill it. Real runtime evidence, not a green install log (L1). **Secrets never enter the repo (R-ENV / L0).** `.env.local` is gitignored; the `.env.example` carries names only. Keys live in `~/.omega/secrets/<app>.env`. **The panel grammar is not optional.** No pages, no modals, no tabs. If the app grows a second navigation mechanic, it stopped being an AgentikOS app. --- ## Reference files | File | When | |---|---| | `references/convex.md` | Schema, indexes, auth, and calling Claude from an action | | `references/clerk.md` | The Clerk plus Convex bridge, and the JWT template that trips everyone | | `references/stripe.md` | Products, prices, webhooks, and the IDs the operator must create | | `references/env.md` | Every environment variable, who provides it, where it lives |