# AGENTS.md

## Purpose

This repository contains the `vibepress` workspace: a WordPress-to-React pipeline plus supporting apps.

Use this file as the first-stop orientation guide before changing code. It is written for human contributors and coding agents.

## Workspace Map

- `ai-pipeline/`
  NestJS backend and the core orchestration pipeline.
  This is the main source of truth for WordPress parsing, planning, generation, validation, preview building, and edit-request flows.

- `xpress-react-spa/`
  React + Vite frontend used for the editor / SPA side of the system.

- `automation/`
  Supporting automation service used alongside the pipeline.

- `db/`
  Database-related assets and local environment support.

- `ai-pipeline/temp/`
  Runtime artifacts only.
  Includes cloned repos, generated previews, logs, and job outputs.
  Do not treat this directory as authoritative source code.

- `ai-pipeline/dist/`
  Compiled Nest output.
  Never edit by hand unless you are debugging a running local job and explicitly accept that it is temporary.

## Source of Truth

Prefer editing these locations:

- Pipeline logic: `ai-pipeline/src/**`
- Express preview template: `ai-pipeline/templates/express-server/**`
- React SPA source: `xpress-react-spa/src/**`

Avoid committing manual edits to:

- `ai-pipeline/temp/**`
- `ai-pipeline/dist/**`
- generated preview apps under `ai-pipeline/temp/generated/**`

Temporary edits in generated preview folders are acceptable only for local debugging, and should usually be mirrored back into real source files afterward.

## Core Pipeline Architecture

For `ai-pipeline`, the high-level flow is:

1. Parse and normalize WordPress source
   Files: `src/modules/agents/php-parser`, `block-parser`, `normalizer`, `source-resolver`

2. Extract DB-backed content and runtime theme data
   Files: `src/modules/sql`, `src/modules/agents/db-content`

3. Build architecture plan
   Files: `src/modules/agents/planner`, `plan-reviewer`

4. Generate React code
   Files: `src/modules/agents/react-generator`

5. Validate and repair code
   Files: `src/modules/agents/validator`, plus validator-related flows inside `orchestrator.service.ts`

6. Build preview app
   Files: `src/modules/agents/preview-builder`, template sources in `templates/express-server`

7. Orchestrate the end-to-end job lifecycle
   Files: `src/modules/orchestrator`

If you are unsure where a behavior belongs, start at:

- `ai-pipeline/src/modules/orchestrator/orchestrator.service.ts`

That file is the best entry point for understanding stage order, retries, artifact writing, validation gates, and preview generation.

## Important Modules

- Planner
  `ai-pipeline/src/modules/agents/planner/`
  Responsible for route contracts, concrete page expansion, visual planning, and section planning.

- React Generator
  `ai-pipeline/src/modules/agents/react-generator/`
  Responsible for codegen, code review, fix-agent behavior, prompts, and visual-plan schema.

- Validator
  `ai-pipeline/src/modules/agents/validator/`
  Enforces route/data contracts, structural constraints, and preview/runtime checks.

- Preview Builder
  `ai-pipeline/src/modules/agents/preview-builder/`
  Assembles generated code into runnable preview apps and wires routes/build/run checks.

- WordPress section heuristics
  `ai-pipeline/src/common/utils/wp-node-to-sections-mapper.ts`
  Central heuristic mapper from parsed WP nodes into draft visual sections.

## Commands

Root workspace:

- Start pipeline prod build:
  `npm run start:ai-pipeline`

- Start SPA:
  `npm run start:xpress-app`

- Start all services:
  `npm run start:all`

Pipeline:

- Build:
  `cd ai-pipeline && npm run build`

- Dev watch:
  `cd ai-pipeline && npm run start:dev`

- Test:
  `cd ai-pipeline && npm run test`

SPA:

- Dev:
  `cd xpress-react-spa && npm run dev`

- Build:
  `cd xpress-react-spa && npm run build`

## Working Rules

- Make changes in source, not in `temp/` or `dist/`, unless you are doing short-lived local debugging.

- If you patch a generated preview app to verify a fix, also patch the real source file that produces it.

- If you change anything under:
  - `ai-pipeline/src/**`
  - `ai-pipeline/templates/**`
  then rebuild `ai-pipeline` before concluding the change is done.

- If the bug reproduces only in a specific job, inspect:
  - `ai-pipeline/temp/logs/<job-id>/plan.final.json`
  - `ai-pipeline/temp/logs/<job-id>/plan.visual-attempt-1.json`
  - `ai-pipeline/temp/generated/<job-id>/`

- Treat `plan.final.json` as an artifact of a run, not as editable source-of-truth.

## Route and Contract Expectations

- The planner owns the route map.
- The generator and preview builder must follow the approved plan contract.
- The validator is the final authority on whether generated code still matches that contract.

When debugging route issues, check these three layers in order:

1. Planner output
   `plan.final.json`

2. Generated React routes
   preview `frontend/src/App.tsx`

3. API/menu URL normalization
   `ai-pipeline/src/modules/sql/wp-query.service.ts`
   and `ai-pipeline/templates/express-server/index.ts`

## Logging and Artifacts

- Planner logs and plan artifacts live under:
  `ai-pipeline/temp/logs/<job-id>/`

- Generated preview apps live under:
  `ai-pipeline/temp/generated/<job-id>/`

- Repo snapshots for a job live under:
  `ai-pipeline/temp/repos/<job-id>/`

When investigating a generation issue, correlate:

- selected planning source
- draft sections
- reviewed visual plan
- generated TSX
- validator output

Do not assume a single log line explains the whole failure.

## Common Pitfalls

- Editing `dist/` without mirroring source changes
  This only fixes the current local process and will be lost on rebuild.

- Editing `temp/generated/...`
  This helps debug a job but does not fix future jobs unless the source/template is also updated.

- Assuming theme template files contain all actual content
  In many jobs, the real structure comes from DB-backed `wp_template`, `wp_template_part`, `wp_navigation`, posts, or pages.

- Blaming React first for navigation issues
  Many menu and route bugs originate in planner contracts or API URL normalization.

## Preferred Debugging Order

When behavior is wrong in preview:

1. Confirm the plan contract
2. Confirm the generated app follows the plan
3. Confirm API payload shape and canonical URLs
4. Confirm validator expectations
5. Only then change prompts or heuristics

## If You Add New Behavior

Document it close to the real source:

- route policy changes near planner or plan-reviewer
- section heuristics near `wp-node-to-sections-mapper.ts`
- codegen contracts near validator or generator prompts
- preview/runtime wiring near preview-builder or express template

Keep policy logic centralized. Do not duplicate the same routing or content-contract rule in multiple places unless a downstream layer is explicitly enforcing it.