diff --git a/VISION.md b/VISION.md
new file mode 100644
index 00000000000..c9bd8fe6d07
--- /dev/null
+++ b/VISION.md
@@ -0,0 +1,46 @@
+# Vision
+
+Layer5 Docs exists to give users and contributors a trustworthy path through Layer5 products and their public developer resources.
+It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk.
+It owns the public documentation contract for the content maintained here. For Layer5 Cloud content, the implementation remains the authority for what the software actually does.
+
+## Shipped behavior is the source of truth
+
+Layer5 Docs documents behavior that can be verified in the relevant implementation or released product.
+When repository reference material disagrees with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it.
+For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions.
+Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead.
+Release-note automation tracks released Cloud and Kanvas versions so version history remains tied to published artifacts.
+
+## Public links are compatibility contracts
+
+Published URLs and heading anchors are treated as interfaces because product UIs, external sites, bookmarks, and existing documentation can link to them.
+When a page moves, its previous path is preserved with Hugo aliases rather than being allowed to become a 404.
+When an externally referenced heading is renamed, its established anchor is retained explicitly.
+Redirects and anchors are verified from built output so source changes are not considered safe merely because the Markdown looks correct.
+Documentation restructuring should improve navigation without silently invalidating known entry points.
+
+## Information architecture serves distinct user journeys
+
+Layer5 Docs organizes content for readers with different goals and experience levels, including beginners, developers, administrators, operators, security specialists, and contributors.
+The documentation separates task guidance, concepts, tutorials, and reference material so readers can move from learning a product to operating and extending it.
+The site acts as a Layer5 documentation entry point while directing readers to canonical project documentation when that material is maintained elsewhere.
+Content should favor clear task outcomes and product-specific terminology over generic prose that could belong to any documentation site.
+
+## Documentation changes are reproducible and reviewable
+
+Layer5 Docs is built with Hugo and Docsy, with the published content rooted in `content/en` and repository configuration defining the site.
+Contributors can build and preview changes locally before review, and pull requests that affect documentation are built by the docs-preview workflow.
+Documentation work follows the repository's issue-first contribution flow so planned changes remain visible and can be continued by other contributors.
+Changes should preserve the repository's DCO, review, build, and contribution requirements rather than bypassing them for documentation-only work.
+
+## Scope
+
+Layer5 Docs is not the authority for product behavior when the relevant implementation says otherwise.
+Layer5 Docs does not publish links to private implementation artifacts as reader-facing evidence.
+Layer5 Docs does not knowingly break established public URLs or heading anchors when compatible redirects or explicit anchors can preserve them.
+Layer5 Docs does not present planned or inferred behavior as shipped behavior without clearly identifying its status.
+Layer5 Docs does not duplicate another project's canonical documentation merely to make this repository appear self-contained when a maintained canonical destination already exists.
+
+A change aligns when it makes product behavior more accurate, preserves public link compatibility, improves a real reader journey, or strengthens reproducible review and validation.
+A change should be resisted when it relies on stale secondary descriptions over implementation evidence, exposes inaccessible references, breaks known URLs or anchors without compatibility handling, or adds generic documentation without a clear Layer5-specific purpose.
diff --git a/docs/vision/vision-evidence.md b/docs/vision/vision-evidence.md
new file mode 100644
index 00000000000..a3e361406c9
--- /dev/null
+++ b/docs/vision/vision-evidence.md
@@ -0,0 +1,94 @@
+# Layer5 Docs Vision Evidence Sheet
+
+This document provides claim-by-claim traceability for `VISION.md` to concrete evidence in `layer5io/docs` and, where product behavior is concerned, to the repository guidance that defines which downstream implementation is authoritative.
+
+---
+
+## Identity and purpose
+
+* **Claim**: "Layer5 Docs exists to give users and contributors a trustworthy path through Layer5 products and their public developer resources."
+  * **Evidence**: `README.md` describes `docs.layer5.io` as documentation and developer resources for Layer5 products and explicitly welcomes contributions.
+* **Claim**: "It publishes the documentation at `docs.layer5.io`, with first-party Cloud and Kanvas content in this repository and clear routes to canonical documentation for projects such as Meshery and Nighthawk."
+  * **Evidence**: `package.json` identifies the project as "Layer5 Product Documentation" with homepage `https://docs.layer5.io`; `content/en/_index.md` links to Cloud Docs and Kanvas Docs in this site, and links readers to `docs.meshery.io` and `getnighthawk.dev`.
+* **Claim**: "It owns the public documentation contract for the content maintained here. For Layer5 Cloud content, the implementation remains the authority for what the software actually does."
+  * **Evidence**: `AGENTS.md` states that Layer5 Cloud behavior must be verified against `meshery-cloud` implementation and that server behavior is the arbiter when documentation or API descriptions disagree.
+
+---
+
+## Principle 1: Shipped behavior is the source of truth
+
+* **Claim**: "Layer5 Docs documents behavior that can be verified in the relevant implementation or released product."
+  * **Evidence**: `AGENTS.md`, "Documenting Layer5 Cloud behavior", requires product claims to be verified against `origin/master` in `meshery-cloud`.
+* **Claim**: "When repository reference material disagrees with shipped behavior, documentation follows the implementation and flags the mismatch instead of repeating it."
+  * **Evidence**: `AGENTS.md` says repository reference material is a starting point rather than the arbiter and requires contributors to document handler responses and flag the `data/openapi.yml` mismatch.
+* **Claim**: "For Layer5 Cloud, behavior claims are checked against the handlers and UI that produce the behavior, not only against secondary descriptions."
+  * **Evidence**: `AGENTS.md` points contributors to `ui/components/identity/org-management/` for screen strings and `server/handlers/` for behavior.
+* **Claim**: "Private implementation repositories are evidence for maintainers, not public destinations for readers; public pages cite released versions or other reader-accessible references instead."
+  * **Evidence**: `AGENTS.md` explicitly prohibits linking private `meshery-cloud` pull requests, issues, or files from public content and directs contributors to cite released versions instead.
+* **Claim**: "Release-note automation tracks released Cloud and Kanvas versions so version history remains tied to published artifacts."
+  * **Evidence**: `.github/workflows/cloud-release-docs.yml` retrieves the latest `meshery-cloud` release and writes Cloud release notes. `.github/workflows/meshery-extension-release-docs.yml` does the same for Kanvas releases from `meshery-extensions-packages`.
+
+---
+
+## Principle 2: Public links are compatibility contracts
+
+* **Claim**: "Published URLs and heading anchors are treated as interfaces because product UIs, external sites, bookmarks, and existing documentation can link to them."
+  * **Evidence**: `AGENTS.md`, "Keeping old URLs alive", records both external URL dependencies and a concrete Layer5 Cloud UI dependency on a heading anchor at `docs.layer5.io`.
+* **Claim**: "When a page moves, its previous path is preserved with Hugo aliases rather than being allowed to become a 404."
+  * **Evidence**: `AGENTS.md` requires dead paths to be added to `aliases:`; working examples include `content/en/kanvas/operator/_index.md` and `content/en/kanvas/operator/views/index.md`. Alias usage is also present throughout the Kanvas and Cloud sections.
+* **Claim**: "When an externally referenced heading is renamed, its established anchor is retained explicitly."
+  * **Evidence**: `AGENTS.md` directs contributors to preserve old anchors with Goldmark heading attributes. `hugo.toml` enables Goldmark parser attributes.
+* **Claim**: "Redirects and anchors are verified from built output so source changes are not considered safe merely because the Markdown looks correct."
+  * **Evidence**: `AGENTS.md` instructs contributors to verify generated redirect stubs and compare built heading IDs between master and a change branch.
+* **Claim**: "Documentation restructuring should improve navigation without silently invalidating known entry points."
+  * **Evidence**: The alias and preserved-anchor requirements in `AGENTS.md` establish backward-compatible navigation as a repository maintenance rule.
+
+---
+
+## Principle 3: Information architecture serves distinct user journeys
+
+* **Claim**: "Layer5 Docs organizes content for readers with different goals and experience levels, including beginners, developers, administrators, operators, security specialists, and contributors."
+  * **Evidence**: `README.md`, "Documentation Structure", explicitly lists these personas and states a goal of comprehensive, organized, and accessible documentation for audiences from new users to expert contributors.
+* **Claim**: "The documentation separates task guidance, concepts, tutorials, and reference material so readers can move from learning a product to operating and extending it."
+  * **Evidence**: `README.md` documents the Cloud and Kanvas information architecture with Getting Started, Concepts, Tutorials or Core Tasks, and Reference sections.
+* **Claim**: "The site acts as a Layer5 documentation entry point while directing readers to canonical project documentation when that material is maintained elsewhere."
+  * **Evidence**: `content/en/_index.md` presents Cloud Docs and Kanvas Docs locally while linking Meshery Docs to `docs.meshery.io` and Nighthawk Docs to `getnighthawk.dev`.
+* **Claim**: "Content should favor clear task outcomes and product-specific terminology over generic prose that could belong to any documentation site."
+  * **Evidence**: `README.md` defines product-specific information architectures and task categories for Layer5 Cloud and Kanvas; issue #1272 also sets the quality bar that repository vision content must not be generic.
+
+---
+
+## Principle 4: Documentation changes are reproducible and reviewable
+
+* **Claim**: "Layer5 Docs is built with Hugo and Docsy, with the published content rooted in `content/en` and repository configuration defining the site."
+  * **Evidence**: `CONTRIBUTING.md` states that Layer5 documentation is built with Hugo and the Docsy theme. `hugo.toml` sets `contentDir = "content/en"` and imports Docsy.
+* **Claim**: "Contributors can build and preview changes locally before review, and pull requests that affect documentation are built by the docs-preview workflow."
+  * **Evidence**: `README.md` and `CONTRIBUTING.md` document local setup and site commands. `package.json` defines build and preview scripts. `.github/workflows/build-docs-preview.yml` builds PR previews for documentation-related changes.
+* **Claim**: "Documentation work follows the repository's issue-first contribution flow so planned changes remain visible and can be continued by other contributors."
+  * **Evidence**: `CONTRIBUTING.md` says all pull requests should reference an open issue and tells contributors to create a new issue when needed.
+* **Claim**: "Changes should preserve the repository's DCO, review, build, and contribution requirements rather than bypassing them for documentation-only work."
+  * **Evidence**: `CONTRIBUTING.md` requires DCO sign-off for each commit, documents local tests and preview steps, and describes the fork-and-pull-request review flow.
+
+---
+
+## Scope and non-goals
+
+* **Claim**: "Layer5 Docs is not the authority for product behavior when the relevant implementation says otherwise."
+  * **Evidence**: `AGENTS.md` identifies implementation handlers as the arbiter for behavior.
+* **Claim**: "Layer5 Docs does not publish links to private implementation artifacts as reader-facing evidence."
+  * **Evidence**: `AGENTS.md` explicitly prohibits public content from linking private `meshery-cloud` pull requests, issues, or files.
+* **Claim**: "Layer5 Docs does not knowingly break established public URLs or heading anchors when compatible redirects or explicit anchors can preserve them."
+  * **Evidence**: `AGENTS.md` requires aliases for moved pages and preserved IDs for externally referenced headings.
+* **Claim**: "Layer5 Docs does not present planned or inferred behavior as shipped behavior without clearly identifying its status."
+  * **Evidence**: `AGENTS.md` requires a concrete producer in Go or TSX before documenting a capability as shipped and warns that a contract enum or runbook sentence alone is not proof.
+* **Claim**: "Layer5 Docs does not duplicate another project's canonical documentation merely to make this repository appear self-contained when a maintained canonical destination already exists."
+  * **Evidence**: `content/en/_index.md` deliberately routes Meshery and Nighthawk readers to their separate canonical documentation sites rather than mirroring those docs here.
+
+---
+
+## Alignment and resistance criteria
+
+* **Claim**: "A change aligns when it makes product behavior more accurate, preserves public link compatibility, improves a real reader journey, or strengthens reproducible review and validation."
+  * **Evidence**: This summarizes the documented maintenance rules in `AGENTS.md`, information architecture goals in `README.md`, and contribution and validation flow in `CONTRIBUTING.md` and `.github/workflows/build-docs-preview.yml`.
+* **Claim**: "A change should be resisted when it relies on stale secondary descriptions over implementation evidence, exposes inaccessible references, breaks known URLs or anchors without compatibility handling, or adds generic documentation without a clear Layer5-specific purpose."
+  * **Evidence**: `AGENTS.md` covers source authority, private links, URL and anchor preservation; issue #1272 establishes the repository-specific quality bar.
diff --git a/docs/vision/vision-hypotheticals.md b/docs/vision/vision-hypotheticals.md
new file mode 100644
index 00000000000..81b9d03dd75
--- /dev/null
+++ b/docs/vision/vision-hypotheticals.md
@@ -0,0 +1,133 @@
+# Layer5 Docs Vision Hypotheticals and Calibration Record
+
+This document records ten stress-test scenarios used to calibrate `VISION.md`. Each scenario tests whether the vision gives a clear answer when accuracy, compatibility, information architecture, or contribution process is under pressure.
+
+---
+
+## Hypothetical 1: Document a behavior from a stale runbook
+
+* **Proposal**: Add a Cloud guide based on an internal runbook even though the current server handler behaves differently.
+* **Tested Principle**: Shipped behavior is the source of truth.
+* **For**: The runbook is easier to read and already describes the intended workflow.
+* **Against**: Readers would receive instructions that do not match the product they are using.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "If the handler and the runbook disagree, the guide must follow the shipped handler behavior and record the mismatch rather than publish the easier secondary description."
+* **Changelog Impact**: The vision explicitly makes implementation behavior authoritative over summaries, runbooks, and stale reference material.
+
+---
+
+## Hypothetical 2: Link a private implementation pull request from a public guide
+
+* **Proposal**: Cite a private `meshery-cloud` pull request as proof of a Cloud capability because it contains the clearest implementation discussion.
+* **Tested Principle**: Shipped behavior is the source of truth and Scope.
+* **For**: Maintainers can verify the implementation quickly from the pull request.
+* **Against**: Most readers cannot open the private link, so the public documentation would contain unusable evidence.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "Private implementation evidence can inform the maintainer, but the published page must point readers to evidence they can access, such as a released version or public documentation."
+* **Changelog Impact**: The vision separates maintainer evidence from reader-facing references.
+
+---
+
+## Hypothetical 3: Rename a heading that a product UI links to
+
+* **Proposal**: Improve a heading title and allow Hugo to generate a new anchor, even though Layer5 Cloud currently links directly to the old anchor.
+* **Tested Principle**: Public links are compatibility contracts.
+* **For**: The new generated anchor is cleaner and matches the revised wording.
+* **Against**: Existing product links would land on the page without reaching the intended section.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "The wording may change, but a known external anchor is part of the public documentation interface. Preserve the old ID explicitly."
+* **Changelog Impact**: The vision names heading anchors alongside page URLs as compatibility surfaces.
+
+---
+
+## Hypothetical 4: Move a page and preserve its old URL
+
+* **Proposal**: Reorganize a Kanvas page into a clearer section and keep the previous path in Hugo `aliases:`.
+* **Tested Principle**: Public links are compatibility contracts.
+* **For**: Readers get a better information architecture without losing bookmarks or inbound links.
+* **Against**: The repository carries an additional redirect entry.
+* **Verdict**: **ACCEPT**
+* **Reasoning**:
+  > "A better location is worthwhile when the old route continues to resolve. The alias is the compatibility cost of improving the structure safely."
+* **Changelog Impact**: The vision requires compatible redirects when pages move.
+
+---
+
+## Hypothetical 5: Publish documentation for an inferred future capability
+
+* **Proposal**: Document a feature as available because an enum, schema field, or planning document suggests that support is coming soon.
+* **Tested Principle**: Shipped behavior is the source of truth and Scope.
+* **For**: The documentation could be ready before launch and reduce release-day work.
+* **Against**: A declaration or schema entry does not prove the user-facing behavior ships.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "A future or inferred capability must not be written as current product behavior. Verify a producer in the implementation or clearly label the material as non-shipped direction."
+* **Changelog Impact**: The scope now rejects presenting planned or inferred behavior as shipped.
+
+---
+
+## Hypothetical 6: Use released versions to support public behavior claims
+
+* **Proposal**: Verify a Cloud behavior against implementation, then cite the released version that contains it rather than a private source link.
+* **Tested Principle**: Shipped behavior is the source of truth.
+* **For**: Maintainers retain implementation confidence while readers get a reference they can actually use.
+* **Against**: Release references can be less granular than a pull request.
+* **Verdict**: **ACCEPT**
+* **Reasoning**:
+  > "Verification and citation serve different audiences. Use implementation to establish truth, then use an accessible released artifact for the public reference."
+* **Changelog Impact**: The vision explicitly distinguishes private maintainer evidence from public destinations.
+
+---
+
+## Hypothetical 7: Copy another project's canonical docs into this repository
+
+* **Proposal**: Copy a substantial Meshery guide into `layer5io/docs` so every Layer5 product appears to have complete documentation in one repository.
+* **Tested Principle**: Information architecture serves distinct user journeys and Scope.
+* **For**: Readers could remain on one domain and search one repository.
+* **Against**: Duplicate documentation can drift while Meshery already maintains its own canonical documentation destination.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "The Layer5 docs site should be a reliable entry point, not a reason to fork canonical documentation. Route readers to the maintained project source when ownership lives elsewhere."
+* **Changelog Impact**: The vision defines the site as an entry point that can direct readers to canonical external project docs.
+
+---
+
+## Hypothetical 8: Reorganize content around a real reader journey
+
+* **Proposal**: Split a long page into concept, task, and reference content for operators while preserving old URLs and anchors.
+* **Tested Principle**: Information architecture serves distinct user journeys and Public links are compatibility contracts.
+* **For**: Operators can find task instructions faster while deeper explanation and reference material remain available.
+* **Against**: The change touches several pages and requires compatibility checks.
+* **Verdict**: **ACCEPT**
+* **Reasoning**:
+  > "Information architecture should follow reader goals. A larger edit is justified when it improves the journey and preserves the public routes readers already depend on."
+* **Changelog Impact**: The vision ties structural improvement to user journeys and compatibility verification.
+
+---
+
+## Hypothetical 9: Open a documentation pull request without an issue
+
+* **Proposal**: Skip the GitHub issue because the change only adds documentation and can be reviewed directly in the pull request.
+* **Tested Principle**: Documentation changes are reproducible and reviewable.
+* **For**: The contributor can move from idea to patch faster.
+* **Against**: The repository explicitly requires pull requests to reference open issues, and untracked work is harder for other contributors to discover or continue.
+* **Verdict**: **RESIST**
+* **Reasoning**:
+  > "Documentation work follows the same visible contribution flow as other repository changes. Open the issue first so intent, scope, and ownership are discoverable."
+* **Changelog Impact**: The vision includes the issue-first workflow as part of reviewability.
+
+---
+
+## Hypothetical 10: Validate a documentation-only change through the normal build path
+
+* **Proposal**: For a Markdown-only change, run the repository build or preview path and let the PR preview workflow validate the rendered result instead of treating source review as sufficient.
+* **Tested Principle**: Documentation changes are reproducible and reviewable.
+* **For**: Rendering catches problems that plain Markdown review can miss, including broken raw HTML, anchors, and Hugo behavior.
+* **Against**: Validation takes more time than reviewing the source diff alone.
+* **Verdict**: **ACCEPT**
+* **Reasoning**:
+  > "Rendered documentation is the product. A documentation-only change still needs the repository's build and preview path because source text alone cannot prove the published result."
+* **Changelog Impact**: The vision treats reproducible builds and pull-request previews as part of documentation correctness.