dogsbay 0.2.0-beta.32 → 0.2.0-beta.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.32",
+  "version": "0.2.0-beta.33",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,14 +32,14 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.32",
-    "@dogsbay/format-astro": "0.2.0-beta.32",
-    "@dogsbay/format-obsidian": "0.2.0-beta.32",
-    "@dogsbay/format-mdx": "0.2.0-beta.32",
-    "@dogsbay/format-starlight": "0.2.0-beta.32",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.32",
-    "@dogsbay/format-openapi": "0.2.0-beta.32",
-    "@dogsbay/types": "0.2.0-beta.32"
+    "@dogsbay/format-mkdocs": "0.2.0-beta.33",
+    "@dogsbay/format-astro": "0.2.0-beta.33",
+    "@dogsbay/format-obsidian": "0.2.0-beta.33",
+    "@dogsbay/format-mdx": "0.2.0-beta.33",
+    "@dogsbay/format-starlight": "0.2.0-beta.33",
+    "@dogsbay/format-openapi": "0.2.0-beta.33",
+    "@dogsbay/types": "0.2.0-beta.33",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.33"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/platform/frontmatter-fields/SKILL.md

@@ -300,6 +300,25 @@ explicit declaration.
   semantic effects, AND they're also the canonical taxonomies
   to declare in `taxonomies:` config. Use the built-in name
   rather than inventing a parallel field.
+- ❌ **Using the YAML-nested-object form for `tags:`** — it's
+  silently dropped by `parseMeta`, page renders with no chips
+  and no facets, nothing warns:
+
+  ```yaml
+  # ❌ silently inert
+  tags:
+    difficulty: beginner
+    topic: [getting-started, install]
+    persona: [author]
+  ```
+
+  `tags:` must be a string or string array. Encode dimensions as
+  slash-prefix slugs (`difficulty/beginner`, `topic/install`,
+  `persona/author`) and declare the prefixes in
+  `taxonomies.tags.prefixes`. See `dogsbay:taxonomy-config` →
+  Dimensional metadata via tag prefixes, and
+  [docs/tagging-cookbook.md](../../../../../../docs/tagging-cookbook.md)
+  for the full migration recipe.
 - ❌ Setting `status: beta` (or any value not in the closed
   enum). The four values are `draft | preview | stable |
   deprecated` — `parseMeta` silently drops anything else, so

package/skills/platform/taxonomy-config/SKILL.md

@@ -17,6 +17,14 @@ for tagging. It provides:
 What goes IN the schemes is the user's call. Dogsbay's role is
 to make the slot work consistently.
 
+For an end-to-end worked example covering **dimensional metadata**
+("I want tags with names and values — difficulty, topic, persona,
+each with their own facet column and chip colour"), see
+[docs/tagging-cookbook.md](../../../../../../docs/tagging-cookbook.md).
+That doc walks the full config + frontmatter + emitted-output
+flow for the multi-prefix dimensional pattern, with migration
+notes for the common YAML-nested-object pitfall.
+
 ## Where taxonomy values live
 
 Per-page in frontmatter:
@@ -375,8 +383,89 @@ taxonomies:
 No `values:` — any tag is valid. Just hierarchical display
 config for the prefixes the writer uses.
 
+### Dimensional metadata via tag prefixes
+
+The answer to "I want tags with names and values — difficulty,
+topic, persona, each with its own facet column and chip colour."
+Slash-prefix slugs encode the dimension; display config supplies
+the human surface.
+
+```yaml
+# dogsbay.config.yml
+taxonomies:
+  tags:
+    indexPath: /tags
+    hierarchical: true
+    prefixes:
+      difficulty: { label: Difficulty, color: amber }
+      topic:      { label: Topic,      color: violet }
+      persona:    { label: For,        color: emerald }
+      concept:    { label: Concept,    color: blue }
+      product:    { label: Product,    color: rose }
+    labels:
+      "difficulty/1": Beginner
+      "difficulty/2": Intermediate
+      "difficulty/3": Advanced
+      "persona/dev": Developer
+      "persona/agent": AI agent
+```
+
+```yaml
+# page frontmatter — one flat `tags:` list, many dimensions
+tags:
+  - difficulty/1
+  - topic/getting-started
+  - topic/install
+  - persona/dev
+  - persona/agent
+  - concept/agent-ready
+  - product/dogsbay-platform
+```
+
+Each prefix becomes its own Cmd+K facet column (`Difficulty`,
+`Topic`, `For`, `Concept`, `Product`), each chip renders as a
+two-part `<label>: <leaf>` block in the prefix's colour, and
+each term gets a browse page (`/tags/difficulty/1/` etc.). One
+authoring pattern, five dimensions of metadata, no extra
+top-level frontmatter keys.
+
+See [docs/tagging-cookbook.md](../../../../../../docs/tagging-cookbook.md)
+for the full end-to-end walkthrough including what gets emitted
+to dist/.
+
 ## Common mistakes
 
+- ❌ **Using the YAML-nested-object form for `tags:` in
+  frontmatter.** This shape is silently dropped by `parseMeta` —
+  no chips, no facets, no taxonomy index entries. The build
+  succeeds, the page renders with no metadata attached, nothing
+  warns.
+
+  ```yaml
+  # ❌ silently inert — parseMeta sees tags as an object, returns
+  # undefined, no chips/facets/index entries are emitted
+  tags:
+    difficulty: beginner
+    topic: [getting-started, install]
+    persona: [author]
+  ```
+
+  Encode the same intent as slash-prefix strings instead:
+
+  ```yaml
+  # ✅ supported — each entry is a string slug, prefix is the
+  # dimension, leaf is the value. Declare the prefixes in
+  # taxonomies.tags.prefixes for the chip + facet UI to light up.
+  tags:
+    - difficulty/beginner
+    - topic/getting-started
+    - topic/install
+    - persona/author
+  ```
+
+  See the dimensional-metadata pattern above + the full migration
+  recipe in [docs/tagging-cookbook.md](../../../../../../docs/tagging-cookbook.md).
+
 - ❌ Putting tag display config (colours, labels) in
   per-page frontmatter — that's site-wide, belongs in
   `dogsbay.config.yml`. Frontmatter just lists which taxonomies