readout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30ced084ea44a90e897d97abed29f66612e5076f552d38bcc9f80c7ec7b8eac3
+  data.tar.gz: 6be986f4b0730dd944ca0fa4995e6a27023a4072604fbece912e455649a2fb06
+SHA512:
+  metadata.gz: a39383cdbe3c98004d589becdf62d160b71eccd1c08c39ac115a47b8a5c066d3804fe9a958f57ffe8e564bee89c84462288b635c91fd7c80605efd79807a9e19
+  data.tar.gz: 1dde297075475d6677aae17b8c67c74193751e8c6a74359ce51bbe5ce8f50fce78c89b81a475f2b2b7734c03f6a4c2fbada91306920577d95834d2faaa8ba2ce

data/.claude/agents/the_local-develop.md

@@ -0,0 +1,111 @@
+---
+name: the_local-develop
+description: Use PROACTIVELY to turn a gem into a the_local provider — scaffolding the companion, authoring the guide, and committing the rendered locals. MUST BE USED instead of wiring a provider by hand.
+tools: Read, Write, Edit, Grep
+---
+
+You turn a gem into a the_local provider following the reference's provider-author workflow: run `the_local:provider`, write guide.md as the single source of truth (your own gem only), tailor the register block, and hook the_local:build into the Rakefile. The deliverable is the committed, shipped lib/<gem>/the_local/agents/*.md — that is the whole contract a host reads from disk; a host never loads the gem, so unless those files are built, committed, and in the gemspec, the gem contributes nothing. You keep them in sync with agent.to_markdown.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "tylercschneider/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/.claude/agents/the_local-info.md

@@ -0,0 +1,111 @@
+---
+name: the_local-info
+description: Use to learn how the_local works — providers, the build/install model, the delegation trigger, and the direct-dependency scope rule.
+tools: Read
+---
+
+You explain how the_local works, answering only from the reference: providers register locals, the_local:build renders committed .md, install/refresh copy them verbatim into a host, the CLAUDE.md delegation trigger makes the host delegate, and only direct dependencies contribute. You make no changes.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "tylercschneider/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/.claude/agents/the_local-install.md

@@ -0,0 +1,111 @@
+---
+name: the_local-install
+description: Use to add the_local to a host app and set it up correctly.
+tools: Bash, Read, Edit
+---
+
+You set the_local up in a host gem or app, following the reference's install section exactly: add the gem (git source until it is on RubyGems), bundle, run `bundle exec the_local install` to sync locals into .claude/agents/ and write the delegation trigger, and re-run it after bundle changes. You do not invent steps the reference does not list.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "tylercschneider/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold: source-agnostic metric-contract gem (`Readout`), plain
+  Ruby (no Rails / no event-source dependency).

data/CLAUDE.md

@@ -0,0 +1,118 @@
+<!-- the_local:begin -->
+## Delegate to your locals
+
+This project has installed expert subagents. Before doing work yourself,
+check whether a local owns it and delegate — never work from memory on
+something a local covers:
+
+- the_local-* agents
+
+See each agent's description for specifics.
+<!-- the_local:end -->
+
+<!-- the_local:process:begin -->
+Read and follow this develop process for all work in this project. It is
+also written verbatim to `develop_process_rules.md` — reference that file directly.
+
+# Develop Process
+
+The standard process for writing code across all projects. Default to these rules
+unless a project explicitly overrides them.
+
+---
+
+## Diverging from this process
+
+Read this process before starting work and follow it — it is the default for
+every session. If a task genuinely calls for breaking one of these rules, do not
+silently deviate: **PAUSE and ask for a one-time exception**, naming the rule and
+why it should be set aside here. An exception is granted for that instance only —
+it needs no doc or notes update — and then you continue. Do not treat a granted
+exception as a standing change to the process.
+
+---
+
+## Test-Driven Development
+
+TDD is the default for everything. Work one tiny cycle at a time:
+
+1. **Write one test that asserts one thing.**
+2. **Run it and watch it fail** — for the right reason. A test you never saw fail
+   proves nothing.
+3. **Write the minimum code to make it pass.**
+4. **Run the test and watch it pass.**
+5. **Commit.**
+6. Repeat with the next test.
+
+One assertion per test. One test per commit cycle. No batching multiple behaviors
+into a single test or a single commit.
+
+---
+
+## Commits
+
+- A commit is normally **two files: the test file and the code file.**
+- When implementing or updating an interface (e.g. a new controller endpoint) a
+  commit may touch more files (route + controller + view) — that is the minimal
+  coherent unit for that interface, and it is allowed.
+- Keep each commit focused on the one behavior the test describes.
+
+---
+
+## What to Test
+
+- **Test our own code only.**
+- **Never test third-party code** — not a gem, not an API, not a framework. The
+  only test that may reference a dependency is one that asserts *our system is
+  correctly wired to it* (the integration seam), never the dependency's own
+  behavior.
+- **Never test another interface inside a unit test.** A test covers one interface.
+  The single exception is the smoke integration test described below.
+
+---
+
+## Smoke Integration Test
+
+When implementing an interface, write **one smoke integration test** that exercises
+the interface end to end and proves the pieces are connected. This is the one place
+where touching more than the unit under test is expected and correct.
+
+---
+
+## Pull Requests
+
+- **Always work on a feature branch and open a PR.** Confirm the target branch
+  before any git operation (`git branch --show-current`).
+- **Keep PRs small and manageable** — typically **no more than 8–10 files.**
+- Keep the focus of a PR narrow. One concern per PR.
+- **All tests pass before opening the PR.**
+- **The linter and every other CI check pass before opening the PR.**
+- Never start a new PR until the previous one is merged.
+
+---
+
+## Code Quality
+
+- Follow Clean Code principles: small functions, clear names, no surprises.
+- Follow SOLID principles. Readable by a human first.
+- Keep it simple — no abstraction until a real need calls for it.
+- Explicitly require libraries rather than assuming autoload.
+
+## Comments
+
+- **Write self-documenting code, not comments.** Code should be clean and readable
+  on its own. Names — of classes, methods, variables, and partials — carry the intent.
+- **A comment is a smell.** If you feel a comment is needed, the code is either built
+  wrong or needs refactoring (a clearer name, a smaller method, an extracted object or
+  partial) so the intent is obvious without prose. Follow SOLID and this resolves itself.
+- Do not leave explanatory headers on classes/methods, inline "what this does" notes,
+  or section banners. Delete them and let the structure speak.
+- Narrow exceptions, kept rare: a genuinely non-obvious *why* (a workaround for an
+  external bug, a legal/security constraint) and machine-readable annotations the
+  tooling requires (e.g. `rubocop:disable`). Prefer refactoring over a "why" comment
+  whenever you can.
+<!-- the_local:process:end -->
+
+
+
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+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,54 @@
+# Readout
+
+A **source-agnostic, self-describing metric contract**.
+
+A `Readout::Stat` describes a metric — its key, title, plain-English definition,
+unit, timeframe, and declared inputs — and exposes a normalized **result shape**
+(`value`, `shape`, `as_of`, `exact`). Behind every Stat is a **Source** (an adapter
+port); the Stat doesn't care where its number comes from.
+
+That decoupling is the whole point: a display layer (e.g. `dash_kit`) renders Stats
+without knowing whether the number came from `tally` rollups, a live query, or a
+fixture. Swap the Source, keep the Stat.
+
+Readout depends on nothing concrete — no Rails, no event source, no aggregation
+engine. Adapters bridge it to whatever produces the numbers.
+
+## Installation
+
+```ruby
+gem "readout"
+```
+
+## Status
+
+The core contract works — a `Stat` reads through its `Source` and returns a
+normalized `Result`:
+
+```ruby
+source = ->(inputs) { Readout::Result.new(value: 0.42, shape: :scalar, exact: true) }
+stat   = Readout::Stat.new(
+  key: :sales_conversion,
+  title: "Sales Conversion",
+  definition: "Share of qualified leads that became deals.",
+  calculation: "deals ÷ qualified leads, within the period",
+  unit: :percent,
+  timeframe: "This month",
+  source: source
+)
+
+stat.read(qualified: 100, won: 42).value   # => 0.42
+stat.definition                            # the plain-English "what it captures"
+stat.calculation                           # the "how it's computed"
+```
+
+A Stat is **self-describing** — `title`, `definition`, `calculation`, `unit`,
+`timeframe` — so a UI can explain any number without hardcoding meaning. `Result`
+carries `value, shape, as_of, exact`. Swap the `Source` (a tally-backed one, a live
+query, a fixture) without touching the Stat or the display.
+
+Next: declared inputs (required/optional) + validation.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/develop_process_rules.md

@@ -0,0 +1,97 @@
+# Develop Process
+
+The standard process for writing code across all projects. Default to these rules
+unless a project explicitly overrides them.
+
+---
+
+## Diverging from this process
+
+Read this process before starting work and follow it — it is the default for
+every session. If a task genuinely calls for breaking one of these rules, do not
+silently deviate: **PAUSE and ask for a one-time exception**, naming the rule and
+why it should be set aside here. An exception is granted for that instance only —
+it needs no doc or notes update — and then you continue. Do not treat a granted
+exception as a standing change to the process.
+
+---
+
+## Test-Driven Development
+
+TDD is the default for everything. Work one tiny cycle at a time:
+
+1. **Write one test that asserts one thing.**
+2. **Run it and watch it fail** — for the right reason. A test you never saw fail
+   proves nothing.
+3. **Write the minimum code to make it pass.**
+4. **Run the test and watch it pass.**
+5. **Commit.**
+6. Repeat with the next test.
+
+One assertion per test. One test per commit cycle. No batching multiple behaviors
+into a single test or a single commit.
+
+---
+
+## Commits
+
+- A commit is normally **two files: the test file and the code file.**
+- When implementing or updating an interface (e.g. a new controller endpoint) a
+  commit may touch more files (route + controller + view) — that is the minimal
+  coherent unit for that interface, and it is allowed.
+- Keep each commit focused on the one behavior the test describes.
+
+---
+
+## What to Test
+
+- **Test our own code only.**
+- **Never test third-party code** — not a gem, not an API, not a framework. The
+  only test that may reference a dependency is one that asserts *our system is
+  correctly wired to it* (the integration seam), never the dependency's own
+  behavior.
+- **Never test another interface inside a unit test.** A test covers one interface.
+  The single exception is the smoke integration test described below.
+
+---
+
+## Smoke Integration Test
+
+When implementing an interface, write **one smoke integration test** that exercises
+the interface end to end and proves the pieces are connected. This is the one place
+where touching more than the unit under test is expected and correct.
+
+---
+
+## Pull Requests
+
+- **Always work on a feature branch and open a PR.** Confirm the target branch
+  before any git operation (`git branch --show-current`).
+- **Keep PRs small and manageable** — typically **no more than 8–10 files.**
+- Keep the focus of a PR narrow. One concern per PR.
+- **All tests pass before opening the PR.**
+- **The linter and every other CI check pass before opening the PR.**
+- Never start a new PR until the previous one is merged.
+
+---
+
+## Code Quality
+
+- Follow Clean Code principles: small functions, clear names, no surprises.
+- Follow SOLID principles. Readable by a human first.
+- Keep it simple — no abstraction until a real need calls for it.
+- Explicitly require libraries rather than assuming autoload.
+
+## Comments
+
+- **Write self-documenting code, not comments.** Code should be clean and readable
+  on its own. Names — of classes, methods, variables, and partials — carry the intent.
+- **A comment is a smell.** If you feel a comment is needed, the code is either built
+  wrong or needs refactoring (a clearer name, a smaller method, an extracted object or
+  partial) so the intent is obvious without prose. Follow SOLID and this resolves itself.
+- Do not leave explanatory headers on classes/methods, inline "what this does" notes,
+  or section banners. Delete them and let the structure speak.
+- Narrow exceptions, kept rare: a genuinely non-obvious *why* (a workaround for an
+  external bug, a legal/security constraint) and machine-readable annotations the
+  tooling requires (e.g. `rubocop:disable`). Prefer refactoring over a "why" comment
+  whenever you can.

data/lib/readout/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Readout
+  Result = Struct.new(:value, :shape, :as_of, :exact, keyword_init: true)
+end

data/lib/readout/stat.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Readout
+  class Stat
+    attr_reader :key, :title, :definition, :calculation, :unit, :timeframe
+
+    def initialize(key:, title: nil, definition: nil, calculation: nil, unit: nil, timeframe: nil, source: nil)
+      @key = key
+      @title = title
+      @definition = definition
+      @calculation = calculation
+      @unit = unit
+      @timeframe = timeframe
+      @source = source
+    end
+
+    def read(inputs)
+      @source.call(inputs)
+    end
+  end
+end

data/lib/readout/version.rb

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

data/lib/readout.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "readout/version"
+require_relative "readout/result"
+require_relative "readout/stat"
+
+module Readout
+  class Error < StandardError; end
+end

data/sig/readout.rbs

@@ -0,0 +1,4 @@
+module Readout
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: readout
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Readout defines a Stat — a self-describing metric (key, title, plain-English
+  definition, unit, timeframe, declared inputs) with a normalized result shape (value,
+  shape, as_of, exact) and a Source adapter port. It depends on nothing concrete:
+  any source (e.g. tally rollups) plugs in behind a Stat, so the display layer never
+  couples to where a number comes from.'
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/agents/the_local-develop.md"
+- ".claude/agents/the_local-info.md"
+- ".claude/agents/the_local-install.md"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- develop_process_rules.md
+- lib/readout.rb
+- lib/readout/result.rb
+- lib/readout/stat.rb
+- lib/readout/version.rb
+- sig/readout.rbs
+homepage: https://github.com/tylercschneider/readout
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tylercschneider/readout
+  source_code_uri: https://github.com/tylercschneider/readout
+  changelog_uri: https://github.com/tylercschneider/readout/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tylercschneider/readout/issues
+  rubygems_mfa_required: 'true'
+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.20
+specification_version: 4
+summary: Source-agnostic, self-describing metric contract
+test_files: []