create-davepi-app 0.1.0

package/templates/_shared/tests/smoke.test.js

@@ -0,0 +1,67 @@
+/**
+ * Smoke tests for the project's schema files.
+ *
+ * Validates each file under `schema/versions/v1/` parses cleanly,
+ * exports a `path` + `fields` shape, and includes the framework's
+ * required `userId` tenant column. Doesn't need MongoDB — this is
+ * a fast guard against typos that would otherwise only surface
+ * when the server boots in production.
+ *
+ * Uses node:test (built-in, no extra deps). Add your own
+ * integration tests alongside this file as the project grows.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const schemaDir = path.join(__dirname, '..', 'schema', 'versions', 'v1');
+const files = fs.existsSync(schemaDir)
+  ? fs.readdirSync(schemaDir).filter((f) => f.endsWith('.js'))
+  : [];
+
+test('schema directory exists and contains at least one schema file', () => {
+  assert.ok(
+    fs.existsSync(schemaDir),
+    'expected ./schema/versions/v1/ to exist'
+  );
+  assert.ok(
+    files.length > 0,
+    'expected at least one schema file under ./schema/versions/v1/'
+  );
+});
+
+for (const file of files) {
+  test(`${file}: exports a valid schema shape`, () => {
+    // require() will throw on a syntax error or a missing CommonJS
+    // export — both of which we want to catch in CI before deploy.
+    const schema = require(path.join(schemaDir, file));
+
+    assert.equal(typeof schema, 'object', `${file} must export an object`);
+    assert.equal(
+      typeof schema.path,
+      'string',
+      `${file}: schema.path must be a string`
+    );
+    assert.ok(schema.path.length > 0, `${file}: schema.path must be non-empty`);
+    assert.ok(Array.isArray(schema.fields), `${file}: schema.fields must be an array`);
+    assert.ok(
+      schema.fields.length > 0,
+      `${file}: schema.fields must have at least one entry`
+    );
+
+    const userIdField = schema.fields.find((f) => f && f.name === 'userId');
+    assert.ok(
+      userIdField,
+      `${file}: every schema must declare a 'userId' field — the framework stamps it as the tenant column`
+    );
+    assert.equal(
+      userIdField.required,
+      true,
+      `${file}: 'userId' must be required: true`
+    );
+  });
+}

package/templates/b2b-saas/README.md

@@ -0,0 +1,57 @@
+# B2B SaaS template
+
+Multi-tenant SaaS skeleton: orgs, workspaces, invitations with a state machine, and a billing-event log with monthly aggregations. The patterns here scale to a real product — invite flow, plan/seat tracking, billing-event audit, computed slug.
+
+## Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `org` | The customer entity. `slug` is computed from `name`. `plan` and `seats` track the subscription. Has `workspaces` (hasMany) and `invites` (hasMany). |
+| `workspace` | A scoped area inside an org. Connects via `org` (belongsTo `orgId`). |
+| `invite` | Pending invitations. `status` flows `pending → accepted / declined / revoked / expired`. `expired` can re-enter `pending` if the org reissues. |
+| `billingEvent` | Append-only ledger (upgrade / downgrade / invoice / refund / usage) referencing an org. Aggregations: `byOrg` (total per org), `monthlyRecurring` (per-month totals). |
+
+## Worked example
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:5050/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"a@b.com","password":"pw12345!"}' | jq -r .accessToken)
+
+# Create an org
+ORG=$(curl -s -X POST http://localhost:5050/api/v1/org \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"name":"Acme Co","plan":"starter","seats":10}' | jq -r ._id)
+
+# Add a workspace inside it
+curl -s -X POST http://localhost:5050/api/v1/workspace \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"orgId\":\"$ORG\",\"name\":\"Engineering\"}"
+
+# Invite someone — initial status = "pending"
+INV=$(curl -s -X POST http://localhost:5050/api/v1/invite \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"orgId\":\"$ORG\",\"email\":\"jane@acme.com\",\"role\":\"admin\"}" | jq -r ._id)
+
+# Accept
+curl -s -X PUT "http://localhost:5050/api/v1/invite/$INV" \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"status\":\"accepted\",\"acceptedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"
+
+# Log a plan upgrade
+curl -s -X POST http://localhost:5050/api/v1/billingEvent \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"orgId\":\"$ORG\",\"kind\":\"upgrade\",\"amount\":99,\"externalRef\":\"ch_abc\"}"
+
+# Aggregations
+curl http://localhost:5050/api/v1/billingEvent/aggregations/byOrg \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+## With Claude Code
+
+> Add a `member` resource that joins users to orgs (with role: 'owner' | 'admin' | 'member'), and a `members` hasMany relation on org.
+
+## Pair with Idempotency-Key
+
+The invite-create endpoint is the obvious place — sending the same key + body twice returns the original invite instead of creating a duplicate. See [Idempotency keys](https://docs.davepi.dev/features/idempotency/).

package/templates/b2b-saas/schema/versions/v1/billingEvent.js

@@ -0,0 +1,46 @@
+module.exports = {
+  path: 'billingEvent',
+  collection: 'billing_event',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'orgId', type: String, required: true },
+    { name: 'kind', type: String, required: true }, // upgrade | downgrade | invoice | refund | usage
+    { name: 'amount', type: Number },
+    { name: 'currency', type: String, default: 'USD' },
+    { name: 'externalRef', type: String }, // Stripe charge id, etc.
+    { name: 'occurredAt', type: Date, default: Date.now },
+  ],
+  relations: {
+    org: { belongsTo: 'org', localKey: 'orgId' },
+  },
+  aggregations: [
+    {
+      name: 'byOrg',
+      description: 'Total billing amount per org for the authenticated tenant.',
+      pipeline: [
+        { $match: { amount: { $type: 'number' } } },
+        { $group: { _id: '$orgId', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+        { $sort: { total: -1 } },
+      ],
+      cache: { ttlSeconds: 60 },
+    },
+    {
+      name: 'monthlyRecurring',
+      description: 'Billing-event totals grouped by month.',
+      pipeline: [
+        { $match: { occurredAt: { $type: 'date' }, amount: { $type: 'number' } } },
+        {
+          $group: {
+            _id: {
+              year: { $year: '$occurredAt' },
+              month: { $month: '$occurredAt' },
+            },
+            total: { $sum: '$amount' },
+          },
+        },
+        { $sort: { '_id.year': 1, '_id.month': 1 } },
+      ],
+      cache: { ttlSeconds: 60 },
+    },
+  ],
+};

package/templates/b2b-saas/schema/versions/v1/invite.js

@@ -0,0 +1,30 @@
+module.exports = {
+  path: 'invite',
+  collection: 'invite',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'orgId', type: String, required: true },
+    { name: 'email', type: String, required: true },
+    { name: 'role', type: String, default: 'member' },
+    {
+      name: 'status',
+      type: String,
+      stateMachine: {
+        initial: 'pending',
+        states: ['pending', 'accepted', 'declined', 'revoked', 'expired'],
+        transitions: {
+          pending: ['accepted', 'declined', 'revoked', 'expired'],
+          accepted: [],
+          declined: [],
+          revoked: [],
+          expired: ['pending'],
+        },
+      },
+    },
+    { name: 'expiresAt', type: Date },
+    { name: 'acceptedAt', type: Date },
+  ],
+  relations: {
+    org: { belongsTo: 'org', localKey: 'orgId' },
+  },
+};

package/templates/b2b-saas/schema/versions/v1/org.js

@@ -0,0 +1,23 @@
+module.exports = {
+  path: 'org',
+  collection: 'org',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'name', type: String, required: true, searchable: true, searchWeight: 5 },
+    {
+      name: 'slug',
+      type: String,
+      computed: (r) =>
+        String(r.name || '')
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-|-$/g, ''),
+    },
+    { name: 'plan', type: String, default: 'trial' }, // trial | starter | growth | enterprise
+    { name: 'seats', type: Number, default: 5 },
+  ],
+  relations: {
+    workspaces: { hasMany: 'workspace', foreignKey: 'orgId' },
+    invites: { hasMany: 'invite', foreignKey: 'orgId' },
+  },
+};

package/templates/b2b-saas/schema/versions/v1/workspace.js

@@ -0,0 +1,13 @@
+module.exports = {
+  path: 'workspace',
+  collection: 'workspace',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'orgId', type: String, required: true },
+    { name: 'name', type: String, required: true, searchable: true },
+    { name: 'description', type: String, searchable: true },
+  ],
+  relations: {
+    org: { belongsTo: 'org', localKey: 'orgId' },
+  },
+};

package/templates/b2b-saas/seed.js

@@ -0,0 +1,98 @@
+'use strict';
+require('dotenv').config();
+
+const port = process.env.API_PORT || 5050;
+const base = `http://127.0.0.1:${port}`;
+const DEMO_EMAIL = 'demo@example.com';
+const DEMO_PASSWORD = 'demo-password!';
+
+async function fetchJson(path, opts = {}) {
+  const res = await fetch(base + path, {
+    ...opts,
+    headers: { 'Content-Type': 'application/json', ...(opts.headers || {}) },
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : null; } catch { body = text; }
+  return { status: res.status, body };
+}
+
+async function ensureDemoUser() {
+  let r = await fetchJson('/login', {
+    method: 'POST',
+    body: JSON.stringify({ email: DEMO_EMAIL, password: DEMO_PASSWORD }),
+  });
+  if (r.status === 200) return r.body.accessToken;
+  r = await fetchJson('/register', {
+    method: 'POST',
+    body: JSON.stringify({
+      first_name: 'Demo', last_name: 'User',
+      email: DEMO_EMAIL, password: DEMO_PASSWORD,
+    }),
+  });
+  if (r.status !== 201) throw new Error(`register: ${r.status} ${JSON.stringify(r.body)}`);
+  return r.body.accessToken;
+}
+
+async function post(path, body, auth) {
+  const r = await fetchJson(path, { method: 'POST', headers: auth, body: JSON.stringify(body) });
+  if (r.status !== 201) throw new Error(`${path}: ${r.status} ${JSON.stringify(r.body)}`);
+  return r.body;
+}
+
+async function put(path, body, auth) {
+  const r = await fetchJson(path, { method: 'PUT', headers: auth, body: JSON.stringify(body) });
+  if (r.status !== 200) throw new Error(`${path}: ${r.status} ${JSON.stringify(r.body)}`);
+  return r.body;
+}
+
+async function main() {
+  const token = await ensureDemoUser();
+  const auth = { Authorization: `Bearer ${token}` };
+
+  const acme = await post('/api/v1/org', {
+    name: 'Acme Co',
+    plan: 'starter',
+    seats: 10,
+  }, auth);
+  const globex = await post('/api/v1/org', {
+    name: 'Globex',
+    plan: 'enterprise',
+    seats: 200,
+  }, auth);
+
+  await post('/api/v1/workspace', { orgId: acme._id, name: 'Engineering' }, auth);
+  await post('/api/v1/workspace', { orgId: acme._id, name: 'Marketing' }, auth);
+  await post('/api/v1/workspace', { orgId: globex._id, name: 'EU Region' }, auth);
+
+  const inv = await post('/api/v1/invite', {
+    orgId: acme._id,
+    email: 'jane@acme.example',
+    role: 'admin',
+  }, auth);
+  await put(`/api/v1/invite/${inv._id}`, { status: 'accepted', acceptedAt: new Date() }, auth);
+
+  await post('/api/v1/invite', {
+    orgId: globex._id,
+    email: 'bob@globex.example',
+    role: 'member',
+  }, auth);
+
+  await post('/api/v1/billingEvent', {
+    orgId: acme._id, kind: 'upgrade', amount: 99, externalRef: 'ch_seed_1',
+  }, auth);
+  await post('/api/v1/billingEvent', {
+    orgId: globex._id, kind: 'invoice', amount: 4990, externalRef: 'ch_seed_2',
+  }, auth);
+  await post('/api/v1/billingEvent', {
+    orgId: globex._id, kind: 'usage', amount: 220, externalRef: 'usage_seed_1',
+  }, auth);
+
+  process.stdout.write(`Seeded 2 orgs, 3 workspaces, 2 invites, 3 billing events as ${DEMO_EMAIL}.\n`);
+  process.stdout.write(`Sign in with: ${DEMO_EMAIL} / ${DEMO_PASSWORD}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`\nSeed failed: ${err.message}\n`);
+  process.exit(1);
+});

package/templates/blank/README.md

@@ -0,0 +1,42 @@
+# Blank template
+
+The minimal starter — one resource (`note`) with full-text search, ready to demo CRUD and the admin SPA without telling you what to model.
+
+## Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `note` | A single text record with `title`, `body`, `pinned`. Both text fields are `searchable` so `__q` works out of the box. |
+
+## Try it
+
+```bash
+# After `npx create-davepi-app my-app --template blank`:
+cd my-app
+npm install
+npm start
+
+# In another terminal:
+curl -X POST http://localhost:5050/register \
+  -H 'Content-Type: application/json' \
+  -d '{"first_name":"A","last_name":"B","email":"a@b.com","password":"pw12345!"}'
+```
+
+Save the returned `accessToken`, then:
+
+```bash
+TOKEN=...
+curl -X POST http://localhost:5050/api/v1/note \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Hello","body":"World"}'
+
+curl 'http://localhost:5050/api/v1/note?__q=hello' \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## Where to go next
+
+- Add another resource: drop a file in `schema/versions/v1/`. Hot-reload picks it up.
+- Wire Claude Code: open the project in your editor, the `.mcp.json` is already configured.
+- Generate a typed client: `npx davepi gen-client --out client/davepi.ts`.

package/templates/blank/schema/versions/v1/note.js

@@ -0,0 +1,10 @@
+module.exports = {
+  path: 'note',
+  collection: 'note',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'title', type: String, required: true, searchable: true },
+    { name: 'body', type: String, searchable: true },
+    { name: 'pinned', type: Boolean, default: false },
+  ],
+};

package/templates/blank/seed.js

@@ -0,0 +1,86 @@
+/**
+ * Seed sample data for the `blank` template.
+ *
+ * Run: `npm run seed` (after `npm install` and `docker compose up -d`)
+ *
+ * The script boots an HTTP client against the configured API_PORT,
+ * registers (or logs in) a demo user, and POSTs a handful of notes
+ * so the admin SPA / MCP surface have something to look at.
+ */
+
+'use strict';
+
+require('dotenv').config();
+
+const port = process.env.API_PORT || 5050;
+const base = `http://127.0.0.1:${port}`;
+
+const DEMO_EMAIL = 'demo@example.com';
+const DEMO_PASSWORD = 'demo-password!';
+
+async function fetchJson(path, opts = {}) {
+  const res = await fetch(base + path, {
+    ...opts,
+    headers: { 'Content-Type': 'application/json', ...(opts.headers || {}) },
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : null; } catch { body = text; }
+  return { status: res.status, body };
+}
+
+async function ensureDemoUser() {
+  // Try to log in first; fall back to register on 400 (no such user).
+  let r = await fetchJson('/login', {
+    method: 'POST',
+    body: JSON.stringify({ email: DEMO_EMAIL, password: DEMO_PASSWORD }),
+  });
+  if (r.status === 200) return r.body.accessToken;
+  r = await fetchJson('/register', {
+    method: 'POST',
+    body: JSON.stringify({
+      first_name: 'Demo',
+      last_name: 'User',
+      email: DEMO_EMAIL,
+      password: DEMO_PASSWORD,
+    }),
+  });
+  if (r.status !== 201) {
+    throw new Error(
+      `Failed to register demo user: ${r.status} ${JSON.stringify(r.body)}`
+    );
+  }
+  return r.body.accessToken;
+}
+
+async function main() {
+  const token = await ensureDemoUser();
+  const auth = { Authorization: `Bearer ${token}` };
+
+  const seed = [
+    { title: 'Pinned: ship the launch post', body: 'Hero, video, comparison page.', pinned: true },
+    { title: 'Reach out to early users', body: 'Three people from the waitlist.' },
+    { title: 'Refactor the auth middleware', body: 'See PR #47 for context.' },
+  ];
+
+  for (const note of seed) {
+    const r = await fetchJson('/api/v1/note', {
+      method: 'POST',
+      headers: auth,
+      body: JSON.stringify(note),
+    });
+    if (r.status !== 201) {
+      throw new Error(
+        `Failed to create note: ${r.status} ${JSON.stringify(r.body)}`
+      );
+    }
+    process.stdout.write(`  ✓ ${note.title}\n`);
+  }
+  process.stdout.write(`\nSeeded ${seed.length} notes as ${DEMO_EMAIL}.\n`);
+  process.stdout.write(`Sign in with: ${DEMO_EMAIL} / ${DEMO_PASSWORD}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`\nSeed failed: ${err.message}\n`);
+  process.exit(1);
+});

package/templates/content/README.md

@@ -0,0 +1,58 @@
+# Content template
+
+A blog / CMS skeleton with editorial workflow, slug computation, hero image upload, and category aggregations.
+
+## Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `article` | The post. `slug` is computed from `title`. `status` flows `draft → review → published → archived` (any state can return to `draft`). `heroImage` is a public file ≤5MB. `publishedAt` is set on the client side when transitioning to `published` (see the example below). |
+| `category` | Taxonomy. `slug` is computed from `name`. `name` is unique. Relates back to articles via `category.articles` (hasMany). |
+
+## Aggregations
+
+- `article.byStatus` — count per status (draft / review / published / archived). Cached 60s.
+- `article.byCategory` — published articles grouped by `categoryId`. Cached 60s.
+
+## Worked example
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:5050/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"a@b.com","password":"pw12345!"}' | jq -r .accessToken)
+
+# Create a category
+CAT=$(curl -s -X POST http://localhost:5050/api/v1/category \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"name":"Engineering","description":"Behind the scenes"}' | jq -r ._id)
+
+# Create an article — initial status = "draft"
+A=$(curl -s -X POST http://localhost:5050/api/v1/article \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"title\":\"How we ship\",\"body\":\"Once a week.\",\"categoryId\":\"$CAT\",\"tags\":[\"process\"]}")
+echo "$A" | jq '{_id, slug, status, availableTransitions}'
+
+ID=$(echo "$A" | jq -r ._id)
+
+# draft → review
+curl -s -X PUT "http://localhost:5050/api/v1/article/$ID" \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"status":"review"}'
+
+# review → published, stamping publishedAt at the same time
+curl -s -X PUT "http://localhost:5050/api/v1/article/$ID" \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"status\":\"published\",\"publishedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"
+
+curl "http://localhost:5050/api/v1/article/$ID" \
+  -H "Authorization: Bearer $TOKEN" | jq '{title, slug, status, publishedAt}'
+
+# Upload a hero image
+curl -X POST "http://localhost:5050/api/v1/article/$ID/heroImage" \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@./hero.jpg"
+```
+
+## With Claude Code
+
+> Add a `readingTimeMinutes` computed field to article: estimated reading time based on `body` length at 200 words per minute.

package/templates/content/schema/versions/v1/article.js

@@ -0,0 +1,77 @@
+module.exports = {
+  path: 'article',
+  collection: 'article',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    { name: 'title', type: String, required: true, searchable: true, searchWeight: 5 },
+    {
+      name: 'slug',
+      type: String,
+      computed: (r) =>
+        String(r.title || '')
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-|-$/g, ''),
+      description: 'URL-safe form of title, derived.',
+    },
+    { name: 'body', type: String, searchable: true },
+    { name: 'excerpt', type: String },
+    { name: 'categoryId', type: String },
+    { name: 'tags', type: [String] },
+    { name: 'authorName', type: String },
+    { name: 'publishedAt', type: Date },
+    {
+      name: 'heroImage',
+      type: 'File',
+      file: {
+        maxBytes: 5 * 1024 * 1024,
+        accept: ['image/jpeg', 'image/png', 'image/webp'],
+        access: 'public',
+      },
+    },
+    {
+      name: 'status',
+      type: String,
+      stateMachine: {
+        initial: 'draft',
+        states: ['draft', 'review', 'published', 'archived'],
+        transitions: {
+          draft: ['review', 'archived'],
+          review: ['published', 'draft'],
+          published: ['archived', 'draft'],
+          archived: ['draft'],
+        },
+        // onEnter hooks run best-effort with `(record, { user, from,
+        // to })`. They're side-effect channels — notifications,
+        // webhooks, downstream events — not write-back. To stamp
+        // `publishedAt` automatically, send it on the PUT that
+        // transitions to `published` (the framework's audit log
+        // captures the timestamp regardless).
+      },
+    },
+  ],
+  relations: {
+    category: { belongsTo: 'category', localKey: 'categoryId' },
+  },
+  aggregations: [
+    {
+      name: 'byStatus',
+      description: 'Article count grouped by current status.',
+      pipeline: [
+        { $group: { _id: '$status', count: { $sum: 1 } } },
+        { $sort: { count: -1 } },
+      ],
+      cache: { ttlSeconds: 60 },
+    },
+    {
+      name: 'byCategory',
+      description: 'Published article count grouped by categoryId.',
+      pipeline: [
+        { $match: { status: 'published' } },
+        { $group: { _id: '$categoryId', count: { $sum: 1 } } },
+        { $sort: { count: -1 } },
+      ],
+      cache: { ttlSeconds: 60 },
+    },
+  ],
+};

package/templates/content/schema/versions/v1/category.js

@@ -0,0 +1,30 @@
+module.exports = {
+  path: 'category',
+  collection: 'category',
+  fields: [
+    { name: 'userId', type: String, required: true },
+    // Per-tenant unique (see compositeIndex below) — NOT globally
+    // unique. Two different users can each have a "Engineering"
+    // category without colliding.
+    { name: 'name', type: String, required: true, searchable: true },
+    {
+      name: 'slug',
+      type: String,
+      computed: (r) =>
+        String(r.name || '')
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-')
+          .replace(/^-|-$/g, ''),
+      description: 'URL-safe form of name, derived.',
+    },
+    { name: 'description', type: String, searchable: true },
+  ],
+  // Tenant-scoped uniqueness on `name`. dAvePi scopes every read /
+  // write by userId, so this index enforces "no duplicate name
+  // within one user's categories" without blocking other users
+  // from using the same string.
+  compositeIndex: [{ userId: 1, name: 1 }],
+  relations: {
+    articles: { hasMany: 'article', foreignKey: 'categoryId' },
+  },
+};