From f939369d032fe6032b312d7e9a67a96f6a73d43f Mon Sep 17 00:00:00 2001
From: athulrajtflycatchtech <athulraj.t@flycatchtech.com>
Date: Mon, 17 Aug 2026 15:02:50 +0530
Subject: [PATCH 1/2] feat(admin-roles): implement role management features
 including role creation, editing, and deletion; enhance UI components for
 roles list and role form; update API endpoints for role operations

---
 .../scripts/check-contract-drift.mjs          |   1 +
 apps/Administration-FE/scripts/check-i18n.mjs |   2 +
 .../scripts/generate-client.mjs               |   1 +
 .../src/components/AdminShell.tsx             | 113 ++++++-
 .../src/components/RoleForm.tsx               | 197 +++++++++++
 .../src/components/RolesList.tsx              | 192 +++++++++++
 apps/Administration-FE/src/i18n/en.json       |  38 ++-
 apps/Administration-FE/src/lib/admin-api.ts   |  45 +++
 apps/Administration-FE/src/lib/i18n.ts        |   6 +
 apps/Administration-FE/src/styles/admin.css   | 241 +++++++++++++
 apps/Administration-FE/src/styles/tokens.css  |   2 +
 .../tests/e2e/admin-roles.spec.ts             |  19 ++
 .../003_role_description_permissions.py       |  59 ++++
 .../src/flycatch_api/api/admin_roles.py       |  67 ++++
 apps/Backend/src/flycatch_api/main.py         |   3 +-
 apps/Backend/src/flycatch_api/models/role.py  |   7 +-
 .../flycatch_api/models/role_permission.py    |  12 +-
 .../src/flycatch_api/schemas/__init__.py      |  16 +
 .../src/flycatch_api/schemas/admin_roles.py   |  71 ++++
 .../src/flycatch_api/security/dependencies.py |   1 +
 .../services/bootstrap_service.py             |  27 +-
 .../src/flycatch_api/services/rbac_service.py |   4 +
 .../src/flycatch_api/services/role_service.py | 276 +++++++++++++++
 .../tests/contract/test_openapi_parity.py     |   1 +
 .../tests/integration/test_admin_auth.py      |   1 +
 .../tests/integration/test_admin_roles.py     | 189 +++++++++++
 .../tests/integration/test_bootstrap.py       |  21 +-
 specs/002-auth-rbac/contracts/README.md       |   4 +-
 .../contracts/admin-rbac.v1.yaml              |   4 +-
 .../contracts/admin-roles.v1.yaml             | 318 ++++++++++++++++++
 30 files changed, 1881 insertions(+), 57 deletions(-)
 create mode 100644 apps/Administration-FE/src/components/RoleForm.tsx
 create mode 100644 apps/Administration-FE/src/components/RolesList.tsx
 create mode 100644 apps/Administration-FE/tests/e2e/admin-roles.spec.ts
 create mode 100644 apps/Backend/alembic/versions/003_role_description_permissions.py
 create mode 100644 apps/Backend/src/flycatch_api/api/admin_roles.py
 create mode 100644 apps/Backend/src/flycatch_api/schemas/admin_roles.py
 create mode 100644 apps/Backend/src/flycatch_api/services/role_service.py
 create mode 100644 apps/Backend/tests/integration/test_admin_roles.py
 create mode 100644 specs/002-auth-rbac/contracts/admin-roles.v1.yaml

diff --git a/apps/Administration-FE/scripts/check-contract-drift.mjs b/apps/Administration-FE/scripts/check-contract-drift.mjs
index 1fcf934..92e9b2d 100644
--- a/apps/Administration-FE/scripts/check-contract-drift.mjs
+++ b/apps/Administration-FE/scripts/check-contract-drift.mjs
@@ -9,6 +9,7 @@ const required = [
   'admin-auth.v2.ts',
   'admin-rbac.v1.ts',
   'admin-management.v2.ts',
+  'admin-roles.v1.ts',
   'publish.v2.ts',
 ];
 
diff --git a/apps/Administration-FE/scripts/check-i18n.mjs b/apps/Administration-FE/scripts/check-i18n.mjs
index 055ca56..14b4cf4 100644
--- a/apps/Administration-FE/scripts/check-i18n.mjs
+++ b/apps/Administration-FE/scripts/check-i18n.mjs
@@ -8,6 +8,8 @@ const files = [
   'components/SignInForm.tsx',
   'components/AdminShell.tsx',
   'components/PageEditor.tsx',
+  'components/RolesList.tsx',
+  'components/RoleForm.tsx',
 ];
 const allowedLiteral = new Set(['Title', 'Description', 'Primary heading', 'Summary', 'Body']);
 
diff --git a/apps/Administration-FE/scripts/generate-client.mjs b/apps/Administration-FE/scripts/generate-client.mjs
index 438ad66..26fecd7 100644
--- a/apps/Administration-FE/scripts/generate-client.mjs
+++ b/apps/Administration-FE/scripts/generate-client.mjs
@@ -14,6 +14,7 @@ const contracts = [
   'admin-auth.v2.yaml',
   'admin-rbac.v1.yaml',
   'admin-management.v2.yaml',
+  'admin-roles.v1.yaml',
   'publish.v2.yaml',
 ];
 
diff --git a/apps/Administration-FE/src/components/AdminShell.tsx b/apps/Administration-FE/src/components/AdminShell.tsx
index 4ecb036..d3788bb 100644
--- a/apps/Administration-FE/src/components/AdminShell.tsx
+++ b/apps/Administration-FE/src/components/AdminShell.tsx
@@ -13,13 +13,22 @@ import {
 import { hasTokens } from '../lib/token-store';
 import { t } from '../lib/i18n';
 import PageEditor from './PageEditor';
+import RoleForm from './RoleForm';
+import RolesList from './RolesList';
 import SignInForm from './SignInForm';
 import SiteSettingsEditor from './SiteSettingsEditor';
 
-type View = 'site_settings' | 'home';
+type View = 'site_settings' | 'home' | 'roles' | 'role_form';
+
+function canManageRolesFrom(session: SessionContext | null): boolean {
+  return (
+    hasPermission(session, 'roles.manage') || Boolean(session?.roles?.includes('administrator'))
+  );
+}
 
 export default function AdminShell() {
   const [view, setView] = useState<View>('site_settings');
+  const [editingRoleId, setEditingRoleId] = useState<string | null>(null);
   const [session, setSession] = useState<SessionContext | null>(null);
   const [siteSettings, setSiteSettings] = useState<Record<string, unknown> | null>(null);
   const [homePage, setHomePage] = useState<Record<string, unknown> | null>(null);
@@ -41,6 +50,9 @@ export default function AdminShell() {
       setSiteSettings(null);
       setHomePage(null);
       setWorkspaceError(t('admin.workspace.load_failed'));
+      if (canManageRolesFrom(nextSession)) {
+        setView('roles');
+      }
     } finally {
       setReady(true);
     }
@@ -57,6 +69,26 @@ export default function AdminShell() {
     });
   }, [loadWorkspace]);
 
+  useEffect(() => {
+    if (!session) {
+      document.title = t('admin.sign_in.title');
+      return;
+    }
+    if (view === 'home') {
+      document.title = t('admin.workspace.home_page');
+      return;
+    }
+    if (view === 'roles') {
+      document.title = t('admin.workspace.settings');
+      return;
+    }
+    if (view === 'role_form') {
+      document.title = editingRoleId ? t('admin.roles.edit') : t('admin.roles.add');
+      return;
+    }
+    document.title = t('admin.workspace.site_settings');
+  }, [session, view, editingRoleId]);
+
   async function refreshData() {
     const settings = await getSiteSettingsRecord();
     setSiteSettings(settings as Record<string, unknown>);
@@ -82,6 +114,14 @@ export default function AdminShell() {
     setMessage(null);
     setError(null);
     setWorkspaceError(null);
+    setView('site_settings');
+    setEditingRoleId(null);
+  }
+
+  function openRoles() {
+    setView('roles');
+    setEditingRoleId(null);
+    setError(null);
   }
 
   if (!ready) {
@@ -100,24 +140,28 @@ export default function AdminShell() {
     );
   }
 
-  if (!siteSettings || !homePage) {
-    return (
-      <main id="main" className="container">
-        <p role="alert">{workspaceError || t('admin.workspace.load_failed')}</p>
-        <button type="button" onClick={handleSignOut}>
-          {t('admin.sign_out')}
-        </button>
-      </main>
-    );
-  }
-
   const canDraft = hasPermission(session, 'drafts.save');
   const canPublish = hasPermission(session, 'records.publish');
+  const canManageRoles = canManageRolesFrom(session);
+  const settingsCurrent = view === 'roles' || view === 'role_form';
+
+  if (!siteSettings || !homePage) {
+    if (!canManageRoles) {
+      return (
+        <main id="main" className="container">
+          <p role="alert">{workspaceError || t('admin.workspace.load_failed')}</p>
+          <button type="button" onClick={handleSignOut}>
+            {t('admin.sign_out')}
+          </button>
+        </main>
+      );
+    }
+  }
 
   return (
     <div>
       <header className="admin-header">
-        <div className="container">
+        <div className="container admin-header-inner">
           <h1>{t('admin.workspace.title')}</h1>
           <p>{session.email}</p>
           <button type="button" onClick={handleSignOut}>
@@ -148,16 +192,28 @@ export default function AdminShell() {
                 {t('admin.workspace.home_page')}
               </button>
             </li>
+            {canManageRoles && (
+              <li>
+                <button
+                  type="button"
+                  className={settingsCurrent ? 'active' : ''}
+                  aria-current={settingsCurrent ? 'page' : undefined}
+                  onClick={openRoles}
+                >
+                  {t('admin.workspace.settings')}
+                </button>
+              </li>
+            )}
           </ul>
         </nav>
         <main id="main" className="admin-main">
-          {message && <p role="status">{message}</p>}
+          {message && view !== 'roles' && view !== 'role_form' && <p role="status">{message}</p>}
           {error && (
             <p className="error" role="alert">
               {error}
             </p>
           )}
-          {view === 'site_settings' && (
+          {view === 'site_settings' && siteSettings && (
             <SiteSettingsEditor
               record={siteSettings}
               canDraft={canDraft}
@@ -178,7 +234,7 @@ export default function AdminShell() {
               }}
             />
           )}
-          {view === 'home' && (
+          {view === 'home' && homePage && (
             <PageEditor
               record={homePage}
               canDraft={canDraft}
@@ -199,6 +255,31 @@ export default function AdminShell() {
               }}
             />
           )}
+          {view === 'roles' && (
+            <RolesList
+              notice={message}
+              onAdd={() => {
+                setEditingRoleId(null);
+                setMessage(null);
+                setView('role_form');
+              }}
+              onEdit={(id) => {
+                setEditingRoleId(id);
+                setMessage(null);
+                setView('role_form');
+              }}
+            />
+          )}
+          {view === 'role_form' && (
+            <RoleForm
+              roleId={editingRoleId}
+              onCancel={openRoles}
+              onSaved={() => {
+                setMessage(t('admin.roles.saved'));
+                openRoles();
+              }}
+            />
+          )}
         </main>
       </div>
     </div>
diff --git a/apps/Administration-FE/src/components/RoleForm.tsx b/apps/Administration-FE/src/components/RoleForm.tsx
new file mode 100644
index 0000000..7ea1192
--- /dev/null
+++ b/apps/Administration-FE/src/components/RoleForm.tsx
@@ -0,0 +1,197 @@
+import { useEffect, useState, type FormEvent } from 'react';
+import {
+  AdminApiError,
+  createRole,
+  getRole,
+  getRoleCatalogue,
+  updateRole,
+  type RoleCatalogue,
+  type RoleWrite,
+} from '../lib/admin-api';
+import { resourceLabel, t } from '../lib/i18n';
+
+interface Props {
+  roleId: string | null;
+  onCancel: () => void;
+  onSaved: () => void;
+}
+
+function permissionKey(resourceId: string, action: string): string {
+  return `${resourceId}.${action}`;
+}
+
+export default function RoleForm({ roleId, onCancel, onSaved }: Props) {
+  const [catalogue, setCatalogue] = useState<RoleCatalogue | null>(null);
+  const [name, setName] = useState('');
+  const [description, setDescription] = useState('');
+  const [grants, setGrants] = useState<Set<string>>(new Set());
+  const [isSystem, setIsSystem] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fieldError, setFieldError] = useState<string | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    async function load() {
+      const nextCatalogue = await getRoleCatalogue();
+      setCatalogue(nextCatalogue);
+      if (roleId) {
+        const role = await getRole(roleId);
+        setName(role.name);
+        setDescription(role.description || '');
+        setGrants(new Set(role.permissions));
+        setIsSystem(role.is_system);
+      } else {
+        setName('');
+        setDescription('');
+        setGrants(new Set());
+        setIsSystem(false);
+      }
+      setReady(true);
+    }
+    load().catch(() => {
+      setError(t('admin.workspace.load_failed'));
+      setReady(true);
+    });
+  }, [roleId]);
+
+  function toggle(resourceId: string, action: string) {
+    const key = permissionKey(resourceId, action);
+    setGrants((current) => {
+      const next = new Set(current);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }
+
+  async function save(event: FormEvent) {
+    event.preventDefault();
+    setError(null);
+    setFieldError(null);
+    if (!name.trim()) {
+      setFieldError(t('admin.field.required'));
+      return;
+    }
+    const allowed = new Set(
+      (catalogue?.resources || []).flatMap((resource) =>
+        (catalogue?.actions || []).map((action) => permissionKey(resource.id, action)),
+      ),
+    );
+    const payload: RoleWrite = {
+      name: name.trim(),
+      description: description.trim() || null,
+      permissions: [...grants].filter((item) => allowed.has(item)),
+    };
+    try {
+      if (roleId) await updateRole(roleId, payload);
+      else await createRole(payload);
+      onSaved();
+    } catch (caught) {
+      if (caught instanceof AdminApiError) {
+        const detail = caught.detail as {
+          message_key?: string;
+          fields?: Record<string, { message_key: string }>;
+        };
+        const nameKey = detail.fields?.name?.message_key;
+        const permissionKeyMessage = detail.fields?.permissions?.message_key;
+        setError(t(nameKey || permissionKeyMessage || detail.message_key || 'admin.action.forbidden'));
+        return;
+      }
+      setError(t('admin.action.forbidden'));
+    }
+  }
+
+  if (!ready) {
+    return <p>{t('admin.roles.title')}</p>;
+  }
+
+  return (
+    <section className="role-form-page">
+      <h2>{roleId ? t('admin.roles.edit') : t('admin.roles.add')}</h2>
+      <form onSubmit={save}>
+        <label>
+          {t('admin.roles.name')}
+          <input
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            required
+            maxLength={64}
+            disabled={isSystem}
+            autoComplete="off"
+          />
+        </label>
+        {isSystem && <p className="hint">{t('admin.roles.system_protected')}</p>}
+        <label>
+          {t('admin.roles.description')}
+          <textarea
+            value={description}
+            onChange={(event) => setDescription(event.target.value)}
+            maxLength={500}
+            rows={3}
+          />
+        </label>
+        {fieldError && (
+          <p className="error" role="alert">
+            {fieldError}
+          </p>
+        )}
+        {error && (
+          <p className="error" role="alert">
+            {error}
+          </p>
+        )}
+        <fieldset className="permission-matrix">
+          <legend>{t('admin.roles.permissions')}</legend>
+          <div className="permission-table-wrap">
+            <table className="permission-table">
+              <thead>
+                <tr>
+                  <th scope="col">{t('admin.roles.name')}</th>
+                  {(catalogue?.actions || []).map((action) => (
+                    <th key={action} scope="col">
+                      {t(`admin.roles.action.${action}`)}
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {(catalogue?.resources || []).map((resource) => (
+                  <tr key={resource.id}>
+                    <th scope="row">{resourceLabel(resource.id)}</th>
+                    {(catalogue?.actions || []).map((action) => {
+                      const key = permissionKey(resource.id, action);
+                      const inputId = `perm-${resource.id}-${action}`;
+                      return (
+                        <td key={action} data-label={t(`admin.roles.action.${action}`)}>
+                          <label className="permission-check" htmlFor={inputId}>
+                            <input
+                              id={inputId}
+                              type="checkbox"
+                              checked={grants.has(key)}
+                              onChange={() => toggle(resource.id, action)}
+                            />
+                            <span className="permission-check-label">
+                              {t(`admin.roles.action.${action}`)}
+                            </span>
+                          </label>
+                        </td>
+                      );
+                    })}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </fieldset>
+        <div className="actions">
+          <button type="button" onClick={onCancel}>
+            {t('admin.roles.cancel')}
+          </button>
+          <button type="submit" className="primary">
+            {t('admin.roles.save')}
+          </button>
+        </div>
+      </form>
+    </section>
+  );
+}
diff --git a/apps/Administration-FE/src/components/RolesList.tsx b/apps/Administration-FE/src/components/RolesList.tsx
new file mode 100644
index 0000000..b79b5e8
--- /dev/null
+++ b/apps/Administration-FE/src/components/RolesList.tsx
@@ -0,0 +1,192 @@
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+import {
+  AdminApiError,
+  deleteRole,
+  listRoles,
+  type RoleList,
+} from '../lib/admin-api';
+import { t } from '../lib/i18n';
+
+interface Props {
+  onAdd: () => void;
+  onEdit: (id: string) => void;
+  notice: string | null;
+}
+
+export default function RolesList({ onAdd, onEdit, notice }: Props) {
+  const [query, setQuery] = useState('');
+  const [appliedQuery, setAppliedQuery] = useState('');
+  const [page, setPage] = useState(1);
+  const [data, setData] = useState<RoleList | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [pendingId, setPendingId] = useState<string | null>(null);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  async function load(nextQuery: string, nextPage: number) {
+    setError(null);
+    try {
+      const result = await listRoles(nextQuery, nextPage);
+      setData(result);
+    } catch {
+      setError(t('admin.workspace.load_failed'));
+    }
+  }
+
+  useEffect(() => {
+    load(appliedQuery, page).catch(() => undefined);
+  }, [appliedQuery, page]);
+
+  function search(event: FormEvent) {
+    event.preventDefault();
+    setPage(1);
+    setAppliedQuery(query.trim());
+  }
+
+  function openDelete(id: string) {
+    setPendingId(id);
+    dialogRef.current?.showModal();
+  }
+
+  function closeDelete() {
+    setPendingId(null);
+    dialogRef.current?.close();
+  }
+
+  async function confirmDelete() {
+    if (!pendingId) return;
+    try {
+      await deleteRole(pendingId);
+      closeDelete();
+      await load(appliedQuery, page);
+    } catch (caught) {
+      closeDelete();
+      if (caught instanceof AdminApiError) {
+        const detail = caught.detail as { message_key?: string };
+        setError(t(detail.message_key || 'admin.action.forbidden'));
+        return;
+      }
+      setError(t('admin.action.forbidden'));
+    }
+  }
+
+  const totalPages = data ? Math.max(1, Math.ceil(data.total / data.per_page)) : 1;
+
+  return (
+    <section className="roles-page">
+      <div className="roles-toolbar">
+        <h2>{t('admin.roles.title')}</h2>
+        <button type="button" className="primary" onClick={onAdd}>
+          {t('admin.roles.add')}
+        </button>
+      </div>
+      {notice && (
+        <p role="status" className="roles-notice">
+          {notice}
+        </p>
+      )}
+      <form className="roles-search" onSubmit={search} role="search">
+        <label>
+          {t('admin.roles.search')}
+          <input
+            type="search"
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            autoComplete="off"
+          />
+        </label>
+        <button type="submit">{t('admin.roles.search.submit')}</button>
+      </form>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+      <div className="roles-table-wrap">
+        <table className="roles-table">
+          <thead>
+            <tr>
+              <th scope="col">{t('admin.roles.name')}</th>
+              <th scope="col">{t('admin.roles.description')}</th>
+              <th scope="col">{t('admin.roles.users')}</th>
+              <th scope="col">{t('admin.roles.actions')}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {data?.items.map((role) => (
+              <tr key={role.id}>
+                <td data-label={t('admin.roles.name')}>{role.name}</td>
+                <td data-label={t('admin.roles.description')}>{role.description || '—'}</td>
+                <td data-label={t('admin.roles.users')}>{role.user_count}</td>
+                <td data-label={t('admin.roles.actions')} className="roles-row-actions">
+                  <button type="button" onClick={() => onEdit(role.id)}>
+                    {t('admin.roles.edit_action')}
+                  </button>
+                  <button
+                    type="button"
+                    className="danger"
+                    disabled={role.is_system || role.user_count > 0}
+                    aria-disabled={role.is_system || role.user_count > 0}
+                    title={
+                      role.is_system
+                        ? t('admin.roles.system_protected')
+                        : role.user_count > 0
+                          ? t('admin.roles.in_use')
+                          : undefined
+                    }
+                    onClick={() => openDelete(role.id)}
+                  >
+                    {t('admin.roles.delete_action')}
+                  </button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+        {data && data.items.length === 0 && (
+          <p className="roles-empty">{t('admin.roles.empty')}</p>
+        )}
+      </div>
+      {data && data.total > data.per_page && (
+        <nav className="roles-pagination" aria-label={t('admin.roles.title')}>
+          <button
+            type="button"
+            disabled={page <= 1}
+            onClick={() => setPage((current) => Math.max(1, current - 1))}
+          >
+            {t('admin.roles.previous')}
+          </button>
+          <p>
+            {t('admin.roles.page')} {data.page} / {totalPages}
+          </p>
+          <button
+            type="button"
+            disabled={page >= totalPages}
+            onClick={() => setPage((current) => current + 1)}
+          >
+            {t('admin.roles.next')}
+          </button>
+        </nav>
+      )}
+      <dialog ref={dialogRef} className="roles-dialog" onClose={() => setPendingId(null)}>
+        <form
+          method="dialog"
+          onSubmit={(event) => {
+            event.preventDefault();
+            confirmDelete().catch(() => undefined);
+          }}
+        >
+          <h3>{t('admin.roles.delete.confirm')}</h3>
+          <p>{t('admin.roles.delete.confirm_body')}</p>
+          <div className="actions">
+            <button type="button" onClick={closeDelete}>
+              {t('admin.roles.delete.cancel')}
+            </button>
+            <button type="submit" className="danger">
+              {t('admin.roles.delete_action')}
+            </button>
+          </div>
+        </form>
+      </dialog>
+    </section>
+  );
+}
diff --git a/apps/Administration-FE/src/i18n/en.json b/apps/Administration-FE/src/i18n/en.json
index 634663a..3ff4cb4 100644
--- a/apps/Administration-FE/src/i18n/en.json
+++ b/apps/Administration-FE/src/i18n/en.json
@@ -11,10 +11,46 @@
   "admin.workspace.title": "Administration",
   "admin.workspace.site_settings": "Site settings",
   "admin.workspace.home_page": "Home page",
+  "admin.workspace.settings": "Settings",
   "admin.save_draft": "Save draft",
   "admin.publish": "Publish",
   "admin.publish.success": "Published. Rebuild the public site to see changes.",
   "admin.field.required": "This field is required.",
   "admin.csrf.failed": "Request could not be verified. Refresh and try again.",
-  "admin.action.forbidden": "You do not have permission for this action."
+  "admin.action.forbidden": "You do not have permission for this action.",
+  "admin.roles.title": "Roles & Permissions",
+  "admin.roles.add": "Add New Role",
+  "admin.roles.edit": "Edit role",
+  "admin.roles.search": "Search roles",
+  "admin.roles.search.submit": "Search",
+  "admin.roles.name": "Role Name",
+  "admin.roles.description": "Description",
+  "admin.roles.users": "Users",
+  "admin.roles.actions": "Actions",
+  "admin.roles.edit_action": "Edit",
+  "admin.roles.delete_action": "Delete",
+  "admin.roles.empty": "No roles match this search.",
+  "admin.roles.previous": "Previous",
+  "admin.roles.next": "Next",
+  "admin.roles.page": "Page",
+  "admin.roles.permissions": "Permissions",
+  "admin.roles.action.create": "Create",
+  "admin.roles.action.read": "Read",
+  "admin.roles.action.update": "Update",
+  "admin.roles.action.delete": "Delete",
+  "admin.roles.action.publish": "Publish",
+  "admin.roles.save": "Save role",
+  "admin.roles.cancel": "Cancel",
+  "admin.roles.delete.confirm": "Delete role",
+  "admin.roles.delete.confirm_body": "This role will be permanently deleted. This cannot be undone.",
+  "admin.roles.delete.cancel": "Cancel",
+  "admin.roles.saved": "Role saved",
+  "admin.roles.deleted": "Role deleted",
+  "admin.roles.system_protected": "Default roles cannot be renamed or deleted.",
+  "admin.roles.in_use": "This role is assigned to users and cannot be deleted.",
+  "admin.roles.not_found": "That role could not be found.",
+  "admin.roles.name.duplicate": "A role with this name already exists.",
+  "admin.roles.permissions.invalid": "One or more permissions are not valid.",
+  "admin.roles.resource.site_settings": "Site settings",
+  "admin.roles.resource.page.home": "Home page"
 }
diff --git a/apps/Administration-FE/src/lib/admin-api.ts b/apps/Administration-FE/src/lib/admin-api.ts
index be7a260..71a1ae3 100644
--- a/apps/Administration-FE/src/lib/admin-api.ts
+++ b/apps/Administration-FE/src/lib/admin-api.ts
@@ -1,5 +1,6 @@
 import type { components as AuthComponents } from '../generated/admin-auth.v2';
 import type { components as RbacComponents } from '../generated/admin-rbac.v1';
+import type { components as RolesComponents } from '../generated/admin-roles.v1';
 import {
   clearTokens,
   getAccessToken,
@@ -14,6 +15,10 @@ export type SessionContext = AuthComponents['schemas']['SessionContext'];
 export type PermissionName = RbacComponents['schemas']['PermissionName'];
 export type AuthError = AuthComponents['schemas']['AuthError'];
 export type PermissionDenied = RbacComponents['schemas']['PermissionDenied'];
+export type RoleList = RolesComponents['schemas']['RoleList'];
+export type RoleDetail = RolesComponents['schemas']['RoleDetail'];
+export type RoleWrite = RolesComponents['schemas']['RoleWrite'];
+export type RoleCatalogue = RolesComponents['schemas']['RoleCatalogue'];
 
 export class AdminApiError extends Error {
   status: number;
@@ -153,3 +158,43 @@ export async function publishRecord(type: string, slug: string) {
 export function hasPermission(session: SessionContext | null, permission: PermissionName): boolean {
   return Boolean(session?.permissions?.includes(permission));
 }
+
+function queryString(params: Record<string, string | number | undefined>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === '') continue;
+    search.set(key, String(value));
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : '';
+}
+
+export async function listRoles(q: string, page: number): Promise<RoleList> {
+  return api<RoleList>(`/admin/roles${queryString({ q: q.trim() || undefined, page, per_page: 5 })}`);
+}
+
+export async function getRoleCatalogue(): Promise<RoleCatalogue> {
+  return api<RoleCatalogue>('/admin/roles/catalogue');
+}
+
+export async function getRole(id: string): Promise<RoleDetail> {
+  return api<RoleDetail>(`/admin/roles/${id}`);
+}
+
+export async function createRole(payload: RoleWrite): Promise<RoleDetail> {
+  return api<RoleDetail>('/admin/roles', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function updateRole(id: string, payload: RoleWrite): Promise<RoleDetail> {
+  return api<RoleDetail>(`/admin/roles/${id}`, {
+    method: 'PATCH',
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function deleteRole(id: string): Promise<void> {
+  await api<void>(`/admin/roles/${id}`, { method: 'DELETE' });
+}
diff --git a/apps/Administration-FE/src/lib/i18n.ts b/apps/Administration-FE/src/lib/i18n.ts
index f84a47e..e06fb8f 100644
--- a/apps/Administration-FE/src/lib/i18n.ts
+++ b/apps/Administration-FE/src/lib/i18n.ts
@@ -3,3 +3,9 @@ import messages from '../i18n/en.json';
 export function t(key: string): string {
   return (messages as Record<string, string>)[key] ?? key;
 }
+
+export function resourceLabel(id: string): string {
+  const key = `admin.roles.resource.${id}`;
+  const value = t(key);
+  return value === key ? id : value;
+}
diff --git a/apps/Administration-FE/src/styles/admin.css b/apps/Administration-FE/src/styles/admin.css
index 0dfb3f0..9e2efd7 100644
--- a/apps/Administration-FE/src/styles/admin.css
+++ b/apps/Administration-FE/src/styles/admin.css
@@ -105,3 +105,244 @@ button.primary {
 .skip-link:focus {
   position: static;
 }
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+.admin-header-inner {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-sm) var(--space-md);
+}
+
+.admin-header-inner h1 {
+  margin: 0;
+  flex: 1 1 auto;
+}
+
+.admin-header-inner p {
+  margin: 0;
+  color: var(--color-muted);
+}
+
+.admin-main h2 {
+  margin-top: 0;
+}
+
+button.danger {
+  color: var(--color-danger);
+  border-color: var(--color-danger);
+  background: var(--color-surface);
+}
+
+button:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.hint {
+  margin: calc(var(--space-sm) * -1) 0 var(--space-md);
+  color: var(--color-muted);
+  font-size: 0.9rem;
+}
+
+.roles-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-md);
+  margin-bottom: var(--space-md);
+}
+
+.roles-toolbar h2 {
+  margin: 0;
+}
+
+.roles-notice {
+  margin: 0 0 var(--space-md);
+}
+
+.roles-search {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: var(--space-sm);
+  margin-bottom: var(--space-lg);
+}
+
+.roles-search label {
+  flex: 1 1 16rem;
+  margin-bottom: 0;
+}
+
+.roles-table-wrap,
+.permission-table-wrap {
+  overflow-x: auto;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+}
+
+.roles-table,
+.permission-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.roles-table th,
+.roles-table td,
+.permission-table th,
+.permission-table td {
+  text-align: left;
+  padding: var(--space-sm) var(--space-md);
+  border-bottom: 1px solid var(--color-border);
+  vertical-align: middle;
+}
+
+.roles-table th,
+.permission-table th {
+  font-weight: 600;
+  background: var(--color-muted-bg);
+}
+
+.roles-row-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs);
+}
+
+.roles-empty {
+  margin: 0;
+  padding: var(--space-md);
+}
+
+.roles-pagination {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-sm);
+  margin-top: var(--space-md);
+}
+
+.roles-pagination p {
+  margin: 0;
+}
+
+.permission-matrix {
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+  padding: var(--space-md);
+  margin: 0 0 var(--space-md);
+}
+
+.permission-matrix legend {
+  padding: 0 var(--space-xs);
+  font-weight: 600;
+}
+
+.permission-check {
+  display: flex;
+  align-items: center;
+  gap: var(--space-xs);
+  margin: 0;
+}
+
+.permission-check input {
+  width: auto;
+}
+
+.permission-check-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+}
+
+.roles-dialog {
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+  padding: var(--space-lg);
+  max-width: 28rem;
+  width: calc(100% - var(--space-lg));
+}
+
+.roles-dialog::backdrop {
+  background: rgb(0 0 0 / 0.4);
+}
+
+.roles-dialog h3 {
+  margin-top: 0;
+}
+
+@media (max-width: 767px) {
+  .roles-table thead,
+  .permission-table thead {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+  }
+
+  .roles-table,
+  .permission-table,
+  .roles-table tbody,
+  .permission-table tbody,
+  .roles-table tr,
+  .permission-table tr,
+  .roles-table td,
+  .permission-table td,
+  .permission-table th {
+    display: block;
+    width: 100%;
+  }
+
+  .roles-table tr,
+  .permission-table tr {
+    padding: var(--space-md);
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .roles-table td,
+  .permission-table td {
+    display: flex;
+    justify-content: space-between;
+    gap: var(--space-sm);
+    border-bottom: 0;
+    padding: var(--space-xs) 0;
+  }
+
+  .roles-table td::before,
+  .permission-table td::before {
+    content: attr(data-label);
+    font-weight: 600;
+  }
+
+  .roles-row-actions {
+    justify-content: flex-end;
+  }
+
+  .permission-table th[scope='row'] {
+    background: transparent;
+    padding: 0 0 var(--space-sm);
+    font-size: 1rem;
+  }
+
+  .permission-check-label {
+    position: static;
+    width: auto;
+    height: auto;
+    overflow: visible;
+    clip: auto;
+  }
+
+  .permission-table td::before {
+    content: none;
+  }
+}
diff --git a/apps/Administration-FE/src/styles/tokens.css b/apps/Administration-FE/src/styles/tokens.css
index ecfcc45..b5d0de7 100644
--- a/apps/Administration-FE/src/styles/tokens.css
+++ b/apps/Administration-FE/src/styles/tokens.css
@@ -7,6 +7,8 @@
   --color-focus: #0066cc;
   --color-border: #dee2e6;
   --color-error: #b00020;
+  --color-danger: #b00020;
+  --color-muted-bg: #eef1f4;
   --font-family-base: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --space-xs: 0.25rem;
   --space-sm: 0.5rem;
diff --git a/apps/Administration-FE/tests/e2e/admin-roles.spec.ts b/apps/Administration-FE/tests/e2e/admin-roles.spec.ts
new file mode 100644
index 0000000..3cf6722
--- /dev/null
+++ b/apps/Administration-FE/tests/e2e/admin-roles.spec.ts
@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+const adminEmail = process.env.E2E_ADMIN_EMAIL;
+const adminPassword = process.env.E2E_ADMIN_PASSWORD;
+
+test.skip(!adminEmail || !adminPassword, 'requires E2E_ADMIN_EMAIL and E2E_ADMIN_PASSWORD');
+
+test('settings opens roles list for an administrator', async ({ page }) => {
+  await page.goto('/');
+  await page.getByLabel(/email/i).fill(adminEmail);
+  await page.getByLabel(/password/i).fill(adminPassword);
+  await page.getByRole('button', { name: /^sign in$/i }).click();
+  await expect(page.getByRole('heading', { name: /administration/i })).toBeVisible();
+
+  await page.getByRole('button', { name: /^settings$/i }).click();
+  await expect(page).toHaveTitle(/settings/i);
+  await expect(page.getByRole('heading', { name: /roles/i })).toBeVisible();
+  await expect(page.getByRole('button', { name: /add new role/i })).toBeVisible();
+});
diff --git a/apps/Backend/alembic/versions/003_role_description_permissions.py b/apps/Backend/alembic/versions/003_role_description_permissions.py
new file mode 100644
index 0000000..9f6d2c2
--- /dev/null
+++ b/apps/Backend/alembic/versions/003_role_description_permissions.py
@@ -0,0 +1,59 @@
+"""Role description and string permissions.
+
+Revision ID: 003
+Revises: 002
+Create Date: 2026-08-17
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "003"
+down_revision: Union[str, None] = "002"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("roles", sa.Column("description", sa.Text(), nullable=True))
+    op.alter_column(
+        "role_permissions",
+        "permission",
+        existing_type=postgresql.ENUM(
+            "records.view",
+            "drafts.save",
+            "records.publish",
+            name="permission_name",
+        ),
+        type_=sa.String(64),
+        existing_nullable=False,
+        postgresql_using="permission::text",
+    )
+    op.execute("DROP TYPE IF EXISTS permission_name")
+
+
+def downgrade() -> None:
+    permission_enum = postgresql.ENUM(
+        "records.view",
+        "drafts.save",
+        "records.publish",
+        name="permission_name",
+        create_type=False,
+    )
+    permission_enum.create(op.get_bind(), checkfirst=True)
+    op.execute(
+        "DELETE FROM role_permissions WHERE permission NOT IN "
+        "('records.view', 'drafts.save', 'records.publish')"
+    )
+    op.alter_column(
+        "role_permissions",
+        "permission",
+        existing_type=sa.String(64),
+        type_=permission_enum,
+        existing_nullable=False,
+        postgresql_using="permission::permission_name",
+    )
+    op.drop_column("roles", "description")
diff --git a/apps/Backend/src/flycatch_api/api/admin_roles.py b/apps/Backend/src/flycatch_api/api/admin_roles.py
new file mode 100644
index 0000000..fb86d52
--- /dev/null
+++ b/apps/Backend/src/flycatch_api/api/admin_roles.py
@@ -0,0 +1,67 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+from flycatch_api.db import get_db
+from flycatch_api.schemas.admin_roles import RoleCatalogue, RoleDetail, RoleList, RoleWrite
+from flycatch_api.security.dependencies import RequireRoles
+from flycatch_api.services.role_service import PER_PAGE, RoleError, RoleService
+
+router = APIRouter(prefix="/admin/roles", tags=["admin-roles"])
+_roles = RoleService()
+
+
+def _raise_role_error(error: RoleError) -> None:
+    raise HTTPException(status_code=error.status_code, detail=error.payload)
+
+
+@router.get("", response_model=RoleList)
+def list_roles(
+    _session: RequireRoles,
+    db: Session = Depends(get_db),
+    q: str | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    per_page: int = Query(default=PER_PAGE, ge=1, le=PER_PAGE),
+):
+    return _roles.list_roles(db, q, page, per_page)
+
+
+@router.get("/catalogue", response_model=RoleCatalogue)
+def get_role_catalogue(_session: RequireRoles, db: Session = Depends(get_db)):
+    return _roles.catalogue(db)
+
+
+@router.post("", response_model=RoleDetail, status_code=status.HTTP_201_CREATED)
+def create_role(payload: RoleWrite, _session: RequireRoles, db: Session = Depends(get_db)):
+    try:
+        return _roles.create(db, payload)
+    except RoleError as error:
+        _raise_role_error(error)
+
+
+@router.get("/{role_id}", response_model=RoleDetail)
+def get_role(role_id: UUID, _session: RequireRoles, db: Session = Depends(get_db)):
+    try:
+        return _roles.get(db, role_id)
+    except RoleError as error:
+        _raise_role_error(error)
+
+
+@router.patch("/{role_id}", response_model=RoleDetail)
+def update_role(
+    role_id: UUID, payload: RoleWrite, _session: RequireRoles, db: Session = Depends(get_db)
+):
+    try:
+        return _roles.update(db, role_id, payload)
+    except RoleError as error:
+        _raise_role_error(error)
+
+
+@router.delete("/{role_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_role(role_id: UUID, _session: RequireRoles, db: Session = Depends(get_db)):
+    try:
+        _roles.delete(db, role_id)
+    except RoleError as error:
+        _raise_role_error(error)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
diff --git a/apps/Backend/src/flycatch_api/main.py b/apps/Backend/src/flycatch_api/main.py
index 91e7c44..f2c70e8 100644
--- a/apps/Backend/src/flycatch_api/main.py
+++ b/apps/Backend/src/flycatch_api/main.py
@@ -2,7 +2,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 
-from flycatch_api.api import admin_auth, admin_management, publish, stubs
+from flycatch_api.api import admin_auth, admin_management, admin_roles, publish, stubs
 
 app = FastAPI(title="Flycatch API", version="2.0.0", docs_url="/api/docs", openapi_url="/openapi.json")
 
@@ -35,6 +35,7 @@ async def security_headers(request: Request, call_next):
 
 app.include_router(admin_auth.router, prefix="/api/v1")
 app.include_router(admin_management.router, prefix="/api/v1")
+app.include_router(admin_roles.router, prefix="/api/v1")
 app.include_router(publish.router, prefix="/api/v1")
 app.include_router(stubs.router, prefix="/api/v1")
 
diff --git a/apps/Backend/src/flycatch_api/models/role.py b/apps/Backend/src/flycatch_api/models/role.py
index ccc6ddb..8d64064 100644
--- a/apps/Backend/src/flycatch_api/models/role.py
+++ b/apps/Backend/src/flycatch_api/models/role.py
@@ -4,7 +4,7 @@
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import DateTime, String
+from sqlalchemy import DateTime, String, Text
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -20,7 +20,10 @@ class Role(Base):
 
     id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     name: Mapped[str] = mapped_column(String(64), unique=True, nullable=False, index=True)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
 
-    permissions: Mapped[list[RolePermission]] = relationship(back_populates="role")
+    permissions: Mapped[list[RolePermission]] = relationship(
+        back_populates="role", cascade="all, delete-orphan"
+    )
     administrator_roles: Mapped[list[AdministratorRole]] = relationship(back_populates="role")
diff --git a/apps/Backend/src/flycatch_api/models/role_permission.py b/apps/Backend/src/flycatch_api/models/role_permission.py
index e341f88..67b7af5 100644
--- a/apps/Backend/src/flycatch_api/models/role_permission.py
+++ b/apps/Backend/src/flycatch_api/models/role_permission.py
@@ -4,7 +4,7 @@
 import uuid
 from typing import TYPE_CHECKING
 
-from sqlalchemy import Enum, ForeignKey
+from sqlalchemy import ForeignKey, String
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -18,6 +18,7 @@ class PermissionName(str, enum.Enum):
     records_view = "records.view"
     drafts_save = "drafts.save"
     records_publish = "records.publish"
+    roles_manage = "roles.manage"
 
 
 class RolePermission(Base):
@@ -26,13 +27,6 @@ class RolePermission(Base):
     role_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), ForeignKey("roles.id"), primary_key=True
     )
-    permission: Mapped[PermissionName] = mapped_column(
-        Enum(
-            PermissionName,
-            name="permission_name",
-            values_callable=lambda members: [member.value for member in members],
-        ),
-        primary_key=True,
-    )
+    permission: Mapped[str] = mapped_column(String(64), primary_key=True)
 
     role: Mapped[Role] = relationship(back_populates="permissions")
diff --git a/apps/Backend/src/flycatch_api/schemas/__init__.py b/apps/Backend/src/flycatch_api/schemas/__init__.py
index 236b0f4..9d6d1c1 100644
--- a/apps/Backend/src/flycatch_api/schemas/__init__.py
+++ b/apps/Backend/src/flycatch_api/schemas/__init__.py
@@ -15,6 +15,15 @@
     TokenPair,
 )
 from flycatch_api.schemas.admin_rbac import PermissionDenied
+from flycatch_api.schemas.admin_roles import (
+    RoleCatalogue,
+    RoleConflict,
+    RoleDetail,
+    RoleList,
+    RoleNotFound,
+    RoleSummary,
+    RoleWrite,
+)
 
 __all__ = [
     "ActionDenied",
@@ -33,6 +42,13 @@
     "PublishResult",
     "PublishedSnapshot",
     "RefreshRequest",
+    "RoleCatalogue",
+    "RoleConflict",
+    "RoleDetail",
+    "RoleList",
+    "RoleNotFound",
+    "RoleSummary",
+    "RoleWrite",
     "SeoMetadata",
     "SessionContext",
     "SessionResponse",
diff --git a/apps/Backend/src/flycatch_api/schemas/admin_roles.py b/apps/Backend/src/flycatch_api/schemas/admin_roles.py
new file mode 100644
index 0000000..27c6619
--- /dev/null
+++ b/apps/Backend/src/flycatch_api/schemas/admin_roles.py
@@ -0,0 +1,71 @@
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RoleResource(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    type: str
+    slug: str
+
+
+class RoleCatalogue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    actions: list[Literal["create", "read", "update", "delete", "publish"]]
+    resources: list[RoleResource]
+
+
+class RoleSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    name: str
+    description: str | None
+    user_count: int = Field(ge=0)
+    is_system: bool
+
+
+class RoleList(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    items: list[RoleSummary]
+    page: int = Field(ge=1)
+    per_page: int = Field(ge=1)
+    total: int = Field(ge=0)
+
+
+class RoleDetail(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    name: str
+    description: str | None
+    permissions: list[str]
+    user_count: int = Field(ge=0)
+    is_system: bool
+
+
+class RoleWrite(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1, max_length=64)
+    description: str | None = Field(default=None, max_length=500)
+    permissions: list[str]
+
+
+class RoleConflict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: Literal["system_role", "role_in_use"]
+    message_key: str
+
+
+class RoleNotFound(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: Literal["not_found"] = "not_found"
+    message_key: Literal["admin.roles.not_found"] = "admin.roles.not_found"
diff --git a/apps/Backend/src/flycatch_api/security/dependencies.py b/apps/Backend/src/flycatch_api/security/dependencies.py
index ab31556..5e2c54f 100644
--- a/apps/Backend/src/flycatch_api/security/dependencies.py
+++ b/apps/Backend/src/flycatch_api/security/dependencies.py
@@ -98,3 +98,4 @@ def _require(
 RequirePublish = Annotated[
     AdminSession, Depends(require_permission(PermissionName.records_publish))
 ]
+RequireRoles = Annotated[AdminSession, Depends(require_permission(PermissionName.roles_manage))]
diff --git a/apps/Backend/src/flycatch_api/services/bootstrap_service.py b/apps/Backend/src/flycatch_api/services/bootstrap_service.py
index e99594b..aab0fbd 100644
--- a/apps/Backend/src/flycatch_api/services/bootstrap_service.py
+++ b/apps/Backend/src/flycatch_api/services/bootstrap_service.py
@@ -8,26 +8,15 @@
 from flycatch_api.models import (
     Administrator,
     AdministratorRole,
-    PermissionName,
     Role,
     RolePermission,
 )
 from flycatch_api.security.password import hash_password
+from flycatch_api.services.role_service import ROLE_DESCRIPTIONS, default_grants
 
 ROLE_ADMINISTRATOR = "administrator"
 ROLE_EDITOR = "editor"
 CATALOGUE_ROLES = (ROLE_ADMINISTRATOR, ROLE_EDITOR)
-CATALOGUE_PERMISSIONS: dict[str, tuple[PermissionName, ...]] = {
-    ROLE_ADMINISTRATOR: (
-        PermissionName.records_view,
-        PermissionName.drafts_save,
-        PermissionName.records_publish,
-    ),
-    ROLE_EDITOR: (
-        PermissionName.records_view,
-        PermissionName.drafts_save,
-    ),
-}
 
 
 class BootstrapError(ValueError):
@@ -103,19 +92,25 @@ def _validate(self, user_1: BootstrapUser, user_2: BootstrapUser) -> None:
 
     def _ensure_catalogue(self, db: Session, result: BootstrapResult) -> None:
         now = datetime.now(UTC)
-        for name, permissions in CATALOGUE_PERMISSIONS.items():
+        for name in CATALOGUE_ROLES:
             role = db.query(Role).filter(Role.name == name).first()
             if role is None:
-                role = Role(name=name, created_at=now)
+                role = Role(
+                    name=name,
+                    description=ROLE_DESCRIPTIONS[name],
+                    created_at=now,
+                )
                 db.add(role)
                 db.flush()
                 result.created_roles.append(name)
+            elif not role.description:
+                role.description = ROLE_DESCRIPTIONS[name]
             existing = {grant.permission for grant in role.permissions}
-            for permission in permissions:
+            for permission in default_grants(name):
                 if permission not in existing:
                     db.add(RolePermission(role_id=role.id, permission=permission))
                     if name not in result.created_roles:
-                        result.created_roles.append(f"{name}:{permission.value}")
+                        result.created_roles.append(f"{name}:{permission}")
 
     def _ensure_user(
         self,
diff --git a/apps/Backend/src/flycatch_api/services/rbac_service.py b/apps/Backend/src/flycatch_api/services/rbac_service.py
index 386f9f2..37b7057 100644
--- a/apps/Backend/src/flycatch_api/services/rbac_service.py
+++ b/apps/Backend/src/flycatch_api/services/rbac_service.py
@@ -6,6 +6,8 @@
 
 from flycatch_api.models import AdministratorRole, PermissionName, Role, RolePermission
 
+ROLE_ADMINISTRATOR = "administrator"
+
 
 class RbacService:
     def role_names(self, db: Session, administrator_id: UUID) -> list[str]:
@@ -29,6 +31,8 @@ def permissions(self, db: Session, administrator_id: UUID) -> list[str]:
             permission.value if isinstance(permission, PermissionName) else str(permission)
             for (permission,) in rows
         }
+        if ROLE_ADMINISTRATOR in self.role_names(db, administrator_id):
+            values.add(PermissionName.roles_manage.value)
         return sorted(values)
 
     def has_permission(
diff --git a/apps/Backend/src/flycatch_api/services/role_service.py b/apps/Backend/src/flycatch_api/services/role_service.py
new file mode 100644
index 0000000..a05dbe7
--- /dev/null
+++ b/apps/Backend/src/flycatch_api/services/role_service.py
@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from flycatch_api.models import AdministratorRole, ManagedRecord, RecordType, Role, RolePermission
+from flycatch_api.models.role_permission import PermissionName
+from flycatch_api.schemas.admin_auth import FieldErrorDetail, FieldErrors
+from flycatch_api.schemas.admin_roles import (
+    RoleCatalogue,
+    RoleConflict,
+    RoleDetail,
+    RoleList,
+    RoleNotFound,
+    RoleResource,
+    RoleSummary,
+    RoleWrite,
+)
+
+ACTIONS: tuple[str, ...] = ("create", "read", "update", "delete", "publish")
+SYSTEM_ROLES = frozenset({"administrator", "editor"})
+ROLE_ADMINISTRATOR = "administrator"
+ROLE_EDITOR = "editor"
+ROLES_MANAGE = PermissionName.roles_manage.value
+DEFAULT_RESOURCES: tuple[RoleResource, ...] = (
+    RoleResource(id="site_settings", type="site_settings", slug="default"),
+    RoleResource(id="page.home", type="page", slug="home"),
+)
+PER_PAGE = 5
+ROLE_DESCRIPTIONS = {
+    ROLE_ADMINISTRATOR: "Full access to administration",
+    ROLE_EDITOR: "Can view and edit drafts",
+}
+
+
+class RoleError(Exception):
+    def __init__(self, status_code: int, payload: dict):
+        self.status_code = status_code
+        self.payload = payload
+        super().__init__(payload.get("message_key", "role_error"))
+
+
+def resource_id_for(record: ManagedRecord) -> str:
+    record_type = record.type.value if isinstance(record.type, RecordType) else str(record.type)
+    if record_type == RecordType.site_settings.value:
+        return "site_settings"
+    return f"{record_type}.{record.slug}"
+
+
+def default_grants(role_name: str) -> list[str]:
+    if role_name == ROLE_ADMINISTRATOR:
+        grants = [f"{resource.id}.{action}" for resource in DEFAULT_RESOURCES for action in ACTIONS]
+        grants.append(ROLES_MANAGE)
+        grants.extend(
+            [
+                PermissionName.records_view.value,
+                PermissionName.drafts_save.value,
+                PermissionName.records_publish.value,
+            ]
+        )
+        return grants
+    grants = [
+        f"{resource.id}.{action}"
+        for resource in DEFAULT_RESOURCES
+        for action in ("read", "update")
+    ]
+    grants.extend([PermissionName.records_view.value, PermissionName.drafts_save.value])
+    return grants
+
+
+def sync_legacy(permissions: set[str]) -> set[str]:
+    synced = set(permissions)
+    if any(item.endswith(".read") for item in synced):
+        synced.add(PermissionName.records_view.value)
+    if any(item.endswith(".update") for item in synced):
+        synced.add(PermissionName.drafts_save.value)
+    if any(item.endswith(".publish") for item in synced):
+        synced.add(PermissionName.records_publish.value)
+    return synced
+
+
+class RoleService:
+    def catalogue(self, db: Session) -> RoleCatalogue:
+        records = db.query(ManagedRecord).order_by(ManagedRecord.type, ManagedRecord.slug).all()
+        resources: list[RoleResource] = []
+        seen: set[str] = set()
+        for record in records:
+            identifier = resource_id_for(record)
+            if identifier in seen:
+                continue
+            seen.add(identifier)
+            record_type = (
+                record.type.value if isinstance(record.type, RecordType) else str(record.type)
+            )
+            resources.append(RoleResource(id=identifier, type=record_type, slug=record.slug))
+        if not resources:
+            resources = list(DEFAULT_RESOURCES)
+        return RoleCatalogue(actions=list(ACTIONS), resources=resources)
+
+    def list_roles(self, db: Session, q: str | None, page: int, per_page: int) -> RoleList:
+        page = max(page, 1)
+        per_page = min(max(per_page, 1), PER_PAGE)
+        query = db.query(Role)
+        if q and q.strip():
+            term = f"%{q.strip()}%"
+            query = query.filter(
+                Role.name.ilike(term) | func.coalesce(Role.description, "").ilike(term)
+            )
+        total = query.count()
+        rows = (
+            query.order_by(Role.name.asc())
+            .offset((page - 1) * per_page)
+            .limit(per_page)
+            .all()
+        )
+        return RoleList(
+            items=[self._summary(db, role) for role in rows],
+            page=page,
+            per_page=per_page,
+            total=total,
+        )
+
+    def get(self, db: Session, role_id: UUID) -> RoleDetail:
+        role = db.get(Role, role_id)
+        if role is None:
+            raise RoleError(404, RoleNotFound().model_dump())
+        return self._detail(db, role)
+
+    def create(self, db: Session, payload: RoleWrite) -> RoleDetail:
+        name = payload.name.strip()
+        self._validate_name(db, name, None)
+        allowed = self._allowed_matrix(db)
+        matrix = self._clean_matrix(payload.permissions, allowed)
+        grants = sync_legacy(matrix)
+        role = Role(
+            name=name,
+            description=self._description(payload.description),
+            created_at=datetime.now(UTC),
+        )
+        db.add(role)
+        db.flush()
+        self._replace_permissions(db, role, grants)
+        db.commit()
+        db.refresh(role)
+        return self._detail(db, role)
+
+    def update(self, db: Session, role_id: UUID, payload: RoleWrite) -> RoleDetail:
+        role = db.get(Role, role_id)
+        if role is None:
+            raise RoleError(404, RoleNotFound().model_dump())
+        name = payload.name.strip()
+        if self._is_system(role) and name.lower() != role.name.lower():
+            raise RoleError(
+                409,
+                RoleConflict(
+                    code="system_role", message_key="admin.roles.system_protected"
+                ).model_dump(),
+            )
+        self._validate_name(db, name, role.id)
+        allowed = self._allowed_matrix(db)
+        matrix = self._clean_matrix(payload.permissions, allowed)
+        grants = sync_legacy(matrix)
+        if self._is_system(role) and role.name == ROLE_ADMINISTRATOR:
+            grants.add(ROLES_MANAGE)
+        if not self._is_system(role):
+            role.name = name
+        role.description = self._description(payload.description)
+        self._replace_permissions(db, role, grants)
+        db.commit()
+        db.refresh(role)
+        return self._detail(db, role)
+
+    def delete(self, db: Session, role_id: UUID) -> None:
+        role = db.get(Role, role_id)
+        if role is None:
+            raise RoleError(404, RoleNotFound().model_dump())
+        if self._is_system(role):
+            raise RoleError(
+                409,
+                RoleConflict(
+                    code="system_role", message_key="admin.roles.system_protected"
+                ).model_dump(),
+            )
+        user_count = self._user_count(db, role.id)
+        if user_count > 0:
+            raise RoleError(
+                409,
+                RoleConflict(code="role_in_use", message_key="admin.roles.in_use").model_dump(),
+            )
+        db.query(RolePermission).filter(RolePermission.role_id == role.id).delete()
+        db.delete(role)
+        db.commit()
+
+    def _allowed_matrix(self, db: Session) -> set[str]:
+        catalogue = self.catalogue(db)
+        return {f"{resource.id}.{action}" for resource in catalogue.resources for action in ACTIONS}
+
+    def _clean_matrix(self, permissions: list[str], allowed: set[str]) -> set[str]:
+        unknown = [item for item in permissions if item not in allowed]
+        if unknown:
+            raise RoleError(
+                422,
+                FieldErrors(
+                    fields={
+                        "permissions": FieldErrorDetail(
+                            message_key="admin.roles.permissions.invalid"
+                        )
+                    }
+                ).model_dump(),
+            )
+        return set(permissions)
+
+    def _validate_name(self, db: Session, name: str, role_id: UUID | None) -> None:
+        if not name:
+            raise RoleError(
+                422,
+                FieldErrors(
+                    fields={"name": FieldErrorDetail(message_key="admin.field.required")}
+                ).model_dump(),
+            )
+        existing = db.query(Role).filter(func.lower(Role.name) == name.lower()).first()
+        if existing is not None and existing.id != role_id:
+            raise RoleError(
+                422,
+                FieldErrors(
+                    fields={"name": FieldErrorDetail(message_key="admin.roles.name.duplicate")}
+                ).model_dump(),
+            )
+
+    def _replace_permissions(self, db: Session, role: Role, grants: set[str]) -> None:
+        db.query(RolePermission).filter(RolePermission.role_id == role.id).delete()
+        for permission in sorted(grants):
+            db.add(RolePermission(role_id=role.id, permission=permission))
+        db.flush()
+
+    def _summary(self, db: Session, role: Role) -> RoleSummary:
+        return RoleSummary(
+            id=role.id,
+            name=role.name,
+            description=role.description,
+            user_count=self._user_count(db, role.id),
+            is_system=self._is_system(role),
+        )
+
+    def _detail(self, db: Session, role: Role) -> RoleDetail:
+        permissions = sorted(
+            grant.permission
+            for grant in db.query(RolePermission).filter(RolePermission.role_id == role.id)
+        )
+        return RoleDetail(
+            id=role.id,
+            name=role.name,
+            description=role.description,
+            permissions=permissions,
+            user_count=self._user_count(db, role.id),
+            is_system=self._is_system(role),
+        )
+
+    def _user_count(self, db: Session, role_id: UUID) -> int:
+        return (
+            db.query(AdministratorRole)
+            .filter(AdministratorRole.role_id == role_id)
+            .count()
+        )
+
+    def _is_system(self, role: Role) -> bool:
+        return role.name.lower() in SYSTEM_ROLES
+
+    def _description(self, value: str | None) -> str | None:
+        if value is None:
+            return None
+        trimmed = value.strip()
+        return trimmed or None
diff --git a/apps/Backend/tests/contract/test_openapi_parity.py b/apps/Backend/tests/contract/test_openapi_parity.py
index dc2f440..aa9a5dd 100644
--- a/apps/Backend/tests/contract/test_openapi_parity.py
+++ b/apps/Backend/tests/contract/test_openapi_parity.py
@@ -10,6 +10,7 @@
     "admin-auth.v2.yaml",
     "admin-rbac.v1.yaml",
     "admin-management.v2.yaml",
+    "admin-roles.v1.yaml",
     "publish.v2.yaml",
 ]
 
diff --git a/apps/Backend/tests/integration/test_admin_auth.py b/apps/Backend/tests/integration/test_admin_auth.py
index 3c98033..25555d7 100644
--- a/apps/Backend/tests/integration/test_admin_auth.py
+++ b/apps/Backend/tests/integration/test_admin_auth.py
@@ -15,6 +15,7 @@ def test_sign_in_returns_token_pair(client, bootstrapped):
     assert body["expires_in"] >= 1
     assert "administrator" in body["session"]["roles"]
     assert "records.publish" in body["session"]["permissions"]
+    assert "roles.manage" in body["session"]["permissions"]
 
 
 def test_generic_failure_creates_no_session(client, bootstrapped, db):
diff --git a/apps/Backend/tests/integration/test_admin_roles.py b/apps/Backend/tests/integration/test_admin_roles.py
new file mode 100644
index 0000000..ad85cd0
--- /dev/null
+++ b/apps/Backend/tests/integration/test_admin_roles.py
@@ -0,0 +1,189 @@
+from uuid import UUID
+
+from fastapi.testclient import TestClient
+
+from flycatch_api.models import Administrator, AdministratorRole, Role
+from flycatch_api.services.role_service import ACTIONS
+
+
+def _sign_in(client: TestClient, email: str, password: str):
+    return client.post("/api/v1/admin/auth/sign-in", json={"email": email, "password": password})
+
+
+def _admin_headers(client, bootstrapped):
+    tokens = _sign_in(client, bootstrapped["admin_email"], bootstrapped["admin_password"]).json()
+    return {"Authorization": f"Bearer {tokens['access_token']}"}
+
+
+def _editor_headers(client, bootstrapped):
+    tokens = _sign_in(client, bootstrapped["editor_email"], bootstrapped["editor_password"]).json()
+    return {"Authorization": f"Bearer {tokens['access_token']}"}
+
+
+def test_editor_cannot_list_roles(client, bootstrapped):
+    headers = _editor_headers(client, bootstrapped)
+    response = client.get("/api/v1/admin/roles", headers=headers)
+    assert response.status_code == 403
+    assert response.json()["code"] == "permission_denied"
+    assert response.json()["permission"] == "roles.manage"
+
+
+def test_list_roles_paginates_and_searches(client, bootstrapped, db):
+    headers = _admin_headers(client, bootstrapped)
+    for index in range(6):
+        created = client.post(
+            "/api/v1/admin/roles",
+            headers=headers,
+            json={
+                "name": f"reviewer-{index}",
+                "description": "Custom reviewer",
+                "permissions": ["site_settings.read"],
+            },
+        )
+        assert created.status_code == 201
+    page_one = client.get("/api/v1/admin/roles?page=1&per_page=5", headers=headers)
+    assert page_one.status_code == 200
+    body = page_one.json()
+    assert body["per_page"] == 5
+    assert body["page"] == 1
+    assert body["total"] >= 8
+    assert len(body["items"]) == 5
+    page_two = client.get("/api/v1/admin/roles?page=2&per_page=5", headers=headers)
+    assert page_two.status_code == 200
+    assert page_two.json()["items"]
+    search = client.get("/api/v1/admin/roles?q=reviewer-1", headers=headers)
+    assert search.status_code == 200
+    assert search.json()["total"] == 1
+    assert search.json()["items"][0]["name"] == "reviewer-1"
+
+
+def test_create_edit_and_delete_role(client, bootstrapped, seeded_records):
+    headers = _admin_headers(client, bootstrapped)
+    catalogue = client.get("/api/v1/admin/roles/catalogue", headers=headers)
+    assert catalogue.status_code == 200
+    resources = {item["id"] for item in catalogue.json()["resources"]}
+    assert "site_settings" in resources
+    assert "page.home" in resources
+    assert catalogue.json()["actions"] == list(ACTIONS)
+
+    created = client.post(
+        "/api/v1/admin/roles",
+        headers=headers,
+        json={
+            "name": "Publisher",
+            "description": "Can publish home",
+            "permissions": ["page.home.read", "page.home.update", "page.home.publish"],
+        },
+    )
+    assert created.status_code == 201
+    role = created.json()
+    assert role["name"] == "Publisher"
+    assert "page.home.publish" in role["permissions"]
+    assert "records.publish" in role["permissions"]
+    assert "records.view" in role["permissions"]
+    assert "drafts.save" in role["permissions"]
+    assert role["user_count"] == 0
+    assert role["is_system"] is False
+
+    loaded = client.get(f"/api/v1/admin/roles/{role['id']}", headers=headers)
+    assert loaded.status_code == 200
+    assert loaded.json()["permissions"] == role["permissions"]
+
+    updated = client.patch(
+        f"/api/v1/admin/roles/{role['id']}",
+        headers=headers,
+        json={
+            "name": "Publisher",
+            "description": "Updated",
+            "permissions": ["page.home.read"],
+        },
+    )
+    assert updated.status_code == 200
+    assert updated.json()["description"] == "Updated"
+    assert "page.home.publish" not in updated.json()["permissions"]
+    assert "records.publish" not in updated.json()["permissions"]
+
+    deleted = client.delete(f"/api/v1/admin/roles/{role['id']}", headers=headers)
+    assert deleted.status_code == 204
+    missing = client.get(f"/api/v1/admin/roles/{role['id']}", headers=headers)
+    assert missing.status_code == 404
+
+
+def test_duplicate_name_and_protected_system_roles(client, bootstrapped, db):
+    headers = _admin_headers(client, bootstrapped)
+    duplicate = client.post(
+        "/api/v1/admin/roles",
+        headers=headers,
+        json={"name": "Editor", "description": None, "permissions": ["site_settings.read"]},
+    )
+    assert duplicate.status_code == 422
+    name_error = duplicate.json()["detail"]["fields"]["name"]["message_key"]
+    assert name_error == "admin.roles.name.duplicate"
+
+    system = db.query(Role).filter_by(name="administrator").one()
+    renamed = client.patch(
+        f"/api/v1/admin/roles/{system.id}",
+        headers=headers,
+        json={"name": "super-admin", "description": "nope", "permissions": ["site_settings.read"]},
+    )
+    assert renamed.status_code == 409
+    assert renamed.json()["code"] == "system_role"
+
+    deleted = client.delete(f"/api/v1/admin/roles/{system.id}", headers=headers)
+    assert deleted.status_code == 409
+    assert deleted.json()["code"] == "system_role"
+
+
+def test_cannot_delete_role_in_use(client, bootstrapped, db):
+    headers = _admin_headers(client, bootstrapped)
+    created = client.post(
+        "/api/v1/admin/roles",
+        headers=headers,
+        json={"name": "assigned", "description": None, "permissions": ["site_settings.read"]},
+    )
+    role_id = created.json()["id"]
+    admin = db.query(Administrator).filter_by(email=bootstrapped["admin_email"]).one()
+    role = db.query(Role).filter_by(id=UUID(role_id)).one()
+    db.add(
+        AdministratorRole(
+            administrator_id=admin.id,
+            role_id=role.id,
+            assigned_at=admin.created_at,
+            assigned_by="test",
+        )
+    )
+    db.commit()
+    deleted = client.delete(f"/api/v1/admin/roles/{role_id}", headers=headers)
+    assert deleted.status_code == 409
+    assert deleted.json()["code"] == "role_in_use"
+
+
+def test_administrator_without_stored_manage_grant_can_list_roles(client, bootstrapped, db):
+    from flycatch_api.models import Role, RolePermission
+
+    role = db.query(Role).filter_by(name="administrator").one()
+    db.query(RolePermission).filter(
+        RolePermission.role_id == role.id,
+        RolePermission.permission == "roles.manage",
+    ).delete()
+    db.commit()
+    headers = _admin_headers(client, bootstrapped)
+    listed = client.get("/api/v1/admin/roles", headers=headers)
+    assert listed.status_code == 200
+
+
+def test_administrator_keeps_roles_manage(client, bootstrapped, db):
+    headers = _admin_headers(client, bootstrapped)
+    system = db.query(Role).filter_by(name="administrator").one()
+    updated = client.patch(
+        f"/api/v1/admin/roles/{system.id}",
+        headers=headers,
+        json={
+            "name": "administrator",
+            "description": "Full access to administration",
+            "permissions": ["site_settings.read"],
+        },
+    )
+    assert updated.status_code == 200
+    assert "roles.manage" in updated.json()["permissions"]
+    assert "records.view" in updated.json()["permissions"]
diff --git a/apps/Backend/tests/integration/test_bootstrap.py b/apps/Backend/tests/integration/test_bootstrap.py
index c611abd..72452cb 100644
--- a/apps/Backend/tests/integration/test_bootstrap.py
+++ b/apps/Backend/tests/integration/test_bootstrap.py
@@ -2,12 +2,13 @@
 from unittest.mock import patch
 
 from flycatch_api.cli.bootstrap import main
-from flycatch_api.models import Administrator, AdministratorRole, PermissionName, Role, RolePermission
+from flycatch_api.models import Administrator, AdministratorRole, Role, RolePermission
 from flycatch_api.services.bootstrap_service import (
     BootstrapError,
     BootstrapService,
     BootstrapUser,
 )
+from flycatch_api.services.role_service import default_grants
 
 
 def test_bootstrap_creates_two_users_and_catalogue(db):
@@ -17,14 +18,14 @@ def test_bootstrap_creates_two_users_and_catalogue(db):
         BootstrapUser("editor1@example.com", "editor-password", "editor"),
     )
     assert sorted(result.created_users) == ["admin1@example.com", "editor1@example.com"]
-    roles = {role.name: {grant.permission for grant in role.permissions} for role in db.query(Role).all()}
-    assert roles["administrator"] == {
-        PermissionName.records_view,
-        PermissionName.drafts_save,
-        PermissionName.records_publish,
+    grants = {
+        role.name: {item.permission for item in role.permissions} for role in db.query(Role).all()
     }
-    assert roles["editor"] == {PermissionName.records_view, PermissionName.drafts_save}
-    assert PermissionName.records_publish not in roles["editor"]
+    assert grants["administrator"] == set(default_grants("administrator"))
+    assert grants["editor"] == set(default_grants("editor"))
+    assert "records.publish" not in grants["editor"]
+    assert "roles.manage" not in grants["editor"]
+    assert "roles.manage" in grants["administrator"]
     assert db.query(Administrator).count() == 2
 
 
@@ -40,7 +41,9 @@ def test_bootstrap_is_idempotent(db):
     assert "already exist" in second.summary().lower() or second.already_existed
     assert db.query(Administrator).count() == 2
     assert db.query(Role).count() == 2
-    assert db.query(RolePermission).count() == 5
+    assert db.query(RolePermission).count() == len(default_grants("administrator")) + len(
+        default_grants("editor")
+    )
 
 
 def test_bootstrap_creates_missing_user_of_the_pair(db):
diff --git a/specs/002-auth-rbac/contracts/README.md b/specs/002-auth-rbac/contracts/README.md
index 77aa000..d4b0a7e 100644
--- a/specs/002-auth-rbac/contracts/README.md
+++ b/specs/002-auth-rbac/contracts/README.md
@@ -8,7 +8,7 @@ Payload schemas for pages and site settings remain in `specs/001-website-foundat
 
 1. **Publish contracts first** — no consumer implementation before the YAML exists and passes validation.
 2. **Backend implements** — routers and Pydantic models align with these files; served `/openapi.json` MUST not drift.
-3. **Administration FE matches** — runtime API client and types MUST be generated from `admin-auth.v2`, `admin-rbac.v1`, `admin-management.v2`, and `publish.v2`.
+3. **Administration FE matches** — runtime API client and types MUST be generated from `admin-auth.v2`, `admin-rbac.v1`, `admin-management.v2`, `admin-roles.v1`, and `publish.v2`.
 4. **Breaking changes** — require a new version file; quality gates reject silent drift.
 5. **Tokens** — access JWT and refresh token appear only in documented JSON bodies. Clients store them in memory and send the access token as `Authorization: Bearer`.
 
@@ -20,6 +20,7 @@ Runtime prefix: `/api/v1`. Public browsers MUST NOT call these endpoints for ord
 | --- | --- | --- |
 | [admin-auth.v2.yaml](./admin-auth.v2.yaml) | Sign-in, refresh, sign-out, session | Replaces `001` `admin-auth.v1.yaml` |
 | [admin-rbac.v1.yaml](./admin-rbac.v1.yaml) | Roles, permissions, denial shape | Shared schemas + operation map |
+| [admin-roles.v1.yaml](./admin-roles.v1.yaml) | Role CRUD and permission matrix | Requires `roles.manage` |
 | [admin-management.v2.yaml](./admin-management.v2.yaml) | View/draft managed records | Bearer; no CSRF; 401 vs 403 |
 | [publish.v2.yaml](./publish.v2.yaml) | Publish | Bearer; `records.publish` required |
 | [bootstrap.cli.yaml](./bootstrap.cli.yaml) | Operator bootstrap CLI | Not an HTTP API |
@@ -30,6 +31,7 @@ Runtime prefix: `/api/v1`. Public browsers MUST NOT call these endpoints for ord
 | --- | --- | --- | --- |
 | admin-auth.v2 | Implements routes | — | Generated client + in-memory token store |
 | admin-rbac.v1 | Implements checks | — | Session permissions / control visibility |
+| admin-roles.v1 | Implements routes | — | Generated client + Settings / Roles UI |
 | admin-management.v2 | Implements routes | — | Generated client |
 | publish.v2 | Implements route | Snapshot still from `001` publish.v1 schemas | Generated client |
 | bootstrap.cli | Implements CLI | — | — |
diff --git a/specs/002-auth-rbac/contracts/admin-rbac.v1.yaml b/specs/002-auth-rbac/contracts/admin-rbac.v1.yaml
index 8ebeaf1..7ec4d8c 100644
--- a/specs/002-auth-rbac/contracts/admin-rbac.v1.yaml
+++ b/specs/002-auth-rbac/contracts/admin-rbac.v1.yaml
@@ -23,7 +23,7 @@ components:
       enum: [administrator, editor]
     PermissionName:
       type: string
-      enum: [records.view, drafts.save, records.publish]
+      enum: [records.view, drafts.save, records.publish, roles.manage]
     PermissionDenied:
       type: object
       additionalProperties: false
@@ -56,7 +56,7 @@ components:
         $ref: '#/components/schemas/RoleGrant'
       example:
         - name: administrator
-          permissions: [records.view, drafts.save, records.publish]
+          permissions: [records.view, drafts.save, records.publish, roles.manage]
         - name: editor
           permissions: [records.view, drafts.save]
     OperationPermissionMap:
diff --git a/specs/002-auth-rbac/contracts/admin-roles.v1.yaml b/specs/002-auth-rbac/contracts/admin-roles.v1.yaml
new file mode 100644
index 0000000..605da33
--- /dev/null
+++ b/specs/002-auth-rbac/contracts/admin-roles.v1.yaml
@@ -0,0 +1,318 @@
+openapi: 3.1.0
+info:
+  title: Administration Role Management
+  version: 1.0.0
+  summary: Create, list, update, and delete roles and their permission matrix.
+  description: |
+    Staff with roles.manage may list and persist roles. Permissions are stored as
+    {resource}.{action} strings. System roles administrator and editor cannot be
+    renamed or deleted. Content APIs continue to enforce records.view, drafts.save,
+    and records.publish; those grants are synced from the matrix on save.
+servers:
+  - url: /api/v1
+security:
+  - bearerAuth: []
+paths:
+  /admin/roles:
+    get:
+      operationId: listRoles
+      summary: List roles with search and pagination
+      parameters:
+        - name: q
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: page
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: per_page
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 5
+            default: 5
+      responses:
+        '200':
+          description: Paginated role list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleList'
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+    post:
+      operationId: createRole
+      summary: Create a role with a permission matrix
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RoleWrite'
+      responses:
+        '201':
+          description: Created role
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleDetail'
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+        '422':
+          $ref: '#/components/responses/FieldErrors'
+  /admin/roles/catalogue:
+    get:
+      operationId: getRoleCatalogue
+      summary: Resources and actions for the permission matrix
+      responses:
+        '200':
+          description: Catalogue
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleCatalogue'
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+  /admin/roles/{role_id}:
+    parameters:
+      - $ref: '#/components/parameters/RoleId'
+    get:
+      operationId: getRole
+      summary: Return one role including permissions
+      responses:
+        '200':
+          description: Role detail
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleDetail'
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    patch:
+      operationId: updateRole
+      summary: Update role name, description, and permissions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RoleWrite'
+      responses:
+        '200':
+          description: Updated role
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleDetail'
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/RoleConflict'
+        '422':
+          $ref: '#/components/responses/FieldErrors'
+    delete:
+      operationId: deleteRole
+      summary: Delete a role that is not a system role and has no users
+      responses:
+        '204':
+          description: Deleted
+        '401':
+          $ref: './admin-rbac.v1.yaml#/components/responses/Unauthenticated'
+        '403':
+          $ref: './admin-rbac.v1.yaml#/components/responses/PermissionDenied'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/RoleConflict'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  parameters:
+    RoleId:
+      name: role_id
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    RoleAction:
+      type: string
+      enum: [create, read, update, delete, publish]
+    RoleResource:
+      type: object
+      additionalProperties: false
+      required: [id, type, slug]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        slug:
+          type: string
+    RoleCatalogue:
+      type: object
+      additionalProperties: false
+      required: [actions, resources]
+      properties:
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/RoleAction'
+        resources:
+          type: array
+          items:
+            $ref: '#/components/schemas/RoleResource'
+    RoleSummary:
+      type: object
+      additionalProperties: false
+      required: [id, name, description, user_count, is_system]
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        user_count:
+          type: integer
+          minimum: 0
+        is_system:
+          type: boolean
+    RoleList:
+      type: object
+      additionalProperties: false
+      required: [items, page, per_page, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/RoleSummary'
+        page:
+          type: integer
+          minimum: 1
+        per_page:
+          type: integer
+          minimum: 1
+        total:
+          type: integer
+          minimum: 0
+    RoleDetail:
+      type: object
+      additionalProperties: false
+      required: [id, name, description, permissions, user_count, is_system]
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        permissions:
+          type: array
+          items:
+            type: string
+        user_count:
+          type: integer
+          minimum: 0
+        is_system:
+          type: boolean
+    RoleWrite:
+      type: object
+      additionalProperties: false
+      required: [name, permissions]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 64
+        description:
+          type: string
+          maxLength: 500
+          nullable: true
+        permissions:
+          type: array
+          items:
+            type: string
+    RoleConflict:
+      type: object
+      additionalProperties: false
+      required: [code, message_key]
+      properties:
+        code:
+          type: string
+          enum: [system_role, role_in_use]
+        message_key:
+          type: string
+    FieldErrorDetail:
+      type: object
+      additionalProperties: false
+      required: [message_key]
+      properties:
+        message_key:
+          type: string
+    FieldErrors:
+      type: object
+      additionalProperties: false
+      required: [fields]
+      properties:
+        fields:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/FieldErrorDetail'
+  responses:
+    NotFound:
+      description: Unknown role
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties: false
+            required: [code, message_key]
+            properties:
+              code:
+                type: string
+                const: not_found
+              message_key:
+                type: string
+                const: admin.roles.not_found
+    RoleConflict:
+      description: System role or role still assigned to users
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/RoleConflict'
+    FieldErrors:
+      description: Field-level validation errors
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/FieldErrors'

From 7cfadde10cf08a3dd80ef412a75963995c093983 Mon Sep 17 00:00:00 2001
From: athulrajtflycatchtech <athulraj.t@flycatchtech.com>
Date: Mon, 17 Aug 2026 15:03:57 +0530
Subject: [PATCH 2/2] feat(roles-permissions): add comprehensive specification
 and quality checklist for Administration Roles and Permissions feature;
 outline user scenarios, acceptance criteria, and scope details

---
 .../checklists/requirements.md                |  41 ++++
 specs/003-roles-permissions/spec.md           | 213 ++++++++++++++++++
 2 files changed, 254 insertions(+)
 create mode 100644 specs/003-roles-permissions/checklists/requirements.md
 create mode 100644 specs/003-roles-permissions/spec.md

diff --git a/specs/003-roles-permissions/checklists/requirements.md b/specs/003-roles-permissions/checklists/requirements.md
new file mode 100644
index 0000000..2d8e89b
--- /dev/null
+++ b/specs/003-roles-permissions/checklists/requirements.md
@@ -0,0 +1,41 @@
+# Specification Quality Checklist: Administration Roles and Permissions
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-08-17
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation iteration 1 (2026-08-17): All items pass.
+- No `[NEEDS CLARIFICATION]` markers in spec.md.
+- Informed defaults (documented in Assumptions and FR-001–FR-021): Settings opens Roles; five roles per page; shared create/edit form; matrix is Create/Read/Update/Delete/Publish per managed page/content type; delete requires confirmation; Administrator has role-management and Editor does not; system roles cannot be renamed or deleted; roles with assigned users cannot be deleted; Create/Delete grants may be stored without new content create/delete operations; tab title follows the selected section.
+- Implementation avoided: no languages, frameworks, data stores, or HTTP path names. Persistence is described as “through the administration backend”. Enforcement is “backend must refuse” so UI hiding is not treated as sufficient.
+- Extension points named without prescribing stack: existing Administration UI, existing staff session, existing operator provisioning path, versioned administration contracts for role management.
+- Stack, tooling, and exact contract file versions remain deferred to `/speckit-plan`.
+- This specification documents the role-management UI that `002-auth-rbac` explicitly left out of scope.
+- Items marked incomplete would require spec updates before `/speckit-clarify` or `/speckit-plan`; none remain incomplete.
diff --git a/specs/003-roles-permissions/spec.md b/specs/003-roles-permissions/spec.md
new file mode 100644
index 0000000..28ce0e1
--- /dev/null
+++ b/specs/003-roles-permissions/spec.md
@@ -0,0 +1,213 @@
+# Feature Specification: Administration Roles and Permissions
+
+**Feature Branch**: `003-roles-permissions`
+
+**Created**: 2026-08-17
+
+**Status**: Draft
+
+**Input**: User description: "In the Administration section, implement a complete Roles & Permissions feature. Clicking Settings should open the Roles page. Add New Role, Search, pagination with 5 roles per page. Table columns: Name, Description, Users, Actions (Edit, Delete). Connect the UI to the backend so roles are persisted. Use the same form for creating and editing a role (Role Name, Description, and per-page/content-type Create, Read, Update, Delete, Publish). When editing, load existing permissions. Save through the backend. Delete only after confirmation. Use existing architecture. Keep the implementation simple. Add clean and responsive styling. The browser tab name follows the selected section."
+
+**Constitution alignment**: This specification implements mandatory governance from `.specify/memory/constitution.md` (v1.0.0). Requirements trace primarily to principles VIII (security), III (contract-first), V (i18n), IX (accessibility), II (native elements), VI (performance), XI (responsive UI), XII (production-grade), and XIII (quality gates). Public SEO/AEO (I) and Core Web Vitals (VII) apply only as a non-regression: this feature MUST NOT weaken public delivery or expose the Administration UI to search.
+
+## Scope
+
+This feature **adds** staff-facing role management to the existing Administration UI. It extends `002-auth-rbac`, which defined roles, permissions, bootstrap, and server-side enforcement but left role-management screens out of scope. It does not add public visitor accounts or a new product surface.
+
+### In scope
+
+- A Settings entry in Administration that opens a Roles page for authorised staff
+- Listing persisted roles with search, pagination (five roles per page), and columns for name, description, assigned-user count, and actions
+- Creating and editing a role with one shared form: role name, description, and a permission matrix of available application pages/content types with Create, Read, Update, Delete, and Publish
+- Loading a role’s existing details and permissions when editing
+- Persisting role details and permissions through the administration backend
+- Deleting a role only after the staff member confirms
+- Browser tab title that follows the selected Administration section
+- Accessible, internationalised, responsive Roles screens consistent with Administration UI baselines
+- Server-side enforcement of who may manage roles (hiding the Settings entry is not sufficient)
+
+### Out of scope
+
+- Public visitor accounts or any authenticated public area
+- Creating, inviting, or assigning staff users from this screen (user provisioning stays on the existing operator path)
+- Changing sign-in, sign-out, session lifetime, or bootstrap of the first two default users
+- Per-record or per-field access lists, approval workflows, or legal-review products
+- Enforcing Create and Delete on content records that the product does not yet allow staff to create or delete
+- Changing public static delivery, publish mechanics, or content models beyond recording permissions against existing pages/content types
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Authorised staff member opens Roles from Settings (Priority: P1)
+
+A signed-in Administrator (or any staff member whose roles include role-management) opens Administration, selects Settings, and sees the Roles page. The browser tab title matches Settings. An Editor (or any staff member without role-management) does not see a working Settings entry for roles and cannot complete role-management actions.
+
+**Why this priority**: Without a reachable, authorised Roles page, nothing else in this feature can be used.
+
+**Independent Test**: Sign in as Administrator; open Settings; confirm the Roles list is shown and the tab title matches the section. Sign in as Editor; confirm Settings for roles is absent or clearly unusable and a direct role-management request is refused.
+
+**Acceptance Scenarios**:
+
+1. **Given** a signed-in staff member whose roles include role-management, **When** they select Settings, **Then** they see the Roles page and the browser tab title is the Settings section label
+2. **Given** a signed-in staff member whose roles do not include role-management, **When** they use Administration, **Then** they do not get a working Settings control that opens Roles
+3. **Given** that same unauthorised signed-in staff member, **When** a role-management request is sent anyway, **Then** the system refuses it, does not change roles, and leaves them signed in
+4. **Given** an unauthenticated person, **When** they request role-management, **Then** they are treated as signed out (not as “permission denied”) and see no staff-only role data
+5. **Given** a signed-in authorised staff member switching among Site settings, Home page, Settings, and add/edit role, **When** the selected section changes, **Then** the browser tab title follows that section’s label; sign-in keeps the sign-in title
+
+---
+
+### User Story 2 - Authorised staff member finds and reviews roles (Priority: P1)
+
+The authorised staff member sees persisted roles in a table: Name, Description, Users (how many staff are assigned), and Actions. They can search and move through pages of five roles each. Default roles created by bootstrap appear alongside any later custom roles.
+
+**Why this priority**: Staff cannot manage what they cannot find. Persistence is proven by listing what the backend already stores.
+
+**Independent Test**: With more than five roles present, open Settings, confirm five per page and paging; search by name or description; confirm user counts and that listed data matches stored roles.
+
+**Acceptance Scenarios**:
+
+1. **Given** persisted roles exist, **When** an authorised staff member opens Settings, **Then** they see a Roles list with Name, Description, Users, and Actions
+2. **Given** more than five roles, **When** they view the list, **Then** exactly five roles appear on the first page and they can move to further pages to see the rest
+3. **Given** roles with distinct names or descriptions, **When** they search, **Then** the list is limited to matching roles and paging starts from the first page of that result
+4. **Given** a role assigned to some number of staff, **When** the list is shown, **Then** the Users column shows that count
+5. **Given** an Add New Role control, **When** the list is shown, **Then** that control is available to authorised staff
+
+---
+
+### User Story 3 - Authorised staff member creates or edits a role and its permissions (Priority: P1)
+
+The authorised staff member uses one form to add a role or to edit an existing one. They enter a role name and description. They see each available application page/content type with Create, Read, Update, Delete, and Publish. On edit, the form shows the role’s current details and permissions. Saving stores name, description, and permissions so a later visit shows the same data.
+
+**Why this priority**: Creating and editing with a persisted permission matrix is the core value of the feature.
+
+**Independent Test**: Create a role with a subset of permissions; reopen it and confirm the same name, description, and checks; change permissions and confirm the stored set updates. Confirm the matrix lists current managed pages/content types.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Roles list, **When** authorised staff choose Add New Role, **Then** they see the same form used for editing, empty of a stored role, with name, description, and the permission matrix
+2. **Given** an existing role, **When** they choose Edit, **Then** the form loads that role’s name, description, and current permissions
+3. **Given** the permission matrix, **When** it is shown, **Then** each available application page/content type has Create, Read, Update, Delete, and Publish
+4. **Given** valid name and selected permissions, **When** they save, **Then** the role is persisted and a later list or edit shows the saved details and permissions
+5. **Given** a role name that already exists (ignoring letter case), **When** they try to save a new role with that name, **Then** save is refused with a field-level, internationalised error and no duplicate role is created
+6. **Given** a default system role (Administrator or Editor), **When** they edit it, **Then** they may change description and permissions but MUST NOT rename it
+
+---
+
+### User Story 4 - Authorised staff member deletes a role after confirmation (Priority: P2)
+
+The authorised staff member chooses Delete on a role that is safe to remove. They must confirm before the role is removed. Default system roles cannot be deleted. A role still assigned to staff cannot be deleted until it has no assignees.
+
+**Why this priority**: Accidental deletion of roles would lock staff out of work; confirmation and safeguards are required before delete is useful.
+
+**Independent Test**: Attempt delete of a custom unused role: cancel leaves it; confirm removes it. Attempt delete of Administrator, Editor, or a role with assignees: deletion is refused.
+
+**Acceptance Scenarios**:
+
+1. **Given** a custom role with no assigned users, **When** authorised staff choose Delete, **Then** they are asked to confirm before anything is removed
+2. **Given** that confirmation prompt, **When** they cancel, **Then** the role remains
+3. **Given** that confirmation prompt, **When** they confirm, **Then** the role is removed and no longer appears in the list
+4. **Given** a default system role (Administrator or Editor), **When** they attempt Delete, **Then** deletion is refused and the role remains
+5. **Given** a role still assigned to one or more staff, **When** they attempt Delete, **Then** deletion is refused and the role remains
+
+---
+
+### Edge Cases
+
+- Settings is selected but workspace content records cannot be loaded — authorised staff MUST still reach Roles; unauthorised staff MUST NOT
+- Search matches no roles — the list is empty with an accessible, internationalised empty state; paging does not invent rows
+- A role is edited by two staff at once — the last successful save is stored; a deleted role cannot be edited (not-found, internationalised)
+- The last remaining role-management capability on Administrator MUST NOT be removable in a way that leaves the environment with nobody who can open Settings
+- A staff member’s role-management access is revoked after they signed in — subsequent role-management actions MUST use current assignments
+- Permission checkboxes for Create or Delete on a content type that staff cannot yet create or delete MAY be stored; they MUST NOT imply those content operations exist
+- Direct requests to Administration addresses by crawlers MUST remain non-indexable and MUST NOT leak role names, descriptions, or permission grants in public HTML
+- Failed role save MUST preserve valid input the person already entered
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+#### Navigation and visibility
+
+- **FR-001**: Administration MUST provide a Settings control, distinct from Site settings, that opens the Roles page for authorised staff.
+- **FR-002**: The Settings control MUST be available only to signed-in staff whose current roles include role-management. Default Administrator MUST have role-management. Default Editor MUST NOT.
+- **FR-003**: The browser tab title MUST follow the selected Administration section, using the same labels as the navigation (Site settings, Home page, Settings, Add New Role, Edit role). The sign-in screen MUST keep the sign-in title.
+- **FR-004**: Role-management screens MUST remain on the existing Administration UI surface. They MUST reuse the existing staff session; they MUST NOT require a separate public application.
+
+#### Roles list
+
+- **FR-005**: The Roles page MUST list persisted roles with columns: Name, Description, Users (assigned staff count), and Actions (Edit, Delete).
+- **FR-006**: The Roles page MUST provide Add New Role and Search (by name or description).
+- **FR-007**: The Roles page MUST paginate at five roles per page.
+- **FR-008**: The list MUST reflect stored roles, including bootstrap default roles and later custom roles.
+
+#### Create and edit
+
+- **FR-009**: Create and edit MUST use the same form with Role Name, Description, and a permission matrix.
+- **FR-010**: The matrix MUST list available application pages/content types. For each, staff MUST be able to grant or withhold Create, Read, Update, Delete, and Publish.
+- **FR-011**: When editing, the form MUST load the role’s existing name, description, and permissions.
+- **FR-012**: Saving MUST persist role details and permissions through the administration backend so a later visit shows the same data.
+- **FR-013**: Role names MUST be unique ignoring letter case. Description MAY be empty.
+- **FR-014**: Default system roles Administrator and Editor MUST NOT be renamed. Their description and permissions MAY be edited, subject to FR-020.
+
+#### Delete
+
+- **FR-015**: Delete MUST run only after the staff member confirms. Cancelling MUST leave the role unchanged.
+- **FR-016**: Default system roles MUST NOT be deletable.
+- **FR-017**: A role with one or more assigned staff MUST NOT be deletable.
+
+#### Authorisation and persistence
+
+- **FR-018**: The backend MUST refuse role-management actions when the signed-in person lacks role-management. A hidden control is not sufficient.
+- **FR-019**: Unauthenticated role-management requests MUST be rejected as unauthenticated, not as insufficient permission.
+- **FR-020**: The Administrator role MUST retain role-management so the environment cannot be left with no one able to open Settings.
+- **FR-021**: Effective permissions for existing view, draft, and publish administration actions MUST stay consistent with the matrix: granting Read MUST continue to allow viewing managed records; Update MUST continue to allow saving drafts; Publish MUST continue to allow publish. Create and Delete grants MAY be stored without adding new content create/delete operations in this feature.
+- **FR-022**: Versioned, machine-readable contracts for listing, reading, creating, updating, and deleting roles, and for the permission catalogue, MUST be published or updated before consumers change (constitution III).
+
+#### Non-functional (constitution)
+
+- **FR-023**: User-facing strings for Roles, Settings, validation, confirmation, and denial MUST be externalised as message keys (constitution V).
+- **FR-024**: Roles screens MUST meet WCAG 2.2 Level AA: labels, keyboard operation, visible focus, and field-level errors that preserve valid input (constitution IX).
+- **FR-025**: Administration responses MUST remain non-indexable and MUST NOT appear in the public sitemap. This feature MUST NOT add Administration UI links to anonymous public pages (constitution I, VIII).
+- **FR-026**: This feature MUST NOT add script or layout weight to public pages. Administration UI changes MUST reuse existing layout regions and design patterns and MUST be usable on supported viewports (constitution II, VI, X, XI).
+- **FR-027**: Quality gates MUST cover authorised list/create/edit/delete, search and five-per-page paging, unauthorised refusal, system-role and in-use delete refusal, duplicate-name refusal, and contract validation (constitution XIII).
+
+### Key Entities
+
+- **Role**: A named set of permissions with an optional description. Assigned to staff; does not itself sign in. Includes bootstrap defaults Administrator and Editor and any later custom roles.
+- **Permission grant**: A stored yes/no for one action (Create, Read, Update, Delete, Publish) on one application page or content type, plus role-management for who may use Settings.
+- **Role assignment**: The link between a staff user and a Role. The Users column is the count of these links. Effective permissions remain the union of assigned roles (`002-auth-rbac`).
+- **Permission catalogue**: The current list of application pages/content types that appear as matrix rows, derived from managed administration records (at minimum site settings and the home page).
+- **Staff session**: The signed-in period required for Administration. Role-management uses current assignments at request time.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: In 100% of trials, an authorised Administrator reaches the Roles page from Settings in under 30 seconds after sign-in on a typical office connection, and the tab title matches Settings.
+- **SC-002**: In 100% of trials, an Editor (or any user without role-management) cannot complete a role create, edit, or delete — including when they send the request directly.
+- **SC-003**: Creating a role and reopening it shows the same name, description, and permission selections in 100% of trials.
+- **SC-004**: With more than five stored roles, the first page shows exactly five rows in 100% of trials, and remaining roles are reachable by paging.
+- **SC-005**: 100% of delete attempts without confirmation leave the role in place; 100% of confirmed deletes of a custom unused role remove it.
+- **SC-006**: 100% of attempts to delete Administrator, Editor, or a role that still has assigned staff leave that role in place.
+- **SC-007**: 100% of unauthenticated requests for role data fail to expose role names, descriptions, or permission grants.
+- **SC-008**: 100% of Roles, Settings, validation, confirmation, and denial messages are referenced by message key (zero hard-coded user-facing strings in those flows).
+- **SC-009**: 100% of Roles list, form, and confirmation screens pass WCAG 2.2 AA automated checks with zero critical violations, and remain usable at a typical mobile and desktop administration viewport.
+
+## Assumptions
+
+- This feature extends `002-auth-rbac` and `001-website-foundation`. It does not replace sign-in, bootstrap of the first two users, draft/publish, or the public static site.
+- “Settings” is the Administration navigation label that opens Roles. It is not Site settings.
+- Role-management is a staff capability held by default Administrator and not by default Editor. Custom roles do not receive role-management unless a later specification says they may.
+- Available matrix rows are the managed pages/content types already administered today (site settings and home at minimum). New managed pages SHOULD appear as additional rows without a new product surface.
+- Create and Delete in the matrix are recorded for completeness. This feature does not add staff operations to create or delete content records.
+- Read, Update, and Publish in the matrix continue to mean view managed records, save drafts, and publish, as in `002-auth-rbac`.
+- Staff user assignment to roles remains an operator provisioning concern. This screen only displays how many users hold each role.
+- Public SEO, Core Web Vitals, and static delivery baselines remain unchanged.
+- WCAG 2.2 Level AA remains the accessibility target for Roles screens.
+
+## Constraints
+
+- Specifications and implementations MUST remain aligned with the existing three-surface architecture (public frontend, backend, Administration UI). A fourth identity or roles product is out of scope.
+- Stack and library choices belong to `/speckit-plan`. This specification MUST stay technology-agnostic while naming the existing Administration UI, staff session, and administration contracts as the extension points.
+- Public pages MUST stay statically deliverable and MUST NOT require a staff session.
+- Least privilege: default Editor MUST NOT receive role-management. Default Administrator MUST NOT lose role-management through this screen.
+- Weakening foundation or `002-auth-rbac` security, accessibility, i18n, or administration-isolation baselines MUST require a documented, approved exception.