diff --git a/docs/placement-switch-spec.md b/docs/placement-switch-spec.md new file mode 100644 index 0000000..90563b5 --- /dev/null +++ b/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/`. 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.