docs: rewrite docs site pages to be shorter and easier to scan

- Pages now start with setup and usage, and reference material is in compact tables
- Configuration reference gives each config block a short explanation and a key/default table
- Internal detail removed from user pages, and docs that had drifted from current behavior fixed
- The status line shows today's date, set on the client, instead of the page's last-updated date
- Add changelog fragment

docs-site/.vitepress/theme/components/StatusLine.vue

@@ -1,10 +1,10 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
-import { computed } from 'vue';
-import { formatStatusLineFilePath } from '../status-line';
+import { computed, onMounted, ref } from 'vue';
+import { formatStatusLineDate, formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
-const { page, frontmatter } = useData();
+const { frontmatter } = useData();
 
 const mode = computed(() => {
   const layout = frontmatter.value.layout;
@@ -23,10 +23,10 @@ const section = computed(() => {
   return parts[0] || 'root';
 });
 
-const lastUpdated = computed(() => {
-  if (!page.value.lastUpdated) return '';
-  const date = new Date(page.value.lastUpdated);
-  return date.toISOString().slice(0, 10);
+// Set on the client only, so the prerendered HTML never bakes in the build date.
+const today = ref('');
+onMounted(() => {
+  today.value = formatStatusLineDate(new Date());
 });
 </script>
 
@@ -40,8 +40,8 @@ const lastUpdated = computed(() => {
     <div class="tui-statusline__right">
       <span class="tui-statusline__section">{{ section }}</span>
       <span class="tui-statusline__sep"></span>
-      <span v-if="lastUpdated" class="tui-statusline__date">{{ lastUpdated }}</span>
-      <span v-if="lastUpdated" class="tui-statusline__sep"></span>
+      <span v-if="today" class="tui-statusline__date">{{ today }}</span>
+      <span v-if="today" class="tui-statusline__sep"></span>
       <span class="tui-statusline__branch">GPL-3.0</span>
     </div>
   </footer>

docs-site/.vitepress/theme/status-line.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from 'bun:test';
-import { formatStatusLineFilePath } from './status-line';
+import { formatStatusLineDate, formatStatusLineFilePath } from './status-line';
 
 test('status line file path formats root home as index markdown', () => {
   expect(formatStatusLineFilePath('/')).toBe('index.md');
@@ -10,7 +10,9 @@ test('status line file path formats version archive home without trailing slash'
 });
 
 test('status line file path keeps normal docs routes as markdown files', () => {
-  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
-    'v/0.12.0/configuration.md',
-  );
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe('v/0.12.0/configuration.md');
+});
+
+test('status line date uses the local calendar day, zero padded', () => {
+  expect(formatStatusLineDate(new Date(2026, 0, 5, 23, 59))).toBe('2026-01-05');
 });

docs-site/.vitepress/theme/status-line.ts

@@ -2,3 +2,10 @@ export function formatStatusLineFilePath(routePath: string): string {
   if (routePath === '/') return 'index.md';
   return `${routePath.replace(/^\/|\/$/g, '')}.md`;
 }
+
+// Local calendar date as YYYY-MM-DD (toISOString would give the UTC date).
+export function formatStatusLineDate(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}