diff --git a/.agents/skills/add-catalogue-project/SKILL.md b/.agents/skills/add-catalogue-project/SKILL.md deleted file mode 100644 index 963fe0b..0000000 --- a/.agents/skills/add-catalogue-project/SKILL.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -name: add-catalogue-project -description: Use when adding a repository to the Purview-Dev website catalogue — recon the repo, author the catalogue record (docs, packages, tags, use cases), integrate it across the catalogue/docs/releases surfaces, and prove it with the validation pipeline. -category: purview-dev-website -roles: - - catalogue - - docs - - integration -tags: - - projects-yml - - astro - - starlight - - documentation ---- - -# add-catalogue-project Skill - -Use this skill when a repository must be added to (or promoted within) the Purview-Dev website. - -Related: `add-project-intake`, `project-manifest-reference`, `docs-aggregation-rules`, -`use-case-authoring`, `github-repo-metadata`, `site-validation-loop`. - -## Step 0 — decide the target collection - -| Situation | Where it goes | -| --- | --- | -| Repository is owned by the `purview-dev` organisation | `projects:` | -| Project the organisation contributes to but does not own (for example `likec4/likec4`) | `externalProjects:` | - -Only `projects:` entries get a `/projects//` page, documentation aggregation, LLM bundles and -release data. `externalProjects:` entries are link-out cards on `/projects/` and must never point at -a `purview-dev` repository. - -## Step 1 — recon the repository (never guess) - -```shell -# Metadata: description, topics, archived, default branch, discussions, homepage -gh api repos// --jq '{description, topics, archived, default_branch, has_discussions, homepage}' - -# Docs layout: does docs/ exist, is it a mirror of the wiki, is there a _Sidebar.md? -gh api "repos///git/trees/main?recursive=1" --jq '.tree[].path' -gh api "repos///contents/README.md" -H 'Accept: application/vnd.github.raw' - -# Project conventions: build type, agent guidance, licensing -gh api "repos///contents/purview-build.json" -H 'Accept: application/vnd.github.raw' - -# Release channel and tag shape -gh api "repos///releases?per_page=10" --jq '.[] | {tag_name, prerelease, published_at}' - -# Packages: confirm each id exists and see its channel (replace the id) -curl.exe -s "https://api.nuget.org/v3-flatcontainer//index.json" -# npm packages (skip the NuGet index): the registry document carries versions + dist-tags -curl.exe -s "https://registry.npmjs.org/%2F" -``` - -Record, as evidence for the record you are about to write: where the docs live, the exact markdown -file that should be the landing page, the NuGet package ids, the release channel, and the repository -description/topics. - -## Step 2 — classify - -- `category`: exactly one of `application-framework`, `validation`, `observability`, - `source-generation`, `aspire`, `build-tooling`, `developer-tooling`. -- `status`: - - `archived` when the repository is archived (GitHub `archived: true`). - - `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 - channel alongside it (`preview` for prerelease-only tooling). See ADR 0004; the project page and - every aggregated documentation page then carry an Experimental warning. -- `id`: lowercase `[a-z0-9-]` slug, normally the repository name. -- `name`: display name. **It must slugify to `id` when the project has `docs`** (so the display name - and the `/projects//` and `/docs//` URLs agree). -- `order`: pick an unused value (10–80 in tens is the existing convention). - -## Step 3 — author the record - -Add the entry as `src/src/data/projects/.yml` (see `project-manifest-reference` for every field): - -```yaml - - id: - name: - shortDescription: - description: >- - - origin: >- - - useWhen: >- - - avoidWhen: >- - - repository: purview-dev/ - category: - status: - order: - docs: - source: github-path | wiki | readme - path: docs # github-path only - rootPage: Home.md # optional; see docs-aggregation-rules - exclude: [ _Sidebar.md ] # only files the repository actually ships - targetFrameworks: [ net8.0, net9.0 ] - install: nuget | msbuild-sdk | dotnet-tool # NuGet packages only; omit for npm - packages: - - id: - registry: nuget | npm # optional; defaults to nuget (ADR 0012) - description: - primary: true - related: [ ] - acknowledgments: - - name: - url: https://github.com// - description: - useCases: - - audience: developer - title: - scenario: >- - - code: | - - language: csharp - outcome: >- - - evidence: >- - - docsPage: -``` - -Every non-archived project needs at least **one** use case with `code` + `language` and an -`evidence` fact (ADR 0002). See `use-case-authoring`. - -## Step 4 — fix the upstream metadata (this is where tags come from) - -- Set GitHub **topics** on the repository (they become the site's tag chips). See - `github-repo-metadata` for the exact command and the taxonomy guidance. -- The repository description must be genuinely descriptive: it backs the `shortDescription` - fallback and social/`og:` metadata. -- Leave `discussions` unset: the loader detects it from the repository (`hasDiscussions`). Set - `discussions: false` only to opt a repository out, or `true` to force the link. - -## Step 5 — integrate and verify - -```shell -just data-sync # aggregate docs + refresh release data (cache-first) -just check-projects # deterministic catalogue guard (part of `just validate`) -bun run typecheck && bun run test -just check-generated -just validate # full chain: format, lint, build, link crawl, dist tests -``` - -Confirm each surface actually lights up: - -1. `/projects/` shows the card with the right category/status/tags (tags come from topics). -2. `/projects//` renders description, use cases, install panel, packages, and related links. -3. `/docs//` exists with the expected page count and a sidebar topic named after the project. -4. `/projects//llms.txt` and `/projects//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 and registry versions (NuGet or npm) for the declared packages. -7. If a live example page exists at `src/src/pages/examples/.mdx`, `/projects//` links it as - **Live example** (the page is discovered, not declared). - -## Step 6 — report - -State: the record added, the recon evidence, the package ids and channels, the docs source and page -count, the checks run with their result, and any `upstream` follow-ups (for example: topics missing, -docs not yet in a `docs/` folder, no stable release yet). - -## Pitfalls - -- `docs.path` must be a **repository path** (`docs`, `docs/wiki`), never a URL. -- A repository whose wiki is mirrored into `docs/wiki` is plain Markdown: `Home.md` is the hub and - `_Sidebar.md` (the navigation) is the only file that has to be excluded. A wiki that keeps a - different first page keeps `rootPage`; only a page the repository does **not** ship needs excluding, - and a stale pattern (an `index.md` the upstream deleted) is a silent no-op rather than an error. - See `docs-aggregation-rules`. -- Aggregation reads branch `main`. If the repository's default branch is `master`/`develop`, docs - aggregation silently yields nothing — rename or report it. -- The `README.md`-as-index mode (`readme:`) publishes exactly one page and cannot be combined with - `rootPage`. -- Adding a project does not require editing tests: the manifest tests assert `>=` counts, not exact - membership. But keep their expectations true (for example the `>= 8` use-case coverage). diff --git a/.agents/skills/audit-catalogue-projects/SKILL.md b/.agents/skills/audit-catalogue-projects/SKILL.md deleted file mode 100644 index 90328d7..0000000 --- a/.agents/skills/audit-catalogue-projects/SKILL.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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. -category: purview-dev-website -roles: - - catalogue - - audit -tags: - - projects-yml - - validation - - metadata ---- - -# audit-catalogue-projects Skill - -Use this skill to answer "is every project in the catalogue correct?" with evidence, and to repair -the unambiguous problems. - -Related: `project-manifest-reference` (fields and vocabularies), `docs-aggregation-rules`, -`use-case-authoring`, `github-repo-metadata`, `site-validation-loop`. - -## Method - -1. **Deterministic first.** Run `just check-projects` and `bun run test`. These already enforce the - structural invariants; start from their output rather than re-deriving it. -2. **Then the judgement checks** that no script can make: is the description truthful, is the - category right, is the stability honest, is the use-case evidence real. -3. **Gather live evidence per project** with `gh` and NuGet (commands in `github-repo-metadata`). -4. **Report before repairing.** Produce the findings table, then apply `blocker`/`drift` fixes and - re-run the guards. - -## Invariant checklist - -### Structure (enforced by `loadProjects()` / `just check-projects`) - -- `id` is a lowercase `[a-z0-9-]` slug; `repository` is `purview-dev/` for `projects:`. -- `related`, `supersedes`, `supersededBy` reference known ids; a superseded project names its - successor and vice versa where the pairing exists. -- Every NuGet package id appears exactly once across the catalogue. -- `order` values are unique integers and the sorted order is the intended presentation order. -- For every project with `docs`, `name` slugifies to exactly `id`. -- Every non-archived project has ≥1 use case; every use case with `code` has `language`. -- Every `docsPage` resolves to a page in `src/.cache/docs/index.json` for that project. -- `externalProjects` never point at a `purview-dev` repository and always have a working `url`. - -### Documentation - -- `docs.source` matches reality: `github-path` when the repository has a docs folder, - `wiki` when the content lives in the wiki, `readme` only for single-page projects. -- `docs.path` exists **on branch `main`** and contains `.md` files. -- `rootPage` names a page that exists under `docs.path`; when it names a non-index page and a - conventional root page (`index.md`/`Home.md`/`readme.md`) also exists, that conventional page must be - listed in `exclude`. -- `exclude` keeps the navigation files out of the page list: `_Sidebar.md` (and `_Footer.md` for a - `wiki` source). It is a filter over the files the repository ships, so a pattern naming a file that - no longer exists is a no-op, not a warning or a failure. -- The aggregated page count is non-zero and the landing page is the page a reader should land on. -- Archived projects that still declare `docs` are intentional (they are excluded from the portal). -- Documentation is not duplicated here: this repository only holds the mirror. -- Pages moved in the repository's history have a redirect — in its `_redirects.yml` or the entry's - `docs.redirects` (ADR 0013). Diagrams are LikeC4/Mermaid pairs, not ASCII art or Mermaid in a - `text` fence. The consumer assessment script reports both against a clone (below); file the - repository-side fixes as `upstream` items, since they belong in the product repository. - -### Stability - -- `archived` repository ⇒ `status: archived`. -- No stable NuGet release ⇒ not `stable` (`preview`). -- `experimental: true` is orthogonal to `status`: report `experimental` with `status: stable` as - `drift` (the flag says "no support promise" while the channel says "recommended for use"), and - `experimental` on an archived project as a `blocker` (the schema rejects it outright). -- `stable` ⇒ a stable, listed NuGet release exists and the repository is not archived. -- Deprecated NuGet packages are reported, not silently accepted. -- A project with `packages: []` is intentional: build tooling consumed as a tool/SDK still declares - its package id when one exists. - -### Metadata and tags - -- Repository description is present, factual, and consistent with `shortDescription`/`description`. -- **Topics are non-empty** — they are the only source of site tags — and follow the lowercase, - hyphenated taxonomy. -- `discussions: true` only when the repository has discussions enabled. -- `homepage`/`url` targets resolve. -- `featured` is used deliberately (a handful of headline projects, not most of the catalogue). - -### Packages, frameworks and install - -- Each declared package id exists on NuGet and has published versions (the guard checks the release - cache). -- Exactly one `primary` when a project has multiple packages. -- `targetFrameworks` match the package's actual TFMs (`netstandard2.0` for generators/analyzers is - normal). `just check-projects` reports a mismatch as an advisory observation: project-level - frameworks against the union of the runtime packages' published TFMs, package-level frameworks - against that package's own. `netstandard*` is treated as an analyzer/generator target, not a - consumer framework. -- `install` is set only when the package is not a plain NuGet reference: `msbuild-sdk` for - `Purview.BuildSdk`, `dotnet-tool` for `Purview.Build`. - -### Use cases - -- Coverage across audiences is meaningful for the project's shape (adopter, approver, extender). -- `scenario` describes a situation; `outcome` describes the result; `evidence` is a fact. -- Snippets are short, compile-plausible, and use the right `language`. -- `docsPage` points at the page that actually carries the depth. - -## Evidence commands - -```shell -# Deterministic guards -just check-projects -bun run test - -# Per-project live evidence -gh api repos/purview-dev/ --jq '{description, topics, archived, default_branch, has_discussions, homepage}' -gh api "repos/purview-dev//git/trees/main?recursive=1" --jq '[.tree[].path | select(endswith(".md"))]' -gh api "repos/purview-dev//releases?per_page=10" --jq '.[] | {tag_name, prerelease}' -curl.exe -s "https://api.nuget.org/v3-flatcontainer//index.json" - -# Repository-side integration (docs layout, diagrams, redirects, skills) against a fresh clone -git clone --depth 300 https://github.com/purview-dev/.git / -node skills/purview-site-assessment/scripts/assess.mjs / --catalogue src/src/data/projects/.yml - -# Aggregated result -node -e "const m=require('./src/.cache/docs/index.json');for(const p of m.projects)console.log(p.projectId,p.pages.length)" -``` - -If `.cache/docs/index.json` or the release cache is stale, run `just data-sync` (live) first so the -evidence and the guards agree. - -## Report format - -```markdown -| Project | Field | Observed | Expected | Severity | Evidence | Fix | -| --- | --- | --- | --- | --- | --- | --- | -| example-tool | status | stable | preview | drift | no stable NuGet version (flat container: only 1.2.0-prerelease.3) | set status: preview | -| example-tool | — | topics: [] | 6–15 topics | drift | `gh api repos/...` shows an empty topics array | set repository topics | -``` - -- Severity: `blocker` (schema/build failure or a broken page), `drift` (data contradicts reality), - `polish` (quality), `upstream` (must be fixed in the product repository: missing docs, missing - topics you cannot set, no stable release). -- Close the report with: number of projects audited, checks run, fixes applied, and the items left - for a human. -- Apply only `blocker` and `drift` fixes; never restructure a record or change a category to make a - check pass. - -## Guardrails - -- Do not add use cases or evidence you cannot trace to the repository or the aggregated docs; report - the gap instead. -- Do not change the schema vocabulary; adding a `status`/`category` value needs an ADR. -- Do not hand-edit the docs mirror or caches to make the audit pass. -- If an audit fix changes a catalogue record, re-run `just check-projects`, `bun run test`, and - `just validate` before reporting completion. diff --git a/.agents/skills/docs-aggregation-rules/SKILL.md b/.agents/skills/docs-aggregation-rules/SKILL.md deleted file mode 100644 index b5e646c..0000000 --- a/.agents/skills/docs-aggregation-rules/SKILL.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -name: docs-aggregation-rules -description: How the website aggregates documentation from product repositories into /docs// — sources, root-page and exclusion rules, ordering, injected front matter, tags from repository topics, staleness, and the failure modes with their remediations. -category: purview-dev-website -roles: - - docs - - reference -tags: - - starlight - - documentation - - aggregation ---- - -# docs-aggregation-rules Skill - -`just data-sync` runs `src/scripts/sync-docs.ts` → `aggregateDocs()` in -`src/src/lib/docs/aggregate.ts`. It reads each catalogue project's `docs` configuration, fetches -the markdown from the product repository, writes the mirror to `src/src/content/docs/docs//` -and records the page list in `src/.cache/docs/index.json`. - -**Never edit the mirror by hand** — it is gitignored and regenerated. - -## Where content comes from - -| `docs.source` | Fetch mechanism | Notes | -| --- | --- | --- | -| `github-path` | Repository tree (`git/trees/?recursive=1`) filtered to `/**/*.md` | Each file fetched from `raw.githubusercontent.com` at the channel's ref (the repository's default branch when no `channels` are declared) | -| `wiki` | `git clone --depth 1 https://github.com/.wiki.git` | `_Sidebar.md` and `_Footer.md` are never rendered. A wiki has one HEAD, so it supports a single channel | -| `readme` | Raw `README.md` | Exactly one page (`index`), single channel | - -The ref is the repository's **default branch** (from the release cache, falling -back to `main`) unless the manifest declares `docs.channels` (ADR 0009). -`lastReviewed` is the last commit date for the file (Atom feed for -`github-path`/`readme`, wiki HEAD commit for `wiki`); a channel pinned to a -release tag uses that release's date instead, because the content cannot move. - -## Channels (`live` and `prerelease`) - -A project may publish two views of its documentation: - -```yaml - docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - channels: - live: - ref: latest-stable - prerelease: - ref: default -``` - -- The **default** channel (`live`, or the only declared channel) is written to - `src/src/content/docs/docs//.md` and served at `/docs///`. -- Any other channel is written to - `src/src/content/docs/docs///.md` and served at - `/docs////`. -- `docs//` is reserved: a source page whose slug equals a channel id - raises `DocsValidationError`. -- `src/.cache/docs/index.json` is schema 2 and stores - `projects[].channels[] = { id, ref, refKind, version, label, default, pages[] }`. - A cache from an older schema reads as absent, so `just data-sync` regenerates it. -- The Starlight sidebar groups a two-channel project per channel (`Live 2.4.2`, - `Prerelease main`); a one-channel project keeps a flat list. The page title - component renders the switcher and a prerelease notice. -- **Promotion is automatic.** The prerelease channel is only aggregated while a - prerelease version outranks the newest stable release, computed from GitHub - release tags and NuGet versions. A stable release that catches up retires the - channel on the next sync (a `docs : prerelease documentation is not - published: …` line, not an error) and the next prerelease restores it. Never - remove the declaration just to stop publishing it. -- **Retired URLs redirect to live.** For each withheld channel URL the build - writes a `noindex` meta-refresh page (canonical + `data-pagefind-ignore`) - pointing at the live page with the same slug — GitHub Pages serves files only, - so `_redirects` is not an option. These files are written at - `astro:build:done` (`config/docs-redirects-integration.ts`), outside Astro's - route list, so they stay out of the sitemap, `discover.json` and the llms - bundles. -- Per-project `llms-full.txt` publishes the default channel only; `llms.txt` - also links the prerelease channel when one exists. - - -## Root page selection (the most common onboarding failure) - -1. A conventional index file wins by default: `index.md`, `Home.md`, or `readme.md` (case-insensitive - basename). -2. `docs.rootPage` may override it **only** when that conventional file is removed with - `docs.exclude`. Otherwise aggregation raises `DocsValidationError`: - *"selects a non-index page while a conventional root page already exists"*. -3. If no index file and no `rootPage` exist, aggregation raises - *"docs: no root page exists"* — add `index.md`/`Home.md`/`readme.md` or set `rootPage`. -4. If `rootPage` names a file that does not exist, aggregation raises - *"docs.rootPage: ... does not exist"*. - -The product wikis are mirrored into `docs/wiki` and are **plain Markdown**: `Home.md` is the hub, -`_Sidebar.md` is the whole navigation, and the repository carries no site configuration at all — the -engineering playbook deleted its `mkdocs.yml` and its TechDocs `index.md`, and no repository needs to -add them back. A repository that still ships a site file (`mkdocs.yml`) or a generated `index.md` is a -**deviation this portal ignores**: aggregation reads `docs.path` and this entry's `exclude`, never the -site configuration. So the pattern for a wiki is: - -```yaml - docs: - source: github-path - path: docs/wiki - rootPage: Home.md - exclude: [ _Sidebar.md ] -``` - -`Home.md` is itself a conventional root page, so `rootPage` restates the default rather than -overriding it, and nothing has to be excluded for it to win. Exclude only the files the repository -actually ships. - -While a repository still carries a site file, `just data-sync` reports it once and **never fails**: - - docs containers: mkdocs.yml is a repository site configuration and the portal ignores it — the - catalogue entry alone decides what is published, so the repository can drop the file. - -That is an advisory (`findLegacySiteConfig` in `src/lib/docs/aggregate.ts`), not a gate, and it is -printed on stdout so it survives into the build log; on GitHub Actions the same text is repeated as a -`::warning` annotation on the run. The aggregation keeps stripping the Material markup such a file -stands for (`./mkdocs`), so the file can be deleted upstream in its own time and on its own pull -request; when it is gone the advisory simply stops appearing. - -## Exclusions and ordering - -- `exclude` matches the **base file name** (`index.md`, `_Sidebar.md`) with `*` wildcards; it is - applied **before** the root page is selected (that is what makes rule 2 work). -- A pattern that matches nothing is a **no-op**: excluding `index.md` from a wiki that has since - replaced it with `Home.md` neither warns nor fails, so a stale pattern cannot block the build while - the upstream repository is mid-reorganisation. Remove it when you notice, but it is not drift the - guard reports. -- Page order comes from, in priority: `docs.order` (explicit slug list) → a `_Sidebar.md` link order - (both for `wiki` and for a mirrored wiki under `github-path`) → `1000`. -- The landing page is always `order: -1`, so it heads the sidebar as "Overview". -- 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//getting-started/`), and a - topic folder stays a path segment (`schemas/Custom-Rules.md` → - `/docs//schemas/custom-rules/`). A nested `README.md` is the folder's index, so - `guide/README.md` publishes at `/docs//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) - -`title` (first `# H1`, else the slug), `description` (first prose paragraph, ≤160 chars), -`owners: [purview-dev]`, `status` (the project's status), `experimental: true` (written only when -the catalogue flags the project, ADR 0004), `lastReviewed`, `sourceProject`, -`sourceRepo`, `projectName`, `sourcePath`, `editUrl`, `tags` (the repository's GitHub **topics**, -absent when there are none), and `sidebar.label`/`sidebar.order`. - -Additional transformations: GitHub alert blockquotes become Starlight asides; relative links between -documents are rewritten to portal URLs; **relative** images are rewritten to GitHub raw URLs while -**absolute** image URLs pass through untouched — a registry badge such as -`![Purview.BuildSdk](https://img.shields.io/nuget/v/Purview.BuildSdk)` keeps its own URL, so a page can -show a live version without stating a number that rots; the first top-level H1 is removed from the body -(it becomes the front-matter `title`, which the page header renders) and any later H1 is demoted to `##`, -so each page shows its title once. - -## What the site does with it - -- Each documented project becomes a `starlight-sidebar-topics` topic whose items come from - `src/.cache/docs/index.json` (so the mirror and the manifest must come from the same sync). -- 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` 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 - bundles, even if they declare `docs`. -- Every documented project gets `/projects//llms.txt` and `/projects//llms-full.txt`, linked - from `/llms.txt` and from the project page. -- Staleness: a page is flagged when `lastReviewed` is older than 365 days - (`src/src/lib/docs/staleness.ts`). -- A ```` ```likec4 ```` fence in a mirrored page is rendered when it compiles, and - stays **source** when it does not: the whole `docs` collection is relaxed through - astroc4's `validation: { collections: ['docs'] }` (`astro.config.ts`). Such a page - was written for another renderer, so its fence is often a partial snippet; astroc4 - logs a warning and leaves it as a highlighted code block instead of failing the - build. Pages the site authors (`src/pages/**`) are not in the collection, so they - keep strict validation. - -## Diagram pairs (ADR 0013) - -A product page pairs a GitHub rendering with a LikeC4 view: - -````markdown - -```mermaid -flowchart LR - resume --> next -``` -[LikeC4 model](./diagrams/the-loop.c4) - -```` - -`buildPage` runs `applyDiagramBlocks` (`src/lib/docs/diagrams.ts`) on the raw source before anything -else: the `.c4` file is read from the repository at the channel's ref (resolved relative to the page, -or `/`-rooted at the repository root), and the whole block becomes a ```` ```likec4 ```` fence holding -the model, with `view`, `project`, `title`, `description`, `height`, `collapsible` and `defaultOpen` -passed through. A missing model, an undeclared view or a malformed marker keeps the Mermaid and logs -`docs : line : …`. Markers inside code fences are ignored. - -## Repository redirects (`_redirects.yml`, ADR 0013) - -`/_redirects.yml` (the wiki root for `source: wiki`) holds `previous: current` pairs, either -under `redirects:` or as a bare map; each side is a slug or a Markdown path, reduced with `docSlug`. -It is read per channel and stored as `channels[].redirects` in `src/.cache/docs/index.json`; -`docsPageRedirects(projects, manifest)` writes each channel's pairs from that channel's base, after the -catalogue's `docs.redirects` (which wins on a conflict). An invalid file is a `DocsValidationError`; a -destination that is not a page, or a source that still is, is an advisory line in the sync log. - -## Consumer skills - -`skills/` at the repository root is what product repositories install -(`npx skills add purview-dev/purview-dev`): `purview-site-integration`, `purview-site-docs` and -`purview-site-assessment` (with `scripts/assess.mjs`). They restate these rules for authors, so a change -to slugs, diagram pairs or redirects here changes them in the same pull request. - -## Verifying - -```shell -just data-sync # expect "docs : pages" per project -node -e "console.log(require('./src/.cache/docs/index.json').projects)" -just build && just check-generated # asserts the mirror matches the manifest -``` - -A reorganised tree is verified in the built output: the old flat slug must be a meta-refresh page -pointing at the new address, on every channel that publishes the tree (`/docs///` and -`/docs//prerelease//`), and the sidebar of a nested channel must contain a `group-label`. - -A page that shows a registry badge instead of a version is verified the same way: the badge URL must -appear verbatim in the built page (`dist/docs///index.html`), not rewritten to a -`raw.githubusercontent.com` address. `docs.test.ts` covers an absolute badge URL beside a relative one. diff --git a/.agents/skills/github-repo-metadata/SKILL.md b/.agents/skills/github-repo-metadata/SKILL.md deleted file mode 100644 index c346bc1..0000000 --- a/.agents/skills/github-repo-metadata/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: github-repo-metadata -description: How GitHub repository metadata feeds the website (topics become tags, description backs shortDescription, archived/description/discussions drive status and links) and how to inspect and correct it with gh. -category: purview-dev-website -roles: - - catalogue - - metadata -tags: - - github - - topics - - tags - - nuget ---- - -# github-repo-metadata Skill - -The manifest is curated, but several site surfaces read **live repository metadata** that is fetched -at build time into `src/.cache/releases/releases.json` (`fetchGitHubRepo`, `fetchNuGetIndex`, -`fetchNuGetSearch` in `src/src/lib/releases/github.ts`). NuGet **version numbers** are the one -exception: the browser re-checks them against the flat-container index and stores the result -(ADR 0008, `src/src/lib/releases/live.ts`), so a published version appears without a redeploy. -Everything else in the table below is build-time. - -## What comes from where - -| Site surface | Source | Notes | -| --- | --- | --- | -| Tag chips (cards, docs portal, docs-page front matter `tags`) | GitHub **topics** | `projectRepoEnrichment()` in `src/src/lib/releases/repo.ts` | -| `shortDescription` fallback | GitHub **description** | Used only when the manifest value is empty | -| "supplemental" description on the project page | GitHub description | Shown when it differs from the manifest description | -| Successor/archived messaging | GitHub **archived** flag + `status`/`supersededBy` | | -| Version numbers, release dates, badges | GitHub releases + NuGet flat-container index | | -| Downloads / deprecated / listed | NuGet search entry | Rendered on the release tables | -| Discussions link | repository discussion settings (detected) | `hasDiscussions` from the cache; a record's `discussions` is only an override | - -`search` corpora on `/projects/` deliberately include the topics, so missing topics make a project -undiscoverable by its domain keywords. - -## Inspecting - -```shell -gh api repos/purview-dev/ --jq '{description, topics, archived, default_branch, has_discussions, homepage, visibility}' -gh api "repos/purview-dev//releases?per_page=10" --jq '.[] | {tag_name, prerelease, draft}' -curl.exe -s "https://api.nuget.org/v3-flatcontainer//index.json" -curl.exe -s "https://azuresearch-usnc.nuget.org/query?q=packageid:&take=1" -``` - -## Correcting - -Topics are replaced wholesale (PUT), so send the complete set: - -```shell -echo '{"names":["csharp","dotnet","roslyn","source-generators","telemetry"]}' > topics.json -gh api repos/purview-dev//topics --method PUT --input topics.json -rm topics.json -``` - -`gh` also accepts repeated array fields: `gh api repos///topics --method PUT -f 'names[]=csharp' -f 'names[]=dotnet'`. - -Other metadata (`description`, `homepage`, `has_discussions`) is set in the repository settings or -with `gh api repos// --method PATCH -f description='...' -f homepage='...'`. Enabling -Discussions on an organisation repository requires organisation permission; report it as an -`upstream` item when you cannot do it. - -## Tag taxonomy guidance - -- Lowercase, hyphenated, and specific: `event-sourcing`, `source-generators`, `zero-allocation`, - `msbuild-sdk`, `dotnet-aspire`, `csharp`, `roslyn`. -- 6–15 topics is the useful range: enough to describe the domain, few enough that the card's first - four chips are meaningful (cards render `tags.slice(0, 4)`). -- Prefer ecosystem-standard names (`dotnet`, `csharp`, `nuget`, `opentelemetry`) so cross-repo - searches behave predictably. -- Topics are the **only** way tags reach the site. There is no `tags` field in a catalogue record — do - not add one. - -## Stability signals to check against `status` - -| Signal | Implication | -| --- | --- | -| `archived: true` | `status` must be `archived` (and `supersededBy` when a successor exists) | -| No stable release, only `-prerelease.N` tags | `preview` at most | -| Latest NuGet version is stable and listed | `stable` is allowed | -| The README/repository presents the project as an experiment | Set `experimental: true` (it does not replace `status`, which stays the release channel) | -| NuGet `deprecated: true` | Report as `drift`/`upstream`; a deprecated package should not front a `stable` project without explanation | -| `default_branch` is not `main` | Docs aggregation produces nothing — a blocker for any project with `docs` | - -Note that the organisation's Changesets automation publishes `vX.Y.Z-prerelease.N` tags **without** -setting GitHub's `prerelease` flag, so version selection is semver-based; do not judge the channel -from the GitHub `prerelease` boolean alone. diff --git a/.agents/skills/project-manifest-reference/SKILL.md b/.agents/skills/project-manifest-reference/SKILL.md deleted file mode 100644 index d02ca06..0000000 --- a/.agents/skills/project-manifest-reference/SKILL.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -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. -category: purview-dev-website -roles: - - catalogue - - reference -tags: - - projects-yml - - zod - - schema ---- - -# 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. - -## Vocabularies (do not invent values) - -| Field | Allowed values | -| --- | --- | -| `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` — 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 -**flag, not a status value**: it never replaces `status`, which stays the project's release channel. - -## `projects[]` fields - -| Field | Required | Notes | -| --- | --- | --- | -| `id` | yes | Lowercase `[a-z0-9-]` slug; also the URL segment and the LLM bundle name | -| `name` | yes | Display name; **must slugify to `id` when `docs` is set**; must not start with `Purview ` | -| `shortDescription` | yes | One sentence; falls back to the GitHub description if empty, then to `name` | -| `description` | yes | Long description (2–4 sentences) | -| `origin` | yes | Why the project became reusable tooling | -| `useWhen` | yes | When it is the right choice | -| `avoidWhen` | yes | When it is the wrong choice | -| `repository` | yes | `owner/repository`; **`owner` must be `purview-dev`** for `projects[]` | -| `category` | yes | See vocabulary | -| `status` | yes | See vocabulary | -| `experimental` | no | Default `false`; marks an exploratory project (unstable API, no support promise). Orthogonal to `status`; invalid with `status: archived`. Displayed as its own status via `displayStatus()` | -| `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`; 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, 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//SKILL.md` (ADR 0010); mirrored to `/skills///` 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 | -| `useCases` | no | Default `[]`; at least one required for non-archived projects | -| `acknowledgments` | no | `{ name, url, description? }[]`; upstream work the project credits | -| `supersedes` / `supersededBy` | no | Known project ids; used for archived/successor messaging | -| `discussions` | no | **Detected, not authored**: the page links repository Discussions when the repository has them enabled (`hasDiscussions` in the release cache). Set it only to override — `false` opts a repository out | - -## `docs` (a discriminated union on `source`) - -| `source` | Fields | Behaviour | -| --- | --- | --- | -| `github-path` | `path` (required), plus `rootPage`, `readmeAsIndex`, `order`, `exclude`, `channels`, `redirects` | Walks `/**/*.md` at each channel's ref (default branch when no `channels`) | -| `wiki` | `rootPage`, `readmeAsIndex`, `order`, `exclude` | Shallow-clones `.wiki.git`; `_Sidebar.md` orders pages, `_Footer.md` is skipped. Single channel only | -| `readme` | none | Publishes `README.md` alone as `/docs//`. Single channel only | - -- `rootPage` names the markdown file that becomes the landing page (`index`). It may only select a - non-index page when the conventional root page is removed via `exclude` (the aggregation otherwise - raises `DocsValidationError`). A product wiki mirrored from `docs/wiki` uses `rootPage: Home.md`: the - wiki is plain Markdown with `Home.md` as its hub and `_Sidebar.md` as the whole navigation, and it - carries no site configuration — a repository that still ships one is a deviation the portal ignores, - not a requirement. -- `exclude` matches the **base file name** (not the repository path) and supports `*` wildcards. It is a - filter over the files the repository ships, so a pattern naming a file that has since been deleted is a - no-op, never a warning or a failure. -- `readmeAsIndex` uses the repository `README.md` as the landing page and cannot be combined with - `rootPage`; it aliases `readme` to `index`. -- `order` is an explicit list of page slugs, applied before the `_Sidebar.md` order. -- `redirects` maps moved slugs (`previous: current`) to keep old URLs alive on every channel that - publishes the tree. Prefer the repository's own `_redirects.yml` in its docs root (ADR 0013), which - lands with the move and is read per channel; the catalogue's pairs win when both name a slug. -- If `docs` is set but the aggregation yields no pages, `just data-sync` fails loudly. - -## `docs.channels` — live and prerelease documentation (ADR 0009) - -A project whose default branch is ahead of its latest release can publish two -views of its documentation. Channels are optional; omitting them keeps one -`live` channel on the default branch. - -```yaml -docs: - source: github-path - path: docs/wiki - rootPage: Getting-Started.md - channels: - live: - ref: latest-stable # newest non-prerelease release tag - prerelease: - ref: default # the repository's default branch -``` - -| Field | Meaning | -| --- | --- | -| `channels.live` / `channels.prerelease` | At most these two; unknown keys are rejected | -| `ref` | `default` (default branch), `latest-stable`, `latest-prerelease`, or any branch/tag/commit used verbatim. Defaults: `live` → `latest-stable`, `prerelease` → `default` | -| `path`, `rootPage`, `readmeAsIndex`, `order`, `exclude` | Optional per-channel overrides of the shared block (a tag's docs tree can differ from `main`) | - -- **`live` is the default channel** and owns `/docs//…`; `prerelease` is - served at `/docs//prerelease/…`. A prerelease-only project is the default - channel and serves its docs at the canonical URLs. -- `latest-stable` with no stable release → live follows the default branch - (warning). `latest-prerelease` with no tag → the channel is skipped. Two - channels on the same ref → the non-default one is dropped. -- **Promotion is automatic.** The prerelease channel is published only while a - prerelease version outranks the newest stable release, comparing GitHub - release tags with NuGet versions. Publishing `3.0.0` retires - `3.0.0-prerelease.N` docs on the next build; the channel returns with the next - prerelease. No manifest edit or PR is needed to stop publishing it. -- `wiki` and `readme` sources reject `channels`: they have a single version. -- Use-case `docsPage` deep links resolve against the **default** channel. - -## Loader-enforced rules (`loadProjects()`) - -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 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. -7. The returned list is sorted by `order` ascending. - -## Defaults applied by the loader - -`featured: false`, `order: 1000`, `packages: []`, `related: []`, `useCases: []`, -`acknowledgments: []`, `install: 'nuget'`, `experimental: false`. Derived values (`repoOwner`, -`repoName`, `sourceUrl`, `issuesUrl`, `discussions`, `discussionsUrl`, `changelogUrl`, `releasesUrl`) are computed, -never authored. - -## `externalProjects[]` fields - -Required: `id` (slug), `name`, `shortDescription`, `description`, `url` (valid URL), `category`. -Optional: `repository` (`owner/repo`, link target), `status`, `featured`, `order`. -Loader-enforced: a collaboration entry must **not** use the `purview-dev` owner (the manifest test -asserts that no `externalProjects` id starts with `purview-`). diff --git a/.agents/skills/purview-site-assessment/SKILL.md b/.agents/skills/purview-site-assessment/SKILL.md deleted file mode 100644 index 64afe45..0000000 --- a/.agents/skills/purview-site-assessment/SKILL.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -name: purview-site-assessment -description: Assess how well a Purview repository integrates with purview.dev and recommend fixes - runs a dependency-free script over the checkout (docs layout and hierarchy, root page, slugs and collisions, titles, broken links and images, ASCII-art and unlabelled Mermaid diagrams, purview:likec4 diagram pairs and their .c4 models, _redirects.yml and page moves in git history that left no redirect, agent skills front matter), cross-checks the site's catalogue entry and the live GitHub metadata, and produces a prioritised report with a concrete fix for each finding. Use before a repository joins purview.dev, after reorganising docs, when the site shows something wrong for the project, or when asked to audit or "assess" site integration. -license: MIT -metadata: - site: https://purview.dev - repository: purview-dev/purview-dev ---- - -# Assessing a repository's purview.dev integration - -The rules being checked are in `purview-site-docs` (how documentation is written) and -`purview-site-integration` (everything else the site reads). This skill finds where a repository -departs from them, ranks the findings, and proposes fixes. It **reports first and edits only when -asked**; and it never edits `purview-dev/purview-dev` — catalogue changes are proposed as a snippet for -the site maintainers. - -## 1. Fetch the catalogue entry (when the project is on the site) - -The entry carries contracts the repository must keep: the docs path, the root page, every use case's -`docsPage` deep link, and any redirects recorded on the site side. - -```shell -curl -sfL https://raw.githubusercontent.com/purview-dev/purview-dev/main/src/src/data/projects/.yml -o .purview-entry.yml -``` - -`` is normally the repository name (`unions`, `build-sdk`, `pm-skills`). A 404 means the project is -not on the site yet — assess without it and include the entry proposal from -`purview-site-integration` (references/catalogue-contract.md) in the report. Delete -`.purview-entry.yml` when done; never commit it. - -## 2. Run the script - -```shell -node /scripts/assess.mjs . --catalogue .purview-entry.yml -``` - -`` is where the skill was installed (for example `.agents/skills/purview-site-assessment`). -Options: `--docs ` to name the docs folder (default `docs/wiki`, then `docs`), `--json` for -machine-readable output. It reads files and `git log` only, needs Node 18+, and exits 1 when an -error-level finding exists, so it can also run in CI. - -Every rule id it prints is explained, with how to fix it, in [references/rules.md](references/rules.md). - -## 3. Check what the script cannot see - -```shell -gh api repos/purview-dev/ --jq '{description, topics, archived, default_branch, has_discussions}' -gh api "repos/purview-dev//releases?per_page=5" --jq '.[] | {tag_name, prerelease, published_at}' -``` - -| Check | Finding when it fails | -| -- | -- | -| 6–15 topics, lower-case and hyphenated | **META-001** warning — the card shows no or weak tags | -| a description that agrees with the entry's `shortDescription` | **META-002** info | -| `default_branch` is `main` (or the entry says otherwise) | **META-003** error — the docs and edit links follow it | -| at least one release, tagged `vX.Y.Z` or `vX.Y.Z-prerelease.N`, matching the package version | **META-004** warning — no version is shown | -| entry `status` agrees: stable registry version → `stable`; prerelease only → `preview`; archived repository → `archived` | **META-005** warning | -| the repository is not archived while the entry says `stable`/`preview` | **META-006** error | - -Then read what a script cannot judge: - -- **Hierarchy.** Do the topic folders match how a reader looks for things? Are pages in the folder - for their topic? A DOCS-003 finding needs a proposed tree, not just "add folders". -- **Diagrams.** For each DIAG-001 (ASCII art) and DIAG-008 (Mermaid in a text fence), decide whether it - is an architecture or flow diagram (→ LikeC4 model + Mermaid pair) or a small sketch (→ a labelled - ```` ```mermaid ```` fence is enough). Draft the model for the most important one. -- **README vs docs.** Does the README point into the docs, or duplicate them? -- **Skills.** Does each `description` say what the skill does *and when to use it*? - -## 4. Report - -Lead with a one-paragraph verdict, then the findings grouped by priority, each with the fix written -out — the redirect line, the renamed path, the converted fence — not just the rule: - -```markdown -# purview.dev integration: - - - -## Blockers (break the site's sync or build) -| Rule | Where | Problem | Fix | - -## Should fix (readers see something wrong) -| Rule | Where | Problem | Fix | - -## Improvements -| Rule | Where | Problem | Fix | - -## Proposed changes -- `docs/wiki/_redirects.yml` — the full file. -- The proposed docs tree, when DOCS-003 fired. -- One converted diagram pair (model + Mermaid), when DIAG-001/008 fired. -- The catalogue entry snippet for the site maintainers, when the entry is missing or drifts. -``` - -Blockers are every `error`; "should fix" is every `warning` plus META errors; improvements are -`info`. Collapse repeated findings into one row with a count and the list of places. - -## 5. Fixing (only when asked) - -Work in this order — each step changes what the next one sees: - -1. Blockers: unclosed fences, broken links and images, slug collisions, missing deep-link pages. -2. Redirects for moves already made (RED-004), before any further move. -3. Reorganise a flat tree into topic folders (`git mv`), adding each move to `_redirects.yml` and fixing - inbound links in the same commit. Leave catalogue deep-linked pages at the root. -4. Convert diagrams. Validate each model with `npx likec4 validate `. -5. Rerun the script; the report should show no errors, and only warnings you have explained. diff --git a/.agents/skills/purview-site-assessment/references/rules.md b/.agents/skills/purview-site-assessment/references/rules.md deleted file mode 100644 index 245e585..0000000 --- a/.agents/skills/purview-site-assessment/references/rules.md +++ /dev/null @@ -1,79 +0,0 @@ -# Assessment rules - -Severity is what the finding costs: an **error** breaks the site's sync or build, or loses content; a -**warning** is visible to readers; an **info** is an improvement. - -## Repository - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| REPO-001 | error | no `README.md` | add one: what it is, install, a minimal example, a link into the docs | - -## Documentation - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| DOCS-001 | warning / info | no docs folder; warning when the README is long enough to be a docs tree (≥ 8 `##` sections or ≥ 300 lines) | create `docs/wiki/` with topic folders; keep the README as the front door | -| DOCS-002 | warning | no `Home.md`/`index.md`/`README.md` at the docs root | add `Home.md`, or have the entry set `docs.rootPage` | -| DOCS-003 | warning / info | a flat folder of 7+ pages, or 10+ pages left at the root beside folders | group into topic folders; keep only the hub, getting-started and deep-linked pages at the root | -| DOCS-004 | info | folders more than two levels deep | flatten unless a sub-area has several pages of its own | -| DOCS-005 | error / warning | a path that reduces to an unpublishable slug (error), a name the site has to rewrite (warning), or a page or folder named `prerelease` (error) | letters, digits and single dashes | -| DOCS-006 | error | two files publish at the same URL | rename one | -| DOCS-007 | warning | no `#` title, or more than one | exactly one `# Title` first | -| DOCS-008 | error | a relative link to a file that does not exist | fix the path; it resolves from the page's own folder | -| DOCS-009 | error | a relative image that does not exist | fix the path or add the image | -| DOCS-010 | info | a fence with no language | label it | -| DOCS-011 | info / warning | no `_Sidebar.md` (info), a sidebar link to a missing page (warning), a page not in the sidebar (info) | list every page once, by section | -| DOCS-012 | info | `mkdocs.yml` present | delete it; the site ignores it | -| DOCS-013 | error | a code fence never closed | close it | - -## Diagrams - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| DIAG-001 | warning | ASCII-art diagram in a text fence | LikeC4 model + Mermaid fence in a `purview:likec4` block; legends become tables | -| DIAG-002 | info | a ```` ```mermaid ```` fence with no LikeC4 pair | fine as is; pair architecture and flow diagrams | -| DIAG-003 | warning | a bare ```` ```likec4 ```` fence — GitHub shows source | move the model to a `.c4` file and use a pair | -| DIAG-004 | error | a malformed pair: unclosed or orphan marker, no `file`, a model that is missing or outside the repository, or a `view` the model does not declare | fix the marker or the model; the site shows the Mermaid until then | -| DIAG-005 | warning | a model that imports or has no `specification` | one self-contained file per diagram | -| DIAG-006 | warning | a pair with no Mermaid fence, so GitHub shows nothing | add the Mermaid rendering between the markers | -| DIAG-007 | info | a pair that does not name its `view` | add `view=""` | -| DIAG-008 | warning | Mermaid source inside a ```` ```text ```` fence | label it ```` ```mermaid ````; both renderers draw it | - -The text-fence classifier skips folder trees (`├──`, `└──`), which are listings rather than diagrams. - -## Redirects - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| RED-001 | error | `_redirects.yml` unreadable, or a pair that cannot become a URL or points at itself — the site's sync fails | one `previous: current` per line under `redirects:` | -| RED-002 | warning | a destination that is not a page | point at the page's current path | -| RED-003 | info | a source that is still a page, so the redirect is inactive | expected while the move is unreleased | -| RED-004 | warning | a page renamed or deleted in git history with no redirect (here or in the catalogue's `docs.redirects`) | add the pair the finding suggests, unless the page was never published | -| RED-005 | warning | a chain (`a → b`, `b → c`) | point every old slug at the final page | - -RED-004 reads the last 300 commits that touched the docs folder. A page that existed only between two -site builds was never published; ignore those. - -## Catalogue (with `--catalogue`) - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| CAT-001 | error | the entry's `docs.path` (or `--docs`) has no Markdown | create it, or correct the entry | -| CAT-002 | error | the entry's `docs.rootPage` does not exist | restore the page, or change the entry in the same release | -| CAT-003 | error | a use case's `docsPage` is not a page — the site's build fails | keep the page at the root under its name, or move the deep link | -| CAT-004 | info | the entry carries `docs.redirects` | move them into `_redirects.yml`, then drop them from the entry | - -## Agent skills - -| Rule | Severity | Finding | Fix | -| -- | -- | -- | -- | -| SKILL-001 | error | a `skills//` folder with no `SKILL.md` | add it, or move the folder | -| SKILL-002 | error | no front matter, or no `name` / `description` | add them | -| SKILL-003 | error | `name` differs from the folder | make them equal | -| SKILL-004 | warning | `name` is not a lower-case slug | rename | -| SKILL-005 | error | `SKILL.md` links a file that is not in the skill folder | ship it beside `SKILL.md` — only the folder is installed | - -## Metadata (checked by hand with `gh`) - -META-001 … META-006 are listed in `SKILL.md`, step 3. diff --git a/.agents/skills/purview-site-assessment/scripts/assess.mjs b/.agents/skills/purview-site-assessment/scripts/assess.mjs deleted file mode 100644 index 644c8b5..0000000 --- a/.agents/skills/purview-site-assessment/scripts/assess.mjs +++ /dev/null @@ -1,669 +0,0 @@ -#!/usr/bin/env node -// Assess a repository's readiness for purview.dev. -// -// node assess.mjs [repository-root] [--docs ] [--catalogue ] [--json] -// -// Reads files only (plus `git log`, when git is available). No network, no -// dependencies, Node 18+. Exit code 1 when an error-level finding exists. -// -// `--catalogue` is a local copy of this project's purview.dev catalogue entry -// (purview-dev/purview-dev: src/src/data/projects/.yml). With it, the -// docs path, root page, deep links and catalogue redirects are checked too. -// -// The rules mirror what purview.dev's docs sync does (purview-dev/purview-dev, -// src/src/lib/docs/). Each finding names a rule id the SKILL.md explains. - -import { execFileSync } from 'node:child_process'; -import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; -import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path'; - -// --------------------------------------------------------------------------- -// Arguments -// --------------------------------------------------------------------------- - -const args = process.argv.slice(2); -const json = args.includes('--json'); -const option = (name) => { - const index = args.indexOf(name); - return index >= 0 ? args[index + 1] : undefined; -}; -const VALUE_OPTIONS = new Set(['--docs', '--catalogue']); -const root = resolve( - args.find((arg, index) => !arg.startsWith('--') && !VALUE_OPTIONS.has(args[index - 1])) ?? '.', -); -const cataloguePath = option('--catalogue'); - -/** - * The few catalogue fields the checks need, read line by line from the entry's - * fixed layout (no YAML dependency): docs source/path/rootPage, docs.redirects - * and every use case's docsPage. - */ -function readCatalogueEntry(path) { - const lines = readFileSync(path, 'utf8').replace(/\r\n?/g, '\n').split('\n'); - const entry = { source: undefined, path: undefined, rootPage: undefined, redirects: {}, docsPages: [] }; - let section = null; - let sectionIndent = 0; - for (const line of lines) { - const indent = line.length - line.trimStart().length; - const text = line.trim().replace(/\s+#.*$/, ''); - if (text === '' || text.startsWith('#')) continue; - if (indent === 0) { - section = text === 'docs:' ? 'docs' : null; - continue; - } - if (section === 'docs' && text === 'redirects:') { - section = 'redirects'; - sectionIndent = indent; - continue; - } - if (section === 'redirects') { - if (indent <= sectionIndent) { - section = 'docs'; - } else { - const pair = /^["']?([^"':]+)["']?\s*:\s*["']?([^"']+?)["']?$/.exec(text); - if (pair) entry.redirects[pair[1].trim()] = pair[2].trim(); - continue; - } - } - if (section === 'docs') { - const field = /^(source|path|rootPage):\s*["']?([^"']+?)["']?$/.exec(text); - if (field && indent === 2) entry[field[1]] = field[2]; - } - const deepLink = /^docsPage:\s*["']?([^"'\s]+)["']?$/.exec(text); - if (deepLink) entry.docsPages.push(deepLink[1]); - } - return entry; -} - -const catalogue = cataloguePath ? readCatalogueEntry(resolve(cataloguePath)) : null; -const docsOverride = option('--docs') ?? (catalogue?.source === 'github-path' ? catalogue.path : undefined); - -/** @type {{ id: string; severity: 'error' | 'warning' | 'info'; file?: string; line?: number; message: string; fix: string }[]} */ -const findings = []; -const report = (id, severity, file, line, message, fix) => - findings.push({ id, severity, file, line, message, fix }); - -// --------------------------------------------------------------------------- -// File helpers -// --------------------------------------------------------------------------- - -const toPosix = (path) => path.split(sep).join('/'); -const repoPath = (absolute) => toPosix(relative(root, absolute)); -const read = (absolute) => readFileSync(absolute, 'utf8').replace(/\r\n?/g, '\n'); -const IGNORED_DIRS = new Set(['.git', 'node_modules', 'bin', 'obj', 'dist', '.vs', '.idea', 'artifacts']); - -function walk(directory, predicate, found = []) { - for (const entry of readdirSync(directory, { withFileTypes: true })) { - const absolute = join(directory, entry.name); - if (entry.isDirectory()) { - if (!IGNORED_DIRS.has(entry.name)) { - walk(absolute, predicate, found); - } - } else if (predicate(absolute)) { - found.push(absolute); - } - } - return found; -} - -// --------------------------------------------------------------------------- -// Slugs — the same reduction purview.dev applies (src/src/lib/docs/links.ts) -// --------------------------------------------------------------------------- - -const reduceSegment = (segment) => - segment - .replace(/[^a-zA-Z0-9-]+/g, '-') - .replace(/^-+|-+$/g, '') - .toLowerCase(); - -function docSlug(relativePath) { - const segments = relativePath.split('/').filter((segment) => segment !== '' && segment !== '.'); - return segments - .map((segment, index) => { - if (index < segments.length - 1) { - return reduceSegment(segment); - } - const name = segment.replace(/\.(md|mdx)$/i, ''); - return segments.length > 1 && /^readme$/i.test(name) ? 'index' : reduceSegment(name); - }) - .join('/'); -} - -const SAFE_SEGMENT = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/; -const isIndexName = (name) => /^(home|index|readme)\.md$/i.test(name); - -// --------------------------------------------------------------------------- -// Markdown helpers -// --------------------------------------------------------------------------- - -/** Lines with fenced code blanked (fences reported separately), so headings and links are read from prose only. */ -function scanFences(text) { - const lines = text.split('\n'); - const fences = []; - const prose = [...lines]; - let open = null; - lines.forEach((line, index) => { - const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line); - if (!open && match) { - open = { start: index, run: match[1], info: match[2].trim(), body: [] }; - prose[index] = ''; - return; - } - if (open) { - if (match && match[1][0] === open.run[0] && match[1].length >= open.run.length && match[2].trim() === '') { - fences.push({ ...open, end: index }); - open = null; - } else { - open.body.push(line); - } - prose[index] = ''; - } - }); - if (open) { - fences.push({ ...open, end: lines.length - 1, unclosed: true }); - } - return { lines, prose, fences }; -} - -const stripInlineCode = (line) => line.replace(/`+[^`]*`+/g, ''); - -const MERMAID_START = /^\s*(flowchart|graph|sequenceDiagram|classDiagram|stateDiagram(-v2)?|erDiagram|gantt|journey|mindmap|timeline|C4Context|C4Container|C4Component|gitGraph|pie|quadrantChart|block-beta|architecture-beta)\b/; - -/** - * What an unlabelled or `text` fence holds: `mermaid` source (the old - * "Mermaid goes in a text block" convention), a folder `tree` (a listing, not a - * diagram), an ASCII-art `diagram`, or null for ordinary text. - */ -function classifyTextFence(fence) { - const language = fence.info.split(/\s+/)[0].toLowerCase(); - if (!['', 'text', 'txt', 'plaintext', 'ascii', 'none'].includes(language)) { - return null; - } - const body = fence.body.filter((line) => line.trim() !== ''); - if (body.length === 0) { - return null; - } - if (MERMAID_START.test(body[0])) { - return 'mermaid'; - } - const treeLines = body.filter((line) => /[├└]──|^\s*│|^\s*[\w.<>-]+\/\s*$/.test(line)).length; - if (treeLines >= Math.ceil(body.length / 2)) { - return 'tree'; - } - if (body.length < 3) { - return null; - } - const boxDrawing = body.some((line) => /[┌┐┘┬┴┼═║╔╗╚╝▶▼◀▲]/.test(line)); - const arrows = body.filter((line) => /(-{1,}>|<-{1,}|={1,}>|\+-{2,}|-{3,}\+|→|↓)/.test(line)).length; - const connectors = body.filter( - (line) => /^\s*[|^v+]\s*($|\s{2,})|\s{2,}[|^v+]\s*$/.test(line) || /\s[|^]\s{3,}[|^]/.test(line), - ).length; - return boxDrawing || (arrows >= 1 && connectors >= 1) || arrows >= 3 ? 'diagram' : null; -} - -// --------------------------------------------------------------------------- -// Diagram pairs — mirrors src/src/lib/docs/diagrams.ts -// --------------------------------------------------------------------------- - -const DIAGRAM_OPEN = /^ {0,3}\s*$/; -const DIAGRAM_CLOSE = /^ {0,3}\s*$/; - -function parseOptions(source) { - const options = {}; - for (const match of source.matchAll(/([A-Za-z][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+))/g)) { - options[match[1]] = match[2] ?? match[3] ?? match[4] ?? ''; - } - return options; -} - -function declaredViews(source) { - return new Set( - [...source.matchAll(/(?:^|[\s{;])(?:dynamic\s+|deployment\s+)?view\s+([A-Za-z_][\w-]*)/g)].map((m) => m[1]), - ); -} - -function checkDiagramBlocks(file, scan) { - const page = repoPath(file); - const inFence = new Set(); - for (const fence of scan.fences) { - for (let index = fence.start; index <= fence.end; index++) inFence.add(index); - } - const blocks = []; - let open = null; - scan.lines.forEach((line, index) => { - if (inFence.has(index)) return; - const opening = DIAGRAM_OPEN.exec(line); - if (opening) { - if (open) { - report('DIAG-004', 'error', page, open.line, 'A purview:likec4 block is not closed before the next one opens.', 'Add `` after the Mermaid fence.'); - } - open = { line: index + 1, start: index, options: parseOptions(opening[1]) }; - } else if (DIAGRAM_CLOSE.test(line)) { - if (!open) { - report('DIAG-004', 'error', page, index + 1, 'A closing purview:likec4 marker has no opening marker.', 'Remove it, or add the opening marker with file="…" and view="…".'); - } else { - blocks.push({ ...open, end: index }); - open = null; - } - } - }); - if (open) { - report('DIAG-004', 'error', page, open.line, 'A purview:likec4 block is never closed.', 'Add `` after the Mermaid fence.'); - } - - for (const block of blocks) { - const inner = scan.fences.filter((fence) => fence.start > block.start && fence.end < block.end); - if (!inner.some((fence) => fence.info.split(/\s+/)[0] === 'mermaid')) { - report('DIAG-006', 'warning', page, block.line, 'The diagram block has no ```mermaid fence, so GitHub readers see no diagram.', 'Put the Mermaid rendering of the view between the markers.'); - } - const file = block.options.file; - if (!file) { - report('DIAG-004', 'error', page, block.line, 'The purview:likec4 marker has no file="…"; the site will show the Mermaid instead.', 'Add file="./diagrams/.c4" (relative to the page).'); - continue; - } - const target = file.startsWith('/') ? posix.normalize(file.slice(1)) : posix.normalize(posix.join(posix.dirname(page), file)); - if (target.startsWith('..')) { - report('DIAG-004', 'error', page, block.line, `file="${file}" leaves the repository.`, 'Keep the model inside the repository.'); - continue; - } - const absolute = join(root, target); - if (!existsSync(absolute)) { - report('DIAG-004', 'error', page, block.line, `file="${file}" does not exist (${target}); the site will show the Mermaid instead.`, 'Create the model or fix the path (it is relative to the page).'); - continue; - } - const model = read(absolute); - const views = declaredViews(model); - if (block.options.view && !views.has(block.options.view)) { - report('DIAG-004', 'error', page, block.line, `${target} declares no view "${block.options.view}" (declared: ${[...views].join(', ') || 'none'}).`, 'Name an existing view, or add it to the model.'); - } else if (!block.options.view) { - report('DIAG-007', 'info', page, block.line, 'The diagram block does not name a view, so the first view in the model is shown.', 'Add view="" so a new view added first does not change this page.'); - } - if (/^\s*import\s/m.test(model) || !/\bspecification\s*\{/.test(model)) { - report('DIAG-005', 'warning', target, 1, 'The model is not self-contained (it imports, or has no specification block). The site compiles each file on its own.', 'Give the file its own `specification`, `model` and `views`, and remove imports.'); - } - } - return blocks; -} - -// --------------------------------------------------------------------------- -// `_redirects.yml` — a tolerant reader for the simple shape the site documents -// --------------------------------------------------------------------------- - -function parseRedirects(text) { - const pairs = []; - const errors = []; - text.split('\n').forEach((raw, index) => { - const line = raw.replace(/\s+#.*$/, '').replace(/^#.*$/, ''); - if (line.trim() === '' || /^redirects:\s*$/.test(line.trim())) return; - const match = /^\s*(?:"([^"]+)"|'([^']+)'|([^:#\s][^:#]*?))\s*:\s*(?:"([^"]*)"|'([^']*)'|(.*?))\s*$/.exec(line); - if (!match) { - errors.push({ line: index + 1, message: `cannot read "${raw.trim()}" as \`previous: current\`` }); - return; - } - const from = match[1] ?? match[2] ?? match[3]; - const to = match[4] ?? match[5] ?? match[6]; - if (!to) { - errors.push({ line: index + 1, message: `"${from}" has no destination` }); - return; - } - pairs.push({ line: index + 1, from, to }); - }); - return { pairs, errors }; -} - -const redirectSlug = (value) => { - const trimmed = value.trim().replace(/^\/+|\/+$/g, ''); - return docSlug(/\.(md|mdx)$/i.test(trimmed) ? trimmed : `${trimmed}.md`); -}; - -// --------------------------------------------------------------------------- -// Repository-level checks -// --------------------------------------------------------------------------- - -if (!existsSync(root) || !statSync(root).isDirectory()) { - console.error(`Not a directory: ${root}`); - process.exit(2); -} - -const readmePath = ['README.md', 'readme.md', 'Readme.md'].map((name) => join(root, name)).find(existsSync); -if (!readmePath) { - report('REPO-001', 'error', undefined, undefined, 'No README.md at the repository root.', 'Add one: what the project is, install, a minimal example, a link into the docs.'); -} -for (const site of ['mkdocs.yml', 'mkdocs.yaml', 'docs/mkdocs.yml', 'docs/wiki/mkdocs.yml']) { - if (existsSync(join(root, site))) { - report('DOCS-012', 'info', site, undefined, `${site} is a site configuration purview.dev ignores.`, 'Delete it; the site reads the Markdown directly. Rewrite any Material-only markup it enabled as plain Markdown.'); - } -} - -// --------------------------------------------------------------------------- -// Documentation -// --------------------------------------------------------------------------- - -const docsCandidates = docsOverride ? [docsOverride] : ['docs/wiki', 'docs']; -const docsRootRelative = docsCandidates.find((candidate) => { - const absolute = join(root, candidate); - return existsSync(absolute) && statSync(absolute).isDirectory() && walk(absolute, (path) => path.endsWith('.md')).length > 0; -}); - -if (docsOverride && !docsRootRelative) { - report('CAT-001', 'error', docsOverride, undefined, `The docs folder "${docsOverride}" has no Markdown${catalogue ? " (the catalogue's docs.path)" : ''}; the site publishes nothing.`, 'Create the folder, or correct docs.path.'); -} - -/** Every Markdown file the checks read: the docs tree and the README. */ -const markdownFiles = []; -let pageSlugs = new Set(); - -if (!docsRootRelative) { - const readme = readmePath ? read(readmePath) : ''; - const sections = (readme.match(/^## /gm) ?? []).length; - const lines = readme.split('\n').length; - if (sections >= 8 || lines >= 300) { - report('DOCS-001', 'warning', 'README.md', undefined, `No docs folder, and the README has ${sections} sections over ${lines} lines — it is a documentation tree in one file.`, 'Move the reference material into docs/wiki/ topic folders (see purview-site-docs) and keep the README as the front door.'); - } else { - report('DOCS-001', 'info', undefined, undefined, 'No docs folder; purview.dev would publish README.md as the only page (docs.source: readme).', 'Fine for a small project. Create docs/wiki/ once the README outgrows one page.'); - } - if (readmePath) markdownFiles.push(readmePath); -} else { - const docsRoot = join(root, docsRootRelative); - const docFiles = walk(docsRoot, (path) => path.endsWith('.md')); - const relativeToDocs = (absolute) => toPosix(relative(docsRoot, absolute)); - const pages = docFiles.filter((path) => !/^_(Sidebar|Footer)\.md$/i.test(basename(path))); - markdownFiles.push(...pages); - if (readmePath && !pages.includes(readmePath)) markdownFiles.push(readmePath); - - // Root page: the catalogue's rootPage when it names one, else the conventional index. - const rootFiles = pages.filter((path) => dirname(path) === docsRoot); - const configuredRoot = catalogue?.rootPage - ? pages.find((path) => relativeToDocs(path).toLowerCase() === catalogue.rootPage.toLowerCase()) - : undefined; - if (catalogue?.rootPage && !configuredRoot) { - report('CAT-002', 'error', `${docsRootRelative}/${catalogue.rootPage}`, undefined, `The catalogue's docs.rootPage "${catalogue.rootPage}" does not exist; the site's sync fails.`, 'Restore the page, or ask the site maintainers to change docs.rootPage in the same release.'); - } - const index = configuredRoot ?? rootFiles.find((path) => isIndexName(basename(path))); - if (!index) { - report('DOCS-002', 'warning', docsRootRelative, undefined, 'No Home.md, index.md or README.md at the docs root.', 'Add Home.md as the hub, or have the catalogue entry name docs.rootPage.'); - } - - // Shape: flat corpus, depth. - const folders = new Set(pages.map((path) => dirname(relativeToDocs(path))).filter((folder) => folder !== '.')); - if (folders.size === 0 && pages.length >= 7) { - report('DOCS-003', 'warning', docsRootRelative, undefined, `${pages.length} pages in one flat folder.`, 'Group them into lower-case topic folders (guide/, configuration/, reference/); keep only the hub, getting-started and catalogue deep-linked pages at the root; add each move to _redirects.yml.'); - } else if (rootFiles.length >= 10 && folders.size > 0) { - report('DOCS-003', 'info', docsRootRelative, undefined, `${rootFiles.length} pages are still at the docs root beside ${folders.size} folder(s).`, 'Move pages into their topic folder unless the catalogue deep-links them (useCases[].docsPage).'); - } - for (const folder of folders) { - if (folder.split('/').length > 2) { - report('DOCS-004', 'info', `${docsRootRelative}/${folder}`, undefined, 'Folders nested more than two levels deep.', 'One level of topic folders is the default; nest only for a sub-area with several pages of its own.'); - } - } - - // Names and slugs. - const bySlug = new Map(); - for (const path of pages) { - const relativePath = relativeToDocs(path); - const slug = path === index ? 'index' : docSlug(relativePath); - const segments = slug.split('/'); - if (segments.some((segment) => !SAFE_SEGMENT.test(segment))) { - report('DOCS-005', 'error', repoPath(path), undefined, `"${relativePath}" reduces to the unpublishable slug "${slug}"; the site's sync fails on it.`, 'Rename every folder and the file with letters, digits and dashes.'); - } else { - const unsafe = relativePath.replace(/\.md$/i, '').split('/').filter((segment) => !/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(segment)); - if (unsafe.length > 0) { - report('DOCS-005', 'warning', repoPath(path), undefined, `"${unsafe.join('/')}" is rewritten to publish (${slug}).`, 'Rename with letters, digits and single dashes so the file name and the URL agree.'); - } - } - if (slug === 'prerelease' || slug.startsWith('prerelease/')) { - report('DOCS-005', 'error', repoPath(path), undefined, '"prerelease" is reserved for the prerelease documentation channel.', 'Rename the page or folder.'); - } - const existing = bySlug.get(slug); - if (existing) { - report('DOCS-006', 'error', repoPath(path), undefined, `Publishes at the same URL as ${repoPath(existing)} (${slug}).`, 'Rename one of them.'); - } else { - bySlug.set(slug, path); - } - } - pageSlugs = new Set(bySlug.keys()); - - // Catalogue deep links: a use case's docsPage that is not a page fails the site's catalogue check. - for (const docsPage of catalogue?.docsPages ?? []) { - if (!pageSlugs.has(docsPage)) { - report('CAT-003', 'error', docsRootRelative, undefined, `The catalogue deep-links "${docsPage}" (useCases[].docsPage), which is not a page here; the site's build fails.`, 'Keep that page at the docs root under its name, or ask the site maintainers to update the use case in the same release.'); - } - } - if (catalogue && Object.keys(catalogue.redirects).length > 0) { - report('CAT-004', 'info', `${docsRootRelative}/_redirects.yml`, undefined, `The catalogue entry carries ${Object.keys(catalogue.redirects).length} docs.redirects pair(s).`, 'Move them into _redirects.yml here, then ask the site maintainers to drop them from the entry.'); - } - - // Sidebar. - const sidebar = docFiles.find((path) => /^_Sidebar\.md$/i.test(basename(path))); - if (!sidebar && pages.length > 3) { - report('DOCS-011', 'info', docsRootRelative, undefined, 'No _Sidebar.md; pages are ordered alphabetically on the site.', 'Add _Sidebar.md listing every page once, grouped by section, in reading order.'); - } else if (sidebar) { - const listed = new Set(); - const text = read(sidebar); - for (const match of text.matchAll(/\]\(([^)\s#]+\.md)(?:#[^)]*)?\)/g)) { - const target = posix.normalize(match[1]); - listed.add(target.toLowerCase()); - if (!existsSync(join(docsRoot, target))) { - report('DOCS-011', 'warning', repoPath(sidebar), undefined, `Lists ${match[1]}, which does not exist.`, 'Fix or remove the entry.'); - } - } - for (const path of pages) { - const relativePath = relativeToDocs(path); - if (path !== index && !listed.has(relativePath.toLowerCase())) { - report('DOCS-011', 'info', repoPath(path), undefined, 'Not listed in _Sidebar.md, so it sorts last on the site.', 'Add it to _Sidebar.md under its section.'); - } - } - } - - // Redirects. - const redirectsFile = join(docsRoot, '_redirects.yml'); - const redirected = new Set(); - if (existsSync(redirectsFile)) { - const { pairs, errors } = parseRedirects(read(redirectsFile)); - for (const error of errors) { - report('RED-001', 'error', repoPath(redirectsFile), error.line, `${error.message}; the site's sync fails on an unreadable redirects file.`, 'Use one `previous: current` pair per line under `redirects:`.'); - } - for (const pair of pairs) { - const from = redirectSlug(pair.from); - const to = redirectSlug(pair.to); - redirected.add(from); - if (from.split('/').some((segment) => !SAFE_SEGMENT.test(segment)) || to.split('/').some((segment) => !SAFE_SEGMENT.test(segment))) { - report('RED-001', 'error', repoPath(redirectsFile), pair.line, `"${pair.from}: ${pair.to}" does not reduce to publishable slugs.`, 'Use slugs or Markdown paths from the docs root.'); - } else if (from === to) { - report('RED-001', 'error', repoPath(redirectsFile), pair.line, `"${pair.from}" redirects to itself.`, 'Remove the line.'); - } else if (!pageSlugs.has(to)) { - report('RED-002', 'warning', repoPath(redirectsFile), pair.line, `"${pair.from}" points at "${to}", which is not a page; no redirect is written.`, 'Point it at the page\'s current path.'); - } else if (pageSlugs.has(from)) { - report('RED-003', 'info', repoPath(redirectsFile), pair.line, `"${from}" is still a page, so this redirect stays inactive.`, 'Expected only while the move is unreleased; otherwise remove the old page.'); - } - } - const sources = new Set(pairs.map((pair) => redirectSlug(pair.from))); - for (const pair of pairs) { - if (sources.has(redirectSlug(pair.to))) { - report('RED-005', 'warning', repoPath(redirectsFile), pair.line, `"${pair.from}" points at "${pair.to}", which itself redirects.`, 'Point every old slug at the final page.'); - } - } - } - - // Moves in git history that left no redirect (the catalogue's docs.redirects counts, when given). - for (const from of Object.keys(catalogue?.redirects ?? {})) { - redirected.add(redirectSlug(from)); - } - try { - const log = execFileSync( - 'git', - ['-C', root, 'log', '--max-count=300', '--find-renames', '--diff-filter=RD', '--name-status', '--format=', '--', docsRootRelative], - { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }, - ); - const missing = new Map(); - const fromDocs = (path) => path.slice(docsRootRelative.length + 1); - for (const line of log.split('\n')) { - const [status, oldPath, newPath] = line.split('\t'); - if (!status || !oldPath || !oldPath.endsWith('.md') || !oldPath.startsWith(`${docsRootRelative}/`)) continue; - if (/^_/.test(basename(oldPath)) || isIndexName(basename(oldPath))) continue; - const oldSlug = docSlug(fromDocs(oldPath)); - if (pageSlugs.has(oldSlug) || redirected.has(oldSlug) || missing.has(oldSlug)) continue; - const newSlug = - status.startsWith('R') && newPath?.startsWith(`${docsRootRelative}/`) ? docSlug(fromDocs(newPath)) : undefined; - missing.set(oldSlug, newSlug && pageSlugs.has(newSlug) ? newSlug : undefined); - } - for (const [slug, current] of missing) { - report( - 'RED-004', - 'warning', - `${docsRootRelative}/_redirects.yml`, - undefined, - current - ? `"${slug}" was renamed to "${current}" in git history and has no redirect.` - : `"${slug}" was moved or deleted in git history and has no redirect.`, - current - ? `Add \`${slug}: ${current}\` to _redirects.yml (unless it was never published).` - : `If it was published, add \`${slug}: \` to _redirects.yml. Pass --catalogue to count the site's docs.redirects.`, - ); - } - } catch { - // Not a git checkout, or git is unavailable: the history check is best-effort. - } -} - -// --------------------------------------------------------------------------- -// Per-page checks (docs pages and the README) -// --------------------------------------------------------------------------- - -for (const file of markdownFiles) { - const page = repoPath(file); - const scan = scanFences(read(file)); - - const titles = []; - scan.prose.forEach((line, index) => { - if (/^#\s+\S/.test(line)) titles.push(index + 1); - }); - if (titles.length === 0) { - report('DOCS-007', 'warning', page, 1, 'No `# Title` heading; the site falls back to the file name.', 'Open the page with exactly one `# Title`.'); - } else if (titles.length > 1) { - report('DOCS-007', 'warning', page, titles[1], `${titles.length} \`#\` headings; the site keeps the first as the title and demotes the rest.`, 'Use one `#` title and `##` for sections.'); - } - - scan.prose.forEach((rawLine, index) => { - const line = stripInlineCode(rawLine); - for (const match of line.matchAll(/(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) { - const target = match[2]; - if (/^(?:[a-z][a-z0-9+.-]*:|#|\/\/|<)/i.test(target)) continue; - const path = decodeURI(target.split('#')[0].split('?')[0]); - if (!path) continue; - const absolute = path.startsWith('/') ? join(root, path) : join(dirname(file), path); - if (!existsSync(absolute)) { - const isImage = match[1] === '!'; - report(isImage ? 'DOCS-009' : 'DOCS-008', 'error', page, index + 1, `${isImage ? 'Image' : 'Link'} target ${target} does not exist.`, 'Fix the path — it resolves from the folder this page is in.'); - } - } - }); - - for (const fence of scan.fences) { - const language = fence.info.split(/\s+/)[0]; - if (fence.unclosed) { - report('DOCS-013', 'error', page, fence.start + 1, 'A code fence is never closed; everything after it renders as code.', `Close it with ${fence.run}.`); - } - if (!language) { - report('DOCS-010', 'info', page, fence.start + 1, 'A code fence has no language.', 'Label it (`csharp`, `json`, `shell`, `text`).'); - } - const kind = classifyTextFence(fence); - if (kind === 'diagram') { - report('DIAG-001', 'warning', page, fence.start + 1, 'An ASCII-art diagram.', 'Replace it with a LikeC4 model plus a Mermaid fence in a purview:likec4 block (purview-site-docs, references/diagrams.md). Move any legend into a table.'); - } else if (kind === 'mermaid') { - report('DIAG-008', 'warning', page, fence.start + 1, 'Mermaid source in a text fence, so neither GitHub nor the site draws it.', 'Label the fence ```mermaid — both render it — and, for an architecture or flow diagram, pair it with a LikeC4 model in a purview:likec4 block.'); - } - } - - const blocks = checkDiagramBlocks(file, scan); - const insideBlock = (line) => blocks.some((block) => line > block.start && line < block.end); - for (const fence of scan.fences) { - const language = fence.info.split(/\s+/)[0]; - if (insideBlock(fence.start)) continue; - if (language === 'likec4' || language === 'c4') { - if (language === 'likec4') { - report('DIAG-003', 'warning', page, fence.start + 1, 'A bare ```likec4 fence: GitHub shows it as source code.', 'Move the model to a .c4 file and use a purview:likec4 block with a Mermaid fence for GitHub.'); - } - } else if (language === 'mermaid') { - report('DIAG-002', 'info', page, fence.start + 1, 'A Mermaid diagram with no LikeC4 pair. Both GitHub and the site render it.', 'Optional: for an architecture or flow diagram, add a LikeC4 model and wrap this fence in a purview:likec4 block.'); - } - } -} - -// --------------------------------------------------------------------------- -// Agent skills -// --------------------------------------------------------------------------- - -const skillsRoot = join(root, 'skills'); -if (existsSync(skillsRoot) && statSync(skillsRoot).isDirectory()) { - for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) { - if (!entry.isDirectory()) continue; - const folder = `skills/${entry.name}`; - const skillFile = join(skillsRoot, entry.name, 'SKILL.md'); - if (!existsSync(skillFile)) { - report('SKILL-001', 'error', folder, undefined, 'A skills folder with no SKILL.md.', 'Add SKILL.md, or move the folder out of skills/.'); - continue; - } - const text = read(skillFile); - const frontMatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1]; - if (!frontMatter) { - report('SKILL-002', 'error', `${folder}/SKILL.md`, 1, 'No YAML front matter.', 'Start the file with `---`, `name:` and `description:`, then `---`.'); - continue; - } - const name = /^name:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(frontMatter)?.[1]; - const description = /^description:\s*(.*)$/m.exec(frontMatter)?.[1]; - if (!name) { - report('SKILL-002', 'error', `${folder}/SKILL.md`, 1, 'Front matter has no `name`.', `Add \`name: ${entry.name}\`.`); - } else if (name !== entry.name) { - report('SKILL-003', 'error', `${folder}/SKILL.md`, 1, `name "${name}" does not match the folder "${entry.name}".`, 'Make them equal; the CLI and the site key the skill on the folder.'); - } - if (name && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) { - report('SKILL-004', 'warning', `${folder}/SKILL.md`, 1, `name "${name}" is not a lower-case slug.`, 'Use lower-case letters, digits and dashes.'); - } - if (description === undefined || description.trim() === '') { - report('SKILL-002', 'error', `${folder}/SKILL.md`, 1, 'Front matter has no `description`.', 'Say what the skill does and when to use it, in one paragraph.'); - } - const scan = scanFences(text); - scan.prose.forEach((line, index) => { - for (const match of stripInlineCode(line).matchAll(/\]\(([^)\s#:]+)(?:#[^)]*)?\)/g)) { - if (!existsSync(join(skillsRoot, entry.name, match[1]))) { - report('SKILL-005', 'error', `${folder}/SKILL.md`, index + 1, `Links ${match[1]}, which is not in the skill folder.`, 'Ship the file beside SKILL.md, or fix the link.'); - } - } - }); - } -} - -// --------------------------------------------------------------------------- -// Report -// --------------------------------------------------------------------------- - -const order = { error: 0, warning: 1, info: 2 }; -findings.sort((a, b) => order[a.severity] - order[b.severity] || a.id.localeCompare(b.id) || String(a.file).localeCompare(String(b.file))); -const counts = { error: 0, warning: 0, info: 0 }; -for (const finding of findings) counts[finding.severity] += 1; - -if (json) { - console.log(JSON.stringify({ root, docsRoot: docsRootRelative ?? null, pages: pageSlugs.size, counts, findings }, null, 2)); -} else { - const lines = [ - `# purview.dev assessment: ${basename(root)}`, - '', - `Docs root: ${docsRootRelative ?? '(none — README only)'} · pages: ${pageSlugs.size || (readmePath ? 1 : 0)} · ` + - `${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} note(s)`, - '', - ]; - if (findings.length === 0) { - lines.push('No findings.'); - } else { - lines.push('| Severity | Rule | Where | Finding | Fix |', '| -- | -- | -- | -- | -- |'); - const cell = (value) => String(value).replace(/\|/g, '\\|').replace(/\n/g, ' '); - for (const finding of findings) { - const where = finding.file ? `${finding.file}${finding.line ? `:${finding.line}` : ''}` : '—'; - lines.push(`| ${finding.severity} | ${finding.id} | ${cell(where)} | ${cell(finding.message)} | ${cell(finding.fix)} |`); - } - } - console.log(lines.join('\n')); -} - -process.exit(counts.error > 0 ? 1 : 0); diff --git a/.agents/skills/purview-site-docs/SKILL.md b/.agents/skills/purview-site-docs/SKILL.md deleted file mode 100644 index 9e916d3..0000000 --- a/.agents/skills/purview-site-docs/SKILL.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -name: purview-site-docs -description: Write and reorganise a Purview repository's documentation so purview.dev publishes it cleanly - a hierarchical docs/wiki tree (topic folders, not one flat folder), one H1 per page, relative links that resolve from the page they are in, GitHub alerts, labelled fences, LikeC4 diagrams paired with a Mermaid fence so GitHub and the site each render the one they can, and a _redirects.yml in the docs root that keeps old URLs working when pages move. Use when adding, moving, renaming or splitting documentation pages, when drawing a diagram (never ASCII art), when a docs folder has grown flat, or when asked how a page will look on purview.dev. -license: MIT -metadata: - site: https://purview.dev - repository: purview-dev/purview-dev ---- - -# Documentation that publishes cleanly on purview.dev - -purview.dev does not host your documentation; it **reads it out of your repository** at build time -and publishes it at `https://purview.dev/docs//`. The same Markdown is also read on -GitHub. Every rule here keeps one file correct in both places, with no site configuration in your -repository. - -The site's catalogue entry for your project (in `purview-dev/purview-dev`, -`src/src/data/projects/.yml`) decides **which** files are read — `docs.source`, `docs.path`, -`docs.rootPage`, `docs.exclude`. This repository decides **what they say and where they sit**. - -## The rules - -| # | Rule | Why | -| - | - | - | -| 1 | Docs live in `docs/wiki/` (or `docs/`), as plain `.md` files. No `mkdocs.yml`, theme or plugin list. | The site renders; the repository only writes. A site file is ignored and drifts. | -| 2 | **Hierarchical, not flat**: one lower-case topic folder per area (`guide/`, `configuration/`, `reference/`). Only the landing page, `Home.md`, `_Sidebar.md` and pages the catalogue deep-links stay at the root. | A folder is a sidebar group and a URL segment: `guide/Getting-Started.md` → `/docs//guide/getting-started/`. Twenty files in one folder is a list nobody scans. | -| 3 | File and folder names: letters, digits, single dashes (`Custom-Rules.md`). | The path *is* the URL, lower-cased; anything else is rewritten, and a name that reduces to nothing fails the sync. | -| 4 | Exactly one `# Title` per page, first; then one paragraph saying what the page answers. | The H1 is the page title and sidebar label; the first paragraph is the meta description (160 chars). | -| 5 | Relative links, resolved from the file they are in (`../reference/Options.md`, `Sibling.md#anchor`). | The site rewrites them to its own URLs; a link outside the docs folder becomes a GitHub link. | -| 6 | Relative images (`./images/flow.png`); badges may stay absolute. | Relative images are served from GitHub raw at the channel's ref. | -| 7 | Every fence declares a language (`csharp`, `json`, `shell`, `text`). | An unlabelled fence loses highlighting on both sides. | -| 8 | Callouts use GitHub alerts: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`. | They become Starlight asides on the site and render natively on GitHub. | -| 9 | **Diagrams are never ASCII art.** A diagram is a LikeC4 model paired with a Mermaid fence (below). | ASCII art is unreadable on a phone, unsearchable, and drifts silently. | -| 10 | Moving or renaming a page adds a line to `_redirects.yml` in the same commit. | The old URL is in bookmarks, search results and other repositories. | -| 11 | `_Sidebar.md` lists every page once, grouped by section, in reading order. | The site orders pages by it; a page missing from it has no place in the navigation. | - -Full layout rules, a worked tree and what the site rewrites: [references/layout.md](references/layout.md). - -## Hierarchy: the default shape - -```text -docs/wiki/ - _Sidebar.md navigation (not published) - _redirects.yml moves (not published) - Home.md hub / landing page (docs.rootPage) - Getting-Started.md root only because the catalogue deep-links it - guide/ - README.md the folder's own page: /docs//guide/ - Installation.md - First-Project.md - configuration/ - Options.md - Environment-Variables.md - diagrams/ - request-flow.c4 LikeC4 models (not published as pages) -``` - -One level of folders is the default; go deeper only when a folder holds a sub-area with several pages -of its own. A nested `README.md` (or `index.md`) is that folder's landing page. A page the site's -catalogue deep-links from a use case (`useCases[].docsPage`) is a single URL segment, so it must stay -at the root until the catalogue entry moves with it — check the entry before moving one. - -## Diagrams: LikeC4 on the site, Mermaid on GitHub - -Draw each diagram once as a LikeC4 model in a `.c4` file, and once as Mermaid for GitHub. Wrap the -Mermaid fence in the `purview:likec4` markers: - -````markdown - -```mermaid -flowchart LR - client[Client] --> api[API] --> store[(Store)] -``` - -[LikeC4 model](./diagrams/request-flow.c4) - -```` - -- **On GitHub** the comments are invisible: the reader sees the Mermaid diagram and a link to the model. -- **On purview.dev** the sync replaces the whole block — markers, Mermaid and link — with the LikeC4 - view, rendered interactively. The Mermaid is never shown there. -- If the model cannot be read or does not declare the view, the site keeps the Mermaid and the sync - logs a warning, so a mistake costs fidelity, never the page. - -Marker options, the model rules (one self-contained file per diagram), and a full worked conversion of an -ASCII flow: [references/diagrams.md](references/diagrams.md). - -## Moving pages: `_redirects.yml` - -```yaml -# docs/wiki/_redirects.yml — previous: current (slugs, or paths from the docs root) -redirects: - getting-started: guide/getting-started - Custom-Rules.md: schemas/Custom-Rules.md -``` - -The site reads the file at each documentation channel's own ref and writes a redirect page for every -pair whose destination exists and whose source is no longer a page. A pair whose destination is missing, -or whose source still exists, is reported and skipped; an invalid file fails the site's sync with the -file name, so fix it rather than delete it. Never remove a line once released — the old URL lives in -someone's bookmark. Details: [references/redirects.md](references/redirects.md). - -## Moving a page — the checklist - -1. `git mv` the file, so history follows it. -2. Fix every inbound link: other pages (relative to *their* folder), `_Sidebar.md`, `Home.md`, the - READMEs, `AGENTS.md`, skills, and tests that name the path. -3. Add `old-slug: new/slug` to `_redirects.yml`. -4. If the page is a catalogue deep link (`docsPage`), it stays at the root, or ask the site maintainers - to move the deep link; do not edit `purview-dev/purview-dev` unasked. -5. Run the assessment (`purview-site-assessment`) and fix what it reports. - -## Related skills - -- `purview-site-integration` — everything else the site reads from a repository (topics, releases, - packages, skills) and how a project joins the catalogue. -- `purview-site-assessment` — a script and a procedure that check a repository against these rules. diff --git a/.agents/skills/purview-site-docs/references/diagrams.md b/.agents/skills/purview-site-docs/references/diagrams.md deleted file mode 100644 index 3710364..0000000 --- a/.agents/skills/purview-site-docs/references/diagrams.md +++ /dev/null @@ -1,174 +0,0 @@ -# Diagrams: a LikeC4 model paired with a Mermaid fence - -GitHub renders Mermaid and shows LikeC4 as source. purview.dev renders LikeC4 (interactive, with the -model behind it) and Mermaid. A diagram pair gives each reader the best diagram their renderer can show, -from one page. - -## The block - -````markdown - -```mermaid -flowchart LR - resume[pm-resume] --> next[pm-next] -``` - -[LikeC4 model](./diagrams/the-loop.c4) - -```` - -| Part | Rule | -| -- | -- | -| Opening marker | `` alone on its line | -| `file` | **required.** The `.c4` model, relative to the page (or `/`-rooted at the repository root). It may live anywhere in the repository, including outside the docs folder | -| `view` | the view to render; defaults to the first view the model declares. Name it explicitly | -| `title`, `description` | the heading and sub-heading of the diagram on the site | -| `height` | pixels, default `420` | -| `collapsible`, `defaultOpen` | `true`/`false`; the site's diagram shell is collapsible and open by default | -| Between the markers | what GitHub shows: one ```` ```mermaid ```` fence, then optionally a link to the model | -| Closing marker | `` alone on its line | - -Markers inside a code fence are ignored (that is how this page shows them). - -## What happens - -| Reader | Sees | -| -- | -- | -| GitHub | the Mermaid diagram and the "LikeC4 model" link; the comments are invisible | -| purview.dev | the LikeC4 view only. The sync swaps the whole block for a ```` ```likec4 ```` fence holding the model file's text | -| purview.dev, model unreadable or view undeclared | the Mermaid diagram, and a warning in the site's sync log naming the page, line and reason | - -## The model file - -- **One self-contained file per diagram**: its own `specification`, `model` and `views`. The site - compiles the file on its own, so it cannot see other `.c4` files — no shared specification across - files, no `import`. -- Keep models beside the docs (`docs/wiki/diagrams/.c4`). A `.c4` file is never published as a - page. -- Element and view ids: letters, digits, underscores, starting with a letter (`theLoop`, `apiGateway`). -- Validate before committing: `npx likec4 validate docs/wiki/diagrams` (or `bunx likec4 validate …`). -- Prefer `autoLayout LeftRight` for flows and `TopBottom` for hierarchies; `include *` for a small model. - -## The Mermaid rendering - -- It is the GitHub reader's diagram, so keep it equivalent: the same nodes and edges, the same labels. - It does not need the styling or descriptions the model carries. -- `flowchart LR`/`TB` for flows; `sequenceDiagram` when the LikeC4 view is a `dynamic view`. -- When the model changes, the Mermaid changes in the same commit — review them side by side. - -## Never ASCII art - -A fenced ```` ```text ```` block of boxes and arrows is a diagram nobody can read on a phone, search, -or keep in step. Convert it. A legend that sits under ASCII art ("pm-park: any time, capture only") -becomes a table or a list after the diagram, not part of it. - -## Worked conversion - -The PM skills README describes its loop as ASCII art: - -```text -pm-resume -> pm-next -> [design -> plan -> execute -> finish] - ^ | | | - | pm-checkpoint (stage updates) pm-checkpoint (done, on the branch) - | | - +-----------------------------------------+ - | - push branch -> one PR -> CI -> merge -``` - -**1. The model** — `docs/diagrams/the-loop.c4`: - -```likec4 -specification { - element skill { - style { - shape rectangle - } - } - element stage { - style { - shape rectangle - color secondary - } - } - element delivery { - style { - shape rectangle - color muted - } - } -} - -model { - resume = skill 'pm-resume' { - description 'Reads the planning files and recommends one action' - } - next = skill 'pm-next' { - description 'Claims the first item that is still the right one' - } - design = stage 'design' - plan = stage 'plan' - execute = stage 'execute' - finish = stage 'finish' - checkpoint = skill 'pm-checkpoint' { - description 'Writes where work stopped, so a compacted session can resume' - } - push = delivery 'push branch' - pr = delivery 'one PR' - ci = delivery 'CI' - merge = delivery 'merge' - - resume -> next - next -> design 'claims an item' - design -> plan - plan -> execute - execute -> finish - design -> checkpoint 'stage updates' - plan -> checkpoint 'stage updates' - execute -> checkpoint 'stage updates' - finish -> checkpoint 'done, on the branch' - checkpoint -> next 'next item' - checkpoint -> push - push -> pr - pr -> ci - ci -> merge -} - -views { - view theLoop { - title 'The loop' - include * - autoLayout LeftRight - } -} -``` - -**2. The README section**: - -````markdown -## The loop - - -```mermaid -flowchart LR - resume[pm-resume] --> next[pm-next] - next -- claims an item --> design - design --> plan --> execute --> finish - design & plan & execute -. stage updates .-> checkpoint[pm-checkpoint] - finish -- done, on the branch --> checkpoint - checkpoint -- next item --> next - checkpoint --> push[push branch] --> pr[one PR] --> ci[CI] --> merge -``` - -[LikeC4 model](./docs/diagrams/the-loop.c4) - - -| Skill | When it runs | -| -- | -- | -| `pm-park` | any time, capture only | -| `pm-review` | weekly | -| `pm-risk` | capture a risk any time; manage the register when no workflow is active | -```` - -The file path is relative to the page, so from the root `README.md` it is `./docs/diagrams/the-loop.c4`; -from `docs/wiki/guide/Loop.md` it would be `../../diagrams/the-loop.c4`. diff --git a/.agents/skills/purview-site-docs/references/layout.md b/.agents/skills/purview-site-docs/references/layout.md deleted file mode 100644 index ba8a033..0000000 --- a/.agents/skills/purview-site-docs/references/layout.md +++ /dev/null @@ -1,92 +0,0 @@ -# Layout and what the site does to a page - -## Which files are read - -The catalogue entry's `docs.source` decides: - -| `docs.source` | Read | Use it when | -| -- | -- | -- | -| `github-path` | every `/**/*.md` at the channel's ref (default branch, or a release tag for a `live` channel) | **the default.** Any repository with more than one page. Supports folders, channels and redirects | -| `wiki` | the top-level `.md` files of the GitHub wiki (`.wiki.git`) | only for an existing GitHub wiki; it has no history the site can pin, and no folders | -| `readme` | `README.md` alone, as one page | a project small enough to be one page. Grows into `github-path` — a README with more than about eight `##` sections or a few hundred lines is a docs tree waiting to happen | - -Files that are never pages: `_Sidebar.md`, `_Footer.md`, `_redirects.yml`, `.c4` models, images, and -anything the entry lists in `docs.exclude` (matched on the base file name, `*` wildcards). - -## The landing page - -1. A conventional index at the docs root wins: `Home.md`, `index.md` or `README.md` (case-insensitive). -2. The entry's `docs.rootPage` may name another page only when the conventional one is excluded. -3. No index and no `rootPage` fails the sync: *"docs: no root page exists"*. - -Prefer `Home.md` as the hub (what the project is, then a table of sections linking every page) and a -`Getting-Started.md` beside it. - -## URL of every page - -The path from the docs root, each segment lower-cased with anything other than letters, digits and -dashes collapsed to `-`, and the `.md` dropped: - -| Source | Published at | -| -- | -- | -| `docs/wiki/Home.md` (root page) | `/docs//` | -| `docs/wiki/Getting-Started.md` | `/docs//getting-started/` | -| `docs/wiki/guide/README.md` | `/docs//guide/` | -| `docs/wiki/guide/First-Project.md` | `/docs//guide/first-project/` | -| `docs/wiki/Q&A/Why Not.md` | `/docs//q-a/why-not/` (works, but rename it) | -| `docs/wiki/___/Page.md` | **sync fails**: the folder reduces to nothing | - -Two files that reduce to the same URL collide; keep names distinct after lower-casing. A page may not -be named `prerelease` (that segment is reserved for the prerelease documentation channel). - -## Sidebar and order - -- Folders become collapsible sidebar groups labelled from the folder name (`getting-started` → - "Getting Started"), placed where their first page appears. -- Order: the entry's `docs.order` (explicit slugs) → the link order in `_Sidebar.md` → alphabetical. -- `_Sidebar.md` links pages by their path from the docs root: - -```markdown -- [Home](Home.md) -- **Guide** - - [Installation](guide/Installation.md) - - [First project](guide/First-Project.md) -- **Configuration** - - [Options](configuration/Options.md) -``` - -## What the site rewrites - -| In the source | On the site | -| -- | -- | -| `[Options](../configuration/Options.md#timeouts)` | a link to `/docs//configuration/options/#timeouts`; an anchor that is not a heading on the target page is dropped | -| `[Code](../../src/Thing.cs)` (outside the docs folder) | `https://github.com//blob//src/Thing.cs` | -| `![Flow](./images/flow.png)` | `https://github.com//raw///images/flow.png` | -| `![badge](https://img.shields.io/…)` | unchanged | -| `> [!WARNING]` blockquote | a Starlight caution aside | -| the first `# Title` | the page header (title, sidebar label); removed from the body so it shows once | -| a second `# Heading` | demoted to `##` — one title per page | -| a `purview:likec4` block | the LikeC4 view (see `diagrams.md`) | -| a bare ```` ```mermaid ```` fence | a Mermaid diagram (both sides render it) | -| a bare ```` ```likec4 ```` fence | a LikeC4 diagram on the site — but **source code on GitHub**; use a pair | -| mkdocs/Material markup (`!!! note`, `{ .md-button }`, `{% … %}`) | stripped or converted; do not write it | - -Front matter in a source page is not needed: the site writes its own (title, description, edit link, -last-reviewed date from the last commit, the repository's topics as tags). A page not touched for 365 -days is flagged as stale on the site. - -## Documentation channels - -A project whose default branch runs ahead of its last release can publish two versions of its docs: -`live` (pinned to the latest stable tag, at `/docs//`) and `prerelease` (the default branch, at -`/docs//prerelease/`). This is declared in the catalogue entry, not in the repository. What it means -for you: a page reorganisation is visible on the prerelease channel immediately and on live only after -the release that carries it, and `_redirects.yml` is read per channel, so each channel forwards its own -old URLs at the right moment. - -## Writing style that survives both renderers - -- ATX headings (`##`), sentence or title case consistently, no trailing punctuation. -- Tables for anything enumerable. -- Wrap prose near 100–110 columns, so documentation diffs stay reviewable. -- HTML only where Markdown cannot express it; the site renders it, but GitHub sanitises it. diff --git a/.agents/skills/purview-site-docs/references/redirects.md b/.agents/skills/purview-site-docs/references/redirects.md deleted file mode 100644 index 7658587..0000000 --- a/.agents/skills/purview-site-docs/references/redirects.md +++ /dev/null @@ -1,49 +0,0 @@ -# `_redirects.yml` — keeping moved pages reachable - -A page's path is its URL. Moving `Getting-Started.md` into `guide/` moves -`/docs//getting-started/` to `/docs//guide/getting-started/`, and every bookmark, search result -and link from another repository to the old address would 404. `_redirects.yml` records the move in the -same commit as the move. - -## Where and what - -`/_redirects.yml` — beside `Home.md` (for a GitHub wiki, at the wiki root). It is never a page. - -```yaml -# previous: current -# Either side may be a slug (`guide/getting-started`) or a Markdown path from the -# docs root (`guide/Getting-Started.md`); both are reduced to the published slug. -redirects: - getting-started: guide/getting-started - Custom-Rules.md: schemas/Custom-Rules.md - old-landing: index # `index` is the docs root, /docs// -``` - -A bare map without the `redirects:` key is accepted too. Keep to this shape: one `previous: current` -pair per line, comments with `#`, quotes only when a name needs them. - -## How the site uses it - -1. The sync reads the file at each documentation channel's ref — so a reorganisation on the default - branch forwards the prerelease channel's URLs straight away, and the live channel's only once the - release that contains it is published. -2. For each pair it writes a small redirect page at the old address pointing to the new one - (`noindex`, not searchable, not in the sitemap). -3. A redirect is **written only when its destination is a published page and its source is not.** A - real page always wins over a redirect. -4. A pair that points nowhere, or whose source still exists, is reported in the sync log and skipped. -5. A file that is not valid YAML, is not a map, or holds a pair that cannot become a URL, **fails the - site's sync** naming the file — the moves it was meant to protect would otherwise vanish silently. - -The site's catalogue entry may also carry `docs.redirects` for the same purpose; when both name the -same old slug the catalogue entry wins. Prefer the file: the move and its redirect then live in one -commit, in the repository that made them. - -## Rules - -- Add the pair in the commit that moves the page. Never remove a released pair. -- Point at the final address. When a page moves twice, update the first pair's destination rather than - chaining `a → b → c`. -- Redirect pages only — not anchors, not folders. A folder with a `README.md` is a page (`guide`), so - it can be a destination. -- After the move, fix inbound links anyway: a redirect is for readers outside the repository. diff --git a/.agents/skills/purview-site-integration/SKILL.md b/.agents/skills/purview-site-integration/SKILL.md deleted file mode 100644 index 24cd40a..0000000 --- a/.agents/skills/purview-site-integration/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: purview-site-integration -description: Make a Purview repository (a NuGet library, an MSBuild SDK, an npm package, or a pure agent-skills repository such as pm-skills) fully integrated with purview.dev - what the site reads from the repository and when, the GitHub metadata it shows (topics as tags, description, releases, default branch), the documentation contract, published agent skills, mirrored assets, and the catalogue entry the site maintainers write for it. Use when preparing a repository to join purview.dev, when its project page or docs look wrong or stale, when adding skills, packages or releases a reader should see, or when asked "how does this show up on purview.dev?". -license: MIT -metadata: - site: https://purview.dev - repository: purview-dev/purview-dev ---- - -# Integrating a repository with purview.dev - -purview.dev is a static site built from two inputs: - -1. **The catalogue** — one YAML file per project in `purview-dev/purview-dev` - (`src/src/data/projects/.yml`): the curated words (description, origin, when to use it, use - cases) and the pointers (which docs to read, which packages and skills to show). -2. **This repository** — read at build time through the GitHub API, raw file URLs and the package - registries. Nothing is pushed to the site; a scheduled build and every site deploy pull it. - -So integration has two halves: make this repository **readable** (this skill and -`purview-site-docs`), and give the site maintainers what they need to **write the entry** -([references/catalogue-contract.md](references/catalogue-contract.md)). Do not edit -`purview-dev/purview-dev` from this repository unless the user asks; propose the entry instead. - -## What the site reads from this repository - -| Site surface | Read from | Your responsibility | -| -- | -- | -- | -| Tag chips on cards, search, docs pages | GitHub **topics** | 6–15 lower-case, hyphenated topics (`csharp`, `source-generators`, `opentelemetry`). The first four are what a card shows. There is no other way to set tags | -| "From the repository" note on the project page | GitHub **description** | One sentence that agrees with the catalogue's `shortDescription` | -| Versions, release dates, "latest release" | GitHub **releases** + the NuGet / npm registry | Tag releases `vX.Y.Z`; prereleases `vX.Y.Z-prerelease.N`. Publish packages to the registry the entry names | -| Status checks (`stable`/`preview`/`archived`) | releases, registry versions, the archived flag | A stable registry version means `stable`; prerelease-only means `preview`; archive the repository rather than leave it idle | -| Documentation at `/docs//` | `docs/wiki/**/*.md` (or `docs/`, a wiki, or `README.md`) at the **default branch** (or a release tag) | Follow `purview-site-docs`: hierarchical folders, one H1, relative links, diagram pairs, `_redirects.yml` | -| Agent skills listed on the project page, served at `/skills///` | every `skills//SKILL.md` (discovered; the entry can opt out) and everything beside it | Front matter `name` (equal to the folder) and `description`. Skills reach users through `npx skills add purview-dev/`, never inside a package | -| Mirrored assets (JSON schemas and similar) | repository paths the entry lists under `assets:` | Keep the path stable; moving it breaks the site build until the entry follows | -| Build badge | the repository's GitHub Actions | A workflow that runs on the default branch | -| Discussions link | repository settings | Enable Discussions if you want readers to ask there | -| Star count | GitHub | — | - -The default branch must be `main` unless the entry says otherwise; the docs, the edit links and the -"last reviewed" dates all follow it. - -## The integration checklist - -1. **Metadata** — description set, 6–15 topics, the repository public, Discussions decided: - - ```shell - gh api repos/purview-dev/ --jq '{description, topics, archived, default_branch, has_discussions}' - ``` - -2. **Releases** — at least one GitHub release whose tag matches the packages' version, published to - NuGet or npm. A project with no release shows no version anywhere. -3. **Documentation** — a `docs/wiki/` tree (or a deliberate one-page `README.md`), laid out per - `purview-site-docs`. ASCII-art diagrams converted to LikeC4/Mermaid pairs. A `_redirects.yml` the - moment a page moves. -4. **Skills** — one folder per skill under `skills/`, each with a `SKILL.md` whose front matter `name` - matches the folder and whose `description` says what it does and when to use it. -5. **README** — the GitHub front door: what it is, install, a minimal example, a link into the docs. - It points into the docs rather than duplicating them (a `readme`-sourced project is the exception: - the README *is* the docs). -6. **The entry** — collect what [references/catalogue-contract.md](references/catalogue-contract.md) - asks for, and hand it to the site maintainers (an issue or pull request on - `purview-dev/purview-dev`). The site's own agents onboard projects from that information. -7. **Assess** — run the `purview-site-assessment` skill and fix every error before asking for the - entry. - -## Live examples and diagrams on the project page - -A project page can link a live example: an `.mdx` page in the site repository -(`src/src/pages/examples/.mdx`). That is authored on the site side; propose it with the entry when -the project has something visual to show. Diagrams inside your docs need nothing from the site — use -the diagram pairs from `purview-site-docs`. - -## When something looks wrong on the site - -| Symptom | Usual cause | -| -- | -- | -| No tags on the card | no GitHub topics | -| Version missing or old | no release, a tag that does not match the package version, or the registry has not indexed it yet | -| A docs page missing | not under the docs path, excluded by name, or a slug that collides with another | -| A link on a docs page goes to GitHub | it points outside the docs folder, or at a page that does not exist | -| A diagram shows Mermaid on the site | the `purview:likec4` model file or view was not found — the site's sync log says which | -| A bookmarked docs URL 404s | a page moved without a `_redirects.yml` line | -| Skills not listed | the skill is not at `skills//SKILL.md`, its front matter is missing a field, or the entry opts out with `skills: false` | - -## Related skills - -- `purview-site-docs` — how to write and organise the documentation itself. -- `purview-site-assessment` — check this repository against both skills and get a prioritised report. diff --git a/.agents/skills/purview-site-integration/references/catalogue-contract.md b/.agents/skills/purview-site-integration/references/catalogue-contract.md deleted file mode 100644 index d945fa4..0000000 --- a/.agents/skills/purview-site-integration/references/catalogue-contract.md +++ /dev/null @@ -1,93 +0,0 @@ -# The catalogue entry — what to hand the site maintainers - -The entry lives in `purview-dev/purview-dev` at `src/src/data/projects/.yml` and is validated by the -site's schema, so its vocabulary is fixed. Collect the answers below from this repository and propose -them; the maintainers (or the site's onboarding agent) turn them into the entry. - -## Identity - -| Field | What to provide | -| -- | -- | -| `id` | lower-case slug, normally the repository name without `purview-` (`unions`, `build-sdk`). It is the URL: `/projects//`, `/docs//` | -| `name` | display name; must slugify to `id` when the project has docs (`Build SDK` → `build-sdk`). Not prefixed with "Purview" | -| `repository` | `purview-dev/` | -| `category` | one of `application-framework`, `validation`, `observability`, `source-generation`, `aspire`, `build-tooling`, `developer-tooling` | -| `status` | `stable` (a stable release is published), `preview` (prereleases only), `archived` | -| `experimental` | `true` when the API and packaging may change without notice | - -## The words - -Write these for a reader deciding whether to use the project. Backticks become inline code on the site. - -| Field | Shape | -| -- | -- | -| `shortDescription` | one sentence; the card text | -| `description` | 2–4 sentences: the problem and what the project does about it | -| `origin` | why it became a reusable project rather than code in one application | -| `useWhen` / `avoidWhen` | the honest fit, including when something simpler is better | -| `useCases` | at least one, each: `audience` (`developer`, `team-lead`, `architect`, `contributor`), `title`, `scenario`, optional `code` + `language`, `outcome`, optional `evidence`, optional `docsPage` | -| `acknowledgments` | upstream work the project builds on: `name`, `url`, `description` | -| `related` | ids of related Purview projects | - -A use case is concrete: a real situation, real code, a measurable outcome, and evidence that can be -checked (a test, a benchmark, a diagnostic id). `docsPage` is a **single-segment** slug of a docs page -at the docs root — so a page used as a deep link stays at the root of the tree. - -## Pointers - -| Field | What to provide | -| -- | -- | -| `docs.source` | `github-path` (preferred), `wiki`, or `readme` | -| `docs.path` | the docs folder, e.g. `docs/wiki` | -| `docs.rootPage` | the landing page, e.g. `Home.md` or `Getting-Started.md` | -| `docs.exclude` | base file names that are not pages, e.g. `_Sidebar.md` | -| `docs.channels` | only when `main` runs ahead of the last release: `live: { ref: latest-stable }`, `prerelease: { ref: default }` | -| `packages` | each package id, its `registry` (`nuget` default, or `npm`), a one-line `description`, and which is `primary` | -| `install` | for NuGet: `nuget` (a `PackageReference`), `msbuild-sdk`, or `dotnet-tool` | -| `targetFrameworks` | what the packages actually ship (`net8.0`, `net10.0`, `netstandard2.0`) — the site checks them against NuGet | -| `skills` | usually omitted: every `skills/*/SKILL.md` is discovered and published. `false` opts out; a list of `{ name, path?, description? }` overrides discovery | -| `assets` | `{ path, output, description? }` for files the site should serve, e.g. a JSON schema at `/schemas/.json` | - -Redirects for moved pages belong in this repository's `_redirects.yml`, not in the entry. - -## A template to fill in - -```yaml -id: -name: -shortDescription: -description: >- - <2–4 sentences> -origin: >- - -useWhen: >- - -avoidWhen: >- - -repository: purview-dev/ -category: -status: -docs: - source: github-path - path: docs/wiki - rootPage: Home.md - exclude: - - _Sidebar.md -packages: - - id: - description: - primary: true -useCases: - - audience: developer - title: - scenario: >- - - code: | - - language: csharp - outcome: >- - - evidence: >- - - docsPage: -``` diff --git a/.agents/skills/site-validation-loop/SKILL.md b/.agents/skills/site-validation-loop/SKILL.md deleted file mode 100644 index 56f6e26..0000000 --- a/.agents/skills/site-validation-loop/SKILL.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -name: site-validation-loop -description: Use when validating a change to the Purview-Dev website — what each just recipe and script checks, the data-sync modes, how to reproduce failures offline, and the rules for generated artefacts. -category: purview-dev-website -roles: - - validation - - tooling -tags: - - just - - bun - - ci - - astro ---- - -# site-validation-loop Skill - -`just validate` is the authoritative chain and the same pipeline runs in CI -(`purview-build.json` → `bun run ci:build`; deploy.yml runs `just validate` first). Treat a green -`just validate` as the definition of done. - -## The chain, in order - -| Step | Command | Catches | -| --- | --- | --- | -| Format check | `just format-check` (`oxfmt --check`) | Formatting drift in `src/**` (not `.astro`) | -| Lint | `just lint` (`oxlint`, `maxWarnings: 0`) | Type-aware + a11y issues in `src/**` | -| Typecheck | `just typecheck` (`astro check` + strict TS) | Component/frontmatter/content-schema type errors | -| Unit tests | `just test` (`bun test tests/unit`) | Manifest/schema rules, catalogue guard, docs aggregation rules, release transform, urls, staleness, branding | -| Assets | `just check-assets` | Branding sources vs generated public assets | -| Catalogue | `just check-projects` | Catalogue invariants (see below) | -| Build | `just build` (runs live data sync first) | Astro/Starlight build, sidebar/llms plugin wiring | -| Links | `just check-links` | Broken internal links **and missing anchors** across `dist/**/*.html` | -| Generated output | `just check-generated` | Docs cache/mirror agreement, release cache shape, mirrored project assets exist and are valid JSON, `llms*.txt`, sitemap, robots, no secrets/local paths | -| Dist tests | `just test:dist` | Per-project LLM bundles, rendered project/use-case surfaces, footer version, SEO outputs | - -## The catalogue guard (`just check-projects`) - -`src/scripts/check-projects.ts` validates the catalogue records (`src/src/data/`) against the generated data (offline, -deterministic). It fails the build on: - -- ids/orders duplicated, `order` not a unique integer, `name` not slugifying to `id` for documented - projects; -- a documented project with no aggregated pages, or a `docsPage` that does not resolve; -- a non-archived project with no use case, or a use case with `code` but no `language`; -- a package declared more than once, more than one `primary`, or a package with no release data; -- `status: archived` on a non-archived repository, or `stable` on a project whose packages have no - stable version; -- missing repository topics (tags), a non-`main` default branch for a documented project, or - `discussions: true` without repository discussions; -- `externalProjects` pointing at a `purview-dev` repository. - -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 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 - are compared with the union of the **runtime** packages' frameworks; package-level frameworks are - compared with that package's own. `netstandard*` is treated as an analyzer/generator build target - (never a consumer framework), and `install: msbuild-sdk`/`dotnet-tool` projects and the `msbuild` - sentinel are skipped. - -Run it alone while iterating: `just check-projects`. - -Apply the machine-applicable observations (missing/mismatched `targetFrameworks`, `preview` → -`stable` when a stable package exists) with `just fix-projects`; it is a dry run by default and only -edits the records with `--write`. It rewrites the affected `targetFrameworks` lists to exactly the -expected set (so it also removes frameworks a package no longer targets), but never touches blockers -or judgement calls such as replacing a deprecated package. - -## Data-sync modes - -`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 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). - -The same mode governs mirrored **project assets** (`assets:` in a record): `just data-sync` fetches -each declared repository file with the docs aggregator's `fetchRawFile`, writes it to `public/`, and -caches it under `.cache/assets/`. A declared asset that cannot be resolved fails the sync, so a -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 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 -install snippets refresh this way. Nothing else is fetched client-side, and no check depends on the -live value — `just check-projects` and `tests/dist` assert the build-time output. - -## Rules - -- **Never edit generated files** (`src/src/content/docs/**`, `src/.cache/**`, `src/dist/**`). - Regenerate with `just data-sync`, `just fetch-releases`, `just build`, or `just refresh-fixtures`. -- **Never weaken a check** to make a change pass. Fix the data or the implementation; changing the - contract needs an ADR. -- Keep `src/fixtures/**` in sync when the release data shape changes (`just refresh-fixtures`, then - review the diff). -- Do not run `just clean` to "fix" a failure: a fresh checkout then needs a live data sync. - -## Reproducing failures - -```shell -# Docs aggregation / sidebar problems -just live-data-sync && just check-generated - -# Link or anchor failures: rebuild then re-crawl -just build && just check-links - -# Catalogue drift in isolation -just check-projects - -# Release-data problems without network -DATA_MODE=fixture just build && just test-dist -``` diff --git a/.agents/skills/use-case-authoring/SKILL.md b/.agents/skills/use-case-authoring/SKILL.md deleted file mode 100644 index 84279ef..0000000 --- a/.agents/skills/use-case-authoring/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: use-case-authoring -description: Use when writing or reviewing useCases in the catalogue records — the ADR 0002 rules for audience-tagged, concrete, evidence-backed examples with short code snippets and resolvable documentation deep links. -category: purview-dev-website -roles: - - catalogue - - content -tags: - - use-cases - - adr-0002 - - documentation ---- - -# 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/.yml`) and validated by the manifest -schema. The governing decision is `docs/decisions/0002-concrete-use-cases.md`. - -## Shape - -```yaml - useCases: - - audience: developer # developer | team-lead | architect | contributor - title: Tracing, logging, and metrics from a single interface - scenario: >- # the situation the reader is in - You want OpenTelemetry activities, structured logs, and metrics around an order service, - but you do not want to hand-write the ActivitySource, ILogger, and Meter wiring. - code: | # short snippet; `language` becomes required - [ActivitySource] - [Logger] - [Meter] - public interface IOrderServiceTelemetry - { - [Activity] - [Info] - [AutoCounter] - Activity? PlacingOrder(int orderId, [Baggage] string region); - } - language: csharp - outcome: >- # what the reader gets back - The generator emits the implementation and an AddOrderServiceTelemetry() DI extension. - evidence: >- # a fact, not a claim - One interface replaces the ActivitySource, ILogger, and Meter boilerplate repeated per service. - docsPage: getting-started # slug of an aggregated page under /docs// -``` - -## Rules - -1. **Audience is from a fixed vocabulary** — `developer`, `team-lead`, `architect`, `contributor`. - Pick the person who would actually read this example; do not tag everything `developer`. -2. **At least one use case per non-archived project**, and no project should have a single - `developer` example when the project also has an adoption/architecture story worth telling - (an audit `polish` finding). Do not pad: two or three strong examples beat six weak ones. -3. **`code` requires `language`.** The snippet is highlighted at build time by Shiki; use a real - language id (`csharp`, `json`, `xml`, `yaml`, `bash`, `typescript`). -4. **Snippets are short and point at the docs for depth.** Long walkthroughs belong in the - aggregated documentation. The card links to `docsPage`. -5. **`docsPage` must be a lowercase `[a-z0-9-]` slug** and must resolve to a real aggregated page - (`/docs///`). The schema rejects other shapes, the unit tests reject a - `docsPage` on a project without a `docs` configuration, and the post-build link crawl - (`just check-links`) fails on a dead link. Slug the source file name: `SQL Server Guide.md` → - `sql-server-guide`. -6. **`evidence` must be a fact.** Good: a before/after, a count of generated members, a measured - allocation property, a generated-output excerpt. Bad: "very fast", "easy to use", "saves time". -7. **`scenario` is a situation, `outcome` is the result.** The pair should let a reader decide in ten - seconds whether the example matches their problem. -8. **Keep the language factual** — no marketing superlatives, no invented benchmarks, no claims that - cannot be traced to the repository or the aggregated docs. - -## Where they render - -- Home page ("What it looks like in practice") — server-rendered, no island. -- Project page (`/projects//`) — the use-case section with highlighted code. -- `/use-cases/` — the full index, filterable by audience via one Preact island; the page is usable - without JavaScript and each card carries `data-usecase-audience` and a search corpus. - -## Verification - -```shell -bun run test # manifest/use-case unit tests (audience, language, docsPage rules) -just check-projects # deterministic coverage and docsPage-resolution checks -just build && just check-links # every rendered docs deep link resolves in dist/ -``` diff --git a/.gitignore b/.gitignore index fe9098c..829f5c1 100644 --- a/.gitignore +++ b/.gitignore @@ -660,10 +660,14 @@ sketch # Repo-local skills live in .agents/skills/; the build-output rules above # would otherwise ignore one named "release". !.agents/ -!.agents/skills/ -!.agents/skills/** # Local installs of this repo's own skills, made by `just setup-skills` # (symlinks into skills/), and the skills CLI's lockfile for them. .agents/skills/pm-* + +# Agent skills are installed into the universal .agents/skills/ folder, which is a local install: +# gitignored, and reproducible from the committed skills-lock.json with `just skills-install`. The +# skills this repository authors live in skills/ and are the only ones another repository installs. +# Per-agent folders (including .claude/) are local too - never commit a copy. +.agents/skills/ .claude/ diff --git a/AGENTS.md b/AGENTS.md index 095f139..e10f16d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -148,7 +148,7 @@ Hooks are configured in `.config/lefthook.yml`: `commit-msg` runs `pre-push` runs `just lint-check` and `just version-check`. Releases are driven by the `version` field in `package.json`, and its major -is the rules/skills version: rules `version=17` ships as `17.x.y`. +is the rules/skills version: rules `version=18` ships as `18.x.y`. - `.github/workflows/release.yml` creates the `v{version}` tag and a GitHub release when `package.json` changes on `main`, and skips when the tag diff --git a/package.json b/package.json index 42b720e..6730426 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pm-skills", - "version": "17.0.0", + "version": "18.0.0", "description": "Project-management skills for solo developers using AI coding agents - a parking lot, challenged shaping, strategy, roadmap, task board, up-next queue, and session memory, installed above a development workflow skill set such as Superpowers.", "license": "MIT", "author": { diff --git a/planning/config.md b/planning/config.md index 05e42d5..71be718 100644 --- a/planning/config.md +++ b/planning/config.md @@ -10,7 +10,7 @@ Read by every `pm-*` skill. Change behaviour here, not in the skills. ## Install -- Rules version: 17 +- Rules version: 18 ## Handoffs diff --git a/scripts/setup-skills.ts b/scripts/setup-skills.ts index 013c38c..a6d0379 100644 --- a/scripts/setup-skills.ts +++ b/scripts/setup-skills.ts @@ -2,9 +2,8 @@ import { spawnSync } from "node:child_process"; import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync, symlinkSync } from "node:fs"; import { join, relative } from "node:path"; -// Make this repository's own pm-* skills usable by the agents working on it: -// clear every pm-* entry in the skill folders, then link each skills/pm-* -// folder back in, so an edit to skills/ is live without reinstalling. +// Make this repository's own skills usable by the agents working on it: clear the skill folders, then +// link each skills// folder back in, so an edit to skills/ is live without reinstalling. // // bun scripts/setup-skills.ts # link each folder (the default) // bun scripts/setup-skills.ts --cli # install with `bunx skills add ./` @@ -22,18 +21,21 @@ const targets = [ { agent: "universal", dir: join(root, ".agents", "skills") }, ]; -const shipped = readdirSync(skillsDir, { withFileTypes: true }) - .filter((d) => d.isDirectory() && d.name.startsWith("pm-") && existsSync(join(skillsDir, d.name, "SKILL.md"))) +// Every skill this repository authors is linked, not only the shipped pm-* ones: `release` is +// repo-local (metadata.internal: true), so the CLI would never install it, and an agent working here +// still has to be able to read it. +const authored = readdirSync(skillsDir, { withFileTypes: true }) + .filter((d) => d.isDirectory() && existsSync(join(skillsDir, d.name, "SKILL.md"))) .map((d) => d.name) .sort(); -// Only pm-* entries are cleared: .agents/skills/ also holds repo-local skills -// (release) that are checked in. +// Both folders are install locations now: gitignored, never committed, and reproducible from +// skills-lock.json - so everything in them is this script's to replace. function clear() { for (const { dir } of targets) { if (!existsSync(dir)) continue; for (const name of readdirSync(dir)) { - if (name.startsWith("pm-")) rmSync(join(dir, name), { recursive: true, force: true }); + rmSync(join(dir, name), { recursive: true, force: true }); } } } @@ -49,7 +51,7 @@ function viaCli(): boolean { function viaLinks() { for (const { dir } of targets) { mkdirSync(dir, { recursive: true }); - for (const name of shipped) { + for (const name of authored) { symlinkSync(join(skillsDir, name), join(dir, name), process.platform === "win32" ? "junction" : "dir"); } } @@ -57,14 +59,14 @@ function viaLinks() { function missing(): string[] { return targets.flatMap(({ dir }) => - shipped + authored .filter((name) => !existsSync(join(dir, name, "SKILL.md"))) .map((name) => relative(root, join(dir, name))), ); } function linked(): boolean { - return targets.every(({ dir }) => shipped.every((name) => lstatSync(join(dir, name)).isSymbolicLink())); + return targets.every(({ dir }) => authored.every((name) => lstatSync(join(dir, name)).isSymbolicLink())); } clear(); @@ -84,4 +86,4 @@ if (gaps.length) { process.exit(1); } const kind = linked() ? "linked" : "copied"; -console.log(`setup-skills: ${shipped.length} pm-* skills ${kind} into ${targets.map((t) => relative(root, t.dir)).join(", ")}`); +console.log(`setup-skills: ${authored.length} skills ${kind} into ${targets.map((t) => relative(root, t.dir)).join(", ")}`); diff --git a/scripts/validate.ts b/scripts/validate.ts index 7d22bce..896de18 100644 --- a/scripts/validate.ts +++ b/scripts/validate.ts @@ -9,28 +9,21 @@ const errors: string[] = []; const fail = (msg: string) => errors.push(msg); const read = (...p: string[]) => readFileSync(join(root, ...p), "utf8"); -const shipped = readdirSync(skillsDir, { withFileTypes: true }) +const authored = readdirSync(skillsDir, { withFileTypes: true }) .filter((d) => d.isDirectory()) .map((d) => d.name); -// Repo-local skills live in .agents/skills/ and are never shipped to a -// consumer, so they are exempt from the consumer tables. Their frontmatter -// must set metadata.internal: true, which hides them from the skills CLI. -const repoDir = join(root, ".agents", "skills"); -const repo = existsSync(repoDir) - ? readdirSync(repoDir, { withFileTypes: true }) - .filter((d) => d.isDirectory()) - .map((d) => d.name) - : []; - -// Skills installed from another repository by the skills CLI are recorded in -// skills-lock.json. They are not authored here, and editing them would break -// their lock hash, so they are exempt from the internal flag. -const locked = new Set( - existsSync(join(root, "skills-lock.json")) - ? Object.keys(JSON.parse(read("skills-lock.json")).skills ?? {}) - : [], -); +// Two kinds of skill live in skills/, the only folder the skills CLI discovers, and the frontmatter is +// what separates them. A skill this repository ships to consumers is listed in every consumer table; a +// repo-local one — guidance for working in *this* repository — sets metadata.internal: true, which +// hides it from the skills CLI, and is exempt from those tables. +function frontmatter(name: string): string { + return /^---\r?\n([\s\S]*?)\r?\n---/.exec(read("skills", name, "SKILL.md"))?.[1] ?? ""; +} + +const isInternal = (name: string) => /(^|\n)\s*internal:\s*true\s*($|\n)/.test(frontmatter(name)); +const repo = authored.filter(isInternal); +const shipped = authored.filter((name) => !isInternal(name)); const readme = read("README.md"); const section = read("skills", "pm-setup", "references", "AGENTS-section.md"); @@ -61,10 +54,10 @@ for (const name of shipped) { } for (const name of repo) { - const fm = checkFrontmatter(".agents/skills", name); - if (fm === null || locked.has(name)) continue; + const fm = checkFrontmatter("skills", name); + if (fm === null) continue; if (!/(^|\n)\s*internal:\s*true\s*($|\n)/.test(fm)) { - fail(`.agents/skills/${name}/SKILL.md: repo-local skill must set metadata.internal: true`); + fail(`skills/${name}/SKILL.md: a repo-local skill must set metadata.internal: true`); } } diff --git a/skills/pm-init/templates/config.md b/skills/pm-init/templates/config.md index 2cc3259..f3fc286 100644 --- a/skills/pm-init/templates/config.md +++ b/skills/pm-init/templates/config.md @@ -10,7 +10,7 @@ Read by every `pm-*` skill. Change behaviour here, not in the skills. ## Install -- Rules version: 17 +- Rules version: 18 ## Handoffs diff --git a/skills/pm-setup/references/AGENTS-section.md b/skills/pm-setup/references/AGENTS-section.md index e5c2678..43f7d97 100644 --- a/skills/pm-setup/references/AGENTS-section.md +++ b/skills/pm-setup/references/AGENTS-section.md @@ -1,4 +1,4 @@ - + diff --git a/.agents/skills/release/SKILL.md b/skills/release/SKILL.md similarity index 100% rename from .agents/skills/release/SKILL.md rename to skills/release/SKILL.md