Rebuild Visual XSharp language website with Vue and Kotlin Spring; add leopard identity, bilingual docs, forum placeholder, site-only API, strict CSP, 21 frontend tests, deployment runbooks, and preserve legacy ViGet redirect during maintenance

2 files changed, 368 insertions, 0 deletions

diff --git a/Documents/CONTENT.md b/Documents/CONTENT.md
new file mode 100644
index 0000000..05d5eb8
--- /dev/null
+++ b/Documents/CONTENT.md
@@ -0,0 +1,169 @@
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
+
+# Language-site content contract
+
+The site is an introduction to Visual X#, not the authority for every detail
+of the language and not a release-coverage database. This document records
+the content decisions reviewers should preserve when improving the pages.
+
+## Reader questions
+
+The homepage should answer three questions before asking the reader to
+install anything:
+
+1. What is Visual X# trying to make easier to reason about?
+2. What makes that direction different enough to investigate?
+3. What can I inspect or try today without assuming the project is finished?
+
+The current answer is readable source with explicit semantic boundaries,
+ownership that belongs to the language model, and a native pipeline whose
+stages can be inspected. These are design choices, not a benchmark claim or
+a promise that every public Spec example compiles now.
+
+The overview expands those ideas. Getting started uses commands checked
+against the compiler repository. The forum placeholder answers only whether
+a discussion service exists; today it does not.
+
+## Authority order
+
+Use the current compiler repository as the source of truth:
+
+1. `Spec/` defines intended public language behavior.
+2. `Documents/` explains development workflows and implementation limits.
+3. Compiler tests and actual outputs establish what the present build does.
+4. Website copy summarizes those sources and links readers to them.
+
+Do not reverse that order by changing the language description to match a
+convenient website sentence. If the Spec and implementation differ, describe
+the intended rule and the current limitation separately. If an example is
+only a design example, avoid presenting it as a verified runnable tutorial.
+
+The HelloWorld block on the site is copied from
+`Examples/HelloWorld/HelloWorld.vxs`. When that file changes, update the
+website example and the tests together. A program entry is a class method,
+not a top-level function. Do not invent source syntax for a visual flourish.
+
+## Page map
+
+### Home
+
+The hero introduces the project in one sentence and links to getting
+started. The principles section answers “Why Visual X#?” without requiring
+the reader to know internal intermediate-representation names. The source
+block is small on purpose. The current-state section distinguishes the
+language contract, compiler implementation, and ongoing work. It should
+never say the runtime or compiler is broadly production-ready without a
+specific tested release basis.
+
+### Overview
+
+This page is a readable conceptual map, not a substitute for `Spec/`.
+Architecture names such as Core, CorePrep, Xpp, and Xmm are useful here
+because they explain where meaning is checked and where the native boundary
+begins. They should not be used as unexplained jargon in the hero.
+
+The page distinguishes value and reference behavior as documented by the
+language. Nested generic type composition must not be simplified to “the
+outer type always wins.” A value-type generic expression remains a value
+type only when all nested type arguments are value types. If its outer or
+any nested member is a reference type, the result is a reference type.
+
+The page should not expose private/internal notes as a public citation.
+Link to the public Spec and Documents paths only. Its FAQ is a place for
+honest scope statements, not speculative launch promises.
+
+### Getting started
+
+This guide starts with the source checkout because there is no stable
+binary installer commitment. The toolchain text should match current
+`Documents/BUILDING.md`, and CLI examples should match
+`Documents/CLI.md`. The native graph belongs to Bazel; the Go developer
+command is an orchestrator and doctor. Haskell and Kotlin have their own
+component build interfaces. The supported development hosts are Windows
+10/11 and macOS Sequoia/Tahoe. Do not casually list Linux as an official
+development host based on incidental compatibility.
+
+The guide may mention package managers only for installing development
+tools. A developer installing LLVM through a package manager is not the
+same thing as the Visual X# package service. There is no site-owned package
+management flow to link from this guide.
+
+### Forum placeholder
+
+The placeholder may say the forum will come later, once the community is
+ready. It must not imply that an account can be created now or that
+discussion posts are stored elsewhere. Its default is English and dark,
+with German and light options for consistency. Its noindex status applies
+both in HTML and at the server boundary.
+
+## Translation rules
+
+`en-US` is the default and must carry complete content. `de-DE` should
+express the same meaning, not mechanically mirror sentence length. Keep
+technical spellings such as `Visual.XSharp.kts`, `CorePrep`, `Xpp`, and
+`Xmm` stable. Translate navigation labels, help text, figure descriptions,
+and accessible names. When adding a paragraph or an interaction, add both
+languages in the same change so a locale switch never leaves mixed copy.
+
+The URL is shared between language preferences. Do not emit inaccurate
+`hreflang` alternatives implying separate German URLs. The document `lang`
+attribute and browser metadata should follow the selected locale. The
+canonical URL should remain the supported route without tracking query
+parameters.
+
+## Visual identity
+
+The logo contains a leopard. Treat the leopard as an intentional mascot,
+not a decorative abstract flourish to be replaced by a generic X. Use the
+full Visual X# composition where it is large enough to read; use the
+leopard-only vector crop for small browser and header contexts. It is
+acceptable for the SVG background to be transparent on the webpage while
+the social-preview image has a dark background.
+
+Visual X# and Progmasoft share ownership, not a single interchangeable
+mark. The corporate four-color artwork does not substitute for the purple
+leopard logo. A footer may name Progmasoft as the project owner without
+turning the language homepage into a corporate landing page.
+
+## Interaction and accessibility
+
+The design favors a calm editorial layout. Animation is optional and must
+earn its place by improving clarity. Prefer short hover/focus transitions
+to large continuously moving decoration. Honor reduced-motion settings.
+Language and theme controls should be obvious, have useful accessible
+names, and remain keyboard reachable. Their slightly rounded corners are
+intentional; they should not turn into oversized pill buttons that dominate
+the navigation.
+
+The two themes should be checked for text, muted copy, border, link, and
+focus contrast, including on the code block. The mobile layout must keep
+the hero, the feature list, documentation sidebar, and navigation readable
+without horizontal overflow. A desktop screenshot alone is insufficient.
+
+## Search and indexing
+
+The sitemap lists only the three supported main-domain language routes.
+The forum placeholder stays noindex. Account, package, retired registry,
+and staging endpoints must not appear in the sitemap. Each supported route
+has its own title, description, social title/description, and canonical URL
+when the application runs. The HTML shell has English home metadata so it
+does not present a blank title before JavaScript initializes.
+
+Opening the public site later is a separate decision from writing this
+content. Until then, main-domain 503 is expected and should not be
+misdiagnosed as a broken frontend build.
+
+## Review checklist
+
+Before approving a copy change, check:
+
+- Is every language claim grounded in the public Spec or compiler tests?
+- Does the wording say “designed to” where implementation is incomplete?
+- Does the command match the latest CLI and toolchain guide?
+- Does the German version preserve meaning and technical identifiers?
+- Are internal notes and private file paths absent from the public page?
+- Are homepage and docs links still valid after repository movement?
+- Are source attribution and the Visual X# leopard identity intact?
+- Are there any unintended account or package links on this language site?
+- Can a reader distinguish site availability from compiler readiness?
diff --git a/Documents/OPERATIONS.md b/Documents/OPERATIONS.md
new file mode 100644
index 0000000..830e8a8
--- /dev/null
+++ b/Documents/OPERATIONS.md
@@ -0,0 +1,199 @@
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
+
+# Visual X# website operations
+
+This runbook covers only the language website and its not-yet-open forum page.
+The account site, corporate site, and package service have their own repositories
+and deployments. A redirect from an old package hostname is retained for
+compatibility, but it does not make package functions part of this website.
+
+## Route ownership
+
+| Host and path | Owner | Current treatment |
+| --- | --- | --- |
+| `xsharp-lang.xyz/` | Vue language site | Maintenance response until approval |
+| `xsharp-lang.xyz/docs/overview` | Vue language site | Maintenance response until approval |
+| `xsharp-lang.xyz/docs/getting-started` | Vue language site | Maintenance response until approval |
+| `xsharp-lang.xyz/api/v1/site` | Spring language API | Not exposed during maintenance |
+| `forum.xsharp-lang.xyz/` | Static placeholder | Live; noindex |
+| `viget.xsharp-lang.xyz/*` | Legacy redirect | Permanent redirect to the new package host |
+
+Do not use a catch-all `/api/` proxy for this service. The production Nginx
+configuration proxies exactly `/api/v1/site`; other `/api/` paths return 404.
+The Spring process listens only on `127.0.0.1:5080`. Its `/health` endpoint is
+for local process checks, not an advertised public route.
+
+## Local gates
+
+Run the frontend checks from `frontend/`:
+
+```text
+npm ci
+npm run check
+npm run format:check
+npm test
+npm run build
+```
+
+Run the backend gates from `backend/` with Temurin JDK 25:
+
+```text
+gradle test bootJar --no-daemon
+```
+
+The frontend tests assert canonical metadata, sitemap membership, asset shape,
+forum non-indexing, and the absence of retired site links. The Spring tests
+assert site-only API behavior, health, read-only operation, and missing account
+and registry routes. These gates are necessary but not a substitute for a
+browser review of both themes, both languages, and narrow screens.
+
+## Asset checks
+
+The source brand file is the supplied Visual X# SVG. The wide, transparent
+composition is used in the hero. The leopard-only crop is used for favicon
+and the small header mark so the animal remains legible at small sizes. The
+social preview is a 1280 × 640 PNG with an intentional background. It is
+separate from the Progmasoft corporate mark.
+
+Before publication, verify that:
+
+1. The leopard is not cropped at either its nose or lower outline.
+2. The full wordmark is readable in the hero at desktop and mobile widths.
+3. The light theme has adequate contrast, including links and focus rings.
+4. The social PNG matches the approved Visual X# identity.
+5. No page unintentionally uses a Progmasoft corporate logo.
+
+## Link checks
+
+All source links should target the current `Progmasoft/visual-xsharp` default
+branch. In particular, check the `Spec/`, `Documents/BUILDING.md`,
+`Documents/CLI.md`, and `Examples/` targets after any repository move.
+The only frontend navigation routes are `/`, `/docs/overview`, and
+`/docs/getting-started`. A retired login, registration, or package route must
+not reappear in the site shell.
+
+The forum placeholder links back to the language domain and to the compiler
+repository. While the main domain is in maintenance, that home link may
+intentionally lead to the maintenance response. Do not silently replace the
+link with a different brand domain.
+
+## Forum placeholder deployment
+
+The forum is deliberately a static document. It has no form, identity flow,
+post model, database, or discussion endpoint. Its language and theme controls
+operate entirely in the browser. The page and its server response both carry
+noindex signals. The Nginx policy only allows same-origin CSS, JavaScript, and
+images; it does not need `unsafe-inline`.
+
+Files under `forum/` are deployed as a unit. Deploying `index.html` without
+its version-matched `site.css`, `site.js`, and two SVG files can leave a
+half-styled page or controls that no longer work. The forum Nginx config
+permits only those named static paths. After copying, restore SELinux labels,
+validate the Nginx configuration, then reload Nginx. Do not turn SELinux off
+to work around a labeling mistake.
+
+Check the public URL for HTTP 200 and for these response properties:
+
+- `X-Robots-Tag: noindex, nofollow`;
+- Content Security Policy with same-origin script and style sources;
+- `site.css`, `site.js`, and the leopard SVG returning HTTP 200;
+- no login, registration, posting, or package UI; and
+- English by default, with working German and light-mode controls.
+
+The forum can be deployed while the main language domain stays in
+maintenance. Opening the real forum later is a separate product decision.
+
+## Main-site rollout gate
+
+The current main-domain server uses `ops/nginx/xsharp-maintenance.conf`.
+The future site config is `ops/nginx/xsharp.conf`. Merely committing the
+future config, building the Vue bundle, or deploying the forum does **not**
+authorize replacing the maintenance config. Keep the two configurations
+mutually exclusive in the live Nginx include directory.
+
+Before opening the main site:
+
+1. Review the English and German copy against the public language Spec and
+   current compiler behavior.
+2. Confirm the homepage actually answers why the language exists and does
+   not describe planned compiler work as a finished feature.
+3. Verify the three route bodies, both themes, keyboard focus, and responsive
+   widths in a real browser.
+4. Confirm all GitHub destinations and the forum link respond correctly.
+5. Run both build/test sets shown above.
+6. Install the Vue `dist/` contents at the static root named in the Nginx
+   config, preserving file permissions and SELinux labels.
+7. Install Java 25 on the host and test the Spring jar on loopback before
+   replacing any running API service.
+8. Confirm the old service's unrelated status function has moved to the
+   correct owner before retiring the old process.
+9. Make one explicit Nginx configuration switch, run `nginx -t`, and reload.
+10. Check the public routes and headers again from outside the server.
+
+The Java service is not required for the static homepage render. If it is
+not ready, do not pretend it is ready by rewriting the API path. Delay the
+rollout or explicitly publish static pages without the API after reviewing
+the impact of that decision.
+
+## Legacy redirect during maintenance
+
+The redirect hostname is intentionally split from the maintenance vhost.
+Requests to `viget.xsharp-lang.xyz` must produce 308 to
+`https://viget.progmasoft.com` and preserve path and query string. This is
+true while `xsharp-lang.xyz` itself returns 503. The redirect certificate
+uses the existing SAN entry for the old hostname. Do not remove the redirect
+in the course of cleaning up language-site copy.
+
+The redirect remains in the future Nginx config as well. It is routing
+compatibility, not a ViGet API or a user-facing section of the language site.
+
+## Rollback
+
+Keep the prior Nginx configuration and the last known good frontend artifact
+available until post-rollout checks pass. A rollback returns the main language
+vhost to maintenance, checks `nginx -t`, reloads Nginx, and confirms the
+expected 503. The forum and legacy redirect should remain unaffected.
+
+Do not roll back by deleting certificates, disabling SELinux, or pointing
+unrelated hostnames at the language frontend. If the Spring process fails,
+inspect its systemd journal and local `/health` response, then restore the
+previous service unit or leave the site in maintenance until the owner
+boundary is clear.
+
+## Monitoring and privacy
+
+Expected main-domain maintenance responses are 503 with `Retry-After`.
+Expected forum responses are 200 for the five static files and 404 for other
+paths. Expected legacy redirect responses are 308. After the public launch,
+the main language routes should be 200 and `/api/v1/site` should return only
+the website's non-sensitive state. A 200 from a retired login or registry
+route is a regression.
+
+Neither the static site nor the forum placeholder should send personal data
+to a third-party analytics service. Theme and language preferences are kept
+locally in the browser. Nginx and Spring logs still need normal retention
+and access-control practices, but this repository does not define an account
+database or a user profile store.
+
+## Post-release review
+
+After a public rollout, perform the same checks from a clean browser profile
+with no saved language or theme choice. Confirm that the default is dark and
+English. Switch to German, navigate through both documentation routes, and
+confirm the choice persists. Switch to light mode and repeat. The forum has
+its own local preference keys and should not unexpectedly change the main
+site's settings.
+
+Inspect the page source as well as the rendered page. The initial HTML has
+English home metadata; JavaScript updates metadata after route and locale
+changes. If search indexing of documentation routes requires fully rendered
+route-specific HTML without JavaScript, add a deliberate prerendering step
+and test its output before claiming that capability. Do not assume that a
+client-side title update alone proves crawler behavior.
+
+Check the published source link and licensing files after deployment. The
+source link must identify the version actually published, not a different
+application's repository. Keep the public logo and third-party font notices
+with the artifact. A successful HTTP response without the right assets,
+copy, and license information is not a complete rollout.