docs: content wave 1 (reference + how-to pages)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: ""
+labels: bug
+---
+
+## Description
+
+A clear and concise description of what went wrong, and what you expected to happen instead.
+
+## Minimal working example (MWE)
+
+Please include the smallest possible piece of code that reproduces the issue.
+Trim away everything that is not needed to trigger the bug (unrelated setup, unused imports, etc).
+
+```julia
+using MPSKit, TensorKit
+
+# ...
+```
+
+## Error / output
+
+Paste the full error message and stacktrace (or the incorrect output), if any.
+
+```
+paste here
+```
+
+## Version info
+
+Please include the versions of MPSKit and its main dependencies.
+From the Julia REPL:
+
+```julia-repl
+julia> using Pkg
+julia> Pkg.status(["MPSKit", "TensorKit"])
+```
+
+Also include the Julia version:
+
+```julia-repl
+julia> versioninfo()
+```
+
+## Additional context
+
+Anything else that might help (OS, whether it also happens on the latest `main`, related issues, etc).

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,27 @@
+---
+name: Question
+about: Ask a question about using MPSKit
+title: ""
+labels: question
+---
+
+## What are you trying to do?
+
+Describe the physics or the workflow you are trying to set up.
+
+## What have you tried?
+
+If applicable, include the code you have so far, and what result you got (or expected but didn't get).
+
+```julia
+using MPSKit, TensorKit
+
+# ...
+```
+
+## Version info (optional but helpful)
+
+```julia-repl
+julia> using Pkg
+julia> Pkg.status(["MPSKit", "TensorKit"])
+```

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Description
+
+Briefly describe what this PR changes and why.
+
+## Checklist
+
+- [ ] Tests pass locally (`julia --project=test test/runtests.jl`, or the relevant subset)
+- [ ] Documentation updated, if this PR changes public API (docstrings, `docs/src/`)
+- [ ] Changelog entry added under `[Unreleased]` in `CHANGELOG.md`

CITATION.cff

@@ -12,7 +12,7 @@ authors:
   orcid: "https://orcid.org/0000-0002-0858-291X"
 
 title: "MPSKit"
-version: 0.13.11
+version: 0.13.13
 doi: 10.5281/zenodo.10654900
-date-released: 2026-05-04
+date-released: 2026-06-09
 url: "https://github.com/QuantumKitHub/MPSKit.jl"

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to MPSKit.jl
+
+Thanks for taking the time to contribute!
+This document is a short, practical guide to reporting issues, asking questions, and submitting changes.
+
+## Asking questions and reporting bugs
+
+Use [GitHub issues](https://github.com/QuantumKitHub/MPSKit.jl/issues) for both.
+There are two templates to help you:
+
+- **Bug report** — for something that doesn't work as expected.
+- **Question** — for anything else, from "how do I model X" to "is Y possible".
+
+A good bug report is one we can act on immediately, and it needs two things:
+
+1. A minimal working example (MWE): the smallest snippet of code that reproduces the problem.
+   Strip away everything not needed to trigger the bug — unrelated setup, unused imports, alternative approaches you also tried.
+2. Version information for MPSKit, TensorKit, and Julia, obtained with:
+
+   ```julia-repl
+   julia> using Pkg
+   julia> Pkg.status(["MPSKit", "TensorKit"])
+   ```
+
+   ```julia-repl
+   julia> versioninfo()
+   ```
+
+Please also include the full error message and stacktrace, if there is one.
+
+## Contributing code
+
+### Development setup
+
+1. Fork and clone the repository.
+2. From the Julia REPL, develop the package against your local checkout:
+
+   ```julia-repl
+   pkg> dev /path/to/your/clone/MPSKit.jl
+   ```
+
+   or, from a fresh environment:
+
+   ```julia-repl
+   julia> using Pkg; Pkg.develop(path = "/path/to/your/clone/MPSKit.jl")
+   ```
+
+### Running the tests
+
+The repository root is a Julia workspace (`Project.toml` lists `test`, `docs`, and `examples` as workspace projects), and `test/Project.toml` already points `MPSKit` back at the repo checkout.
+From the repository root, run the full suite with:
+
+```
+julia --project=test test/runtests.jl
+```
+
+The test suite is organized by topic under `test/` (`algorithms/`, `states/`, `operators/`, `misc/`, `gpu/`), with shared setup code in `test/setup/`.
+GPU tests only run when a functional CUDA/cuTENSOR install is detected, so most contributors will only ever exercise the CPU tests.
+A `--fast` flag is available for a quicker, reduced run while iterating.
+
+### Building the documentation
+
+The docs use Documenter.jl with the DocumenterVitepress backend, so a full render needs Node.js in addition to Julia.
+
+For routine verification of code examples (fast, no Node required), run the doctests directly:
+
+```
+julia --project=docs -e 'using Documenter, MPSKit; doctest(MPSKit)'
+```
+
+For a full local site build (slower, needs `npm`):
+
+```
+julia --project=docs docs/make.jl
+```
+
+### Code formatting
+
+This repository is formatted with [Runic](https://github.com/fredrikekre/Runic.jl).
+Formatting is checked automatically on pull requests, and there is a [pre-commit](https://pre-commit.com/) hook (`.pre-commit-config.yaml`) that runs Runic locally if you use pre-commit.
+Please format any Julia files you touch before opening a PR.
+
+### Changelog
+
+If your change is user-facing (new feature, behavior change, bug fix, deprecation, or removal), add an entry under the `[Unreleased]` section of `CHANGELOG.md`, in the category that matches your change.
+
+### Opening a pull request
+
+Small, focused pull requests are easiest to review.
+Please describe what the change does and why, link any related issues, and make sure the checklist in the PR template is filled in before requesting review.

README.md

@@ -42,8 +42,23 @@ out the [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) for
 use-cases.
 
 This package is under active development and new algorithms are added regularly.
-Nevertheless, the documentation is quite terse, so feel free to open an issue if you have
-any questions.
+Questions and general discussion are welcome on [GitHub
+Discussions](https://github.com/QuantumKitHub/MPSKit.jl/discussions); if you think you have
+found a bug, please open an issue.
+
+## How MPSKit compares
+
+Finite and infinite systems are one interface, not two.
+`FiniteMPS` and `InfiniteMPS` share the same algorithms, so a calculation moves from a
+finite chain to the thermodynamic limit with a one-line change, as the two examples below
+show.
+Symmetries are first-class rather than an add-on: abelian, non-abelian, fermionic, and
+anyonic symmetries are all available through the [TensorKit.jl](https://github.com/jutho/TensorKit.jl)
+backend, including symmetry groups that most tensor-network codebases do not support at
+all.
+The whole toolbox — states, operators, and algorithms — is native Julia and composes
+directly with the TensorKit ecosystem, so extending it does not mean dropping into a
+different language.
 
 ## Installation
 
@@ -118,3 +133,19 @@ scatter(g_values, M, xlabel="g", ylabel="M", label="D=$D", title="Magnetization"
 ```
 
 ![Magnetization](docs/src/assets/README_ising_infinite.png)
+
+## Citing
+
+If you use MPSKit.jl in your research, please cite it.
+See [`CITATION.cff`](CITATION.cff) for the up-to-date citation metadata, or use the BibTeX entry below.
+
+```bibtex
+@software{mpskitjl,
+  author  = {Devos, Lukas and Van Damme, Maarten and Haegeman, Jutho},
+  title   = {{MPSKit.jl}},
+  version = {v0.13.13},
+  doi     = {10.5281/zenodo.10654900},
+  url     = {https://github.com/QuantumKitHub/MPSKit.jl},
+  year    = {2026}
+}
+```

docs/.gitignore

@@ -1,4 +1,5 @@
 build/
 node_modules/
 package-lock.json
-Manifest.toml
+Manifest.toml
+src/changelog.md