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, PhpcValidateManifestTest

Field reference (from shipped examples)

Field	Required	Example	Purpose
entry	yes	"example.php" or "public/index.php"	Script compiled by phpc build / --project
binary	no	".phpc/bin/app"	Default AOT output; phpc serve --aot reads this
public	no	"public"	Docroot for phpc serve / deploy (#609)
assets	no	"assets"	Static files copied on phpc deploy
includes	no	["src/Router.php", "config.php"]	Extra TUs for --project link (#452, #752)

Minimal flat example (examples/001-SimpleWeb/phpc.json)

{
    "entry": "example.php",
    "binary": ".phpc/bin/app"
}

Project example (examples/003-MiniWebApp/phpc.json)

{
    "entry": "public/index.php",
    "binary": ".phpc/bin/app",
    "public": "public",
    "assets": "assets",
    "includes": ["src/Router.php", "config.php"]
}

Document that includes[] order matters for link-time symbol resolution and that runtime template include paths are separate (#623, #783, #784).

Implementation hints

Piece	File	Notes
Doc	docs/phpc-json.md	new file
Source of truth	lib/Web/ProjectManifest.php	cross-check field names
Links	README.md, examples/README.md	one-line pointer each
CI	optional	script/check-docs-phpc-json.sh greps broken links

Acceptance criteria

• docs/phpc-json.md exists and matches ProjectManifest for keys above
• README + examples README link to the doc
• ./script/ci-fast.sh still green (doc-only PR)

Dependencies

• Testing: ci-fast gate phpc validate-manifest for all examples phpc.json #654 ✅ validation
• DevEx: PSR-4 autoload paths in phpc.json project manifest #155 — future autoload section (stub “planned”)
• Docs: Sync examples/README + 003 README with live MiniWebApp AOT status #753 — sync examples README AOT status in same PR or follow-up

Verification

Local/Docker only — doc change; no GitHub Actions required.

Links

• DevEx: PSR-4 autoload paths in phpc.json project manifest #155, AOT: phpc deploy bundles binary, public/, assets/, and phpc.json into dist/ #609, AOT: Honor phpc.json includes array in phpc build --project #452, Docs: Sync examples/README + 003 README with live MiniWebApp AOT status #753
• ROADMAP 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 Phase 0 Foundation