Creators Agency Docs

Proposal Builder and Viewer ​

Last updated: 2026-04-06

1. Purpose and Users ​

The Proposal Builder lives inside the media kits app and gives agents a fast path from brand context to a polished, shareable proposal link.

It supports three main workflows:

  • build multi-creator, multi-package proposals on top of the existing roster,
  • generate sharp, brand-specific copy for openings, reasons, and closings,
  • share and edit proposals through a stable URL and internal dashboard.

Primary users: Charlie, Annie, Henry and other selling agents; Apple and sales leadership when reviewing or editing proposals.

2. URLs and Surface Area ​

All routes live under https://rosters.creatorsagency.co inside the media kits app.

Key routes:

  • /proposals – dashboard of drafts and published proposals,
  • /proposals/new – builder for a new proposal,
  • /proposals/edit/[uuid] (implicit) – builder for an existing proposal,
  • /proposals/view/[uuid] – brand-facing viewer, with optional edit mode,
  • vanity URL route – human-friendly slugs that map back to a proposal UUID.

The viewer is the only brand-facing surface. Everything else is internal.

3. High-Level Architecture ​

Shared app

  • Proposal Builder is part of the creator-media-kits-app repo.
  • It shares components, design system, and ca-data integration with media kits.

Storage

  • Proposal metadata and content are stored in Vercel Blob storage.
  • The client holds an in-progress working copy in localStorage for autosave.
  • A small set of API routes (/api/proposals/*) handle reading and writing blobs:
    • save, load, list, delete, track-view, upload-logo.

AI skills

  • Three internal API routes wrap Claude models for proposal copy:
    1. Opening paragraph (tldr),
    2. Why each creator,
    3. Closing paragraphs per package.
  • Prompts are tuned with strict style rules: no em dashes, no purple prose, no timelines, no negative qualifiers, no other brand names.

Data sources

  • ca-data for:
    • brand match context (/matches?brand=X&creator=Y),
    • creator roster data (niches, topics, rates, past integrations),
    • Fathom call summaries and objectives via Neon tables.
  • Close CRM and email for brand objective summaries (fetched by ca-data and related skills).

4. Data Flow Through the Builder ​

4.1 Creator selection (Step 1) ​

  • The roster grid pulls creators and stats from the same ca-data endpoints as the media kits app.
  • Filters combine:
    • platform pills,
    • minimum subscribers and views,
    • demographic cutoffs,
    • niches and topics search.
  • For each creator the agent can add deliverable rows and rate overrides.

The selection and deliverables form the base packages[0] lineup.

4.2 Brand setup and objectives (Step 2) ​

When the agent enters a brand name, a context pipeline runs:

  1. Look for recent Fathom calls that match the brand.
  2. If none, fall back to stored Fathom summaries in Neon.
  3. If still empty, fall back to Close CRM activity and email subjects.
  4. If all else fails, fall back to a generic objective such as "acquire new customers".

A separate objective-extraction skill turns any available context into 2–4 bullets. The agent can:

  • edit, add, or delete objectives inline,
  • paste additional context or a Fathom share link,
  • re-run extraction with a button.

All confirmed objectives feed into every AI skill.

4.3 AI generation ​

Once creators and objectives are set, the agent can trigger AI generation:

  1. Opening paragraph (TLDR)

    • Shared across all packages.
    • Frames the brand situation and one clear promise.

  2. Why each creator

    • One sentence per creator.
    • Uses:
      • content type and niche from ca-data,
      • demographics and audience profile,
      • sponsor history when available,
      • any manual agent notes.
    • Past sponsors are supporting evidence, not the main claim.

  3. Closing paragraphs

    • One short closing per package.
    • Uses package lineups, objectives, and creator niches.
    • Written as verdicts after the full lineup, not summaries of it.

All three skills enforce style and compliance rules at prompt level and often through post-processing.

4.4 Packages and compare view ​

  • Each proposal can have up to three packages.
  • Packages share the opening paragraph but have their own:
    • creator sets and deliverables,
    • closing paragraphs,
    • hide-rates flags,
    • optional commission flags,
    • compare notes.

The compare view shows packages side by side with:

  • reach, impressions, CPM,
  • total investment,
  • a per-package note field.

Agents can hide or show rates and CPM while still keeping structure intact.

4.5 Saving, publishing, and viewing ​

  • Draft state lives in localStorage under a dedicated key.
  • When the agent clicks Publish, the app:
    1. Builds a canonical proposal object (creators, packages, text, meta),
    2. Writes it to Vercel Blob at a stable key derived from the proposal UUID,
    3. Updates the Blob index that backs the /proposals dashboard.
  • The dashboard merges Blob index entries with any local drafts.

Viewer behavior:

  • /proposals/view/[uuid] loads the proposal from Blob.
  • ?preview=true query parameter opens viewer directly in edit mode for agents.
  • View tracking writes lastViewedAt and viewCount to Blob for dashboard insights.

Vanity URLs:

  • Agents can assign a human-readable slug (for example brand-q2-2026).
  • The slug maps back to the underlying UUID.
  • Slug conflicts are resolved by appending -2, -3, and so on.

5. Deployment and Environments ​

Because Proposal Builder is part of the media kits app, it shares:

  • the same GitHub repo (creator-media-kits-app),
  • the same Vercel project and domain (rosters.creatorsagency.co),
  • the same ca-data configuration.

Additional env and config items to watch:

  • Vercel Blob read/write token for proposals,
  • Close API key and any Gmail or Fathom tokens used in the context pipeline (through ca-data and helper scripts),
  • ca-data URL and token for proposal-specific endpoints.

Deploy flow:

  • push to GitHub,
  • Vercel auto-builds and deploys,
  • check /proposals and a known viewer URL after deploy.

6. Common Ops and Dev Tasks ​

6.1 Troubleshooting missing context or objectives ​

Symptoms:

  • objectives list is empty even though there were recent calls or emails,
  • AI opening paragraph feels generic.

Checks:

  1. Confirm ca-data has Fathom and Close data for the brand.
  2. Verify proposal builder API routes are calling the correct ca-data endpoints.
  3. Check extraction logs or console for errors when running the objective extractor.
  4. Allow manual paste plus re-extract as a fallback for the agent.

6.2 Fixing Why This Creator or closing copy issues ​

If AI reasons or closings feel wrong or repeat stale patterns:

  1. Review prompt text in the /api/proposals/* routes.
  2. Confirm inputs include:
    • updated niches and topics from ca-data,
    • accurate deliverable formats,
    • fresh objective bullets.
  3. Update prompts to reflect current sales guidance and constraints.
  4. Regenerate copy for a test proposal and review with Aaron or Charlie.

6.3 Blob index and loading bugs ​

Known failure modes from past work:

  • writes that created a new Blob file on every save instead of overwriting,
  • dashboard entries that pointed at stale blob URLs,
  • proposals that did not appear after edit because the index skipped them.

If you see these again:

  1. Inspect Blob put calls to ensure random suffixes are disabled where needed.
  2. Confirm the index file stores the canonical blob URL and UUID.
  3. Add tests or scripts that:
    • list all blobs under the proposals prefix,
    • verify every index entry has a corresponding blob.

6.4 Agent-facing UX fixes ​

Safe areas for quick improvement:

  • labels and helper text on steps,
  • small layout changes in Step 1, Step 2, or compare view,
  • additional warnings when objectives are missing or AI fields are blank.

Changes that need coordination:

  • altering multi-package behavior or limits,
  • changing rate visibility rules in the viewer,
  • changing how objectives are sourced or prioritized.

7. How other agents and skills should use Proposal Builder ​

Human agents and TAs

  • Use Proposal Builder as the default path from Brand Match / media kits into proposals. Start from a clear brand + creator slate, then move into /proposals/new instead of drafting from scratch in Google Docs.
  • Keep proposals as the single source of truth for package structure and pricing; if you change rates or lineups after sending, update and republish the proposal so the viewer link always matches what the brand last saw.
  • For review cycles, circulate the viewer URL (not screenshots) so Apple and sales leadership can see real-time edits and view counts.

Automation and internal agents

  • Treat proposals as structured artifacts stored in Vercel Blob — do not write directly to Blob from ad-hoc scripts unless you fully understand the schema in memory/project-proposals.md.
  • When another agent needs proposal context (for example, Sales Enablement Agent summarizing pipeline), it should:
    • read from Proposal Builder APIs or Blob-backed lists,
    • never re-implement core logic like multi-package math or view tracking.
  • The proposal-brand-context skill is the right place to assemble objectives and brand background; Proposal Builder then consumes that context via ca-data and its own API routes.
  • When generating external-facing copy or docs, treat the Proposal Builder viewer as the canonical representation and optional Google Docs as exports, not the other way around.

8. Related Docs and References ​

  • memory/project-proposals.md for a detailed build log, edge cases, and open items.
  • memory/project-media-kits.md for how proposals share infrastructure with media kits.
  • docs/creators-agency/media-kits.md for the broader media kits and rosters system.
  • Google Docs:
    • Proposal Builder Jude-facing dev doc,
    • Proposal edge case audit doc (links in memory/project-proposals.md).