From 127576f695017a2eceacaa026ec6c5ff5fac90d6 Mon Sep 17 00:00:00 2001
From: os-steve <steve@objectstack.ai>
Date: Sun, 20 Sep 2026 21:54:25 +0000
Subject: [PATCH] docs(skills): pages.md rule 2 states the enforceable reason,
 not the retired ADR-0048 claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Authoring rule 2 of skills/objectstack-ui/rules/pages.md told an AI author
that doc names "share one flat, instance-global space with the URL, so a
bare `user_guide` would collide across packages and fail at install
(ADR-0048)". Each clause is refuted by the source it cites:

- routing keys on the package id and packaged items are stored under the
  composite `<packageId>:<name>` key (ADR-0048 §3.1/§3.3;
  packages/objectql/src/registry.ts storageKey line);
- the cross-package throw is retired — two distinct packages coexist on
  the same bare name by construction (ADR-0048 §3.4);
- a bare doc name is refused at BUILD by `docs/namespace-prefix`
  (packages/cli/src/utils/collect-docs.ts, severity error; `os build`
  exits 1 on doc errors), not at install — the install gate refuses on
  `manifest.namespace` ownership and `NamespaceConflictError` is
  constructed with a namespace, not a doc name.

The rule (the stem must start with the package namespace) and the ADR
citation stay; the REASON now names where the refusal happens and what
the prefix is for. Net 0 lines; published-skills token ratchet 5499 -> 5501
of 5501 (paid within the same span).

Claude-Session: https://claude.ai/code/session_017ETYWqMQD4qMtZzAGovWNi
Co-authored-by: Claude <noreply@anthropic.com>
---
 skills/objectstack-ui/rules/pages.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/skills/objectstack-ui/rules/pages.md b/skills/objectstack-ui/rules/pages.md
index 489217dc5dc..7fdf6b033fd 100644
--- a/skills/objectstack-ui/rules/pages.md
+++ b/skills/objectstack-ui/rules/pages.md
@@ -336,9 +336,9 @@ src/docs/
    — a reference resolves by basename, never by path.
 2. **Namespace-prefixed filename.** The filename stem becomes the doc
    `name` (`^[a-z][a-z0-9_]*$`) and must start with the package namespace
-   (`crm_…`). Names share one flat, instance-global space with the URL, so
-   a bare `user_guide` would collide across packages and fail at install
-   (ADR-0048).
+   (`crm_…`). `os build` refuses a bare `user_guide`
+   (`docs/namespace-prefix`) — hygiene, not uniqueness: two packages
+   coexist on one bare name (ADR-0048 §3.4).
 3. **Title** resolves: frontmatter `title:` → first `#` heading → `name`.
    Optional frontmatter `description:` is a one-line summary the docs portal
    shows under the title — add it on index/overview docs.