docs(vc-shell): clean up concepts/ for narrative-only role

.github/workflows/protect-generated.yml

@@ -0,0 +1,33 @@
+name: protect-generated
+
+on:
+  pull_request:
+    paths:
+      - "platform/developer-guide/docs/custom-apps-development/vc-shell/**"
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'auto-generated') && github.event.pull_request.user.login != 'vc-shell-docs-bot' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Detect AUTO-GENERATED file edits
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          CHANGED=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'platform/developer-guide/docs/custom-apps-development/vc-shell/**' || true)
+          STATUS=0
+          for f in $CHANGED; do
+            # Skip files outside the auto-managed subtree.
+            case "$f" in
+              */vc-shell/introduction/*|*/vc-shell/getting-started/*|*/vc-shell/guides/*|*/vc-shell/reference/migration/*) continue ;;
+            esac
+            if [[ -f "$f" ]] && grep -q "AUTO-GENERATED FROM vc-shell" "$f"; then
+              echo "::error file=$f::$f is auto-generated from vc-shell. Edit the source *.docs.md in the vc-shell repo and run yarn docs:sync."
+              STATUS=1
+            fi
+          done
+          exit $STATUS

.gitignore

@@ -295,3 +295,5 @@ site/
 
 # Local gh-pages folder for versioned content
 gh-pages/
+
+.venv/

mkdocs.yml

@@ -539,12 +539,18 @@ extra:
                     content:
                         - title: Developer Guide
                           links:
-                              - title: Overview
-                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/vc-shell-overview
+                              - title: Introduction
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/introduction/
                               - title: Getting Started
-                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/Getting-started/creating-first-custom-app/
-                              - title: Connecting to Platform
-                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform/
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/getting-started/installation/
+                              - title: Concepts
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/concepts/blade-navigation/
+                              - title: Components
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/components/data-display/vc-data-table/
+                              - title: Composables
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/composables/blade-navigation/useBlade/
+                              - title: Reference
+                                url: /platform/developer-guide/latest/custom-apps-development/vc-shell/reference/cli/create-vc-app/
                   - title: Deployment on Virto Cloud
                     content:
                         - links:
@@ -574,7 +580,7 @@ extra:
                   - title: VC-Shell
                     links:
                         - title: Developer Getting Started
-                          url: /platform/developer-guide/latest/custom-apps-development/vc-shell/Getting-started/creating-first-custom-app
+                          url: /platform/developer-guide/latest/custom-apps-development/vc-shell/getting-started/installation/
             - iconSrc: assets/icons/graphql.svg
               title: APIs
               content:

overrides/main.html

@@ -33,6 +33,25 @@
 <!-- End Google Tag Manager -->
 {% endblock %}
 
+{% block announce %}
+  <div id="vc-shell-frozen-banner" hidden style="background: var(--md-warning-fg-color, #f0a020); color: #fff; padding: 0.5rem 1rem; text-align: center;">
+    Live demos on this page show the latest framework version, which may differ from the documented version.
+  </div>
+  <script>
+    (function () {
+      // Only on vc-shell pages.
+      if (window.location.pathname.indexOf('custom-apps-development/vc-shell') === -1) return;
+      // Only on numbered release versions (e.g. "2.0", "3.0"); hide on "latest" / main builds.
+      var versionEl = document.querySelector('[data-mike-version]') || document.querySelector('.md-version__current');
+      var version = versionEl ? versionEl.textContent.trim() : '';
+      if (/^\d+\.\d+$/.test(version)) {
+        var banner = document.getElementById('vc-shell-frozen-banner');
+        if (banner) banner.hidden = false;
+      }
+    })();
+  </script>
+{% endblock %}
+
 {% block html_body %}
 <!-- Google Tag Manager (noscript) -->
 <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HSVF5VV"

platform/developer-guide/docs/assets/stylesheets/vc-shell-docs.css

@@ -0,0 +1,49 @@
+/* Storybook embed */
+.vc-storybook-embed {
+  margin: 1.5rem 0;
+}
+.vc-storybook-embed iframe {
+  width: 100%;
+  height: var(--height, 400px);
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 6px;
+  background: var(--md-default-bg-color);
+}
+.vc-storybook-embed a {
+  display: inline-block;
+  margin-top: 0.5rem;
+  font-size: 0.85em;
+  color: var(--md-default-fg-color--light);
+  text-decoration: none;
+}
+.vc-storybook-embed a:hover {
+  color: var(--md-typeset-a-color);
+}
+
+/* Annotated screenshots */
+.vc-annotated-screenshot {
+  position: relative;
+  display: inline-block;
+  margin: 1rem 0;
+}
+.vc-annotated-screenshot img {
+  display: block;
+  max-width: 100%;
+}
+.vc-annotated-screenshot .annotation {
+  position: absolute;
+  left: var(--x, 0);
+  top: var(--y, 0);
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  background: var(--md-accent-fg-color);
+  color: var(--md-accent-bg-color);
+  font-size: 14px;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.25);
+  transform: translate(-50%, -50%);
+}

platform/developer-guide/docs/custom-apps-development/.pages

@@ -0,0 +1,5 @@
+title: Custom Apps Development
+nav:
+  - Overview: overview.md
+  - Registering New App: how-to-register-new-app.md
+  - vc-shell

platform/developer-guide/docs/custom-apps-development/vc-shell/.pages

@@ -0,0 +1,9 @@
+title: VC-Shell
+nav:
+  - introduction
+  - getting-started
+  - concepts
+  - components
+  - composables
+  - guides
+  - reference