Docs: docs/phpc-json.md — project manifest reference (autoload, deploy, gates)

[PurHur]

Problem

Contributors rely on scattered comments in #106 (closed), #155, #609 (closed), and lib/Web/ProjectManifest.php for phpc.json fields. There is no single checked-in reference at docs/phpc-json.md (called out in #155 tasks).

phpc validate-manifest (#654 ✅) enforces shape in CI, but operators still grep PHP for semantics of includes, assets, public, and future autoload.

Goal

A short, accurate manifest reference linked from README, examples/README.md, and #78 ROADMAP.

Scope

• Create docs/phpc-json.md with field table + examples
• Document current keys: entry, binary, public, assets, includes
• Document planned keys: autoload.psr-4 (DevEx: PSR-4 autoload paths in phpc.json project manifest #155), deploy notes (AOT: phpc deploy bundles binary, public/, assets/, and phpc.json into dist/ #609 ✅, Docs: deploy-web-aot.md quickstart (phpc deploy + PHPC_DEPLOY_ROOT + nginx CGI) #635)
• Link validation: phpc validate-manifest, test/unit/ValidateManifestTest.php
• Cross-link examples/003-MiniWebApp/phpc.json and templates/init-miniwebapp/phpc.json (DevEx: Keep phpc init --profile miniwebapp template in sync with examples/003-MiniWebApp #695)

Acceptance criteria

• README “Web workflow” links to docs/phpc-json.md
• Manifest doc matches ProjectManifest.php parser (no contradictions)
• phpc validate-manifest examples/*/phpc.json passes on master

Verification (local / Docker only)

phpc validate-manifest examples/003-MiniWebApp/phpc.json
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev phpc validate-manifest examples/003-MiniWebApp/phpc.json

No GitHub Actions required.

Dependencies

• DevEx: PSR-4 autoload paths in phpc.json project manifest #155 — autoload section (document as “planned” until implemented)
• DevEx: phpc.json JSON Schema and phpc validate-manifest #263 / Testing: ci-fast gate phpc validate-manifest for all examples phpc.json #654 ✅ — schema validation in CI

Links

• lib/Web/ProjectManifest.php, docs/deploy-web-aot.md
• ROADMAP 🗺️ ROADMAP: Compile a small PHP web application (living document) #78, DevEx: PSR-4 autoload paths in phpc.json project manifest #155, Docs: Rewrite README feature list to match current compiler (2026) #48