@pylonsync/create-pylon 0.3.275 → 0.3.276

package/templates/agency/components/marketing.tsx

@@ -1,4 +1,6 @@
 import React from "react";
+import { Link } from "@pylonsync/react";
+import type { ProjectView } from "@/lib/agency";
 
 // Reusable presentational pieces for the landing page. All server-rendered —
 // no client JS. Restyle here and the whole page follows. The brand accent
@@ -95,6 +97,43 @@ export function initials(name: string) {
     .toUpperCase();
 }
 
+// A linked portfolio card — the project's cover, title, client label, summary,
+// and tag chips, linking to its /work/[slug] case study. Used on the homepage
+// "Selected work" grid and the full /work index, so both stay in lockstep.
+export function ProjectCard({ p }: { p: ProjectView }) {
+  return (
+    <Link href={`/work/${p.slug}`} className="group block">
+      {/* Case-study cover — drop in a real project screenshot. */}
+      <ImagePlaceholder
+        shape="landscape"
+        title={`${p.title} — project shot`}
+        hint="Swap for an <img> per case study"
+      />
+      <div className="mt-4 flex items-baseline justify-between gap-3">
+        <h3 className="text-[16px] font-semibold text-zinc-900 transition-colors group-hover:text-brand">
+          {p.title}
+        </h3>
+        <span className="shrink-0 font-mono text-[11px] uppercase tracking-wide text-zinc-400">
+          {p.client}
+        </span>
+      </div>
+      <p className="mt-1.5 text-[14px] leading-relaxed text-zinc-500">{p.summary}</p>
+      {p.tags.length > 0 ? (
+        <div className="mt-3 flex flex-wrap gap-1.5">
+          {p.tags.map((t) => (
+            <span key={t} className="rounded-full bg-zinc-100 px-2.5 py-0.5 text-[11px] font-medium text-zinc-600">
+              {t}
+            </span>
+          ))}
+        </div>
+      ) : null}
+      <span className="mt-3 inline-flex items-center gap-1 text-[13px] font-medium text-brand opacity-0 transition-opacity group-hover:opacity-100">
+        Read case study →
+      </span>
+    </Link>
+  );
+}
+
 // A deliberately-obvious image placeholder. Real sites drop a photo here; this
 // makes the spot unmistakable — dashed border, a photo glyph, and a one-line
 // "swap this" instruction telling you exactly what to replace and where. Looks

package/templates/agency/functions/clientsForOwner.ts

@@ -0,0 +1,27 @@
+import { query } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { ClientRow, OwnerClientsResult } from "../lib/agency";
+
+// clientsForOwner — the owner's CRM. Client rows hold contact PII (name, email,
+// phone), so the entity denies all client access; this owner-gated query is the
+// only way to read them. A query has no `ctx.error`, so a non-owner gets
+// `{ authorized: false }` (a bare throw would surface as a stripped
+// HANDLER_ERROR) and NO data. The dashboard calls it with `callFn` and refetches
+// after any write.
+export default query({
+  auth: "user",
+  async handler(ctx): Promise<OwnerClientsResult> {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    const email = (me?.email as string | undefined) ?? null;
+    if (!emailMatchesOwner(email, ctx.env.PYLON_OWNER_EMAIL)) {
+      return { authorized: false };
+    }
+
+    const rows = (await ctx.db.unsafe.list("Client")) as unknown as ClientRow[];
+    const clients = rows
+      .map((r) => ({ ...r }))
+      .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+
+    return { authorized: true, clients };
+  },
+});

package/templates/agency/functions/deleteClient.ts

@@ -0,0 +1,27 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { InvoiceRow } from "../lib/agency";
+
+// deleteClient — owner-only. Refuses to delete a client that still has invoices
+// (a financial record must not lose its counterparty); the owner deletes or
+// reassigns those invoices first. Returns `{ ok: false, invoices: n }` so the
+// dashboard can explain why.
+export default mutation<{ id: string }, { ok: boolean; invoices: number }>({
+  auth: "user",
+  args: { id: v.id("Client") },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage clients.");
+    }
+    const client = await ctx.db.get("Client", args.id);
+    if (!client) return { ok: true, invoices: 0 };
+
+    const invoices = (await ctx.db.unsafe.list("Invoice")) as unknown as InvoiceRow[];
+    const linked = invoices.filter((i) => i.clientId === args.id).length;
+    if (linked > 0) return { ok: false, invoices: linked };
+
+    await ctx.db.unsafe.delete("Client", args.id);
+    return { ok: true, invoices: 0 };
+  },
+});

package/templates/agency/functions/deleteInvoice.ts

@@ -0,0 +1,19 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// deleteInvoice — owner-only. Removes a bill outright (e.g. a draft created in
+// error). No cascade — invoices don't own anything.
+export default mutation<{ id: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Invoice") },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage invoices.");
+    }
+    const invoice = await ctx.db.get("Invoice", args.id);
+    if (!invoice) return { ok: true };
+    await ctx.db.unsafe.delete("Invoice", args.id);
+    return { ok: true };
+  },
+});

package/templates/agency/functions/deleteProject.ts

@@ -0,0 +1,20 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// deleteProject — owner-only. Removes a case study. Any invoice that referenced
+// it keeps its denormalized `projectTitle` (so the bill still reads sensibly),
+// it just no longer links anywhere — we don't cascade-delete money records.
+export default mutation<{ id: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Project") },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage projects.");
+    }
+    const project = await ctx.db.get("Project", args.id);
+    if (!project) return { ok: true };
+    await ctx.db.unsafe.delete("Project", args.id);
+    return { ok: true };
+  },
+});

package/templates/agency/functions/invoicesForOwner.ts

@@ -0,0 +1,27 @@
+import { query } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { InvoiceRow, OwnerInvoicesResult } from "../lib/agency";
+
+// invoicesForOwner — the owner's billing. Invoices hold money + client data, so
+// the entity denies all client access; this owner-gated query is the only way
+// to read them. Like the other owner queries it returns `{ authorized: false }`
+// for a non-owner (a query has no `ctx.error`) rather than throwing. Sorted
+// newest-first by issue date, falling back to creation time.
+export default query({
+  auth: "user",
+  async handler(ctx): Promise<OwnerInvoicesResult> {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    const email = (me?.email as string | undefined) ?? null;
+    if (!emailMatchesOwner(email, ctx.env.PYLON_OWNER_EMAIL)) {
+      return { authorized: false };
+    }
+
+    const rows = (await ctx.db.unsafe.list("Invoice")) as unknown as InvoiceRow[];
+    const key = (i: InvoiceRow) => i.issuedAt || i.createdAt;
+    const invoices = rows
+      .map((r) => ({ ...r }))
+      .sort((a, b) => (key(a) < key(b) ? 1 : key(a) > key(b) ? -1 : 0));
+
+    return { authorized: true, invoices };
+  },
+});

package/templates/agency/functions/seedProjects.ts

@@ -0,0 +1,41 @@
+import { mutation } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+import { slugify } from "../lib/agency";
+
+// seedProjects — create the portfolio from config on first visit (idempotent).
+// The public pages call it on mount; once any Project row exists it's a no-op,
+// so it's safe to call on every load. A lock keeps two concurrent first-visits
+// from double-seeding.
+//
+// Public so an anonymous first visitor seeds it: Projects are public marketing
+// content (no PII), and this only ever writes the config's case studies.
+export default mutation<Record<string, never>, { seeded: number }>({
+  auth: "public",
+  async handler(ctx) {
+    await ctx.db.advisoryLock("agency_seed_projects");
+    const existing = await ctx.db.unsafe.list("Project");
+    if (existing.length > 0) return { seeded: 0 };
+
+    const now = new Date().toISOString();
+    let order = 0;
+    for (const p of siteConfig.work.items) {
+      await ctx.db.unsafe.insert("Project", {
+        title: p.title,
+        slug: p.slug || slugify(p.title),
+        client: p.client,
+        summary: p.summary,
+        year: p.year ?? null,
+        tags: p.tags.join(", "),
+        selected: p.selected ?? false,
+        published: true,
+        order: order++,
+        challenge: p.challenge ?? null,
+        approach: p.approach ?? null,
+        outcome: p.outcome ?? null,
+        liveUrl: p.liveUrl ?? null,
+        createdAt: now,
+      });
+    }
+    return { seeded: order };
+  },
+});

package/templates/agency/functions/seedStudioBackoffice.ts

@@ -0,0 +1,74 @@
+import { mutation } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { siteConfig } from "../lib/site.config";
+import { lineItemsTotal, slugify, type ProjectRow } from "../lib/agency";
+
+// seedStudioBackoffice — owner-only, idempotent. Fills the dashboard's CRM +
+// billing with the demo clients/invoices from config so it isn't an empty shell
+// on first sign-in. Private data (PII + money) is only ever seeded for the
+// signed-in owner — never by an anonymous visitor — which is why this is
+// owner-gated, unlike the public seedProjects.
+//
+// Invoices link to clients by name and to projects by slug; we resolve those to
+// ids here. Projects may already be seeded (the public site calls seedProjects);
+// if a project isn't present yet, the invoice still carries its title and just
+// doesn't deep-link.
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "user",
+  async handler(ctx) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can seed the back-office.");
+    }
+
+    await ctx.db.advisoryLock("agency_seed_backoffice");
+    const existingClients = await ctx.db.unsafe.list("Client");
+    if (existingClients.length > 0) return { seeded: false };
+
+    const now = new Date().toISOString();
+
+    // Clients first — keep a name → id map for the invoices.
+    const clientIdByName = new Map<string, string>();
+    for (const c of siteConfig.backoffice.clients) {
+      const id = await ctx.db.unsafe.insert("Client", {
+        name: c.name,
+        company: c.company ?? null,
+        email: c.email ?? null,
+        phone: c.phone ?? null,
+        status: c.status ?? "prospect",
+        notes: c.notes ?? null,
+        createdAt: now,
+      });
+      clientIdByName.set(c.name, id);
+    }
+
+    // Resolve project links by slug (config slug, or derived from the title).
+    const projects = (await ctx.db.unsafe.list("Project")) as unknown as ProjectRow[];
+    const projectBySlug = new Map(projects.map((p) => [p.slug, p]));
+    const titleBySlug = new Map(
+      siteConfig.work.items.map((p) => [p.slug || slugify(p.title), p.title]),
+    );
+
+    for (const inv of siteConfig.backoffice.invoices) {
+      const clientId = clientIdByName.get(inv.client);
+      if (!clientId) continue; // skip an invoice whose client wasn't seeded
+      const project = inv.projectSlug ? projectBySlug.get(inv.projectSlug) : undefined;
+      await ctx.db.unsafe.insert("Invoice", {
+        number: inv.number,
+        clientId,
+        clientName: inv.client,
+        projectId: project?.id ?? null,
+        projectTitle: project?.title ?? (inv.projectSlug ? titleBySlug.get(inv.projectSlug) ?? null : null),
+        lineItems: JSON.stringify(inv.lineItems),
+        amountCents: lineItemsTotal(inv.lineItems),
+        status: inv.status ?? "draft",
+        issuedAt: inv.issuedAt ?? null,
+        dueAt: inv.dueAt ?? null,
+        notes: null,
+        createdAt: now,
+      });
+    }
+
+    return { seeded: true };
+  },
+});

package/templates/agency/functions/setInvoiceStatus.ts

@@ -0,0 +1,27 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// setInvoiceStatus — owner-only. Move a bill along its lifecycle
+// (draft → sent → paid, or → overdue) without re-opening the full editor. The
+// dashboard's per-invoice status menu calls this.
+const STATUSES = new Set(["draft", "sent", "paid", "overdue"]);
+
+export default mutation<{ id: string; status: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Invoice"), status: v.string() },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage invoices.");
+    }
+    const status = args.status.trim();
+    if (!STATUSES.has(status)) {
+      throw ctx.error("INVALID_ARGS", "Status must be draft, sent, paid, or overdue.");
+    }
+    const invoice = await ctx.db.get("Invoice", args.id);
+    if (!invoice) throw ctx.error("NOT_FOUND", "Invoice not found.");
+
+    await ctx.db.unsafe.update("Invoice", args.id, { status });
+    return { ok: true };
+  },
+});

package/templates/agency/functions/setProjectFlags.ts

@@ -0,0 +1,35 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// setProjectFlags — owner-only. A quick toggle for the two flags the owner flips
+// most: `selected` (feature it on the homepage) and `published` (show it on the
+// public site at all). Separate from the full upsertProject so the dashboard can
+// flip a switch without round-tripping the whole form. Pass only the flag(s) you
+// want to change.
+export default mutation<
+  { id: string; selected?: boolean; published?: boolean },
+  { ok: boolean }
+>({
+  auth: "user",
+  args: {
+    id: v.id("Project"),
+    selected: v.optional(v.boolean()),
+    published: v.optional(v.boolean()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage projects.");
+    }
+    const project = await ctx.db.get("Project", args.id);
+    if (!project) throw ctx.error("NOT_FOUND", "Project not found.");
+
+    const patch: Record<string, boolean> = {};
+    if (typeof args.selected === "boolean") patch.selected = args.selected;
+    if (typeof args.published === "boolean") patch.published = args.published;
+    if (Object.keys(patch).length > 0) {
+      await ctx.db.unsafe.update("Project", args.id, patch);
+    }
+    return { ok: true };
+  },
+});

package/templates/agency/functions/upsertClient.ts

@@ -0,0 +1,73 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { ClientRow } from "../lib/agency";
+
+// upsertClient — owner-only. Create a CRM contact or edit one (pass `id`). When
+// a client's name or company changes, any invoice that referenced it keeps its
+// denormalized `clientName` from when it was issued — invoices are a financial
+// record and shouldn't silently rewrite themselves; the link by `clientId`
+// still resolves for navigation.
+type Args = {
+  id?: string;
+  name: string;
+  company?: string;
+  email?: string;
+  phone?: string;
+  status?: string;
+  notes?: string;
+};
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const STATUSES = new Set(["prospect", "active", "past"]);
+const clip = (s: string | undefined, max: number): string | null =>
+  s != null && s.trim().length > 0 ? s.trim().slice(0, max) : null;
+
+export default mutation<Args, { ok: boolean; id: string }>({
+  auth: "user",
+  args: {
+    id: v.optional(v.string()),
+    name: v.string(),
+    company: v.optional(v.string()),
+    email: v.optional(v.string()),
+    phone: v.optional(v.string()),
+    status: v.optional(v.string()),
+    notes: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage clients.");
+    }
+    const name = args.name.trim();
+    if (name.length < 1 || name.length > 120) {
+      throw ctx.error("INVALID_ARGS", "A client name is required (up to 120 chars).");
+    }
+    const email = clip(args.email, 254);
+    if (email && !EMAIL_RE.test(email)) {
+      throw ctx.error("INVALID_ARGS", "Enter a valid email address.");
+    }
+    const status = STATUSES.has((args.status ?? "").trim()) ? args.status!.trim() : "prospect";
+
+    const patch = {
+      name,
+      company: clip(args.company, 160),
+      email,
+      phone: clip(args.phone, 40),
+      status,
+      notes: clip(args.notes, 2000),
+    };
+
+    if (args.id) {
+      const existing = (await ctx.db.get("Client", args.id)) as ClientRow | null;
+      if (!existing) throw ctx.error("NOT_FOUND", "Client not found.");
+      await ctx.db.unsafe.update("Client", args.id, patch);
+      return { ok: true, id: args.id };
+    }
+
+    const id = await ctx.db.unsafe.insert("Client", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id };
+  },
+});

package/templates/agency/functions/upsertInvoice.ts

@@ -0,0 +1,113 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { lineItemsTotal, type ClientRow, type InvoiceLineItem, type ProjectRow } from "../lib/agency";
+
+// upsertInvoice — owner-only. Create a bill or edit one (pass `id`). The client
+// is referenced by id and must exist; we denormalize its name onto the invoice
+// (`clientName`) so the list renders without a join, and so the bill keeps the
+// name it was issued under even if the contact is renamed later. An optional
+// project link works the same way (`projectTitle`).
+//
+// `lineItems` is the source of truth for the amount: when present we store it
+// (JSON) and compute `amountCents = Σ quantity × unitCents` server-side, so the
+// total can never disagree with the breakdown the client sent. When omitted we
+// fall back to the explicit `amountCents` (a one-line bill). Amounts are cents.
+type Args = {
+  id?: string;
+  number: string;
+  clientId: string;
+  projectId?: string;
+  lineItems?: InvoiceLineItem[];
+  amountCents: number;
+  status?: string;
+  issuedAt?: string;
+  dueAt?: string;
+  notes?: string;
+};
+
+const STATUSES = new Set(["draft", "sent", "paid", "overdue"]);
+const clip = (s: string | undefined, max: number): string | null =>
+  s != null && s.trim().length > 0 ? s.trim().slice(0, max) : null;
+
+export default mutation<Args, { ok: boolean; id: string }>({
+  auth: "user",
+  args: {
+    id: v.optional(v.string()),
+    number: v.string(),
+    clientId: v.string(),
+    projectId: v.optional(v.string()),
+    lineItems: v.optional(
+      v.array(
+        v.object({ description: v.string(), quantity: v.number(), unitCents: v.int() }),
+      ),
+    ),
+    amountCents: v.int(),
+    status: v.optional(v.string()),
+    issuedAt: v.optional(v.string()),
+    dueAt: v.optional(v.string()),
+    notes: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage invoices.");
+    }
+    const number = args.number.trim();
+    if (number.length < 1 || number.length > 40) {
+      throw ctx.error("INVALID_ARGS", "An invoice number is required.");
+    }
+
+    const client = (await ctx.db.get("Client", args.clientId)) as ClientRow | null;
+    if (!client) throw ctx.error("INVALID_ARGS", "Pick a client for this invoice.");
+
+    let projectId: string | null = null;
+    let projectTitle: string | null = null;
+    if (args.projectId) {
+      const project = (await ctx.db.get("Project", args.projectId)) as ProjectRow | null;
+      if (project) {
+        projectId = project.id;
+        projectTitle = project.title;
+      }
+    }
+
+    // Normalize line items; when present they define the total.
+    const items: InvoiceLineItem[] = (args.lineItems ?? [])
+      .map((it) => ({
+        description: (it.description ?? "").trim().slice(0, 300),
+        quantity: Math.max(0, Number(it.quantity) || 0),
+        unitCents: Math.max(0, Math.trunc(Number(it.unitCents) || 0)),
+      }))
+      .filter((it) => it.description.length > 0 || it.unitCents > 0);
+
+    const amountCents =
+      items.length > 0 ? lineItemsTotal(items) : Math.max(0, Math.trunc(args.amountCents || 0));
+    const status = STATUSES.has((args.status ?? "").trim()) ? args.status!.trim() : "draft";
+
+    const patch = {
+      number,
+      clientId: client.id,
+      clientName: client.name,
+      projectId,
+      projectTitle,
+      lineItems: items.length > 0 ? JSON.stringify(items) : null,
+      amountCents,
+      status,
+      issuedAt: clip(args.issuedAt, 20),
+      dueAt: clip(args.dueAt, 20),
+      notes: clip(args.notes, 2000),
+    };
+
+    if (args.id) {
+      const existing = await ctx.db.get("Invoice", args.id);
+      if (!existing) throw ctx.error("NOT_FOUND", "Invoice not found.");
+      await ctx.db.unsafe.update("Invoice", args.id, patch);
+      return { ok: true, id: args.id };
+    }
+
+    const id = await ctx.db.unsafe.insert("Invoice", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id };
+  },
+});

package/templates/agency/functions/upsertProject.ts

@@ -0,0 +1,97 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { slugify, type ProjectRow } from "../lib/agency";
+
+// upsertProject — owner-only. Create a new case study or edit an existing one
+// (pass `id` to update). Projects are public-read, so the change shows up on the
+// dashboard's live `db.useQuery("Project")` immediately, and on the marketing
+// site on its next render. The slug is derived from the title (or an explicit
+// slug) and made unique — a unique index backs it, so we resolve collisions
+// here rather than letting the insert fail.
+type Args = {
+  id?: string;
+  title: string;
+  slug?: string;
+  client?: string;
+  summary?: string;
+  year?: string;
+  tags?: string;
+  selected?: boolean;
+  published?: boolean;
+  order?: number;
+  challenge?: string;
+  approach?: string;
+  outcome?: string;
+  liveUrl?: string;
+};
+
+const clip = (s: string | undefined, max: number): string | null =>
+  s != null && s.trim().length > 0 ? s.trim().slice(0, max) : null;
+
+export default mutation<Args, { ok: boolean; id: string; slug: string }>({
+  auth: "user",
+  args: {
+    id: v.optional(v.string()),
+    title: v.string(),
+    slug: v.optional(v.string()),
+    client: v.optional(v.string()),
+    summary: v.optional(v.string()),
+    year: v.optional(v.string()),
+    tags: v.optional(v.string()),
+    selected: v.optional(v.boolean()),
+    published: v.optional(v.boolean()),
+    order: v.optional(v.int()),
+    challenge: v.optional(v.string()),
+    approach: v.optional(v.string()),
+    outcome: v.optional(v.string()),
+    liveUrl: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage projects.");
+    }
+    const title = args.title.trim();
+    if (title.length < 1 || title.length > 120) {
+      throw ctx.error("INVALID_ARGS", "A project title is required (up to 120 chars).");
+    }
+
+    await ctx.db.advisoryLock("agency_projects");
+    const all = (await ctx.db.unsafe.list("Project")) as unknown as ProjectRow[];
+
+    // Resolve a unique slug (skip the row being edited).
+    const base = slugify(args.slug || title) || "project";
+    let slug = base;
+    let n = 2;
+    while (all.some((p) => p.slug === slug && p.id !== args.id)) slug = `${base}-${n++}`;
+
+    const patch = {
+      title,
+      slug,
+      client: clip(args.client, 120) ?? "",
+      summary: clip(args.summary, 300) ?? "",
+      year: clip(args.year, 12),
+      tags: clip(args.tags, 200),
+      selected: args.selected === true,
+      published: args.published !== false, // default published
+      order: Math.trunc(args.order ?? 0),
+      challenge: clip(args.challenge, 2000),
+      approach: clip(args.approach, 2000),
+      outcome: clip(args.outcome, 2000),
+      liveUrl: clip(args.liveUrl, 400),
+    };
+
+    if (args.id) {
+      const existing = all.find((p) => p.id === args.id);
+      if (!existing) throw ctx.error("NOT_FOUND", "Project not found.");
+      await ctx.db.unsafe.update("Project", args.id, patch);
+      return { ok: true, id: args.id, slug };
+    }
+
+    const id = await ctx.db.unsafe.insert("Project", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id, slug };
+  },
+});