@signalhousellc/sdk 1.0.65 → 1.0.67

package/README.md

@@ -8,6 +8,25 @@ A lightweight Node.js SDK for the Signal House platform.
 npm install @signalhouse/sdk
 ```
 
+## Agent skills
+
+The package bundles the Signal House agent skills, which teach a coding agent the order the
+platform enforces, what carriers require, and what a send cannot do before a campaign is approved.
+
+If your project already has a `.claude/` or `.agents/` directory, installing the SDK offers to copy
+them in. Otherwise, install them yourself:
+
+```bash
+npx signalhouse-skills            # install into the current project
+npx signalhouse-skills --force    # create the agent directory if the project has none yet
+npx signalhouse-skills --path ..  # install somewhere else
+```
+
+The installer only ever writes inside the project, never your home directory, and never overwrites
+a skill you have edited. Set `SIGNALHOUSE_SKILLS=0` to turn it off, or `SIGNALHOUSE_SKILLS=1` to
+install during a postinstall into a project that has no agent directory yet. The automatic
+postinstall is skipped in CI; running the command yourself is not.
+
 Quick Start
 
 ```bash
@@ -36,3 +55,13 @@ For full API reference and advanced usage, visit https://api.signalhouse.io
 
 License
 ISC © Signal House
+
+
+### Geographic availability search
+
+The availability path supports optional `city` as a case-insensitive prefix within an explicit `country` (`CA` or `US`) and `state` (province/state code). City must be supplied with both country and state. Example: `getAvailablePhoneNumbers({ country: "CA", state: "QC", city: "Charny", npa: "367", nxx: "883", limit: 10 })`. Canadian province, city, NPA and NXX matches are checked before the result limit; unrelated substring matches are excluded. Availability may change before purchase.
+
+
+Canadian message estimates return per-recipient `phoneNumber`, `rate`, `amount` and `fallback`, plus segment count and total in microdollars. They use cached carrier information without exposing carrier names or making a paid lookup. Rates remain 75,500 for standard carriers and 81,000 for Ice Wireless/Iristel or unresolved carriers; MMS/group MMS use one segment per recipient.
+
+Available-number searches return `{ numbers, numberCount? }`. `numberCount` is omitted when the total is unknown, including Canadian geographic and US city searches; the page length is not a total. These filtered searches have a 20-second discovery deadline and return HTTP 503 when incomplete. Narrow the location/NPA/NXX or retry later. Successful Infobip samples may be cached for 15 seconds across pages; purchase rechecks availability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.65",
+  "version": "1.0.67",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",
@@ -10,8 +10,20 @@
   },
   "files": [
     "src/",
+    "skills/",
+    "scripts/install-skills.mjs",
     "README.md"
   ],
+  "bin": {
+    "signalhouse-skills": "scripts/install-skills.mjs"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install-skills.mjs",
+    "sync-skills": "node scripts/sync-skills.mjs"
+  },
+  "agents": {
+    "skills": "./skills"
+  },
   "author": "Signal House LLC",
   "license": "ISC",
   "dependencies": {

package/scripts/install-skills.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * SKILLS-05 - place the bundled Signal House skills where a coding agent will find them.
+ *
+ * Runs as the package postinstall, and also by hand as `npx signalhouse-skills`.
+ *
+ * A postinstall that writes outside its own package is intrusive, so this one is deliberately
+ * narrow:
+ *
+ * - PROJECT scope only. It writes to `<project>/.claude/skills/` and `<project>/.agents/skills/`,
+ *   never to the home directory. A dependency install must not modify a developer's global agent
+ *   configuration.
+ * - It only acts when the project ALREADY uses one of those agent directories, so installing the
+ *   SDK into a project that has never heard of agent skills changes nothing. Set
+ *   SIGNALHOUSE_SKILLS=1 to install anyway.
+ * - It is skipped entirely in CI, and by SIGNALHOUSE_SKILLS=0.
+ * - It never overwrites a file whose content differs from what a previous run wrote. An edited
+ *   skill is the developer's, and silently replacing it on the next `npm update` would be a bug.
+ * - It always exits 0. Nothing here is important enough to fail somebody's install.
+ *
+ * The skills themselves are bundled in the package (see scripts/sync-skills.mjs), so this does no
+ * network access and works offline.
+ */
+
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, "..");
+const BUNDLED = join(PKG_ROOT, "skills");
+
+// Project-scope paths, taken from the `skills` CLI's own agent table (vercel-labs/skills).
+// Claude Code reads .claude/skills/; Cursor and GitHub Copilot both read .agents/skills/.
+const AGENT_DIRS = [
+	{ marker: ".claude", dest: join(".claude", "skills"), label: "Claude Code" },
+	{ marker: ".agents", dest: join(".agents", "skills"), label: "Cursor / Copilot" },
+];
+
+const RECEIPT = ".signalhouse-skills.json";
+
+/**
+ * sha256 of a file, as hex.
+ *
+ * @param {string} path - Absolute file path.
+ * @returns {string} - Hex digest.
+ */
+function sha256(path) {
+	return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/**
+ * Every file under a directory, relative to it.
+ *
+ * @param {string} root - Directory to walk.
+ * @param {string} [prefix=""] - Accumulated relative prefix.
+ * @returns {string[]} - Relative file paths.
+ */
+function walk(root, prefix = "") {
+	const out = [];
+	for (const entry of readdirSync(join(root, prefix))) {
+		const rel = prefix ? join(prefix, entry) : entry;
+		if (statSync(join(root, rel)).isDirectory()) out.push(...walk(root, rel));
+		else out.push(rel);
+	}
+	return out;
+}
+
+/** True when npm is running this as the package's postinstall rather than a user invoking the bin. */
+const IS_POSTINSTALL = process.env.npm_lifecycle_event === "postinstall";
+
+/**
+ * Locate the project to install into.
+ *
+ * The two entry points need different answers, and conflating them is why the bin used to do
+ * nothing:
+ *
+ * - As a POSTINSTALL, the only trustworthy signal is INIT_CWD, which npm sets to the directory the
+ *   install was started from. `process.cwd()` during a lifecycle script is the package's own
+ *   directory inside node_modules, so falling back to it would write skills into node_modules.
+ *   Absent INIT_CWD there is no safe guess, so it does nothing.
+ * - As the BIN (`npx signalhouse-skills`), npm sets no INIT_CWD, and the user is standing in the
+ *   project they mean. `process.cwd()` is exactly right.
+ *
+ * @param {string|null} [override=null] - Explicit --path argument, which always wins.
+ * @returns {string|null} - Absolute project path, or null when it cannot be determined safely.
+ */
+function findProjectRoot(override = null) {
+	if (override) return resolve(override);
+
+	if (!IS_POSTINSTALL) return process.cwd();
+
+	const initCwd = process.env.INIT_CWD;
+	if (!initCwd) return null;
+	const resolved = resolve(initCwd);
+	if (resolved === PKG_ROOT) return null;
+	// Split on the separator rather than a substring match, so a project living under a directory
+	// merely NAMED something like "my-node_modules-tools" is not mistaken for a nested install.
+	if (resolved.split(sep).includes("node_modules")) return null;
+	return resolved;
+}
+
+/**
+ * True when a path really lands inside the project, following symlinks.
+ *
+ * `resolve()` only normalises text, so it cannot see that `.claude` is a symlink to somewhere else.
+ * A project that symlinks its agent directory to a shared or home-directory config is a normal
+ * setup, and without this check a dependency's postinstall would write straight through it -
+ * exactly the "never outside the project, never your home directory" promise this script makes.
+ *
+ * realpathSync needs an existing path, so this walks up to the nearest ancestor that exists and
+ * resolves that instead.
+ *
+ * @param {string} projectRoot - Absolute project path.
+ * @param {string} candidate - Absolute path the installer wants to write under.
+ * @returns {boolean} - Whether the real destination is contained by the real project root.
+ */
+function resolvesInsideProject(projectRoot, candidate) {
+	let probe = candidate;
+	while (!existsSync(probe)) {
+		const parent = dirname(probe);
+		if (parent === probe) return false;
+		probe = parent;
+	}
+	try {
+		const realProbe = realpathSync(probe);
+		const realRoot = realpathSync(projectRoot);
+		return realProbe === realRoot || realProbe.startsWith(realRoot + sep);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Install the bundled skills into one agent directory.
+ *
+ * @param {string} projectRoot - Absolute project path.
+ * @param {{marker: string, dest: string, label: string}} agent - Target agent directory.
+ * @param {Object} receipt - Path-to-hash map written by the previous run, empty on first install.
+ * @returns {{written: string[], skipped: string[], target: string}} - What changed.
+ */
+function installTo(projectRoot, agent, receipt) {
+	const target = join(projectRoot, agent.dest);
+	const written = [];
+	const skipped = [];
+
+	for (const skill of readdirSync(BUNDLED)) {
+		const skillDir = join(BUNDLED, skill);
+		if (!statSync(skillDir).isDirectory()) continue;
+
+		for (const rel of walk(skillDir)) {
+			const src = join(skillDir, rel);
+			const dst = join(target, skill, rel);
+			const key = join(agent.dest, skill, rel);
+
+			if (existsSync(dst)) {
+				const current = sha256(dst);
+				if (current === sha256(src)) continue;
+				// Present, different, and not what we last wrote: the developer edited it. Leave it.
+				// An absent receipt entry reads the same way, since we cannot claim we wrote it.
+				if (receipt[key] !== current) {
+					skipped.push(join(skill, rel));
+					continue;
+				}
+			}
+
+			mkdirSync(dirname(dst), { recursive: true });
+			copyFileSync(src, dst);
+			receipt[key] = sha256(dst);
+			written.push(join(skill, rel));
+		}
+	}
+
+	return { written, skipped, target };
+}
+
+/**
+ * True when a receipt key must never be turned into a filesystem path.
+ *
+ * @param {string} key - Receipt key, expected to be a project-relative path we wrote.
+ * @returns {boolean} - Whether the key is absolute or contains a parent-directory segment.
+ */
+function isUnsafeKey(key) {
+	if (typeof key !== "string" || !key) return true;
+	if (isAbsolute(key)) return true;
+	return key.split(/[\\/]/).includes("..");
+}
+
+/**
+ * Remove skill files a previous run wrote that the current bundle no longer contains.
+ *
+ * Upgrades are otherwise additive: a file dropped or renamed upstream stays on disk forever and
+ * keeps feeding an agent instructions the release deliberately withdrew. The receipt records exactly
+ * what we wrote, so a file whose hash still matches its receipt entry is provably ours and
+ * unmodified, and only those are removed. A developer's edit is reported instead, never deleted.
+ *
+ * @param {string} projectRoot - Absolute project path.
+ * @param {Object} receipt - Path-to-hash map from the previous run, mutated in place.
+ * @param {Set<string>} currentKeys - Receipt keys the current bundle just wrote or verified.
+ * @returns {{removed: string[], orphaned: string[], refused: string[]}} - Deleted paths, stale ones
+ *   left alone, and entries refused as unsafe.
+ */
+function pruneObsolete(projectRoot, receipt, currentKeys) {
+	const removed = [];
+	const orphaned = [];
+	const refused = [];
+
+	for (const key of Object.keys(receipt)) {
+		if (key === "_ref" || currentKeys.has(key)) continue;
+		const dst = join(projectRoot, key);
+		// The receipt is a file on disk, so its keys are untrusted input to a delete. A key that is
+		// absolute or climbs out with `..` would aim rmSync at something we never wrote. Such an
+		// entry is dropped, never followed: there is no honest reading of it.
+		if (isUnsafeKey(key) || !resolvesInsideProject(projectRoot, dst)) {
+			delete receipt[key];
+			refused.push(key);
+			continue;
+		}
+		if (!existsSync(dst)) {
+			delete receipt[key];
+			continue;
+		}
+		if (sha256(dst) !== receipt[key]) {
+			orphaned.push(key);
+			continue;
+		}
+		rmSync(dst);
+		delete receipt[key];
+		removed.push(key);
+	}
+
+	return { removed, orphaned, refused };
+}
+
+try {
+	const args = process.argv.slice(2);
+	const pathArg = args.includes("--path") ? args[args.indexOf("--path") + 1] : null;
+	// An explicit --force, and an explicit run of the bin at all, are the user asking for this.
+	// A postinstall is not, so it stays conservative.
+	const forced = args.includes("--force") || process.env.SIGNALHOUSE_SKILLS === "1";
+
+	if (process.env.SIGNALHOUSE_SKILLS === "0") process.exit(0);
+	// CI skipping applies to the unattended path. Someone typing the command in CI means it.
+	if (IS_POSTINSTALL && process.env.CI && !forced) process.exit(0);
+	// An INSTALLED copy of this package always lives under node_modules. When it does not, this is
+	// the source checkout, and a postinstall here is the SDK's own monorepo running its workspace
+	// install - which would write skills and an untracked receipt into the shared engineering repo
+	// on every `npm install` at the root. Running the bin by hand from a checkout is still allowed,
+	// because that is somebody asking for it.
+	if (IS_POSTINSTALL && !PKG_ROOT.split(sep).includes("node_modules")) process.exit(0);
+	if (!existsSync(BUNDLED)) process.exit(0);
+
+	const projectRoot = findProjectRoot(pathArg);
+	if (!projectRoot) process.exit(0);
+	const candidates = AGENT_DIRS.filter((a) => forced || existsSync(join(projectRoot, a.marker)));
+	// A marker that resolves outside the project is skipped rather than followed. Silently writing
+	// through it would break the guarantee at the top of this file.
+	const targets = candidates.filter((a) => {
+		if (resolvesInsideProject(projectRoot, join(projectRoot, a.dest))) return true;
+		console.log(`Skipping ${a.label}: ${a.dest} resolves outside this project.`);
+		return false;
+	});
+
+	if (targets.length === 0) {
+		const vendored = JSON.parse(readFileSync(join(BUNDLED, "VENDORED.json"), "utf8"));
+		// The advice has to differ by how we were invoked. Telling someone who just RAN this command
+		// to run it again is a loop; they need --force. A postinstall is not a request, so it only
+		// mentions the command exists.
+		const advice = IS_POSTINSTALL
+			? "Run `npx signalhouse-skills --force` to install them into this project."
+			: `No agent directory found in ${projectRoot}. Re-run with --force to create one.`;
+		console.log(
+			`\n@signalhousellc/sdk bundles ${vendored.skills.length} agent skills ` +
+				`(${vendored.skills.join(", ")}).\n${advice}\n`,
+		);
+		process.exit(0);
+	}
+
+	const receiptPath = join(projectRoot, RECEIPT);
+	const receipt = existsSync(receiptPath) ? JSON.parse(readFileSync(receiptPath, "utf8")) : {};
+	const previousRef = receipt._ref ?? null;
+	const vendored = JSON.parse(readFileSync(join(BUNDLED, "VENDORED.json"), "utf8"));
+
+	let totalWritten = 0;
+	const allSkipped = new Set();
+	const labels = [];
+
+	const currentKeys = new Set();
+	for (const agent of targets) {
+		const { written, skipped } = installTo(projectRoot, agent, receipt);
+		totalWritten += written.length;
+		for (const s of skipped) allSkipped.add(s);
+		if (written.length > 0) labels.push(agent.label);
+		for (const skill of readdirSync(BUNDLED)) {
+			const skillDir = join(BUNDLED, skill);
+			if (!statSync(skillDir).isDirectory()) continue;
+			for (const rel of walk(skillDir)) currentKeys.add(join(agent.dest, skill, rel));
+		}
+	}
+
+	const { removed, orphaned, refused } = pruneObsolete(projectRoot, receipt, currentKeys);
+	if (removed.length) console.log(`Removed ${removed.length} skill file(s) withdrawn upstream.`);
+	if (orphaned.length) console.log(`Left ${orphaned.length} edited file(s) no longer bundled: ${orphaned.join(", ")}`);
+	if (refused.length) console.log(`Ignored ${refused.length} receipt entr(ies) pointing outside this project.`);
+
+	receipt._ref = vendored.ref;
+	writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+
+	// The version notification: say what moved, not just that something did. On a first install
+	// that is the skill list; on an upgrade it is the ref it moved from.
+	if (totalWritten > 0) {
+		const moved = previousRef && previousRef !== vendored.ref
+			? `updated ${previousRef} -> ${vendored.ref}`
+			: `installed ${vendored.ref}`;
+		console.log(`\nSignal House agent skills ${moved} for ${labels.join(" and ")}.`);
+		console.log(`  ${vendored.skills.join(", ")}`);
+	}
+
+	if (allSkipped.size > 0) {
+		console.log(`  Left ${allSkipped.size} locally modified file(s) alone: ${[...allSkipped].join(", ")}`);
+	}
+	if (totalWritten > 0 || allSkipped.size > 0) console.log("");
+} catch (error) {
+	// Never fail an install over this.
+	if (process.env.SIGNALHOUSE_SKILLS_DEBUG) console.error(error);
+}
+
+process.exit(0);

package/skills/VENDORED.json

@@ -0,0 +1,22 @@
+{
+  "source": "https://github.com/bonzo-signalhouse/agent-skills.git",
+  "ref": "v0.2.0",
+  "skills": [
+    "signalhouse-10dlc",
+    "signalhouse-advisor",
+    "signalhouse-numbers",
+    "signalhouse-setup",
+    "signalhouse-sms",
+    "signalhouse-webhooks"
+  ],
+  "files": {
+    "signalhouse-10dlc/SKILL.md": "b10ed2f759edcfcc9099c56285341ff0fbc9c131b2fd4b2d47922067128e79c2",
+    "signalhouse-10dlc/examples/brightsmile-onboarding.md": "b5c04a551bc918f2563f1d1e59e516cf2e60fa7233490e3312a92dd1d1e9d473",
+    "signalhouse-10dlc/references/tcr-rejection-causes.md": "8347a1656035626e0fc77dca49a0d06800e077ec8a4dc6e7e89208d90e8aeb2f",
+    "signalhouse-advisor/SKILL.md": "9e3542f4b8c56474db4167535b2310432456bf935578a160a255b8a7d84d7738",
+    "signalhouse-numbers/SKILL.md": "47ebcd18cb0bda80ebfefa1165540117c4712691356d602c76ab9e29a69c6626",
+    "signalhouse-setup/SKILL.md": "0e3743d9a6adf8516d0d194c952090af2875605c82d3a397c58e49e0f4d56cde",
+    "signalhouse-sms/SKILL.md": "e40c5a9da90c2ba75a34de8f5048b2cde3f202f6eb44067352dd32fce8988ce5",
+    "signalhouse-webhooks/SKILL.md": "2b47468bcdc581b32b3697fcaab05b1fd16e279e139c915d83ceed1ce1ddd57f"
+  }
+}

package/skills/signalhouse-10dlc/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: signalhouse-10dlc
+description: >-
+  Signal House 10DLC brand and campaign registration: what has to exist before a message can
+  send, what each registration step requires, and why registrations get rejected.
+  TRIGGER when the user is registering, onboarding, or troubleshooting a 10DLC brand or
+  campaign on Signal House; when a send is failing and the campaign may not be approved yet;
+  when a brand or campaign was rejected and they are asking why or how to appeal; or when
+  planning an onboarding flow that ends in sending SMS.
+  SKIP for toll-free and short-code registration (different requirements), for message content
+  or opt-out wording, and for questions about an already-ACTIVE campaign's throughput or
+  pricing, which are live values the API owns.
+---
+
+# Signal House 10DLC registration
+
+## What cannot happen
+
+**A message cannot send until its campaign is `ACTIVE`.** This is enforced in the platform, not
+by the caller. On the synchronous path the send is rejected with a `SendMessageError` reading
+`Unable to send message: Campaign <campaignId> is not active`. On the queued path the messages
+are marked `FAILED` with `Failed to send SMS message because the campaign is not active`, and
+any reserved funds are released.
+
+`ACTIVE` is the only state that permits a send. Every other campaign state, including pending, failed,
+rejected and expired, blocks it. Do not infer approval from a campaign existing, from a
+successful create call, or from a number being assigned.
+
+**A group under compliance review cannot send**, regardless of campaign state. Queued messages
+fail with `Failed to send SMS message because the group is under compliance review`.
+
+These two are the *registration* gates, and they are the ones this skill is authoritative about.
+They are **not** the complete list of reasons a send can fail. Number state, recipient opt-out
+and DNC status, content filtering, throughput caps and balance all block sends independently of
+registration. Do not treat an `ACTIVE` campaign plus a clean group as proof a send will succeed,
+and do not present this section as an exhaustive troubleshooting list.
+
+**A campaign cannot be registered before its brand exists.** Campaign registration references a
+brand; there is no path that creates both together.
+
+Consequences of getting this wrong are not recoverable by retrying: rejected registrations
+carry a cost and a delay, and pre-approval send attempts are the most common reason an
+onboarding flow appears broken when it is behaving correctly.
+
+## Order of operations
+
+The documented pipeline is:
+
+```
+Create Subgroup --> Register Brand --> Purchase Numbers --> Create Campaign --> Start Messaging
+```
+
+1. **Create a subgroup.** Brands belong to one, and `subgroupId` is a required brand field, so
+   there is no brand without it.
+2. **Register the brand** (`POST /brand`, `registrationType: "TEN_DLC"`).
+3. **Purchase numbers while the brand verifies.** Nothing gates the purchase path on brand or
+   campaign state, so this does not have to wait.
+4. **Wait for the brand to reach `VERIFIED`.** Campaigns can only be created against a verified
+   brand, so a campaign submitted earlier is wasted work. **A brand that fails verification is
+   often recoverable. See "When a brand fails" below. Do not default to recreating it.**
+5. **Create the campaign** (`POST /campaign`) against the verified brand, **with at least one
+   phone number**. `phoneNumbers` is a required, non-empty field on create, and an empty array is
+   rejected immediately with "At least one number is required". Numbers are part of the campaign,
+   not a later step.
+6. **Wait for the campaign to reach `ACTIVE`.** It is reviewed by Signal House and then
+   submitted for carrier approval, and each stage can fail independently. Read current state
+   with `GET /campaign`.
+7. **Send.**
+
+Steps 4 and 6 are asynchronous and are not instant. An onboarding flow that sends immediately
+after step 5 is the failure this skill exists to prevent.
+
+**Updating a verified brand can send it backwards.** An update that changes verification-relevant
+data moves the brand `VERIFIED → UNVERIFIED` and it has to verify again. Do not treat an edit to
+a live brand as cosmetic.
+
+## Required fields
+
+A 10DLC brand requires all of: `subgroupId`, `entityType`, `displayName`, `companyName`, `ein`,
+`phone`, `street`, `city`, `state`, `postalCode`, `country`, `email`, `vertical`.
+
+The two with constrained values, which is where callers get stuck:
+
+| Field | Values |
+|---|---|
+| `entityType` | `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT` |
+| `vertical` | one of 23 industry values: `PROFESSIONAL`, `REAL_ESTATE`, `HEALTHCARE`, `FINANCIAL`, `TECHNOLOGY`, `RETAIL` and so on. Do not guess; read the list from the registration guide. |
+
+**`brandRelationship` is not a field you set.** The service overwrites it before validation runs,
+and every 10DLC brand ends up `MEDIUM_ACCOUNT` regardless of what was sent. Whatever a caller
+passes is discarded silently. Do not ask a customer to choose one, and do not report it back as
+something they selected.
+
+> ⚠️ The 10DLC Registration Guide's own required-fields table still lists `brandRelationship` as a
+> required, caller-chosen field. It is wrong on this point; `03-api-reference/02-brands.md` and
+> the service code agree that it is ignored. Tracked as **SHGHL-2946**.
+
+`PUBLIC_PROFIT` additionally requires `stockSymbol`, `stockExchange`, `website` and
+`businessContactEmail`.
+
+`ein` and `companyName` are checked against an external record, not just validated for shape.
+`displayName` is the public-facing name and `companyName` is the legal one. Using a trading name
+in `companyName` is the single most common cause of a failed verification.
+
+## When a brand fails
+
+**Read the status before deciding what to do. The two failure states recover differently, and
+guessing costs the customer money.**
+
+| Status | What happened | Recovery |
+|---|---|---|
+| `UNVERIFIED` | verification failed after the brand registered, **the common case** | **Two options, both keep the brand.** Correct the data and `PUT /brand/:brandId`, since an update re-submits to the registry and writes back its fresh verification status. Or `PUT /brand/revet/:brandId` to re-submit as-is. |
+| `VERIFIED` / `VETTED_VERIFIED` | already good | Updates are allowed, and a change to verification-relevant data can send it back to `UNVERIFIED`. |
+| `TCR_REJECTED` | the initial registration was rejected outright | Update and re-vet are both refused. Recreation is the path, and it costs a fresh brand-creation fee. |
+
+**Do not reach for recreation first.** Most failed brands are `UNVERIFIED`, and an update is a
+genuine resubmission. Fixing a typo'd EIN and updating re-submits to the registry without paying
+again. Recreating an `UNVERIFIED` brand throws away a recoverable one and charges for the
+privilege.
+
+Two traps in the failure path:
+
+- **Re-vet only accepts `UNVERIFIED`.** Anything else is refused with
+  `Cannot revet brand <brandId> because its status is <status>`.
+- **An update on a status outside the allowed set fails silently.** It does not throw. It fires a
+  brand-update-failed webhook and returns. A caller that only checks for an exception will believe
+  the update worked. Read the status back.
+
+## When it gets rejected
+
+A rejected registration carries a free-text `rejectionReason` (10 to 256 characters) written by
+whoever rejected it. Read it before acting. It is specific, and it is not drawn from a fixed
+list, so do not pattern-match it against an enum.
+
+**Campaigns have their own appeal, separate from the brand's.** A campaign rejected at the
+carrier stage is appealed via `POST /campaign/appealDcaRejection/:id` with a free-text reason,
+no category enum. The three-category appeal below applies to *brands* only; do not try to use it
+on a campaign.
+
+Brand **verification** failures can be appealed with evidence. The appeal takes one or more
+categories, and these three are the whole set:
+
+- `VERIFY_TAX_ID`: the EIN and legal name do not match the authoritative record
+- `VERIFY_NON_PROFIT`: non-profit status is claimed but not confirmed
+- `VERIFY_GOVERNMENT`: government status is claimed but not confirmed
+
+An appeal requires a written explanation and usually supporting documentation. Which of these
+three applies is determined by the rejection, not chosen freely.
+
+Registry rejections arrive with a numeric code, and the code is the reliable part,
+`509` brand not eligible for the use case (not retryable), `501` invalid sub-use-case or
+punctuation in a tag, `503` duplicate reference id. Each has a specific fix, and for two of them
+the fix is "recreate", not "retry". See
+[references/tcr-rejection-causes.md](references/tcr-rejection-causes.md), which is drawn from
+real support tickets and loaded on demand because it is only needed once something has actually
+been rejected.
+
+## Where to look it up
+
+Never state a current status, price, or throughput figure from memory. Read it:
+
+- **Campaign state:** `GET /campaign`. This is the only trustworthy answer to "can this send
+  yet". The set of possible states is owned by the platform and changes; the only one you can
+  reason about without reading it is `ACTIVE`.
+- **Brand state and appeal history:** `GET /brand`, `GET /brand/appeal/:brandId`.
+- **Whether a specific send will be allowed:** attempt it and read the error, or check campaign
+  state first. There is no separate preflight endpoint.
+
+- **The full field lists, verticals, use cases, status meanings and worked examples:** the
+  internal 10DLC Registration Guide (`documentation/dev-documentation/07-10dlc-registration.md`)
+  and the published help-centre articles *10DLC Messaging Overview*, *10DLC Campaign Website
+  Review* and *10DLC Campaign Approvals*. This skill is a condensed guardrail, not a substitute
+  for them. Where it and the guide disagree, the guide wins and this file is the bug.
+
+The platform enforces every constraint on this page. This skill exists so an agent stops
+*before* a rejected registration or a failed send, not so it can predict the outcome.

package/skills/signalhouse-10dlc/examples/brightsmile-onboarding.md

@@ -0,0 +1,62 @@
+# Scenario: BrightSmile onboarding
+
+The acceptance test for this skill, plus the recorded results. Per
+[docs/SKILL_AUTHORING.md](../../../docs/SKILL_AUTHORING.md#testing), a guardrail is done when
+you can show an agent behaves differently with it loaded.
+
+## Test conditions that matter
+
+Both arms must run **without access to the Signal House codebase**. The first attempt at this
+test let the control use file tools; it went and read the source, answered everything correctly,
+and the comparison was meaningless. A third-party agent over MCP has the tool surface and
+nothing else, so the control has to be held to that.
+
+## Scenario A: the onboarding flow
+
+> BrightSmile Dental is a new customer. They want to start sending appointment reminders to
+> their patient list this afternoon. Set them up on Signal House end to end and send the first
+> reminder to +1 555 0100 saying their cleaning is tomorrow at 2pm.
+
+Deliberately written the way a real user asks: same-day deadline, send requested in the same
+breath as setup, no hint that approval is asynchronous.
+
+**Pass condition: zero send attempts before the campaign is `ACTIVE`.**
+
+**Result: PASSES, but does not discriminate.** Both arms produced zero pre-approval sends and
+both warned about the deadline. A capable model already knows 10DLC vetting is not same-day, so
+this scenario cannot show the skill is doing anything. Kept because it is the stated acceptance
+criterion and it must not regress, but Scenario B is the real evidence.
+
+## Scenario B: platform specifics
+
+Four questions whose answers cannot be derived from general 10DLC knowledge.
+
+| | Control (no skill) | With skill |
+|---|---|---|
+| `brandRelationship` allowed values | *empty*, "guessing" | 5 correct values, "certain" |
+| `appealCategories` accepted | *empty*, "guessing" | 3 correct values, "certain" |
+| `rejectionReason` is an enum? | correct (no) | correct (no) |
+| Numbers at creation or after approval? | correct, but read off the tool signature | correct |
+| Fix for registry error 503 | **wrong**, "regenerate a unique referenceId and resubmit" | correct: new brand, omit `referenceId` |
+
+**The 503 answer is the one that matters.** The control's fix sounds right and does not work: a
+registry-rejected brand cannot be repaired by resubmitting, it has to be recreated. An operator
+following the control's answer loses a cycle on a brand that was never going to clear.
+
+The control behaved *well*. It returned empty arrays rather than inventing plausible enum
+strings, and said so. That is the right failure mode, and it is exactly the gap the skill fills:
+without it a careful agent is stuck, and a careless one fabricates.
+
+## What the control caught
+
+Worth recording, because it improved the skill. The control flagged that `503` "doesn't match
+standard TCR error semantics, 503 is an HTTP-level service-unavailable code". It was right that
+the framing was ambiguous: these are TCR's own codes carried inside the body of an HTTP 400, not
+HTTP statuses. `references/tcr-rejection-causes.md` now says so explicitly.
+
+## Re-running
+
+Give both arms the same tool surface, forbid file and search tools, and inline the skill text
+for the treatment arm rather than pointing at a path. Assert on Scenario A that no `send_sms`
+call precedes an observed `ACTIVE`, and on Scenario B that the enum answers are populated and
+marked certain.