# AGENTS.md

## Project Overview

This repository contains an oTree experiment project for a Charity Navigator-style study. The active oTree project directory is:

- `/home/ckormylo/CharityNavigator/CharNav`

The top-level repository directory is not itself the oTree project root. oTree commands should be run from `CharNav/`, because that is where `settings.py` lives.

The experiment is structured as a continuous participant flow:

1. `consent_intro`
2. `org_evaluation`
3. `donation_allocation`
4. `payment`

The core experimental idea is that participants review humanitarian organizations in a platform-style interface, then allocate a $10 bonus across those organizations or keep some/all of it.


## Current App Structure

Apps currently implemented under `CharNav/`:

- `consent_intro`
- `org_evaluation`
- `donation_allocation`
- `payment`

Key project files:

- `/home/ckormylo/CharityNavigator/CharNav/settings.py`
- `/home/ckormylo/CharityNavigator/CharNav/_static/global/experiment.css`


## Session Configuration

`settings.py` currently defines one session config:

- `charity_navigator_experiment`

Its app sequence is:

- `consent_intro`
- `org_evaluation`
- `donation_allocation`
- `payment`

`num_demo_participants` is set to `1`.


## App-by-App Summary

### 1. `consent_intro`

Purpose:

- Collect consent
- Provide simple instructions about the study and the $10 bonus/allocation task

Implementation:

- `Player.consent` is a required Boolean radio choice
- Two pages:
  - `Consent`
  - `Instructions`

Templates:

- `/home/ckormylo/CharityNavigator/CharNav/consent_intro/templates/consent_intro/Consent.html`
- `/home/ckormylo/CharityNavigator/CharNav/consent_intro/templates/consent_intro/Instructions.html`


### 2. `org_evaluation`

Purpose:

- Core experimental app
- Participants evaluate 3 organizations total
- One organization per round
- Within-subject design with participant-level randomized order

Rounds:

- `NUM_ROUNDS = 3`

Stimuli:

- Centralized in `ORG_STIMULI` inside:
  - `/home/ckormylo/CharityNavigator/CharNav/org_evaluation/__init__.py`

Each organization currently has:

- `org_id`
- `name`
- `mission_statement`
- `condition`
- `posts`

Each post currently has:

- `caption`
- `image_paths` with 6 placeholder image filenames

Important:

- The `condition` field is stored in data but must not be shown to participants.
- Participant-facing condition labels were explicitly removed from templates.

Randomization:

- Participant-level org order is randomized with `random.sample(...)`
- Stored in `participant.vars["org_sequence"]`
- This sequence is used for:
  - org evaluation rounds
  - final donation allocation page

Round-level stored fields:

- `org_id`
- `org_name`
- `condition`
- `profile_seconds`
- `caring`
- `emotional_understanding`
- `planning`
- `decision_making`
- `favorability`

Current page flow:

- Only one page per round: `OrgProfile`

Important design change:

- The original separate `Evaluation` page was removed.
- The evaluation items are now displayed on the same page as the org profile/feed, in a right-side panel on desktop.

Current org profile page behavior:

- Left side:
  - mission statement
  - scrollable Instagram-style feed
- Right side:
  - evaluation items

Feed details:

- The feed is built from `feed_posts` prepared in Python
- Each post includes:
  - 6-image carousel
  - right hover-only next arrow
  - left hover-only previous arrow
  - dot indicators

Backward compatibility:

- `get_post_image_sequence(post)` supports both:
  - new `image_paths`
  - legacy `image_path`
- This was added because earlier participant/session data could contain stale `participant.vars["org_sequence"]` content with the old single-image structure.

Template:

- `/home/ckormylo/CharityNavigator/CharNav/org_evaluation/templates/org_evaluation/OrgProfile.html`


### 3. `donation_allocation`

Purpose:

- Final allocation decision after all organization evaluations

Fields:

- `donation_org_1`
- `donation_org_2`
- `donation_org_3`
- `total_donated`
- `amount_kept`

Behavior:

- Reads organization order from `participant.vars["org_sequence"]`
- Displays all 3 organizations on one page
- Validates that total donations do not exceed `$10`
- Computes:
  - `total_donated`
  - `amount_kept`

Also stores a summary in:

- `participant.vars["donation_summary"]`

That summary is later used in the payment app.

Template:

- `/home/ckormylo/CharityNavigator/CharNav/donation_allocation/templates/donation_allocation/Allocation.html`


### 4. `payment`

Purpose:

- Final summary page
- Displays donated amount, kept amount, and total bonus

Behavior:

- Reads `participant.vars["donation_summary"]`
- Sets `player.payoff = amount_kept`

Template:

- `/home/ckormylo/CharityNavigator/CharNav/payment/templates/payment/Summary.html`


## Front-End / Styling

Shared CSS file:

- `/home/ckormylo/CharityNavigator/CharNav/_static/global/experiment.css`

This currently styles:

- consent/instructions panels
- org profile hero section
- Instagram-style feed shell
- scrollable feed area
- carousel arrows/dots
- side-by-side org-review layout
- donation allocation cards
- payment summary

Important UI constraints already implemented:

- No participant-facing Human / AI / Hybrid labels remain in templates or CSS
- Carousel arrows only appear on hover
- Left arrow appears when not on first image
- Right arrow appears when not on last image
- On mobile, the side-by-side org evaluation layout collapses to one column


## Files Created or Modified So Far

Created:

- `/home/ckormylo/CharityNavigator/CharNav/consent_intro/__init__.py`
- `/home/ckormylo/CharityNavigator/CharNav/consent_intro/templates/consent_intro/Consent.html`
- `/home/ckormylo/CharityNavigator/CharNav/consent_intro/templates/consent_intro/Instructions.html`
- `/home/ckormylo/CharityNavigator/CharNav/org_evaluation/__init__.py`
- `/home/ckormylo/CharityNavigator/CharNav/org_evaluation/templates/org_evaluation/OrgProfile.html`
- `/home/ckormylo/CharityNavigator/CharNav/donation_allocation/__init__.py`
- `/home/ckormylo/CharityNavigator/CharNav/donation_allocation/templates/donation_allocation/Allocation.html`
- `/home/ckormylo/CharityNavigator/CharNav/payment/__init__.py`
- `/home/ckormylo/CharityNavigator/CharNav/payment/templates/payment/Summary.html`
- `/home/ckormylo/CharityNavigator/CharNav/_static/global/experiment.css`

Deleted during refactor:

- `/home/ckormylo/CharityNavigator/CharNav/org_evaluation/templates/org_evaluation/Evaluation.html`

Modified:

- `/home/ckormylo/CharityNavigator/CharNav/settings.py`


## Data / State Conventions

Participant vars currently used:

- `participant.vars["org_sequence"]`
- `participant.vars["donation_summary"]`

Notes:

- `org_sequence` is central to preserving consistent ordering between evaluation and allocation.
- If the org stimulus structure changes in the future, be careful about stale data already stored in `participant.vars`.


## Known Technical Notes

1. oTree template engine limitations encountered

- Some Django/Jinja conveniences are not available in this environment.
- Unsupported usages already removed:
  - `|lower`
  - `forloop.first`

The current templates avoid these patterns by precomputing data in Python.

2. Database/session staleness

- During development, stale DB/session data caused issues because old `participant.vars["org_sequence"]` values used an earlier stimulus schema.
- `get_post_image_sequence()` was added as a compatibility layer.
- If needed, a full reset can be done by deleting `db.sqlite3` in `CharNav/` and recreating sessions.

3. Current verification status

- Import checks for the apps succeeded from inside `CharNav/`
- `otree create_session charity_navigator_experiment 1` succeeded
- At one point `otree test` requested a database reset because oTree had been updated


## Recommended Commands

Run from:

- `/home/ckormylo/CharityNavigator/CharNav`

Useful commands:

```bash
../venv/bin/otree devserver
../venv/bin/otree create_session charity_navigator_experiment 1
../venv/bin/otree test charity_navigator_experiment 1
```

If `otree test` complains about DB compatibility, remove `db.sqlite3` and recreate the session.


## Assumptions Embedded in Current Scaffold

- Exactly 3 organizations are used right now
- Final allocation page has exactly 3 donation fields
- Bonus endowment is `$10`
- The social feed currently uses placeholder image filenames rather than actual assets
- The feed handle format `@{{ org.org_id }}community` is purely presentational

If the study expands beyond 3 organizations, `donation_allocation` should be refactored to support a dynamic number of inputs rather than fixed `donation_org_1..3`.


## Good Next Steps for a Future Agent

- Replace placeholder image filenames with actual static assets
- Refine the page styling and spacing after live browser inspection
- Add attention checks if desired
- Add bots/tests for the full participant flow
- Refactor donation allocation to handle a dynamic number of organizations
- Move stimuli to a separate module/file if they become larger