Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/agents/catalogue-auditor.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ You are a specialist for auditing (and repairing) the Purview-Dev project catalo

## Primary objective

Prove that every project defined in the catalogue (`src/src/data/projects/`) is correct and report the evidence,
Prove that every catalogue record — the project-owned ones at `.config/purview-docs.yml` (ADR 0013) and the ones under `src/src/data/projects/` — is correct and report the evidence,
then fix the drift that is unambiguous and safe to fix.

## Background knowledge
Expand Down
2 changes: 1 addition & 1 deletion .agents/agents/catalogue-onboarder.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ You are a specialist for onboarding repositories into the Purview-Dev website ca
## Primary objective

Take a repository (`purview-dev/<repo>` or a collaboration repository) and deliver a complete,
validated integration: a correct catalogue record under `src/src/data/projects/`, a working documentation
validated integration: a correct catalogue record (`.config/purview-docs.yml` in the project's own repository, ADR 0013), a working documentation
configuration, concrete use cases, tags/metadata, and a green `just validate`.

## Background knowledge
Expand Down
4 changes: 3 additions & 1 deletion .agents/skills/add-catalogue-project/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,9 @@ description/topics.

## Step 3 — author the record

Add the entry as `src/src/data/projects/<id>.yml` (see `project-manifest-reference` for every field):
Add the record as `.config/purview-docs.yml` in the project's repository (ADR 0013), or as
`src/src/data/projects/<id>.yml` here until the project owns one (see `project-manifest-reference` for
every field):

```yaml
- id: <slug>
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/audit-catalogue-projects/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: audit-catalogue-projects
description: Use when auditing or repairing the catalogue records under src/src/data/ — the invariant checklist for documentation, stability, metadata, tags, packages, relationships, use cases and ordering, plus the findings report format.
description: Use when auditing or repairing the catalogue records — each project's own .config/purview-docs.yml (ADR 0013) and the ones still under src/src/data/ — the invariant checklist for documentation, stability, metadata, tags, packages, relationships, use cases and ordering, plus the findings report format.
category: purview-dev-website
roles:
- catalogue
Expand Down
12 changes: 8 additions & 4 deletions .agents/skills/project-manifest-reference/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: project-manifest-reference
description: Field-by-field reference for the catalogue records under src/src/data/projects/ (schema vocabulary, defaults, loader-enforced rules, and the invariants the site build depends on). Use whenever authoring or reviewing a catalogue record.
description: Field-by-field reference for the catalogue records a project publishes at .config/purview-docs.yml and the ones still under src/src/data/projects/ (schema vocabulary, defaults, loader-enforced rules, and the invariants the site build depends on). Use whenever authoring or reviewing a catalogue record.
category: purview-dev-website
roles:
- catalogue
Expand All @@ -13,9 +13,13 @@ tags:

# project-manifest-reference Skill

The catalogue is one file per project under `src/src/data/projects/` (plus
`src/src/data/external-projects.yml` for collaborations), typed by `src/src/lib/manifest/schema.ts` and validated
by `src/src/lib/manifest/load.ts`. `$schema: ../lib/manifest/schema.ts` is the first line of the file.
The catalogue is one record per project. A project publishes its own at `.config/purview-docs.yml` in
its repository, and that is what the site reads at build time (ADR 0013); the records a project does
not own yet are under `src/src/data/projects/`, and `src/src/data/external-projects.yml` holds the
collaborations. All of them are typed by `src/src/lib/manifest/schema.ts` and validated by
`src/src/lib/manifest/load.ts`. A record held here opens with `$schema: ../lib/manifest/schema.ts`;
a project-owned record names the schema by absolute URL, because the relative path resolves to nothing
from another repository.

## Vocabularies (do not invent values)

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/use-case-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ tags:
# use-case-authoring Skill

Use cases are the "what does it actually do for me" evidence on the home page, on each project page,
and on `/use-cases/`. They are authored in the catalogue records (`src/src/data/projects/<id>.yml`) and validated by the manifest
and on `/use-cases/`. They are authored in the catalogue records (`src/src/data/projects/<id>.yml` here, or a project's own `.config/purview-docs.yml`) and validated by the manifest
schema. The governing decision is `docs/decisions/0002-concrete-use-cases.md`.

## Shape
Expand Down
2 changes: 1 addition & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ package is `src/`.
- Treat `just validate` as the definition of done. It chains format-check, lint, typecheck, unit
tests, asset checks, build, link crawl, generated-output checks, built-output tests, and the
catalogue guard (`just check-projects`).
- Edit the catalogue under `src/src/data/` only (one file per project, plus `external-projects.yml`), and keep every invariant listed in
- Catalogue records live in each project repository at `.config/purview-docs.yml` (ADR 0013), in `src/src/data/projects/` for projects that do not own one yet, and in `src/src/data/external-projects.yml` for collaborations. Keep every invariant listed in
`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
Expand Down
24 changes: 15 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,10 @@ Two agent tasks recur here, and both have a dedicated agent plus skills under `.

1. **Add a project** — given a `purview-dev/<repo>` (or a collaboration repository), build its
documentation, use cases, tags and metadata so it is fully integrated into the site.
2. **Audit the catalogue** — prove that every project defined in `src/src/data/projects/` (one file per project, plus
`external-projects.yml` for collaborations) is
correct: documentation configuration, lifecycle stability, metadata and relationships.
2. **Audit the catalogue** — prove that every project record is correct: the ones the project
repositories own at `.config/purview-docs.yml` (ADR 0013) and the ones still here under
`src/src/data/projects/`, plus `src/src/data/external-projects.yml` for collaborations —
documentation configuration, lifecycle stability, metadata and relationships.

## Technology and tooling context

Expand All @@ -26,9 +27,10 @@ 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 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
- **All external data is fetched at build time**, never by the visitor's browser: the project-owned
catalogue records (ADR 0013), 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).
Expand All @@ -39,6 +41,7 @@ from the repository root and delegated to the package.
| --- | --- | --- |
| `src/src/content/docs/**` | Aggregated documentation mirror (gitignored) | `just data-sync` |
| `src/.cache/docs`, `src/.cache/releases` | Typed docs/release caches (gitignored) | `just data-sync` / `just fetch-releases` |
| `src/.cache/manifests` | Project-owned catalogue records fetched from their repositories (gitignored) | `just data-sync` / `just refresh-fixtures` |
| `src/public/schemas/**` | Mirrored project assets declared in `assets:` (gitignored) | `just data-sync` |
| `src/public/skills/**` | Mirrored Agent Skills declared in `skills:` (gitignored) | `just data-sync` |
| `src/dist/**` | Production build output (gitignored) | `just build` |
Expand All @@ -58,8 +61,10 @@ prints advisory observations (which never fail the build) when a project's decla

## Ecosystem model — what "a project" means here

- `projects:` entries — one file per project under `src/src/data/projects/` — are Purview-owned catalogue entries. Their `repository`
**must** be `purview-dev/<repo>` (enforced by the loader).
- `projects:` records — the ones under `src/src/data/projects/` here and the ones a project publishes
at `.config/purview-docs.yml` (ADR 0013) — are Purview-owned catalogue entries. Their `repository`
**must** be `purview-dev/<repo>` (enforced by the loader). A record declared in both places is
reported by `just check-projects`: the project's own copy wins, and the local one is deleted.
- `externalProjects:` are collaborations the organisation contributes to but does not own (for
example `likec4/likec4`). They link out to their own site/repository: no documentation
aggregation, no NuGet packages, no `/projects/<id>/` page.
Expand Down Expand Up @@ -175,7 +180,8 @@ src/src/data/projects/<id>.yml` against a clone of its repository.

| Concern | Location |
| --- | --- |
| Catalogue manifest | `src/src/data/projects/<id>.yml` (one per project) + `src/src/data/external-projects.yml` |
| Catalogue records | `.config/purview-docs.yml` in each project repository (ADR 0013), plus `src/src/data/projects/<id>.yml` for projects that have not moved, plus `src/src/data/external-projects.yml` for collaborations |
| Manifest fetch and cache | `src/src/lib/manifest/{remote,runtime}.ts`, `src/scripts/sync-manifests.ts` |
| Manifest schema / loader | `src/src/lib/manifest/{schema,load}.ts` |
| Docs aggregation | `src/src/lib/docs/aggregate.ts` (+ `frontmatter`, `links`, `sidebar`, `staleness`, `diagrams`, `redirect-file`) |
| Consumer skills for product repositories | `skills/purview-site-{integration,docs,assessment}/` |
Expand Down
23 changes: 15 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ purview-dev/ # workspace root
├── src/
│ ├── content.config.ts # Starlight docs collection schema
│ ├── content/docs/ # GENERATED documentation mirror (gitignored)
│ ├── data/projects/ # Typed, validated catalogue: one file per project
│ ├── data/projects/ # Records this repo still owns (a project owns its own - ADR 0013)
│ ├── data/external-projects.yml # Collaborations the organisation does not own
│ ├── lib/ # manifest, releases, docs, urls, site constants
│ ├── components/ # shared chrome, Starlight overrides, islands
Expand Down Expand Up @@ -173,7 +173,9 @@ just dev
```

The dev server starts after a data sync. Edit `src/src/pages/` for marketing
pages and `src/src/data/projects/<id>.yml` for catalogue content. Documentation pages
pages and a project's own `.config/purview-docs.yml` for that project's catalogue record —
the records a project does not own yet are still under `src/src/data/projects/`, and are edited here.
Documentation pages
are generated under `src/src/content/docs/` and should not be edited by hand —
change the source repository instead and re-run `just data-sync`.

Expand All @@ -198,15 +200,20 @@ generated copies.

## Project catalogue

`src/src/data/projects/<id>.yml` (one file per project, plus
`src/src/data/external-projects.yml` for collaborations) is the single source of truth for the catalogue. It
is validated at build time by a typed Zod schema
(`src/src/lib/manifest/schema.ts`). Validation failures report the source file,
the offending property, the expected shape, and a remediation hint.
Every project publishes its catalogue record at `.config/purview-docs.yml` in its own repository
(ADR 0013), which the site reads at build time from that repository's default branch, so a record
changes in the same pull request as the project it describes. Records a project does not own yet live
under `src/src/data/projects/` — a project-owned record wins when both exist — and
`src/src/data/external-projects.yml` holds the collaborations the organisation does not own.

Everything is validated at build time by a typed Zod schema
(`src/src/lib/manifest/schema.ts`). Validation failures name the record's owner, the
offending property, the expected shape, and a remediation hint.

### Adding a new Purview-Dev project

1. Add a record at `src/src/data/projects/<id>.yml` with a unique `id`, `name`,
1. Add the record at `.config/purview-docs.yml` in the project's repository (or under
`src/src/data/projects/<id>.yml` here, until the project owns one) with a unique `id`, `name`,
`shortDescription`, `description`, `repository` (a purview-dev repo),
`category`, `status`, and optional `order`. Set `experimental: true` for an
exploratory project — it is a flag orthogonal to `status` (ADR 0004).
Expand Down
102 changes: 102 additions & 0 deletions docs/decisions/0013-project-owned-manifests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# ADR 0013 — Project-owned catalogue records

- Status: accepted
- Date: 2026-11-15

## Context

ADR 0005 split the catalogue into one file per project, `src/src/data/projects/<id>.yml`, and the
split worked: a project's history and review are self-contained, and two concurrent additions no
longer conflict. What it did not change is **who owns the words**.

Every one of those files is written and reviewed here, in `purview-dev/purview-dev`, by the site
maintainers, while the project it describes lives in another repository and moves without asking.
That is a drift engine with no detector: `zodsharp`'s record still listed `net8.0` and `net9.0` two
releases after the project dropped them, and its `status`, `docs.channels` and package descriptions
are all facts the project knows better than the site does. Correcting any of it is a cross-repository
pull request, which is exactly the friction that makes a record stale in the first place.

Everything else the site reads for a project is already pulled from the project at build time — the
release data, the documentation tree, the agent skills, the mirrored assets — each with a cache under
`src/.cache/` and a committed fixture under `src/fixtures/` as the offline fallback. The catalogue is
the one input that is still copy-pasted in.

## Decisions

### 1. `.config/purview-docs.yml`, published by the project

A project repository publishes its catalogue record at `.config/purview-docs.yml`: the same record,
the same fields, one file, no wrapper. A repository that publishes the file is a catalogue project;
a repository that does not is not one, and no list anywhere else says which is which.

### 2. Discovery is the organisation's repository list

`sync-manifests` lists the `purview-dev` organisation's repositories (one API call, paged) and tries
`raw.githubusercontent.com/<owner>/<repo>/<default-branch>/.config/purview-docs.yml` for each. A 404
is not an error: it means that repository is not a catalogue project. Adding a project to the site is
therefore one file in the project's repository and no pull request here; removing it is deleting the
file.

The record is read at the **default branch**, the same source and ref the documentation mirror uses,
so the site shows what the project actually publishes rather than what a pull request once said.

### 3. A project's record wins, and the clash is reported

`readRawManifest()` still reads `src/src/data/projects/*.yml`, and merges the project-owned records
over them: same id means the owner's record wins. This is the migration path — moving a record is a
change in the project repository plus the deletion of the local copy — and it means a project with no
published record keeps working exactly as before.

The clash is not silent. `readRawManifest()` reports the ids declared twice, and `just check-projects`
prints an observation naming the local file to delete. It is an observation rather than a blocker
because the move is two pull requests in two repositories and the site must not fail in the gap
between them.

### 4. `.config/` rather than a top-level file

The record is site plumbing, not project source, and `.config/` is where a project already keeps its
other tool configuration (`lefthook.yml`, `dotnet-tools.json`, `purview-build.json`). One file, one
purpose, out of the way of the project's own documentation.

### 5. The same cache and fixture model as the release data

`sync-manifests` writes `src/.cache/manifests/manifests.json`, and `just refresh-fixtures` writes
`src/fixtures/manifests/index.json`. `getManifestIndex()` reads the cache, then the fixture, and
never performs network I/O, so rendering is unaffected and an offline build still resolves the whole
catalogue. `DATA_MODE` selects the source exactly as it does for releases: `live` always fetches,
`cache` and `fixture` never do, and `auto` prefers the cache.

The fixture is a snapshot, not a second source of truth: a record that changed in its project
repository is picked up by the next `just data-sync` (or `just refresh-fixtures`).

### 6. The `$schema` hint stays advisory

The record may open with a `$schema` pointing at this repository's schema module. It is an editor
affordance, as ADR 0005 §5 says, and the enforcing validation remains `loadProjects()` here plus
`just check-projects`. A project-owned record names the schema by absolute URL, because the relative
path it used to carry resolves to nothing from another repository.

### 7. Validation failures name the owner

`parseManifest()` takes the provenance of each record, so a failure reads
`projects[zodsharp] (purview-dev/zodsharp (.config/purview-docs.yml at main))` rather than naming a
file that does not exist here. A schema error in a project-owned record is a build failure with the
repository named: the project owns the record, so it owns fixing it.

## Consequences

- The catalogue is complete without this repository holding any project's words. What is left here is
`src/src/data/external-projects.yml` (collaborations, which are not ours to own) and the records of
projects that have not migrated.
- Editorial fields — `status`, `featured`, `order`, `category`, the docs channels and the redirects —
move to the project with the rest of the record: the record is the project's, whole.
- The site's build now depends on files it does not control. A malformed record fails the build with
the repository named, and the fetch reports *every* unreadable record at once rather than skipping
it, because a catalogue that silently lost a project is worse than a failed build.
- `just fix-projects` can no longer auto-fix a project-owned record: the observation is printed with
the repository to edit, and the write to a local file is skipped.
- Discovery is organisation-wide, so a new repository that publishes a record appears on the site on
the next build. That is the intent: the organisation's repositories are the catalogue's scope.
- The record is read at the default branch while the documentation mirror still honours per-channel
refs (`docs.channels`), so a project that publishes docs from a tag keeps its record at the head of
the branch.
Loading
Loading