Add walkthrough artifact generation

README.md

@@ -73,6 +73,7 @@ on:
     types: [created]
 
 permissions:
+  actions: read       # needed only when walkthrough_url is configured
   contents: read
   pull-requests: write
   issues: write
@@ -125,6 +126,34 @@ The free tier is metered per repository owner against a weekly cap. For more —
 
 Add the secret under **Settings → Secrets and variables → Actions** (e.g. `OPENROUTER_API_KEY = sk-or-...`). For local runs with `scripts/run_local.sh`, export `OPENROUTER_API_KEY` as an environment variable instead. When `llm_api_key` is set it takes precedence; `license_key` is used only when no key is set; with neither, the free OIDC tier is used.
 
+## PR walkthrough artifact
+
+The paid CodeBoarding walkthrough Lambda can turn the posted architecture review into a `walkthrough.json` artifact. Store the Lambda base URL in `WALKTHROUGH_URL` and an active `pro` or `custom` license in `CODEBOARDING_LICENSE`, then configure the review action as follows:
+
+```yaml
+permissions:
+  actions: read        # lets the Lambda read this run's review artifact
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+steps:
+  - uses: CodeBoarding/CodeBoarding-action@v1
+    with:
+      license_key: ${{ secrets.CODEBOARDING_LICENSE }}
+      walkthrough_url: ${{ secrets.WALKTHROUGH_URL }}
+```
+
+When `walkthrough_url` is set, the action first uploads the PR analysis artifact and posts the sticky review comment. It then calls `<WALKTHROUGH_URL>/walkthrough` with the PR URL, the supplied license, and the workflow token, and uploads the Lambda response as a `codeboarding-walkthrough-<pr>-<sha>` artifact containing `walkthrough.json`. The Lambda token needs Actions-read access; use a GitHub App token for `github_token` only if that app also has Actions read permission. Leave `walkthrough_url` empty to skip this paid, opt-in step.
+
+### Artifact lifecycle
+
+1. Review mode writes the PR-head architecture data to `codeboarding-pr-<pr>-<sha>`. That artifact contains `analysis.json` and `metadata.json`, including the workflow run and head SHA.
+2. The action uploads that source artifact, builds and posts the sticky architecture review comment, and only then starts the walkthrough request.
+3. The Lambda receives the PR URL, paid license, and short-lived workflow token. It uses the token to find and read the matching review artifact; neither token is stored in the returned document.
+4. The action validates that the Lambda response is JSON and uploads it unchanged as `codeboarding-walkthrough-<pr>-<sha>`, containing `walkthrough.json`. Consumers can download that result artifact or read its URL from the action's `walkthrough_artifact_url` output.
+
 ## Bring your own LLM provider
 
 OpenRouter is the default, but you can use any provider the engine supports. Set `llm_provider` and pass that provider's key:
@@ -275,6 +304,7 @@ Review mode does not need `contents: write`: PR-specific generated files are sto
 | `trigger_command` | review | `/codeboarding` | Slash command for trusted on-demand runs. |
 | `cta_base_url` | review | empty | Click-proxy base URL: deep-links the editor link into VS Code/Cursor and adds a "get the extension" link (tracks owner/repo/pr). Empty links to the extension listing instead (GitHub strips `vscode:`/`cursor:` from comments). |
 | `webview_base_url` | review | `https://app.codeboarding.org` | Hosted webview base URL. The PR comment links to an artifact-backed head-vs-comparison-branch architecture diff. Set empty to disable the browser link. |
+| `walkthrough_url` | review | empty | Base URL of the paid walkthrough Lambda, normally `${{ secrets.WALKTHROUGH_URL }}`. When set, the action invokes `<url>/walkthrough` after posting the review comment and uploads `walkthrough.json`. Requires `license_key` and a GitHub token with `actions: read`. |
 | `output_dir` | sync | `.codeboarding` | Directory the rendered docs and analysis metadata are committed to. Owned by the action: pre-existing top-level `.md` files in it are deleted on every run. |
 | `output_format` | sync | `.md` | Output format. Only `.md` is supported. |
 | `target_branch` | sync | `${{ github.ref_name }}` | Branch the generated docs are pushed to. |
@@ -290,6 +320,7 @@ Review mode does not need `contents: write`: PR-specific generated files are sto
 | `n_changed` | review | Number of changed components, counted recursively. |
 | `truncated` | review | `true` when the graph was reduced to fit GitHub Mermaid limits. |
 | `review_artifact_url` | review | GitHub Actions artifact URL containing the PR-head `analysis.json` and comparison-branch metadata. |
+| `walkthrough_artifact_url` | review | GitHub Actions artifact URL containing the Lambda-generated `walkthrough.json`; empty when walkthroughs are not configured. |
 | `analysis_mode` | sync | `full` or `incremental`: whether the run rebuilt the analysis from scratch or reused the committed baseline. |
 | `files_written` | sync | The generated files written for the docs commit. |
 | `committed` | sync | `true` when a docs commit was pushed to `target_branch`; `false` when sync mode ran but had nothing to commit (or the push failed open). Empty only if sync mode did not run. |

action.yml

@@ -71,6 +71,10 @@ inputs:
     description: 'Review mode: hosted webview base URL. The PR comment links to an artifact-backed head-vs-comparison-branch architecture diff; review mode does not commit generated files to PR branches. Set empty to disable the browser link.'
     required: false
     default: 'https://app.codeboarding.org'
+  walkthrough_url:
+    description: 'Review mode: base URL of the paid CodeBoarding walkthrough Lambda (for example, secrets.WALKTHROUGH_URL). When set, the action invokes <url>/walkthrough after posting the review comment and uploads its walkthrough.json response as a workflow artifact. Requires license_key and a token with actions: read.'
+    required: false
+    default: ''
   trigger_command:
     description: 'Review mode: slash-command that triggers the action from a PR comment (issue_comment event). A comment whose first word is this runs the diagram on-demand.'
     required: false
@@ -134,6 +138,9 @@ outputs:
   review_artifact_url:
     description: 'Review mode: GitHub Actions artifact URL containing the PR-head analysis.json and metadata.'
     value: ${{ steps.upload_review_artifact.outputs.artifact-url }}
+  walkthrough_artifact_url:
+    description: 'Review mode: GitHub Actions artifact URL containing walkthrough.json, when walkthrough_url is configured.'
+    value: ${{ steps.upload_walkthrough_artifact.outputs.artifact-url }}
 
 runs:
   using: 'composite'
@@ -1377,6 +1384,68 @@ runs:
         path: ${{ steps.body.outputs.body_file }}
         GITHUB_TOKEN: ${{ inputs.github_token }}
 
+    # The walkthrough Lambda ingests the review artifact just uploaded above, so
+    # it must run only after the review has been published. It receives the
+    # workflow token solely to read the PR and its Actions artifact; the Lambda
+    # response is saved verbatim as its own artifact for later consumers.
+    - name: Generate PR walkthrough
+      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && inputs.walkthrough_url != ''
+      id: walkthrough
+      shell: bash
+      env:
+        WALKTHROUGH_URL: ${{ inputs.walkthrough_url }}
+        LICENSE_KEY: ${{ inputs.license_key }}
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+        OWNER_REPO: ${{ github.repository }}
+        PR: ${{ steps.guard.outputs.pr_number }}
+        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
+      run: |
+        set -euo pipefail
+        endpoint="${WALKTHROUGH_URL%/}/walkthrough"
+        [ -n "$LICENSE_KEY" ] || {
+          echo "::error::walkthrough_url requires license_key with an active pro or custom CodeBoarding license."
+          exit 1
+        }
+        [ -n "$GITHUB_TOKEN" ] || {
+          echo "::error::walkthrough_url requires github_token with Actions read access."
+          exit 1
+        }
+        echo "::add-mask::$LICENSE_KEY"
+        echo "::add-mask::$GITHUB_TOKEN"
+
+        WALKTHROUGH_PATH="${RUNNER_TEMP}/walkthrough.json"
+        PR_URL="https://github.com/${OWNER_REPO}/pull/${PR}"
+        python3 - "$PR_URL" <<'PY' | curl --fail-with-body --silent --show-error \
+          --retry 3 --retry-all-errors --max-time 900 \
+          -X POST "$endpoint" \
+          -H "Authorization: Bearer $LICENSE_KEY" \
+          -H "X-GitHub-Token: $GITHUB_TOKEN" \
+          -H "Content-Type: application/json" \
+          --data @- \
+          --output "$WALKTHROUGH_PATH"
+        import json
+        import sys
+        print(json.dumps({"pull_request_url": sys.argv[1]}))
+        PY
+        python3 - "$WALKTHROUGH_PATH" <<'PY'
+        import json
+        import sys
+
+        with open(sys.argv[1], encoding="utf-8") as response:
+            json.load(response)
+        PY
+        echo "path=$WALKTHROUGH_PATH" >> "$GITHUB_OUTPUT"
+        echo "name=codeboarding-walkthrough-${PR}-${HEAD_SHA}" >> "$GITHUB_OUTPUT"
+
+    - name: Upload PR walkthrough artifact
+      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && inputs.walkthrough_url != ''
+      id: upload_walkthrough_artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ steps.walkthrough.outputs.name }}
+        path: ${{ steps.walkthrough.outputs.path }}
+        retention-days: 14
+
     # ---- Sync mode: render and commit the architecture. ----
 
     - name: Render docs