Rewrite admin docs for end-user audience

Replace API-reference-style docs (POST /api/... examples) with
UI-oriented guides that walk users through the web interface.
Covers authentication setup, blueprint creation, role management,
and user/group administration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gmr

docs/docs/admin/authentication.md

@@ -1,34 +1,40 @@
 # Authentication
 
 Imbi supports multiple authentication methods that can be used
-simultaneously.
+simultaneously. As an administrator, you configure these during
+deployment via environment variables.
 
 ## Local Authentication
 
-Local authentication uses email and password credentials stored in Neo4j
-with Argon2 password hashing.
+Local authentication allows users to sign in with an email address and
+password. It is enabled by default and is the simplest way to get
+started.
 
-Password requirements:
+When creating a user account (or when users set their own password),
+the following requirements apply:
 
 - Minimum 12 characters
 - At least one uppercase letter
 - At least one lowercase letter
 - At least one digit
 - At least one special character
 
-Local authentication is enabled by default. Disable it with:
+To disable local authentication (for example, if you only want OAuth):
 
 ```
 IMBI_AUTH_LOCAL_ENABLED=false
 ```
 
-## OAuth2 / OIDC
+## Single Sign-On (OAuth2 / OIDC)
 
-Imbi supports OAuth2/OIDC authentication with the following providers:
+For organizations using a centralized identity provider, Imbi supports
+OAuth2 and OpenID Connect. When configured, a "Sign in with ..."
+button appears on the login page. Users who sign in via SSO for the
+first time are automatically provisioned with a default role.
 
 ### Google
 
-Set the following environment variables:
+Add these environment variables to enable Google sign-in:
 
 ```
 IMBI_AUTH_GOOGLE_CLIENT_ID=your-client-id
@@ -44,23 +50,37 @@ IMBI_AUTH_GITHUB_CLIENT_SECRET=your-client-secret
 
 ### Generic OIDC (Keycloak, Okta, etc.)
 
+Any OpenID Connect-compatible provider can be used:
+
 ```
 IMBI_AUTH_OIDC_CLIENT_ID=your-client-id
 IMBI_AUTH_OIDC_CLIENT_SECRET=your-client-secret
 IMBI_AUTH_OIDC_DISCOVERY_URL=https://your-idp/.well-known/openid-configuration
 ```
 
+!!! tip
+    Set `IMBI_AUTH_CALLBACK_BASE_URL` to the public URL of your Imbi
+    instance (e.g. `https://imbi.example.com`) so that OAuth callbacks
+    route correctly.
+
 ## Multi-Factor Authentication
 
-Imbi supports TOTP-based MFA. Users can enable MFA from their profile
-settings. When enabled, users must provide a time-based one-time password
-in addition to their primary credentials.
+Users can enable TOTP-based multi-factor authentication from their
+profile settings page. Once enabled, they will be prompted for a
+time-based one-time password after entering their credentials.
+
+MFA is optional and user-managed -- administrators cannot force it at
+this time, but it is recommended for accounts with elevated privileges.
 
 ## Sessions
 
-Sessions are managed via JWT tokens:
+Imbi manages sessions automatically:
 
-- **Access tokens** expire after 15 minutes
+- **Access tokens** expire after 15 minutes and are refreshed transparently
 - **Refresh tokens** expire after 7 days
 - Maximum 5 concurrent sessions per user
-- Session timeout (inactivity): 24 hours (configurable)
+- Session timeout (inactivity): 24 hours (configurable via
+  `IMBI_AUTH_SESSION_TIMEOUT`)
+
+Users do not need to manage sessions directly. If a session expires,
+they are redirected to the login page.

docs/docs/admin/blueprints.md

@@ -1,64 +1,66 @@
 # Blueprints
 
-Blueprints are customizable metadata schemas that extend the base project
-model with additional fields specific to your organization's needs.
+Blueprints let you define custom metadata fields for different types of
+projects in your service catalog. For example, you might create a
+"Microservice" blueprint that requires every microservice to specify its
+programming language and SLA tier, while a "Library" blueprint asks for
+documentation URL and supported platforms.
 
 ## How Blueprints Work
 
-Each blueprint defines a JSON Schema that describes additional metadata
-fields for projects. When a project is created with a blueprint, the
-project's metadata is validated against the blueprint's schema.
+Each blueprint defines a set of additional fields (as a JSON Schema)
+that are added to the project creation and edit forms. When someone
+creates a project and selects a blueprint, Imbi shows the blueprint's
+fields in the UI and validates them before saving.
 
 ## Creating a Blueprint
 
-```json
-POST /api/blueprints
-{
-  "name": "Microservice",
-  "description": "Schema for microservice projects",
-  "schema": {
-    "type": "object",
-    "properties": {
-      "language": {
-        "type": "string",
-        "enum": ["python", "go", "rust", "typescript"]
-      },
-      "framework": {
-        "type": "string"
-      },
-      "sla_tier": {
-        "type": "string",
-        "enum": ["tier1", "tier2", "tier3"]
-      }
-    },
-    "required": ["language", "sla_tier"]
-  }
-}
-```
+1. Navigate to **Settings > Blueprints** in the admin panel
+2. Click **New Blueprint**
+3. Fill in the name and description
+4. Define the fields using the schema editor:
+    - Add fields with types like text, number, select (dropdown), or
+      boolean
+    - Mark fields as required or optional
+    - For select fields, define the allowed values
+5. Click **Save**
+
+### Example
+
+A "Microservice" blueprint might define:
+
+| Field | Type | Required | Options |
+|-------|------|----------|---------|
+| Language | Select | Yes | Python, Go, Rust, TypeScript |
+| Framework | Text | No | - |
+| SLA Tier | Select | Yes | Tier 1, Tier 2, Tier 3 |
+
+When a user creates a new project with this blueprint, they see these
+fields alongside the standard project fields (name, description,
+team, etc.).
 
 ## Using Blueprints
 
-When creating a project, specify the blueprint to apply its schema:
-
-```json
-POST /api/projects
-{
-  "name": "my-service",
-  "blueprint_id": "blueprint-id",
-  "metadata": {
-    "language": "python",
-    "framework": "FastAPI",
-    "sla_tier": "tier1"
-  }
-}
-```
-
-The metadata will be validated against the blueprint's JSON Schema. If
-validation fails, the request is rejected with details about which fields
-are invalid.
+When creating or editing a project:
+
+1. Select a blueprint from the **Blueprint** dropdown
+2. Fill in the blueprint-specific fields that appear
+3. Required fields must be completed before the project can be saved
+
+The blueprint selection can be changed later, but metadata from the
+previous blueprint is not automatically migrated.
 
 ## Updating Blueprints
 
-Blueprint schemas can be updated over time. Existing projects are not
-retroactively validated against updated schemas, but new project
-creations and updates will use the current schema.
+Blueprint schemas can be updated over time as your organization's
+needs change. When you update a blueprint:
+
+- **New projects** use the updated schema immediately
+- **Existing projects** are not retroactively validated -- they keep
+  their current metadata until the next edit
+- When editing an existing project, the current schema is applied
+
+!!! tip
+    Start with fewer required fields and add more over time. It is
+    easier to make a field required later than to deal with existing
+    projects that are missing a newly required field.

docs/docs/admin/roles-and-permissions.md

@@ -1,61 +1,87 @@
 # Roles and Permissions
 
-Imbi uses a role-based access control (RBAC) system for authorization.
+Imbi uses role-based access control (RBAC) to manage what users can
+see and do. Permissions are grouped into roles, and roles are assigned
+to users.
 
-## Permissions
+## Built-in Roles
 
-Permissions are fine-grained access controls in the format
-`resource:action`. For example:
-
-- `projects:read` - View projects
-- `projects:write` - Create and update projects
-- `projects:delete` - Delete projects
-- `users:read` - View user profiles
-- `users:write` - Create and update users
-- `blueprints:read` - View blueprints
-- `blueprints:write` - Create and update blueprints
-
-## Roles
-
-Roles are named collections of permissions. Imbi ships with three
-default roles:
+Imbi ships with three default roles created during initial setup:
 
 ### Admin
 
-Full access to all resources and operations.
+Full access to everything: manage users, roles, organizations, teams,
+blueprints, and all project operations. Assign this role to platform
+administrators.
 
 ### Developer
 
-Read and write access to projects, blueprints, and related resources.
-Cannot manage users, roles, or system settings.
+Can view and manage projects, blueprints, and related resources. Cannot
+manage users, roles, or system-level settings. This is the typical role
+for engineering team members.
 
 ### Readonly
 
-Read-only access to all resources. Cannot create, update, or delete
-anything.
+Can view all resources but cannot create, edit, or delete anything.
+Useful for stakeholders who need visibility without write access.
 
-## Custom Roles
+## Assigning Roles
 
-Administrators can create custom roles with any combination of
-permissions via the REST API:
-
-```
-POST /api/roles
-{
-  "name": "Team Lead",
-  "permissions": [
-    "projects:read",
-    "projects:write",
-    "users:read",
-    "blueprints:read"
-  ]
-}
-```
+Roles are assigned to users within the context of an organization. A
+user can have different roles in different organizations -- for example,
+an admin in one org and a developer in another.
 
-## Assigning Roles
+To assign a role:
+
+1. Navigate to **Settings > Users**
+2. Select the user
+3. Under **Organization Memberships**, choose the role for each
+   organization the user belongs to
+4. Click **Save**
 
-Roles are assigned to users within the context of an organization. A user
-can have different roles in different organizations.
+## Group-Based Roles
+
+Instead of assigning roles to individual users, you can assign roles
+to groups. All members of the group automatically inherit the group's
+roles.
+
+This is the recommended approach for teams:
+
+1. Create a group (e.g. "Backend Team")
+2. Assign a role to the group (e.g. "Developer")
+3. Add users to the group
+
+When a user is added to or removed from the group, their effective
+permissions update immediately.
+
+## Custom Roles
 
-Roles can also be assigned to groups. All members of the group inherit the
-group's roles in addition to any individually assigned roles.
+If the built-in roles do not fit your needs, administrators can create
+custom roles:
+
+1. Navigate to **Settings > Roles**
+2. Click **New Role**
+3. Enter a name (e.g. "Team Lead")
+4. Select the permissions to include
+5. Click **Save**
+
+### Available Permissions
+
+Permissions follow a `resource:action` pattern:
+
+| Permission | Description |
+|------------|-------------|
+| `projects:read` | View projects and their metadata |
+| `projects:write` | Create and update projects |
+| `projects:delete` | Delete projects |
+| `users:read` | View user profiles |
+| `users:write` | Create and manage user accounts |
+| `blueprints:read` | View blueprints |
+| `blueprints:write` | Create and manage blueprints |
+| `roles:read` | View roles and permissions |
+| `roles:write` | Create and manage roles |
+
+!!! tip
+    Follow the principle of least privilege: start with the Readonly
+    role and add permissions as needed, rather than starting with Admin
+    and removing them.