Docs / Technical / Course modification
Course modification: the complete map.
Every object of a course is written by one of three means: the learner edits it directly, an AI generation writes it, or a deterministic algorithm computes it. No object influences another without passing through a mechanism that reads some objects as context. This page is the exhaustive reference, verified against the engine source.
Object × means.
Who is allowed to write each state object. Several objects have more than one writer (the plan can be hand-edited, or re-drafted by three AI mechanisms).
| Object | Direct edit | AI generation | Deterministic | Status |
|---|---|---|---|---|
| Brief | updateSkillDescription | · | · | |
| Competency | updateSkillCompetency / createSkill (ratified in the wizard) | restate_competency / preview_competency | · | |
| Objective + dimensions | · | classify_objective | · | read-only |
| Learner notes | setSkillLearnerNotes | · | · | |
| Schedule | updateSkillSchedule | · | feeds planner | |
| Parameters | setSkill* | · | · | |
| Sources | addSource / deleteSource | · | · | |
| Placement summary | · | generate_placement | · | produced |
| Plan | updatePlan | generate_plan propose_plan_edit generate_graph | · | |
| Structure (sections + LPs) | via plan | · | compute_session_plan | |
| Concept type | setSkillNodeClass | · | · | |
| Graph edges | add/removeSkillGraphEdge | generate_graph | sanitize_edges | |
| Section content | saveCourseSectionEdit | generate_course_section revise / request_revision | · | |
| Glossary | · | insert_terms | · | read-only |
| Project | · | generate_project update_module_project | · | |
| Sessions | · | generate_session | compute_session_plan compose_*_lps | |
| Exercises + questions | applyExercisePatch | generate_session | PED-32 grid, term-games | detail |
| Attempts | regradeAttempt addAttemptExplanation | LLM judge | deterministic grading | |
| Mastery / FSRS | via regrade | · | mastery::update | |
| Lifecycle / maintenance | · | · | maintenance_tick | not wired |
Read-models (never written, recomputed on demand): frontier states (available / locked / mastered / fading), mastery bands, retention forecast, retention targets, feasibility report, maintenance selection, cadence.
Exact context per generation.
What each AI mechanism actually reads. There is no shared context assembler: each builds its own prompt.
| Mechanism | Resources injected | Writes | Sources? |
|---|---|---|---|
| generate_plan | brief (parsed) · competency · objective + dimensions (if performance) · placement summary · params | plan → planner | yes |
| generate_graph | brief (raw) · competency · placement summary | plan → planner | no |
| generate_course_section | learning points (Bloom) · prior sections · plan structure · forward-refs · banked terms · brief · competency · register | new section version + glossary terms | yes |
| revise_course_section struggle | prior state · weak points + accumulated misconceptions · + generation context | version (in place) | yes |
| request_course_section_revision request | prior state · latest request only · + generation context | version (in place) | yes |
| propose_plan_edit | current plan · competency · performance summary · accumulated remarks (max 5 threads) · request (opt.) | proposal (client diff) | no |
| generate_session | competency · notes · register · target points + live retention state · teaching content · review queue · exercise grid · the glossary, grouped by concept | exercises, questions | no |
| generate_project | full plan · brief | project brief | no |
| update_module_project | module section · per-point mastery | project section | no |
| generate_placement | brief (depth / goal / prior knowledge) | placement summary | yes |
| restate_competency / preview_competency / classify_objective | title · brief goal · depth | competency, objective type | no |
Everything that enters and leaves.
The table above reads by mechanism. This one reads by object: what goes into a course and into one exercise session, and what comes out. Verified against the engine source. The last block is the part that is stored and not read yet, which is the honest half.
Into a course
| What | Where it comes from | What reads it |
|---|---|---|
| Brief | you, at capture: goal, depth, prior knowledge, time per session, level | plan, concept graph, placement, every section |
| Competency restatement | restate_competency | plan, graph, section, plan edit |
| Objective type + dimensions | classify_objective | the plan, when the objective is a performance |
| Placement summary | generate_placement | plan and graph |
| Sources | you | plan, section, placement. Not graph, not project |
| Your remarks | you, as threads | plan revision only, five most recent threads |
| Misconceptions | grading, from your attempts | section revision, and one exercise slot per session |
| Retention state | the retention engine | session composition, section revision, project update |
Out of a course
| What | Written by | Lifetime |
|---|---|---|
| Plan | generate_plan or generate_graph, then the deterministic planner | replaced on replanning |
| Concepts | the planner | one per concept, each with its cognitive level |
| Concept graph | generate_graph | prerequisite edges |
| Section versions | generate_course_section | versioned, revisions rewrite in place |
| Glossary terms | section generation only, one insert-or-ignore per lesson | durable: only ever added to, never deleted |
| Project brief | generate_project, then per-module updates | one per course |
Into one exercise session
| What | Detail |
|---|---|
| Live retention state | per target concept: mastery, repetitions, lapses, interval, next review |
| The grid's slots | concept, cognitive tier, allowed exercise types, scaffold rung, transfer probe |
| The glossary, grouped by concept | a slot the glossary can cover is authored locally and never reaches the model |
| Teaching content | the sections the session targets |
| Review queue | what is due, most overdue first |
| Competency, notes, register | so the wording matches the course |
| Open misconceptions | one extra slot, its type forced to true or false |
Out of one exercise session
| What | Detail | Lifetime |
|---|---|---|
| Exercises and questions | the authored items | ephemeral: deleted and rewritten every session |
| One attempt row per answer | your answer, the score, the feedback, your confidence rating, any misconception named, whether the item was new to you | kept |
| The retention update | mastery, repetitions, lapses, lapses since last success, interval, last and next review, stability, difficulty, first-success flag, transfer flag | kept |
Stored, and read by nothing yet
- Whether you took a hint. The card offers hints one rung at a time and, after a miss, a second attempt. That second attempt travels marked as assisted, and the marker is dropped at the API boundary: the attempt row has no column for it. An answer found with a hint and an answer found alone are stored identically.
- The scaffold rung. The grid decides whether an exercise arrives worked through, partly faded, or unaided. The grading code does not read that back, so the retention model is billed the same either way.
- Three of the glossary's own columns. Accepted synonyms, the extra field (part of speech, gloss, translation) and the marker saying whether a term came from the AI or from you are all stored and read by no generator.
- Threads on a section, an exercise or an attempt. Stored, but only the threads on the plan are read back into a generation.
- Per-term retention. A glossary term is scheduled through its concept, not on its own. A term you know well and one you keep missing come back at the same time.
The three data-flows.
Dotted green = a resource read as context · solid ember = a mechanism writes its object · solid blue = a deterministic algorithm · thick ember (flow 2) = a direct edit by the learner.
Brief → competency → plan (or concept graph) → the deterministic planner → sections, learning points. Sources feed plan, section and placement, but not graph or project.
Three gestures: direct edit, trigger a mechanism, and the context it reads. A revision regenerates in place: the prior state is always re-injected.
Planner → sessions → exercises → your attempts → the retention engine (FSRS) → mastery, which feeds session generation, section revision and maintenance.
The accumulation asymmetry
Revising the plan re-injects your accumulated remarks (up to 5 recent threads). Revising a section does not read your threads. Its accumulated channel is the misconceptions from your attempts, and a typed revision request uses only your latest message.
Notes & open points.
- Remarks accumulate only for the plan. The thread digest is read at exactly one place; section / exercise / attempt threads are stored but no generation reads them back today.
- Two objects are read-only. Objective (type + dimensions) and the glossary have no write command yet, so the learner sees but cannot correct them.
- Regrading writes learning state. Correcting a grade rewrites the score and replays the retention model for that concept, a rare lever where the learner writes mastery directly.
- Deterministic where it counts. Scheduling, review selection, the exercise grid and most grading are pure computation, not AI: the AI authors content into slots the engine has already chosen.
- Session generation has its own reference. The grid that fixes the exercise set (its six stages, every calibration constant, the prompt it assembles and its known gaps) is documented in the session engine page.