AGENTS.md

Webentor Stack AI Guide

This file is for AI coding agents working in webentor-stack.

Purpose

webentor-stack is the source of truth for shared Webentor packages and docs. The monorepo exists to keep versioning and integration changes coordinated.

Repository Map

• packages/webentor-core: shared PHP + JS runtime package.
• packages/webentor-configs: shared ESLint/Stylelint/Prettier/static config package.
• packages/webentor-setup: shared setup runtime + setup CLI.
• packages/webentor-starter: pure project skeleton (WordPress/theme only; no setup scaffolding).
• docs: VitePress documentation project.

Non-Negotiable Boundaries

• webentor-demo is not part of this monorepo; it is a separate integration-gate repository.
• packages/webentor-setup and packages/webentor-starter are mirrored to standalone repositories.
• In consumer projects, scripts/setup-core/ is added via git subtree add from a tagged webentor-setup release.
• All other scaffolding under scripts/ and .webentor/ is generated by webentor-setup init.
• Project-specific setup customizations must live in:
  • scripts/.env.setup
  • scripts/hooks/
  • scripts/project-specific/

Dependency Direction

Allowed direction:

• webentor-starter -> webentor-core, webentor-configs, webentor-setup (as runtime copy/subtree output)
• webentor-demo (external) -> released outputs from monorepo packages

Avoid reverse dependencies from shared packages back into starter/demo.

Setup Runtime Contract

packages/webentor-setup defines setup contract. The init command generates all scaffolding (.env.setup, setup.sh, hooks, project-specific, optionally ts-up.sh, and .webentor/project.json). Without flags it prompts interactively; with flags the corresponding prompts are skipped (useful for CI/AI). The starter contains no setup files — it is a pure project skeleton.

If setup runtime behavior changes, update all of these together:

1. runtime scripts (common.sh, helpers, platform scripts)
2. CLI behavior (src/webentor-setup.php) — including init scaffolding generators
3. docs/README contract text
4. upgrade manifests in upgrades/<version>/manifest.json if migration behavior changes

Setup-Core Consumption Rule

In consumer projects:

• scripts/setup-core/ is not in the starter — it is added via git subtree add from a tagged webentor-setup release.
• scripts/setup.sh and all other scaffolding under scripts/ are generated by webentor-setup init.
• Do not place project business logic in setup-core.
• Do not put generated scaffolding files back into packages/webentor-starter.

When packages/webentor-setup changes, keep consumer runtime in sync intentionally.

Release and Rollout Order

Default order for coordinated releases:

1. webentor-core and/or webentor-configs
2. webentor-setup (including any upgrade recipe)
3. webentor-starter
4. webentor-demo bump/validation (external repo)

Shared release is not complete until demo CI is green.

Versioning Policy

• Use independent semver per package; do not force shared version numbers across the monorepo.
• On every release request, update docs/src/compatibility-matrix.md with the tested-together version set.

Release Workflow (Manual versioning)

For released packages in this monorepo, maintainers choose version bumps and write changelog entries manually. Do not rely on .changeset files or generated version PRs to decide release contents. The source of truth is the version and changelog files committed in the repository.

Release preparation

1. Decide the semver bump for each affected package.
2. Edit the authoritative version files listed in the "Version Source Map" below.
3. Update the package changelog manually with a curated release entry.
4. Keep every mirrored version field in sync for packages that have multiple version sources.
5. Update docs/src/compatibility-matrix.md with the tested-together version set.
6. Commit and push the release preparation through the normal review flow.

Existing release workflow

• Keep the current release workflow structure in place after release preparation is merged.
• release.yml remains the repository release automation entry point on push to main.
• Push a namespaced tag to trigger split-mirror workflows when needed:
• core-v* -> split-webentor-core.yml (also pings Packagist)
• setup-v* -> split-webentor-setup.yml
• starter-v* -> split-webentor-starter.yml
• Example: git tag core-v0.9.14 && git push origin core-v0.9.14

AI agent release instructions

When asked to release a package:

1. Identify the affected package(s) and choose the correct bump level.
2. Edit the version files directly in the repository.
3. Update the relevant changelog file(s) manually.
4. Keep all related version sources synchronized for that package.
5. Update docs/src/compatibility-matrix.md.
6. Commit and push through the normal release flow, then push the namespaced tag when needed.

Manual version and changelog edits are expected for release work in this repository.

Version Source Map

Reference map for locating version sources per package.

• webentor-core (beta, 0.9.x):
• packages/webentor-core/package.json -> "version" (manual)
• packages/webentor-core/composer.json -> "version" (manual; keep in sync with package.json)
• packages/webentor-core/CHANGELOG.md -> add new entry at top (manual)
• npm publish via the existing release workflow; Composer/Packagist via split-mirror + Packagist API ping
• webentor-configs (stable, 1.x):
• packages/webentor-configs/package.json -> "version" (manual)
• packages/webentor-configs/CHANGELOG.md -> add new entry at top (manual)
• npm publish via the existing release workflow
• webentor-setup (stable, 1.x):
  • packages/webentor-setup/CHANGELOG.md -> add new entry at top (manual)
  • Runtime is mirrored via split workflow (no npm publish)
  • packages/webentor-setup/composer.json -> "version" (manual)
• webentor-starter (stable, 2.x):
  • packages/webentor-starter/composer.json -> "version" (manual)
  • packages/webentor-starter/changelog.md -> add new entry at top (manual)
  • Runtime is mirrored via split workflow (no npm publish)
• webentor-theme-v2 (stable, 2.x, inside starter):
  • packages/webentor-starter/web/app/themes/webentor-theme-v2/package.json -> "version" (manual)
  • packages/webentor-starter/web/app/themes/webentor-theme-v2/composer.json -> "version" (manual)
  • packages/webentor-starter/web/app/themes/webentor-theme-v2/style.css -> Version: header (manual)
  • packages/webentor-starter/web/app/themes/webentor-theme-v2/changelog.md -> add new entry at top (manual)
  • Keep all theme version sources synchronized in the same bump

Mirror Policy

Mirror targets and workflows:

• packages/webentor-core -> .github/workflows/split-webentor-core.yml / scripts/split-webentor-core.sh (tag: core-v*)
• packages/webentor-setup -> .github/workflows/split-webentor-setup.yml / scripts/split-webentor-setup.sh (tag: setup-v*)
• packages/webentor-starter -> .github/workflows/split-webentor-starter.yml / scripts/split-webentor-starter.sh (tag: starter-v*)

The split-webentor-core.yml workflow also pings Packagist after mirroring to update the Composer package. Secrets required: PACKAGIST_USERNAME, PACKAGIST_API_TOKEN.

Do not introduce additional split mirrors unless explicitly requested.

AI Editing Rules

• Prefer minimal, contract-preserving edits.
• Preserve comments that explain operational intent, especially in setup scripts.
• Do not silently remove troubleshooting paths (1Password, env fallback, platform-specific behavior).
• Keep file paths and command examples consistent with scripts/setup-core naming.
• Avoid editing unrelated files in large migrations.
• Always check and update documentation

Validation Checklist for AI Changes

Before handoff, run relevant checks:

• Shell syntax for setup scripts:
  • find packages/webentor-setup -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n
• Shell syntax for split mirror scripts:
  • bash -n scripts/split-webentor-setup.sh
  • bash -n scripts/split-webentor-starter.sh
• Setup CLI syntax:
  • php -l packages/webentor-setup/src/webentor-setup.php
• JSON validity for changed package.json or manifest files.
• If starter touched, verify it contains no setup scaffolding (no scripts/, no .webentor/).

Common Mistakes to Avoid

• Breaking 1Password .env fetch flow (OP_VAULT_ID + OP_ITEM_ID + env-valet).
• Mixing project-specific hooks into setup-core.
• Releasing package changes without considering demo compatibility.
• Putting generated scaffolding files (.env.setup, setup.sh, hooks, etc.) back into packages/webentor-starter — the starter is a pure project skeleton.

Decision Rule

If uncertain whether a change belongs in shared runtime or project customization:

• Put reusable behavior in packages/webentor-setup.
• Put project-specific behavior in hooks/env files outside setup-core.