readout 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b916687af6e5b720d58adf3f4e842405529340f447510c9929fe40c77130590
-  data.tar.gz: d97935c3995909c5b8d149cf488d2ffb3f4e4b85833023360e7e5b1945ba453c
+  metadata.gz: 65a550bbaa11d7ea07cbb2cf8cc6dceaf611354dedea94bb99740d27afc55569
+  data.tar.gz: '00995800efa634f0da429569f2084dba7d5be9aee74bd0c78860847833552902'
 SHA512:
-  metadata.gz: b25addb3ea16c1e68f29ac9f3d8b615be4f6e38045c1664faec5d6749bee9eadbdf6c7e673d5cf0fa87d3ec870549b648d8a490475a25b1bfb1192405c5289cb
-  data.tar.gz: e80886070d7cb964153592a5a22febd5e7638205ada15f0a851cbccd37a05cfc80b3e78e52d63ee711b945cfdadcf60190a532d14ce91c0aa08a2289b6a9b2f0
+  metadata.gz: 67ba649e19014d3d7668b1d34ec1e3be501f5425cc3fb4d874621a86045a583328f067c8e9f274dddf6936893a44c3c39116b2fe1d6eb4993fb2c0a36a2299c6
+  data.tar.gz: '074875441dc2070fe0fc6193250c6bd1447e64c3181925104a934556a9f4ba3ba554e874652cb72329c57adf4cdcf9a5d5a6efc60e33b2c205e169c24a7782d8'

data/CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this project are documented here, following
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-26
+
+### Changed
+- readout's info, install and develop agents are now written by the_local's
+  authoring task instead of by hand.
+
 ## [0.2.0] - 2026-09-25
 
 ### Added

data/lib/readout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Readout
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/the_local/agents/readout-develop.md

@@ -35,11 +35,19 @@ Use this local whenever code needs a named, explained metric value.
    returns a `Readout::Result`; a lambda works:
 
    ```ruby
-   source = ->(inputs) { Readout::Result.new(value: 0.42, shape: :scalar, as_of: Time.now, exact: true) }
+   source = ->(inputs) do
+     Readout::Result.new(
+       value: inputs[:won].fdiv(inputs[:qualified]),
+       shape: :scalar,
+       as_of: Time.now,
+       exact: true
+     )
+   end
    ```
 
    Stat does not check what the source returns, so the source must build the
-   `Readout::Result` itself.
+   `Readout::Result` itself. readout accepts any object for `shape`, `as_of` and
+   `exact`, so ask the developer which values the project uses for `shape`.
 2. Ask the developer where the number comes from, and put that lookup inside the
    source. The source is the only place that knows where the number comes from.
 3. Build the Stat with its description and the source:

data/the_local/agents/readout-info.md

@@ -34,7 +34,9 @@ develop local.
 ## Conventions
 
 - A **Stat** is one metric: a key plus its title, definition, calculation, unit
-  and timeframe, and the source it reads from.
+  and timeframe, and the source it reads from. Only the key is required.
+- Reading a Stat hands its inputs to the source unchanged and returns whatever
+  the source returns. readout itself computes nothing.
 - The **definition** says what the metric captures, and the **calculation** says
   how its value is computed, both in plain English.
 - A **source** is any object that responds to `call(inputs)` and returns a Result.

data/the_local/agents/readout-install.md

@@ -1,6 +1,6 @@
 ---
 name: readout-install
-description: Use to hook readout into a project — adding the gem to the Gemfile and loading it in plain Ruby.
+description: Use to hook readout into a project — adding the gem to the Gemfile and loading it with require.
 tools: Bash, Read, Edit
 scope: self-describing metrics — defining a Stat, reading it through a pluggable source, and the normalized Result it returns
 ---
@@ -16,22 +16,27 @@ Add it to any project that defines or displays metrics.
 ## Interface
 
 - `gem "readout"` — the Gemfile line that adds readout to the bundle.
-- `require "readout"` — loads readout in code that is not auto-required by Bundler.
+- `require "readout"` — loads readout in code that Bundler does not auto-require.
 
 ## How to use it
 
 1. Ask the developer how to source the gem. Use `gem "readout"` for the published
    gem, or `gem "readout", github: "tylercschneider/readout"` for the repository.
-   Add the chosen line to the host's `Gemfile`.
-2. Run `bundle install`.
-3. In a Rails app, `Bundler.require` loads readout, so stop here. Anywhere else, add
-   `require "readout"` at the top of the file that first uses it.
-4. Confirm it loads: `bundle exec ruby -e 'require "readout"; puts Readout::VERSION'`
+2. If the host is itself a gem, ask the developer whether readout is a runtime
+   dependency of it. If it is, add `spec.add_dependency "readout"` to the host's
+   gemspec, and if step 1 chose the repository, also add that line to the host's
+   `Gemfile`. If it is not, or the host is an app, add the line from step 1 to the
+   host's `Gemfile`.
+3. Run `bundle install`.
+4. In a Rails app, `Bundler.require` loads readout, so skip this step. Anywhere
+   else, add `require "readout"` at the top of the file that first uses it.
+5. Confirm it loads: `bundle exec ruby -e 'require "readout"; puts Readout::VERSION'`
    prints a version.
 
 ## Conventions
 
 - readout needs Ruby 3.2 or newer.
 - It adds no generators, initializers, migrations or configuration files, so
-  setup edits the `Gemfile` and nothing else.
+  setup edits the `Gemfile` or gemspec and nothing else.
+- After a readout upgrade, run `bundle update readout` and repeat step 5.
 - Defining and reading metrics is the develop local's job.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: readout
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - tylercschneider