dogsbay 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -0,0 +1,392 @@
+---
+name: dogsbay:taxonomy-config
+description: Configure user-defined taxonomies (tags, types, audience, status) in dogsbay.config.yml. Dogsbay provides the slot, the user defines the categories. Use when adding tagging schemes, custom badges, or facet UI.
+---
+
+# Taxonomy configuration
+
+Dogsbay does **not** prescribe what categories a doc site uses
+for tagging. It provides:
+
+- A frontmatter slot for tag values
+- A config slot (`taxonomies:`) for declaring tag schemes
+- Audit rules + display components that consume the schemes
+- Browse pages (`/tags/`, `/by-type/`, etc.) per declared
+  taxonomy
+
+What goes IN the schemes is the user's call. Dogsbay's role is
+to make the slot work consistently.
+
+## Where taxonomy values live
+
+Per-page in frontmatter:
+
+```yaml
+---
+title: Configuring environments
+description: …
+type: how-to                 # built-in field (treated as a taxonomy)
+status: stable               # built-in
+audience: [developer, ops]   # built-in
+tags:                        # free-form tag list
+  - concept/environments
+  - difficulty/intermediate
+  - kind/configuration
+---
+```
+
+Five built-in field names (`tags`, `type`, `status`, `audience`,
+`category`) are treated as taxonomies if declared in
+`dogsbay.config.yml`. Custom names work too — just declare them
+in the config.
+
+## Declaring a taxonomy
+
+In `dogsbay.config.yml`:
+
+```yaml
+taxonomies:
+  tags:
+    indexPath: /tags                   # browse page (default: /<name>)
+    prefixes:                          # display config per top-level slug prefix
+      concept:
+        label: Concept
+        color: blue
+      difficulty:
+        label: Difficulty
+        color: amber
+      kind:
+        label: Kind
+        color: emerald
+    labels:                            # display label overrides per slug
+      "concept/a11y": Accessibility    # /tags/concept/a11y → "Concept: Accessibility"
+      "difficulty/intermediate": Intermediate
+  type:
+    indexPath: /by-type
+    values:                            # closed list (audit rule fails on unknown values)
+      - tutorial
+      - how-to
+      - reference
+      - explanation
+  status:
+    indexPath: /by-status
+    values: [draft, preview, stable, deprecated]
+  audience:
+    indexPath: /by-audience
+    values: [developer, ops, security, end-user]
+```
+
+Each taxonomy declaration produces:
+
+- A browse index at `/tags/`, `/by-type/`, etc.
+- Per-term pages (`/tags/concept/a11y`)
+- A faceted-search checkbox group in the `Cmd+K` search dialog,
+  emitted automatically as `data-pagefind-filter="<name>:<value>"`
+  divs on every page that declares the taxonomy
+
+## Discovery model — chips vs. facets vs. browse
+
+Taxonomies play two distinct roles in a doc site:
+
+- **Associative tags** — answer *"what other pages are like this
+  one?"*. Primary mode: chips on the article header, link to
+  related pages. The `tags:` taxonomy is the canonical example.
+- **Descriptive metadata** — answers *"what kind of doc is this,
+  is it for me?"*. Primary mode: faceted search + browse-by-axis
+  pages. `audience`, `difficulty`, `team`, `status`, `type` all
+  fit here.
+
+Dogsbay surfaces them as follows:
+
+| Surface | Built-ins (tags, type, status) | Custom taxonomies (difficulty, team, …) |
+|---|---|---|
+| Chips on article header | ✅ rendered | ❌ not rendered (use a custom layout to add) |
+| Pagefind facet checkbox | ✅ automatic | ✅ automatic |
+| Browse pages (`/tags/`, `/by-difficulty/`) | ✅ from `indexPath` | ✅ from `indexPath` |
+| Sidebar nav entry | ❌ writer adds via `nav.yml` | ❌ writer adds via `nav.yml` |
+
+The chip cluster on the page header deliberately stays small —
+adding every taxonomy as a chip would crowd the article. Search
+facets are the discovery path for descriptive metadata, and
+browse pages are the catalogue path. Add browse pages to the
+sidebar nav (see "Surfacing browse pages" below) when discovery
+matters.
+
+## Faceted search comes free
+
+Every taxonomy declared in `dogsbay.config.yml` automatically
+appears as a checkbox group in the `Cmd+K` search dialog. No
+extra config — declaring it produces the `<div
+data-pagefind-filter="<name>:<value>">` markers on every
+matching page, Pagefind discovers them at index time, and the
+search UI renders one column per taxonomy with checkboxes per
+distinct value, sorted by frequency.
+
+Display labels for the checkboxes flow from
+`taxonomies.<name>.prefixes` and `taxonomies.<name>.labels` (the
+same display config that drives chips). When unset, raw slugs
+appear ("intermediate", "developer").
+
+```yaml
+taxonomies:
+  difficulty:
+    indexPath: /by-difficulty
+    values: [beginner, intermediate, advanced]
+    prefixes:
+      beginner: { label: Beginner, color: emerald }
+      intermediate: { label: Intermediate, color: amber }
+      advanced: { label: Advanced, color: rose }
+```
+
+Above declaration ⇒ search dialog grows a "Difficulty" column
+with three labelled checkboxes, with counts.
+
+## Surfacing browse pages
+
+Browse pages (`/by-difficulty/`, `/by-audience/`, etc.) exist
+the moment you declare a taxonomy with an `indexPath`, but
+nothing links to them by default. The standard pattern is a
+"Browse" group at the bottom of `nav.yml`:
+
+```yaml
+# nav.yml
+- Guides:
+    - Getting started: /getting-started
+    - Configuration: /config
+- Browse:
+    - By type: /by-type/
+    - By audience: /by-audience/
+    - By difficulty: /by-difficulty/
+    - Tags: /tags/
+```
+
+Nav entries accept absolute paths to internal pages. The
+"Browse" group is conventional, not enforced — pick the IA that
+fits the site.
+
+## Hierarchical tags via slug prefixes
+
+Tags can have slash-separated prefixes that the display layer
+treats as namespaces:
+
+```yaml
+tags:
+  - concept/accessibility
+  - concept/observability
+  - difficulty/beginner
+  - difficulty/advanced
+```
+
+Renders as two-part chips: `Concept: Accessibility`,
+`Difficulty: Beginner`. The prefix maps to a colour via
+`taxonomies.tags.prefixes.<prefix>.color`; the leaf maps to a
+human label via `taxonomies.tags.labels.<full-slug>`.
+
+This is the slot for "we want categories of tags but don't want
+to invent five separate frontmatter fields." Slash separation
+is the convention; the parser doesn't enforce it.
+
+### `hierarchical:` controls prefix browsing
+
+When `hierarchical: true`, declaring tag `concept/rag` also
+emits a `/tags/concept/` browse page that aggregates every
+`concept/*` tag. Term-page breadcrumbs (`Tags / Concept / RAG`)
+become clickable.
+
+When `hierarchical: false`, only leaf-tag pages (`/tags/concept/rag/`)
+exist; the prefix is purely visual styling on chips.
+
+**The default is auto-derived:** when you declare `prefixes:`,
+`hierarchical` defaults to `true` (the writer signalled they
+want prefixes to be real browsable categories). When
+`prefixes:` is absent, `hierarchical` defaults to `false`. Set
+the flag explicitly to override.
+
+```yaml
+# Auto-hierarchical — prefixes declared, /tags/concept/ exists
+taxonomies:
+  tags:
+    prefixes:
+      concept: { color: blue }
+
+# Flat — prefixes are pure styling, /tags/concept/ does NOT exist
+taxonomies:
+  tags:
+    hierarchical: false
+    prefixes:
+      concept: { color: blue }
+```
+
+## Closed-list taxonomies
+
+`values:` makes a taxonomy closed — pages declaring a value
+outside the list fire the `taxonomy/unknown-value` audit rule.
+Use for taxonomies where you want type-safety:
+
+```yaml
+taxonomies:
+  status:
+    values: [draft, preview, stable, deprecated]
+```
+
+A page with `status: production` fails `dogsbay site check`.
+
+Without `values:`, the taxonomy is open — any string is
+accepted. Useful for free-form tags.
+
+### `status: draft` is special-cased
+
+The `draft` value of the `status` taxonomy is **also** a
+build-time visibility gate — equivalent to `draft: true` in
+frontmatter. A page with `status: draft` is dropped from
+`dogsbay site build` (production) and the build line prints
+"(N drafts excluded)". `dogsbay site dev` always includes
+drafts so the writer can preview; `--include-drafts` is the
+escape hatch for production builds.
+
+The other three values (`preview`, `stable`, `deprecated`) are
+pure taxonomy — they render as a `<StatusBadge>` chip and
+populate `/by-status/`, but don't gate visibility.
+
+This is the only built-in taxonomy with overloaded semantics.
+If a writer wants `draft` to be only-a-taxonomy (no
+exclusion), the workaround is to use a different value name
+(e.g. `status: in-progress`) and customize the badge labels via
+`taxonomies.status.labels`.
+
+**Agents should not proactively stamp `status: draft` on new
+pages.** In a git-backed site (the common case), in-progress
+work is already isolated by branch — the page is a draft
+because the PR isn't merged, not because of frontmatter. Adding
+`status: draft` then layers an invisible build-time gate on
+top of the branch isolation, so when the PR merges the page
+*still* doesn't ship until someone notices and removes the
+frontmatter. That's a confusion trap.
+
+Use `status:` only when:
+
+1. The writer explicitly asked for it ("mark this draft").
+2. There's no git workflow (single-author site editing
+   directly on `main`).
+3. The page is a long-lived `preview` / `deprecated` /
+   `stable` lifecycle marker (not draft).
+
+Default to no `status` field on new pages. Branches handle
+draft state.
+
+## Display palette
+
+The closed colour palette for prefix chips and badges:
+
+`blue`, `amber`, `emerald`, `violet`, `rose`, `slate`
+
+These resolve to theme tokens — they look correct in any theme
+the site uses. Don't pass arbitrary hex codes here; the palette
+is intentional.
+
+## Audit rule integration
+
+`dogsbay site check` ships a few taxonomy-related rules
+(currently in the `seo/` and (planned) `taxonomy/` categories):
+
+- `seo/missing-tags` — page has no tags (configurable threshold)
+- `taxonomy/unknown-value` — frontmatter value not in declared
+  `values:`
+- `taxonomy/orphan-term` — taxonomy term page exists but no page
+  references it
+- `taxonomy/duplicate-display-label` — two slugs map to the same
+  display string
+
+Plugins and patterns can register additional taxonomy-aware
+rules.
+
+## Browse + facet UI
+
+`<TaxonomyIndex>` and `<TaxonomyTerm>` components render the
+browse pages — they read `siteConfig.taxonomyDisplay` and
+`siteConfig.taxonomyIndexPaths` (both populated from the config
+at build time).
+
+`<TagList>` renders chip-style tags in page headers. Reads the
+prefix colours and label overrides.
+
+`<SearchFacets>` renders facet checkboxes ("Concept:
+Accessibility", "How-to") — reads the same display config.
+
+## Per-page taxonomy values flow
+
+```
+content/page.md frontmatter
+    ↓ (parsed by importer)
+ExportPage.meta.taxonomies = { tags: [...], type: ..., ... }
+    ↓ (rendered into page)
+data-pagefind-filter attributes (search facets)
+TagList component (visual chips)
+TaxonomyIndex pages (browse)
+```
+
+Each step is platform-mechanical. The categories (concept,
+difficulty, audience values, etc.) are user-defined.
+
+## Common patterns
+
+### Diátaxis-style content typing
+
+When `@dogsbay/pattern-diataxis` is installed, it pre-declares:
+
+```yaml
+taxonomies:
+  type:
+    values: [tutorial, how-to, reference, explanation]
+    prefixes:
+      tutorial: { color: emerald }
+      "how-to": { color: blue }
+      reference: { color: amber }
+      explanation: { color: violet }
+```
+
+The pattern owns the values; the user can extend with their own.
+
+### Custom team taxonomies
+
+```yaml
+taxonomies:
+  team:
+    values: [platform, billing, identity, search]
+    indexPath: /by-team
+  release:
+    indexPath: /releases
+```
+
+Each team owns a subset of pages. The `/by-team/platform/` page
+lists every page that declares `team: platform` in frontmatter.
+
+### Free-form tags only
+
+```yaml
+taxonomies:
+  tags:
+    indexPath: /tags
+    prefixes:
+      concept: { color: blue }
+      kind: { color: emerald }
+```
+
+No `values:` — any tag is valid. Just hierarchical display
+config for the prefixes the writer uses.
+
+## Common mistakes
+
+- ❌ Putting tag display config (colours, labels) in
+  per-page frontmatter — that's site-wide, belongs in
+  `dogsbay.config.yml`. Frontmatter just lists which taxonomies
+  apply to this page.
+- ❌ Using `tagPrefixes` directly in `dogsbay.config.yml` —
+  legacy field, deprecated. Use
+  `taxonomies.tags.prefixes` instead.
+- ❌ Mixing prefix-based and free-form tags inconsistently —
+  pick one approach per taxonomy. If `tags` uses `concept/...`
+  prefixes, every tag should follow that pattern.
+- ❌ Declaring `values: [draft, …]` and then using `Draft` (with
+  capital) in frontmatter — values match exactly; case
+  matters.

package/skills/platform/theme-tokens/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: dogsbay:theme-tokens
+description: The 60 design tokens Dogsbay ships, how theme.css works, and how to override colours, fonts, radius, or swap themes wholesale. Use when customising visual design or troubleshooting theming issues.
+---
+
+# Theme tokens
+
+Dogsbay ships ~60 design tokens grouped by purpose. They live
+in `astro/src/styles/theme.css` (scaffold-once — yours to edit
+freely) and are consumed by the 72 components via Tailwind's
+`@theme` directive.
+
+Two themes ship out of the box:
+
+- `default` — shadcn-zinc-style (clean, neutral)
+- `material` — Material-Design-inspired (denser, more chromed)
+
+Set in `dogsbay.config.yml`:
+
+```yaml
+theme: default        # or "material"
+```
+
+## The token groups
+
+### Shadcn baseline (25 tokens)
+
+Standard shadcn UI tokens. Every component reads from these:
+
+```css
+:root {
+  --background:   oklch(1 0 0);
+  --foreground:   oklch(0.145 0.014 285.823);
+  --card:         oklch(1 0 0);
+  --card-foreground: …;
+  --popover, --popover-foreground;
+  --primary, --primary-foreground;
+  --secondary, --secondary-foreground;
+  --muted, --muted-foreground;
+  --accent, --accent-foreground;
+  --destructive, --destructive-foreground;
+  --border;
+  --input;
+  --ring;
+  --radius:       0.625rem;
+}
+```
+
+Override any of these to reskin the whole site. Want emerald
+buttons? Set `--primary` to an emerald oklch value; every
+component using `bg-primary` updates.
+
+### Sidebar (8 tokens)
+
+`--sidebar`, `--sidebar-foreground`, `--sidebar-primary`,
+`--sidebar-primary-foreground`, `--sidebar-accent`,
+`--sidebar-accent-foreground`, `--sidebar-border`,
+`--sidebar-ring`.
+
+These let the sidebar diverge from the main content panel —
+useful for sites with a darker nav bar over a lighter content
+area.
+
+### Admonitions (13 tokens)
+
+One per callout type:
+
+```css
+--note:      oklch(0.637 0.174 259.126);
+--abstract:  …;
+--info:      …;
+--tip:       …;
+--success:   …;
+--question:  …;
+--warning:   …;
+--failure:   …;
+--danger:    …;
+--bug:       …;
+--example:   …;
+--quote:     oklch(0.65 0 0);
+```
+
+`--note-foreground` is also exposed for callouts that need
+explicit text contrast.
+
+### Code (3 tokens)
+
+`--code-background`, `--code-foreground`, `--font-code`.
+
+The `<CodeBlock>` and inline `<code>` components read these.
+Default to a slightly-different background from `--background`
+so code stands out.
+
+### API panel (2 tokens)
+
+`--api-panel-bg`, `--api-panel-fg`.
+
+The dark right-column panel on OpenAPI endpoint pages.
+**Always dark**, regardless of light/dark mode — it's a stylistic
+choice that matches Stripe / Mintlify API doc convention.
+
+### API semantic (17 tokens)
+
+HTTP methods, type badges, status codes, role indicators —
+everything `<MethodBadge>`, `<EndpointCard>`, `<ParameterTable>`,
+`<ResponseTabs>`, `<SchemaViewer>`, etc. consume:
+
+```css
+--api-get:        oklch(0.723 0.15 162);    /* green */
+--api-post:       oklch(0.637 0.174 259);   /* blue */
+--api-put:        oklch(0.74 0.175 63);     /* orange */
+--api-patch:      oklch(0.7 0.18 45);       /* amber */
+--api-delete:     oklch(0.614 0.194 22);    /* red */
+--api-head:       oklch(0.534 0.222 286);   /* violet */
+--api-required:   oklch(0.614 0.194 22);    /* red */
+--api-deprecated: oklch(0.74 0.175 63);     /* orange */
+--api-type-string:  oklch(0.723 0.15 162);
+--api-type-number:  oklch(0.637 0.174 259);
+--api-type-boolean: oklch(0.74 0.175 63);
+--api-type-object:  oklch(0.534 0.222 286);
+--api-type-array:   oklch(0.7 0.18 45);
+--api-status-2xx: oklch(0.723 0.15 162);
+--api-status-3xx: oklch(0.637 0.174 259);
+--api-status-4xx: oklch(0.74 0.175 63);
+--api-status-5xx: oklch(0.614 0.194 22);
+```
+
+These are present in the scaffold even if the user isn't
+shipping OpenAPI yet — adding an OpenAPI source later doesn't
+require theme.css changes.
+
+### Fonts (3 tokens)
+
+`--font-sans`, `--font-heading`, `--font-code`.
+
+Defaults are system fonts. Override at the top of `theme.css`:
+
+```css
+:root {
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-heading: "Inter Display", "Inter", sans-serif;
+  --font-code: "JetBrains Mono", ui-monospace, monospace;
+}
+```
+
+## Light vs dark
+
+`theme.css` defines `:root { ... }` for light mode and `.dark
+{ ... }` for dark mode. The user's OS preference + the
+`<ThemeToggle>` component switch which class is applied to
+`<html>`.
+
+Dark-mode tokens override the same names with darker values.
+Both modes share radius, fonts, and the dark API panel
+(intentionally constant — see "API panel" above).
+
+## Override patterns
+
+### Tweak one colour
+
+Edit `theme.css`:
+
+```css
+:root {
+  --primary: oklch(0.5 0.18 145);   /* greenish primary */
+}
+
+.dark {
+  --primary: oklch(0.65 0.16 145);  /* lighter green for dark mode */
+}
+```
+
+### Swap themes wholesale
+
+`global.css` imports `theme.css`. To switch themes, change the
+import:
+
+```css
+/* Was: */
+@import "./theme.css";
+
+/* Now: */
+@import "./theme-material.css";
+```
+
+Both files ship by default. `theme-material.css` lives in the
+scaffold alongside `theme.css` for easy A/B-ing.
+
+### Custom theme from scratch
+
+Copy `theme.css` to `theme-mybrand.css`, edit, swap the import.
+
+The recommended editing path: keep the structure (light root +
+dark class + same token names), change values. Components find
+the tokens by name — renaming a token breaks the components.
+
+## Tailwind config consumption
+
+`@theme inline { --color-primary: var(--primary); ... }` in
+`theme.css` makes every token usable as a Tailwind utility:
+
+- `bg-primary` → `var(--primary)`
+- `text-api-get` → `var(--api-get)`
+- `border-sidebar-border`
+- etc.
+
+This is why the components use `class="bg-api-get/20
+text-api-get"` and Just Work in any theme. The tokens are the
+contract; the colours are the override surface.
+
+## Typography
+
+Two opt-in typography enhancements (pulled from theme tokens):
+
+- `font-heading` — applied to `<h1>` / `<h2>` / `<h3>` if
+  `--font-heading` differs from `--font-sans`. Set both to
+  the same value for "headings look like body".
+- `font-code` — applied to `<pre>`, `<code>`, syntax-highlighted
+  blocks.
+
+## Common patterns
+
+### Default theme (no edits)
+
+```yaml
+theme: default
+```
+
+`theme.css` ships, you don't touch it. Works for 80% of sites.
+
+### Brand-tinted defaults
+
+Edit just `--primary` + `--accent` to brand colours. Leave the
+rest alone. The site looks "yours" without 50 lines of CSS.
+
+### Dark-only or light-only
+
+The scaffold supports both modes via the `.dark` class. To
+force dark-only:
+
+```css
+:root,
+.dark {
+  /* dark token values */
+}
+```
+
+(The `<ThemeToggle>` component still exists; it just toggles
+between two identical themes. Hide it via DocsHeader prop if
+preferred.)
+
+### Swap to Material
+
+```yaml
+theme: material
+```
+
+Replace `default` with `material` in the config; `dogsbay site
+init` re-emits `global.css` with the right import.
+
+## Common mistakes
+
+- ❌ Using arbitrary Tailwind colours (`bg-emerald-500`) in
+  scaffolded components — bypasses the token system, breaks
+  theme switching. Use `bg-primary` / `bg-api-get` / etc.
+- ❌ Editing tokens INSIDE `:root` that are meant to be derived
+  from another (`--ring` is supposed to follow `--primary` in
+  the default theme; overriding directly produces inconsistent
+  state).
+- ❌ Setting tokens via inline `style="..."` on individual
+  elements — works but defeats the cascade. Update `theme.css`
+  instead.
+- ❌ Forgetting that the API panel is always dark — overriding
+  `--api-panel-bg` to a light value makes white text on white
+  background. The panel is intentionally a constant; reskin
+  individual API tokens (`--api-get`, etc.) instead.