From aa46ca88100bd16daef53789720da5bbba6fbbd4 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Sat, 9 May 2026 16:30:26 +0300
Subject: [PATCH] feat(docs): add legacy.md

docs/src/legacy.md | 25 +++++++++++++++++++++++++  1 file changed, 25 insertions(+)
---
 docs/src/legacy.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 docs/src/legacy.md

diff --git a/docs/src/legacy.md b/docs/src/legacy.md
new file mode 100644
index 0000000..cef660a
--- /dev/null
+++ b/docs/src/legacy.md
@@ -0,0 +1,25 @@
+# [Legacy module](@id legacy_module)
+
+JuliaFEM.jl is **0.x**; the default `using JuliaFEM` surface is the type-stable
+pipeline described in `AGENTS.md` (`Element{K,P,S,N}`, `DOFHandler`, domain
+kernels, modern assemblers).
+
+Older tutorials, notebooks, and helper scripts target a **previous** API:
+`Problem` / `Assembly` / `Solver` / `Analysis`, Dict-based fields, legacy element
+constructors, and some mesh readers (for example Abaqus `.inp` and Code Aster
+`.med`). That code lives under `src/legacy/` inside `module Legacy`.
+
+## Enabling Legacy
+
+Set the environment variable **`JULIAFEM_ENABLE_LEGACY=1`** before the first
+`using JuliaFEM` in a Julia session so the `Legacy` submodule is loaded.
+Symbols are namespaced as `JuliaFEM.Legacy.<name>` and are **not** re-exported
+from `JuliaFEM`.
+
+## When to use it
+
+- Porting old scripts or reproducing historical results.
+- Reading meshes or models that still depend on legacy constructors.
+
+For new work, prefer the current API and the Quarto site map at
+`juliafem.github.io/docs/documentation-map.md`.