ima-claude 2.20.0 → 2.25.0

package/plugins/ima-claude/skills/design-to-code/SKILL.md

@@ -5,122 +5,87 @@ description: "Convert design screenshots into working WordPress code through a t
 
 # Design to Code
 
-Orchestrate the transformation of design screenshots into working WordPress code. Two phases, one skill — produce the implementation prompt (Phase A), then execute it (Phase B).
-
-You are the orchestrator. You analyze designs, compose prompts, delegate implementation, and verify results. You do NOT implement directly — you delegate to `ima-claude:wp-developer` agents.
-
----
+Two-phase workflow: screenshots → implementation prompt (Phase A) → working WordPress code (Phase B). You orchestrate; delegate implementation to `ima-claude:wp-developer`.
 
 ## Mode Selection
 
-Determine the mode from the user's input:
-
 ```
 What did the user provide?
 ├── Screenshots/mockups (no existing prompt)
-│   → Phase A: Design → Prompt
-│   → Read references/phase-a-design-to-prompt.md
-│
-├── An existing implementation prompt
-│   → Phase B: Prompt → Code
-│   → Read references/phase-b-prompt-to-code.md
-│
+│   → Phase A → references/phase-a-design-to-prompt.md
+├── Existing implementation prompt
+│   → Phase B → references/phase-b-prompt-to-code.md
 └── Screenshots + "implement this" / "full pipeline"
     → Phase A then Phase B in sequence
-    → Phase A produces prompt → user reviews → Phase B executes
 ```
 
----
-
 ## Required Skills
 
-Always load alongside this skill:
-- **`ima-brand`** — color palette, typography, mixins (needed for both phases)
-- **`ima-bootstrap`** — utility classes, grid system, components
-
-Phase B additionally needs:
-- **`php-fp-wordpress`** — WordPress development patterns, security, shortcodes
-
----
+- **`ima-brand`** — color palette, typography, mixins (both phases)
+- **`ima-bootstrap`** — utility classes, grid, components
+- **`php-fp-wordpress`** — WordPress patterns (Phase B only)
 
 ## Phase A: Design → Prompt
 
-Transform design screenshots into a detailed, section-by-section implementation prompt. Output: a ~200-300 line prompt file matching the team's established template structure.
-
-Before starting, search Qdrant for `design-to-prompt` to recall prior lessons.
-
-### Steps (read `references/phase-a-design-to-prompt.md` for detailed procedures)
-
-1. **GATHER** — Fetch Jira context + receive screenshots + explore codebase (parallel)
-2. **ANALYZE** — Load brand palette from `ima-brand` (**must complete before COMPOSE**)
-3. **CROP** — Full view → section detection → detail crops (iterative PIL cropping)
-4. **EXTRACT** — Per crop: exact text, icons, colors, layout, spacing
-5. **MAP** — Visual elements → brand variables, components → existing shortcodes
-6. **COMPOSE** — Write prompt using `references/prompt-template.md` structure
-7. **VALIDATE** — Re-check each section against its crop for accuracy
+Output: ~200-300 line prompt file matching team template. Search Qdrant for `design-to-prompt` before starting.
 
-**Output**: Save prompt to `docs/designs/{ticket}/PROMPT.md` and Serena memory as `{feature-name}-plan`.
+| Step | Action |
+|------|--------|
+| GATHER | Fetch Jira context + receive screenshots + explore codebase (parallel) |
+| ANALYZE | Load brand palette from `ima-brand` — must complete before COMPOSE |
+| CROP | Full view → section detection → detail crops (iterative PIL cropping) |
+| EXTRACT | Per crop: exact text, icons, colors, layout, spacing |
+| MAP | Visual elements → brand variables, components → existing shortcodes |
+| COMPOSE | Write prompt using `references/prompt-template.md` structure |
+| VALIDATE | Re-check each section against its crop for accuracy |
 
-After Phase A, present the prompt to the user. Stop here unless running full pipeline.
-
----
+Save prompt to `docs/designs/{ticket}/PROMPT.md` and Serena memory as `{feature-name}-plan`. Present to user; stop here unless running full pipeline.
 
 ## Phase B: Prompt → Code
 
-Execute an implementation prompt to produce working WordPress code. Input: a structured prompt (from Phase A or user-provided).
-
-Before starting, search Qdrant for `design-to-code` to recall prior lessons.
+Search Qdrant for `design-to-code` before starting.
 
-### Steps (read `references/phase-b-prompt-to-code.md` for detailed procedures)
-
-1. **RESEARCH** — Brand SCSS files + current code + component libraries (parallel explorers)
-2. **ARCHITECTURE** — New file vs modify, function reuse, component migration decision
-3. **DECOMPOSE** — Stories by page section; Story 1 = foundation, Stories 2-N = parallel fills, final = polish
-4. **IMPLEMENT** — Delegate to `ima-claude:wp-developer` per story with precise prompts
-5. **REVIEW** — Verify copy, colors, element order, asset paths (orchestrator review before visual test)
-6. **VISUAL-QA** — Compile SASS → screenshot desktop + mobile → compare to design → iterate
-
----
+| Step | Action |
+|------|--------|
+| RESEARCH | Brand SCSS files + current code + component libraries (parallel explorers) |
+| ARCHITECTURE | New file vs modify, function reuse, component migration decision |
+| DECOMPOSE | Stories by page section; Story 1 = foundation, Stories 2-N = parallel fills, final = polish |
+| IMPLEMENT | Delegate to `ima-claude:wp-developer` per story with precise prompts |
+| REVIEW | Verify copy, colors, element order, asset paths before visual test |
+| VISUAL-QA | Compile SASS → screenshot desktop + mobile → compare to design → iterate |
 
 ## Critical Guardrails
 
-Read `references/guardrails.md` for the complete set. The top 5 (each learned from a real failure):
+Full set in `references/guardrails.md`. Top 5:
 
-1. **Never hardcode colors** — always brand SCSS variables or Bootstrap utilities
-2. **Always verify asset paths exist** — Glob/grep before referencing; check existing usage patterns
-3. **Always provide exact copy text** — never let agents paraphrase; include verbatim text in quotes
-4. **Load brand palette BEFORE composition** — informs every color reference on first pass
-5. **Check site header/footer first** — don't build custom components that duplicate existing site elements
+1. Never hardcode colors — use brand SCSS variables or Bootstrap utilities
+2. Always verify asset paths exist — Glob/grep before referencing
+3. Always provide exact copy text — include verbatim text in quotes, never let agents paraphrase
+4. Load brand palette BEFORE composition — informs every color reference on first pass
+5. Check site header/footer first — don't build components that duplicate existing site elements
 
----
-
-## Agent Delegation Model
+## Agent Delegation
 
 | Role | Agent | When |
-|---|---|---|
+|------|-------|------|
 | Orchestrator | opus (you) | All phases — research, planning, decomposition, delegation, review, surgical fixes |
 | Codebase explorer | `ima-claude:explorer` (haiku) | GATHER/RESEARCH: find existing shortcodes, templates, SCSS files |
 | Implementer | `ima-claude:wp-developer` (sonnet) | IMPLEMENT: write PHP/SCSS with skills: ima-brand, ima-bootstrap, php-fp-wordpress |
-| Reviewer | `ima-claude:reviewer` (sonnet, read-only) | REVIEW: brand compliance + accessibility audit (for larger implementations) |
-
-Orchestrator does surgical fixes (<5 lines) directly via Edit tool. Anything larger → delegate to wp-developer.
+| Reviewer | `ima-claude:reviewer` (sonnet, read-only) | REVIEW: brand compliance + accessibility audit (larger implementations) |
 
----
+Orchestrator does surgical fixes (<5 lines) directly via Edit. Anything larger → delegate to wp-developer.
 
 ## Qdrant Integration
 
-Before each phase, search Qdrant for prior lessons:
-- Phase A: `qdrant_find("design-to-prompt workflow")` — retrieves methodology, cropping techniques, composition decisions
-- Phase B: `qdrant_find("design-to-code implementation")` — retrieves decomposition patterns, delegation templates, QA patterns
-
----
+- Phase A: `qdrant_find("design-to-prompt workflow")`
+- Phase B: `qdrant_find("design-to-code implementation")`
 
 ## Related Skills
 
 | Skill | Relationship |
-|---|---|
+|-------|------|
 | `ima-brand` | Required — color palette, typography, mixins |
 | `ima-bootstrap` | Required — utility classes, grid, components |
-| `php-fp-wordpress` | Required for Phase B — WordPress dev patterns |
-| `task-master` | Optional — for complex multi-page designs needing Epic > Story > Task decomposition |
-| `prompt-starter` | Pattern borrowed — Phase A follows its "builder not executor" philosophy |
+| `php-fp-wordpress` | Required for Phase B |
+| `task-master` | Optional — complex multi-page designs needing Epic > Story > Task |
+| `prompt-starter` | Phase A follows its "builder not executor" philosophy |

package/plugins/ima-claude/skills/discourse/SKILL.md

@@ -5,59 +5,38 @@ description: "Discourse plugin development - plugin.rb, after_initialize, admin
 
 # Discourse Plugin Development
 
-Discourse plugins are Rails engines with conventions. Work with the framework — its plugin API, Guardian authorization system, and event hooks exist for good reason.
+Discourse plugins are Rails engines. Work with the framework — Plugin API, Guardian, and event hooks exist for good reason.
 
-## When to Use This Skill
+## Core Rules
 
-- Building or modifying Discourse plugins
-- Adding admin UI to a Discourse plugin
-- Implementing authentication hooks or user lifecycle extensions
-- Migrating data into Discourse (import scripts)
-- Reviewing Discourse plugin security
+- `after_initialize` — all plugin wiring goes here
+- `Guardian` — authorization layer; every user action checks it
+- `register_*` / `add_*` — use Plugin API hooks, not monkey-patches
+- `StaffConstraint` — required on all admin routes; never roll your own
+- `RuboCop` — enforced; Discourse ships lint rules
 
-## Core Philosophy
-
-> Discourse plugins are Rails. Discourse adds its own authorization layer (Guardian). Respect both.
-
-- **`after_initialize`** is where plugin logic wires into Discourse
-- **Guardian** is the authorization layer — every action checks it
-- **Plugin API** hooks (`register_*`, `add_*`) are the extension points — don't monkey-patch core
-- **StaffConstraint** protects admin routes — use it, never roll your own
-- **RuboCop** is enforced — Discourse ships lint rules
-
-**Foundation**: Reference `../rails/SKILL.md` for Rails security practices and `../ruby-fp/SKILL.md` for Ruby patterns.
+Foundation: `../rails/SKILL.md` (security), `../ruby-fp/SKILL.md` (patterns).
 
 ## Plugin Structure
 
 ```
 my-plugin/
 ├── plugin.rb               # Manifest + bootstrap (required)
-├── about.json              # Metadata for admin panel
+├── about.json
 ├── app/
-│   ├── controllers/
-│   │   └── admin/
-│   │       └── my_plugin_controller.rb
-│   ├── models/
-│   │   └── my_plugin_record.rb
-│   └── serializers/
-│       └── my_plugin_serializer.rb
+│   ├── controllers/admin/my_plugin_controller.rb
+│   ├── models/my_plugin_record.rb
+│   └── serializers/my_plugin_serializer.rb
 ├── config/
-│   ├── locales/
-│   │   └── server.en.yml
-│   └── settings.yml        # Site settings
-├── db/
-│   └── migrate/
-│       └── 20250101000000_create_my_plugin.rb
-├── assets/
-│   └── javascripts/
-│       └── admin/          # Ember components for admin UI
-├── lib/
-│   └── my_plugin/          # Pure logic (no Discourse deps)
-└── spec/
-    └── plugin_helper.rb
+│   ├── locales/server.en.yml
+│   └── settings.yml
+├── db/migrate/
+├── assets/javascripts/admin/   # Ember admin UI
+├── lib/my_plugin/              # Pure logic (no Discourse deps)
+└── spec/plugin_helper.rb
 ```
 
-## plugin.rb: Manifest + Bootstrap
+## plugin.rb
 
 ```ruby
 # frozen_string_literal: true
@@ -68,63 +47,44 @@ my-plugin/
 # authors: Your Name
 # url: https://github.com/yourorg/my-plugin
 
-# Autoloading — define module first, then require engine
 module ::MyPlugin
   PLUGIN_NAME = "my-plugin"
 end
 
 require_relative "lib/my_plugin/engine"
 
-# All wiring happens inside after_initialize
 after_initialize do
-  # Register settings, hooks, extensions here
-  # This runs after Discourse core is fully loaded
+  # All wiring here — runs after Discourse core is fully loaded
 end
 ```
 
-## after_initialize: The Plugin Entry Point
+## after_initialize
 
 ```ruby
 after_initialize do
-  # Extend models — use class_eval in after_initialize, not top-level monkey-patches
   User.class_eval do
     has_one :my_plugin_profile, dependent: :destroy
   end
 
-  # Register custom fields
   register_post_custom_field_type('wp_original_id', :integer)
   register_topic_custom_field_type('imported_from', :string)
 
-  # Wire into Discourse events (preferred over overriding methods)
-  on(:user_created) do |user|
-    MyPlugin::UserSetup.call(user)
-  end
-
-  on(:post_created) do |post, opts, user|
-    MyPlugin::PostSync.call(post, user)
-  end
+  on(:user_created) { |user| MyPlugin::UserSetup.call(user) }
+  on(:post_created) { |post, opts, user| MyPlugin::PostSync.call(post, user) }
 
-  # Add serializer extensions
-  add_to_serializer(:user, :wp_user_id) do
-    object.custom_fields['wp_user_id']
-  end
+  add_to_serializer(:user, :wp_user_id) { object.custom_fields['wp_user_id'] }
 end
 ```
 
 ## Admin Routes + Controller
 
-Every admin route needs `StaffConstraint` — never expose admin actions without it.
-
 ```ruby
-# In plugin.rb — register the admin nav link
+# plugin.rb
 add_admin_route 'my_plugin.title', 'my-plugin'
 
-# Wire the route
 Discourse::Application.routes.append do
-  get '/admin/plugins/my-plugin' => 'admin/my_plugin#index',
-      constraints: StaffConstraint.new
-  post '/admin/plugins/my-plugin/action' => 'admin/my_plugin#action',
-      constraints: StaffConstraint.new
+  get  '/admin/plugins/my-plugin'         => 'admin/my_plugin#index',  constraints: StaffConstraint.new
+  post '/admin/plugins/my-plugin/action'  => 'admin/my_plugin#action', constraints: StaffConstraint.new
 end
 ```
 
@@ -133,21 +93,15 @@ end
 # frozen_string_literal: true
 
 class ::Admin::MyPluginController < ::Admin::AdminController
-  # Admin::AdminController already requires:
-  # - User is logged in
-  # - User is staff (moderator or admin)
-  # For admin-only actions, add:
+  # AdminController enforces: logged_in + staff
+  # For admin-only actions:
   before_action :ensure_admin, only: [:dangerous_action]
 
   def index
-    render json: {
-      stats: MyPlugin::Stats.summary,
-      settings: SiteSetting.my_plugin_enabled
-    }
+    render json: { stats: MyPlugin::Stats.summary, settings: SiteSetting.my_plugin_enabled }
   end
 
   def action
-    # Strong parameters for any mutating action
     attrs = params.require(:my_plugin).permit(:field_one, :field_two)
     result = MyPlugin::SomeService.call(attrs.to_h.symbolize_keys)
 
@@ -160,26 +114,18 @@ class ::Admin::MyPluginController < ::Admin::AdminController
 end
 ```
 
-## Guardian: Authorization Layer
-
-Guardian is Discourse's authorization system. Always check it for user-facing actions.
+## Guardian
 
 ```ruby
-# Check permissions before acting
 def update_post
   post = Post.find(params[:id])
-
-  # guardian.can_edit_post? checks ownership, trust level, staff status
-  unless guardian.can_edit_post?(post)
-    return render json: failed_json, status: :forbidden
-  end
+  return render json: failed_json, status: :forbidden unless guardian.can_edit_post?(post)
 
   post.update!(body: params[:body])
   render json: PostSerializer.new(post, scope: guardian).as_json
 end
 
-# Extending Guardian for plugin-specific permissions
-# In after_initialize:
+# Extend Guardian in after_initialize:
 module ::Guardian::MyPluginExtensions
   def can_use_my_feature?
     authenticated? && (is_staff? || user.trust_level >= 2)
@@ -189,69 +135,42 @@ end
 Guardian.prepend(::Guardian::MyPluginExtensions)
 ```
 
-## Security Non-Negotiables
+## Security
 
-### 1. Never Raw SQL with Interpolation — Use ActiveRecord or Named Params
+### SQL — no interpolation
 
 ```ruby
-# BAD — SQL injection
+# BAD
 User.where("username = '#{params[:username]}'")
 DB.query("SELECT * FROM users WHERE id = #{user_id}")
 
-# GOOD — ActiveRecord parameterization
+# GOOD
 User.where(username: params[:username])
-User.where("created_at > ?", params[:since])
-
-# GOOD — Discourse DB helper with named bind params (always use this for raw SQL)
 DB.query("SELECT * FROM users WHERE id = :id", id: user_id.to_i)
-DB.query("UPDATE users SET flag = TRUE WHERE id = :id", id: user_id.to_i)
-```
-
-### 2. Staff-Only Admin Routes
-
-```ruby
-# ALWAYS use StaffConstraint on admin routes
-get '/admin/plugins/my-plugin' => 'admin/my_plugin#index',
-    constraints: StaffConstraint.new
-
-# Admin::AdminController gives you these checks automatically:
-# - ensure_logged_in
-# - ensure_staff
-# For admin-only (not just moderator), add ensure_admin
 ```
 
-### 3. No Sensitive Data in Logs
+### Logs — no sensitive values
 
 ```ruby
-# BAD — logs hash values, tokens, passwords
-Rails.logger.warn("[MyPlugin] Processing hash: #{user_hash}")
-Rails.logger.info("[MyPlugin] Token: #{token}")
+# BAD
+Rails.logger.warn("[MyPlugin] Hash: #{user_hash}")
 
-# GOOD — log what happened, not the sensitive value
+# GOOD
 Rails.logger.info("[MyPlugin] Processing user #{user.id}")
-Rails.logger.warn("[MyPlugin] Auth failed for user #{user.id}")
 ```
 
-### 4. Custom Fields — Validate Types
+### Custom fields — register types
 
 ```ruby
-# Register field types to prevent type confusion
 register_user_custom_field_type('my_plugin_id', :integer)
-register_post_custom_field_type('source_url', :string)
-
-# Whitelist custom fields for API/serializer exposure
 DiscoursePluginRegistry.serialized_current_user_fields << 'my_plugin_id'
-
-# Access safely — always coerce type
 user_id = (user.custom_fields['my_plugin_id'].to_i rescue nil)
 ```
 
-### 5. Rate Limiting on Sensitive Endpoints
+### Rate limiting
 
 ```ruby
-# For endpoints that test credentials or perform expensive operations
 RateLimiter.new(current_user, "my_plugin_sensitive_action", 5, 1.minute).performed!
-# Raises RateLimiter::LimitExceeded if over limit
 ```
 
 ## Site Settings
@@ -261,7 +180,7 @@ RateLimiter.new(current_user, "my_plugin_sensitive_action", 5, 1.minute).perform
 plugins:
   my_plugin_enabled:
     default: false
-    client: false  # server-side only unless UI needs it
+    client: false
   my_plugin_max_items:
     default: 100
     min: 1
@@ -270,29 +189,22 @@ plugins:
 ```
 
 ```ruby
-# Access in code
-SiteSetting.my_plugin_enabled
-SiteSetting.my_plugin_max_items
-
-# Guard features
 return unless SiteSetting.my_plugin_enabled
+SiteSetting.my_plugin_max_items
 ```
 
 ## Migrations
 
 ```ruby
-# db/migrate/20250101000000_create_my_plugin_records.rb
 # frozen_string_literal: true
-
 class CreateMyPluginRecords < ActiveRecord::Migration[7.0]
   def change
     create_table :my_plugin_records do |t|
       t.integer :user_id, null: false
-      t.string :source_id, null: false
-      t.text :data
+      t.string  :source_id, null: false
+      t.text    :data
       t.timestamps
     end
-
     add_index :my_plugin_records, :user_id
     add_index :my_plugin_records, :source_id, unique: true
     add_foreign_key :my_plugin_records, :users
@@ -300,20 +212,17 @@ class CreateMyPluginRecords < ActiveRecord::Migration[7.0]
 end
 ```
 
-## Import Script Pattern (Standalone Ruby)
-
-Import scripts inherit from `ImportScripts::Base` and run outside the Rails request cycle.
+## Import Script
 
 ```ruby
 # frozen_string_literal: true
-
 require_relative "base"
 
 class ImportScripts::MyImport < ImportScripts::Base
   def initialize
     super
     @client = Mysql2::Client.new(
-      host: ENV.fetch('SOURCE_DB_HOST'),
+      host:     ENV.fetch('SOURCE_DB_HOST'),
       username: ENV.fetch('SOURCE_DB_USER'),
       password: ENV.fetch('SOURCE_DB_PASSWORD'),
       database: ENV.fetch('SOURCE_DB_NAME')
@@ -329,26 +238,16 @@ class ImportScripts::MyImport < ImportScripts::Base
   private
 
   def import_users
-    puts "Importing users..."
-
-    # Parameterized query — never interpolate
     users = @client.query(
       "SELECT id, email, username, display_name FROM wp_users WHERE user_status = 0",
       as: :hash
     )
-
-    create_users(users) do |user|
-      {
-        id: user['id'],
-        email: user['email'],
-        username: normalize_username(user['username']),
-        name: user['display_name']
-      }
+    create_users(users) do |u|
+      { id: u['id'], email: u['email'], username: normalize_username(u['username']), name: u['display_name'] }
     end
   end
 
   def normalize_username(raw)
-    # Pure function — transform only, no side effects
     raw.to_s.strip.downcase.gsub(/[^a-z0-9_]/, '_').truncate(20)
   end
 end
@@ -359,10 +258,8 @@ ImportScripts::MyImport.new.perform
 ## Testing
 
 ```ruby
-# spec/plugin_helper.rb — loads Discourse test env
 require 'rails_helper'
 
-# spec/requests/admin/my_plugin_spec.rb
 RSpec.describe Admin::MyPluginController do
   fab!(:admin) { Fabricate(:admin) }
   fab!(:user)  { Fabricate(:user) }
@@ -370,27 +267,24 @@ RSpec.describe Admin::MyPluginController do
   before { sign_in(admin) }
 
   describe "GET #index" do
-    it "returns success for admin" do
+    it "returns 200 for admin" do
       get "/admin/plugins/my-plugin.json"
       expect(response.status).to eq(200)
     end
   end
 
   describe "authorization" do
-    it "rejects non-staff" do
+    it "rejects non-staff with 404" do
       sign_in(user)
       get "/admin/plugins/my-plugin.json"
-      expect(response.status).to eq(404)  # Discourse returns 404 for staff routes
+      expect(response.status).to eq(404)
     end
   end
 end
 
-# Pure logic specs — no Discourse dependencies
 RSpec.describe MyPlugin::UserSetup do
-  describe ".call" do
-    it "normalizes username" do
-      expect(described_class.normalize("John Doe!")).to eq("john_doe_")
-    end
+  it "normalizes username" do
+    expect(described_class.normalize("John Doe!")).to eq("john_doe_")
   end
 end
 ```
@@ -398,43 +292,34 @@ end
 ## Security Checklist
 
 - [ ] `StaffConstraint.new` on all admin routes
-- [ ] Inherited from `Admin::AdminController` for admin endpoints
-- [ ] Strong parameters on all mutating endpoints
-- [ ] No string interpolation in SQL — use ActiveRecord or `DB.query` with `:named` params
-- [ ] `guardian.can_*?` checked before user-facing mutations
-- [ ] No sensitive values (tokens, hashes, passwords) in log output
-- [ ] Rate limiting on credential-testing or expensive endpoints
-- [ ] Custom field types registered (`register_*_custom_field_type`)
-- [ ] Site settings used for feature flags, not hardcoded booleans
+- [ ] Inherit `Admin::AdminController` for admin endpoints
+- [ ] Strong params (`require().permit()`) on all mutations
+- [ ] No SQL interpolation — use ActiveRecord or `DB.query` with `:named` params
+- [ ] `guardian.can_*?` before user-facing mutations
+- [ ] No sensitive values in logs
+- [ ] Rate limiting on credential-testing / expensive endpoints
+- [ ] Custom field types registered
+- [ ] Feature flags via SiteSettings, not hardcoded booleans
 
 ## Common Pitfalls
 
-| Pitfall | Correct Approach |
-|---------|-----------------|
-| Monkey-patching Discourse classes | Use `class_eval` / `prepend` in `after_initialize` |
-| Direct DB string interpolation | `DB.query("... WHERE id = :id", id: val)` |
-| Checking `current_user.staff?` in controller | Inherit `Admin::AdminController` instead |
-| Logging `user.password_hash` for debugging | Log `user.id` only |
-| `params[:field]` without strong params | Always `params.require().permit()` |
-| Hardcoded credentials in plugin.rb | `ENV.fetch('KEY')` or Rails credentials |
-
-## When to Load Reference Files
-
-### Security Examples
-**File**: [`references/security.md`](references/security.md)
-**Load when**: Implementing auth hooks, custom Guardian checks, SQL safety in import scripts
-**Contains**: Guardian extension patterns, DB.query vs ActiveRecord, rate limiting, log hygiene
+| Pitfall | Fix |
+|---------|-----|
+| Monkey-patching Discourse classes | `class_eval` / `prepend` in `after_initialize` |
+| SQL string interpolation | `DB.query("… WHERE id = :id", id: val)` |
+| `current_user.staff?` check in controller | Inherit `Admin::AdminController` |
+| Logging `user.password_hash` | Log `user.id` only |
+| Raw `params[:field]` | Always `params.require().permit()` |
+| Hardcoded credentials | `ENV.fetch('KEY')` |
 
-### Admin UI (Ember)
-**File**: [`references/admin-ui.md`](references/admin-ui.md)
-**Load when**: Building admin panel Ember components
-**Contains**: Route setup, Ember component patterns, REST adapter, admin nav
+## Reference Files
 
-### Import Scripts
-**File**: [`references/import-scripts.md`](references/import-scripts.md)
-**Load when**: Writing data migration scripts
-**Contains**: ImportScripts::Base lifecycle, batching, lookup maps, resume/idempotency
+| File | Load when |
+|------|-----------|
+| [`references/security.md`](references/security.md) | Auth hooks, Guardian extensions, SQL safety in imports |
+| [`references/admin-ui.md`](references/admin-ui.md) | Admin panel Ember components |
+| [`references/import-scripts.md`](references/import-scripts.md) | Data migration: batching, lookup maps, idempotency |
 
 ---
 
-**Evidence Base**: Discourse Developer Docs, Discourse GitHub (discourse-solved, discourse-data-explorer), Discourse CVE history (2024–2026), Rails Security Guide.
+**Evidence Base**: Discourse Developer Docs, discourse-solved, discourse-data-explorer, Discourse CVE history (2024–2026), Rails Security Guide.