@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/tooling.md

@@ -1,14 +1,16 @@
 # Native builds and developer tooling
 
+Use this page to look up CLI commands, project configuration, native requirements, and editor behavior. If you need a running first project, follow [the book](learn/index.md). To use context reports during a change, follow [the module review guide](guides/change-a-module.md).
+
 ## CLI
 
-Use `aug` if installed or `node bin/aug.mjs` from the repository. Commands take a project folder, defaulting to the current directory. Editor commands also accept --file and --offset; use --help for the command inventory.
+Install `aug` once as shown in [Your first project](getting-started.md). Commands take a project folder, defaulting to the current directory. Editor commands also accept --file and --offset; use --help for the command inventory.
 
 | Command | Output |
 | --- | --- |
 | `check PROJECT [--json]` | Production, tests, module policy, documentation, and configuration diagnostics. |
 | `build PROJECT [--out NAME] [--json]` | Native path; JSON contains output and sourceMap. |
-| `run PROJECT -- args...` | Builds and runs; program stdout is preserved. |
+| `run [PROJECT] [--offline] -- args...` | Prepares declared packages and required native libraries, checks, compiles, and runs; program stdout is preserved. |
 | `emit-c PROJECT` | Generated C for inspection. |
 | `format PROJECT [--file PATH] [--write] [--json]` | Canonical source; --write updates files. |
 | `migrate PROJECT [--file PATH] [--write] [--json]` | Verified migration of rejected legacy syntax; preview by default. |
@@ -18,21 +20,26 @@ Use `aug` if installed or `node bin/aug.mjs` from the repository. Commands take
 | `explain PROJECT --file PATH [--name NAME]` | Checked contracts, dependencies, layers, origins, tests, and module surface. |
 | `context PROJECT --file PATH [--name NAME] [--budget N]` | Bounded JSON context, including related declarations and source snippets. |
 | `lsp PROJECT` | Persistent language server over stdio. |
-| `package init DIRECTORY --name @owner/name` | Standalone source library with public exports, Javadoc and a same-file test. |
+| `package init DIRECTORY [--name @owner/name]` | Standalone source library with public exports, Javadoc and a same-file test. |
 | `package pack DIRECTORY` | Checked source archive ready for npm publishing or local installation. |
-| `install PROJECT [--frozen] [--offline]` | Explicit dependency snapshot and aug.lock.json. |
+| `add URL --as NAME [--project DIRECTORY]` | Installs a repository or archive under a short import alias. |
+| `install PROJECT [--frozen|--update] [--offline]` | Explicit dependency snapshot and aug.lock.json. |
 
-Warnings are nonblocking. Machine diagnostics carry severity, code, file, line, column, and message. check/build fail on errors; invalid command usage returns nonzero. Test failure returns nonzero and includes the case output.
+Warnings are nonblocking. Human diagnostics show the source line, a pointer, and help. Machine diagnostics carry severity, code, file, line, column, message, and help. check/build fail on errors; invalid options and missing option values return status 2. Test failure returns nonzero and includes the case output. Put runtime arguments after `--`, for example `aug run -- --port 8080`.
 
 ## Native standard libraries
 
-Web, crypto, JSON and tasks use pinned private C dependencies. On macOS or Linux, bootstrap them once from the compiler directory:
+`aug run` handles dependency preparation. `build`, `test`, and `bench` also prepare the native libraries their checked programs need; they require source packages to be installed already. Pure programs need only a C11 compiler. JSON needs yyjson, tasks need minicoro, crypto needs the pinned cryptographic libraries, and HTTP needs the full transport stack. Unused libraries are not downloaded.
+
+The first native preparation can take several minutes for web/crypto; progress names the current download or build. Later runs reuse the cache. Downloaded archives must match their pinned SHA-256 hashes. Interrupted preparation can resume, and simultaneous projects sharing a cache wait for its writer. Native setup never installs system packages. Missing compilers or build tools produce a recovery command. On Linux, HTTP builds also need CMake and zlib development headers. macOS works with Xcode or its Command Line Tools.
+
+For an offline run, prepare the project once with network access, then use:
 
 ```sh
-node scripts/bootstrap-native.mjs
+aug run --offline
 ```
 
-The script verifies archive SHA-256 hashes and builds under `.aug-native`; it does not install system packages. `--extract-only` supplies yyjson and minicoro for JSON/task-only programs. Web and crypto require the complete native build. Sources, dependency revisions and hashes are recorded in scripts/native-dependencies.lock.json; the installed manifest also records host platform and architecture. The full build has run on macOS ARM and Linux ARM; Linux x86-64 is checked by the Docker CI job.
+`--offline` prevents dependency downloads; it does not restrict application networking. Native commands accept it too. You can prewarm libraries without running an application using `aug-native --extract-only --only yyjson,minicoro`, `aug-native --profile crypto`, or `aug-native` for all libraries. The installed manifest records the host platform and architecture; a cache from another host produces an actionable error. The full build has run on macOS ARM and Linux ARM; Linux x86-64 is checked by the Docker CI job.
 
 Set `AUG_NATIVE_HOME` to share a dependency directory across compiler copies. It names the directory containing `sources/` and `prefix/`, not the prefix itself. Bootstrap and compilation both honor it. For the bundled VS Code compiler, set `augscript.nativeHome` to that same absolute directory. The extension bundles the bootstrap scripts and lockfile; it does not bundle host-specific native libraries. Node 24+ and a C11 compiler remain requirements.
 
@@ -110,7 +117,7 @@ announce(message="Hello from C")
 ```aug project=ffi-guide file=native.aug
 extern C puts(string value) returns c_int
 
-announce(string message) uses C.puts:
+announce(string message):
     unsafe:
         result = puts(value=message)
 ```
@@ -124,7 +131,7 @@ announce(string message) uses C.puts:
 | string | const char* (UTF-8, no NUL) |
 | void | void |
 
-C calls require unsafe, and callables declare uses C.function. Ordinary scalar extern declarations have no generics, resolve parameters, ownership transfer, nullable boundary types, or checked error clause. For libc functions taking C int, explicitly narrow with c_int; do not declare their boundary as int64_t.
+C calls require unsafe, and executable callers infer uses C.function. Ordinary scalar extern declarations have no generics, resolve parameters, ownership transfer, nullable boundary types, or checked error clause. For libc functions taking C int, explicitly narrow with c_int; do not declare their boundary as int64_t.
 
 Standard adapters use `extern C value` for the managed AugValue ABI. Each C argument and result must actually be AugValue; headers expose the declared capability effect and checked failures. `pure` asserts a trusted native implementation has no observable effects. These declarations are unsafe contracts, not automatic C bindings. Crypto, HTTP, JSON and time adapters demonstrate this narrow boundary in src/stdlib and runtime.
 
@@ -144,7 +151,7 @@ run
 bt
 ```
 
-Debug information resolves source breakpoints. Variables currently display the C runtime's tagged representation; rich AugScript variable views, expression evaluation, and ownership-aware debugging are future work. This machine has LLDB but no lldb-dap, so the DAP launch path requires installing/configuring that adapter. The source-breakpoint smoke test resolved two locations; native launch then stalled on this host and was stopped, so interactive stepping and call-stack behavior remain unverified here.
+Debug information resolves source breakpoints. Variables currently display the C runtime's tagged representation; rich AugScript variable views, expression evaluation, and ownership-aware debugging are future work. Configure an LLDB DAP adapter to use the debug launch path. Native variables still use the runtime’s tagged representation; richer August views remain on the roadmap.
 
 AUG_TRACE_DROPS=1 enables runtime cleanup tracing to stderr for lifecycle verification; it is developer instrumentation, not a language I/O capability.
 
@@ -194,4 +201,10 @@ The language server implements the [LSP 3.17 protocol](https://github.com/Micros
 
 One server runs per project. Parsed modules and checked import closures are cached by source/configuration revision. Unrelated edits reuse the previous immutable semantic document; dependency edits invalidate its closure. Local files can be checked while main composition is incomplete. Whole-project check/build still validates all bindings and startup.
 
-Compiler and extension development dependencies use exact versions and lockfiles. Native maps record the selected C toolchain and inputs; C compiler/OS versions are environment requirements, not vendored binaries. User-authored source packages use npm archives/registry transport, exact versions, and `aug.lock.json`; [the package guide](packages.md) covers creation, installation, public imports and frozen CI builds.
+Compiler and extension development dependencies use exact versions and lockfiles. Native maps record the selected C toolchain and inputs; C compiler/OS versions are environment requirements, not vendored binaries. Source packages use public repository URLs, local folders, or npm archives, with revisions and integrity recorded in `aug.lock.json`; [the package guide](packages.md) covers creation, installation, public imports and frozen CI builds.
+
+## Inferred contract hints
+
+VS Code shows inferred results, mutations, capability operations, and escaping checked errors beside executable headers. Long capability/error lists collapse to counts; their tooltip shows the full contract. These hints use the checked project, including unsaved edits and imported declarations. They are display text; formatting and saving do not add them to source. Hover, signature help, `aug explain`, and compiled specs share the same contracts. Bodyless interfaces and foreign declarations keep explicit contracts.
+
+Hints are enabled by default. Disable `augscript.inferredContractHints` to hide them, or use VS Code’s `editor.inlayHints.enabled` setting. The language server supports `textDocument/inlayHint` with range filtering for other editors.

package/docs/weather-api.md

@@ -0,0 +1,65 @@
+# Build a weather API
+
+Create a service that returns five simulated weather forecasts as JSON. This example follows the familiar weather API shape from Microsoft's ASP.NET Core starter: a date, Celsius and Fahrenheit temperatures, and a summary. It uses fixed values so you can reproduce its responses and tests. It does not fetch live weather.
+
+You need the [August toolchain](packages.md#npm-registry) and the native HTTP build prerequisites described in the [web guide](web.md). You can also use a [Dev Container](dev-containers.md).
+
+## Start the service
+
+```sh
+npx @greenpandastudios/aug-cli@next init weather --template weather
+cd weather
+npx @greenpandastudios/aug-cli@next run
+```
+
+The first run prepares the required native dependencies and starts the server on port 8787. Keep it running, then open another terminal:
+
+```sh
+curl http://127.0.0.1:8787/weatherforecast
+```
+
+You should receive an array of five forecasts. Its first item is:
+
+```json
+{"date":"2026-01-01","temperatureC":0,"temperatureF":32,"summary":"Freezing"}
+```
+
+Open `http://127.0.0.1:8787/docs` for the API viewer, or `/openapi.json` for the generated OpenAPI document. The starter also includes `weather.http` with these requests for editors that support HTTP request files. Stop the server with Ctrl+C before starting another instance on the same port.
+
+## Read the two source files
+
+`main.aug` imports the endpoint and starts it:
+
+```text
+import weatherForecast from forecasts
+
+serve weatherForecast on port 8787
+```
+
+`forecasts.aug` declares the immutable `WeatherForecast` record, the endpoint, and its tests. The endpoint has no inputs and returns a list of records. August infers that result from its body, serializes it as JSON, and describes the same shape in OpenAPI. You do not need a controller class or a library dependency for this service.
+
+A record construction names each field, for example:
+
+```text
+WeatherForecast(
+    date="2026-01-01",
+    temperatureC=0,
+    temperatureF=32,
+    summary="Freezing"
+)
+```
+
+The endpoint's route is `GET /weatherforecast`. The test client exercises that route through the HTTP pipeline; it checks the JSON response and the rejection of another HTTP method. `main.yaml` enables OpenAPI and sets the document title and version.
+
+## Make a change and check it
+
+In `forecasts.aug`, change the first summary from `Freezing` to `Cold`. Run the application again and check that the first response changed. Then run:
+
+```sh
+npx @greenpandastudios/aug-cli@next test
+npx @greenpandastudios/aug-cli@next spec
+```
+
+If you installed the CLI globally, the equivalent commands are `aug test` and `aug spec`. Open `forecasts.aug.md` to read the actual compiled explanation. The starter's `AGENTS.md` asks coding agents to read that explanation before changing the code.
+
+[Browse the complete weather project](examples/weather-api/index.md) to see the source beside its generated spec, switch between indentation and braces, or download the files. Continue with the [web guide](web.md) to accept typed inputs, return errors, render HTML, or stream a response. See Microsoft's [first web API tutorial](https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api) for the original starter context.

package/docs/web.md

@@ -1,30 +1,47 @@
 # HTTP, server pages, and crypto
 
-HTTP endpoints are language declarations. `august.web` supplies explicit network, authentication, authorization, and logging capabilities; `august.crypto` supplies cryptographic adapters. August source owns routing contracts and application decisions. The native boundary owns transport, serialization, and cryptographic primitives.
+Build a service by declaring its routes in August and serving them from `main.aug`. The declarations describe how HTTP inputs become typed values and how results become responses. Your application selects authentication, authorization, and logging capabilities explicitly. The optional web and crypto packages provide adapters for native transport and cryptographic operations.
+
+This guide builds a service with JSON, a server-rendered page, a form action, and an event stream. Learn [modules and dependencies](learn/modules-and-dependencies.md) first if `implement` and `resolve` are unfamiliar. Full web and crypto runs need the [native bootstrap](tooling.md#native-standard-libraries). The service uses demonstration authentication; [the gap ledger](web-library-gaps.md) describes what remains before a production service claim.
 
 ## A complete service
 
-This project serves a protected JSON endpoint, an August page, a form action, and an event stream. The documentation gate builds it and runs its endpoint cases without starting a persistent server. Copy the files into one folder and run `aug run FOLDER` to listen on port 8080.
+Copy the following files into one folder and run `aug install`. `aug check .` checks the contracts and `aug test .` runs the three endpoint cases. `aug run .` starts the server on port 8080. The documentation gate builds the service and runs its tests; it does not leave a server running.
+
+Read `main.aug` first. It supplies the authentication and request-logging implementations, then serves the four named endpoints. Read `api.aug` for the JSON route and stream, `actions.aug` for the POST, and the page/view files for HTML.
+
+**main.yaml**
+
+```yaml project=web-guide file=main.yaml
+packages:
+  web: "https://github.com/GreenPandaStudios/augscript/src/stdlib/web#v0.19.0"
+```
+
+**main.aug**
 
 ```aug project=web-guide file=main.aug
 import readUser and events from api
 import home from pages
 import save from actions
 import DemoAuthentication from auth
-import Authentication and RequestLogger and WebRequestLogger from august.web
+import Authentication and RequestLogger and WebRequestLogger from web
 
 implement Authentication with DemoAuthentication
 implement RequestLogger with WebRequestLogger scoped
 serve readUser and events and home and save on port 8080
 ```
 
+**models.aug**
+
 ```aug project=web-guide file=models.aug
 record User(int id, string name)
 record UserInput(string name)
 ```
 
+**auth.aug**
+
 ```aug project=web-guide file=auth.aug
-import Authentication and Principal from august.web
+import Authentication and Principal from web
 
 /** A demonstration adapter. Replace its credential check for a real application. */
 DemoAuthentication() implements Authentication:
@@ -38,10 +55,12 @@ DemoAuthentication() implements Authentication:
                 return null
 ```
 
+**api.aug**
+
 ```aug project=web-guide file=api.aug
 import User from models
 import DemoAuthentication from auth
-import Authentication and RequestLogger and WebRequestLogger from august.web
+import Authentication and RequestLogger and WebRequestLogger from web
 
 /** Look up one user. Authentication runs before the identifier is decoded. */
 [LogRequest(logger=logger)]
@@ -49,7 +68,7 @@ import Authentication and RequestLogger and WebRequestLogger from august.web
 [RateLimit(requests=100, seconds=60)]
 [Timeout(milliseconds=1000)]
 [Compress]
-endpoint GET "/users/{id}" as readUser(int id from path, resolve Authentication auth, resolve RequestLogger logger) returns User uses auth.authenticate and logger.complete:
+endpoint GET "/users/{id}" as readUser(int id from path, resolve Authentication auth, resolve RequestLogger logger):
     return User(id, name="Ada")
 
 test endpoint readUser client:
@@ -78,15 +97,19 @@ test endpoint events client:
             assert(condition=response.headers.get(name="content-type") == "text/event-stream")
 ```
 
+**actions.aug**
+
 ```aug project=web-guide file=actions.aug
 import UserInput from models
-import redirect from august.web
+import redirect from web
 
 /** Accept a typed form and redirect after handling it. */
-endpoint POST "/users" as save(UserInput input from form) returns HttpResponse<string> unless HttpError:
+endpoint POST "/users" as save(UserInput input from form):
     return redirect(location="/")
 ```
 
+**views.aug**
+
 ```aug project=web-guide file=views.aug
 import User from models
 import save from actions
@@ -98,6 +121,8 @@ NewUser() returns Html unless HttpError:
     return <form onSubmit={handle save(input from form)}><label>Name <input name="name" required /></label><button type="submit">Save</button></form>
 ```
 
+**pages.aug**
+
 ```aug project=web-guide file=pages.aug
 import User from models
 import UserCard and NewUser from views
@@ -119,7 +144,7 @@ JSON bodies decode into concrete immutable records. `optional T` allows a value
 
 An ordinary return becomes the documented status and a JSON, Html, or Bytes representation. `HttpResponse<T>` selects status and immutable `Headers` explicitly. `Headers.with` appends a value, preserving repeated headers such as Set-Cookie; singular wire inputs reject duplicates. The `redirect` and `cookie` helpers validate header values. Cookie callers explicitly choose Secure and lifetime settings.
 
-Response status literals must range from 200 to 599; constructing a response with a dynamic status requires handling or declaring `HttpError`. Complex form fields use the same JSON schemas as body inputs: malformed JSON text returns 400 and a schema mismatch returns 422.
+Response status literals must range from 200 to 599. Constructing a response with a dynamic status can fail with `HttpError`; catch that failure or let it propagate through the inferred contract. Complex form fields use the same JSON schemas as body inputs: malformed JSON text returns 400 and a schema mismatch returns 422.
 
 `unless ErrorType with status CODE` declares an error response. Unexpected failures produce 500 with server-side error reporting. Default failures use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html). OAuth endpoints in the proof return their protocol's JSON errors explicitly. HEAD suppresses the body; 204 and 304 suppress body and Content-Length. See the [gap ledger](web-library-gaps.md) for unimplemented HTTP behavior; this is not a claim of full protocol conformance.
 
@@ -129,15 +154,15 @@ The first written HTTP policy is outermost. Policies execute before wire decodin
 
 | Policy | Inputs and behavior |
 | --- | --- |
-| RequireLogin | `authentication=auth` maps an explicit `resolve Authentication auth`; declare `uses auth.authenticate`. A null identity returns 401. The adapter validates credentials. |
-| RequirePermission | Maps Authentication and Authorization dependencies plus a literal permission; denied access returns 403. Declare both capability operations. |
-| LogRequest | Maps `resolve RequestLogger logger` and `uses logger.complete`. Calls completion in reverse layer order after transport completion or disconnect. Disconnect status is 499 for logging. WebRequestLogger emits escaped JSON metadata without credentials or query strings. |
+| RequireLogin | `authentication=auth` maps an explicit `resolve Authentication auth`. The compiler includes `auth.authenticate` in the handler's inferred contract. A null identity returns 401. The adapter validates credentials. |
+| RequirePermission | Maps Authentication and Authorization dependencies plus a literal permission; denied access returns 403. Both capability operations appear in the inferred contract. |
+| LogRequest | Maps `resolve RequestLogger logger` and adds `logger.complete` to the inferred contract. Calls completion in reverse layer order after transport completion or disconnect. Disconnect status is 499 for logging. WebRequestLogger emits escaped JSON metadata without credentials or query strings. |
 | RateLimit | Literal requests and seconds; a bounded fixed-window counter per endpoint and trusted transport peer. It ignores client-supplied forwarding headers. Excess returns 429. |
 | Timeout | Literal milliseconds; handler, scoped tasks, streaming and transport share the deadline. Before output, timeout returns 504; after headers it terminates output. C calls finish before cooperative cancellation is observed. Buffered request reception precedes this deadline. |
 | Cors | Literal exact origins, optional request-header allowlist and credentials. A supplied disallowed origin returns 403. Preflight checks the selected route's method and requested headers. Wildcard cannot enable credentials. CORS is not authentication or CSRF protection. |
 | Compress | Negotiates gzip, respects an existing Content-Encoding, and skips bodyless statuses. Stream items use complete concatenated gzip members as permitted by [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952.html). |
 
-Options are compile-time literals; dependency mappings must reference the canonical `august.web` capabilities. Cors and Compress may each appear once. Multiple deadlines choose the earliest. Custom interceptors retain their checked around/next contracts and written order.
+Options are compile-time literals. Import the policy interfaces from the web source package; the compiler checks their signatures against the native adapter contract. Cors and Compress may each appear once. Multiple deadlines choose the earliest. Custom interceptors retain their checked around/next contracts and written order.
 
 ## Streams and scoped tasks
 
@@ -186,12 +211,19 @@ Crypto is an injected capability with GnuTlsCrypto as its native adapter. It pro
 
 `signJwt` requires an explicit key id and token type. `verifyJwt` accepts the configured RS256/key-id/type profile, rejects unsupported JOSE fields, verifies the signature before exposing claims, and follows no token-provided URL. The consuming protocol still validates issuer, audience, times, nonce and token purpose. The implementation follows the fixed-algorithm approach described in [JWT best current practices](https://www.rfc-editor.org/rfc/rfc8725.html).
 
-The [same-app login example](../examples/oidc-login/README.md) contains an OpenID Connect provider and relying party in one August application. It uses real loopback discovery, authorization, token, JWKS and UserInfo endpoints, Authorization Code with S256 PKCE, browser-bound state/nonce/CSRF, and a distinct application-session JWT with live revocation. The UI signs in and signs out through typed actions. See [OpenID Connect Core validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) and [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+The [same-app login example](examples/oidc-login/index.md) contains an OpenID Connect provider and relying party in one August application. It uses real loopback discovery, authorization, token, JWKS and UserInfo endpoints, Authorization Code with S256 PKCE, browser-bound state/nonce/CSRF, and a distinct application-session JWT with live revocation. The UI signs in and signs out through typed actions. See [OpenID Connect Core validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) and [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+
+Download and extract [the login project](examples/oidc-login/index.md#try-this-project). From the folder containing it:
+
+```sh
+cd oidc-login
+aug run
+```
+
+In another terminal, run the signed-claim tests from the same project folder:
 
 ```sh
-node scripts/bootstrap-native.mjs
-node bin/aug.mjs run examples/oidc-login
-node bin/aug.mjs test examples/oidc-login --group signed_identity_claims
+aug test --group signed_identity_claims
 ```
 
-Open http://127.0.0.1:8787 and sign in as **ada** with **august-demo**. `/me` returns the protected identity; `/docs` exposes endpoint contracts. The [gap ledger](web-library-gaps.md) distinguishes this verified development profile from broader provider, library and runtime support.
+The first run prepares the native HTTP and crypto libraries automatically; later runs reuse them. [Install August](getting-started.md) first if `aug` is not available. Open http://127.0.0.1:8787 and sign in as **ada** with **august-demo**. `/me` returns the protected identity; `/docs` exposes endpoint contracts. The [gap ledger](web-library-gaps.md) distinguishes this verified development profile from broader provider, library and runtime support.

package/docs/writing-docs.md

@@ -0,0 +1,49 @@
+# Writing the August documentation
+
+Write for a developer who wants to understand a program, complete a task, or check a rule. The wiki serves people trying August, engineers assessing it for a team, and developers working with coding agents. State what the current language does and show it in code. Design goals need explanation; claims of safety, speed, productivity, or production readiness need evidence and scope.
+
+The [editorial research](research/wiki-editorial-design.md) records the primary sources behind this approach. The Rust book informs the learning sequence; C's About page informs the compact introduction. Diátaxis informs the separate reading modes. Google's developer style guidance informs the prose. August's writing and examples are original.
+
+## Put a page in the right place
+
+| Reader's need | Place | What the page provides |
+| --- | --- | --- |
+| Learn a new concept | `docs/learn/` and `getting-started.md` | A runnable lesson with a goal, expected result, and next step. |
+| Complete a task | `docs/guides/` or an existing task guide | Direct actions, prerequisites, verification, and relevant limits. |
+| Look up exact behavior | Language, tooling, grammar, or generated API reference | Precise contracts and a consistent structure. |
+| Understand a design or assess the language | About, performance, readiness, compatibility, roadmap | Reasons, tradeoffs, and evidence. |
+| Maintain August | Contributor guides and research notes | Repository workflows and implementation details. |
+
+Keep existing URLs and anchors when a page still serves the same need. Add links to the lesson or task guide rather than turning the reference into a second book. Contributor processes belong under Contribute in navigation.
+
+## Explain it like a developer
+
+Open with the problem or operation the reader cares about. Introduce a program by saying what it does, then explain the important lines and their consequences. Use ordinary connected sentences and short paragraphs. Name actual declarations and commands. Explain unfamiliar terms when they first matter.
+
+Use lists for steps or parallel items and tables for comparisons. A prose explanation should not become a stack of bullets, headings, or signature dumps. Remove repeated summaries and promises that a topic will be explained later. Avoid promotional adjectives and claims that a procedure is easy. Precision matters more than brevity when a dependency, state change, failure, or limit could surprise the reader.
+
+For example, write: “The group constructs a new counter for each case. The second case still sees its initial value.” That explains the behavior a reader can observe. “Isolated test architecture enables scalable validation” does not.
+
+## Give examples a dependable path
+
+A lesson assumes the reader knows programming, not August. State where commands run, which files to save, and the output to expect. Introduce one new mechanism at a time where practical. Put detailed alternatives and edge cases in the reference and link them from the lesson.
+
+Install the published CLI once, then teach `aug init NAME` and `aug run`. Keep npx as an optional installation alternative. Continue lessons with short aug commands and offer complete example downloads. Reader instructions must not require cloning the language repository or running its internal CLI files. Source-workspace build and maintenance commands belong in contributor pages. Explain automatic dependency preparation and the system-tool prerequisites; distinguish creating files from preparing or executing a program.
+
+Complete runnable source uses `aug project=NAME file=PATH` fences and an entry in `docs/examples.json`. Fragments use `text` and explicitly say they are fragments. Before an intentional failure, say what change the reader is making and that checking or running it should fail; afterward explain the result and how to restore working code. Test important failing examples as well as successful ones when the lesson depends on that behavior.
+
+Handwritten lesson code is checked and run by `tests/documentation.test.mjs`, including nested Learn and Guides pages. `docs/lesson-failures.json` describes the book's tested mistake transformations and expected diagnostics. Generated gallery pages get their examples from `docs/example-projects.json` and `scripts/example-docs.mjs`. Edit those inputs, source, or Javadoc and regenerate; do not hand-edit generated Markdown.
+
+## Keep claims current
+
+Verify command names against CLI help and contracts against declarations, checker/runtime behavior, and regression tests. Do not infer semantics from a function's name. Keep release versions and installation availability in their canonical pages; link to them from introductions. A possible future command is not an installation instruction.
+
+Performance claims need a workload, compiler version, environment, methodology, and raw measurements. The homepage links to the benchmark page instead of duplicating numbers that can become stale. Do not treat microbenchmarks as evidence of agent productivity or general production readiness.
+
+An example involving security or deployment states its applicable limits nearby. Pending approval work and proposals remain labeled as such. Keep [readiness](production-readiness.md), the [roadmap](roadmap.md), and [library gaps](web-library-gaps.md) consistent with implemented behavior.
+
+## Review before publishing
+
+Follow [documentation maintenance](maintaining-docs.md) for generation and executable checks. Read the rendered page as a newcomer: can you find the first action, follow dependencies, understand the result, and locate the full contract? Check a narrow screen for long code and tables, and a wider screen for code/spec comparisons. Review copied source as well as visual wrapping.
+
+Research notes cite primary sources near the claims they support and distinguish findings from recommendations. Link research from contributor pages when it explains an editorial decision; users should not need to read the research to use August.

package/examples/{hello/.aug-spec/august/0.19.0 → approved-design/.aug-spec/august/0.20.1}/io/contracts.aug

@@ -1,4 +1,5 @@
 // Generated by aug spec. This is a copy of the installed dependency source.
+// 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. */
@@ -21,9 +22,9 @@ capability FileWriter:
 
 /** Native files. Operations are explicit; construction opens no files. */
 LocalFiles() implements FileReader, FileWriter:
-    read(string path) returns string unless FileError:
+    read(string path) :
         return read_file(path=path)
-    write(string path, string content) unless FileError:
+    write(string path, string content) :
         write_file(path=path, content=content)
 
 /** Read command-line input through an explicit dependency. */
@@ -32,5 +33,5 @@ capability Arguments:
 
 /** Native command-line arguments. */
 ProcessArguments() implements Arguments:
-    read() returns List<string>:
+    read() :
         return arguments()

package/examples/approved-design/.aug-spec/august/0.20.1/io/contracts.aug.md

@@ -0,0 +1,82 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug`
+
+<a id="symbol-Console"></a>
+## `Console` · capability interface · [source](contracts.aug#L4)
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+### `Console.write` · [source](contracts.aug#L6)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+<a id="symbol-SystemConsole"></a>
+## `SystemConsole` · class · [source](contracts.aug#L9)
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.aug.md#symbol-Console).
+
+<a id="symbol-SystemConsole.write"></a>
+### `SystemConsole.write` · [source](contracts.aug#L10)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+<a id="symbol-FileReader"></a>
+## `FileReader` · capability interface · [source](contracts.aug#L14)
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+### `FileReader.read` · [source](contracts.aug#L16)
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.aug.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+<a id="symbol-FileWriter"></a>
+## `FileWriter` · capability interface · [source](contracts.aug#L19)
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+### `FileWriter.write` · [source](contracts.aug#L21)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+<a id="symbol-LocalFiles"></a>
+## `LocalFiles` · class · [source](contracts.aug#L24)
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.aug.md#symbol-FileReader) and [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+<a id="symbol-LocalFiles.read"></a>
+### `LocalFiles.read` · [source](contracts.aug#L25)
+
+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`.
+
+<a id="symbol-LocalFiles.write"></a>
+### `LocalFiles.write` · [source](contracts.aug#L27)
+
+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`.
+
+<a id="symbol-Arguments"></a>
+## `Arguments` · capability interface · [source](contracts.aug#L31)
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+### `Arguments.read` · [source](contracts.aug#L32)
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+<a id="symbol-ProcessArguments"></a>
+## `ProcessArguments` · class · [source](contracts.aug#L35)
+
+Native command-line arguments. It implements [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+<a id="symbol-ProcessArguments.read"></a>
+### `ProcessArguments.read` · [source](contracts.aug#L36)
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/approved-design/.aug-spec/manifest.json

@@ -1,8 +1,8 @@
 {
   "format": 1,
   "files": [
-    ".aug-spec/august/0.19.0/io/contracts.aug",
-    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    ".aug-spec/august/0.20.1/io/contracts.aug",
+    ".aug-spec/august/0.20.1/io/contracts.aug.md",
     "counters.aug.md",
     "domain/app.aug.md",
     "domain/export.aug.md",
@@ -10,5 +10,5 @@
     "domain/numbers.aug.md",
     "main.aug.md"
   ],
-  "digest": "17b8a92022fe0e3becdd73b3eb31493a9cebe7ddeb63b1e76596c612ed728d88"
+  "digest": "62a350fdc80a432889b594eb5999b865b9801dcb7aaf6e90e1b636538d15ce58"
 }

package/examples/approved-design/counters.aug

@@ -1,20 +1,21 @@
+// aug-spec: "counters.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Reading state has no mutation effect. */
 interface State:
 	read() returns int
 _Initial() implements State:
-	read() returns int:
+	read() :
 		return 0
 _Updated(int count) implements State:
-	read() returns int:
+	read() :
 		return count
 /** A mutable counter with an explicit transition contract. */
 interface Counter:
 	increment() changes self
 	value() returns int
 _Counter(resolve mutable State initial to _state) implements Counter:
-	increment() changes self:
+	increment() :
 		_state to _Updated(count=_state.read() + 1)
-	value() returns int:
+	value() :
 		return _state.read()
 /** The complete counter composition; its mutable state belongs to each scope. */
 composition Counters: