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

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

@@ -0,0 +1,310 @@
+---
+name: dogsbay:frontmatter-fields
+description: Reference for the frontmatter fields Dogsbay recognises and how the importers + audit rules use them. Use when adding YAML frontmatter to a content/*.md page or debugging why a field isn't taking effect.
+---
+
+# Frontmatter fields
+
+Every Dogsbay markdown page can declare YAML frontmatter at
+the top, delimited by `---` lines. The importer parses it via
+`gray-matter`; the recognised keys flow into `ExportPage` and
+the rendered `.astro` page.
+
+```markdown
+---
+title: Configuration
+description: How to configure your Dogsbay site.
+draft: false
+---
+
+# Configuration
+
+…
+```
+
+## Three categories of frontmatter
+
+Dogsbay sees three distinct kinds of frontmatter, and they're
+easy to confuse:
+
+1. **Built-in fields** with semantic meaning — Dogsbay's
+   importer (`parseMeta`) lifts these into `ExportPage` and the
+   layout reads them. Setting them produces visible effects
+   (chips, badges, build-time gates, SEO meta).
+2. **User-declared taxonomies** — keys you name in
+   `taxonomies:` config get lifted into `meta.taxonomies[name]`
+   and produce browse pages, faceted search, and (for the five
+   built-ins below) chips. See `dogsbay:taxonomy-config`.
+3. **Arbitrary frontmatter** — anything else is preserved
+   on `ExportPage.frontmatter` but not consumed. Suitable for
+   build-tool inputs, internal annotations, or fields that
+   future plugins might read.
+
+The three tiers are mutually exclusive: `tags` is a built-in
+(tier 1), not "user-defined" (tier 2). Custom `difficulty`
+declared in your `taxonomies:` config is tier 2, not tier 3.
+
+# Tier 1: Built-in fields
+
+Each subsection groups built-ins by purpose. Setting any of
+these produces a real effect — they aren't opaque slots.
+
+## Identification
+
+| Field | Type | Purpose |
+|---|---|---|
+| `title` | string | Page title. Used in `<title>` tag, sidebar fallback, OG meta. Default: H1 of body, or filename. |
+| `description` | string | Page description. Used in `<meta name="description">`, OG description, search snippets. Treated as load-bearing for SEO and AEO. |
+
+## Routing
+
+| Field | Type | Purpose |
+|---|---|---|
+| `redirect` | string | Page is a redirect-only route. Renders no body; emits a 0-byte `<meta http-equiv="refresh">` page that points at the value. Use when you need a stable old URL to point at a new page. |
+| `slug` | string | Override the URL slug (default: filename without `.md`). Use sparingly — file paths are usually the better source of truth. |
+
+## Visibility
+
+| Field | Type | Default | Purpose |
+|---|---|---|---|
+| `draft` | boolean | `false` | When `true`, the page is excluded from production builds (`dogsbay site build`). It IS included in `dogsbay site dev` so the writer can preview. |
+| `noindex` | boolean | `false` | Adds `<meta name="robots" content="noindex">`. Page is still public; just hidden from external search engines. |
+| `excludeFromSearch` | boolean | `false` | Skip Pagefind indexing for this page. Use for legal pages, redirect stubs, etc. Independent of `noindex` — a page can be in-site-searchable but external-noindex, or vice versa. |
+
+The escape hatch for production builds is `--include-drafts`
+on `dogsbay site build` (matches the always-on behaviour of
+`dogsbay site dev`). The build line prints "(N drafts excluded)"
+so the writer notices.
+
+`status: draft` is **also** a build-time visibility gate (see
+the "`status` is dual-purpose" subsection below).
+
+**Don't stamp `draft: true` or `status: draft` on new pages
+proactively.** In a git-backed site, draftness is the branch
+state — the page is a draft because the PR isn't merged, not
+because of frontmatter. Layering frontmatter draft flags on top
+creates an invisible second gate that survives the merge: the
+PR ships, but the page silently doesn't appear in production
+because nobody removed the flag. Default to no draft flag and
+let branches do the gating. Only stamp draft when the writer
+explicitly asks (or there's no git workflow at all).
+
+## Content classification (also taxonomies)
+
+These five fields are first-class Dogsbay metadata AND drive
+the taxonomy system when declared in `taxonomies:` config. They
+have semantic effects regardless of whether you declare a
+taxonomy:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `type` | string | Open string — `tutorial`, `how-to`, `reference`, `explanation`, or any custom value. Renders a `<TypeBadge>`; drives Schema.org JSON-LD selection (`HowTo` for how-tos, `TechArticle` for references). |
+| `status` | enum | Closed enum — `draft \| preview \| stable \| deprecated`. Renders a `<StatusBadge>`. **`draft` is special-cased** (see below). |
+| `audience` | string[] | Who the page is for. Single string is coerced to a one-element array. Surfaced as `<div data-pagefind-filter="audience:<value>">` for search facets. |
+| `category` | string[] | Category segments. Auto-derived from path when absent (e.g. `/guides/auth/foo` → `["guides", "auth"]`). Hidden Pagefind facet. |
+| `tags` | string[] | Free-form chip strip on the article header. Slash-nested values link to taxonomy term pages (`api/rest` → `/tags/api/rest/`). |
+
+When **declared in `taxonomies:` config** (recommended), these
+also light up:
+
+- A browse index (`/tags/`, `/by-type/`, `/by-status/`, etc.)
+- Per-term pages (`/tags/concept/auth`, `/by-type/tutorial`)
+- A faceted-search checkbox group in `Cmd+K` search (one column
+  per declared taxonomy, sorted by frequency)
+- Display-config consumption for human labels and prefix
+  colors
+
+See `dogsbay:taxonomy-config` for the full taxonomy surface.
+
+### `status` is dual-purpose
+
+`status: draft` is **both** a taxonomy value AND aliased to
+`draft: true` as a build-time visibility gate. A page with
+`status: draft` is excluded from production builds the same
+way `draft: true` is. The other three values (`preview`,
+`stable`, `deprecated`) are pure taxonomy — they render a
+`<StatusBadge>` chip and populate the `/by-status/` browse
+page, but don't gate visibility.
+
+This is the only built-in taxonomy with overloaded semantics.
+Implications:
+
+- `status: draft` + `dogsbay site build` → page omitted from
+  output (the same N-drafts-excluded message fires).
+- `status: preview` / `stable` / `deprecated` → page ships
+  normally; just renders the badge and gets bucketed into
+  `/by-status/<value>/`.
+- A writer who wants `draft` to be a pure taxonomy value
+  (no exclusion) should rename to a different value (e.g.
+  `status: in-progress`) and customize the badge label via
+  `taxonomies.status.labels`.
+
+The escape hatch on `dogsbay site build` is `--include-drafts`
+(see the visibility section above).
+
+## SEO / social
+
+| Field | Type | Purpose |
+|---|---|---|
+| `ogImage` | string | Per-page Open Graph image URL. Falls back to `siteConfig.ogImage` then no OG image. |
+| `ogType` | string | Override `<meta property="og:type">` (default `article`). |
+| `canonicalUrl` | string | Explicit `<link rel="canonical">` href. Default: build-time-computed from `siteUrl` + URL. |
+
+## Agent surface
+
+| Field | Type | Purpose |
+|---|---|---|
+| `llmActions` | boolean / object | When `false`, suppress the per-page LLM-action UI cluster (Copy as markdown, Open in Claude, etc.). When an object, override placement / providers. See `dogsbay:agent-readiness`. |
+
+## Dates and ordering
+
+| Field | Type | Purpose |
+|---|---|---|
+| `updated` | date | ISO date string for "last updated" displays. Date objects are coerced via `.toISOString()`. |
+| `created` | date | ISO date string for "first published" displays. Same coercion. |
+| `weight` | number | Sort hint for term/index pages (lower first). Non-numeric values are dropped. |
+
+## Auto-rendering hints
+
+| Field | Type | Default | Purpose |
+|---|---|---|---|
+| `autoH1` | boolean | depends | When `true`, the layout renders `<h1>{title}</h1>` at the top of `<main>` if the body doesn't start with an H1. Computed per-page by the lede-detection step. |
+| `autoLede` | boolean | `false` | When `true`, render `<p>{description}</p>` below the auto-H1 (or above the meta strip when there's no H1). |
+
+## Multi-source axis metadata (read-only, set by aggregator)
+
+These get stamped by the multi-source aggregator when more than
+one source / version / locale is in play. Setting them manually
+is a mistake — the aggregator overwrites on every build.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `multiSource.namespace` | string | Set when ≥2 sources have distinct names. |
+| `multiSource.version` | string | Set when version axis is active. |
+| `multiSource.locale` | string | Set when locale axis is active. |
+| `multiSource.originalSlug` | string | Slug as the importer produced it before any axis prefixing. Used by the version-switcher to compute cross-version equivalents. |
+
+## Custom props bag
+
+| Field | Type | Purpose |
+|---|---|---|
+| `props` | object | Arbitrary key/value bag passed to the layout's per-page props slot. Useful for plugin or pattern integrations that need page-specific config without inventing a new top-level field. |
+
+# Tier 2: User-declared taxonomies
+
+Any frontmatter key you name in `taxonomies:` config gets
+lifted into `meta.taxonomies[name]` as a string array. Example:
+declaring `taxonomies.difficulty` in `dogsbay.config.yml` makes
+`difficulty: intermediate` available as a Pagefind facet, a
+browse page at `/by-difficulty/intermediate/`, and (with
+`prefixes:` config) a chip color.
+
+The five Tier 1 classification fields (`status`, `type`,
+`audience`, `category`, `tags`) are **also** valid in
+`taxonomies:` config — declaring them there extends their
+existing built-in behavior (chip strips, badges) with the
+taxonomy surface (browse pages, facets).
+
+Keys NOT in `taxonomies:` config are tier 3 (arbitrary).
+
+See `dogsbay:taxonomy-config` for the full taxonomy surface,
+including `prefixes` (chip colors), `labels` (display
+overrides), `values` (closed enum + audit), and `hierarchical`
+(slash-nested browsing).
+
+# Tier 3: Arbitrary frontmatter
+
+Anything not in tiers 1–2 is preserved on
+`ExportPage.frontmatter` and forwarded to the rendered page,
+but Dogsbay's importer + layout don't consume it. No semantic
+effect — no chips, no facets, no audit rules, no SEO meta.
+
+Use cases:
+
+- Internal annotations the writing team uses (e.g. a `reviewers:`
+  list rendered nowhere but tracked for editorial workflow).
+- Custom plugin inputs (a plugin can add an `auditRule` that
+  reads any frontmatter key — see `dogsbay:plugin-api`).
+- Importer-specific carry-through: Starlight's
+  `pcx_content_type`, MkDocs' `template`, etc. are preserved
+  but not lifted into Dogsbay's typed slots.
+
+Plugins promote arbitrary frontmatter to semantic via the
+`auditRules` and `componentWrappers` hooks. If you find
+yourself wanting an arbitrary field to "do something", that's
+the path.
+
+## Diátaxis (only if `@dogsbay/pattern-diataxis` is installed)
+
+The Diátaxis pattern adds audit rules that match on `meta.type`
+values:
+
+| Value | Triggers |
+|---|---|
+| `tutorial` | `diataxis/tutorial-*` audit rules (verb-led headings, step structure, etc.) |
+| `how-to` | `diataxis/how-to-*` rules |
+| `reference` | `diataxis/reference-*` rules |
+| `explanation` | `diataxis/explanation-*` rules |
+
+Without the pattern installed, `meta.type` still works — it
+renders a `<TypeBadge>` and powers `/by-type/` if you declare
+the taxonomy. The pattern just adds opinionated audit rules.
+
+# How importers + audit rules read frontmatter
+
+- **format-dogsbay-md** parses via gray-matter; the typed
+  subset becomes `ExportPage.title`, `description`, `redirect`.
+  The full raw YAML lands in `ExportPage.frontmatter`.
+- **format-mkdocs / format-obsidian / format-starlight** do
+  the same; importer-specific keys are preserved in
+  `frontmatter` but not lifted to typed fields.
+- **format-astro** writes the typed fields into the generated
+  `.astro` page's frontmatter; the layout reads them as props.
+- **dogsbay site check** rules can match on any frontmatter
+  key. `seo/description-missing` and `seo/description-length`
+  look at the `description` field directly.
+
+# Cross-format `description` quirk
+
+Three importers generate descriptions slightly differently:
+
+- **dogsbay-md** uses whatever's in frontmatter. Empty if
+  missing.
+- **MkDocs** falls back to the first paragraph if frontmatter
+  is empty (matching MkDocs Material convention).
+- **Starlight** treats the typed subset as authoritative.
+
+If the `seo/description-missing` audit fires unexpectedly,
+check whether the importer is providing a default vs requiring
+explicit declaration.
+
+# Common mistakes
+
+- ❌ Embedding YAML in the body (only the leading
+  `---`-delimited block is parsed; later `---` is rendered as
+  `<hr>`).
+- ❌ Single-quoted multi-line strings without `>` or `|` block
+  scalars — multi-line strings need YAML's block syntax.
+- ❌ Setting `multiSource.namespace` (or any `multiSource.*`)
+  manually — overwritten by the aggregator on every build.
+- ❌ Using `draft: 'true'` (string) instead of `draft: true`
+  (boolean) — strings are truthy but the audit rules check for
+  the boolean.
+- ❌ Adding `status: draft` (or `draft: true`) to a new page
+  by default. Branches handle draft state in a git workflow;
+  the frontmatter gate persists past merge and silently hides
+  the page in production. Only stamp draft when explicitly
+  asked.
+- ❌ Treating `status`, `type`, `audience`, `category`, `tags`
+  as user-defined fields. They're built-in classification with
+  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.
+- ❌ 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
+  the badge won't render and you'll waste time debugging.
+- ❌ Custom `slug` that doesn't match the file path's parent
+  segments — the URL becomes inconsistent with the file
+  hierarchy. Stick with file-path-derived slugs unless there's
+  a specific reason.

package/skills/platform/markdown-directives/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: dogsbay:markdown-directives
+description: Write Dogsbay markdown using the directive syntax for cards, steps, tabs, callouts, grids, details, and other components. Use when authoring or editing content/*.md pages.
+---
+
+# Dogsbay markdown directives
+
+Dogsbay markdown is a small superset of CommonMark with `:::name`
+block directives for the components docs sites need most. The
+directive syntax is parser-enforced — getting it wrong fails the
+build or renders as literal text.
+
+## Block directive shape
+
+```
+:::name{attr1="value" attr2="value"}
+content
+:::
+```
+
+Use `::::` (four colons) when the content itself contains `:::`
+(e.g., a directive nested inside another).
+
+## Callouts
+
+Two equivalent forms — pick whichever reads cleaner.
+
+### GitHub-alert form (preferred for note/warning/tip/danger)
+
+```markdown
+> [!NOTE]
+> Helpful supplemental information.
+
+> [!WARNING]
+> Don't do the thing.
+
+> [!TIP]
+> Confirmation that you're on the right track.
+
+> [!DANGER]
+> Destructive or irreversible.
+```
+
+The token after `[!` is the type — `NOTE`, `TIP`, `WARNING`,
+`DANGER`, `IMPORTANT`, `CAUTION`.
+
+### Directive form (for custom titles or types outside the GitHub set)
+
+```markdown
+:::callout{type="success" title="Build complete"}
+The site published in 4.2 seconds.
+:::
+```
+
+Without `title`, the directive form behaves identically to the
+GitHub form for the type.
+
+## Steps
+
+Numbered steps for sequential procedures. Renders as `<Steps>` +
+`<Step>` components with circle indicators.
+
+```markdown
+:::steps
+1. **Install the CLI**
+   Run `npm install -g dogsbay`.
+
+2. **Initialise**
+   Run `dogsbay site init my-docs`.
+
+3. **Preview**
+   Run `dogsbay site dev` and open localhost:4321.
+:::
+```
+
+The numbered-list inside is plain markdown. Bold the step's
+short verb, then a paragraph or code block of detail.
+
+## Tabs
+
+Side-by-side content using a definition-list inside `:::tabs`.
+
+```markdown
+:::tabs
+TypeScript
+:   ```ts
+    const x = 1;
+    ```
+
+Python
+:   ```py
+    x = 1
+    ```
+
+Curl
+:   ```bash
+    curl https://example.com/api
+    ```
+:::
+```
+
+The tab label is the term; the tab content is the definition
+(`:   …` with three spaces or a tab). Multi-line content is
+allowed; indent further lines to align with the first.
+
+## Cards
+
+Bulleted list of bold-link entries inside `:::cards`. Renders as
+a responsive grid.
+
+```markdown
+:::cards
+- **[Getting started](./getting-started)** {icon="rocket"}
+  Three-minute orientation to authoring.
+
+- **[API reference](./api/)** {icon="book-open"}
+  Endpoint browser, schemas, code samples.
+
+- **[GitHub](https://github.com/your-org/repo)** {icon="github"}
+  Star, browse, file an issue.
+:::
+```
+
+Each item: `- **[Title](href)**` optionally followed by an
+attribute block (`{icon="..."}`), then the description on the
+next line, indented two spaces. Optional blank line between
+items improves readability.
+
+### Icons on cards
+
+`icon` accepts any name from the platform Icon component
+(see `dogsbay:theme-tokens` for the Icon component reference):
+
+- **Bare names** default to Lucide:
+  `{icon="rocket"}`, `{icon="book-open"}`, `{icon="github"}`.
+  Browse the catalog at <https://lucide.dev/icons/>.
+- **`pack:name`** routes to other Iconify packs:
+  `{icon="mdi:home"}` (Material Design Icons),
+  `{icon="simple-icons:github"}` (brand glyphs),
+  `{icon="lucide:book-open"}` (explicit Lucide).
+- **Emoji shortcodes** map to Unicode characters when no
+  Iconify pack is given: `{icon="rocket"}` → 🚀,
+  `{icon="tada"}` → 🎉. The emoji map wins for bare names that
+  match it.
+
+When the name doesn't resolve in any pack, the icon slot
+renders nothing (silent fallback) — better than a broken-image
+placeholder, since the title and description still convey the
+card's intent.
+
+## Single card (with attrs or YAML body)
+
+For a standalone card with rich props, use the singular `:::card`
+directive:
+
+```markdown
+:::card{title="Pro plan" href="/pricing/pro"}
+For growing teams.
+:::
+```
+
+When prop count exceeds 3 OR any value contains a newline, the
+serializer switches to YAML body form:
+
+```markdown
+:::card
+---
+title: Pro plan
+description: |
+  For growing teams.
+  Includes priority support.
+href: /pricing/pro
+icon: rocket
+---
+:::
+```
+
+Both forms are accepted by the parser.
+
+## Link card (`:::link-card`)
+
+A focused variant of `:::card` for "go here next" navigation
+affordances. Renders a chevron arrow on the right and a
+distinctive hover state — visually clearer that it's a link
+rather than a content tile.
+
+```markdown
+:::link-card{title="Configuration guide" href="/config/"}
+Site name, theme, base path, and per-source settings live in
+dogsbay.config.yml.
+:::
+```
+
+YAML body form when prop count or content grows:
+
+```markdown
+:::link-card
+---
+title: Configuration guide
+description: |
+  Site name, theme, base path, and per-source settings live in
+  dogsbay.config.yml.
+href: /config/
+---
+:::
+```
+
+Props: `title` (required), `href` (required), `description`
+(optional — also accepted as the body paragraph for ergonomic
+authoring). No `icon` slot — link-cards intentionally lean on
+the chevron alone for the link affordance. When you need an
+icon, use `:::card`.
+
+### When to pick which card directive
+
+- **`:::cards`** (plural) — list of related links, displayed as
+  a responsive grid. Best for "browse next" clusters at the
+  end of a page or on a landing page. Items are bulleted-link
+  shorthand.
+- **`:::card`** (singular) — one rich card with full prop
+  surface (`icon`, `variant`, custom classes, arbitrary body).
+  Use when you want a tile with deliberate visual weight.
+- **`:::link-card`** — one card scoped to a single navigation
+  link, with chevron arrow. Use for callouts that lead the
+  reader somewhere specific ("Continue with Configuration
+  guide →").
+
+## Grid
+
+Generic responsive grid container with `cols` and `gap` attrs:
+
+```markdown
+:::grid{cols="3" gap="4"}
+
+Cell A
+
+Cell B
+
+Cell C
+
+:::
+```
+
+Each cell is plain markdown content (a paragraph, a callout, a
+code block, etc.). Empty lines between cells separate them.
+
+## Details (collapsible)
+
+```markdown
+:::details{title="Show advanced configuration"}
+The expanded content goes here.
+
+Multi-paragraph + code blocks + nested directives all work.
+:::
+```
+
+Renders as `<details><summary>Title</summary>...</details>`.
+Closed by default; pass `open="true"` to start expanded.
+
+## Code blocks
+
+Triple-backtick fenced blocks with language identifiers. Always
+specify the language for syntax highlighting:
+
+````markdown
+```bash
+curl -X POST https://api.example.com/v1/pets
+```
+
+```yaml title="dogsbay.config.yml"
+site:
+  name: Example
+```
+````
+
+Supported attributes on the fence:
+
+- `title="..."` — header bar above the code block
+- `lineNumbers` — render line numbers
+- `frame="terminal"` — terminal styling
+
+## Inline directives
+
+For inline-level marks, use `:name[text]{attrs}`:
+
+```markdown
+Press :kbd[Ctrl+C] to copy.
+This is :badge[New]{tone="success"} content.
+Click :icon[rocket] to launch, or :icon[mdi:home] to go home.
+```
+
+`:icon[name]` accepts the same shorthand as the `{icon=...}`
+attribute on cards — bare names default to Lucide,
+`pack:name` routes to other Iconify packs, emoji shortcodes
+render as Unicode. See "Icons on cards" above.
+
+## Frontmatter
+
+Every page should start with YAML frontmatter delimited by `---`:
+
+```markdown
+---
+title: Configuration
+description: How to configure the site via dogsbay.config.yml.
+---
+
+# Configuration
+
+…
+```
+
+See `dogsbay:frontmatter-fields` for the platform-recognised
+fields.
+
+## Common mistakes
+
+- ❌ Using `<Cards>` JSX — Dogsbay markdown is NOT MDX. Use
+  `:::cards` directives instead.
+- ❌ Forgetting the language identifier on code fences — most
+  themes won't highlight without it.
+- ❌ Mixing tab definition-list `:` with regular list `-` markers
+  — they're different syntactic structures.
+- ❌ Writing card descriptions on the same line as the title —
+  must be on the next line, indented two spaces.
+- ❌ Using a non-existent icon name. The icon slot fails
+  silently when the name doesn't resolve, so a typo leaves the
+  card looking wrong without any error. Verify Lucide names
+  against <https://lucide.dev/icons/> or use the `pack:name`
+  form to be explicit.