assistant 0.1.0 → 1.0.0.rc1

data/_config.yml

@@ -0,0 +1,87 @@
+# Site configuration for the Assistant docs site, deployed to
+# https://ramongr.github.io/assistant/ via .github/workflows/docs.yml.
+# Toolchain: Jekyll 4 + just-the-docs (Ruby). Source files live under
+# docs/. The v1 planning corpus under docs/v1/ is excluded — those are
+# authored-for-GitHub-render plan docs, not site pages.
+
+title: Assistant
+description: >-
+  Tiny, dependency-free soft-fail service objects for Ruby. Uniform result
+  hash, RBS signatures, 1.0-frozen public API, zero runtime gem dependencies.
+url: https://ramongr.github.io
+baseurl: /assistant
+repository: ramongr/assistant
+
+# Source layout
+source: docs
+destination: _site
+
+# Theme
+theme: just-the-docs
+color_scheme: light
+
+# Search
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: true
+  focus_shortcut_key: 'k'
+
+# Navigation
+nav_enabled: true
+heading_anchors: true
+
+# Aux links (top-right)
+aux_links:
+  View on GitHub:
+    - https://github.com/ramongr/assistant
+  RubyGems:
+    - https://rubygems.org/gems/assistant
+aux_links_new_tab: true
+
+# Footer
+gh_edit_link: true
+gh_edit_link_text: Edit this page on GitHub
+gh_edit_repository: https://github.com/ramongr/assistant
+gh_edit_branch: main
+gh_edit_source: docs
+gh_edit_view_mode: tree
+
+back_to_top: true
+back_to_top_text: Back to top
+
+# Build settings
+markdown: kramdown
+kramdown:
+  syntax_highlighter: rouge
+  input: GFM
+  hard_wrap: false
+
+# Files Jekyll should ignore. Paths are relative to `source:` (docs/),
+# so `v1` skips docs/v1/ — the v1 planning corpus authored for GitHub's
+# Markdown renderer (relative links into ../ and across plan files). It
+# is intentionally NOT a site route.
+exclude:
+  - v1
+  - README.md
+
+# Jekyll plugins (the GitHub Pages workflow installs these via Bundler;
+# we are not using github-pages gem, so plugins must be safe-listed too)
+plugins:
+  - jekyll-seo-tag
+  - jekyll-relative-links
+
+# Rewrite intra-docs Markdown links (foo.md) to Jekyll URLs so the
+# same files render both on GitHub (where authors keep .md links for
+# context) and on the site (where .html is needed).
+relative_links:
+  enabled: true
+  collections: false
+
+# just-the-docs strict mode is off because the v1 plan docs use
+# kramdown-incompatible link anchors; this site doesn't include them.

data/assistant.gemspec

@@ -13,35 +13,52 @@ Gem::Specification.new do |spec|
   spec.authors = ['Ramon Rodrigues']
   spec.email = ['cerberus.ramon@gmail.com']
 
-  spec.summary = 'Simple, soft fail enabled, composable services'
-  spec.description = 'Simple, composable services'
+  spec.summary = 'Tiny, dependency-free soft-fail service objects for Ruby'
+  spec.description = <<~DESC
+    Assistant is 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 — never raising for
+    expected failures. Ships with RBS signatures, a 1.0-frozen public API,
+    and zero runtime gem dependencies.
+  DESC
   spec.homepage = 'https://github.com/ramongr/assistant'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.4'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/ramongr/assistant/issues'
   spec.metadata['changelog_uri'] = 'https://github.com/ramongr/assistant/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/assistant'
   spec.metadata['homepage_uri'] = 'https://github.com/ramongr/assistant'
   spec.metadata['rubygems_mfa_required'] = 'true'
   spec.metadata['source_code_uri'] = 'https://github.com/ramongr/assistant'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  # Internal planning docs (`docs/v1/`, `docs/v1.x/`) and runnable examples
+  # are excluded from the packaged gem (Q9 decision).
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|examples|docs/v1(\.x)?)/})
+    end
   end
 
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = 'lib'
 
-  spec.add_development_dependency 'brakeman', '~> 8.0'
   spec.add_development_dependency 'bundler', '~> 4.0'
   spec.add_development_dependency 'byebug', '~> 13.0'
   spec.add_development_dependency 'colorize', '~> 1.1'
-  spec.add_development_dependency 'fasterer', '~> 0.11.0'
-  spec.add_development_dependency 'minitest', '~> 5.25'
+  spec.add_development_dependency 'minitest', '~> 6.0'
   spec.add_development_dependency 'rake', '~> 13.4'
-  spec.add_development_dependency 'rubocop', '~> 1.86'
+  spec.add_development_dependency 'rubocop', '~> 1.86', '>= 1.86.2'
   spec.add_development_dependency 'rubocop-minitest', '~> 0.39'
   spec.add_development_dependency 'rubocop-performance', '~> 1.26'
   spec.add_development_dependency 'rubocop-rake', '~> 0.7'
+  spec.add_development_dependency 'rubocop-style-compact_nesting', '~> 0.1'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'steep', '~> 2.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

data/docs/api-reference.md

@@ -0,0 +1,264 @@
+---
+title: API reference
+nav_order: 3
+---
+
+<!-- markdownlint-disable MD013 MD024 -->
+# API reference
+
+This is the hand-written, curated reference for every public symbol
+that ships in `assistant` 1.0.0. The source of truth for stability
+labels is
+[`docs/v1/01-api-surface.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/01-api-surface.md); the table
+of contents here mirrors it.
+
+Anything not listed on this page is **internal** and may change
+without a major version bump.
+
+## Stability labels
+
+- **Frozen** — covered by semver from 1.0.0 onward. Breaking changes
+  require a 2.0.
+- **Experimental** — public but subject to change in a 1.x minor
+  with a deprecation cycle.
+
+## Table of contents
+
+- [`Assistant` module](#assistant-module)
+- [`Assistant::Service`](#assistantservice)
+  - [Class methods](#class-methods)
+  - [Instance methods](#instance-methods)
+  - [Generated per-input methods](#generated-per-input-methods)
+  - [Result shape](#result-shape)
+- [`Assistant::LogItem`](#assistantlogitem)
+- [`Assistant::LogList`](#assistantloglist)
+- [Execute callbacks](#execute-callbacks)
+- [Service composition](#service-composition)
+- [Instrumentation notifier](#instrumentation-notifier)
+- [Input snapshot](#input-snapshot)
+- [`assistant-rbs` CLI](#assistant-rbs-cli)
+- [Semver and deprecation policy](#semver-and-deprecation-policy)
+
+---
+
+## `Assistant` module
+
+| Symbol                          | Stability                | Description                                                                              |
+|---------------------------------|--------------------------|------------------------------------------------------------------------------------------|
+| `Assistant::VERSION`            | Frozen                   | Semver-compliant `String`. Defined in `lib/assistant/version.rb`.                        |
+| `Assistant.notifier`            | Frozen *(new in 1.0)*    | Reader for the instrumentation proc. Defaults to a no-op.                                |
+| `Assistant.notifier=(callable)` | Frozen *(new in 1.0)*    | Writer. Accepts any object responding to `#call(event, payload)`.                        |
+
+See [Instrumentation notifier](#instrumentation-notifier) below for the
+event catalogue.
+
+---
+
+## `Assistant::Service`
+
+Subclass `Assistant::Service` and override `#execute` (and optionally
+`#validate`). Every other method on the table below is provided for
+you.
+
+### Class methods
+
+| Signature                                                                       | Stability | Description                                                                                              |
+|---------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------|
+| `Service.run(**inputs) -> Hash`                                                 | Frozen    | One-shot. Instantiates with `inputs`, calls `#run`, returns the result hash.                             |
+| `Service.input(name, type:, required: false, optional: nil, if: nil, default: nil, allow_nil: false)` | Frozen | Declarative input. `name` is a leading positional symbol; everything else is keyword. See [Inputs](./guides/inputs.md). |
+| `Service.inputs(names, type:, **options)`                                       | Frozen    | Bulk declaration. `names` is an `Array<Symbol>`. Options apply to every input.                           |
+| `Service.before_execute(&block)`                                                | Frozen    | Hook block runs after validation, before `#execute`. `instance_exec`'d on the service.                   |
+| `Service.after_execute(&block)`                                                 | Frozen    | Hook block runs after `#execute` returns; receives the result as the block argument.                     |
+| `Service.around_execute(&block)`                                                | Frozen    | Hook block is `instance_exec`'d with an inner block argument that yields to the next layer.              |
+| `Service.input_snapshot_class -> Class`                                         | Frozen *(new in 1.0)* | Memoised `Data.define(*declared_input_names)` class used by `#input_snapshot`.                |
+
+> **M12 keyword-only sweep.** Every other public DSL helper (e.g.
+> `merge_logs`, all `InputBuilder` internals) takes keyword arguments
+> only. The two exemptions above — `Service.input` and
+> `Service.inputs` — keep their leading positional `name` / `names`
+> because the class-body declaration reads better as
+> `input :email, type: String` than `input name: :email, type: String`.
+
+### Instance methods
+
+| Signature                                          | Stability             | Description                                                                                                                              |
+|----------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `#initialize(**inputs)`                            | Frozen                | Stores `inputs` after applying every `default:`. Does **not** run validation or `#execute`.                                              |
+| `#run -> Hash`                                     | Frozen                | Runs `#validate`, the `before_execute` chain, `#execute` wrapped in `around_execute`, then `after_execute`. Returns the result hash.     |
+| `#result -> Object`                                | Frozen                | Memoised return value of `#execute`. `nil` on failure.                                                                                   |
+| `#success? -> Boolean`                             | Frozen                | True when status is `:ok` or `:with_warnings`.                                                                                           |
+| `#failure? -> Boolean`                             | Frozen                | True when status is `:with_errors`.                                                                                                      |
+| `#status -> Symbol`                                | Frozen                | Exactly one of `:ok`, `:with_warnings`, `:with_errors`.                                                                                  |
+| `#logs -> Array<Assistant::LogItem>`               | Frozen *(new in 1.0)* | All accumulated log items, in the order they were added.                                                                                 |
+| `#infos / #warnings / #errors`                     | Frozen                | Filtered subsets of `#logs`, by level.                                                                                                   |
+| `#call_service(klass, **inputs) -> Service`        | Frozen *(new in 1.0)* | Runs another service, merges its logs into this one, returns the inner instance. Errors on the inner flip this service to `:with_errors`. |
+| `#input_snapshot -> Data`                          | Frozen *(new in 1.0)* | Frozen value object capturing the post-default, post-`allow_nil` inputs. See [Composing services](./guides/composing-services.md).         |
+| `#execute -> Object` (override)                    | Frozen                | Your subclass overrides this. Return value becomes `result:`.                                                                            |
+| `#validate -> void` (override)                     | Frozen                | Optional. Add log items here to short-circuit `#execute`.                                                                                |
+
+### Generated per-input methods
+
+For every `input :name, type: T` declaration, the following are
+generated as instance methods on the service:
+
+| Method                                  | When generated                          | Description                                                                                                |
+|-----------------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------|
+| `#name`                                 | Always                                  | Reader for the post-default value of the input.                                                            |
+| `#name?`                                | Always                                  | Present-and-truthy predicate. Whitespace-only strings are treated as missing.                              |
+| `#valid_type_name? -> Boolean`          | Always                                  | True when `name` matches the declared `type:` (or is one of an `Array` type).                              |
+| `#valid_required_name? -> Boolean`      | When `required: true`                   | True when `name` is present (uses `#name?`). **Canonical name in 1.0.**                                    |
+| `#valid_require_name? -> Boolean`       | When `required: true`                   | **Deprecated in 1.0**, removed in 2.0. Delegates to `#valid_required_name?` with a `Kernel.warn` per call site. |
+| `#valid_required_conditional_name? -> Boolean` | When `required: true` **and** `if:` is supplied | True when the `if:` predicate is truthy **and** `name` is present.                                        |
+| `#valid_require_conditional_name? -> Boolean`  | Same                                  | **Deprecated in 1.0**, removed in 2.0. Delegates with a warning.                                          |
+
+See [`docs/deprecations.md`](./deprecations.md) for the deprecation
+table and migration recipe.
+
+### Result shape
+
+`Service#run` (and therefore `Service.run`) always returns one of two
+hash shapes:
+
+```ruby
+# Success
+{ result: <Object>, status: :ok | :with_warnings, warnings: Array<LogItem> }
+
+# Failure
+{ result: nil, status: :with_errors, errors: Array<LogItem> }
+```
+
+The status enum is exhaustively `:ok`, `:with_warnings`, `:with_errors`.
+No new status values may be added in 1.x without a deprecation cycle.
+
+---
+
+## `Assistant::LogItem`
+
+> **Breaking change in 1.0 (M10).** `LogItem.new` now raises
+> `ArgumentError` when any required attribute is invalid. The
+> `#valid?` family is **retained** for introspection, but in normal
+> flows it always returns `true` after a successful `new`.
+
+| Signature                                                                                | Stability                |
+|------------------------------------------------------------------------------------------|--------------------------|
+| `LogItem.new(level:, source:, detail:, message:, trace: nil)`                            | Frozen *(raises in 1.0)* |
+| `#level / #source / #detail / #message / #trace` — readers                               | Frozen                   |
+| `#info? / #warning? / #error?` — level predicates                                        | Frozen                   |
+| `#valid? / #valid_level? / #valid_source? / #valid_detail? / #valid_message?`            | Frozen                   |
+| `#item -> Hash{Symbol => Object}`                                                        | Frozen                   |
+| `Assistant::LogItem::VALID_LEVELS` — `%i[info warning error]`                            | Frozen                   |
+
+`#level`, `#source`, `#detail` are always `Symbol`; `#message` is
+`String`; `#trace` is `String` or `nil`.
+
+---
+
+## `Assistant::LogList`
+
+Mixin module included in `Assistant::Service`. Users don't normally
+include it themselves; the methods are available on any service
+instance.
+
+| Signature                                                          | Stability                |
+|--------------------------------------------------------------------|--------------------------|
+| `#add_log(level:, source:, detail:, message:, trace: nil)`         | Frozen                   |
+| `#merge_logs(logs:)`                                               | Frozen *(keyword-only in 1.0)* |
+| `#log_item_error_initialize(attr_name:, message:)`                 | Frozen                   |
+| `#log_item_info(source:, detail:, message:, trace: nil)`           | Frozen *(new in 1.0)*    |
+| `#log_item_warning(source:, detail:, message:, trace: nil)`        | Frozen *(new in 1.0)*    |
+| `#log_item_error(source:, detail:, message:, trace: nil)`          | Frozen *(new in 1.0)*    |
+| `#infos / #warnings / #errors -> Array<LogItem>`                   | Frozen                   |
+
+See [Logging and results](./guides/logging-and-results.md) for the
+`log_item_*` shorthands vs. the explicit `add_log` form.
+
+---
+
+## Execute callbacks
+
+New in 1.0. Class-level DSL on `Assistant::Service`; see the table
+under [Class methods](#class-methods).
+
+Hook error semantics: an exception raised inside any `before_execute`,
+`after_execute`, or `around_execute` hook is caught and logged via
+`add_log(level: :error, source: :hook, ...)` — it **never** propagates
+out of `#run`. See [Composing services](./guides/composing-services.md).
+
+---
+
+## Service composition
+
+| Signature                                                  | Stability                |
+|------------------------------------------------------------|--------------------------|
+| `#call_service(klass, **inputs) -> Assistant::Service`     | Frozen *(new in 1.0)*    |
+
+Constructs `klass`, runs it, merges the inner instance's `#logs` into
+the caller's, and returns the inner instance for further inspection.
+If the inner service has any error-level log item, the outer service's
+status becomes `:with_errors`.
+
+---
+
+## Instrumentation notifier
+
+Configured via `Assistant.notifier = ->(event, payload) { ... }`.
+
+Events emitted in 1.0, each with a payload that always carries
+`:service_class` and `:duration_s`:
+
+- `:service_started`
+- `:service_validated`
+- `:service_executed`
+- `:service_failed`
+
+The event set is **Frozen** for 1.0. Adding events requires a minor
+release; removing one or removing a payload key requires a full
+deprecation cycle.
+
+---
+
+## Input snapshot
+
+| Signature                          | Stability                | Description                                                                                                  |
+|------------------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------|
+| `#input_snapshot -> Data`          | Frozen *(new in 1.0)*    | Returns a frozen `Data.define(*declared_input_names).new(**post_default_inputs)`. Reflects post-`default:` / post-`allow_nil:` values. |
+
+The `Data` class is memoised on the service class — repeated calls
+return values whose `class` is `equal?`. See
+[Composing services](./guides/composing-services.md).
+
+---
+
+## `assistant-rbs` CLI
+
+Bundled executable shipped at `exe/assistant-rbs` (M11). Generates
+per-class RBS signatures for `Assistant::Service` subclasses so Steep
+can type-check user code.
+
+| Invocation                                                  | Stability     |
+|-------------------------------------------------------------|---------------|
+| `bundle exec assistant-rbs PATH [--output sig/]`            | Experimental  |
+
+Scans `PATH` for `Assistant::Service` subclasses and emits
+`sig/<class>.rbs` with `def name: () -> Type` and `def name?: () -> bool`
+per declared input. A multi-type `type:` produces a union; `allow_nil:`
+produces a nullable type. The output is idempotent — running twice
+overwrites the same file with the same contents.
+
+Labelled **Experimental** in 1.0 because the output format may evolve
+in 1.x as RBS support for richer types matures.
+
+---
+
+## Semver and deprecation policy
+
+- **Patch (1.0.x)**: bug fixes, doc updates, internal refactors with no
+  observable behaviour change.
+- **Minor (1.x.0)**: additive API only — new `input` options, new
+  `LogItem` predicates, new `Service` hooks. No removals.
+- **Major (2.0.0)**: removals, renames, behaviour changes that break
+  the contract above.
+
+Every deprecated symbol lives for **at least one further minor** after
+its deprecation, with a `Kernel.warn` runtime warning and a row in
+[`docs/deprecations.md`](./deprecations.md).

data/docs/changelog.md

@@ -0,0 +1,26 @@
+---
+title: Changelog
+nav_order: 7
+---
+
+# Changelog
+
+The full release history is in
+[`CHANGELOG.md`](https://github.com/ramongr/assistant/blob/main/CHANGELOG.md)
+at the repository root, formatted per
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+The same file is what `assistant.gemspec` points to via
+`spec.metadata['changelog_uri']`, so RubyGems shows the identical content
+under the gem's **Changelog** tab.
+
+## How to read it
+
+- `[Unreleased]` collects changes that have merged to `main` but have not
+  been cut into a release tag.
+- Each released version uses an ISO date and groups entries by
+  `### Added` / `### Changed` / `### Deprecated` / `### Removed` /
+  `### Fixed` / `### Security`.
+- `### Changed (Breaking)` callouts mark semver-breaking changes; for
+  the 0.x → 1.x sweep, those are catalogued in
+  [`docs/v1/06-migration-0x-to-1.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/06-migration-0x-to-1.md).

data/docs/deprecations.md

@@ -0,0 +1,86 @@
+---
+title: Deprecations
+nav_order: 4
+---
+
+# Deprecations
+
+This page tracks every public symbol that is **deprecated** in a 1.x release
+and the version in which it will be removed. Each entry includes a 1:1
+replacement and the runtime warning users will see.
+
+The deprecation policy is one full minor cycle: anything marked here in
+`1.x` is removed in `2.0`.
+
+## Index
+
+| Symbol                                                  | Replacement                                                       | Deprecated in | Removed in |
+|---------------------------------------------------------|-------------------------------------------------------------------|---------------|------------|
+| `Assistant::Service#valid_require_<name>?`              | `Assistant::Service#valid_required_<name>?`                       | `1.0.0` (M9)  | `2.0.0`    |
+| `Assistant::Service#valid_require_conditional_<name>?`  | `Assistant::Service#valid_required_conditional_<name>?`           | `1.0.0` (M9)  | `2.0.0`    |
+
+---
+
+## `valid_require_<name>?` → `valid_required_<name>?`
+
+**Deprecated in**: `1.0.0` (M9). **Removed in**: `2.0.0`.
+
+### What changed
+
+Per-input requirement validators are now generated under their
+grammatically correct names. For each `input :name, required: true`
+declaration, `Assistant::Service` subclasses gain:
+
+| Canonical (use this)                          | Deprecated alias (still works, warns once per call site) |
+|-----------------------------------------------|----------------------------------------------------------|
+| `#valid_required_<name>?`                     | `#valid_require_<name>?`                                 |
+| `#valid_required_conditional_<name>?`         | `#valid_require_conditional_<name>?`                     |
+
+Both names refer to the same underlying predicate — the deprecated alias
+simply delegates to the canonical method after emitting the deprecation
+warning. Return values, side effects, and `log_item_error_initialize`
+behaviour are unchanged.
+
+### Runtime warning
+
+```text
+assistant: `#valid_require_email?` is deprecated; use `#valid_required_email?` (removed in assistant 2.0)
+```
+
+The warning fires through `Kernel.warn` (i.e. on `$stderr`) **once per
+textual call site** (`caller_locations(1, 1).first` is keyed by `path +
+lineno`). Calling the alias 100 times from the same line yields exactly
+one warning; calling it from two different lines yields two warnings.
+
+Internal framework code (`Service#validate_inputs`) calls only the
+canonical name, so the warning never fires from inside the gem.
+
+### Migration
+
+Search-and-replace at the call site:
+
+```ruby
+# Before
+service.valid_require_email?
+service.valid_require_conditional_token?
+
+# After
+service.valid_required_email?
+service.valid_required_conditional_token?
+```
+
+If your code overrides one of these predicates (`def valid_require_email?
+...`), rename the override to the canonical name. The deprecated alias
+will still exist in `1.x` and will continue to delegate to the canonical
+method, so an override under the old name is silently bypassed.
+
+### Why
+
+Q2 in
+[`docs/v1/07-risks-and-open-questions.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/07-risks-and-open-questions.md)
+was decided in favour of Option B: the new names read better, match
+standard English, and are easier to grep for. The old names live one
+minor cycle to give downstream services an upgrade window.
+
+See [`docs/v1/02-features.md`](https://github.com/ramongr/assistant/blob/main/docs/v1/02-features.md) **M9** for the
+implementation plan and acceptance criteria.

data/docs/examples/cli-handler.md

@@ -0,0 +1,17 @@
+---
+title: CLI handler
+parent: Examples
+nav_order: 2
+---
+
+# CLI handler
+
+> **Status:** placeholder — ships in
+> [P7](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+An `OptionParser`-driven script whose exit code derives from `#status`.
+
+When the runnable script under `examples/cli_handler/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/composing-services.md

@@ -0,0 +1,17 @@
+---
+title: Composing services
+parent: Examples
+nav_order: 4
+---
+
+# Composing services
+
+> **Status:** placeholder — ships in
+> [P9](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+An outer service uses `call_service` to chain two inner services with log timeline merging.
+
+When the runnable script under `examples/composing_services/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/execute-callbacks.md

@@ -0,0 +1,17 @@
+---
+title: Execute callbacks
+parent: Examples
+nav_order: 5
+---
+
+# Execute callbacks
+
+> **Status:** placeholder — ships in
+> [P10](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+`before_execute` audit logger plus an `around_execute` timing wrapper, including failure cases.
+
+When the runnable script under `examples/execute_callbacks/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/index.md

@@ -0,0 +1,29 @@
+---
+title: Examples
+nav_order: 5
+has_children: true
+permalink: /examples/
+---
+
+# Examples
+
+> **Status:** gallery scaffolding — each entry below ships with a
+> runnable script under `examples/<slug>/`, a writeup on this site,
+> and a regression test. See
+> [P6–P12 of the GitHub Pages plan](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example)
+> for the per-example schedule.
+
+| Example | Demonstrates |
+| --- | --- |
+| [Rails service](rails-service.md) | Rails-shaped controller; `case service.run in { result:, status: :ok }`. |
+| [CLI handler](cli-handler.md) | `OptionParser` driving a service; exit code derived from `#status`. |
+| [Sidekiq worker](sidekiq-worker.md) | Worker class that runs a service; idempotent; logs warnings vs errors separately. |
+| [Composing services](composing-services.md) | Outer service uses `call_service` to chain two inner services; log timeline merging. |
+| [Execute callbacks](execute-callbacks.md) | `before_execute` audit logger; `around_execute` timing wrapper; failure cases. |
+| [Instrumentation notifier](instrumentation-notifier.md) | `Assistant.notifier=` wired to a fake `ActiveSupport::Notifications`-shaped sink. |
+| [RBS generator](rbs-generator.md) | Service definition → `bin/assistant-rbs --output sig` → Steep proving per-input return types. |
+
+Each example is intentionally small enough to be read in one sitting.
+Source for every script lives under
+[`examples/`](https://github.com/ramongr/assistant/tree/main/examples)
+in the repository.

data/docs/examples/instrumentation-notifier.md

@@ -0,0 +1,17 @@
+---
+title: Instrumentation notifier
+parent: Examples
+nav_order: 6
+---
+
+# Instrumentation notifier
+
+> **Status:** placeholder — ships in
+> [P11](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+`Assistant.notifier=` wired to a fake `ActiveSupport::Notifications`-shaped sink.
+
+When the runnable script under `examples/instrumentation_notifier/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/rails-service.md

@@ -0,0 +1,17 @@
+---
+title: Rails service
+parent: Examples
+nav_order: 1
+---
+
+# Rails service
+
+> **Status:** placeholder — ships in
+> [P6](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+A Rails-shaped controller calling a service and pattern-matching on the result hash.
+
+When the runnable script under `examples/rails_service/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/rbs-generator.md

@@ -0,0 +1,17 @@
+---
+title: RBS generator
+parent: Examples
+nav_order: 7
+---
+
+# RBS generator
+
+> **Status:** placeholder — ships in
+> [P12](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+Service definition → `bin/assistant-rbs --output sig` → Steep proving the per-input return type.
+
+When the runnable script under `examples/rbs_generator/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.