1 files changed, 74 insertions, 0 deletions

diff --git a/README.md b/README.md
index ccff7b1..69c79ed 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,77 @@
 # scorecounter
 
 *scorecounter* is a simple score counting app written in Python.
+
+
+## General
+
+*scorecounter* is intended for use on mobile devices (mobile phones and tablets)
+as a simple app for counting and recording scores during head‑to‑head games
+between two teams or participants. It is perfect for parents who want to
+record a child's football match score.
+No ads, no tracking, 100% free (as in freedom) software that doesn't require
+network access or additional permissions.
+
+Hence the intended target systems are *Android* and *iOS*, but because the
+application is implemented with [BeeWare](https://beeware.org/) it can be
+deployed to any platform supported by BeeWare.
+
+To date, only the Android build has been tested and documented.
+
+
+## How to use
+
+When a team or participant scores, tap their corresponding red or blue button.
+You can assign custom names to teams or participants.
+
+
+## Building and installing
+
+This document assumes that [Briefcase](https://briefcase.beeware.org/en/stable/)
+is installed.
+
+For more details visit the [official BeeWare tutorial](https://tutorial.beeware.org/)
+
+iOS applications require Xcode, which is only available on macOS
+ - a proprietary operating system I do not intend to use.
+
+
+### Android
+
+   ```bash
+   # build scorecounter for Android
+   briefcase build android
+
+   # Run and test scorecounter either using emulator or a real phone
+   # connected using an USB cable
+   briefcase run android
+   
+   # Make .apk package
+   briefcase package android -p apk
+   ```
+
+
+## Changelog
+
+A complete changelog can be found at:
+[https://codeberg.org/sgs/scorecounter/src/branch/main/CHANGELOG.md](https://codeberg.org/sgs/scorecounter/src/branch/main/CHANGELOG.md)
+
+
+## Support and contributing
+
+*scorecounter* is hosted on Codeberg: https://codeberg.org/sgs/scorecounter
+
+
+## Author
+
+Simeon Simeonov - sgs @ LiberaChat
+
+
+## [License](https://codeberg.org/sgs/scorecounter/src/branch/main/LICENSE)
+
+Copyright (C) 2026 Simeon Simeonov
+All rights reserved.
+
+[Licensed](https://codeberg.org/sgs/scorecounter/src/branch/main/LICENSE) under the
+GNU General Public License v3.0 or later.
+SPDX-License-Identifier: GPL-3.0-or-later