# Agent acceptance contract

An AI-native claim should be tested from the package that a user receives,
not from an editable source checkout or a maintainer's memory. AgentFEM's
deterministic acceptance route starts in a clean directory and requires the
installed wheel to expose and complete this sequence:

```text
doctor -> capabilities -> init -> check -> run -> inspect -> verify
```

The release gate exercises every installed project template through that
sequence. It also rejects a constitutive maturity claim when the benchmark
registry does not provide the minimum evidence appropriate to that claim.
Run it against a candidate distribution with:

```bash
python release_gate.py \
  --dist dist \
  --smoke \
  --report agent-acceptance.json
```

The report records the runtime fingerprint, capability discovery, evidence
audit, and result lifecycle for each template. It can be produced on Linux,
macOS, or WSL2 without changing the scientific case.

This deterministic gate proves that the machine interfaces needed by an agent
are present and coherent. It does **not** impersonate an unfamiliar AI agent.
A fresh-agent trial remains a separate behavioral test: the agent must choose
an applicable model, preserve visible scientific choices, and explain why the
result is or is not supported by its evidence. Successful execution alone is
not scientific validation.

Prepare an immutable trial bundle from the exact release candidate first:

```bash
python tools/prepare_agent_trial.py \
  --wheel dist/agentfem-*.whl \
  --output fresh-agent-trial
```

The bundle contains one bounded mechanics task, an empty project directory,
the exact wheel, its SHA-256 digest, the source commit and an independent
review checklist. Give `TASK.md` and the bundle to a genuinely fresh agent;
the maintainer who developed the candidate must not silently complete or
repair the project.

After a genuinely fresh task has completed, retain its transcript and final
scientific explanation beside the project, then record the trial with:

```bash
python tools/agent_trial_acceptance.py \
  --project fresh-agent-project \
  --agent "Codex/<model identity>" \
  --transcript fresh-agent-project/agent-transcript.md \
  --explanation fresh-agent-project/explanation.md \
  --fresh-context --human-interventions 0 --reviewed-explanation \
  --source-commit <commit-from-trial-contract> \
  --wheel fresh-agent-trial/agentfem-*.whl \
  --contract fresh-agent-trial/trial-contract.json \
  --report fresh-agent-project/agent-trial-acceptance.json
```

The recorder independently reruns `doctor`, `capabilities`, `check`, `inspect`
and `verify`. It refuses a source checkout, inherited project context, missing
transcript, human repair intervention, unverified result, or unreviewed
explanation. The reviewer confirms scientific adequacy; the recorder never
pretends that prose quality can be inferred from a successful solve.
Candidate version, source commit, wheel digest, transcript digest and
explanation digest are retained and cross-checked against the immutable trial
contract, so an older or substituted successful trial cannot promote a newer
release candidate.

# Agent entry

AgentFEM exposes one public workflow to people, scripts, IDEs, GUIs, and AI
agents. An agent should construct or revise the readable `case.py`, use the
structured CLI for operations, and accept results only through their explicit
status and scientific evidence.

For a direct tool connection, install the official
[AgentFEM MCP companion](mcp.md). It exposes seven typed lifecycle operations
to Codex, Claude, and other compatible hosts while leaving the model source,
solver, and evidence in normal AgentFEM projects.

## Machine-readable entrypoints

| Resource | Purpose |
| --- | --- |
| `/llms.txt` | Short discovery document for language-model tools |
| `/agentfem.json` | Versioned documentation and command manifest |
| `installation` in `/agentfem.json` | Tested runtime and official/mainland-China environment commands |
| `src/agentfem/knowledge/catalog.json` | Scientific cards, formulas, evidence, consumers, and maturity |
| `agentfem doctor --json` | Environment capability check |
| `agentfem workspace --json` | Runtime-independent project custody check |
| `agentfem capabilities --json` | Public API, providers, maturity, and benchmark evidence |
| `agentfem check --json` | Static project and upgrade check |
| `agentfem run --json` | Addressable execution result |
| `agentfem inspect --json` | Result and artifact discovery |
| `agentfem telemetry status --json` | Exact privacy mode, queue and reviewed delivery routes |
| `agentfem telemetry route auto|global|china --json` | Optional transport preference without location inference |
| `agentfem inspect-abaqus model.inp --json` | Side-effect-free legacy-deck inventory |
| `agentfem inspect-user-material material.for --json` | Fingerprinted UMAT/UHYPER source inventory and migration route |
| `agentfem migrate-abaqus model.inp ./project --json` | Fail-closed Abaqus migration project |
| `agentfem lower-abaqus ./project --reviewed-by NAME --unit-system SI --json` | Inactive reviewed native draft for the eligible subset |

## Safe operating sequence

```text
discover → doctor → protect workspace → init/open → inspect project → edit case.py → check
         → run → inspect structured result → verify policy → publish or revise
```

If no environment exists, consume the installation contract from
`/agentfem.json` or follow the installation guide. Do not infer that a PyPI
wheel can provision DOLFINx/PETSc, and do not mix conda channels for the
compiled numerical stack.

An agent must not infer scientific validity from a zero exit code. It should
inspect convergence, requested outputs, quality policy, applicability limits,
benchmark evidence, and any explicit failure record.

On WSL, an agent must not replace or unregister a distribution until
`agentfem workspace --json` reports that project data is protected from
distribution removal. Use `agentfem workspace --protect`; for the Complete
Runtime, use its lifecycle scripts rather than reproducing destructive WSL
commands.

For an Abaqus migration, inspect before creating a project. Preserve the
complete source graph and review every issue in `migration.json`; never remove
an element suffix, collapse Part/Instance scopes, or execute a generated
material candidate merely because its syntax was recognized.
When the native subset is eligible, record reviewer and unit interpretation,
inspect the inactive draft and decision fingerprint, and activate separately.
If a deck references user material, inspect its Fortran source separately;
never interpret an `adapter_candidate` report as executable compatibility.

## Start here

- [Installed project workflow](../getting_started.md)
- [Connect with AgentFEM MCP](mcp.md)
- [Agent and GUI integration](../agent_gui_integration.md)
- [Scientific trust and verification](../scientific_verification.md)
- [Project upgrades](../project_upgrades.md)
- [AgentFEM skill](skill.md)
- [Agent acceptance contract](acceptance.md)

# Connect AgentFEM with MCP

AgentFEM MCP is AgentFEM's official, lightweight connection to
Codex, Claude, or another Model Context Protocol host. It is not an AI model
or a separate simulation product; AgentFEM remains the finite-element engine.

```text
AI agent → seven typed MCP tools → AgentFEM CLI
         → Study → Model → Step → SimulationResult
         → FEniCSx / PETSc / MPI
```

## Install for Codex

Install AgentFEM first and confirm `agentfem doctor`. Then choose the project
root the agent may access:

```bash
codex mcp add agentfem \
  --env AGENTFEM_MCP_ROOTS=/absolute/path/to/AgentFEMProjects \
  -- uvx --from agentfem-mcp agentfem-mcp
codex mcp list
```

The adapter is published on
[PyPI](https://pypi.org/project/agentfem-mcp/) and discoverable through the
[official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.haoming-luo%2Fagentfem)
under `io.github.haoming-luo/agentfem`.

## Open in a desktop client

On macOS or Linux, a supporting desktop client can open the tiny
[AgentFEM 0.1.0 MCPB bundle](https://github.com/haoming-luo/agentfem-mcp/releases/download/v0.1.0/AgentFEM-0.1.0.mcpb)
and ask for the single project folder AgentFEM may use. The bundle installs
only the official connection from PyPI; it does not duplicate or replace the
AgentFEM scientific runtime. Windows currently uses the explicit WSL2 setup
rather than an unverified native bridge.

The companion
[SHA-256 file](https://github.com/haoming-luo/agentfem-mcp/releases/download/v0.1.0/AgentFEM-0.1.0.mcpb.sha256)
lets an agent verify the download before opening it.

Begin with a concrete request:

> Use AgentFEM to create, validate, run, verify, and briefly explain a 2D
> cantilever. Keep the project and result paths visible.

The adapter discovers the normal AgentFEM executable, including the documented
Complete Runtime and common conda environments. If a desktop host cannot see
it, set `AGENTFEM_COMMAND` to the absolute executable path.

## Why the surface is small

The adapter exposes seven lifecycle tools: describe the runtime, create a
project, validate it, inspect it, submit a run, read run status, and read a
result. The surrounding agent already has normal file-editing ability; MCP
does not duplicate materials, elements, or every solver option as hundreds of
fragile tools.

Numerical work runs in a separate process so PETSc and MPI do not enter the
agent host's lifetime. Paths must remain under approved roots, no shell command
is accepted, and the server cannot access the network. A successful process is
reported as `completed`; it becomes `verified` or `validated` only when the
AgentFEM result contains the corresponding evidence.

See the [public interface repository](https://github.com/haoming-luo/agentfem-mcp)
for Claude-compatible configuration, security boundaries, release evidence,
and the portable AgentFEM workflow Skill.

# AgentFEM skill

The repository ships a standards-compatible AgentFEM skill that teaches coding
agents the public workflow, project lifecycle, result contract, scientific
validation boundary, and safe extension rules.

The canonical source is
[`skills/agentfem/SKILL.md`](https://github.com/haoming-luo/agentfem/blob/main/skills/agentfem/SKILL.md).
It is versioned with the code so that agent behavior can evolve alongside API
and project-format changes.

The directory is self-contained: keep `SKILL.md`, `agents/`, and `references/`
together. A skill-aware agent can load it directly from the repository. For a
personal Codex installation, copy or link the complete `skills/agentfem/`
directory to `$CODEX_HOME/skills/agentfem/` (or
`~/.codex/skills/agentfem/` when `CODEX_HOME` is unset); copying only
`SKILL.md` omits the scientific and implementation references.

The main skill stays concise and routes detailed material progressively:
workflow guidance is read for modeling tasks, while concepts, module ownership,
validation, and extension rules are loaded only when the task requires them.

## What the skill is for

- discover and validate an AgentFEM installation;
- create and operate projects through the public workflow;
- interpret structured failures and simulation results;
- preserve the distinction between execution and scientific verification;
- route reusable finite-element functionality to the correct module;
- upgrade older projects without silently rewriting scientific intent.
- freeze runtime and scientific-input evidence, run safe local ensembles, and
  build traceable convergence/loading/response experiments;
- inspect declared private extensions without automatically executing or
  installing untrusted packages.

The skill does not guess API keywords. It begins with
`agentfem.public_api("core")`, `models.model_api("core")`, and the provider
contracts reported by `agentfem capabilities --json`. Compatibility names may
remain executable during 0.2.x, but new cases use the canonical vocabulary.

The skill complements the machine-readable `/agentfem.json` manifest and
scientific `src/agentfem/knowledge/catalog.json`; it does not replace the public API or the
solver's deterministic checks.