add contributing guide and CoC

CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# 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
+rc-ssl-oc@lists.robocup.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,131 @@
+# Contributing Guide
+
+This document provide guidelines for contributing to this repository.
+
+## Scope
+
+Any high-level documentation related to the SSL is welcome here. This includes anything not clearly having a home 
+elsewhere.
+
+Architecture documentation is welcome here. This may include items such as fields, protocols, league technical 
+summaries, or community technical surveys of TDPs or other academic publications.
+
+In general, development specific documentation for league tools should live with that tool. This includes detailed 
+descriptions of commands, dependencies, bugs, etc. Consider opening issues or pull requests on those tools when
+issue arise. However, higher level documentation is very welcome here. This would include step-by-step usage guides,
+guides that include the tools in broader application, e.g. an example of calibrating vision to a specific field. When,
+possible, documentation should not be duplicated from a league tool repository. It's expected though that a usage guide
+may invoke some of the documented commands or compile steps. Consider adding an external link for the full 
+documentation and just invoking the command here. 
+
+If a league or external tool defines a _formal contract_ for usage, the definition of that contract must be 
+unambiguous. For example, the league [protocol definitions repository](https://github.com/RoboCup-SSL/ssl-protocol-defs)
+is the authoritative source on the data format of the protocols. However some aspects of the protocol outside the data 
+format are defined here, such as standard port numbers and expected network topology. On pages of this nature the
+author _must_ clearly separate what is defined where and link to external resources. Consider opening an Issue with
+the "discussion" tag if you are unclear about a boundary; a committee member can quickly help set the boundary of what
+should be documented where.
+
+## Style
+
+Pages should be written in clear concise technical English. Avoid abbreviations and sentence fragments in wiki pages.
+Do not use overly flowery language or sentence enhancers. Reviewers **will** request language be tightened if this
+writing stype is present.
+
+Use figures to augment or replace prose when possible. This improves readability. In order of preference, add 
+images as [SVG](https://en.wikipedia.org/wiki/SVG), then PNG, then JPG. This instance supports native rendering of
+[Mermaid Diagrams](https://en.wikipedia.org/wiki/Mermaid_(software)) and 
+[Diagrams.net (draw.io)](https://en.wikipedia.org/wiki/Diagrams.net). Care has been taken to support both light and 
+dark rendering for both options, though rendering draw.io is slightly more complicated due to limitations with the
+sphinx supporting module. Use Mermaid if possible.
+
+For algorithms or calculations, considering embedded a JavaScript asset. See the Camera Calculator page as an
+example.
+
+### Adding Images
+
+Add images with following block:
+
+````
+![Image Name](../images/image1.svg)
+````
+
+The name on the left is used when the asset cannot be loaded. Use relative paths to reference the image. Images live
+in an `images/` subfolder next to the page that uses them. Save and commit your images there.
+
+### Adding Mermaid Diagrams
+
+Mermaid sources live as `.mmd` files in a `diagrams/` subdirectory next to the page that uses them, and are
+embedded with the `mermaid` directive:
+
+````
+```{mermaid} diagrams/my-diagram.mmd
+```
+````
+
+Mermaid renders natively in both light and dark themes.
+
+### Adding Diagrams.net
+
+Diagrams.net (draw.io) sources live in a `diagrams/` subdirectory next to the page that uses them. Draw the
+diagram with the [desktop app or diagrams.net](https://www.diagrams.net/) and save the `.drawio` file there.
+
+Diagrams are pre-rendered at build time into separate light and dark SVGs so they track the site's theme toggle
+correctly. To wire up a new diagram, add its path to `DUAL_THEME_DIAGRAMS` in [`conf.py`](docs-source/conf.py):
+
+```python
+DUAL_THEME_DIAGRAMS = [
+    "field/network/diagrams/ssl_field_network_fanout_truss.drawio",
+    "field/network/diagrams/ssl_field_network_fanout_direct.drawio",
+    "field/network/diagrams/my_new_diagram.drawio",  # new entry
+]
+```
+
+Then reference the generated `.light.svg` / `.dark.svg` pair with Furo's theme-scoped image classes:
+
+````
+```{image} diagrams/my_new_diagram.light.svg
+:class: only-light
+:alt: Description of the diagram
+```
+
+```{image} diagrams/my_new_diagram.dark.svg
+:class: only-dark
+:alt: Description of the diagram
+```
+````
+
+Building the docs (inside `nix develop`) regenerates the two SVGs from the `.drawio` source automatically. The
+generated svg files should not be committed to git and are ignored by the top-level .gitignore file by default.
+
+## Opening Issues
+
+Feel free to open issues to raise bugs, request new pages, or discuss the reorganization or migration of existing
+documentation. Take a look at the `type` labels and be sure to assign the right one. Please open a discussion issue
+if you expect to make a large contribution or otherwise thing the community might want to weigh in, including 
+dividing up work or setting scope.
+
+## Opening PRs
+
+Contributions are made though pull requests. If your PR addressing one or more issues, please tag them in in the
+description.
+
+**PRs Must Include an AI Disclosure!** Please briefly describe what, if anything, AI assisted with.
+
+## Usage of AI
+
+Usage of AI is generally encouraged. The documentation maintainers strongly prefer pictures, graphics, diagrams,
+and interactive webpages to static prose. AI is a powerful tool to improve visual communication. Use of AI is also
+a powerful tool for language translation and improving technical brevity.
+
+**The author is responsible for the output of their AI.** We expect authors to check generated content for accuracy.
+The AI must maintain a concise neutral or slightly friendly tone. Aggressive critical tone of in-league resources is
+discouraged as is overly sycophantic or flattering language. Do not generate large amounts of text. This is technical 
+documentation designed primarily for utility.
+
+### Improving Language Density
+
+The following prompt is an example of guidance that can be given to an AI helping you write prose:
+
+> Use simple technical english. Do not use abbreviations, but standard acronyms are acceptable. Do not use sentence 
+> fragments. Strip or rewrite any casual and non-technical prose to emphasize readabilty of technical documentation. 

README.md

@@ -1,10 +1,11 @@
 # SSL Docs
 
 [**Live docs → robocup-ssl.github.io/ssl-docs**](https://robocup-ssl.github.io/ssl-docs/)
-
 [![Build and deploy docs](https://github.com/RoboCup-SSL/ssl-docs/actions/workflows/docs.yml/badge.svg)](https://github.com/RoboCup-SSL/ssl-docs/actions/workflows/docs.yml)
 [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](LICENSE)
 
+See the [Contributing Guide](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md)!
+
 RoboCup Small Size League docs. [Sphinx](https://www.sphinx-doc.org/) + [MyST](https://myst-parser.readthedocs.io/), deployed to GitHub Pages via Actions.
 
 This repository documents top level items, such as field architecture, new team guides, etc. Highly technical documentation regarding the usage of a