diff --git a/aligned-onboarding/README.md b/aligned-onboarding/README.md old mode 100755 new mode 100644 index 2519900..63863ef --- a/aligned-onboarding/README.md +++ b/aligned-onboarding/README.md @@ -1,51 +1,62 @@ # Meta Onboarding Package: Overview This package teaches Runneth how to understand and work inside a customer's Meta ad account. It -ships as two parts that live side by side. Install and run them in order. +ships as three parts that live side by side. Install and run them in order. -The two parts: +The three parts: - **Account Context Brain** - how Runneth should analyze this account. -- **Creative Corpus** - the per-creative attributes Runneth analyzes. +- **Report Dashboard Setup** - how this customer wants report, dashboard, and app readouts built. +- **Creative Corpus** - durable creative context Runneth can reuse when it helps future analysis. The one-line model: -> **The Account Context Brain tells Runneth how to analyze the account. The Creative Corpus gives -> Runneth the per-creative attributes it needs to actually do the job.** +> **The Account Context Brain tells Runneth how to analyze the account. The Report Dashboard Setup +> tells Runneth how to package that analysis for this customer. The Creative Corpus gives Runneth the +> durable creative context it should reuse, while exact creative content stays in Motion.** -The Creative Corpus depends on the Account Context Brain and never re-derives it. Keep them as two -files: they do different jobs, persist to different places, and refresh on different cadences. +Report Dashboard Setup and Creative Corpus both depend on the Account Context Brain and never +re-derive it. Keep them as separate files: they do different jobs, persist to different places, and +refresh on different cadences. --- ## Where the package files live -These instruction files (this overview, the Account Context Brain, the Creative Corpus, and the -Motion CLI Data-Query Guide) are the package itself, not its output. They live in the Brain outside -the `meta` folder structure; the exact folder for them is not fixed yet and can be decided later. -corpus-search is a bundled tool, not an instruction file, and installs under -`/agent/tools/corpus-search/`. The `meta` folder holds only what Runneth generates from running the -package: the filled account context and the per-creative files. +These instruction files (this overview, the Account Context Brain, the Report Dashboard Setup, the +Creative Corpus, and the Motion CLI Data-Query Guide) are the package itself, not its output. They +live in the Brain outside the `meta` folder structure at `/agent/brain/aligned-onboarding/`. +corpus-search is an optional companion tool, not an instruction file, and installs under +`/agent/tools/corpus-search/` when needed. The `meta` folder is the package's first-run default +output area for what Runneth generates from running the package. Before writing, resolve the owning +customer setup location from an installed guard, `/agent/INDEX.md`, or customer-edited setup. Create +the package default only when no established file already owns that workspace's account context, +report/dashboard setup, or creative context. --- -## Scope rules (apply to both parts) +## Scope rules (apply to all three parts) - **Meta only.** Never look for or pull other ad platforms (TikTok, LinkedIn, YouTube). - **Ignore Motion workspace settings.** Treat workspace goal, preferred KPI, spend threshold, and attribution config as if they do not exist. Everything comes from auto-pulled Meta ad data, the worksheet, and customer confirmation. - **One workspace at a time.** Every auto-pull names the account with `--workspace-id `. -- **Brain files are customer-facing.** Only account interpretation goes into the saved files. Never - save internal Runneth-team content: tool-calling nuances, CLI commands or flags, - command-vs-command discrepancies, or debugging notes. Metric nuances about how a metric shows up - in this account are welcome, written in business terms. +- **Brain files are customer-facing.** Saved outputs hold account interpretation, report/dashboard + preferences, and creative attributes. Never save internal Runneth-team content: tool-calling + nuances, CLI commands or flags, command-vs-command discrepancies, or debugging notes. Metric + nuances about how a metric shows up in this account are welcome, written in business terms. +- **Customer setup stays visible and editable.** Report/dashboard preferences, saved-report trust + rules, taxonomy, delivery cadence, and visual standards are customer-owned setup. Resolve the + workspace's reporting/app setup file before writing; use this package's default only when one does + not exist yet. Do not hide these rules in app code, runtime config, scratch files, or + conversation-only memory. - **Onboarding pull window.** The fill-in auto-pulls default to `last_365d` so onboarding sees enough history. This governs the fill-in only, not later performance queries. --- -## The two parts +## The three parts ### Account Context Brain File: `account-context-brain.md` @@ -56,23 +67,42 @@ File: `account-context-brain.md` targets). - **How it runs:** auto-pull, then confirm with a person, then validate, then flag what it cannot capture. `[AUTO]` values are proposals until a person confirms them. -- **Persists to:** `/agent/brain/meta/account-context.md` (create the `meta` folder if needed) +- **Persists to:** the established indexed account-context file for this workspace, or this + package's default if one does not exist yet. - **Activation:** merges a read-before-performance guard into `/agent/user.md`. - **Refresh:** monthly cadence plus structural-drift triggers, logged in `/agent/brain/meta/_changelog.md`. +### Report Dashboard Setup +File: `report-dashboard-setup.md` + +- **Job:** capture how this customer wants Runneth to build report, dashboard, app, and weekly-readout + surfaces so they do not repeat the same preferences every time. It covers standard views, trusted + sources, metrics, thresholds, date windows, taxonomy, creative evidence, visual standards, cadence, + generated-app quality standards, reusable component roles, and validation questions. +- **How it runs:** reads the Account Context Brain first, inspects any saved Motion report metadata + and existing app/routine registry entries when available, then asks a short confirmation with a + person. It captures only customer-facing preferences and labels uncertain items as open. +- **Persists to:** the established indexed reporting/app setup file for this workspace, or this + package's default if one does not exist yet. +- **Activation:** extends the account-context guard with a read-before-reporting rule. +- **Refresh:** after reporting setup calls, when saved Motion reports change, or when a built + dashboard gets corrected by the team. Log updates in `/agent/brain/meta/_changelog.md`. + ### Creative Corpus File: `creative-corpus-playbook.md` -- **Job:** build and maintain one enriched record per active creative (identity, summary, hook, - value props, transcript, AI tags, naming), the attributes Runneth uses to do the analysis the - Account Context Brain defines. +- **Job:** maintain customer-facing creative context (identity, summary, hook, value props, + transcript notes, AI tags, naming) when those attributes are useful for future analysis. Motion or + the creative store remains authoritative for exact creative assets, previews, and current + source-backed content. - **How it runs:** reads what the Account Context Brain already knows, then pulls from Motion only - what the Account Context Brain cannot tell it (the creative content itself). No separate corpus - tool to install. -- **Persists to:** individual creative Markdown files under `/agent/brain/meta/creatives/`, plus an - optional tagging taxonomy at `/agent/brain/meta/creatives/_tagging-taxonomy.md`. -- **Retrieval:** automatic through Knoweth. Writing the file is the index step. + what is needed to create or refresh saved creative context. Default Brain retrieval can pick up + intentionally saved files; corpus-search can be installed as the optional filterable supplement. +- **Persists to:** the established creative-context location for this workspace, or this package's + default if one does not exist yet. Keep an optional tagging taxonomy beside that creative context. +- **Retrieval:** automatic through default Brain retrieval for saved Brain files. Use stable names, + source IDs, tags, and `/agent/INDEX.md` entries to make saved context findable. - **Maintenance:** daily and event-triggered updates as creatives change. --- @@ -81,18 +111,17 @@ File: `creative-corpus-playbook.md` File: `motion-cli-data-query-guide.md` - **Job:** the canonical contract for how Runneth pulls Meta, TikTok, Inspo, benchmark, and - workspace-setup data through the `motion` CLI, so queries come out right on the first try. Both - parts above lean on it for their auto-pulls. + workspace-setup data through the `motion` CLI, so queries come out right on the first try. The + package procedures lean on it for their auto-pulls. - **Not run on its own.** It's reference knowledge, not a step to execute. It is brand-agnostic and carries no account-specific IDs. -### corpus-search (bundled tool) +### corpus-search (optional companion tool) Source: `Motion-Creative/runneth-apps/corpus-search` -The package ships with **corpus-search**, a local hybrid-retrieval CLI, to **supplement** Knoweth -(not replace it). Knoweth stays the default: everything written under `/agent/brain/` is surfaced -automatically as pre-context. Reach for corpus-search when you need deliberate, filterable search -over a lot of raw text. +The package reuses **corpus-search**, a local retrieval CLI, to supplement default Brain retrieval +when deliberate, filterable search over a lot of raw text is needed. Saved Brain files remain the +default context source. **corpus-search is a general raw-text retrieval layer, not a creative-only tool.** The Creative Corpus is one source it indexes; it is meant to hold any high-volume raw text the brain accumulates, @@ -102,10 +131,9 @@ similar. Everything shares one index, kept separate by the `kind` tag (`creative - **Install:** stage it under `/agent/tools/corpus-search/`, then run `bash /agent/tools/corpus-search/install.sh` and resolve its checklist. -- **Requires `OPENAI_API_KEY`** reachable in the workspace for embeddings. If the checklist flags it - as missing, request it securely (host `api.openai.com`), never pasted into chat. Some workspaces - pre-provision it. -- **Register sources by kind:** for this package, add `/agent/brain/meta/creatives` to +- **Credentials:** if the checklist flags a missing credential, request it securely and never ask for + it to be pasted into chat. Some workspaces pre-provision it. +- **Register sources by kind:** for this package, add the resolved creative-context folder to corpus-search's `sources.json` with `kind: creative`. Register other raw-text folders (reviews, voice-of-customer, transcripts) the same way under their own `kind` so `refresh` keeps them all current. Give each indexed file frontmatter (`brand`, `workspace`, `source_id`, and `event_at` @@ -118,25 +146,38 @@ similar. Everything shares one index, kept separate by the `kind` tag (`creative 1. **Install the package.** Staging the files does not self-run anything. 2. **Activate the Account Context Brain.** Merge its guard block into `/agent/user.md`. 3. **Run the Account Context Brain fill-in.** Auto-pull, confirm with a person, validate, flag - gaps. This writes `/agent/brain/meta/account-context.md`. -4. **Install corpus-search.** Run `bash /agent/tools/corpus-search/install.sh`, resolve its - checklist (including `OPENAI_API_KEY`), and register `/agent/brain/meta/creatives` as a source - with `kind: creative`. One-time; can happen before or after the corpus is built. -5. **Build the Creative Corpus.** With the Account Context Brain in place, generate the per-creative - attribute files (each with its frontmatter). The Creative Corpus reads the Account Context Brain - for interpretation. Then index the folder into corpus-search so filterable search is available. -6. **Keep both current.** The Account Context Brain on its refresh cadence, the Creative Corpus on - daily and event-triggered maintenance, and refresh the corpus-search index on that same cadence. + gaps. This updates the established indexed account-context file for this workspace, or creates the + package default if none exists yet. +4. **Run Report Dashboard Setup.** Read this workspace's account-context file, capture the team's + reporting preferences, update the established reporting/app setup file or create the package + default, and index it in `/agent/INDEX.md`. +5. **Install corpus-search when deliberate filterable search is needed.** Run + `bash /agent/tools/corpus-search/install.sh`, resolve its checklist, and register the resolved + creative-context folder as a source with `kind: creative`. One-time; can happen before or after + the corpus is built. +6. **Build the Creative Corpus.** With the Account Context Brain in place, generate or refresh the + saved creative-context files that are useful for future analysis. The Creative Corpus reads the + Account Context Brain for interpretation and the Report Dashboard Setup when report surfaces need + creative evidence rules. If corpus-search is installed, refresh that source so filterable search + is available. +7. **Keep all three current.** The Account Context Brain on its refresh cadence, Report Dashboard + Setup when report preferences or saved reports change, the Creative Corpus on daily and + event-triggered maintenance, and refresh corpus-search on that same cadence when it is installed. --- -## How the two parts relate +## How the three parts relate -- The Account Context Brain is the lens; the Creative Corpus is the material. A performance question - uses the Account Context Brain to decide what "best" means and which numbers to trust, then the - Creative Corpus to reason about the specific creatives. +- The Account Context Brain is the lens, Report Dashboard Setup is the packaging rulebook, and the + Creative Corpus is the material. A dashboard request uses the Account Context Brain to decide what + "best" means, Report Dashboard Setup to decide which view, metric order, thresholds, and evidence + belong on the surface, then the Creative Corpus to reason about the specific creatives. Report + Dashboard Setup also carries the app-quality floor for readable labels, stable cards, explicit + media states, visible caveats, and the component roles that should map onto the active app + scaffold. - The Account Context Brain's read-before-performance guard is what forces the lens to be loaded - before any performance work. The Creative Corpus is surfaced automatically through Knoweth when - creatives are discussed. -- The dependency runs one way: the Creative Corpus reads the Account Context Brain. The Account - Context Brain never depends on the Creative Corpus. + before any performance work. Report Dashboard Setup adds the read-before-reporting preferences. + The Creative Corpus is surfaced automatically by default Brain retrieval when creatives are + discussed. +- The dependency runs one way: Report Dashboard Setup and Creative Corpus read the Account Context + Brain. The Account Context Brain never depends on the other two. diff --git a/aligned-onboarding/SKILL.md b/aligned-onboarding/SKILL.md index e6973e1..21fbffc 100644 --- a/aligned-onboarding/SKILL.md +++ b/aligned-onboarding/SKILL.md @@ -1,39 +1,47 @@ --- name: aligned-onboarding description: > - Teaches Runneth how a customer reads their Meta ad account, then builds and maintains one - enriched record per active creative. Two parts run in order: the Account Context Brain (how to - analyze the account) and the Creative Corpus (the per-creative attributes). Meta only, one - workspace at a time. Trigger on "run aligned onboarding", "set up my Meta account context", - "build my account context", "teach Runneth how we read the account", "build the creative corpus", - or when a Meta performance question is asked and /agent/brain/meta/account-context.md does not - exist yet. + Teaches Runneth how a customer reads their Meta ad account, captures customer-specific report and + dashboard setup, then builds and maintains saved creative context. Three parts run in order: the + Account Context Brain (how to analyze the account), Report Dashboard Setup (how to package + account analysis for this team), and the Creative Corpus (durable creative attributes when useful). + Meta only, one workspace at a time. Trigger on "run aligned onboarding", "set up my Meta account + context", "set up report dashboard context", "teach Runneth how we read the account", + "teach Runneth how we build dashboards", "build the creative corpus", or when a Meta performance + or reporting question is asked before an account-context file is established for the workspace. triggers: phrases: - "run aligned onboarding" - "aligned onboarding" - "set up my meta account context" - "build my account context" + - "set up report dashboard context" + - "set up dashboard reporting" - "teach runneth how we read the account" + - "teach runneth how we build dashboards" + - "build report dashboard context" - "build the creative corpus" - "onboard my meta account" - intent: "User wants Runneth to learn how their Meta account should be interpreted and build the per-creative corpus." + intent: "User wants Runneth to learn how their Meta account should be interpreted, how report/dashboard surfaces should be packaged, and how to build saved creative context." --- # Aligned Onboarding -Teaches Runneth how this customer reads their Meta ad account, then builds the per-creative corpus -off that lens. It ships as two parts that do different jobs and persist to different places. +Teaches Runneth how this customer reads their Meta ad account, captures how the team wants reports +and dashboards packaged, then builds saved creative context off that lens. It ships as three parts +that do different jobs and persist to customer-owned locations. The one-line model: -> The **Account Context Brain** tells Runneth **how to analyze** the account. The **Creative -> Corpus** gives Runneth **the attributes it needs to actually do the job**. +> The **Account Context Brain** tells Runneth **how to analyze** the account. **Report Dashboard +> Setup** tells Runneth **how to package that analysis for this team**. The **Creative Corpus** +> gives Runneth **durable creative context it should reuse when useful**. Read the package overview at `/agent/brain/aligned-onboarding/README.md` before running. The full -procedures live in the staged docs and are the source of truth for each step: +procedures live in the staged docs and define the contract for each step: - Account Context Brain: `/agent/brain/aligned-onboarding/account-context-brain.md` +- Report Dashboard Setup: `/agent/brain/aligned-onboarding/report-dashboard-setup.md` - Creative Corpus playbook: `/agent/brain/aligned-onboarding/creative-corpus-playbook.md` - Motion CLI data-query guide: `/agent/brain/aligned-onboarding/motion-cli-data-query-guide.md` @@ -44,8 +52,12 @@ procedures live in the staged docs and are the source of truth for each step: attribution config as if they do not exist. Everything comes from auto-pulled Meta data, the worksheet, and customer confirmation. - **One workspace at a time.** Every auto-pull names the account with `--workspace-id `. -- **Brain files are customer-facing.** Save only account interpretation. Never write tool-calling +- **Brain files are customer-facing.** Save account interpretation, report/dashboard preferences, + taxonomy, cadence, and creative attributes in plain business language. Never write tool-calling nuances, CLI commands or flags, or debugging notes into the saved files. +- **Customer setup stays visible and editable.** Report/dashboard preferences belong in the + established indexed reporting/app setup file for the workspace. Use this package's default only + when that file does not exist yet. Do not hide those rules in runtime config or app code. - **Onboarding pull window is `last_365d`** for the fill-in only, so onboarding sees enough history. ## Run order @@ -58,23 +70,43 @@ procedures live in the staged docs and are the source of truth for each step: Replace an existing block in place; never duplicate it. 3. **Run the Account Context Brain fill-in.** Follow `account-context-brain.md`: auto-pull all nine fields, present them together as one overview, confirm the open questions with a person, - validate, and flag what cannot be captured. Write the prose result to - `/agent/brain/meta/account-context.md` and index it in `/agent/INDEX.md`. `[AUTO]` values stay - proposals until a person signs off. -4. **Reuse corpus-search (optional but recommended).** If `/agent/tools/corpus-search/` is not - already present, fetch corpus-search from the public library and install it per its own - install-config; never clobber a customized copy. It supplements Knoweth for deliberate, - filterable search. Register `/agent/brain/meta/creatives` as a source with `kind: creative`. -5. **Build the Creative Corpus.** Follow `creative-corpus-playbook.md`: read what the Account - Context Brain already knows, pull only the creative content from Motion, and write one enriched - Markdown file per active creative under `/agent/brain/meta/creatives/`. Writing the files is the - index step for Knoweth; index the corpus-search source too if installed. -6. **Keep both current.** Account Context Brain on a monthly-plus-drift cadence; Creative Corpus on - daily and event-triggered maintenance. Log every refresh in `/agent/brain/meta/_changelog.md`. + validate, and flag what cannot be captured. Update the established indexed account-context file + for this workspace, or create this package's default if none exists yet, and index it in + `/agent/INDEX.md`. `[AUTO]` values stay proposals until a person signs off. +4. **Run Report Dashboard Setup.** Follow `report-dashboard-setup.md`: merge the report-dashboard + guard block into `/agent/user.md`, read this workspace's account-context file, inspect saved + Motion report metadata and existing app or routine registry entries when available, confirm the + team's reporting preferences with a person, then update the established indexed reporting/app + setup file for this workspace, or create this package's default if none exists yet, and index it + in `/agent/INDEX.md`. +5. **Reuse corpus-search when deliberate filterable search is needed.** If + `/agent/tools/corpus-search/` is not already present, fetch corpus-search from the public library + and install it per its own install-config; never clobber a customized copy. It supplements default + Brain retrieval for deliberate, filterable search. Register the resolved creative-context folder + as a source with `kind: creative`. +6. **Build the Creative Corpus.** Follow `creative-corpus-playbook.md`: read what the Account + Context Brain already knows, pull source-backed creative data from Motion only when it is needed + for durable saved context, and write or update creative-context Markdown files in the established + creative-context folder, or create this package's default if none exists yet. + Motion or the creative store remains authoritative for exact creative content and media. Refresh + the corpus-search source too if installed. +7. **Keep all three current.** Account Context Brain on a monthly-plus-drift cadence, Report + Dashboard Setup when reporting preferences or saved reports change, and Creative Corpus on daily + and event-triggered maintenance. Log every refresh in `/agent/brain/meta/_changelog.md`. ## Precedence -`/agent/brain/meta/account-context.md` is the sole source of account interpretation (how "best," -"winner," and cost-per are judged). It defers only to a metric the user names explicitly in the -current turn. The Creative Corpus reads the Account Context Brain and never re-derives it; when they -disagree, the Account Context Brain wins. +The established indexed account-context file for this workspace owns account interpretation (how +"best," "winner," and cost-per are judged). It defers only to a metric the user names explicitly in +the current turn. + +The established indexed reporting/app setup file for this workspace owns report and dashboard +packaging: standard views, saved-report trust, metric order, thresholds, date windows, taxonomy, +creative evidence requirements, visual expectations, generated-app quality standards, reusable +component roles, and delivery cadence. It defers to explicit current-turn instructions and to a +named saved Motion report unless the report-dashboard context says that report is not trusted or +should be adapted. + +The Creative Corpus reads the Account Context Brain for interpretation and the Report Dashboard +Setup for report-surface evidence requirements. It never re-derives either one. When the corpus and +the Account Context Brain disagree about account interpretation, the Account Context Brain wins. diff --git a/aligned-onboarding/account-context-brain.md b/aligned-onboarding/account-context-brain.md old mode 100755 new mode 100644 index 07adf3f..fede258 --- a/aligned-onboarding/account-context-brain.md +++ b/aligned-onboarding/account-context-brain.md @@ -7,9 +7,13 @@ the ad platform for this account by definition. Installing it stages these files into the customer brain. It does not self-run. Activation, below, is what makes Runneth run the fill-in and then live by the result. +This file owns account interpretation. It does not own report packaging, dashboard layout, delivery +cadence, saved-report trust rules, or visual standards. Those customer-specific reporting choices +belong in the workspace's reporting/app setup file from the companion Report Dashboard Setup. + Two things exist after activation: 1. A durable, workspace-scoped context file, written as a plain-language reference document (not - the worksheet), that Runneth writes and later reads as source of truth. + the worksheet), that Runneth writes and later reads as the source of account interpretation. 2. A small standing guard merged into `/agent/user.md` that forces Runneth to read that file before any performance work. @@ -27,15 +31,15 @@ Merge the block using the standard behavior-snippet convention (author it from **MERGE INSTRUCTIONS:** If a block with the sentinel `runneth:account-context-guard` already exists in `/agent/user.md`, replace it in place. Otherwise append it. Never duplicate it. Do not -edit anything outside the sentinels. +edit anything outside the sentinels. Replace `` with the established +account-context file for this workspace, or this package's default path if none exists yet. ``` Account context guard (workspace ): - Before any ad-performance work for this account (rankings, "best ads," CPA/ROAS reads, - winner or cut calls, creative performance judgments), read - /agent/brain/meta/account-context.md first. + winner or cut calls, creative performance judgments), read first. - If that file does not exist, or its required interpretation fields are not all [CONFIRMED], treat account interpretation as unknown. Offer to run the account-context fill-in flow, and do not answer @@ -73,9 +77,13 @@ This context describes one workspace. Record the scope before pulling anything: Confirmed answers do not live in this worksheet. Runneth writes them to a durable brain file so future turns read them. -- Create the account's `meta` folder in the brain if it does not exist. Save the filled result - to `/agent/brain/meta/account-context.md`. The per-creative files from the Creative Corpus live - in a `creatives` subfolder beside it (`/agent/brain/meta/creatives/`). +- Resolve the output path before writing. Use `/agent/INDEX.md`, an installed guard, or a + customer-edited setup file when one already names this workspace's account-context file. Otherwise + create this package's default in the account's `meta` folder. The per-creative files from the + Creative Corpus live beside the package default unless an established creative-context location + already exists. +- Do not save dashboard layout, report cadence, visual standards, or saved-report trust rules in + this file. Save those to the Report Dashboard Setup output during Report Dashboard Setup. **The saved file is a prose reference document, not the worksheet.** Capture and communication are two different jobs. The fields-and-statuses procedure below is how Runneth captures rigorously; the @@ -201,6 +209,11 @@ settings; treat workspace goal, preferred KPI, spend threshold, and attribution do not exist for this account. This file defers only to a metric the user names explicitly in the current turn. +When a report or dashboard also depends on customer-specific packaging choices, read the +workspace's reporting/app setup file after this file. That companion file can decide view shape, +metric order, saved-report trust, taxonomy, evidence, and cadence, but it never redefines the +account interpretation captured here. + --- # How Runneth fills this in @@ -656,6 +669,6 @@ back to the field that is wrong or missing. - Fields confirmed: `` / 9 - Flagged fields needing the customer: `` -- Written to: `/agent/brain/meta/account-context.md` +- Written to: `` - Indexed in `/agent/INDEX.md`: `` - Guard merged into `/agent/user.md`: `` diff --git a/aligned-onboarding/creative-corpus-playbook.md b/aligned-onboarding/creative-corpus-playbook.md old mode 100755 new mode 100644 index dc77df0..7360998 --- a/aligned-onboarding/creative-corpus-playbook.md +++ b/aligned-onboarding/creative-corpus-playbook.md @@ -1,20 +1,25 @@ # Meta Creative Corpus Playbook (Onboarding Package) -**How Runneth builds and maintains the per-creative attribute corpus for a Meta account, -using the Account Context Brain it already has.** +**How Runneth builds and maintains saved creative context for a Meta account, using the Account +Context Brain it already has.** -This is the creative-attributes part of the Meta onboarding package. It pairs with the -**Meta Account Context Brain** (`/agent/brain/meta/account-context.md`). +This is the creative-attributes part of the Meta onboarding package. It pairs with this workspace's +established Account Context Brain and, for report surfaces, the established Report Dashboard Setup. The one-line model: > The **Account Context Brain** tells Runneth **how to analyze** the account. The **Creative -> Corpus** gives Runneth **the attributes it needs to actually do the job**: one enriched record -> per active creative. +> Corpus** gives Runneth **the durable creative context it needs to actually do the job**. The Creative Corpus depends on the Account Context Brain for interpretation and does not -re-derive it. It only pulls from Motion what the Account Context Brain cannot already tell it: the -creative content itself. +re-derive it. It pulls enough source-backed creative data from Motion to create customer-facing +context, but Motion or the creative store remains authoritative for exact assets, previews, +transcripts, and current source-backed content. + +For reports and dashboards, the corpus supplies creative evidence: hooks, transcripts, previews, +tags, value props, and identity. Report Dashboard Setup decides how that evidence should appear on a +surface. Performance metrics stay live or saved-report-backed; they do not belong in the creative +files. --- @@ -22,37 +27,40 @@ creative content itself. The output is: -- **Individual creative Markdown files**, one per active creative, with identity, summary, hook, - value props, transcript, AI tags, and naming. -- An optional thin **tagging taxonomy** file, only if the Account Context Brain has a decoded - naming convention to - project. -- These files are automatically retrievable through **Knoweth**. There is no separate corpus - index to build. +- **Individual creative Markdown files** for creatives that need durable saved context, with + identity, summary, hook, value props, transcript notes, AI tags, and naming. +- An optional thin **tagging taxonomy** file, only if the Account Context Brain has a decoded naming + convention to project. +- These files are available through default Brain retrieval when they are saved to Brain. They are + not the canonical creative store and should not be created solely to mirror every source row. + +Report and dashboard builds use these files for stable creative context, not for current +performance. If the established reporting/app setup asks for playable videos, same-size creative +cards, transcript snippets, or specific evidence columns, satisfy those requirements from this +corpus where possible and show visible caveats when media or transcripts are missing. -## How retrieval works here (Knoweth first, corpus-search to supplement) +## How retrieval works here (default Brain retrieval first, corpus-search to supplement) -Runneth already has Knoweth, its local retrieval layer. Any Markdown written under -`/agent/brain/` in a readable lane is automatically chunked, indexed, and surfaced as -pre-context in future turns. Knoweth is the default and needs no setup: +Runneth can surface readable Markdown under `/agent/brain/` as saved context in future turns. Treat +default Brain retrieval as the ordinary path for saved creative context: -- Writing the file under `/agent/brain/meta/creatives/` is the index step. No manual `index`, - `embed`, or `refresh` needed for Knoweth to surface it. +- When a creative-context file is intentionally saved under the established creative-context folder + or this package's default, stable names, source IDs, tags, headings, and + `/agent/INDEX.md` entries make it findable for ordinary Brain recall. - To confirm a file is discoverable, reference its topic in a later turn, or list the folder. - Use `ContextConfig` only if these files need a specific lane (for example a workspace lane). -**corpus-search supplements Knoweth** for this package. It ships alongside (see the README for -install) and is the right tool when you need structured, filterable search over the creative files: -by `kind`, brand, field, or a specific intent across the whole corpus, rather than the automatic -pre-context Knoweth surfaces. Knoweth stays the default for everyday recall; reach for corpus-search -when you need to query the corpus deliberately. corpus-search requires its own index step (below); -Knoweth does not. +**corpus-search supplements default Brain retrieval** for this package. It ships alongside (see the +README for install) and is the right tool when you need structured, filterable search over the +creative files: by `kind`, brand, field, or a specific intent across the whole corpus. Default Brain +retrieval stays the ordinary path for everyday recall; reach for corpus-search when you need to +query the corpus deliberately. corpus-search requires its own index step below. --- ## Step 1 - Read what the Account Context Brain already knows (do not re-derive) -Open `/agent/brain/meta/account-context.md` first and pull these directly: +Open this workspace's established Account Context Brain first and pull these directly: - **Naming conventions** (Account Context Brain field 4): if it has a decoded pattern, use it to decode each creative's name. If it does not, just store the raw ad name as the attribute and move on. @@ -66,12 +74,17 @@ Open `/agent/brain/meta/account-context.md` first and pull these directly: If a needed field in the Account Context Brain is `[FLAGGED]` or missing, that is the only case where you gather it live, and you flag it the same way rather than guessing. +When the corpus is being built or refreshed to support a report/dashboard surface, also read the +established reporting/app setup if it exists. Use it only for report evidence requirements such as +card content, table columns, media behavior, and taxonomy. Do not let it override the Account +Context Brain's interpretation of what counts as best, winning, scaling, or ready to cut. + --- -## Step 2 - Pull the creative corpus from Motion +## Step 2 - Pull source creative context from Motion -This is the genuinely new data the Account Context Brain does not hold. Use the workspace and window from the Account Context Brain -(default `last_365d`). +This is the source-backed creative data the Account Context Brain does not hold. Use the workspace +and window from the Account Context Brain (default `last_365d`). ``` motion meta insights --date-range last_365d --include-glossary --include-metrics --include-transcript --workspace-id @@ -114,22 +127,20 @@ naming decode, skip the naming table entirely; the per-creative files simply carry the raw ad name. Do not build elaborate auto-tagging logic. Keep this file to the naming table (if any) and the -template. Save it at: -``` -/agent/brain/meta/creatives/_tagging-taxonomy.md -``` -The underscore keeps it at the top of the folder and signals it is a reference, not a creative. +template. Save it beside the creative-context files as `_tagging-taxonomy.md`. The underscore keeps +it at the top of the folder and signals it is a reference, not a creative. --- -## Step 4 - Generate individual creative MD files (the attributes) +## Step 4 - Generate saved creative-context MD files -One file per creative. +Write one file per creative only when that creative needs durable saved context. **File naming:** match the ad name exactly, `.md` extension, replace slashes or special characters with hyphens. -**Location:** `/agent/brain/meta/creatives/.md` +**Location:** the established creative-context folder for this workspace, or this package's default +if one does not exist yet. **Each file contains:** @@ -172,8 +183,8 @@ duration_s: