GEMINI.md

1# Gemini Agent Brief — Vue Email Editor Integration (Unlayer)
2# Agent Brief — Vue Email Editor Integration (Unlayer)
3 
4** history can be found in the chat folder for reference **
5 
6## Project Goal
7 
8Integrate the **Unlayer Vue Email Editor** (`vue-email-editor`) into a Vue app, modernize the configuration, and add a persistence & media layer so users can **create, edit, version, and publish email designs** to **PostgreSQL**, with support for:
9 
10- Template Picker
11- File Manager & Custom Media Library
12- User Saved Blocks
13- Style Guide (design tokens / brand guardrails)
14- Merge Tags & Design Tags
15- Versioning & Autosave
16- Publishing workflow (draft → publish → usage)
17 
18This brief serves as the single source of truth for both **product and engineering** — describing the high-level vision, architecture, backend contracts, data model, DevOps considerations, and operational guardrails.
19 
20---
21 
22## High-Level Architecture
23 
24### Frontend (Vue 3 + Vite)
25- `vue-email-editor` component wrapper
26- State store (Pinia) for user/session, current template, save status
27- UI surfaces: Template Picker modal, File Manager modal, Saved Blocks, Style Guide panel, Merge/Design tag menus
28 
29### Backend (Node/Express or Nest)
30- REST/JSON endpoints for templates, designs, user blocks, media, tags
31- Auth middleware (JWT or session cookie) + RBAC for media/templates
32 
33### Database (PostgreSQL + Prisma)
34- Tables: `users`, `templates`, `versions`, `user_blocks`, `media_assets`, `merge_tags`, `design_tags`
35- Soft-deletes + versioning (immutable `versions` rows)
36 
37### Object Storage
38- S3-compatible (AWS S3, Cloudflare R2, GCS) for media assets
39- Signed upload URLs, MIME checks, image processing pipeline (optional)
40 
41### Queues (optional)
42- For heavy exports (HTML inlining, image optimization)
43 
44---
45 
46 
47# Agent Secret Access Documentation
48 
49To operate correctly, the agent requires access to sensitive credentials. 
50These credentials are provided securely at runtime using the 1Password CLI tool.
51 
52**The agent should never contain hardcoded secrets.**
53 
54### Accessing Secrets
55 
56The secrets are exposed to the agent as standard environment variables within its 
57runtime environment. The agent code must read these variables during initialization.
58 
59CLOUDFLARE_KEY	The API Key for Cloudflare Storage	op://AI/Cloudflare Storage API Key/credential
60POSTGRES_CONN_STR	The full PostgreSQL connection string	op://AI/PostgresSQL/connection string
61 
62Code Implementation (Example: Node.js)
63The agent should use its language's standard method for reading environment variables. 
64 
65javascript
66// Example in Node.js/JavaScript
67const cloudflareKey = process.env.CLOUDFLARE_KEY;
68const postgresConnString = process.env.POSTGRES_CONN_STR;
69 
70if (!cloudflareKey || !postgresConnString) {
71    console.error("ERROR: Required secrets were not loaded into the environment.");
72    process.exit(1);
73}
74 
75// Proceed with agent logic...
76// useApiKey(cloudflareKey);
77// connectToDatabase(postgresConnString);
78 
79 
80## POSTGRES CONNECTION CREDENTIALS
81 
82** The Postgres Database is hosted on a local network server. 
83It's NOT running on docker on this machine. 
84Connect using either of the options below, both contain the same 
85endpoint for the connection string to the network server at 192.168.8.105:5432 
86including the db user and password.
87 
88 
89## Environment Variables (example)
90 
91```
92# Frontend (Vite)
93VITE_API_BASE=https://api.example.com
94VITE_UNLAYER_PROJECT_ID=xxxxxxxx
95 
96# Backend
97DATABASE_URL=postgresql://rebelbot:pass@192.168.8.105:5432/email_db
98JWT_SECRET=supersecret
99S3_ENDPOINT=https://s3.example.com
100S3_BUCKET=emails-media
101S3_ACCESS_KEY=...
102S3_SECRET_KEY=...
103CORS_ORIGIN=https://app.example.com
104```
105 
106---
107 
108## Core End-to-End Flows
109 
110### 1. Template Lifecycle (Draft → Publish → Use)
111- **Create Template**: Name + org → auto-create initial **Draft v1**.
112- **Edit Draft**: Update content (`design_json`), preview HTML, autosave.
113- **Publish**: Locks draft and sets `currentPublishedVersionId`. Draft remains editable or is cleared.
114- **Fork New Draft**: Create a new draft from the published version.
115- **Archive**: Soft-delete templates (never delete versions).
116 
117### 2. Versioning
118- Templates have at most **one current draft** and **one current published version**.
119- Publishing locks a version (`locked=true`, `status=PUBLISHED`).
120- Version numbers increment sequentially per template.
121 
122### 3. Merge Tags
123- Defined **per org** with unique `(org_id, key)`.
124- System tags (e.g., `{{ unsubscribe_url }}`) are reserved.
125- Unknown tags → validation error with list of unknown keys.
126 
127### 4. Media Assets
128- Upload to storage; store `storage_key` and `checksum`.
129- Signed URLs generated on demand (`public_url` optional).
130- Deduplicate on `(org_id, checksum)`.
131 
132### 5. Render & Preview
133- Compile `design_json` → HTML; substitute merge tags; inline CSS.
134- Generate **test sends** (rate-limited).
135- Capture renderer metadata for reproducibility.
136 
137### 6. Usage in Sending
138- External systems reference `template_id` + optional `version_id`.
139- If `version_id` is omitted → latest `currentPublishedVersionId` is used.
140- Audit logs record which version was rendered.
141 
142### 7. Access Control & Audit
143- RBAC per org (Author / Publisher / Admin).
144- Audit logs: template changes, version publishes, asset uploads.
145 
146### 8. Webhooks & Events
147- `template.published`, `template.version.created`, `asset.created`, `send.previewed`
148 
149---
150 
151## Frontend Integration — Key Tasks
152 
153### 1. Start from `dev-example.vue`
154- Initialize `vue-email-editor`
155- Load merge tags, initial design
156- Implement `saveDesign`, `exportHtml`, `loadDesign` methods
157 
158### 2. Editor Event Plumbing
159- Listen for `design:updated` (dirty state) → throttled autosave (5–10s).
160- Register merge tags on load and persist last-used set per org/user.
161- Override media selection to route through your File Manager (custom picker → returns URL to Unlayer).
162 
163### 3. Editor Options
164- Template Picker
165- File Manager (custom picker + signed uploads)
166- Saved Blocks
167- Style Guide enforcement
168- Merge Tag registration
169- Design Tags form
170 
171### 4. Autosave
172- Throttled autosave → `POST /api/templates/:id/autosave`
173- Cancel on route leave; show states: *Saving… / Saved / Failed*
174- On revisit, if autosave is newer than draft, prompt to **Restore**
175 
176### 5. Export Pipeline
177- `exportHtml` → POST `/api/versions/:versionId/render`
178- Cache multiple export variants
179- Inline CSS, absolutize URLs, sanitize & minify output
180- Store compatibility results (e.g., linter results, deliverability checks)
181 
182### 6. Version Browser
183- Side panel list with author, timestamp
184- “Open as draft” and “Restore” actions
185 
186### 7. Publish Flow
187- Run linter → show grouped violations → block or warn based on severity
188 
189### 8. Merge-Tag Picker
190- Searchable; insert at cursor; preview with defaults
191 
192### 9. File Manager
193- Single picker UX across image/file tools
194- Thumbnails, folder support, drag-drop upload
195- AV scan (async) on upload
196- Responsive sizes and quotas with retention policies
197 
198---
199 
200## Guardrails & Invariants
201 
202- Published versions are immutable (`locked=true`).
203- Drafts are the only mutable state.
204- Merge tags unique per org (case-insensitive).
205- Media URLs are derived from `storage_key`; ephemeral signed URLs should never be persisted.
206- Assets cannot be deleted if referenced by any version.
207- Publish without a draft → `409 Conflict`.
208 
209### Style-Guide Guardrails
210- Central JSON of brand tokens (colors, fonts, radii, spacing).
211- Pre-publish/export **linter**:
212  - Reject/warn on non-approved fonts/colors/line-heights.
213  - Enforce alt text and basic contrast checks.
214- Optionally lock disallowed tools/colors in Unlayer options.
215 
216#### Example Style-Guide Tokens
217```json
218{
219  "colors": {
220    "background": {
221      "dark": "#B2D3DE",
222      "light": "#FAFAFA"
223    },
224    "brandPrimary": "#163666",
225    "brandSecondary": "#B2D3DE",
226    "button": {
227      "dark": "#163666",
228      "light": "#B2D3DE"
229    },
230    "danger": "#F37D59",
231    "error": "#E05047",
232    "info": "#B2D3DE",
233    "textDark": "#0B1320",
234    "textLight": "#334155",
235    "warning": "#FACA78"
236  },
237  "fontFamily": {
238    "btn": "'Khand', 'Oswald', 'Impact', sans-serif",
239    "header": "'Khand', 'Oswald', 'Impact', sans-serif",
240    "primary": "'General Sans', 'Public Sans', 'Inter', 'Andale Mono', Tahoma, sans-serif"
241  },
242  "fontWeight": {
243    "btn": 700,
244    "header": 700,
245    "primary": 400
246  },
247  "layout": {
248    "maxWidth": 640
249  },
250  "padding": {
251    "btn": {
252      "top": 20,
253      "right": 24,
254      "bottom": 20,
255      "left": 24
256    }
257  },
258  "radius": {
259    "btn": 3
260  },
261  "spacing": {
262    "btn": 8,
263    "contentGutter": 24,
264    "sectionGap": 32
265  }
266}
267```
268 
269---
270 
271## Database Schema (Finalized)
272 
273```sql
274-- templates
275id (uuid pk)
276org_id (uuid fk -> orgs)
277name (text)
278slug (text unique)
279status (text check in ['draft','published','archived'])
280current_draft_version_id (uuid fk -> versions null)
281current_published_version_id (uuid fk -> versions null)
282style_guide_id (uuid null)
283deleted_at (timestamp null)
284created_at, updated_at
285 
286-- versions
287id (uuid pk)
288template_id (uuid fk -> templates)
289number (int)
290status (text check in ['DRAFT','PUBLISHED'])
291design_json (jsonb)
292html_compiled (text)
293renderer_name (text)
294renderer_ver (text)
295inliner_ver (text)
296created_by (uuid fk -> users)
297created_at (timestamp)
298published_at (timestamp)
299locked (boolean default false)
300 
301-- media_assets
302id (uuid pk)
303org_id (uuid fk -> orgs)
304filename (text)
305content_type (text)
306byte_size (int)
307storage_key (text)
308public_url (text null)
309checksum (text)
310meta (jsonb)
311created_by (uuid fk -> users)
312created_at, updated_at, deleted_at
313unique (org_id, checksum)
314 
315-- merge_tags
316id (uuid pk)
317org_id (uuid fk -> orgs)
318key (citext)
319label (text)
320default_value (text)
321system (boolean default false)
322created_at, updated_at
323unique (org_id, key)
324```
325 
326### Schema Extensions & Advanced Tables
327 
328- `organizations`, `org_members`, `template_collaborators` for multi-tenancy & permissions
329- `exports` table for multiple cached variants
330- `jobs` table for AV scans, thumbnails, heavy exports
331- `audit_logs` table for traceability
332 
333---
334 
335## Backend API (Contract)
336 
337### Templates & Versions
338- `POST /api/templates`
339- `GET /api/templates`
340- `GET /api/templates/:id`
341- `PATCH /api/templates/:id`
342- `POST /api/templates/:id/versions`
343- `GET /api/templates/:id/versions`
344- `GET /api/versions/:versionId`
345- `POST /api/versions/:versionId`
346- `POST /api/versions/:versionId/publish`
347- `POST /api/versions/:versionId/render`
348- `POST /api/versions/:versionId/test-send`
349 
350### Media
351- `GET /api/media`
352- `POST /api/media/sign`
353- `GET /api/media/:id/url`
354- `DELETE /api/media/:id`
355 
356### API Additions
357- `POST /api/templates/:id/duplicate`
358- `GET /api/templates/:id/exports`
359- `GET /api/templates/:id/exports/:exportId`
360- `POST /api/media/scan/:id`
361- `GET /api/style-guide`
362- `POST /api/webhooks`, `GET /api/webhooks/events`
363 
364---
365 
366### Templates & Versions
367- `POST /api/templates`
368- `GET /api/templates`
369- `GET /api/templates/:id`
370- `PATCH /api/templates/:id`
371- `POST /api/templates/:id/versions`
372- `GET /api/templates/:id/versions`
373- `GET /api/versions/:versionId`
374- `POST /api/versions/:versionId`
375- `POST /api/versions/:versionId/publish`
376- `POST /api/versions/:versionId/render`
377- `POST /api/versions/:versionId/test-send`
378 
379---
380 
381## Testing Plan
382 
383### Media
384- `GET /api/media`
385- `POST /api/media/sign`
386- `GET /api/media/:id/url`
387- `DELETE /api/media/:id`
388 
389### API Additions
390- `POST /api/templates/:id/duplicate`
391- `GET /api/templates/:id/exports`
392- `GET /api/templates/:id/exports/:exportId`
393- `POST /api/media/scan/:id`
394- `GET /api/style-guide`
395- `POST /api/webhooks`, `GET /api/webhooks/events`
396 
397### Tags Additions
398**Tags**
399 
400- [ ] Multi-tenant model & collaborator permissions
401- [ ] Editor event hooks wired (dirty, autosave, export)
402- [ ] Style-guide tokens + linter + publish gate
403- [ ] Exports, jobs, audit_logs, template_collaborators tables
404- [ ] Draft vs published semantics clarified and implemented
405- [ ] File Manager override + AV scan + thumbnails + quotas
406- [ ] CSP/CORS, pooling, backups, metrics
407- [ ] Tight indexes & scoped uniqueness
408- [ ] Secrets only in `.env.example`
409 
410---
411 
412## DevOps / Platform Considerations
413 
414- **CORS/CSP**: Allow Unlayer iframe domain; set `img-src`/`media-src` to CDN + `data:`.
415- **DB Pooling**: Use pgbouncer or node-pg pool.
416- **Migrations/Seeds**: Seed org, users, template, tags, media.
417- **Observability**: Include `request_id`, `user_id`, `org_id` in logs.
418- **Metrics**: saves/sec, exports latency, AV scan times.
419- **Backups**: Daily PG snapshots; media lifecycle rules (IA/Glacier).
420- **Secrets**: Only `.env.example`; never commit real credentials.
421 
422---
423 
424## Testing Plan
425 
426- **Contract tests**: editor bridges (load/save/export, media select)
427- **Snapshot tests**: exported HTML (goldens)
428- **Security tests**: object-level auth across orgs
429- **E2E tests**: full flow — create → edit → autosave → publish → export
430 
431---
432 
433## Definition of Done (Checklist)
434 
435- [ ] Multi-tenant model & collaborator permissions
436- [ ] Editor event hooks wired (dirty, autosave, export)
437- [ ] Style-guide tokens + linter + publish gate
438- [ ] Exports, jobs, audit_logs, template_collaborators tables
439- [ ] Draft vs published semantics clarified and implemented
440- [ ] File Manager override + AV scan + thumbnails + quotas
441- [ ] CSP/CORS, pooling, backups, metrics
442- [ ] Tight indexes & scoped uniqueness
443- [ ] Secrets only in `.env.example`
444 
445---
446 
447## Spec Addendum (Summary)
448 
449- One draft and one published version per template.
450- Published versions are immutable.
451- Merge tags scoped per org.
452- Signed URLs are ephemeral and derived at read-time.
453- Compiled HTML cached for current published version.
454- Signed URL TTL default: 15 minutes.
455- Metrics: render latency, publish latency, error rates.
456 
457## ⚙️ Local Development Notes
458 
459* **Server Control:** When working on local development, please let me handle starting and stopping the dev server — manual restarts during active work can cause the agent to freeze or lose state.
460 
461* **Port Consistency:** Keep the local dev server port fixed in `vite.config.ts` at:
462 
463```ts
464  server: {
465    port: 9022
466  }
467```
468 
469* **Network Flow / Reverse Proxy Setup:**
470  External requests from outside IPs follow this path:
471 
472```
473  SSL :443 (External Request)
474        ↓
475  Reverse Proxy Server
476        ↓
477  Local Dev Server (192.168.8.137:9022)
478```
479 
480This ensures stable connections during testing and remote access, while avoiding conflicts with the agent runtime.
481 
482 
483## Issues
484- Review the AGENT_issues.md file for a list of current open issues.
485- Use this file as the source of truth for tracking bugs, feature gaps, tech debt, and pending decisions.
486 
487 
488## Resolved
489- When an issue listed in AGENT_issues.md is confirmed fixed or completed, move that exact line into AGENT_resolved.md.
490- Immediately below the original line, add the tag RESOLVED followed by the data and include a brief summary of the high-level steps taken to resolve it.
491- This ensures historical traceability and keeps the issues list clean while preserving context for future reference.
492 
493---
494 
495## 🧰 Issue Template
496 
497### Issue [#] | [MM-DD-YYYY]
498 
499**Title:** [Short, descriptive title of the issue]
500 
501**Description:**
502[Detailed description of the issue, how it was discovered, and any reproduction steps if relevant.]
503 
504**Impact:**
505[What part of the system is affected and how it impacts users or workflows.]
506 
507**Status:** Open
508**Priority:** [Low | Medium | High | Critical]
509**Owner:** [Team or individual responsible]
510**Reference:** [Optional: internal tracking ID, issue number, or ticket link]
511 
512---
513 
514### RESOLVED | [MM-DD-YYYY]
515 
516**Resolution Summary:**
517[Brief explanation of the fix or solution implemented.]
518 
519**Commit:** [Commit hash or link]
520**Linked PR:** [PR number or link]
521**Verified By:** [QA name or date]
522 
523---
524 
525## ✅ Examples — Real Issue
526 
527### Issue 1 | 10-19-2025
528 
529**Title:** Autosave fails silently when the editor tab loses focus.
530 
531**Description:**
532Users reported that when the browser tab is backgrounded during editing, the `design:updated` event is not always triggered. As a result, autosave does not fire, leading to potential data loss if the tab is closed or refreshed before a manual save.
533 
534**Impact:**
535 
536* Draft data can be lost unexpectedly.
537* Increases user frustration and reduces trust in autosave reliability.
538 
539**Status:** Open
540**Priority:** High
541**Owner:** Frontend Integration Team
542**Reference:** `editor_autosave_event_bug`
543 
544---
545 
546### RESOLVED | 10-25-2025
547 
548**Resolution Summary:**
549✅ Added a visibility change listener to trigger a final autosave before the tab loses focus.
550✅ Implemented a fallback debounce timer to ensure autosave fires even if the event is skipped.
551✅ Added logging and metrics to monitor autosave failures in production.
552 
553**Commit:** [`abc1234`](https://github.com/REVREBEL/email-editor/commit/abc1234)
554**Linked PR:** #42
555**Verified By:** QA on staging (10-24-2025)
556 
557 
558---
559 
560# Unlayer Features & Docs Map
561 
562When implementing functionality, prefer **custom components** over broad Unlayer SDK expansion—**except** for the explicitly whitelisted “Use Unlayer Native Function: True” items below. The official Unlayer documentation has been added under `./AGENTS.md/*`. Use the relative links in this section to find the correct doc quickly.
563 
564## App Pages to Add (Builder Modes)
565 
566> Each page demonstrates a different `displayMode` with a minimal `unlayer.init(...)` example.
567 
568### 1) Page Builder (Web)
569**Docs:** `./AGENTS.md/unlayer-builder/page-builder.md`
570 
571```js
572unlayer.init({
573  id: 'editor-container',
574  displayMode: 'web',
575  projectId: 1234 // REPLACE
576});
577```
578 
579### 2) Document Builder
580**Docs:** `./AGENTS.md/unlayer-builder/document-builder.md`
581 
582```js
583unlayer.init({
584  id: 'editor-container',
585  displayMode: 'document',
586  projectId: 1234 // REPLACE
587});
588```
589 
590### 3) Popup Builder
591**Docs:** `./AGENTS.md/builder/popup-builder.md`
592 
593```js
594unlayer.init({
595  id: 'editor-container',
596  displayMode: 'popup',
597  projectId: 1234 // REPLACE
598});
599```
600 
601### Export Example (all modes)
602```js
603unlayer.exportHtml(console.log, { title: 'Exported HTML Title' });
604```
605 
606---
607 
608## Feature Flags & Native SDK (Allowed)
609 
610> The following should use **Unlayer native functions** (not custom components), per our implementation policy.
611 
612### Headers & Footers
613Enable via feature flag:
614 
615```js
616unlayer.init({
617  features: {
618    headersAndFooters: true
619  }
620});
621```
622 
623### Page Anchors
624**Docs:** (See “Page Anchors” notes in builder docs) — lets users link buttons/links to sections of the page.
625 
626```js
627unlayer.init({
628  features: {
629    pageAnchors: true
630  }
631});
632```
633 
634### Connect Your CDN (Optional)
635Use native Unlayer integration so assets leverage  CloudFront) for faster loads.  
636**Docs:** `./AGENTS.md/builder/file-storage/custom.md`
637 
638Use Tool  1Password: Get from 1Password.
639 
640Cloudflare API Key 
641"op run://AI/Cloudflare Storage API Key/credential"
642"op run:op://AI/PostgresSQL/connection string"
643Connection URL
644"op run://AI/Cloudflare Storage API Key/hostname"
645 
646 
647---
648 
649## Custom File Storage (Native Callbacks)
650 
651**Docs:** `./AGENTS.md/builder/file-storage/custom.md`
652 
653Register Unlayer’s native `image` callback to control uploads:
654 
655```js
656unlayer.registerCallback('image', function (file, done) {
657  // Handle file upload here (POST to your storage/signing endpoint)
658  // Example: immediately show some progress
659  done({ progress: 10 });
660});
661```
662 
663**Update progress bar during upload:**
664```js
665unlayer.registerCallback('image', function (file, done) {
666  // ... upload chunk ...
667  done({ progress: 10 });
668  // ... upload chunk ...
669  done({ progress: 50 });
670});
671```
672 
673**Finish upload with final URL:**
674```js
675unlayer.registerCallback('image', function (file, done) {
676  // After your upload finishes:
677  done({ progress: 100, url: 'https://cdn.example.com/path/to/image.jpg' });
678});
679```
680 
681---
682 
683## Templates (On Your Own Servers)
684**Docs:** `./AGENTS.md/builder/templates/management.md`
685 
686Load a template JSON directly:
687 
688```js
689const template = { /* Unlayer design JSON */ };
690unlayer.loadDesign(template);
691```
692 
693---
694 
695## Custom Tools & Blocks (Native)
696 
697> Prefer Unlayer’s native extension points for tools/blocks; only build a heavy custom component if the SDK cannot cover the use case.
698 
699- **Create Custom Tools (Docs):** `./AGENTS.md/builder/tools/custom/create.md`  
700- **Inject CSS/JS from Tools (Docs):** `./AGENTS.md/builder/tools/custom/css-javascript.md`  
701  > Each tool can insert CSS/JS into <head> if you prefer non-inline styles.
702- **Custom Blocks (Docs):** `./AGENTS.md/builder/blocks/custom.md`  
703- **User Saved Blocks (Docs):** `./AGENTS.md/builder/blocks/user-saved.md`
704 
705---
706 
707## Text Management
708 
709- **Tables (Enable):** `./AGENTS.md/builder/text-management/tables`  
710- **Spell Checker (Enable):** `./AGENTS.md/builder/text-management/spell-checker.md`  
711```js
712  unlayer.init({
713    features: {
714      textEditor: {
715        spellChecker: true
716      }
717    }
718  });
719```
720- **Inline Font Controls (Enable):** `./AGENTS.md/builder/text-management/inline-font-controls.md`  
721```js
722  unlayer.init({
723    features: {
724      textEditor: {
725        inlineFontControls: true
726      }
727    }
728  });
729```
730 
731---
732 
733## Device Support
734 
735**Docs:** `./AGENTS.md/builder/device-management.md`
736 
737```js
738unlayer.init({
739  devices: ['desktop', 'mobile']
740});
741```
742 
743---
744 
745### Implementation Notes
746 
747- **Policy:** Default to **custom components** for new functionality, **except** where this section explicitly says “Use Unlayer Native Function: True.”
748- **Docs Source:** All linked docs are local to this repo under `./AGENTS.md/...` so they remain versioned with the project.
749- **Project ID:** Replace `projectId` in examples with your Unlayer Project ID.
750- **Export Pipeline:** Use native `exportHtml` and route the output through our **export fidelity pipeline** (inlining, absolutizing, sanitizing)—see “Export Pipeline” section earlier in this doc.
751 
752 
753### Template Picker
754 
755* Server: paginate templates by owner/status; include `current_version_id` & version meta.
756* Client: searchable list, preview thumbnail (render HTML server-side once & screenshot optional).
757 
758### File Manager & Custom Media Library
759 
760* Use signed upload URLs to object storage; DB stores metadata + URL.
761* Image validation (mime, dims), size limits, per-user folders.
762* Selection returns absolute URL that the editor can embed.
763 
764### User Saved Blocks
765 
766* Store each block as JSON fragment compatible with Unlayer’s block structure.
767* Offer categories and preview thumbnails; insert by calling the editor’s add/merge API.
768 
769### Style Guide
770 
771* Centralize tokens (fonts, colors, spacings) in one config file.
772* Lock or hide non-approved tools/colors via editor options when possible.
773* Pre-export linter to detect rogue colors or non-approved fonts in `design_json`.
774 
775### Merge Tags
776 
777* Provide a curated list with labels and defaults (e.g., `user.first_name`, `hotel.name`).
778* Ensure the list syncs with your ESP/templating engine expectations.
779 
780### Design Tags
781 
782* Free-form key/value for analytics & downstream automation (e.g., `campaign_id`, `segment`).
783 
784### User Template Updates
785 
786* Autosave drafts; manual version bump on Save.
787* Show status (Draft/Published) and save indicator (saving / saved).
788 
789---
790 
791 
792## Security & Compliance
793 
794* AuthN: JWT cookies (httpOnly, secure) or session.
795* AuthZ: Enforce ownership and roles on all endpoints.
796* Input validation: Zod/Valibot for request bodies.
797* Media: antivirus scan (ClamAV) if required; signed URLs with short TTL.
798* Audit trail for create/update/delete.
799* Rate limiting + CORS allow-list.
800 
801---
802 
803## Testing Strategy
804 
805* Unit: API handlers (templates, versions, media) with in-memory PG or test DB.
806* Integration: Save → Load → Export using a headless browser against the editor.
807* E2E: Cypress flows covering Template Picker, Media upload, Saved Blocks, Merge Tags insertion, Export.
808 
809---
810 
811## Deliverables
812 
813* Vue app with `vue-email-editor` integrated and all feature UIs.
814* Node/Express backend + Prisma schema & migrations.
815* Postgres SQL dump (baseline).
816* API docs (OpenAPI/Swagger) covering endpoints above.
817* Admin-only seed script with demo templates, merge tags, and media samples.
818* README with setup, env, and run instructions.
819 
820---
821 
822## Resources Needed
823 
824* Access to the `vue-email-editor` repo & `dev-example.vue`.
825* Unlayer account / Project ID (if required by advanced features).
826* Postgres instance & credentials.
827* S3-compatible storage (bucket, keys).
828* Domain for API (for CORS) and OAuth provider if SSO desired.
829* Brand tokens: fonts, colors, spacing, logo assets.
830 
831---
832 
833 
834## Frontend Integration — Key Tasks
835 
8361. **Start from `dev-example.vue`**
837 
838   * Ensure ref access to editor (`<EmailEditor ref="editorRef" :options="editorOptions" @load="onLoad" />`).
839   * Implement `onLoad` to set config, load initial design if `template.current_version` exists.
840   * Expose `saveDesign`, `exportHtml`, `loadDesign` via methods bound to UI buttons.
841 
842- One draft and one published version per template.
843- Published versions are immutable.
844- Merge tags scoped per org.
845- Signed URLs are ephemeral and derived at read-time.
846- Compiled HTML cached for current published version.
847- Signed URL TTL default: 15 minutes.
848- Metrics: render latency, publish latency, error rates.
849 
850## ⚙️ Local Development Notes
851 
852* **Server Control:** When working on local development, please let me handle starting and stopping the dev server — manual restarts during active work can cause the agent to freeze or lose state.
853 
854* **Port Consistency:** Keep the local dev server port fixed in `vite.config.ts` at:
855 
856```ts
857  server: {
858    port: 9022
859  }
860```
861 
862* **Network Flow / Reverse Proxy Setup:**
863  External requests from outside IPs follow this path:
864 
865```
866  SSL :443 (External Request)
867        ↓
868  Reverse Proxy Server
869        ↓
870  Local Dev Server (192.168.8.137:9022)
871```
872 
873This ensures stable connections during testing and remote access, while avoiding conflicts with the agent runtime.
874 
875 
876## Issues
877- Review the AGENT_issues.md file for a list of current open issues.
878- Use this file as the source of truth for tracking bugs, feature gaps, tech debt, and pending decisions.
879 
880 
881## Resolved
882- When an issue listed in AGENT_issues.md is confirmed fixed or completed, move that exact line into AGENT_resolved.md.
883- Immediately below the original line, add the tag RESOLVED followed by the data and include a brief summary of the high-level steps taken to resolve it.
884- This ensures historical traceability and keeps the issues list clean while preserving context for future reference.
885 
886---
887 
888## 🧰 Issue Template
889 
890### Issue [#] | [MM-DD-YYYY]
891 
892**Title:** [Short, descriptive title of the issue]
893 
894**Description:**
895[Detailed description of the issue, how it was discovered, and any reproduction steps if relevant.]
896 
897**Impact:**
898[What part of the system is affected and how it impacts users or workflows.]
899 
900**Status:** Open
901**Priority:** [Low | Medium | High | Critical]
902**Owner:** [Team or individual responsible]
903**Reference:** [Optional: internal tracking ID, issue number, or ticket link]
904 
905---
906 
907### RESOLVED | [MM-DD-YYYY]
908 
909**Resolution Summary:**
910[Brief explanation of the fix or solution implemented.]
911 
912**Commit:** [Commit hash or link]
913**Linked PR:** [PR number or link]
914**Verified By:** [QA name or date]
915 
916---
917 
918## ✅ Examples — Real Issue
919 
920### Issue 1 | 10-19-2025
921 
922**Title:** Autosave fails silently when the editor tab loses focus.
923 
924**Description:**
925Users reported that when the browser tab is backgrounded during editing, the `design:updated` event is not always triggered. As a result, autosave does not fire, leading to potential data loss if the tab is closed or refreshed before a manual save.
926 
927**Impact:**
928 
929* Draft data can be lost unexpectedly.
930* Increases user frustration and reduces trust in autosave reliability.
931 
932**Status:** Open
933**Priority:** High
934**Owner:** Frontend Integration Team
935**Reference:** `editor_autosave_event_bug`
936 
937---
938 
939 
940## Definition of Done
941 
942* Users can: pick a template, edit, insert media via custom file manager, use saved blocks, apply style guide, insert merge/design tags, autosave, version, and export HTML.
943* All data persisted in Postgres; media stored and retrievable.
944* Tests green; docs complete; lint/format pass; CI pipeline in place.
945 
946---
947