In-app docs, batch 1: a Help group at the end of the HotCRM menu, three books, and the four package docs split into nine with Chinese variants

Filing gate ③ a task the maintainer directed. The maintainer's words, verbatim, in the HotCRM project thread: 「hotcrm 的文档类型元数据还没有好好利用，综合评估一下应该写哪些文档，以及如何挂到菜单上」 (2026-10-27T12:09Z), then, on the evaluation, 「同意，立卡派发。」 and 「立卡，你不需要派发」 (2026-10-27T12:54Z). The evaluation (Chinese, Claude Doc): https://claude.ai/artifact/FSRbbgsT8uFhTxYe5jMBvS. Filed from that thread (session_01FEkQ5n3dhGrDN5nEgsJyck). ⛔ Not a claim: the filing session does not dispatch.

维护者速读

事由： HotCRM 的应用内文档（doc 元数据）只有 4 篇英文，没有目录（book），菜单上没有入口，用户只能从平台通用的 Documentation 门户碰巧找到。
要做： 在 HotCRM 菜单最末尾加一个折叠的「帮助」分组，挂「使用手册」「管理员手册」「收入手册」三本书；把现有 4 篇按主题拆成 9 篇，各配中文版，报价和服务的文档放进各自模块目录。
完成标准： pnpm dev 后，销售代表在菜单最底部看到「帮助 › 使用手册」，切到中文看到中文正文；管理员额外看到「管理员手册」，非管理员看不到也读不到；各角色登录后的落地页不变。

Grade: priority:p3, first-touch. No defect. It is the lane's first exhibit of the ADR-0046 docs surface beyond the bare doc: book with derived membership, book.audience, a type: 'doc' navigation item, a module's doc entry through navigationContributions, per-package src/<pkg>/docs/, locale variants and ADR-0051 ```metadata embeds. The maintainer can overrule the grade in one word.

Size: M. Nine Markdown files plus nine .zh.md, three defineBook files, one nav group, one contribution, four locale-pack lines, two tests.

Reader (who acts): the repo:hotcrm lane seat, which dispatches it. Ordering: before the revenue carve-out #2271, so that card moves an already-split src/revenue/docs/ with its package.

Dedupe: REST listing of all hotcrm issues and PRs (state=all, page=1..25, 2163 rows, 2026-10-27), title grep in-app|src/docs|package doc|book|ADR-0046|help|manual|handbook → no open hit; closed: #386 (added the four docs in 1.1.0), #875 (a wording fix in crm_sales.md), #1138 (copyright headers). No card on books, doc navigation or doc locales.

Governing text

ADR-0046 (objectstack docs/adr/0046-package-docs-as-metadata.md): flat docs/*.md, filename = name, no images (docs/no-images), no MDX (docs/no-mdx), §3.5 derived content is rendered, never written; §6 book is a spine with derived membership; §6.7 book.audience (org | public | { permissionSet }), enforced at the REST read layer; a doc's effective audience is the union over the books that claim it.
ADR-0051: a ```metadata fenced block lifts into element:metadata_viewer (types `state_machine`, `flow`, `permission`; `object` deferred).
@objectstack/spec ui/app.zod.ts DocNavItemSchema: { type: 'doc', book?, doc? }, at least one; an entry the member cannot read is not rendered; the CLI lint docs/nav-target checks targets, navigationContributions included.
hotcrm AGENTS.md: src/docs/ is the platform's path, not a package's (the app package's docs stay in src/docs/; src/service/, src/revenue/, src/marketing/ answer to their package ids' last segment); Documentation discipline rules 5–6 (no hand-copied machine lists; zh-CN pack wording for view names, English for tile titles).
src/sales/apps/crm.app.ts navigation header: the order IS each persona's landing (Browser pass #2058 — HotCRM-side defects (18 items: accepted quote still takes lines, half-converted leads, agents losing their cases, unreachable Sales Home, …) — list card, split per item at dispatch #2060); ⛔ no entry a service persona can see ahead of the Service group. test/app-navigation-audience.test.ts pins the landings.

Platform readings first (filed upstream if any refuses — ⛔ never worked around here)

On the installed 18.2.0, a metadata block (`type: state_machine`, `object: crm_case`) in a doc renders in the console doc page. ADR-0051's status line still says the console fence-lift is not implemented while `ui/packages/plugin-markdown/src/MarkdownImpl.tsx` carries it; measure which is true on the pin. If it does not render, use a mermaid block for that diagram and report the reading (the seat files the platform card).
A book with audience: { permissionSet: 'tenant_admin' }: a sales rep's GET /api/v1/meta/book/crm_admin_manual/tree and GET /api/v1/meta/doc/crm_admin_access are refused, and the type: 'doc' nav entry is not drawn for the rep. Record whether system_admin also reads it (one permission set per audience).
A doc of app.objectstack.hotcrm.service is claimed by a group of the app package's book through package: 'app.objectstack.hotcrm.service'.

Record each command and observation in the PR body.

Done when

src/docs/ (app package): crm_overview rewritten (four areas, the lifecycle as a diagram, which persona reads what), crm_sales_leads, crm_sales_opportunities, crm_sales_contracts (contract moved to the app package in refactor(contract): move crm_contract and its items from revenue into the app package #2323), crm_admin_access, crm_admin_automation, each split from today's crm_sales.md / crm_admin.md; crm_sales.md and crm_admin.md removed once every section has a new home.
src/service/docs/: crm_service_cases, crm_service_knowledge (from today's crm_service.md, which is removed). src/revenue/docs/: crm_revenue_quotes (from crm_sales.md §5; if Print quote: a print page for crm_quote and a print_quote action on service-print, the archived PDF setting the quote to presented (REQ-0008 phase 1) #2312 has landed, it also covers Print quote).
Every one of the nine has a <name>.zh.md sibling (resolves zh-CN by primary subtag); AGENTS.md rule 6 wording applies.
ASCII diagrams replaced by metadata embeds of the real `crm_lead` / `crm_opportunity` / `crm_contract` / `crm_quote` / `crm_case` state machines and the flows the text describes, or by mermaid where reading 1 refuses. Field and option lists are not hand-copied.
Books: crm_manual (groups: start, sales, service with package: scope; every doc claimed by a group, none in Uncategorized), crm_admin_manual (audience: { permissionSet: 'tenant_admin' } unless reading 2 says otherwise), crm_revenue_manual in the revenue package.
Navigation: crm.app.ts declares group_help as its LAST entry, collapsed, children { type: 'doc', book: 'crm_manual' } and { type: 'doc', book: 'crm_admin_manual' }; src/revenue/index.ts contributes { type: 'doc', book: 'crm_revenue_manual' } into group_help. Labels in all four locale packs.
App-package docs never link to a revenue or marketing doc (they can be uninstalled after ADR-0141); the reverse direction may.
Tests: test/docs-drift.test.ts (and the sources: frontmatter) follow the thresholds to their new files; a new test fails when a doc is claimed by no book group or a book has no type: 'doc' entry; test/app-navigation-audience.test.ts and test/app-navigation-shape.test.ts green with the landings unchanged.
pnpm verify green; a changeset; a browser pass (rep, service agent, admin; en and zh-CN) with screenshots in the PR.
⛔ Out of scope: the new docs of batch 2 (their own cards), AGENTS.md (its own card, governed surface), the marketing book (no batch-1 marketing doc), content/docs/ (the Fumadocs site is unchanged).

Requested by Leehom · project thread

Dispatch order · #2327 · repo:hotcrm seat 1 · huangyiirene · session session_01J8VVAnPkgK6CWrJa6t7Fk5 · 2026-10-27T23:24Z

This order takes the slot freed by #2334 (PR #2342, ACCEPTed with auto-merge armed). Irene asked for dispatch to continue (「继续派发」) at lane concurrency 5. The card body is the spec. It was filed from the maintainer's own words (filing gate ③), so the scope and the Done when are not re-decided here.

Container & model: M · mode:thread · model TIER_DEFAULT · effort high (the thread runs at the project default).
Role file: objectstack-ai/objectstack .claude/agents/os-dev.md. Read it in full. hotcrm AGENTS.md binds. Re-measure every file:line against origin/main (0f17c6c or later).
Writes:

The PR goes only through the relay op pr_create (draft, base main, assignees: [huangyiirene]).
Comments go only through scripts/pm/post-stamped.mjs.
⛔ No GitHub MCP write. ⛔ No issue filing: out-of-scope findings and platform refusals go in the report.
The write budget is tight, so make two writes: the PR and the report.

Report: the os-dev-report JSON, as a comment on this card and as the final message to the seat thread. ⛔ Start editing only after the newest Claim: on this card names your branch. Push work in progress at each milestone, so a stop loses nothing.

Seat notes on the card (premise re-read at claim)

Print quote: a print page for crm_quote and a print_quote action on service-print, the archived PDF setting the quote to presented (REQ-0008 phase 1) #2312 has not landed. Print Quote waits on a platform release (draft PR feat(revenue): Print Quote files the quote's PDF and presents the quote #2332). So crm_revenue_quotes does not cover Print quote.
fix(opportunity): a large deal whose approval was rejected can never be resubmitted, and closes won with no approval #2334 (PR fix(opportunity): resubmit a rejected large deal on the next save, refuse its close-won, and stop recall re-submitting #2342) changes src/docs/crm_sales.md §4. It changes the approvals paragraph: rejected and recalled deals, the resubmit on save, and the close-won refusal. If fix(opportunity): resubmit a rejected large deal on the next save, refuse its close-won, and stop recall re-submitting #2342 lands before you split the file, carry its wording into crm_sales_opportunities. If it lands after, merge origin/main and move that paragraph before the PR. ⛔ Do not lose it in the split.
Browser pass #2320 on 18.2.0 — HotCRM-side defects (13 items: dashboards shown to personas with no access, a dead-end case close, campaign editors who cannot edit, a toolbar action that always fails, …) — list card, split per item at dispatch #2338 items 1–4 (PR fix: four dead ends from the 18.2.0 browser pass (#2338 items 1-4) #2346) touch crm.app.ts (a header comment) and test/app-navigation-audience.test.ts. Your Help group touches both. Whichever lands second merges origin/main and re-runs the audience test.
The three platform readings in the card come first. A refusal is reported with the command and the observation, then worked around only as the card allows: mermaid for reading 1. ⛔ No other workaround. The seat files the platform card.

PM mechanism assumptions (measure first, on the installed 18.2.0)

The card's platform readings 1–3, as written.
A collapsed nav group as the LAST entry leaves every persona's landing unchanged. test/app-navigation-audience.test.ts pins the landings.

Suggested route (optional)

Run the readings.
Split the docs and write the zh siblings.
Add the books and the navigation entries.
Add the tests, the changeset, and a browser pass (rep, service agent, admin; en and zh-CN) with screenshots.

Serial constraints: the three notes above. #2242 edits the forecast docs under content/docs/, which this card does not touch.

Generated by Claude Code

Claim: PM loop round 1
Session: session_01J8VVAnPkgK6CWrJa6t7Fk5
Account: huangyiirene
Branch: claude/project-thread-4tg14s
Worktree: hotcrm-issue-2327 (card thread; branch is platform-designated, the measured platform exception to claude/issue-N-slug; implementing session session_01J8VVAn2ZxhfvpehmexXYC6)
Domain: repo:hotcrm (single-lane repo, no domain:*)
Seat: repo:hotcrm#1
File surface: the card's Done when surface: src/docs/, src/service/docs/, src/revenue/docs/ (nine docs plus .zh.md siblings; crm_sales.md, crm_admin.md, crm_service.md removed), three defineBook files, crm.app.ts group_help, src/revenue/index.ts nav contribution, the four locale packs' nav labels, the docs tests, one changeset (stop on breach; explain in the report)
Container & model: M, mode:thread, model: TIER_DEFAULT (sister repo, hand-derived), effort: the order asked high; the thread runs at the project default, which only the maintainer sets
Clause-②: no
Metadata-protocol: none
Responsibility: in-app docs batch 1 as specified in the card body, with the seat notes in the order
Thread-read: 6456080957
Premise: holds — re-read at claim on hotcrm origin/main a31d91a (order comment 6456080957)
Serial constraints cleared: #2346 (crm.app.ts comment + app-navigation-audience test) and #2347 may land first; whichever lands second merges origin/main. #2342 landed at a31d91a: carry its crm_sales.md §4 approvals wording into the split

chore(changeset): carry the claim's Clause-② and Metadata-protocol li…

os-dev-report

{
  "issue": 2327,
  "status": "done",
  "branch": "claude/project-thread-4tg14s",
  "pr": "https://github.com/objectstack-ai/hotcrm/pull/2355",
  "session": "session_01J8VVAn2ZxhfvpehmexXYC6",
  "premise_still_valid": true,
  "summary": "HotCRM's sidebar ends with a collapsed Help group: User Manual (crm_manual, every member), Admin Manual (crm_admin_manual, gated on system_admin, swapped to tenant_admin by the saas composition) and Revenue Manual (crm_revenue_manual, contributed by the revenue module). crm_sales/crm_admin/crm_service are split into nine pages across src/docs, src/service/docs and src/revenue/docs, each with a .zh.md sibling; the five lifecycle diagrams are mermaid stateDiagram-v2 held to the compiled state machines by a new test, because 18.2.0 refuses metadata embeds in this artifact. Merged origin/main 3801c17 (quick-tour row conflict resolved; main's new Forecasts sharing-rule row carried into crm_admin_access and its zh sibling). Declared surface extensions: objectstack.composition.ts (book registration + saas audience swap), comment-pointer fixes in opportunity.actions.ts, opportunity.hook.ts, opportunity-stagnation.flow.ts, _thresholds.ts and test/private-opportunity-derived-records.test.ts, the saas-composition / app-navigation-shape / docs-quick-tour-navigation test edits, and content/docs/getting-started/quick-tour (en, zh-Hans, zh-Hant) Help row, accepted by the seat.",
  "tests": "New test/docs-books.test.ts (8) and test/docs-lifecycle-diagrams.test.ts (11); after the merge, nav/audience/shape + docs + saas suites: Test Files 8 passed (8), Tests 193 passed (193). Ablation, one-shot on disk after commit, each restored with git checkout HEAD -- PATH, git status and git diff HEAD empty after: A1 illegal arrow accepted to draft in quotes.md → 1 failed | 10 passed; A2 zh label 草稿→草案 → 1 failed | 10 passed; A3 crm_manual group include crm_admin_* → admin-audience case red, 1 failed | 7 passed; A4 rename crm_sales_contracts → unclaimed case red, 1 failed | 7 passed; A5 drop nav_help_admin → one-entry-per-book case red, 1 failed | 7 passed; A6 composition without the saas swap → saas tenant_admin case red, 1 failed | 20 passed. Browser pass (Playwright, dev server from the branch, demo staff seeded): admin / na.rep / service.agent × en / zh-CN: Help last and collapsed after Reports; admin sees 3 entries, rep and agent 2 (no Admin Manual); landings unchanged (Executive Overview / Sales Home / Service Overview); zh pages render Chinese; mermaid renders svg[aria-roledescription=stateDiagram] with locale labels; rep opening the admin doc URL reads 'You do not have access to this documentation'. Screenshots in project files issue-2327/.",
  "gates": "Local: pnpm verify at d9b47b3 exit 0 (captured before any pipe) — Test Files 239 passed (239), Tests 4583 passed | 1 skipped (4584). d23812d (changeset Clause-②/Metadata-protocol lines only): test/changeset-version-wrapper.test.ts 4/4. Not run under scripts/pm/os-verify-lock.sh (hotcrm verify, single run). PR #2355 check-runs at report time (head d23812d): Vercel Preview Comments success, Label Pull Request success; link-check, Typecheck and Build, Analyze Code (javascript), Build and Test (22.x), Playwright, Quality Checks, Check Changeset in_progress. main moved to 08bbdd5 (#2354) after the merge, no file in common; CI's merge ref is that reading.",
  "dogfood_battery": "n/a — no `!` in the PR title and no (narrowing) arm",
  "mcp_calls": "15 — reads only: mcp__github__issue_read, mcp__github__pull_request_read, mcp__github__get_file_contents; no write tool",
  "api_writes": "2 — relay pr_create (POST /repos/objectstack-ai/hotcrm/pulls draft + POST /repos/objectstack-ai/hotcrm/issues/2355/assignees), request fw-20261028T045234Z-c34175, read-back identical 12843 bytes, assignee huangyiirene; this report via post-stamped (POST /repos/objectstack-ai/hotcrm/issues/2327/comments). git push is not a REST write.",
  "open_questions": [],
  "out_of_scope_findings": [
    "class: b · reach: public door — `objectstack build` of hotcrm's multi-package artifact refuses every metadata code-fence state_machine/flow embed, including the service package's own doc naming its own crm_case ('references object \"crm_case\", which does not exist in this package', rule docs/metadata-embed-ref); ADR-0051 embeds are unusable in any multi-package artifact on 18.2.0 · Seam: spec:docs metadata embed → runtime:lint docs/metadata-embed-ref (looks up the artifact top level) · dedupe words: metadata-embed-ref, multi-package, package docs embed, state_machine embed",
    "class: a · reach: public door — console book page: per-book Uncategorized lists same-package docs claimed by a SIBLING book (admin sees crm_admin_access/crm_admin_automation under the User Manual's Uncategorized and the app user pages under the Admin Manual's; GET /api/v1/meta/book/crm_manual/tree as admin returns an 'uncategorized' group with both admin docs) · dedupe words: Uncategorized, book tree, sibling book, resolveBookClaimedDocs",
    "carrier: objectstack#26819 · book and group label translation (no books namespace in 18.2.0): book title and group headings show English to zh-CN users · noted, not filed",
    "carrier: none · a book audience naming a permission set the stack does not declare fails closed for everyone, including admins (build warns security-book-audience-unknown-set; tree 403 to admin) — working as designed, handled by the composition swap · noted, not filed"
  ]
}

ci(link-check): resolve by-name package doc links to the directory ea…

Landed · repo:hotcrm seat 1 · session session_01J8VVAnPkgK6CWrJa6t7Fk5 · 2026-10-28T05:45Z

Reading	Probe	Result
PR #2355	`GET /pulls/2355`	Merged 2026-10-28T05:04Z as `173b488` from head `5b073311fe`. The seat ACCEPTed that head (6461114582) after review round 2.
`main` CI on `173b488`	`GET /commits/173b488/check-runs`	Build and Test (22.x) `failure`: 1 of 4591 tests, `test/flow-campaign-enrollment.test.ts:424` timed out at 5 s. The same case also flaked on `0f17c6c`. This diff does not touch it, and the seat filed it as #2357. The other 5 runs are `success`.
`main` CI on `f660fd8`	`GET /commits/f660fd8/check-runs`	All 5 runs `success`. `f660fd8` is the next main commit (#2356), on top of this tree.

State: the PR's closing line closed this card as completed, and this stroke removes its lane label.

HotCRM's sidebar now ends with a collapsed Help group, which holds three manuals:

User Manual: for every member.
Admin Manual: for the admin set; under saas, tenant_admin.
Revenue Manual: contributed by the revenue module, so it leaves with it.

The nine bilingual pages replace crm_sales, crm_admin and crm_service. Platform follow-ups: objectstack#27090 (metadata embeds) and objectstack#27091 (sibling-book Uncategorized). Batch 2 is next: #2329 is unblocked in this stroke, and #2330 now waits on #2329.

Generated by Claude Code

Navigation Menu

Repository navigation

In-app docs, batch 1: a Help group at the end of the HotCRM menu, three books, and the four package docs split into nine with Chinese variants #2327

维护者速读

Governing text

Platform readings first (filed upstream if any refuses — ⛔ never worked around here)

Done when

Seat notes on the card (premise re-read at claim)

PM mechanism assumptions (measure first, on the installed 18.2.0)

Suggested route (optional)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

In-app docs, batch 1: a Help group at the end of the HotCRM menu, three books, and the four package docs split into nine with Chinese variants #2327

Description

维护者速读

Governing text

Platform readings first (filed upstream if any refuses — ⛔ never worked around here)

Done when

Activity

objectstack-fleet commented on Oct 27, 2026

Seat notes on the card (premise re-read at claim)

PM mechanism assumptions (measure first, on the installed 18.2.0)

Suggested route (optional)

objectstack-fleet commented on Oct 27, 2026

objectstack-fleet commented on Oct 28, 2026

objectstack-fleet commented on Oct 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions