docs(setup): slim the Setup overview to the genuinely-invisible rules

.changeset/setup-doc-slim.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/setup": patch
+---
+
+docs(setup): slim the Setup overview to the genuinely-invisible rules
+
+Cut the textbook concept-restatement (permission-set vs role definitions) and
+the repeated "see external docs" lines that duplicated what the Setup UI's own
+Users/Roles/Permission-set screens already show. What remains is three short
+bullets the screens *don't* reveal: a user is identity-not-access, permissions
+are additive, and "can't see a record" is almost always sharing rather than
+object permissions. EN + zh updated together. No behaviour change — content only.

packages/apps/setup/src/setup-overview.doc.ts

@@ -9,78 +9,59 @@ import type { Doc } from '@objectstack/spec/system';
  * Authored inline rather than as a flat `src/docs/*.md` file because this is a
  * TS-first code package built by tsup, not a user app built by `os build` —
  * `defineStack({ docs })` / manifest `docs[]` is the supported path for those
- * (see `DocSchema` in `@objectstack/spec/system`). The `content` below is plain
- * CommonMark + GFM with no images/MDX, per ADR-0046 §3.4.
+ * (see `DocSchema` in `@objectstack/spec/system`). Plain CommonMark + GFM, no
+ * images/MDX, per ADR-0046 §3.4.
  *
- * Principle (from the HotCRM reference docs): document the *invisible* concepts,
- * not what the Setup UI already shows on screen.
+ * Principle (from the HotCRM reference docs): document only the *invisible*
+ * rules, not what the Setup UI already shows. Deliberately three short bullets —
+ * the Users/Roles/Permission-set screens cover the rest; this page exists for
+ * the handful of behaviours those screens don't reveal.
  *
  * `translations` carries per-locale variants (ADR-0046 i18n); the REST layer
  * collapses the doc to the request's `Accept-Language` and serves one body.
  */
 export const SETUP_OVERVIEW_DOC: Doc = {
   name: 'setup_overview',
   label: 'Setup overview',
-  description: 'Orientation for administrators: users, roles & permissions, and record visibility.',
+  description: 'The non-obvious rules behind Setup: identity vs access, additive permissions, and record visibility.',
   content: `# Setup overview
 
-Setup is the administrator app for the platform. Its screens are mostly
-self-explanatory — this page covers the concepts behind them that the UI does
-not make obvious. For the full reference, see <https://docs.objectstack.ai>.
-
-## Users & authentication
-
-Every person who signs in is a \`sys_user\` record. Authentication (passwords,
-SSO, API keys, sessions) is handled by the platform's auth layer, so creating a
-user here grants *identity*, not access — what they can do is decided entirely
-by the roles and permissions assigned to them. Deactivating a user revokes
-sign-in without deleting their records, preserving ownership and history.
-
-## Roles & permissions
-
-Permission sets define *what* a user can do (which objects and fields they can
-read or write, which apps they can open); roles place a user in the
-organization hierarchy and drive *which records* they can reach. A user's
-effective access is the union of all permission sets granted to them — access is
-additive, so you grant capability rather than taking it away.
-
-## Record visibility (sharing)
-
-Object-level permissions decide whether a user can touch a *kind* of record;
-sharing decides *which* rows of that kind they actually see. Visibility starts
-from an org-wide default (private or public) and is then widened by the role
-hierarchy and explicit sharing rules — it is never silently narrowed. When a
-user "can't see a record they should," the cause is almost always sharing, not
-object permissions.
+Setup is the administrator app. Its screens are mostly self-explanatory — these
+are the few rules behind them that the UI does not show. For everything else,
+see <https://docs.objectstack.ai>.
+
+- **A user is identity, not access.** Creating a \`sys_user\` lets someone sign
+  in; *what* they can do comes entirely from the roles and permission sets you
+  then assign. Deactivating a user revokes sign-in without deleting their
+  records, so ownership and history survive.
+- **Access is additive.** A user's effective permissions are the *union* of
+  every permission set granted to them — you grant capability, you never
+  subtract it.
+- **"Can't see a record" is almost always sharing, not permissions.**
+  Object-level permissions decide which *kinds* of records a user can touch;
+  sharing decides *which rows*. Visibility starts from the org-wide default and
+  is only ever widened by the role hierarchy and sharing rules — never silently
+  narrowed.
 
 See <https://docs.objectstack.ai> for the full security model.
 `,
   translations: {
     zh: {
       label: 'Setup 概览',
-      description: '管理员入门:用户、角色与权限、记录可见性。',
+      description: 'Setup 背后看不见的几条规则:身份≠权限、权限叠加、记录可见性。',
       content: `# Setup 概览
 
-Setup 是平台的管理员应用。它的界面大多一目了然——本页讲的是界面背后、UI 没有
-明说的概念。完整参考见 <https://docs.objectstack.ai>。
-
-## 用户与认证
-
-每个登录的人都是一条 \`sys_user\` 记录。认证(密码、SSO、API Key、会话)由平台
-的认证层负责,所以在这里创建用户给的是*身份*,不是权限——他能做什么,完全由分配
-给他的角色和权限决定。停用用户会收回登录权,但不删除其记录,从而保留归属与历史。
-
-## 角色与权限
-
-权限集定义用户*能做什么*(可读写哪些对象和字段、能打开哪些应用);角色把用户放进
-组织层级,决定他*能触及哪些记录*。用户的最终访问权是其所有权限集的并集——权限是
-叠加的,你是在授予能力,而不是在收回能力。
-
-## 记录可见性(共享)
-
-对象级权限决定用户能否操作某*类*记录;共享决定他实际能看到该类记录中的*哪些行*。
-可见性从组织级默认(私有或公开)出发,再由角色层级和显式共享规则*放宽*——绝不会被
-悄悄收窄。当用户"看不到本该看到的记录"时,原因几乎总是共享,而不是对象权限。
+Setup 是管理员应用。它的界面大多一目了然——下面这几条是界面背后、UI 没有明说的
+规则。其余内容见 <https://docs.objectstack.ai>。
+
+- **用户是身份,不是权限。** 创建一条 \`sys_user\` 只是让人能登录;他*能做什么*
+  完全由你随后分配的角色和权限集决定。停用用户会收回登录权,但不删除其记录,
+  归属与历史因此得以保留。
+- **权限是叠加的。** 用户的最终权限是其所有权限集的*并集*——你是在授予能力,
+  从不做减法。
+- **"看不到某条记录"几乎总是共享问题,不是权限问题。** 对象级权限决定用户能碰
+  *哪类*记录;共享决定*哪些行*。可见性从组织级默认出发,只会被角色层级和共享规则
+  *放宽*,绝不会被悄悄收窄。
 
 完整安全模型见 <https://docs.objectstack.ai>。
 `,