DZINEDesign contracts
Install CLI

Navigate DZINE

Start hereInstall the public core, generate a pack, then hand it to your AI builder.Read install guide →
TroubleshootingMIT · agent-agnostic

Support

Troubleshooting

Verify the product works, diagnose common CLI and deploy issues, and mirror CI locally before you open a GitHub issue.

Verify the product works

Run these from a clone of the DZINE repository before reporting issues:

Full local CI mirror
./scripts/ci-local.sh
Corpus validation only
python3 skills/dzine/scripts/validate_dzine.py --root .
CLI health check
npx dzine-skill doctor

Quick smoke test (your project)

  1. cd into your app directory (not necessarily the DZINE repo).
  2. Run npx dzine-skill run "<brief>" --write-build-pack
  3. Confirm ./build-pack/contract/design-contract.json exists in that directory
  4. Run npx dzine-skill lint build-pack/contract/design-contract.json

Common issues

SymptomLikely causeFix
doctor shows old PythonSystem Python below 3.10Install Python 3.10+ and ensure python3 points to it
No build-pack in cwdRan from wrong directorycd to your project root; pack writes to cwd/build-pack/
lint fails on weak contractBrief too vagueAdd audience, proof, primary action, and product type
score cannot reach URLDev server not runningStart your app (site uses port 3003 by default)
validate_dzine.py fails on siteDocs copy drifted from markersRestore required strings listed in validate_dzine.py
MCP tools return hints onlyBy design for file workflowUse CLI for render/score; MCP returns command hints
npx dzine-skill not foundPackage not on npm yetUse npx dzine-skill from a repo clone — see /docs/install

Default ports

ServicePortCommand
DZINE marketing site3003cd site && npm run dev
Preview gallery3002python3 -m http.server 3002 --directory preview-gallery

CI failures

GitHub Actions runs the same checks as ci-local.sh:

  • 20 golden brief compile regressions
  • 2 intentional weak-contract lint failures
  • DesignContract E2E smoke (CLI paths + API)
  • Site lint, typecheck, and static build

See Deploy for shipping the docs site. For agent-specific issues, see Agent handoff.