Repository navigation
docs: modernize README and move reference material into docs - #2571
Merged
Merged
Conversation
The README was 1,519 lines of reference material. It now leads with what WP Codebox is, two verified quick starts, and the self-describing CLI commands, and links to docs for depth. Reference sections move into docs/ (cli-reference, artifact-bundles, runtime-episodes, wordpress-plugin, host-tool-registry, sandbox-workspace-contract, distribution) and are indexed in docs/README.md. Removed stale content: the agent-sandbox-run, agent-sandbox-batch and agent-runtime-probe CLI sections (these are recipe steps, not CLI commands), the npm install instructions (the packages are not published), and hardcoded command and ability lists that had drifted from commands --json and the registered abilities.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The README had grown to 1,519 lines of reference material. It now runs 173 lines: what WP Codebox is, two quick starts verified against the current build, the CLI commands that describe the live contract (
--help,commands --json,schema recipe --json,runtime descriptor,doctor), a map of entry points, artifact bundles, runtime policy, the repo layout and development commands.Its reference sections are now in
docs/and listed indocs/README.md:docs/cli-reference.md: CLI commands, run lifecycle, previewsdocs/artifact-bundles.md: bundle layout and runtime evidence attestationdocs/runtime-episodes.mddocs/wordpress-plugin.md: why a plugin, browser site operations, browser runnerdocs/host-tool-registry.md,docs/sandbox-workspace-contract.mddocs/distribution.md: rewritten againstscripts/package-release-artifact.tsand.github/workflows/release.ymlRemoved stale content
agent-sandbox-run,agent-sandbox-batchandagent-runtime-probeCLI sections. These are recipe steps, not CLI commands (wp-codebox agent-sandbox-runreturnsUnknown command).docs/agent-runtime-contract.mdis corrected to match.npm install -g @automattic/wp-codebox-cliandnpm publishinstructions. The scoped packages aren't published, so installation goes through release assets.commands --jsonand the registered abilities. The docs now point to those live sources.v0.4.0examples and the lead paragraph pointing to the adversarial runtime.Testing
wordpress.run-phpsucceeded.wordpress.browser-probewithprofile=low-end-mobile-slow-4gandassert=fcp_ms<=1800passed (FCP 820 ms).npm run checkpasses (325/325 smoke).tests/production-boundary-enforcement.test.tsstays green: the public docs keep consumer-neutral vocabulary.README.mdanddocs/*.mdresolves.docs/and the package and example READMEs. The only terms now missing belong to the removed sections listed above.AI disclosure
Written by Claude (via the Pi coding agent in a Roadie session). It read the CLI router, command registry, runtime policy, release scripts and workflows, ran the quick starts and
npm run check, and rewrote the README and docs. Chris Huber reviewed and directed the work.