@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/approved-design/dependencies/august/0.21.0/io/contracts.md

@@ -0,0 +1,178 @@
+---
+title: "august/0.21.0/io/contracts.aug · Modules and composition"
+generated: true
+source: "examples/approved-design/.aug-spec/august/0.21.0/io/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `august/0.21.0/io/contracts.aug`
+
+[Modules and composition](../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path):
+        return read_file(path=path)
+    write(string path, string content):
+        write_file(path=path, content=content)
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read():
+        return arguments()
+```
+
+```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console {
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+}
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console {
+    write<T>(T value) {
+        print(value=value)
+    }
+}
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader {
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+}
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter {
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+}
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter {
+    read(string path) {
+        return read_file(path=path)
+    }
+    write(string path, string content) {
+        write_file(path=path, content=content)
+    }
+}
+/** Read command-line input through an explicit dependency. */
+capability Arguments {
+    read() returns List<string> uses Arguments.read
+}
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments {
+    read() {
+        return arguments()
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `Console` · capability interface · [source](contracts.md#code) {#symbol-Console}
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+#### `Console.write` · [source](contracts.md#code) {#symbol-Console.write}
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.md#symbol-Console.write).
+
+### `SystemConsole` · class · [source](contracts.md#code) {#symbol-SystemConsole}
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.md#symbol-Console).
+
+#### `SystemConsole.write` · [source](contracts.md#code) {#symbol-SystemConsole.write}
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+### `FileReader` · capability interface · [source](contracts.md#code) {#symbol-FileReader}
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+#### `FileReader.read` · [source](contracts.md#code) {#symbol-FileReader.read}
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+### `FileWriter` · capability interface · [source](contracts.md#code) {#symbol-FileWriter}
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+#### `FileWriter.write` · [source](contracts.md#code) {#symbol-FileWriter.write}
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+### `LocalFiles` · class · [source](contracts.md#code) {#symbol-LocalFiles}
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.md#symbol-FileReader) and [`FileWriter`](contracts.md#symbol-FileWriter).
+
+#### `LocalFiles.read` · [source](contracts.md#code) {#symbol-LocalFiles.read}
+
+Read text. It takes `path` as a string (File path). Failures can raise `FileError` (The file could not be read). It returns `read_file` with `path`.
+
+#### `LocalFiles.write` · [source](contracts.md#code) {#symbol-LocalFiles.write}
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). Failures can raise `FileError` (Writing failed). It calls `write_file` with `path` and `content`.
+
+### `Arguments` · capability interface · [source](contracts.md#code) {#symbol-Arguments}
+
+Read command-line input through an explicit dependency.
+
+#### `Arguments.read` · [source](contracts.md#code) {#symbol-Arguments.read}
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.md#symbol-Arguments.read).
+
+### `ProcessArguments` · class · [source](contracts.md#code) {#symbol-ProcessArguments}
+
+Native command-line arguments. It implements [`Arguments`](contracts.md#symbol-Arguments).
+
+#### `ProcessArguments.read` · [source](contracts.md#code) {#symbol-ProcessArguments.read}
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/approved-design/domain/app.md

@@ -33,6 +33,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "app.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Fruit from models
 /** The application's explicit startup operation. */
@@ -41,13 +42,14 @@ interface Application:
     start() uses Console.write
 /** Construction stores dependencies; start performs the visible external work. */
 ApplicationImpl(resolve Console console) implements Application:
-    start() uses console.write:
+    start():
         fruit to [Fruit(code=1, name="apple"), Fruit(name="pear", code=2)]
         for item in fruit:
             console.write(value=item.name)
 ```
 
 ```aug [Braces]
+// aug-spec: "app.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Fruit from models
 /** The application's explicit startup operation. */
@@ -57,7 +59,7 @@ interface Application {
 }
 /** Construction stores dependencies; start performs the visible external work. */
 ApplicationImpl(resolve Console console) implements Application {
-    start() uses console.write {
+    start() {
         fruit to [Fruit(code=1, name="apple"), Fruit(name="pear", code=2)]
         for item in fruit {
             console.write(value=item.name)
@@ -74,91 +76,25 @@ ApplicationImpl(resolve Console console) implements Application {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-### In this file
-
-- [`Application`](app.md#symbol-Application) is an interface.
-- [`ApplicationImpl`](app.md#symbol-ApplicationImpl) is a class implementing `Application`.
-
-### `Application` {#symbol-Application}
-
-[source](app.md#code)
-
-Interface.
-
-**Author documentation**
+### `Application` · interface · [source](app.md#code) {#symbol-Application}
 
 The application's explicit startup operation.
 
-#### `Application.start` {#symbol-Application.start}
-
-[source](app.md#code)
-
-Returns: no value.
-
-Capabilities: [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-Interface contract. A selected implementation supplies the behavior.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
-
-### `ApplicationImpl` {#symbol-ApplicationImpl}
-
-[source](app.md#code)
-
-Behavioral class.
-
-Satisfies [`Application`](app.md#symbol-Application).
-
-**Author documentation**
-
-Construction stores dependencies; start performs the visible external work.
-
-**Inputs**
-
-- `console` ([`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it — stored as `console` and read-only after initialization.
-
-#### `ApplicationImpl.start` {#symbol-ApplicationImpl.start}
-
-[source](app.md#code)
-
-Returns: no value.
-
-Capabilities: [`console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-**What it does**
-
-- Set `fruit` to a list containing call [`Fruit`](models.md#symbol-Fruit) with `code` = `1`; `name` = `"apple"`, call [`Fruit`](models.md#symbol-Fruit) with `name` = `"pear"`; `code` = `2`.
-- For each `item` in a snapshot of `fruit`, in iteration order:
-  - Call [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write) on `console` with `value` = `name` of `item`.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+#### `Application.start` · [source](app.md#code) {#symbol-Application.start}
 
-Capability interface from `august.io`.
+Writes the fruit names through the selected console. It can call [`Console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
-- [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+### `ApplicationImpl` · class · [source](app.md#code) {#symbol-ApplicationImpl}
 
-#### [`Fruit`](models.md#symbol-Fruit)
+Construction stores dependencies; start performs the visible external work. It implements [`Application`](app.md#symbol-Application). The `console` dependency is injected as [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) and stored read-only.
 
-Record from `models`.
+#### `ApplicationImpl.start` · [source](app.md#code) {#symbol-ApplicationImpl.start}
 
-- Construct with `code`: `int`, `name`: `string` → [`Fruit`](models.md#symbol-Fruit).
-- Read `name` (`string`).
+Writes the fruit names through the selected console. It sets `fruit` to a list containing a [`Fruit`](models.md#symbol-Fruit) with `code` `1` and `name` `"apple"`, a [`Fruit`](models.md#symbol-Fruit) with `name` `"pear"` and `code` `2`. For each `item` in a snapshot of `fruit`, it passes `item.name` to [`console.write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
-### Shared language rules
+### Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.21.0/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Fruit`](models.md#symbol-Fruit) (`name`) from `models`.
 
 ::::
 

package/docs/examples/approved-design/domain/export.md

@@ -33,6 +33,7 @@ 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 Application from app
 export ApplicationImpl from app
 export Fruit from models
@@ -41,6 +42,7 @@ export RangeError from numbers
 ```
 
 ```aug [Braces]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export Application from app
 export ApplicationImpl from app
 export Fruit from models
@@ -56,27 +58,11 @@ export RangeError from numbers
 
 ## 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 the declaration `Application` from [`app.aug`](app.md#symbol-Application). Export the declaration `ApplicationImpl` from [`app.aug`](app.md#symbol-ApplicationImpl). Export the declaration `Fruit` from [`models.aug`](models.md#symbol-Fruit). Export the declaration `double` from [`numbers.aug`](numbers.md#symbol-double).
 
-- Export `Application` from this folder.
-- Export `ApplicationImpl` from this folder.
-- Export `Fruit` from this folder.
-- Export `double` from this folder.
-- Export `RangeError` from this folder.
-
-### Folder exports
-
-- Export the declaration `Application` from [`app.aug`](app.md#symbol-Application).
-- Export the declaration `ApplicationImpl` from [`app.aug`](app.md#symbol-ApplicationImpl).
-- Export the declaration `Fruit` from [`models.aug`](models.md#symbol-Fruit).
-- Export the declaration `double` from [`numbers.aug`](numbers.md#symbol-double).
-- Export the declaration `RangeError` from [`numbers.aug`](numbers.md#symbol-RangeError).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `RangeError` from [`numbers.aug`](numbers.md#symbol-RangeError).
 
 ::::
 

package/docs/examples/approved-design/domain/models.md

@@ -33,11 +33,13 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "models.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Immutable fruit data, with public construction labels and structural equality. */
 record Fruit(int code, string name)
 ```
 
 ```aug [Braces]
+// aug-spec: "models.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Immutable fruit data, with public construction labels and structural equality. */
 record Fruit(int code, string name)
 ```
@@ -50,30 +52,9 @@ record Fruit(int code, string name)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Fruit` · immutable record · [source](models.md#code) {#symbol-Fruit}
 
-### In this file
-
-- [`Fruit`](models.md#symbol-Fruit) is an immutable record.
-
-### `Fruit` {#symbol-Fruit}
-
-[source](models.md#code)
-
-Immutable record.
-
-**Author documentation**
-
-Immutable fruit data, with public construction labels and structural equality.
-
-**Inputs**
-
-- `code` (`int`) — required labeled input — stored as `code` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Immutable fruit data, with public construction labels and structural equality. It takes `code` as an integer, kept read-only and `name` as a string, kept read-only.
 
 ::::
 

package/docs/examples/approved-design/domain/numbers.md

@@ -33,12 +33,13 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "numbers.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Raised when an input is outside the operation's domain. */
 RangeError(int value) implements Error:
     pass
 /** A pure validation layer, shared by any compatible callable. */
 interceptor Positive<T>():
-    around(int amount) returns T unless RangeError:
+    around(int amount) returns T:
         if amount < 0:
             throw RangeError(value=amount)
         return next()
@@ -49,7 +50,7 @@ interceptor Positive<T>():
 * @throws RangeError A validation layer rejected a negative input.
 */
 [Positive]
-double(int amount) returns int:
+double(int amount):
     return amount * 2
 test double:
     when "positive":
@@ -65,13 +66,14 @@ test double:
 ```
 
 ```aug [Braces]
+// aug-spec: "numbers.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Raised when an input is outside the operation's domain. */
 RangeError(int value) implements Error {
     pass
 }
 /** A pure validation layer, shared by any compatible callable. */
 interceptor Positive<T>() {
-    around(int amount) returns T unless RangeError {
+    around(int amount) returns T {
         if amount < 0 {
             throw RangeError(value=amount)
         }
@@ -85,7 +87,7 @@ interceptor Positive<T>() {
 * @throws RangeError A validation layer rejected a negative input.
 */
 [Positive]
-double(int amount) returns int {
+double(int amount) {
     return amount * 2
 }
 test double {
@@ -115,133 +117,41 @@ test double {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `RangeError` · class · [source](numbers.md#code) {#symbol-RangeError}
 
-### In this file
+Raised when an input is outside the operation's domain. It implements `Error`. It takes `value` as an integer, kept read-only.
 
-- [`RangeError`](numbers.md#symbol-RangeError) is a class implementing `Error`.
-- [`Positive`](numbers.md#symbol-Positive) is an interceptor.
-- [`double`](numbers.md#symbol-double) is a function returning `int`.
-- [`test double`](numbers.md#symbol-test-20-double) is a same-file test suite.
+### `Positive` · interceptor · [source](numbers.md#code) {#symbol-Positive}
 
-### `RangeError` {#symbol-RangeError}
+A pure validation layer, shared by any compatible callable. The type parameters are `T`. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
-[source](numbers.md#code)
+#### `Positive.around` · [source](numbers.md#code) {#symbol-Positive.around}
 
-Behavioral class.
+It takes `amount` as an integer. Failures can raise [`RangeError`](numbers.md#symbol-RangeError). If `amount` is negative, it raises a [`RangeError`](numbers.md#symbol-RangeError) with `value` from `amount`. It returns `next`.
 
-Satisfies `Error`.
+### `double` · [source](numbers.md#code) {#symbol-double}
 
-**Author documentation**
+Double a nonnegative amount. It takes `amount` as an integer (Integer to double). It returns `int` — Twice the amount, with defined integer wrapping. Failures can raise [`RangeError`](numbers.md#symbol-RangeError) (A validation layer rejected a negative input).
 
-Raised when an input is outside the operation's domain.
+Layers run in the declared order. Call [`Positive.around`](numbers.md#symbol-Positive.around). It returns `amount` times `2`.
 
-**Inputs**
+### `test double` · [source](numbers.md#code) {#symbol-test-20-double}
 
-- `value` (`int`) — required labeled input — stored as `value` and read-only after initialization.
+Tests [`double`](numbers.md#symbol-double). Each case gets fresh setup and dependencies.
 
-### `Positive` {#symbol-Positive}
+#### `positive`
 
-[source](numbers.md#code)
+##### `doubles` · [source](numbers.md#code)
 
-Function or constructor middleware.
+Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`. The test requires [`double`](numbers.md#symbol-double) with `amount` from `input` equals `expected`.
 
-Type parameters: `T`.
+##### `rejects_negative` · [source](numbers.md#code)
 
-**Author documentation**
+It sets `rejected` to `false`.
 
-A pure validation layer, shared by any compatible callable.
+It tries to call [`double`](numbers.md#symbol-double) with `amount` `-1`. If this work raises [`RangeError`](numbers.md#symbol-RangeError) as `error`, it sets `rejected` to `error.value` equals `-1`. The test requires `rejected` is true.
 
-Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
-
-#### `Positive.around` {#symbol-Positive.around}
-
-[source](numbers.md#code)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `T`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If `amount` is less than `0`:
-  - Fail with call [`RangeError`](numbers.md#symbol-RangeError) with `value` = `amount`. Transfer control to a matching catch or propagate the failure.
-- Return call `next`.
-
-### `double` {#symbol-double}
-
-[source](numbers.md#code)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `int`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**Interceptors, in execution order**
-
-1. Call [`Positive.around`](numbers.md#symbol-Positive.around). It can call the next layer or finish with its own result or failure. Unselected inputs pass through.
-
-The first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.
-
-**What it does**
-
-- Return `amount` times `2`.
-
-**Author documentation**
-
-Double a nonnegative amount.
-
-**Returns** Twice the amount, with defined integer wrapping.
-
-**Parameters**
-- `amount`: Integer to double.
-
-**Throws**
-- `RangeError`: A validation layer rejected a negative input.
-
-### `test double` {#symbol-test-20-double}
-
-[source](numbers.md#code)
-
-Same-file function tests for [`double`](numbers.md#symbol-double). Each case gets isolated setup and dependency bindings.
-
-#### Group `positive`
-
-##### `doubles`
-
-[source](numbers.md#code)
-
-Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`.
-
-- Call `assert` with (call [`double`](numbers.md#symbol-double) with `amount` = `input` equals `expected`).
-
-##### `rejects_negative`
-
-[source](numbers.md#code)
-
-- Set `rejected` of type `bool` to `false`.
-- Try these operations:
-  - Call [`double`](numbers.md#symbol-double) with `amount` = `-1`.
-- If they fail with [`RangeError`](numbers.md#symbol-RangeError), name the failure `error` and recover:
-  - Set `rejected` to `value` of `error` equals `-1`.
-- Call `assert` with `rejected` = `rejected`.
-
-### 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/approved-design/index.md

@@ -10,9 +10,17 @@ outline: [2, 3]
 
 # Modules and composition
 
-Combine domain modules, generic values, explicit capabilities, and scoped providers.
+Startup combines narrow domain exports with a scoped counter provider. Records and validation keep data and checked failures visible.
 
-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.
+
+## Follow the program
+
+Read [`main.aug`](main.md). Follow the domain imports, provider choices, explicit scope, and checked failure before opening the implementation files.
+
+Read [`domain/export.aug`](domain/export.md). The export file gives callers the folder's deliberate public API.
+
+Read [`domain/numbers.aug`](domain/numbers.md). The validation interceptor rejects a negative input. Tests cover successful doubling and recovery from that failure.
 
 ## Project files
 
@@ -27,13 +35,14 @@ 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/approved-design.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/approved-design
-aug spec examples/approved-design
-aug test examples/approved-design
-aug run examples/approved-design
+cd approved-design
+aug check .
+aug spec .
+aug test .
+aug run .
 ```
 
 [Browse all examples](../index.md)