agentfem 0.1.1__tar.gz

agentfem-0.1.1/AGENT_GUIDE.md

@@ -0,0 +1,67 @@
+# AgentFEM Agent Guide
+
+Use this guide when an AI agent is asked to build, review, extend, or debug a
+finite-element simulation with AgentFEM.
+
+## First Steps
+
+1. Read `WORKFLOW.md` to identify the standard finite-element sequence.
+2. Read `CONCEPTS.md` to align terminology before changing code.
+3. Identify or create the `studies.Study` before choosing constitutive laws or
+   operators.
+4. Inspect or create a mesh summary before reasoning about boundary tags,
+   material regions, or output dimensions.
+5. Inspect the target application only after mapping it to AgentFEM concepts.
+6. Prefer existing `agentfem` APIs before adding new helpers.
+7. Add reusable code only when it belongs to a standard FEM concept.
+
+## Progressive Reading
+
+- Mesh or boundary tagging: read `docs/module_map.md`, then use
+  `mesh.summarize_mesh`, `mesh.require_cell_tags`, and
+  `mesh.require_facet_tags`.
+- Study setup: use `studies.linear_static`, `studies.first_order_transient`, or
+  `studies.second_order_dynamics` before building operators.
+- Model audit: use `model.tree()`, `model.manifest()`, `model.summary()`, and
+  `model.check()` when multiple fields, regions, loads, constraints, or steps
+  must be inspected.
+- Model registration: use `model.field(...)`, `model.material(...)`,
+  `model.fix(...)`, and `model.traction(...)` in application workflows when the
+  assets should stay visible and auditable.
+- Application unknowns: use `fields.py` before dropping to `spaces.py`.
+- Function spaces: inspect `spaces.py`; only inspect `kernel/dofs.py` for
+  implementation-level dof work.
+- Essential boundary conditions: read `CONCEPTS.md`, then use `constraints/`.
+- Natural loads: read `CONCEPTS.md`, then use `loads.body_load`,
+  `loads.neumann`, or `loads.boundary_load`.
+- Constitutive laws: read `docs/extension_rules.md`, then use `constitutive/`.
+- Absorbing or Robin-like terms: use `boundary_models/`.
+- Assembly or lumped operators: inspect `assembly.py`.
+- Time stepping: inspect `time/` and `problems.py`.
+- Solves: inspect `solvers.py`.
+- Analysis steps: prefer `model.step(...)` or `model.linear_static_step(...)`
+  when a model owns fields, materials, loads, and constraints. Use
+  `problems.linear_static` or `problems.first_order_transient` when a workflow
+  intentionally starts from explicit K/C/F operators without model ownership.
+- Problem summaries: use `problems.FEMProblem` when a workflow needs a
+  broader structured audit record.
+- Results: inspect `diagnostics.py`, then use `io.CSVLogger`,
+  `io.XDMFTimeSeries`, or `io.ResultWriter`.
+- Example workflows: inspect `examples/` after reading `WORKFLOW.md`.
+
+## Agent Rules
+
+- Do not mix constraints, loads, and boundary models.
+- Do not hide the finite-element workflow inside overly broad abstractions.
+- Keep application-specific geometry, source definitions, and parameter choices
+  outside the core platform.
+- Validate imports, syntax, and a small runnable case after structural changes.
+- When changing a public concept, update `CONCEPTS.md`, `WORKFLOW.md`, and the
+  relevant skill references.
+
+## Current Platform Focus
+
+AgentFEM currently focuses on DOLFINx/PETSc workflows, linear elasticity,
+explicit dynamics, weak loads, absorbing boundary models, diagnostics, and XDMF
+output. The architecture should remain open to thermal, multiphysics,
+viscoelastic, anisotropic, and coupled simulations.

agentfem-0.1.1/CONCEPTS.md

@@ -0,0 +1,194 @@
+# AgentFEM Concepts
+
+This file defines the vocabulary that humans and AI agents should use when
+working with AgentFEM.
+
+## Study
+
+The early analysis context: analysis type, physics, dimension, and modeling
+assumptions. Examples include linear static solid mechanics in 2D plane strain,
+transient heat transfer in 2D, or second-order dynamics in 3D. A study is a
+modeling declaration and validation object; it does not assemble or solve.
+Constitutive laws and operators may use it to select modeling assumptions such
+as 2D plane strain or plane stress.
+
+## Model
+
+A lightweight registry of mesh, regions, fields, amplitudes, materials,
+constraints, loads, and boundary models under a study. A model supports checks
+and summaries for humans and agents. It should not hide operator construction
+or solving.
+
+## Mesh
+
+The computational domain and its topology/geometry. Mesh generation may be
+application-specific, but standard mesh import, reading, tagging, and boundary
+measures should use reusable helpers when possible.
+
+A mesh summary records dimension, local/global entity counts, and available
+cell/facet tags. A required-tag check is a modeling guard: it should fail early
+when a material region or boundary label is missing.
+
+External CAE mesh formats such as Abaqus input, NASTRAN bulk data, VTK, and
+COMSOL-exported neutral formats should be converted into a DOLFINx-readable
+format before analysis. AgentFEM treats this as mesh-format conversion, not as a
+physics or solver concern.
+
+## Mesh Region
+
+A named geometric location on the mesh, such as a boundary, material region, or
+point set. Loads and constraints should be described as acting on regions and
+targeting unknown fields.
+
+Boundary regions provide restricted `ds(tag)` measures. Cell regions provide
+restricted `dx(tag)` measures for material-dependent domain integrals.
+
+## Function Space
+
+The finite-element approximation space for scalar, vector, or mixed unknowns.
+Examples include displacement, temperature, pressure, and internal variables.
+
+## Unknown Field
+
+An application-level finite-element unknown that bundles the space, solution
+field, trial function, and test function. Unknown fields let beginner workflows
+say `displacement` or `temperature` instead of manually managing `V`, `u`,
+`du`, and `v`.
+
+## Field
+
+A finite-element function living in a function space. Fields may represent an
+unknown, a state variable, a coefficient, or an output quantity.
+
+AgentFEM fields support eager same-space field algebra. For compatible fields
+on the same function space, operations such as `u + dt * v` immediately compute
+and return a new field with numerical dof values, similar to Cast3M field
+operations or tensor-style array arithmetic. This is intentionally different
+from symbolic weak-form expressions.
+
+## Amplitude
+
+A named time history or scale factor used to drive prescribed data. Amplitudes
+may be constant, ramped, tabular, sinusoidal, or application-defined. They are
+model assets, but they are not finite-element fields: they do not own a
+function space or spatial degrees of freedom.
+
+Loads, constraints, sources, and prescribed data may reference amplitudes.
+
+## Constitutive Law
+
+A local response relation that maps state to stress, flux, tangent, or another
+response quantity. Elastic stress-strain equations belong here. Future
+viscoelasticity, plasticity, thermal conduction, and coupled response laws
+should also live here.
+
+## Material Record
+
+A reusable set of material constants with units and provenance. Material
+records are data assets. Constitutive laws are equations. Keep these concepts
+separate so one material record can be used by different solvers or law
+families when appropriate.
+
+## Material Properties
+
+A typed parameter object created directly by a user or loaded from a material
+record. For example, isotropic elastic properties store `young`, `poisson`, and
+`density`; the constitutive relation uses those properties to compute stress.
+
+## Constraint
+
+An essential or algebraic restriction on degrees of freedom. Dirichlet data,
+periodicity, and MPC relations are constraints.
+
+Neumann force, flux, and traction terms are not constraints.
+
+## Load
+
+A weak right-hand-side source term, such as body force, heat source, Neumann
+flux, or traction.
+
+Natural boundary data is expressed as a load because it enters the weak form,
+not as a direct dof restriction.
+
+## Boundary Model
+
+A weak boundary physics model that is not simply an external load. Robin,
+impedance, convection, and absorbing boundaries are boundary models.
+
+## Form
+
+A UFL expression representing a weak-form contribution before assembly.
+
+## Operator
+
+An assembled vector, matrix, diagonal/lumped operator, or linear algebra object
+that acts on a field or residual.
+
+At the application layer, operators should read like engineering finite-element
+notation: `K u = F`, `M a + C v + K u = F`, or
+`(C/dt + K) T = C T_old/dt + Q`. AgentFEM operator constructors may still
+store UFL expressions before assembly, but their names should communicate the
+matrix/vector role.
+
+Operator contributions should remain addable. A multi-material stiffness may be
+represented explicitly as `K = K1 + K2` or, preferably in audited scripts, as
+`operators.combine(K1, K2, name="K")`.
+
+Model-first helpers such as `model.stiffness(u)` may generate these
+contribution sums from registered materials and regions, but the generated
+operator should still be inspectable.
+
+## Analysis Step
+
+A solve stage under a study. A step records the analysis method, time increment
+when relevant, visible operators, boundary conditions, and solver options.
+
+Examples include a linear static step solving `K U = F` and an implicit Euler
+heat-transfer step solving `(C / dt + K) T_next = C T_old / dt + Q`.
+
+The step should not hide the finite-element meaning. It is the place where
+visible operators become a solveable algebraic problem.
+
+## Element Policy
+
+A reusable interpolation, quadrature, or integration choice. DOLFINx should
+remain the backend, but AgentFEM may eventually name common element policies for
+consistent human and agent workflows.
+
+## State
+
+A collection of fields used by a solver or time integrator. Examples include
+first-order transient states and second-order displacement/velocity/acceleration
+states.
+
+For explicit second-order dynamics, the state may also store a mid-step
+velocity such as `v_mid`, because central-difference boundary damping and
+absorbing boundaries often use half-step velocity data.
+
+## Time Integrator
+
+A time integrator advances a transient state according to a named numerical
+method. In AgentFEM, `time.explicit.central_difference(...)` represents the
+explicit central-difference method, i.e. the Newmark family with `beta=0` and
+`gamma=1/2`.
+
+Integrator names should describe the analysis route first, such as explicit
+dynamics, and expose method parameters through `summary()` rather than forcing
+beginner workflows to start from algorithm parameters.
+
+## Problem
+
+A discrete algebraic or transient system, such as `K x = F`,
+`C xdot + K x = F`, or `M a + C v + K u = F`. Problems solve systems; steps
+describe the analysis stage, studies declare context, and models register
+assets.
+
+## Diagnostic
+
+A scalar or field quantity used to inspect correctness, convergence, stability,
+or physical behavior.
+
+## Benchmark
+
+A standard verification problem with expected quantities and tolerances.
+Benchmarks validate platform capabilities; examples teach workflows.

agentfem-0.1.1/INSTALL.md

@@ -0,0 +1,51 @@
+# Install AgentFEM
+
+AgentFEM depends on the FEniCSx/DOLFINx stack. For the MVP release, use
+conda-forge unless you already maintain a compatible MPI/PETSc/DOLFINx build.
+
+## Recommended Environment
+
+```bash
+mamba create -n agentfem-env -c conda-forge \
+  python=3.11 fenics-dolfinx=0.11 gmsh mpi4py petsc4py \
+  meshio matplotlib jupyterlab ipykernel
+mamba activate agentfem-env
+```
+
+Then install AgentFEM from the repository root:
+
+```bash
+python -m pip install -e .
+```
+
+## Smoke Test
+
+From the `agentfem` repository directory:
+
+```bash
+python examples/static_elasticity_2d.py
+```
+
+From the parent development directory:
+
+```bash
+python agentfem/examples/static_elasticity_2d.py
+```
+
+Expected output:
+
+```text
+Model: cantilever_model
+...
+Static elasticity result: .../examples_output/static_elasticity_2d.xdmf
+```
+
+## Optional Tools
+
+- `meshio`: external CAE mesh conversion, including Abaqus `.inp` and NASTRAN
+  `.bdf/.nas` formats where supported by meshio.
+- `mkdocs`, `mkdocs-material`, `pymdown-extensions`: documentation site.
+- `jupyterlab`, `ipykernel`: notebook workflows.
+
+`requirements.txt` records the tested MVP stack, but direct pip installation of
+DOLFINx/PETSc/MPI packages may be fragile across platforms.

agentfem-0.1.1/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include INSTALL.md
+include WORKFLOW.md
+include CONCEPTS.md
+include AGENT_GUIDE.md
+include pyproject.toml
+recursive-include materials/data *.json
+recursive-include docs *.md
+recursive-include skills *.md
+recursive-include examples *.py *.md
+recursive-include benchmarks *.py *.md
+recursive-include elements *.md
+recursive-include operators *.md
+prune site
+prune examples_output
+global-exclude .DS_Store
+global-exclude __pycache__
+global-exclude *.py[cod]

agentfem-0.1.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: agentfem
+Version: 0.1.1
+Summary: Agent-oriented finite-element workflow tools built on DOLFINx/PETSc.
+Author: Haoming Luo
+Project-URL: Homepage, https://github.com/haoming-luo/agentfem
+Project-URL: Repository, https://github.com/haoming-luo/agentfem
+Project-URL: Issues, https://github.com/haoming-luo/agentfem/issues
+Project-URL: Documentation, https://github.com/haoming-luo/agentfem#readme
+Keywords: finite-element,fem,cae,dolfinx,fenicsx,scientific-computing,agent-oriented
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: mpi4py
+Provides-Extra: mesh-formats
+Requires-Dist: meshio; extra == "mesh-formats"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: pymdown-extensions; extra == "docs"
+Provides-Extra: notebooks
+Requires-Dist: jupyterlab; extra == "notebooks"
+Requires-Dist: ipykernel; extra == "notebooks"
+Requires-Dist: nbformat; extra == "notebooks"
+Requires-Dist: nbclient; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# AgentFEM
+
+AgentFEM is an agent-oriented finite-element workflow platform built on
+DOLFINx/PETSc. It aims to make finite-element scripts readable to both
+researchers and AI agents by keeping the standard CAE workflow visible:
+
+```text
+Study -> Model -> Mesh/Regions -> Fields -> Materials -> Loads/Constraints
+      -> Operators -> Step -> Solve -> Diagnostics/Output
+```
+
+The current MVP focuses on linear elasticity, transient heat conduction,
+explicit elastodynamics, reusable loads and constraints, material records,
+operator-level `K/M/C/F` notation, model inspection, and ParaView/XDMF output.
+
+## Why AgentFEM
+
+- Finite-element language for humans: `model.linear_static_step(...)`,
+  `model.tree()`, `operators.xtmx(...)`, and field algebra such as
+  `u_next = u + dt * v + 0.5 * dt**2 * a`.
+- Inspectable objects for agents: `study.summary()`, `model.manifest()`,
+  `operator.summary()`, and step summaries.
+- Transparent layers: daily workflows use `models`, `fields`, `loads`,
+  `operators`, and `problems`; advanced users can still drop to `forms`,
+  `assembly`, PETSc, or DOLFINx when needed.
+
+## Install
+
+AgentFEM currently expects a working FEniCSx/DOLFINx stack. The recommended
+route is conda-forge:
+
+```bash
+mamba create -n agentfem-env -c conda-forge \
+  python=3.11 fenics-dolfinx=0.11 gmsh mpi4py petsc4py \
+  meshio matplotlib jupyterlab ipykernel
+mamba activate agentfem-env
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+After the first PyPI release, users will install AgentFEM with:
+
+```bash
+python -m pip install agentfem
+```
+
+`requirements.txt` records the tested MVP stack and optional documentation /
+notebook helpers. Pure pip installation of DOLFINx can be fragile because MPI,
+PETSc, and HDF5 must match.
+
+## Quick Start
+
+Run the beginner static-elasticity example:
+
+```bash
+python examples/static_elasticity_2d.py
+```
+
+From the parent development directory used in this workspace:
+
+```bash
+python agentfem/examples/static_elasticity_2d.py
+```
+
+The output is written to `examples_output/static_elasticity_2d.xdmf` and can be
+opened in ParaView.
+
+## Minimal Workflow
+
+```python
+from mpi4py import MPI
+import numpy as np
+
+from agentfem import fields, mesh, models, studies
+from agentfem.constitutive import elasticity
+
+study = studies.linear_static(
+    physics="solid_mechanics",
+    dimension=2,
+    assumption="plane_strain",
+)
+
+domain = mesh.rectangle(
+    lower=(0.0, 0.0),
+    upper=(1.0, 0.2),
+    cells=(40, 8),
+    comm=MPI.COMM_WORLD,
+    cell_type="quadrilateral",
+)
+model = models.create(study=study, mesh=domain, name="cantilever")
+
+u = model.field(fields.displacement(domain, degree=1))
+model.material(elasticity.isotropic_elastic(young=210e9, poisson=0.3, density=7800))
+
+left = mesh.boundary(domain, lambda x: np.isclose(x[0], 0.0), name="left", tag=1)
+right = mesh.boundary(domain, lambda x: np.isclose(x[0], 1.0), name="right", tag=2)
+model.fix(u, on=left, value=0.0)
+model.traction(value=(0.0, -1.0e6), on=right)
+
+step = model.linear_static_step(target=u)
+step.solve()
+
+print(model.tree())
+```
+
+The `Step` path is the recommended public workflow. It still exposes the
+operator system for review:
+
+```python
+print(step.system.summary())
+```
+
+## Public Workflow Modules
+
+Beginner and agent-generated workflows should prefer:
+
+```python
+from agentfem import studies, mesh, models, fields, materials, constitutive
+from agentfem import amplitudes, constraints, loads, operators, problems
+from agentfem import solvers, time, io, diagnostics
+```
+
+Lower-level modules such as `forms`, `assembly`, `spaces`, and `kernel` remain
+available for extension work and debugging, but they should not be the first
+thing a new model exposes.
+
+## Examples
+
+- `examples/static_elasticity_2d.py`: beginner linear-static mechanics example.
+- `examples/transient_heat_2d.py`: intermediate first-order transient heat solve.
+- `examples/wave_packet_plate_2d.py`: advanced explicit dynamics wave example.
+- `examples/wave_packet_inclusion_2d.py`: advanced wave propagation with
+  regional material assignment and absorbing/periodic boundary handling.
+
+## Documentation
+
+- `WORKFLOW.md`: standard AgentFEM modeling sequence.
+- `INSTALL.md`: tested MVP environment and smoke-test command.
+- `CONCEPTS.md`: shared vocabulary for finite-element and agent workflows.
+- `AGENT_GUIDE.md`: first file for AI agents working in this repository.
+- `docs/`: design notes, module map, validation notes, and extension rules.
+- `docs/publishing.md`: PyPI release checklist and Trusted Publisher setup.
+- `site/index.html`: generated static documentation site.
+
+Rebuild the local documentation site with:
+
+```bash
+python build_docs.py
+```
+
+## MVP Status
+
+AgentFEM is a research-oriented MVP. It is not yet a general-purpose CAE
+replacement. The stable direction is:
+
+- model-first workflows for common analyses,
+- operator-first workflows for transparent research code,
+- structured model manifests for agents,
+- examples and benchmarks that make assumptions explicit.

agentfem-0.1.1/README.md

@@ -0,0 +1,163 @@
+# AgentFEM
+
+AgentFEM is an agent-oriented finite-element workflow platform built on
+DOLFINx/PETSc. It aims to make finite-element scripts readable to both
+researchers and AI agents by keeping the standard CAE workflow visible:
+
+```text
+Study -> Model -> Mesh/Regions -> Fields -> Materials -> Loads/Constraints
+      -> Operators -> Step -> Solve -> Diagnostics/Output
+```
+
+The current MVP focuses on linear elasticity, transient heat conduction,
+explicit elastodynamics, reusable loads and constraints, material records,
+operator-level `K/M/C/F` notation, model inspection, and ParaView/XDMF output.
+
+## Why AgentFEM
+
+- Finite-element language for humans: `model.linear_static_step(...)`,
+  `model.tree()`, `operators.xtmx(...)`, and field algebra such as
+  `u_next = u + dt * v + 0.5 * dt**2 * a`.
+- Inspectable objects for agents: `study.summary()`, `model.manifest()`,
+  `operator.summary()`, and step summaries.
+- Transparent layers: daily workflows use `models`, `fields`, `loads`,
+  `operators`, and `problems`; advanced users can still drop to `forms`,
+  `assembly`, PETSc, or DOLFINx when needed.
+
+## Install
+
+AgentFEM currently expects a working FEniCSx/DOLFINx stack. The recommended
+route is conda-forge:
+
+```bash
+mamba create -n agentfem-env -c conda-forge \
+  python=3.11 fenics-dolfinx=0.11 gmsh mpi4py petsc4py \
+  meshio matplotlib jupyterlab ipykernel
+mamba activate agentfem-env
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+After the first PyPI release, users will install AgentFEM with:
+
+```bash
+python -m pip install agentfem
+```
+
+`requirements.txt` records the tested MVP stack and optional documentation /
+notebook helpers. Pure pip installation of DOLFINx can be fragile because MPI,
+PETSc, and HDF5 must match.
+
+## Quick Start
+
+Run the beginner static-elasticity example:
+
+```bash
+python examples/static_elasticity_2d.py
+```
+
+From the parent development directory used in this workspace:
+
+```bash
+python agentfem/examples/static_elasticity_2d.py
+```
+
+The output is written to `examples_output/static_elasticity_2d.xdmf` and can be
+opened in ParaView.
+
+## Minimal Workflow
+
+```python
+from mpi4py import MPI
+import numpy as np
+
+from agentfem import fields, mesh, models, studies
+from agentfem.constitutive import elasticity
+
+study = studies.linear_static(
+    physics="solid_mechanics",
+    dimension=2,
+    assumption="plane_strain",
+)
+
+domain = mesh.rectangle(
+    lower=(0.0, 0.0),
+    upper=(1.0, 0.2),
+    cells=(40, 8),
+    comm=MPI.COMM_WORLD,
+    cell_type="quadrilateral",
+)
+model = models.create(study=study, mesh=domain, name="cantilever")
+
+u = model.field(fields.displacement(domain, degree=1))
+model.material(elasticity.isotropic_elastic(young=210e9, poisson=0.3, density=7800))
+
+left = mesh.boundary(domain, lambda x: np.isclose(x[0], 0.0), name="left", tag=1)
+right = mesh.boundary(domain, lambda x: np.isclose(x[0], 1.0), name="right", tag=2)
+model.fix(u, on=left, value=0.0)
+model.traction(value=(0.0, -1.0e6), on=right)
+
+step = model.linear_static_step(target=u)
+step.solve()
+
+print(model.tree())
+```
+
+The `Step` path is the recommended public workflow. It still exposes the
+operator system for review:
+
+```python
+print(step.system.summary())
+```
+
+## Public Workflow Modules
+
+Beginner and agent-generated workflows should prefer:
+
+```python
+from agentfem import studies, mesh, models, fields, materials, constitutive
+from agentfem import amplitudes, constraints, loads, operators, problems
+from agentfem import solvers, time, io, diagnostics
+```
+
+Lower-level modules such as `forms`, `assembly`, `spaces`, and `kernel` remain
+available for extension work and debugging, but they should not be the first
+thing a new model exposes.
+
+## Examples
+
+- `examples/static_elasticity_2d.py`: beginner linear-static mechanics example.
+- `examples/transient_heat_2d.py`: intermediate first-order transient heat solve.
+- `examples/wave_packet_plate_2d.py`: advanced explicit dynamics wave example.
+- `examples/wave_packet_inclusion_2d.py`: advanced wave propagation with
+  regional material assignment and absorbing/periodic boundary handling.
+
+## Documentation
+
+- `WORKFLOW.md`: standard AgentFEM modeling sequence.
+- `INSTALL.md`: tested MVP environment and smoke-test command.
+- `CONCEPTS.md`: shared vocabulary for finite-element and agent workflows.
+- `AGENT_GUIDE.md`: first file for AI agents working in this repository.
+- `docs/`: design notes, module map, validation notes, and extension rules.
+- `docs/publishing.md`: PyPI release checklist and Trusted Publisher setup.
+- `site/index.html`: generated static documentation site.
+
+Rebuild the local documentation site with:
+
+```bash
+python build_docs.py
+```
+
+## MVP Status
+
+AgentFEM is a research-oriented MVP. It is not yet a general-purpose CAE
+replacement. The stable direction is:
+
+- model-first workflows for common analyses,
+- operator-first workflows for transparent research code,
+- structured model manifests for agents,
+- examples and benchmarks that make assumptions explicit.