Set up a source checkout
Use a non-root account with Git, Bash, Make, Docker and Compose. The workflows select a local Linux Docker engine; do not substitute a remote context for a server login.
Install the locked dependencies
git clone https://github.com/numpde/dapp32.git
cd dapp32
docker context ls
make dapps/deps/install DOCKER_CONTEXT=your-local-context
make js/deps/install DOCKER_CONTEXT=your-local-context
make ci DOCKER_CONTEXT=your-local-contextReplace your-local-context with the engine you intend to use. Omit the argument only when you want the interactive chooser. Noninteractive commands need the context on the Make command line. Each operation resolves that engine once and uses the same endpoint for child operations and cleanup.
Dependency installation is explicitly networked. The offline checks do not install missing dependencies for you. For the standalone viewer, only JavaScript dependencies are needed; its build guide also acquires its pinned base images explicitly.
With dependencies installed, follow Change a screen locally to edit a form label and inspect the result in the viewer.
Choose the relevant validation
| Change | Validation |
|---|---|
| Authored CAM files | make cam/conformance/check; refresh resource pins after edits. |
| Repository/tooling | make tests/checks; relevant integration tests for changed behavior. |
| JavaScript/runtime | make js/tests and the affected app scenario. |
| Complete fixture qualification | make tests, which also runs networked checks and disposable local scenarios. |
| Documentation changes | Follow Documentation authoring to build the site, inspect its generated output and check generated links and navigation. |
Add your context to source Make commands. Run make help for prerequisites and current target options. README-only CI uses its lightweight length check, not application integration.
Host prerequisites and private files
Isolated Compose services disable Multipath TCP, so the kernel must expose the per-network-namespace net.mptcp.enabled setting. Host-network browser tools instead share the host's settings.
Release tools also need host Python 3.11+ and the maintained identity probe. Follow private-file qualification before using an operator instance on a different engine. Do not repair access failures by loosening the instance's permissions or changing its owner.
Documentation navigation ownership
docs/.vitepress/architecture.json declares the site homepage as the root and assigns every authored guide exactly one canonical route. The sections are its children, not competing top-level tabs. The homepage cards and its left sidebar are both rendered from those sections' labels and landing routes, so neither can drift from the top navigation. Every canonical documentation page, including the site root, must render a sidebar; CI checks the generated HTML against its declared owner. Every section declares a landing page separately from its sidebar groups: pages groups link only to guides owned by that section; the Gallery's catalog group reads app names and anchors from docs/public/gallery/deployments.json. The same inventory generates top navigation, sidebars, breadcrumbs and legacy redirects. Do not add sidebar links directly to the VitePress config or duplicate deployment names in navigation. Put links to another section in the page's Related tasks content, as on the Gallery page.
Docs CI checks unique route ownership, in-section sidebar destinations, valid catalog anchors and the rendered sidebar of every generated guide. Add or move pages by editing the inventory and the source page; broken navigation fails publication.
Source and documentation ownership
main owns implementation, fixtures, Markdown documentation and protocol-reference sources. gh-pages holds generated published documentation and the independently built Pages viewer. Both publishers build and qualify on main, reuse their exact qualified artifact, and publish automatically; neither needs a manual publishing PR. Documentation owns the site outside the viewer application files; the viewer owns viewer/index.html, viewer/assets/ and its publication manifest. Both use the same CI publication lock on gh-pages, preserve the other's files and refuse non-fast-forward updates. The independently hosted viewer is deployed separately. Keep versioned CAM protocol copies byte-identical to their source; current readers use CAM 1.4.0 / UI 1.1.0. Historical specifications are not compatibility promises.
Published-site integrity and drift
gh-pages is a deployment snapshot, not a Git-history mirror of main. For each component, the publication manifest identifies the exact source_sha, qualified_run_id, and SHA-256 digest of every generated file it owns. Documentation records these in docs-publication.json at the site root; the viewer records its HTML and hashed assets in viewer/viewer-publication.json. The viewer's hosting guide is documentation-owned and is not included in the viewer manifest. Neither publisher maintains a second file inventory by hand.
Published Pages integrity is the independent, read-only audit. It runs when either publisher finishes (checking that component), daily at 07:17 UTC (checking both), and on manual dispatch. Pull requests run its unit tests without publishing. The auditor checks that the recorded CI run actually qualified its recorded source, compares that source with the newest completed successful qualification for that component, checks the complete local file inventory against its recorded hashes, and fetches every owned generated file and both publication manifests over public HTTPS to compare exact bytes. A newer unrelated main commit does not constitute drift; a newer qualification whose publication failed does. A currently running qualification is not considered final until its workflow completes.
A failing audit names the affected component and the source revisions or files that disagree. Check the documentation publisher or viewer publisher for its qualifying and publishing jobs. Inspect the manifest, gh-pages checkout and served response separately: an accurate manifest does not prove publication reached the CDN, and a successful Git push does not prove the intended bytes were deployed. Resolve the underlying failed qualification, publishing or CDN boundary, then manually dispatch the appropriate publisher workflow on main; both workflows requalify and republish on a successful main-branch dispatch. The audit never repairs drift or changes either branch. Do not merge or rebase main into gh-pages to force synchronization.
For a release or published example, record the reviewed source commit. Do not mix an older deployment's ABI and signing rules with today's guide. The archived proof of concept is historical, not the starting point for current work.