Spec: member-selectable placement setting, with sponsor inheritance

Terry asked how a new referral of his would be set up as 'Direct with
spillover', and Marty asked whether a leader's choice should carry down to
their team. This writes up the answer for the three of them to agree on
before anything is built.

Three states — Team first, Direct, Follow my sponsor — with a new member
starting on whatever their sponsor uses, so a team duplicates its leader
by default without anyone being locked in.

The rule that needed pinning down: inherit from the SPONSOR, never the
matrix parent. Under spillover those are frequently different people, and
the setting should follow whoever recruited and teaches them rather than
whoever they happened to land beneath.

Also names the pitfalls rather than leaving them to be discovered — chiefly
that inherited Direct is a doctrine change, not just a setting, since it
reverses the team-first play for everyone below a leader who picks it.

Nothing built. Three open questions at the end need Marty's call.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/placement-switch-spec.md

@@ -0,0 +1,147 @@
+# How your link places people — a setting, not a rule
+
+**Status:** proposal, nothing built yet. For Marty, Terry and Clinton to agree on before we code it.
+**Written:** 18 September 2026
+
+---
+
+## The question Terry asked
+
+> "How would a new referral of mine set up *Direct with spillover*?"
+
+And the follow-on Marty raised: if a leader builds that way, should everyone who joins under
+them inherit the same setting, so the team duplicates the leader's play?
+
+Short answer: yes, as a **default they can see and change** — not as a locked rule. The rest of
+this explains why, and what it takes to do it without creating problems we cannot explain later.
+
+---
+
+## What exists today
+
+Every position has a personal link, `rmcircle.team/join/<id>`. It is a **moving link**: once the
+member is qualified, a join through it is routed to the next position in their leg that still
+needs directs. Their promotion builds the team downward, in order.
+
+There is already an opt-out — `?direct=1` — which places the join **directly under the member**
+instead. And there is an admin list, `directDefaultIds`, that makes a position behave that way
+by default. Five positions are on it today: **21, 137, 139, 30, 840**.
+
+So the capability exists. What does not exist is a way for a member to choose it themselves, or
+for a leader's choice to carry down to their team.
+
+---
+
+## What the setting does NOT change
+
+Worth stating plainly, because this is where people assume more than is true:
+
+- **The contract is untouched.** Payments, the 50/20/10 split, qualification at 2 directs, the
+  catch-or-pass rule — none of it is affected. This only decides **which position the join is
+  registered under**.
+- **The entry reward still follows the referrer.** Whoever's link was used gets paid, either way.
+- **Spillover still does not qualify anyone.** A position qualifies only through its own
+  directs. Placing people under yourself builds your depth; it does not qualify the people you
+  place.
+
+---
+
+## The proposal: three states, chosen by the member
+
+On the dashboard, under "Share this position":
+
+| Setting | What a join through your link does | Who it suits |
+|---|---|---|
+| **Team first** *(today's behaviour)* | Routes to the next position in your leg that still needs directs | Most people. Builds the team in order and gets your two qualified |
+| **Direct** | Every join lands directly under you, as depth in your leg | A leader deliberately building out one position |
+| **Follow my sponsor** | Mirrors whatever your sponsor is set to, and keeps tracking it if they change | Someone who wants to run their upline's play without thinking about it |
+
+A new member's starting value is **whatever their sponsor is on** — so a team duplicates its
+leader by default, which is what Terry is asking for. But it is visible on their own dashboard
+from day one and takes one click to change.
+
+---
+
+## The inheritance rule, stated exactly
+
+**Inherit from the SPONSOR (the referrer), never from the matrix parent.**
+
+This matters more than it sounds. Under spillover the two are often different people: a join
+through Terry's link can be placed several positions deep in his leg, so that member's *sponsor*
+is Terry while the position directly above them is someone they have never spoken to. The
+setting should follow the person who recruited and teaches them, not whoever they happened to
+land beneath.
+
+Consequences of that choice, all intentional:
+
+- If Terry is on **Direct**, everyone he personally brings in starts on **Direct**.
+- If one of them switches to **Team first**, only that person changes. Their own future
+  referrals then start on **Team first**, because they are now the sponsor.
+- If Terry later switches, only members on **Follow my sponsor** move with him. Anyone who made
+  an explicit choice keeps it.
+
+That last rule is what stops the tree becoming unreadable. An explicit choice is never
+overwritten by someone above.
+
+---
+
+## What the member sees
+
+- The share panel states the current behaviour in plain words, the way it already does for
+  positions on the admin list: *"Rotation is off for this position: every join through your page
+  lands directly under you."*
+- Where the setting came from is shown, not hidden: *"Starting setting, from your sponsor #840.
+  You can change this."*
+- Changing it takes effect on the next join. Nothing already placed moves — placements are
+  permanent on-chain and we should never imply otherwise.
+
+---
+
+## Migration
+
+The five positions on `directDefaultIds` (21, 137, 139, 30, 840) become explicit **Direct**
+choices, so nothing changes for them on the day it ships. The admin list stays as an override
+for support, but stops being the only way in.
+
+Everyone else starts on **Team first**, which is what they have today. Nobody's link behaviour
+changes without them doing something.
+
+---
+
+## The pitfalls, and what we do about each
+
+**1. It is a doctrine change, not just a setting.**
+The method is team-first: get your two, help your two. Direct reverses that — you keep everyone
+under yourself. As a personal choice that is fine. Inherited silently across a large leg, it
+quietly converts people who were taught the team-first play. *Handling:* inheritance sets a
+**starting value**, never a lock, and the dashboard always says what the link is doing and where
+the setting came from.
+
+**2. "Which upline do I inherit from?"**
+Ambiguous under spillover. *Handling:* the sponsor, always. Written into the spec so the answer
+is the same every time anyone asks.
+
+**3. Settings drifting out of sync.**
+If a leader changes their mind, what happens below? *Handling:* only **Follow my sponsor**
+tracks changes. An explicit choice stays put.
+
+**4. Spillover expectations.**
+Members who are used to receiving spillover from an active upline will see it slow down if that
+upline switches to Direct. *Handling:* be upfront in the training — spillover is a by-product of
+how your upline promotes, never a promise.
+
+**5. Someone picks Direct without understanding it.**
+Direct builds depth under you but does nothing to qualify the people below, and they still need
+their own two. *Handling:* the setting screen says that in one sentence, next to the choice.
+
+---
+
+## What we need agreed before building
+
+1. **Three states, or just two?** Is "Follow my sponsor" worth the extra concept, or is a plain
+   inherited starting value enough?
+2. **Should a leader be able to lock their leg?** Terry might want his team on Direct with no
+   opt-out. My recommendation is no — it is the kind of control that reads badly when a member
+   finds out — but it is a real request and worth a decision.
+3. **Does the same switch belong on InstantAdPay?** It has the same sponsor/placement shape, and
+   answering it once for both is cheaper than twice.