Rachel/voc onboarding package

package-index.json

@@ -1,5 +1,24 @@
 {
   "schemaVersion": 1,
-  "indexRevision": "initial-empty",
-  "packages": []
+  "indexRevision": "2026-08-04-01",
+  "packages": [
+    {
+      "id": "voc-onboarding",
+      "name": "Voice of Customer Onboarding",
+      "version": "1",
+      "description": "INSTALLER: the moment this package installs, read /agent/brain/voc-onboarding/post-install.md and follow it - it announces the install and states the trigger phrase; nothing else runs at install time. The Voice of Customer onboarding package. Manual install only (installPolicy: manual): an agent installs it with one explicit package install call of its GitHub source. Stages this README and post-install.md into /agent/brain/voc-onboarding/, plus the voc-data-pull, voc-audit, and voc-onboarding-walkthrough skills into the skills root. The package is fully human-triggered: a person saying 'run voice of customer onboarding' (or any ask to begin, resume, or check on VoC onboarding) invokes the voc-onboarding-walkthrough skill, which resolves the workspace from the conversation's own Motion context, finds every reachable VoC platform (OAuth, stored key, or Motion native - a connected Meta workspace counts, since ad comments are customer voice), pins a human-confirmed platform account per workspace, creates one daily voc-sync-<workspace>-<platform> routine per reachable platform with the first run kicked (files land under /agent/brain/<workspace>/data-sources/voc/<platform>/), and, once data lands, presents the per-integration Voice of Customer summary and offers the Voice of Customer Audit by previewing its plan. The first complete backfill also offers the audit once, asynchronously. The audit runs only on a person's yes or explicit request and saves one compiled page at /agent/brain/<workspace>/data-sources/voc/voice-of-customer-audit.md. Outside those human-triggered runs, nothing self-runs - this package merges no guards and never touches /agent/user.md. One workspace at a time; everything it produces is scoped to that workspace's own folder, so a second workspace in the same org onboards additively without touching the first.",
+      "categories": [],
+      "packageManagerVersion": 1,
+      "installPolicy": "manual",
+      "updatePolicy": "auto",
+      "uninstallPolicy": "allowed",
+      "source": {
+        "type": "github",
+        "owner": "Motion-Creative",
+        "repo": "runneth-apps",
+        "path": "voc-onboarding",
+        "ref": "main"
+      }
+    }
+  ]
 }

voc-onboarding/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## v1 (August 2026)
+
+Initial release: the Voice of Customer half of `meta-and-voc-onboarding`, extracted as-is
+at parent commit `bce9619` and isolated from the Meta onboarding work.
+
+- **Fully human-triggered lifecycle.** Install stages files and announces the trigger
+  phrase — nothing else runs at install time. "Run voice of customer onboarding" invokes
+  the new `voc-onboarding-walkthrough` skill, which owns the whole sequence: workspace
+  resolution from the conversation's own Motion context, VoC reachability probes (OAuth +
+  stored keys + Meta connection), human-confirmed account pinning, one daily
+  `voc-sync-<workspace>-<platform>` routine per reachable platform with the first run
+  kicked, then — once data lands — the per-integration Voice of Customer summary and the
+  explained audit offer (method preview, additions and reference docs invited).
+- **No guards, no roster, no `/agent/user.md` writes.** Because nothing self-fires, the
+  package needs no activation gate: idempotency comes from routine existence and files on
+  disk, per the voc-data-pull skill's resume rules.
+- **`voc-data-pull` and `voc-audit` copied verbatim** from the parent snapshot, including
+  the Meta ad-comments integration (one file per creative under `voc/meta-ad-comments/`,
+  `motion meta creative-comments`), the audit's numbered standalone findings with verbatim
+  attributed quotes inline and explicit no-signal lines, and the reference-docs intake.
+  One substitution in `voc-data-pull/SKILL.md`: the setup trigger names this package's
+  walkthrough instead of the parent's install. The full substitutions list lives in the
+  README's "Provenance and divergence" section.

voc-onboarding/README.md

@@ -0,0 +1,108 @@
+# Voice of Customer Onboarding
+
+The VoC-only onboarding package: it finds a workspace's reachable voice-of-customer
+integrations, syncs their raw data into the workspace's brain folder on a daily routine,
+and turns that corpus into durable creative-strategy insight through the human-gated Voice
+of Customer Audit. It is the Voice of Customer half of the `meta-and-voc-onboarding`
+package, extracted as-is and isolated from the Meta onboarding work (Account Context
+Brain, Creative Attributes, Meta Validation, Knoweth organize) — with one structural
+difference: nothing runs at install time. A person triggers everything.
+
+**Meta ad comments are a VoC integration.** A connected Meta workspace always gets a
+`voc-sync-<workspace>-meta-ad-comments` routine (pulled with
+`motion meta creative-comments`, one file per creative) alongside the review, support, and
+community platforms. That is the only Meta touchpoint in this package.
+
+## The three parts
+
+- **VoC Onboarding Walkthrough** (`voc-onboarding-walkthrough/`) — the entry point. A
+  person says "run voice of customer onboarding" (or asks to begin, resume, or check on
+  it) and the skill runs its setup phase: workspace resolution from the conversation's own
+  Motion context, reachability probes across every VoC platform (OAuth connections and
+  stored keys), human-confirmed account pinning, one daily `voc-sync-<workspace>-<platform>`
+  routine per reachable platform with the first run kicked. Once data lands, its
+  presentation phase gives the per-integration Voice of Customer summary ("Judge.me: 1,240
+  reviews across 6 products, May 2025 – July 2026") and offers the audit by previewing its
+  plan — split by product, score 1–5, the five buckets, personas — and inviting additions
+  and reference docs. Re-invoking is always safe: existing routines are skipped, a
+  mid-backfill invocation reports counts so far, an existing audit gets a rerun offer.
+- **VoC Data Pull** (`voc-data-pull/`) — the sync mechanics: platform recipes, account
+  pinning rules, routine templates, coverage contract (trailing 12 months, bounded pulls),
+  and the standardized one-file-per-item storage format (one file per creative for Meta ad
+  comments). Files land under `/agent/brain/<workspace>/data-sources/voc/<platform>/`.
+  The first fully covered backfill sends one asynchronous audit offer to the setup
+  conversation, previewing the audit's plan.
+- **Voice of Customer Audit** (`voc-audit/`) — manual skill: separates every synced entry
+  by product, scores 1–5 for usefulness, and extracts five insight buckets per product
+  (pain points, trigger moments, objections before purchasing, transformations, standout
+  language), plus evidence-backed personas for products with 200+ entries. Buckets 1–4 are
+  numbered lists of distinct standalone findings with verbatim attributed quotes inline
+  (name, rating, source file) and explicit no-signal lines for empty buckets. Saves one
+  canonical compiled page at
+  `/agent/brain/<workspace>/data-sources/voc/voice-of-customer-audit.md`. Runs only on a
+  person's yes to an offer or an explicit request; requires at least 200 total entries and
+  a completed backfill.
+
+## File structure
+
+```
+voc-onboarding/
+  package.json                          # manifest
+  README.md                             # this file        -> /agent/brain/voc-onboarding/
+  post-install.md                       # install announce -> /agent/brain/voc-onboarding/
+  voc-onboarding-walkthrough/SKILL.md   # -> /agent/.agents/skills/voc-onboarding-walkthrough/
+  voc-data-pull/                        # -> /agent/.agents/skills/voc-data-pull/
+    SKILL.md
+    references/platform-recipes.md
+    templates/{review,support-conversation,community-post,ad-comments-creative}.md
+  voc-audit/SKILL.md                    # -> /agent/.agents/skills/voc-audit/
+```
+
+Everything the package produces is workspace-scoped under `/agent/brain/<workspace>/`
+(name slugged from the conversation's `Default workspace:` line): raw items under
+`data-sources/voc/<platform>/`, the compiled audit beside them. A second workspace in the
+same org onboards additively; folders and routines never merge.
+
+## Install and run order
+
+1. **Install (manual, quiet).** An agent installs the package with one explicit install
+   call. Post-install announces the install and the trigger phrase — nothing else runs.
+   No guards are merged; the package never touches `/agent/user.md`.
+2. **A person triggers onboarding.** "Run voice of customer onboarding" invokes the
+   walkthrough skill: reachability, account pinning (human-confirmed; auto-pin only for
+   single-workspace orgs), routines created and kicked. The 12-month backfills run in the
+   background — data is never pulled inside the conversation.
+3. **Data lands; the summary and offer follow.** The first fully covered backfill sends
+   one asynchronous audit offer; invoking the walkthrough again presents the
+   per-integration summary and the same explained offer on demand. Both log
+   `voc-audit-offer` in the workspace changelog so nobody is offered twice by default.
+4. **The audit runs on a yes.** The `voc-audit` skill compiles the corpus into the
+   canonical audit page, honoring any requested additions and supplied reference docs.
+   Reruns are also manual and regenerate the same page — never dated duplicates.
+
+## Provenance and divergence
+
+Extracted from `meta-and-voc-onboarding` at commit `bce9619` (August 2026). `voc-audit/`
+and `voc-data-pull/` are byte-for-byte copies of that snapshot except for the
+substitutions below. The two packages do not track each other automatically: a fix landing
+in either package's copy of a shared file must be mirrored by hand.
+
+Substitutions (the complete list — everything else is verbatim):
+
+1. `voc-data-pull/SKILL.md`, "When to use," first bullet: the setup trigger names this
+   package's walkthrough skill instead of the `meta-and-voc-onboarding` install, and adds
+   "never at install" to the never-unprompted rule.
+2. The walkthrough skill is new (`voc-onboarding-walkthrough`, its own name so it can
+   never collide with the parent's `onboarding-walkthrough` at the skills root). Its setup
+   phase carries the parent's post-install steps 0–2 (workspace readout, reachability, VoC
+   sync setup) with install-turn phrasing adapted to invocation phrasing; its presentation
+   phase carries the parent walkthrough's VoC summary and audit-offer beats with the
+   Meta-sequencing preamble (account-context questions, Field 10) removed.
+3. `post-install.md` and `package.json` are new, written for the trigger-phrase model:
+   staged docs live under `/agent/brain/voc-onboarding/` instead of
+   `/agent/brain/meta-and-voc-onboarding/`.
+
+Deliberately absent, relative to the parent: all four guards (nothing here self-fires, so
+nothing needs `/agent/user.md`), the onboarded-workspace roster, the Account Context
+Brain, Creative Attributes, Meta Validation, Knoweth organize, the
+`meta-ad-performance-analysis` skill, and the Meta CLI/cache references.

voc-onboarding/package.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": 1,
+  "id": "voc-onboarding",
+  "name": "Voice of Customer Onboarding",
+  "version": "1",
+  "description": "INSTALLER: the moment this package installs, read /agent/brain/voc-onboarding/post-install.md and follow it - it announces the install and states the trigger phrase; nothing else runs at install time. The Voice of Customer onboarding package. Manual install only (installPolicy: manual): an agent installs it with one explicit package install call of its GitHub source. Stages this README and post-install.md into /agent/brain/voc-onboarding/, plus the voc-data-pull, voc-audit, and voc-onboarding-walkthrough skills into the skills root. The package is fully human-triggered: a person saying 'run voice of customer onboarding' (or any ask to begin, resume, or check on VoC onboarding) invokes the voc-onboarding-walkthrough skill, which resolves the workspace from the conversation's own Motion context, finds every reachable VoC platform (OAuth, stored key, or Motion native - a connected Meta workspace counts, since ad comments are customer voice), pins a human-confirmed platform account per workspace, creates one daily voc-sync-<workspace>-<platform> routine per reachable platform with the first run kicked (files land under /agent/brain/<workspace>/data-sources/voc/<platform>/), and, once data lands, presents the per-integration Voice of Customer summary and offers the Voice of Customer Audit by previewing its plan. The first complete backfill also offers the audit once, asynchronously. The audit runs only on a person's yes or explicit request and saves one compiled page at /agent/brain/<workspace>/data-sources/voc/voice-of-customer-audit.md. Outside those human-triggered runs, nothing self-runs - this package merges no guards and never touches /agent/user.md. One workspace at a time; everything it produces is scoped to that workspace's own folder, so a second workspace in the same org onboards additively without touching the first.",
+  "installPolicy": "manual",
+  "updatePolicy": "auto",
+  "uninstallPolicy": "allowed",
+  "resources": [
+    {
+      "id": "readme",
+      "type": "file",
+      "sourcePath": "README.md",
+      "executable": false,
+      "target": {
+        "root": "agent_brain",
+        "path": "voc-onboarding/README.md"
+      }
+    },
+    {
+      "id": "post-install",
+      "type": "file",
+      "sourcePath": "post-install.md",
+      "executable": false,
+      "target": {
+        "root": "agent_brain",
+        "path": "voc-onboarding/post-install.md"
+      }
+    },
+    {
+      "id": "voc-data-pull-skill",
+      "type": "directory",
+      "sourcePath": "voc-data-pull",
+      "executablePaths": [],
+      "target": {
+        "root": "agent_skills",
+        "path": "voc-data-pull"
+      }
+    },
+    {
+      "id": "voc-audit-skill",
+      "type": "directory",
+      "sourcePath": "voc-audit",
+      "executablePaths": [],
+      "target": {
+        "root": "agent_skills",
+        "path": "voc-audit"
+      }
+    },
+    {
+      "id": "voc-onboarding-walkthrough-skill",
+      "type": "file",
+      "sourcePath": "voc-onboarding-walkthrough/SKILL.md",
+      "executable": false,
+      "target": {
+        "root": "agent_skills",
+        "path": "voc-onboarding-walkthrough/SKILL.md"
+      }
+    }
+  ]
+}

voc-onboarding/post-install.md

@@ -0,0 +1,30 @@
+# Post-install: announce and wait
+
+Installing the voc-onboarding package stages files and does nothing else. There is no
+install-time sequence: no reachability checks, no routines, no pulls, no writes to
+`/agent/user.md`, no workspace resolution. Everything runs later, when a person asks.
+
+When this package's files land, close the installing turn with exactly this:
+
+> voc-onboarding - installed
+>
+> Say "run voice of customer onboarding" whenever you're ready and I'll find your
+> voice-of-customer integrations, set up the syncs, and take it from there.
+
+Nothing follows that line. The trigger phrase (or any ask to begin, resume, or check on
+Voice of Customer onboarding) invokes the `voc-onboarding-walkthrough` skill - that skill,
+and only that skill, owns the sequence: workspace resolution, reachability, account
+pinning, sync routine creation, the Voice of Customer summary, and the audit offer. The
+audit itself (`voc-audit` skill) runs only on a person's yes to that offer or an explicit
+request, and only after its data gate is met.
+
+What lands where, once the walkthrough runs:
+
+- Raw VoC items: `/agent/brain/<workspace>/data-sources/voc/<platform>/` (one file per
+  item; Meta ad comments one file per creative under `voc/meta-ad-comments/`).
+- The compiled audit (later, human-gated):
+  `/agent/brain/<workspace>/data-sources/voc/voice-of-customer-audit.md`.
+
+The README's "Install and run order" describes this same lifecycle for humans; this file,
+`post-install.md`, is the executable version. If the two ever disagree, fix them together -
+do not improvise.