feat(meta-and-voc-onboarding): Meta + VoC onboarding package - installable by name

[motionBuilderEric]

Meta and VoC Onboarding (meta-and-voc-onboarding, package version 1): Meta onboarding (Cacheth-first, three steps + Field 10 deck spec), VoC data pull, Knoweth organize, ad-performance + walkthrough skills, installable by name, corpus-search removed

Summary

Replaces the legacy Aligned Onboarding payload with the meta-and-voc-onboarding/ folder: one part per subfolder — meta/, voc-data-pull/, knoweth/, meta-ad-performance-analysis/, and onboarding-walkthrough/ — with a single combined README and a real schema-v1 package.json manifest (package version 1; versions are simple integers bumped once per package update) mapping every file. The package is registered in the repo root package-index.json, so it installs by name: a person says "install meta-and-voc-onboarding" and Runneth runs package intent add-optional meta-and-voc-onboarding + package sync - no GitHub link, artifacts fetched from GitHub, durable intent across VM rebuilds, fleet auto-updates (updatePolicy: auto), clean uninstall. The canonical install message carries the kickoff clause ("...then read /agent/brain/meta-and-voc-onboarding/post-install.md and execute its install-time sequence in this conversation" - exact copy-paste text in the package README), so the installing conversation runs the full setup end to end; an activation package instruction staged with the files backstops later sessions. Measured end-to-end on staging, install-to-gap-questions went from 16m08s to 10m47s versus the old LLM-copied install-config.json flow. Creative content is Cacheth-first (no per-creative files anywhere), the Meta flow runs as three steps (Creative Attributes → Account Context Brain → Validation) with Field 10 as the deck spec, 17 VoC platforms get standardized raw-data pulls with daily sync routines, Knoweth gets an organize-the-brain part grounded in the real retrieval wiring, and the corpus-search/ tool is removed. This targets the staging deployment, where retrieval runs on Knoweth and creative summaries live in Cacheth, so nothing in the package builds or depends on a local search index.

What changed

Meta part (meta/), three steps plus two supporting references:

• meta-creative-attributes-playbook.md — Step 1 (renamed from Creative Attribution: the step establishes attributes of the creative, not spend attribution). The creative-content-layer contract plus naming decode: creative content lives in Cacheth (the local creative cache), queried via Knoweth pre-context injection first, then the motion cache CLI (search-summaries / get-creative; local, no API call). No per-creative files are written. The decode is a handoff: detected provisionally here (including where product tokens live across name levels) and folded into the Account Context Brain (Field 4) on confirmation.
• meta-account-context-brain-onboarding-package.md — Step 2, v1.31. Nine required interpretation fields plus Field 10 (the deck spec), opening brand frame, closing TLDR. Field 4 owns the confirmed naming decode and writes the operational decoder to /agent/brain/meta/naming-decoder.json (typed positions, query fields, _VALUE_ filter patterns, LP-reference decode); it also detects and confirms where product names live. Field 9 is structured around four captures (ranking metric, CPA target, winner/cut criteria incl. spend floor, default reporting window). Field 10 (reporting structure + marketing calendar) synthesizes from Fields 4/7/9 with no new pull — it gates the validation deck, not the question loop, is offered as fill-in Step 5 once its inputs confirm, and is saved as the deck-spec section of account-context.md. The fill-in presentation has a required three-part output schema (opening frame, field sections, closing TLDR) with a literal skeleton and pre-send checklist — structure fixed, content account-specific. The "at a glance" section can carry a one-line answer-register note written by validation's register corrections. Persists to /agent/brain/meta/account-context.md with a read-before-performance guard merged into /agent/user.md.
• meta-validation-onboarding-package.md — Step 3, v1.10. The answer-and-confirm loop with the show-the-work rule (each answer states which filter, signal, and name level it used), the show-the-creatives rule (referenced creatives render as a gallery per the Data-Query Guide contract), register corrections (how an answer is pitched is correctable like any fact; standing preferences persist to account-context.md), and a name-level probe starter question ("show me all our [product] ads"); validation.md written incrementally after every confirmed answer so interrupted validations resume instead of restarting; starter question 4 uses neutral testing-vs-scaling language with a single-pool fallback; the weekly deck build pre-filled from the Field 10 deck spec (no deck without it — an unconfirmed spec runs its two beats at deck time; questions-only customers never need it); lock-in (deck approval, refresh routine, Slack); and the MVCE gate, which ends with an explicit handoff to the Knoweth organize part. Validation runs as a training loop: every piece of feedback routes through a durability test (judgment rules heal ACB fields, standing preferences persist to the register note or Field 10, current-state facts shape the answer only, one-offs revert on refresh), and deck change requests are context corrections — the deck regenerates from context and is never hand-edited. Gates on cache coverage, not files.
• motion-cli-data-query-guide.md — the canonical contract for Motion CLI pulls, now Meta-only (TikTok insights, brand-specific metric gotchas, and the workspace-goal / spend-threshold commands removed). New "Which name level to filter on" section: product/theme words legitimately cascade across campaign, ad set, and ad names; bare product names default to adName + includes; never silently swap levels. Adds the WHAT-vs-WHY evidence split (live metrics answer what; Cacheth creative content and VoC answer why, with ad comments bridging the two; metrics pick the set, content explains it), the presenting-creatives contract (creatives render as a gallery of cards with media from the Cacheth record's url — the insights mediaUrl is often null on ASC — and names always decoded through naming-decoder.json), and the answering-posture section (judgment over rules: report data-answerable questions plainly, offer interpretation instead of dumping it, respect mode signals like "just the numbers"). Performance metrics are pulled live, never stored.
• cacheth-command-reference.md — the flag-level contract for the five motion cache commands. motion cache status runs first as a one-shot access check; exports are a two-hop flow (the command's workdir wrapper file carries .providers.<provider>.path pointing at the JSONL corpus in Cacheth's own storage); transcripts and AI glossary tags exist only on the full record via get-creative — export, search, and Knoweth injection are summary-level (ad metadata, copy, media URLs, summary text). Cacheth itself is a hydration layer behind the CLI, transparent to the agent; Knoweth indexes the summary artifacts generated from it, never the complete records.

VoC Data Pull part (voc-data-pull/):

• SKILL.md plus references/platform-recipes.md and four output templates, installed to the skills root (/agent/.agents/skills/voc-data-pull/). Pulls raw voice-of-customer data — reviews, support conversations, community posts, ad comments — from 17 platforms (Judge.me, Trustpilot, Yotpo, Junip, Okendo, Stamped, Reviews.io, Gorgias, Intercom, Zendesk, Klaviyo, Attentive, Gong, Hotjar, Discord, YouTube, Reddit, plus Meta ad comments) into standardized files under /agent/brain/data-sources/voc/<platform>/, one id-keyed file per item. Coverage is by availability (OAuth, stored API key, or Motion native), with a raw-VoC save exemption and the Reddit full-window contract.
• Recipes are resilient by mandate (Step 2): the live API is the truth and a stale recipe never stops a pull — adapt field names, endpoints, and pagination from real responses, stop only when external_id/created_at genuinely don't exist. Docs are single-sourced: per-platform evidence levels and caveats live only in each recipe's header (Junip live-verified, Yotpo since_date corrected, the eight new platforms doc-grounded), and the coverage contract (12-month window, page-cap resume, coverage reporting) is owned solely by SKILL.md's hard boundaries.
• Setup runs at post-install for every reachable platform, or on request afterwards: one daily routine per platform (voc-sync-<platform>, 6am), first run backfills 12 months in the background, daily runs pull only new items. Pulls never run inside the installing conversation.

Knoweth organize part (knoweth/):

• knoweth-organize-onboarding-package.md — the cross-cutting organize-the-brain part: after the account questions are answered and content has landed, organize retrieval (shared content in the global lane, sliced with tags and a naming decoder) and hold it with two sentinel guard blocks merged into /agent/user.md. Grounded in the real harness wiring: only global, user:<userId>, and project:<workspaceId> are queried today; data-source-family lanes are a documented forward path gated on a harness change. Durable done-marker: /agent/brain/_tag-vocabulary.md. v1.1: gate 2 gains a file-based coverage fallback for VoC data that landed without a sync routine.

Meta Ad Performance Analysis skill (meta-ad-performance-analysis/):

• Diagnostic framework for one ad, a set of ads, or the account in general, installed to the skills root: primary KPI first, efficiency against the account's own averages, then the funnel trace (first frame retention, thumbstop, hold rate, engagement, CTR outbound, conversion rate, AOV); across many ads, group by optimization goal and rank by primary-KPI efficiency before diagnosing, tying every funnel diagnosis to what the creative actually says and shows. Output renders analyzed ads as a gallery with decoder-normalized names. Interpretation comes from account-context.md (guard-enforced), metrics from live CLI pulls, name filters through the confirmed decode. On-demand only.

Onboarding Walkthrough skill (onboarding-walkthrough/):

• The presentation layer for onboarding, installed to the skills root: post-install ends by asking "Are you ready to begin your onboarding?", and the walkthrough — opening brand frame, field-by-field findings with the gap questions only a human can answer, closing TLDR — fires only on a human's yes to that invitation or an explicit ask to begin/resume onboarding. Outside that, nothing self-runs.

corpus-search removed:

• corpus-search/ deleted entirely. Root README.md and MIGRATION.md updated so the compatibility set is now just building-integrations; manifest-name references corrected to package.json. The removed payload stays recoverable from archive/full-library and the pre-cleanup tag.

Install mechanics (package manager):

• install-config.json is gone; meta-and-voc-onboarding/package.json (schema v1, version 1, categories: [], installPolicy: manual, updatePolicy: auto, uninstallPolicy: allowed) maps every doc, the three skills, the staged guard files, and the activation instruction. Registered in package-index.json (source github at main). One package-manager call stages everything deterministically; package install "github:...#<branch>" remains only as the branch-testing path.
• The four /agent/user.md guard blocks ship as ready-made staged files (guards/, byte-identical to the blocks embedded in the docs), merged in one whole-file Write — byte-for-byte, workspaceId substituted, with a mandatory pre-write check that the base document and each sentinel pair appear exactly once.
• The repo-only meta-and-voc-onboarding/CHANGELOG.md (never staged to customer brains) is a single v1 entry describing the package as it ships; each staged doc keeps its version header.

Activation model (instructions/activation.md + post-install.md):

• The canonical install message tells the agent to read post-install.md and execute its install-time sequence in the same conversation; an activation package instruction staged with the files also lands in the agent's standing instructions as a backstop for later sessions. The sequence is idempotent (the guard sentinels double as the ran-already marker): reachability check (OAuth connections, stored secrets, Meta workspace), VoC sync setup for every reachable platform with first runs kicked (a connected Meta workspace counts — voc-sync-meta-ads via ad comments), the guard merge, Creative Attributes, and the Account Context Brain autofill running silently (results persisted to the brain); it ends by asking "Are you ready to begin your onboarding?" — the findings presentation and gap questions fire only on a human's yes, via the onboarding-walkthrough skill. What the guards gate (Knoweth organize, Meta validation) still fires later on its own gates. One status line per part; if nothing is reachable, it says so and stops (no polling — later connects are set up on ask).
• Post-install is tuned for staging VMs: canceled routines are terminal (never resumed), the edit/patch tool is never used, existing files are read-then-written-whole.
• Post-install's checks are mechanical, not judgment calls: stored secrets are probed per documented key (secret run --env KEY=<SECRET_KEY> -- true or a bounded secure-fetch run — the secret store has no list command, and a refused directory read proves nothing), the guard merge resolves the conversation's active Meta workspace and stamps it into the guard headers only (Knoweth project:<workspaceId> lane syntax stays literal), the Creative Attributes step reads the playbook at its staged path (/agent/brain/meta-and-voc-onboarding/meta-creative-attributes-playbook.md) and never improvises if it is unreadable, the account-context brain file is written as a prose reference document and indexed in /agent/INDEX.md at install, and the end-of-run readiness report is template-only status lines — no metrics, counts, or decoder detail in the report or the narration around it.
• Creative ingestion still runs only through the Cacheth sync, and the ad-performance skill stays on-demand; nothing in the package writes per-creative files to the brain.

Notes for reviewers

• Family/business lanes need the harness to layer configured lanes into the requested read set (resolveKnowethReadLanes requests exactly [user, project:<workspaceId>, global] today). Needs an owner; fits PDEC-9225.
• The VoC pull flow was E2E-tested live on a fresh sandbox: skill install, routine creation, 12-month backfill, and an incremental re-run verified.
• Field 10's marketing-calendar detection reads campaign-type and launch-date positions from the account's naming-decoder.json — never an assumed offset; if the decoder carries neither, it asks for the calendar directly.
• This PR leaves scripts/validate-runneth-package-index.mjs untouched — the validator update for the current contract (integer versions, empty categories, github source) lands separately in fix(packages): align package index validation contracts #184. The fleet-approval gate still applies: this PR registers a managed-sync package, so it needs the runneth-fleet-change-approved label after core engineering approval (not self-applied).
• Known platform bugs (fixes belong in agent-builder): the Edit tool fails validation on staging VMs, and /agent/user.md is blocked from Bash (hence the single-Write guard merge).
• The package describes desired state only and never instructs workarounds: if an install fails, both READMEs tell the agent to report the exact error and stop - never hand-copy staged files or edit state under /agent/.runneth/packages/. Hand-written package state has produced invalid installed.json entries in the field that blocked every later turn on the VM.

Staging validation

• End-to-end branch installs on staging, each graded from the conversation trace (Runneth thinking + tool calls) against a 13-point rubric covering install mechanics, the unprompted post-install sequence, the Cacheth decode flow, guard placement, and report discipline: Motion Crew, Buoy (4,339 cached creatives), Huel (766), Huel EU, Tentbox, and ecko digital.
• Final clean-slate re-runs (full uninstall first) on the two cache-enabled workspaces: Huel EU 13/13, Motion Crew 12/13 — the single miss was trace observability in a contaminated conversation, not package behavior.
• A sterile fresh-conversation run confirmed the activation model end to end: the post-install sequence fires unprompted on the first turn after install (package instructions inject at turn start), reads the staged playbook, and runs the Cacheth flow.
• A cache-disabled sandbox exercised the documented error path: one motion cache status call, blocker recorded, step stopped with no retry loops — exactly as the playbook prescribes.
• Platform-level issues observed and deliberately out of scope (fixes belong in agent-builder): package uninstall leaves merged guard blocks and brain files on disk, and transient harness errors that retried cleanly.

Test plan

• Package index validation passes once fix(packages): align package index validation contracts #184's validator lands
• The canonical install message (package intent add-optional meta-and-voc-onboarding + package sync + the kickoff clause) stages every file and runs the post-install sequence in the same conversation
• Confirm the post-install run creates one voc-sync-<platform> routine per reachable platform, kicks backfills in the background, and never pulls VoC data in-conversation
• Confirm no path in the staged docs triggers automatic creative ingestion, and that a VM with nothing reachable gets a stop-and-say-so (no polling)
• Confirm the four guard blocks merge at post-install and Knoweth organize / Meta validation still wait on their own gates
• Confirm the Knoweth organize step runs once (gated on _tag-vocabulary.md) behind its already-merged guard blocks
• Confirm the validation question loop starts on the nine confirmed fields without Field 10, and the deck build refuses until Field 10 is confirmed (running its two beats at deck time)
• Confirm the name-level probe answer states which name level it filtered