beskar 0.1.0 → 0.2.0

data/app/views/beskar/banned_ips/show.html.erb

@@ -3,12 +3,8 @@
 <% content_for :header_actions do %>
   <%= link_to "← Back to Banned IPs", banned_ips_path, class: "btn btn-secondary" %>
   <%= link_to "Edit", edit_banned_ip_path(@banned_ip), class: "btn btn-secondary" %>
-  <%= link_to "Unban", banned_ip_path(@banned_ip),
-      data: {
-        "turbo-method": "delete",
-        "turbo-confirm": "Are you sure you want to unban #{@banned_ip.ip_address}?"
-      },
-      class: "btn btn-danger" %>
+  <%= link_to "Action History", administrative_actions_path(target_id: @banned_ip.id), class: "btn btn-secondary" %>
+  <%= link_to "Unban", review_banned_ip_path(@banned_ip, operation: "unban"), class: "btn btn-danger" %>
 <% end %>
 
 <!-- Ban Overview -->
@@ -143,7 +139,7 @@
       </div>
 
       <div style="text-align: center; padding: 1rem; background: #FAFBFC; border-radius: 6px;">
-        <div style="font-size: 24px; font-weight: 600; color: <%= @stats[:avg_risk_score] > 70 ? '#E91E63' : '#1A1F36' %>;">
+        <div style="font-size: 24px; font-weight: 600; color: <%= risk_level_color(@stats[:avg_risk_score]) %>;">
           <%= @stats[:avg_risk_score] %>
         </div>
         <div style="font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.025em; color: #697386; margin-top: 0.25rem;">
@@ -152,7 +148,7 @@
       </div>
 
       <div style="text-align: center; padding: 1rem; background: #FAFBFC; border-radius: 6px;">
-        <div style="font-size: 24px; font-weight: 600; color: <%= @stats[:max_risk_score] > 85 ? '#D32F2F' : '#1A1F36' %>;">
+        <div style="font-size: 24px; font-weight: 600; color: <%= risk_level_color(@stats[:max_risk_score]) %>;">
           <%= @stats[:max_risk_score] %>
         </div>
         <div style="font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.025em; color: #697386; margin-top: 0.25rem;">
@@ -239,11 +235,11 @@
                 <td>
                   <% if event.user %>
                     <div style="font-size: 13px;">
-                      <%= event.user.try(:email) || "User ##{event.user_id}" %>
+                      <%= audit_user_label(event) %>
                     </div>
                   <% elsif event.attempted_email %>
                     <div style="font-size: 13px; color: #697386;">
-                      <%= event.attempted_email %>
+                      <%= audit_user_label(event) %>
                     </div>
                   <% else %>
                     <span style="color: #C1C7D0;">-</span>
@@ -295,16 +291,14 @@
               ['Make Permanent', 'permanent']
             ]),
             style: "padding: 0.5rem 0.75rem; font-size: 14px;" %>
+        <%= label_tag :audit_reason, "Administrative reason" %>
+        <%= text_field_tag :audit_reason, nil, required: true, maxlength: 1000 %>
         <%= submit_tag "Extend Ban", class: "btn btn-warning" %>
       <% end %>
     </div>
   <% end %>
 
-  <%= link_to "Unban IP", banned_ip_path(@banned_ip),
-      data: {
-        "turbo-method": "delete",
-        "turbo-confirm": "Are you sure you want to unban #{@banned_ip.ip_address}?"
-      },
+  <%= link_to "Unban IP", review_banned_ip_path(@banned_ip, operation: "unban"),
       class: "btn btn-danger",
       style: "margin-left: #{ @banned_ip.active? && !@banned_ip.permanent? ? '0' : 'auto' };" %>
 </div>

data/app/views/beskar/dashboard/index.html.erb

@@ -38,7 +38,7 @@
     <div class="stat-value" style="color: var(--primary);">
       <%= number_with_delimiter(@stats[:high_risk_events]) %>
     </div>
-    <div class="stat-change">Score > 60</div>
+    <div class="stat-change">Score &ge; <%= Beskar::RiskLevel::RANGES[:high].begin %></div>
   </div>
 
   <div class="stat-card">
@@ -46,7 +46,7 @@
     <div class="stat-value" style="color: #D32F2F;">
       <%= number_with_delimiter(@stats[:critical_threats]) %>
     </div>
-    <div class="stat-change">Score > 85</div>
+    <div class="stat-change">Score &ge; <%= Beskar::RiskLevel::RANGES[:critical].begin %></div>
   </div>
 </div>
 
@@ -172,11 +172,11 @@
                 <td>
                   <% if event.user %>
                     <div style="font-size: 13px;">
-                      <%= event.user.try(:email) || "User ##{event.user_id}" %>
+                      <%= audit_user_label(event) %>
                     </div>
                   <% elsif event.attempted_email %>
                     <div style="font-size: 13px; color: #697386;">
-                      <%= event.attempted_email %>
+                      <%= audit_user_label(event) %>
                     </div>
                   <% else %>
                     <span style="color: #C1C7D0;">-</span>

data/app/views/beskar/security_events/index.html.erb

@@ -2,10 +2,7 @@
 
 <% content_for :header_actions do %>
   <div style="display: flex; gap: 0.5rem;">
-    <%= link_to "Export CSV", export_security_events_path(request.query_parameters.merge(format: :csv)),
-        class: "btn btn-secondary" %>
-    <%= link_to "Export JSON", export_security_events_path(request.query_parameters.merge(format: :json)),
-        class: "btn btn-secondary" %>
+    <%= render "beskar/shared/export_form", export_url: export_security_events_path %>
   </div>
 <% end %>
 
@@ -46,12 +43,7 @@
         <div class="form-group">
           <label>Risk Level</label>
           <%= select_tag :risk_level,
-              options_for_select([
-                ['Low (0-30)', 'low'],
-                ['Medium (31-60)', 'medium'],
-                ['High (61-85)', 'high'],
-                ['Critical (86-100)', 'critical']
-              ], params[:risk_level]),
+              options_for_select(@risk_levels, params[:risk_level]),
               prompt: 'All risk levels',
               style: "width: 100%;" %>
         </div>
@@ -109,15 +101,16 @@
   </div>
 
   <div style="display: flex; align-items: center; gap: 0.5rem;">
-    <label style="margin: 0; font-size: 13px; color: #697386;">Per page:</label>
+    <label for="per_page" style="margin: 0; font-size: 13px; color: #697386;">Per page:</label>
     <%= form_with url: security_events_path, method: :get, local: true, style: "display: inline;" do |f| %>
-      <% request.query_parameters.except(:per_page).each do |key, value| %>
+      <% request.query_parameters.except("per_page", "page").each do |key, value| %>
         <%= hidden_field_tag key, value %>
       <% end %>
       <%= select_tag :per_page,
           options_for_select([10, 25, 50, 100], params[:per_page]&.to_i || 25),
-          onchange: "this.form.submit();",
+          data: { beskar_auto_submit: true },
           style: "padding: 0.25rem 0.5rem; font-size: 13px;" %>
+      <%= submit_tag "Apply page size", class: "btn btn-sm btn-secondary" %>
     <% end %>
   </div>
 </div>
@@ -178,14 +171,14 @@
                 <td>
                   <% if event.user %>
                     <div style="font-size: 13px;">
-                      <%= event.user.try(:email) || "User ##{event.user_id}" %>
+                      <%= audit_user_label(event) %>
                     </div>
                     <div style="font-size: 11px; color: #697386;">
                       ID: <%= event.user_id %>
                     </div>
                   <% elsif event.attempted_email %>
                     <div style="font-size: 13px; color: #697386;">
-                      <%= event.attempted_email %>
+                      <%= audit_user_label(event) %>
                     </div>
                     <div style="font-size: 11px; color: #C1C7D0;">
                       (attempted)

data/app/views/beskar/security_events/show.html.erb

@@ -35,25 +35,11 @@
           Risk Score
         </div>
         <div style="display: flex; align-items: center; gap: 0.75rem;">
-          <span style="font-size: 24px; font-weight: 600; color: <%=
-            case @event.risk_score
-            when 0..30 then '#4CAF50'
-            when 31..60 then '#FF9800'
-            when 61..85 then '#E91E63'
-            else '#D32F2F'
-            end
-          %>;">
+          <span style="font-size: 24px; font-weight: 600; color: <%= risk_level_color(@event.risk_score) %>;">
             <%= @event.risk_score %>
           </span>
           <span class="badge badge-<%= risk_level_class(@event.risk_score) %>">
-            <%=
-              case @event.risk_score
-              when 0..30 then 'Low Risk'
-              when 31..60 then 'Medium Risk'
-              when 61..85 then 'High Risk'
-              else 'Critical'
-              end
-            %>
+            <%= risk_level_label(@event.risk_score) %>
           </span>
         </div>
       </div>
@@ -101,14 +87,14 @@
         </div>
         <% if @event.user %>
           <div style="font-size: 14px; color: #1A1F36;">
-            <%= @event.user.try(:email) || "User ##{@event.user_id}" %>
+            <%= audit_user_label(@event) %>
           </div>
           <div style="font-size: 13px; color: #697386; margin-top: 0.25rem;">
             ID: <%= @event.user_id %> • Type: <%= @event.user_type %>
           </div>
         <% elsif @event.attempted_email %>
           <div style="font-size: 14px; color: #697386;">
-            <%= @event.attempted_email %> <span style="font-size: 12px;">(attempted)</span>
+            <%= audit_user_label(@event) %> <span style="font-size: 12px;">(attempted)</span>
           </div>
         <% else %>
           <div style="color: #C1C7D0;">No user associated</div>
@@ -214,9 +200,9 @@
                 </td>
                 <td>
                   <% if event.user %>
-                    <%= event.user.try(:email) || "User ##{event.user_id}" %>
+                    <%= audit_user_label(event) %>
                   <% elsif event.attempted_email %>
-                    <span style="color: #697386;"><%= event.attempted_email %></span>
+                    <span style="color: #697386;"><%= audit_user_label(event) %></span>
                   <% else %>
                     <span style="color: #C1C7D0;">-</span>
                   <% end %>

data/app/views/beskar/shared/_export_form.html.erb

@@ -0,0 +1,10 @@
+<%= form_with url: export_url, method: :get, local: true do %>
+  <% request.query_parameters.except("format", "audit_reason", "page", "per_page").each do |key, value| %>
+    <%= hidden_field_tag key, value if value.is_a?(String) %>
+  <% end %>
+  <%= label_tag :export_audit_reason, "Export reason" %>
+  <%= text_field_tag :audit_reason, nil, id: :export_audit_reason, required: true, maxlength: 1000 %>
+  <%= label_tag :export_format, "Export format" %>
+  <%= select_tag :format, options_for_select([["CSV", "csv"], ["JSON", "json"]]), id: :export_format %>
+  <%= submit_tag "Export", class: "btn btn-secondary" %>
+<% end %>

data/app/views/layouts/beskar/_behavior.html.erb

@@ -0,0 +1,121 @@
+<%= javascript_tag nonce: true do %>
+  (() => {
+    // One delegated installation per document, even if a host evaluates the
+    // layout again. Native navigation is the dashboard's supported boundary.
+    if (window.beskarDashboardBehaviorInstalled) return;
+    window.beskarDashboardBehaviorInstalled = true;
+
+    function isPermanent(form) {
+      return form.querySelector('[name="ban_type"]:checked')?.value === 'permanent' ||
+        form.querySelector('[name="banned_ip[permanent]"]:checked')?.value === 'true';
+    }
+
+    function updateBanForm(form) {
+      const permanent = isPermanent(form);
+      const options = form.querySelector('#temporary-options');
+      options.hidden = permanent;
+      options.querySelectorAll('input, select, button').forEach(input => { input.disabled = permanent; });
+      const expiry = form.querySelector('#banned_ip_expires_at');
+      expiry.required = !permanent && !!form.querySelector('[name="banned_ip[permanent]"]');
+      const preview = document.getElementById('ban-preview');
+      if (!preview) return;
+      const ip = form.querySelector('#banned_ip_ip_address');
+      const reason = form.querySelector('#banned_ip_reason');
+      preview.hidden = !(ip.value || reason.value);
+      document.getElementById('preview-ip').textContent = ip.value || '-';
+      document.getElementById('preview-reason').textContent = reason.selectedOptions[0]?.textContent || '-';
+      const duration = form.querySelector('[name="duration"]:checked');
+      document.getElementById('preview-duration').textContent = permanent ? 'Permanent' :
+        (expiry.value ? `${expiry.value.replace('T', ' ')} UTC` : (duration?.parentElement.textContent.trim() || '24 hours (server default)'));
+      const status = document.getElementById('preview-status');
+      status.textContent = permanent ? 'Permanent' : 'Temporary';
+      status.className = permanent ? 'badge badge-critical' : 'badge badge-danger';
+    }
+
+    function updateSelection(form) {
+      const boxes = Array.from(form.querySelectorAll('.ban-checkbox'));
+      const count = boxes.filter(box => box.checked).length;
+      form.querySelector('#selected-count').textContent = count;
+      form.querySelector('#bulk-actions-bar').hidden = count === 0;
+      const all = form.querySelector('#select-all');
+      all.checked = boxes.length > 0 && count === boxes.length;
+      all.indeterminate = count > 0 && count < boxes.length;
+    }
+
+    function initialize() {
+      if (!document.querySelector('[data-beskar-dashboard]')) return;
+      document.querySelectorAll('[data-beskar-ban-form]').forEach(updateBanForm);
+      document.querySelectorAll('#bulk-actions-form').forEach(updateSelection);
+    }
+
+    document.addEventListener('change', event => {
+      if (!event.target.closest('[data-beskar-dashboard]')) return;
+      if (event.target.matches('[data-beskar-auto-submit]')) event.target.form.requestSubmit();
+      const form = event.target.closest('[data-beskar-ban-form]');
+      if (form) {
+        const expiry = form.querySelector('#banned_ip_expires_at');
+        if (event.target.name === 'duration') expiry.value = '';
+        if (event.target.name === 'banned_ip[permanent]' && !isPermanent(form) && !expiry.value) {
+          expiry.value = new Date(Date.now() + 86400000).toISOString().slice(0, -1);
+        }
+        updateBanForm(form);
+      }
+      const bulk = event.target.closest('#bulk-actions-form');
+      if (bulk) {
+        if (event.target.id === 'select-all') {
+          bulk.querySelectorAll('.ban-checkbox').forEach(box => { box.checked = event.target.checked; });
+        }
+        updateSelection(bulk);
+      }
+    });
+
+    document.addEventListener('input', event => {
+      const form = event.target.closest('[data-beskar-ban-form]');
+      if (!form) return;
+      if (event.target.id === 'banned_ip_expires_at' && event.target.value) {
+        form.querySelectorAll('[name="duration"]').forEach(input => { input.checked = false; });
+      }
+      updateBanForm(form);
+    });
+
+    document.addEventListener('click', event => {
+      if (!event.target.closest('[data-beskar-dashboard]')) return;
+      const clear = event.target.closest('[data-beskar-clear-selection]');
+      if (clear) {
+        const form = clear.closest('form');
+        form.querySelectorAll('.ban-checkbox').forEach(box => { box.checked = false; });
+        updateSelection(form);
+      }
+      const extend = event.target.closest('[data-beskar-extend-hours]');
+      if (extend) {
+        const form = extend.closest('form');
+        const expiry = form.querySelector('#banned_ip_expires_at');
+        // The displayed wall-clock value is UTC, never browser-local time.
+        const base = expiry.value ? Date.parse(`${expiry.value}Z`) : Date.now();
+        if (Number.isFinite(base)) {
+          expiry.value = new Date(Math.max(base, Date.now()) + Number(extend.dataset.beskarExtendHours) * 3600000).toISOString().slice(0, -1);
+          updateBanForm(form);
+        }
+      }
+      const permanent = event.target.closest('[data-beskar-make-permanent]');
+      if (permanent) {
+        const form = permanent.closest('form');
+        form.querySelector('[name="banned_ip[permanent]"][value="true"]').checked = true;
+        updateBanForm(form);
+      }
+    });
+
+    document.addEventListener('submit', event => {
+      if (!event.target.closest('[data-beskar-dashboard]')) return;
+      const message = event.submitter?.dataset.beskarConfirm;
+      if (message && !window.confirm(message)) event.preventDefault();
+      // Do not synthesize forms, bypass validation, or convert duration presets
+      // to client-clock timestamps. Rails forms carry CSRF and method fields.
+    });
+
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', initialize, { once: true });
+    else initialize();
+    document.addEventListener('pageshow', initialize);
+    document.addEventListener('turbo:load', initialize);
+  })();
+<% end %>

data/app/views/layouts/beskar/application.html.erb

@@ -8,7 +8,7 @@
   <%= csp_meta_tag %>
 
   <!-- Embedded Styles (No external dependencies) -->
-  <style>
+  <style nonce="<%= content_security_policy_nonce %>">
     :root {
       --primary: #635BFF;
       --primary-dark: #5243CC;
@@ -384,6 +384,7 @@
     input[type="password"],
     input[type="number"],
     input[type="date"],
+    input[type="datetime-local"],
     select,
     textarea {
       width: 100%;
@@ -492,7 +493,7 @@
 
   <%= yield :head %>
 </head>
-<body>
+<body data-beskar-dashboard data-turbo="false">
   <div class="dashboard-container">
     <!-- Sidebar -->
     <aside class="sidebar">
@@ -531,6 +532,11 @@
           <% end %>
         </div>
 
+        <div class="nav-section">
+          <%= link_to "Administrative Actions", administrative_actions_path,
+              class: "nav-link #{controller_name == 'administrative_actions' ? 'active' : ''}" %>
+        </div>
+
         <div class="nav-section">
           <div class="nav-section-title">Configuration</div>
           <% if Beskar.configuration.monitor_only? %>
@@ -581,79 +587,6 @@
     </main>
   </div>
 
-  <%= javascript_tag nonce: true do %>
-    // Add active state to current nav link
-    document.addEventListener('DOMContentLoaded', function() {
-      // Handle nav link clicks
-      document.querySelectorAll('.nav-link').forEach(link => {
-        if (link.href === window.location.href) {
-          link.classList.add('active');
-        }
-      });
-
-      // Auto-dismiss alerts after 5 seconds
-      setTimeout(() => {
-        document.querySelectorAll('.alert').forEach(alert => {
-          alert.style.transition = 'opacity 0.5s';
-          alert.style.opacity = '0';
-          setTimeout(() => alert.remove(), 500);
-        });
-      }, 5000);
-
-      // Handle data-turbo-method links (Rails UJS replacement)
-      document.addEventListener('click', function(e) {
-        const link = e.target.closest('a[data-turbo-method]');
-        if (!link) return;
-
-        e.preventDefault();
-
-        const method = link.dataset.turboMethod || link.dataset['turbo-method'];
-        const confirm = link.dataset.turboConfirm || link.dataset['turbo-confirm'];
-
-        if (confirm && !window.confirm(confirm)) {
-          return;
-        }
-
-        const form = document.createElement('form');
-        form.method = 'POST';
-        form.action = link.href;
-        form.style.display = 'none';
-
-        // Add CSRF token
-        const csrfToken = document.querySelector('meta[name="csrf-token"]').content;
-        const csrfParam = document.querySelector('meta[name="csrf-param"]').content;
-
-        if (csrfToken && csrfParam) {
-          const input = document.createElement('input');
-          input.type = 'hidden';
-          input.name = csrfParam;
-          input.value = csrfToken;
-          form.appendChild(input);
-        }
-
-        // Add method override for DELETE, PUT, PATCH
-        if (method && method.toLowerCase() !== 'post') {
-          const methodInput = document.createElement('input');
-          methodInput.type = 'hidden';
-          methodInput.name = '_method';
-          methodInput.value = method;
-          form.appendChild(methodInput);
-        }
-
-        // Add any URL parameters as form inputs
-        const url = new URL(link.href);
-        url.searchParams.forEach((value, key) => {
-          const input = document.createElement('input');
-          input.type = 'hidden';
-          input.name = key;
-          input.value = value;
-          form.appendChild(input);
-        });
-
-        document.body.appendChild(form);
-        form.submit();
-      });
-    });
-  <% end %>
+  <%= render "layouts/beskar/behavior" %>
 </body>
 </html>

data/config/routes.rb

@@ -1,43 +1,32 @@
 Beskar::Engine.routes.draw do
   # Root route - dashboard
-  root to: 'dashboard#index'
+  root to: "dashboard#index"
 
   # Dashboard
-  get 'dashboard', to: 'dashboard#index', as: :dashboard
+  get "dashboard", to: "dashboard#index", as: :dashboard
 
   # Security Events
   resources :security_events, only: [:index, :show] do
     collection do
-      get 'export'
+      get "export"
     end
   end
 
   # Banned IPs
   resources :banned_ips do
     member do
-      post 'extend'
+      post "extend"
+      get "review"
     end
 
     collection do
-      post 'bulk_action'
-      get 'export'
+      post "bulk_action"
+      get "export"
     end
   end
 
-  # API endpoints (optional, for future AJAX calls)
-  namespace :api do
-    namespace :v1 do
-      resources :security_events, only: [:index, :show] do
-        collection do
-          get 'stats'
-        end
-      end
+  resources :administrative_actions, only: [:index, :show]
 
-      resources :banned_ips, only: [:index, :show, :create, :destroy] do
-        member do
-          post 'extend'
-        end
-      end
-    end
-  end
+  # No versioned JSON API is implemented. Authenticated CSV/JSON exports live
+  # on the resources above; do not expose routes to nonexistent controllers.
 end

data/db/migrate/20251016000001_create_beskar_security_events.rb

@@ -8,7 +8,7 @@ class CreateBeskarSecurityEvents < ActiveRecord::Migration[8.0]
       t.string :ip_address
       t.string :attempted_email
       t.text :user_agent
-      t.json :metadata, default: {}
+      t.json :metadata, default: -> { "('{}')" }
       t.integer :risk_score
 
       t.timestamps
@@ -19,7 +19,7 @@ class CreateBeskarSecurityEvents < ActiveRecord::Migration[8.0]
     add_index :beskar_security_events, :attempted_email
     add_index :beskar_security_events, :created_at
     add_index :beskar_security_events, :risk_score
-    add_index :beskar_security_events, [:ip_address, :event_type, :created_at], 
-              name: 'index_security_events_on_ip_event_time'
+    add_index :beskar_security_events, [:ip_address, :event_type, :created_at],
+      name: "index_security_events_on_ip_event_time"
   end
 end

data/db/migrate/20260910000001_create_beskar_security_states.rb

@@ -0,0 +1,14 @@
+class CreateBeskarSecurityStates < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_security_states do |t|
+      t.string :key, null: false
+      t.json :data, null: false, default: -> { "('{}')" }
+      t.datetime :expires_at
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+    end
+    add_index :beskar_security_states, :key, unique: true
+    add_index :beskar_security_states, :expires_at
+    add_index :beskar_security_events, [:user_type, :user_id, :event_type, :created_at], name: "index_beskar_events_on_user_event_time"
+  end
+end

data/db/migrate/20260911000001_create_beskar_administrative_actions.rb

@@ -0,0 +1,22 @@
+class CreateBeskarAdministrativeActions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_administrative_actions do |t|
+      t.string :actor, null: false, limit: 200
+      t.string :action, null: false
+      t.bigint :target_id, null: false
+      t.string :operation_id, null: false, limit: 36
+      t.string :request_id, null: false, limit: 200
+      t.text :reason, null: false
+      # MySQL requires JSON defaults to be expressions, even for literals.
+      t.json :before_state, null: false, default: -> { "('{}')" }
+      t.json :after_state, null: false, default: -> { "('{}')" }
+      t.datetime :created_at, null: false
+    end
+    # No user/ban foreign key or cascading association: the action must survive
+    # deletion of its live target. Retention is a separate, explicit operation.
+    add_index :beskar_administrative_actions, [:operation_id, :target_id], unique: true,
+      name: "index_beskar_actions_on_operation_target"
+    add_index :beskar_administrative_actions, [:target_id, :id]
+    add_index :beskar_administrative_actions, :created_at
+  end
+end

data/db/migrate/20260911000002_expand_administrative_action_targets.rb

@@ -0,0 +1,6 @@
+class ExpandAdministrativeActionTargets < ActiveRecord::Migration[8.0]
+  def change
+    add_column :beskar_administrative_actions, :target_type, :string, null: false, default: "BannedIp"
+    change_column_null :beskar_administrative_actions, :target_id, true
+  end
+end

data/docs/README.md

@@ -0,0 +1,73 @@
+# Beskar documentation
+
+Start with the current guides and operational contracts below. The original
+review and archived overview describe earlier code; they are not current setup
+instructions. [Repair status](audits/repair-status.md) distinguishes verified
+changes from open findings and production validation still required.
+
+## Start here
+
+- **Installing or integrating:** follow the [project README](../README.md#installation),
+  then read [configuration](guides/configuration.md),
+  [authentication](guides/authentication.md), and [state storage](operations/state-storage.md).
+- **Upgrading an existing installation:** use the
+  [security hardening and rollout checklist](operations/security-hardening.md#rollout).
+- **Working on repairs:** consult [repair status](audits/repair-status.md) and the
+  [original findings](audits/project-review.md) before selecting work.
+
+## Guides
+
+- [Configuration](guides/configuration.md) — validation, supported capabilities,
+  defaults, and audited runtime changes.
+- [Authentication](guides/authentication.md) — Devise/Warden admission, native
+  session integration, account locks, and revocation boundaries.
+- [Risk scoring](guides/risk-scoring.md) — factors, geographic evidence, and
+  heuristic limitations.
+- [Audit data and WAF](guides/audit-and-waf.md) — filtering, exports, scanner
+  matching, and privacy boundaries.
+- [Audit lifecycle](guides/audit-lifecycle.md) — unchanged event retention,
+  administrative permissions, actor/reason history, and migrations.
+- [Dashboard and search](guides/dashboard-and-search.md) — reporting, search,
+  routes, forms, timezones, and browser/CSP behavior.
+- [Notifications and recovery](guides/notifications-and-recovery.md) — opt-in
+  delivery jobs and host-owned recovery flows.
+
+## Operations
+
+- [State storage](operations/state-storage.md) — database authority, cache
+  independence, concurrency, rate limits, cleanup, and rollout.
+- [Monitor-only mode](operations/monitor-only-mode.md) — observation behavior and
+  the transition to enforcement.
+- [Security hardening](operations/security-hardening.md) — authentication
+  coverage, deployment requirements, availability tradeoffs, and validation gates.
+
+## Audits and repair tracking
+
+- [Repair status](audits/repair-status.md) — completed batches, test evidence,
+  unresolved findings, and next verification gates.
+- [Original project review](audits/project-review.md) — the September 2026
+  diagnostic baseline and F01–F26 findings; preserved as historical evidence.
+
+## Research and historical reference
+
+- [Rust performance assessment](research/rust-performance-assessment.md) — a
+  measured investigation and proposal, not an implemented feature or performance
+  guarantee.
+- [Archived project overview](archive/project-documentation.md) — the
+  pre-remediation architecture and examples; do not use it as current guidance.
+- [Changelog](../CHANGELOG.md) — historical release notes.
+
+## Maintaining these docs
+
+Keep `README.md` and `CHANGELOG.md` at the repository root. Put current feature
+guides in `guides/`, deployment/runtime contracts in `operations/`, findings and
+progress in `audits/`, proposals in `research/`, and superseded references in
+`archive/`. Use lowercase, hyphenated filenames and relative Markdown links.
+Source paths mentioned in prose are relative to the repository root.
+
+Add new documents to this index. The gem includes `docs/**/*.md`; link/index and
+packaging regressions run with:
+
+```sh
+mise exec -- env PARALLEL_WORKERS=1 bin/rails test test/documentation_test.rb
+```