@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/approved-design/main.md

@@ -33,6 +33,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 Console and SystemConsole from august.io
 import Application and ApplicationImpl and Fruit and double and RangeError from domain
 import Counter and Counters from counters
@@ -48,7 +49,9 @@ match names.get(key=2):
     when some name:
         print(value=name)
 (code, label) to (3, "plum")
-print(value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length())
+print(
+    value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length()
+)
 scope:
     resolve Counter to counter
     borrow counter:
@@ -62,6 +65,7 @@ catch RangeError error:
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Application and ApplicationImpl and Fruit and double and RangeError from domain
 import Counter and Counters from counters
@@ -80,7 +84,9 @@ match names.get(key=2) {
     }
 }
 (code, label) to (3, "plum")
-print(value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length())
+print(
+    value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length()
+)
 scope {
     resolve Counter to counter
     borrow counter {
@@ -105,110 +111,27 @@ catch RangeError error {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Providers
 
-### In this file
+`Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). The same instance is shared.
 
-- Include providers from `Counters`.
-- Register 2 dependency providers before startup.
-- Run startup operations with checked error recovery.
-- Run 7 other startup steps in source order.
+`Application` is provided by [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl). The same instance is shared. It requires bindings for `Console`. Include providers from [`Counters`](counters.md#symbol-Counters).
 
-### Dependency providers
+### Startup
 
-Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+It sets `app` to the instance provided for `Application`. It calls [`app.start`](domain/app.md#symbol-Application.start). It sets `names` to a map with `1` mapped to `"apple"`; `2` mapped to `"pear"`. If the value under `2` in `names` is null, it prints `"missing fruit"`.
 
-- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
-- Provide [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl) when `Application` is requested. Reuse one instance. Required dependencies: `Console`.
-- Include the providers from [`Counters`](counters.md#symbol-Counters) before execution.
+If the value under `2` in `names` is not null, using `name` for it prints `name`. It splits a tuple containing `3`, `"plum"` into `code` and `label` in order. It prints the number of elements in a set containing a [`Fruit`](domain/models.md#symbol-Fruit) with `code` and `name` from `label`, a [`Fruit`](domain/models.md#symbol-Fruit) with `name` from `label` and `code`. Within a task and ownership scope, it sets `counter` to the instance provided for `Counter`.
 
-### Startup, in source order
+With temporary permission to change `counter`, it calls [`counter.increment`](counters.md#symbol-Counter.increment). It prints [`counter.value`](counters.md#symbol-Counter.value). On leaving this scope, join its child tasks and release its local values. It prints [`double`](domain/numbers.md#symbol-double) with `amount` `7`.
 
-- Set `app` to the instance provided for `Application`.
-- Call [`Application.start`](domain/app.md#symbol-Application.start) on `app`.
-- Set `names` to a map with `1` mapped to `"apple"`; `2` mapped to `"pear"`.
-- Select the matching case for call `get` on `names` with `key` = `2`:
-  - A null value, including omitted optional input:
-    - Call `print` with `value` = `"missing fruit"`.
-  - A present, non-null value, named `name`:
-    - Call `print` with `value` = `name`.
-- Split a tuple containing `3`, `"plum"` into `code`, `label`, in that order.
-- Call `print` with `value` = call `length` on a set containing call [`Fruit`](domain/models.md#symbol-Fruit) with `code` = `code`; `name` = `label`, call [`Fruit`](domain/models.md#symbol-Fruit) with `name` = `label`; `code` = `code`.
-- Create a dependency and task scope. Join its child tasks and release scoped values before leaving:
-  - Set `counter` to the instance provided for `Counter`.
-  - Grant exclusive mutable access to `counter` for this block, then end the borrow:
-    - Call [`Counter.increment`](counters.md#symbol-Counter.increment) on `counter`.
-  - Call `print` with `value` = call [`Counter.value`](counters.md#symbol-Counter.value) on `counter`.
-- Try these operations:
-  - Call `print` with `value` = call [`double`](domain/numbers.md#symbol-double) with `amount` = `7`.
-  - Call [`double`](domain/numbers.md#symbol-double) with `amount` = `-1`.
-- If they fail with [`RangeError`](domain/numbers.md#symbol-RangeError), name the failure `error` and recover:
-  - Call `print` with `value` = `"negative amount rejected"`.
+It calls [`double`](domain/numbers.md#symbol-double) with `amount` `-1`. If this work raises [`RangeError`](domain/numbers.md#symbol-RangeError), it prints `"negative amount rejected"`.
 
-### Dependencies used by this file
+### Dependencies
 
-Only referenced types and operations appear here. Each name links to its complete specification.
+It uses [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Counter`](counters.md#symbol-Counter) ([`increment`](counters.md#symbol-Counter.increment) and [`value`](counters.md#symbol-Counter.value)) and [`Counters`](counters.md#symbol-Counters) from `counters`. It uses [`Application`](domain/app.md#symbol-Application) ([`start`](domain/app.md#symbol-Application.start)), [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl), [`Fruit`](domain/models.md#symbol-Fruit), [`RangeError`](domain/numbers.md#symbol-RangeError), and [`double`](domain/numbers.md#symbol-double) from `domain`.
 
-#### [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
-
-Class from `august.io`.
-
-Used as a type or provider.
-
-#### [`Counter`](counters.md#symbol-Counter)
-
-Interface from `counters`.
-
-- [`Counter.increment`](counters.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
-- [`Counter.value`](counters.md#symbol-Counter.value) (no caller inputs) → `int`.
-
-#### [`Counters`](counters.md#symbol-Counters)
-
-Composition from `counters`.
-
-Used as a type or provider.
-
-#### [`Application`](domain/app.md#symbol-Application)
-
-Interface from `domain`.
-
-- [`Application.start`](domain/app.md#symbol-Application.start) (no caller inputs) → `void`; uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-#### [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl)
-
-Class from `domain`.
-
-Used as a type or provider.
-
-#### [`Fruit`](domain/models.md#symbol-Fruit)
-
-Record from `domain`.
-
-- Construct with `code`: `int`, `name`: `string` → [`Fruit`](domain/models.md#symbol-Fruit).
-
-#### [`RangeError`](domain/numbers.md#symbol-RangeError)
-
-Class from `domain`.
-
-Used as a type or provider.
-
-#### [`double`](domain/numbers.md#symbol-double)
-
-Function from `domain`.
-
-- [`double`](domain/numbers.md#symbol-double) (`amount`: `int`) → `int`; can fail with `RangeError`.
-
-### Built-in operations used by this file
-
-- `Map<int, string>.get` (`key`: `int`) → `optional string`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
-- `Set<Fruit>.length` (no inputs) → `int`: Read the number of elements.
-- `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/benchmark/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Measure a deterministic arithmetic workload with aug bench.
 
-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/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 examples/benchmark
-aug spec examples/benchmark
-aug run examples/benchmark
+cd benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/benchmark/main.md

@@ -28,6 +28,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.
 // A deterministic native workload: arithmetic and 20,000 hash entries.
 own Map<int,int> values = {}
 own Set<int> unique = {}
@@ -45,6 +46,7 @@ print(value=values.length() == unique.length())
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 // A deterministic native workload: arithmetic and 20,000 hash entries.
 own Map<int,int> values = {}
 own Set<int> unique = {}
@@ -72,45 +74,15 @@ print(value=values.length() == unique.length())
 
 ## 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 `values` of type `Map<int,int>` to a context-typed empty collection with no items. `values` of type `Map<int,int>` owns this value. It sets `unique` of type `Set<int>` to a context-typed empty collection with no items. `unique` of type `Set<int>` owns this value.
 
-- Run 8 other startup steps in source order.
+It sets `index` to `0`. While `index` is less than `20000`, it stores `index` times `3` in `values` under `index`; then it adds `index` to `unique`; then it increases `index` by `1`. After the loop, it sets `checksum` to `0`. For each `key` and `value` in a snapshot of `values`, if whether `unique` contains `key` returns true, it increases `checksum` by `value`.
 
-### Startup, in source order
+After the loop, it prints `checksum`. It prints the number of elements in `values` equals the number of elements in `unique`.
 
-- Set `values` of type `Map<int,int>` to a context-typed empty collection with no items.
-- This variable owns the value.
-- Set `unique` of type `Set<int>` to a context-typed empty collection with no items.
-- This variable owns the value.
-- Set `index` of type `int` to `0`.
-- While `index` is less than `20000`, repeat:
-  - Call `set` on `values` with `key` = `index`; `value` = (`index` times `3`).
-  - Call `add` on `unique` with `value` = `index`.
-  - Set `index` to `index` plus `1`.
-  - Check the condition again before the next iteration.
-- Set `checksum` of type `int` to `0`.
-- For each `key` and `value` in a snapshot of `values`, in iteration order:
-  - If call `contains` on `unique` with `value` = `key` is true:
-    - Set `checksum` to `checksum` plus `value`.
-- Call `print` with `value` = `checksum`.
-- Call `print` with `value` = (call `length` on `values` equals call `length` on `unique`).
-
-### Built-in operations used by this file
-
-- `Map<int, int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<int, int>.set` (`key`: `int`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
-- `Set<int>.add` (`value`: `int`) → `void`: Insert a unique element with exclusive mutable access. Changes the receiver.
-- `Set<int>.contains` (`value`: `int`) → `bool`: Test structural or identity equality with a stored element.
-- `Set<int>.length` (no inputs) → `int`: Read the number of elements.
-- `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/calls-benchmark/index.md

@@ -0,0 +1,36 @@
+---
+title: "Function-call benchmark"
+generated: true
+source: "benchmarks/calls"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Function-call benchmark
+
+Call a labeled function repeatedly with a dependent integer result.
+
+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
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+
+## Try this project
+
+[Download this project](/downloads/calls-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
+cd calls-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,78 @@
+---
+title: "main.aug · Function-call benchmark"
+generated: true
+source: "benchmarks/calls/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Function-call benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import step from operations
+int iterations = 200000
+int state = 123
+int index = 0
+while index < iterations:
+    state = step(value=state)
+    index = index + 1
+print(value=state)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import step from operations
+int iterations = 200000
+int state = 123
+int index = 0
+while index < iterations {
+    state = step(value=state)
+    index = index + 1
+}
+print(value=state)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `200000`. It sets `state` to `123`. It sets `index` to `0`. While `index` is less than `iterations`, it sets `state` to [`step`](operations.md#symbol-step) with `value` from `state`; then it increases `index` by `1`.
+
+After the loop, it prints `state`.
+
+### Dependencies
+
+It uses [`step`](operations.md#symbol-step) from `operations`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/calls-benchmark/operations.md

@@ -0,0 +1,60 @@
+---
+title: "operations.aug · Function-call benchmark"
+generated: true
+source: "benchmarks/calls/operations.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `operations.aug`
+
+[Function-call benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+step(int value) returns int:
+    int product = value * 48271 + 1
+    return product - product / 2147483647 * 2147483647
+```
+
+```aug [Braces]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+step(int value) returns int {
+    int product = value * 48271 + 1
+    return product - product / 2147483647 * 2147483647
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `step` · [source](operations.md#code) {#symbol-step}
+
+It takes `value` as an integer. It sets `product` to (`value` times `48271`) plus `1`. It returns `product` minus ((`product` divided by `2147483647`) times `2147483647`).
+
+::::
+
+:::::

package/docs/examples/cli-args/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Read arguments, inspect collections, and return a process exit status.
 
-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/cli-args.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/cli-args
-aug spec examples/cli-args
-aug run examples/cli-args
+cd cli-args
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/cli-args/main.md

@@ -28,6 +28,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.
 try:
     args = arguments()
     print(value=args.length())
@@ -42,6 +43,7 @@ catch IndexError error:
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 try {
     args = arguments()
     print(value=args.length())
@@ -67,40 +69,13 @@ catch IndexError error {
 
 ## 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 `args` to `arguments`. It prints the number of elements in `args`. If the number of elements in `args` is positive, it prints the item at index `0` in `args`. It sets `numbers` to a list of `int` containing `1`, `2`.
 
-- Run startup operations with checked error recovery.
+With temporary permission to change `numbers`, it appends `3` to `numbers`. It prints the item at index `2` in `numbers`. If this work raises `IndexError`, it prints `"unexpected index failure"`.
 
-### Startup, in source order
-
-- Try these operations:
-  - Set `args` to call `arguments`.
-  - Call `print` with `value` = call `length` on `args`.
-  - If call `length` on `args` is greater than `0`:
-    - Call `print` with `value` = call `get` on `args` with `index` = `0`.
-  - Set `numbers` to a list of `int` containing `1`, `2`.
-  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
-    - Call `append` on `numbers` with `value` = `3`.
-  - Call `print` with `value` = call `get` on `numbers` with `index` = `2`.
-- If they fail with `IndexError`, name the failure `error` and recover:
-  - Call `print` with `value` = `"unexpected index failure"`.
-
-### Built-in operations used by this file
-
-- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
-- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<string>.length` (no inputs) → `int`: Read the number of elements.
-- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
-- `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/collections/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Create typed collections and update them through checked mutable access.
 
-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/collections.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/collections
-aug spec examples/collections
-aug run examples/collections
+cd collections
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/collections/main.md

@@ -28,6 +28,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.
 try:
     numbers = List<int>(2, 4)
     borrow numbers:
@@ -45,6 +46,7 @@ catch IndexError error:
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 try {
     numbers = List<int>(2, 4)
     borrow numbers {
@@ -73,45 +75,15 @@ catch IndexError error {
 
 ## 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 `numbers` to a list of `int` containing `2`, `4`. With temporary permission to change `numbers`, it appends `6` to `numbers`. It prints the number of elements in `numbers`. It prints the item at index `1` in `numbers`.
 
-- Run startup operations with checked error recovery.
+It sets `scores` to an empty map from `string` to `int`. With temporary permission to change `scores`, it stores `42` in `scores` under `"ada"`. It prints whether `scores` contains the key `"ada"`. It prints the value under `"ada"` in `scores`.
 
-### Startup, in source order
+It prints the number of elements in `scores`. If this work raises `IndexError`, it prints `"unexpected index failure"`.
 
-- Try these operations:
-  - Set `numbers` to a list of `int` containing `2`, `4`.
-  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
-    - Call `append` on `numbers` with `value` = `6`.
-  - Call `print` with `value` = call `length` on `numbers`.
-  - Call `print` with `value` = call `get` on `numbers` with `index` = `1`.
-  - Set `scores` to an empty map from `string` to `int`.
-  - Grant exclusive mutable access to `scores` for this block, then end the borrow:
-    - Call `set` on `scores` with `value` = `42`; `key` = `"ada"`.
-  - Call `print` with `value` = call `contains` on `scores` with `key` = `"ada"`.
-  - Call `print` with `value` = call `get` on `scores` with `key` = `"ada"`.
-  - Call `print` with `value` = call `length` on `scores`.
-- If they fail with `IndexError`, name the failure `error` and recover:
-  - Call `print` with `value` = `"unexpected index failure"`.
-
-### Built-in operations used by this file
-
-- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
-- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<string, int>.contains` (`key`: `string`) → `bool`: Check for a key, including entries whose value is null.
-- `Map<string, int>.get` (`key`: `string`) → `optional int`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
-- `Map<string, int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<string, int>.set` (`key`: `string`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
-- `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/collections-benchmark/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Insert, find, and iterate over 20,000 collection entries.
 
-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/collections-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/collections
-aug spec benchmarks/collections
-aug run benchmarks/collections
+cd collections-benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.