# Member-facing learning copy — the first-time reader rules

**Scope:** every screen a MEMBER reads to learn — the road (`utils/road/content.js`,
`takeoffContent.js`, `stages.js`), the Glossary course (`utils/glossaryContent.js`), 案例复盘
(`utils/cases/`), lesson descriptions, the AI Coach pages' teaching copy, Area Tutorials'
scripts. Not admin copy.

**Origin (2026-09-02).** The founder read 起 · screen 2 (`/property/academy/road/mindset?beat=2`)
as a first-time member and stopped on three things in one paragraph:

> 「小明从餐厅打工到自己开店、到培养店长、到拿钱投资，走的就是这四格」 — *how would a first-time
> user know what 小明's story is?* · 「ESBI」 — *E stands for what?* · 「课程的 T 单元讲的 2A1P」 —
> *what is T? what is 2A1P?* … *dun always assume they read somewhere. This is not world class
> learning portal.*

The copy had been written by someone who had read the book, watched the course and built the
portal — so every term was "obvious". The member has done none of those things. The review that
followed found the same defect on every stop (SPA is never expanded anywhere on the road; 2+2+1
is the TITLE of Analyze's concept screen and is defined one beat later; Ryan is quoted on the
road's first screen and introduced on its fourteenth). These rules exist so it is not written
again.

---

## The test

**The first-time reader test.** A member who has never read the book, never watched the course
and never opened another page of the portal reads THIS screen, cold. Every capitalised term,
every letter, every name and every number on it must be answerable from this screen or an
EARLIER screen on the same path. If the reviewer has to say "they'll know that from…", the screen
fails.

Run it on every new or edited screen. It takes two minutes and it is the only check that sees
the problem, because the writer cannot: they already know what the word means.

---

## The rules

### 1 · Define on first use — on the screen it first appears, not in a glossary at the end

The FIRST time a term appears on the path, it carries its full form, its Chinese and one line of
meaning, in the sentence itself:

```
DSR（Debt Service Ratio，偿债比率）—— 银行用它决定借你多少：每月要还的债 ÷ 每月净收入。
ESBI —— 收入的四种来路：E Employee 打工 · S Self-employed 自雇 · B Business owner 企业主 · I Investor 投资者。
SPA（Sale and Purchase Agreement，买卖合约）
```

Applies to acronyms (DSR, MoF, HDA, SPA, VP, LAD, GRR, RPGT, OPR, PSF, BMV, BNM, NAPIC, TEDUH,
KPKT, CCRIS, OPM, 2A1P, 2+2+1…), to letters used as names (D · M · A · I · C · T · D′ · E · S ·
B · I · A1 · A2 · P), to product names (Deal Day, Vibe Coding, Pro) and to the course's own
inventions (格, 卡, 铁律, 单元). A term defined on 起 does not need re-defining on D; a term
defined five stops ago gets a short re-gloss (`SPA（买卖合约）`) — the reader may have come back
after a month, or jumped in from the chapter list.

**The glossary strip on beat 9 is a reference, not the definition.** It sits after the reader has
already met the term four times. Keep it — but the definition lives at the first use.

### 2 · No forward references

Never explain a screen with something the reader has not reached: 「课程的 T 单元讲的 2A1P，就是
这个顺序的完整版」 tells a reader on stop 1 nothing and makes them feel they missed a page. If a
later stop must be teased, tease it in PLAIN words and name the stop by what it is, never by its
letter or acronym:

```
✗ 课程的 T 单元讲的 2A1P，就是这个顺序的完整版。
✓ 第 7 站会把这个顺序讲完整：先在职做副业，全职是结果，不是起点。
```

The same rule covers the video course's own structure (「第2单元」「Bonus 单元」): the road never
told the member the course HAS units. Either introduce the course map once (起's first screen)
or refer to lessons by their titles, which the lessons shelf already prints.

### 3 · One cast, introduced before use, never renamed

- **A character is introduced with a 人物卡 the first time they appear** — name, one line of who
  they are, their numbers — and every later screen may use them. Ryan is quoted on 起's first
  screen (「Ryan 的答案是 45 岁前每月 RM 8,000」) and introduced on D's fifth beat; that order is
  backwards.
- **One name, one person, one set of numbers, for the whole path.** The road currently has TWO
  Ryans (the road's, net RM 6,500; 「书里的 Ryan」, net RM 4,000) and TWO 小明s (起's
  restaurant-worker-turned-investor; T's 「Ryan 叫回他的中文名小明」 on RM 5,000). A reader who
  meets the second 小明 assumes he is the first. A different case needs a different name; a
  character whose numbers must change for a lesson gets a NEW character, with the reason said.
- **The author is a person, not 「作者」 or 「书里」.** Name the book and the author once on the
  first screen (「这条路来自 Wai Kit 的书《…》和课程《…》」), then say 「课程」.

### 4 · A story is a strip, not a clause

An example that carries an argument gets at least one screen of its own: who they are → what
changed at each step → what it cost or earned → the lesson. 「小明从餐厅打工到自己开店、到培养店长、
到拿钱投资」 is four steps compressed into one clause; the reader cannot see what changed between
steps, so the ESBI argument (who pays him? does he have to be there?) never lands. Four steps =
four panels, each labelled with the letter it illustrates.

### 5 · One idea per screen

- ≤ 3 paragraphs per screen; ≤ ~110 Chinese characters per paragraph; one number per sentence,
  **bold**, with its unit.
- A screen that needs more becomes two screens. Control's 「方法的答案」 is six paragraphs
  covering nine process steps, showroom tactics, five SPA clauses, the construction period,
  tenancy, tax and round two — that is three screens, not one.
- Put the number the paragraph is about in a callout beside it, not only inside the prose.

### 6 · System vocabulary is not member vocabulary

Words the BUILD uses (beat, 格, 卡, stale, handoff, D′, Pro, 单元) are either introduced on the
path's first screen or replaced by plain words. Current mapping:

| build word | member word (or: where it must be introduced) |
|---|---|
| 格 / 第 n 格 | keep only if 起's first screen says 「这条路有 8 格，像走棋盘；每一格结束留一张答案卡」; otherwise 站 |
| 卡 / D 卡 | 答案卡 (introduce once, same screen) |
| 已过期 (stale) | 「上游的答案改了，这一站的数字要重算」 — the chip keeps the two characters, the first use explains them |
| D′ | 「D′（读作 D prime）—— 第二轮的 D」 |
| Pro 入口 / Pro extension | 进阶资源, or say what Pro IS if it is a tier |
| T 单元 / 第 n 单元 / Bonus 单元 | the course map, introduced once; otherwise lesson titles |
| A2 / P 引擎 / OPM | plain words until T defines them |

### 7 · Every stop opens with objectives and a duration, and closes with a recap

- Beat 1: 「学完这一站你能…」 × 3, in the member's words (「算出银行今天肯借你多少」, not
  「掌握 DSR 概念」), plus 「约 N 分钟」.
- Beat 9: a 3-bullet 「这一站你带走的」 recap + the 3–5 key terms as chips. The recap is what a
  reader who comes back next month re-reads instead of the stop.

### 8 · Picture the mechanism

A list of three or more things, any sequence, any comparison, any formula → a diagram, and the
diagram states its facts in words (never colour alone — the existing viz rule). Every screen has
a visual anchor; a photograph is mood, not explanation, and does not count. Draw what the caption
says: D's gauge caption admits 「课程自己的线 40% 图上没画」 — draw it.

### 9 · One thing, one name

Pick the member word for each concept and use it everywhere, with the English in brackets at
first use only: 交楼 (VP) · 月供 (never 供期 / instalment mid-sentence) · 成数 (MoF) · 签 SPA ·
净收入 · 可借额 · 天花板. Alternating names reads as two concepts.

### 10 · Source once, then 「课程」

Name the book, the course and the author on the path's first screen. After that, 「课程教的」 /
「课程的底线」 — never 「书里」 or 「作者」, which make the reader wonder which book and who.

### 11 · Audit the reasoning, not just the vocabulary (2026-09-02, second review)

A term audit is not a review. After the first pass (which only checked what was defined where)
the founder read 起 · screen 3 and asked *"do you really go through it and understand the logic?"*
— and the screen did not survive the question: two durian metaphors on one screen (a durian as a
traded GOOD, then a durian TREE as an asset) with nothing saying they are different; the
borrow-from-mum example ends at 「本金 10 换 20 的盈利」 without the point (same RM 100 buys ten
durians → RM 200) and without interest or the loss case; the tree paragraph jumps from roots to
「银行肯借的前提是它信你」 with no connector; and a false 「所以」 (the BNM 70% third-loan rule is
a 2010 anti-speculation rule, not a consequence of "you might not carry it"). None of that is a
missing definition. **For every paragraph ask, in order:** what is the claim → does the previous
sentence give a reason for it → would a reader say "so what?" or "why?" here → is the example
carried to its conclusion (including the downside) → is the arithmetic right → does it contradict
a stance taken on an earlier stop. The worked case must obey the rules the course teaches (Ryan
cannot sign at DSR 64.5% on a stop that just taught 「新项目 ≤ 60%」 and be waved through with a
3% negotiation that does not close the gap).

### 12 · One point per screen, and the picture moves with it

The founder's format ask: *"why you can't do like typeform style, every slide show few points with
animation and picture to easy understand."* A screen is a SEQUENCE of points, not three
paragraphs: each point is a headline (≤ 14 characters) + one sentence + a state of ONE diagram
that grows as the points advance (the tree grows roots, then trunk, then fruit; RM 50,000 becomes
RM 125,000 then RM 500,000). Advance by click / → / space, dots for progress, `?beat=N&p=M` in the
URL (the stepper-over-scroll rule). Shape: `points: [{ key, title, line, viz: { kind, state } }]`
on the screen, a `PointStepper` component, a `state` prop on the viz; `prefers-reduced-motion`
lands on the final state. A photograph is not the picture; the mechanism is.

---

## The check before a screen ships

1. Run the first-time reader test (above) on the screen — read it cold, list every term you had
   to already know.
2. Every listed term is defined on this screen or an earlier one on the same path (Rule 1), and
   nothing points forward by acronym (Rule 2).
3. Every person on the screen has been introduced, under this name, with these numbers (Rule 3).
4. Any example that carries the argument has its own strip (Rule 4).
5. ≤ 3 paragraphs, one idea, numbers bold with units (Rule 5); one diagram (Rule 8).
6. Objectives + duration at the stop's start, recap at its end (Rule 7).
7. Every paragraph's claim has its reason in the sentence before it, every example is carried to
   its conclusion, every 「所以」 is a real consequence, the arithmetic is re-done, and the worked
   case obeys the stop's own rules (Rule 11).
8. The screen is written as points with a diagram state per point, not as prose (Rule 12).

## Making Rules 1 and 2 checkable

Proposed (not built yet, 2026-09-02): a registry `utils/road/terms.js` —
`{ key, en, zh, def, definedAt: '<stage>/<beat>' }` — read by an inline `<Term>` component (dotted
underline, popover with `en · zh · def`) and by a vitest, `terms.test.js`, that walks
`CONTENT` in road order and fails when a registered term's FIRST occurrence sits before its
`definedAt` screen. That turns the two rules the founder's review caught by eye into a test the
next writer cannot skip. See the road handbook for where the copy lives.

## Rule 13 — Don't over-summarise: a point must be understood without thinking (2026-09-03)

The founder, reading 起 as a first-time member: *"why so short description? I not even can
understand, I need to think"* · *"how to get 200%, need to show calculation!"* · *"suddenly u say
u can buy 10, no explanation at all to 铺垫"* · *"why 1.5, u assume user understand?"* · *"you keep
over summarize the explanation and expect people to understand."*

One point = one idea, **explained in full**, not one clipped sentence. Every point line carries:
1. **the claim** in a complete sentence (a title like 「几间才够？」 is not a sentence — 「几间才够
   RM 6,000？」 is);
2. **the why** — the reason a first-time reader would ask for;
3. **the calculation, written out** whenever a number is the point (20 ÷ 100 = 20%; 20 ÷ 10 =
   200%; 40,000 ÷ 5,800 = 6.9 → 6 个月) — never a bare result;
4. **the 铺垫** before any jump — 「妈妈肯借 9 倍，所以 100 能借到 900，一共 1,000，够买 10 颗」
   precedes 「所以你能买 10 颗」, never follows it;
5. **what to look at in the picture** (「图里那条灰色的「金钱压力」…」) — and the diagram itself prints a
   one-line caption for its state (`data-viz-caption`), because a member cannot decode
   「上班 ON · 薪水 · 进账」 from the drawing alone.

A point that asks the member to DO something says so **visibly**: `interaction: { kind, label }`
renders a 「试一试：…」 prompt under the line, and the control itself carries a 「按一下」 hint until
it has been used. A sentence that mentions a switch is not a prompt.

The old "one sentence per point" ratchet is gone: three or four plain sentences beat one compressed
one. Keep the **title ≤ 14 characters** — the title is the label, the line is the teaching.

## Rule 14 — Never mention the founder's book

No 「书里」, no 「书里的 Ryan」, no "source" point naming it — the founder has said so more than once.
A case that used to be "the book's" gets its own name (`cast.js` `BOOK_CASE` → 「另一个案例」).
The Kiyosaki citation on ESBI is a different book and stays. `roadConsistency.test.js` guards it.

## Rule 15 — Never say 「课程」 either (2026-09-03)

Rule 14 retired the book. The same applies to 「课程」: the member is ON the thing, they do not
need it named, and the founder read it as the same mistake — *"mention 课程, why mention it, same
stupid mistake like mention book"*. Say 「我们的做法」, 「这条路的规矩」, or simply state the rule
(「签约时 DSR 不超过 60%」). `roadConsistency.test.js` fails on 课程 and 书.

## Rule 16 — Spell the word out on every use, not the letter

「Employee（打工）」 every time, never a bare 「E」; 「DSR（每月要还的债 ÷ 净收入）」 on first use in a
screen. A reader who joined at screen 6 has not memorised a legend. *"dun mention E and I, need to
mention Employee (E) like that, people might not remember what is E."*

## Rule 17 — One calculation, one line, each line labelled

Never a chain (`6,500 × 60% − 1,800 = 2,100 → 贷 474,000 → ÷ 90% → 527,000`). Write it as steps
the reader can follow with a finger, each with what it means:

```
① 每月能还的上限   6,500 × 60% = 3,900
② 减掉现有承担     3,900 − 1,800 = 2,100  ← 新房贷月供最多这么多
③ 换成贷款额       2,100 × 200 ≈ 474,000
④ 换成房价（借 90%） 474,000 ÷ 0.9 ≈ 527,000  ← 你该看的价位上限
```

Use `Components/Road/CalcSteps.vue` so every station shows them the same way.

## Rule 18 — The picture may not show what the words have not said

A diagram grows with its points: a card appears EMPTY when the point names it and FILLS when the
point explains it; a later point's number never appears early. *"only show the description at left,
but right side already show since early … if info not yet describe, then dun show at right."*
And one forward button per screen, at the very bottom right, after every extra block.

## How these rules are enforced (2026-09-03)

Four of them are machine checks in `resources/js/utils/road/roadConsistency.test.js`, so the same
mistake cannot ship twice. Each fired on something the founder found by reading:

| Rule | The test | What it catches |
|---|---|---|
| 18 | *a station walks each diagram FORWARD through its own reveal order* | A cumulative drawing (one declaring `ORDER` and asking `reached()`) whose point sequence goes backwards — i.e. the picture showed a fact before the words said it. A deliberate return marks the point's viz `rewind: true`. |
| 17 | *no point chains a calculation inside its sentence* | Two `=` in one line, or `=` plus `→`. The fix is a `calc` block (rendered as labelled steps by `CalcSteps`) or the arithmetic inside the diagram. |
| 16 | *every abbreviation is spelled out where a station first uses it* | DSR · ROI · BMV · GRR · LAD · RPGT · COCR · OPM · CCRIS · CTOS · HDA · SPA · EPF · SOCSO · PCB · psf · Median · 成数 used without their meaning on a station's first use. |
| C5 | *names him where a station first spends his numbers* | A station leaning on Ryan without saying who he is. |
| 14 · 15 | *no road SOURCE file names the book or the course* | 书 / 课程 anywhere under `utils/road/`, `Pages/…/Road/`, `Components/Road/` — not just in the walked copy, which is how 34 of them hid in beat labels, term popovers and viz captions. |

**What no test can check**, and therefore what a cold read by a person is still for: whether a
sentence actually teaches, whether the Chinese reads as Chinese rather than as translated English,
and whether a claim raises a question it does not answer. Ship ONE station, have it read, then
build the next — the eight-at-once run of 2026-09-02 is what let the same faults into all of them.