WP HOLODEV
==========

Version:      1.1.77
Edition:      Windows ZIP
Author:       Alan Lloyd
Website:      https://wpholodev.com
Docs:         https://wpholodev.com/docs
Issues:       https://wpholodev.com/issues
Platform:     Windows 10/11 64-bit
Licence:      GNU General Public License version 3 or later
SPDX:         GPL-3.0-or-later
Copyright:    Copyright (c) 2026 Alan Lloyd
Source:       The corresponding 1.1.77 source tree used to build this release

WP HoloDev is a local AI development harness for WordPress plugins, themes and
websites. It gives coding agents controlled project inspection, editing, review,
testing, WordPress runtime validation, browser validation, specialist skills,
MCP integrations, release preparation, deployment and rollback where supported.

WP HoloDev and project state run locally. Cloud model requests go to the provider
you configure. A supported local provider, such as LM Studio, can keep inference
local according to its own configuration.

RUNTIME AND PROJECT TOOLING
===========================

The Windows ZIP bundles Node.js v26.7.0, so a separate Node.js installation is
not required for WP HoloDev itself. npm is not bundled. When npm is installed on
the Windows host, WP HoloDev detects it and makes it available to project
commands.

CHOOSING AN EDITION
===================

WINDOWS ZIP
  Choose this edition for the simplest extract-and-run setup, normal Windows
  operation, Docker-independent everyday development, and optional Docker-backed
  WordPress testing when Docker Desktop is available.

DOCKER
  Choose the Docker edition when you need stronger isolation for model-controlled
  execution, current-project execution containers, isolated STDIO MCP, disposable
  WordPress/database environments and dedicated browser validation. This is a
  trade-off: Docker requires Docker Desktop and uses more setup and disk space.

SYSTEM REQUIREMENTS
===================

  - Windows 10 or Windows 11, 64-bit. Windows Server 2019+ is also supported.
  - A normal web browser.
  - The ZIP includes Node.js v26.7.0; no separate Node installation is required.
  - Internet access for cloud providers and authorised external integrations.
  - Docker Desktop is optional and is only needed for isolated WordPress testing.
  - Git, PHP, Composer and project tooling are used when installed; unavailable
    tools are reported rather than silently assumed.

RECOMMENDED DIRECTORY LAYOUT
============================

  O:\dev\
      WPHoloDev\       application files
      Project1\         project source
      Project2\         another project
      .wpholodev\       WP HoloDev application data

The application folder may have another name and may be on any suitable drive.
The parent folder is the workspace root. Paths containing spaces are supported.
Projects normally live beside, not inside, the application folder.

INSTALLATION
============

  1. Create a development root, for example O:\dev\.
  2. Extract WPHoloDev-1.1.77-win-x64.zip into that root.
  3. Rename the extracted folder to WPHoloDev if desired.
  4. Place existing projects beside it, or create one in the application.
  5. Run WPHoloDev-silent.vbs for normal use, or WPHoloDev.cmd to see startup
     output in a console.
  6. The local workspace opens in your browser at http://127.0.0.1:<port>.
  7. On first run, open Settings, connect a provider and choose model routing.

STARTING AND STOPPING
=====================

WPHoloDev-silent.vbs starts the server without a console window.
WPHoloDev.cmd starts the same application with visible output.
The launcher opens the browser once. Launching again reopens the existing
workspace instead of starting a second server.

Run WPHoloDev-Stop.cmd, or use the in-app Shut down action, to stop the server.
Closing a browser tab does not stop it. The stop helper verifies process ownership
before terminating a process.

DOCKER SUPPORT (OPTIONAL)
=========================

The Windows edition works without Docker. It detects Docker automatically and
reports NOT_INSTALLED, INSTALLED_NOT_RUNNING, AVAILABLE or a degraded/unavailable
state in Settings and /status. Recheck can refresh the capability state, and
starting Docker after WP HoloDev does not require restarting the application.

When available, Docker enables disposable databases and WordPress installations,
plugin/theme installation and activation, WP-CLI, runtime checks, clean-site
checks, browser validation, screenshots and compatibility/integration evidence.
When unavailable, ordinary project management, file inspection/editing, search,
providers, models, memory, skills, specialist agents, native tools, static checks,
commands, MCP, packaging and supported deployment remain available.

DATA STORAGE
============

For O:\dev\WPHoloDev\, application data is O:\dev\.wpholodev\.
It contains the local SQLite database, settings, jobs, memory, encrypted
credentials, logs, browser evidence, artifacts, uploads and temporary data.
It is separate from projects and survives replacement of the application folder.

Older data under %LOCALAPPDATA%\WPHoloDev is copied once into the workspace data
directory when needed. The old directory is retained as a backup; migration is
idempotent and does not delete it automatically.

PROJECT SECURITY
================

Native project tools enforce the workspace boundary using canonical path checks,
traversal protection and symlink/junction handling. Archive extraction is also
confined to the workspace. Normal Windows child processes, including external
STDIO MCP servers, still run as the Windows user with normal OS permissions unless
an isolated Docker execution path is selected.

AI PROVIDERS AND MODEL ROUTING
=============================

Supported provider types are OpenAI, Anthropic, OpenRouter, OpenCode, OpenCode Go,
LM Studio, WP HoloDev LUNA and compatible custom endpoints. Configure credentials
in Settings. Provider charges belong to the provider. Routing choices are Auto,
Efficient, Balanced and Expert; provider identity and model identity are separate.
Credentials are protected application secrets, not project files or prompt text.

MCP
===

MCP adds approved external tools, resources and prompts alongside native tools.
WP HoloDev supports STDIO and HTTP/streamable HTTP transports, discovery and
invocation. Windows STDIO servers run locally under normal Windows permissions;
they remain subject to permissions, approvals and audit logging.

SPECIALIST AGENTS AND SKILLS
============================

WP HoloDev includes 24 bundled skills covering implementation, debugging, code
review, architecture, WordPress development, REST, PHPStan, performance,
WP-CLI, testing, release checks and security. Specialist reviewers can provide
focused code, security, testing, WordPress, frontend, accessibility,
architecture and browser-validation review when a task benefits from it.

SLASH COMMANDS
==============

Common commands are /help, /models, /model, /connect, /project, /projects, /new,
/chats, /rename, /clear, /agents, /skills, /status, /test, /review, /build,
/deploy, /rollback, /cancel, /compact, /memory, /settings and /check. /holo and
/audit are available aliases where the current context supports them.

THINKING AND TECHNICAL TRACE
============================

Thinking shows readable task phases, findings, decisions, next actions,
validation, specialist activity, model changes and translated provider errors.
Private model chain-of-thought and raw reasoning streams are not shown. Explicitly
public provider summaries may be cleaned and displayed; models without reasoning
output still produce factual progress summaries from harness activity.

Use Show technical details or the job trace for raw tool calls, command output,
validator evidence, timings, Docker/MCP protocol data, provider metadata and
technical errors. Secrets remain redacted in both views.

TESTING AND VALIDATION
======================

Validation adapts to the project, installed tooling, task and Docker availability.
Results distinguish PASSED, FAILED, SKIPPED, UNAVAILABLE and WARNING. Release
checks may include source checks, WordPress runtime, installation/activation,
WP-CLI, browser validation, error inspection, evidence collection and cleanup.
Runtime evidence is stronger than static inspection alone.

UPDATING
========

Stop WP HoloDev. Extract the new ZIP to a temporary folder and replace only the
WPHoloDev application folder. Preserve the sibling .wpholodev directory and all
project folders. Start the new launcher. Never delete the workspace root or its
.wpholodev directory during an update.

UNINSTALLING
============

Delete the WPHoloDev application folder to remove the program. Delete the sibling
.wpholodev folder only if you also want to remove application state and encrypted
credentials. Projects are separate user-owned source folders and are not deleted
automatically. WP HoloDev-owned empty project folders may be removed only after
explicit confirmation. External and unknown directories are never removed by
ordinary project deletion. If an attached directory becomes unavailable, the
project must be reconnected to its original absolute path; it is never silently
redirected to another folder.

LICENSING AND SOURCE
====================

The WP HoloDev desktop harness is GPL-3.0-or-later. The generated WordPress
Bridge is GPL-2.0-or-later. Third-party components retain their own licences;
see THIRD-PARTY-NOTICES.txt and the component licence files. The corresponding
 source is the exact 1.1.77 source tree, including application, frontend, runner,
proxy, MCP, Docker, Compose and build/packaging sources.

SUPPORT
=======

Website:             https://wpholodev.com
Documentation:       https://wpholodev.com/docs
Issues / bug reports: https://wpholodev.com/issues

Include the WP HoloDev version, Windows or Docker edition, reproduction steps,
error text and relevant logs. Remove API keys, cookies, tokens and other private
credentials before sharing logs.
