SchOS/docs/Website/README.md

<!-- SPDX-License-Identifier: GPL-2.0-or-later -->
# The website

Three pages, two scripts, one stylesheet of its own, and the design system
underneath. No build step, no dependencies, no framework — open `index.html`
and it works, including from a `file://` URL.

```
index.html    the front page
download.html get it, write it to a stick, or build it
docs.html     the documentation reader
app.css       this site's layout — and nothing else, see below
app.js        the boot log types, sections arrive, the bar takes a shadow
docs.js       the Markdown renderer and the doc index
niveus/       Niveus, vendored. The site links niveus/dist/niveus.css and
              niveus/niveus/niveus.js
Assets/       shift.svg (logo), uberblock.svg (SchFS),
              usb.svg (downloads), pride.svg
```

## It is built on Niveus

[Niveus](../niveus/) is the interface language the project uses for everything
with a screen — this site first, applications after it. The rule that makes it
worth having is the one it enforces on this directory:

**`app.css` contains no colour, shadow, radius, type size or duration.** It is
layout: where things sit, how wide they get, when they stack. Everything else
is a token. A hex value in that file means the system is missing something, and
the answer is to add it to Niveus rather than to work around it here.

What that replaced was a 21 KB `style.css` that transcribed
[`include/gfx/theme.h`](../../include/gfx/theme.h) by hand — palette, type scale,
shadows, the lot. The intent was right and the mechanism was a copy: two files
that had to be kept in step by remembering to. Now the whole identity is one
declaration, in the `<head>` of each page:

```css
:root { --nv-brand: #7C5CFF; }
```

That is `SCH_ACCENT`, the same violet the kernel draws with. Niveus derives the
accent and its states, the link colour, the focus ring, the tint in the greys
and how far the status colours lean — for light and dark both. The site still
looks like the operating system, and now there is one number to keep true
instead of forty.

**The appearance follows the system, and remembers what you pick.** Dark is the
default because the OS is dark; the Light/Dark/Auto group in the bar is real,
and `app.js` keeps the choice in `localStorage`. An inline script in each
`<head>` reads it back before first paint, so the page never renders in one
appearance and corrects itself in front of you.

**PSOGM purple appears exactly once.** `#4B1D9A` is on the crash-screen section
and nowhere else, because [../branding/README.md](../branding/README.md) says
it means *the machine stopped* and that a colour used everywhere means nothing.
It is spelled the way Niveus spells a subtree with its own colour —
`data-nv-brand` with its own `--nv-brand` — so every role inside that section
re-derives from it rather than being painted on. If it shows up in a second
place, that is a bug in the page.

### Updating the system

`niveus/` here is a copy, so that this directory can be deployed on its own.
The original lives in [../niveus/](../niveus/) and is where changes are made:

```sh
rm -rf docs/Website/niveus && cp -r docs/niveus docs/Website/niveus
```

## The download page

`download.html` links to the ISO attached to the release on the project's Forgejo
(`https://pandor.pl/git/nexoniarz/SchOS/releases/download/v0.1.0/schos-v0.1.0.iso`). The ISO is
hundreds of megabytes and does not belong in the repository, so nothing is stored under
`docs/Website/`; publishing a release is `tools/posix/release.sh vX.Y.Z`, and **when the tag
changes, change the link and the version beside it** (only the newest release keeps its ISO).

The page is written so that nothing on it is a promise the tree cannot keep. In
particular the support table lists the three machines SchOS has booted on and nothing else,
because that is the entire bare-metal record and a compatibility list would be fiction. When
that changes, change the table; do not soften the wording.

The `dd` command is split across two lines on purpose. It was one long line
first, and the card clipped it at `conv=` — a destructive command that can
scroll half of itself out of view is a good way to take somebody's disk.

## The docs reader

`docs.html` renders the Markdown in `docs/` in the site's own theme, with the
index down the left and a table of contents down the right. Links between
documents are rewritten to stay inside the reader, so `../history/schfs.md` in
an architecture page navigates rather than downloads.

Both rails are `.nv-nav--vertical`, the current document is marked with
`aria-current="page"` rather than a class of our own, and the renderer emits
`.nv-table` and `.nv-code` — the reader is built from the same system as the
rest of the site, so a change to Niveus reaches the documentation too.

The parser is about 150 lines in `docs.js` and handles what `docs/` actually
uses: headings, fenced code, tables, lists, quotes, rules and inline marks.
A Markdown library would be larger than everything else here put together.
Every document is escaped before a single tag is emitted — the only HTML that
reaches the page is HTML `docs.js` wrote.

**This one page needs a server.** Browsers refuse `fetch()` on `file://` for
the same reason they refuse it cross-origin, so opening `docs.html` from a
file gives a panel explaining that instead of the docs. Everything else works
from a file. To read them locally:

```sh
cd /home/nexoniarz/Dokumenty/Projects/SchOS
python3 -m http.server 8000
# then http://localhost:8000/docs/Website/docs.html
```

Adding a document means adding one line to the `DOCS` array in `docs.js`. The
reader will only load a path that appears there.

## The two footer notes

Both pages carry two statements below the licence line, and both are meant to
be read rather than skimmed past.

The first is the flag, below. The second is about AI, and it says the thing
worth saying: the tool is not the measure. A project is good when the people
building it understand what was built. That claim is deliberately made next to
a link to `history/`, because that directory is where it can be checked — the
bugs are written up in full, including the wrong turns and the measurements
that disproved them. An explanation you can follow is the evidence; the byline
is not.

## The flag

`Assets/pride.svg` is in the top bar and in the footer, on every page, and it
is not seasonal. Support with an end date is marketing; this is a project that
belongs to whoever writes it. It is also deliberately small — the site is
about an operating system, and the flag is a statement, not a subject.

## The rules it follows

**The typefaces are the ones the OS ships.** Roboto for text and JetBrains Mono
for the system voice — both already in `ports/`, both already in `NOTICE`. They
are requested from the system rather than downloaded: a font file would be
larger than the entire rest of the site.

**The script is optional.** If `app.js` fails to load the page is still
complete and still readable. Everything it does is decoration, and it honours
`prefers-reduced-motion` by doing none of it. `niveus.js` is optional in the
same way — without it, state changes arrive instead of travelling.

**The boot log is real.** The lines in `app.js` are from an actual boot, not
invented. The timer calibration line is there deliberately; see section 13 of
[../history/kernel.md](../history/kernel.md) for what it cost.

## Editing it

The numbers in the *Numbers* section are measured, not estimated, and they go
stale. To refresh them:

```sh
find kernel include -name '*.c' -o -name '*.h' | xargs wc -l | tail -1
grep -c '^SYSCALL' kernel/sys/table.inc
```

The feature cards carry a badge — `runs`, `in progress`, or `designed` — and
the badge is a promise. Anything marked `runs` is in the tree and works today.
When that stops being true, change the badge rather than the wording.