feat: automated developer docs site (TypeDoc + Starlight + CI)

.github/workflows/docs.yml

@@ -0,0 +1,84 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "docs-site/**"
+      - "packages/**"
+      - "schemas/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build docs site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install docs-site dependencies
+        working-directory: docs-site
+        run: npm ci
+
+      # Drift gate: the committed data-driven pages (permission scopes,
+      # manifest reference, namespace map, …) are generated from
+      # schemas/ + packages/plugin-types/src/. This regenerates them
+      # in-memory, byte-compares against the committed files, and verifies
+      # the recorded input hash (docs-site/generated-docs.hash). Fails the
+      # build when the type declarations changed but the generated docs
+      # were not regenerated and committed.
+      - name: Drift gate — generated docs vs type declarations
+        working-directory: docs-site
+        run: npm run check-drift
+
+      # Full build: regenerate data pages, run TypeDoc (via
+      # starlight-typedoc) over packages/*/src, build the Starlight site,
+      # and emit dist/llms.txt + dist/llms-full.txt.
+      - name: Build site
+        working-directory: docs-site
+        run: npm run build
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site-dist
+          path: docs-site/dist
+          retention-days: 14
+
+  # ---------------------------------------------------------------------
+  # Deploy to Cloudflare Pages (docs.appos.space).
+  # Pages project: appos-docs. Requires repo secrets CLOUDFLARE_API_TOKEN
+  # (with "Cloudflare Pages: Edit") + CLOUDFLARE_ACCOUNT_ID.
+  # ---------------------------------------------------------------------
+  deploy:
+    name: Deploy to Cloudflare Pages
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-site-dist
+          path: docs-site/dist
+      - name: Deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy docs-site/dist --project-name=appos-docs

docs-site/.gitignore

@@ -0,0 +1,13 @@
+# build output
+dist/
+# generated types
+.astro/
+# dependencies
+node_modules/
+# TypeDoc output — regenerated on every build by starlight-typedoc
+src/content/docs/api/
+# environment variables
+.env
+.env.production
+# macOS
+.DS_Store

docs-site/README.md

@@ -0,0 +1,70 @@
+# AppOS Plugin SDK — docs site
+
+Automated developer documentation for the AppOS Plugin SDK, built with
+[Astro Starlight](https://starlight.astro.build) and
+[TypeDoc](https://typedoc.org) (via
+[starlight-typedoc](https://github.com/HiDeoo/starlight-typedoc)).
+
+Deployed target: **https://docs.appos.space** (Cloudflare Pages — see
+`.github/workflows/docs.yml`).
+
+## Quick start
+
+```bash
+cd docs-site
+npm install
+npm run dev        # generate data pages + local dev server (localhost:4321)
+```
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `npm run dev` | Regenerates data pages, then starts the dev server |
+| `npm run generate` | Regenerates the committed data-driven pages from `schemas/` + `packages/plugin-types/src/` |
+| `npm run check-drift` | Drift gate — fails if committed generated pages are stale vs the sources (used in CI) |
+| `npm run build` | Full production build: generate → astro build (incl. TypeDoc API reference) → `dist/llms.txt` + `dist/llms-full.txt` |
+| `npm run preview` | Serves the last `dist/` build |
+
+## How the pipeline fits together
+
+1. **API Reference** — three `starlight-typedoc` instances (one per SDK
+   package) run TypeDoc over `packages/*/src/index.ts` during `astro build`
+   and write markdown into `src/content/docs/api/` (**gitignored** —
+   regenerated every build; never edit or commit it).
+2. **Data-driven pages** — `scripts/generate-docs-data.mjs` extracts the
+   permission-scope catalog, manifest field reference, runtime limits,
+   namespace map, and extension-point/contribution tables from
+   `schemas/plugin-v1.json`, `schemas/constraints.json`,
+   `packages/plugin-types/src/permissions.ts`, and
+   `packages/plugin-types/src/core.ts`. Its outputs **are committed**; the
+   `check-drift` mode is the CI gate that keeps them in sync with the
+   sources (`generated-docs.hash` records the input hash).
+3. **llms.txt** — `scripts/generate-llms-txt.mjs` runs after `astro build`
+   and emits `dist/llms.txt` (index) and `dist/llms-full.txt` (full corpus:
+   every docs page + the SDK type sources + the manifest schemas) per the
+   [llms.txt convention](https://llmstxt.org).
+
+## Editing content
+
+- Hand-written pages live in `src/content/docs/` (everything except
+  `api/` and the pages carrying a `GENERATED FILE` banner).
+- Generated pages: edit the **sources** (`schemas/`,
+  `packages/plugin-types/src/`) or the generator script, then run
+  `npm run generate` and commit the result.
+
+## Deployment
+
+- The site deploys to **Cloudflare Pages** (project `appos-docs`, live at
+  <https://docs.appos.space>) via the `deploy` job in
+  `.github/workflows/docs.yml`, which runs on every push to `main` after
+  the build job succeeds. The required repo secrets
+  (`CLOUDFLARE_API_TOKEN` with "Cloudflare Pages: Edit" +
+  `CLOUDFLARE_ACCOUNT_ID`) are configured on the repository.
+
+## Known stubs / TODOs
+
+- **Extension-point payload schemas** and the **host event-topic catalog**
+  are owned by the AppOS host repo and are not machine-readable from this
+  repo yet. The corresponding pages carry explicit TODO callouts and will
+  grow generated tables once the host exports those catalogs.

docs-site/astro.config.mjs

@@ -0,0 +1,107 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import { createStarlightTypeDocPlugin } from "starlight-typedoc";
+
+// One starlight-typedoc instance per SDK package. Single-entry-point mode is
+// used deliberately: in multi-entry-point mode starlight-typedoc deletes the
+// per-module index pages, which leaves broken "Modules" links on the API
+// index. One instance per package gives each package a working index page.
+const [typesPlugin, typesSidebarGroup] = createStarlightTypeDocPlugin();
+const [buildersPlugin, buildersSidebarGroup] = createStarlightTypeDocPlugin();
+const [utilsPlugin, utilsSidebarGroup] = createStarlightTypeDocPlugin();
+
+/** Shared TypeDoc options for all three instances. */
+const sharedTypeDoc = {
+  readme: "none",
+  excludeInternal: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  sort: ["source-order"],
+};
+
+// https://astro.build/config
+export default defineConfig({
+  site: "https://docs.appos.space",
+  // Friendly alias for the API reference landing page.
+  redirects: {
+    "/api": "/api/plugin-types/readme",
+  },
+  integrations: [
+    starlight({
+      title: "AppOS Plugin SDK",
+      description:
+        "Developer documentation for the AppOS Plugin SDK — plugin-types, view-builders, plugin-utils, manifest schema, and permission scopes.",
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/appos/plugin-sdk",
+        },
+      ],
+      editLink: {
+        baseUrl: "https://github.com/appos/plugin-sdk/edit/main/docs-site/",
+      },
+      plugins: [
+        // API Reference generated from the SDK's TypeScript source of truth.
+        // Output lands in src/content/docs/api/ at build time (gitignored).
+        typesPlugin({
+          entryPoints: ["../packages/plugin-types/src/index.ts"],
+          tsconfig: "./tsconfig.typedoc.json",
+          output: "api/plugin-types",
+          sidebar: { label: "plugin-types", collapsed: true },
+          typeDoc: sharedTypeDoc,
+        }),
+        buildersPlugin({
+          entryPoints: ["../packages/view-builders/src/index.ts"],
+          tsconfig: "./tsconfig.typedoc.json",
+          output: "api/view-builders",
+          sidebar: { label: "view-builders", collapsed: true },
+          typeDoc: sharedTypeDoc,
+        }),
+        utilsPlugin({
+          entryPoints: ["../packages/plugin-utils/src/index.ts"],
+          tsconfig: "./tsconfig.typedoc.json",
+          output: "api/plugin-utils",
+          sidebar: { label: "plugin-utils", collapsed: true },
+          typeDoc: sharedTypeDoc,
+        }),
+      ],
+      sidebar: [
+        {
+          label: "Getting Started",
+          items: [
+            { slug: "getting-started/installation" },
+            { slug: "getting-started/first-plugin" },
+            { slug: "getting-started/packages" },
+          ],
+        },
+        {
+          label: "API Reference",
+          items: [
+            { slug: "reference/namespaces" },
+            typesSidebarGroup,
+            buildersSidebarGroup,
+            utilsSidebarGroup,
+          ],
+        },
+        {
+          label: "Manifest & Permissions",
+          items: [
+            { slug: "manifest" },
+            { slug: "manifest/reference" },
+            { slug: "manifest/permission-scopes" },
+            { slug: "manifest/limits" },
+          ],
+        },
+        {
+          label: "Extension Points",
+          items: [
+            { slug: "extension-points" },
+            { slug: "extension-points/event-topics" },
+          ],
+        },
+      ],
+    }),
+  ],
+});

docs-site/generated-docs.hash

@@ -0,0 +1,3 @@
+# SHA-256 over generator inputs (schemas/ + plugin-types sources).
+# Regenerate: cd docs-site && npm run generate
+42580dbca0f7e6bab74c7e9cadde427e71b467736239354769b90cedc20bfa07