docs: an Astro 7 site on Pages, and a README shaped for the marketplace

The README was a single scrolling page carrying quickstart, every input, the
Deno environment contract, artifact naming, signing, orchestrator internals
and CI notes — readable as a reference, useless as a listing. A marketplace
visitor decides in about ten seconds whether the action does what they need.

So: header, one sentence, one example that is what most people will paste,
then a table of contents that links out. Everything it used to carry is on
the site rather than deleted.

docs/ is now Astro 7 + Starlight, published to https://dappco.re/build/. The
old flat markdown under docs/ still said  and listed Wails v3
as "planned once upstream stabilizes"; it is replaced, not kept alongside,
because two sets of docs rot at different rates.

Styling is the Lethean design pack ported from lthn/desktop's foundations —
the same oklch ramps, the same brand hue calibrated so --brand-400 lands on
#40c1c5, the same never-pure-black rule. Starlight's own --sl-* variables
point at those tokens rather than the palette being written twice. Light mode
is not an inversion: teal at --brand-400 fails contrast on white, so it
darkens to --brand-700. Fonts are @fontsource, bundled — no CDN, matching the
desktop app's CSP-clean posture.

Also fixes the wails3 fixture the new CI job caught:  could not
see the CLI, because the tool directive lives in go/go.mod and there was no
go.work at the project root to bring it into scope. lthn/desktop has that file
for exactly this reason; the fixture was not faithful without it. The failure
reads as , which sounds like a missing install, so
it is now documented on the Wails v3 page.

Verified: npm run build produces 12 pages;  —
the exact command CI runs — now stages the frontend and leaves a 14MB binary.

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+# Publishes docs/ to GitHub Pages at https://dappco.re/build/. Path-filtered,
+# because a change to an action has no bearing on the site and a docs typo
+# should not queue behind a three-platform build matrix.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build the site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - run: npm ci
+        working-directory: docs
+      - run: npm run build
+        working-directory: docs
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  # A pull request proves the site still builds; only main publishes it.
+  deploy:
+    name: Publish to Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

README.md

@@ -1,232 +1,73 @@
-# dAppCore/build@v4
+# dAppCore/build
 
 [![CI](https://github.com/dAppCore/build/actions/workflows/ci.yml/badge.svg)](https://github.com/dAppCore/build/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-EUPL-green.svg)](LICENSE)
+[![Licence: EUPL-1.2](https://img.shields.io/badge/licence-EUPL--1.2-blue.svg)](LICENSE)
 
-> [!NOTE]
-> For comprehensive documentation, please visit the [docs](docs/) directory.
-
-
-> I help on lots of open source projects, im tired of doing the same thing over and over again.\
-> so, I'm going to put them all together in one place.\
-> Hopefully it will help you too.
-
-General build action (multi-stack). 
-
-By default, the root action will best guess the builds you might want to run and delegate to the appropriate sub-action. You can also explicitly select a stack and enable/disable setup steps.
-
-you should write out an action that cherry-picks the parts you need; the auto-detected method works for me, based on the file structures in the tdd/* folders
-
-# Default build
-```yaml
-- uses: dAppCore/build@v4
-  with:
-    build-name: wailsApp
-    build-platform: linux/amd64
-```
-
-## Build with No uploading
+One GitHub Action that reads your repository, works out what it is, and builds
+it — Wails v3, Wails v2, or a plain Go binary, on Linux, macOS and Windows.
 
 ```yaml
+- uses: actions/checkout@v4
 - uses: dAppCore/build@v4
   with:
-    build-name: wailsApp
-    build-platform: linux/amd64
-    package: false
+    build-name: myApp
 ```
-## Inputs (high level)
-
-This repository is multi-stack. The root action detects the stack and delegates; Wails v2 is the fallback when detection finds nothing it recognises. For stack-specific inputs and examples, see the wrapper README beside each stack.
 
-Common high-level inputs on the root action include:
-- `build-name` — required; base name for outputs
-- `build-platform` — target platform (e.g., `linux/amd64`, `windows/amd64`, `darwin/universal`)
-- `build` — whether to build (default `true`)
-- `package` — upload artifacts and (on tags) publish a release (default `true`)
-- `sign` — enable platform signing when configured (default `false`)
+That detects the stack, installs the toolchains, builds, uploads the result as
+a workflow artifact, and publishes a GitHub release when the ref is a tag.
 
-Stack-specific inputs (Wails flags, signing certs, etc.) are documented in the Wails v2 wrapper: `actions/wails2/README.md`.
+## Contents
 
+| | |
+| :-- | :-- |
+| [Quickstart](https://dappco.re/build/quickstart/) | The matrix build, build-only, and apps not at the repository root |
+| [How detection works](https://dappco.re/build/detection/) | What it reads, what it concludes, how to overrule it |
+| [Wails v3](https://dappco.re/build/stacks/wails3/) | Runs your Taskfile target — so CI takes the path you do |
+| [Wails v2](https://dappco.re/build/stacks/wails2/) | Composes `wails build` flags from inputs |
+| [Go binaries](https://dappco.re/build/stacks/core/) | A Go project with no frontend |
+| [Inputs](https://dappco.re/build/reference/inputs/) | Every input, on the root action and each wrapper |
+| [Sub-actions](https://dappco.re/build/reference/sub-actions/) | Discovery, setup, build, sign and package, each callable alone |
+| [Packaging & releases](https://dappco.re/build/reference/packaging/) | Artifact naming, and what a tag changes |
+| [Code signing](https://dappco.re/build/reference/signing/) | macOS notarisation and Windows signtool |
 
+### Three platforms
 
-## Examples and stack-specific docs
+Nothing about the action changes per runner. The matrix does the work.
 
-For Wails v2 end-to-end usage, examples, and advanced options, see:
-- Wails v2 wrapper: `actions/build/wails2/README.md`
-- Wails build sub-action: `actions/build/wails2/build/README.md`
-
-The root README focuses on multi-stack concepts. Stack-specific workflows are documented alongside each stack.
-
-## macOS code signing docs moved
-
-The detailed macOS code signing and notarization guide (including `gon` JSON examples and `entitlements.plist`) now lives with the Wails v2 stack docs:
-- See `actions/build/wails2/README.md` → “macOS Code Signing (Wails v2)”
-
-
-## Configure Deno via environment variables (optional)
-
-Deno is not required. If you want to run a Deno build/asset step before Wails, you can configure it entirely via env vars — no `deno-*` inputs are needed.
-
-Precedence used by the action (inside `actions/setup`):
-- Environment variables > action inputs > defaults.
-- If nothing is provided, Deno is skipped.
-
-Supported variables:
-- `DENO_ENABLE` — `true`/`1`/`yes`/`on` explicitly enables Deno even without a build command.
-- `DENO_BUILD` — full command to run (e.g., `deno task build`, `deno run -A build.ts`).
-- `DENO_VERSION` — e.g., `v1.44.x`.
-- `DENO_WORKDIR` — working directory for the Deno command (default `.`).
-- Pass-throughs (used by Deno if present): `DENO_AUTH_TOKEN`, `DENO_DIR`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, etc.
-
-Example (job-level env):
 ```yaml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    env:
-      DENO_ENABLE: 'true'
-      DENO_VERSION: 'v1.44.x'
-      DENO_WORKDIR: 'frontend'
-      DENO_BUILD: 'deno task build'
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dAppCore/build@v4
-        with:
-          build-name: wailsApp
-          build-platform: linux/amd64
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+runs-on: ${{ matrix.os }}
+steps:
+  - uses: actions/checkout@v4
+  - uses: dAppCore/build@v4
+    with:
+      build-name: myApp
 ```
 
-Using `$GITHUB_ENV` in a prior step:
+### Build without publishing
+
 ```yaml
-- name: Configure Deno via $GITHUB_ENV
-  run: |
-    echo "DENO_ENABLE=true" >> "$GITHUB_ENV"
-    echo "DENO_VERSION=v1.44.x" >> "$GITHUB_ENV"
-    echo "DENO_WORKDIR=frontend" >> "$GITHUB_ENV"
-    echo "DENO_BUILD=deno task build" >> "$GITHUB_ENV"
 - uses: dAppCore/build@v4
   with:
-    build-name: wailsApp
-    build-platform: linux/amd64
-```
-
-Secrets example (private modules):
-```yaml
-env:
-  DENO_AUTH_TOKEN: ${{ secrets.DENO_AUTH_TOKEN }}
+    build-name: myApp
+    package: false
 ```
 
-
-## Sub-actions overview
-
-This repo is modular. You can call the root action, the Wails v2 wrapper, or any sub-action directly.
-
-- actions/discovery — detects OS/ARCH, Ubuntu version on Linux, and exposes repo/ref metadata.
-- actions/options — computes `BUILD_OPTIONS` (adds `-tags webkit2_41` on Ubuntu 24.04 when appropriate).
-- actions/setup — orchestrator that delegates to:
-  - actions/setup/go — Go, optional Garble, Wails CLI, and `gon` on macOS.
-  - actions/setup/npm — Node.js and npm install/ci in your app working directory.
-  - actions/setup/deno — optional; ENV-first Deno setup and command runner.
-  - actions/setup/conan — placeholder for future C++ builds.
-- actions/build/wails2/build — runs `wails build` and fixes executable permissions per-OS.
-- actions/build/wails3/build — runs the project's Taskfile target through `go tool wails3` and fixes executable permissions per-OS.
-- actions/sign — unified macOS and Windows signing; notarizes on tags.
-- actions/package — uploads artifacts; on tags, publishes a GitHub Release.
-
-## Stacks
-
-- Available:
-  - **wails3** — `uses: dAppCore/build/actions/build/wails3@v4`
-  - **wails2** — `uses: dAppCore/build/actions/build/wails2@v4`
-  - **core** — plain Go binaries, no frontend
-- Coming soon:
-  - cpp — via `setup/conan` and dedicated build/sign/pack steps
-
-### wails2 or wails3?
-
-Detection reads the Go module, because that is the only place the two differ
-unambiguously — both are Go plus a frontend. A module requiring `wails/v3`
-selects the v3 stack; anything else with Go and a frontend selects v2. The
-module is found at `go.mod` or `go/go.mod`, since keeping it one level down is
-a normal layout rather than an exception.
-
-The stacks are not variations on each other. v2 takes build options as CLI
-flags this action composes. v3 projects own a Taskfile, and wails3 runs targets
-in it — so the v3 stack runs the project's own target rather than
-reconstructing the command, and CI takes the same path a developer does. That
-is why the v3 stack has no `build-platform` input: the Taskfile target and the
-runner decide together, and offering a platform would be offering a choice the
-stack cannot honour.
+### Pick the stack yourself
 
 ```yaml
-# wails3 — the Taskfile decides how; the runner decides which target
 - uses: dAppCore/build@v4
   with:
     build-name: myApp
-
-# wails3, explicit target
-- uses: dAppCore/build/actions/build/wails3@v4
-  with:
-    build-name: myApp
-    task: linux:package
+    STACK: wails3
 ```
 
-Linux runners get `libgtk-4-dev` and `libwebkitgtk-6.0-dev`. Wails v3 compiles
-its GTK4 path unless the `gtk3` build tag is set, and installing the GTK3 pair
-instead fails as `Package 'gtk4', required by 'virtual:world', not found` —
-often at binding generation rather than at build, which reads as a frontend
-problem.
-
-## Setup orchestrator notes
-
-The `actions/setup` sub-action is a thin orchestrator that runs Go → npm → Deno (optional) → Conan (optional). It keeps Deno independent from Wails. Configure Deno via environment variables (ENV-first), or via inputs as a fallback. See the Deno section below and `actions/setup/deno/README.md` for details.
-
-## Orchestrator controls (root action)
-
-The root action can auto-detect your stack and auto-enable setup steps. This makes `dAppCore/build@v4` “just work” for common layouts, while still allowing full control.
-
-- Inputs (root action):
-  - `AUTO_STACK` (default `true`) — auto-select a stack based on `actions/discovery` outputs.
-  - `AUTO_SETUP` (default `true`) — allow sub-setup enabling based on env toggles.
-  - `STACK` (optional) — force a stack (e.g., `wails2`). When set, it takes precedence over auto.
-- Environment toggles (read when `AUTO_SETUP == true`):
-  - `ENABLE_GO`, `ENABLE_NPM`, `ENABLE_DENO`, `ENABLE_CONAN` — `true`/`1`/`yes`/`on` to explicitly enable those setups; otherwise defaults are used.
-- Precedence and routing:
-  - If `STACK` is set, the root action routes to that stack wrapper directly.
-  - Else if `AUTO_STACK` is enabled, the root action uses `PRIMARY_STACK_SUGGESTION` from discovery and routes accordingly (currently `wails2`).
-  - You can fully opt out by setting `AUTO_STACK: 'false'` and `AUTO_SETUP: 'false'` and calling sub-actions directly in your workflow.
-- Debug logs:
-  - Look for `[DEBUG_LOG] Auto stack=...` and `[DEBUG_LOG] npm-install resolved=...` in the logs to see decisions made.
-
-## Smarter artifact naming (package)
-
-Starting in v3, the `actions/package` sub-action composes a descriptive artifact name using discovery metadata:
-
-```text
-<build-name>_<OS>_<ARCH>_<TAG|SHORTSHA>
-```
-
-- On tag builds, the tag (e.g., `v1.2.3`) is used.
-- On branch/PR builds, the short commit SHA is used.
-- Example: `wailsApp_Ubuntu-22.04_amd64_ab12cd3` or `wailsApp_macos_arm64_v1.2.3`.
-
-When you call the root action or the `wails2` wrapper, discovery outputs are passed automatically to `actions/package`.
-
-
-## CI validations and gating
+Or call a stack directly: `dAppCore/build/actions/build/wails3@v4`.
 
-The repository includes self-tests to surface issues early and gate app builds behind fast sub-action checks:
-- Sub-action tests (gating): `discovery`, `options`, `setup/*` (go, npm, deno, conan), `sign` diagnostics, and `package` run first. App build jobs depend on these via `needs:` and will not execute if any sub-test fails.
-- Packaging smoke (Ubuntu): runs the root action locally with `package: true` on branch/PR builds and verifies artifact upload. No release is created on non-tag refs. Look for `[DEBUG_LOG] ARTIFACT_NAME=...` in logs.
-- Matrix builds with packaging: root action and the `wails2` wrapper run on Ubuntu/macOS/Windows with `package: true` on branches/PRs to confirm cross-OS uploads. Signing remains disabled.
-- Signing diagnostics (dry-run):
-  - macOS: prints `gon --version` if available or guidance if not; always green.
-  - Windows: searches common Windows SDK locations for `signtool.exe` and logs the result; always green.
+---
 
-These checks run on `push`/`pull_request` to branches and are safe on forks (no secrets required). On tag refs, real releases are only created when your workflow explicitly runs and `refs/tags/*` is detected.
+**Full documentation: [dappco.re/build](https://dappco.re/build/)**
 
-### Extending CI for new stacks (cpp)
-- Mirror the pattern: create stack-specific sub-action tests (e.g., `setup/wails3`, `setup/conan`, stack-specific build options) that are fast and deterministic.
-- Add the new test jobs to the app build job `needs:` so stack builds only run after sub-tests pass.
-- Prefer dummy artifacts with the `actions/package` sub-action for packaging checks; keep releases tag-gated.
-- Keep tests secrets-free; add tool presence diagnostics (similar to `gon`/`signtool`) for platform-specific tools.
+`@v4` follows the latest v4 release. Pin `@v4.1.0` to choose your own upgrades.

docs/.gitignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.astro/