NTT-learning/AGENT_CONTEXT.md

# Agent Context

  This file exists so a restarted coding agent can get up to speed quickly in `NTT-learning` without relying on vanished session memory.

  ## Project Identity

  - Project: `NTT-learning`
  - Directory: `/Users/oho/GitClone/CodexProjects/NTT-learning`
  - Goal: build a local-first, notebook-first learning platform for understanding the Number Theoretic Transform in the context of Kyber, with special focus on:
    - forward NTT
    - inverse NTT
    - butterfly structure
    - Cooley-Tukey vs Gentleman-Sande / Sande-style inverse flow
    - layer-by-layer data movement
    - how the algorithm actually plays out in arrays
  - The project should follow the same high standard as `QuantumLearning` in pedagogy, guardrails, notebook design, testing, and local operations.

  ## Core Teaching Judgement

  This topic is confusing because most explanations blur together three different things:

  1. the algebraic purpose of NTT
  2. the in-place butterfly dataflow
  3. the Kyber-specific implementation conventions

  The course must separate those cleanly.

  A learner should not be forced to jump straight into Kyber’s real implementation. The correct staircase is:

  1. ordinary polynomial multiplication / convolution
  2. negacyclic multiplication
  3. tiny toy NTT with very small `n`
  4. butterfly mechanics in isolation
  5. forward vs inverse flow side by side
  6. only then Kyber-specific parameters and indexing
  7. only then the real implementation patterns

  ## Official Course Contract

  The project must have one supported end-to-end walkthrough only.

  Inside notebooks, the visible cell contract must be explicit:

  - `META` cells are route/objective/pacing guidance
  - `MANDATORY` cells are the official walkthrough
  - `FACULTATIVE` cells are optional extensions only

  Difficulty scheme:

  - difficulty `1-3` is reserved for mandatory cells
  - difficulty `4-10` is reserved for facultative cells

  Route notebooks must remain pure route notebooks:
  - they must not contain facultative detours
  - they must not confuse meta-level guidance with technical payload

  Hide plumbing where possible:
  - if widgets are used, learners should see the pedagogical surface, not raw helper code unless that code is itself the lesson

  ## Pedagogical Style

  The strongest style is notebook-first, small-step, highly visual, and highly inspectable.

  Every major concept should be taught through:
  - careful lecture-style explanation
  - array-state snapshots
  - editable examples
  - multiple-choice retrieval checks
  - written reflection prompts
  - “predict the next layer before running it” moments

  The learner must be able to watch:
  - inputs
  - current layer
  - twiddle factor / zeta use
  - pairings
  - outputs after one butterfly stage

  This topic especially needs:
  - explicit diagrams of pairings
  - side-by-side tables of array values after each stage
  - bit-reversal explained visually, not only verbally
  - forward and inverse diagrams compared directly
  - “same structure, opposite direction” intuition for inverse flow

  ## Topic-Specific Judgement

  The course should make clear that Kyber is not just “a generic FFT story with modular arithmetic”.

  The learner must understand:
  - why polynomial multiplication matters
  - why negacyclic structure matters
  - what the transform is buying
  - why Kyber’s parameter choices shape the exact construction
  - what butterflies do locally
  - how local butterfly operations produce the global transform
  - why inverse butterflies undo the forward structure
  - where scaling enters
  - how base multiplication fits between NTT and inverse NTT

  The course must distinguish carefully between:
  - mathematical NTT definition
  - implementation-oriented in-place iterative NTT
  - Kyber’s specific indexing / ordering / twiddle schedule

  ## Proposed Curriculum Spine

  The likely notebook architecture should look like this:

  1. `START_HERE.ipynb`
  2. `COURSE_BLUEPRINT.ipynb`

  Then technical bundles such as:

  ### Foundations
  - polynomial multiplication and convolution
  - negacyclic rings and why Kyber uses them
  - modular arithmetic and roots of unity
  - toy NTT with tiny examples

  ### Butterfly Mechanics
  - what one butterfly does
  - forward Cooley-Tukey butterfly
  - inverse Gentleman-Sande butterfly
  - layer-by-layer traces
  - bit-reversal and ordering

  ### Kyber Mapping
  - Kyber parameters
  - Kyber forward NTT
  - Kyber base multiplication
  - Kyber inverse NTT
  - implementation reading studio

  ### Professional / Debugging
  - common misconceptions
  - debugging wrong twiddle/sign/index mistakes
  - hand-tracing selected stages
  - implementation critique and validation

  Each serious module should follow the same bundle style used successfully elsewhere:

  - `lecture.ipynb`
  - `lab.ipynb`
  - `problems.ipynb`
  - `studio.ipynb`

  ## Operational Expectations

  The repo should be self-service for a normal user.

  Provide repo-local operations such as:
  - bootstrap
  - start
  - stop
  - restart
  - status
  - reset-state
  - validate

  Use a repo-local `.venv`.

  Prefer:
  - local Jupyter
  - bash-first commands
  - repo-local config and runtime files
  - no Docker
  - no cloud dependency
  - no IDE-specific assumptions

  ## Validation Expectations

  The project should include:

  - curriculum / route tests
  - pedagogy tests
  - notebook execution tests
  - browser UX tests where practical
  - repo-local operational docs

  The notebooks should be tested not only for existence, but also for:
  - route consistency
  - required labels
  - mandatory/facultative separation
  - presence of quizzes / exercises / reflections where appropriate
  - visible next-notebook handoff

  ## Immediate Build Priorities

  When starting from an empty repo, do this first:

  1. inspect repo state
  2. create `.venv`
  3. create package / notebook / test / config skeleton
  4. create consumer-facing operational scripts
  5. create the course backbone and route guardrails
  6. build the first serious module around toy convolution and toy butterflies
  7. only then expand to Kyber-specific notebooks

  Do not start by dumping advanced Kyber code into notebooks.

  ## What To Avoid

  Do not:
  - create multiple competing learner routes
  - mix meta guidance with technical payload without clear labels
  - introduce facultative cells into route notebooks
  - overuse abstraction before a learner has seen concrete arrays move
  - assume the learner can infer butterfly flow from equations alone
  - rely on “trust me, this is just FFT-like” explanations

  ## Recommended First Reads For A Restarted Agent

  If a coding agent restarts in this repo, it should:

  1. read this file first
  2. inspect `git status --short --branch`
  3. inspect `git log --oneline -5`
  4. inspect the repo tree
  5. summarize current state and immediate build plan
  6. then execute

  ## One-Line Restart Prompt

  Use this after restarting an agent in this repo:

  `Read AGENT_CONTEXT.md first. Then inspect git status and the repo tree, summarize the current state and constraints, and only then continue the build.`