tormenta20 0.2.18 → 0.2.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a852265478492bb032c632483694f735ed348dfa4e934de22eeb2205e53f2b52
-  data.tar.gz: f55b2253f5db758a95867045ebad5a3d49adabd4a972bbe9029917441b7b55af
+  metadata.gz: 5e92c1ce7a7fac6f4e16264f342f1ee1b76a4c91983b2d438b4349731ad96b1d
+  data.tar.gz: 9f42ecfc0f2281cfbb007b1b4739de71de7ef59f6ba853864267013f7dd17e76
 SHA512:
-  metadata.gz: 70593b146c7f71e503902871cdd9553fbb319bddc7d9c25987ba88fc8b8e747b6d2aa7d5142727dc208eba23d34f77727977ca346aa42d2a0f2c01d86d3a4d83
-  data.tar.gz: e2691cb49bc21db416a90bc97fa4866023ffa8e606da35de673a417167f00616542d6d579476e5418ad7f556a91223e66543261277835433bec5ea1daa40ac44
+  metadata.gz: 6fc6fb26b97f9d56cef8e6ba404932d9c369c146becbc6606ab887feaae0f3a2fea546f75e228fd288a6c1c00b9785b768f52bd7f0346615917f67cfa0b26398
+  data.tar.gz: 66b602e7b6b081dd01c48ceba97e4d2e46d784522cb1a021c11313193121021e0fb4ba764c17e86d42516cf738799c68cd2a85b1d30a1148e6156df5cd91eaef

data/README.md

@@ -1,17 +1,20 @@
 # Tormenta20
 
-[![Gem Version](https://img.shields.io/gem/v/tormenta20)](https://rubygems.org/gems/tormenta20)
+[![Ruby](https://img.shields.io/gem/v/tormenta20)](https://rubygems.org/gems/tormenta20)
+[![npm](https://img.shields.io/npm/v/tormenta20)](https://www.npmjs.com/package/tormenta20)
 [![CI](https://github.com/LuanGB/tormenta20/actions/workflows/main.yml/badge.svg)](https://github.com/LuanGB/tormenta20/actions/workflows/main.yml)
 [![Coverage](https://codecov.io/gh/YggdrasilGeekNetwork/tormenta20/graph/badge.svg?token=XB8BTBS6PJ)](https://codecov.io/gh/YggdrasilGeekNetwork/tormenta20)
+[![Ruby Docs](https://img.shields.io/badge/docs-rubydoc.info-red)](https://rubydoc.info/gems/tormenta20)
+[![TS Docs](https://img.shields.io/badge/docs-typedoc-blue)](https://luangb.github.io/tormenta20/typedoc/)
 [![License](https://img.shields.io/github/license/LuanGB/tormenta20)](LICENSE.txt)
 
-Uma biblioteca Ruby com dados do RPG de mesa brasileiro Tormenta20.
+Uma biblioteca Ruby, TypeScript e Python com dados do RPG de mesa brasileiro Tormenta20.
 
-A gem inclui um banco de dados SQLite pré-populado com informações sobre magias, classes, origens, divindades, poderes, equipamentos, raças e condições do sistema Tormenta20. Todos os registros expõem referências de livro e página via o concern `BookReferenceable`.
+Inclui um banco de dados SQLite pré-populado com magias, classes, origens, divindades, poderes, equipamentos, raças e condições do sistema T20. Todos os registros expõem referências de livro e página via `bookReference()` / `book_reference`.
 
 ## Dependências do Sistema
 
-A gem usa SQLite3 para armazenar os dados. O driver Ruby (`sqlite3` gem) vem com binaries pré-compilados, mas em ambientes Linux (incluindo Docker) a biblioteca de runtime precisa estar presente:
+A biblioteca usa SQLite3. Em ambientes Linux (incluindo Docker):
 
 ```bash
 # Debian/Ubuntu
@@ -27,235 +30,76 @@ No Dockerfile da sua aplicação:
 RUN apt-get install --no-install-recommends -y libsqlite3-0
 ```
 
-## Installation
+## Instalação
 
-Adicione ao Gemfile da sua aplicação:
+**Ruby (Bundler):**
 
 ```ruby
+# Gemfile
 gem 'tormenta20'
 ```
 
-E execute:
-
 ```bash
 bundle install
 ```
 
-Ou instale diretamente:
+**Node.js / TypeScript:**
 
 ```bash
-gem install tormenta20
+npm install tormenta20
 ```
 
-## Usage
+## Uso Rápido
 
-A gem já vem com o banco de dados populado. Basta fazer require e usar:
+**Ruby:**
 
 ```ruby
 require 'tormenta20'
 
-# Magias
-Tormenta20.magias.count                    # => 198
-Tormenta20.magias.arcanas                  # Magias arcanas
-Tormenta20.magias.divinas                  # Magias divinas
-Tormenta20.magias.by_circle("3")           # Magias do 3º círculo
-Tormenta20.magias.by_school('evoc')        # Magias de evocação
-Tormenta20.magias.arcanas.by_circle("1")   # Combinar filtros
-
-# Classes
-Tormenta20.classes.all
-Tormenta20.classes.conjuradores            # Classes com magia
-
-# Raças
-Tormenta20.racas.all
-Tormenta20.racas.find('anao')
-
-# Origens
-Tormenta20.origens.all
-Tormenta20.origens.find('soldado')
-Tormenta20.origens.with_unique_power       # Origens com poder único
-
-# Divindades
-Tormenta20.divindades.all
-Tormenta20.divindades.energia_positiva     # Deuses de energia positiva
-Tormenta20.divindades.energia_negativa     # Deuses de energia negativa
-
-# Poderes
-Tormenta20.poderes.all
-Tormenta20.poderes.habilidades_unicas      # Habilidades únicas de origem
-Tormenta20.poderes.poderes_concedidos      # Poderes concedidos por divindades
-Tormenta20.poderes.poderes_tormenta        # Poderes da Tormenta
-
-# Condições
-Tormenta20.condicoes.all
-Tormenta20.condicoes.by_type('medo')
-Tormenta20.condicoes.medo
-Tormenta20.condicoes.mental
-
-# Equipamentos
-Tormenta20.armas.all
-Tormenta20.armas.simples                   # Armas simples
-Tormenta20.armas.marciais                  # Armas marciais
-Tormenta20.armaduras.all
-Tormenta20.armaduras.leves                 # Armaduras leves
-Tormenta20.escudos.all
-
-# Itens Superiores
-Tormenta20.materiais_especiais.all
-Tormenta20.melhorias.all
-
-# Regras
-Tormenta20.regras.all
-
-# Índice Remissivo
-Tormenta20.livros.all
-Tormenta20.indice_remissivo.do_livro('t20_eja')
-Tormenta20.indice_remissivo.para_tabela('classes')
-Tormenta20.indice_remissivo.buscar_termo('Fúria')
-```
-
-### Query Interface
-
-A gem oferece uma interface de consulta simplificada. Todos os métodos retornam modelos ActiveRecord, permitindo encadeamento de scopes e queries:
-
-```ruby
-# Accessors disponíveis
-Tormenta20.origens              # => Tormenta20::Models::Origem
-Tormenta20.poderes              # => Tormenta20::Models::Poder
-Tormenta20.divindades           # => Tormenta20::Models::Divindade
-Tormenta20.classes              # => Tormenta20::Models::Classe
-Tormenta20.magias               # => Tormenta20::Models::Magia
-Tormenta20.armas                # => Tormenta20::Models::Arma
-Tormenta20.armaduras            # => Tormenta20::Models::Armadura
-Tormenta20.escudos              # => Tormenta20::Models::Escudo
-Tormenta20.itens                # => Tormenta20::Models::Item
-Tormenta20.materiais_especiais  # => Tormenta20::Models::MaterialEspecial
-Tormenta20.melhorias            # => Tormenta20::Models::Melhoria
-Tormenta20.regras               # => Tormenta20::Models::Regra
-Tormenta20.racas                # => Tormenta20::Models::Raca
-Tormenta20.condicoes            # => Tormenta20::Models::Condicao
-Tormenta20.livros               # => Tormenta20::Models::Livro
-Tormenta20.indice_remissivo     # => Tormenta20::Models::IndiceRemissivo
-
-# Exemplos de queries ActiveRecord
-Tormenta20.magias.where(type: 'arcana')
-Tormenta20.magias.where(school: 'evoc').order(:name)
-Tormenta20.poderes.where("name LIKE ?", "%Fúria%")
-```
-
-### Models Disponíveis
-
-| Model | Descrição | Quantidade | Documentação |
-|-------|-----------|------------|--------------|
-| `Magia` | Magias arcanas, divinas e universais | 198 | [docs/magias.md](docs/magias.md) |
-| `Classe` | Classes de personagem | 14 | [docs/classes.md](docs/classes.md) |
-| `Origem` | Origens de personagem | 35 | [docs/origens.md](docs/origens.md) |
-| `Divindade` | Deuses do Panteão | 20 | [docs/divindades.md](docs/divindades.md) |
-| `Poder` | Poderes (habilidades únicas, concedidos, tormenta, classe, raça) | 518 | [docs/poderes.md](docs/poderes.md) |
-| `Raca` | Raças jogáveis | 18 | [docs/racas.md](docs/racas.md) |
-| `Condicao` | Condições de status | 35 | [docs/condicoes.md](docs/condicoes.md) |
-| `Arma` | Armas | - | [docs/armas.md](docs/armas.md) |
-| `Armadura` | Armaduras | - | [docs/armaduras.md](docs/armaduras.md) |
-| `Escudo` | Escudos | 2 | [docs/escudos.md](docs/escudos.md) |
-| `Item` | Itens gerais | - | [docs/itens.md](docs/itens.md) |
-| `MaterialEspecial` | Materiais especiais | 6 | [docs/materiais_especiais.md](docs/materiais_especiais.md) |
-| `Melhoria` | Melhorias mágicas | - | [docs/melhorias.md](docs/melhorias.md) |
-| `Regra` | Regras e dados de referência | 14 | [docs/regras.md](docs/regras.md) |
-| `Livro` | Livros indexados | 1 | [docs/livros.md](docs/livros.md) |
-| `IndiceRemissivo` | Entradas do índice remissivo | 1098 | [docs/indice_remissivo.md](docs/indice_remissivo.md) |
-
-### Referência de Livro e Página
-
-Todos os modelos incluem o concern `BookReferenceable`. Se o registro estiver indexado no índice remissivo, os seguintes métodos ficam disponíveis:
-
-```ruby
-guerreiro = Tormenta20.classes.find('guerreiro')
-
-guerreiro.book_reference  # => "T20 - EJA, p. 64"
-guerreiro.page            # => 64
-guerreiro.book            # => "T20 - EJA"
-guerreiro.full_book       # => "Tormenta 20 - Edição Jogo do Ano"
-
-# Retorna nil se o registro não estiver no índice
-item_sem_indice = Tormenta20.itens.first
-item_sem_indice.book_reference  # => nil
+Tormenta20.magias.arcanas.by_circle("3")
+Tormenta20.classes.conjuradores.all
+Tormenta20.poderes.poderes_concedidos.all
+Tormenta20.racas.find('anao').book_reference  # => "T20 - EJA, p. 20"
 ```
 
-O resultado é memoizado por instância — o banco é consultado apenas uma vez por objeto.
-
-Os dados do índice remissivo são carregados de `src/json/indice_remissivo/<livro_id>.json`. Atualmente inclui o índice de **Tormenta 20 - Edição Jogo do Ano** (`t20_eja`) com mais de 1000 entradas.
-
-### Índice Remissivo
-
-O model `IndiceRemissivo` permite buscar entradas por livro, tabela ou termo:
-
-```ruby
-# Todas as entradas de um livro
-Tormenta20.indice_remissivo.do_livro('t20_eja')
-
-# Entradas vinculadas a uma tabela específica
-Tormenta20.indice_remissivo.para_tabela('classes')
-
-# Entradas vinculadas a registros concretos
-Tormenta20.indice_remissivo.associados
-
-# Entradas sem vínculo a registro
-Tormenta20.indice_remissivo.nao_associados
+**TypeScript / JavaScript:**
 
-# Busca por termo
-Tormenta20.indice_remissivo.buscar_termo('Fúria')
+```ts
+import { Magia, Classe, Poder, Raca } from 'tormenta20'
 
-# Consultar o livro de uma entrada
-entrada = Tormenta20.indice_remissivo.first
-entrada.livro.nome        # => "Tormenta 20 - Edição Jogo do Ano"
-entrada.livro.nome_curto  # => "T20 - EJA"
+Magia.arcanas().all()
+Classe.conjuradores().all()
+Poder.poderesConcedidos().all()
+Raca.find('anao')?.bookReference()  // => { formatted: "T20 - EJA, p. 20", ... }
 ```
 
-### Exemplos
+## Modelos
 
-```ruby
-# Buscar uma magia específica
-bola_de_fogo = Tormenta20.magias.find('bola_de_fogo')
-puts bola_de_fogo.name            # => "Bola de Fogo"
-puts bola_de_fogo.circle          # => "3"
-puts bola_de_fogo.school          # => "evoc"
-puts bola_de_fogo.book_reference  # => "T20 - EJA, p. ..."
-
-# Listar poderes de uma divindade
-khalmyr = Tormenta20.divindades.find('khalmyr')
-puts khalmyr.name             # => "Khalmyr"
-puts khalmyr.granted_powers   # => ["coragem_total", "espada_justiceira", ...]
-puts khalmyr.book_reference   # => "T20 - EJA, p. 99"
-
-# Classe com informações de magia e referência de livro
-mago = Tormenta20.classes.find('arcanista')
-puts mago.initial_hp          # PV inicial
-puts mago.mp_per_level        # PM por nível
-puts mago.conjurador?         # => true
-puts mago.book_reference      # => "T20 - EJA, p. 36"
-
-# Raça com bônus de atributo
-anao = Tormenta20.racas.find('anao')
-puts anao.attribute_bonus_for('constituicao')  # => 2
-puts anao.visao_no_escuro?                     # => true
-puts anao.book_reference                       # => "T20 - EJA, p. 20"
-
-# Filtrar magias arcanas do 1º círculo da escola de evocação
-Tormenta20.magias.arcanas.by_circle("1").by_school("evoc").each do |magia|
-  puts "#{magia.name} - #{magia.book_reference}"
-end
-
-# Condições de medo
-Tormenta20.condicoes.medo.each do |c|
-  puts "#{c.name}: #{c.escalates_to ? "escala para #{c.escalates_to}" : 'não escala'}"
-end
-```
+| Model | Descrição | Qtd | Ruby | TypeScript |
+|-------|-----------|-----|------|------------|
+| `Magia` | Magias arcanas, divinas e universais | 198 | [docs/ruby/magias.md](docs/ruby/magias.md) | [docs/ts/magias.md](docs/ts/magias.md) |
+| `Classe` | Classes de personagem | 14 | [docs/ruby/classes.md](docs/ruby/classes.md) | [docs/ts/classes.md](docs/ts/classes.md) |
+| `Origem` | Origens de personagem | 35 | [docs/ruby/origens.md](docs/ruby/origens.md) | [docs/ts/origens.md](docs/ts/origens.md) |
+| `Divindade` | Deuses do Panteão | 20 | [docs/ruby/divindades.md](docs/ruby/divindades.md) | [docs/ts/divindades.md](docs/ts/divindades.md) |
+| `Poder` | Poderes (origem, concedido, tormenta, classe, raça) | 518 | [docs/ruby/poderes.md](docs/ruby/poderes.md) | [docs/ts/poderes.md](docs/ts/poderes.md) |
+| `Raca` | Raças jogáveis | 18 | [docs/ruby/racas.md](docs/ruby/racas.md) | [docs/ts/racas.md](docs/ts/racas.md) |
+| `Condicao` | Condições de status | 35 | [docs/ruby/condicoes.md](docs/ruby/condicoes.md) | [docs/ts/condicoes.md](docs/ts/condicoes.md) |
+| `Arma` | Armas | — | [docs/ruby/armas.md](docs/ruby/armas.md) | [docs/ts/armas.md](docs/ts/armas.md) |
+| `Armadura` | Armaduras | — | [docs/ruby/armaduras.md](docs/ruby/armaduras.md) | [docs/ts/armaduras.md](docs/ts/armaduras.md) |
+| `Escudo` | Escudos | 2 | [docs/ruby/escudos.md](docs/ruby/escudos.md) | [docs/ts/escudos.md](docs/ts/escudos.md) |
+| `Item` | Itens gerais | — | [docs/ruby/itens.md](docs/ruby/itens.md) | [docs/ts/itens.md](docs/ts/itens.md) |
+| `MaterialEspecial` | Materiais especiais | 6 | [docs/ruby/materiais_especiais.md](docs/ruby/materiais_especiais.md) | [docs/ts/materiais_especiais.md](docs/ts/materiais_especiais.md) |
+| `Melhoria` | Melhorias mágicas | — | [docs/ruby/melhorias.md](docs/ruby/melhorias.md) | [docs/ts/melhorias.md](docs/ts/melhorias.md) |
+| `Regra` | Regras e dados de referência | 14 | [docs/ruby/regras.md](docs/ruby/regras.md) | [docs/ts/regras.md](docs/ts/regras.md) |
+| `Livro` | Livros indexados | 1 | [docs/ruby/livros.md](docs/ruby/livros.md) | [docs/ts/livros.md](docs/ts/livros.md) |
+| `IndiceRemissivo` | Entradas do índice remissivo | 1098 | [docs/ruby/indice_remissivo.md](docs/ruby/indice_remissivo.md) | [docs/ts/indice_remissivo.md](docs/ts/indice_remissivo.md) |
 
 ## Development
 
 ### Pré-requisitos
 
 - Ruby >= 3.0.0
+- Node.js >= 18
 - Bundler
 
 ### Setup
@@ -264,77 +108,50 @@ end
 git clone https://github.com/LuanGB/tormenta20.git
 cd tormenta20
 bundle install
+npm install
 ```
 
 ### Construir o Banco de Dados
 
-O arquivo `db/tormenta20.sqlite3` é **gerado** a partir dos JSONs em `src/json/` e não está versionado no repositório. É necessário gerá-lo antes de rodar os specs ou a gem localmente:
+O arquivo `db/tormenta20.sqlite3` é **gerado** a partir dos JSONs em `src/json/`:
 
 ```bash
-# Construir apenas o banco
+# Ruby
 rake build_db
 
-# Build completo da gem (inclui build_db automaticamente)
+# Build completo (inclui build_db)
 rake build
-```
 
-Os specs (`rake spec` / `rake`) também executam `build_db` automaticamente antes de rodar.
+# TypeScript (compila dist/ + docs)
+npm run build
+npm run docs
+```
 
 ### Estrutura do Projeto
 
 ```
 tormenta20/
 ├── src/
-│   ├── json/                    # Dados em formato JSON
-│   │   ├── magias/
-│   │   ├── classes/
-│   │   ├── origens/
-│   │   ├── deuses/
-│   │   ├── poderes/
-│   │   │   ├── habilidades_unicas_de_origem/
-│   │   │   ├── poderes_concedidos/
-│   │   │   └── poderes_da_tormenta/
-│   │   ├── equipamentos/
-│   │   ├── itens_superiores/
-│   │   ├── regras/
-│   │   ├── condicoes/
-│   │   ├── racas/
-│   │   ├── livros/
-│   │   └── indice_remissivo/    # Índice por livro (ex: t20_eja.json)
-│   └── ruby/                    # Código Ruby
-│       └── tormenta20/
-│           ├── models/          # ActiveRecord models
-│           ├── concerns/        # Mixins (BookReferenceable)
-│           ├── database.rb      # Conexão com banco
-│           └── seeder.rb        # Import de dados
+│   ├── json/          # Dados fonte em JSON
+│   ├── ruby/          # Código Ruby (ActiveRecord models)
+│   └── ts/            # Código TypeScript
+├── docs/
+│   ├── ruby/          # Referência da API Ruby
+│   └── ts/            # Referência da API TypeScript
 ├── db/
-│   ├── schema.sql              # Schema SQLite
-│   ├── seeds.rb                # Script de seed (desenvolvimento)
-│   └── tormenta20.sqlite3      # Banco pré-construído (gerado)
-└── bin/
-    └── build_db                # Script de build do banco
+│   ├── schema.sql
+│   └── tormenta20.sqlite3   # Gerado por rake build_db
+└── dist/              # Build TypeScript compilado
 ```
 
 ### Testes
 
 ```bash
+# Ruby
 bin/test
-```
-
-Ou individualmente:
-
-```bash
-# Apenas specs
-bundle exec rspec
 
-# Suite completa (build_db + specs + rubocop + jsonlint)
-bin/ci
-```
-
-### Linting
-
-```bash
-rake rubocop
+# TypeScript
+npm test
 ```
 
 ## Contributing

data/db/schema.sql

@@ -519,6 +519,52 @@ BEGIN
   UPDATE acessorios_magicos SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
 END;
 
+-- -----------------------------------------------------------------------------
+-- PERÍCIAS (Skills)
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS pericias (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  atributo TEXT NOT NULL CHECK(atributo IN ('FOR', 'DES', 'CON', 'INT', 'SAB', 'CAR')),
+  trained_only INTEGER NOT NULL DEFAULT 0,
+  armor_penalty INTEGER NOT NULL DEFAULT 0,
+  resistance_skill INTEGER NOT NULL DEFAULT 0,
+  description TEXT,
+  uses JSON DEFAULT '[]',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_pericias_atributo ON pericias(atributo);
+CREATE INDEX IF NOT EXISTS idx_pericias_trained_only ON pericias(trained_only);
+
+CREATE TRIGGER IF NOT EXISTS update_pericias_timestamp
+AFTER UPDATE ON pericias
+BEGIN
+  UPDATE pericias SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+END;
+
+-- -----------------------------------------------------------------------------
+-- TABELAS (Reference Tables)
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS tabelas (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  description TEXT,
+  headers JSON NOT NULL DEFAULT '[]',
+  rows JSON NOT NULL DEFAULT '[]',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_tabelas_name ON tabelas(name);
+
+CREATE TRIGGER IF NOT EXISTS update_tabelas_timestamp
+AFTER UPDATE ON tabelas
+BEGIN
+  UPDATE tabelas SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+END;
+
 -- =============================================================================
 -- VIEWS ÚTEIS
 -- =============================================================================

data/src/ruby/tormenta20/models/acessorio_magico.rb

@@ -5,13 +5,42 @@ require "active_record"
 module Tormenta20
   module Models
     # Magic accessory items (rings, amulets, cloaks, etc.) with passive and active effects.
+    #
+    # @example
+    #   AcessorioMagico.menores.all
+    #   AcessorioMagico.find_by(id: "anel_de_protecao").efeito
+    #
+    # @!attribute [rw] id
+    #   @return [String] Unique identifier
+    # @!attribute [rw] name
+    #   @return [String] Item name
+    # @!attribute [rw] categoria
+    #   @return [String] Power tier: +"menor"+, +"medio"+, or +"maior"+
+    # @!attribute [rw] preco
+    #   @return [Integer, nil] Price in tibares
+    # @!attribute [rw] roll_min
+    #   @return [Integer, nil] Minimum roll on random loot table
+    # @!attribute [rw] roll_max
+    #   @return [Integer, nil] Maximum roll on random loot table
+    # @!attribute [rw] description
+    #   @return [String, nil] Item description
     class AcessorioMagico < Base
       self.table_name = "acessorios_magicos"
 
+      # @!group Scopes
+      # @!method menores
+      #   @return [ActiveRecord::Relation] Minor-tier accessories
       scope :menores, -> { where(categoria: "menor") }
+      # @!method medios
+      #   @return [ActiveRecord::Relation] Medium-tier accessories
       scope :medios,  -> { where(categoria: "medio") }
+      # @!method maiores
+      #   @return [ActiveRecord::Relation] Major-tier accessories
       scope :maiores, -> { where(categoria: "maior") }
+      # @!endgroup
 
+      # Returns the parsed effect hash, handling both raw JSON strings and pre-parsed hashes.
+      # @return [Hash] Effect data, or +{}+ on parse failure
       def efeito
         raw = read_attribute(:efeito)
         return {} if raw.blank?

data/src/ruby/tormenta20/models/base.rb

@@ -11,11 +11,56 @@ module Tormenta20
     # inherits from ActiveRecord::Base. This provides common functionality
     # and ensures all models share the same database connection.
     #
-    # @abstract Subclass and set table_name to create a new model
+    # Every concrete model adds {Concerns::BookReferenceable}, which provides
+    # the {Concerns::BookReferenceable#book_reference} method for sourcebook
+    # page lookup.
+    #
+    # @abstract Subclass and set +table_name+ to create a new model
+    #
+    # @!attribute [rw] id
+    #   @return [String] Unique string identifier (e.g. +"guerreiro"+, +"espada_longa"+)
+    # @!attribute [r] created_at
+    #   @return [Time] Record creation timestamp
+    # @!attribute [r] updated_at
+    #   @return [Time] Record last-update timestamp
     class Base < ActiveRecord::Base
       self.abstract_class = true
 
       include Concerns::BookReferenceable
+
+      # Raised when any write operation is attempted on the Tormenta20 database.
+      # The database is read-only by design — it ships as pre-built data.
+      class ReadOnlyError < StandardError
+        def initialize(msg = "Tormenta20 database is read-only")
+          super
+        end
+      end
+
+      # @!group Read-only enforcement
+
+      def readonly?
+        true
+      end
+
+      def destroy
+        raise ReadOnlyError
+      end
+      alias destroy! destroy
+
+      WRITE_CLASS_METHODS = %i[
+        create create!
+        insert insert! insert_all insert_all!
+        upsert upsert_all
+        update_all
+        delete delete_all
+        destroy_all
+      ].freeze
+
+      WRITE_CLASS_METHODS.each do |m|
+        define_singleton_method(m) { |*| raise ReadOnlyError }
+      end
+
+      # @!endgroup
     end
   end
 end

data/src/ruby/tormenta20/models/livro.rb

@@ -4,7 +4,20 @@ require "active_record"
 
 module Tormenta20
   module Models
-    # ActiveRecord model for livros (books).
+    # ActiveRecord model for livros (sourcebooks).
+    #
+    # Livros are the target of {IndiceRemissivo} entries, which link
+    # game terms to page numbers in a specific book.
+    #
+    # @example
+    #   Livro.find_by(id: "t20_eja").nome_curto  # => "T20 - EJA"
+    #
+    # @!attribute [rw] id
+    #   @return [String] Unique identifier (e.g. +"t20_eja"+)
+    # @!attribute [rw] nome
+    #   @return [String] Full book title
+    # @!attribute [rw] nome_curto
+    #   @return [String] Short reference abbreviation (e.g. +"T20 - EJA"+)
     class Livro < Base
       self.table_name = "livros"
 

data/src/ruby/tormenta20/models/pericia.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "json"
+
+module Tormenta20
+  module Models
+    # Model representing a Perícia (Skill) in Tormenta20.
+    #
+    # @example Find all skills governed by Charisma
+    #   Pericia.by_atributo("CAR").all
+    #
+    # @example Find saving-throw skills
+    #   Pericia.resistance_skills.all
+    #
+    # @!attribute [rw] id
+    #   @return [String] Unique identifier (e.g. +"diplomacia"+)
+    # @!attribute [rw] name
+    #   @return [String] Skill name
+    # @!attribute [rw] atributo
+    #   @return [String] Governing attribute abbreviation — see {ATRIBUTOS}
+    # @!attribute [rw] trained_only
+    #   @return [Integer] 1 if training is required to use the skill, 0 otherwise
+    # @!attribute [rw] armor_penalty
+    #   @return [Integer] 1 if armor check penalty applies, 0 otherwise
+    # @!attribute [rw] resistance_skill
+    #   @return [Integer] 1 if this skill is used as a saving throw, 0 otherwise
+    # @!attribute [rw] description
+    #   @return [String, nil] Skill description
+    # @!attribute [rw] uses
+    #   @return [Array] Use-case descriptors
+    class Pericia < Base
+      self.table_name = "pericias"
+
+      # Valid governing attribute abbreviations.
+      # @return [Array<String>]
+      ATRIBUTOS = %w[FOR DES CON INT SAB CAR].freeze
+
+      validates :id, presence: true, uniqueness: true
+      validates :name, presence: true
+      validates :atributo, inclusion: { in: ATRIBUTOS }
+
+      # @!group Scopes
+      # @!method by_atributo(attr)
+      #   @param attr [String] Attribute abbreviation (e.g. +"CAR"+)
+      #   @return [ActiveRecord::Relation]
+      scope :by_atributo,     ->(attr) { where(atributo: attr) }
+      # @!method trained_only
+      #   @return [ActiveRecord::Relation] Skills that require training to use
+      scope :trained_only,    -> { where(trained_only: true) }
+      # @!method with_armor_penalty
+      #   @return [ActiveRecord::Relation] Skills affected by armor check penalty
+      scope :with_armor_penalty, -> { where(armor_penalty: true) }
+      # @!method resistance_skills
+      #   @return [ActiveRecord::Relation] Skills used as saving throws
+      scope :resistance_skills, -> { where(resistance_skill: true) }
+      # @!endgroup
+
+      def to_h
+        {
+          id: id,
+          name: name,
+          atributo: atributo,
+          trained_only: trained_only?,
+          armor_penalty: armor_penalty?,
+          resistance_skill: resistance_skill?,
+          description: description,
+          uses: uses || []
+        }.compact
+      end
+
+      private
+
+      # @return [Boolean]
+      def trained_only?     = [true, 1].include?(trained_only)
+      # @return [Boolean]
+      def armor_penalty?    = [true, 1].include?(armor_penalty)
+      # @return [Boolean]
+      def resistance_skill? = [true, 1].include?(resistance_skill)
+    end
+  end
+end