@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/examples/generic-di/types.md

@@ -29,31 +29,33 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "types.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 interface Repository<T>:
     get() returns T
 NumberRepository() implements Repository<int>:
-    get() returns int:
+    get():
         return 7
 Program(resolve Repository<int> repository) implements IProgram:
-    start(resolve Console console) uses Console.write:
+    start(resolve Console console):
         console.write(value=repository.get())
 interface IProgram:
     start(resolve Console console) uses Console.write
 ```
 
 ```aug [Braces]
+// aug-spec: "types.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 interface Repository<T> {
     get() returns T
 }
 NumberRepository() implements Repository<int> {
-    get() returns int {
+    get() {
         return 7
     }
 }
 Program(resolve Repository<int> repository) implements IProgram {
-    start(resolve Console console) uses Console.write {
+    start(resolve Console console) {
         console.write(value=repository.get())
     }
 }
@@ -70,110 +72,39 @@ interface IProgram {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Repository` · interface · [source](types.md#code) {#symbol-Repository}
 
-### In this file
+The type parameters are `T`.
 
-- [`Repository`](types.md#symbol-Repository) is an interface.
-- [`NumberRepository`](types.md#symbol-NumberRepository) is a class implementing `Repository<int>`.
-- [`Program`](types.md#symbol-Program) is a class implementing `IProgram`.
-- [`IProgram`](types.md#symbol-IProgram) is an interface.
+#### `Repository.get` · [source](types.md#code) {#symbol-Repository.get}
 
-### `Repository` {#symbol-Repository}
+It returns `T`.
 
-[source](types.md#code)
+### `NumberRepository` · class · [source](types.md#code) {#symbol-NumberRepository}
 
-Interface.
+It implements [`Repository<int>`](types.md#symbol-Repository).
 
-Type parameters: `T`.
+#### `NumberRepository.get` · [source](types.md#code) {#symbol-NumberRepository.get}
 
-#### `Repository.get` {#symbol-Repository.get}
+It returns `7`.
 
-[source](types.md#code)
+### `Program` · class · [source](types.md#code) {#symbol-Program}
 
-Returns: `T`.
+It implements [`IProgram`](types.md#symbol-IProgram). The `repository` dependency is injected as [`Repository<int>`](types.md#symbol-Repository) and stored read-only.
 
-Interface contract. A selected implementation supplies the behavior.
+#### `Program.start` · [source](types.md#code) {#symbol-Program.start}
 
-### `NumberRepository` {#symbol-NumberRepository}
+It gets `console` ([`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It passes [`repository.get`](types.md#symbol-Repository.get) to [`console.write`](dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
 
-[source](types.md#code)
+### `IProgram` · interface · [source](types.md#code) {#symbol-IProgram}
 
-Behavioral class.
+#### `IProgram.start` · [source](types.md#code) {#symbol-IProgram.start}
 
-Satisfies [`Repository`](types.md#symbol-Repository).
+It gets `console` ([`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It can call [`Console.write`](dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
 
-#### `NumberRepository.get` {#symbol-NumberRepository.get}
+### Dependencies
 
-[source](types.md#code)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `7`.
-
-### `Program` {#symbol-Program}
-
-[source](types.md#code)
-
-Behavioral class.
-
-Satisfies [`IProgram`](types.md#symbol-IProgram).
-
-**Inputs**
-
-- `repository` ([`Repository<int>`](types.md#symbol-Repository)) — injected; callers omit it — stored as `repository` and read-only after initialization.
-
-#### `Program.start` {#symbol-Program.start}
-
-[source](types.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-
-Returns: no value.
-
-Capabilities: [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-**What it does**
-
-- Call [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write) on `console` with `value` = call [`Repository.get`](types.md#symbol-Repository.get) on `repository`.
-
-### `IProgram` {#symbol-IProgram}
-
-[source](types.md#code)
-
-Interface.
-
-#### `IProgram.start` {#symbol-IProgram.start}
-
-[source](types.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-
-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.
-
-### 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)
-
-Capability interface from `august.io`.
-
-- [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) from `august.io`.
 
 ::::
 

package/docs/examples/generics/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Write reusable records, interfaces, classes, and functions with type parameters.
 
-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/generics.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/generics
-aug spec examples/generics
-aug run examples/generics
+cd generics
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/generics/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 Formatter from types
 import TextFormatter from types
 import Box from types
@@ -41,6 +42,7 @@ print(value=box.get())
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Formatter from types
 import TextFormatter from types
 import Box from types
@@ -60,60 +62,21 @@ print(value=box.get())
 
 ## 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
+`Formatter` is provided by [`TextFormatter`](types.md#symbol-TextFormatter). The same instance is shared.
 
-- Register 1 dependency provider before startup.
-- Run 5 other startup steps in source order.
+### Startup
 
-### Dependency providers
+It sets `formatter` to the instance provided for `Formatter`. It prints [`formatter.title`](types.md#symbol-Formatter.title). It prints [`formatter.format`](types.md#symbol-Formatter.format) for `int` with `value` `42`. It sets `box` to a [`Box`](types.md#symbol-Box) for `string` with `value` `"inside a generic box"`.
 
-Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+It prints [`box.get`](types.md#symbol-Box.get).
 
-- Provide [`TextFormatter`](types.md#symbol-TextFormatter) when `Formatter` is requested. Reuse one instance.
+### Dependencies
 
-### Startup, in source order
+It uses [`Box`](types.md#symbol-Box) ([`get`](types.md#symbol-Box.get)), [`Formatter`](types.md#symbol-Formatter) ([`format`](types.md#symbol-Formatter.format) and [`title`](types.md#symbol-Formatter.title)), and [`TextFormatter`](types.md#symbol-TextFormatter) from `types`.
 
-- Set `formatter` to the instance provided for `Formatter`.
-- Call `print` with `value` = call [`Formatter.title`](types.md#symbol-Formatter.title) on `formatter`.
-- Call `print` with `value` = call [`Formatter.format`](types.md#symbol-Formatter.format) on `formatter` with type arguments `int` with `value` = `42`.
-- Set `box` to call [`Box`](types.md#symbol-Box) with type arguments `string` with `value` = `"inside a generic box"`.
-- Call `print` with `value` = call [`Box.get`](types.md#symbol-Box.get) on `box`.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Box`](types.md#symbol-Box)
-
-Class from `types`.
-
-- Construct with `value`: `T` → [`Box`](types.md#symbol-Box).
-- [`Box.get`](types.md#symbol-Box.get) (no caller inputs) → `T`.
-
-#### [`Formatter`](types.md#symbol-Formatter)
-
-Interface from `types`.
-
-- [`Formatter.format`](types.md#symbol-Formatter.format)<`T`> (`value`: `T`) → `string`.
-- [`Formatter.title`](types.md#symbol-Formatter.title) (no caller inputs) → `string`.
-
-#### [`TextFormatter`](types.md#symbol-TextFormatter)
-
-Class from `types`.
-
-Used as a type or provider.
-
-### 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/generics/types.md

@@ -29,34 +29,36 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "types.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface Formatter:
     format<T>(T value) returns string
-    title() returns string:
+    title():
         return "formatted"
 TextFormatter() implements Formatter:
-    format<T>(T value) returns string:
+    format<T>(T value):
         return "generic method called"
 Box<T>(T value) implements IBox<T>:
-    get() returns T:
+    get():
         return value
 interface IBox<T>:
     get() returns T
 ```
 
 ```aug [Braces]
+// aug-spec: "types.aug.md" explains this file. Read it before changes; refresh with aug spec.
 interface Formatter {
     format<T>(T value) returns string
-    title() returns string {
+    title() {
         return "formatted"
     }
 }
 TextFormatter() implements Formatter {
-    format<T>(T value) returns string {
+    format<T>(T value) {
         return "generic method called"
     }
 }
 Box<T>(T value) implements IBox<T> {
-    get() returns T {
+    get() {
         return value
     }
 }
@@ -73,116 +75,39 @@ interface IBox<T> {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Formatter` · interface · [source](types.md#code) {#symbol-Formatter}
 
-### In this file
+#### `Formatter.format` · [source](types.md#code) {#symbol-Formatter.format}
 
-- [`Formatter`](types.md#symbol-Formatter) is an interface.
-- [`TextFormatter`](types.md#symbol-TextFormatter) is a class implementing `Formatter`.
-- [`Box`](types.md#symbol-Box) is a class implementing `IBox<T>`.
-- [`IBox`](types.md#symbol-IBox) is an interface.
+The type parameters are `T`. It takes `value` as `T`. It returns `string`.
 
-### `Formatter` {#symbol-Formatter}
+#### `Formatter.title` · [source](types.md#code) {#symbol-Formatter.title}
 
-[source](types.md#code)
+It returns `"formatted"`.
 
-Interface.
+### `TextFormatter` · class · [source](types.md#code) {#symbol-TextFormatter}
 
-#### `Formatter.format` {#symbol-Formatter.format}
+It implements [`Formatter`](types.md#symbol-Formatter). It inherits the default implementations of [`Formatter.title`](types.md#symbol-Formatter.title).
 
-[source](types.md#code)
+#### `TextFormatter.format` · [source](types.md#code) {#symbol-TextFormatter.format}
 
-Type parameters: `T`.
+The type parameters are `T`. It takes `value` as `T`. It returns `"generic method called"`.
 
-**Inputs**
+### `Box` · class · [source](types.md#code) {#symbol-Box}
 
-- `value` (`T`) — required labeled input.
+It implements [`IBox<T>`](types.md#symbol-IBox). The type parameters are `T`. It takes `value` as `T`, kept read-only.
 
-Returns: `string`.
+#### `Box.get` · [source](types.md#code) {#symbol-Box.get}
 
-Interface contract. A selected implementation supplies the behavior.
+It returns `value`.
 
-#### `Formatter.title` {#symbol-Formatter.title}
+### `IBox` · interface · [source](types.md#code) {#symbol-IBox}
 
-[source](types.md#code)
+The type parameters are `T`.
 
-Returns: `string`.
+#### `IBox.get` · [source](types.md#code) {#symbol-IBox.get}
 
-**What it does**
-
-- Return `"formatted"`.
-
-### `TextFormatter` {#symbol-TextFormatter}
-
-[source](types.md#code)
-
-Behavioral class.
-
-Satisfies [`Formatter`](types.md#symbol-Formatter).
-
-**Inherited default behavior**
-
-- [`Formatter.title`](types.md#symbol-Formatter.title).
-
-#### `TextFormatter.format` {#symbol-TextFormatter.format}
-
-[source](types.md#code)
-
-Type parameters: `T`.
-
-**Inputs**
-
-- `value` (`T`) — required labeled input.
-
-Returns: `string`.
-
-**What it does**
-
-- Return `"generic method called"`.
-
-### `Box` {#symbol-Box}
-
-[source](types.md#code)
-
-Behavioral class.
-
-Type parameters: `T`.
-
-Satisfies [`IBox`](types.md#symbol-IBox).
-
-**Inputs**
-
-- `value` (`T`) — required labeled input — stored as `value` and read-only after initialization.
-
-#### `Box.get` {#symbol-Box.get}
-
-[source](types.md#code)
-
-Returns: `T`.
-
-**What it does**
-
-- Return `value`.
-
-### `IBox` {#symbol-IBox}
-
-[source](types.md#code)
-
-Interface.
-
-Type parameters: `T`.
-
-#### `IBox.get` {#symbol-IBox.get}
-
-[source](types.md#code)
-
-Returns: `T`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns `T`.
 
 ::::
 

package/docs/examples/hello/app/export.md

@@ -33,10 +33,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 Greeter from greeter
 ```
 
 ```aug [Braces]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export Greeter from greeter
 ```
 
@@ -48,19 +50,9 @@ export Greeter from greeter
 
 ## 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 `Greeter` from this folder.
-
-### Folder exports
-
-- Export the declaration `Greeter` from [`greeter.aug`](greeter.md#symbol-Greeter).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `Greeter` from [`greeter.aug`](greeter.md#symbol-Greeter).
 
 ::::
 

package/docs/examples/hello/app/greeter.md

@@ -33,6 +33,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "greeter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Logger from logging
 /**
@@ -44,7 +45,7 @@ Greeter(resolve Logger logger) implements IGreeter:
     * Prints a personalized greeting.
     * @param name The user to welcome.
     */
-    greet(resolve Console console, string name) uses Console.write:
+    greet(resolve Console console, string name):
         logger.log(message="Hello, " + name + "!")
 interface IGreeter:
     /**
@@ -55,6 +56,7 @@ interface IGreeter:
 ```
 
 ```aug [Braces]
+// aug-spec: "greeter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Logger from logging
 /**
@@ -66,7 +68,7 @@ Greeter(resolve Logger logger) implements IGreeter {
     * Prints a personalized greeting.
     * @param name The user to welcome.
     */
-    greet(resolve Console console, string name) uses Console.write {
+    greet(resolve Console console, string name) {
         logger.log(message="Hello, " + name + "!")
     }
 }
@@ -87,103 +89,23 @@ interface IGreeter {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Greeter` · class · [source](greeter.md#code) {#symbol-Greeter}
 
-### In this file
+Welcomes a user through the configured logger. It implements [`IGreeter`](greeter.md#symbol-IGreeter). The `logger` dependency is injected as [`Logger`](../logging/logger.md#symbol-Logger) and stored read-only (The application logger, injected when resolved).
 
-- [`Greeter`](greeter.md#symbol-Greeter) is a class implementing `IGreeter`.
-- [`IGreeter`](greeter.md#symbol-IGreeter) is an interface.
+#### `Greeter.greet` · [source](greeter.md#code) {#symbol-Greeter.greet}
 
-### `Greeter` {#symbol-Greeter}
+Prints a personalized greeting. It takes `name` as a string (the user to welcome). It gets `console` ([`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It passes the text `Hello, {name}!` to [`logger.log`](../logging/logger.md#symbol-Logger.log), using injected `console`.
 
-[source](greeter.md#code)
+### `IGreeter` · interface · [source](greeter.md#code) {#symbol-IGreeter}
 
-Behavioral class.
+#### `IGreeter.greet` · [source](greeter.md#code) {#symbol-IGreeter.greet}
 
-Satisfies [`IGreeter`](greeter.md#symbol-IGreeter).
+Prints a personalized greeting. It takes `name` as a string (the user to welcome). It gets `console` ([`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console)) from dependency injection. It can call [`Console.write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write).
 
-**Author documentation**
+### Dependencies
 
-Welcomes a user through the configured logger.
-
-**Parameters**
-- `logger`: The application logger, injected when resolved.
-
-**Inputs**
-
-- `logger` ([`Logger`](../logging/logger.md#symbol-Logger)) — injected; callers omit it — stored as `logger` and read-only after initialization.
-
-#### `Greeter.greet` {#symbol-Greeter.greet}
-
-[source](greeter.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-- `name` (`string`) — required labeled input.
-
-Returns: no value.
-
-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` = (text formed by joining `"Hello, "`, `name`, `"!"` in order); inject `console` from `console`.
-
-**Author documentation**
-
-Prints a personalized greeting.
-
-**Parameters**
-- `name`: The user to welcome.
-
-### `IGreeter` {#symbol-IGreeter}
-
-[source](greeter.md#code)
-
-Interface.
-
-#### `IGreeter.greet` {#symbol-IGreeter.greet}
-
-[source](greeter.md#code)
-
-**Inputs**
-
-- `console` ([`Console`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console)) — injected; callers omit it.
-- `name` (`string`) — required labeled input.
-
-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**
-
-Prints a personalized greeting.
-
-**Parameters**
-- `name`: The user to welcome.
-
-### 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)
-
-Capability interface from `august.io`.
-
-- [`Console.write`](../dependencies/august/0.19.0/io/contracts.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
-
-#### [`Logger`](../logging/logger.md#symbol-Logger)
-
-Interface from `logging`.
-
-- [`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).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console) ([`write`](../dependencies/august/0.20.1/io/contracts.md#symbol-Console.write)) from `august.io`. It uses [`Logger`](../logging/logger.md#symbol-Logger) ([`log`](../logging/logger.md#symbol-Logger.log)) from `logging`.
 
 ::::