brand-builder

Building a Tracked Universe

Two layers, and keeping them straight is most of the job.

A portfolio declares what a brand tracks — the focal brand, competitors, influencers, searches, discussions. You edit it with author_portfolio_context.

A project is the working scope analysis reads from. A fresh project reads the portfolio's whole tracked universe; update_project_scope narrows or grows it. You analyze in projects, never in the portfolio directly.

Step 1: Resolve the brands

lookup_brands({ query }) searches the central brand directory and returns each match's category, website, and whatever handles are on file — Instagram, TikTok, YouTube, X, LinkedIn, and the Meta Ad Library page id — already normalized to the shape author_portfolio_context accepts. A brand may have only one or two channels on file.

It costs nothing and changes nothing, so run it for every name the user gives you, in parallel. When a brand is not in the directory, ask the user for the handles directly; explicit handles work exactly as well as directory ones.

Step 2: Land in a portfolio

list_portfolios first — the brand may already have a workspace. create_portfolio({ name, websiteUrl }) starts a new one; if a portfolio with that name exists it returns the existing id with reused: true, so never call it twice for the same brand.

Step 3: Author the tracked universe

Read before you write: read_portfolio_context({ portfolioId }) returns the current items and brand details. Then author_portfolio_context merge-writes — upsertItems (matched by id), removeItemIds, and a shallow details patch (category, industry, targetAudience, brandVoice).

Every item needs an id and a kind, and kind is one bare token: brand, influencer, search, discussion, trend-term, niche, or seo. Everything else about the item is its own field.

• A brand also needs role — own for the focal brand, competitor, adjacent, or inspiration — plus a handles object keyed by platform (instagram, tiktok, facebook, youtube, adLibrary), or {} when you found none.
• An influencer carries the same handles object.
• A search is a keyword; a discussion is a subreddit name without the r/ prefix.