docs: standardize README and add repository documentation guide

README.md

@@ -4,29 +4,7 @@ RadioSync Hub is a self-hosted podcast synchronization service for selected Poli
 
 The project is designed to run on a home server or Raspberry Pi using Docker.
 
-## Supported stations
+[Features](#features) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Architecture](#architecture) · [Limitations](#limitations) · [Development](#development) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
-
-### Radio 357
-
-- Fetches podcast metadata from the Radio 357 content API.
-- Performs an initial metadata index of the available catalogue.
-- On later synchronizations, stops when it reaches a page containing only known episodes.
-- Retrieves protected audio URLs separately using an authenticated gateway.
-- Stores and refreshes the Radio 357 access token.
-
-### Radio Nowy Świat
-
-- Fetches programme and episode pages from the station website.
-- Uses a logged-in web session for patron-only content.
-- Stores the authenticated cookies securely in the local database.
-- Synchronizes recent episodes before gradually backfilling older pages.
-- Uses an adaptive cooldown for programmes that publish infrequently.
-- Retries request timeouts up to three times with a 30-second delay.
-- Reports unavailable episode players as warnings instead of failing the entire synchronization.
-
-### Radio Jazz FM
-
-Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discovers available programmes and links directly to the original feeds hosted by the station.
 
 ## Features
 
@@ -44,35 +22,39 @@ Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discove
 - Encrypted configuration values in SQLite, including passwords, tokens, and cookies.
 - Docker Compose deployment.
 
+### Supported stations
+
+#### Radio 357
+
+- Fetches podcast metadata from the Radio 357 content API.
+- Performs an initial metadata index of the available catalogue.
+- On later synchronizations, stops when it reaches a page containing only known episodes.
+- Retrieves protected audio URLs separately using an authenticated gateway.
+- Stores and refreshes the Radio 357 access token.
+
+#### Radio Nowy Świat
+
+- Fetches programme and episode pages from the station website.
+- Uses a logged-in web session for patron-only content.
+- Stores the authenticated cookies securely in the local database.
+- Synchronizes recent episodes before gradually backfilling older pages.
+- Uses an adaptive cooldown for programmes that publish infrequently.
+- Retries request timeouts up to three times with a 30-second delay.
+- Reports unavailable episode players as warnings instead of failing the entire synchronization.
+
+#### Radio Jazz FM
+
+Radio Jazz FM is treated as a catalogue of public RSS feeds. The service discovers available programmes and links directly to the original feeds hosted by the station.
+
 ## Requirements
 
 - Docker Engine
 - Docker Compose
 - A Gitea or Git server is optional and only needed for source-code hosting
 
-## Configuration
+## Getting started
 
-Create a local `.env` file next to `docker-compose.yml`:
+First complete [Configuration](#configuration), then start the service:
-
-```env
-RADIOSYNC_SECRET_KEY=generate-a-long-random-value
-RADIOSYNC_CONFIG_KEY=generate-a-fernet-key
-```
-
-Generate the values with:
-
-```bash
-python -c "import secrets; print(secrets.token_urlsafe(48))"
-python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-```
-
-`RADIOSYNC_SECRET_KEY` signs browser sessions. `RADIOSYNC_CONFIG_KEY` encrypts sensitive values stored in SQLite.
-
-Keep both keys safe and do not change them after the application has stored credentials. Losing or changing the encryption key makes existing encrypted configuration unreadable.
-
-The repository includes `.env.example` as a template. Never commit `.env`, the SQLite database, or the contents of `data/`.
-
-## Running with Docker
 
 The repository contains `docker-compose.example.yml` as a portable default configuration. Copy it to `docker-compose.yml` before starting the service:
 
@@ -108,7 +90,29 @@ docker compose down
 
 The `data/` directory is mounted as a Docker volume, so the database survives container rebuilds.
 
-## Dashboard and feeds
+## Configuration
+
+Copy `.env.example` to `.env` in the repository root, then set both keys:
+
+```dotenv
+RADIOSYNC_SECRET_KEY=generate-a-long-random-value
+RADIOSYNC_CONFIG_KEY=generate-a-fernet-key
+```
+
+Generate the values with Python 3 (only needed for this setup step):
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(48))"
+python3 -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
+```
+
+`RADIOSYNC_SECRET_KEY` signs browser sessions. `RADIOSYNC_CONFIG_KEY` encrypts sensitive values stored in SQLite.
+
+Keep both keys safe and do not change them after the application has stored credentials. Losing or changing the encryption key makes existing encrypted configuration unreadable.
+
+The repository includes `.env.example` as a template. Never commit `.env`, the SQLite database, or the contents of `data/`.
+
+## Usage
 
 The dashboard allows you to:
 
@@ -130,7 +134,7 @@ Available feed endpoints:
 
 Station names are `radio357`, `rns`, and `jazz`.
 
-## Diagnostics
+### Diagnostics
 
 Unexpected responses are recorded with a diagnostic code such as:
 
@@ -144,7 +148,7 @@ Unexpected responses are recorded with a diagnostic code such as:
 
 When possible, the response is saved under `data/diagnostics/` for investigation. Diagnostic snapshots can contain website HTML and should be treated as local operational data.
 
-## Project structure
+## Architecture
 
 ```text
 .
@@ -167,7 +171,7 @@ When possible, the response is saved under `data/diagnostics/` for investigation
 └── .env.example
 ```
 
-## Important limitations
+## Limitations
 
 This project relies on unofficial endpoints and the current HTML structure of the station websites. The stations may change those interfaces without notice. The scrapers therefore validate responses, retry transient failures, preserve existing data, and report unexpected changes through the dashboard and ntfy.
 
@@ -192,6 +196,14 @@ The application currently has no dedicated automated test suite. At minimum, val
 python -m py_compile main.py core/*.py core/scrapers/*.py
 ```
 
-## Collaboration with AI
+## Documentation
+
+[README style guide](docs/README-STYLE.md).
+
+## Credits
 
 This project was developed with assistance from GitHub Copilot. Human decisions, configuration, deployment, and responsibility for running the service remain with the project owner.
+
+## License
+
+No project-level license file is currently included in this repository. Third-party components retain their own licenses.

docs/README-STYLE.md

@@ -0,0 +1,74 @@
+# Repository README standard
+
+Version: 1.0. Documentation language: English.
+
+A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard.
+
+## Original projects
+
+Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document.
+
+Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template.
+
+| Section | Content |
+| --- | --- |
+| Features | Concrete capabilities and supported use cases. |
+| Requirements | Runtime, hardware, services, and build prerequisites; distinguish build from runtime needs. |
+| Getting started | Shortest complete path from checkout or download to a working result, including initial setup. |
+| Configuration | Settings, defaults, required values, and example files. Explain prerequisites before commands that need them. |
+| Usage | Common workflows, commands, and expected output or artifact locations. |
+| Architecture | Project layout, interfaces, data model, or hardware overview. |
+| Limitations | Known constraints and validation boundaries; keep critical setup constraints near the affected step too. |
+| Development | Build, test, validation, and release instructions supported by repository files. |
+| Documentation | Links to detailed guides, diagrams, screenshots, and this style guide. |
+| Credits | Contributors, reused work, upstream sources, and existing AI-assistance disclosures. |
+| License | Link to the actual project license; state explicitly when no project-level license file exists. |
+
+Keep specialized content under these headings using `###` and `####`. For example, put power variants under Configuration, pinouts under Architecture, and schematic downloads under Documentation or Architecture. Small component READMEs can use only the relevant sections and link back to the root README.
+
+## Forks
+
+Use the same formatting rules, but introduce the fork before describing the original project. Start with one title, a short fork description, and clearly labeled links to upstream and the fork repository.
+
+Use these headings in order, omitting optional sections when unnecessary:
+
+1. Fork purpose
+2. Changes from upstream
+3. Requirements
+4. Getting started
+5. Configuration
+6. Usage
+7. Architecture
+8. Limitations
+9. Development
+10. Upstream maintenance
+11. Documentation
+12. Credits
+13. License
+
+Explain why the fork exists, list its differences, and identify where to obtain its builds. Clearly label links to upstream builds, contribution channels, and screenshots. Include upstream synchronization instructions based on the actual workflow, and checks needed after merges.
+
+Keep inherited documentation in `README.upstream.md` at the repository root. Keeping it beside the original README preserves relative links to assets. Retain upstream attribution, donations, and license notices there. Label any local corrections; this file is inherited documentation, not a claim to be the latest upstream version. After an upstream merge, refresh the inherited file and review the fork README separately. Do not overwrite the fork's explanation with the upstream README.
+
+Borrowing a component or taking inspiration from another project does not by itself make the entire repository a fork. Explain that relationship under Credits and preserve component licensing.
+
+## Markdown and accuracy
+
+- Write documentation in English. Preserve proper names and UI labels as shown in the product.
+- Use one H1, sentence-case headings, and consecutive heading levels. Do not number headings.
+- Separate paragraphs, headings, lists, tables, and fenced blocks with blank lines.
+- Use `-` for unordered lists. Indent nested content consistently; use four spaces for nested unordered lists.
+- Label fenced blocks: `bash`, `sh`, `powershell`, `python`, `json`, `yaml`, `dotenv`, `text`, or `mermaid` as appropriate.
+- Run commands from the repository root unless a different working directory is explicitly stated.
+- Use placeholders or portable example paths instead of private workstation paths. Never include real tokens, passwords, private keys, or local data.
+- Link to versioned files using relative paths. Use full URLs for other repositories, services, and upstream sources. Avoid sibling-checkout links.
+- Prefer Markdown. Use HTML only when it improves a gallery or layout; provide image alt text.
+- Keep navigation anchors synchronized with headings. Avoid duplicate headings that create ambiguous anchors.
+- Avoid decorative badges, repeated separators, promotional claims, and unsupported claims of production readiness or completed testing.
+- Verify requirements and commands against manifests, scripts, configuration, and workflows. Distinguish previously documented results from checks performed during an edit.
+- Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into `docs/` when useful and update links relative to their new location.
+- Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision.
+
+## Maintenance
+
+Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import.