belt 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1436a1cb03096bd9de50abd65ecfbb973fc0f054c7e45902bdadd78516806a0c
-  data.tar.gz: 88ddfe6f1b1789a539bd71d407a736514ef091d2b126fc8c3296e5ee2f4e23ca
+  metadata.gz: f29c42b3eb7869a90ab1a0a22d56fd6b1304dbd6e22f32503669b3c9b0974890
+  data.tar.gz: f313115ee77ceafb82a4c424c6721f6776f3b869c1b71cc1e458332bc16b53fd
 SHA512:
-  metadata.gz: a5e7bee23ca7077b19273c9c7605da6c42a1ec8226332d629a6d7a51b9f3ece913cc415005b905a32774eb0b8e47159fa2abeee08e5b3b4888008981a116ad82
-  data.tar.gz: 33ffbdc6d97e3600f09d90877d0edde784f2d5b377d3250d4044ff456256ecb7642936f7c4531b47dc88d7be69c6160e3b694873a6f7d712fb532e62cbb97d85
+  metadata.gz: 57150cb2d0934d723b6fafb9eaee652dc933c4522fcae787518d2e03990da13e1c9f229d498b990a86fb1daa90ec3916e4e049e411a418a4534e76f4274a658e
+  data.tar.gz: 8e2d42b8ba9417dacdf725a66cc0e0a0d37e3a7ae59c3085a50f40c7c1e38eb298be49fa0a0ac3d3489e445e3907d85174bc07f45959a385ccbe55a605a5016d

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## Unreleased
+## 0.4.6
+
+### Added
+
+- **Agent Skill (`SKILL.md`) — installable via `npx skills add stowzilla/belt`.**
+  A root-level `SKILL.md` with trigger-rich frontmatter, a lean activation body
+  (core patterns + decision guide), and on-demand `references/` docs (CLI, routing,
+  controllers, models+auth, deploy/ops, plugins). A CI workflow validates the
+  frontmatter and that every reference link resolves.
+- **`SKILL.md` + `references/` now ship inside the `belt` gem.** The gemspec
+  `files` manifest was extended so a `gem install belt` lands the skill on disk
+  alongside the runtime. The `skills` CLI resolves git repos and local paths (not
+  RubyGems), so a gem install won't *auto-register* the skill — but the files are
+  present and can be picked up via a local-path install
+  (`npx skills add <gem-install-dir>`), and belt.dev tooling can vendor them.
 
 ### Bug Fix
 

data/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: belt
+license: MIT
+description: >-
+  Build, run, and deploy serverless Ruby apps on AWS Lambda with the Belt
+  framework (Rails-inspired). Use when working in a Belt app or the belt gem:
+  scaffolding apps/models/controllers/frontends, defining routes with the
+  Belt routing DSL, writing BeltController actions, modeling DynamoDB data
+  with ActiveItem, wiring Cognito auth, configuring the Lambda handler,
+  running `belt` CLI commands (new, generate, deploy, console, routes, logs,
+  server, setup, plugin, explain, db:copy/db:seed), Terraform via belt,
+  backups, observability, or authoring Belt plugins. Triggers on "belt new",
+  "belt deploy", "belt generate", "belt routes", "BeltController", "ActiveItem",
+  "Belt::LambdaHandler", "belt console", "belt server", "conveyor-belt". Do NOT
+  activate for physical belts, conveyor hardware, or unrelated Ruby web
+  frameworks like Rails/Sinatra outside a Belt project.
+metadata:
+  author: stowzilla
+  version: "0.1.0"
+---
+
+# Belt
+
+Belt is a Rails-inspired framework for serverless Ruby on AWS Lambda. It ships a
+runtime (`BeltController`, `Belt::LambdaHandler`, `Belt::ActionRouter`,
+`Belt::Authentication`), a DynamoDB ORM (`ActiveItem`), logging/metrics
+(`lambda_loadout`), a routing DSL consumed by the **conveyor-belt** Terraform
+provider, and a `belt` CLI. Optional features (`belt-messaging`, `belt-pay`)
+ship as separate plugin gems.
+
+## First: orient yourself
+
+Belt has an authoritative, in-repo docs system. **Use it before guessing.**
+
+```bash
+belt explain <topic>   # routing controllers models deployment generators
+                       # lambda_handler observability console backups
+                       # data_seeding plugins structure frontend authentication
+belt --help            # full command list
+belt routes            # list every endpoint (verb, path, controller#action)
+belt doctor            # check deps + AWS config
+```
+
+- **Working in a Belt app?** Read the app's own `AGENTS.md` (scaffolded by `belt new`).
+- **Working on the belt gem itself?** Read `AGENTS.md` + `README.md` at the gem root.
+- The `belt explain` docs live at `lib/belt/docs/*.md` in the gem — the single
+  source of truth for CLI behavior, controller lifecycle, and routing.
+
+## Decision guide
+
+| I want to… | Do this |
+|---|---|
+| Scaffold an app | `belt new <name> --frontend react` |
+| Add a resource | `belt generate scaffold post title:string body:text` |
+| See all routes | `belt routes` (add `-f json` for tooling) |
+| Deploy to AWS | `belt deploy <env>` (`--auto` to skip prompt) |
+| Poke at data live | `belt console <env>` |
+| Run a local frontend | `belt server` (see references for env targeting) |
+| Add Cognito auth | `belt generate auth` → `cognito_authenticatable` in a model |
+| Build a plugin | `belt plugin new <name>` |
+| Learn a concept | `belt explain <topic>` |
+
+## Core patterns (memorize these)
+
+**Controller** — assigns become the JSON body; explicit helpers win.
+
+```ruby
+class PostsController < BeltController::Base
+  before_action :authenticate_user!
+
+  def index
+    @posts = Post.where(user_id: current_user.id, index: "UserIndex")
+  end
+
+  def create
+    @post = Post.create!(params.require(:post).permit(:title, :body).to_h)
+    response_status :created   # → 201 + { post: {...} }
+  end
+
+  def destroy
+    Post.find(params["id"]).destroy
+    head :no_content
+  end
+end
+```
+
+**Model** — ActiveItem over DynamoDB.
+
+```ruby
+class Post < ActiveItem::Base
+  self.primary_key = :id
+  attr_accessor :id, :user_id, :title, :body, :created_at
+  validates :title, presence: true
+  before_create { self.id ||= SecureRandom.uuid }
+end
+```
+
+**Routes DSL** — `infrastructure/routes.tf.rb`. `gateway`/`function` pick the
+Lambda; `namespace`/`scope` only affect paths + controller module.
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api, auth: :cognito do
+    resources :posts do
+      member     { post :publish }     # /posts/:post_id/publish
+      collection { get  :recent }       # /posts/recent
+    end
+  end
+end
+```
+
+**Lambda entry point** — `Belt::LambdaHandler` gives observability, CORS
+preflight, JSON parsing, and error wrapping for free.
+
+```ruby
+require "belt"
+include Belt::LambdaHandler
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, gateway: "api")
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+```
+
+## Golden rules for agents
+
+1. **`belt explain <topic>` before inventing behavior.** The docs are canonical.
+2. **`namespace`/`scope` never change which Lambda serves a route** — only
+   `gateway` and `function` do. Do not conflate them.
+3. **Controllers need no registration.** Belt discovers them by convention.
+4. **Runtime code stays in gems; generators copy only what the app must own.**
+5. **Never commit secrets** (`.env`, AWS keys, real account IDs).
+6. **`rubocop` + `rspec` must pass** before a PR on the belt gem.
+
+## Deeper references
+
+Load these only when the task needs them:
+
+- [references/cli.md](references/cli.md) — every `belt` command, flags, env vars, Terraform shorthand
+- [references/routing.md](references/routing.md) — full routing DSL, nested resources, request/response model inference
+- [references/controllers.md](references/controllers.md) — callbacks, strong params, responses, error handling, formats
+- [references/models-and-auth.md](references/models-and-auth.md) — ActiveItem + Cognito authentication
+- [references/deploy-and-ops.md](references/deploy-and-ops.md) — deploy lifecycle, environments, backups, seeding, observability
+- [references/plugins.md](references/plugins.md) — authoring Belt plugin gems and the GeneratorRegistry contract

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.4.5'
+  VERSION = '0.4.6'
 end

data/references/cli.md

@@ -0,0 +1,76 @@
+# Belt CLI reference
+
+Run `belt --help` for the live list, or `belt <command> --help` for a specific
+command. `belt explain <topic>` gives conceptual docs. `BELT_ENV` sets the
+default environment so you can omit the `<env>` argument.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `belt new <app> [--frontend react]` | Create a new Belt app. `-v` lists every created file. |
+| `belt generate <thing> <name>` (alias `g`) | Generate `scaffold`, `model`, `controller`, `frontend`, `views`, `environment`, `dns`, `auth`, or a plugin generator. |
+| `belt destroy <thing> <name>` (alias `d`) | Remove what `generate` created. |
+| `belt routes [-g PATTERN] [-f json] [--namespace N]` | Show/inspect routes; generate Ruby route constants for the runtime router. |
+| `belt contracts [-g PATTERN] [-f json]` | Show API request/response contracts. |
+| `belt lambda-config [-e ENV] [-f json\|terraform]` | Show merged Lambda configuration. |
+| `belt console [env]` (alias `c`) | Interactive IRB with the app booted. `--run "expr"` for runner mode. |
+| `belt logs [lambda] [-f] [-s 5m] [-e env]` | Tail Lambda logs. |
+| `belt tasks [-g PATTERN] [-a]` (alias `-T`) | List rake tasks. Any rake task can be run directly: `belt lambda:build_layer`. |
+| `belt setup <state\|tables <env>\|frontend>` | Create S3 state bucket / generate DynamoDB tables / frontend infra. |
+| `belt doctor` | Check system deps + AWS config. |
+| `belt plugin new <name>` | Scaffold a Belt plugin gem. |
+| `belt explain <topic>` | Explain a concept (see topic list below). |
+| `belt deploy [env] [--auto] [--skip-backup] [--backup-only]` | Deploy to AWS (init → plan → apply, runs backups first if configured). |
+| `belt deploy frontend <env> [--frontend NAME]` | Build + deploy frontend(s). |
+| `belt dns <deploy\|add <env>\|show>` | Manage the root DNS zone. |
+| `belt frontend <env <env>\|list>` | Write `<frontend>/.env` from TF outputs, or list frontends. |
+| `belt server [--frontend NAME]` (alias `s`) | Start local dev server. |
+| `belt db:copy <from> <to> [--force]` | Copy DynamoDB data between environments. |
+| `belt db:seed [env] [--force]` | Run `config/seeds.rb` against an environment. |
+| `belt version` | Show Belt version. |
+
+### Terraform shorthand
+
+`belt <action> [env]` maps to Terraform: `init`, `plan`, `apply`, `destroy`,
+`output`. Example: `belt apply wups`, `belt output prod`.
+
+> ⚠ `belt destroy` is ambiguous: `belt destroy <env>` runs terraform destroy,
+> while `belt destroy scaffold post` removes generated code. Belt disambiguates
+> by argument shape.
+
+## `belt explain` topics
+
+`routing`, `controllers`, `models`, `deployment`, `generators`,
+`lambda_handler`, `observability`, `console`, `backups`, `data_seeding`,
+`plugins`, `structure`, `frontend`, `authentication`.
+
+## Standalone vs project commands
+
+These run anywhere (no Belt project needed): `new`, `version`, `doctor`,
+`explain`. All others chdir to the detected project root first.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `BELT_ENV` | Default environment for env-scoped commands |
+| `ENVIRONMENT` | Verbose error responses (`dev*`, `local`, `test`) |
+| `BELT_METRICS_NAMESPACE` | CloudWatch metrics namespace (default `Belt`) |
+| `ACTION` | Service name for logging (falls back to function name) |
+| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
+| `CORS_ALLOWED_ORIGINS` | Comma-separated origins (overrides domain vars) |
+| `CUSTOMER_APP_DOMAIN` / `OPS_APP_DOMAIN` | CORS domains |
+
+## Common flows
+
+```bash
+belt new blog --frontend react
+belt generate scaffold post title:string content:text
+belt routes
+belt deploy dev
+belt deploy prod --auto
+belt console prod --run "Post.count"
+belt logs api -f -e prod
+belt db:copy prod dev
+```

data/references/controllers.md

@@ -0,0 +1,73 @@
+# BeltController
+
+`BeltController::Base` gives Rails-like callbacks, strong params, response
+helpers, and error handling. Run `belt explain controllers` for canonical docs.
+
+## Implicit responses
+
+Instance variables assigned in an action become the JSON body by default:
+
+```ruby
+def index
+  @posts = Post.all      # → { "posts": [ ... ] }
+end
+```
+
+Explicit helpers always override implicit assigns.
+
+## Callbacks
+
+```ruby
+before_action :authenticate_user!
+before_action :require_admin!, except: [:health]
+skip_before_action :authenticate_user!, only: [:health]
+```
+
+## Strong parameters
+
+```ruby
+params.require(:user).permit(:name, :email, address: [:street, :city])
+```
+
+## Response helpers
+
+```ruby
+success_response({ id: "123" })                 # 200 JSON + CORS
+success_response({ id: "123" }, :created)       # 201 (symbol or int)
+error_response("Not found", :not_found)         # 404 JSON error
+error_response("Nope", :unprocessable_entity)   # 422
+html_response("<h1>Hi</h1>")                     # 200 HTML + CORS
+head :no_content                                 # 204 empty
+response_status :created                         # 201 + implicit assigns
+```
+
+## Error handling
+
+```ruby
+rescue_from MyError, with: :handle_it
+
+def handle_it(exception, _context = {})
+  error_response(exception.message, 422)
+end
+```
+
+## Default format (JSON vs HTML)
+
+```ruby
+# App-wide (lambda/config/environment.rb)
+Belt.configure { |c| c.default_format = :json }   # default
+
+# Per-controller
+class PagesController < ApplicationController
+  self.default_format = :html   # implicitly renders views/<controller>/<action>.html.erb
+end
+```
+
+- `:json` (default): assigns → `success_response({ ... })`.
+- `:html`: Belt implicitly renders the ERB template. Missing template raises
+  `Belt::TemplateNotFound` (no silent JSON fallback).
+
+## Controller discovery
+
+No registration needed. Belt looks in the app namespace module first, then
+`Belt.all_controller_paths`.

data/references/deploy-and-ops.md

@@ -0,0 +1,77 @@
+# Deploy, environments, backups, seeding & observability
+
+Run `belt explain deployment`, `belt explain backups`, `belt explain
+data_seeding`, and `belt explain observability` for canonical docs.
+
+## Deploy lifecycle
+
+`belt deploy [env]` runs pre-deploy backups (if configured) → terraform init →
+plan → apply. The **conveyor-belt** Terraform provider packages Ruby into
+Lambdas, creates API Gateway routes from the routing DSL, generates IAM for
+DynamoDB access, and sets up CloudWatch log groups.
+
+```bash
+belt deploy dev
+belt deploy prod --auto          # skip confirmation
+belt deploy prod --skip-backup   # CI re-runs
+belt deploy prod --backup-only   # recovery point, no deploy
+```
+
+Provider config (Terraform):
+
+```hcl
+terraform {
+  required_providers {
+    conveyor-belt = { source = "stowzilla/conveyor-belt", version = "~> 0.0.1" }
+  }
+}
+```
+
+## Environments
+
+Each env has `infrastructure/<env>/` (main.tf, backend.tf, variables.tf,
+terraform.tfvars, outputs.tf, belt.rb). Create with `belt generate environment
+<name> [parent]`. Terraform shorthand: `belt init|plan|apply|destroy|output <env>`.
+Set `BELT_ENV` to omit the env arg.
+
+## Backups (pre-deploy, config-driven)
+
+`infrastructure/<env>/belt.rb`:
+
+```ruby
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all                 # PITR check + on-demand snapshot per table
+    cognito  :users, :pool_config # export to backup bucket
+    s3       :legal_documents     # sync to backup bucket
+    retention snapshots: 90, cognito: 10, s3: 10
+  end
+end
+```
+
+Simple mode: `config.backups = true` (DynamoDB, all tables, 90-day retention).
+Omit the block entirely for lightweight dev envs. Belt auto-creates
+`<app>-backups-<env>` (versioned, public access blocked) on first run. Table
+names come from `terraform output`, so the first-ever deploy skips backups.
+
+## Data seeding
+
+```bash
+belt db:copy prod dev [--force]  # copy DynamoDB between envs (matches by stripped prefix)
+belt db:seed [env] [--force]     # run config/seeds.rb in the booted console context
+```
+
+`db:copy` skips non-empty destination tables by default. `db:seed` refuses to
+run against an env that already has data unless `--force`.
+
+## Observability
+
+`Belt::LambdaHandler` wires these global facades automatically:
+
+```ruby
+Belt::Observability::Logger.info("Something happened", user_id: "123")
+Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
+```
+
+Backed by `lambda_loadout` (structured logging + CloudWatch EMF metrics + error
+alerting via `ERROR_NOTIFICATION_TOPIC_ARN`).

data/references/models-and-auth.md

@@ -0,0 +1,71 @@
+# Models (ActiveItem) & Cognito authentication
+
+Run `belt explain models` and `belt explain authentication` for canonical docs.
+
+## ActiveItem (DynamoDB ORM)
+
+```ruby
+require "activeitem"
+
+class Post < ActiveItem::Base
+  self.primary_key = :id
+  attr_accessor :id, :user_id, :title, :body, :created_at
+
+  validates :title, presence: true
+  before_create { self.id ||= SecureRandom.uuid }
+end
+```
+
+Supports queries, validations, associations, and transactions. Query a GSI:
+
+```ruby
+Post.where(user_id: current_user.id, index: "UserIndex")
+Post.find(id)
+Post.create!(attrs)
+```
+
+Table schema is declared in `infrastructure/schema.tf.rb`:
+
+```ruby
+Belt.application.schema.define do
+  model :post do
+    partition_key :id, :string
+    global_secondary_index :UserIndex, partition_key: :user_id
+  end
+end
+```
+
+DynamoDB tables generated by Belt default to PITR enabled and (in prod)
+deletion protection enabled.
+
+## Authentication — Cognito owns auth, Belt owns the record
+
+```ruby
+class User < ApplicationRecord
+  cognito_authenticatable
+end
+```
+
+One line supplies: Cognito `sub` as primary key, identity attributes (`email`,
+`name`, `role`, `email_verified`, `last_seen_on`), an `EmailIndex` GSI,
+just-in-time provisioning from a token, and `#admin?` for platform staff.
+
+Controllers get helpers for free — no `include`, no config:
+
+| Helper | Meaning |
+|---|---|
+| `current_user` | User record or nil (memoized per request) |
+| `user_signed_in?` | Is there a Cognito identity on this request? |
+| `authenticate_user!` | `before_action` guard → 401 |
+| `cognito_admin?` | Does the token carry a staff Cognito group? |
+
+```ruby
+class ProfilesController < ApplicationController
+  before_action :authenticate_user!
+  def show = @profile = current_user
+end
+```
+
+`belt generate auth` creates the user pool **and** scaffolds the model + table.
+See `belt explain authentication` for the `after_cognito_sync` hook, platform
+staff handling, and both token shapes. Upgrading an existing app? See `UPGRADING.md`.

data/references/plugins.md

@@ -0,0 +1,64 @@
+# Authoring Belt plugins
+
+Belt stays lean; optional capabilities ship as **separate gems** that plug into
+the CLI and runtime. Run `belt explain plugins` for canonical docs. Reference
+implementations: `belt-messaging`, `belt-pay`.
+
+## Discovery contract (GeneratorRegistry)
+
+No central registry, no initializer. Belt discovers a generator when:
+
+1. The gem is in the app's `Gemfile` and bundled.
+2. It ships `lib/belt/generators/<name>_generator.rb`.
+3. The class is `Belt::Generators::<Name>Generator`.
+4. It implements `.run(args)` (required); optionally `.destroy(args)` and `.description`.
+
+After `bundle install`, `belt generate <name>` and `belt destroy <name>` just work.
+
+## Scaffold a plugin
+
+```bash
+belt plugin new notifications                       # → ./belt-notifications/
+belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"
+```
+
+Point an app at a local plugin while developing:
+
+```ruby
+# app Gemfile
+gem "belt-notifications", path: "../belt-notifications"
+```
+
+`belt deploy` vendors `path:` gems into `vendor/cache` so conveyor-belt can
+package them.
+
+## Canonical layout
+
+```
+belt-messaging/
+├── belt-messaging.gemspec
+├── lib/
+│   ├── belt-messaging.rb              # require entrypoint
+│   └── belt/
+│       ├── messaging.rb               # Belt::Messaging API
+│       ├── messaging/{configuration,version}.rb
+│       ├── messaging/controllers/     # default controllers (optional)
+│       ├── messaging/templates/       # ERB for the generator
+│       └── generators/messaging_generator.rb   # ← auto-discovered
+└── spec/
+```
+
+**Runtime code stays in the gem.** Generators copy only what the host app must
+own — Terraform modules, Lambda entrypoints, optional controller overrides.
+Prefer gem defaults + `belt g <plugin> --controllers` over dumping everything
+into the app.
+
+## Generator checklist
+
+1. Terraform module → `infrastructure/modules/<name>/`
+2. Lambda config → `config/lambda/<name>.yml`
+3. Lambda entrypoint → `lambda/<name>.rb` via `Belt::LambdaHandler`
+4. Routes/schema injection when needed
+5. Optional `--controllers` for app-local overrides
+6. Matching `destroy` path
+7. `.description` + `--help`

data/references/routing.md

@@ -0,0 +1,78 @@
+# Belt routing DSL
+
+Routes live in `infrastructure/routes.tf.rb` and are read both by the
+**conveyor-belt** Terraform provider (for infra) and by `belt routes` (which
+generates the runtime route constants at `lambda/lib/routes/<namespace>_routes.rb`).
+
+Run `belt explain routing` for the canonical docs.
+
+## Four keywords
+
+| Keyword | Purpose | Changes which Lambda? |
+|---|---|---|
+| `gateway` | API Gateway + default Lambda | **Yes** — sets default for routes inside |
+| `function` | Route to a different Lambda | **Yes** — overrides gateway default |
+| `namespace` | Path prefix + controller module | No — code organization only |
+| `scope` | Path/module/auth grouping | No — grouping + shared options |
+
+**Critical:** `namespace` and `scope` are purely organizational. Only `gateway`
+and `function` determine the serving Lambda.
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api, auth: :cognito do
+    resources :posts                    # lambda: api, /posts, posts controller
+
+    namespace :admin do
+      resources :users                  # /admin/users, admin/users controller
+    end
+
+    function :worker do
+      resources :jobs                   # lambda: worker, /jobs, jobs controller
+    end
+
+    scope path: 'v2', module: 'legacy' do
+      resources :widgets                # /v2/widgets, legacy/widgets controller
+    end
+  end
+end
+```
+
+## Nested resources
+
+```ruby
+resources :projects do
+  resource  :billing, only: [:show], tables: [:memberships]  # singular, no :id
+
+  resources :webhooks do
+    member     { post :test }      # POST /projects/:project_id/webhooks/:webhook_id/test
+  end
+
+  resources :surfaces do
+    collection { get :teams }      # GET /projects/:project_id/surfaces/teams
+    member     { put :assign }     # PUT /projects/:project_id/surfaces/:surface_id/assign
+  end
+
+  scope path: 'billing', controller: :billing, tables: [:memberships] do
+    get  '/', action: :show
+    post :checkout
+  end
+end
+```
+
+- **Action inference:** `post :checkout` uses `checkout` as both path segment and action.
+- **Controller inheritance:** `member`/`collection` inherit the parent resource's controller.
+- **`tables:`** declares DynamoDB access for IAM generation.
+
+## Request/response model inference (for `belt routes` / contracts)
+
+Resolution order (highest first):
+
+1. **Explicit per-route:** `put "/items/:id", request_model: :update_item`
+2. **Hash per-action:** `resources :items, request_model: { create: :create_item }`
+3. **Convention cascade** (POST/PUT/PATCH only):
+   - `:<verb>_<gateway>_<singular>` → e.g. `:create_customer_item`
+   - `:<verb>_<singular>` → e.g. `:create_item`
+
+**Response model:** singular of the resource name → `resources :items` looks for
+`model :item` in `contracts.rb`. Applies to all verbs. No match = no model documented.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Stowzilla
@@ -97,6 +97,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- SKILL.md
 - exe/belt
 - lib/belt.rb
 - lib/belt/action_router.rb
@@ -262,6 +263,12 @@ files:
 - lib/templates/views/Index.jsx.erb
 - lib/templates/views/New.jsx.erb
 - lib/templates/views/Show.jsx.erb
+- references/cli.md
+- references/controllers.md
+- references/deploy-and-ops.md
+- references/models-and-auth.md
+- references/plugins.md
+- references/routing.md
 homepage: https://github.com/stowzilla/belt
 licenses:
 - MIT