@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/releasing.md

@@ -5,7 +5,7 @@ All first-party packages and the extension use one compiler-compatible version.
 ## Verify and create artifacts
 
 ```sh
-node scripts/version.mjs 0.19.0
+node scripts/version.mjs 0.20.1
 npm ci
 npm --prefix vscode ci
 node scripts/bootstrap-native.mjs
@@ -18,6 +18,8 @@ npm run package:packages
 npm run test:packages -- --native
 npm run package:extension
 node scripts/release-artifacts.mjs
+node scripts/publish-release.mjs dist/release --verify-only
+node scripts/publish-extension.mjs dist/release --verify-only
 ```
 
 Update both changelogs and relevant guides, and commit regenerated docs. The final artifact step combines four installable npm tarballs, a VSIX, offline documentation, package metadata and SHA-256 checksums under `dist/release`. It excludes native caches, private credentials and application build output.
@@ -27,15 +29,21 @@ Update both changelogs and relevant guides, and commit regenerated docs. The fin
 After verification and committing, create and push the version tag:
 
 ```sh
-git tag v0.19.0
-git push origin main v0.19.0
+git tag v0.20.1
+git push origin main v0.20.1
 ```
 
-`release.yml` validates the tag against every manifest, runs compiler/native/docs/package gates, and uploads artifacts to a **draft prerelease**. Review the draft and publish it in GitHub Releases. `ci.yml` checks pushes and pull requests. Linux CI builds the pinned full native stack, runs the native suite, and executes core and crypto apps in the matching runtime image. macOS CI runs the same native suite with its private bootstrap.
+`release.yml` validates the tag against every manifest, runs compiler/native/docs/package gates, and uploads artifacts to a **draft prerelease**. Review the draft and publish it in GitHub Releases. Publishing starts **Publish npm packages** and **Publish VS Code extension** automatically. Each workflow deploys the archives attached to that release. Changing an asset after review invalidates its checksum.
+
+`ci.yml` checks pushes and pull requests. Linux CI builds the pinned full native stack, runs the native suite, and executes core and crypto apps in the matching runtime image. macOS CI runs the same native suite with its private bootstrap.
+
+The automatic publishers are included starting with `v0.20.1`. Existing tags keep their original workflows; the `v0.20.0` draft does not contain these scripts.
+
+The manually published Marketplace `0.19.0` contains files that differ from the VSIX attached to the `v0.19.0` GitHub release. It is not a matching deployment of that archive. Use a new version for the first automated extension release; do not bypass the content comparison to skip an older mismatch.
 
 ## npm publication
 
-The intended scope is `@greenpandastudios`. Claim this npm identity or choose an owned scope consistently before the first registry release. Create the initial packages with the owner's authenticated npm account. GitHub tarballs work independently of registry setup.
+The packages use the `@greenpandastudios` npm scope. Verify ownership and each package's trusted publisher before a release. GitHub tarballs can also be installed directly.
 
 Configure a trusted publisher for each of the four npm packages:
 
@@ -47,19 +55,17 @@ Configure a trusted publisher for each of the four npm packages:
 
 Use npm CLI 11.5.1+ and GitHub-hosted runners. The workflow grants `id-token: write` for OIDC and needs no stored npm publishing token. Match package repository URLs to this repository. See [npm's trusted publisher instructions](https://docs.npmjs.com/trusted-publishers/).
 
-Publishing a reviewed GitHub release automatically runs **Publish npm packages**. To retry, dispatch that workflow with the existing verified version tag. It checks out that tag, checks types/docs/installed artifacts, then publishes standard library, web, crypto and CLI in dependency order with public access and the `next` dist tag. The `npm` environment can hold owner-configured release protection. Existing versions cannot be overwritten; inspect partial runs before retrying.
+The job downloads the four reviewed tarballs, `packages.json` and `SHA256SUMS`. It checks every archive's SHA-256 and SHA-512 integrity, exact version and complete manifest against the tagged source before publishing anything. It checks all existing registry versions, then publishes standard library, web, crypto and CLI in that order with public access and the `next` dist tag. Lifecycle scripts are disabled. No rebuild or dependency installation runs in the npm deployment job.
 
-## VS Code Marketplace
+Retries skip a version only when its registry integrity matches the release archive. A registry failure or a different published archive stops deployment. Each new publication is checked against the registry before proceeding. The CLI is published last because its dependencies use exact matching versions. An interrupted run can leave some libraries published; retry the same release to finish. Retries leave already-published versions and their dist tags alone. This pipeline publishes preview packages to `next`; promoting a release to `latest` remains a separate maintainer decision.
 
-Confirm ownership of the `augscript` Marketplace publisher. Publishing a reviewed GitHub release runs **Publish VS Code extension** (`publish-marketplace.yml`); manual dispatch accepts the same published tag for retries. It downloads the release's VSIX, verifies its SHA-256 checksum, version and `augscript.augscript` identity, then publishes that exact artifact. VSIX files remain available directly from GitHub Releases.
+## VS Code Marketplace
 
-One-time owner setup follows [Microsoft's secure publishing guide](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#secure-automated-publishing-to-visual-studio-marketplace):
+The extension identity is `augscript.augscript`. An owner of the `augscript` publisher must configure a Marketplace trusted publishing policy for `GreenPandaStudios/augscript`, workflow `publish-extension.yml` and the `marketplace` deployment environment. VSCE 4.0.0 supports `vsce publish --oidc` on GitHub Actions; the workflow requests a short-lived credential and does not use a stored PAT or an Azure subscription. See [the shipping VSCE trusted publishing instructions](https://github.com/microsoft/vscode-vsce/blob/v4.0.0/README.md#trusted-publishing). Account-side trust must be configured before the first deployment; adding a workflow does not grant publisher access.
 
-- Create a Microsoft Entra identity and grant it publishing access to the `augscript` Marketplace publisher.
-- Add a GitHub federated credential with issuer `https://token.actions.githubusercontent.com`, audience `api://AzureADTokenExchange`, and subject `repo:GreenPandaStudios/augscript:environment:marketplace`.
-- Create the GitHub environment `marketplace` and set its variables `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` to that identity's IDs. Configure release protection there if needed.
+The preparation job downloads the reviewed VSIX, verifies its checksum, complete manifest, logo and bundled compiler, and installs the locked publishing tool with lifecycle scripts disabled. It passes these files to a separate `marketplace` job with OIDC permission. That job rechecks the VSIX and publishes it with `--packagePath`, so publication does not build another extension or run `vscode:prepublish`.
 
-The workflow uses Azure login through OIDC and the pinned `vsce` CLI's `--azure-credential` support. No publishing token is stored. The first public listing requires the publisher identity setup; the repository does not establish ownership of a Marketplace namespace. The intended listing is [AugScript](https://marketplace.visualstudio.com/items?itemName=augscript.augscript), currently unpublished.
+For retries, the publisher downloads an existing Marketplace version and compares all files under `extension/` with the reviewed VSIX. Marketplace signature metadata outside that directory may differ. A changed, missing or additional extension file stops the retry. After uploading, the job downloads and verifies the published version, allowing roughly a minute for indexing. If confirmation still fails after an upload, wait for the version to become available and retry. VSIX files remain available from GitHub for direct installation.
 
 The packaging script supplies the repository's `vscode` directory as the HTTPS
 base for README images. Verify those URLs are public before Marketplace
@@ -68,7 +74,15 @@ users. The extension logo and **AugScript: Open Welcome** images are bundled
 locally and do not depend on that image host. To update artwork, run
 `npm --prefix vscode run artwork` and commit the rendered PNGs.
 
-Global Azure DevOps PATs retire on December 1, 2026; this project does not introduce a new long-lived Marketplace PAT. Marketplace identity setup is an external owner prerequisite.
+## Deployment protection and retries
+
+Configure GitHub environments named `npm` and `marketplace`. Allow only tags matching `v*`; use required reviewers if your release process needs another approval. Keep the npm environment name identical to each package's trusted publisher configuration, and the Marketplace policy aligned with its workflow and environment. See [GitHub's environment protection guide](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment). Restrict who can create or move release tags through repository rules.
+
+Both workflows also accept a manual retry. Open the appropriate workflow in Actions, select the release tag as the workflow ref, and enter the same tag in the `tag` input. A branch ref, mismatched version, draft release or tag moved since the run began is rejected before publication. The tag must contain these publishing workflows and scripts. Re-running the failed job on its original run also retains the exact tagged source. npm and Marketplace have separate concurrency groups and deployment environments, so a failure at one destination can be retried independently.
+
+Release creation uses the repository's `GITHUB_TOKEN` to create a draft. A maintainer must publish that draft through GitHub Releases or their own authorized GitHub CLI session. Events produced only by `GITHUB_TOKEN` do not start another workflow; do not replace this review step with a token-authenticated automatic publish unless you also add an explicit deployment handoff. See [GitHub's workflow trigger rules](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow).
+
+If npm reports an authentication failure, check all four package connections, their exact workflow/environment spelling, permission for direct `npm publish`, and OIDC permission. For a Marketplace failure, check the publisher policy and `marketplace` environment. Do not place credentials in workflow files or release assets. The scripts distinguish missing versions from authorization and service errors; investigate the reported error before retrying.
 
 ## Documentation deployment
 
@@ -76,4 +90,4 @@ Enable GitHub Pages with **GitHub Actions** as its publishing source. `docs.yml`
 
 ## Current limits
 
-August is experimental. Native web/crypto bootstrap supports macOS and Linux; other platforms are unverified. Registry and Marketplace identities require owner configuration. User-authored source packages are supported through npm transport; prebuilt native dependency releases and a stable external native adapter ABI remain future work. See [the gap ledger](web-library-gaps.md) and [performance assessment](performance.md).
+August is experimental. Native web/crypto bootstrap supports macOS and Linux; other platforms are unverified. npm and Marketplace deployment require owner-configured trust; a live upload has not yet verified the new Marketplace workflow. User libraries can use public Git repositories, local folders, or npm archives. Prebuilt native dependency releases and a stable external native adapter ABI remain future work. See [the gap ledger](web-library-gaps.md) and [performance assessment](performance.md).

package/docs/research/code-to-natural-language.md

@@ -0,0 +1,108 @@
+# Research: deterministic prose from source code
+
+Research date: 2026-09-29. This note supports August's compiled specifications: connected prose describing local implementation behavior, with references to the dependency surfaces that the implementation actually uses. It records research evidence and proposed engineering choices; it is not an implementation status report.
+
+## Findings that matter for August
+
+A practical approach is to generate text from explicit program facts through document planning, sentence planning, and realization. Classic NLG separates content determination, discourse planning, aggregation, lexicalization, reference generation, and realization [1]. McBurney and McMillan apply these ideas to code, including fixed message ordering and rules that combine related phrases [5]. This provides a stronger starting point than emitting an independent template for each syntax node.
+
+Aggregation can reduce repeated subjects and predicates while retaining the facts being communicated. Dalianis and Hovy explicitly distinguish repackaging facts from dropping selected information, and restrict reordering to zones where ordering is free [8]. For program explanations, that restriction matters: execution order, branch scope, mutation, and error behavior cannot be treated as freely reorderable facts.
+
+Program names provide useful linguistic hints. They do not establish a function's semantics. SWUM represents action, theme, and argument relationships in names and signatures [3]. The parameter-comment work combines these clues with control flow and data dependencies and acknowledges limitations from uninformative names and abbreviations [4]. August should establish behavioral claims from its compiler representations before choosing wording.
+
+Context can help explain how a function fits into its program. The context-summary research uses call relationships and output uses [5, 6]. Its relevance ranking deliberately selects a small subset of context, and its evaluations concern summaries. It does not demonstrate generation of a complete executable or behavioral specification.
+
+## Primary literature reviewed
+
+Entries report what each source supports, followed by the limit relevant to this task. Sources are linked to the paper or its publisher/author copy. Full text was inspected where available; the two abstract-only entries are marked explicitly.
+
+### 1. Reiter and Dale, 1997: the generation pipeline
+
+Ehud Reiter and Robert Dale. *Building Applied Natural Language Generation Systems*. Natural Language Engineering 3(1), 57–87, March 1997. [Publisher record and abstract](https://www.cambridge.org/core/journals/natural-language-engineering/article/abs/building-applied-natural-language-generation-systems/FEB374A3FF652F06D8567A6FAB2EF36E), [author-hosted PDF](https://web.science.mq.edu.au/~rdale/publications/papers/1997/jnle97.pdf). DOI: 10.1017/S1351324997001502.
+
+The paper identifies content determination, discourse planning, sentence aggregation, lexicalization, referring expression generation, and linguistic realization as distinct tasks in applied NLG. Its stated emphasis is techniques suitable for practical systems. This gives August a vocabulary for separating semantic extraction from paragraph structure and wording. **Access limit:** the publisher abstract was read; author PDF fetching failed during this review. Detailed pipeline mechanics are additionally supported by the full-text implementation in [5]. The paper is architectural guidance, not a proof of specification completeness or reproducibility.
+
+### 2. Sridhara et al., 2010: method summary comments
+
+Giriprasad Sridhara, Emily Hill, Divya Muppaneni, Lori Pollock, and K. Vijay-Shanker. *Towards Automatically Generating Summary Comments for Java Methods*. ASE 2010, 43–52, September 2010. [Publication DOI](https://doi.org/10.1145/1858996.1859006), [paper abstract](https://www.researchgate.net/publication/220883580_Towards_automatically_generating_summary_comments_for_Java_methods).
+
+The authors describe deriving descriptive method summaries from method signatures and bodies, and report programmer judgments of accuracy, important content, and conciseness. This is directly relevant precedent for source-based comment generation. **Access limit:** only the original paper's abstract was accessible; the publisher rejected access and the linked repository copy was unavailable. Implementation details should not be attributed to an independently read full text here. The later full-text papers [4, 5] discuss its selection of important statements. Neither favorable summary judgments nor selecting important content establishes that every behavior is explained.
+
+### 3. Hill, Pollock, and Vijay-Shanker, 2011: linguistic roles in code
+
+Emily Hill, Lori Pollock, and K. Vijay-Shanker. *Improving Source Code Search with Natural Language Phrasal Representations of Method Signatures*. ASE 2011, November 6–10, 2011. DOI: 10.1109/ASE.2011.6100115. [Author-uploaded full text](https://www.researchgate.net/publication/220883654_Improving_source_code_search_with_natural_language_phrasal_representations_of_method_signatures).
+
+The paper uses SWUM to derive action, theme, secondary argument, and auxiliary argument roles. Its search score incorporates word location, role, distance from a phrase's head, and usage. The evaluation covers eight search tasks from four Java programs. Phrasal structure can distinguish adding an auction from adding an auction link. This supports keeping noun phrases and argument roles intact during wording. Its empirical result concerns search relevance, not generated documentation accuracy; the authors discuss limited generalization beyond Java. August's symbol resolution must establish what is called, independently of lexical heuristics.
+
+### 4. Sridhara, Pollock, and Vijay-Shanker, 2011: parameters in context
+
+Giriprasad Sridhara, Lori Pollock, and K. Vijay-Shanker. *Generating Parameter Comments and Integrating with Method Summaries*. ICPC 2011, 71–80. DOI: 10.1109/ICPC.2011.28. [Full paper](https://www.cs.kent.edu/~jmaletic/cs63902/Papers/Pollock11.pdf).
+
+This method-local approach combines control flow, control and data dependencies, def-use chains, and SWUM information to identify a parameter's main role and connect it to the method's computation. It supports parameter comments and integration into method summaries. Nine experienced developers evaluated the results. The authors explicitly describe reduced readability and analysis accuracy from abbreviations and a dependence on meaningful identifiers. The approach emphasizes primary usage, so it does not justify omitting secondary parameter uses when August promises comprehensive local behavior.
+
+### 5. McBurney and McMillan, 2014: readable method context
+
+Paul W. McBurney and Collin McMillan. *Automatic Documentation Generation via Source Code Summarization of Method Context*. ICPC 2014, 279–290, June 2–3, 2014. [Author-hosted full paper](https://sdf.org/~cmc/papers/mcburney_icpc_2014.pdf).
+
+The technique combines call graphs, PageRank-selected contextual methods, SWUM, and a custom NLG pipeline. Its document plan uses predefined message ordering; aggregation combines related phrases and suppresses repeated subjects and verbs. A study with twelve Java programmers evaluates understanding of internal behavior, purpose, and usage. This is particularly useful evidence that rule-driven code descriptions can form connected sentences. However, it selects only some context and uses simplifying assumptions about names and outputs. Its context descriptions are clues about role, not verified design intent or an exhaustive dependency contract.
+
+### 6. McBurney and McMillan, 2015 accepted manuscript: stronger comparison
+
+Paul W. McBurney and Collin McMillan. *Automatic Source Code Summarization of Context for Java Methods*. IEEE Transactions on Software Engineering, accepted manuscript bearing 2015 copyright and DOI 10.1109/TSE.2015.2465386. [Full accepted manuscript](https://sdf.org/~cmc/papers/mcburney_tse15.pdf).
+
+This extension compares context summaries with expert summaries and an existing automatic summarizer. Its conclusion reports better contextual information than manual summaries, while human summaries were more accurate and concise; combining generated context with existing summaries improved documentation. This qualifies the earlier results: useful context does not imply human-level overall quality. The linked copy is a prepublication manuscript, so 2015 here identifies that manuscript rather than asserting the final issue's publication year. These studies are from the same research line and should not be counted as independent replications.
+
+### 7. Reiter, Mellish, and Levine, 1995: documentation and links
+
+Ehud Reiter, Chris Mellish, and John Levine. *Automatic Generation of Technical Documentation*. Applied Artificial Intelligence 9, 259–287, 1995; preprint submitted November 1994. [Full preprint](https://arxiv.org/pdf/cmp-lg/9411031), [version metadata](https://arxiv.org/abs/cmp-lg/9411031).
+
+The IDAS work generates documentation from domain knowledge and linguistic/contextual models, including hypertext nodes and links. It discusses the expense of adding information absent from existing design databases and checking whether generated language faithfully reflects the knowledge base. This supports retaining explicit facts and structured references as generator input. It also shows why the quality of the underlying model constrains the text. IDAS concerns equipment help and tailored documentation, not compiler extraction from arbitrary programs; it does not solve August's dependency selection problem.
+
+### 8. Dalianis and Hovy, 1993 workshop version: aggregation
+
+Hercules Dalianis and Eduard Hovy. *Aggregation in Natural Language Generation*. EWNLG 1993 workshop version, later a chapter in *Trends in Natural Language Generation*. [Author-hosted manuscript](https://people.dsv.su.se/~hercules/papers/EGEN_Aggregation_NLG_1996.pdf).
+
+The manuscript identifies aggregation operations from a small telephone-domain study, including grouping shared subjects and predicates. It distinguishes reducing redundancy from entirely omitting information chosen for communication. Its ordering discussion confines rearrangement to free-order zones in a discourse structure. Twelve participants completed the questionnaire; nine produced aggregated text. This provides concrete rules for turning repeated factual sentences into paragraphs. Its small constrained domain and assumptions about discourse structure limit generalization. The manuscript's heading identifies the 1993 workshop version; the filename should not be used as publication metadata.
+
+### 9. Dalianis, 1995: aggregation for formal specifications
+
+Hercules Dalianis. *Aggregation in the NL-generator of the Visual and Natural Language Specification Tool*. EACL 1995, 286–290. [Full paper](https://aclanthology.org/E95-1042.pdf).
+
+VINST paraphrases formal information through naturalization, compacting, and surface grammar stages. The paper describes repeated noun phrase removal and proposes predicate grouping and a bidirectional grammar to improve tedious fact-base descriptions. This is an unusually close precedent for readable natural language from a formal specification representation. The discussion concerns a telecom specification prototype and a proposed architecture improvement, not an empirical demonstration that all program behaviors can be paraphrased without ambiguity. Use its representation-oriented approach while verifying August's individual language constructs.
+
+### 10. Gatt and Reiter, 2009: realization under developer control
+
+Albert Gatt and Ehud Reiter. *SimpleNLG: A Realisation Engine for Practical Applications*. ENLG 2009, 90–93, March 30–31, 2009. [Full paper](https://aclanthology.org/W09-0613.pdf).
+
+SimpleNLG separates tactical linguistic choices from mechanical syntax, morphology, and linearization. Developers retain control over how semantic inputs map to phrase structures; the engine supports mixed canned and constructed text. This supports a small controlled realization layer handling coordination, agreement, inflection, and punctuation. It does not choose which source-code facts are true or complete. August need not adopt the Java library: the architectural separation is useful in a TypeScript compiler, and byte-identical output remains an engineering requirement to verify separately.
+
+### 11. Roy, Fakhoury, and Arnaoudova, 2021: evaluation metrics
+
+Devjeet Roy, Sarah Fakhoury, and Venera Arnaoudova. *Reassessing Automatic Evaluation Metrics for Code Summarization Tasks*. ESEC/FSE 2021, 1105–1116, August 23–28, 2021. DOI: 10.1145/3468264.3468588. [Author-hosted full paper](https://veneraarnaoudova.com/wp-content/uploads/2021/09/2021-FSE-CR-Reassessing-Automatic-Evaluation-Metrics-for-Code-Summarization-Tasks.pdf).
+
+A study with 226 human annotators compares automatic metrics and human summary judgments. In its setting, improvements below two metric points do not reliably indicate quality improvements, and corpus BLEU remains unreliable for some larger differences. This argues against treating lexical overlap as the acceptance gate for August's prose. These observations concern the studied datasets and summarizers; they are not universal numerical thresholds. August needs direct semantic coverage checks and reader comprehension judgments, as separate dimensions.
+
+### 12. Nie et al., 2022: evaluation should match use
+
+Pengyu Nie, Jiyang Zhang, Junyi Jessy Li, Ray Mooney, and Milos Gligoric. *Impact of Evaluation Methodologies on Code Summarization*. ACL 2022, 4936–4960, May 2022. DOI: 10.18653/v1/2022.acl-long.339. [Full paper](https://aclanthology.org/2022.acl-long.339.pdf).
+
+The authors compare mixed-project, cross-project, and time-segmented evaluation of learned code summarizers. Different splits can lead to conflicting conclusions, and the paper maps evaluation methods to intended use cases. This is chiefly relevant if August later adds learned lexical or summary components. Its broader lesson motivates representative acceptance examples and revisions of real programs. A deterministic rule generator has no training leakage in the same sense, so the paper's machine-learning results should not be presented as direct evidence of August's quality.
+
+## Proposed engineering choices for August
+
+These are recommendations derived from the requirements and the literature, not findings that the papers prove or claims that the current generator implements them.
+
+1. Extract an immutable behavior representation from resolved compiler structures. Each fact should retain its construct identity, lexical scope, source location, guard, ordering relation, and involved symbols. Represent bindings, calculations, calls, returns, mutation, loops, pattern alternatives, cleanup, capabilities, and checked errors explicitly.
+2. Plan documents by module and declaration, and explain each body in its actual control structure. A declaration overview can precede its detailed behavior; branches and repeated actions should remain recognizable in paragraphs. Paragraph breaks are useful boundaries for changes in scope or topic.
+3. Aggregate adjacent compatible clauses. Combine shared subjects or predicates, introduce a value once, and use unambiguous references afterward. Keep quantified repetition, negation, mutually exclusive alternatives, and early returns explicit. Repeated calls are distinct events even when their text matches.
+4. Use a controlled lexicon and grammar. Render equality, assignment, comparison, indexing, conditional execution, iteration, and error propagation with stable terminology. Treat names as names; retain an identifier or a precise source fragment when linguistic expansion would guess its meaning.
+5. Derive dependency surfaces from resolved usage: called declarations, referenced values, accessed members, referenced types and constructors. Imports alone do not prove a surface is used. Aliases must resolve to their original declaration. Define separately whether type-only usage belongs in the dependency section.
+6. Link a dependency at its use and provide one canonical description of its used contract. Explain local call arguments, return handling, state changes, and failure handling locally. Avoid recursively narrating an entire dependency implementation. If symbol resolution or documentation is unavailable, state that boundary explicitly without inventing behavior.
+7. Make determinism explicit: fixed traversal and ordering, fixed grammar rules, canonical links, no random variation or remote generation, and no timestamps or environment-specific paths in the output. Equal compiler inputs and generator version should produce equal bytes. This is a project contract requiring tests, not a research guarantee.
+8. Preserve a coverage ledger through planning and aggregation. Every required source fact must be realized or deliberately accounted for. Aggregated clauses should retain all contributing fact identities. This makes missing local behavior inspectable without forcing one sentence per AST node.
+
+## Validation criteria
+
+Use independent gates for factual coverage, faithfulness, readable prose, dependency scope, valid links, and reproducibility. Representative fixtures should include nested alternatives, early exit, loops, local mutation, errors, callbacks, aliases, overloaded or ambiguous references, type-only dependencies, and repeated effects. A sentence snapshot alone cannot prove behavior coverage.
+
+For prose quality, ask readers to recover inputs, outputs, branching, state changes, errors, and the role of dependencies from the generated document. Review sentence-level truth separately from paragraph coherence and excessive detail. The literature supports these as useful evaluation directions; it does not establish that a compiled prose document replaces executable semantics, formal verification, domain requirements, or handwritten explanations of design intent.

package/docs/research/ecosystem-workflow.md

@@ -0,0 +1,41 @@
+# Project creation, Git packages, and editor help
+
+Research checked September 30, 2026. This note separates behavior documented by the source projects from recommendations for August. Proposed commands and import forms below are design examples, not a claim that they are implemented.
+
+## What to borrow from Go
+
+Go lets an author distribute a module through its source repository. The module path identifies its location, and release tags identify versions. Consumers can discover dependencies from their imports and fetch the source into a cache. A repository can contain several modules, although one module at its root is the simpler authoring path. [Go: managing module source](https://go.dev/doc/modules/managing-source)
+
+Go accepts revision queries such as a branch or commit at the command line, then records a canonical version. Its pseudo-versions preserve a particular revision when no release tag exists. Modules can live in repository subdirectories, with a corresponding tag prefix. Cached source is checked against hashes; Go also has a public checksum database. These are separate mechanisms: storing a hash locally does not establish the publisher's identity or reproduce that database's protections. [Go modules reference](https://go.dev/ref/mod#versions), [module subdirectories](https://go.dev/ref/mod#vcs-dir), [module authentication](https://go.dev/ref/mod#authenticating)
+
+Publishing a Go release includes testing, creating a new version tag, and pushing it. Its documentation tells authors to publish a new version rather than change an existing release. [Go: publishing a module](https://go.dev/doc/modules/publishing)
+
+**Recommendation for August:** make a public HTTPS Git repository enough to share a library. An author should need August source, `export.aug`, one August manifest, a license, and a release tag. Keep npm archives as an additional transport, without requiring an npm account or a duplicate npm manifest for Git packages. Teach one ordinary author-to-consumer path before explaining transport alternatives.
+
+For consumers, put the location where the dependency is used. A quoted source such as `import add from "https://github.com/example/math#v0.1.0"` is one possible form. A short package alias can remain useful when many files import the same library; let a command generate its configuration instead of making the reader maintain the mapping by hand. Avoid spelling the same URL and version in both source and configuration unless they serve different purposes.
+
+Resolve a tag or branch to an exact commit during installation, and retain that commit, the selected repository subdirectory, and a source digest in `aug.lock.json`. A matching lock should restore that snapshot rather than follow a moved branch. Make dependency updates explicit. Continue to keep ordinary checking read-only and let `aug run` prepare missing snapshots. Distinguish “available offline” from “first download verified against a previously trusted digest.”
+
+Git can list a remote's references and object IDs without a working-tree checkout. Annotated tags have both tag and peeled-object entries, so the resolver must retain the commit target. [Git: ls-remote](https://git-scm.com/docs/git-ls-remote)
+
+Use subprocess argument arrays, validate repository paths and revision selectors, and disable dependency hooks. Preserve August's source-boundary and symlink checks. These are implementation recommendations, not security guarantees supplied by Go.
+
+Move optional August libraries through the same consumer path, using actual package directories in the existing public repository. Keep compiler/runtime primitives in the toolchain. The migration must retain native adapter compatibility and make the weather starter work from an installed CLI without a language-repository checkout.
+
+## The familiar weather API
+
+Microsoft's ASP.NET Core web API template provides `GET /weatherforecast`. Its minimal API implementation returns five forecasts with a date, Celsius temperature, summary, and computed Fahrenheit temperature. It generates simulated values, rather than calling a weather provider. Startup, the route, and the response record are visible in its generated `Program.cs`. OpenAPI registration and its development endpoint are included when enabled. [Microsoft's minimal API template source](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/WebApi-CSharp/Program.MinimalAPIs.WindowsOrNoAuth.cs)
+
+Microsoft's onboarding creates a project, runs it, opens the forecast route, and inspects the returned JSON. The tutorial also explains the generated OpenAPI document. [Microsoft: create a web API](https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-10.0)
+
+**Recommendation for August:** offer a weather template through the installed CLI and npx, then continue with `aug run`. Keep the recognizable route and response fields. Use deterministic sample forecasts so the guide, tests, and compiled explanation agree. Say plainly that the data is simulated. Put startup in `main.aug`, the typed response and forecast operation beside their tests, and the endpoint in a nearby file if separating it helps the lesson. Include an HTTP request file, the expected JSON, OpenAPI configuration, and `AGENTS.md` with the project's own checking/spec commands. Demonstrate one change and its test after the initial successful request.
+
+## Completion and suggested fixes
+
+VS Code completion items accept a `SnippetString`, explicit replacement ranges, documentation, and sorting/filtering text. Additional text edits can insert an import when a completion is accepted; they must not overlap the main edit or one another. Set sorting and insertion fields in the initial result, because resolving an item later must not change them. [VS Code API: CompletionItem](https://code.visualstudio.com/api/references/vscode-api#CompletionItem)
+
+Code actions should apply to the requested range. A quick fix can carry its diagnostic, a workspace edit, and `isPreferred` when it resolves the underlying problem. Providers should declare their supported action kinds so VS Code can avoid unnecessary requests. [VS Code API: CodeAction](https://code.visualstudio.com/api/references/vscode-api#CodeAction), [CodeActionProvider](https://code.visualstudio.com/api/references/vscode-api#CodeActionProvider)
+
+Snippets appear in IntelliSense and the snippet picker. `editor.tabCompletion` enables insertion from a typed prefix, and numbered placeholders allow navigation through editable fields. [VS Code: snippets](https://code.visualstudio.com/docs/editing/userdefinedsnippets)
+
+**Recommendation for August:** rank visible locals and members first, offer named argument placeholders, complete import paths and public exports, and attach Javadoc to suggestions. Add context-specific snippets for records, interfaces, implementations, endpoints, tests, error handling, tasks, and ownership scopes in the project's chosen block style. Offer fixes for misspelled visible names, missing public imports, mislabeled arguments, and absent interface members. A fix must make the program more correct; an “Explain error” action is useful help but should not be presented as a repair. Exercise these workflows against unsaved and incomplete source, since that is where users invoke completion.

package/docs/research/wiki-editorial-design.md

@@ -0,0 +1,71 @@
+# Wiki editorial design research
+
+Retrieved: 2026-09-30. Scope: public language documentation architecture and prose; this note does not establish AugustScript's implementation capabilities or comparative performance.
+
+## Primary source observations
+
+The Rust book introduces the language's purpose, identifies its readers, states that readers should already know another programming language, and explains a sequential learning path. Its chapters alternate concepts with small projects; its introduction also explains how deliberately failing examples are labeled. These are useful mechanisms for setting expectations before the reader encounters unfamiliar rules. [Rust book introduction](https://doc.rust-lang.org/book/ch00-00-introduction.html)
+
+The C About page opens with a small program, explains the language's history and common uses, and links to learning resources and the standards committee. Its compact presentation connects a concrete language sample to purpose and provenance. This observation concerns the page's editorial structure, not independent verification of its historical or adoption claims. [C About](https://www.c-language.org/about)
+
+Diátaxis distinguishes tutorials, task-oriented how-to guides, technical reference, and explanation according to the reader's needs. It recommends organizing documentation around these different needs. [Diátaxis](https://diataxis.fr/)
+
+For tutorials, Diátaxis recommends an achievable practical goal, small concrete actions, visible results early, expected output, and a dependable path. It advises moving extended explanations and alternative choices out of the immediate lesson. [Diátaxis tutorials](https://diataxis.fr/tutorials/)
+
+For reference, Diátaxis recommends precise descriptions, consistent patterns, an organization corresponding to the product, and examples that illustrate usage. It explicitly recognizes generated API documentation as useful for fidelity while distinguishing it from a complete documentation system. [Diátaxis reference](https://diataxis.fr/reference/)
+
+Google's developer style guide recommends conversational, respectful prose, active voice, second person, descriptive links, and conditions stated before instructions. It advises against announcing unreleased functionality in documentation. [Google style highlights](https://developers.google.com/style/highlights)
+
+Google's tone guidance emphasizes direct, useful writing for developers who may be in a hurry. It discourages buzzwords, filler, awkward sentences, and assurances that procedures are easy. Its code-sample guidance recommends introductory context, the relevant project's formatting conventions, readable line lengths, and explicit comments for omitted code. [Google voice and tone](https://developers.google.com/style/tone), [Google code samples](https://developers.google.com/style/code-samples)
+
+Write the Docs recommends explaining the problem a project solves, showing a common small example, providing concise basic installation instructions with links to caveats, and exposing source, issue reporting, support, contribution, and license information. It warns that expanding FAQs can accumulate unrelated material and become difficult to search. [Write the Docs beginner guide](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/)
+
+## Application to AugustScript
+
+The following recommendations are editorial synthesis, not claims made by the sources. The audience supplied for this work is senior engineers and large teams changing unfamiliar modular code with coding agents, with a quick entrance for hobbyists. Agent experiments are still underway: the wiki should present inspectable language mechanisms and examples without claiming that superiority has been proved.
+
+The audit issues to resolve are mixed navigation, dense reference serving as the first lesson, unsupported metrics or broad claims, and a missing progression for learners. These are local editorial concerns, not external research findings.
+
+### Give each reading mode a clear entrance
+
+Use a small public landing page to explain what AugustScript is, the problems its design addresses, how to run a first program, and where to continue. Place a short, implemented example near the opening. Describe the current implementation and material limits plainly; link to detailed status rather than placing a backlog in the main introduction. This recommendation combines C's compact positioning with Write the Docs' practical entry points.
+
+Provide five recognizable documentation areas:
+
+| Area | Reader's purpose | Editorial shape |
+| --- | --- | --- |
+| Learn | Build familiarity with the language | A book-like sequence of lessons and small programs |
+| Guides | Complete a specific task | Prerequisites, actions, expected result, relevant caveats |
+| Reference | Check exact behavior | Consistent language, library, CLI, and configuration entries |
+| Explanation | Understand a design choice | Rationale, tradeoffs, examples, and links to exact contracts |
+| Engineering | Work on AugustScript itself | Compiler/runtime architecture, contribution, releases, documentation maintenance |
+
+The four reader modes adapt Diátaxis; Engineering is a local addition for contributors. Keep product-user learning distinct from instructions for maintaining the repository. A source file or implementation detail belongs in public prose when it helps explain a contract or debug a real problem.
+
+### Build a dependable learning sequence
+
+State the assumed programming background. Begin with installation and a runnable first program, then build toward values and functions, control flow, custom data, modules and public boundaries, errors, and explicit capabilities as supported by the implementation. Use a modest project to connect earlier concepts before presenting advanced reference detail. Treat this sequence as a proposal to validate against actual dependencies between language features.
+
+Each lesson should answer a concrete question, show a complete program or clearly labeled fragment, explain the important behavior, and provide the output or diagnostic the reader should observe. Introduce one unfamiliar idea at a time where practical. Link to the full reference for exhaustive syntax, edge cases, and advanced forms. Deliberately failing programs should say that they fail before the code and explain the diagnostic afterward. Rust's failure labeling and Diátaxis' expectation-setting support these choices.
+
+### Make prose earn trust through evidence
+
+Explain a mechanism and its consequence in ordinary developer language. For example, an account of module boundaries should show what a caller can access and what change is rejected, then explain how that makes an unfamiliar module easier to inspect. Avoid turning design goals into guarantees. Quantitative performance or productivity claims require reproducible evidence and scope; otherwise remove them or describe them as an investigation.
+
+Keep implementation limits next to affected examples and contracts. A centralized readiness page can summarize support, but readers should not need to discover it to learn that the example in front of them cannot run. Clearly distinguish implemented behavior, experimental behavior, and proposed work. Pending approval work must not appear as an available capability.
+
+Use short connected paragraphs, concrete titles, and code identifiers when they identify actual syntax or APIs. Introduce code with its purpose, then explain what to notice. Reserve tables for comparisons and mappings; reserve lists for actual sequences or parallel facts. Concision should remove repetition and filler while preserving the reasoning needed to understand the example.
+
+### Verify the published contract
+
+The local verification recommendation is to execute runnable examples with the documented compiler and CLI, check intended failures, and compare output with the prose. Validate package installation paths as documented, preserve executable-fence metadata, regenerate API and construct pages, and run documentation drift and site checks. Recheck readiness statements against code, tests, and the approved scope. Generated reference and handwritten explanations should agree on terminology and behavior.
+
+Success means a newcomer can reach a working program and understand why it behaves as shown; a returning engineer can locate an exact contract; and a contributor can find implementation instructions without interrupting either journey.
+
+## Installation audit during implementation
+
+The source wiki still said the CLI had not been published. A live `npm view` check on September 30, 2026 found `@greenpandastudios/aug-cli`, `aug-stdlib`, `aug-web`, and `aug-crypto` at 0.19.0; the CLI's `next` and `latest` tags both selected that version and its library dependencies used exact matching versions. The published CLI was installed in a temporary directory and passed starter creation, checking, a native test, execution, spec generation, and read-only drift checking. That smoke run reused the verified native cache and does not by itself establish a fresh host's full web/crypto bootstrap. [CLI registry metadata](https://registry.npmjs.org/@greenpandastudios%2Faug-cli), [standard library](https://www.npmjs.com/package/@greenpandastudios/aug-stdlib), [web library](https://www.npmjs.com/package/@greenpandastudios/aug-web), [crypto library](https://www.npmjs.com/package/@greenpandastudios/aug-crypto)
+
+An additional run used the exact `npx @greenpandastudios/aug-cli@next init` starter, a global installation under a temporary prefix, and an empty temporary native cache. The extraction-only minicoro/yyjson bootstrap, native test, run, spec generation, and drift check all passed. This verifies the book's core onboarding path on the measured macOS host; it does not certify fresh web/crypto builds or other platforms.
+
+The installation lesson now uses available registry commands. The publishing task “Streamline getting started with npx” verified the public starter and matching packages. Its `init` implementation creates files; native source preparation remains explicit. The book now continues through `npx`, and the gallery supplies independent ZIP project archives with their license. A fresh-cache run of the public starter passed checking, execution, tests, spec generation, and drift checking without a global install. Downloaded calculator and neighboring package projects also ran through the public CLI. The standalone Docker recipes installed that CLI, built the complete native dependency set on Linux ARM64, and checked, tested, compiled, and ran the starter in the run image. These checks establish those workflows, not broader platform or service readiness. Contributor benchmark maintenance is separate from application instructions. This is a concrete example of why editorial review must check public claims against live distribution evidence, even when the checked source examples remain valid.

package/docs/roadmap.md

@@ -7,7 +7,7 @@ August's goal is a language that stays understandable as a codebase grows: local
 | 0.19: public preview | Runnable CLI, editor, source packages, wiki, same-file tests, specs, measured benchmarks, and starter projects. | Current CI and [example projects](examples/index.md); experimental label remains. |
 | 0.x: language and ownership | Define and check mutable captures, shared object lifetime, cleanup, delayed errors, and task cancellation for the documented cooperative task model; keep both block styles and specs in sync. | **Open:** the [ownership and task conformance suite](language-conformance.md) covers moves, aliases, branch and nested-scope joins, initialization, return/error exits, collection pressure, and public `Task<T>` errors. [Generated robustness checks](production-readiness.md#what-is-measured-and-verified) now exercise parser recovery, native results, and the core runtime under sanitizers. Adversarial review found additional capture and lifetime gaps after the first green CI run; independent review and wider runtime coverage remain before this gate can close. |
 | 0.x: portable native stack | Reproducible Linux and macOS web/crypto builds; build/run container images for full apps; platform-specific CI. | Versioned dependency manifests, license notices, native integration tests, and matching package builds on each target. |
-| 0.x: developer distribution | Publish version-matched npm packages and VS Code extension; project bootstrap with `npx`; package compatibility and reproducible releases. | Clean installed-package tests, signed/versioned artifacts, release instructions, and supported upgrade path. |
+| 0.x: developer distribution | Publish version-matched npm packages and VS Code extension; project bootstrap with `npx`; package compatibility and reproducible releases. | The [0.19.0 npm packages and core `npx` workflow](packages.md#npm-registry) are verified. The gate also requires clean installed-package tests, signed/versioned artifacts, release instructions, and a supported upgrade path. |
 | 1.0.0 | Freeze the supported language and package/native ABI; publish migration policy and production support matrix. | All preceding gates pass in CI, examples and specs regenerate deterministically, dependency audit and security review pass, and known gaps are classified explicitly. |
 
 HTTP and OIDC hardening are library and application work. They are tracked in the [web and crypto gap ledger](web-library-gaps.md) and are not gates for the language's 1.0 release. The [compatibility policy](compatibility.md) identifies the proposed 1.x contract and platform evidence still required. The [production readiness page](production-readiness.md) explains current use and dependency obligations. Language performance is tracked with [reproducible benchmarks](performance.md), with regressions investigated before a stable release.

package/docs/specifications.md

@@ -16,11 +16,21 @@ aug spec . --check
 | `export.aug` | `export.aug.md`: the folder's public surface. |
 | An installed dependency | A versioned explanation and source copy under `.aug-spec/`. |
 
-Successful `build`, `run`, and `bench` commands refresh these documents after native compilation. `aug pack` refreshes them before creating the source archive. `--check` writes nothing and exits with a failure if a document, dependency copy, or manifest is missing or stale. Use it in CI after `aug check`.
+After a source change, run `aug check .` and `aug test .`, regenerate with `aug spec .`, and review the source and spec diffs together. Use `aug spec . --check` in CI to detect drift without writing files. It fails if a document, source pointer, dependency copy, or manifest is missing or stale.
+
+Successful `build`, `run`, and `bench` commands also refresh specs after native compilation. `aug pack` refreshes them before creating the source archive. [Change an unfamiliar module](guides/change-a-module.md) walks through this workflow.
+
+Generation also adds one managed comment at the top of each project source file:
+
+```text
+// aug-spec: "orders.aug.md" explains this file. Read it before changes; refresh with aug spec.
+```
+
+This points readers and coding agents to the explanation before they edit the code. The compiler keeps the pointer current after a rename and preserves handwritten comments. It does not edit installed dependencies. Native builds add the pointer after checking and before C emission, so source maps use the correct lines. `aug spec --check` reports missing or outdated pointers without adding them.
 
 ## What the document explains
 
-The compiler describes labeled inputs, injected dependencies, return values, state changes, capabilities, and checked failures. It follows each local branch, loop, match, recovery path, and cleanup block. It includes private helpers and same-file tests. For endpoints, it describes routes, wire inputs, policies, middleware ordering, and configured HTTP behavior.
+Read a spec as a developer's explanation of the file. Each declaration has a short introduction and ordinary paragraphs about its behavior. The text explains inputs, dependencies, decisions, changes, results, and failures. It includes private helpers and same-file tests. Endpoint explanations include their routes, request inputs, policies, and HTTP outcomes.
 
 For example, this complete program uses two source files:
 
@@ -30,25 +40,29 @@ print(value=total(price=7, quantity=3))
 ```
 
 ```aug project=spec-guide file=prices.aug
-total(int price, int quantity) returns int:
+total(int price, int quantity):
     if quantity > 0:
         return price * quantity
     return 0
 ```
 
-Without any comments, the generated spec lists `total` near the top of the file, explains its two labeled inputs and `int` result, and then describes its behavior:
+Without any author comments, the generated explanation reads:
 
-> - If `quantity` is greater than `0`:
->   - Return `price` times `quantity`.
-> - Return `0`.
+> It takes `price` and `quantity` as integers. It returns `price` times `quantity` if `quantity` is positive, or `0` otherwise.
 
-The generated document preserves the actual branch structure and links to the full explanation of each used dependency. Javadoc, when present, appears after the generated behavior as **Author documentation**. It can explain intent that a compiler cannot infer, but readers do not need comments to follow the checked inputs, operations, and outcomes.
+Related work is explained together. Validation describes the requirements and what happens at the first failed check. HTTP results describe responses. Collection updates describe the values added or stored. Decisions, repeated effects, recovery, and cleanup remain part of the explanation.
 
-Optional contracts use `optional Type`. Specs describe two possible states: a value or null. Omitted inputs become null, so missing and explicit null follow the same branch. If an older program handles missing and null differently, combine those cases deliberately before using the syntax migration command.
+For a list of literal records, the spec names the fields once and gives the rows in their original order. Calls with computed inputs keep their individual explanations, so the shorter description does not hide work or dependencies.
+
+String construction appears as readable text such as `Hello, {name}!`. Braces mark inserted values; doubled braces represent literal braces. Parentheses preserve expression grouping when it changes the meaning. These are conventions in the explanation, not new August source syntax.
+
+Javadoc, when present, becomes part of the explanation: its summary introduces the declaration, parameter notes sit beside their inputs, and return and error notes sit beside those outcomes. Comments can explain intent that a compiler cannot infer, but readers do not need them to follow the checked inputs, operations, and outcomes.
+
+Optional contracts describe a value or null. Omitted inputs become null too. The [language reference](reference.md#null-matching-and-checked-failures) gives the matching and narrowing rules.
 
 ## Dependencies stay small and navigable
 
-Each file starts with a short map of its declarations and startup steps, then explains local behavior. A compact dependency section follows it. Each used operation shows its inputs, result, injected values, changes, capabilities, and failures, with a link to the complete explanation. Dependency implementation bodies belong in their own documents.
+The document follows the file's declarations and startup work. A short dependency section names only the types, operations, and fields used here, grouped by module. Their links lead to complete explanations. It does not repeat dependency signatures or implementation bodies. Built-in contracts link to the language reference.
 
 `import everything` stays valid. The spec lists the names and operations actually used by the file. Adding an unused export does not expand that list. VS Code hover still shows all names available from the import.
 
@@ -79,7 +93,9 @@ In VS Code, use **AugScript: Open Compiled Specification** to generate and previ
 
 ## Determinism and limits
 
-Generation is offline and deterministic for the same checked sources, configuration, installed dependency versions, and compiler version. It adds no timestamps or machine paths. It uses fixed templates and the compiler's semantic information.
+Generation is offline and deterministic for the same checked sources, configuration, installed dependencies, and compiler version. It adds no timestamps or machine paths. Explanations include inferred result types, mutations, dependencies, and escaping errors even when their clauses are absent from source. Explanations use checked contracts; the writer does not guess what an arbitrary function does from its name.
+
+The spec describes the checked program; it is not a proof that the implementation meets your domain's requirements. Review the explanation for clarity and intent, and use tests for behavior. [Research and implementation notes](research/code-to-natural-language.md) explain the generation approach and its evaluation limits.
 
 ASD-STE100 guides the wording. The output is best effort Simplified Technical English, without a claim of formal compliance. Native C boundaries are explained through their declared contracts and author documentation; the compiler does not infer a foreign implementation's internals. Shared numeric, ownership, and task rules link to the language reference.
 

package/docs/testing.md

@@ -1,23 +1,31 @@
 # Built-in unit tests
 
-Tests live in the same file as the declaration they describe. Class suites use `test ClassName subject`; function suites use `test functionName`. Tests are excluded from production executables, and no test package is required.
+Keep a behavior test in the same file as the declaration it checks. A reader can inspect the contract, implementation, and cases together. August's CLI runs these tests as native programs; you do not need a test package, and test bodies are excluded from production executables.
 
-Endpoint suites use `test endpoint endpointName client`. HttpTestClient enters the native routing and policy pipeline with explicit method, relative path, headers and optional Bytes body. Group bindings supply fresh test dependencies; production startup is excluded. See the [complete service and endpoint cases](web.md#endpoint-tests). Live sockets, TLS negotiation and disconnect behavior require transport tests separately.
+Use `test functionName` for a function or `test ClassName subject` for a class. This guide gives complete examples, then covers setup, filtering, and coverage. If testing is new to you in August, work through [State and tests](learn/state-and-tests.md) first. For HTTP, use [endpoint tests](web.md#endpoint-tests); they exercise routing and policies, while live sockets and TLS need separate transport tests.
 
 ## A complete function suite
 
+Save these three files in one folder. `aug run .` prints `3`; `aug test .` runs four cases. Three come from the input rows, and one calls the reusable fixture.
+
+**main.aug**
+
 ```aug project=testing-guide file=main.aug
 import add from math
 
 print(value=add(left=1, right=2))
 ```
 
+**fixtures.aug**
+
 ```aug project=testing-guide file=fixtures.aug
 /** A reusable, pure test input. */
 fixture seven() returns int:
     return 7
 ```
 
+**math.aug**
+
 ```aug project=testing-guide file=math.aug
 import seven from fixtures
 
@@ -39,10 +47,14 @@ test add:
             assert(add(left=seven(), right=0) == 7)
 ```
 
-Each tuple row becomes a separately listed and executed case. Row arity and types are checked. The row variables are local to that case. Fixtures are ordinary checked functions marked `fixture`; import them explicitly and declare any dependencies/effects. They create no implicit fixture scope and remain callable as ordinary functions.
+Each tuple row becomes a separately listed and executed case. The checker verifies its arity and types, and the row variables belong to that case. `fixture seven` is a reusable checked function. Import fixtures explicitly and declare their dependencies and effects, as you would for other functions. They remain callable outside tests and create no implicit setup scope.
 
 ## A complete class suite
 
+In a separate folder, save these two files. `aug run .` prints `1`, and `aug test .` runs two cases. Notice that the second case sees the initial counter value even though the first case increments its own subject.
+
+**main.aug**
+
 ```aug project=class-testing-guide file=main.aug
 import Counter from counter
 
@@ -50,6 +62,8 @@ counter = Counter(initial=1)
 print(value=counter.value())
 ```
 
+**counter.aug**
+
 ```aug project=class-testing-guide file=counter.aug
 interface Count:
     increment() changes self
@@ -72,7 +86,7 @@ test Counter counter:
             assert(counter.value() == 3)
 ```
 
-The subject header identifies a local class and the variable used to test it. It does not invoke the constructor; initialize that subject in setup or the case. Generic classes use concrete type arguments. Tests follow ordinary member privacy and cannot access private fields merely because they share the file.
+The subject header names a local class and its test variable. It does not construct the subject; setup does that here. Each case gets a new counter. Tests follow ordinary privacy rules, so sharing the source file does not grant access to `_count`. Test generic classes with concrete type arguments.
 
 ## Groups, setup, and dependencies
 
@@ -92,7 +106,7 @@ An uncaught checked error, a native crash, a nonzero exit, or a timeout fails th
 
 ## CLI and coverage
 
-Use `aug` when installed, or `node bin/aug.mjs` from this repository.
+Use `npx @greenpandastudios/aug-cli@next` in place of `aug` below, or use an installed `aug` command. See [Your first project](getting-started.md) for the npm workflow.
 
 | Command | Action |
 | --- | --- |