Adopt the hub's shared instruction templates; bridge them into Claude Code

.github/copilot-instructions.md

@@ -4,13 +4,13 @@
 
 ## Project Overview
 
-**Julia basic maths project** using a Julia workspace for reproducibility. Implements mathematical foundations (algebra, geometry, trigonometry) with visualization, comprehensive testing, and cross-repository documentation deployment.
+**Julia basic maths project** using a Julia workspace for reproducibility. Implements mathematical foundations (algebra, geometry, trigonometry) with visualization, comprehensive testing and cross-repository documentation deployment.
 
 ### Core Architecture
 
-- **`src/Math_Foundations.jl`**: Main module with CI-aware plotting (auto-detects headless environments)
+- **`src/Math_Foundations.jl`**: Main module; uses `@reexport` to re-export `Symbolics`, `Nemo`, `Plots`, `LaTeXStrings`, `Dates`, `AMRVW`, `Polynomials` and `GeometryBasics` — consumers get all exported names with a single `using Math_Foundations`
 - **`src/basic_maths.jl`**: Mathematical library (roots, polynomials, hyperbolas, financial calculations)
-- **`test/`**: 54 tests with separated computational/plotting logic for CI compatibility
+- **`test/`**: Tests using `Math_Foundations` and `Test` only — re-exported names are available via `@reexport`, no explicit `using` needed in test files
 - **`docs/`**: Documenter.jl deploying to `https://fourm.info/math_foundations/` (cross-repo to `math_tech_study`)
 - **`notebooks/`**: Jupyter notebooks for exploration (not tested in CI)
 
@@ -23,8 +23,8 @@ member environments. Each member has its own `Project.toml` and `Manifest.toml`:
 |---|---|
 | `Project.toml` | Root package — defines `Math_Foundations` as a library (uuid `27a7a001-4557-47fa-93d4-b76916053e56`) |
 | `test/Project.toml` | Test-only deps (`Math_Foundations`, `Test`) — workspace member |
-| `docs/Project.toml` | Docs deps (`Documenter`, `Dates`, `Math_Foundations`) — workspace member; uses `Pkg.develop(path=".")` |
-| `notebooks/Project.toml` | Notebook superset (Makie stack + root deps) — **not** a workspace member |
+| `docs/Project.toml` | Docs deps (`Documenter`, `Dates`, `LiveServer`, `Math_Foundations`) — workspace member; uses `Pkg.develop(path=".")`. `LiveServer` is for local live preview (see the `documenter-jl-conventions` skill) |
+| `notebooks/Project.toml` | Notebook superset (`IJulia`, `Revise`, `Math_Foundations`, the Makie stack, `Meshes`, `ImageShow`) — **not** a workspace member |
 
 The `notebooks/` environment is intentionally excluded from the workspace `projects` list because
 it is a developer-only interactive environment, not a dependency of any other member.
@@ -80,13 +80,6 @@ pkg> instantiate
 
 This creates `notebooks/Manifest.toml` (gitignored) with `path = ".."` pointing at the root package. Subsequent `julia --project=./notebooks` invocations will resolve `Math_Foundations` from the local source.
 
-## Julia Compilation Considerations
-
-- **Be Patient with First Runs**: Julia often needs to precompile packages on first run; allow 15-30 seconds before tests actually start
-- **Example Expected Output**: `Precompiling Math_Foundations... N dependencies successfully precompiled in 17 seconds`
-- **Subsequent Runs**: Much faster once cache is built
-- **Don't Cancel Early**: Allow time for compilation to complete
-
 ## Git Best Practices
 
 - **Never use `git add .`** - Always stage files explicitly by name to avoid accidentally committing development files, notebooks, or temporary files
@@ -99,47 +92,22 @@ This creates `notebooks/Manifest.toml` (gitignored) with `path = ".."` pointing
 
 - **ALWAYS check all commits on the branch first**: Run `git log main..HEAD --oneline` before writing the PR description
 - **ALWAYS push changes first**: Use `git push origin BRANCH_NAME` before creating PR
-- **Do NOT use `gh pr create`** - The GitHub CLI command doesn't work properly in this environment
-- **Use GitHub web interface with URL parameters**:
+- **`gh` works here** — `gh pr create --repo FourMInfo/Math_Foundations` is the normal route (verified 2026-09-28). Always pass `--repo` explicitly; see the `phased-implementation-workflow` skill for the branch → PR → squash-merge → prune sequence
+- **Fallback if `gh` is unavailable**: open the compare URL in a browser, with title and body as parameters
   ```
   https://github.com/FourMInfo/Math_Foundations/compare/main...BRANCH_NAME?title=Your+PR+Title&body=Your+PR+Description
   ```
-- **Always provide fallback copy-paste content**: Include separate, copyable title and description in case URL parameters don't work
-
-## 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
+  Supply a separate copy-paste title and description as well, in case the URL parameters do not populate
 
 ## Communication Patterns
 
-- Avoid being overly obsequious in responses
-    - do not tell me "I am happy to help" or similar phrases
-    - do not tell me how amazing I am or how great my work is
-    - do not say something is "awesome" or "fantastic" unless it is truly exceptional
-    - do not use overly emotional language
-    - do not use words like "wonderful" or "great" to describe my work
-    - do not use words like "perfect" or "flawless" to describe my work
-- When asked to analyze a bug or problem first lay out the problem clearly, then suggest potential solutions or debugging steps and let the user decide on the next steps
-- Never say "I see what the problem is" or similar phrases that imply you have fully understood the issue without further discussion and confirmation that you have understood the issue
-- Always provide clear, actionable suggestions for next steps in debugging or implementation
-    - Acknowledge when you need more information or clarification before proceeding
-    - 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
-    - Use comments to explain key parts of the code where necessary
-    - Ensure code examples are formatted correctly for readability
-- If you find yourself repeating steps stop and explain why you are repeating them and ask if the user would like to proceed with the same steps again
-- Always ask for confirmation before proceeding with potentially destructive actions, such as deleting files or making significant changes to the codebase
-- When discussing code changes, clearly outline the impact of those changes on the overall project
-    - Discuss how changes align with project goals and coding standards
-    - Highlight any potential risks or trade-offs associated with the changes
-- If you encounter a situation where you need to make assumptions, clearly state those assumptions and their implications
-- When discussing project architecture or design decisions, provide a rationale for each decision made
-- If you need to reference external resources or documentation, provide clear links and context for their relevance
-- Always strive for clarity and precision in communication, especially when discussing technical details
-- If you need to ask for clarification, do so in a way that encourages open dialogue and collaboration
-- When providing feedback on code or design, focus on constructive criticism that helps improve the overall quality
+> **Copilot mirror.** Claude Code gets these rules from the global `~/.claude/CLAUDE.md`
+> (canonical: `Dotfiles.Mac/Files/claude/CLAUDE.md`), which is the source of truth. Copilot has no
+> global-instructions equivalent, so the essentials are restated here. Keep the two in step.
+
+- No obsequiousness: no "happy to help", no praise of my work ("amazing", "awesome", "perfect", "flawless"), no emotional language
+- Lay the problem out before proposing a fix, and never claim to have grasped an issue ("I see what the problem is") before that is confirmed
+- Say when you need more information rather than guessing, and state any assumption you are working from
+- Say immediately if you cannot read a file you were given — never substitute another file or infer its contents
+- If you find yourself repeating steps, stop, explain why, and ask before repeating them
+- Ask for confirmation before destructive actions or significant structural changes

.github/instructions/docs.instructions.md

@@ -3,6 +3,11 @@ applyTo: 'docs/**'
 ---
 # Documentation Conventions
 
+This file is **shared**: copied unchanged into every math study repo from the hub
+(`FourMInfo/math_tech_study`, `project_resources/instructions/`) and byte-identical everywhere.
+This repo's deployed URL (`dirname`) and anything specific to its docs are in
+`project.instructions.md`.
+
 ## Structure for Mathematical Concept Documentation
 
 Documentation in `docs/src/` explains general math concepts (not code). Follow these patterns:
@@ -20,7 +25,7 @@ Documentation in `docs/src/` explains general math concepts (not code). Follow t
 - **Multiple representations**: Equations, tables, visual aids (SVG diagrams when helpful)
 - **Context matters**: Explain _why_ concepts are important, not just _what_ they are
   - Example: "Projections are fundamental to least-squares approximation, computer graphics, and data compression"
-- **Derivations**: Show mathematical reasoning step-by-step (see projection and transformation matrix derivations)
+- **Derivations**: Show mathematical reasoning step-by-step
 
 ## Mathematical Notation, MathJax3 & MathWorld Links
 
@@ -50,16 +55,19 @@ See `documenter-jl-conventions` skill for section anchor rules and examples.
 ## Documentation Structure
 
 - **Cross-Repository Deployment**: Deploys to math_tech_study repository
-- **Subdirectory Pattern**: Available at fourm.info/math_foundations/
+- **Subdirectory Pattern**: Available at `fourm.info/<dirname>/` — this repo's dirname is in `project.instructions.md`
 - **Auto-docs Integration**: Uses `@autodocs` for automatic function documentation
 - **Mathematical Notation**: Supports LaTeX rendering in documentation
 
 ## Building Documentation
 
 ```bash
-julia --project=. docs/make.jl
+# Once after cloning (docs/Manifest.toml is gitignored) — the same step CI runs
+julia --project=docs -e 'using Pkg; Pkg.develop(path="."); Pkg.instantiate()'
+
+julia --project=docs 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.
+**IMPORTANT**: Always run `julia --project=docs 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.
 
 For a live, auto-refreshing preview served from `docs/build/`, use `LiveServer` (declared in `docs/Project.toml`). See the `documenter-jl-conventions` skill for the exact `serve` command.

.github/instructions/ecosystem.instructions.md

@@ -0,0 +1,110 @@
+---
+applyTo: '**'
+---
+# Math Study Ecosystem
+
+This file is **shared**: it is copied unchanged into every math study repo from the hub
+(`FourMInfo/math_tech_study`, `project_resources/instructions/`) and must stay byte-identical
+everywhere. Never edit a repo's copy — change the hub template and propagate. Everything
+specific to this repo (its package, deployed URL, dependencies, notebook setup) is in
+`project.instructions.md`.
+
+## What This Repository Is
+
+This is **one subrepository** in a multi-repository Julia math study project. Understand the
+broader ecosystem before changing CI, documentation configuration, or project structure.
+
+## The Math & Tech Study Hub
+
+The main website lives at **https://fourm.info**, built with **Franklin.jl** in the separate
+repository `FourMInfo/math_tech_study`. The hub owns the top-level domain, navigation and
+study guides.
+
+Current math study repositories and their deployed URLs:
+
+| Repository | Deployed URL |
+|---|---|
+| `FourMInfo/Linear_Algebra` | https://fourm.info/linear_algebra/ |
+| `FourMInfo/Math_Foundations` | https://fourm.info/math_foundations/ |
+| `FourMInfo/Calculus` | https://fourm.info/calculus/ |
+
+New repositories follow the same pattern; the hub template of this file gains a row and is
+propagated to all of them.
+
+## How These Repositories Deploy
+
+Each repo is a Julia package documented with **Documenter.jl**.
+
+```text
+Push to main
+    → CI.yml runs the deploy-docs job
+    → docs/make.jl builds the Documenter site
+    → deploydocs() cross-deploys to FourMInfo/math_tech_study (gh-pages branch)
+    → appears at fourm.info/<dirname>/   (this repo's dirname: see project.instructions.md)
+```
+
+Key facts about `docs/make.jl`:
+
+- `ENV["GITHUB_REPOSITORY"]` is **deliberately overridden** to `"FourMInfo/math_tech_study"` —
+  this is what makes the deployment cross-repository. Do NOT remove or change it.
+- `dirname` in `deploydocs()` sets the subdirectory on the live site. Do NOT change it.
+- The `DOCUMENTER_KEY` secret is the private half of a deploy key registered on
+  `math_tech_study` (not on this repo), shared by every study repo.
+
+## CI Behaviour
+
+`.github/workflows/CI.yml` has three independent jobs (no `needs:` between them):
+
+1. **test** — runs on pull requests and manual triggers (`workflow_dispatch`), not on pushes to
+   `main`
+2. **docs-build** — builds (does not deploy) the docs on pull requests that change `src/` or
+   `docs/`
+3. **deploy-docs** — runs on push to `main` or a manual trigger, and deploys to the site
+
+Because deploy-docs does not wait for tests, a change must pass its tests on the pull request
+**before** it is merged.
+
+**CRITICAL**: keep the `workflow_dispatch` trigger. It lets this repo's docs be redeployed
+without a code change if they ever go missing from the site.
+
+## Project Layout and Environments
+
+- Every study repo's file and directory structure is generated by **DrWatson.jl** when the repo
+  is created, never by hand. The layout (`src/`, `test/`, `docs/`, `notebooks/` and the other
+  DrWatson directories) exists because DrWatson made it; CI and the docs build depend on it, so
+  do not restructure it.
+- DrWatson also activates the project in interactive work: the Julia `startup.jl` (canonical
+  copy in `Dotfiles.Mac/Files/julia/`) loads it in every REPL and runs `quickactivate(".")` when
+  Julia starts in a repo root without `--project`. Code does not call DrWatson: tests and CI run
+  with `--project` / `Pkg.test()`, and notebooks and tests load everything through
+  `using <Package>`, whose module reexports its dependencies.
+- `Manifest.toml` is gitignored in every environment, so the `[compat]` bounds in each
+  `Project.toml` (root, `docs/`, `test/`, `notebooks/`) are the only pin. Keep them current —
+  see the `julia-coding-conventions` skill.
+
+## Critical Constraints — Do NOT Do These
+
+| Action | Why It Is Dangerous |
+|---|---|
+| Enable GitHub Pages on this repository | Only `math_tech_study` may have GitHub Pages with the custom domain. Enabling it here breaks the domain |
+| Change or remove the `ENV["GITHUB_REPOSITORY"]` override in `docs/make.jl` | Deployment targets the wrong repository |
+| Change `dirname` in `deploydocs()` | The subdirectory path on the live site breaks |
+| Remove `workflow_dispatch` from CI.yml | Loses the ability to redeploy the docs manually |
+| Change the `DOCUMENTER_KEY` secret without also updating the deploy key on `math_tech_study` | Deployment fails with authentication errors |
+
+## Relationship to the Main Franklin Site
+
+The Franklin deploy in `math_tech_study` wipes `gh-pages` on every build, so its workflow backs
+up **every** top-level directory on `gh-pages` first and restores those the build did not
+regenerate. There is no list to maintain: a new study repo's subdirectory is preserved
+automatically. The details are in `math_tech_study`'s
+`.github/instructions/subrepo-docs-publishing.instructions.md`.
+
+## Local Documentation Preview
+
+```bash
+# Build docs locally (does not deploy)
+julia --project=docs docs/make.jl
+
+# The built site is in docs/build/ — see the documenter-jl-conventions skill for a live preview
+```