Simplify user-facing method documentation

.github/pull_request_template.md

@@ -3,7 +3,6 @@
 
 ## Validation
 
-- [ ] `python tools/generate_docs.py --check`
 - [ ] `python -m unittest discover -s tests -v`
 - [ ] `python tools/validate_specs.py`
 - [ ] `python -m compileall tools`
@@ -12,6 +11,6 @@
 ## Reviewer Checklist
 
 - [ ] JSON specifications and conformance cases remain the normative source of truth.
-- [ ] Scientific notes, if changed, are explanatory and do not duplicate full input/output or parameter definitions.
-- [ ] Specification and scientific-note changes were reviewed for consistency.
+- [ ] Method pages help users call and interpret a function without duplicating the normative contract.
+- [ ] Specification, method-page, field-description, reference, and case changes were reviewed for consistency.
 - [ ] No implementation repository changes are included unless this PR explicitly targets one.

.github/workflows/docs.yml

@@ -28,9 +28,6 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -r requirements-dev.txt
 
-      - name: Check generated documentation
-        run: python tools/generate_docs.py --check
-
       - name: Build documentation
         run: mkdocs build --strict
 

.github/workflows/release.yml

@@ -105,9 +105,6 @@ jobs:
       - name: Validate Biosiglib
         run: python tools/validate_specs.py
 
-      - name: Check generated documentation
-        run: python tools/generate_docs.py --check
-
       - name: Build documentation
         run: mkdocs build --strict
 

AGENTS.md

@@ -1,92 +1,17 @@
 # AGENTS
 
-This file provides persistent context for AI coding agents working in Biosiglib. Treat the decisions below as project policy unless the maintainers explicitly change them.
-
-1. Biosiglib is a multimodal biomedical signal-processing ecosystem supporting ECG, PPG, respiration, HRV, and general signal-processing tools. HRV is one module, not the central purpose of the whole project.
-
-2. Biosiglib is the language-independent source of truth for:
-- public algorithm behavior;
-- inputs and outputs;
-- units;
-- parameters and defaults;
-- numerical definitions;
-- missing-value and edge-case behavior;
-- scientific provenance;
-- shared conformance cases.
-
-3. Biosigmat and Biosigpy are independent implementations. Biosigpy is not a line-by-line translation of Biosigmat.
-
-4. Implementations may use idiomatic language-specific APIs, internal architectures, data structures, exceptions, and plotting tools. They must preserve the normative scientific and computational behavior defined by Biosiglib.
-
-Canonical Biosiglib IDs use snake_case. Python should generally use the canonical names directly. MATLAB may use idiomatic camelCase or name-value spelling, but conceptual mappings must be explicit and aligned.
-Normative Biosiglib specification identifiers, including input IDs, output IDs, parameter IDs, definition targets, and other canonical structured IDs, must use snake_case. Implementation-specific naming conventions such as MATLAB camelCase must not appear as normative Biosiglib identifiers.
-
-ECG R-wave timing identifiers must use `r_wave_*`, not `r_peak_*`. Use R-wave terminology in public Biosiglib contracts because a chosen fiducial point may not be a literal amplitude peak.
-
-Generic timing or interval algorithms, including `hrv.tdmetrics`, must remain modality-generic unless the contract explicitly narrows them. Describe `dtk`-style inputs as cleaned beat-to-beat or pulse-to-pulse intervals rather than ECG- or R-wave-specific timing.
-
-Shared conformance cases should focus on positive outputs, algorithmically meaningful edge behavior, and cross-language semantic decisions. Avoid adding separate shared cases for every trivial argument-validation variant when the specification already states the generic type, shape, or scalar-value constraint.
-Do not create shared fixtures or conformance cases solely for trivial degenerate behavior such as empty inputs, empty outputs, all-NaN inputs, or all-NaN outputs when the behavior can be stated unambiguously in the specification. Define those behaviors in the normative specification text instead, unless the case exercises algorithmically meaningful processing, cross-language ambiguity, or a regression-prone semantic decision.
-Conformance case filenames and case IDs should use descriptive names without serial suffixes such as `_001`. Add a serial suffix only when multiple genuinely distinct cases would otherwise need the same descriptive filename or case ID.
-
-5. Specifications will use JSON and will be validated using JSON Schema. Human-readable web documentation will be generated from the JSON specifications. Generated documentation is not the normative source.
-
-6. Specification fields will distinguish normative information from informative documentation.
-
-7. Shared numerical and signal data will use:
-- JSON for metadata and small structured values;
-- CSV for signals, annotations, and tabular numerical data.
-
-8. Shared fixtures will initially remain in Biosiglib. Their catalog must contain machine-readable metadata required by tests and examples, including modality, device, sampling frequency, units, processing, duration, and annotations.
-
-9. Conformance comparisons currently use:
-- absolute numerical tolerances;
-- explicit comparison of NaN values;
-- language-independent expected-error categories for invalid type, shape, value, and insufficient-data behavior.
-Relative tolerances are not part of the initial design.
-
-10. Reference outputs may pragmatically be generated by the mature Biosigmat implementation, especially for complex algorithms. Their provenance must be recorded. Biosigmat is not automatically correct when a disagreement is detected; each disagreement must be analysed individually.
-
-11. Do not change scientific or computational behavior without explicit maintainer review. This includes filtering direction and phase behavior, NaN handling, default filters, default parameters, units, physiological interpretation, and reference-result provenance. Do not escalate purely idiomatic differences unless they affect scientific behavior. Examples: zero-based versus one-based internal indexing, exception class names, plotting library choices, or local variable names normally do not require maintainer review.
-
-12. Scientific algorithm authorship is recognised through citations to the original publications and relevant method extensions. Biosiglib software authorship belongs to the project maintainers. Do not introduce CRediT roles or intermediate per-algorithm software authorship systems.
-
-13. All repositories use GPL-3.0.
-
-14. Biosiglib, Biosigmat, and Biosigpy use independent semantic versioning with MAJOR.MINOR.PATCH.
-
-15. Workflows and examples are not public API contracts. However, corresponding workflows and examples across implementations should preserve the same conceptual processing sequence, parameters, input data, expected results, and scientific interpretation whenever possible.
-
-16. In Biosigmat:
-- public functions under src/ require specifications;
-- functions inside private/ do not;
-- examples and workflows remain under examples/;
-- all current public functions are considered stable.
-
-17. The generated specification catalog is the authoritative inventory. Do not maintain manual subsets of current specification IDs in policy or overview documents.
-
-18. For hrv.tdmetrics:
-- the canonical input dtk is the cleaned beat-to-beat or pulse-to-pulse interval sequence in seconds;
-- valid finite intervals must be strictly positive; Inf, -Inf, zero, and negative intervals are invalid;
-- NaN values in dtk are allowed as missing or invalid interval markers and are omitted from metric calculations;
-- dtk is produced before tdmetrics by beat or pulse detection, interval construction, and preprocessing for artifacts, missed beats, false detections, ectopic beats, outliers, and missing data;
-- mean heart or pulse rate is defined as 60 / mean(valid dtk), after omitting NaN markers;
-- outputs use their conventional units.
-
-19. Avoid overengineering. Do not introduce resource APIs, cross-language test runners, code generators, databases, or additional repositories unless they solve a demonstrated problem.
-
-20. Use English for filenames, code, comments, JSON field names, and technical documentation.
-
-21. Do not make architectural decisions that contradict this file without explicitly reporting the conflict to the maintainers.
-
-22. All local Python tooling in Biosiglib must run inside the repository-local `.venv`. AI agents must create `.venv` when it is absent, invoke the `.venv` Python executable explicitly, and never commit `.venv` or generated Python caches. `requirements-dev.txt` remains the dependency declaration for Biosiglib tooling. CI environments, when introduced later, must install dependencies in a clean environment and must not reuse the local `.venv`. Biosigpy will also use its own independent repository-local `.venv` when its package structure is created.
-
-23. Each implementation repository contains a `biosiglib.lock` file with one exact lowercase Biosiglib commit SHA. Code merged into an implementation must conform to every specification in that commit and execute every shared case; partial support and implementation roadmaps belong in issues and pull requests. Implementation versions remain independent from Biosiglib versions, and no per-algorithm version is used.
-
-24. Each implementation's normal full test suite must validate the `biosiglib.lock` format, verify the resolved checkout commit, and execute every shared case. Biosiglib does not define or validate downstream implementation metadata.
-
-25. Scientific notes under `docs/scientific/` are explanatory, not normative. They help researchers understand a method's purpose, rationale, assumptions, interpretation, and limitations, but they must not duplicate or replace the JSON specification.
-
-26. JSON specifications and conformance cases remain the source of truth for algorithm behavior, inputs, outputs, units, parameters, defaults, numerical definitions, missing-value behavior, edge cases, tolerances, and implementation conformance.
-
-27. Scientific notes must declare a `spec_id` in Markdown front matter, link to the corresponding normative specification, and avoid copying full input/output or parameter contracts from JSON specs. When a spec or note changes, AI agents and reviewers must check consistency between the explanatory note, the JSON specification, and relevant conformance cases.
+Persistent project rules for coding agents working in Biosiglib:
+
+1. Biosiglib is the language-independent contract for public methods implemented independently by Biosigpy and Biosigmat. JSON specifications and shared conformance cases are normative.
+2. A downstream `biosiglib.lock` declares total conformance with one exact commit. Partial support belongs in issues or pull requests, not repository metadata.
+3. Preserve normative scientific behavior across languages while allowing idiomatic APIs, internal structures, exceptions, indexing, and plotting.
+4. Do not change formulas, filtering direction or phase, units, defaults, NaN behavior, physiological meaning, edge cases, or reference results without explicit maintainer review.
+5. Canonical structured IDs use `snake_case`. ECG timing uses `r_wave_*`, not `r_peak_*`. Keep generic interval methods modality-neutral unless their contract says otherwise.
+6. Add shared cases for meaningful numerical behavior, cross-language ambiguity, and regressions. Do not multiply cases for trivial validation already stated unambiguously in a specification.
+7. Use JSON for structured metadata and small values, and CSV for signals, annotations, and tabular numerical data. Conformance comparisons use absolute tolerances and explicit NaN comparison.
+8. Every public method has one page under `docs/methods/`. It should help a user choose, call, and interpret the method. Keep implementation history and development-process commentary out of public documentation.
+9. Method interfaces, references, and technical links are injected during the MkDocs build. Do not commit derived Markdown or duplicate the normative contract in prose.
+10. Keep specifications, method pages, field descriptions, references, and cases consistent. Scientific authorship is recognised through original publications; software authorship belongs to the project maintainers.
+11. Use English for filenames, code, comments, structured fields, and technical documentation. All repositories use GPL-3.0 and independent semantic versioning.
+12. Use the repository-local `.venv` and the commands in `CONTRIBUTING.md`. Do not commit virtual environments or caches.
+13. Avoid new generators, resource APIs, databases, cross-language runners, or repositories unless they solve a demonstrated problem.

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to Biosiglib
+
+## Local setup
+
+Create a repository-local virtual environment and install the development dependencies:
+
+```powershell
+py -m venv .venv
+.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
+```
+
+## Validation
+
+Run these checks before submitting a change:
+
+```powershell
+.venv\Scripts\python.exe -m compileall tools
+.venv\Scripts\python.exe -m unittest discover -s tests -v
+.venv\Scripts\python.exe tools\validate_specs.py
+.venv\Scripts\python.exe -m mkdocs build --strict
+git diff --check
+```
+
+## Method changes
+
+The JSON specification and shared validation cases define behavior. A method page explains its purpose, expected data, scientific rationale, interpretation, and limitations. Repeated interface tables, references, and technical links are inserted from machine-readable sources during the documentation build.
+
+When adding or changing a method:
+
+1. update its specification and meaningful validation cases;
+2. update the corresponding page and field descriptions under `docs/methods/`;
+3. keep scientific references in `references/references.json`;
+4. run the full validation set above.
+
+Do not include implementation history, compatibility commentary, release planning, or contributor workflow in public method pages. Link to source code or technical artifacts when their contents do not need to be restated for a user.

README.md

@@ -1,40 +1,26 @@
 # Biosiglib
 
-**Language-independent specifications and shared validation resources for reproducible biomedical signal processing.**
+Biosiglib is the shared, language-independent description of biomedical signal-processing methods implemented by BSICoS.
 
-Biosiglib defines the expected scientific and computational behavior of public algorithms implemented by the BSICoS biomedical signal-processing libraries. It is not an executable signal-processing package; it contains specifications, scientific provenance, shared fixtures, conformance cases, and documentation-generation tooling.
+It contains:
 
-## Ecosystem
+- practical and scientific method documentation;
+- machine-readable JSON contracts;
+- scientific references;
+- shared validation cases and fixtures.
 
-- [Biosigmat](https://github.com/BSICoS/biosigmat): MATLAB implementation.
-- [Biosigpy](https://github.com/BSICoS/biosigpy): Python implementation.
-
-## What is in this repository
-
-- Machine-readable JSON specifications for public algorithms.
-- JSON Schemas used to validate specifications and implementation manifests.
-- Scientific references associated with each method.
-- Shared fixtures and conformance cases.
-- Tools for validation and generated documentation.
+Biosiglib is not an executable package. Use [Biosigpy](https://github.com/BSICoS/biosigpy) for Python or [Biosigmat](https://github.com/BSICoS/biosigmat) for MATLAB.
 
 ## Documentation
 
-The generated documentation site is available at [https://bsicos.github.io/biosiglib/](https://bsicos.github.io/biosiglib/).
-
-The website is generated from the JSON specifications. The JSON files remain the normative source of truth for algorithm behavior, inputs, outputs, units, defaults, missing-value handling, edge cases, and tolerances. Implementations declare total conformance with one exact Biosiglib commit.
-
-## Local validation
-
-See [docs/development.md](docs/development.md) for local setup and validation commands.
-
-## Releases
+Browse the methods at [bsicos.github.io/biosiglib](https://bsicos.github.io/biosiglib/). Each page explains the expected inputs and outputs, scientific basis, limitations, references, and links to both implementations.
 
-See the [SemVer classification and release-readiness checklist](docs/releases.md) for release semantics and coordinated conformance details.
+The JSON specifications and validation cases define the exact cross-language behavior. They are linked from each method page for contributors and advanced users.
 
-## Project status
+## Contributing
 
-Biosiglib is under active development. The generated specification catalog is the authoritative inventory of its current algorithm contracts.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the local setup, validation commands, and documentation rules.
 
 ## License
 
-Biosiglib is distributed under the GNU General Public License version 3. See [LICENSE](LICENSE) for the complete license text.
+Biosiglib is distributed under the [GNU General Public License version 3](LICENSE).

docs/citation.md

@@ -1,13 +1,11 @@
-# Citation
+# Cite Biosiglib
 
-Biosiglib will provide project-level software citation metadata in a future `CITATION.cff` file. A Zenodo DOI is also planned for archived software releases.
+When reproducibility matters, cite the repository and the exact commit used by your analysis:
 
-Until that metadata is added, cite the repository and release or commit used in your work as precisely as possible.
+```text
+BSICoS Biosiglib. Biomedical signal-processing method specifications and validation resources. https://github.com/BSICoS/biosiglib, commit <SHA>.
+```
 
-## Software And Scientific Citations
+Also cite the original publication for each method you use. The relevant references are listed on its page in the [method catalog](methods/index.md).
 
-Software citation and original scientific algorithm citation are complementary.
-
-Citing Biosiglib recognizes the software project: its specifications, validation resources, documentation, release process, and maintenance. Citing the original scientific publications recognizes the authorship of the algorithms and methodological foundations implemented by the ecosystem.
-
-For example, using an ECG detector through the Biosiglib ecosystem may require both the Biosiglib software citation and the original Pan-Tompkins method citation when that method is scientifically relevant to the work.
+If you used an executable implementation, identify [Biosigpy or Biosigmat](implementations.md) and its version as well.