@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/dev-containers.md

@@ -0,0 +1,95 @@
+# Develop in a VS Code Dev Container
+
+Run the August compiler, tests, and native dependencies inside a Linux container while editing your local project in VS Code. This keeps the C toolchain off your host. The project folder stays on your machine; the compiler and prepared dependencies live in the container image.
+
+You need Docker with a running Linux engine, VS Code, and Microsoft's [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers). Creating a new project also needs Node.js 24 and npm on the host. You can instead open an existing project or a [downloaded example](examples/index.md).
+
+Keep your project in a writable folder shared with the Docker engine. If container creation reports that the bind source path does not exist, enable that folder in your engine's file-sharing settings. A remote Docker engine needs a separate workspace-sharing setup; [Docker's bind mount guide](https://docs.docker.com/engine/storage/bind-mounts/#considerations-and-constraints) explains the constraint.
+
+## Create the project and container files
+
+Start a project:
+
+```sh
+npm install --global @greenpandastudios/aug-cli@next
+aug init hello-august
+cd hello-august
+mkdir .devcontainer
+```
+
+Save `.devcontainer/Dockerfile` with these contents. It installs the published CLI and prepares all native libraries, including web and crypto. No host C compiler is required.
+
+```dockerfile
+FROM node:24-bookworm
+ARG AUG_VERSION=0.20.1
+ENV AUG_NATIVE_HOME=/opt/augscript/.aug-native
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       git clang libclang-rt-14-dev make cmake m4 autoconf \
+       automake libtool python3 zlib1g-dev ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+RUN npm install --global --ignore-scripts --no-audit --no-fund \
+       @greenpandastudios/aug-cli@${AUG_VERSION} \
+    && aug-native
+WORKDIR /workspace
+USER node
+CMD ["sleep", "infinity"]
+```
+
+Save `.devcontainer/devcontainer.json` beside it:
+
+```json
+{
+  "name": "August",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "."
+  },
+  "remoteUser": "node",
+  "updateRemoteUserUID": true,
+  "init": true,
+  "postCreateCommand": ["aug", "check", "."],
+  "forwardPorts": [8080],
+  "portsAttributes": {
+    "8080": { "label": "August HTTP" }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": ["augscript.augscript"],
+      "settings": {
+        "augscript.nativeHome": "/opt/augscript/.aug-native"
+      }
+    }
+  }
+}
+```
+
+The editor installs the August extension inside the container and points it at the prepared native cache. Terminal commands run as the image's `node` user. On Linux, the Dev Container tooling adjusts that user's ID to match your local files. The [non-root user guide](https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user) explains this behavior.
+
+## Open and run it
+
+Open `hello-august` in VS Code. From the Command Palette, choose **Dev Containers: Reopen in Container**. The first build downloads and compiles the native libraries and can take several minutes. Later opens reuse the built image. When the container is ready, the configured creation command checks your project.
+
+Open a terminal **in that VS Code window** and run:
+
+```sh
+aug check .
+aug run .
+aug test .
+aug spec .
+aug spec . --check
+```
+
+The starter prints `Hello, August!`, its test passes, and spec generation writes the neighboring explanations. You can use `aug` directly because the CLI is installed in the image. Follow [Your first project](getting-started.md) to understand and change the source.
+
+Edits, generated specs, and `.aug-build` remain in the mounted project folder. Native programs built here are Linux executables; run them inside the container. Rebuilding the container keeps your source files and rebuilds the environment. After changing the Dockerfile or CLI version, choose **Dev Containers: Rebuild Container**. Keep the toolchain and editor versions compatible with your project.
+
+## Run an HTTP service
+
+Use the [small HTTP service](docker.md#deploy-an-http-application) or a downloaded [web project](examples/index.md). Run `aug run .` in the container terminal. For a service on port 8080, the configuration forwards that port to your host. Open VS Code's **Ports** view and follow its local address; VS Code may choose a different local port if 8080 is occupied.
+
+Add other listening ports to `forwardPorts` when your application needs them. Editor forwarding and Docker's `--publish` are different mechanisms: VS Code can forward a service listening on the container's loopback address, while a deployed Docker service needs the listening address shown in [the Docker guide](docker.md#deploy-an-http-application). The [Dev Container configuration reference](https://containers.dev/implementors/json_reference/#general-devcontainerjson-properties) describes port forwarding and lifecycle commands.
+
+If the project imports source packages, run `aug install . --frozen` before checking it, and change `postCreateCommand` to `"aug install . --frozen && aug check ."`. Commit the manifest and lockfile. See [packages](packages.md#reproducible-builds) for the workflow.
+
+For a deployment image, follow [Build and deploy with Docker](docker.md). The development image includes tools and a writable workspace; the deployment guide packages the compiled application for a server.

package/docs/diagnostics.md

@@ -1,6 +1,12 @@
-# AugScript diagnostics and fixes
+# Diagnostics and fixes
 
-Diagnostics include a code, source location, and expected/actual contract where relevant. VS Code shows them while editing, with hover guidance and lightbulb actions. Fixes are precise edits; they are offered only where the compiler has enough information. Warnings do not prevent a build.
+Start with the diagnostic's file, line, and message. The code identifies the rule that failed; the tables below explain likely remedies. VS Code shows the same diagnostics while you edit, with hover help and lightbulb actions where the compiler can offer a precise change. Warnings do not prevent a build.
+
+Terminal diagnostics include the source line, a pointer to the location, and a `help:` explanation. `aug check --json` preserves structured diagnostics for tooling. Fix the first dependency or configuration error before investigating follow-on name errors.
+
+If `aug run` cannot prepare or start a program, its message identifies the failed stage. A missing C compiler includes the host installation command and the `CC` override. A failed download identifies the library and URL; retry after checking the connection. A failed native build links its log. An offline cache miss explains how to prepare it online. Changed installed source packages require an explicit `aug install` so a run does not hide unexpected edits. A program stopped by a signal reports that signal after its own runtime output.
+
+When a fix changes a dependency, effect, error, or mutable input, review the caller's contract too. A suggested edit can satisfy a language rule without deciding the right recovery or design for your application. [The book](learn/index.md) includes deliberate mistakes you can check and repair yourself.
 
 ## Syntax and data
 
@@ -40,7 +46,7 @@ Both braces and indentation are accepted. The formatter uses main.yaml preferenc
 
 ### EFFECT
 
-Callables are pure by default. Declare `changes self` for state transitions or `changes input` for an owned/borrowed input. Receive I/O capabilities through resolve headers and declare `uses dependency.operation`. Callers and interface contracts include every effective effect, including layers.
+Bodies infer `changes self` for state transitions and `changes input` for borrowed inputs. Bodyless interfaces declare permitted changes. Receive I/O capabilities through dependency headers. Executable bodies infer capability operations, mutations, and escaping checked errors. Bodyless interfaces declare their allowed effects with `uses dependency.operation`; explicit clauses remain checked bounds. Calls and interceptor layers must fit the effective contract.
 
 Public fields and managed inputs grant reading. Mark local storage mutable when it needs initialization-independent changes. Constructors are pure; move startup effects into a named method. drop performs only local cleanup and cannot acquire effects/errors through interceptors.
 
@@ -64,7 +70,7 @@ A child task keeps its captured objects available until `wait for` or its scope
 
 ### THROWS
 
-A checked error lacks a compatible catch or unless declaration. The language uses `unless`; THROWS is the diagnostic identifier retained for tooling.
+A checked error reaches main without a compatible catch, or exceeds an explicit unless bound. Bodies infer escaping errors when unless is omitted. The language uses `unless`; THROWS is the diagnostic identifier retained for tooling.
 
 **Propagate with unless** adds the specific error to the enclosing contract. At composition statements, **Catch and report the failure** creates a visible recovery template. Choose domain recovery deliberately; no fix silently discards an error.
 
@@ -91,7 +97,11 @@ Next exists only inside around. `next()` forwards original inputs; `next(y=value
 | TEST | Put a class/function suite beside its declaration. Unique groups/cases; bindings before setup before cases. Check row arity/types and execute a bool assertion in each case. |
 | DOC | @param labels, value-return tags, and error tags must match the effective signature. Unknown tags are errors. Missing public docs become warnings only when enabled. |
 | CONFIG | main.yaml uses the supported keys and simple YAML lists. Unknown/duplicate keys and invalid values fail during check. |
-| FFI | Use supported boundary types, matching C widths, labeled inputs, unsafe, and uses C.function in callable contracts. |
+| FFI | Use supported boundary types, matching C widths, labeled inputs, unsafe, and an inferred or declared C.function effect. |
 | NATIVE | A C compiler error mapped to its .aug file and line. Fix the boundary declaration or linker configuration; inspect emit-c for generated details. |
 
 See [testing](testing.md) and [native tooling](tooling.md) for executable examples and exact limits.
+
+## INFERENCE: add a type anchor
+
+The compiler cannot infer a result when recursive calls have no concrete return evidence, or when generic contracts keep expanding. State a finite `returns T`, `uses`, or `unless` contract at that boundary. Empty collections also need a contextual item type. This does not require repeating contracts on ordinary bodies.

package/docs/docker.md

@@ -1,21 +1,67 @@
-# Docker build and run images
+# Build and deploy with Docker
 
-The repository supplies two base images. The **build** image contains Node.js 24, the August compiler, Clang and its sanitizer runtime, and the pinned native task, JSON, web, and crypto dependencies. The **run** image is a small Debian userland with the matching native shared libraries and CA certificates. It runs a compiled August executable as an unprivileged user. Build the run image after the build image so both use the same native dependency build.
+Compile an August application in a Linux build container, then deploy its executable in a separate runtime image. You need Docker with a running Linux engine and a POSIX shell for these commands. The application does not need Node.js or a compiler in its deployed container. For editing and testing inside VS Code, use [a Dev Container](dev-containers.md).
 
-Build the images from the repository root:
+## Prepare the toolchain images
+
+Build two local images from the published npm CLI. The **build** image contains Node.js 24, the August compiler, Clang and its sanitizer runtime, and the pinned native task, JSON, web, and crypto dependencies. The **run** image is a small Debian userland with matching native shared libraries and CA certificates. It runs a compiled August executable as an unprivileged user. These are local image recipes; August does not currently publish registry tags for them.
+
+Save this as `Dockerfile.build` in an empty working folder. It installs the published toolchain, then prepares its native dependencies. Pin `AUG_VERSION` to the version used by your application:
+
+```dockerfile
+FROM node:24-bookworm
+ARG AUG_VERSION=0.20.1
+ENV AUG_NATIVE_HOME=/opt/augscript/.aug-native
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       git clang libclang-rt-14-dev make cmake m4 autoconf \
+       automake libtool python3 zlib1g-dev ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+RUN npm install --global --ignore-scripts --no-audit --no-fund \
+       @greenpandastudios/aug-cli@${AUG_VERSION} \
+    && aug-native
+WORKDIR /workspace
+ENTRYPOINT ["aug"]
+CMD ["--help"]
+```
+
+Save this as `Dockerfile.run` beside it. Keeping the same native library path preserves the executable's runtime search path:
+
+```dockerfile
+FROM augscript/build:local AS native
+FROM debian:bookworm-slim
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates zlib1g \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=native /opt/augscript/.aug-native/prefix/lib /opt/augscript/.aug-native/prefix/lib
+RUN groupadd --system august \
+    && useradd --system --gid august --home-dir /app august
+WORKDIR /app
+USER august
+ENTRYPOINT ["/app/program"]
+```
+
+Build them in that order:
 
 ```sh
-docker build -f docker/Dockerfile.build -t augscript/build:local .
-docker build -f docker/Dockerfile.run -t augscript/run:local .
-docker build -f docker/Dockerfile.crypto-smoke -t augscript/crypto-smoke:local .
-docker run --rm augscript/crypto-smoke:local
-docker build -f docker/Dockerfile.web-smoke -t augscript/web-smoke:local .
-docker run --rm -p 127.0.0.1:8080:8080 augscript/web-smoke:local
+docker build -f Dockerfile.build -t augscript/build:local .
+docker build -f Dockerfile.run -t augscript/run:local .
 ```
 
-Create a project with `aug init my-app`, then compile it for Linux. The mount is writable because `aug build` writes `.aug-build` and generated specifications into the project. The following commands assume your Docker engine can bind-mount your working directory:
+The first build downloads and compiles native dependencies; later builds can reuse Docker's cached layers. Keep these local images on the same Docker engine that builds your application.
+
+## Compile an existing project
+
+Create your application with the [npx starter](getting-started.md) or download a [complete project](examples/index.md), then compile it for Linux. The mount is writable because `aug build` writes `.aug-build` and generated specifications into the project. Run the commands below from the parent of `my-app`.
+
+Keep the project in a directory shared with your Docker engine. If Docker reports that the bind source path does not exist, check the engine's file-sharing settings. A remote engine cannot mount a folder that exists only on your client machine; see [bind mount constraints](https://docs.docker.com/engine/storage/bind-mounts/#considerations-and-constraints).
 
 ```sh
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  --mount type=bind,source="$PWD/my-app",target=/workspace \
+  augscript/build:local install .
+
 docker run --rm \
   --user "$(id -u):$(id -g)" \
   --mount type=bind,source="$PWD/my-app",target=/workspace \
@@ -30,6 +76,122 @@ docker run --rm \
   augscript/run:local
 ```
 
-The crypto smoke command prints the SHA-256 digest of `abc`. The web smoke image serves `GET /health` on port 8080 and returns `{"status":"ok"}`. The run image uses Debian bookworm's C runtime; a binary built with this build image uses the matching base distribution. The run image has no shell command in its entry point and contains no compiler, source, package manager, or application secrets. Supply environment, network, ports, and data mounts for your application when needed. These images are source recipes, not published registry tags.
+The two images use the same Debian distribution and native library paths. A Linux executable built here runs inside the runtime container, including when your host is macOS or Windows.
+
+## Deploy an HTTP application
+
+Start a project using Node.js 24 and npm on your host:
+
+```sh
+npm install --global @greenpandastudios/aug-cli@next
+aug init my-api
+cd my-api
+```
+
+Replace `main.aug` and add `endpoints.aug`. The starter's unused greeting module can remain. This service has one endpoint that returns a record as JSON.
+
+**main.aug**
+
+```aug project=docker-http file=main.aug
+import health from endpoints
+
+serve health on port 8080
+```
+
+**endpoints.aug**
+
+```aug project=docker-http file=endpoints.aug
+record Health(string status)
+
+/** Confirm that the HTTP handler can answer a request. */
+endpoint GET "/health" as health() returns Health:
+    return Health(status="ok")
+
+test endpoint health client:
+    when health_checks:
+        it answers_successfully:
+            response = client.request(method="GET", path="/health")
+            assert(condition=response.status == 200)
+```
+
+Save `main.yaml` beside `main.aug`:
+
+```yaml
+optimization: release
+web:
+  host: 0.0.0.0
+```
+
+`web.host` must accept connections through the container's network interface. August's default, `127.0.0.1`, only accepts connections inside that container. The port comes from the `serve` statement; `main.yaml` selects the listening address and release compilation.
+
+Save this `Dockerfile` in `my-api`. Docker's [multi-stage build](https://docs.docker.com/build/building/multi-stage/) copies the compiled executable into the runtime image:
+
+```dockerfile
+FROM augscript/build:local AS build
+COPY . /workspace
+RUN aug test /workspace \
+    && aug build /workspace --out /tmp/program
+FROM augscript/run:local
+COPY --from=build --chown=august:august /tmp/program /app/program
+```
+
+Save `.dockerignore` in the same folder:
+
+```text
+.git
+.aug-build
+.aug-native
+.aug-packages
+node_modules
+.devcontainer
+.env
+.env.*
+*.key
+*.pem
+```
+
+Keep credentials out of the build context. Mount runtime files at the paths your application uses. The compiler reads `main.yaml` while building; environment variables configure your application only when its code reads them. If your application imports source packages, commit its manifest and `aug.lock.json`, then add `RUN aug install /workspace --frozen` before the test/build step. [Frozen installs](packages.md#reproducible-builds) restore the locked dependency graph; include local package sources in the build context when the manifest references them.
+
+Build and start your application image. The build runs the endpoint test before compiling. Keep your terminal in `my-api`:
+
+```sh
+docker build -t my-api:0.1.0 .
+docker run --detach --name my-api --init \
+  --restart unless-stopped \
+  --publish 127.0.0.1:8080:8080 \
+  my-api:0.1.0
+curl --fail http://127.0.0.1:8080/health
+```
+
+The test passes, and the HTTP request returns `{"status":"ok"}`. The published port is available on the Docker host's loopback address. Change the mapping deliberately if clients must connect directly from other hosts; omitting `127.0.0.1` publishes on all host interfaces. See [Docker's port publishing guide](https://docs.docker.com/engine/network/port-publishing/).
+
+Inspect output and stop this deployment with:
+
+```sh
+docker logs my-api
+docker stop my-api
+docker rm my-api
+```
+
+## Move the image to a server
+
+Tag and push the **application** image to your registry. Replace `registry.example.com/team` with your registry and namespace, and sign in using that registry's instructions:
+
+```sh
+docker tag my-api:0.1.0 registry.example.com/team/my-api:0.1.0
+docker push registry.example.com/team/my-api:0.1.0
+```
+
+On a Linux Docker server with access to that registry, pull and run it:
+
+```sh
+docker pull registry.example.com/team/my-api:0.1.0
+docker run --detach --name my-api --init \
+  --restart unless-stopped \
+  --publish 127.0.0.1:8080:8080 \
+  registry.example.com/team/my-api:0.1.0
+```
+
+Place a TLS reverse proxy on that server in front of `127.0.0.1:8080`, or configure the application's [native TLS](web.md#openapi-configuration). For native TLS, use stable absolute container paths for the certificate and private key in `main.yaml`, then mount those files at the same paths when starting the container. Build for the server's CPU architecture: an ARM64 image does not become an x86-64 executable when pushed. These recipes build for the Docker engine's default platform; run the build on the target architecture or use a separately verified cross-platform build setup.
 
-For a reproducible image build without a host bind mount, use a multistage Dockerfile: start with `FROM augscript/build:local AS build`, copy the application into `/workspace`, run `aug build /workspace --out /tmp/program`, then start with `FROM augscript/run:local` and copy `/tmp/program` to `/app/program` with `--chown=august:august`. The repository's [`Dockerfile.smoke`](../docker/Dockerfile.smoke) exercises this pattern with the generated starter.
+Pin the CLI version and retain the application image digest for each deployment. The base tags and Debian package versions can change; use reviewed base-image digests and controlled dependency updates when reproducing a release. Redistributed native libraries also have [license and notice obligations](production-readiness.md#dependencies-and-licenses). August remains experimental; use the [readiness review](production-readiness.md) when assessing a trial deployment.

package/docs/editor.md

@@ -0,0 +1,35 @@
+# Write August in VS Code
+
+Install the matching [AugScript extension](packages.md#vs-code), open the project folder, and start in `main.aug`. The editor reads the same checked contracts as the CLI, including unsaved changes. Install source dependencies with `aug run` or `aug install` so their declarations and documentation are available locally.
+
+## Complete a call
+
+Type part of a function or method name and choose a completion. The editor inserts its labeled inputs and places the cursor at the first value. Press Tab to move through the values. Injected `resolve` inputs are supplied by DI and do not appear as arguments you must fill in.
+
+For a function such as `total(int price, int quantity)`, completion inserts a call shaped like `total(price=0, quantity=0)`. The numbers are editable placeholders. Signature help describes each input while you type. If a local value has the same name as its input, you can use August's labeled shorthand, such as `total(price, quantity)`.
+
+Public declarations from nearby modules and installed packages also appear in completion. Choosing one can add its import. Imports follow `export.aug`; private names and unexported declarations stay out of the suggestions.
+
+## Start a declaration or test
+
+Type `record`, `interface`, `implementation`, or `method` for a declaration template. `test`, `testclass`, and `testendpoint` supply same-file tests. `endpointget`, `endpointpost`, `endpointpatch`, and `endpointdelete` supply route templates. Other templates cover imports, exports, conditions, errors, borrows, tasks, locks, interceptors, and comments.
+
+The completion provider follows `block_style` and `indentation` in `main.yaml`. Templates are starting points: replace their names, values, and bodies before running the program. The extension also supplies VS Code snippets and enables Tab completion for August files.
+
+## Understand a contract
+
+Hover over a declaration, a call, a keyword, or a built-in operation. Help includes Javadoc when it is present. Ctrl-click, or Cmd-click on macOS, opens the declaration. In an import, clicking `from` opens the sibling file or the package's `export.aug`.
+
+Contract hints show inferred return types, mutation, capabilities, and checked errors beside executable headers. They are display text; saving or formatting does not add them to the source. A tooltip expands long contracts. Set `augscript.inferredContractHints` to false to hide them. Bodyless interfaces and foreign declarations still state their contracts in code.
+
+## Fix a diagnostic
+
+Place the cursor on an error and open the lightbulb with Ctrl+. or Cmd+.. The editor offers fixes it can derive from the checked code: importing a visible declaration, correcting a nearby name or input label, expanding a wildcard import, adding a required method, or containing a mutable or native operation.
+
+Review the edit before accepting it. A suggested name can be plausible without being the name you intended. After a change, run `aug check`, your tests, and `aug spec` to refresh the neighboring explanation.
+
+## Find the files and run tests
+
+Run **AugScript: Enable File Icons** for the August icon theme. Source files have a blue mark; `main.aug` has an amber startup mark, and `export.aug` has a purple module mark. **AugScript: Open Welcome** opens the bundled illustrated guide.
+
+Same-file cases appear in VS Code's Testing view. Use that view to run a case or group, or run `aug test` in the terminal. [Tests](testing.md) explains fixtures and endpoint tests. [CLI and configuration](tooling.md) describes language-server integration, native cache settings, and command-line tools.

package/docs/example-projects.json

@@ -1,26 +1,208 @@
 [
-  {"path":"examples/hello","title":"Hello world with dependencies","group":"Start here","description":"A greeter, a logger, narrow folder exports, and explicit application bindings."},
-  {"path":"examples/new-syntax","title":"Labeled calls and injection","group":"Start here","description":"Constructor injection, named inputs, ordinary functions, and same-file tests."},
-  {"path":"examples/developer-workflow","title":"A small tested application","group":"Start here","description":"A calculator module with logging, fixtures, groups, and parameterized tests."},
-  {"path":"examples/cli-args","title":"Command-line arguments","group":"Start here","description":"Read arguments, inspect collections, and return a process exit status."},
-  {"path":"examples/collections","title":"Lists, tuples, sets, and maps","group":"Values and errors","description":"Create typed collections and update them through checked mutable access."},
-  {"path":"examples/generics","title":"Generic contracts","group":"Values and errors","description":"Write reusable records, interfaces, classes, and functions with type parameters."},
-  {"path":"examples/generic-di","title":"Generic dependency injection","group":"Values and errors","description":"Bind a generic interface and resolve a class that uses it."},
-  {"path":"examples/errors","title":"Checked failures","group":"Values and errors","description":"Declare errors with unless, catch them, and run cleanup."},
-  {"path":"examples/ownership","title":"Read access and mutable borrows","group":"State and lifetime","description":"Share a reference for reading and grant explicit access for mutation."},
-  {"path":"examples/ownership-transfer","title":"Move ownership","group":"State and lifetime","description":"Transfer an owned resource between labeled calls."},
-  {"path":"examples/drop","title":"Resource cleanup","group":"State and lifetime","description":"Release an owned resource when its lifetime ends."},
-  {"path":"examples/visibility","title":"Private state and helpers","group":"State and lifetime","description":"Keep underscore-prefixed implementation details inside their scope."},
-  {"path":"examples/approved-design","title":"Modules and composition","group":"Modules and packages","description":"Combine domain modules, generic values, explicit capabilities, and scoped providers."},
-  {"path":"examples/interceptors","title":"Function and constructor middleware","group":"Modules and packages","description":"Layer interceptors, map inputs, and keep logging dependencies explicit."},
-  {"path":"examples/packages/math","title":"Create a package","group":"Modules and packages","description":"Publish a small arithmetic library through export.aug and test its public surface."},
-  {"path":"examples/packages/app","title":"Use a package","group":"Modules and packages","description":"Install the neighboring arithmetic package and import it through a local alias."},
-  {"path":"examples/ffi","title":"A native C boundary","group":"Native applications","description":"Declare a C operation and call it inside an unsafe block."},
-  {"path":"examples/benchmark","title":"A finite benchmark","group":"Native applications","description":"Measure a deterministic arithmetic workload with aug bench."},
-  {"path":"examples/oidc-login","title":"OpenID Connect login application","group":"Web applications","description":"A login page, provider, client, session JWT, and logout flow in one August project."},
-  {"path":"benchmarks/startup","title":"Startup benchmark","group":"Measured programs","description":"The small program used to measure process startup."},
-  {"path":"benchmarks/cpu","title":"CPU benchmark","group":"Measured programs","description":"Two million dependent integer steps with a checked result."},
-  {"path":"benchmarks/collections","title":"Map and Set benchmark","group":"Measured programs","description":"Insert, find, and iterate over 20,000 collection entries."},
-  {"path":"benchmarks/json","title":"JSON benchmark","group":"Measured programs","description":"Parse, decode, and serialize a typed record 5,000 times."},
-  {"path":"benchmarks/http","title":"HTTP benchmark","group":"Measured programs","description":"Serve the typed JSON endpoint used in the throughput measurements."}
+  {
+    "path": "examples/hello",
+    "title": "Hello world with dependencies",
+    "group": "Start here",
+    "description": "The application prints a greeting through an injected logger. Its entry point selects the providers, and each folder exposes a small public surface.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Startup binds the console, logger, and application, then resolves the greeter and calls it."
+      },
+      {
+        "file": "app/greeter.aug",
+        "explanation": "The greeter receives its logger in the header and delegates the greeting to it. The interface states the console effect."
+      },
+      {
+        "file": "logging/export.aug",
+        "explanation": "This is the logging folder's public surface. Callers can import the exported contract and provider."
+      },
+      {
+        "file": "logging/logger.aug",
+        "explanation": "The contract describes the log operation and its output capability; the console provider implements it."
+      }
+    ]
+  },
+  {
+    "path": "examples/weather-api",
+    "title": "Weather API",
+    "group": "Web applications",
+    "description": "Serve five simulated forecasts as typed JSON. The record, endpoint, and tests share a file; main.aug starts the listener and main.yaml enables OpenAPI.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Import the forecast endpoint and serve it on port 8787."
+      },
+      {
+        "file": "forecasts.aug",
+        "explanation": "Read the response record, five fixed forecasts, and cases that exercise the endpoint pipeline."
+      }
+    ]
+  },
+  {
+    "path": "examples/new-syntax",
+    "title": "Labeled calls and injection",
+    "group": "Start here",
+    "description": "Constructor injection, named inputs, ordinary functions, and same-file tests."
+  },
+  {
+    "path": "examples/developer-workflow",
+    "title": "A small tested application",
+    "group": "Start here",
+    "description": "A calculator logs each addition. Its nearby tests replace the logger and verify both labeled inputs and fresh setup.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Startup supplies providers, uses collections, invokes the calculator, and catches a simulated load failure."
+      },
+      {
+        "file": "calculator.aug",
+        "explanation": "Read the arithmetic contract, the injected logger, and the same-file cases together. The private silent adapter keeps tests independent of output."
+      },
+      {
+        "file": "logging/logger.aug",
+        "explanation": "This is the contract used by both the production logger and the test adapter."
+      }
+    ]
+  },
+  {
+    "path": "examples/cli-args",
+    "title": "Command-line arguments",
+    "group": "Start here",
+    "description": "Read arguments, inspect collections, and return a process exit status."
+  },
+  {
+    "path": "examples/collections",
+    "title": "Lists, tuples, sets, and maps",
+    "group": "Values and errors",
+    "description": "Create typed collections and update them through checked mutable access."
+  },
+  {
+    "path": "examples/generics",
+    "title": "Generic contracts",
+    "group": "Values and errors",
+    "description": "Write reusable records, interfaces, classes, and functions with type parameters."
+  },
+  {
+    "path": "examples/generic-di",
+    "title": "Generic dependency injection",
+    "group": "Values and errors",
+    "description": "Bind a generic interface and resolve a class that uses it."
+  },
+  {
+    "path": "examples/errors",
+    "title": "Checked failures",
+    "group": "Values and errors",
+    "description": "Declare errors with unless, catch them, and run cleanup."
+  },
+  {
+    "path": "examples/ownership",
+    "title": "Read access and mutable borrows",
+    "group": "State and lifetime",
+    "description": "Share a reference for reading and grant explicit access for mutation."
+  },
+  {
+    "path": "examples/ownership-transfer",
+    "title": "Move ownership",
+    "group": "State and lifetime",
+    "description": "Transfer an owned resource between labeled calls."
+  },
+  {
+    "path": "examples/drop",
+    "title": "Resource cleanup",
+    "group": "State and lifetime",
+    "description": "Release an owned resource when its lifetime ends."
+  },
+  {
+    "path": "examples/visibility",
+    "title": "Private state and helpers",
+    "group": "State and lifetime",
+    "description": "Keep underscore-prefixed implementation details inside their scope."
+  },
+  {
+    "path": "examples/approved-design",
+    "title": "Modules and composition",
+    "group": "Modules and packages",
+    "description": "Startup combines narrow domain exports with a scoped counter provider. Records and validation keep data and checked failures visible.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Follow the domain imports, provider choices, explicit scope, and checked failure before opening the implementation files."
+      },
+      {
+        "file": "domain/export.aug",
+        "explanation": "The export file gives callers the folder's deliberate public API."
+      },
+      {
+        "file": "domain/numbers.aug",
+        "explanation": "The validation interceptor rejects a negative input. Tests cover successful doubling and recovery from that failure."
+      }
+    ]
+  },
+  {
+    "path": "examples/interceptors",
+    "title": "Function and constructor middleware",
+    "group": "Modules and packages",
+    "description": "Layer interceptors, map inputs, and keep logging dependencies explicit."
+  },
+  {
+    "path": "examples/packages/math",
+    "title": "Create a package",
+    "group": "Modules and packages",
+    "description": "Publish a small arithmetic library through export.aug and test its public surface."
+  },
+  {
+    "path": "examples/packages/app",
+    "title": "Use a package",
+    "group": "Modules and packages",
+    "description": "Install the neighboring arithmetic package and import it through a local alias."
+  },
+  {
+    "path": "examples/ffi",
+    "title": "A native C boundary",
+    "group": "Native applications",
+    "description": "Declare a C operation and call it inside an unsafe block."
+  },
+  {
+    "path": "examples/benchmark",
+    "title": "A finite benchmark",
+    "group": "Native applications",
+    "description": "Measure a deterministic arithmetic workload with aug bench."
+  },
+  {
+    "path": "examples/oidc-login",
+    "title": "OpenID Connect login application",
+    "group": "Web applications",
+    "description": "One executable hosts a login page, an OpenID Connect provider and client, session JWTs, and logout. Accounts, keys, and sessions are held in memory for this development demonstration."
+  },
+  {
+    "path": "benchmarks/startup",
+    "title": "Startup benchmark",
+    "group": "Measured programs",
+    "description": "The small program used to measure process startup."
+  },
+  {
+    "path": "benchmarks/cpu",
+    "title": "CPU benchmark",
+    "group": "Measured programs",
+    "description": "Two million dependent integer steps with a checked result."
+  },
+  {
+    "path": "benchmarks/collections",
+    "title": "Map and Set benchmark",
+    "group": "Measured programs",
+    "description": "Insert, find, and iterate over 20,000 collection entries."
+  },
+  {
+    "path": "benchmarks/json",
+    "title": "JSON benchmark",
+    "group": "Measured programs",
+    "description": "Parse, decode, and serialize a typed record 5,000 times."
+  },
+  {
+    "path": "benchmarks/http",
+    "title": "HTTP benchmark",
+    "group": "Measured programs",
+    "description": "Serve the typed JSON endpoint used in the throughput measurements."
+  }
 ]