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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 11 additions & 0 deletions docs/modules/ROOT/pages/changelog.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
56 changes: 56 additions & 0 deletions docs/modules/ROOT/pages/explanation/apps-catalogue.adoc
Original file line number Diff line number Diff line change
@@ -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/<slug>`. 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/<slug>/index.html` in `.output/public`).
. `scripts/spa-fallback.mjs` copies the SPA shell into `/ideas/<slug>/` 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
12 changes: 12 additions & 0 deletions docs/modules/ROOT/pages/explanation/bootstrap-templates.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down
16 changes: 14 additions & 2 deletions docs/modules/ROOT/pages/explanation/site-architecture.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
9 changes: 9 additions & 0 deletions docs/modules/ROOT/pages/explanation/toolchain-advisor.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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
3 changes: 3 additions & 0 deletions docs/modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
Loading