Repository navigation
In-app docs, batch 2 (app package): getting started, activities, metric definitions and AI skills, plus admin setup and data import #2329
Description
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.
维护者速读
- 事由： 第 1 批只拆了现有内容；用户最常问的几件事——登录后先做什么、看板指标怎么算、AI 能帮我做什么、管理员上线要按什么顺序——应用内没有答案。
- 要做： 在主包新写 6 篇应用内文档（英文 + 中文）：上手指南、活动规则、指标口径、AI 技能，以及管理员手册里的上线清单和数据导入。
- 完成标准： 6 篇出现在「使用手册」/「管理员手册」里对应分组，中文用户看到中文；每个指标的口径与看板实际算法一致，测试守住。
Grade: priority:p3, first-touch. No defect; extends the docs surface batch 1 opens.
Size: M. Six Markdown files plus six .zh.md, book groups, one drift test.
Reader (who acts): the repo:hotcrm lane seat, after the batch-1 card closes.
Dedupe: the same hotcrm listing as the batch-1 card #2327 (2163 rows, 2026-10-27) → no card on these docs.
Governing text
- The batch-1 card's governing text (ADR-0046, ADR-0051, AGENTS.md Documentation discipline rules 5–6), and the AGENTS.md docs rule once it lands.
- The Fumadocs pages named below are a source to learn from, not to copy: they are MDX with screenshots; in-app docs are Markdown with no images.
Done when
All in src/docs/, each with a .zh.md sibling, each claimed by a group of crm_manual or crm_admin_manual:
crm_getting_started— per persona: where the app opens (the 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 landings), My Work, the approvals inbox, asking the Ask assistant. Source to learn from:content/docs/getting-started/quick-tour.mdx.crm_sales_activities— tasks, events, meetings and calls, and the automation behind them (from today'scrm_sales.md§7 plus the activity flows).crm_analytics_metrics— what win rate, pipeline coverage, churn signals and the other dashboard and report figures count, read from the datasets and cubes, not transcribed as a field roster; a test pins each stated definition to its dataset so a changed measure goes red.crm_ai_skills— what the HotCRM skills undersrc/sales/skills/andsrc/service/skills/do when the platformaskagent uses them, and their limits.crm_admin_setup(admin book) — the go-live checklist: users, positions, permission sets, demo data on or off. Source to learn from:content/docs/administration/setup.mdx.crm_admin_data_import(admin book) — import order, the uniqueness and dedupe rules the objects enforce, common refusals. Source to learn from:content/docs/guides/importing-your-data.mdx.pnpm verifygreen; a changeset; a browser pass in en and zh-CN.- ⛔ Out of scope: module docs (their own card),
content/docs/.
Requested by Leehom · project thread
Activity
objectstack-fleet commentedon Oct 28, 2026
Dispatch order · #2329 ·
repo:hotcrmseat 1 ·huangyiirene· sessionsession_01J8VVAnPkgK6CWrJa6t7Fk5· 2026-10-28T05:47ZThis order takes the slot freed by #2327, which landed as PR #2355 (
173b488). That also clears this card's onlyBlocked-by: #2327. Lane concurrency is 2, per Irene's 「后续并发降到2」, and the other slot is #2357 (the test-timeout flake). The card body is the spec. It was filed from the maintainer's own words (filing gate ③), so its scope and Done when are not re-decided here.Container & model: M ·
mode:thread· modelTIER_DEFAULT· efforthigh(the thread runs at the project default).Role file:
objectstack-ai/objectstack.claude/agents/os-dev.md. Read it in full. hotcrmAGENTS.mdbinds. Re-measure every file:line againstorigin/main(f660fd8or later).Writes:
pr_create: draft, basemain,assignees: [huangyiirene].scripts/pm/post-stamped.mjs.Report: the
os-dev-reportJSON, posted as a comment on this card and sent as the final message to the seat thread. ⛔ Start editing only after the newestClaim: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 the order)
crm_sales.mdno longer exists. Its §7 (activities) now lives in the batch-1 pages. Find it withgit grepon173b488, and move the text rather than copying it, so no page states the same rule twice.src/sales/books/crm-manual.book.ts(groups: Getting Started, Sales, Service) andcrm-admin-manual.book.ts(include: 'crm_admin_*').docs-booksinvariants green: every page is claimed by exactly one book, and the admin pages' audience is exactly the admin set.crm_getting_startedvscrm_overview. Batch 1'scrm_overviewalready opens the User Manual. Getting started goes into the same Getting Started group, ordered after the overview, and the two pages must not overlap. If they cannot be told apart, report that rather than merging them.crm_analytics_metrics. The card requires a test that pins each stated definition to its dataset or cube. Followtest/docs-lifecycle-diagrams.test.ts: read the compiled stack, never a hand-copied list../crm_x.md. Link-check now maps thecrm_overview,crm_sales_,crm_admin_,crm_service_andcrm_revenue_prefixes (.github/markdown-link-check-config.json, feat(docs): in-app Help group with three manuals and nine bilingual package docs #2355 round 2). A new prefix such ascrm_getting_,crm_analytics_orcrm_ai_needs its own anchoredsrc/docs/row there, and that file is part of your surface. App-package pages never link to a revenue or marketing page.PM mechanism assumptions (measure first, on the installed 18.2.0)
Serial constraints: #2330 (the module half of batch 2) is held until this card lands, because both edit the books and the link-check config. #2357 touches only
test/flow-campaign-enrollment.test.ts.Generated by Claude Code
objectstack-fleet commentedon Oct 28, 2026
Claim: PM loop round 1
Session:
session_01J8VVAnPkgK6CWrJa6t7Fk5Account:
huangyiireneBranch:
claude/project-thread-oe1e56Worktree:
hotcrm-issue-2329(card thread; branch is platform-designated, the measured platform exception toclaude/issue-N-slug; implementing sessionsession_01J8VVAkXhMGs3b6W5rW9ioC)Domain:
repo:hotcrm(single-lane repo, nodomain:*)Seat:
repo:hotcrm#1File surface: the six new pages
src/docs/crm_getting_started,crm_sales_activities,crm_analytics_metrics,crm_ai_skills,crm_admin_setup,crm_admin_data_import(each +.zh.md); edits to existingsrc/docs/*.md/.zh.mdonly to MOVE text the new pages take over (activities, getting-started overlap);src/sales/books/*.book.ts;.github/markdown-link-check-config.json(anchoredsrc/docs/rows for new prefixes);test/docs-*.test.tsplus one new metrics-definition test; 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 setsClause-②: no
Metadata-protocol: none
Responsibility: in-app docs batch 2, app package, as specified in the card body with the seat notes in the order
Thread-read: 6461746115
Premise: holds — re-read at claim on hotcrm
origin/mainf660fd8(order comment 6461746115)Serial constraints cleared: #2330 held blocked until this lands; #2357 touches only test/flow-campaign-enrollment.test.ts
wip(docs): AI skills, go-live checklist and data import pages; books,…
docs: getting-started assistant wording and the batch-2 changeset (#2329
objectstack-fleet commentedon Oct 28, 2026
os-dev-report
{
"issue": 2329,
"status": "done",
"branch": "claude/project-thread-oe1e56",
"pr": "#2359",
"session": "session_01J8VVAkXhMGs3b6W5rW9ioC",
"premise_still_valid": true,
"summary": "Six bilingual app-package pages in src/docs: crm_getting_started and crm_ai_skills (User Manual, Getting Started, now a curated pages list), crm_sales_activities (Sales; the Tasks section of crm_sales_opportunities moved here, not copied), crm_analytics_metrics (new Analytics group), crm_admin_setup (Admin Manual opens on it, order 0) and crm_admin_data_import. crm_admin_automation's AI-skills roster became a pointer to crm_ai_skills. Three guards read the compiled stack: every metrics definition against its measure/widget/report/formula, every skill section against its skill and action labels, the import matching table against each upsert mapping's upsertKey, each in en and zh-CN. Behaviour claims were measured on the 18.2.0 dev server; the assistant pages say Cloud/Enterprise because the open framework answers 501 for it.",
"tests": "pnpm verify at 68351e0: VERIFY_EXIT=0, Test Files 242 passed (242), Tests 4606 passed | 1 skipped (4607). Bite proofs: an English copy of crm_analytics_metrics as .zh.md gave 36 failures in docs-analytics-metrics; un-bolding 转化线索 gave 1 failure in docs-ai-skills; each restored. markdown-link-check@3.13.7 with the repo config over the 16 changed .md files: 0 dead links. Changeset tests (changeset-version-wrapper etc.) green after the changeset was added.",
"gates": "local: pnpm verify (validate, typecheck, lint, hygiene, hygiene:tokens, build, test) exit 0 captured as VERIFY_EXIT before any pipe. PR check-runs on #2359 not yet read at report time; the PR is subscribed and CI failures will be fixed on the branch.",
"dogfood_battery": "n/a — no
!in the PR title and no (narrowing) arm","mcp_calls": "5 — read-only: mcp__github__issue_read x4 (#2329 card, dispatch order, claim), mcp__github__pull_request_read x1 (get #2355, batch-1 body shape)",
"api_writes": "2 — POST /repos/objectstack-ai/objectstack/dispatches (fleet-write pr_create: draft #2359 + assignee huangyiirene, read-back identical 5530 bytes); this os-dev-report comment via post-stamped.mjs. git push not counted.",
"open_questions": [],
"out_of_scope_findings": [
"class: a · reach: REST import door, POST import of a lead row with a blank owner as admin answers owner = the importer, while src/docs/crm_sales_leads.md (batch 1) says a lead created without owner by 'web-to-lead, CSV import, API capture' is auto-assigned round-robin; content/docs/guides/importing-your-data.mdx agrees with the measurement · evidence: crm_admin_data_import states the measured behaviour, crm_sales_leads left as is (out of this card's surface) · dedupe words: round-robin, CSV import, lead owner, crm_sales_leads",
"carrier: none · noted, not filed — src/sales/objects/task.hook.ts header comment (line 10) says it 'Warns when reminder_date is after due_date' but the handler refuses with VALIDATION_FAILED 400 (stale comment)",
"carrier: none · noted, not filed — on 18.2.0 a by-name in-body doc link rewrites to /_console/docs// and leaves the app shell (same for batch-1 pages); the page renders correctly there",
"carrier: none · noted, not filed — the platform's 'You do not have access to this documentation' refusal stays English for a zh-CN rep",
"carrier: none · not measured — where the assistant panel opens (needs Cloud/Enterprise), and the import undo row limit (omitted from the page)",
"carrier: none · deviation — commits carry the harness Co-Authored-By and Claude-Session trailers; not rewritten"
]
}
objectstack-fleet commentedon Oct 28, 2026
Landed ·
repo:hotcrmseat 1 · sessionsession_01J8VVAnPkgK6CWrJa6t7Fk5· 2026-10-28T07:09ZGET /pulls/23590312803from head68351e0dc2, the head the seat ACCEPTed (6462403022).mainCI on0312803GET /commits/0312803/check-runssuccess.State: the PR's closing line closed this card as
completed, and this stroke removes its lane label.The app package's manuals gain six bilingual pages:
Three guards hold the metric, skill and import statements to the compiled stack. Follow-ups:
Generated by Claude Code