From e624dcb9f8b4946b6aa6c3e85e60d80162937919 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 30 Jun 2026 10:57:28 -0400 Subject: [PATCH 1/8] feat(account-setup): add visible account setup package --- account-setup/brain/account-setup/README.md | 42 ++++++++++ account-setup/instructions/account-setup.md | 91 +++++++++++++++++++++ account-setup/package.json | 26 ++++++ package-index.json | 22 ++++- scripts/validate-runneth-package-index.mjs | 6 +- 5 files changed, 182 insertions(+), 5 deletions(-) create mode 100644 account-setup/brain/account-setup/README.md create mode 100644 account-setup/instructions/account-setup.md create mode 100644 account-setup/package.json diff --git a/account-setup/brain/account-setup/README.md b/account-setup/brain/account-setup/README.md new file mode 100644 index 00000000..62de30dc --- /dev/null +++ b/account-setup/brain/account-setup/README.md @@ -0,0 +1,42 @@ +# Account Setup + +This folder is where Runneth keeps setup that should be visible, editable, and easy to inspect later. + +## What Lives Here + +- Motion imports for brand context, primary KPI, attribution windows, and spend thresholds +- Customer-taught corrections that should win over imported values +- Notes about which workspace, account, brand, market, or organization a setup file applies to +- Integration source guides when a connected source needs customer-specific instructions + +## How To Update It + +Tell Runneth what changed in plain language. + +Examples: + +- "For this workspace, primary KPI should be purchase ROAS." +- "When you use our attribution source, use this attribution window." +- "For this brand, ignore products with less than $1,000 spend." +- "For the asset source, this folder is our source of truth for approved assets." + +Runneth should update the visible setup file and preserve the latest imported Motion value unless you ask it to refresh from Motion. + +## Motion Imports + +Motion-imported setup lives in `motion-imports/`. + +Each import file has: + +- `Latest Import From Motion`: the last value pulled from Motion +- `Runneth Instructions`: corrections and customer-specific rules + +When those conflict, the `Runneth Instructions` section is the behavior Runneth should follow. + +## Integration Source Guides + +Integration capability docs answer what a connected tool can do. + +Account Setup answers how this customer wants Runneth to use that connected tool. + +If an integration needs customer-specific setup, create a clear source guide here and say exactly which account, workspace, brand, or folder it applies to. diff --git a/account-setup/instructions/account-setup.md b/account-setup/instructions/account-setup.md new file mode 100644 index 00000000..411849e3 --- /dev/null +++ b/account-setup/instructions/account-setup.md @@ -0,0 +1,91 @@ +# Account Setup + +Use Account Setup for customer-owned setup that should be visible in Agent Brain and easy for a user to change. + +## Purpose + +Account Setup is the customer's visible setup layer. It is not hidden runtime config. + +Use it for: + +- brand context +- primary KPI and attribution settings +- spend thresholds +- naming conventions +- customer-specific source instructions +- integration setup notes that describe how this customer wants Runneth to use a connected source + +## Main Folder + +Account Setup lives under: + +`/agent/brain/account-setup/` + +Motion imports live under: + +`/agent/brain/account-setup/motion-imports/` + +Each setup file should clearly say what it applies to: organization, workspace, account, brand, market, data source, folder, or user scope. + +## Motion Imports + +Motion imports have two important sections: + +- `Latest Import From Motion`: the most recent value pulled from Motion +- `Runneth Instructions`: customer-taught corrections and rules + +Use the Motion accessors for ordinary reads: + +- `motion brand-context --data-query "..."` +- `motion workspace-goal` +- `motion spend-threshold` + +Use `--refresh-from-motion` only when the user asks to refresh, re-import, sync with Motion, or compare against the current Motion UI value. + +Refreshing should update `Latest Import From Motion` and preserve `Runneth Instructions`. + +## Conflict Rule + +When `Latest Import From Motion` conflicts with `Runneth Instructions`, follow `Runneth Instructions` unless the user explicitly chooses the Motion value. + +If the conflict matters to the answer, say it plainly: + +`Motion currently says X, but your Runneth instructions say Y. I am using Y.` + +If the user wants Motion itself changed, explain whether Runneth has a write path for that Motion setting. If not, save the Runneth-side instruction here and say that it does not change the Motion UI. + +## Integration Source Guides + +Keep the split simple: + +- Integration capability docs describe what the tool can do. +- Account Setup source guides describe how this customer wants Runneth to use that tool. + +Do not create integration setup files by default. + +Create a source guide only when the customer connects that source or gives instructions for it. + +Use clear names like: + +- `integrations/ad-platform.md` +- `integrations/asset-library.md` +- `integrations/data-warehouse.md` + +Each source guide should answer: + +- What account, workspace, folder, table, or brand does this apply to? +- What should Runneth use this source for? +- What should Runneth avoid using it for? +- What customer-specific rules matter? +- What is still an open question? + +## Updating Setup + +When a user asks to save or change setup: + +1. Resolve the scope first. +2. Read the existing Account Setup file. +3. Put customer rules in `Runneth Instructions`. +4. Preserve Motion import JSON unless the user asked to refresh from Motion. +5. Ask one short confirmation before overwriting a conflicting instruction. +6. Reread the file after editing and make sure any Motion import JSON block is still valid. diff --git a/account-setup/package.json b/account-setup/package.json new file mode 100644 index 00000000..88841b3a --- /dev/null +++ b/account-setup/package.json @@ -0,0 +1,26 @@ +{ + "schemaVersion": 1, + "id": "account-setup", + "name": "Account Setup", + "version": "0.1.0", + "description": "Visible Account Setup instructions for customer-owned Runneth configuration.", + "updatePolicy": "manual", + "uninstallPolicy": "allowed", + "resources": [ + { + "id": "account-setup-readme", + "type": "file", + "sourcePath": "brain/account-setup/README.md", + "target": { + "root": "agent_brain", + "path": "account-setup/README.md" + }, + "executable": false + }, + { + "id": "account-setup-instructions", + "type": "package_instruction", + "sourcePath": "instructions/account-setup.md" + } + ] +} diff --git a/package-index.json b/package-index.json index ddfb614d..d4725b31 100644 --- a/package-index.json +++ b/package-index.json @@ -1,5 +1,23 @@ { "schemaVersion": 1, - "indexRevision": "initial-empty", - "packages": [] + "indexRevision": "account-setup-0.1.0", + "packages": [ + { + "id": "account-setup", + "name": "Account Setup", + "description": "Visible Account Setup instructions for customer-owned Runneth configuration.", + "version": "0.1.0", + "packageManagerVersion": 1, + "categories": ["baseline"], + "source": { + "type": "github", + "owner": "Motion-Creative", + "repo": "runneth-apps", + "path": "account-setup", + "ref": "main" + }, + "updatePolicy": "manual", + "uninstallPolicy": "allowed" + } + ] } diff --git a/scripts/validate-runneth-package-index.mjs b/scripts/validate-runneth-package-index.mjs index eef87b71..e751ae72 100644 --- a/scripts/validate-runneth-package-index.mjs +++ b/scripts/validate-runneth-package-index.mjs @@ -205,7 +205,7 @@ const validatePackageIndex = (index) => { } const localManifestPathForSource = (source) => { - return `${source.path}/runneth-package.json` + return `${source.path}/package.json` } const assertPathHasNoSymlinkSegments = (relativePath, label) => { @@ -272,7 +272,7 @@ const assertManifestMatchesIndexEntry = (entry, manifest, manifestPath) => { entry.uninstallPolicy, `${entry.id}: manifest uninstallPolicy does not match index uninstallPolicy`, ) - assertManifestResourceFilesExist(manifest, manifestPath.replace(/\/runneth-package\.json$/, '')) + assertManifestResourceFilesExist(manifest, manifestPath.replace(/\/package\.json$/, '')) } const getIndexedPackageById = (index) => @@ -364,7 +364,7 @@ test('package-index.json matches the package index contract', () => { validatePackageIndex(readJSON(INDEX_PATH)) }) -test('indexed packages match their runneth-package.json manifests', () => { +test('indexed packages match their package.json manifests', () => { const index = readJSON(INDEX_PATH) for (const entry of index.packages) { const manifestPath = localManifestPathForSource(entry.source) From 3631b6955fb86a38be2416b8d41c7aabdf5c0af8 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 30 Jun 2026 11:26:57 -0400 Subject: [PATCH 2/8] test(account-setup): enforce unique package resource ids --- scripts/validate-runneth-package-index.mjs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/scripts/validate-runneth-package-index.mjs b/scripts/validate-runneth-package-index.mjs index e751ae72..d53fd6d1 100644 --- a/scripts/validate-runneth-package-index.mjs +++ b/scripts/validate-runneth-package-index.mjs @@ -152,8 +152,14 @@ const assertPackageManifest = (manifest, label) => { `${label}.uninstallPolicy: invalid`, ) assert.ok(Array.isArray(manifest.resources), `${label}.resources: must be array`) + const resourceIds = new Set() manifest.resources.forEach((resource, index) => { assertPackageResource(resource, `${label}.resources[${index}]`) + assert.ok( + !resourceIds.has(resource.id), + `${label}.resources: duplicate resource id ${resource.id}`, + ) + resourceIds.add(resource.id) }) } From b9d403f5a2a82538989e80231630c040de52be24 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Fri, 24 Jul 2026 20:26:21 -0400 Subject: [PATCH 3/8] feat(account-setup): seed report dashboard guide --- account-setup/brain/account-setup/README.md | 10 ++ .../account-setup/report-dashboard-guide.md | 104 ++++++++++++++++++ account-setup/instructions/account-setup.md | 25 +++++ account-setup/package.json | 14 ++- package-index.json | 6 +- 5 files changed, 154 insertions(+), 5 deletions(-) create mode 100644 account-setup/brain/account-setup/report-dashboard-guide.md diff --git a/account-setup/brain/account-setup/README.md b/account-setup/brain/account-setup/README.md index 62de30dc..079aad35 100644 --- a/account-setup/brain/account-setup/README.md +++ b/account-setup/brain/account-setup/README.md @@ -5,6 +5,7 @@ This folder is where Runneth keeps setup that should be visible, editable, and e ## What Lives Here - Motion imports for brand context, primary KPI, attribution windows, and spend thresholds +- Report and dashboard defaults in `report-dashboard-guide.md` - Customer-taught corrections that should win over imported values - Notes about which workspace, account, brand, market, or organization a setup file applies to - Integration source guides when a connected source needs customer-specific instructions @@ -19,6 +20,8 @@ Examples: - "When you use our attribution source, use this attribution window." - "For this brand, ignore products with less than $1,000 spend." - "For the asset source, this folder is our source of truth for approved assets." +- "For reporting dashboards, use Northbeam new-customer ROAS as the source of truth." +- "Our weekly dashboard should show top ads, product comparison, and testing ads that could graduate." Runneth should update the visible setup file and preserve the latest imported Motion value unless you ask it to refresh from Motion. @@ -33,6 +36,13 @@ Each import file has: When those conflict, the `Runneth Instructions` section is the behavior Runneth should follow. +## Report Dashboard Guide + +Report and dashboard setup lives in `report-dashboard-guide.md`. + +Use it to teach Runneth the standard report views, source-of-truth rules, metric definitions, date +windows, taxonomy, visual expectations, refresh cadence, and validation questions for this account. + ## Integration Source Guides Integration capability docs answer what a connected tool can do. diff --git a/account-setup/brain/account-setup/report-dashboard-guide.md b/account-setup/brain/account-setup/report-dashboard-guide.md new file mode 100644 index 00000000..0dc8b249 --- /dev/null +++ b/account-setup/brain/account-setup/report-dashboard-guide.md @@ -0,0 +1,104 @@ +# Report Dashboard Guide + +This file captures how this customer wants Runneth to build report and dashboard apps. Edit it when the +team teaches Runneth a reporting preference, source-of-truth rule, metric definition, visual standard, +or recurring dashboard shape. + +Use this guide for ad performance reports, creative dashboards, weekly decks, launch trackers, and +team readouts. Customer-specific rules here should win over generic defaults unless the user explicitly +chooses a different setup for one report. + +## Scope + +- Organization: +- Workspace or account: +- Brand, market, or product scope: +- Primary audience for reports: + +## Standard Views + +| View | Question it should answer | Default sections | Customer-specific notes | +| --- | --- | --- | --- | +| Top ads | What should we make more of? | Top creative cards, ranked table, scaling notes, caveats | | +| Topline metrics | How is the account doing? | KPI snapshot, previous-period comparison, drivers, risks | | +| Comparative analysis | Which campaign, product, creator, concept, or tag is working? | Grouped comparison, representative creatives, interpretation | | +| Launch analysis | What happened to new or testing ads? | New launch cohort, product breakdown, hit/scaling/graduation labels | | + +## Source Of Truth + +- Saved Motion reports to reuse: +- Platform sources to use: +- Attribution source for performance decisions: +- Attribution window rules: +- Sources Runneth should avoid for reporting: +- When Motion and this guide conflict: + +## Metrics And Definitions + +| Metric or label | Definition | Direction | Qualification rule | +| --- | --- | --- | --- | +| Primary KPI | | | | +| Spend | | Higher means more scale, not automatically better | | +| CPA or cost per result | | Lower is better | Require enough spend before calling a winner | +| ROAS or revenue efficiency | | Higher is better | | +| Thumbstop rate | | Higher is better | | +| Hold rate | | Higher is better | | +| Outbound CTR | | Higher is better | | +| Hit | | | | +| Scaling or graduated | | | | +| Cut or loser | | | | + +## Date Windows + +- Default dashboard windows: +- Weekly comparison window: +- Long-lookback window: +- Custom range rules: +- Timezone: + +## Taxonomy And Naming + +- Product or SKU naming rules: +- Campaign naming rules: +- Creator or influencer naming rules: +- Funnel or audience naming rules: +- AI tag categories to trust: +- Taxonomy Runneth should ask about instead of inferring: + +## Creative Evidence + +- Show playable videos when video URLs are available: +- Use still previews when playable video is not available: +- Keep creative cards the same size: +- Required metrics on creative cards: +- Required columns in comparison tables: +- Drilldowns or links users expect: + +## Visual Standards + +- Match Motion-style reporting unless the user gives a specific template: +- Keep the report dense enough for review, not a marketing page: +- Do not hide source, date, attribution, grouping, or threshold caveats: +- Customer brand or presentation preferences: + +## Refresh And Delivery + +- Recurring cadence: +- Delivery destination: +- Saved phrase users can say to regenerate: +- Files, apps, or dashboards users return to: +- Approval or review step before sending: + +## Validation Questions + +Use these to confirm Runneth understands the account before treating a dashboard as validated. + +1. What are the five fundamental business questions this team asks every week? +2. Which saved Motion reports or existing spreadsheets are already trusted? +3. Which metrics decide scale, cut, or creative iteration? +4. Which taxonomy does the team use for products, campaigns, creators, and tests? +5. What dashboard or weekly readout would prove the connected sources and context are working? + +## Open Questions + +- TBD diff --git a/account-setup/instructions/account-setup.md b/account-setup/instructions/account-setup.md index 411849e3..92fdcb64 100644 --- a/account-setup/instructions/account-setup.md +++ b/account-setup/instructions/account-setup.md @@ -12,6 +12,7 @@ Use it for: - primary KPI and attribution settings - spend thresholds - naming conventions +- report and dashboard app-building defaults - customer-specific source instructions - integration setup notes that describe how this customer wants Runneth to use a connected source @@ -27,6 +28,30 @@ Motion imports live under: Each setup file should clearly say what it applies to: organization, workspace, account, brand, market, data source, folder, or user scope. +## Report Dashboard Guide + +Report and dashboard app-building defaults live at: + +`/agent/brain/account-setup/report-dashboard-guide.md` + +Read this guide before building or updating ad performance reports, creative dashboards, weekly deck +sources, launch trackers, or recurring reporting apps. Use it for the customer's standard views, +source-of-truth choices, KPI definitions, date windows, taxonomy, visual standards, refresh cadence, +and validation questions. + +Update this guide when the user teaches Runneth: + +- which report views matter to the team +- which saved Motion reports or connected sources are trusted +- what metrics, thresholds, or attribution rules decide scale, cut, hit, or graduation labels +- how products, campaigns, creators, funnels, or tests are named +- what the dashboard must show visually, such as playable videos, same-size cards, and table columns +- how often a report should refresh and where it should be delivered + +Do not create hidden app-building config when this guide is the right customer-owned setup surface. +If the guide is blank and the missing preference changes the report's meaning, ask one focused +question or write the open question into the guide after building the best available first version. + ## Motion Imports Motion imports have two important sections: diff --git a/account-setup/package.json b/account-setup/package.json index 88841b3a..2a5515e9 100644 --- a/account-setup/package.json +++ b/account-setup/package.json @@ -2,8 +2,8 @@ "schemaVersion": 1, "id": "account-setup", "name": "Account Setup", - "version": "0.1.0", - "description": "Visible Account Setup instructions for customer-owned Runneth configuration.", + "version": "0.2.0", + "description": "Visible Account Setup instructions and report dashboard defaults for customer-owned Runneth configuration.", "updatePolicy": "manual", "uninstallPolicy": "allowed", "resources": [ @@ -17,6 +17,16 @@ }, "executable": false }, + { + "id": "account-setup-report-dashboard-guide", + "type": "file", + "sourcePath": "brain/account-setup/report-dashboard-guide.md", + "target": { + "root": "agent_brain", + "path": "account-setup/report-dashboard-guide.md" + }, + "executable": false + }, { "id": "account-setup-instructions", "type": "package_instruction", diff --git a/package-index.json b/package-index.json index d4725b31..eecda5b1 100644 --- a/package-index.json +++ b/package-index.json @@ -1,12 +1,12 @@ { "schemaVersion": 1, - "indexRevision": "account-setup-0.1.0", + "indexRevision": "account-setup-0.2.0", "packages": [ { "id": "account-setup", "name": "Account Setup", - "description": "Visible Account Setup instructions for customer-owned Runneth configuration.", - "version": "0.1.0", + "description": "Visible Account Setup instructions and report dashboard defaults for customer-owned Runneth configuration.", + "version": "0.2.0", "packageManagerVersion": 1, "categories": ["baseline"], "source": { From 180e845dc6080e8697ea59c000102219c06b1f17 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Fri, 24 Jul 2026 22:52:45 -0400 Subject: [PATCH 4/8] feat(aligned-onboarding): seed report dashboard setup --- account-setup/brain/account-setup/README.md | 52 -- .../account-setup/report-dashboard-guide.md | 104 --- account-setup/instructions/account-setup.md | 116 --- account-setup/package.json | 36 - aligned-onboarding/README.md | 170 +++++ aligned-onboarding/SKILL.md | 106 +++ aligned-onboarding/account-context-brain.md | 674 ++++++++++++++++++ .../creative-corpus-playbook.md | 335 +++++++++ aligned-onboarding/install-config.json | 72 ++ aligned-onboarding/marketing.md | 23 + .../motion-cli-data-query-guide.md | 225 ++++++ aligned-onboarding/package.json | 71 ++ aligned-onboarding/report-dashboard-setup.md | 355 +++++++++ aligned-onboarding/use-case.json | 8 + package-index.json | 14 +- 15 files changed, 2046 insertions(+), 315 deletions(-) delete mode 100644 account-setup/brain/account-setup/README.md delete mode 100644 account-setup/brain/account-setup/report-dashboard-guide.md delete mode 100644 account-setup/instructions/account-setup.md delete mode 100644 account-setup/package.json create mode 100644 aligned-onboarding/README.md create mode 100644 aligned-onboarding/SKILL.md create mode 100644 aligned-onboarding/account-context-brain.md create mode 100644 aligned-onboarding/creative-corpus-playbook.md create mode 100644 aligned-onboarding/install-config.json create mode 100644 aligned-onboarding/marketing.md create mode 100644 aligned-onboarding/motion-cli-data-query-guide.md create mode 100644 aligned-onboarding/package.json create mode 100644 aligned-onboarding/report-dashboard-setup.md create mode 100644 aligned-onboarding/use-case.json diff --git a/account-setup/brain/account-setup/README.md b/account-setup/brain/account-setup/README.md deleted file mode 100644 index 079aad35..00000000 --- a/account-setup/brain/account-setup/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Account Setup - -This folder is where Runneth keeps setup that should be visible, editable, and easy to inspect later. - -## What Lives Here - -- Motion imports for brand context, primary KPI, attribution windows, and spend thresholds -- Report and dashboard defaults in `report-dashboard-guide.md` -- Customer-taught corrections that should win over imported values -- Notes about which workspace, account, brand, market, or organization a setup file applies to -- Integration source guides when a connected source needs customer-specific instructions - -## How To Update It - -Tell Runneth what changed in plain language. - -Examples: - -- "For this workspace, primary KPI should be purchase ROAS." -- "When you use our attribution source, use this attribution window." -- "For this brand, ignore products with less than $1,000 spend." -- "For the asset source, this folder is our source of truth for approved assets." -- "For reporting dashboards, use Northbeam new-customer ROAS as the source of truth." -- "Our weekly dashboard should show top ads, product comparison, and testing ads that could graduate." - -Runneth should update the visible setup file and preserve the latest imported Motion value unless you ask it to refresh from Motion. - -## Motion Imports - -Motion-imported setup lives in `motion-imports/`. - -Each import file has: - -- `Latest Import From Motion`: the last value pulled from Motion -- `Runneth Instructions`: corrections and customer-specific rules - -When those conflict, the `Runneth Instructions` section is the behavior Runneth should follow. - -## Report Dashboard Guide - -Report and dashboard setup lives in `report-dashboard-guide.md`. - -Use it to teach Runneth the standard report views, source-of-truth rules, metric definitions, date -windows, taxonomy, visual expectations, refresh cadence, and validation questions for this account. - -## Integration Source Guides - -Integration capability docs answer what a connected tool can do. - -Account Setup answers how this customer wants Runneth to use that connected tool. - -If an integration needs customer-specific setup, create a clear source guide here and say exactly which account, workspace, brand, or folder it applies to. diff --git a/account-setup/brain/account-setup/report-dashboard-guide.md b/account-setup/brain/account-setup/report-dashboard-guide.md deleted file mode 100644 index 0dc8b249..00000000 --- a/account-setup/brain/account-setup/report-dashboard-guide.md +++ /dev/null @@ -1,104 +0,0 @@ -# Report Dashboard Guide - -This file captures how this customer wants Runneth to build report and dashboard apps. Edit it when the -team teaches Runneth a reporting preference, source-of-truth rule, metric definition, visual standard, -or recurring dashboard shape. - -Use this guide for ad performance reports, creative dashboards, weekly decks, launch trackers, and -team readouts. Customer-specific rules here should win over generic defaults unless the user explicitly -chooses a different setup for one report. - -## Scope - -- Organization: -- Workspace or account: -- Brand, market, or product scope: -- Primary audience for reports: - -## Standard Views - -| View | Question it should answer | Default sections | Customer-specific notes | -| --- | --- | --- | --- | -| Top ads | What should we make more of? | Top creative cards, ranked table, scaling notes, caveats | | -| Topline metrics | How is the account doing? | KPI snapshot, previous-period comparison, drivers, risks | | -| Comparative analysis | Which campaign, product, creator, concept, or tag is working? | Grouped comparison, representative creatives, interpretation | | -| Launch analysis | What happened to new or testing ads? | New launch cohort, product breakdown, hit/scaling/graduation labels | | - -## Source Of Truth - -- Saved Motion reports to reuse: -- Platform sources to use: -- Attribution source for performance decisions: -- Attribution window rules: -- Sources Runneth should avoid for reporting: -- When Motion and this guide conflict: - -## Metrics And Definitions - -| Metric or label | Definition | Direction | Qualification rule | -| --- | --- | --- | --- | -| Primary KPI | | | | -| Spend | | Higher means more scale, not automatically better | | -| CPA or cost per result | | Lower is better | Require enough spend before calling a winner | -| ROAS or revenue efficiency | | Higher is better | | -| Thumbstop rate | | Higher is better | | -| Hold rate | | Higher is better | | -| Outbound CTR | | Higher is better | | -| Hit | | | | -| Scaling or graduated | | | | -| Cut or loser | | | | - -## Date Windows - -- Default dashboard windows: -- Weekly comparison window: -- Long-lookback window: -- Custom range rules: -- Timezone: - -## Taxonomy And Naming - -- Product or SKU naming rules: -- Campaign naming rules: -- Creator or influencer naming rules: -- Funnel or audience naming rules: -- AI tag categories to trust: -- Taxonomy Runneth should ask about instead of inferring: - -## Creative Evidence - -- Show playable videos when video URLs are available: -- Use still previews when playable video is not available: -- Keep creative cards the same size: -- Required metrics on creative cards: -- Required columns in comparison tables: -- Drilldowns or links users expect: - -## Visual Standards - -- Match Motion-style reporting unless the user gives a specific template: -- Keep the report dense enough for review, not a marketing page: -- Do not hide source, date, attribution, grouping, or threshold caveats: -- Customer brand or presentation preferences: - -## Refresh And Delivery - -- Recurring cadence: -- Delivery destination: -- Saved phrase users can say to regenerate: -- Files, apps, or dashboards users return to: -- Approval or review step before sending: - -## Validation Questions - -Use these to confirm Runneth understands the account before treating a dashboard as validated. - -1. What are the five fundamental business questions this team asks every week? -2. Which saved Motion reports or existing spreadsheets are already trusted? -3. Which metrics decide scale, cut, or creative iteration? -4. Which taxonomy does the team use for products, campaigns, creators, and tests? -5. What dashboard or weekly readout would prove the connected sources and context are working? - -## Open Questions - -- TBD diff --git a/account-setup/instructions/account-setup.md b/account-setup/instructions/account-setup.md deleted file mode 100644 index 92fdcb64..00000000 --- a/account-setup/instructions/account-setup.md +++ /dev/null @@ -1,116 +0,0 @@ -# Account Setup - -Use Account Setup for customer-owned setup that should be visible in Agent Brain and easy for a user to change. - -## Purpose - -Account Setup is the customer's visible setup layer. It is not hidden runtime config. - -Use it for: - -- brand context -- primary KPI and attribution settings -- spend thresholds -- naming conventions -- report and dashboard app-building defaults -- customer-specific source instructions -- integration setup notes that describe how this customer wants Runneth to use a connected source - -## Main Folder - -Account Setup lives under: - -`/agent/brain/account-setup/` - -Motion imports live under: - -`/agent/brain/account-setup/motion-imports/` - -Each setup file should clearly say what it applies to: organization, workspace, account, brand, market, data source, folder, or user scope. - -## Report Dashboard Guide - -Report and dashboard app-building defaults live at: - -`/agent/brain/account-setup/report-dashboard-guide.md` - -Read this guide before building or updating ad performance reports, creative dashboards, weekly deck -sources, launch trackers, or recurring reporting apps. Use it for the customer's standard views, -source-of-truth choices, KPI definitions, date windows, taxonomy, visual standards, refresh cadence, -and validation questions. - -Update this guide when the user teaches Runneth: - -- which report views matter to the team -- which saved Motion reports or connected sources are trusted -- what metrics, thresholds, or attribution rules decide scale, cut, hit, or graduation labels -- how products, campaigns, creators, funnels, or tests are named -- what the dashboard must show visually, such as playable videos, same-size cards, and table columns -- how often a report should refresh and where it should be delivered - -Do not create hidden app-building config when this guide is the right customer-owned setup surface. -If the guide is blank and the missing preference changes the report's meaning, ask one focused -question or write the open question into the guide after building the best available first version. - -## Motion Imports - -Motion imports have two important sections: - -- `Latest Import From Motion`: the most recent value pulled from Motion -- `Runneth Instructions`: customer-taught corrections and rules - -Use the Motion accessors for ordinary reads: - -- `motion brand-context --data-query "..."` -- `motion workspace-goal` -- `motion spend-threshold` - -Use `--refresh-from-motion` only when the user asks to refresh, re-import, sync with Motion, or compare against the current Motion UI value. - -Refreshing should update `Latest Import From Motion` and preserve `Runneth Instructions`. - -## Conflict Rule - -When `Latest Import From Motion` conflicts with `Runneth Instructions`, follow `Runneth Instructions` unless the user explicitly chooses the Motion value. - -If the conflict matters to the answer, say it plainly: - -`Motion currently says X, but your Runneth instructions say Y. I am using Y.` - -If the user wants Motion itself changed, explain whether Runneth has a write path for that Motion setting. If not, save the Runneth-side instruction here and say that it does not change the Motion UI. - -## Integration Source Guides - -Keep the split simple: - -- Integration capability docs describe what the tool can do. -- Account Setup source guides describe how this customer wants Runneth to use that tool. - -Do not create integration setup files by default. - -Create a source guide only when the customer connects that source or gives instructions for it. - -Use clear names like: - -- `integrations/ad-platform.md` -- `integrations/asset-library.md` -- `integrations/data-warehouse.md` - -Each source guide should answer: - -- What account, workspace, folder, table, or brand does this apply to? -- What should Runneth use this source for? -- What should Runneth avoid using it for? -- What customer-specific rules matter? -- What is still an open question? - -## Updating Setup - -When a user asks to save or change setup: - -1. Resolve the scope first. -2. Read the existing Account Setup file. -3. Put customer rules in `Runneth Instructions`. -4. Preserve Motion import JSON unless the user asked to refresh from Motion. -5. Ask one short confirmation before overwriting a conflicting instruction. -6. Reread the file after editing and make sure any Motion import JSON block is still valid. diff --git a/account-setup/package.json b/account-setup/package.json deleted file mode 100644 index 2a5515e9..00000000 --- a/account-setup/package.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "schemaVersion": 1, - "id": "account-setup", - "name": "Account Setup", - "version": "0.2.0", - "description": "Visible Account Setup instructions and report dashboard defaults for customer-owned Runneth configuration.", - "updatePolicy": "manual", - "uninstallPolicy": "allowed", - "resources": [ - { - "id": "account-setup-readme", - "type": "file", - "sourcePath": "brain/account-setup/README.md", - "target": { - "root": "agent_brain", - "path": "account-setup/README.md" - }, - "executable": false - }, - { - "id": "account-setup-report-dashboard-guide", - "type": "file", - "sourcePath": "brain/account-setup/report-dashboard-guide.md", - "target": { - "root": "agent_brain", - "path": "account-setup/report-dashboard-guide.md" - }, - "executable": false - }, - { - "id": "account-setup-instructions", - "type": "package_instruction", - "sourcePath": "instructions/account-setup.md" - } - ] -} diff --git a/aligned-onboarding/README.md b/aligned-onboarding/README.md new file mode 100644 index 00000000..636165f3 --- /dev/null +++ b/aligned-onboarding/README.md @@ -0,0 +1,170 @@ +# Meta Onboarding Package: Overview + +This package teaches Runneth how to understand and work inside a customer's Meta ad account. It +ships as three parts that live side by side. Install and run them in order. + +The three parts: + +- **Account Context Brain** - how Runneth should analyze this account. +- **Report Dashboard Setup** - how this customer wants report, dashboard, and app readouts built. +- **Creative Corpus** - the per-creative attributes Runneth analyzes. + +The one-line model: + +> **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 +> per-creative attributes it needs to actually do the job.** + +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 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 holds only what Runneth generates from +running the package: the filled account context, the report/dashboard setup context, and the +per-creative files. + +--- + +## 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.** 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 belongs in the Brain.** Report/dashboard preferences, saved-report trust rules, + taxonomy, delivery cadence, and visual standards are customer-owned setup. They should be visible + and editable in `/agent/brain/meta/report-dashboard-context.md`, not hidden in runtime config. +- **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 three parts + +### Account Context Brain +File: `account-context-brain.md` + +- **Job:** capture how the team interprets the account, so rankings, "best ad" calls, and insights + match how they actually think. Nine required context fields (sources of truth, conversion + hierarchy, metric gotchas, naming, attribution, account structure, funnel map, creative metrics, + 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) +- **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, + 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:** `/agent/brain/meta/report-dashboard-context.md` +- **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. +- **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). Knoweth picks up the + files automatically; corpus-search can be installed as the optional filterable supplement. +- **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. +- **Maintenance:** daily and event-triggered updates as creatives change. + +--- + +### Motion CLI Data-Query Guide (supporting reference) +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. 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 (optional companion tool) +Source: `Motion-Creative/runneth-apps/corpus-search` + +The package reuses **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. + +**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, +with customer reviews and voice-of-customer as primary use cases, alongside transcripts, notes, and +similar. Everything shares one index, kept separate by the `kind` tag (`creative`, `review`, +`voice-of-customer`, `transcript`, and so on), so you can search within a type or across all of them. + +- **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 + 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` + where it applies) so corpus-search can filter and dedupe on it. + +--- + +## Install and run order + +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. **Run Report Dashboard Setup.** Read `/agent/brain/meta/account-context.md`, capture the team's + reporting preferences, write `/agent/brain/meta/report-dashboard-context.md`, and index it in + `/agent/INDEX.md`. +5. **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. +6. **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 and the Report Dashboard Setup when report surfaces need creative evidence + rules. Then index the folder into corpus-search 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 the corpus-search index on that same cadence. + +--- + +## How the three parts relate + +- 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. +- The Account Context Brain's read-before-performance guard is what forces the lens to be loaded + before any performance work. Report Dashboard Setup adds the read-before-reporting preferences. + The Creative Corpus is surfaced automatically through Knoweth 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 new file mode 100644 index 00000000..ca6ae560 --- /dev/null +++ b/aligned-onboarding/SKILL.md @@ -0,0 +1,106 @@ +--- +name: aligned-onboarding +description: > + Teaches Runneth how a customer reads their Meta ad account, captures customer-specific report and + dashboard setup, then builds and maintains one enriched record per active creative. 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 (the per-creative attributes). + 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 and /agent/brain/meta/account-context.md does not exist yet. +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, how report/dashboard surfaces should be packaged, and how to build the per-creative corpus." +--- + +# Aligned Onboarding + +Teaches Runneth how this customer reads their Meta ad account, captures how the team wants reports +and dashboards packaged, then builds the per-creative corpus off that lens. It ships as three parts +that do different jobs and persist to different places. + +The one-line model: + +> 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 **the attributes it needs to actually do the job**. + +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: + +- 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` + +## Scope rules (apply throughout) + +- **Meta only.** Never pull or reason about 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 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 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 belongs in the Brain.** Report/dashboard preferences are visible setup in + `/agent/brain/meta/report-dashboard-context.md`, not hidden runtime config or app code. +- **Onboarding pull window is `last_365d`** for the fill-in only, so onboarding sees enough history. + +## Run order + +1. **Resolve the workspace.** Confirm the target `` (the Meta account being onboarded). + Use `motion workspaces` if it is not already known. +2. **Activate the guard.** Merge the account-context guard block from `account-context-brain.md` + into /agent/user.md using the sentinel convention (`runneth:account-context-guard`), + substituting the real ``. Author it from `building-integrations/behavior-snippet.md`. + 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. **Run Report Dashboard Setup.** Follow `report-dashboard-setup.md`: merge the report-dashboard + guard block into `/agent/user.md`, read `/agent/brain/meta/account-context.md`, inspect saved + Motion report metadata and existing app or routine registry entries when available, confirm the + team's reporting preferences with a person, then write the prose result to + `/agent/brain/meta/report-dashboard-context.md` and index it in `/agent/INDEX.md`. +5. **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`. +6. **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. +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. + +`/agent/brain/meta/report-dashboard-context.md` is the source for report and dashboard packaging: +standard views, saved-report trust, metric order, thresholds, date windows, taxonomy, creative +evidence requirements, visual expectations, 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 new file mode 100644 index 00000000..304e05d9 --- /dev/null +++ b/aligned-onboarding/account-context-brain.md @@ -0,0 +1,674 @@ +# Meta Account Context: Brain Onboarding Package + +This package teaches Runneth how a customer understands their Meta ad account, so its queries, +rankings, and insights match how the team actually thinks about the data. This package is +Meta-only: it never looks for or pulls other ad platforms (TikTok, LinkedIn, YouTube). Meta is +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 companion Report Dashboard Setup file at +`/agent/brain/meta/report-dashboard-context.md`. + +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. +2. A small standing guard merged into `/agent/user.md` that forces Runneth to read that file + before any performance work. + +--- + +# How this package operates + +## 1. Activation (what triggers it, and when) + +Installing only stages files. The package does not self-run. To activate it, merge the guard +block below into `/agent/user.md`, then run the fill-in procedure. + +Merge the block using the standard behavior-snippet convention (author it from +`building-integrations/behavior-snippet.md`). It is sentinel-wrapped so it is idempotent. + +**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. + +``` + +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. +- 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 + performance questions on guesses. +- Runneth may auto-fill and mark [AUTO] fields on its own immediately. It must hold [CONFIRMED] + fields for a person and never promote [AUTO] to [CONFIRMED] without human sign-off. +- Precedence: this file is the sole source of account interpretation (how "best," "winner," and + cost-per are judged). Do not read or defer to Motion workspace settings (workspace goal, + preferred KPI, spend threshold, attribution config); treat them as if they do not exist for + this account. Defer only to a metric the user names explicitly in the current turn. + +``` + +## 2. Workspace scope + +This context describes one workspace. Record the scope before pulling anything: + +- Target workspace: `` (ad account: ``) +- Date window for filling in this package: the `[AUTO]` pulls used to complete these fields + default to `last_365d` (the last 365 days of creatives), so onboarding sees enough history to + interpret the account. This window governs the fill-in pulls only. It is not a standing default + for later performance queries; those still use their own requested window, or the normal + defaults, unless the user asks otherwise. +- Every `[AUTO]` pull passes `--workspace-id ` explicitly. Customer brains are + usually one workspace, but multi-workspace orgs are real and the pulls must name the account. +- Platform scope: Meta only. Never look for, pull, or reason about other ad platforms (TikTok, + LinkedIn, YouTube) in this package. +- Settings scope: pretend Motion workspace configuration settings do not exist. Do not read or + rely on workspace goal, preferred KPI, spend threshold, or attribution-window config. Every + value comes from auto-pulled Meta ad data, this worksheet, and customer confirmation. This + file is the only source of account interpretation. + +## 3. Where the filled result lives (persistence) + +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/`). +- Do not save dashboard layout, report cadence, visual standards, or saved-report trust rules in + this file. Save those to `/agent/brain/meta/report-dashboard-context.md` 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 +saved file is how it communicates. Write the saved file the way a sharp analyst would explain this +account to a new teammate: interpretation baked into sentences, the decision stated, readable in +about 30 seconds. State conclusions, not statuses. Do not carry `[CONFIRMED]`/`[AUTO]`/`[FLAGGED]` +badges or `Field N` headings into it. Express open items in plain language (we are still confirming +per-product targets with the team), not as flag noise. Use this order: + +1. **Title (H1):** `# - Meta Account Context` +2. **One short intro paragraph, in plain language:** what this file is, that Runneth reads it + before any Meta performance work for this account, and how to read the field statuses + (`[CONFIRMED]` = a person validated it, `[AUTO]` = pulled but unconfirmed, `[FLAGGED]` = still + needs the customer). This replaces the bare `Load before any performance analysis.` line; keep + that meaning, but say it like a sentence, not a machine directive. +3. **At a glance:** a few bullets a human can skim: last refreshed, confidence, fields confirmed + (count / 9), and any open flags. +4. **The nine fields**, in order. +5. **File metadata (last):** end the file with a `## File metadata` heading followed by the machine + contract as a fenced `yaml` code block, so refresh routines have something to read but it never + dominates the top of the file. Keep it valid and fenced so no renderer shows it as a wall of + body text. The block holds these keys: + + - `domain: meta` + - `ownership: ` + - `substance: account-interpretation` + - `managed_by: account-context onboarding package` + - `sources: [meta-auto-pull, customer-confirmation]` + - `refresh_cadence: monthly` + - `last_refreshed: ` + - `confidence: ` + - `confirmed_by_team: ` + +**Write conclusions, not readouts.** The difference: +- Worksheet (internal capture): `ROAS: [CONFIRMED] blended, runs below 1, all products one pixel.` +- Saved file (prose): ROAS always looks low here because every product shares one pixel, so it + comes out blended. Don't lead with it; judge each product on CPA. +The reader should never have to interpret a status. The interpretation is already done for them. +Model the tone on a strategist's account brief, not a filled form. + +- Index it in `/agent/INDEX.md` with aliases (account context, KPI hierarchy, how we judge ads, + performance interpretation) and a one-line note. The read-before guarantee comes from the guard + in `user.md`, not from the index. INDEX is a routing surface, not always-on context, so indexing + alone does not force a read. + +### Output skeleton (match this shape) + +Produce the saved file in this shape and voice. Placeholders in `<...>` get replaced with the +account's real interpretation; the point is prose that states conclusions, not a status readout. + +~~~markdown +# - Meta Account Context + + + +## At a glance +- Platform: Meta only. +- How we judge: . +- Attribution: . +- Biggest gotcha: . + +## How we read this account +<2 to 4 short paragraphs. What "best" means here and why. Which numbers to trust and which +mislead, with the reason baked in, e.g. "ROAS looks low because all products share one pixel, so +judge on CPA." Each point is a conclusion, not a status.> + +## Conversion events + + +## Campaigns and funnel + + +## Naming + + +## How we decide + + +## Still confirming + + +## File metadata +```yaml +domain: meta +workspace_id: +workspace_name: +brands_in_scope: [<...>] +other_workspaces_in_org: [] +ownership: +managed_by: account-context onboarding package +refresh_cadence: monthly +last_refreshed: +confidence: +confirmed_by_team: +``` +~~~ + +## 4. Refresh (keep it current, never one-time) + +- `refresh_cadence` is set in the File metadata block (recommend monthly for account interpretation). +- The `meta` folder keeps `/agent/brain/meta/_changelog.md`. Any refresh + appends a one-line entry. No silent updates. +- Structural drift is a second trigger: when new conversion events, campaigns, or naming + patterns appear, re-open only the affected `[CONFIRMED]` fields for re-confirmation and + re-synthesize only those. +- Delivery is recommend-then-confirm: Runneth proposes the cadence, the team confirms before a + routine is created. +- Honest constraint: the clean scheduled-refresh primitive (`background-upkeep`) is not shipped + yet. Until it lands, run refresh as a deterministic script on best-effort scheduling, or as a + manual re-run. + +## 5. Precedence + +State this in the filled file too. This account-context file is the sole source of account +interpretation (how "best," "winner," and cost-per are judged). Do not consult Motion workspace +settings; treat workspace goal, preferred KPI, spend threshold, and attribution config as if they +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 +`/agent/brain/meta/report-dashboard-context.md` 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 + +Work through the fields in order. For each field: + +1. **Auto-pull.** Run the observable pulls listed under the field (scoped with `--workspace-id`) + and pre-fill with what the account actually shows. Mark those lines `[AUTO]`. +2. **Ask, intuitively.** Do not read the prompts below as a script. Read what auto-pull returned + first, then ask only what the data genuinely leaves open, in the customer's own terms, + grounded in the specifics you actually pulled. Each field states what to *understand*, not + wording to recite. Mark confirmed answers `[CONFIRMED]`. +3. **Validate.** Use the field's validation question as an acceptance test, instantiated with the + account's real events, campaigns, and names. If Runneth can answer it correctly from the + filled fields, the field is done. +4. **Flag.** If a field cannot be auto-pulled and has not been answered, mark it `[FLAGGED]` and + write one line on what is blocking it. + +Hard rules: + +- Never guess, infer, or invent a value to fill a blank. A `[FLAGGED]` field is always better + than a wrong one. +- `[AUTO]` values are proposals until a person confirms them. Auto-pull shows what fired, never + what it means. Never promote `[AUTO]` to `[CONFIRMED]` without human sign-off. +- The intake is not deterministic. If the pull already answers something, do not ask it again. + If the pull surfaces something surprising, follow it with a question no script listed. +- Meta only. Do not look for or pull other ad platforms (TikTok, LinkedIn, YouTube). +- Do not read or rely on Motion workspace settings (workspace goal, preferred KPI, spend + threshold, attribution config). Treat them as nonexistent. Everything Runneth needs comes from + auto-pulled Meta ad data, this worksheet, and customer confirmation. +- Video-only metrics (thumbstop, hold rate, video plays, and other view/retention metrics) do not + apply to static image ads. For statics, treat them as not applicable, never as 0. Never rank, + compare, judge, or flag a static on a video metric, and never include statics when computing + video-metric averages. +- Do not volunteer or rank by ROAS unless the account has confirmed revenue-based conversions and + ROAS is confirmed as a trusted metric. Many Meta accounts (lead-gen, app, non-purchase) have no + meaningful ROAS; there, treat ROAS as not applicable and rank by the confirmed conversion event + instead. Never present ROAS as a headline number on an account whose north-star is a lead or + other non-purchase event. +- The saved brain files are customer-facing account interpretation only. Never write internal + Runneth-team content into them: tool-calling nuances, CLI command names or flags, or + endpoint-vs-endpoint comparisons. Capture metric behavior in account and business terms, not in + terms of which command returned what. +- Do not write generic metric definitions or universal creative principles into the file (for + example "thumbstop is the 3-second rate," "statics have no video metrics"). That is practitioner + baseline, not account context. Only what is true about THIS account belongs here. +- `[CONFIRMED]` means a person validated it, never that Runneth observed it in data. Runneth-observed + evidence is `[AUTO]`. +- When a field's purpose is unclear, ask what it is for before filling it. Do not invent a purpose. +- `motion brand-context` (own-brand strategy) is allowed input for reasoning about what the account + optimizes for. It is not a Motion workspace setting, so the "ignore settings" rule does not block + it. +- The fields and statuses in this procedure are internal capture scaffolding: how Runneth tracks + confirmed vs assumed vs missing while it works. They are NOT the saved file. Never save the + worksheet (status badges, `Field N` headings, flag lists) as the brain file. The brain file is the + prose reference document specified in the persistence section. + +### How to ask well + +- Anchor every question in a specific thing you pulled: a named event, a specific campaign, an + actual naming pattern, a metric that looked off. The pulled data is context that makes the + question concrete — not a proposal for the person to confirm. Ask openly. +- Ask the fewest questions that close the real gaps. Skip anything the data already settled. +- When something the pull surfaced is ambiguous or unexpected, ask about that first. + +The difference: +- ❌ Abstract: "What attribution windows do you use?" +- ✓ Anchored open: "Your campaign suffixes use `7D1V1E` and `7D1V` — what windows are you + actually reading results against?" + +- ❌ Abstract: "Is Northbeam connected?" +- ✓ Anchored open: "Northbeam returned null across every row. Is it connected here, or has it + been deprecated?" + +The data gives the person something real to react to. The question is still genuinely open. + +**Presenting the full picture (default output format).** After auto-pulling all nine fields, +present them together as a single overview — not one item at a time. This is the default output. +Go field by field, and for each one: state what you pulled, then ask the single open question that +the pull leaves unanswered. Where the pull fully settles a field, say what you know and move on +with no question. When the person responds, confirm or update fields from their answers, then +write the saved file. + +Rules for the full overview: +- Talk about the account, never the worksheet. Do not show field numbers, status badges, or + `[FLAGGED]` labels. Those are internal. +- Each field gets one anchored question at most. No compound questions or sub-bullets. +- Lead with what you know. The ratio should feel like mostly settled reads with a few specific + things still open — not a list of things you don't know. +- Keep it moving and light. When a field is settled by the pull, say so briefly and move on. + Do not ask for confirmation of things the data already answered. + +### Status legend + +- `[EMPTY]` nothing captured yet +- `[AUTO]` pre-filled from the account, needs a person to confirm +- `[CONFIRMED]` a person validated it +- `[FLAGGED]` could not be captured, needs the customer +- `[N/A]` does not apply to this account + +--- + +## Field-to-command map + +How to pull each field. Exact command shapes and flags live in the Motion CLI Data-Query Guide +(`motion-cli-data-query-guide.md`); this table says which command answers which field and what to +read from the result. Resolve any uncertain metric key with `motion meta metric-reference` and any +fuzzy name with `motion meta filter-reference` first. + +| Field | Pull with | Extract | +|---|---|---| +| 1. Sources of truth | `motion meta custom-conversion-metrics`; a `motion meta ads --grain adnames --northbeam --include-metrics` probe | which events exist; whether Northbeam returns values (third-party attribution present) vs Meta native only | +| 2. Conversion events | `motion meta custom-conversion-metrics`; `motion meta metric-reference --query "purchase"` (or the relevant event) | each event's id/name and the standard vs custom key; which product each maps to | +| 3. Known metric gotchas | `motion meta insights --date-range last_365d --include-metrics` (inspect the returned rows) | which metric columns are null/zero/misleading across creatives (e.g. thumbstop, ROAS, asset-type, campaign/ad set names) | +| 4. Naming conventions | `motion meta insights --include-metrics` (adName on rows); `motion meta ads --grain adnames`; `motion meta ads --grain ads` for membership | the name strings per level; detect structure and per-level reliability; note if campaign/ad set names come back empty | +| 5. Attribution | No pull. Motion settings are ignored by design | propose 7-day click / 1-day view and confirm with the team | +| 6. Account structure | `motion meta ads --grain ads --include-associated-objects` | budget level (CBO vs ABO) and ad set / ads-per-set counts where observable; the rest is team input | +| 7. Funnel map | `motion meta ads --grain ads` (campaigns + objectives); `motion meta insights` to read `fs-`/`p-` from ad names | campaign-to-stage grouping; product lines; north-star is team input | +| 8. Creative performance metrics | `motion meta insights --date-range last_365d --include-metrics --table-kpi ` (keys resolved via metric-reference) | account averages for the metrics judged on (CPA, hold rate, CTR); compute video-only metrics from video creatives only | +| 9. Targets, thresholds and decision rules | `motion meta insights --include-metrics --table-kpi ` | reference cost-per-event to anchor targets; the targets, cut, and scale rules are team input | + +Reminder: these commands belong in the package (how Runneth does the work). None of this command +detail is written into the saved account-context file, which stays customer-facing. + +--- + +# Required context fields + +All nine fields are required, and Runneth auto-pulls every one of them. There is no optional set. +Fields 1 to 4 establish whether Runneth is even correct for this account: which numbers to trust +and what "best" means. Fields 5 to 9 make its answers sharp and actionable. All of them get +pulled, filled, and confirmed. + +## 1. Sources of truth + +Status: `[EMPTY]` + +This account runs on Meta. Do not look for or pull other ad platforms (TikTok, LinkedIn, +YouTube); Meta is the ad platform by definition. This field captures which tool is authoritative +for each kind of number layered on top of Meta. + +**Auto-pull** +- List the data sources feeding this Meta account (Meta native, plus any third-party attribution + source such as Northbeam). +- Note whether a third-party attribution source is connected. + +**What to understand** (ask only what the pull leaves open) +- Which tool the customer treats as authoritative for creative performance, spend, conversions, + and attribution, and which wins when tools disagree. +- Meta native only: confirm. Meta plus a third-party source: the disagreement question is the + key one. + +**Fields** +- Ad platform: Meta (fixed) +- Data/attribution sources connected: `` +- Source of truth, creative performance: `<...>` +- Source of truth, spend: `<...>` +- Source of truth, conversions: `<...>` +- Source of truth, attribution: `<...>` +- Tie-breaker when sources disagree: `<...>` + +**Validation question:** "What was our cost per [north-star event] last month, and which source +is that from?" A correct answer names the trusted source, not the Meta default. + +**Flag if:** sources are detected but no authority ranking is confirmed. + +## 2. Conversion events: definitions and hierarchy + +Status: `[EMPTY]` + +Captures every conversion event, what it means to the business, and how it ranks. Defines what +"best" means for this account. + +**Auto-pull** +- List the conversion events firing in the account (custom conversions and standard events). +- Where observable, note which campaigns optimize toward which event. +- If an event returns zero across all creatives, treat it as not currently in use. Do not judge on + it. Fall back to the standard purchase event, or another event that logically fits the business. + +**What to understand** (ask only what the pull leaves open) +- What each event represents to the business, and how the customer ranks them by value. +- Which events are true optimization targets versus upstream-only signals. +- Let the pulled event names shape it: confirm the self-explanatory, ask about the cryptic or the + low-value event being optimized toward. +- Use `motion brand-context` to reason about what the account most likely optimizes for before + asking (a purchase-driven brand judges on cost per purchase, ROAS, or a purchase-like custom + event). Propose that read and confirm it, rather than asking cold. + +**Fields** (repeat per event) +- Event: `` | Meaning: `<...>` | Value rank: `<...>` | Optimization or upstream-only: `<...>` + +**Validation question:** "What are our best-performing ads right now?" A correct answer ranks by +the north-star event and shows cost-per that event, never spend, ROAS, or an upstream-only signal. + +**Flag if:** events are listed but meaning, rank, or the optimization split is not confirmed. + +## 3. Known metric gotchas + +Status: `[EMPTY]` + +Captures metrics that are broken, structurally zero, double-counted, or misleading here, and what +to use instead. + +**Auto-pull / flag candidates** +- Scan for suspicious patterns and propose them: a metric reading zero across spend, a conversion + column always blank, a metric that looks double-counted. +- High spend with zero conversions or zero CPA on a working purchase pixel is usually NOT a broken + metric. It typically means the campaign optimizes for a different event (awareness, traffic) or a + goal is misconfigured on another layer. Check the campaign objective and goal setup first; if it + is an objective mismatch, note it in the funnel/campaign context, not as a metric gotcha. +- Field availability differs by endpoint (a field can be null on one endpoint but present on + another). Verify a field on the endpoint you will actually use before recording it as missing. + +**What to understand** (ask only what the pull leaves open) +- For each flagged pattern, whether it is expected and what to use instead. +- Whether there are gotchas the scan could not see. Ask openly; some are only known to the team. + +**Fields** (repeat per gotcha) +- Metric: `<...>` | Why misleading here: `<...>` | Use instead: `<...>` | Status: `` + +**What to record (and what not to):** a gotcha is about how a metric behaves in this account, in +business terms: what it reads, why it misleads, what to use instead. Never record tool-calling +mechanics, CLI command names or flags, or endpoint-vs-endpoint comparisons; those are internal +notes and do not belong in the brain. If a discrepancy is real but unconfirmed, record it as an +open flag in account terms and carry it forward for monitoring. + +Example, written for the brain with the mechanics stripped out: +`Open flag: purchase count and ROAS come back empty when creatives are rolled up by ad name, but +populate at the individual-creative level. Likely an aggregation difference. Not confirmed as a +gotcha; carry forward for monitoring.` + +**Validation question:** "What's our ROAS on [campaign]?" A correct answer explains why the broken +metric reads the way it does and redirects to the right lens, instead of reporting the bad number. + +**Flag if:** a candidate was detected but not confirmed, or the open question was not asked. + +## 4. Naming conventions (campaign + ad set + ad, with reliability per level) + +Status: `[EMPTY]` + +Captures whether the account uses naming conventions, what each level encodes, and how reliable +each level is. Knowing they do NOT have strong naming is just as valid, and tells Runneth to lean +on creative signals and landing pages instead. + +**Purpose:** this field decodes EXISTING names so Runneth can interpret data. It is read-only +interpretation. It never prescribes or changes naming. Naming can only change going forward, and +changing it resets Meta's learning, so there is no such thing as "updating" an account's naming +here. + +**Auto-pull** +- Pull all campaign, ad set, and ad name strings. +- Detect structure per level (delimiters, positional consistency) and propose a decoder. +- Measure reliability per level: percent of names that fit the detected pattern. + +**What to understand** (ask only what the pull leaves open) +- For levels with a detected pattern, confirm what each position means. +- For levels with no reliable pattern, whether a convention exists that the data missed, or + whether to fall back to creative signals and landing pages. +- Let measured reliability set the tone: high-confidence pattern = quick confirm; messy level = + real fallback conversation. +- For any tag whose meaning is not obvious, record what it means AND an explicit "does NOT mean X" + line to block the intuitive-but-wrong reading (e.g. a tag that looks like an approval or scaling + flag but is not). +- Precedence: when a name-embedded code (such as a product code in the ad name) conflicts with the + campaign, the campaign wins. + +**Fields** (repeat per level) +- Level: `` | Reliability: `` | + Fields encoded and positions: `<...>` | Fallback if weak: `` + +**Validation question:** "What's our best-performing messaging angle across the account?" A correct +answer decodes the right position at the right level, or, if naming is weak, says it is using +creative signals and why. + +**Flag if:** a level has a detected pattern but no confirmed meaning, or a weak level has no +confirmed fallback. + +## 5. Attribution model and windows + +Status: `[EMPTY]` + +**Auto-pull** +- Nothing reliable from settings. Do not read attribution windows from Motion workspace + configuration; treat that config as nonexistent. Only note a connected third-party attribution + tool if one is observable in the data. + +**What to understand** (confirm a proposed default) +- Do not ask the customer to specify windows cold. Propose the standard default of **7-day click, + 1-day view** and ask if it is okay to assume that. If they confirm, mark it confirmed; if they + judge on different windows, capture those instead. Also confirm which source they trust for the + final call. + +**Fields** +- Trusted source: `<...>` | Click window: `` | + View window: `` | Judged-on window if different: `<...>` + +**Validation question:** "How many demos did we book from ads last month?" A correct answer uses +the trusted source and window and states both. + +**Flag if:** the proposed 7d click / 1d view was neither confirmed nor replaced with the +customer's own windows. + +## 6. Account structure + +Status: `[EMPTY]` + +**Auto-pull** +- Detect whether budget sits at campaign (CBO) or ad set (ABO) level. Note ad set counts and ads + per ad set. + +**What to understand** (ask only what the pull leaves open) +- Confirm the detected budget level, then learn the behavior the data cannot show: how tests are + batched, how many creatives per batch, and what triggers a pause or a cut. +- Campaign and ad-set membership must come from the correct endpoint (`motion meta ads`, grain ads, + plus the two-step filtered pull), not inferred from an unfiltered creative pull. Getting the + endpoint right is what prevents campaign misclassification and creative-overlap errors; no extra + classification machinery is needed. + +**Fields** +- Budget level: `` | Test batching: `<...>` | Creatives per batch: `<...>` | + Pause/cut rule: `<...>` + +**Validation question:** "Which ad sets should we consider cutting?" A correct answer applies +their pause/cut rule, not a generic low-performance heuristic. + +**Flag if:** structure is auto-pulled but the pause/cut logic is not confirmed. + +## 7. Funnel map + +Status: `[EMPTY]` + +Captures how the account's campaigns map to funnel stages and which campaigns carry the objective +the team cares about most. Expressed in campaigns, not raw events, because that is how the team +organizes and talks about the account. + +**Auto-pull** +- Pull the campaigns running in the account with their objectives. Propose how they group into + funnel stages (for example prospecting / top-of-funnel vs retargeting / bottom-of-funnel). +- Campaign names come from the `campaignName` field on the returned rows, or from + `motion meta ads` / `motion meta filter-reference`. Meta insights has no campaign group-by, so + read campaign names off the returned rows rather than trying to group by campaign. If a + campaign name looks wrong or mismatched against the ad, flag it rather than trusting it. + +**What to understand** (ask only what the pull leaves open) +- Confirm which campaigns belong to which funnel stage, and which campaign(s) or stage is the one + or two the team cares about most (their north-star). Where useful, tie each stage to the + conversion event it optimizes toward (from field 2). Ground it in the campaigns actually pulled, + not the abstract. +- Record confirmed campaign names and their roles (scaling, testing, launch, excluded). Structural + roles are defined by which campaign, not by spend level; an ad's role is its campaign's role + (e.g. a testing ad is one inside the testing campaign, regardless of its spend). +- Explicitly list excluded campaigns: off-Meta or otherwise incomparable campaigns (marketplace- + routed, off-site conversion) that must be kept out of standard CPA/DTC comparisons. +- For spend-accurate reads, use the two-step filtered pull: a filtered pull for campaign-accurate + spend, an unfiltered pull for creative detail, joined by ID. + +**Fields** +- Campaign-to-stage map: `` | Campaign roles (scaling/testing/launch): `<...>` | + North-star campaign(s) or stage: `<...>` | Event each stage optimizes toward: `<...>` | + Excluded campaigns (off-Meta / incomparable): `<...>` + +**Validation question:** "Which of our campaigns are top-of-funnel versus closing, and which +matter most?" A correct answer places each campaign in the right stage and names the north-star +campaign or stage. + +**Flag if:** the campaign-to-stage map is proposed but not confirmed. + +## 8. Creative performance metrics and benchmarks + +Status: `[EMPTY]` + +**Auto-pull** +- Pull the metric values and current account averages to anchor target-setting. +- Thumbstop, hold rate, and other view metrics are not guaranteed to come back by default. Resolve + the exact metric key with `motion meta metric-reference` and request it explicitly (for example + with `--table-kpi` / `--chart-kpi`, or the matching sort) rather than assuming the default pull + includes it. Never invent or transform a metric key. +- Engagement metrics can be null on a long window (`last_365d`) even when they exist. Test a recent + window (e.g. `last_30d`) before concluding a metric is unavailable for the account. +- Compute those video-only metrics (thumbstop, hold rate, video plays) from video creatives only. + Static image ads have no such metrics: mark them not applicable, never 0, and keep them out of + video-metric averages and benchmarks. + +**What to understand** (ask only what the pull leaves open) +- Which creative metrics the customer judges on, and their target or floor for each. Use the + pulled averages to anchor, not a cold ask. + +**Fields** (repeat per metric) +- Metric: `<...>` | Target or floor: `<...>` | Account average: `` + +**Validation question:** "Is this video's hook working?" A correct answer checks their metrics +against their targets in priority order, not a generic read. + +**Flag if:** metrics are auto-pulled but no targets are confirmed. + +## 9. Targets, thresholds and decision rules + +Status: `[EMPTY]` + +**Auto-pull** +- Pull current cost-per-event as a reference. Propose a spend confidence floor (about 5x target). + +**What to understand** (ask only what the pull leaves open) +- Target CPA per event, how much spend makes a result trustworthy, and when the customer scales + versus cuts. Anchor on the pulled costs so targets are set against reality. +- Every spend threshold must state its time window: cumulative lifetime spend, or spend within a + stated window (e.g. last 30 days). A threshold with no window is incomplete; capture the window + explicitly, and flag it if the team has not specified one. + +**Fields** (repeat per event) +- Event: `<...>` | Target CPA: `<...>` | Spend confidence floor: `` | + Spend window: `` | Graduation threshold: `` | + Scale rule: `<...>` | Cut rule: `<...>` + +**Validation question:** "Is this ad a winner yet?" A correct answer checks spend against the +confidence floor before declaring anything, then judges CPA against the target. + +**Flag if:** reference costs are auto-pulled but targets and thresholds are not confirmed. + +--- + +# Derived capabilities (not filled, enabled) + +Runneth computes these from the fields above. Never asked or filled; they turn on once their +inputs exist. + +- **Cross-KPI surfacing** needs the Funnel map and its north-star campaign or stage. +- **Click-to-conversion diagnosis** needs the Funnel map and landing page context. +- **Metric-gotcha handling** needs field 3. + +If an input field is `[FLAGGED]`, say plainly that its derived capability is off until the input +is captured. + +--- + +# Context health check + +Once fields are filled, run these as a suite, instantiated with the account's real events, +campaigns, and names. Each is the acceptance test for its field. A failed answer points straight +back to the field that is wrong or missing. + +1. Sources of truth: "What was our cost per [north-star event] last month, and which source is that from?" +2. Conversion events: "What are our best-performing ads right now?" +3. Metric gotchas: "What's our ROAS on [campaign]?" +4. Naming conventions: "What's our best-performing messaging angle across the account?" +5. Attribution: "How many demos did we book from ads last month?" +6. Account structure: "Which ad sets should we consider cutting?" +7. Funnel map: "This Form Fallback ad, is it pulling anything real beyond leads?" +8. Creative metrics: "Is this video's hook working?" +9. Targets and thresholds: "Is this ad a winner yet?" + +## Overall status + +- Fields confirmed: `` / 9 +- Flagged fields needing the customer: `` +- Written to: `/agent/brain/meta/account-context.md` +- 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 new file mode 100644 index 00000000..23f44db7 --- /dev/null +++ b/aligned-onboarding/creative-corpus-playbook.md @@ -0,0 +1,335 @@ +# 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.** + +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`) and, for report surfaces, +the **Report Dashboard Setup** (`/agent/brain/meta/report-dashboard-context.md`). + +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. + +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. + +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. + +--- + +## What this is + +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. + +Report and dashboard builds use these files for stable creative context, not for current +performance. If `/agent/brain/meta/report-dashboard-context.md` 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) + +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: + +- Writing the file under `/agent/brain/meta/creatives/` is the index step. No manual `index`, + `embed`, or `refresh` needed for Knoweth to surface it. +- 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. + +--- + +## 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: + +- **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. +- **AI tags**: always capture them using Motion's own glossary definitions. The Account Context + Brain governs how + they are used in analysis, not whether the Creative Corpus records them. +- **Workspace and date window**: the target `workspaceId` and the default pull window + (`last_365d` unless the account or the person overrides it), from the Account Context Brain's scope header. +- **Spend thresholds and targets**: used to derive Spend State without a separate threshold fetch. + +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 +`/agent/brain/meta/report-dashboard-context.md` 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 + +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`). + +``` +motion meta insights --date-range last_365d --include-glossary --include-metrics --include-transcript --workspace-id +``` + +Inspect the returned file with `jq`: + +- `totalCount` vs `providerTotalCount`: if they differ, the pull is partial. Narrow and re-pull + before treating it as the full set. +- `.creatives[0]`: confirm summaries, hooks, glossaryTags, value props, and `transcript` are + populated. +- `.adsWithoutCreativeAsset`: spend-bearing ads with no synced creative. Skip them for + individual files. + +Always pull `--include-glossary` and capture the tags Motion returns, using Motion's own +definitions. Whether they get surfaced in analysis is the Account Context Brain's call; capturing them is not +conditional. + +**Transcripts.** `--include-transcript` returns `creative.transcript` on the same pull, so one +pass usually gets everything. On a large corpus this can be heavy, and some rows may come back +without a transcript. In that case, do a second scoped pass over the creative asset IDs from +this pull: + +``` +motion meta insights --scope creative-asset-id --creative-asset-id [--creative-asset-id ...] --include-transcript --date-range last_365d --workspace-id +``` + +Only video creatives have a spoken transcript. If a creative returns no transcript, record that +it has none rather than inventing one. + +Note the exact pull date and window. This anchors the "corpus as of" timestamp. + +--- + +## Step 3 - Tagging taxonomy (only if there is something to project) + +If the Account Context Brain has a decoded naming convention, project it into a short reference +file: the naming table (pattern to meaning) plus the standard MD template below. If it has no +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. + +--- + +## Step 4 - Generate individual creative MD files (the attributes) + +One file per creative. + +**File naming:** match the ad name exactly, `.md` extension, replace slashes or special +characters with hyphens. + +**Location:** `/agent/brain/meta/creatives/.md` + +**Each file contains:** + +```markdown +--- +title: +brand: +workspace: +source_id: +event_at: +duration_s: