@drawbridge/drawbridge-agents 0.1.51 → 0.1.55

package/.claude-template/skills/drawbridge-add-connection/SKILL.md

@@ -1,45 +1,47 @@
 ---
 name: drawbridge-add-connection
-description: Use when adding a new vendor connection (a new manifest in drawbridge-utils) — runs the auth-type assessment FIRST so the integration is built the way the vendor's own docs recommend, then walks the build against the documented checklist and its guards.
+description: Use when adding a vendor connection (a new manifest in drawbridge-utils), changing one's auth type or scopes, or adding a hook, link, or step to an existing manifest — and when asked to check an existing connection against the connection checklist.
 ---
 
 # Add a connection
 
-A connection is one manifest file in `drawbridge-utils/lib/connections/`, and the
-build half is documented — `drawbridge-docs/reference/connection-hooks.md`,
-"Adding a connection". This skill exists for what comes BEFORE the file: deciding
-what kind of connection to build, from the vendor's documentation rather than
-from whichever auth mechanism is easiest to wire.
+A connection is one manifest in `drawbridge-utils/lib/connections/providers/`.
+The manifest is the only place vendor facts live, and it carries its own
+proof: a `review` key the contract test refuses to accept incomplete. This
+skill is the order of work that fills it honestly.
 
-The failure it prevents is real: Attentive was first built as pasted API keys
-because keys worked, and their docs turned out to frame private-app keys as
-"integrate your own account" — the public OAuth app was the documented path for
-platforms like Drawbridge. The rebuild cost an afternoon; the assessment costs
-ten minutes.
-
-## When to use
-
-Any new vendor manifest, and any auth-type change to an existing one (keys →
-OAuth is a rebuild of the auth surface, not a tweak).
+**A manifest ships complete: every hook the vendor can serve, every link the
+dashboard exposes, every scope those need, copy humanized, walked on dev.
+Nothing is deferred for a deadline. Darren, 2026-09-11: "Don't skip shit, do
+this right, our production launch deadline is somewhat flexible." If the work
+does not fit the time, the time moves.**
 
 ## Steps
 
-1. **Fetch the vendor's developer docs and answer these in writing, with the
-   URL of the page that answers each.** Never from memory — the Klaviyo consent
-   url was once written from memory, pointed at their API host, and stalled
+1. **Read the vendor twice, and write down where.** Fetch, never recall — a
+   consent url once written from memory pointed at the api host and stalled
    every merchant on a blank page.
-
-   - What auth mechanisms exist, and **who does the vendor say each is for**?
-     The distinction that matters is *your own account* versus *accounts outside
-     your organization*. Drawbridge is always the second: merchants connect
-     THEIR account to OUR platform.
-   - Is there a partner / public-app / marketplace program? What does
-     registration take, and what credentials does it issue?
-   - For OAuth: authorize url, token url, how client credentials are sent
-     (form fields vs Basic header), whether PKCE is required, token lifetime,
-     whether refresh tokens exist, scope names.
-
-2. **Pick the `auth.type` from the answers, not from convenience:**
+   - **API reference**: auth mechanisms and who the vendor says each is for
+     (your own account vs accounts outside your organization — Drawbridge is
+     always the second), partner or public-app program, OAuth urls and
+     transport, token lifetime, refresh, every endpoint a hook will call.
+   - **Dashboard docs** (help centre, app UI): the page url for each object
+     we will hold an id for (list, segment, tag, contact, order), where the
+     vendor says the id appears, what the vendor calls each thing, and what a
+     disconnect actually does on their side. This read fills `urls.*` and the
+     merchant copy. A vendor whose UI urls are not documented gets an
+     observed form, marked observed, confirmed on dev before promote.
+   `review.api` and `review.dashboard` take the urls read.
+
+2. **Scope for the whole manifest, not today's hooks.** List every scope the
+   vendor offers with its url in `review.scopes`, then request every scope any
+   hook in the contract could need for this vendor — contacts, segments,
+   tags, custom fields, lists, webhooks — whether or not that hook ships
+   now. Scopes are app-level at Klaviyo and Attentive: adding one later costs
+   every connected merchant a re-consent. "Minimum for what I built today" is
+   the wrong minimum.
+
+3. **Pick `auth.type` from the vendor's own framing:**
 
    | vendor's shape | type |
    |---|---|
@@ -48,32 +50,53 @@ OAuth is a rebuild of the auth surface, not a tweak).
    | the vendor offers ONLY per-account credentials | `keys` |
    | no third party behind it at all | `generated` |
 
-   `keys` when OAuth exists is a decision someone must make out loud — usually
-   as an explicitly-flagged interim while a partner registration is pending, and
-   the manifest header says so.
-
-3. **If the app is not yet registered, build it dormant.** `requires` names the
-   client env vars that will exist after registration; until they land on a
-   deployment, the connection is offered nowhere. Shipping the manifest complete
-   and inert beats waiting — adding the env vars becomes the launch.
-
-4. **Record the assessment in the manifest header**: every cited fact, every
-   contradiction between the vendor's own pages (cite both and say which one the
-   code models), and — for OAuth — the questions only a live registration
-   answers: does consent echo `state` back, what is the real token lifetime,
-   does one app accept both environments' redirect urls.
-
-5. **Build against the checklist** in
-   `drawbridge-docs/reference/connection-hooks.md` → "Adding a connection". Its
-   guards are the enforcement: the directory-registration test, the
-   feature-grant test, `build()` itself. Trust the named failures over your
+   `keys` is only for a vendor that offers nothing else to third parties.
+   Where OAuth exists, build OAuth; a registration that has not landed ships
+   the manifest dormant (`requires` names the client vars), never as keys.
+
+4. **Implement every hook the vendor can serve.** The only `false` is "the
+   vendor has no endpoint for this", with the one-line reason and the page
+   that shows the absence. Time is never a reason. "Flip later" is how segment
+   labels shipped as tags with no id kept. Every `urls` entry the dashboard
+   read found is implemented too.
+
+5. **Write the merchant copy from the two reads, then run the humanizer.**
+   Excerpt, description, guide, confirm, error copy: the vendor's own names
+   for things, the guide's navigation path from the help centre, and what
+   disconnect really does. Then invoke `humanizer:humanizer` on the copy
+   before commit and put the date in `review.content`. Not "if time".
+
+6. **Build against the checklist** in
+   `drawbridge-docs/reference/connection-hooks.md` → "Adding a connection".
+   Its guards are the enforcement: directory registration, feature grant,
+   `build()`, the `review` contract test. Trust a named failure over your
    memory of the steps.
 
+7. **Walk it on dev, then date `review.verified`.** Connect a real account,
+   pick the resource, sync one contact and one opted-out contact, open each
+   `urls.*` link. `verified` is `null` on the publish that first carries the
+   manifest (the walk needs it deployed) and dated on the next; a manifest
+   still `null` at promote does not promote. A green suite is not the walk.
+
+## Checking an existing connection
+
+Same steps, read as questions: is each `review` entry a real url or date, do
+the requested scopes cover every hook the contract lists, does each `urls.*`
+entry exist and open, was the copy humanized. A gap is a manifest fix, not a
+note.
+
+## Red flags — stop
+
+- "Minimum scopes for now" — re-consent for every merchant later.
+- "Help centre only for the guide" — `urls.*` will be empty.
+- "Humanizer if time" — it is a step with a date, not a polish.
+- "Verified in the header comment" — `review.verified` is the record.
+- "Flip that hook later", "skipped because of the deadline" — nothing is
+  skipped. Say the time is short and keep going.
+- "Keys as an interim, OAuth after the demo" — the OAuth build is the work.
+
 ## Notes
 
-- The manifest is the only place vendor facts live. If the assessment finds a
-  fact that must hold across repos, record it with `drawbridge-record-contract`.
-- The picker/search question is part of the assessment: if the vendor's list
-  endpoint filters by name server-side, the field must NOT declare
-  `search : false` — Attentive was the first vendor that could, and a test pins
-  that it stays searchable.
+- A fact that must hold across repos goes through `drawbridge-record-contract`.
+- If the vendor's list endpoint filters by name server-side, the field must
+  NOT declare `search : false`; a test pins that for Attentive.

package/conventions/cross-repo-contracts.md

@@ -68,13 +68,27 @@ skill) so it stops living only in tribal memory.
   `lib/suppression.js canSend()` — a new lead-facing send path must call it, or opted-out
   recipients get contacted (TCPA/CAN-SPAM exposure). Lead-facing = the notification carries
   `lead`/`workflow`/`connection`; those sends also REQUIRE an org connection (no system-sender
-  fallback), while org-less system mail (OTC codes, member invites, security notices) keeps the
-  system sender and is never suppressed. Inbound STOP flows webhooks
+  fallback), while system mail (OTC codes, member invites, security notices) keeps the system
+  sender and is never suppressed. **System mail is identified by `audience`, not by whether an
+  organization is present** — `queue/identity.js` sends member mail WITH an org, and
+  `stream/transaction.js` sends AI-balance notices with none. Inbound STOP flows webhooks
   (`POST /connection/:id/twilio`, signature-verified against the URL built from
   `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain → platform-global suppression row;
   api registers the number's SmsUrl at twilio connect (`lib/twilio.js`) and `scripts.js
   registerTwilioWebhooks` backfills — a deployed webhooks route with unregistered numbers hears
   nothing, silently.
+- **`audience` picks the FROM-address; `intent` picks the opt-out machinery** (utils ↔ sync ↔
+  api). `resolveEmailSender` (sync `queue/notification.js`) resolves verified `identity` row →
+  `subAddress( leadSender, organization.shortId )` for lead-facing mail → `accountSender` for
+  member and platform mail. The tag is `shortId`, never `subdomain` — a rename and a custom-plan
+  downgrade both rewrite subdomain, and the from-address is frozen into delivered mail; api's
+  `identityDefaults.from` must tag with the SAME field or the settings screen shows a merchant an
+  address their leads never see. Drop the `leadFacing` branch and the fallback is `leadSender || accountSender`
+  for everything, so the moment a lead address is configured, Drawbridge's own mail leaves from
+  the merchant-facing lead domain — silently, with nothing raised. `subAddress` lives in utils
+  `lib/email.js` and is the inverse of `toCanonicalEmail`, which suppression uses to strip the
+  same tag; break the round-trip and consent lookups stop matching. api mirrors ONLY the
+  lead-facing branch (`identityDefaults.from`). Detail: drawbridge-docs `reference/providers.md`.
 - **Adding an email/SMS vendor is a two-repo change** (api ↔ sync). A connection is deliverable
   only if sync implements a sender for its slug — `lib/email.js` (`{ mailchimp, sendgrid }`) and
   `lib/sms.js` (`{ twilio }`), which `queue/notification.js` reads **directly** as its guard and
@@ -108,6 +122,14 @@ skill) so it stops living only in tribal memory.
   missing until 2026-08-13 (Shopify renames took 5+ min to reach share pages). Product scope is
   special: the doc carries no campaign/org refs, so the worker resolves featuring campaigns via
   `campaign.products[]`, per-page org (canonical product docs can span orgs).
+  Since 2026-09-09 share's HTML cache also stores a **404 render** under the same html key,
+  for the soft TTL only and never background-revalidated: every miss leaves share's single
+  server IP and lands in the api's global per-IP limiter, so a scanner walking a subdomain
+  (Sentry DRAWBRIDGE-SHARE-FQ) or a burst on an unpublished slug used to cost an api call per
+  request. The seam therefore MUST bust on page **insert** as well as update/delete (sync
+  `stream/page.js`), or a page created already published answers "not found" until the entry
+  expires. A slug can never carry a dot (`slugify` strips them), which is what lets share's
+  proxy refuse extension paths before they reach the api at all.
 - Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
   `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
   and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
@@ -207,6 +229,14 @@ skill) so it stops living only in tribal memory.
   sync upserts the same invoice from three concurrent webhooks (finalized/payment_succeeded/voided)
   and relies on the index to reject the losing insert so the catch can redo it as an update. Drop
   the index → silent duplicate invoice rows; remove the catch → concurrent events throw + retry.
+- The `buffer` collection's **unique partial index on Stripe `provider.id`** (drawbridge-api
+  `schema/buffer.js`, Stripe rows with a string id only) and webhooks' E11000 catch in
+  `route/stripe.js` are one contract: the route dedupes a Stripe redelivery with a read before its
+  insert, two retries arriving together both pass that read, and the index refuses the second
+  insert, which the route answers 200 without touching the first row. Drop the index → the race
+  reopens silently and sync processes one event twice; remove the catch → a concurrent retry 500s
+  and Stripe keeps retrying. The index is manual (the resetIndexes block is the runbook) and its
+  creation fails while duplicates exist — dedupe first.
 - The `contact` collection's **unique multikey index on `leads`** (drawbridge-api
   `schema/contact.js`) and sync's contact resolution (`lib/contact.js` + `queue/contact.js`) are
   one contract: a lead belongs to at most one contact. One submission enqueues two resolve jobs
@@ -455,6 +485,18 @@ sweep (`queue/identity.js`), which re-points any number whose Twilio config drif
 the path in one place and the sweep "repairs" every number to the wrong URL — inbound SMS
 (STOP included) goes dark with all rows reading healthy.
 
+**Provider rows are keyed by VENDOR, and no manifest owns a vendor (utils ↔ api ↔ sync ↔
+webhooks, since utils 0.0.153).** A manifest declares only the fields it spends under
+`provider.vendors.<vendor>`; `mergeVendors()` in utils unions every manifest's slices into
+one entry per vendor, and the `provider` collection holds one row per key of that merge —
+`sendgrid`, `twilio`, `hubspot` for the private `drawbridge` connection, one `google` row for
+however many Google connections come. Build refuses a vendor drawn two ways, a shared field
+declared differently, and a credential name claimed twice. A connection reads its vendors
+merged through `vendorSettings({ controller, slug })` (sync's `drawbridgeProvider()`, the
+api's identity/organization routes); the merged keys keep the old names. Reading
+`providerSettings({ slug : 'drawbridge' })` anywhere finds no row — it was split on dev
+2026-09-08 and prod is seeded per-vendor. Detail: `drawbridge-docs/reference/providers.md`.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.51",
+  "version": "0.1.55",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {