From 1be224fe95d49959e8f54164a45b51ffc4a92986 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 16:04:20 +0000 Subject: [PATCH] docs: changelog for Aug 19 posts and apps catalogue guide Backfill changelog entries for After Skia/advisor rendering docs and the agent-rules harness essay. Add apps catalogue explanation page, document SiteMap solar system, advisor Read docs links, and HARNESS.md layering. Co-authored-by: Ryan Johnson --- docs/modules/ROOT/nav.adoc | 1 + ...-08-19 - after-skia-advisor-rendering.adoc | 6 ++ ...2026-08-19 - agent-rules-harness-blog.adoc | 5 ++ docs/modules/ROOT/pages/changelog.adoc | 11 ++++ .../pages/explanation/apps-catalogue.adoc | 56 +++++++++++++++++++ .../explanation/bootstrap-templates.adoc | 12 ++++ .../pages/explanation/site-architecture.adoc | 16 +++++- .../pages/explanation/toolchain-advisor.adoc | 9 +++ docs/modules/ROOT/pages/index.adoc | 3 + 9 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-08-19 - after-skia-advisor-rendering.adoc create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-08-19 - agent-rules-harness-blog.adoc create mode 100644 docs/modules/ROOT/pages/explanation/apps-catalogue.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 1ac5600..5de175f 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,5 +1,6 @@ * xref:index.adoc[Overview] ** xref:explanation/site-architecture.adoc[Site architecture] +** xref:explanation/apps-catalogue.adoc[Apps catalogue] ** xref:explanation/news-and-changelog.adoc[News & changelog pipeline] ** xref:explanation/theme-reveal.adoc[Theme reveal] ** xref:explanation/toolchain-advisor.adoc[Toolchain Advisor] diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-19 - after-skia-advisor-rendering.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-19 - after-skia-advisor-rendering.adoc new file mode 100644 index 0000000..8f85dc7 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-19 - after-skia-advisor-rendering.adoc @@ -0,0 +1,6 @@ += 2026-08-19 — After Skia essay and advisor rendering docs + +* Inward essay *After Skia: where rendering is headed* — Electron vs native stacks, gigabyte-scale documents, and what comes after Skia on Windows and Linux. +* Toolchain Advisor catalog adds `desktop-rendering-engines` guidance with a link to xref:general-knowledge::explanation/architecture/graphics-rendering-engines.adoc[graphics-rendering-engines] in general-knowledge. +* Desktop/GUI and web-runtime option overviews in `advisor.json` now point readers at the rendering-engine landscape before they pick a shell. +* `ToolchainAdvisor.tsx` shows a **Read docs** link when the best recommendation includes a `docs` URL. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-19 - agent-rules-harness-blog.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-19 - agent-rules-harness-blog.adoc new file mode 100644 index 0000000..63d19b2 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-19 - agent-rules-harness-blog.adoc @@ -0,0 +1,5 @@ += 2026-08-19 — Agent rules without the harness baked in + +* Inward essay on forkable `agent-rules` layering — portable templates vs machine-local `HARNESS.md` and `MEMORIES.md`. +* Clarifies that skill discovery paths (for example `~/.cursor/skills`) are harness facts, not org policy. +* Points readers at the harness-neutral guide on link:https://docs.devcentr.org[docs.devcentr.org] and the canonical `dev-centr/agent-rules` repo. diff --git a/docs/modules/ROOT/pages/changelog.adoc b/docs/modules/ROOT/pages/changelog.adoc index 99eccc1..a052882 100644 --- a/docs/modules/ROOT/pages/changelog.adoc +++ b/docs/modules/ROOT/pages/changelog.adoc @@ -2,6 +2,17 @@ Timeline of notable documentation and site changes in the devcentr.org repository. +== 2026-08-19 — Agent rules harness layering (blog) + +* Essay: Agent rules without the harness baked in — forkable templates vs `HARNESS.md` / `MEMORIES.md`. +* See xref:changelog-details/2026-08-19 - agent-rules-harness-blog.adoc[Detailed changelog]. + +== 2026-08-19 — After Skia essay and advisor rendering docs + +* Essay: After Skia — rendering headroom for dense desktop clients. +* Advisor: `desktop-rendering-engines` recommendation and **Read docs** link to general-knowledge graphics rendering guide. +* See xref:changelog-details/2026-08-19 - after-skia-advisor-rendering.adoc[Detailed changelog]. + == 2026-08-18 — Polyglot distribution research * News: Unified binary distribution under investigation. diff --git a/docs/modules/ROOT/pages/explanation/apps-catalogue.adoc b/docs/modules/ROOT/pages/explanation/apps-catalogue.adoc new file mode 100644 index 0000000..e81ced3 --- /dev/null +++ b/docs/modules/ROOT/pages/explanation/apps-catalogue.adoc @@ -0,0 +1,56 @@ += Apps catalogue +:navtitle: Apps catalogue +:description: Products, services, and standards lists on devcentr.org — data model, idea pages, and GitHub Pages routing. + +The `/apps` tree is a curated index of Dev-Centr offerings. Lists are hand-maintained in `src/lib/apps-catalog.ts`; the site does not scrape GitHub for metadata. + +== Routes + +[cols="1,2",options="header"] +|=== +| Path | Purpose + +| `/apps` +| Hub with links to the three category lists + +| `/apps/products`, `/apps/services`, `/apps/standards` +| Category lists (`CatalogPage` component) + +| `/ideas/:slug` +| Idea pages for in-ecosystem products with narrative copy and repo links + +| `/resting-lanczos` +| Image-pipeline comparison demo (listed under Products; not an idea page) +|=== + +== Data model + +`apps-catalog.ts` exports: + +* `products`, `services`, `standards` — arrays of `CatalogItem` (name, summary, `href`, optional `logo`, `ideaSlug`, `tags`, `external`) +* `ideas` — `IdeaPage` records keyed by `slug` (title, category, overview, `repos[]`) + +An item with `ideaSlug` links to `/ideas/`. External products link straight to `devcentr.app`, GitHub, or partner sites. + +Topic strings such as `Tooling · Image pipeline` are *tags*, not breadcrumb segments. Nested pages use `PageTrail` for `Apps / Category / Current`. + +== Idea pages and static export + +Vinxi's static preset prerenders file routes under `src/routes/ideas/`. The dynamic `[slug].tsx` route does not always emit HTML for new slugs before CI runs. + +When GitHub Pages must serve a slug immediately: + +. Add the idea to `ideas[]` and a matching `ideaSlug` on the catalog item. +. Add a file route such as `src/routes/ideas/uniconfig.tsx` that renders `IdeaDetail` for that slug (ensures `ideas//index.html` in `.output/public`). +. `scripts/spa-fallback.mjs` copies the SPA shell into `/ideas//` for every `slug` in `ideas[]` as a second line of defense. + +CI asserts `ideas/equivalence-engine/index.html` and `ideas/uniconfig/index.html` after build. + +== Logos + +Product marks live under `public/apps/logos/`. Omit `logo` on catalog items until a mark exists — lists stay text-only. + +== Related docs + +* xref:explanation/site-architecture.adoc[Site architecture] — full route map and build pipeline +* xref:changelog-details/2026-08-17 - uniconfig-catalog.adoc[UniConfig catalog entry] — first idea page with file route + SPA fallback diff --git a/docs/modules/ROOT/pages/explanation/bootstrap-templates.adoc b/docs/modules/ROOT/pages/explanation/bootstrap-templates.adoc index f5876ce..c563a8a 100644 --- a/docs/modules/ROOT/pages/explanation/bootstrap-templates.adoc +++ b/docs/modules/ROOT/pages/explanation/bootstrap-templates.adoc @@ -22,6 +22,18 @@ Locally, place a sibling clone at `../agent-rules` and run `pnpm sync-bootstrap- Vinxi's static preset does not write `.output/public/skills/index.html` for this client-only route. `scripts/spa-fallback.mjs` copies the SPA shell there (same as `/toolchain-advisor`) so GitHub Pages and the CI artifact check succeed. `/templates` is kept as a redirect page. +== Harness vs portable layers + +Forkable policy in `dev-centr/agent-rules` (`RULES.md`, `AGENTS.md`, `agents/*`, skill bodies) must stay harness-neutral — placeholders only, no machine paths or vendor-specific discovery rules baked in. + +Machine-local facts split further: + +* `MEMORIES.md` — workstation paths, hive layout, OS quirks +* `HARNESS.md` — how a specific AI harness loads skills (for example Cursor `~/.cursor/skills` junctions vs project-local playbooks) + +The public `/skills` page compiles bootstrap SDL and lists shipped skills; it does not duplicate harness wiring. +See the inward essay *Agent rules without the harness baked in* on link:https://devcentr.org/news/2026-08-19-agent-rules-without-the-harness-baked-in[/news] and xref:general-knowledge::how-to/bootstrap-cursor-skills.adoc[Bootstrap Cursor skills]. + == Route * Canonical: `src/routes/skills.tsx` (`/skills`) diff --git a/docs/modules/ROOT/pages/explanation/site-architecture.adoc b/docs/modules/ROOT/pages/explanation/site-architecture.adoc index 20f686f..2e3c93a 100644 --- a/docs/modules/ROOT/pages/explanation/site-architecture.adoc +++ b/docs/modules/ROOT/pages/explanation/site-architecture.adoc @@ -19,7 +19,7 @@ devcentr.org is a **static** SolidStart (Vinxi) application. | Path | Purpose | `/` -| Landing — hero, ecosystem copy, toolchain diagram, apps teaser +| Landing — hero, ecosystem copy, toolchain diagram, apps teaser, and `SiteMap` solar-system navigator | `/news`, `/blog` | News index and posts (`/blog` is an SEO alias) @@ -73,10 +73,22 @@ On push to `main`, the `deploy` job uploads `.output/public` via `actions/deploy A `.nojekyll` file is added so GitHub Pages serves `_build` and `_server` paths correctly. Custom domain `devcentr.org` is configured in the repository's Pages settings. +== Home solar system (`SiteMap`) + +The landing page footer includes an interactive orbit field (`src/components/site-map.tsx`): + +* Teal-white dwarf at the center links to link:https://devcentr.app[devcentr.app]. +* Seven planets orbit on inclined 3D circular paths (canvas-drawn tracks + CSS-positioned bodies). +* Planets link to Apps, docs portal, News, Changelog, Skills, Toolchain Advisor, and the GitHub org. +* Animation uses `requestAnimationFrame`; `prefers-reduced-motion: reduce` freezes planet positions. +* Planets scale and fade on the far side of the orbit; labels appear on hover. + +The hero background uses a separate decorative `HeroOrbit` SVG (`src/components/hero-orbit.tsx`) — not the same widget as `SiteMap`. + == Key source locations * `src/routes/` — page components -* `src/components/` — shared UI (header, footer, diagrams, advisor widget, agent skills catalog) +* `src/components/` — shared UI (header, footer, diagrams, advisor widget, agent skills catalog, `SiteMap` solar system) * `src/lib/` — catalog data, changelog loader, theme reveal, site links * `content/news/` — authored news (see xref:explanation/news-and-changelog.adoc[News & changelog pipeline]) * `public/brand/` — SVG logo marks (canonical org assets live in `.github` profile repos) diff --git a/docs/modules/ROOT/pages/explanation/toolchain-advisor.adoc b/docs/modules/ROOT/pages/explanation/toolchain-advisor.adoc index 0aae731..eefe37b 100644 --- a/docs/modules/ROOT/pages/explanation/toolchain-advisor.adoc +++ b/docs/modules/ROOT/pages/explanation/toolchain-advisor.adoc @@ -16,6 +16,14 @@ Locally, place a sibling clone at `../toolchain-advisor` or run `pnpm sync-advis If compilation fails but a committed `advisor.json` exists in the definitions repo, the sync script falls back to that file. +== Recommendations panel + +`rankRecommendations` picks the best-matching entry from `catalog.recommendations` for the current step selections. +The context panel shows its title, summary, and — when present — a **Read docs** outbound link (`best().docs`). + +Recent example: `desktop-rendering-engines` links to xref:general-knowledge::explanation/architecture/graphics-rendering-engines.adoc[graphics-rendering-engines] and summarizes when Electron/Chromium vs native stacks (Avalonia, Qt, Flutter, GPUI) fit dense, long-lived UIs. +Desktop and web-runtime *option* overviews in the catalog also reference that guide. + == Route * Page: `src/routes/toolchain-advisor.tsx` @@ -26,4 +34,5 @@ If compilation fails but a committed `advisor.json` exists in the definitions re * xref:explanation/bootstrap-templates.adoc[Agent skills] — inventory plus bootstrap-org SDL selector * xref:general-knowledge::explanation/infrastructure/toolchain-management.adoc[Toolchain management] (general-knowledge) +* xref:general-knowledge::explanation/architecture/graphics-rendering-engines.adoc[Graphics rendering engines] — linked from desktop UI recommendations * xref:devcentr::index.adoc[DevCentr] — desktop host for the same advisor definitions diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 0085edd..0bf413f 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -27,6 +27,9 @@ https://devcentr.org | Routes, build pipeline, and CI checkouts | xref:explanation/site-architecture.adoc[Site architecture] +| `/apps` lists, idea pages, SPA fallback for `/ideas` +| xref:explanation/apps-catalogue.adoc[Apps catalogue] + | News vs changelog, `build-news.mjs`, feeds | xref:explanation/news-and-changelog.adoc[News & changelog pipeline]