docs: MkDocs site + ICA/AMICA concepts, figures, community files

.context/plan.md

@@ -76,3 +76,61 @@
 ## Notes
 - Correctness is defined by parity with the Fortran binary, not by convergence alone.
 - Detailed feature status: `feature_parity.md`; migration record: `migration_plan.md`.
+
+## Release Readiness (JOSS track) — started 2026-07-10
+Endgame ordering: finish the three open benchmark issues -> documentation ->
+transfer to github.com/sccn -> JOSS paper. The repo will move to
+`github.com/sccn/pyAMICA` (full transfer, preserving issues/PRs/history) and docs
+will be hosted at `eeglab.org/pyAMICA`.
+
+### Phase R1: Benchmark completion (#90, #91, #92)
+- [~] #90 Data-size (k-factor) frames sweep at 70ch. Code + data staged on hallu
+      (branch `feature/issue-90-datasize-sweep`, origin-pushed; based on current main).
+      Full 747,750-frame npy present (`ds002718_sub-002_eeg70_full.npy`). CUDA sweep
+      (torch-cuda-f64/f32) + native-fortran-f64 launched on hallu 2026-07-10:
+      frames 73.5k/147k/294k/490k/747.75k -> k=15/30/60/100/152, 2000 iters,
+      out=`benchmarks/results_k90_hallu`. Probe: largest frames ~1.1 s/it (f64) ->
+      ~36 min/run; CUDA sweep ETA ~2.5 h. Remaining: finish runs -> `--compare`
+      cross-backend |corr| vs k figure + report -> PR.
+- [ ] #91 Spatially-distributed channel subsets: replace `full[:nc]` first-N slicing
+      in `benchmark_dimsweep.py`/`benchmark_decompose.py` with farthest-point sampling
+      over real electrode 3D coords (whole-head 16/32/48ch montages). Local; formalize
+      `mne` as a viz/benchmark extra (not in core env). Prereq for #92 reduced-montage.
+- [ ] #92 EEGLAB drop-in output parity: variance-ordered ICs (back-projected variance,
+      IC1=highest), `loadmodout15`/`pop_runamica`-readable output, sign/scale
+      conventions, documented MATLAB+EEGLAB round-trip. MATLAB R2025b and EEGLAB both
+      present locally (`~/Documents/git/eeg/eeglab`).
+
+### Phase R2: Documentation (MkDocs Material, per /project:init-project)
+Use the init-project docs templates verbatim where possible
+(`~/.claude/plugins/cache/research-skills/project/0.5.0/templates/config/mkdocs.yml`
++ `github/workflows/docs.yml`), adapted for pyAMICA:
+- Material theme (light/dark palette toggle, navigation.tabs/sections/indexes/top/
+  instant, search.suggest/highlight, content.code.copy, toc.integrate).
+- Plugins: `search`, `mkdocstrings` (python) with **`docstring_style: numpy`** (repo
+  uses numpy docstrings, NOT the template's `google` default), `git-revision-date-localized`.
+- Add a `docs` optional-dependency extra (mkdocs-material, mkdocstrings[python],
+  mkdocs-git-revision-date-localized-plugin) — the `docs.yml` workflow runs
+  `uv sync --extra docs` then `uv run mkdocs build`. Currently only an `mlx` extra exists.
+- **Hosting:** GitHub Pages via `docs.yml` (build+deploy on push to main). Served at
+  `eeglab.org/pyAMICA` because `sccn/pyAMICA` *project* Pages inherit the sccn org
+  Pages custom domain (`eeglab.org`) at the `/pyAMICA` subpath. `site_url:
+  https://eeglab.org/pyAMICA/`, relative links; stages at
+  `neuromechanist.github.io/pyAMICA/` pre-transfer.
+- [ ] De-WIP `README.md` (drop the "do not rely on this" disclaimer; `uv` install;
+      quickstart; backend-selection guide MLX/CUDA/CPU + f32/f64; results table).
+- [ ] mkdocs.yml + docs/ skeleton (Home, Getting Started, User Guide, API Reference
+      via mkdocstrings, Development, Changelog) + `docs` extra + `docs.yml` workflow.
+- [ ] Community health: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CITATION.cff`,
+      issue/PR templates (JOSS-expected).
+
+### Phase R3: Transfer to github.com/sccn (before JOSS submission)
+- [ ] GitHub repo transfer (preserves issues/PRs/stars/history; auto-redirects old
+      URLs). Post-transfer: update badge/repo URLs (README, CITATION.cff, paper.md),
+      wire up the `eeglab.org/pyAMICA` docs deploy target.
+
+### Phase R4: JOSS paper (/manuscript:manuscript-writing)
+- [ ] `paper.md` (~1000 words) + `paper.bib`: summary, statement of need (GPU +
+      cross-platform AMICA with Fortran parity; drop-in for EEGLAB AMICA), comparison
+      vs EEGLAB AMICA / Picard / FastICA, backend + parity results, acknowledgments;
+      `repository -> github.com/sccn/pyAMICA`.

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # git-revision-date-localized needs full history, not a shallow clone
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --extra docs
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy-docs:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,3 +44,6 @@ bench_out/
 
 # Decomposition benchmark run artifacts (#87)
 results/
+
+# MkDocs build output
+site/

CITATION.cff

@@ -0,0 +1,37 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "pyAMICA: a Python implementation of Adaptive Mixture ICA"
+abstract: >-
+  pyAMICA is a Python (PyTorch) implementation of Adaptive Mixture Independent
+  Component Analysis (AMICA) that reproduces the reference Fortran
+  implementation, with GPU (CUDA), Apple-GPU (MLX), and CPU support. It targets
+  EEG/EMG blind source separation.
+type: software
+authors:
+  - family-names: Shirazi
+    given-names: Seyed Yahya
+    email: shirazi@ieee.org
+version: 0.1.dev0
+license: BSD-3-Clause
+repository-code: "https://github.com/neuromechanist/pyAMICA"
+url: "https://github.com/neuromechanist/pyAMICA"
+keywords:
+  - AMICA
+  - independent component analysis
+  - blind source separation
+  - EEG
+  - EMG
+  - PyTorch
+references:
+  - type: article
+    title: "AMICA: An adaptive mixture of independent component analyzers with shared components"
+    authors:
+      - family-names: Palmer
+        given-names: Jason A.
+      - family-names: Kreutz-Delgado
+        given-names: Kenneth
+      - family-names: Makeig
+        given-names: Scott
+    year: 2012
+    institution:
+      name: Swartz Center for Computational Neuroscience, University of California San Diego

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+shirazi@ieee.org. All complaints will be reviewed and investigated promptly and
+fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to pyAMICA
+
+Thanks for your interest in contributing. pyAMICA is a Python implementation of
+Adaptive Mixture Independent Component Analysis (AMICA) that reproduces the
+reference Fortran implementation. Because **numerical parity with the Fortran
+reference is the definition of correctness**, contributions are held to that
+standard rather than to "it converges."
+
+## Getting help and reporting issues
+
+- **Questions, bugs, and feature requests:** please open an issue on the
+  [GitHub issue tracker](https://github.com/neuromechanist/pyAMICA/issues).
+- When reporting a bug, include the pyAMICA version, platform, device
+  (CPU/CUDA/MPS/MLX), precision (float32/float64), and a minimal example.
+
+## Development setup
+
+pyAMICA uses [UV](https://docs.astral.sh/uv/) for environment and dependency
+management.
+
+```bash
+git clone https://github.com/neuromechanist/pyAMICA.git
+cd pyAMICA
+uv sync                 # install the project and dependencies
+uv run pytest           # run the test suite
+```
+
+On Apple MPS, run with `PYTORCH_ENABLE_MPS_FALLBACK=1` for ops MPS does not yet
+support.
+
+## Testing
+
+- **Real data only.** Correctness tests use the real sample EEG and the Fortran
+  binary shipped in `pyAMICA/sample_data/`. Do not use mocks, stubs, or synthetic
+  data as the basis for a correctness test: no test is better than a fake passing
+  test.
+- Run with coverage: `uv run pytest --cov`.
+- The natural-gradient backend computes in float64 for Fortran parity; use
+  float64 for parity-sensitive tests.
+
+## Code style
+
+- **Lint and format** with Ruff before committing:
+  ```bash
+  uv run ruff check --fix . && uv run ruff format .
+  ```
+- Follow the conventions in the surrounding code and in `AGENTS.md`.
+- No em-dashes in prose; define abbreviations on first use.
+
+## Pull requests
+
+1. Open an issue first (except for minor fixes).
+2. Create a branch (for example `gh issue develop <n>`).
+3. Make atomic commits with concise messages (no emojis, no AI attribution).
+4. Add or update tests, and run the suite before pushing.
+5. Open a PR describing what changed and how it was tested.
+6. Ensure CI is green before requesting a merge.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+project's [BSD 3-Clause License](LICENSE).

docs/api/amica.md

@@ -0,0 +1,6 @@
+# AMICA
+
+The main scikit-learn-style interface. Wraps the natural-gradient EM backend
+([`AMICATorchNG`](torch-backend.md)).
+
+::: pyAMICA.AMICA

docs/api/index.md

@@ -0,0 +1,21 @@
+# API Reference
+
+The public import surface is stable:
+
+```python
+from pyAMICA import AMICA, AMICA_NumPy, AMICATorchNG
+```
+
+- **[`AMICA`](amica.md)** — the main scikit-learn-style interface. Wraps the
+  PyTorch natural-gradient EM backend. Start here.
+- **[`AMICATorchNG`](torch-backend.md)** — the PyTorch natural-gradient EM
+  backend (Fortran parity). The `AMICA` interface delegates to this class.
+- **[`AMICA_NumPy`](numpy-backend.md)** — the legacy NumPy reference
+  implementation, retained as an oracle and for its command-line interface.
+
+The optional Apple-Silicon GPU backend is imported separately and is not part of
+the default import surface:
+
+```python
+from pyAMICA.mlx_impl import AMICAMLXNG  # requires the `mlx` extra
+```

docs/api/numpy-backend.md

@@ -0,0 +1,7 @@
+# NumPy backend (AMICA_NumPy)
+
+The legacy NumPy reference implementation, retained as an oracle and for its
+command-line interface. It carries the same parity fixes as the PyTorch backend,
+plus baralpha and outlier rejection.
+
+::: pyAMICA.AMICA_NumPy

docs/api/torch-backend.md

@@ -0,0 +1,8 @@
+# PyTorch backend (AMICATorchNG)
+
+The natural-gradient EM backend that reaches Fortran parity (Newton, exact-EM
+mixture updates, symmetric-ZCA sphere, Jacobian log-likelihood). The
+[`AMICA`](amica.md) interface delegates to this class; use it directly for
+lower-level control.
+
+::: pyAMICA.AMICATorchNG