maintain-docs.yml is the consumer-facing reusable workflow for scheduled upkeep. Consumer repositories pass product-level inputs such as audience, require_pr, base_ref, docs_branch, writable_paths, context_repositories, bootstrap_contract, source_delta, validation_dependencies, verification_commands, drift_checks, prompt, run_agent, and dry_run.
The consumer workflow supports separate lanes for technical docs, user docs, and live skills maintenance. Use audience: skills with skills/package writable paths instead of broad docs paths.
The canonical execution architecture consists of exactly five native Agents API packages: technical bootstrap, technical maintenance, user bootstrap, user maintenance, and skills maintenance. Each .agent.json package is the sole executable instruction authority for its lane; maintain-docs.yml selects one immutable package without a separate manifest, flow, pipeline, or memory envelope.
Schedule skills upkeep separately from docs upkeep. The skills lane should use a dedicated branch such as docs-agent/skills-upkeep, skill/package writable paths, verification commands, and drift checks through the portable recipe.
When validation setup, verification commands, or drift checks are needed, pass them through the reusable workflow inputs above. validation_dependencies is an optional caller-owned command that runs before verification during a live execution. The reusable workflow includes those executable inputs in the portable recipe and keeps the target repository as the writable Docs Agent workspace.
Maintenance permits a no-op only for a non-empty caller-bounded source_delta. The completion validator derives the report from those validated records, the host Git diff, writable paths, and filesystem bootstrap checks; model final prose is supplementary transcript evidence only. Bootstrap uses inventory mode with its positive contract. Set require_pr: true for changed maintenance that must produce a valid target-repository PR; bootstrap changes always require publication.
The reusable workflow declares the expected typed review artifacts for Docs Agent runs: transcript, change summary, verification report, drift report, completion report, and workspace publication links. maintain-docs.yml writes those declarations into the portable recipe and exposes the declaration objects through declared_artifacts_json. The completion runtime declaration remains optional for producer lifecycle compatibility, but the final completion drift command has a mandatory generic {name,type,path} artifact output. The Docs Agent-owned validator generates canonical host-observed bytes under .codebox/agent-task-artifacts, and WP Codebox stages only that declared artifact for review.
The target repository grants contents: write, pull-requests: write, and issues: write. Docs Agent forwards the caller-scoped ${{ github.token }} to WP Codebox for same-repository publication, so consumers do not configure ACCESS_TOKEN. OPENAI_API_KEY is an optional workflow secret and is required only for a live OpenAI run; skipped and dry-run calls do not require it. EXTERNAL_PACKAGE_SOURCE_POLICY remains a separate required v1 JSON secret. Migrate its value to the exact one-line JSON in the root README: it authorizes the selected Docs Agent package, the pinned Agents API component, the pinned PHP AI Client overlay, and the checksum-pinned OpenAI provider artifact. Both secrets are forwarded to WP Codebox without serialization into the task descriptor.
Docs Agent consumes the reusable WP Codebox workflow and helper implementation at accepted immutable revision a6fe2d208e990a8d04104aa74aacbb8d1539fbc1 and passes wp_codebox_release_ref: v0.12.29 only for released packaged runtime assets. The release tag resolves to immutable revision bc982947ec33c78160125026e16d357b7ece3ea1, distinct from both the workflow producer revision and the fixed Docs Agent package revision. WP Codebox materializes the declared native runtime closure, executes the selected package, applies bounded workspace changes, runs verification, and publishes approved host changes. The released assets are 01-wp-codebox.zip and 02-wp-codebox-workspace-0.12.29.tgz; the private package-recovery manifest is intentionally not a reviewer asset.
Provider artifacts retain only allowlisted review artifacts, controlled workflow envelopes, and canonical runtime-source and seed provenance. WP Codebox v0.12.24 uploads a reviewer-safe workflow-result projection: public control, verification, publication, output-projection, access, failure, artifact-declaration, and canonical transcript-provenance fields remain, while raw runtime_result, outputs.engine_data, model/provider/tool payloads, source content, private paths, and secrets are excluded. Before persistence or upload, it sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. WP Codebox captures one trusted canonical codebox-transcript through a pre-sanitization reviewer-evidence descriptor, validates its artifact-root containment, schema, digest, and size, then emits the compact reviewer transcript as a wp-codebox/reviewer-agent-transcript/v1 projection. Before apply-back, it compares the seed identity with the host workspace identity; rejected patches preserve the expected and actual identities plus patch and changed-file evidence for upload. Its pre-redaction trusted apply input preserves machine-applicable patch bytes in a private channel that is removed before durable artifact sanitization, as fixed in WP Codebox #1842. The canonical transcript remains the bounded tool-observability surface. Lifecycle and downstream failures retain runtime evidence in their internal normalized failed result even when artifact preparation cannot complete. Diagnostic messages that name runtime classes remain reviewable, while PHP-shaped runtime source remains blocked. See WP Codebox #1767, WP Codebox #1814, WP Codebox #1815, and WP Codebox #1823. Successful canonical reviewer-evidence reference: run 29350690551. The hosted failure 29468956857 executed WP Codebox v0.12.20, published Agents API #430, then failed during upload preparation; it motivated #1814/#1815 and is not a successful v0.12.24 reviewer-safe workflow-result run.
WP Codebox v0.12.25 excludes Git-ignored verification artifacts such as pnpm's symlinked node_modules tree from publication integrity snapshots while continuing to reject tracked or otherwise publishable symlinks. This allows dependency installation during verification without weakening the bounded workspace publication contract; see WP Codebox #1845.
WP Codebox v0.12.26 restores the unconditional exclusion for mutable .codebox runtime control files, preventing task request and result state from invalidating an approved workspace snapshot. Publishable workspace files remain governed by Git tracking and ignore semantics; see WP Codebox #1848.
WP Codebox v0.12.27 reports bounded added, modified, and deleted paths when post-verification integrity changes and preserves that evidence in normalized publication failures. It also restores bounded filesystem snapshots for non-Git workspaces; see WP Codebox #1852.
WP Codebox v0.12.28 validates canonical GitHub repository identity case-insensitively while preserving strict pull-request URL, pull number, target binding, and API resolution checks; see WP Codebox #1875.
WP Codebox v0.12.29 returns { valid: true } without a failure-only error when canonical pull-request verification succeeds, while repository mismatches retain their exact diagnostic; see WP Codebox #1885.
Docs Agent workflow call sites prepare a portable recipe instead of calling a concrete runner. Docs Agent owns the native package, lane, artifact, prompt, and workspace mapping. Consumers depend on Docs Agent inputs and review artifacts, not runner internals.
The recipe boundary covers standalone native package selection, complete native runtime closure selection, read-only context repositories, bootstrap criteria, bounded source deltas, workspace publication expectations, artifact declarations, verification, drift checks, and output mapping suggestions. Package provenance is the fixed DOCS_AGENT_PACKAGE_REVISION, independent of the reusable-workflow revision, and each descriptor includes a byte digest. Package changes advance that revision and every declared digest atomically. The post-command validator has its own immutable DOCS_AGENT_COMPLETION_CONTRACT_REVISION, so validator changes do not rewrite unchanged package provenance. Docs Agent declares the runtime sources and product completion check. WP Codebox materializes and lowers them under its generic runtime contract, including its generic command interface, without learning Docs Agent semantics.
The execution order is native package runtime, host patch apply, caller dependency command, caller verification commands, caller drift checks, Docs Agent completion validation and command-artifact capture, publication, then WP Codebox declared-artifact staging and upload. This makes the validated report reviewer-visible without moving Docs Agent semantics into the producer. Neither WP Codebox nor Agents API implements Docs Agent report fields or outcome rules, and Data Machine is not part of the path.
Native package selection is expressed through recipe docsAgent.externalPackageSource. Workspace boundaries are expressed through recipe runner fields so agents remain workspace editors while caller-owned execution handles sandboxing and publication handoff.
Direct consumers of the removed legacy manifests, flows, pipelines, or memory envelopes must migrate to the corresponding native .agent.json package. Existing maintain-docs.yml consumers retain native execution, but maintenance calls now require non-empty caller-bounded source deltas and bootstrap calls must provide positive bootstrap_contract criteria.
Run php tests/validate-docs-agent-packages.php after workflow changes so package structure, workflow routing, and runner config stay aligned.