@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/oidc-login/provider/contracts.md

@@ -49,6 +49,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** A provider request is bound to a browser cookie, a form CSRF token, and a registered client. */
 record AuthorizationRequest(string clientId, string redirectUri, string state, string nonce, string challenge, string browser, string csrf, int expires)
 /** Codes are short-lived, single-use and bound to a redirect URI and S256 challenge. */
@@ -67,6 +68,7 @@ CodeError() implements Error:
 ```
 
 ```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** A provider request is bound to a browser cookie, a form CSRF token, and a registered client. */
 record AuthorizationRequest(string clientId, string redirectUri, string state, string nonce, string challenge, string browser, string csrf, int expires)
 /** Codes are short-lived, single-use and bound to a redirect URI and S256 challenge. */
@@ -94,173 +96,49 @@ CodeError() implements Error {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `AuthorizationRequest` · immutable record · [source](contracts.md#code) {#symbol-AuthorizationRequest}
 
-### In this file
+A provider request is bound to a browser cookie, a form CSRF token, and a registered client. It takes `clientId`, `redirectUri`, `state`, `nonce`, `challenge`, `browser`, and `csrf` as strings, kept read-only and `expires` as an integer, kept read-only.
 
-- [`AuthorizationRequest`](contracts.md#symbol-AuthorizationRequest) is an immutable record.
-- [`AuthorizationCode`](contracts.md#symbol-AuthorizationCode) is an immutable record.
-- [`IdClaims`](contracts.md#symbol-IdClaims) is an immutable record.
-- [`AccessGrant`](contracts.md#symbol-AccessGrant) is an immutable record.
-- [`TokenResponse`](contracts.md#symbol-TokenResponse) is an immutable record.
-- [`OAuthError`](contracts.md#symbol-OAuthError) is an immutable record.
-- [`TokenForm`](contracts.md#symbol-TokenForm) is an immutable record.
-- [`LoginForm`](contracts.md#symbol-LoginForm) is an immutable record.
-- [`UserInfo`](contracts.md#symbol-UserInfo) is an immutable record.
-- [`LoginError`](contracts.md#symbol-LoginError) is a class implementing `Error`.
-- [`CodeError`](contracts.md#symbol-CodeError) is a class implementing `Error`.
+### `AuthorizationCode` · immutable record · [source](contracts.md#code) {#symbol-AuthorizationCode}
 
-### `AuthorizationRequest` {#symbol-AuthorizationRequest}
+Codes are short-lived, single-use and bound to a redirect URI and S256 challenge. It takes `clientId`, `redirectUri`, `challenge`, `nonce`, `subject`, and `name` as strings, kept read-only and `expires` as an integer, kept read-only.
 
-[source](contracts.md#code)
+### `IdClaims` · immutable record · [source](contracts.md#code) {#symbol-IdClaims}
 
-Immutable record.
+It takes `iss`, `sub`, and `aud` as strings, kept read-only, `exp` and `iat` as integers, kept read-only, and `nonce` and `name` as strings, kept read-only.
 
-**Author documentation**
+### `AccessGrant` · immutable record · [source](contracts.md#code) {#symbol-AccessGrant}
 
-A provider request is bound to a browser cookie, a form CSRF token, and a registered client.
+It takes `subject` and `name` as strings, kept read-only and `expires` as an integer, kept read-only.
 
-**Inputs**
+### `TokenResponse` · immutable record · [source](contracts.md#code) {#symbol-TokenResponse}
 
-- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
-- `redirectUri` (`string`) — required labeled input — stored as `redirectUri` and read-only after initialization.
-- `state` (`string`) — required labeled input — stored as `state` and read-only after initialization.
-- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
-- `challenge` (`string`) — required labeled input — stored as `challenge` and read-only after initialization.
-- `browser` (`string`) — required labeled input — stored as `browser` and read-only after initialization.
-- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
-- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+It takes `token_type`, `access_token`, and `id_token` as strings, kept read-only, `expires_in` as an integer, kept read-only, and `scope` as a string, kept read-only.
 
-### `AuthorizationCode` {#symbol-AuthorizationCode}
+### `OAuthError` · immutable record · [source](contracts.md#code) {#symbol-OAuthError}
 
-[source](contracts.md#code)
+It takes `error` and `error_description` as strings, kept read-only.
 
-Immutable record.
+### `TokenForm` · immutable record · [source](contracts.md#code) {#symbol-TokenForm}
 
-**Author documentation**
+It takes `grant_type`, `code`, `redirect_uri`, `client_id`, and `code_verifier` as strings, kept read-only.
 
-Codes are short-lived, single-use and bound to a redirect URI and S256 challenge.
+### `LoginForm` · immutable record · [source](contracts.md#code) {#symbol-LoginForm}
 
-**Inputs**
+It takes `request_id`, `csrf`, `username`, and `password` as strings, kept read-only.
 
-- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
-- `redirectUri` (`string`) — required labeled input — stored as `redirectUri` and read-only after initialization.
-- `challenge` (`string`) — required labeled input — stored as `challenge` and read-only after initialization.
-- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
-- `subject` (`string`) — required labeled input — stored as `subject` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+### `UserInfo` · immutable record · [source](contracts.md#code) {#symbol-UserInfo}
 
-### `IdClaims` {#symbol-IdClaims}
+It takes `sub` and `name` as strings, kept read-only.
 
-[source](contracts.md#code)
+### `LoginError` · class · [source](contracts.md#code) {#symbol-LoginError}
 
-Immutable record.
+It implements `Error`.
 
-**Inputs**
+### `CodeError` · class · [source](contracts.md#code) {#symbol-CodeError}
 
-- `iss` (`string`) — required labeled input — stored as `iss` and read-only after initialization.
-- `sub` (`string`) — required labeled input — stored as `sub` and read-only after initialization.
-- `aud` (`string`) — required labeled input — stored as `aud` and read-only after initialization.
-- `exp` (`int`) — required labeled input — stored as `exp` and read-only after initialization.
-- `iat` (`int`) — required labeled input — stored as `iat` and read-only after initialization.
-- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-
-### `AccessGrant` {#symbol-AccessGrant}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `subject` (`string`) — required labeled input — stored as `subject` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
-
-### `TokenResponse` {#symbol-TokenResponse}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `token_type` (`string`) — required labeled input — stored as `token_type` and read-only after initialization.
-- `access_token` (`string`) — required labeled input — stored as `access_token` and read-only after initialization.
-- `id_token` (`string`) — required labeled input — stored as `id_token` and read-only after initialization.
-- `expires_in` (`int`) — required labeled input — stored as `expires_in` and read-only after initialization.
-- `scope` (`string`) — required labeled input — stored as `scope` and read-only after initialization.
-
-### `OAuthError` {#symbol-OAuthError}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `error` (`string`) — required labeled input — stored as `error` and read-only after initialization.
-- `error_description` (`string`) — required labeled input — stored as `error_description` and read-only after initialization.
-
-### `TokenForm` {#symbol-TokenForm}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `grant_type` (`string`) — required labeled input — stored as `grant_type` and read-only after initialization.
-- `code` (`string`) — required labeled input — stored as `code` and read-only after initialization.
-- `redirect_uri` (`string`) — required labeled input — stored as `redirect_uri` and read-only after initialization.
-- `client_id` (`string`) — required labeled input — stored as `client_id` and read-only after initialization.
-- `code_verifier` (`string`) — required labeled input — stored as `code_verifier` and read-only after initialization.
-
-### `LoginForm` {#symbol-LoginForm}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `request_id` (`string`) — required labeled input — stored as `request_id` and read-only after initialization.
-- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
-- `username` (`string`) — required labeled input — stored as `username` and read-only after initialization.
-- `password` (`string`) — required labeled input — stored as `password` and read-only after initialization.
-
-### `UserInfo` {#symbol-UserInfo}
-
-[source](contracts.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `sub` (`string`) — required labeled input — stored as `sub` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-
-### `LoginError` {#symbol-LoginError}
-
-[source](contracts.md#code)
-
-Behavioral class.
-
-Satisfies `Error`.
-
-### `CodeError` {#symbol-CodeError}
-
-[source](contracts.md#code)
-
-Behavioral class.
-
-Satisfies `Error`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It implements `Error`.
 
 ::::
 

package/docs/examples/oidc-login/provider/credentials.md

@@ -49,12 +49,17 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
-import Crypto from august.crypto
+// aug-spec: "credentials.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Crypto from crypto
 /** One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability. */
-verifyCredentials(string username, string password, resolve Crypto crypto) returns bool uses crypto.passwordHash and crypto.decodeBase64url and crypto.equal unless CryptoError:
+verifyCredentials(string username, string password, resolve Crypto crypto):
     if username.length() > 64 or password.length() > 256:
         return false
-    actual = crypto.passwordHash(password=password.bytes(), salt="August demo salt v1".bytes(), iterations=600000)
+    actual = crypto.passwordHash(
+        password=password.bytes(),
+        salt="August demo salt v1".bytes(),
+        iterations=600000
+    )
     expected = crypto.decodeBase64url(input="s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A")
     userMatches = crypto.equal(left=username.bytes(), right="ada".bytes())
     passwordMatches = crypto.equal(left=actual, right=expected)
@@ -62,13 +67,18 @@ verifyCredentials(string username, string password, resolve Crypto crypto) retur
 ```
 
 ```aug [Braces]
-import Crypto from august.crypto
+// aug-spec: "credentials.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Crypto from crypto
 /** One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability. */
-verifyCredentials(string username, string password, resolve Crypto crypto) returns bool uses crypto.passwordHash and crypto.decodeBase64url and crypto.equal unless CryptoError {
+verifyCredentials(string username, string password, resolve Crypto crypto) {
     if username.length() > 64 or password.length() > 256 {
         return false
     }
-    actual = crypto.passwordHash(password=password.bytes(), salt="August demo salt v1".bytes(), iterations=600000)
+    actual = crypto.passwordHash(
+        password=password.bytes(),
+        salt="August demo salt v1".bytes(),
+        iterations=600000
+    )
     expected = crypto.decodeBase64url(input="s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A")
     userMatches = crypto.equal(left=username.bytes(), right="ada".bytes())
     passwordMatches = crypto.equal(left=actual, right=expected)
@@ -84,64 +94,21 @@ verifyCredentials(string username, string password, resolve Crypto crypto) retur
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `verifyCredentials` · [source](credentials.md#code) {#symbol-verifyCredentials}
 
-### In this file
+One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability. It takes `username` and `password` as strings. It gets `crypto` ([`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto)) from dependency injection.
 
-- [`verifyCredentials`](credentials.md#symbol-verifyCredentials) is a function returning `bool`.
+Failures can raise `CryptoError`.
 
-### `verifyCredentials` {#symbol-verifyCredentials}
+If the byte length of `username` is greater than `64` or the byte length of `password` is greater than `256`, it returns `false`. It sets `actual` to [`crypto.passwordHash`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.passwordHash) with `password` from the UTF-8 bytes of `password`, `salt` from the UTF-8 bytes of `"August demo salt v1"`, and `iterations` `600000`. It sets `expected` to [`crypto.decodeBase64url`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.decodeBase64url) with `input` `"s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A"`. It sets `userMatches` to [`crypto.equal`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.equal) with `left` from the UTF-8 bytes of `username` and `right` from the UTF-8 bytes of `"ada"`.
 
-[source](credentials.md#code)
+It sets `passwordMatches` to [`crypto.equal`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.equal) with `left` from `actual` and `right` from `expected`. It returns `userMatches` and `passwordMatches`.
 
-**Inputs**
+### Dependencies
 
-- `username` (`string`) — required labeled input.
-- `password` (`string`) — required labeled input.
-- `crypto` ([`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)) — injected; callers omit it.
+It uses [`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto) ([`decodeBase64url`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.decodeBase64url), [`equal`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.equal), and [`passwordHash`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.passwordHash)) from `crypto`.
 
-Returns: `bool`.
-
-Capabilities: [`crypto.passwordHash`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.passwordHash), [`crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url), [`crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal).
-
-Can fail with `CryptoError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If (call `length` on `username` is greater than `64`) or (call `length` on `password` is greater than `256`):
-  - Return `false`.
-- Set `actual` to call [`Crypto.passwordHash`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.passwordHash) on `crypto` with `password` = call `bytes` on `password`; `salt` = call `bytes` on `"August demo salt v1"`; `iterations` = `600000`.
-- Set `expected` to call [`Crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url) on `crypto` with `input` = `"s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A"`.
-- Set `userMatches` to call [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `username`; `right` = call `bytes` on `"ada"`.
-- Set `passwordMatches` to call [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) on `crypto` with `left` = `actual`; `right` = `expected`.
-- Return `userMatches` and `passwordMatches`.
-
-**Author documentation**
-
-One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url) (`input`: `string`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
-- [`Crypto.passwordHash`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.passwordHash) (`password`: `Bytes`, `salt`: `Bytes`, `iterations`: `int`) → `Bytes`; can fail with `CryptoError`.
-
-### Built-in operations used by this file
-
-- `string.bytes` (no inputs) → `Bytes`: Encode this string as immutable UTF-8 bytes.
-- `string.length` (no inputs) → `int`: Read the number of UTF-8 bytes. Unicode text is preserved losslessly.
-
-[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/oidc-login/provider/discovery.md

@@ -49,30 +49,60 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "discovery.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import settings and SigningKeys and KeyError from common
-import Crypto and RsaJwks and rsaJwk from august.crypto
+import Crypto and RsaJwks and rsaJwk from crypto
 /** Discovery advertises exactly this provider's supported authorization-code profile. */
 record Discovery(string issuer, string authorization_endpoint, string token_endpoint, string userinfo_endpoint, string jwks_uri, List<string> response_types_supported, List<string> grant_types_supported, List<string> subject_types_supported, List<string> id_token_signing_alg_values_supported, List<string> token_endpoint_auth_methods_supported, List<string> scopes_supported, List<string> claims_supported, List<string> code_challenge_methods_supported)
-endpoint GET "/provider/.well-known/openid-configuration" as discovery() returns Discovery:
+endpoint GET "/provider/.well-known/openid-configuration" as discovery():
     config = settings()
-    return Discovery(issuer=config.issuer, authorization_endpoint=config.issuer + "/authorize", token_endpoint=config.issuer + "/token", userinfo_endpoint=config.issuer + "/userinfo", jwks_uri=config.issuer + "/jwks", response_types_supported=["code"], grant_types_supported=["authorization_code"], subject_types_supported=["public"], id_token_signing_alg_values_supported=["RS256"], token_endpoint_auth_methods_supported=["none"], scopes_supported=["openid", "profile"], claims_supported=["iss", "sub", "aud", "exp", "iat", "nonce", "name"], code_challenge_methods_supported=["S256"])
+    return Discovery(
+        issuer=config.issuer,
+        authorization_endpoint=config.issuer + "/authorize",
+        token_endpoint=config.issuer + "/token",
+        userinfo_endpoint=config.issuer + "/userinfo",
+        jwks_uri=config.issuer + "/jwks",
+        response_types_supported=["code"],
+        grant_types_supported=["authorization_code"],
+        subject_types_supported=["public"],
+        id_token_signing_alg_values_supported=["RS256"],
+        token_endpoint_auth_methods_supported=["none"],
+        scopes_supported=["openid", "profile"],
+        claims_supported=["iss", "sub", "aud", "exp", "iat", "nonce", "name"],
+        code_challenge_methods_supported=["S256"]
+    )
 /** Only the provider's public signing key is published. Session keys never enter this JWKS. */
-endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys keys) returns RsaJwks uses keys.provider and crypto.publicRsa and crypto.exportRsa unless KeyError and CryptoError:
+endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys keys):
     publicKey = crypto.publicRsa(key=keys.provider())
     return RsaJwks(keys=[rsaJwk(publicKey=publicKey, kid="provider-1")])
 ```
 
 ```aug [Braces]
+// aug-spec: "discovery.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import settings and SigningKeys and KeyError from common
-import Crypto and RsaJwks and rsaJwk from august.crypto
+import Crypto and RsaJwks and rsaJwk from crypto
 /** Discovery advertises exactly this provider's supported authorization-code profile. */
 record Discovery(string issuer, string authorization_endpoint, string token_endpoint, string userinfo_endpoint, string jwks_uri, List<string> response_types_supported, List<string> grant_types_supported, List<string> subject_types_supported, List<string> id_token_signing_alg_values_supported, List<string> token_endpoint_auth_methods_supported, List<string> scopes_supported, List<string> claims_supported, List<string> code_challenge_methods_supported)
-endpoint GET "/provider/.well-known/openid-configuration" as discovery() returns Discovery {
+endpoint GET "/provider/.well-known/openid-configuration" as discovery() {
     config = settings()
-    return Discovery(issuer=config.issuer, authorization_endpoint=config.issuer + "/authorize", token_endpoint=config.issuer + "/token", userinfo_endpoint=config.issuer + "/userinfo", jwks_uri=config.issuer + "/jwks", response_types_supported=["code"], grant_types_supported=["authorization_code"], subject_types_supported=["public"], id_token_signing_alg_values_supported=["RS256"], token_endpoint_auth_methods_supported=["none"], scopes_supported=["openid", "profile"], claims_supported=["iss", "sub", "aud", "exp", "iat", "nonce", "name"], code_challenge_methods_supported=["S256"])
+    return Discovery(
+        issuer=config.issuer,
+        authorization_endpoint=config.issuer + "/authorize",
+        token_endpoint=config.issuer + "/token",
+        userinfo_endpoint=config.issuer + "/userinfo",
+        jwks_uri=config.issuer + "/jwks",
+        response_types_supported=["code"],
+        grant_types_supported=["authorization_code"],
+        subject_types_supported=["public"],
+        id_token_signing_alg_values_supported=["RS256"],
+        token_endpoint_auth_methods_supported=["none"],
+        scopes_supported=["openid", "profile"],
+        claims_supported=["iss", "sub", "aud", "exp", "iat", "nonce", "name"],
+        code_challenge_methods_supported=["S256"]
+    )
 }
 /** Only the provider's public signing key is published. Session keys never enter this JWKS. */
-endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys keys) returns RsaJwks uses keys.provider and crypto.publicRsa and crypto.exportRsa unless KeyError and CryptoError {
+endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys keys) {
     publicKey = crypto.publicRsa(key=keys.provider())
     return RsaJwks(keys=[rsaJwk(publicKey=publicKey, kid="provider-1")])
 }
@@ -86,129 +116,25 @@ endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
-### In this file
+### `Discovery` · immutable record · [source](discovery.md#code) {#symbol-Discovery}
 
-- [`Discovery`](discovery.md#symbol-Discovery) is an immutable record.
-- [`discovery`](discovery.md#symbol-discovery) handles `GET` `/provider/.well-known/openid-configuration` returning `Discovery`.
-- [`jwks`](discovery.md#symbol-jwks) handles `GET` `/provider/jwks` returning `RsaJwks`.
+Discovery advertises exactly this provider's supported authorization-code profile. It takes `issuer`, `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, and `jwks_uri` as strings, kept read-only and `response_types_supported`, `grant_types_supported`, `subject_types_supported`, `id_token_signing_alg_values_supported`, `token_endpoint_auth_methods_supported`, `scopes_supported`, `claims_supported`, and `code_challenge_methods_supported` as `List<string>`, kept read-only.
 
-### `Discovery` {#symbol-Discovery}
+### `discovery` · [source](discovery.md#code) {#symbol-discovery}
 
-[source](discovery.md#code)
+`discovery` handles `GET /provider/.well-known/openid-configuration`. It gets `config` from [`settings`](../common/settings.md#symbol-settings). It returns a [`Discovery`](discovery.md#symbol-Discovery) with `config.issuer`, `authorization_endpoint` from the text `{config.issuer}/authorize`, `token_endpoint` from the text `{config.issuer}/token`, `userinfo_endpoint` from the text `{config.issuer}/userinfo`, `jwks_uri` from the text `{config.issuer}/jwks`, `response_types_supported` from a list containing `"code"`, `grant_types_supported` from a list containing `"authorization_code"`, `subject_types_supported` from a list containing `"public"`, `id_token_signing_alg_values_supported` from a list containing `"RS256"`, `token_endpoint_auth_methods_supported` from a list containing `"none"`, `scopes_supported` from a list containing `"openid"`, `"profile"`, `claims_supported` from a list containing `"iss"`, `"sub"`, `"aud"`, `"exp"`, `"iat"`, `"nonce"`, `"name"`, and `code_challenge_methods_supported` from a list containing `"S256"`.
 
-Immutable record.
+### `jwks` · [source](discovery.md#code) {#symbol-jwks}
 
-**Author documentation**
+`jwks` handles `GET /provider/jwks`. Only the provider's public signing key is published. Session keys never enter this JWKS. It gets `crypto` ([`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto)) and `keys` ([`SigningKeys`](../common/keys.md#symbol-SigningKeys)) from dependency injection.
 
-Discovery advertises exactly this provider's supported authorization-code profile.
+It can also raise `CryptoError` and `KeyError`. It sets `publicKey` to [`crypto.publicRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.publicRsa) with `key` from [`keys.provider`](../common/keys.md#symbol-SigningKeys.provider). It returns a [`RsaJwks`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-RsaJwks) with `keys` from a list containing [`rsaJwk`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-rsaJwk) with `publicKey` and `kid` `"provider-1"` using injected `crypto`.
 
-**Inputs**
+### Dependencies
 
-- `issuer` (`string`) — required labeled input — stored as `issuer` and read-only after initialization.
-- `authorization_endpoint` (`string`) — required labeled input — stored as `authorization_endpoint` and read-only after initialization.
-- `token_endpoint` (`string`) — required labeled input — stored as `token_endpoint` and read-only after initialization.
-- `userinfo_endpoint` (`string`) — required labeled input — stored as `userinfo_endpoint` and read-only after initialization.
-- `jwks_uri` (`string`) — required labeled input — stored as `jwks_uri` and read-only after initialization.
-- `response_types_supported` (`List<string>`) — required labeled input — stored as `response_types_supported` and read-only after initialization.
-- `grant_types_supported` (`List<string>`) — required labeled input — stored as `grant_types_supported` and read-only after initialization.
-- `subject_types_supported` (`List<string>`) — required labeled input — stored as `subject_types_supported` and read-only after initialization.
-- `id_token_signing_alg_values_supported` (`List<string>`) — required labeled input — stored as `id_token_signing_alg_values_supported` and read-only after initialization.
-- `token_endpoint_auth_methods_supported` (`List<string>`) — required labeled input — stored as `token_endpoint_auth_methods_supported` and read-only after initialization.
-- `scopes_supported` (`List<string>`) — required labeled input — stored as `scopes_supported` and read-only after initialization.
-- `claims_supported` (`List<string>`) — required labeled input — stored as `claims_supported` and read-only after initialization.
-- `code_challenge_methods_supported` (`List<string>`) — required labeled input — stored as `code_challenge_methods_supported` and read-only after initialization.
-
-### `discovery` {#symbol-discovery}
-
-[source](discovery.md#code)
-
-Returns: [`Discovery`](discovery.md#symbol-Discovery).
-
-HTTP route: `GET` `/provider/.well-known/openid-configuration`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-**What it does**
-
-- Set `config` to call [`settings`](../common/settings.md#symbol-settings).
-- Return call [`Discovery`](discovery.md#symbol-Discovery) with `issuer` = `issuer` of `config`; `authorization_endpoint` = (`issuer` of `config` plus `"/authorize"`); `token_endpoint` = (`issuer` of `config` plus `"/token"`); `userinfo_endpoint` = (`issuer` of `config` plus `"/userinfo"`); `jwks_uri` = (`issuer` of `config` plus `"/jwks"`); `response_types_supported` = a list containing `"code"`; `grant_types_supported` = a list containing `"authorization_code"`; `subject_types_supported` = a list containing `"public"`; `id_token_signing_alg_values_supported` = a list containing `"RS256"`; `token_endpoint_auth_methods_supported` = a list containing `"none"`; `scopes_supported` = a list containing `"openid"`, `"profile"`; `claims_supported` = a list containing `"iss"`, `"sub"`, `"aud"`, `"exp"`, `"iat"`, `"nonce"`, `"name"`; `code_challenge_methods_supported` = a list containing `"S256"`.
-
-### `jwks` {#symbol-jwks}
-
-[source](discovery.md#code)
-
-**Inputs**
-
-- `crypto` ([`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)) — injected; callers omit it.
-- `keys` ([`SigningKeys`](../common/keys.md#symbol-SigningKeys)) — injected; callers omit it.
-
-Returns: [`RsaJwks`](../dependencies/august/0.19.0/crypto/jose.md#symbol-RsaJwks).
-
-Capabilities: [`keys.provider`](../common/keys.md#symbol-SigningKeys.provider), [`crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa), [`crypto.exportRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.exportRsa).
-
-Can fail with `KeyError`, `CryptoError`. Callers must catch or propagate these errors.
-
-HTTP route: `GET` `/provider/jwks`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-**What it does**
-
-- Set `publicKey` to call [`Crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa) on `crypto` with `key` = call [`SigningKeys.provider`](../common/keys.md#symbol-SigningKeys.provider) on `keys`.
-- Return call [`RsaJwks`](../dependencies/august/0.19.0/crypto/jose.md#symbol-RsaJwks) with `keys` = a list containing call [`rsaJwk`](../dependencies/august/0.19.0/crypto/jose.md#symbol-rsaJwk) with `publicKey` = `publicKey`; `kid` = `"provider-1"`; inject `crypto` from `crypto`.
-
-**Author documentation**
-
-Only the provider's public signing key is published. Session keys never enter this JWKS.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.exportRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.exportRsa) (`publicKey`: `RsaPublicKey`) → `Tuple<Bytes,Bytes>`; can fail with `CryptoError`.
-- [`Crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa) (`key`: `RsaPrivateKey`) → `RsaPublicKey`; can fail with `CryptoError`.
-
-#### [`RsaJwks`](../dependencies/august/0.19.0/crypto/jose.md#symbol-RsaJwks)
-
-Record from `august.crypto`.
-
-- Construct with `keys`: `List<RsaJwk>` → [`RsaJwks`](../dependencies/august/0.19.0/crypto/jose.md#symbol-RsaJwks).
-
-#### [`rsaJwk`](../dependencies/august/0.19.0/crypto/jose.md#symbol-rsaJwk)
-
-Function from `august.crypto`.
-
-- [`rsaJwk`](../dependencies/august/0.19.0/crypto/jose.md#symbol-rsaJwk) (`publicKey`: `RsaPublicKey`, `kid`: `string`) → [`RsaJwk`](../dependencies/august/0.19.0/crypto/jose.md#symbol-RsaJwk); inject `crypto`: [`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto); uses [`crypto.exportRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.exportRsa); can fail with `CryptoError`.
-
-#### [`KeyError`](../common/keys.md#symbol-KeyError)
-
-Class from `common`.
-
-Used as a type or provider.
-
-#### [`SigningKeys`](../common/keys.md#symbol-SigningKeys)
-
-Capability interface from `common`.
-
-- [`SigningKeys.provider`](../common/keys.md#symbol-SigningKeys.provider) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
-
-#### [`Settings`](../common/settings.md#symbol-Settings)
-
-Record.
-
-- Read `issuer` (`string`).
-
-#### [`settings`](../common/settings.md#symbol-settings)
-
-Function from `common`.
-
-- [`settings`](../common/settings.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.md#symbol-Settings).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto) ([`exportRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.exportRsa) and [`publicRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.publicRsa)), [`RsaJwks`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-RsaJwks), and [`rsaJwk`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-rsaJwk) from `crypto`. It uses [`KeyError`](../common/keys.md#symbol-KeyError), [`SigningKeys`](../common/keys.md#symbol-SigningKeys) ([`provider`](../common/keys.md#symbol-SigningKeys.provider)), and [`settings`](../common/settings.md#symbol-settings) from `common`. It uses [`Settings`](../common/settings.md#symbol-Settings) (`issuer`).
 
 ::::
 

package/docs/examples/oidc-login/provider/export.md

@@ -49,6 +49,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 AuthorizationRequest from contracts
 export AuthorizationCode from contracts
 export AccessGrant from contracts
@@ -65,6 +66,7 @@ export userinfo from userinfo
 ```
 
 ```aug [Braces]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export AuthorizationRequest from contracts
 export AuthorizationCode from contracts
 export AccessGrant from contracts
@@ -88,43 +90,15 @@ export userinfo from userinfo
 
 ## 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
-
-- Export `AuthorizationRequest` from this folder.
-- Export `AuthorizationCode` from this folder.
-- Export `AccessGrant` from this folder.
-- Export `IdClaims` from this folder.
-- Export `TokenResponse` from this folder.
-- Export `UserInfo` from this folder.
-- Export `Discovery` from this folder.
-- Export `discovery` from this folder.
-- Export `jwks` from this folder.
-- Export `authorize` from this folder.
-- Export `providerLogin` from this folder.
-- Export `token` from this folder.
-- Export `userinfo` from this folder.
-
-### Folder exports
-
-- Export the declaration `AuthorizationRequest` from [`contracts.aug`](contracts.md#symbol-AuthorizationRequest).
-- Export the declaration `AuthorizationCode` from [`contracts.aug`](contracts.md#symbol-AuthorizationCode).
-- Export the declaration `AccessGrant` from [`contracts.aug`](contracts.md#symbol-AccessGrant).
-- Export the declaration `IdClaims` from [`contracts.aug`](contracts.md#symbol-IdClaims).
-- Export the declaration `TokenResponse` from [`contracts.aug`](contracts.md#symbol-TokenResponse).
-- Export the declaration `UserInfo` from [`contracts.aug`](contracts.md#symbol-UserInfo).
-- Export the declaration `Discovery` from [`discovery.aug`](discovery.md#symbol-Discovery).
-- Export the declaration `discovery` from [`discovery.aug`](discovery.md#symbol-discovery).
-- Export the declaration `jwks` from [`discovery.aug`](discovery.md#symbol-jwks).
-- Export the declaration `authorize` from [`authorization.aug`](authorization.md#symbol-authorize).
-- Export the declaration `providerLogin` from [`authorization.aug`](authorization.md#symbol-providerLogin).
-- Export the declaration `token` from [`token.aug`](token.md#symbol-token).
-- Export the declaration `userinfo` from [`userinfo.aug`](userinfo.md#symbol-userinfo).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+### Exports
+
+Export the declaration `AuthorizationRequest` from [`contracts.aug`](contracts.md#symbol-AuthorizationRequest). Export the declaration `AuthorizationCode` from [`contracts.aug`](contracts.md#symbol-AuthorizationCode). Export the declaration `AccessGrant` from [`contracts.aug`](contracts.md#symbol-AccessGrant). Export the declaration `IdClaims` from [`contracts.aug`](contracts.md#symbol-IdClaims).
+
+Export the declaration `TokenResponse` from [`contracts.aug`](contracts.md#symbol-TokenResponse). Export the declaration `UserInfo` from [`contracts.aug`](contracts.md#symbol-UserInfo). Export the declaration `Discovery` from [`discovery.aug`](discovery.md#symbol-Discovery). Export the declaration `discovery` from [`discovery.aug`](discovery.md#symbol-discovery).
+
+Export the declaration `jwks` from [`discovery.aug`](discovery.md#symbol-jwks). Export the declaration `authorize` from [`authorization.aug`](authorization.md#symbol-authorize). Export the declaration `providerLogin` from [`authorization.aug`](authorization.md#symbol-providerLogin). Export the declaration `token` from [`token.aug`](token.md#symbol-token).
+
+Export the declaration `userinfo` from [`userinfo.aug`](userinfo.md#symbol-userinfo).
 
 ::::