question_kit 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37b2cc86be99b7513693957fd7e67cd9f19209c47ab31678836acfc0a8332661
-  data.tar.gz: 882bc674404e1cf01084da328595a14a0deff0096c96a775648ba97e54960d7a
+  metadata.gz: c5639e96431bb3c4754d3655dee3b8805ff685db6946f720688708a3dea83768
+  data.tar.gz: 54d2beff617fcab5f988fe30fdef1680db0e68e9750be6de1455bc158639c9a6
 SHA512:
-  metadata.gz: f51ba58ee9eafbeaa9faa1539f617c5bbddb09bf0248a35462537323f5fda0131968c725ec4f867de5f671ee472443067dce5b3ac2b4085cc6f076ee6dd69a46
-  data.tar.gz: c7be35b2bbe19282322aa576353a6a7ee50f3f1479b42e787e1688f3884d220d01812a2bec116446bc655262346642bb4236c910dd39da2826a1666b9f9eab83
+  metadata.gz: 37c3a74f4a42956916a4d8fd9cdeedb62c7e77405cee84b280aca71b097a11505d89f486485a83da333c41719bb94d7c04a60abc7439b4b679b2e9bc2d58a5f4
+  data.tar.gz: 2a8adaeeba7b2db1bdbbd9e63683bf33e8e74c9e8b0c2b57cb3c51f9446edcadfb3465a926ce5e24570bc7a309a085eb91090228623454972cd12b935533744e

data/lib/question_kit/answer_explanations.rb

@@ -0,0 +1,25 @@
+module QuestionKit
+  module AnswerExplanations
+    TEXT = {
+      "question" => {
+        "answers.info" => "Extra detail saved with this answer, which the question page does not show to a player.",
+        "answers.hint" => "A smaller line a player sees under this answer's text.",
+        "answers.label" => "The text a player sees for this answer in place of its value.",
+        "answers.value" => "The text saved when a player picks this answer, which the player also sees when the label is blank or the flow shows answer values.",
+        "answers.weight" => "The points a player scores by picking this answer, and any weight above zero makes it a right answer."
+      },
+      "multiple_select" => {
+        "answers.label" => "The text a player sees for this answer in place of its value.",
+        "answers.value" => "The text saved when a player ticks this answer, which the player also sees when the label is blank.",
+        "answers.weight" => "Any weight above zero makes this a right answer, whatever its size, and the question scores one point only when a player ticks every right answer and no others."
+      },
+      "fill_in_the_blank" => {
+        "accepted_answers.value" => "A typed answer that matches this text, ignoring capitals and the spaces around it, is right and scores one point."
+      }
+    }.freeze
+
+    def explanation_for(step_type, setting)
+      super || TEXT.dig(step_type.to_s, setting.to_s)
+    end
+  end
+end

data/lib/question_kit/answer_key.rb

@@ -0,0 +1,15 @@
+module QuestionKit
+  module AnswerKey
+    def self.chosen(step)
+      case step["type"]
+      when "multiple_select" then Score.right_answers(step)
+      when "fill_in_the_blank" then Array(step["accepted_answers"]).first&.fetch("value", nil)
+      else Score.right_answers(step).first
+      end
+    end
+
+    def self.accepted(step)
+      Array(step["accepted_answers"]).filter_map { |answer| answer["value"].presence }
+    end
+  end
+end

data/lib/question_kit/question_importer.rb

@@ -0,0 +1,18 @@
+module QuestionKit
+  class QuestionImporter < Ixport::Importer
+    field :type, label: "Type"
+    field :question, label: "Question"
+    field :category, label: "Category"
+    UploadedQuestion::ANSWER_FIELDS.each.with_index(1) { |key, number| field key, label: "Answer #{number}" }
+    field :right_answer, label: "Right answer"
+
+    def records
+      UploadedQuestions.new(target)
+    end
+
+    def self.allows?(account, quiz)
+      host = EasyFlow.host_named(QuestionKit.flow_host)
+      quiz.is_a?(EasyFlow::Definition) && quiz.host == QuestionKit.flow_host.to_s && (host.owner_method.nil? || quiz.owner == account)
+    end
+  end
+end

data/lib/question_kit/railtie.rb

@@ -1,4 +1,11 @@
 module QuestionKit
   class Railtie < ::Rails::Railtie
+    initializer "question_kit.answer_explanations" do |app|
+      app.config.to_prepare { QuestionKit.explain_answer_fields }
+    end
+
+    initializer "question_kit.question_importer" do |app|
+      app.config.to_prepare { require "question_kit/question_importer" if defined?(Ixport::Importer) }
+    end
   end
 end

data/lib/question_kit/score.rb

@@ -0,0 +1,32 @@
+module QuestionKit
+  module Score
+    def self.total(answers, steps)
+      answers.sum { |id, value| worth(steps[id.to_s].to_h, value) }
+    end
+
+    def self.worth(step, value)
+      return picked_worth(step, value) if step["type"] == "multiple_select"
+      return typed_worth(step, value) if step["type"] == "fill_in_the_blank"
+
+      chosen = EasyFlow::Steps::Question.answers_of(step).find { |answer| answer.is_a?(Hash) && answer["value"] == value }
+
+      chosen&.fetch("weight", nil).to_i
+    end
+
+    def self.typed_worth(step, text)
+      Array(step["accepted_answers"]).any? { |accepted| comparable(accepted["value"]) == comparable(text) } ? 1 : 0
+    end
+
+    def self.comparable(text)
+      text.to_s.strip.downcase
+    end
+
+    def self.picked_worth(step, values)
+      Array(values).sort == right_answers(step).sort ? 1 : 0
+    end
+
+    def self.right_answers(step)
+      EasyFlow::Steps::Question.answers_of(step).filter_map { |answer| answer["value"] if answer["weight"].to_i.positive? }
+    end
+  end
+end

data/lib/question_kit/time_taken.rb

@@ -0,0 +1,10 @@
+module QuestionKit
+  module TimeTaken
+    def self.seconds(run)
+      return unless run.flow.each_step?
+
+      last_answered = run.completed_at.values.max
+      (last_answered - run.created_at).to_i if last_answered
+    end
+  end
+end

data/lib/question_kit/titled_start.rb

@@ -0,0 +1,43 @@
+module QuestionKit
+  class TitledStart
+    FALLBACK_SLUG = "quiz"
+    MADE_SLUG_LENGTH = 100
+    TRIES_FOR_A_FREE_SLUG = 3
+    SLUGS_THE_ROUTES_USE = %w[manage pages runs].freeze
+
+    def initialize(flow)
+      @flow = flow
+    end
+
+    def save
+      return refuse_blank_title if @flow.title.blank?
+
+      tries = 0
+      begin
+        @flow.slug = free_slug
+        @flow.save
+      rescue ActiveRecord::RecordNotUnique
+        retry if (tries += 1) < TRIES_FOR_A_FREE_SLUG
+        raise
+      end
+    end
+
+    private
+      def refuse_blank_title
+        @flow.errors.add(:title, :blank)
+        false
+      end
+
+      def free_slug
+        made = @flow.title.parameterize.first(MADE_SLUG_LENGTH).chomp("-").presence || FALLBACK_SLUG
+        numbered = (2..).lazy.map { |number| "#{made}-#{number}" }
+        taken = unavailable
+
+        [ made ].chain(numbered).find { |candidate| taken.exclude?(candidate) }
+      end
+
+      def unavailable
+        EasyFlow::Definition.where(host: @flow.host, owner: @flow.owner).pluck(:slug) + SLUGS_THE_ROUTES_USE
+      end
+  end
+end

data/lib/question_kit/uploaded_question.rb

@@ -0,0 +1,84 @@
+module QuestionKit
+  class UploadedQuestion
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attr_accessor :flow
+
+    attribute :type, :string
+    attribute :question, :string
+    attribute :category, :string
+    attribute :right_answer, :string
+    ANSWER_FIELDS = (1..6).map { |number| :"answer_#{number}" }
+    ANSWER_FIELDS.each { |field| attribute field, :string }
+
+    KINDS = %w[truefalse multiplechoice].freeze
+
+    validates :question, presence: true
+    validate :kind_is_offered
+    validate :choices_are_offered, if: -> { kind == "multiplechoice" }
+    validate :true_or_false_is_right, if: -> { kind == "truefalse" }
+
+    def save!
+      before = document.to_h
+      flow.edit_history.record(appended, :added, [ step["id"] ], before)
+    end
+
+    private
+      def choices_are_offered
+        errors.add(:answers, "must be at least two for a multiple choice question") if filled_answers.size < 2
+        errors.add(:right_answer, "must be the number of one of its answers") if answers.none? { |answer| answer["weight"] == 1 }
+      end
+
+      def true_or_false_is_right
+        errors.add(:right_answer, "must be true or false") if answers.none? { |answer| answer["weight"] == 1 }
+      end
+
+      def kind_is_offered
+        errors.add(:type, "must be true/false or multiple choice") unless KINDS.include?(kind)
+      end
+
+      def document
+        EasyFlow::Document.new(flow.document || flow.definition || {})
+      end
+
+      def appended
+        leaving = document.edges_from(last_question).first
+        return document.insert(step, on: [ last_question, leaving.to ]) if leaving
+
+        document.add(step).connect(from: last_question, to: step["id"])
+      end
+
+      def last_question
+        reached = document.reachable
+        reached.reverse.find { |id| document.node(id)&.type == "question" } || reached.last
+      end
+
+      def step
+        @step ||= { "id" => next_id, "type" => "question", "question" => question, "category" => category.presence, "answers" => answers }.compact
+      end
+
+      def answers
+        return true_false_answers if kind == "truefalse"
+
+        filled_answers.map { |number, text| { "value" => text, "weight" => number.to_s == right_answer.to_s.strip ? 1 : 0 } }
+      end
+
+      def true_false_answers
+        %w[True False].map { |text| { "value" => text, "weight" => text.casecmp?(right_answer.to_s.strip) ? 1 : 0 } }
+      end
+
+      def kind
+        type.to_s.downcase.gsub(/[^a-z]/, "")
+      end
+
+      def filled_answers
+        ANSWER_FIELDS.each_with_index.filter_map { |field, index| [ index + 1, public_send(field).strip ] if public_send(field).present? }
+      end
+
+      def next_id
+        taken = document.nodes.map(&:id)
+        (1..).lazy.map { |number| "question_#{number}" }.find { |id| !taken.include?(id) }
+      end
+  end
+end

data/lib/question_kit/uploaded_questions.rb

@@ -0,0 +1,15 @@
+module QuestionKit
+  class UploadedQuestions
+    def initialize(flow)
+      @flow = flow
+    end
+
+    def new(values)
+      UploadedQuestion.new(values.merge(flow: @flow))
+    end
+
+    def where(*)
+      []
+    end
+  end
+end

data/lib/question_kit/version.rb

@@ -1,3 +1,3 @@
 module QuestionKit
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/question_kit.rb

@@ -1,7 +1,25 @@
 require "easy_flow"
 require "question_kit/version"
 require "question_kit/railtie"
+require "question_kit/score"
+require "question_kit/answer_key"
+require "question_kit/time_taken"
+require "question_kit/titled_start"
+require "question_kit/uploaded_question"
+require "question_kit/uploaded_questions"
+require "question_kit/answer_explanations"
 
 module QuestionKit
-  # Your code goes here...
+  class << self
+    attr_reader :flow_host
+
+    def flow_host=(name)
+      @flow_host = name
+      explain_answer_fields
+    end
+
+    def explain_answer_fields
+      EasyFlow.host_named(flow_host).extend(AnswerExplanations) if flow_host
+    end
+  end
 end

data/the_local/agents/question_kit-develop.md

@@ -1,50 +1,180 @@
 ---
 name: question_kit-develop
-description: Use PROACTIVELY for reading which question_kit version a host app has loaded, and for checking that version before code relies on a question_kit release — MUST BE USED instead of reading Gem.loaded_specs, parsing Gemfile.lock, or comparing version strings by hand.
+description: Use PROACTIVELY for scoring an easy_flow quiz — working out what one answer to a question, multiple-select or fill-in-the-blank step is worth, adding up a run's total score, listing a question's right answers, showing a question's answer key or every accepted spelling of a fill-in-the-blank answer, timing how long a visitor took over a quiz run — and for building quizzes — starting a new quiz from its title with a free address slug, finding which easy_flow host runs the quizzes, letting a builder upload a CSV file of true/false and multiple choice questions into a quiz through ixport, limiting that upload to the builder's own quizzes, adding one uploaded question to a quiz, reading or replacing the explanations an admin sees beside a question's answer settings, and reading which question_kit version is loaded — MUST BE USED instead of summing answer weights by hand, comparing typed answers to accepted answers in host code, picking out right answers from a step's answer list, subtracting run timestamps, making a quiz slug from its title, writing a CSV question importer or a loop that adds question steps to a flow, or writing a permission check for uploading into a quiz.
 tools: Bash, Read, Write, Edit, Grep
 scope: shared question and answer rules for easy_flow quizzes — what an answer to a question step is worth, which answers are right, and how a quiz is built
 ---
 
-This local writes host app code against question_kit's declared interface only, and follows these steps exactly.
+This local writes host app code that scores, keys, times and builds easy_flow quizzes through question_kit's declared interface only, and follows the steps below in order.
 
 ## What question_kit is
 
-A Rails gem for apps that run quizzes as easy_flow flows, meant to hold the rules those apps share: what an answer to a question step is worth, which answers are right, and how a quiz is built. Today its only code-facing interface is its version constant. Use this local when host app code needs to know which question_kit release is loaded. Building the quiz flow, its question steps, runs and answers belongs to the easy_flow locals.
+A Rails gem for apps that run quizzes as easy_flow flows on one easy_flow host, the flow host. It holds the rules those apps share: what an answer to a question step is worth, which answers are right, how long a visitor took, how a new quiz gets its slug, how a CSV file of questions becomes question steps, and the explanations an admin sees beside a question's answer settings. The scoring, key and timing methods take plain step hashes and answer values, or an easy_flow run, and write nothing. Use this local whenever host code needs a score, an answer key, a time taken, a new quiz, or a question upload. Flows, step types, runs and answers in general belong to the easy_flow locals, and ixport's own pages and configuration belong to the ixport locals.
 
 ## Interface
 
-- `QuestionKit::VERSION` — a string such as `"0.1.0"` naming the question_kit release loaded in the host app.
+- `QuestionKit::VERSION` — a string such as `"0.2.0"` naming the question_kit release loaded in the host app.
+- `QuestionKit::Score.worth(step, value)` — returns the integer one answer `value` to the step hash `step` is worth.
+- `QuestionKit::Score.total(answers, steps)` — returns the integer sum of the worth of every answer in a run.
+- `QuestionKit::Score.right_answers(step)` — returns the list of answer values on a choice step that carry a positive weight.
+- `QuestionKit::AnswerKey.chosen(step)` — returns the answer key to show for a step: one value, a list of values, or `nil`.
+- `QuestionKit::AnswerKey.accepted(step)` — returns every non-blank accepted answer on a fill-in-the-blank step.
+- `QuestionKit::TimeTaken.seconds(run)` — returns the whole seconds from a run's start to its last answer, or `nil`.
+- `QuestionKit.flow_host` — returns the name of the easy_flow host that runs the app's quizzes, exactly as the install set it, or `nil` when none is set.
+- `QuestionKit::TitledStart.new(flow).save` — gives an unsaved quiz a slug made from its title and saves it, returning `true` or `false`.
+- `QuestionKit::UploadedQuestion` — one row of a question upload: validates it and, once valid, adds it to the quiz as a question step.
+- `QuestionKit::UploadedQuestion::ANSWER_FIELDS` — the six answer field names, `:answer_1` to `:answer_6`, a row may fill.
+- `QuestionKit::UploadedQuestions.new(flow)` — the set of uploaded rows for one quiz, which builds an `UploadedQuestion` bound to that quiz from a row's values.
+- `QuestionKit::QuestionImporter` — the ixport importer class that turns each row of a CSV file into a question step in the quiz the upload targets.
+- `QuestionKit::QuestionImporter.allows?(account, quiz)` — returns whether `account` may upload questions into `quiz`.
+- `QuestionKit::AnswerExplanations` — the explanations question_kit adds to the flow host's answer settings, which an admin sees beside each field.
+- `QuestionKit::AnswerExplanations::TEXT` — a frozen hash from step type to setting to the explanation text question_kit shows.
+
+## The step hash
+
+Every scoring, key and timing method that takes a `step` takes the step's settings as a hash with string keys, as easy_flow stores them in a flow's document. Pass the hash, not a record.
+
+- `"type"` decides how it is read: `"multiple_select"`, `"fill_in_the_blank"`, or any other value (or none) for a single-choice question.
+- A choice step lists its answers under `"answers"` or `"options"`, each a hash with a `"value"` and an optional `"weight"`. A weight may be an integer or a string of digits, and a missing weight counts as 0.
+- A fill-in-the-blank step lists its accepted answers under `"accepted_answers"`, each a hash with a `"value"`.
 
 ## How to use it
 
+### Before any of it
+
 1. Confirm question_kit is in the host app's `Gemfile.lock`. If it is not, hand the work to `question_kit-install` and stop.
-2. In the file that reads the version, require the gem explicitly at the top:
+2. At the top of the file that calls question_kit, require it explicitly:
 
    ```ruby
    require "question_kit"
    ```
 
    This also loads easy_flow, so no separate `require "easy_flow"` is needed.
-3. Read the version where it is needed:
+3. Confirm `QuestionKit.flow_host` returns a host name in the app, for example with `bin/rails runner 'p QuestionKit.flow_host'`. Starting a quiz, uploading questions and the answer explanations all depend on it. If it prints `nil`, hand the work to `question_kit-install` and stop.
 
-   ```ruby
-   QuestionKit::VERSION
-   ```
+### Scoring, keying and timing a run
 
-4. When code depends on a release, compare with `Gem::Version`, never with string comparison:
+4. Put the calls in host code that reads a finished or stored run, such as a results page's controller, a model method on the app's own quiz record, or a job that records a score. Ask the developer where the score is used and whether it is shown only or also stored; do not pick.
+5. Build the arguments from the flow version the run was taken on, not from the flow's live version, so a later edit does not change an old run's score:
+   - `steps` is a hash from step id (string) to that step's settings hash.
+   - `answers` is a hash from step id to the value the visitor gave. Ids may be strings or symbols.
+6. Score one answer with `QuestionKit::Score.worth(step, value)`:
+   - Single-choice: `value` is the chosen answer's value, matched exactly, including letter case, and the result is that answer's weight, or 0 when it carries none or matches no answer.
+   - Multiple-select: `value` is the list of ticked values, and the result is 1 when they are exactly the right answers in any order and 0 otherwise. Partial credit is not given.
+   - Fill-in-the-blank: `value` is the typed text, and the result is 1 when it matches an accepted answer after removing outer spaces and ignoring letter case, and 0 otherwise.
+7. Score a whole run with `QuestionKit::Score.total(answers, steps)`. An answer whose step id is not in `steps` counts 0, so steps that are not questions, such as info or branch steps, can be left in `answers` or taken out.
+8. Ask the developer whether a score of 0 for a single-choice question with no weights set is correct for their quizzes, or whether every quiz must set weights before it is published. question_kit cannot tell an unweighted question from a wrong answer.
+9. Show what was right:
+   - `QuestionKit::Score.right_answers(step)` for the full list of values with a positive weight on a choice step.
+   - `QuestionKit::AnswerKey.chosen(step)` for the single thing to display as the key: the list of right values for multiple-select, the first accepted answer for fill-in-the-blank, and the first right value for any other question. With no right or accepted answer it returns an empty list for multiple-select and `nil` for every other type, so render both cases.
+   - `QuestionKit::AnswerKey.accepted(step)` for every accepted spelling on a fill-in-the-blank step, with blank entries left out.
+10. Time a run with `QuestionKit::TimeTaken.seconds(run)`, passing the easy_flow run record. It returns `nil` when the run's flow saves answers only once the flow ends, and when no step has been completed yet; render both cases, for example as "not timed".
 
-   ```ruby
-   Gem::Version.new(QuestionKit::VERSION) >= Gem::Version.new("0.2.0")
-   ```
+### Starting a new quiz
+
+11. In the host app's action that creates a quiz, build an unsaved `EasyFlow::Definition` with the flow host, the owner and the title the builder typed, and save it through `TitledStart` instead of calling `save` on it:
+
+    ```ruby
+    quiz = EasyFlow::Definition.new(host: QuestionKit.flow_host.to_s, owner: current_owner, title: params[:title])
+
+    if QuestionKit::TitledStart.new(quiz).save
+      redirect_to ...
+    else
+      render :new, status: :unprocessable_entity
+    end
+    ```
+
+    `current_owner` stands for whatever record owns the host's flows; ask the developer which method returns it, or pass no owner when the host keeps none.
+12. Read the result:
+    - A blank title is refused: `save` returns `false` and `quiz.errors` holds a blank error on `:title`. Render the form with that error.
+    - Otherwise the quiz takes a slug made from its title, lower case with hyphens, at most 100 characters and never ending on a hyphen. A title with no usable letters or digits gets `quiz`.
+    - When the same host and owner already have that slug, or the slug is `manage`, `pages` or `runs`, the quiz takes the first free numbered slug, such as `morning-routine-2`.
+    - `save` then returns what saving the flow returns, so any other validation error on the flow comes back as `false` with its errors.
+    - When another quiz takes the same slug at the same moment, it tries the next free slug, and after three lost tries it raises `ActiveRecord::RecordNotUnique`. Ask the developer whether to let that error reach the error page or rescue it and show the form again.
+13. Never set `slug` yourself when using `TitledStart`; it replaces any slug already on the flow.
+
+### Uploading questions into a quiz
+
+`QuestionKit::QuestionImporter` is defined only when ixport is loaded in the app. In an app without ixport, it does not exist, and nothing in this section applies. If the developer asks for question uploads and ixport is missing, hand adding ixport to `ixport-install`.
+
+14. Register the upload with ixport in an initializer that runs after the ixport configuration, naming the importer by its string and limiting it with `allows?`:
+
+    ```ruby
+    Ixport.register_import :quiz_questions, title: "Quiz questions", importer: "QuestionKit::QuestionImporter", refuse_whole_file: true,
+      allow: ->(_person, account, quiz) { QuestionKit::QuestionImporter.allows?(account, quiz) }
+    ```
+
+    Ask the developer for the key and the title the builder sees. Ask whether one bad row refuses the whole file (`refuse_whole_file: true`) or only that row; refusing the whole file is the setting that keeps a quiz from gaining half a file of questions.
+15. `allows?(account, quiz)` returns `true` only when `quiz` is an easy_flow flow on the flow host and, when the flow host keeps owners, `quiz.owner` is `account`. A flow host with no owner method lets any account upload into any of its quizzes. ixport answers a refused upload page with not found.
+16. Link a builder to the upload page from the quiz's own page, passing the quiz as the target by its global id. Hand the link and ixport's pages to `ixport-develop`:
+
+    ```ruby
+    ixport.new_import_path(key: :quiz_questions, target: quiz.to_global_id)
+    ```
+
+17. Tell the developer what the file must hold, since the builder's columns are matched to these fields on ixport's column-matching page:
+    - `Type` — `True/false` or `Multiple choice`. Letter case, spaces, slashes and other non-letters are ignored, so `truefalse` and `multiple-choice` also match. Any other type refuses the row.
+    - `Question` — the question text. A blank question refuses the row.
+    - `Category` — optional; saved as the question's category when filled.
+    - `Answer 1` to `Answer 6` — the answers of a multiple choice question, of which at least two must be filled. A true/false question ignores them and always offers `True` and `False`.
+    - `Right answer` — for multiple choice, the number of the answer column that is right, such as `2` for `Answer 2`, counted by column even when an earlier column is blank; for true/false, `true` or `false` in any letter case. Outer spaces are ignored. A right answer that names no filled answer refuses the row.
+    - Each answer text is saved with its outer spaces removed, and the question text is saved as given.
+18. Each accepted row becomes a single-choice question step whose right answer has weight 1 and every other answer weight 0, so `Score.worth` scores it 1 or 0. Every row is added as a new question; an upload never matches or updates an existing question.
+19. Each question is added to the quiz's draft, after the last question a visitor can reach and before whatever step followed it, and is recorded in the quiz's edit history as an added step. Visitors are asked the uploaded questions only once the quiz is published. Tell the developer that the builder must publish after uploading.
+
+### Adding one question outside an upload
+
+20. To add a single question from host code in the same way an upload row does, build it through `UploadedQuestions` and check it before saving, since `save!` does not validate:
+
+    ```ruby
+    question = QuestionKit::UploadedQuestions.new(quiz).new(type: "Multiple choice", question: "Which planet is largest?", category: "Space",
+                                                            answer_1: "Mars", answer_2: "Jupiter", right_answer: "2")
+
+    if question.valid?
+      question.save!
+    else
+      question.errors.full_messages
+    end
+    ```
+
+    The accepted keys are `type`, `question`, `category`, `right_answer` and each name in `QuestionKit::UploadedQuestion::ANSWER_FIELDS`. The rules in step 17 and the placement in step 19 apply. A refused question carries its errors on `:question`, `:type`, `:answers` or `:right_answer`. Build the answer keys from `ANSWER_FIELDS` rather than typing `answer_1` to `answer_6`.
+
+### Answer explanations
+
+21. question_kit adds its explanations to the flow host's answer settings by itself once the install sets the flow host, so an admin sees them beside each answer field on the canvas. Write no code to turn them on.
+22. They cover the `question` step's answer value, label, hint, info and weight, the `multiple_select` step's answer value, label and weight, and the `fill_in_the_blank` step's accepted answer value. Read the exact text from `QuestionKit::AnswerExplanations::TEXT`, for example `QuestionKit::AnswerExplanations::TEXT["question"]["answers.weight"]`.
+23. To show different words for a field, set it in the flow host's own setting explanations, keyed by step type and then by the same setting name `TEXT` uses. The host app's text replaces question_kit's for that field only, and question_kit's text stays on every other field:
+
+    ```ruby
+    EasyFlow.host_named(QuestionKit.flow_host).setting_explanations = { question: { "answers.weight" => "Points for this answer." } }
+    ```
+
+    Ask the developer which fields to reword and the words to use. Other easy_flow hosts get none of question_kit's explanations.
+
+### Versions and tests
+
+24. When code depends on a release, compare versions with `Gem::Version`, never as strings:
+
+    ```ruby
+    Gem::Version.new(QuestionKit::VERSION) >= Gem::Version.new("0.2.0")
+    ```
 
-5. Ask the developer what the app does when the loaded version is older than the one its code needs: raise at boot, log a warning, or skip the feature. Do not pick one.
-6. If the check runs at boot, put it in an initializer under `config/initializers/` in the host app. Otherwise put it beside the code that depends on the release.
-7. Write a test in the host app that asserts the app's own behaviour for each branch of the check, and run it.
+    Ask the developer what the app does when the loaded version is older: raise at boot, log a warning, or skip the feature.
+25. Write host app tests that assert the app's own behaviour with the score, key, time, new quiz or upload, such as what the results page shows or that a builder cannot reach another owner's upload page, and run them. Do not test question_kit's own scoring, slug or row rules.
 
 ## Conventions
 
-- Never hard-code the version string in host app code. Read `QuestionKit::VERSION`.
-- Never assign to or redefine `QuestionKit::VERSION`.
-- question_kit has no scoring, right-answer or quiz-building methods yet. Do not invent calls for them. If the developer asks for that behaviour, say the gem does not offer it and ask whether to build it in the host app or wait for question_kit to add it.
-- Adding the gem, and upgrading it, belongs to `question_kit-install`.
-- Flows, step types, runs and answers belong to the easy_flow locals.
+- Never compute a score, a right answer or a time taken in host code. Call question_kit so every app scores the same way.
+- Never compare a typed answer to an accepted answer in host code; `Score.worth` already ignores case and outer spaces.
+- Never mutate the step hash passed in.
+- Never make a quiz slug in host code; save a new quiz through `TitledStart`.
+- Never write a question importer, a CSV parser for questions or a loop that adds question steps; register `QuestionKit::QuestionImporter` with ixport.
+- Always pass `allows?` as the upload's access rule, so a builder cannot upload into another owner's quiz or a flow on another host.
+- Never call `UploadedQuestion#save!` on a row that has not passed `valid?`.
+- Never edit `QuestionKit::AnswerExplanations::TEXT` or extend a host with `AnswerExplanations` yourself; reword a field through the host's setting explanations.
+- Compare `QuestionKit.flow_host` with a flow's host as a string, with `.to_s`.
+- Never hard-code or redefine `QuestionKit::VERSION`.
+- question_kit does not store scores, add step types, or upload multiple-select or fill-in-the-blank questions. If the developer asks for that, say so and ask whether to build it in the host app or wait for question_kit to add it.
+- Adding or upgrading the gem and setting the flow host belong to `question_kit-install`.
+- Flows, step types, runs, publishing and answers belong to the easy_flow locals.
+- Adding ixport and its pages, links and configuration belong to the ixport locals.

data/the_local/agents/question_kit-info.md

@@ -1,6 +1,6 @@
 ---
 name: question_kit-info
-description: Use to learn what question_kit offers — shared rules for easy_flow quizzes, covering what an answer to a question step is worth, which answers are right, and how a quiz is built.
+description: Use to learn what question_kit offers — shared rules for easy_flow quizzes, covering what an answer to a question step is worth, which answers are right, the answer key a quiz shows for each question, how long a visitor took on a quiz, starting a quiz from its title, adding questions to a quiz from an uploaded CSV file, and the explanations an admin sees beside a question's answer settings.
 tools: Read
 scope: shared question and answer rules for easy_flow quizzes — what an answer to a question step is worth, which answers are right, and how a quiz is built
 ---
@@ -10,40 +10,106 @@ This local explains question_kit and makes no changes.
 ## What question_kit is
 
 question_kit is a Rails gem for apps that run quizzes as easy_flow flows. Each
-quiz question is an easy_flow question step. The gem is meant to hold the rules
-those apps share: what an answer to a question step is worth, which answers are
-right, and how a quiz is built. With the rules in one gem, each app does not
-keep its own copy.
+quiz question is an easy_flow question step. The gem holds the rules those apps
+share, so each app does not keep its own copy of them.
 
-Today the gem holds none of those rules yet. It loads easy_flow into the host
-app and reports its own version, and nothing more. Reach for it when an app
-runs easy_flow quizzes and should follow the shared rules as they are added.
-Until then, it is only a dependency to put in place.
+Reach for it when an app runs easy_flow quizzes and needs to:
+
+- score a visitor's answer to one question, or add up a whole quiz;
+- say which answers to a question are right;
+- show the answer key for a question once the quiz is over;
+- report how long a visitor took to answer the quiz;
+- start a new quiz from the title an admin types;
+- add questions to a quiz from a CSV file an admin uploads;
+- explain to an admin, beside each answer setting on the canvas, what that
+  setting does to the score.
+
+It reads and writes the flows, steps and runs easy_flow already stores. It adds
+no tables and no step types of its own. The CSV upload uses ixport's import
+pages, and is only there in an app that has ixport.
 
 ## Interface
 
 This local documents no commands. The other two locals cover everything the
 gem exposes:
 
-- The install local, `question_kit-install`, adds the gem to a host app.
-- The develop local, `question_kit-develop`, covers the code a host app writes against the gem.
+- The install local, `question_kit-install`, adds the gem to a host app and
+  names the easy_flow host whose flows are quizzes.
+- The develop local, `question_kit-develop`, covers scoring, the answer key,
+  time taken, starting a quiz from its title, the question upload and the
+  answer setting explanations.
 
 Anything about building or running the flows themselves, such as the canvas,
-step types, runs and answers, belongs to easy_flow. The easy_flow locals cover
-that.
+step types, runs and recorded answers, belongs to easy_flow, and the easy_flow
+locals cover it. The import pages themselves belong to ixport, and the ixport
+locals cover them.
 
 ## How to use it
 
 - To add question_kit to an app, use `question_kit-install`.
-- To write code that uses question_kit, use `question_kit-develop`.
-- To build the quiz flow or a question step, use the easy_flow locals.
+- To score answers, show an answer key, time a quiz, start a quiz from its
+  title or offer the question upload, use `question_kit-develop`.
+- To build the quiz flow or a question step by hand, use the easy_flow locals.
 
 ## Conventions
 
 - **Quiz** — an easy_flow flow whose steps ask the visitor questions.
-- **Question step** — one easy_flow step that asks one question and records the
-  visitor's answer.
-- **Worth** — what an answer is worth toward the quiz's result.
-- **Right answer** — an answer the quiz counts as correct for its question.
 - **Host app** — the Rails app that installs question_kit and easy_flow and runs
   the quizzes.
+- **Quiz host** — the one easy_flow host in the host app whose flows are
+  quizzes. The answer setting explanations and the question upload apply to
+  that host only.
+- **Question step** — one easy_flow step that asks one question and records the
+  visitor's answer. The rules know three kinds:
+  - a **single choice** question, where the visitor picks one of the step's
+    answers;
+  - a **multiple select** question, where the visitor ticks several;
+  - a **fill-in-the-blank** question, where the visitor types the answer.
+- **Weight** — a number an admin sets on each answer of a choice question.
+- **Right answer** — on a choice question, an answer whose weight is above
+  zero.
+- **Accepted answer** — on a fill-in-the-blank question, a text the admin lists
+  as correct. The list of accepted answers a quiz shows leaves out any left
+  blank.
+- **Worth** — what one answer counts toward the quiz's result:
+  - a single choice answer is worth the weight of the answer picked, and zero
+    when it has none;
+  - a multiple select answer is worth one when the ticked answers are exactly
+    the right answers, and zero otherwise;
+  - a fill-in-the-blank answer is worth one when it matches any accepted answer,
+    ignoring capital letters and spaces at either end, and zero otherwise.
+- **Total** — the sum of the worth of every answer in a run.
+- **Answer key** — the answer a quiz shows as correct for a question: the first
+  right answer of a single choice question, every right answer of a multiple
+  select question, and the first accepted answer of a fill-in-the-blank
+  question.
+- **Time taken** — the seconds from the start of a visitor's run to the last
+  answer they gave. A run with no answers has none. A flow that saves answers
+  only when the visitor finishes, rather than after each step, records no
+  time per answer, so its runs have no time taken.
+- **Titled start** — saving a new quiz from its title alone. A blank title is
+  refused. The quiz's address is made from the title, cut to 100 characters,
+  and is `quiz` when the title holds nothing usable. When another quiz of the
+  same host and owner already has that address, a number is added, starting at
+  2. The words `manage`, `pages` and `runs` are never used as an address.
+- **Uploaded question** — one row of a CSV file an admin uploads to a quiz. Its
+  columns are Type, Question, Category, Answer 1 to Answer 6, and Right answer.
+  - Type is true/false or multiple choice, read without regard to capitals,
+    spaces or punctuation.
+  - Category is saved on the question when it is filled in.
+  - A true/false row gets the answers True and False, and its Right answer is
+    true or false.
+  - A multiple choice row needs at least two answers, and its Right answer is
+    the number of one of them.
+  - The right answer gets a weight of one and every other answer zero.
+  - A row with no question, an unknown type or no right answer is refused.
+- **Where uploaded questions go** — each one is added as a single choice
+  question after the last question a visitor can reach, and is recorded in the
+  quiz's edit history as an added step. It is added to the quiz's unpublished
+  changes, so visitors are not asked it until the quiz is published.
+- **Who may upload** — only to a quiz of the quiz host, and, when that host's
+  flows each belong to an owner, only by the account that owns the quiz.
+- **Answer setting explanation** — the line an admin sees beside a question's
+  answer settings on the canvas, saying what the setting shows a player and
+  what it does to the score. An explanation the host app gives itself is shown
+  in place of question_kit's.

data/the_local/agents/question_kit-install.md

@@ -1,6 +1,6 @@
 ---
 name: question_kit-install
-description: Use to hook question_kit into a project — adding the gem to the host app's Gemfile and installing it alongside easy_flow.
+description: Use to hook question_kit into a project — adding the gem to the host app's Gemfile alongside easy_flow, and naming the easy_flow host whose flows are the app's quizzes.
 tools: Bash, Read, Edit
 scope: shared question and answer rules for easy_flow quizzes — what an answer to a question step is worth, which answers are right, and how a quiz is built
 ---
@@ -14,6 +14,7 @@ A Rails gem holding the shared quiz rules for apps that run quizzes as easy_flow
 ## Interface
 
 - `gem "question_kit"` — the Gemfile line that adds question_kit, and with it easy_flow, to the host app.
+- `QuestionKit.flow_host = name` — names the easy_flow host whose flows are the app's quizzes, so that host's admin settings for answers carry question_kit's explanations and quiz questions are uploaded only into that host's flows.
 
 ## How to use it
 
@@ -33,12 +34,22 @@ A Rails gem holding the shared quiz rules for apps that run quizzes as easy_flow
 
    This edits `Gemfile.lock` and brings in easy_flow if the app did not have it.
 5. Check whether easy_flow is already hooked into the app: its migrations copied and run, its engine mounted, and its hosts declared. If any of that is missing, hand the work to `easy_flow-install`, and ask the developer which hosts to declare rather than picking them.
+6. Find the easy_flow host declarations in the app's initializers, the `EasyFlow.host(:name)` lines. Ask the developer which declared host runs the quizzes. Never pick one, even when only one host is declared.
+7. Set that host as question_kit's flow host, in `config/initializers/question_kit.rb`:
 
-question_kit has no generator, no initializer, no migrations and no routes of its own. Requiring the gem loads easy_flow, so the host app needs no separate `require "easy_flow"`.
+   ```ruby
+   QuestionKit.flow_host = :quizzes
+   ```
+
+   Use the host's name exactly as its `EasyFlow.host` line spells it. The line must run after that `EasyFlow.host` line. Rails runs initializers in alphabetical order by file name, so when the host is declared in a file that sorts after `question_kit.rb`, put the line in that file, directly below the declaration, instead of in a file of its own.
+
+question_kit has no generator, no migrations and no routes of its own. Requiring the gem loads easy_flow, so the host app needs no separate `require "easy_flow"`.
 
 ## Conventions
 
 - After install, run `bundle list | grep -E "question_kit|easy_flow"` and confirm both gems are listed.
+- After install, boot the app with `bin/rails runner 'puts QuestionKit.flow_host'` and confirm it prints the host name chosen in step 6.
+- One app has one quiz host. To move the quizzes to another host, change the name in the `QuestionKit.flow_host` line and nowhere else.
 - After a `bundle update question_kit`, check `Gemfile.lock` again for the easy_flow version it brought in, and run `easy_flow-install` for any new easy_flow migrations.
 - Setting up easy_flow itself, its hosts, step types and admin pages belongs to `easy_flow-install`.
-- Writing code against question_kit belongs to `question_kit-develop`.
+- Registering the quiz question upload with ixport, and writing code against question_kit, belong to `question_kit-develop`.

data/the_local/interface.yml

@@ -2,11 +2,36 @@ scope: shared question and answer rules for easy_flow quizzes — what an answer
 
 install:
   - gem "question_kit"
+  - QuestionKit.flow_host = name
 
 develop:
   - QuestionKit::VERSION
+  - QuestionKit::Score.worth(step, value)
+  - QuestionKit::Score.total(answers, steps)
+  - QuestionKit::Score.right_answers(step)
+  - QuestionKit::AnswerKey.chosen(step)
+  - QuestionKit::AnswerKey.accepted(step)
+  - QuestionKit::TimeTaken.seconds(run)
+  - QuestionKit.flow_host
+  - QuestionKit::TitledStart.new(flow).save
+  - QuestionKit::UploadedQuestion
+  - QuestionKit::UploadedQuestion::ANSWER_FIELDS
+  - QuestionKit::UploadedQuestions.new(flow)
+  - QuestionKit::QuestionImporter
+  - QuestionKit::QuestionImporter.allows?(account, quiz)
+  - QuestionKit::AnswerExplanations
+  - QuestionKit::AnswerExplanations::TEXT
 
 sources:
   - question_kit.gemspec
   - lib/question_kit.rb
   - lib/question_kit/version.rb
+  - lib/question_kit/railtie.rb
+  - lib/question_kit/score.rb
+  - lib/question_kit/answer_key.rb
+  - lib/question_kit/time_taken.rb
+  - lib/question_kit/titled_start.rb
+  - lib/question_kit/uploaded_question.rb
+  - lib/question_kit/uploaded_questions.rb
+  - lib/question_kit/question_importer.rb
+  - lib/question_kit/answer_explanations.rb

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: question_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - tylercschneider
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,7 +50,15 @@ files:
 - README.md
 - Rakefile
 - lib/question_kit.rb
+- lib/question_kit/answer_explanations.rb
+- lib/question_kit/answer_key.rb
+- lib/question_kit/question_importer.rb
 - lib/question_kit/railtie.rb
+- lib/question_kit/score.rb
+- lib/question_kit/time_taken.rb
+- lib/question_kit/titled_start.rb
+- lib/question_kit/uploaded_question.rb
+- lib/question_kit/uploaded_questions.rb
 - lib/question_kit/version.rb
 - lib/tasks/question_kit_tasks.rake
 - the_local/agents/question_kit-develop.md
@@ -64,7 +71,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/DYB-Development/question_kit
   source_code_uri: https://github.com/DYB-Development/question_kit
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -79,8 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Shared question and answer rules for apps that run easy_flow quizzes.
 test_files: []