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

package/skills/platform/multi-source/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: dogsbay:multi-source
+description: How sources[] aggregation works in Dogsbay — multiple content sources with locale, version, and namespace axes producing unified URLs and per-source nav. Use when configuring multi-source sites, multi-version setups, or i18n.
+---
+
+# Multi-source aggregation
+
+Dogsbay treats versioning, i18n, and multi-repo aggregation as
+the **same problem with different metadata keys**. One mechanism
+solves all three: each entry in `content.sources[]` carries
+optional `name`, `version`, `locale` metadata, and the
+aggregator activates a URL axis when ≥2 sources have distinct
+values.
+
+## Three axes, one URL convention
+
+```
+/<basePath>/<locale>/<version>/<namespace>/<page-slug>
+```
+
+Each axis is **omitted from URLs when not in use**. The base
+case (single locale, version, namespace) keeps URLs flat:
+`/docs/intro`. Add axes by configuring sources; the URL grows
+left-to-right in canonical order.
+
+| Configuration | URL example |
+|---|---|
+| Single source, no axis metadata | `/docs/intro` |
+| i18n only | `/docs/en/intro`, `/docs/fr/intro` |
+| Versioning only | `/docs/v1/intro`, `/docs/latest/intro` |
+| Locale + version | `/docs/en/v2/intro`, `/docs/fr/latest/intro` |
+| Multi-namespace | `/docs/api-reference/intro`, `/docs/handbook/intro` |
+| All three | `/docs/en/v2/api-reference/intro` |
+
+Order: locale → version → namespace. Locale outermost matches
+universal convention (Mintlify, Starlight, Cloudflare Docs).
+Version inside locale because each locale has its own version
+cadence.
+
+## When does an axis activate?
+
+The aggregator inspects the configured sources at build time:
+
+- **Locale axis** active when ≥2 distinct `locale:` values appear
+- **Version axis** active when ≥2 distinct `version:` values appear
+- **Namespace axis** active when ≥2 distinct `name:` values appear
+
+`undefined` counts as a distinct bucket. So:
+
+- One source with `locale: en`, one with no `locale:` → locale
+  axis IS active. The unspecified source's pages stay flat
+  (`/docs/page`); the `en:` source's pages get `/docs/en/page`.
+- Five sources all with `locale: en` → locale axis is NOT active.
+  The metadata is uniform; no prefix needed.
+
+This produces the "current + archived" / "default + i18n" patterns
+naturally. Adding versioning to one source never silently
+rewrites URLs in the unversioned baseline.
+
+## Source descriptor
+
+```yaml
+content:
+  sources:
+    # Local filesystem
+    - name: docs
+      path: ./content/v1
+      version: v1
+      locale: en
+      from: dogsbay-md
+      primary: true
+
+    # Git checkout — fetched at build time
+    - name: api-reference
+      git: https://github.com/acme/api-docs.git
+      ref: v1.0
+      subdir: docs            # optional path within the repo
+      version: v1
+
+    # Same source as a different version
+    - name: docs
+      path: ./content/v2
+      version: v2
+      locale: en
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `path` OR `git` | yes (exactly one) | Origin |
+| `ref` | required when `git:` is set | Branch / tag / sha |
+| `subdir` | no | Subdirectory within resolved source |
+| `name` | no | Namespace key |
+| `version` | no | Version label |
+| `locale` | no | BCP-47 locale tag |
+| `from` | no | One of `auto`, `dogsbay-md`, `mkdocs`, `obsidian`, `starlight`, `mdx`, `openapi` |
+| `nav` | no | Path to explicit nav file |
+| `primary` | no | Marks this source for primary build mode |
+
+## Single canonical shape — `sources[]` only
+
+Even one source uses the array. There is no `content.source:`
+shorthand. Single-source pays one extra YAML line; in exchange
+the schema, loader, and docs stay simple.
+
+```yaml
+content:
+  sources:
+    - path: ./content
+```
+
+## Defaults for missing axis metadata
+
+When an axis IS active but a source omits the key:
+
+| Axis | Default |
+|---|---|
+| `locale` | falls back to `defaultLocale` if declared, else `undefined` (no segment) |
+| `version` | falls back to `defaultVersion` if declared, else `undefined` (no segment) |
+| `namespace` | `undefined` — no segment, even when other sources have names |
+
+The `undefined`-as-distinct-bucket semantics let users mix
+"current" + "archived" sources without explicit metadata on the
+current one.
+
+## Build modes — `all` (default) vs `primary-only`
+
+```bash
+dogsbay site build                  # all sources (default — full matrix)
+dogsbay site build --primary-only   # only sources marked primary: true
+dogsbay site dev                    # primary-only (fast iteration)
+dogsbay site dev --full             # all sources (preview switcher chrome)
+```
+
+`dogsbay site build` defaults to **publish mode** — every declared
+source builds. Declaring `locales:`, `versions:`, or multiple
+sources in config is a strong signal you want them all in
+production; a writer who runs `site build` after declaring a
+French locale should see French in the output, not silently dropped.
+
+`--primary-only` is the opt-out for fast-iteration CI lint jobs
+that don't need the full matrix (rare). When ≥1 source has
+`primary: true`, primary-only loads just those. If NO source has
+`primary: true`, the filter is inert (every source loads).
+
+`dogsbay site dev` is the writer's iteration loop and defaults to
+`primary-only` for speed. Use `--full` to preview the version /
+locale switcher chrome locally.
+
+The legacy `--publish` flag is kept as a deprecated no-op for
+older scripts; publish IS the default now.
+
+## Namespace nav merging
+
+Each source's nav becomes a top-level group in the unified
+sidebar:
+
+```
+Sidebar:
+  Docs                               ← namespace "docs" group
+    Getting started
+    Concepts
+    …
+  API reference                      ← namespace "api-reference" group
+    Authentication
+    Endpoints
+    …
+```
+
+Sources without an explicit `name:` contribute their nav flat
+(no group wrapper).
+
+## Per-page axis metadata
+
+When ANY axis is active, every imported page gets
+`page.multiSource` populated:
+
+```ts
+{
+  namespace?: string;     // when namespace axis active
+  version?: string;       // when version axis active
+  locale?: string;        // when locale axis active
+  originalSlug: string;   // slug as the importer produced it
+}
+```
+
+Used by:
+
+- The version-switcher UI (cross-version equivalents)
+- The locale-switcher UI (translated equivalents)
+- Hreflang / canonical tag emission
+- The agent-readiness `.md` mirror with axis context
+
+## Common patterns
+
+### Versioning markdown sources
+
+```yaml
+content:
+  sources:
+    - path: ./content                    # current — flat URLs
+      from: dogsbay-md
+      primary: true
+
+    - path: ./archive/v1
+      from: dogsbay-md
+      version: v1                        # archived — /docs/v1/...
+
+    - path: ./archive/v0
+      from: dogsbay-md
+      version: v0                        # archived — /docs/v0/...
+
+versions:
+  - id: latest
+    label: Latest
+    default: true
+  - id: v1
+    label: v1
+  - id: v0
+    label: v0 (legacy)
+    eol: 2025-12-31                      # tombstones in switcher
+```
+
+### Mixed prose + API ref with independent versions
+
+```yaml
+content:
+  sources:
+    # Evergreen prose
+    - path: ./content
+      from: dogsbay-md
+
+    # API ref — date-pinned
+    - name: api
+      path: ./openapi/2024-04-10.yaml
+      from: openapi
+      version: "2024-04-10"
+      primary: true
+
+    - name: api
+      path: ./openapi/2023-12-01.yaml
+      from: openapi
+      version: "2023-12-01"
+```
+
+URLs:
+```
+/docs/                                      ← prose, versionless
+/docs/api/2024-04-10/                       ← API root, latest spec
+/docs/api/2024-04-10/pets/list-pets         ← operation
+/docs/api/2023-12-01/pets/list-pets         ← same op, prior version
+```
+
+### Multi-locale with git origin
+
+```yaml
+content:
+  sources:
+    - path: ./content
+      locale: en
+      primary: true
+
+    - git: https://github.com/acme/docs-fr.git
+      ref: main
+      locale: fr
+
+    - git: https://github.com/acme/docs-pt-BR.git
+      ref: main
+      locale: pt-BR
+
+locales:
+  - id: en
+    label: English
+  - id: fr
+    label: Français
+  - id: pt-BR
+    label: Português (Brasil)
+```
+
+URLs: `/docs/en/...`, `/docs/fr/...`, `/docs/pt-BR/...`. Plus a
+default-locale redirect from `/docs/...` to `/docs/en/...`.
+
+## Common mistakes
+
+- ❌ Setting `version:` on one source and not declaring the
+  version in `versions:[]` — fails validation.
+- ❌ Mixing `defaultVersion: latest` with no `version:` field on a
+  source — the source's pages get `/docs/latest/...` URLs even
+  when you wanted them flat. Drop `defaultVersion` for the
+  current-baseline pattern.
+- ❌ Hand-editing `multiSource.namespace` in frontmatter — the
+  aggregator overwrites it on every build.
+- ❌ Trying to emit nav hrefs with hand-written axis prefixes —
+  the aggregator does this; importers should write hrefs
+  relative to their content root.

package/skills/platform/nav-file/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dogsbay:nav-file
+description: Write or edit a Dogsbay nav file (nav.yml, nav.yaml, or nav.json) with the correct single-key-map syntax. Use when the user asks to add pages to the sidebar, reorder the sidebar, create grouped sections, or fix a malformed nav file.
+---
+
+# Writing a Dogsbay nav file
+
+Dogsbay's sidebar nav lives in the content directory under one of:
+
+- `nav.json` (highest precedence)
+- `nav.yml`
+- `nav.yaml`
+
+The loader auto-detects in that order. Most users pick `nav.yml` because YAML is friendlier to edit.
+
+## Format — single-key maps
+
+Each entry is a **single-key map** where the key is the sidebar label and the value is one of:
+
+- A file path relative to `content/` — leaf link
+- An absolute URL (`http://`, `https://`, etc.) — external leaf
+- A list of child entries — group
+
+```yaml
+- Home: index.md
+- Getting started: getting-started.md
+- Guides:
+    - Configuration: guides/configuration.md
+    - Deployment: guides/deployment.md
+- Source: https://github.com/your-org/your-repo
+```
+
+## What NOT to write
+
+This is the most common mistake. The loader will print a "malformed" warning and fall back to directory-scan order:
+
+```yaml
+# ❌ WRONG — multi-key map
+- label: Home
+  href: /docs/
+
+# ❌ WRONG — using href for internal pages
+- Home: /docs/
+- Getting started: /docs/getting-started
+
+# ❌ WRONG — missing .md extension on file paths
+- Home: index
+```
+
+The validator throws `Nav entry must have exactly one key at [N]. Got 2: ["label","href"]` for the first form.
+
+## URL derivation — never write absolute paths for internal pages
+
+URLs are composed at build time from the configured `basePath`, the active multi-source axes (locale / version / namespace), and the file path. Always use the **file path relative to the content directory**, never a hand-written URL.
+
+If the user has `basePath: /docs` and a markdown source named `api`:
+
+- `index.md` → `/docs/api/`
+- `getting-started.md` → `/docs/api/getting-started`
+- `guides/configuration.md` → `/docs/api/guides/configuration`
+
+Hand-writing `/docs/getting-started` works today but breaks when the user changes `basePath`, adds a version axis, or activates locales. Always use the file path.
+
+## Groups vs leaf-with-children
+
+A group has no associated page — clicking the label expands the children. To make the GROUP itself link to a page (a section landing page), use this combined shape:
+
+```yaml
+- Guides:
+    - guides/index.md          # bare string entry — sets the group's href to this page
+    - Configuration: guides/configuration.md
+    - Deployment: guides/deployment.md
+```
+
+The leading bare-string entry is parsed as the group's own `href`/`file`. Without it, the group is an expand-only label.
+
+## External URLs
+
+Use absolute URLs for external destinations. The loader treats anything starting with `http://`, `https://`, or `mailto:` as an external link (no axis prefixing applied):
+
+```yaml
+- API reference: api/index.md
+- GitHub: https://github.com/your-org/your-repo
+- Status: https://status.your-org.com
+- Contact: mailto:hello@your-org.com
+```
+
+## When there's no nav file
+
+If `content/nav.{json,yml,yaml}` doesn't exist, the loader does a directory scan and produces nav from filenames. The order is alphabetical with `index.md` first per directory. This works for prototyping but quickly stops being what the user wants — encourage authoring `nav.yml` early.
+
+## When the user moves or renames a page
+
+Update three places:
+
+1. The file itself (move/rename in `content/`)
+2. The `nav.yml` entry (update the file path)
+3. Add a redirect in `dogsbay.config.yml` if the old URL was published
+
+```yaml
+# In dogsbay.config.yml
+site:
+  redirects:
+    /docs/old-page: /docs/new-page
+```
+
+Skipping (3) breaks bookmarks and external links.

package/skills/platform/openapi-source/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: dogsbay:openapi-source
+description: Add an OpenAPI 3.x spec as a content source in a Dogsbay site. Renders endpoint pages inline alongside markdown prose. Use when configuring API reference, multi-version OpenAPI, or x-codeSamples.
+---
+
+# OpenAPI as a content source
+
+Dogsbay treats OpenAPI 3.x as a first-class content source. The
+`@dogsbay/format-openapi` importer reads the spec, parses it
+with `@scalar/openapi-parser` (handles dereferencing, includes
+Swagger 2 conversion), and emits one `.astro` page per
+operation plus tag-overview pages and a root info page.
+
+The rendering is **inline** — endpoints render through real
+Dogsbay components (`EndpointCard`, `ApiLayout`,
+`ParameterTable`, `SchemaViewer`, `ResponseTabs`,
+`CodeSamples`), not via an iframe.
+
+## Basic config
+
+```yaml
+content:
+  sources:
+    - path: ./content                # markdown prose
+      from: dogsbay-md
+
+    - name: api
+      path: ./openapi/petstore.yaml  # path to spec file (or URL)
+      from: openapi
+```
+
+Required: `from: openapi`. Auto-detection (`from: auto`) doesn't
+fire for OpenAPI — extension-based detection is too ambiguous.
+
+## Path forms
+
+The `path:` value can be:
+
+- A direct file path (`./openapi/petstore.yaml`, `./spec.json`)
+- A directory containing `openapi.{yaml,yml,json}` or
+  `spec.{yaml,yml,json}` — auto-detected
+- An HTTP(S) URL — fetched at build time
+
+YAML and JSON specs both work; the parser handles both.
+
+## URLs produced
+
+With `name: api` and `basePath: /docs`:
+
+```
+/docs/api/                              ← root info page (info.title + description)
+/docs/api/<tag-slug>/                   ← per-tag overview
+/docs/api/<tag-slug>/<operation-slug>   ← one per operation
+```
+
+Operation slug derivation:
+
+- `operationId` if set (kebab-cased) — most public specs set it
+- Fallback: `{method}-{path-slug}` from the wire path
+
+Stripe-style URLs (`/docs/api/pets/list-pets`) come from
+operationId. Method-path URLs (`/docs/api/get-pets-petid`) come
+from the fallback. Either way, the path is stable.
+
+## Multi-version OpenAPI
+
+The version axis works for OpenAPI sources just like markdown
+sources. Per-source independent versioning:
+
+```yaml
+content:
+  sources:
+    - path: ./content                # markdown evergreen
+      from: dogsbay-md
+
+    - name: api
+      path: ./openapi/2024-04-10.yaml
+      from: openapi
+      version: "2024-04-10"
+
+    - name: api
+      path: ./openapi/2023-12-01.yaml
+      from: openapi
+      version: "2023-12-01"
+
+versions:
+  - id: "2024-04-10"
+    label: "2024-04-10 (latest)"
+    default: true
+  - id: "2023-12-01"
+    label: "2023-12-01"
+```
+
+Resulting URLs:
+
+```
+/docs/                                      ← prose, versionless
+/docs/api/2024-04-10/pets/list-pets
+/docs/api/2023-12-01/pets/list-pets
+```
+
+The version-switcher UI scopes to whichever pages have axis
+activity — only `/docs/api/...` pages show the switcher; prose
+stays flat.
+
+This is the **Mintlify-style independent-axis model** (Stripe,
+Twilio, GitHub all do this). API moves on its own cadence;
+prose stays evergreen.
+
+## Hand-curated code samples — `x-codeSamples`
+
+Auto-generated samples (curl + Python + TypeScript) are
+emitted by default. To override with hand-written examples,
+use the Redoc convention `x-codeSamples` on the operation:
+
+```yaml
+paths:
+  /pets:
+    post:
+      summary: Create a pet
+      x-codeSamples:
+        - lang: shell
+          label: cURL
+          source: |
+            curl -X POST "https://api.example.com/v1/pets" \
+              -H "Authorization: Bearer $TOKEN" \
+              -d '{"name":"Rex"}'
+        - lang: typescript
+          source: |
+            await client.pets.create({ name: "Rex" });
+```
+
+When `x-codeSamples` is present, it **replaces** the
+auto-generated samples entirely (not added alongside). The
+legacy `x-code-samples` (kebab) spelling is also accepted.
+
+## Deprecating an operation
+
+Set `deprecated: true`:
+
+```yaml
+paths:
+  /orders:
+    post:
+      summary: Place an order
+      deprecated: true
+      …
+```
+
+The endpoint page renders a warning banner. The `.md` mirror
+prefixes the operation with a `> [!WARNING]` callout so agents
+see the deprecation status too.
+
+## Components on the rendered page
+
+Each operation page emits an `<ApiLayout>` with two slots:
+
+- **description**: `<EndpointCard>` containing `<EndpointSection>`
+  blocks for parameters / request body / responses, using
+  `<PropertyList>` (Stripe-style location-grouped) /
+  `<SchemaViewer>` / `<ResponseTabs>`
+- **code**: `<ApiCodePanel>` with `<CodeSamples>` plus per-status
+  `<ExampleBlock>` panels with content-type-aware syntax
+  highlighting
+
+The full URL bar at the top of the description column tints
+its background to the HTTP method colour (Stripe / Redoc /
+Mintlify convention) — GET = green, POST = blue, etc.
+
+## What's NOT yet supported
+
+- **Multi-server picker** (`servers[]` with sandbox / production)
+  — currently uses `servers[0].url` only.
+- **`x-internal` honour** — known limitation; see
+  `plans/openapi-builtin-followups.md`.
+- **Live "Try it" execution** — out of scope; ships as a future
+  plugin.
+- **AsyncAPI / WebSocket / gRPC** — different specs; separate
+  importer.
+
+## Common patterns
+
+### Single-source API ref
+
+```yaml
+content:
+  sources:
+    - path: ./openapi/petstore.yaml
+      from: openapi
+```
+
+URLs: `/docs/`, `/docs/<tag>/<operation>` (no namespace prefix
+because there's only one source).
+
+### Multi-source: prose + API ref under /docs/api/
+
+```yaml
+content:
+  sources:
+    - path: ./content
+      from: dogsbay-md
+    - name: api
+      path: ./openapi/spec.yaml
+      from: openapi
+```
+
+The seminal Dogsbay-OpenAPI pattern. Prose stays flat at
+`/docs/`; API reference under `/docs/api/`.
+
+### Remote OpenAPI URL
+
+```yaml
+content:
+  sources:
+    - name: api
+      path: https://api.example.com/openapi.json
+      from: openapi
+```
+
+Fetched at build time. Useful when the spec is generated
+upstream (e.g. by a backend codebase) and the docs site
+shouldn't have a vendored copy.
+
+## Common mistakes
+
+- ❌ Forgetting `from: openapi` — auto-detection fails on `.yaml`
+  / `.json` (too ambiguous), the source falls through importers
+  and errors.
+- ❌ Setting `name: api` and expecting to write `/api/foo`
+  manually in a markdown link — the namespace prefix is
+  build-time-resolved, write `./api/foo` (relative) or use the
+  full `${basePath}/api/...`.
+- ❌ Per-version OpenAPI with the same `version:` value on both
+  sources — version axis doesn't activate; pages collide. Each
+  spec needs a distinct version label.
+- ❌ Using `x-codeSamples` AND expecting auto-generated samples
+  alongside — vendor samples replace, not augment.