More documentation is needed on how variables/secrets are rendered/scoped across reusable workflows & actions

Hi community, I feel the need for better documentation on how variables are available, scoped, rendered across reusable workflows, actions, etc. It's almost a shot in the dark trying to get our values running through workflows.

Example 1 - ${{ github.workspace }}

In the workflow definition, ${{ github.workspace }} renders to nothing, example

jobs:
  job_name:
    uses: .../.github/workflows/template.yaml@pipelines
    with:
      workspace: ${{ github.workspace }} # This resolves to empty string

However, in the reusable workflow .../.github/workflows/template.yaml@pipelines, it renders the correct path

on:
  workflow_call:
    inputs:
      someArg:
        description: 'Some args'
        required: true
        type: string

jobs:
  ci:
    name: Build, test and push
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo ${{ github.workspace }} # This prints something

Then in the documentation for available environment variables, we see GITHUB_WORKSPACE as an available variable. How does GITHUB_WORKSPACE becomes this github.workspace, on which occasions? When are they available? Where? (this goes for everything github.*

Example 2 - Organization secrets

As stated here: https://github.com/actions/runner/issues/1413

Organization-level secrets aren't available in the caller workflow. But repo-specific repos are!

Example 3 - env at root is not available at any moment in the caller workflow

In the caller workflow, if env is defined at the root level of the framework, values aren't achievable anywhere within the jobs.<job_id>.with.

env:
   var1: 'value'

jobs:
  job_name:
    uses: .../.github/workflows/template.yaml@pipelines
    with:
      workspace: ${{ env.var1 }} # This doesn't work
      workspace: ${ var1 } # This doesn't work

Trying to access from the job definition is also invalid. * and doesn't allow for reuse of variables in different uses.

jobs:
  job_name:
    env: # This is invalid syntax
       var1: 'test' # This is invalid syntax
    uses: .../.github/workflows/template.yaml@pipelines
    with:
      workspace: ${{ github.workspace }} # This resolves to empty string

I mean, the list goes on. I have an entire document on how to rig solutions to get these values through, but I don't see it anywhere on the documentation. For instance, Azure DevOps has differences for ${{ var }} [ var ] $(var) .

Start with the reusable-workflow examples in the issue and the linked actions/runner#1413 discussion. Document when github.* contexts, environment variables, secrets, and caller-workflow env values are available across reusable workflows and actions, including the shown failing cases. Done means the documentation clearly explains scope, rendering, and supported ways to pass each value.