# Agent and WordPress Scaffold Design

## Purpose

Create a private GitHub repository for the rebuild of `https://phyllisschlafly.com`.
Place the repository in the `Eagle-Forum-Education-Legal` GitHub organization.
Provide safe placeholders for Agent access to the current WordPress site.
Provide a local WordPress development environment.

## Repository

- Name: `PS-Site-Rebuild`
- Owner: `Eagle-Forum-Education-Legal`
- Visibility: Private
- Default branch: `main`

## Structure

```text
PS-Site-Rebuild/
├── AGENTS.md
├── README.md
├── .env.example
├── .gitignore
├── docker-compose.yml
├── docs/
│   ├── ACCESS.md
│   ├── SAFETY.md
│   └── SITE-INVENTORY.md
├── agent/
│   ├── browser/
│   ├── wordpress-mcp/
│   ├── rest-api/
│   ├── ssh/
│   ├── wp-cli/
│   └── database/
├── scripts/
│   ├── validate-environment.sh
│   ├── validate-mu-plugin-loader.sh
│   ├── wp-read.sh
│   └── db-read.sh
├── tests/
│   └── playwright/
└── wp-content/
    ├── themes/
    │   └── custom-theme/
    ├── plugins/
    │   └── custom-plugin/
    └── mu-plugins/
        ├── custom-mu-plugin.php
        └── custom-mu-plugin/
```

## Agent access

### Browser and Playwright

Add a Playwright project for public page inspection.
Use `https://phyllisschlafly.com` as the default base URL.
Do not authenticate by default.
Store optional credentials in environment variables.

### WordPress MCP

Add a placeholder configuration and setup instructions.
Do not select a specific WordPress MCP server until the operator approves it.
Keep the server disabled until the operator supplies credentials.

### WordPress REST API

Add placeholders for the site URL, user name, and application password.
Use read-only requests in example commands.
Do not store application passwords in Git.
Use a `rest` validation mode for `SITE_URL` and the REST placeholders.
The `rest` mode validates configuration only.
The `rest` mode does not authenticate.
Run the public REST check through `scripts/rest-public-read.sh`.
Remove REST credential placeholders before the script runs `curl`.

### SSH filesystem access

Add placeholders for the host, port, user, key path, known-hosts path, and WordPress path.
Require a restricted SSH account.
Disable SSH client configuration files.
Do not include a private key.
Use read-only example commands.
Use an `ssh` validation mode for only the SSH variables and remote path.

### WP-CLI

Add an SSH-based wrapper for remote read commands.
Allow only an explicit set of read commands by default.
Require an operator to run write commands without the wrapper.
Run the wrapper through the `ssh` environment mode.

### Git repository

Track custom themes, custom plugins, must-use plugins, configuration templates, documentation, and tests.
Exclude WordPress core, uploads, caches, logs, database exports, dependencies, and secrets.

### Read-only database inspection

Add placeholders for the database host, port, name, user, password, and TLS settings.
Require a database account with `SELECT` permission only.
Disable MySQL option files and login paths.
Add a wrapper that rejects SQL that does not start with `SELECT`, `SHOW`, `DESCRIBE`, or `EXPLAIN`.
Reject MySQL client commands and backslash escapes.
Do not connect the local environment to the production database.
Use a `database` validation mode for only the database variables.

### Environment loading

Use `local`, `rest`, `ssh`, and `database` as the only environment modes.
Reject the old combined `remote` mode.
Clear all repository contract variables before file parsing.
Accept only known `NAME=VALUE` entries from the reviewed file.
Export only the variables for the selected mode.
Do not pass stale ambient contract values to validation or child commands.

## Local development

Use Docker Compose for local WordPress and database services.
Use safe local-only passwords from `.env.example`.
Use `mariadb:11.4.12@sha256:a794d9eb009e20de605858a11f32f63b4075cbd197c650436f0e3b457e4caed7`.
Use `wordpress:6.9.1-php8.3-apache@sha256:ffef0dca1f0fc4357bfef3856ebd1ba18f7b394378277122eaa4524ca2619d43`.
Bind the WordPress port only to `127.0.0.1:8080`.
Mount each tracked custom component directory to its matching WordPress component directory.
Mount `custom-mu-plugin.php` as read-only at the must-use plugin root.
Load readable PHP files from `custom-mu-plugin` in name order.
Do not mount a tracked parent directory that receives bundled WordPress content.
Use container restart policies and service healthchecks.
Do not copy production data or uploads.

## Data flow

The browser tools read public pages from the site.
The REST API reads structured WordPress content.
SSH and WP-CLI inspect the remote filesystem and WordPress state.
The database tool uses a separate read-only account for limited inspection.
Git stores approved source files and configuration templates.
The local environment runs isolated WordPress services.

## Safety

Disable production write operations by default.
Keep all credentials outside Git.
Use least-privilege accounts for each connection.
Require explicit operator action for production changes.
Do not add automated deployment in the initial scaffold.
Do not add database import or export automation.

## Error handling

Validation scripts will list missing environment variables.
Wrapper scripts will reject unsupported commands before connection.
Remote tools will stop when host keys, credentials, or paths are missing.
Tests will report the failed page or configuration check.

## Validation

GitHub Actions will run local checks only.
The workflow will not connect to production.
Checks will validate shell syntax, configuration templates, and Playwright tests.
`tests/shell/guards.bats` will run as a standalone Bash harness.
The workflow will not install Bats because the test harness does not use the Bats executable.
The checkout step will fetch full history and will not persist credentials.
The workflow will check committed changes from the event base to `HEAD`.
The workflow will compare Git's empty tree to the complete `HEAD` tree when the event base is missing or all zeros.
The workflow will validate commit values before it passes a quoted range to Git.
The local smoke test will confirm that WordPress responds after startup.

## Acceptance criteria

- The private repository exists in the correct GitHub organization.
- The default branch is `main`.
- The repository contains each approved placeholder.
- The repository contains no credentials or private keys.
- The local WordPress environment starts from documented commands.
- Read wrappers reject production write operations.
- Automated checks do not connect to production.