cianium · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,58 @@
+name: Source QA and Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: source-ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Source QA and placeholder build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    # These intentionally fake values are for artifact-shape checks only.
+    # Never deploy the generated dist/ or connect this job to a real database.
+    env:
+      SUPABASE_URL: https://ci-placeholder.supabase.co
+      SUPABASE_PUBLISHABLE_KEY: sb_publishable_ci_placeholder_not_a_real_key
+      SITE_URL: https://example.invalid
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Run source and mocked security QA
+        run: npm run qa
+
+      - name: Build using non-production placeholders
+        run: npm run build
+
+      - name: Verify output contains only expected public files
+        run: npm run verify:dist
+
+      - name: Confirm CI placeholders were used
+        run: |
+          grep -Fq 'https://ci-placeholder.supabase.co' dist/assets/runtime-config.js
+          grep -Fq 'sb_publishable_ci_placeholder_not_a_real_key' dist/assets/runtime-config.js
+          # Avoid scanning harmless warning comments for the words "service_role":
+          # tools/dist-qa.mjs already validates credential assignment values.
+          echo 'Verified fake build configuration; artifact is not deployable.'
diff --git a/README.md b/README.md
@@ -1,63 +1,121 @@
-# German Library v3.2.1-p0-preview — Security & SSR Navigation Patch
+<div align="center">
 
-**این نسخه Source-only است، Production نیست.** پچ امنیتی جدید `backend/migrations/20261015_p0_article_source_read_access.sql` باید **پس از** Migration مقالات vNext روی Supabase Development اجرا و با حساب‌های واقعی آزمایش شود. بدون اجرای SQL، مشکل دسترسی به نسخه در حال ویرایش حل نشده است. مسیرهای SSR مقالات چهارمقصدی و هماهنگ با V7.5 شده‌اند؛ SEO URL خالی هم اصلاح شده است. گزارش کامل: `docs/P0_SECURITY_AND_NAV_REPORT_FA.md`.
+# German Library
 
-تست‌ها: `npm run qa`، `npm run qa:ssr:browser` و `npm run qa:studio:browser`. Build آزمایشی جای تست دیتابیس واقعی را نمی‌گیرد.
+**A mobile-first German learning resource library for CEFR A1–C2.**
 
----
+[![Source QA and Build](https://github.com/cianium/German-Library/actions/workflows/ci.yml/badge.svg)](https://github.com/cianium/German-Library/actions/workflows/ci.yml)
+![Status](https://img.shields.io/badge/Status-Development%20Preview-E5A50A)
+![Version](https://img.shields.io/badge/Source-3.2.1--p0--preview-147D8B)
 
-# German Library v3.2.0-preview — Article Studio Mobile Increment
+**Books & learning resources · Articles · Content management · Multi-device experience**
 
-**این بسته یک توسعه افزایشی است و جایگزین کامل نیازمندی‌های V7.5 نیست.**
-- ناوبری عمومی چهارمقصدی V7.5 با Articles زیر Extras؛ پنل مدیریت تغییر نکرده است.
-- جدول‌ساز، ویرایش لینک داخلی/خارجی، Alt و Caption جداگانه و ویرایش تصویر موجود.
-- اصلاح باگ حفظ متادیتا هنگام باز کردن مقاله و بهبود SEO تصویر.
-- دستور تست: `npm run qa`؛ تست UI با Chromium و Playwright: `npm run qa:studio:browser`.
-- مستندات تغییرات و محدودیت‌ها: `docs/VNEXT_MOBILE_STUDIO_DELTA_FA.md`.
-- آپلود امن تصاویر در Editor، Structured Editor Engine و Live Supabase/RLS QA **هنوز انجام نشده است**.
-- برای ساخت Production باید `SUPABASE_URL`، `SUPABASE_PUBLISHABLE_KEY` و `SITE_URL` واقعی و امن را تنظیم کنی؛ `dist/` آزمایشی در فایل ZIP تحویلی قرار ندارد.
+</div>
 
----
+> **Release status:** This repository is currently a **source/preview build**, not a verified production release. The P0 article-access SQL patch exists in source, but its application to any real Supabase database and live role-based access verification are **not confirmed**. Do not use a passing CI run as evidence that deployed database permissions are secure.
 
-# German Library v3 (Source release)
+## What this project does
 
-This v3 release is derived from German Library V7.4.0; it **is not** the older V7.3 release.
+German Library helps German learners find curated learning materials by **CEFR level (A1–C2)**, book category, and learning objective. The codebase includes a browser-first catalog, content-management interfaces, an article authoring workflow, and Vercel server-rendered article endpoints.
 
-## What's in v3.1
-- Five destinations: **سطح → مکمل → خانه → مقالات → کتابخانه**.
-- Books-only library: categories and featured shelf; all published books regardless of level.
-- Admin book editor: stable ID, book type, skills, optional CEFR, featured flag, cover URL/upload, book URL/upload, provider, status, core selection.
-- Book assets: audio, podcast, video, transcript are still editable inside a book.
-- Dedicated levels directory; independent media in Supplemental tab.
-- Calm teal/blue-green light and deep-slate dark palette.
-- Vercel server-rendered Articles directory and individual article pages, with raw SEO metadata, JSON-LD, sitemap, 404, and slug redirects.
-- Supabase Article Studio workflow, private preview, revision history, optimistic concurrency, SEO checklist, and Admin-only Author assignment with audit.
-- Additive Article and role migration: `backend/migrations/20261014_vnext_articles.sql`.
+| Area | Included in source | Important boundary |
+| :--- | :--- | :--- |
+| Learning catalog | Levels, books, book-linked media, supplemental resources | The starter catalog is example content; access rights to third-party resources must be respected |
+| Public interface | Mobile-first pages, navigation, responsive layouts | Check physical browsers before declaring release-ready |
+| Administration | Content editing, status and sync-related workflows | Live Supabase Auth, Storage and permission checks still required |
+| Article platform | SSR directory/article routes, SEO metadata, author/editor flows and preview | Live RLS migration and permission matrix must be verified on Staging |
+| Quality checks | Static/source QA, mocked backend/SSR tests, build and dist inspection | Mocked tests do **not** validate a live database or deployed security |
 
-## Run locally on Termux
-Extract to a clean directory and run `python -m http.server 8080`; visit `http://127.0.0.1:8080/index.html`. **Never serve an old `dist` directory.** Offline mode uses sample content and a local Demo admin only on localhost. Live authentication/uploads need Supabase.
+## Technology
 
-## Article routes
+- **Frontend:** HTML, CSS and JavaScript (mobile-first).
+- **Server-rendered articles:** Vercel Functions and server-side navigation.
+- **Backend services (when configured):** Supabase Auth, PostgreSQL/RLS and private Storage.
+- **Build and QA:** Node.js (20+) and Python 3.
+- **Deployment configuration:** `vercel.json`, with a separate static GitHub Pages deployment history.
 
-Article HTML and `/sitemap.xml` run as Vercel Functions. `python -m http.server` does not execute these routes. Configure `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, and `SITE_URL` in Vercel. The publishable key is safe for browser use; no service-role key is required by the article renderer.
+## Run locally (source preview)
 
-## Supabase release order
-1. Back up Production database and storage.
-2. In Development, apply `backend/migrations/20261014_v74_books_media.sql` if missing, then `backend/migrations/20261014_v3_book_metadata.sql`.
-3. Apply `backend/migrations/20261014_vnext_articles.sql` **then** `backend/migrations/20261015_p0_article_source_read_access.sql` in Development; run both `backend/validation/vnext_articles_check.sql` and `backend/validation/p0_article_access_check.sql` and live positive/negative role tests.
-4. Set public Supabase URL, publishable key and `SITE_URL` in Vercel; never expose service-role keys.
-5. Deploy Preview and verify existing Staff, book uploads and sync, plus article login, autosave, RLS, publishing, raw HTML, canonical, redirects and sitemap.
-6. Only after successful Preview testing, plan a separate Production migration and deployment. No live Supabase migration or Production deployment was performed in this build.
+Requirements: Node.js 20+ and Python 3.
 
-## QA
-`npm run qa` then `npm run build` then `npm run verify:dist`. The mocked Function and raw-HTML checks run in `tools/vnext-articles-qa.mjs`. Local browser QA: `python3 tools/v3-browser-qa.py` (requires Python Playwright and Chromium); it does not verify live Supabase.
+```bash
+git clone https://github.com/cianium/German-Library.git
+cd German-Library
+python3 -m http.server 8080
+```
 
-## Article platform boundaries
+Open **http://localhost:8080** to view the static pages. This local static server does **not** execute Vercel article routes (`/articles`, `/articles/:slug`, `/sitemap.xml`), nor does it provision Supabase. Local demo behavior is **not** a production authentication or access-control test.
 
-The editor currently uses browser `contenteditable` with allow-list serialization. Cover and inline images require stable public HTTPS URLs. Private draft bucket policies and asset metadata are prepared, but in-editor uploads, crop/focal-point tools, draft-to-public asset promotion, scheduled publishing, and live Supabase tests are not implemented.
+## Quality checks
 
-## Known constraints
-- Level/category changes on existing books with dependent files are blocked to preserve referential integrity; move assets first.
-- Cover upload uses existing private Supabase Storage; public viewing requires the current bucket signed-download rules.
-- External links are structurally validated but not automatically health-checked.
-- Migration is not automatically executed on any live database.
+```bash
+npm run qa
+```
+
+This runs the repository's static checks, content validation and **mocked** backend/article security regression checks.
+
+To assemble and inspect a **non-deployable CI test artifact** without using real Supabase credentials:
+
+```bash
+SUPABASE_URL=https://ci-placeholder.supabase.co \
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_ci_placeholder_not_a_real_key \
+SITE_URL=https://example.invalid \
+npm run build
+
+npm run verify:dist
+```
+
+These intentionally fake public values satisfy build-time configuration checks only. **Do not deploy that artifact.** A production deployment requires its own reviewed environment, approved public configuration, staged database migration, and live verification.
+
+Additional browser tests (require appropriate local tooling/Playwright + Chromium):
+
+```bash
+npm run qa:ssr:browser
+npm run qa:studio:browser
+```
+
+The GitHub Actions workflow runs **source QA + placeholder build + dist verification**. It does **not** run real Supabase migrations, live permission tests, or these separate browser suites.
+
+## Security & staging release gate
+
+Before enabling a real deployment, follow the documented migration order and verify RLS **in an authorized Development/Staging Supabase project**, including the P0 patch `backend/migrations/20261015_p0_article_source_read_access.sql`. Validate permissions for guest, learner, owning author, non-owning author, and editor/admin against both raw article rows and published snapshots.
+
+Do not apply a patch blindly to Production. Back up data, check migration history, and complete positive/negative access tests in Staging first. The patch being committed to GitHub is **not** proof it is deployed.
+
+- [P0 security and SSR navigation report (FA)](docs/P0_SECURITY_AND_NAV_REPORT_FA.md)
+- [Supabase setup and staged verification](docs/SUPABASE_SETUP.md)
+- [QA and historical technical audits](docs/TECHNICAL_AUDIT.md)
+- [Release checklist (FA)](docs/RELEASE_CHECKLIST_FA.md)
+
+## Architecture and repository guide
+
+| Path | Responsibility |
+| :--- | :--- |
+| `assets/` | Shared UI, browser code, client-facing pages and styles |
+| `data/` | Public fallback catalog content |
+| `api/` | Vercel article and sitemap functions |
+| `server/` | Shared server-side presentation helpers |
+| `backend/migrations/` | Versioned database migrations **requiring explicit deployment** |
+| `backend/validation/` | SQL validation scripts for staging checks |
+| `tools/` | Source QA, mocked tests and optional browser checks |
+| `docs/` | Product scope, security and delivery reports |
+
+## Roadmap
+
+- [ ] Verify live P0 permissions and draft/published-article boundaries in Staging.
+- [ ] Complete responsive and accessibility testing in real mobile browsers.
+- [ ] Validate Auth, Storage, and the article publish/review flow end-to-end.
+- [ ] Improve the secure article media workflow.
+- [ ] Publish a tested release with aligned versioning, migration instructions and rollback steps.
+
+## Versioning and historical releases
+
+The current `package.json` source version is **`3.2.1-p0-preview`**. GitHub also contains an older release **titled `v7.1.1` with tag `v1.1.1`**. Those identifiers refer to different versioning contexts; the old tag must not be silently moved or rewritten.
+
+Read the [Changelog](CHANGELOG.md) and [GitHub Releases and publishing policy](docs/RELEASES.md). A CI-green badge does **not** mean the project is production-ready.
+
+## Contributions and licensing
+
+Suggestions and reproducible bug reports are welcome through GitHub Issues. Please verify the status and current architecture before proposing changes. This public repository's contents are **not automatically licensed for reuse**; no open-source license is assumed until one is expressly added by the maintainer. For third-party learning materials, link to official publisher resources or use assets you are authorized to share.
+
+**Maintained by [Kian Khayat](https://github.com/cianium).**
diff --git a/docs/RELEASES.md b/docs/RELEASES.md
@@ -0,0 +1,38 @@
+# GitHub releases and publishing policy — German Library
+
+**Current source version:** `3.2.1-p0-preview` (as recorded in `package.json` on 2026-10-20).
+
+**Status:** Preview/source only. No documented execution of the current P0 security migration against an authorized live database, no independently verified Production rollout, and no live role-based security acceptance.
+
+## Historical GitHub Release
+
+As of 2026-10-20, the repository has one GitHub Release:
+
+| Git tag | Displayed Release title | Published (UTC) | Current interpretation |
+| :--- | :--- | :--- | :--- |
+| `v1.1.1` | `v7.1.1` | 2026-10-17 00:32 | Historical release; inconsistent tag/title, not the current preview |
+
+**Do not retag or delete the historical release.** The current GitHub integration does not expose metadata editing for Release objects. A maintainer should inspect the original commit and notes, then optionally rename the *display title* (not the tag) to:
+
+`German Library — Historical v7.1.1 snapshot (tag v1.1.1)`
+
+Suggested introductory disclaimer:
+
+> This is a historical source snapshot. Its Git tag is `v1.1.1` while the original displayed title was `v7.1.1`. Current repository source is `3.2.1-p0-preview`; no live Supabase migration or Production readiness is implied. See the current README and security report before deploying.
+
+Preserve the original body below the clarification and retain historical tags, dates and assets.
+
+## Release gate for future versions
+
+1. Record a **single version source of truth** in `package.json`; align release title, new tag and `CHANGELOG.md` when publishing a genuinely new release.
+2. Confirm security migrations in **Development/Staging**, never from GitHub CI against Production. Keep appropriate backups and migration history.
+3. Run live role-permission tests for unpublished and published snapshots. Verify Auth, private Storage and author/editor workflows.
+4. Run `npm run qa`, `npm run build`, `npm run verify:dist`, and optional browser suites against an appropriately configured Preview environment.
+5. Document limitations, real test evidence, rollback steps and relevant deployment environment without exposing secrets or personal account data.
+6. Mark incomplete builds **pre-release**. Do not call a build Production-ready based only on mocked QA or GitHub Pages status.
+
+## CI limitations
+
+`.github/workflows/ci.yml` uses intentionally fake Supabase *publishable* configuration and a non-resolvable example domain. It only tests that sources and build output satisfy static/mock checks. The job must not execute SQL, send writes to a live Supabase instance, or upload the build artifact for deployment.
+
+**Different hosts, different features:** GitHub Pages can host static pages, but **Vercel** is used by this repository's configuration for `/articles`, `/articles/:slug`, and `/sitemap.xml`. A successful GitHub Pages deployment is not verification of those serverless functions.