docs(connectors): connection ownership + act-as-artist authority contract

[sweetmantech]

Summary

Contract-first PR of the P1 connector re-key chain for recoupable/chat#1860. Merge order: docs → database → api — this contract merges first, before the api re-key implements it.

Documents the connection-ownership + authority model decided in chat#1860 (2026-07-08):

• Association ≠ authority — an artist on an account's roster (account_artist_ids) or in an org grants read/analytics only.
• Connections are scoped per (account, artist), or per (org, artist) when org-shared — keyed on the join row, never on the bare canonical artist. Whoever establishes a connection owns it; roster membership never inherits it.
• Authorize / execute / disconnect — owning account only (or members of the owning org for org-shared); admin override is Recoup-staff (Recoup internal org admin) only.
• Artists stay canonical/shared; isolation lives on the connection.

Changes

• New concept page connectors/ownership.mdx (Connectors tab → Concepts group in docs.json).
• The page explicitly flags that the current connector endpoint reference (account-scoped) describes pre-contract shipped behavior and that this page is the authority contract until the re-keyed API ships. Endpoint OpenAPI descriptions were deliberately left untouched — they accurately describe what is live today.

Deliberately not documented

The open design decision (join-row id vs (owner, artist) pair in request/response shapes) is intentionally omitted — the api re-key PR is not designed yet. This page stays at the ownership/authority-model level.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a concept doc that defines connector connection ownership and act‑as‑artist authority for the P1 re‑key. Connections are owned per (account, artist) or (org, artist); roster is read/analytics only; only the owner/owning org can authorize, execute, or disconnect (Recoup staff override only).

• Migration
  • This page is the source of truth until the re‑keyed API ships.
  • Current endpoint docs remain account‑scoped; re‑keyed request/response shapes are TBD.
  • No production behavior change in this PR (contract‑first docs only).

^{Written for commit 1c870c4. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

@sweetmantech, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9a7e99f9-e9bf-4ef5-9ae9-9e0ec7e3d422

📥 Commits

Reviewing files that changed from the base of the PR and between f441eca and 1c870c4.

📒 Files selected for processing (2)

• connectors/ownership.mdx
• docs.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/connector-ownership-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="connectors/ownership.mdx">

<violation number="1" location="connectors/ownership.mdx:50">
P1: The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At connectors/ownership.mdx, line 50:

<comment>The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.</comment>

<file context>
@@ -0,0 +1,65 @@
+| Capability | Who has it |
+|------------|-----------|
+| Read / analytics on an artist | Any account or org member with the artist in their roster |
+| Authorize a new connection | The account (or org member, for org-shared) establishing the connection — they become the owner |
+| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |
+| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |
</file context>