# Plugin Settings Requirements

## Purpose
Define implemented setup/settings and diagnostics behavior for the calendar plugin admin pages.

## Scope
This document covers:

- Admin menu structure for plugin management pages
- Setup page controls and persisted settings
- Diagnostics page and diagnostics download behavior

## Admin Navigation
The plugin must provide a single WordPress admin menu entry with these pages:

- Top-level menu: `Calendar Plugin`
- Sub-pages: `Setup`, `Users`, `Diagnostics`
- Access capability: `manage_options`

The top-level duplicate submenu entry should be removed so only the explicit pages appear in navigation.

## Setup Page
The Setup page must support:

- Saving plugin settings
- Seeding default events
- Deleting all event and recurrence-exception data

Setup form controls:

- `CalDAV/ICS Calendar Name` (`caldav_calendar_name`)
- `URL Slug Prefix` (`url_slug`)
- `Verification Page Path` (`verification_page_path`)
- `Plugin Table Prefix` (`table_prefix`)
- `ICS Access Mode` (`ics_access_mode`: `public_read` or `authenticated_read`)
- `Diagnostics Enabled` (`diagnostics_enabled`)
- `Uninstall Cleanup` (`uninstall_cleanup_mode`: `keep` or `remove`)

Behavior requirements:

- Save, seed, and delete-all actions provide success/failure messaging on the Setup page.
- Setup POST actions are nonce-protected.
- `table_prefix` updates rename plugin tables (events, exceptions, users, tokens, audit log) without dropping existing data.
- Prefix changes must fail safely if target tables already exist.
- `url_slug` affects canonical routed paths for ICS and CalDAV endpoints.

## Settings Persistence
- Settings are persisted through plugin options storage and returned by the admin settings API (`/wp-json/calendar/v1/settings`).
- Runtime endpoints and UI links must reflect the latest saved settings.

## Diagnostics Page
The Diagnostics page must be admin-only and show:

- Whether diagnostics are enabled
- Runtime metadata snapshot (generation time, endpoint paths, user context, table stem)
- Recent audit log rows when diagnostics are enabled

Diagnostics download behavior:

- Download action is available only when `diagnostics_enabled=1`
- Download uses a nonce-protected admin-post action
- Response is JSON attachment (`calendar-diagnostics-*.json`)

## Security and Access
- Setup, Users, and Diagnostics pages require `manage_options`.
- Form actions must validate WordPress nonces.
- Inputs must be sanitized/normalized before persistence.