docs: document extensions and app upload workflow

docs/app-architecture.md

@@ -0,0 +1,76 @@
+# App / Extension Architecture
+
+This document explains how CrossPoint apps (aka extensions) work today, and how we can evolve toward an on-device app store.
+
+## Current Model: Partition-based apps
+
+CrossPoint runs as the main firmware, and apps are installed by flashing a standalone firmware image into the device's *other* OTA partition.
+
+### Components
+
+- **Apps directory** (SD): `/.crosspoint/apps/<appId>/`
+  - `app.json`: manifest (name/version/author/minFirmware...)
+  - `app.bin`: firmware image for the app (ESP32-C3)
+- **Launcher UI** (device): Home → Apps
+  - lists apps discovered on SD
+  - installs/launches apps by flashing `app.bin`
+- **AppLoader**: SD scan + OTA flashing
+- **File Transfer Web UI**: developer workflow for uploading apps without removing SD
+
+### End-to-end flow
+
+```text
+Developer builds app firmware -> app.bin
+          |
+          | (WiFi) upload via File Transfer /apps (developer page)
+          v
+SD card: /.crosspoint/apps/<appId>/{app.bin, app.json}
+          |
+          | (device UI) Home -> Apps -> select app -> Install
+          v
+AppLoader flashes app.bin to next OTA partition, sets boot partition, reboots
+          |
+          v
+Device boots into the app firmware
+```
+
+### Why this aligns with extension requests
+
+This keeps out-of-scope features (games/puzzles, experimental tools) out of the core reader firmware while still allowing the community to build and run them.
+
+This is directly aligned with:
+- Discussion #257: "extension/plugin support" requests
+- Discussion #575: chess interest + feedback that games should not live in the core firmware
+
+## Future: On-device app store (proposed)
+
+The current system requires getting `app.bin` onto the SD card.
+An on-device app store would automate that step by downloading releases and assets over WiFi.
+
+### Proposed pieces
+
+1) **Registry**
+
+- `apps.json` listing available apps with metadata and download URLs.
+- Maintainer choice:
+  - separate repo (recommended) `crosspoint-reader/app-registry`
+  - or keep `apps.json` in the firmware repo
+
+2) **Release assets**
+
+- Required: `app.bin`
+- Optional: `assets.zip` (unpacks to `/.crosspoint/<appId>/...`)
+- Optional: `app.json` (manifest) if authors prefer to author it directly
+
+3) **Device-side store UX** (follow-up work)
+
+- Fetch registry over HTTPS
+- Download `app.bin` + optional `assets.zip` to SD
+- Unpack assets to expected paths
+- Surface install/update actions via Home → Apps
+
+### Why assets.zip matters
+
+Many apps need more than a binary (sprites, fonts, puzzle packs).
+For production UX, users should not have to manually place these files.
+Bundling assets as a separate downloadable archive keeps the app firmware small while enabling a 1-click install experience.

docs/apps.md

@@ -0,0 +1,111 @@
+# Apps (Extensions) and Developer Workflow
+
+CrossPoint supports **apps/extensions** that live on the SD card and are installed by flashing their firmware image into the device's unused OTA partition.
+
+This is intentionally designed so out-of-scope apps (games, puzzles, etc.) do **not** need to be included in the core reader firmware.
+
+## What is an "app"?
+
+An app is a **standalone firmware binary** (ESP32-C3) with a small manifest.
+
+SD card layout:
+
+```
+/.crosspoint/apps/<appId>/
+  app.bin   # app firmware image (ESP32-C3; starts with magic byte 0xE9)
+  app.json  # manifest (name, version, ...)
+```
+
+The CrossPoint launcher discovers apps by scanning `/.crosspoint/apps/*/app.json`.
+
+## Installing an app (on device)
+
+1. Home → Apps
+2. Select the app
+3. Press Launch/Install
+
+CrossPoint will flash `app.bin` to the OTA partition and reboot.
+
+## Fast iteration: upload apps over WiFi (no SD card removal)
+
+Use the File Transfer feature:
+
+1. On device: Home → File Transfer
+2. Connect to WiFi (STA) or create a hotspot (AP)
+3. From your computer/phone browser, open the URL shown on the device
+4. Open **Apps (Developer)**
+5. Fill in:
+   - App ID (e.g. `chess-puzzles` or `org.example.myapp`)
+   - Name
+   - Version
+   - Optional: author, description, minFirmware
+6. Upload your app binary (`app.bin`)
+7. On device: Home → Apps → select app → Install
+
+Notes:
+- This page is upload-only. Installing always happens on device.
+- The Apps (Developer) page writes to `/.crosspoint/apps/<appId>/` and generates `app.json`.
+
+## Building apps with the community SDK
+
+Recommended SDK: `https://github.com/open-x4-epaper/community-sdk`
+
+Typical setup (in your app repo):
+
+1. Add the SDK as a submodule:
+   ```bash
+   git submodule add https://github.com/open-x4-epaper/community-sdk.git open-x4-sdk
+   ```
+2. In `platformio.ini`, add SDK libs as `lib_deps` (symlink form), for example:
+   ```ini
+   lib_deps =
+     BatteryMonitor=symlink://open-x4-sdk/libs/hardware/BatteryMonitor
+     EInkDisplay=symlink://open-x4-sdk/libs/display/EInkDisplay
+     SDCardManager=symlink://open-x4-sdk/libs/hardware/SDCardManager
+     InputManager=symlink://open-x4-sdk/libs/hardware/InputManager
+   ```
+3. Build with PlatformIO:
+   ```bash
+   pio run
+   ```
+4. The firmware binary will usually be:
+   - `.pio/build/<env>/firmware.bin`
+
+For CrossPoint app uploads:
+- Rename/copy your output to `app.bin`, then upload via the Apps (Developer) page.
+
+## Example: Hello World app
+
+This repo includes a minimal Hello World app that can be built as a standalone firmware image and installed via the Apps menu.
+
+Build:
+
+```bash
+.venv/bin/pio run -e hello-world
+```
+
+Upload the output:
+
+- File: `.pio/build/hello-world/firmware.bin`
+- Upload via: File Transfer → Apps (Developer)
+- Suggested App ID: `hello-world`
+
+Then install on device:
+
+Home → Apps → Hello World → Install
+
+## Distribution (proposed)
+
+Apps should live in their own repositories and publish binaries via GitHub Releases.
+
+For safety/auditability, registry listings should reference a public source repository (e.g. GitHub URL) so maintainers and users can review the code that produced the release.
+
+Release assets:
+- Required: `app.bin`
+- Optional: `app.json`
+
+Registry location (maintainer choice):
+1. Separate repo (recommended): `crosspoint-reader/app-registry` containing `apps.json`
+2. Or keep `apps.json` in the main firmware repo
+
+The on-device store UI can be built later on top of this ecosystem.

docs/webserver-endpoints.md

@@ -7,9 +7,11 @@ This document describes all HTTP and WebSocket endpoints available on the CrossP
   - [HTTP Endpoints](#http-endpoints)
     - [GET `/` - Home Page](#get----home-page)
     - [GET `/files` - File Browser Page](#get-files---file-browser-page)
+    - [GET `/apps` - Apps (Developer) Page](#get-apps---apps-developer-page)
     - [GET `/api/status` - Device Status](#get-apistatus---device-status)
     - [GET `/api/files` - List Files](#get-apifiles---list-files)
     - [POST `/upload` - Upload File](#post-upload---upload-file)
+    - [POST `/upload-app` - Upload App (Developer)](#post-upload-app---upload-app-developer)
     - [POST `/mkdir` - Create Folder](#post-mkdir---create-folder)
     - [POST `/delete` - Delete File or Folder](#post-delete---delete-file-or-folder)
   - [WebSocket Endpoint](#websocket-endpoint)
@@ -57,6 +59,22 @@ curl http://crosspoint.local/files
 
 ---
 
+### GET `/apps` - Apps (Developer) Page
+
+Serves the Apps (Developer) HTML interface.
+
+This is a developer-oriented page for uploading app binaries to the SD card under `/.crosspoint/apps/`.
+Installing/running apps still happens on the device: Home → Apps.
+
+**Request:**
+```bash
+curl http://crosspoint.local/apps
+```
+
+**Response:** HTML page (200 OK)
+
+---
+
 ### GET `/api/status` - Device Status
 
 Returns JSON with device status information.
@@ -170,6 +188,51 @@ File uploaded successfully: mybook.epub
 
 ---
 
+### POST `/upload-app` - Upload App (Developer)
+
+Uploads an app binary to the SD card under `/.crosspoint/apps/<appId>/` and creates/updates `app.json`.
+
+**Important:** this endpoint does not install the app. Install on device via Home → Apps.
+
+**Request:**
+```bash
+curl -X POST \
+  -F "file=@app.bin" \
+  "http://crosspoint.local/upload-app?appId=chess-puzzles&name=Chess%20Puzzles&version=0.1.0"
+```
+
+**Query Parameters:**
+
+| Parameter     | Required | Description |
+|---------------|----------|-------------|
+| `appId`       | Yes      | App identifier; allowed chars: `[A-Za-z0-9._-]`, max 64, no slashes |
+| `name`        | Yes      | Display name |
+| `version`     | Yes      | Version string |
+| `author`      | No       | Author string |
+| `description` | No       | Short description |
+| `minFirmware` | No       | Minimum CrossPoint firmware version required |
+
+**Response (200 OK):**
+```
+App uploaded. Install on device: Home -> Apps -> <Name> v<Version>
+```
+
+**Error Responses:**
+
+| Status | Body                                       | Cause |
+|--------|--------------------------------------------|-------|
+| 400    | `Missing required fields: appId, name, version` | Missing query parameters |
+| 400    | `Invalid appId`                            | appId failed validation |
+| 500    | `SD card not ready`                        | SD not mounted/ready |
+| 500    | `Failed to create app.bin.tmp`             | File create failed (disk full / FS error) |
+| 500    | `Invalid firmware image (bad magic byte)`  | Uploaded file is not an ESP32 image |
+
+**Notes:**
+- Upload uses a temp file (`app.bin.tmp`) and finalizes to `app.bin` on success.
+- Partial uploads are cleaned up on abort/failure.
+
+---
+
 ### POST `/mkdir` - Create Folder
 
 Creates a new folder on the SD card.

docs/webserver.md

@@ -10,6 +10,7 @@ CrossPoint Reader includes a built-in web server that allows you to:
 - Browse and manage files on your device's SD card
 - Create folders to organize your ebooks
 - Delete files and folders
+- (Developer) Upload app binaries for installation via the on-device Apps menu
 
 ## Prerequisites
 
@@ -118,6 +119,7 @@ The home page displays:
 Navigation links:
 
 - **Home** - Returns to the status page
+- **Apps (Developer)** - Upload app binaries to `/.crosspoint/apps/<appId>/` (install on device)
 - **File Manager** - Access file management features
 
 <img src="./images/wifi/webserver_homepage.png" width="600">