docs(sharing): describe the record-level access the app really ships (#549)

[yinlianghui]

Description

A sharing rule widens the object it names, never the records hanging off it. HotCRM authors its widening rules on crm_account only (north_america_territory, europe_territory, account_team_sharing), so a rep who receives an account through a territory rule reads the account and its contacts (controlled_by_parent) — while the quotes, contracts and tasks on it stay own-only and opportunities widen only through the ≥ $100k leadership rules.

The docs claimed otherwise. contracts.mdx promised "Contracts follow the account's sharing — if you can see the account, you can see its contracts", the security doc documented an account-team roster and a Team tab this app does not ship, and the FAQ told users to ask for a seat on that team. That is the declaration-vs-reality half of #549 and it is what this PR fixes.

No permission set, OWD or sharing rule changed. Whether quotes, contracts and tasks should follow the account is the business decision the issue asks for; the options and their costs are written up in a comment on #549.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• CI/CD update

Related Issues

Related to #549 (the record-level decision stays open), follows #547.

Changes Made

• Sharing & Security (en + zh-Hans + zh-Hant): new "A rule widens one object, not the records underneath it" section with a per-related-list table of what a shared account actually carries; Layer 4 restated as Manual shares (the platform feature that exists) with an explicit note that no account-team object or Team tab ships and that Account Team Sharing is an ordinary criteria rule for sales_manager; the "you're on the account team" combine-rule and user tip replaced.
• Contracts (3 locales): owner-only visibility documented, including who does hold View All, and what an admin would have to author to change it.
• FAQ (3 locales): the account-team diagnostic step replaced with parent-derivation / sharing-rule / manual-share steps, plus a note that a shared account carries its contacts and nothing else.
• src/docs/crm_admin.md: the Account Team rule row says what it grants; a paragraph records the own-only reach of the account's children and points at the open decision.
• sales-rep / service-agent profiles: comments no longer claim cross-team visibility that no sharing rule delivers, and warn against widening the grants to paper over Sharing coverage gap: territory/team-shared accounts show quote, task and contract related lists the rep cannot read #549.
• test/sharing-coverage.test.ts (new): guards described below.

Testing

• Unit tests pass (pnpm test — 646 passed, 1 skipped)
• Linting passes (pnpm lint)
• Build succeeds (pnpm build)
• Manual testing completed — pnpm verify (validate → typecheck → lint → hygiene → build → test) green
• New tests added (if applicable)

test/sharing-coverage.test.ts holds a ledger of every object hanging off crm_account, classified derived / partial / own_only, and asserts:

• the ledger covers exactly the objects that hang off the account (a new child object fails until someone decides its reach);
• the ledger matches the shipped OWD + sharing rules, and no rule widens a child by account criteria behind its back;
• sales_rep / service_agent keep own scope on the own-only children (no silent viewAllRecords);
• the docs' rule table matches src/sharing/ rule-for-rule (object, access level, position), the positions block matches CrmPositions, and the related-list table's promises match the ledger;
• no product doc promises account-derived visibility for an object the metadata keeps own-only — the exact defect reported in Sharing coverage gap: territory/team-shared accounts show quote, task and contract related lists the rep cannot read #549.

Both directions were negative-tested: flipping a ledger entry and restoring the old contracts.mdx sentence each turn the suite red.

Screenshots

n/a — documentation and test-only change.

Checklist

• I have added a changeset (.changeset/sharing-coverage-docs-truth.md)
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

Two adjacent defects were found and deliberately left alone — each is the same "docs describe something that isn't shipped" class but a different subject, and folding them in would bury the sharing fix:

1. Phantom Competitor object. The OWD table lists Competitor — Public Read-Only, and profiles.mdx has three personas reading "competitor battlecards". No such object exists; competitors are a picklist on crm_opportunity.
2. Role-hierarchy roll-up prose. ADR-0090 D3 made positions flat, but ~38 lines across ~13 doc pages (× 3 locales) still say access flows "up the role hierarchy" or to "managers and their subordinates". sharing-and-security.mdx already states the flat rule, so the feature docs contradict it.

Both are worth their own issues.

---

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 1, 2026 2:13am