diff --git a/.gitignore b/.gitignore
index 3c697eb7da..a1eb95a77c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,13 @@ backend/app/frontend/
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+
+# IDE
+.idea/
+
+# Duplicate OpenSpec tool scaffolding
+.agent/
+.agents/
+.commandcode/
+.claude/commands/opsx/
+.claude/skills/openspec-*/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..2b85c70638
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,37 @@
+# Engineering rules
+
+## Stack
+
+- **Backend**: FastAPI + SQLModel (Pydantic + SQLAlchemy) + Alembic + Postgres. Package/venv managed with `uv` from `backend/`.
+- **Frontend**: React + TanStack Router/Query + generated OpenAPI client (`@hey-api/openapi-ts`) + shadcn/radix + Tailwind. Managed with `bun` from `frontend/` (or repo root via `bun run --filter frontend <script>`).
+- **Local services**: `docker compose up` runs Postgres + Mailpit (see `compose.yml`). App servers run outside Docker in dev.
+
+## Known gotchas
+
+- `app.main` (`backend/app/main.py`) unconditionally mounts a static frontend build at `backend/app/frontend`. That directory only exists after a frontend build is copied in (normally a Docker build step). Running `uv run fastapi dev app/main.py` in a fresh dev checkout without that directory logs a `UserWarning` but still starts — if it ever hard-fails instead, generate the OpenAPI schema from `app.api.main.api_router` directly (see `scripts/generate-client.sh` for the shape) rather than importing `app.main`.
+- `scripts/generate-client.sh` requires the backend importable and a running Postgres (`docker compose up`). Regenerate the client (`bun run --filter frontend generate-client`) any time backend Pydantic/SQLModel schemas change — the frontend has no fallback typing.
+- **`uv run bash scripts/test.sh` wipes all `User` and `Item` rows** in whatever database `DATABASE_URL` points to. `tests/conftest.py`'s session-scoped `db` fixture unconditionally deletes both tables at teardown. Locally this is the *same* Postgres instance/database used for interactive dev testing — there's no separate test DB in this local setup. Never run the backend test suite against a database with data you want to keep; if you just did, re-seed with `uv run bash scripts/prestart.sh` (restores roles/permissions/first-admin, but any other manually-created accounts are gone for good).
+
+## Authorization (RBAC)
+
+This project uses role-based access control. The design lives in `openspec/changes/add-rbac/design.md`; the human-facing writeup (permission matrix, setup, seeding) lives in `docs/AUTHORIZATION.md`. The rules below are what keep it maintainable — read them before touching any permission check.
+
+**Single source of truth for permission codes and role grants**: `backend/app/core/rbac.py`. Every permission code and every role→permission grant is defined there once, as constants — nowhere else. The frontend mirrors the same codes as a `PERMISSIONS` constant object in `frontend/src/utils.ts`. Never hardcode a permission string (`"users:list"`, `"metrics:view"`, etc.) anywhere else in either codebase — import the constant.
+
+**Backend checks always go through `require_permission(code)`** (`backend/app/api/deps.py`), used as a route dependency. The one exception is item-ownership fallback (`owner_id == current_user.id`) in `app/api/routes/items.py`, which stays inline because it's data-scoped, not role-scoped — everything else goes through the dependency. Never write an inline `if current_user.role.slug == "admin"` check in a route; that's exactly the pattern this replaced.
+
+**Frontend checks always go through `hasPermission(user, code)`** (`frontend/src/utils.ts`). Never branch on `user.role === "..."` in a component — role names are for display (badges, select options), not authorization decisions.
+
+**Unauthorized direct navigation shows the shared `AccessDenied` page** (routed at `/forbidden`), not a silent redirect to `/` and not a raw error. Every route `beforeLoad` guard redirects there on a failed permission check.
+
+**To add a new role**: add one row to the seed data (migration + `init_db`) and one entry to `ROLE_PERMISSIONS` in `rbac.py`. No route or component should need to change.
+
+**To add a new permission**: add one constant in `rbac.py` (and the mirrored `PERMISSIONS` entry in `utils.ts`), add it to whichever roles should have it in `ROLE_PERMISSIONS`/seed data, and use it at exactly the route(s) or component(s) it protects via `require_permission`/`hasPermission`. That's the whole change — if you find yourself editing more than the seed data, `rbac.py`, `utils.ts`, and the specific protected site(s), stop and reconsider.
+
+**Comments**: authorization code stays comment-free by default — the constants and dependency names should make the model obvious on their own. Add a comment only where the *why* genuinely isn't visible in the code (e.g., why several unrelated checks share the `system:admin` catch-all). Don't add a comment that restates what a function or constant name already says.
+
+## General
+
+- No comments unless the *why* is non-obvious (see above) — this applies repo-wide, not just to authorization code.
+- Don't add abstractions, config flags, or generalized helpers for a single call site. Three similar lines beat a premature abstraction.
+- Keep changes scoped to what's asked; don't drive-by refactor unrelated code in the same diff.
diff --git a/README.md b/README.md
index a3e20f4dbf..5149be0dd0 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,10 @@ General development docs: [development.md](./development.md).
 
 This includes the local FastAPI and Vite workflow, Docker Compose services, `.env` configuration, and more.
 
+## Authorization
+
+Role-based access control (roles, permissions, and how the frontend learns a user's capabilities): [docs/AUTHORIZATION.md](./docs/AUTHORIZATION.md).
+
 ## Release Notes
 
 Check the file [release-notes.md](./release-notes.md).
diff --git a/backend/app/alembic/versions/2d1ae9889b29_add_rbac_roles_and_permissions.py b/backend/app/alembic/versions/2d1ae9889b29_add_rbac_roles_and_permissions.py
new file mode 100644
index 0000000000..f9eff031fd
--- /dev/null
+++ b/backend/app/alembic/versions/2d1ae9889b29_add_rbac_roles_and_permissions.py
@@ -0,0 +1,149 @@
+"""add rbac roles and permissions
+
+Revision ID: 2d1ae9889b29
+Revises: fe56fa70289e
+Create Date: 2026-08-20 15:22:27.932585
+
+"""
+import uuid
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+
+
+# revision identifiers, used by Alembic.
+revision = '2d1ae9889b29'
+down_revision = 'fe56fa70289e'
+branch_labels = None
+depends_on = None
+
+
+ADMIN_ROLE_ID = uuid.uuid4()
+MANAGER_ROLE_ID = uuid.uuid4()
+MEMBER_ROLE_ID = uuid.uuid4()
+
+PERMISSION_CODES = [
+    "users:list",
+    "users:create",
+    "users:manage",
+    "metrics:view",
+    "system:admin",
+]
+
+# role slug -> permission codes granted to it
+ROLE_PERMISSIONS = {
+    "admin": PERMISSION_CODES,
+    "manager": ["users:list", "metrics:view"],
+    "member": [],
+}
+
+
+def upgrade():
+    op.create_table(
+        'permission',
+        sa.Column('code', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=False),
+        sa.Column('id', sa.Uuid(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(op.f('ix_permission_code'), 'permission', ['code'], unique=True)
+    op.create_table(
+        'role',
+        sa.Column('slug', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=False),
+        sa.Column('id', sa.Uuid(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(op.f('ix_role_slug'), 'role', ['slug'], unique=True)
+    op.create_table(
+        'role_permission',
+        sa.Column('role_id', sa.Uuid(), nullable=False),
+        sa.Column('permission_id', sa.Uuid(), nullable=False),
+        sa.ForeignKeyConstraint(['permission_id'], ['permission.id'], ondelete='CASCADE'),
+        sa.ForeignKeyConstraint(['role_id'], ['role.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('role_id', 'permission_id'),
+    )
+    op.add_column('user', sa.Column('role_id', sa.Uuid(), nullable=True))
+
+    bind = op.get_bind()
+
+    role_table = sa.table('role', sa.column('id', sa.Uuid()), sa.column('slug', sa.String()))
+    permission_table = sa.table(
+        'permission', sa.column('id', sa.Uuid()), sa.column('code', sa.String())
+    )
+    role_permission_table = sa.table(
+        'role_permission',
+        sa.column('role_id', sa.Uuid()),
+        sa.column('permission_id', sa.Uuid()),
+    )
+
+    role_ids = {
+        "admin": ADMIN_ROLE_ID,
+        "manager": MANAGER_ROLE_ID,
+        "member": MEMBER_ROLE_ID,
+    }
+    bind.execute(
+        role_table.insert(),
+        [{"id": role_id, "slug": slug} for slug, role_id in role_ids.items()],
+    )
+
+    permission_ids = {code: uuid.uuid4() for code in PERMISSION_CODES}
+    bind.execute(
+        permission_table.insert(),
+        [{"id": pid, "code": code} for code, pid in permission_ids.items()],
+    )
+
+    bind.execute(
+        role_permission_table.insert(),
+        [
+            {"role_id": role_ids[slug], "permission_id": permission_ids[code]}
+            for slug, codes in ROLE_PERMISSIONS.items()
+            for code in codes
+        ],
+    )
+
+    bind.execute(
+        sa.text('UPDATE "user" SET role_id = :role_id WHERE is_superuser IS TRUE'),
+        {"role_id": ADMIN_ROLE_ID},
+    )
+    bind.execute(
+        sa.text(
+            'UPDATE "user" SET role_id = :role_id '
+            'WHERE is_superuser IS NOT TRUE'
+        ),
+        {"role_id": MEMBER_ROLE_ID},
+    )
+
+    op.alter_column('user', 'role_id', nullable=False)
+    op.create_foreign_key(
+        'user_role_id_fkey', 'user', 'role', ['role_id'], ['id']
+    )
+    op.drop_column('user', 'is_superuser')
+
+
+def downgrade():
+    op.add_column(
+        'user',
+        sa.Column(
+            'is_superuser',
+            sa.BOOLEAN(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+
+    bind = op.get_bind()
+    bind.execute(
+        sa.text(
+            'UPDATE "user" SET is_superuser = true '
+            'WHERE role_id = (SELECT id FROM role WHERE slug = \'admin\')'
+        )
+    )
+    op.alter_column('user', 'is_superuser', server_default=None)
+
+    op.drop_constraint('user_role_id_fkey', 'user', type_='foreignkey')
+    op.drop_column('user', 'role_id')
+    op.drop_table('role_permission')
+    op.drop_index(op.f('ix_role_slug'), table_name='role')
+    op.drop_table('role')
+    op.drop_index(op.f('ix_permission_code'), table_name='permission')
+    op.drop_table('permission')
diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py
index 5f28ec692a..5833beccfa 100644
--- a/backend/app/api/deps.py
+++ b/backend/app/api/deps.py
@@ -1,4 +1,4 @@
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from typing import Annotated
 
 import jwt
@@ -8,7 +8,7 @@
 from pydantic import ValidationError
 from sqlmodel import Session
 
-from app.core import security
+from app.core import rbac, security
 from app.core.config import settings
 from app.core.db import engine
 from app.models import TokenPayload, User
@@ -49,9 +49,14 @@ def get_current_user(session: SessionDep, token: TokenDep) -> User:
 CurrentUser = Annotated[User, Depends(get_current_user)]
 
 
-def get_current_active_superuser(current_user: CurrentUser) -> User:
-    if not current_user.is_superuser:
-        raise HTTPException(
-            status_code=403, detail="The user doesn't have enough privileges"
-        )
-    return current_user
+def require_permission(code: str) -> Callable[[CurrentUser], User]:
+    # Factory, not a dependency itself: `Depends(require_permission("x"))` calls
+    # this to build the actual per-code dependency below.
+    def dependency(current_user: CurrentUser) -> User:
+        if not rbac.has_permission(current_user, code):
+            raise HTTPException(
+                status_code=403, detail="The user doesn't have enough privileges"
+            )
+        return current_user
+
+    return dependency
diff --git a/backend/app/api/main.py b/backend/app/api/main.py
index a42e5003ee..b5eaaadfa5 100644
--- a/backend/app/api/main.py
+++ b/backend/app/api/main.py
@@ -1,6 +1,6 @@
 from fastapi import APIRouter
 
-from app.api.routes import items, login, private, users, utils
+from app.api.routes import items, login, metrics, private, users, utils
 from app.core.config import settings
 
 api_router = APIRouter()
@@ -8,6 +8,7 @@
 api_router.include_router(users.router)
 api_router.include_router(utils.router)
 api_router.include_router(items.router)
+api_router.include_router(metrics.router)
 
 
 if settings.FASTAPI_ENV == "development":
diff --git a/backend/app/api/routes/items.py b/backend/app/api/routes/items.py
index f0eb30e4ce..df34afdf7c 100644
--- a/backend/app/api/routes/items.py
+++ b/backend/app/api/routes/items.py
@@ -5,6 +5,7 @@
 from sqlmodel import col, func, select
 
 from app.api.deps import CurrentUser, SessionDep
+from app.core import rbac
 from app.models import Item, ItemCreate, ItemPublic, ItemsPublic, ItemUpdate, Message
 
 router = APIRouter(prefix="/items", tags=["items"])
@@ -18,7 +19,7 @@ def read_items(
     Retrieve items.
     """
 
-    if current_user.is_superuser:
+    if rbac.has_permission(current_user, rbac.PERMISSION_SYSTEM_ADMIN):
         count_statement = select(func.count()).select_from(Item)
         count = session.exec(count_statement).one()
         statement = (
@@ -53,7 +54,9 @@ def read_item(session: SessionDep, current_user: CurrentUser, id: uuid.UUID) ->
     item = session.get(Item, id)
     if not item:
         raise HTTPException(status_code=404, detail="Item not found")
-    if not current_user.is_superuser and (item.owner_id != current_user.id):
+    if not rbac.has_permission(current_user, rbac.PERMISSION_SYSTEM_ADMIN) and (
+        item.owner_id != current_user.id
+    ):
         raise HTTPException(status_code=403, detail="Not enough permissions")
     return item
 
@@ -86,7 +89,9 @@ def update_item(
     item = session.get(Item, id)
     if not item:
         raise HTTPException(status_code=404, detail="Item not found")
-    if not current_user.is_superuser and (item.owner_id != current_user.id):
+    if not rbac.has_permission(current_user, rbac.PERMISSION_SYSTEM_ADMIN) and (
+        item.owner_id != current_user.id
+    ):
         raise HTTPException(status_code=403, detail="Not enough permissions")
     update_dict = item_in.model_dump(exclude_unset=True)
     item.sqlmodel_update(update_dict)
@@ -106,7 +111,9 @@ def delete_item(
     item = session.get(Item, id)
     if not item:
         raise HTTPException(status_code=404, detail="Item not found")
-    if not current_user.is_superuser and (item.owner_id != current_user.id):
+    if not rbac.has_permission(current_user, rbac.PERMISSION_SYSTEM_ADMIN) and (
+        item.owner_id != current_user.id
+    ):
         raise HTTPException(status_code=403, detail="Not enough permissions")
     session.delete(item)
     session.commit()
diff --git a/backend/app/api/routes/login.py b/backend/app/api/routes/login.py
index 58441e37e9..27083c781a 100644
--- a/backend/app/api/routes/login.py
+++ b/backend/app/api/routes/login.py
@@ -6,8 +6,8 @@
 from fastapi.security import OAuth2PasswordRequestForm
 
 from app import crud
-from app.api.deps import CurrentUser, SessionDep, get_current_active_superuser
-from app.core import security
+from app.api.deps import CurrentUser, SessionDep, require_permission
+from app.core import rbac, security
 from app.core.config import settings
 from app.models import Message, NewPassword, Token, UserPublic, UserUpdate
 from app.utils import (
@@ -99,7 +99,7 @@ def reset_password(session: SessionDep, body: NewPassword) -> Message:
 
 @router.post(
     "/password-recovery-html-content/{email}",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(require_permission(rbac.PERMISSION_SYSTEM_ADMIN))],
     response_class=HTMLResponse,
 )
 def recover_password_html_content(email: str, session: SessionDep) -> Any:
diff --git a/backend/app/api/routes/metrics.py b/backend/app/api/routes/metrics.py
new file mode 100644
index 0000000000..2dc1d5db37
--- /dev/null
+++ b/backend/app/api/routes/metrics.py
@@ -0,0 +1,22 @@
+from fastapi import APIRouter, Depends
+from sqlmodel import func, select
+
+from app.api.deps import SessionDep, require_permission
+from app.core import rbac
+from app.models import Item, MetricsPublic, User
+
+router = APIRouter(
+    prefix="/metrics",
+    tags=["metrics"],
+    dependencies=[Depends(require_permission(rbac.PERMISSION_METRICS_VIEW))],
+)
+
+
+@router.get("/")
+def read_metrics(session: SessionDep) -> MetricsPublic:
+    """
+    Basic usage metrics. A stub — not a real analytics pipeline.
+    """
+    user_count = session.exec(select(func.count()).select_from(User)).one()
+    item_count = session.exec(select(func.count()).select_from(Item)).one()
+    return MetricsPublic(user_count=user_count, item_count=item_count)
diff --git a/backend/app/api/routes/private.py b/backend/app/api/routes/private.py
index 9f33ef1900..c846b5278f 100644
--- a/backend/app/api/routes/private.py
+++ b/backend/app/api/routes/private.py
@@ -3,10 +3,10 @@
 from fastapi import APIRouter
 from pydantic import BaseModel
 
+from app import crud
 from app.api.deps import SessionDep
-from app.core.security import get_password_hash
 from app.models import (
-    User,
+    UserCreate,
     UserPublic,
 )
 
@@ -26,13 +26,9 @@ def create_user(user_in: PrivateUserCreate, session: SessionDep) -> Any:
     Create a new user.
     """
 
-    user = User(
+    user_create = UserCreate(
         email=user_in.email,
         full_name=user_in.full_name,
-        hashed_password=get_password_hash(user_in.password),
+        password=user_in.password,
     )
-
-    session.add(user)
-    session.commit()
-
-    return user
+    return crud.create_user(session=session, user_create=user_create)
diff --git a/backend/app/api/routes/users.py b/backend/app/api/routes/users.py
index 1748f58484..9943027bbc 100644
--- a/backend/app/api/routes/users.py
+++ b/backend/app/api/routes/users.py
@@ -8,8 +8,9 @@
 from app.api.deps import (
     CurrentUser,
     SessionDep,
-    get_current_active_superuser,
+    require_permission,
 )
+from app.core import rbac
 from app.core.config import settings
 from app.core.security import get_password_hash, verify_password
 from app.models import (
@@ -18,6 +19,7 @@
     UpdatePassword,
     User,
     UserCreate,
+    UserMePublic,
     UserPublic,
     UserRegister,
     UsersPublic,
@@ -31,7 +33,7 @@
 
 @router.get(
     "/",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(require_permission(rbac.PERMISSION_USERS_LIST))],
     response_model=UsersPublic,
 )
 def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
@@ -52,7 +54,9 @@ def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
 
 
 @router.post(
-    "/", dependencies=[Depends(get_current_active_superuser)], response_model=UserPublic
+    "/",
+    dependencies=[Depends(require_permission(rbac.PERMISSION_USERS_CREATE))],
+    response_model=UserPublic,
 )
 def create_user(*, session: SessionDep, user_in: UserCreate) -> Any:
     """
@@ -121,12 +125,15 @@ def update_password_me(
     return Message(message="Password updated successfully")
 
 
-@router.get("/me", response_model=UserPublic)
+@router.get("/me", response_model=UserMePublic)
 def read_user_me(current_user: CurrentUser) -> Any:
     """
     Get current user.
     """
-    return current_user
+    permissions = rbac.get_permission_codes(current_user)
+    return UserMePublic.model_validate(
+        current_user, update={"permissions": permissions}
+    )
 
 
 @router.delete("/me", response_model=Message)
@@ -134,9 +141,9 @@ def delete_user_me(session: SessionDep, current_user: CurrentUser) -> Any:
     """
     Delete own user.
     """
-    if current_user.is_superuser:
+    if rbac.has_permission(current_user, rbac.PERMISSION_SYSTEM_ADMIN):
         raise HTTPException(
-            status_code=403, detail="Super users are not allowed to delete themselves"
+            status_code=403, detail="Admins are not allowed to delete themselves"
         )
     session.delete(current_user)
     session.commit()
@@ -169,7 +176,7 @@ def read_user_by_id(
     user = session.get(User, user_id)
     if user == current_user:
         return user
-    if not current_user.is_superuser:
+    if not rbac.has_permission(current_user, rbac.PERMISSION_USERS_LIST):
         raise HTTPException(
             status_code=403,
             detail="The user doesn't have enough privileges",
@@ -181,7 +188,7 @@ def read_user_by_id(
 
 @router.patch(
     "/{user_id}",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(require_permission(rbac.PERMISSION_USERS_MANAGE))],
     response_model=UserPublic,
 )
 def update_user(
@@ -211,7 +218,10 @@ def update_user(
     return db_user
 
 
-@router.delete("/{user_id}", dependencies=[Depends(get_current_active_superuser)])
+@router.delete(
+    "/{user_id}",
+    dependencies=[Depends(require_permission(rbac.PERMISSION_USERS_MANAGE))],
+)
 def delete_user(
     session: SessionDep, current_user: CurrentUser, user_id: uuid.UUID
 ) -> Message:
@@ -223,7 +233,7 @@ def delete_user(
         raise HTTPException(status_code=404, detail="User not found")
     if user == current_user:
         raise HTTPException(
-            status_code=403, detail="Super users are not allowed to delete themselves"
+            status_code=403, detail="Admins are not allowed to delete themselves"
         )
     statement = delete(Item).where(col(Item.owner_id) == user_id)
     session.exec(statement)
diff --git a/backend/app/api/routes/utils.py b/backend/app/api/routes/utils.py
index fc093419b3..5faa64e20b 100644
--- a/backend/app/api/routes/utils.py
+++ b/backend/app/api/routes/utils.py
@@ -1,7 +1,8 @@
 from fastapi import APIRouter, Depends
 from pydantic.networks import EmailStr
 
-from app.api.deps import get_current_active_superuser
+from app.api.deps import require_permission
+from app.core import rbac
 from app.models import Message
 from app.utils import generate_test_email, send_email
 
@@ -10,7 +11,7 @@
 
 @router.post(
     "/test-email/",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(require_permission(rbac.PERMISSION_SYSTEM_ADMIN))],
     status_code=201,
 )
 def test_email(email_to: EmailStr) -> Message:
diff --git a/backend/app/core/db.py b/backend/app/core/db.py
index f19ac0d3bf..beede20ca1 100644
--- a/backend/app/core/db.py
+++ b/backend/app/core/db.py
@@ -1,8 +1,9 @@
 from sqlmodel import Session, create_engine, select
 
 from app import crud
+from app.core import rbac
 from app.core.config import settings
-from app.models import User, UserCreate
+from app.models import Permission, Role, User, UserCreate
 
 engine = create_engine(str(settings.DATABASE_URL))
 
@@ -12,6 +13,34 @@
 # for more details: https://github.com/fastapi/full-stack-fastapi-template/issues/28
 
 
+def _upsert_permissions(session: Session) -> dict[str, Permission]:
+    permissions: dict[str, Permission] = {}
+    for code in rbac.PERMISSION_CODES:
+        permission = session.exec(
+            select(Permission).where(Permission.code == code)
+        ).first()
+        if not permission:
+            permission = Permission(code=code)
+            session.add(permission)
+            session.flush()
+        permissions[code] = permission
+    return permissions
+
+
+def _upsert_roles(session: Session, permissions: dict[str, Permission]) -> None:
+    for slug in rbac.ROLE_SLUGS:
+        role = session.exec(select(Role).where(Role.slug == slug)).first()
+        if not role:
+            role = Role(slug=slug)
+            session.add(role)
+            session.flush()
+        existing_codes = {permission.code for permission in role.permissions}
+        for code in rbac.ROLE_PERMISSIONS[slug]:
+            if code not in existing_codes:
+                role.permissions.append(permissions[code])
+    session.commit()
+
+
 def init_db(session: Session) -> None:
     # Tables should be created with Alembic migrations
     # But if you don't want to use migrations, create
@@ -21,6 +50,9 @@ def init_db(session: Session) -> None:
     # This works because the models are already imported and registered from app.models
     # SQLModel.metadata.create_all(engine)
 
+    permissions = _upsert_permissions(session)
+    _upsert_roles(session, permissions)
+
     user = session.exec(
         select(User).where(User.email == settings.FIRST_SUPERUSER)
     ).first()
@@ -28,6 +60,6 @@ def init_db(session: Session) -> None:
         user_in = UserCreate(
             email=settings.FIRST_SUPERUSER,
             password=settings.FIRST_SUPERUSER_PASSWORD,
-            is_superuser=True,
+            role=rbac.ROLE_ADMIN,
         )
         user = crud.create_user(session=session, user_create=user_in)
diff --git a/backend/app/core/rbac.py b/backend/app/core/rbac.py
new file mode 100644
index 0000000000..246089d199
--- /dev/null
+++ b/backend/app/core/rbac.py
@@ -0,0 +1,45 @@
+from app.models import User
+
+# Role slugs. This is the single source of truth for what roles exist and
+# what they grant — see ROLE_PERMISSIONS below.
+ROLE_ADMIN = "admin"
+ROLE_MANAGER = "manager"
+ROLE_MEMBER = "member"
+
+ROLE_SLUGS = [ROLE_ADMIN, ROLE_MANAGER, ROLE_MEMBER]
+
+# Permission codes
+PERMISSION_USERS_LIST = "users:list"
+PERMISSION_USERS_CREATE = "users:create"
+PERMISSION_USERS_MANAGE = "users:manage"
+PERMISSION_METRICS_VIEW = "metrics:view"
+# Catch-all for the remaining admin-only surfaces (item access across all
+# owners, transactional-email test/preview endpoints) and the permission
+# that blocks self-deletion. Kept as one code rather than four narrow ones
+# because only `admin` has ever held any of them.
+PERMISSION_SYSTEM_ADMIN = "system:admin"
+
+PERMISSION_CODES = [
+    PERMISSION_USERS_LIST,
+    PERMISSION_USERS_CREATE,
+    PERMISSION_USERS_MANAGE,
+    PERMISSION_METRICS_VIEW,
+    PERMISSION_SYSTEM_ADMIN,
+]
+
+# Permission codes granted to each seeded role. Adding a role is one entry
+# here (plus a matching seed-data row); adding a permission is one constant
+# above plus wiring it into the roles that should have it here.
+ROLE_PERMISSIONS: dict[str, list[str]] = {
+    ROLE_ADMIN: PERMISSION_CODES,
+    ROLE_MANAGER: [PERMISSION_USERS_LIST, PERMISSION_METRICS_VIEW],
+    ROLE_MEMBER: [],
+}
+
+
+def get_permission_codes(user: User) -> list[str]:
+    return [permission.code for permission in user.role.permissions]
+
+
+def has_permission(user: User, code: str) -> bool:
+    return code in get_permission_codes(user)
diff --git a/backend/app/crud.py b/backend/app/crud.py
index a8ceba6444..af93e93959 100644
--- a/backend/app/crud.py
+++ b/backend/app/crud.py
@@ -3,13 +3,25 @@
 
 from sqlmodel import Session, select
 
+from app.core import rbac
 from app.core.security import get_password_hash, verify_password
-from app.models import Item, ItemCreate, User, UserCreate, UserUpdate
+from app.models import Item, ItemCreate, Role, User, UserCreate, UserUpdate
+
+
+def get_role_by_slug(*, session: Session, slug: str) -> Role:
+    role = session.exec(select(Role).where(Role.slug == slug)).first()
+    if role is None:
+        raise ValueError(f"Unknown role: {slug}")
+    return role
 
 
 def create_user(*, session: Session, user_create: UserCreate) -> User:
-    db_obj = User.model_validate(
-        user_create, update={"hashed_password": get_password_hash(user_create.password)}
+    role = get_role_by_slug(session=session, slug=user_create.role or rbac.ROLE_MEMBER)
+    user_data = user_create.model_dump(exclude={"password", "role"})
+    db_obj = User(
+        **user_data,
+        hashed_password=get_password_hash(user_create.password),
+        role_id=role.id,
     )
     session.add(db_obj)
     session.commit()
@@ -19,11 +31,13 @@ def create_user(*, session: Session, user_create: UserCreate) -> User:
 
 def update_user(*, session: Session, db_user: User, user_in: UserUpdate) -> Any:
     user_data = user_in.model_dump(exclude_unset=True)
-    extra_data = {}
+    extra_data: dict[str, Any] = {}
     if "password" in user_data:
-        password = user_data["password"]
-        hashed_password = get_password_hash(password)
-        extra_data["hashed_password"] = hashed_password
+        password = user_data.pop("password")
+        extra_data["hashed_password"] = get_password_hash(password)
+    if "role" in user_data:
+        role_slug = user_data.pop("role")
+        extra_data["role_id"] = get_role_by_slug(session=session, slug=role_slug).id
     db_user.sqlmodel_update(user_data, update=extra_data)
     session.add(db_user)
     session.commit()
diff --git a/backend/app/models.py b/backend/app/models.py
index dcedf9a2f5..a48cbec049 100644
--- a/backend/app/models.py
+++ b/backend/app/models.py
@@ -1,7 +1,8 @@
 import uuid
 from datetime import UTC, datetime
+from typing import Any
 
-from pydantic import EmailStr
+from pydantic import EmailStr, field_validator
 from sqlalchemy import DateTime
 from sqlmodel import Field, Relationship, SQLModel
 
@@ -10,17 +11,52 @@ def get_datetime_utc() -> datetime:
     return datetime.now(UTC)
 
 
+# Permission-role link table
+class RolePermissionLink(SQLModel, table=True):
+    __tablename__ = "role_permission"
+
+    role_id: uuid.UUID = Field(
+        foreign_key="role.id", primary_key=True, ondelete="CASCADE"
+    )
+    permission_id: uuid.UUID = Field(
+        foreign_key="permission.id", primary_key=True, ondelete="CASCADE"
+    )
+
+
+class PermissionBase(SQLModel):
+    code: str = Field(unique=True, index=True, max_length=64)
+
+
+class Permission(PermissionBase, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    roles: list[Role] = Relationship(
+        back_populates="permissions", link_model=RolePermissionLink
+    )
+
+
+class RoleBase(SQLModel):
+    slug: str = Field(unique=True, index=True, max_length=64)
+
+
+class Role(RoleBase, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    permissions: list[Permission] = Relationship(
+        back_populates="roles", link_model=RolePermissionLink
+    )
+    users: list[User] = Relationship(back_populates="role")
+
+
 # Shared properties
 class UserBase(SQLModel):
     email: EmailStr = Field(unique=True, index=True, max_length=255)
     is_active: bool = True
-    is_superuser: bool = False
     full_name: str | None = Field(default=None, max_length=255)
 
 
 # Properties to receive via API on creation
 class UserCreate(UserBase):
     password: str = Field(min_length=8, max_length=128)
+    role: str | None = Field(default=None, max_length=64)
 
 
 class UserRegister(SQLModel):
@@ -33,7 +69,7 @@ class UserRegister(SQLModel):
 class UserUpdate(SQLModel):
     email: EmailStr | None = Field(default=None, max_length=255)
     is_active: bool | None = None
-    is_superuser: bool | None = None
+    role: str | None = Field(default=None, max_length=64)
     full_name: str | None = Field(default=None, max_length=255)
     password: str | None = Field(default=None, min_length=8, max_length=128)
 
@@ -56,6 +92,8 @@ class User(UserBase, table=True):
         default_factory=get_datetime_utc,
         sa_type=DateTime(timezone=True),  # type: ignore
     )
+    role_id: uuid.UUID = Field(foreign_key="role.id", nullable=False)
+    role: Role = Relationship(back_populates="users")
     items: list[Item] = Relationship(back_populates="owner", cascade_delete=True)
 
 
@@ -63,6 +101,17 @@ class User(UserBase, table=True):
 class UserPublic(UserBase):
     id: uuid.UUID
     created_at: datetime | None = None
+    role: str
+
+    @field_validator("role", mode="before")
+    @classmethod
+    def _role_slug(cls, value: Any) -> Any:
+        slug = getattr(value, "slug", None)
+        return slug if slug is not None else value
+
+
+class UserMePublic(UserPublic):
+    permissions: list[str]
 
 
 class UsersPublic(SQLModel):
@@ -112,6 +161,11 @@ class ItemsPublic(SQLModel):
     count: int
 
 
+class MetricsPublic(SQLModel):
+    user_count: int
+    item_count: int
+
+
 # Generic message
 class Message(SQLModel):
     message: str
diff --git a/backend/tests/api/routes/test_login.py b/backend/tests/api/routes/test_login.py
index 96677a25f6..456ddaf745 100644
--- a/backend/tests/api/routes/test_login.py
+++ b/backend/tests/api/routes/test_login.py
@@ -4,6 +4,7 @@
 from pwdlib.hashers.bcrypt import BcryptHasher
 from sqlmodel import Session
 
+from app import crud
 from app.core.config import settings
 from app.core.security import get_password_hash, verify_password
 from app.crud import create_user
@@ -89,7 +90,6 @@ def test_reset_password(client: TestClient, db: Session) -> None:
         full_name="Test User",
         password=password,
         is_active=True,
-        is_superuser=False,
     )
     user = create_user(session=db, user_create=user_create)
     token = generate_password_reset_token(email=email)
@@ -138,7 +138,10 @@ def test_login_with_bcrypt_password_upgrades_to_argon2(
     bcrypt_hash = bcrypt_hasher.hash(password)
     assert bcrypt_hash.startswith("$2")  # bcrypt hashes start with $2
 
-    user = User(email=email, hashed_password=bcrypt_hash, is_active=True)
+    member_role = crud.get_role_by_slug(session=db, slug="member")
+    user = User(
+        email=email, hashed_password=bcrypt_hash, is_active=True, role_id=member_role.id
+    )
     db.add(user)
     db.commit()
     db.refresh(user)
@@ -172,7 +175,10 @@ def test_login_with_argon2_password_keeps_hash(client: TestClient, db: Session)
     assert argon2_hash.startswith("$argon2")
 
     # Create user with argon2 hash
-    user = User(email=email, hashed_password=argon2_hash, is_active=True)
+    member_role = crud.get_role_by_slug(session=db, slug="member")
+    user = User(
+        email=email, hashed_password=argon2_hash, is_active=True, role_id=member_role.id
+    )
     db.add(user)
     db.commit()
     db.refresh(user)
diff --git a/backend/tests/api/routes/test_rbac.py b/backend/tests/api/routes/test_rbac.py
new file mode 100644
index 0000000000..93e2d05723
--- /dev/null
+++ b/backend/tests/api/routes/test_rbac.py
@@ -0,0 +1,80 @@
+"""Focused coverage of the role/permission matrix documented in docs/AUTHORIZATION.md.
+
+One allowed and one denied case per permission, plus the privilege-escalation
+check on self-update — not an exhaustive role x permission grid.
+"""
+
+from fastapi.testclient import TestClient
+from sqlmodel import Session, select
+
+from app.core.config import settings
+from app.models import User
+from tests.utils.user import create_random_user
+
+
+def test_manager_can_list_users(
+    client: TestClient, manager_user_token_headers: dict[str, str]
+) -> None:
+    r = client.get(f"{settings.API_V1_STR}/users/", headers=manager_user_token_headers)
+    assert r.status_code == 200
+
+
+def test_member_cannot_list_users(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    r = client.get(f"{settings.API_V1_STR}/users/", headers=normal_user_token_headers)
+    assert r.status_code == 403
+
+
+def test_manager_cannot_create_user(
+    client: TestClient, manager_user_token_headers: dict[str, str]
+) -> None:
+    data = {"email": "new-user@example.com", "password": "password123"}
+    r = client.post(
+        f"{settings.API_V1_STR}/users/", headers=manager_user_token_headers, json=data
+    )
+    assert r.status_code == 403
+
+
+def test_manager_can_view_metrics(
+    client: TestClient, manager_user_token_headers: dict[str, str]
+) -> None:
+    r = client.get(
+        f"{settings.API_V1_STR}/metrics/", headers=manager_user_token_headers
+    )
+    assert r.status_code == 200
+    assert "user_count" in r.json()
+
+
+def test_member_cannot_view_metrics(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    r = client.get(f"{settings.API_V1_STR}/metrics/", headers=normal_user_token_headers)
+    assert r.status_code == 403
+
+
+def test_manager_cannot_update_another_user(
+    client: TestClient, manager_user_token_headers: dict[str, str], db: Session
+) -> None:
+    other_user = create_random_user(db)
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/{other_user.id}",
+        headers=manager_user_token_headers,
+        json={"full_name": "Renamed"},
+    )
+    assert r.status_code == 403
+
+
+def test_member_cannot_escalate_role_via_self_update(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me",
+        headers=normal_user_token_headers,
+        json={"full_name": "Still Member", "role": "admin"},
+    )
+    assert r.status_code == 200
+
+    user = db.exec(select(User).where(User.email == settings.EMAIL_TEST_USER)).first()
+    assert user
+    assert user.role.slug == "member"
diff --git a/backend/tests/api/routes/test_users.py b/backend/tests/api/routes/test_users.py
index 9c4cdd5991..7589360b57 100644
--- a/backend/tests/api/routes/test_users.py
+++ b/backend/tests/api/routes/test_users.py
@@ -19,7 +19,14 @@ def test_get_users_superuser_me(
     current_user = r.json()
     assert current_user
     assert current_user["is_active"] is True
-    assert current_user["is_superuser"]
+    assert current_user["role"] == "admin"
+    assert set(current_user["permissions"]) == {
+        "users:list",
+        "users:create",
+        "users:manage",
+        "metrics:view",
+        "system:admin",
+    }
     assert current_user["email"] == settings.FIRST_SUPERUSER
 
 
@@ -30,7 +37,8 @@ def test_get_users_normal_user_me(
     current_user = r.json()
     assert current_user
     assert current_user["is_active"] is True
-    assert current_user["is_superuser"] is False
+    assert current_user["role"] == "member"
+    assert current_user["permissions"] == []
     assert current_user["email"] == settings.EMAIL_TEST_USER
 
 
@@ -457,7 +465,7 @@ def test_delete_user_me_as_superuser(
     )
     assert r.status_code == 403
     response = r.json()
-    assert response["detail"] == "Super users are not allowed to delete themselves"
+    assert response["detail"] == "Admins are not allowed to delete themselves"
 
 
 def test_delete_user_super_user(
@@ -502,7 +510,7 @@ def test_delete_user_current_super_user_error(
         headers=superuser_token_headers,
     )
     assert r.status_code == 403
-    assert r.json()["detail"] == "Super users are not allowed to delete themselves"
+    assert r.json()["detail"] == "Admins are not allowed to delete themselves"
 
 
 def test_delete_user_without_privileges(
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 7cdabf3c45..65259ca93f 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -40,3 +40,10 @@ def normal_user_token_headers(client: TestClient, db: Session) -> dict[str, str]
     return authentication_token_from_email(
         client=client, email=settings.EMAIL_TEST_USER, db=db
     )
+
+
+@pytest.fixture(scope="module")
+def manager_user_token_headers(client: TestClient, db: Session) -> dict[str, str]:
+    return authentication_token_from_email(
+        client=client, email="manager-fixture@example.com", db=db, role="manager"
+    )
diff --git a/backend/tests/crud/test_user.py b/backend/tests/crud/test_user.py
index 3db77ef624..6b6bb222d6 100644
--- a/backend/tests/crud/test_user.py
+++ b/backend/tests/crud/test_user.py
@@ -50,26 +50,26 @@ def test_check_if_user_is_active_inactive(db: Session) -> None:
     assert user.is_active is False
 
 
-def test_check_if_user_is_superuser(db: Session) -> None:
+def test_create_user_with_role(db: Session) -> None:
     email = random_email()
     password = random_lower_string()
-    user_in = UserCreate(email=email, password=password, is_superuser=True)
+    user_in = UserCreate(email=email, password=password, role="admin")
     user = crud.create_user(session=db, user_create=user_in)
-    assert user.is_superuser is True
+    assert user.role.slug == "admin"
 
 
-def test_check_if_user_is_superuser_normal_user(db: Session) -> None:
+def test_create_user_default_role(db: Session) -> None:
     username = random_email()
     password = random_lower_string()
     user_in = UserCreate(email=username, password=password)
     user = crud.create_user(session=db, user_create=user_in)
-    assert user.is_superuser is False
+    assert user.role.slug == "member"
 
 
 def test_get_user(db: Session) -> None:
     password = random_lower_string()
     username = random_email()
-    user_in = UserCreate(email=username, password=password, is_superuser=True)
+    user_in = UserCreate(email=username, password=password, role="admin")
     user = crud.create_user(session=db, user_create=user_in)
     user_2 = db.get(User, user.id)
     assert user_2
@@ -80,10 +80,10 @@ def test_get_user(db: Session) -> None:
 def test_update_user(db: Session) -> None:
     password = random_lower_string()
     email = random_email()
-    user_in = UserCreate(email=email, password=password, is_superuser=True)
+    user_in = UserCreate(email=email, password=password, role="admin")
     user = crud.create_user(session=db, user_create=user_in)
     new_password = random_lower_string()
-    user_in_update = UserUpdate(password=new_password, is_superuser=True)
+    user_in_update = UserUpdate(password=new_password, role="admin")
     if user.id is not None:
         crud.update_user(session=db, db_user=user, user_in=user_in_update)
     user_2 = db.get(User, user.id)
@@ -104,7 +104,8 @@ def test_authenticate_user_with_bcrypt_upgrades_to_argon2(db: Session) -> None:
     assert bcrypt_hash.startswith("$2")  # bcrypt hashes start with $2
 
     # Create user with bcrypt hash directly in the database
-    user = User(email=email, hashed_password=bcrypt_hash)
+    member_role = crud.get_role_by_slug(session=db, slug="member")
+    user = User(email=email, hashed_password=bcrypt_hash, role_id=member_role.id)
     db.add(user)
     db.commit()
     db.refresh(user)
diff --git a/backend/tests/utils/user.py b/backend/tests/utils/user.py
index 5867431ed8..75e4878148 100644
--- a/backend/tests/utils/user.py
+++ b/backend/tests/utils/user.py
@@ -28,17 +28,18 @@ def create_random_user(db: Session) -> User:
 
 
 def authentication_token_from_email(
-    *, client: TestClient, email: str, db: Session
+    *, client: TestClient, email: str, db: Session, role: str | None = None
 ) -> dict[str, str]:
     """
     Return a valid token for the user with given email.
 
-    If the user doesn't exist it is created first.
+    If the user doesn't exist it is created first, with the given role
+    (defaults to `member`).
     """
     password = random_lower_string()
     user = crud.get_user_by_email(session=db, email=email)
     if not user:
-        user_in_create = UserCreate(email=email, password=password)
+        user_in_create = UserCreate(email=email, password=password, role=role)
         user = crud.create_user(session=db, user_create=user_in_create)
     else:
         user_in_update = UserUpdate(password=password)
diff --git a/docs/AUTHORIZATION.md b/docs/AUTHORIZATION.md
new file mode 100644
index 0000000000..48de5f4c33
--- /dev/null
+++ b/docs/AUTHORIZATION.md
@@ -0,0 +1,91 @@
+# Authorization
+
+This project uses role-based access control (RBAC): every user has exactly one role, and each role grants a fixed set of permission codes. Routes and UI check permission codes, never role names.
+
+## Permission matrix
+
+| Action                          | admin | manager | member |
+|----------------------------------|:-----:|:-------:|:------:|
+| List all users                   |   ✓   |    ✓    |   ✗    |
+| Create a user                    |   ✓   |    ✗    |   ✗    |
+| View metrics/insights            |   ✓   |    ✓    |   ✗    |
+| View / update **own** profile    |   ✓   |    ✓    |   ✓    |
+| Update / delete **any** profile  |   ✓   |    ✗    |   ✗    |
+| Access items you don't own; test-email; password-recovery preview; self-delete blocked | ✓ | ✗ | ✗ |
+
+The five underlying permission codes are `users:list`, `users:create`, `users:manage`, `metrics:view`, and `system:admin` — the last one is a single admin-only catch-all covering the bottom row (item access across owners, transactional-email endpoints, and the rule that blocks an admin from deleting their own account). Viewing and updating your own profile needs no permission at all; it's the baseline for any authenticated, active user regardless of role.
+
+## How it works
+
+**Backend.** Authorization checks live in one FastAPI dependency, `require_permission(code)` (`backend/app/api/deps.py`), applied per-route via `dependencies=[Depends(require_permission(...))]`. It's a dependency *factory* — calling it with a permission code returns the actual dependency FastAPI runs. The one exception is item ownership, which stays inline in `app/api/routes/items.py` as a fallback (`owner_id == current_user.id`) because it's data-scoped, not role-scoped. There is no middleware and no decorator — every protected route says explicitly, in one line, which permission it needs.
+
+**Data model.** Roles and permissions are database tables (`role`, `permission`, `role_permission`), linked from `user.role_id`. The permission codes themselves and the role→permission grants are defined once, as plain Python constants, in `backend/app/core/rbac.py` — that file is the single source of truth. `init_db` (`backend/app/core/db.py`) upserts this seed data on every startup, so the roles and grants in the database always match the constants in code. Adding a new role is one entry in the seed data plus one line in `rbac.py`'s `ROLE_PERMISSIONS` mapping; adding a new permission is one constant plus wiring it into the roles and routes that need it — neither requires touching every route.
+
+**Frontend.** The frontend never re-derives permissions from a role name. `GET /users/me` returns the current user's role slug and their full list of permission codes; the frontend stores that on the authenticated user object and checks it with one helper, `hasPermission(user, code)` (`frontend/src/utils.ts`), mirrored against a `PERMISSIONS` constants object with the same five codes. Every gated nav item, route guard, and form control calls that helper — never `user.role === "..."`. Route guards that fail redirect to a shared `/forbidden` page (`AccessDenied` component) rather than silently bouncing to `/` or showing a blank screen, so a user who follows a stale link or bookmark gets an explicit, friendly explanation instead of a mystery.
+
+## Setup
+
+Requirements: [Docker](https://www.docker.com/), [uv](https://docs.astral.sh/uv/), [Bun](https://bun.sh/). See the root [`development.md`](../development.md) for the full local-dev workflow; the RBAC-relevant steps are below.
+
+1. Start Postgres and Mailpit from the project root:
+
+   ```bash
+   docker compose up -d db mailpit
+   ```
+
+2. From `backend/`, install dependencies, run migrations, and seed the database (this also creates the first admin — see below):
+
+   ```bash
+   uv sync
+   uv run bash scripts/prestart.sh
+   uv run fastapi dev
+   ```
+
+3. From the project root, install and start the frontend:
+
+   ```bash
+   bun install
+   bun run dev
+   ```
+
+   Frontend: <http://localhost:5173>. Backend: <http://localhost:8000> (docs at `/docs`).
+
+### Seeding an admin and a non-admin account
+
+`scripts/prestart.sh` already seeds the `admin`, `manager`, and `member` roles with their permission grants, and creates one `admin` account from the `FIRST_SUPERUSER` / `FIRST_SUPERUSER_PASSWORD` values in `.env` (defaults: `admin@example.com` / `changethis`).
+
+To get a non-admin account for manual testing, either self-register through the UI or `POST /api/v1/users/signup` (always creates a `member`), or have an existing admin create one with a specific role — e.g. from `backend/`:
+
+```console
+$ uv run python -c "
+from sqlmodel import Session
+from app.core.db import engine
+from app.models import UserCreate
+from app import crud
+
+with Session(engine) as session:
+    crud.create_user(session=session, user_create=UserCreate(
+        email='manager@example.com', password='password123', role='manager',
+    ))
+"
+```
+
+(`role` accepts `admin`, `manager`, or `member`; omit it to get the `member` default.)
+
+## Running tests
+
+Backend (from `backend/`):
+
+```bash
+uv run bash scripts/test.sh
+```
+
+Frontend/Playwright (from `frontend/`, requires the stack running):
+
+```bash
+bunx playwright test
+```
+
+## Migrations
+
+Standard Alembic workflow — see [`backend/README.md`](../backend/README.md#migrations). The RBAC schema (roles, permissions, `user.role_id`) is introduced in `backend/app/alembic/versions/2d1ae9889b29_add_rbac_roles_and_permissions.py`, which also seeds the roles/permissions and backfills existing users' roles.
diff --git a/frontend/src/client/index.ts b/frontend/src/client/index.ts
index f4fdf30796..ecf48c55ea 100644
--- a/frontend/src/client/index.ts
+++ b/frontend/src/client/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-export { ItemsService, LoginService, type Options, PrivateService, UsersService, UtilsService } from './sdk.gen';
-export type { Body_login_login_access_token, ClientOptions, HTTPValidationError, ItemCreate, ItemPublic, itemsCreateItemData, itemsCreateItemError, itemsCreateItemErrors, itemsCreateItemResponse, itemsCreateItemResponses, itemsDeleteItemData, itemsDeleteItemError, itemsDeleteItemErrors, itemsDeleteItemResponse, itemsDeleteItemResponses, ItemsPublic, itemsReadItemData, itemsReadItemError, itemsReadItemErrors, itemsReadItemResponse, itemsReadItemResponses, itemsReadItemsData, itemsReadItemsError, itemsReadItemsErrors, itemsReadItemsResponse, itemsReadItemsResponses, itemsUpdateItemData, itemsUpdateItemError, itemsUpdateItemErrors, itemsUpdateItemResponse, itemsUpdateItemResponses, ItemUpdate, loginLoginAccessTokenData, loginLoginAccessTokenError, loginLoginAccessTokenErrors, loginLoginAccessTokenResponse, loginLoginAccessTokenResponses, loginRecoverPasswordData, loginRecoverPasswordError, loginRecoverPasswordErrors, loginRecoverPasswordHtmlContentData, loginRecoverPasswordHtmlContentError, loginRecoverPasswordHtmlContentErrors, loginRecoverPasswordHtmlContentResponse, loginRecoverPasswordHtmlContentResponses, loginRecoverPasswordResponse, loginRecoverPasswordResponses, loginResetPasswordData, loginResetPasswordError, loginResetPasswordErrors, loginResetPasswordResponse, loginResetPasswordResponses, loginTestTokenData, loginTestTokenResponse, loginTestTokenResponses, Message, NewPassword, privateCreateUserData, privateCreateUserError, privateCreateUserErrors, privateCreateUserResponse, privateCreateUserResponses, PrivateUserCreate, Token, UpdatePassword, UserCreate, UserPublic, UserRegister, usersCreateUserData, usersCreateUserError, usersCreateUserErrors, usersCreateUserResponse, usersCreateUserResponses, usersDeleteUserData, usersDeleteUserError, usersDeleteUserErrors, usersDeleteUserMeData, usersDeleteUserMeResponse, usersDeleteUserMeResponses, usersDeleteUserResponse, usersDeleteUserResponses, UsersPublic, usersReadUserByIdData, usersReadUserByIdError, usersReadUserByIdErrors, usersReadUserByIdResponse, usersReadUserByIdResponses, usersReadUserMeData, usersReadUserMeResponse, usersReadUserMeResponses, usersReadUsersData, usersReadUsersError, usersReadUsersErrors, usersReadUsersResponse, usersReadUsersResponses, usersRegisterUserData, usersRegisterUserError, usersRegisterUserErrors, usersRegisterUserResponse, usersRegisterUserResponses, usersUpdatePasswordMeData, usersUpdatePasswordMeError, usersUpdatePasswordMeErrors, usersUpdatePasswordMeResponse, usersUpdatePasswordMeResponses, usersUpdateUserData, usersUpdateUserError, usersUpdateUserErrors, usersUpdateUserMeData, usersUpdateUserMeError, usersUpdateUserMeErrors, usersUpdateUserMeResponse, usersUpdateUserMeResponses, usersUpdateUserResponse, usersUpdateUserResponses, UserUpdate, UserUpdateMe, utilsHealthCheckData, utilsHealthCheckResponse, utilsHealthCheckResponses, utilsTestEmailData, utilsTestEmailError, utilsTestEmailErrors, utilsTestEmailResponse, utilsTestEmailResponses, ValidationError } from './types.gen';
+export { ItemsService, LoginService, MetricsService, type Options, PrivateService, UsersService, UtilsService } from './sdk.gen';
+export type { Body_login_login_access_token, ClientOptions, HTTPValidationError, ItemCreate, ItemPublic, itemsCreateItemData, itemsCreateItemError, itemsCreateItemErrors, itemsCreateItemResponse, itemsCreateItemResponses, itemsDeleteItemData, itemsDeleteItemError, itemsDeleteItemErrors, itemsDeleteItemResponse, itemsDeleteItemResponses, ItemsPublic, itemsReadItemData, itemsReadItemError, itemsReadItemErrors, itemsReadItemResponse, itemsReadItemResponses, itemsReadItemsData, itemsReadItemsError, itemsReadItemsErrors, itemsReadItemsResponse, itemsReadItemsResponses, itemsUpdateItemData, itemsUpdateItemError, itemsUpdateItemErrors, itemsUpdateItemResponse, itemsUpdateItemResponses, ItemUpdate, loginLoginAccessTokenData, loginLoginAccessTokenError, loginLoginAccessTokenErrors, loginLoginAccessTokenResponse, loginLoginAccessTokenResponses, loginRecoverPasswordData, loginRecoverPasswordError, loginRecoverPasswordErrors, loginRecoverPasswordHtmlContentData, loginRecoverPasswordHtmlContentError, loginRecoverPasswordHtmlContentErrors, loginRecoverPasswordHtmlContentResponse, loginRecoverPasswordHtmlContentResponses, loginRecoverPasswordResponse, loginRecoverPasswordResponses, loginResetPasswordData, loginResetPasswordError, loginResetPasswordErrors, loginResetPasswordResponse, loginResetPasswordResponses, loginTestTokenData, loginTestTokenResponse, loginTestTokenResponses, Message, MetricsPublic, metricsReadMetricsData, metricsReadMetricsResponse, metricsReadMetricsResponses, NewPassword, privateCreateUserData, privateCreateUserError, privateCreateUserErrors, privateCreateUserResponse, privateCreateUserResponses, PrivateUserCreate, Token, UpdatePassword, UserCreate, UserMePublic, UserPublic, UserRegister, usersCreateUserData, usersCreateUserError, usersCreateUserErrors, usersCreateUserResponse, usersCreateUserResponses, usersDeleteUserData, usersDeleteUserError, usersDeleteUserErrors, usersDeleteUserMeData, usersDeleteUserMeResponse, usersDeleteUserMeResponses, usersDeleteUserResponse, usersDeleteUserResponses, UsersPublic, usersReadUserByIdData, usersReadUserByIdError, usersReadUserByIdErrors, usersReadUserByIdResponse, usersReadUserByIdResponses, usersReadUserMeData, usersReadUserMeResponse, usersReadUserMeResponses, usersReadUsersData, usersReadUsersError, usersReadUsersErrors, usersReadUsersResponse, usersReadUsersResponses, usersRegisterUserData, usersRegisterUserError, usersRegisterUserErrors, usersRegisterUserResponse, usersRegisterUserResponses, usersUpdatePasswordMeData, usersUpdatePasswordMeError, usersUpdatePasswordMeErrors, usersUpdatePasswordMeResponse, usersUpdatePasswordMeResponses, usersUpdateUserData, usersUpdateUserError, usersUpdateUserErrors, usersUpdateUserMeData, usersUpdateUserMeError, usersUpdateUserMeErrors, usersUpdateUserMeResponse, usersUpdateUserMeResponses, usersUpdateUserResponse, usersUpdateUserResponses, UserUpdate, UserUpdateMe, utilsHealthCheckData, utilsHealthCheckResponse, utilsHealthCheckResponses, utilsTestEmailData, utilsTestEmailError, utilsTestEmailErrors, utilsTestEmailResponse, utilsTestEmailResponses, ValidationError } from './types.gen';
diff --git a/frontend/src/client/sdk.gen.ts b/frontend/src/client/sdk.gen.ts
index b1dd2cf1d5..00835f3ddb 100644
--- a/frontend/src/client/sdk.gen.ts
+++ b/frontend/src/client/sdk.gen.ts
@@ -2,7 +2,7 @@
 
 import { type Client, type Options as Options2, type TDataShape, urlSearchParamsBodySerializer } from './client';
 import { client } from './client.gen';
-import type { itemsCreateItemData, itemsCreateItemErrors, itemsCreateItemResponses, itemsDeleteItemData, itemsDeleteItemErrors, itemsDeleteItemResponses, itemsReadItemData, itemsReadItemErrors, itemsReadItemResponses, itemsReadItemsData, itemsReadItemsErrors, itemsReadItemsResponses, itemsUpdateItemData, itemsUpdateItemErrors, itemsUpdateItemResponses, loginLoginAccessTokenData, loginLoginAccessTokenErrors, loginLoginAccessTokenResponses, loginRecoverPasswordData, loginRecoverPasswordErrors, loginRecoverPasswordHtmlContentData, loginRecoverPasswordHtmlContentErrors, loginRecoverPasswordHtmlContentResponses, loginRecoverPasswordResponses, loginResetPasswordData, loginResetPasswordErrors, loginResetPasswordResponses, loginTestTokenData, loginTestTokenResponses, privateCreateUserData, privateCreateUserErrors, privateCreateUserResponses, usersCreateUserData, usersCreateUserErrors, usersCreateUserResponses, usersDeleteUserData, usersDeleteUserErrors, usersDeleteUserMeData, usersDeleteUserMeResponses, usersDeleteUserResponses, usersReadUserByIdData, usersReadUserByIdErrors, usersReadUserByIdResponses, usersReadUserMeData, usersReadUserMeResponses, usersReadUsersData, usersReadUsersErrors, usersReadUsersResponses, usersRegisterUserData, usersRegisterUserErrors, usersRegisterUserResponses, usersUpdatePasswordMeData, usersUpdatePasswordMeErrors, usersUpdatePasswordMeResponses, usersUpdateUserData, usersUpdateUserErrors, usersUpdateUserMeData, usersUpdateUserMeErrors, usersUpdateUserMeResponses, usersUpdateUserResponses, utilsHealthCheckData, utilsHealthCheckResponses, utilsTestEmailData, utilsTestEmailErrors, utilsTestEmailResponses } from './types.gen';
+import type { itemsCreateItemData, itemsCreateItemErrors, itemsCreateItemResponses, itemsDeleteItemData, itemsDeleteItemErrors, itemsDeleteItemResponses, itemsReadItemData, itemsReadItemErrors, itemsReadItemResponses, itemsReadItemsData, itemsReadItemsErrors, itemsReadItemsResponses, itemsUpdateItemData, itemsUpdateItemErrors, itemsUpdateItemResponses, loginLoginAccessTokenData, loginLoginAccessTokenErrors, loginLoginAccessTokenResponses, loginRecoverPasswordData, loginRecoverPasswordErrors, loginRecoverPasswordHtmlContentData, loginRecoverPasswordHtmlContentErrors, loginRecoverPasswordHtmlContentResponses, loginRecoverPasswordResponses, loginResetPasswordData, loginResetPasswordErrors, loginResetPasswordResponses, loginTestTokenData, loginTestTokenResponses, metricsReadMetricsData, metricsReadMetricsResponses, privateCreateUserData, privateCreateUserErrors, privateCreateUserResponses, usersCreateUserData, usersCreateUserErrors, usersCreateUserResponses, usersDeleteUserData, usersDeleteUserErrors, usersDeleteUserMeData, usersDeleteUserMeResponses, usersDeleteUserResponses, usersReadUserByIdData, usersReadUserByIdErrors, usersReadUserByIdResponses, usersReadUserMeData, usersReadUserMeResponses, usersReadUsersData, usersReadUsersErrors, usersReadUsersResponses, usersRegisterUserData, usersRegisterUserErrors, usersRegisterUserResponses, usersUpdatePasswordMeData, usersUpdatePasswordMeErrors, usersUpdatePasswordMeResponses, usersUpdateUserData, usersUpdateUserErrors, usersUpdateUserMeData, usersUpdateUserMeErrors, usersUpdateUserMeResponses, usersUpdateUserResponses, utilsHealthCheckData, utilsHealthCheckResponses, utilsTestEmailData, utilsTestEmailErrors, utilsTestEmailResponses } from './types.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
     /**
@@ -364,6 +364,22 @@ export class ItemsService {
     }
 }
 
+export class MetricsService {
+    /**
+     * Read Metrics
+     *
+     * Basic usage metrics. A stub — not a real analytics pipeline.
+     */
+    public static readMetrics<ThrowOnError extends boolean = true>(options?: Options<metricsReadMetricsData, ThrowOnError>) {
+        return (options?.client ?? client).get<metricsReadMetricsResponses, unknown, ThrowOnError>({
+            responseType: 'json',
+            security: [{ scheme: 'bearer', type: 'http' }],
+            url: '/api/v1/metrics/',
+            ...options
+        });
+    }
+}
+
 export class PrivateService {
     /**
      * Create User
diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts
index 6252d88c2f..74b227abb0 100644
--- a/frontend/src/client/types.gen.ts
+++ b/frontend/src/client/types.gen.ts
@@ -122,6 +122,20 @@ export type Message = {
     message: string;
 };
 
+/**
+ * MetricsPublic
+ */
+export type MetricsPublic = {
+    /**
+     * User Count
+     */
+    user_count: number;
+    /**
+     * Item Count
+     */
+    item_count: number;
+};
+
 /**
  * NewPassword
  */
@@ -198,10 +212,6 @@ export type UserCreate = {
      * Is Active
      */
     is_active?: boolean;
-    /**
-     * Is Superuser
-     */
-    is_superuser?: boolean;
     /**
      * Full Name
      */
@@ -210,12 +220,16 @@ export type UserCreate = {
      * Password
      */
     password: string;
+    /**
+     * Role
+     */
+    role?: string | null;
 };
 
 /**
- * UserPublic
+ * UserMePublic
  */
-export type UserPublic = {
+export type UserMePublic = {
     /**
      * Email
      */
@@ -225,9 +239,39 @@ export type UserPublic = {
      */
     is_active?: boolean;
     /**
-     * Is Superuser
+     * Full Name
+     */
+    full_name?: string | null;
+    /**
+     * Id
+     */
+    id: string;
+    /**
+     * Created At
+     */
+    created_at?: string | null;
+    /**
+     * Role
+     */
+    role: string;
+    /**
+     * Permissions
      */
-    is_superuser?: boolean;
+    permissions: Array<string>;
+};
+
+/**
+ * UserPublic
+ */
+export type UserPublic = {
+    /**
+     * Email
+     */
+    email: string;
+    /**
+     * Is Active
+     */
+    is_active?: boolean;
     /**
      * Full Name
      */
@@ -240,6 +284,10 @@ export type UserPublic = {
      * Created At
      */
     created_at?: string | null;
+    /**
+     * Role
+     */
+    role: string;
 };
 
 /**
@@ -273,9 +321,9 @@ export type UserUpdate = {
      */
     is_active?: boolean | null;
     /**
-     * Is Superuser
+     * Role
      */
-    is_superuser?: boolean | null;
+    role?: string | null;
     /**
      * Full Name
      */
@@ -554,7 +602,7 @@ export type usersReadUserMeResponses = {
     /**
      * Successful Response
      */
-    200: UserPublic;
+    200: UserMePublic;
 };
 
 export type usersReadUserMeResponse = usersReadUserMeResponses[keyof usersReadUserMeResponses];
@@ -921,6 +969,22 @@ export type itemsUpdateItemResponses = {
 
 export type itemsUpdateItemResponse = itemsUpdateItemResponses[keyof itemsUpdateItemResponses];
 
+export type metricsReadMetricsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v1/metrics/';
+};
+
+export type metricsReadMetricsResponses = {
+    /**
+     * Successful Response
+     */
+    200: MetricsPublic;
+};
+
+export type metricsReadMetricsResponse = metricsReadMetricsResponses[keyof metricsReadMetricsResponses];
+
 export type privateCreateUserData = {
     body: PrivateUserCreate;
     path?: never;
diff --git a/frontend/src/components/Admin/AddUser.tsx b/frontend/src/components/Admin/AddUser.tsx
index 0cb83b2d46..2a46fa7cb1 100644
--- a/frontend/src/components/Admin/AddUser.tsx
+++ b/frontend/src/components/Admin/AddUser.tsx
@@ -28,8 +28,16 @@ import {
 } from "@/components/ui/form"
 import { Input } from "@/components/ui/input"
 import { LoadingButton } from "@/components/ui/loading-button"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
 import useCustomToast from "@/hooks/useCustomToast"
 import { handleError } from "@/utils"
+import { ROLE_OPTIONS } from "./roleOptions"
 
 const formSchema = z
   .object({
@@ -42,7 +50,7 @@ const formSchema = z
     confirm_password: z
       .string()
       .min(1, { message: "Please confirm your password" }),
-    is_superuser: z.boolean(),
+    role: z.enum(["member", "manager", "admin"]),
     is_active: z.boolean(),
   })
   .refine((data) => data.password === data.confirm_password, {
@@ -66,7 +74,7 @@ const AddUser = () => {
       full_name: "",
       password: "",
       confirm_password: "",
-      is_superuser: false,
+      role: "member",
       is_active: false,
     },
   })
@@ -186,16 +194,25 @@ const AddUser = () => {
 
               <FormField
                 control={form.control}
-                name="is_superuser"
+                name="role"
                 render={({ field }) => (
-                  <FormItem className="flex items-center gap-3 space-y-0">
-                    <FormControl>
-                      <Checkbox
-                        checked={field.value}
-                        onCheckedChange={field.onChange}
-                      />
-                    </FormControl>
-                    <FormLabel className="font-normal">Is superuser?</FormLabel>
+                  <FormItem>
+                    <FormLabel>Role</FormLabel>
+                    <Select onValueChange={field.onChange} value={field.value}>
+                      <FormControl>
+                        <SelectTrigger className="w-full">
+                          <SelectValue placeholder="Select a role" />
+                        </SelectTrigger>
+                      </FormControl>
+                      <SelectContent>
+                        {ROLE_OPTIONS.map((option) => (
+                          <SelectItem key={option.value} value={option.value}>
+                            {option.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <FormMessage />
                   </FormItem>
                 )}
               />
diff --git a/frontend/src/components/Admin/EditUser.tsx b/frontend/src/components/Admin/EditUser.tsx
index 9d001a2a3e..9ceb93513c 100644
--- a/frontend/src/components/Admin/EditUser.tsx
+++ b/frontend/src/components/Admin/EditUser.tsx
@@ -28,8 +28,16 @@ import {
 } from "@/components/ui/form"
 import { Input } from "@/components/ui/input"
 import { LoadingButton } from "@/components/ui/loading-button"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
 import useCustomToast from "@/hooks/useCustomToast"
 import { handleError } from "@/utils"
+import { ROLE_OPTIONS } from "./roleOptions"
 
 const formSchema = z
   .object({
@@ -41,7 +49,7 @@ const formSchema = z
       .optional()
       .or(z.literal("")),
     confirm_password: z.string().optional(),
-    is_superuser: z.boolean().optional(),
+    role: z.enum(["member", "manager", "admin"]).optional(),
     is_active: z.boolean().optional(),
   })
   .refine((data) => !data.password || data.password === data.confirm_password, {
@@ -68,7 +76,9 @@ const EditUser = ({ user, onSuccess }: EditUserProps) => {
     defaultValues: {
       email: user.email,
       full_name: user.full_name ?? undefined,
-      is_superuser: user.is_superuser,
+      role: ROLE_OPTIONS.some((option) => option.value === user.role)
+        ? (user.role as FormData["role"])
+        : "member",
       is_active: user.is_active,
     },
   })
@@ -188,16 +198,25 @@ const EditUser = ({ user, onSuccess }: EditUserProps) => {
 
               <FormField
                 control={form.control}
-                name="is_superuser"
+                name="role"
                 render={({ field }) => (
-                  <FormItem className="flex items-center gap-3 space-y-0">
-                    <FormControl>
-                      <Checkbox
-                        checked={field.value}
-                        onCheckedChange={field.onChange}
-                      />
-                    </FormControl>
-                    <FormLabel className="font-normal">Is superuser?</FormLabel>
+                  <FormItem>
+                    <FormLabel>Role</FormLabel>
+                    <Select onValueChange={field.onChange} value={field.value}>
+                      <FormControl>
+                        <SelectTrigger className="w-full">
+                          <SelectValue placeholder="Select a role" />
+                        </SelectTrigger>
+                      </FormControl>
+                      <SelectContent>
+                        {ROLE_OPTIONS.map((option) => (
+                          <SelectItem key={option.value} value={option.value}>
+                            {option.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <FormMessage />
                   </FormItem>
                 )}
               />
diff --git a/frontend/src/components/Admin/UserActionsMenu.tsx b/frontend/src/components/Admin/UserActionsMenu.tsx
index 01f71cbb7a..14e69c87d2 100644
--- a/frontend/src/components/Admin/UserActionsMenu.tsx
+++ b/frontend/src/components/Admin/UserActionsMenu.tsx
@@ -9,6 +9,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu"
 import useAuth from "@/hooks/useAuth"
+import { hasPermission, PERMISSIONS } from "@/utils"
 import DeleteUser from "./DeleteUser"
 import EditUser from "./EditUser"
 
@@ -24,10 +25,14 @@ export const UserActionsMenu = ({ user }: UserActionsMenuProps) => {
     return null
   }
 
+  if (!hasPermission(currentUser, PERMISSIONS.usersManage)) {
+    return null
+  }
+
   return (
     <DropdownMenu open={open} onOpenChange={setOpen}>
       <DropdownMenuTrigger asChild>
-        <Button variant="ghost" size="icon">
+        <Button variant="ghost" size="icon" aria-label="User actions">
           <EllipsisVertical />
         </Button>
       </DropdownMenuTrigger>
diff --git a/frontend/src/components/Admin/columns.tsx b/frontend/src/components/Admin/columns.tsx
index 8b0fa13eef..b94958cc54 100644
--- a/frontend/src/components/Admin/columns.tsx
+++ b/frontend/src/components/Admin/columns.tsx
@@ -39,11 +39,11 @@ export const columns: ColumnDef<UserTableData>[] = [
     ),
   },
   {
-    accessorKey: "is_superuser",
+    accessorKey: "role",
     header: "Role",
     cell: ({ row }) => (
-      <Badge variant={row.original.is_superuser ? "default" : "secondary"}>
-        {row.original.is_superuser ? "Superuser" : "User"}
+      <Badge variant={row.original.role === "admin" ? "default" : "secondary"}>
+        {row.original.role}
       </Badge>
     ),
   },
diff --git a/frontend/src/components/Admin/roleOptions.ts b/frontend/src/components/Admin/roleOptions.ts
new file mode 100644
index 0000000000..4f7b49e1ec
--- /dev/null
+++ b/frontend/src/components/Admin/roleOptions.ts
@@ -0,0 +1,5 @@
+export const ROLE_OPTIONS = [
+  { value: "member", label: "Member" },
+  { value: "manager", label: "Manager" },
+  { value: "admin", label: "Admin" },
+] as const
diff --git a/frontend/src/components/Common/AccessDenied.tsx b/frontend/src/components/Common/AccessDenied.tsx
new file mode 100644
index 0000000000..14ffef59d4
--- /dev/null
+++ b/frontend/src/components/Common/AccessDenied.tsx
@@ -0,0 +1,31 @@
+import { Link } from "@tanstack/react-router"
+import { Button } from "@/components/ui/button"
+
+const AccessDenied = () => {
+  return (
+    <div
+      className="flex min-h-screen items-center justify-center flex-col p-4"
+      data-testid="access-denied"
+    >
+      <div className="flex items-center z-10">
+        <div className="flex flex-col ml-4 items-center justify-center p-4">
+          <span className="text-6xl md:text-8xl font-bold leading-none mb-4">
+            403
+          </span>
+          <span className="text-2xl font-bold mb-2">Access Denied</span>
+        </div>
+      </div>
+
+      <p className="text-lg text-muted-foreground mb-4 text-center z-10">
+        You don't have permission to view this page.
+      </p>
+      <div className="z-10">
+        <Link to="/">
+          <Button className="mt-4">Go Back</Button>
+        </Link>
+      </div>
+    </div>
+  )
+}
+
+export default AccessDenied
diff --git a/frontend/src/components/Sidebar/AppSidebar.tsx b/frontend/src/components/Sidebar/AppSidebar.tsx
index 8502bcb9a4..8c31b688a9 100644
--- a/frontend/src/components/Sidebar/AppSidebar.tsx
+++ b/frontend/src/components/Sidebar/AppSidebar.tsx
@@ -1,4 +1,4 @@
-import { Briefcase, Home, Users } from "lucide-react"
+import { BarChart3, Briefcase, Home, Users } from "lucide-react"
 
 import { SidebarAppearance } from "@/components/Common/Appearance"
 import { Logo } from "@/components/Common/Logo"
@@ -9,6 +9,7 @@ import {
   SidebarHeader,
 } from "@/components/ui/sidebar"
 import useAuth from "@/hooks/useAuth"
+import { hasPermission, PERMISSIONS } from "@/utils"
 import { type Item, Main } from "./Main"
 import { User } from "./User"
 
@@ -20,9 +21,15 @@ const baseItems: Item[] = [
 export function AppSidebar() {
   const { user: currentUser } = useAuth()
 
-  const items = currentUser?.is_superuser
-    ? [...baseItems, { icon: Users, title: "Admin", path: "/admin" }]
-    : baseItems
+  const items = [
+    ...baseItems,
+    ...(hasPermission(currentUser, PERMISSIONS.usersList)
+      ? [{ icon: Users, title: "Admin", path: "/admin" }]
+      : []),
+    ...(hasPermission(currentUser, PERMISSIONS.metricsView)
+      ? [{ icon: BarChart3, title: "Metrics", path: "/metrics" }]
+      : []),
+  ]
 
   return (
     <Sidebar collapsible="icon">
diff --git a/frontend/src/hooks/useAuth.ts b/frontend/src/hooks/useAuth.ts
index 051b222aee..e4068ec454 100644
--- a/frontend/src/hooks/useAuth.ts
+++ b/frontend/src/hooks/useAuth.ts
@@ -4,7 +4,7 @@ import { useNavigate } from "@tanstack/react-router"
 import {
   type Body_login_login_access_token as AccessToken,
   LoginService,
-  type UserPublic,
+  type UserMePublic,
   type UserRegister,
   UsersService,
 } from "@/client"
@@ -20,7 +20,7 @@ const useAuth = () => {
   const queryClient = useQueryClient()
   const { showErrorToast } = useCustomToast()
 
-  const { data: user } = useQuery<UserPublic | null, Error>({
+  const { data: user } = useQuery<UserMePublic | null, Error>({
     queryKey: ["currentUser"],
     queryFn: async () => (await UsersService.readUserMe()).data,
     enabled: isLoggedIn(),
diff --git a/frontend/src/routeTree.gen.ts b/frontend/src/routeTree.gen.ts
index b45f83a1d3..c6fa6e5da7 100644
--- a/frontend/src/routeTree.gen.ts
+++ b/frontend/src/routeTree.gen.ts
@@ -16,7 +16,9 @@ import { Route as ResetPasswordRouteImport } from './routes/reset-password'
 import { Route as SignupRouteImport } from './routes/signup'
 import { Route as LayoutIndexRouteImport } from './routes/_layout/index'
 import { Route as LayoutAdminRouteImport } from './routes/_layout/admin'
+import { Route as LayoutForbiddenRouteImport } from './routes/_layout/forbidden'
 import { Route as LayoutItemsRouteImport } from './routes/_layout/items'
+import { Route as LayoutMetricsRouteImport } from './routes/_layout/metrics'
 import { Route as LayoutSettingsRouteImport } from './routes/_layout/settings'
 
 const LayoutRoute = LayoutRouteImport.update({
@@ -53,11 +55,21 @@ const LayoutAdminRoute = LayoutAdminRouteImport.update({
   path: '/admin',
   getParentRoute: () => LayoutRoute,
 } as any)
+const LayoutForbiddenRoute = LayoutForbiddenRouteImport.update({
+  id: '/forbidden',
+  path: '/forbidden',
+  getParentRoute: () => LayoutRoute,
+} as any)
 const LayoutItemsRoute = LayoutItemsRouteImport.update({
   id: '/items',
   path: '/items',
   getParentRoute: () => LayoutRoute,
 } as any)
+const LayoutMetricsRoute = LayoutMetricsRouteImport.update({
+  id: '/metrics',
+  path: '/metrics',
+  getParentRoute: () => LayoutRoute,
+} as any)
 const LayoutSettingsRoute = LayoutSettingsRouteImport.update({
   id: '/settings',
   path: '/settings',
@@ -71,7 +83,9 @@ export interface FileRoutesByFullPath {
   '/reset-password': typeof ResetPasswordRoute
   '/signup': typeof SignupRoute
   '/admin': typeof LayoutAdminRoute
+  '/forbidden': typeof LayoutForbiddenRoute
   '/items': typeof LayoutItemsRoute
+  '/metrics': typeof LayoutMetricsRoute
   '/settings': typeof LayoutSettingsRoute
 }
 export interface FileRoutesByTo {
@@ -80,7 +94,9 @@ export interface FileRoutesByTo {
   '/reset-password': typeof ResetPasswordRoute
   '/signup': typeof SignupRoute
   '/admin': typeof LayoutAdminRoute
+  '/forbidden': typeof LayoutForbiddenRoute
   '/items': typeof LayoutItemsRoute
+  '/metrics': typeof LayoutMetricsRoute
   '/settings': typeof LayoutSettingsRoute
   '/': typeof LayoutIndexRoute
 }
@@ -92,7 +108,9 @@ export interface FileRoutesById {
   '/reset-password': typeof ResetPasswordRoute
   '/signup': typeof SignupRoute
   '/_layout/admin': typeof LayoutAdminRoute
+  '/_layout/forbidden': typeof LayoutForbiddenRoute
   '/_layout/items': typeof LayoutItemsRoute
+  '/_layout/metrics': typeof LayoutMetricsRoute
   '/_layout/settings': typeof LayoutSettingsRoute
   '/_layout/': typeof LayoutIndexRoute
 }
@@ -105,7 +123,9 @@ export interface FileRouteTypes {
     | '/reset-password'
     | '/signup'
     | '/admin'
+    | '/forbidden'
     | '/items'
+    | '/metrics'
     | '/settings'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -114,7 +134,9 @@ export interface FileRouteTypes {
     | '/reset-password'
     | '/signup'
     | '/admin'
+    | '/forbidden'
     | '/items'
+    | '/metrics'
     | '/settings'
     | '/'
   id:
@@ -125,7 +147,9 @@ export interface FileRouteTypes {
     | '/reset-password'
     | '/signup'
     | '/_layout/admin'
+    | '/_layout/forbidden'
     | '/_layout/items'
+    | '/_layout/metrics'
     | '/_layout/settings'
     | '/_layout/'
   fileRoutesById: FileRoutesById
@@ -189,6 +213,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutAdminRouteImport
       parentRoute: typeof LayoutRoute
     }
+    '/_layout/forbidden': {
+      id: '/_layout/forbidden'
+      path: '/forbidden'
+      fullPath: '/forbidden'
+      preLoaderRoute: typeof LayoutForbiddenRouteImport
+      parentRoute: typeof LayoutRoute
+    }
     '/_layout/items': {
       id: '/_layout/items'
       path: '/items'
@@ -196,6 +227,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutItemsRouteImport
       parentRoute: typeof LayoutRoute
     }
+    '/_layout/metrics': {
+      id: '/_layout/metrics'
+      path: '/metrics'
+      fullPath: '/metrics'
+      preLoaderRoute: typeof LayoutMetricsRouteImport
+      parentRoute: typeof LayoutRoute
+    }
     '/_layout/settings': {
       id: '/_layout/settings'
       path: '/settings'
@@ -208,14 +246,18 @@ declare module '@tanstack/react-router' {
 
 interface LayoutRouteChildren {
   LayoutAdminRoute: typeof LayoutAdminRoute
+  LayoutForbiddenRoute: typeof LayoutForbiddenRoute
   LayoutItemsRoute: typeof LayoutItemsRoute
+  LayoutMetricsRoute: typeof LayoutMetricsRoute
   LayoutSettingsRoute: typeof LayoutSettingsRoute
   LayoutIndexRoute: typeof LayoutIndexRoute
 }
 
 const LayoutRouteChildren: LayoutRouteChildren = {
   LayoutAdminRoute: LayoutAdminRoute,
+  LayoutForbiddenRoute: LayoutForbiddenRoute,
   LayoutItemsRoute: LayoutItemsRoute,
+  LayoutMetricsRoute: LayoutMetricsRoute,
   LayoutSettingsRoute: LayoutSettingsRoute,
   LayoutIndexRoute: LayoutIndexRoute,
 }
diff --git a/frontend/src/routes/_layout/admin.tsx b/frontend/src/routes/_layout/admin.tsx
index 39241c23ca..0db2cc7aac 100644
--- a/frontend/src/routes/_layout/admin.tsx
+++ b/frontend/src/routes/_layout/admin.tsx
@@ -8,6 +8,7 @@ import { columns, type UserTableData } from "@/components/Admin/columns"
 import { DataTable } from "@/components/Common/DataTable"
 import PendingUsers from "@/components/Pending/PendingUsers"
 import useAuth from "@/hooks/useAuth"
+import { hasPermission, PERMISSIONS } from "@/utils"
 
 function getUsersQueryOptions() {
   return {
@@ -21,9 +22,9 @@ export const Route = createFileRoute("/_layout/admin")({
   component: Admin,
   beforeLoad: async () => {
     const { data: user } = await UsersService.readUserMe()
-    if (!user.is_superuser) {
+    if (!hasPermission(user, PERMISSIONS.usersList)) {
       throw redirect({
-        to: "/",
+        to: "/forbidden",
       })
     }
   },
@@ -57,6 +58,8 @@ function UsersTable() {
 }
 
 function Admin() {
+  const { user: currentUser } = useAuth()
+
   return (
     <div className="flex flex-col gap-6">
       <div className="flex items-center justify-between">
@@ -66,7 +69,7 @@ function Admin() {
             Manage user accounts and permissions
           </p>
         </div>
-        <AddUser />
+        {hasPermission(currentUser, PERMISSIONS.usersCreate) && <AddUser />}
       </div>
       <UsersTable />
     </div>
diff --git a/frontend/src/routes/_layout/forbidden.tsx b/frontend/src/routes/_layout/forbidden.tsx
new file mode 100644
index 0000000000..2ea33294e9
--- /dev/null
+++ b/frontend/src/routes/_layout/forbidden.tsx
@@ -0,0 +1,14 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import AccessDenied from "@/components/Common/AccessDenied"
+
+export const Route = createFileRoute("/_layout/forbidden")({
+  component: AccessDenied,
+  head: () => ({
+    meta: [
+      {
+        title: "Access Denied - FastAPI Template",
+      },
+    ],
+  }),
+})
diff --git a/frontend/src/routes/_layout/metrics.tsx b/frontend/src/routes/_layout/metrics.tsx
new file mode 100644
index 0000000000..1daf471ca6
--- /dev/null
+++ b/frontend/src/routes/_layout/metrics.tsx
@@ -0,0 +1,90 @@
+import { useSuspenseQuery } from "@tanstack/react-query"
+import { createFileRoute, redirect } from "@tanstack/react-router"
+import { Suspense } from "react"
+
+import { MetricsService, UsersService } from "@/client"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { Skeleton } from "@/components/ui/skeleton"
+import { hasPermission, PERMISSIONS } from "@/utils"
+
+function getMetricsQueryOptions() {
+  return {
+    queryFn: async () => (await MetricsService.readMetrics()).data,
+    queryKey: ["metrics"],
+  }
+}
+
+export const Route = createFileRoute("/_layout/metrics")({
+  component: Metrics,
+  beforeLoad: async () => {
+    const { data: user } = await UsersService.readUserMe()
+    if (!hasPermission(user, PERMISSIONS.metricsView)) {
+      throw redirect({
+        to: "/forbidden",
+      })
+    }
+  },
+  head: () => ({
+    meta: [
+      {
+        title: "Metrics - FastAPI Template",
+      },
+    ],
+  }),
+})
+
+function MetricsCards() {
+  const { data: metrics } = useSuspenseQuery(getMetricsQueryOptions())
+
+  return (
+    <div className="grid gap-4 sm:grid-cols-2">
+      <Card>
+        <CardHeader>
+          <CardDescription>Users</CardDescription>
+          <CardTitle className="text-3xl">{metrics.user_count}</CardTitle>
+        </CardHeader>
+        <CardContent className="text-sm text-muted-foreground">
+          Total registered accounts
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader>
+          <CardDescription>Items</CardDescription>
+          <CardTitle className="text-3xl">{metrics.item_count}</CardTitle>
+        </CardHeader>
+        <CardContent className="text-sm text-muted-foreground">
+          Total items across all users
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+
+function PendingMetrics() {
+  return (
+    <div className="grid gap-4 sm:grid-cols-2">
+      <Skeleton className="h-32" />
+      <Skeleton className="h-32" />
+    </div>
+  )
+}
+
+function Metrics() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h1 className="text-2xl font-bold tracking-tight">Metrics</h1>
+        <p className="text-muted-foreground">Basic usage insights</p>
+      </div>
+      <Suspense fallback={<PendingMetrics />}>
+        <MetricsCards />
+      </Suspense>
+    </div>
+  )
+}
diff --git a/frontend/src/routes/_layout/settings.tsx b/frontend/src/routes/_layout/settings.tsx
index e109b5ae81..42ecadaae0 100644
--- a/frontend/src/routes/_layout/settings.tsx
+++ b/frontend/src/routes/_layout/settings.tsx
@@ -5,6 +5,7 @@ import DeleteAccount from "@/components/UserSettings/DeleteAccount"
 import UserInformation from "@/components/UserSettings/UserInformation"
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
 import useAuth from "@/hooks/useAuth"
+import { hasPermission, PERMISSIONS } from "@/utils"
 
 const tabsConfig = [
   { value: "my-profile", title: "My profile", component: UserInformation },
@@ -25,8 +26,8 @@ export const Route = createFileRoute("/_layout/settings")({
 
 function UserSettings() {
   const { user: currentUser } = useAuth()
-  const finalTabs = currentUser?.is_superuser
-    ? tabsConfig.slice(0, 3)
+  const finalTabs = hasPermission(currentUser, PERMISSIONS.systemAdmin)
+    ? tabsConfig.filter((tab) => tab.value !== "danger-zone")
     : tabsConfig
 
   if (!currentUser) {
diff --git a/frontend/src/utils.ts b/frontend/src/utils.ts
index 967bb471ee..e62bca65c2 100644
--- a/frontend/src/utils.ts
+++ b/frontend/src/utils.ts
@@ -1,5 +1,7 @@
 import { AxiosError } from "axios"
 
+import type { UserMePublic } from "@/client"
+
 function extractErrorMessage(err: Error): string {
   if (err instanceof AxiosError) {
     const errDetail = (err.response?.data as any)?.detail
@@ -27,3 +29,18 @@ export const getInitials = (name: string): string => {
     .join("")
     .toUpperCase()
 }
+
+export const PERMISSIONS = {
+  usersList: "users:list",
+  usersCreate: "users:create",
+  usersManage: "users:manage",
+  metricsView: "metrics:view",
+  systemAdmin: "system:admin",
+} as const
+
+export const hasPermission = (
+  user: UserMePublic | null | undefined,
+  code: string,
+): boolean => {
+  return user?.permissions.includes(code) ?? false
+}
diff --git a/frontend/tests/admin.spec.ts b/frontend/tests/admin.spec.ts
index cd73dbad5c..6977f398ad 100644
--- a/frontend/tests/admin.spec.ts
+++ b/frontend/tests/admin.spec.ts
@@ -2,7 +2,7 @@ import { expect, test } from "@playwright/test"
 import { firstSuperuser, firstSuperuserPassword } from "./config.ts"
 import { createUser } from "./utils/privateApi"
 import { randomEmail, randomPassword } from "./utils/random"
-import { logInUser } from "./utils/user"
+import { logInUser, logOutUser } from "./utils/user"
 
 test("Admin page is accessible and shows correct title", async ({ page }) => {
   await page.goto("/admin")
@@ -42,7 +42,7 @@ test.describe("Admin user management", () => {
     await expect(userRow).toBeVisible()
   })
 
-  test("Create a superuser", async ({ page }) => {
+  test("Create an admin user", async ({ page }) => {
     await page.goto("/admin")
 
     const email = randomEmail()
@@ -53,7 +53,10 @@ test.describe("Admin user management", () => {
     await page.getByPlaceholder("Email").fill(email)
     await page.getByPlaceholder("Password").first().fill(password)
     await page.getByPlaceholder("Password").last().fill(password)
-    await page.getByLabel("Is superuser?").check()
+
+    const dialog = page.getByRole("dialog")
+    await dialog.getByRole("combobox").click()
+    await page.getByRole("option", { name: "Admin" }).click()
     await page.getByLabel("Is active?").check()
 
     await page.getByRole("button", { name: "Save" }).click()
@@ -63,7 +66,7 @@ test.describe("Admin user management", () => {
     await expect(page.getByRole("dialog")).not.toBeVisible()
 
     const userRow = page.getByRole("row").filter({ hasText: email })
-    await expect(userRow.getByText("Superuser")).toBeVisible()
+    await expect(userRow.getByText("admin")).toBeVisible()
   })
 
   test("Edit a user successfully", async ({ page }) => {
@@ -182,7 +185,9 @@ test.describe("Admin user management", () => {
 test.describe("Admin page access control", () => {
   test.use({ storageState: { cookies: [], origins: [] } })
 
-  test("Non-superuser cannot access admin page", async ({ page }) => {
+  test("Member sees Access Denied when navigating directly to admin page", async ({
+    page,
+  }) => {
     const email = randomEmail()
     const password = randomPassword()
 
@@ -192,14 +197,63 @@ test.describe("Admin page access control", () => {
     await page.goto("/admin")
 
     await expect(page.getByRole("heading", { name: "Users" })).not.toBeVisible()
-    await expect(page).not.toHaveURL(/\/admin/)
+    await expect(page).toHaveURL(/\/forbidden/)
+    await expect(page.getByTestId("access-denied")).toBeVisible()
+    await expect(page.getByText("Access Denied")).toBeVisible()
+  })
+
+  test("Member does not see the Admin nav link", async ({ page }) => {
+    const email = randomEmail()
+    const password = randomPassword()
+
+    await createUser({ email, password })
+    await logInUser(page, email, password)
+
+    await expect(
+      page.getByRole("link", { name: "Admin", exact: true }),
+    ).not.toBeVisible()
+  })
+
+  test("Admin can access admin page", async ({ page }) => {
+    await logInUser(page, firstSuperuser, firstSuperuserPassword)
+
+    await page.goto("/admin")
+
+    await expect(page.getByRole("heading", { name: "Users" })).toBeVisible()
   })
 
-  test("Superuser can access admin page", async ({ page }) => {
+  test("Manager can list users but not manage them", async ({ page }) => {
     await logInUser(page, firstSuperuser, firstSuperuserPassword)
+    await page.goto("/admin")
 
+    const managerEmail = randomEmail()
+    const managerPassword = randomPassword()
+
+    await page.getByRole("button", { name: "Add User" }).click()
+    await page.getByPlaceholder("Email").fill(managerEmail)
+    await page.getByPlaceholder("Password").first().fill(managerPassword)
+    await page.getByPlaceholder("Password").last().fill(managerPassword)
+    const dialog = page.getByRole("dialog")
+    await dialog.getByRole("combobox").click()
+    await page.getByRole("option", { name: "Manager" }).click()
+    await page.getByLabel("Is active?").check()
+    await page.getByRole("button", { name: "Save" }).click()
+    await expect(page.getByText("User created successfully")).toBeVisible()
+
+    await logOutUser(page)
+    await logInUser(page, managerEmail, managerPassword)
     await page.goto("/admin")
 
     await expect(page.getByRole("heading", { name: "Users" })).toBeVisible()
+    await expect(
+      page.getByRole("button", { name: "Add User" }),
+    ).not.toBeVisible()
+
+    const otherUserRow = page
+      .getByRole("row")
+      .filter({ hasText: firstSuperuser })
+    await expect(
+      otherUserRow.getByRole("button", { name: "User actions" }),
+    ).not.toBeVisible()
   })
 })
diff --git a/frontend/tests/user-settings.spec.ts b/frontend/tests/user-settings.spec.ts
index 533ebb6207..2639e1e4df 100644
--- a/frontend/tests/user-settings.spec.ts
+++ b/frontend/tests/user-settings.spec.ts
@@ -14,11 +14,27 @@ test("My profile tab is active by default", async ({ page }) => {
   )
 })
 
-test("All tabs are visible", async ({ page }) => {
+test("Admin does not see the Danger zone tab", async ({ page }) => {
   await page.goto("/settings")
-  for (const tab of tabs) {
-    await expect(page.getByRole("tab", { name: tab })).toBeVisible()
-  }
+  await expect(page.getByRole("tab", { name: "My profile" })).toBeVisible()
+  await expect(page.getByRole("tab", { name: "Password" })).toBeVisible()
+  await expect(page.getByRole("tab", { name: "Danger zone" })).not.toBeVisible()
+})
+
+test.describe("Non-admin settings tabs", () => {
+  test.use({ storageState: { cookies: [], origins: [] } })
+
+  test("All tabs are visible for a non-admin user", async ({ page }) => {
+    const email = randomEmail()
+    const password = randomPassword()
+    await createUser({ email, password })
+
+    await logInUser(page, email, password)
+    await page.goto("/settings")
+    for (const tab of tabs) {
+      await expect(page.getByRole("tab", { name: tab })).toBeVisible()
+    }
+  })
 })
 
 test.describe("Edit user profile", () => {
diff --git a/openspec/changes/add-rbac/.openspec.yaml b/openspec/changes/add-rbac/.openspec.yaml
new file mode 100644
index 0000000000..f774115be7
--- /dev/null
+++ b/openspec/changes/add-rbac/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-20
diff --git a/openspec/changes/add-rbac/design.md b/openspec/changes/add-rbac/design.md
new file mode 100644
index 0000000000..5f4496846e
--- /dev/null
+++ b/openspec/changes/add-rbac/design.md
@@ -0,0 +1,132 @@
+## Context
+
+See proposal.md for motivation. Today authorization is a boolean `User.is_superuser` checked in `get_current_active_superuser` and inline in item and self-delete routes. The React app copies that flag for admin route `beforeLoad`, sidebar, user forms, and settings tabs. First-run seed in `app/core/db.py` creates a superuser. No authorization library is in use.
+
+Constraints: stay on SQLModel + FastAPI `Depends` + TanStack Router; prefer a small, copy-paste-friendly model over a policy engine; keep existing pytest/Playwright green rather than adding a new test layer.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Single permission check API on the backend (`require_permission("users:list")`) replacing `is_superuser`.
+- A small, realistic protected surface — list users, create a user, view a metrics/insights page, view/update your own profile — enforced identically on the backend and the frontend.
+- Three roles (`admin`, `manager`, `member`) whose grants are obvious from one table, so a teammate understands the authorization model in under 5 minutes.
+- Data model that can grow (new permission codes, extra seeded roles) without another boolean column or touching every route.
+
+**Non-Goals:**
+
+- Custom role/permission CRUD APIs or an admin UI to invent roles at runtime.
+- Multi-role users, groups, tenants, or resource ACLs beyond existing item ownership.
+- Casbin, Oso, or other policy engines.
+- New documentation site or a dedicated unit-test framework for RBAC.
+
+## Decisions
+
+### 1. User has exactly one role; roles have many permissions
+
+```
+┌──────────┐     role_id      ┌──────────┐
+│   User   │─────────────────▶│   Role   │  slug unique (admin, manager, member)
+└──────────┘                  └────┬─────┘
+                                   │
+                            link table
+                                   │
+                              ┌────▼─────┐
+                              │Permission│  code unique (users:list)
+                              └──────────┘
+```
+
+**Why:** Classic RBAC, easy to reason about in a template, one FK on `user`. Many-to-many users↔roles adds join complexity without a product need. A permission enum on the user skips roles and cannot group privileges. Adding a fourth role later is one seed-data row plus a grants entry, not a new column or a new set of route checks.
+
+**Alternatives:** Keep `is_superuser` and add extra booleans — rejected (does not scale past two tiers). Library-based RBAC — rejected (heavier than the template).
+
+### 2. Five permission codes cover the whole surface
+
+```
+users:list      list all users / view a user other than yourself
+users:create    create a user
+users:manage    update or delete a user other than yourself
+metrics:view    view the metrics/insights page
+system:admin    everything else admin-only: item access across owners,
+                transactional-email test/preview, blocks self-delete
+```
+
+| Role      | users:list | users:create | users:manage | metrics:view | system:admin |
+|-----------|:---:|:---:|:---:|:---:|:---:|
+| `admin`   | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `manager` | ✓ |   |   | ✓ |   |
+| `member`  |   |   |   |   |   |
+
+Viewing/updating your **own** profile needs no permission check — it's the baseline for any authenticated, active user, matching how `PATCH /users/me` already worked.
+
+**Why:** The proposal's permission matrix maps directly to 4 of these codes (`users:list`, `users:create`, `users:manage`, `metrics:view`). Everything the old design protected that isn't in that matrix (item ownership bypass, test-email, password-recovery HTML preview, the "admins can't self-delete" rule) is folded into one `system:admin` code rather than kept as separate codes (`items:read_any`, `items:write_any`, `system:ops`, `users:write`). One admin-only catch-all is easier to hold in your head than four overlapping ones, and it's still just a `require_permission("system:admin")` call at each of those sites — nothing about the dependency mechanism changes.
+
+**Alternatives:** Keep the old finer-grained codes alongside the three new ones (8 total) — rejected, adds surface area without adding real access control (nothing but `admin` was ever going to hold the fine-grained ones). Drop those protections entirely — rejected, it's a behavior regression nobody asked for.
+
+### 3. FastAPI dependency factory, not a new middleware
+
+`require_permission(code: str)` returns a dependency that loads the current user, resolves permission codes for their role, and raises 403 if `code` is missing. Item ownership stays in the item routes: missing `system:admin` falls back to `owner_id == current_user.id` (same shape as today's superuser bypass, inverted).
+
+Replace `get_current_active_superuser` entirely.
+
+**Why:** Fits existing `Annotated` / `Depends` style. Middleware would run on every route and still need per-route metadata.
+
+### 4. `/users/me` is the UI source of truth
+
+Extend the current-user response with `role: str` and `permissions: list[str]`. Other user list/detail payloads include `role` only (no permission dump). Frontend: small helper `hasPermission(user, code)` used by sidebar, admin `beforeLoad`, the new metrics route guard, and settings tab filtering. A `PERMISSIONS` constants object in the frontend mirrors the backend's codes so call sites never hardcode strings. Regenerated OpenAPI client after schema change.
+
+**Why:** UI must not invent a second mapping from role slug → screens. Listing other users' full permission sets is unnecessary.
+
+### 5. Breaking replacement of `is_superuser`
+
+Drop the column. User create/update take `role` slug (optional on create, default `member`). Admin forms: role select (`member` | `manager` | `admin`) instead of "Is superuser?".
+
+Self-delete guard: if the current user has `system:admin`, forbid self-delete (same intent as "superusers cannot delete themselves").
+
+**Why:** Dual-writing `is_superuser` and roles would keep the problem the change is meant to remove.
+
+### 6. Metrics/insights page is a stub
+
+Backend: `GET /api/v1/metrics/`, gated on `metrics:view`, returns a small fixed/derived payload (e.g. user and item counts) — not a real analytics pipeline. Frontend: one route (`/metrics`) with a placeholder page, gated the same way the admin route is, plus a sidebar nav item shown only when `metrics:view` is granted.
+
+**Why:** The clarification explicitly says "simple stub is acceptable" — this exists to prove the permission model covers a second, non-user-management feature, not to build real analytics.
+
+### 7. Direct navigation to a forbidden route shows Access Denied, not a silent bounce
+
+Add one shared `AccessDenied` page component and a `/forbidden` route. Route `beforeLoad` guards (admin, metrics) redirect there — with the attempted path preserved for the message — instead of silently redirecting to `/`. The sidebar still hides nav items the user can't use; Access Denied only fires when someone lands on a guarded URL directly (typed, bookmarked, or a stale link).
+
+**Why:** A silent redirect to `/` looks like a bug ("why did my click do nothing?"); a cryptic 403 JSON blob is worse. One reusable component keeps this consistent across every guarded route without duplicating the message in each one — adding a fourth guarded route later is "call the same guard, done," not "invent new copy."
+
+**Alternatives:** Show nothing and redirect silently (today's behavior) — rejected, fails the "no cryptic/silent failures" requirement. Render the denial inline per-route — rejected, duplicates copy and styling across every guarded route.
+
+### 8. Documentation lives in one dedicated file, not scattered comments
+
+Permission matrix, the 2-4 paragraph approach explanation (where checks live, how roles are stored/validated, how the frontend learns capabilities), and setup/seed/test-run instructions go in a new `docs/AUTHORIZATION.md`. The root `README.md` (template-wide, not RBAC-specific) gets a single pointer line rather than a large inserted section. Code itself stays comment-free except where the *why* genuinely isn't obvious from structure — e.g. one line on `require_permission` explaining it's a dependency factory (not a dependency itself), and one line on the `system:admin` catch-all explaining why several unrelated checks share one code (see design decision 2). No comment restates what a role/permission constant already says.
+
+**Why:** Matches the rubric's own split — code should be self-documenting via naming and structure; a dedicated doc is for the matrix and the "why," not a substitute for readable code, and not bolted onto an already-large template README.
+
+### 9. Tests: a few well-chosen backend cases beat exhaustive matrix coverage
+
+One pytest test per meaningfully distinct authorization path — not one per matrix cell. Concretely: an allowed and a denied case for each of `users:list`, `users:create`, `users:manage`, `metrics:view`; one case proving "update your own profile" needs no permission; one case proving a `member` cannot escalate their own role via the self-update endpoint (since `UserUpdateMe` has no `role` field, this is a schema-level guarantee worth asserting explicitly, not just trusting the type). That's roughly 8-10 focused, clearly named tests, not a 3×5 role×permission grid. Playwright coverage stays limited to what already existed (admin/login specs) plus asserting the Access Denied page renders for one blocked route — not a full frontend permission matrix.
+
+**Why:** The rubric explicitly rewards "3 well-chosen tests with clean code" over a large sprawling suite, and privilege-escalation-via-self-update is the one non-obvious gap worth a dedicated test rather than trusting "the schema doesn't have the field" to be self-evident.
+
+## Risks / Trade-offs
+
+- [Stale UI if permissions change while a session is open] → Accept for v1; `/users/me` is already fetched on layout. Document that a refresh picks up role changes.
+- [Forgotten route still using `is_superuser`] → Grep during apply; remove the field so type-checkers fail.
+- [Admin with empty permission table if seed skipped] → `init_db` upserts permissions every startup, not only when the first user is created.
+- [One role per user is inflexible] → Accept; adding a link table later is possible without changing permission codes.
+- [`system:admin` bundles unrelated concerns (items, email, self-delete) behind one code] → Accepted trade-off for a small, understandable surface; only `admin` ever holds it today, so splitting it later (if a role needs items-bypass but not email-preview) is a non-breaking migration — add a code, update the seed grants, update the two or three call sites that used the bundled one.
+
+## Migration Plan
+
+This change has not shipped yet, so the RBAC migration already written for the two-role version is **rewritten in place** rather than stacked with a second migration — there is no production data depending on the old `admin`/`user` seed to preserve.
+
+1. Add `permission`, `role`, `role_permission` tables and nullable `user.role_id`.
+2. Seed `admin`, `manager`, `member` roles and the five permission codes (same codes as `init_db`) with the grants table above.
+3. `UPDATE` users: `is_superuser = true` → `admin`, else → `member`.
+4. Make `role_id` NOT NULL; drop `is_superuser`.
+5. Deploy backend then regenerate frontend client.
+
+Rollback: reverse migration restores `is_superuser` from `role.slug == 'admin'`. In-flight tokens remain valid (user id in JWT is unchanged).
diff --git a/openspec/changes/add-rbac/proposal.md b/openspec/changes/add-rbac/proposal.md
new file mode 100644
index 0000000000..b826e7c85a
--- /dev/null
+++ b/openspec/changes/add-rbac/proposal.md
@@ -0,0 +1,33 @@
+## Why
+
+The template gates privileged actions with a boolean `is_superuser`. That is enough for a demo admin, but it cannot express distinct privileges, cannot hide only some UI, and forces every new sensitive feature into another superuser check. We need role-based access control so authorized users can reach sensitive API endpoints and UI sections, and everyone else cannot.
+
+## What Changes
+
+- Replace the `is_superuser` flag with **roles** and **permissions**.
+- Seed three roles: **admin** (full access to user management and settings), **manager** (can list users and view metrics, but not manage users or settings), and **member** (self-service only — own profile and basic app features; default for new and self-registered accounts).
+- Enforce permissions on sensitive FastAPI routes via a reusable dependency, not scattered boolean checks.
+- Expose the current user's role and permission list on `/users/me` so the React app can hide routes, nav, and controls.
+- Add a minimal "metrics/insights" surface (a stub page and endpoint) as a second protected feature beyond user management, to prove the permission model generalizes beyond one screen.
+- Direct navigation to a route the current user lacks permission for shows a friendly "Access Denied" page instead of a silent redirect.
+- **BREAKING**: User create/update payloads and public user schemas drop `is_superuser` and use a role instead. Existing superusers migrate to the admin role; everyone else to member.
+- Existing pytest and Playwright cases that assume `is_superuser` are updated only as needed to keep the current suite green. No new documentation site or extra test layers.
+- Document the authorization approach and permission matrix in a new `docs/AUTHORIZATION.md`, with a one-line pointer from the root `README.md`.
+
+## Capabilities
+
+### New Capabilities
+
+- `rbac`: Roles, permissions, assignment to users, API enforcement, and frontend gating of sensitive screens and actions.
+
+### Modified Capabilities
+
+- None. There are no main specs under `openspec/specs/` yet.
+
+## Impact
+
+- **Backend**: `User` model and schemas, Alembic migration, `app/api/deps.py`, user/item/login/utils/metrics routes, first-superuser seed in `app/core/db.py`, CRUD helpers, existing pytest fixtures and assertions.
+- **Frontend**: generated OpenAPI client, admin route guard, new metrics route guard, a shared "Access Denied" page, sidebar/nav, user create/edit forms (3-way role select), settings tab logic, Playwright admin specs.
+- **Docs**: new `docs/AUTHORIZATION.md` (permission matrix, approach, setup/seed/test instructions); root `README.md` gets a one-line pointer.
+- **API clients**: any consumer sending or reading `is_superuser` must switch to role (and, for the current user, permissions).
+- **Dependencies**: none new; stay on SQLModel, FastAPI `Depends`, and TanStack Router.
diff --git a/openspec/changes/add-rbac/specs/rbac/spec.md b/openspec/changes/add-rbac/specs/rbac/spec.md
new file mode 100644
index 0000000000..cd45b5b908
--- /dev/null
+++ b/openspec/changes/add-rbac/specs/rbac/spec.md
@@ -0,0 +1,167 @@
+## Purpose
+
+Controls who may perform privileged operations and see sensitive UI by assigning each user a role that carries a set of permissions.
+
+## ADDED Requirements
+
+### Requirement: Seeded roles and permissions
+
+The system SHALL persist roles and permissions and SHALL seed `admin`, `manager`, and `member` roles on startup if they are missing. New and self-registered users MUST be assigned the `member` role. The first configured administrator account MUST be assigned the `admin` role.
+
+Seeded permission codes MUST be:
+
+- `users:list` — list all users, or view a user other than yourself
+- `users:create` — create a user
+- `users:manage` — update or delete a user other than yourself
+- `metrics:view` — view the metrics/insights page
+- `system:admin` — catch-all for remaining admin-only surfaces (item access across all owners, transactional-email test/preview endpoints); also the permission that blocks self-deletion
+
+Role grants MUST be:
+
+| Role      | `users:list` | `users:create` | `users:manage` | `metrics:view` | `system:admin` |
+|-----------|:---:|:---:|:---:|:---:|:---:|
+| `admin`   | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `manager` | ✓ |   |   | ✓ |   |
+| `member`  |   |   |   |   |   |
+
+#### Scenario: Fresh database has default roles
+
+- **WHEN** the application initializes an empty database
+- **THEN** roles `admin`, `manager`, and `member` exist; `admin` holds all seeded permission codes; `manager` holds `users:list` and `metrics:view`; `member` holds none
+
+#### Scenario: Self-registration gets the default role
+
+- **WHEN** a visitor registers a new account
+- **THEN** that account is assigned the `member` role
+
+#### Scenario: First administrator is an admin
+
+- **WHEN** the configured first administrator account is created
+- **THEN** that account is assigned the `admin` role
+
+### Requirement: One role per user
+
+Each user MUST have exactly one role. An authorized administrator MUST be able to assign an existing role when creating or updating another user. The API MUST NOT accept `is_superuser`. User representations MUST include the user's role identifier (slug).
+
+#### Scenario: Admin assigns the manager role
+
+- **WHEN** a caller with `users:create` creates a user with role `manager`
+- **THEN** that user is stored with the `manager` role
+
+#### Scenario: Superuser field is rejected
+
+- **WHEN** a client sends `is_superuser` on a user create or update payload
+- **THEN** the field is not part of the public contract and does not grant privileges
+
+### Requirement: Current user exposes permissions
+
+`GET` current-user MUST return the authenticated user's role slug and the list of permission codes granted by that role.
+
+#### Scenario: Admin current user payload
+
+- **WHEN** an `admin` user requests their own profile
+- **THEN** the response includes role `admin` and every seeded permission code
+
+#### Scenario: Manager current user payload
+
+- **WHEN** a `manager` user requests their own profile
+- **THEN** the response includes role `manager` and permissions `users:list` and `metrics:view` only
+
+#### Scenario: Default member current user payload
+
+- **WHEN** a `member`-role user requests their own profile
+- **THEN** the response includes role `member` and an empty permission list
+
+### Requirement: API enforces permissions
+
+Sensitive endpoints MUST require the matching permission and MUST respond with HTTP 403 when the caller lacks it. Authentication is still required as today. Viewing and updating **your own** profile MUST always succeed for any authenticated, active user regardless of role — it requires no permission.
+
+| Permission | Protected operations |
+|---|---|
+| `users:list` | List all users; get a user other than yourself by id |
+| `users:create` | Create a user |
+| `users:manage` | Update or delete a user other than yourself |
+| `metrics:view` | View the metrics/insights endpoint and page |
+| `system:admin` | Read or write items the caller does not own; transactional-email test/preview endpoints; required to be absent for self-delete to succeed |
+
+#### Scenario: Manager can list users but not create one
+
+- **WHEN** a `manager` requests the user list
+- **THEN** the API returns 200
+- **WHEN** that same `manager` attempts to create a user
+- **THEN** the API returns 403
+
+#### Scenario: Member cannot list users or view metrics
+
+- **WHEN** a `member` requests the user list or the metrics endpoint
+- **THEN** the API returns 403 for both
+
+#### Scenario: Manager can view metrics
+
+- **WHEN** a `manager` requests the metrics endpoint
+- **THEN** the API returns 200
+
+#### Scenario: Any authenticated user can update their own profile
+
+- **WHEN** a `member` updates their own profile via the current-user endpoint
+- **THEN** the update succeeds
+
+#### Scenario: Manager cannot update another user's profile
+
+- **WHEN** a `manager` (who lacks `users:manage`) attempts to update a different user's profile
+- **THEN** the API returns 403
+
+#### Scenario: Owner can still manage own item
+
+- **WHEN** a caller without `system:admin` updates an item they own
+- **THEN** the update succeeds
+
+#### Scenario: Non-owner cannot update another's item
+
+- **WHEN** a caller without `system:admin` updates an item they do not own
+- **THEN** the API returns 403
+
+#### Scenario: Admin cannot self-delete
+
+- **WHEN** a user whose role includes `system:admin` requests deletion of their own account
+- **THEN** the API returns 403
+
+### Requirement: UI gates sensitive sections
+
+The web app MUST hide navigation and routes that require a permission the current user does not have. Admin user-management UI MUST be reachable only with `users:list` (view) and MUST use role assignment instead of a superuser checkbox, offering all three seeded roles. The metrics/insights page MUST be reachable only with `metrics:view`. Users without `system:admin` MUST still be offered account self-deletion in settings; users with `system:admin` MUST NOT.
+
+Direct navigation to a route the current user lacks permission for MUST show a friendly "Access Denied" page explaining the user lacks permission — never a silent redirect, a blank page, or a cryptic error.
+
+#### Scenario: Member sees no admin or metrics nav items
+
+- **WHEN** a `member` is signed in
+- **THEN** neither the admin nav item nor the metrics nav item is shown in the sidebar
+
+#### Scenario: Member navigating directly to admin or metrics sees Access Denied
+
+- **WHEN** a `member` navigates directly to the admin users page or the metrics page by URL
+- **THEN** the app shows a friendly "Access Denied" page instead of the requested content, a silent redirect, or a cryptic error
+
+#### Scenario: Manager can open user management but not create a user
+
+- **WHEN** a `manager` opens the admin users page
+- **THEN** the page loads with users shown, but no control to create a user is offered
+
+#### Scenario: Manager can open the metrics page
+
+- **WHEN** a `manager` opens the metrics page
+- **THEN** the page loads
+
+### Requirement: Existing superusers migrate to admin
+
+On schema migration, every user with `is_superuser` true MUST receive the `admin` role and every other user MUST receive the `member` role. The `is_superuser` column MUST be removed.
+
+#### Scenario: Legacy superuser becomes admin
+
+- **WHEN** the RBAC migration runs against a database that has a superuser
+- **THEN** that user has the `admin` role after migration and `is_superuser` no longer exists
+
+#### Scenario: Legacy non-superuser becomes a member
+
+- **WHEN** the RBAC migration runs against a database that has a non-superuser
+- **THEN** that user has the `member` role after migration
diff --git a/openspec/changes/add-rbac/tasks.md b/openspec/changes/add-rbac/tasks.md
new file mode 100644
index 0000000000..dfc6565298
--- /dev/null
+++ b/openspec/changes/add-rbac/tasks.md
@@ -0,0 +1,29 @@
+## 1. Data model and migration rework
+
+- [x] 1.1 Rewrite (in place, not stacked — unshipped) migration `2d1ae9889b29`: seed roles `admin`/`manager`/`member` and permission codes `users:list`, `users:create`, `users:manage`, `metrics:view`, `system:admin`; grant admin all five, manager `users:list`+`metrics:view`, member none; backfill `is_superuser=true` → `admin`, else → `member`. Verify `alembic upgrade head` succeeds against a DB that previously had superusers, and role/permission rows match the grants table.
+- [x] 1.2 Update `app/core/rbac.py` constants (`ROLE_ADMIN`/`ROLE_MANAGER`/`ROLE_MEMBER`, the five permission codes, `ROLE_PERMISSIONS`) to the new model. Verify constants match design.md's grants table exactly.
+
+## 2. Backend authorization remap
+
+- [x] 2.1 Remap `require_permission()` call sites: user list / get-other-user → `users:list`; user create → `users:create`; user update/delete-other → `users:manage`; item any-owner access, test-email, password-recovery-html-content → `system:admin`. Verify a `manager` gets 200 on list-users and 403 on create-user; a `member` gets 403 on both.
+- [x] 2.2 Update the self-delete guard (`DELETE /users/me`) to block on `system:admin` instead of the old `users:write`. Verify admin self-delete still returns 403 and manager/member self-delete succeeds.
+- [x] 2.3 Add `GET /api/v1/metrics/` stub endpoint gated on `metrics:view`, returning a small fixed/derived payload. Verify `admin` and `manager` get 200, `member` gets 403.
+- [x] 2.4 Security pass: confirm `UserUpdateMe` has no `role` field (self-update cannot escalate privilege) and grep for any remaining direct `role`/permission-code checks that bypass `require_permission`/`has_permission`. Add the one non-obvious clarifying comment each on `require_permission` (it's a dependency *factory*) and the `system:admin` catch-all (why several unrelated checks share one code) — no other authorization comments.
+
+## 3. Frontend remap and Access Denied UX
+
+- [x] 3.1 Regenerate the OpenAPI client (schema now includes the metrics route). Update the `PERMISSIONS` constants object in `src/utils.ts` to the five new codes.
+- [x] 3.2 Add a shared `AccessDenied` page component and a `/forbidden` route. Update the admin and metrics route `beforeLoad` guards to redirect there (not to `/`) when the permission check fails.
+- [x] 3.3 Update sidebar gating from the old codes to `users:list`; add a "Metrics" nav item and `/metrics` route guarded by `metrics:view` with a stub page. Verify a `member` sees neither Admin nor Metrics nav items, and direct navigation to either route shows the Access Denied page (not a silent redirect); a `manager` sees and can open both.
+- [x] 3.4 Replace the two-way role select in Add/Edit User forms with a three-way select (`member` | `manager` | `admin`). Verify creating/editing a user with each role persists correctly and the users table shows the right role badge.
+- [x] 3.5 Update the settings danger-zone tab gating from the old `users:write` check to `system:admin`. Verify only `admin` sessions hide the self-delete tab; `manager` and `member` still see it.
+
+## 4. Documentation
+
+- [x] 4.1 Write `docs/AUTHORIZATION.md`: permission matrix (role × permission, matching design.md's grants table); a 2-4 paragraph approach explanation covering where checks live (the `require_permission` dependency, not middleware/decorators), how roles are stored and validated (the `role`/`permission`/`role_permission` tables plus `rbac.py` constants), and how the frontend learns capabilities (`/users/me`'s `permissions` array plus the `hasPermission` helper). Add a one-line pointer to it from the root `README.md`.
+- [x] 4.2 Add setup/seed/test-run instructions to `docs/AUTHORIZATION.md`: how to run the app locally, how to seed at least one admin and one non-admin (manager or member) account for manual testing, how to run `alembic upgrade head`, and how to run the backend and frontend test suites.
+
+## 5. Existing tests
+
+- [x] 5.1 Update pytest fixtures/assertions for the new role slugs and permission codes. Write a small, focused set of new authorization tests (not an exhaustive per-cell matrix) covering: an allowed and a denied case for each of `users:list`, `users:create`, `users:manage`, `metrics:view`; that any authenticated user can update their own profile without a permission; and that a `member` cannot escalate their own role via the self-update endpoint. Verify `pytest` in `backend/` passes.
+- [x] 5.2 Update Playwright admin specs for the new role terminology and the three-way role select; add one assertion that navigating a `member` session directly to a guarded URL renders the Access Denied page. Verify `bunx playwright test` admin/login specs still pass.
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000000..c4d34acea9
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,32 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
+
+# Per-operation guidance (optional)
+# Add advisory guidance for how apply and archive work should be conducted.
+# This is separate from artifact rules above.
+# Example:
+#   operations:
+#     apply:
+#       guidance:
+#         - Keep test summaries concise
+#     archive:
+#       guidance:
+#         - Summarize the archive outcome before finishing