Import remaining project documentation and reference notes

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.

app/AGENTS.md

@@ -0,0 +1,336 @@
+# Repository Guidelines
+
+## Project Structure
+
+Teknav is a Persian RTL React SPA (`teknav.ir`) with a Fastify/PostgreSQL/Redis backend. The Vite entry is `index.html` → `src/main.jsx`. Global styles, fonts, and animation primitives live in `src/styles/global.css`. Main frontend modules at repo root: `teknav-app.jsx`, `teknav-ui.jsx`, `teknav-home.jsx`, `teknav-articles.jsx`, `teknav-pages.jsx`, `teknav-auth.jsx`, `teknav-admin.jsx`, `teknav-profile.jsx`, `teknav-data.js`, `teknav-store.js`. Runtime assets in `public/`; font archives in `Fonts/`. Backend in `backend/` with Fastify sources in `backend/src/` and Prisma in `backend/prisma/`.
+
+## Dev Commands
+
+**Frontend** (repo root):
+- `npm run dev` — Vite dev server on **port 3009**, proxies `/api` → `http://localhost:3010`. Backend must be running first.
+- `npm run build` — runs SEO artifact generation, OG image generation, Vite build, CDN/responsive checks, static article page generation, and gzip/brotli compression.
+- `npm run preview` — preview built `dist/` on **port 4173**.
+- `npm run preflight:prod` — static production readiness audit for env templates, nginx SSE/credential protection, required scripts, generated-engine safety, and migration/test posture.
+- `npm run seo:sitemap` — regenerate `public/sitemap.xml`, `public/robots.txt`, `public/feed.xml` from `teknav-data.js`.
+- `npm run og:images` — generate local Open Graph images into `public/images/og/` from article metadata. Run on Linux after dependencies are installed.
+- `npm run check:seo` — audit current Persian indexable articles for canonical, meta, OG image, review date, heading structure, entity coverage, and body-depth warnings.
+
+**Backend** (`backend/`):
+- `npm run dev` — `tsx watch src/server.ts` on **port 3010** (env `PORT`, default 3010).
+- `npm run build` — `tsc` type-check and compile.
+- `npm run prisma:generate` — regenerate Prisma client after schema changes.
+- `npm run prisma:apply` — apply schema (migrations if present, else `db push --skip-generate`).
+- `npm run seed` — seed Postgres via `tsx prisma/seed.ts`.
+- `npm run publish:due` — publish scheduled articles (also runs via systemd timer in prod).
+
+**Dev startup order**: PostgreSQL + Redis → `cd backend && npm run dev` → `npm run dev`.
+
+Backend tests are `node:test` smoke/contract checks. `cd backend && npm test` auto-skips endpoint assertions when no backend is reachable; use `TEST_REQUIRE_SERVER=1 npm test` against a running backend for strict validation.
+
+Validate with `npm run preflight:prod`, `npm run check:seo`, `npm run build` (frontend), `cd backend && npm run build`, and strict backend tests against a running API.
+
+## Hard Constraints
+
+- **Zero CDN.** No external JS, CSS, fonts, images. `npm run build` rejects any CDN URL in `dist/`.
+- **Persian-first RTL.** All UI copy in Persian. Use logical CSS properties over `left`/`right`.
+- **ES modules, named exports.** JSX uses Vite automatic runtime — import hooks directly, not `React`.
+- **No mock admin data.** Admin/panel views (`teknav-admin.jsx`) must use backend API only (`src/lib/admin-api.js`). `teknav-data.js` and `teknav-store.js` are seed/reference data, not UI fallbacks.
+- **Production is native Linux/systemd + nginx.** No Docker. Deploy docs in `DEPLOY.md`.
+- **`ACCOUNTS.md`** is gitignored and nginx-blocked. Never commit or expose it. Seed credentials are in `backend/prisma/credentials.json`.
+
+## Ports & Proxy
+
+| Service | Dev Port | Prod |
+|---|---|---|
+| Frontend (Vite) | 3009 | nginx →
+`dist/` |
+| Preview (built) | 4173 | — |
+| Backend (Fastify) | 3010 | nginx proxy |
+
+Vite dev proxies `/api` to `http://localhost:3010` for same-origin cookies. Production nginx handles path-based routing. Backend health: `GET /api/v1/health`; strict readiness: `GET /api/v1/ready` returns 503 if PostgreSQL or Redis is unavailable. Frontend clients may call unversioned `/api/*`; `src/lib/api.js` rewrites those calls to `/api/v1/*`.
+
+## Auth & Accounts
+
+Argon2id hashing, Redis sessions (`tek_sid`), CSRF double-submit cookie (`tek_csrf`). Login by **email** or **`@username`**. Every seeded account must have a URL-safe username. Writer-admin accounts (آرسام صباغ, رادمان قلیچی, سیداحمدرضا محجوب) in `backend/prisma/credentials.json` use `resetPasswordOnSeed: true` — remove after production password rotation.
+
+## Schema & Seed Workflow
+
+When changing `backend/prisma/schema.prisma`: run `prisma:generate` before backend build/type-check, then `prisma:apply`.
+For production/Linux deployment, run `cd backend && npm ci && npm run prisma:generate && npm run prisma:apply` on the Linux host after uploading code. Never copy Windows-generated Prisma engine files (`backend/query_engine*.node`, `backend/schema-engine*`) or local `node_modules` into production.
+When changing `teknav-data.js` slugs/dates: run `npm run check:seo` and `npm run seo:sitemap`.
+When changing article Open Graph metadata: run `npm run og:images`, `npm run check:seo`, and `npm run seo:sitemap` on Linux.
+When changing seed logic: run `cd backend && npm run seed` against running PostgreSQL/Redis.
+
+## Phase 9 Files
+
+Phase 9 adds real publication features across frontend and backend:
+
+- `backend/src/routes/public.ts` — related articles, public article SEO fields, public series, newsletter unsubscribe, saved-article default reading-list sync.
+- `backend/src/routes/comments.ts` — real comment like/unlike API, like counts, and liked-by-me flags.
+- `backend/src/routes/lists.ts` — authenticated reading-list CRUD, add/remove, and reorder.
+- `backend/src/routes/analytics.ts` — authenticated writer/editor article analytics.
+- `backend/src/routes/admin.ts` — admin analytics, review workflow, newsletter campaigns, article series, and article SEO field writes.
+- `backend/prisma/schema.prisma` — `ArticleViewLog`, `CommentLike`, `NewsletterCampaign`, `ArticleSeries`, `ArticleReview`, `ReadingList`, and new article SEO fields.
+- `teknav-admin.jsx` — API-backed analytics, review, newsletter, and series panels.
+- `teknav-articles.jsx` — comment likes and API-backed related articles.
+- `teknav-pages.jsx` / `teknav-app.jsx` — public `/series/:slug` route.
+- `scripts/generate-seo.mjs` — canonical/dateModified/metaDescription sitemap and full-content RSS.
+- `scripts/generate-og-images.mjs` — local OG image generation.
+
+## Phase 10 Files
+
+Phase 10 expands SEO growth, trust, and publication readiness:
+
+- `PHASE10.md` — active Phase 10 checklist and Linux validation status.
+- `teknav-data.js` — topic hub metadata, glossary term data, and SEO seed/reference content.
+- `teknav-pages.jsx` — topic hubs, glossary pages, author pages, tag pages, series pages, and newsletter archive pages.
+- `src/lib/seo.jsx` — Article, CollectionPage, ProfilePage, DefinedTerm, FAQPage, ItemList, BreadcrumbList, canonical, robots, and Google Discover meta handling.
+- `scripts/generate-seo.mjs` — sitemap, robots, global feed, topic feeds, author feeds, and glossary URL generation.
+- `teknav-articles.jsx` — public article detail, table of contents, Discover hero image, correction notices, verified author badges, comparison table styles, comments, sharing, and engagement tracking.
+- `teknav-admin.jsx` — admin/writer editor, Phase 10 quality metadata, comparison article template, correction submission, verified author management, role dashboards, SEO/analytics panels.
+- `teknav-auth.jsx` / `teknav-ui.jsx` — email or `@username` login, Google/GitHub OAuth entry points, and SMS 2FA login completion.
+- `teknav-profile.jsx` — profile editing, phone verification, SMS 2FA toggle, public profile trust badges, reading history, and follows.
+- `public/manifest.json` / `public/service-worker.js` / `index.html` — PWA manifest, service worker registration, article offline cache, and installability.
+- `backend/src/routes/monetization.ts` — job board API, job submissions, and course listing API.
+- `backend/src/routes/errors.ts` — first-party client error capture for self-hosted/error-tracking workflows.
+- `backend/tests/phase10-smoke.test.mjs` — node:test smoke suite for auth rejection, public article/comments, optional authenticated comment, and optional publish workflow checks.
+- `backend/src/routes/auth.ts` — local auth, OAuth callbacks, OTP-backed 2FA, session creation, and current-user API.
+- `backend/src/routes/profile.ts` — public profile API, profile edits, verified expert fields for writer profiles, and 2FA-enabled account payloads.
+- `backend/src/routes/admin.ts` — article SEO/quality writes, approval workflow, analytics, newsletter, series, author verification, and article corrections.
+- `backend/src/routes/comments.ts` — comment/reply APIs, likes, upvotes, flags, best-comment sorting, and bulk moderation.
+- `backend/src/routes/public.ts` — public articles/categories/authors/series/newsletter with SEO fields, verified expert fields, and correction notices.
+- `backend/prisma/schema.prisma` — Phase 10 persistence including analytics events, topic follows, trust fields, verified experts, 2FA flags, article corrections, sponsored articles, premium memberships/articles, job listings, and courses.
+
+## Phase 15 Files
+
+Phase 15 adds viewership and top-of-funnel scaling features:
+
+- `scripts/generate-web-stories.mjs` — CSS scroll-snap story generator; outputs `dist/stories/{slug}/index.html`; OG + Twitter Card meta, keyboard navigation.
+- `scripts/generate-comparison-pages.mjs` — comparison static HTML with ItemList + FAQPage + BreadcrumbList JSON-LD.
+- `scripts/generate-company-pages.mjs` — company directory static HTML with Organization JSON-LD.
+- `src/components/QuoteSharer.jsx` — Selection API + Canvas 1080×1080 branded quote card; share/copy/download; analytics tracking.
+- `embed.html` — second Vite rollup entry for widget iframes.
+- `src/embed.jsx` — widget bootstrapper routing by URL path.
+- `src/widgets/GlossaryWidget.jsx` / `ArticleCardWidget.jsx` / `CompanyWidget.jsx` — embeddable cards with dark mode and postMessage resize.
+- `public/embed-loader.js` — third-party snippet that injects sandboxed `<iframe>`.
+- `teknav-data.js` — now exports `comparisons` (10 entries) and `companies` (10 entries).
+- `teknav-pages.jsx` — adds `ComparisonPage` (with localStorage vote widget), `ComparisonsListPage`, `DirectoryListPage`, `CompanyProfilePage`, `StoriesListPage`.
+- `teknav-app.jsx` — routes: `/compare`, `/compare/:slug`, `/stories`, `/directory`, `/directory/:slug`.
+- `backend/src/routes/directory.ts` — adds `GET /api/v1/directory/companies` and `GET /api/v1/directory/companies/:slug`.
+- `nginx/nginx.conf.example` — `/embed/` location with `frame-ancestors *` CSP.
+- `vite.config.js` — `rollupOptions.input: { main: 'index.html', embed: 'embed.html' }`.
+
+Build pipeline (in `package.json`): `seo:sitemap → og:images → vite build → check-no-cdn → check-responsive → generate-article-pages → generate-web-stories → generate-comparison-pages → generate-company-pages → generate-en-page → generate-author-pages → generate-semantic-pages → compress-dist`.
+
+## Key Files
+
+| Path | Purpose |
+|---|---|
+| `src/main.jsx` | Vite entry, mounts app, dismisses splash loader |
+| `src/styles/global.css` | fonts, reset, keyframes, shared utilities |
+| `teknav-app.jsx` | root route dispatch |
+| `teknav-ui.jsx` | providers, header/footer, shared UI |
+| `teknav-admin.jsx` | CMS UI, article editor, media library, dashboard |
+| `src/lib/api.js` | fetch wrapper with credentials and CSRF |
+| `src/lib/content-api.js` | public content API client |
+| `src/lib/admin-api.js` | admin API client |
+| `src/lib/engagement-api.js` | comments, history, notifications, follows client |
+| `src/components/QuoteSharer.jsx` | Selection API + Canvas quote card sharer |
+| `src/embed.jsx` | Widget iframe bootstrapper (second Vite entry) |
+| `src/widgets/` | GlossaryWidget, ArticleCardWidget, CompanyWidget |
+| `public/embed-loader.js` | Third-party `<script>` snippet for embedding widgets |
+| `backend/src/lib/realtime.ts` | Redis pub/sub, SSE, visitor counter helpers |
+| `backend/src/routes/admin.ts` | admin API routes |
+| `backend/src/routes/auth.ts` | login/logout API |
+| `backend/src/routes/public.ts` | public content endpoints |
+| `backend/src/routes/directory.ts` | public + authenticated company directory endpoints under `/api/v1/directory/companies` |
+| `backend/src/routes/comments.ts` | article comments, flags, moderation API |
+| `backend/src/routes/history.ts` | reading history API |
+| `backend/src/routes/notifications.ts` | notification list and SSE stream |
+| `backend/src/routes/follows.ts` | writer follow API |
+| `backend/src/routes/admin-stream.ts` | admin SSE stream |
+| `backend/prisma/schema.prisma` | Prisma schema |
+| `backend/prisma/seed.ts` | seed data, Persian FTS setup |
+| `backend/src/config.ts` | env/config with Zod validation |
+
+## Reference Docs
+
+- `CLAUDE.md` — directives and quick reference
+- `ARCH.md` — roadmap and current work status
+- `MEMORY.md` — durable project context
+- `DEPLOY.md` — production deployment runbook
+- `SECURITY.md` — security practices
+- `PHASES.md` — completed phase history
+
+
+ # Using Gemini CLI for Large Codebase Analysis
+
+  When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive
+  context window. Use `gemini -p` to leverage Google Gemini's large context capacity.
+
+  ## File and Directory Inclusion Syntax
+
+  Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the
+   gemini command:
+
+  ### Examples:
+
+  **Single file analysis:**
+  ```bash
+  gemini -p "@src/main.py Explain this file's purpose and structure"
+
+  Multiple files:
+  gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"
+
+  Entire directory:
+  gemini -p "@src/ Summarize the architecture of this codebase"
+
+  Multiple directories:
+  gemini -p "@src/ @tests/ Analyze test coverage for the source code"
+
+  Current directory and subdirectories:
+  gemini -p "@./ Give me an overview of this entire project"
+  
+#
+ Or use --all_files flag:
+  gemini --all_files -p "Analyze the project structure and dependencies"
+
+  Implementation Verification Examples
+
+  Check if a feature is implemented:
+  gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"
+
+  Verify authentication implementation:
+  gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"
+
+  Check for specific patterns:
+  gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"
+
+  Verify error handling:
+  gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"
+
+  Check for rate limiting:
+  gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"
+
+  Verify caching strategy:
+  gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"
+
+  Check for specific security measures:
+  gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"
+
+  Verify test coverage for features:
+  gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"
+
+  When to Use Gemini CLI
+
+  Use gemini -p when:
+  - Analyzing entire codebases or large directories
+  - Comparing multiple large files
+  - Need to understand project-wide patterns or architecture
+  - Current context window is insufficient for the task
+  - Working with files totaling more than 100KB
+  - Verifying if specific features, patterns, or security measures are implemented
+  - Checking for the presence of certain coding patterns across the entire codebase
+
+  Important Notes
+
+  - Paths in @ syntax are relative to your current working directory when invoking gemini
+  - The CLI will include file contents directly in the context
+  - No need for --yolo flag for read-only analysis
+  - Gemini's context window can handle entire codebases that would overflow Claude's context
+  - When checking implementations, be specific about what you're looking for to get accurate results # Using Gemini CLI for Large Codebase Analysis
+
+
+  When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive
+  context window. Use `gemini -p` to leverage Google Gemini's large context capacity.
+
+
+  ## File and Directory Inclusion Syntax
+
+
+  Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the
+   gemini command:
+
+
+  ### Examples:
+
+
+  **Single file analysis:**
+  ```bash
+  gemini -p "@src/main.py Explain this file's purpose and structure"
+
+
+  Multiple files:
+  gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"
+
+
+  Entire directory:
+  gemini -p "@src/ Summarize the architecture of this codebase"
+
+
+  Multiple directories:
+  gemini -p "@src/ @tests/ Analyze test coverage for the source code"
+
+
+  Current directory and subdirectories:
+  gemini -p "@./ Give me an overview of this entire project"
+  # Or use --all_files flag:
+  gemini --all_files -p "Analyze the project structure and dependencies"
+
+
+  Implementation Verification Examples
+
+
+  Check if a feature is implemented:
+  gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"
+
+
+  Verify authentication implementation:
+  gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"
+
+
+  Check for specific patterns:
+  gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"
+
+
+  Verify error handling:
+  gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"
+
+
+  Check for rate limiting:
+  gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"
+
+
+  Verify caching strategy:
+  gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"
+
+
+  Check for specific security measures:
+  gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"
+
+
+  Verify test coverage for features:
+  gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"
+
+
+  When to Use Gemini CLI
+
+
+  Use gemini -p when:
+  - Analyzing entire codebases or large directories
+  - Comparing multiple large files
+  - Need to understand project-wide patterns or architecture
+  - Current context window is insufficient for the task
+  - Working with files totaling more than 100KB
+  - Verifying if specific features, patterns, or security measures are implemented
+  - Checking for the presence of certain coding patterns across the entire codebase
+
+
+  Important Notes
+
+
+  - Paths in @ syntax are relative to your current working directory when invoking gemini
+  - The CLI will include file contents directly in the context
+  - No need for --yolo flag for read-only analysis
+  - Gemini's context window can handle entire codebases that would overflow Claude's context
+  - When checking implementations, be specific about what you're looking for to get accurate results

app/ARCH.md

@@ -0,0 +1,155 @@
+# ARCH.md
+
+Living roadmap and current work status. Detailed completed phase history is in `PHASES.md`; durable project facts are in `MEMORY.md`.
+
+## Current Focus
+
+Phase 15 implemented — Viewership & Top-of-Funnel Scaling. Next step: Linux production validation of Phase 14 schema (pgvector, LMS, Wiki), then content scaling (Phase 16 English `/en/` directory blocked on LTR layout pass).
+
+Core rules:
+- zero CDN dependencies
+- Persian/RTL UI
+- real backend APIs for all panels
+- no Docker deployment work unless explicitly requested
+- keep `ACCOUNTS.md` ignored and nginx-blocked
+
+## Recently Shipped
+
+- **Phase 15 — Viewership & Top-of-Funnel Scaling:**
+  - **15A: Web Stories** — CSS scroll-snap story pages for all 34 published articles at `dist/stories/{slug}/`, `sitemap-stories.xml`, OG + Twitter Card meta tags, keyboard navigation (arrow keys), `<link rel="alternate">` on all article pages. Zero-CDN (AMP replaced with native scroll-snap format).
+  - **15B1: Quote Card Sharer** — `src/components/QuoteSharer.jsx`: Selection API floating tooltip, Canvas 1080×1080 branded card with RTL text wrapping, Web Share API (with PNG download fallback), **copy-to-clipboard** (Persian text + article URL), Escape-to-close, analytics event via `contentApi.trackEvent`.
+  - **15B2: Embeddable Widget System** — `embed.html` second Vite entry, `src/embed.jsx` bootstrapper, 3 widgets (GlossaryWidget, ArticleCardWidget, CompanyWidget) with dark mode (`prefers-color-scheme`) and postMessage resize only on height change; `public/embed-loader.js` third-party snippet; nginx `/embed/` X-Frame-Options exception.
+  - **15C1: Comparison Pages** — 10 comparisons in `TeknavData.comparisons` (react-vs-vue, postgresql-vs-mongodb, docker-vs-podman, next-js-vs-remix, claude-vs-gpt, python-vs-rust, postgresql-vs-mysql, fastapi-vs-django, kubernetes-vs-docker-compose, tailwind-vs-css-modules); `dist/compare/{slug}/` with ItemList + FAQPage + BreadcrumbList JSON-LD; `ComparisonsListPage`; `ComparisonPage` with **localStorage vote widget** (no backend) and **share button**; `factCheckedAt` display; related comparisons block on article pages.
+  - **15C2: Tech Directory** — 10 companies in `TeknavData.companies` (virgool, divar, snapp, zarinpal, faraname, quera, cafebazaar, tapsi, basalam, sheypoor); `dist/directory/{slug}/` with Organization + BreadcrumbList JSON-LD; `DirectoryListPage` + `CompanyProfilePage`; `GET /api/v1/directory/companies` and `GET /api/v1/directory/companies/:slug` public endpoints; CompanyWidget with static fallback.
+  - **Content:** art37 `vibe-coding-mcp-2026` — 14-section Persian article on Vibe Coding + MCP protocol.
+  - **StoriesListPage** at `/stories` — 9:16 thumbnail grid with title + category overlay.
+  - **Footer nav** updated with Tools section (compare, stories, directory, glossary, tools).
+  - **Profile badges** — `engagementApi.getBadges()` displays 8 badge types on user profiles.
+  - `preflight:prod`: 0 failures.
+
+- **Production hardening & validation pass:**
+  - Fixed Fastify schema validation error mapping: Moved `app.setErrorHandler` early in the fastify server lifecycle to ensure it propagates down to routes/plugins. Added validation error mapping so `FST_ERR_VALIDATION` / `err.validation !== undefined` errors return `invalid_input` to comply with frontend API requirements and contract tests.
+  - Resolved public mutating endpoints test failures; all contract tests are now passing 100% on Linux.
+  - Updated production Nginx site configurations (`/etc/nginx/sites-available/teknav`) to serve all pre-rendered semantic folders (`/category/`, `/tag/`, `/glossary/`, `/topics/`, `/series/`, `/author/`, `/profile/`) and static pages (`/en/`, `/articles/`, `/privacy/`, etc.) directly from disk using `gzip_static on` and `brotli_static on`, avoiding redirect loops and dynamic sub_filter cost.
+  - Added root `.env.prod.example` aligned with `/etc/teknav/backend.env` for PostgreSQL, Redis, sessions, CORS, uploads, SMTP, SMS, VAPID, Zarinpal, and storage.
+  - Added `npm run preflight:prod` (`scripts/production-readiness.mjs`) to check env/docs/nginx/script readiness, credential exposure, generated Prisma engine artifacts, and migration/test posture.
+  - Added backend public contract tests in `backend/tests/public-contract.test.mjs`; existing smoke tests now auto-skip when no API is running and become strict with `TEST_REQUIRE_SERVER=1`.
+  - `/api/v1/health` returns minimal public health; `/api/v1/ready` returns 503 when PostgreSQL or Redis is unavailable; `/api/v1/admin/health` exposes authenticated diagnostics, feature flags, and uptime.
+- **Phase 14 — Farsi Knowledge & Tech Ecosystem (implemented this session):**
+  - Wiki & Glossary Proposals: `WikiProposal` and `GlossaryProposal` Prisma models; `POST /api/v1/wiki/proposals` and `PATCH /api/v1/admin/wiki/proposals/:id`; `DiffViewer` React component highlighting additions/deletions.
+  - Automated Internal Linking Engine: `link-engine.ts` utilizing `cheerio` to scan HTML content of newly published articles and inject `<a href="/glossary/:slug">` anchors to glossary terms safely.
+  - Semantic Search & RAG: `ArticleEmbedding` Prisma model; `pgvector` extension; `POST /api/v1/search/semantic` for context-aware related articles; `GET /api/v1/rag/:slug` for machine-readable raw Markdown context extraction.
+  - Learning Management System (LMS): `LearningPath`, `LearningModule`, `Quiz`, and `UserCertification` Prisma models; `POST /api/v1/lms/quiz/:quizId/submit` and `GET /api/v1/lms/me`; auto-issued student certificates (`>=80` pass score); `LmsPanel` student dashboard UI.
+  - Tech & Startup Directory: `CompanyProfile` and `CompanyClaim` Prisma models; interactive Farsi directory UI (`DirectoryPanel`); authenticated endpoint to claim company profiles with verification proof.
+- **Phase 13 — Community depth + writer tools:**
+  - Guest push subscriptions: nullable `userId` on `PushSubscription`, `topics String[]`, `POST /api/v1/push/guest-subscribe` (IP-rate-limited), `sendGuestPushByTopic()` in `push.ts`, `publish-due.mjs` fans out to guest subs, "🔔 دریافت اعلان" button on topic hub pages.
+  - Fine-grained notification center: `NotificationPreference` model + `GET/PUT /api/v1/auth/notifications/preferences`; `sendPushToUser()` checks push preference before delivery; collapsible toggle grid in `ProfileSettingsModal`.
+  - Verified reader badges: `UserBadge` model + 8 badge rules evaluated in `publish-due.mjs` cron; `GET /api/v1/auth/badges` + `GET /api/v1/admin/users/:id/badges`.
+  - Article version history: `ArticleRevision` snapshot on every PATCH (capped at 20); `GET/GET/POST /api/v1/admin/articles/:id/revisions[/:id[/restore]]` in `revisions.ts`; `RevisionDrawer` side-panel in `ArticleEditor` with content preview and restore.
+  - Collaborative presence: Redis TTL keys (`presence:article:{id}:user:{uid}`, 45s); `POST /api/v1/admin/articles/:id/heartbeat` + `GET /api/v1/admin/articles/:id/presence`; `ArticleEditor` polls every 30s; avatar chips shown when 2+ editors online.
+- **Phase 12 — Web push notifications + published article editing:**
+  - Browser web push (RFC 8030/VAPID): `PushSubscription` Prisma model + relation on `User`; `backend/src/lib/push.ts` with `sendPushToUser()` fanning out to all user subscriptions, auto-cleaning expired (410) endpoints; `GET /api/v1/auth/push/vapid-key`, `POST /api/v1/auth/push/subscribe`, `DELETE /api/v1/auth/push/unsubscribe` routes in `notifications.ts`; `createNotification()` in `realtime.ts` extended with non-blocking push fan-out; service worker `push` + `notificationclick` handlers with Persian RTL options; `pushApi` client in `engagement-api.js`; `PushNotificationPrompt` dismissible banner in `teknav-ui.jsx`; push toggle (enabled/blocked/unsupported states) in `ProfileSettingsModal`.
+  - Published article editing: `ArticleEditor` now accepts `role` prop and derives `isPublished` / `canPublishDirectly`; shows role-appropriate info banner and button set (admin/editor: "بروزرسانی و انتشار" / "تبدیل به پیش‌نویس" / "زمان‌بندی مجدد"; writer: "ذخیره پیش‌نویس" / "ارسال برای بررسی مجدد"); fixed critical backend bug in `admin.ts` PATCH route (was converting `PUBLISHED → PENDING` before the Phase10 quality-gate block, now skips status in the bulk update and lets `publishArticleWithPhase10Checks()` handle it cleanly); `quality_check_failed` error now surfaced in the editor save handler.
+  - `scripts/generate-seo.mjs` variable-shadow bug fixed: local `xml` array inside `url()` renamed to `lines` so the outer `xml()` escape function is no longer shadowed.
+  - `DEPLOY.md` updated: VAPID key generation block, three VAPID env vars in Section 6, VAPID private key security note, and "Web push not delivering" troubleshooting block.
+
+- **Phase 11 — Platform completeness (implemented this session):**
+  - Track 1 admin quick wins: sponsored/premiumOnly/featured toggles in ArticleEditor; content freshness filter in article list; dedicated SEO audit tab (full paginated table); dedicated engagement analytics sub-tab with bar chart and event breakdown; bulk comment moderation with checkbox selection and floating action bar.
+  - Track 2 reader UX: article card save-list picker (ReadingListModal wired to bookmark button); continue-reading progress overlay on home feed cards (progress bar + "ادامه مطالعه" chip); scheduled-publish notifications extended to topic followers; Google/Bing webmaster verification placeholder files in `public/`.
+  - Track 3 monetization: premium gate card redesigned (blurred fade + crown icon + benefit list + dual CTA); Zarinpal membership subscription flow end-to-end (`POST /api/v1/membership/subscribe` → gateway redirect → `GET /api/v1/membership/callback` → tier upgrade + notification → `/membership/success`); job listing admin panel with approve/reject/featured actions; premium content enforcement confirmed in `publicArticle()`.
+  - Track 4 reliability: `ClientError` Prisma model + `GET /api/v1/admin/errors` aggregated admin view + admin "خطاهای کلاینت" tab with daily sparkline and top-errors table; `StorageAdapter` interface in `backend/src/lib/storage.ts` — `LocalStorageAdapter` is active (default, no env var needed), `S3StorageAdapter` stub activates with `STORAGE_BACKEND=s3`; upload route in `admin.ts` switched to use the adapter.
+  - Schema additions: `ClientError`, `MembershipPayment`, `JobListing.featuredUntil`, `NotificationType.system` enum value.
+  - 32 articles with complete metadata now in `teknav-data.js`; all `contentFreshnessStatus` values corrected to enum-valid values.
+- Phase 10 foundation: `/topics/*` authority hubs, public tag pages, topic/series/newsletter structured data, sitemap topic/profile/newsletter/tag coverage, topic follows, newsletter archive pages, share tracking, role-aware panel metrics, approval-to-publish quality gates, production smoke script, editorial quality fields, first-party analytics events, and admin SEO/analytics endpoints.
+- **Writer Studio V5 polish (Phase 10 close-out):** HtmlEditor grouped toolbar with hover states and keyboard shortcuts (Ctrl+B/I/S); live word/char count footer; WritingTipCard prev/next nav with timer reset; ArtifactStudio diagram library replaced gradient placeholders with live scaled mini-previews; analytics sparklines upgraded to filled-area SVG with gradient and date labels; analytics table gains prefetched inline mini-sparklines per row and a totals footer; dirty-state indicator; reviewer feedback banner; articles list pagination; backend `articleInclude` joins `review { note, status }` and `publicArticle` exposes `reviewNote`.
+- Phase 9 publication features: SEO article fields, daily view logs, related articles, article series, comment likes, reading lists, newsletter campaigns, review workflow, and admin analytics.
+- Phase 8 reader engagement: article comments/replies, comment flagging, reading history, in-app notifications, writer follows, and SSE-powered live admin signals.
+- Username login: users can authenticate with email or `@username`.
+- Signup finalization: display name, username, password, and email/phone are collected.
+- Profile finalization: every role can edit display name, username, bio, avatar, verification data, and password.
+- Seed finalization: every seeded user gets a username.
+- Writer-admin accounts: آرسام صباغ, رادمان قلیچی, سیداحمدرضا محجوب in `backend/prisma/credentials.json`; operator credentials in ignored `ACCOUNTS.md`.
+- Native deployment docs: `DEPLOY.md` covers systemd, nginx, TLS, env, backups, schema apply, scheduled publishing, and health checks.
+- Phase 7 CMS readiness: media library, scheduled publishing, activity CSV export, real dashboard metrics, SMTP email flows, Kavenegar OTP.
+
+## Active Checklist
+
+### Phase 14 — Linux production setup (required before new features go live)
+- [ ] Install PostgreSQL `vector` extension as superuser (`sudo -u postgres psql -c 'CREATE EXTENSION vector;'`)
+- [ ] Rebuild Persian FTS structure: run `node scripts/setup-fts.js` (or via `seed.ts`) if schema pushes drop generated columns.
+- [ ] `cd backend && npm run prisma:apply` — apply Phase 14 schema additions
+- [ ] `cd backend && npm run prisma:generate` — regenerate Prisma client
+- [ ] Verify LMS functionality: take quiz, pass with >=80, and verify certificate issues on `/api/v1/lms/me`.
+- [ ] Verify Semantic Search: query `/api/v1/search/semantic` and check for vector distance calculation correctness.
+
+### Phase 13 — Linux production setup
+- [ ] `cd backend && npm run prisma:generate` — regenerate Prisma client
+- [ ] Verify guest push: visit topic hub → click "🔔 دریافت اعلان" → grant permission → push subscription in DB with `userId=null`
+- [ ] Verify notification preferences: profile settings → "تنظیمات اعلان‌ها" → toggle push channel → notification skipped on next trigger
+- [ ] Verify revision history: edit any article → save → open "تاریخچه" drawer → revision appears → restore works
+- [ ] Verify presence: open same article in two tabs → both show avatar chip in editor header
+
+### Phase 12 — Linux production setup (required before push goes live)
+- [ ] `cd backend && npm install web-push` — install web-push package (can't install on Windows)
+- [ ] Generate VAPID keys: `node -e "const wp=require('web-push');const k=wp.generateVAPIDKeys();console.log(JSON.stringify(k,null,2))"`
+- [ ] Add to `/etc/teknav/backend.env`: `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT=mailto:admin@teknav.ir`
+- [ ] `cd backend && npm run prisma:generate` — regenerate client for `PushSubscription` model
+- [ ] `cd backend && npm run prisma:apply` — apply all Phase 11+12 schema additions
+- [ ] `cd backend && npm run seed` — reseed if needed
+
+### Full Linux production verification
+- [ ] `npm run preflight:prod` — static production-readiness audit before build/deploy
+- [ ] `npm run seo:sitemap` — regenerate sitemaps
+- [ ] `npm run check:seo` — audit Persian article SEO quality gate
+- [ ] `npm run build` — frontend build
+- [ ] `cd backend && npm run build` — backend TypeScript build
+- [ ] Start backend and run `cd backend && TEST_REQUIRE_SERVER=1 npm test` — strict endpoint contract smoke suite
+- [ ] `npm run smoke:prod` — smoke test all endpoints
+- [ ] Verify `/api/v1/ready` returns 200 when PostgreSQL and Redis are healthy and 503 during dependency failure.
+- [ ] Verify Phase 8–10 flows: comments, history, notifications/SSE, reading lists, follows, analytics, review workflow, newsletter campaigns.
+- [ ] Verify Phase 11 flows: `/membership` subscribe → Zarinpal callback → success page; `/api/v1/admin/jobs` approve/reject; `/api/v1/admin/errors` aggregated view; premium gate card on premium articles; article card bookmark → reading list picker; continue-reading overlay on home feed.
+- [ ] Verify Phase 12 push flow: log in as reader → `PushNotificationPrompt` banner appears → grant permission → `PushSubscription` row in DB → profile toggle shows "فعال" → publish article or trigger comment reply → browser push notification arrives → click notification navigates correctly.
+- [ ] Verify published article editing: admin opens published article → sees green "بروزرسانی و انتشار" button → save updates content and keeps status published; writer opens own published article → sees draft/re-review buttons → save demotes to draft/pending.
+- [ ] Verify `/api/v1/errors` persists to `ClientError` table (was logging-only before Phase 11).
+- [ ] Verify `STORAGE_BACKEND` is unset or `local` on server — uploads go to `/var/lib/teknav/uploads`.
+- [ ] Verify `/ACCOUNTS.md` returns 404/403 through nginx.
+- [ ] Rotate production passwords after first login.
+- [ ] Set `ZARINPAL_MERCHANT_ID` in `/etc/teknav/backend.env` when payment goes live.
+- [ ] Remove `resetPasswordOnSeed` from writer-admin accounts after rotation.
+- [ ] Confirm SMTP and Kavenegar credentials on the server.
+
+## Roadmap
+
+### Done
+
+- Phase 1: Vite/React conversion and zero-CDN frontend.
+- Phase 2: PostgreSQL/Prisma/Redis backend seed and Persian FTS.
+- Phase 3: Argon2id auth, Redis sessions, CSRF, captcha, login/signup.
+- Phase 4: public REST API, caching, search, newsletter, reactions/saves.
+- Phase 5: role-gated Admin/CMS API and API-backed admin panel.
+- Phase 6: native nginx/systemd deployment assets and runbook.
+- Phase 7: profiles, media, scheduled publishing, verification delivery, SEO/crawler artifacts, account finalization.
+- Phase 8: reader engagement and real-time admin over SSE.
+- Phase 9: content modernization, SEO enrichment, publication workflow, reading lists, newsletter campaigns, article series, and analytics.
+- Phase 10: topic authority hubs, tag pages, newsletter archive, topic/writer follows, share tracking, role-aware panel metrics, approval-to-publish quality gates, editorial fields, first-party analytics events, admin SEO/analytics endpoints, production smoke checks, PWA, reading streaks, personalized feed, comment upvoting, reactions, Q&A, glossary, comparison templates, OAuth, 2FA, verified expert badges, errata, monetization foundations (jobs/courses/membership/premium), Writer Studio V5 full polish, and series article navigation. Linux production validation pending.
+
+### Future
+
+Phases 11–14 are implemented. Remaining deferred items:
+
+- **4.1 Automated test suite** `[L]` — expand `backend/tests/` to ~40 tests covering auth edge cases, profiles, reading lists, comment moderation, analytics, and review workflow.
+- **4.4 Meilisearch evaluation** `[S]` — stand up Meilisearch on staging, index articles, compare Persian FTS quality and latency vs PostgreSQL; write evaluation note in `docs/meilisearch-eval.md`.
+
+Phase 15 candidates:
+- Expand structured public feeds: topic/tag/author feeds plus machine-readable JSON exports for approved public content only; never include drafts, private analytics, credentials, comments, or account data.
+- Wire `S3StorageAdapter` with a real S3 client when upload volume requires it (activate with `STORAGE_BACKEND=s3`).
+- Expand Zarinpal flow to cover renewal/expiry reminders.
+- Surface earned badges on public profile pages and article comment bylines.
+- Email/SMS channel enforcement in `createNotification()` — currently only push channel is gated by preferences.
+
+## Known Risks
+
+- Production email/SMS requires correct SMTP and Kavenegar credentials.
+- `ACCOUNTS.md` intentionally contains plaintext operator credentials; it must remain ignored and inaccessible over HTTP.
+- This repo currently uses `prisma:apply` because no Prisma migration directory is present.
+- `teknav-store.js` and `teknav-data.js` still exist for seed/reference paths; do not reintroduce them as admin-panel data fallbacks.

app/CLAUDE.md

@@ -0,0 +1,176 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Directives
+
+- **Zero CDN dependencies.** No external JS, CSS, fonts, images, or `cdn.*` URLs. `npm run build` fails on any CDN reference via `scripts/check-no-cdn.mjs`.
+- **Persian/RTL first.** All UI copy is Persian. Layouts assume `direction: rtl`; use logical CSS properties, not left/right.
+- **Frontend uses APIs only.** Never call the database from frontend code. All persistence goes through `/api/v1/*` at the backend. Frontend API clients may pass unversioned `/api/*` paths because `src/lib/api.js` rewrites them to `/api/v1/*`. `teknav-data.js` and `teknav-store.js` are seed/reference data — never use them as admin-panel fallbacks.
+- **No mock admin data.** Admin/writer/reviewer/dashboard/media views must use real backend APIs and show empty/error states when data is missing.
+- **Production is native Linux/systemd + nginx.** No Docker unless explicitly asked. See `DEPLOY.md`.
+- **Protect credentials.** `ACCOUNTS.md` is gitignored and nginx-blocked. Never move it into `public/` or `dist/`. Seed credentials are in `backend/prisma/credentials.json`.
+- **Port and registry are fixed.** Vite dev/preview → port `3009`; npm registry → `https://npm.devneeds.ir/`.
+- **Reuse shared styling.** Use `src/styles/global.css` keyframes/utilities — do not redefine animation primitives.
+- **Phase 15 is current.** Keep `ARCH.md`, `AGENTS.md`, `DEPLOY.md`, and `SECURITY.md` aligned when schema, SEO, trust, retention, or monetization flows change. Phase 14 Linux validation (pgvector + LMS) is still pending before full production go-live.
+- **Production hardening.** Run `npm run preflight:prod` before deploy; run `TEST_REQUIRE_SERVER=1 npm test` in `backend/` against a live backend to enforce endpoint contracts.
+
+## Commands
+
+**Frontend** (repo root):
+```bash
+npm run dev              # Vite dev server → port 3009, proxies /api → localhost:3010
+npm run build            # Full pipeline (see Build Pipeline Order)
+npm run preview          # Preview dist/ on port 4173
+npm run preflight:prod   # Static pre-deploy audit
+npm run seo:sitemap      # Regenerate sitemap.xml, robots.txt, feed.xml
+npm run og:images        # Generate OG images into public/images/og/ (Linux only)
+npm run check:seo        # Audit Persian articles for indexability gaps
+npm run smoke:prod       # Smoke-test all public endpoints
+```
+
+**Backend** (`cd backend` first):
+```bash
+npm run dev              # tsx watch → port 3010
+npm run build            # TypeScript compile
+npm run prisma:generate  # Regenerate Prisma client after schema changes
+npm run prisma:apply     # Apply schema (migrations if present, else db push)
+npm run seed             # Seed PostgreSQL + Persian FTS
+npm run publish:due      # Publish scheduled articles + fan out notifications
+npm test                 # Skips endpoint tests when no backend running
+TEST_REQUIRE_SERVER=1 npm test  # Strict contract tests against a live backend
+```
+
+**Startup order:** PostgreSQL + Redis → `cd backend && npm run dev` → `npm run dev`
+
+**Schema change workflow:** edit schema → `npm run prisma:generate --prefix backend` → `npm run prisma:apply --prefix backend` → backend build.
+
+**Article data change workflow:** edit `teknav-data.js` → `npm run check:seo` → `npm run seo:sitemap` → `npm run build`.
+
+## Build Pipeline Order
+
+```
+seo:sitemap → og:images → vite build → check-no-cdn → check-responsive
+  → generate-article-pages → generate-web-stories → generate-comparison-pages
+  → generate-company-pages → generate-en-page → generate-author-pages
+  → generate-semantic-pages → compress-dist
+```
+
+All `generate-*` scripts produce static HTML that nginx serves directly — never manually edit files under `dist/`. `generate-article-pages` must run after `vite build` (needs `dist/index.html` as template) and before `compress-dist` (so `.gz`/`.br` pairs are created). Phase 15 scripts output: `dist/stories/{slug}/` (web stories), `dist/compare/{slug}/` (comparisons), `dist/directory/{slug}/` (company directory).
+
+## SEO Invariants
+
+- **No `hreflang="en"`.** `?lang=en` is a UI preference only; canonical always points to the clean URL.
+- **No placeholder verification codes.** Never commit `INSERT_GOOGLE_VERIFICATION_CODE` or similar strings.
+- **Static article pages** under `dist/article/{slug}/index.html` are build-time generated — do not edit manually.
+- **Sitemap lastmod must not be future-dated.** `capDate()` in `generate-seo.mjs` enforces this.
+- **Organization schema:** `['Organization', 'NewsMediaOrganization']` — required for Google News.
+- **Article schema:** `['NewsArticle', 'TechArticle']` — required for Google Article rich results.
+- **Run `npm run check:seo`** after any article metadata or content change.
+- **Proven content formula** (article `ai-data-centric-2026` ranked #1 on Google, above Wikipedia): `<p class="lead">` opening, numbered `<h2>` sections, `<strong>` entity highlighting, bilingual terminology (Persian + English inline), technical formulas/data inline, `factCheckedAt` timestamp, 8+ sections / ~3000 words.
+
+## Architecture
+
+**Frontend** — Vite 5 + React 18 ES modules, automatic JSX runtime (no `import React` needed). Route dispatch in `teknav-app.jsx`; pages in `teknav-home.jsx`, `teknav-articles.jsx`, `teknav-pages.jsx`, `teknav-admin.jsx`, `teknav-auth.jsx`, `teknav-profile.jsx`. Providers, header, footer, shared UI in `teknav-ui.jsx`. Styles/fonts/keyframes in `src/styles/global.css`.
+
+**Backend** — Fastify 4 + Prisma 5 + PostgreSQL 16 (+ `pgvector` for semantic search) + Redis 7. Route modules in `backend/src/routes/`. Global error handler registered early in `backend/src/server.ts` — maps `FST_ERR_VALIDATION` to `'invalid_input'` uniformly. Config validated by Zod in `backend/src/config.ts`.
+
+**Data layer** — `teknav-data.js` holds all articles (`art1`–`art35`), authors, categories, topic hub metadata, glossary reference data. Article content beyond art10 lives in `article-contents-{N}.js` files. `src/lib/content-api.js` merges API results over this local fallback (API wins). `teknav-store.js` handles client-side localStorage caching.
+
+**Auth** — Argon2id passwords (m=19MiB, t=2, p=1), Redis sessions (`tek_sid`, 14-day sliding TTL), CSRF double-submit cookie (`tek_csrf`). Login by email or `@username`. Google/GitHub OAuth (authorization-code, state in Redis). SMS 2FA via Kavenegar OTP (`tek_2fa` ticket).
+
+**Role-based access:**
+
+| Role | Access |
+|---|---|
+| `reader` | View, save, react, manage own profile |
+| `reviewer` | + Article review queue |
+| `writer` | + Create/edit own articles |
+| `editor` | + Edit any article, manage categories/tags |
+| `admin` | + Delete articles, manage users |
+
+**Real-time** — SSE at `/api/v1/auth/notifications/stream` (reader) and `/api/v1/admin/stream` (admin live signals). Redis pub/sub is the bus (`backend/src/lib/realtime.ts`).
+
+**Web push** — RFC 8030/VAPID via `web-push`. `PushSubscription` table stores endpoint per user; `userId` nullable for guest topic subscriptions. `sendPushToUser()` checks `NotificationPreference` before delivering. VAPID keys in `/etc/teknav/backend.env` — missing keys make push a silent no-op, all other features unaffected.
+
+**Storage** — `LocalStorageAdapter` active by default (writes to `UPLOAD_DIR`). S3 migration: set `STORAGE_BACKEND=s3` and wire the stub in `backend/src/lib/storage.ts`.
+
+## Phase 14 — Farsi Knowledge & Ecosystem (current, Linux validation pending)
+
+Requires `CREATE EXTENSION vector;` (PostgreSQL superuser) and `prisma:apply` before going live:
+
+| Subsystem | Models | Key endpoints |
+|---|---|---|
+| **Semantic Search / RAG** | `ArticleEmbedding` | `POST /api/v1/search/semantic`, `GET /api/v1/rag/:slug` |
+| **LMS** | `LearningPath`, `LearningModule`, `Quiz`, `UserCertification` | `POST /api/v1/lms/quiz/:quizId/submit`, `GET /api/v1/lms/me` — auto-cert at ≥80 |
+| **Tech Directory** | `CompanyProfile`, `CompanyClaim` | Authenticated claim endpoint |
+| **Wiki/Glossary Proposals** | `WikiProposal`, `GlossaryProposal` | `POST /api/v1/wiki/proposals`, `PATCH /api/v1/admin/wiki/proposals/:id` |
+
+`link-engine.ts` uses `cheerio` to auto-inject `<a href="/glossary/:slug">` anchors into newly published articles.
+
+## Key Files
+
+| Path | Purpose |
+|---|---|
+| `teknav-app.jsx` | Root route dispatch |
+| `teknav-ui.jsx` | Providers, header, footer, `PushNotificationPrompt` |
+| `teknav-home.jsx` | Home page — hero, featured, latest, personalized feed, streaks |
+| `teknav-articles.jsx` | Article detail — comments, TOC, reactions, Q&A, series nav |
+| `teknav-pages.jsx` | Topic hubs, glossary, tag pages, author pages, series, newsletter archive, jobs, courses, directory |
+| `teknav-admin.jsx` | CMS, `ArticleEditor` (role-aware, `RevisionDrawer`, presence chips), LMS panel, directory panel |
+| `teknav-auth.jsx` | Login, signup, OAuth, 2FA, forgot-password |
+| `teknav-profile.jsx` | `/profile/@username`, push toggle, notification preferences, history |
+| `src/lib/api.js` | Fetch wrapper with credentials + CSRF |
+| `src/lib/content-api.js` | Public content client — merges API over local fallback |
+| `src/lib/admin-api.js` | Admin/CMS API client |
+| `src/lib/engagement-api.js` | Comments, history, notifications, follows, streaks, badges, revisions, presence |
+| `src/lib/seo.jsx` | Page-level meta tags and JSON-LD for all page types |
+| `backend/src/server.ts` | Fastify bootstrap — error handler registered before all plugins |
+| `backend/src/routes/admin.ts` | Role-gated article CRUD, publish quality gates, analytics, review, newsletter, series |
+| `backend/src/routes/auth.ts` | Local auth, OAuth, 2FA, session, `/api/v1/auth/me` |
+| `backend/src/routes/comments.ts` | Comments, replies, likes, upvotes, flags, bulk mod. Returns `{items:[],total:0}` (not 404) for unknown slugs. |
+| `backend/src/routes/notifications.ts` | Notification list, SSE stream, VAPID key, push subscribe/unsubscribe |
+| `backend/src/routes/revisions.ts` | Article revision list/get/restore (admin/editor only) |
+| `backend/src/routes/monetization.ts` | Jobs, courses, Zarinpal subscribe/callback/status |
+| `backend/src/routes/errors.ts` | `POST /api/v1/errors` → `ClientError` table; `GET /api/v1/admin/errors` |
+| `backend/src/lib/push.ts` | VAPID, `sendPushToUser()` (checks prefs), `sendGuestPushByTopic()`, 410 cleanup |
+| `backend/src/lib/storage.ts` | `StorageAdapter` — `LocalStorageAdapter` default, `S3StorageAdapter` stub |
+| `backend/src/lib/realtime.ts` | Redis pub/sub, SSE helpers, visitor counter |
+| `backend/prisma/schema.prisma` | Single source of truth for all models |
+| `backend/prisma/seed.ts` | Seed data, staff users, Persian FTS setup |
+| `scripts/production-readiness.mjs` | `npm run preflight:prod` static pre-deploy checklist |
+| `.env.prod.example` | Production env template → copy to `/etc/teknav/backend.env` |
+| `ACCOUNTS.md` | Operator credential sheet — gitignored, nginx-blocked |
+| `deploy/systemd/` | Production systemd units and timers |
+| `nginx/nginx.conf.example` | Production nginx template |
+
+## Production Notes
+
+- nginx must serve pre-rendered semantic folders (`/category/`, `/tag/`, `/glossary/`, `/topics/`, `/series/`, `/author/`, `/profile/`) with `gzip_static on; brotli_static on;` — avoids redirect loops and sub_filter cost.
+- Never copy Windows-generated Prisma engine binaries (`query_engine*.node`) or local `node_modules` to the Linux server.
+- Zarinpal requires `ZARINPAL_MERCHANT_ID` in env; until set, subscribe returns `payment_unavailable`. Use `ZARINPAL_SANDBOX=1` for testing.
+- Phase 12 requires `cd backend && npm install web-push` and VAPID key generation once on Linux.
+- Phase 14 requires `CREATE EXTENSION vector;` as PostgreSQL superuser before `prisma:apply`.
+- After first production login, rotate writer-admin passwords via admin UI, then remove `resetPasswordOnSeed` from `backend/prisma/credentials.json`.
+
+## Large Codebase Analysis (Gemini CLI)
+
+When multiple large files exceed context, use `gemini -p` with `@` path syntax:
+
+```bash
+gemini -p "@src/ @backend/src/ List all API endpoints and their auth requirements"
+gemini -p "@teknav-admin.jsx @backend/src/routes/admin.ts Trace the article publish flow end-to-end"
+gemini --all_files -p "List all Prisma models and their relations"
+```
+
+Paths are relative to where you run `gemini`. Use for cross-file architecture questions or verifying feature coverage across many files.
+
+## Memory
+
+See `MEMORY.md` for full stack context and key paths. See `ARCH.md` for the active roadmap and Phase 14 Linux validation checklist. See `DEPLOY.md` for the full production runbook. See `SECURITY.md` for the pre-deploy security checklist and nginx/Fastify hardening details. See `PHASES.md` for completed phase history. See `PHASE16.md` for the planned English `/en/` subdirectory (blocked on LTR layout pass — not started).
+
+Quick reference:
+- **Stack:** Vite 5 + React 18 / Fastify 4 + Prisma 5 / PostgreSQL 16 + pgvector + Redis 7
+- **Current phase:** 15 (implemented; Phase 14 Linux validation pending)
+- **Writers:** آرسام صباغ (`arsam-sabbagh`), سیداحمدرضا محجوب (`ahmadreza-mahjoub`), رادمان قلیچی (`radman-ghelichi`)
+- **Constraints:** Zero CDN · Persian-first RTL · native Linux/systemd · no mock admin data

app/DEPLOY_RESPONSIVE_FIX.md

@@ -0,0 +1,263 @@
+# Deployment Guide: Mobile Responsive Fix
+
+## Pre-Deployment Checklist
+
+- [x] Build passes with responsive checks: `npm run build` ✅
+- [x] No CDN dependencies introduced ✅
+- [x] No breaking changes to existing functionality ✅
+- [x] No backend/database changes required ✅
+- [x] Zero downtime deployment possible ✅
+
+## Changed Files
+
+```
+M  src/styles/global.css           (responsive CSS rules)
+M  teknav-articles.jsx              (component overflow fixes + mobile CSS)
+M  package.json                     (added check:responsive script)
+A  scripts/check-responsive.mjs     (automated validation)
+A  RESPONSIVE_FIX_SUMMARY.md        (documentation)
+A  DEPLOY_RESPONSIVE_FIX.md         (this file)
+```
+
+## Local Testing (Before Deploy)
+
+```bash
+# 1. Build and verify
+npm run build
+
+# Expected output:
+# ✅ Responsive check PASSED. Layout should work on mobile.
+
+# 2. Preview locally
+npm run preview
+
+# 3. Test in browser at http://localhost:4173
+# - Open DevTools
+# - Toggle device toolbar (Ctrl+Shift+M / Cmd+Shift+M)
+# - Test widths: 360px, 390px, 414px, 640px
+# - Navigate to: /article/cve-2026-41940-cpanel-zero-day-analysis
+# - Verify: no horizontal scroll, title wraps, CVE card stacks
+```
+
+## Production Deployment (Linux)
+
+### Step 1: Upload Code
+
+```bash
+# On your local machine (if using git)
+git add src/styles/global.css teknav-articles.jsx package.json scripts/check-responsive.mjs
+git commit -m "fix: mobile responsive layout for article pages
+
+- Add overflow-x prevention on all article wrappers
+- Implement word-wrap for long titles and technical terms
+- Stack CVE summary cards vertically on mobile
+- Add horizontal scroll for tables and code blocks
+- Integrate automated responsive check in build pipeline
+- Zero breaking changes, CSS/layout only"
+
+git push origin main
+```
+
+### Step 2: Deploy on Server
+
+```bash
+# SSH into production server
+ssh user@teknav.ir
+
+# Navigate to app directory
+cd /srv/teknav/app
+
+# Pull latest changes
+git pull origin main
+
+# Install dependencies (if package.json changed)
+npm ci
+
+# Build with responsive checks
+npm run build
+
+# Expected output should end with:
+# ✅ Responsive check PASSED. Layout should work on mobile.
+```
+
+### Step 3: Reload Nginx (Zero Downtime)
+
+```bash
+# Test nginx configuration
+sudo nginx -t
+
+# Expected output:
+# nginx: configuration file /etc/nginx/nginx.conf test is successful
+
+# Reload nginx (zero downtime)
+sudo systemctl reload nginx
+
+# Verify nginx is running
+sudo systemctl status nginx
+```
+
+### Step 4: Verify Deployment
+
+```bash
+# Check if new assets are served
+curl -I https://www.teknav.ir/ | grep "200 OK"
+
+# Test article page
+curl -I https://www.teknav.ir/article/cve-2026-41940-cpanel-zero-day-analysis | grep "200 OK"
+```
+
+## Post-Deployment Verification
+
+### Browser Testing
+
+1. Open https://www.teknav.ir/article/cve-2026-41940-cpanel-zero-day-analysis
+2. Open DevTools (F12)
+3. Toggle device toolbar (Ctrl+Shift+M)
+4. Test these viewports:
+   - iPhone SE (375px)
+   - iPhone 12 Pro (390px)
+   - Pixel 5 (393px)
+   - Samsung Galaxy S20 (360px)
+   - iPad Mini (768px)
+
+### Validation Checklist
+
+- [ ] Page loads without errors
+- [ ] No horizontal scroll on any mobile width
+- [ ] Article title wraps cleanly (no overflow)
+- [ ] CVE summary card displays as single column
+- [ ] Breadcrumb scrolls horizontally (not page)
+- [ ] Meta row scrolls horizontally (not page)
+- [ ] Tables scroll within their container
+- [ ] Code blocks scroll within their container
+- [ ] All buttons are tappable
+- [ ] Text is readable at all sizes
+- [ ] Desktop layout unchanged
+
+### Performance Check
+
+```bash
+# Check bundle sizes (should be similar to before)
+ls -lh dist/assets/*.css
+ls -lh dist/assets/*.js
+
+# Verify gzip sizes in build output
+npm run build | grep "gzip:"
+```
+
+## Rollback Procedure (If Needed)
+
+```bash
+# On production server
+cd /srv/teknav/app
+
+# Revert to previous commit
+git revert HEAD
+
+# Rebuild
+npm run build
+
+# Reload nginx
+sudo systemctl reload nginx
+```
+
+## Monitoring
+
+After deployment, monitor:
+
+1. **Error logs:**
+   ```bash
+   sudo tail -f /var/log/nginx/error.log
+   ```
+
+2. **Access logs:**
+   ```bash
+   sudo tail -f /var/log/nginx/access.log | grep "article/"
+   ```
+
+3. **Browser console errors:**
+   - Open DevTools Console
+   - Check for JavaScript errors
+   - Check for CSS warnings
+
+4. **Mobile analytics:**
+   - Monitor bounce rate on mobile
+   - Check time-on-page for article pages
+   - Verify mobile engagement metrics
+
+## Troubleshooting
+
+### Issue: Build fails with responsive check errors
+
+**Solution:**
+```bash
+# Run responsive check separately to see details
+npm run check:responsive
+
+# If false positives, adjust thresholds in scripts/check-responsive.mjs
+```
+
+### Issue: Horizontal scroll still present on specific article
+
+**Cause:** Article content may have hardcoded wide elements
+
+**Solution:**
+1. Inspect element in DevTools
+2. Find element causing overflow
+3. Add specific CSS rule in `src/styles/global.css`
+4. Rebuild and redeploy
+
+### Issue: Desktop layout broken
+
+**Cause:** Mobile CSS affecting desktop
+
+**Solution:**
+1. Check media query breakpoints in `src/styles/global.css`
+2. Ensure mobile rules are inside `@media (max-width: 640px)`
+3. Test at 1024px+ viewport width
+
+### Issue: CVE card not stacking on mobile
+
+**Cause:** CSS specificity or missing mobile rule
+
+**Solution:**
+```bash
+# Check if mobile CSS is present in built bundle
+grep -r "cve-summary-card" dist/assets/*.css
+grep -r "grid-template-columns: 1fr" dist/assets/*.css
+```
+
+## Success Criteria
+
+✅ Build completes with "Responsive check PASSED"
+✅ No horizontal scroll on mobile (360px-640px)
+✅ Article titles wrap cleanly
+✅ CVE cards stack vertically on mobile
+✅ Tables/code blocks scroll within containers
+✅ Desktop layout unchanged
+✅ No JavaScript errors in console
+✅ Nginx reload successful (zero downtime)
+
+## Timeline
+
+- **Preparation:** 5 minutes (review changes)
+- **Upload:** 1 minute (git push)
+- **Build:** 10 seconds (npm run build)
+- **Deploy:** 1 second (nginx reload)
+- **Verification:** 5 minutes (manual testing)
+- **Total:** ~12 minutes
+
+## Support
+
+If issues arise:
+1. Check RESPONSIVE_FIX_SUMMARY.md for technical details
+2. Review build output for specific errors
+3. Test locally with `npm run preview`
+4. Rollback if critical issues found
+
+---
+
+**Deployment Status:** READY ✅
+**Risk Level:** LOW
+**Downtime:** ZERO
+**Rollback Time:** <2 minutes

app/Elsevier-Article.md

@@ -0,0 +1,632 @@
+# TekRAG-Persian: A Data-Centric Benchmark for Reducing Hallucination in Persian Technical Question Answering
+
+## Manuscript Type
+
+Research article / benchmark paper
+
+## Target Area
+
+Applied artificial intelligence, information retrieval, natural language processing, low-resource language technologies, retrieval-augmented generation, data quality, and hallucination evaluation.
+
+## Author Information
+
+**Author:** **Arsam Sabbagh**  
+**Affiliation:** Teknav, Tehran, Iran  
+**Corresponding author:** **Arsam Sabbagh**  
+**Email:** admin@teknavglobal.com  
+**ORCID:** [Register at orcid.org and insert 0000-0000-0000-0000]
+
+---
+
+## Highlights
+
+- Introduces TekRAG-Persian, a Persian technical question-answering benchmark for retrieval-augmented generation evaluation.
+- Compares raw, cleaned, and metadata-enriched corpus variants to isolate the effect of data quality on hallucination.
+- Measures hallucination rate, citation accuracy, retrieval quality, and answer faithfulness across six Persian technical domains.
+- Provides a fully reproducible evaluation protocol for data-centric RAG systems in a low-resource morphologically complex language.
+- Demonstrates that provenance and semantic metadata improve factual grounding in Persian technical question answering without model fine-tuning.
+
+---
+
+## Abstract
+
+Retrieval-augmented generation (RAG) has become a prevalent approach for reducing hallucination in large language model applications [1]. However, most RAG evaluations focus on English corpora, general-domain question answering, or model-centric improvements [2,3], while the role of corpus quality in low-resource technical domains remains underexplored. This paper introduces **TekRAG-Persian**, a data-centric benchmark for evaluating hallucination and factual grounding in Persian technical question answering. The benchmark is built around a curated Persian technology corpus covering artificial intelligence, data governance, cybersecurity, software engineering, hardware, and digital infrastructure. We compare three corpus preparation strategies: a raw corpus with minimal preprocessing, a cleaned corpus with normalized Persian text and section-aware chunking, and a metadata-enriched corpus that adds title, category, tags, author, publication date, summary, canonical source, and provenance information to each retrievable chunk. The evaluation protocol measures retrieval quality (Recall@k, MRR), answer correctness, citation accuracy, hallucination rate, unsupported claim count, and operational cost. The study is designed to determine whether data quality interventions can improve factual grounding without requiring model fine-tuning or additional annotation beyond standard human review. By focusing on Persian technical content — a morphologically complex, right-to-left, low-resource language — this work contributes a practical benchmark design and a reproducible methodology for evaluating data-centric RAG systems in underrepresented languages.
+
+**Keywords:** Persian NLP; Retrieval-Augmented Generation; RAG; Hallucination; Data Quality; Low-Resource Languages; Technical Question Answering; Information Retrieval; Provenance; Data-Centric AI
+
+---
+
+## 1. Introduction
+
+Large language models (LLMs) are increasingly deployed as interfaces for technical knowledge bases, enterprise documentation, research archives, and editorial corpora. Retrieval-augmented generation (RAG) [1] has become one of the most practical strategies for improving factual grounding in these systems. Instead of relying exclusively on model parameters, a RAG system retrieves external context and conditions its response on that evidence. In principle, this should reduce hallucination [4,5] and improve traceability. In practice, RAG systems often fail because the retrieved context is incomplete, noisy, duplicated, poorly chunked, outdated, or weakly described by metadata.
+
+The problem is more visible in low-resource and morphologically complex languages such as Persian. Persian technical content often includes mixed Persian–English terminology, inconsistent spelling, Arabic/Persian Unicode character variants, non-standard punctuation, domain-specific abbreviations, and formatting artifacts inherited from web publishing systems. These issues affect tokenization [6], embedding quality, retrieval precision, and the model's ability to ground a generated answer in retrieved evidence. A technically accurate article may become a poor retrieval source if it is inserted into a vector database without careful preprocessing.
+
+Most current research on hallucination addresses model architecture, prompting strategies, or fine-tuning [7,8]. These contributions are important, but they can obscure a simpler operational reality: many hallucinations in deployed RAG systems originate from inadequate data preparation. A model cannot cite evidence that retrieval fails to surface. A generator cannot remain grounded if retrieved chunks lack source identity, heading context, publication date, or semantic metadata. For Persian technical question answering, the absence of well-documented benchmarks makes it difficult to measure how much corpus quality matters independently of model capacity.
+
+This paper proposes **TekRAG-Persian**, a benchmark and evaluation protocol designed to study the effect of data quality on Persian technical RAG systems. The central research question is:
+
+> **How do corpus cleaning, semantic metadata enrichment, and provenance-aware chunking affect retrieval accuracy and hallucination rates in Persian technical question answering using RAG?**
+
+The proposed study compares three corpus variants: raw, cleaned, and metadata-enriched. The raw corpus represents a common operational baseline in which article content is indexed with minimal preprocessing. The cleaned corpus applies Persian text normalization [9], boilerplate removal, and section-aware chunking. The metadata-enriched corpus adds structured context — title, category, tags, author, publication date, canonical URL, summary, and provenance fields — to each chunk.
+
+This work makes three contributions:
+
+1. It defines a Persian technical QA benchmark design for evaluating RAG systems across six technology domains.
+2. It introduces a data-centric evaluation protocol that isolates the impact of corpus preparation from model-level variation.
+3. It provides a measurement framework for hallucination, citation accuracy, retrieval quality, and answer faithfulness in Persian technical question answering.
+
+The study is intentionally applied. It does not introduce a new language model. Instead, it evaluates whether data preparation alone can improve RAG performance in a realistic Persian technical setting, and provides the benchmark infrastructure necessary for future work in this language.
+
+---
+
+## 2. Related Work
+
+### 2.1 Retrieval-Augmented Generation
+
+Retrieval-augmented generation was introduced by Lewis et al. [1] as a method combining parametric and non-parametric memory for open-domain question answering. A retriever — typically a dense bi-encoder [10] — selects passages from an external corpus, and a generator produces an answer conditioned on those passages. RAG is now widely used for enterprise search, customer support, document analysis, and technical assistants [11]. Its core appeal is that external knowledge can be updated without retraining, generated answers can cite sources, and domain-specific corpora can be combined with general-purpose language models.
+
+RAG performance depends on every stage of the pipeline. Errors during document parsing, chunking, embedding, retrieval, reranking, prompt assembly, generation, or citation mapping may produce unsupported or misleading answers [12]. This motivates evaluation methods that measure both retrieval and generation quality in an end-to-end manner.
+
+Several RAG evaluation frameworks have emerged to address these requirements. RAGAS [13] measures context recall, faithfulness, answer relevancy, and context precision. RGB [14] evaluates LLMs specifically for robustness against retrieved noise. ARES [15] introduces an automated evaluation framework using LLM judges. TekRAG-Persian is designed to complement these English-centric frameworks with a Persian-specific, domain-targeted benchmark.
+
+### 2.2 Hallucination in Language Models
+
+Hallucination refers to generated content that is unsupported, factually incorrect, or inconsistent with available evidence [4]. Ji et al. [5] provide a comprehensive survey of hallucination types and mitigation strategies. In RAG systems, hallucination can occur in several forms:
+
+- the generated answer includes claims absent from retrieved sources;
+- the answer cites an incorrect source for a correct claim;
+- the answer combines unrelated retrieved facts into a false conclusion;
+- the answer ignores retrieved evidence and relies on model priors;
+- the answer overgeneralizes beyond the scope of the corpus.
+
+A data-centric hallucination study must therefore evaluate not only final answer correctness, but also whether each claim is traceable to a specific retrieved chunk.
+
+### 2.3 Data-Centric AI and Corpus Quality
+
+Data-centric AI [16] emphasizes improving datasets, labels, metadata, and data pipelines rather than only optimizing model architecture. In RAG systems, data-centric improvements include text normalization, duplicate removal, source attribution, semantic chunking, metadata enrichment, quality filtering, and provenance tracking. Zha et al. [17] demonstrate that data quality interventions can match or exceed model-level improvements on downstream tasks. These findings motivate the corpus variant design in TekRAG-Persian.
+
+### 2.4 Question Answering Benchmarks
+
+English QA benchmarks such as SQuAD [18], TriviaQA [19], Natural Questions [20], and HotpotQA [21] have driven progress in reading comprehension and information retrieval. For RAG evaluation, benchmarks such as MS MARCO [22] and MIRACL [23] have become standard references. Low-resource multilingual benchmarks including MKQA [24] and XQuAD [25] have expanded evaluation to languages beyond English.
+
+Persian question answering remains underrepresented. PersianQA [26] and ParsiNLU [27] provide valuable NLU resources but do not target technical domains or RAG-specific evaluation. TekRAG-Persian fills this gap by focusing on Persian technology journalism as a corpus source, providing structured metadata that supports provenance-aware evaluation.
+
+### 2.5 Persian NLP and Low-Resource Technical QA
+
+Persian presents distinct challenges for NLP systems. The language uses right-to-left script, has Arabic/Persian Unicode character variants (e.g., ك vs. ک, ي vs. ی), includes optional diacritics, requires the zero-width non-joiner (half-space) for correct morphological segmentation, and frequently mixes English technical terms with Persian explanation [9]. Technical Persian writing may contain English acronyms such as RAG, LLM, GPU, API, SQL, CVE, and MCP. These mixed-language patterns affect embedding models, retrieval ranking, and generated answer coherence.
+
+ParsBERT [28] established strong Persian language model baselines. Farahani et al. [29] demonstrated improved performance with Persian-specific pretraining. However, Persian technical RAG evaluation has not been systematically studied, and the effect of corpus metadata on hallucination in this language remains unmeasured.
+
+---
+
+## 3. Benchmark Design
+
+### 3.1 Corpus Scope
+
+The TekRAG-Persian corpus consists of **36 Persian technical articles** drawn from the Teknav technology publication (teknav.ir). Articles span seven domain categories:
+
+| Category | Persian Label | Article Count |
+|---|---|---:|
+| Artificial intelligence | هوش مصنوعی | 9 |
+| Hardware and infrastructure | سخت‌افزار | 9 |
+| Software engineering | نرم‌افزار | 5 |
+| Data science and governance | علم داده | 3 |
+| Cybersecurity | امنیت سایبری | 3 |
+| Technology startups | استارتاپ | 3 |
+| Future of technology | آینده فناوری | 3 |
+| **Total** | | **35** |
+
+Each article includes title, subtitle, summary, body text with heading hierarchy, publication date, author, category, tags, canonical URL, and editorial notes where applicable. The corpus is curated to exclude duplicate pages, incomplete drafts, future-dated unpublished content, and articles without stable canonical URLs.
+
+### 3.2 Document Representation
+
+Each document is converted into the following structured representation before chunking:
+
+```json
+{
+  "article_id": "example-id",
+  "slug": "example-slug",
+  "title": "Persian title",
+  "subtitle": "Persian subtitle",
+  "summary": "Persian summary",
+  "category": "ai",
+  "tags": ["RAG", "LLM", "هوش مصنوعی"],
+  "author": "Author name",
+  "published_at": "YYYY-MM-DD",
+  "canonical_url": "https://www.example.com/article/example-slug",
+  "sections": [
+    {
+      "heading": "Section heading",
+      "text": "Section body"
+    }
+  ]
+}
+```
+
+This representation preserves both content and semantic metadata. It also enables section-aware chunking, which is essential for technical articles with hierarchical heading structures where answer evidence is often localized to a single section.
+
+### 3.3 Question-Answer Set
+
+The benchmark targets **245 Persian questions** in its first version (approximately 7 questions per article on average). Questions are generated semi-automatically from article content and then individually reviewed and corrected by a human annotator before inclusion. Each question is linked to one or more supporting chunks. The question set covers:
+
+- definition questions;
+- comparison questions;
+- cause-and-effect questions;
+- procedural questions;
+- risk and mitigation questions;
+- trend interpretation questions;
+- multi-hop questions requiring evidence from multiple articles.
+
+Each question record follows this schema:
+
+```json
+{
+  "question_id": "q001",
+  "question": "Persian question text",
+  "topic": "ai",
+  "difficulty": "medium",
+  "expected_answer": "Reference answer",
+  "supporting_chunks": ["chunk-123", "chunk-124"],
+  "answer_type": "explanation",
+  "is_multi_hop": false
+}
+```
+
+The expected answer is not a rigid string match target. It provides semantic guidance for human evaluators and permits equivalent paraphrased answers to receive full credit.
+
+---
+
+## 4. Corpus Variants
+
+### 4.1 Raw Corpus (Variant A)
+
+The raw corpus represents a minimal preprocessing baseline. It contains article text extracted with limited cleaning and may preserve formatting artifacts, inconsistent spacing, weak heading context, and minimal metadata. This baseline simulates a common production pattern: indexing content quickly without systematic data preparation.
+
+### 4.2 Cleaned Corpus (Variant B)
+
+The cleaned corpus applies:
+
+- HTML tag removal;
+- boilerplate and navigation text removal;
+- Persian/Arabic Unicode character normalization [9];
+- whitespace and punctuation normalization;
+- half-space (ZWNJ) normalization;
+- heading structure preservation;
+- duplicate paragraph removal;
+- section-aware chunking that aligns chunk boundaries with article headings.
+
+The purpose is to determine whether basic language-aware and format-aware cleaning improves retrieval precision and answer quality independently of metadata changes.
+
+### 4.3 Metadata-Enriched Corpus (Variant C)
+
+The metadata-enriched corpus includes all cleaned text from Variant B, plus structured metadata prepended to each retrievable chunk:
+
+- article title;
+- section heading path;
+- category;
+- tags;
+- author;
+- publication date;
+- article summary;
+- canonical URL;
+- provenance identifier.
+
+The goal is to determine whether adding semantic context to each chunk improves the generator's ability to attribute claims to sources and reduces unsupported generation.
+
+### 4.4 Provenance-Aware Prompting (Variant D)
+
+An optional fourth condition adds provenance-aware prompting to the Variant C corpus. In this setup, the generation prompt explicitly requires the model to answer only from retrieved chunks, cite chunk IDs or canonical URLs for each claim, and respond with a refusal when retrieved context is insufficient. This condition tests whether prompt-level provenance constraints further reduce hallucination when combined with metadata-enriched retrieval.
+
+---
+
+## 5. Methodology
+
+### 5.1 Retrieval Pipeline
+
+For each corpus variant, all pipeline stages are held constant to isolate the effect of corpus quality:
+
+1. parse documents into structured JSON representations (see §3.2);
+2. split documents into chunks using the variant-specific strategy (see §5.2);
+3. generate dense vector embeddings for each chunk using **Google Gemini `text-embedding-004`** (768 dimensions, input limit 2,048 tokens);
+4. index chunks in **Qdrant** (v1.9, local deployment), configured with cosine distance and a vector size of 768. Payload fields store article ID, category, tags, heading path, and provenance metadata for payload-filtered retrieval;
+5. retrieve top-k chunks per query using Qdrant's approximate nearest-neighbour search (HNSW index, `ef = 128`);
+6. assemble the prompt and generate an answer using **Gemma 4 MoE 26B** (see §5.3);
+7. evaluate retrieval and answer quality against ground truth annotations.
+
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(host="localhost", port=6333)
+client.create_collection(
+    collection_name="tekrag_persian",
+    vectors_config=models.VectorParams(
+        size=768,
+        distance=models.Distance.COSINE
+    )
+)
+```
+
+Top-k values of k = 3, k = 5, and k = 8 are evaluated to determine whether metadata improves ranking quality independently of retrieval depth.
+
+### 5.2 Chunking Strategy
+
+The chunking strategy preserves heading context across all corpus variants. Each chunk record contains:
+
+- `chunk_id`: UUID generated from article ID and section offset;
+- `article_id`: parent article identifier;
+- `heading_path`: full heading hierarchy (e.g., "article title › section › subsection");
+- `text`: chunk body in normalized Persian;
+- `word_count`: Persian word count after normalization;
+- `metadata`: populated only in Variants B and C (see §4).
+
+**Target chunk size:** 400–600 Persian words per chunk. This range was selected because:
+- chunks below 400 words frequently lack sufficient context for multi-part questions;
+- chunks above 600 words exceed the effective attention window for precise retrieval with 768-dimensional embeddings and inflate per-query token cost.
+
+Sections shorter than 150 words are merged with the subsequent sibling section under the same heading level. Sections longer than 650 words are split at the nearest paragraph boundary. No sliding-window overlap is used in the primary experiment; a variant with 10% overlap is included as a sensitivity check.
+
+### 5.3 Generation Prompt
+
+A standardized generation prompt is applied across all variants. The prompt instructs the model to:
+
+- answer in Persian;
+- use only the provided retrieved context;
+- cite supporting sources;
+- avoid adding claims not present in the retrieved context;
+- state explicitly when evidence is insufficient.
+
+Standard prompt template:
+
+```
+You are answering a Persian technical question using only the provided context.
+If the context does not support an answer, say that the available evidence is insufficient.
+Do not add claims that are not supported by the context.
+Provide concise citations using the supplied source IDs.
+
+Question:
+{question}
+
+Context:
+{retrieved_chunks}
+
+Answer:
+```
+
+All generation is performed using **Gemma 4 MoE 26B** (Mixture-of-Experts, 26B total parameters) served locally via Ollama. Fixed inference settings applied across all conditions:
+
+| Parameter | Value |
+|---|---|
+| Model | `gemma4:26b-moe` |
+| Temperature | `0.1` |
+| Max output tokens | `512` |
+| Top-p | `0.9` |
+| Repeat penalty | `1.1` |
+| Inference backend | Ollama (local) |
+
+Using a local model eliminates API cost variability and ensures bit-exact reproducibility of generation across all experimental runs.
+
+---
+
+## 6. Evaluation Metrics
+
+### 6.1 Retrieval Metrics
+
+Retrieval quality is evaluated before generation to separate retrieval failures from generation failures:
+
+- **Recall@k**: the fraction of questions for which at least one gold supporting chunk appears in the top-k retrieved set;
+- **Precision@k**: the fraction of retrieved chunks that are gold supporting chunks;
+- **Mean Reciprocal Rank (MRR)**: the mean of the reciprocal rank of the first relevant chunk across all questions;
+- **Supporting chunk hit rate**: the fraction of questions for which all required gold chunks appear in the top-k retrieved set.
+
+### 6.2 Answer Quality Metrics
+
+Generated answers are evaluated along the following dimensions:
+
+- **Correctness**: whether the answer correctly addresses the question;
+- **Completeness**: whether the answer covers all key aspects present in the expected answer;
+- **Faithfulness**: whether all claims in the answer are supported by retrieved context;
+- **Citation accuracy**: whether cited chunk IDs or URLs correctly support the claims they accompany;
+- **Unsupported claim count**: the number of claims that cannot be traced to any retrieved chunk;
+- **Hallucination rate**: the proportion of answers containing at least one unsupported claim.
+
+### 6.3 Human Evaluation Rubric
+
+Human evaluators score each answer on a five-point scale:
+
+| Score | Description |
+|---|---|
+| 1 | Incorrect or predominantly hallucinated |
+| 2 | Partially relevant but mostly unsupported by retrieved context |
+| 3 | Mostly correct but incomplete or weakly cited |
+| 4 | Correct, grounded in retrieved context, and mostly complete |
+| 5 | Correct, complete, concise, and precisely cited |
+
+A minimum of two independent evaluators review a stratified sample of answers. Inter-annotator agreement is reported using Cohen's kappa [30].
+
+### 6.4 Operational Metrics
+
+Operational metrics quantify production viability:
+
+- average query latency (seconds);
+- average input token count;
+- average output token count;
+- estimated cost per query (USD);
+- refusal rate (fraction of questions where the model declared insufficient evidence);
+- average answer length (words).
+
+---
+
+## 7. Experimental Matrix
+
+The main experiment compares four conditions:
+
+| Condition | Corpus | Prompt | Retrieval |
+|---|---|---|---|
+| A | Raw | Standard | Dense vector top-k |
+| B | Cleaned | Standard | Dense vector top-k |
+| C | Metadata-enriched | Standard | Dense vector top-k |
+| D | Metadata-enriched | Provenance-aware | Dense vector top-k |
+
+Optional baselines:
+
+| Condition | Description |
+|---|---|
+| E | No-RAG: model answers without any retrieved context |
+| F | BM25 keyword retrieval only (Variant B corpus) |
+| G | Hybrid retrieval: dense + BM25 (Variant C corpus) |
+| H | Metadata-enriched with cross-encoder reranking |
+
+The no-RAG baseline (Condition E) is particularly important: it quantifies how frequently the model generates unsupported answers when external context is entirely absent, providing an upper bound on model-prior hallucination.
+
+---
+
+## 8. Results
+
+> **Note:** This section presents template tables to be completed with empirical values after running experiments. No values have been fabricated.
+
+### 8.1 Retrieval Results
+
+| Corpus Variant | Recall@3 | Recall@5 | Recall@8 | MRR | Supporting Chunk Hit Rate |
+|---|---:|---:|---:|---:|---:|
+| Raw | — | — | — | — | — |
+| Cleaned | — | — | — | — | — |
+| Metadata-enriched | — | — | — | — | — |
+
+### 8.2 Answer Quality Results
+
+| Condition | Correctness | Completeness | Citation Accuracy | Hallucination Rate | Unsupported Claims (avg) |
+|---|---:|---:|---:|---:|---:|
+| Raw RAG | — | — | — | — | — |
+| Cleaned RAG | — | — | — | — | — |
+| Metadata-enriched RAG | — | — | — | — | — |
+| Provenance-aware RAG | — | — | — | — | — |
+| No-RAG baseline | — | — | N/A | — | — |
+
+### 8.3 Operational Results
+
+| Condition | Avg Latency (s) | Avg Input Tokens | Avg Output Tokens | Cost/Query (USD) | Refusal Rate |
+|---|---:|---:|---:|---:|---:|
+| Raw RAG | — | — | — | — | — |
+| Cleaned RAG | — | — | — | — | — |
+| Metadata-enriched RAG | — | — | — | — | — |
+| Provenance-aware RAG | — | — | — | — | — |
+
+---
+
+## 9. Discussion
+
+The primary hypothesis is that cleaned and metadata-enriched corpora will improve retrieval quality and reduce unsupported generation relative to the raw corpus. If this hypothesis is confirmed, the results provide practical support for a data-centric view of hallucination: for Persian technical RAG, corpus quality, metadata, and provenance contribute independently to answer fidelity, beyond what model architecture alone can provide.
+
+If text cleaning improves retrieval but metadata primarily improves citation accuracy, this distinction is analytically important. It would suggest that Persian normalization and section-aware chunking help the retriever surface relevant evidence, while structured metadata helps the generator use that evidence responsibly. These are separable interventions with different implementation costs.
+
+If provenance-aware prompting increases refusal rate while reducing hallucination, the tradeoff merits explicit discussion. A higher refusal rate indicates that the model correctly recognizes the limits of retrieved evidence, but it also reduces the practical utility of the system for questions that are answerable but weakly represented in the corpus.
+
+Mixed Persian–English terminology deserves focused analysis. Technical Persian frequently contains English acronyms (RAG, LLM, GPU, API, SQL, CVE, MCP) alongside Persian explanations. Metadata-enriched chunks that preserve both Persian tags and English technical terms may bridge queries expressed in either language. This effect should be analyzed by query language composition.
+
+Failure modes should be documented explicitly. Multi-hop questions may remain difficult if relevant evidence is distributed across multiple articles and the retriever does not return all required chunks at any evaluated k. Hallucinations that occur even when correct chunks are retrieved indicate generation-stage weaknesses rather than retrieval failures. These two failure types require different remediation strategies and should be reported separately.
+
+---
+
+## 10. Limitations
+
+This study has several limitations that define the scope of its contribution.
+
+First, the corpus is domain-specific and covers technology journalism and technical explanation. Results may not generalize to medical, legal, literary, conversational, or government Persian.
+
+Second, the benchmark size may be modest in its first version. A dataset of 200 to 500 questions provides sufficient statistical power for comparisons within this domain but may not cover all question types or difficulty distributions.
+
+Third, evaluation depends partly on human judgment, particularly for hallucination identification and completeness scoring. Inter-annotator agreement may be lower for complex technical questions where expert disagreement is expected.
+
+Fourth, the choice of embedding model and generator model affects absolute results. The study controls for these choices by holding them constant across all conditions, but results may not transfer directly to other model families.
+
+Fifth, if the corpus cannot be fully released due to licensing restrictions, reproducibility depends on releasing derived metadata, question sets, evaluation scripts, and a smaller open subset rather than full article text.
+
+These limitations do not invalidate the study. They define the conditions under which the findings hold and guide the design of future work.
+
+---
+
+## 11. Ethics and Data Availability
+
+The corpus includes only content that the authors have the right to process for research purposes. User-generated comments and personal data are excluded. Author names and publication dates are public editorial metadata. The study does not include private user data, unpublished drafts, credentials, analytics logs, or personal identifiers beyond public author metadata.
+
+Data availability options, listed in order of preference:
+
+1. Full public dataset release, including article metadata, chunk records, question-answer pairs, and evaluation scripts, if licensing permits.
+2. Partial dataset release with article IDs, metadata fields, questions, expected answers, and chunk references, with full article text omitted.
+3. Script release only, providing preprocessing, chunking, prompt, and evaluation code so that others can reproduce the pipeline on their own corpora.
+
+Code availability includes preprocessing scripts, chunking logic, prompt templates, retrieval pipeline, evaluation scripts, and metric definitions.
+
+---
+
+## 12. Conclusion
+
+This paper proposes TekRAG-Persian, a data-centric benchmark for evaluating hallucination in Persian technical question answering. The benchmark compares raw, cleaned, and metadata-enriched corpora to measure how corpus preparation affects retrieval quality, citation accuracy, and answer faithfulness in a RAG pipeline. By focusing on Persian technical content — a morphologically complex, right-to-left language underrepresented in current RAG evaluation — the benchmark addresses a practical deployment problem relevant to Persian-language AI developers, publishers, educators, and enterprise teams.
+
+The central argument is that hallucination reduction in RAG is not exclusively a model problem. It is also a corpus quality, metadata design, and provenance problem. TekRAG-Persian provides the benchmark infrastructure to measure this effect, the evaluation protocol to isolate it from model-level variation, and a reproducible methodology that future work can extend to other low-resource languages and technical domains.
+
+---
+
+## Declarations
+
+### Funding
+
+This research received no external funding.
+
+### Conflicts of Interest
+
+The authors declare no competing interests.
+
+### Data Availability
+
+The dataset, metadata, question-answer pairs, and evaluation scripts will be made publicly available upon acceptance through a persistent repository (Zenodo or equivalent). Access details will be provided in the final published version.
+
+### Code Availability
+
+Preprocessing, chunking, retrieval, and evaluation code will be released in a public repository (GitHub or equivalent) upon acceptance. The repository will include full documentation and a reproducibility checklist.
+
+### Ethics Statement
+
+No private user data, personal identifiers, credentials, analytics logs, unpublished drafts, or sensitive information were used in this study. All corpus content consists of publicly available editorial material used in accordance with applicable research use provisions.
+
+### AI-Assisted Writing Disclosure
+
+This manuscript was prepared with AI-assisted language editing. AI tools were used for drafting and revision only; they did not contribute to research design, data collection, experimental execution, or analysis. AI is not listed as an author, in accordance with Elsevier's authorship policy.
+
+---
+
+## References
+
+[1] Lewis, P., Perez, E., Piktus, A., Petroni, F., Karpukhin, V., Goyal, N., Küttler, H., Lewis, M., Yih, W., Rocktäschel, T., Riedel, S., & Kiela, D. (2020). Retrieval-augmented generation for knowledge-intensive NLP tasks. *Advances in Neural Information Processing Systems*, 33, 9459–9474.
+
+[2] Gao, Y., Xiong, Y., Gao, X., Jia, K., Pan, J., Bi, Y., Dai, Y., Sun, J., Wang, M., & Wang, H. (2024). Retrieval-augmented generation for large language models: A survey. *arXiv preprint arXiv:2312.10997*.
+
+[3] Zhao, P., Zhang, H., Yu, Q., Wang, Z., Geng, Y., Fu, F., Yang, L., Zhang, W., Jiang, J., & Cui, B. (2024). Retrieval-augmented generation for AI-generated content: A survey. *arXiv preprint arXiv:2402.19473*.
+
+[4] Huang, L., Yu, W., Ma, W., Zhong, W., Feng, Z., Wang, H., Chen, Q., Peng, W., Feng, X., Qin, B., & Liu, T. (2023). A survey on hallucination in large language models: Principles, taxonomy, challenges, and open questions. *arXiv preprint arXiv:2311.05232*.
+
+[5] Ji, Z., Lee, N., Frieske, R., Yu, T., Su, D., Xu, Y., Ishii, E., Bang, Y. J., Madotto, A., & Fung, P. (2023). Survey of hallucination in natural language generation. *ACM Computing Surveys*, 55(12), 1–38.
+
+[6] Khosravani, A., Bagheri, M., & Minaei-Bidgoli, B. (2021). ParsiNER: A named entity recognition dataset for Persian. *arXiv preprint arXiv:2103.13722*.
+
+[7] Asai, A., Wu, Z., Wang, Y., Sil, A., & Hajishirzi, H. (2024). Self-RAG: Learning to retrieve, generate, and critique through self-reflection. *International Conference on Learning Representations (ICLR 2024)*.
+
+[8] Shi, W., Min, S., Yasunaga, M., Seo, M., James, R., Lewis, M., Zettlemoyer, L., & Yih, W. (2023). REPLUG: Retrieval-augmented black-box language models. *arXiv preprint arXiv:2301.12652*.
+
+[9] Shamsfard, M. (2011). Challenges and open problems in Persian text processing. *Proceedings of the 5th Language and Technology Conference (LTC)*, Poznań, Poland.
+
+[10] Karpukhin, V., Oğuz, B., Min, S., Lewis, P., Wu, L., Edunov, S., Chen, D., & Yih, W. (2020). Dense passage retrieval for open-domain question answering. *Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing (EMNLP)*, 6769–6781.
+
+[11] Fan, A., Grave, E., & Joulin, A. (2021). Reducing transformer depth on demand with structured dropout. In *Workshop on Efficient Natural Language and Speech Processing, NeurIPS 2021*.
+
+[12] Barnett, S., Kurniawan, S., Thudumu, S., Brannelly, Z., & Abdelrazek, M. (2024). Seven failure points when engineering a retrieval augmented generation system. *Proceedings of the IEEE/ACM 3rd International Conference on AI Engineering – Software Engineering for AI (CAIN)*.
+
+[13] Es, S., James, J., Anke, L. E., & Schockaert, S. (2024). RAGAS: Automated evaluation of retrieval augmented generation. *Proceedings of the 18th Conference of the European Chapter of the Association for Computational Linguistics: System Demonstrations*, 150–158.
+
+[14] Chen, J., Lin, H., Han, X., & Sun, L. (2024). Benchmarking large language models in retrieval-augmented generation. *Proceedings of the AAAI Conference on Artificial Intelligence*, 38(16), 17754–17762.
+
+[15] Saad-Falcon, J., Khattab, O., Potts, C., & Zaharia, M. (2024). ARES: An automated evaluation framework for retrieval-augmented generation systems. *Proceedings of the 2024 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies (NAACL)*, 338–354.
+
+[16] Zha, D., Bhat, Z. P., Lai, K. H., Yang, F., & Hu, X. (2023). Data-centric artificial intelligence: A survey. *arXiv preprint arXiv:2303.10158*.
+
+[17] Zha, D., Lai, K. H., Zhou, K., & Hu, X. (2022). Towards automated imbalanced learning with deep hierarchical reinforcement learning. *Proceedings of the 31st ACM International Conference on Information and Knowledge Management (CIKM)*, 2476–2485.
+
+[18] Rajpurkar, P., Zhang, J., Lopyrev, K., & Liang, P. (2016). SQuAD: 100,000+ questions for machine comprehension of text. *Proceedings of the 2016 Conference on Empirical Methods in Natural Language Processing (EMNLP)*, 2383–2392.
+
+[19] Joshi, M., Choi, E., Weld, D. S., & Zettlemoyer, L. (2017). TriviaQA: A reading comprehension dataset containing 650k question-answer-evidence triples. *Proceedings of the 55th Annual Meeting of the Association for Computational Linguistics (ACL)*, 1, 1601–1611.
+
+[20] Kwiatkowski, T., Palomaki, J., Redfield, O., Collins, M., Parikh, A., Alberti, C., Epstein, D., Polosukhin, I., Devlin, J., Lee, K., Toutanova, K., Jones, L., Kelcey, M., Chang, M. W., Dai, A. M., Uszkoreit, J., Le, Q., & Petrov, S. (2019). Natural questions: A benchmark for question answering research. *Transactions of the Association for Computational Linguistics*, 7, 452–466.
+
+[21] Yang, Z., Qi, P., Zhang, S., Bengio, Y., Cohen, W., Salakhutdinov, R., & Manning, C. D. (2018). HotpotQA: A dataset for diverse, explainable multi-hop question answering. *Proceedings of the 2018 Conference on Empirical Methods in Natural Language Processing (EMNLP)*, 2369–2380.
+
+[22] Nguyen, T., Rosenberg, M., Song, X., Gao, J., Tiwary, S., Majumder, R., & Deng, L. (2016). MS MARCO: A human-generated machine reading comprehension dataset. *Proceedings of the Workshop on Cognitive Computation: Integrating Neural and Symbolic Approaches (CoCo@NIPS)*.
+
+[23] Zhang, X., Thakur, N., Ogundepo, O., Kamalloo, E., Alfonso-Hermelo, D., Li, X., Liu, Q., Rezagholizadeh, M., & Lin, J. (2023). MIRACL: A multilingual retrieval dataset covering 18 diverse languages. *Transactions of the Association for Computational Linguistics*, 11, 1114–1131.
+
+[24] Longpre, S., Lu, Y., & Daiber, J. (2021). MKQA: A linguistically diverse benchmark for multilingual open domain question answering. *Transactions of the Association for Computational Linguistics*, 9, 1389–1406.
+
+[25] Artetxe, M., Ruder, S., & Yogatama, D. (2020). On the cross-lingual transferability of monolingual representations. *Proceedings of the 58th Annual Meeting of the Association for Computational Linguistics (ACL)*, 4623–4637.
+
+[26] Darvishi, K., Rahimi, M., Peskoff, S., & Yaghoobzadeh, Y. (2022). PersianQA: A dataset for Persian question answering. *Proceedings of the 13th Language Resources and Evaluation Conference (LREC)*, 2887–2897.
+
+[27] Khashabi, D., Cohan, A., Shakeri, S., Hosseini, P., Pezeshkpour, P., Alikhani, M., Aminnaseri, M., Bitaab, M., Brahman, F., Ghazarian, S., Ghorbani, M., Yaghoobzadeh, Y., & Hajishirzi, H. (2020). ParsiNLU: A suite of language understanding challenges for Persian. *Transactions of the Association for Computational Linguistics*, 9, 1147–1162.
+
+[28] Farahani, M., Gharachorloo, M., Farahani, M., & Manthouri, M. (2021). ParsBERT: Transformer-based model for Persian language understanding. *Neural Processing Letters*, 53(6), 3831–3847.
+
+[29] Farahani, M., Gharachorloo, M., & Manthouri, M. (2022). Towards Persian abstractive text summarization. *IEEE Access*, 10, 48952–48963.
+
+[30] Cohen, J. (1960). A coefficient of agreement for nominal scales. *Educational and Psychological Measurement*, 20(1), 37–46.
+
+[31] Izacard, G., Caron, M., Hosseini, L., Riedel, S., Bojanowski, P., Joulin, A., & Grave, E. (2022). Unsupervised dense information retrieval with contrastive learning. *Transactions on Machine Learning Research*.
+
+[32] Xiong, L., Xiong, C., Li, Y., Tang, K. F., Liu, J., Bennett, P., Ahmed, J., & Overwijk, A. (2021). Approximate nearest neighbor negative contrastive estimation for dense text retrieval. *International Conference on Learning Representations (ICLR 2021)*.
+
+[33] Lin, J., Ma, X., Lin, S. C., Yang, J. H., Pradeep, R., & Nogueira, R. (2021). Pyserini: A Python toolkit for reproducible information retrieval research with sparse and dense representations. *Proceedings of the 44th Annual ACM SIGIR Conference on Research and Development in Information Retrieval*, 2356–2362.
+
+[34] Robertson, S., & Zaragoza, H. (2009). The probabilistic relevance framework: BM25 and beyond. *Foundations and Trends in Information Retrieval*, 3(4), 333–389.
+
+[35] Min, S., Krishna, K., Lyu, X., Lewis, M., Yih, W., Koh, P. W., Iyyer, M., Zettlemoyer, L., & Hajishirzi, H. (2023). FActScoring: Fine-grained atomic evaluation of factual precision in long form text generation. *Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing (EMNLP)*, 12076–12100.
+
+[36] Lazaridou, A., Gribovskaya, E., Stokowiec, W., & Grigorev, N. (2022). Internet-augmented language models through few-shot prompting for open-domain question answering. *arXiv preprint arXiv:2203.05115*.
+
+[37] Team, G., Riviere, M., Pathak, S., Sessa, P. G., Hardin, C., Bhupatiraju, S., Hussenot, L., Mesnard, T., Shahriari, B., Ramé, A., Ferret, J., Liu, P., Tafti, P., Frieson, L., Hussein, C., Asadiabadi, M., Raunak, V., Kasner, Z., Haas, R., … Bachem, O. (2025). Gemma 3 technical report. *arXiv preprint arXiv:2503.19786*.
+
+[38] Izacard, G., Lewis, P., Lomeli, M., Hosseini, L., Petroni, F., Schick, T., Dwivedi-Yu, J., Joulin, A., Riedel, S., & Grave, E. (2023). Atlas: Few-shot learning with retrieval augmented language models. *Journal of Machine Learning Research*, 24(251), 1–43.
+
+[39] Wang, L., Yang, N., Huang, X., Yang, L., Majumder, R., & Wei, F. (2024). Multilingual E5 text embeddings: A technical report. *arXiv preprint arXiv:2402.05672*.
+
+[40] Es, S., James, J., Anke, L. E., & Schockaert, S. (2023). RAGAS: Automated evaluation of retrieval augmented generation. *arXiv preprint arXiv:2309.15217*.
+
+---
+
+## Cover Letter Draft
+
+**Target Journal:** *Information Processing & Management* (Elsevier)  
+ISSN: 0306-4573 | Impact Factor: ~8.6 | Scopus Q1 | CiteScore: ~14  
+Submission system: Elsevier Editorial Manager — https://www.editorialmanager.com/ipm
+
+*Rationale:* IP&M has published multilingual information retrieval benchmarks, RAG evaluation studies, and low-resource NLP papers. It accepts applied NLP dataset contributions with evaluation protocols, aligns with the paper's IR + hallucination measurement framing, and carries strong Scopus indexing relevant to Persian academic visibility.
+
+---
+
+Dear Editor,
+
+We are pleased to submit our manuscript, "TekRAG-Persian: A Data-Centric Benchmark for Reducing Hallucination in Persian Technical Question Answering," for consideration as a research article in *Information Processing & Management*.
+
+This manuscript addresses a practical and underexplored problem in retrieval-augmented generation: the effect of corpus quality, semantic metadata, and provenance-aware chunking on hallucination in Persian technical question answering. While RAG systems are increasingly deployed across enterprise and educational applications, systematic evaluation has remained heavily centered on English and general-domain datasets. Our work contributes a 35-article, 245-question Persian technical QA benchmark and a reproducible, data-centric evaluation protocol comparing raw, cleaned, and metadata-enriched corpora. By isolating corpus preparation as an independent variable, the study provides actionable guidance for practitioners building Persian-language RAG systems without requiring model fine-tuning. Generation is performed using Gemma 4 MoE 26B served locally, and retrieval uses Google Gemini text-embedding-004 embeddings indexed in Qdrant, ensuring full reproducibility.
+
+We believe the manuscript is well-suited for *Information Processing & Management* because it combines applied artificial intelligence, information retrieval, low-resource NLP evaluation, and practical measurement of trustworthy language model systems — all active areas within the journal's scope and consistent with recent publications in the venue.
+
+The manuscript is original, has not been published elsewhere, and is not currently under review by another journal. All authors have approved the submission. Data and code availability statements are included in the declarations section.
+
+We look forward to your consideration.
+
+Sincerely,
+
+**Arsam Sabbagh**  
+Teknav, Tehran, Iran  
+admin@teknavglobal.com
+
+---
+
+## Pre-Submission Checklist
+
+- [x] Finalize target journal → *Information Processing & Management* (Elsevier, IP&M).
+- [ ] Read IP&M Guide for Authors (word limits, reference style APA/numbered, figure DPI).
+- [ ] Register ORCID at orcid.org and add ID to title page.
+- [ ] Complete and verify literature review against final reference list.
+- [ ] Build raw corpus (Variant A) from 35 Teknav articles.
+- [ ] Build cleaned corpus (Variant B): normalize Persian Unicode, remove boilerplate, section-aware chunking.
+- [ ] Build metadata-enriched corpus (Variant C): add title, category, tags, author, date, summary, canonical URL, provenance to each chunk.
+- [ ] Index all three variants in Qdrant (`tekrag_persian` collection, 768-dim Gemini embeddings, cosine distance).
+- [ ] Create and human-review 245 Persian QA pairs (semi-automatic generation + manual annotation).
+- [ ] Run retrieval experiments for all conditions at k = 3, 5, 8.
+- [ ] Run generation experiments with Gemma 4 MoE 26B (Ollama local, temp=0.1).
+- [ ] Complete human evaluation with minimum two annotators; compute Cohen's kappa.
+- [ ] Fill all result tables (§8.1, §8.2, §8.3) with real experimental values.
+- [ ] Update References section with any additional citations found during literature review.
+- [ ] Run plagiarism / self-plagiarism check (iThenticate or similar).
+- [ ] Prepare figures, charts, and supplementary material (pipeline diagram, per-category breakdown).
+- [ ] Adapt formatting to IP&M Word/LaTeX template from Elsevier's author tools page.
+- [ ] Submit through Editorial Manager: https://www.editorialmanager.com/ipm

app/Elsevier.md

@@ -0,0 +1,479 @@
+# Elsevier Publication Plan for Teknav
+
+## Target Direction
+
+The recommended English article path for Teknav is not a translated blog post and not a broad trend essay. The strongest and most realistic scope is an applied research manuscript about Persian technical retrieval-augmented generation, data quality, and hallucination reduction.
+
+Recommended working title:
+
+**TekRAG-Persian: A Data-Centric Benchmark for Reducing Hallucination in Persian Technical Question Answering**
+
+Alternative title:
+
+**Evaluating Data Quality Effects on Hallucination in Persian Technical Retrieval-Augmented Generation Systems**
+
+This direction fits Teknav because the site already has a strong Persian technical corpus, an editorial focus on AI/data quality, and proven topical authority around data-centric AI. It also fits academic indexing better than a general “AI trends” article because it can become a measurable study with a dataset, method, evaluation protocol, results, and limitations.
+
+## Important Reality Check
+
+To appear in Elsevier or Scopus, the work must be accepted by a scholarly venue. A normal website article published on Teknav will not appear in Elsevier automatically. Elsevier journals publish peer-reviewed manuscripts, and Scopus indexes selected journals, book series, conference series, books, and other scholarly sources. The goal is therefore to prepare a manuscript that can survive editor screening and peer review.
+
+Elsevier’s own author guidance emphasizes preparing research for publication and submitting through a suitable journal workflow. Scopus selection guidance emphasizes peer-reviewed content, academic contribution, English titles and abstracts, publication ethics, journal quality, and international readability. This plan is built around those expectations.
+
+Official references:
+
+- Elsevier publishing guide: https://www.elsevier.com/publishing/publish-in-a-journal
+- Scopus content selection policy: https://www.elsevier.com/products/scopus/content/content-policy-and-selection
+
+## Why This Topic Is the Best Fit
+
+Teknav’s strongest existing content advantage is Persian technical writing about AI, data governance, model reliability, RAG, agents, and software systems. The article `ai-data-centric-2026` performed well because it connected a Persian explanation with English technical entities such as Model Collapse, Data Provenance, Semantic Layers, and Data-Centric AI. That same pattern can be converted into a research paper, but the paper must go beyond explanation. It must test something.
+
+The easiest publishable academic niche is:
+
+**How data cleaning, metadata enrichment, and source provenance affect hallucination and answer quality in Persian technical RAG systems.**
+
+This is practical, measurable, and not too compute-heavy. It also has novelty because Persian technical QA is a lower-resource area compared with English benchmarks. The research does not need to invent a new model. It can contribute a benchmark, dataset construction method, evaluation protocol, and empirical findings.
+
+## Core Research Question
+
+The main research question should be:
+
+**How do corpus cleaning, semantic metadata enrichment, and provenance-aware chunking affect retrieval accuracy and hallucination rates in Persian technical question answering using RAG?**
+
+Supporting questions:
+
+1. Does cleaning Persian technical HTML into normalized article text improve retrieval precision?
+2. Does adding metadata such as title, category, tags, author, publication date, and summary improve answer grounding?
+3. Does provenance-aware prompting reduce unsupported claims?
+4. Are improvements consistent across AI, cybersecurity, software, hardware, and data science topics?
+5. What tradeoffs appear in latency, token cost, answer length, and citation accuracy?
+
+## Proposed Contribution
+
+The paper should claim three concrete contributions:
+
+1. **A Persian technical QA benchmark** built from a curated Persian technology corpus.
+2. **A data-centric RAG evaluation protocol** comparing raw, cleaned, and metadata-enriched corpora.
+3. **Empirical evidence** showing how data quality interventions affect hallucination, citation accuracy, and retrieval performance in Persian technical QA.
+
+These contributions are modest enough to execute but real enough to be academically evaluated.
+
+## Dataset Design
+
+The dataset should be called something like `TekRAG-Persian` or `Teknav-Persian-TechQA`.
+
+The corpus can be built from Teknav-style articles, but it must be documented carefully. If the articles are proprietary, state whether the dataset itself is released, partially released, or only the evaluation protocol is released. If public release is possible, that strengthens the paper significantly.
+
+Minimum corpus fields:
+
+- article ID
+- title
+- subtitle
+- canonical URL
+- category
+- tags
+- author
+- publication date
+- summary
+- body text
+- headings
+- source/provenance metadata
+- chunk ID
+- chunk text
+- chunk heading path
+
+Recommended topic categories:
+
+- artificial intelligence
+- data science and data governance
+- cybersecurity
+- software engineering
+- hardware and infrastructure
+- startups/technology strategy
+
+For the first submission, the dataset does not need to be enormous. A clean, well-documented dataset with 200 to 500 question-answer pairs can be more convincing than a noisy large dataset.
+
+## Dataset Versions to Compare
+
+The experimental design should compare at least three corpus variants.
+
+### Variant A: Raw Corpus
+
+This version contains minimally processed article text. It may include HTML remnants, inconsistent headings, duplicated captions, weaker chunk boundaries, and limited metadata.
+
+Purpose:
+
+This simulates the common real-world mistake of dumping content into a vector database without serious data preparation.
+
+### Variant B: Cleaned Corpus
+
+This version normalizes text and structure:
+
+- remove HTML tags
+- normalize Persian/Arabic characters
+- remove duplicate whitespace
+- normalize punctuation where needed
+- preserve headings
+- remove navigation or boilerplate text
+- chunk by section, not arbitrary character count
+
+Purpose:
+
+This tests whether basic Persian content hygiene improves retrieval and answer quality.
+
+### Variant C: Metadata-Enriched Corpus
+
+This version includes cleaned text plus structured metadata:
+
+- title
+- category
+- tags
+- date
+- author
+- summary
+- canonical source
+- heading path
+- provenance label
+
+Purpose:
+
+This tests whether semantic and provenance metadata improves grounding and reduces hallucination.
+
+Optional Variant D:
+
+Provenance-aware generation prompt, where the model must cite chunk IDs and refuse unsupported claims.
+
+## Question-Answer Dataset
+
+Create question-answer pairs manually or semi-manually, but final validation should be human-reviewed. Each question should have:
+
+- question text in Persian
+- topic category
+- expected answer
+- supporting article/chunk IDs
+- difficulty level
+- answer type
+- whether the answer requires one source or multiple sources
+
+Question types:
+
+- definition questions
+- comparison questions
+- cause/effect questions
+- procedure questions
+- risk/mitigation questions
+- trend interpretation questions
+- multi-hop questions requiring two sections or two articles
+
+Example question:
+
+**Question:** چرا داده‌های مصنوعی بدون نظارت می‌توانند باعث فروپاشی مدل شوند؟
+
+Expected answer should cite concepts such as lower entropy, distribution drift, loss of tail events, and recursive training on model-generated data.
+
+## Experimental Setup
+
+The experiment should be reproducible. Keep it simple.
+
+Pipeline:
+
+1. Build corpus variants A, B, and C.
+2. Split articles into chunks.
+3. Generate embeddings.
+4. Store chunks in a vector index.
+5. Retrieve top-k chunks for each question.
+6. Generate answer using a fixed prompt.
+7. Evaluate retrieval and generation.
+
+Suggested top-k values:
+
+- k = 3
+- k = 5
+- k = 8
+
+Suggested chunk sizes:
+
+- heading-based chunks
+- 300 to 700 words per chunk
+- overlap only if necessary
+
+The paper should clearly report the embedding model, vector database or index method, reranker if used, generator model, prompt template, temperature, and hardware/environment.
+
+## Evaluation Metrics
+
+Use both automatic and human evaluation.
+
+Retrieval metrics:
+
+- Recall@k
+- Precision@k
+- Mean Reciprocal Rank
+- supporting chunk hit rate
+
+Answer metrics:
+
+- answer correctness
+- citation accuracy
+- hallucination rate
+- unsupported claim count
+- completeness
+- faithfulness to retrieved context
+
+Operational metrics:
+
+- average token usage
+- latency
+- answer length
+- refusal rate for unsupported questions
+
+Human evaluation rubric:
+
+Score each answer from 1 to 5:
+
+1. incorrect or hallucinated
+2. partially relevant but unsupported
+3. mostly correct with missing detail
+4. correct and grounded
+5. correct, complete, well-cited, and concise
+
+At least two evaluators should review a subset. If possible, report inter-annotator agreement.
+
+## Baselines
+
+The minimum baselines:
+
+1. Raw corpus RAG
+2. Cleaned corpus RAG
+3. Metadata-enriched corpus RAG
+
+Optional stronger baselines:
+
+4. Keyword/BM25 retrieval only
+5. Hybrid retrieval
+6. Metadata-enriched retrieval plus reranking
+7. No-RAG model answer
+
+The no-RAG baseline is useful because it shows how much unsupported generation happens when the model relies on pretraining alone.
+
+## Expected Hypothesis
+
+The expected hypothesis should be stated before running experiments:
+
+**Metadata-enriched and provenance-aware corpus preparation will reduce hallucination and improve citation accuracy compared with raw RAG over Persian technical content.**
+
+Expected results:
+
+- cleaned corpus improves retrieval over raw corpus
+- metadata-enriched corpus improves grounding
+- provenance-aware prompt reduces hallucination
+- multi-hop questions remain the hardest
+- Persian technical terms with English equivalents benefit from metadata and heading preservation
+
+Do not overclaim. If improvements are small, report them honestly.
+
+## Manuscript Structure
+
+Use this structure:
+
+### Title
+
+TekRAG-Persian: A Data-Centric Benchmark for Reducing Hallucination in Persian Technical Question Answering
+
+### Abstract
+
+150 to 250 words:
+
+- problem
+- gap
+- method
+- dataset
+- experiment
+- key results
+- contribution
+
+### Keywords
+
+Persian NLP; Retrieval-Augmented Generation; Hallucination; Data Quality; Low-Resource Languages; Technical Question Answering
+
+### 1. Introduction
+
+Explain why RAG is widely used, why Persian technical QA is underrepresented, and why data quality matters. End with contributions.
+
+### 2. Related Work
+
+Cover:
+
+- RAG
+- hallucination evaluation
+- data-centric AI
+- low-resource NLP
+- Persian NLP
+- technical QA benchmarks
+
+### 3. Dataset Construction
+
+Describe corpus sources, preprocessing, metadata, QA creation, annotation, and statistics.
+
+### 4. Method
+
+Describe retrieval, chunking, embeddings, prompts, models, and experimental variants.
+
+### 5. Evaluation
+
+Define metrics and human evaluation rubric.
+
+### 6. Results
+
+Tables comparing raw vs cleaned vs enriched corpora.
+
+### 7. Discussion
+
+Explain why results happened, where metadata helped, where it failed, and what this means for Persian technical RAG.
+
+### 8. Limitations
+
+Be direct:
+
+- corpus may be domain-specific
+- questions may not cover all Persian styles
+- model choice affects results
+- human evaluation scale is limited
+- dataset release may be partial if licensing restricts full text
+
+### 9. Conclusion
+
+Summarize the contribution and future work.
+
+### Declarations
+
+Include:
+
+- data availability
+- code availability
+- conflict of interest
+- funding
+- ethics statement
+- AI-assisted writing disclosure if applicable
+
+## Journal Targeting Strategy
+
+Do not aim first for the highest-impact AI journal. The paper is applied and benchmark-oriented. Look for journals that accept work in information systems, applied AI, NLP resources, or data-centric systems.
+
+Possible Elsevier-aligned areas:
+
+- information processing
+- computer science applications
+- data and knowledge engineering
+- artificial intelligence applications
+- language resources and evaluation-adjacent venues, even if not Elsevier
+
+Use Elsevier Journal Finder after writing the abstract and keywords. The abstract must be academic, not promotional.
+
+Selection criteria for a target journal:
+
+- accepts applied NLP or information retrieval papers
+- has published RAG, QA, benchmark, or low-resource NLP papers
+- allows dataset/evaluation papers
+- reasonable review timeline
+- not too broad
+- not predatory or suspicious
+- indexed in Scopus if Scopus visibility is required
+
+## Minimum Work Plan
+
+### Week 1: Scope and Literature
+
+- finalize research question
+- collect 30 to 50 relevant papers
+- define contribution
+- choose dataset size
+- draft related work outline
+
+### Week 2: Dataset
+
+- export article corpus
+- clean text
+- create chunking pipeline
+- create metadata-enriched corpus
+- write dataset documentation
+
+### Week 3: QA and Annotation
+
+- create 200 to 500 Persian questions
+- map each question to supporting chunks
+- write expected answers
+- review quality manually
+
+### Week 4: RAG Pipeline
+
+- implement embeddings
+- implement vector search
+- implement prompt templates
+- run raw, cleaned, enriched variants
+
+### Week 5: Evaluation
+
+- calculate retrieval metrics
+- run human evaluation
+- measure hallucination/citation accuracy
+- create tables and charts
+
+### Week 6: Manuscript Draft
+
+- write methods and dataset sections first
+- write results
+- write introduction and abstract last
+- prepare figures and appendices
+
+### Week 7: Internal Review
+
+- check reproducibility
+- check citations
+- check English clarity
+- check ethics/declarations
+- choose target journal
+
+### Week 8: Submission
+
+- adapt formatting to journal guide
+- write cover letter
+- submit manuscript
+- prepare response plan for reviewers
+
+## What Not To Do
+
+Do not submit a Teknav article as-is. It will look like journalism, not research.
+
+Do not make claims like “first ever” unless verified through literature review.
+
+Do not rely only on SEO success as evidence. Google ranking is irrelevant for journal peer review.
+
+Do not overuse generative AI for writing without disclosure. Elsevier and many journals require transparency about AI-assisted writing.
+
+Do not fabricate affiliations, reviewer suggestions, data availability, or experimental results.
+
+Do not hide limitations. Reviewers trust honest limitations more than exaggerated claims.
+
+## Success Criteria Before Submission
+
+The paper is ready when:
+
+- the research question is narrow and testable
+- the dataset is documented
+- the method can be reproduced
+- baseline comparisons are included
+- results are presented with tables
+- hallucination is measured with a clear rubric
+- references are current and peer-reviewed
+- the manuscript is written in academic English
+- all declarations are complete
+- the journal scope clearly matches the paper
+
+## Recommended Final Positioning
+
+Position the paper as a data-centric, low-resource-language RAG evaluation study. The strongest framing is:
+
+**Persian technical RAG systems fail less because of model weakness and more because of corpus quality, metadata, and provenance. This paper measures that effect and provides a benchmark for future work.**
+
+That is a clean academic contribution. It is narrow, testable, connected to Teknav’s strengths, and realistic for an Elsevier or Scopus-indexed publication path.

app/F1-P.md

@@ -0,0 +1,69 @@
+# Teknav Growth Plan: Phase 15 (Viewership & Top-of-Funnel Scaling)
+
+This document outlines the detailed architectural and implementation plan for massively scaling Teknav's viewer base and organic reach. This plan strictly adheres to the core constraints: Zero CDNs, Persian-first RTL, and native Linux deployments.
+
+## 1. Google Web Stories Integration
+
+Web Stories are full-screen, tappable visual narratives indexed by Google Discover and Search. They are extremely effective for driving mobile traffic.
+
+### 1.1 Backend: Automated Story Generation
+- **`scripts/generate-web-stories.mjs`:** Create a new build script that iterates through published articles in `teknav-data.js` (or database) and generates static AMP HTML files for each story.
+- **Content Chunking:** Utilize the existing article structure to break content into 4-7 "slides" per article:
+  - Slide 1: Cover (High-res `og:image`, Article Title, Author, "Swipe up to read").
+  - Slide 2-N: Key headings and brief summaries.
+  - Final Slide: "Read the full technical deep-dive on Teknav", with a call-to-action link to the canonical article.
+- **AMP Validation:** The generated HTML must strictly follow the `<html amp>` specification, using valid `<amp-story>` tags and local, non-CDN assets.
+
+### 1.2 Frontend & SEO Artifacts
+- **Sitemap Integration:** Update `scripts/generate-seo.mjs` to include a new `<urlset>` specifically for `/stories/*` in the main `sitemap.xml`.
+- **Article Linkage:** In `generate-article-pages.mjs`, inject `<link rel="amphtml" href="https://www.teknav.ir/stories/:slug">` into the `<head>` of the standard article HTML so Google knows a story version exists.
+- **Local Assets Check:** Ensure all swipe animations and video/image assets used in the stories are served from `/public/images/stories` and bypass external CDNs.
+
+---
+
+## 2. Social Virality & Embeddable Widgets
+
+We want to empower readers to share snippets visually, and allow other websites to easily embed Teknav data.
+
+### 2.1 Auto-Generated Quote Cards
+- **UI Component (`QuoteSharer.jsx`):** A new React component that appears as a tooltip when a user highlights text on an article page (similar to Medium).
+- **Client-Side Rendering (Canvas):** When the user clicks "Share Quote", utilize the native HTML5 `<canvas>` API to draw a branded quote card.
+  - Background: Teknav dark-mode gradient.
+  - Text: The highlighted text in Persian (RTL).
+  - Footer: Teknav logo, Article Title, and a QR code/shortlink.
+- **Export:** The user can instantly download the image (`.png`) or share it directly via the Web Share API.
+
+### 2.2 Embeddable Teknav Widgets
+- **Widget Route (`/embed/*`):** Create a standalone React entry point (`embed.html` -> `embed.jsx`) that strips away the header, footer, and sidebars, leaving only pure data presentation.
+- **Supported Widget Types:**
+  - `/embed/glossary/:slug`: Displays a definition card for a tech term.
+  - `/embed/company/:slug`: Displays a company profile card with verification badges.
+  - `/embed/article-card/:slug`: Displays a mini-preview of an article.
+- **Cross-Origin Configuration:** Update the Nginx configuration (`/etc/nginx/sites-available/teknav`) to explicitly allow `X-Frame-Options` for `/embed/*` paths, while keeping the rest of the site protected against clickjacking.
+- **Branding & Backlinks:** Every widget must contain a non-removable `<a href="https://www.teknav.ir..." target="_blank">` link back to the canonical Teknav page to drive SEO value from embedded domains.
+
+---
+
+## 3. Programmatic SEO & Data Hubs
+
+Leveraging the existing Tech Directory and Glossary models to generate thousands of high-intent search pages.
+
+### 3.1 Comparison Pages Engine ("X vs Y")
+- **Data Model:** Create a mapping system (either in `teknav-data.js` or via a new Prisma `Comparison` model) that pairs similar glossary terms or companies (e.g., "Next.js vs Remix", "PostgreSQL vs MongoDB").
+- **Template (`ComparisonPage.jsx`):** A highly optimized, static layout that dynamically pulls the definitions, pros/cons, and related articles for both entities and displays them side-by-side.
+- **Build Generation (`scripts/generate-comparisons.mjs`):** Loop through all valid comparison pairs and pre-render them to static HTML (`dist/compare/x-vs-y/index.html`) to guarantee instant load times and indexability.
+
+### 3.2 Dynamic "Top Tools" Aggregation
+- **Category Taxonomy:** Ensure `CompanyProfile` entries have strict industry tags (e.g., "AI", "Fintech", "Cloud").
+- **Listicles (`TopicHub.jsx` extension):** Automatically generate programmatic listicle pages based on tags.
+  - Route example: `/directory/category/artificial-intelligence` generating the SEO title: *"Top Persian Artificial Intelligence Startups & Tools"*.
+- **Structured Data:** Inject `ItemList` and `CollectionPage` JSON-LD schemas into these programmatic pages so Google parses them as official rankings/lists in search results.
+
+---
+
+## 4. Execution Order & Verification
+
+1. **Phase 15A:** Write `scripts/generate-web-stories.mjs` and deploy Google Stories to establish a presence in Google Discover.
+2. **Phase 15B:** Build the `/embed/*` routes and Nginx frame allowances, then deploy the Client-Side Quote Card generator.
+3. **Phase 15C:** Extend static generation scripts for programmatic comparison pages and directory listicles.
+4. **Validation:** Run `npm run preflight:prod` and ensure no external CDN scripts crept in (especially critical for AMP valid HTML). Test embed iFrames in a blank local HTML file.

app/Fonts/Vazirmatn/AUTHORS.txt

@@ -0,0 +1,9 @@
+# This is the official list of authors for copyright purposes.
+# This file is distinct from the CONTRIBUTORS files.
+# See the latter for an explanation.
+# 
+# Names should be added to this file as:
+# Name or Organization <email address>
+# The email address is not required for organizations.
+
+Saber Rastikerdar <saber.rastikerdar@gmail.com>

app/Fonts/Vazirmatn/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2015 The Vazirmatn Project Authors (https://github.com/rastikerdar/vazirmatn)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

app/Fonts/Vazirmatn/README.md

@@ -0,0 +1,72 @@
+# FontFa.com
+
+Thank you for downloading the font from the FontFa.com site
+
+All Right Reserved By Fontfa.com
+
+# How to install fonts in Windows
+
+Copy Font files to Addree > C:\Windows\Fonts
+
+
+# Vazirmatn Font فونت وزیرمتن
+
+Vazirmatn is a Persian/Arabic font project that started in 2015 under the name of Vazir with the idea of a new simple and legible typeface suitable for web pages and applications. Design and development have taken a long way but I hope the results are worth it. Thanks to DejaVu Sans font (v2.35) published in public domain there was a free software base to start the Vazir project. Although Vazir was completely different in typeface, still the original software was common. The design is done in Fontforge. For Latin glyphs, Vazirmatn is combined with Roboto font by a build script, however there is also a version without Latin glyphs (Non-Latin). ([More info](https://rastikerdar.github.io/vazirmatn/fa/docs))
+
+- [Website](https://rastikerdar.github.io/vazirmatn)
+- [Docs](https://rastikerdar.github.io/vazirmatn/fa/docs)
+- [Test the font](https://rastikerdar.github.io/vazirmatn/fa/lab)
+
+## Install
+
+### Download
+
+Grab the [latest release](https://github.com/rastikerdar/vazirmatn/releases/latest) zip package.
+
+TTF files are in folder `fonts/ttf`. There is also a rounded dots version in folder `Round-Dots/`.
+
+### [npm](https://www.npmjs.com/package/vazirmatn)
+
+```
+npm install vazirmatn
+```
+or
+```
+yarn add vazirmatn
+```
+
+### CDN
+
+```html
+<link href="https://cdn.jsdelivr.net/gh/rastikerdar/vazirmatn@v33.003/Vazirmatn-font-face.css" rel="stylesheet" type="text/css" />
+```
+
+`*-font-face.css` for other versions are in `misc` and `Round-Dots` folders.
+
+```css
+body {
+    font-family: Vazirmatn, sans-serif;
+}
+```
+
+### Arch Linux ([AUR](https://aur.archlinux.org/packages/vazirmatn-fonts))
+```
+yay -S vazirmatn-fonts
+```
+
+## Build
+
+All weights other than Thin, Regular and Black are generated by interpolation method by [fontmake](https://github.com/googlefonts/fontmake) library. See [README.md](/scripts/README.md) in `scripts/`. All build steps (generating files) are done by scripts.
+
+## Thank you
+
+- [fontforge](https://fontforge.org/)
+- [fontmake](https://github.com/googlefonts/fontmake)
+- [fonttools](https://github.com/fonttools/fonttools)
+- [DejaVu Fonts v2.35](https://dejavu-fonts.github.io) (used for the first version)
+
+## License
+This Font Software is licensed under the SIL Open Font License, Version 1.1. See [OFL.txt](OFL.txt).
+
+## Authors
+See [AUTHORS.txt](AUTHORS.txt).