# AI Web Command SaaS: Fields And Navigation

Status: implementation source of truth. The local UI MVP is available; identity, database persistence, Woo bridge synchronization, and the hosted MCP gateway are the next backend milestones.

## Product Role

The SaaS is the account and control center for AI Web Command. It does not directly edit WordPress content. The installed WordPress plugin performs approved site actions; the SaaS owns identity, site enrollment, licenses, subscriptions, MCP access, cross-site jobs, and organization-level audit visibility.

## Global App Shell

### Primary Sidebar

| Tab | Purpose | Primary action |
| --- | --- | --- |
| Overview | Organization health, active sites, recent actions, plan usage, attention items. | Add site |
| Sites | List and manage every enrolled WordPress site. | Add site |
| Activity | Searchable cross-site audit trail and job activity. | Export activity |
| MCP Access | Connect ChatGPT, Claude, and compatible clients through one secure AI Web Command MCP connection. | Create connection |
| Team | Invite and manage organization members and access roles. | Invite member |
| Billing | Subscription, plan limits, and the customer billing portal. | Manage billing |
| Settings | Organization profile, security defaults, notifications, and data controls. | Save changes |

### Global Header

| Element | Behavior |
| --- | --- |
| Organization switcher | Shows current workspace; supports future multi-organization users. |
| Site context switcher | Optional filter for a site; defaults to all sites. |
| Command/search | Searches sites, jobs, and activity. Later can open a command palette. |
| Notifications | Connection failures, license issues, expired credentials, failed jobs. |
| Account menu | Profile, security, sign out. |

## Auth And First-Run Flow

### Sign In

| Field | Required | Notes |
| --- | --- | --- |
| WooCommerce account email | Yes | Used only to open the customer account portal. |
| WooCommerce session | Yes | The store verifies the logged-in customer and starts signed SSO. |

There is no independent SaaS account, password, signup form, or second billing identity. WooCommerce and WooCommerce Subscriptions own customer registration, sign-in, password recovery, invoices, subscription state, and payment methods. The store-side bridge sends a short-lived HMAC-signed SSO payload with customer ID, email, display name, nonce, and issue time. The SaaS accepts it once, creates or updates the matching workspace, and issues an HTTP-only session.

### Onboarding

1. Register or sign in through the WooCommerce customer portal.
2. Choose subscription or trial in WooCommerce.
3. Return through signed SSO and add the first WordPress site.
4. Install and activate the plugin.
5. Generate a scoped plugin enrollment token and paste it once into the SaaS.
6. Validate site ownership, remote access, HTTPS, and minimum plugin version.
7. Create or copy the MCP connection details.

The onboarding UI should show progress, never make the user discover these steps from a blank dashboard.

## Overview

### Information Blocks

| Block | Data |
| --- | --- |
| Licensed sites | Used / included / available slots. |
| Site health | Connected, needs attention, disconnected. |
| MCP connections | Active connections and last use. |
| Work completed | Agent actions and jobs over 7/30 days. |
| Chat usage | Only for sites with AI Chat enabled: messages, tokens, estimated customer-provided API cost. |
| Needs attention | Expired licenses, disabled remote access, outdated plugin, failed jobs, required re-auth. |
| Recent activity | Timestamp, actor, site, action, outcome. |

### Actions

- Add site
- Open site details
- Open failed job
- Manage subscription
- Open MCP setup

## Sites

### Sites List Columns

| Column | Meaning |
| --- | --- |
| Site | Display name, URL, environment badge. |
| Status | Connected, attention, disconnected, paused. |
| License | Active, trial, grace period, expired, suspended. |
| Plugin | Installed version and update indicator. |
| Last seen | Last authenticated heartbeat. |
| Activity | Recent agent actions. |
| Actions | Open, reconnect, pause, remove. |

### Add Site Form

| Field | Required | Validation / behavior |
| --- | --- | --- |
| Site display name | Yes | Human-readable label. |
| Full site URL | Yes | HTTPS URL, normalized; no WordPress admin URL. |
| Environment | Yes | Production, staging, development. Staging does not consume a paid site slot only if the final plan permits it. |
| Plugin enrollment token | Yes | Paste once; exchange immediately; never display or retain raw token. |
| Default MCP permissions | Yes | Read-only, standard operations, or custom. Final permissions are enforced by the plugin too. |
| Notes | Optional | Internal team note, not sent to plugin. |

### Site Detail Tabs

| Tab | Contents |
| --- | --- |
| Overview | Connection state, license, capabilities, plugin version, health, quick actions. |
| Connection | URL, site ID, last heartbeat, enrollment/reconnect controls, remote access status, plugin upgrade state. |
| Capabilities | Read-only catalogue of what the installed plugin reports, grouped by content, builders, commerce, SEO, community, and operations. |
| Activity | Site-filtered immutable audit trail and job outcomes. |
| AI Chat | License entitlement, widget status, knowledge freshness, scan status, usage and handoff metrics. No customer AI key is stored in the SaaS. |
| Security | Credential rotation history, permission defaults, allowed MCP connections, emergency pause, data retention. |

### Site Actions

- Reconnect site
- Rotate SaaS-to-plugin credential
- Pause all remote actions
- Resume actions
- Request plugin update
- Remove site after confirmation

Removal must revoke SaaS credentials first. It must not silently delete WordPress data.

## MCP Access

### MCP Connections List

| Field | Meaning |
| --- | --- |
| Connection name | User-defined label, such as `Daniel - ChatGPT`. |
| Client type | ChatGPT, Claude, custom, unknown. |
| Permissions | Organization-level and site-level allowed scope. |
| Allowed sites | All sites or selected sites. |
| Last used | Last successful tool call. |
| Status | Active, expired, revoked. |

### Create MCP Connection

| Field | Required | Notes |
| --- | --- | --- |
| Connection name | Yes | Human-readable. |
| Client type | Yes | ChatGPT, Claude, Custom MCP client. |
| Site access | Yes | All active sites or selected sites. |
| Permission profile | Yes | Read-only, standard, custom. |
| Require approval for writes | Yes | Default on for content, commerce, settings, plugins, and snippets. |
| Expiry | Optional | Recommended for client-specific access. |

### Connection Output

After creation, show a copyable MCP server URL or platform-specific connection instructions once. Secrets must be masked after the first display; rotate instead of revealing later.

## Activity And Jobs

### Activity Filters

- Date range
- Site
- Actor: MCP connection, organization member, system
- Operation group: content, builder, commerce, SEO, community, operations, chat
- Result: success, failed, denied, pending approval
- Risk level: read, write, destructive

### Activity Row

| Field | Meaning |
| --- | --- |
| Time | UTC storage; local display. |
| Site | Affected site. |
| Actor | MCP connection, user, or system process. |
| Operation | Plain-language action plus technical endpoint. |
| Outcome | Success, failed, denied, awaiting approval. |
| Details | Sanitized request summary, checkpoint, rollback link where supported. |

### Multi-Site Jobs

Use for a single approved action across selected sites, such as updating a footer year or a telephone number. Required fields:

| Field | Required | Notes |
| --- | --- | --- |
| Job name | Yes | Human-readable. |
| Target sites | Yes | Explicit selected set. |
| Requested change | Yes | Structured operation or MCP-generated plan. |
| Dry run | Yes | Default enabled. |
| Approval | Yes for writes | Per job approval record. |
| Schedule | Optional | One-off initially; recurring later. |

Job status: draft, awaiting approval, queued, running, partially complete, complete, failed, canceled.

## Team

### Team Fields

| Field | Required | Notes |
| --- | --- | --- |
| Name | Yes | Display name. |
| Email | Yes | Unique invitation destination. |
| Role | Yes | Owner, Admin, Operator, Viewer. |
| Site access | Yes | All sites or selected sites. |
| Invitation expiry | Automatic | Default seven days. |

Role intent:

- Owner: billing, organization deletion, all sites, all security controls.
- Admin: sites, team, MCP, operations, no ownership transfer.
- Operator: selected-site operations, cannot change billing or team.
- Viewer: read-only dashboard, activity, and reports.

## Billing

### Billing Page

| Block | Data / action |
| --- | --- |
| Current plan | Plan name, price, renewal date, included active production sites. |
| Usage | Licensed sites used, chat entitlement, multi-site jobs entitlement. |
| Upgrade options | Solo (1 site), Growth (10 sites), Agency (30 sites). Prices and entitlements are synchronized from the SaaS plan catalogue. |
| Billing portal | Opens the WooCommerce account portal where the customer manages payment method, invoices, and subscription changes. |
| Billing contact | Name and email. |

For the initial product, WooCommerce Subscriptions is the billing source of truth. A store-side Woo bridge will map subscription lifecycle events to a signed SaaS entitlement payload containing only the organization, plan, status, renewal period, and allowed production-site count. The SaaS does not accept, process, or store card details. Keep the entitlement integration behind a billing adapter so a future direct Stripe implementation can be added without changing licensing, MCP, or site-enrollment logic.

### Initial Plan Entitlements

| Plan | Monthly | Annual prepay | Sites | Included SaaS features |
| --- | ---: | ---: | ---: | --- |
| Solo | $15 | $119 | 1 | Core agent, site-level audit history, BYOK AI Chat |
| Growth | $39 | $299 | 10 | Solo plus chat analytics, multi-site jobs, 10 restricted client seats |
| Agency | $89 | $699 | 30 | Growth plus white-label chat and 30 restricted client seats |

All recurring plans begin with a 7-day trial. Any advertised money-back period
must be implemented in the WooCommerce policy and reviewed Terms before launch.
Client seats must be site-scoped and cannot access billing, provider keys, MCP
secrets, or organization-wide operations.

## Settings

### Organization

| Field | Required |
| --- | --- |
| Organization name | Yes |
| Billing contact name | Yes |
| Billing contact email | Yes |
| Timezone | Yes |
| Default language | Yes |

### Security Defaults

| Field | Default |
| --- | --- |
| Require approval for write operations | On |
| Require approval for destructive operations | On and not disableable at organization level |
| Default MCP permission profile | Read-only |
| Credential expiry for new MCP connections | 90 days |
| Session timeout | Configurable policy |
| Notify on failed connection / license issue | On |

### Data And Notifications

| Field | Purpose |
| --- | --- |
| Activity retention | Organization-level retention policy. |
| Job result retention | Retention policy for job metadata, not WordPress content. |
| Email notifications | Connection, job, billing, and security events. |
| Webhook endpoint | Future feature; signed outbound events only. |

## Core Data Model For Engineering

The first Prisma schema should center on these entities, not the Review Nest schema:

- `User`
- `Organization`
- `OrganizationMember`
- `Subscription`
- `Plan`
- `Site`
- `SiteCredential` (hashed credential metadata only)
- `SiteHeartbeat`
- `McpConnection`
- `McpConnectionSiteAccess`
- `OperationApproval`
- `Job`
- `JobTarget`
- `AuditEvent`
- `Notification`
- `Invitation`

Important relationships:

- A user can belong to multiple organizations.
- An organization owns many sites and one current subscription.
- A site has many rotated credentials, heartbeats, audit events, and job targets.
- An MCP connection belongs to one organization and can have restricted site access.
- All write operations must be traceable to an MCP connection or organization member.

## Security Requirements

- Store no raw plugin enrollment token after the exchange completes.
- Store no customer AI provider key in the SaaS; it remains inside the WordPress plugin.
- Hash long-lived credentials; show a secret only once.
- Use signed request bodies, timestamps, nonce/replay protection, and constant-time comparison for SaaS-to-plugin or billing webhooks.
- Enforce permission checks twice: in SaaS before routing and in the WordPress plugin before execution.
- Default to dry run and explicit approval for write, plugin, theme, settings, snippet, and commerce actions.
- Keep immutable audit records with sanitized request summaries.
- Support immediate emergency pause and credential revocation.

## Design Direction

- Premium operational SaaS, not a marketing landing page: quiet, dense, highly scannable.
- White/light neutral background, restrained accent color supplied by the logo direction, clear operational states.
- Avoid oversized cards. Use full-width data sections, concise page headers, predictable sidebar navigation, and icon-first compact actions.
- Every empty state must have one obvious next action.
- Responsive behavior: sidebar becomes a drawer; site tables become structured list rows; approval controls remain visible without horizontal clipping.