Add developer experience principles

[elinashoko]

What changed

• Added docs/design/developer-experience-principles.md as a shared product and engineering decision framework.
• Linked the principles from the Operate — one contract, every surface section of VISION.md.
• Excluded the earlier open-questions section.
• Aligned configuration lifecycle terminology with ADR 035: revisions, immutable releases, deployment and promotion.

Why

The repository already documents the product vision and concrete architectural decisions, but it did not have a concise set of principles explaining how configuration, runtime state and operational actions should shape developer workflows across the repository, CLI, API, Console and MCP.

Impact

This gives product, design and engineering contributors a common framework for future decisions without changing runtime behaviour.

Validation

• Confirmed the new document exists on the branch.
• Confirmed the VISION.md link resolves to the intended repository path.
• Confirmed the referenced ADR 007 and ADR 035 files exist.
• Confirmed the document contains no open-questions section.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview, Comment	Jul 29, 2026 2:17pm
nextgen-docs	Ready	Preview, Comment	Jul 29, 2026 2:17pm
nextgen-mock-zitadel	Ready	Preview, Comment	Jul 29, 2026 2:17pm

[github-actions]

⚠️ No Changeset found

Latest commit: df55aac

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[Copilot]

Pull request overview

Adds a shared “developer experience principles” document to the design docs and links it from the repository vision so future product/engineering decisions across CLI/API/Console/MCP align on configuration vs runtime state vs operational actions.

Changes:

• Introduces docs/design/developer-experience-principles.md as a cross-surface decision framework.
• Links the new principles doc from the “Operate — one contract, every surface” section in VISION.md.

Reviewed changes

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

File	Description
VISION.md	Adds a pointer to the new developer experience principles doc from the vision narrative.
docs/design/developer-experience-principles.md	New principles document describing sources of truth, workflows-first design, and interface roles.

Comments suppressed due to low confidence (1)

docs/design/developer-experience-principles.md:212

• For consistency with the rest of the design docs, consider using the same “next-generation” terminology here instead of “Zitadel Next”.

When designing a new capability in Zitadel Next: