Astroc4 update

.agents/skills/docs-aggregation-rules/SKILL.md

@@ -112,8 +112,10 @@ The wikis of several product repositories are mirrored into `docs/wiki`, so the
 - A page's slug is its path from the docs root (ADR 0011): a flat corpus keeps the single-segment
   slug (`Getting-Started.md` → `getting-started`, served at `/docs/<id>/getting-started/`), and a
   topic folder stays a path segment (`schemas/Custom-Rules.md` →
-  `/docs/<id>/schemas/custom-rules/`). A `docsPage` in a use case must use a slug that still resolves
-  in the **default** channel, which is why it stays a single segment.
+  `/docs/<id>/schemas/custom-rules/`). A nested `README.md` is the folder's index, so
+  `guide/README.md` publishes at `/docs/<id>/guide/` (the root `README.md` stays the landing page).
+  A `docsPage` in a use case must use a slug that still resolves in the **default** channel, which
+  is why it stays a single segment.
 
 ## Injected front matter (per page)
 
@@ -134,8 +136,9 @@ H1s are demoted to keep one title per document.
 - The sidebar mirrors the published tree (ADR 0011): every folder in a slug becomes a nested
   `starlight` group labelled with the folder's name spelled out (`schemas` → `Schemas`), placed where
   its first page appears and holding all of that folder's pages in channel order. Nesting is
-  recursive, a folder's `index.md` links the folder's own address, and a flat corpus renders exactly
-  the flat list it always did (`buildChannelItems` in `src/lib/docs/sidebar.ts`).
+  recursive, a folder's `index.md` or nested `README.md` links the folder's own address, and a flat
+  corpus renders exactly the flat list it always did (`buildChannelItems` in
+  `src/lib/docs/sidebar.ts`).
 - Each aggregated page also names the folders above it, above the title, in the same spelling as the
   sidebar (`PageTitle.astro` + `docSectionTrail`).
 - Archived projects are excluded from the docs portal, the sidebar topics, and per-project LLM

docs/decisions/0011-documentation-folders.md

@@ -95,7 +95,8 @@ address disagrees with. So the display follows the slug:
   appears and absorbs its later pages, so a folder is listed once and the sync's
   reading order (`docs.order` / `_Sidebar.md`) survives.
 - Nesting is recursive, because a slug is a path: `guides/getting-started/install`
-  is a group inside a group. A folder's index file (`schemas/index.md`) is
+  is a group inside a group. A folder's index file (`schemas/index.md`, or a
+  nested `README.md` — the file GitHub renders as the folder's landing page) is
   published at the folder's own address, so its sidebar entry links the folder.
 - A flat corpus has no folder in any slug, so it produces no group and no code
   path changes for the projects that never nested.

src/astro.config.ts

@@ -8,7 +8,6 @@ import starlight from '@astrojs/starlight';
 import astroc4 from '@purview-dev/astroc4';
 import tailwindcss from '@tailwindcss/vite';
 import { defineConfig } from 'astro/config';
-import { fileURLToPath } from 'node:url';
 import starlightLinksValidator from 'starlight-links-validator';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import starlightSidebarTopics from 'starlight-sidebar-topics';
@@ -196,6 +195,10 @@ export default defineConfig({
       plugins: [
         // The live astroc4 demo (src/pages/examples/astroc4.mdx) is the site
         // dogfooding the plugin it catalogues: real fences and real views.
+        //
+        // This is the Starlight entry point, so it belongs in `plugins` — the
+        // plain-Astro `@purview-dev/astroc4/integration` shape in `integrations`
+        // would render diagrams but skip the translated UI and the highlighting.
         astroc4({
           vitePlugin: { workspace: 'src/likec4' },
           highlighting: { ref: 'v1.60.0' },
@@ -285,21 +288,14 @@ export default defineConfig({
   ],
   vite: {
     plugins: [tailwindcss()],
-    resolve: {
-      alias: {
-        // LikeC4's React bundle imports React's CommonJS compiler runtime with
-        // a named `c` export. Vite 8's Rolldown optimiser does not expose that
-        // export from the development build, so the islands fail to hydrate.
-        // The bridge is the same `useMemoCache` call in ESM form.
-        'react/compiler-runtime': fileURLToPath(
-          new URL('./config/react-compiler-runtime.ts', import.meta.url),
-        ),
-      },
-    },
     optimizeDeps: {
       // LikeC4 is a dependency added at build time; listing its React entry
       // and the React runtime means a cold dev start pre-bundles them instead
       // of serving them raw and producing "504 Outdated Optimize Dep".
+      //
+      // `react/compiler-runtime` is deliberately absent: astroc4 1.0.0-prerelease.5
+      // adds it to this list itself (only when the site has not), which is what
+      // keeps the LikeC4 islands hydrating in `astro dev`.
       include: [
         'react',
         'react-dom',

src/config/satteri-mermaid.ts

@@ -7,11 +7,14 @@ import { defineMdastPlugin } from 'satteri';
  * block is highlighted, so the browser-side Mermaid script can draw them.
  *
  * This is the Sätteri equivalent of the remark plugin the site used before
- * Astro 7.4 (and before astroc4 required the Sätteri pipeline): a Sätteri
- * plugin declares one visitor per node type rather than a single tree walker,
- * so only `code` nodes are visited. Replacing the node with an `html` node is
+ * Astro 7.4 made Sätteri the default Markdown processor: a Sätteri plugin
+ * declares one visitor per node type rather than a single tree walker, so only
+ * `code` nodes are visited. Replacing the node with an `html` node is
  * deliberate — the output is exactly the element the Mermaid runtime expects,
  * and it does not depend on the converter honouring `data.hName`.
+ *
+ * `markdown.processor` is the site's own; astroc4 appends its ```likec4 fence
+ * transform to whatever processor the site registered, so the two coexist.
  */
 function escapeHtml(value: string): string {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');

src/fixtures/github/releases/astroc4.json

@@ -1,4 +1,47 @@
 [
+  {
+    "url": "https://api.github.com/repos/purview-dev/astroc4/releases/436363619",
+    "assets_url": "https://api.github.com/repos/purview-dev/astroc4/releases/436363619/assets",
+    "upload_url": "https://uploads.github.com/repos/purview-dev/astroc4/releases/436363619/assets{?name,label}",
+    "html_url": "https://github.com/purview-dev/astroc4/releases/tag/v1.0.0-prerelease.5",
+    "id": 436363619,
+    "author": {
+      "login": "github-actions[bot]",
+      "id": 41898282,
+      "node_id": "MDM6Qm90NDE4OTgyODI=",
+      "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4",
+      "gravatar_id": "",
+      "url": "https://api.github.com/users/github-actions%5Bbot%5D",
+      "html_url": "https://github.com/apps/github-actions",
+      "followers_url": "https://api.github.com/users/github-actions%5Bbot%5D/followers",
+      "following_url": "https://api.github.com/users/github-actions%5Bbot%5D/following{/other_user}",
+      "gists_url": "https://api.github.com/users/github-actions%5Bbot%5D/gists{/gist_id}",
+      "starred_url": "https://api.github.com/users/github-actions%5Bbot%5D/starred{/owner}{/repo}",
+      "subscriptions_url": "https://api.github.com/users/github-actions%5Bbot%5D/subscriptions",
+      "organizations_url": "https://api.github.com/users/github-actions%5Bbot%5D/orgs",
+      "repos_url": "https://api.github.com/users/github-actions%5Bbot%5D/repos",
+      "events_url": "https://api.github.com/users/github-actions%5Bbot%5D/events{/privacy}",
+      "received_events_url": "https://api.github.com/users/github-actions%5Bbot%5D/received_events",
+      "type": "Bot",
+      "user_view_type": "public",
+      "site_admin": false
+    },
+    "node_id": "RE_kwDOVhwi5M4aAmFj",
+    "tag_name": "v1.0.0-prerelease.5",
+    "target_commitish": "main",
+    "name": "v1.0.0-prerelease.5",
+    "draft": false,
+    "immutable": false,
+    "prerelease": true,
+    "created_at": "2026-11-06T10:25:03Z",
+    "updated_at": "2026-11-06T10:26:09Z",
+    "published_at": "2026-11-06T10:26:09Z",
+    "assets": [],
+    "tarball_url": "https://api.github.com/repos/purview-dev/astroc4/tarball/v1.0.0-prerelease.5",
+    "zipball_url": "https://api.github.com/repos/purview-dev/astroc4/zipball/v1.0.0-prerelease.5",
+    "body": "## What's Changed\n* docs: record the dist-tag and publish-order follow-ups by @kieronlanning in https://github.com/purview-dev/astroc4/pull/7\n* ci: publish without an approval prompt by @kieronlanning in https://github.com/purview-dev/astroc4/pull/8\n* docs: fold the wiki into guide/ and contributing/, and drop mkdocs by @kieronlanning in https://github.com/purview-dev/astroc4/pull/9\n* docs: describe the removal without naming the tools by @kieronlanning in https://github.com/purview-dev/astroc4/pull/10\n* docs: point the skills and the guide at the LikeC4 DSL skill by @kieronlanning in https://github.com/purview-dev/astroc4/pull/11\n* docs: describe the grammar cache without a build path by @kieronlanning in https://github.com/purview-dev/astroc4/pull/12\n* docs: install LikeC4's skill from likec4.dev, not its GitHub mirror by @kieronlanning in https://github.com/purview-dev/astroc4/pull/13\n* docs: removed old roadmap by @kieronlanning in https://github.com/purview-dev/astroc4/pull/14\n* docs: added version badge to readme.md by @kieronlanning in https://github.com/purview-dev/astroc4/pull/15\n* fix: npm version badge by @kieronlanning in https://github.com/purview-dev/astroc4/pull/16\n* feat: plain Astro support, and the smoke suite run against the packed package by @kieronlanning in https://github.com/purview-dev/astroc4/pull/17\n\n\n**Full Changelog**: https://github.com/purview-dev/astroc4/compare/v1.0.0-prerelease.4...v1.0.0-prerelease.5",
+    "mentions_count": 1
+  },
   {
     "url": "https://api.github.com/repos/purview-dev/astroc4/releases/433624030",
     "assets_url": "https://api.github.com/repos/purview-dev/astroc4/releases/433624030/assets",

src/fixtures/github/repos/astroc4.json

@@ -66,14 +66,14 @@
   "releases_url": "https://api.github.com/repos/purview-dev/astroc4/releases{/id}",
   "deployments_url": "https://api.github.com/repos/purview-dev/astroc4/deployments",
   "created_at": "2026-11-03T18:31:42Z",
-  "updated_at": "2026-11-04T08:50:48Z",
-  "pushed_at": "2026-11-04T08:50:45Z",
+  "updated_at": "2026-11-06T13:22:37Z",
+  "pushed_at": "2026-11-06T13:22:33Z",
   "git_url": "git://github.com/purview-dev/astroc4.git",
   "ssh_url": "git@github.com:purview-dev/astroc4.git",
   "clone_url": "https://github.com/purview-dev/astroc4.git",
   "svn_url": "https://github.com/purview-dev/astroc4",
   "homepage": "https://purview.dev/projects/astroc4/",
-  "size": 336,
+  "size": 424,
   "stargazers_count": 1,
   "watchers_count": 1,
   "language": "TypeScript",

src/fixtures/npm/purview-dev-astroc4.json

@@ -5,13 +5,14 @@
     "1.0.0-prerelease.1",
     "1.0.0-prerelease.2",
     "1.0.0-prerelease.3",
-    "1.0.0-prerelease.4"
+    "1.0.0-prerelease.4",
+    "1.0.0-prerelease.5"
   ],
   "distTags": {
-    "latest": "1.0.0-prerelease.4",
-    "prerelease": "1.0.0-prerelease.4"
+    "latest": "1.0.0-prerelease.5",
+    "prerelease": "1.0.0-prerelease.5"
   },
-  "publishedAt": "2026-11-04T07:35:57.303Z",
-  "weeklyDownloads": null,
+  "publishedAt": "2026-11-06T10:26:34.324Z",
+  "weeklyDownloads": 803,
   "deprecated": false
 }

src/fixtures/releases/index.json

@@ -1,6 +1,6 @@
 {
   "schema": 3,
-  "retrievedAt": "2026-11-04T09:09:11.026Z",
+  "retrievedAt": "2026-11-06T13:25:51.228Z",
   "repos": {
     "purview-dev/telemetry-sourcegenerator": {
       "name": "telemetry-sourcegenerator",
@@ -350,7 +350,7 @@
       "stargazersCount": 1,
       "openIssuesCount": 0,
       "defaultBranch": "main",
-      "updatedAt": "2026-11-04T08:50:48Z",
+      "updatedAt": "2026-11-06T13:22:37Z",
       "hasDiscussions": false
     },
     "purview-dev/dotnet-logging-source-generators": {
@@ -2893,6 +2893,15 @@
       }
     ],
     "purview-dev/astroc4": [
+      {
+        "tagName": "v1.0.0-prerelease.5",
+        "name": "v1.0.0-prerelease.5",
+        "body": "## What's Changed\n* docs: record the dist-tag and publish-order follow-ups by @kieronlanning in https://github.com/purview-dev/astroc4/pull/7\n* ci: publish without an approval prompt by @kieronlanning in https://github.com/purview-dev/astroc4/pull/8\n* docs: fold the wiki into guide/ and contributing/, and drop mkdocs by @kieronlanning in https://github.com/purview-dev/astroc4/pull/9\n* docs: describe the removal without naming the tools by @kieronlanning in https://github.com/purview-dev/astroc4/pull/10\n* docs: point the skills and the guide at the LikeC4 DSL skill by @kieronlanning in https://github.com/purview-dev/astroc4/pull/11\n* docs: describe the grammar cache without a build path by @kieronlanning in https://github.com/purview-dev/astroc4/pull/12\n* docs: install LikeC4's skill from likec4.dev, not its GitHub mirror by @kieronlanning in https://github.com/purview-dev/astroc4/pull/13\n* docs: removed old roadmap by @kieronlanning in https://github.com/purview-dev/astroc4/pull/14\n* docs: added version badge to readme.md by @kieronlanning in https://github.com/purview-dev/astroc4/pull/15\n* fix: npm version badge by @kieronlanning in https://github.com/purview-dev/astroc4/pull/16\n* feat: plain Astro support, and the smoke suite run against the packed package by @kieronlanning in https://github.com/purview-dev/astroc4/pull/17\n\n\n**Full Changelog**: https://github.com/purview-dev/astroc4/compare/v1.0.0-prerelease.4...v1.0.0-prerelease.5",
+        "prerelease": true,
+        "draft": false,
+        "publishedAt": "2026-11-06T10:26:09Z",
+        "htmlUrl": "https://github.com/purview-dev/astroc4/releases/tag/v1.0.0-prerelease.5"
+      },
       {
         "tagName": "v1.0.0-prerelease.4",
         "name": "v1.0.0-prerelease.4",
@@ -4756,14 +4765,15 @@
         "1.0.0-prerelease.1",
         "1.0.0-prerelease.2",
         "1.0.0-prerelease.3",
-        "1.0.0-prerelease.4"
+        "1.0.0-prerelease.4",
+        "1.0.0-prerelease.5"
       ],
       "distTags": {
-        "latest": "1.0.0-prerelease.4",
-        "prerelease": "1.0.0-prerelease.4"
+        "latest": "1.0.0-prerelease.5",
+        "prerelease": "1.0.0-prerelease.5"
       },
-      "publishedAt": "2026-11-04T07:35:57.303Z",
-      "weeklyDownloads": null,
+      "publishedAt": "2026-11-06T10:26:34.324Z",
+      "weeklyDownloads": 803,
       "deprecated": false
     }
   }

src/package.json

@@ -36,7 +36,7 @@
     "@astrojs/react": "7.1.2",
     "@likec4/core": "1.60.0",
     "@pagefind/default-ui": "1.5.2",
-    "@purview-dev/astroc4": "1.0.0-prerelease.4",
+    "@purview-dev/astroc4": "1.0.0-prerelease.5",
     "likec4": "1.60.0",
     "preact": "10.29.8",
     "react": "19.3.1",