create-m5kdev 0.35.0 → 0.37.2

package/templates/minimal-app/apps/e2e/tests/standard.spec.ts.tpl

@@ -3,8 +3,10 @@ import {
   authFetch,
   clearEmails,
   createProvisionedClaimUser,
+  createTrpcClient,
   emailUrl,
   expectLoginRejected,
+  findMemberByEmail,
   getUserState,
   latestEmail,
   login,
@@ -29,6 +31,43 @@ async function createVerifiedAccount(
   await verifyLatestEmail(request, profile, email);
 }
 
+async function inviteFromMembersPage(page: Page, email: string) {
+  await page.goto("/organization/members");
+  await expect(page.getByRole("button", { name: /^invite$/i })).toBeEnabled();
+  await page.locator('input[type="email"]').fill(email);
+  const inviteResponsePromise = page.waitForResponse(
+    (response) =>
+      response.request().method() === "POST" && response.url().includes("inviteOrganizationMember")
+  );
+  await page.getByRole("button", { name: /^invite$/i }).click();
+  const inviteResponse = await inviteResponsePromise;
+  expect(
+    inviteResponse.ok(),
+    `${inviteResponse.status()} ${inviteResponse.statusText()}: ${await inviteResponse.text()}`
+  ).toBe(true);
+  const invitedRow = page.getByRole("row").filter({ hasText: email });
+  await expect(invitedRow.getByText(/^invited$/i)).toBeVisible();
+  return invitedRow;
+}
+
+async function listOrganizationMembers(page: Page) {
+  const trpc = await createTrpcClient(page, profile);
+  return trpc.auth.listOrganizationMembers.query();
+}
+
+async function expectBetterAuthInviteForbidden(page: Page, email: string) {
+  const response = await authFetch(page, profile, "/api/auth/organization/invite-member", {
+    method: "POST",
+    body: {
+      organizationId: enterpriseOrgId,
+      email,
+      role: "member",
+    },
+  });
+  expect(response.ok, `${response.status} ${response.statusText}: ${response.text}`).toBe(false);
+  expect(response.status).toBe(403);
+}
+
 test.beforeEach(async ({ request }) => {
   await clearEmails(request, profile);
 });
@@ -52,7 +91,7 @@ test("signup, verification email, login, protected app, and logout", async ({ pa
 
   await login(page, email, password);
   await expect(page.getByTestId("posts-route")).toBeVisible();
-  await expect(page.getByText(/small blog that protects auth changes/i).first()).toBeVisible();
+  await expect(page.getByRole("button", { name: /create post/i })).toBeVisible();
 
   await logout(page);
 });
@@ -144,14 +183,19 @@ test("organization invite email lets a new user join without creating a separate
   const invitee = `member.${Date.now()}@auth-e2e.local`;
 
   await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
-  await page.goto("/organization/members");
-  await page.locator('input[type="email"]').fill(invitee);
-  await page.getByRole("button", { name: /invite/i }).click();
+  await inviteFromMembersPage(page, invitee);
+
+  const invited = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(invited?.userId).toBeNull();
+  expect(invited?.invitationId).toBeTruthy();
+  const invitedMemberId = invited?.id;
+  expect(invitedMemberId).toBeTruthy();
 
   const invite = await latestEmail(request, profile, {
     to: invitee,
     templateId: "organization-invite",
   });
+  expect(emailUrl(invite)).toContain("/organization/accept-invitation?id=");
 
   await logout(page);
   await page.goto(emailUrl(invite));
@@ -163,7 +207,9 @@ test("organization invite email lets a new user join without creating a separate
   const state = await getUserState(request, profile, invitee);
   expect(state.user.emailVerified).toBe(true);
   expect(state.organizations.map((organization) => organization.id)).toEqual([enterpriseOrgId]);
+  expect(state.organizations[0]?.memberId).toBe(invitedMemberId);
   expect(state.latestSession?.activeOrganizationId).toBe(enterpriseOrgId);
+  expect(state.latestSession?.activeOrganizationMemberId).toBe(invitedMemberId);
 });
 
 test("organization invite lets an existing user join an additional org", async ({
@@ -179,14 +225,16 @@ test("organization invite lets an existing user join an additional org", async (
   expect(beforeInvite.organizations[0]?.id).not.toBe(enterpriseOrgId);
 
   await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
-  await page.goto("/organization/members");
-  await page.locator('input[type="email"]').fill(email);
-  await page.getByRole("button", { name: /invite/i }).click();
+  await inviteFromMembersPage(page, email);
+  const invited = findMemberByEmail(await listOrganizationMembers(page), email);
+  expect(invited?.userId).toBeNull();
+  const invitedMemberId = invited?.id;
 
   const invite = await latestEmail(request, profile, {
     to: email,
     templateId: "organization-invite",
   });
+  expect(emailUrl(invite)).toContain("/organization/accept-invitation?id=");
 
   await logout(page);
   await login(page, email, password);
@@ -203,7 +251,184 @@ test("organization invite lets an existing user join an additional org", async (
   expect(afterInvite.organizations.map((organization) => organization.id)).toContain(
     enterpriseOrgId
   );
+  expect(
+    afterInvite.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId
+  ).toBe(invitedMemberId);
   expect(afterInvite.latestSession?.activeOrganizationId).toBe(enterpriseOrgId);
+  expect(afterInvite.latestSession?.activeOrganizationMemberId).toBe(invitedMemberId);
+});
+
+test("organization members page changes an invited member role before they accept", async ({
+  page,
+  request,
+}) => {
+  const invitee = `invite-role.${Date.now()}@auth-e2e.local`;
+
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await inviteFromMembersPage(page, invitee);
+  const invited = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(invited?.role).toBe("member");
+  expect(invited?.userId).toBeNull();
+  const invitedMemberId = invited?.id;
+  expect(invitedMemberId).toBeTruthy();
+
+  const invitedRow = page.getByRole("row").filter({ hasText: invitee });
+  await invitedRow.getByRole("button", { name: `Role for ${invitee}` }).click();
+  const roleResponsePromise = page.waitForResponse(
+    (response) =>
+      response.request().method() === "POST" && response.url().includes("updateMemberRole")
+  );
+  await page.getByRole("option", { name: /^Admin$/ }).click();
+  const roleResponse = await roleResponsePromise;
+  expect(
+    roleResponse.ok(),
+    `${roleResponse.status()} ${roleResponse.statusText()}: ${await roleResponse.text()}`
+  ).toBe(true);
+
+  const afterRole = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(afterRole?.id).toBe(invitedMemberId);
+  expect(afterRole?.role).toBe("admin");
+  expect(afterRole?.userId).toBeNull();
+  expect(afterRole?.invitationId).toBeTruthy();
+
+  const invite = await latestEmail(request, profile, {
+    to: invitee,
+    templateId: "organization-invite",
+  });
+  await logout(page);
+  await page.goto(emailUrl(invite));
+  await expect(page).toHaveURL(/\/signup/);
+  await page.locator('[name="signup-password"]').fill("password1234");
+  await page.getByRole("button", { name: /sign up/i }).click();
+  await expect(page.getByTestId("session-email")).toContainText(invitee);
+
+  const state = await getUserState(request, profile, invitee);
+  expect(state.organizations).toEqual([
+    expect.objectContaining({
+      id: enterpriseOrgId,
+      memberId: invitedMemberId,
+      role: "admin",
+    }),
+  ]);
+});
+
+test("organization members page resends, updates, cancels, and revives an invited seat", async ({
+  page,
+}) => {
+  const invitee = `invite-manage.${Date.now()}@auth-e2e.local`;
+
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await inviteFromMembersPage(page, invitee);
+  const firstSeat = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  const memberId = firstSeat?.id;
+  expect(memberId).toBeTruthy();
+
+  await inviteFromMembersPage(page, invitee);
+  const resent = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(resent?.id).toBe(memberId);
+  expect(resent?.userId).toBeNull();
+
+  const invitedRow = page.getByRole("row").filter({ hasText: invitee });
+  await invitedRow.getByRole("button", { name: `Role for ${invitee}` }).click();
+  await page.getByRole("option", { name: /^Admin$/ }).click();
+  await expect(page.getByText(/member role updated/i)).toBeVisible();
+  await expect
+    .poll(async () => findMemberByEmail(await listOrganizationMembers(page), invitee)?.role)
+    .toBe("admin");
+
+  await invitedRow.getByRole("button", { name: /cancel invitation/i }).click();
+  await expect(page.getByText(/invitation canceled/i)).toBeVisible();
+  await expect(invitedRow).toBeHidden();
+  expect(findMemberByEmail(await listOrganizationMembers(page), invitee)).toBeUndefined();
+
+  await inviteFromMembersPage(page, invitee);
+  const revived = findMemberByEmail(await listOrganizationMembers(page), invitee);
+  expect(revived?.id).toBe(memberId);
+  expect(revived?.userId).toBeNull();
+});
+
+test("organization members page refuses a live member invite, then remove and leave drop the seat", async ({
+  page,
+  request,
+}) => {
+  const email = `live-member.${Date.now()}@auth-e2e.local`;
+  const password = "password1234";
+
+  await createVerifiedAccount(page, request, email, password);
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await inviteFromMembersPage(page, email);
+  const invitedMemberId = findMemberByEmail(await listOrganizationMembers(page), email)?.id;
+
+  const invite = await latestEmail(request, profile, {
+    to: email,
+    templateId: "organization-invite",
+  });
+  await logout(page);
+  await login(page, email, password);
+  await page.goto(emailUrl(invite));
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return (
+        state.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId ??
+        null
+      );
+    })
+    .toBe(invitedMemberId);
+
+  await logout(page);
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await page.goto("/organization/members");
+  await page.locator('input[type="email"]').fill(email);
+  await page.getByRole("button", { name: /^invite$/i }).click();
+  await expect(page.getByText(/live membership already exists/i)).toBeVisible();
+
+  const memberRow = page.getByRole("row").filter({ hasText: email });
+  await expect(memberRow.getByText(/^active$/i)).toBeVisible();
+  await memberRow.getByRole("button", { name: /remove member/i }).click();
+  await expect(page.getByText(/member removed/i)).toBeVisible();
+  await expect(memberRow).toBeHidden();
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.some((organization) => organization.id === enterpriseOrgId);
+    })
+    .toBe(false);
+
+  await inviteFromMembersPage(page, email);
+  const revived = findMemberByEmail(await listOrganizationMembers(page), email);
+  expect(revived?.id).toBe(invitedMemberId);
+
+  const reinvite = await latestEmail(request, profile, {
+    to: email,
+    templateId: "organization-invite",
+  });
+  await logout(page);
+  await login(page, email, password);
+  await page.goto(emailUrl(reinvite));
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return (
+        state.organizations.find((organization) => organization.id === enterpriseOrgId)?.memberId ??
+        null
+      );
+    })
+    .toBe(invitedMemberId);
+
+  const memberTrpc = await createTrpcClient(page, profile);
+  await memberTrpc.auth.leaveOrganization.mutate();
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.some((organization) => organization.id === enterpriseOrgId);
+    })
+    .toBe(false);
+});
+
+test("Better Auth organization invite HTTP is not a public invite path", async ({ page }) => {
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await expectBetterAuthInviteForbidden(page, `ba-invite.${Date.now()}@auth-e2e.local`);
 });
 
 test("admin creates, bans, unbans, and authenticates a user", async ({ page, request }) => {
@@ -318,7 +543,7 @@ test("admin manages organization members from organization admin", async ({ page
     })
     .toBe("member");
 
-  await memberRow.getByRole("button", { name: `Member Role for ${email}` }).click();
+  await memberRow.getByRole("button", { name: `Role for ${email}` }).click();
   await page.getByRole("option", { name: /^Admin$/ }).click();
   await expect
     .poll(async () => {
@@ -340,6 +565,63 @@ test("admin manages organization members from organization admin", async ({ page
     .toBe(false);
 });
 
+test("admin transfers organization ownership to an active member", async ({ page, request }) => {
+  const email = `org-owner.${Date.now()}@auth-e2e.local`;
+  const password = "password1234";
+  const childOrgName = `Transfer Org ${Date.now()}`;
+
+  await createVerifiedAccount(page, request, email, password);
+  await login(page, profiles.standard.adminEmail, profiles.standard.adminPassword);
+  await page.goto("/organization/manage");
+  await page.getByRole("button", { name: /new organization/i }).click();
+  const createDialog = page.getByRole("dialog");
+  await createDialog.getByPlaceholder(/acme subsidiary/i).fill(childOrgName);
+  await createDialog.getByRole("button", { name: /create organization/i }).click();
+  await expect(page.getByText(childOrgName)).toBeVisible();
+
+  await page.goto("/admin/organizations");
+  await page.locator('input[name="search"]').fill(childOrgName);
+  const organizationRow = page.getByRole("row").filter({ hasText: childOrgName });
+  await expect(organizationRow).toBeVisible();
+  await organizationRow.getByLabel(/manage members/i).click();
+
+  const dialog = page.getByRole("dialog").filter({ hasText: "Manage Members" });
+  await expect(dialog.getByText(childOrgName)).toBeVisible();
+  await dialog.getByText("Select user", { exact: true }).click();
+  await page.getByPlaceholder("Search users...").fill(email);
+  await page.getByRole("option", { name: new RegExp(email) }).click();
+  await dialog.getByRole("button", { name: /add member/i }).click();
+
+  const memberRow = dialog.getByRole("row").filter({ hasText: email });
+  await expect(memberRow).toBeVisible();
+  await expect(memberRow.getByRole("button", { name: `Transfer owner to ${email}` })).toBeVisible();
+
+  const transferResponsePromise = page.waitForResponse(
+    (response) =>
+      response.request().method() === "POST" && response.url().includes("transferOrganizationOwner")
+  );
+  await memberRow.getByRole("button", { name: `Transfer owner to ${email}` }).click();
+  const transferResponse = await transferResponsePromise;
+  expect(
+    transferResponse.ok(),
+    `${transferResponse.status()} ${transferResponse.statusText()}: ${await transferResponse.text()}`
+  ).toBe(true);
+
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, email);
+      return state.organizations.find((organization) => organization.name === childOrgName)?.role;
+    })
+    .toBe("owner");
+  await expect
+    .poll(async () => {
+      const state = await getUserState(request, profile, profiles.standard.adminEmail);
+      return state.organizations.find((organization) => organization.name === childOrgName)?.role;
+    })
+    .toBe("admin");
+  await expect(memberRow.getByRole("button", { name: `Transfer owner to ${email}` })).toBeHidden();
+});
+
 test("admin organization pagination stays on the selected page", async ({ page, request }) => {
   const prefix = `Pagination Org ${Date.now()}`;
   await seedOrganizations(request, profile, { prefix, count: 12 });

package/templates/minimal-app/apps/expo/app.json.tpl

@@ -19,6 +19,7 @@
     },
     "plugins": [
       "expo-router",
+      "expo-notifications",
       [
         "expo-splash-screen",
         {

package/templates/minimal-app/apps/expo/package.json.tpl

@@ -21,11 +21,14 @@
     "@expo/metro-runtime": "~56.0.13",
     "@gorhom/bottom-sheet": "^5.2.14",
     "@m5kdev/commons": "catalog:m5kdev",
+    "@m5kdev/expo": "catalog:m5kdev",
     "@m5kdev/frontend": "catalog:m5kdev",
     "@trpc/client": "catalog:m5kdev",
+    "@tanstack/react-query": "catalog:m5kdev",
     "expo": "~56.0.5",
     "expo-constants": "~56.0.16",
     "expo-linking": "~56.0.12",
+    "expo-notifications": "~56.0.18",
     "expo-router": "~56.2.7",
     "expo-splash-screen": "~56.0.10",
     "expo-status-bar": "~56.0.4",
@@ -47,6 +50,7 @@
     "uniwind": "^1.5.0"
   },
   "devDependencies": {
+    "{{PACKAGE_SCOPE}}/server": "workspace:*",
     "@biomejs/biome": "catalog:m5kdev",
     "@m5kdev/backend": "catalog:m5kdev",
     "@m5kdev/config": "catalog:m5kdev",

package/templates/minimal-app/apps/expo/src/app/_layout.tsx.tpl

@@ -1,4 +1,5 @@
 import { AppConfigProvider } from "@m5kdev/frontend/modules/app/components/AppConfigProvider";
+import { AppTrpcQueryProvider } from "@m5kdev/frontend/modules/app/components/AppTrpcQueryProvider";
 import { AuthProvider } from "@m5kdev/frontend/modules/auth/components/AuthProvider";
 import { APP_NAME } from "{{PACKAGE_SCOPE}}/shared/modules/app/app.constants";
 import { Stack } from "expo-router";
@@ -22,7 +23,9 @@ export default function RootLayout(): JSX.Element {
           }}
         >
           <AuthProvider loader={<LoadingScreen />}>
-            <Stack screenOptions={{ headerShown: false }} />
+            <AppTrpcQueryProvider>
+              <Stack screenOptions={{ headerShown: false }} />
+            </AppTrpcQueryProvider>
           </AuthProvider>
         </AppConfigProvider>
       </HeroUINativeProvider>

package/templates/minimal-app/apps/expo/src/app/notifications.tsx.tpl

@@ -0,0 +1,70 @@
+import { useNativePush } from "@m5kdev/expo/hooks/useNativePush";
+import { NotificationInbox } from "@m5kdev/expo/modules/notification/components/NotificationInbox";
+import { useSession } from "@m5kdev/frontend/modules/auth/hooks/useSession";
+import { Link, Redirect } from "expo-router";
+import { Button, Card, Typography } from "heroui-native";
+import { ScrollView, Text, View } from "react-native";
+import { useTRPC } from "../lib/trpc";
+
+export default function NotificationsScreen() {
+  const { data: session } = useSession();
+  const trpc = useTRPC();
+  const nativePush = useNativePush({
+    enabled: Boolean(session?.user?.id),
+    messages: {
+      unsupported: "Native push is not available on this platform.",
+      denied: "Notification permission was denied.",
+      noToken: "Could not read a device push token.",
+      failed: "Could not register this device.",
+      enabled: "This device is registered for push.",
+    },
+    registerDeviceMutation: trpc.notification.registerDevice.mutationOptions(),
+  });
+
+  if (!session) {
+    return <Redirect href="/login" />;
+  }
+
+  const pushLabel =
+    nativePush.flowStatus === "done"
+      ? "This device is registered for push."
+      : nativePush.permission === "denied"
+        ? "Notification permission was denied."
+        : "Enable push for this device";
+
+  return (
+    <ScrollView className="flex-1 bg-background" contentContainerClassName="px-5 py-8">
+      <View className="gap-5">
+        <View className="gap-2">
+          <Text className="text-3xl font-semibold text-foreground">Notifications</Text>
+          <Typography.Paragraph className="text-default-600">
+            Inbox for this membership. Push registration is this User's device.
+          </Typography.Paragraph>
+        </View>
+        <Card className="gap-3 p-5">
+          <Text className="text-lg font-semibold text-foreground">This device</Text>
+          <Button
+            isDisabled={!nativePush.canSubscribe || nativePush.isWorking}
+            onPress={() => {
+              void nativePush.subscribe();
+            }}
+          >
+            {pushLabel}
+          </Button>
+          {nativePush.feedback ? (
+            <Typography.Paragraph className="text-default-600">
+              {nativePush.feedback}
+            </Typography.Paragraph>
+          ) : null}
+        </Card>
+        <Card className="gap-3 p-5">
+          <Text className="text-lg font-semibold text-foreground">Inbox</Text>
+          <NotificationInbox />
+        </Card>
+        <Link href="/posts" asChild>
+          <Button variant="outline">Back to posts</Button>
+        </Link>
+      </View>
+    </ScrollView>
+  );
+}

package/templates/minimal-app/apps/expo/src/app/organization/accept-invitation.tsx.tpl

@@ -46,22 +46,14 @@ export default function AcceptInvitationScreen() {
       return;
     }
 
-    authClient.organization
-      .acceptInvitation({ invitationId })
-      .then(async ({ data, error }) => {
-        if (error) {
-          throw new Error(error.message ?? "Unable to accept invitation");
-        }
-
-        const organizationId =
-          (data as { invitation?: { organizationId?: string } | null } | null)?.invitation
-            ?.organizationId ?? null;
-
-        if (organizationId) {
-          const activeResult = await authClient.organization.setActive({ organizationId });
-          if (activeResult.error) {
-            throw new Error(activeResult.error.message ?? "Unable to activate organization");
-          }
+    trpcClient.auth.acceptOrganizationInvitation
+      .mutate({ id: invitationId })
+      .then(async (accepted) => {
+        const activeResult = await authClient.organization.setActive({
+          organizationId: accepted.organizationId,
+        });
+        if (activeResult.error) {
+          throw new Error(activeResult.error.message ?? "Unable to activate organization");
         }
 
         if (!cancelled) {

package/templates/minimal-app/apps/expo/src/app/posts.tsx.tpl

@@ -1,5 +1,5 @@
 import { useSession } from "@m5kdev/frontend/modules/auth/hooks/useSession";
-import { Link, Redirect } from "expo-router";
+import { type Href, Link, Redirect } from "expo-router";
 import { Button, Card, Typography } from "heroui-native";
 import { ScrollView, Text, View } from "react-native";
 
@@ -29,6 +29,9 @@ export default function PostsScreen() {
             @m5kdev/frontend.
           </Typography.Paragraph>
         </Card>
+        <Link href={"/notifications" as Href} asChild>
+          <Button variant="outline">Notifications</Button>
+        </Link>
         <Link href="/logout" asChild>
           <Button testID="logout-submit" variant="outline">
             Logout

package/templates/minimal-app/apps/expo/src/lib/trpc.ts.tpl

@@ -1,9 +1,10 @@
-import type { BackendTRPCRouter } from "@m5kdev/backend/types";
 import { transformer } from "@m5kdev/commons/utils/trpc";
+import { useAppTRPC, useAppTRPCClient } from "@m5kdev/frontend/modules/app/hooks/useAppTrpc";
+import type { AppRouter } from "{{PACKAGE_SCOPE}}/server/types";
 import { createTRPCClient, httpBatchLink } from "@trpc/client";
 import { serverUrl } from "../config";
 
-export const trpcClient = createTRPCClient<BackendTRPCRouter>({
+export const trpcClient = createTRPCClient<AppRouter>({
   links: [
     httpBatchLink({
       url: `${serverUrl}/trpc`,
@@ -18,3 +19,11 @@ export const trpcClient = createTRPCClient<BackendTRPCRouter>({
     }),
   ],
 });
+
+export function useTRPC() {
+  return useAppTRPC<AppRouter>();
+}
+
+export function useTRPCClient() {
+  return useAppTRPCClient<AppRouter>();
+}

package/templates/minimal-app/apps/landing/vite.config.ts.tpl

@@ -18,8 +18,7 @@ export default defineConfig({
     dedupe: ["react", "react-dom", "react-router"],
   },
   envDir: "../shared",
-  preview: {
-    host: "0.0.0.0",
-    port: 8080,
+  server: {
+    port: 5174,
   },
 });

package/templates/minimal-app/apps/server/AGENTS.md.tpl

@@ -20,6 +20,9 @@ apps/server/src/modules/<module>/
 ├── <module>.repository.ts
 ├── <module>.service.ts
 ├── <module>.trpc.ts
+// m5k:mcp:start
+├── <module>.mcp.ts
+// m5k:mcp:end
 └── <module>.module.ts
 ```
 
@@ -28,6 +31,9 @@ apps/server/src/modules/<module>/
 - Repositories own persistence and query construction.
 - Services own business rules, orchestration, and context-aware defaults.
 - tRPC files own transport only and must delegate to services.
+// m5k:mcp:start
+- MCP call maps live in `<module>.mcp.ts` and are contributed from `mcp()` / `mcpUser()`. Delegate to Procedures or unguarded service methods; do not scrape Service properties.
+// m5k:mcp:end
 - Register Core Modules and app modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`. Do not use `backendApp.use`. Optional Backend Modules (`@m5kdev/module-*`) are not scaffolded; add them only when the product needs Clay, Docx, Pdf, Social, or Video.
 // m5k:ai:start
 - `AIModule` is registered in `app.ts` with an app-owned Mastra Agent (`assistant`). Conversation HTTP lives on `/ai`. Set `OPENROUTER_API_KEY` for live replies. Do not add a Starter service wrapper around `AIService` chat.
@@ -50,6 +56,10 @@ apps/server/src/modules/<module>/
 - `index.ts` calls `builtBackendApp.start()`, which listens and handles SIGINT/SIGTERM. Extra shutdown work (telemetry) is `onShutdown` on `createBackendApp`.
 - After changing Drizzle tables, run `pnpm --filter ./apps/server drizzle:generate` then `drizzle:migrate` — do not hand-edit SQL migrations in this repo.
 
+// m5k:mcp:start
+- `McpModule` is registered in `app.ts`. MCP clients authenticate with Better Auth MCP OAuth (not API keys). Compose `auth.oauth.db` plus `mcpAllowlistEntries`. Contribute Organization-scoped calls from `posts.mcp.ts`. Omit the module to disable MCP.
+// m5k:mcp:end
+
 // m5k:notifications:start
 - `NotificationModule` is registered in `app.ts` when this feature is selected. Push-related server env vars are documented in `apps/shared/.env.example`.
 // m5k:notifications:end