Skip to content

Commit 28f8993

Browse files
committed
fix(spec): api, doc and book descriptions say only what the code does
api names the two endpoint types that execute (flow, object operation); doc and book drop the package-only clause, since both are runtime-creatable. Claude-Session: https://claude.ai/code/session_014SHyy7c7ipsMkzJ3J9mdL9 Co-authored-by: Claude <noreply@anthropic.com>
1 parent b625ac4 commit 28f8993

6 files changed

Lines changed: 21 additions & 21 deletions

File tree

‎.changeset/23808-type-descriptions-plain.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ Clause-②: no
88
The `description` of four metadata types in `DEFAULT_METADATA_TYPE_REGISTRY`, which Setup shows under the
99
type's title, is now one plain sentence for an administrator instead of ADR vocabulary:
1010

11-
- `api`: "A stable HTTP URL that other systems call to reach flows, scripts and data in the app"
12-
- `doc`: "A help page written in Markdown that a package ships for its users to read"
13-
- `book`: "A table of contents that groups the help pages of a package into ordered sections"
11+
- `api`: "A stable HTTP URL that other systems call to run a flow or work with records in the app"
12+
- `doc`: "A help page written in Markdown that a package ships or you write yourself"
13+
- `book`: "A table of contents that groups help pages into ordered sections"
1414
- `capability`: "A permission a package defines; you grant it through permission sets"
1515

1616
The ADR references (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) moved to the comments beside the

‎packages/platform-objects/src/apps/translations/bare-type-display-echo-decisions.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -312,10 +312,10 @@ const DECISIONS: readonly Decision[] = [
312312
scope: 'type',
313313
key: 'api',
314314
prop: 'description',
315-
en: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app',
315+
en: 'A stable HTTP URL that other systems call to run a flow or work with records in the app',
316316
verdict: ALL_TRANSLATE,
317317
reason:
318-
'REWRITTEN AS PLAIN ADMIN COPY: the registry description is what Setup shows, so it says what the item is and who uses it, and the ADR-0121 vocabulary (declarative endpoint, policy layer, pipeline) moved to the comment beside the registry row. "flows, scripts and data" names what ApiEndpointSchema.type can target (flow/script/object_operation; proxy is the rare fourth) in words an admin reads. ⇒ 其他系统调用的稳定 HTTP URL,用于访问应用的流程、脚本和数据 / 他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL / URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación. ⭐ `HTTP` and `URL` stay machine tokens in all three, asserted by the token guard below. ⚠️ No second person in zh/ja/es: the catalog carries no 你的/您的, so "the app" is rendered 应用 / アプリ / la aplicación.',
318+
'REWRITTEN AS PLAIN ADMIN COPY: the registry description is what Setup shows, so it says what the item is and who uses it, and the ADR-0121 vocabulary (declarative endpoint, policy layer, pipeline) moved to the comment beside the registry row. It names only what EXECUTES: ApiEndpointSchema.type says only `flow` and `object_operation` run, while `script` and `proxy` are rejected at publish, so "run a flow or work with records" is the whole servable set in an admin\'s words. "records" takes the catalog\'s record noun (记录 / レコード / registros). ⇒ 其他系统调用的稳定 HTTP URL,用于运行流程或操作应用中的记录 / 他のシステムが呼び出す固定の HTTP URL。フローを実行したり、アプリのレコードを操作したりします / URL HTTP estable a la que llaman otros sistemas para ejecutar un flujo o trabajar con los registros de la aplicación. ⭐ `HTTP` and `URL` stay machine tokens in all three, asserted by the token guard below. ⚠️ No second person in zh/ja/es: the catalog carries no 你的/您的.',
319319
},
320320
{
321321
scope: 'type',
@@ -330,10 +330,10 @@ const DECISIONS: readonly Decision[] = [
330330
scope: 'type',
331331
key: 'doc',
332332
prop: 'description',
333-
en: 'A help page written in Markdown that a package ships for its users to read',
333+
en: 'A help page written in Markdown that a package ships or you write yourself',
334334
verdict: ALL_TRANSLATE,
335335
reason:
336-
'REWRITTEN AS PLAIN ADMIN COPY: "flat Markdown items (ADR-0046)" became what an admin meets, a help page, and the ADR reference moved to the comment beside the registry row. `package` is still rendered as the noun, by the near-miss clearing asserted below (zh prose takes 软件包, as in 软件包层). ⇒ 软件包随附的 Markdown 帮助页面,供用户阅读 / パッケージに同梱される、ユーザー向けの Markdown ヘルプページ / Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios. ⭐ `Markdown` is KEPT as a format proper noun in all three; asserted by the token guard.',
336+
'REWRITTEN AS PLAIN ADMIN COPY: "flat Markdown items (ADR-0046)" became what an admin meets, a help page, and the ADR reference moved to the comment beside the registry row. Both origins are named because the registry row is `allowRuntimeCreate: true`: a doc can be shipped by a package or drafted in place through saveMetaItem. `package` is still rendered as the noun, by the near-miss clearing asserted below (zh prose takes 软件包). zh/ja/es carry the second origin impersonally (自行编写 / 自分で作成 / redactada directamente). ⇒ 以 Markdown 编写的帮助页面,可由软件包随附,也可自行编写 / Markdown で書かれたヘルプページ。パッケージに同梱されるほか、自分で作成することもできます / Página de ayuda en Markdown, incluida en un paquete o redactada directamente. ⭐ `Markdown` is KEPT as a format proper noun in all three; asserted by the token guard.',
337337
},
338338
{
339339
scope: 'type',
@@ -348,10 +348,10 @@ const DECISIONS: readonly Decision[] = [
348348
scope: 'type',
349349
key: 'book',
350350
prop: 'description',
351-
en: 'A table of contents that groups the help pages of a package into ordered sections',
351+
en: 'A table of contents that groups help pages into ordered sections',
352352
verdict: ALL_TRANSLATE,
353353
reason:
354-
'REWRITTEN AS PLAIN ADMIN COPY: "navigation spine — ordered groups with derived membership (ADR-0046 §6)" became a table of contents, and the ADR-0046 §6 vocabulary moved to the comment beside the registry row. "help pages" is the same phrase the doc row now uses, so the two types read as a pair in every locale. "sections" is prose, not BookSchema.groups (a key that takes an array, asserted below). ⇒ 将软件包的帮助页面按顺序分节组织的目录 / パッケージのヘルプページを順序付きのセクションにまとめた目次 / Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas. No machine token is kept: the ADR citation and its §6 are exactly what this rewrite removed, asserted by the plain-copy guard below.',
354+
'REWRITTEN AS PLAIN ADMIN COPY: "navigation spine — ordered groups with derived membership (ADR-0046 §6)" became a table of contents, and the ADR-0046 §6 vocabulary moved to the comment beside the registry row. No package clause: the row is `allowRuntimeCreate: true` and a brand-new book can be authored in place. "help pages" is the doc row\'s own phrase, so the two types read as a pair in every locale. "sections" is prose, not BookSchema.groups (a key that takes an array, asserted below). ⇒ 将帮助页面按顺序分节组织的目录 / ヘルプページを順序付きのセクションにまとめた目次 / Índice que organiza las páginas de ayuda en secciones ordenadas. No machine token is kept: the ADR citation and its §6 are exactly what this rewrite removed, asserted by the plain-copy guard below.',
355355
},
356356
{
357357
scope: 'type',

‎packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2202,7 +2202,7 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
22022202
},
22032203
api: {
22042204
label: "Endpoint API",
2205-
description: "URL HTTP estable a la que llaman otros sistemas para acceder a los flujos, scripts y datos de la aplicación"
2205+
description: "URL HTTP estable a la que llaman otros sistemas para ejecutar un flujo o trabajar con los registros de la aplicación"
22062206
},
22072207
translation: {
22082208
label: "Traducción"
@@ -2282,11 +2282,11 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
22822282
},
22832283
doc: {
22842284
label: "Documentación",
2285-
description: "Página de ayuda en Markdown que un paquete incluye para que la lean sus usuarios"
2285+
description: "Página de ayuda en Markdown, incluida en un paquete o redactada directamente"
22862286
},
22872287
book: {
22882288
label: "Libro de documentación",
2289-
description: "Índice que organiza las páginas de ayuda de un paquete en secciones ordenadas"
2289+
description: "Índice que organiza las páginas de ayuda en secciones ordenadas"
22902290
},
22912291
permission: {
22922292
label: "Conjunto de permisos",

‎packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2202,7 +2202,7 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
22022202
},
22032203
api: {
22042204
label: "API エンドポイント",
2205-
description: "他のシステムがアプリのフロー、スクリプト、データにアクセスするために呼び出す固定の HTTP URL"
2205+
description: "他のシステムが呼び出す固定の HTTP URL。フローを実行したり、アプリのレコードを操作したりします"
22062206
},
22072207
translation: {
22082208
label: "翻訳"
@@ -2282,11 +2282,11 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
22822282
},
22832283
doc: {
22842284
label: "ドキュメント",
2285-
description: "パッケージに同梱される、ユーザー向けの Markdown ヘルプページ"
2285+
description: "Markdown で書かれたヘルプページ。パッケージに同梱されるほか、自分で作成することもできます"
22862286
},
22872287
book: {
22882288
label: "ドキュメントブック",
2289-
description: "パッケージのヘルプページを順序付きのセクションにまとめた目次"
2289+
description: "ヘルプページを順序付きのセクションにまとめた目次"
22902290
},
22912291
permission: {
22922292
label: "権限セット",

‎packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2202,7 +2202,7 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
22022202
},
22032203
api: {
22042204
label: "API 端点",
2205-
description: "其他系统调用的稳定 HTTP URL,用于访问应用的流程、脚本和数据"
2205+
description: "其他系统调用的稳定 HTTP URL,用于运行流程或操作应用中的记录"
22062206
},
22072207
translation: {
22082208
label: "翻译"
@@ -2282,11 +2282,11 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
22822282
},
22832283
doc: {
22842284
label: "文档",
2285-
description: "软件包随附的 Markdown 帮助页面,供用户阅读"
2285+
description: "以 Markdown 编写的帮助页面,可由软件包随附,也可自行编写"
22862286
},
22872287
book: {
22882288
label: "文档手册",
2289-
description: "将软件包的帮助页面按顺序分节组织的目录"
2289+
description: "将帮助页面按顺序分节组织的目录"
22902290
},
22912291
permission: {
22922292
label: "权限集",

‎packages/spec/src/kernel/metadata-plugin.zod.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1133,7 +1133,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] =
11331133
// metadata-forms translations), so it stays in plain words; the design it
11341134
// summarises — a declarative endpoint, a stable URL and policy layer over an
11351135
// existing pipeline — is ADR-0121.
1136-
{ type: 'api', label: 'API Endpoint', description: 'A stable HTTP URL that other systems call to reach flows, scripts and data in the app', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' },
1136+
{ type: 'api', label: 'API Endpoint', description: 'A stable HTTP URL that other systems call to run a flow or work with records in the app', filePatterns: ['**/*.api.ts', '**/*.api.yml', '**/*.api.json'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: false, supportsVersioning: false, executionPinned: false, loadOrder: 92, domain: 'system' },
11371137
{ type: 'translation', label: 'Translation', filePatterns: ['**/*.translation.ts', '**/*.translation.yml', '**/*.translation.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 90, domain: 'system' },
11381138
{ type: 'email_template', label: 'Email Template', filePatterns: ['**/*.email-template.ts', '**/*.email-template.yml', '**/*.email-template.json'], supportsOverlay: true, allowEnvironmentOverlay: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 85, domain: 'system' },
11391139
// ADR-0046: package documentation. Inert data — no runtime behavior, no
@@ -1143,7 +1143,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] =
11431143
// never parses `content`. loadOrder is last: nothing references docs.
11441144
// `description` is admin-facing copy: plain words, the ADR-0046 vocabulary
11451145
// (flat Markdown items) stays in this comment.
1146-
{ type: 'doc', label: 'Documentation', description: 'A help page written in Markdown that a package ships for its users to read', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
1146+
{ type: 'doc', label: 'Documentation', description: 'A help page written in Markdown that a package ships or you write yourself', filePatterns: ['**/docs/*.md'], supportsOverlay: false, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
11471147
// Navigation spine over docs (ADR-0046 §6): ordered groups, membership derived
11481148
// by rule. Overlay-mergeable at read (`supportsOverlay: true`); runtime-
11491149
// creatable for AI/authors. loadOrder last (references docs).
@@ -1160,7 +1160,7 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntryParsed[] =
11601160
//
11611161
// `description` is admin-facing copy: plain words, the ADR-0046 §6
11621162
// vocabulary (navigation spine, ordered groups, derived membership) stays here.
1163-
{ type: 'book', label: 'Documentation Book', description: 'A table of contents that groups the help pages of a package into ordered sections', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
1163+
{ type: 'book', label: 'Documentation Book', description: 'A table of contents that groups help pages into ordered sections', filePatterns: ['**/*.book.ts'], supportsOverlay: true, allowEnvironmentOverlay: false, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 99, domain: 'system' },
11641164

11651165
// Security Protocol
11661166
//

0 commit comments

Comments
 (0)