create-mithaq 0.0.0-stage → 0.2.0

package/template/apps/asas-tanstack/src/server.ts

@@ -0,0 +1,26 @@
+import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
+import type { ScreenClient } from 'mithaq/admin'
+import { checkComponents } from 'mithaq-admin/components.tsx'
+import { components } from './components.ts'
+import { withQuietAbort } from './quiet-abort.ts'
+
+// Every screen this app serves, checked against its components map as it starts, so a field whose kind has no
+// control fails the start, naming the kind and the field, and never reaches a page. Read on the server alone,
+// since a screen.json names every field of the screen.
+for (const client of Object.values(import.meta.glob<ScreenClient>('./routes/(screens)/*/screen.json', { eager: true, import: 'default' }))) {
+  checkComponents({ client, components })
+}
+
+// A production start connects once before handing on any request, and `connect()` refuses to
+// start while a migration is unapplied; a refused start exits 1. NODE_ENV is read off `process`
+// so Vite cannot replace it at build time, and a built server started without
+// `NODE_ENV=production` never connects, which would push into the deploy's database.
+const { env } = process
+if (env.NODE_ENV === 'production') {
+  await (await import('asas')).asas.connect().catch((error: unknown) => {
+    console.error(error)
+    process.exit(1)
+  })
+}
+
+export default createServerEntry({ fetch: (request: Request) => handler.fetch(withQuietAbort(request)) })

package/template/apps/asas-tanstack/src/slide.ts

@@ -0,0 +1,22 @@
+/**
+ * The provider's own session read, which refreshes a session past its `updateAge` and forwards the cookie.
+ * Run it before the actor is resolved: a read that refreshes the row first leaves this one nothing due.
+ */
+export const slide = async ({
+  strategies,
+  headers,
+  setResponseHeader,
+}: {
+  strategies: readonly unknown[]
+  headers: Headers
+  setResponseHeader: (name: 'set-cookie', value: string[]) => void
+}) => {
+  const cookies: string[] = []
+  for (const strategy of strategies) {
+    const read = (strategy as { server?: { api?: { getSession?: (args: object) => Promise<{ headers: Headers }> } } }).server?.api?.getSession
+    if (read) cookies.push(...(await read({ headers, returnHeaders: true })).headers.getSetCookie())
+  }
+  // Set once with every strategy's cookies: a second set replaces the first.
+  if (cookies.length) setResponseHeader('set-cookie', cookies)
+}
+// mithaq-admin 2d3ab739c92c6c2b397041b76bf4b23b2902b7a2 bc0221e1088103f8638e0333b84aafb6b326e3991a187ced198bce2d090ecbe9

package/template/apps/asas-tanstack/src/start.ts

@@ -0,0 +1,57 @@
+import { createCsrfMiddleware, createMiddleware, createStart } from '@tanstack/react-start'
+import { dirOf, localeCookie, localeOf } from './copy.ts'
+
+// The locale is resolved once per request, before any route runs, because the document's `lang`
+// and `dir` are written before a loader exists. Nothing here imports
+// `@tanstack/react-start/server`: both builds reach this entry, so it would put server code in the client.
+
+/** No `decodeURIComponent`: the only caller refuses every value but two ASCII names. */
+const cookieOf = (header: string | null, name: string): string | undefined =>
+  header
+    ?.split(';')
+    .map((one) => one.trim().split('='))
+    .find(([key]) => key === name)
+    ?.slice(1)
+    .join('=')
+
+/**
+ * The request's locale and direction, off the `locale` cookie alone: `Accept-Language` is not a
+ * choice the viewer made.
+ */
+const locale = createMiddleware({ type: 'request' }).server(({ request, next }) => {
+  const asked = localeOf(cookieOf(request.headers.get('cookie'), localeCookie))
+  return next({ context: { locale: asked, dir: dirOf(asked) } })
+})
+
+/** Refuses a server function reached from outside the page; page renders and `/api` are untouched. */
+const csrf = createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' })
+
+/**
+ * `/admin` answers a 308 to the same path under `/dashboard`, so a saved link still lands with its
+ * method and body. The location is a path, never a URL, so the request's host header never reaches it.
+ */
+const moved = createMiddleware({ type: 'request' }).server(({ request, next }) => {
+  const url = new URL(request.url)
+  if (!/^\/admin(\/|$)/.test(url.pathname)) return next()
+  return new Response(null, { status: 308, headers: { location: `/dashboard${url.pathname.slice('/admin'.length)}${url.search}` } })
+})
+
+/**
+ * Only this origin may frame this app's pages, so no other site can lay it under its own page and
+ * steer a click. First, so it covers every other middleware's answer; rebuilt, since a redirect's
+ * headers are immutable.
+ */
+const framing = createMiddleware({ type: 'request' }).server(async ({ next }) => {
+  const result = await next()
+  const answer = result.response
+  const html = answer.headers.get('content-type')?.startsWith('text/html') === true
+  if (answer.headers.has('content-security-policy') && !html) return result
+  const headers = new Headers(answer.headers)
+  if (!headers.has('content-security-policy')) headers.set('content-security-policy', "frame-ancestors 'self'")
+  // No HTML answer is cached: each is drawn for one request's session and locale, so a page
+  // someone signed out of must not come back from the cache on Back.
+  if (html) headers.set('cache-control', 'no-store')
+  return { ...result, response: new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers }) }
+})
+
+export const startInstance = createStart(() => ({ requestMiddleware: [framing, moved, csrf, locale] }))

package/template/apps/asas-tanstack/src/styles.css

@@ -0,0 +1,163 @@
+/* Theme copied wholesale from tanstack-business:apps/web/src/styles.css:
+   imports, custom-variant, :root and .dark variables, the @theme inline
+   block and the @layer base rules, unchanged. Only the @source line below
+   differs, pointing at this project's template instead of TB's monorepo.
+   Tailwind finds this app's own files, an ejected `src/components/mithaq`
+   among them, without one. */
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+/* The admin's pieces in node_modules, which Tailwind never scans on its own. */
+@import 'mithaq-admin/source.css';
+@import '@fontsource-variable/raleway';
+@import '@fontsource/ibm-plex-sans-arabic';
+
+/* The project's own shells, pages and components, which the screens load
+   (the language package's `src/ui/app-shell.tsx`), in every package of the project.
+   Named by their folder, which every package manager leaves where it is, since
+   each links the package elsewhere. */
+@source '../../../templates';
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.147 0.004 49.25);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.147 0.004 49.25);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.147 0.004 49.25);
+  --primary: oklch(0.216 0.006 56.043);
+  --primary-foreground: oklch(0.985 0.001 106.423);
+  --secondary: oklch(0.97 0.001 106.424);
+  --secondary-foreground: oklch(0.216 0.006 56.043);
+  --muted: oklch(0.97 0.001 106.424);
+  --muted-foreground: oklch(0.553 0.013 58.071);
+  --accent: oklch(0.97 0.001 106.424);
+  --accent-foreground: oklch(0.216 0.006 56.043);
+  /* Darker than the preset's red 600, which is 4.0:1 on the pale red fill the destructive button and menu item draw it on and 3.3:1 on its hover; this is 5.9:1 on the fill and 4.9:1 on the hover. */
+  --destructive: oklch(0.48 0.2 27.5);
+  --border: oklch(0.923 0.003 48.717);
+  --input: oklch(0.923 0.003 48.717);
+  --ring: oklch(0.709 0.01 56.259);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0.001 106.423);
+  --sidebar-foreground: oklch(0.147 0.004 49.25);
+  --sidebar-primary: oklch(0.216 0.006 56.043);
+  --sidebar-primary-foreground: oklch(0.985 0.001 106.423);
+  --sidebar-accent: oklch(0.97 0.001 106.424);
+  --sidebar-accent-foreground: oklch(0.216 0.006 56.043);
+  --sidebar-border: oklch(0.923 0.003 48.717);
+  --sidebar-ring: oklch(0.709 0.01 56.259);
+}
+
+.dark {
+  --background: oklch(0.147 0.004 49.25);
+  --foreground: oklch(0.985 0.001 106.423);
+  --card: oklch(0.216 0.006 56.043);
+  --card-foreground: oklch(0.985 0.001 106.423);
+  --popover: oklch(0.216 0.006 56.043);
+  --popover-foreground: oklch(0.985 0.001 106.423);
+  --primary: oklch(0.923 0.003 48.717);
+  --primary-foreground: oklch(0.216 0.006 56.043);
+  --secondary: oklch(0.268 0.007 34.298);
+  --secondary-foreground: oklch(0.985 0.001 106.423);
+  --muted: oklch(0.268 0.007 34.298);
+  --muted-foreground: oklch(0.709 0.01 56.259);
+  --accent: oklch(0.268 0.007 34.298);
+  --accent-foreground: oklch(0.985 0.001 106.423);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.553 0.013 58.071);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.216 0.006 56.043);
+  --sidebar-foreground: oklch(0.985 0.001 106.423);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0.001 106.423);
+  --sidebar-accent: oklch(0.268 0.007 34.298);
+  --sidebar-accent-foreground: oklch(0.985 0.001 106.423);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.553 0.013 58.071);
+}
+
+@theme inline {
+  --font-sans: 'IBM Plex Sans Arabic', 'Raleway', sans-serif;
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply font-sans bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}
+
+/* Fix: Make dropdown menu roots not affect layout */
+[data-slot='dropdown-menu'] {
+  display: contents;
+}
+
+/* Fix: Ensure sidebar menu action dropdowns don't affect layout */
+/* Fix: Ensure sidebar menu action dropdowns don't affect layout
+   Note: This was causing issues with SidebarMenuAction positioning. Removing display: contents from trigger.
+*/
+/* [data-sidebar='menu-item'] > [data-slot='dropdown-menu-trigger'] {
+  display: contents;
+} */
+
+/* Fix: Ensure sidebar footer content spans full width */
+[data-sidebar='footer'] [data-slot='dropdown-menu-trigger'] {
+  width: 100%;
+}

package/template/apps/asas-tanstack/src/theme.ts

@@ -0,0 +1,5 @@
+/**
+ * Where the chosen theme is remembered. The React provider and the blocking head script both
+ * read it, and disagreeing would flash the wrong theme on first paint.
+ */
+export const themeStorageKey = 'vite-ui-theme'

package/template/apps/asas-tanstack/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "lib": ["es2024", "dom", "dom.iterable"],
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "types": ["node", "vite/client"],
+    "paths": { "@/*": ["./src/*"], "mithaq-admin/*": ["./src/components/mithaq/*", "./node_modules/mithaq-admin/registry/*"] }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "vite.config.ts", "../../templates/mithaq/src/ui/*.tsx", "../../templates/asas/src/ui-*/*.tsx", "../../templates/features/*/*/ui/*.tsx"]
+}

package/template/apps/asas-tanstack/vite.config.ts

@@ -0,0 +1,34 @@
+import tailwindcss from '@tailwindcss/vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+import { mithaqAdmin } from 'mithaq/vite'
+import { defineConfig } from 'vite'
+import { fileURLToPath } from 'node:url'
+
+export default defineConfig({
+  // An alias rather than `resolve.tsconfigPaths`, which applies only to files the nearest
+  // tsconfig claims: the project's shells in the language package's `src/ui/` import `@/` too.
+  // `^@/` and not `@`, so `@tanstack/*` is left alone.
+  resolve: { alias: [{ find: /^@\//, replacement: fileURLToPath(new URL('./src/', import.meta.url)) }] },
+  plugins: [
+    tailwindcss(),
+    // A file under this folder takes the place of mithaq-admin's file of the same name, for every importer.
+    mithaqAdmin(fileURLToPath(new URL('./src/components/mithaq/', import.meta.url))),
+    // `mithaq generate screens` writes `types.ts` and `files.ts` beside the route files, and neither is a route.
+    tanstackStart({ router: { routeFileIgnorePattern: '^(files|types)\\.ts$' } }),
+    viteReact(),
+  ],
+  // Behind the proxy that routes by Host: bound to the loopback address it targets, and answering
+  // the public name in BETTER_AUTH_URL, which Vite refuses in a Host header unless named here.
+  preview: { host: '127.0.0.1', allowedHosts: process.env.BETTER_AUTH_URL ? [new URL(process.env.BETTER_AUTH_URL).hostname] : [] },
+  environments: {
+    ssr: {
+      // `asas` and `mithaq` stay external: the drizzle adapter imports `drizzle-kit/api-postgres`
+      // behind a `webpackIgnore` comment Vite does not honour, and bundled, the build fails on
+      // drizzle's optional peers. The dev server reads `resolve.external`, the build reads
+      // `build.rollupOptions.external`, so both are set.
+      resolve: { external: ['asas', 'mithaq'] },
+      build: { rollupOptions: { external: [/^asas$/, /^mithaq(\/|$)/] } },
+    },
+  },
+})

package/template/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "workspaces": [
+    "packages/mithaq",
+    "packages/features/*",
+    "packages/asas",
+    "apps/*"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.12.3"
+  }
+}

package/template/templates/asas/.claude/skills/add-field/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: add-field
+description: Add, change or remove a field of an existing kayan in this mithaq project and write the migration for it. Use when asked to add a column, change a field's kind or rules, or write a migration.
+---
+
+# Add a field and its migration
+
+The guide is "A field" under "Add a feature to an existing kayan" in `README.md`, and "Migrations" in `AGENTS.md`. The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root: every kind and rule is in its `docs/packages/mithaq/README.md`, and `mithaq migrate` in its `docs/packages/mithaq/src/asas/cli/README.md`.
+
+1. Edit `fields` in the kayan's file. A kind or rule the language does not hold changes the vocabulary: stop and ask the developer.
+2. A new `required` field on a table with rows needs a literal `defaultValue`, or goes in without `required` and becomes required in a later migration.
+3. Add the field to the pages that should draw it, and to the roles' grants when they list fields one by one (`<kayan>.fields.<field>`).
+4. From `packages/asas/`, with `DATABASE_URL` pointing at a database built from the migrations (never a pushed one; `AGENTS.md` "Migrations" says how to build one):
+
+   ```sh
+   bunx mithaq generate screens      # when a page draws it
+   bunx mithaq generate messages     # then fill every empty translation
+   bunx mithaq migrate --name <slug>
+   bunx mithaq generate --check
+   ```
+
+5. When `mithaq migrate` stops and asks for an answer in `mithaq.hints.json`, it is a rename or a drop. A drop deletes rows: ask the developer before you answer it.
+6. From the project root, `bunx --package typescript tsc -p .` and the same with `-p` naming each app.
+
+Commit the migration folder.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/template/templates/asas/.claude/skills/add-kayan/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: add-kayan
+description: Add a kayan, one data type with its table, operations, access and admin pages, to this mithaq project. Use when asked for a new entity, table, resource or list in the dashboard.
+---
+
+# Add a kayan
+
+The steps are "Adding a kayan" in `AGENTS.md`, and the guide's worked example is "Add a kayan" in `README.md`. The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root; its `docs/packages/mithaq/README.md` lists every kind and rule a field can take.
+
+1. Ask, unless the request says: does each row belong to one organization (place `organization`, the usual answer) or does every organization share it?
+2. Follow `AGENTS.md` "Adding a kayan", copying `packages/features/tags/`. Use only the kinds and rules the language holds; a new one changes the vocabulary, so stop and ask the developer.
+3. Grant its keys to the roles that use it, as step 4 there says. A kayan no role is granted answers no one.
+4. From `packages/asas/`, with `DATABASE_URL` pointing at a database built from the migrations (never a pushed one; `AGENTS.md` "Migrations" says how to build one):
+
+   ```sh
+   bunx mithaq generate screens      # when a screen draws it
+   bunx mithaq generate messages     # then fill every empty translation
+   bunx mithaq migrate --name add_<name>
+   bunx mithaq generate --check
+   ```
+
+5. From the project root, `bunx --package typescript tsc -p .` and `bunx --package typescript tsc -p apps/asas-tanstack` (and `apps/asas-backoffice` when the project has it).
+
+Commit the migration folder. Never edit a file whose first line reads ``// Written by `mithaq <command>` ``; run the command again.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/template/templates/asas/.claude/skills/eject-admin-piece/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: eject-admin-piece
+description: Change how the admin draws something in this mithaq project, by replacing a control, cell or node in the components map or by ejecting a mithaq-admin piece. Use when asked to restyle or change an admin control, list, form, shell or page piece.
+---
+
+# Change an admin piece
+
+The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root. The guide is the admin's, its `docs/packages/mithaq-admin/README.md` ("Add or replace a control", "Replace a node", "Eject a piece"), and `eject` in its `docs/packages/mithaq/src/asas/cli/README.md`.
+
+1. Reach for the components map first: a control, a cell or a node is replaced in the app's `src/components.ts` without ejecting anything.
+2. Otherwise eject the piece, in the app that draws it (`apps/asas-tanstack` or `apps/asas-backoffice`):
+
+   ```sh
+   bunx mithaq eject <item>          # an unknown name lists every item
+   ```
+
+   It writes the piece into `src/components/mithaq/`, drawn in place of the package's, and names any shadcn primitive or npm package to add. Restart the dev server.
+3. Edit the ejected file in place; it is the project's now. Keep its last line, the `// mithaq-admin` marker, which `upgrade --check` reads.
+4. Check, in the app:
+
+   ```sh
+   bunx mithaq upgrade --check       # the held files against the installed mithaq-admin
+   bunx --package typescript tsc -p .
+   ```
+
+To go back to the package's piece, delete the file, or run `bunx mithaq eject --prune`, which deletes every ejected file nobody edited.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/template/templates/asas/.claude/skills/upgrade-mithaq/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: upgrade-mithaq
+description: Upgrade this project to a newer mithaq and mithaq-admin. Use when asked to update or upgrade mithaq, or when the installed version is behind the one a task needs.
+---
+
+# Upgrade mithaq
+
+Run each command from the project root. The installed mithaq, `$M` below, is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root, as in a project made with `--layout single`; each block finds it first.
+
+1. Before you install, save the developer's own edits to the skills this version shipped. Skip this when `$M/skills` does not exist: that version shipped none.
+
+   ```sh
+   M=packages/asas/node_modules/mithaq; [ -d "$M" ] || M=node_modules/mithaq
+   ls "$M/skills" > /tmp/mithaq-shipped-skills
+   for skill in $(cat /tmp/mithaq-shipped-skills); do diff -ru "$M/skills/$skill" ".claude/skills/$skill"; done > /tmp/mithaq-skill-edits.diff
+   ```
+
+2. Set `mithaq` and `mithaq-admin` to the same new version in every `package.json` that names them (`npm:@drhomet/mithaq@<version>` and `npm:@drhomet/mithaq-admin@<version>`), and install.
+3. Read "Upgrading" in the new version's project guide, `$M/docs/templates/asas/README.md`: it says what a project made before each round changes. Apply every note for the rounds since this project's version, in order. A note that changes the vocabulary or drops data needs the developer's word first.
+4. Replace the shipped skills with the new version's. A skill the old version shipped and the new one does not is deleted; a skill the developer wrote, which no version shipped, is left alone.
+
+   ```sh
+   M=packages/asas/node_modules/mithaq; [ -d "$M" ] || M=node_modules/mithaq
+   for skill in $(cat /tmp/mithaq-shipped-skills 2>/dev/null); do rm -rf ".claude/skills/$skill"; done
+   mkdir -p .claude/skills && cp -R "$M/skills/." .claude/skills/
+   git status --short -- .claude/skills
+   git diff -- .claude/skills
+   ```
+
+   Then put back each of the developer's edits in `/tmp/mithaq-skill-edits.diff` that the new text lost, and ask the developer where an edit no longer fits the new text.
+5. From `packages/asas/`, with `DATABASE_URL` exported, run `bunx mithaq generate --check`. It also checks the lock and the migrations; rerun `generate auth`, `screens` or `messages` as it says.
+6. Run `bunx mithaq upgrade --check` in each folder holding a `components.json`: `packages/mithaq`, `apps/asas-tanstack` and, when the project has it, `apps/asas-backoffice`. Each file it reports as `differs` came from mithaq-admin: diff it against the package's and merge by hand, keeping the project's own edits.
+7. From the project root, `bunx --package typescript tsc -p .` and the same with `-p` naming each app, then build and start each app once.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it.

package/template/templates/asas/.env.example

@@ -0,0 +1,33 @@
+# The settings a development machine runs with; every variable is described in
+# README.md, "Environment variables".
+# create-mithaq writes a copy as `.env` here, in `apps/asas-tanstack` and in
+# `apps/asas-backoffice`, with the same fresh secrets in each. The `seed` script
+# and the apps' Vite read it, and `node --env-file=.env` does; the `mithaq`
+# bin does not. A variable the shell already sets wins.
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/mithaq
+# 32 characters at least. Unset, every POST under /api/auth/local answers 503.
+LOCAL_AUTH_SECRET=
+BETTER_AUTH_SECRET=
+BETTER_AUTH_URL=http://localhost:5173
+BACKOFFICE_URL=http://localhost:5174
+# The account `bun run dev:setup` makes on a fresh database on this machine:
+# the owner of an organization and, with the backoffice console, its super_admin.
+# A development value only: dev:setup refuses any other database.
+DEV_ADMIN_EMAIL=admin@example.com
+DEV_ADMIN_PASSWORD=dev-admin-password
+# The backoffice console's first administrator, and with one organization or
+# none the app's first owner, are made only with this code, entered on
+# /auth/create-first-user or /auth/first-run. Set a random value of 32
+# characters or more before the first start outside development; a shorter
+# one counts as unset. `vite dev` on this machine asks for none.
+SETUP_CODE=
+# The mailer: both, or neither. Without them a password reset is offered only
+# in development, where the link is written to the server log, and an open
+# sign-up refuses to start in production.
+# RESEND_API_KEY=
+# MAIL_FROM=Asas <mail@example.com>
+# Required in production; development defaults them, the secret to a new
+# random one on every start.
+# STORAGE_SECRET=
+# STORAGE_PREFIX=mithaq/asas
+# STORAGE_ADAPTER=local

package/template/templates/asas/AGENTS.md

@@ -0,0 +1,101 @@
+# Working in a mithaq project
+
+This project is built on mithaq. Each data type is a kayan (an entity), declared once with `defineKayan`; its table, input schema, operations, access and admin pages all follow from that one declaration. The arkan (singular rukn, a pillar) in the language, `packages/mithaq/src/mithaq.ts`, bring the kinds and rules a field can use. `buildAsas` in `packages/asas/src/asas.ts` builds the asas, the runtime that serves every kayan.
+
+Run every `mithaq` command from `packages/asas/` unless it says otherwise. `README.md` beside this file is the full guide, with the steps and examples behind each section here. In a project made with `--layout single`, every folder below is one package: `packages/mithaq/src/` and `packages/asas/src/` are both `src/`, and `packages/features/<feature>/` is `src/features/<feature>/`.
+
+The guides of the installed mithaq ship in its package, at their paths in the mithaq repository, under `node_modules/mithaq/docs/` (from `packages/asas/`, the nearest `node_modules` holding `mithaq`: its own or the root's). They match the installed version, so read them before GitHub, whose `main` describes the next release: `docs/packages/mithaq/README.md` is the language reference, `docs/packages/mithaq/src/asas/cli/README.md` the `mithaq` command, `docs/packages/mithaq/src/asas/runner/README.md` tenancy, `docs/packages/mithaq/src/drizzle/README.md` migrations in production and `docs/packages/mithaq-admin/README.md` the admin. The workflow skills in `.claude/skills/` (`add-kayan`, `add-field`, `eject-admin-piece`, `upgrade-mithaq`) are the ones the package ships under `skills/` at the version the project was made with; `upgrade-mithaq` copies them again.
+
+## Where things go
+
+The project is three steps, each named after what it holds, and each imports only the steps before it.
+
+1. **The language**, `packages/mithaq` (`@asas/mithaq`). `src/mithaq.ts` declares it with `defineMithaq`, with its targets and screens, and exports `defineKayan`, `defineGlobal`, `buildAsas` and the tenant field `organization`. Beside it sits everything the language or more than one feature reads:
+   - `src/mithaq/auth/`: the Better Auth setup, imported as `@asas/mithaq/auth`.
+   - `src/mithaq/pages.ts`, with the rich-text add-on `rich-text-nodes.ts`, and with the audit-log add-on `audit-sink.ts`: the page trees every kayan page starts from, the rich-text nodes and the audit sink.
+   - `src/roles/`: `tenant-roles.ts`, the roles every organization gets and the permission keys each holds, and the access rows and grants beside it. Without the roles add-on those roles are Better Auth's own `owner`, `admin` and `member`, listed in `default-member-roles.ts`, and a member holds the ones its `member.role` names.
+   - `src/ui/`: the shells, layouts and pieces several screens draw.
+   - `src/steps/`, `src/mail/` and, with the uploads add-on, `src/storage/`: a write step, the mailers and storage adapters ejected from `mithaq-admin`, and the `index.ts` that chooses the mailer. They are this project's files.
+2. **The features**, `packages/features/<feature>` (`@asas/<feature>`), each holding one or more kayan. `index.ts` exports the feature's `kayan` list (and `global`, for a single-row kayan). The media feature's `kayan` is a function of `reads`, what opens an image to an actor without `media.create`; a feature whose rows point at images exports its read (courses' `coverReads`), and the asas hands it in. Each kayan has a folder of its own, `<kayan>/<kayan>.ts`, with any page pieces only it draws in `<kayan>/ui/`; a child kayan is a sibling folder in its feature, never nested. `auth/user/` holds the Better Auth kayan, written by `mithaq generate auth`.
+3. **The asas**, `packages/asas` (`asas`). `src/asas.ts` is the build: it spreads each feature's `kayan` into `buildAsas`. Beside it are each screen's own pieces (`src/ui-dashboard/`, `src/ui-portal/`, `src/ui-backoffice/`), `src/messages/` (one copy file per kayan, which `mithaq generate messages` fills with missing keys; translate in place), `src/migrations/` (written by `mithaq migrate`; commit them) and `src/seed.ts`.
+
+A feature reaches another feature's kayan by its name (`relationTo: 'user'`) or through that feature's `index.ts`, never an inner file. The language never imports a feature or the asas.
+
+`apps/asas-tanstack/` is the tenant app, serving `/dashboard` and `/portal`; `apps/asas-backoffice/`, with the backoffice add-on, is the backoffice console for staff across every organization. Both import the asas alone.
+
+The project holds the add-ons it was made with (`roles`, `audit-log`, `settings`, `rich-text`, `uploads`, `media`, `courses`, `backoffice`); `packages/features/` and `apps/` show which. No command adds one yet: `README.md`, "Add an add-on", says how by hand.
+
+## Adding a kayan
+
+Copy `packages/features/tags/`; with the courses add-on, `packages/features/courses/courses/courses.ts` shows custom operations and steps.
+
+1. Write `<name>/<name>.ts` in the feature it belongs to, or in a new feature `packages/features/<feature>/` with a `package.json` like `tags`' and an `index.ts`. Import `defineKayan` from `@asas/mithaq`. Spread `defaultFields` (id, createdAt, updatedAt) into `fields`, and `defaultOperations` into `targets.service.operations`, leaving out any operation the kayan should not have. Give every label and message one string per locale (`en` and `ar`).
+2. Place `organization` in `fields` when each row belongs to one organization. Leave it out for a kayan every organization shares.
+3. Add the kayan to its feature's `kayan` list. A new feature is a dependency of `packages/asas/package.json`, and its `kayan` is spread into `buildAsas` in `src/asas.ts`.
+4. Grant its keys (`<name>.find`, `<name>.create`, `<name>.fields.<field>` and so on) to the roles that use it in `packages/mithaq/src/roles/tenant-roles.ts`, or under `member` in `default-member-roles.ts` in a project without the roles add-on, where `owner` and `admin` already hold every key.
+5. To draw it, add it to a screen's `kayan` list in `packages/mithaq/src/mithaq.ts`, describe its pages under `targets.dashboard` in the kayan, and run `bunx mithaq generate screens`.
+6. Run `bunx mithaq generate messages` and fill any empty translation it adds.
+7. Write the migration: `bunx mithaq migrate --name add_<name>`. Commit the folder it writes.
+8. Run `bunx mithaq generate --check`.
+
+## The tenant field
+
+A kayan that places `organization` is per-organization, and mithaq core enforces it on every managed read and write; nothing in the project can turn it off. The scope is the signed-in session's verified active organization. A create fills `organization` from the session, so a caller or a step never sets it, and it never changes. Another organization's row answers like a missing one. Raw SQL through `ctx.tx` is not scoped: filter by organization there yourself. Write the field as `organization` from `@asas/mithaq`; a look-alike field that is not bound is refused.
+
+On a per-organization kayan, `rules: { unique: true }` means unique within each organization, and `{ within: 'organization', unique: [...], index: [...] }` in `indexes` builds indexes led by the organization. A plain `{ fields, unique: true }` entry is unique across every organization.
+
+How many organizations the project holds, and who may sign up and join, is `packages/mithaq/src/mithaq/auth/organizations.ts` (`organizations`, `showOrganization`, `signUp`, `joinRole`, `verifyEmail`, `allowedDomains`). In one organization the field and the scope are the same, so keep placing `organization` on every per-organization kayan: leaving it off makes the kayan shared by every organization the day the project holds many. README.md, "Organization modes", says what each value does and how to change it.
+
+Reads that reach further (`tenant: 'mine' | 'all'`), what is refused, and the index rules are in the tenancy guide, `docs/packages/mithaq/src/asas/runner/README.md` in the installed mithaq.
+
+## Migrations
+
+- In development `asas.connect()` pushes the schema; nothing needs a migration to run locally.
+- A project made without every add-on that holds tables starts with no migration: write its first, `bunx mithaq migrate --name init`, against an empty database before it first deploys.
+- `mithaq migrate` refuses to write against a pushed database. Point `DATABASE_URL` at a database built from the migrations: create an empty one, apply them with the `drizzle-kit` the installed mithaq depends on, then run `bunx mithaq migrate --name <slug>`. The slug is lowercase letters, digits and underscores.
+
+  ```sh
+  DRIZZLE_KIT=$(node -p "path.join(path.dirname(require('module').createRequire(fs.realpathSync('node_modules/mithaq/package.json')).resolve('drizzle-kit')), 'bin.cjs')")
+  node "$DRIZZLE_KIT" migrate --config src/migrations/drizzle.config.ts
+  ```
+- When a change would lose data, `mithaq migrate` stops and asks for an answer in `mithaq.hints.json`. A drop deletes rows: ask the developer before you write one.
+- In production `connect()` checks for pending migrations, as `prodMigrations` in `packages/mithaq/src/mithaq.ts` says: `pending: 'refuse'` refuses to start, `pending: 'run'` applies them under a lock. `drizzle-kit migrate` run by hand takes no lock, so never run it while an app is starting. See `README.md`, "Running in production", and the guide to migrations in production, `docs/packages/mithaq/src/drizzle/README.md` in the installed mithaq.
+
+## Rules
+
+- The vocabulary of `defineMithaq` in `packages/mithaq/src/mithaq.ts` (its locales, kinds, rules, target names and capabilities, and root keys) changes only when the developer asks for that change. When a task needs it, tell the developer what and why first. If the project has a `mithaq.lock`, `mithaq lock` shows a popup the developer approves; never edit the lock by hand. Everything in `defineKayan`, `defineGlobal` and `buildAsas` is yours to change. With a lock, `bunx mithaq lock --check`, part of `bunx mithaq generate --check`, fails on a word the lock does not record.
+- The backoffice is served on a subdomain of its own (`backoffice.example.com` beside `app.example.com`), never mounted under a path of the customer app: browsers isolate scripts by origin and send cookies by host, so on one host a script flaw in the customer app would reach staff sessions. Start refuses when `BACKOFFICE_URL` and `BETTER_AUTH_URL` share an origin, or a host off this machine. The backoffice's Origin checks are the barrier between the two subdomains: keep one on every route that changes state. `README.md`, "Deploying both apps on one domain", shows the proxy. The start's refusal checks the first; review checks the Origin checks.
+- A file whose first line reads ``// Written by `mithaq <command>` `` is regenerated by that command, never edited. `bunx mithaq generate --check` fails when one differs from what its command writes.
+- The admin's pieces come from the `mithaq-admin` package. Replace a control, cell or node in the components map (`src/components.ts` in each app); to change another piece, `bunx mithaq eject <item>` in the app writes it into `src/components/mithaq/`, drawn in place of the package's. A file ejected from `mithaq-admin` ends with a `// mithaq-admin` marker line. It is this project's: edit it in place. After you update mithaq and mithaq-admin together, `bunx mithaq upgrade --check` names each file that differs; merge an edited one by hand.
+- A function the project writes takes one object once it has three or more parameters. Steps keep `(ctx, tools)`. Review checks this.
+- Comments say why, never what. Review checks this.
+
+## Commands
+
+The `mithaq` bin runs under Node and does not read `.env`, so export `DATABASE_URL` first. Commands that touch the database refuse to run without it.
+
+```sh
+bunx mithaq --help
+bunx mithaq generate --check    # the lock, generated files, migrations and copies; writes nothing
+bunx mithaq generate auth       # the Better Auth kayan
+bunx mithaq generate messages   # copy files
+bunx mithaq generate screens    # each screen's routes in the apps
+bunx mithaq migrate --name <slug>
+bunx mithaq migrate --check
+bunx mithaq lock --check
+bunx mithaq upgrade --check
+bun run dev:setup --seed        # a fresh dev database: the schema, the dev admin .env names, sample rows
+bun run seed
+```
+
+From the project root, where an isolated install puts no `typescript` and a bare `bunx tsc` would fetch the unrelated `tsc` package:
+
+```sh
+bunx --package typescript tsc -p .
+bunx --package typescript tsc -p apps/asas-tanstack
+bunx --package typescript tsc -p apps/asas-backoffice
+bun run --cwd apps/asas-tanstack dev    # http://localhost:5173
+bun run --cwd apps/asas-backoffice dev    # http://localhost:5174
+```
+
+`README.md` beside this file is the guide to this project. The language reference is `docs/packages/mithaq/README.md` in the installed mithaq.

package/template/templates/asas/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md