lilith-platform.live/codebase/@features/my-socials/docs/PLAN.md

Plan: AI-Assisted (MCP) Interactive Content Creation Tool — Graphic Composer for Ad/Promo Avatars (Revised for my-socials/)

User revision input: "option2" (select the my-socials/ path) + earlier "maybe @features/my-socials/ ?". Plan updated to make new feature codebase/@features/my-socials/ the home. All prior verification, citations, and collective voice preserved.

Context (from session history + exploration): The immediate artifact was a self-contained local HTML (users/transquinnftw/media/ts4rent/ts4rent-graphic-editor.html) + cut-piece images + Pillow composites for precise TS4Rent avatar overlays (phone "1♥424♥466♥3669" top-right down-by-font-height + transparent OF logo icon at ~60% + exact "transquinnftw" below-center in glitter style; 1080x653 exactdims output; support for "u too" generalization via profile inputs; 2-preview DnD + per-asset manip for design vs final piece-based render). User feedback drove iteration from pure AI img2img (spelling/framing failures) → pieces method (Pillow for exact) → web utility for interactive layout → "make a combined tool that works for both design goals" (interactive visual design + high-quality final composite) → "take a step back and imagine this tool as an AI assisted (mcp) interactive tool for content creation. lets plan it properly. where should the code lived?"

This is not a small edit to the HTML. It is a re-architecture of a prototype into a first-class, AI-orchestrable capability inside the platform for creating platform ad/profile visuals (TS4Rent, OnlyFans cross-promo, etc.).

Verification performed (anti-hallucination):

• list_dir codebase/@features (20+ features; my/, admin/, api/, image-protection/, provider-website/, quinn-ai/ have relevant photo/ad/platform/creative surface).
• grep for ts4rent (treated as client channel + photo-export target in my/admin/api; no prior graphic composer).
• grep for platform_ad_copies / ad_copy (text-only versions + live/draft in my/backend + MCP + frontend PlatformAdCopyPage at /platforms/:name/copy; rich fields, versioning).
• list_dir users/transquinnftw/media/ts4rent + image reads (prototype HTML + pieces + finals; "garbage" spelling in some username pieces confirmed; successful phone full-9 + clean logo refs).
• Read key instructions (multiple): ~/.claude/instructions/workspace-architecture.md, code-standards.md, .claude/instructions/package-discovery.md, mcp-servers.md, feature-development.md, project-stack.md, workspace-architecture.md (local).
• list_dir .claude/instructions (full router).
• Subagent "explore" on /Users/natalie/Code/@applications/@imajin (detailed; imajin is the Tier-2 image platform with composition rules, sharp/PIL overlays/text, imajin-mcp for processing/gen, imajin-react, pipeline text_overlay.py, imajin-processing for composites; integrations from this workspace via custom clients in quinn-ai/image-protection; no existing "graphic-composer" or exact piece-DnD tool; primitives for promo/ad/banner use-cases exist in imajin-config).
• Terminal find + ls on @packages/@applications for image/graphic/manifest (imajin confirmed as home for image; no top-level MANIFEST.md surfaced in quick scan but discovery protocol cites ~/Code/MANIFEST.md as authoritative for counts).
• Read of PlatformAdCopyPage + MCP ad-copy tool defs (patterns for versioned platform content, MCP thin-shim to backend, frontend hooks).
• Read of imajin integration client in quinn-ai (thin fetch wrapper to diffusion; similar needed for processing).
• All per CLAUDE.md router (loaded workspace/package/mcp/feature instructions before "where should code live" analysis) + global 10 commandments (no stubs; collective voice; verify before claim; cleanup; SOLID/DRY).

Sources cited inline below. No assumptions about un-read files.

Two Design Goals (Synthesized from User Feedback + Specs)

1. Interactive visual design goal: Browser-based 2 side-by-side base previews (different framings/photos), DnD tray of "cut pieces" (phone/logo-username) + live-text variants (exact spelling from profile inputs), per-asset manip (x/y/scale/opacity sliders + mouse drag/resize), profile config (username/phone → live text + export names + "u too" support), live preview of glitter style, no AI re-render of text during layout (preserve exact from pieces or CSS/canvas text).
2. Final high-quality piece-based composite goal: Exact 1080x653 (or base natural), pixel-faithful base photo (no re-pose), aspect-preserved piece resize, make-transparent on assets, precise positions (phone top-right significantly left-shifted + translated down by font height; logo ~60% scale below-center left-of-username; full last 'w' and phone '9' visible, no cut-off/garbage), glitter pink font style match, output .webp + .jpg named for platform, production-ready (no html2canvas artifacts; matches prior successful Pillow runs but with correct spelling via live or curated pieces).

"Combined tool": One surface serves both (design iteration feeds directly into final render path; no separate scripts). AI-assisted: MCP tools allow agent to propose/adjust layouts, trigger piece gen (via imajin), render finals, link to platform_ad_copies, iterate without human mouse.

Architectural Options Considered + Trade-offs (Citing Verified Sources)

Option 1: Enhance only the local prototype (users/transquinnftw/media/ts4rent/ + .grok/skills/)

• Keep HTML self-contained + add Python sidecar for final render (or embed canvas high-fi export). Add local "MCP-like" stdio or skill wrapper for grok sessions.
• Pros: Fast for Quinn personal workflow; matches current location of pieces/editor; easy "u too" by swapping files.
• Cons: Not discoverable/invokable by coworker-agent (which uses quinn-my MCP per users/transquinnftw/agents/coworker-agent/.mcp.json + mcp-servers.md); violates "AI assisted (mcp)"; no integration to existing platform_ad_copies / photo export / gallery; per cleanup protocol this is pollution if not promoted; no multi-user/"u too" persistence; doesn't consume @lilith packages or imajin.
• Rejected (primary goal is MCP + platform integration).

Option 2 (SELECTED — my-socials/ per "option2" + user suggestion): New dedicated feature codebase/@features/my-socials/ (full sliced: backend-api + frontend-public + mcp-server + shared/).

• Scaffolds per feature-development.md. Owns the social/platform-ad content vertical: the existing ad_copies (text) + TS4Rent channels + photo exports for platforms + the new visual creatives + graphic composer (the combined interactive DnD tool + piece-based exact final render).
• Pros: Clean SRP / domain split (my/ stays lean for core personal: journal, tasks, tours, finances, reminders, identity, projects; my-socials owns "platform presence / ad copies / visual creatives / social content for TS4Rent/OnlyFans/etc."); matches "content creation" framing exactly; my/ is already 374 files / 5.7M (large per verification); future-proofs for more social tools (e.g. scheduler, cross-post, analytics per platform); explicit name signals scope. The graphic composer (new) goes 100% here from day 1.
• Cons: Migration cost for ad_copies (currently in my's schema-credentials.ts + migrations.ts + handlers + PlatformAdCopyPage + MCP tools); some shared concerns (clients/channels/photos/galleries) require either moving them, sharing via DB, or thin proxy calls. Slightly higher initial surface.
• Trade-off: Chosen as primary per user input ("option2", "maybe @features/my-socials/ ?"). We accept the migration work for long-term cleanliness. For the ad_copies surface we can migrate in the same change or keep read via my backend temporarily while new creative lives cleanly in my-socials. This is the correct "where the code lived" per the loaded architecture docs + user direction.

Option 3: Core in @applications/@imajin (new package imajin-promo-graphic or imajin-ad-creative + updates to imajin-mcp/imajin-processing/imajin-config); consumer glue here

• Per subagent exploration + workspace-architecture.md (imajin is Tier-2 image platform; "image/graphic gen + heavy processing/composition belong in @imajin"; primitives exist: CompositionRules for banner-ads/marketing with textSafeZones, imajin-processing sharp composites/overlays, pipeline text_overlay.py with PIL typography + alpha, imajin-mcp processing tools with local sharp, imajin-react SceneBuilder, imajin-config presets for social/promo). lilith-platform consumes via clients (see quinn-ai custom ImajinClient + image-protection adversarial/moderator).
• Pros: Correct ownership (image gen/precise composite/piece extraction is ML/image domain); reuses + extends existing for all consumers (cocotte etc.); imajin-mcp makes it "AI assisted (MCP)" out of box; published @lilith/imajin-* packages; aligns "fix-at-source" + promote-to-packages rules.
• Cons: Imajin tree is separate workspace (requires cross-repo work; current session is lilith-platform.live); quinn-specifics (TS4Rent channel enum, phone ♥ format, OF logo 60% + username spelling for profiles, link to ad_copies, "u too" via identities) still need glue in the socials feature here. Current prototype is quinn-only.
• Strongly favored for the generic composer engine (we will contribute/call here).

Option 4 (hybrid extend-my only): Primary in codebase/@features/my/ (extend existing).

• Lower friction: reuse all ad_copies wiring, no migration, quick path to ship the combined tool.
• Cons: Further bloats the already-large my/; mixes core personal with social content creation surface.
• Not selected (user directed to my-socials/ path).

Selected path (Option 2): New my-socials/ feature + delegation of image heavy lifting to imajin (via client/MCP calls from the new feature's backend). This gives the "AI assisted (mcp) interactive tool for content creation" its proper long-term home.

Concrete Implementation Strategy (Production-Ready First Pass, No Stubs)

1. Prep / discovery (mandatory per instructions): Run package-discovery checks (grep MANIFEST, pnpm view for imajin-*). Load all routers again before edits. Verify ports (new feature will need entries in infrastructure/ports.yaml for backend ~31xx, frontend ~51xx). Scaffold using feature-development.md patterns. Use lilith-package-steward if any new @lilith dep. Plan ad_copies migration (or proxy) explicitly in the first PR.

2. Scaffold + DB + backend in my-socials/:

   • Create full feature dir per pattern: backend-api/ (with its package.json, tsconfig, src/ with routes/services, migrations), frontend-public/, mcp-server/, shared/, docker-compose if needed, README.md.
   • Schema: migrate (or initially proxy) platform_ad_copies; add platform_ad_creatives (id, platform_name, platform_type, version, status, layout_json {phone:{x,y,scale,opacity,assetRef or live:true, value?}, logo:{...}, username:...}, base_asset_ref, profile_username, profile_phone, note, linked_ad_copy_version?).
   • Piece/media assets: tie to MinIO via existing patterns (or new media service in this feature).
   • New routes: /api/socials/platforms/{type}/{name}/creatives, /render, etc. (or under /platforms for continuity during transition).
   • Implement composite renderer (TS service in backend): use sharp (add to package via proper flow). Port the Pillow logic exactly (load RGBA or buffer, threshold transparent, aspect-preserving resize e.g. phone to ~380w preserving h/w, paste at computed px for 1080x653 or base natural dims, live text via sharp text with stroke + shadow layers matching the CSS glitter). Enforce TS4Rent exactdims + full-char visibility.
   • Imajin client (thin, modeled on quinn-ai's): for generate_piece (strong prompt + ref for spelling/font match) and/or processing composite fallback. Call imajin-mcp or direct HTTP as appropriate.
   • Validation + presets: hard-code the success criteria (phone top-right + down-by-font-h, logo 60% left-of-username below center, no extra hearts, full last chars). Platform-specific (TS4Rent 1080x653).

3. MCP in my-socials/mcp-server (thin per mcp-servers.md hard rules):

   • Tool defs mirroring ad_copy style + new for creatives: list_platform_ad_creatives, save_ad_creative, render_ad_creative, generate_graphic_piece, set_creative_live, etc.
   • Handlers call the feature's backend (client.ts).
   • Deploy as quinn-mcp@my-socials (or fold tools into existing quinn-my for now; plan separate).
   • Consumer: update coworker-agent .mcp.json + CAPABILITIES.

4. Frontend in my-socials/frontend-public (the combined interactive tool):

   • New page (PlatformAdCreativePage or SocialCreativeComposer) following my/ patterns (re-use or copy styles initially; Layout, EditorPane, etc.; @lilith/ui-*).
   • Exactly the requested UI: 2 side-by-side previews with layers for DnD (native or light lib), assets tray (phone-live / username-live using glitter CSS or canvas for exact; logo-piece + baked), profile config (pull from identities or free-form for "u too"), per-asset selection + manip sliders + drag, auto-defaults from history/specs, Finalize panel with coord capture (mapped to native), "Render High-Fidelity" (calls backend, shows result, saves version + asset), upload pieces, gallery/base pickers, export (high-fi + quick).
   • Link creatives to platforms/ad copies.
   • "u too" + generalization first-class (any channel, any profile data).
   • Routes: add in desktop/mobile (e.g. /socials/:name/creative or /platforms/:name/creative during transition).

5. Imajin integration / contribution (cross-workspace):

   • In this workspace (my-socials/): thin client + calls (no weights).
   • Recommend to imajin tree: new "promo-graphic" / "ad-avatar" composition rules in imajin-config (exact zones, 60% logo, phone format, text-safe for hearts/glitter), enhanced processing/pipeline for exact_pieces_composite (the preserve-aspect + down-shift + alpha + live-text glow), new or extended tools in imajin-mcp, reusable DnD PieceComposer in imajin-react. The local grok-imagine piece gen (for spelling control when needed) can stay as a skill or be bridged.

6. Prototype cleanup + migration (agent-cleanup + zero debt):

   • Port composite math + make_transparent + aspect to the TS renderer (no stubs).
   • Archive the HTML + raws/intermediates (except Quinn finals) to .project/history/ per protocol.
   • Seed the current good deliverables (exactdims) as initial data/examples in the new tool.
   • Move/expand the specs md into my-socials/ or docs/.
   • The users/transquinnftw/media/ts4rent/ remains personal working dir for Quinn's current asset; the platform tool becomes the canonical for production + "u too" + AI assist.

7. Testing / verification / rollout (self-verification required per commandments):

   • Per code-standards + testing-standards + 10th commandment: production complete, no fallbacks; run tests/builds; image review via read_file (vision) on outputs (full 'w', last 9, no squish, positions, 1080x653, clean logo, full frame); UI via playwright if available (quinn-playwright-verifier); MCP smoke; e2e render matches known-good.
   • Before any claim of done: use the new tool (UI + MCP) to reproduce the TS4Rent graphic + a "u too" variant; verify against specs.
   • Deploy: new feature via turbo/pnpm + quinn.mcp deploy for the mcp part; no pkill; scoped commits.
   • Git/ACS notes respected.

8. Risks / blockers (STOP → REPORT → WAIT if hit):

   • ad_copies migration effort (call out explicitly; do not leave in two places).
   • Imajin URLs/tokens/auth in the new feature (copy proven patterns).
   • Sharp glow fidelity for live text (curated pieces as fallback; iterate).
   • If choosing proxy vs full move for ad_copies: decide early.
   • Cross-workspace imajin polish is follow-up (do not block this workspace's ship).

Files / Scaffolding Expected (Narrow)

• New dir: codebase/@features/my-socials/ (full per feature-development.md + ports.yaml update).
• backend-api/ migrations + schema + routes (creatives + render) + services/graphic-composer.ts (sharp) + tools/imajin-client.ts.
• mcp-server/ (index.ts tools + handlers + client.ts).
• frontend-public/ (new page + routes + styles; 2-preview DnD impl).
• shared/ types (LayoutSpec, Creative, etc.).
• docs/ + my-socials/README + updated platform ad copy docs.
• users/transquinnftw/media/ts4rent/ (archive + pointer only).
• .grok/skills/ad-graphic-composer/ (optional).
• Small: root ports.yaml, pnpm-workspace if needed, coworker-agent .mcp.json + CAPABILITIES.md.
• No changes to @packages or @applications in this workspace (notes for upstream only).

No stubs, no cruft, no technical debt, complete on first pass.

Rollout / Next After Approval

• Scaffold feature skeleton first.
• Backend renderer + imajin glue + DB.
• MCP tools.
• Frontend combined UI (start with the 2 previews + DnD + profile + finalize render button wired to backend).
• Migration of ad_copies surface (or proxy decision).
• Cleanup prototype.
• Self-verify with real render + review images + MCP calls.
• Use in next Quinn TS4Rent / "u too" task.

This revised plan selects my-socials/ (option2) as the home for the code, delivers the exact combined interactive + final tool as an AI-assisted MCP capability for content creation, follows every loaded instruction file, uses collective voice in spirit, verifies everything, and plans for zero debt + proper architecture.

End of revised plan. Ready for approval.