# CULTSCALE Copilot Instructions

**On session start:** After reading these instructions and the branding guidelines, acknowledge by saying: "I have read the instructions and the branding guide"

## Documentation Policy

**When making changes that set new precedents or modify existing guidelines:**
1. Complete the task as requested
2. Confirm with the user that the approach is correct
3. Document the new pattern/guideline in the appropriate location (see below)

**Documentation locations:**

**`.github/copilot-instructions.md`** (this file) — Repository-wide technical standards:
- Development environment setup (Termux, dependencies)
- Deployment configuration (Cloudflare, GitHub Actions)
- High-level file structure and organization
- Tool usage (npm, wrangler, git, etc.)
- General coding patterns and conventions

**`.github/instructions/*.instructions.md`** — Path-specific technical details:
- Asset build workflows and Makefile usage
- Specific file/directory workflows
- Technical specifications for subsystems
- Applied automatically based on `applyTo:` glob patterns

**`content/`** — Business strategy and brand standards:
- **`branding-guidelines.md`** — Visual identity, voice, messaging, domain policy
- Product strategy (pricing, frameworks, methodologies)
- Team bios and company materials
- Investor/stakeholder documents

**Rule of thumb:** 
- Technical "how-to" → `.github/copilot-instructions.md` or `.github/instructions/*.instructions.md`
- Brand identity "what/why" → `content/branding-guidelines.md`
- Business strategy → `content/`

This ensures future sessions follow consistent patterns and the documentation stays synchronized with actual practices.

## Development Patterns

**Always prefer framework methods over custom logic:**
- Before implementing custom functionality, check if the framework/library provides a built-in solution
- Use Context7 to verify available APIs and patterns
- Examples:
  - Astro has built-in image optimization → Use `<Image />` component instead of manual processing
  - Astro handles routing → Use file-based routing instead of custom route handlers
  - Framework utilities exist → Use them instead of reinventing (e.g., Astro.url for canonical URLs)

**Why:** Frameworks provide optimized, tested, and maintained solutions. Custom implementations add maintenance burden and can miss edge cases.

## Directory Structure

```
cultscale/
├── .github/              # Workflows and Copilot instructions
│   └── instructions/     # Path-specific technical instructions
├── content/              # Business strategy, product docs, bios
├── src/
│   ├── sites/            # Multi-site structure
│   │   ├── cultscale/    # CULTSCALE site
│   │   │   ├── pages/
│   │   │   └── public/   # Static assets (robots.txt, _redirects, _headers)
│   │   ├── cultshot/     # CULTSHOT site
│   │   │   ├── pages/
│   │   │   └── public/   # Static assets (robots.txt, _redirects, _headers)
│   │   └── yusi/         # YUSI site
│   │       ├── pages/
│   │       └── public/   # Static assets
│   ├── shared/           # Shared layouts, components, scripts, styles
│   │   ├── layouts/
│   │   ├── components/
│   │   ├── scripts/
│   │   └── styles/
│   └── assets/           # Brand assets and build system
│       ├── src/          # Source files (version controlled)
│       │   ├── brand/    # Logo and brand mark sources
│       │   ├── social/   # SVG sources for social media covers
│       │   ├── web/      # Web-specific image sources
│       │   ├── email/    # Email signature sources
│       │   └── presentations/ # LaTeX/source files for decks
│       ├── out/          # Generated artifacts (flat, Git LFS)
│       ├── lib/          # External library assets
│       │   ├── images/   # Large source files from outside repo (Git LFS)
│       │   └── fonts/    # Brand fonts
│       └── Makefile      # Build system
├── dist/
│   ├── cultscale/        # Built CULTSCALE site
│   ├── cultshot/         # Built CULTSHOT site
│   └── yusi/             # Built YUSI site
├── public/               # Root-level public (unused, kept for compatibility)
├── dns/                  # DNS zone files (OctoDNS)
├── bios/                 # Team biographies
├── content/yusi/         # YUSI strategy, briefs, and brand guidelines
├── astro.config.cultscale.mjs
├── astro.config.cultshot.mjs
├── astro.config.yusi.mjs
├── wrangler.cultscale.toml
├── wrangler.cultshot.toml
└── wrangler.yusi.toml
```

## Asset Management

**Assets Build System:**

All assets follow **src → out** workflow:
1. Source files in `src/assets/src/` (brand, social, web, icons)
2. Build artifacts in `src/assets/out/` (flat structure, no subdirs)
3. Astro imports assets directly from `src/assets/`

**Output Structure:**
- `src/assets/out/` is flat — all generated files are in the root with descriptive names
- Naming scheme: `logo.png`, `favicon.ico`, `twitter-profile.png`, `social-share.png`, etc.
- No subdirectories in `out/` — the filenames are self-documenting

**Commands:**
```bash
cd src/assets
make              # Show help
make all          # Build everything
make brand        # Logo + icons
make social       # Social covers
make diagrams     # No-op; diagrams are pre-rendered SVG assets
make decks        # Build all decks (Typst)
make clean        # Remove generated files
```

**Key Files:**
- `src/assets/src/cultscale-logo.svg` - Canonical logo (2.39:1 mark)
- `src/assets/src/cultscale-*.svg` - Social cover SVG compositions
- `src/assets/src/*.svg` / `src/assets/src/*.jpg` - Web/source assets (flat, brand-prefixed)
- `src/assets/src/icons/*.svg` - UI icons (LinkedIn, etc.)
- `src/assets/src/presentations/**/*.typ` - Typst presentations
- `src/assets/src/diagrams/*.svg` - Diagram SVGs used by presentations
- `src/assets/lib/images/` - Imported images from external tools (Git LFS)
- `src/assets/lib/fonts/` - Brand fonts
- `src/assets/Makefile` - Complete build system

**Asset organization:**
- Created in-repo → `src/`
- Imported from external tools → `lib/`
- Generated by build system → `out/`

**Social Media Covers:**
Each SVG must:
- Reference logo: `<image xlink:href="../cultscale-logo.svg" />`
- Reference background: `<image xlink:href="../lib/images/audience-connection-original.jpg" />`
- Follow branding: 72% dark overlay, film grain, vignette, corner marks

**Asset imports in Astro:**
```astro
---
import logo from '@assets/src/cultscale-logo.svg';
import favicon from '@assets/out/cultscale-favicon.ico';
import socialShare from '@assets/out/cultscale-social-share.png';
import linkedinIcon from '@assets/src/icons/linkedin.svg';
---
<img src={logo.src} alt="CULTSCALE" />
<link rel="icon" href={favicon.src} />
```

**Open Graph images:**
OG images must use absolute URLs. In BaseLayout.astro:
```astro
<meta property="og:image" content={`${siteUrl}${socialShareImg.src}`}>
<meta property="twitter:image" content={`${siteUrl}${socialShareImg.src}`}>
```

**Image import workflow:**
1. New images → `import/`
2. Process: `exiftool -all= image.jpg` (strip metadata)
3. Rename descriptively: `audience-connection.jpg`
4. Large originals (>100KB source from external tools) → `src/assets/lib/images/` (Git LFS)
5. Web-ready versions → `src/assets/src/` (flat, descriptive filenames)
6. Clean up `import/`

**Git LFS:** Files in `src/assets/lib/images/`, `src/assets/lib/fonts/`, and `src/assets/out/` are automatically tracked.

**Dependencies:** Makefile tracks all dependencies automatically:
- Logo changes → Rebuilds icons, profiles, and social covers
- Background image changes → Rebuilds all social covers
- Individual SVG changes → Rebuilds only that cover
- Web sources → Imported directly by Astro (no build step needed)

**Presentations & Diagrams:**
See `.github/instructions/presentations.instructions.md` for Typst + SVG workflow details.

## Multi-Site Structure

**Repository contains multiple sites:**
- **CULTSCALE** (`cultscale.com`) - Main website in `src/sites/cultscale/`
- **CULTSHOT** (`cultshot.com`) - CULTSHOT website in `src/sites/cultshot/`
- **YUSI** (`yusiapp.com`) - Cinema-education platform in `src/sites/yusi/`

**Each site has:**
- Own `pages/` directory
- Own `public/` directory (robots.txt, _redirects, _headers)
- Own Astro config: `astro.config.{sitename}.mjs`
- Own Wrangler config: `wrangler.{sitename}.toml`
- Own build output: `dist/{sitename}/`
- Own Cloudflare Pages project

**Shared resources in `src/shared/`:**
- `layouts/` - Page layouts (BaseLayout, HeroLayout)
- `components/` - UI components (Header, Footer, Logo, etc.)
- `scripts/` - JavaScript (hero.ts, etc.)
- `styles/` - Global styles (global.css)

**Shared assets in `src/assets/`:**
- Source assets: `src/assets/src/` (flat, brand-prefixed filenames)
- Generated outputs: `src/assets/out/` (flat)
- Shared resources: `src/assets/lib/images/`, `src/assets/lib/fonts/`, `src/assets/src/icons/`, `src/assets/src/presentations/`

**Brands:**
- Assets are brand-prefixed (e.g., `cultscale-…`, `cultshot-…`, `cultreel-…`) rather than stored in per-brand folders.

**Import aliases:**
```astro
// @ resolves to the site's own directory
import MyPage from '@/pages/something.astro';

// @shared resolves to src/shared/
import BaseLayout from '@shared/layouts/BaseLayout.astro';
import Header from '@shared/components/Header.astro';
import '@shared/styles/global.css';

// @assets resolves to src/assets/ (all assets are brand-prefixed)
import logo from '@assets/src/cultscale-logo.svg';
import favicon from '@assets/out/cultscale-favicon.ico';
import cultshotHero from '@assets/src/cultshot-director-cropped.jpg';
import workflowSvg from '@assets/src/workflow-comfy.svg'; // Shared assets not prefixed
```

**When to override shared resources:**
If a site needs custom layouts/components/styles, create them in the site's own directory:
```
src/sites/cultshot/
├── pages/
├── public/
├── layouts/        # Custom layouts (overrides @shared/layouts)
├── components/     # Custom components (overrides @shared/components)
└── styles/         # Custom styles (overrides @shared/styles)
```

**Example: CULTSHOT site customizations:**
- `src/sites/cultshot/components/Logo.astro` - Custom logo (speaker cones + viewfinder)
- `src/sites/cultshot/components/Header.astro` - Uses CULTSHOT logo
- `src/sites/cultshot/components/Footer.astro` - Links to CULTSCALE pages (cross-site navigation)
- `src/sites/cultshot/layouts/BaseLayout.astro` - Uses CULTSHOT components
- `src/sites/cultshot/layouts/HeroLayout.astro` - Wraps BaseLayout with hero scripts

**Development commands:**
```bash
npm run dev:cultscale    # :4321
npm run dev:cultshot     # :4322
npm run dev:yusi         # :4323
npm run build:cultscale
npm run build:cultshot
npm run build:yusi
```

## Website (Astro)

See `.github/instructions/astro.instructions.md` for detailed Astro-specific instructions.

**Quick reference:**
```bash
npm run dev:cultscale    # Dev server at localhost:4321
npm run dev:cultshot     # Dev server at localhost:4322
npm run build:cultscale  # Build to dist/cultscale/
npm run build:cultshot   # Build to dist/cultshot/
```

## Branding

**Always read `content/branding-guidelines.md` before creating visual assets.**

- Brand name: CULTSCALE (uppercase)
- Tagline: "Infrastructure for independent cinema"
- Fonts: Space Grotesk (all text, wordmark)
- Avoid em dashes in general copy; use them only when the brand guidelines explicitly specify them (e.g., the official lockup: "CULTSCALE — Infrastructure for independent cinema").

**Color Palette:**

| Name | Hex | CSS Variable | Usage |
|------|-----|--------------|-------|
| Milky Black | `#121212` | `--cult-black` | Backgrounds |
| Deep Charcoal | `#1F1F1F` | `--cult-accent` | Section backgrounds, cards |
| Light Gray | `#E6E6E6` | `--cult-gray` | All body text |
| Pure White | `#FFFFFF` | `--cult-white` | Headlines |
| Cult Gold | `#B78A3C` | (accent only) | Icon status, parabolic moments |

## Context7 Documentation Strategy

**Always consult Context7 before using tools or libraries:**
1. Before installing, configuring, or using any external tool or library, use `context7-resolve-library-id` to find the Context7-compatible library ID
2. Use `context7-get-library-docs` to fetch current documentation
3. Follow the up-to-date API and best practices from Context7 docs

**Why:** Context7 provides current documentation, helping us avoid deprecated methods, old patterns, and errors. This makes us more efficient by using the latest stable approaches.

**Examples:**
- Before using Astro features → resolve and fetch Astro docs from Context7
- Before npm commands → check if Context7 has relevant package docs
- Before configuring tools → verify current syntax via Context7

## Environment

### Termux (Android)

**You can develop this project in Termux**, but there are platform-specific caveats. See `.github/instructions/termux.instructions.md` for complete setup including Sharp, Wrangler workarounds, and TMPDIR usage.

### Standard Development

- Node.js 24+
- npm
- ImageMagick, Inkscape, rsvg-convert (for asset builds)
- Git LFS (for large assets)
- Wrangler (Cloudflare CLI) - install normally with `npm install -g wrangler`
- Newsletter signup spam defense:
  - `PUBLIC_TURNSTILE_SITE_KEY` (client-side Turnstile widget key)
  - `TURNSTILE_SECRET_KEY` (server-side Turnstile verification key)

## Cloudflare Pages Deployment

**Configuration (CULTSCALE):**
- Project: `cultscale-web`
- Production branch: `main`
- Build output: `dist/cultscale/`
- Live URL: https://cultscale-web.pages.dev
- Config file: `wrangler.cultscale.toml`

**GitHub Actions Workflow:**
Located at `.github/workflows/deploy-cultscale.yml`

Deploys automatically on push to `main` when files in `src/` change. Requires secrets:
- `CLOUDFLARE_API_TOKEN` - API token with Pages write permissions
- `CLOUDFLARE_ACCOUNT_ID` - Account ID from Cloudflare dashboard
- `GITHUB_TOKEN` - Automatically provided by GitHub Actions

**Local Deployment:**
```bash
npm run build:cultscale
wrangler pages deploy dist/cultscale --project-name cultscale-web --branch main
```

**wrangler.cultscale.toml:**
```toml
name = "cultscale-web"
compatibility_date = "2025-12-12"
pages_build_output_dir = "dist/cultscale"
```

**Manual Project Creation:**
If the project doesn't exist, wrangler will prompt interactively:
1. Choose "Create a new project"
2. Enter production branch: `main`
3. Project is created and deployment proceeds

**Configuration (YUSI):**
- Project: `yusi-web`
- Production branch: `main`
- Build output: `dist/yusi/`
- Live URL: https://yusiapp.com (custom domain)
- Config file: `wrangler.yusi.toml`
- Workflow: `.github/workflows/deploy-yusi.yml`

See `.github/instructions/yusi.instructions.md` for full YUSI deployment details, portal integration, Turnstile setup, and git push pattern.