the-collective-hub/plans/identity-adaptation-plan.md

Identity Adaptation Plan: The Web Cooperative → The Collective Hub

Goal: Rewrite all project identity files from "The Web Cooperative" (marketing agency for small businesses) to "The Collective Hub" (multi-tenant SvelteKit template system for theater/community landing pages).

---

Table of Contents

1. AGENTS.md — Master Rewrite
2. .github/copilot-instructions.md — Rewrite
3. .github/instructions/ — Instruction Files
4. .github/prompts/ — Prompt Templates
5. .github/workflows/ — CI/CD Workflows
6. Summary: Files to Create vs Keep vs Delete
7. Execution Order

---

1. AGENTS.md — Master Rewrite

Action: Full rewrite (~90% new content, ~10% salvageable structure)

Section-by-Section Plan

Section	Current (The Web Cooperative)	Target (The Collective Hub)
Title	"The Web Cooperative — AI Agent Instructions"	"The Collective Hub — AI Agent Instructions"
Section 1: Project Identity	Marketing help for small businesses: jargon-free, practical	Multi-tenant SvelteKit website template system for launching branded landing pages for online theater hosts, watch-party communities, and Discord communities. One codebase → multiple deployed sites → one shared database + CDN.
Section 2: Services Offered	7 subsections of marketing services (strategy, SEO, ads, AI automation, etc.)	Replace with Platform Capabilities covering: multi-deployment model, site resolution, admin panel, public site rendering, CDN/assets, auth/roles, events/scheduling, theming/branding
Section 3: Target Audience	Small business owners, local service providers	Replace with three personas: David (system maintainer), Site Owners (theater hosts), Site Visitors (community members) — each with distinct needs and access levels
Section 4: Project Structure	Old src/ structure with EspoCRM, marketing components	Update directory tree to match actual codebase — reflect hooks.server.ts, site-resolver.ts, db/ schema, admin routes, asset management, CDN helpers
Section 5: How AI Agents Should Operate	Marketing-focused: write for small biz owners, budget-conscious, content generation principles	Rewrite for development context: Follow architecture patterns (siteId scoping, multi-tenant queries), respect phase roadmap (Phase 1 first), never write site-specific conditionals, prefer JSON settings over migrations, maintain Docker/Coolify compatibility
Section 6: Hard Rules	9 marketing rules (no jargon, budget-conscious, templates, etc.)	Replace with 10 dev-hard-rules: (1) Always filter by siteId, (2) Store CDN keys not URLs, (3) One deployment runs migrations, (4) No site-specific conditionals, (5) Never commit .env, (6) Use $lib aliases not relative imports, (7) Co-locate tests, (8) No svelte-ignore comments, (9) Prefer additive migrations, (10) Respect the phase roadmap
Section 7: File Reference Index	All marketing files + old tech references	Update to reference: new instructions, prompt templates, docs/, schema files, auth helpers, CDN utilities
Section 8: Mode Responsibilities	Marketing-focused mode descriptions	Rewrite for dev context: Architect plans multi-tenant architecture; Code builds SvelteKit routes, DB queries, admin pages; Debug troubleshoots multi-deploy issues, migration conflicts; Ask answers SvelteKit/Drizzle/Postgres questions

Specific Content Changes

• Line 1-5: Update AGENTS.md header with Collective Hub project config (add Drizzle, Better Auth, PostgreSQL to add-ons)
• Line 9: # The Collective Hub — AI Agent Instructions
• Line 17-32: Complete rewrite of project identity with multi-tenant description
• Line 36-127: Replace "Services Offered" with "Platform Capabilities" — describe the system's features (site resolution, admin panel, auth, CDN, events, theming)
• Line 130-148: Replace target audience with the three personas
• Line 152-227: Update project structure to match actual codebase (verified from src/ listing)
• Line 235-248: Keep tech stack instruction references but update file references
• Line 252-281: Rewrite "How AI Agents Should Operate" for development — focus on architecture patterns, not marketing
• Line 286-301: Replace hard rules with multi-tenant development rules
• Line 306-341: File reference — remove all marketing file references, add new instruction/prompt files
• Line 344-355: Mode responsibilities — rewrite for platform development

Attachments to File

Add link to key documentation:

• docs/00-project-brief.md — Project overview
• docs/01-architecture-plan.md — Architecture decisions
• docs/02-database-plan.md — Schema documentation
• docs/04-environment-variables.md — Env var reference
• docs/09-risks-and-rules.md — Critical risks to avoid

---

2. .github/copilot-instructions.md — Rewrite

Action: Full rewrite (~95% new content)

Current	Target
The Web Cooperative — Copilot Instructions	The Collective Hub — Copilot Instructions
Marketing-focused overview and file structure	Multi-tenant platform overview, architecture principles, key file references
References to marketing instruction files	References to dev instruction files (multi-tenant architecture, DB schema, auth, deployment)
"When asked to..." table for marketing tasks	"When working on..." table for dev tasks (admin pages, API routes, DB queries, auth, assets)

---

3. .github/instructions/ — Instruction Files

3A. Tech Instructions to KEEP (with minor updates)

These files are mostly project-agnostic and need only applyTo description updates and path fixes.

bits-ui.instructions.md — Minor Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Content: Already generic — keep as-is. Just update the description frontmatter line.
• Changes: ~2 lines

components.instructions.md — Minor Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Folder structure: Keep ui/ and layout/ pattern, but add note about admin components living in src/routes/admin/
• Changes: ~3 lines (description, add admin component note)

icons.instructions.md — Minor Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Content: Already generic — keep as-is
• Changes: ~1 line

svelte-ts.instructions.md — No Changes

• Already completely generic (no project-specific references)
• Changes: None

svelte5.instructions.md — Minor Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Content: Already generic — keep as-is
• Changes: ~1 line

tailwindcss.instructions.md — Minor Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Path reference: Update layout.css path if needed (currently references src/routes/layout.css)
• Changes: ~2 lines

testing.instructions.md — Moderate Update

• Description: Change "The Web Cooperative website" → "The Collective Hub platform"
• Add: Section on testing with multi-tenant context (mocking locals.site, locals.siteSettings, siteId filtering)
• Add: Note about testing admin auth guards
• Keep: All existing patterns (Vitest browser/node split, expect.element, co-location, requireAssertions)
• Changes: ~15-20 lines added

server-ts.instructions.md — Significant Update

• Description: Change from "The Web Cooperative website... EspoCRM API client" → "The Collective Hub platform... Drizzle schema, site resolver, auth patterns"
• Replace Section "EspoCRM API Client" with "Drizzle Database Patterns":
  • Import db from $lib/server/db
  • Always filter by siteId from locals
  • Use eq, and, desc from drizzle-orm
  • Pattern: const { site } = locals; const items = await db.select().from(table).where(eq(table.siteId, site.id));
• Replace Section "Form Actions" with "Admin Form Actions":
  • Auth guard first: if (!locals.user) throw redirect(302, '/login');
  • Validate before write
  • Use fail for validation errors
• Add Section "Site Context Access":
  • locals.site — site record
  • locals.siteSettings — parsed settings JSON
  • locals.user — authenticated user (or null)
  • locals.membership — user's role for this site (or null)
• Keep: Env var rules (still valid), module sections
• Changes: ~50% of file rewritten

3B. docs-workflow.instructions.md — Complete Rewrite

Current: Legal documents workflow (master services agreement, privacy policy, etc.) Target: Development documentation workflow

New Content:

• Document Inventory: Reference the docs/ folder files (00-09)
• Source of Truth: The docs/ .md files are authoritative
• Update Workflow: How to update architecture docs when decisions change
• Phase Tracking: How to mark phase deliverables as complete in roadmap
• Template: Standard doc format (title, purpose, decisions, risks)

3C. Marketing Instructions to REPLACE (9 files → 9 new dev instruction files)

#	Old File	New File	Purpose
1	brand-voice.instructions.md	multi-tenant-architecture.instructions.md	Site resolution, data scoping, deployment model, env vars
2	copywriting.instructions.md	database-schema.instructions.md	All tables, relationships, indexes, migration strategy
3	seo.instructions.md	auth-and-roles.instructions.md	Better Auth, Discord OAuth, role system, super admin
4	local-seo.instructions.md	deployment-guide.instructions.md	Coolify multi-deploy, Docker, migration runner, env setup
5	social-media.instructions.md	admin-panel.instructions.md	Admin layout, auth guards, form patterns, admin pages
6	ad-copy.instructions.md	cdn-and-assets.instructions.md	CDN helpers, image upload, webp conversion, URL construction
7	ai-automation.instructions.md	public-site-theming.instructions.md	SSR-only landing page, CSS custom properties, theme presets
8	business-ops.instructions.md	api-route-patterns.instructions.md	API route conventions, asset upload, event CRUD, validation
9	tech-help.instructions.md	testing-multi-tenant.instructions.md	Multi-tenant test patterns, mocking site context, auth testing

New File Details

1. multi-tenant-architecture.instructions.md

Content:

• Overview: One codebase, multiple Coolify deployments, one database + CDN
• Site resolution flow: env.SITE_SLUG → hooks.server.ts → site-resolver.ts → locals.site
• Data scoping rule: Every table has siteId, every query filters by it
• Deployment model diagram: Git repo → multiple Coolify deployments
• Migration safety: RUN_MIGRATIONS flag, exactly one deployment runs migrations
• Environment variable conventions (shared vs per-site)
• Risk reminders: No site-specific conditionals, no hardcoded CDN URLs

2. database-schema.instructions.md

Content:

• Table reference: sites, users, memberships, siteSettings, assets, navLinks, socialLinks, events
• ER diagram (Mermaid)
• Key patterns: UUID PKs, snake_case columns, timestamps on every table
• Indexing rules: siteId indexed on every table, unique constraints
• JSON settings pattern: siteSettings.settings is a JSONB column
• Migration strategy: Additive only, one deployment runs migrations
• Drizzle patterns: How to write queries, schema definitions, typed inserts

3. auth-and-roles.instructions.md

Content:

• Better Auth with Discord OAuth setup
• Auth flow: Login → Discord redirect → callback → session creation
• Owner bootstrap: OWNER_DISCORD_ID env var
• Super admin: SUPER_ADMIN_DISCORD_IDS env var, cross-site access
• Role hierarchy: owner > admin > editor
• Auth guard patterns in +layout.server.ts
• locals.user, locals.membership — checking access in server code

4. deployment-guide.instructions.md

Content:

• Coolify setup: One Git repo, multiple deployments
• Dockerfile build process
• Environment variable configuration per deployment
• Migration runner: Which deployment runs migrations, deploy order
• CDN storage configuration
• Adding a new site: Create DB row → deploy with new SITE_SLUG → set OWNER_DISCORD_ID
• Troubleshooting common deployment issues

5. admin-panel.instructions.md

Content:

• Admin route structure: src/routes/admin/
• Auth guard pattern in +layout.server.ts
• Admin layout shell with navigation
• Form action patterns: validate, save, redirect with flash
• Admin pages: settings, branding, homepage editor, links, events, assets
• Svelte 5 patterns in admin forms (two-way binding, $bindable, event handlers)

6. cdn-and-assets.instructions.md

Content:

• CDN helper at $lib/server/cdn.ts
• URL construction: CDN_BASE_URL + cdnKey
• Upload flow: accept file → validate type/size → convert to webp (sharp) → upload to CDN → store record in assets table
• cdnKey convention: sites/{siteSlug}/{type}/{filename}
• Asset library browsing patterns
• Never store full URLs, only keys

7. public-site-theming.instructions.md

Content:

• Public site: SSR-only single page, no client-side routing beyond initial load
• Section structure: Hero → About → Events → Social Links → Footer
• Theme system: CSS custom properties generated from siteSettings.theme
• Preset support: dark, light, custom presets
• Dynamic branding: logo, background image, favicon from CDN
• Layout presets (single layout for V1)

8. api-route-patterns.instructions.md

Content:

• SvelteKit +server.ts conventions
• API route structure: src/routes/api/
• Asset upload endpoint: multipart form, file validation, sharp conversion
• Event CRUD: list, create, update, delete with site scoping
• Form action alternatives (prefer form actions over API for admin)
• Authentication checks in API routes
• Response format conventions

9. testing-multi-tenant.instructions.md

Content:

• Testing with multi-tenant context: mocking locals
• Mocking the database: Drizzle mock patterns with vi.hoisted
• Testing auth guards: mock locals.user, locals.membership
• Testing site resolution: mock getSiteBySlug return values
• Testing admin form actions: POST to route, check redirects
• Testing API routes: mock file upload, verify CDN interaction
• Coverage targets for multi-tenant code paths

---

4. .github/prompts/ — Prompt Templates

4A. Tech Prompts to KEEP (with updates)

generate-api-test.prompt.md — Moderate Update

• Description: Already mentions "SvelteKit API handler"
• Change: Replace "The Web Cooperative project" → "The Collective Hub project"
• Mocking patterns: Update from generic to Collective Hub patterns (mock $lib/server/db, $lib/server/cdn, $lib/server/auth)
• Add: Multi-tenant test patterns (mock locals.site, test site-scoped queries)
• Changes: ~10-15 lines

generate-component-test.prompt.md — Minor Update

• Description: Replace "The Web Cooperative" → "The Collective Hub"
• Content: Likely already generic — verify and update project name references
• Changes: ~2-3 lines

new-route.prompt.md — Moderate Update

• Description: Replace "The Web Cooperative website" → "The Collective Hub platform"
• Auth guard pattern: Update to use Collective Hub's locals.site and locals.membership
• Load function template: Add site-scoped query pattern
• Add: Note about admin routes vs public routes
• Changes: ~15 lines

test-coverage.prompt.md — Moderate Update

• Description: Replace "The Web Cooperative" → "The Collective Hub"
• Coverage targets: Adjust for multi-tenant code paths
• Focus areas: Admin routes, API routes, site resolver, auth logic, DB queries
• Changes: ~10 lines

4B. Marketing Prompts to REPLACE (5 files → 5 new dev prompts)

#	Old File	New File	Purpose
1	competitor-analysis.prompt.md	generate-admin-page.prompt.md	Scaffold new admin page with auth guard, form, and save pattern
2	generate-ad-copy.prompt.md	generate-db-migration.prompt.md	Scaffold Drizzle migration for schema changes
3	generate-seo-content.prompt.md	generate-api-endpoint.prompt.md	Scaffold API route with auth, validation, site scoping
4	generate-website-copy.prompt.md	generate-svelte-component.prompt.md	Scaffold Svelte component with runes, Tailwind, snippets
5	social-media-content.prompt.md	generate-seed-data.prompt.md	Scaffold seed script for local dev and new site setup

New Prompt Details

1. generate-admin-page.prompt.md

Content:

Scaffold a new admin page for The Collective Hub at path `admin/{section}/`.

## What to create

### 1. `+page.server.ts`
- Auth guard: verify `locals.user` and `locals.membership` role
- Load current settings/data from DB scoped by `locals.site.id`
- Form actions: validate, save to DB, redirect with success message

### 2. `+page.svelte`
- Import types from `./$types`
- Use Svelte 5 runes: `$props()`, `$state()`, `$derived()`
- Form with Tailwind styling
- Save/cancel buttons

2. generate-db-migration.prompt.md

Content:

Generate a Drizzle migration for The Collective Hub.

## Rules
- Additive changes only (new tables, new columns)
- Every new table must have a `siteId` foreign key
- Every new table must have UUID PK, createdAt, updatedAt
- Use `drizzle-kit generate` to create the SQL migration
- Update schema.ts first, then run generation

3. generate-api-endpoint.prompt.md

Content:

Scaffold a SvelteKit API endpoint for The Collective Hub at `api/{resource}/`.

## What to create

### `+server.ts`
- Import `db` from `$lib/server/db`
- Access `locals.site` for site scoping
- All queries filter by `siteId`
- Auth check: `if (!locals.user) return json({ error: 'Unauthorized' }, { status: 401 })`
- Validate request body with Zod or manual checks
- Return `json()` responses

4. generate-svelte-component.prompt.md

Content:

Scaffold a Svelte 5 component for The Collective Hub.

## Conventions
- PascalCase filename
- `$lib/components/` path for shared components
- Route-level components stay in route directory
- Use `$props()` with inline type
- Use snippets over slots for composition
- Tailwind CSS for styling
- Lucide icons from `@lucide/svelte`
- No `svelte-ignore` comments

5. generate-seed-data.prompt.md

Content:

Generate a seed script for The Collective Hub.

## What to create in `scripts/seed.mjs`

### Site Record
- Insert a site row with slug matching `SITE_SLUG` env var
- Name, isActive=true

### Site Settings
- Insert siteSettings row with default branding, theme, homepage JSON

### Default Data
- Optional default navLinks, socialLinks, sample events
- Only if the phase requires it

---

5. .github/workflows/ — CI/CD Workflows

ci-web.yml — Moderate Update

Changes:

1. Title: "CI" → "CI - The Collective Hub" (cosmetic)
2. Env vars: Add Collective Hub-specific stubs for build:
   • SITE_SLUG=ci-test (needed for build)
   • OWNER_DISCORD_ID=000000000000000000 (stub)
   • CDN_BASE_URL=http://cdn.example.com (stub)
3. Trigger paths: Already correct (src/, package.json, etc.)
4. Steps: Add Docker build test stage:

   - name: Build Docker image
     run: docker build -t collective-hub-ci .
   

5. Coverage: Already using vitest, keep as-is
6. Markdown validation: Keep but update config to exclude old marketing files

release.yml — Minor Update

Changes:

1. Line 63: Change ## The Web Cooperative — ${{ steps.resolve.outputs.tag }} → ## The Collective Hub — ${{ steps.resolve.outputs.tag }}
2. Tag prefix: Optionally change content/* to release/* for conventional release tags (or keep release/* — discuss with David)

---

6. Summary: Files to Create vs Keep vs Delete

Files to CREATE (new content, no existing version useful)

#	File Path
1	.github/instructions/multi-tenant-architecture.instructions.md
2	.github/instructions/database-schema.instructions.md
3	.github/instructions/auth-and-roles.instructions.md
4	.github/instructions/deployment-guide.instructions.md
5	.github/instructions/admin-panel.instructions.md
6	.github/instructions/cdn-and-assets.instructions.md
7	.github/instructions/public-site-theming.instructions.md
8	.github/instructions/api-route-patterns.instructions.md
9	.github/instructions/testing-multi-tenant.instructions.md
10	.github/prompts/generate-admin-page.prompt.md
11	.github/prompts/generate-db-migration.prompt.md
12	.github/prompts/generate-api-endpoint.prompt.md
13	.github/prompts/generate-svelte-component.prompt.md
14	.github/prompts/generate-seed-data.prompt.md

Files to REWRITE (existing file, >70% new content)

#	File Path	New Content %
1	AGENTS.md	~90%
2	.github/copilot-instructions.md	~95%
3	.github/instructions/docs-workflow.instructions.md	~95%
4	.github/instructions/server-ts.instructions.md	~50% (keep env var rules, replace EspoCRM sections)

Files to UPDATE (existing file, <30% new content)

#	File Path	Changes
1	.github/instructions/bits-ui.instructions.md	Update description line only
2	.github/instructions/components.instructions.md	Update description, add admin component note
3	.github/instructions/icons.instructions.md	Update description line
4	.github/instructions/svelte5.instructions.md	Update description line
5	.github/instructions/tailwindcss.instructions.md	Update description, path references
6	.github/instructions/testing.instructions.md	Add multi-tenant testing section
7	.github/prompts/generate-api-test.prompt.md	Update project name, mock patterns
8	.github/prompts/generate-component-test.prompt.md	Update project name
9	.github/prompts/new-route.prompt.md	Update auth guard, add site-scoped patterns
10	.github/prompts/test-coverage.prompt.md	Update project name, coverage targets
11	.github/workflows/ci-web.yml	Add build env stubs, Docker build test
12	.github/workflows/release.yml	Update release title

Files to DELETE (no longer relevant)

None — the old marketing files (brand-voice.instructions.md, seo.instructions.md, etc.) are being replaced by new files with different names. The old files must be removed to avoid confusion. This is a delete-then-create operation for 9 instructions + 5 prompts = 14 files to delete.

Files to KEEP AS-IS

#	File Path	Reason
1	.github/instructions/svelte-ts.instructions.md	Already generic, no project references

---

7. Execution Order

The work should be done in this order, grouped by dependency:

Phase A: Foundation (parallel-safe)

1. Delete 9 old marketing instruction files
2. Delete 5 old marketing prompt files
3. Create 9 new instruction files (all independent, can be done in parallel)
4. Create 5 new prompt files (all independent, can be done in parallel)

Phase B: Updates (depends on Phase A for context)

5. Update server-ts.instructions.md — needs to know new instruction file names for cross-references
6. Update testing.instructions.md — add multi-tenant patterns
7. Update 4 tech prompts (api-test, component-test, new-route, test-coverage)
8. Update docs-workflow.instructions.md

Phase C: Master files (depends on Phase B for file references)

9. Rewrite AGENTS.md — references all instruction and prompt files
10. Rewrite .github/copilot-instructions.md — references all instruction files

Phase D: CI/CD (independent)

11. Update ci-web.yml
12. Update release.yml

Phase E: Cleanup

13. Run svelte-check to verify no broken imports
14. Run vitest to verify tests still pass
15. Verify markdown links are valid using markdown-link-check

---

Appendix: File Content Comparison

Old vs New: Brand Voice → Multi-Tenant Architecture

Old (brand-voice.instructions.md):

# Brand Voice & Tone Guidelines
## Voice Characteristics
- Direct, Honest, Practical, Plain language, Authoritative but approachable
## Tone Ladder
- Educational, Direct feedback, Supportive, Firm, Casual

New (multi-tenant-architecture.instructions.md):

# Multi-Tenant Architecture
## Site Resolution Flow
- env.SITE_SLUG → hooks.server.ts → site-resolver.ts → locals.site
## Data Scoping
- Every table has siteId, every query filters by it
## Deployment Model
- Git repo → multiple Coolify deployments → same Docker image
## Migration Safety
- RUN_MIGRATIONS flag, exactly one deployment runs migrations
## Environment Variables
- Shared vs per-site variable classification

Old vs New: Copywriting → Database Schema

Old (copywriting.instructions.md):

# Copywriting Best Practices
- PAS formula, AIDA formula
- Feature-to-benefit mapping
- Headline templates, CTA formulas

New (database-schema.instructions.md):

# Database Schema
## Tables
- sites, users, memberships, siteSettings, assets, navLinks, socialLinks, events
## ER Diagram (Mermaid)
## Indexing Strategy
## Migration Patterns
## Query Examples

Old vs New: SEO → Auth & Roles

Old (seo.instructions.md):

# SEO Content & Strategy Guidelines
- Keyword research
- On-page optimization
- Content structuring

New (auth-and-roles.instructions.md):

# Authentication & Roles
## Better Auth with Discord OAuth
## Auth Flow: Login → Callback → Session
## Owner Bootstrap (OWNER_DISCORD_ID)
## Super Admin (SUPER_ADMIN_DISCORD_IDS)
## Role Hierarchy: owner > admin > editor
## Auth Guard Patterns

---

End of Plan

This plan covers 35 files total: 14 new, 4 rewritten, 12 updated, 1 kept as-is, and 14 deleted.