= Contributing to Seven Tentacles
:toc:

Thank you for your interest in contributing to Seven Tentacles! This document
provides guidelines for contributing to the project.

== Getting Started

=== Prerequisites

* Git
* Node.js 20+
* Nix (recommended) or manual dependency management

=== Setting Up Development Environment

[source,bash]
----
# Clone the repository
git clone https://github.com/Hyperpolymath/7-tentacles.git
cd 7-tentacles

# Enter development environment (if using Nix)
nix develop

# Or install dependencies manually
npm install

# Run the development server
just dev
----

== How to Contribute

=== Types of Contributions

We welcome contributions in these areas:

1. **Curriculum Content**
   * Writing new lessons for any agent
   * Improving existing lessons
   * Creating activities and games

2. **Code**
   * Language implementations (Me, Solo, Duet, Ensemble)
   * Interactive tools and visualizations
   * Bug fixes and improvements

3. **Documentation**
   * Improving guides and tutorials
   * Translations
   * Accessibility documentation

4. **Design**
   * Mascot artwork
   * UI/UX improvements
   * Accessibility enhancements

=== Contribution Process (TPCF Framework)

We use the Think-Propose-Collaborate-Finalize framework:

1. **Think:** Research and understand the problem
2. **Propose:** Open an issue describing your proposed change
3. **Collaborate:** Discuss with maintainers and community
4. **Finalize:** Submit a pull request

=== Pull Request Guidelines

* Create a feature branch from `main`
* Write clear commit messages
* Include tests where applicable
* Update documentation as needed
* Follow the code style guidelines

== Code Style

=== ReScript

* Use meaningful variable names
* Add comments for complex logic
* Follow existing patterns in the codebase

=== AsciiDoc (Curriculum)

* Use consistent heading levels
* Include learning objectives
* Add "What You Really Learned" sections

=== HTML/CSS/JavaScript

* Semantic HTML
* CSS variables for theming
* Accessible by default (WCAG 2.1 AA)

== Curriculum Contribution Guidelines

When writing lessons:

1. **Age-Appropriate Language**
   * Cuttle (8-12): Simple, playful, no jargon
   * Squidlet (13-14): Introduce technical terms gradually
   * Duet (15): Full technical vocabulary
   * Octopus (16+): Academic level

2. **Hidden Learning**
   * Always include the CS concept being taught
   * Don't reveal it directly to younger learners
   * Make the reveal satisfying for older learners

3. **Accessibility**
   * Include alt text for images
   * Provide text alternatives for games
   * Consider colorblind users

== Testing

[source,bash]
----
# Run all tests
just test

# Check curriculum structure
just count-lessons

# Validate documentation
just build-docs
----

== License

By contributing, you agree that your contributions will be licensed under the
same license as the project (MIT + Palimpsest v0.8).

== Questions?

Open an issue or reach out to the maintainers. We're happy to help!
