[codex] open-source baseline

.devcontainer/devcontainer.json

@@ -0,0 +1,18 @@
+{
+  "name": "FEA Copilot",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+  "postCreateCommand": "python3 -m pip install --upgrade pip && python3 -m pip install -e '.[dev]'",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/python/current/bin/python",
+        "python.testing.pytestEnabled": true
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-toolsai.jupyter"
+      ]
+    }
+  }
+}

.github/ISSUE_TEMPLATE/benchmark_case.yml

@@ -0,0 +1,48 @@
+name: Benchmark case
+description: Contribute or request a reproducible linear-elastic benchmark case.
+title: "[Benchmark]: "
+labels:
+  - benchmark
+body:
+  - type: input
+    id: geometry
+    attributes:
+      label: Geometry or case name
+      placeholder: cantilever beam, plate with hole, L-bracket
+    validations:
+      required: true
+  - type: textarea
+    id: definition
+    attributes:
+      label: Problem definition
+      description: Geometry, material, load, and boundary conditions.
+    validations:
+      required: true
+  - type: textarea
+    id: assumptions
+    attributes:
+      label: Assumptions
+      description: List simplifications explicitly.
+    validations:
+      required: true
+  - type: textarea
+    id: reference
+    attributes:
+      label: Reference result and source
+      description: Include the analytical, handbook, or benchmark source and the expected result.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproducible command
+      description: Include the command or script path needed to reproduce the case.
+    validations:
+      required: true
+  - type: input
+    id: tolerance
+    attributes:
+      label: Expected tolerance
+      placeholder: e.g. 2% on max deflection
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Report a reproducible defect in parsing, solver execution, artifacts, or docs.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What failed, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Include the exact command or prompt and any relevant files.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, backend mode, OS, Docker availability.
+  - type: textarea
+    id: artifacts
+    attributes:
+      label: Artifact Paths Or Logs
+      description: Point to `run_result.json`, `backend_status.json`, or log excerpts if available.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security reporting guidance
+    url: https://github.com/suchipizza/hellostress/security/policy
+    about: Do not post vulnerabilities publicly. Follow the disclosure guidance in SECURITY.md.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a scoped improvement to supported workflows, docs, or contributor tooling.
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user or contributor problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Keep this concrete. Mention example directories, validation cases, or modules if relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Validation or evidence
+      description: What benchmark, example, or workflow would prove the feature is useful?

.github/ISSUE_TEMPLATE/validation_case.yml

@@ -0,0 +1,52 @@
+name: Validation case
+description: Propose a reproducible validation case with a public reference and tolerance.
+title: "[Validation]: "
+labels:
+  - validation
+body:
+  - type: input
+    id: case_name
+    attributes:
+      label: Case name
+      placeholder: cantilever beam hand calc, rectangular plate, solver comparison
+    validations:
+      required: true
+  - type: dropdown
+    id: reference_type
+    attributes:
+      label: Reference type
+      options:
+        - analytical
+        - hand calculation
+        - numerical benchmark
+        - solver comparison
+    validations:
+      required: true
+  - type: textarea
+    id: assumptions
+    attributes:
+      label: Assumptions
+      description: Geometry, loads, boundary conditions, simplifications.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result and tolerance
+      description: Include units and tolerance policy.
+    validations:
+      required: true
+  - type: textarea
+    id: reference_source
+    attributes:
+      label: Public reference source
+      description: Cite the handbook, paper, or formula source.
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Reproducible command
+      description: Include the exact command or script path.
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+- what changed
+- why it changed
+- user or contributor impact
+
+## Validation
+
+- [ ] `python3 -m py_compile app.py fea_engine/*.py templates/*.py tests/*.py`
+- [ ] `pytest -q`
+- [ ] `./examples/smoke_test.sh`
+- [ ] Docker smoke path, if relevant
+
+## Scope Check
+
+- [ ] docs and examples match the actual supported behavior
+- [ ] new validation claims include reproducible evidence
+- [ ] unrelated refactors were not mixed into this PR

.github/workflows/ci.yml

@@ -24,11 +24,28 @@ jobs:
           pip install '.[dev]'
 
       - name: Compile Python sources
-        run: python -m py_compile app.py fea_engine/*.py templates/*.py tests/*.py
+        run: python -m py_compile app.py fea_engine/*.py templates/*.py tests/*.py tools/*.py validation/public_formula_checks/*.py validation/mesh_convergence/*.py validation/roark_formulas/*.py
 
       - name: Run tests
         run: pytest -q
 
+      - name: Packaging sanity check
+        run: |
+          python -c "import importlib.metadata as md; assert md.version('feacopilot') == '0.3.0'"
+          feacopilot --help >/dev/null
+
+      - name: Check markdown links
+        run: python3 tools/check_markdown_links.py
+
+      - name: Run example smoke tests
+        run: ./examples/smoke_test.sh
+
+      - name: Run analytical benchmark smoke test
+        run: ./validation/roark_formulas/run.sh
+
+      - name: Run validation suite
+        run: make validate
+
       - name: Run CLI artifact workflow smoke test
         run: |
           export FEA_RUNS_DIR="$RUNNER_TEMP/fea-runs"

.gitignore

@@ -3,3 +3,8 @@
 __pycache__/
 *.pyc
 .DS_Store
+feacopilot.egg-info/
+tmp-runs/
+examples/**/output/
+validation/analytical_beam/output/
+validation/public_formula_checks/**/output/

AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+## Project Purpose
+
+FEA Copilot is a narrow-scope open-source engineering tool that turns supported natural-language structural prompts into transparent, reproducible beam, plate, bracket, and plate-with-hole workflows. The repo is optimized for humans and coding agents to inspect, run, validate, and extend.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e '.[dev]'
+```
+
+Optional Docker backend:
+
+```bash
+docker pull dolfinx/dolfinx:v0.7.3
+```
+
+## Run Tests
+
+```bash
+make test
+```
+
+Docker smoke path:
+
+```bash
+make validate-docker
+RUN_DOCKER_SMOKE=1 pytest -q tests/test_integration_docker_smoke.py --run-docker-smoke
+```
+
+## Run The Minimal Example
+
+```bash
+./examples/minimal/run.sh
+```
+
+Or directly:
+
+```bash
+feacopilot --prompt-file examples/minimal/prompt.txt --solver-mode mock --output json
+```
+
+## Run Validation
+
+```bash
+make validate
+python3 tools/run_validation.py --list
+```
+
+## Project Structure
+
+- `fea_engine/`: parser, validation, service orchestration, solver integration, artifact handling, and visualization.
+- `templates/`: Jinja templates for generated solver scripts plus contributor scaffolds.
+- `examples/`: runnable examples and extension stubs.
+- `validation/`: committed comparisons, benchmark intake scaffolds, and convergence workflows.
+- `docs/`: quickstart, architecture, validation, launch, and contribution docs.
+- `docs/repo-map.md`: concise orientation file for agents and maintainers.
+- `.github/`: CI plus issue and PR templates.
+- `tests/`: unit, golden, CLI, artifact, visualization, and gated Docker smoke tests.
+
+## Rules For Modifying Examples
+
+- Keep example commands reproducible from a fresh editable install.
+- Every example directory should include `README.md`, `prompt.txt`, `run.sh`, and an expected-output artifact or note.
+- If an example is analytical-only or backend-limited, state that explicitly and keep the script deterministic.
+- Do not claim benchmark accuracy unless the reference result, source, tolerance, and command are committed in that example or validation case.
+
+## Rules For Adding Validation Cases
+
+- Include the problem definition, assumptions, reproducible command, reference result, tolerance, and source of truth.
+- Prefer committed `expected_metrics.json` or a similarly machine-readable artifact.
+- If the reference comes from a handbook or paper, cite the source in the case README and avoid paraphrasing it as if it were produced by the repository.
+- Mesh convergence claims require either committed convergence data or a script that regenerates it.
+
+## Rules For Solver Adapters
+
+- Preserve the current public CLI and artifact contract unless there is a strong reason to change it.
+- New adapters must write the same bundle shape: generated script, logs, metrics, `backend_status.json`, and `backend_metadata.json`.
+- Unsupported environments should fail clearly with actionable messages.
+- Add coverage in `tests/` for adapter behavior, error normalization, and artifact integrity.
+
+## Definition Of Done For Agent Changes
+
+- The change is scoped to a clear user-facing or contributor-facing outcome.
+- Docs and examples stay consistent with the actual supported scope.
+- Relevant tests pass locally, or the blocking reason is stated explicitly.
+- New files are linked from the README or relevant docs.
+- No fake badges, benchmark claims, citations, or community metrics are introduced.

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable repository-surface changes should be recorded here.
+
+## Unreleased
+
+### Added
+
+- open-source launch README centered on runnable examples, validation, and contribution paths
+- agent-facing repository guide in `AGENTS.md`
+- example, validation, and benchmark contribution scaffolding
+- GitHub issue templates, PR template, roadmap, citation metadata, and launch checklist
+- example smoke-test script and CI coverage for repository examples
+
+### Changed
+
+- contribution guidance now points to reproducible examples and validation evidence instead of phase-plan milestones
+
+## 0.3.0
+
+Current package version from `pyproject.toml`.
+
+- CLI entry point for prompt execution, inspection, export, workspace reporting, and cleanup
+- artifact schema versioning and validation
+- gated Docker smoke tests

CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+title: FEA Copilot
+message: "If you use FEA Copilot in teaching, benchmarking, or research, please cite the repository."
+type: software
+authors:
+  - name: HelloStress
+version: 0.3.0
+license: Apache-2.0
+repository-code: https://github.com/suchipizza/hellostress
+url: https://github.com/suchipizza/hellostress
+abstract: "Natural-language FEA copilot for reproducible linear-elastic beam and plate workflows."