docs(sales): the opportunity header says what it holds

[claude]

Closes #1709

Description

The opportunity detail layout's Header bullet enumerated "name, stage badge
with the 7-stage path, amount, close date, owner", and was wrong in both
directions at once. Re-derived from src/pages/opportunity_detail.page.ts on
this branch rather than taken from the card:

the card's claim	measured on the page
page:header (opp_header) declares four things	✅ title: '{name}', subtitle: '{crm_account}', breadcrumb: true, actions: ['generate_quote', 'clone_opportunity', 'log_call', 'log_meeting', 'schedule_meeting']
the stage path is a separate record:path	✅ opp_stage_path — statusField: 'stage' and the seven stages in funnel order
amount / close date / owner are record:highlights fields	✅ opp_highlights — fields: ['amount', 'close_date', 'probability', 'expected_revenue', 'owner_id', 'crm_account']

So the bullet named a component that is not on the header (record:path — which
the same list already named on its own line as Sales Path, so one component
was counted twice), named fields belonging to a component the page description
never mentioned at all (record:highlights), and left the subtitle, the
breadcrumb and all five action buttons unnamed — Generate Quote among them,
which the page placed on the Quote related list rather than on the header.

This is a rewrite, not a deletion, which is why it could not ride along on
#1701's one-item removal: the fix has to add a bullet as well as correct one.

Type of Change

• Documentation update

Related Issues

Closes #1709

Filed from this card's measurements rather than corrected here — four findings,
four cards, in the class-per-card discipline this card itself came from: #1719, #1720,
#1721, #1722.

Changes Made

The scope is the enumeration under The opportunity detail layout: the Header
bullet and the neighbours it double-counts. Four bullets per face, three faces.

• Header — rewritten against page:header: the title, the subtitle, the
  breadcrumb and the five buttons by name, then what is not on it (no stage
  badge, no amount, no close date, no owner) and where Generate Quote really
  sits.
• Key Information — new. record:highlights had no line anywhere on the
  page; it now has one naming its six fields, and noting that the account is
  therefore on the screen twice.
• Sales Path — now describes record:path once and alone, so the path is no
  longer counted twice.
• Quote related list — stops claiming the Generate Quote button; it says
  where the button actually is. The link to the Quote Generation flow is
  unchanged in each face, anchor included.

.changeset/opportunity-header-says-what-it-holds.md is new.

⛔ No src/ metadata changed — opportunity_detail.page.ts is correct as
authored. ⛔ No gate and no test added. ⛔ content/docs/releases/ untouched.

The Chinese faces were rewritten in their own register, not back-translated: each
uses its own vocabulary (组件 / 元件, 侧栏 / 側欄, 标签页 / 標籤頁) and keeps the
page's established terms (头部 / 頭部, 成交日期, 负责人 / 負責人) rather than
importing the cases page's. UI nouns take the zh-CN language-pack wording, which
also corrected a coined short form the old bullet carried: the button is
生成报价单 in the pack, not 生成报价.

Zone 2 — the measurements handed over as unverified

1. The card's property table is the finder's, not the PM's. Re-derived above
from the page file on this branch. It holds item for item, including the two
components the header bullet was borrowing from.

2. The two "written against the component" bullets in the same section. Both
re-measured before being used as the style model, and both are still accurate:
the page does declare three regions with the rail alone in aside; competitors
is retired (src/views/opportunity.view.ts records where it sat); the rail's
three entries carry no title and no filter, so the task card really is headed
Task and really does count tasks of every status, while opp_tasks on the
Related tab carries status not_equals completed, ten at a time. One inaccuracy
was found inside the Competitors & Notes bullet — it calls the field Loss
Details, whose declared label is Loss/Win Details — and per the card's own
instruction it is filed as #1721 rather than corrected here.

3. The separate table higher up the page ("What an opportunity record stores ·
The detail screen has 7 sections"). Measured, and it is a different claim that is
independently wrong: the seven are the object's fieldGroups, while the detail
screen's Details tab declares three sections and the form declares four.
It is unaffected by this PR — different section, different components, no
shared sentence — and is filed as #1719 with the sibling page's corrected shape
cited as the precedent.

4. The sibling sweep was not redone, as instructed. The two Chinese faces
were verified character by character: the card's quotes are accurate but
partial — both faces carried a second sentence the card did not quote
(「点击路径上的任意阶段可直接跳转到它。」/「點擊路徑上的任意階段可直接跳轉到它。」),
which is itself false and is corrected here.

5. Test pins, checked before editing. None on this prose. The four files under
test/ that name this page key on other things — docs-view-rosters on the view
roster, docs-drift on the verbatim $100K CEL condition, docs-object-coverage
on the term line item (still present, in the Line items section), and
docs-role-hierarchy on the sharing paragraph. The distinctive tokens of the
rewritten bullets (stage badge, Sales Path, Add Product, 阶段徽章, 一键阶段推进)
have no assertion site anywhere under test/. docs-metadata-counts does not
reach "7 sections" — it guards registered-stack counts, not section counts.
Nothing turned red, so nothing needed relaxing.

6. The two devs in flight (#1707 on src/views/lead.view.ts, #1708 on
src/flows/lead-conversion.flow.ts) touch nothing this PR reads or writes. No
overlap, nothing to report.

Two claims dropped for one measured reason

Both faces of the old text promised a control that does not exist — "Click any
stage on the path to jump directly to it" on the Header bullet, and "one-click
stage progression" as the whole of the Sales Path bullet.

• RecordPathProps (@objectstack/spec/ui 17.3.0) declares statusField,
  stages and aria. There is no click, select, navigate or href property to
  author.
• The renderer shipped in the pinned @objectstack/console 17.3.0 draws the strip
  as role="list" / role="listitem" spans with aria-current="step". Its whole
  component body contains zero occurrences of onClick, onKeyDown, button,
  href, navigate or cursor-pointer.
• And the object forbids the jump the sentence promised anyway: the
  opportunity_stage_progression state-machine rule on crm_opportunity declares
  the legal transitions, and they are not "any stage from any stage".

The bullet now says the path is a read-only indicator and that a deal moves when
its Stage field changes — which is what the same page's The 7 sales stages
section has always described.

Testing

• pnpm verify fully green, the whole chain in one run: validate →
  typecheck → lint → lint:i18n-gate → hygiene → hygiene:tokens →
  build → test. Exit code 0, captured before any pipe.

Every stage's real result, read from that run's log:

✓ Validation passed (1280ms)
   (typecheck: tsc --noEmit, no output, stage exit 0)
   (lint: 1 warning(s), 12 suggestion(s) — pre-existing approval-staffing advisories)
✓ i18n lint gate: 0 `i18n/missing-*` issues
✓ source hygiene clean
✓ source token ratchet clean
✓ Build complete (1354ms)

 Test Files  161 passed (161)
      Tests  3408 passed | 1 skipped (3409)

The token ratchet's three readings are unchanged by this PR (~84,536 / ~37,958 /
~136,835) — it measures src/, and this PR adds no source.

Checklist

• I have added a changeset — .changeset/opportunity-header-says-what-it-holds.md, 'hotcrm': patch.
• I have performed a self-review of my own changes
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes

Why 'hotcrm': patch, re-measured rather than inherited

#1710's dev measured this precedent three days ago and concluded patch. That
judgement was re-checked here against today's tree rather than carried over,
because both forms are live: .github/workflows/changeset-check.yml documents the
empty-frontmatter entry as the sanctioned "this PR releases nothing" declaration,
on par with the skip-changeset label.

Counting every changeset by the commit that added it, restricted to docs-only
commits (content/docs touched, no src/):

month	patch	minor	empty
2026-08	8	0	9
2026-09	26	1	2

So #1710's conclusion replicates, with one correction to its framing: the split is
not purely by kind. The empty form was genuinely common for docs-only PRs in
August and has all but stopped since — the two September entries are the same
security-page pair from 2026-09-03. The decisive evidence is nearer than the
totals anyway: the two immediately preceding corrections to this same bullet-list
family on the sibling page, #1702 and #1710, both took 'hotcrm': patch.

It is also the right answer on the merits rather than by count. This PR changes
what a reader of the shipped product documentation is told about a screen they
use every day, and it deletes two promises of a control that does not exist. That
is a change a user sees, so the release notes carry it.

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 6, 2026 1:37pm UTC