From d210e5d8c583ab889dff86fbd83b6bcc7ed8c572 Mon Sep 17 00:00:00 2001
From: Antigravity AI <antigravity@falah-os.com>
Date: Mon, 6 Jul 2026 11:00:26 +0800
Subject: [PATCH] docs: add iStore publisher guide and token instructions

- docs/publish-to-istore.md: full app.yml spec, Docker image
  requirements, and step-by-step publishing workflow for developers
- .env.example: document pre-generated Gitea token scope and
  bitwarden.falahos.my retrieval note

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JWCfXRGY3WA5PNeMRLad7w
---
 .env.example              |   5 +-
 docs/publish-to-istore.md | 106 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+), 2 deletions(-)
 create mode 100644 docs/publish-to-istore.md

diff --git a/.env.example b/.env.example
index bd32e83..320ff95 100644
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,7 @@ CASDOOR_CLIENT_ID=           # from Casdoor app settings (Client ID field)
 
 # ── iStore / Gitea ────────────────────────────────────────────────────────────
 # Personal access token from git.falahos.my/-/user/settings/applications
-# Scopes required: read:org, read:repository
-# Leave empty to use public repos only (rate-limited)
+# Scopes required: read:organization, read:repository
+# A read-only token is pre-generated for the iStore service — retrieve it from
+# bitwarden.falahos.my under "Falah OS iStore Gitea Token"
 GITEA_TOKEN=
diff --git a/docs/publish-to-istore.md b/docs/publish-to-istore.md
new file mode 100644
index 0000000..0d6e6c1
--- /dev/null
+++ b/docs/publish-to-istore.md
@@ -0,0 +1,106 @@
+# Publishing an App to Falah OS iStore
+
+Any developer can publish an app to the iStore by creating a public repository in the
+`falahos` organization on [git.falahos.my](https://git.falahos.my/falahos) and adding
+an `app.yml` manifest at the repository root.
+
+---
+
+## 1. Request org membership
+
+Contact the Falah OS team to be added as a member of the `falahos` org on Gitea.
+Once added you can create repositories directly in the org.
+
+## 2. Create your app repository
+
+Repository naming convention: `app-<your-app-id>` (e.g. `app-prayer-times`).
+
+```bash
+# via Gitea UI: git.falahos.my → + → New Repository → Owner: falahos
+# or via API:
+curl -X POST https://git.falahos.my/api/v1/orgs/falahos/repos \
+  -H "Authorization: token $YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"app-my-app","private":false,"auto_init":true}'
+```
+
+## 3. Add `app.yml` at the repository root
+
+The iStore service reads this file to populate the store listing.
+
+```yaml
+# app.yml — required fields
+id: my-app                          # unique, kebab-case, matches repo name suffix
+name: My App                        # display name
+version: 1.0.0                      # semver
+tagline: One-line description       # shown in store card
+category: Finance                   # Finance | Worship | Lifestyle | Productivity | Tools
+ramz_verified: false                # true = Ramz-audited Islamic finance compliance
+image: docker.io/yourorg/my-app:latest   # Docker image to pull on install
+port: 8080                          # host port the container exposes
+icon: 🕌                            # emoji or URL to 512×512 PNG
+featured: false                     # request featured placement (reviewed by team)
+author: Your Name / Org
+license: MIT                        # SPDX identifier
+min_ce_version: 1.3                 # minimum Falah OS CE version required
+```
+
+## 4. Publish your Docker image
+
+The App Manager pulls the `image` value directly from the manifest.
+Push to any public registry your CE instance can reach:
+
+```bash
+docker build -t docker.io/yourorg/my-app:1.0.0 .
+docker push docker.io/yourorg/my-app:1.0.0
+docker tag  docker.io/yourorg/my-app:1.0.0 docker.io/yourorg/my-app:latest
+docker push docker.io/yourorg/my-app:latest
+```
+
+## 5. Verify the listing
+
+Once your `app.yml` is on the `main` branch the iStore will pick it up within
+5 minutes (cache TTL). You can force a refresh:
+
+```bash
+curl -X POST http://<ce-host>:3021/api/cache/clear
+```
+
+Then check:
+
+```bash
+curl http://<ce-host>:3021/api/apps/<your-app-id>
+```
+
+---
+
+## App manifest reference
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | ✅ | kebab-case, unique |
+| `name` | string | ✅ | display name |
+| `version` | string | ✅ | semver |
+| `tagline` | string | ✅ | ≤ 80 chars |
+| `category` | string | ✅ | see allowed values above |
+| `ramz_verified` | bool | ✅ | `true` only after audit |
+| `image` | string | ✅ | fully-qualified Docker image |
+| `port` | int | ✅ | container port to expose |
+| `icon` | string | ✅ | emoji or HTTPS PNG URL |
+| `featured` | bool | — | default `false` |
+| `author` | string | — | |
+| `license` | string | — | SPDX id |
+| `min_ce_version` | string | — | semver |
+
+## Container requirements
+
+Your Docker container must:
+
+- Listen on the port declared in `app.yml`
+- Start within 30 seconds
+- Respond to `GET /health` with HTTP 200 (optional but recommended)
+- Run as a non-root user where possible
+- Not require host-mode networking
+
+The App Manager places each installed container on the `falah-net` Docker network,
+so containers can reach each other by service name.