Refine public Hypershell site

DESIGN.md

@@ -12,7 +12,7 @@ colors:
   text-primary: "#E2E8F0"
   text-heading: "#F1F5F9"
   text-muted: "#94A3B8"
-  text-dim: "#64748B"
+  text-dim: "#6B7C95"
   border: "#4C5C80"
   white: "#FFFFFF"
 typography:
@@ -147,7 +147,7 @@ Hypershell is a personal homelab and connected-home environment. Its public webs
 
 The visual identity is **dark-only**, spacious and high-contrast. Neon pink, blue and cyan create energy and recognisability, but they are accents rather than background fills for large content areas. Structural clarity, readable content and responsive behaviour take precedence over decorative effects.
 
-Spiny is the mascot and primary visual signature. The normal Spiny asset belongs in branding and the homepage hero; the dead Spiny variant belongs on the 404 page. Mascot artwork must retain its source aspect ratio and must not be recoloured, redrawn or visually distorted without an explicit design decision.
+The accepted Hypershell H-core masterbrand is the official product identity and is used for header identity, favicon and installable web-app icon derivatives. Spiny is the mascot and personality-bearing visual signature: normal Spiny belongs in the homepage hero and related expressive artwork, while dead Spiny belongs on the 404 page. Mascot artwork must retain its source aspect ratio and must not be recoloured, redrawn or visually distorted without an explicit design decision. Web derivatives are generated from the accepted brand-workspace assets and record their source hashes in `src/data/brand-assets.json`; the derivatives never become a competing brand authority.
 
 This file records the implemented design system. Keep it synchronized with `src/styles.css` whenever normative visual values change. The website must remain static and must not acquire runtime third-party design dependencies merely to reproduce this system.
 
@@ -204,7 +204,7 @@ Glass cards use a partially transparent elevated surface, a faint internal radia
 
 The page background combines three low-opacity radial accent fields with a faint technical grid. The grid must recede behind content and fade toward the bottom. It is environmental texture, not foreground decoration.
 
-Use `backdrop-filter` only as progressive enhancement. Content must remain understandable when blur is unsupported.
+Use `backdrop-filter` only as progressive enhancement. Content must remain understandable when blur is unsupported. **Accepted product constraint:** the glass blur treatment is intentionally retained at mobile widths on cards and appropriate mobile surfaces; do not propose disabling or reducing it merely as speculative performance polish. Reconsider it only on measured device/runtime evidence or an explicit new product request.
 
 ## Shapes
 
@@ -228,25 +228,37 @@ Render both with `object-fit: contain`. The profile portrait uses a square conta
 
 ### Header and navigation
 
-The header is transparent at the top and gains a translucent base-surface background, subtle border, shadow and blur after scrolling. Desktop navigation is centered. Mobile navigation uses a native `details` disclosure and appears as an elevated menu beneath the header, so it remains usable without JavaScript.
+The header is transparent at the top and gains a translucent base-surface background, subtle border, shadow and blur after scrolling. The accepted H-core masterbrand is the header mark. Desktop navigation is centered. Mobile navigation uses a native `details` disclosure and appears as an elevated menu beneath the header, so it remains usable without JavaScript.
 
-Active and hover navigation states use heading-colour text and a thin brand-gradient indicator. Keyboard focus uses a clearly visible cyan outline with offset. Closing the enhanced mobile menu with Escape returns focus to its summary control.
+Active and hover navigation states use heading-colour text and a thin brand-gradient indicator. Keyboard focus uses a clearly visible cyan outline with offset. Closing the enhanced mobile menu with Escape returns focus to its summary control. **Accepted product constraint:** the public `Private dashboard` launcher intentionally remains in the public header as the operator shortcut into the authenticated dashboard. Do not propose removing or hiding it merely as generic security/privacy polish; reconsider only on new exposure evidence, a changed authentication boundary or an explicit product request.
 
 ### Hero
 
-The hero centers Spiny, an uppercase eyebrow, the oversized Hypershell wordmark and concise explanatory copy. Keep one dominant visual focus. Decorative orbit rings and glows must remain subdued.
+The hero centers Spiny, an uppercase eyebrow, the oversized Hypershell wordmark, one concise explanatory sentence and one short signature line. A compact three-part scope strip may show the build-derived domain, core-initiative and maintained-software counts as navigational context. The scope strip remains subordinate to the wordmark. Keep one dominant visual focus and keep decorative orbit rings and glows subdued.
 
-Spiny floats slowly. On initial page load, two temporary colour-separated glitch layers may animate over the base image and must then stop. Do not run the glitch continuously. Respect `prefers-reduced-motion` by disabling glitch and reveal effects.
+On initial page load, Spiny and the wordmark may each receive one temporary colour-separated glitch treatment as a short startup sequence. After startup, brief intermittent glitches may recur on either Spiny or the wordmark while the hero is visible; they must remain short, non-continuous, pause when the page or hero is not visible, and respect `prefers-reduced-motion` by disabling glitch and reveal effects.
+
+### Rationale section
+
+The **Why Hypershell** section appears after the public domain overview and before Architecture. It explains why the environment is treated as one evolving system rather than presenting more product inventory. Use one strong statement plus three restrained numbered principles; do not turn it into another card catalogue.
 
 ### Glass cards
 
-Cards contain related information and use the shared glass treatment. Domain cards use a bordered icon tile, heading, concise description and optional tags. Project cards use small uppercase metadata, a status dot and a larger title.
+Cards contain related information and use the shared glass treatment. Domain cards use a bordered icon tile, heading, concise purpose-oriented description and optional tags. Domain copy explains what each part enables; Architecture explains how responsibilities are organized.
+
+The public narrative order is **Inside the Lab → Why Hypershell → Architecture → Projects → About**. The Projects section separates **Core initiatives** from **Maintained software** and shows build-derived counts for both plus a combined project total. Core initiatives retain a spacious two-column treatment. Maintained software uses a denser three-column desktop grid, falls back to two columns on medium screens and one column on narrow screens, and may be filtered by safe curated categories. Filter controls are progressive enhancement: without JavaScript every project remains visible.
+
+Repository cards show Public or Private only as neutral visibility metadata; repository visibility must never reuse lifecycle-status colour semantics. Each card displays a safe curated category and a compact provenance label from the single presentation owner `src/data/project-presentation.json`; raw GitHub topics are not a public presentation source. That presentation file also owns the small explicit-include set, display-name exceptions, presentation order and activity exclusions without copying GitHub-owned descriptions, visibility or URLs. Public repository cards expose an explicit text GitHub action anchored at the lower-right of the card, while private repository URLs remain undisclosed. GitHub remains the source for repository name, description, visibility, URL and public release/update timestamps.
+
+Core and repository cards have stable fragment IDs and link to generated static `/projects/<slug>/` detail pages. Those pages provide a shareable public project profile without exposing private repository URLs or private activity. The maintained-software filters remain progressive enhancement; on narrow/mobile layouts their filter bar stays sticky beneath the fixed header and the controls retain at least a 44px practical touch target.
+
+A compact Recent activity block may follow maintained software. It shows at most three public selected projects, preferring the latest public GitHub Release and falling back to the repository update timestamp when no release exists. Private repository activity is never surfaced, and the website repository itself is intentionally excluded to avoid self-referential activity noise.
 
 Hover effects enhance existing borders and glow; they must not move content enough to disturb reading or pointer targeting.
 
 ### Architecture diagram
 
-The public architecture view is a simplified responsibility stack, not an infrastructure topology. Layers are rounded, low-contrast surfaces connected by cyan arrows. Selected boundary layers may receive the brand-gradient border treatment.
+The public architecture view is a simplified responsibility stack, not an infrastructure topology. Layers are rounded, low-contrast surfaces connected by cyan arrows. Each row carries a restrained layer-purpose label so the hierarchy can be scanned before reading every capability. Selected boundary layers may receive the brand-gradient border treatment.
 
 Never expose internal addresses, ports, hostnames, credentials or a complete attack-relevant topology through this component.
 
@@ -256,12 +268,25 @@ Primary-looking links use an elevated dark fill with a gradient border rather th
 
 Interactive touch targets should be at least 44px high where layout permits. All interactive elements require visible hover and keyboard-focus states. Avoid interactions that depend exclusively on hover.
 
+### Public metadata
+
+The web-app manifest uses the Hypershell product name, H-core masterbrand derivatives and the dark `#050816` theme/background. Publish compact PNG/ICO favicon assets rather than wrapping a raster image in a large base64 SVG. `/.well-known/security.txt` provides the canonical public security contact and the build fails when its expiry is less than 90 days away. The homepage publishes a public-only `SoftwareSourceCode` `ItemList`; generated project pages are included in the sitemap with available `lastmod` dates. Public HTML revalidates, versioned CSS/JavaScript may use long-lived immutable caching, and the web-server layer provides zstd/gzip compression. Public usage insight is server-side and privacy-bounded: no client analytics script is required.
+
 ### Mascot and imagery
 
-Use the supplied mascot assets rather than approximations. The normal Spiny is used for the brand icon and homepage hero. Dead Spiny is reserved for the custom 404 page. The portrait is presented in a square crop with a restrained gradient glow.
+Use accepted brand-workspace assets rather than approximations. The H-core masterbrand supplies official identity derivatives for the header, favicon and installable web app. Normal Spiny is reserved for the homepage hero and mascot/personality use; Dead Spiny is reserved for the custom 404 page. The hero prefers an optimized WebP derivative with a PNG fallback, and the social preview uses an optimized JPEG derivative while the source PNG remains available. The portrait is presented in a square crop with a restrained gradient glow.
 
 Images must declare intrinsic width and height to prevent layout shift. Decorative duplicate glitch layers are hidden from assistive technology.
 
+## Accepted product constraints
+
+These are human-accepted product decisions, not open optimization suggestions:
+
+- **Public dashboard launcher stays.** The authenticated `Private dashboard` shortcut remains visible in the public header unless new exposure/authentication evidence or an explicit product request changes that decision.
+- **Mobile glass blur stays.** Existing glass/backdrop blur remains part of the mobile visual treatment unless measured device/runtime evidence or an explicit product request justifies a change.
+
+Generic security or performance reviews must treat these as accepted constraints rather than repeatedly reopening them without new evidence.
+
 ## Do's and Don'ts
 
 - **Do** preserve the dark-only navy foundation and the pink-blue-cyan accent relationship.

README.md

@@ -4,15 +4,15 @@
 
 Static public website for `hypershell.eu` and `www.hypershell.eu`.
 
-Hypershell is Ronald's personal homelab and connected home environment. The site presents its major domains, selected projects, simplified public architecture and visual identity without exposing internal topology or operational details.
+Hypershell is Ronald's personal homelab and connected home environment. The site presents its major domains, design rationale, simplified public architecture, core initiatives and maintained software without exposing internal topology or operational details.
 
 ## Design
 
 The canonical, agent-readable design system is documented in [`DESIGN.md`](DESIGN.md) following the Google Labs DESIGN.md format.
 
 - dark-only Hypershell neon branding;
 - no runtime third-party dependencies;
-- responsive one-page layout;
+- responsive homepage plus generated static project detail pages;
 - semantic HTML and keyboard-visible focus states;
 - reduced-motion support;
 - custom branded 404 page;
@@ -36,7 +36,7 @@ hypershell-website/
 ./scripts/build.sh
 ```
 
-The build has no package-manager dependency. It fetches current GitHub repository metadata at build time, renders selected Hypershell projects into the static site, creates `dist/`, derives a content-based asset version and validates every required output asset.
+The production build has no package-manager dependency. It fetches current GitHub repository metadata and latest public releases at build time, renders the homepage plus static project detail pages, generates the only published sitemap from current project metadata, creates `dist/`, derives a content-based asset version and validates every required output asset and the `security.txt` expiry horizon.
 
 Live project discovery requires authenticated GitHub repository metadata access. The build accepts `GH_TOKEN` or `GITHUB_TOKEN`; alternatively it reads a protected token file from `GITHUB_TOKEN_FILE` or, by default, `.runtime-secrets/github-token` when that file exists. `.runtime-secrets/` is ignored by Git. The token is used only for the GitHub API request and is never written to `dist/`. A build fails if authenticated repository metadata cannot be retrieved.
 
@@ -46,9 +46,21 @@ A repository is included automatically when it is active and its GitHub **Websit
 https://www.hypershell.eu/#projects
 ```
 
-Public repositories receive a GitHub link. Private repositories may expose their selected name, description and `PRIVATE` visibility label but never their repository URL. Selected repositories must have a non-empty GitHub description or the build fails. GitHub-backed project cards are sorted alphabetically by their display name; display-name exceptions live in `src/data/project-display-names.json`, otherwise the repository name is humanized. Non-GitHub projects remain supported through `src/data/manual-projects.json` and keep their declared order.
+The homepage flows from the lab domains through **Why Hypershell** and the simplified public architecture before reaching Projects. The Projects section renders non-GitHub work from `src/data/manual-projects.json` as **Core initiatives** and selected repositories as **Maintained software**. Dynamic counts are derived at build time for the six public domains, core initiatives, maintained repositories and combined project total. Public repositories receive an explicit GitHub link. Private repositories may expose their selected name, description and neutral `PRIVATE` visibility label but never their repository URL. Repository visibility is metadata, not lifecycle status. Selected repositories must have a non-empty GitHub description or the build fails.
 
-For deterministic tests or an explicitly pre-fetched metadata input, set `GITHUB_REPOSITORIES_FILE` to a JSON file with GitHub repository objects.
+GitHub remains the source for repository name, description, visibility, URL and public release/update timestamps. `src/data/project-presentation.json` is the single local presentation owner for safe categories, display-name exceptions, explicit includes, presentation order, provenance labels and activity exclusions; it does not duplicate GitHub descriptions or URLs. Every core initiative and maintained repository receives a stable homepage fragment and a generated `/projects/<slug>/` detail page. Private repository URLs and private activity are never emitted. Recent activity prefers the latest public GitHub Release and falls back to repository update time; the website repository is excluded from this block to avoid self-referential noise.
+
+For deterministic tests or explicitly pre-fetched metadata, set `GITHUB_REPOSITORIES_FILE` to a JSON file with GitHub repository objects and optionally `GITHUB_RELEASES_FILE` to a mapping of repository names to release objects.
+
+### Brand derivatives
+
+The accepted H-core masterbrand is used for official website identity; Spiny remains the mascot and homepage/404 personality layer. Web-specific PNG/ICO/WebP/JPEG derivatives are generated from accepted sources without modifying the canonical brand workspace:
+
+```sh
+BRAND_ROOT=/path/to/hypershell-brand ./scripts/sync-brand-assets.sh
+```
+
+`src/data/brand-assets.json` records the accepted source paths and hashes used for those derivatives. This maintenance step uses the repository's digest-pinned Playwright image, but the resulting production website has no Node.js or browser runtime dependency.
 
 ## Feedback and contributions
 
@@ -70,7 +82,9 @@ Tests are project-specific and run in an ephemeral digest-pinned Playwright cont
 
 GitHub CI runs the same repository test entry point. Browser-test dependencies are locked, Dependabot tracks npm and GitHub Actions updates, external Actions are pinned to full commit SHAs, GitHub CodeQL default setup scans the maintained JavaScript/Python/workflow source, and OpenSSF Scorecard publishes an independent repository-security signal.
 
-The suite covers project selection/rendering, responsive layout, overflow, mobile navigation with and without JavaScript, keyboard focus restoration, mascot proportions, glitch lifecycle, project-card consistency, social metadata, the custom 404 response and WCAG A/AA checks through Axe.
+The suite covers project selection/rendering, consolidated presentation metadata, provenance, generated detail pages and sitemap, release-first public activity, dynamic counts/categories/filtering, responsive layout and sticky mobile filters, overflow, mobile navigation with and without JavaScript, retained dashboard/mobile-blur contracts, keyboard focus restoration, brand/mascot delivery, intermittent hero glitch lifecycle, manifest/security/structured metadata, project-card consistency, social metadata, the custom 404 response and WCAG A/AA checks through Axe.
+
+The public asset set includes a dark Hypershell web-app manifest and `/.well-known/security.txt`. The favicon and installable-app icon set is derived from the accepted H-core masterbrand; the previous SVG wrapper around an embedded raster image is intentionally not published. The hero prefers an optimized Spiny WebP derivative with PNG fallback, and social metadata uses an optimized 1200×630 JPEG derivative.
 
 ## Deploy
 

public/.well-known/security.txt

@@ -0,0 +1,5 @@
+Contact: mailto:info@hypershell.eu
+Expires: 2027-09-08T00:00:00Z
+Preferred-Languages: en, nl
+Canonical: https://www.hypershell.eu/.well-known/security.txt
+Policy: https://github.com/X1pheR/hypershell-website/security/policy