feat: scaffold editable schema and flow config

[fforootd]

Summary

• Add @zitadel/config as the versioned single source for the editable default schema/flow documents and their authoring Zod schemas (@zitadel/config/schemas), shared by the CLI, the api-mock, and the Go server fallback (via go:embed).
• Change zitadel setup to be local-first: scaffold .zitadel/schemas/default-human-user.json (with objectType: "human-user", no $id) and .zitadel/flows/default-login.json, create the project with seedDefaults: false, upload the schema, pin the flow to the server-assigned opaque schema id (feat: implemented correlation between schemas #456/fix: user_schema is an opaque server-assigned id, not a URI #460 model), and seed .zitadel/state.json so plan is immediately empty. READMEs are scaffolded into .zitadel/{schemas,flows}/.
• Revisioned user-schemas in the sync engine (feat: revisioned user-schemas + schemas list + repin warning  #458): editing a schema file and running apply publishes a new immutable revision and warns about flow files still pinned to the previous id; flows are never auto-repinned. New zitadel schemas list --object-type=<value> inspects revision history (interactive picker fetches and pretty-prints a revision).
• Keep server fallback defaults for non-CLI project creation (seedDefaults defaults to true), rendered from the same shared documents.
• Robustness: setup rolls back its markers (zitadel.json, .zitadel/secret) when resource seeding fails so a rerun completes instead of stranding the project; doctor warns (instead of unfixably failing) on projects that predate editable config; doctor and validateFlows use the same canonical Zod as the sync engine.
• Packaging: zod is a runtime dependency of @zitadel/api (its published …zod export imports it); msw/@faker-js/faker are optional peers for the .msw export; @zitadel/config is wired into the release manifest, tarball verification, journey registry, and the changesets fixed group.
• CI: eliminate the shared-dist race class — the release chain (release:*, all *:build-release) is excluded from moon ci (runInCI: false; the release:snapshot step builds it afterwards, serially), the release pre-clean is ordered after every dev build it races, and contended dists keep mutexes for parallel local runs.

Validation

• moon ci :lint :typecheck :build :test (full graph green in CI)
• moon run cli:test (675 tests, incl. setup rollback/rerun, doctor warn, schemas-list URL-encoding, revision sync)
• moon run config:test api-mock:test api:test
• go build ./..., go test ./internal/api ./internal/service ./api/..., go vet -tags postgres_integration ./internal/api/integration_test (postgres run in CI)
• corepack pnpm --dir packages/api pack → published manifest carries zod in dependencies (catalog resolved)
• Fresh-app journeys (all 8 frameworks) green against the real binary server
• corepack pnpm exec changeset status --since origin/main, git diff --check

Release notes / changeset

• Changeset: .changeset/scaffold-editable-schema-flow-config.md — minor product bump covering @zitadel/config (new), @zitadel/cli, @zitadel/api, @zitadel/server and the fixed alpha group.

Notes

• The user_schema ↔ schema-revision model follows feat: implemented correlation between schemas #456 (objectType correlation) and fix: user_schema is an opaque server-assigned id, not a URI #460 (opaque server-assigned ids); re-pinning a flow after a schema edit is an explicit second step by design.
• Deferred follow-ups (tracked in PR comments): scaffolded metaSchema is pinned to the default builtin_public_base (needs a server-side decision); api-mock fidelity gaps (409 on duplicate flow names, idempotent deletes, schema project-scoping on get/delete); bundle/atomic-apply design filed on ADR: define architecture for environments and releases #449.
• Templates remain out of scope until template storage/API exists ( feature: app-type selection on zitadel setup #448 follows).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview, Comment	Jul 7, 2026 9:26am
nextgen-mock-zitadel	Ready	Preview, Comment	Jul 7, 2026 9:26am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nextgen-docs	Skipped		Jul 7, 2026 9:26am

[github-actions]

🦋 Changeset detected

Latest commit: fd4c8aa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@zitadel/cli	Minor
@zitadel/api	Minor
@zitadel/config	Minor
@zitadel/server	Minor
@zitadel/components	Minor
@zitadel/sdk-angular	Minor
@zitadel/sdk-core	Minor
@zitadel/sdk-next	Minor
@zitadel/sdk-nuxt	Minor
@zitadel/sdk-qwik	Minor
@zitadel/sdk-react	Minor
@zitadel/sdk-solid	Minor
@zitadel/sdk-svelte	Minor
@zitadel/sdk-vue	Minor
@zitadel/server-linux-x64	Minor
@zitadel/server-linux-arm64	Minor
@zitadel/server-darwin-x64	Minor
@zitadel/server-darwin-arm64	Minor
@zitadel/server-win32-x64	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

This PR introduces a new versioned @zitadel/config package to centralize editable local config defaults and schemas, then updates the CLI + server/API to support a “local-first” setup flow where schema/flow files are scaffolded locally, uploaded via APIs, and recorded into sync state while keeping server fallback defaults available for non-CLI project creation.

Changes:

• Add new public package @zitadel/config with shared default schema/flow documents and Zod schemas.
• Add seedDefaults to project creation to allow CLI-created projects to opt out of server fallback defaults.
• Update CLI setup + sync + api-mock to scaffold/upload defaults, fix project_id usage for flows, and seed .zitadel/state.json so plan is immediately idempotent.

Reviewed changes

Copilot reviewed 54 out of 58 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/release-artifacts.mjs	Include packages/config in public release artifacts.
scripts/check-changesets-status.mjs	Treat @zitadel/config as a public package for changeset enforcement.
pnpm-lock.yaml	Wire workspace dependency graph for new packages/config.
packages/config/tsdown.config.ts	Add tsdown build config for @zitadel/config.
packages/config/tsconfig.spec.json	Add config package test TS config.
packages/config/tsconfig.lib.json	Add config package library TS config (incl. JSON).
packages/config/tsconfig.json	Add project references for config package.
packages/config/src/schemas.ts	Export Zod schemas derived from @zitadel/api Zod types.
packages/config/src/index.ts	Barrel exports for defaults + schemas.
packages/config/src/defaults.ts	Provide default schema/flow templates and rendering helpers.
packages/config/package.json	Define new public package metadata/exports.
packages/config/moon.yml	Add Moon tasks for config package build/typecheck/test.
packages/config/LICENSE	Add MIT license file for the new public package.
packages/config/defaults/defaults.go	Embed default JSON documents for Go server fallback usage.
packages/config/defaults/default-login.json	Add versioned default login flow JSON template.
packages/config/defaults/default-human-user.json	Add versioned default user schema JSON template.
packages/api-mock/src/spec-conformance.spec.ts	Update conformance tests for seedDefaults + project_id flow queries.
packages/api-mock/src/platform-handlers.ts	Seed/serve default resources, enforce project_id on flow operations, and use config defaults.
packages/api-mock/package.json	Add dependency on @zitadel/config.
packages/api-mock/moon.yml	Add Moon dependency/build ordering on config.
internal/service/project.go	Add optional seeding control for fallback defaults on project creation.
internal/service/project_test.go	Add test coverage for skipping fallback defaults.
internal/api/project.go	Thread seedDefaults from API request to service.
internal/api/integration_test/project_test.go	Add integration coverage for skipping default provisioning via API.
apps/cli/tests/unit/scripts/verify-tarballs.test.ts	Expect config tarball in release verification.
apps/cli/tests/unit/scripts/local-registry.test.ts	Ensure local registry build list includes @zitadel/config.
apps/cli/tests/unit/scripts/check-changesets-status.test.ts	Ensure changesets fixed-group includes @zitadel/config.
apps/cli/tests/unit/lib/sync/syncers.test.ts	Update syncer tests for flow schema_uri + project_id + update-not-implemented.
apps/cli/tests/unit/lib/orca/patchers/rule/next/index.test.ts	Align expectations: patchers don’t write schema/flow; setup materializer does.
apps/cli/tests/integration/setup-next.test.ts	Validate setup scaffolds/uploads schema+flow and seeds .zitadel/state.json.
apps/cli/tests/integration/flow-schema.test.ts	Update comment/context to match new default scaffolding behavior.
apps/cli/src/lib/sync/types.ts	Extend sync state entries with flow metadata (name, status).
apps/cli/src/lib/sync/syncers.ts	Validate via config Zod schemas; enforce flow project_id; block flow updates locally.
apps/cli/src/lib/sync/loop.ts	Export hashing helper for consistent state seeding.
apps/cli/src/lib/sync/index.ts	Re-export hashResourceContent.
apps/cli/src/lib/setup-resources.ts	New helper to scaffold/upload defaults and seed sync state during setup.
apps/cli/src/lib/orca/patchers/types.ts	Update patcher context docs for new resource materialization step.
apps/cli/src/lib/orca/patchers/rule/base.ts	Clarify .zitadel/{schemas,flows} are created empty then filled later.
apps/cli/src/commands/setup/index.ts	Create project with seedDefaults:false, materialize/upload defaults, and report written files.
apps/cli/src/commands/doctor/patch-context.ts	Update docstrings for local editable sync resources.
apps/cli/src/commands/doctor/checks/schema.ts	Re-enable schema check to validate local .zitadel/schemas/*.json.
apps/cli/src/commands/doctor/checks/index.ts	Re-enable SchemaCheck in doctor.
apps/cli/SKILLS.md	Update agent-facing CLI contract docs for editable schema/flow scaffolding.
apps/cli/README.md	Update CLI README for local-first schema/flow scaffolding and sync behavior.
apps/cli/package.json	Add dependency on @zitadel/config.
apps/cli/moon.yml	Add Moon dependency/build ordering on config.
apps/cli-journey-e2e/scripts/verify-tarballs.mjs	Require config tarball for journey verification.
apps/cli-journey-e2e/scripts/local-registry.mjs	Publish config tarball to Verdaccio for journeys.
api/openapi/endpoints/schemas/embed.go	Switch server builtin schema template source to packages/config/defaults.
api/openapi/endpoints/projects/create-project-request.yaml	Add seedDefaults request field with default true.
api/openapi/endpoints/flow_definitions/embed.go	Switch builtin flow template source + wrap create envelope including schema_uri/project_id.
api/generated/oas_schemas_gen.go	Regenerated schema: add SeedDefaults to CreateProjectRequest.
api/generated/oas_json_gen.go	Regenerated JSON codec: encode/decode seedDefaults + default handling hook.
api/generated/oas_defaults_gen.go	Regenerated defaults: set SeedDefaults default to true.
.moon/workspace.yml	Register packages/config as a Moon project.
.changeset/scaffold-editable-schema-flow-config.md	Add changeset covering CLI/API/server + new config package.
.changeset/README.md	Document packages/config as publishable path.
.changeset/config.json	Add @zitadel/config into the fixed version group.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[fforootd]

Post-merge review sweep (after #458 and #464 landed on this branch) — pushed 5bb8d866 fixing the highest-severity findings:

• setup no longer strands projects: if the default schema/flow upload fails after zitadel.json was written, setup now removes the marker (and .zitadel/secret) and surfaces an actionable error instead of every rerun silently reporting skipped for a project that has no login flow anywhere. Covered by a new integration test that injects a POST /schemas failure and verifies the rerun completes.
• doctor works on pre-existing projects: an empty .zitadel/schemas/ (every project created before this PR) is now a warn, not a permanent unfixable fail.
• one canonical validation path: doctor and validateFlows now use @zitadel/config/schemas — the same Zod the sync engine uses — and the flow syncer no longer Zod-parses every file twice per plan/apply.
• dist race closed for real: build: serialize cli release build after tests #464's dep chain (build < test < build-release) makes the cli-dist mutexes redundant, but the built oclif commands also import @zitadel/{api,config,sdk-next} from those packages' dists at runtime, and their build-release tasks can't take a task dep on cli:test (reverse edge cycles the project graph). Replaced the per-dist mutexes with one shared public-dist mutex on cli:test + those three release builds.

Known follow-ups deliberately left out of this PR: the same dist-contention pattern exists for the remaining sdk packages' release builds vs their consumers (a systemic fix — e.g. a separate release out-dir — deserves its own PR), and the scaffolded schema's metaSchema is pinned to the default builtin_public_base, which needs a server-side decision before the CLI can do better.

[fforootd]

07b2add9 replaces the per-leg race patches with the systemic fix: the entire release chain (release:*, all 14 *:build-release, clean-public-package-dist) is now runInCI: false, so moon ci never schedules a release build alongside the build/test graph. The release:snapshot step in ci.yml already rebuilds them explicitly (env -u CI moon run …) right after, so PR coverage is unchanged — release-build breakage still fails the same job, just in its own serialized step.

Context: the previous run failed with demo-next:typecheck reading sdk-next/dist mid-rewrite (TS7016, missing declarations) — the third consumer leg hit by the same shared-dist race after cli:test (exit 127) and demo-nuxt:build. Per-leg fixes can't scale here: a task can hold only one mutex, and writer→reader task deps invert dependsOn edges into project-graph cycles (moon rejects them). Removing the contention at the scheduling level is the only shape that covers all readers. The mutexes stay as insurance for explicit parallel local runs.

[Copilot]

Pull request overview

Copilot reviewed 95 out of 99 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Comments suppressed due to low confidence (1)

packages/api-mock/src/platform-handlers.ts:438

• DELETE /schemas/:id validates the project_id query param but does not enforce it when deleting. This allows deleting a schema by id while supplying a different project_id, which breaks project scoping and is inconsistent with the flow-definition delete handler.