docs: write five claims to what the product does — docs-truth sweep (#1063)

[huangyiirene]

Fixes #1063
Fixes #998
Fixes #1012
Fixes #732
Fixes #961
Fixes #709

Description

Docs-truth sweep: five separately filed findings, all ruled the same way on 2026-08-11 — the documentation claims something the product does not do, so the documentation moves — packaged into one PR per the sweep card #1063. No capability expansion anywhere: every ruling declined the "make the product match the docs" option.

Review is by checklist line, not diff order. The git diff --stat file list maps 1:1 onto the checklist below (33 files: 22 + 1 guard for #998, 3 for #1012, 3 for #961, 3 for #709, 1 changeset; #732 needed no file).

Per-item checklist

#	落点	before	after
#998	22 doc files, 25 occurrences (analytics/index ×3, getting-started/quick-tour ×3, guides/search-and-navigation, marketing/index ×3, revenue/approvals ×3, revenue/index ×3, sales/index ×3, service/index ×3)	the app is called Enterprise CRM — a spelling src/ has never carried	HotCRM, the string CrmApp.label / the locale bundles / dist/objectstack.json / the marketplace manifest all ship, and the one the app launcher shows. Re-counted on origin/main: 25 occurrences across 22 files, exactly as filed
#998 guard	test/docs-quick-tour-navigation.test.ts	the app's own name was unguarded — the launcher list sat outside the guarded block, and the occurrence inside it was not bold, so the "bold must be a real name" rule passed over it	CrmApp.label joins the assertion set: the block's start marker and the app-launcher bullet on all three locale pages are derived from it, plus the label joins ALLOWED_BOLD. Renaming the app in src/ now goes red until the pages follow
#1012	README.md:62 (banner) and README.md:130 (repository-layout block)	13 actions — and server actions + AI tools (13) one section down	26, the registered count, re-measured on this tree after pnpm build (26 Actions; premise confirmed, not moved). ⚠️ The card named one README location; the layout block states the same figure a second time and was wrong on every calibre (that directory holds 6 files), so both are fixed — flagged here for review
#1012	docs/STATUS.md (the note under the validator transcript)	"which calibre a reader should be told is an open product question — #1012 — and this block does not settle it"	the note states the settled calibre (registrations), keeps the 6-files/26-registrations distinction, and records that the README now states the same 26. Filed premise said STATUS.md:17; the 13 actions reference actually sits at :35 on today's tree (it moved when #1011 landed)
#1012 guard	test/docs-drift.test.ts, the #729 rule (added by PR #1010)	actions deliberately absent — "this guard does not pick a side"	an actions kind read off the registered stack, plus two CLAIMS spellings (banner + layout block). The banner pattern is bold-scoped on purpose: actions is the one noun here that is also an ordinary English word in these pages — a bare (\d+) actions reads whats-new's Copilot prompt "What are the next 3 actions I should take?" as an inventory claim
#732	content/docs/sales/forecasting.mdx ×3 locales	(filed) the Copilot skill writes a forecast record and stores the transcript on it	no change needed — already true on main in all three locales. PR #742 landed the docs-truth half: the skill "composes describe_object / aggregate_data / query_records / visualize_data … answers in the conversation … opens no forecast row", and the Source field row reads "ai (reserved for an agent or integration of your own — nothing in HotCRM writes it)". Verified line by line in en / zh-Hans / zh-Hant. The card closes because the remaining half (build the write capability) was declined by the ruling. The soft "AI grounding" line stays untouched, as the earlier PM review directed
#961	content/docs/marketing/campaign-members.mdx ×3 locales — the «Standard list views» section	a Members tab with four member list views: All Members, Responded, Bounced / Unsubscribed, Converted to Opportunity	«Where members appear»: the Campaign Members panel on the shared Related tab, with its real columns Lead / Contact / Status / Response Date. Re-measured: crm_campaign_member registers zero views; highlightFields = [crm_campaign, crm_lead, crm_contact, status, response_date] minus the panel-scoped crm_campaign; no relatedList: 'primary' anywhere in the repo. All four retired names are still named, in italics, per the #927/#932 convention
#961	same three files, the enrolment list	"open a campaign and click Add Members, then pick from lead and contact list views", and "from a lead or contact…"	the picker path that ships — Add to Campaign — plus the campaign panel's New button for one-at-a-time entry. ⚠️ Measured deviation from the ruling's wording: the ruling says "the Add to Campaign action on lead/contact pages", but CreateCampaignAction declares objectName: 'crm_lead' and no contact action carries it (src/actions/contact.actions.ts has only Mark as Primary Contact / Send Email). The docs now say lead only — the measured reality, per the sweep card's "use the measured value and say so" rule
#709	content/docs/administration/profiles.mdx ×3 locales, Marketing User block	"Create, read and edit leads, contacts and campaigns org-wide"	per object: leads — create, read org-wide, edit own-and-created; contacts — read org-wide, create refused (master-detail insert needs edit on the master account, which this profile holds nowhere), edit own-and-created; campaigns and campaign members — create and edit any, because both carry a row-level rule authored for this set (marketing_campaign_updates, marketing_campaign_member_updates, verified in src/profiles/marketing-user.profile.ts)
#709	same three files, Service Agent block	"Read accounts, contacts (editable) and leads org-wide"	the (editable) claim is dropped: reading is org-wide, saving needs owner and creator, which a contact that arrived with the account never is
#709	same three files, new section	the owner-and-creator update gate was nowhere on the page, so "org-wide" read like a write scope	Why "org-wide" describes reading, not writing — states the gate once, says View All never grants a write, and names the row-level rule as the deliberate per-object exception. No grant changed in src/; the permission expansion stays parked on #1062
sweep	.changeset/docs-truth-sweep-app-name-actions-members-permissions.md	—	one patch changeset covering all five items (see Changeset convention below)

Changeset convention for this PR shape

Conclusion: ship a changeset, do not use skip-changeset. .github/workflows/changeset-check.yml fails any PR that adds none unless the skip-changeset label is applied, and its error text reserves that label for changes that "genuinely ship nothing (pure CI/docs chores)". This repo's own precedent is unambiguous — every recent docs-truth PR shipped a 'hotcrm': patch changeset (#1019, #1014/#1011/#1015, #995, #1001, #1010). A published doc-site page is product surface here, and this PR also changes two guard tests. So: one changeset, patch, covering all five items.

Type of Change

• Documentation update
• New tests added (two guard rules: the app-name assertions and the actions count rule)

Related Issues

Six Fixes lines at the top of this body: the sweep card #1063 and its five members.

Changes Made

• 全站 22 个页面把这个应用叫 **Enterprise CRM**，而应用 label（含 app launcher 上的字）是 **HotCRM** —— 全仓零处支持这个名字 #998 — 25 occurrences across 22 doc files renamed to HotCRM; CrmApp.label joins the quick-tour guard's assertion set (block marker + launcher bullet, both derived).
• 「多少个 action」需要一个产品口径：文档写 13，注册进 stack 的是 26 #1012 — README (two locations) states the registered action count 26; docs/STATUS.md's note records the settled calibre; the [17.0-rc2验收] README 与 marketplace 文档的对象/flow 数量仍是旧值(15 objects / 23 flows),rc.2 实际为 17 / 24 #729 count guard gains an actions kind.
• Forecasting guide says the Copilot skill writes a forecast record and stores the transcript on it; revenue_forecasting writes nothing #732 — verified already true on main in all three locales; no change needed.
• campaign-members 三语文档的《Standard list views》承诺了 Members 选项卡与四个成员列表视图,元数据里一个都没有;「Add Members」选人流程同样不存在 #961 — campaign-members' «Standard list views» rewritten to the Related panel and its real columns, and the enrolment paths rewritten to Add to Campaign (lead-only) + the panel's New button, in three locales.
• 权限矩阵文档承诺了平台无法兑现的写权:marketing 的 contact 创建被 master-detail 门拒、agent/mkt 的"可编辑 contact/lead"在 owner_id+created_by 写门下不可实现 #709 — the two unfulfillable permission promises rewritten to the enforced gate in three locales, plus a section explaining the gate once.

Testing

• Unit tests pass — pnpm test: 81 files, 1889 passed | 1 skipped
• Linting passes — pnpm lint exit 0 (116 warnings, all pre-existing)
• Build succeeds — pnpm build exit 0; pnpm validate exit 0 ("Validation passed"); pnpm hygiene clean
• New tests added

Reverse verification (red before, green after) — measured on this tree, both new guard rules:

1. Put - **Enterprise CRM** — the main app… back on quick-tour.mdx:46 → predicted red on the new launcher rule only. Measured 1 failed | 41 passed: "the app-launcher list … calls this app something other than the name it ships … expected 'Enterprise CRM' to be 'HotCRM'".
2. Put **13 actions** back in the README banner → predicted red on the count rule only. Measured 1 failed | 75 passed: "README.md:62 says "13 actions", the stack registers 26 actions".

Both files were restored and the suites re-run green afterwards.

Additional Notes

• Zero changes outside the five items. git diff --stat's 33 files map 1:1 onto the checklist above.
• Out-of-scope discoveries, not fixed here: AGENTS.md:4 opens "Enterprise CRM built on the @objectstack/runtime engine" — read as a common-noun descriptor rather than the app's name, so it was left alone rather than swept in; CHANGELOG.md:197 and docs/archive/** carry the old name as historical record and must keep it.
• package.json / pnpm-lock.yaml (chore(deps): upgrade @objectstack/* 17.0.0-rc.5 → 17.0.0-rc.6 (maintainer order), and re-measure tracked upstream-mirror behavior #1059) and e2e/** (e2e: make the specs independent of who owns the seeded records (option 2 from #665) #669) untouched.
• Branch merged with origin/main (ed0ca36, fix(hotcrm): repoint crm app branding to existing icon.svg (404 on crm-logo.png / crm-favicon.ico) #1064 included) before opening.

🤖 Generated with Claude Code

https://claude.ai/code/session_011NVPRcYcPzZ6rqEhPU79dC

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 11, 2026 5:25am