Merge pull request '#35: restructure README into canonical sections (closes #11)'

README.md

@@ -1,43 +1,49 @@
 # lora.vegas
 
-Las Vegas Meshtastic and LoRa community website.
+`lora.vegas` is the website of the Las Vegas Meshtastic and LoRa community: a
+single-page static site, built with Hugo, by [@sneak](https://sneak.berlin).
 
-## About
-
-This site provides information about the Las Vegas mesh networking community,
-including:
+It publishes what the local mesh needs in one linkable place:
 
 - Mesh channel configurations
-- Community coordination (Discord, Signal)
+- Community coordination links (Discord, Signal)
 - Meetup information
 - Local resources
 
-## Contributing
+## Getting Started
+
+From a fresh clone, `make setup` installs every build dependency (git, make, go,
+the pinned Hugo, node/npm) and the git pre-commit hook, and `make serve` starts
+the Hugo development server:
+
+```bash
+git clone git@git.eeqj.de:sneak/lora.vegas.git
+cd lora.vegas
+make setup
+make serve
+```
+
+Then open <http://localhost:1313> to preview the site.
+
+To produce the production build, which writes the rendered site to `public/`:
+
+```bash
+make test
+```
+
+Before committing, run the full check suite — the production build, the lint
+build, and the formatting check:
+
+```bash
+make check
+```
+
+`make fmt` rewrites the repo's markdown and CSS to the project's prettier
+settings; run it if `make check` fails on formatting.
 
 To contribute to this site, contact **sneak@sneak.berlin** for git repository
 access.
 
-## Technical Details
-
-This is a static site built with Hugo. The site is deployed automatically via
-GitHub Actions.
-
-### Local Development
-
-```bash
-hugo server
-```
-
-Visit http://localhost:1313 to preview.
-
-### Build
-
-```bash
-hugo
-```
-
-Output will be in the `public/` directory.
-
 ## Entrypoints
 
 This repository adheres to the
@@ -55,7 +61,8 @@ provide:
 - `script/test` — the correctness check: a clean `hugo --minify` production
   build
 - `script/lint` — a clean build that surfaces broken links and path collisions
-- `script/fmt` — format the repo's own top-level markdown docs with prettier
+- `script/fmt` — format every markdown and CSS file in the repo with prettier;
+  the exclusions live in `.prettierignore` with the reason for each
 - `script/fmt-check` — check that formatting (read-only)
 - `script/check` — run `script/test`, `script/lint`, then `script/fmt-check`;
   modifies no tracked files
@@ -72,6 +79,38 @@ green it did not earn. A bare `docker build .` fails closed on the Dockerfile's
 
 A convenience `make serve` target runs `hugo server` for local preview.
 
+## Rationale
+
+The Las Vegas Meshtastic and LoRa community needs one durable, linkable place
+for its channel configurations and group links. Those details otherwise live
+inside a Discord or Signal thread, where they scroll away, cannot be linked to
+from outside, are invisible to anyone who has not already joined, and quietly go
+stale. A static site at a stable domain is the opposite of that: one URL to hand
+to a newcomer, and one place to correct when a channel changes.
+
+## Design
+
+The site is a single page. All of its content is one Hugo content file,
+`content/_index.md`, rendered by a minimal theme vendored in-repo at
+`themes/loravega/` — there is no upstream theme dependency and no submodule.
+
+The theme's `layouts/_default/baseof.html` inlines
+`themes/loravega/static/css/style.css` into a `<style>` block with Hugo's
+`readFile`, so the whole site ships as a single HTML document with no external
+CSS request and no second round trip.
+
+`hugo --minify` builds the site into `public/`. Deployment is automatic: on push
+to `main`, the Gitea Actions workflow `.gitea/workflows/deploy.yml` builds the
+site and publishes `public/` to Cloudflare Pages.
+
+## TODO
+
+The live task list is in [TODO.md](TODO.md).
+
 ## License
 
 Content is provided as-is for community use.
+
+## Author
+
+[@sneak](https://sneak.berlin)

TODO.md

@@ -28,6 +28,23 @@ remaining policy scaffold is otherwise complete.
 
 # Completed Steps
 
+- 2026-08-09: restructured `README.md` into the canonical section set (closes
+  #11): a Description first line, then Getting Started, Entrypoints, Rationale,
+  Design, TODO, License, Author. The non-standard About / Contributing /
+  Technical Details headings are gone, but nothing they held was dropped — the
+  bullet list of what the site publishes moved under the Description, the
+  contribute contact and the local-preview instructions moved into Getting
+  Started. Getting Started was written against the current `Makefile` rather
+  than the old prose: there is no `make build` target, so the former "Build:
+  `hugo`" instruction is now `make test`, and the former "Local Development:
+  `hugo server`" is `make setup` then `make serve`. Two stale claims fixed: the
+  site is deployed by Gitea Actions to Cloudflare Pages, not "GitHub Actions",
+  and the Entrypoints bullet for `script/fmt` still described the
+  top-level-markdown-only scope that #12 replaced with `'**/*.md'` and
+  `'**/*.css'`. The License section body is deliberately untouched — it is owned
+  by #10, which is blocked on the owner's choice of license, and the Description
+  sentence is likewise missing the license clause the policy calls for until #10
+  lands. Design section claims were verified against the tree, not assumed
 - 2026-08-09: widened the prettier gate from top-level markdown to `'**/*.md'`
   and `'**/*.css'` (closes #12). `themes/loravega/static/css/style.css` was
   never formatted or gated even though it is inlined into every page; it is now
@@ -161,9 +178,6 @@ remaining policy scaffold is otherwise complete.
   here (#20)
 - Move the deploy container to a pinned node 22 so the wrangler pin can advance
   past 4.86.0 (#21)
-- Rework README.md into the standard sections: Description, Getting Started,
-  Rationale, Design, TODO, License, Author (currently About, Contributing,
-  Technical Details, License)
 - Sync the reformat of `REPO_POLICIES.md` back upstream to `prompts` so the
   canonical copy is clean under the shared prettier settings and future syncs
   are a straight byte copy