Development

This page is for people working on plywood itself. The rest of the site describes the published package.

Repository docs

Path	Covers
CONTRIBUTING.md	where a feature belongs: chant CI core, a chant lexicon, or plywood
AGENTS.md	the repository rules, the checks to run before a change, and the release steps
justfile	every recipe, each with a comment
e2e/	the bench on chant’s e2e harness that runs the scenarios; the header of e2e/main.ts lists the just e2e commands
EVIDENCE.md	the e2e scenarios and the plunge features, with their status
stack/	the tutorial bench behind just tutorial-up: a local Forgejo, a runner and the floci emulator

Issues for plywood are on its tracker. chant and plunge keep their own.

The chant pin

@intentius/chant and every chant lexicon are pinned to one exact version in package.json and packages/plywood/package.json, and just bundle-check holds the two together. Versions and pins names the pinned release. A chant feature newer than the pin goes behind a feature-detect with a fallback; packages/plywood/src/chant-next.ts lists those from chant#4624 to chant#4636.

To build plywood against chant from source:

just chant-local              # packs chant's origin/main from a worktree next to the chant checkout
just chant-local ../chant     # packs that chant directory
just chant-local --reset      # back to the pin

Run --reset before committing a lock file.

Draft pages

A guide whose feature needs a newer chant or plunge than plywood pins carries draft: true and the issues under needs: in its front matter. just site-serve shows drafts, and a production build leaves them out. In site/, node scripts/check-needs.mjs --list prints each need with its pages. With --closed it names the needs whose issues have closed. A page with no needs left drops draft: true and publishes.

Draft page	Source	Needs
Evaluate plywood	for/evaluate	plywood#22
Have an agent request an app	guides/agent-request-from-a-template	plywood#40
Keep the stack export current	guides/keep-the-export-current	chant#4519
Change a stack's backend	guides/move-a-stack-backend	plunge#7
Re-preview from a comment	guides/re-preview-from-a-comment	plywood#28
See your stacks in behold	guides/see-your-estate-in-behold	chant#4519, plunge#40
Preview a few resources	guides/target-resources	plywood#28
Watch an update on plunge	guides/watch-a-plunge-update	plunge#55
The same repo on plunge	tutorial/plunge	plunge#7

approvals.preview is off by default since 0.3.1 and preview: true in plywood.yml turns it on, because of two bugs in the plan digest: plywood#55 (the second of two merges that change different resources of one stack is refused) and plywood#56 (a pull request that creates an autonamed resource is refused at merge). The default goes back to on in previewOf (src/config/approval.ts) once both are fixed.

Day-2 actions (plywood#39) ship the actions key with its check. The plywood action verb refuses on a lexicon without gatedStackAction. The pw-action scenario (plywood#44) runs on a local command resource rotate that the bench’s seed adds to prod-us, with the command provider plywood’s images carry. Its run is not recorded yet.

Agent requests (plywood#41) ship plywood mcp --propose on chant#4655’s propose tier, detected by PRODUCT_MCP_PROPOSE_FLOOR. Its plywood:request_from_template tool is declared forgeWrite and refuses every call. Pulumi templates arrive with plywood#40 after the registry in plywood#32. The pw-agent-request scenario comes with them.