@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/collections-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.
 own Map<int,int> values = {}
 own Set<int> unique = {}
 int index = 0
@@ -44,6 +45,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.
 own Map<int,int> values = {}
 own Set<int> unique = {}
 int index = 0
@@ -70,45 +72,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/cpu-benchmark/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Two million dependent integer steps with a checked result.
 
-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/cpu-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/cpu
-aug spec benchmarks/cpu
-aug run benchmarks/cpu
+cd cpu-benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.

package/docs/examples/cpu-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 loop-carried dependency prevents removal of the computation.
 int state = 123
 int index = 0
@@ -39,6 +40,7 @@ print(value=state)
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 // A loop-carried dependency prevents removal of the computation.
 int state = 123
 int index = 0
@@ -58,32 +60,11 @@ print(value=state)
 
 ## 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 `state` to `123`. It sets `index` to `0`. While `index` is less than `2000000`, it sets `product` to `state` times `48271`; then it sets `state` to `product` minus ((`product` divided by `2147483647`) times `2147483647`); then it increases `index` by `1`. After the loop, it prints `state`.
 
-- Run 4 other startup steps in source order.
-
-### Startup, in source order
-
-- Set `state` of type `int` to `123`.
-- Set `index` of type `int` to `0`.
-- While `index` is less than `2000000`, repeat:
-  - Set `product` of type `int` to `state` times `48271`.
-  - Set `state` to `product` minus ((`product` divided by `2147483647`) times `2147483647`).
-  - Set `index` to `index` plus `1`.
-  - Check the condition again before the next iteration.
-- Call `print` with `value` = `state`.
-
-### 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/developer-workflow/calculator.md

@@ -32,6 +32,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "calculator.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Logger from logging
 /** Adds two integers. */
@@ -45,7 +46,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic:
     * @param right Second integer.
     * @return Sum of the two integers.
     */
-    add(resolve Console console, int left, int right) returns int uses Console.write:
+    add(resolve Console console, int left, int right):
         _logger.log(message="adding integers")
         return left + right
 /**
@@ -53,7 +54,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic:
 * @param fail Whether to simulate a failed load.
 * @throws FileError When fail is true.
 */
-load(bool fail) returns string unless FileError:
+load(bool fail):
     if fail:
         throw FileError()
     return "loaded"
@@ -74,10 +75,13 @@ test Calculator calculator:
             assert(values.length() == 3)
         it "starts with fresh setup":
             assert(values.length() == 2)
-            assert(calculator.add(left=values.get(index=0), right=values.get(index=1)) == 3)
+            assert(
+                calculator.add(left=values.get(index=0), right=values.get(index=1)) == 3
+            )
 ```
 
 ```aug [Braces]
+// aug-spec: "calculator.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Logger from logging
 /** Adds two integers. */
@@ -92,7 +96,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic {
     * @param right Second integer.
     * @return Sum of the two integers.
     */
-    add(resolve Console console, int left, int right) returns int uses Console.write {
+    add(resolve Console console, int left, int right) {
         _logger.log(message="adding integers")
         return left + right
     }
@@ -102,7 +106,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic {
 * @param fail Whether to simulate a failed load.
 * @throws FileError When fail is true.
 */
-load(bool fail) returns string unless FileError {
+load(bool fail) {
     if fail {
         throw FileError()
     }
@@ -129,7 +133,9 @@ test Calculator calculator {
         }
         it "starts with fresh setup" {
             assert(values.length() == 2)
-            assert(calculator.add(left=values.get(index=0), right=values.get(index=1)) == 3)
+            assert(
+                calculator.add(left=values.get(index=0), right=values.get(index=1)) == 3
+            )
         }
     }
 }
@@ -143,214 +149,61 @@ test Calculator calculator {
 
 ## 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
-
-- [`Arithmetic`](calculator.md#symbol-Arithmetic) is an interface.
-- [`Calculator`](calculator.md#symbol-Calculator) is a class implementing `Arithmetic`.
-- [`load`](calculator.md#symbol-load) is a function returning `string`.
-- [`_SilentLogger`](calculator.md#symbol-_SilentLogger) is a class implementing `Logger`.
-- [`test Calculator calculator`](calculator.md#symbol-test-20-Calculator-20-calculator) is a same-file test suite.
-
-### `Arithmetic` {#symbol-Arithmetic}
-
-[source](calculator.md#code)
-
-Interface.
-
-**Author documentation**
+### `Arithmetic` · interface · [source](calculator.md#code) {#symbol-Arithmetic}
 
 Adds two integers.
 
-#### `Arithmetic.add` {#symbol-Arithmetic.add}
-
-[source](calculator.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
-
-Returns: `int`.
-
-Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-Interface contract. A selected implementation supplies the behavior.
-
-### `Calculator` {#symbol-Calculator}
-
-[source](calculator.md#code)
-
-Behavioral class.
-
-Satisfies [`Arithmetic`](calculator.md#symbol-Arithmetic).
-
-**Author documentation**
-
-Uses the selected logger to describe each addition.
-
-**Inputs**
-
-- `logger` ([`Logger`](logging/logger.md#symbol-Logger)) — injected; callers omit it — stored as `_logger` (private) and read-only after initialization.
-
-#### `Calculator.add` {#symbol-Calculator.add}
-
-[source](calculator.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
-
-Returns: `int`.
-
-Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-**What it does**
-
-- Call [`Logger.log`](logging/logger.md#symbol-Logger.log) on `_logger` with `message` = `"adding integers"`; inject `console` from `console`.
-- Return `left` plus `right`.
-
-**Author documentation**
-
-Adds left and right, logging the operation.
-
-**Returns** Sum of the two integers.
-
-**Parameters**
-- `left`: First integer.
-- `right`: Second integer.
-
-### `load` {#symbol-load}
-
-[source](calculator.md#code)
-
-**Inputs**
-
-- `fail` (`bool`) — required labeled input.
-
-Returns: `string`.
-
-Can fail with `FileError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If `fail` is true:
-  - Fail with call `FileError`. Transfer control to a matching catch or propagate the failure.
-- Return `"loaded"`.
-
-**Author documentation**
-
-Demonstrates a checked failure instead of a successful result.
-
-**Parameters**
-- `fail`: Whether to simulate a failed load.
-
-**Throws**
-- `FileError`: When fail is true.
-
-### `_SilentLogger` {#symbol-_SilentLogger}
-
-[source](calculator.md#code)
-
-Behavioral class, private to this file.
-
-Satisfies [`Logger`](logging/logger.md#symbol-Logger).
-
-**Author documentation**
-
-Test adapter: keeps calculator tests independent of console output.
-
-#### `_SilentLogger.log` {#symbol-_SilentLogger.log}
-
-[source](calculator.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-- `message` (`string`) — required labeled input.
-
-Returns: no value.
-
-Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-**What it does**
-
-- Continue without another operation.
-
-**Author documentation**
-
-**Parameters**
-- `message`: Text to write.
-
-### `test Calculator calculator` {#symbol-test-20-Calculator-20-calculator}
-
-[source](calculator.md#code)
-
-Same-file class tests for [`Calculator`](calculator.md#symbol-Calculator). Each case gets isolated setup and dependency bindings.
+#### `Arithmetic.add` · [source](calculator.md#code) {#symbol-Arithmetic.add}
 
-#### Group `addition`
+It takes `left` and `right` as integers. It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It returns `int`. It can call [`Console.write`](dependencies/august/0.21.0/io/contracts.md#symbol-Console.write).
 
-**Setup before each case**
+### `Calculator` · class · [source](calculator.md#code) {#symbol-Calculator}
 
-- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Use a fresh instance when this provider retains state; otherwise reuse one instance.
-- Provide [`_SilentLogger`](calculator.md#symbol-_SilentLogger) when `Logger` is requested. Use a fresh instance when this provider retains state; otherwise reuse one instance.
-- Set `calculator` to call [`Calculator`](calculator.md#symbol-Calculator); inject `_logger` from `Logger`.
-- Set `values` of type `List<int>` to a list containing `1`, `2`.
+Uses the selected logger to describe each addition. It implements [`Arithmetic`](calculator.md#symbol-Arithmetic). The `_logger` dependency is injected as [`Logger`](logging/logger.md#symbol-Logger) and stored read-only and privately.
 
-##### `adds labeled inputs`
+#### `Calculator.add` · [source](calculator.md#code) {#symbol-Calculator.add}
 
-[source](calculator.md#code)
+Adds left and right, logging the operation. It takes `left` as an integer (First integer) and `right` as an integer (Second integer). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It returns `int` — Sum of the two integers.
 
-- Call `assert` with (call [`Calculator.add`](calculator.md#symbol-Calculator.add) on `calculator` with `right` = `2`; `left` = `1`; inject `console` from `Console` equals `3`).
-- Grant exclusive mutable access to `values` for this block, then end the borrow:
-  - Call `append` on `values` with `value` = `3`.
-- Call `assert` with (call `length` on `values` equals `3`).
+It passes `"adding integers"` to [`_logger.log`](logging/logger.md#symbol-Logger.log), using injected `console`. It returns `left` plus `right`.
 
-##### `starts with fresh setup`
+### `load` · [source](calculator.md#code) {#symbol-load}
 
-[source](calculator.md#code)
+Demonstrates a checked failure instead of a successful result. It takes `fail` as a boolean (Whether to simulate a failed load). Failures can raise `FileError` (when fail is true).
 
-- Call `assert` with (call `length` on `values` equals `2`).
-- Call `assert` with (call [`Calculator.add`](calculator.md#symbol-Calculator.add) on `calculator` with `left` = call `get` on `values` with `index` = `0`; `right` = call `get` on `values` with `index` = `1`; inject `console` from `Console` equals `3`).
+It checks that `fail` is false. It raises a `FileError` at the first failed check. It returns `"loaded"`.
 
-### Dependencies used by this file
+### `_SilentLogger` · class · [source](calculator.md#code) {#symbol-_SilentLogger}
 
-Only referenced types and operations appear here. Each name links to its complete specification.
+Test adapter: keeps calculator tests independent of console output. It implements [`Logger`](logging/logger.md#symbol-Logger). It is private to this file.
 
-#### [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)
+#### `_SilentLogger.log` · [source](calculator.md#code) {#symbol-_SilentLogger.log}
 
-Capability interface from `august.io`.
+It takes `message` as a string (Text to write). It gets `console` ([`Console`](dependencies/august/0.21.0/io/contracts.md#symbol-Console)) from dependency injection. It continues without an operation.
 
-- [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+### `test Calculator calculator` · [source](calculator.md#code) {#symbol-test-20-Calculator-20-calculator}
 
-#### [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
+Tests [`Calculator`](calculator.md#symbol-Calculator). Each case gets fresh setup and dependencies.
 
-Class from `august.io`.
+#### `addition`
 
-Used as a type or provider.
+Setup for each case: `Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). Stateless instances are reused; stateful instances are created for each resolve. `Logger` is provided by [`_SilentLogger`](calculator.md#symbol-_SilentLogger). Stateless instances are reused; stateful instances are created for each resolve.
 
-#### [`Logger`](logging/logger.md#symbol-Logger)
+It sets `calculator` to a [`Calculator`](calculator.md#symbol-Calculator) using injected `Logger` for `_logger`. It sets `values` of type `List<int>` to a list containing `1`, `2`.
 
-Interface from `logging`.
+##### `adds labeled inputs` · [source](calculator.md#code)
 
-- [`Logger.log`](logging/logger.md#symbol-Logger.log) (`message`: `string`) → `void`; inject `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+The test requires [`calculator.add`](calculator.md#symbol-Calculator.add) with `right` `2` and `left` `1` using injected `Console` for `console` equals `3`. With temporary permission to change `values`, it appends `3` to `values`. The test requires the number of elements in `values` equals `3`.
 
-### Built-in operations used by this file
+##### `starts with fresh setup` · [source](calculator.md#code)
 
-- `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.
-- `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.
+The test requires the number of elements in `values` equals `2`. The test requires [`calculator.add`](calculator.md#symbol-Calculator.add) with `left` from the item at index `0` in `values` and `right` from the item at index `1` in `values` using injected `Console` for `console` equals `3`.
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+### Dependencies
 
-### Shared language 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)) and [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Logger`](logging/logger.md#symbol-Logger) ([`log`](logging/logger.md#symbol-Logger.log)) from `logging`.
 
-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/developer-workflow/dependencies/august/0.21.0/io/contracts.md

@@ -0,0 +1,178 @@
+---
+title: "august/0.21.0/io/contracts.aug · A small tested application"
+generated: true
+source: "examples/developer-workflow/.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`
+
+[A small tested application](../../../../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).
+
+::::
+
+:::::