feat(astroc4): added astroc4 site _and_ example page!

.agents/skills/add-catalogue-project/SKILL.md

@@ -49,6 +49,8 @@ gh api "repos/<owner>/<repo>/releases?per_page=10" --jq '.[] | {tag_name, prerel
 
 # Packages: confirm each id exists and see its channel (replace the id)
 curl.exe -s "https://api.nuget.org/v3-flatcontainer/<packageid>/index.json"
+# npm packages (skip the NuGet index): the registry document carries versions + dist-tags
+curl.exe -s "https://registry.npmjs.org/<scope>%2F<name>"
 ```
 
 Record, as evidence for the record you are about to write: where the docs live, the exact markdown
@@ -61,7 +63,7 @@ description/topics.
   `source-generation`, `aspire`, `build-tooling`, `developer-tooling`.
 - `status`:
   - `archived` when the repository is archived (GitHub `archived: true`).
-  - `preview` when there is no stable NuGet release.
+  - `preview` when there is no stable release on the registry the project publishes to.
   - `stable` only when a stable (non-prerelease) release exists and is recommended for use.
 - `experimental: true` (a flag, not a status value) when the tooling is explicitly an experiment:
   no compatibility promise, no production support guarantee. Keep `status` as the honest release
@@ -98,9 +100,10 @@ Add the entry as `src/src/data/projects/<id>.yml` (see `project-manifest-referen
       rootPage: Getting-Started.md   # optional; see docs-aggregation-rules
       exclude: [ _Sidebar.md, index.md ]
     targetFrameworks: [ net8.0, net9.0 ]
-    install: nuget | msbuild-sdk | dotnet-tool   # only when not a plain NuGet package
+    install: nuget | msbuild-sdk | dotnet-tool   # NuGet packages only; omit for npm
     packages:
-      - id: <NuGet.Package.Id>
+      - id: <Package.Id.Or.Npm.Name>
+        registry: nuget | npm                   # optional; defaults to nuget (ADR 0012)
         description: <what this package is for>
         primary: true
     related: [ <known-project-id> ]
@@ -153,7 +156,9 @@ Confirm each surface actually lights up:
 4. `/projects/<id>/llms.txt` and `/projects/<id>/llms-full.txt` are emitted and linked from
    `/llms.txt`.
 5. `/use-cases/` lists the new use cases under the right audiences.
-6. `/releases/` shows GitHub/NuGet versions for the declared packages.
+6. `/releases/` shows GitHub and registry versions (NuGet or npm) for the declared packages.
+7. If a live example page exists at `src/src/pages/examples/<id>.mdx`, `/projects/<id>/` links it as
+   **Live example** (the page is discovered, not declared).
 
 ## Step 6 — report
 

.agents/skills/add-project-intake/SKILL.md

@@ -32,7 +32,7 @@ Never ask a question whose answer is in the repository. Fetch it, show the evide
 | --- | --- |
 | Owner, description, topics, archived, default branch, discussions, homepage | `gh api repos/<owner>/<repo>` |
 | Docs layout and the landing-page candidates | `gh api "repos/<owner>/<repo>/git/trees/main?recursive=1"` |
-| Package ids and the release channel | `curl https://api.nuget.org/v3-flatcontainer/<id>/index.json` |
+| Package ids and the release channel | `curl https://api.nuget.org/v3-flatcontainer/<id>/index.json`, or the npm registry document for `registry: npm` |
 | `install` kind, target frameworks, the reader-facing package set | the nuspec / `.config/purview-build.json` |
 
 The commands and the evidence to record are listed in `add-catalogue-project` (Step 1). Recon first
@@ -57,7 +57,7 @@ decides. "Required" means stop and ask; "confirm" means propose a value and let
 | # | Question | Decides | Default / rule |
 | --- | --- | --- | --- |
 | 4 | Which `category`? **Required when the project straddles two** (for example architecture tests: `developer-tooling` — a tool you add to a repository — or `validation` — the input/data-validation bucket, currently ZodSharp). | `category` | Exactly one of the seven vocabulary values; never a new label. |
-| 5 | `status` follows the release channel: an archived repository is `archived`, prerelease-only tooling is `preview`, a project with a stable (non-prerelease) NuGet version is `stable`. **Ask only when the channel and the intent disagree** — a stable package for a project that is not yet recommended (keep `preview` and record why), or a package that is not published yet. | `status` | Derived from GitHub `archived` + the NuGet index; never "stable" without a stable version. |
+| 5 | `status` follows the release channel: an archived repository is `archived`, prerelease-only tooling is `preview`, a project with a stable (non-prerelease) version on its registry is `stable`. **Ask only when the channel and the intent disagree** — a stable package for a project that is not yet recommended (keep `preview` and record why), or a package that is not published yet. | `status` | Derived from GitHub `archived` + the package registry; never "stable" without a stable version. |
 | 6 | Is this an **experiment** — the API, defaults and packaging may change between prereleases and there is no production support guarantee? **Ask; it is orthogonal to `status`** and invalid on an archived project. | `experimental` | `false`. `true` adds a warning badge to the catalogue and every aggregated docs page (ADR 0004). |
 
 ### Documentation (recon decides; ask only on a failure mode)
@@ -74,7 +74,7 @@ decides. "Required" means stop and ask; "confirm" means propose a value and let
 | --- | --- | --- | --- |
 | 10 | When there is more than one package: **which one should a reader install first?** | `packages[].primary` | Exactly one `primary: true` when there are two or more packages. |
 | 11 | Is any declared package internal-only (an abstractions or runtime companion) rather than something a consumer installs? | `packages[].description` | Declare it anyway with a description; only one is primary. |
-| 12 | How is the primary package consumed — a plain NuGet reference, an MSBuild SDK, or a `dotnet` tool? | `install` | `nuget`; recon from the nuspec / `purview-build.json`. |
+| 12 | How is the primary package consumed — a plain NuGet reference, an MSBuild SDK, or a `dotnet` tool? (For an npm package, skip this: the registry decides the install tabs.) | `install` | `nuget`; recon from the nuspec / `purview-build.json`. |
 | 13 | *(Do not ask.)* Which target frameworks does it publish? | `targetFrameworks` | Read from the nuspec; the guard compares it and `just fix-projects` can rewrite it. |
 
 ### Curation and relationships (only the human knows these)
@@ -158,7 +158,7 @@ report — no check will catch them.
 | `category`, `experimental`, use-case prose | not machine-checkable → **judgement; record it** |
 | `status` | archived vs active repo, stable vs stable package → **fail**; preview with a stable package → **observation** |
 | `docs` | no pages, non-`main` branch → **fail**; no landing page → **observation** |
-| `packages` | duplicate id, >1 `primary`, unpublished package → **fail** |
+| `packages` | duplicate `registry:id`, >1 `primary`, unpublished package → **fail** |
 | `targetFrameworks` | mismatch with the published nuspec → **observation** (`just fix-projects`) |
 | `related`/`supersedes`/`supersededBy` | unknown id → **fail** (loader) |
 | topics | none set → **fail** |

.agents/skills/project-manifest-reference/SKILL.md

@@ -24,7 +24,8 @@ by `src/src/lib/manifest/load.ts`. `$schema: ../lib/manifest/schema.ts` is the f
 | `category` | `application-framework`, `validation`, `observability`, `source-generation`, `aspire`, `build-tooling`, `developer-tooling` |
 | `status` | `stable`, `preview`, `archived` |
 | `experimental` | boolean flag, default `false` — orthogonal to `status` (ADR 0004); invalid with `status: archived` |
-| `install` | `nuget` (default), `msbuild-sdk`, `dotnet-tool` |
+| `install` | `nuget` (default), `msbuild-sdk`, `dotnet-tool` — NuGet packages only |
+| `packages[].registry` | `nuget` (default), `npm` (ADR 0012) |
 | `useCases[].audience` | `developer`, `team-lead`, `architect`, `contributor` (labels: Developer, Team lead, Architect, Contributor) |
 
 Adding a value to any of these lists is a schema change and requires an ADR. `experimental` is a
@@ -48,9 +49,9 @@ Adding a value to any of these lists is a schema change and requires an ADR. `ex
 | `featured` | no | Default `false`; shown prominently on the home page |
 | `order` | no | Default `1000`; projects are sorted ascending; keep values unique |
 | `docs` | no | See below |
-| `install` | no | Default `nuget` |
+| `install` | no | Default `nuget`; how a **NuGet** package is consumed, so it has no meaning for an npm package |
 | `targetFrameworks` | no | e.g. `net8.0`, `net9.0`, `net10.0`, `netstandard2.0`; `just check-projects` reports (advisory) when it does not match the union of the runtime packages' published NuGet TFMs |
-| `packages` | no | `{ id, description?, primary?, targetFrameworks? }[]`; defaults to `[]` |
+| `packages` | no | `{ id, registry?, description?, primary?, targetFrameworks? }[]`; defaults to `[]`. `registry` is `nuget` (default) or `npm`; versions come from that registry and the install panel follows it |
 | `skills` | no | `{ name, path?, description? }[]` — Agent Skills the project publishes from `skills/<name>/SKILL.md` (ADR 0010); mirrored to `/skills/<id>/<name>/` and rendered with the shared install block; defaults to `[]` |
 | `assets` | no | `{ path, output, description? }[]`; repository files mirrored into `public/` at build time (`path` is repo-relative, `output` is site-relative); defaults to `[]` |
 | `related` | no | Known project ids; rendered in the project page aside |
@@ -119,7 +120,8 @@ docs:
 1. Schema validation with remediation text (unknown keys are rejected).
 2. `projects[].repository.split('/')[0]` must equal `purview-dev`.
 3. `related`, `supersedes`, and `supersededBy` must all reference existing project ids.
-4. A NuGet package id may be declared by **exactly one** project.
+4. A package id may be declared by **exactly one** project for its registry (the key is
+   `registry:id`; an absent `registry` means `nuget`).
 5. `experimental: true` is rejected when `status` is `archived` (schema refinement).
 6. An asset `output` path may be declared by **exactly one** project, must be relative, and must
    not contain a `..` segment.

.agents/skills/site-validation-loop/SKILL.md

@@ -52,7 +52,7 @@ deterministic). It fails the build on:
 Beyond those blockers, the guard prints **advisory observations** (they never fail the build) when a
 project disagrees with the versions and frameworks its packages have published:
 
-- a `preview` project whose packages already publish a stable NuGet version (unless `experimental`);
+- a `preview` project whose packages already publish a stable version on their registry (unless `experimental`);
 - a NuGet package that is deprecated or unlisted;
 - packages that trail the project's headline version;
 - `targetFrameworks` that do not match the packages' NuGet nuspec metadata. Project-level frameworks
@@ -74,7 +74,7 @@ or judgement calls such as replacing a deprecated package.
 `DATA_MODE` (`src/.env.example`) controls how docs/release data is obtained:
 
 - `auto` (default) — use the cache if present, else fetch live, else fall back to committed fixtures.
-- `live` — always fetch from GitHub/NuGet (`just live-data-sync`).
+- `live` — always fetch from GitHub and the package registries (`just live-data-sync`).
 - `cache` — only use the existing cache (fails if missing).
 - `fixture` — only use `src/fixtures/**` (fully offline, deterministic).
 
@@ -86,7 +86,7 @@ missing schema never silently ships a broken URL.
 `DATA_FALLBACK_TO_FIXTURES=false` makes `auto` fail loudly instead of silently using fixtures. Set
 `GITHUB_TOKEN` (or `gh auth token`) to avoid unauthenticated rate limits.
 
-The one thing the **browser** fetches is the NuGet **version numbers** a page already displays
+The one thing the **browser** fetches is the package **version numbers** a page already displays
 (ADR 0008, `src/src/lib/releases/live.ts`): the build-time value renders first, a strictly higher
 live version replaces it, and the result is stored in `localStorage` for six hours. The home-page
 snapshot, the package tables on `/releases/` and project pages, and the version pinned in the

.github/copilot-instructions.md

@@ -20,12 +20,13 @@ package is `src/`.
   `AGENTS.md` (unique ids/orders/packages, `name` slugifying to `id` for documented projects, at
   least one use case per non-archived project, `code` paired with `language`, resolvable `docsPage`).
 - Keep declared `status` and `targetFrameworks` honest: `just check-projects` prints advisory
-  observations when they disagree with the packages' published NuGet versions and frameworks. Apply
-  the machine-applicable ones with `just fix-projects` (dry run; pass `--write` to edit).
+  observations when they disagree with the packages' published versions and frameworks (NuGet, or
+  npm for a package with `registry: npm`). Apply the machine-applicable ones with `just fix-projects`
+  (dry run; pass `--write` to edit).
 - Keep documentation where it lives (the product repository). This site aggregates it at build time.
-- Keep the NuGet version hydration intact (ADR 0008): the build-time version renders first, the
-  browser only ever raises it, and the result is stored in `localStorage` for six hours. Do not move
-  any other data to the client.
+- Keep the package version hydration intact (ADR 0008, ADR 0012): the build-time version renders
+  first, the browser only ever raises it, and the result is stored in `localStorage` for six hours.
+  Do not move any other data to the client.
 - Use Conventional Commits and keep changes small and reviewable.
 
 ## Never
@@ -37,8 +38,8 @@ package is `src/`.
   `externalProjects:`.
 - Never invent a `category`, `status`, `audience`, or `install` value; the vocabulary lives in
   `src/src/lib/manifest/schema.ts`.
-- Never claim a project is `stable` without a stable NuGet release, or leave a project `stable`
-  while its repository is archived.
+- Never claim a project is `stable` without a stable release on its package registry, or leave a
+  project `stable` while its repository is archived.
 - Never derive a project's displayed status outside `displayStatus()` (`src/src/lib/status.ts`):
   `experimental: true` is an intent flag orthogonal to `status` (ADR 0004) and is invalid with
   `status: archived`.

AGENTS.md

@@ -26,11 +26,12 @@ from the repository root and delegated to the package.
   `oxfmt` does **not** support `.astro` yet (oxc-project/oxc#15665) — format those by hand and rely
   on `astro check` + oxlint.
 - **Task runner:** Just (`justfile`; switches to pwsh on Windows).
-- **All external data is fetched at build time**, never by the visitor's browser: GitHub/NuGet
-  release data, the documentation mirror, and any `assets:` a project mirrors into `public/`, cached
-  under `src/.cache/` with committed fixtures as the offline fallback. The one exception is the NuGet
-  **version numbers** the page already displays: the browser re-checks them against the NuGet
-  flat-container index, applies any higher version, and stores it (ADR 0008).
+- **All external data is fetched at build time**, never by the visitor's browser: GitHub releases,
+  NuGet and npm registry data, the documentation mirror, and any `assets:` a project mirrors into
+  `public/`, cached under `src/.cache/` with committed fixtures as the offline fallback. The one
+  exception is the package **version numbers** the page already displays: the browser re-checks them
+  against the registry that publishes the package (NuGet or npm), applies any higher version, and
+  stores it (ADR 0008, ADR 0012).
 
 ### Generated outputs — never edit by hand
 
@@ -65,7 +66,8 @@ prints advisory observations (which never fail the build) when a project's decla
 - Documentation stays in the product repository and is aggregated at build time into
   `/docs/<project-id>/`. **Tag chips are not authored in the manifest** — they come from the GitHub
   repository's *topics*, read through the release cache.
-- Versions and release dates come from GitHub releases plus the NuGet flat-container index.
+- Versions and release dates come from GitHub releases plus the registry that publishes each
+  package: the NuGet flat-container index, or npm's registry document.
 
 ## Mandatory rules
 
@@ -78,7 +80,8 @@ prints advisory observations (which never fail the build) when a project's decla
      `purview-dev/*` for `projects:` entries.
    - For any project with `docs`, the display `name` must slugify to exactly `id` (so the display
      name and the `/projects/<id>/` and `/docs/<id>/` URLs agree).
-   - NuGet package ids are unique across the whole catalogue; when a project has more than one
+   - Package ids are unique across the whole catalogue for their registry (`registry:id`; an absent
+      `registry` means `nuget`, ADR 0012); when a project has more than one
      package, exactly one must be `primary: true`.
    - Every non-archived project needs at least one concrete use case; a use case with `code` must
      also set `language`, and `docsPage` must be a lowercase `[a-z0-9-]` slug that resolves to a real
@@ -114,9 +117,9 @@ prints advisory observations (which never fail the build) when a project's decla
    - `order` values are unique and control the catalogue order.
    - `related`, `supersedes`, `supersededBy` must reference known ids.
    - `status` must match reality: an archived repository is `archived`; prerelease-only tooling is
-     `preview`; a project with a stable release is `stable`.
-   - Declared versions and frameworks must agree with what the packages publish: a stable NuGet
-     version on a `preview` project, a deprecated or unlisted package, packages that trail the family
+     `preview`; a project with a stable release on its package registry is `stable`.
+   - Declared versions and frameworks must agree with what the packages publish: a stable package
+     version on a `preview` project, a deprecated or unlisted NuGet package, packages that trail the family
      version, and a `targetFrameworks` set (project- or package-level) that does not match the
      packages' NuGet metadata are reported as advisory observations by `just check-projects`. They
      never fail the build, but they are catalogue drift and should be fixed or explicitly accepted.
@@ -165,5 +168,6 @@ Do not assume this file contains everything; consult `.agents/` while planning.
 | Release data | `src/src/lib/releases/*`, `src/scripts/fetch-releases.ts` |
 | Mirrored project assets | `src/scripts/sync-assets.ts` (`assets:` in the manifest) |
 | Pages | `src/src/pages/{index,about,use-cases,docs,projects,releases}/` |
+| Live examples | `src/src/pages/examples/<project-id>.mdx` (linked from the project page automatically) |
 | Validation | `justfile`, `src/scripts/{check-links,check-generated,check-assets,check-projects}.ts` |
 | Architecture decisions | `docs/decisions/*.md` |