Synculous-2/HOOKS.md

Where the hooks are

API route registration — api/main.py

Lines 10-17: imported route modules and added to ROUTE_MODULES:

• api.routes.routines
• api.routes.medications
• api.routes.routine_steps_extended
• api.routes.routine_sessions_extended
• api.routes.routine_templates
• api.routes.routine_stats
• api.routes.routine_tags

Bot command registration — bot/bot.py

Lines 23-24: imported bot.commands.routines and bot.commands.medications These imports trigger register_module() and register_validator() at load time, which makes the bot's AI parser route "routine" and "medication" interaction types to the right handlers.

Bot command handlers — bot/commands/routines.py, bot/commands/medications.py

Each file:

• Defines an async handler (handle_routine, handle_medication)
• Defines a JSON validator for the AI parser
• Calls register_module() to hook into the command registry
• Calls ai_parser.register_validator() to hook into parse validation

Scheduler — scheduler/daemon.py

poll_callback() now calls three check functions on every tick:

• check_medication_reminders() — sends notifications for doses due now
• check_routine_reminders() — sends notifications for scheduled routines
• check_refills() — warns when medication supply is running low

All three use core.notifications._sendToEnabledChannels() to deliver.

AI config — ai/ai_config.json

Updated the command_parser system prompt to list the two interaction types (routine, medication) and the fields to extract for each. This is what tells the LLM how to parse natural language into the right action structure.

Extended Routines API — New Modules

Routine Steps Extended — api/routes/routine_steps_extended.py

• PUT /api/routines/<id>/steps/<step_id>/instructions — update step instructions
• PUT /api/routines/<id>/steps/<step_id>/type — update step type (timer, checklist, etc)
• PUT /api/routines/<id>/steps/<step_id>/media — update media URL

Routine Sessions Extended — api/routes/routine_sessions_extended.py

• POST /api/sessions/<id>/pause — pause active session
• POST /api/sessions/<id>/resume — resume paused session
• POST /api/sessions/<id>/abort — abort with reason
• POST /api/sessions/<id>/note — add note to session
• PUT /api/sessions/<id>/duration — record actual duration
• GET /api/sessions/<id> — get session with notes

Routine Templates — api/routes/routine_templates.py

• GET /api/templates — list templates
• POST /api/templates — create template
• GET /api/templates/<id> — get template with steps
• POST /api/templates/<id>/clone — clone to user's routines
• PUT /api/templates/<id> — update template
• DELETE /api/templates/<id> — delete template
• POST /api/templates/<id>/steps — add step to template

Routine Stats — api/routes/routine_stats.py

• GET /api/routines/<id>/stats — completion stats
• GET /api/routines/streaks — all user streaks
• GET /api/routines/<id>/streak — specific routine streak
• GET /api/routines/weekly-summary — weekly progress

Routine Tags — api/routes/routine_tags.py

• GET /api/tags — list tags
• POST /api/tags — create tag
• DELETE /api/tags/<id> — delete tag
• POST /api/routines/<id>/tags — add tags to routine
• DELETE /api/routines/<id>/tags/<tag_id> — remove tag
• GET /api/routines/<id>/tags — get routine's tags

Core Modules — Business Logic

core/routines.py

Shared functions for routine operations:

• start_session() — create and start a new session
• pause_session() — pause an active session
• resume_session() — resume a paused session
• abort_session() — abort with reason
• complete_session() — mark complete and update streak
• clone_template() — clone template to user's routines
• calculate_streak() — get current streak

core/stats.py

Statistics calculation functions:

• get_routine_stats() — completion rate, avg duration, total time
• get_user_streaks() — all streaks for user
• get_weekly_summary() — weekly progress summary
• get_monthly_summary() — monthly progress summary

Bot Commands — Extended Routines

New actions added to bot/commands/routines.py:

• pause — pause current session
• resume — resume paused session
• abort — abort with reason
• note — add note to session
• stats — show completion statistics
• streak — show current streak
• templates — list available templates
• clone — clone a template
• tag — add tag to routine