pbmate.ro

Build a personal Romanian maths practice trainer in an empty folder.
Stack: Next.js 15 (App Router), TypeScript, SQLite via better-sqlite3, Tailwind, KaTeX. Do not offer alternatives.
Problems live as Markdown files in content/problems, one per file, with frontmatter: id, chapter, grade, difficulty 1 to 5, statement, four options, correctIndex, hints (up to three, ordered nudge -> method -> setup), solution.
Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.
Ship exactly three seed problems as format examples plus a chapters.json for one grade, taken from the official programa. Generate no problems yourself.
Practice loop: pick a chapter, get five problems ordered easy to hard, answer, then reveal hints one at a time before the solution.
Record every attempt (problem id, chosen option, correct, seconds, hints used) in SQLite.
Show a per-chapter mastery bar from the last twenty attempts on that chapter and a weak-chapters list. No streaks, no badges, no daily guilt.
Add `npm run drill` that serves only problems previously answered wrong.
Render maths with KaTeX inline and display, and verify the seed problems render before you finish.
Handle Romanian diacritics correctly in the files and the UI.
Add `npm run export` writing all attempts to CSV, and keep every byte on the local disk.
If ANTHROPIC_API_KEY is set in .env, add an optional `npm run draft -- paper.pdf` that turns an exam PDF into draft Markdown in content/drafts, never imported until a human moves the file, and print a warning that the answer key is unverified.
Secrets in .env, ship .env.example, commit neither.
Test the importer validation rules and one end-to-end five-problem session.
Write a README covering setup, the problem file format, and how to add a chapter.
Leave out: accounts, payments, hosting, telemetry, parent and teacher views, a mobile app, and anything claiming to grade a real exam.
Finish by running the import and the tests, then print the exact commands used.

# AGENTS.md — Build guide for pbmate.ro

## Project scope
A local trainer for maths problems you author yourself: pick a chapter, work through five problems, reveal graded hints, then the full solution, and watch a per chapter mastery bar move.

Catalogue verdict: no. The trainer is not the product. An agent will hand you a clean multiple-choice runner with LaTeX, hints and a mastery chart in one evening, and then you will be staring at an empty database. What is actually being sold here is roughly 5.000 published problems mapped chapter by chapter to the Romanian programa, the official Bacalaureat and Evaluare Națională papers rebuilt as interactive tests with every marking scheme re-derived rather than trusted, and four role surfaces (pupil, parent, teacher, plus an iOS app) grown over more than 2.300 commits. A language model will cheerfully generate a thousand Romanian maths problems for you, and a worrying share will carry a wrong answer key, a hint that leaks the answer, or a chapter label that does not match the programa. You will not find out which until a child gets one wrong for the wrong reason. Check a hundred by hand and the price stops looking mysterious. Build the trainer if you enjoy building; the honest free move is the ministry's own paper archive, not a rebuild.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node 22
- your own problem set, or the public Bacalaureat and Evaluare Națională PDFs
- optional Anthropic or OpenAI API key for draft extraction from those PDFs
- somebody willing to solve every problem before trusting its answer key

## Stack and architecture
- Stack: Next.js 15 (App Router), TypeScript, SQLite via better-sqlite3, Tailwind, KaTeX. Do not offer alternatives.
- Model lessons, study sessions, progress checkpoints, and user-owned learning material; keep stable source IDs and timestamps.
- Interface for this Romanian school maths practice and national exam prep, grades 5 to 11 workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: roughly 5.000 vetted problems, each tied to a chapter of the Romanian programa and a difficulty tier.

## Agent implementation rules
- Project rule, data: Model lessons, study sessions, progress checkpoints, and user-owned learning material; keep stable source IDs and timestamps.
- Project rule, behavior: Practice loop: pick a chapter, get five problems ordered easy to hard, answer, then reveal hints one at a time before the solution.
- Project rule, recovery: Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this Romanian school maths practice and national exam prep, grades 5 to 11 operation with sample or user-owned data: Practice loop: pick a chapter, get five problems ordered easy to hard, answer, then reveal hints one at a time before the solution.
- Show a concrete result or export: Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.
- State the practical limit: roughly 5.000 vetted problems, each tied to a chapter of the Romanian programa and a difficulty tier.

## Engineering roadmap
1. Phase 1, architecture and data: Stack: Next.js 15 (App Router), TypeScript, SQLite via better-sqlite3, Tailwind, KaTeX. Do not offer alternatives. Model lessons, study sessions, progress checkpoints, and user-owned learning material; keep stable source IDs and timestamps.
2. Phase 2, implement: Practice loop: pick a chapter, get five problems ordered easy to hard, answer, then reveal hints one at a time before the solution.
3. Phase 3, implement: Record every attempt (problem id, chosen option, correct, seconds, hints used) in SQLite.
4. Phase 4, review and output: Show a per-chapter mastery bar from the last twenty attempts on that chapter and a weak-chapters list. No streaks, no badges, no daily guilt. Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.
5. Phase 5, recovery and acceptance: Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring. Verify this invariant with a saved fixture: An interrupted session cannot double-count an answer; a restored deck retains card IDs and due dates. State the practical limit: roughly 5.000 vetted problems, each tied to a chapter of the Romanian programa and a difficulty tier.

## Paid-product capabilities outside this build
- roughly 5.000 vetted problems, each tied to a chapter of the Romanian programa and a difficulty tier
- official exam papers rebuilt as interactive tests, with each marking scheme re-derived point by point
- three progressive hints and a written solution on every problem, not just the correct letter
- the parent and teacher surfaces, assigned homework, and the iOS app
- somebody maintaining all of it when the programa or the exam format shifts

## Implementation prompt
Build a personal Romanian maths practice trainer in an empty folder.
Stack: Next.js 15 (App Router), TypeScript, SQLite via better-sqlite3, Tailwind, KaTeX. Do not offer alternatives.
Problems live as Markdown files in content/problems, one per file, with frontmatter: id, chapter, grade, difficulty 1 to 5, statement, four options, correctIndex, hints (up to three, ordered nudge -> method -> setup), solution.
Write `npm run import` to validate every file into SQLite, failing loudly on a missing correctIndex, an out-of-range difficulty, an unknown chapter, or a hint containing the final answer as a substring.
Ship exactly three seed problems as format examples plus a chapters.json for one grade, taken from the official programa. Generate no problems yourself.
Practice loop: pick a chapter, get five problems ordered easy to hard, answer, then reveal hints one at a time before the solution.
Record every attempt (problem id, chosen option, correct, seconds, hints used) in SQLite.
Show a per-chapter mastery bar from the last twenty attempts on that chapter and a weak-chapters list. No streaks, no badges, no daily guilt.
Add `npm run drill` that serves only problems previously answered wrong.
Render maths with KaTeX inline and display, and verify the seed problems render before you finish.
Handle Romanian diacritics correctly in the files and the UI.
Add `npm run export` writing all attempts to CSV, and keep every byte on the local disk.
If ANTHROPIC_API_KEY is set in .env, add an optional `npm run draft -- paper.pdf` that turns an exam PDF into draft Markdown in content/drafts, never imported until a human moves the file, and print a warning that the answer key is unverified.
Secrets in .env, ship .env.example, commit neither.
Test the importer validation rules and one end-to-end five-problem session.
Write a README covering setup, the problem file format, and how to add a chapter.
Leave out: accounts, payments, hosting, telemetry, parent and teacher views, a mobile app, and anything claiming to grade a real exam.
Finish by running the import and the tests, then print the exact commands used.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.