docs: add readmes for workflow modules

Author: sidpalas

03-core-features/filters/README.md

@@ -0,0 +1,15 @@
+# 03. Core Features
+
+This module demonstrates the building blocks used in all GitHub Actions workflows. Each example workflow is located in `.github/workflows/` and follows the naming pattern `03-core-features--<name>.yaml`.
+
+## Included Workflows
+
+- [**03-core-features--01-hello-world.yaml**](../.github/workflows/03-core-features--01-hello-world.yaml) – the most basic workflow that prints a message from an inline bash step.
+- [**03-core-features--02-step-types.yaml**](../.github/workflows/03-core-features--02-step-types.yaml) – shows different step types including bash, Python, and an action from the marketplace.
+- [**03-core-features--03-workflows-jobs-steps.yaml**](../.github/workflows/03-core-features--03-workflows-jobs-steps.yaml) – illustrates how workflows are organised into jobs and steps and how jobs can run in parallel or depend on each other.
+- [**03-core-features--04-triggers-and-filters.yaml**](../.github/workflows/03-core-features--04-triggers-and-filters.yaml) – explores triggering events and path filters. This workflow watches changes inside [`03-core-features/filters`](./filters/).
+- [**03-core-features--05-environment-variables.yaml**](../.github/workflows/03-core-features--05-environment-variables.yaml) – explains variable scoping at workflow, job and step level.
+- [**03-core-features--06-passing-data.yaml**](../.github/workflows/03-core-features--06-passing-data.yaml) – passes data between jobs using job outputs and environment variables.
+- [**03-core-features--07-secrets-and-variables.yaml**](../.github/workflows/03-core-features--07-secrets-and-variables.yaml) – demonstrates injecting secrets and variables from both the repository and environments.
+
+See the `filters` directory for sample files that are used by the triggers and filters workflow.

04-advanced-features/README.md

@@ -0,0 +1,20 @@
+# 04. Advanced Features
+
+This module covers several advanced capabilities of GitHub Actions. Each topic is demonstrated by a workflow in [`.github/workflows`](../.github/workflows) whose file name begins with `04-advanced-features--`.
+
+## Topics & Workflows
+
+- **Runner Types** – [`04-advanced-features--01-runner-types.yaml`](../.github/workflows/04-advanced-features--01-runner-types.yaml)
+  - shows GitHub-hosted Linux/Windows/macOS runners, container jobs, and a third-party runner
+- **Artifacts** – [`04-advanced-features--02-artifacts.yaml`](../.github/workflows/04-advanced-features--02-artifacts.yaml)
+  - one job uploads a text file and a second job downloads and displays it
+- **Caching** – [`04-advanced-features--03-caching.yaml`](../.github/workflows/04-advanced-features--03-caching.yaml)
+  - demonstrates the `actions/cache` action and `setup-node` built‑in caching
+- **GitHub Permissions** – [`04-advanced-features--04-github-permissions.yaml`](../.github/workflows/04-advanced-features--04-github-permissions.yaml)
+  - compares read-only vs read/write `GITHUB_TOKEN` permissions on pull requests
+- **Third-Party Authentication** – [`04-advanced-features--05-third-party-auth.yaml`](../.github/workflows/04-advanced-features--05-third-party-auth.yaml)
+  - contrasts static AWS credentials with OIDC-based authentication
+- **Matrix & Conditionals** – [`04-advanced-features--06-matrix-and-conditionals.yaml`](../.github/workflows/04-advanced-features--06-matrix-and-conditionals.yaml)
+  - runs a job across a two-dimensional matrix and skips steps based on conditions
+
+The caching example also includes a minimal Node project in [`caching/minimal-node-project`](./caching/minimal-node-project).

06-authoring-actions/README.md

@@ -1 +1,41 @@
-https://docs.github.com/en/actions/sharing-automations/reusing-workflowss
+# 06. Authoring Actions
+
+This module demonstrates how to build custom GitHub Actions and reusable workflows. Each example below has a workflow located in `.github/workflows/` following the pattern `06-authoring-actions--<name>.yaml`.
+
+## Composite Action
+- **Folder:** `composite-action`
+- **Workflow:** [`.github/workflows/06-authoring-actions--01-composite-action.yaml`](../.github/workflows/06-authoring-actions--01-composite-action.yaml)
+- **What it does:** defines a simple action that prints a greeting and outputs a
+  random number. The workflow demonstrates calling the action twice in
+  separate jobs.
+
+## Reusable Workflows
+- **Folder:** `reuseable-workflow`
+- **Workflows:**
+ - [`.github/workflows/06-authoring-actions--02-reuseable-workflows-source.yaml`](../.github/workflows/06-authoring-actions--02-reuseable-workflows-source.yaml) – defines the reusable workflow
+ - [`.github/workflows/06-authoring-actions--03-reuseable-workflows-caller.yaml`](../.github/workflows/06-authoring-actions--03-reuseable-workflows-caller.yaml) – calls the reusable workflow
+  - **What they do:** the source workflow exposes inputs and secrets and prints
+    them in a job. The caller workflow triggers manually and invokes the source
+    workflow using both a relative path and a specific commit reference.
+
+## JavaScript & TypeScript Actions
+- **Folder:** `javascript-actions`
+- **Workflow:** [`.github/workflows/06-authoring-actions--04-javascript-actions.yaml`](../.github/workflows/06-authoring-actions--04-javascript-actions.yaml)
+- **What it does:** runs three jobs showcasing different approaches for
+  JavaScript/TypeScript actions:
+  - `javascript-action-no-build` uses vanilla Node with dependencies committed.
+  - `javascript-action-with-build` demonstrates a Node action that normally
+    would require a build step (pulled in as a submodule).
+  - `typescript-action-with-build` shows a TypeScript action compiled before
+    execution.
+
+## Container Actions
+- **Folder:** `container-actions`
+- **Workflow:** [`.github/workflows/06-authoring-actions--05-container-actions.yaml`](../.github/workflows/06-authoring-actions--05-container-actions.yaml)
+- **What it does:** runs three jobs that execute container-based actions:
+  - `shell-dockerfile` builds a shell-based container action from a local
+    Dockerfile each run.
+  - `shell-public-container-image` reuses a prebuilt container image to skip the
+    build step.
+  - `python-dockerfile` builds and runs a Python action defined by a Dockerfile
+    and prints a greeting.

09-best-practices/README.md

@@ -0,0 +1,7 @@
+1. measure your pipelines (e.g. send data to honeycomb)
+2. invest in local iteration (act + task)
+3. pull logic out of the workflow
+4. cache toolchain
+5. cache dependencies
+6. use docker cache
+7. share logic smartly