cmba-bylaws/.ai/project-context.md

Project Context

Project Summary

This repository stores and publishes the governing documents for the Chicago Metropolitan Baseball Association (CMBA).

The canonical source text lives in Markdown files under docs/. The repository also contains the MkDocs configuration, build tooling, and CI/release workflows used to publish those documents as a static documentation site.

Project Goals

• Keep the current CMBA governing documents in version-controlled plain text
• Publish a readable static site for league officials, managers, and players
• Preserve a clear separation between bylaws, policy, and playing rules
• Make edits reviewable, traceable, and easy to validate before publication
• Maintain enough project history to understand how the governing documents evolved

Document Model

The repository is organized around three core documents:

• docs/01-bylaws.md: league governance, authority, membership, meetings, and amendment structure
• docs/02-policy.md: league operations, procedures, discipline, administration, and competition governance
• docs/03-playing-rules.md: on-field rules, lineup formats, game administration, and incorporated baseball rules

When interpreting or editing content, preserve that separation unless the user explicitly wants to reorganize the document set.

The site home page in docs/index.md describes the intended hierarchy:

1. Bylaws
2. League Policy
3. Playing Rules

For on-field administration, the playing rules also incorporate Official Baseball Rules where CMBA rules do not provide otherwise.

Repository Structure

• docs/: canonical published content and site assets
• docs/assets/: logos and site images
• docs/styles/: site-specific CSS
• mkdocs/mkdocs.yml: MkDocs site configuration
• mkdocs/requirements.txt: Python build dependencies
• tools/build.sh: local/CI build entry point for MkDocs
• tools/spellcheck/: CSpell config and baseball-specific dictionary
• .github/workflows/ci-docs.yml: validation workflow for spelling and docs build
• .github/workflows/release.yml: release packaging and publishing workflow

Working Assumptions For AI

• Treat Markdown files under docs/ as the canonical source of truth
• Prefer editing the source documents rather than generated outputs
• Keep cross-references, headings, and document numbering stable unless there is a reason to change them
• Avoid mixing governance text, operational policy, and game rules without explicit justification
• If a change affects wording, structure, or links, local preview/build validation is useful
• League-specific terms may need updates to tools/spellcheck/baseball-words.txt
• Check .ai/skills/ before substantive work and use the relevant local skill when the task matches one

Local Development Workflow

Typical local commands:

python3 -m pip install -r mkdocs/requirements.txt
mkdocs serve -f mkdocs/mkdocs.yml

Builds are driven by MkDocs with mkdocs/mkdocs.yml, and tools/build.sh wraps the production build command with optional strict mode.

Historical Context

• The constitution and bylaws were modernized in Google Docs in 2021
• This repository moves that work into Git and GitHub
• Earlier tracked history reaches back to 2016
• In 2026, the material was re-architected into the current split between bylaws, policy, and playing rules. The league was also re-organized into a non-profit organization.

Recommended AI Usage

Use this file for stable repository context.

Put task-specific material elsewhere under .ai/, for example:

• plans/ for implementation plans
• notes/ for research notes
• scratch/ for temporary generated files

If future AI-specific conventions are added, record them in .ai/README.md and keep this file focused on the project itself.