Documentation

Getting Started

FaultPilot is a reliability, diagnostics and recovery engine for WordPress. After activation it walks you through a short onboarding: a welcome screen, an initial full diagnosis, and the creation of a baseline — the measured “normal” against which all future trends are compared. From that moment the engine observes live traffic and starts building your incident history.

A typical first session takes about five minutes: activate, run the initial diagnosis, review what was found, and skim the dashboard. You do not need to configure anything for the engine to work — sensible defaults apply, and everything is adjustable afterwards.

What to do first

• Run the initial diagnosis — 16 checks establish the site’s measured state.
• Review the risk breakdown — six components with per-factor explanations.
• Read the attention queue — anything the engine already noticed.
• Generate a recovery link — store it safely before you ever need it.

Installation

Install FaultPilot like any WordPress plugin: upload the zip through Plugins → Add New → Upload, or copy the plugin folder to wp-content/plugins/ and activate it in the Plugins screen. On multisite, use Network Activate — management capability is provisioned across the network, including sites created later.

After activation the onboarding flow starts automatically. No wp-config edits are required; there is nothing to chmod and no external service to sign up for.

Updating

Before every plugin, theme or core update, FaultPilot automatically captures a pre-update recovery point. Updates are recorded on the change timeline with their points, so a bad update can be rolled back in one action.

Uninstalling

Uninstalling removes everything: the engine’s database tables, options, transients, scheduled events, the Safe Mode drop-in and the plugin directory itself — verified against the core uninstall contract. WooCommerce and your other plugins are untouched. If you prefer to keep diagnostic history, export a report first.

Requirements

Configuration

FaultPilot works with defaults from the first minute. When you want control, configuration is grouped by concern:

• Observation — which signals to collect, sampling rate for deprecations, per-request buffer limits.
• Alerts — minimum severity, quiet hours, throttling and the email channel.
• Prevention — sweep thresholds for trends such as autoload growth or cron backlog.
• Recovery — Safe Mode arming, recovery link generation, quarantine scope.
• Data — retention windows for events, incidents and metrics; pruning runs in wp-cron.

Settings and state are stored with autoload = off, so configuration never weighs on front-end requests. A structured, versioned REST API (cookie authentication plus nonce, capability-checked) is available for automation — the same API powers the admin application.

Dashboard

The command center answers four questions at a glance: how healthy is the site, what needs attention, what changed, and what is at risk.

• Status & health ring — current site status (Healthy → Critical) with a health score that ships its deductions.
• Error trends — 24-hour signal volume, spikes annotated with the incidents they belong to.
• Risk breakdown — six components (reliability, updates, database, performance, compatibility, security), each factor visible.
• Attention queue — open incidents and prevention signals that need a human decision.
• Recent changes — updates, activations and config changes with their recovery points.

Everything on the dashboard is measured on this site. Sections without observable data say so instead of showing zeros that pretend to be data.

Incidents

Events sharing a fingerprint group into an incident — a stable object with an ID, severity, lifecycle and evidence, instead of a growing pile of log lines. Occurrences are counted and time-bounded; repeated hits merge so a flood stays readable.

Lifecycle

open → investigating → resolved, with automatic reopen when a resolved fingerprint recurs. Every transition is written to the activity log.

Evidence & recommendations

Each incident carries: the affected component (attributed by file path), the PHP stack trace when present, recent related changes, occurrence patterns, and related failures elsewhere in the system (for example Action Scheduler jobs failing for the same hook). The Root Cause Analyzer weighs this evidence and names a primary suspect with a confidence tier — Strong correlation, Likely cause, Possible cause, Insufficient evidence — together with the factors behind the verdict and a recommended action.

Diagnostics

The diagnostics suite runs 16 real checks — manually, during onboarding and daily. Each check reports a measured result, or an explicit skip with a reason when its subject is not observable (a check that cannot see something says so — it does not guess).

Results feed the health score, persist as daily metrics, and are read by the prevention engine as measured infrastructure state. The full list: PHP version, memory limit, disk space, TLS certificate, REST loopback, autoloaded options, transients, table sizes, cron health, Action Scheduler, error backlog, plugin compatibility, plugin health, theme health, WooCommerce, and security signals.

Structured and printable reports can be generated and exported at any time — for clients, post-mortems or your own records.

Recovery

Recovery is designed for the worst moment: the site is down and wp-admin may be down with it. Three mechanisms work together:

• Recovery points — the active component set captured automatically before every update, plus manual points; one click rolls the set back.
• Safe Mode — a must-use drop-in that quarantines failing components; see the Safe Mode section below.
• Single-use recovery links — 256-bit random tokens, HMAC-hashed at rest, expiring within 24 hours, rate-limited per IP, consumed on use. Generate one now and store it safely — it arms Safe Mode without wp-admin.

After any treatment, verification re-measures health — the error stream must stay quiet and key signals must pass. Recovery reduces the distance between failure and fix; it does not promise zero downtime, and it cannot repair bootstrap-level damage such as a corrupted database or wp-config (see the honest limits table on the Recovery page).

Safe Mode

Safe Mode is a small must-use drop-in that loads before regular plugins. When armed, it reads its quarantine option and filters the active plugin list — the failing component stops loading while everything else runs. It is the only file FaultPilot ever writes outside its own directory.

• No secrets inside — the drop-in contains no tokens and accepts no remote commands.
• Deletable — removing the file disables the feature cleanly.
• Rate-limited — token validation attempts are limited per IP; only failures count, and a valid token always passes and clears the counter.

Safe Mode arms through the admin UI when possible, or through a recovery link when wp-admin is unreachable. Quarantine scope is per component, and every arm/disarm action is audit-logged.

Alerts

Alerts are governed by shared rules across two channels — the dashboard notification center and a branded HTML email:

• Deduplication — repeated signals merge; you get one alert with an occurrence count, not fifty.
• Throttling — alert storms are paced; the channel never floods.
• Minimum severity — choose the floor; deprecations stay out of your inbox.
• Quiet hours — non-critical alerts wait for morning; critical ones do not.

Every alert links to the incident with its evidence already assembled. Preventive alerts (from the hourly sweep) use the same machinery — the goal is signal, and the goal is sleep.

WooCommerce

When WooCommerce is active, its intelligence layer activates automatically. It monitors and diagnoses:

• Checkout reliability — measured request outcomes with deterioration alerts.
• Action Scheduler — backlog depth, failed jobs, stuck hooks.
• Payment gateway and webhook HTTP failures — attributed with evidence via the API/Webhook Doctor.
• Plugin conflicts — PHP errors attributed to the exact component.
• Template overrides — outdated WooCommerce overrides reported before they break.
• HPOS-aware order signals — respects High-Performance Order Storage.

Boundary: FaultPilot never creates, modifies, refunds or cancels orders, and never touches payment or customer financial data. It observes, diagnoses and correlates — the fix stays in your hands. See the WooCommerce page for the full picture.

Performance

A reliability plugin that slows WordPress down is unacceptable — FaultPilot’s performance philosophy is enforced in code:

• Zero front-end overhead — collectors ride hooks that already run; no extra public requests.
• Admin assets only on FaultPilot screens — nothing is enqueued elsewhere.
• Buffered writes — events buffer per request and flush in batches; deprecations are sampled.
• Heavy work in wp-cron — prevention sweeps, diagnosis and pruning never run in the request path.
• Autoload-safe storage — settings and state stored with autoload off.

The Performance Doctor then measures the site itself: memory headroom, autoload weight and top offenders, REST loopback latency and slow-query signals — each with the doctor’s explain-first treatment flow.

Database

The Database Doctor covers the data-layer failure modes that actually hurt: autoloaded option bloat, transient buildup, table growth, and orphaned metadata. Its workflow is strict — analyze, explain, snapshot, confirm, execute, verify — and one rule is absolute: FaultPilot never deletes table data automatically.

Treatments require your explicit confirmation, and every treatment takes a snapshot first so it can be undone. The diagnostics suite measures table sizes and growth as part of the daily scan; findings feed the risk model’s database component.

Cron

The Cron Doctor watches scheduled work: overdue events, duplicate schedules, stuck jobs and the Action Scheduler backlog (pending depth and age, failed jobs with their hooks). Findings correlate with incidents — a failing queue is usually evidence for something else, and FaultPilot connects the dots automatically.

The prevention engine tracks backlog growth hourly and alerts before a stalled queue becomes a business problem (missed renewal emails, undelivered receipts). Duplicate cron events are reported with their origins so they can be cleaned safely.

Security

FaultPilot treats itself as security-sensitive software. The model, summarized:

• Least privilege — a dedicated management capability (mapped to administrators, filterable per role) guards every read and write; multisite access is super-admin-only.
• Nonce everywhere — all REST routes require cookie auth plus nonce; every state change re-checks capability.
• Prepared SQL only — no dynamic table or column names from input.
• Recovery security — hashed single-use tokens, 24-hour expiry, per-IP rate limiting (failures only), full audit trail, and a drop-in with no secrets and no remote commands.
• Data minimization — file paths and line numbers, not payloads; sensitive keys redacted recursively at capture; login failures never store usernames; recovery tokens stored only as hashes.
• No call-home — no external AI, telemetry or license beacons in the request path.

Report vulnerabilities through the contact form (topic: Security) — reports are treated as the priority they are.

Troubleshooting

The site is down and wp-admin shows an error

Use the recovery link you generated earlier — it arms Safe Mode without logging in. Then read the incident: the failing component is attributed with evidence. If the failure traces to an update, roll back to the pre-update recovery point.

No recovery link was generated

Generate recovery links proactively — that is the point. Without one, disable the failing plugin by renaming its folder over SFTP/SSH (equivalent to what Safe Mode automates), then use the incident evidence to plan the real fix.

An alert never arrived by email

Check whether wp_mail works on your host at all (the mail-failure signal will show it), and whether quiet hours or the minimum-severity threshold held the message. The alert center shows every alert with its routing decision.

A check says “not observable”

Some hosts block loopback requests or hide disk metrics. A skipped check reports why; it is not an error — it is the engine refusing to invent a number. The rest of the suite continues to work.

FaultPilot data needs removing completely

Uninstall removes tables, options, transients, scheduled events, the drop-in and the plugin directory. If anything appears to remain, verify you uninstalled (deactivated only ≠ removed) — and contact support with the details.

FAQ

Does FaultPilot replace backups?

No. Recovery points capture the active component set for rollback — the complement to real backups, not a substitute. Keep full file and database backups; FaultPilot helps you avoid needing them.

Does it slow my site down?

It is built not to: zero front-end requests, admin assets only on its own screens, buffered batch writes, sampled deprecations, heavy work in wp-cron, autoload-off storage.

Does it use AI or send my data anywhere?

No. A structured diagnostic-context endpoint exists for a future AI layer, but nothing depends on an external service and nothing leaves your server by itself.

Is it compatible with multisite?

Yes — network activation provisions capability across sites (including sites created later), data is network-global and access is restricted to super admins.

Can it fix everything?

No — and it says so. Plugin and theme failures, including ones that break wp-admin: yes. Bootstrap-level damage (wp-config, database corruption, host outage): no plugin can, and honest tooling admits it.

Is WooCommerce required?

No. WooCommerce intelligence activates automatically when WooCommerce is present; every other capability works regardless.