feat(modules): Swin-style PatchMerging with register-row support

.github/pull_request_template.md

@@ -23,3 +23,16 @@ pre-commit run --all-files
 ## Test plan
 
 <!-- How did you test this? Bulleted checklist preferred. -->
+
+## Documentation checklist
+
+For every new or modified public symbol in `nvsubquadratic/` or `experiments/`:
+
+- [ ] Every new **module** has a module-level docstring explaining what it contains and why.
+- [ ] Every new **public class** has a class docstring covering purpose, math/motivation, and key attributes.
+- [ ] Every new **public method / function** has `Args:` and `Returns:` blocks with tensor shapes where applicable.
+- [ ] Math notation is consistent with the paper (or a comment explains any deviation).
+- [ ] Docstrings containing backslashes use `r"""..."""` (required by ruff D301).
+- [ ] If a new file was added, a row has been added to [`docs-tracker.md`](../docs-tracker.md) with status `[x]`.
+
+> See [`CONVENTIONS.md`](../CONVENTIONS.md) for the full style guide.

.github/workflows/docstring_check.yml

@@ -0,0 +1,49 @@
+name: Docstring coverage
+
+on:
+  pull_request:
+
+# Cancel in-flight runs for the same PR when a new commit is pushed
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docstrings:
+    name: Check docstrings on changed files
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # need full history to diff against base branch
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Collect changed Python files in scope
+        id: changed
+        run: |
+          git diff --name-only origin/${{ github.base_ref }}...HEAD \
+            | grep -E '^(nvsubquadratic|experiments)/.*\.py$' \
+            > changed_files.txt || true
+          echo "Files to check:"
+          cat changed_files.txt
+
+      - name: Run docstring checks on changed files
+        run: |
+          if [ ! -s changed_files.txt ]; then
+            echo "No in-scope Python files changed — skipping."
+            exit 0
+          fi
+          # D100 missing module docstring
+          # D101 missing class docstring
+          # D102 missing method docstring
+          # D103 missing function docstring
+          # D301 use r""" for docstrings with backslashes
+          # D417 missing argument descriptions in docstring
+          xargs ruff check --select D100,D101,D102,D103,D301,D417 < changed_files.txt

CONVENTIONS.md

@@ -0,0 +1,128 @@
+# Documentation Conventions
+
+## Goal
+
+External collaborators should be able to read any module in `nvsubquadratic/`
+or `experiments/` alongside the research paper and understand:
+
+1. **What** the class/function does and **why** it exists.
+1. The **math** it implements (notation from the paper where applicable).
+1. The **shape contract** of every tensor argument.
+1. How it fits into the larger architecture.
+
+______________________________________________________________________
+
+## Docstring style
+
+All public classes, functions, and methods use **Google-style docstrings**.
+
+```python
+def forward(self, x: torch.Tensor) -> torch.Tensor:
+    """Apply RMS normalisation over the last dimension.
+
+    Args:
+        x: Input tensor of shape ``[*leading, D]``.
+
+    Returns:
+        torch.Tensor: Normalised tensor, same shape and dtype as ``x``.
+
+    Raises:
+        RuntimeError: If ``x.shape[-1]`` does not equal ``self.dim``.
+    """
+```
+
+### Rules
+
+| What                                    | Where                                                      |
+| --------------------------------------- | ---------------------------------------------------------- |
+| Math / motivation / paper context       | **Module docstring** or **class docstring**                |
+| Parameter descriptions + shapes         | `Args:` block on the method                                |
+| Return shape + dtype                    | `Returns:` block                                           |
+| Docstrings containing `\` (backslashes) | Use `r"""..."""` (required by ruff D301)                   |
+| Single-line `__init__` docstrings       | Allowed only when the class docstring covers all arguments |
+
+______________________________________________________________________
+
+## PR convention
+
+> **Any PR that adds or modifies a public class or function in `nvsubquadratic/`
+> or `experiments/` must update the docstring of every touched symbol.**
+
+This means:
+
+- New file → full module docstring + docstrings on all public classes/functions.
+- Existing file touched → update only the affected symbols; do not leave
+  neighbouring docstrings stale.
+- Renamed parameter → rename in the docstring too (never paper over a
+  misleading name with a docstring explanation).
+
+______________________________________________________________________
+
+## Automated enforcement
+
+### 1. ruff (already active)
+
+The pre-commit hook runs `ruff` with the `D` rule-set enabled.  It catches:
+
+- `D100` Missing docstring in public module
+- `D101` Missing docstring in public class
+- `D102` Missing docstring in public method
+- `D103` Missing docstring in public function
+- `D301` Use `r"""` if backslashes appear in a docstring
+
+If your commit is rejected by ruff with a `D` error, add or fix the docstring
+before pushing.
+
+### 2. CI diff-check (recommended addition)
+
+Add the following job to `.github/workflows/ci.yml` (or your equivalent):
+
+```yaml
+- name: Docstring coverage on changed files
+  run: |
+    # Collect Python files touched by this PR
+    git diff --name-only origin/main...HEAD \
+      | grep -E '^(nvsubquadratic|experiments)/.*\.py$' \
+      > changed.txt
+
+    # Fail if any changed file has missing public docstrings
+    if [ -s changed.txt ]; then
+      xargs ruff check --select D100,D101,D102,D103,D417 < changed.txt
+    fi
+```
+
+This restricts the `D` check to **files actually changed in the PR**, so it
+never blocks unrelated legacy files.
+
+### 3. CONVENTIONS.md review checklist
+
+Add a pull-request template (`.github/pull_request_template.md`) that
+reminds authors:
+
+```markdown
+## Documentation checklist
+
+- [ ] Every new public class has a module-level or class-level docstring
+      explaining *what it does* and *why*.
+- [ ] Every new public method/function has Args: and Returns: blocks with
+      tensor shapes.
+- [ ] Math notation is consistent with the paper (or a comment explains any
+      difference).
+- [ ] Docstrings containing backslashes use `r"""..."""`.
+```
+
+### 4. Updating `docs-tracker.md`
+
+When a PR introduces a **new file** in scope (`nvsubquadratic/` or
+`experiments/`), add a row to the relevant table in `docs-tracker.md` with
+status `[x]` and a one-line note.  This keeps the tracker current without a
+separate documentation PR.
+
+______________________________________________________________________
+
+## What does *not* need a docstring
+
+- Private helpers prefixed with `_` (encouraged but not required).
+- `__repr__` / `extra_repr` methods — a brief one-liner is enough.
+- Test files under `tests/` — descriptive test names suffice.
+- Config files under `experiments/` that contain only a `cfg = ...` assignment.

README.md

@@ -155,7 +155,17 @@ source .env && PYTHONPATH=. python -m pytest tests/ -m nightly -v -o addopts=""
 
 ### Documentation
 
-The API reference is built with Sphinx. Sources live under [`docs/`](docs/) and the rendered site is published to the `gh-pages` branch on every push to `main` via [`.github/workflows/docs.yml`](.github/workflows/docs.yml).
+All public classes and functions carry **Google-style docstrings** with math
+context, shape annotations, and paper references.  See [`CONVENTIONS.md`](CONVENTIONS.md)
+for the style guide and PR checklist.
+
+#### Viewing the docs
+
+**Sphinx HTML (full API reference)**
+
+The API reference is built with Sphinx. Sources live under [`docs/`](docs/) and
+the rendered site is published to the `gh-pages` branch on every push to `main`
+via [`.github/workflows/docs.yml`](.github/workflows/docs.yml).
 
 Build and preview locally:
 
@@ -166,7 +176,31 @@ make -C docs html SPHINXBUILD="python -m sphinx"
 python -m http.server 8000 --directory docs/_build/html
 ```
 
-Open <http://localhost:8000> to browse. The autosummary stubs in `docs/generated/` are regenerated on every build (gitignored).
+Open <http://localhost:8000> to browse.  The autosummary stubs in
+`docs/generated/` are regenerated on every build (gitignored).
+
+**Inline — IDE hover / `help()`**
+
+Because all documentation lives directly in the docstrings, you can also:
+
+- Hover over any symbol in VS Code / PyCharm to see the rendered docstring.
+- Run `help(SomeClass)` in a Python REPL for an immediate plain-text view.
+- Use `python -m pydoc nvsubquadratic.modules.hyena_nd` for a terminal-friendly
+  per-module dump.
+
+**`pdoc` (quick zero-config HTML)**
+
+For a fast, dependency-light alternative to Sphinx that renders the docstrings
+as-is:
+
+```bash
+pip install pdoc
+pdoc nvsubquadratic --output-dir /tmp/pdoc-out
+python -m http.server 8000 --directory /tmp/pdoc-out
+```
+
+This does not require a `docs/conf.py` and picks up the Google-style sections
+automatically.
 
 ### CI