feat: update boilerplate skill for per-DB architecture

- Update environment config: single NEXT_PUBLIC_DB_NAME instead of three endpoints
- Update SDK structure: @sdk/admin, @sdk/auth, @sdk/app
- Update project structure: hooks/admin/, hooks/auth/
- Add SDK usage examples and import patterns
- Add 'Building Your App' section
- Update troubleshooting table

Author: theothersideofgod

skills/constructive-starter-kits/references/nextjs-app.md

@@ -17,11 +17,19 @@ Use this skill when:
 
 The Constructive App boilerplate is a **frontend-only** Next.js application that connects to a Constructive backend. It provides production-ready authentication flows, organization management, invite handling, member management, and account settings — all powered by a generated GraphQL SDK.
 
+**Per-DB Architecture**: The boilerplate uses three separate SDK contexts, each pointing to a different API endpoint:
+
+| SDK | Endpoint | Purpose |
+|-----|----------|---------|
+| `@sdk/admin` | `admin-{db}.localhost:3000` | Organizations, members, permissions, invites |
+| `@sdk/auth` | `auth-{db}.localhost:3000` | Users, emails, authentication |
+| `@sdk/app` | `app-public-{db}.localhost:3000` | Your business data (tables you created) |
+
 ## Setup
 
 ### 1. Clone the Boilerplate
 
-Use `pgpm init` with the `-w` flag to scaffold a workspace from the template. All required arguments must be provided to avoid interactive prompts:
+Use `pgpm init` with the `-w` flag to scaffold a workspace from the template:
 
 ```bash
 pgpm init -w \
@@ -36,7 +44,7 @@ pgpm init -w \
   --moduleName <module-name>
 ```
 
-**Required arguments for non-interactive mode (avoid asking for user input):**
+**Required arguments for non-interactive mode:**
 
 | Argument | Description |
 |----------|-------------|
@@ -50,14 +58,9 @@ pgpm init -w \
 
 The boilerplate is created at `<workspace-name>/packages/<module-name>/`.
 
-> **Interactive mode (for humans):** Prompt will be asking for the arguments missing from the required arguments list:
-> ```bash
-> pgpm init -w --repo constructive-io/sandbox-templates --template nextjs/constructive-app
-> ```
-
 #### Adding to an Existing Workspace
 
-If you already have a pnpm workspace (a directory with `pnpm-workspace.yaml`), use `pgpm init` **without** the `-w` flag to clone the boilerplate as a new module inside it. Run this from the **workspace root**:
+If you already have a pnpm workspace, use `pgpm init` **without** the `-w` flag:
 
 ```bash
 pgpm init \
@@ -66,21 +69,6 @@ pgpm init \
   --moduleName <module-name>
 ```
 
-**Required arguments for existing workspace :**
-
-| Argument | Description |
-|----------|-------------|
-| `--moduleName` | Module/package name for the new boilerplate |
-
-This creates the module at `packages/<module-name>/` within your existing workspace. The workspace-level arguments (`--name`, `--fullName`, `--email`, etc.) are **not needed** since the workspace already exists.
-
-> **Note:** You must run this from the workspace root or a valid `packages/` subdirectory. If you are not inside a pnpm workspace, pgpm will error with "Not inside a PNPM workspace." Use the `-w` flag (see above) to create a new workspace and module together.
-
-> **Interactive mode (for humans):** :
-> ```bash
-> pgpm init --repo constructive-io/sandbox-templates --template nextjs/constructive-app
-> ```
-
 ### 2. Install Dependencies
 
 ```bash
@@ -90,11 +78,24 @@ pnpm install
 
 ### 3. Configure Environment
 
-Create or verify `.env.local`:
+Create `.env.local` with your database name:
 
 ```bash
-# GraphQL endpoint (must point to a running Constructive backend)
-NEXT_PUBLIC_SCHEMA_BUILDER_GRAPHQL_ENDPOINT=http://api.localhost:3000/graphql
+# Required: Your provisioned database name
+NEXT_PUBLIC_DB_NAME=your-db-name
+```
+
+This single variable derives all three API endpoints:
+- `admin-{db}.localhost:3000/graphql`
+- `auth-{db}.localhost:3000/graphql`
+- `app-public-{db}.localhost:3000/graphql`
+
+**Optional endpoint overrides** (only if your setup differs from standard):
+
+```bash
+# NEXT_PUBLIC_ADMIN_ENDPOINT=http://admin-mydb.localhost:3000/graphql
+# NEXT_PUBLIC_AUTH_ENDPOINT=http://auth-mydb.localhost:3000/graphql
+# NEXT_PUBLIC_APP_ENDPOINT=http://app-public-mydb.localhost:3000/graphql
 ```
 
 ### 4. Generate GraphQL SDK
@@ -105,7 +106,10 @@ The SDK must be generated against a running backend:
 pnpm codegen
 ```
 
-This runs `@constructive-io/graphql-codegen` using `graphql-codegen.config.ts` and outputs the SDK to `src/graphql/schema-builder-sdk/api`.
+This generates three SDK targets:
+- `src/graphql/sdk/admin/` — Admin operations
+- `src/graphql/sdk/auth/` — Auth operations  
+- `src/graphql/sdk/app/` — Your business data
 
 ### 5. Start Development
 
@@ -115,6 +119,8 @@ pnpm dev
 
 Opens at [http://localhost:3001](http://localhost:3001).
 
+After login, you'll see the **"Start Building Here"** page with instructions for adding your business logic.
+
 ## Backend Requirements
 
 This boilerplate requires a running Constructive backend. The easiest way is via **Constructive Hub**:
@@ -134,8 +140,7 @@ Required backend services:
 | Service | Port | Purpose |
 |---------|------|---------|
 | PostgreSQL | 5432 | Database with Constructive schema |
-| GraphQL Server (Public) | 3000 | API endpoint for app operations |
-| GraphQL Server (Private) | 3002 | Admin operations |
+| GraphQL Server | 3000 | API endpoints (admin, auth, app-public) |
 | Job Service | 8080 | Background job processing |
 | Email Function | 8082 | Email sending via SMTP |
 | Mailpit SMTP | 1025 | Email server (development) |
@@ -147,7 +152,9 @@ Required backend services:
 src/
 ├── app/                        # Next.js App Router pages
 │   ├── layout.tsx              # Root layout with providers
-│   ├── page.tsx                # Home / org listing page
+│   ├── page.tsx                # Home page (Start Building Here)
+│   ├── (authenticated)/        # Protected pages
+│   │   └── organizations/      # Organizations list
 │   ├── login/                  # Login page
 │   ├── register/               # Registration page
 │   ├── forgot-password/        # Password reset request
@@ -167,7 +174,7 @@ src/
 │           ├── members/        # Org members management
 │           └── settings/       # Org settings
 ├── components/
-│   ├── ui/                     # shadcn/ui components (43 components)
+│   ├── ui/                     # shadcn/ui components
 │   ├── auth/                   # Auth forms (login, register, reset, etc.)
 │   ├── organizations/          # Org CRUD components
 │   ├── invites/                # Invite management components
@@ -183,24 +190,116 @@ src/
 ├── graphql/
 │   ├── execute.ts              # GraphQL execution layer
 │   ├── index.ts                # GraphQL exports
-│   ├── typed-document.ts       # Typed document utilities
-│   └── schema-builder-sdk/     # Generated SDK (via codegen)
+│   └── sdk/                    # Generated SDKs
+│       ├── admin/              # Admin SDK (orgs, members, permissions)
+│       ├── auth/               # Auth SDK (users, authentication)
+│       └── app/                # App SDK (your business data)
 ├── hooks/                      # Shared React hooks
 ├── lib/
 │   ├── auth/                   # Auth utilities and context
-│   ├── gql/                    # GraphQL hooks and query factories
+│   ├── gql/
+│   │   └── hooks/
+│   │       ├── admin/          # Admin-related hooks (orgs, members)
+│   │       │   ├── account/    # Account management hooks
+│   │       │   ├── app/        # App-level hooks
+│   │       │   ├── organizations/  # Organization hooks
+│   │       │   └── policies/   # Permission hooks
+│   │       └── auth/           # Auth hooks (login, register, logout)
 │   ├── navigation/             # Route and navigation helpers
 │   ├── permissions/            # Permission checking utilities
-│   ├── constants/              # App constants
-│   ├── logger/                 # Logging utilities
-│   ├── runtime/                # Runtime helpers
-│   ├── utils/                  # General utilities
-│   └── validation/             # Zod schemas and validation
+│   ├── runtime/                # Runtime configuration
+│   └── utils/                  # General utilities
 ├── store/                      # Client state management
 ├── app-config.ts               # App-wide configuration
 └── app-routes.ts               # Route definitions
 ```
 
+## SDK Usage
+
+### Import Examples
+
+```typescript
+// Your business data (from your provisioned tables)
+import { 
+  useYourTableQuery,
+  useCreateYourTableMutation,
+  useUpdateYourTableMutation,
+  useDeleteYourTableMutation 
+} from '@sdk/app';
+
+// Current user & authentication
+import { useCurrentUserQuery, useSignInMutation } from '@sdk/auth';
+
+// Organizations & permissions
+import { useOrgMembershipsQuery, useAppMembershipsQuery } from '@sdk/admin';
+```
+
+### SDK Structure
+
+| SDK | Import | Use For |
+|-----|--------|---------|
+| `@sdk/admin` | `import { ... } from '@sdk/admin'` | Organizations, members, permissions, invites |
+| `@sdk/auth` | `import { ... } from '@sdk/auth'` | Users, emails, signIn, signUp, currentUser |
+| `@sdk/app` | `import { ... } from '@sdk/app'` | Your business tables |
+
+## Building Your App
+
+After login, the home page (`src/app/page.tsx`) shows a guide. To add your business logic:
+
+### 1. Edit the Home Page
+
+Replace the guide content in `src/app/page.tsx` with your main feature:
+
+```typescript
+'use client';
+
+import { useYourTableQuery, useCreateYourTableMutation } from '@sdk/app';
+
+export default function HomePage() {
+  const { data, isLoading } = useYourTableQuery({});
+  const createMutation = useCreateYourTableMutation();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold mb-4">Your Feature</h1>
+      
+      <ul className="space-y-2">
+        {data?.yourTable?.nodes?.map((item) => (
+          <li key={item.id}>{item.name}</li>
+        ))}
+      </ul>
+      
+      <button 
+        onClick={() => createMutation.mutate({ input: { name: 'New Item' } })}
+        className="mt-4 px-4 py-2 bg-primary text-white rounded"
+      >
+        Create New
+      </button>
+    </div>
+  );
+}
+```
+
+### 2. Add New Pages
+
+Create pages in `src/app/(authenticated)/`:
+
+```
+src/app/(authenticated)/your-feature/page.tsx
+```
+
+### 3. Update Sidebar
+
+Edit `src/lib/navigation/sidebar-config.ts` to add navigation items.
+
+### 4. Regenerate SDK After Schema Changes
+
+```bash
+pnpm codegen
+```
+
 ## Customization
 
 ### Branding
@@ -210,7 +309,6 @@ Edit `src/config/branding.ts` to customize:
 - Logo and wordmark paths (relative to `/public`)
 - Company name for legal footer
 - Legal links (disclaimer, privacy policy, etc.)
-- Home path for logo links
 
 ### Adding UI Components
 
@@ -220,18 +318,6 @@ Components use the Constructive shadcn registry:
 npx shadcn@latest add @constructive/<component>
 ```
 
-Registry URL is configured in `components.json`. Components use Base UI primitives, Tailwind CSS 4, and cva for variants.
-
-### GraphQL SDK
-
-The SDK is generated from the running backend schema. After backend schema changes:
-
-```bash
-pnpm codegen
-```
-
-Config in `graphql-codegen.config.ts` points to `http://api.localhost:3000/graphql` by default.
-
 ## Features
 
 - **Authentication** — Login, register, logout, password reset, email verification
@@ -244,7 +330,10 @@ Config in `graphql-codegen.config.ts` points to `http://api.localhost:3000/graph
 
 ## Troubleshooting
 
-- **GraphQL errors on startup**: Ensure the Constructive backend is running and the endpoint in `.env.local` is correct
-- **Empty SDK directory**: Run `pnpm codegen` with the backend running to generate the SDK
-- **Password reset emails not arriving**: Requires the full backend stack (job service + email function). Check Mailpit UI at `http://localhost:8025`
-- **Port conflicts**: The frontend runs on port 3001 by default. The backend GraphQL server uses port 3000
+| Issue | Solution |
+|-------|----------|
+| GraphQL errors on startup | Ensure backend is running and `NEXT_PUBLIC_DB_NAME` is set |
+| Empty SDK directory | Run `pnpm codegen` with backend running |
+| `useXxx` not found | Check if importing from correct SDK (`@sdk/admin`, `@sdk/auth`, or `@sdk/app`) |
+| Password reset emails not arriving | Check Mailpit UI at `http://localhost:8025` |
+| Port conflicts | Frontend: 3001, Backend GraphQL: 3000 |