Scheduling docs: Spanish entity/field names and documentation gaps

[sebastianbarrozo]

Problem

The scheduling documentation uses Spanish entity names, field names, and API parameters. This creates confusion for tenants built with English conventions and is inconsistent with the rest of the Fyso platform (which uses English entity names in presets like doctors, patients, appointments).

Spanish names that should be English

Entity names

Current (Spanish)	Suggested (English)
horarios	schedules
excepciones_horario	schedule_exceptions
turnos	appointments / bookings

Field names

Current (Spanish)	Suggested (English)
profesional_id	professional_id or doctor_id
paciente_id	patient_id
hora_inicio	start_time
hora_fin	end_time
duracion	duration
activo	active
fecha	date
hora	time
notas	notes
tipo	type

REST API query params

Current (Spanish)	MCP equivalent (English)
profesional_id	professional_id
fecha	date
desde	from
hasta	to

Response fields

Slot objects return fecha, hora, duracion, profesional_id — should be date, time, duration, professional_id.

Documentation gaps found

1. No exact field schema: The docs describe fields conceptually ("includes fields for the professional's ID, recurrence rule...") but never list the exact fieldKey, fieldType, isRequired for each entity. Without this, it's impossible to know what the engine expects.

2. RRule format undocumented: Mentions "RFC 5545 / RRule format" but gives zero examples. What does a typical rrule look like for "every Monday 9:00-13:00"? What fields combine with the rrule (does hora_inicio/hora_fin override the rrule times)?

3. No entity discovery docs: How does the scheduling engine find the entities? By exact name? By convention? Can it be configured to use different entity names? When entities don't exist, get_slots silently returns [] with no error — this is very hard to debug.

4. MCP vs REST param inconsistency: MCP get_slots uses English (professional_id, date, from, to), REST uses Spanish (profesional_id, fecha, desde, hasta). The docs show both but don't explain this mismatch.

5. create_booking uses Spanish fields: The create_booking example uses profesional_id, paciente_id, fecha, hora, notas — inconsistent with MCP conventions.

6. No error/troubleshooting docs: What happens when the required entities don't exist? When the professional has no schedules? When fields are missing? The engine returns empty arrays silently, making it extremely hard to diagnose issues.

7. Clinica preset vs docs mismatch: The clinica preset installs entities with English names (doctors, appointments, exceptions) and embedded schedule fields (mon_enabled, mon_from_1, etc.) — but the scheduling engine expects Spanish entity names (horarios, turnos) with completely different field conventions. This means the preset and the scheduling engine are incompatible out of the box.

Context

Discovered while debugging why get_slots returned empty for a consultorio tenant. The tenant was built following the clinica preset conventions (English entity names, embedded schedule fields in doctors), but the scheduling engine silently expected horarios/excepciones_horario/turnos entities that didn't exist.