Add descriptive markdown documentation

README.md

@@ -3,6 +3,9 @@
 [![CI](https://github.com/snider/wails-build-action/actions/workflows/ci.yml/badge.svg)](https://github.com/snider/wails-build-action/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-EUPL-green.svg)](LICENSE)
 
+> [!NOTE]
+> For comprehensive documentation, please visit the [docs](docs/) directory.
+
 
 > I help on lots of open source projects, im tired of doing the same thing over and over again.\
 > so, I'm going to put them all together in one place.\

docs/README.md

@@ -0,0 +1,15 @@
+# Documentation
+
+Welcome to the documentation for `snider/build@v3`. This repository contains a modular build action for multi-stack projects, primarily focused on Wails v2 but designed to be extensible.
+
+## Contents
+
+- [Getting Started](getting-started.md) - Learn how to use the action in your workflows.
+- [Configuration](configuration.md) - Detailed reference for inputs and environment variables.
+- [Architecture](architecture.md) - Understand the modular design and sub-actions.
+- [Stacks](stacks.md) - Specific information about supported stacks (Wails v2, Deno, etc.).
+
+## Quick Links
+
+- [Root README](../README.md)
+- [Action Definition](../action.yml)

docs/architecture.md

@@ -0,0 +1,32 @@
+# Architecture
+
+`snider/build@v3` is designed as a modular, multi-stack build system.
+
+## Overview
+
+The root action acts as a gateway. It performs discovery and then delegates the heavy lifting to specialized sub-actions.
+
+1.  **Discovery**: Scans the repository to identify the OS, architecture, and project type (stack).
+2.  **Orchestration**: Decides which specific build pipeline (stack) to run.
+3.  **Setup**: Installs dependencies (Go, Node, Deno, etc.) based on the selected stack or configuration.
+4.  **Build**: Compiles the application.
+5.  **Sign**: Signs the binaries (if configured).
+6.  **Package**: Archives the output and uploads it as an artifact (and release asset on tags).
+
+## Directory Structure
+
+- `actions/`
+    - `discovery/`: Detects environment and project metadata.
+    - `options/`: Computes build options (e.g., tags).
+    - `setup/`: Orchestrates dependency installation.
+        - `go/`, `npm/`, `deno/`, `conan/`: Specific setup actions.
+    - `build/`: Contains stack-specific build logic.
+        - `wails2/`: Logic for Wails v2 builds.
+    - `sign/`: Unified signing for macOS and Windows.
+    - `package/`: Handles artifact upload and releases.
+
+## Design Principles
+
+-   **Modular**: Each step is a separate composite action. You can use them individually if needed.
+-   **Smart Defaults**: The system tries to guess the right thing to do (Auto-Stack, Auto-Setup) but allows full override.
+-   **CI Gating**: The repository includes self-tests that run sub-actions to ensure stability.

docs/configuration.md

@@ -0,0 +1,58 @@
+# Configuration
+
+This document covers the inputs and configuration options for the `snider/build@v3` action.
+
+## Action Inputs
+
+These inputs are defined in `action.yml` and are passed to the `with` block in your workflow.
+
+| Input | Description | Required | Default |
+| :--- | :--- | :--- | :--- |
+| `build-name` | The name of the binary or app bundle. | **Yes** | - |
+| `build-platform` | Target platform (e.g., `linux/amd64`, `windows/amd64`, `darwin/universal`). | No | `darwin/universal` |
+| `build` | Whether to run the build step. | No | `true` |
+| `package` | Upload artifacts and publish release on tags. | No | `true` |
+| `sign` | Enable platform signing (if configured). | No | `false` |
+| `app-working-directory` | Root directory of the app being built. | No | `.` |
+| `AUTO_STACK` | Allow auto-selection of stack based on discovery. | No | `true` |
+| `AUTO_SETUP` | Allow sub-setup enabling based on env toggles. | No | `true` |
+| `STACK` | Explicitly override the stack (e.g., `wails2`). | No | `""` |
+
+## Environment Variables
+
+The action uses environment variables for certain configurations, particularly for sub-actions like Deno setup.
+
+### Deno Configuration
+
+You can configure Deno usage via environment variables. These take precedence over inputs in the setup phase.
+
+| Variable | Description | Example |
+| :--- | :--- | :--- |
+| `DENO_ENABLE` | Explicitly enable Deno setup. | `true`, `1`, `on` |
+| `DENO_BUILD` | Full command to run for Deno build. | `deno task build` |
+| `DENO_VERSION` | Version of Deno to install. | `v1.44.x` |
+| `DENO_WORKDIR` | Working directory for Deno command. | `frontend` |
+
+### Example with Environment Variables
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: snider/build@v3
+    env:
+      DENO_ENABLE: 'true'
+      DENO_VERSION: 'v1.44.x'
+      DENO_WORKDIR: 'frontend'
+      DENO_BUILD: 'deno task build'
+    with:
+      build-name: wailsApp
+      build-platform: linux/amd64
+```
+
+## Orchestration Control
+
+You can control how the action delegates tasks.
+
+- **Auto-Stack**: By default (`AUTO_STACK: true`), the action tries to detect if you are building a Wails v2 app, etc., and uses the appropriate sub-action.
+- **Auto-Setup**: By default (`AUTO_SETUP: true`), the orchestrator looks at environment variables to decide if it should set up Go, Node, Deno, etc.
+- **Manual Stack**: Set `STACK: wails2` to force the Wails v2 pipeline, ignoring auto-detection.

docs/getting-started.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+This guide will help you get started with the `snider/build@v3` action.
+
+## Basic Usage
+
+The simplest way to use this action is to let it auto-detect your project type.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: snider/build@v3
+    with:
+      build-name: myApp
+      build-platform: linux/amd64
+```
+
+This configuration will:
+1. Detect your project stack (e.g., Wails v2).
+2. Set up the necessary environment (Go, Node.js, etc.).
+3. Build your application.
+4. Package the artifacts.
+5. Upload artifacts (and publish release on tags).
+
+## Common Examples
+
+### Build Only (No Packaging)
+
+If you only want to verify the build without uploading artifacts:
+
+```yaml
+- uses: snider/build@v3
+  with:
+    build-name: myApp
+    build-platform: linux/amd64
+    package: false
+```
+
+### macOS Build
+
+```yaml
+- uses: snider/build@v3
+  with:
+    build-name: myApp
+    build-platform: darwin/universal
+```
+
+### Windows Build
+
+```yaml
+- uses: snider/build@v3
+  with:
+    build-name: myApp
+    build-platform: windows/amd64
+```
+
+## Next Steps
+
+- Check [Configuration](configuration.md) for more advanced options.
+- Read about [Stacks](stacks.md) for specific stack details.

docs/stacks.md

@@ -0,0 +1,34 @@
+# Stacks
+
+This action supports multiple stacks, with Wails v2 being the primary one currently.
+
+## Wails v2
+
+This is the default stack. It handles the complete lifecycle of a Wails v2 application.
+
+- **Detection**: Automatically detected if `wails.json` is present (logic in `discovery`).
+- **Setup**: Installs Go, Node.js, and the Wails CLI.
+- **Build**: Runs `wails build` with appropriate flags for the target platform.
+- **Signing**: Supports macOS code signing and notarization (requires secrets) and Windows signing.
+
+For detailed documentation on Wails v2 inputs and usage, refer to:
+- [Wails v2 Wrapper README](../actions/build/wails2/README.md)
+- [Wails Build Sub-action README](../actions/build/wails2/build/README.md)
+
+### macOS Code Signing
+
+Detailed instructions for setting up macOS code signing (Certificate, Notarization) can be found in the [Wails v2 README](../actions/build/wails2/README.md).
+
+## Deno
+
+Deno support is integrated into the setup phase and can be used alongside other stacks or independently.
+
+- **Enable**: Set `DENO_ENABLE: true` or define `DENO_BUILD`.
+- **Usage**: Useful for running frontend build steps before the main application build.
+
+For more details, see [Deno Setup README](../actions/setup/deno/README.md).
+
+## Future Stacks
+
+- **Wails v3**: Planned support once upstream stabilizes.
+- **C++**: Placeholder support exists via `conan` setup action.