diff --git a/docs/README.md b/docs/README.md
index e69de29..887f045 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,106 @@
+# Skyfeed
+Leak Technologies — Terminal Weather Intelligence
+
+Skyfeed is a minimal, terminal-style weather application built for Linux systems.
+It retrieves live Environment Canada data, normalizes conditions, and displays
+them using a clean Unicode interface with a black-on-colour retro aesthetic.
+
+This project forms the foundation of the weather system that will power the
+Telefact information service.
+
+----------------------------------------------------------------------
+Features
+----------------------------------------------------------------------
+
+• Real-time Environment Canada weather data
+• Government alert integration (warnings, advisories, statements)
+• Automatic or manual location detection
+• Unicode icon set (no external graphics required)
+• Monospaced terminal UI (inspired by Ceefax / MS-DOS)
+• Multilingual support (English, French, Inuktut)
+• Configurable refresh and cache intervals
+• Optional alert border and clock display
+• Modular architecture for easy reuse by Telefact
+
+----------------------------------------------------------------------
+Installation
+----------------------------------------------------------------------
+
+Requirements:
+  - Python 3.13 or later
+  - pip
+  - Linux or compatible terminal environment
+
+Clone and install locally:
+    git clone https://git.leaktechnologies.dev/stu/Skyfeed.git
+    cd Skyfeed
+    pip install -r requirements.txt   # if created later
+    python -m src.cli.main
+
+----------------------------------------------------------------------
+Configuration
+----------------------------------------------------------------------
+
+Configuration file:
+    config/config.json
+
+Key options:
+  • Language — en_CA, fr_CA, iu_CA
+  • Theme — dark / custom
+  • ManualLocation — override IP lookup
+  • Display — alert borders, clock toggle, icon scale
+  • RefreshMinutes — update interval
+
+----------------------------------------------------------------------
+Running Tests
+----------------------------------------------------------------------
+
+Run all tests:
+    pytest -v
+
+Run a specific test:
+    pytest tests/test_weather_client.py
+
+----------------------------------------------------------------------
+Development Notes
+----------------------------------------------------------------------
+
+Version format:
+    MAJOR.MINOR.PATCH.DEV
+
+Example:
+    0.1.0.0  = Initial scaffolding and documentation
+    0.1.0.1  = Development build after README and tests
+    0.1.1.0  = Patch release with fixes
+
+----------------------------------------------------------------------
+Roadmap
+----------------------------------------------------------------------
+
+• [x] Initial architecture and documentation
+• [x] Unicode weather symbol mapping
+• [x] Localization (English, French, Inuktut)
+• [ ] Minimal terminal UI
+• [ ] Fullscreen weather view
+• [ ] Alert notification bar
+• [ ] Integration with Telefact
+
+----------------------------------------------------------------------
+Repository
+----------------------------------------------------------------------
+
+Primary repo:
+    https://git.leaktechnologies.dev/stu/Skyfeed.git
+
+Maintainer:
+    Stu Leak — Leak Technologies
+
+License:
+    MIT License (see LICENSE file)
+
+----------------------------------------------------------------------
+Version
+----------------------------------------------------------------------
+
+Current version: 0.1.0.1-dev
+Revision date: November 2025