Souldroid-Chat/AGENTS.md

# AGENTS.md

Agent guidance for this repository (`Soul Droid Chat`).

## Quick Start for New Agents

1. Read `game/script.rpy`, `game/screens.rpy`, and `game/llm_ren.py` to understand flow and LLM integration.
2. Run `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint` before making changes.
3. Make small, focused edits that preserve Ren'Py ids and the `EMOTION:<value>` response contract.
4. Validate with `compile` and `test` (`test <testcase_or_suite_name>` for a single case while iterating).
5. Avoid committing generated artifacts/logs (`*.rpyc`, `game/cache/`, `log.txt`, `errors.txt`, `traceback.txt`) or secrets.
6. In your handoff, include what changed, why, and exact validation commands run.

## Project Snapshot

- Engine: Ren'Py 8.5.x project with script files in `game/*.rpy`.
- Python support code is embedded in Ren'Py files and `game/*_ren.py`.
- Runtime dependency: LM Studio server (default `http://localhost:1234`).
- No dedicated `tests/` directory was found; use Ren'Py `lint` and `test`.

## Repository Layout

- `game/script.rpy`: main dialogue/game flow loop.
- `game/screens.rpy`: UI screens, preferences, and menus.
- `game/options.rpy`: Ren'Py/build/runtime config and defaults.
- `game/llm_ren.py`: LLM call logic, parsing, and sanitizing.
- `game/constants_ren.py`: emotion synonym table.
- `project.json`, `android.json`: distribution/build settings.

## Tooling and Environment

- Expected Ren'Py launcher script: `/home/micost/renpy-8.5.2-sdk/renpy.sh`.
- CLI usage pattern:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "<repo-path>" <command> [args]`
- Python in environment is available (`python3`), but gameplay validation should use Ren'Py commands.

## Build, Lint, and Test Commands

Run all commands from repository root:
`/home/micost/Documentos/Renpy Projects/Soul Droid Chat`

### Quick checks (most common)

- Lint project:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint`
- Run game locally:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" run`
- Compile scripts/python cache:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" compile`

### Test execution (Ren'Py test runner)

- Run default/global test suite:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test`
- Run a single test suite or testcase (important):
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test <testcase_or_suite_name>`
- Show detailed test report:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --report-detailed`
- Run all testcases even if disabled:
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --enable-all`

### Distribution/build packaging

- Create distributions (launcher command):
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" distribute`
- Android build exists as a Ren'Py command (if SDK/keystore configured):
  - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" android_build`

## Suggested Validation Sequence for Agents

1. `lint`
2. `compile`
3. `test` (or `test <single_case>` when iterating)
4. `run` for a manual smoke check on the edited flow/screen

If a command fails, include the failing command and key error excerpt in your report.

## Code Style Guidelines

### General principles

- Match existing Ren'Py and Python style in nearby files.
- Prefer small, focused changes; avoid unrelated refactors.
- Keep user-facing narrative tone and Anita persona constraints intact.
- Preserve ASCII-oriented output behavior where current code expects it.

### Ren'Py script/style conventions (`.rpy`)

- Use 4-space indentation; never tabs.
- Keep labels/screen names `snake_case` (`label start`, `screen quick_menu`).
- Keep style declarations grouped and readable (existing file order is a good template).
- For dialogue flow, keep Python blocks short; move reusable logic to `*_ren.py`.
- Use explicit keyword args when clarity helps (`prompt =`, `fadeout`, `fadein`).
- Do not rename core ids required by Ren'Py (`"window"`, `"what"`, `"who"`, `"input"`).

### Python conventions (`*_ren.py` and embedded `init python`)

- Imports:
  - Standard library first (`re`).
  - Ren'Py modules (`renpy`, `persistent`).
  - Local imports last (`from .constants_ren import SYNONYMS`).
- Naming:
  - Functions/variables: `snake_case`.
  - Constants: `UPPER_SNAKE_CASE` (`EMOTIONS`, `SYSTEM_PROMPT`).
  - Keep names descriptive (`parse_emotion`, `sanitize_speech`, `fetch_llm`).
- Types:
  - Add type hints on new/edited Python functions when practical.
  - Keep return types accurate (for list-returning functions, annotate accordingly).
- Formatting:
  - Follow PEP 8 basics for spacing, line breaks, and readability.
  - Keep multiline literals and dicts formatted consistently with existing file style.

### Error handling and resilience

- Wrap external boundary calls (network/LM Studio) with `try/except`.
- Return safe fallback values that keep game loop stable.
- Error messages should be concise and actionable for debugging.
- Avoid swallowing exceptions silently; at minimum return or log context.
- Preserve conversation continuity fields when present (`last_response_id`).

### LLM integration constraints

- Keep `SYSTEM_PROMPT` format guarantees consistent unless intentionally changing behavior.
- Maintain `EMOTION:<value>` parsing contract used by dialogue rendering.
- If you add emotions, update both:
  - `EMOTIONS` in `game/llm_ren.py`
  - `SYNONYMS` in `game/constants_ren.py`
- Keep speech sanitization aligned with UI/rendering constraints.

### UI/screens changes

- Reuse existing `gui.*` variables and style helpers where possible.
- Keep mobile/small variant handling (`renpy.variant("small")`) intact.
- Prefer extending existing screens over introducing parallel duplicate screens.
- For settings UI, follow patterns already used in `preferences` screen.

## Agent Working Rules

- Before edits:
  - Read related files fully (at least the touched blocks and nearby context).
  - Check for existing patterns and follow them.
- During edits:
  - Do not include secrets or API keys in committed files.
  - Do not commit generated caches/logs (`*.rpyc`, `log.txt`, `errors.txt`, `traceback.txt`).
- After edits:
  - Run relevant validation commands from the section above.
  - Summarize what changed, why, and what was validated.

## Git and Change Scope

- Keep commits scoped to the requested task.
- Avoid touching binary assets unless the task explicitly requires it.
- If a keystore or credential-like file is changed, call it out explicitly.
- Do not rewrite history unless explicitly requested.

## Cursor/Copilot Rules Status

- No repository-specific Cursor rules were found:
  - `.cursor/rules/` not present.
  - `.cursorrules` not present.
- No repository-specific Copilot instruction file found:
  - `.github/copilot-instructions.md` not present.

If any of the above files are added later, treat them as higher-priority constraints and update this document.