Various stuff

docs/nightly-alpha/by_example/examples.md

@@ -1,3 +1,5 @@
 > WARNING: Experimental standard library is used here. The full documentation covering it will be created soon as it get's more stable.
 
 Here, you’ll find a collection of practical scripts designed to help you quickly grasp the fundamentals and advanced features of the Amber programming language. Whether you are new to programming or an experienced developer, these examples will guide you through.
+
+Also check out [Awesome Amber](https://github.com/amber-lang/awesome-amberlang) - a curated list of awesome Amber tools, libraries, and resources.

docs/nightly-alpha/getting_started/faq.md

@@ -0,0 +1,109 @@
+# FAQ
+
+## Who is Amber for?
+
+Amber is aimed at developers who need the power of a modern programming language while staying within the ubiquitous Bash environment. It is especially useful for:
+- System administrators automating complex tasks.
+- DevOps engineers writing portable scripts.
+- Developers who want type‑safety and richer abstractions without abandoning the shell.
+
+## Why not Python?
+
+Python excels at many domains, but it requires a separate runtime and often incurs additional deployment overhead. Amber compiles directly to Bash, so you can:
+- Leverage existing shell tooling and pipelines.
+- Deploy a single script without installing a language interpreter.
+- Benefit from Bash‑native features (process substitution, job control) while enjoying high‑level syntax and safety.
+
+## Why not write Bash directly?
+
+Pure Bash scripts lack static type checking, modular imports, and modern language constructs. Amber provides:
+- A type system that catches errors early.
+- Structured imports and modules for better code organization.
+- Built‑in helpers (e.g., safe string interpolation, automatic error handling) that reduce boilerplate.
+
+## How does Amber compare to other languages?
+
+| Feature | Amber | Bash | Python | 
+|---|---|---|---|
+| Compiles to Bash | ✅ | ✅ | ❌ | 
+| Static typing | ✅ | ❌ | ✅ |
+| Native shell integration | ✅ | ✅ | ❌ |
+| Learning curve | Low | Moderate | Moderate |
+
+Amber fills a niche between lightweight shell scripting and full‑featured high‑level languages.
+
+## Is Amber production‑ready?
+
+Amber is under active development. The **nightly** provides the latest features and improvements, but may contain breaking changes. For production workloads, we recommend using the latest stable release (e.g., `0.5.x`) rather than the nightly build.
+
+## Can I use Amber for system scripts?
+
+Yes. Amber is designed for exactly that purpose. It can replace many typical Bash one‑liners and larger maintenance scripts, offering better readability, safety, and testability while still running on any POSIX‑compatible system.
+
+## What shells does Amber support?
+
+Currently, Amber targets **Bash** versions 3.2 through 5.3. We actively test across:
+- Linux (GNU bash 3.2-5.3)
+- macOS (bash 3.2)
+
+The compiled code is highly portable and will run on any system with the target shell installed.
+
+## Can Amber compile to other shells like Zsh or POSIX sh?
+
+Yes, this is actively being developed. Amber currently targets Bash as its primary shell, but we're working on mechanisms to allow targeting different shells. For now, you can use Amber's built-in features that have equivalents in POSIX shell, and we're working on a target configuration that will let you specify the target shell.
+
+## Why not just use an LLM to write scripts?
+
+LLMs can generate scripts, but they come with their own challenges:
+- Scripts may only work on your machine with your specific Bash version
+- No type safety or compile-time error checking
+- Security concerns with AI-generated code
+
+Amber provides the ease of writing with a modern syntax while ensuring your scripts work reliably across different environments.
+
+## Is Amber better than Python for shell tasks?
+
+It depends on your needs:
+
+| Consider Amber if... | Consider Python if... |
+|---------------------|----------------------|
+| You need maximum portability (only Bash required) | You need external dependencies (pip packages) |
+| Your scripts should run on any Unix-like system | You control the strict deployment environment |
+| You want type safety in shell scripting | You need complex data structures or pip dependencies |
+| You prefer Bash-native features | You need complex APIs or specific integration with other technologies |
+
+Many users use Amber for system administration and DevOps tasks where portability matters, and Python for application development where ecosystem matters more.
+
+## Can I use Amber for CI/CD pipelines?
+
+Absolutely! Amber shines in CI/CD because:
+- Only Bash is required (pre-installed on all CI runners)
+- Type safety catches errors before they reach production
+- Scripts compile to clean, readable Bash
+- *Bshchk* validation ensures dependencies exist
+- The compiler itself can be installed via various methods (bin, brew, pip, etc.)
+
+We even use Amber to generate parts of our own documentation!
+
+## How does Amber handle error cases?
+
+Amber enforces explicit error handling at compile time. If a function can fail, Amber will not compile your code unless you handle both success and failure cases, either by displaying an error message or failing silently. This prevents the "silent failure" problem common in Bash scripts where commands fail but execution continues as if nothing happened.
+
+## Can Amber generate Bash that ShellCheck would accept?
+
+Yes! Our focus on clean Bash generation means the compiled code follows ShellCheck (not yet at 100%) best practices. We're also working on integrating ShellCheck into our CI pipeline to ensure the generated code maintain high quality standards.
+
+## Is Amber suitable for beginners?
+
+Yes, Amber is designed to be approachable:
+- Syntax similar to JavaScript/Python/Rust (familiar to most developers)
+- Type system catches common mistakes early
+- Built-in functions reduce boilerplate
+- Documentation includes many examples
+- The compiler provides helpful error messages
+
+Many users start with Amber to learn scripting concepts before moving to more complex languages.
+
+## Why was Amber created?
+
+The project started as a PhD research topic, focusing on making Bash scripting safer and more maintainable. It gained community interest and evolved into a full project.

docs/nightly-alpha/getting_started/getting_started.md

@@ -36,3 +36,7 @@ Amber's compiled Bash scripts are actively tested across a range of environments
 | **Bash (Linux) GNU**  | 3.2 - 5.3     | Under Testing | All versions within this range are tested using [tianon/docker-bash](https://github.com/tianon/docker-bash). |
 | **Bash (macOS)**  | 3.2           | Under Testing | Verified through GitHub Actions `macos-latest` environments.       |
 | **Bash (Linux) Busy Box**           | Latest           | Under Testing | Busy box environment. As of right now latest is 5.3 |
+
+---
+
+If you're wondering who Amber is for or why to use it instead of other languages, check the [FAQ](getting_started/faq).

docs/nightly-alpha/getting_started/installation.md

@@ -145,7 +145,10 @@ sudo mkdir /opt /usr/local/bin
 Amber is currently an alpha-stage project, and to implement some features, we have chosen to integrate external tools.  
 If these tools are available on your system, they will be executed at the end of the Bash compilation process.
 
-* [bshchk](https://github.com/b1ek/bshchk): A runtime Bash dependency checker
+* [bshchk](https://github.com/b1ek/bshchk): A runtime Bash dependency checker. Install it separately on your system to enable automatic checking of external command dependencies in your compiled scripts. See the [bshchk repository](https://github.com/b1ek/bshchk) for installation instructions.
+
+> [!TIP]
+> bshchk is not included with Amber. For more information about using it, including inline directives and disabling it when needed, see the [Postprocessors section in the Usage guide](getting_started/usage#postprocessors).
 
 ## Uninstallation
 

docs/nightly-alpha/getting_started/usage.md

@@ -72,6 +72,23 @@ $ ./args.ab 1 2 3
 3
 ```
 
+### Preventing Execution with Bash
+
+If you write an Amber script with a shebang pointing to `amber`, there is a risk that someone might accidentally execute it with `bash` instead. To prevent this, you can add a check at the top of your script using the following technique:
+
+```ab
+// 2> /dev/null; exit 1
+
+// Your Amber code here
+echo("Hello world")
+```
+
+This line is valid in both Amber and Bash:
+- In **Amber**, `//` starts a comment, so the line is ignored
+- In **Bash**, `//` is treated as a comment (ignored), `2> /dev/null` suppresses errors, and `exit 1` terminates the script with an error code
+
+For more information about running Amber scripts, see [Running Amber Code](#running-amber-code).
+
 If you want to run just a small code snippet, you can do that as well:
 
 ```sh
@@ -119,6 +136,7 @@ Here is a list of plugins that support syntax highlighting for Amber language.
 | Icon | Name | Location |
 |---|:----:|:-----:|
 | LOGO:hx | **Helix Editor** | [Native Support](https://docs.helix-editor.com/lang-support.html) |
+| LOGO:kate | **Kate/KWrite** | [GitHub](https://github.com/amber-lang/amber-kate) |
 | LOGO:nova | **Nova** | [Nova extensions](https://extensions.panic.com/extensions/besya/besya.amber/) |
 | LOGO:vim | **Vim** | [Our extension repository](https://github.com/amber-lang/amber-vim) |
 | LOGO:vsc | **VS Code** | [VSC Marketplace](https://marketplace.visualstudio.com/items?itemName=Ph0enixKM.amber-language) or [Our extension repository](https://github.com/amber-lang/amber-vsc) |
@@ -129,11 +147,18 @@ Here is a list of plugins that support syntax highlighting for Amber language.
 
 ### Postprocessors
 
-By default, Amber runs postprocessor `bshchk` (if installed) on the compiled Bash script.  This functionality can be disabled with a `--no-proc` option:
+Amber supports postprocessors that can optionally run after compilation to enhance your scripts. These tools are not included with Amber but will be executed automatically if they are installed on your system.
 
-```sh
-$ amber build --no-proc=bshchk input.ab output.sh
-```
+#### bshchk
+
+[bshchk](https://github.com/b1ek/bshchk) is a runtime Bash dependency checker. It analyzes your compiled Bash script to ensure all external commands used are available at runtime, preventing runtime failures due to unavailable dependencies.
+
+**Features:**
+- Detects missing external commands before script execution
+- Prevents runtime failures due to unavailable dependencies
+- Supports inline directives for fine-grained control
+
+For installation instructions and usage details, please refer to the [bshchk README](https://github.com/b1ek/bshchk#readme).
 
 ### Minification
 
@@ -181,3 +206,45 @@ The optimizer is still being improved. If you encounter any issues with optimiza
 ```sh
 AMBER_NO_OPTIMIZE=1 amber ...
 ```
+
+### Custom Header and Footer
+
+Amber allows you to customize the header and footer of compiled scripts using environment variables:
+
+**AMBER_HEADER**: Path to a custom header file that replaces the default header. The header can use template variables:
+- `{{ version }}` - Amber compiler version
+
+**AMBER_FOOTER**: Path to a custom footer file that appends to the end of the script. The footer can use:
+- `{{ version }}` - Amber compiler version
+
+**Example custom header (`custom_header.sh`):**
+```bash
+#!/usr/bin/env bash
+# Custom header for production scripts
+# Project: {{ version }}
+# Generated on: $(date)
+```
+
+**Example custom footer (`custom_footer.sh`):**
+```bash
+# Custom footer
+# End of generated script
+```
+
+**Usage:**
+```sh
+# Using custom header
+AMBER_HEADER=./custom_header.sh amber build input.ab output.sh
+
+# Using both header and footer
+AMBER_HEADER=./custom_header.sh AMBER_FOOTER=./custom_footer.sh amber build input.ab output.sh
+```
+
+**Default header:**
+```bash
+#!/usr/bin/env bash
+# Written in [Amber](https://amber-lang.com/)
+# version: {{ version }}
+```
+
+Note: Custom headers and footers are useful for adding project-specific metadata, license information, or runtime checks to your compiled scripts.

docs/nightly-alpha/index.json

@@ -12,6 +12,10 @@
                     "path": "getting_started/usage",
                     "title": "Usage"
                 },
+                {
+                    "path": "getting_started/faq",
+                    "title": "FAQ"
+                },
                 {
                     "path": "getting_started/testing",
                     "title": "Testing"
@@ -177,8 +181,17 @@
                 {
                     "path": "by_example/lsp_installer",
                     "title": "LSP Installer"
+                },
+                {
+                    "path": "by_example/awesome_amber",
+                    "title": "Awesome Amber",
+                    "url": "https://github.com/amber-lang/awesome-amberlang"
                 }
             ]
+        },
+        {
+            "path": "press/press",
+            "title": "Press"
         }
     ]
 }

docs/nightly-alpha/press/press.md

@@ -0,0 +1,16 @@
+# Press
+
+Amber has attracted attention from various media outlets and community platforms, highlighting its innovative approach to compiling to Bash and its growing ecosystem.
+
+## Articles
+
+- [Amber compiles to Bash – Hackaday (May 2024)](https://hackaday.com/2024/05/22/amber-compiles-to-bash/) – An overview of Amber’s design and its ability to generate Bash scripts.
+- [Bash via transpiler – Hackaday (Feb 2026)](https://hackaday.com/2026/02/12/bash-via-transpiler/) – Discusses Amber as a modern transpiler targeting Bash.
+
+## Zine
+
+- [Paged Out #8](https://pagedout.institute/?page=issues.php) - A 1-page article about Amber
+
+## Conference talks
+
+- [FOSDEM 2026 – Amber: Bash Transpiler (talk slides)](https://fosdem.org/2026/schedule/event/GGLZS9-amber-lang-bash-transpiler/) – Presentation at FOSDEM with slide deck hosted at https://mte90.tech/Talk-Amber/.