Bring the documentation up to the published site and fill its gapsdocs/current-state

The documents still described a site in maintenance with two languages and
a forum page with a language menu. They now describe what is published, and
three documents are new.

New, under Documents/:
- README.md: index of the documentation.
- ARCHITECTURE.md: the frontend, the backend and the forum page, what each
  serves, what the site deliberately does not contain, and how search
  engines and crawlers are treated.
- LOCALIZATION.md: the four languages, how a page picks one, what counts as
  a visitor's choice, how Hebrew text is laid out, where the text lives and
  how to add a language.
- DEVELOPMENT.md: requirements, the commands of each part, the dependency
  locks and checksums, the tests and what CI enforces.

Updated:
- README.md: the site is public; four languages and the browser-language
  default; a documentation section; the Dokka gate.
- CONTENT.md: the forum notice without a language menu; translation rules
  for four languages, including preferring the term a reader would use over
  a literal one; the crawler rules as an owner decision.
- OPERATIONS.md: the live route table; the release steps for the directory
  layout on the server, with the SELinux labelling order that caused an
  outage once; cache keys for the forum files and CDN caching; maintenance
  mode as a fallback instead of the current state; rollback by directory;
  checksum regeneration with --refresh-dependencies; the post-release check
  for four languages and right-to-left text.

No source file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 113 insertions, 0 deletions

diff --git a/Documents/DEVELOPMENT.md b/Documents/DEVELOPMENT.md
new file mode 100644
index 0000000..4781e76
--- /dev/null
+++ b/Documents/DEVELOPMENT.md
@@ -0,0 +1,113 @@
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
+
+# Development
+
+## Requirements
+
+| Tool | Version | Used for |
+| --- | --- | --- |
+| Node.js | 22.18 or newer; CI uses 24 | the frontend and all JavaScript tests |
+| npm | the one that ships with Node.js | frontend dependencies |
+| Temurin JDK | 25 | the backend |
+| Gradle | 9.6.0, the version CI installs | the backend build; the repository has no Gradle wrapper |
+
+## Frontend
+
+```text
+cd frontend
+npm ci
+npm run dev            # development server
+npm run check          # vue-tsc type check
+npm test               # Node tests
+npm run format:check   # Prettier, also over ../forum
+npm run build          # type check and production build into dist/
+```
+
+`npm run format` rewrites the files Prettier checks. The development server proxies `/api` to
+`http://127.0.0.1:5080`, the default port of a locally started backend.
+
+`.npmrc` refuses install scripts of dependencies that were not reviewed. A new dependency with an install script
+fails `npm ci` until its exact version is allowed in `package.json`.
+
+## Backend
+
+```text
+cd backend
+gradle test bootJar dokkaGenerate --no-daemon
+gradle bootRun --no-daemon      # serves on 127.0.0.1:5080
+```
+
+- `test` runs the Spring tests.
+- `bootJar` builds `build/libs/visual-xsharp-website-api-1.0.0.jar`.
+- `dokkaGenerate` builds the API documentation and is a gate: a public declaration without KDoc, a broken link or an
+  unresolved reference fails the build.
+
+### Dependency locks and checksums
+
+The backend pins every resolved version in `gradle.lockfile` and the SHA-256 of every downloaded file in
+`gradle/verification-metadata.xml`. After changing a dependency or a plugin, regenerate both and review the diff:
+
+```text
+gradle dependencies --write-locks --no-daemon
+gradle --refresh-dependencies --write-verification-metadata sha256 help test jacocoTestReport bootJar dokkaGenerate --no-daemon
+```
+
+`--refresh-dependencies` matters. With a warm local cache Gradle does not download every metadata file again and so
+does not record it; the build then passes locally and fails verification on a clean CI machine.
+
+A checksum is an integrity pin, not a trust review. Confirm the version and the repository of an artifact before
+accepting its checksum.
+
+## Forum page
+
+`forum/` has no build step. Open `forum/index.html` through any static file server, for example:
+
+```text
+python -m http.server 3022 --bind 127.0.0.1 --directory forum
+```
+
+Its script is tested by `frontend/tests/forum.test.mjs`, which runs it against a minimal fake document. To see the
+notice in another language, change the preferred language of the browser.
+
+## Tests
+
+All JavaScript tests run with `npm test` in `frontend/`.
+
+| File | Asserts |
+| --- | --- |
+| `locales.test.mjs` | the published locales, browser-language selection, the English fallback, that a stored choice wins, text direction, and when a change is remembered |
+| `seo.test.mjs` | the title, description and canonical URL of every route in every language |
+| `forum.test.mjs` | the notice in each language, the fallback, the absence of a language menu, and the theme button |
+| `site-integrity.test.mjs` | sitemap and router agreement, forum non-indexing, logo and social image shape, absence of retired links, pinned workflow actions, and that the Nginx and systemd files agree with each other |
+
+Two tests in `site-integrity.test.mjs` compare the site with a checkout of the compiler repository next to this one
+and skip themselves when it is absent.
+
+The backend tests assert the content of `/api/v1/site`, the empty health response, that the API is read-only, and
+that account and registry routes do not exist.
+
+A change to a page is not verified by these tests alone. Look at it in a browser: all four languages, both themes, a
+narrow window, and keyboard focus.
+
+## Continuous integration
+
+| Job | Enforces |
+| --- | --- |
+| `frontend` | `npm ci`, `npm audit` at moderate severity, type check, tests with coverage, format check, build |
+| `backend` | tests with coverage, the jar, and the Dokka documentation gate |
+| `frontend-coverage`, `backend-coverage` | upload coverage to Codecov |
+| `dependency-review` | reviews dependency changes of a pull request |
+| CodeQL | static analysis of the workflows, TypeScript and Kotlin |
+
+Only the coverage jobs receive an OIDC token; the jobs that install and build do not, and pull requests from forks
+skip the upload. Workflow actions are pinned to commit hashes, and a test fails when one is not.
+
+`main` is protected: changes arrive through pull requests with green checks.
+
+## Conventions
+
+- Public documents, comments, commit messages and pull request text are written in American English.
+- Every file carries the SPDX header of the repository; `REUSE.toml` covers the formats that cannot hold a comment.
+- A user-visible string is added to every locale in the same change. See [Localization](LOCALIZATION.md).
+- What the pages may claim about the language is governed by the [content contract](CONTENT.md).