fogserv.cloud fogserv.cloud

Agent Reference File

Project: fogserv.cloud
Last Updated: April 22, 2026
Purpose: Comprehensive reference for AI agents operating on this codebase

🎯 Mission Context

You are working on fogserv.cloud, an implementation of "The AI-Managed Server" that treats infrastructure as a living entity that learns and evolves. This project embodies the TELOS philosophy: "Helping People Help Themselves" through democratic technology, knowledge as freedom, and agentic autonomy.

Read First: /kb/TELOS.md - The North Star guiding all decisions

📁 Project Structure & Key Files

Root Directory

/
├── src/
│   ├── main.tsx              # All page components + full route tree
│   ├── index.css             # Global Tailwind imports
│   ├── vite-env.d.ts         # Typed ImportMetaEnv (email provider vars)
│   ├── services/
│   │   └── emailService.ts   # Typed email abstraction (console/api modes)
│   └── routes/               # Scaffold only – main.tsx is canonical
├── scripts/
│   └── import-ghost.ts       # Ghost JSON export → Prisma import script
├── kb/                        # Knowledge Base (CRITICAL – update after every session)
│   ├── TELOS.md              # Mission & philosophy – READ THIS FIRST
│   ├── README.md             # KB navigation
│   ├── agent.md              # This file
│   ├── tasks.md              # Project task tracking
│   ├── lessons-learned.md    # Session insights
│   ├── problems-solved.md    # Technical issues & solutions
│   ├── implementations.md    # Architecture decisions
│   ├── wireframes.md         # MVP UX and wireframe specs
│   ├── workflows.md          # Unified workflow runbook
│   ├── frontend/
│   │   └── website-rebuild.md
│   ├── sysadmin/
│   │   └── dotenvx.md
│   ├── agentic/
│   │   └── agentic-workflows.md
│   └── migrations/
│       ├── ghost-content-migration-map.md
│       └── ghost-redirect-manifest.json  # Auto-generated by import script
├── prisma/
│   ├── schema.prisma         # Full CRM/CMS schema
│   └── migrations/           # Prisma migration history
├── .forgejo/workflows/ci.yml # Forgejo Actions CI pipeline
├── .env                      # Local secrets (NEVER COMMIT)
├── .env.example              # Template (safe to commit)
├── package.json              # Dependencies & scripts
├── vite.config.ts            # Vite config + ALL backend API middleware
├── tsconfig.json             # TypeScript configuration
├── index.html                # HTML shell
└── SECRETS_MANAGEMENT.md     # Root-level secrets guide

🔧 Technology Stack

Core Technologies

Package Manager Commands

bun install                                            # Install dependencies
bun run dev                                           # Start dev server (with dotenvx)
bun run build                                         # Build for production
bun run preview                                       # Preview production build
bun run db:push                                       # Sync database schema
bun run db:generate                                   # Generate Prisma client
bun run db:migrate                                    # Create migration
bun run db:studio                                     # Open Prisma Studio
bun run type-check                                    # TypeScript validation
bun run lint                                          # ESLint
bun run secrets:get KEY                               # Get secret value
bun run import:ghost <ghost-export.json> [--dry-run]  # Import Ghost content

🗄️ Database & Environment

Environment Variables

Located in: .env (local), .env.production (encrypted or CI/CD)

Current Variables (see .env.example for full list):

DATABASE_URL="file:./dev.db"              # SQLite for local dev
PRISMA_ORM=prisma+postgres://...          # Prisma Accelerate (production)
PRISMA_ANY=postgres://...                 # Direct PostgreSQL
MAILGUN_API_KEY=...                       # Mailgun API key
MAILGUN_DOMAIN=mg.fogserv.cloud       # Sending domain
MAILGUN_FROM_EMAIL=noreply@fogserv.cloud
MAILGUN_WEBHOOK_SIGNING_KEY=...           # Webhook HMAC verification
APP_BASE_URL=http://localhost:5173        # For verification email links
VITE_EMAIL_PROVIDER=api                   # 'api' (real) or 'console' (dev)
VITE_EMAIL_API_BASE_URL=/api

Planned:

JWT_SECRET=...                            # For user auth tokens

Database Schema

Current Models (all in prisma/schema.prisma):

Operations:

# After schema changes
bun run db:generate     # Regenerate client
bun run db:push         # Sync to database
# OR for production
bun run db:migrate      # Create migration file

🎨 Frontend Architecture

Current Pages

  1. Home (/) — Hero, core pillars, mission
  2. About (/about) — TELOS mission, goals, how it works
  3. Changelog (/changelog) — Update list
  4. Knowledge Base (/kb) — KB document browser with react-markdown + remark-gfm + rehype-slug
  5. Admin (/admin) — Dashboard with KPI cards, content queue, quick actions, Email Sandbox

Backend API routes (Vite middleware in vite.config.ts):

Component Structure

In src/main.tsx:

Styling Patterns

📋 Core Pillars (TELOS)

1. GitOps is Law

2. Ticketing is Truth

3. Documentation is Memory

4. Proactive Polish

🤖 Agent Operations

Before Starting Work

  1. Read Context

    • Read /kb/TELOS.md for mission alignment
    • Read /kb/tasks.md for current priorities
    • Check related KB files for domain knowledge

  2. Check Issues

    • Is there a ticket for this work?
    • If not, should one be created?
    • Reference ticket number in commits

  3. Understand Environment

    • Are secrets configured in .env?
    • Is database schema current?
    • Are dependencies installed?

During Work

  1. Follow Patterns

    • Match existing code style
    • Use established component patterns
    • Follow naming conventions (see /kb/implementations.md)

  2. Document Decisions

    • Why did you choose this approach?
    • What alternatives were considered?
    • Update /kb/implementations.md for architecture changes

  3. Test as You Go

    • Run dev server to verify changes
    • Check browser console for errors
    • Test responsive design

After Completing Work

  1. Update Knowledge Base

    • Add to /kb/lessons-learned.md if you learned something
    • Add to /kb/problems-solved.md if you fixed an issue
    • Update /kb/tasks.md to mark tasks complete
    • Update relevant KB files with new information

  2. Commit Properly

    git add [files]
git commit -m "feat: Add email signup form

Implements newsletter subscription with Mailgun integration.
Includes double opt-in flow and welcome email.

Fixes #42"

  3. Update Documentation

    • Update CHANGELOG.md with changes
    • Update README.md if setup changed
    • Ensure all new features are documented

🚨 Common Issues & Solutions

React Hydration Errors

Problem: <html> cannot be child of <div>
Solution: Keep HTML structure in index.html, React mounts inside #root
Reference: /kb/problems-solved.md#problem-1

PostCSS Module Error

Problem: module is not defined in ES module scope
Solution: Use export default in postcss.config.js
Reference: /kb/problems-solved.md#problem-2

Tailwind Plugin Error

Problem: Tailwind v4 PostCSS plugin missing
Solution: bun add -d @tailwindcss/postcss and update config
Reference: /kb/problems-solved.md#problem-3

Environment Variables Not Loading

Problem: Variables undefined in application
Solution: Ensure scripts use dotenvx run -- wrapper
Reference: /kb/dotenvx.md

📚 Key Workflows

Adding a New Page

  1. Add route in src/main.tsx:

    const newRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/new-page',
  component: NewPage,
})

  2. Add to route tree:

    const routeTree = rootRoute.addChildren([..., newRoute])

  3. Add navigation link in Navigation() component

  4. Document in /kb/implementations.md

Adding Database Model

  1. Edit prisma/schema.prisma:

    model NewModel {
  id   Int    @id @default(autoincrement())
  name String
}

  2. Generate client:

    bun run db:generate

  3. Push to database:

    bun run db:push

  4. Document in /kb/implementations.md

Adding Secret

  1. Add to .env:

    NEW_SECRET=value_here

  2. Add to .env.example (without value):

    NEW_SECRET=your_secret_here

  3. Use in code:

    const secret = process.env.NEW_SECRET

  4. Document in /kb/dotenvx.md and SECRETS_MANAGEMENT.md

🎯 Current Priorities (from tasks.md)

Phase 1-2 ✅ COMPLETE

Phase 3: CRM/CMS Architecture 🔄 IN PROGRESS

Phase 4: Email & Mailgun 🔄 IN PROGRESS

Phase 5: Ghost Migration 🔄 IN PROGRESS

Phase 6: CI/CD

🔗 External Resources

Documentation

Git Repository

Production Site

⚠️ Critical Rules

NEVER

ALWAYS

📞 Questions & Clarifications

If you encounter ambiguity:

  1. Check KB First: Answer is probably in /kb/
  2. Check TELOS: Does it align with mission?
  3. Check implementations.md: Is there a pattern?
  4. Ask User: If still unclear, ask for clarification
  5. Document Answer: Add to appropriate KB file

📊 Session Checklist

At the end of every session, ensure:

This file is your command center. Refer to it often. Keep it updated.

Last Updated: April 22, 2026
Next Update: After every significant session Agent dashboard design (Phase 8) — KPI cards, real-time polling, deployment tracking — see kb/artifacts/phase8/agent-dashboard-search-community.md

Choose Theme

Your selection is saved locally.

Neural Cacophony
Aperture v2
Flux v1
Mosaic Chaos
Nexus v1
Nexus Zest
Prism v2
Synapse