dogsbay 0.2.0-beta.5 → 0.2.0-beta.6

package/dist/commands/agent.js

@@ -0,0 +1,216 @@
+/**
+ * `dogsbay agent install` — wire skill discovery for an LLM agent
+ * (Claude Code, Cursor, Copilot, etc.).
+ *
+ * Bundled platform skills live at `<cli-install-dir>/skills/platform/*.md`.
+ * This command:
+ *   1. Resolves the bundled platform skills directory.
+ *   2. Symlinks them into `<project>/.dogsbay/skills/platform/`.
+ *   3. Creates `.dogsbay/skills/site/` (empty + README) and
+ *      `.dogsbay/skills/plugins/` (empty placeholder).
+ *   4. For each requested --agent, writes the per-agent discovery
+ *      path (`.claude/skills/dogsbay/`, `.cursor/rules/dogsbay/`).
+ *
+ * Re-running is idempotent — symlinks are recreated; existing
+ * site/ files are never touched.
+ *
+ * See plans/dogsbay-agent-skills.md for the four-tier ownership
+ * model and how this fits.
+ */
+import { existsSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync, readlinkSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+const SUPPORTED_AGENTS = ["claude", "cursor"];
+const AGENT_TARGETS = {
+    claude: {
+        name: "claude",
+        path: ".claude/skills/dogsbay",
+        label: "Claude Code (.claude/skills/dogsbay/)",
+    },
+    cursor: {
+        name: "cursor",
+        path: ".cursor/rules/dogsbay",
+        label: "Cursor (.cursor/rules/dogsbay/)",
+    },
+};
+export async function agentInstall(cwd, options) {
+    const projectRoot = resolve(cwd || ".");
+    // Resolve the bundled platform-skills directory. We're running
+    // from <cli-install>/dist/commands/agent.js, so walk up to
+    // <cli-install>/skills/platform/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const platformSkills = resolve(here, "..", "..", "skills", "platform");
+    if (!existsSync(platformSkills)) {
+        console.error(pc.red(`Error: bundled platform skills not found at ${platformSkills}.`));
+        console.error(`       The dogsbay CLI install seems incomplete. Reinstall with`);
+        console.error(`       'npm install -g dogsbay@latest'.`);
+        process.exit(1);
+    }
+    // Pick the agents to install.
+    const agents = pickAgents(options);
+    if (agents.length === 0) {
+        printDetected(projectRoot);
+        return;
+    }
+    console.log(pc.cyan("→ Installing skill discovery"));
+    // 1. Always set up .dogsbay/skills/{platform,site,plugins}.
+    const dogsbayDir = join(projectRoot, ".dogsbay");
+    const skillsDir = join(dogsbayDir, "skills");
+    mkdirSync(skillsDir, { recursive: true });
+    const platformLink = join(skillsDir, "platform");
+    refreshSymlink(platformLink, platformSkills);
+    console.log(pc.green(`  ✓ ${relative(projectRoot, platformLink)} → bundled platform skills`));
+    const siteDir = join(skillsDir, "site");
+    if (!existsSync(siteDir)) {
+        mkdirSync(siteDir, { recursive: true });
+        writeFileSync(join(siteDir, "README.md"), `# Site skills
+
+This directory holds **site-specific** skills — your team's style
+guide, voice / tone, terminology, glossary, internal conventions.
+Anything an LLM should know that's specific to THIS site.
+
+Each skill is a single \`.md\` file with frontmatter:
+
+\`\`\`markdown
+---
+name: site:style-guide
+description: Our team's writing voice, terminology, and PR conventions.
+---
+
+# Style guide
+
+We use Oxford commas. Sentence-case headings. ...
+\`\`\`
+
+These skills are picked up automatically by any agent you've
+installed via \`dogsbay agent install --agent <name>\`.
+
+To override a platform skill (e.g. a different opinion on
+\`nav-file.md\`), put your version under \`overrides/<skill-name>.md\`.
+The agent loader checks overrides first.
+`);
+        console.log(pc.green(`  ✓ ${relative(projectRoot, siteDir)} created (empty + README)`));
+    }
+    else {
+        console.log(pc.gray(`  · ${relative(projectRoot, siteDir)} already exists (preserved)`));
+    }
+    const pluginsDir = join(skillsDir, "plugins");
+    if (!existsSync(pluginsDir)) {
+        mkdirSync(pluginsDir, { recursive: true });
+    }
+    // 2. Per-agent discovery symlinks.
+    for (const agent of agents) {
+        const target = AGENT_TARGETS[agent];
+        const agentLink = join(projectRoot, target.path);
+        mkdirSync(dirname(agentLink), { recursive: true });
+        refreshSymlink(agentLink, skillsDir);
+        console.log(pc.green(`  ✓ ${target.label} → .dogsbay/skills/`));
+    }
+    console.log("");
+    console.log(pc.cyan("Next:"));
+    console.log("  Open your editor — the agent should now see Dogsbay platform skills");
+    console.log("  on next prompt.");
+    console.log("");
+    console.log("  Add team-specific skills to .dogsbay/skills/site/.");
+    console.log("  Override a platform skill with .dogsbay/skills/site/overrides/<name>.md.");
+}
+/**
+ * Decide which agents to set up. Priority:
+ *   --all → every supported agent
+ *   --agent claude,cursor → exactly that list
+ *   neither → return [], caller prints detected agents and exits
+ */
+function pickAgents(options) {
+    if (options.all)
+        return [...SUPPORTED_AGENTS];
+    if (options.agent) {
+        const requested = options.agent.split(",").map((a) => a.trim().toLowerCase());
+        const valid = [];
+        for (const r of requested) {
+            if (SUPPORTED_AGENTS.includes(r)) {
+                valid.push(r);
+            }
+            else {
+                console.error(pc.yellow(`  warn: unknown agent "${r}" (supported: ${SUPPORTED_AGENTS.join(", ")})`));
+            }
+        }
+        return valid;
+    }
+    return [];
+}
+/**
+ * When called without --agent or --all, just probe the project
+ * for known agent-config dirs and suggest commands.
+ */
+function printDetected(projectRoot) {
+    const detected = [];
+    if (existsSync(join(projectRoot, ".claude"))) {
+        detected.push({ agent: "claude", signal: ".claude/" });
+    }
+    if (existsSync(join(projectRoot, ".cursor")) ||
+        existsSync(join(projectRoot, ".cursorrules"))) {
+        detected.push({ agent: "cursor", signal: ".cursor/ or .cursorrules" });
+    }
+    console.log(pc.cyan("Dogsbay agent install"));
+    console.log("");
+    console.log("Wires Dogsbay platform skills into the discovery path of an");
+    console.log("LLM agent so it picks them up on every prompt.");
+    console.log("");
+    if (detected.length > 0) {
+        console.log(pc.green("Detected in this project:"));
+        for (const d of detected) {
+            console.log(`  ${d.agent.padEnd(8)} (${d.signal})`);
+        }
+        console.log("");
+        console.log("Run:");
+        for (const d of detected) {
+            console.log(`  dogsbay agent install --agent ${d.agent}`);
+        }
+        console.log("  dogsbay agent install --all      # set up every detected agent");
+    }
+    else {
+        console.log(pc.yellow("No supported agent configs detected in this project."));
+        console.log("");
+        console.log("Run:");
+        console.log("  dogsbay agent install --agent claude");
+        console.log("  dogsbay agent install --agent cursor");
+        console.log("  dogsbay agent install --all");
+    }
+    console.log("");
+    console.log(`Supported agents: ${SUPPORTED_AGENTS.join(", ")}`);
+}
+/**
+ * Replace any existing entry at `linkPath` with a fresh symlink
+ * pointing at `target`. Idempotent: if the link already points at
+ * the right place, leaves it alone.
+ */
+function refreshSymlink(linkPath, target) {
+    if (existsSync(linkPath) || isBrokenSymlink(linkPath)) {
+        try {
+            const current = readlinkSync(linkPath);
+            const resolved = resolve(dirname(linkPath), current);
+            if (resolved === target)
+                return; // already correct
+        }
+        catch {
+            // not a symlink
+        }
+        try {
+            unlinkSync(linkPath);
+        }
+        catch {
+            // ignore
+        }
+    }
+    symlinkSync(target, linkPath, "dir");
+}
+function isBrokenSymlink(p) {
+    try {
+        readlinkSync(p);
+        return true; // it's a symlink, regardless of target validity
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { siteInit } from "./commands/site-init.js";
 import { siteBuild } from "./commands/site-build.js";
 import { siteCheck } from "./commands/site-check.js";
 import { siteDev, sitePreview } from "./commands/site-dev.js";
+import { agentInstall } from "./commands/agent.js";
 // Read version from the runtime package.json so `dogsbay --version`
 // never drifts from what's published. Walks one level up from
 // `dist/index.js` to `package.json` (works in both monorepo dev and
@@ -218,6 +219,16 @@ program
     .option("--concurrency <n>", "Maximum concurrent fetches (default: 3)", "3")
     .option("--rate-limit <ms>", "Minimum ms between request batches (default: 200)", "200")
     .action((url, options) => pull(url, options));
+// ── `dogsbay agent` — wire skill discovery for LLM agents ──────────────
+const agent = program
+    .command("agent")
+    .description("Wire Dogsbay platform skills into LLM-agent discovery paths");
+agent
+    .command("install")
+    .description("Install platform skills + per-agent discovery symlinks")
+    .option("--agent <names>", "Comma-separated list (e.g. claude,cursor)")
+    .option("--all", "Install for every supported agent")
+    .action((options) => agentInstall(undefined, options));
 program
     .command("export-techdocs")
     .description("Post-process Astro build output into Backstage TechDocs format")

package/package.json

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

package/skills/platform/agent-readiness.md

@@ -0,0 +1,262 @@
+---
+name: dogsbay:agent-readiness
+description: How Dogsbay sites expose content to LLM agents and search indexers — llms.txt, llms-full.txt, .md mirrors, Content-Signal HTTP headers, robots.txt. Use when configuring agent.* in dogsbay.config.yml or debugging agent consumption.
+---
+
+# Agent readiness
+
+Every Dogsbay site is built to be **agent-readable by default**.
+Three mechanisms work together so that any modern LLM, search
+engine, or AI-answer-engine can consume the docs as cleanly as
+a human reader:
+
+1. **llms.txt** at the root — the canonical agent index
+2. **`.md` mirror** for every page — the prose body without
+   chrome
+3. **Content-Signal HTTP headers** — IETF-track signal for "what
+   AI use is permitted"
+
+All three are emitted at `dogsbay site build` time. Toggleable
+via the `agent:` block in `dogsbay.config.yml`.
+
+## llms.txt
+
+The standard at [llmstxt.org](https://llmstxt.org/) — a single
+file at the site root that lists every page with title +
+description + URL. Two flavours:
+
+- `/llms.txt` — short index (title + description + URL per page,
+  grouped by section). The agent's "table of contents."
+- `/llms-full.txt` — full index with the markdown body of every
+  page concatenated. The agent's "everything in one paste."
+
+Per-section mini-indexes also emit (`/llms-${section}.txt` for
+each top-level nav group), so an agent can pull just the
+relevant slice without grabbing the whole site.
+
+Format example (`/llms.txt`):
+
+```
+# Acme Docs
+
+> Documentation for the Acme platform.
+
+## Getting started
+
+- [Installation](/docs/install): Install the CLI on macOS, Linux, or Windows.
+- [Quickstart](/docs/quickstart): Your first request in 60 seconds.
+
+## API reference
+
+- [List pets](/docs/api/pets/list-pets): Returns paginated list.
+- [Create a pet](/docs/api/pets/create-pet): Idempotent creation.
+```
+
+Toggleable:
+
+```yaml
+agent:
+  llmsTxt: true              # default true; set false to omit
+```
+
+## `.md` mirror
+
+Every emitted page has a sibling `.md` route that returns the
+markdown source (or a faithful prose rendering of it) with
+`Content-Type: text/markdown`.
+
+For a page at `/docs/api/pets/list-pets`, the mirror is at
+`/docs/api/pets/list-pets.md`. For `/docs/`, it's at `/docs.md`.
+
+Why two URLs? A human visiting `/docs/api/pets/list-pets` gets
+the rich HTML page with components, sidebar, search. An agent
+hitting `/docs/api/pets/list-pets.md` gets just the prose —
+faster to parse, no HTML noise, no dependency on a Cloudflare
+worker for content negotiation.
+
+### Discovery via `<link rel="alternate">`
+
+Every HTML page emits:
+
+```html
+<link rel="alternate" type="text/markdown" href="/docs/api/pets/list-pets.md">
+```
+
+Agents that follow `rel="alternate"` find the mirror without
+guessing at URL conventions. Anthropic's prompt-cache, Mintlify's
+agents, and several others do this.
+
+Toggleable:
+
+```yaml
+agent:
+  mdMirror: true             # default true
+```
+
+### Per-page opt-out
+
+Some pages don't have useful prose mirrors (e.g. landing pages
+that are mostly hero components). Opt out per-page:
+
+```yaml
+---
+title: Home
+mdMirror: false
+---
+```
+
+Or via the global `agent.mdMirror: false`.
+
+### Content negotiation (Cloudflare worker)
+
+Astro's static-mode output doesn't pass per-request headers to
+middleware, so the in-build middleware can't respond to
+`Accept: text/markdown` by serving the `.md` body. The current
+mitigation: the explicit `.md` URL is always available, and
+`<link rel="alternate">` exposes it. A Cloudflare worker that
+does proper content negotiation at the edge is planned (see
+`plans/cloudflare-deploy-content-negotiation.md`).
+
+## Content-Signal HTTP headers
+
+Per the IETF Content-Signal draft, sites can declare AI-use
+permissions via HTTP headers:
+
+```
+Content-Signal: aiTrain=no, aiInput=yes, search=yes
+```
+
+Three keys:
+
+| Key | Values | Meaning |
+|---|---|---|
+| `aiTrain` | `yes` / `no` | May this content be used for AI model training? |
+| `aiInput` | `yes` / `no` | May this content be used as input to a live AI session (RAG, prompt context)? |
+| `search` | `yes` / `no` | May this content be indexed by search engines? |
+
+Configure via `agent.contentSignal`:
+
+```yaml
+agent:
+  contentSignal:
+    aiTrain: "no"            # don't use my docs to train models
+    aiInput: "yes"           # but DO use them as live context (e.g. for users in Claude / Cursor)
+    search: "yes"            # standard search indexing OK
+```
+
+Emitted in two places:
+
+- `public/_headers` — Cloudflare Pages / Vercel / Netlify pick
+  this up at the edge automatically
+- `<meta>` tags in HTML head — for hosts that don't read
+  `_headers`
+
+## robots.txt
+
+Auto-emitted at `public/robots.txt` based on `noindex` settings
++ Content-Signal `search` value. Disallows crawlers when
+`search: "no"`; otherwise allows everything.
+
+For per-page `noindex`, the `robots` meta tag handles it (see
+`dogsbay:frontmatter-fields`).
+
+## Per-page LLM action UI
+
+Beyond the data side, Dogsbay can render an action cluster
+("Copy as markdown", "Open in Claude", "Open in ChatGPT") on
+each page:
+
+```yaml
+agent:
+  llmsTxt: true
+  mdMirror: true
+
+llmActions:
+  enabled: true
+  providers: [claude, chatgpt, perplexity, gemini]   # render order
+  placement: header                                   # header | inline | both
+  copyButton: true
+  promptTemplate: "Read this docs page: {url}"
+  footerLink: true
+```
+
+`{url}` resolves to the absolute `.md` mirror URL. The user
+clicks "Open in Claude" → goes to `claude.ai/new?q=...` with a
+prepopulated prompt that pulls the markdown into Claude's
+context.
+
+Per-page opt-out via `llmActions: false` in frontmatter.
+
+## What agents see
+
+When an LLM is given the URL of a Dogsbay site:
+
+1. It fetches `/llms.txt` (table of contents)
+2. Picks pages relevant to the question
+3. Fetches each as `/{path}.md` (full prose)
+4. Reads `Content-Signal` to know if it's allowed to use the
+   content as context (typically yes if `aiInput=yes`)
+
+That's a self-contained agent-consumption loop with no special
+configuration on the agent's side.
+
+## Common patterns
+
+### Public docs, no AI training, allow live context
+
+```yaml
+agent:
+  llmsTxt: true
+  mdMirror: true
+  contentSignal:
+    aiTrain: "no"
+    aiInput: "yes"
+    search: "yes"
+```
+
+The default for most teams. Their docs help users in AI sessions
+but don't end up in training data.
+
+### Internal docs (no public agent access)
+
+```yaml
+agent:
+  llmsTxt: false             # don't advertise to crawlers
+  mdMirror: true             # but keep the dev-side .md surface
+  contentSignal:
+    aiTrain: "no"
+    aiInput: "no"
+    search: "no"
+```
+
+Plus host-side auth (Cloudflare Access, Vercel password, etc.)
+to gate the site itself.
+
+### Marketing-site mode (everything open)
+
+```yaml
+agent:
+  llmsTxt: true
+  mdMirror: true
+  contentSignal:
+    aiTrain: "yes"           # put us in the training data; we want the visibility
+    aiInput: "yes"
+    search: "yes"
+```
+
+## Common mistakes
+
+- ❌ Setting `agent.mdMirror: false` and expecting llms.txt to
+  still link to .md files — the index emits whatever URLs the
+  build produces. If mirrors aren't built, the index can't link
+  to them.
+- ❌ Trusting `Accept: text/markdown` content negotiation today —
+  static-mode middleware doesn't see request headers. Use the
+  explicit `.md` URL.
+- ❌ `aiTrain: "no"` + a public-internet-readable site —
+  Content-Signal is **declarative**, not enforceable. Crawlers
+  can ignore it. For real protection, gate access at the
+  network level.
+- ❌ Mistyping the Content-Signal values (`"true"` instead of
+  `"yes"`) — the loader doesn't normalise; the header emits
+  literally what you wrote.