feat: revamp README.md for enhanced project clarity and user engagement. Introduce a new project description, features list, and supported exams section. Update environment variable examples in .env.example for better developer onboarding. Refactor GeneratePage and job state management to improve user experience with job dismissal functionality. Enhance AI question generation with new language rules and regeneration capabilities, ensuring compliance with exam standards.

README.md

@@ -1,101 +1,283 @@
-# labas
+<p align="center">
+  <img src="./apps/web/public/logo.png" alt="Labas" width="200" />
+</p>
 
-This project was created with [Better-T-Stack](https://github.com/AmanVarshney01/create-better-t-stack), a modern TypeScript stack that combines React, TanStack Router, Hono, TRPC, and more.
+<h1 align="center">Labas</h1>
+
+<p align="center">
+  <strong>AI-powered multi-language test practice platform</strong><br />
+  Generate authentic exam questions, run mock tests, and track your progress — all in one place.
+</p>
+
+<p align="center">
+  <a href="#getting-started">Getting Started</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#supported-exams">Exams</a> ·
+  <a href="#project-structure">Structure</a> ·
+  <a href="#license">License</a>
+</p>
+
+---
+
+## What is Labas?
+
+**Labas** is an open-source platform for practicing foreign-language proficiency exams. Users can generate reading (and writing) questions with AI, save them into question packages, take timed mock tests, and review results with explanations in **Bahasa Indonesia** (foreign script such as kanji, hanzi, hangul, or Arabic may appear when relevant).
+
+The project is a **Turborepo monorepo** managed with **Bun**. The web app talks to a **Hono + tRPC** backend backed by **PostgreSQL**, **Redis** (job queue), and **Better Auth**.
 
 ## Features
 
-- **TypeScript** - For type safety and improved developer experience
-- **TanStack Router** - File-based routing with full type safety
-- **TailwindCSS** - Utility-first CSS for rapid UI development
-- **Shared UI package** - shadcn/ui primitives live in `packages/ui`
-- **Hono** - Lightweight, performant server framework
-- **tRPC** - End-to-end type-safe APIs
-- **Bun** - Runtime environment
-- **Drizzle** - TypeScript-first ORM
-- **PostgreSQL** - Database engine
-- **Authentication** - Better-Auth
-- **PWA** - Progressive Web App support
-- **Turborepo** - Optimized monorepo build system
+- **AI question generation** — Quick mode (single-pass) and Agentic mode (multi-step pipeline with passage validation and quality checks)
+- **8 exam types** — IELTS, TOEFL, JLPT, HSK, Goethe, TOPIK, TOAFL, DELE
+- **20+ question formats** — Multiple choice, true/false/not given, fill-in-blank, kanji reading, matching, and more
+- **Question bank & packages** — Organize generated questions into shareable or private packages
+- **Mock tests & attempts** — Timed practice sessions with scoring and review
+- **Analytics & leaderboard** — Track performance over time
+- **User-managed AI keys** — Bring your own OpenAI-compatible API key via Settings (never hardcoded in server env)
+- **Credit system** — Token-based usage tracking for AI generation
+- **Admin panel** — User management, moderation, jobs, credits, and featured content
+- **PWA** — Installable progressive web app
+- **Accessible UI** — Shared shadcn/ui components with skip links, proper ARIA, and focus management
+
+## Supported Exams
+
+| Exam | Language | Notes |
+|------|----------|-------|
+| IELTS Academic | English | Reading & Writing sections |
+| TOEFL iBT | English | Reading & Writing sections |
+| JLPT | Japanese | Kanji annotations supported (`漢字(かんじ)`) |
+| HSK | Chinese | |
+| Goethe-Zertifikat | German | |
+| TOPIK | Korean | Particles, honorifics, speech levels |
+| TOAFL | Arabic | RTL text support |
+| DELE | Spanish | Verb conjugation focus |
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Runtime & package manager | [Bun](https://bun.sh) 1.3+ |
+| Frontend | React 19, Vite, [TanStack Router](https://tanstack.com/router) |
+| Backend | [Hono](https://hono.dev), [tRPC](https://trpc.io) |
+| Database | PostgreSQL + [Drizzle ORM](https://orm.drizzle.team) |
+| Queue | Redis + BullMQ (AI generation jobs) |
+| Auth | [Better Auth](https://www.better-auth.com) (email/password) |
+| UI | [shadcn/ui](https://ui.shadcn.com) in `packages/ui` |
+| AI | OpenAI-compatible API (`packages/ai`) |
+| Build | Turborepo + tsdown |
+
+## Prerequisites
+
+- **[Bun](https://bun.sh)** `1.3.11` or later (see `packageManager` in root `package.json`)
+- **PostgreSQL** 15+
+- **Redis** 7+ (required for background AI generation jobs)
+- **SMTP server** (required for email verification and password reset)
+
+> Use `bun` for all install and script commands. Do not use `pnpm`, `npm`, or `yarn` unless a global tool explicitly requires it.
 
 ## Getting Started
 
-First, install the dependencies:
+### 1. Clone and install
 
 ```bash
+git clone https://github.com/<your-org>/labas.git
+cd labas
 bun install
 ```
 
-## Database Setup
-
-This project uses PostgreSQL with Drizzle ORM.
-
-1. Make sure you have a PostgreSQL database set up.
-2. Update your `apps/server/.env` file with your PostgreSQL connection details.
+### 2. Start PostgreSQL and Redis
 
-3. Apply the schema to your database:
+The repo includes a Docker Compose file for local development:
 
 ```bash
-bun run db:push
+bun run db:start
 ```
 
-Then, run the development server:
+This starts PostgreSQL on port `5432` and Redis on port `6379`. See [`packages/db/docker-compose.yml`](./packages/db/docker-compose.yml) for defaults.
+
+Alternatively, point `DATABASE_URL` and `REDIS_URL` at your own instances.
+
+### 3. Configure environment
+
+Copy the example env files:
 
 ```bash
-bun run dev
+cp apps/server/.env.example apps/server/.env
+cp apps/web/.env.example apps/web/.env
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser to see the web application.
-The API is running at [http://localhost:3000](http://localhost:3000).
+Edit **`apps/server/.env`**:
 
-## UI Customization
+```env
+# PostgreSQL (matches docker-compose defaults)
+DATABASE_URL=postgresql://postgres:password@localhost:5432/labas
 
-React web apps in this stack share shadcn/ui primitives through `packages/ui`.
+# Redis (defaults to redis://localhost:6379 if omitted)
+REDIS_URL=redis://localhost:6379
 
-- Change design tokens and global styles in `packages/ui/src/styles/globals.css`
-- Update shared primitives in `packages/ui/src/components/*`
-- Adjust shadcn aliases or style config in `packages/ui/components.json` and `apps/web/components.json`
+# Auth — generate random strings ≥ 32 characters
+BETTER_AUTH_SECRET=your-random-secret-at-least-32-chars
+BETTER_AUTH_URL=http://localhost:3000
+CORS_ORIGIN=http://localhost:3001
 
-### Add more shared components
+# Encrypts user AI API keys at rest — ≥ 32 characters
+API_KEY_ENCRYPTION_KEY=your-encryption-key-at-least-32-chars
 
-Run this from the project root to add more primitives to the shared UI package:
+# SMTP (required for sign-up verification & password reset)
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=your-smtp-user
+SMTP_PASS=your-smtp-password
+SMTP_FROM=noreply@example.com
+
+# Optional: platform-wide AI fallback (users normally set keys in Settings UI)
+# PLATFORM_AI_API_KEY=
+# PLATFORM_AI_BASE_URL=
+# PLATFORM_AI_MODEL=
+```
+
+Edit **`apps/web/.env`**:
+
+```env
+VITE_SERVER_URL=http://localhost:3000
+```
+
+### 4. Push database schema
 
 ```bash
-npx shadcn@latest add accordion dialog popover sheet table -c packages/ui
+bun run db:push
 ```
 
-Import shared components like this:
+Optionally seed reference data (exam types, sections):
 
-```tsx
-import { Button } from "@labas/ui/components/button";
+```bash
+cd packages/db && bun run db:seed
 ```
 
-### Add app-specific blocks
+### 5. Run the dev servers
+
+```bash
+bun run dev
+```
+
+| Service | URL |
+|---------|-----|
+| Web app | [http://localhost:3001](http://localhost:3001) |
+| API server | [http://localhost:3000](http://localhost:3000) |
+
+Sign up, verify your email, then open **Settings** to add your OpenAI-compatible API key before generating questions.
+
+## AI Configuration
+
+AI provider keys are **not** stored in server `.env` by default. Each user configures their own key in the **Settings** page. The server encrypts keys with `API_KEY_ENCRYPTION_KEY`.
+
+Generation supports any **OpenAI-compatible** endpoint (OpenAI, OpenRouter, local LM Studio, etc.).
 
-If you want to add app-specific blocks instead of shared primitives, run the shadcn CLI from `apps/web`.
+Two generation modes are available:
+
+| Mode | Description |
+|------|-------------|
+| **Quick** | Single LLM call with schema validation and repair |
+| **Agentic** | Multi-step pipeline: plan → shared passage → parallel question shards → validation |
+
+AI logic lives in [`packages/ai/`](./packages/ai/).
 
 ## Project Structure
 
 ```
 labas/
 ├── apps/
-│   ├── web/         # Frontend application (React + TanStack Router)
-│   └── server/      # Backend API (Hono, TRPC)
+│   ├── web/              # Frontend (React + TanStack Router) — port 3001
+│   └── server/           # Backend entry (Hono + tRPC) — port 3000
 ├── packages/
-│   ├── ui/          # Shared shadcn/ui components and styles
-│   ├── api/         # API layer / business logic
-│   ├── auth/        # Authentication configuration & logic
-│   └── db/          # Database schema & queries
+│   ├── ai/               # Prompts, schemas, quick & agentic pipelines
+│   ├── api/              # tRPC routers, queue workers, business logic
+│   ├── auth/             # Better Auth configuration
+│   ├── config/           # Shared TypeScript configs
+│   ├── db/               # Drizzle schema, migrations, docker-compose
+│   ├── env/              # Environment validation (Zod)
+│   └── ui/               # Shared shadcn/ui components & design tokens
+├── AGENTS.md             # Contributor guide for AI agents & developers
+└── turbo.json
 ```
 
+Internal imports use the `@labas/*` workspace namespace. Apps should not import from each other directly — share code through `packages/*`.
+
 ## Available Scripts
 
-- `bun run dev`: Start all applications in development mode
-- `bun run build`: Build all applications
-- `bun run dev:web`: Start only the web application
-- `bun run dev:server`: Start only the server
-- `bun run check-types`: Check TypeScript types across all apps
-- `bun run db:push`: Push schema changes to database
-- `bun run db:generate`: Generate database client/types
-- `bun run db:migrate`: Run database migrations
-- `bun run db:studio`: Open database studio UI
-- `cd apps/web && bun run generate-pwa-assets`: Generate PWA assets
+Run from the **repository root**:
+
+| Command | Description |
+|---------|-------------|
+| `bun run dev` | Start web + server in development |
+| `bun run dev:web` | Start web app only |
+| `bun run dev:server` | Start server only |
+| `bun run build` | Build all packages |
+| `bun run check-types` | TypeScript check across the monorepo |
+| `bun test` | Run all tests via Turborepo |
+| `bun run db:push` | Push Drizzle schema to PostgreSQL |
+| `bun run db:generate` | Generate migration files |
+| `bun run db:migrate` | Run migrations |
+| `bun run db:studio` | Open Drizzle Studio |
+| `bun run db:start` | Start PostgreSQL + Redis (Docker Compose) |
+| `bun run db:stop` | Stop Docker Compose services |
+
+## Development
+
+### Type checking
+
+```bash
+bun run check-types
+```
+
+### Testing
+
+```bash
+bun test
+```
+
+Tests use **Bun's built-in test runner**. Unit tests live in `src/__tests__/` within each package. Integration tests in `packages/api` use PGlite (in-memory PostgreSQL).
+
+### Adding shadcn/ui components
+
+From the project root:
+
+```bash
+npx shadcn@latest add accordion dialog -c packages/ui
+```
+
+Import shared components:
+
+```tsx
+import { Button } from "@labas/ui/components/button";
+```
+
+Design tokens and global styles: [`packages/ui/src/styles/globals.css`](./packages/ui/src/styles/globals.css).
+
+### PWA assets
+
+```bash
+cd apps/web && bun run generate-pwa-assets
+```
+
+## Contributing
+
+Contributions are welcome! Before opening a PR:
+
+1. Read [`AGENTS.md`](./AGENTS.md) for architecture, conventions, and common pitfalls.
+2. Run `bun run check-types` and `bun test`.
+3. Keep changes focused and match existing code style.
+
+For AI-related changes, see the **AI Generation Context** section in `AGENTS.md` — adding a new question format touches schemas, prompts, attempt normalization, and frontend constants.
+
+## License
+
+This project is licensed under the **[GNU Affero General Public License v3.0 (AGPL-3.0)](./LICENSE)**.
+
+If you run a modified version as a network service, you must make the corresponding source code available to users of that service.
+
+---
+
+<p align="center">
+  Built with Bun, React, Hono, and tRPC.
+</p>

apps/server/.env.example

@@ -1,13 +1,27 @@
+# PostgreSQL connection string
+# Local dev (docker-compose): postgresql://postgres:password@localhost:5432/labas
+DATABASE_URL=
+
+# Redis — required for AI generation job queue
+# Local dev (docker-compose): redis://localhost:6379
+REDIS_URL=redis://localhost:6379
+
+# Auth — random strings, minimum 32 characters
 BETTER_AUTH_SECRET=
 BETTER_AUTH_URL=http://localhost:3000
 CORS_ORIGIN=http://localhost:3001
 
-DATABASE_URL=
-
+# Encrypts user AI API keys at rest — minimum 32 characters
 API_KEY_ENCRYPTION_KEY=
 
+# SMTP — required for email verification and password reset
 SMTP_HOST=
-SMTP_PORT=
+SMTP_PORT=587
 SMTP_USER=
 SMTP_PASS=
-SMTP_FROM=
+SMTP_FROM=
+
+# Optional: platform-wide AI fallback (users normally configure keys in Settings UI)
+# PLATFORM_AI_API_KEY=
+# PLATFORM_AI_BASE_URL=
+# PLATFORM_AI_MODEL=

apps/web/src/components/routes/GeneratePage.tsx

@@ -60,8 +60,8 @@ export function RouteComponent() {
     isGenerating,
     error,
     addJob,
-    removeJob,
     resetAll,
+    dismissResult,
     setError,
   } = useGenerationJobs();
 
@@ -708,7 +708,7 @@ export function RouteComponent() {
                     <span
                       onClick={(e) => {
                         e.stopPropagation();
-                        removeJob(res.jobId);
+                        dismissResult(res.jobId);
                       }}
                       role="button"
                       aria-label={`Tutup tab ${res.mode}`}

apps/web/src/hooks/use-generation-jobs.ts

@@ -26,6 +26,7 @@ export function useGenerationJobs() {
     trackStatus,
     setResult,
     clearResult,
+    dismissResult,
   } = useJobState();
 
   /* Fallback: discover active jobs from myJobs endpoint */
@@ -157,6 +158,7 @@ export function useGenerationJobs() {
     addJob,
     removeJob: wrappedRemoveJob,
     resetAll,
+    dismissResult,
     setError,
     myJobsQuery,
   };

apps/web/src/hooks/use-job-state.ts

@@ -56,6 +56,22 @@ function broadcastJobs(ids: string[]) {
   );
 }
 
+function broadcastResults(results: CompletedResult[]) {
+  window.dispatchEvent(
+    new CustomEvent("labas:results-change", { detail: { results } }),
+  );
+}
+
+function createInitialState(): State {
+  return {
+    jobIds: readStoredIds(),
+    completedResults: readStoredResults(),
+    error: null,
+    processedStates: {},
+    removedIds: new Set(readClearedJobIds()),
+  };
+}
+
 /* ── State shape ── */
 
 interface State {
@@ -72,6 +88,7 @@ type Action =
   | { type: "removeJob"; id: string }
   | { type: "reset" }
   | { type: "syncIds"; ids: string[] }
+  | { type: "syncResults"; results: CompletedResult[] }
   | { type: "trackStatus"; jobId: string; status: string }
   | { type: "setResult"; result: CompletedResult }
   | { type: "clearResult"; jobId: string }
@@ -99,18 +116,15 @@ function reducer(state: State, action: Action): State {
 
     case "removeJob": {
       const nextIds = state.jobIds.filter((j) => j !== action.id);
-      const nextResults = state.completedResults.filter((r) => r.jobId !== action.id);
       const nextRemoved = new Set(state.removedIds).add(action.id);
 
       writeStoredIds(nextIds);
-      writeStoredResults(nextResults);
       const cleared = readClearedJobIds();
       if (!cleared.includes(action.id)) writeClearedJobIds([...cleared, action.id]);
 
       return {
         ...state,
         jobIds: nextIds,
-        completedResults: nextResults,
         removedIds: nextRemoved,
       };
     }
@@ -125,6 +139,7 @@ function reducer(state: State, action: Action): State {
       const nextRemoved = new Set(state.removedIds);
       for (const id of current) nextRemoved.add(id);
 
+      broadcastResults([]);
       return {
         ...state,
         jobIds: [],
@@ -139,6 +154,10 @@ function reducer(state: State, action: Action): State {
       return { ...state, jobIds: action.ids };
     }
 
+    case "syncResults": {
+      return { ...state, completedResults: action.results };
+    }
+
     case "trackStatus": {
       return {
         ...state,
@@ -148,18 +167,25 @@ function reducer(state: State, action: Action): State {
 
     case "setResult": {
       const idx = state.completedResults.findIndex((r) => r.jobId === action.result.jobId);
+      let nextResults: CompletedResult[];
       if (idx >= 0) {
-        const updated = [...state.completedResults];
-        updated[idx] = action.result;
-        return { ...state, completedResults: updated };
+        nextResults = [...state.completedResults];
+        nextResults[idx] = action.result;
+      } else {
+        nextResults = [...state.completedResults, action.result];
       }
-      return { ...state, completedResults: [...state.completedResults, action.result] };
+      writeStoredResults(nextResults);
+      broadcastResults(nextResults);
+      return { ...state, completedResults: nextResults };
     }
 
     case "clearResult": {
+      const nextResults = state.completedResults.filter((r) => r.jobId !== action.jobId);
+      writeStoredResults(nextResults);
+      broadcastResults(nextResults);
       return {
         ...state,
-        completedResults: state.completedResults.filter((r) => r.jobId !== action.jobId),
+        completedResults: nextResults,
       };
     }
 
@@ -175,31 +201,22 @@ function reducer(state: State, action: Action): State {
 /* ── Hook ── */
 
 export function useJobState() {
-  const [state, dispatch] = useReducer(reducer, {
-    jobIds: [],
-    completedResults: [],
-    error: null,
-    processedStates: {},
-    removedIds: new Set<string>(),
-  });
+  const [state, dispatch] = useReducer(reducer, undefined, createInitialState);
+  const skipPersistRef = useRef(true);
 
   const stateRef = useRef(state);
   stateRef.current = state;
 
-  /* Recover from sessionStorage on mount */
-  useEffect(() => {
-    const saved = readStoredIds();
-    const savedResults = readStoredResults();
-    const clearedIds = readClearedJobIds();
-    dispatch({ type: "init", jobIds: saved, results: savedResults, clearedIds });
-  }, []);
-
-  /* Persist completedResults */
+  /* Persist completedResults — skip first run (lazy init already loaded from storage) */
   useEffect(() => {
+    if (skipPersistRef.current) {
+      skipPersistRef.current = false;
+      return;
+    }
     writeStoredResults(state.completedResults);
   }, [state.completedResults]);
 
-  /* Sync across hook instances via custom event */
+  /* Sync job IDs across hook instances */
   useEffect(() => {
     const handler = (e: Event) => {
       const detail = (e as CustomEvent).detail as { ids: string[] };
@@ -209,6 +226,17 @@ export function useJobState() {
     return () => window.removeEventListener("labas:jobs-change", handler);
   }, []);
 
+  /* Sync completed results across hook instances (GeneratePage + GlobalProgress) */
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const detail = (e as CustomEvent).detail as { results: CompletedResult[] };
+      skipPersistRef.current = true;
+      dispatch({ type: "syncResults", results: detail.results });
+    };
+    window.addEventListener("labas:results-change", handler);
+    return () => window.removeEventListener("labas:results-change", handler);
+  }, []);
+
   const addJob = useCallback((id: string) => dispatch({ type: "addJob", id }), []);
   const removeJob = useCallback((id: string) => dispatch({ type: "removeJob", id }), []);
   const resetAll = useCallback(() => dispatch({ type: "reset" }), []);
@@ -225,6 +253,10 @@ export function useJobState() {
     (jobId: string) => dispatch({ type: "clearResult", jobId }),
     [],
   );
+  const dismissResult = useCallback((jobId: string) => {
+    dispatch({ type: "clearResult", jobId });
+    dispatch({ type: "removeJob", id: jobId });
+  }, []);
 
   return {
     jobIds: state.jobIds,
@@ -239,5 +271,6 @@ export function useJobState() {
     trackStatus,
     setResult,
     clearResult,
+    dismissResult,
   };
 }

apps/web/src/hooks/use-polling-transport.ts

@@ -11,9 +11,15 @@ function jobStatusRefetchInterval(query: unknown): number | false {
   return 1000;
 }
 
-/** Track previous active job IDs and per-job statuses to avoid redundant state updates. */
-function serializeJobIds(jobs: ActiveJob[]): string {
-  return jobs.map((j) => j.id).sort().join(",");
+/** Track job snapshots so progress/message/log updates propagate without ID churn. */
+function serializeJobSnapshot(jobs: ActiveJob[]): string {
+  return jobs
+    .map((j) => {
+      const logsLen = Array.isArray(j.logs) ? j.logs.length : 0;
+      return [j.id, j.status, j.progress ?? 0, j.progressMessage ?? "", logsLen].join(":");
+    })
+    .sort()
+    .join("|");
 }
 
 /** Polling-based implementation of JobTransport.
@@ -30,7 +36,7 @@ export function usePollingTransport({
   const onUpdateRef = useRef<(event: JobTransportEvent) => void>(undefined);
   const onErrorRef = useRef<(error: Error) => void>(undefined);
 
-  const prevActiveIdsRef = useRef("");
+  const prevSnapshotRef = useRef("");
   const prevStatusesRef = useRef<Record<string, string>>({});
 
   const jobQueries = useQueries({
@@ -46,9 +52,9 @@ export function usePollingTransport({
       .filter((q) => q.data && !isTerminal((q.data as { status: string }).status))
       .map((q) => q.data as unknown as ActiveJob);
 
-    const nextIds = serializeJobIds(nextActive);
-    if (nextIds !== prevActiveIdsRef.current) {
-      prevActiveIdsRef.current = nextIds;
+    const nextIds = serializeJobSnapshot(nextActive);
+    if (nextIds !== prevSnapshotRef.current) {
+      prevSnapshotRef.current = nextIds;
       setActiveJobs(nextActive);
     }
 

packages/ai/src/__tests__/language-rules.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "bun:test";
+import {
+  getQuestionLanguageErrors,
+  isLikelyIndonesianContent,
+  getTargetLanguage,
+  getExplanationLanguageErrors,
+} from "../language-rules";
+
+describe("language-rules", () => {
+  it("detects Indonesian question text for JLPT", () => {
+    const errors = getQuestionLanguageErrors(
+      {
+        questionText: "Menurut paragraf tersebut, apakah pernyataan berikut benar?",
+        options: [
+          { key: "A", text: "はい、正しいです" },
+          { key: "B", text: "いいえ、違います" },
+        ],
+      },
+      "JLPT",
+    );
+    expect(errors.some((e) => e.includes("questionText"))).toBe(true);
+  });
+
+  it("accepts Japanese question text for JLPT", () => {
+    const errors = getQuestionLanguageErrors(
+      {
+        questionText: "この文章によると、筆者の主張として正しいものはどれか。",
+        options: [
+          { key: "A", text: "環境問題は深刻化している" },
+          { key: "B", text: "経済成長だけが重要だ" },
+        ],
+      },
+      "JLPT",
+    );
+    expect(errors).toHaveLength(0);
+  });
+
+  it("flags Indonesian options", () => {
+    expect(isLikelyIndonesianContent("Pilihan yang benar menurut teks")).toBe(true);
+  });
+
+  it("returns Japanese for JLPT", () => {
+    expect(getTargetLanguage("JLPT")).toBe("Japanese");
+  });
+
+  it("accepts mixed Indonesian + Japanese in explanation", () => {
+    const errors = getExplanationLanguageErrors(
+      "Jawaban A benar karena kata 環境(かんきょう) di paragraf kedua merujuk pada lingkungan hidup.",
+    );
+    expect(errors).toHaveLength(0);
+  });
+
+  it("rejects explanation with only Japanese and no Indonesian prose", () => {
+    const errors = getExplanationLanguageErrors(
+      "この文章によると、正しい答えはAです。",
+    );
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("rejects English-only explanation", () => {
+    const errors = getExplanationLanguageErrors(
+      "The correct answer is A because the passage clearly states the main idea.",
+    );
+    expect(errors.some((e) => e.includes("Bahasa Indonesia"))).toBe(true);
+  });
+});

packages/ai/src/__tests__/repair.test.ts

@@ -3,6 +3,7 @@ import {
   repairQuestion,
   repairAndParseQuestions,
   tryParseQuestion,
+  isGenericOptionText,
 } from "../repair";
 
 const fullPassage = "A".repeat(200);
@@ -18,7 +19,7 @@ const baseRaw = {
     { key: "D", text: "Fourth option" },
   ],
   correctAnswer: "A",
-  explanation: "This is the correct answer because...",
+  explanation: "Jawaban A benar karena pilihan ini sesuai dengan isi teks.",
   difficulty: 3,
   skillTags: ["comprehension"],
 };
@@ -143,16 +144,48 @@ describe("coerceCorrectAnswer — multiple_choice with invalid key", () => {
   });
 });
 
+describe("isGenericOptionText", () => {
+  it("detects common placeholder patterns", () => {
+    expect(isGenericOptionText("Option A")).toBe(true);
+    expect(isGenericOptionText("option b")).toBe(true);
+    expect(isGenericOptionText("Pilihan C")).toBe(true);
+    expect(isGenericOptionText("Placeholder option")).toBe(true);
+    expect(isGenericOptionText("")).toBe(true);
+  });
+
+  it("accepts real answer text", () => {
+    expect(isGenericOptionText("The author argues for renewable energy")).toBe(false);
+    expect(isGenericOptionText("Pada paragraf kedua")).toBe(false);
+  });
+});
+
 describe("ensureOptions", () => {
-  it("injects placeholder options when missing for multiple_choice", () => {
+  it("rejects missing options via repairAndParseQuestions instead of injecting placeholders", () => {
     const raw = {
       ...baseRaw,
       format: "multiple_choice",
       options: [],
     };
-    const { question, wasRepaired } = repairQuestion(raw, fullPassage);
-    expect(question.options).toHaveLength(4);
-    expect(wasRepaired).toBe(true);
+    const result = repairAndParseQuestions([raw], fullPassage);
+    expect(result.valid).toHaveLength(0);
+    expect(result.invalid).toHaveLength(1);
+    expect(result.invalid[0]!.errors.some((e) => e.includes("options missing"))).toBe(true);
+  });
+
+  it("rejects model-provided generic option text", () => {
+    const raw = {
+      ...baseRaw,
+      options: [
+        { key: "A", text: "Option A" },
+        { key: "B", text: "Option B" },
+        { key: "C", text: "Option C" },
+        { key: "D", text: "Option D" },
+      ],
+    };
+    const result = repairAndParseQuestions([raw], fullPassage);
+    expect(result.valid).toHaveLength(0);
+    expect(result.invalid).toHaveLength(1);
+    expect(result.invalid[0]!.errors.some((e) => e.includes("generic placeholder"))).toBe(true);
   });
 
   it("deduplicates options by key", () => {
@@ -177,14 +210,14 @@ describe("repairAndParseQuestions", () => {
     expect(result.invalid).toHaveLength(0);
   });
 
-  it("repairs and processes mixed valid/invalid questions", () => {
+  it("repairs valid questions and rejects structurally incomplete ones", () => {
     const raw = [
       baseRaw,
       { format: "multiple_choice", passageText: "", questionText: "", correctAnswer: "", explanation: "", difficulty: 99, skillTags: [] },
     ];
     const result = repairAndParseQuestions(raw, fullPassage);
-    expect(result.valid).toHaveLength(2);
-    expect(result.invalid).toHaveLength(0);
+    expect(result.valid).toHaveLength(1);
+    expect(result.invalid).toHaveLength(1);
     expect(result.repairLog.length).toBeGreaterThan(0);
   });
 

packages/ai/src/agentic.ts

@@ -9,6 +9,13 @@ import {
   getGenericQuestionJsonSchemaDescription,
   repairAndParseQuestions,
 } from "./repair";
+import { regenerateQuestions, buildRegenerationContext } from "./regenerate-questions";
+import { OPTION_QUALITY_RULES } from "./prompts";
+import {
+  getTargetLanguage,
+  buildContentLanguageRules,
+  buildExplanationLanguageRule,
+} from "./language-rules";
 import { type GenerationInput, type GenerationResult } from "./schemas";
 
 interface AgenticStep {
@@ -34,15 +41,7 @@ function getSystemPrompt(): string {
   return "You are a precise exam question generator. You always return valid JSON. You never include markdown formatting around the JSON.";
 }
 
-function getTargetLanguage(examType: string): string {
-  if (examType === "JLPT") return "Japanese";
-  if (examType === "HSK") return "Chinese";
-  if (examType === "GOETHE") return "German";
-  if (examType === "TOPIK") return "Korean";
-  if (examType === "TOAFL") return "Arabic";
-  if (examType === "DELE") return "Spanish";
-  return "English";
-}
+export { getTargetLanguage };
 
 /** Estimate max tokens needed per step to avoid truncation. */
 function calculateMaxTokens(
@@ -196,7 +195,9 @@ Rules:
 - Questions should test real comprehension, not surface recall
 - For multiple choice: always provide 4 options (A, B, C, D) with one clearly correct answer
 - Options must be plausible distractors
-- explanation — WAJIB ditulis dalam Bahasa Indonesia. DILARANG menggunakan bahasa asing.
+${OPTION_QUALITY_RULES}
+${buildContentLanguageRules(input.examType)}
+${buildExplanationLanguageRule(input.examType)}
 - For true_false_not_given: correctAnswer must be exactly TRUE, FALSE, or NOT_GIVEN (uppercase)
 - For author_view: correctAnswer must be exactly YES, NO, or NOT_GIVEN (uppercase)
 - For matching_pairs: options are {key, text} pairs. correctAnswer is serialized mapping like "A:1,B:2".
@@ -232,15 +233,32 @@ Return ONLY valid JSON conforming to this schema.`;
   };
 }
 
+function formatQuestionForValidation(q: Record<string, unknown>, index: number): string {
+  const lines = [`Q${index + 1}: ${q.questionText}`];
+  if (Array.isArray(q.options) && q.options.length > 0) {
+    const optionLines = q.options
+      .map((o) => {
+        const opt = o as Record<string, unknown>;
+        const key = opt.key ?? opt.left ?? "?";
+        const text = opt.text ?? opt.right ?? "";
+        return `  ${key}: ${text}`;
+      })
+      .join("\n");
+    lines.push(`Options:\n${optionLines}`);
+  }
+  lines.push(`Claimed answer: ${q.correctAnswer}`);
+  return lines.join("\n");
+}
+
 async function step4SelfValidate(
   client: OpenAICompatibleClient,
   input: GenerationInput,
   passage: string,
   questions: Array<Record<string, unknown>>,
   onToken?: (token: string) => void,
-): Promise<{ confidence: number; issues: any[]; tokensUsed: number }> {
+): Promise<{ confidence: number; issues: unknown[]; tokensUsed: number }> {
   const qaPairs = questions
-    .map((q, i) => `Q${i + 1}: ${q.questionText}\nA: ${q.correctAnswer}`)
+    .map((q, i) => formatQuestionForValidation(q, i))
     .join("\n\n");
 
   const schema = getSelfValidationJsonSchemaDescription();
@@ -258,6 +276,7 @@ For each question, verify:
 1. Is the claimed answer truly correct based on the passage?
 2. Are there any ambiguous questions?
 3. Are distractors plausible but clearly wrong?
+4. Are all option texts meaningful (not generic placeholders like "Option A")?
 
 Return ONLY valid JSON conforming to this schema:
 ${schema}`;
@@ -283,69 +302,21 @@ ${schema}`;
   return { confidence, issues, tokensUsed: result.usage?.total_tokens ?? 0 };
 }
 
-async function stepRegenerateQuestions(
-  client: OpenAICompatibleClient,
+export async function generatePassageForInput(
   input: GenerationInput,
-  passage: string,
-  count: number,
-  context: string,
   onToken?: (token: string) => void,
-): Promise<{ questions: Array<Record<string, unknown>>; tokensUsed: number }> {
-  const schema = getGenericQuestionJsonSchemaDescription();
-
-  const prompt = `You are an expert exam question writer. ${context}
-
-Passage:
-"""
-${passage}
-"""
-
-Generate ${count} new reading comprehension questions for ${input.examType} exam.
-Formats: ${input.formats.join(", ")}
-Difficulty: ${input.difficulty}/5
-
-Rules:
-- Each question must be directly answerable from the passage
-- Use "passageText" field with relevant excerpt (or full passage)
-- For multiple choice: provide 4 options (A, B, C, D)
-- explanation — WAJIB ditulis dalam Bahasa Indonesia. DILARANG menggunakan bahasa asing.
-- For true_false_not_given: correctAnswer must be TRUE, FALSE, or NOT_GIVEN (uppercase)
-- For author_view: correctAnswer must be YES, NO, or NOT_GIVEN (uppercase)
-- For matching_pairs: options are {key, text} pairs. correctAnswer is serialized mapping.
-- For error_recognition: options are error segments. correctAnswer is key of segment with error.
-- For text_insertion: options are position markers. correctAnswer is best position key.
-
-Question schema:
-${schema}
-
-Return ONLY valid JSON conforming to this schema.`;
-
-  const result = await client.chatCompletion(
-    {
-      model: input.apiKeyConfig.model,
-      messages: [
-        { role: "system", content: getSystemPrompt() },
-        { role: "user", content: prompt },
-      ],
-      temperature: 0.7,
-      max_tokens: calculateMaxTokens(input.apiKeyConfig.maxTokens, "regenerate", count),
-      response_format: { type: "json_object" },
-    },
-    onToken ? { onToken } : undefined,
+): Promise<{ passage: string; title: string; tokensUsed: number }> {
+  const client = new OpenAICompatibleClient(
+    input.apiKeyConfig.baseUrl,
+    input.apiKeyConfig.apiKey,
   );
-
-  const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
-  if (!Array.isArray(parsed.questions)) {
-    throw new Error("Missing questions array in regeneration response");
-  }
-  return {
-    questions: parsed.questions as Array<Record<string, unknown>>,
-    tokensUsed: result.usage?.total_tokens ?? 0,
-  };
+  return step1GeneratePassage(client, input, onToken);
 }
 
-export async function generateQuestionsAgentic(
+/** Generate + validate questions from an existing passage (skips passage generation). */
+export async function generateQuestionsAgenticFromPassage(
   input: GenerationInput,
+  passage: string,
   onProgress?: (progress: AgenticProgress) => void,
   onToken?: (token: string) => void,
   options?: AgenticGenerationOptions,
@@ -359,9 +330,9 @@ export async function generateQuestionsAgentic(
   );
 
   const steps: [AgenticStep, AgenticStep, AgenticStep, AgenticStep] = [
-    { step: "generate_passage", status: "running" },
-    { step: "validate_passage", status: "pending" as any },
-    { step: "generate_questions", status: "pending" as any },
+    { step: "generate_passage", status: "done", message: "Using shared passage" },
+    { step: "validate_passage", status: "done", message: "Skipped (shared passage)" },
+    { step: "generate_questions", status: "running" },
     { step: "self_validate", status: "pending" as any },
   ];
 
@@ -375,64 +346,63 @@ export async function generateQuestionsAgentic(
   };
 
   let accumulatedTokens = 0;
+  return runAgenticQuestionPipeline({
+    client,
+    input,
+    passage,
+    steps,
+    report,
+    strategy,
+    maxRegenAttempts,
+    onToken,
+    start,
+    accumulatedTokens,
+  });
+}
 
-  // ── Step 1: Generate passage ────────────────────────────
-  report(0);
-  let passage: string;
-  let title: string;
-  try {
-    const s1 = await step1GeneratePassage(client, input, onToken);
-    passage = s1.passage;
-    title = s1.title;
-    accumulatedTokens += s1.tokensUsed;
-    steps[0].status = "done";
-    steps[0].message = `Generated: ${title}`;
-    steps[0].output = passage;
-  } catch (err: any) {
-    steps[0].status = "error";
-    steps[0].message = err.message ?? "Passage generation failed";
-    throw new GenerationError(`Step 1 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
-  }
-
-  // ── Step 2: Validate passage ────────────────────────────
-  if (strategy === "full") {
-    steps[1].status = "running";
-    report(1);
-    try {
-      const s2 = await step2ValidatePassage(client, input, passage, onToken);
-      accumulatedTokens += s2.tokensUsed;
-      steps[1].status = s2.isValid ? "done" : "error";
-      steps[1].message = s2.feedback;
-      steps[1].output = JSON.stringify({ isValid: s2.isValid, feedback: s2.feedback }, null, 2);
-    } catch (err: any) {
-      steps[1].status = "error";
-      steps[1].message = err.message ?? "Passage validation failed";
-      throw new GenerationError(`Step 2 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
-    }
-  } else {
-    steps[1].status = "done";
-    steps[1].message = "Skipped in lean strategy";
-    report(1, steps[1].message);
-  }
-
-  // ── Step 3: Generate questions ──────────────────────────
-  steps[2].status = "running";
+async function runAgenticQuestionPipeline(ctx: {
+  client: OpenAICompatibleClient;
+  input: GenerationInput;
+  passage: string;
+  steps: [AgenticStep, AgenticStep, AgenticStep, AgenticStep];
+  report: (current: number, extraMsg?: string) => void;
+  strategy: AgenticGenerationStrategy;
+  maxRegenAttempts: number;
+  onToken?: (token: string) => void;
+  start: number;
+  accumulatedTokens: number;
+}): Promise<GenerationResult> {
+  const {
+    client,
+    input,
+    passage,
+    steps,
+    report,
+    strategy,
+    maxRegenAttempts,
+    onToken,
+    start,
+  } = ctx;
+  let accumulatedTokens = ctx.accumulatedTokens;
+
+  steps[2]!.status = "running";
   report(2, `Generating ${input.questionCount} questions...`);
   let rawQuestions: Array<Record<string, unknown>>;
   try {
     const s3 = await step3GenerateQuestions(client, input, passage, input.questionCount, onToken);
     rawQuestions = s3.questions;
     accumulatedTokens += s3.tokensUsed;
-    steps[2].message = `Generated ${rawQuestions.length} questions`;
-    steps[2].output = rawQuestions.map((q, i) => `${i + 1}. [${q.format}] ${q.questionText}`).join("\n");
+    steps[2]!.status = "done";
+    steps[2]!.message = `Generated ${rawQuestions.length} questions`;
+    steps[2]!.output = rawQuestions.map((q, i) => `${i + 1}. [${q.format}] ${q.questionText}`).join("\n");
+    report(2);
   } catch (err: any) {
-    steps[2].status = "error";
-    steps[2].message = err.message ?? "Question generation failed";
+    steps[2]!.status = "error";
+    steps[2]!.message = err.message ?? "Question generation failed";
     throw new GenerationError(`Step 3 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
   }
 
-  // ── Step 4: Self-validate + Repair + Regenerate loop ─────
-  steps[3].status = "running";
+  steps[3]!.status = "running";
   report(3, "Validating & repairing questions...");
 
   let validQuestions: any[] = [];
@@ -446,98 +416,80 @@ export async function generateQuestionsAgentic(
       selfValidationConfidence = s4.confidence;
     }
 
-    // Repair & parse
-    let { valid, invalid, repairLog } = repairAndParseQuestions(rawQuestions, passage);
-
-    // Move questions with non-Indonesian (CJK) explanations to invalid for regeneration
-    const hasCJK = (text: string) => /[\u4E00-\u9FFF\u3400-\u4DBF\u3040-\u309F\u30A0-\u30FF\uAC00-\uD7AF]/.test(text);
-    const cjkInvalid: Array<{ index: number; raw: unknown; errors: string[] }> = [];
-    const filteredValid: typeof valid = [];
-    for (let vi = 0; vi < valid.length; vi++) {
-      const q = valid[vi];
-      if (!q) continue;
-      if (q.explanation && hasCJK(q.explanation)) {
-        cjkInvalid.push({
-          index: vi,
-          raw: q,
-          errors: ["explanation contains CJK characters (should be Bahasa Indonesia)"],
-        });
-        repairLog.push(`Q${vi + 1}: explanation contains CJK characters, moved to regeneration queue`);
-      } else {
-        filteredValid.push(q);
-      }
-    }
-    validQuestions = filteredValid;
-    invalid = [...invalid, ...cjkInvalid];
+    let { valid, invalid, repairLog } = repairAndParseQuestions(rawQuestions, passage, {
+      examType: input.examType,
+    });
+
+    validQuestions = valid;
+    invalid = [...invalid];
     allRepairLogs.push(...repairLog);
 
-    // Regenerate structural-invalid questions with bounded attempts
     let regenerationAttempts = 0;
 
     while (invalid.length > 0 && regenerationAttempts < maxRegenAttempts && validQuestions.length < input.questionCount) {
       regenerationAttempts++;
       const regenCount = Math.min(invalid.length, input.questionCount - validQuestions.length);
-      const context = `The previous ${regenCount} question(s) had structural errors: ${invalid.map((i) => `Q${i.index + 1}: ${i.errors.join(", ")}`).join("; ")}.`;
+      const context = buildRegenerationContext(invalid.slice(0, regenCount));
 
       report(3, `Regenerating ${regenCount} invalid question(s) (attempt ${regenerationAttempts}/${maxRegenAttempts})...`);
 
-      const regen = await stepRegenerateQuestions(client, input, passage, regenCount, context, onToken);
+      const regen = await regenerateQuestions(client, input, passage, regenCount, context, onToken);
       accumulatedTokens += regen.tokensUsed;
 
-      const regenResult = repairAndParseQuestions(regen.questions, passage);
+      const regenResult = repairAndParseQuestions(regen.questions, passage, {
+        examType: input.examType,
+      });
       validQuestions.push(...regenResult.valid);
       allRepairLogs.push(...regenResult.repairLog.map((l) => `[Regen ${regenerationAttempts}] ${l}`));
 
-      // If regeneration produced valid questions, remove corresponding invalid entries
       if (regenResult.valid.length > 0) {
         invalid = invalid.slice(regenResult.valid.length);
       } else {
-        // No progress — break to avoid infinite loop
         break;
       }
     }
 
-    // If still below target, generate additional questions
     if (validQuestions.length < input.questionCount) {
       const needMore = input.questionCount - validQuestions.length;
       report(3, `Generating ${needMore} additional question(s)...`);
-      const extra = await stepRegenerateQuestions(
+      const extra = await regenerateQuestions(
         client, input, passage, needMore,
         `Need ${needMore} more valid questions to reach target of ${input.questionCount}.`,
         onToken,
       );
       accumulatedTokens += extra.tokensUsed;
-      const extraResult = repairAndParseQuestions(extra.questions, passage);
+      const extraResult = repairAndParseQuestions(extra.questions, passage, {
+        examType: input.examType,
+      });
       validQuestions.push(...extraResult.valid);
       allRepairLogs.push(...extraResult.repairLog.map((l) => `[Extra] ${l}`));
     }
 
-    steps[3].status = "done";
-    steps[3].message =
+    steps[3]!.status = "done";
+    steps[3]!.message =
       strategy === "full"
         ? `Validated ${validQuestions.length}/${input.questionCount} questions. Confidence: ${selfValidationConfidence}%`
         : `Lean validation completed: ${validQuestions.length}/${input.questionCount} valid`;
-    steps[3].output = [
+    steps[3]!.output = [
       `Strategy: ${strategy}`,
       ...(strategy === "full" ? [`Overall Confidence: ${selfValidationConfidence}%`] : []),
       `Valid Questions: ${validQuestions.length}/${input.questionCount}`,
       `Repair Log:`,
       ...allRepairLogs,
     ].join("\n");
+    report(3);
   } catch (err: any) {
-    steps[3].status = "error";
-    steps[3].message = err.message ?? "Self-validation failed";
+    steps[3]!.status = "error";
+    steps[3]!.message = err.message ?? "Self-validation failed";
     throw new GenerationError(`Step 4 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
   }
 
-  // ── Final check ─────────────────────────────────────────
   if (validQuestions.length === 0) {
     throw new GenerationError("No valid questions generated after agentic validation", {
       tokensUsed: accumulatedTokens,
     });
   }
 
-  // Trim to requested count (if we overshot)
   const finalQuestions = validQuestions.slice(0, input.questionCount);
 
   return {
@@ -550,3 +502,90 @@ export async function generateQuestionsAgentic(
     },
   };
 }
+
+export async function generateQuestionsAgentic(
+  input: GenerationInput,
+  onProgress?: (progress: AgenticProgress) => void,
+  onToken?: (token: string) => void,
+  options?: AgenticGenerationOptions,
+): Promise<GenerationResult> {
+  const start = Date.now();
+  const strategy = options?.strategy ?? "full";
+  const maxRegenAttempts = Math.max(0, options?.maxRegenerateAttempts ?? (strategy === "lean" ? 1 : 2));
+  const client = new OpenAICompatibleClient(
+    input.apiKeyConfig.baseUrl,
+    input.apiKeyConfig.apiKey,
+  );
+
+  const steps: [AgenticStep, AgenticStep, AgenticStep, AgenticStep] = [
+    { step: "generate_passage", status: "running" },
+    { step: "validate_passage", status: "pending" as any },
+    { step: "generate_questions", status: "pending" as any },
+    { step: "self_validate", status: "pending" as any },
+  ];
+
+  const report = (current: number, extraMsg?: string) => {
+    if (extraMsg && steps[current]) {
+      steps[current]!.message = extraMsg;
+    }
+    if (onProgress) {
+      onProgress({ steps, currentStep: current });
+    }
+  };
+
+  let accumulatedTokens = 0;
+
+  // ── Step 1: Generate passage ────────────────────────────
+  report(0);
+  let passage: string;
+  let title: string;
+  try {
+    const s1 = await step1GeneratePassage(client, input, onToken);
+    passage = s1.passage;
+    title = s1.title;
+    accumulatedTokens += s1.tokensUsed;
+    steps[0].status = "done";
+    steps[0].message = `Generated: ${title}`;
+    steps[0].output = passage;
+    report(0);
+  } catch (err: any) {
+    steps[0].status = "error";
+    steps[0].message = err.message ?? "Passage generation failed";
+    throw new GenerationError(`Step 1 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
+  }
+
+  // ── Step 2: Validate passage ────────────────────────────
+  if (strategy === "full") {
+    steps[1].status = "running";
+    report(1);
+    try {
+      const s2 = await step2ValidatePassage(client, input, passage, onToken);
+      accumulatedTokens += s2.tokensUsed;
+      steps[1].status = s2.isValid ? "done" : "error";
+      steps[1].message = s2.feedback;
+      steps[1].output = JSON.stringify({ isValid: s2.isValid, feedback: s2.feedback }, null, 2);
+      report(1);
+    } catch (err: any) {
+      steps[1].status = "error";
+      steps[1].message = err.message ?? "Passage validation failed";
+      throw new GenerationError(`Step 2 failed: ${err.message}`, { tokensUsed: accumulatedTokens });
+    }
+  } else {
+    steps[1].status = "done";
+    steps[1].message = "Skipped in lean strategy";
+    report(1, steps[1].message);
+  }
+
+  return runAgenticQuestionPipeline({
+    client,
+    input,
+    passage,
+    steps,
+    report,
+    strategy,
+    maxRegenAttempts,
+    onToken,
+    start,
+    accumulatedTokens,
+  });
+}

packages/ai/src/index.ts

@@ -1,6 +1,7 @@
 export { OpenAICompatibleClient } from "./client";
 export { generateQuestionsQuick } from "./pipeline";
-export { generateQuestionsAgentic } from "./agentic";
+export { generateQuestionsAgentic, generatePassageForInput, generateQuestionsAgenticFromPassage } from "./agentic";
+export { getTargetLanguage, buildContentLanguageRules } from "./language-rules";
 export type {
   AgenticProgress,
   AgenticGenerationOptions,

packages/ai/src/language-rules.ts

@@ -0,0 +1,124 @@
+interface QuestionLanguageFields {
+  questionText: string;
+  options?: Array<{ key: string; text: string }>;
+}
+
+/** Target language for exam content (passage, question, options). */
+export function getTargetLanguage(examType: string): string {
+  if (examType === "JLPT") return "Japanese";
+  if (examType === "HSK") return "Chinese";
+  if (examType === "GOETHE") return "German";
+  if (examType === "TOPIK") return "Korean";
+  if (examType === "TOAFL") return "Arabic";
+  if (examType === "DELE") return "Spanish";
+  return "English";
+}
+
+const EXAMS_REQUIRING_NON_LATIN_SCRIPT = new Set(["JLPT", "HSK", "TOPIK"]);
+
+const INDONESIAN_PROSE_MARKERS =
+  /\b(yang|dari|pada|Apakah|Menurut|paragraf|bacaan|teks|judul|penulis|artikel|soal|pilihan|jawaban|berikut|manakah|bagian|kalimat|isinya|topik|gagasan|benar|karena|merujuk|sesuai|artinya|makna|kata|terdapat|disebutkan|dijelaskan|adalah|jadi|oleh|opsi|pilihan|jawabannya|penjelasan)\b/i;
+
+/** Strip exam-script characters to analyze Indonesian prose separately. */
+export function stripExamScriptForAnalysis(text: string): string {
+  return text
+    .replace(/[\u4E00-\u9FFF\u3400-\u4DBF\u3040-\u309F\u30A0-\u30FF\uAC00-\uD7AF\u0600-\u06FF]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Latin prose looks like Bahasa Indonesia (not English-only or empty). */
+export function hasIndonesianProse(text: string): boolean {
+  const t = text.trim();
+  if (!t) return false;
+  if (INDONESIAN_PROSE_MARKERS.test(t)) return true;
+  if (/^(The|This|That|According|Because|Therefore|Option|Answer|It is|In the)\b/i.test(t)) {
+    return false;
+  }
+  return t.length >= 15;
+}
+
+export function hasCJKScript(text: string): boolean {
+  return /[\u4E00-\u9FFF\u3400-\u4DBF\u3040-\u309F\u30A0-\u30FF\uAC00-\uD7AF]/.test(text);
+}
+
+export function hasArabicScript(text: string): boolean {
+  return /[\u0600-\u06FF]/.test(text);
+}
+
+function hasTargetScript(text: string, examType: string): boolean {
+  if (examType === "TOAFL") return hasArabicScript(text);
+  if (EXAMS_REQUIRING_NON_LATIN_SCRIPT.has(examType)) return hasCJKScript(text);
+  return true;
+}
+
+/** Heuristic: Latin text that looks like Indonesian exam instructions, not English. */
+export function isLikelyIndonesianContent(text: string): boolean {
+  const t = text.trim();
+  if (!t) return false;
+  if (hasCJKScript(t) || hasArabicScript(t)) return false;
+  return INDONESIAN_PROSE_MARKERS.test(t);
+}
+
+export function buildContentLanguageRules(examType: string): string {
+  const target = getTargetLanguage(examType);
+  return `- LANGUAGE RULE (critical):
+  * passageText, questionText, and every option "text" MUST be written in ${target} — the authentic exam language.
+  * NEVER write questionText or options in Bahasa Indonesia for ${examType}.
+  * explanation: tulis dalam Bahasa Indonesia; boleh sisipkan istilah/kanji/kata ${target} bila perlu (mis. 「環境」 atau kutipan singkat dari teks).`;
+}
+
+export function buildExplanationLanguageRule(examType?: string): string {
+  const target = examType ? getTargetLanguage(examType) : "bahasa ujian";
+  return `- explanation — WAJIB ditulis dalam Bahasa Indonesia sebagai penjelasan utama. Boleh menyertakan istilah, kanji, atau kutipan singkat dalam ${target} jika relevan (mis. arti kanji, padanan kata). Jangan tulis seluruh explanation hanya dalam ${target} atau Inggris.`;
+}
+
+export function getQuestionLanguageErrors(
+  q: QuestionLanguageFields,
+  examType: string,
+): string[] {
+  const errors: string[] = [];
+  const target = getTargetLanguage(examType);
+
+  if (isLikelyIndonesianContent(q.questionText)) {
+    errors.push(`questionText must be ${target}, not Bahasa Indonesia`);
+  }
+
+  if (EXAMS_REQUIRING_NON_LATIN_SCRIPT.has(examType) && !hasTargetScript(q.questionText, examType)) {
+    errors.push(`questionText must be written in ${target}`);
+  }
+
+  if (examType === "IELTS" || examType === "TOEFL") {
+    if (isLikelyIndonesianContent(q.questionText)) {
+      errors.push("questionText must be English for IELTS/TOEFL");
+    }
+  }
+
+  for (const opt of q.options ?? []) {
+    if (isLikelyIndonesianContent(opt.text)) {
+      errors.push(`option ${opt.key} must be ${target}, not Bahasa Indonesia`);
+    }
+    if (EXAMS_REQUIRING_NON_LATIN_SCRIPT.has(examType) && !hasTargetScript(opt.text, examType)) {
+      errors.push(`option ${opt.key} must be written in ${target}`);
+    }
+  }
+
+  return errors;
+}
+
+export function getExplanationLanguageErrors(explanation: string): string[] {
+  const t = explanation.trim();
+  if (!t) return [];
+
+  const latinPart = stripExamScriptForAnalysis(t);
+
+  if (latinPart.length === 0) {
+    return ["explanation must include Bahasa Indonesia prose, not only foreign script"];
+  }
+
+  if (!hasIndonesianProse(latinPart)) {
+    return ["explanation prose must be in Bahasa Indonesia"];
+  }
+
+  return [];
+}

packages/ai/src/pipeline.ts

@@ -2,11 +2,14 @@ import { OpenAICompatibleClient } from "./client";
 import { GenerationError } from "./errors";
 import { buildQuickModePrompt } from "./prompts";
 import { repairAndParseQuestions } from "./repair";
+import { regenerateQuestions, buildRegenerationContext } from "./regenerate-questions";
 import {
   type GenerationInput,
   type GenerationResult,
 } from "./schemas";
 
+const MAX_QUICK_REGEN_ATTEMPTS = 2;
+
 export interface QuickModeCallbacks {
   onToken?: (token: string) => void;
 }
@@ -115,36 +118,69 @@ export async function generateQuestionsQuick(
   ) as any;
   const fallbackPassage = firstWithPassage?.passageText ?? "No passage available.";
 
-  const { valid, invalid, repairLog } = repairAndParseQuestions(raw.questions, fallbackPassage);
+  let { valid: validQuestions, invalid: pendingInvalid, repairLog } = repairAndParseQuestions(
+    raw.questions,
+    fallbackPassage,
+    { examType: input.examType },
+  );
+
+  let accumulatedTokens = tokensUsed ?? 0;
+
+  for (let attempt = 0; attempt < MAX_QUICK_REGEN_ATTEMPTS && pendingInvalid.length > 0; attempt++) {
+    log("warn", "Regenerating invalid questions in quick mode", {
+      attempt: attempt + 1,
+      count: pendingInvalid.length,
+    });
+
+    const context = buildRegenerationContext(pendingInvalid);
+    const regen = await regenerateQuestions(
+      client,
+      input,
+      fallbackPassage,
+      pendingInvalid.length,
+      context,
+      callbacks?.onToken,
+    );
+    accumulatedTokens += regen.tokensUsed ?? 0;
+
+    const regenResult = repairAndParseQuestions(regen.questions, fallbackPassage, {
+      examType: input.examType,
+    });
+    validQuestions = [...validQuestions, ...regenResult.valid];
+    pendingInvalid = regenResult.invalid;
+    if (regenResult.repairLog.length > 0) {
+      repairLog = [...repairLog, ...regenResult.repairLog.map((l) => `[Regen ${attempt + 1}] ${l}`)];
+    }
+  }
 
   if (repairLog.length > 0) {
     log("warn", "Repairs applied", { count: repairLog.length, details: repairLog });
   }
-  if (invalid.length > 0) {
-    log("warn", "Invalid questions after repair", {
-      count: invalid.length,
-      details: invalid.map((i) => ({ index: i.index, errors: i.errors })),
+  if (pendingInvalid.length > 0) {
+    log("warn", "Invalid questions after repair and regeneration", {
+      count: pendingInvalid.length,
+      details: pendingInvalid.map((i) => ({ index: i.index, errors: i.errors })),
     });
   }
 
-  if (valid.length === 0) {
+  if (validQuestions.length === 0) {
     log("error", "No valid questions after repair", { rawCount: raw.questions.length });
-    throw new GenerationError("No valid questions generated", { tokensUsed });
+    throw new GenerationError("No valid questions generated", { tokensUsed: accumulatedTokens });
   }
 
   log("info", "Quick mode generation completed", {
-    validCount: valid.length,
+    validCount: validQuestions.length,
     rawCount: raw.questions.length,
     durationMs: Date.now() - start,
   });
 
-  const questions = valid;
+  const questions = validQuestions;
 
   return {
     questions,
     meta: {
       model: input.apiKeyConfig.model,
-      tokensUsed,
+      tokensUsed: accumulatedTokens,
       durationMs: Date.now() - start,
       mode: "quick",
     },

packages/ai/src/prompts.ts

@@ -1,5 +1,9 @@
 import type { GenerationInput } from "./schemas";
 import { getQuestionJsonSchemaDescription } from "./schema-to-prompt";
+import { buildContentLanguageRules, buildExplanationLanguageRule } from "./language-rules";
+
+export const OPTION_QUALITY_RULES = `- Each option "text" must be meaningful content derived from the passage or question — NEVER use generic labels like "Option A", "Option B", "Pilihan A", "Choice B", or "Placeholder".
+- For multiple choice: always provide at least 4 real answer choices labeled A, B, C, D with plausible distractors.`;
 
 export function buildQuickModePrompt(input: GenerationInput): string {
   const { examType, section, formats, difficulty, topics, questionCount } = input;
@@ -17,22 +21,24 @@ TOPICS: ${topics.join(", ")}
 FORMATS TO GENERATE: ${formats.join(", ")}
 
 INSTRUCTIONS:
-- The reading passage must be written in the target language of the exam (${examType === "JLPT" ? "Japanese" : examType === "HSK" ? "Chinese" : examType === "GOETHE" ? "German" : examType === "TOPIK" ? "Korean" : examType === "TOAFL" ? "Arabic" : examType === "DELE" ? "Spanish" : "English"}).
+${buildContentLanguageRules(examType)}
+${buildExplanationLanguageRule(examType)}
 - For Korean (TOPIK): Focus on particles, honorifics (speech levels), and functional grammar.
 - For Arabic (TOAFL): Support RTL text. Focus on I'rab (case endings/vowel changes) and grammar.
 - For Spanish (DELE): Focus on verb conjugation by subject and agreement.
-- For JLPT/TOPIK kanji/hanja: Include reading annotations in format: 漢字(かんじ) for words that have readings.
 - Passage length should be appropriate for the exam type and difficulty.
 - Each question must have:
   * a reading passage (passageText)
-   * a clear question prompt (questionText)
+   * a clear question prompt (questionText) — in exam language, NOT Bahasa Indonesia
    * a correct answer (correctAnswer)
-   * an explanation (explanation) — WAJIB ditulis dalam Bahasa Indonesia. DILARANG menggunakan bahasa asing (China, Jepang, Jerman, Inggris) untuk explanation.
+   * an explanation (explanation) — Bahasa Indonesia, boleh sisipkan istilah/kanji/kata ujian bila perlu
   * difficulty level (${difficulty})
   * relevant skill tags (skillTags)
+- For JLPT/TOPIK kanji/hanja: Include reading annotations in format: 漢字(かんじ) for words that have readings.
 - Questions should test real comprehension, not just surface-level recall.
 - For multiple choice: always provide 4 options labeled A, B, C, D.
 - Options must be plausible distractors — one clearly correct answer.
+${OPTION_QUALITY_RULES}
 - For matching_pairs: Provide options as an array of {key, text} where key is the left item identifier and text is the left item. correctAnswer should be a serialized mapping like "A:1,B:2,C:3" matching each left key to its right pair.
 - For error_recognition: options are error segments (A, B, C, D) and correctAnswer is the key of the segment containing an error.
 - For text_insertion: options are position markers (A, B, C, D) within the passage where a sentence could be inserted. correctAnswer is the best position key.

packages/ai/src/regenerate-questions.ts

@@ -0,0 +1,100 @@
+import { OpenAICompatibleClient } from "./client";
+import { getGenericQuestionJsonSchemaDescription } from "./repair";
+import { OPTION_QUALITY_RULES } from "./prompts";
+import { buildContentLanguageRules, buildExplanationLanguageRule } from "./language-rules";
+import type { GenerationInput } from "./schemas";
+
+function parseJsonResponse(content: string): unknown {
+  if (!content) throw new Error("Empty response from AI");
+  try {
+    return JSON.parse(content);
+  } catch {
+    const cleaned = content
+      .replace(/^```json\s*/, "")
+      .replace(/```\s*$/, "")
+      .trim();
+    return JSON.parse(cleaned);
+  }
+}
+
+function calculateRegenerateMaxTokens(userMax: number, count: number): number {
+  const base = userMax > 0 ? userMax : 16_384;
+  return Math.min(Math.max(base, 2_000 + count * 600), 64_000);
+}
+
+const SYSTEM_PROMPT =
+  "You are a precise exam question generator. You always return valid JSON. You never include markdown formatting around the JSON.";
+
+/**
+ * Regenerate questions that failed structural or semantic validation.
+ */
+export async function regenerateQuestions(
+  client: OpenAICompatibleClient,
+  input: GenerationInput,
+  passage: string,
+  count: number,
+  context: string,
+  onToken?: (token: string) => void,
+): Promise<{ questions: Array<Record<string, unknown>>; tokensUsed: number }> {
+  const schema = getGenericQuestionJsonSchemaDescription();
+
+  const prompt = `You are an expert exam question writer. ${context}
+
+Passage:
+"""
+${passage}
+"""
+
+Generate ${count} new reading comprehension questions for ${input.examType} exam.
+Formats: ${input.formats.join(", ")}
+Difficulty: ${input.difficulty}/5
+
+Rules:
+- Each question must be directly answerable from the passage
+- Use "passageText" field with relevant excerpt (or full passage)
+${OPTION_QUALITY_RULES}
+${buildContentLanguageRules(input.examType)}
+${buildExplanationLanguageRule(input.examType)}
+- For true_false_not_given: correctAnswer must be TRUE, FALSE, or NOT_GIVEN (uppercase)
+- For author_view: correctAnswer must be YES, NO, or NOT_GIVEN (uppercase)
+- For matching_pairs: options are {key, text} pairs. correctAnswer is serialized mapping.
+- For error_recognition: options are error segments. correctAnswer is key of segment with error.
+- For text_insertion: options are position markers. correctAnswer is best position key.
+
+Question schema:
+${schema}
+
+Return ONLY valid JSON conforming to this schema.`;
+
+  const result = await client.chatCompletion(
+    {
+      model: input.apiKeyConfig.model,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: prompt },
+      ],
+      temperature: 0.7,
+      max_tokens: calculateRegenerateMaxTokens(input.apiKeyConfig.maxTokens, count),
+      response_format: { type: "json_object" },
+    },
+    onToken ? { onToken } : undefined,
+  );
+
+  const parsed = parseJsonResponse(result.content) as Record<string, unknown>;
+  if (!Array.isArray(parsed.questions)) {
+    throw new Error("Missing questions array in regeneration response");
+  }
+  return {
+    questions: parsed.questions as Array<Record<string, unknown>>,
+    tokensUsed: result.usage?.total_tokens ?? 0,
+  };
+}
+
+export function buildRegenerationContext(
+  invalid: Array<{ index: number; errors: string[] }>,
+): string {
+  const details = invalid
+    .map((item) => `Q${item.index + 1}: ${item.errors.join(", ")}`)
+    .join("; ");
+  return `The previous ${invalid.length} question(s) failed validation: ${details}.`;
+}

packages/ai/src/repair.ts

@@ -5,6 +5,10 @@ import {
   questionSchema,
   type Question,
 } from "./schemas";
+import {
+  getQuestionLanguageErrors,
+  getExplanationLanguageErrors,
+} from "./language-rules";
 
 // ── Generic Question Schema (for AI prompt) ─────────────────
 // Simplified schema that AI can understand easily.
@@ -43,6 +47,58 @@ const FORMATS_WITH_OPTIONS = new Set([
   "sentence_arrangement",
 ]);
 
+const FORMATS_MIN_TWO_OPTIONS = new Set([
+  "multiple_choice",
+  "synonym",
+  "grammar_in_context",
+  "sentence_completion",
+  "reference",
+  "kanji_reading",
+  "particle_choice",
+  "article_case",
+  "character_reading",
+  "sentence_arrangement",
+  "error_recognition",
+  "text_insertion",
+  "summary_completion",
+  "cloze",
+  "matching_headings",
+  "matching_information",
+]);
+
+/** Detect generic placeholder option text from lazy AI output or repair fallbacks. */
+export function isGenericOptionText(text: string): boolean {
+  const t = text.trim();
+  if (!t) return true;
+  if (/^placeholder/i.test(t)) return true;
+  if (/^(option|pilihan|choice|opsi)(\s+[a-d0-9]+)?\.?$/i.test(t)) return true;
+  return false;
+}
+
+/** Semantic quality checks beyond Zod structural validation. */
+export function getQuestionSemanticErrors(q: GenericQuestion): string[] {
+  if (!FORMATS_WITH_OPTIONS.has(q.format)) return [];
+
+  const errors: string[] = [];
+  if (!Array.isArray(q.options) || q.options.length === 0) {
+    errors.push("options missing or empty");
+    return errors;
+  }
+
+  const minOptions = FORMATS_MIN_TWO_OPTIONS.has(q.format) ? 2 : 1;
+  if (q.options.length < minOptions) {
+    errors.push(`options must have at least ${minOptions} item(s)`);
+  }
+
+  for (const opt of q.options) {
+    if (isGenericOptionText(opt.text)) {
+      errors.push(`generic placeholder option text: "${opt.text}"`);
+    }
+  }
+
+  return errors;
+}
+
 function normalizeOptionKey(key: string): string {
   return key.trim().toUpperCase();
 }
@@ -58,26 +114,10 @@ function ensureOptions(
 
   let opts = q.options;
   if (!Array.isArray(opts) || opts.length === 0) {
-    // AI forgot options — inject plausible placeholders so parsing can succeed
-    // We'll mark them for later regeneration if needed
-    if (q.format === "multiple_choice" || q.format === "synonym" || q.format === "grammar_in_context" ||
-        q.format === "sentence_completion" || q.format === "reference" || q.format === "kanji_reading" ||
-        q.format === "particle_choice" || q.format === "article_case" || q.format === "character_reading" ||
-        q.format === "sentence_arrangement" || q.format === "error_recognition" || q.format === "text_insertion") {
-      return [
-        { key: "A", text: "Option A" },
-        { key: "B", text: "Option B" },
-        { key: "C", text: "Option C" },
-        { key: "D", text: "Option D" },
-      ];
-    }
-    if (q.format === "matching_headings" || q.format === "matching_information" ||
-        q.format === "summary_completion" || q.format === "cloze") {
-      return [{ key: "1", text: "Placeholder option" }];
-    }
+    return undefined;
   }
 
-  opts = opts!.map((o) => ({
+  opts = opts.map((o) => ({
     key: normalizeOptionKey(o.key),
     text: normalizeOptionText(o.text),
   }));
@@ -158,10 +198,13 @@ function ensureExplanation(q: GenericQuestion): string {
   return "Penjelasan tidak tersedia.";
 }
 
-function ensureQuestionText(q: GenericQuestion): string {
+function ensureQuestionText(q: GenericQuestion, examType?: string): string {
   const text = q.questionText?.trim();
   if (text && text.length >= 10) return text;
-  return text || "Soal latihan membaca.";
+  if (examType === "JLPT") return "この文章の内容について正しいものはどれですか。";
+  if (examType === "HSK") return "根据短文，下列哪项正确？";
+  if (examType === "TOPIK") return "글의 내용과 일치하는 것은 무엇입니까?";
+  return text || "What is the correct answer based on the passage?";
 }
 
 function ensureDifficulty(q: GenericQuestion): number {
@@ -176,6 +219,7 @@ function ensureDifficulty(q: GenericQuestion): number {
 export function repairQuestion(
   raw: unknown,
   fullPassage: string,
+  examType?: string,
 ): { question: GenericQuestion; wasRepaired: boolean; repairNotes: string[] } {
   const notes: string[] = [];
   let wasRepaired = false;
@@ -190,7 +234,7 @@ export function repairQuestion(
   const q: GenericQuestion = {
     format: String(r.format || "multiple_choice").trim().toLowerCase() as any,
     passageText: ensurePassageText(r as GenericQuestion, fullPassage),
-    questionText: ensureQuestionText(r as GenericQuestion),
+    questionText: ensureQuestionText(r as GenericQuestion, examType),
     options: Array.isArray(r.options)
       ? r.options
           .filter((o: any) => o && typeof o === "object")
@@ -215,8 +259,8 @@ export function repairQuestion(
   if (explanationText.trim().length === 0) {
     notes.push("explanation missing, used fallback");
     wasRepaired = true;
-  } else if (hasCJK(explanationText)) {
-    notes.push("explanation contains CJK characters (should be Bahasa Indonesia), marked for regeneration");
+  } else if (getExplanationLanguageErrors(explanationText).length > 0) {
+    notes.push("explanation not in Bahasa Indonesia, marked for regeneration");
     wasRepaired = true;
   }
   if (!Array.isArray(r.skillTags) || r.skillTags.length === 0) {
@@ -232,14 +276,12 @@ export function repairQuestion(
     wasRepaired = true;
   }
 
-  // Ensure options
+  // Normalize options (no placeholder injection — missing options fail semantic validation)
   const repairedOptions = ensureOptions(q);
   if (repairedOptions !== undefined) {
-    if (!q.options || q.options.length === 0) {
-      notes.push("options missing, injected placeholders");
-      wasRepaired = true;
-    }
     q.options = repairedOptions;
+  } else if (FORMATS_WITH_OPTIONS.has(q.format)) {
+    q.options = undefined;
   }
 
   return { question: q, wasRepaired, repairNotes: notes };
@@ -263,6 +305,7 @@ export function tryParseQuestion(generic: GenericQuestion): Question | null {
 export function repairAndParseQuestions(
   rawQuestions: unknown[],
   fullPassage: string,
+  options?: { examType?: string },
 ): {
   valid: Question[];
   invalid: { index: number; raw: unknown; errors: string[] }[];
@@ -272,13 +315,27 @@ export function repairAndParseQuestions(
   const invalid: { index: number; raw: unknown; errors: string[] }[] = [];
   const repairLog: string[] = [];
 
+  const examType = options?.examType;
+
   for (let i = 0; i < rawQuestions.length; i++) {
     const raw = rawQuestions[i];
     try {
-      const { question: repaired, wasRepaired, repairNotes } = repairQuestion(raw, fullPassage);
+      const { question: repaired, wasRepaired, repairNotes } = repairQuestion(raw, fullPassage, examType);
       if (wasRepaired) {
         repairLog.push(`Q${i + 1}: ${repairNotes.join("; ")}`);
       }
+
+      const semanticErrors = [
+        ...getQuestionSemanticErrors(repaired),
+        ...(examType ? getQuestionLanguageErrors(repaired, examType) : []),
+        ...getExplanationLanguageErrors(repaired.explanation),
+      ];
+      if (semanticErrors.length > 0) {
+        invalid.push({ index: i, raw, errors: semanticErrors });
+        repairLog.push(`Q${i + 1}: semantic quality failure — ${semanticErrors.join(", ")}`);
+        continue;
+      }
+
       const parsed = tryParseQuestion(repaired);
       if (parsed) {
         valid.push(parsed);
@@ -349,7 +406,7 @@ export function getGenericQuestionJsonSchemaDescription(): string {
                   type: "object",
                   properties: {
                     key: { type: "string", description: "Option identifier (e.g. A, B, C, D)" },
-                    text: { type: "string", description: "Option text" },
+                    text: { type: "string", description: "Meaningful answer text from the passage — never generic labels like 'Option A'" },
                   },
                   required: ["key", "text"],
                 },
@@ -358,7 +415,7 @@ export function getGenericQuestionJsonSchemaDescription(): string {
                 type: "string",
                 description: "For true_false_not_given use TRUE/FALSE/NOT_GIVEN. For author_view use YES/NO/NOT_GIVEN. For multiple choice use the option key (e.g. A).",
               },
-              explanation: { type: "string", description: "Explanation in Indonesian" },
+              explanation: { type: "string", description: "Explanation in Bahasa Indonesia; may include exam-language terms/kanji when relevant" },
               difficulty: { type: "integer", minimum: 1, maximum: 5 },
               skillTags: { type: "array", items: { type: "string" } },
             },

packages/api/src/queue.ts

@@ -9,7 +9,10 @@ async function log(level: "debug" | "warn", message: string, meta?: Record<strin
 import {
   generateQuestionsQuick,
   generateQuestionsAgentic,
+  generatePassageForInput,
+  generateQuestionsAgenticFromPassage,
   GenerationError,
+  type AgenticProgress,
   type GenerationInput,
   type GenerationResult,
 } from "@labas/ai";
@@ -83,6 +86,74 @@ export class GenerationJobCancelledError extends Error {
   }
 }
 
+const AGENTIC_STEP_FRACTIONS = [0.12, 0.28, 0.62, 0.92] as const;
+
+const AGENTIC_STEP_LABELS: Record<string, string> = {
+  generate_passage: "Menulis bacaan...",
+  validate_passage: "Memvalidasi bacaan...",
+  generate_questions: "Membuat soal...",
+  self_validate: "Validasi kualitas...",
+};
+
+function mapAgenticProgressInShard(
+  agentic: AgenticProgress,
+  completedShards: number,
+  totalShards: number,
+): { progress: number; message: string } {
+  const shardSpan = 65 / Math.max(totalShards, 1);
+  const shardBase = 15 + completedShards * shardSpan;
+  const stepFrac = AGENTIC_STEP_FRACTIONS[agentic.currentStep] ?? 0.5;
+  const progress = Math.min(Math.round(shardBase + shardSpan * stepFrac), 84);
+  const step = agentic.steps[agentic.currentStep];
+  const message =
+    step?.message ??
+    AGENTIC_STEP_LABELS[step?.step ?? ""] ??
+    "Agentic generation...";
+  return { progress, message };
+}
+
+function mapAgenticProgressInQuality(agentic: AgenticProgress): { progress: number; message: string } {
+  const stepFrac = AGENTIC_STEP_FRACTIONS[agentic.currentStep] ?? 0.5;
+  const progress = Math.min(86 + Math.round(stepFrac * 10), 96);
+  const step = agentic.steps[agentic.currentStep];
+  const message =
+    step?.message ??
+    AGENTIC_STEP_LABELS[step?.step ?? ""] ??
+    "Quality validation...";
+  return { progress, message };
+}
+
+function createAgenticProgressHandler(
+  updateProgress: (progress: number, progressMessage: string) => Promise<void>,
+  pushLog: (
+    step: string,
+    message: string,
+    status: "running" | "done" | "error",
+    details?: string,
+  ) => Promise<void>,
+  mapProgress: (agentic: AgenticProgress) => { progress: number; message: string },
+) {
+  const seenSteps = new Set<string>();
+
+  return (agentic: AgenticProgress) => {
+    const { progress, message } = mapProgress(agentic);
+    void updateProgress(progress, message).catch(() => {});
+
+    for (const step of agentic.steps) {
+      if (!step || step.status === "pending") continue;
+      const key = `${step.step}:${step.status}`;
+      if (seenSteps.has(key)) continue;
+      seenSteps.add(key);
+      void pushLog(
+        step.step,
+        step.message ?? AGENTIC_STEP_LABELS[step.step] ?? step.step,
+        step.status as "running" | "done" | "error",
+        step.output,
+      ).catch(() => {});
+    }
+  };
+}
+
 export function computeSectionSplit(
   selectedSections: string[],
   count: number,
@@ -532,6 +603,7 @@ export const generationWorker = new Worker<FastJobData>(
         .where(eq(generationJob.id, jobId));
     };
 
+    let maxProgress = 0;
     const updateProgress = async (
       progress: number,
       progressMessage: string,
@@ -539,11 +611,13 @@ export const generationWorker = new Worker<FastJobData>(
       resultJson?: unknown,
     ) => {
       cancelPoll.check();
-      await job.updateProgress(progress);
+      const next = Math.max(maxProgress, progress);
+      maxProgress = next;
+      await job.updateProgress(next);
       const [updated] = await db
         .update(generationJob)
         .set({
-          progress,
+          progress: next,
           progressMessage,
           ...(status ? { status } : {}),
           ...(resultJson !== undefined ? { resultJson: resultJson as any } : {}),
@@ -590,6 +664,29 @@ export const generationWorker = new Worker<FastJobData>(
       let completedShards = 0;
       let partialPublished = false;
       let timeToFirstValidQuestionMs: number | null = null;
+      const sectionPassages = new Map<string, string>();
+
+      if (selectedMode === "agentic") {
+        for (const split of sectionSplits) {
+          if (sectionPassages.has(split.section)) continue;
+          await updateProgress(8, `Menulis bacaan ${split.section}...`);
+          const passageInput: GenerationInput = {
+            ...input,
+            section: split.section as GenerationInput["section"],
+            questionCount: split.count,
+          };
+          const passageResult = await generatePassageForInput(passageInput, tokenCounter);
+          totalTokens += passageResult.tokensUsed ?? 0;
+          sectionPassages.set(split.section, passageResult.passage);
+          await pushLog(
+            "generate_passage",
+            `Bacaan siap: ${passageResult.title}`,
+            "done",
+            passageResult.passage.slice(0, 400),
+          );
+        }
+      }
+
       const shardResults: Array<{
         shard: ShardPlan;
         questions: PersistableQuestion[];
@@ -610,14 +707,30 @@ export const generationWorker = new Worker<FastJobData>(
         };
 
         let sectionResult: GenerationResult;
+        const onAgenticProgress = createAgenticProgressHandler(
+          (progress, progressMessage) => updateProgress(progress, progressMessage),
+          pushLog,
+          (agentic) => mapAgenticProgressInShard(agentic, completedShards, shards.length),
+        );
         try {
           if (selectedMode === "agentic") {
-            sectionResult = await generateQuestionsAgentic(
-              subInput,
-              undefined,
-              tokenCounter,
-              { strategy: "lean", maxRegenerateAttempts: 1 },
-            );
+            const sharedPassage = sectionPassages.get(shard.section);
+            if (sharedPassage) {
+              sectionResult = await generateQuestionsAgenticFromPassage(
+                subInput,
+                sharedPassage,
+                onAgenticProgress,
+                tokenCounter,
+                { strategy: "full", maxRegenerateAttempts: 1 },
+              );
+            } else {
+              sectionResult = await generateQuestionsAgentic(
+                subInput,
+                onAgenticProgress,
+                tokenCounter,
+                { strategy: "full", maxRegenerateAttempts: 1 },
+              );
+            }
           } else {
             sectionResult = await generateQuestionsQuick(subInput, {
               onToken: tokenCounter,
@@ -637,9 +750,9 @@ export const generationWorker = new Worker<FastJobData>(
 
           sectionResult = await generateQuestionsAgentic(
             { ...subInput, mode: "agentic" },
-            undefined,
+            onAgenticProgress,
             tokenCounter,
-            { strategy: "lean", maxRegenerateAttempts: 1 },
+            { strategy: "full", maxRegenerateAttempts: 1 },
           );
         }
 
@@ -780,43 +893,24 @@ export const generationWorker = new Worker<FastJobData>(
       };
 
       if (selectedMode === "agentic") {
-        await updateProgress(85, "Fast phase done, enqueuing quality phase...", "running_quality", {
-          ...fastResult,
+        await pushLog("save", "Saving agentic result...", "running");
+        await completeJobWithResult({
+          jobId,
+          input,
+          allQuestions,
           sectionSplits,
-          qualityPhase: "fast",
-          isPartial: true,
+          totalTokens: totalTokens || approxTokens,
+          durationMs: Date.now() - start,
+          statusMessage: "Completed",
           metrics: {
             timeToFirstValidQuestionMs: timeToFirstValidQuestionMs ?? Date.now() - start,
             shardCount: shards.length,
             shardRetryBudget: MAX_SHARD_RETRIES,
+            shardFailures: failedShards.length,
+            singlePassAgentic: true,
           },
         });
-        await pushLog(
-          "quality_queue",
-          "Partial result ready, lanjut quality upgrade di background",
-          "done",
-        );
-        await generationQualityQueue.add(
-          "quality-upgrade",
-          {
-            input,
-            jobId,
-            sectionSplits,
-            fastQuestions: allQuestions,
-            fastMeta: {
-              tokensUsed: totalTokens,
-              durationMs: totalDurationMs || Date.now() - start,
-              approxTokens,
-            },
-          },
-          {
-            jobId,
-            removeOnComplete: { count: 100 },
-            removeOnFail: { count: 100 },
-            attempts: 2,
-            backoff: { type: "exponential", delay: 4000 },
-          },
-        );
+        await pushLog("save", `Saved ${allQuestions.length} questions`, "done");
         return;
       }
 
@@ -902,6 +996,7 @@ export const generationQualityWorker = new Worker<QualityJobData>(
 
     const cancelPoll = createCancellationPoller(jobId);
     let approxTokens = 0;
+    let maxProgress = 0;
     const tokenCounter = (token: string) => {
       cancelPoll.check();
       approxTokens += Math.ceil(token.length / 4);
@@ -909,12 +1004,14 @@ export const generationQualityWorker = new Worker<QualityJobData>(
 
     const updateProgress = async (progress: number, progressMessage: string) => {
       cancelPoll.check();
-      await job.updateProgress(progress);
+      const next = Math.max(maxProgress, progress);
+      maxProgress = next;
+      await job.updateProgress(next);
       const [updated] = await db
         .update(generationJob)
         .set({
           status: "running_quality",
-          progress,
+          progress: next,
           progressMessage,
         })
         .where(
@@ -961,9 +1058,14 @@ export const generationQualityWorker = new Worker<QualityJobData>(
               questionCount: split.count,
               mode: "agentic",
             };
+            const onQualityProgress = createAgenticProgressHandler(
+              updateProgress,
+              pushLog,
+              mapAgenticProgressInQuality,
+            );
             const result = await generateQuestionsAgentic(
               sectionInput,
-              undefined,
+              onQualityProgress,
               tokenCounter,
               { strategy: "full", maxRegenerateAttempts: 2 },
             );