docs: P0 audit fixes — resolve contradictions, hand over the keys#3092
Merged
Conversation
Fixes the highest-leverage findings from the full docs audit (110 guide
pages reviewed against a customer-comprehension rubric).
Contradiction fixes (docs said two different things, or taught dead APIs):
- OWD: permissions-matrix table/example/callout now use the canonical four
sharingModel values (ADR-0090 D4) instead of removed legacy aliases
- referenceFilters taught as a positive example while relationships.mdx
documents it as schema-accepted-but-inert — fields.mdx now teaches
structured lookupFilters + dependsOn; property tables mark it Legacy
- percent semantics unified to fraction storage (0.85 = 85%) across
fields/decision-tree (validation-rules already had it right)
- hook input shape unified to the `{ doc }` contract (plugins tutorial
handler + test now match kernel/events.mdx)
- libsql:// removed from self-hosting env table (driver ships in Cloud,
not the open framework); backup page Turso section qualified
- api/index MCP row: actions require the author's ai.exposed opt-in
- permission-metadata: `positions` (not `roles`) is the canonical field
- common-patterns: all pattern objects now declare sharingModel and the
page warns about namespace prefixes — examples pass the gate they teach
Key handovers (previously undocumented dead-ends):
- build-with-claude-code: seeded dev admin credentials at the verify step,
npx os invocations, localhost MCP connect example
- api/index: new Authentication section (session sign-in + API keys)
- self-hosting: "First boot: create the admin" section (first signup =
bootstrap admin); fixed dead examples/docker links (also docker/README)
- vercel: warn that InMemoryDriver loses data on every cold start
- getting-started prerequisites: Node 18+ only for the scaffold path
- kernel/services-checklist: stale-status warning banner
- quick-reference: unlink two non-existent reference pages
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
对全站文档做了客户视角审计(8 个并行审计员逐页精读 110 页手写指南 + 抽样生成参考,统一评估框架:定位/可运行示例/覆盖面/闭环/AI 视角/排错)。总结论:概念层能理解,动手层会卡住。本 PR 是审计修复的第一批(P0)——全部为"文档自相矛盾/教死 API/关键钥匙缺失"类,每处都有源码依据。
矛盾修正(文档两处说法打架,或在教已死的 API)
public_read等,ADR-0090 D4 已移除 legacy 别名 —— specobject.zod.ts:940白纸黑字);原页 callout 还在说"legacy 两者皆可"lookupFilters+dependsOn;field-types/validation-rules 属性表标注 Legacyinput.first_name、测试传{doc:{...}}、kernel/events.mdx 契约是{doc}—— 三处统一到{doc}libsql://,与 env-vars/drivers 两页"不支持"矛盾(该驱动在 Cloud 仓库)—— 修正并在 backup 页限定ai.exposed— action bodies run trusted (unbounded RLS/FLS), so invoke-time is the only agent boundary (#2849) #2849 之前的旧表述,与ai.exposed治理直接冲突 —— 修正rolesis the only canonical role field"违反自家 D3 词汇冻结 —— 改positionssharingModel(含controlled_by_parent教学点)+ 页首 namespace 前缀警告钥匙补齐(此前的文档死胡同)
admin@objectos.ai/admin123);bareos→npx os;MCP 接入补 localhost 示例POST /api/v1/keys,x-api-key: osk_…)—— 此前整个 api 板块不告诉你 token 从哪来验证
pnpm --filter @objectstack/docs build✅(含 spec gen,MDX 全量编译通过)🤖 Generated with Claude Code