feat(ADR-0046): add optional description to package docs

A doc can now carry a one-line `description` (frontmatter `description:`) —
title / summary / body, the natural minimal model.

- spec: DocSchema gains optional `description`.
- cli: collect-docs reads `description:` from frontmatter (generalized the
  scalar extractor; title + description share it). Regression test added.
- It travels in GET /meta/doc list (content is omitted there), so the docs
  portal shows summaries without fetching each body — verified live: showcase
  /meta/doc returns description, hasContent:false.
- Example docs (app-showcase, app-todo) carry descriptions.
- ADR-0046: schema + a P3 design note for doc TAGS (deferred) — tags are
  i18n-resolved keys, core protocol vocabulary + namespace-prefixed package
  tags; not a field to bolt on early.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/adr-0046-doc-description.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+feat(ADR-0046): add optional `description` to package docs
+
+A doc can now carry a one-line `description` (frontmatter `description:`),
+giving the natural minimal model: title / summary / body. `DocSchema` gains an
+optional `description`; `os build` reads it from frontmatter. It travels in the
+`GET /meta/doc` list response (unlike `content`, which the list omits), so a
+docs portal can show summaries without fetching each body. Example docs
+(app-showcase, app-todo) updated.
+
+Also records the deferred-to-P3 design for doc **tags** in ADR-0046: tags are
+keys (i18n-resolved, never display strings), with a small protocol core
+vocabulary plus namespace-prefixed package tags — not a field to bolt on early.

content/docs/guides/metadata/doc.mdx

@@ -31,19 +31,23 @@ stable (a link resolves by basename, never by path).
 
 ### Frontmatter
 
-A leading YAML frontmatter block is optional. Only `title` is read:
+A leading YAML frontmatter block is optional. `title` and `description`
+are read:
 
 ```md
 ---
 title: User Guide
+description: How to create, organize, and complete records in CRM.
 ---
 
 # Getting started with CRM
 ...
 ```
 
 The display title resolves in order: frontmatter `title:` → the first
-`#` heading → the doc `name`.
+`#` heading → the doc `name`. The optional `description` is a one-line
+summary the docs portal renders under the title (it travels in the doc
+list, so the portal shows summaries without fetching each body).
 
 ## Doc Properties
 
@@ -53,6 +57,7 @@ When a `*.md` file is collected, it becomes a `doc` item with this shape:
 | :--- | :--- | :--- | :--- |
 | `name` | `string` | ✅ | Machine name (`snake_case`), from the filename stem. Must match `^[a-z][a-z0-9_]*$` and be **namespace-prefixed** |
 | `label` | `string` | — | Display title (from frontmatter `title`) |
+| `description` | `string` | — | One-line summary for listings (from frontmatter `description`) |
 | `content` | `string` | ✅ | The Markdown body |
 
 You can also declare a doc programmatically with `DocSchema` in a stack

docs/adr/0046-package-docs-as-metadata.md

@@ -107,6 +107,8 @@ export const DocSchema = z.object({
     .describe('Unique doc name; MUST carry the package namespace prefix (enforced by build/publish lint)'),
   label: z.string().optional()
     .describe('Display title; defaults to the first `#` heading, then the name'),
+  description: z.string().optional()
+    .describe('One-line summary for listings (frontmatter `description:`); travels in the list response'),
   content: z.string().describe('Raw Markdown (CommonMark + GFM)'),
 });
 ```
@@ -144,6 +146,8 @@ unbounded, and manifest-size pressure lands here first.
   legacy, so day-one lint costs nothing — the same reasoning as the
   image ban.
 - `label` = frontmatter `title:` if present, else first `#` heading.
+- `description` = frontmatter `description:` if present (optional one-line
+  summary; the docs portal renders it under the title).
 - `content` = the file body (frontmatter stripped).
 - **Subdirectories under `src/docs/` are a build error**, not silently
   flattened — flatness is the contract that keeps references stable.
@@ -240,3 +244,30 @@ maintained, so it cannot rot.
 
 P0 conventions are isomorphic to the P1 schema by construction: when the
 compiler lands, pilot content migrates with zero edits.
+
+### P3 design note — tags / categorization (deferred, not bolted on early)
+
+Tags, categories, and ordering are **navigation-model** concerns and stay
+in P3 by design — adding them before there is enough doc volume to need
+filtering buys an i18n-bearing protocol field with no payoff. When they
+land, design the discovery surface (tags + category + search + cross-package
+aggregation) as one thing, not field-by-field. The agreed shape for tags:
+
+- **A tag is a stable key, never a display string.** Display always resolves
+  through the platform's existing label-key → i18n mechanism, exactly like
+  every other label. Free-form display strings fail twice: cross-package
+  fragmentation (`setup` vs `getting-started` vs `quickstart`) and no i18n
+  owner. Keying fixes both.
+- **Layered vocabulary, not closed-vs-open.** The protocol blesses a *small
+  core* of cross-cutting "purpose" tags (`getting-started`, `guide`,
+  `reference`, `tutorial`, `api`, `migration`, `troubleshooting`) — central
+  i18n, eligible for dedicated UI. Packages extend with **namespace-prefixed**
+  tags (`crm_*`, same rule as doc names) for domain topics, shipping their
+  translations in the package i18n bundle (same path as object/field labels).
+- Pure closed enum is too rigid (packages can't express domain topics); pure
+  open free-form is too fragmented and has no i18n home. The layered
+  key-based model is the resolution.
+
+The current addition — `description` — deliberately stops short of this: it is
+a per-doc summary, not a taxonomy, so it carries no i18n-keying or
+cross-package-coherence burden.

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

@@ -1,5 +1,6 @@
 ---
 title: Documentation Guide
+description: The authoring rules every package doc must follow — flat directory, namespace prefix, links, and the Markdown subset.
 ---
 
 # Writing package docs

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

@@ -1,3 +1,8 @@
+---
+title: Showcase
+description: Overview of the showcase package and the docs-as-metadata feature it demonstrates.
+---
+
 # Showcase
 
 The living conformance fixture for the ObjectStack protocol: every field

examples/app-todo/src/docs/todo_index.md

@@ -1,3 +1,8 @@
+---
+title: Todo App
+description: A minimal task-management app that demonstrates the ObjectStack metadata protocol end to end.
+---
+
 # Todo App
 
 A minimal task-management app demonstrating the ObjectStack metadata

examples/app-todo/src/docs/todo_user_guide.md

@@ -1,5 +1,6 @@
 ---
 title: User Guide
+description: How to create, organize, and complete tasks in the Todo app.
 ---
 
 # Working with Tasks

packages/cli/src/utils/collect-docs.test.ts

@@ -38,6 +38,18 @@ describe('collectDocsFromSrc (ADR-0046 §3.2)', () => {
     expect(guide.content).not.toContain('title:'); // frontmatter stripped
   });
 
+  it('reads optional frontmatter `description:` (and omits it when absent)', () => {
+    write('crm_index.md', '---\ntitle: CRM\ndescription: Start here.\n---\n\n# CRM\n\nBody.');
+    write('crm_plain.md', '# Plain\n\nNo frontmatter.');
+    const { docs, issues } = collectDocsFromSrc(configPath);
+    expect(issues).toHaveLength(0);
+    const index = docs.find((d) => d.name === 'crm_index')!;
+    expect(index.description).toBe('Start here.');
+    expect(index.content).not.toContain('description:'); // frontmatter stripped
+    const plain = docs.find((d) => d.name === 'crm_plain')!;
+    expect(plain.description).toBeUndefined(); // absent → omitted, not ''
+  });
+
   it('errors on subdirectories — flatness is the contract', () => {
     fs.mkdirSync(path.join(docsDir, 'user'));
     write('crm_index.md', '# x');

packages/cli/src/utils/collect-docs.ts

@@ -29,6 +29,7 @@ import path from 'path';
 export interface DocItem {
   name: string;
   label?: string;
+  description?: string;
   content: string;
 }
 
@@ -41,19 +42,31 @@ export interface DocIssue {
 
 const DOC_NAME_RE = /^[a-z][a-z0-9_]*$/;
 
-/** Strip a leading `---` frontmatter block; extract a `title:` if present. */
-function parseFrontmatter(raw: string): { title?: string; body: string } {
+/** Extract a single-line scalar `key: value` from a frontmatter block. */
+function frontmatterScalar(block: string, key: string): string | undefined {
+  const re = new RegExp(`^${key}\\s*:`, 'i');
+  const line = block.split(/\r?\n/).find((l) => re.test(l));
+  if (!line) return undefined;
+  const value = line.replace(re, '').trim().replace(/^['"]|['"]$/g, '');
+  return value || undefined;
+}
+
+/**
+ * Strip a leading `---` frontmatter block; extract `title:` and
+ * `description:` if present (both optional, single-line scalars).
+ */
+function parseFrontmatter(raw: string): { title?: string; description?: string; body: string } {
   if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) return { body: raw };
   const end = raw.indexOf('\n---', 3);
   if (end === -1) return { body: raw };
   const block = raw.slice(raw.indexOf('\n') + 1, end);
   const bodyStart = raw.indexOf('\n', end + 1);
   const body = bodyStart === -1 ? '' : raw.slice(bodyStart + 1);
-  const titleLine = block.split(/\r?\n/).find((l) => /^title\s*:/.test(l));
-  const title = titleLine
-    ? titleLine.replace(/^title\s*:\s*/, '').trim().replace(/^['"]|['"]$/g, '')
-    : undefined;
-  return { title: title || undefined, body };
+  return {
+    title: frontmatterScalar(block, 'title'),
+    description: frontmatterScalar(block, 'description'),
+    body,
+  };
 }
 
 /** Remove fenced code blocks and inline code spans before content scans. */
@@ -105,8 +118,13 @@ export function collectDocsFromSrc(configPath: string): { docs: DocItem[]; issue
     }
 
     const raw = fs.readFileSync(path.join(docsDir, entry.name), 'utf-8');
-    const { title, body } = parseFrontmatter(raw);
-    docs.push({ name: stem, label: title ?? firstHeading(body), content: body });
+    const { title, description, body } = parseFrontmatter(raw);
+    docs.push({
+      name: stem,
+      label: title ?? firstHeading(body),
+      ...(description ? { description } : {}),
+      content: body,
+    });
   }
   return { docs, issues };
 }

packages/spec/src/system/doc.zod.ts

@@ -41,6 +41,16 @@ export const DocSchema = lazySchema(() => z.object({
   label: z.string().optional()
     .describe('Display title; defaults to the first `#` heading, then the name'),
 
+  /**
+   * One-line summary for listings (the docs portal renders it under the
+   * title). The CLI reads it from frontmatter `description:`. Optional and
+   * short by convention — it travels in the list response (unlike
+   * `content`, which the REST list omits by default), so a portal can show
+   * summaries without fetching each doc's body.
+   */
+  description: z.string().optional()
+    .describe('One-line summary for listings; from frontmatter `description:`'),
+
   /**
    * Raw Markdown body (CommonMark + GFM), frontmatter stripped.
    * MDX and image references are banned in v1 (ADR-0046 §3.4) —