Admin

# Admin

The Admin page (`/admin`) is the control center for your workspace. It is only accessible to users with the `owner` or `admin` role. The page is organized into tabs, each governing a distinct part of the platform.

## Overview

Admin tabs:

| Tab | What you manage |
|---|---|
| **Tenant** | Current workspace name, switch between organizations, create new ones |
| **Members** | Invite users, view the team roster, change roles |
| **Roles** | View role definitions and permission sets |
| **Data Types** | Create and edit record schemas; link to the field config editor |
| **Public Data Types** | Enable/disable shared data types provided by the platform |
| **Agents** | Create and configure AI agents; view the org chart |
| **Navigation** | Customize the sidebar sections and item order |
| **Skills** | Manage reusable agent skill bundles |
| **Jobs** | Monitor Inngest background job history |
| **Models** | Configure available AI models per context |
| **Costs** | Track AI token usage and spending by agent and model |
| **Webhooks** | Register outbound HTTP hooks for platform events |
| **API Keys** | Generate, view, and revoke programmatic access keys |
| **Connections** | Configure external agent connections (OpenClaw, A2A, MCP) |
| **Sources** | Configure monitored content sources, preview feeds, and pick target records |
| **Platform** | Read-only platform info: stack, record counts, tenant count |

## How It Works

### Tenant management

The Tenant tab shows your active workspace name, slug, and your role. If you belong to multiple organizations, the Switch Tenant card lets you change context. Use **Create Tenant** to spin up a new isolated workspace — you become its admin automatically.

### Member management

Invite users by email from the Members tab. New users are provisioned with `guest` role by default (read-only). Admins can promote members to `member`, `viewer`, `admin`, or (for system admins) `owner`. You cannot change your own role.

### Data Types (record schemas)

Each data type card shows its name, description, field list, and record count. Click the edit icon to open the full data type admin at `/admin/entity-types/[slug]`, which has:

- **Schema editor** — Add, remove, or rename JSON schema fields
- **Field config editor** — Set display labels, rendering hints (currency, percentage), and AI extraction instructions per field
- **Views tab** — Create and edit block-based views for the list and detail pages

Use **Create Data Type** to define a new schema from scratch.

### Customization Map

The Customization Map tab shows how each data type is rendered across the supported entity surfaces: card, detail, list, form, and share. Each slot reports the active tier:

- **Platform code** — default platform component registration
- **Tenant code** — tenant module or tenant-scoped code registration
- **Tenant DB** — tenant-scoped artifact binding from the artifact catalog
- **Workspace DB** — workspace-scoped artifact binding that overrides tenant-level behavior
- **None** — no explicit component or binding for that slot

Use the slot-kind and source-tier filters to find DB-authored components, code-only surfaces, and missing customization coverage. Expanding a row reveals binding metadata such as artifact slug, version/status, workspace scope, priority, and update timestamps.

### Agents

The Agents tab lists all DB-managed agents with their system prompt preview, tool groups, and enabled/scheduled status. Code-defined agents (always available) appear in a separate read-only list at the bottom.

Click an agent name to go to `/admin/agents/[id]` for:
- Full run history
- Heartbeat schedule and last-run status
- Config version history
- Manual trigger button

The Org Chart visualizes reporting relationships between agents.

### API Keys

Generate API keys with a name and optional scope. Keys are shown once at creation — store them securely. Revoke a key at any time. Keys authenticate requests to `/api/*` routes that accept the `x-api-key` header.

### Connections

Configure external agent integrations:
- **OpenClaw / A2A** — Register external agents reachable via HTTP for delegation
- **MCP servers** — Connect Model Context Protocol servers for additional tool sets

Test connections and discover available tools from this tab.

### Sources

The Sources tab provides a guided source-sync editor rather than a raw entity form. It supports source presets, connection selection, monitored-record picking, preview-before-save, and source-specific filtering. The tab uses React Query hooks for source lists, relation lookup, preview, validation, and save invalidation so the UI stays responsive without ad hoc effect-driven fetches.

Source saves are validation-gated. The platform normalizes legacy source types from the URL, runs a live preview/validation check, and only leaves a source in a syncable state when validation succeeds. Invalid or blocked sources are saved with an error state instead of being marked active.

The page also exposes source-sync operations directly in the admin surface:

- **Queue stats** — queued items, items still awaiting workflow handoff, records needing review, and errored sources
- **Recent source runs** — each source’s latest sync summary with created, duplicate, and filtered counts
- **Needs attention queue** — source items with document upload failures, stale queued state, or missing workflow handoff markers

This adds the operational visibility of a news-ingestion control room without baking a product-specific news model into the platform.

Website monitors also expose a scrape strategy:

- **Auto** — default, keeps the built-in HTTP + Readability pipeline
- **HTTP + Readability** — lightweight fetch and DOM extraction
- **Firecrawl** — remote browser-backed scrape for dynamic or JS-heavy sites
- **Browser Agent** — routes website monitoring through a source-capable OpenClaw or A2A browser agent connection for sites that need real browser/computer-use navigation

For Browser Agent monitors, create a connection from the Connections tab using the `Browser Monitoring Agent` preset or edit an existing OpenClaw/A2A connection and enable the `Source monitoring` capability. Then set the **Browser Monitoring Agent ID** field to the external agent identifier that should perform the monitoring, such as `chippy`.

## Manual Test Script

### Prerequisites

- Logged in as `owner` or `admin` role
- At least one data type and one member in the workspace

### Happy Path

1. **Navigate to Admin**
   - Go to `/admin`
   - Expected: Tabs render; first tab (Tenant) is active by default

2. **View tenant context**
   - Expected: Tenant name, slug, role, and email are displayed correctly

3. **Switch tabs**
   - Click Members tab
   - Expected: Member list loads with email, display name, and role badge for each user

4. **Create an agent**
   - Click Agents tab > **New Agent**
   - Fill in name, system prompt, select tool groups
   - Expected: Agent card appears in the list after save

5. **Generate an API key**
   - Click API Keys tab > **Generate Key**
   - Expected: Key value shown once; row appears in the list with name and creation date

6. **Check costs**
   - Click Costs tab
   - Expected: Token usage and spend displayed per agent and model (empty state if no AI calls yet)

### Edge Cases

- **Member tab with one member (yourself):** Role change UI is disabled for your own row
- **Data type with no fields:** Card shows "No fields defined"; clicking edit opens empty schema editor
- **Agent with heartbeat enabled:** "scheduled" badge visible on the agent card
- **External connection test fails:** Error message displayed inline; connection is not saved

### Regression Checks

- [ ] Viewer and member roles cannot access `/admin` (redirect or 403)
- [ ] Creating a data type without a name shows a validation error
- [ ] Deleting a member removes them from the Members list without page reload
- [ ] API key is shown exactly once; subsequent page reloads show only masked value

## Troubleshooting

| Symptom | Likely Cause | Fix |
|---|---|---|
| Admin page shows 403 | User is `member` or `viewer` role | Promote to `admin` via another admin account |
| Agent not appearing in chat | Agent `enabled` is false | Toggle enabled in the agent dialog |
| Webhook not firing | Endpoint URL unreachable from Inngest | Verify URL is publicly accessible; check Inngest delivery logs in Jobs tab |
| API key requests returning 401 | Key was revoked or wrong header name | Use `x-api-key: \{key\}` header; generate a new key if needed |