docs: improve openapi docs, update slugs

apps/api/src/routes/announcements/index.ts

@@ -16,7 +16,7 @@ export const router = createRouter()
 			tags: ["announcements"],
 			summary: "Get announcements",
 			description:
-				"Retrieve a paginated, reverse-chronological list of news, opportunities and funding calls. Each item is tagged with its `type`; fetch the full record from the endpoint for that type.",
+				"Retrieve a paginated, reverse-chronological list of news, opportunities and funding calls. Each item is tagged with its `type`; fetch the full record from the endpoint for that type. Featuring an item only affects the sort order: featured items come first, in the order they were configured, followed by the reverse-chronological remainder. Every announcement appears exactly once and is counted in `total`, so featured items occupy the start of the first page (subject to `limit`, `offset` and `type`).",
 			operationId: "getAnnouncements",
 			responses: {
 				200: {

apps/api/test/__snapshots__/openapi.test.ts.snap

@@ -18607,7 +18607,7 @@ exports[`openapi > GET /docs/openapi.json > should match the api contract snapsh
   "paths": {
     "/api/v1/announcements": {
       "get": {
-        "description": "Retrieve a paginated, reverse-chronological list of news, opportunities and funding calls. Each item is tagged with its \`type\`; fetch the full record from the endpoint for that type.",
+        "description": "Retrieve a paginated, reverse-chronological list of news, opportunities and funding calls. Each item is tagged with its \`type\`; fetch the full record from the endpoint for that type. Featuring an item only affects the sort order: featured items come first, in the order they were configured, followed by the reverse-chronological remainder. Every announcement appears exactly once and is counted in \`total\`, so featured items occupy the start of the first page (subject to \`limit\`, \`offset\` and \`type\`).",
         "operationId": "getAnnouncements",
         "parameters": [
           {

packages/website-routes/lib/interim-page-paths.test.ts

@@ -8,9 +8,12 @@ describe("resolveInterimPagePath", () => {
 		expect(resolveInterimPagePath("strategy")).toBe("/about/strategy");
 		expect(resolveInterimPagePath("join-dariah")).toBe("/get-involved/join-dariah");
 		expect(resolveInterimPagePath("regional-hubs")).toBe("/network/regional-hubs");
-		// Slugs that deliberately differ from the path leaf — the reason a hardcoded map is needed.
-		expect(resolveInterimPagePath("dariah-in-nutshell")).toBe("/about/dariah-in-a-nutshell");
-		expect(resolveInterimPagePath("working-groups-list")).toBe("/network/working-groups");
+		// A slug that deliberately differs from the path leaf — the reason a hardcoded map is needed.
+		expect(resolveInterimPagePath("transformations-a-dariah-journal")).toBe(
+			"/resources/transformations",
+		);
+		// A nested pathname that cannot be derived from the single-segment slug.
+		expect(resolveInterimPagePath("working-groups")).toBe("/network/working-groups");
 		// Footer legal pages are CMS `page` entities.
 		expect(resolveInterimPagePath("legal-notice")).toBe("/privacy-and-legal/legal-notice");
 	});

packages/website-routes/lib/interim-page-paths.ts

@@ -3,9 +3,9 @@
  *
  * CMS `page` entities carry only a single-segment slug: the WordPress import
  * (`normalizeWordPressSlug`) dropped the section prefix, so a page's real nested pathname
- * (`/about/strategy`) cannot be derived from CMS data — and slugs deliberately differ from the path
- * leaf (`dariah-in-nutshell` → `/about/dariah-in-a-nutshell`, `working-groups-list` → …), so a
- * hardcoded map is required.
+ * (`/about/strategy`) cannot be derived from CMS data — and a slug may deliberately differ from the
+ * path leaf (`transformations-a-dariah-journal` → `/resources/transformations`), so a hardcoded map
+ * is required.
  *
  * Authoritative source: DARIAH-ERIC/knowledge-base issue #703 ("Map page slugs to website paths"),
  * the hand-curated mapping. This is also the backfill source for the eventual `pages.path` column.
@@ -20,22 +20,22 @@
  */
 export const interimPagePathBySlug: Readonly<Record<string, string>> = {
 	// About
-	"dariah-in-nutshell": "/about/dariah-in-a-nutshell",
+	"dariah-in-a-nutshell": "/about/dariah-in-a-nutshell",
 	strategy: "/about/strategy",
 	"organisation-and-governance": "/about/organisation-and-governance",
 	"impact-case-studies": "/about/impact-case-studies",
 	// Network
 	"members-and-partners": "/network/members-and-partners",
 	"regional-hubs": "/network/regional-hubs",
-	"working-groups-list": "/network/working-groups",
+	"working-groups": "/network/working-groups",
 	// Resources
 	"resource-catalogue": "/resources/resource-catalogue",
 	"dariah-campus": "/resources/dariah-campus",
-	"transformation-a-dariah-journal": "/resources/transformations",
+	"transformations-a-dariah-journal": "/resources/transformations",
 	"ssh-open-marketplace": "/resources/ssh-open-marketplace",
 	// Projects / news / events / spotlights
-	"projects-list": "/projects",
-	spotlights: "/spotlight",
+	projects: "/projects",
+	spotlight: "/spotlight",
 	newsletters: "/newsletters",
 	// Get involved
 	"join-dariah": "/get-involved/join-dariah",