From 5bfd30e9a9c47875b831fd3f298a5cf68d9f5673 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Mon, 10 Nov 2025 22:20:40 +0200
Subject: [PATCH] docs: Move book README to docs/src/book/ following
 Documenter.jl standard

- Relocate docs/book/README.md to docs/src/book/README.md
- Follows standard Julia documentation structure where all source files live under docs/src/
- File contains YAML header and book philosophy/structure overview
- Part of three-tier documentation reorganization (user/contributor/book)
---
 docs/src/book/README.md | 103 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/src/book/README.md

diff --git a/docs/src/book/README.md b/docs/src/book/README.md
new file mode 100644
index 0000000..656c301
--- /dev/null
+++ b/docs/src/book/README.md
@@ -0,0 +1,103 @@
+---
+title: "The JuliaFEM Book"
+subtitle: "A comprehensive manual mixing theory, software design, and personal experience"
+description: "Deep dive into FEM theory, design philosophy, and research directions"
+date: 2025-11-09
+author: "Jukka Aho"
+categories: ["theory", "research", "philosophy"]
+keywords: ["fem theory", "contact mechanics", "design philosophy", "research"]
+audience: "researchers and theory enthusiasts"
+level: "expert"
+type: "book"
+status: "work in progress"
+---
+
+# The JuliaFEM Book
+
+**Audience:** Advanced researchers, theory nerds, those who want to understand the "why" and "how" at a deep level. And Jukka.
+
+This is the **JuliaFEM Bible** - a comprehensive manual mixing theory, philosophy, software design, and personal experience. It's educational, opinionated, and unapologetically deep.
+
+## What's Here
+
+- **Mathematical Foundations:** Lagrange basis functions, weak forms, contact mechanics
+- **Design Philosophy:** Why JuliaFEM exists, what problems it solves (and doesn't)
+- **Technical Vision:** Strategic mistakes from 2015-2019, lessons learned
+- **Research Directions:** Experimental ideas (nodal assembly, matrix-free, etc.)
+- **Personal Notes:** The journey, the failures, the "aha!" moments
+- **Theory + Code:** How mathematics becomes software
+
+## What's NOT Here
+
+- "How do I install?" (see `docs/user/`)
+- "How do I add a feature?" (see `docs/contributor/`)
+- Short answers (everything here is DEEP)
+
+## Philosophy
+
+**"Let me show you how I think about FEM."**
+
+This is:
+
+- **Educational:** Teach FEM through implementation
+- **Personal:** Written in Jukka's voice, reflecting 8+ years of experience
+- **Opinionated:** Strong views on what works and what doesn't
+- **Comprehensive:** From first principles to cutting-edge research
+- **Honest:** Documents failures as much as successes
+
+We assume you:
+
+- Love mathematics AND programming
+- Want to understand WHY, not just HOW
+- Have time to read deeply
+- Are curious about unconventional approaches
+- Might be me, 5 years from now, trying to remember why I did this
+
+## Structure
+
+### Part I: Foundations
+
+- Finite Element Method (brief review)
+- Lagrange Basis Functions (deep dive)
+- Assembly and Solving
+- Contact Mechanics
+
+### Part II: Software Design
+
+- Type Stability and Performance
+- Zero-Allocation Design
+- Immutability and Composition
+- Field System Architecture
+
+### Part III: History and Vision
+
+- Strategic Mistakes (2015-2019)
+- Why JuliaFEM is Different
+- Contact Mechanics Focus
+- Laboratory Philosophy
+
+### Part IV: Research
+
+- Nodal Assembly (experimental)
+- Matrix-Free Methods
+- Automatic Differentiation
+- GPU Acceleration
+
+### Part V: The Journey
+
+- Personal Reflections
+- Lessons Learned
+- Future Directions
+- Open Questions
+
+## Reading Guide
+
+- **For Theory:** Start with Part I
+- **For Design Rationale:** Start with Part II
+- **For History:** Start with Part III
+- **For Research Ideas:** Start with Part IV
+- **For Philosophy:** Read Part V first, then everything else
+
+---
+
+**Start here:** [Mathematical Foundations](foundations.md) | [Strategic Mistakes](strategic_mistakes.md) | [Why JuliaFEM?](philosophy.md)