# WP Vibecoder

WP Vibecoder synchronizes a WordPress theme from a GitHub repository into a WordPress installation. It does not generate code, call an AI API, or provide a page builder.

WP Vibecoder and its starter remain at version `1.0` during private development
and testing. Version progression begins when the plugin is prepared for its
official WordPress.org release.

## Requirements

- WordPress 6.0 or newer
- PHP 7.4 or newer
- OpenSSL PHP extension for encrypted token storage
- A server that can make outbound HTTPS requests to `api.github.com`

## Installation

1. Copy the `vibecoder-theme-sync` directory into `wp-content/plugins/`.
2. Activate **WP Vibecoder** in WordPress.
3. Open **WP Vibecoder** in the admin menu.
4. Save a GitHub repository URL and branch. Add a fine-grained personal access token when the repository is private.
5. Use **Connect & import** in Setup, then activate the theme from Setup or **Themes**.

## Admin workflow

The admin interface is organized into Setup, Themes, Backups, Logs, and
Settings tabs.

Setup currently supports **Existing project → Manual connect**. A single
**Connect & import** action saves the GitHub settings, checks API access,
downloads the branch, validates the WP Vibecoder contract, and imports the
theme into WordPress. Successful setup shows the project name, theme version,
branch, repository, and theme screenshot.

Each WordPress site has one connected repository at a time. **Disconnect**
clears the current repository connection before another can be connected,
while preserving themes that were already imported or installed.

The **Themes** tab imports the validated theme and lists themes previously
managed by WP Vibecoder. A theme can be activated directly from this screen
without opening **Appearance > Themes**. Automatic activation after import
remains optional and is disabled by default.

Setup displays the connected repository, last synchronization time, and current
commit. Action confirmations and operation results are presented as in-admin
modals and toast popups instead of browser alerts. Repository connection and
validation progress is also displayed in a blocking popup until the request
finishes. After import, **Activate Theme** is the primary Setup action. Once the
theme is active, that action becomes a visible **Active** status and
**View Site** remains the primary action.

The project summary includes the connected branch. Administrators can switch
to another repository branch from Setup; WP Vibecoder validates and imports the
selected branch before saving it as the branch to monitor. The previous branch
theme remains installed as a rollback option.

WP Vibecoder compares the imported commit with the current HEAD of the connected
GitHub branch. Setup includes the branch name and shows statuses such as
**main · Up to date**, **main · Update available**, or
**main · Could not check** beside the commit. When an update is available,
**Sync main** downloads, validates, backs up, and installs the latest commit
from that branch. The GitHub status check is cached for two minutes.

## Pristine starter detection

WP Vibecoder calculates a repository fingerprint during validation. When the
repository exactly matches a compatible official pre-release starter fingerprint,
Setup displays a dedicated **Ready to vibecode** onboarding screen with Codex,
Claude, and Gemini as compatible agent options. All recognized pre-release
starters are presented as version `1.0`.

The screen explains that the repository already contains agent context through
`AGENTS.md`, `CLAUDE.md`, and `agent.md`, then guides the user to open the
repository, describe the website, commit and push the current branch, and sync
the resulting commit back into WordPress. Functional repository file changes
break the pristine fingerprint and return Setup to the normal project status
screen after synchronization. Non-functional documentation/control files such as
`README.md`, `.gitignore`, and `.DS_Store` are excluded from the comparison.

Agent actions are built from the connected repository URL:

- Claude Code copies `claude github.com/owner/repository`.
- Cursor opens the `cursor://vscode.git/clone` deep link.
- Codex opens `https://chatgpt.com/codex`.
- Gemini copies the repository URL and opens `https://gemini.google.com`.

The ready screen prioritizes the final result: connected WordPress site,
GitHub repository, and branch. It includes direct copyable example prompts and
a four-step visual workflow through the manual WordPress branch sync. The base
starter screenshot is intentionally omitted from this onboarding state.

The onboarding flow is organized into four explicit steps: choose one of four
equal agent options, copy a starter prompt, open the selected agent, then sync
WordPress after pushing a new commit. Prompt buttons keep a copy icon and use a
subtle success state instead of replacing their labels.

When GitHub reports a different branch HEAD, the final step changes to
**New commit detected**, **Ready to sync**, and presents a
**Sync to WordPress** action.

While the AI-ready setup screen is open, WP Vibecoder checks the connected
branch in the background without reloading the page. Checks run every 30
seconds when a GitHub token is configured and every 75 seconds without one,
pause while the browser tab is hidden, and back off automatically after API
errors. Detection never applies repository changes automatically; the
administrator must confirm **Sync to WordPress**.

New project generation and connected-GitHub repository browsing are visible as
separate setup flows. **Create new project** can create a GitHub repository from
the WP Vibecoder starter through the WP Vibecoder API, or open the public
starter template on GitHub. The plugin does not bundle a starter ZIP. Automatic
GitHub authentication can create a repository from the configured starter,
browse authorized installations, select any available branch, and import
public or private repositories without storing GitHub access tokens in
WordPress. The repository's default branch is selected first.

## Expected repository contract

The repository root must contain:

- `wp-vibecoder.json`
- `agent.md`

WP Vibecoder identifies the managed theme by repository URL, branch, and
`themeFolder`. `Theme Name`, `name`, screenshots, branding, and content are
display metadata only; changing them updates the same managed theme.

The configured theme folder (default: `theme`) must contain:

- `style.css` with `Theme Name` and `Version` headers
- `functions.php`
- `page-home.php`
- `index.php`
- Optional `screenshot.png` as a 1200×900 PNG

Example:

```json
{
  "name": "Corporate Website",
  "starter": "corporate",
  "version": "1.0.0",
  "themeFolder": "theme",
  "pages": [
    {
      "title": "Contact",
      "slug": "contact",
      "template": "page-contact.php",
      "status": "publish"
    }
  ],
  "requires": {
    "wordpress": ">=6.0",
    "plugins": []
  }
}
```

## Synchronization flow

1. Download the configured GitHub branch through the GitHub REST API.
2. Inspect ZIP entries and reject unsafe paths and symbolic links.
3. Extract into a temporary directory.
4. Validate repository files, JSON, theme folder, and theme headers.
5. Back up an existing destination theme.
6. Copy the theme through a staging directory into `wp-content/themes/`.
7. Show the imported theme in the Themes tab and optionally activate it.
8. Create or update repository-declared pages without overwriting existing editor content.
9. Create or reuse the empty `WP Vibecoder Home` page and assign it as the static homepage.
10. Render the homepage layout entirely through `page-home.php`.

Backups are stored in `wp-content/uploads/wp-vibecoder-backups/`. The Backups
panel restores the latest available theme-file backup only; pages, posts,
settings, plugins, and database content are not included.

## Homepage convention

The homepage layout always lives in `theme/page-home.php`. WP Vibecoder creates
or reuses a WP Vibecoder-managed published page named `WP Vibecoder Home` with
the slug `wp-vibecoder-home`, keeps its content and excerpt empty, sets
`show_on_front` to `page`, and assigns its ID to `page_on_front`.
WP Vibecoder routes that managed front page to `theme/page-home.php`, so the
homepage template does not depend on the page slug.

If the site already has a static homepage, WP Vibecoder does not edit, empty,
delete, or reuse that page. It creates or reuses its own `wp-vibecoder-home`
page and changes only the Reading Settings front page assignment. The previous
page remains available in **Pages** and can be selected again under
**Settings > Reading**.

Codex should edit `page-home.php` whenever the landing page or corporate
homepage changes. The WP Vibecoder Home page exists only for SEO plugins,
metadata, OpenGraph, Gutenberg compatibility, previews, revisions, future CMS
features, and WordPress compatibility. Its content editor must not contain
homepage layout content.

When an administrator edits the assigned WP Vibecoder Home page, WP Vibecoder displays a
persistent notice explaining that the layout is managed in
`theme/page-home.php` and that the page editor should remain empty.

`page.php` remains the template for standard pages, `single.php` is available
only if posts are used, and `index.php` is a fallback. Blog functionality is
not included in V1 unless explicitly requested. WP Vibecoder does not create a
Blog page and does not modify `page_for_posts`.

V1 does not use `front-page.php` or `home.php`. Dedicated page layouts may use
`page-{slug}.php` only when a unique layout is required.

## Page creation convention

Landing-page sections such as Hero, About, Services, Testimonials, FAQ,
Contact, Pricing, and CTA belong in `page-home.php`. They do not become
separate WordPress pages unless the user explicitly requests a dedicated URL.

Standard pages such as `/about`, `/services`, `/contact`, `/portfolio`, or
`/gallery` use `page.php` by default. A project may add `page-about.php`,
`page-services.php`, or another `page-{slug}.php` template when that page
requires a unique layout.

Page declarations in `wp-vibecoder.json` are metadata only. They may include
`title`, `slug`, optional `status`, and optional `template`, but must not
include `content` or `excerpt`. WP Vibecoder creates declared pages with an
empty editor and preserves manually edited page content. Repository-managed
copy and layout should live in `page.php` or `page-{slug}.php`.

When `wp-vibecoder.json` declares a page template that matches the
`page-{slug}.php` hierarchy pattern, WP Vibecoder lets WordPress load it by
slug and does not assign `_wp_page_template`. Any other declared page template
must include a `Template Name` header so WordPress accepts it as a valid page
template.

## Managed forms

Repositories may declare managed forms in `wp-vibecoder.json`. V1 supports the
Fluent Forms provider for simple contact, newsletter, and custom forms.

When a repository declares forms, it must also declare the Fluent Forms plugin
dependency:

```json
{
  "requires": {
    "plugins": [
      {
        "slug": "fluentform",
        "required": true,
        "minVersion": "6.1",
        "maxTestedVersion": "6.x"
      }
    ]
  },
  "forms": [
    {
      "id": "contact",
      "provider": "fluent-forms",
      "title": "Contact",
      "type": "contact",
      "fields": [
        { "name": "name", "type": "text", "label": "Name", "required": true },
        { "name": "email", "type": "email", "label": "Email", "required": true },
        { "name": "message", "type": "textarea", "label": "Message", "required": true }
      ],
      "submitLabel": "Send"
    }
  ]
}
```

Before installing or syncing theme files, WP Vibecoder verifies that Fluent
Forms is active and checks the declared version constraints. If the dependency
is missing or below the required version, the install or sync stops before the
managed theme is changed. When the dependency check passes, WP Vibecoder creates
or updates the declared Fluent Forms forms and stores a stable mapping from
repository form ID to provider form ID.
Themes render managed forms with:

```php
<?php echo function_exists( 'wpv_render_form' ) ? wpv_render_form( 'contact' ) : ''; ?>
```

Supported V1 field types are `text`, `email`, `textarea`, and `tel`.
Submissions are stored by Fluent Forms entries. WP Vibecoder does not configure
external newsletter or CRM destinations unless a supported provider is declared
in a future version.

## Agent instruction compatibility

WP Vibecoder treats `agent.md` as a versioned contract between the installed
plugin and AI coding agents. The plugin validates the connected repository's
`agent.md` against the capabilities required by the installed plugin version.
When instructions are missing or outdated, the setup page shows an
`Update Agent.md` action.

The update action does not overwrite custom user instructions. It inserts or
replaces WP Vibecoder-managed blocks marked with comments such as:

```md
<!-- WPVIBECODER:MANAGED-FORMS START v1 -->
...
<!-- WPVIBECODER:MANAGED-FORMS END -->
```

When the repository is connected through the WP Vibecoder GitHub App, the
plugin sends the merged `agent.md` content to the WP Vibecoder API, which
creates a branch and opens a pull request for review.

The GitHub App installation must grant repository `Contents` read/write and
`Pull requests` read/write permissions. If GitHub returns
`Resource not accessible by integration`, update or reinstall the GitHub App
installation so those permissions are accepted for the repository.

WordPress reads `theme/screenshot.png` for the preview shown in
**Appearance > Themes**. When a repository does not provide one, WP Vibecoder
installs its branded generic 1200×900 screenshot automatically. A custom
screenshot may override it, but must be a valid 1200×900 PNG.

## Security

- Every action requires `manage_options` and a valid nonce.
- Input is sanitized and output is escaped.
- The GitHub token is encrypted at rest with AES-256-GCM using a key derived from WordPress salts. It is never rendered back into the admin form.
- Archives are inspected before extraction.
- Persistent theme writes are restricted to the WordPress theme root.
- Persistent backup writes are restricted to the WP Vibecoder uploads backup directory.
- Logs are stored in the WordPress options table and capped at 200 entries.

Temporary GitHub archives are extracted with local PHP ZIP APIs after their
contents have passed path and symlink validation. Theme installation still uses
the WordPress filesystem API. If installation cannot write to `wp-content/themes`,
correct the directory ownership/permissions or configure `FS_METHOD` as `direct`
when appropriate for the hosting environment.

## Uninstall behavior

Deleting WP Vibecoder from the WordPress Plugins screen runs `uninstall.php`.
It removes the repository connection, encrypted token, setup state, imported
theme registry, managed-theme registry, and logs.

Installed themes, the WP Vibecoder Home page, Reading settings, backup ZIP files,
and backup metadata are intentionally preserved to avoid deleting website or
recovery data.

## V1 exclusions

V1 intentionally excludes AI generation inside WordPress, page builders,
Elementor integration, Gutenberg block builders, GitHub OAuth, webhooks,
auto-deployment, and ACF integration. ACF support is reserved for a future Pro
workflow.
