Educamos

Build a local-only family school tracker called Boletin. Single user, no accounts, no cloud.

Stack, no substitutions:
- Node 20, TypeScript, Fastify for the server
- SQLite via better-sqlite3, file at ./data/boletin.db, schema created on first run
- Server-rendered HTML with a single Pico.css CDN link, plus a little vanilla JS. No React, no build step beyond tsc.

Data model:
- child: id, name, school_year
- subject: id, child_id, name, teacher_name (optional), weight (optional)
- grade: id, subject_id, date, label, score, max_score, notes
- attendance: id, child_id, date, status (present, absent, late, excused), notes
- note: id, child_id, date, source (teacher, school, me), title, body, pinned boolean
- homework: id, subject_id, due_date, title, done boolean

Features, in scope:
- Child switcher in the header.
- Dashboard per child: current average per subject (weighted if weights set), homework due in the next 7 days, last 5 notes, absence count this term.
- Forms to add and edit every entity. Fast keyboard entry matters more than looks: one page per entity type with an inline add row at the top.
- Subject detail page with a plain SVG line chart of grades over time, no chart library.
- A weekly summary page rendered from the last 7 days of data, with a copy-to-clipboard plain text version.
- CSV import for grades: columns subject,date,label,score,max_score. Show a preview and a row count before committing.
- Export everything to JSON at /export, and a button that copies the SQLite file to ./backups with a timestamp.

Explicitly out of scope, do not attempt:
- Any connection to a school platform, no scraping, no login automation, no unofficial APIs
- Multi-user, invites, or messaging
- Push notifications, email, telemetry, analytics

Details:
- npm start runs the server on PORT from .env, default 3000. Commit .env.example only.
- Seed script with one fictional child and two subjects so the UI is not empty on first run.
- README: what this is, what it is not, and one blunt line saying grades must be typed in by hand because the school's system is the source of truth.

# AGENTS.md — Build guide for Educamos

## Project scope
A local family dashboard where you manually log grades, homework and school notices per child and get a simple trend view plus a weekly summary.

Catalogue verdict: no. This is not an app you own, it is the system of record your school runs on. The grades, attendance marks, timetables and official report cards live on the school's tenant, entered by teachers you do not employ, under student data rules you do not control. A personal replacement would have nothing authoritative to read from: there is no public API you can point at, and scraping a minor's school portal is a bad idea on several axes at once. Even if you rebuilt the parent-facing screens perfectly, the moment a teacher posts a notice it would appear in Educamos and not in your build. The honest DIY here is a private tracker that sits beside it, not a replacement for it.
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 and a local SQLite file
- Manual entry, or copy-paste from whatever the school actually sends you
- Nothing else, no school system access

## Stack and architecture
- Node 20, TypeScript, Fastify for the server.
- Data model:.
- Interface for this school management platform workflow: a focused school management platform input, review, and export interface.

## Security and data integrity
- On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Authoritative data: teachers enter grades and attendance in Educamos, not in your app.

## Agent implementation rules
- Project rule, data: Data model:.
- Project rule, behavior: subject: id, child_id, name, teacher_name (optional), weight (optional).
- Project rule, recovery: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.

## 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 school management platform operation with sample or user-owned data: subject: id, child_id, name, teacher_name (optional), weight (optional).
- Show a concrete result or export: Export everything to JSON at /export, and a button that copies the SQLite file to ./backups with a timestamp.
- State the practical limit: Authoritative data: teachers enter grades and attendance in Educamos, not in your app.

## Engineering roadmap
1. Phase 1, architecture and data: Node 20, TypeScript, Fastify for the server. Data model:.
2. Phase 2, implement: subject: id, child_id, name, teacher_name (optional), weight (optional).
3. Phase 3, implement: grade: id, subject_id, date, label, score, max_score, notes.
4. Phase 4, review and output: attendance: id, child_id, date, status (present, absent, late, excused), notes. Export everything to JSON at /export, and a button that copies the SQLite file to ./backups with a timestamp.
5. Phase 5, recovery and acceptance: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry. 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: Authoritative data: teachers enter grades and attendance in Educamos, not in your app.

## Paid-product capabilities outside this build
- Authoritative data: teachers enter grades and attendance in Educamos, not in your app
- Two-way messaging with teachers and the school office
- Official documents: report cards, absence justifications, enrolment and billing flows
- Timetable, room and substitution updates that come from the school's own scheduling
- Everyone else on it: the school, other parents, the administration staff

## Implementation prompt
Build a local-only family school tracker called Boletin. Single user, no accounts, no cloud.

Stack, no substitutions:
- Node 20, TypeScript, Fastify for the server
- SQLite via better-sqlite3, file at ./data/boletin.db, schema created on first run
- Server-rendered HTML with a single Pico.css CDN link, plus a little vanilla JS. No React, no build step beyond tsc.

Data model:
- child: id, name, school_year
- subject: id, child_id, name, teacher_name (optional), weight (optional)
- grade: id, subject_id, date, label, score, max_score, notes
- attendance: id, child_id, date, status (present, absent, late, excused), notes
- note: id, child_id, date, source (teacher, school, me), title, body, pinned boolean
- homework: id, subject_id, due_date, title, done boolean

Features, in scope:
- Child switcher in the header.
- Dashboard per child: current average per subject (weighted if weights set), homework due in the next 7 days, last 5 notes, absence count this term.
- Forms to add and edit every entity. Fast keyboard entry matters more than looks: one page per entity type with an inline add row at the top.
- Subject detail page with a plain SVG line chart of grades over time, no chart library.
- A weekly summary page rendered from the last 7 days of data, with a copy-to-clipboard plain text version.
- CSV import for grades: columns subject,date,label,score,max_score. Show a preview and a row count before committing.
- Export everything to JSON at /export, and a button that copies the SQLite file to ./backups with a timestamp.

Explicitly out of scope, do not attempt:
- Any connection to a school platform, no scraping, no login automation, no unofficial APIs
- Multi-user, invites, or messaging
- Push notifications, email, telemetry, analytics

Details:
- npm start runs the server on PORT from .env, default 3000. Commit .env.example only.
- Seed script with one fictional child and two subjects so the UI is not empty on first run.
- README: what this is, what it is not, and one blunt line saying grades must be typed in by hand because the school's system is the source of truth.

## 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.