Oxford Music Academy

The user manual

Everything the front desk, the teachers, and the owner need — organised by how often you'll need it. Each task is a short list of steps. Nothing here assumes you are technical.

Starting the system

The system is one program running on the school computer. Everyone — the web browser and the teachers' iPhones — connects to it.

1. Open the Terminal application.
2. Paste this line and press return:
   npm --prefix app start
3. Open a browser to http://localhost:7070/welcome.html — the front page. The brass button opens the system itself.

Signing in

Everyone has their own account, and the books record who did what — a mark made on Ruth's phone lands in the audit trail as Ruth, and nobody can act as someone else.

Sign out is at the bottom of the sidebar, under your name. Sessions last 30 days on a device you keep using.

Setting up the iPhone app

1. Open Oxford Teacher on the phone.
2. Sign in with your own username and password (e.g. ruth / ruth-key-26). Only teacher accounts work here — the owner and front desk use the web.
3. That's it. The app remembers you for 30 days; Sign out is in Settings (the circle icon, top right).

The Today screen

This is the first screen every morning. Four numbers, left to right:

The chart below is two years of monthly revenue. The dips are term breaks; they are supposed to be there.

The schedule

The Schedule view shows one week. Move between weeks with the ‹ › arrows; This week brings you home.

• Each lesson card shows the time, the student, and the teacher. The dot is the teacher's colour — the legend above the grid lists every teacher. Click a teacher's name in the legend (or use the dropdown) to see only their lessons.
• The card's left edge is its status: attended · no-show · cancelled · grey means not yet marked.
• Makeup lessons say so on the card — they are lessons taught against a credit.
• Click any lesson to open it. Everything you can do to a lesson happens there.

Taking attendance

1. Click the lesson (web) — or, on the phone, swipe it right.
2. Choose Attended or No-show. On the phone: swipe right for attended, left for no-show.

The mark lands in payroll immediately and is written to the activity log under your name.

Cancelling a lesson

1. Open the lesson and choose Cancel…
2. Say who is cancelling — the family or the school. This matters: school cancellations always credit the family; family cancellations follow the policy.
3. Read the decision. The system shows its reasoning as numbered steps — the notice hours compared against the cutoff, the family's cancellation count against the cap — and then what happened: a credit was issued, the lesson was forfeited, or the cancellation was blocked.

That reasoning is stored with the lesson forever. When a parent asks in July why March went the way it did, open the lesson: it answers with March's rules, not today's.

Undoing a cancellation

Open the cancelled lesson and choose Reinstate. The lesson returns to the calendar and any credit it created is voided — not deleted; the books remember everything.

Credits & makeups

A credit is a lesson the school owes a family — usually from a timely cancellation. The Credits view is the whole ledger: outstanding, booked, used, expired, voided.

Booking a makeup against a credit

1. In Credits, find the outstanding credit and choose Book makeup.
2. Pick the teacher and time. The system refuses slots that clash.
3. The new lesson appears on the schedule marked makeup. When it's taught, the credit is used up.

Issuing a goodwill credit by hand

In Credits, choose Issue credit. A reason is required — it goes in the books and the family may one day read it.

Students & enrolment

The Students view is the roster. The filter switches between current students and those who have left (with when and why).

Enrolling a new student

1. Click Add a student.
2. Choose the family — an existing one, or type a new family's name and contact.
3. Pick the lesson type, teacher, weekday, time, and how many weeks.
4. Read the result: "11 lessons booked — 0 clashed, 1 fell in a school holiday." The system books only real, term-time, clash-free lessons and tells you exactly what it skipped and why.

Retention — who to call this week

The Retention view exists to catch families who leave without telling you. Most do.

• The risk cards name each drifting student, the evidence in plain words ("Nothing on the calendar. The last lesson taught was June 19."), and what they are worth per month. Red cards are urgent; amber cards are worth watching.
• The cohort table reads left to right: of the students who started in a given month, how many were still attending one month later, two months later, and so on. The bottom row is the school's blended survival curve.
• Average lifetime and what one student is worth turn "should I bother calling?" into arithmetic. One saved student is roughly $1,300.

The Action Queue — what needs you, with proof

The Actions view is a short list of situations the system found in the records: a student drifting away, practice that collapsed against the student's own baseline, a credit about to expire, a hard cancellation a family may not understand, a payroll collision, missing attendance marks, or an odd movement in the month-end books. Rules find these — not AI. Every item shows its evidence in plain sentences, the money involved when it is real, and one suggested next step.

1. Read the evidence. Every line comes from the ledger; Open record jumps to the underlying view.
2. Act, then tell the queue: Done when handled; Follow up to keep it on screen until you close it; Snooze 1 week to put it off; Dismiss… with a one-line reason if it needs nothing.
3. Everything you decide is recorded in Activity under your name.

The two AI buttons on each card — Draft message and Case summary — only reword that one card's evidence. They see nothing else, they send nothing, and without an API key the queue works exactly the same minus those two buttons. The queue is visible to the owner's account only.

The AI — what it does and what it never does

One rule governs every AI feature: the AI writes language, never numbers. Every fact it may use comes from the ledger at that moment; the deciding — credits, payroll, refunds — is always done by the policy engine. And the AI never sends anything: every message it writes waits for you to read it and copy it.

Draft buttons, wherever there is evidence

• Retention — every risk card has Draft the message: a warm check-in written from the exact evidence on the card.
• Credits — every outstanding credit has Draft reminder: the value, the expiry date, an invitation to book.
• A cancelled lesson — Explain it to the family: the policy's stored reasoning, said kindly.
• A student's practice — open a student, and if their keyboard reports practice, Draft a practice note writes the encouraging weekly recap.

Each draft opens in a panel with a Copy button. Read it, change what you like, paste it into your own email or text. Nothing is sent by the system.

The Monday briefing

In Assistant, one button writes the owner's weekly page: who to call with the evidence and dollar amounts, the month's three numbers, the payroll collisions to check, expiring credits, and one thing worth doing. Copy it into your notes or email — it reads the books as of the moment you click.

Give an instruction

Also in Assistant: type what you want done — "mark Theo's Wednesday lesson attended", "cancel Chidi's Thursday lesson, the family called", "book Marisol's makeup with Alice next Tuesday at 4pm". The AI only matches your words to real lessons and credits; the system then shows you a proposal built from the database, and nothing happens until you press Confirm. The policy engine has the final word exactly as if you had clicked the buttons yourself. If your words are ambiguous, it says so instead of guessing.

The auditor's note

In Month end, one button asks the AI to read the period like a sceptical accountant: does the margin tie, is the residual zero, which double-pay warnings need eyes before payroll is approved. It checks the numbers in the report — it computes none of them.

Practice telemetry

Piano students' keyboards report practice sittings. You'll see it in three places: a week-by-week chart on the student's card, a "the piano has gone quiet" line in Retention when practice collapses (families stop practising weeks before they stop attending — this catches them earliest of all), and the drafted practice notes above.

One-time setup

1. Create a file called .env inside the app folder.
2. Put one line in it: ANTHROPIC_API_KEY=sk-ant-… (your key).
3. Restart the system. Without the key, every AI button shows the same setup card and everything else works normally.

Payroll

The Payroll view computes each teacher's pay for the period from the lessons actually taught — fixed per lesson, hourly, or a percentage of what the lesson earned. Percentages are stored exactly (62.5% is 62.5%, never a rounded approximation), so the run ties to the cent.

Closing the month

The Month end view answers: can this school close its month from its own records? Three numbers:

Under the liability is its movement: opening balance + issued − used − expired = closing balance. The residual line should always read zero. If it ever doesn't, the report itself is broken and you should say so — the system shows the discrepancy rather than hiding it.

The iPhone app — reference

When something looks wrong

The words this system uses