docs: add contributing, security and conduct guides; link the live demo

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# 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 e-mail 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 GitHub private vulnerability reporting on this repository (**Security → Report a vulnerability**), which reaches the maintainer privately. 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,71 @@
+# Contributing
+
+## What this is
+
+A command-line tool that turns video of a production operation into an interactive motion and time
+study. It is used to measure processes, and it deliberately refuses to rate people — see the README
+for why that boundary exists. **Contributions that erode it will be declined**, however well
+implemented: no performance rating, no effort estimation, no per-person productivity scoring, no
+leaderboards.
+
+That is the only closed door. Everything else is open, and there is plenty to do.
+
+## Especially welcome
+
+- **Detection and tracking accuracy on real footage.** This is the biggest gap in the project. The
+  analysis half is validated against synthetic ground truth (`tests/test_demo_accuracy.py`); the
+  detection half has never been measured against a hand-labelled video. A benchmark, a labelled
+  clip you can share, or a reproducible accuracy number would be the single most useful
+  contribution.
+- **Other domains.** The demo models a scaffolding line because that is what it was built for. If
+  you run it on a different kind of assembly or fabrication work and it does something wrong, that
+  is worth an issue with the config you used.
+- **Speed.** Analysis runs at roughly 1.5–2× video length on CPU. `onnxruntime-gpu` with
+  `detection.device: cuda` is a config change away, but nobody has published measured numbers.
+- **Report clarity.** The report is the deliverable, and it has to survive being shown to a
+  supervisor who has never seen a Yamazumi chart. Confusing labels and misleading defaults are bugs.
+- **Platform fixes.** Developed on Windows, tested in CI on Linux. macOS is unverified.
+
+## Setting up
+
+Python 3.11 or newer.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest tests -q                  # 71 tests, no video or model weights needed
+```
+
+`python -m mstudy demo` builds a complete report from synthetic data, so you can work on the
+analysis, the report or the charts without any footage at all. Most changes can be developed and
+reviewed this way.
+
+On Windows-on-ARM, use an x64 Python — `opencv-python` publishes no Windows-ARM64 wheel.
+
+## Before opening a PR
+
+```bash
+pytest tests -q
+```
+
+CI runs the same on Python 3.11 and 3.12. Two things to keep true:
+
+- **Never commit footage, a report, or model weights.** `.gitignore` covers `input/`, `runs/`,
+  video extensions, `models/` and `*.onnx`. If you add an output path, add it there in the same
+  commit.
+- **Declare new dependencies in `pyproject.toml`.** A package that is merely installed in your venv
+  will pass locally and break every clean install — that exact bug shipped once, which is why CI now
+  installs from scratch on every push.
+
+Conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+
+## Reporting something sensitive
+
+Do not open a public issue for a security or privacy problem. See [SECURITY.md](SECURITY.md) — and
+note that the privacy boundary around footage matters more here than any conventional vulnerability.
+
+## Licence
+
+By contributing you agree your contribution is licensed under the Apache License 2.0 in
+[LICENSE](LICENSE).

README.md

@@ -37,11 +37,16 @@ camera in a workshop is not recoverable once people conclude they are being scor
 
 ## See it before filming anything
 
+A live copy of the report this produces, generated from the built-in synthetic demo, with nothing to
+install: **<https://motion-study-demo.vercel.app>**
+
+To generate your own:
+
 ```bash
 python -m mstudy demo
 ```
 
-Builds a complete report from a synthetic three-worker line — no video, no models, no GPU, no
+Builds the same complete report from a synthetic three-worker line — no video, no models, no GPU, no
 network. Opens at `runs/demo/report.html`.
 
 ![The generated demo report: the rating-factor banner, headline figures, and the per-worker operation timeline](assets/demo-report.png)
@@ -198,6 +203,19 @@ judgement you attach to its output.
 Footage of identifiable workers never leaves the machine that processes it: `input/` and `runs/` are
 gitignored, nothing is uploaded, and no model call leaves the host.
 
+## Contributing
+
+Bugs, other domains, speed work and report clarity are all welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). The one closed door is performance rating; the reasoning is at
+the top of this README.
+
+The most useful thing anyone could contribute is a measured detection-accuracy number on real,
+hand-labelled footage, which is the gap named above.
+
+Security and privacy reports go through [SECURITY.md](SECURITY.md), not public issues — the privacy
+boundary around footage of identifiable workers matters more here than any conventional
+vulnerability. [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) is the Contributor Covenant 2.1.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,53 @@
+# Security and privacy reporting
+
+## Reporting
+
+Please do not open a public issue for a security or privacy problem.
+
+Use GitHub's private vulnerability reporting on this repository
+(**Security → Report a vulnerability**), which reaches the maintainer without disclosing the report.
+
+Expect an acknowledgement within seven days. This is maintained by one person, not a product with
+an on-call rotation — please size your expectations accordingly, and say in the report if you intend
+to disclose publicly on a deadline.
+
+## The thing most worth reporting
+
+This software processes **video of identifiable people at work**. The privacy boundary matters more
+here than any conventional vulnerability class, because a leak is not a database of hashes — it is
+footage of named employees.
+
+The design intent is that footage and analysis outputs never leave the machine that processes them:
+
+- `input/` and `runs/` are gitignored, and `.gitignore` has excluded them since the first commit;
+- nothing is uploaded, and no network call is made during analysis;
+- model weights are downloaded once from the `rtmlib` project and cached locally;
+- `report.html` is self-contained and opens offline.
+
+**Anything that breaks one of those is a genuine finding**, and the most valuable report you can
+make. Concretely: a path by which a frame, a track, a worker name, or a report reaches the network;
+a way a generated report embeds a source frame you would not expect; a default that writes footage
+somewhere outside `input/` or `runs/`.
+
+## Also in scope
+
+- A credential, key, or token committed anywhere in the git history.
+- A crafted video or config file that leads to code execution rather than a clean error.
+- Path traversal via a config value — station names and paths from `configs/*.yaml` reach the
+  filesystem and the generated HTML.
+- HTML or script injection into `report.html` through a config value, worker name, or station label,
+  since the report is rendered from a Jinja template and opened in a browser.
+
+## Not in scope
+
+- Detection or tracking inaccuracy. Real-footage detection accuracy is explicitly **not validated**
+  — the README says so. A missed worker is a known limitation, not a vulnerability.
+- Dependency advisories with no exploit path in this usage.
+- The absence of authentication. There is no server; this is a local command-line tool.
+
+## A note on lawful use
+
+Filming people at work is regulated differently in different places, and consent, notice and
+works-council obligations are not optional. `docs/RUNBOOK.md` covers the practical side. If you find
+that this tool makes it *easier* to do something unlawful or covert — for example a default that
+hides the fact that recording is happening — please report that too. It is a design defect.