Time Tracking

Two related concepts

Flow: start / stop a timer

stos_time_tracking_start({ penNameId, bookId: titleId, chapterId, note: 'Drafting' })
// later
stos_time_tracking_stop({ id })  // sets end_time = now

If the user doesn't specify a pen name + title, ask which they're tracking against (or default to their active one).

Flow: log a completed session

If the user worked offline and wants to log retroactively, use stos_time_tracking_create({ fields: { start_time, end_time, notes } }) with both times set (ISO timestamps).

Flow: review

For "how much time did I spend on [X]":

stos_time_tracking_list({ penNameId, limit: 'all' })

The list has no title filter, so narrow to the title yourself where the entries carry it. Sum the (end_time − start_time) differences and report. If the user wants a per-day breakdown, group locally.

Pomodoro settings

If the user references pomodoro defaults:

stos_pomodoro_settings_get()
stos_pomodoro_settings_update({ fields: { focus_minutes: 25, ... } })

Writing goals

Goal-tracking is a separate flow:

stos_writing_goals_list()
stos_writing_goals_create({ fields: { goal_name, goal_type: 'daily', target_words: 1500, start_date } })

Use this when the user says "set a goal of 1500 words/day" or "I'm aiming to finish by [date]".

Anti-patterns

• Auto-stopping the user's timer. Don't stop a timer unless the user asked. They may have walked away and want the elapsed time counted.
• Starting a timer without scope. If you can't infer pen name + title, ask — otherwise the entry hangs unattributed.