docs: Reorganize documentation into three-tier structure

**Three Manuals for Three Audiences:**

1. **User Manual** (docs/user/) - "Just Get It Done"
   - For end users, engineers, students
   - Simple, practical, step-by-step
   - Quick start, tutorials, examples, troubleshooting
   - Philosophy: Show me how to solve my problem

2. **Contributor Manual** (docs/contributor/) - "Show Me the Code"
   - For developers, contributors, advanced users
   - Technical, detailed, design rationale
   - Testing, architecture, performance, CI/CD
   - Philosophy: Explain HOW and WHY

3. **The JuliaFEM Book** (docs/book/) - "Let Me Show You How I Think"
   - For researchers, theory nerds, and Jukka
   - Comprehensive, educational, opinionated, personal
   - Math foundations, design philosophy, history, research
   - Philosophy: Mix theory, code, and personal experience

**Reorganization:**
- Moved: TESTING_PHILOSOPHY.md → contributor/testing_philosophy.md
- Moved: STATUS.md → contributor/status.md
- Moved: TEST_FIXES_NEEDED.md → contributor/test_fixes_needed.md
- Moved: lagrange_basis_functions.md → book/lagrange_basis_functions.md
- Moved: benchmarks/ → book/benchmarks/
- Created: docs/README.md (main index explaining structure)
- Created: README.md in each section explaining audience and contents
- Updated: All references in scripts and source files

**Naming:** All docs now lowercase (testing_philosophy not TESTING_PHILOSOPHY)

**Benefits:**
- Clear separation of concerns
- Users don't get overwhelmed with implementation details
- Contributors get technical depth
- Book preserves deep theory and personal insights
- Each manual optimized for its audience

**Next:** Populate each section with appropriate content

docs/README.md

@@ -0,0 +1,118 @@
+# JuliaFEM Documentation
+
+Welcome! JuliaFEM documentation is organized into **three manuals** for three different audiences:
+
+---
+
+## 📘 [User Manual](user/) - "Just Get It Done"
+
+**For:** End users, engineers, students who want to run simulations.
+
+**Style:** Simple, practical, step-by-step.
+
+**Contents:**
+- Quick start and installation
+- Tutorials and examples
+- API reference
+- Troubleshooting
+
+**Philosophy:** Show me how to solve my problem, skip the lectures.
+
+👉 **[Start Here](user/README.md)** if you want to run simulations.
+
+---
+
+## 🔧 [Contributor Manual](contributor/) - "Show Me the Code"
+
+**For:** Developers, contributors, advanced users who want to extend JuliaFEM.
+
+**Style:** Technical, detailed, design rationale.
+
+**Contents:**
+- Testing philosophy
+- Code style and architecture
+- Performance guidelines
+- How to add elements
+- CI/CD and git workflow
+
+**Philosophy:** Explain HOW the code works and WHY we made these choices.
+
+👉 **[Start Here](contributor/README.md)** if you want to contribute code.
+
+---
+
+## 📖 [The JuliaFEM Book](book/) - "Let Me Show You How I Think"
+
+**For:** Advanced researchers, theory nerds, those who want to understand deeply. And Jukka.
+
+**Style:** Comprehensive, educational, opinionated, personal.
+
+**Contents:**
+- Mathematical foundations (Lagrange basis, contact mechanics, etc.)
+- Design philosophy and technical vision
+- Strategic mistakes and lessons learned (2015-2019)
+- Research directions (nodal assembly, matrix-free, etc.)
+- Personal reflections on the journey
+
+**Philosophy:** Mix theory, software design, and personal experience. Teach FEM through implementation.
+
+👉 **[Start Here](book/README.md)** if you love deep dives and want to understand the "why" behind everything.
+
+---
+
+## Quick Navigation
+
+### I want to...
+
+- **Solve a heat transfer problem** → [User Manual](user/)
+- **Add a new element type** → [Contributor Manual](contributor/)
+- **Understand Lagrange basis functions** → [Book: Lagrange Basis](book/lagrange_basis_functions.md)
+- **Learn about testing** → [Contributor: Testing Philosophy](contributor/testing_philosophy.md)
+- **See benchmark results** → [Book: Benchmarks](book/benchmarks/)
+- **Understand the design philosophy** → [Book: Philosophy](book/)
+- **Report a bug** → GitHub Issues
+- **Ask a question** → GitHub Discussions
+
+---
+
+## Documentation Philosophy
+
+### Why Three Manuals?
+
+Different readers have different needs:
+
+1. **Users** don't care about implementation details - they just want working code.
+2. **Contributors** need technical depth but not necessarily all the theory.
+3. **Researchers** (and Jukka) want to understand everything from first principles.
+
+Mixing these audiences in one manual makes it too complex for users and too shallow for researchers.
+
+### Design Principles
+
+- **User Manual:** Optimize for time-to-first-result
+- **Contributor Manual:** Optimize for correctness and maintainability
+- **Book:** Optimize for understanding and education
+
+### Cross-References
+
+Manuals link to each other when appropriate:
+- User manual links to theory when deeper understanding helps
+- Contributor manual links to book for design rationale
+- Book links to code examples and practical guides
+
+---
+
+## Contributing to Documentation
+
+Documentation improvements are always welcome!
+
+- **User docs:** Fix errors, add examples, improve clarity
+- **Contributor docs:** Update for new features, clarify architecture
+- **Book:** Add theory, share insights, document research
+
+See [Contributor Manual](contributor/) for guidelines.
+
+---
+
+**License:** MIT (same as code)  
+**Questions?** Open an issue or discussion on GitHub

docs/book/README.md

@@ -0,0 +1,82 @@
+# 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)

docs/contributor/README.md

@@ -0,0 +1,53 @@
+# JuliaFEM Contributor Manual
+
+**Audience:** Developers, contributors, advanced users who want to extend or modify JuliaFEM.
+
+This manual is **technical and detailed** - it explains HOW the code works and WHY we made certain design choices.
+
+## What's Here
+
+- **Testing Philosophy:** How and why we test
+- **Code Style:** Conventions and best practices
+- **Architecture:** Module structure, data flow, key abstractions
+- **Performance:** Zero-allocation design, profiling, benchmarking
+- **Adding Elements:** How to implement new element types
+- **CI/CD:** Continuous integration, releases, versioning
+- **Git Workflow:** Branching, commits, pull requests
+
+## What's NOT Here
+
+- User tutorials (see `docs/user/` for that)
+- Deep mathematical theory (see `docs/book/` for that)
+- "How do I solve problem X?" (that's user docs)
+
+## Philosophy
+
+**"Show me the code AND tell me why."**
+
+We assume you:
+- Know Julia reasonably well
+- Understand FEM basics
+- Want to add features or fix bugs
+- Care about performance and correctness
+- Need to understand design rationale
+
+## Before Contributing
+
+1. Read [Testing Philosophy](testing_philosophy.md)
+2. Understand [Architecture](architecture.md)
+3. Follow [Code Style](code_style.md)
+4. Check [Performance Guidelines](performance.md)
+5. Review [Git Workflow](git_workflow.md)
+
+## Key Principles
+
+- **Type stability:** No `Any`, no `Dict` without types
+- **Zero allocations:** Hot paths should allocate nothing
+- **Immutability:** Prefer `struct` over `mutable struct`
+- **Composition:** Use tuples and free functions, not OOP hierarchies
+- **Explicit:** No magic, user knows what happens
+- **Test first:** Write tests before fixing bugs
+
+---
+
+**Start here:** [Testing Philosophy](testing_philosophy.md) | [Architecture Overview](architecture.md)

docs/user/README.md

@@ -0,0 +1,40 @@
+# JuliaFEM User Manual
+
+**Audience:** End users, engineers, students who want to run simulations and get results.
+
+This manual is designed to be **simple and practical** - get you from zero to running simulations as quickly as possible.
+
+## What's Here
+
+- **Quick Start:** Installation and first simulation in 5 minutes
+- **Tutorials:** Step-by-step guides for common problems
+- **Examples:** Pre-built simulations you can run and modify
+- **API Reference:** Function documentation (what does this do?)
+- **Troubleshooting:** Common errors and how to fix them
+
+## What's NOT Here
+
+- Deep theory (see `docs/book/` for that)
+- How to contribute code (see `docs/contributor/` for that)
+- Internal architecture details
+
+## Philosophy
+
+**"Just show me how to solve my problem."**
+
+We assume you:
+- Have a problem to solve (heat transfer, elasticity, contact)
+- Want working code, not lectures
+- Will read theory when YOU need it, not when WE think you should
+
+## Getting Help
+
+1. Start with the Quick Start
+2. Find an example similar to your problem
+3. Modify it to fit your needs
+4. If stuck, check Troubleshooting
+5. Still stuck? Ask on GitHub Discussions
+
+---
+
+**Next:** Start with [Quick Start](quickstart.md) or browse [Examples](../examples/)

scripts/README.md

@@ -35,7 +35,7 @@ julia --project=. scripts/generate_lagrange_basis.jl
 - `src/basis/lagrange_generated.jl` (commit this file!)
 
 **Theory:**
-See `src/lagrange_basis_functions.md` for mathematical foundation.
+See `docs/book/lagrange_basis_functions.md` for mathematical foundation.
 
 **Architecture:**
 
@@ -130,6 +130,6 @@ Pre-compute stiffness matrices for simple elements.
 
 **See also:**
 
-- `src/lagrange_basis_functions.md` - Mathematical theory
+- `docs/book/lagrange_basis_functions.md` - Mathematical theory
 - `src/basis/lagrange_generator.jl` - Symbolic generation engine
 - `llm/VISION_2.0.md` - Overall project architecture

scripts/generate_lagrange_basis.jl

@@ -21,7 +21,7 @@
 #   - After modifying lagrange_generator.jl
 #
 # THEORY:
-#   See src/lagrange_basis_functions.md for full mathematical details
+#   See docs/book/lagrange_basis_functions.md for full mathematical details
 #
 # ==============================================================================
 
@@ -617,7 +617,7 @@ println(output, "#   cd /path/to/JuliaFEM.jl")
 println(output, "#   julia --project=. scripts/generate_lagrange_basis.jl")
 println(output, "#")
 println(output, "# Theory:")
-println(output, "#   See src/lagrange_basis_functions.md")
+println(output, "#   See docs/book/lagrange_basis_functions.md")
 println(output, "#")
 println(output, "# Generator:")
 println(output, "#   src/basis/lagrange_generator.jl (symbolic engine)")

src/basis/lagrange_generator.jl

@@ -45,7 +45,7 @@
 #   - Version control shows what changed
 #
 # SEE:
-#   - src/lagrange_basis_functions.md (mathematical explanation)
+#   - docs/book/lagrange_basis_functions.md (mathematical explanation)
 #   - scripts/generate_lagrange_basis.jl (generation script)
 #   - src/basis/lagrange_generated.jl (output - do not edit manually!)
 #