create-freakpunch 0.1.0 → 0.2.0

package/README.md

@@ -1,23 +1,24 @@
-# create-freakpunch
-
-Adds the freakpunch admin panel to any project as a self-contained `fp-admin/` folder. It has its own
-`package.json`, talks to your backend over HTTP, and works next to PHP, Laravel, Next.js or anything else.
-
-```bash
-cd my-project
-npm create freakpunch@latest
-cd fp-admin
-npm run dev
-```
-
-Options: `npm create freakpunch@latest my-folder`, `-- --no-install`, `-- --no-agent-files`.
-
-The command also adds a short pointer to `fp-admin/` in your project's `CLAUDE.md` and `AGENTS.md`
-(creating them if needed), so AI agents started at the project root follow the panel's design rules.
-
-Get newer freakpunch files later (your modules and config are never touched; `--dry-run` previews):
-
-```bash
-cd fp-admin
-npm run fp:update
-```
+# create-freakpunch
+
+Adds a clean admin panel to any project as a self-contained `fp-admin/` folder. It has its own
+`package.json`, talks to your backend over HTTP, and works next to PHP, Laravel, Next.js or anything else.
+The first time you open it, a setup wizard creates your company and admin account.
+
+```bash
+cd my-project
+npm create freakpunch@latest
+cd fp-admin
+npm run dev
+```
+
+Options: `npm create freakpunch@latest my-folder`, `-- --no-install`, `-- --no-agent-files`.
+
+The command also adds a short pointer to `fp-admin/` in your project's `CLAUDE.md` and `AGENTS.md`
+(creating them if needed), so AI agents started at the project root follow the panel's design rules.
+
+Get newer freakpunch files later (your modules and config are never touched; `--dry-run` previews):
+
+```bash
+cd fp-admin
+npm run fp:update
+```

package/bin/create-freakpunch.mjs

@@ -23,6 +23,7 @@ const PROJECT_OWNED = [
   /^\.gitignore$/,
   /^package\.json$/,
   /^package-lock\.json$/,
+  /^\.env/,
 ]
 const isProjectOwned = (file) => PROJECT_OWNED.some((r) => r.test(file))
 
@@ -96,11 +97,10 @@ function create(args) {
     if (!isProjectOwned(target)) files[target] = hashFile(path.join(root, target))
   }
 
-  // Installed defaults: start clean instead of with the template's demo content.
-  const appName = path.basename(project).replace(/[^\w .-]/g, '') || 'Admin'
-  const config = readFileSync(path.join(pkgDir, 'files/app.config.ts'), 'utf8').replaceAll('__APP_NAME__', appName)
-  writeFileSync(path.join(root, 'src/app.config.ts'), config)
   copyFileSync(path.join(pkgDir, 'files/README.md'), path.join(root, 'README.md'))
+  // Browser data is per address, so each project gets its own dev port and panels never share accounts.
+  const port = 5200 + (parseInt(hash(root).slice(0, 6), 16) % 700)
+  writeFileSync(path.join(root, '.env.development'), `VITE_DEV_PORT=${port}\n`)
   writeManifest(root, files)
 
   const notes = flags.has('--no-agent-files') ? [] : addAgentNotes(project, dirName)
@@ -120,8 +120,8 @@ Done. Next:
   cd ${dirName}
   npm run dev
 
-Sign in with owner@freakpunch.site and any password (demo mode).
-Add a feature:  npm run new-module -- assets --en "Assets" --tr "Zimmet"
+The first time you open it, a setup wizard creates your company and admin account.
+Add a feature:  npm run new-module -- orders --en "Orders" --tr "Siparişler"
 Connect a backend, serve under /admin: see ${dirName}/BACKEND.md
 `)
 }

package/files/README.md

@@ -1,15 +1,19 @@
-# Admin panel
-
-Built on [freakpunch](https://www.npmjs.com/package/create-freakpunch).
-
-```bash
-npm run dev                                                  # start it
-npm run new-module -- assets --en "Assets" --tr "Zimmet"     # add a feature
-npm run check                                                # design rules + lint + build
-npm run fp:update                                            # get newer freakpunch files
-```
-
-- Your code: `src/modules/`, `src/app.config.ts`, `src/app.roles.ts`, `public/`.
-- freakpunch's code: everything else. `npm run fp:update` refreshes it, so don't edit it here.
-- Rules for people and AI agents: [CLAUDE.md](./CLAUDE.md) and [design/](./design).
-- Connecting a backend and deploying under `/admin`: [BACKEND.md](./BACKEND.md).
+# Admin panel
+
+Built on [freakpunch](https://www.npmjs.com/package/create-freakpunch).
+
+```bash
+npm run dev                                                  # start it
+npm run new-module -- orders --en "Orders" --tr "Siparişler"  # add a feature
+npm run check                                                # design rules + lint + build
+npm run fp:update                                            # get newer freakpunch files
+```
+
+The first time you open it, a setup wizard creates your company and admin account. To start over without a
+backend, clear this site's data in your browser. Built-in pages such as Users and Audit log are off:
+turn them on in `src/app.config.ts` → `features`.
+
+- Your code: `src/modules/`, `src/app.config.ts`, `src/app.roles.ts`, `public/`.
+- freakpunch's code: everything else. `npm run fp:update` refreshes it, so don't edit it here.
+- Rules for people and AI agents: [CLAUDE.md](./CLAUDE.md) and [design/](./design).
+- Connecting a backend and deploying under `/admin`: [BACKEND.md](./BACKEND.md).

package/files/app.config.ts

@@ -1,58 +1,50 @@
-import type { AppConfig, AuthMode } from '@/core/config/types'
-
-/** This project's panel: name, brand, sidebar groups, modules and which built-in areas are on. */
-export const appConfig = {
-  name: '__APP_NAME__',
-  /** A preset key from src/core/theme/brand.ts, or a custom { color, foreground } pair. */
-  brand: 'indigo',
-
-  /** Workspaces shown in the sidebar switcher. */
-  workspaces: [{ id: 'main', name: '__APP_NAME__', plan: 'common:plans.business' }],
-
-  /** Sidebar group order; labels are translation keys. Modules attach nav items to these ids. */
-  navGroups: [
-    { id: 'overview', label: 'common:nav.groups.overview' },
-    { id: 'catalog', label: 'common:nav.groups.catalog' },
-    { id: 'content', label: 'common:nav.groups.content' },
-    { id: 'system', label: 'common:nav.groups.system' },
-  ],
-
-  /**
-   * Turn modules on/off. Keys must exist in src/modules/registry.ts. `products` is the
-   * reference module agents copy patterns from; it stays off unless you want it.
-   */
-  modules: {
-    products: false,
-    // fp:modules
-  },
-
-  /** Marketing page at `/`; off, so `/` opens the panel. */
-  landing: false,
-
-  /** Built-in areas. Switch off what this project doesn't need. */
-  features: {
-    /** Off until connected: its demo feed talks about products and stock. */
-    notifications: false,
-    users: true,
-    roles: true,
-    securityPolicies: true,
-    modules: true,
-    integrations: true,
-    auditLog: true,
-    dangerZone: true,
-    /** The sample KPI/revenue/activity cards on the dashboard. */
-    demoDashboard: false,
-  },
-
-  /** Default ISO 4217 currency for formatting (Settings → Company → General can override it). */
-  currency: 'USD',
-
-  /** Real REST API base URL; mock services ignore it. */
-  apiBaseUrl: import.meta.env.VITE_API_URL ?? '/api',
-
-  /** mock (demo data) | bearer (JWT) | cookie (Laravel Sanctum). See BACKEND.md. */
-  auth: {
-    mode: (import.meta.env.VITE_AUTH_MODE ?? 'mock') as AuthMode,
-    csrfUrl: import.meta.env.VITE_CSRF_URL ?? '/sanctum/csrf-cookie',
-  },
-} satisfies AppConfig
+import type { AppConfig, AuthMode } from '@/core/config/types'
+
+/** This panel's settings. The company name and logo come from the setup wizard and Settings. */
+export const appConfig = {
+  name: 'Admin',
+  /** A preset key from src/core/theme/brand.ts, or a custom { color, foreground } pair. */
+  brand: 'indigo',
+
+  workspaces: [{ id: 'main', name: 'Admin' }],
+
+  /** Sidebar group order; labels are translation keys. Modules attach nav items to these ids. */
+  navGroups: [
+    { id: 'overview', label: 'common:nav.groups.overview' },
+    { id: 'catalog', label: 'common:nav.groups.catalog' },
+    { id: 'content', label: 'common:nav.groups.content' },
+    { id: 'system', label: 'common:nav.groups.system' },
+  ],
+
+  /** Turn modules on/off. `npm run new-module` adds them here. */
+  modules: {
+    // fp:modules
+  },
+
+  /** No marketing page: `/` opens the panel. */
+  landing: false,
+
+  /** Built-in areas, off until a project needs them. Setting one to true adds its pages and menu items. */
+  features: {
+    notifications: false,
+    users: false,
+    roles: false,
+    securityPolicies: false,
+    modules: false,
+    integrations: false,
+    auditLog: false,
+    dangerZone: false,
+  },
+
+  /** Default ISO 4217 currency for the setup wizard. */
+  currency: 'USD',
+
+  /** Real REST API base URL. */
+  apiBaseUrl: import.meta.env.VITE_API_URL ?? '/api',
+
+  /** mock (no backend, data stays in this browser) | bearer (JWT) | cookie (Laravel Sanctum). See BACKEND.md. */
+  auth: {
+    mode: (import.meta.env.VITE_AUTH_MODE ?? 'mock') as AuthMode,
+    csrfUrl: import.meta.env.VITE_CSRF_URL ?? '/sanctum/csrf-cookie',
+  },
+} satisfies AppConfig

package/files/locales.ts

@@ -0,0 +1,10 @@
+// fp:locale-imports
+
+/** Translations owned by modules; each key is the module's namespace. */
+export const moduleLocalesEn = {
+  // fp:locale-en
+}
+
+export const moduleLocalesTr: typeof moduleLocalesEn = {
+  // fp:locale-tr
+}

package/files/registry.ts

@@ -0,0 +1,17 @@
+import { appConfig } from '@/app.config'
+import type { AppModule } from '@/core/modules/types'
+// fp:module-imports
+
+/**
+ * Every module in this panel. `npm run new-module` registers new ones here and
+ * enables them in src/app.config.ts → `modules`.
+ */
+export const moduleRegistry = {
+  // fp:module-registry
+} satisfies Record<string, AppModule>
+
+export type ModuleId = keyof typeof moduleRegistry
+
+export const enabledModules: AppModule[] = (Object.keys(moduleRegistry) as ModuleId[])
+  .filter((id) => appConfig.modules[id])
+  .map((id) => moduleRegistry[id])

package/package.json

@@ -1,23 +1,23 @@
-{
-  "name": "create-freakpunch",
-  "version": "0.1.0",
-  "description": "Add the freakpunch admin panel to any project as an fp-admin folder.",
-  "keywords": ["admin", "admin-panel", "dashboard", "react", "vite", "template"],
-  "license": "UNLICENSED",
-  "type": "module",
-  "bin": {
-    "create-freakpunch": "bin/create-freakpunch.mjs"
-  },
-  "files": [
-    "bin",
-    "files",
-    "template"
-  ],
-  "engines": {
-    "node": ">=20.11"
-  },
-  "scripts": {
-    "build:template": "node scripts/build-template.mjs",
-    "prepack": "node scripts/build-template.mjs"
-  }
-}
+{
+  "name": "create-freakpunch",
+  "version": "0.2.0",
+  "description": "Add the freakpunch admin panel to any project as an fp-admin folder.",
+  "keywords": ["admin", "admin-panel", "dashboard", "react", "vite", "template"],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "create-freakpunch": "bin/create-freakpunch.mjs"
+  },
+  "files": [
+    "bin",
+    "files",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build:template": "node scripts/build-template.mjs",
+    "prepack": "node scripts/build-template.mjs"
+  }
+}

package/template/BACKEND.md

@@ -1,86 +1,108 @@
-# Connecting a backend
-
-The panel is a static single-page app. It talks to your backend over HTTP, so the backend can be
-Laravel, Next.js route handlers, Spring Boot or anything else. Until you switch it, everything runs on demo data.
-
-## 1. Settings
-
-Put these in `.env` (build time, not secret: never put secrets in `VITE_` variables).
-
-| Variable | Example | Meaning |
-| --- | --- | --- |
-| `VITE_AUTH_MODE` | `bearer` or `cookie` | Default `mock` (demo data). `bearer`: token in the `Authorization` header. `cookie`: session cookie + `X-XSRF-TOKEN` (Laravel Sanctum). |
-| `VITE_API_URL` | `/api` or `https://api.example.com` | API base URL. |
-| `VITE_CSRF_URL` | `/sanctum/csrf-cookie` | Cookie mode: fetched before login. |
-| `VITE_BASE_PATH` | `/admin/` | Where the panel is served. Keep the trailing slash. Default `/`. |
-| `VITE_DEV_API_PROXY` | `http://localhost:8000` | `npm run dev` only: forwards `VITE_API_URL` calls to your backend. |
-
-## 2. Auth endpoints
-
-```
-POST {API}/auth/login   { email, password }  →  { user, token?, expiresAt? }
-POST {API}/auth/logout
-```
-
-- `token` is required in bearer mode and omitted in cookie mode. `expiresAt` is epoch milliseconds (default 7 days).
-- `user` matches `User` in `src/core/users/types.ts`. `role` must be a role the panel knows: `owner`, `admin`, `editor`, `viewer` or one from `src/app.roles.ts`.
-- Any `401` signs the user out. Errors may return `{ "message": "…" }`, which is shown to the user.
-
-**UI permission checks are not security.** Enforce every permission on the server, using the same strings (`assets.delete`).
-
-## 3. Module endpoints
-
-Modules created with `npm run new-module` switch to these automatically when `VITE_AUTH_MODE` is not `mock`:
-
-```
-GET    {API}/assets?page=1&pageSize=10&search=x&sort=name.asc&status=active
-GET    {API}/assets/:id
-POST   {API}/assets
-PUT    {API}/assets/:id
-DELETE {API}/assets/:id
-```
-
-Pages are 1-based. List responses may use any of these shapes (`src/core/api/rest.ts`):
-
-```jsonc
-{ "items": [], "total": 0, "page": 1, "pageSize": 10 }                      // freakpunch
-{ "data": [], "total": 0, "current_page": 1, "per_page": 10 }               // Laravel paginate()
-{ "data": [], "meta": { "total": 0, "current_page": 1, "per_page": 10 } }   // Laravel API resource
-{ "content": [], "totalElements": 0, "number": 0, "size": 10 }              // Spring Data Page
-```
-
-Spring Data expects a 0-based `page` in the request, and a backend may use other parameter names. For those,
-or for module-specific calls, write the method by hand in the module's `api/*.service.ts` using `http`.
-
-## 4. Built-in areas that are still demo data
-
-These services run on mock data in every auth mode. For each one you use, implement its interface with
-`http` and change its one `export const xService = …` line. Switch off the rest in `src/app.config.ts`
-→ `features` (their pages and menu items disappear). Don't leave a demo area visible on a real site.
-
-| Area | Service | Feature flag |
-| --- | --- | --- |
-| Users, profile | `src/core/users/users.service.ts` | `users` (Profile always shows) |
-| Company settings, branding, security policies | `src/core/company/company.service.ts` | `securityPolicies`, `dangerZone` (General and Branding always show) |
-| Audit log | `src/core/audit/audit.service.ts` | `auditLog` |
-| Notifications | `src/core/notifications/notifications.service.ts` | `notifications` |
-| Integrations, webhooks, API keys | `src/pages/settings/company/integrations/integrations.service.ts` | `integrations` |
-| Password, 2FA, sessions | `src/pages/settings/account/account.service.ts` | none |
-
-Updating a core service means editing a freakpunch file, which `npm run check` reports. Until there is a
-built-in way to replace them from a project, fix them in freakpunch itself so every project benefits.
-
-## 5. Deploying
-
-`npm run build` writes static files to `dist/`. Any URL inside the panel must fall back to `index.html`.
-
-**Subdomain (`admin.example.com`):** deploy `dist/` anywhere static, or use the included `Dockerfile`.
-
-**Same domain (`example.com/admin`):** set `VITE_BASE_PATH=/admin/` and build, then:
-
-- *Laravel / PHP:* copy `dist/` to `public/admin/` and rewrite unknown `/admin/*` paths to `public/admin/index.html`.
-- *Next.js:* copy `dist/` to `public/admin/` and add a rewrite from `/admin/:path*` to `/admin/index.html`.
-- *nginx:* `location /admin/ { alias /var/www/admin/; try_files $uri $uri/ /admin/index.html; }`
-
-Same-domain hosting is the simplest route for cookie mode, because it avoids cross-site cookie and CORS setup.
-If the host project has its own `tsconfig.json`, add `fp-admin` to its `exclude`.
+# Connecting a backend
+
+The panel is a static single-page app. It talks to your backend over HTTP, so the backend can be
+Laravel, Next.js route handlers, Spring Boot or anything else. Until you switch it, everything runs on demo data.
+
+## 1. Settings
+
+Put these in `.env` (`.env.development` holds this panel's own dev port) (build time, not secret: never put secrets in `VITE_` variables).
+
+| Variable | Example | Meaning |
+| --- | --- | --- |
+| `VITE_AUTH_MODE` | `bearer` or `cookie` | Default `mock` (demo data). `bearer`: token in the `Authorization` header. `cookie`: session cookie + `X-XSRF-TOKEN` (Laravel Sanctum). |
+| `VITE_API_URL` | `/api` or `https://api.example.com` | API base URL. |
+| `VITE_CSRF_URL` | `/sanctum/csrf-cookie` | Cookie mode: fetched before login. |
+| `VITE_BASE_PATH` | `/admin/` | Where the panel is served. Keep the trailing slash. Default `/`. |
+| `VITE_DEV_API_PROXY` | `http://localhost:8000` | `npm run dev` only: forwards `VITE_API_URL` calls to your backend. |
+
+## 2. Auth endpoints
+
+```
+POST {API}/auth/login   { email, password }  →  { user, token?, expiresAt? }
+POST {API}/auth/logout
+```
+
+- `token` is required in bearer mode and omitted in cookie mode. `expiresAt` is epoch milliseconds (default 7 days).
+- `user` matches `User` in `src/core/users/types.ts`. `role` must be a role the panel knows: `owner`, `admin`, `editor`, `viewer` or one from `src/app.roles.ts`.
+- Any `401` signs the user out. Errors may return `{ "message": "…" }`, which is shown to the user.
+
+**UI permission checks are not security.** Enforce every permission on the server, using the same strings (`orders.delete`).
+
+## 3. First-run setup
+
+Without a backend the setup wizard keeps the Owner account in this browser (salted hash, not real security),
+so it is for building only. With a backend it uses:
+
+```
+GET  {API}/setup/status  →  { needsSetup: boolean }
+POST {API}/setup         →  same response as /auth/login
+```
+
+```jsonc
+{
+  "company": { "name": "", "language": "en", "timeZone": "Europe/Istanbul", "currency": "USD" },
+  "admin": { "firstName": "", "lastName": "", "email": "", "password": "" },
+  "branding": { "brand": "indigo", "logo": "data:image/png;base64,…" }   // logo is optional
+}
+```
+
+**`POST /setup` must return 403 once an Owner exists**, or anyone could take over the panel. Check that, validate the
+password and hash it on the server. If you create the first admin another way (seeder, CLI), skip these
+endpoints: when `/setup/status` fails, the panel goes straight to login.
+
+## 4. Module endpoints
+
+Modules created with `npm run new-module` switch to these automatically when `VITE_AUTH_MODE` is not `mock`:
+
+```
+GET    {API}/orders?page=1&pageSize=10&search=x&sort=name.asc&status=active
+GET    {API}/orders/:id
+POST   {API}/orders
+PUT    {API}/orders/:id
+DELETE {API}/orders/:id
+```
+
+Pages are 1-based. List responses may use any of these shapes (`src/core/api/rest.ts`):
+
+```jsonc
+{ "items": [], "total": 0, "page": 1, "pageSize": 10 }                      // freakpunch
+{ "data": [], "total": 0, "current_page": 1, "per_page": 10 }               // Laravel paginate()
+{ "data": [], "meta": { "total": 0, "current_page": 1, "per_page": 10 } }   // Laravel API resource
+{ "content": [], "totalElements": 0, "number": 0, "size": 10 }              // Spring Data Page
+```
+
+Spring Data expects a 0-based `page` in the request, and a backend may use other parameter names. For those,
+or for module-specific calls, write the method by hand in the module's `api/*.service.ts` using `http`.
+
+## 5. Built-in areas that still save locally
+
+These services keep their data in the browser in every auth mode, and they start empty. Most are switched off in a new panel. For each one you use, implement its interface with
+`http` and change its one `export const xService = …` line. Switch off the rest in `src/app.config.ts`
+→ `features` (their pages and menu items disappear). Don't leave an unconnected area on for a real site.
+
+| Area | Service | Feature flag |
+| --- | --- | --- |
+| Users, profile | `src/core/users/users.service.ts` | `users` (Profile always shows) |
+| Company settings, branding, security policies | `src/core/company/company.service.ts` | `securityPolicies`, `dangerZone` (General and Branding always show) |
+| Audit log | `src/core/audit/audit.service.ts` | `auditLog` |
+| Notifications | `src/core/notifications/notifications.service.ts` | `notifications` |
+| Integrations, webhooks, API keys | `src/pages/settings/company/integrations/integrations.service.ts` | `integrations` |
+| Password, 2FA, sessions | `src/pages/settings/account/account.service.ts` | none |
+
+Updating a core service means editing a freakpunch file, which `npm run check` reports. Until there is a
+built-in way to replace them from a project, fix them in freakpunch itself so every project benefits.
+
+## 6. Deploying
+
+`npm run build` writes static files to `dist/`. Any URL inside the panel must fall back to `index.html`.
+
+**Subdomain (`admin.example.com`):** deploy `dist/` anywhere static, or use the included `Dockerfile`.
+
+**Same domain (`example.com/admin`):** set `VITE_BASE_PATH=/admin/` and build, then:
+
+- *Laravel / PHP:* copy `dist/` to `public/admin/` and rewrite unknown `/admin/*` paths to `public/admin/index.html`.
+- *Next.js:* copy `dist/` to `public/admin/` and add a rewrite from `/admin/:path*` to `/admin/index.html`.
+- *nginx:* `location /admin/ { alias /var/www/admin/; try_files $uri $uri/ /admin/index.html; }`
+
+Same-domain hosting is the simplest route for cookie mode, because it avoids cross-site cookie and CORS setup.
+If the host project has its own `tsconfig.json`, add `fp-admin` to its `exclude`.

package/template/CLAUDE.md

@@ -5,20 +5,23 @@ New features are **modules** that look and behave exactly like the rest of the p
 look, layout or component style: reuse what exists and follow `design/`.
 
 
-Services return mock data until a backend is connected: see `BACKEND.md`.
+A new panel is deliberately empty: no modules, no sample data, and optional built-in pages switched off in
+`src/app.config.ts` → `features`. On first open, a setup wizard (`/setup`) creates the company and the Owner.
+Until a backend is connected, data stays in the browser: see `BACKEND.md`.
 
 ## Rules for AI agents
 
 1. Read this file and `design/` before changing anything.
 2. New feature = new module: `npm run new-module -- <id> --en "Label" --tr "Etiket"`, then replace its sample
-   fields. Use `src/modules/products` as the reference for detail pages and richer forms.
+   fields. The generated list, detail and form pages are the reference for new pages.
 3. **Only change project files:** `src/modules/**`, `src/app.config.ts`, `src/app.roles.ts`, `public/**`.
    Everything else (`src/core`, `src/pages`, `src/components/ui`, `src/locales`, `src/index.css`, `design/`,
    `tools/`) belongs to freakpunch and is replaced by updates. If something is missing there, say so to the user
    instead of editing or copying it.
 4. Every string in both EN and TR. Tokens only. Shared components first (`design/COMPONENTS.md`).
 5. Gate every route and action with a permission; add project-specific ones in `src/app.roles.ts`.
-6. `npm run check` must pass before you finish.
+6. Never add sample or placeholder data to a panel unless the user asks for it.
+7. `npm run check` must pass before you finish.
 
 ## Commands
 
@@ -27,7 +30,7 @@ npm run dev      # Vite dev server
 npm run build    # tsc -b && vite build (must pass with no errors)
 npm run lint     # oxlint (must pass with no errors or warnings)
 npm run check    # design rules + lint + build: run this before finishing any change
-npm run new-module -- assets --en "Assets" --tr "Zimmet" [--group content]
+npm run new-module -- orders --en "Orders" --tr "Siparişler" [--group content]
 npm run fp:update  # installed copies: refresh freakpunch's files (add -- --dry-run to preview)
 docker build -t freakpunch . && docker run --rm -p 8080:80 freakpunch
 ```
@@ -71,6 +74,7 @@ src/
                 require-auth (→ /login?redirect=…), roles, permissions (role → permission map),
                 can (Can, useCan, usePermissions), require-permission (route guard), dev-role-switcher
     users/      user model, mock team (one demo user per role), users.service, hooks
+    setup/      first-run wizard service (local or POST /setup) + SetupGate
     company/    company settings (general, branding, security policies), password-policy, hooks
     audit/      audit.service (record + list), hooks
     notifications/ event catalog + types, notifications.service (feed + settings, mock, per user),
@@ -90,14 +94,15 @@ src/
     lib/        storage (namespaced localStorage), format (createFormatters, initials), phone, csv
   modules/
     registry.ts            ← every available module; app.config.ts decides which are on
-    products/              ← example module (copy this to start a new one)
+    locales.ts             ← registers each module's translations
+    orders/                ← what `npm run new-module` generates
       index.ts             module definition: nav, routes, quick actions (labels = i18n keys, permissions)
       locales/             en.ts + tr.ts (namespace = module id)
       types.ts             entity types + Zod form schema
-      api/                 products.service.ts (interface + mock impl), products.mock.ts (seed)
+      api/                 orders.service.ts (interface + mock impl), orders.mock.ts (seed)
       hooks.ts             TanStack Query keys + hooks
       components/  pages/
-  pages/                   core pages: landing, login, dashboard/, not-found, no-access
+  pages/                   core pages: setup, login, dashboard/, not-found, no-access
     settings/              settings-routes, settings-nav, settings-layout (left sub-nav),
                            account/ (profile, security, notifications, preferences),
                            company/ (general, branding, users, roles, security policies, modules,
@@ -169,7 +174,7 @@ Four built-in roles (`core/auth/roles.ts`), plus project-defined ones from `src/
 demoted, only transfer ownership), **admin** (everything except the danger zone; can't edit the Owner),
 **editor** (create/edit/delete in modules, no company settings), **viewer** (read-only).
 - `core/auth/permissions.ts` is the single role → permission map. Permission strings are
-  `<resource>.<action>` (`products.delete`, `settings.company.edit`, `users.manage`,
+  `<resource>.<action>` (`orders.delete`, `settings.company.edit`, `users.manage`,
   `company.transfer`) and are meant to be reused 1:1 as Spring Security authorities. Every registered
   module automatically gets `<id>.view|create|edit|delete`.
 - UI: `useCan('x')` / `usePermissions().can` / `<Can permission="x">` (hide, or render-prop to
@@ -178,7 +183,7 @@ demoted, only transfer ownership), **admin** (everything except the danger zone;
   Owner rules for user management: `canManageUser(actor, target)`.
 - **UI checks are not security.** The backend must enforce every permission (the mock services
   enforce the Owner rules the same way a backend should).
-- Demo users (any password): owner@, admin@, editor@, viewer@freakpunch.site. In `npm run dev` the top
+- In `npm run dev` the top
   bar has a role switcher (`DevRoleSwitcher`, code-split behind `import.meta.env.DEV`, absent from
   production builds).
 
@@ -207,7 +212,7 @@ components**: page titles, labels, `aria-label`, `placeholder`, toasts, empty st
   (modules: `locales/` and `src/modules/locales.ts`), use `useTranslation(['<ns>', 'common'])` and `t('common:actions.save')`
   for shared strings.
 - Config-like data (nav labels, crumbs, quick actions, nav groups, workspace plans) stores
-  `I18nKey` values (`'products:nav'`) and is translated with `useAnyT()`.
+  `I18nKey` values (`'orders:nav'`) and is translated with `useAnyT()`.
 - Zod messages are keys: `vmsg('validation.minChars', { min: 2 })`; render errors with
   `FormFieldError` (translates at render time).
 - Formatting: `const fmt = useFormat()` → `fmt.currency/number/date/dateTime/relative/…` (Intl with the

package/template/design/COMPONENTS.md

@@ -90,7 +90,7 @@ Add more with `npx shadcn@latest add @sortui/<name> -y`, then rewrite the `cn` i
 ### Feedback
 
 - **`useConfirm()`** (`core/components/confirm-dialog.tsx`): promise-based confirm.
-  `destructive: true` for irreversible actions, `typeToConfirm: 'acme'` to require typing a value
+  `destructive: true` for irreversible actions, `typeToConfirm: companyName` to require typing a value
   (danger zone).
 - **`toast`** from `sonner`: success after a save, error with the message on failure,
   `toast.promise` for row actions. Messages are translated.