[docs] high level doc updates

README.md

@@ -109,7 +109,7 @@ python3 -m pytest -rsxX | tee test_results.txt
 
 ## Use
 
-`meanas` is organized around a few core workflows:
+`meanas` is a collection of finite-difference electromagnetics tools:
 
 - `meanas.fdfd`: frequency-domain wave equations, sparse operators, SCPML, and
   iterative solves for driven problems.
@@ -121,13 +121,10 @@ python3 -m pytest -rsxX | tee test_results.txt
 - `meanas.fdmath`: low-level finite-difference operators, vectorization helpers,
   and derivations shared by the FDTD and FDFD layers.
 
-The most mature user-facing workflows are:
-
-1. Build an FDFD operator or waveguide port source, then solve a driven
-   frequency-domain problem.
-2. Run an FDTD simulation, extract one or more frequency-domain phasors with
-   `meanas.fdtd.accumulate_phasor(...)`, and compare those phasors against an
-   FDFD reference on the same Yee grid.
+For most users, the tracked examples under `examples/` are the right entry
+point. The library API is primarily a toolbox; the module docstrings and API
+pages are there to document the mathematical conventions and derivations behind
+those tools.
 
 ## Documentation
 
@@ -135,37 +132,6 @@ API and workflow docs are generated from the package docstrings with
 [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
 and [mkdocstrings](https://mkdocstrings.github.io/).
 
-When hosted on a Forgejo instance, the intended setup is:
-
-- publish the generated site from a dedicated `docs-site` branch
-- serve that branch from the instance's static-pages host
-- point the repository's **Wiki** tab at the published docs URL
-
-This repository now uses a version-controlled wrapper script rather than a
-Forgejo runner. After a successful `git push`, the wrapper builds the docs
-locally and force-updates the `docs-site` branch from the same machine.
-
-Use the wrapper instead of `git push` when publishing from your development
-machine:
-
-```bash
-./scripts/push_with_docs.sh
-```
-
-It only auto-publishes after successful pushes of local `master` to `origin`.
-For unusual refspecs or other remotes, push manually and publish the docs
-branch separately if needed.
-
-To persist the published docs URL for canonical MkDocs links in this clone, set
-the local git config value with:
-
-```bash
-./scripts/configure_docs_url.sh 'https://docs.example.com/meanas/'
-```
-
-The wrapper will also respect a shell-level `DOCS_SITE_URL` override if one is
-set.
-
 Install the docs toolchain with:
 
 ```bash
@@ -184,13 +150,10 @@ This produces:
 - a combined printable single-page HTML site under `site/print_page/`
 - an optional fully inlined `site/standalone.html` when `htmlark` is available
 
-The version-controlled push wrapper publishes this same output to the
-`docs-site` branch.
-
 The docs build uses a local MathJax bundle vendored under `docs/assets/`, so
 the rendered HTML does not rely on external services for equation rendering.
 
-Tracked examples under `examples/` are the intended starting points:
+The tracked examples under `examples/` are the intended entry points for users:
 
 - `examples/fdtd.py`: broadband FDTD pulse excitation, phasor extraction, and a
   residual check against the matching FDFD operator.