Skip to content

Commit 7390bef

Browse files
committed
docs(skills,docs): an email-template override names a locale its base ships; a new locale carries no overrides
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2g7RyXa8ErM6GAkHyc
1 parent c064d3a commit 7390bef

3 files changed

Lines changed: 22 additions & 8 deletions

File tree

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): objectstack-platform says an email-template override names a locale its base ships; a new locale carries no `overrides`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- **Before.** The ADR-0146 customization paragraph taught that a same-named item in the paired `.custom` package with `overrides` replaces the base's item, and listed `email_template` among the honoured types, but said nothing about the locale. An email template is one item per `(name, locale)`, and the override write gate refuses a declared override of a locale the base does not ship (`declared_package_ships_no_such_item`), so an author following the skill could declare `overrides` on a locale the base never shipped and be refused.
11+
- **Now.** One sentence in that paragraph: an email template is one item per (name, locale), an override names a locale the base ships, and a locale the base does not ship is added without `overrides`. The file stays at its token ceiling: the sentence is paid for by naming the not-yet-honoured types as the rest of `OVERRIDABLE_METADATA_TYPES` instead of enumerating them, and by dropping four filler intro clauses. No rule is removed, no frontmatter, schema or behaviour changes.

‎content/docs/concepts/metadata-lifecycle.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,8 @@ later ships. See [ADR-0070](https://github.com/objectstack-ai/objectstack/blob/m
115115

116116
A customer's change to an installed base package — HotCRM, id `hotcrm` — is an item of
117117
the base's paired writable package **`hotcrm.custom`**, which depends on the base; the
118-
base's own items stay read-only. An item of the pair that bears a base item's name and
118+
base's own items stay read-only. An item of the pair that bears a base item's name — for an
119+
`email_template`, one item per `(name, locale)`, the name **and** a locale the base ships — and
119120
declares in its body `overrides: { package: 'hotcrm', basedOn: '3.2.0' }` (the base's
120121
`manifest.id` and `manifest.version`; `basedOn` is recorded and never judged; schema:
121122
[Override Declaration](/docs/references/kernel/override-declaration)) replaces the base's
@@ -131,6 +132,11 @@ document **whole** for every read that serves the base's name
131132
or `translation`: the rest of `OVERRIDABLE_METADATA_TYPES` (`@objectstack/spec/kernel`)
132133
— `page`, `app`, `dataset`, `doc`, `book`, `mapping`, `flow` and `action` — waits for
133134
its doors and is not served yet. A declaration from any other package is ignored.
135+
- **A new locale is not an override.** An `email_template` the pair saves at a locale the
136+
base does not ship is the pair's own member, served under `hotcrm.custom`, and carries no
137+
`overrides`; declaring one there is refused (`403 NOT_OVERRIDABLE` at the save, publish
138+
and install doors, a row from `os validate`, the sentence naming the locale), because the
139+
base ships no such member to replace.
134140
- **The environment-wide list** serves one item per name that exactly one code package
135141
ships. A dependent package's same-named item is not listed beside it and stays under
136142
its own `?package=` address. A package-unbound row — the overlay row of the table

‎skills/objectstack-platform/SKILL.md‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,7 @@ ownerless row into a queue — parked, `round_robin` or `least_loaded` — or to
5555
user. Both need the ownership-queue service `@objectstack/plugin-sharing` registers
5656
(`sharing` in `requires`): a stack declaring either without it is refused at boot.
5757

58-
Undeclared keys are handled per surface, and the two postures are worth
59-
keeping straight:
58+
Undeclared keys are handled per surface, in two postures:
6059

6160
- **Refused** — `defineStack()`'s top level, each `objects[]` entry
6261
(`ObjectSchema`), and each field (`FieldSchema`). The parse throws, naming
@@ -108,7 +107,7 @@ OS_ARTIFACT_PATH=./dist/objectstack.json objectstack dev
108107

109108
## Manifest Reference
110109

111-
Every stack needs a `manifest` to identify itself in the ecosystem:
110+
Every stack needs a `manifest`:
112111

113112
```typescript
114113
manifest: {
@@ -131,7 +130,7 @@ to a new protocol major — never to silence a mismatch.
131130

132131
**`manifest.namespace` (ADR-0048):** Optional, but **enforced once set**. When a package declares `manifest.namespace: 'crm'`, every `object.name` must start with `crm_` or `defineStack` errors (`validateNamespacePrefix` in `@objectstack/spec`); the legacy `<ns>__<short>` double-underscore form is rejected, and `sys_`-prefixed names are platform-reserved and exempt. The namespace is also a package-ownership key — installing two packages that both claim `crm` fails with `NamespaceConflictError` (downgrade to a warning with `OS_METADATA_COLLISION=warn`). `os lint` additionally emits a non-fatal `naming/namespace-prefix` warning for bare-named UI/automation items (app, page, dashboard, flow, action, report, dataset) when a namespace is set.
133132

134-
**Customizing an installed package (ADR-0146):** Customize an installed base `hotcrm` in its paired writable package `hotcrm.custom`, which depends on it: a same-named item there with `overrides: { package: 'hotcrm', basedOn: '3.2.0' }` (its `manifest.id`/`manifest.version`) replaces the base's document whole. The read honours it only from the pair (the row's `package_id`), today only for a view, dashboard, report, email_template or translation (page, app, dataset, doc, book, mapping, flow and action wait for their doors), never judges `basedOn` and ignores any other package's declaration. Then no `?package`, `?package=hotcrm`, the layered read and both lists serve it; the env-wide list holds one item per name one code package ships (a dependent's stays under its own `?package=`); a package-unbound Setup row still wins over the base's until D11. An undeclared pair row or a dependent's row is an orphan in the layered read's `overlay`, `effective` = the base's. An override may narrow a public form's anonymous intake, never re-open one any honoured body withdrew. `GET /packages/hotcrm.custom/export` carries it with `overrides`; the base's is unchanged.
133+
**Customizing an installed package (ADR-0146):** Customize an installed base `hotcrm` in its paired writable package `hotcrm.custom`, which depends on it: a same-named item there with `overrides: { package: 'hotcrm', basedOn: '3.2.0' }` (its `manifest.id`/`manifest.version`) replaces the base's document whole. The read honours it only from the pair (the row's `package_id`), today only for a view, dashboard, report, email_template or translation (the rest of `OVERRIDABLE_METADATA_TYPES` wait for their doors), never judges `basedOn` and ignores any other package's declaration. An email template is one item per (name, locale): an override names a locale the base ships; a locale the base does not ship is added without `overrides`. Then no `?package`, `?package=hotcrm`, the layered read and both lists serve it; the env-wide list holds one item per name one code package ships (a dependent's stays under its own `?package=`); a package-unbound Setup row still wins over the base's until D11. An undeclared pair row or a dependent's row is an orphan in the layered read's `overlay`, `effective` = the base's. An override may narrow a public form's anonymous intake, never re-open one any honoured body withdrew. `GET /packages/hotcrm.custom/export` carries it with `overrides`; the base's is unchanged.
135134

136135
---
137136

@@ -227,7 +226,7 @@ my-app/
227226

228227
## Driver Selection Guide
229228

230-
Drivers are the storage layer. Pick based on your environment:
229+
Drivers are the storage layer:
231230

232231
| Driver | Package | Best For | Notes |
233232
|:-------|:--------|:---------|:------|
@@ -291,8 +290,6 @@ routes added to HttpDispatcher work automatically**.
291290

292291
## Runtime Boot Sequence
293292

294-
Understanding how ObjectStack starts helps debug and customize:
295-
296293
```
297294
objectstack.config.ts
298295
└── defineStack({ manifest, objects, views, ... })

0 commit comments

Comments
 (0)