feat(docs): add apps/docs documentation site

[amondnet]

Summary

Add apps/docs/ — the ASK documentation site built on the docs-please Nuxt layer (Nuxt 4 + Nuxt Content v3 + shadcn-vue + Tailwind 4), deployed to Cloudflare Pages with D1.

This is a single logical change: a new docs site plus the two supporting workarounds it required.

What Changed

New: apps/docs/

Full scaffold for the ASK docs site:

• package.json — workspace package wired into the monorepo
• nuxt.config.ts — extends docs-please, configures Cloudflare Pages preset, D1 binding
• app/app.config.ts — site title and navigation config
• content/index.md — landing page
• content/docs/1.getting-started/ — introduction and installation docs
• eslint.config.ts, tsconfig.json — tooling config
• wrangler.jsonc — Cloudflare Workers config with D1 binding (ask-docs-db, id 13fc057c-92f7-4879-9fb1-e9a7a457fd57)
• README.md

New: bunfig.toml — hoisted linker workaround

Bun 1.3.2+ defaults to the isolated linker. Nitro's Rollup pipeline crashes when a dependency ships raw .ts/.vue files from node_modules/ because the isolated linker places each package in its own virtual store, breaking Rollup's module resolution. Forcing linker = "hoisted" restores the flat layout Nitro expects.

See nuxt-content/docus#1279 for the upstream report on this class of issue.

New: patches/docs-please@0.2.6.patch — Vue SFC compiler workaround

Two SFCs in docs-please extend NuxtLinkProps / PrimitiveProps via TypeScript extends type syntax. The Vue SFC compiler cannot resolve auto-imported types from .vue files inside node_modules/, so it emits a fatal build error. The patch injects /* @vue-ignore */ before those extends clauses to suppress the unresolvable type check.

The docs-please repo itself uses workspace:* for its own packages, so its authors do not hit this in development. A follow-up PR to pleaseai/docs will let us drop this patch once the fix lands upstream.

Modified files

• package.json — adds patchedDependencies["docs-please@0.2.6"]
• bun.lock — regenerated under hoisted linker
• ARCHITECTURE.md — new apps/docs/ module section
• CLAUDE.md — apps/docs/ commands + gotchas for bunfig.toml and the docs-please patch

Verification

• bun run build — 4/4 packages succeed (cli, schema, registry, docs)
• bun run lint — 5/5 succeed
• apps/docs builds with --preset=cloudflare_pages (default) and the plain Node preset (build:node)

Follow-up Items

• Create Cloudflare Pages project, link repo, set build command (cd apps/docs && bun run build), output dir (apps/docs/.output/public), and bind the D1 database ask-docs-db
• Open upstream PR to pleaseai/docs with the /* @vue-ignore */ fix so we can eventually drop patches/docs-please@0.2.6.patch
• Add actual documentation content pages

---

Summary by cubic

Adds apps/docs — the ASK documentation site built on docs-please (Nuxt 4 + @nuxt/content v3), deployable to Cloudflare Pages with D1. Also adds a hoisted Bun linker and a temporary docs-please@0.2.6 patch to keep builds green.

• New Features

  • New apps/docs/ scaffold extending docs-please with site config and starter content (landing + Getting Started).
  • Content DB auto-select: D1 binding DB on Cloudflare builds; native sqlite locally.
  • Cloudflare config: wrangler.jsonc with D1 database ask-docs-db (id 13fc057c-92f7-4879-9fb1-e9a7a457fd57).
  • Repo docs updated for the new app and commands.

• Migration

  • Create a Cloudflare Pages project, bind D1, set build bun run --cwd apps/docs build, output apps/docs/dist.
  • Root bunfig.toml forces linker = "hoisted" (required for Nuxt/Content builds).
  • Temporary workaround: patches/docs-please@0.2.6.patch; remove after the upstream fix.

^{Written for commit 028a5c6. Summary will update on new commits.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	028a5c6
Status:	✅  Deploy successful!
Preview URL:	https://29034748.ask-registry.pages.dev
Branch Preview URL:	https://worktree-corona-cholla.ask-registry.pages.dev

View logs

[cubic-dev-ai]

2 issues found across 19 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/docs/.wrangler/deploy/config.json">

<violation number="1" location="apps/docs/.wrangler/deploy/config.json:1">
P2: Remove this file and add `.wrangler/` to `.gitignore`. The `config.json` inside `.wrangler/deploy/` is auto-generated by `wrangler deploy` / `wrangler pages deploy` and should not be committed to version control. The repo's source-of-truth for Wrangler config is already `apps/docs/wrangler.jsonc`.</violation>
</file>

<file name="apps/docs/content/docs/1.getting-started/.navigation.yml">

<violation number="1" location="apps/docs/content/docs/1.getting-started/.navigation.yml:2">
P2: The `icon` field must be nested under a `navigation:` key. Without this, Nuxt Content will not apply the icon to the directory navigation item returned by `queryCollectionNavigation()`.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Workspace as Monorepo Workspace
    participant Bun as Bun Installer
    participant DocsApp as apps/docs (Nuxt App)
    participant DocsPlease as docs-please Nuxt Layer
    participant NuxtContent as @nuxt/content v3
    participant D1 as Cloudflare D1
    participant SQLite as Native SQLite

    Note over Dev,D1: Build-time Architecture

    Dev->>Bun: bun install
    Bun->>Bun: Read bunfig.toml (linker = "hoisted")
    Bun->>Workspace: Install deps with flat node_modules
    Workspace->>DocsApp: Patched docs-please@0.2.6 (Vue SFC extends fix)

    Note over DocsApp,D1: Build Phase

    Dev->>DocsApp: nuxt build --preset=cloudflare_pages
    DocsApp->>DocsPlease: Extend Nuxt layer (chrome, components)
    DocsApp->>DocsPlease: Provide app.config.ts (site metadata)
    DocsApp->>NuxtContent: Initialize content database

    alt Cloudflare Build
        NuxtContent->>D1: Use type: "d1", bindingName: "DB"
        D1-->>NuxtContent: D1 binding configured
    else Local Build
        NuxtContent->>SQLite: Use type: "sqlite", filename: .data/content/contents.sqlite
        SQLite-->>NuxtContent: Native sqlite connector
    end

    DocsPlease->>DocsApp: Render chrome (header, footer, sidebar, TOC)
    NuxtContent->>DocsApp: Parse content/ .md files
    DocsApp->>DocsApp: Generate static pages

    Note over Dev,D1: Runtime (Cloudflare Pages Worker)

    Client->>D1: GET /docs/getting-started/introduction
    D1->>NuxtContent: Query content from D1
    NuxtContent-->>D1: Return MDC content
    D1-->>Client: Rendered HTML page

    Note over Dev,D1: Local Development

    Client->>SQLite: GET /docs/getting-started/introduction
    SQLite->>NuxtContent: Query content from .data/content/contents.sqlite
    NuxtContent-->>SQLite: Return MDC content
    SQLite-->>Client: Rendered HTML page

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Remove this file and add .wrangler/ to .gitignore. The config.json inside .wrangler/deploy/ is auto-generated by wrangler deploy / wrangler pages deploy and should not be committed to version control. The repo's source-of-truth for Wrangler config is already apps/docs/wrangler.jsonc.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/.wrangler/deploy/config.json, line 1:

<comment>Remove this file and add `.wrangler/` to `.gitignore`. The `config.json` inside `.wrangler/deploy/` is auto-generated by `wrangler deploy` / `wrangler pages deploy` and should not be committed to version control. The repo's source-of-truth for Wrangler config is already `apps/docs/wrangler.jsonc`.</comment>

<file context>
@@ -0,0 +1 @@
+{ "configPath": "../../dist/_worker.js/wrangler.json" }
</file context>

[cubic-dev-ai]

P2: The icon field must be nested under a navigation: key. Without this, Nuxt Content will not apply the icon to the directory navigation item returned by queryCollectionNavigation().

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/content/docs/1.getting-started/.navigation.yml, line 2:

<comment>The `icon` field must be nested under a `navigation:` key. Without this, Nuxt Content will not apply the icon to the directory navigation item returned by `queryCollectionNavigation()`.</comment>

<file context>
@@ -0,0 +1,2 @@
+title: Getting Started
+icon: i-lucide-rocket
</file context>