@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/examples/packages-math/src/arithmetic.md

@@ -29,8 +29,9 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int:
+add(int left, int right):
     return left + right
 test add:
     when "addition":
@@ -39,8 +40,9 @@ test add:
 ```
 
 ```aug [Braces]
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int {
+add(int left, int right) {
     return left + right
 }
 test add {
@@ -60,61 +62,21 @@ test add {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `add` · [source](arithmetic.md#code) {#symbol-add}
 
-### In this file
+Add two integers. It takes `left` as an integer (First value) and `right` as an integer (Second value). It returns `int` — Their sum. It returns `left` plus `right`.
 
-- [`add`](arithmetic.md#symbol-add) is a function returning `int`.
-- [`test add`](arithmetic.md#symbol-test-20-add) is a same-file test suite.
+### `test add` · [source](arithmetic.md#code) {#symbol-test-20-add}
 
-### `add` {#symbol-add}
+Tests [`add`](arithmetic.md#symbol-add). Each case gets fresh setup and dependencies.
 
-[source](arithmetic.md#code)
+#### `addition`
 
-**Inputs**
+##### `adds_two_integers` · [source](arithmetic.md#code)
 
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
+The test requires [`add`](arithmetic.md#symbol-add) with `left` `2` and `right` `3` equals `5`.
 
-Returns: `int`.
-
-**What it does**
-
-- Return `left` plus `right`.
-
-**Author documentation**
-
-Add two integers.
-
-**Returns** Their sum.
-
-**Parameters**
-- `left`: First value.
-- `right`: Second value.
-
-### `test add` {#symbol-test-20-add}
-
-[source](arithmetic.md#code)
-
-Same-file function tests for [`add`](arithmetic.md#symbol-add). Each case gets isolated setup and dependency bindings.
-
-#### Group `addition`
-
-##### `adds_two_integers`
-
-[source](arithmetic.md#code)
-
-- Call `assert` with (call [`add`](arithmetic.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
-
-### Built-in operations used by this file
-
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

package/docs/examples/packages-math/src/export.md

@@ -29,10 +29,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export add from arithmetic
 ```
 
 ```aug [Braces]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export add from arithmetic
 ```
 
@@ -44,19 +46,9 @@ export add from arithmetic
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Exports
 
-### In this file
-
-- Export `add` from this folder.
-
-### Folder exports
-
-- Export the declaration `add` from [`arithmetic.aug`](arithmetic.md#symbol-add).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `add` from [`arithmetic.aug`](arithmetic.md#symbol-add).
 
 ::::
 

package/docs/examples/startup-benchmark/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 The small program used to measure process startup.
 
-Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -21,12 +21,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/startup-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check benchmarks/startup
-aug spec benchmarks/startup
-aug run benchmarks/startup
+cd startup-benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.

package/docs/examples/startup-benchmark/main.md

@@ -28,10 +28,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 print(value=7)
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 print(value=7)
 ```
 
@@ -43,25 +45,11 @@ print(value=7)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It prints `7`.
 
-- Run 1 other startup step in source order.
-
-### Startup, in source order
-
-- Call `print` with `value` = `7`.
-
-### Built-in operations used by this file
-
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

package/docs/examples/visibility/counter.md

@@ -29,30 +29,32 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface ICounter:
     label() returns string
 Counter(mutable int value) implements ICounter:
-    _label() returns string:
+    _label():
         return _prefix()
-    label() returns string:
+    label():
         return self._label()
-_prefix() returns string:
+_prefix():
     return "count"
 ```
 
 ```aug [Braces]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface ICounter {
     label() returns string
 }
 Counter(mutable int value) implements ICounter {
-    _label() returns string {
+    _label() {
         return _prefix()
     }
-    label() returns string {
+    label() {
         return self._label()
     }
 }
-_prefix() returns string {
+_prefix() {
     return "count"
 }
 ```
@@ -65,77 +67,27 @@ _prefix() returns string {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `ICounter` · interface · [source](counter.md#code) {#symbol-ICounter}
 
-### In this file
+#### `ICounter.label` · [source](counter.md#code) {#symbol-ICounter.label}
 
-- [`ICounter`](counter.md#symbol-ICounter) is an interface.
-- [`Counter`](counter.md#symbol-Counter) is a class implementing `ICounter`.
-- [`_prefix`](counter.md#symbol-_prefix) is a function returning `string`.
+It returns `string`.
 
-### `ICounter` {#symbol-ICounter}
+### `Counter` · class · [source](counter.md#code) {#symbol-Counter}
 
-[source](counter.md#code)
+It implements [`ICounter`](counter.md#symbol-ICounter). It takes `value` as an integer, kept mutable.
 
-Interface.
+#### `Counter._label` · [source](counter.md#code) {#symbol-Counter._label}
 
-#### `ICounter.label` {#symbol-ICounter.label}
+It is private to its defining scope. It returns [`_prefix`](counter.md#symbol-_prefix).
 
-[source](counter.md#code)
+#### `Counter.label` · [source](counter.md#code) {#symbol-Counter.label}
 
-Returns: `string`.
+It returns [`self._label`](counter.md#symbol-Counter._label).
 
-Interface contract. A selected implementation supplies the behavior.
+### `_prefix` · [source](counter.md#code) {#symbol-_prefix}
 
-### `Counter` {#symbol-Counter}
-
-[source](counter.md#code)
-
-Behavioral class.
-
-Satisfies [`ICounter`](counter.md#symbol-ICounter).
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and mutable.
-
-#### `Counter._label` {#symbol-Counter._label}
-
-[source](counter.md#code)
-
-Private to its defining scope.
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`_prefix`](counter.md#symbol-_prefix).
-
-#### `Counter.label` {#symbol-Counter.label}
-
-[source](counter.md#code)
-
-Returns: `string`.
-
-**What it does**
-
-- Return call [`Counter._label`](counter.md#symbol-Counter._label) on `self`.
-
-### `_prefix` {#symbol-_prefix}
-
-[source](counter.md#code)
-
-Private to its defining scope.
-
-Returns: `string`.
-
-**What it does**
-
-- Return `"count"`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It is private to its defining scope. It returns `"count"`.
 
 ::::
 

package/docs/examples/visibility/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Keep underscore-prefixed implementation details inside their scope.
 
-Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -22,12 +22,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/visibility.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check examples/visibility
-aug spec examples/visibility
-aug run examples/visibility
+cd visibility
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/visibility/main.md

@@ -29,6 +29,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 counter = Counter(value=1)
 print(value=counter.label())
@@ -38,6 +39,7 @@ print(value=counter.value)
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 counter = Counter(value=1)
 print(value=counter.label())
@@ -55,41 +57,15 @@ print(value=counter.value)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It sets `counter` to a [`Counter`](counter.md#symbol-Counter) with `value` `1`. It prints [`counter.label`](counter.md#symbol-Counter.label). With temporary permission to change `counter`, it sets `counter.value` to `2`. It prints `counter.value`.
 
-- Run 4 other startup steps in source order.
+### Dependencies
 
-### Startup, in source order
+It uses [`Counter`](counter.md#symbol-Counter) ([`label`](counter.md#symbol-Counter.label) and `value`) from `counter`.
 
-- Set `counter` to call [`Counter`](counter.md#symbol-Counter) with `value` = `1`.
-- Call `print` with `value` = call [`Counter.label`](counter.md#symbol-Counter.label) on `counter`.
-- Grant exclusive mutable access to `counter` for this block, then end the borrow:
-  - Set `value` of `counter` to `2`.
-- Call `print` with `value` = `value` of `counter`.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Counter`](counter.md#symbol-Counter)
-
-Class from `counter`.
-
-- Construct with `value`: `int` → [`Counter`](counter.md#symbol-Counter).
-- Read `value` (`int`); its owner can change it.
-- [`Counter.label`](counter.md#symbol-Counter.label) (no caller inputs) → `string`.
-
-### Built-in operations used by this file
-
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

package/docs/examples/weather-api/forecasts.md

@@ -0,0 +1,168 @@
+---
+title: "forecasts.aug · Weather API"
+generated: true
+source: "examples/weather-api/forecasts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `forecasts.aug`
+
+[Weather API](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "forecasts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast():
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+test endpoint weatherForecast client:
+    when "forecasts":
+        it "returns_json":
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        it "rejects_other_methods":
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+```
+
+```aug [Braces]
+// aug-spec: "forecasts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast() {
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+}
+test endpoint weatherForecast client {
+    when "forecasts" {
+        it "returns_json" {
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        }
+        it "rejects_other_methods" {
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
+
+### `WeatherForecast` · immutable record · [source](forecasts.md#code) {#symbol-WeatherForecast}
+
+The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. It takes `date` as a string, kept read-only, `temperatureC` and `temperatureF` as integers, kept read-only, and `summary` as a string, kept read-only.
+
+### `weatherForecast` · [source](forecasts.md#code) {#symbol-weatherForecast}
+
+`weatherForecast` handles `GET /weatherforecast`. Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. It returns a list of 5 [`WeatherForecast`](forecasts.md#symbol-WeatherForecast) records, with `(date, temperatureC, temperatureF, summary)` values of `("2026-01-01", 0, 32, "Freezing")`, `("2026-01-02", 10, 50, "Cool")`, `("2026-01-03", 20, 68, "Mild")`, `("2026-01-04", 30, 86, "Warm")`, and `("2026-01-05", 35, 95, "Hot")`, in that order.
+
+### `test weatherForecast client` · [source](forecasts.md#code) {#symbol-test-20-weatherForecast-20-client}
+
+Tests [`weatherForecast`](forecasts.md#symbol-weatherForecast). Each case gets fresh setup and dependencies.
+
+#### `forecasts`
+
+##### `returns_json` · [source](forecasts.md#code)
+
+It sets `response` to `client.request` with `method` `"GET"` and `path` `"/weatherforecast"`. The test requires `response.status` equals `200`.
+
+##### `rejects_other_methods` · [source](forecasts.md#code)
+
+It sets `response` to `client.request` with `method` `"POST"` and `path` `"/weatherforecast"`. The test requires `response.status` equals `405`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/weather-api/index.md

@@ -0,0 +1,42 @@
+---
+title: "Weather API"
+generated: true
+source: "examples/weather-api"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Weather API
+
+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.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Follow the program
+
+Read [`main.aug`](main.md). Import the forecast endpoint and serve it on port 8787.
+
+Read [`forecasts.aug`](forecasts.md). Read the response record, five fixed forecasts, and cases that exercise the endpoint pipeline.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+- [`main.yaml`](main-yaml.md)
+
+## Try this project
+
+[Download this project](/downloads/weather-api.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd weather-api
+aug check .
+aug spec .
+aug test .
+aug run .
+```
+
+[Browse all examples](../index.md)

package/docs/examples/weather-api/main-yaml.md

@@ -0,0 +1,21 @@
+---
+title: "main.yaml · Weather API"
+generated: true
+source: "examples/weather-api/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[Weather API](index.md) · Project configuration
+
+```yaml
+block_style: indent
+openapi:
+  enabled: true
+  title: "Weather forecast API"
+  version: "0.1.0"
+```