@drawbridge/drawbridge-agents 0.1.51 → 0.1.58

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/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: drawbridge-asana-comment
+description: Use before posting ANY comment to an Asana task — ship handoffs, answers, status notes, questions. Enforces scannable lists of actions over paragraphs, plain correctly-named things, a mandatory review before posting, and the humanizer pass.
+---
+
+# Write an Asana comment
+
+Every comment posted to Asana goes through this skill. No exceptions for length, urgency, or
+"it's just a quick note". Posting is publishing. A teammate reads it, acts on it, and cannot
+unread a wrong one.
+
+Four rules, in order of how often they get broken.
+
+## 1. Lists and actions, not paragraphs
+
+There is no word count. Length is not the problem, shape is. Structure it so the reader can
+scan it and act.
+
+**The default shape:**
+
+- One line on what changed, in plain past tense.
+- A list of what to do and what to expect. One step per line, each one something they can
+  actually do or check.
+- Anything that would otherwise look wrong to them, as its own line.
+
+Use prose only for something a list would distort, like a one-sentence cause. Never write three
+paragraphs where four bullets would do.
+
+**Every line earns its place.** Cut it if it is:
+
+- The investigation narrative. They want the outcome, not how you got there.
+- File names, commit SHAs, function names, branch names. They are verifying behaviour.
+- Anything restating what they already told you.
+- Anything that would not change what they do next.
+
+**Completeness beats brevity.** Include every scenario to retest, any setup gotcha, and
+anything in the result that would look wrong without warning. A second comment correcting or
+completing the first is the real failure. Structure is what keeps a complete comment readable,
+so restructure before you cut content.
+
+**The stop test:** if it does not fit on a phone screen without scrolling, restructure it. Do
+not trim facts to hit a length.
+
+## 2. Use normal words and name things correctly
+
+Write for the person reading it, not for the repo.
+
+- **No internal jargon.** If the term lives in our docs and not in their message, replace it
+  with a plain description. Runbook, backfill, cascade, manifest, provider row, seam, capped,
+  hydrate all read as noise to someone testing a button. If you must use one, say what it is
+  the first time.
+- **Name things by their real name.** The screen, the button, the plan, the setting, exactly as
+  the interface labels them. Not your paraphrase, not the variable name. If the button says
+  Send, write Send.
+- **Quote user-facing copy exactly**, so they can match it against what is on screen.
+- Use their words for their bug. If they called it a prize notification, it is a prize
+  notification, not a lead-facing transactional send.
+
+## 3. Review before posting, always
+
+Never post a first draft. Read it back against this list:
+
+- Is it a scannable list of actions, or did it drift back into paragraphs?
+- **Is every claim verified?** Each factual statement must be something you checked in this
+  session: a test you ran, a deploy you confirmed live, a value you read. Anything you merely
+  believe gets cut or marked unverified. A wrong comment is worse than a thin one and costs
+  them a retest.
+- Any jargon they have not used themselves?
+- Does it open with `<a data-asana-gid="<their gid>"/>` so they are actually notified?
+- Would this need a follow-up comment? Fix that now.
+
+Then show the user the final text and get a go-ahead before posting, unless they have already
+said to proceed. After posting, read the comment back (`get_task` with comments) and confirm
+the mention expanded and the formatting survived. Asana silently flattens some markup.
+
+## 4. Run it through `humanizer`
+
+Required by `conventions/humanized-copy.md`, no exceptions for length. It must not touch the
+mention markup, quoted interface copy, or any concrete step. If a pass makes an instruction
+vaguer, keep the original for that line. If humanizer is unavailable, say so and do not post.
+
+## Sound like a teammate
+
+The comment should read as though the person who did the work wrote it in a hurry, because that
+is what a good one is.
+
+- **Plain past tense about what you did.** "Fixed on dev." Not "the fix has been implemented"
+  or "this has now been addressed".
+- **No throat-clearing.** No "Thanks for flagging this", "Great catch", "Just wanted to let you
+  know", "I hope this helps", "Let me know if you have questions".
+- **No hedging stack.** Not "this should now potentially resolve". Either it works and you saw
+  it work, or you say what you did not check.
+- **Own a mistake in one line and move on.** "I had this wrong, it only affects email." Not a
+  paragraph of explanation.
+- **Say what you did not test.** Being straight about a gap is what makes the rest credible.
+- **Ask a real question when you need an answer**, at the end, as a question. Do not bury it.
+- **Bold almost nothing.** If everything is bold, nothing is.
+- **No emoji** unless the thread already uses them.
+
+## Notes
+
+- Plain prose goes in `text`. Use `html_text` for a mention or a list. Allowed tags are
+  `<body> <strong> <em> <code> <ol> <ul> <li> <a> <blockquote> <pre>` only.
+- The `<a data-asana-gid="..."/>` form expands to a real @-mention. Reassignment alone is easy
+  to miss, so mention the person even when you also reassign.
+- If the Asana MCP is not connected, stop and say so. Never describe a comment as posted when
+  it was not.

package/.claude-template/skills/drawbridge-asana-ship-handoff/SKILL.md

@@ -1,69 +1,44 @@
 ---
 name: drawbridge-asana-ship-handoff
-description: Use when a feature has shipped (merged to develop) against an Asana task — reassigns the task back to its last commenter, posts a concise summary of what changed plus retest/verify steps, and sets the due date to now.
+description: Use when a feature has shipped (merged to develop) against an Asana task — reassigns the task back to its last commenter, posts a concise retest summary, and sets the due date to today.
 ---
 
 # Asana ship handoff
 
 Hand a shipped feature back to whoever last commented on its Asana task, with everything they
-need to retest. Use this right after merging the work to `develop` (which deploys to dev).
+need to retest. Use this right after merging to `develop` (which deploys to dev).
 
 ## Inputs
 
-- The Asana task URL or ID for the shipped work. Ask the user for it if it isn't obvious from
-  the branch, PR, or conversation — do not guess.
-- The change you shipped (from the diff / PR).
+- The Asana task URL or ID. Ask for it if it isn't obvious from the branch, PR, or
+  conversation. Do not guess.
+- The change you shipped.
 
 ## Steps
 
-1. **Load the task.** `asana_get_task` with the task gid (extract it from the URL).
-2. **Find the last commenter.** `asana_get_stories_for_task`, filter to comment stories
-   (`type` / `resource_subtype` is a comment, not a system story), take the **most recent**
-   one's `created_by`. This is the reassignee — do not hardcode a person. If there are no
-   comments, ask the user who to assign to.
-3. **Draft the comment — short.** Two parts, nothing else: what changed (and, if they
-   reported a bug, what actually caused it), then a **Retest** section with the steps and
-   the expected result. Ground the steps in the behaviour that actually changed.
-
-   **Hard limit: ~200 words, and never more than 6 short paragraphs/bullets.** These
-   comments have been far too long — reading them costs the reader more than the fix did.
-   Cut: the investigation narrative, why the bug shipped, code/file/commit detail, anything
-   restating what they already reported, and any sentence that would not change what they
-   do next.
-
-   **Short is not partial.** Include everything they need in ONE comment — every scenario to
-   retest, any setup or data gotcha, and anything about the result that would otherwise look
-   wrong (an odd amount, a delay, a cosmetic leftover). A follow-up comment correcting or
-   completing this one is the failure this limit exists to prevent, so check the draft for
-   omissions *before* trimming words.
-
-   **Open with an @-mention of the reassignee** — use `html_text` and start the body with
-   `<a data-asana-gid="<their user gid>"/>` (Asana expands it into a proper mention). A
-   comment without a mention may notify no one; reassignment alone is easy to miss.
-4. **Run the draft through `humanizer`.** A real teammate reads this, and generated-sounding
-   prose reads as effort nobody spent. Invoke the `humanizer` skill on the drafted body: it
-   strips the AI tells — inflated claims, hedging, stock transitions, "it's worth noting",
-   restating the ask twice.
-
-   It pulls in the same direction as the word limit above, so apply it *before* the final
-   trim and re-check the result against both rules. Two things it must not touch: the
-   `<a data-asana-gid="..."/>` mention (leave the markup exactly as-is) and any concrete
-   detail from the Retest steps — if a pass makes the steps vaguer, keep the original wording.
-5. **Confirm before writing.** This posts to an external system. Show the user the chosen
-   assignee and the drafted comment and get a go-ahead, unless they've told you to proceed
-   without asking.
-6. **Apply** (on approval):
-   - `asana_update_task` — set `assignee` to the last commenter's gid and `due_at` to the
-     current date/time (ISO 8601).
-   - `asana_create_task_story` — post the comment.
-7. **Report** the task URL, who it was assigned to, and confirm the due date was updated.
+1. **Load the task.** `get_task` with the gid from the URL.
+2. **Find the reassignee.** `get_task_stories`, filter to stories whose `resource_subtype` is
+   `comment_added`, take the most recent one's `created_by`. Do not hardcode a person. If there
+   are no comments, the task's creator is the fallback, but say so and confirm it.
+3. **Write the comment with `drawbridge-asana-comment`.** That skill owns the shape, the naming
+   rules, the humanizer pass, claim verification and the read-back. Do not restate its rules
+   here or work around them.
+
+   What this comment specifically must carry: what changed, and if they reported a bug, what
+   actually caused it; then the steps to retest and the expected result. Ground the steps in
+   the behaviour that changed, not in the diff.
+4. **Apply**, once the user has approved the text:
+   - `update_tasks` with `assignee` set to their gid and `due_on` set to today (`YYYY-MM-DD`).
+     The MCP cannot set a due *time*, only a date, so do not try to pass `due_at`.
+   - `add_comment` with `html_text`.
+5. **Report** the task URL, who it went to, and the due date. Confirm from the tool result, not
+   from intent.
 
 ## Notes
 
-- If the Asana MCP isn't connected, stop and tell the user to authorize it — don't fabricate a
-  handoff.
-- Keep the comment user/QA-facing: what to test and expect, not internal implementation detail.
-  The reader is verifying behaviour, not reviewing the fix — if a sentence only makes sense to
-  someone who has read the diff, it does not belong in the comment.
-- Consider running `drawbridge-ship-feature` instead if docs/graph updates for this ship
-  haven't been done yet — this skill is the final step of that flow.
+- Keep it QA-facing: what to test and expect. If a sentence only makes sense to someone who has
+  read the diff, it does not belong in the comment.
+- Run `drawbridge-ship-feature` instead if the docs and graph updates for this ship have not
+  been done yet. This skill is the last step of that flow.
+- If the Asana MCP isn't connected, stop and say so. Never describe a handoff that did not
+  happen.

package/claude/CLAUDE.md

@@ -2,6 +2,7 @@
 @../conventions/cross-repo-contracts.md
 @../conventions/karpathy-guidelines.md
 @../conventions/rules.md
+@../conventions/verification.md
 @../conventions/javascript-formatting.md
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md
@@ -19,3 +20,4 @@
 @../conventions/git-branching.md
 @../conventions/graphify.md
 @../conventions/testing.md
+@../conventions/workflow-step-naming.md

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/conventions/humanized-copy.md

@@ -18,6 +18,8 @@ descriptions — engineer-facing text follows the code conventions instead.
 Rules when running it:
 
 - Run humanizer BEFORE posting/committing the copy, not after someone flags it.
+- **Asana comments go through the `drawbridge-asana-comment` skill**, which runs the humanizer
+  pass for you along with the brevity cap and the read-back. Do not hand-roll a comment.
 - It must not change facts, numbers, steps, or expected results — if a pass makes concrete
   instructions vaguer, keep the original wording for those parts.
 - Leave markup intact (Asana mention tags, links, placeholders like `{name}`).

package/conventions/rules.md

@@ -12,3 +12,9 @@
    This is not a style preference, it is the difference between advice and noise. Asserting a limitation that isn't real sends the reader to check your work, and asserting two implementations are identical when one carries a field the other drops ships a regression. Both have happened.
 
    In practice: before claiming a component can't do something, read the component. Before calling two implementations equivalent, read both ends to end. Before proposing a new endpoint or field to work around a gap, confirm the gap exists in the code rather than in your sample of it.
+
+6. Prove absence before you claim it, and name the space you searched. "Nothing writes this field", "that isn't documented anywhere", "no caller does this" — claims of that shape cost far more to establish than they look. Reading one file proves what that file does; it can never prove what every other file doesn't. Search the whole space the claim covers — every repo, the built `dist/` as well as the source, `drawbridge-docs/user-stories/` as well as the code, and the tests — then put the space in the sentence: "no writer across the family, source and dist" rather than "nothing writes it".
+
+   Why: the reader cannot see where you stopped looking. A bare "it doesn't exist" reads as settled, and by the time the thing turns up — documented under an older name, written by a manifest in another package — work has already been built on top of it. Naming the search space turns an unfalsifiable claim into one that can be checked in seconds.
+
+   Three traps that have actually caused this. A counter incremented from a manifest in `drawbridge-utils` while the search only covered `drawbridge-sync`. A workflow step documented under a name the product had since changed, so searching for the product's label found nothing. A key assembled at runtime (`'totals.' + field`) that no search for the literal will ever match — when a claim depends on a name, check whether the name is ever built rather than written.

package/conventions/verification.md

@@ -0,0 +1,39 @@
+# Verify before you assert
+
+Every rule here was written after a confident, wrong statement reached Darren. They share one shape: the reasoning was sound and the input was never checked. Sound reasoning on an unchecked input is the most expensive kind of wrong, because nothing downstream looks suspicious.
+
+## Never state a number you did not measure
+
+A measurement in a sentence — a count, a total, "none in the last 30 days" — may only be emitted when the underlying field is actually present. Gate on `value != null` before the claim and say nothing when it is absent.
+
+`|| 0` on an unmeasured field manufactures a fact. In drawbridge-growth it reached three surfaces at once: the task queue, profile embeddings, and outreach drafts telling paying customers they had done nothing, all from a field no connected database was filling.
+
+The same applies to prose. "This is faster", "most callers do X", "that's a small table" are measurements. Measure them or drop them.
+
+## Walk the flow before saying it works
+
+Tests passing, lint clean and a green build are not evidence that a screen works. Three bugs in a row survived all three and were found by clicking: a `.then()` chained off a react-query `mutate()` (which returns undefined), colour swatches handed `{ hex, name }` objects where CSS wanted a string, and a screen in a question flow that asked nothing.
+
+Before reporting a feature as working, run the path a person takes through it. If the runtime makes that hard, that is a reason to fix the harness, not to skip the walk.
+
+## Fetch before claiming what is on a branch
+
+Before asserting what is or isn't on `origin/develop` or `origin/main`, run `git fetch` **in that repo**. Fetching one family repo does not refresh the others, and grepping a stale `origin/develop` returns stale content with no warning.
+
+In a multi-repo check, fetch every repo you will cite, in one batch, first. Treat an `origin/<branch>` read as evidence only if the fetch happened in this session. "Repo A ships a write that repo B's schema rejects" is exactly the shape a stale ref produces — re-fetch, or read the live database, before reporting it.
+
+## Quote vendor documentation, do not recall it
+
+When writing against a vendor's API, open its documentation and quote each literal as you write it: authorize url, token url, revoke url, API base, required headers, scope names, auth scheme. Then re-read the finished file against the docs as a separate pass, paying most attention to the lines written first.
+
+Klaviyo's `authorize` host was written from memory as `a.klaviyo.com` — the API host — while the browser-facing url is `www.klaviyo.com`. The docs were fetched five times that session for the values that felt uncertain, and never for the one already written. Confidence is not verification, and the values never doubted are the ones that reach a user unchecked.
+
+Pin the API **version** too. Documentation defaults to `latest`; a repo pins something older, and a field that exists in `latest` may not exist in the pinned version — or may be deprecated there when it is current in `latest`.
+
+## Check the shape you are consuming, not the one you expect
+
+Before importing, confirm the symbol is actually exported by that package's entry point. Before chaining off a wrapper's return value, confirm what it returns. Both have shipped inert code that compiled cleanly.
+
+## A build that exits 0 is not a build that ran
+
+Confirm the build produced its real output — a route table, an emitted bundle, a written artifact — rather than trusting the exit code. `drawbridge-app-web` aborts on a missing environment variable and still exits 0, which is a "successful" build that compiled nothing.

package/package.json

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