# CULTSCALE OS Plan (Portal Worker)

## Scope & Requirements (confirmed)
- Cloudflare-native stack (Worker + D1 + KV + R2 + Analytics Engine later)
- Admin auth via Cloudflare Access
- Programmatic-first MCP/API; UI can be minimal
- UI must follow `content/branding-guidelines.md` (CULTSCALE voice + colors)
- Modular domain system (kernel + pluggable modules)
- Mailbox ingestion target: `cultscale@gmail.com`
- Mail body storage in R2; D1 stores metadata + pointers
- Tasks v1 fields: title, status, due date, priority, links
- Task dependencies: `blocked_by` edges; prevent cycles at write time
- File sharing:
  - Stable public link with unguessable token
  - Default expiry: 30 days
  - Max file size: 25MB (v1)
  - Link serves latest version only
  - Replace file without changing URL
  - Cache-control: private/no-store, versioned ETag
- Local dev on Termux is unreliable; CI-only deploy to Workers is the source of truth

## Modules (explicit)
### Kernel modules (always-on)
- Identity + roles
- Parties/CRM (people + companies)
- Projects + tasks + dependencies
- Activity log (append-only) + major updates scoring
- Mailbox threads/messages + ingestion
- File sharing + stable links + versioning
- MCP surface for all kernel tools

### Domain modules (pluggable)
- Campaigns + conversions (newsletter is one campaign type)
- Films/Titles registry (v1 minimal) + rights/availability
- Later: Payments, Events, Social monitoring

## Current State (as of 2026-01-27)
- Worker deployed: https://cultscale-os.cultscale.workers.dev
- Endpoints:
  - `/` and `/ui`: minimal HTML landing (Worker-served)
  - `/api/status`: JSON status
  - `/healthz`: JSON ok
  - `/api/projects`: CRUD (requires D1 binding)
  - `/api/tasks`: CRUD (requires D1 binding)
- CI workflows:
  - PR check: `Check CULTSCALE OS (Worker)` runs `wrangler deploy --dry-run`
  - Deploy: `Deploy CULTSCALE OS (Worker)` on `main` changes under `portal/**`
- D1 binding now configured in `portal/wrangler.toml`
  - `/api/projects` and `/api/tasks` require D1 migrations to be applied
  - CI migrations require D1 token permissions (updated; rerun pending)

## Workplan (track progress here)

### Phase 0 — Foundations (now)
- [x] Worker scaffold + cron
- [x] CI check + deploy workflows
- [x] Minimal UI landing on `/`
- [x] Provision Cloudflare D1 database
- [x] Bind D1 in `portal/wrangler.toml`
- [x] Enable D1 migrations in CI deploy
- [x] Update CLOUDFLARE_API_TOKEN with D1 permissions

### Phase 1 — Kernel data model + services
- [ ] D1 migrations: users/roles, parties, campaigns/conversions
- [ ] D1 migrations: projects, tasks, task_dependencies, generic_links
- [ ] D1 migrations: activities (append-only log)
- [ ] D1 migrations: mailbox tables (threads/messages/labels)
- [ ] D1 migrations: films/titles minimal registry + FTS
- [ ] Service layer (D1 access, validation, dependency cycle check)


### Phase 2a — Newsletter management
- [ ] Newsletter lists CRUD
- [ ] Subscriber capture (double opt-in)
- [ ] Subscription lifecycle (confirm/unsubscribe)
- [ ] CRM linkage (party + primary email)
### Phase 2 — HTTP API
- [x] Projects CRUD (Worker handlers; requires D1 binding)
- [x] Tasks CRUD (Worker handlers; requires D1 binding)
- [ ] Task dependencies add/remove
- [ ] Generic links add/remove/list
- [ ] Activities append/query
- [ ] Mailbox list/get/search
- [ ] Files: upload, create share link, download via stable URL, replace
- [ ] Films: create/update/search + rights claims + availability
- [ ] Auth: Access gate + app-level role checks

### Phase 3 — Mailbox ingestion
- [ ] Gmail OAuth connector
- [ ] Scheduled sync (every 5 min)
- [ ] Incremental sync via history.list + fallback resync
- [ ] Store message bodies in R2; metadata in D1

### Phase 4 — MCP tools
- [ ] Expose Worker methods as MCP tools (workers-mcp)
- [ ] Tools: task/project CRUD, dependencies, links, updates, mailbox, films

### Phase 5 — UI (minimal)
- [ ] Projects list/detail
- [ ] Tasks list/detail (filters)
- [ ] Mailbox viewer (latest + thread)

## Notes
- File links must always serve the latest version, never cached.
- Use stable IDs and deterministic scoring for “major updates”.