coach_zed 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2d8daf5761eb18163bfa3580c333a16f45d78e9c42cba6c57fdcc10f181d029
+  data.tar.gz: f1587187415f4436aee180a525b26e09157c947ac00efe0ca833cd69dca0338c
+SHA512:
+  metadata.gz: c3dd7fd8e883d7d5cf970e5ef71b0aed8e1c4f5e1dec12b072b0f1f6bef511d27cbab4128556782438506e943e72a7d8f8f8035d32b7dcd65a1a27dc32f36d06
+  data.tar.gz: d11ce506d3f700217bf1ba9fe02d425aeadbf4b385e0eb04b8ac8e74d0e461b462c26cfcf57a056b4f8123f0c9e27aae9aafcc9d6e38dc906a9a7c9a4e2f1272

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+## [](https://github.com/rossta/coach_zed/compare/v0.4.0...v) (2026-06-15)
+
+### Bug Fixes
+
+* bump version ([588bd4a](https://github.com/rossta/coach_zed/commit/588bd4a8a67ab005523648132fdfdf41835e05e5))
+## [](https://github.com/rossta/coach_zed/compare/v0.3.0...v) (2026-06-15)
+
+### Features
+
+* add steep typechecking ([7dd711b](https://github.com/rossta/coach_zed/commit/7dd711b3bdd15d5b04a6917bb5864b513fcc35d7))
+## [](https://github.com/rossta/coach_zed/compare/v0.2.0...v) (2026-06-15)
+
+### Features
+
+* nudge release pipeline again ([91166c9](https://github.com/rossta/coach_zed/commit/91166c9d0392d18f4723d4c96d7cd0bedd28b215))
+## [](https://github.com/rossta/coach_zed/compare/v0.1.0...v) (2026-06-15)
+
+### Features
+
+* add config defaults and data result ([c5a4d81](https://github.com/rossta/coach_zed/commit/c5a4d81aa269bde5a85d7f8bb7fa4afaa1a3f6dd))
+* nudge release pipeline ([fac7bb8](https://github.com/rossta/coach_zed/commit/fac7bb87969dfae2c5112061cf0b8dffba6159c7))
+* rename fitness_butler to coach_zed ([2d8be2d](https://github.com/rossta/coach_zed/commit/2d8be2d3855fb93c09f104689e94a014ce05d85f))
+## [Unreleased]
+
+## [0.1.0] - 2026-06-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ross Kaffenberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+# CoachZed
+
+CoachZed reads a workout catalog, asks an AI client for a day-by-day training plan, and writes schedule JSON plus calendar feeds.
+
+## Configuration
+
+You can set shared defaults with:
+
+```ruby
+CoachZed.configure do |config|
+  config.workout_catalog_dir = "workouts"
+  config.output_dir = "results"
+end
+```
+
+`CoachZed.new` also loads defaults from either:
+
+- `.coach_zed.yml` in the current directory
+- `~/.config/coach_zed.yml`
+
+If a config file is present, you can initialize with just `client:`.
+
+Generated files are written beneath `output_dir`:
+
+- `output_dir/schedules`
+- `output_dir/feeds`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. Releases are automated through GitHub Actions: conventional commits determine the next version, the workflow updates `lib/coach_zed/version.rb` and `CHANGELOG.md`, tags the release, builds the gem, and publishes the package to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/coach_zed. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/coach_zed/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the CoachZed project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/coach_zed/blob/main/CODE_OF_CONDUCT.md).

data/lib/coach_zed/catalog.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "digest"
+require "pathname"
+
+class CoachZed
+  module Catalog
+    class Entry
+      attr_reader :path, :relative_path, :title, :domain, :session_duration, :frequency, :program, :format, :equipment, :summary, :work_items, :notes, :source_urls
+
+      def initialize(
+        path:,
+        relative_path:,
+        title:,
+        summary:,
+        work_items:,
+        notes:,
+        source_urls:,
+        domain: nil,
+        session_duration: nil,
+        frequency: nil,
+        program: nil,
+        format: nil,
+        equipment: nil
+      )
+        @path = path
+        @relative_path = relative_path
+        @title = title
+        @domain = domain
+        @session_duration = session_duration
+        @frequency = frequency
+        @program = program
+        @format = format
+        @equipment = equipment
+        @summary = summary
+        @work_items = work_items
+        @notes = notes
+        @source_urls = source_urls
+      end
+
+      def fingerprint
+        Digest::SHA256.hexdigest([
+          relative_path,
+          title,
+          domain,
+          session_duration,
+          frequency,
+          program,
+          format,
+          equipment,
+          summary,
+          work_items.join("\n"),
+          notes.join("\n"),
+          source_urls.join("\n")
+        ].join("\u0000"))
+      end
+
+      def to_h
+        {
+          "path" => path.to_s,
+          "relative_path" => relative_path,
+          "title" => title,
+          "domain" => domain,
+          "session_duration" => session_duration,
+          "frequency" => frequency,
+          "program" => program,
+          "format" => format,
+          "equipment" => equipment,
+          "summary" => summary,
+          "work_items" => work_items,
+          "notes" => notes,
+          "source_urls" => source_urls
+        }
+      end
+    end
+
+    class Loader
+      IGNORED_BASENAMES = %w[INDEX.md TEMPLATE.md].freeze
+
+      def initialize(root)
+        @root = Pathname(root)
+      end
+
+      def load
+        Dir.glob(@root.join("**/*.md")).sort.filter_map do |file|
+          path = Pathname(file)
+          next if ignored?(path)
+
+          parse_entry(path)
+        end
+      end
+
+      private
+
+      attr_reader :root
+
+      def ignored?(path)
+        IGNORED_BASENAMES.include?(path.basename.to_s)
+      end
+
+      def parse_entry(path)
+        relative_path = path.relative_path_from(root).to_s
+        lines = path.read.lines(chomp: true)
+        title = lines.find { |line| line.start_with?("# ") }&.sub("# ", "")
+        return if title.nil?
+
+        # @type var metadata: Hash[String, String]
+        metadata = {}
+        index = 1
+        index += 1 while index < lines.length && lines[index].strip.empty?
+        while index < lines.length
+          line = lines[index]
+          break if line.nil? || line.empty?
+          break unless line.start_with?("- ")
+
+          if (match = line.match(/^- ([^:]+):\s*(.*)$/))
+            key = normalize_key(match[1].to_s)
+            metadata[key] = strip_ticks(match[2].to_s)
+          end
+
+          index += 1
+        end
+
+        index += 1 while index < lines.length && lines[index].strip.empty?
+
+        sections = parse_sections(lines[index..] || [])
+
+        Entry.new(
+          path: path,
+          relative_path: relative_path,
+          title: title,
+          domain: metadata["domain"],
+          session_duration: metadata["session_duration"],
+          frequency: metadata["frequency"],
+          program: metadata["program"],
+          format: metadata["format"],
+          equipment: metadata["equipment"],
+          summary: sections.fetch("summary", []).join(" ").strip,
+          work_items: normalize_bullets(sections.fetch("work", [])),
+          notes: normalize_bullets(sections.fetch("notes", [])),
+          source_urls: normalize_urls(sections.fetch("source", []))
+        )
+      end
+
+      def parse_sections(lines)
+        # @type var sections: Hash[String, Array[String]]
+        sections = {}
+        current = nil
+
+        lines.each do |line|
+          if (match = line.match(/^##\s+(.+)$/))
+            current = normalize_section_name(match[1].to_s)
+            next
+          end
+
+          next unless current
+          section_name = current.to_s
+
+          sections[section_name] ||= []
+          sections[section_name] << line
+        end
+
+        sections
+      end
+
+      def normalize_section_name(name)
+        name.downcase.strip
+      end
+
+      def normalize_key(key)
+        key.downcase.tr(" -", "_")
+      end
+
+      def strip_ticks(value)
+        value.to_s.delete_prefix("`").delete_suffix("`")
+      end
+
+      def normalize_bullets(lines)
+        lines.filter_map do |line|
+          next if line.strip.empty?
+
+          line.sub(/^- /, "").strip
+        end
+      end
+
+      def normalize_urls(lines)
+        lines.filter_map do |line|
+          next unless line.match?(%r{\A-\s+https?://})
+
+          line.sub(/^- /, "")
+        end
+      end
+    end
+  end
+end

data/lib/coach_zed/clients/ruby_openai.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class CoachZed
+  module Clients
+    class RubyOpenAI
+      def initialize(client:, model: "gpt-4.1")
+        @client = client
+        @model = model
+      end
+
+      def generate(prompt:)
+        response = client.chat(parameters: {
+          model: model,
+          messages: [{role: "user", content: prompt}]
+        })
+        extract_content(response)
+      end
+
+      private
+
+      attr_reader :client, :model
+
+      def extract_content(response)
+        return response if response.is_a?(String)
+
+        if response.respond_to?(:dig)
+          content = response.dig("choices", 0, "message", "content") ||
+            response.dig(:choices, 0, :message, :content)
+          return content if content.is_a?(String)
+        end
+
+        if response.respond_to?(:[])
+          content = response["choices"]&.first&.dig("message", "content") ||
+            response[:choices]&.first&.dig(:message, :content)
+          return content if content.is_a?(String)
+        end
+
+        raise ArgumentError, "unable to extract content from ruby-openai response"
+      end
+    end
+  end
+end

data/lib/coach_zed/feed_reader.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "date"
+
+class CoachZed
+  class FeedReader
+    class Event
+      attr_reader :date, :summary, :description
+
+      def initialize(date: nil, summary: nil, description: nil)
+        @date = date
+        @summary = summary
+        @description = description
+      end
+    end
+
+    def self.load(path)
+      new(File.read(path.to_s)).events
+    end
+
+    def self.load_existing(path)
+      new(File.read(path.to_s))
+    end
+
+    def initialize(feed_content)
+      @feed_content = feed_content
+    end
+
+    attr_reader :feed_content
+
+    def events
+      @events ||= parse_events
+    end
+
+    def last_date
+      events.map(&:date).compact.max
+    end
+
+    def recent_events(limit_days: 28)
+      last = last_date
+      cutoff = last ? last - (limit_days - 1) : nil
+      return events if cutoff.nil?
+
+      events.select { |event| event.date && event.date >= cutoff }
+    end
+
+    def to_context(limit_days: 28)
+      recent_events(limit_days:).map do |event|
+        # @type var pieces: Array[String]
+        pieces = []
+        pieces << event.date.iso8601 if event.date
+        pieces << event.summary if event.summary && !event.summary.empty?
+        pieces << event.description if event.description && !event.description.empty?
+        pieces.join(" | ")
+      end.join("\n")
+    end
+
+    private
+
+    def parse_events
+      blocks = feed_content.split(/BEGIN:VEVENT\r?\n/).drop(1)
+      blocks.filter_map do |block|
+        event_text = block.split("END:VEVENT").first
+        next if event_text.nil?
+
+        Event.new(
+          date: parse_date(event_text),
+          summary: parse_line(event_text, /^SUMMARY:(.*)$/),
+          description: unescape(parse_line(event_text, /^DESCRIPTION:(.*)$/))
+        )
+      end
+    end
+
+    def parse_date(event_text)
+      value = parse_line(event_text, /^DTSTART;VALUE=DATE:(\d{8})$/)
+      return if value.nil?
+
+      Date.strptime(value, "%Y%m%d")
+    end
+
+    def parse_line(event_text, pattern)
+      match = event_text.match(pattern)
+      match && match[1]
+    end
+
+    def unescape(value)
+      value.to_s
+        .gsub("\\n", "\n")
+        .gsub("\\,", ",")
+        .gsub("\\;", ";")
+        .gsub("\\\\", "\\")
+    end
+  end
+end

data/lib/coach_zed/feed_writer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+class CoachZed
+  class FeedWriter
+    def initialize(schedule:, start_date:, existing_feed_content: nil)
+      @schedule = schedule
+      @start_date = start_date
+      @existing_feed_content = existing_feed_content
+    end
+
+    def build
+      if existing_feed_content
+        append_to_existing_feed(existing_feed_content)
+      else
+        fresh_feed
+      end
+    end
+
+    private
+
+    attr_reader :schedule, :start_date, :existing_feed_content
+
+    def fresh_feed
+      lines = header_lines
+      lines.concat(event_lines)
+      lines << "END:VCALENDAR"
+      lines.join("\r\n") + "\r\n"
+    end
+
+    def append_to_existing_feed(existing_feed)
+      event_block = event_lines.join("\r\n") + "\r\n"
+      existing_feed.sub(/END:VCALENDAR\s*\z/, "#{event_block}END:VCALENDAR\r\n")
+    end
+
+    def header_lines
+      [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//CoachZed//EN",
+        "CALSCALE:GREGORIAN",
+        "METHOD:PUBLISH",
+        "X-WR-CALNAME:#{escape(schedule_name)}",
+        "X-WR-TIMEZONE:America/New_York"
+      ]
+    end
+
+    def event_lines
+      schedule.fetch("days").flat_map do |day|
+        date = start_date + (day.fetch("day_number").to_i - 1)
+        [
+          "BEGIN:VEVENT",
+          "UID:#{schedule.fetch("schedule_id")}-#{format("%02d", day.fetch("day_number").to_i)}@coach_zed",
+          "DTSTAMP:#{generated_timestamp}",
+          "DTSTART;VALUE=DATE:#{date.strftime("%Y%m%d")}",
+          "DTEND;VALUE=DATE:#{(date + 1).strftime("%Y%m%d")}",
+          "SUMMARY:#{escape(event_summary(day))}",
+          "DESCRIPTION:#{escape(event_description(day))}",
+          "END:VEVENT"
+        ]
+      end
+    end
+
+    def schedule_name
+      schedule["program_name"] || "Training Schedule"
+    end
+
+    def generated_timestamp
+      Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
+    end
+
+    def event_summary(day)
+      return "Rest" if day["day_type"] == "rest"
+
+      day.fetch("workout").fetch("title")
+    end
+
+    def event_description(day)
+      # @type var pieces: Array[String]
+      pieces = []
+      pieces << day["notes"].to_s if day["notes"] && !day["notes"].to_s.empty?
+      if day["day_type"] == "workout"
+        workout = day.fetch("workout")
+        pieces << "Catalog path: #{workout.fetch("catalog_path")}"
+        pieces << "Domain: #{workout.fetch("domain")}"
+        pieces << "Session duration: #{workout.fetch("session_duration")}"
+      end
+      pieces.join("\n")
+    end
+
+    def escape(value)
+      value.to_s
+        .gsub("\\", "\\\\")
+        .gsub(";", "\\;")
+        .gsub(",", "\\,")
+        .gsub("\r\n", "\\n")
+        .gsub("\n", "\\n")
+    end
+  end
+end

data/lib/coach_zed/prompt_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+class CoachZed
+  class PromptBuilder
+    def initialize(consultation_prompt:, catalog:, start_date:, schedule_key:, generation_days:, existing_feed_context: nil)
+      @consultation_prompt = consultation_prompt
+      @catalog = catalog
+      @start_date = start_date
+      @schedule_key = schedule_key
+      @generation_days = generation_days
+      @existing_feed_context = existing_feed_context
+    end
+
+    def build
+      <<~PROMPT
+        You are a training coach. Build a daily training schedule for the athlete using only the provided catalog.
+
+        Return JSON only. Do not wrap it in markdown fences or commentary.
+
+        Required schema:
+        {
+          "program_name": string,
+          "program_length_days": integer,
+          "days": [
+            {
+              "day_number": integer,
+              "day_type": "workout" or "rest",
+              "workout": {
+                "title": string,
+                "catalog_path": string,
+                "domain": string,
+                "session_duration": string
+              } or null,
+              "notes": string
+            }
+          ]
+        }
+
+        Rules:
+        - Produce exactly #{generation_days} entries for the requested time period.
+        - Include rest days when appropriate.
+        - Use only workouts that exist in the catalog.
+        - Match the athlete's goals and the requested time period.
+        - If existing feed context is provided, continue from the end of the prior feed and avoid changing earlier weeks.
+        - Keep the JSON valid and complete.
+
+        Schedule metadata:
+        - Start date: #{@start_date.iso8601}
+        - Schedule key: #{@schedule_key}
+
+        Athlete consultation prompt:
+        #{@consultation_prompt}
+
+        Existing feed context (most recent weeks, if available):
+        #{existing_feed_context || "none"}
+
+        Catalog:
+        #{JSON.pretty_generate(catalog.map(&:to_h))}
+      PROMPT
+    end
+
+    private
+
+    attr_reader :consultation_prompt, :catalog, :start_date, :schedule_key, :generation_days, :existing_feed_context
+  end
+end

data/lib/coach_zed/schedule_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+class CoachZed
+  class ScheduleParser
+    class Error < StandardError; end
+
+    def self.parse(raw_schedule)
+      json = extract_json(raw_schedule)
+      schedule = JSON.parse(json)
+      validate!(schedule)
+      schedule
+    rescue JSON::ParserError => e
+      raise Error, "invalid schedule JSON: #{e.message}"
+    end
+
+    def self.extract_json(raw_schedule)
+      text = raw_schedule.to_s.strip
+      return text unless text.start_with?("```")
+
+      fenced = text.match(/```(?:json)?\s*(.*?)\s*```/m)
+      fenced ? fenced[1].to_s.strip : text
+    end
+
+    def self.validate!(schedule)
+      raise Error, "schedule must be a JSON object" unless schedule.is_a?(Hash)
+
+      days = schedule.fetch("days")
+      raise Error, "schedule must contain days" unless days.is_a?(Array) && !days.empty?
+
+      expected_length = schedule["program_length_days"] || days.length
+      raise Error, "program_length_days must match days length" unless expected_length.to_i == days.length
+
+      days.each_with_index do |day, index|
+        validate_day!(day, index + 1)
+      end
+    rescue KeyError => e
+      raise Error, "missing required schedule field: #{e.key}"
+    end
+
+    def self.validate_day!(day, expected_day_number)
+      raise Error, "each day must be an object" unless day.is_a?(Hash)
+      raise Error, "day_number must be sequential" unless day.fetch("day_number").to_i == expected_day_number
+      raise Error, "day_type must be workout or rest" unless %w[workout rest].include?(day.fetch("day_type"))
+      raise Error, "notes must be present" unless day.key?("notes")
+
+      if day["day_type"] == "workout"
+        workout = day.fetch("workout")
+        raise Error, "workout must be present for workout days" unless workout.is_a?(Hash)
+
+        %w[title catalog_path domain session_duration].each do |field|
+          raise Error, "workout must include #{field}" unless workout[field].is_a?(String) && !workout[field].empty?
+        end
+      end
+    rescue KeyError => e
+      raise Error, "missing required day field: #{e.key}"
+    end
+  end
+end

data/lib/coach_zed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class CoachZed
+  VERSION = "0.4.1"
+end

data/lib/coach_zed.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require "json"
+require "pathname"
+require "yaml"
+
+require_relative "coach_zed/version"
+require_relative "coach_zed/catalog"
+require_relative "coach_zed/clients/ruby_openai"
+require_relative "coach_zed/feed_reader"
+require_relative "coach_zed/feed_writer"
+require_relative "coach_zed/prompt_builder"
+require_relative "coach_zed/schedule_parser"
+
+class CoachZed
+  Result = Data.define(:schedule_path, :ics_path, :webcal_path, :schedule)
+
+  class Config
+    attr_accessor :workout_catalog_dir, :model, :output_dir, :feed_output_basename, :existing_feed_path
+
+    def initialize(
+      workout_catalog_dir: nil,
+      model: nil,
+      output_dir: nil,
+      feed_output_basename: nil,
+      existing_feed_path: nil
+    )
+      @workout_catalog_dir = workout_catalog_dir
+      @model = model
+      @output_dir = output_dir
+      @feed_output_basename = feed_output_basename
+      @existing_feed_path = existing_feed_path
+    end
+
+    def apply(hash)
+      hash.each do |key, value|
+        public_send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+  end
+
+  class << self
+    def config
+      @config ||= default_config
+      load_config_file
+      @config
+    end
+
+    def configure
+      load_config_file
+      yield config
+    end
+
+    def load_config_file
+      return if @config_file_loaded
+
+      @config ||= default_config
+
+      config_file_paths.each do |path|
+        next unless File.exist?(path)
+
+        parsed = YAML.load_file(path)
+        next unless parsed.is_a?(Hash)
+
+        @config.apply(parsed.transform_keys(&:to_sym))
+        @config_file_loaded = true
+        return path
+      end
+
+      @config_file_loaded = true
+      nil
+    end
+
+    def reset_config!
+      @config = nil
+      @config_file_loaded = false
+    end
+
+    def default_config
+      Config.new(
+        model: "gpt-4.1",
+        output_dir: "results"
+      )
+    end
+
+    def config_file_paths
+      [".coach_zed.yml", File.expand_path("~/.config/coach_zed.yml")]
+    end
+  end
+
+  def initialize(
+    client:,
+    workout_catalog_dir: nil,
+    model: nil,
+    output_dir: nil,
+    feed_output_basename: nil,
+    existing_feed_path: nil
+  )
+    config = self.class.config
+
+    @workout_catalog_dir = Pathname(workout_catalog_dir || config.workout_catalog_dir || raise(ArgumentError, "workout_catalog_dir is required"))
+    model_name = model || config.model || "gpt-4.1"
+    @ai_client = wrap_client(client, model: model_name)
+    @output_dir = Pathname(output_dir || config.output_dir || "results")
+    @schedule_output_dir = @output_dir.join("schedules")
+    @feed_output_dir = @output_dir.join("feeds")
+    @feed_output_basename = feed_output_basename.nil? ? config.feed_output_basename : feed_output_basename
+    resolved_existing_feed_path = existing_feed_path.nil? ? config.existing_feed_path : existing_feed_path
+    @existing_feed_path = resolved_existing_feed_path && Pathname(resolved_existing_feed_path)
+  end
+
+  def generate_schedule(start_date:, consultation_prompt: nil, consultation_prompt_path: nil)
+    prompt_text = resolve_prompt_text(consultation_prompt, consultation_prompt_path)
+    catalog = Catalog::Loader.new(@workout_catalog_dir).load
+    existing_feed = load_existing_feed
+    start_date = generation_start_date(start_date, existing_feed:)
+    generation_days = existing_feed ? 7 : 28
+    existing_feed_context = existing_feed&.to_context(limit_days: 28)
+    schedule_key = schedule_key_for(prompt_text, start_date, catalog, generation_days, existing_feed_context)
+    prompt = PromptBuilder.new(
+      consultation_prompt: prompt_text,
+      catalog: catalog,
+      start_date: start_date,
+      schedule_key: schedule_key,
+      generation_days: generation_days,
+      existing_feed_context: existing_feed_context
+    ).build
+    raw_schedule = @ai_client.generate(prompt:)
+    schedule = ScheduleParser.parse(raw_schedule)
+    schedule = normalize_schedule(schedule, start_date:, prompt_text:, schedule_key:, catalog:, generation_days:)
+
+    schedule_path = write_schedule(schedule, schedule_key)
+    feed_paths = write_feeds(schedule, start_date:, schedule_key:, existing_feed:)
+
+    Result.new(
+      schedule_path: schedule_path,
+      ics_path: feed_paths.fetch(:ics),
+      webcal_path: feed_paths.fetch(:webcal),
+      schedule: schedule
+    )
+  end
+
+  private
+
+  attr_reader :workout_catalog_dir, :ai_client, :output_dir, :schedule_output_dir, :feed_output_dir, :feed_output_basename, :existing_feed_path
+
+  def wrap_client(client, model:)
+    return client if client.is_a?(Clients::RubyOpenAI)
+
+    client_name = client.class.name
+    if client_name == "OpenAI::Client"
+      return Clients::RubyOpenAI.new(client:, model:)
+    end
+
+    raise ArgumentError, "unsupported client: #{client_name || client.class}"
+  end
+
+  def resolve_prompt_text(consultation_prompt, consultation_prompt_path)
+    if consultation_prompt && consultation_prompt_path
+      raise ArgumentError, "provide either consultation_prompt or consultation_prompt_path, not both"
+    end
+
+    if consultation_prompt.nil? && consultation_prompt_path.nil?
+      raise ArgumentError, "provide consultation_prompt or consultation_prompt_path"
+    end
+
+    return consultation_prompt if consultation_prompt
+
+    Pathname(consultation_prompt_path.to_s).read
+  end
+
+  def normalize_date(value)
+    case value
+    when Date
+      value
+    when Time, DateTime
+      value.to_date
+    else
+      Date.parse(value.to_s)
+    end
+  end
+
+  def load_existing_feed
+    return nil if existing_feed_path.nil?
+    return nil unless existing_feed_path.exist?
+
+    FeedReader.load_existing(existing_feed_path)
+  end
+
+  def generation_start_date(start_date, existing_feed:)
+    last_date = existing_feed&.last_date
+    return normalize_date(start_date) if last_date.nil?
+
+    last_date + 1
+  end
+
+  def schedule_key_for(prompt_text, start_date, catalog, generation_days, existing_feed_context)
+    Digest::SHA256.hexdigest(
+      [
+        prompt_text.strip,
+        start_date.iso8601,
+        generation_days,
+        catalog_digest(catalog),
+        existing_feed_context.to_s
+      ].join("\n")
+    )[0...12] || ""
+  end
+
+  def catalog_digest(catalog)
+    Digest::SHA256.hexdigest(catalog.map(&:fingerprint).join("\n"))
+  end
+
+  def normalize_schedule(schedule, start_date:, prompt_text:, schedule_key:, catalog:, generation_days:)
+    days = schedule.fetch("days")
+    normalized_days = days.each_with_index.map do |day, index|
+      day_number = day.fetch("day_number", index + 1).to_i
+      date = start_date + (day_number - 1)
+      workout = day["workout"]
+      {
+        "day_number" => day_number,
+        "date" => date.iso8601,
+        "day_type" => day.fetch("day_type"),
+        "workout" => workout&.transform_keys(&:to_s),
+        "notes" => day["notes"].to_s
+      }
+    end
+
+    schedule.merge(
+      "schema_version" => 1,
+      "schedule_id" => schedule_key,
+      "start_date" => start_date.iso8601,
+      "consultation_prompt" => prompt_text,
+      "catalog_directory" => workout_catalog_dir.to_s,
+      "catalog_count" => catalog.count,
+      "program_length_days" => schedule.fetch("program_length_days", generation_days).to_i,
+      "days" => normalized_days
+    )
+  end
+
+  def write_schedule(schedule, schedule_key)
+    schedule_output_dir.mkpath
+    path = schedule_output_dir.join(schedule_filename(schedule_key))
+    path.write(JSON.pretty_generate(schedule) + "\n")
+    path
+  end
+
+  def write_feeds(schedule, start_date:, schedule_key:, existing_feed:)
+    feed_output_dir.mkpath
+    base_path = feed_output_dir.join(feed_basename(schedule_key))
+    feed = FeedWriter.new(
+      schedule:,
+      start_date:,
+      existing_feed_content: existing_feed&.feed_content
+    ).build
+    ics_path = base_path.sub_ext(".ics")
+    webcal_path = base_path.sub_ext(".webcal")
+    ics_path.write(feed)
+    webcal_path.write(feed)
+    {ics: ics_path, webcal: webcal_path}
+  end
+
+  def schedule_filename(schedule_key)
+    "schedule-#{schedule_key}.json"
+  end
+
+  def feed_basename(schedule_key)
+    feed_output_basename || "schedule-#{schedule_key}"
+  end
+end

data/sig/coach_zed.rbs

@@ -0,0 +1,238 @@
+class CoachZed
+  VERSION: String
+
+  class Result
+    attr_reader schedule_path: Pathname
+    attr_reader ics_path: Pathname
+    attr_reader webcal_path: Pathname
+    attr_reader schedule: Hash[String, untyped]
+
+    def initialize: (
+      schedule_path: Pathname,
+      ics_path: Pathname,
+      webcal_path: Pathname,
+      schedule: Hash[String, untyped]
+    ) -> void
+  end
+
+  class Config
+    attr_accessor workout_catalog_dir: String?
+    attr_accessor model: String?
+    attr_accessor output_dir: String?
+    attr_accessor feed_output_basename: String?
+    attr_accessor existing_feed_path: String?
+
+    def initialize: (
+      ?workout_catalog_dir: String?,
+      ?model: String?,
+      ?output_dir: String?,
+      ?feed_output_basename: String?,
+      ?existing_feed_path: String?
+    ) -> void
+
+    def apply: (Hash[untyped, untyped]) -> void
+  end
+
+  def self.config: -> Config
+  def self.configure: { (Config) -> untyped } -> untyped
+  def self.load_config_file: -> String?
+  def self.reset_config!: -> void
+  def self.default_config: -> Config
+  def self.config_file_paths: -> Array[String]
+
+  attr_reader workout_catalog_dir: Pathname
+  attr_reader ai_client: untyped
+  attr_reader output_dir: Pathname
+  attr_reader schedule_output_dir: Pathname
+  attr_reader feed_output_dir: Pathname
+  attr_reader feed_output_basename: String?
+  attr_reader existing_feed_path: Pathname?
+
+  def initialize: (
+    client: untyped,
+    ?workout_catalog_dir: String?,
+    ?model: String?,
+    ?output_dir: String?,
+    ?feed_output_basename: String?,
+    ?existing_feed_path: String?
+  ) -> void
+
+  def generate_schedule: (
+    start_date: untyped,
+    ?consultation_prompt: String?,
+    ?consultation_prompt_path: String?
+  ) -> Result
+
+  private
+
+  def wrap_client: (untyped client, model: String) -> untyped
+  def resolve_prompt_text: (String? consultation_prompt, String? consultation_prompt_path) -> String
+  def normalize_date: (untyped value) -> Date
+  def load_existing_feed: -> CoachZed::FeedReader?
+  def generation_start_date: (untyped start_date, existing_feed: CoachZed::FeedReader?) -> Date
+  def schedule_key_for: (String prompt_text, Date start_date, Array[CoachZed::Catalog::Entry] catalog, Integer generation_days, String? existing_feed_context) -> String
+  def catalog_digest: (Array[CoachZed::Catalog::Entry] catalog) -> String
+  def normalize_schedule: (Hash[String, untyped] schedule, start_date: Date, prompt_text: String, schedule_key: String, catalog: Array[CoachZed::Catalog::Entry], generation_days: Integer) -> Hash[String, untyped]
+  def write_schedule: (Hash[String, untyped] schedule, String schedule_key) -> Pathname
+  def write_feeds: (Hash[String, untyped] schedule, start_date: Date, schedule_key: String, existing_feed: CoachZed::FeedReader?) -> Hash[Symbol, Pathname]
+  def schedule_filename: (String schedule_key) -> String
+  def feed_basename: (String schedule_key) -> String
+
+  module Catalog
+    class Entry
+      attr_reader path: Pathname
+      attr_reader relative_path: String
+      attr_reader title: String
+      attr_reader domain: String?
+      attr_reader session_duration: String?
+      attr_reader frequency: String?
+      attr_reader program: String?
+      attr_reader format: String?
+      attr_reader equipment: String?
+      attr_reader summary: String
+      attr_reader work_items: Array[String]
+      attr_reader notes: Array[String]
+      attr_reader source_urls: Array[String]
+
+      def initialize: (
+        path: Pathname,
+        relative_path: String,
+        title: String,
+        ?domain: String?,
+        ?session_duration: String?,
+        ?frequency: String?,
+        ?program: String?,
+        ?format: String?,
+        ?equipment: String?,
+        summary: String,
+        work_items: Array[String],
+        notes: Array[String],
+        source_urls: Array[String]
+      ) -> void
+
+      def fingerprint: -> String
+      def to_h: -> Hash[String, untyped]
+    end
+
+    class Loader
+      IGNORED_BASENAMES: Array[String]
+
+      attr_reader root: Pathname
+
+      def initialize: (Pathname | String) -> void
+      def load: -> Array[Entry]
+
+      private
+
+      def ignored?: (Pathname path) -> bool
+      def parse_entry: (Pathname path) -> Entry?
+      def parse_sections: (Array[String] lines) -> Hash[untyped, Array[String]]
+      def normalize_section_name: (String name) -> String
+      def normalize_key: (String key) -> String
+      def strip_ticks: (String? value) -> String
+      def normalize_bullets: (Array[String] lines) -> Array[String]
+      def normalize_urls: (Array[String] lines) -> Array[String]
+    end
+  end
+
+  module Clients
+    class RubyOpenAI
+      attr_reader client: untyped
+      attr_reader model: String
+
+      def initialize: (client: untyped, ?model: String) -> void
+      def generate: (prompt: String) -> String
+
+      private
+
+      def extract_content: (untyped response) -> String
+    end
+  end
+
+  class FeedReader
+    class Event
+      attr_reader date: Date?
+      attr_reader summary: String?
+      attr_reader description: String?
+
+      def initialize: (
+        ?date: Date?,
+        ?summary: String?,
+        ?description: String?
+      ) -> void
+    end
+
+    def self.load: (Pathname | String) -> Array[Event]
+    def self.load_existing: (Pathname | String) -> FeedReader
+
+    def initialize: (String) -> void
+    attr_reader feed_content: String
+    def events: -> Array[Event]
+    def last_date: -> Date?
+    def recent_events: (?limit_days: Integer) -> Array[Event]
+    def to_context: (?limit_days: Integer) -> String
+
+    private
+
+    def parse_events: -> Array[Event]
+    def parse_date: (String event_text) -> Date?
+    def parse_line: (String event_text, Regexp pattern) -> String?
+    def unescape: (String? value) -> String
+  end
+
+  class FeedWriter
+    attr_reader schedule: Hash[String, untyped]
+    attr_reader start_date: Date
+    attr_reader existing_feed_content: String?
+
+    def initialize: (
+      schedule: Hash[String, untyped],
+      start_date: Date,
+      ?existing_feed_content: String?
+    ) -> void
+
+    def build: -> String
+
+    private
+
+    def fresh_feed: -> String
+    def append_to_existing_feed: (String existing_feed) -> String
+    def header_lines: -> Array[String]
+    def event_lines: -> Array[String]
+    def schedule_name: -> String
+    def generated_timestamp: -> String
+    def event_summary: (Hash[String, untyped] day) -> String
+    def event_description: (Hash[String, untyped] day) -> String
+    def escape: (untyped value) -> String
+  end
+
+  class PromptBuilder
+    attr_reader consultation_prompt: String
+    attr_reader catalog: Array[Catalog::Entry]
+    attr_reader start_date: Date
+    attr_reader schedule_key: String
+    attr_reader generation_days: Integer
+    attr_reader existing_feed_context: String?
+
+    def initialize: (
+      consultation_prompt: String,
+      catalog: Array[Catalog::Entry],
+      start_date: Date,
+      schedule_key: String,
+      generation_days: Integer,
+      ?existing_feed_context: String?
+    ) -> void
+
+    def build: -> String
+  end
+
+  class ScheduleParser
+    class Error < StandardError
+    end
+
+    def self.parse: (String) -> Hash[String, untyped]
+    def self.extract_json: (String raw_schedule) -> String
+    def self.validate!: (Hash[String, untyped] schedule) -> void
+    def self.validate_day!: (Hash[String, untyped] day, Integer expected_day_number) -> void
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: coach_zed
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- Ross Kaffenberger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: CoachZed reads a workout catalog, asks an AI client for a daily training
+  plan, and writes schedule JSON plus calendar feeds.
+email:
+- rosskaff@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/coach_zed.rb
+- lib/coach_zed/catalog.rb
+- lib/coach_zed/clients/ruby_openai.rb
+- lib/coach_zed/feed_reader.rb
+- lib/coach_zed/feed_writer.rb
+- lib/coach_zed/prompt_builder.rb
+- lib/coach_zed/schedule_parser.rb
+- lib/coach_zed/version.rb
+- sig/coach_zed.rbs
+homepage: https://example.com/coach_zed
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://example.com/coach_zed
+  source_code_uri: https://example.com/coach_zed/source
+  changelog_uri: https://example.com/coach_zed/changelog
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Generate fitness schedules from a workout catalog.
+test_files: []