From 9b9bfdb39c57bbf0ecf186ca1987bdc85e23e81b Mon Sep 17 00:00:00 2001
From: Aron T <aront@fourm.info>
Date: Tue, 10 Feb 2026 18:36:19 +0200
Subject: [PATCH 1/3] refactor: split copilot-instructions into contextual
 instruction files

Move domain-specific instructions into .github/instructions/ with applyTo
front matter so they load only when editing relevant files:

- docs.instructions.md (docs/**): LaTeX conventions, MathWorld links, doc structure
- testing.instructions.md (test/**): CI strategy, plotting patterns, test organization
- source.instructions.md (src/**): module structure, coding standards, function signatures, dependencies
- notebooks.instructions.md (notebooks/**): notebook setup and guidelines

Main copilot-instructions.md trimmed from 394 to 126 lines, keeping only
universal content: project overview, workflows, git/PR conventions,
communication patterns, Azure integration.
---
 .github/copilot-instructions.md               | 282 +-----------------
 .github/instructions/docs.instructions.md     |  97 ++++++
 .../instructions/notebooks.instructions.md    |  29 ++
 .github/instructions/source.instructions.md   | 134 +++++++++
 .github/instructions/testing.instructions.md  |  96 ++++++
 5 files changed, 363 insertions(+), 275 deletions(-)
 create mode 100644 .github/instructions/docs.instructions.md
 create mode 100644 .github/instructions/notebooks.instructions.md
 create mode 100644 .github/instructions/source.instructions.md
 create mode 100644 .github/instructions/testing.instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 98994b4..fb2dbdc 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,5 +1,7 @@
 # Copilot Instructions for Math_Foundations
 
+> **Note:** Context-specific instructions (docs, testing, source, notebooks) are in `.github/instructions/` and load automatically based on the file being edited.
+
 ## Project Overview
 
 **Julia basic maths project** using DrWatson for reproducibility. Implements mathematical foundations (algebra, geometry, trigonometry) with visualization, comprehensive testing, and cross-repository documentation deployment.
@@ -12,166 +14,6 @@
 - **`docs/`**: Documenter.jl deploying to `https://study.fourm.info/math_foundations/` (cross-repo to `math_tech_study`)
 - **`notebooks/`**: Jupyter notebooks for exploration (not tested in CI)
 
-## Critical Development Patterns
-
-### Module Structure & Exports
-
-All code uses `@reexport` pattern and exports both computational + plotting functions:
-
-```julia
-# Main module uses @reexport for clean interface
-using Reexport
-@reexport using Symbolics, Nemo, Plots, Latexify, LaTeXStrings, Dates, AMRVW, Polynomials
-
-# Comprehensive exports for all functions
-# Pure computational functions (no plotting dependencies)
-export calculate_parabola_roots_quadratic, calculate_parabola_roots_polynomial, calculate_parabola_roots_amrvw
-
-# Integrated plotting functions (computation + visualization)
-export plot_parabola_roots_quadratic, plot_hyperbola, plot_hyperbola_axes_direct
-
-# Always export new functions in main module
-```
-
-### Automatic CI/Interactive Detection
-
-Module auto-configures at load time - no manual intervention needed:
-
-```julia
-# src/Math_Foundations.jl - Runs on module load
-if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
-    ENV["GKSwstype"] = "100"  # Headless plotting
-    gr(show=false)
-else
-    gr()  # Interactive plotting
-end
-```
-
-## Testing Strategy (CI-Compatible)
-
-### Three-Layer Testing Approach
-
-**1. Module-Level Detection** - Automatic (in `Math_Foundations.jl`):
-```julia
-if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
-    ENV["GKSwstype"] = "100"
-    gr(show=false)
-end
-```
-
-**2. Test-Level Configuration** - Manual (in `runtests.jl`):
-```julia
-ENV["GKSwstype"] = "100"  # Set BEFORE using Math_Foundations
-using DrWatson, Test
-@quickactivate "Math_Foundations"
-using Math_Foundations
-```
-
-**3. Separated Logic** - Design pattern for all new functions:
-
-- **Computational functions** (`calculate_*`): Pure math, no plotting, test directly
-- **Plotting functions** (`plot_*`): Computation + visualization, test with try-catch
-- **Pattern Example**:
-
-```julia
-# src/basic_maths.jl
-function calculate_parabola_roots_quadratic(a₂, a₁=0.0, a₀=0.0)
-    discriminant = a₁^2 - 4 * a₂ * a₀
-    root1 = (-a₁ + sqrt(Complex(discriminant))) / (2 * a₂)
-    root2 = (-a₁ - sqrt(Complex(discriminant))) / (2 * a₂)
-    return [root1, root2]  # Always returns ComplexF64
-end
-
-function plot_parabola_roots_quadratic(a₂, a₁=0.0, a₀=0.0)
-    all_roots = calculate_parabola_roots_quadratic(a₂, a₁, a₀)  # Math always succeeds
-    try
-        @variables x
-        f = a₂ * x^2 + a₁ * x + a₀
-        plot_parabola(f, all_roots, a₂, a₁, a₀, "Quadratic")
-    catch e
-        !haskey(ENV, "CI") && @warn "Plotting failed: $e"
-    end
-    return [real(r) for r in all_roots if abs(imag(r)) < 1e-10]  # Real roots only
-end
-```
-
-### Testing Pattern
-
-```julia
-# test/test_basic_maths.jl
-@testset "Computational Tests" begin
-    # NO try-catch - math errors should fail
-    roots = calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)
-    @test length(roots) == 2
-    @test typeof(roots) == Vector{ComplexF64}
-end
-
-@testset "Integration Tests" begin
-    # try-catch for CI-safe plotting
-    try
-        result = plot_parabola_roots_quadratic(1.0, 0.0, -4.0)
-        @test typeof(result) == Vector{Float64}  # Real roots
-    catch e
-        @test hasmethod(plot_parabola_roots_quadratic, (Float64, Float64, Float64))
-        @test typeof(calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)) == Vector{ComplexF64}
-    end
-end
-```
-
-### Plotting Conventions
-
-- All plots auto-save: `"plots/" * Dates.format(now(),"yyyymmdd-HHMMSS") * "functionname.png"`
-- Ensure `plots/` directory exists before running tests
-- Use LaTeX titles: `title!(L"Plot\ of\ %$a₂ * x^2 + %$a₁ * x + %$a₀\\")`
-
-## Coding Standards
-
-### Mathematical Functions
-
-- Use Unicode symbols for coefficients: `a₂, a₁, a₀` (type `a\\_2<tab>` in Julia)
-- Return `ComplexF64` for roots (even if imaginary part is zero)
-- Handle negative numbers correctly (see `nth_root` - odd roots return negative reals, even roots return complex)
-- Always export new functions in `src/Math_Foundations.jl`
-- Follow pattern: `calculate_*` (pure math) + `plot_*` (integrated)
-
-### Testing Requirements
-
-- **@testset structure**: Group tests by function (54 total tests across all functions)
-- **No try-catch for math**: Computational tests should fail on mathematical errors
-- **try-catch for plots**: Only use for CI-safe visualization testing
-- **Edge cases**: Test positive/negative, zero, special values
-- Use `@test_throws` for expected errors, `@test_broken` for known failures
-
-### Documentation Standards
-
-- **Docstrings**: Required for all exported functions with signature and description
-- **LaTeX math**: Use for equations in docs and plot titles
-- **MathWorld links**: Add for new mathematical concepts (verify URL before adding)
-- **Markdown docs**: Files in `docs/src/` organized by topic (Algebra, Geometry, Trigonometry)
-- **Examples**: Include in docstrings showing typical usage
-
-## Dependencies & Libraries
-
-**Heavy Dependencies**: Nemo (~500MB), GLMakie, WGLMakie (main Project.toml)
-**Optimized Tests**: Minimal dependencies in `test/Project.toml` for CI speed
-
-### Key Mathematical Libraries
-
-- **Symbolics.jl**: Symbolic variables (`@variables x`) for equation manipulation
-  - Create variables: `@variables x; f = a₂*x^2 + a₁*x + a₀`
-  - Simplify expressions: `simplify(expr, expand=true)`
-  - **Extract numeric values** (two methods):
-    1. **substitute + value**: `substitute(expr, x => π/4; fold=Val(true))` then `Symbolics.value(result)`
-    2. **build_function**: `f = build_function(expr, x, expression=Val{false})` creates callable Julia function
-  - Use `fold=Val(true)` with substitute to simplify after substitution
-  - Use `expression=Val{false}` with build_function to avoid eval requirement
-- **Polynomials.jl**: Polynomial operations and root finding
-  - Create: `p = Polynomial([a₀, a₁, a₂])`
-  - Solve: `roots(p)`
-- **AMRVW.jl**: Alternative root finding: `AMRVW.roots([a₀, a₁, a₂])`
-- **Nemo.jl**: Number theory (verify usage patterns before adding new tests)
-- **Plots.jl/GR**: Plotting with automatic CI headless mode
-
 ## Key Workflows
 
 ### Local Development
@@ -187,21 +29,15 @@ CI=true julia --project=. test/runtests.jl
 julia --project=. docs/make.jl
 ```
 
+**IMPORTANT**: Always run `julia --project=. docs/make.jl` after making changes to documentation files in `docs/src/`. This allows the user to preview changes in the browser immediately without running the build manually.
+
 ## Julia Compilation Considerations
-- **Be Patient with First Runs**: Julia often needs to precompile packages and rebuild project cache on first run. when running a Julia command in the CLI for the first time, it may take a while to precompile the packages and build the project cache, so you won't see the results of running the command for a while.
+- **Be Patient with First Runs**: Julia often needs to precompile packages and rebuild project cache on first run. When running a Julia command in the CLI for the first time, it may take a while to precompile the packages and build the project cache, so you won't see the results of running the command for a while.
 - **Typical First Run**: May take 15-30 seconds for precompilation before tests actually start
 - **Example Expected Output**: `Precompiling DrWatson... 3 dependencies successfully precompiled in 17 seconds`
 - **Subsequent Runs**: Much faster once cache is built
 - **Don't Cancel Early**: Allow time for compilation phase to complete
 - **IMPORTANT**: This applies to ALL Julia commands including CI testing with `CI=true julia --project=. test/runtests.jl`
-- 
-### CI/CD Pipeline
-
-- **Tests**: Run on all PRs (`.github/workflows/CI.yml`)
-- **Docs Build**: Test on PR (no deploy)
-- **Docs Deploy**: Auto-deploy to `https://study.fourm.info/math_foundations/` on merge to `main`
-- **Cross-Repo**: Deploys to `FourMInfo/math_tech_study` subdirectory
-- **Prerequisites**: `plots/` directory must exist for tests to pass
 
 ## Git Best Practices
 
@@ -238,115 +74,11 @@ Your comprehensive PR description with:
 - Testing completed
 - Related issues
 ```
+
 ## Azure Integration
 
 - Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `azure_development-get_best_practices` tool if available
 
-## Project-Specific Conventions
-
-- **DrWatson Integration**: Use `projectdir()`, `srcdir()` for paths (except in tests)
-- **Mathematical Notation**: Use Unicode symbols (a₂, a₁, a₀) in function parameters
-- **Test Organization**: Group tests by function with comprehensive edge cases (54+ tests)
-- **Documentation**: Use LaTeX math notation with Latexify.jl integration
-
-## Function Signature Patterns
-
-### Mathematical Functions
-```julia
-nth_root(x, n) -> Number                  # Returns complex for even roots of negative numbers
-```
-
-### Plotting Functions  
-```julia
-plot_parabola_roots_amrvw(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
-plot_parabola_roots_polynomial(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
-plot_parabola_roots_quadratic(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
-plot_hyperbola(a::Float64=1.0, h::Float64=0.0, k::Float64=0.0) -> Plot
-plot_hyperbola_axes_varx(a::Float64, b::Float64) -> Plot
-plot_hyperbola_axes_direct(a::Float64, b::Float64) -> Plot
-```
-
-### Financial Functions
-```julia
-accrued_apr(i::Real, p::Real, c::Int64) -> Float64
-accrued(i::Real, p::Real, c::Int64) -> Float64
-```
-
-### Geometric Functions
-```julia
-triangle_area_perim(a::Float64, b::Float64, c::Float64) -> Tuple{Float64, Float64}
-```
-
-## Documentation Patterns
-
-### Structure for Mathematical Concept Documentation
-
-Documentation in `docs/src/` explains general math concepts (not code). Follow these patterns:
-
-**Document Organization:**
-- Start with concept overview and [MathWorld](https://mathworld.wolfram.com/) link in opening paragraph
-- Use hierarchical headings: `##` for major topics, `###` for subtopics
-- Group related concepts (e.g., "By Side Length", "By Angle Measure")
-- Include real-world applications section
-
-**Content Style:**
-- **Definitions first**: Clear, precise mathematical definitions with MathWorld links
-- **Build progressively**: Simple concepts → complex relationships → applications
-- **Multiple representations**: Equations, tables, visual aids (SVG diagrams when helpful)
-- **Context matters**: Explain _why_ concepts are important, not just _what_ they are
-  - Example: "Arc length is crucial for engineering, navigation, physics..."
-- **Derivations**: Show mathematical reasoning step-by-step (see Hyperbola derivation)
-
-**Mathematical Notation:**
-- Use LaTeX: `$$` for display equations, inline with `$...$`
-- **CRITICAL**: `$$` display blocks in Documenter.jl must have `$$` directly attached to content (no blank lines or return after opening or before closing)
-  - ✅ **CORRECT** (multi-line aligned block):
-    ```
-    $$\begin{aligned}
-    b &= a\sqrt{1-e^2} \\
-    c &= ae \\
-    a^2 &= b^2 + c^2
-    \end{aligned}$$
-    ```
-  - ✅ **CORRECT** (single equation): `$$equation$$`
-  - ❌ **WRONG** (blank lines or return between `$$` and content):
-    ```
-    $$
-
-    content
-
-    $$
-    ```
-- **Bullet point style**: List items starting with `-` must begin with text, then LaTeX math
-  - ✅ **CORRECT**: `- The semi-major axis is $a$`
-  - ❌ **WRONG**: `- $a$ is the semi-major axis`
-- **Equation placement style**: Prefer inline equations with "where:" at end of sentence, followed by list
-  - ✅ **CORRECT**: `For an ellipse: $\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1$ where:`
-  - ❌ **AVOID**: Blank line, then equation block, then blank line, then "where:"
-- LaTeX syntax for symbols: `^\circ` not `°`, `\frac{}{}` for fractions
-- Label variables clearly: "where: $r$ = radius, $θ$ = angle"
-- Use aligned equations: `\begin{aligned}...\end{aligned}` for multi-step derivations
-- **Square brackets in LaTeX math**: Use `\lbrack` and `\rbrack` instead of `[` and `]` inside math expressions to avoid markdown link interpretation errors
-  - ✅ **CORRECT**: `$\mathbf{v} = \lbrack v_1, v_2 \rbrack$`
-  - ❌ **WRONG**: `$\mathbf{v} = [v_1, v_2]$` (markdown interprets `[v_1, v_2]` as a link)
-
-**MathWorld Links:**
-- Link every new mathematical term on first mention
-- Format: `[Term](https://mathworld.wolfram.com/Term.html)`
-- Verify URLs before adding (use fetch_webpage)
-- Compare multiple URLs to choose most appropriate
-
-**Visual Elements:**
-- SVG diagrams for geometric concepts (see Triangles, Polygons)
-- Tables for reference data (degree/radian conversions, common values)
-- Consistent styling in diagrams (colors, labels, annotations)
-
-**Markdown Conventions:**
-- _Underscore_ for emphasis (not asterisk)
-- **Bold** for important terms and section labels
-- Fix all linting issues after editing (except config files)
-- Code blocks with language tags: ````julia` for Julia examples  
-
 ## Communication Patterns
 
 - Avoid being overly obsequious in responses
@@ -391,4 +123,4 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
     - Discuss any relevant factors considered in the decision-making process
 - When discussing project goals or objectives, ensure they are clearly defined and measurable
 - If you need to prioritize tasks or features, clearly explain the reasoning behind the prioritization
-    - Discuss how priorities align with project goals and timelines
\ No newline at end of file
+    - Discuss how priorities align with project goals and timelines
diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md
new file mode 100644
index 0000000..d6b1fe8
--- /dev/null
+++ b/.github/instructions/docs.instructions.md
@@ -0,0 +1,97 @@
+---
+applyTo: 'docs/**'
+---
+# Documentation Conventions
+
+## Structure for Mathematical Concept Documentation
+
+Documentation in `docs/src/` explains general math concepts (not code). Follow these patterns:
+
+**Document Organization:**
+- Start with concept overview and [MathWorld](https://mathworld.wolfram.com/) link in opening paragraph
+- Use hierarchical headings: `##` for major topics, `###` for subtopics
+- Group related concepts (e.g., "By Side Length", "By Angle Measure")
+- Include real-world applications section
+
+**Content Style:**
+- **Definitions first**: Clear, precise mathematical definitions with MathWorld links
+- **Define before use**: All terms must be defined before they are used elsewhere in the document. This principle drives the order and structure of sections—ensure logical progression where each concept builds only on previously defined terms.
+- **Build progressively**: Simple concepts → complex relationships → applications
+- **Multiple representations**: Equations, tables, visual aids (SVG diagrams when helpful)
+- **Context matters**: Explain _why_ concepts are important, not just _what_ they are
+  - Example: "Arc length is crucial for engineering, navigation, physics..."
+- **Derivations**: Show mathematical reasoning step-by-step (see Hyperbola derivation)
+
+## Mathematical Notation
+
+- Use LaTeX: `$$` for display equations, inline with `$...$`
+- **CRITICAL**: `$$` display blocks in Documenter.jl must have `$$` directly attached to content (no blank lines or return after opening or before closing)
+  - ✅ **CORRECT** (multi-line aligned block):
+    ```
+    $$\begin{aligned}
+    b &= a\sqrt{1-e^2} \\
+    c &= ae \\
+    a^2 &= b^2 + c^2
+    \end{aligned}$$
+    ```
+  - ✅ **CORRECT** (single equation): `$$equation$$`
+  - ❌ **WRONG** (blank lines or return between `$$` and content):
+    ```
+    $$
+
+    content
+
+    $$
+    ```
+- **Bullet point style**: List items starting with `-` must begin with **text**, then LaTeX math. LaTeX commands immediately after `-` render incorrectly (misaligned or broken formatting)
+  - ✅ **CORRECT**: `- The semi-major axis is $a$`
+  - ❌ **WRONG**: `- $a$ is the semi-major axis` (LaTeX immediately after dash)
+- **Equation placement style**: Prefer inline equations with "where:" at end of sentence, followed by list
+  - ✅ **CORRECT**: `For an ellipse: $\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1$ where:`
+  - ❌ **AVOID**: Blank line, then equation block, then blank line, then "where:"
+- LaTeX syntax for symbols: `^\circ` not `°`, `\frac{}{}` for fractions
+- Label variables clearly: "where: $r$ = radius, $θ$ = angle"
+- Use aligned equations: `\begin{aligned}...\end{aligned}` for multi-step derivations
+- **Square brackets in LaTeX math**: Use `\lbrack` and `\rbrack` instead of `[` and `]` inside math expressions to avoid markdown link interpretation errors
+  - ✅ **CORRECT**: `$\mathbf{v} = \lbrack v_1, v_2 \rbrack$`
+  - ❌ **WRONG**: `$\mathbf{v} = [v_1, v_2]$` (markdown interprets `[v_1, v_2]` as a link)
+- **Absolute value notation**: Use `\lvert` and `\rvert` instead of `|` to avoid markdown pipe interpretation
+  - ✅ **CORRECT**: `$\lvert c \rvert > 1$`
+  - ❌ **WRONG**: `$|c| > 1$` (pipe may be interpreted as table delimiter)
+
+## MathWorld Links
+
+- Link every new mathematical term on first mention
+- Format: `[Term](https://mathworld.wolfram.com/Term.html)`
+- Verify URLs before adding (use fetch_webpage)
+- Compare multiple URLs to choose most appropriate
+
+## Visual Elements
+
+- SVG diagrams for geometric concepts (see Triangles, Polygons)
+- Tables for reference data (degree/radian conversions, common values)
+- Consistent styling in diagrams (colors, labels, annotations)
+
+## Markdown Conventions
+
+- _Underscore_ for emphasis (not asterisk)
+- **Bold** for important terms and section labels
+- Fix all linting issues after editing (except config files)
+- Code blocks with language tags: ````julia` for Julia examples
+
+## Documentation Structure
+
+- **Topics**: Organized by Algebra, Geometry, Trigonometry in `docs/src/`
+- **Cross-Repository Deployment**: Deploys to `FourMInfo/math_tech_study` repository
+- **URL**: Available at `https://study.fourm.info/math_foundations/`
+- **Docstrings**: Required for all exported functions with signature and description
+- **Examples**: Include in docstrings showing typical usage
+- **LaTeX math**: Use Latexify.jl integration for equations in docs and plot titles
+
+## Building Documentation
+
+```bash
+julia --project=. docs/make.jl
+```
+
+**IMPORTANT**: Always run `julia --project=. docs/make.jl` after making changes to documentation files in `docs/src/`. This allows the user to preview changes in the browser immediately without running the build manually.
diff --git a/.github/instructions/notebooks.instructions.md b/.github/instructions/notebooks.instructions.md
new file mode 100644
index 0000000..30a3ebc
--- /dev/null
+++ b/.github/instructions/notebooks.instructions.md
@@ -0,0 +1,29 @@
+---
+applyTo: 'notebooks/**'
+---
+# Notebook Conventions
+
+## Setup Pattern
+
+All notebooks should start with the standard DrWatson activation:
+
+```julia
+using Revise
+using DrWatson
+quickactivate(@__DIR__, "Math_Foundations")
+using Math_Foundations
+```
+
+## Notebook Guidelines
+
+- Notebooks are for exploration and study, not tested in CI
+- Use `println()` for output to make results clear when re-running cells
+- Include explanatory markdown cells between code cells
+- Use Unicode variable names consistent with the source code (e.g., `a₂`, `a₁`, `a₀`)
+- Reference the documentation sections being studied
+
+## Plotting in Notebooks
+
+- Plots render inline in Jupyter notebooks
+- No need for headless mode configuration
+- Use the same plotting functions from the package (`plot_parabola_roots_quadratic`, `plot_hyperbola`, etc.)
diff --git a/.github/instructions/source.instructions.md b/.github/instructions/source.instructions.md
new file mode 100644
index 0000000..e018cb8
--- /dev/null
+++ b/.github/instructions/source.instructions.md
@@ -0,0 +1,134 @@
+---
+applyTo: 'src/**'
+---
+# Source Code Conventions
+
+## Module Structure & Exports
+
+All code uses `@reexport` pattern and exports both computational + plotting functions:
+
+```julia
+# Main module uses @reexport for clean interface
+using Reexport
+@reexport using Symbolics, Nemo, Plots, Latexify, LaTeXStrings, Dates, AMRVW, Polynomials
+
+# Comprehensive exports for all functions
+# Pure computational functions (no plotting dependencies)
+export calculate_parabola_roots_quadratic, calculate_parabola_roots_polynomial, calculate_parabola_roots_amrvw
+
+# Integrated plotting functions (computation + visualization)
+export plot_parabola_roots_quadratic, plot_hyperbola, plot_hyperbola_axes_direct
+
+# Always export new functions in main module
+```
+
+## Automatic CI/Interactive Detection
+
+Module auto-configures at load time — no manual intervention needed:
+
+```julia
+# src/Math_Foundations.jl - Runs on module load
+if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
+    ENV["GKSwstype"] = "100"  # Headless plotting
+    gr(show=false)
+else
+    gr()  # Interactive plotting
+end
+```
+
+## Coding Standards
+
+### Mathematical Functions
+
+- Use Unicode symbols for coefficients: `a₂, a₁, a₀` (type `a\_2<tab>` in Julia)
+- Return `ComplexF64` for roots (even if imaginary part is zero)
+- Handle negative numbers correctly (see `nth_root` — odd roots return negative reals, even roots return complex)
+- Always export new functions in `src/Math_Foundations.jl`
+- Follow pattern: `calculate_*` (pure math) + `plot_*` (integrated)
+
+### Function Design Pattern
+
+```julia
+# Pure computational function
+function calculate_parabola_roots_quadratic(a₂, a₁=0.0, a₀=0.0)
+    discriminant = a₁^2 - 4 * a₂ * a₀
+    root1 = (-a₁ + sqrt(Complex(discriminant))) / (2 * a₂)
+    root2 = (-a₁ - sqrt(Complex(discriminant))) / (2 * a₂)
+    return [root1, root2]  # Always returns ComplexF64
+end
+
+# Integrated plotting function
+function plot_parabola_roots_quadratic(a₂, a₁=0.0, a₀=0.0)
+    all_roots = calculate_parabola_roots_quadratic(a₂, a₁, a₀)
+    try
+        @variables x
+        f = a₂ * x^2 + a₁ * x + a₀
+        plot_parabola(f, all_roots, a₂, a₁, a₀, "Quadratic")
+    catch e
+        !haskey(ENV, "CI") && @warn "Plotting failed: $e"
+    end
+    return [real(r) for r in all_roots if abs(imag(r)) < 1e-10]
+end
+```
+
+### Docstrings
+
+- Required for all exported functions with signature and description
+- Use LaTeX math in docstrings
+- Include examples showing typical usage
+
+## Function Signature Patterns
+
+### Mathematical Functions
+```julia
+nth_root(x, n) -> Number                  # Returns complex for even roots of negative numbers
+```
+
+### Plotting Functions
+```julia
+plot_parabola_roots_amrvw(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
+plot_parabola_roots_polynomial(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
+plot_parabola_roots_quadratic(a₂::Float64, a₁::Float64=0.0, a₀::Float64=0.0) -> Vector{ComplexF64}
+plot_hyperbola(a::Float64=1.0, h::Float64=0.0, k::Float64=0.0) -> Plot
+plot_hyperbola_axes_varx(a::Float64, b::Float64) -> Plot
+plot_hyperbola_axes_direct(a::Float64, b::Float64) -> Plot
+```
+
+### Financial Functions
+```julia
+accrued_apr(i::Real, p::Real, c::Int64) -> Float64
+accrued(i::Real, p::Real, c::Int64) -> Float64
+```
+
+### Geometric Functions
+```julia
+triangle_area_perim(a::Float64, b::Float64, c::Float64) -> Tuple{Float64, Float64}
+```
+
+## Dependencies & Libraries
+
+**Heavy Dependencies**: Nemo (~500MB), GLMakie, WGLMakie (main Project.toml)
+**Optimized Tests**: Minimal dependencies in `test/Project.toml` for CI speed
+
+### Key Mathematical Libraries
+
+- **Symbolics.jl**: Symbolic variables (`@variables x`) for equation manipulation
+  - Create variables: `@variables x; f = a₂*x^2 + a₁*x + a₀`
+  - Simplify expressions: `simplify(expr, expand=true)`
+  - **Extract numeric values** (two methods):
+    1. **substitute + value**: `substitute(expr, x => π/4; fold=Val(true))` then `Symbolics.value(result)`
+    2. **build_function**: `f = build_function(expr, x, expression=Val{false})` creates callable Julia function
+  - Use `fold=Val(true)` with substitute to simplify after substitution
+  - Use `expression=Val{false}` with build_function to avoid eval requirement
+- **Polynomials.jl**: Polynomial operations and root finding
+  - Create: `p = Polynomial([a₀, a₁, a₂])`
+  - Solve: `roots(p)`
+- **AMRVW.jl**: Alternative root finding: `AMRVW.roots([a₀, a₁, a₂])`
+- **Nemo.jl**: Number theory (verify usage patterns before adding new tests)
+- **Plots.jl/GR**: Plotting with automatic CI headless mode
+
+## Project-Specific Conventions
+
+- **DrWatson Integration**: Use `projectdir()`, `srcdir()` for paths (except in tests)
+- **Mathematical Notation**: Use Unicode symbols (a₂, a₁, a₀) in function parameters
+- **Documentation**: Use LaTeX math notation with Latexify.jl integration
diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md
new file mode 100644
index 0000000..2c310dd
--- /dev/null
+++ b/.github/instructions/testing.instructions.md
@@ -0,0 +1,96 @@
+---
+applyTo: 'test/**'
+---
+# Testing Conventions
+
+## Three-Layer CI-Compatible Testing Approach
+
+### 1. Module-Level Detection (Automatic)
+
+In `src/Math_Foundations.jl` — runs on module load:
+
+```julia
+if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
+    ENV["GKSwstype"] = "100"  # Headless plotting
+    gr(show=false)
+else
+    gr()  # Interactive plotting
+end
+```
+
+### 2. Test-Level Configuration (Manual)
+
+In `test/runtests.jl` — set BEFORE loading module:
+
+```julia
+ENV["GKSwstype"] = "100"  # Set BEFORE using Math_Foundations
+using DrWatson, Test
+@quickactivate "Math_Foundations"
+using Math_Foundations
+```
+
+### 3. Separated Logic (Design Pattern)
+
+All functions follow the `calculate_*` / `plot_*` split:
+
+- **Computational functions** (`calculate_*`): Pure math, no plotting, test directly
+- **Plotting functions** (`plot_*`): Computation + visualization, test with try-catch
+
+## Testing Patterns
+
+### Computational Tests (No try-catch)
+
+```julia
+@testset "Computational Tests" begin
+    # NO try-catch - math errors should fail
+    roots = calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)
+    @test length(roots) == 2
+    @test typeof(roots) == Vector{ComplexF64}
+end
+```
+
+### Integration Tests (CI-safe plotting)
+
+```julia
+@testset "Integration Tests" begin
+    try
+        result = plot_parabola_roots_quadratic(1.0, 0.0, -4.0)
+        @test typeof(result) == Vector{Float64}  # Real roots
+    catch e
+        @test hasmethod(plot_parabola_roots_quadratic, (Float64, Float64, Float64))
+        @test typeof(calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)) == Vector{ComplexF64}
+    end
+end
+```
+
+## Test Organization
+
+- **@testset structure**: Group tests by function (54 total tests across all functions)
+- **No try-catch for math**: Computational tests should fail on mathematical errors
+- **try-catch for plots**: Only use for CI-safe visualization testing
+- **Edge cases**: Test positive/negative, zero, special values
+- Use `@test_throws` for expected errors, `@test_broken` for known failures
+
+## Plotting in Tests
+
+- All plots auto-save: `"plots/" * Dates.format(now(),"yyyymmdd-HHMMSS") * "functionname.png"`
+- Ensure `plots/` directory exists before running tests
+- Use LaTeX titles: `title!(L"Plot\ of\ %$a₂ * x^2 + %$a₁ * x + %$a₀\\")`
+
+## Running Tests
+
+```bash
+# Local
+julia --project=. test/runtests.jl
+
+# CI mode (headless plotting)
+CI=true julia --project=. test/runtests.jl
+```
+
+## CI/CD Pipeline
+
+- **Tests**: Run on all PRs (`.github/workflows/CI.yml`)
+- **Docs Build**: Test on PR (no deploy)
+- **Docs Deploy**: Auto-deploy to `https://study.fourm.info/math_foundations/` on merge to `main`
+- **Cross-Repo**: Deploys to `FourMInfo/math_tech_study` subdirectory
+- **Prerequisites**: `plots/` directory must exist for tests to pass

From 5b188c2a41d3174c4e87554856fb32c478f03733 Mon Sep 17 00:00:00 2001
From: Aron T <aront@fourm.info>
Date: Tue, 10 Feb 2026 19:36:12 +0200
Subject: [PATCH 2/3] align: synchronize instruction files with Linear_Algebra

Add missing shared content to instruction files for cross-project consistency:

docs.instructions.md:
- Add extra bullet point examples for bullet point style (item 1)
- Add MathJax3 Configuration section (item 2)
- Add 'follow existing pattern' line (item 3)
- Add Cross-Document Section Links section (item 4)
- Add project-specific grouping example (item 7)

testing.instructions.md:
- Add CI-Compatible Plotting with ENV detection pattern (item 8)
- Add smarter catch block with rethrow for non-plotting errors (item 9)
- Add atol=1e-10 numerical precision guidance (item 10)

source.instructions.md:
- Add Documentation & Comments subsection (item 15)
- Add Code Organization subsection (item 16)
---
 .github/instructions/docs.instructions.md    | 55 +++++++++++++++++++-
 .github/instructions/source.instructions.md  | 15 ++++++
 .github/instructions/testing.instructions.md | 26 ++++++++-
 3 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md
index d6b1fe8..816dab3 100644
--- a/.github/instructions/docs.instructions.md
+++ b/.github/instructions/docs.instructions.md
@@ -10,7 +10,7 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
 **Document Organization:**
 - Start with concept overview and [MathWorld](https://mathworld.wolfram.com/) link in opening paragraph
 - Use hierarchical headings: `##` for major topics, `###` for subtopics
-- Group related concepts (e.g., "By Side Length", "By Angle Measure")
+- Group related concepts logically (e.g., "By Side Length", "By Angle Measure" for geometry)
 - Include real-world applications section
 
 **Content Style:**
@@ -45,7 +45,9 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
     ```
 - **Bullet point style**: List items starting with `-` must begin with **text**, then LaTeX math. LaTeX commands immediately after `-` render incorrectly (misaligned or broken formatting)
   - ✅ **CORRECT**: `- The semi-major axis is $a$`
+  - ✅ **CORRECT**: `- stretch the vector: $\lvert c \rvert \gt 1$`
   - ❌ **WRONG**: `- $a$ is the semi-major axis` (LaTeX immediately after dash)
+  - ❌ **WRONG**: `- $\mathbf{e}_1 = \lbrack 1, 0 \rbrack$ (points along x-axis)` (LaTeX starts the line)
 - **Equation placement style**: Prefer inline equations with "where:" at end of sentence, followed by list
   - ✅ **CORRECT**: `For an ellipse: $\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1$ where:`
   - ❌ **AVOID**: Blank line, then equation block, then blank line, then "where:"
@@ -59,6 +61,32 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
   - ✅ **CORRECT**: `$\lvert c \rvert > 1$`
   - ❌ **WRONG**: `$|c| > 1$` (pipe may be interpreted as table delimiter)
 
+## MathJax3 Configuration
+
+This project uses MathJax3 for math rendering (not the default KaTeX). Key configuration in `docs/make.jl`:
+
+```julia
+mathengine = Documenter.MathJax3(Dict(
+    :loader => Dict("load" => ["[tex]/physics", "[tex]/ams"]),
+    :tex => Dict(
+        "packages" => ["base", "ams", "mathtools"],
+        "inlineMath" => [["\$", "\$"]],
+        "displayMath" => [["\$\$", "\$\$"], ["\\[", "\\]"]],
+    ),
+)),
+```
+
+**Critical**: The `displayMath` array must include **both** `$$...$$` AND `\[...\]` delimiters because:
+- Markdown source uses `$$...$$` for display math
+- Documenter.jl converts some `$$` blocks to `\[...\]` in generated HTML (especially in list items or new paragraphs)
+- Without both delimiters, MathJax won't process `\[...\]` blocks and they render as literal text
+
+**To switch from KaTeX to MathJax3:**
+1. Add `mathengine` parameter to `Documenter.HTML()` in `docs/make.jl`
+2. Include both delimiter styles in `displayMath`
+3. Load desired packages (ams, mathtools, physics) via `:loader` and `"packages"`
+4. Clean rebuild: `rm -rf docs/build && julia --project=. docs/make.jl`
+
 ## MathWorld Links
 
 - Link every new mathematical term on first mention
@@ -78,6 +106,31 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
 - **Bold** for important terms and section labels
 - Fix all linting issues after editing (except config files)
 - Code blocks with language tags: ````julia` for Julia examples
+- Follow the pattern of existing function documentation in src directory
+
+## Cross-Document Section Links (Documenter.jl)
+
+When linking to a specific section in another document, use standard markdown link syntax with the full file path and section anchor:
+
+```markdown
+[Display Text](../Folder/Document Name.md#Section-Heading)
+```
+
+**CRITICAL rules for section anchors:**
+- Section anchors must **exactly match** the heading text with proper capitalization
+- Spaces in **file names** remain as spaces (not `%20`)
+- Spaces in **section anchors** become hyphens (`-`)
+- Parentheses in section names are preserved in the anchor
+
+**Examples:**
+- ✅ **CORRECT**: `[Solving Equations](../Algebra/03 Solving Equations.md#Solving-Equations)`
+- ❌ **WRONG**: `[Section](../Algebra/03%20Solving%20Equations.md#section)` (wrong: `%20` and lowercase)
+- ❌ **WRONG**: `[Section](@ref "Section Name")` (`@ref` is for docstrings, not cross-document links)
+
+**Best practice for cross-references:**
+- Include context about which document contains the section: "see [Section Name](path#anchor) in Document Name"
+- Verify the section heading spelling and capitalization before creating the link
+- Test the link by building docs (`julia --project=. docs/make.jl`) and clicking in browser
 
 ## Documentation Structure
 
diff --git a/.github/instructions/source.instructions.md b/.github/instructions/source.instructions.md
index e018cb8..491202d 100644
--- a/.github/instructions/source.instructions.md
+++ b/.github/instructions/source.instructions.md
@@ -77,6 +77,21 @@ end
 - Use LaTeX math in docstrings
 - Include examples showing typical usage
 
+### Documentation & Comments
+
+- Include detailed comments explaining mathematical concepts
+- Use clear variable names (e.g., `a₂`, `a₁`, `a₀` for polynomial coefficients)
+- Document return types and edge cases in comments
+- Explain mathematical formulas in comments
+- Maintain consistency with mathematical notation
+
+### Code Organization
+
+- **Single Source File**: Core functions in `basic_maths.jl`, main module in `Math_Foundations.jl`
+- **Consistent Naming**: `calculate_*` for pure computation, `plot_*` for visualization
+- **Export Everything**: All public functions exported from main module
+- **Separate Concerns**: Computational logic separated from plotting logic
+
 ## Function Signature Patterns
 
 ### Mathematical Functions
diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md
index 2c310dd..1a3719d 100644
--- a/.github/instructions/testing.instructions.md
+++ b/.github/instructions/testing.instructions.md
@@ -56,9 +56,32 @@ end
     try
         result = plot_parabola_roots_quadratic(1.0, 0.0, -4.0)
         @test typeof(result) == Vector{Float64}  # Real roots
+    catch e
+        # Only catch plotting-related errors, not computational errors
+        if contains(string(e), "display") || contains(string(e), "GKS") || isa(e, ArgumentError)
+            @test hasmethod(plot_parabola_roots_quadratic, (Float64, Float64, Float64))
+            @test typeof(calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)) == Vector{ComplexF64}
+        else
+            rethrow(e)  # Re-throw computational errors — these should fail the test
+        end
+    end
+end
+```
+
+### CI-Compatible Plotting with Environment Detection
+
+```julia
+# Alternative pattern: skip plotting entirely in CI
+if get(ENV, "CI", "false") == "true" || get(ENV, "GITHUB_ACTIONS", "false") == "true"
+    # In CI, just test that the function exists
+    @test hasmethod(plot_parabola_roots_quadratic, (Float64, Float64, Float64))
+else
+    # Local testing - allow plotting but capture any display issues
+    try
+        result = plot_parabola_roots_quadratic(1.0, 0.0, -4.0)
+        @test typeof(result) == Vector{Float64}
     catch e
         @test hasmethod(plot_parabola_roots_quadratic, (Float64, Float64, Float64))
-        @test typeof(calculate_parabola_roots_quadratic(1.0, 0.0, -4.0)) == Vector{ComplexF64}
     end
 end
 ```
@@ -69,6 +92,7 @@ end
 - **No try-catch for math**: Computational tests should fail on mathematical errors
 - **try-catch for plots**: Only use for CI-safe visualization testing
 - **Edge cases**: Test positive/negative, zero, special values
+- **Numerical Precision**: Use `atol=1e-10` for floating-point comparisons
 - Use `@test_throws` for expected errors, `@test_broken` for known failures
 
 ## Plotting in Tests

From 2f79abcedbc0a18525fa647cea2cb15ec4a74cdf Mon Sep 17 00:00:00 2001
From: Aron T <aront@fourm.info>
Date: Wed, 18 Feb 2026 18:07:02 +0200
Subject: [PATCH 3/3] docs: add instruction to notify user when files cannot be
 read

---
 .github/copilot-instructions.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index fb2dbdc..18bfb93 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -95,6 +95,7 @@ Your comprehensive PR description with:
     - Summarize the current understanding of the issue before discussing potential solutions
     - Document any assumptions made during the analysis
     - Identify any knowledge gaps or areas requiring further investigation
+- Notify user immediately if you cannot read a file they provided (e.g., PDFs, binary files) instead of silently substituting other files or faking understanding of the content
 - If you are unsure about a solution, clearly state that more information is needed or that further investigation is required
 - When providing code examples, ensure they are clear, concise, and directly relevant to the problem at hand
     - Avoid unnecessary complexity in code examples