docs: add FS and FileService info

docs/Development.md

@@ -73,6 +73,37 @@ lib_deps =
     ESP8266WiFi@1.0
 ```
 
+### Filesystem, Linker Scripts, and Flash Layout
+
+This project uses LittleFS as the filesystem on ESP8266. Flash layout is controlled by the linker script (ldscript) selected per environment in `platformio.ini`.
+
+- **Filesystem**: LittleFS (replaces SPIFFS). Although ldscripts reference SPIFFS in their names, the reserved region is used by LittleFS transparently.
+- **Why ldscript matters**: It defines maximum sketch size and the size of the filesystem area in flash.
+
+| Board / Env | Flash size | ldscript | Filesystem | FS size | Notes |
+|-------------|------------|---------|------------|---------|-------|
+| esp01_1m    | 1MB        | `eagle.flash.1m64.ld` | LittleFS | 64KB | Prioritizes sketch size on 1MB modules. OTA is constrained on 1MB.
+| d1_mini     | 4MB        | `eagle.flash.4m1m.ld` | LittleFS | 1MB  | Standard 4M/1M layout; ample space for firmware and data.
+
+Configured in `platformio.ini`:
+
+```ini
+[env:esp01_1m]
+board_build.filesystem = littlefs
+board_build.ldscript = eagle.flash.1m64.ld
+
+[env:d1_mini]
+board_build.filesystem = littlefs
+board_build.ldscript = eagle.flash.4m1m.ld
+```
+
+Notes:
+- The ldscript name indicates total flash and filesystem size (e.g., `4m1m` = 4MB flash with 1MB FS; `1m64` = 1MB flash with 64KB FS).
+- LittleFS works within the filesystem region defined by the ldscript, despite SPIFFS naming.
+- If you need a different FS size, select an appropriate ldscript variant and keep `board_build.filesystem = littlefs`.
+- On ESP8266, custom partition CSVs are not used for layout; the linker script defines the flash map. This project removed prior `board_build.partitions` usage in favor of explicit `board_build.ldscript` entries per environment.
+
+
 ## Building
 
 ### Basic Build Commands

docs/README.md

@@ -52,6 +52,7 @@ Complete development and deployment guide.
 
 **Includes:**
 - PlatformIO configuration
+- Filesystem, linker scripts, and flash layout mapping
 - Build and flash instructions
 - OTA update procedures
 - Cluster management commands
@@ -59,6 +60,9 @@ Complete development and deployment guide.
 - Troubleshooting guide
 - Best practices
 
+### 📖 [StaticFileService.md](./StaticFileService.md)
+Static file hosting over HTTP using LittleFS.
+
 ## Quick Links
 
 - **Main Project**: [../README.md](../README.md)

docs/StaticFileService.md

@@ -0,0 +1,84 @@
+# StaticFileService
+
+Serves static files from the device's LittleFS filesystem over HTTP.
+
+## Overview
+
+- Service name: `StaticFileService`
+- Mounts: LittleFS at startup
+- Endpoints:
+  - GET / → serves /index.html
+  - GET /* → serves any file under LittleFS by path
+
+Files are looked up relative to the filesystem root. If a requested path is empty or `/`, it falls back to `index.html`. Unknown paths return 404; a helper exists to fall back to `index.html` for SPA routing if desired.
+
+## Content types
+
+Determined by filename extension:
+
+- .html, .htm → text/html
+- .css → text/css
+- .js → application/javascript
+- .json → application/json
+- .png → image/png
+- .jpg, .jpeg → image/jpeg
+- .gif → image/gif
+- .svg → image/svg+xml
+- .ico → image/x-icon
+- default → application/octet-stream
+
+## Building and uploading the filesystem
+
+Place your web assets under the `data/` folder at the project root. The build system packages `data/` into a LittleFS image matching the environment's flash layout.
+
+### Upload via PlatformIO
+
+```bash
+# Build and upload filesystem for esp01_1m
+pio run -e esp01_1m -t uploadfs
+
+# Build and upload filesystem for d1_mini
+pio run -e d1_mini -t uploadfs
+```
+
+### Manual image build (optional)
+
+There are helper commands in `ctl.sh` if you need to build and flash the FS image manually:
+
+```bash
+# Build image from ./data into littlefs.bin
+./ctl.sh mkfs
+
+# Flash image at preconfigured offset
+./ctl.sh flashfs
+```
+
+Note: Offsets and sizes must match the environment's ldscript. The project defaults are:
+
+- esp01_1m: ldscript `eagle.flash.1m64.ld` (64KB FS)
+- d1_mini: ldscript `eagle.flash.4m1m.ld` (1MB FS)
+
+See `docs/Development.md` for details on filesystem and ldscript mapping.
+
+## Enabling the service
+
+`StaticFileService` is registered as a core service in the framework and enabled by default:
+
+```cpp
+// part of Spore::registerCoreServices()
+auto staticFileService = std::make_shared<StaticFileService>(ctx, apiServer);
+services.push_back(staticFileService);
+```
+
+If you maintain a custom build without the default services, ensure you instantiate and add the service before starting the API server.
+
+## Routing notes
+
+- Place your SPA assets in `data/` and reference paths relatively.
+- To support client-side routing, you can adapt `handleNotFound` to always serve `/index.html` for unknown paths.
+
+## Troubleshooting
+
+- "LittleFS Mount Failed": Ensure `board_build.filesystem = littlefs` is set and the ldscript provides a filesystem region.
+- 404 for known files: Confirm the file exists under `data/` and was uploaded (`pio run -t uploadfs`).
+- Incorrect MIME type: Add the extension mapping to `getContentType()` if using custom extensions.