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

package/skills/platform/cli-commands/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: dogsbay:cli-commands
+description: Reference for every dogsbay CLI command and flag — site init/build/dev/preview/check, astro init/add/list, convert, pattern install, agent install. Use when running CLI operations or recommending the right subcommand.
+---
+
+# Dogsbay CLI command reference
+
+Three command namespaces, each with a clear scope:
+
+- `dogsbay site …` — full SSG; Dogsbay owns the project (`dogsbay.config.yml` at root)
+- `dogsbay astro …` — drop Dogsbay components into someone else's existing Astro project
+- `dogsbay convert …` — pure content-format primitive; no SSG, no install
+
+## site init
+
+Scaffold a new Dogsbay-owned project.
+
+```bash
+dogsbay site init [target] [flags]
+```
+
+| Flag | Purpose |
+|---|---|
+| `--yes` | Non-interactive; combine with `--site-name` and `--content` |
+| `--site-name <string>` | Site name (required in non-interactive mode) |
+| `--content <path>` | Content directory path (required in non-interactive mode) |
+| `--from <format>` | Source format: `auto`, `dogsbay-md`, `mkdocs`, `obsidian`, `starlight`, `mdx`, `openapi` |
+| `--theme <name>` | `default` or `material` |
+| `--deploy <target>` | `cloudflare-workers` adds wrangler config + worker emission |
+| `--scaffold-only` | Skip writing dogsbay.config.yml; just scaffold astro/. Used when content + config already exist. |
+| `--force` | Overwrite an existing scaffold |
+| `--local` | Use `link:` deps to a local monorepo checkout (development only) |
+| `--config-format <yaml\|json>` | Default `yaml` |
+
+Writes (default): `dogsbay.config.yml` + `content/index.md` + `content/getting-started.md` + `content/nav.yml` + `astro/` scaffold. Never overwrites an existing `content/` dir (the seed-content step is skipped if it exists).
+
+## site build
+
+Build Astro source from the configured sources. Generates pages, nav.json, and agent-readiness files.
+
+```bash
+dogsbay site build [flags]
+```
+
+| Flag | Purpose |
+|---|---|
+| `--config <path>` | Explicit config path |
+| `--include-drafts` | Include pages with `draft: true` in frontmatter (default false; site dev defaults true) |
+| `--primary-only` | Build only sources marked `primary: true` — fast iteration. Default builds the full matrix (every locale / version / namespace declared in config). |
+| `--publish` | Deprecated no-op (publish IS the default now). Kept for compat with older scripts. |
+| `--refresh` | Invalidate the git-source cache and re-clone |
+
+Writes into the configured `output:` (default `./astro/`). Doesn't run Astro itself — that's `site dev` / `site preview`.
+
+## site dev
+
+Build + serve with hot reload at localhost:4321.
+
+```bash
+dogsbay site dev [flags]
+```
+
+| Flag | Purpose |
+|---|---|
+| `--no-build` | Skip the implicit `site build`; only run Astro dev server |
+| `--full` | Build the full publish matrix (every source) |
+| `--config <path>` | Explicit config path |
+
+Auto-installs scaffolded site deps on first run if `astro/node_modules` is missing. Picks pnpm if on PATH, falls back to npm.
+
+## site preview
+
+Production build + static serve.
+
+```bash
+dogsbay site preview [flags]
+```
+
+Runs `dogsbay site build` then `astro build` then `astro preview`. Same flags as `site dev`. Used for verifying the deployable artefact locally.
+
+## site check
+
+Run audit rules against built content.
+
+```bash
+dogsbay site check [flags]
+```
+
+| Flag | Purpose |
+|---|---|
+| `--quiet` | Suppress stdout (still writes JSON output if requested) |
+| `--output <path>` | Write findings to a JSON file |
+| `--rule <name>` | Run only the named rule (or comma-separated list) |
+| `--severity <level>` | Filter to error / warning / info |
+
+Audit categories (some shipped, some pending): coherence (broken links, orphan pages), seo (titles, descriptions, brand keywords), prose (Vale wrapper), corpus (duplicate paragraphs), performance (page weight), freshness (stale pages, dead screenshots), aeo (agent readability, llms.txt coverage).
+
+## astro init
+
+Scaffold theme + path aliases into an existing Astro project (where Dogsbay is a guest, not the owner).
+
+```bash
+dogsbay astro init
+```
+
+Writes `src/styles/theme.css`, `src/styles/global.css`, sets `@/*` and `@ui/*` path aliases in `tsconfig.json`. Doesn't write a dogsbay.config.yml.
+
+## astro add
+
+Copy components into an Astro project. The component must exist in the registry (see `astro list`).
+
+```bash
+dogsbay astro add card badge button
+```
+
+Resolves `registryDependencies` (e.g. `form` auto-adds `field`). Installs npm deps for components that need them (e.g. `maplibre-gl` for `map-view`).
+
+## astro list
+
+Show every registered component grouped by category.
+
+```bash
+dogsbay astro list
+```
+
+72 components across base UI / docs / API / map / layout categories.
+
+## convert
+
+Pure content-format primitive. Reads source markdown, writes target format. No project scaffolding.
+
+```bash
+dogsbay convert <src> --to <format> [-o <output>]
+```
+
+| `--to` value | Target |
+|---|---|
+| `astro` | `.astro` pages + `nav.json` (no full Astro project — just the content tier) |
+| `dogsbay-md` | Normalise to canonical Dogsbay markdown |
+
+Used for one-shot migrations and CI-style content transformations.
+
+## pattern install
+
+Install a pattern package into the project (Diátaxis content types, Google-style guide, etc.).
+
+```bash
+dogsbay pattern install diataxis
+dogsbay pattern install @your-org/pattern-internal
+```
+
+Copies templates into `.dogsbay/patterns/<name>/`. Adds the pattern's audit rules to `dogsbay.config.yml`'s registered list (with user confirmation). See `dogsbay:taxonomy-config` for what patterns can register.
+
+## agent install
+
+Wire skill discovery for an agent harness.
+
+```bash
+dogsbay agent install --agent claude
+dogsbay agent install --agent cursor
+dogsbay agent install --all
+dogsbay agent install --workflow pr-review
+```
+
+| Flag | Purpose |
+|---|---|
+| `--agent <name>` | Set up discovery for a specific agent (claude, cursor, copilot) |
+| `--all` | Set up every supported agent |
+| `--workflow <name>` | Install a workflow package (writes to `.github/workflows/`, etc.) |
+
+Without `--agent` or `--workflow`, prints a list of detected agents in the project + suggests next-step commands.
+
+## Common patterns
+
+### First-run after clone
+
+```bash
+git clone …
+cd …
+dogsbay site dev      # auto-installs deps + builds + serves
+```
+
+### Migrating from MkDocs
+
+```bash
+dogsbay convert ./mkdocs-site --to astro -o ./astro-pages
+# OR for a fresh Dogsbay site:
+dogsbay site init my-docs --content ./mkdocs-site/docs --from mkdocs
+```
+
+### Production publish to Cloudflare
+
+```bash
+dogsbay site build                # builds full matrix by default
+cd astro && pnpm run build && wrangler deploy
+# OR via the deploy script:
+cd astro && pnpm run deploy
+```
+
+### Adding components mid-project
+
+```bash
+dogsbay astro add tabs accordion popover
+# components copied to src/components/ui/
+```

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

@@ -0,0 +1,219 @@
+---
+name: dogsbay:config-yml
+description: Read or write fields in dogsbay.config.yml. Use when configuring site identity, base path, multi-source content, theme, deploy target, agent readiness, plugins, taxonomies, or any other site-wide setting.
+---
+
+# Writing dogsbay.config.yml
+
+The config file lives at the project root. It anchors path resolution
+for `output:`, content sources, and the scaffolded astro/ subdir.
+
+YAML is the canonical format (`.yml`). JSON is also accepted
+(`dogsbay.config.json`); the loader picks whichever exists.
+
+## Top-level shape
+
+```yaml
+schemaVersion: 1
+
+site:                  # site identity
+  name: …
+  url: …
+  basePath: /docs
+  description: …
+
+content:               # one or more content sources
+  sources:
+    - …
+
+theme: default         # or "material"
+
+agent:                 # agent-readiness toggles
+  llmsTxt: true
+  mdMirror: true
+
+deploy:                # optional deploy target
+  target: cloudflare-workers
+
+plugins:               # plugin configurations
+  - …
+
+taxonomies:            # tagging schemes (user-defined)
+  …
+
+analytics:             # optional
+  plausible:
+    domain: …
+
+output: ./astro        # where the scaffold lives
+```
+
+## site
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | Shown in header, page-title suffixes, copyright. |
+| `url` | string | recommended | Canonical site URL. **Must be host-only when `basePath` is set** — `https://example.com`, NOT `https://example.com/docs`. The validator throws otherwise. Used for sitemap, canonical tags, OG meta. |
+| `basePath` | string | no | URL prefix for all pages. Defaults to `/docs`. Set to `""` for root-mounted sites. |
+| `description` | string | no | Site-wide description; default `og:description` and `<meta name="description">`. |
+| `repoUrl` | string | no | Source repo URL — used for edit-on-GitHub links. |
+| `editUri` | string | no | Path inside repo for edit links, e.g. `blob/main/content/`. |
+| `copyright` | string | no | Footer copyright text. |
+| `redirects` | object | no | Map of old-path → new-path. Emitted as redirects in the build output. |
+| `brandKeywords` | string[] | no | Used by the `seo/h1-brand-keyword` audit rule. |
+
+## content.sources
+
+Each entry is a `SourceConfig`. The aggregator concatenates them in declaration order. See `dogsbay:multi-source` for the full axis model.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `path` | string | one of path/git | Local directory containing the source. |
+| `git` | string | one of path/git | Git URL — checked out at build time. Requires `ref:`. |
+| `ref` | string | required when git is set | Branch / tag / sha. |
+| `subdir` | string | no | Subdirectory within the resolved source. |
+| `from` | enum | no | One of `auto`, `dogsbay-md`, `mkdocs`, `obsidian`, `starlight`, `mdx`, `openapi`. Default `auto` (detection by content). |
+| `name` | string | no | Namespace key — when ≥2 sources have distinct names, the namespace axis activates. |
+| `version` | string | no | Version label — when ≥2 sources have distinct versions, the version axis activates. |
+| `locale` | string | no | BCP-47 locale tag. |
+| `nav` | string | no | Path to an explicit nav file. Defaults to auto-detect (see `dogsbay:nav-file`). |
+| `primary` | boolean | no | Marks this source for the primary build mode (default mode for `site dev` / `site build`). |
+
+## theme
+
+`default` or `material`. Default is `default` (shadcn-style zinc). Both ship with 60 design tokens — see `dogsbay:theme-tokens` for what's overridable.
+
+## agent
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `llmsTxt` | boolean | `true` | Emit `public/llms.txt` and `public/llms-full.txt`. |
+| `mdMirror` | boolean | `true` | Emit a `.md` mirror endpoint for every page (e.g. `/docs/page.md`). |
+| `contentSignal` | object | none | Sets `Content-Signal: aiTrain=…, aiInput=…, search=…` headers. Each key is `"yes"` / `"no"`. |
+
+See `dogsbay:agent-readiness` for the full agent surface.
+
+## deploy
+
+```yaml
+deploy:
+  target: cloudflare-workers
+```
+
+Currently supports `cloudflare-workers`. Adds wrangler.jsonc + worker emission to the scaffold.
+
+## plugins
+
+Each entry is either a string (the package name) or an object with options. The CLI auto-prefixes `@dogsbay/plugin-` and `dogsbay-plugin-` for short names:
+
+```yaml
+plugins:
+  - image-zoom                         # resolves to @dogsbay/plugin-image-zoom
+  - "@your-org/plugin-foo"             # explicit
+  - name: typedoc                      # with options
+    options:
+      sourceRoot: ./src
+```
+
+See `dogsbay:plugin-api` for what plugins can do.
+
+## taxonomies
+
+User-defined tagging schemes. Dogsbay doesn't prescribe categories; this is the slot for the user's opinions. See `dogsbay:taxonomy-config`.
+
+## analytics
+
+```yaml
+analytics:
+  plausible:
+    domain: docs.example.com
+    scriptUrl: https://plausible.io/js/script.js   # optional
+```
+
+Plausible is the only built-in. Self-hosting via `scriptUrl` is supported.
+
+## output
+
+Where the scaffolded astro/ project lives. Default `./astro`. The user almost never changes this.
+
+## Common patterns
+
+### Single-source site
+
+```yaml
+schemaVersion: 1
+site:
+  name: My Docs
+  url: https://docs.example.com
+content:
+  sources:
+    - path: ./content
+```
+
+### Multi-source — markdown + OpenAPI
+
+```yaml
+schemaVersion: 1
+site:
+  name: Acme API
+  url: https://docs.acme.com
+  basePath: /docs
+content:
+  sources:
+    - path: ./content
+      from: dogsbay-md
+    - name: api
+      path: ./openapi/spec.yaml
+      from: openapi
+```
+
+URLs: `/docs/` (markdown), `/docs/api/...` (operations).
+
+### Multi-version OpenAPI
+
+```yaml
+content:
+  sources:
+    - path: ./content                      # evergreen prose
+      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"
+```
+
+### Cloudflare Workers deploy + agent readiness
+
+```yaml
+deploy:
+  target: cloudflare-workers
+
+agent:
+  llmsTxt: true
+  mdMirror: true
+  contentSignal:
+    aiTrain: "no"
+    aiInput: "yes"
+    search: "yes"
+```
+
+## Validation that fails the build
+
+- `site.url` includes a path AND `basePath` is set → throws "site.url must be host-only when basePath is set"
+- `site.basePath` contains `?`, `#`, whitespace, or `//` → throws
+- `content.sources` is empty → throws
+- `content.sources[].from` is unknown → throws (valid values: `auto`, `dogsbay-md`, `mkdocs`, `obsidian`, `starlight`, `mdx`, `openapi`)
+- `content.sources[]` has neither `path` nor `git` → throws
+- `git:` source has no `ref:` → throws
+- An entry has both `path:` and `git:` → throws (exactly-one-of)