From 794cbab13fda4836d98dd3775f777642828c2f98 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Sun, 9 Oct 2022 22:56:49 +1100
Subject: [PATCH 01/10] Support Ruby highlighting.

---
 docusaurus.config.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docusaurus.config.js b/docusaurus.config.js
index 092332b..e626b0d 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -126,6 +126,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
+        additionalLanguages: ['ruby'],
       },
     }),
 };

From a8e0daf0b0af654bf91253a9d6668b8b85253e09 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Sun, 9 Oct 2022 23:06:23 +1100
Subject: [PATCH 02/10] Add preliminary drafts.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Includes:

docs
├── intro.md
├── application-structure
│   ├── containers.md
│   ├── providers.md
│   └── slices.md
├── http-handling
│   ├── actions.md
│   ├── rack-middleware.md
│   └── routing.md
---
 docs/application-structure/_category_.json |   8 +
 docs/application-structure/containers.md   | 341 +++++++++++++++++++++
 docs/application-structure/providers.md    | 145 +++++++++
 docs/application-structure/slices.md       |  35 +++
 docs/http-handling/_category_.json         |   8 +
 docs/http-handling/actions.md              |   7 +
 docs/http-handling/rack-middleware.md      |   7 +
 docs/http-handling/routing.md              |  79 +++++
 docs/intro.md                              | 226 ++++++++++++--
 docs/tutorial-basics/_category_.json       |   2 +-
 docs/tutorial-extras/_category_.json       |   2 +-
 docusaurus.config.js                       |   6 +-
 12 files changed, 840 insertions(+), 26 deletions(-)
 create mode 100644 docs/application-structure/_category_.json
 create mode 100644 docs/application-structure/containers.md
 create mode 100644 docs/application-structure/providers.md
 create mode 100644 docs/application-structure/slices.md
 create mode 100644 docs/http-handling/_category_.json
 create mode 100644 docs/http-handling/actions.md
 create mode 100644 docs/http-handling/rack-middleware.md
 create mode 100644 docs/http-handling/routing.md

diff --git a/docs/application-structure/_category_.json b/docs/application-structure/_category_.json
new file mode 100644
index 0000000..6d4c37b
--- /dev/null
+++ b/docs/application-structure/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Application structure",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Organising a Hanami application: containers and dependency injection, providers, and slices."
+  }
+}
diff --git a/docs/application-structure/containers.md b/docs/application-structure/containers.md
new file mode 100644
index 0000000..cb2f711
--- /dev/null
+++ b/docs/application-structure/containers.md
@@ -0,0 +1,341 @@
+---
+sidebar_position: 1
+---
+
+# Containers and dependencies
+
+In Hanami, the application code you add to your `/app` directory is automatically organised into a container. This container forms the basis of a depenency injection system, in which the dependencies of the components you create are provided to them automatically.
+
+Let's take a look at what this means in practice.
+
+Imagine we're building a Bookshelf notifications service responsible for sending notifications to users of the Bookshelf platform, over email and instant message. After running `hanami new notifications_service`, our first task is to send welcome emails. To achieve this, we want to provide a `POST /welcome-emails` action that will send a welcome email via a third-party Acme Email service.
+
+As a first pass, we might add two components to our `/app` folder: an action to handle the POST requests, and a send operation for welcome emails.
+
+Ignoring the content of these classes for now, on the file system, this might look like:
+
+```shell
+app
+├── actions
+│   └── welcome_emails
+│       └── create.rb
+└── emails
+    └── welcome
+        └── operations
+            └── send.rb
+```
+
+When our application boots, Hanami will automatically create instances of these two components and register them in its __app container__, under a key based on their Ruby namespace.
+
+For example, an instance of our `NotificationsService::Emails::Welcome::Operations::Send` class will be registered under the key `"emails.welcome.operations.send"` (since every class in the `/app` folder uses `module NotificationsService` as its top level namespace, that module is excluded from the container key).
+
+```ruby title="app/emails/welcome/operations/send.rb"
+# frozen_string_literal: true
+
+module NotificationService
+  module Emails
+    module Welcome
+      module Operations
+        class Send
+          def call(name:, email_address:)
+            puts "Sending greetings to #{name} via #{email_address}!"
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+We can see this in the Hanami console if we boot our application and ask what keys are registered with the app container:
+
+```ruby
+bundle exec hanami console
+
+notifications_service[development]> Hanami.app.boot
+=> NotificationsService::App
+
+notifications_service[development]> Hanami.app.keys
+=> ["notifications",
+ "settings",
+ "routes",
+ "inflector",
+ "logger",
+ "rack.monitor",
+ "actions.welcome_emails.create",
+ "emails.welcome.operations.send"]
+ ```
+
+To fetch our welcome email send operation from the container, we ask for it by its `"emails.welcome.operations.send"` key:
+
+```ruby
+notifications_service[development]> Hanami.app["emails.welcome.operations.send"]
+=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010df0a1a0>
+
+notifications_service[development]> Hanami.app["emails.welcome.operations.send"].call(name: "New user", email_address: "email@example.com")
+Sending greetings to New user email@example.com!
+=> nil
+```
+
+Most of the time however, you won't use the container directly via `Hanami.app`, but will instead make use of the container through the dependency injection system it supports.
+
+## Dependency injection
+
+Dependency injection is a software pattern where, rather than a component knowing how to instantiate its dependencies, the dependencies are instead provided to it. This means its dependencies can be abstract rather than hard coded, making the component more flexible, reusable and easier to test.
+
+To illustrate, here's an example of a welcome email send operation which _doesn't_ use dependency injection:
+
+```ruby title="app/emails/welcome/operations/send.rb"
+# frozen_string_literal: true
+
+module NotificationsService
+  module Emails
+    module Welcome
+      module Operations
+        class Send
+          def call(name:, email_address:)
+            return unless Hanami::Settings.new.email_sending_enabled
+
+            AcmeEmail::Client.new.deliver(
+              to: email_address,
+              subject: "Welcome!",
+              text_body: "Welcome to Bookshelf #{name}"
+            )
+
+            Hanami::Logger.new.info("Welcome email to #{email_address} queued for delivery")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+This component has three dependencies, each of which is a "hard coded" reference to a concrete Ruby class:
+
+- `Hanami::Settings`, used to check whether email sending is enabled in the current environment.
+- `AcmeEmail::Client`, used to queue the email for delivery via Acme's email service.
+- `Hanami::Logger`, used to log a message that the email has been queued.
+
+To make our send welcome email operation more resuable and easier to test, we could instead _inject_ its three dependencies when we initialize it:
+
+```ruby title="app/emails/welcome/operations/send.rb"
+# frozen_string_literal: true
+
+module NotificationsService
+  module Emails
+    module Welcome
+      module Operations
+        class Send
+          attr_reader :email_client
+          attr_reader :settings
+          attr_reader :logger
+
+          def initialize(email_client:, settings:, logger:)
+            @email_client = email_client
+            @settings = settings
+            @logger = logger
+          end
+
+          def call(name:, email_address:)
+            return unless settings.email_sending_enabled
+
+            email_client.deliver(
+              to: email_address,
+              subject: "Welcome!",
+              text_body: "Welcome to Bookshelf #{name}"
+            )
+
+            logger.info("Welcome email to #{email_address} queued for delivery")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+As a result of injection, our component no longer has rigid dependencies - it's able to use any email client, settings object or logger we provide to it.
+
+Hanami makes this style of dependency injection simple through an `include Deps[]` mechanism. Built into the app container (and all slice containers), `include Deps[]` allows components to use any component in their container as a dependency, while removing the need for any attr_reader or initializer boilerplate:
+
+```ruby title="app/emails/welcome/operations/send.rb"
+# frozen_string_literal: true
+
+module NotificationsService
+  module Emails
+    module Welcome
+      module Operations
+        class Send
+          include Deps["email_client", "logger", "settings"]
+
+          def call(name:, email_address:)
+            return unless settings.email_sending_enabled
+
+            email_client.deliver(
+              to: email_address,
+              subject: "Welcome!",
+              text_body: "Welcome to Bookshelf #{name}"
+            )
+
+            logger.info("Welcome email to #{email_address} queued for delivery")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Injecting dependencies via `include Deps[]`
+
+In the above example the `include Deps[]` mechanism takes each given key and makes the relevant component from the app container available via an instance method of the same name. i.e. `include Deps["logger"]` makes the `logger` registration from the app container available anywhere in the class via the `#logger` method. (`logger` is automatically provided by Hanami).
+
+We can see `include Deps[]` in action in the console if we instantiate an instance of our send welcome email operation:
+
+```ruby
+notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new
+=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010e7b2460
+ @email_client=#<AcmeEmail::Client:0x000000010e7c01f0>,
+ @logger=
+  #<Hanami::Logger:0x000000010e7b82c0
+   @application_name="notifications_service",
+  ...snip...
+ @settings=
+  #<NotificationsService::Settings:0x000000010b7efe58
+   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>>
+```
+
+We can provide different dependencies during initialization:
+
+```ruby
+notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new(logger: "a different logger")
+=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010bc207c0
+ @email_client=#<AcmeEmail::Client:0x000000010ba91f30>,
+ @logger="a different logger",
+ @settings=
+  #<NotificationsService::Settings:0x000000010b7efe58
+   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>>
+```
+
+This behaviour is particularly useful when testing, as you can substitute one or more components to test behaviour.
+
+In this unit test, we substitute all three dependencies in order to unit test our operations behaviour:
+
+```ruby title="spec/unit/emails/welcome/operations/send_spec.rb"
+RSpec.describe NotificationsService::Emails::Welcome::Operations::Send, "#call" do
+  subject(:send) {
+    described_class.new(email_client: email_client, settings: settings, logger: logger)
+  }
+
+  let(:email_client) { double(:email_client) }
+  let(:logger) { double(:logger) }
+
+  context "when email sending is enabled" do
+    let(:settings) { double(:settings, email_sending_enabled: true) }
+
+    it "delivers an email using the email client" do
+      expect(email_client).to receive(:deliver).with(
+        to: "email@example.com",
+        subject: "Welcome!",
+        text_body: "Welcome to Bookshelf Bookshelf user"
+      )
+
+      expect(logger).to receive(:info).with(
+        "Welcome email to email@example.com queued for delivery"
+      )
+
+      send.call(name: "Bookshelf user", email_address: "email@example.com")
+    end
+  end
+
+  context "when email sending is not enabled" do
+    let(:settings) { double(:settings, email_sending_enabled: false) }
+
+    it "does not deliver an email" do
+      expect(email_client).not_to receive(:deliver)
+
+      send.call(name: "Bookshelf user", email_address: "email@example.com")
+    end
+  end
+end
+```
+
+Exactly which dependency to stub using RSpec mocks is up to you - if a depenency is left out of the constructor within the spec, then the real dependency is resolved from the container. Every test can decide exactly which dependencies to replace.
+
+## Renaming dependencies
+
+Sometimes you want to use a dependency under another name (either because two dependencies end with the same suffix, or just because it makes things clearer in a different context).
+
+This can be done with `include Deps[]` like so:
+
+```ruby
+module NotificationsService
+  class NewBookNotification
+    include Deps[
+      "settings",
+      send_email_notification: "emails.book_added.operations.send",
+      send_slack_notification: "slack_notifications.book_added.operations.send"
+    ]
+
+    def call(...)
+      send_email_notification.call(...) if settings.email_sending_enabled
+      send_slack_notification.call(...) if settings.slack_sending_enabled
+    end
+  end
+end
+```
+
+## Opting out of the container
+
+Sometimes it doesn’t make sense for something to be put in the container. For example, Hanami provides a base action class at `app/action.rb` from which all actions inherit. This type of class will never be used as a dependency by anything, and so registering it in the container doesn’t make sense.
+
+For once-off exclusions like this Hanami supports a magic comment: `# auto_register: false`
+
+```ruby title="app/action.rb"
+# auto_register: false
+# frozen_string_literal: true
+
+require "hanami/action"
+
+module NotificationsService
+  class Action < Hanami::Action
+  end
+end
+```
+
+Another alternative for classes you do not want to be registered in your container is to place them in `/lib`.
+
+If you have a whole class of objects that shouldn't be placed in your container, you can configure your Hanami application (or slice) to exclude an entire directory from auto registration by adjusting its `no_auto_register_paths` configuration.
+
+Here for example, the `app/structs` directory is excluded:
+
+```ruby title="config/app.rb"
+# frozen_string_literal: true
+
+require "hanami"
+
+module NotificationsService
+  class App < Hanami::App
+    config.no_auto_register_paths << "structs"
+  end
+end
+```
+
+## Container behaviour: prepare vs boot
+
+Hanami supports a **prepared** state and a **booted** state.
+
+### Hanami.prepare
+
+When you call `Hanami.prepare` (or use `require "hanami/prepare"`) Hanami will make its app and slices available, but components within containers will be **lazily loaded**.
+
+This is useful for minimizing load time. It's the default mode in the Hanami console and when running tests.
+
+It can also be very useful when running Hanami in serverless environments where boot time matters, such as on AWS Lambda, as Hanami will instantiate only the components needed to satisfy a particular web request or operation.
+
+### Hanami.boot
+
+When you call `Hanami.boot` (or use `require "hanami/boot"`) Hanami will go one step further and **eagerly load** all components in all containers up front.
+
+This is useful in contexts where you want to incur initialization costs up front, such as when preparing your application to serve web requests. It's the default when running via Hanami's puma setup (see `config.ru`).
diff --git a/docs/application-structure/providers.md b/docs/application-structure/providers.md
new file mode 100644
index 0000000..dfacbbc
--- /dev/null
+++ b/docs/application-structure/providers.md
@@ -0,0 +1,145 @@
+---
+sidebar_position: 2
+---
+
+# Providers
+
+Providers are a way to register components with your containers, outside of the automatic registration mechanism detailed in [containers and depenencies](/docs/application-structure/containers).
+
+Providers are useful when:
+
+- you need to set up a dependency that requires non-trivial configuration (often a third party library, or some library-like code in your `/lib` directory)
+- you want to take advantage of provider lifecycle methods (prepare, start and stop)
+- you want to share a component across both your app container and the containers of all your [slices](/docs/application-structure/slices).
+
+App-level providers should be placed in the `config/providers` directory. Slices can have their own providers also, placed in `slices/my_slice/providers`.
+
+Here's an example provider for that registers an email client in the app container, using an imagined third-party Acme Email service.
+
+```ruby title="config/providers/email_client.rb"
+# frozen_string_literal: true
+
+Hanami.app.register_provider(:email_client) do
+  prepare do
+    require "acme_email/client"
+  end
+
+  start do
+    client = AcmeEmail::Client.new(
+      api_key: target["settings"].acme_api_key,
+      default_from: "no-reply@bookshelf.example.com"
+    )
+
+    register "email_client", client
+  end
+end
+```
+
+The above provider initializes an instance of Acme's email client, providing an api key from the application's setting as well as a default from address, then registers the client in the app container with the key `"email_client"`.
+
+The registered dependency can now be used in app components, via `include Deps["email_client"]`:
+
+```ruby title="app/emails/welcome/operations/send.rb"
+# frozen_string_literal: true
+
+module NotificationsService
+  module Emails
+    module Welcome
+      module Operations
+        class Send
+          include Deps["email_client", "settings"]
+
+          def call(name:, email_address:)
+            return unless settings.email_sending_enabled
+
+            email_client.deliver(
+              to: email_address,
+              subject: "Welcome!",
+              text_body: "Welcome to Bookshelf #{name}"
+            )
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Every provider has a name (`Hanami.app.register_provider(:my_provider_name)`) and registers _one or more_ related components with the relevant container. Registered items are not limited to objects - they can be classes too.
+
+```ruby title="config/providers/something_provider.rb"
+# frozen_string_literal: true
+
+Hanami.app.register_provider(:something_provider) do
+  start do
+    register "something", Something.new
+    register "another.thing", AnotherThing.new
+    register "thing", Thing
+  end
+end
+```
+
+## Provider lifecycle
+
+Providers offer a three-stage lifecycle: `prepare`, `start`, and `stop`. Each has a distinct purpose:
+
+- prepare - basic setup code, here you can require 3rd party code and perform basic configuration
+- start - code that needs to run for a component to be usable at runtime
+- stop - code that needs to run to stop a component, perhaps to close a database connection, or purge some artifacts.
+
+```ruby title="config/providers/database.rb"
+Hanami.app.register_provider(:database) do
+  prepare do
+    require "3rd_party/db"
+
+    register "database", 3rdParty::DB.configure(target["settings"].database_url)
+  end
+
+  start do
+    target["database"].establish_connection
+  end
+
+  stop do
+    target["database"].close_connection
+  end
+end
+```
+
+Lifecycle steps will not run until a provider is required by another component, is started directly, or when the container finalizes as a result of Hanami booting.
+
+`Hanami.boot` and `Hanami.shutdown` call `start` and `stop` respectively on each of the application’s registered providers.
+
+Lifecycle transitions can be triggered directly by using `Hanami.app.container.prepare(:provider_name)`, `Hanami.app.container.start(:provider_name)` and `Hanami.app.container.stop(:provider_name)`.
+
+## Accessing the container via `#target`
+
+Within a provider, the `target` method (also available as `target_container`) can be used to access the container (either the app container, or, if the provider is specific to a slice, the slice's container).
+
+This is useful for accessing the application's settings or logger (via `target["settings]` and `target["logger"]`). It can also be used when a provider wants to ensure another provider has started before starting itself, via `target.start(:provider_name)`:
+
+```ruby title="config/providers/uploads_bucket"
+Hanami.app.register_provider(:uploads_bucket) do
+  prepare do
+    require "aws-sdk-s3"
+  end
+
+  start do
+    target.start(:metrics)
+
+    uploads_bucket_name = target["settings"].uploads_bucket_name
+
+    credentials = Aws::Credentials.new(
+      target["settings"].aws_access_key_id,
+      target["settings"].aws_secret_access_key,
+    )
+
+    uploads_bucket = Aws::S3::Resource.new(credentials: credentials).bucket(uploads_bucket_name)
+
+    register "uploads_bucket", uploads_bucket
+  end
+end
+```
+
+## Default providers
+
+Hanami ships with several providers. TODO.
diff --git a/docs/application-structure/slices.md b/docs/application-structure/slices.md
new file mode 100644
index 0000000..b7a9862
--- /dev/null
+++ b/docs/application-structure/slices.md
@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+---
+
+# Slices
+
+In addition to the `/app` directory, Hanami also supports organising your application code into **slices**.
+
+You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or by feature concern (api or search).
+
+Slices live in the `/slices` directory.
+
+To create a slice, you can either create a new directory in `/slices`:
+
+```ruby
+mkdir -p slices/admin
+
+bundle exec hanami console
+Admin::Slice
+=> Admin::Slice
+```
+
+Or run `bundle exec hanami generate slice api`, which has the added benefit of adding some slice-specific classes, like actions:
+
+```shell
+bundle exec hanami generate slice api
+
+slices
+└── api
+    ├── action.rb
+    └── actions
+```
+
+
+TODO - the rest of slices :)
diff --git a/docs/http-handling/_category_.json b/docs/http-handling/_category_.json
new file mode 100644
index 0000000..7b95667
--- /dev/null
+++ b/docs/http-handling/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "HTTP handling",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Routing, actions and middlewares."
+  }
+}
diff --git a/docs/http-handling/actions.md b/docs/http-handling/actions.md
new file mode 100644
index 0000000..c5fccd6
--- /dev/null
+++ b/docs/http-handling/actions.md
@@ -0,0 +1,7 @@
+---
+sidebar_position: 2
+---
+
+# Actions
+
+Hello from actions
diff --git a/docs/http-handling/rack-middleware.md b/docs/http-handling/rack-middleware.md
new file mode 100644
index 0000000..1b95ba0
--- /dev/null
+++ b/docs/http-handling/rack-middleware.md
@@ -0,0 +1,7 @@
+---
+sidebar_position: 3
+---
+
+# Rack middleware
+
+Rack middleware
diff --git a/docs/http-handling/routing.md b/docs/http-handling/routing.md
new file mode 100644
index 0000000..f485f44
--- /dev/null
+++ b/docs/http-handling/routing.md
@@ -0,0 +1,79 @@
+---
+sidebar_position: 1
+---
+
+# Routing
+
+Hanami provides a fast, simple router for handling http requests.
+
+To add a route to your application, define it in your `Routes` class in the `config/routes.rb` file.
+
+If you ran `hanami new bookshelf`, your `config/routes.rb` file will look like this:
+
+```ruby title="config/routes.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    root { "Hello from Hanami" }
+  end
+end
+```
+
+## Composing a route
+
+In the Hanami router, each route is comprised of:
+- a HTTP method (i.e. `get`, `post`, `put`, `patch`, `delete`, `options` or `trace`)
+- a path
+- an endpoint to be invoked.
+
+Endpoints are usually actions within your application, but they can also be a block, a rack application, or anything that responds to `#call`.
+
+```ruby title="Example routes"
+get "/authors", to: "authors.index"
+get "/authors/:id", to: "authors.show"
+post "/authors", to: "authors.create"
+put "/authors/:id", to: "authors.update"
+get "/rack-app", to: RackApp.new
+```
+
+A root method defines a root route for handling GET requests to "/". Above, the root path calls a block which returns "Hello from Hanami". You can also invoke an action for root requests by specifying `root to: "my_action"`. For example to invoke a `"home"` action:
+
+```ruby title="config/routes.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    root to: "home"
+  end
+end
+```
+
+Let's add three routes to our bookshelf application: one for listing an index of books, one for showing a particular book, and one for creating a new book.
+
+[Actually, let's add full set of CRUD here to show that off]
+
+```ruby title="config/routes.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    root to: "home"
+
+    get "/books", to: "books.index"
+    get "/books/:id", to: "books.show"
+    post "/books", to: "books.create"
+  end
+end
+```
+
+Hanami provides a `hanami routes` command to inspect your application's routes. Let's run `bundle exec hanami routes` on the command line after adding our new routes:
+
+```shell title="bundle exec hanami routes"
+GET     /                             home                          as :root
+GET     /books                        books.index
+GET     /books/:id                    books.show
+POST    /books                        books.create
+```
+
+TODO: the rest of routing :)
diff --git a/docs/intro.md b/docs/intro.md
index c135225..00e646d 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -1,47 +1,231 @@
 ---
 sidebar_position: 1
+title: Getting started
+description: Getting started with Hanami 2
 ---
 
-# Hanami Tutorial
+# Getting started
 
-Let's discover **Docusaurus in less than 5 minutes**.
+Hanami is a Ruby framework designed to create software that is well-architected, maintainable and a pleasure to work on.
 
-## Getting Started
+These guides aim to introduce you to the Hanami framework and demonstrate how its components fit together to produce a coherent application.
 
-Get started by **creating a new site**.
+Ideally, you already have some familiarity with web applications and the [Ruby language](https://www.ruby-lang.org/en/).
 
-Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
+:::tip Hanami 2.0 is beta software
 
-### What you'll need
+Hanami 2 currently beta software. If you encounter an issue with these guides, please raise an issue or contribute a correction on our guides repository. If you encounter what you think is a bug with Hanami, please raise an issue on the [Hanami repository](https://github.com/hanami/hanami).
 
-- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+:::
 
-## Generate a new site
+## Creating a Hanami application
 
-Generate a new Docusaurus site using the **classic template**.
+### Prerequisites
 
-The classic template will automatically be added to your project after you run the command:
+To create a Hanami application, you will need Ruby 3.0 or greater. Check your ruby version:
 
 ```bash
-npm init docusaurus@latest my-website classic
+ruby --version
 ```
 
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+If you need to install Ruby, follow with the instructions on [rubylang.org](https://www.ruby-lang.org/en/documentation/installation/).
 
-The command also installs all necessary dependencies you need to run Docusaurus.
+### Installing the gem
 
-## Start your site
+In order to create a Hanami application, first install the hanami gem:
 
-Run the development server:
+```bash
+gem install hanami --pre
+```
+
+### Generating your first application
+
+Hanami provides a `hanami new` command for generating a new application. Let's use it to create a new application called "bookshelf":
 
 ```bash
-cd my-website
-npm run start
+hanami new bookshelf
+```
+
+Here's what was generated for us:
+
+```shell title="Generated files"
+cd bookshelf
+tree .
+.
+├── Gemfile
+├── Gemfile.lock
+├── Guardfile
+├── README.md
+├── Rakefile
+├── app
+│   ├── action.rb
+│   └── actions
+├── config
+│   ├── app.rb
+│   ├── puma.rb
+│   ├── routes.rb
+│   └── settings.rb
+├── config.ru
+├── lib
+│   ├── bookshelf
+│   │   └── types.rb
+│   └── tasks
+└── spec
+    ├── requests
+    │   └── root_spec.rb
+    ├── spec_helper.rb
+    └── support
+        ├── requests.rb
+        └── rspec.rb
+
+9 directories, 16 files
+```
+
+As you can see, a new Hanami application has just 16 files in total. We'll look at each file as this guide progresses but for now let's get our new application running.
+
+In the bookshelf directory, run:
+
+```shell
+hanami server
+```
+
+If all has gone well, you should see this output:
+
+```
+Puma starting in single mode...
+* Puma version: 5.6.5
+*  Min threads: 0
+*  Max threads: 5
+*  Environment: development
+*          PID: 31634
+* Listening on http://0.0.0.0:2300
+Use Ctrl-C to stop
+```
+
+Visit your application in the browser at [http://localhost:2300](http://localhost:2300)
+
+```
+open http://localhost:2300
+```
+
+You should see "Hello from Hanami"!
+
+:::tip A note on bundle install
+
+You may have noticed that we did not run `bundle install` before starting our server. That's because the `hanami new` command runs `bundle install` for you. To opt out of this behaviour, run `hanami new --skip-bundle`. See `hanami new --help` for more options.
+
+:::
+
+
+## Anatomy of a generated application
+
+Before we add our first functionality, let's take a brief look at some of the key files in your freshly generated application.
+
+### The `App` class
+
+As we'll explore in this guide, `config/app.rb` defines the `App` class - the core of your application.
+
+```ruby title="config/app.rb"
+# frozen_string_literal: true
+
+require "hanami"
+
+module Bookshelf
+  class App < Hanami::App
+  end
+end
+```
+
+This class allows you to configure application-level behaviours, while also providing a way to do things like booting your application, or starting or stopping your application's [providers](/docs/application-structure/providers).
+
+It's also the interface some core components, such as your application's settings, via `Hanami.app["settings"]`, and its logger, via `Hanami.app["logger"]`.
+
+Read more about [Hanami's app class](#).
+
+### Routes
+
+Your application's routes are defined using the `Routes` class in `config/routes.rb`.
+
+```ruby title="config/routes.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    root { "Hello from Hanami" }
+
+    get "/books/:id", to: "books.show"
+  end
+end
+```
+
+Routes in Hanami most commonly invoke what Hanami calls actions. For example, with the routes configuration above, a GET request to `/books/1` will call a `"books.show"` action, defined in your application's `app/actions` folder:
+
+```ruby title="app/actions/books/show.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  module Actions
+    module Books
+      class Show < Bookshelf::Action
+        def handle(request, response)
+          # Show the book specified by request.params[:id] here
+        end
+      end
+    end
+  end
+end
+```
+
+Read more about routes an actions in [HTTP handling](/docs/category/http-handling).
+
+### Settings
+
+Hanami provides a `Settings` class where you can define the custom settings that your application needs.
+
+```ruby title="config/settings.rb"
+# frozen_string_literal: true
+
+require "bookshelf/types"
+
+module Bookshelf
+  class Settings < Hanami::Settings
+    # Define your app settings here, for example:
+    #
+    setting :my_flag, default: false, constructor: Types::Params::Bool
+  end
+end
+```
+
+Settings read from the environment (i.e. the `my_flag` setting above takes its value from the `MY_FLAG` environment variable), and are available either through `Hanami.app["settings"]` or by injecting the `"settings"` component via Hanami's dependency injection mechanism (see [Dependency injection](#)).
+
+A **default** and a **constructor** can be optionally specified for each setting. The `Types::Params::Bool` constructor above will coerce any value found in the `MY_FLAG` environment variable into a boolean value. And because of the `default: false` argument, if the `MY_FLAG` environment variable is absent, `my_flag` will be `false`.
+
+This means that you can trust `Hanami.app["settings"].my_flag` to always return a boolean.
+
+Read more about [Hanami's settings](#).
+
+
+## Commands
+
+Hanami ships with useful commands for things like starting a console, inspecting routes and generating code.
+
+To list available commands, run:
+
+```shell
+bundle exec hanami --help
+
+Commands:
+  hanami console                              # App REPL
+  hanami generate [SUBCOMMAND]
+  hanami install
+  hanami middlewares                          # List all the registered middlewares
+  hanami routes                               # Inspect application
+  hanami server                               # Start Hanami server
+  hanami version
 ```
 
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+We'll see most of these commands at play in this guide. For complete information on these commands, see the [Hanami reference](#).
 
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+## What's next?
 
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+Now that we're a little acquainted, let's examine the structure of a Hanami application in more detail through [containers, providers and slices](/docs/category/application-structure).
diff --git a/docs/tutorial-basics/_category_.json b/docs/tutorial-basics/_category_.json
index 2e6db55..192f1ee 100644
--- a/docs/tutorial-basics/_category_.json
+++ b/docs/tutorial-basics/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Tutorial - Basics",
-  "position": 2,
+  "position": 4,
   "link": {
     "type": "generated-index",
     "description": "5 minutes to learn the most important Docusaurus concepts."
diff --git a/docs/tutorial-extras/_category_.json b/docs/tutorial-extras/_category_.json
index a8ffcc1..7378048 100644
--- a/docs/tutorial-extras/_category_.json
+++ b/docs/tutorial-extras/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Tutorial - Extras",
-  "position": 3,
+  "position": 5,
   "link": {
     "type": "generated-index"
   }
diff --git a/docusaurus.config.js b/docusaurus.config.js
index e626b0d..b57de0c 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -68,9 +68,9 @@ const config = {
             type: 'doc',
             docId: 'intro',
             position: 'left',
-            label: 'Tutorial',
+            label: 'Guides',
           },
-          {to: '/blog', label: 'Blog', position: 'left'},
+          {to: '/blog', label: 'Reference', position: 'left'},
           {
             href: 'https://github.com/hanami/hanami',
             label: 'GitHub',
@@ -85,7 +85,7 @@ const config = {
             title: 'Docs',
             items: [
               {
-                label: 'Tutorial',
+                label: 'Guides',
                 to: '/docs/intro',
               },
             ],

From 5e4cc74422b9d72e933ab23a11ac61ab2a1c2460 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Sun, 9 Oct 2022 23:11:57 +1100
Subject: [PATCH 03/10] Remove docusaurus tutorials.

---
 docs/tutorial-basics/_category_.json          |   8 -
 docs/tutorial-basics/congratulations.md       |  23 ---
 docs/tutorial-basics/create-a-blog-post.md    |  34 ----
 docs/tutorial-basics/create-a-document.md     |  57 -------
 docs/tutorial-basics/create-a-page.md         |  43 ------
 docs/tutorial-basics/deploy-your-site.md      |  31 ----
 docs/tutorial-basics/markdown-features.mdx    | 146 ------------------
 docs/tutorial-extras/_category_.json          |   7 -
 .../img/docsVersionDropdown.png               | Bin 25427 -> 0 bytes
 docs/tutorial-extras/img/localeDropdown.png   | Bin 27841 -> 0 bytes
 docs/tutorial-extras/manage-docs-versions.md  |  55 -------
 docs/tutorial-extras/translate-your-site.md   |  88 -----------
 12 files changed, 492 deletions(-)
 delete mode 100644 docs/tutorial-basics/_category_.json
 delete mode 100644 docs/tutorial-basics/congratulations.md
 delete mode 100644 docs/tutorial-basics/create-a-blog-post.md
 delete mode 100644 docs/tutorial-basics/create-a-document.md
 delete mode 100644 docs/tutorial-basics/create-a-page.md
 delete mode 100644 docs/tutorial-basics/deploy-your-site.md
 delete mode 100644 docs/tutorial-basics/markdown-features.mdx
 delete mode 100644 docs/tutorial-extras/_category_.json
 delete mode 100644 docs/tutorial-extras/img/docsVersionDropdown.png
 delete mode 100644 docs/tutorial-extras/img/localeDropdown.png
 delete mode 100644 docs/tutorial-extras/manage-docs-versions.md
 delete mode 100644 docs/tutorial-extras/translate-your-site.md

diff --git a/docs/tutorial-basics/_category_.json b/docs/tutorial-basics/_category_.json
deleted file mode 100644
index 192f1ee..0000000
--- a/docs/tutorial-basics/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "label": "Tutorial - Basics",
-  "position": 4,
-  "link": {
-    "type": "generated-index",
-    "description": "5 minutes to learn the most important Docusaurus concepts."
-  }
-}
diff --git a/docs/tutorial-basics/congratulations.md b/docs/tutorial-basics/congratulations.md
deleted file mode 100644
index 04771a0..0000000
--- a/docs/tutorial-basics/congratulations.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_position: 6
----
-
-# Congratulations!
-
-You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
-
-Docusaurus has **much more to offer**!
-
-Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
-
-Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
-
-## What's next?
-
-- Read the [official documentation](https://docusaurus.io/)
-- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
-- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
-- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
-- Add a [search bar](https://docusaurus.io/docs/search)
-- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
-- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)
diff --git a/docs/tutorial-basics/create-a-blog-post.md b/docs/tutorial-basics/create-a-blog-post.md
deleted file mode 100644
index ea472bb..0000000
--- a/docs/tutorial-basics/create-a-blog-post.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-sidebar_position: 3
----
-
-# Create a Blog Post
-
-Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
-
-## Create your first Post
-
-Create a file at `blog/2021-02-28-greetings.md`:
-
-```md title="blog/2021-02-28-greetings.md"
----
-slug: greetings
-title: Greetings!
-authors:
-  - name: Joel Marcey
-    title: Co-creator of Docusaurus 1
-    url: https://github.com/JoelMarcey
-    image_url: https://github.com/JoelMarcey.png
-  - name: Sébastien Lorber
-    title: Docusaurus maintainer
-    url: https://sebastienlorber.com
-    image_url: https://github.com/slorber.png
-tags: [greetings]
----
-
-Congratulations, you have made your first post!
-
-Feel free to play around and edit this post as much you like.
-```
-
-A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).
diff --git a/docs/tutorial-basics/create-a-document.md b/docs/tutorial-basics/create-a-document.md
deleted file mode 100644
index ffddfa8..0000000
--- a/docs/tutorial-basics/create-a-document.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-sidebar_position: 2
----
-
-# Create a Document
-
-Documents are **groups of pages** connected through:
-
-- a **sidebar**
-- **previous/next navigation**
-- **versioning**
-
-## Create your first Doc
-
-Create a Markdown file at `docs/hello.md`:
-
-```md title="docs/hello.md"
-# Hello
-
-This is my **first Docusaurus document**!
-```
-
-A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).
-
-## Configure the Sidebar
-
-Docusaurus automatically **creates a sidebar** from the `docs` folder.
-
-Add metadata to customize the sidebar label and position:
-
-```md title="docs/hello.md" {1-4}
----
-sidebar_label: 'Hi!'
-sidebar_position: 3
----
-
-# Hello
-
-This is my **first Docusaurus document**!
-```
-
-It is also possible to create your sidebar explicitly in `sidebars.js`:
-
-```js title="sidebars.js"
-module.exports = {
-  tutorialSidebar: [
-    'intro',
-    // highlight-next-line
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-};
-```
diff --git a/docs/tutorial-basics/create-a-page.md b/docs/tutorial-basics/create-a-page.md
deleted file mode 100644
index 20e2ac3..0000000
--- a/docs/tutorial-basics/create-a-page.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-sidebar_position: 1
----
-
-# Create a Page
-
-Add **Markdown or React** files to `src/pages` to create a **standalone page**:
-
-- `src/pages/index.js` → `localhost:3000/`
-- `src/pages/foo.md` → `localhost:3000/foo`
-- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
-
-## Create your first React Page
-
-Create a file at `src/pages/my-react-page.js`:
-
-```jsx title="src/pages/my-react-page.js"
-import React from 'react';
-import Layout from '@theme/Layout';
-
-export default function MyReactPage() {
-  return (
-    <Layout>
-      <h1>My React page</h1>
-      <p>This is a React page</p>
-    </Layout>
-  );
-}
-```
-
-A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).
-
-## Create your first Markdown Page
-
-Create a file at `src/pages/my-markdown-page.md`:
-
-```mdx title="src/pages/my-markdown-page.md"
-# My Markdown page
-
-This is a Markdown page
-```
-
-A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).
diff --git a/docs/tutorial-basics/deploy-your-site.md b/docs/tutorial-basics/deploy-your-site.md
deleted file mode 100644
index 1c50ee0..0000000
--- a/docs/tutorial-basics/deploy-your-site.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-sidebar_position: 5
----
-
-# Deploy your site
-
-Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
-
-It builds your site as simple **static HTML, JavaScript and CSS files**.
-
-## Build your site
-
-Build your site **for production**:
-
-```bash
-npm run build
-```
-
-The static files are generated in the `build` folder.
-
-## Deploy your site
-
-Test your production build locally:
-
-```bash
-npm run serve
-```
-
-The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).
-
-You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).
diff --git a/docs/tutorial-basics/markdown-features.mdx b/docs/tutorial-basics/markdown-features.mdx
deleted file mode 100644
index 6b3aaaa..0000000
--- a/docs/tutorial-basics/markdown-features.mdx
+++ /dev/null
@@ -1,146 +0,0 @@
----
-sidebar_position: 4
----
-
-# Markdown Features
-
-Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
-
-## Front Matter
-
-Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
-
-```text title="my-doc.md"
-// highlight-start
----
-id: my-doc-id
-title: My document title
-description: My document description
-slug: /my-custom-url
----
-// highlight-end
-
-## Markdown heading
-
-Markdown text with [links](./hello.md)
-```
-
-## Links
-
-Regular Markdown links are supported, using url paths or relative file paths.
-
-```md
-Let's see how to [Create a page](/create-a-page).
-```
-
-```md
-Let's see how to [Create a page](./create-a-page.md).
-```
-
-**Result:** Let's see how to [Create a page](./create-a-page.md).
-
-## Images
-
-Regular Markdown images are supported.
-
-You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
-
-```md
-![Docusaurus logo](/img/docusaurus.png)
-```
-
-![Docusaurus logo](/img/docusaurus.png)
-
-You can reference images relative to the current file as well, as shown in [the extra guides](../tutorial-extras/manage-docs-versions.md).
-
-## Code Blocks
-
-Markdown code blocks are supported with Syntax highlighting.
-
-    ```jsx title="src/components/HelloDocusaurus.js"
-    function HelloDocusaurus() {
-        return (
-            <h1>Hello, Docusaurus!</h1>
-        )
-    }
-    ```
-
-```jsx title="src/components/HelloDocusaurus.js"
-function HelloDocusaurus() {
-  return <h1>Hello, Docusaurus!</h1>;
-}
-```
-
-## Admonitions
-
-Docusaurus has a special syntax to create admonitions and callouts:
-
-    :::tip My tip
-
-    Use this awesome feature option
-
-    :::
-
-    :::danger Take care
-
-    This action is dangerous
-
-    :::
-
-:::tip My tip
-
-Use this awesome feature option
-
-:::
-
-:::danger Take care
-
-This action is dangerous
-
-:::
-
-## MDX and React Components
-
-[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
-
-```jsx
-export const Highlight = ({children, color}) => (
-  <span
-    style={{
-      backgroundColor: color,
-      borderRadius: '20px',
-      color: '#fff',
-      padding: '10px',
-      cursor: 'pointer',
-    }}
-    onClick={() => {
-      alert(`You clicked the color ${color} with label ${children}`)
-    }}>
-    {children}
-  </span>
-);
-
-This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
-
-This is <Highlight color="#1877F2">Facebook blue</Highlight> !
-```
-
-export const Highlight = ({children, color}) => (
-  <span
-    style={{
-      backgroundColor: color,
-      borderRadius: '20px',
-      color: '#fff',
-      padding: '10px',
-      cursor: 'pointer',
-    }}
-    onClick={() => {
-      alert(`You clicked the color ${color} with label ${children}`);
-    }}>
-    {children}
-  </span>
-);
-
-This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
-
-This is <Highlight color="#1877F2">Facebook blue</Highlight> !
diff --git a/docs/tutorial-extras/_category_.json b/docs/tutorial-extras/_category_.json
deleted file mode 100644
index 7378048..0000000
--- a/docs/tutorial-extras/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "label": "Tutorial - Extras",
-  "position": 5,
-  "link": {
-    "type": "generated-index"
-  }
-}
diff --git a/docs/tutorial-extras/img/docsVersionDropdown.png b/docs/tutorial-extras/img/docsVersionDropdown.png
deleted file mode 100644
index 97e4164618b5f8beda34cfa699720aba0ad2e342..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 25427
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
C*H>)-

diff --git a/docs/tutorial-extras/img/localeDropdown.png b/docs/tutorial-extras/img/localeDropdown.png
deleted file mode 100644
index e257edc1f932985396bf59584c7ccfaddf955779..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 27841
zcmXt9WmFtZ(*=S%B)EHUciG??+-=biEVw%f7J?HT77G@f5ZpbB1Pku&vgoqxemw6v
z-;X&{JzZV*cFmohnLgcd+M3FE*p%2vNJx09Dhj$tNXVWq2M^|}mn)^e9a~;bs1CC4
zWs#5?l5k+wXfI`CFI{Chq}oa9BP66(NZK0uiU<Va8ghMo4S9ZkM!*qpIQ+lT^)=$f
ze5ty=x_YtUaM<(n_0@lc7ni3e*h}5z<s}3HxwyEvy}i4+xj8#OheDxucX#Li8IK6~
zGvpd_e}Df1`ta~@{o;BBd3d;g@j*O4pPZaLzW_mAqCKCUo<eRQR@Qd#XZXqS@e2kO
zHQoKg{YwKF4EFf=`1}mNdI7$I+}+)rot+&YAD^9`-Q3>1Kwn&3K0m`=xIMoxdVZ#+
zp?hKSLSSimjhdEzWp#6Tbpr;2A08YY9vwczVR!d;r)Q^kw|6h$pbt<ATKe^k?Q6)@
z!vpl<^707^y}G=d`?m;tg5E$Nm)F<4Q3kN*r`www*b@x;1bsoey1G2SxIjE3rf28p
z7nW}C?q2x7o}TXSA08hb9$$>RyO;c2US2)Ho=#3q?{4m1GWOCI`k&9;zl9YD<mU3?
z>hH|l{oVck{{HdF$xGeh(%RX@ITa1V-QE4arPZ_3^N0KUo15FS^Rt74gNyU?f6HsD
z>zmu#+n1LY=NIRf7Z*oIN2_aF7nc`%dwaXPyVf>#Q`56+>svGPi|1!&J3Bj8*0u|a
zE61nDOKTge8(T{&>(jIU{?5$PF)%N#t}iaHQc%;Ky=4F7L{Hzy*Vp$Mj`%zGZ+7k<
zCpRC^+V1HYCi6}{?rS`Ew80CL%d5-LF)(<1lJAQ_QE}<r-R;2O&=myI+t<IbvBAQ|
z;pyeAsjb7uFQlrb!5?L?y0#G%657z%q@bjdnwCB^GUn{^iJY8VAjYVxtEai8^@GF5
z#H3^l42+ZW)0f;$OwHux7hFNE!XrM*C)rd~{j902Gd4BX{O;^f9Ew0Z6A=*$i->I<
z?$m+XE%JR|)Y|g5*Z=3YjLfXkvht|tSaC_|$oh1*A78S&%grr-Q|oi0ai*n%^?I3Z
zz4If<tssFf1}{2-!JzY7%RFBUMwcfG%1SXuC|@2BdL&f^S$+TIQ`4^alSL9Ta|^}@
zbUPx<XondzYjOiQ$2z5n-pHJ6?r}|Pt|(UxD|e#iS3IxGO0$J7c=>n)p1zW0ShuJU
zjT*W!;4n<s#y``|?fOlAcX{-Z`WADVJKfB!eqWvxG<7fDKFr?IbG4rVZ;+Pmk`7U~
zaMRK<gDtl9J-4`Nxlsg~Js+jHQMg>~Y)3m5E=4m0n9;cN(k*j`y5!~j2)ij4x1#tx
zB&it>z`(yY6BF>DU9?)rvOb2G!4AbPa`$!ju_}{}N=X3%ljy@XN?Dz5W~L8#vn;(%
zS0y`!_FK8bT{5iuza9iPzyFntcC0hEUgCyxwZgrs_lXv54ZHujy!d4_U`~v!&Xq6w
z_%CfMkDLt!D3SDYg>XEZ!YJH*s~-dg$LmS&Mt_;Y7X9a!>IDr+ded%2&q%}2^ODhk
z<X4v_V#}leiEcjrMX_PEtszSVVeU}7)vCvE!A=QJH@<yB^Se^pj+w8!Qtm7{Y(Gx?
zdCu-jab+xEVmFSP&DATzjO~u?3yNnRbUYzOHXjR4#B`zfNyciknfQs}!O(}<!=|_s
zCh+eJr4dsFfev@A_T*PM{hN=p!>oJMHe1;<*D7+WnelW=pb#;#*9m22_D0Uy+B;{x
z(r=4T(e9>b$HL=1ZhtTnMZ8m?T*4WlE1nANJoY~M+S`a~oAzPxq?IY|K;|faC(Qf6
z6st=g2Oa&+>GJF*AU5<{Q1pIIjk9IOz}i1XThs0R)dBg}u}I!L^(JejuqE{$Bx0WH
zK_L%2hekVKCo%({=C&4>8XPbm?HVjtj7;pR;Nl%bO7u_%gfl5w5S;(8b>qCb9KY=2
zcH1B8#T*pZQMR+_zF|mDvyu5p%arE^>?K|9F#FDuJCyu6$KPjjPBMq7j0f$|h@y<y
zr~eg->!QXH+UdeH3iv*9ArYX^V-S2rxolaBRROkUH4!AxVghY-$mqUuOg%w5X}J1K
z3LIKED&GtI+|Bu|l2Og<cykmF%8H?iJoG-Dsn<C-@u=lNCO8{E``i%f*#$O+>JXS@
z##5m-UU-??q5BVBs3e%jt&;*!MXilSO_r%{gmW&qj$2WWx8M1Us?Tzp=Of?r=^y=m
zDDr>5Z2+yUUf9O3Kqm?KxT9VJX#G6EP&E+e7EkxJF5QqcBPy@TsIFiD!!LWKz2ftR
za<|^DinsXw>aBe|0DWOEi#5cV&B>!$<?5R^*N2ReZe+_vtl-jzH`Hw**9+Y6x2qon
zyG!euyFY+`S=hCB!c!WT!g0hxVoJ2)gM}8-%wRgL&1%3u@PLIH8?TwvIZx8S2ygI?
z%u#z>i8?+vTr3ZDMK}XFeg)Ime5=*V++LLjj6sSf>5d+I|6V|cU`LfQPC<oXTcPwJ
z$%euIb)kCcR(Twq48r1}_I8h2Uu||Pj})tBgMe$-I1YT=ud(vkc22ES4K=QiwBqe>
z;p|(TN|j&~8CO`*<Hd;RLMG1QlgwuK!7NTCZ9nyw>qIi<o9m>-79281;uL=cj-kt$
zx5MwWh>2LRlqjdUEGgk)P@$`Rs3-3sSlqxdxpG@!K`;a)V2m#wvau8$FIZuT9T00v
znI8L>LHCkAZsu+5PUedUKs5fY2Ehv7Lqr}Ue$h;p6jBeeweEDUn2p#fwkvxk%Z<-6
zlgcD$>a-9H1#>^}Ku>>wLa`FkP^$V?ys$YQ&1L$o#0R}|{e?+I{K?~0CPz_*Bh#mo
zh#!|PeV|ebfXa=JD#~>$?!*)i)b@eZZ`$qTk#-n$b{Cnhx2wH9N;PkqOwfS5FPe4A
z!^5G+7=f|QUkN8gZmRRF-gxA&%`!7|F<Oq0ByFvhd@)W`jwjvF>LGzf?uPu9E>P4d
zrO@Y<kzs6Q&ItHzM;fmpm!wZ$mBHxGk^y?$wvxhC=f_rN5FXl)8sBjz*99gHAaHmR
zg?lV+RtoE^$L%*$yY4k=W!ufYK#+d^II%eWxbqx^n@-~&$TZ51YKztnA7cZm%>SB$
z8Q{^@GSty5G&7xHSPy#pErSb3Yym^l5+QhvVlc)ItslUVgKOTQyYw8QX+2%`A%uhb
zCJ{CE9{zUB(&-v8uRN|49S2Np{L4XRjFWz9R?)%ikl#d@WJtzM$=odVE^A1_CR5$l
zs~b7y&?qM}RqSq1_-7&^wqiGh$yZuM2al<jOM8#F4=Q_GgdBgcsrH4|jVrB*GW@J%
z{_JE%x{Zg4hPZ$|qE4rA+S|HRfuCQg*4FDSWkv=(W{;*Iqwca3hm?QmikZUpW)zai
zEtnc*EKZ=`T}&8L+xN3(JAIq;<#!e@4sbGzE`;$*4Dfn|p-mN7RlA6}AkFcIxgdU#
ziv6A3)!R>HG{5LL=^QiF^u2prn!rcZ9%AF_!mJaxS9)8?8ha{9;`m^(Fx7`o(9*^-
zI+OEv7<`;JEbKrNAh#EhBOA3x9E1Hr;lS)5pbY@p_LBMGn<&!Nxl41i9>dX%V}P+N
zR;}+{G5WqCjnW#@f9ZNd^d5R<+ViQpx-L3$P}Nkiph3->K~K9)Sw$@INj*8YJLj@f
z*+Rh+naB!_+NtSnzwWfLhq1;bmSozM80Xik(oGSLM*c)>iC_Wvd=JP|df1=roC3iU
zoG&xR@$6d-6s0^VR}3V5OF<O#OG{g~kAF~KnUtj=|3@C`v#uLw1jhW-1=f^erG(=2
z7;8StM)kM^S_ogusRSqMLP>QndgqfbboOay9Tf7RQmygGWgZ+DD(=|p9<gwvV@LY$
zsKw{Gy}=wX0hJ{}sFn&3A-EWGzke09X`ZP?CFlW<{rO(f`WXXA+>Aw+)O_<s2qddx
zj@M76aoU4${C!U)#%gMwR&mw}CxopW?cEH#uHE=d!2Wgoew<E>j8?HRA#~+mIn^!H
zQ6fcNW1FIjQ#SN_nK%EQV_F{VV77VfT5B(ea{vC|K#&-RTdcH#OR%(Mr#R1?jLzzq
zSC-hN{(b^Ik^Q{uB|gq70;JUnM+#nmHCHA@PxC-sYqdnHZfEu1VHP*(8?jf)TsXH7
z`d(w{qU>V+81-UywGHL+AD7SV`|6-5PENL9RC02nnu15q_;*RRA_g8|!M(z88r&2?
zCYs;1K=%c4QceJr-h+O=+K2tbY%HGQfyO1=9--HP5(yo2@2ad|TVK+$67(dBRpKI9
zcTvYDh?n^D9&qCvQhZoHb7DSvql}UJ8B+>~m5-ISatyypAR9WnfzbiDmXq*ctR3Xu
z(~YwCAKYipx{EI8!HwsIlC6i`0r<gQ!Iw2bBRzP^H<5&_bhWb%`Jp+7N6S#}0k1$A
zO)0F@L9I92YTpO>hcb>6<%+Cp)h@mK*_1d8_q6dg4>n}&ihP)NGiUvb81U?bXk&I<
zbcqui@Y<I^d~3O<cQBYU<DeDNRY00OnHzczE=lNTIFM9x2V{Qq=);<S_51OCZU5Pg
z$&6Nkc7tfby9Iyykap`Km(%Z>B^CK-jFfu@*XpEERc^Mh(aJ)LB<!qMKQwcgB>A@|
ze4m|#Gs|Rc+0u4VvgE2<QNrr@m7|*zp7=#d_}YCKgVf1-F#OE#<bkfoAK?%p?e2}Z
zgIplsx!+I1Zg-vlTvx-lJz<CiplCr)L|uX#z!LXQaRIO)FU$d{as*~{r1zaYE>s^$
ztYjCc@_u6&>iu~fe+ed*pr>hTdj(LcVf&SE`t2uXleZ(mhZd7kd|U$5HrJHPQ@IZ7
zz1w#&@Hi?VMVg$?DV~d{6LYoL8SFlWmuiYZxE8-M?^q32JSt7GoOVzZ8#I13;Ax`h
zy=DXkH>H2B>%O@Ual0AO#Lh>Z`q=%r{<MA(f^Z-tsTl3Ybj%`98mP}R8|d_;o-w;*
zt4Wm?XVT=`^{jp_%#V3Y#dg%Dc}r}#IVd#aS-jIyjA$_Y84^-*|0h+xnC{#=*;xdZ
z`4wJl7*zaxYeL2(x}w1QDgl6Z<mc+Q)8r0I>iaZi3fZKcmBtmff&=e!GF%sO1~^L|
z<3g?B>etUeZ?Suv6A<@bH;i=|KtG0mk@t4!qPRX4+^*osf+?77qg=U_OjVUxbTvh%
z8<gmIt!2BbU+49&s58z96ZOuVVFZ7OBO}=HiP=m%Z3HiyZGs+$1-vJ0XP960E4MJy
zmO^>DC!P=LlXRVFEd#m0i*Ka(b7e+3E&CC^Yv2#TgpoU(C>Wsp4))0%aRYtPxSr1x
zO6uJUAMROWMj1L@;~jX6gRh(+e1ZqC_CTY4s&GfB-E;b?6+vEb;^bSE6j9xTFW;oq
z9(1ndc$4}qdAB6ta4BN@p|T{**jB<HA9451CHyq8j(Yah#2d?Vo20ZNN&<=&hpS9w
zU^vu_at77!Pu%v7D4meE1T~e+hJ3Vz?FIR8r+SMhavXx~a{p0;i;Fv=Efu-utTmBg
z;OUtLDO{K|b~yV?CU(pSNrI@XLNq@76<=A5fQ!Jb$@}K<-#m^fxnV4dz+LR5)*8o=
zhY^k=jZR%>2P48}=Ya*Jc5#3mv|J&XRD;~yH>^DLwT>bp@)BbsVm+*3t=;598_Aj{
zF(?v`d_@ky*e%9dvu#A7+LtE~P$5VDCRJz{ZCt3Qh5aQ==>mF~k7bTCZxZg$!j<f(
z*A~dS<7H}{O+Zvg$PZG}mV8x2Zi14e8J_iPweUOtdh5NQ)1<fM`i~Q!5LZV|zgO7e
z_dERQpf7)P%mvp&QMIF6zu!g}o^VUS3t7+bq&hLI?j2z=v@+vP(fHQrtqm9q-G$lE
zzv0}%Jt;pRA3pDXPW~q07v+Kzn{=pm9d#}Ft?_j&!3amX%<zJ77;<e?W0qrZ#ZI?S
zUy_bxtme+oZa|W|JZo2Ph;nUUMVwcB6G;3wome%BvZKb9yL+7dWw|2ys;NB|bpj5}
zQe^!v6jJFzA5^9J-|e=N>nP8he7?WmJYT*1>c{*tJR|Ie+ScEevd4@gG>!gnL_ZL0
zKC)4$4wIXHIG~yE4+vZ~gh~Du9&92xJVUy91zt6P+$SZ9%)_wNU7KW~uGu2PF`KM6
z)UjHJQr%bRkMmIKABTD;BRcKhrdAbU;gFURvdg`TDW)T{)k8(vFbm<M1B2Q9PJM}k
zb@^=UMqP%MV&4w)?X*{b#QxU}(Sx>tSAMueO{E8RHEQz-$F2C0;smk?8Q*e=qM%6O
z6aGCJV;h1Tf3qvPEYi~fsz?&nlrg71v(eKqA!&F7d&p(^Xy#{`bl-!6%zc6pwsB;^
z+s#(uj7tu(L!ti&l1T51?Zuxg`16)sS-XNZm6tV-9#MfVeX#M39*XRuyFiJrxU@lO
zA94#H%u0U~Ea9b26Qf{o;FeeG*!6uF*bYv#%%B^zN~9gqX{FS&&Ba|4AuSA${f^sf
z7tg9}O%6m})g#&j5f%_eXA&}AZI!vQtzb=^sQxVZi~_}R^pgdM?5WD3%5Gx)%~qaP
zgb4y1pEi3Ut}qG#QQ8SxhEk<k2?U`Jq-iT4)lu7}>Ye1Iy%<wx)8Wf?dc>QMz~|VS
zKNsn5WGa%en;uc#7;LpDxYo4^@zL&dT*?Movr0f}Fry~2?+=LVy&$9SKV5+@SE-{M
z4E!tmqebqFV%O~LO=L7??~zNUu90ECkq2Dut+Q$C#QJ*uQ33)=L?sH^<zU0<jexSA
zC#wsSrg(QY`$ihf7K{bDYo?<Mn`$;)TETHkq;^7{P^t5KUrmW!_QE~6YFRIgLSC6F
z`M8P6tD}RR$Lut%Ts$)Y8oj=sok}1|;Gk4eh-PdUtJO#eg)v=SPx_WZ==WLhqWB)4
zJJ*nI!0%sj4--i^vqarG&_W@ot=;M6p88^>oM|)e*HvE5J+C=qp79zhoRrLcNRA%1
zo?(m~(so82vOoC7`kQMWO5~^(`_b!C)8yq_VgnO5blD*sV`<qQZ0{!~=zzr-AM@D1
zmBN7rA$hpr%=vb(Ze~*1<JElydJ?WrbK1-*5qkqB9C>=DhQ}{$VtHxJJ@hixJ@hcZ
z!Y6lPxZ6KphBnMJ)Ki2qFXY=iKs$GnX#1@Z7~hW~TuZju?)u=y?>z5W?Gv0-coA#k
zCeo>mYl2HbT(xw!L&23l5KXaDk)yq}eBc&oPdWOPI`+f_o2cgW5QeU+)?Z2SHRplP
z^{WM#a*z=ndtAjrTjbW0xE@*Ir~X+Bi-n#;6t1um9|^H4v%4b8X{_t71*TeupTOxB
zM!=Yir}l!cM!GzQSnjS?@tOr){-JXhj8oH5p=g?cX47@jYyLLVq#|_Nsv3>>?X=ey
zqHoKr;KTdI-GBAo?{+YUsVsacvsXS>8d?dLdU_)>MB*glDaE}%bBrd^98i+k4NQ8s
zc0?8Fbqr&)Wq3Wd=YVyyUH$oZkbSRGYQQj1NofbRth{<Zb`d~w7(n=o#qncuZxSh3
zrK+hwrS1D(x~3|lVOLrCKW`mm6oAT~K%kNL8<{mAu`GfC7q0zwbSOvNdsksC-BP@1
z;#{aFw9YV-x0WA)j7n75%=vfajNhVXd82t^S9=0TB-OpW;l{l5^Yp~_k>_t5aE##Z
zRgYXbJ@On89x<aiK#sGsQ)yIdr)0<z?Hr3QRJ>{nXLRlW`84WcfoXw=cPcZZH9T^b
zcb#iuU7-qyv~G@U`}AkosbCYozUSeB3Hxyoirpqhcbvd|soGDf8>z48$4OE>XaW4E
zM`Bd>uV&vA8~mC0n0*yWn<ob-6}7((=-iH6*IK?NyrJbNPwt7j#5!f?0_ejo@X%KX
zZoAnfFA^R@E`bAsD<xNs@Rp8@RUJtA+`|^^sUj}?Aw8Jv2#WSNHZT9I$hb+fS$K+t
z{o}81Vr5?6YZ-fo?~zW9k-*ws8l+Z&P08oyz}?TQsmIdAy7}^`SuD~(kFOjj%E6P>
z!;O|1HnCN1ghEB898BR#@4Bo<WayBZ_EHDj7Z{|Lnk*|>&&oP9!4dcdtLZ@`un@&0
zzvF-GJhEY|FLF{hrM=dB7|h@3bEZZVJc3@GCJk0{ONwS8^g2F0`roJtV2uvN1O)||
zIfYh)=}lZzT`5BbTHcM6zo=WwB7-gyvx+Cm)a}&MT+1M^^h@h5kMVlZF*~3?Y5n)L
zG9~s#<;5)1%>+_Ny*GZHAebop+bfp3&+eUH&4)I7Bc%5<40;DxP0G8{l|7Ufj)b!u
zw?zWRNHyLJzYlCQj^pLwN#g~68@bp>+KA=l8QJkW-|B;3+XPeez-@9TIs${Q*6_9g
zgZY+gF6*%)arn3AJUkn5bhfZ9zut{n6VIK=XKt|=rtOVmc&6zImd8%#b}Bw)vQ<=y
zZ*)E`F>yPlf=T61Cm%u&Swgy**c63kVp0V|yM7_vkz7jkw+1H3?_NcbXa2QR`&1S!
z+&YBgY5aZe3Oz3Y&y0-J_SoE$OJ?^Y5E^umyENba+t#hf=fjWb@y_QD-S_*?k6rg&
zYCqi76Dk6v!l>?hqKLvuFrKkCcX`eYORriHtB{LekCARf*i6xO%HyN*j5mwg%*8!T
z_-nF5R#R3`E%JC%un?Z*bLKZbmC(`y?h5hS4~y5*hgyC*ji|t|>+*|`-dcqG*G|Tt
zEST8(?OF|TW>rp<0OymrGE9zAlwD*|y}VO>>~H8Z91s2Imik`Rq+^-6$BW;-O~_dA
z!0~$@ir)8VZEok*1Z^bx^25FUR#w|5ZBYL3o!iz3!TIR!4dM0kJ3M$Uu6oT8;C<Uy
z1J0yNP-@YaciVnkX+_8r`kt?Cbcc8ewFkeK3PXpc8~}uS4*oKw#SQ@NR3=%Mv+2E+
zJ2dTngtX;|r%$104yYK3BMyRZsP6|BuYI7i7QF(+eD83yarHEREmro*doZ##ZhaH+
zU=-Vg$WQ<`M7rii?>KYy50-UD6m_X=r8s9+5$+sA0zy6pqH_&Z@W^+??+HTsDpji*
zpJYPs-t|l<_3g9}ngwho<bQp3+X#)u*^!hqH`FkI2aqv}-WEqfTvvgQBYP<y#mS|i
z<DoLcWJywp%Eu4_8W>*oRGjLvmgR^?mB%vOAB;nrI30-@eap3v)1iCsy6LJHpO1J<
zyJZ4Wh4TL8e$;A)3J{xrvG(WSc=))?Jb7Ude7PQzrs^QKFUs80=y)usVamepIs@|w
z`Iz`#mm;4!p8c?~+N=@YBv*C$SE3I503HJZ0R|PT!IyVtgvYdpEy__RjV?qXKeZS8
zQn;w-0EHEP$J1*7n@+9+ndkivReVrStsXO#HIyz74ueJ3uc5Y(sVEe}?RntR{lQiH
z`Z!qQ;Og%AD&~>mulH;=Kz}3H2_E@LZb@~4srs2{vY?%@)Kl!Nap4D79D{9}Z!`{&
z?#?MOm>og((zofbkjOl>6O9@pvqoooVcjc^C-#xV?L|D3rXAR!rX4PzRkgx;H70*D
zI_Pqi!x-h~CVp;&e0Ji8#XXONI@+S1=SSfqMQ>WVhhw!ZpqKaFLfG@O*E!;9JweoR
z?{TX1XS6B@-~)hQV+wZL_soD`{+?KKnJh{Y4z>ugj&n-b6_}j<Gie?s>Be(jSLX6P
z&9H{W>AHrLNjvzbPKRmV@tT%0mYUCuBT1kvP^GO=`ICpra+8UwYXrd(pWPuzm_4{&
zWk{u~y0Zv8Qlt(vtPO(#zX5n?`VDW3Ct(plTSM;$<*Wqlw`Z7-AN6CITh2!btkaDu
zrf!`e&u14f%tSP&(Dnr<9bp(XcXW%tYO*s963nBWA=#0746gunNA6vA<xQ}U%grr?
zeSx?*DAUWX-^@tqyVM8pJ`VmH#lDuxSRm(y{zHyU+?x7q*ekd6<u2dTD_%u5GP|+i
zRhWZef#thIBs^3AdM^dj=AEL_O59*f%=OkxhtfQ<<??`U@%<NU%dYic1XOF?BVT;1
z%jS(}<|)e}ZJu8G`zWrMnTWR|c!}A`ex+`t_MYCh79xZ~_qhDB%hT*);F$Cev{EKk
z@qqD?f#aXEp9y-_Yu<EA-aQzVae7YDXW(*<IB99d{&Fe9h8tkp^+NKkrJTy&>eP1s
zh3fwN_Xo-D)nJ}kr8L9i<ZT_uyXNm7;TB~cev#GI<jM~fO6HR<)6_Aq6KVaM`Ra=~
zehO^P2P7(UIjWZ*4nkbz;?e&Us%i+iJ`(}n%hEB+7bKVSW8%pr5Qf+kX}6{n%CmfV
z_Bsmd(QSh>Lhlp8zQQ{nY4Q<LVO)>$@E9VtETvY3caFqEe?wB~cpWg4cy=Whdd?Z?
zXPs;EKDvGsP6*bHo;Asedj+UOAyPE`Cwl8av`E7KMRPx<l@}=-d8odSeIojMOm=@@
zu3c@Bv6zxnOuDfg1v5rmv|lpn${2brE5jF~!VQE|(7oF6al=RtS4b!vgZI@qMY5lz
z+n-_FQ<Oi11sH{70x`jaN|IOS%zs#rQi1BP-%|=JcgH**F<;M0fBIH&%fr=NoL$wM
ztv_0HBhcSMqjZ_4qH_j5UL^KK=Pd^dDHd_OH%ylL#hHgnRV0hjiI?h)`@4TpINeU=
ziaM#FJ+kLyAyFDWe?&UAo^zn3tifU>4{M5Nm)na^3~o1fyYQucv~N{FBO$#$%a?f>
z_2b|tKXBB$5)5npHFNe?Zy-grTI8sM+$}L__i>e2nemkwx%9r!i}lDhBEL!$_8+d6
z#LJ6vr&OO=-?<A6N!>Wf@W*)yvCLByyX|NQV|ecCy7=VAOB)9BI*Nhl6$m2&;G5gX
z7X%M<l!C8~by<q^6r+Fg?OJ^qOd)st)@-I3)-ek@--bK=75bVt-$?#0jzs3!zvpxB
zQW4B5dckQlFm#ymll!=i7z#V-k!s}J2fpw)xzE9$lD;JIZb4LNdz7!$Qm1y(R)1Op
z`<YY=7IN`%RPcK>-WD-iH8(`K^IByV*KC4pkE;Q%d_{*#4?^g1OlJz4do+x=4js7@
z4A1i5J{^EH#kWeooG$|j7@#2|@kwpNNOp2q5tS?TUv|0sCwg@^U#G?D|NVyEHk3@4
zh9QWPx@!?z6UooVSfd6QY0LCJiII2vLNZ0~Jqnz~Z^l-ou^A;QU;}AhM{s6oqmA>R
zx?|OM=&u!W1Uio$0m&-Ry7O|=MSkJHZ2nMCm3cd2v986rcYhXj>{)~`rp~In^`jTf
zFrXGkn7tKY<w==*82i)(r|Xbja`~M<fnFBj%bv__-vnMl>Ru$h+~JfC4LO`D=-Is-
z`O52#2dQHUn`kg1yFQXPBn)1doD<v&!IKG;|0OB$e6k8UKX&ac(Kd58;57Pa%F6S{
z=$YZs1JnHbNVG&##jhf-PqS75Z2j2EL9HLPRMohws@Cfr=D8nZi;x~JasD-)L^%G7
z*%<-jB++Fyo<RvBcpgb@h<|qdQiDaksIr6~sb53L<>3>%Z#Qc1db!Om^YRfrJIQst
z-;fRaT=uTy2I$-qS|{FdP~V|NDf7ik?ZkYCef!_RSVV*5*a4(SshTJnq8S~a`-xao
zsx;}%hc<l<Yxrgv&0DN8HSp3cG?34q2-FPqmcaYBa4cpyB1^dPix!5MDS8AW|GO(c
z2ulaNmBOW>FK5ULvK;gHS_-z^^qx#frvEWpEI~{rtfbuS8wSnx+wfU>o`2dC=x3`D
zBhoCot?)M$PTo$u&5L;JYCKUEb(v4VM%h4az4C?X?!Y6cb3KdhwS}?e9dC<zw+q!Q
zi^$6Crm1^KyJek2+%#9{30e8s<`8sw`Q$yB(>7;HdnO7P%wI_DM;;s)@@Z%bXbt<g
zXU_oI{wu`v0YF1{$A)WJ*jaowc?4{Enw^sJ@CXzB`OvKrYDL>Az>;d_JUlP#%eF{9
z&G?mfv!)Kp4BGm-`S$<U0{q(i{N3hfQ%dR#D&P<L!W9|pkdfUm$TgqG5*vMilx&K}
zCJ6F=`3hr&E!g#{MFR$$O`7B-my$q;uy+s8DgHyd6B-Qj?;W*B|4=bAonBNZF~7jX
z+=D;HuX)t-8`SW$a0b62A-mOz$HzO4*&d=*h{S@$75!wLpUn|C=np`ve3iOyjG01A
zdT^(Q>V!e>YW%_7wOu6Y@dH03UOV54u#?t3zN87%+2DV4y8UA)tjRAF;L2r0P4{}i
zS>CSrwAQsVg`0^P+-P9(t8Inr_eUS#5t?4*HluhdNj63cJr5&s250OW1_Y*Veacuo
z)0zW>;IdzS14@>TV9}D^5NujBuLsVE+*^zGaRsMzd40GW&lUtN9c}wb{~oH-rn5i@
z8}x~^(V56NJ>0RjWulsd{#z*g#MP3;$Kift?|Xb^>Pq7n-uera3;fa&%Kqq+sTISU
z>9I?T5p%nzkJI+%EB3-pvu^_`-K4BPitQJr=<|A1pF^2$^d||Im4!Lx+DZc#;0d%Z
zU}NxmZU|4p(!59eAHdzA{rqw6Ka=ssc2YVTy@Kr%TweSx7~PHI0$Ux(MH2xP>83k;
zbDo^brmW`!))Eo*!~#*~(W4nwS!=Y1;yzh_{9+ERu~TOO)jk9Zv~B;)rYQX6mHFEK
z$FpwAYy(lY1r9y+I7I{>9?geW)UF1iXT09htM#|*5w)gCZMKyi*_Ji;8TO`jkr6_D
z6d^;@Cn2~1@1t9zQh@LC&YnCIm}xot2eOM8;p8qUQN8+;{_dBN&^VM~s_~5G#LV6m
z_E3xKqtq!foUe8JYAMWpG6L66c?}#MBe-snYIx34#${6zQ+joY8Si;6OdZ&ke9RI9
zhJVE8S27lRcx<hkm3Zm}Q3=IN7H$ej;?p5~CC~yyv^U^n&_hVM1)W;Mtl1ui@mcQa
z!So@~Qc1HTvS&>M1to&zo06ulR~=)s2%EoSb-}Kq8vZm%56`3bWG&{95m-EEyf%f3
zH>Hp1P(-{>oBt2RmrZ0^^02K|$)u`-lkn!CnYo`C98s@Jf)-Nt3YGS7qu+WJ#ig-Q
zFrQrF(9BS8SkgJ;+Ad7Nb-pL%EFha^nT1{-?E>u#tIcaiqZ19=37#rTd8pgB7g#`{
z3R`W-FmER}xBCpl>6-zNKPtsGV+;sy5|;j2PzH**0v8xbiA$I)z;nGF=f0kD;9o80
zk9RY17@+hFh@PzHbGN#U;3$|?cr@7<-4>(%aAapZ`iHIwt+VtBy0LH(1}{C)3kg3a
z$axD|Iyt-X`@2lAY5noiw7Ges2<yWKE6_)@0DXMR)}oQ5lPm^B|87oXq@i-U=bNBD
zm=I*8W-ZV;ZYxo*mBmii>e_Qy#ZG7g7!r}~R1hs0kXTsZV6s<#V!mFs#>11$)A<fj
zp-)pjs{r<_?juCoSX`vH#f_;o5NV`xp}IHPFf2bg^TwXodOlHx#IcJmU6f>=<$Kuz
z!efePeRv291X1dfQaDLD&pz&<bJKhr4y5k2h=24Qn_-th99~2^Bqfvd_Oeqj1T6%h
z8=~h6O)8S2h5X70>rySTeJ)gM_}RHN4$p39$|V&}Hy&}+?dW^|({y!MySY<7Jzg!O
zf^s9Ppls*TLgM-SI9c;jdIIB_<GD!!5g2lP0O*u)V$Vl;DxU2106Po?n$@?reZF1^
z{EqQYW$dG=kXlH->?_E}SC2dbL5<#e@~e!>h*T}3V7Qjuwb}kpd$k{i8yIhNxcWp5
zmhr}|T%BZqGQI3rUBDr76MVryhwI4_s>U>$O&%JFqpibpT73JynWfVyP9vAd8#TkF
z@b21lX~Xp&JvEw!njH%gzR#bLZ(HQc-x>V%ncNiNZVJK&R)GfUJ{=r%@BYj|e?tAE
z^QvUXJVicpo4=Ku(9&oBMNT}AFs6q4)YmcNKs}&Yl3qAPrANKvAX)cQ0-_JnGLH^%
zib2!LEZ+!2?9Xjt;Vsr#lw0vn26t$134ju@;-k>6A|D<1f9{NA&6lpAq^(bHU;7<z
zT@w`a&<y^LElFsRvN-B-ZICScTk>3`4+N|^gyuiqNV6V>4tiHuh2}gS>rpliJMYF>
z8oV`hL{!l3Cr!jFuS`U(PLYOcg;mf+q*tapy-Rrq73i4^Zr_D8w5!nj+I0u!FF(jA
za<ELIEfiehy-vN@quclr8+rskJ?fbYi*@Jeve>a|Fie9<Wby1nuIzBL@?Ln>MYyVD
zY+|f$aJ?0^#q(7Bv(_Rf>!-!26{dkm`vv5_{yhqlfE=-JnrnR3CE&==9oG^BPJ~kT
zwR#L%pm6XWo_o>~-xFwsnFCS-K3SEG*9n3OmOIw$y|;&`Jh_54%d_jy$;Tc2Y_spR
zsaIH2I<UhI*VzK0JJ3&w5awPau^p7BGToq>H@qw%s;q1T8%_~*JZ&ytt);Fy%vh>g
z0w_CsOn#JW{R5GsH?OEs1xr47FZzM7B-{&lNe2bAnJ#CYkWk}CK065tB0jzXv_Ue+
z&!kU}(r(0*6z9AtXe^RO8lX0D<%I!#-wUlmC}2X3R^;0)cuXyXl#01U9aAYGBNq07
zQ0C`^>CvlIsr|X$a@#JlI=!B?psUQx$bJ$^?{z*pe0X~bm^`c#V&s{0MlZ2T-y>}F
z;qPquk(Pkc+@>~ButddAyRL%Hp<*0=QjboBwPSW-PHOEB-@Y}(p8aa|yNnqY5iwd}
zMW09Non<@D_S6*Yt^2H1H_*KaVR?1$sYP$fe%28z_TYR*uvmX_{;5wg$t{<haelV^
zcv<Sf_vMWjl0B9A`fp1lS3xz2xU?nv=bnGT$lt{<+jNLJ-UbE)hB29IfeM|G@n8}$
z2fH$<&AH4E!Czmyv1`8Zu%uZ`3@5+<)=Yc}*$HyQnP<nakCO3Y3ey5r3!bI&dv4AK
zgwQ0M@{@5qdPTfNr$D}(-Sb3;HA`1@bgb^Ku@07Og_mp1xGqYyXCa48ot*sJIT@Qf
z_r!rc;t&C9tgkUExh}VwvME-4o%s&`(M-zsrOaO6R7%)(ZqD+bgg<IuK6c#h3P27}
z3T2oINXECFy>cwp()qhVL2-qx3)1wM*a1-Qko7WOS|m_n5#TglB_)$&TDF_|oOK~F
z5`+$vb~~{DgX@<_1p#;oVwb#0EZ3TI6$r55L4sS>BE@dTA#G0aD>84pQZg}wEWXX`
zi!o|(wQ#4Y+7TC_zH2&(JiwOOYq`B)Z<ld1>MOS$()lGjP?Re|ONa!QYMvwZxST#y
zqxy;V%ft%25Xi@T@m(kD!pOvW$-@7ISP-Y%N|Ru>0)+_1!Xqh6yx_LcFNm{O`PE!f
z1~@)qX~N_wIEb^f5u-?lm)di~;Jr!!^i2p381+NQa^Cc41Q-KE0Pi#aTB>o!<@$c%
z*Q&0@cBXHDTZ2s@7*To0m*BYhWJwxEsgU+sx@6~uz6~lY%RS;a{p~AC-LG>IUop{T
zr=uIPav^B@XZ77ba;qQ)w|Dxt<bE2mFFHKg?-TK_<qLplyaJmi_nFq!wD_h~+NlNa
z?tsp(c&YuiWcKfeISmy{3uG)DnACz&?EzIgkdY*iOb9%forhP8hZnE~gE%a}VCZmq
ziC3C~F@qM+-Z}y70vScW3EbRJsQ1{&*cb*BVeRVr-fpAjuZKs&-9bEocU~~P4_D9*
zT`q($^lJ0+M)@W!O}%k<c^O0CWP^vt&@gM#OQbQ%nC%}CG||x{u{njt(!ze$E(A)2
zu!y0iRNtzY?4wx-geruby(~>$Q-fY!I+bh=a*g~Nhdb4cY<~1N)F-&Ui>SR1l(Zm@
zU~{AX%FoF4u=?X-SNV(5k>HE$9dJyNJ1i`5o7!u7exC)~47YqFkDvB6Qvg#`GnW$m
zy^C0qY~lL3`HdJoR6L$C-K(+><84eipiDHzaN)Qv$Lvk($43+H>IVoTphDA%<1OV7
zN*wIOIb>eQ)`8RyzvwEjennj>vn!@tYo7b3bB?40+SdR)E#yrS^OTn6TmN05HqK%l
zP)ZuCwf1Dqt9nt}M75{7)xl<t0YEin8VE&Qvq@^~a#e?~j_&;-kt&RfmcKRB<!cov
zf4qSS|061}mHs}G6qav!m^x-unLSG{RL!#4AFuQyx-&pJ`_1={JS8l@s=5MdS6G+*
zi;k{#faQpoE>28WCdmP&nv%F5L&v^Csh6lR4+6qW$%QBQl1y9g2m&zLQodlxDQe5t
ze74A-pBpIlCOSp+vzs<1{?Jh<5)t`U7lpH47Ax0<afmgJ?6d8x5UOP6YU(Y+$juBQ
zjET)Dt=Rj!w952DvKVNc2?jZNLLj;>o_SFnzt-ale`H{M8h&qB)qshbx7Ad#HNB$|
zo={%npyBI&{m}+3+ngQmW@l~dYovp+my{i|_PyEoYucnl>EfHm=~;&)!6SYGXW9S;
zu#fmK+2v+_G46lfe~J+}-wMrzj+?*^#t`G>E$l*-E7%bPB)Ef578L#cU|%dTi4@hk
zp;+bBv%g<!DScD;#EB1xE2+tWIuUE!WPf0B;Cr_Fw<Kd@$={VlOJ9rAOCv%%CC#rn
zvF|>-&D%NlYIGgkRvGc3A&8QgDxkHez9M?flQx3A$cKc(&?EFW$uDMSdb(QMw9odi
zQA?zO%QwiY&D&*2_|La;le8f+v*;YqftP=UX(~GO>fBxRS{^y4gbh*RyJXj3%v!%!
zELfdXKw~e(B^eo_RBX;Th4TrEi|2p2@Hg*5bt%Y7ZIk$P-}GUj)gwz0gIBAGiFNn8
zU4&Na+V|69<~TqZyxqSPaeGkw<_`ynX{4vBxwIX_Ypq#9SqSJ=W^R4opKAeSa3L{m
z&lHRtdQy{5Ggy~SFu34>`lJ%Zqqg`)p0E)ulwxhQ-;}L>tXPKb-xTPBQs}1)CSM*$
z)G0-&fr8_TI{4boZwExp&4Rt|u<&mI1_Iy+`yv2(?Zm>&!E#z5*xWy{v=^H#tjEA3
z;?O-=$gFu6kw*5=S@@t1PtJM?AR~Jb<+?`D@ni^f9@rf(6M@{G_~V?Cy-fQf^8)n?
zQMliUqyBPjXiOCQo#z#uU#^qooR+z_tHzkiIsIG6rn#gWN}koO1iCdnJ2E?}15?Vb
zHv1jpiRE-A-Rv<Yi*v^`21o3O<+{*_2F<)~@(6*qd!_e9c~U%uT>ipUQ>D1lRSvmj
z7W3Og%mVd(!g)KZzdxx03y^c4IMqbhs;z8!D&FY;i56b*oQ6$WJxRAsvOKW!wE>ua
zD0mc=bW>_*_Ph03EUervAR2#dS<NH<ImGu!4Vn!y-o$mAqot{{{78LGjMkl4b71`X
zL@nq8gYd!tu5-qjId11_0_(l{_w)+iIioOa4VjI^x|-TgbY=sbgT4TP^(Txe5wKlX
zwvC9Pkutwr@mNe&Pi?K`I~W-O-GYkkPKxHp=dmP97a4{V$(83qUJTxQ^%=(Y$2XvF
ztoC$Z)7jUF;k6jGk`zCwQ>Hw8J{!GR_N!df0ZL;vK+=3WRYyZ#GgT>l0+k}~1qIqt
zS6WmMZM)!rz7z_m`fK9CHVM8F$z&G%jWzFH!hm|FYpam-1QF?Z)lPOHi8}0f1o9EZ
zDHf!)*@a?vnvbdJDr!`&Cqj=g-f;y=uFs7+Jzk$Lqc5IOB(A-BqFIgF5T*Qh4dUC&
z&KPT!3?JZJ?!2FGI-p$Yz1pL2ZT@|G!_!$1J@*9lY>pk*)lpl#C(!j;vJ^FY@2K3n
z2bIo|a*SE!HzHgWM{6~I(^a*s15DV0tUv$zES9Amg!xeS8?y}$1Z}K#^z*n0>1<nw
z+j<>~He8ZPz~6(W>wyBjvX_I$UA!VL?CFEa)<61QoPZ6E_lJpjc$tmFIQ8ZC{iPDf
zO2-9y&-i(=bBR|;{%~gM8=O_tg<9F|DLGA&TZU$Dmt&g50M3#7f)z&Uh;BRwc9Fuz
z-1wDw3C{{c-~!Wkhp>&;jVmvmxQJZfG-RppOg1^@pFD4B;*!n~lLSmHhRBGUZW=wL
zrq<~HsA?@Fl|25*Z_6NP<q4DR6qo<^Hk6q9u8)sT{Be>zj7X+}j+I5Z=nZ2_bWFC7
zTuxY^a9H;EY7yk(wd>FO+r1&Q=A6pE#dPEy^vWSAqgg}SUq@acOCxOw#+d|Qm9XIz
zRGFSu)D?W`_1iH$=?m+<blem!&bP_}Q!a@NgIqpRx{t<uyk=ku?k}gcDYbAtm;Cm)
zB~4Qlw!~^z{sN$A@ZNeRQr+wkH7SIo0nujrjr94O1&=$w3`1)JJH38^6Vdy1Szv<Y
zi*)6GdrtK_3+@U=NALwUN4=7c0oFEzk2#!gE?niZ`IGQCx?qXX8jobry<dNVUKbx5
z;0YLon|LOFUa`*|+b>!uJ;FT$Ox9sW_Mi@heywtUNevsjY|GZ+9y&g$4FCA5uwfk%
zf*2q%_Xk{=xlxR0V-lrZ<8c<Wo81Vc^A2^oE?CIaYvAT#gUVMR2}40i#!`z*0K(x{
zUfO{u4ceBKjCH6lL6eZ9PR_*q+pMpPa>^ny0kflt5f{jx54mj|S>kwam*Tak1b3;(
z5uPT_RKvI3-JN1xNUUV?slZ3MO>r6QL6oc6t-jxIO{GxTrzD(yK)QDPpLm+v`7|p}
z2gy(VZGC&YNw^Sa`UGiI9uXm!9PVr<j3kpz#+lObx0;?r&(>a7Ew3o^o&h~XSGDkY
zs;^<HzKnl-yl=Nx2(7)DU|vR|?VkH)FHMR42D=A^Rn(pD(SsZj`*Cj{ephmf{$==b
z+Q_^%Vl3um8&^wc^k;^sU~iQh`E=u7`7(bqwSvfc58v&ZoZ?N4T#}Nx@Drd_z_A2H
zNp|WHVl~o3xE#>`*cxA6xHK0$Wic0L>UEZ->|DkX6j1#<+RIHQm=vtR9K&^UG7kBp
zohssHdJ&9qvGa3a$c)-8t8?K+cH6&N!v~A?-<*cwix;^Kx->T5?74h9@7rrK!RqW(
zo2vJoGt#1rN>*x0wCL^Iy~m|a9o+HOx%%|#GJ$IR^@H56PS~Nk&64x4VbME}59a@h
zAqcjHo2qUpv4ru+gtljF5cq0UfGkddYadJBa9qH5nTqNu$*6Eyt0)uW<rV_we+^hL
z;DHs7_s})F@)GH~{PB#|`@jHs9=5|hK-6UbPS59Z+6DLAoi^FiVS%0cl!lw`ZYfN=
z?(q11hL?dH(y7rB-F+)IE~Gk$6K<Gpo<S<7m=gFXIR^yWmEC=i^7pCKy4~B{>)o4o
zI;<zJA`2E->X)D{>#dI8(%wELz1GF@W7BU?iTh#pd^;0(7A|qgmkyuW5DgLce~io-
ziyf8;ON`-an0(auAd<+A^E&OM70amakbMh9ou51y1A4-pKz;ftECew{C|lR<2EG2V
zc_YNUU-=dDwp<c)VE@S^(Rhi!-EMO3k$ma^5+7P2EtvWCJH|!?9NO<{Tcg8tval{0
z62KQ5L)c}EW5A(?PtvLi9CT?4c-eE9!Q3L(B2A)Vte{~$_v43OQ4jp#h_#d}A%U~+
zUJHoN3KCHZ)iHT<4SN%on8svFDpGLwE|q+U3L6diB9KVW>U#60DATW|2Y$&LhL{Md
z<W=T1s+^E#=}9gmiyoKdzu`Wc>gU?Q#<3)i(y#qZ1bzpAfA$a(p99$lv#>L?Q)GTy
zvV36GhERupL#v>^msU5ZmKGe6Pb0Y50Z_*<H;Co4TM{>r_EQ}YYljZ+66G=_SknIB
zZ29q((LiBZotu{WaHM14bGk|AaDkw7pRRF+J)Lu6k|cfbwnXs?-X|W_s!|@*zFqbI
zKH(l_gt(*O6YGy(ey6N?m_zU{`f$GyG}a%6%QeTyYV_*9CTC!O*p|m9#!SnxQYjCr
zx0?Pz4pbv$bbm($)?Vp<k27WyXiUydMpj2C=JIdJC6(3M<G1>u@0tzWHsS2>)v#t>
z@)vmMMS@d6sl1*mp^|5P{sVa2Ydr|^bT4x;;m;G%!7jv|MnM$?)5Ax-e8U)PJP1|j
zw%heI;oCzyygq;2<vxm%!%kz60Ymt^ML*eT2vg|EDf5PN*Zo5w9ldYx%;k8~evsBu
zMy4=YJfdD4dIEW`6%?aE`h60WH}BHF93xmT)SURw*2$cE2AlL6WXx<PjnI+oY3D(t
zS16Li>y=EfJqsY192X~vsQk<QV2&X_TJ(<~nE-XDI6oNNZn<qhIyl~CEjaozfk7J#
z6cU>XUXIO-m*UbQ!I#`v`?SW-Wg`74otU4C1v*?+r{tKmsUFh+cJOFn%ei*x1dOd6
zFdTHO)IfMfuFw1>5}qFUpQ-y^y)mXc>I%0whfG<;p=IXi5i)%>S(gUE5DNjBWKBzr
z_#Wcq8RL0%$M(|1pAfjAhgbM^y%{*VI1Cxpv0wt>7i8%;SsQ+%*i3Mo@%ohO<IPVU
zy{~ssP#*uX$Bgf)BlT9-CSnWHpiW_FtXV08&cNqckCf2J4%B;!=;S@W_;|FW#f$7o
zs$nq)<3cdbf2o<pk+N&EAy_9pk;`%W;1XCdlD_E4?76fvk4|sQYaxK@9lzeRc~qda
zo|@<oOd9WZ4iC>Idc9n_pG$ewjs26kJ$SwQbo^Sk8@-{F@9Fe^jtAAGY004(QP$Jw
zW%MMJ!r8%+p2x)w<D!yVps(*)|3Ia9nfoz)rr6xx^SYZABplo*NYLfxTuwo&K8RIo
z2Lup)c>EYW>%pS&FodEgu=HP#p6`0Pp&o4ydp&i>(Z~^F0082|Xag}ZxCR2>ZQ5t;
z>A|WQnDS?znrt%Ye7if=pzl|H131>3+~^IjMyPz5ZIm@Fg=5~D$N*x02W!5TwV`kb
z5cs|uy{8RXJNs9M*y;%C*|n%;`^I*cHg&PuVYA{FO+N1V#OU2-1R1gU@ug@Xa?q>b
ze*(Sl%OV@%(h7UJ-Bu0-x!o!4QqeLO#F)tNvHiyS;USp!I+M=xg@Z(rv47_0_;K4l
zshut-0EL`c=&=BxhuXPiRDTm2%{M?W6#9@tfK~EMaZ8WoQZWLcVe@du#-RsW4+z}g
zO%&Y$Psw`fY1m|z2k?BkJbNCMBPap;?iM?k=FSWB*Y9pWRVL?x;LPus(N-8_gAb^2
zM!(Sv0A<gMPAR(!e#+l&h-`raSa(~sm^=_2fQ^tw!Ui(>t)38Cm$o>ww`vVSsgov{
zCdYVS8Njokqj9l98H3CsY7CH3qo`^|-M;Kkwb$*2&=wdc*1-MVk+~=0au2!?|GVoi
zlb*^0KS?Cd6dOGkZxX~LQMUMnNLwVqKjApVqAuG@J2V4|Fd>bG08(u4#?aCTUfwsl
z{TWl42|bHA2xHp6o%d%^K-JUV6R+VEJtB_j^juRPb}G3*dpx1g1>G$4D|Q=s2G}3F
z;M%u%O4iu*46HuCLsus<$^K?YHU&?^`|2hfnKp0+1Y(JBc(8|T9J{KMB=@c(b3ro2
zd}F1=?F9afZ~ia~4`SjA>gbccd%Z9QB@zWr+A5TT>sE|}xp#hA#&LC`+{fA1q~Mmx
z+3>dUL=K{Nck=f3=8SQ@%l>15p%Xoytnks;MkrQJ`6T31H;fuO#pNAfE-KSZmMP3@
zdV?m2M1<oVK*C7s>M4Ni5x`?cm$`5?d(F2Rn)Mc246oiYT~1vAZvcRa4><B(o5;Kv
z*^9ew0V!&(cRnuN27SgUW8?;H3ulN=fROIvHo1rQhLpPVDs(QV`G(U~m<!)>RjEnY
z8NB%znB~)cz7NJ}j%6vQisQW~_;r>G41dCv^mugKaMV#j1*e|WaXQam%?@nx(d*kR
z@V)Bo;iEq2(L+y3>yNCS^$`W~tUB=5o*d2ik0YLVGl&)hCY;~+g$9;+2nOIL&ClSa
zTuN#y(f|?&^pdT#|Ez4cA^jTq_=Y?0|BCwVa5kW}eTrH&O080>)LunxYP43(*4|X@
zy@`aP_O8aBMb+LrYL6iH9yKCnjTi~R=Y7B5`2U<|Ki74x^W5h?g}(n)O**8@D0X7%
zVv1o98ti#psHl7+4G@z!_b)r-6_a96mysLGA`sTw(Ba-7OH=r)+EA&MQ`L_4tX0x^
zh97RKX4$v-B12RoBIkh@0H=2|>nW{0opXR%ix!QX23G=kLL=*dp`Khm?uTVT%=5qU
zl4gELxb+XDu+fPBS<+5c=0N?{hS8o(nA9d9b3JdK`8G~5DcxJQ00$!y=d99=`xY)w
zp-=NHMv)Qjt9j(z87hEilFo(355}q1@Z61JoxzK+smK_6!a<MGo<%>sI<ngzRL9?a
z#hp-u>S7%bE2S{&+M-m`xqaH!!UdGuQ{MHaAnI2l0j<#hiPzCyfQYWoGe0;pPvFm9
zT-J;f{>>*8e=<tqzfaZkl}y$%r&8<$o^TTfhT1~nACajuyw=!;!aO0S<)`qT;4|h^
zEIGc@O*$?2+D^+TwO7}!g(>-gaW$IrStoFN!%a~L;Qa~w)fv1KAARO8J#5#Sm8Z{j
z#VBuH3O4+H@pkC~JCMTsw_Q%vgPKQz$H#I*U>;hwTpuL-h7cqpS2-lF(*F7RD~i67
zB&2SfG7B>msr15LAdW>s7Alqm5I~DQGk<7+a$^#JgrrLh9s~7$Xle9d(Mgo*vsD77
z{XEUQAQbTUUiSPIpf#1~#b0Qe-(P5Lc5fhIUulw)PBL~)2<u1lq415ny>q*Ap5<fY
z-SIoOXo2~xGdO^RJW}*|lHy;Lp_RbZL6fO`D8-e8r^@5OqK;UItx<WU={j{MmjxrN
z-wYt}5RtWDNOrZD*aozS_T*!(pVfQj<Y;ziTjQqyoORv<Jg12OxH8Fm!X@cFv-80p
z7Y%6#%Y_e)v!X=??xA3VWPwO%P?$Y50Q}M-_t&B4%Z>kw1*lb26_XnqN}@H)z34&U
z?4Hgp4HD1g^PpCA;OR=)fDO?6y6cAq?_jC(#}EdCh`QU>IwX)KN;^qF`M~?}m)5JT
zP`Yj~INK=K`7hKcie~x|8<DC3?Kg27BXx(;pVaJ%B$Cozjx}EY+0Pg2^_b@jzAMvN
z-Q#{cxdss)=k5AV)2iK+u2%dU<!PUAGWnxBASAVfviV0v0Bc!?4n(`>0v(_XO498{
z%^s9ZU(A!qoHI=zrty!fwL9+QM|?owwFzMRf6~AS2FK|Vrouv>ZbLV&|7K8fNZY)u
z_sZaM(dD5>N()A^cp|44v_qzt)7Vu!$_hUiHdi!+Gsi3aMT~4UHg=v|7Nr$)@50{9
z>sQQ{(kob4m;|9pD;r0~k%Nr~Vsm~KY04(B>;tCiYDmM}oAtAst`I3MB8-^1o2*4y
zg=}#5@v$pYJIkkeVAjPefCS@EAtJ8tvw2n~bX5N#2M1`#1Ca#)q+jL=(#NqNRit|l
zV;QlZ#8SM<NU%OD|Msk~j>O5qsok2-sFZGbtrhPJ{>uIw=e`rw!G+gd*hp>*aCy>?
zvFOe+_1<RKc=69o*v-n5w}<Vuy&&h#m2!&4g5aTsjT_*N%iJm;z=cdMckuNd!VQtt
z53o3bmy*T@l-2;~V~YnbUi$`cFa7}+!L-@%3=D84>UcHYR?BD$%7t)pjqZN4t<<yJ
zl&yTcreBdZwz_(ere;fXA?mb;9-ltyoE^zZoA<x1vaPH*{wGuY$sB?eyliZ|y0jYf
zsjMU5lIe1ssUe;>aVv#X#4^luROO`zvzKdla_cXG4rX=K-zCu|J>K`0jQkZn&>rh-
z>q*zkKe)=0ROa|p#N4B4M6USBET+lU%s<_26PUl6swgZeP}E@(*;cNu1~k7XyBjLZ
z`HpJ}_F3G%AAjI!fpx$zz!qTGfrip=ZgX!>06=%A<7x8awY>DVcI!75wXO&#Uzb9A
zHpP!eJ}**?zDle*Ov-CgAC3N^=C%f#m_;69M2Pse-+jVicE?|p7pHyz$4(<h+Q3HB
z5^}$ZI$h2fPg7rvT;?0J08ylu^;93_LhoD?vqWDP()gPPKruDy^KSHC$Sz4%ogXU~
z=Z;Hx-wxz1mMkkbUC{u({2vqUFCfkODzP!XUy4NsSXB(CQcvUTH8SdQVMNm{R0`V<
zMy#<a?2$jhFBJV<MdF&C_VS>J<~(i=wYOGLEU<%oiQ19w`jb~5lv3X_mQZu-QAF5j
zyURDVYTRjBr8W-84N##WY~6PKt5@Up{EN%>@?_At1##d*91dmXm79_9O;V`0J-&J-
zpK)+*(;)3(T5-M#g*qaET^f{}zKnLz!3M-K{r>y{M~!|6dK$UU0{mKS1)jh089wp^
zYd{j+YOQw%d+yQ?e0FVr=dgLi!3zTw+BkM`_el7$gU;YJ$1KNg&gTayx7TlO%4d!M
zt?uykNvryn@^{l4w$F`sbSjz%J*O15cln`|JisON88##nfPU9$(VI2@VJ)y4#^{%M
z6js!13fnZP*!`ln;HMR^%Ey<R*>Nq@W#*DCvh1TYB6&#vZSlKwm19H~JQ6?WU;JO#
z5kR7Ld^&MB&Ca1I>0t!MCA?GexWe&E#x<C7IAvNX6?kA}BK0u3H*nikp}0XEJQp)T
zTrUzH0nGp-3e_E=<voyc8*rk&4-oY<PlgzgsA8GPrd~vnBc@v2bhQh`{PM*?c}ZE^
zjfvGyuM-X`+(Nz9-tAie=hnMcf+oAN-|I*-PIUo7s!L8<*9R@;Th=7!mrHb9eFGb9
zR{!2i@HCVULxLP<R#VX*r+;0ZE=K+CnA$&oE_2&J8dM97Fh3H7mJ}RcRLOy4e}Y=m
zy}Ty7R&EAwz+@-0zzT#W6UZz`Jt5+po8mk7>3p=}c>M%Vwn0Sj)w5+(Zh1v781%P3
z*?dm@r{9L5rIzX@KJW$=;>v3tbcad25&#QagCiBE75^)48;W>{K&Dj_?+f*XXBZ!F
zR_V>eQ`v_Q#P&x7ry?n1VXlqKT`eXnzX*Ztign-ZO&3fsm%QACV)MCjOiNwT=Rf@?
zyE>F^p~Y9X(2UW~pQF3J5l>#Y@4~0|SZ<;CC`X;(%hUO7L*CnkziIFKcH-Xvw5TOh
z`hM3OpEVQYrK*@}CPu^F?*}utYCbXE)Y)67QZjfd%Vop$A`N=Hdo30DIIr^(gHF1G
zvq(BMeUX^Ne34-3H7~e>%PNPbHFdm}aWQ!^X#P(YL}d5S-T0_|l4n;p!5Gm?U+7fP
z!jB{4W`p$yzKYNU-Cx{?4&c<=Xpg`J$C=E?Pll3-8jyKO;5-)-tLhVDbw&n{oQEfp
zof$G!Uf&fSJbY-BLUn8LXFT7c=|_TU%MEA`XW4~ncv(2+JJ8ZUq^W_ev5BP!uL%Av
z=w6fluf(qR<`3BpQd!vW)pW8Y%HvP2CAg_7n2!jK^-iTP%`tGDw?^{a6(7LAxz1Rv
z3)Vtc$M><to{R*=h3$_$2=NBVcymZIt@1vrfi|l}*Ag6Zl+2)Bk45ne3l}!mztYD@
z%wbXit?O?GrXFhR$>Et-r$@L&Xwl<YX`|h3XhiV5$UzTeri`|xS}go_S2g2cpgT)!
zCEUhCv}KVEC^ad+0uNHosihwRcQF}K=O~|#2F-5^4`g?<J1&B2AOA423AYjGOOXTJ
zoeQJS_FOMKW!uB294^DmkN!PrzXLY6dkCXFi4%xf{J(f*S(D?L7$s{5rPxGE=`XNe
zOwZ{OR0-4!o?fA85Kx|u+l1gwK&#~zxeRfZ4&Q;sBwHWBq24<k@Rlro?2rh>S{{#*
z%?2{~t{;8&ntME~&j1RJ1vVdO;f_^L8v1izz0`GA82%;8E0G;Q!Jbk=Rk*Q9ykP{9
zwvb)l!HhkuHYv7Ct~*nRc}1w4!c$`~1^wOja3=&Y)f{t1-=17-oH(8FS!4=SyXujR
zcIH(75Xghz3@T(Jzo<cj9LP6msmfEi;Zd@KbYq5Toy#Km*`!-Tc_0S}MrA%(5BOj_
zm2_`Ets{(1;GGt=2VOsyDMP!d+5}3qS`<jp^`v3vLHKb4nQ?q|y1@NE)_0>i37k;X
zrbjpVDeqg4O?>>{{~ew0*i0`}sgF>o_H#p@!M32sD=a(I5fiV}V0=RFX)h@kwli7;
z{v~k=mD0CJ@X^Ot(aifPRR8Z<rfIW2!v^h!o!((y)<TZfGrU7jRqLWy6X#dQFp32&
z#4|tF{|eosGYK8AZFGr$-AA=h$^q5}$SR`xQj}>|g=rE&)N^HKn|fz(F`b91J~!2`
zpdH(30GLb5bz4^RmU)Qg7O?xh9x>9j);4v{eWiVeBtoCjmo1|`ldGQ<_GkYnREV0?
zsed4$`tejon3!}p!kRPMC4qh3`uXcD?cG!Wnq;f%-WdXr5n&=$7Hf3o7kgRFmrzTP
za(2#kiBiBUD&q6^jT@>qc~U25YJpM&x~wo)d1K&e6S9=jH+B`JWUvQAqO;(17FZBK
zcx^2vQ;a>m^3e;)2OBOjk*fw3<-QOGF4nJh-Fe7D@)QHwu-olV&mk**>sJ#6D_-mi
z1iuSrns!P{xpKoTmeFUY_g+8@<#l$B09pU8vjyc5#dh9+T8)M76ckFg{#yX@SDV~_
z(eN_~_V>2%zB;6U?-2mK>NM_WQG4enWns>yR_=e-!J)2Xsl~^w{m<?nY)oRx^$ItZ
zO^tVN3_)bfavA97moIl!bTH;;QF&*d4+=;>OUq`;0#r6oN5}O5)y#~?c?S*h_@upl
zQSy^<Pq<_-dR;o{wAsoo<Vm?#qW|&C8sOi6dn=udv4{iCgwnYRFO_uv5#usAu(Nj8
z*Yr~W$uODXKWV4(f*z1gs|IBtxt|~j7tbSuE}AL;F`c;i5B*o0-ZYa}%r*Pk-?=ao
z6gG9)qd}e4{eF=b2*`~kdg*M{prqUjL^szZ&Cs~R6bP5z|FD3cTs1+L4ZCvwhyBC!
zB2JB$>#c-Szn|MpDkzu#dd+?fu+QO0NO2y=9U~R?6EJ(#tAM3y9Y}Pi`s}tCNwwa2
zq;(h27Sf=*EPTSC>bujBTN7ViPPcB#Ecj15jlExHvqY+ehUaeG>K1x~-ZQ!Nl=-kn
zbP)|!kLykq(9nektRqYaa2aJ4Y+HX~@SiSv>0jRh`im5=!Js~^^?mSxJKTMHjY?v8
zVI<uoQ}@}7{K9tV?4RB)NdPoe&0Wd!6~(Y<?M|1&WEaV~z<qk2@5(-S?|$KD**2Ok
z;3*J~Ux`rj_o+VyB5>E67<#Il@C2JLsypu8oPFN?4$Q&t=oadNY1q>5`q0I*^QX6R
zD4HPWPxKb^tRKjS|8J1^U8ka6>G!fSg0%b(KS1{x<2i#afYzM<)w5L?N~eI>r8^bS
zwB=5inr;qxZGSPSOpxdJUgs4XN6ekD1eco*;qL{Mr<B}L%dEgO_-=3wjcJH4@sK`J
zQ+h;5>cO!6N!%)#{81Sf_ZdZ0`s`&5J~>IzYFU(_%TMg&eCB69q)8it?8MkVAL;BV
zxo%KgVZB&PE1{6*vo?tl;p6&BEidXAq~a!gR4^!UgbY4PvXoo}g@|oO-m(Et2NS!F
zkxPjdsj0BVqIu_(Px80y`06F@sNN1iwwb6x_Vg18aeQURHJ&uTdSTCpvrO)&fEYq6
z3kicA_FqElr+57>tMvTaU`FZ;BtE3n-*3WeS*+rcB3msBs|q#%!*V=^&TH|tO#lug
zbPPScgFy-h)yjm{HnbHr;gvzdYz}3F9Hr66nP~TxkIrmX8^Z`nJ)!Zys*x~i5yyiA
zFG+l@ZEzN{bPSEKyJWqYPfKh0%D~e4Nnf9$+>x0>>jaPv0B}yxMjKK9dN#INB!6n$
z#~M#K9cC)sbjALErQN{AgfN~}r#G-nd^BSA!%)DPSJ#9DdyI8_|DY6uymG~$2jpi$
zQ>-1y;*M|Wxt<QNRRXk>4FZ0VYXZ%}P5%g)eAZQA2i3lr@%Rh9>Gi;cZ+?2|6M>ll
z>J}}1wB{2?<>u6mTRIXu8b_BX{J-6><*dVT$eTBT8J{L&!+3C;BD1rvuYuhHF;8{8
zQ)^BjmNlgbTkeqPm6b2sPbI>@NHly0<KT6N&M<2R(TgN3E;++<iMI2+^d8`t@}LP0
z?QmKaD>`qJ%m4~6<sO4Ek77MI#p`D-&vIZeeMyeW<gPnDP)LRN|61Q{c;{`z>m$k2
zIZ(#DZ)glNu@M>{^c+DeTglV<CPuq9FH;~Wt*jZ@c<lIij<~_jPEETSZ~A->V*KE3
zz`=sp7EzVg64RmB#$|Cuymg-H0)A)kf%y1%`aw98n5=<r+2qVFXYL56Y>6hg=p&P?
z9q7RG#bI#wICqbtjv;#y(GF+nK1a}HbB-7tdu9GF$2Pgu_4T~DPkel(q8XK3CJq(1
zAC&RiyOk-5UhcMTr#5%4ji@2Unq*H7_EX#ugj1x}^sm_IViJ>6VtXUE;R+luu`SxS
zid2!9y_hO<`fuf*arD<-?Ha_lOOseuPzM8$bU4?A*sC9cZMMek1n--73oL!8@)<?l
z?R>pjyO^GmWJ17DxbFwwZ?>PB5AxD)L!t0M6y6OJ=5Dsw^k3~)39Ki*1MN7*Gu^uS
zcn2ap+}(4ZHAsif2>)KEH>p06lgOv6=0G_2N5}_XW_dM9l$k0lJwQQXB6!9yMal|@
zbXo@n?{+f2J1Zi(fb&EZ<D``Zp0o?!Ev4O#X$c95)xh?~yM3P=G*&sj*i0^+-2_dd
znT%GB2aLkAcjG>vlPlPkN^fu8K=Oj}FISvK!kkR6w62xmiS0Lm;_ZMs)w*hs^uk@r
zi!K5FkcuzOzxd}}b#6y?Y{2IK?54LDxNG%A1Hq!38nzu+3<r5^+b{SihaAm2%|TQK
z2|*rF*~NCM#ku?sRaN^NmrDXg<bkcp-{!O;O3lK1LMX?jnbdZh-M9?^KTBI`D>^^G
z<9OWrZhVDE;@Z)L7>Oi}<6d6_9`57qhu@MG<&LdMm}#<#QEi@u&Rwx*`77q-=GEcA
z5F^+3wRv~92WIm^XWqu4T34W-bOy5BHI>DC-7&le9XJIc-9a6loj73@iXV;nNy(qJ
z_}?B;Rr^s#lI0NVq)>6Gt&Yoi$uQ7-F1?^sOvJTP^G;16O92yqCD%ml3T*6hMT^cD
zRhluHrmM&l%HA}1HO(I6d}*G`{Da!T;rmwPC#YHqvN=t^<_i>b>q;Ga&Zq?e7X9hi
z^?Kf3tyT`bv}nw;|Liab90mNtt3>fU=4x!t!~U%^>pt;8zx2nV9QVoSvRJMyNuDV4
zv5Vj@Ls|1FBE98xkWy@yx@M=zr+cT&=69&P=^Oe9ecMjl?YCGkkH3tAX6!->L<26a
z-Kg!x>&h_wj#OmYG;#eU#N4-U&PK*y#A8;EmkrSyt!&*P^jcaJE-URVhK(k7!I#}7
zc=cQy|EzTJo#&*)%~(VeI)E)Fhz_~56ulIyB(s=2bG$Zhg}O%hcQ48ZpVFc$ty_g!
z4u*znqi}Gr_df07jntKq-<D2LWhUP$5p4yw;oL|L--JaTlbHtnuB-KlfOy>7VeVMQ
z)(4M;)lp~vVqfa%Obd9n-rQ>an>tT`U`AzYOGZSDWm!PYkg=p9;0|orKEhTn=sgt0
zhEQj=P+%$H{P0mS#W^G^8rz;o_v)Z*!`XJw>E^K0rOCb_mN4MOJoyKdyMC7uIc9qs
zcSVNQ;d+48Hzg}l)fE*^wjps=YV?!StX^Q@=F8I-e<4F+{+B)Oc6<S<c4wXnmTzyV
z6<w#U9t9`{roY_N!VEu;=J*cB>0S=0(*9F(H<L7Pfcr}ESgU6JxODyBb7WrW6!!{}
zZgGB{UbtB~dYc0K)+leS`^=Bj)Z}$}lDTesHQm;#!Y#K;Rh~#1CWG3`0P*5ACd)rE
zq$8)%O4aNmLC?O@5jPvyKM0YNHvZ-uiEy5mj%!Kt`ji?g1qn-vl!|yi`9gw$p~8d7
zye2ByodKAT&?P`!?!^phYcB6;qHY`$U_R)WQU$t-2L`*`;x-9}<<2zUd|(Nu<0vbb
zx7m)3jpZ;g_(c{2`TdN9cK7tL?P3WTfr7ci^QGyqAg!owY!+i>art!5pnRV_aE_nI
zmVuGYkmwOX`_Pu(_Iy=PLlpa;@!Cpv8tCA_a?yVJ`_lSP840FezVboo0}!P7RvJ_R
z%{uS@n$mvYl=vgv5%DPIfOfiRRw~*9b@9XND9E9zK|!HOJx+0-$jkGj_(bsap={g}
zQgi#dC#hM3c>CmNhb(dN^QiHh$UML0pU2DRz+b5=D<PU1-Y%XBZYucRyTZbQGx6>+
zsWOWdnM5vx4IeU1IiE;bL5t6G0A|xb+X}sS=8pMK%zk{f4%bmba?HMRt}ek7-rEj<
z#fvb0@~Yr8mUaE@v77VUg8ua)b|$=-eH(N0^zd8^ZAeN-cw2_QKw=y(qF13Q6{n|f
z|M!)oB>&Kr5_DKHr=^+*rB_gt7sZaMNyJ}&uajMfm8{TL@{0JBCfq;$D#C+yezLb;
zd|T_|=f&VkKRy^BFvXaF=-a-5{Z`eS_5AaebP?Q=PG&*LD`(%8Pp%pH^}ee7-`+;_
zFL-A9o*_P$zCSMt-D2j$k$5#MG<@eFcOUf4^oNC|Q?dlH2houFlWYcmg=05|%bh7?
z<YOlzGDX_6x8}8=qGK7$Y!+o$ND$kzN9W0K+iMe2cz}g-fnebev-wtqZWLSlhrHE+
z5`h>eM~}MtKI5_4Fr&Wj2)r15)|}*x_nSwq*UyI@@N`xST2oVpT5N!XHi{}D^t3LW
z)QWYzln?}cv`F<!{XlO;jr3*)>-@tpJ-bx;2s|w(^WsB^_*bQKh+#fV_AwFOu0j+L
zhwf}0{96B>DmmoSin7%d_O_O{J?}3_-K{!xpZ7NQ_1O(piGa>BCsb~N8fz(%;B5`S
z><96Y71j{(#eq3vk|K+edR73!{2M5dH}c1Qy|cIIhJzvK@RXPKN|HlJ7Jc}YZ)x@R
z=6GiB+z>kK;_-@eC`_D*ELPO!BWtwUb{4TlSlBi^{-ZU3lRqhQOT4Oj1Jq$=W>0VM
z+{dD6A_66!;&N;G?v>?NJnBa*+$P)Xf=(NM<?0TYo(al79#-KAr?GB5Xrz*EGKDtg
z_&E6Wx4qv}TL`vid8|CcBC?pTq55?iw=BGYY}h1K7FDYiH10R(OL0BNZV>%N<e_(h
zcCwH;$L$7wD?5UNTFU!3XnIzvs2%yeiCj#YwVT`W<>(uPBV1I>u+xMQdzMejPXd3a
z9q)SU?37-g=>@v+(O*b`k6cy3-Gpik&WnP&pu)H1!R2pc?@srJhOS1qYmqM9$E}w4
z(b&5mLotm9<<yflLk`gGGZ5i;ets$_o?^EF^ARt}FD^0B%eVz*Y-{W}kcBN<qWW_r
zqxd_aP^sJ|0_Ek^649kQJWzKm_Llq->t93*u}%_?&I@<({Y~xI@y}YYbBk;1;BMyD
z;^O|%)9HzryP2v{H^`S(=iy}m#Zv?v-Rx5NHb-kYv%5T}@YGaUER3yRC<Np4djpPI
zj;uC)+%(RtzSfP4U83@Z<sPWcMxOluN(*SMM}D@mvye}CVY?oAl_xAI7m&}454A+(
z1%y8ppAhI9VVVF?ZO5=|_k(l^&^!o^i~`xtP@Ejmq=bE5TvLI)7i`l<m%R)4J%R$K
zJKR0qqH^dO#8ocAU>;>xehpD!es1gMDY)rLAZ4`DY_hw!C7jR>u(TKM-eB8GtSm3a
zstZT$5maSzy-rWzw<rD{ivjWoYR$0Faj;!X6>tu?^K)ymZW95bGe{|MtH1A7e^2Jj
zh&aEAV%iw0dSO6u2A+JGRA_OB+bc^SPqbZ!3<EuHmr+%g6T+ezN=&>Txk_Z=2>rQN
z=Vock1nN#SB$^R)<rQv?`!QMVtt~N1emp+j^cKMqZ8A65=T<f8!R;e1YCHbMb2H6S
zabix4?j?jA&Pm7=(>M-Sle9ulB-9$_v3b(duYR-=9@OfkQ`+}vu!_ReUIg6erUr9`
z7^=Hgn6q0LrwQ1a{$~BSfVntOrqCTWDg;%v-waLrPIGb1|1^KhHvi0K29+EG$LGB|
zUTF<JCOGpx|JU8!P2!_^=Z-5u1?6-8>D@uEmy}4Gw1v9*w+?J$S?KW>^EXx)N2+TC
zhONu}Nda!+B~dT04W+#<j?<q~FJ@hG+&!6V;=2~TaZEM)64uO{@$Ko>&CLTBJcxA6
zPcr?5?VaFqQp3@hM6^I-40PiJ{kS5$gGlOXz$JK?u_l<jJ@HNEm}`Ap^_on#>-{sk
z^&S$X))sE=9Q3;%q{FW@Czd1#hf#5VtC(ppQgOw7E`vkrTc^}|fQ-3!v_JhmiKM<t
zockjPg9LdKUty39cU&wqzQrmSM?@re;m*uhzRFiN;7B$N)tKy^nS_jbB$1HFb9%Tx
zz#?DIIW*nz9tOc3`1J3-wSQ$!)cEQ>|HrA2=Bl&?)2e)`;lG^#ZViDV4_R$p6~Js?
ztK4U6+^#q|xg*yn)6VP}v(xi9#8;AAr`&=Zn~=W#0?9ANmZ)LzXh=a~C+wtPXUDyM
z6h@*TXZ5@<{^5>Hy!mSll$Etg)A9XMn_<w+)5DWr@Vd`|Fs`iQmb3TR2T(p}30K{U
z;EcQx=XLUe)%BW{=W(|Nmd4QR<vpY1tlQ<ZLny<#^b#5YJB?1FG{f=4KHvG~p^$6B
zv5nyrHT;(+3b{WHl6b+1<KFq5%Tl8^tHgze>4$PVj>{!fBQm>(Uu>GWFg-A1U3%q-
zIW{nU5#n6K@#^b}C`pGruWVi~g0^OSuGJqe-QckH;(U>ljsE?j&C@rLrKlj?dw~zF
zSm$QbZSRUF!86E4BvL`}S%M4Jt+2-qE~L|xS~P;Wva@JQTSLutv&NZLtoo~^Vt0tb
zmjFzeDM|3wz>BmVNP=3eCmeQOYT<Dc7FNEXY}5*DK+=dZMkgUrk0kUNWn=@C#bP9j
z-X<KYYrKc<i5(McHXo;nXh1*5WQO`wY4bi)c=vqXx-=z1ox7mU_ZzHADEQALW&Wug
z<VI6?sC(CJfS7yY$LEw4c07L$08OO=FQI{TO6TnYyF-|CBpDt}XsYq(Yr6cw<7n+d
zFOetb6Pf*t_K(VAdDAjH38nR(g#DZ&#0Y?!?If#c6MV9bG>x*7sZ1kyw%Bu;z85%+
zq@9l@iwHik5aU-k`WKtEIk@&K@n2U<)!}T5MvHm-%|$QF;vQ0)G6^N?rpU-HIrwZR
z;|I7qQ_QvKy}ZrK1%N&Zke^v|DL2$UYEX<&c;LkykuJR<52H7suV3J^j*J6JKh0PN
z#Oy6qY&&6Fk5bo94sA$KmQvJsD9MwS`}qFif2tL-SS$0dpI?Zc(v;*oAHxCD4|MA-
z4F(8{p5fONvZqT8@lF=n<Bqu2x6AE=6#GAB6P6!}*h-sK?1f?N`UV=dEz)gPhrZlM
z6R9b#!X|2vRiyPa{#FUwb89sJV5}0Zj@_<JG}%^5<(5@Y1(0RdvMO<{=Oh(-XSsc+
zGP2dhjLd3h-x<{{7ZEvU*~xC`PT@dARYQeNIFx7c>GL{2+4*D_s$B(k5}$UmeZ7|j
zD(=(@Hiu`Ke7^e^)z#Ito@z{&pknX+4Hje$XR;()V40J6`k3|ScoU!Pabun5@9%mP
zmE0H)8ujqF3@j`{ssH>D@QaMH5^8TCZ^LDO{!!%PNEn6MW7YyC+i#)^Ow8An7w4hu
zJ@(nP%+vtDo!CBc0r?3jw%d0#ygUU24b7gQ#AL4HJ^wT?jFCKsgZ06I)s3?0qQi$N
zB1!(9M3$G;5+Nl%L^iTl=&#ok5~E5*pOeBWrLW$koe8@$Zw6)W)1O4YY46?P5(SAV
zQ<?3G1t+~OW~C<e-f$~8D*q{(yuW=}(*Gyif5vl>T%^;4ds0^Zq*?DWKH2F&`MIl^
zWEn%ensMHAjJ3`FI1qZl*{@K`N&MXJDJ!0e+qa*e+GM{4^Tk)bR+MV8-stG&VK7`i
zKAq<Qh+Fo*aLyj7E3IcaI9!fhWUHZ(k$qs^zyU$*b8;eX&e6Xijy^0pJ}EGpR8@ME
zG^dPL(IW3)b4St6@ue4L(luNHYno`$R^wCADr5mSW?0~>ZPTO9O+%>d^;IPwo^(&-
z+FY-X4}F7=lL%`%MHaXyLv>oz)~+?>bxYyv?uV!4Q$xcnTb0^<-wehR<E!T*70ezr
zGDA9ATTNT*8n{^jKJOmoQQZ@XuM`a=UiJ2YXk0&+niNTKvek-><%%U;Jo>Og9FXpA
z7+m9CzO^|~+=lCrvnjn1kK-e#&g&3sd&NfXGTJ0kul{Ll{gzl81UqJ8_%<JPB2hr?
z8$OXoe$IX)jr%?4(!AVf2?xm>IE*41!RmC`9Gbpt%HjA}7%@P?8(&foUCm1E*2&oP
zA?!^}75N2RqeGh;addDgdKQg0I&z5<894GRqif|!!3NMzWJqa_F-WrD_LYmrp1Hn|
z-7Lagf`8mNvVumy?6;R;ff<D*a-XZzsaxWxVX@?Dr|#J9%6f6qojfM8cYoCJVZgpy
zK*>`k9|FlT-ilx{F(5Q|&)E(*x<q@%D?WLI3@CPNdgS}3nmUKP2}!^q`$X?e`^0#m
z<C_nazql^@I5hsbt|0Cafwt`|cziGmtez~YMq6QT)2>CmJ>xaZjpw`2yF}9d;*_1R
z_t7&i=K$3fV-{5>8-EF-Ja#@rS&T{rkI-8f{%WI`b)?cK3Er*wIuc1Bfos##&3)2p
zP)wC7<6gKp`E7wy8J?h-<J(@^Gk{sO6i6&x*Xp-ldZF1}@K&O#I<Gr#W~PB?AS|_P
z*8Vym{Z5*}QMRVBMSNXVubs1izGxn!JoT?iJ7V0Cl3G9c3(sW*rn<G<K?6?ItKfIV
zuk-~IC(gNuYpS9`OOaH8Pb43v6shTuk{R*qX9-+WaAD*f1+*V9(<JUrGjarSPwl+_
zgZc4!8W8}aRotx;`>et+SU-WxMo1qIc0l;u17=TaMHv%A&z!NcLz_iUq}^ALcRQGp
zO3#doE5|#DE|A17N&RrT%=+<_Q}UAjR}>vMemq*pZZSq4keZc7wkj?Tyw0KDeUqAX
zGZq}z9c5m3xA==aFv2W4<~sN*{{<rO&HmN#V;EDq&YwUq^i3+Z6sr(s<LCvT$?!=M
z=zEg*W&1>4?ULGuufMXW;<om;d>sxyI+iSm?i7hO@%9UYV(+`Q>Nos%vF8g!Usd2P
z;4~-_8`!v6@(tpz_4Q(RM26{pkU|)UyNr=ihw-ukPHw<<uM;ff7~|)N;y}JZImUdG
zyCEHFdQ(Iee@GJM6-x_xu|!^k?!Gdk%O@R#kM1%%E@@={p>UpU+AXw!RaEXpRZ`!!
zYg8dc?5IoMJQ2hB>hz-+?AEJm77QYbCtHtF_p0^ms1x@`UMtAF;}i{5AxiVl9DDpj
zl)*5)Ng<4^TDD4i$KlbhQ-E&f_bUF+KzD6OX^sBayL(UNNV{|$loE2{yD|2UlLV?J
z@Ig(y`w&7yeCv-`?uUV^&4RXrHsy&k@i}adNm;XgZ!a@xnvjG)yI_LjRiUqV%gYIh
zTK1D&S;x6J%jL!y86wNhlMbcxK=q;CDA?OTEGBAUdVZ$JYB=ElyA%2HUEC_MuhHw9
zf<rr}k|%R-&2J>P)~1CR0x8cHDC6+A8>NSYxQ2z$vA2UJn>pzZd<c$rq>q@C^#Xoh
zdqe|=^fm{HmPOP#EjbbH25nT$CZP%K7azkF(mG$3cnFnvV!sc|V%0fVJ$l8KpsRTu
zO8L$dH*_-Z+K;9`{p&$Rca2+turcwk=8~cyK0rNk55^Im*gM#q=U-^i{<0)$3uHRn
zH_J=aK6A*?VLE!3Hi&0;r$KN%3v1#-jxKH%pl+cXKmYXX5gm8@@y1#xCav0t9od(z
z48bdZip}mIsrXig{8+&@W$YEwRGTr);Lw|2E0DvqPPPlK%Q*y-eRpGMtZQa*dHiOB
zm&!{b3*PxxlCIhz1he8Qe_ituN*=Vlqosm<vz%1}I{ej$I-1v2#iD%}`vqT<;O~1f
zlLyawJi_!j_~`xt%YxcFv)AiDtyQJEE~Q6;Hbdb=ClW(Q`foBS58RQxyLH3feBri~
z+@xmF^JYZqt0aIZ#m~%Qw2uFZgA1z_;-Byu!7Q!#v*0Vy;PI&Mkwtddw)d{QprouS
zZunk4#vT`u_Fax9hXYw|`<Ofv^l2T1l5#Z<xjk8X79(&2E~Q4=UB(cm@kPMsyirvj
z1tmA*iG8|HgC{-yF3ZFy_LK3r_OB9nZv`p)^9@H4)V&01wADgLg&k`c^TC`ovd`xX
zJ+V%%E-Kc>zZgl~c62oxde$5Fm7!q248t=D%7jc(T&EAIMN0uPq5-R!nvG8HJu)x#
z2l7Bbq!k*ScO@_{>}1p$JUt%!O}$q309mlnN$TVTn`5E)<0cDkchxB5N9ij>^1C4R
z#OSfF2<An8kt1)}7|zk$$M3vqpAT?<=;4p0MxuxG^Vq#7A%VhGK2nq#m7RyjFL?FG
zCRJoX<U+=2BEuPa5^{nZI@^4+&2o1SA<xwab<ixyF+22g$5iDd4uOBrTx@|+96*g^
zk2Q+~9>7Mj!AhRy0lnNE`7ddO(RS@~@s9$AV7<UyuT!t*Iq!?y=WKL&3ojE#9&MAI
z1<rI^mo6PW8}+?>2Rat8_}SIGlyS`bO`b4OLVX-@+it2;l!x9Kc))(Q=DJL~4JFw^
z(QdVI!ny}MfWXZX+W7j09)ZfAZ3qAKqN*1(7zzgC2SM1%t1q&GJt^ZKz5~NjeW$5Z
JrC|B>e*nH7H{}2T

diff --git a/docs/tutorial-extras/manage-docs-versions.md b/docs/tutorial-extras/manage-docs-versions.md
deleted file mode 100644
index e12c3f3..0000000
--- a/docs/tutorial-extras/manage-docs-versions.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-sidebar_position: 1
----
-
-# Manage Docs Versions
-
-Docusaurus can manage multiple versions of your docs.
-
-## Create a docs version
-
-Release a version 1.0 of your project:
-
-```bash
-npm run docusaurus docs:version 1.0
-```
-
-The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
-
-Your docs now have 2 versions:
-
-- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
-- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
-
-## Add a Version Dropdown
-
-To navigate seamlessly across versions, add a version dropdown.
-
-Modify the `docusaurus.config.js` file:
-
-```js title="docusaurus.config.js"
-module.exports = {
-  themeConfig: {
-    navbar: {
-      items: [
-        // highlight-start
-        {
-          type: 'docsVersionDropdown',
-        },
-        // highlight-end
-      ],
-    },
-  },
-};
-```
-
-The docs version dropdown appears in your navbar:
-
-![Docs Version Dropdown](./img/docsVersionDropdown.png)
-
-## Update an existing version
-
-It is possible to edit versioned docs in their respective folder:
-
-- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
-- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`
diff --git a/docs/tutorial-extras/translate-your-site.md b/docs/tutorial-extras/translate-your-site.md
deleted file mode 100644
index caeaffb..0000000
--- a/docs/tutorial-extras/translate-your-site.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-sidebar_position: 2
----
-
-# Translate your site
-
-Let's translate `docs/intro.md` to French.
-
-## Configure i18n
-
-Modify `docusaurus.config.js` to add support for the `fr` locale:
-
-```js title="docusaurus.config.js"
-module.exports = {
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en', 'fr'],
-  },
-};
-```
-
-## Translate a doc
-
-Copy the `docs/intro.md` file to the `i18n/fr` folder:
-
-```bash
-mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
-
-cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
-```
-
-Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.
-
-## Start your localized site
-
-Start your site on the French locale:
-
-```bash
-npm run start -- --locale fr
-```
-
-Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.
-
-:::caution
-
-In development, you can only use one locale at a same time.
-
-:::
-
-## Add a Locale Dropdown
-
-To navigate seamlessly across languages, add a locale dropdown.
-
-Modify the `docusaurus.config.js` file:
-
-```js title="docusaurus.config.js"
-module.exports = {
-  themeConfig: {
-    navbar: {
-      items: [
-        // highlight-start
-        {
-          type: 'localeDropdown',
-        },
-        // highlight-end
-      ],
-    },
-  },
-};
-```
-
-The locale dropdown now appears in your navbar:
-
-![Locale Dropdown](./img/localeDropdown.png)
-
-## Build your localized site
-
-Build your site for a specific locale:
-
-```bash
-npm run build -- --locale fr
-```
-
-Or build your site to include all the locales at once:
-
-```bash
-npm run build
-```

From ca81b202e4d32f16ec370df0b4fa745deda3eb57 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Tue, 11 Oct 2022 17:28:41 +1100
Subject: [PATCH 04/10] Rework containers doc to use more deps from the
 container.

---
 .../_category_.json                           |   2 +-
 .../containers.md                             | 117 ++++++++++--------
 .../providers.md                              |   0
 .../slices.md                                 |   0
 4 files changed, 66 insertions(+), 53 deletions(-)
 rename docs/{application-structure => application-architecture}/_category_.json (82%)
 rename docs/{application-structure => application-architecture}/containers.md (71%)
 rename docs/{application-structure => application-architecture}/providers.md (100%)
 rename docs/{application-structure => application-architecture}/slices.md (100%)

diff --git a/docs/application-structure/_category_.json b/docs/application-architecture/_category_.json
similarity index 82%
rename from docs/application-structure/_category_.json
rename to docs/application-architecture/_category_.json
index 6d4c37b..499c416 100644
--- a/docs/application-structure/_category_.json
+++ b/docs/application-architecture/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "Application structure",
+  "label": "Application architecture",
   "position": 2,
   "link": {
     "type": "generated-index",
diff --git a/docs/application-structure/containers.md b/docs/application-architecture/containers.md
similarity index 71%
rename from docs/application-structure/containers.md
rename to docs/application-architecture/containers.md
index cb2f711..c6df4a4 100644
--- a/docs/application-structure/containers.md
+++ b/docs/application-architecture/containers.md
@@ -8,11 +8,11 @@ In Hanami, the application code you add to your `/app` directory is automaticall
 
 Let's take a look at what this means in practice.
 
-Imagine we're building a Bookshelf notifications service responsible for sending notifications to users of the Bookshelf platform, over email and instant message. After running `hanami new notifications_service`, our first task is to send welcome emails. To achieve this, we want to provide a `POST /welcome-emails` action that will send a welcome email via a third-party Acme Email service.
+Imagine we're building a Bookshelf notifications service for sending notifications to users of the Bookshelf platform. After running `hanami new notifications_service`, our first task is to send welcome emails. To achieve this, we want to provide a `POST /welcome-emails` action that will send a welcome email, probably via a send welcome operation, which in turn will want to render our email in both html and plain text.
 
-As a first pass, we might add two components to our `/app` folder: an action to handle the POST requests, and a send operation for welcome emails.
+As a first pass, we might add four Ruby classes to our `/app` folder - our action, operation, and two renderers.
 
-Ignoring the content of these classes for now, on the file system, this might look like:
+On the file system, this might look like:
 
 ```shell
 app
@@ -21,13 +21,16 @@ app
 │       └── create.rb
 └── emails
     └── welcome
-        └── operations
-            └── send.rb
+        ├── operations
+        │   └── send.rb
+        └── renderers
+            ├── html.rb
+            └── text.rb
 ```
 
-When our application boots, Hanami will automatically create instances of these two components and register them in its __app container__, under a key based on their Ruby namespace.
+When our application boots, Hanami will automatically create instances of these components and register them in its __app container__, under a key based on their Ruby namespace.
 
-For example, an instance of our `NotificationsService::Emails::Welcome::Operations::Send` class will be registered under the key `"emails.welcome.operations.send"` (since every class in the `/app` folder uses `module NotificationsService` as its top level namespace, that module is excluded from the container key).
+For example, an instance of our `NotificationsService::Emails::Welcome::Operations::Send` class will be registered under the key `"emails.welcome.operations.send"`.
 
 ```ruby title="app/emails/welcome/operations/send.rb"
 # frozen_string_literal: true
@@ -63,7 +66,9 @@ notifications_service[development]> Hanami.app.keys
  "logger",
  "rack.monitor",
  "actions.welcome_emails.create",
- "emails.welcome.operations.send"]
+ "emails.welcome.operations.send",
+ "emails.welcome.renderers.html",
+ "emails.welcome.renderers.text"]
  ```
 
 To fetch our welcome email send operation from the container, we ask for it by its `"emails.welcome.operations.send"` key:
@@ -74,10 +79,9 @@ notifications_service[development]> Hanami.app["emails.welcome.operations.send"]
 
 notifications_service[development]> Hanami.app["emails.welcome.operations.send"].call(name: "New user", email_address: "email@example.com")
 Sending greetings to New user email@example.com!
-=> nil
 ```
 
-Most of the time however, you won't use the container directly via `Hanami.app`, but will instead make use of the container through the dependency injection system it supports.
+Most of the time however, you won't use the container directly via `Hanami.app`, but will instead make use of the container through the dependency injection system it supports. Let's see how that works!
 
 ## Dependency injection
 
@@ -88,6 +92,8 @@ To illustrate, here's an example of a welcome email send operation which _doesn'
 ```ruby title="app/emails/welcome/operations/send.rb"
 # frozen_string_literal: true
 
+require "acme_email/client"
+
 module NotificationsService
   module Emails
     module Welcome
@@ -99,10 +105,9 @@ module NotificationsService
             AcmeEmail::Client.new.deliver(
               to: email_address,
               subject: "Welcome!",
-              text_body: "Welcome to Bookshelf #{name}"
+              text_body: Renderers::Text.new.call(name: name),
+              html_body: Renderers::Html.new.call(name: name)
             )
-
-            Hanami::Logger.new.info("Welcome email to #{email_address} queued for delivery")
           end
         end
       end
@@ -111,13 +116,14 @@ module NotificationsService
 end
 ```
 
-This component has three dependencies, each of which is a "hard coded" reference to a concrete Ruby class:
+This component has four dependencies, each of which is a "hard coded" reference to a concrete Ruby class:
 
 - `Hanami::Settings`, used to check whether email sending is enabled in the current environment.
-- `AcmeEmail::Client`, used to queue the email for delivery via Acme's email service.
-- `Hanami::Logger`, used to log a message that the email has been queued.
+- `AcmeEmail::Client`, used to queue the email for delivery via the third party Acme Email service.
+- `Renderers::Text`, used to render the text version of the welcome email.
+- `Renderers::Html`, used to render the html version of the welcome email.
 
-To make our send welcome email operation more resuable and easier to test, we could instead _inject_ its three dependencies when we initialize it:
+To make our send welcome email operation more resuable and easier to test, we could instead _inject_ its dependencies when we initialize it:
 
 ```ruby title="app/emails/welcome/operations/send.rb"
 # frozen_string_literal: true
@@ -129,12 +135,14 @@ module NotificationsService
         class Send
           attr_reader :email_client
           attr_reader :settings
-          attr_reader :logger
+          attr_reader :text
+          attr_reader :html
 
-          def initialize(email_client:, settings:, logger:)
+          def initialize(email_client:, settings:, text:, html:)
             @email_client = email_client
             @settings = settings
-            @logger = logger
+            @text = text
+            @html = html
           end
 
           def call(name:, email_address:)
@@ -143,10 +151,9 @@ module NotificationsService
             email_client.deliver(
               to: email_address,
               subject: "Welcome!",
-              text_body: "Welcome to Bookshelf #{name}"
+              text_body: text.call(name: name)
+              html_body: html.call(name: name)
             )
-
-            logger.info("Welcome email to #{email_address} queued for delivery")
           end
         end
       end
@@ -155,9 +162,9 @@ module NotificationsService
 end
 ```
 
-As a result of injection, our component no longer has rigid dependencies - it's able to use any email client, settings object or logger we provide to it.
+As a result of injection, our component no longer has rigid dependencies - it's able to use any email client, settings object or renderers we provide.
 
-Hanami makes this style of dependency injection simple through an `include Deps[]` mechanism. Built into the app container (and all slice containers), `include Deps[]` allows components to use any component in their container as a dependency, while removing the need for any attr_reader or initializer boilerplate:
+Hanami makes this style of dependency injection simple through an `include Deps[]` mechanism. Built into the app container (and all slice containers), `include Deps[]` allows a component to use any other component in its container as a dependency, while removing the need for any attr_reader or initializer boilerplate:
 
 ```ruby title="app/emails/welcome/operations/send.rb"
 # frozen_string_literal: true
@@ -167,7 +174,12 @@ module NotificationsService
     module Welcome
       module Operations
         class Send
-          include Deps["email_client", "logger", "settings"]
+          include Deps[
+            "settings",
+            "email_client",
+            "emails.welcome.renderers.text",
+            "emails.welcome.renderers.html"
+          ]
 
           def call(name:, email_address:)
             return unless settings.email_sending_enabled
@@ -175,10 +187,9 @@ module NotificationsService
             email_client.deliver(
               to: email_address,
               subject: "Welcome!",
-              text_body: "Welcome to Bookshelf #{name}"
+              text_body: text.call(name: name),
+              html_body: html.call(name: name)
             )
-
-            logger.info("Welcome email to #{email_address} queued for delivery")
           end
         end
       end
@@ -189,47 +200,52 @@ end
 
 ## Injecting dependencies via `include Deps[]`
 
-In the above example the `include Deps[]` mechanism takes each given key and makes the relevant component from the app container available via an instance method of the same name. i.e. `include Deps["logger"]` makes the `logger` registration from the app container available anywhere in the class via the `#logger` method. (`logger` is automatically provided by Hanami).
+In the above example the `include Deps[]` mechanism takes each given key and makes the relevant component from the app container available via an instance method of the same name. i.e. `include Deps["settings"]` makes the `settings` registration from the app container available anywhere in the class via the `#settings` method. By default, dependencies are made available under a method named after the last segment of their key. So `include Deps["emails.welcome.renderers.html"]` makes the html renderer available via the method `#html`.
 
 We can see `include Deps[]` in action in the console if we instantiate an instance of our send welcome email operation:
 
 ```ruby
 notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new
-=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010e7b2460
- @email_client=#<AcmeEmail::Client:0x000000010e7c01f0>,
- @logger=
-  #<Hanami::Logger:0x000000010e7b82c0
-   @application_name="notifications_service",
-  ...snip...
+=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010c843660
+ @email_client=#<AcmeEmail::Client:0x000000010c808858>,
+ @html=#<NotificationsService::Emails::Welcome::Renderers::Html:0x000000010c843818>,
  @settings=
-  #<NotificationsService::Settings:0x000000010b7efe58
-   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>>
+  #<NotificationsService::Settings:0x000000010c4bf340
+   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>,
+ @text=#<NotificationsService::Emails::Welcome::Renderers::Text:0x000000010c858628>>
 ```
 
 We can provide different dependencies during initialization:
 
 ```ruby
-notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new(logger: "a different logger")
-=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010bc207c0
- @email_client=#<AcmeEmail::Client:0x000000010ba91f30>,
- @logger="a different logger",
+notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new(email_client: "another client")
+=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010c1ded88
+ @email_client="another client",
+ @html=#<NotificationsService::Emails::Welcome::Renderers::Html:0x000000010c1df1c0>,
  @settings=
-  #<NotificationsService::Settings:0x000000010b7efe58
-   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>>
+  #<NotificationsService::Settings:0x000000010c4bf340
+   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true, :acme_api_key=>"sdf"}>>,
+ @text=#<NotificationsService::Emails::Welcome::Renderers::Text:0x000000010c28ca50>>
 ```
 
 This behaviour is particularly useful when testing, as you can substitute one or more components to test behaviour.
 
-In this unit test, we substitute all three dependencies in order to unit test our operations behaviour:
+In this unit test, we substitute each of the operation's dependencies in order to unit test its behaviour:
 
 ```ruby title="spec/unit/emails/welcome/operations/send_spec.rb"
 RSpec.describe NotificationsService::Emails::Welcome::Operations::Send, "#call" do
   subject(:send) {
-    described_class.new(email_client: email_client, settings: settings, logger: logger)
+    described_class.new(
+      email_client: email_client,
+      settings: settings,
+      text: text,
+      html: html
+    )
   }
 
   let(:email_client) { double(:email_client) }
-  let(:logger) { double(:logger) }
+  let(:text) { double(:text, call: "Welcome to Bookshelf Bookshelf user") }
+  let(:html) { double(:html, call: "<p>Welcome to Bookshelf Bookshelf user</p>") }
 
   context "when email sending is enabled" do
     let(:settings) { double(:settings, email_sending_enabled: true) }
@@ -238,11 +254,8 @@ RSpec.describe NotificationsService::Emails::Welcome::Operations::Send, "#call"
       expect(email_client).to receive(:deliver).with(
         to: "email@example.com",
         subject: "Welcome!",
-        text_body: "Welcome to Bookshelf Bookshelf user"
-      )
-
-      expect(logger).to receive(:info).with(
-        "Welcome email to email@example.com queued for delivery"
+        text_body: "Welcome to Bookshelf Bookshelf user",
+        html_body: "<p>Welcome to Bookshelf Bookshelf user</p>"
       )
 
       send.call(name: "Bookshelf user", email_address: "email@example.com")
diff --git a/docs/application-structure/providers.md b/docs/application-architecture/providers.md
similarity index 100%
rename from docs/application-structure/providers.md
rename to docs/application-architecture/providers.md
diff --git a/docs/application-structure/slices.md b/docs/application-architecture/slices.md
similarity index 100%
rename from docs/application-structure/slices.md
rename to docs/application-architecture/slices.md

From 1ca13946003db64561e6e53ae20c0dceb4859e5e Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Tue, 11 Oct 2022 18:24:49 +1100
Subject: [PATCH 05/10] Fix ups.

---
 docs/application-architecture/containers.md | 6 +++---
 docs/application-architecture/providers.md  | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/application-architecture/containers.md b/docs/application-architecture/containers.md
index c6df4a4..88f589b 100644
--- a/docs/application-architecture/containers.md
+++ b/docs/application-architecture/containers.md
@@ -6,11 +6,11 @@ sidebar_position: 1
 
 In Hanami, the application code you add to your `/app` directory is automatically organised into a container. This container forms the basis of a depenency injection system, in which the dependencies of the components you create are provided to them automatically.
 
-Let's take a look at what this means in practice.
+Let's take a look at how this works in practice.
 
 Imagine we're building a Bookshelf notifications service for sending notifications to users of the Bookshelf platform. After running `hanami new notifications_service`, our first task is to send welcome emails. To achieve this, we want to provide a `POST /welcome-emails` action that will send a welcome email, probably via a send welcome operation, which in turn will want to render our email in both html and plain text.
 
-As a first pass, we might add four Ruby classes to our `/app` folder - our action, operation, and two renderers.
+As a first pass, we might add four Ruby classes to our `app` folder - our action, operation, and two renderers.
 
 On the file system, this might look like:
 
@@ -28,7 +28,7 @@ app
             └── text.rb
 ```
 
-When our application boots, Hanami will automatically create instances of these components and register them in its __app container__, under a key based on their Ruby namespace.
+When our application boots, Hanami will automatically create __instances__ of these components and register them in its __app container__, under a key based on their Ruby namespace.
 
 For example, an instance of our `NotificationsService::Emails::Welcome::Operations::Send` class will be registered under the key `"emails.welcome.operations.send"`.
 
diff --git a/docs/application-architecture/providers.md b/docs/application-architecture/providers.md
index dfacbbc..a72d944 100644
--- a/docs/application-architecture/providers.md
+++ b/docs/application-architecture/providers.md
@@ -4,13 +4,13 @@ sidebar_position: 2
 
 # Providers
 
-Providers are a way to register components with your containers, outside of the automatic registration mechanism detailed in [containers and depenencies](/docs/application-structure/containers).
+Providers are a way to register components with your containers, outside of the automatic registration mechanism detailed in [containers and dependencies](/docs/application-architecture/containers).
 
 Providers are useful when:
 
-- you need to set up a dependency that requires non-trivial configuration (often a third party library, or some library-like code in your `/lib` directory)
+- you need to set up a dependency that requires non-trivial configuration (often a third party library, or some library-like code in your `lib` directory)
 - you want to take advantage of provider lifecycle methods (prepare, start and stop)
-- you want to share a component across both your app container and the containers of all your [slices](/docs/application-structure/slices).
+- you want to share a component across both your app container and the containers of all your [slices](/docs/application-architecture/slices).
 
 App-level providers should be placed in the `config/providers` directory. Slices can have their own providers also, placed in `slices/my_slice/providers`.
 

From f70a909c41dcd87f679f89b60f441231abd6065d Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Tue, 11 Oct 2022 23:03:06 +1100
Subject: [PATCH 06/10] Fix ups.

---
 docs/intro.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/intro.md b/docs/intro.md
index 00e646d..b93f869 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -136,7 +136,7 @@ module Bookshelf
 end
 ```
 
-This class allows you to configure application-level behaviours, while also providing a way to do things like booting your application, or starting or stopping your application's [providers](/docs/application-structure/providers).
+This class allows you to configure application-level behaviours, while also providing a way to do things like booting your application, or starting or stopping your application's [providers](/docs/application-architecture/providers).
 
 It's also the interface some core components, such as your application's settings, via `Hanami.app["settings"]`, and its logger, via `Hanami.app["logger"]`.
 
@@ -228,4 +228,4 @@ We'll see most of these commands at play in this guide. For complete information
 
 ## What's next?
 
-Now that we're a little acquainted, let's examine the structure of a Hanami application in more detail through [containers, providers and slices](/docs/category/application-structure).
+Now that we're a little acquainted, let's examine the structure of a Hanami application in more detail through [containers, providers and slices](/docs/category/application-architecture).

From 746a8c62d57159b89c163994727fd6ee498a50b0 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Tue, 11 Oct 2022 23:03:17 +1100
Subject: [PATCH 07/10] Add more content to slices.

---
 docs/application-architecture/slices.md | 255 +++++++++++++++++++++++-
 1 file changed, 249 insertions(+), 6 deletions(-)

diff --git a/docs/application-architecture/slices.md b/docs/application-architecture/slices.md
index b7a9862..e1a5d07 100644
--- a/docs/application-architecture/slices.md
+++ b/docs/application-architecture/slices.md
@@ -4,17 +4,21 @@ sidebar_position: 3
 
 # Slices
 
-In addition to the `/app` directory, Hanami also supports organising your application code into **slices**.
+In addition to the `app` directory, Hanami also supports organising your application code into **slices**.
 
-You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or by feature concern (api or search).
+You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or to separate modules by feature or concern (api or search).
 
-Slices live in the `/slices` directory.
+Slices exist in the `slices` directory.
+## Creating a slice
 
-To create a slice, you can either create a new directory in `/slices`:
+To create a slice, you can either create a new directory in `slices`:
 
-```ruby
+```shell
 mkdir -p slices/admin
 
+slices
+└── admin
+
 bundle exec hanami console
 Admin::Slice
 => Admin::Slice
@@ -26,10 +30,249 @@ Or run `bundle exec hanami generate slice api`, which has the added benefit of a
 bundle exec hanami generate slice api
 
 slices
+├── admin
 └── api
     ├── action.rb
     └── actions
 ```
 
+## Features of a slice
+
+Slices offer much of the same behaviour and features as Hanami's `app` folder.
+
+A Hanami slice:
+
+- has its own container (e.g. `API::Slice.container`)
+- can have its own providers (e.g. `slices/api/providers/my_provider.rb`)
+- can include actions, routable from the application's router
+- can import and export components from other slices
+- can be prepared and booted independently of other slices
+- can have its own slice-specific settings (e.g. `slices/api/config/settings.rb`)
+
+## Slice containers
+
+Like Hanami's `app` folder, components added to a Hanami slice are automatically organised into the slice's container.
+
+For example, suppose our Bookshelf application, which catalogues international books, is in need of an API to return the name, flag, and currency of a given country. We might create a show action in our API slice (by adding the file manually or by running `bundle exec hanami generate action countries.show --slice api`), that looks something like:
+
+```ruby title="slices/api/actions/countries/show.rb"
+# frozen_string_literal: true
+
+require "countries"
+
+module API
+  module Actions
+    module Countries
+      class Show < API::Action
+        include Deps[
+          query: "queries.countries.show"
+        ]
+
+        params do
+          required(:country_code).value(included_in?: ISO3166::Country.codes)
+        end
+
+        def handle(request, response)
+          response.format = format(:json)
+
+          halt 422, {error: "Unprocessable country code"}.to_json unless request.params.valid?
+
+          result = query.call(
+            request.params[:country_code]
+          )
+
+          response.body = result.to_json
+        end
+      end
+    end
+  end
+end
+```
+
+This action checks that the provided country code (`request.params[:country_code]`) is a valid ISO3166 code (using the countries gem) and returns a 422 response if it isn't.
+
+If the code is valid, the action calls the countries show query (by including the `"queries.countries.show"` item from the slice's container - aliased here as `query` for readability). That class might look like:
+
+```ruby title="slices/api/queries/countries/show.rb"
+# frozen_string_literal: true
+
+require "countries"
+
+module API
+  module Queries
+    module Countries
+      class Show
+        def call(country_code)
+          country = ISO3166::Country[country_code]
+
+          {
+            name: country.iso_short_name,
+            flag: country.emoji_flag,
+            currency: country.currency_code
+          }
+        end
+      end
+    end
+  end
+end
+```
+
+As an exercise, as with `Hanami.app` and its app container, we can boot the `API::Slice` to see what its container contains:
+
+```ruby
+bundle exec hanami console
+
+bookshelf[development]> API::Slice.boot
+=> API::Slice
+bookshelf[development]> API::Slice.keys
+=> ["settings",
+ "actions.countries.show",
+ "queries.countries.show",
+ "inflector",
+ "logger",
+ "notifications",
+ "rack.monitor",
+ "routes"]
+```
+
+We can call the query with a country code:
+
+```
+bookshelf[development]> API::Slice["queries.countries.show"].call("UA")
+=> {:name=>"Ukraine", :flag=>"🇺🇦", :currency=>"UAH"}
+```
+
+To add a route for our action, we can add the below to our application's `config/routes.rb` file. This is done for you if you used the action generator.
+
+```ruby title="config/routes.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    root { "Hello from Hanami" }
+
+    slice :api, at: "/api" do
+      get "/countries/:country_code", to: "countries.show"
+    end
+  end
+end
+```
+
+`slice :api` tells the router it can find actions for the routes within the block in the API slice. `at: "/api"` specifies an optional mount point, such the routes in the block each be mounted at `/api`.
+
+After running `bundle exec hanami server`, the endpoint can be hit via a `GET` request to `/api/countries/:country_code`:
+
+```shell
+curl http://localhost:2300/api/countries/AU
+{"name":"Australia","flag":"🇦🇺","currency":"AUD"}
+```
+
+
+# Slice imports and exports
+
+Suppose that our bookshelf application uses a content delivery network (CDN) to serve book covers. While this makes these images fast to download, it does mean that book covers need to be purged from the CDN when they change, in order for freshly updated images to take their place.
+
+Images can be updated in one of two ways: the publisher of the book can sign in and upload a new image, or a Bookshelf staff member can use an admin interface to update an image on the publisher's behalf.
+
+In our bookshelf app, an `Admin` supports the latter functionality, and a `Publisher` slice the former. Both these slices want to trigger a CDN purge when a book cover is updated, but neither slice necessarily needs to know how that's acheived. Instead, a `CDN` slice can manage this operation.
+
+```ruby title="slices/cdn/book_covers/purge.rb"
+module CDN
+  module BookCovers
+    class Purge
+      def call(book_cover_path)
+        puts "Purging #{book_cover_path}"
+        # "Purging logic here!"
+      end
+    end
+  end
+end
+```
+
+To allow slices other than the CDN slice to use this component, we first export it from the CDN.
+
+Any slice can be optionally configured by creating a file at `config/slices/slice_name.rb`.
+
+Here, we configure the CDN slice to export is purge component:
+
+```ruby title="config/slices/cdn.rb"
+module CDN
+  class Slice < Hanami::Slice
+    export ["book_covers.purge"]
+  end
+end
+```
+
+Now, the `Admin` slice can be configured to import _everything_ that the CDN slice exports:
+
+```ruby title="config/slices/admin.rb"
+module Admin
+  class Slice < Hanami::Slice
+    import from: :cdn
+  end
+end
+```
+
+In action in the console:
+
+```ruby
+bundle exec hanami console
+
+bookshelf[development]> Admin::Slice.boot.keys
+=> ["settings",
+ "cdn.book_covers.purge",
+ "inflector",
+ "logger",
+ "notifications",
+ "rack.monitor",
+ "routes"]
+```
+
+In use within an admin slice component:
+
+```ruby title="slices/admin/books/operations/update.rb"
+module Admin
+  module Books
+    module Operations
+      class Update
+        include Deps[
+          "repositories.book_repo",
+          "cdn.book_covers.purge"
+        ]
+
+        def call(id, params)
+          # ... update the book using the book repository ...
+
+          # If the update is successful, purge the book cover from the CDN
+          purge.call(book.cover_path)
+        end
+      end
+    end
+  end
+end
+```
+
+It's also possible to import only specific exports from another slice. Here for example, the `Publisher` slice imports strictly the purge operation, while also - for reasons of its own choosing - using the suffix `content_network` instead of `cdn`:
+
+```ruby title="config/slices/publisher.rb"
+module Publisher
+  class Slice < Hanami::Slice
+    import keys: ["book_covers.purge"], from: :cdn, as: :content_network
+  end
+end
+```
+
+In action in the console:
 
-TODO - the rest of slices :)
+```ruby
+bundle exec hanami console
+
+bookshelf[development]> Publisher::Slice.boot.keys
+=> ["settings",
+ "content_network.book_covers.purge",
+ "inflector",
+ "logger",
+ "notifications",
+ "rack.monitor",
+ "routes"]
+```

From 2e7e75b83e3093d50bcd39dd55775140c41dc246 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Sun, 23 Oct 2022 11:41:37 +1100
Subject: [PATCH 08/10] Revise containers, providers and slices in response to
 feedback.

---
 docs/application-architecture/containers.md | 465 +++++++++++---------
 docs/application-architecture/providers.md  |  74 ++--
 docs/application-architecture/slices.md     |  72 ++-
 3 files changed, 338 insertions(+), 273 deletions(-)

diff --git a/docs/application-architecture/containers.md b/docs/application-architecture/containers.md
index 88f589b..fc9a21d 100644
--- a/docs/application-architecture/containers.md
+++ b/docs/application-architecture/containers.md
@@ -2,303 +2,311 @@
 sidebar_position: 1
 ---
 
-# Containers and dependencies
+# Containers and components
 
-In Hanami, the application code you add to your `/app` directory is automatically organised into a container. This container forms the basis of a depenency injection system, in which the dependencies of the components you create are provided to them automatically.
+In Hanami, the application code you add to your `app` directory is automatically organised into a **container**, which forms the basis of a **component management system**.
 
-Let's take a look at how this works in practice.
+What's a component? A component is an object that's used within your application. For example, a HTTP action for responding to requests, a validation contract for verifying data, an operation for writing to the database, or a client that calls an external API.
 
-Imagine we're building a Bookshelf notifications service for sending notifications to users of the Bookshelf platform. After running `hanami new notifications_service`, our first task is to send welcome emails. To achieve this, we want to provide a `POST /welcome-emails` action that will send a welcome email, probably via a send welcome operation, which in turn will want to render our email in both html and plain text.
+Ideally, each component in your application has a single responsibility. Very often, one component will need to use other components to achieve its work. When this happens, we call those latter components **dependencies**.
 
-As a first pass, we might add four Ruby classes to our `app` folder - our action, operation, and two renderers.
+Hanami is designed to make it easy to create applications that are systems of well-formed components with clear dependencies.
 
-On the file system, this might look like:
+Let's take a look at how this works in practice!
+
+Imagine we want our Bookshelf application to send welcome emails to new users. Assuming that we're already handling user sign ups, our task is now to create an operation for sending the welcome email. We're going to use an external mail delivery service, while sending email in both html and plain text.
+
+To acheive this, we first add two new components to our application: a _send welcome email operation_, and a _welcome email renderer_.
+
+On the file system, this looks like:
 
 ```shell
 app
-├── actions
-│   └── welcome_emails
-│       └── create.rb
-└── emails
-    └── welcome
-        ├── operations
-        │   └── send.rb
-        └── renderers
-            ├── html.rb
-            └── text.rb
+├── operations
+│   └── send_welcome_email.rb
+└── renderers
+    └── welcome_email.rb
 ```
 
-When our application boots, Hanami will automatically create __instances__ of these components and register them in its __app container__, under a key based on their Ruby namespace.
+Sketching out a send welcome email operation component:
+
+```ruby title="app/operations/send_welcome_email.rb"
+# frozen_string_literal: true
 
-For example, an instance of our `NotificationsService::Emails::Welcome::Operations::Send` class will be registered under the key `"emails.welcome.operations.send"`.
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      def call(name:, email_address:)
+        # Send a welcome email to the user here...
+      end
+    end
+  end
+end
+```
 
-```ruby title="app/emails/welcome/operations/send.rb"
+And a welcome email renderer component:
+
+```ruby title="app/renderers/welcome_email.rb"
 # frozen_string_literal: true
 
-module NotificationService
-  module Emails
-    module Welcome
-      module Operations
-        class Send
-          def call(name:, email_address:)
-            puts "Sending greetings to #{name} via #{email_address}!"
-          end
-        end
+module Bookshelf
+  module Renderers
+    class WelcomeEmail
+      def render_html(name:)
+        "<p>Welcome to Bookshelf #{name}!</p>"
+      end
+
+      def render_text(name:)
+        "Welcome to Bookshelf #{name}!"
       end
     end
   end
 end
 ```
 
+When our application boots, Hanami will automatically register these classes as components in its __app container__, each under a __key__ based on their Ruby class name.
+
+This means that an instance of the `Bookshelf::Operations::SendWelcomeEmail` class is available in the container under the key `"operations.send_welcome_email"`, while an instance of `Bookshelf::Renderers::WelcomeEmail` is available under the key `"renderers.welcome_email"`.
+
 We can see this in the Hanami console if we boot our application and ask what keys are registered with the app container:
 
 ```ruby
 bundle exec hanami console
 
-notifications_service[development]> Hanami.app.boot
-=> NotificationsService::App
+bookshelf[development]> Hanami.app.boot
+=> Bookshelf::App
 
-notifications_service[development]> Hanami.app.keys
+bookshelf[development]> Hanami.app.keys
 => ["notifications",
  "settings",
  "routes",
  "inflector",
  "logger",
  "rack.monitor",
- "actions.welcome_emails.create",
- "emails.welcome.operations.send",
- "emails.welcome.renderers.html",
- "emails.welcome.renderers.text"]
+ "operations.send_welcome_email",
+ "renderers.welcome_email"]
  ```
 
-To fetch our welcome email send operation from the container, we ask for it by its `"emails.welcome.operations.send"` key:
+To fetch our welcome email send operation from the container, we can ask for it by its `"operations.send_welcome_email"` key:
+
+```ruby
+bookshelf[development]> Hanami.app["operations.send_welcome_email"]
+=> #<Bookshelf::Operations::SendWelcomeEmail:0x00000001055dadd0>
+```
+
+Similarly we can fetch and call the renderer via the `"renderers.welcome_email"` key:
 
 ```ruby
-notifications_service[development]> Hanami.app["emails.welcome.operations.send"]
-=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010df0a1a0>
+bookshelf[development]> Hanami.app["renderers.welcome_email"]
+=> #<Bookshelf::Renderers::WelcomeEmail:0x000000010577afc8>
 
-notifications_service[development]> Hanami.app["emails.welcome.operations.send"].call(name: "New user", email_address: "email@example.com")
-Sending greetings to New user email@example.com!
+bookshelf[development]> Hanami.app["renderers.welcome_email"].render_html(name: "Ada")
+=> "<p>Welcome to Bookshelf Ada!</p>"
 ```
 
-Most of the time however, you won't use the container directly via `Hanami.app`, but will instead make use of the container through the dependency injection system it supports. Let's see how that works!
+Most of the time however, you won't work with components directly through the container via `Hanami.app`. Instead, you'll work with components through the convenient __dependency injection__ system that having your components in a container supports. Let's see how that works!
 
 ## Dependency injection
 
-Dependency injection is a software pattern where, rather than a component knowing how to instantiate its dependencies, the dependencies are instead provided to it. This means its dependencies can be abstract rather than hard coded, making the component more flexible, reusable and easier to test.
+Dependency injection is a software pattern where, rather than a component knowing how to instantiate its dependencies, those dependencies are instead provided to it. This means the dependencies can be abstract rather than hard coded, making the component more flexible, reusable and easier to test.
 
-To illustrate, here's an example of a welcome email send operation which _doesn't_ use dependency injection:
+To illustrate, here's an example of a send welcome email operation which _doesn't_ use dependency injection:
 
-```ruby title="app/emails/welcome/operations/send.rb"
+```ruby title="app/operations/send_welcome_email.rb"
 # frozen_string_literal: true
 
 require "acme_email/client"
 
-module NotificationsService
-  module Emails
-    module Welcome
-      module Operations
-        class Send
-          def call(name:, email_address:)
-            return unless Hanami::Settings.new.email_sending_enabled
-
-            AcmeEmail::Client.new.deliver(
-              to: email_address,
-              subject: "Welcome!",
-              text_body: Renderers::Text.new.call(name: name),
-              html_body: Renderers::Html.new.call(name: name)
-            )
-          end
-        end
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      def call(name:, email_address:)
+        email_client = AcmeEmail::Client.new
+
+        email_renderer = Renderers::WelcomeEmail.new
+
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: email_renderer.render_text(name: name),
+          html_body: email_renderer.render_html(name: name)
+        )
       end
     end
   end
 end
 ```
 
-This component has four dependencies, each of which is a "hard coded" reference to a concrete Ruby class:
+This component has two dependencies, each of which is a "hard coded" reference to a concrete Ruby class:
 
-- `Hanami::Settings`, used to check whether email sending is enabled in the current environment.
-- `AcmeEmail::Client`, used to queue the email for delivery via the third party Acme Email service.
-- `Renderers::Text`, used to render the text version of the welcome email.
-- `Renderers::Html`, used to render the html version of the welcome email.
+- `AcmeEmail::Client`, used to send an email via the third party Acme Email service.
+- `Renderers::WelcomeEmail`, used to render text and html versions of the welcome email.
 
-To make our send welcome email operation more resuable and easier to test, we could instead _inject_ its dependencies when we initialize it:
+To make this send welcome email operation more resuable and easier to test, we could instead _inject_ its dependencies when we initialize it:
 
-```ruby title="app/emails/welcome/operations/send.rb"
+```ruby title="app/operations/send_welcome_email.rb"
 # frozen_string_literal: true
 
-module NotificationsService
-  module Emails
-    module Welcome
-      module Operations
-        class Send
-          attr_reader :email_client
-          attr_reader :settings
-          attr_reader :text
-          attr_reader :html
-
-          def initialize(email_client:, settings:, text:, html:)
-            @email_client = email_client
-            @settings = settings
-            @text = text
-            @html = html
-          end
-
-          def call(name:, email_address:)
-            return unless settings.email_sending_enabled
-
-            email_client.deliver(
-              to: email_address,
-              subject: "Welcome!",
-              text_body: text.call(name: name)
-              html_body: html.call(name: name)
-            )
-          end
-        end
+require "acme_email/client"
+
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      attr_reader :email_client
+      attr_reader :email_renderer
+
+      def initialize(email_client:, email_renderer:)
+        @email_client = email_client
+        @email_renderer = email_renderer
+      end
+
+      def call(name:, email_address:)
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: email_renderer.render_text(name: name),
+          html_body: email_renderer.render_html(name: name)
+        )
       end
     end
   end
 end
 ```
 
-As a result of injection, our component no longer has rigid dependencies - it's able to use any email client, settings object or renderers we provide.
+As a result of injection, this component no longer has rigid dependencies - it's able to use any email client and email renderer it's provided.
 
-Hanami makes this style of dependency injection simple through an `include Deps[]` mechanism. Built into the app container (and all slice containers), `include Deps[]` allows a component to use any other component in its container as a dependency, while removing the need for any attr_reader or initializer boilerplate:
+Hanami makes this style of dependency injection simple through its `Deps` mixin. Built into the component management system, and invoked through the use of `include Deps["key"]`, the `Deps` mixin allows a component to use any other component in its container as a dependency, while removing the need for any attr_reader or initializer boilerplate:
 
-```ruby title="app/emails/welcome/operations/send.rb"
+```ruby title="app/operations/send_welcome_email.rb"
 # frozen_string_literal: true
 
-module NotificationsService
-  module Emails
-    module Welcome
-      module Operations
-        class Send
-          include Deps[
-            "settings",
-            "email_client",
-            "emails.welcome.renderers.text",
-            "emails.welcome.renderers.html"
-          ]
-
-          def call(name:, email_address:)
-            return unless settings.email_sending_enabled
-
-            email_client.deliver(
-              to: email_address,
-              subject: "Welcome!",
-              text_body: text.call(name: name),
-              html_body: html.call(name: name)
-            )
-          end
-        end
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      include Deps[
+        "email_client",
+        "renderers.welcome_email"
+      ]
+
+      def call(name:, email_address:)
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: welcome_email.render_text(name: name),
+          html_body: welcome_email.render_html(name: name)
+        )
       end
     end
   end
 end
 ```
 
-## Injecting dependencies via `include Deps[]`
+## Injecting dependencies via `Deps`
 
-In the above example the `include Deps[]` mechanism takes each given key and makes the relevant component from the app container available via an instance method of the same name. i.e. `include Deps["settings"]` makes the `settings` registration from the app container available anywhere in the class via the `#settings` method. By default, dependencies are made available under a method named after the last segment of their key. So `include Deps["emails.welcome.renderers.html"]` makes the html renderer available via the method `#html`.
+In the above example, the `Deps` mixin takes each given key and makes the relevant component from the app container available within the current component via an instance method.
 
-We can see `include Deps[]` in action in the console if we instantiate an instance of our send welcome email operation:
+i.e. this code:
 
 ```ruby
-notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new
-=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010c843660
- @email_client=#<AcmeEmail::Client:0x000000010c808858>,
- @html=#<NotificationsService::Emails::Welcome::Renderers::Html:0x000000010c843818>,
- @settings=
-  #<NotificationsService::Settings:0x000000010c4bf340
-   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true}>>,
- @text=#<NotificationsService::Emails::Welcome::Renderers::Text:0x000000010c858628>>
+include Deps[
+  "email_client",
+  "renderers.welcome_email"
+]
 ```
 
-We can provide different dependencies during initialization:
+makes the `"email_client"` component from the container available via an `#email_client` method, and the `"renderers.welcome_email"` component available via `#welcome_email`.
+
+By default, dependencies are made available under a method named after the last segment of their key. So `include Deps["renderers.welcome_email"]` allows us to call `#welcome_email` anywhere in our `SendWelcomeEmail` class access the welcome email renderer.
+
+We can see `Deps` in action in the console if we instantiate an instance of our send welcome email operation:
 
 ```ruby
-notifications_service[development]> NotificationsService::Emails::Welcome::Operations::Send.new(email_client: "another client")
-=> #<NotificationsService::Emails::Welcome::Operations::Send:0x000000010c1ded88
+bookshelf[development]> Bookshelf::Operations::SendWelcomeEmail.new
+=> #<Bookshelf::Operations::SendWelcomeEmail:0x0000000112a93090
+ @email_client=#<AcmeEmail::Client:0x0000000112aa82d8>,
+ @welcome_email=#<Bookshelf::Renderers::WelcomeEmail:0x0000000112a931d0>>
+```
+
+We can choose to provide different dependencies during initialization:
+
+```ruby
+bookshelf[development]> Bookshelf::Operations::SendWelcomeEmail.new(email_client: "another client")
+=> #<Bookshelf::Operations::SendWelcomeEmail:0x0000000112aba8c0
  @email_client="another client",
- @html=#<NotificationsService::Emails::Welcome::Renderers::Html:0x000000010c1df1c0>,
- @settings=
-  #<NotificationsService::Settings:0x000000010c4bf340
-   @config=#<Dry::Configurable::Config values={:email_sending_enabled=>true, :acme_api_key=>"sdf"}>>,
- @text=#<NotificationsService::Emails::Welcome::Renderers::Text:0x000000010c28ca50>>
+ @welcome_email=#<Bookshelf::Renderers::WelcomeEmail:0x0000000112aba9b0>>
 ```
 
 This behaviour is particularly useful when testing, as you can substitute one or more components to test behaviour.
 
 In this unit test, we substitute each of the operation's dependencies in order to unit test its behaviour:
 
-```ruby title="spec/unit/emails/welcome/operations/send_spec.rb"
-RSpec.describe NotificationsService::Emails::Welcome::Operations::Send, "#call" do
-  subject(:send) {
-    described_class.new(
-      email_client: email_client,
-      settings: settings,
-      text: text,
-      html: html
-    )
+```ruby title="spec/unit/operations/send_welcome_email_spec.rb"
+RSpec.describe Bookshelf::Operations::SendWelcomeEmail, "#call" do
+  subject(:send_welcome_email) {
+    described_class.new(email_client: email_client, welcome_email: welcome_email)
   }
 
   let(:email_client) { double(:email_client) }
-  let(:text) { double(:text, call: "Welcome to Bookshelf Bookshelf user") }
-  let(:html) { double(:html, call: "<p>Welcome to Bookshelf Bookshelf user</p>") }
-
-  context "when email sending is enabled" do
-    let(:settings) { double(:settings, email_sending_enabled: true) }
+  let(:welcome_email) { double(:welcome_email) }
 
-    it "delivers an email using the email client" do
-      expect(email_client).to receive(:deliver).with(
-        to: "email@example.com",
-        subject: "Welcome!",
-        text_body: "Welcome to Bookshelf Bookshelf user",
-        html_body: "<p>Welcome to Bookshelf Bookshelf user</p>"
-      )
-
-      send.call(name: "Bookshelf user", email_address: "email@example.com")
-    end
+  before do
+    allow(welcome_email).to receive(:render_text).and_return("Welcome to Bookshelf Ada!")
+    allow(welcome_email).to receive(:render_html).and_return("<p>Welcome to Bookshelf Ada!</p>")
   end
 
-  context "when email sending is not enabled" do
-    let(:settings) { double(:settings, email_sending_enabled: false) }
-
-    it "does not deliver an email" do
-      expect(email_client).not_to receive(:deliver)
+  it "sends a welcome email" do
+    expect(email_client).to receive(:deliver).with(
+      to: "ada@example.com",
+      subject: "Welcome!",
+      text_body: "Welcome to Bookshelf Ada!",
+      html_body: "<p>Welcome to Bookshelf Ada!</p>"
+    )
 
-      send.call(name: "Bookshelf user", email_address: "email@example.com")
-    end
+    send_welcome_email.call(name: "Ada!", email_address: "ada@example.com")
   end
 end
 ```
 
-Exactly which dependency to stub using RSpec mocks is up to you - if a depenency is left out of the constructor within the spec, then the real dependency is resolved from the container. Every test can decide exactly which dependencies to replace.
+Exactly which dependency to stub using RSpec mocks is up to you - if a depenency is left out of the constructor within the spec, then the real dependency is resolved from the container. This means that every test can decide exactly which dependencies to replace.
 
 ## Renaming dependencies
 
-Sometimes you want to use a dependency under another name (either because two dependencies end with the same suffix, or just because it makes things clearer in a different context).
+Sometimes you want to use a dependency under another name, either because two dependencies end with the same suffix, or just because it makes things clearer in a different context.
 
-This can be done with `include Deps[]` like so:
+This can be done by using the `Deps` mixin like so:
 
-```ruby
-module NotificationsService
-  class NewBookNotification
-    include Deps[
-      "settings",
-      send_email_notification: "emails.book_added.operations.send",
-      send_slack_notification: "slack_notifications.book_added.operations.send"
-    ]
-
-    def call(...)
-      send_email_notification.call(...) if settings.email_sending_enabled
-      send_slack_notification.call(...) if settings.slack_sending_enabled
+```ruby title="app/operations/send_welcome_email.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      include Deps[
+        "email_client",
+        email_renderer: "renderers.welcome_email"
+      ]
+
+      def call(name:, email_address:)
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: email_renderer.render_text(name: name),
+          html_body: email_renderer.render_html(name: name)
+        )
+      end
     end
   end
 end
 ```
 
+Above, the welcome email renderer is now available via the `#email_renderer` method, rather than via `#welcome_email`. When testing, the renderer can now be substituted by providing `email_renderer` to the constructor:
+
+```ruby
+subject(:send_welcome_email) {
+  described_class.new(email_client: mock_email_client, email_renderer: mock_email_renderer)
+}
+```
+
 ## Opting out of the container
 
 Sometimes it doesn’t make sense for something to be put in the container. For example, Hanami provides a base action class at `app/action.rb` from which all actions inherit. This type of class will never be used as a dependency by anything, and so registering it in the container doesn’t make sense.
@@ -311,44 +319,103 @@ For once-off exclusions like this Hanami supports a magic comment: `# auto_regis
 
 require "hanami/action"
 
-module NotificationsService
+module Bookshelf
   class Action < Hanami::Action
   end
 end
 ```
 
-Another alternative for classes you do not want to be registered in your container is to place them in `/lib`.
-
-If you have a whole class of objects that shouldn't be placed in your container, you can configure your Hanami application (or slice) to exclude an entire directory from auto registration by adjusting its `no_auto_register_paths` configuration.
+If you have a whole class of objects that shouldn't be placed in your container, you can configure your Hanami application to exclude an entire directory from auto registration by adjusting its `no_auto_register_paths` configuration.
 
-Here for example, the `app/structs` directory is excluded:
+Here for example, the `app/structs` directory is excluded, meaning nothing in the `app/structs` directory will be registered with the container:
 
 ```ruby title="config/app.rb"
 # frozen_string_literal: true
 
 require "hanami"
 
-module NotificationsService
+module Bookshelf
   class App < Hanami::App
     config.no_auto_register_paths << "structs"
   end
 end
 ```
 
-## Container behaviour: prepare vs boot
+A third alternative for classes you do not want to be registered in your container is to place them in the `lib` directory at the root of your project.
 
-Hanami supports a **prepared** state and a **booted** state.
+For example, this `SlackNotifier` class can be used anywhere in your application, and is not registered in the container:
+
+```ruby title="lib/bookshelf/slack_notifier.rb"
+module Bookshelf
+  class SlackNotifier
+    def self.notify(message)
+      # ...
+    end
+  end
+end
+```
+
+```ruby title="app/operations/send_welcome_email.rb"
+# frozen_string_literal: true
+
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      include Deps[
+        "email_client",
+        "renderers.welcome_email"
+      ]
+
+      def call(name:, email_address:)
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: welcome_email.render_text(name: name),
+          html_body: welcome_email.render_html(name: name)
+        )
+
+        SlackNotifier.notify("Welcome email sent to #{email_address}")
+      end
+    end
+  end
+end
+```
+
+
+
+:::tip Autoloading and the `lib` directory
+
+[Zeitwerk](https://github.com/fxn/zeitwerk) autoloading is in place for code you put in `lib/<app_name>`, meaning that you do not need to use a `require` statement before using it.
+
+Code that you place in other directories under `lib` needs to be explicitly required before use.
+
+| Constant location               | Usage                                      |
+|---------------------------------|--------------------------------------------|
+| lib/bookshelf/slack_notifier.rb | Bookshelf::SlackNotifier                   |
+| lib/my_redis/client.rb          | require "my_redis/client"<br /><br />  MyRedis::Client |
+
+:::
+
+## Container compontent loading
+
+Hanami applications support a **prepared** state and a **booted** state.
+
+Whether your app is prepared or booted determines whether components in your app container are _lazily_ loaded on demand, or _eagerly_ loaded up front.
 
 ### Hanami.prepare
 
-When you call `Hanami.prepare` (or use `require "hanami/prepare"`) Hanami will make its app and slices available, but components within containers will be **lazily loaded**.
+When you call `Hanami.prepare` (or use `require "hanami/prepare"`) Hanami will make its app available, but components within the app container will be **lazily loaded**.
 
 This is useful for minimizing load time. It's the default mode in the Hanami console and when running tests.
 
-It can also be very useful when running Hanami in serverless environments where boot time matters, such as on AWS Lambda, as Hanami will instantiate only the components needed to satisfy a particular web request or operation.
-
 ### Hanami.boot
 
-When you call `Hanami.boot` (or use `require "hanami/boot"`) Hanami will go one step further and **eagerly load** all components in all containers up front.
+When you call `Hanami.boot` (or use `require "hanami/boot"`) Hanami will go one step further and **eagerly load** all components up front.
+
+This is useful in contexts where you want to incur initialization costs at boot time, such as when preparing your application to serve web requests. It's the default when running via Hanami's puma setup (see `config.ru`).
+
+## What's next?
+
+Reading the above examples, you may have wondered where the `"email_client"` component came from, given it wasn't defined in the `app` directory.
 
-This is useful in contexts where you want to incur initialization costs up front, such as when preparing your application to serve web requests. It's the default when running via Hanami's puma setup (see `config.ru`).
+Hanami offers a mechanism called **providers** for adding components to a container outside of the auto-registration process. We'll look at providers next.
diff --git a/docs/application-architecture/providers.md b/docs/application-architecture/providers.md
index a72d944..9c756be 100644
--- a/docs/application-architecture/providers.md
+++ b/docs/application-architecture/providers.md
@@ -4,17 +4,15 @@ sidebar_position: 2
 
 # Providers
 
-Providers are a way to register components with your containers, outside of the automatic registration mechanism detailed in [containers and dependencies](/docs/application-architecture/containers).
+Providers are a way to register components with your containers, outside of the automatic registration mechanism detailed in [containers and components](/docs/application-architecture/containers).
 
 Providers are useful when:
 
+- you want to register a specific instance of an object as a component, and have that very same instance be available as a dependency
 - you need to set up a dependency that requires non-trivial configuration (often a third party library, or some library-like code in your `lib` directory)
 - you want to take advantage of provider lifecycle methods (prepare, start and stop)
-- you want to share a component across both your app container and the containers of all your [slices](/docs/application-architecture/slices).
 
-App-level providers should be placed in the `config/providers` directory. Slices can have their own providers also, placed in `slices/my_slice/providers`.
-
-Here's an example provider for that registers an email client in the app container, using an imagined third-party Acme Email service.
+Providers should be placed in the `config/providers` directory. Here's an example provider for that registers a client for an imagined third-party Acme Email delivery service.
 
 ```ruby title="config/providers/email_client.rb"
 # frozen_string_literal: true
@@ -35,44 +33,46 @@ Hanami.app.register_provider(:email_client) do
 end
 ```
 
-The above provider initializes an instance of Acme's email client, providing an api key from the application's setting as well as a default from address, then registers the client in the app container with the key `"email_client"`.
+The above provider creates an instance of Acme's email client, using an API key from our application's settings, then registers the client in the app container with the key `"email_client"`.
 
-The registered dependency can now be used in app components, via `include Deps["email_client"]`:
+The registered dependency can now become a dependency for other components, via `include Deps["email_client"]`:
 
-```ruby title="app/emails/welcome/operations/send.rb"
+```ruby title="app/operations/send_welcome_email.rb"
 # frozen_string_literal: true
 
-module NotificationsService
-  module Emails
-    module Welcome
-      module Operations
-        class Send
-          include Deps["email_client", "settings"]
-
-          def call(name:, email_address:)
-            return unless settings.email_sending_enabled
-
-            email_client.deliver(
-              to: email_address,
-              subject: "Welcome!",
-              text_body: "Welcome to Bookshelf #{name}"
-            )
-          end
-        end
+module Bookshelf
+  module Operations
+    class SendWelcomeEmail
+      include Deps[
+        "email_client",
+        "renderers.welcome_email"
+      ]
+
+      def call(name:, email_address:)
+        email_client.deliver(
+          to: email_address,
+          subject: "Welcome!",
+          text_body: welcome_email.render_text(name: name),
+          html_body: welcome_email.render_html(name: name)
+        )
       end
     end
   end
 end
 ```
 
-Every provider has a name (`Hanami.app.register_provider(:my_provider_name)`) and registers _one or more_ related components with the relevant container. Registered items are not limited to objects - they can be classes too.
+Every provider has a name (`Hanami.app.register_provider(:my_provider_name)`) and will usually register _one or more_ related components with the relevant container.
+
+Registered components can be any kind of object - they can be classes too.
+
+To register an item with the container, providers call `register`, which takes two arguments: the _key_ to be used, and the _item_ to register under it.
 
-```ruby title="config/providers/something_provider.rb"
+```ruby title="config/providers/my_provider.rb"
 # frozen_string_literal: true
 
-Hanami.app.register_provider(:something_provider) do
+Hanami.app.register_provider(:my_provider) do
   start do
-    register "something", Something.new
+    register "my_thing", MyThing.new
     register "another.thing", AnotherThing.new
     register "thing", Thing
   end
@@ -83,16 +83,16 @@ end
 
 Providers offer a three-stage lifecycle: `prepare`, `start`, and `stop`. Each has a distinct purpose:
 
-- prepare - basic setup code, here you can require 3rd party code and perform basic configuration
+- prepare - basic setup code, here you can require third-party code, or code from your `lib` directory, and perform basic configuration
 - start - code that needs to run for a component to be usable at runtime
 - stop - code that needs to run to stop a component, perhaps to close a database connection, or purge some artifacts.
 
 ```ruby title="config/providers/database.rb"
 Hanami.app.register_provider(:database) do
   prepare do
-    require "3rd_party/db"
+    require "acme/db"
 
-    register "database", 3rdParty::DB.configure(target["settings"].database_url)
+    register "database", Acme::DB.configure(target["settings"].database_url)
   end
 
   start do
@@ -105,17 +105,17 @@ Hanami.app.register_provider(:database) do
 end
 ```
 
-Lifecycle steps will not run until a provider is required by another component, is started directly, or when the container finalizes as a result of Hanami booting.
+A provider's prepare and start steps will run as necessary when a component that the provider registers is used by another component at runtime.
 
-`Hanami.boot` and `Hanami.shutdown` call `start` and `stop` respectively on each of the application’s registered providers.
+`Hanami.boot` calls `start` on each of your application’s providers, meaning each of your providers is started automatically when your application boots. Similarly, `Hanami.shutdown` can be invoked to call `stop` on each provider.
 
-Lifecycle transitions can be triggered directly by using `Hanami.app.container.prepare(:provider_name)`, `Hanami.app.container.start(:provider_name)` and `Hanami.app.container.stop(:provider_name)`.
+You can also trigger lifecycle transitions directly by using `Hanami.app.prepare(:provider_name)`, `Hanami.app.start(:provider_name)` and `Hanami.app.stop(:provider_name)`.
 
 ## Accessing the container via `#target`
 
-Within a provider, the `target` method (also available as `target_container`) can be used to access the container (either the app container, or, if the provider is specific to a slice, the slice's container).
+Within a provider, the `target` method (also available as `target_container`) can be used to access the app container.
 
-This is useful for accessing the application's settings or logger (via `target["settings]` and `target["logger"]`). It can also be used when a provider wants to ensure another provider has started before starting itself, via `target.start(:provider_name)`:
+This is useful if your provider needs to use other components within the container, for example the application's settings or logger (via `target["settings]` and `target["logger"]`). It can also be used when a provider wants to ensure another provider has started before starting itself, via `target.start(:provider_name)`:
 
 ```ruby title="config/providers/uploads_bucket"
 Hanami.app.register_provider(:uploads_bucket) do
diff --git a/docs/application-architecture/slices.md b/docs/application-architecture/slices.md
index e1a5d07..22c8145 100644
--- a/docs/application-architecture/slices.md
+++ b/docs/application-architecture/slices.md
@@ -6,34 +6,31 @@ sidebar_position: 3
 
 In addition to the `app` directory, Hanami also supports organising your application code into **slices**.
 
-You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or to separate modules by feature or concern (api or search).
+You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or to have separate modules for a particular feature (API) or technical concern (search).
 
 Slices exist in the `slices` directory.
 ## Creating a slice
 
-To create a slice, you can either create a new directory in `slices`:
+Hanami provides a slice generator. To create an API slice, run `bundle exec hanami generate slice api`.
+
+This creates a directory in `slices`, adding some slice-specific classes like actions:
 
 ```shell
-mkdir -p slices/admin
+bundle exec hanami generate slice api
 
 slices
-└── admin
-
-bundle exec hanami console
-Admin::Slice
-=> Admin::Slice
+└── api
+    ├── action.rb
+    └── actions
 ```
 
-Or run `bundle exec hanami generate slice api`, which has the added benefit of adding some slice-specific classes, like actions:
+Simply creating a new directory in `slices` will also create a slice:
 
 ```shell
-bundle exec hanami generate slice api
+mkdir -p slices/admin
 
 slices
-├── admin
-└── api
-    ├── action.rb
-    └── actions
+└── admin
 ```
 
 ## Features of a slice
@@ -42,7 +39,7 @@ Slices offer much of the same behaviour and features as Hanami's `app` folder.
 
 A Hanami slice:
 
-- has its own container (e.g. `API::Slice.container`)
+- has its own container
 - can have its own providers (e.g. `slices/api/providers/my_provider.rb`)
 - can include actions, routable from the application's router
 - can import and export components from other slices
@@ -53,7 +50,7 @@ A Hanami slice:
 
 Like Hanami's `app` folder, components added to a Hanami slice are automatically organised into the slice's container.
 
-For example, suppose our Bookshelf application, which catalogues international books, is in need of an API to return the name, flag, and currency of a given country. We might create a show action in our API slice (by adding the file manually or by running `bundle exec hanami generate action countries.show --slice api`), that looks something like:
+For example, suppose our Bookshelf application, which catalogues international books, needs an API to return the name, flag, and currency of a given country. We can create a countries show action in our API slice (by running `bundle exec hanami generate action countries.show --slice api` or by adding the file manually) that looks like:
 
 ```ruby title="slices/api/actions/countries/show.rb"
 # frozen_string_literal: true
@@ -89,9 +86,9 @@ module API
 end
 ```
 
-This action checks that the provided country code (`request.params[:country_code]`) is a valid ISO3166 code (using the countries gem) and returns a 422 response if it isn't.
+This action uses the countries gem to check that the provided country code (`request.params[:country_code]`) is a valid ISO3166 code and returns a 422 response if it isn't.
 
-If the code is valid, the action calls the countries show query (by including the `"queries.countries.show"` item from the slice's container - aliased here as `query` for readability). That class might look like:
+If the code is valid, the action calls the countries show query (aliased here as `query` for readability). That class might look like:
 
 ```ruby title="slices/api/queries/countries/show.rb"
 # frozen_string_literal: true
@@ -174,14 +171,13 @@ Suppose that our bookshelf application uses a content delivery network (CDN) to
 
 Images can be updated in one of two ways: the publisher of the book can sign in and upload a new image, or a Bookshelf staff member can use an admin interface to update an image on the publisher's behalf.
 
-In our bookshelf app, an `Admin` supports the latter functionality, and a `Publisher` slice the former. Both these slices want to trigger a CDN purge when a book cover is updated, but neither slice necessarily needs to know how that's acheived. Instead, a `CDN` slice can manage this operation.
+In our bookshelf app, an `Admin` slice supports the latter functionality, and a `Publisher` slice the former. Both these slices want to trigger a CDN purge when a book cover is updated, but neither slice needs to know exactly how that's achieved. Instead, a `CDN` slice can manage this operation.
 
 ```ruby title="slices/cdn/book_covers/purge.rb"
 module CDN
   module BookCovers
     class Purge
       def call(book_cover_path)
-        puts "Purging #{book_cover_path}"
         # "Purging logic here!"
       end
     end
@@ -189,21 +185,9 @@ module CDN
 end
 ```
 
-To allow slices other than the CDN slice to use this component, we first export it from the CDN.
+Slices can be configured by creating a file at `config/slices/slice_name.rb`.
 
-Any slice can be optionally configured by creating a file at `config/slices/slice_name.rb`.
-
-Here, we configure the CDN slice to export is purge component:
-
-```ruby title="config/slices/cdn.rb"
-module CDN
-  class Slice < Hanami::Slice
-    export ["book_covers.purge"]
-  end
-end
-```
-
-Now, the `Admin` slice can be configured to import _everything_ that the CDN slice exports:
+To configure the `Admin` slice to import components from the CDN container (including the purge component above), we can create a `config/slices/admin.rb` file with the following configuration:
 
 ```ruby title="config/slices/admin.rb"
 module Admin
@@ -213,7 +197,7 @@ module Admin
 end
 ```
 
-In action in the console:
+Let's see this import in action in the console, where we can see that the `Admin` slices's container now has a `"cdn.book_covers.purge"` component:
 
 ```ruby
 bundle exec hanami console
@@ -228,7 +212,7 @@ bookshelf[development]> Admin::Slice.boot.keys
  "routes"]
 ```
 
-In use within an admin slice component:
+Using the purge operation from the `CDN` slice within the `Admin` slice component below is now as simple as using the `Deps` mixin:
 
 ```ruby title="slices/admin/books/operations/update.rb"
 module Admin
@@ -252,7 +236,7 @@ module Admin
 end
 ```
 
-It's also possible to import only specific exports from another slice. Here for example, the `Publisher` slice imports strictly the purge operation, while also - for reasons of its own choosing - using the suffix `content_network` instead of `cdn`:
+It's also possible to import only specific components from another slice. Here for example, the `Publisher` slice imports strictly the purge operation, while also - for reasons of its own choosing - using the suffix `content_network` instead of `cdn`:
 
 ```ruby title="config/slices/publisher.rb"
 module Publisher
@@ -276,3 +260,17 @@ bookshelf[development]> Publisher::Slice.boot.keys
  "rack.monitor",
  "routes"]
 ```
+
+Slices can also limit what they make available for export to other slices.
+
+Here, we configure the CDN slice to export only its purge component:
+
+```ruby title="config/slices/cdn.rb"
+module CDN
+  class Slice < Hanami::Slice
+    export ["book_covers.purge"]
+  end
+end
+```
+
+TODO: the rest of slices :)

From c7e07e5ab16dd59d81fc2ecc6375255366306cbd Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Sat, 29 Oct 2022 08:12:06 +1100
Subject: [PATCH 09/10] Tweak components.

---
 docs/application-architecture/containers.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/application-architecture/containers.md b/docs/application-architecture/containers.md
index fc9a21d..a775b78 100644
--- a/docs/application-architecture/containers.md
+++ b/docs/application-architecture/containers.md
@@ -6,9 +6,9 @@ sidebar_position: 1
 
 In Hanami, the application code you add to your `app` directory is automatically organised into a **container**, which forms the basis of a **component management system**.
 
-What's a component? A component is an object that's used within your application. For example, a HTTP action for responding to requests, a validation contract for verifying data, an operation for writing to the database, or a client that calls an external API.
+The **components** within that system are the objects you create to get things done within your application. For example, a HTTP action for responding to requests, a validation contract for verifying data, an operation for writing to the database, or a client that calls an external API.
 
-Ideally, each component in your application has a single responsibility. Very often, one component will need to use other components to achieve its work. When this happens, we call those latter components **dependencies**.
+Ideally, each component in your application has a single responsibility. Very often, one component will need to use other components to achieve its work. When this happens, we call the latter components **dependencies**.
 
 Hanami is designed to make it easy to create applications that are systems of well-formed components with clear dependencies.
 

From c3cc1e222634d6821c348ae1b503ad1bdb75f0a8 Mon Sep 17 00:00:00 2001
From: Andrew Croome <andrewcroome@gmail.com>
Date: Fri, 4 Nov 2022 15:57:51 +1100
Subject: [PATCH 10/10] Update routing - still WIP. Borrows from material
 written by @swilgosz

---
 docs/http-handling/routing.md | 216 ++++++++++++++++++++++++++++++----
 1 file changed, 196 insertions(+), 20 deletions(-)

diff --git a/docs/http-handling/routing.md b/docs/http-handling/routing.md
index f485f44..e77486e 100644
--- a/docs/http-handling/routing.md
+++ b/docs/http-handling/routing.md
@@ -2,13 +2,11 @@
 sidebar_position: 1
 ---
 
-# Routing
+# Routing and actions
 
-Hanami provides a fast, simple router for handling http requests.
+Hanami provides a fast, simple [router](https://github.com/hanami/router) for handling HTTP requests.
 
-To add a route to your application, define it in your `Routes` class in the `config/routes.rb` file.
-
-If you ran `hanami new bookshelf`, your `config/routes.rb` file will look like this:
+Your application's routes are defined within the `Routes` class in the `config/routes.rb` file.
 
 ```ruby title="config/routes.rb"
 # frozen_string_literal: true
@@ -20,38 +18,56 @@ module Bookshelf
 end
 ```
 
-## Composing a route
+## Adding a route
+
+Each route in Hanami's router is comprised of:
 
-In the Hanami router, each route is comprised of:
 - a HTTP method (i.e. `get`, `post`, `put`, `patch`, `delete`, `options` or `trace`)
 - a path
 - an endpoint to be invoked.
 
-Endpoints are usually actions within your application, but they can also be a block, a rack application, or anything that responds to `#call`.
+Endpoints are usually actions within your application, but they can also be a block, a [Rack](https://github.com/rack/rack) application, or anything that responds to `#call`.
 
 ```ruby title="Example routes"
-get "/authors", to: "authors.index"
-get "/authors/:id", to: "authors.show"
-post "/authors", to: "authors.create"
-put "/authors/:id", to: "authors.update"
+get "/books", to: "books.index"  # Invokes the Bookshelf::Actions:Books::Index action
+post "/books", to: "books.create" # Invokes the Bookshelf::Actions:Books::Create action
 get "/rack-app", to: RackApp.new
+get "/my-lambda", to: ->(env) { [200, {}, ["A Rack compatible response"]] }
+```
+
+To add a full set of routes for viewing and managing books, you can either manually add the required routes to your `config/routes.rb` file, or use Hanami's action generator, which will generate actions in addition to adding routes for you.
+
+```shell title="Using Hanami's action generator"
+bundle exec hanami generate action books.index
+bundle exec hanami generate action books.show
+bundle exec hanami generate action books.new
+bundle exec hanami generate action books.create
+bundle exec hanami generate action books.update
+bundle exec hanami generate action books.destroy
 ```
 
-A root method defines a root route for handling GET requests to "/". Above, the root path calls a block which returns "Hello from Hanami". You can also invoke an action for root requests by specifying `root to: "my_action"`. For example to invoke a `"home"` action:
 
 ```ruby title="config/routes.rb"
 # frozen_string_literal: true
 
 module Bookshelf
   class Routes < Hanami::Routes
-    root to: "home"
+    root { "Hello from Hanami" }
+
+    get "/books", to: "books.index"
+    get "/books/:id", to: "books.show"
+    get "/books/new", to: "books.new"
+    post "/books", to: "books.create"
+    patch "/books/:id", to: "books.update"
+    delete "/books/:id", to: "books.destroy"
   end
 end
 ```
 
-Let's add three routes to our bookshelf application: one for listing an index of books, one for showing a particular book, and one for creating a new book.
 
-[Actually, let's add full set of CRUD here to show that off]
+## Root request routing
+
+A `root` method allows you to define a root route for handling `GET` requests to `"/"`. In a newly generated application, the root path calls a block which returns "Hello from Hanami". You can instead choose to invoke an action by specifying `root to: "my_action"`. For example, with the following configuration, the router will invoke the `"home"` action:
 
 ```ruby title="config/routes.rb"
 # frozen_string_literal: true
@@ -59,21 +75,181 @@ Let's add three routes to our bookshelf application: one for listing an index of
 module Bookshelf
   class Routes < Hanami::Routes
     root to: "home"
+  end
+end
+```
 
-    get "/books", to: "books.index"
-    get "/books/:id", to: "books.show"
-    post "/books", to: "books.create"
+## Path matching
+
+The path component of a route supports matching on fixed strings, as well as matching with dynamic variables which can be accessed in Hanami actions via `request.params[:name]`, where `:name` matches the segment's name specified in the path.
+
+### Fixed paths
+
+The following route matches `GET` requests for `"/books"` exactly:
+
+```ruby
+get "/books", to: "books.index"
+```
+
+### Dynamic segments
+
+The path `"/books/:id"` matches `GET` requests like `"/books/1"`:
+
+```ruby
+get "/books/:id", to: "books.show"
+
+# GET /books/1
+# request.params[:id] <-- 1
+```
+
+### Multiple dynamic segments
+
+Paths support multiple dynamic segments. For example, the path `"/books/:book_id/reviews/:id"` matches `GET` requests like `"/books/17/reviews/6"`:
+
+```ruby
+get "/books/:book_id/reviews/:id", to: "book_reviews.show"
+
+# GET /books/17/reviews/6
+# request.params[:book_id] <-- 17
+# request.params[:id] <-- 6
+```
+
+Here's what accessing these variables looks like in a Hanami action:
+
+```ruby title="Route, matching request and resulting params"
+# Route: get "/books/:book_id/reviews/:id", to: "book_reviews.show"
+
+# Request: GET /books/17/reviews/6
+
+module Bookshelf
+  module Actions
+    module BookReviews
+      class Show < Bookshelf::Action
+        def handle(request, response)
+          request.params[:book_id] # 17
+          request.params[:id] # 6
+        end
+      end
+    end
+  end
+end
+```
+
+### Constraints
+
+Constraints can be added when matching variables. Contraints are regular expressions that must match in order for the route to match. They can be useful for ensuring that ids are digits:
+
+```ruby
+get "/books/:id", id: /\d+/, to: "books.show"
+
+# GET /books/2 # matches
+# GET /books/two # will not match
+```
+
+### Globbing and catch all routes
+
+Catch all routes can be added using globbing. These can be used to handle requests that do not match preceeding routes.
+
+For example, in the absence of an earlier matching route, `"/pages/*match"` will match requests for paths like `"/pages/2022/my-page"`:
+
+```ruby
+get "/pages/*path", to: "page_catch_all"
+
+# GET /pages/2022/my-page will invoke the Bookshelf::Actions::PageCatchAll action
+# request.params[:path] # <-- 2022/my-page
+```
+
+To create a catch all to handle all unmatched `GET` requests using a custom `"unmatched"` action, configure this route last:
+
+```ruby
+get "/*path", to: "unmatched"
+```
+
+## Named routes
+
+Routes can be named using the `as` option.
+
+```
+get "/books", to: "books.index", as: :books
+get "/books/:id", to: "books.show", as: :book
+```
+
+This enables `path` and `url` helpers, which can be accessed via the routes helper registered under `"routes"` within your application.
+
+```ruby
+Hanami.app["routes"].path(:books)
+=> "/books"
+
+Hanami.app["routes"].url(:books)
+=> #<URI::HTTP http://0.0.0.0:2300/books>
+```
+
+When a route requires variables, they can be passed to the helper:
+
+```ruby
+Hanami.app["routes"].path(:book, id: 1)
+=> "/books/1"
+
+Hanami.app["routes"].url(:book, id: 1)
+=> #<URI::HTTP http://0.0.0.0:2300/books/1>
+```
+
+
+To set a base URL for the `url` helper, configure it in `config/app.rb`:
+
+```ruby title="config/app.rb"
+# frozen_string_literal: true
+
+require "hanami"
+
+module Bookshelf
+  class App < Hanami::App
+    config.base_url = "https://bookshelf.example.com"
   end
 end
 ```
 
-Hanami provides a `hanami routes` command to inspect your application's routes. Let's run `bundle exec hanami routes` on the command line after adding our new routes:
+```ruby
+Hanami.app["routes"].url(:book, id: 1)
+=> #<URI::HTTP https://bookshelf.example.com/books/1>
+```
+
+## Scopes
+
+To nest a series of routes under a particular path, you can set a scope:
+
+```ruby
+# frozen_string_literal: true
+
+module Bookshelf
+  class Routes < Hanami::Routes
+    scope "about" do
+      get "/contact-us", to: "content.contact_us" # <-- /about/contact-us
+      get "/faq", to: "content.faq" # <-- /about/faq
+    end
+  end
+end
+```
+
+
+
+## Inspecting routes
+
+Hanami provides a `hanami routes` command to inspect your application's routes. Run `bundle exec hanami routes` on the command line to view current routes:
 
 ```shell title="bundle exec hanami routes"
 GET     /                             home                          as :root
 GET     /books                        books.index
 GET     /books/:id                    books.show
+GET     /books/new                    books.new
 POST    /books                        books.create
+PATCH   /books/:id                    books.update
+DELETE  /books/:id                    books.destroy
 ```
 
 TODO: the rest of routing :)
+
+
+
+
+At the end, say - how does this action stuff wire up? Via the container. What is dat - let's see next...