Skip to content

Rename the capability concept to integration - #14

Open
solev wants to merge 1 commit into
feat/roadmap-implementationfrom
refactor/rename-capabilities-to-integrations
Open

solev wants to merge 1 commit into
feat/roadmap-implementationfrom
refactor/rename-capabilities-to-integrations

Conversation

@solev

@solev solev commented Aug 17, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #13. Answers "I am not sure I like the capabilities folder naming."

What the research found

Full write-up in docs/research/folder-naming-prior-art.md. Every path was verified against the live GitHub contents API, not a blog post.

capabilities/ had no precedent in any repo checked for this meaning. And the word is heavily overloaded — Linux CAP_*, WASI, Kubernetes securityContext, Playwright config, capability-based security.

The damaging part: the nearest in-domain neighbours use it for the opposite idea.

Repo Path Means
dubinc/dub apps/web/lib/plan-capabilities.ts billing-tier entitlements
formbricks/formbricks apps/web/modules/entitlements/ same idea, different word

integrations/ is what the ecosystem calls this, verified:

Repo Path Contents
withastro/astro packages/integrations/ react, mdx, netlify, cloudflare, partytown
dubinc/dub apps/web/lib/integrations/ stripe, slack, shopify, hubspot, segment
better-auth/better-auth packages/better-auth/src/integrations/ next-js, svelte-kit, node

It also matches Rocket's own test in docs/agents/upstreaming.md: "Does it require external configuration or a third-party account?" That is the definition of an integration.

Two arguments I had to discard

  • CONTEXT.md listed "integration" under Avoid. That is a record of the decision under review, so citing it is circular.
  • A test-name clash between tests/integration/ (methodology) and app/integrations/ (subject). Real, but it touches two files, and both read better named for what they assert.

Closest analogue, and why it lost

medusajs/medusa → packages/modules/providers/ (payment-stripe, notification-sendgrid, file-s3) is the nearest match in shape. But a Medusa provider implements a swappable interface, whereas Rocket's billing is the billing concern, Polar-shaped throughout. So providers/ would misdescribe it.

Worth noting: Medusa's notification-local / file-local no-op fallbacks are exactly what app/lib/email/delivery.server.ts does — a nice independent validation of that seam design.

Changes

Now Was
app/integrations/ app/capabilities/
docs/integrations/ docs/capabilities/
app/lib/integration.ts app/lib/capability.ts
IntegrationUnavailableError CapabilityUnavailableError
requireIntegration() requireCapability()
IntegrationGroup CapabilityGroup
BILLING_INTEGRATION / AI_CHAT_INTEGRATION *_CAPABILITY

Two disambiguations fall out of it:

  • The guide section ## Integration (how a thing is wired in) becomes ## Wiring, so an integration guide no longer contains an Integration section.
  • Tests are named for what they assert: capability-contract → availability-contract, capability-endpoints → webhook-endpoints.

Glossary gap closed

CONTEXT.md defined the term without ever mentioning optionality — the trait the entire contract rests on. Absence being valid is the whole point, yet it was implied only by contrast with Core. The definition now names it outright.

The honest argument against

"Integration" describes where the code points (outward, at a vendor); "capability" describes what the application gains. If Rocket ever ships an optional concern with no vendor behind it — in-house audit logging, a pg-boss job runner — it would be an integration with nothing.

Every item present and on the backlog is vendor-backed today, so this is a bet that the optional surface stays that way. Easy to revisit, but worth saying out loud.

Verification

  • bun run check exits 0 (format, lint, typecheck, env check, unit + DOM, integration, drift, build)
  • 30/30 integration tests
  • 7/7 Playwright against the production build, no retries
  • No stale capability references outside .agents/skills/ (vendored, generic usage)

Scope note: this branch now contains only the rename. The signup-atomicity fix
that was briefly stacked here was moved to #13, where the hook it fixes is
introduced, so a real bug fix does not depend on accepting a naming change.

@vercel

vercel Bot commented Aug 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
rocket Ready Ready Preview Aug 22, 2026 12:39pm

`capabilities/` had no precedent in any repo checked for "folder of
optional third-party integrations", and the word is heavily overloaded:
Linux CAP_*, WASI, Kubernetes securityContext, Playwright config, and
capability-based security. Worse, the nearest in-domain neighbours use it
for the opposite idea — dubinc/dub has plan-capabilities.ts for billing
entitlements, and Formbricks has modules/entitlements/.

`integrations/` is what the ecosystem actually calls this, verified
against live directory listings: withastro/astro packages/integrations
(react, mdx, netlify), dubinc/dub apps/web/lib/integrations (stripe,
slack, shopify), better-auth packages/better-auth/src/integrations.

It also matches Rocket's own test in docs/agents/upstreaming.md: "does it
require external configuration or a third-party account?" That is the
definition of an integration.

CONTEXT.md previously listed "integration" under Avoid for this term.
That was a record of the decision now being reviewed, so it could not be
used to defend itself.

The glossary also never stated the trait the whole contract rests on:
optionality. Absence being valid is the entire point, yet it was only
implied by contrast with Core. The definition now names it outright.

Two disambiguations fall out of the rename:

- the guide section "## Integration" (how a thing is wired in) becomes
  "## Wiring", so an integration guide no longer has an Integration
  section
- the tests are named for what they assert rather than their subject,
  avoiding a clash with tests/integration/ as a methodology:
  capability-contract -> availability-contract, and
  capability-endpoints -> webhook-endpoints

Research and the argument against are in
docs/research/folder-naming-prior-art.md.

Verified: bun run check exits 0, 27/27 integration tests, 7/7 Playwright
with no retries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@solev
solev force-pushed the refactor/rename-capabilities-to-integrations branch from bf01484 to 55b4544 Compare August 22, 2026 12:37

This branch was successfully deployed

1 active deployment
Preview — 55b45449 Deployed Aug 22, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant