builder-prototype/CLAUDE.md

# Dispute Protocol Builder

This is a prototype website, built in Hugo, to enable communities to develop customizable protocols for dispute resolution processes. It guides users through an accessible process that provides best practices while allowing for customization.

## Project Structure

- **Static Site Generator**: Hugo
- **Main Builder Interface**: `/themes/dispute-protocol-theme/layouts/_default/builder.html`
- **JavaScript Files**:
  - `/static/js/builder.js`: Main application logic
- **Data Files**:
  - `/data/stages_array.yaml`: Protocol structure (stages, components, and fields)
  - `/data/templates/*.yaml`: Protocol template definitions with complete content

## Content Organization

- **Stages and Components**: Building blocks of a protocol, defined in `/data/stages_array.yaml`
- **Templates**: Complete predefined protocols with content for all fields, defined in `/data/templates/*.yaml`
- **Hugo Data System**: Templates are loaded from YAML files via Hugo's data system and made available to JavaScript

## Data Model

The application maintains a hierarchical data model:
- **Stages** → **Components** → **Fields**
- Each field is populated with content directly from templates
- Protocol structure: 6 stages with 16 total fields across all components

### Protocol Structure (from `/data/stages_array.yaml`):

1. **Basics** (3 components): community_rules, shared_values, information_access
2. **Process** (3 components): process_start, facilitation, ground_rules
3. **Assessment** (3 components): dispute_assessment, jurisdiction, non_participation
4. **Deliberation** (3 components): deliberation_process, additional_voices, deliberation_conclusion
5. **Resolution** (2 components): resolution_process, resolution_failure
6. **Appeal** (2 components): appeal_criteria, appeal_process

## Core Features

1. **Black & white UI**: Clean, accessible interface with vertical accordion sections
2. **Template selection**: Users can start with a predefined protocol template
3. **Customization**: Direct text editing in fields
4. **Export options**: Markdown, PDF, and JSON formats
5. **Import capability**: Load previously saved protocols
6. **Preview mode**: Toggle to see how the final protocol will appear

## Template System

Templates provide complete content for dispute resolution protocols:
- Each template has: `id`, `title`, `description`, and nested content data
- Templates define content for all stages and components in YAML format
- Templates are loaded by Hugo from `/data/templates/` and injected into JavaScript via `builder.html`
- The template selector provides one-click application of complete protocols
- Templates are automatically cleared when switching to ensure clean slate

### Available Templates:

1. Peer-to-Peer
2. Chosen Facilitator
3. Community Jury
4. Facilitation Council
5. Community Referee
6. Shalish Mediation
7. Restorative Justice
8. Transformative Justice

## Recent Improvements

1. **Template clearing on switch**: Ensures old template content doesn't persist when switching templates
2. **Complete template coverage**: All templates now have content for all 16 protocol fields
3. **Component titles**: Simplified all component titles to be more direct and consistent
4. **Preview mode**: Improved rendering of protocol content with Markdown support
5. **Consolidated data structure**: Combined stages and components into a unified structure for better maintainability
6. **Improved template selection**: Updated the template selector from a dropdown to an expandable section with descriptions

## Deployment

- Deployable from a self-hosted GitLab server
- All data is maintained in YAML files for stages, components, and templates
- Hugo processes YAML data and makes it available to JavaScript for client-side functionality

## Key Files to Modify

### Adding or Editing Templates:
- `/data/templates/*.yaml`: Add, edit or remove protocol templates
- Each template must include all 6 stages with appropriate components and fields

### Modifying Protocol Structure:
- `/data/stages_array.yaml`: Edit stages and components structure in one consolidated file
- Changes here will affect the builder interface and available fields

### Customizing Interface:
- `/static/js/builder.js`: Modify core interface functionality (template application, export, etc.)
- `/themes/dispute-protocol-theme/layouts/_default/builder.html`: Modify HTML structure
- `/static/css/main.css`: Adjust styling and responsive behavior

### Configuration:
- `/config.toml`: Hugo site configuration
- `/themes/dispute-protocol-theme/layouts/partials/head.html`: Script and style includes