diff --git a/.gitea/ISSUE_TEMPLATE/bug_report.md b/.gitea/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..33b3fbe
--- /dev/null
+++ b/.gitea/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Report incorrect results, crashes, or broken workflows
+title: "[bug] "
+labels: bug
+---
+
+## Summary
+
+<!-- What went wrong? -->
+
+## Expected behavior
+
+## Actual behavior
+
+## Reproduction
+
+<!-- Minimal steps, XML snippet or path under data/cases/, API request JSON, etc. -->
+
+## Environment
+
+- OS:
+- Node (`node -v`):
+- Commit / tag:
+
+## Logs / output
+
+```
+(paste relevant logs)
+```
diff --git a/.gitea/ISSUE_TEMPLATE/feature_request.md b/.gitea/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..3c44d2f
--- /dev/null
+++ b/.gitea/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Propose new physics, API fields, or GUI workflow improvements
+title: "[feature] "
+labels: enhancement
+---
+
+## Problem / motivation
+
+<!-- What engineering workflow is painful today? -->
+
+## Proposal
+
+<!-- Concrete behavior, API shape, or UI change -->
+
+## Acceptance criteria
+
+<!-- What tests / goldens / docs must change? -->
+
+## References
+
+<!-- Papers, field data, or internal notes -->
diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..32f9e2c
--- /dev/null
+++ b/.gitea/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,31 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Docs only
+- [ ] Refactor (no intended behavior change)
+
+## Risk / impact
+
+- [ ] Touches solver numerics (`solver-c`)
+- [ ] Touches API contract (`solver-api`)
+- [ ] Touches GUI (`gui-ts`)
+- [ ] Updates goldens / deterministic hashes
+
+## Testing
+
+```bash
+make test
+```
+
+Paste output or note what could not be run.
+
+## Documentation
+
+- [ ] Updated `Agents/MATH_SPEC.md` (if equations/BCs changed)
+- [ ] Updated `Agents/COMPUTE_PLAN.md` (if roadmap/gaps changed)
+- [ ] Updated `README.md` / `docs/engineering/*` as needed
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d37e364
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial public-ish repository layout: `solver-c`, `solver-api`, `gui-ts`, regression data, engineering docs, and agent handoff docs.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..13e5922
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for helping improve this project. The goal is **deterministic, explainable** rod-string / dynamometer simulation: C is the numerical source of truth; Node orchestrates; the GUI is workflow and visualization.
+
+## Before you start
+
+Read (in order):
+
+1. [AGENTS.md](AGENTS.md)
+2. [Agents/MATH_SPEC.md](Agents/MATH_SPEC.md)
+3. [Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md)
+
+## Local development
+
+### Prerequisites
+
+- `gcc`, `make`
+- Node.js 20+ and `npm`
+- Docker (optional, for compose / CI image)
+
+### Build C drivers (JSON on stdin)
+
+From the repository root, follow the `gcc` commands in [README.md](README.md) or use CMake:
+
+```bash
+cmake -S solver-c -B solver-c/build
+cmake --build solver-c/build
+```
+
+The API expects `solver-c/solver_main` and `solver-c/solver_fea_main` in the repo root layout (see `docker-compose.yml` and `solver-api`).
+
+### Run tests
+
+```bash
+make test
+```
+
+This runs `solver-api` Vitest, `gui-ts` Vitest, and `solver-c/test_solver`.
+
+## Pull requests
+
+- Keep changes focused; avoid drive-by refactors.
+- If you change solver equations or boundary conditions, update [Agents/MATH_SPEC.md](Agents/MATH_SPEC.md) and the gap table in [Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md).
+- If you change the JSON contract or HTTP responses, bump `schemaVersion` only with an explicit migration plan (see [AGENTS.md](AGENTS.md)).
+
+## Coding style
+
+- Match existing formatting and naming in each package (`solver-c`, `solver-api`, `gui-ts`).
+- Prefer small, test-backed changes for numerics.
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
diff --git a/README.md b/README.md
index 7d6081f..6f54c03 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 Deterministic **C** numerical core (FDM + FEA), **Node** API for XML and orchestration, **TypeScript** GUI for workflow. See **[AGENTS.md](AGENTS.md)** for agent rules and **[Agents/MATH_SPEC.md](Agents/MATH_SPEC.md)** for equations and paper citations.
 
+Contributor workflow: **[CONTRIBUTING.md](CONTRIBUTING.md)** · Security: **[SECURITY.md](SECURITY.md)** · History: **[CHANGELOG.md](CHANGELOG.md)**
+
 ## Repository layout
 
 | Directory | Purpose |
@@ -24,6 +26,31 @@ Build a transparent, deterministic rod-string and wellbore mechanics platform th
 - Inspectability of imported case data and solver assumptions.
 - Multi-model validation (FDM vs FEA) with clear comparison metadata.
 
+## Forge metadata (Gitea)
+
+Repository **title**, **description**, **topics**, default branch protections, and **Releases** are configured in the Gitea UI (they are not stored as files in git).
+
+Suggested values you can paste into the repo settings page for [connermajic/rods](https://gitea.majicmedia.ca/connermajic/rods.git):
+
+- **Name / title:** `Rods` (or `Rods — rod-string solver stack`)
+- **Description:** `Deterministic C core (FDM+FEA) + Node XML/SI API + TypeScript GUI for sucker-rod dynamometer workflows.`
+- **Topics / keywords:** `sucker-rod`, `dynamometer`, `rod-pumping`, `finite-difference`, `finite-element`, `wellbore-trajectory`, `oil-and-gas`, `typescript`, `nodejs`, `c`
+- **Website:** leave blank until you publish a demo URL
+
+### Releases
+
+Releases are optional until you want a downloadable snapshot. When you are ready:
+
+1. Pick a version (for example `v0.1.0`).
+2. Tag the commit on `main`:
+
+```bash
+git tag -a v0.1.0 -m "v0.1.0 — initial published snapshot"
+git push origin v0.1.0
+```
+
+3. In Gitea: **Releases → New Release**, select the tag, paste notes from `CHANGELOG.md`, and attach artifacts if you build any.
+
 ## Prerequisites
 
 - **Local:** `gcc`, `make`, Node 20+, `npm`  
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..d54775a
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,20 @@
+# Security policy
+
+## Supported versions
+
+This repository is under active development. Security fixes land on the default branch (`main`) first.
+
+## Reporting a vulnerability
+
+Please email the repository maintainers with:
+
+- a short description of the issue
+- steps to reproduce (if applicable)
+- affected component (`solver-api`, `gui-ts`, `solver-c`, Docker, etc.)
+
+Do not open a public issue for undisclosed vulnerabilities.
+
+## Scope notes
+
+- The local API is intended for **trusted development networks**. Do not expose it to the public internet without hardening (TLS, auth, rate limits, reverse proxy).
+- Treat uploaded XML as untrusted input at API boundaries.