docs(copilot): add Copilot instructions for The Collective Hub

- Add comprehensive project overview and core philosophy - Document file structure reference for the codebase - Create key files reference table for task-specific guidance - Include multi-tenant guidelines and site resolution flow
2026-06-05 23:46:15 -07:00
parent f4245a996a
commit b192cd53ba
33 changed files with 5710 additions and 120 deletions
@@ -0,0 +1,367 @@
+## Project Configuration
+
+- **Language**: TypeScript
+- **Package Manager**: npm
+- **Runtime**: Node.js 22
+- **Framework**: SvelteKit 2.8.1 + Svelte 5
+- **Database**: PostgreSQL
+- **ORM**: Drizzle ORM 0.45 (with Kysely 0.29 as query builder)
+- **Auth**: Better Auth 1.6 (Discord OAuth)
+- **Image processing**: sharp 0.34
+- **Dev tools**: prettier, eslint, vitest, playwright, tailwindcss v4
+- **Deployment**: Coolify (multi-deploy), Docker
+- **CDN**: Bunny CDN or S3-compatible
+- **Add-ons**: mcp
+
+---
+
+# The Collective Hub — AI Agent Instructions
+
+> **Single entry point for all AI assistants (Cline, Roo Code, Continue.dev, etc.) working on this project.**
+
+---
+
+## 1. Project Identity
+
+**The Collective Hub** — A reusable 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.
+
+We help community organizers look professional online, show their events, attract new members, and build a home for their community — without needing to build a website from scratch.
+
+| Resource | Link |
+| -------- | ---- |
+| This file | [`AGENTS.md`](AGENTS.md) |
+| Project brief | [`docs/00-project-brief.md`](docs/00-project-brief.md) |
+| Architecture plan | [`docs/01-architecture-plan.md`](docs/01-architecture-plan.md) |
+| Database plan | [`docs/02-database-plan.md`](docs/02-database-plan.md) |
+| Feature roadmap | [`docs/03-feature-roadmap.md`](docs/03-feature-roadmap.md) |
+| Environment variables | [`docs/04-environment-variables.md`](docs/04-environment-variables.md) |
+| Admin UX plan | [`docs/05-admin-ux-plan.md`](docs/05-admin-ux-plan.md) |
+| Public site UX plan | [`docs/06-public-site-ux-plan.md`](docs/06-public-site-ux-plan.md) |
+| Development plan | [`docs/07-development-plan.md`](docs/07-development-plan.md) |
+| Open questions | [`docs/08-open-questions.md`](docs/08-open-questions.md) |
+| Risks and rules | [`docs/09-risks-and-rules.md`](docs/09-risks-and-rules.md) |
+| Multi-tenant architecture | [`multi-tenant-architecture.instructions.md`](.github/instructions/multi-tenant-architecture.instructions.md) |
+| Database schema | [`database-schema.instructions.md`](.github/instructions/database-schema.instructions.md) |
+| Auth & roles | [`auth-and-roles.instructions.md`](.github/instructions/auth-and-roles.instructions.md) |
+| Deployment guide | [`deployment-guide.instructions.md`](.github/instructions/deployment-guide.instructions.md) |
+| Admin panel | [`admin-panel.instructions.md`](.github/instructions/admin-panel.instructions.md) |
+| CDN & assets | [`cdn-and-assets.instructions.md`](.github/instructions/cdn-and-assets.instructions.md) |
+| Public site theming | [`public-site-theming.instructions.md`](.github/instructions/public-site-theming.instructions.md) |
+| API route patterns | [`api-route-patterns.instructions.md`](.github/instructions/api-route-patterns.instructions.md) |
+| Testing (multi-tenant) | [`testing-multi-tenant.instructions.md`](.github/instructions/testing-multi-tenant.instructions.md) |
+
+---
+
+## 2. Platform Capabilities
+
+### Core Platform
+
+- **Multi-deployment model**: Each Coolify deployment runs the same Docker image; differentiated only by `SITE_SLUG` env var
+- **Data scoping**: Every table has `siteId` — multi-tenant from day one
+- **Site resolution**: [`hooks.server.ts`](src/hooks.server.ts) → [`site-resolver.ts`](src/lib/server/site-resolver.ts) → `locals.site` for all downstream code
+- **Auth**: Owner bootstrap via `OWNER_DISCORD_ID`; super admin via `SUPER_ADMIN_DISCORD_IDS`; roles: owner/admin/editor
+- **CDN**: Database stores only CDN keys (paths); full URLs constructed via `CDN_BASE_URL` env var
+- **Image processing**: Automatic webp conversion + optimization via sharp on upload
+
+### Admin Panel
+
+- **Settings**: Edit site name, tagline, and general configuration
+- **Branding**: Upload logo, background image, favicon; select color theme
+- **Homepage editor**: Hero title, subtitle, about text, CTA button text/link
+- **Links manager**: Add/edit/delete/reorder nav links and social links
+- **Events manager**: Create, edit, publish/unpublish events with timezone support
+- **Asset library**: Browse, upload, and manage media files with CDN URL copying
+
+### Public Site
+
+- **SSR-only single landing page**: Hero → About → Events → Social Links → Footer
+- **Theme-aware**: CSS custom properties generated from site settings (dark/light/custom presets)
+- **Responsive**: Works on mobile and desktop without client JS
+- **Accessible**: Proper heading hierarchy, alt text, sufficient contrast
+
+### Infrastructure
+
+- **Coolify multi-deploy**: One Git repo, multiple deployments, shared database
+- **Docker containerized**: Multi-stage Dockerfile, deployed via Coolify
+- **Migration safety**: One deployment runs migrations (`RUN_MIGRATIONS=true`); others skip
+- **Shared CDN**: Single bucket, site-scoped paths (`sites/{siteSlug}/...`)
+
+---
+
+## 3. Target Audience
+
+### David (System Maintainer)
+
+- Deploys new sites, maintains the shared codebase, pushes updates
+- Has super admin access across all sites via `SUPER_ADMIN_DISCORD_IDS`
+- Needs: reliable deployment process, clean migration strategy, maintainable code
+
+### Site Owners (Theater Hosts / Community Organizers)
+
+- Log in via Discord, customize their site through the admin panel
+- Non-technical but motivated — need a simple, intuitive admin UI
+- Needs: change branding, edit content, manage events, upload images
+
+### Site Visitors (Community Members & Newcomers)
+
+- Visit the public landing page to learn about the community
+- Want to see what the community is about, when events happen, how to join
+- Needs: fast-loading page, clear info, easy access to Discord/social links
+
+---
+
+## 4. Project Structure
+
+```
+.roo/
+  skills/                   ← Roo Code skills for scaffolding and automation
+    admin-page/
+    api-endpoint/
+    db-migration/
+    generate-api-test/
+    generate-component-test/
+    new-component/
+    new-route/
+    run-tests/
+    test-coverage/
+.github/
+  instructions/             ← Development guidelines for The Collective Hub
+    multi-tenant-architecture.instructions.md
+    database-schema.instructions.md
+    auth-and-roles.instructions.md
+    deployment-guide.instructions.md
+    admin-panel.instructions.md
+    cdn-and-assets.instructions.md
+    public-site-theming.instructions.md
+    api-route-patterns.instructions.md
+    testing-multi-tenant.instructions.md
+    bits-ui.instructions.md
+    components.instructions.md
+    icons.instructions.md
+    server-ts.instructions.md
+    svelte-ts.instructions.md
+    svelte5.instructions.md
+    tailwindcss.instructions.md
+    testing.instructions.md
+  prompts/                  ← Scaffolding templates for routes, components, API, DB
+    new-route.prompt.md
+    generate-component-test.prompt.md
+    generate-api-endpoint.prompt.md
+    generate-admin-page.prompt.md
+    generate-db-migration.prompt.md
+    generate-svelte-component.prompt.md
+    generate-seed-data.prompt.md
+    test-coverage.prompt.md
+  workflows/                ← CI/CD and release automation
+docs/                         ← Architecture, database, roadmap, environment docs
+ 00-project-brief.md
+ 01-architecture-plan.md
+ 02-database-plan.md
+ 03-feature-roadmap.md
+ 04-environment-variables.md
+ 05-admin-ux-plan.md
+ 06-public-site-ux-plan.md
+ 07-development-plan.md
+ 08-open-questions.md
+ 09-risks-and-rules.md
+drizzle/                      ← Drizzle migration files
+scripts/
+  seed.mjs                    ← Database seed script for local dev
+src/
+  app.d.ts                    ← App types, locals augmentation
+  app.html                    ← HTML shell
+  hooks.server.ts             ← Site resolver + auth + migration runner
+  lib/
+    server/
+      auth.ts                 ← Better Auth configuration
+      cdn.ts                  ← CDN URL helpers
+      site-resolver.ts        ← Site loading by SITE_SLUG
+      db/
+        index.ts              ← Drizzle + postgres connection
+        schema.ts             ← All table definitions
+        seed.ts               ← Optional seed data
+        migrate.ts            ← Migration runner
+    shared/
+      types.ts                ← Shared TypeScript types (SiteSettingsData, SiteContext, etc.)
+  routes/
+    +layout.server.ts         ← Root layout, loads site for all pages
+    +layout.svelte            ← Root layout shell
+    +page.server.ts           ← Public homepage data loading
+    +page.svelte              ← Public homepage
+    login/
+      +page.svelte            ← Login page (Discord redirect)
+    admin/
+      +layout.server.ts       ← Admin auth guard
+      +layout.svelte          ← Admin shell/nav
+      +page.svelte            ← Admin dashboard
+      settings/
+        +page.server.ts       ← Site settings editor
+        +page.svelte
+      branding/
+        +page.server.ts       ← Logo, colors, theme
+        +page.svelte
+      assets/
+        +page.server.ts       ← Asset library
+        +page.svelte
+    api/
+      assets/
+        +server.ts            ← Upload endpoint
+static/                       ← Favicon
+```
+
+> The [`.roo/skills/`](.roo/skills/) directory contains reusable skills for common development tasks — scaffolding admin pages, API endpoints, database migrations, components, routes, and generating tests. These are auto-detected by Roo Code when running in this project.
+
+### Tech Stack Instructions
+
+The repo includes development guidelines for the web application's tech stack:
+
+| File | Purpose |
+| ---- | ------- |
+| [`multi-tenant-architecture.instructions.md`](.github/instructions/multi-tenant-architecture.instructions.md) | Site resolution, data scoping, deployment model, env vars |
+| [`database-schema.instructions.md`](.github/instructions/database-schema.instructions.md) | All tables, relationships, indexes, migration strategy |
+| [`auth-and-roles.instructions.md`](.github/instructions/auth-and-roles.instructions.md) | Better Auth, Discord OAuth, role system, super admin |
+| [`deployment-guide.instructions.md`](.github/instructions/deployment-guide.instructions.md) | Coolify multi-deploy, Docker, migration runner, env setup |
+| [`admin-panel.instructions.md`](.github/instructions/admin-panel.instructions.md) | Admin layout, auth guards, form patterns, admin pages |
+| [`cdn-and-assets.instructions.md`](.github/instructions/cdn-and-assets.instructions.md) | CDN helpers, image upload, webp conversion, URL construction |
+| [`public-site-theming.instructions.md`](.github/instructions/public-site-theming.instructions.md) | SSR-only landing page, CSS custom properties, theme presets |
+| [`api-route-patterns.instructions.md`](.github/instructions/api-route-patterns.instructions.md) | API route conventions, asset upload, event CRUD, validation |
+| [`testing-multi-tenant.instructions.md`](.github/instructions/testing-multi-tenant.instructions.md) | Multi-tenant test patterns, mocking site context, auth testing |
+| [`bits-ui.instructions.md`](.github/instructions/bits-ui.instructions.md) | Component patterns for bits-ui library |
+| [`components.instructions.md`](.github/instructions/components.instructions.md) | Svelte 5 component architecture and conventions |
+| [`icons.instructions.md`](.github/instructions/icons.instructions.md) | Lucide icon usage guidelines |
+| [`server-ts.instructions.md`](.github/instructions/server-ts.instructions.md) | SvelteKit server-side TypeScript patterns, Drizzle queries |
+| [`svelte-ts.instructions.md`](.github/instructions/svelte-ts.instructions.md) | TypeScript conventions for Svelte projects |
+| [`svelte5.instructions.md`](.github/instructions/svelte5.instructions.md) | Svelte 5 runes, snippets, and migrations |
+| [`tailwindcss.instructions.md`](.github/instructions/tailwindcss.instructions.md) | Tailwind CSS v4 configuration and patterns |
+| [`testing.instructions.md`](.github/instructions/testing.instructions.md) | Vitest + Playwright testing patterns |
+
+> **Svelte 5 note:** `<svelte:component>` is deprecated. Use `{@const ComponentVar = ...}` in the template and render it as `<ComponentVar />` instead. See [`svelte5.instructions.md`](.github/instructions/svelte5.instructions.md#deprecated-apis) for details and migration examples.
+
+---
+
+## 5. How AI Agents Should Operate
+
+This section defines how AI agents (Cline, Roo Code, Copilot, etc.) should work within this development context.
+
+### Follow the Architecture
+
+- **Always scope queries by `siteId`**. Every database query that touches site-owned data must filter by `siteId` from `locals.site`. Missing a `siteId` filter is the most common multi-tenant bug.
+- **Respect the phase roadmap**. Phase 1 (Foundation) must be complete before Phase 2 starts. Don't build features from Phase 3+ before the core works. See [`docs/03-feature-roadmap.md`](docs/03-feature-roadmap.md).
+- **Use the correct env pattern**. Server-side secret env vars use `$env/dynamic/private`. Never import private env modules from client-side code.
+- **Store CDN keys, not URLs**. Database fields like `cdnKey` store paths (e.g., `sites/bad-movies-theater/logo.webp`), never full URLs. Use the `cdnUrl()` helper from [`src/lib/server/cdn.ts`](src/lib/server/cdn.ts) to construct full URLs.
+
+### Stay On-Architecture
+
+- **No site-specific conditionals**. Never write `if (site.slug === 'bad-movies-theater')`. All customization comes from database settings (branding, theme, homepage content).
+- **Prefer JSON settings over migrations**. Adding a setting to the `siteSettings.settings` JSON column requires no database migration. Only create new tables/tables for structured data that needs indexes, foreign keys, or complex queries.
+- **One layout in V1**. Don't create multiple layout options. One clean, flexible layout that adapts to content is better than three half-baked options.
+- **Additive migrations only**. In production, always use additive changes (new columns, new tables). Avoid renames or destructive operations.
+
+### Development Principles
+
+- **Code for the shared codebase**. Every feature should work for all sites. If a feature is only useful for one site, reconsider whether it belongs in the shared codebase.
+- **Keep the admin panel simple**. The admin exists to serve the public page. Don't build complex admin UIs before the public rendering works.
+- **Security is everyone's responsibility**. Sanitize file uploads, validate all form input server-side, never expose private env vars to the client, protect against XSS in rendered content.
+- **Test the boundary conditions**. Test with no data (empty site), test with missing settings, test with inactive sites, test with various role levels.
+
+### When Creating Templates
+
+- Use clear `[placeholders]` for variables that the developer must customize
+- Include a brief example filled out so they see the expected pattern
+- Reference the relevant instruction file for detailed conventions
+
+---
+
+## 6. Hard Rules (Non-Negotiable)
+
+1. **Always filter by `siteId`.** Every Drizzle query on site-owned data must include a `siteId` filter. Missing this is the most common multi-tenant bug and causes data leaks between sites.
+
+2. **Store CDN keys, not full URLs.** Database fields store paths like `sites/{slug}/logo.webp`. The `cdnUrl()` helper constructs full URLs using `CDN_BASE_URL`. Never store a full URL in the database.
+
+3. **One deployment runs migrations.** Only the deployment with `RUN_MIGRATIONS=true` runs database migrations. Deploy this one first when schema changes are included in a release.
+
+4. **No site-specific conditional logic.** Never write `if (site.slug === 'some-site')`. All per-site differences come from database settings. If a site genuinely needs a unique feature, build it as a configurable option for all sites.
+
+5. **Never commit `.env` files.** Environment variables are configured per-deployment in Coolify. The `.env` file is in `.gitignore` and must never be committed.
+
+6. **Use `$lib` aliases, not relative paths.** Always import from `$lib/server/db`, `$lib/components/`, etc. Never use relative imports like `../../lib/server/db`.
+
+7. **Co-locate tests.** Test files go next to the source they test. Server tests use `.test.ts`, browser component tests use `.svelte.test.ts`.
+
+8. **No `svelte-ignore` suppression comments.** All accessibility and type issues must be fixed properly. Never hide a warning behind a suppression comment.
+
+9. **Prefer additive migrations.** In production, add new columns and tables. Avoid destructive operations (ALTER DROP, RENAME). JSON settings columns reduce migration frequency.
+
+10. **Respect the phase roadmap.** Phase 1 must be fully working (public site + admin login + settings save) before Phase 2. A working simple site is more valuable than a half-built complex one.
+
+---
+
+## 7. File Reference Index
+
+| File | Purpose |
+| ---- | ------- |
+| [`AGENTS.md`](AGENTS.md) | This file — master instructions for all AI agents working on The Collective Hub project |
+| [`.github/copilot-instructions.md`](.github/copilot-instructions.md) | Copilot-specific instructions for development tasks |
+| [`docs/00-project-brief.md`](docs/00-project-brief.md) | Project overview — what The Collective Hub is and who it's for |
+| [`docs/01-architecture-plan.md`](docs/01-architecture-plan.md) | Technical architecture — stack, site resolution, deployment model |
+| [`docs/02-database-plan.md`](docs/02-database-plan.md) | Database schema — all tables, relationships, migration strategy |
+| [`docs/03-feature-roadmap.md`](docs/03-feature-roadmap.md) | Development phases and feature priorities across the roadmap |
+| [`docs/04-environment-variables.md`](docs/04-environment-variables.md) | Environment variable reference — shared vs per-site |
+| [`docs/05-admin-ux-plan.md`](docs/05-admin-ux-plan.md) | Admin panel user experience design and layout |
+| [`docs/06-public-site-ux-plan.md`](docs/06-public-site-ux-plan.md) | Public site user experience and page structure |
+| [`docs/07-development-plan.md`](docs/07-development-plan.md) | Step-by-step development plan and implementation order |
+| [`docs/08-open-questions.md`](docs/08-open-questions.md) | Open design questions and pending decisions |
+| [`docs/09-risks-and-rules.md`](docs/09-risks-and-rules.md) | Critical risks and design pitfalls to avoid |
+| [`.github/instructions/multi-tenant-architecture.instructions.md`](.github/instructions/multi-tenant-architecture.instructions.md) | Site resolution flow, data scoping, deployment model |
+| [`.github/instructions/database-schema.instructions.md`](.github/instructions/database-schema.instructions.md) | All tables, relationships, Drizzle query patterns |
+| [`.github/instructions/auth-and-roles.instructions.md`](.github/instructions/auth-and-roles.instructions.md) | Better Auth, Discord OAuth, roles, auth guards |
+| [`.github/instructions/deployment-guide.instructions.md`](.github/instructions/deployment-guide.instructions.md) | Coolify multi-deploy, Docker, migration runner |
+| [`.github/instructions/admin-panel.instructions.md`](.github/instructions/admin-panel.instructions.md) | Admin routes, auth guards, form actions |
+| [`.github/instructions/cdn-and-assets.instructions.md`](.github/instructions/cdn-and-assets.instructions.md) | CDN helpers, upload flow, sharp processing |
+| [`.github/instructions/public-site-theming.instructions.md`](.github/instructions/public-site-theming.instructions.md) | SSR page, CSS custom properties, theme system |
+| [`.github/instructions/api-route-patterns.instructions.md`](.github/instructions/api-route-patterns.instructions.md) | API route conventions, validation, site scoping |
+| [`.github/instructions/testing-multi-tenant.instructions.md`](.github/instructions/testing-multi-tenant.instructions.md) | Multi-tenant test patterns, mocking, auth testing |
+| [`.github/instructions/bits-ui.instructions.md`](.github/instructions/bits-ui.instructions.md) | Bits UI headless component patterns |
+| [`.github/instructions/components.instructions.md`](.github/instructions/components.instructions.md) | Svelte 5 component architecture |
+| [`.github/instructions/icons.instructions.md`](.github/instructions/icons.instructions.md) | Lucide icon usage guidelines |
+| [`.github/instructions/server-ts.instructions.md`](.github/instructions/server-ts.instructions.md) | SvelteKit server-side TypeScript patterns |
+| [`.github/instructions/svelte-ts.instructions.md`](.github/instructions/svelte-ts.instructions.md) | Svelte 5 .svelte.ts reactive module patterns |
+| [`.github/instructions/svelte5.instructions.md`](.github/instructions/svelte5.instructions.md) | Svelte 5 runes, snippets, migrations |
+| [`.github/instructions/tailwindcss.instructions.md`](.github/instructions/tailwindcss.instructions.md) | Tailwind CSS v4 configuration |
+| [`.github/instructions/testing.instructions.md`](.github/instructions/testing.instructions.md) | Vitest + Playwright base testing patterns |
+| [`.github/prompts/new-route.prompt.md`](.github/prompts/new-route.prompt.md) | Scaffold new SvelteKit routes with auth + site-scoped queries |
+| [`.github/prompts/generate-component-test.prompt.md`](.github/prompts/generate-component-test.prompt.md) | Generate Vitest browser component tests |
+| [`.github/prompts/test-coverage.prompt.md`](.github/prompts/test-coverage.prompt.md) | Analyse coverage gaps and generate missing tests |
+| [`.github/prompts/generate-admin-page.prompt.md`](.github/prompts/generate-admin-page.prompt.md) | Scaffold admin page with auth guard + form |
+| [`.github/prompts/generate-db-migration.prompt.md`](.github/prompts/generate-db-migration.prompt.md) | Scaffold Drizzle migration for schema changes |
+| [`.github/prompts/generate-api-endpoint.prompt.md`](.github/prompts/generate-api-endpoint.prompt.md) | Scaffold API route with auth + site scoping |
+| [`.github/prompts/generate-svelte-component.prompt.md`](.github/prompts/generate-svelte-component.prompt.md) | Scaffold Svelte 5 component with runes + Tailwind |
+| [`.github/prompts/generate-seed-data.prompt.md`](.github/prompts/generate-seed-data.prompt.md) | Scaffold seed script for local dev |
+| [`.github/workflows/`](.github/workflows/) | CI/CD and release automation |
+| [`src/lib/server/site-resolver.ts`](src/lib/server/site-resolver.ts) | Site loading by SITE_SLUG — core multi-tenant logic |
+| [`src/lib/server/auth.ts`](src/lib/server/auth.ts) | Better Auth with Discord OAuth configuration |
+| [`src/lib/server/cdn.ts`](src/lib/server/cdn.ts) | CDN URL construction helpers |
+| [`src/lib/server/db/schema.ts`](src/lib/server/db/schema.ts) | All Drizzle table definitions |
+| [`src/lib/server/db/index.ts`](src/lib/server/db/index.ts) | Drizzle + postgres connection |
+| [`src/lib/shared/types.ts`](src/lib/shared/types.ts) | SiteSettingsData, SiteContext, shared types |
+| [`scripts/seed.mjs`](scripts/seed.mjs) | Database seed script for local dev |
+| [`Dockerfile`](Dockerfile) | Multi-stage Docker build |
+| [`docker-compose.yml`](docker-compose.yml) | Local development with Postgres |
+
+---
+
+## 8. Mode Responsibilities
+
+This section maps AI agent operating modes to development tasks within The Collective Hub context.
+
+| Mode | How It's Used Here |
+| ---- | ------------------ |
+| **🪃 Orchestrator** | Breaks down multi-tenant features into discrete tasks; coordinates site resolution, auth integration, admin panel work, and CDN setup; delegates research, implementation, and review stages across phases |
+| **🏗️ Architect** | Plans technical architecture for multi-tenant features: site resolution flow, database schema additions, admin panel structure, deployment strategy, CDN integration patterns; creates technical specifications for new features |
+| **💻 Code** | Builds and maintains the SvelteKit platform; implements Drizzle queries, admin form actions, public site rendering, auth guards, CDN upload flows; writes Vitest tests with multi-tenant mocking patterns |
+| **❓ Ask** | Answers development questions about the codebase; explains multi-tenant architecture patterns (e.g., "how does site resolution work?"); provides recommendations on Drizzle queries, SvelteKit patterns, Postgres optimization |
+| **🪲 Debug** | Troubleshoots multi-tenant issues (data leaks between sites, wrong site context, auth failures); diagnoses deployment problems (migration conflicts, env var misconfiguration, CDN URL issues); investigates database query performance |
+
+---
+
+> **For new AI agents**: Start by reading the relevant instruction file linked in [Section 7](#7-file-reference-index) above based on your task. When in doubt about architecture or patterns, review the multi-tenant architecture guidelines in [`multi-tenant-architecture.instructions.md`](.github/instructions/multi-tenant-architecture.instructions.md) and the risks document in [`docs/09-risks-and-rules.md`](docs/09-risks-and-rules.md). The core philosophy of this project is simple: one codebase, multiple sites, no data leaks, maintainable by one person.