fix: resolve sidebar issues and bring in framework specific guides (CopilotKit#5057)

## Summary
- Unify authored and generated shell-docs navigation so the sidebar
keeps the same structure across framework modes.
- Restore setup-content bundling from integration-owned docs and wire
shell-docs to consume the generated bundle at runtime.
- Audit and fix the LangGraph TypeScript and Google ADK code regions so
the generated snippets are more useful and accurate.
- Tighten docs/build routing and workflow triggers so shell-docs
rebuilds when the relevant integration docs inputs change.

## Testing
- Shell-docs unit tests passed.
- Shell-docs typecheck passed.
- Shell-docs lint passed with existing repository warnings only.
- Setup-content bundle generation passed.
- Python integration files compiled successfully.
- Workflow YAML parsed successfully.

Author: tylerslaton

.github/workflows/showcase_build.yml

@@ -15,6 +15,8 @@ on:
     branches: [main]
     paths:
       - "showcase/**"
+      - ".github/workflows/showcase_build.yml"
+      - ".github/workflows/showcase_build_check.yml"
   workflow_dispatch:
     inputs:
       service:
@@ -83,6 +85,9 @@ jobs:
           # single-line strings, but mixing styles (list vs. string)
           # in the same filters block is easy to misread during review.
           filters: |
+            workflow_config:
+              - '.github/workflows/showcase_build.yml'
+              - '.github/workflows/showcase_build_check.yml'
             shell:
               - 'showcase/shell/**'
               - 'showcase/shared/**'
@@ -141,6 +146,9 @@ jobs:
               - 'showcase/shared/**'
               - 'showcase/scripts/**'
               - 'showcase/integrations/*/manifest.yaml'
+              - 'showcase/integrations/*/docs-links.json'
+              - 'showcase/integrations/*/docs/setup/**'
+              - 'showcase/integrations/*/src/**'
             showcase_harness:
               - 'showcase/harness/**'
               - 'showcase/shared/**'
@@ -187,16 +195,11 @@ jobs:
             {"dispatch_name":"built-in-agent","filter_key":"built_in_agent","context":"showcase/integrations/built-in-agent","image":"showcase-built-in-agent","railway_id":"f4f8371a-bc46-45b2-b6d4-9c9af608bdbf","timeout":15,"lfs":false,"build_args":"","dockerfile":"","health_path":"/api/health"},
             {"dispatch_name":"shell-dojo","filter_key":"shell_dojo","context":".","image":"showcase-shell-dojo","railway_id":"7ad1ece7-2228-49cd-8a78-bddf30322907","timeout":10,"lfs":false,"build_args":"","dockerfile":"showcase/shell-dojo/Dockerfile","health_path":"/"},
             {"dispatch_name":"shell-dashboard","filter_key":"shell_dashboard","context":".","image":"showcase-shell-dashboard","railway_id":"4d5dfd74-be61-40b2-8564-b53b7dd4c15b","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","build_args_pb_url":"https://showcase-pocketbase-production.up.railway.app","build_args_shell_url":"https://showcase.copilotkit.ai","build_args_ops_url":"https://showcase-harness-production.up.railway.app","dockerfile":"showcase/shell-dashboard/Dockerfile","health_path":"/"},
-            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","railway_id":"7badfb8d-4228-414c-9145-b4026803714f","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","build_args_analytics":"yes","dockerfile":"showcase/shell-docs/Dockerfile","health_path":"/"},
+            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","railway_id":"7badfb8d-4228-414c-9145-b4026803714f","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","build_args_base_url":"https://docs.copilotkit.ai","build_args_shell_url":"https://showcase.copilotkit.ai","build_args_analytics":"yes","dockerfile":"showcase/shell-docs/Dockerfile","health_path":"/"},
             {"dispatch_name":"showcase-harness","filter_key":"showcase_harness","context":".","image":"showcase-harness","railway_id":"3a14bfed-0537-4d71-897b-7c593dca161d","timeout":20,"lfs":false,"build_args":"","dockerfile":"showcase/harness/Dockerfile","health_path":"/health"},
             {"dispatch_name":"showcase-aimock","filter_key":"showcase_aimock","context":"showcase/aimock","image":"showcase-aimock","railway_id":"0fa0435d-8a66-46f0-84fd-e4250b580013","timeout":5,"lfs":false,"build_args":"","dockerfile":"showcase/aimock/Dockerfile","health_path":"/health"}
           ]'
 
-          # Substitute trusted git context (sha, ref_name) into JSON placeholders.
-          # Routed through env: above to satisfy zizmor template-injection check.
-          ALL_SERVICES="${ALL_SERVICES//__GH_SHA__/$GITHUB_SHA_ENV}"
-          ALL_SERVICES="${ALL_SERVICES//__GH_REF_NAME__/$GITHUB_REF_NAME_ENV}"
-
           DISPATCH="$DISPATCH_SERVICE"
           CHANGES="${FILTER_CHANGES:-[]}"
 
@@ -211,11 +214,14 @@ jobs:
           #   dispatch == <specific service>: narrow to that service only (skips paths-filter so
           #     drift-rebuild and manual single-service dispatches work regardless of $changes).
           #   dispatch == "": push event — include services whose filter_key appears in paths-filter CHANGES.
-          MATRIX=$(echo "$ALL_SERVICES" | jq -c --arg dispatch "$DISPATCH" --argjson changes "$CHANGES" '
-            [.[] | (.filter_key as $fk | select(
+          MATRIX=$(echo "$ALL_SERVICES" | jq -c --arg dispatch "$DISPATCH" --argjson changes "$CHANGES" --arg sha "$GITHUB_SHA_ENV" --arg ref "$GITHUB_REF_NAME_ENV" '
+            [.[] |
+              if .build_args_sha == "__GH_SHA__" then .build_args_sha = $sha else . end |
+              if .build_args_branch == "__GH_REF_NAME__" then .build_args_branch = $ref else . end |
+              (.filter_key as $fk | select(
               $dispatch == "all" or
               ($dispatch != "" and $dispatch != "all" and $dispatch == .dispatch_name) or
-              ($dispatch == "" and ($changes | index($fk) != null))
+              ($dispatch == "" and (($changes | index("workflow_config") != null) or ($changes | index($fk) != null)))
             ))]
           ')
 
@@ -310,33 +316,49 @@ jobs:
 
       - name: Prepare build args
         id: build-args
+        env:
+          BUILD_ARGS_SHA: ${{ matrix.service.build_args_sha }}
+          BUILD_ARGS_BRANCH: ${{ matrix.service.build_args_branch }}
+          BUILD_ARGS_PB_URL: ${{ matrix.service.build_args_pb_url }}
+          BUILD_ARGS_BASE_URL: ${{ matrix.service.build_args_base_url }}
+          BUILD_ARGS_SHELL_URL: ${{ matrix.service.build_args_shell_url }}
+          BUILD_ARGS_OPS_URL: ${{ matrix.service.build_args_ops_url }}
+          BUILD_ARGS_ANALYTICS: ${{ matrix.service.build_args_analytics }}
+          NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.POSTHOG_PROJECT_KEY }}
+          NEXT_PUBLIC_REB2B_KEY: ${{ secrets.REB2B_KEY }}
+          NEXT_PUBLIC_SCARF_PIXEL_ID: ${{ secrets.SCARF_PIXEL_ID }}
+          NEXT_PUBLIC_REO_KEY: ${{ secrets.REO_PROJECT_KEY }}
+          NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID: ${{ secrets.GOOGLE_ANALYTICS_TRACKING_ID }}
         run: |
           ARGS=""
-          if [ -n "${{ matrix.service.build_args_sha }}" ]; then
-            ARGS="COMMIT_SHA=${{ matrix.service.build_args_sha }}"
-            ARGS="${ARGS}"$'\n'"BRANCH=${{ matrix.service.build_args_branch }}"
+          if [ -n "$BUILD_ARGS_SHA" ]; then
+            ARGS="COMMIT_SHA=${BUILD_ARGS_SHA}"
+            ARGS="${ARGS}"$'\n'"BRANCH=${BUILD_ARGS_BRANCH}"
+          fi
+          if [ -n "$BUILD_ARGS_PB_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POCKETBASE_URL=${BUILD_ARGS_PB_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_pb_url }}" ]; then
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POCKETBASE_URL=${{ matrix.service.build_args_pb_url }}"
+          if [ -n "$BUILD_ARGS_BASE_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_BASE_URL=${BUILD_ARGS_BASE_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_shell_url }}" ]; then
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SHELL_URL=${{ matrix.service.build_args_shell_url }}"
+          if [ -n "$BUILD_ARGS_SHELL_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SHELL_URL=${BUILD_ARGS_SHELL_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_ops_url }}" ]; then
+          if [ -n "$BUILD_ARGS_OPS_URL" ]; then
             # OPS_BASE_URL is required at build time by shell-dashboard's
             # next.config.ts rewrites() — without it `next build` aborts.
-            ARGS="${ARGS:+${ARGS}$'\n'}OPS_BASE_URL=${{ matrix.service.build_args_ops_url }}"
+            ARGS="${ARGS:+${ARGS}$'\n'}OPS_BASE_URL=${BUILD_ARGS_OPS_URL}"
           fi
-          if [ "${{ matrix.service.build_args_analytics }}" = "yes" ]; then
+          if [ "$BUILD_ARGS_ANALYTICS" = "yes" ]; then
             # Client-side analytics keys for the shell-docs bundle.
             # NEXT_PUBLIC_* values must reach `next build` so they get
             # inlined into client JS chunks. Sourced from repo secrets;
             # Railway runtime env doesn't reach this build step.
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POSTHOG_KEY=${{ secrets.POSTHOG_PROJECT_KEY }}"
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REB2B_KEY=${{ secrets.REB2B_KEY }}"
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SCARF_PIXEL_ID=${{ secrets.SCARF_PIXEL_ID }}"
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REO_KEY=${{ secrets.REO_PROJECT_KEY }}"
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID=${{ secrets.GOOGLE_ANALYTICS_TRACKING_ID }}"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POSTHOG_KEY=${NEXT_PUBLIC_POSTHOG_KEY}"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REB2B_KEY=${NEXT_PUBLIC_REB2B_KEY}"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SCARF_PIXEL_ID=${NEXT_PUBLIC_SCARF_PIXEL_ID}"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REO_KEY=${NEXT_PUBLIC_REO_KEY}"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID=${NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID}"
           fi
           # Use delimiter to safely pass multiline value
           echo "args<<BUILDARGS_EOF" >> $GITHUB_OUTPUT

.github/workflows/showcase_build_check.yml

@@ -9,9 +9,11 @@ on:
   pull_request:
     paths:
       - "showcase/**"
+      - ".github/workflows/showcase_build.yml"
+      - ".github/workflows/showcase_build_check.yml"
 
 concurrency:
-  group: showcase-build-check-${{ github.head_ref }}
+  group: showcase-build-check-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 permissions:
@@ -36,6 +38,9 @@ jobs:
         id: filter
         with:
           filters: |
+            workflow_config:
+              - '.github/workflows/showcase_build.yml'
+              - '.github/workflows/showcase_build_check.yml'
             shell:
               - 'showcase/shell/**'
               - 'showcase/shared/**'
@@ -94,6 +99,9 @@ jobs:
               - 'showcase/shared/**'
               - 'showcase/scripts/**'
               - 'showcase/integrations/*/manifest.yaml'
+              - 'showcase/integrations/*/docs-links.json'
+              - 'showcase/integrations/*/docs/setup/**'
+              - 'showcase/integrations/*/src/**'
             showcase_harness:
               - 'showcase/harness/**'
               - 'showcase/shared/**'
@@ -140,23 +148,22 @@ jobs:
             {"dispatch_name":"built-in-agent","filter_key":"built_in_agent","context":"showcase/integrations/built-in-agent","image":"showcase-built-in-agent","timeout":15,"lfs":false,"build_args":"","dockerfile":""},
             {"dispatch_name":"shell-dojo","filter_key":"shell_dojo","context":".","image":"showcase-shell-dojo","timeout":10,"lfs":false,"build_args":"","dockerfile":"showcase/shell-dojo/Dockerfile"},
             {"dispatch_name":"shell-dashboard","filter_key":"shell_dashboard","context":".","image":"showcase-shell-dashboard","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","build_args_pb_url":"https://showcase-pocketbase-production.up.railway.app","build_args_shell_url":"https://showcase.copilotkit.ai","build_args_ops_url":"https://showcase-harness-production.up.railway.app","dockerfile":"showcase/shell-dashboard/Dockerfile"},
-            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","dockerfile":"showcase/shell-docs/Dockerfile"},
+            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","timeout":10,"lfs":true,"build_args_sha":"__GH_SHA__","build_args_branch":"__GH_REF_NAME__","build_args_base_url":"https://docs.copilotkit.ai","build_args_shell_url":"https://showcase.copilotkit.ai","build_args_analytics":"yes","dockerfile":"showcase/shell-docs/Dockerfile"},
             {"dispatch_name":"showcase-harness","filter_key":"showcase_harness","context":".","image":"showcase-harness","timeout":20,"lfs":false,"build_args":"","dockerfile":"showcase/harness/Dockerfile"},
             {"dispatch_name":"showcase-aimock","filter_key":"showcase_aimock","context":"showcase/aimock","image":"showcase-aimock","timeout":5,"lfs":false,"build_args":"","dockerfile":"showcase/aimock/Dockerfile"}
           ]'
 
-          # Substitute trusted PR head sha/ref into JSON placeholders.
-          # Routed through env: above to satisfy zizmor template-injection check.
-          # Note: PR_HEAD_REF is attacker-controllable (fork branch name) but is only
-          # consumed as a Docker build-arg label inside the isolated build context.
-          ALL_SERVICES="${ALL_SERVICES//__GH_SHA__/$PR_HEAD_SHA}"
-          ALL_SERVICES="${ALL_SERVICES//__GH_REF_NAME__/$PR_HEAD_REF}"
-
           CHANGES="${FILTER_CHANGES:-[]}"
 
-          # PR event only — filter to changed services
-          MATRIX=$(echo "$ALL_SERVICES" | jq -c --argjson changes "$CHANGES" '
-            [.[] | (.filter_key as $fk | select(
+          # PR event only — filter to changed services. Use jq --arg for
+          # untrusted PR metadata so branch names are encoded as JSON data,
+          # not interpolated into shell source.
+          MATRIX=$(echo "$ALL_SERVICES" | jq -c --argjson changes "$CHANGES" --arg sha "$PR_HEAD_SHA" --arg ref "$PR_HEAD_REF" '
+            [.[] |
+              if .build_args_sha == "__GH_SHA__" then .build_args_sha = $sha else . end |
+              if .build_args_branch == "__GH_REF_NAME__" then .build_args_branch = $ref else . end |
+              (.filter_key as $fk | select(
+              ($changes | index("workflow_config") != null) or
               ($changes | index($fk) != null)
             ))]
           ')
@@ -193,20 +200,38 @@ jobs:
 
       - name: Prepare build args
         id: build-args
+        env:
+          BUILD_ARGS_SHA: ${{ matrix.service.build_args_sha }}
+          BUILD_ARGS_BRANCH: ${{ matrix.service.build_args_branch }}
+          BUILD_ARGS_PB_URL: ${{ matrix.service.build_args_pb_url }}
+          BUILD_ARGS_BASE_URL: ${{ matrix.service.build_args_base_url }}
+          BUILD_ARGS_SHELL_URL: ${{ matrix.service.build_args_shell_url }}
+          BUILD_ARGS_OPS_URL: ${{ matrix.service.build_args_ops_url }}
+          BUILD_ARGS_ANALYTICS: ${{ matrix.service.build_args_analytics }}
         run: |
           ARGS=""
-          if [ -n "${{ matrix.service.build_args_sha }}" ]; then
-            ARGS="COMMIT_SHA=${{ matrix.service.build_args_sha }}"
-            ARGS="${ARGS}"$'\n'"BRANCH=${{ matrix.service.build_args_branch }}"
+          if [ -n "$BUILD_ARGS_SHA" ]; then
+            ARGS="COMMIT_SHA=${BUILD_ARGS_SHA}"
+            ARGS="${ARGS}"$'\n'"BRANCH=${BUILD_ARGS_BRANCH}"
+          fi
+          if [ -n "$BUILD_ARGS_PB_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POCKETBASE_URL=${BUILD_ARGS_PB_URL}"
+          fi
+          if [ -n "$BUILD_ARGS_BASE_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_BASE_URL=${BUILD_ARGS_BASE_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_pb_url }}" ]; then
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POCKETBASE_URL=${{ matrix.service.build_args_pb_url }}"
+          if [ -n "$BUILD_ARGS_SHELL_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SHELL_URL=${BUILD_ARGS_SHELL_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_shell_url }}" ]; then
-            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SHELL_URL=${{ matrix.service.build_args_shell_url }}"
+          if [ -n "$BUILD_ARGS_OPS_URL" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}OPS_BASE_URL=${BUILD_ARGS_OPS_URL}"
           fi
-          if [ -n "${{ matrix.service.build_args_ops_url }}" ]; then
-            ARGS="${ARGS:+${ARGS}$'\n'}OPS_BASE_URL=${{ matrix.service.build_args_ops_url }}"
+          if [ "$BUILD_ARGS_ANALYTICS" = "yes" ]; then
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_POSTHOG_KEY=pr-build"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REB2B_KEY=pr-build"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SCARF_PIXEL_ID=pr-build"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_REO_KEY=pr-build"
+            ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID=G-PRBUILD"
           fi
           # Use delimiter to safely pass multiline value
           echo "args<<BUILDARGS_EOF" >> $GITHUB_OUTPUT

showcase/integrations/google-adk/docs/setup/agent-config-setup.mdx

@@ -15,7 +15,7 @@
     available in session state on every turn — read it inside a
     `before_model_callback` to inject preferences into the system prompt.
 
-    <DemoCode file="src/agents/hitl_in_chat_agent.py" region="setup" />
+    <DemoCode file="src/agents/agent_config_agent.py" region="agent-config-setup" />
 
   </Step>
 </Steps>

showcase/integrations/google-adk/docs/setup/agent-context-setup.mdx

@@ -0,0 +1,21 @@
+<Steps>
+  <Step>
+    ### Install the ADK + AG-UI bridge
+
+    ```bash
+    pip install ag-ui-adk
+    ```
+
+  </Step>
+  <Step>
+    ### Read CopilotKit context before each model call
+
+    `useAgentContext` entries arrive in ADK session state under
+    `state["copilotkit"]["context"]`. Add `AGUIToolset()` to the agent and
+    use a `before_model_callback` to inject those read-only values into the
+    system instruction.
+
+    <DemoCode file="src/agents/readonly_state_agent_context_agent.py" region="agent-context-setup" />
+
+  </Step>
+</Steps>

showcase/integrations/google-adk/docs/setup/shared-state-setup.mdx

@@ -14,7 +14,7 @@
     it directly and the runtime forwards updates to the UI. Wire your
     `LlmAgent` with `AGUIToolset()` and CopilotKit takes care of the rest.
 
-    <DemoCode file="src/agents/hitl_in_chat_agent.py" region="setup" />
+    <DemoCode file="src/agents/shared_state_read_write_agent.py" region="shared-state-setup" />
 
     See `src/agents/shared_state_read_write_agent.py` for the bidirectional
     pattern: a before-model callback reads UI-authored preferences out of

showcase/integrations/google-adk/docs/setup/state-streaming-setup.mdx

@@ -0,0 +1,21 @@
+<Steps>
+  <Step>
+    ### Install the ADK + AG-UI bridge
+
+    ```bash
+    pip install ag-ui-adk
+    ```
+
+  </Step>
+  <Step>
+    ### Declare the predicted state mapping
+
+    ADK state streaming uses `PredictStateMapping` to map the streaming
+    `write_document` tool argument into `state["document"]`. Add
+    `AGUIToolset()` to the agent so CopilotKit can forward the state deltas to
+    the UI.
+
+    <DemoCode file="src/agents/shared_state_streaming_agent.py" region="state-streaming-middleware" />
+
+  </Step>
+</Steps>

showcase/integrations/google-adk/docs/setup/subagents-setup.mdx

@@ -16,7 +16,7 @@
     delegation. Delegation events are written to `tool_context.state` and
     flow back to the UI through CopilotKit's shared-state channel.
 
-    <DemoCode file="src/agents/hitl_in_chat_agent.py" region="setup" />
+    <DemoCode file="src/agents/subagents_agent.py" region="subagent-setup" />
 
     See `src/agents/subagents_agent.py` for the supervisor + three
     sub-agents pattern with a live delegation log.