assistant 0.1.0 → 1.0.0.rc1

data/Gemfile.lock

@@ -1,36 +1,117 @@
 PATH
   remote: .
   specs:
-    assistant (0.1.0)
+    assistant (1.0.0.rc1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
-    brakeman (8.0.4)
-      racc
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
     byebug (13.0.0)
       reline (>= 0.6.0)
+    colorator (1.1.0)
     colorize (1.1.0)
-    fasterer (0.11.0)
-      ruby_parser (>= 3.19.1)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
+    docile (1.4.1)
+    drb (2.2.3)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.4)
+    ffi (1.17.4-arm64-darwin)
+    fileutils (1.8.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.35.1)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.35.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
     io-console (0.8.2)
-    json (2.19.5)
+    jekyll (4.4.1)
+      addressable (~> 2.4)
+      base64 (~> 0.2)
+      colorator (~> 1.0)
+      csv (~> 3.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.3, >= 0.3.6)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-relative-links (0.7.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
+    jekyll-seo-tag (2.9.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    json (2.19.9)
+    just-the-docs (0.12.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    minitest (5.27.0)
+    liquid (4.0.4)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mercenary (0.4.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
     parallel (2.1.0)
     parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
     prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.4.2)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
     regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
-    rubocop (1.86.1)
+    rexml (3.4.4)
+    rouge (4.7.0)
+    rubocop (1.86.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -55,14 +136,47 @@ GEM
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
+    rubocop-style-compact_nesting (0.1.2)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72, < 2.0)
     ruby-progressbar (1.13.0)
-    ruby_parser (3.22.0)
-      racc (~> 1.5)
-      sexp_processor (~> 4.16)
-    sexp_processor (4.17.5)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.101.0)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.101.0-arm64-darwin)
+      google-protobuf (~> 4.31)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    steep (2.0.0)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.17.0.4, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.2)
+      prism (>= 0.25.0)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 4.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 5)
+      uri (>= 0.12.0)
+    strscan (3.1.8)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    tsort (0.2.0)
+    unicode-display_width (2.6.0)
+    uri (1.1.1)
+    webrick (1.9.2)
+    yard (0.9.44)
 
 PLATFORMS
   arm64-darwin-25
@@ -70,49 +184,102 @@ PLATFORMS
 
 DEPENDENCIES
   assistant!
-  brakeman (~> 8.0)
   bundler (~> 4.0)
   byebug (~> 13.0)
   colorize (~> 1.1)
-  fasterer (~> 0.11.0)
-  minitest (~> 5.25)
+  jekyll (~> 4.3)
+  jekyll-relative-links (~> 0.7)
+  just-the-docs (~> 0.10)
+  minitest (~> 6.0)
   rake (~> 13.4)
-  rubocop (~> 1.86)
+  rubocop (~> 1.86, >= 1.86.2)
   rubocop-minitest (~> 0.39)
   rubocop-performance (~> 1.26)
   rubocop-rake (~> 0.7)
+  rubocop-style-compact_nesting (~> 0.1)
+  simplecov (~> 0.22)
+  steep (~> 2.0)
+  yard (~> 0.9)
 
 CHECKSUMS
-  assistant (0.1.0)
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  assistant (1.0.0.rc1)
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
-  brakeman (8.0.4) sha256=7bf921fa9638544835df9aa7b3e720a9a72c0267f34f92135955edd80d4dcf6f
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
   bundler (4.0.11) sha256=5bcec0fb78302e48d02ee46f10ee6e6942be647ba5b44a6d1ddfda9a240ce785
   byebug (13.0.0) sha256=d2263efe751941ca520fa29744b71972d39cbc41839496706f5d9b22e92ae05d
+  colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38
   colorize (1.1.0) sha256=30b5237f0603f6662ab8d1fc2bd4a96142b806c6415d79e45ef5fdc6a0cfc837
-  fasterer (0.11.0) sha256=9c38b77583584f3339a729eb077fd8f2856a317abe747528f6563d7c23e9dda8
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8
+  eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972
+  ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  fileutils (1.8.0) sha256=8c6b1df54e2540bdb2f39258f08af78853aa70bad52b4d394bbc6424593c6e02
+  forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97
+  google-protobuf (4.35.1) sha256=a3a6471331d918f58dfa4d014a8f6286f0af2cf4840216bde52fcf2ea3fe3726
+  google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
+  http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
-  json (2.19.5) sha256=218a18553e4801d579ca7e0f5bc72bafd776d7397238a1fb4e74db5b0a812c59
+  jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1
+  jekyll-include-cache (0.2.1) sha256=c7d4b9e551732a27442cb2ce853ba36a2f69c66603694b8c1184c99ab1a1a205
+  jekyll-relative-links (0.7.0) sha256=831e54c348eeae751845c0d4ac4b244bd73b664341f0e8c9f1803b16f4570835
+  jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443
+  jekyll-seo-tag (2.9.0) sha256=0260015a8e1df9bf195cdfb0c675b7b2883fd8cbf12556e1c1cbe36a831c6852
+  jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1
+  json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
+  just-the-docs (0.12.0) sha256=15f2839ac9082898d60f33b978aa6f8e46fc50ba8fac20ae7a7f0e1fb295523e
+  kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa
+  kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
-  minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3
+  listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
   parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
+  pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  rbs (4.0.2) sha256=af75671e66cd03434cc546622741ebf83f6197ec4328375805306330bf78ef25
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  rubocop (1.86.1) sha256=44415f3f01d01a21e01132248d2fd0867572475b566ca188a0a42133a08d4531
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739
+  rubocop (1.86.2) sha256=bb2e97f635eda42c448f2588f4a6ff78f221b8bdfdf65b1e9b07fbd57521b45d
   rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   rubocop-minitest (0.39.1) sha256=998398d6da4026d297f0f9bf709a1eac5f2b6947c24431f94af08138510cf7ed
   rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
   rubocop-rake (0.7.1) sha256=3797f2b6810c3e9df7376c26d5f44f3475eda59eb1adc38e6f62ecf027cbae4d
+  rubocop-style-compact_nesting (0.1.2) sha256=cbe155ec7230dcea32925d34a435b40c2fc666ea9b45755f92102dd1a73b739b
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
-  ruby_parser (3.22.0) sha256=1eb4937cd9eb220aa2d194e352a24dba90aef00751e24c8dfffdb14000f15d23
-  sexp_processor (4.17.5) sha256=ae2b48ba98353d5d465ce8759836b7a05f2e12c5879fcd14d7815b026de32f0e
-  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
-  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848
+  sass-embedded (1.101.0) sha256=57dbc3409e2c0a2c581a4c9945c2bd72ec88e71ec98017bd02dd1da8a76b22f4
+  sass-embedded (1.101.0-arm64-darwin) sha256=9fed684380b49499dfc856aba0d026a0748f924bd78044ffff2bae1537aea73e
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  steep (2.0.0) sha256=6eb0ecc09637bbb54f0a5f2cf63daea6d3208ccace64b4f1107d976333605c30
+  strscan (3.1.8) sha256=aae2db611a225559f21ffbb71765c9a4e60fd262534a9ea84f4f11c7f32f679e
+  terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+  yard (0.9.44) sha256=eb087e9b631ccd887b049f303d489963945452d5e2a7eb49a5a74a7cf6887f28
 
 BUNDLED WITH
   4.0.11

data/README.md

@@ -1,43 +1,152 @@
 # Assistant
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/assistant`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![CI](https://github.com/ramongr/assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/ramongr/assistant/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/assistant.svg)](https://rubygems.org/gems/assistant)
+[![Downloads](https://img.shields.io/gem/dt/assistant.svg)](https://rubygems.org/gems/assistant)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.4-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-TODO: Delete this and the text above, and describe your gem
+A tiny, dependency-free Ruby library for writing **soft-fail, composable
+service objects**. A service declares its inputs, validates them, runs its
+body, and returns a uniform result that always carries either a value plus
+warnings or a list of errors — it never raises for expected failures.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```sh
+bundle add assistant
+```
 
-```ruby
-gem 'assistant'
+Or without Bundler:
+
+```sh
+gem install assistant
 ```
 
-And then execute:
+Ruby `>= 3.4` is required.
+
+## 60-second example
+
+```ruby
+require 'assistant'
+
+class CreateUser < Assistant::Service
+  input :email, type: String,  required: true
+  input :name,  type: String,  required: true
+  input :age,   type: Integer, allow_nil: true, default: nil
+
+  def validate
+    return if email.include?('@')
+
+    log_item_error(source: :validate, detail: :email, message: 'must contain @')
+  end
 
-    $ bundle
+  def execute
+    log_item_warning(source: :execute, detail: :age, message: 'age missing') if age.nil?
 
-Or install it yourself as:
+    User.create!(email:, name:, age:)
+  end
+end
 
-    $ gem install assistant
+CreateUser.run(email: 'ada@example.com', name: 'Ada')
+# => { result: #<User …>, status: :with_warnings, warnings: [#<Assistant::LogItem …>] }
 
-## Usage
+CreateUser.run(email: 'nope', name: 'Ada')
+# => { errors: [#<Assistant::LogItem …>], result: nil, status: :with_errors }
+```
+
+The result hash is always one of two shapes:
 
-TODO: Write usage instructions here
+```ruby
+# Success — status is :ok or :with_warnings
+{ result: <Object>, status: :ok | :with_warnings, warnings: Array<Assistant::LogItem> }
+
+# Failure — any error was logged before or during execute
+{ errors: Array<Assistant::LogItem>, result: nil, status: :with_errors }
+```
+
+Use `#success?`, `#failure?`, and `#status` on a service instance, or
+pattern-match the hash returned by `.run` directly.
+
+## Why another service-object gem?
+
+- **No runtime dependencies.** `assistant` is one require away; it does not
+  pull in ActiveSupport, dry-rb, or anything else. It runs in plain Ruby,
+  Rails, Hanami, Sidekiq workers, and Rake tasks alike.
+- **Soft-fail by design.** Validation problems and recoverable failures are
+  surfaced as `LogItem`s on the result, not exceptions. Callers
+  pattern-match a hash; they don't write `rescue` blocks for expected
+  outcomes.
+- **Tiny, frozen surface.** The public API documented in
+  [`docs/v1/01-api-surface.md`](docs/v1/01-api-surface.md) is everything
+  there is. No DSL gymnastics, no plug-in registry, no opinionated
+  serialization. Compose services with the plain `#call_service` primitive.
+
+Compared to [Interactor](https://github.com/collectiveidea/interactor) and
+[dry-transaction](https://dry-rb.org/gems/dry-transaction/), `assistant`
+keeps a single result shape regardless of success or failure, distinguishes
+warnings from errors at the log-item level, and ships RBS signatures plus
+a per-class generator (`bin/assistant-rbs`) out of the box.
+
+## Documentation
+
+- **Getting started** — [`docs/getting-started.md`](docs/getting-started.md)
+  walks from `gem install` to a first working service.
+- **API reference** — [`docs/api-reference.md`](docs/api-reference.md)
+  is the hand-written, curated reference for every Frozen symbol; the
+  source of truth for stability labels stays in
+  [`docs/v1/01-api-surface.md`](docs/v1/01-api-surface.md).
+- **Feature catalogue and rationale** —
+  [`docs/v1/02-features.md`](docs/v1/02-features.md).
+- **Upgrading from 0.x** —
+  [`docs/v1/06-migration-0x-to-1.md`](docs/v1/06-migration-0x-to-1.md).
+- **Deprecations** — [`docs/deprecations.md`](docs/deprecations.md).
+- **Runnable sample** — [`examples/greeter.rb`](examples/greeter.rb).
+- **Changelog** — [`CHANGELOG.md`](CHANGELOG.md).
+
+The deeper guides (`docs/guides/inputs.md`,
+`docs/guides/validation.md`, `docs/guides/logging-and-results.md`,
+`docs/guides/composing-services.md`) are tracked in
+[`docs/v1/03-documentation.md`](docs/v1/03-documentation.md) and land
+in follow-up PRs.
+
+## Roadmap
+
+The plan for the 1.0 release lives under
+[`docs/v1/`](docs/v1/README.md). Every "must" item is shipped; remaining
+work is documentation and release-checklist tasks.
 
 ## 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.
+```sh
+bin/setup                                  # install dependencies
+bundle exec rake test                      # Minitest
+bundle exec rubocop                        # style
+bundle exec steep check --jobs=1           # type-check RBS signatures
+bin/console                                # IRB session with the gem loaded
+```
+
+To install the gem locally for ad-hoc experimentation:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```sh
+bundle exec rake install
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/assistant. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome at
+<https://github.com/ramongr/assistant>. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [Contributor Covenant](http://contributor-covenant.org) code
+of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is released under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the Assistant project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/assistant/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Assistant project's codebases, issue trackers,
+chat rooms, and mailing lists is expected to follow the
+[code of conduct](https://github.com/ramongr/assistant/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -10,4 +10,49 @@ Rake::TestTask.new(:test) do |t|
   t.warning = false
 end
 
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new
+rescue LoadError
+  # rubocop is a development-only dependency; the rubocop task is unavailable
+  # in environments (e.g. release builds) where it isn't installed.
+end
+
+desc 'Run Steep type-check (matches the required CI job)'
+task :steep do
+  sh 'bundle exec steep check --jobs=1'
+end
+
+desc 'YARD: build docs into doc/ and enforce 100% public-method coverage'
+task :yard do
+  sh 'bundle exec yard doc --quiet'
+  stats = `bundle exec yard stats --list-undoc 2>&1`
+  match = stats.match(/([\d.]+)% documented/)
+  abort "yard: could not parse stats output:\n#{stats}" unless match
+
+  percentage = match[1].to_f
+  abort "yard: only #{format('%.2f', percentage)}% documented; full output:\n#{stats}" if percentage < 100.0
+  puts "yard: #{format('%.2f', percentage)}% documented"
+end
+
+desc 'Run the full local CI pipeline: test + rubocop + steep + yard'
+task ci: %i[test rubocop steep yard]
+
+namespace :docs do
+  desc 'Install the Jekyll docs toolchain (Bundler :docs group)'
+  task :install do
+    sh 'bundle install --with docs'
+  end
+
+  desc 'Build the Jekyll site into ./_site (mirrors the CI Pages build)'
+  task :build do
+    sh 'bundle exec jekyll build --strict_front_matter'
+  end
+
+  desc 'Serve the Jekyll site on http://127.0.0.1:4000 with live reload'
+  task :serve do
+    sh 'bundle exec jekyll serve --livereload'
+  end
+end
+
 task default: :test

data/SECURITY.md

@@ -0,0 +1,50 @@
+<!-- markdownlint-disable MD013 -->
+# Security Policy
+
+`assistant` is a small Ruby gem with no runtime dependencies and a tiny
+surface area, but security reports are still very welcome.
+
+## Supported versions
+
+| Version | Status                                                          |
+|---------|-----------------------------------------------------------------|
+| 1.x     | **Supported.** Security fixes land on `main` and ship promptly. |
+| 0.x     | **End of life** on the `1.0.0` release. No further fixes.       |
+
+The supported branch will always be the current `1.x` release line. There is
+no intention to backport security fixes to `0.x` once `1.0.0` ships; users on
+`0.x` should upgrade. The migration guide lives at
+[`docs/v1/06-migration-0x-to-1.md`](./docs/v1/06-migration-0x-to-1.md).
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue or pull request for a security report.**
+
+Email <cerberus.ramon@gmail.com> with:
+
+- A description of the issue.
+- The version of `assistant` (and Ruby) you reproduced it on.
+- A minimal proof-of-concept or runnable reproduction.
+- Any suggested mitigation, if you have one.
+
+If the report involves dependencies pulled in by a downstream Rails or Sinatra
+application, please mention that too — `assistant` itself has zero runtime
+dependencies, so the issue may need to be routed upstream.
+
+## Response SLA
+
+We aim for the following turnaround on a best-effort basis:
+
+- **First response:** within **7 days** of receiving the email.
+- **Fix or mitigation plan:** within **30 days** of triage, depending on
+  severity. Critical issues are fast-tracked.
+
+You will be kept in the loop on the timeline and credited in the
+`CHANGELOG.md` entry once the fix ships, unless you ask to remain anonymous.
+
+## Coordinated disclosure
+
+We follow a coordinated-disclosure model: the fix is released first, the
+CHANGELOG entry calls out the affected versions and the reporter, and any
+CVE / GHSA advisory is filed afterwards. Please do not publish details
+publicly until the fixed release is out.

data/Steepfile

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Steep configuration for the `assistant` gem (docs/v1 M8).
+#
+# A single `:lib` target type-checks the gem's Ruby code against the
+# sibling `lib/**/*.rbs` declarations.
+#
+# Steep is intentionally restricted to files that do **not** rely on
+# metaprogramming Steep cannot model:
+#
+#   * `Module#define_method` (used by InputBuilder to install the
+#     per-input `valid_type_*?`, `valid_required_*?`, etc. methods);
+#   * `Kernel#send` to one of those generated methods;
+#   * Ruby refinements (`Assistant::Refinements::StringBlankness`);
+#   * cross-module helper lookups that only resolve once every
+#     `InputBuilder` submodule has been mixed into the same singleton.
+#
+# Signatures for the excluded files still live in `lib/**/*.rbs` so
+# downstream consumers (and the included files) can name the modules
+# and call the helpers. The full per-input surface generated by
+# `Service.input` is the subject of M11 (`bin/assistant-rbs`).
+target :lib do
+  signature 'lib'
+
+  library 'fileutils'
+  library 'optparse'
+
+  check 'lib/assistant.rb'
+  check 'lib/assistant/version.rb'
+  check 'lib/assistant/input_builder.rb'
+  check 'lib/assistant/input_builder/registry.rb'
+  check 'lib/assistant/input_builder/default_option.rb'
+  check 'lib/assistant/input_builder/optional_option.rb'
+  check 'lib/assistant/rbs_generator.rb'
+  check 'lib/assistant/rbs_generator/renderer.rb'
+  check 'lib/assistant/rbs_generator/writer.rb'
+  check 'lib/assistant/rbs_generator/cli.rb'
+end
+
+# Type-checks the sample service in `examples/` against the .rbs
+# generated by `exe/assistant-rbs` and shipped in `sig/examples/`.
+# Doubles as the M11 regression that the generator's output is in fact
+# accepted by Steep.
+target :examples do
+  signature 'lib'
+  signature 'sig'
+
+  check 'examples'
+end