Fix semantic html

.ai/app-directories.md

@@ -0,0 +1,47 @@
+# App directories
+
+As decidim is a gem for Ruby on Rails you may find the usual rails directories: controllers, models, etc. but we also have other kind of directories.
+
+## Standard Rails
+
+| Directory    | Description                      | Technology             |
+|--------------|----------------------------------|------------------------|
+| controllers/ | HTTP request handlers            | Rails ActionController |
+| models/      | ActiveRecord models and entities | Rails ActiveRecord     |
+| views/       | ERB templates for rendering      | Rails ERB              |
+| helpers/     | View helper methods              | Rails ActionView       |
+| mailers/     | Email sending classes            | Rails ActionMailer     |
+| jobs/        | Background job classes           | Rails ActiveJob        |
+
+## Beyond Standard Rails
+
+| Directory    | Description                                                 | Technology                                                        |
+|--------------|-------------------------------------------------------------|-------------------------------------------------------------------|
+| commands/    | Business logic encapsulating use cases (Command Pattern)    | Custom Decidim base class (inspired by Rectify gem).              |
+| forms/       | Form objects for data validation and transformation         | Custom Form base class with Decidim::Attributes                   |
+| cells/       | Reusable view components                                    | Trailblazer::Cells gem                                            |
+| events/      | Activity logging, notifications, event triggering           | Custom Event classes (SimpleEvent, NotificationEvent, EmailEvent) |
+| permissions/ | Authorization and permission checking logic                 | Custom Decidim permission system                                  |
+| queries/     | Database query objects for complex queries                  | Custom Query base class                                           |
+| presenters/  | Decorator classes for view-specific formatting              | SimpleDelegator-based                                             |
+| services/    | Stateless utility and business service classes              | Plain Ruby classes                                                |
+| validators/  | Custom validation classes                                   | Rails Custom Validators                                           |
+| serializers/ | JSON/XML serialization for API responses                    | Custom serializers                                                |
+| uploaders/   | File upload handling                                        | Custom validations for ActiveStorage                              |
+| constraints/ | Rails routing constraints                                   | Custom constraint classes                                         |
+| resolvers/   | GraphQL data resolution                                     | Custom resolver classes                                           |
+| scrubbers/   | HTML content sanitization                                   | Rails::HTML::Scrubber                                             |
+| packs/       | JavaScript/CSS entry points and assets                      | Shakapacker                                                       |
+| assets/      | Static assets (some modules)                                | Asset pipeline                                                    |
+
+## Key Architectural Patterns
+
+**IMPORTANT: You must follow the existing patterns.**
+
+1. **Command Pattern**: Commands in `app/commands/` encapsulate single use cases and broadcast events
+2. **Form Objects**: Forms in `app/forms/` handle validation separately from models
+3. **Cells**: Component-based views using `Trailblazer::Cells` for reusable UI
+4. **Query Objects**: Complex database queries isolated in `app/queries/`
+5. **Events**: Events trigger notifications, logs, and side effects
+6. **Permission System**: Scope-based authorization with action/subject model
+7. **Content Block System**: Customizable page sections via manifests

.ai/build-pipeline-integration.md

@@ -0,0 +1,113 @@
+# Build Pipeline Integration
+
+**CI Requirements:** The `.github/workflows/` contain the production CI setup:
+
+- Tests run on Ubuntu
+- Requires PostgreSQL and Redis services
+- Uses specific Ruby and Node versions
+- Runs parallel tests across multiple modules
+- **Each module CI can timeout at 30-60 minutes - NEVER CANCEL**
+
+## Pre-Commit Checklist
+
+Before committing, ALWAYS run:
+
+```bash
+npm run lint
+bundle exec rubocop
+bundle exec erblint --lint-all
+bundle exec i18n-tasks normalize --locales en
+bundle exec rspec
+npm run test
+```
+
+## Troubleshooting
+
+### JavaScript Lint Failures
+
+```bash
+# View errors
+npm run lint
+
+# Auto-fix what can be fixed
+npm run lint -- --fix
+```
+
+### Ruby Lint Failures (RuboCop)
+
+```bash
+# View errors with details
+bundle exec rubocop
+
+# Auto-fix safe corrections
+bundle exec rubocop -a
+
+# Auto-fix including unsafe corrections (review changes afterward)
+bundle exec rubocop -A
+```
+
+### ERB Lint Failures
+
+```bash
+# View errors
+bundle exec erblint --lint-all
+
+# Auto-fix
+bundle exec erblint --lint-all --autocorrect
+```
+
+### CSS/SCSS Formatting Issues
+
+```bash
+# Check issues
+npm run stylelint
+npm run prettier
+
+# Auto-fix
+npm run prettify
+```
+
+### Translation Key Issues
+
+```bash
+# Normalize and sort keys (only English)
+bundle exec i18n-tasks normalize --locales en
+
+# Find missing keys
+bundle exec i18n-tasks missing
+
+# Find unused keys
+bundle exec i18n-tasks unused
+```
+
+### Test Failures
+
+**IMPORTANT:** When a test fails, always ask the user whether you should fix the test or fix the code that the test is validating. Do not assume which approach is correct.
+
+1. **Read the error message carefully** - RSpec provides detailed failure information
+
+2. **Run the specific failing test** to iterate faster:
+
+```bash
+cd decidim-<module>
+bundle exec rspec spec/path/to/failing_spec.rb:LINE_NUMBER
+```
+
+- You can pass multiple line numbers: file.rb:12:34
+- For failures in shared contexts/examples, always run the concrete example using its file:line from the failure output.
+- Alternatively, run by example description:
+
+```bash
+bundle exec rspec spec/path/to/failing_spec.rb -e "example description"
+```
+
+1. **Check for flaky tests** - If a test passes when run individually but fails in the suite, it may be a test isolation issue
+
+2. **Reset the test database** if you suspect data issues:
+
+```bash
+cd spec/decidim_dummy_app
+bin/rails db:reset RAILS_ENV=test
+```
+
+1. **Check for missing dependencies** - Run `bundle install` and `npm install` if tests fail with load errors

.ai/development-workflow.md

@@ -0,0 +1,206 @@
+# Development Workflow
+
+## Creating a Development App
+
+As decidim is a gem, we need to create a rails application to test it. That's why we have the `development_app`. When you generate it, you create a rails application with the decidim gem using the local files. You only need to generate it once. So if the directory already exists you don't need to generate it again unless a reset is required.
+
+You should not change anything inside this development app as it's a local directory that won't be persisted.
+
+```bash
+# Install dependencies first (if not already done)
+bundle install
+npm install
+
+# Create development app for active development
+bundle exec rake development_app
+cd development_app
+bin/dev  # Starts Rails server with webpack dev server
+```
+
+## Key Development Files and Locations
+
+**Gem Structure:** Each `decidim-*` directory is a separate gem:
+
+- `decidim-core/` - Main framework and shared components
+- `decidim-admin/` - Administrative interface  
+- `decidim-proposals/` - Proposal management component
+- `decidim-participatory_processes/` - Process management
+- `decidim-assemblies/` - Assembly management
+- `decidim-meetings/` - Meeting management
+- `decidim-surveys/` - Survey component
+- And many more...
+
+**Important Files:**
+
+- `Rakefile` - Main build tasks and gem management
+- `Gemfile` - Root dependency specification
+- `package.json` - JavaScript dependencies and scripts
+- `.github/workflows/` - CI/CD pipeline definitions
+- `docs/` - Comprehensive documentation in AsciiDoc format
+
+**JavaScript Assets:** Located in each gem's `app/packs/` directory
+**Stylesheets:** Located in each gem's `app/packs/stylesheets/` directory
+
+## Common Development Tasks
+
+Running the development server:
+
+```bash
+cd development_app
+bin/dev  # Starts Rails + webpack dev server
+# Access at http://localhost:3000
+# Admin panel: http://localhost:3000/admin (after creating admin user)
+```
+
+Database operations:
+
+```bash
+cd development_app
+bin/rails db:drop       # Drop database
+bin/rails db:create     # Create database
+bin/rails db:migrate    # Run migrations
+bin/rails db:seed       # Load sample data
+bin/rails db:reset      # Reset and reseed database
+```
+
+Asset compilation:
+
+```bash
+cd development_app
+bin/rails assets:precompile
+```
+
+## Database Migrations
+
+When creating new features that require database changes, migrations belong in the appropriate `decidim-*` module, not in the development app.
+
+### Creating a Migration
+
+```bash
+cd decidim-<module>
+bin/rails generate migration AddFieldToTableName field_name:type
+```
+
+### Migration File Location
+
+Migrations are stored in each gem's `db/migrate/` directory:
+
+```text
+decidim-<module>/
+└── db/
+    └── migrate/
+        └── YYYYMMDDHHMMSS_migration_name.rb
+```
+
+### Applying Migrations
+
+After creating a migration, regenerate the development or test app to apply it:
+
+```bash
+# For development
+bundle exec rake development_app
+
+# For testing
+bundle exec rake test_app
+```
+
+Or apply migrations directly in an existing app:
+
+```bash
+cd development_app  # or spec/decidim_dummy_app
+bin/rails decidim:upgrade
+bin/rails db:migrate
+```
+
+### Migration Best Practices
+
+- Use reversible migrations when possible
+- Add indexes for foreign keys and frequently queried columns
+- Use `change_column_null` with a default value for non-nullable columns
+- Test migrations in both directions: `bin/rails db:migrate` and `bin/rails db:rollback`
+
+## Data Migrations (data-migrate)
+
+Decidim uses the `data-migrate` gem for data changes that should not live in schema migrations (e.g. backfilling data, transforming existing records, one-off fixes).
+
+Use data migrations when:
+
+- Modifying existing data
+- Backfilling new columns
+- Migrating values between columns or tables
+- Fixing production data inconsistencies
+
+Do **not** use schema migrations for these cases.
+
+### Creating a Data Migration
+
+From the appropriate decidim-* module:
+
+```bash
+cd decidim-<module> bin/rails generate data_migration BackfillSomething
+```
+
+This creates a file under:
+
+```text
+decidim-<module>/
+└── db/
+    └── data/
+        └── YYYYMMDDHHMMSS_backfill_something.rb
+```
+
+### Running Data Migrations
+
+In a development or test app:
+
+```bash
+bin/rails data:migrate
+```
+
+To check status:
+
+```bash
+bin/rails data:migrate:status
+```
+
+### Data Migration Best Practices
+
+- Never reference application models directly.
+- Define a minimal ActiveRecord::Base class inside the migration.
+- Always pin the table name to avoid breakage if models change:
+
+```ruby
+class LegacyProposal < ActiveRecord::Base
+  self.table_name = "decidim_proposals_proposals"
+end
+```
+
+- Avoid callbacks, validations, and scopes.
+- Make migrations idempotent (safe to re-run).
+- Prefer find_each for large datasets.
+- Keep data migrations small and focused.
+
+### Example Pattern
+
+```ruby
+class BackfillPublishedAt < ActiveRecord::Migration[6.1]
+  class Proposal < ActiveRecord::Base
+    self.table_name = "decidim_proposals_proposals"
+  end
+
+  def up
+    Proposal.where(published_at: nil).find_each do |proposal|
+      proposal.update_column(:published_at, proposal.created_at)
+    end
+  end
+
+  def down
+    # no-op (data migrations are usually irreversible)
+  end
+end
+```
+
+### When in Doubt
+
+- Schema change? → regular migration
+- Data change? → data-migrate