feat(showcase): ADR-0046 — package docs coverage (flat src/docs/*.md) (#1793)

Two cross-referencing docs demonstrating every doc-metadata authoring
rule the build enforces — flat directory, namespace-prefixed filename
stems, frontmatter-title vs first-heading title derivation, relative
cross-references with anchors, code blocks keeping link syntax literal —
plus a COVERAGE entry so the dimension is tracked like every other
showcase feature.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

examples/app-showcase/src/coverage.ts

@@ -73,6 +73,10 @@ export const COVERAGE = {
   i18nThemingPortals: {
     coveredBy: 'translations/index.ts (en + zh-CN), themes/index.ts (light + dark), portals/index.ts',
   },
+  docs: {
+    source: 'ADR-0046 (doc metadata)',
+    coveredBy: 'src/docs/*.md — flat Markdown compiled to `doc` items: frontmatter title + first-heading title, cross-references with anchors, namespace-prefixed names',
+  },
 } as const;
 
 /** Collect every field `type` used across a set of object definitions. */

examples/app-showcase/src/docs/showcase_docs_guide.md

@@ -0,0 +1,31 @@
+---
+title: Documentation Guide
+---
+
+# Writing package docs
+
+Rules this very file follows (each one is enforced by `os build`):
+
+- **Flat directory** — every doc lives directly in `src/docs/`;
+  subdirectories fail the build. Flatness is what keeps references
+  stable: a link is resolved by basename, never by path.
+- **Namespace-prefixed filename** — the stem becomes the doc name
+  (`showcase_docs_guide.md` → `showcase_docs_guide`), globally unique
+  inside a running instance, so the console URL needs no package
+  coordinate.
+- **Title** — frontmatter `title:` wins (this file uses it); otherwise
+  the first `#` heading; otherwise the name.
+- **Pure Markdown** — CommonMark + GFM only. MDX and image references
+  are rejected at build time (trust boundary + version immutability).
+
+## Cross-references
+
+Link to a sibling doc with a plain relative link:
+
+```md
+See the [overview](./showcase_index.md).
+```
+
+The console rewrites it to `/docs/showcase_index`; in an editor or on
+GitHub the same link just works. Broken same-package links fail the
+build. Back to the [overview](./showcase_index.md).

examples/app-showcase/src/docs/showcase_index.md

@@ -0,0 +1,16 @@
+# Showcase
+
+The living conformance fixture for the ObjectStack protocol: every field
+type, view type, chart type, report type, and action location appears at
+least once, and the coverage test fails when the platform gains a
+feature this package does not yet demonstrate.
+
+This manual itself demonstrates one of those features — **package docs
+as metadata** (ADR-0046). Every Markdown file in the flat `src/docs/`
+directory compiles into a `doc` metadata item at build time, ships
+inside the package artifact, and renders in the console at
+`/docs/<name>`.
+
+For the authoring rules this page must itself obey, see the
+[documentation guide](./showcase_docs_guide.md) — or jump straight to
+its [cross-reference section](./showcase_docs_guide.md#cross-references).